Skip to content

fix: split Claude Code subagent sessions so they stop queueing on the main session lock (#970) - #975

Merged
ranxianglei merged 2 commits into
ranxianglei:masterfrom
elevenfund:2026-09-19_subagent-split
Sep 19, 2026
Merged

ranxianglei merged 2 commits into
ranxianglei:masterfrom
elevenfund:2026-09-19_subagent-split

Conversation

@elevenfund

Copy link
Copy Markdown
Contributor

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-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.

How

Two-signal discrimination, both verified against live Claude Code 2.1.274 traffic (-p mode AND custom agent types like Explore):

  1. Header: request carries x-claude-code-agent-id and/or x-claude-code-parent-agent-id. The parent header alone is NOT reliable — -p general-purpose subagents send it, custom agent types (Explore) do not, and main turns carry agent-id only from their second request on.
  2. System: the MAIN agent's system always has a block starting with You are Claude Code… (interactive) or You 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 / Responses subagentNamespace precedents). anthropicIdentity itself is NOT rewritten — affinityToken/clientLabel keep 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), and recordPluginSession keys 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 /acp lookups and MCP tool routing).

Verification

  • New tests: 5/5 (two-signal discrimination across captured system shapes, stable namespaces, session isolation with main-identity stability, deterministic no-stall, off-switch)
  • Negative control: with the split off, the subagent's first byte arrives at 1238ms gated behind the main stream — proving the no-stall assertion bites
  • Regression ring: 57/57 (session-id, codex-turn-isolation, subagent-namespace, e2e-anthropic, fix-config-session, anthropic-pck-identity)
  • Full suite: 1883/1888 pass; the 3 failures reproduce identically on unmodified master (environmental, git stash baseline verified)
  • Typecheck clean
  • End-to-end: two concurrent Task subagents through the proxy land on |sub: sessions in the log and complete in parallel (20.6s vs 129-188s pre-fix)

Opt-out

BILI_SUBAGENT_SPLIT=0 restores single-session behavior (covered by a test).

🤖 Generated with Claude Code

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Reviewing this PR now. Initial notes before the deep dive:

elevenfund and others added 2 commits September 19, 2026 09:57
… 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>
@ranxianglei
ranxianglei force-pushed the 2026-09-19_subagent-split branch from eff29e1 to 370ee63 Compare September 19, 2026 02:01
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[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: 370ee63.

What I changed (commit 370ee63, 4 files): subagentSplit only honored the BILI_SUBAGENT_SPLIT env var, unlike every other boolean toggle in src/config.ts (debug, autoUpdate, maskHosts all fall back to the config file). Now "subagentSplit": false in billion-context.json disables the split too, with env winning over file — same pattern as maskHosts (#897). Docs (CONFIGURATION.md / .zh-CN / CHANGELOG) updated to match. Verified with a 5-case precedence matrix (default-on, file-off, file-on, env-over-file both directions) plus typecheck + the PR's 5 new tests.

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 分支上补了一个小修复(subagentSplit 现在也支持配置文件关闭,与仓库其他开关一致),本地全量测试通过,等 CI 绿后给最终结论。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

[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、被 withSessionLock 串行化导致的 116–142s 首字节阻塞(#970);双信号判别逻辑经逐条代码核验成立且失败方向安全,我已补上配置文件开关的小修复并 rebase 到最新 master,CI 8/8 全绿,可以合并。

Duplicate screening

Related open PR #972 fixes the same issue #970 with a different mechanism (shrinking withSessionLock to state-mutating sections instead of splitting sessions). Not a duplicate — complementary: #975 removes subagents from the main lock entirely, #972 shortens whatever remains on it. Both rewrite the same src/server.ts region, so whichever lands second needs a semantic rebase. My recommendation: merge this one first (it's fully verified, CI-green, and kills the observed failure mode), then rebase #972 onto it.

What I audited (beyond running tests)

  • Root cause: confirmed at src/server.ts — the anthropic conversation value came straight from x-claude-code-session-id, and withSessionLock spans prepare + forward + full streamed response, so concurrent Task subagents head-of-line-block the main turn. Matches your live observation.
  • Two-signal discrimination (claudeSubagentAgentId, src/session-id.ts): header presence AND no main-system prefix match. The negative-check design is correct given there's no stable positive subagent marker across agent types, and failure degrades to serial (safe direction) — a main-prompt rewording can never mis-split the main session. Header-array edge (multi-value header treated as absent) and blank-agent-id fallback to parent are handled.
  • Identity continuity: verified the load-bearing claim — bodyIdentity (src/server.ts:~1240) still derives from the raw anthropicIdentity, so affinityToken/clientLabel keep the raw session id; only the internal conversation key becomes <id>|sub:<agent-id>. Forwarded body is untouched → wire-neutral, upstream prefix caches unaffected. No empty-base edge: on the anthropic branch the base identity is always defined.
  • Plugin-layer guards: the pending-register guard correctly mirrors [PR] feat: partition codex subagent threads by turn-metadata (PR-A of #316) #317 (a split session can't claim the root's register), and keying recordPluginSession under the split id fixes the last-writer-wins flip in the single-valued conversations map. Both are inert for today's Claude Code (no x-bili-plugin) but keep the layer honest if that changes.
  • Kernel contract: split sessions are independent Session objects with their own ref spaces; persistence format unchanged; id-never-reused guarantee intact.

Verification

  • Rebased onto current master (was 7 commits behind) — conflict-free; pushed as new head 370ee63 with one small fix of mine (see below).
  • CI on 370ee63: 8/8 success (test ubuntu×2/windows×2, codex fake-upstream E2E, version-guard, build-artifact).
  • Local on rebased head: typecheck clean, build green, full suite 1914/1916 pass, 0 failures (your 3 environmental failures didn't reproduce here).
  • Your negative control (split off → subagent first byte gated at ~1238ms behind the main stream) is what makes the no-stall test bite — good discipline pinning both sides.

Fix I pushed directly (commit 370ee63)

subagentSplit only honored the env var, unlike every other boolean toggle (debug/autoUpdate/maskHosts all fall back to the config file). Now "subagentSplit": false in billion-context.json works too, env wins over file — same pattern as maskHosts (#897). Docs updated; verified with a 5-case precedence matrix.

One nit I did not change (FYI, no action needed): the CHANGELOG entry is a single ~500-word paragraph — densest entry in the file. Fine for this one given the subtlety, but future entries could lead with the user-facing line.

@ranxianglei
ranxianglei merged commit ad0c73f into ranxianglei:master Sep 19, 2026
8 checks passed
ranxianglei pushed a commit that referenced this pull request Oct 23, 2026
…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.
ranxianglei pushed a commit that referenced this pull request Oct 23, 2026
…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.
ranxianglei pushed a commit to Mako-L/billion-context that referenced this pull request Oct 28, 2026
…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Subagent first token stalls 1-2min: withSessionLock covers full forward + slow flash upstream first byte

2 participants