[RaghwendraSingh]

Issue for this PR

Closes #1642

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

task threw on background: true without checking OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS. The flag only decided whether the registry kept background in the task schema, and the task tool's JSON schema had already removed it, so the field was never offered and the behaviour never ran. The parent always waited for the whole subagent.

1. Launch and collect (tool/task.ts).

• With the flag on, background: true starts the child prompt without awaiting it and returns at once. Output: task_id: <child session id> plus "Task is running in the background. Its result is collected by calling task again with task_id=; it is cancelled if your turn ends before you collect it." Metadata: { sessionId, model, background: true }.
• A later task call from the same parent session that passes that task_id collects it. If the child is still running it waits; the result is the synchronous output (<task_result>…) with the first line task_id: <id> (background task: calling task with this task_id returns this same result). The collect does not send its prompt to the child.
• Every launched child keeps a record (its result, its error, or its partial findings when cancelled) for the life of the process, bounded to 100 records per parent session (oldest settled first). A second collect, parallel collects in one step, and a collect after an error all return the same recorded outcome; nothing re-prompts the child. A background child is therefore not resumable through its task_id; start a new task to continue the work.
• background: true with the task_id of a running child returns "still running" at once instead of blocking.
• A parent may have at most 4 running background children; a fifth launch fails with a tool error asking it to collect one first.
• A launch on an already-aborted signal fails, as the synchronous path does, instead of reporting a running task.

2. Cancellation is visible and keeps partial findings.

• The child is bound to the launching call's ctx.abort, a per-request AbortSignal.any over the loop generation's signal. Cancel, a hard run deadline and the loop's cleanup at the end of the turn abort the generation signal, so they cancel a running child. A soft run-budget interrupt aborts only the request it targets: it cancels a child launched in that request, not one launched in an earlier step (kept as is).
• A child cancelled before it was collected appends to the launch tool part: "Background task was cancelled at the end of the turn, before its result was collected. Its partial findings:" plus the recovered <task_result>, with metadata.interrupted: true. A later collect returns those partial findings with metadata.interrupted: true.
• A collect publishes the child's sessionId/messageID on its own tool part before it waits (after the loop has marked the part running), so cancelling or hitting the deadline while blocked on a collect recovers "Task interrupted. These are partial findings…" as the synchronous path does.

3. One flag source (tool/registry.ts). The registry decides the flag from RuntimeFlags and passes that decision to execution (extra.backgroundSubagents), so the schema gate and the execution gate cannot disagree. Without runtime flags (the imperative prompt path) both read the environment through the same Effect Config.boolean parser (true/yes/on/1/y; TRUE is false). As with the other experiments, OPENCODE_EXPERIMENTAL=true also enables it.

4. Tool contract. With the flag on, the registry publishes background and replaces the task.txt sentence "For background tasks, you will be notified automatically…" (no notification exists) with: collect by calling task again with the task_id; ending the turn cancels uncollected tasks; a background task_id always returns the recorded result. With the flag off, the schema, the description and the error text are unchanged.

Not in this PR: the BackgroundJob service, promotion of running foreground tasks, notifying the parent when a child finishes, and cancelling children on session removal. The "promotes a running foreground task" test stays skipped.

Merge note: #1632 edits the block this PR moves into run(); when it lands, keep emptyTaskStatus inside run() so a collected child gets it too.

How did you verify your code works?

New tests through the real prompt loop with a mock LLM (test/session/background-task-loop.test.ts, the trace-context-loop harness, parent and child on one mock server):

• the parent ends its turn without collecting: the launch part records the cancellation with the child's partial text; next turn's collect returns Task interrupted… + the partial text with interrupted: true, and the child gets no new prompt;
• two parallel collects in one step while the child runs, then a third collect in the next step: all three return the same CHILDRESULT, one child request;
• an errored child: two collects give the same outcome, one child request, no re-prompt;
• cancelling the parent while it is blocked on a collect: the collect part is completed with "Task interrupted. These are partial findings…" and the child's text (was error, "Tool execution aborted").

Unit tests: test/tool/task.test.ts (already-aborted launch fails and never prompts; background: true + running task_id returns at once; the cap; the flag parser matches RuntimeFlags for on/y/1/yes/true/TRUE/false/0/off), test/tool/registry.test.ts (flag-off description unchanged; flag-on description says collect + cancel and drops "notified automatically"; execution follows the registry's flag with the env unset).

All four loop tests, the registry description test and the registry execution-flag test fail on the previous head; the new task.test.ts cases need exports added here.

No-regression protocol (test/tool, test/session, test/agent, one after the other, same machine, on the merged branch before and after this change):

suite	before (merged head bde819ee9d)	after (806ff2b9f3)
test/tool	692 pass, 0 fail	699 pass, 0 fail
test/session	1262 pass, 0 fail	1266 pass, 0 fail
test/agent	176 pass, 0 fail	176 pass, 0 fail

(fail) list before: none. (fail) list after: none. The touched files (task.test.ts, registry.test.ts, background-task-loop.test.ts) passed 3 runs in a row. Typecheck clean; script/check-tracker-leaks.ts and analyze.ts --markers --strict pass.

Gateway run: one headless run on the real gateway with the flag on, on a local branch that stacks this PR with #1631, #1632, #1639 and #1641 (not this PR alone): #1643 (comment). It shows that the parent keeps working while a child runs. It does not show a cache saving: the worker ran for 0.7 minutes, well inside the cache lifetime.

Cost side effects

Adds no model calls or queries. With the flag on, the parent can keep working while a child runs. That saves cache only when the parent has other work to do and the child outlives the cache lifetime: a parent that collects straight away still blocks, and no run has measured the saving yet. Children cannot outlive the parent's turn, at most 4 run at once per parent, and records are capped at 100 per parent. Flag off: no change.

Screenshots / recordings

N/A

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR
• I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

• X
• Mastodon
• Reddit
• LinkedIn

[github-actions]

👋 This PR was automatically closed by our quality checks.

Common reasons:

• New GitHub account with limited contribution history
• PR description doesn't meet our guidelines
• Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

[RaghwendraSingh]

Gateway run: background subagent with the flag on

One headless run on the real gateway (model altimate-backend/altimate-default) with OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true, on a local branch that stacks this PR with #1631, #1632, #1639 and #1641, against a 240-model dbt project with the same whole-project task used in our earlier runs. 1M-token cap, one leg. Measured from the session database (parent session and its child session).

check	earlier runs on main (passes 5–8)	this run
task call with background: true	throws "Background subagents require …"	accepted at parent step 9; returned the task_id at once
parent requests while the worker ran	0 (parent blocked 79 min across 4 runs)	3 during the worker's 0.7-minute run
first parent request after the worker finished	full miss (5 of 5 post-wait requests, ~716K tokens)	cache_read 114,520, fresh 8,378
worker outcome	—	7 requests, wrote its deliverable (unused.md, 41K chars, 0 TODO), ended with finish: stop

The join is explicit (a second task call with the task_id), as described in the PR.

[sahrizvi]

Changes requested. The launch and join path works, and with the flag off nothing changes. But with the flag on, a child's result can be lost or silently replaced, so there are 3 open major findings, each reproduced. All findings are inline.

Major

1. If the parent ends its turn without joining, the child is silently killed, while task.txt:17 tells the model it will be notified.
2. A task_id call after the entry is gone re-prompts the child, and a killed child's result is replaced by a fresh answer with no interruption marker.
3. Cancelling while blocked on a join loses the partial findings the synchronous path keeps.

Minor (none blocks by itself)

• Two flag parsers disagree on on, y and TRUE.
• The signal comment and the soft-interrupt claim are inaccurate.
• There is no cap on background children.
• background: true with a running task_id blocks.
• A launch on an already-aborted signal reports success.
• The new tests don't exercise the real loop.

Verified

• Flag off: the registry's task schema and description have the same sha256 at base and head, and the error text is unchanged.
• New tests: the two new behaviour tests fail at base and pass at head.
• Suites: test/session, test/tool and test/agent, run one after the other on a quiet machine, gave head 2127 pass / 2 fail and base 2124 pass / 2 fail. The same 2 tests fail on both, so there are no head-only failures. Those runs used an install without native builds, so the DuckDB binding was missing; that is the error I saw at those failures.
• Guards: the tracker-leak check and the strict marker check both pass.

Everything else is in the PR comment.

[sahrizvi]

Major: if the parent ends its turn without joining, the child is silently killed, and the tool description tells the model the opposite.

With the flag on, task.txt:17 still says "For background tasks, you will be notified automatically when the result is ready." No notification exists, and this launch output doesn't say that ending the turn cancels the child. A model that follows task.txt ends its turn. The loop cleanup (session/prompt.ts:724) then aborts the signal and the child is cancelled. Nothing tells the parent or the user.

Reproduced through the real prompt loop with the mock LLM server. The parent replied "Started it. I will be notified when ready." and prompt() returned. The child session ended with MessageAbortedError, and its partial text was left unread in the database.

The same thing happens if compaction drops the id from the parent's context, because nothing lists running children (from reading the code, not run).

Suggested fix: gate the task.txt sentence on the flag and state the join requirement, add "finishing your turn cancels it" to this output, and have the parent loop surface unjoined children before it exits, by joining or reporting them.

[RaghwendraSingh]

Fixed in 806ff2b: the launch output and the flag-on task description now say the result is collected with task_id and is cancelled if the turn ends first, and an uncollected cancelled child appends its partial findings to the launch tool part (loop test: background-task-loop.test.ts).

[sahrizvi]

Major: once this entry is gone, a task_id call re-prompts the child instead of collecting its result, and a killed child's outcome is replaced by a fresh answer with no interruption marker.

The entry is deleted here on first join and at line 338 on abort. Later calls take the resume path and send the join's prompt to the child as new work. Reproduced in four cases:

• Child killed at end of turn: the next turn's collect call sent "collect the result" to the child and returned a normal <task_result> with the new answer. There was no interrupted flag, and the partial findings never surfaced.
• Second join after success: one more model call, returning a new answer.
• Errored child: the first join correctly fails, then the second join re-runs the child and returns a normal result.
• Two parallel joins in one step: the first gets the result, and the second prompts the still-running child (prompts seen: LAUNCH, JB).

The PR description says "the join then returns the partial findings". That only holds for a join already in flight when the abort fires. The launch output tells the model to collect with this same call, so it can't tell it has asked for new work.

Suggested fix: keep a record of launched children past abort and first join, evicted when the session ends. A task_id naming a cancelled child then returns interruptedTaskOutput(child, messageID) or an explicit "cancelled" result, and a repeat join returns the stored result. Resuming should then be something the model asks for explicitly, not a side effect of a collect call.

[RaghwendraSingh]

Fixed in 806ff2b: every child keeps a recorded outcome (result, error, or partial findings marked interrupted), so repeated, parallel, post-error and post-cancel collects return that outcome and never re-prompt; loop tests cover all four cases.

[sahrizvi]

Major: cancelling or hitting the hard deadline while blocked on a join loses the child's partial findings. The synchronous path keeps them.

interruptedToolPart (session/processor.ts:64) recovers partial findings only when the running tool part's metadata has sessionId and messageID. The synchronous path publishes them through ctx.metadata, but this join returns before that code.

Same scenario in both modes through the real loop, cancelling the parent while the child is mid-stream:

path	parent's task part
synchronous	completed, "Task interrupted. These are partial findings from before cancellation: PARTIALFINDING"
join	error, "Tool execution aborted", no findings

The test cancelled through SessionPrompt.cancel. A hard deadline aborts the same signal and goes through the same recovery code, but I didn't run that case separately.

Suggested fix: store messageID and model in the map entry and call await ctx.metadata({ title: params.description, metadata: { sessionId, messageID, model } }) before awaiting pending.result.

[RaghwendraSingh]

Fixed in 806ff2b: a collect publishes sessionId/messageID/model on its running tool part before waiting, so cancelling during a collect now gives completed with "Task interrupted. These are partial findings…" (loop test).

[sahrizvi]

Minor (does not block: edge input): two parsers decide this flag.

The schema gate uses RuntimeFlags (Effect Config.boolean, effect/runtime-flags.ts:12), and production always passes those flags (registry.ts:632). Execution uses this 1/true/yes list. Results from running both:

• =on and =y: the runtime flag is true, so background is offered, and then this check rejects the call, telling the user to set the flag they already set. That is the original bug on these values.
• =TRUE: the reverse. The field isn't offered, but a hand-sent call is accepted.

The fallback the description calls shared only runs when flags are absent. Suggested fix: read one source in both places.

[RaghwendraSingh]

Fixed in 806ff2b: the registry passes its RuntimeFlags decision to execution (extra.backgroundSubagents), and the env fallback uses the same Effect Config.boolean parser; a test pins on/y/1/yes/true/TRUE/false/0/off.

[sahrizvi]

Minor (does not block: documentation): this comment and the PR description misdescribe the signal.

For a model tool call, ctx.abort is options.abortSignal (session/prompt.ts:2837), which is a per-request AbortSignal.any (session/processor.ts:512), not the generation signal. The subtask path does use the generation signal, but it never passes background.

Cancel, hard deadline and end of loop all still reach the child, and the end-of-loop case is confirmed by test. A soft interrupt, however, only aborts the request it targets, so it reaches a child launched in that same request. A child launched in an earlier step should survive it (from reading the code, not run). The description's "a soft run-budget interrupt ... also cancels running background children" is therefore not generally true.

"Run" here also means one loop generation, not a whole CLI run. Please correct both texts and decide which soft-interrupt behaviour you want.

[RaghwendraSingh]

Fixed in 806ff2b: the comment and PR body now describe the per-request AbortSignal.any and say a soft interrupt reaches only children launched in that request; I kept that behaviour.

[sahrizvi]

Minor (does not block: flag-gated, safe in a follow-up): no cap on background children.

Launches accumulate across parent steps, each with its own concurrent provider stream, until the loop ends. Parallel calls in one step are already unbounded, but background children add up over the whole run. Suggested fix: a per-parent limit that returns a clear tool error.

[RaghwendraSingh]

Fixed in 806ff2b: at most 4 running background children per parent; a fifth launch fails with a tool error asking to collect one first.

[sahrizvi]

Minor (does not block: edge input): background: true with the task_id of a running child blocks.

This branch takes the call as a join before it looks at background, so the parent waits for the child. The field's description says "return immediately". Reproduced. Suggested fix: return the running status at once, or reject the combination.

[RaghwendraSingh]

Fixed in 806ff2b: background: true with a running task_id now returns "still running" at once.

[sahrizvi]

Minor (does not block: narrow window, a later join reports AbortError): launching on an already-aborted signal reports success.

run() rejects at throwIfAborted, but this path still returns "Task is running in the background" for a child that was never prompted. Reproduced. An abort listener added to an already-aborted signal doesn't fire (confirmed in Bun), so the entry at line 338 stays until a join. The synchronous path rejects in this case, and task.test.ts:754 covers it. Suggested fix: call ctx.abort.throwIfAborted() before detaching.

[RaghwendraSingh]

Fixed in 806ff2b: the launch calls ctx.abort.throwIfAborted() before detaching, so an aborted launch fails and never prompts the child.

[sahrizvi]

Minor (does not block: test-only, but the fixes above need these tests): the new tests don't reach the paths that break.

Both tests are real and run: they fail at base and pass at head. But they use a stub prompt and a plain AbortController, so these cases aren't covered:

• the real prompt loop and its per-request signal
• a parent that ends its turn without joining
• an errored child
• a second join or parallel joins
• a cancel during a join
• the task.txt wording

test/session/trace-context-loop.test.ts shows the loop-plus-mock-LLM setup. My probes used it and reproduced each major finding.

[RaghwendraSingh]

Fixed in 806ff2b: added test/session/background-task-loop.test.ts (real loop + mock LLM: end of turn without collect, parallel/repeated collects, errored child, cancel during collect) and registry tests for the flag-on/off description.

[sahrizvi]

Review notes that don't map to a diff line, plus nits. The formal review has the inline findings.

Sibling PRs

• fix(session): end at the step cap with a toolless answer, and report empty task results #1632 conflicts in tool/task.ts (git merge-tree): it edits the block this PR moves into run(). Keep emptyTaskStatus inside run() when resolving, so a joined child gets it too. Until fix(session): end at the step cap with a toolless answer, and report empty task results #1632 lands, a child that ends on an assistant error with no text should give an empty <task_result> at the join, the same as the synchronous path (from reading the code, not run). A child that throws does surface as a tool error at the join (reproduced).
• fix(session): keep the cached system prompt prefix stable across steps #1631, fix(session): compact once per overflow and list shell-written files in the ledger #1639, fix(session): run-mode nudge without a clarification stop, a blocked exit, and the completion contract for run-mode agents #1641 and fix(tool): apply external_directory: deny to every literal path a bash command names #1646 merge cleanly with this PR.

Proof and description

• The PR body still says "No gateway or real-model run", while the later comment reports one. Please update the body.
• That gateway run stacks fix(session): keep the cached system prompt prefix stable across steps #1631, fix(session): end at the step cap with a toolless answer, and report empty task results #1632, fix(session): compact once per overflow and list shell-written files in the ledger #1639 and fix(session): run-mode nudge without a clarification stop, a blocked exit, and the completion contract for run-mode agents #1641, so it doesn't test this PR alone.
• The worker ran for 0.7 minutes, well inside the 5-minute cache lifetime the PR is about, so a blocking call would probably also have hit the cache. The run shows that the parent isn't blocked. It doesn't show the cache saving.
• A parent that joins straight away still blocks and lets the cache cool on a long child. The saving depends on the parent having other work to do.
• "Reduces cost" needs a run with a child longer than the cache lifetime.

Scope of the flag

• OPENCODE_EXPERIMENTAL=true also turns this path on (confirmed by running it), so anyone on the general experiment flag gets the major findings without opting in to this feature.

Nits

• The run footer shows a running background child as completed, because the launch tool part has completed (cli/cmd/run/subagent-data.ts:298). From reading the code, not run.
• One subagent now produces two tool rows in telemetry. The launch is close to 0 ms and the join shows only the wait, so per-task duration dashboards need to allow for that.
• registry.ts:16 adds a second import from ./task.
• The delete listener at task.ts:338 isn't removed after a join and stays until the signal aborts. It is small and bounded by the number of children.

Checked, no defect

• An id from another session can't join (guard at task.ts:148) and gets a new child, as on base. A running sibling's result is not exposed.
• An errored child's join rethrows the real error. The .catch at task.ts:336 makes a separate promise, and the stored one still rejects.
• Join skipping ctx.ask is fine. The launch already asked for that child, the join starts no work, and the parent-session guard holds.
• Join ignoring subagent_type is fine. It returns the real child's result and id.
• Child tokens not counting toward the parent's totals isn't new: session/prompt.ts excludes them on the synchronous path too. I found no token or cost cap in run accounting. The time budget and query deadline do reach the child.
• using scopes in run() last until the child settles, so the abort listener and deadline stay in place (the new test checks the deadline).
• Run tracing links the join through input.task_id.
• The -351: the source side is the moved block plus the replaced throw. The test side is 7 background tests that were all .skip against the BackgroundJob design, so no running coverage was lost. The behaviour they described (session removal cancelling background tasks, notification, promotion) still isn't implemented or tested. Session removal doesn't cancel a running child today, on base or here.

[github-actions]

👋 This PR was automatically closed by our quality checks.

Common reasons:

• New GitHub account with limited contribution history
• PR description doesn't meet our guidelines
• Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

[RaghwendraSingh]

Addressed review in 806ff2b (after merging main): all 3 majors (no silent kill at end of turn: launch text and description say collect-or-cancel, plus a cancellation record on the launch part; a recorded outcome per child, so collects never re-prompt; collect publishes child identity so cancel keeps partial findings) and all 6 minors (one flag parser, signal comment, cap of 4, background + running task_id returns at once, aborted launch fails, real-loop tests). PR body updated: before/after suite lists (0 fails both) and the gateway-run link (stacked branch). Not changed: OPENCODE_EXPERIMENTAL=true still enables this, like the other experiments; telemetry/footer nits left as is.