工具执行完整流程

职责概述

工具执行是 Claude Code 的核心能力通道。当模型返回 tool_use block 后，系统需要完成工具匹配、参数校验、权限检查、Hook 前置/后置处理、并发控制、结果处理等一系列步骤。本页完整追踪这一端到端流程，涵盖正常路径、错误路径、重试逻辑和并发安全机制。

架构设计

工具执行涉及五个层级，自上而下协作完成一次调用：

核心数据流

以下是工具执行的完整流程，包含决策点和错误路径：

错误与重试路径

关键类型与接口

Tool 核心接口

// Tool.ts:362 — 工具类型定义
export type Tool<
  Input extends AnyObject = AnyObject,
  Output = unknown,
  P extends ToolProgressData = ToolProgressData,
> = {
  readonly name: string
  aliases?: string[]
  call(
    args: z.infer<Input>,
    context: ToolUseContext,
    canUseTool: CanUseToolFn,
    parentMessage: AssistantMessage,
    onProgress?: ToolCallProgress<P>,
  ): Promise<ToolResult<Output>>
  isConcurrencySafe(input: z.infer<Input>): boolean
  isReadOnly(input: z.infer<Input>): boolean
  isDestructive?(input: z.infer<Input>): boolean
  maxResultSizeChars: number
  interruptBehavior?(): 'cancel' | 'block'
}

工具匹配函数

// Tool.ts:348-360 — 工具查找
export function toolMatchesName(
  tool: Tool, name: string,
): boolean {
  return tool.name === name ||
    tool.aliases?.includes(name) === true
}

export function findToolByName(
  tools: Tools, name: string,
): Tool | undefined {
  return tools.find(t => toolMatchesName(t, name))
}

ToolUseContext 执行上下文

// Tool.ts:158-300 — 工具执行上下文
export type ToolUseContext = {
  options: {
    tools: Tools
    mainLoopModel: string
    isNonInteractiveSession: boolean
    thinkingConfig: ThinkingConfig
    mcpClients: Map<string, MCPServerConnection>
    // ...更多选项
  }
  agentId?: string
  abortController: AbortController
  setAppState: (updater: (prev: AppState) => AppState) => void
  getAppState: () => AppState
  readFileState: FileStateCache
  contentReplacementState?: ContentReplacementState
  setResponseLength: (updater: (prev: number) => number) => void
  // ...更多字段
}

Hook 结果类型

// hooks.ts — Hook 执行结果
export type HookResult = {
  hook: HookCommand
  outcome: 'success' | 'blocking' | 'cancelled'
      | 'non_blocking_error'
  message?: AttachmentMessage
  blockingError?: { blockingError: string; command: string }
  preventContinuation?: boolean
  stopReason?: string
}

Hook 事件元数据（部分）

// hookEvents.ts:27-99 — Hook 事件定义
PreToolUse: {
  summary: 'Before tool execution',
  matcherMetadata: {
    fieldToMatch: 'tool_name',
    values: toolNames,  // 动态填充所有注册工具名
  },
},
PostToolUse: {
  summary: 'After tool execution',
  matcherMetadata: { fieldToMatch: 'tool_name', values: toolNames },
},
PostToolUseFailure: {
  summary: 'After tool execution fails',
  matcherMetadata: { fieldToMatch: 'tool_name', values: toolNames },
},
PermissionDenied: {
  summary: 'After auto mode classifier denies a tool call',
  // 可返回 {"retry": true} 让模型重试
},
PermissionRequest: {
  summary: 'When a permission dialog is displayed',
  // 可返回 decision: allow/deny 覆盖用户选择
}

设计模式与亮点

// 四种 Hook 类型
type HookCommand =
  | { type: 'command'; command: string; timeout?: number }
  | { type: 'http'; url: string; headers?: Record<string, string> }
  | { type: 'prompt'; prompt: string; model?: string }
  | { type: 'agent'; prompt: string; model?: string; timeout?: number }

代码索引