从「单兵死磕」到「分身协作」

本章导读(你在这)
  ↓
① 先看一眼一次真实的委派    ← 子 Agent 干活的完整日志
  ↓
② 这章解决什么问题          ← 上下文隔离,不是沙箱
  ↓
③ 严格的 task 输入          ← 自包含 description
  ↓
④ SubagentTool = 执行边界    ← 复用同一个 AgentRunner
  ↓
⑤ 历史隔离 + 边界共享        ← 三、四
  ↓
⑥ 禁止递归委派              ← 三层防线
  ↓
⑦ 30 轮上限 + 脱敏错误       ← 六
  ↓
⑧ 组合根 + 离线证明          ← 七、八
  ↓
⑨ 运行 + 实验 + 差异 + 小结   ← 九~十一

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

子 Agent 的 write_file 照样走第 3 章权限:工作区内弹审批、工作区外被硬边界 deny。`task` 自己是 allow(读取类),但子 Agent 的写入照样弹到你面前——审批框上不标注「这是子 Agent 发起的」,因为父子共享 identity。

第 5 章 todo_write 解决「单会话如何保存计划」,但不减少探索过程本身的上下文。第 6 章解决「如何隔离一段独立探索」:父调用 task,运行时创建新 AgentRunner:

父 Agent
  assistant: task(description=...)
      ↓
一次性 Subagent
  system: 专注完成委派任务,不再委派
  user: description
  history: 全新
  tools: shell/read_file/write_file/edit_file/glob/todo_write
      ↓
父 Agent
  tool: 子 Agent 的 finalText

description 必须 trim 后非空,.strict() 拒绝额外字段。为什么强调「自包含」?因为子 Agent 不继承父 history。

子 Agent 可多轮 read_file/glob/shell,但 SubagentTool 只返回 result.finalText。父 history 只保存:

user:      父任务
assistant: tool_calls=[task(parent-task)]
tool:      子 Agent 的 finalText, toolCallId=parent-task
assistant: 父 Agent 的最终回答

子内部历史不 append 到父。父 Loop 仍按 tool_call_id 配对写 tool message,OpenAI 工具配对契约无例外。

子 Agent 用新 AgentRunner,但不是新权限系统。构造时直接传入父会话组合根创建的同一实例:hooks、permissionPolicy、workspace、identity。

子工具调用顺序仍是:PreToolUse → PermissionPolicy → handler → PostToolUse。子尝试向 workspace 外写入,第 3 章硬边界先 deny,审批器不会被调用。合法的子 write_file 仍按原策略请求审批并写入同一 workspace,父之后可继续读。

P06 父工具有 7 个(含 task),子工具工厂只创建前 6 个(不含 task)。两层防护:

1. 工厂不注册:正常组装路径,子工具集不含 task。
2. 运行时拒绝:若 tools.names.includes("task") 返回 subagent_configuration_error,保护工厂被错误改写。

若子模型仍生成 task(...),Registry 返回 unknown_tool: Unknown tool: task,不会创建孙 Agent。

DEFAULT_SUBAGENT_MAX_TURNS=30,构造时不允许高于 30。子连续 30 轮只返回工具调用时,公共 Loop 抛 AgentLimitError,task handler 转成稳定错误:

Error [subagent_turn_limit]: Subagent exceeded max_turns=30 without a final answer

父不会收到第 30 轮最后一个工具输出,不能把它误认为结论。其他异常也脱敏:subagent_execution_error,不泄漏 API Key/路径/适配器细节。

task 的 effect 是 "external"(发起一段独立执行,而非直接读写文件)。第 3 章审批仍由工具名和硬边界决定,不会因 task 标 external 就把所有子工具误判成磁盘写入。子工具是否允许写盘,仍由各自工具名和权限边界决定。

Set-Location 'F:\笔记\Agent实操\code'
npm ci
npm run test:ch06

 Test Files  16 passed (16)
      Tests  118 passed (118)

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 给出结论"

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

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