4 · 工具模型

这一章讲「一个工具」在程序里被建模成什么样子，以及 40 个内建工具是怎么被组织和投放的。

4.1 Tool 接口：七组正交能力

Tool.ts 全文 793 行，其中类型定义 Tool<Input, Output, Progress> 占了 330 行。它把「一个工具需要回答的所有问题」切成了七组互不重叠的能力：

4.2 为什么「安全谓词」值得单独成组

因为这一组不是给人看的，是给调度器看的。调度器完全不认识任何具体工具 —— 它不知道什么是 Bash、什么是 Read，它只会问这几个布尔问题，然后据此安排执行：

一个容易被忽略的细节：谓词接收参数

isConcurrencySafe(input) 是接收参数的方法，不是一个静态标记。

同一个 Bash 工具：执行 ls（列文件）是并发安全的，执行 rm -rf（删除）就不安全。安全性取决于这次具体要做什么，而不取决于工具类型。如果建模成静态标记，Bash 工具就只能永远声明「我不安全」，从而失去所有并行机会。

4.3 失败保守默认值

所有工具都通过一个工厂函数创建：

const TOOL_DEFAULTS = {
  isEnabled:          () => true,
  isConcurrencySafe:  () => false,   // ← 默认"不能并行"
  isReadOnly:         () => false,   // ← 默认"会写入"
  isDestructive:      () => false,
  checkPermissions:   (input) => ({ behavior:'allow', updatedInput: input }),
  toAutoClassifierInput: () => '',   // ← 默认"跳过安全分类器"
  userFacingName:     () => '',
}

export function buildTool<D>(def: D): BuiltTool<D> {
  return { ...TOOL_DEFAULTS,               // 先铺默认值
           userFacingName: () => def.name,
           ...def }                        // 再用工具自己的定义覆盖
}

claude-code/src/Tool.ts

源码注释总结了设计原则：「Defaults (fail-closed where it matters)」（默认值在重要的地方倒向保守）。

唯一一个看起来违反原则的默认值

toAutoClassifierInput 默认返回空字符串，意思是「这个工具不进安全分类器的视野」。注释解释了原因：

4.4 40 个内建工具分类

工具清单是条件组装的

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    // 内部原生构建版把快速搜索程序内嵌进了可执行文件，
    // shell 里的 find/grep 被别名指向它们，所以不需要独立的 Glob/Grep 工具
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ExitPlanModeV2Tool,
    FileReadTool, FileEditTool, FileWriteTool, NotebookEditTool,
    WebFetchTool, TodoWriteTool, WebSearchTool, TaskStopTool,
    AskUserQuestionTool, SkillTool, EnterPlanModeTool,
    ...(process.env.USER_TYPE === 'ant' ? [ConfigTool] : []),      // 只给内部用户
    ...(isTodoV2Enabled() ? [TaskCreateTool, TaskGetTool, ...] : []),
    ...(isEnvTruthy(process.env.ENABLE_LSP_TOOL) ? [LSPTool] : []),
    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),
    ...(isAgentSwarmsEnabled() ? [getTeamCreateTool(), getTeamDeleteTool()] : []),
    ...cronTools,
    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),
  ]
}

三种条件维度：编译期特性开关（feature('XXX')）、运行时环境变量、用户类型（内部 / 外部）。第 13 章会讲编译期开关怎么做到「外部版本里这些代码根本不存在」。

4.5 渐进式工具加载

问题

每个工具的完整说明文字都要放进系统提示词，而系统提示词每一轮都要重发。用户接了十几个 MCP 外部服务时，工具总数可能上百个，说明文字加起来几万 token —— 每轮都付一遍。

解法：defer_loading（延迟加载）

相关的两个字段：

• shouldDefer: true —— 这个工具延迟加载
• alwaysLoad: true —— 永不延迟。用于模型在第一轮就必须看到的工具。MCP 外部工具可以在服务端通过 _meta['anthropic/alwaysLoad'] 声明

关键词的写法规范

延迟加载失败时的补救

延迟加载有一个副作用：模型可能凭记忆调用一个它还没加载完整说明的工具，参数写错了。所以参数校验失败时有一个特殊提示：

const schemaHint = buildSchemaNotSentHint(tool, toolUseContext.messages,
                                          toolUseContext.options.tools)
if (schemaHint) {
  logEvent('tengu_deferred_tool_schema_not_sent', {
    toolName: sanitizeToolNameForAnalytics(tool.name), isMcp: tool.isMcp ?? false })
  errorContent += schemaHint    // 追加提示："你还没加载这个工具的说明，先搜一下"
}

而且这个情况专门有埋点（tengu_deferred_tool_schema_not_sent）—— 说明他们在监控「延迟加载导致的调用失败率」，用来判断这个优化的净收益。

4.6 工具清单装配：一个关于缓存的隐藏约束

这段代码只有 8 行，但它揭示的东西非常值钱：

export function assembleToolPool(permissionContext, mcpTools): Tools {
  const builtInTools    = getTools(permissionContext)               // 内建工具
  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)

  const byName = (a, b) => a.name.localeCompare(b.name)
  return uniqBy(
    [...builtInTools].sort(byName)             // ★ 内建工具单独排序
      .concat(allowedMcpTools.sort(byName)),   // ★ 外部工具单独排序后拼在后面
    'name',                                    // 按名字去重，内建优先
  )
}

claude-code/src/tools.ts

注意：两组是分别排序后拼接的，不是合并成一个大数组统一排序。对不了解缓存机制的人来说，这看起来是多余的复杂化。源码注释给出了答案：

这件事有多严重

同一个文件里还有一行注释：

/**
 * NOTE: This MUST stay in sync with
 * https://console.statsig.com/.../claude_code_global_system_caching,
 * in order to cache the system prompt across users.
 */
export function getAllBaseTools(): Tools { ... }

译：注意：这个函数必须和某个线上配置保持同步，才能让系统提示词在所有用户之间共享缓存。

4.7 backfillObservableInput：一个极致的缓存保护例子

有时工具需要给日志、钩子、开发工具包补充一些派生字段（比如把相对路径展开成绝对路径）。但那个要发回接口的原始参数对象绝对不能改 —— 改一个字节，缓存就没了。

/**
 * Called on copies of tool_use input before observers see it (SDK stream,
 * transcript, canUseTool, PreToolUse/PostToolUse hooks). Mutate in place
 * to add legacy/derived fields. Must be idempotent. The original API-bound
 * input is never mutated (preserves prompt cache).
 */
backfillObservableInput?(input: Record<string, unknown>): void

调用处的实现更讲究：

const originalInput = block.input as Record<string, unknown>
const inputCopy = { ...originalInput }        // 克隆
tool.backfillObservableInput(inputCopy)       // 只改克隆体

// ★ 只有当补充操作"新增了字段"时才产生克隆版消息；
//   如果只是覆写了已有字段，连克隆都不做
const addedFields = Object.keys(inputCopy).some(k => !(k in originalInput))
if (addedFields) {
  clonedContent ??= [...message.message.content]
  clonedContent[i] = { ...block, input: inputCopy }
}

为什么「只覆写已有字段」就不克隆？注释解释了：

这个级别的克制程度，能说明「保护缓存」在这个系统里是一等公民约束 —— 甚至连一个可能影响测试固件的字段覆写都要避免。