[Bug]: Nested Claude subagent stays Running after the SDK reports it completed during a user turn#16355

Triage

Thanks for the detailed timeline, @coygeek! It matches the Claude adapter on current main (3a9c1a6d). This is a real stuck status, separate from #14641, #14665, #16261, and #14802.

What I found

A nested task_started that arrives while the root is idle is kept in the wake buffer and doesn't start a continuation. A user turn then leaves that buffer alone (startTurn, if (userMessage !== null)). The completion is only handled on the live turn, where it gets dropped:

• updateClaudeSubagentNode returns immediately when the task isn't registered and the status isn't running (ClaudeAdapterV2.ts, around line 4122). The subagent exists only as a buffered task_started, so the completed task_notification never lands, and nothing is logged.
• task_updated isn't a lifecycle signal here, and task_progress while idle isn't wake evidence, so the 01:20:36 progress frame couldn't create the card before the user turn.
• The next continuation drain replays the held task_started and creates the subagent as running, with started_at set to drain time. The completion isn't in the buffer, so nothing afterward writes completed_at.
• A run that finishes completed doesn't close its open subagents: cascadeTerminalizeRunOwnedSubagents only runs for interrupted, failed, or cancelled. Startup recovery in ProviderRuntimeRecoveryService is the only later sweep, and it marks the row cancelled.

That lines up with the 01:17:05 start, the 01:21:16 completion during run 36, and the card created as running at 01:24:51 on run 37. Lineage reads subagent.status, and the composer banner comes from the still-running subagent turn item in derivePendingBackgroundWork, so both stay on "Running" / "Waiting on subagent …" after the provider thread is idle.

When both frames are buffered while idle, the next drain creates the card and then completes it (the #14641 path), so your two controls hold. The gap is the user turn in between, which consumes the completion and keeps the start.

The same drain can also undo a completion that did land. If a task_progress during the user turn creates the card and the notification then completes it, the held task_started is still replayed later with reopen: true, which reopens the terminal subagent (the SendMessage resume rule) and leaves it running again.

Likely fix area

One option is to keep the terminal task_notification alongside the held task_started instead of dropping it, e.g. appending it to the wake buffer without offering a continuation, so the next drain replays start and then completion, consistent with the nested-subagent handling from #14641.

Details that may matter with that approach:

• A terminal notification for a task with no buffered task_started and no registered subagent (a stray id) could still be ignored as today.
• Replaying the original held task_started shouldn't reopen a subagent the turn already completed. Reopen could stay limited to a new task_started (a different tool_use_id), or the held start could be dropped once a terminal status is applied.
• The idle cases should keep working: start and completion both while idle still settle on the next drain, and a subagent that's really still running stays running until its real completion.

Restarting the server should clear the banner as a workaround, though the subagent ends up cancelled rather than completed.

A maintainer will decide on the fix direction.

Fresh occurrence on the v0.1.0 release (the current Latest, not a nightly), through a second path with the same root cause: a nested subagent's task_started stays held in the wake buffer, and only a continuation run drains that buffer. Here the completions were not dropped. They sat in the wake buffer and nothing applied them for 2 h 21 m to 2 h 27 m, because every run that followed carried a message. This bears directly on the fix direction proposed above: appending the terminal task_notification to the wake buffer without offering a continuation is exactly the state these four subagents were stuck in.

What happened

A background subagent P (spawn_depth: 1) launched five foreground forks C1 to C5 (spawn_depth: 2, parent_task_id = P) while the root was idle. C5 finished during a live run and settled on time. C1 to C4 finished while the root was idle and stayed Running through every later run (six or seven each) until run 48. At 03:43 the Lineage panel read "Lineage · 7 running" and listed C1 to C4 as Running for 31 m, each labelled with the thread's own title instead of its description. Stop on three of them did nothing. They settled only after the root started a background Bash command for that purpose (a 60 s sleep) and it finished while the root was idle, which started the first wake continuation. An earlier 45 s attempt finished during a live run and changed nothing.

Timeline (UTC, 2026-10-17; one server process throughout, one provider session, no restart, no session replacement):

Provider event log, lifecycle frames (trimmed):

Where it sticks, on main (73af7122)

In apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts unless noted:

1. While the root is idle, a nested completion is buffered but cannot be applied while that task's own task_started is still held: canApplyOutcome requires !hasBufferedStart (L6552-L6564). It also never offers a continuation, because a nested end "never wakes the root" (L3527-L3528, L6091-L6098, L6216-L6222).
2. Only a continuation run drains the wake buffer. A run that carries a message returns before the drain (L8367-L8372), and that includes every delegate_task result delivery, not only user prompts. In a thread that delegates, most runs are of this kind, so the next drain can be hours away.
3. The owner's own completion, which normally brings that wake (as the trace posted in #19993 today notes), does not help when it lands during a live run, as P's did at 03:41:02.
4. Stop cannot repair the row. stopSubagent sends stop_task and waits 2 s for a new native outcome (L8903-L8914). The SDK finished the task long before, so no outcome comes, and the completion T3 already holds in its own wake buffer is never consulted.
5. Nothing else closes the row while the server runs. A completed run does not terminalize subagents it still owns (isRunOwnedSubagentTerminalStatus in RunExecutionService.ts, L163-L167), and ProviderRuntimeRecoveryService sweeps only at startup and shutdown, where it records the real completed as cancelled.

The v0.1.0 tag (81493efb) has the same logic (L3685, L6914-L6928, L8830, L9406-L9416).

Request

Please re-assess the P2 "minor" rating and fix this at the level of the invariant:

• It ships in v0.1.0, the Latest release.
• Ordinary orchestration triggers it: 4 of the 5 nested subagents in a single fan-out, in a thread that uses T3's own delegate_task.
• It misleads everything that reads subagent state. Here that was Lineage. The waiting banner and T3's own task_status read the same stale state: once a delegated task's own runs have finished, task_status can report it as waiting_for_children while any subagent in its child thread still shows Running (#17154 is that failure through another trigger).
• There is no clean way out. It takes a wake of the root that has nothing to do with these subagents (luck, or a background command started only to cause one, which works only if it finishes while the root is idle) or a restart, and a restart records finished work as cancelled.

The same stale-Running end state has now been reported through nine different triggers: #16355, #17154, #17512, #17847, #18877, #18910, #19440, #19612 and #19993. Each fix so far closed one trigger, and the end state keeps returning through another. What is needed is that a subagent's real outcome cannot be lost or parked:

1. Apply a terminal outcome as soon as it arrives, whatever the root is doing. If the task's task_started is still held, replay that start first and then the outcome. No subagent should depend on an unrelated wake to settle. The fix offered in #19993 today (apply the buffered start and the outcome immediately in the idle branch, with a failing test) is this item for the nested case, and it would have settled C1 to C4 at 03:17 to 03:23. Please give that direction a go-ahead.
2. Give every run start the drain, including user prompts and delegate_task deliveries, at least for subagent lifecycle frames.
3. Make Stop reconcile: settle from an outcome T3 already holds before waiting for a new one, and settle the row when the provider no longer lists the task as running. Here stop_task was accepted silently and no outcome followed.
4. Settle foreground (is_backgrounded: false) descendants when their owner completes, since a foreground subagent cannot outlive the subagent waiting on it. Attach nested cards by parent_task_id, not to whichever run happens to be live. The 03:47 control shows this already works when the start arrives during a live run.
5. Reconcile while the server runs, for example by checking open subagent rows against the provider's task state after each run settles, so that one missed frame cannot leave a permanent Running.
6. Add a regression test for this exact sequence: nested starts while the root is idle, a message-carrying run, nested completions while idle, then only message-carrying runs. All four subagents must end completed without a wake continuation.

Until this is fixed we have set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 on this machine, which turns nested subagents off entirely. Without a restart, a stuck row clears only on the next wake continuation. Here we forced one by having the root start a short background command that finished while the root was idle; a first attempt that finished during a live run did nothing.

Environment

T3 Code v0.1.0 desktop (tag v0.1.0, 81493efb71e8), macOS 26.2 (25C56), Apple silicon. Orchestrator v2 store, Claude provider through claude-agent-sdk, Claude Code CLI 2.1.302, claude-opus-5-5. The evidence comes from this machine's provider event log, server.trace.ndjson (the 15 stopSubagent failures) and read-only queries of statev2.sqlite. I can share trimmed extracts or the projection rows if useful.

A depth-1 case with no nested subagent, on 2026-10-19, on 0.0.46-nightly.20261013.3040:

1. 03:15:48Z: the root agent launches one background subagent. T3 writes a record for it in orchestration_v2_projection_subagents (origin: provider_native, status: running).
2. 03:15:52Z: the root turn ends.
3. 03:17:09Z: the SDK emits task_notification with status completed for that subagent. T3 starts a new run from it, and the root agent reads the result.
4. The subagent's status stays running while three more runs complete on the thread.
5. 18:56:48Z: T3 sets its status to cancelled. In the same second, T3 also cancelled the subagent records of two other threads and this thread's open run.

The subagent's record read running for 15 h 39 m after its completion notification.

Still present in the source on v0.1.1 (fe27e8e3) and main (96bae546). If a nested task's start is held while idle, a message-carrying turn still skips the wake-buffer drain, and its live completion is ignored when the task is not yet registered. The next continuation can therefore replay only the start and leave it Running. #18778 protects already-registered tasks but does not cover this original ordering. #20835 is still open, and #19993 was consolidated here as a duplicate, so I'm keeping this open. This is a source and test-coverage check; I did not run a fresh UI/Claude reproduction.

Still reproduces on v0.1.2 (Linux x64, Claude provider, Opus root thread). The trigger matches #19993, the parent hitting its usage limit:

1. The root thread started one background native subagent with the Agent tool (run_in_background: true). That subagent ran several nested native subagents in parallel (spawn depth 2).
2. Mid-run, the account hit its Claude session limit. The depth-1 subagent ended with Agent terminated early due to an API error ... rate_limit, HTTP 429.
3. After the reset, the root resumed it with SendMessage. It started new nested subagents, which finished, and it then reported completed.

Result, hours later:

• Lineage still shows 5 entries as Running, all titled with the root thread's title.
• t3_thread_list with includeSubagents: true lists no running children.
• ps shows no Claude process for them; the only one left belongs to the root thread.
• Their work stopped writing output at the moment of the 429.

So the stale entries survive both the parent's error exit and its later resume and completion. Nothing reconciles them while the server keeps running.

Another occurrence, on Windows. The stuck subagent was stopped by the user, not completed.

Environment

• T3 Code: 0.1.0 (release channel)
• OS: Windows 11 Pro (10.0.26200)
• Provider: Claude (Claude Code SDK 2.1.308), root model Opus 5.5

What happened

1. The root thread launched a background native subagent with the Agent tool (run_in_background: true, spawn depth 1): "Cost 99.5/99.9/99.95% availability tiers".
2. That subagent launched a foreground nested subagent (spawn depth 2, is_backgrounded: false): "Fetch Microsoft SLA terms". It started at 2026-10-25T23:54:12Z.
3. The nested subagent was stopped at 2026-10-25T23:56:43Z. Claude's subagent metadata records "finished": true, "stoppedByUser": true.
4. The parent subagent kept running and finished normally at 2026-10-26T00:27:24Z. The root thread has since completed many turns and launched more background subagents, all of which completed and reconciled normally.

Result

• The thread's Lineage panel still shows "Fetch Microsoft SLA terms" as running, with a timer past 6 hours.
• The thread status is stuck on "waiting Xm".
• From the root agent, TaskStop on both the nested ID and the parent ID returns "No task found", so nothing is running on the provider side.
• The stale entry has persisted through many later runs; nothing reconciles it.

Difference from the original report Here the nested task ended by a user stop, not by a completion during a user turn. So the stop or cancel path for a depth-2 task may also skip reconciliation. Our workaround was moving to a new thread.