95
0第4章的主题是 “工具执行编排 —— 权限、并发、流式与中断”。这一章深入解析了 Claude Code 如何在保证安全和一致性的前提下，高效地执行模型请求的多个工具调用。展示了 Claude Code 如何通过分区调度、纵深防御的权限链以及确定性的结果管理，在追求极致并发性能的同时，构建起一套不容突破的安全红线
1. 核心任务：解决三个关键问题
工具编排层（Tool Orchestration）主要负责处理以下三个核心挑战：
- 安全并发：区分只读工具（可并行）与写入工具（须串行），防止竞态条件。
- 权限门控：确保危险操作在执行前经过权限决策链的审查。
- 结果管理：对海量输出进行智能裁剪和持久化，防止挤爆上下文窗口。
2. 工具调用分区 (partitionToolCalls)
当模型一次性发出多个工具请求时，编排层首先进行“贪心合并”分区：
- 并发安全批次：连续的只读工具（如
FileRead,Grep）被合并，最大化吞吐量。 - 串行批次：修改状态的工具（如
FileWrite,Bash中的写入命令）独占一批，确保顺序执行。 - 失败即关闭 (Fail-closed)：如果模型输入无效或并发安全判定出错，系统默认回退到最安全的串行模式。
3. 单工具执行的九阶段生命周期
每个工具调用都会经历一套严密的执行流水线：
- 阶段 1-2：工具查找、Schema 验证及推测性分类器启动（提前开始 Bash 权限检查以减少延迟）。
- 阶段 3-4：执行 PreToolUse Hooks 并进入权限决策链。遵循纵深防御原则：Hook 的“允许”决策不能绕过用户在配置文件中显式设定的“拒绝”规则。
- 阶段 5-6：工具执行并产出进度事件，随后进行结果映射。
- 阶段 7-9：大结果持久化、执行 PostToolUse Hooks 以及必要时的中断判定（Stop Hooks）。
4. 流式并发执行器 (StreamingToolExecutor)
为了实现极致的流式体验，系统支持“工具到达即执行”，无需等待 API 响应结束：
- 状态机驱动：为每个工具维护
queued到yielded的状态转换。 - 选择性级联中断：这是一个精妙的设计——当一个 Bash 命令失败时，系统会取消所有同级并行的 Bash 工具（因为它们通常存在逻辑依赖），但不会影响独立的只读工具（如
Read）。
5. 结果管理与缓存优化
- 两级预算控制：单工具结果上限为 50,000 字符，单回合聚合预算为 200,000 字符。超出部分将被持久化到磁盘，模型仅看到带路径的摘要。
- 提示缓存稳定性：通过
ContentReplacementState确保一旦结果被持久化，后续迭代中该结果的摘要内容保持绝对一致，防止“缓存抖动”导致 API 成本激增。 - 空结果占位：为防止模型将空输出误判为回合结束，系统会自动注入占位文本（如
(Bash completed with no output)）。
6. 版本演化与新趋势
- AdvisorTool：引入了第一个“非执行类”工具，它不改变环境而是提供建议，标志着 Agent 从“只做事”向“先对齐意图再做事”演进。
- 工具结果去重：新增第三道上下文防线（前两道为输入去重和压缩），通过对输出端去重进一步维护上下文卫生。
