随笔
Claude Code 源码解读 07：多 Agent 协作先要被收束
拆解 AgentTool、agent 过滤、fork、background task、通知回灌和 worktree isolation，说明多 Agent 协作不是随意分身。
多 Agent 不是多开几个模型。源码里真正重要的是委托入口、agent 可见性过滤、异步任务状态、结果通知和 worktree isolation。
快速了解
- 多 Agent 的核心不是分身，而是把子任务变成可观察、可中断、可回灌的任务。
AgentTool是统一委托入口，normal、fork、background、team、remote 都是条件分支。- agent 类型也要过 MCP requirement 和 deny rule，不能绕开权限系统。
- worktree isolation 是文件副作用边界，不只是体验优化。
如果只想快速理解，可以先读这一节；如果要看源码机制，再往下看“主线与场景插入分类”和机制图。
设问与回应
| 设问 | 回应 |
|---|---|
AgentTool 的 schema 为什么要按 feature 收缩？ | AgentTool 的 schema 要按 feature 收缩，是为了让模型只看到当前模式真正可用的委托能力。normal、fork、background、team、remote 不应被包装成同一个无条件入口。 |
| agent 选择为什么要先过 MCP requirement 和 deny rule？ | agent 选择先过 MCP requirement 和 deny rule，是因为子 agent 也是能力暴露面。不能因为它是“另一个 agent”，就绕过当前环境的工具依赖和权限策略。 |
| background task 如何避免变成黑盒？ | background task 不变成黑盒，靠的是 task state、pending messages、完成通知、output file 和 turn 边界回灌。主 agent 需要看到异步任务状态，而不是只等一段自然语言汇报。 |
| worktree isolation 是体验优化，还是文件副作用边界？ | worktree isolation 不是单纯体验优化，而是文件副作用边界。多 agent 并发时，如果共享同一工作区，改动冲突和上下文污染会直接破坏协作可靠性。 |
主线与场景插入分类
| 机制/模块 | 分类 | 我保留的判断 |
|---|---|---|
AgentTool | 主线 + 场景插入聚合点 | 模型委托工作的统一工具入口；normal/fork/background/team/remote 按条件触发 |
filterAgentsByMcpRequirements() | 安全/治理横切 | agent prompt 暴露前先按 MCP server tool 可用性过滤 |
filterDeniedAgents() | 安全/治理横切 | agent 类型也受权限规则控制 |
LocalAgentTaskState.pendingMessages | 可观测/恢复支撑 | mid-turn message 排队，在工具轮边界进入 agent 输入 |
| TaskCompleted / TeammateIdle hooks | 可观测/恢复支撑 | teammate 完成路径检查 in-progress task 和 idle 状态 |
多 Agent 的关键不是扩张，而是收束
复杂任务可以拆，但拆出去的任务必须能被主循环看见、叫停、恢复、汇总。normal subagent、fork subagent、background task、remote agent、worktree isolation 都是不同条件路径。
从 Codex 差异拆解多 Agent 设计
Codex 的差异价值，不是判断“谁更会并发”，而是逼着我们把多 Agent 问题拆开：子任务如何被创建，父子关系如何记录，权限如何继承或收缩，结果如何回灌，未完成状态如何被主循环感知。只要这些问题没有结构化答案，多 Agent 就会从协作机制退化成自然语言派活。
我当前更愿意用五个检查点看这类 harness：任务状态是否独立于模型叙述存在，输出是否有文件或结构化记录承接，通知是否能在 turn 边界被 drain，取消/恢复是否有明确路径，文件副作用是否能被 worktree isolation 约束。Claude Code 的 task state、notification、output file、worktree isolation 和 query loop 回灌给了一个样本；Codex 的 thread / task / subagent 关系则适合用来反问这些边界是否同样清楚。这个对比真正服务的是一个设计原则：多 Agent 能力越强，harness 越要把并发结果收束成可观察、可恢复、可治理的主线状态。