5 · 工具执行

这一章讲：模型给出一批工具调用之后，程序是怎么把它们跑完的。

5.1 执行链路总览

5.2 并发分区：贪心算法

function partitionToolCalls(toolUseMessages, 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 {
            // 如果判定函数抛异常（比如 shell 引号解析失败），
            // 保守地当成"不安全"
            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
  }, [])
}

claude-code/src/services/tools/toolOrchestration.ts

执行效果：

5.3 上下文修改要排队到批次结束

有些工具会修改共享的上下文对象（比如 EnterPlanMode 会切换权限模式）。并行批里如果每个工具立刻改，就有竞态。

if (isConcurrencySafe) {
  const queuedContextModifiers: Record<string, ((ctx) => ToolUseContext)[]> = {}

  for await (const update of runToolsConcurrently(blocks, ...)) {
    if (update.contextModifier) {
      const { toolUseID, modifyContext } = update.contextModifier
      if (!queuedContextModifiers[toolUseID]) queuedContextModifiers[toolUseID] = []
      queuedContextModifiers[toolUseID].push(modifyContext)      // ★ 先排队
    }
    yield { message: update.message, newContext: currentContext }  // 仍用旧上下文
  }

  // ★ 整批完成后，严格按工具调用的原始顺序应用修改
  for (const block of blocks) {
    const modifiers = queuedContextModifiers[block.id]
    if (!modifiers) continue
    for (const modifier of modifiers) currentContext = modifier(currentContext)
  }
  yield { newContext: currentContext }
}

而 Tool.ts 里有一条对应的兜底约束：

5.4 单次执行：runToolUse 的完整流程

第 ① 步：按名字找工具，支持别名

// 先在"模型能看到的工具"里找
let tool = findToolByName(toolUseContext.options.tools, toolName)

// 找不到 → 检查是不是一个已废弃的名字（老对话记录里可能还在用旧名）
// 例如老记录里调用 "KillShell"，而它现在是 "TaskStop" 的别名
// 只有当名字匹配的是"别名"而不是"主名"时才回退

这个设计解决的问题是：工具改名之后，用户用 --resume 恢复的旧对话里还有旧名字的调用记录。如果直接报「工具不存在」，那条历史消息就永远无法被正确处理。

第 ③ 步：参数格式校验，附带一句诚实的注释

// Validate input types with zod
// (surprisingly, the model is not great at generating valid input)
const parsedInput = tool.inputSchema.safeParse(input)
if (!parsedInput.success) {
  let errorContent = formatZodValidationError(tool.name, parsedInput.error)
  const schemaHint = buildSchemaNotSentHint(tool, ...)   // 见第 4.5 节
  if (schemaHint) errorContent += schemaHint
  ...
  return [{ message: createUserMessage({
    content: [{ type:'tool_result',
                content: `<tool_use_error>InputValidationError: ${errorContent}</tool_use_error>`,
                is_error: true, tool_use_id: toolUseID }],
    ... }) }]
}

括号里那句 「surprisingly, the model is not great at generating valid input」（意外的是，模型并不太擅长生成合法参数）—— 这是源码里少见的直白吐槽，但它说明了一个重要事实：即使是最强的模型，工具参数也需要严格校验，不能信任。

注意错误结果的形式：它不是抛异常，而是作为一条正常的「工具结果」返回给模型，只是标记了 is_error: true，内容用 <tool_use_error> 标签包裹。这样模型能看到自己错在哪，下一轮自己改正。

第 ⑤ 步：投机性地提前启动分类器

// Speculatively start the bash allow classifier check early so it runs in
// parallel with pre-tool hooks, deny/ask classifiers, and permission dialog
// setup. The UI indicator (setClassifierChecking) is NOT set here — it's
// set in interactiveHandler.ts only when the permission check returns `ask`
// with a pendingClassifierCheck. This avoids flashing "classifier running"

译：投机性地提前启动 bash 放行分类器的检查，让它和「工具前钩子」「拒绝/询问分类器」「权限对话框的准备」并行跑。界面上的「分类器运行中」指示器不在这里设置 —— 只有当权限检查返回「需要询问」且带着一个待定的分类器检查时，才在交互处理器里设置。这避免了指示器闪一下就消失。

5.5 流式工具执行器

常规做法是等模型的整个响应流完再开始跑工具。Claude Code 的做法是：模型每写完一个工具调用就立刻开始执行它。

为什么能这么做

模型是一个 token 一个 token 往外吐的。如果这一轮要写三个工具调用，那么第一个写完时第二个还没开始 —— 这中间有几秒钟空档。

// query.ts 的流式循环内部
if (message.type === 'assistant') {
  const msgToolUseBlocks = message.message.content.filter(c => c.type === 'tool_use')
  if (msgToolUseBlocks.length > 0) {
    toolUseBlocks.push(...msgToolUseBlocks)
    needsFollowUp = true
  }
  if (streamingToolExecutor && !toolUseContext.abortController.signal.aborted) {
    for (const toolBlock of msgToolUseBlocks) {
      streamingToolExecutor.addTool(toolBlock, message)     // ★ 一到手就入队
    }
  }
}
// 同一个循环里持续收割已完成的
if (streamingToolExecutor && !toolUseContext.abortController.signal.aborted) {
  for (const result of streamingToolExecutor.getCompletedResults()) {
    if (result.message) {
      yield result.message
      toolResults.push(...normalizeMessagesForAPI([result.message], ...))
    }
  }
}

执行器的内部状态机

type ToolStatus = 'queued' | 'executing' | 'completed' | 'yielded'
//                 排队中     执行中       已完成        已发出

type TrackedTool = {
  id: string
  block: ToolUseBlock
  assistantMessage: AssistantMessage
  status: ToolStatus
  isConcurrencySafe: boolean
  promise?: Promise<void>
  results?: Message[]
  pendingProgress: Message[]      // 进度消息单独存，立刻发出
  contextModifiers?: Array<(ctx: ToolUseContext) => ToolUseContext>
}

并发规则

private canExecuteTool(isConcurrencySafe: boolean): boolean {
  const executingTools = this.tools.filter(t => t.status === 'executing')
  return (
    executingTools.length === 0                                   // 没人在跑 → 随便跑
    || (isConcurrencySafe && executingTools.every(t => t.isConcurrencySafe))
                                        // 或者：我安全 且 正在跑的全都安全
  )
}

private async processQueue(): Promise<void> {
  for (const tool of this.tools) {
    if (tool.status !== 'queued') continue
    if (this.canExecuteTool(tool.isConcurrencySafe)) {
      await this.executeTool(tool)
    } else {
      // 跑不了这个工具。而不安全的工具必须保序，所以直接停在这里，
      // 不去尝试它后面的工具
      if (!tool.isConcurrencySafe) break
    }
  }
}

类注释总结了三条规则：

5.6 兄弟中止控制器：最漂亮的一处设计

// Child of toolUseContext.abortController. Fires when a Bash tool errors
// so sibling subprocesses die immediately instead of running to completion.
// Aborting this does NOT abort the parent — query.ts won't end the turn.
private siblingAbortController: AbortController

constructor(...) {
  this.siblingAbortController = createChildAbortController(
    toolUseContext.abortController      // ★ 父控制器
  )
}

译：这是主中止控制器的一个子控制器。当某个 Bash 工具出错时触发它，让同批的兄弟子进程立刻死掉，而不是白白跑到结束。中止这个子控制器不会中止父控制器 —— 所以主循环不会结束本轮。

5.7 丢弃机制

/**
 * Discards all pending and in-progress tools. Called when streaming fallback
 * occurs and results from the failed attempt should be abandoned.
 * Queued tools won't start, and in-progress tools will receive synthetic errors.
 */
discard(): void {
  this.discarded = true
}

译：丢弃所有待定和进行中的工具。在流式请求失败回退时调用，此时失败那次尝试的结果应该被抛弃。排队中的工具不会启动，进行中的工具会收到合成的错误结果。

这个方法在两个地方被调用，而且两处的处理完全一样：

// 场景 1：流式请求失败，退回非流式重试
if (streamingFallbackOccured) {
  for (const msg of assistantMessages) yield { type:'tombstone', message: msg }
  logEvent('tengu_orphaned_messages_tombstoned', { orphanedMessageCount: ... })
  assistantMessages.length = 0; toolResults.length = 0; toolUseBlocks.length = 0
  if (streamingToolExecutor) {
    streamingToolExecutor.discard()
    streamingToolExecutor = new StreamingToolExecutor(...)    // ★ 重建一个新的
  }
}

// 场景 2：模型降级切换备用模型（见第 3.7 节）
// 同样的四步：打墓碑、清数组、丢弃执行器、重建

注释解释了为什么要重建而不是复用：

5.8 「墓碑」消息

上面出现了一个新概念：tombstone（墓碑）。它是一种控制信号消息，意思是「请从界面和对话记录里删除这条消息」。

yield { type: 'tombstone' as const, message: msg }

为什么需要它？注释说明：

场景是：流式请求失败时，模型已经吐出了一部分内容，界面上也已经显示出来了。这些内容不能留着 —— 它们不完整、签名无效。所以要发一个墓碑把它们撤回。

这个设计对流式界面很重要：你已经把东西画到屏幕上了，现在需要一个「撤回」机制。而且撤回要同时作用于界面和落盘的记录。

5.9 结果的最终处理

工具执行完之后，结果还要经过两道处理才能回传给模型：

① 超限落盘

每个工具声明了 maxResultSizeChars。超限的结果被写到磁盘，模型收到的是「前 2000 字节预览 + 文件路径」。详见第 6.2 节。

② 序列化

mapToolResultToToolResultBlockParam(content: Output, toolUseID: string): ToolResultBlockParam

每个工具自己决定「我的输出该怎么变成给模型看的文字」。比如 Read 工具会加上行号，Bash 工具会分开标记标准输出和标准错误。

注意 Tool 接口里还有一个专门为对话记录搜索服务的方法：

/**
 * Flattened text of what renderToolResultMessage shows IN TRANSCRIPT MODE.
 * For transcript search indexing: the index counts occurrences in this string,
 * the highlight overlay scans the actual screen buffer. For count ≡ highlight,
 * this must return the text that ends up visible — not the model-facing
 * serialization from mapToolResultToToolResultBlockParam.
 *
 * Phantoms are not fine — text that's claimed here but doesn't render is a
 * count≠highlight bug.
 */
extractSearchText?(out: Output): string

译：这个方法返回「在对话记录模式下实际渲染出来的文字」的扁平化版本。用于搜索索引：索引统计这个字符串里的出现次数，而高亮层扫描的是真实的屏幕缓冲区。为了让「统计数」和「高亮数」相等，这里必须返回最终可见的文字 —— 而不是给模型看的那个序列化结果。……幽灵文本是不可接受的 —— 在这里声称存在但实际没渲染出来的文字，就是一个「统计数 ≠ 高亮数」的 bug。