Claude Code 的工具执行流程

第 3 章讲了工具如何被定义、注册和暴露给模型。这一章接着看真正的执行链：模型吐出 tool_use 以后，Claude Code 如何把它变成安全、可中断、可回写的 tool_result。

核心问题不是“怎么调用函数”，而是五个更具体的问题：

• 多个工具调用能不能并发？
• 输入是否真的合法？
• hook、权限规则、用户配置谁优先？
• 流式工具执行时，进度和结果如何按序交付？
• 结果太大、为空、被中断时，下一轮模型到底看到什么？

先看源码入口

这章主要追三条线：toolOrchestration.ts 管批次，toolExecution.ts 管单工具生命周期，StreamingToolExecutor.ts 管流式并发。

总流程图

注意：StreamingToolExecutor 会把这条链路提前到模型流式响应期间执行。只要某个 tool_use block 已经可解析，它就能入队，而不是等整段 assistant 响应完全结束。

分区调度：partitionToolCalls() 先决定并发边界

模型可以一次返回多个 tool_use。如果全串行，读文件和搜索会很慢；如果全并发，写文件、改目录、跑命令可能互相污染。Claude Code 用 partitionToolCalls() 做折中：保留模型给出的顺序，但把连续的并发安全工具合成一个批次。

原文给出的核心片段：

function partitionToolCalls(
  toolUseMessages: ToolUseBlock[],
  toolUseContext: ToolUseContext,
): Batch[] {
  return toolUseMessages.reduce((acc: Batch[], toolUse) => {
    const tool = findToolByName(toolUseContext.options.tools, toolUse.name);
    const parsedInput = tool?.inputSchema.safeParse(toolUse.input);
    const isConcurrencySafe = parsedInput?.success
      ? (() => {
          try {
            return Boolean(tool?.isConcurrencySafe(parsedInput.data));
          } catch {
            return false;
          }
        })()
      : false;

    if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
      acc[acc.length - 1]!.blocks.push(toolUse);
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] });
    }
    return acc;
  }, []);
}

这段代码证明了三个执行策略：

举个具体序列：

[Read A] [Read B] [Grep C] [Bash D] [Read E] [Edit F]

会被分成：

runTools()：并发批次和串行批次走不同路径

runTools() 是批量执行入口。它拿到分区后的批次，然后按批次类型分发：

partitionToolCalls()
-> 并发安全批次: runToolsConcurrently()
-> 串行批次: runToolsSerially()

并发路径的形状是：

async function* runToolsConcurrently(...) {
  yield* all(
    toolUseMessages.map(async function* (toolUse) {
      yield* runToolUse(toolUse, ...);
      markToolUseAsComplete(toolUseContext, toolUse.id);
    }),
    getMaxToolUseConcurrency(),
  );
}

这段代码证明并发不是无限打开，而是受 getMaxToolUseConcurrency() 控制。原文定位到环境变量 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY，默认值为 10。

并发路径还有一个容易漏掉的点：context modifier 延迟应用。并发工具可能各自产生对工具上下文的修改，但如果执行中立即写入共享上下文，就会产生竞态。所以并发批次会先收集修改，等整个批次结束后再按工具出现顺序应用。

串行路径则相反：每个工具执行后立即应用上下文修改。

这说明 runTools() 不只是调度性能，它还在维护“上下文状态一致性”。

单工具生命周期：runToolUse() 到 checkPermissionsAndCallTool()

每个工具最终都会进入 runToolUse() 和 checkPermissionsAndCallTool()。可以把单工具生命周期拆成九步：

查找和输入校验

第一步是找工具。如果当前工具名找不到，还会检查已弃用工具 alias。这个设计让旧会话记录里的工具调用不至于因为工具改名直接失效。

输入校验分两层：

原文还提到 deferred tool 的特殊错误提示：如果某个工具 schema 没有发送给 API，Zod 错误会提示模型先通过 ToolSearch 加载 schema 再重试。这说明错误消息不是只给人看的，也会被模型用来修复下一轮动作。

命令分类器：提前为 Bash 权限判断做准备

在真正进入权限检查前，如果工具是 Bash，系统会推测性启动允许分类器。原文定位在 toolExecution.ts:740-752。

这个行为证明：权限系统不只追求正确，还追求等待体验。分类器和 hooks 可以并行跑，等用户需要权限判断时，分类器结果可能已经准备好。

预执行钩子：工具运行前先改输入和给权限建议

PreToolUse hooks 可以产生多种效果：

hook 如果被 abort signal 中断，系统会立即返回取消消息。这条路径说明 hook 自身也是执行链的一部分，不是旁路观察者。

权限决策链：hook 的 allow 不能覆盖用户 deny

权限链由 resolveHookPermissionDecision() 协调。原文强调一个不变量：Hook 的 allow 不能绕过 settings.json 中的 deny/ask 规则。

可以画成：

这张图里最重要的是 allow -> settings deny/ask 这条边。它说明用户配置的硬边界比 hook 的批准更高优先级。

执行阶段：tool.call() 和进度流合在一起

权限通过后，系统调用 tool.call()。原文提到执行过程会包在 startSessionActivity('tool_exec') 和 stopSessionActivity('tool_exec') 之间，用于追踪会话活跃状态。

工具执行期间还会产生进度事件。streamedCheckPermissionsAndCallTool 把两类东西合并到一个异步可迭代对象里：

• checkPermissionsAndCallTool 的最终 Promise 结果。
• 工具执行过程中的实时 progress 事件。

这说明执行链不只是“等结果”，而是边执行边向 UI 和上层循环提供可见信号。

StreamingToolExecutor：工具到达即入队，不等全量响应

批量 runTools() 是等 tool_use blocks 收集完以后执行。流式模式下，模型响应还没结束，某些 tool_use block 已经到达并可解析。StreamingToolExecutor 就负责把这些工具提前入队执行。

它为每个工具维护四个状态：

queued -> executing -> completed -> yielded

状态由 processQueue() 推进。每次新工具入队或某个工具完成，队列处理器都会尝试启动下一个可执行工具。

核心并发判断：

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing');
  return (
    executingTools.length === 0 ||
    (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
  );
}

这段代码证明：

这和 partitionToolCalls() 的策略是一致的：不确定就独占，确定只读才并发。

兄弟级联：一个 Bash 失败后取消同级命令

StreamingToolExecutor 对 Bash 有一条特殊错误策略：

if (tool.block.name === BASH_TOOL_NAME) {
  this.hasErrored = true;
  this.erroredToolDescription = this.getToolDescription(tool);
  this.siblingAbortController.abort('sibling_error');
}

这段代码证明：一个 Bash 工具出错时，会取消同级并行 Bash 工具。原因是 shell 命令之间常有隐式依赖，比如前一个 mkdir 失败，后面的 cp 多半也没有意义。

但它使用的是 siblingAbortController，不是父级 toolUseContext.abortController。也就是说：

这体现的是选择性级联：局部失败不要扩散成全局崩溃。

进度可以先交付，结果必须守顺序

原文还指出：普通工具结果必须按序传递，但进度消息可以立即传递。StreamingToolExecutor 把进度消息放进独立的 pendingProgress 队列，getCompletedResults() 会优先 yield 进度。

当没有完成结果但仍有工具执行时，getRemainingResults() 用 Promise.race 等待“任一工具完成”或“新进度到达”，避免轮询。

这说明执行器区分两种时序：

中断行为：cancel 和 block

每个工具可以声明中断行为：cancel 或 block。

StreamingToolExecutor 通过 updateInterruptibleState() 追踪当前是否所有执行中工具都可中断，并把这个信息传给 UI。UI 是否显示“按 ESC 取消”，不是凭感觉，而是来自工具执行状态。

结果管理：大输出、聚合预算和空结果都要处理

工具完成后，结果不能直接无脑写回。toolResultStorage.ts 负责结果预算和持久化。

单工具大结果持久化

阈值优先级是：

原文指出最终阈值取工具声明值和全局上限的较小者；如果工具声明 Infinity，则跳过持久化，例如 Read 工具自己管理输出边界。

当结果超过阈值，persistToolResult() 会把完整内容写入会话目录下 tool-results/，并生成预览：

<persisted-output>
Output too large (245.0 KB). Full output saved to: /path/to/tool-results/abc123.txt

Preview (first 2.0 KB):
[前 2000 字节的内容...]
...
</persisted-output>

预览会尽量在换行处截断，避免把错误日志或表格行切断在中间。

每消息聚合预算

如果一个回合里 10 个工具各返回 40K，单个工具都不一定超限，但合起来就是 400K。Claude Code 还有单消息聚合预算，默认 MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200,000。

超出聚合预算时，系统从最大的工具结果开始持久化，直到总量回到预算内。

ContentReplacementState：为了缓存稳定，替换结果要可重复

原文提到聚合预算维护 ContentReplacementState。它记录哪些工具结果已经被持久化。

这证明持久化不是每次重新临时决定。一旦某个结果被替换，后续评估中继续使用同一个替换版本，即使当下总量没有超预算。

原因是 prompt cache：同一条消息如果一会儿是完整结果、一会儿是持久化摘要，前缀字节会抖动，缓存命中就会变差。

空结果也要补占位文本

原文指出空 tool_result 可能让某些模型误以为到了回合边界，输出 \n\nHuman: 停止序列。系统会给空结果注入占位文本，比如 (Bash completed with no output)。

这说明“没有输出”本身也需要被编码成明确事实。否则模型可能把空白理解成结构信号，而不是工具结果。

停止钩子：工具执行后的中断点

PreToolUse 和 PostToolUse hooks 都可以设置 preventContinuation。

关键行为是：

hook 设置 preventContinuation
-> 工具仍可能执行
-> 执行后追加 hook_stopped_continuation 附件消息
-> Agent Loop 检测到后终止当前迭代
-> 不再把结果继续送给模型推理

这条路径体现了一种精细控制：hook 不一定阻止工具本身执行，但可以阻止“执行结果继续驱动 Agent 自主行动”。这对安全策略非常重要。

状态和数据结构

设计取舍

读源码抓手

建议按这个顺序读：

1. 从 toolOrchestration.ts 的 runTools() 入口开始，不要先跳到具体工具。
2. 看 partitionToolCalls()，确认 schema 解析和 isConcurrencySafe(input) 如何决定批次。
3. 追 runToolsConcurrently() 和 runToolsSerially()，重点看 context modifier 何时应用。
4. 进入 toolExecution.ts 的 runToolUse()，画出查找工具、schema 校验、语义校验、hook、权限、执行、结果映射。
5. 看 resolveHookPermissionDecision()，确认 hook 决策和 settings deny/ask 的优先级。
6. 读 StreamingToolExecutor 的 queued -> executing -> completed -> yielded 状态转移和 canExecuteTool()。
7. 最后读 toolResultStorage.ts，重点看 persistToolResult()、聚合预算、ContentReplacementState 和空结果占位。