fix(orchestration): Preserve Claude subagent attribution after settle

[mwolson]

Summary

• Persist Claude native-task and tool-use attribution across settled root turns
  and fresh buffered continuations.
• Keep child narration, tools, results, and distinct terminal output in child
  threads without changing ordinary root assistant text.
• Replace raw task summaries in provider-owned root continuations with a fixed
  generic Claude prompt, preserve other providers' requested detail, and hide
  automatic provider entries from queue controls.

Problem and Fix

Problem and Why it Happened	Fix
Claude child SDK frames can arrive after the root turn settles. The fresh continuation no longer has the launch turn's tool-use maps, so child text, tools, and results can leak into the root thread.	Keep task identity, launch and resume aliases, bounded registration-race buffering, and resume state together in native-thread-scoped session state. Every attributed child frame resolves through that durable state.
A boolean or one-result latch cannot distinguish streamed narration, an equivalent notification fallback, and a genuinely distinct terminal Agent result across resumes.	Track bounded native identities and normalized terminal equivalence per generation. Equivalent fallback text is suppressed, while distinct narration, summaries, and terminal results survive once.
task_notification.summary was used as the provider-owned Claude continuation input and could render as raw child text labelled as another agent's message. A shared override would also erase Codex background-command context.	Give Claude an explicit fixed root text, Background task completed., while preserving provider-specific continuation detail for Codex. Omit provider-owned automatic entries from visible queue controls.
Unknown attributed lineage must not silently become root output.	Buffer a fixed number of lineages and frames until task registration. Overflow is logged and dropped child-side, never projected into the root.
Multiple pending Agent launches cannot safely recover an omitted task_started.tool_use_id by arrival order.	Infer only a single unambiguous launch. Ambiguous siblings wait for an explicit SDK alias, which atomically binds the task, preserves launch identity, and drains its child buffer.
Agent launch results and child approval requests can arrive before task_started registers their alias. A structured agentId can also appear in ordinary root tool output.	Remember bounded launch identities, route known native task IDs directly, fail closed for unknown child-looking approvals, and prefer an existing root tool call before interpreting incidental agentId data.

Defensive Fixes

Problem and Why it Happened	Fix
A failed continuation dispatch without a buffered terminal result left a native-thread-wide drain marker. A later sibling completion on the same Claude session could be mistaken for stale output and failed.	Record the exact task IDs represented by the failed offer. Stale frames for those tasks fail closed, known sibling tasks clear the drain and continue normally, and native-process replacement clears the scoped state.
A sibling completion could append after dispatch failed but before failIfCurrent, where a live-buffer rescan pulled the sibling into the failed cohort.	Freeze the failed cohort at offer time and replay later frames through normal wake buffering, so appended siblings receive their own continuation and are never projected failed.
A declined or cancelled Agent approval remained in the per-turn launch-inference queue, making a later alias-free valid launch look ambiguous.	Remove only the rejected approval from pending per-turn inference while retaining its durable session launch identity.
Native query replacement, interrupt timeout, or session disposal could delete Claude's registry while durable child projections still said running.	Fail-close every still-running native child with one static session-ended artifact before deleting aliases or process state. Already-terminal children remain unchanged.
An unresolved Agent result inside a multi-result SDK frame buffered the whole frame and returned, so later sibling results could be delayed or replayed more than once.	Split buffered results into one-block messages and continue through the batch, preserving independent lineage even when aliases arrive in reverse order.
A split multi-result user frame could retain the original frame-level tool_use_result, then incorrectly apply that shared structured result when one buffered block replayed.	Remove frame-level structured output from split messages and derive each replayed result from its own content block.
The bounded pending Agent launch queue could evict an unresolved launch while leaving implicit alias inference enabled, allowing a later alias-free start to claim the final retained sibling alias.	Disable implicit launch-alias inference for the rest of the turn after overflow. Explicit SDK aliases remain authoritative and drain only their own child buffer.

Validation

• The final MCP, Claude adapter, provider continuation, replay, and
  client-runtime set passed 189 tests with 1 skipped.
• vp check: passed all 2,690 files.
• vp run typecheck: passed all 15 packages.
• A fresh isolated v2.1 Nightly AppImage built from the deliberate final union
  passed the exact packaged Grok post-settlement subagent, Claude
  post-settlement subagent, and Codex background-command wake scenarios. Claude
  projected one generic provider-owned root input while keeping raw child
  output on the child; Grok and Codex retained their provider-specific
  behavior.
• Codex GPT-5.6 Luna identified the incidental root agentId collision. The
  regression was fixed and covered. Fresh Grok 4.5 high-reasoning source and deliberate-integration reviews
  returned SHIP after verifying teardown ordering, exactly-once terminals,
  semaphore safety, independent batched-result lineage, and fail-closed pending-launch overflow.

---

Note

High Risk
Large refactor of Claude orchestration around turn settlement and continuation; missed attribution or generation checks could drop or mis-route subagent output silently.

Overview
Fixes Claude SDK child frames arriving after a root turn settles leaking narration, tools, and results into the parent thread when continuation turns no longer have launch-turn tool maps.

ClaudeAdapterV2 now tracks subagent identity, launch/resume aliases, bounded pre-registration buffers, and terminal deduplication in native-thread-scoped session state (with an SDK message semaphore). Attributed frames route to child threads; unknown lineage is buffered or dropped fail-closed instead of becoming root output. Continuation wakes use PROVIDER_CONTINUATION_MESSAGE_TEXT (Background task completed.) so raw task_notification summaries are not shown as another agent’s root message, while provider-specific detail is preserved for other adapters (e.g. Codex).

Related hardening covers ambiguous multi-launch inference, failed continuation drain cohorts, session teardown of still-running children, split multi-result SDK frames, and pending launch queue overflow. The web queue UI omits provider-owned automatic completion deliveries (e.g. delegatedCompletion / matching continuation text).

^{Reviewed by Cursor Bugbot for commit a593d5c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Preserve Claude subagent attribution and route approvals correctly after turn settlement

• Rewrites subagent state tracking in ClaudeAdapterV2 to be scoped per native thread rather than per turn, preventing attribution loss after settlement.
• Serializes SDK message handling under a semaphore to avoid races between concurrent wake frames, subagent launches, and continuation requests.
• Buffers SDK frames attributed to unresolved agent launches by parent_tool_use_id, replaying them once the taskId↔toolUseId alias is established.
• Routes tool approval requests to the correct subagent lineage using callbackOptions.agentID; denies approvals that cannot be resolved rather than proceeding incorrectly.
• Hides provider-buffered "Background task completed." continuation messages from the visible thread queue in deriveThreadQueueWorkflowState.
• Risk: SDK message processing is now serialized via a semaphore, which changes concurrency behavior in the adapter and may affect throughput under high message rates.

^{Macroscope summarized a593d5c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 038a7b6b-4ae8-4844-a7fe-90998fe714f4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Effect Service Conventions review: one convention issue found in the newly added test module's service imports. Everything else in the changed Effect code (subpath namespace imports, layer construction, dependency acquisition via yield* Service, error modeling) matches the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[macroscopeapp]

Approvability

Verdict: Needs human review

Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

[macroscopeapp]

Reviewed the changed Effect service code against the service conventions. One import-shape issue in the new server test; everything else (namespace imports from effect/* subpaths, Context.Service shapes, error modelling, and dependency acquisition in the touched orchestration/adapter code) looks consistent with the conventions.

^{Posted via Macroscope — Effect Service Conventions}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 48f545d. Configure here.}