Repository navigation
fix: split Claude Code subagent sessions so they stop queueing on the main session lock (#970) - #975
Conversation
[bot] 🏷 Reviewing this PR now. Initial notes before the deep dive:
|
… main session lock (ranxianglei#970) Claude Code stamps the same x-claude-code-session-id on every model request of a session — Task-tool subagents included — so main turn and all subagents land on ONE session and serialize on withSessionLock (which spans prepare + forward + the whole streamed response). A slow subagent first token head-of-line-blocks the main turn for the full upstream latency; observed live as 116-142s first-byte stalls with two concurrent subagents. Discrimination is two-signal, verified against live Claude Code 2.1.274 traffic (-p mode AND custom agent types like Explore): the request carries the agent headers, AND the main agent's system-prefix block ("You are Claude Code…" / "You are an interactive agent…") is absent — subagent systems are their own agent definitions with no stable positive marker. Both signals must agree; failure degrades to no-split (today's serial behavior), never mis-splits the main session. - src/session-id.ts: claudeSubagentAgentId / claudeSubagentSplit - src/server.ts: anthropic conversation branch derives <id>|sub:<agent-id>; anthropicIdentity itself untouched (affinity/clientLabel stay continuous); split sessions can't claim the root's pending register (ranxianglei#317 mirror); recordPluginSession keys subagent sessions under the split id so the conversations map never flips between main and subagent sessions - src/config.ts: BILI_SUBAGENT_SPLIT env gate (default on) - tests: discrimination cases across captured system shapes, session isolation, deterministic no-stall (gated upstream), off-switch - docs: CHANGELOG + CONFIGURATION (en/zh) End-to-end verified: two concurrent Task subagents through the proxy land on |sub: sessions and complete in parallel (20.6s vs 129-188s pre-fix). Co-Authored-By: Claude Code <noreply@anthropic.com>
eff29e1 to
370ee63
Compare
[bot] 🏷 Review progress — I rebased the branch to current master (it was 7 commits behind; rebase was conflict-free) and pushed one small fix directly onto the PR branch so the diff stays reviewable in place. New head: What I changed (commit Local verification on the rebased head: typecheck clean, build green, full suite 1914/1916 pass, 0 failures (the 3 environmental failures you saw didn't reproduce here; 2 skips are the usual gated ones). CI is re-running on the new head — I'll confirm once it's green before the final verdict. 中文小结:已把分支 rebase 到最新 master,并直接在 PR 分支上补了一个小修复( |
[bot] 🏷 Review complete — ready for you to merge (merge stays human-only; this touches session-identity logic, which our auto-merge gate keeps out of agent hands). 中文小结:修复了 Claude Code subagent 与主会话共用一个 session、被 Duplicate screeningRelated open PR #972 fixes the same issue #970 with a different mechanism (shrinking What I audited (beyond running tests)
Verification
Fix I pushed directly (commit
|
…ane (#4352) Claude Code builds that stamp no agent-id headers (VS Code extension) send subagent model requests under the parent session id. Their short, unrelated histories ride the parent session and destroy its fold substrate: fold-reconcile sees covered ids missing, confirms epoch destruction, and the model's compress calls die as substrate-destruction with refs recorded DEAD. The #975 two-signal gate cannot see these subagents: VS Code builds share the parent's first system block verbatim, so the main-prefix negative check fails even when the agent-id headers are present. Route claude anthropic-wire traffic (x-claude-code-session-id source, evidence allowlist in the lane-decisions registry) through the continuity-aware order resolver when the #975 gate misses: a continuing main conversation keeps the raw id on order+content evidence; a history-disjoint ride forks onto its own |sub:<fp> lane (own lock chain, own compression state); a byte-drifted system on continuing history still keeps the raw id (#1106). Gated by the existing subagentSplit knob (no new config surface); side calls and empty-system requests stay verbatim. Docs: CONFIGURATION.md/.zh-CN.md subagentSplit rows describe both paths. Tests: tests/issue4352-claude-anthropic-subagent-split.test.ts — both gate directions plus the live VS Code field shape captured in the issue comment.
…ane (#4352) Claude Code builds that stamp no agent-id headers (VS Code extension) send subagent model requests under the parent session id. Their short, unrelated histories ride the parent session and destroy its fold substrate: fold-reconcile sees covered ids missing, confirms epoch destruction, and the model's compress calls die as substrate-destruction with refs recorded DEAD. The #975 two-signal gate cannot see these subagents: VS Code builds share the parent's first system block verbatim, so the main-prefix negative check fails even when the agent-id headers are present. Route claude anthropic-wire traffic (x-claude-code-session-id source, evidence allowlist in the lane-decisions registry) through the continuity-aware order resolver when the #975 gate misses: a continuing main conversation keeps the raw id on order+content evidence; a history-disjoint ride forks onto its own |sub:<fp> lane (own lock chain, own compression state); a byte-drifted system on continuing history still keeps the raw id (#1106). Gated by the existing subagentSplit knob (no new config surface); side calls and empty-system requests stay verbatim. Docs: CONFIGURATION.md/.zh-CN.md subagentSplit rows describe both paths. Tests: tests/issue4352-claude-anthropic-subagent-split.test.ts — both gate directions plus the live VS Code field shape captured in the issue comment.
…ane (ranxianglei#4352) Claude Code builds that stamp no agent-id headers (VS Code extension) send subagent model requests under the parent session id. Their short, unrelated histories ride the parent session and destroy its fold substrate: fold-reconcile sees covered ids missing, confirms epoch destruction, and the model's compress calls die as substrate-destruction with refs recorded DEAD. The ranxianglei#975 two-signal gate cannot see these subagents: VS Code builds share the parent's first system block verbatim, so the main-prefix negative check fails even when the agent-id headers are present. Route claude anthropic-wire traffic (x-claude-code-session-id source, evidence allowlist in the lane-decisions registry) through the continuity-aware order resolver when the ranxianglei#975 gate misses: a continuing main conversation keeps the raw id on order+content evidence; a history-disjoint ride forks onto its own |sub:<fp> lane (own lock chain, own compression state); a byte-drifted system on continuing history still keeps the raw id (ranxianglei#1106). Gated by the existing subagentSplit knob (no new config surface); side calls and empty-system requests stay verbatim. Re-applies the fix from unmerged PR ranxianglei#4409 (closed by a stale-ticket bot that misattributed the closure to ranxianglei#4337, which does not touch this path) onto current master. Closes ranxianglei#4769 (re-report of ranxianglei#4352). Tests: tests/issue4352-claude-anthropic-subagent-split.test.ts — both gate directions plus the live VS Code field shape captured in the issue comment. Docs: CONFIGURATION.md/.zh-CN.md subagentSplit rows describe both paths.
What
Fixes #970 — Claude Code subagent requests no longer queue behind the main turn's session lock.
Claude Code stamps the same
x-claude-code-session-idon every model request of a session — Task-tool subagents included — so main turn and all subagents land on ONE session and serialize onwithSessionLock(which spans prepare + forward + the whole streamed response). A slow subagent first token head-of-line-blocks the main turn for the full upstream latency; observed live as 116-142s first-byte stalls with two concurrent subagents.How
Two-signal discrimination, both verified against live Claude Code 2.1.274 traffic (
-pmode AND custom agent types like Explore):x-claude-code-agent-idand/orx-claude-code-parent-agent-id. The parent header alone is NOT reliable —-pgeneral-purpose subagents send it, custom agent types (Explore) do not, and main turns carry agent-id only from their second request on.You are Claude Code…(interactive) orYou are an interactive agent…(-p/SDK). Subagent systems are their agent definitions (This session is a background job…,You are a file search specialist for…) — no stable positive marker exists across types, so the check is negative: no main prefix may match.Both signals must agree. Failure degrades in the safe direction: a future rewording of Claude Code's main prompts only stops the split (back to serial), never mis-splits the main session.
The anthropic identity branch derives
<id>|sub:<agent-id>(mirroring the codex #316 / ResponsessubagentNamespaceprecedents).anthropicIdentityitself is NOT rewritten —affinityToken/clientLabelkeep the raw value, so upstream prefix caches and the UI label stay continuous. Two guards keep the plugin layer honest: a split session's first request can't claim the root's pending register (#317 mirror), andrecordPluginSessionkeys subagent sessions under the split id so the single-valued conversations map never flips between main and subagent sessions (last-writer-wins bug that would break/acplookups and MCP tool routing).Verification
master(environmental,git stashbaseline verified)|sub:sessions in the log and complete in parallel (20.6s vs 129-188s pre-fix)Opt-out
BILI_SUBAGENT_SPLIT=0restores single-session behavior (covered by a test).🤖 Generated with Claude Code