Skip to content

[PR] Claude subagent parallel homogeneous dispatch merge: SubagentStart hook injects a unique lane token per dispatch (#5095) | claude 子代理并行同型派发合流:SubagentStart hook 注入每次派发唯一 lane token(#5095) - #5184

Merged
ranxianglei merged 4 commits into
masterfrom
2026-10-30_subagent-lane-token
Oct 31, 2026

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

(ai: vllm-qwen/qwen3.8-27b)

Fixes #5095

什么坏了

#4774(v0.1.209)把无 agent-id 头的 Claude Code 子代理(VS Code 扩展构建)从父会话裸 key 上分到 |sub:<fp16(system)> 车道。但并行派发同一类型的子代理(同一 system 文本 → 同一指纹)全部合流到这一条车道:无关会话互相串内容、折叠互相干扰(#5095 实测时间线)。指纹只对「类型」单射,不对「派发」单射。

方案(D1-C,方案讨论见 issue 评论)

bili 托管 settings 新增一个 SubagentStart hook(dist/claude-subagent-hook.js,与现有 SessionStart bootstrap 同安装通道):每次子代理启动铸一个 12 位十六进制随机 token,以 additionalContext(bili-lane-token:<hex>)注入该次派发的上下文。token 随派发自己的首条 user 消息上线;解析器读到 token 就确定性地键控到 <rawId>|sub:<fp16(tag)>:t:<token>——每次派发唯一,并行同型派发天然分道。token 不在(未升级安装/首条消息被折叠后/其他宿主)时精确回落现行 #4774 行为,零回归面。

改动

  • src/claude-lane-token.ts(新):token 语法单一来源(mint/校验/提取,零依赖,被 hook 入口与代理侧共同内联)。
  • src/claude-subagent-hook.ts(新,tsup 入口):SubagentStart hook——读空 stdin、铸 token、输出 {hookSpecificOutput:{hookEventName:"SubagentStart",additionalContext:...}};任何错误静默 exit 0,绝不打断用户子代理启动。
  • src/session-resolve.ts:resolveSessionOrder/personaConversationOrder 新增可选 laneToken;token 有效时在最前面确定分叉(不读骨架、不认领裸 key——同时杀掉 virgin-id 上的 [bug] dsh:side request 先到会抢走 persona 锚点,主会话被 fork 到 |sub:<fp>,原生 compress 永久失败 #2156 式抢注竞态),非法 token 被消毒拒绝。
  • src/session-id.ts:claudeSubagentLaneTokenOf(messages)——只扫第一条 user 消息(string / text 块,system-reminder 包裹无所谓);用户把标记粘到后续消息不会误分叉主会话。
  • src/server/handle.ts:Subagent requests share the parent session id and trip fold-reconcile #4352 分支(personaOrderKeyed 车道)传入第 5 参;其余车道零改动。
  • src/plugin-install.ts:托管块安装/重钉/剥离 SubagentStart 钩子(与 SessionStart 同 isOurs 纪律;用户自己的 SubagentStart 条目永不触碰;repin 只在 dist 文件存在时写,升级中途不烤死命令)。
  • tsup.config.ts、reference/architecture.md、README.md/README.zh-CN.md(zh/en 同步)。

测试

tests/issue5095-subagent-lane-token.test.ts(7 用例,正反两向 #3617):

  • 语法:铸/校验/边界(hex 两侧贴 hex 拒匹配);hook 输出 JSON 契约、每次新 token。
  • 提取器:首条 user 命中;后续消息粘贴 = 负例;图像块/退化形状 = 负例。
  • 解析器:同 token 多趟同键;同型并行两 token 不同键(本 PR 的核心修复);非法 token 回落指纹车道;token 流量不抢注 virgin 裸 key;无 token 控制组保持 Subagent requests share the parent session id and trip fold-reconcile #4352 合流形态(文档化缺口,不变)。
  • 安装:SubagentStart 写入/幂等/陈旧命令刷新/用户条目保留/不传参不写/剥离对称。
  • 端到端(真实 server + mock 上游):并行同型派发各自成 session、父会话不动、无共享指纹车道;无 token 负例端到端。

相邻面:issue4352、claude-subagent-split、hook-command 全绿;claude-native 4 个失败为本地端口区粘滞环境噪音(干净 HEAD 同样失败,CI 隔离环境绿)。typecheck + build 绿;独立脚本实测(echo … | node dist/claude-subagent-hook.js → 合法 JSON、exit 0、空 stdin 安全)。

config surface

无新增用户配置键。受管 settings 块(bili plugin install claude 写入的 hooks.*)新增一条 SubagentStart 条目——属安装面而非 billion-context.json schema;卸载随受管块一并移除。现存机制已穷尽:该判别量线上不存在(msgid 无、头无、metadata.user_id 父子同值),只能 bili 自铸;通道复用现有 SessionStart 同构安装通道(#5051 receipt 先例)。

已知边界

审查提示

触及会话身份/车道键(§7.4 must-stay-human):不申请 auto-merge,人工审查合并。

@github-actions

github-actions Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-30_subagent-lane-token (04403d0)

Latest build — install this exact version

npm install -g billion-context@0.0.7272-pr.5184.a6a5751

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
04403d0 billion-context@0.0.7272-pr.5184.a6a5751 build
689f701 billion-context@0.0.7005-pr.5184.8c2e6db build
6f800f2 billion-context@0.0.6992-pr.5184.b836f02 build
392721d billion-context@0.0.6982-pr.5184.40a5610 build
c137294 billion-context@0.0.6975-pr.5184.e8baab9 build
da3bf5a billion-context@0.0.6973-pr.5184.6448076 build
69818a9 billion-context@0.0.6921-pr.5184.14e4773 build
4a5eb43 billion-context@0.0.6912-pr.5184.4042893 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr5184.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title claude 子代理并行同型派发合流:SubagentStart hook 注入每次派发唯一 lane token(#5095) [PR] claude 子代理并行同型派发合流:SubagentStart hook 注入每次派发唯一 lane token(#5095) Oct 30, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

(ai: sglang-gpu0/qwen3.8-27b)

CI 状态说明(2026-10-30 02:2xZ 更新)

本 PR 自己造成的失败已修完:test-import-graph / unused-exports 两个静态门(新入口没同步门脚本清单、两个无外部使用的导出)在 69818a9 起全绿。

剩余的 test 分片红不是本 PR 引入的。失败的是固定一组测试(#3575 squatter 诊断、#4323 shadow 冻结、#5103 存储告警、#5140 raw-tail),与本 PR 改动面(claude 安装面 / session-resolve / lane token)无交集,且同样这批测试在 merge 基底 a8c907dd5(master)本身、以及同期另一个 PR #5188 的 CI 上以相同分片挂掉;4bb2bc1ed(#5169 之前的 master)是全绿的。完整证据表和判别建议在 #5195(已开,回归问题/p1/scope/ci)。

本 PR 相关文件所在的分片(包括跑过 tests/issue5095-*、tests/issue4352-*、tests/plugin-install* 的所有分片)除上述 master 遗留失败外全绿;本地 tests/plugin-fork.test.ts 54/54 绿。

@ranxianglei ranxianglei changed the title [PR] claude 子代理并行同型派发合流:SubagentStart hook 注入每次派发唯一 lane token(#5095) [PR] Claude subagent parallel homogeneous dispatch merge: SubagentStart hook injects a unique lane token per dispatch (#5095) | claude 子代理并行同型派发合流:SubagentStart hook 注入每次派发唯一 lane token(#5095) Oct 30, 2026
@ranxianglei ranxianglei added bug Something isn't working claude p2 scope/ci labels Oct 30, 2026
@ranxianglei
ranxianglei force-pushed the 2026-10-30_subagent-lane-token branch from 392721d to 6f800f2 Compare October 30, 2026 06:22
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b) Merge guard ping resolved without a push from my side: while I was merging master (dc10c2d0b) locally, a parallel session force-updated the branch with a cleaner rebase onto current master (392721d7c→6f800f2fc, incl. CI follow-up fixes to gate entry lists). My push was correctly rejected as non-fast-forward and I did NOT overwrite it — verified instead that remote head 6f800f2fc contains current master plus the full changeset (all 3 new files, lane-token wiring in handle/session-resolve/session-id/plugin-install/tsup). PR state now: mergeable=true, mergeable_state=blocked (not behind — waiting on CI for 6f800f2fc). Local branch reset to match remote.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b) Merge guard ping resolved: branch was already up-to-date with master (dc10c2d0b, guard snapshot stale), but CI on 6f800f2fc showed 4 red gates (mysql-contract / config-surface-guard / docs-coverage / lifecycle-ledger-guard) = the known inherited red family on master per #4599. Merged origin/ci-fixes (9c186cc56) into the branch — zero file overlap with the PR's changes; local typecheck + build + all 3 static gate scripts + targeted test file green on pushed head 689f70155 (mysql-contract needs the live MySQL service, left to CI rerun). PR state after push: mergeable=true, mergeable_state=blocked (not behind — waiting on CI for 689f70155).

@ranxianglei ranxianglei left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

审查结论:代码通过,等 CI 转绿后可合并(不申请 auto-merge,§7.4)

问题:VS Code 扩展版 Claude Code 的子代理不带 agent-id 头、骑着父会话 id 走。#4774 用 system 文本指纹分车道,但并行派发同一类型的子代理(system 文本相同 → 指纹相同)全部挤进同一条车道,互相串内容、折叠互相干扰。

根因:解析器对无头子代理流量的键是 <rawId>|sub:<fp16(指纹)>,这个映射只对"类型"单射、不对"每次派发"单射;线上又没有任何能区分两次派发的量(msgid 无、头无、metadata.user_id 父子同值),所以同型并行必然合流。

修法核验(逐项):

  • ✅ token 分支在 src/session-resolve.ts:234(isClaudeLaneToken 守卫后)于所有启发式之前短路返回,键 <rawId>|sub:<fp>:t:<token>——每次派发唯一;且不读裸 id 骨架、不认领裸 key,顺带杀掉 virgin-id 上的 #2156 式抢注竞态(测试里有"子代理先到、主会话后到仍能认领裸 id"的验证行)。
  • ✅ 零回归面成立:非法 token 被 src/claude-lane-token.ts:25 的语法校验拒绝回落;无 token 路径字节级不变,两个端到端负例锚定了旧合流形态不变。
  • ✅ 提取器(src/session-id.ts claudeSubagentLaneTokenOf)只扫第一条 user 消息:用户把标记粘到后续消息不会误分叉主会话(有负例);图像块/退化形状安全。
  • ✅ 安装面(src/plugin-install.ts):用户自有 SubagentStart 条目永不触碰(有测试);重钉路径有 fs.existsSync 守卫,升级中途不会烤死指向不存在文件的命令;剥离与安装对称。
  • ✅ 无泄漏:skeleton 存储有界(MAX_ORDER_ENTRIES=1024 LRU + 8MB,src/order-persist.ts:29),token 车道不会无限增长。
  • ✅ 测试符合 #3617 门禁纪律:正反两向齐全,核心修复点(同型并行两 token 不同键)和文档化缺口(无 token 仍合流)都有锚定。

参考:本地定向跑了新文件 + 相邻回归(issue4352 / claude-subagent-split / hook-command)共 27 用例全绿;PR 自述 claude-native 4 个失败为本地端口区环境噪音(干净 HEAD 同样失败),最终以 CI 为准。

两个非阻塞小发现(可不改合并)

  1. 入口自检写法与同类入口不一致:src/claude-subagent-hook.ts 用 process.argv[1].includes("claude-subagent-hook"),而 kimi/bootstrap-hook.ts:52、zcode/bootstrap-hook.ts:55、claude-native-bootstrap.ts:588 都是正则锚定文件名结尾(如 /(?:^|[\\/])bootstrap-hook\.(?:ts|js)$/)。.includes() 在任何 argv 路径包含该子串时也会误触(例如仓库 checkout 在名叫 …claude-subagent-hook… 的目录下时,模块被 import 也会执行 main)。实际风险极低,改成同型正则即可一了百了。
  2. 边角:如果用户把自己的第一条消息粘贴成含 bili-lane-token:<12位小写hex> 的内容,整个主会话会被键到该 token 车道上(该会话压缩连续性受损,直到首条消息被折叠才恢复)。概率极低、仅自伤(键含自己的 rawId,无跨会话影响),可在 README「已知边界」补一行注释即可。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) Merge-guard follow-up check: re-verified via GitHub API that PR #5184 is still state=closed, merged=true (merged 2026-10-31 00:31 UTC, merge commit 64e5b2d6…→64e55a5c3). The recurring "behind" pings are stale — the branch's content is fully in master; there is nothing left to sync or push, and no further action from my side. Full coordination history: two real master-syncs (rounds 1/3), one parallel-session rebase I verified instead of overwriting (round 4), one inherited CI red fixed via origin/ci-fixes merge (round 5, sha 689f70155, logged in #4599), and the remaining pings were stale flags on an already-merged PR.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) Correction to my previous line: the merge commit is 64e55a5c3 (the 64e5b2d6… fragment was a typo, ignore it).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

1 participant