第9章：工具执行链 —— 一次调用要过多少道关

模型吐出 tool_use block
  ↓
① 找工具（找不到就试别名 → 还找不到就返回错误结果）
  ↓
② 中断检查
  ↓
③ Zod schema 校验          ← 失败：返回错误 + 「schema 没发」诊断
  ↓
④ tool.validateInput()      ← 失败：返回错误
  ↓
⑤ Bash 分类器预热（并发启动，不等）
  ↓
⑥ 剥掉内部字段（防御性）
  ↓
⑦ backfillObservableInput → 克隆一份「观察者输入」
  ↓
⑧ PreToolUse 钩子（可产出 7 种结果）
  ↓
⑨ 开 span / 遥测计时
  ↓
⑩ resolveHookPermissionDecision → 权限决策
  ↓
   ├─ 非 allow → 记录、组装拒绝消息、跑 PermissionDenied 钩子 → 返回
  ↓
⑪ 用权限返回的 updatedInput 覆盖输入
  ↓
⑫ callInput 收敛（决定 call() 到底拿哪一份）
  ↓
⑬ tool.call()               ← 抛异常：走失败分支
  ↓
⑭ 结果处理 → PostToolUse 钩子 → 组装消息

let tool = findToolByName(toolUseContext.options.tools, toolName)

// If not found, check if it's a deprecated tool being called by alias
// (e.g., old transcripts calling "KillShell" which is now an alias for "TaskStop")
// Only fall back for tools where the name matches an alias, not the primary name
if (!tool) {
  const fallbackTool = findToolByName(getAllBaseTools(), toolName)
  if (fallbackTool && fallbackTool.aliases?.includes(toolName)) {
    tool = fallbackTool
  }
}

yield {
  message: createUserMessage({
    content: [{ type: 'tool_result', content: `<tool_use_error>Error: No such tool available: ${toolName}</tool_use_error>`, is_error: true, tool_use_id: toolUse.id }],
    toolUseResult: `Error: No such tool available: ${toolName}`,
  }),
}

// Validate input types with zod (surprisingly, the model is not great at generating valid input)
const parsedInput = tool.inputSchema.safeParse(input)

/**
 * Determines if this tool is allowed to run with this input in the current context.
 * It informs the model of why the tool use failed, and does not directly display any UI.
 */
validateInput?(input, context): Promise<ValidationResult>

/**
 * Determines if the user is asked for permission. Only called after validateInput() passes.
 * General permission logic is in permissions.ts. This method contains tool-specific logic.
 */
checkPermissions(input, context): Promise<PermissionResult>

// 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"
// for commands that auto-allow via prefix rules.
if (tool.name === BASH_TOOL_NAME && 'command' in parsedInput.data) {
  startSpeculativeClassifierCheck(
    (parsedInput.data as BashToolInput).command,
    appState.toolPermissionContext,
    toolUseContext.abortController.signal,
    toolUseContext.options.isNonInteractiveSession,
  )
}

AsyncGenerator<
  | { type: 'message'; message: … }                                  // 普通消息
  | { type: 'hookPermissionResult'; hookPermissionResult: PermissionResult }  // 权限决定
  | { type: 'hookUpdatedInput'; updatedInput: Record<string, unknown> }       // 改写输入
  | { type: 'preventContinuation'; shouldPreventContinuation: boolean }       // 阻止继续
  | { type: 'stopReason'; stopReason: string }                       // 停止理由
  | { type: 'additionalContext'; message: … }                        // 追加上下文
  // stop execution ↓
  | { type: 'stop' }                                                 // 直接中止
>

switch (result.type) {
  case 'message': …                                       // 累积到结果消息
  case 'hookPermissionResult': hookPermissionResult = …   // 存下来给第 ⑩ 步
  case 'hookUpdatedInput': processedInput = result.updatedInput   // 直接改写
  case 'preventContinuation': shouldPreventContinuation = …
  case 'stopReason': stopReason = …
  case 'additionalContext': …
  case 'stop':
    // 立刻返回一条 tool_result stop 消息，工具根本不执行
    return resultingMessages
}

const preToolHookDurationMs = Date.now() - preToolHookStart
getStatsStore()?.observe('pre_tool_hook_duration_ms', preToolHookDurationMs)
if (preToolHookDurationMs >= SLOW_PHASE_LOG_THRESHOLD_MS) {
  logForDebugging(`Slow PreToolUse hooks: ${preToolHookDurationMs}ms for ${tool.name} (${preToolHookInfos.length} hooks)`, { level: 'info' })
}

/** Minimum total hook duration (ms) to show inline timing summary */
export const HOOK_TIMING_DISPLAY_THRESHOLD_MS = 500
/** Log a debug warning when hooks/permission-decision block for this long. Matches
 * BashTool's PROGRESS_THRESHOLD_MS — the collapsed view feels stuck past this. */
const SLOW_PHASE_LOG_THRESHOLD_MS = 2000

if (hookPermissionResult?.behavior === 'allow') {
  const hookInput = hookPermissionResult.updatedInput ?? input

  // Hook provided updatedInput for an interactive tool — the hook IS the
  // user interaction (e.g. headless wrapper that collected AskUserQuestion
  // answers). Treat as non-interactive for the rule-check path.
  const interactionSatisfied = requiresInteraction && hookPermissionResult.updatedInput !== undefined

  if ((requiresInteraction && !interactionSatisfied) || requireCanUseTool) {
    // 工具本来就需要真人交互，而钩子没提供答案 → 还是得走正常流程
    return { decision: await canUseTool(…), input: hookInput }
  }

  // Hook allow skips the interactive prompt, but deny/ask rules still apply.
  const ruleCheck = await checkRuleBasedPermissions(tool, hookInput, toolUseContext)
  if (ruleCheck === null) {
    return { decision: hookPermissionResult, input: hookInput }     // 没有规则拦 → 钩子说了算
  }
  if (ruleCheck.behavior === 'deny') {
    // Hook approved tool use, but deny rule overrides
    return { decision: ruleCheck, input: hookInput }                // deny 规则赢
  }
  // ask rule — dialog required despite hook approval
  return { decision: await canUseTool(…), input: hookInput }        // ask 规则赢
}

if (hookPermissionResult?.behavior === 'deny') {
  return { decision: hookPermissionResult, input }                  // 钩子 deny 直接生效
}

// 没有钩子决定，或者钩子说 ask → 正常流程，但把钩子的 ask 消息透传下去
const forceDecision = hookPermissionResult?.behavior === 'ask' ? hookPermissionResult : undefined
return { decision: await canUseTool(…, forceDecision), input: askInput }

function decisionReasonToOTelSource(reason, behavior): string {
  switch (reason.type) {
    case 'permissionPromptTool': {
      // SDK host 可以直接告诉我们是「这次允许」还是「永久允许」还是「缓存命中」
      const classified = reason.toolResult?.decisionClassification
      if (classified === 'user_temporary' || classified === 'user_permanent' || classified === 'user_reject') return classified
      return behavior === 'allow' ? 'user_temporary' : 'user_reject'   // 保守兜底
    }
    case 'rule': return ruleSourceToOTelSource(reason.rule.source, behavior)
    case 'hook': return 'hook'
    case 'mode': case 'classifier': case 'subcommandResults': case 'asyncAgent':
    case 'sandboxOverride': case 'workingDir': case 'safetyCheck': case 'other':
      return 'config'
    default: { const _exhaustive: never = reason; return 'config' }
  }
}

// If processedInput still points at the backfill clone, no hook/permission
// replaced it — pass the pre-backfill callInput so call() sees the model's
// original field values. Otherwise converge on the hook-supplied input.
// Permission/hook flows may return a fresh object derived from the
// backfilled clone (e.g. via inputSchema.parse). If its file_path matches
// the backfill-expanded value, restore the model's original so the tool
// result string embeds the path the model emitted — keeps transcript/VCR
// hashes stable. Other hook modifications flow through unchanged.
if (backfilledClone && processedInput !== callInput
    && 'file_path' in processedInput && 'file_path' in callInput
    && processedInput.file_path === backfilledClone.file_path) {
  callInput = { ...processedInput, file_path: callInput.file_path }
} else if (processedInput !== backfilledClone) {
  callInput = processedInput
}

async function addToolResult(toolUseResult, preMappedBlock?) {
  const toolResultBlock = preMappedBlock
    ? await processPreMappedToolResultBlock(preMappedBlock, tool.name, tool.maxResultSizeChars)
    : await processToolResultBlock(tool, toolUseResult, toolUseID)

  const contentBlocks: ContentBlockParam[] = [toolResultBlock]

  // Add accept feedback if user provided feedback when approving
  if ('acceptFeedback' in permissionDecision && permissionDecision.acceptFeedback) {
    contentBlocks.push({ type: 'text', text: permissionDecision.acceptFeedback })
  }
  // Add content blocks (e.g., pasted images) from the permission decision
  …
}

toolUseResult: toolUseContext.agentId && !toolUseContext.preserveToolUseResults
  ? undefined
  : toolUseResult,
mcpMeta: toolUseContext.agentId ? undefined : mcpMeta,

// TOOD(hackyon): refactor so we don't have different experiences for MCP tools
if (!isMcpTool(tool)) {
  await addToolResult(toolOutput, mappedToolResultBlock)
}

} catch (error) {
  // MCP 认证错误 → 把客户端状态改成 needs-auth，/mcp 面板会显示要重新授权
  if (error instanceof McpAuthError) { toolUseContext.setAppState(…) }

  if (!(error instanceof AbortError)) {
    // 打日志、打点、发 OTel —— 但 AbortError 不打，因为那是用户主动中断
    if (!(error instanceof ShellError)) logError(error)   // shell 出错不算异常
    logEvent('tengu_tool_use_error', { error: classifyToolError(error), … })
    void logOTelEvent('tool_result', { success: 'false', … })
  }

  const content = formatError(error)
  const isInterrupt = error instanceof AbortError

  // PostToolUseFailure 钩子
  for await (const hookResult of runPostToolUseFailureHooks(…, isInterrupt, …)) { … }

  return [{ message: createUserMessage({ content: [{ type: 'tool_result', content, is_error: true, … }] }) }, ...hookMessages]
} finally {
  stopSessionActivity('tool_exec')
  if (decisionInfo) toolUseContext.toolDecisions?.delete(toolUseID)
}

/**
 * Classify a tool execution error into a telemetry-safe string.
 *
 * In minified/external builds, `error.constructor.name` is mangled into
 * short identifiers like "nJT" or "Chq" — useless for diagnostics.
 * This function extracts structured, telemetry-safe information instead:
 * - TelemetrySafeError: use its telemetryMessage (already vetted)
 * - Node.js fs errors: log the error code (ENOENT, EACCES, etc.)
 * - Known error types: use their unminified name
 * - Fallback: "Error" (better than a mangled 3-char identifier)
 */
export function classifyToolError(error: unknown): string

cd claude-code-deep-dive/extracted-source

# 1. 主入口与前四道关
sed -n '337,500p' src/services/tools/toolExecution.ts
sed -n '599,760p' src/services/tools/toolExecution.ts

# 2. PreToolUse 钩子的七种结果
sed -n '795,895p' src/services/tools/toolExecution.ts
sed -n '435,470p' src/services/tools/toolHooks.ts

# 3. 钩子权限 × 规则权限 的真值表
sed -n '332,433p' src/services/tools/toolHooks.ts

# 4. 三份输入的收敛
sed -n '1178,1210p' src/services/tools/toolExecution.ts

# 5. 成功/失败两条尾巴
sed -n '1395,1500p' src/services/tools/toolExecution.ts
sed -n '1588,1745p' src/services/tools/toolExecution.ts

# 6. 错误分类的三级降级
sed -n '139,172p' src/services/tools/toolExecution.ts

# 7. 那两个把安全声明写进名字的类型
grep -rn 'I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS' src/ | wc -l

# 打开 OTel 导出后能看到 tool_decision / tool_result 事件
# 参数详情默认关闭，需要显式打开（可能含敏感内容）
OTEL_LOG_TOOL_DETAILS=1 claude