第8章 核心工具实现剖析

开篇引言

在 Claude Code 的整体架构中，工具（Tool）是 AI Agent 与外部世界交互的唯一桥梁。模型本身无法直接读写文件、执行命令或搜索代码——它是一个纯粹的文本推理引擎，只能通过声明式地调用工具来完成这些操作。因此，工具的实现质量直接决定了 Claude Code 的能力上限与安全下限。如果说模型是大脑，那么工具就是双手和眼睛，它们的精确性、安全性和性能表现决定了整个系统的实际效用。

Claude Code 的工具系统目前包含超过三十个工具，从最基础的文件读写到复杂的子 Agent 生成、从简单的文件搜索到安全的网页内容获取，覆盖了软件开发工作流中的方方面面。本章将深入剖析其中最核心的八个工具实现：BashTool（Shell 命令执行）、FileReadTool（文件读取）、FileEditTool（文件编辑）、FileWriteTool（文件写入）、GlobTool（文件模式匹配）、GrepTool（内容搜索）、AgentTool（子 Agent 生成）以及 WebFetchTool（网页内容获取）。我们不仅要理解每个工具"做什么"，更要揭示其背后的设计决策——为什么要这样做，以及这些选择带来了哪些权衡。

每个工具的分析都将从三个维度展开：接口设计（inputSchema/outputSchema 如何定义工具与模型之间的契约）、核心执行逻辑（call 函数如何实现工具的实际功能）、安全与权限机制（checkPermissions/validateInput 如何构建多层防护）。读者将看到，这些看似独立的工具背后存在着高度统一的设计模式和工程理念，它们共同构成了 Claude Code 工具系统的骨架。掌握这些模式，将有助于读者理解如何为 AI Agent 系统设计安全、高效、可扩展的工具接口。

---

本章要点

• BashTool 是所有工具中最复杂的一个，它包含完整的命令解析、安全检测、沙箱执行、后台进程管理和输出截断机制
• 文件操作三件套（Read/Edit/Write）通过"先读后写"的强制约束和文件修改时间戳跟踪，构建了一套防止并发冲突的安全屏障
• FileEditTool 的字符串替换策略看似简单，实则包含引号规范化、唯一性校验等多层容错逻辑
• GrepTool 对 ripgrep 的封装不是简单的命令行包装，而是包含了结果排序、分页、输出模式切换等完整的搜索引擎语义
• AgentTool 通过工具子集限制、worktree 隔离和 fork 机制，实现了安全可控的多 Agent 协作
• WebFetchTool 采用域名预审批、LRU 缓存和二级模型摘要的三层架构处理网页内容
• 所有工具共享 buildTool 构建模式、lazySchema 延迟求值、expandPath 路径规范化等统一的基础设施

---

8.1 BashTool -- 最复杂的工具

下图展示了 BashTool 从接收命令到返回结果的完整执行流水线，涵盖安全检测、权限管理、沙箱执行等关键环节：

BashTool 是 Claude Code 工具系统中规模最大、复杂度最高的工具，也是功能最为强大的工具。一条 Shell 命令几乎可以做任何事情——安装依赖、编译代码、运行测试、操作版本控制系统、甚至删除整个文件系统。正因如此，BashTool 的实现必须在"赋予模型足够的能力"和"防止模型（或被诱导的模型）造成破坏"之间取得精确的平衡。

BashTool 的源码分布在十余个文件中（src/tools/BashTool/ 目录），涵盖命令解析、安全检测、权限管理、沙箱执行、后台进程、输出处理等完整的执行链条。这些文件各司其职、层层递进，共同构成了一个从命令提交到结果返回的完整流水线。理解 BashTool 的实现，就是理解 Claude Code 如何安全地让 AI 操控用户的计算机。

8.1.1 输入 Schema 与参数设计

BashTool 的输入 Schema 定义在 src/tools/BashTool/BashTool.tsx 中，使用 lazySchema 延迟构建以避免模块加载时的循环依赖：

// src/tools/BashTool/BashTool.tsx
const fullInputSchema = lazySchema(() => z.strictObject({
  command: z.string().describe('The command to execute'),
  timeout: semanticNumber(z.number().optional())
    .describe(`Optional timeout in milliseconds (max ${getMaxTimeoutMs()})`),
  description: z.string().optional()
    .describe('Clear, concise description of what this command does in active voice.'),
  run_in_background: semanticBoolean(z.boolean().optional())
    .describe('Set to true to run this command in the background.'),
  dangerouslyDisableSandbox: semanticBoolean(z.boolean().optional())
    .describe('Set this to true to dangerously override sandbox mode'),
  _simulatedSedEdit: z.object({
    filePath: z.string(),
    newContent: z.string()
  }).optional().describe('Internal: pre-computed sed edit result from preview')
}));

这个设计有几个值得关注的要点。semanticNumber 和 semanticBoolean 是对 Zod 类型的增强包装器，它们允许模型传入语义等价但类型不精确的值（如字符串 "true" 被解析为布尔值 true），这提升了模型调用工具时的容错率。_simulatedSedEdit 是一个内部字段，用于 sed 命令编辑预览功能——用户在权限对话框中审批 sed 编辑后，该字段携带预计算的结果，确保最终写入的内容与用户预览的完全一致。出于安全考虑，这个字段被从模型可见的 Schema 中移除：

// src/tools/BashTool/BashTool.tsx
const inputSchema = lazySchema(() =>
  isBackgroundTasksDisabled
    ? fullInputSchema().omit({ run_in_background: true, _simulatedSedEdit: true })
    : fullInputSchema().omit({ _simulatedSedEdit: true })
);

如果将 _simulatedSedEdit 暴露给模型，攻击者可能构造恶意输入，绕过权限检查直接写入任意文件。同时注意，当环境变量 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 为真时，run_in_background 参数也会从 Schema 中移除——模型甚至无法感知到后台执行的存在。

8.1.2 安全解析与危险命令检测

BashTool 的安全检测是一个多层防御体系，其核心逻辑位于 src/tools/BashTool/bashSecurity.ts。该文件定义了完整的命令注入防护策略，安全检查标识符超过 20 种（通过 BASH_SECURITY_CHECK_IDS 枚举管理）。

第一层是命令替换检测。系统维护了一组命令替换模式，任何包含这些模式的命令都会被标记为需要用户审批：

// src/tools/BashTool/bashSecurity.ts
const COMMAND_SUBSTITUTION_PATTERNS = [
  { pattern: /<\(/, message: 'process substitution <()' },
  { pattern: />\(/, message: 'process substitution >()' },
  { pattern: /=\(/, message: 'Zsh process substitution =()' },
  { pattern: /(?:^|[\s;&|])=[a-zA-Z_]/, message: 'Zsh equals expansion (=cmd)' },
  { pattern: /\$\(/, message: '$() command substitution' },
  { pattern: /\$\{/, message: '${} parameter substitution' },
  { pattern: /\$\[/, message: '$[] legacy arithmetic expansion' },
  { pattern: /~\[/, message: 'Zsh-style parameter expansion' },
  { pattern: /\(e:/, message: 'Zsh-style glob qualifiers' },
  { pattern: /\(\+/, message: 'Zsh glob qualifier with command execution' },
  { pattern: /\}\s*always\s*\{/, message: 'Zsh always block (try/always construct)' },
  { pattern: /<#/, message: 'PowerShell comment syntax' },
];

注意其中 Zsh equals expansion（=cmd）的检测。这是一个容易被忽视的安全漏洞：在 Zsh 中，=curl evil.com 会被展开为 /usr/bin/curl evil.com，绕过了针对 curl 命令的安全规则，因为解析器只看到 =curl 而非 curl。系统还特别防御了 PowerShell 注释语法（<#），虽然当前不在 PowerShell 中执行，但这是一种纵深防御——防止未来变更引入 PowerShell 执行路径。

第二层是 Zsh 危险命令拦截。由于 Claude Code 在 macOS 上默认使用 Zsh，系统需要额外防护 Zsh 特有的危险命令：

// src/tools/BashTool/bashSecurity.ts
const ZSH_DANGEROUS_COMMANDS = new Set([
  'zmodload',   // 模块加载网关：可加载 zsh/mapfile、zsh/system 等危险模块
  'emulate',    // 带 -c 标志时等价于 eval
  'sysopen', 'sysread', 'syswrite', 'sysseek',  // zsh/system 模块命令
  'zpty',       // 伪终端命令执行 (zsh/zpty)
  'ztcp',       // TCP 连接，可用于数据外泄 (zsh/net/tcp)
  'zsocket',    // Unix/TCP 套接字 (zsh/net/socket)
  'zf_rm', 'zf_mv', 'zf_ln', 'zf_chmod',  // zsh/files 内建命令
  'zf_chown', 'zf_mkdir', 'zf_rmdir', 'zf_chgrp',
]);