从“单兵死磕”到“分身协作”：复杂任务下 AI Agent 的工程化突围

大任务塞进单一上下文会让模型注意力涣散。委派 = 把一段自包含探索搬到全新历史里跑（干净上下文），父 Agent 只拿回一句结论。注意：「隔离」= 上下文隔离，不是沙箱、不是提权、不是降权。子 Agent 与父共享 workspace、身份、权限和进程。

只有一个入参：description（自包含任务描述）。它必须完整——因为子 Agent 看不到父 history，它只能靠这句话独立干活。描述里该带路径、该带验收标准、该带返回格式要求。

{\"description\": \"检查本项目用的测试框架:读 package.json、找到测试目录...\"}

SubagentTool 不是第二套 Loop——它复用同一个 AgentRunner，对同一个 context 跑一次内部 run()。只是这个内部 run 用的是全新 history 和子工具集。父 history 极少被触碰。

父调用一次 task，父 history 只多三条消息：assistant(task) → tool(结论) → assistant(最终回答)。子 Agent 的完整推理过程不进父历史——代价是子推理无法审计，所以要求 evidence-based 结论（子 Agent 必须引用文件做证据）。

共享意味着子 Agent 没有豁免：它的工具调用照样打 hook 日志、照样过权限、越界照样被硬边界 deny。审批框上不标注「这是子 Agent 发起的」——因为父子共享 identity。

三层防线保证子 Agent 不可能再调 task：① 提示层：子 system 明确禁止；② 工厂层：子工具集构建时剔除 task；③ 运行时：即使模型自己生成了 task 调用，也返回 subagent_configuration_error。第三层保证「模型零调用」——子 Agent 压根没被创建，模型请求次数只有父那一次。

子 Agent 有独立 maxTurns=30，构造期校验（>30 直接拒绝启动）。跑满轮数返回结构化错误 Error [subagent_turn_limit]，绝不把最后一个工具输出冒充结论。父历史仍保持「一条 tool 消息」的整洁。

// 子 Agent 异常/超限 → 结构化 ToolResult,不污染父 Loop

P06 在 bootstrap 里构造 SubagentTool 并注册为父工具集的一员。SubagentTool 需要拿到父的 AgentRunner 工厂、子工具集（不含 task）、maxTurns。父子共用 ModelClient，因此只需要一组 .env。

子 Agent 的工具列表里有 todo_write，但没有挂 toolRoundObserver——所以它不会收到「计划陈旧」提醒。子 Agent 有工具但没这层机制，这是刻意的。测试用注入的假审批器证明：即使配「永远批准」，子 Agent 也写不出 workspace（硬边界拦下）。

npm run ch06 -- --prompt \"调用 task 独立检查本项目使用的测试框架，只返回有文件证据的结论\"
# stderr 上父子交错:
#   [Hook] UserPromptSubmit     (父)
#   [Hook] PreToolUse: task     (父)
#   [Hook] UserPromptSubmit     ← 子 Agent 那次 run() 也打日志!
#   [Hook] PreToolUse: read_file (子)
#   ...
# Hook 是共享实例,所以子 Agent 的 run() 也会打 UserPromptSubmit 和 Stop
# 观测局限:共享 HookRegistry 的代价是日志里分不清父子

npm run test:ch06   # 预期 16 files / 118 tests

npm run ch06 -- --prompt \"调用 task 独立检查本项目使用的测试框架，只返回有文件证据的结论\"
# 父子日志交错;Hook 共享实例,子 Agent 的 run() 也打 UserPromptSubmit/Stop

npm run ch06 -- --prompt \"调用 task 让子 Agent 把一句话写入 sub-demo.txt\"
# task 自己 allow;子 Agent 的写入照样弹审批框

# 统一入口
npm run agent-tutorial -- run --chapter 6 --prompt \"调用 task 总结 chapters/ch06/src/core 目录职责，再由父 Agent 给出结论\"

• task 把一段自包含探索搬到一个全新历史里跑，父 Agent 只拿回一句结论。
• 隔离的只有消息历史和工具注册表；Hook、权限、workspace、identity、进程全部共享。
• 委派不创造新路径：子 Agent 该弹的审批照样弹，该拦的越界照样拦。

P06 只加了「一层同步委派」，没加并行、没加持久化、没加沙箱。并行（第 13 章后台任务）、多 Agent 认领（第 17、18 章）、Inbox 异步协作（第 15 章）都在后面。

• 子 Agent 在 workspace 里写的文件，task 返回后还在吗？为什么？
• 父 Agent 调用一次 task，父 history 里多了几条消息？分别是什么？
• 子 Agent 的 write_file 会弹审批框吗？审批框上能看出这是子 Agent 吗？
• 给子 Agent 配「永远批准」的审批器，它能写出 workspace 吗？
• 子模型自己生成了 task(...) 调用，它会收到什么？
• 子 Agent 跑满 30 轮，父 Agent 收到的是第 30 轮的工具输出，还是别的东西？
• 子 Agent 的工具列表里有 todo_write。它会收到「计划陈旧」提醒吗？