Builtin Tools

Claude Code 内置了 40 余个 tool，分为多个类别。每个 tool 以目录形式实现于 src/tools/ 下，包含 tool 定义、UI 组件和 prompt 文本。本章对所有 tool 进行分类说明，并阐述各类别的设计原理。

Tool 目录结构

每个 tool 遵循统一的文件布局：

src/tools/
├── BashTool/
│   ├── BashTool.tsx          # Tool definition (call, schema, permissions)
│   ├── UI.tsx                # Rendering components
│   ├── prompt.ts             # System prompt for the tool
│   ├── toolName.ts           # Exported name constant
│   ├── bashPermissions.ts    # Permission logic
│   ├── bashSecurity.ts       # Security checks
│   └── commandSemantics.ts   # Command classification
├── FileReadTool/
│   ├── FileReadTool.ts
│   ├── UI.tsx
│   ├── prompt.ts
│   └── limits.ts
└── ...

类别总览

mindmap
  root((Tools))
    File Operations
      FileRead
      FileWrite
      FileEdit
      NotebookEdit
    Search & Discovery
      Glob
      Grep
      ToolSearch
      LSP
    Execution
      Bash
      PowerShell
      REPL
    Agent & Task
      Agent
      TaskCreate
      TaskGet
      TaskList
      TaskOutput
      TaskStop
      TaskUpdate
    Communication
      AskUserQuestion
      SendMessage
      Brief
    Web
      WebSearch
      WebFetch
    Meta & Config
      TodoWrite
      Config
      Skill
    Plan & Workflow
      EnterPlanMode
      ExitPlanMode
      EnterWorktree
      ExitWorktree
    MCP
      MCPTool
      McpAuth
      ListMcpResources
      ReadMcpResource
    Team
      TeamCreate
      TeamDelete
    Background
      Sleep
      ScheduleCron
      RemoteTrigger
      SyntheticOutput

文件操作

FileRead

路径：src/tools/FileReadTool/FileReadTool.ts

从本地文件系统读取文件。支持：

带行号的文本文件（cat -n 格式）
图片（PNG、JPG）——以 base64 返回，用于多模态处理
PDF——逐页文本 + 视觉提取
Jupyter notebook（.ipynb）——所有单元格及其输出
偏移量/限制参数，支持分块读取大文件

inputSchema: z.object({
  file_path: z.string(),
  offset: z.number().optional(),
  limit: z.number().optional(),
})

设计：maxResultSizeChars: Infinity——结果永不持久化，因为该 tool 已通过 limits.ts 自行控制大小，从而避免 Read→file→Read 的循环。

FileWrite

路径：src/tools/FileWriteTool/FileWriteTool.ts

写入完整文件内容。如有需要会创建父目录。记录新增/删除的行数用于费用展示。

设计：需要 permission 检查。非并发（有副作用）。在 TUI 中显示差异预览。

FileEdit

路径：src/tools/FileEditTool/FileEditTool.ts

对文件执行精确字符串替换。old_string → new_string 模式确保精准编辑，无需依赖行号（行号可能发生漂移）。

inputSchema: z.object({
  file_path: z.string(),
  old_string: z.string(),
  new_string: z.string(),
  replace_all: z.boolean().default(false),
})

设计：若 old_string 在文件中不唯一（且 replace_all 为 false），编辑将失败。此约束防止意外编辑错误位置。

NotebookEdit

路径：src/tools/NotebookEditTool/NotebookEditTool.ts

按索引编辑 Jupyter notebook 单元格。支持替换、插入和删除操作。

设计：默认延迟加载（shouldDefer: true）——仅当模型通过 ToolSearch 发现它时才加载。searchHint: 'jupyter' 有助于发现。

搜索与发现

Glob

路径：src/tools/GlobTool/GlobTool.ts

使用 glob 模式（如 **/*.ts）进行快速文件匹配。返回按修改时间排序的匹配文件路径。

设计：并发安全（只读）。结果数量上限为 globLimits.maxResults。

Grep

路径：src/tools/GrepTool/GrepTool.ts

基于 ripgrep 的内容搜索。支持正则表达式、文件类型过滤、上下文行数以及多种输出模式（content、files_with_matches、count）。

设计：并发安全。ripgrep 二进制文件与 Claude Code 捆绑，确保跨平台行为一致。

ToolSearch

路径：src/tools/ToolSearchTool/

通过关键词搜索可用 tool 列表。实现延迟加载模式——带有 shouldDefer: true 的 tool 仅在通过此 tool 发现后才完整加载。

LSP

路径：src/tools/LSPTool/LSPTool.ts

Language Server Protocol 集成。提供语义代码智能（跳转定义、查找引用、诊断）。仅在 LSP 服务器已连接时启用（IDE 集成）。

执行

Bash

路径：src/tools/BashTool/BashTool.tsx

最复杂的 builtin tool。在持久化 session 中执行 shell 命令，具备：

超时管理
沙箱模式（macOS Seatbelt、Linux Landlock）
安全命令分类（破坏性检测）
大结果的输出截断
sed 验证，防止意外文件损坏

inputSchema: z.object({
  command: z.string(),
  timeout: z.number().optional(),
  description: z.string().optional(),
})

设计：非并发。在 StreamingToolExecutor 中，只有 Bash 错误才会触发兄弟取消——原因是 Bash 命令通常形成隐式依赖链。

PowerShell

路径：src/tools/PowerShellTool/

通过 PowerShell 执行 Windows 专用命令。在 Windows 平台上作为 Bash 的替代方案。

REPL

路径：src/tools/REPLTool/

一个”透明包装器”，委托给其他 tool 执行。在模型可以链式调用多个 tool 的交互式 REPL 循环中内部使用。

Agent 与任务系统

Agent（Sub-agent）

路径：src/tools/AgentTool/AgentTool.tsx

生成一个拥有独立对话 context 的 sub-agent。sub-agent 运行嵌套的 query() 循环并返回摘要。

设计：支持以下几种内置 agent 类型：

generalPurposeAgent——通用任务处理
exploreAgent——代码探索
planAgent——规划
verificationAgent——验证
claudeCodeGuideAgent——帮助/文档

任务管理（TaskCreate、TaskGet、TaskList、TaskOutput、TaskStop、TaskUpdate）

路径：src/tools/Task*Tool/

用于管理后台任务的 tool 族。任务作为独立进程运行，可以被监控、更新或停止。

Tool	用途
`TaskCreate`	启动新的后台任务
`TaskGet`	检查任务状态
`TaskList`	列出所有任务
`TaskOutput`	读取任务输出
`TaskStop`	终止任务
`TaskUpdate`	向运行中的任务发送更新

通信

AskUserQuestion

路径：src/tools/AskUserQuestionTool/AskUserQuestionTool.tsx

向用户提问并获取输入。将用户回复作为 tool result 返回。

设计：requiresUserInteraction: () => true——hook 可通过在 PreToolUse hook 响应中提供 updatedInput 来满足此交互。

SendMessage

路径：src/tools/SendMessageTool/

在 multi-agent 场景中向其他 agent 发送消息。

Brief

路径：src/tools/BriefTool/BriefTool.ts

创建带有可选文件附件和上传的简报/报告。

Web

WebSearch

路径：src/tools/WebSearchTool/

使用 Anthropic 服务端 web 搜索 tool 执行网络搜索。返回带摘要和链接的搜索结果。

WebFetch

路径：src/tools/WebFetchTool/

从 URL 获取内容，将 HTML 转换为 markdown，并使用小型模型进行摘要处理。

元数据与配置

TodoWrite

路径：src/tools/TodoWriteTool/TodoWriteTool.ts

创建并管理显示在 TUI 侧边栏中的结构化任务列表。用于追踪多步骤任务。

设计：renderToolResultMessage 返回 null——结果显示在 todo 面板中，而非对话记录里。

Config

路径：src/tools/ConfigTool/ConfigTool.ts

查看和修改 Claude Code 设置。支持 supportedSettings.ts 中定义的一组配置项。

Skill

路径：src/tools/SkillTool/

调用已注册的 skill（专业能力）。skill 可通过 ToolSearch 发现或直接引用。

计划与工作流

EnterPlanMode / ExitPlanMode

路径：src/tools/EnterPlanModeTool/、src/tools/ExitPlanModeTool/

在计划模式（只读，不写入）和普通模式之间切换。计划模式将可用 tool 限制为只读操作。

设计：使用 contextModifier 修改 ToolPermissionContext.mode——这正是 ToolResult 类型上存在 context modifier 的原因。

EnterWorktree / ExitWorktree

路径：src/tools/EnterWorktreeTool/、src/tools/ExitWorktreeTool/

Git worktree 管理。创建并切换 worktree，支持并行开发工作流。

MCP Tools

MCPTool

路径：src/tools/MCPTool/MCPTool.ts

将 MCP 服务器 tool 适配为 Claude Code Tool interface 的通用包装器。在 MCP 服务器连接时动态创建。

McpAuth、ListMcpResources、ReadMcpResource

用于认证、资源发现和资源读取的 MCP 基础设施 tool。

命名规范

规范	示例	用途
`PascalCase` 目录	`BashTool/`	Tool 目录名
`PascalCase` 类	`BashTool`	导出的 tool 名称
`camelCase` 文件	`toolName.ts`	辅助模块
`mcp__server__tool`	`mcp__github__create_issue`	MCP tool 命名

关键实现模式

Prompt 分离

每个 tool 将其 system prompt 分离到专属的 prompt.ts 文件中：

export async function getBashPrompt(options: {...}): Promise<string> {
  return `You have access to a Bash tool for terminal operations...`;
}

这种模式使 prompt 可以：

懒加载（仅在 tool 被使用时）
独立测试
根据 context 动态生成

进度上报

Tool 可通过 onProgress 回调在执行期间上报进度：

async call(args, context, canUseTool, parentMessage, onProgress) {
  onProgress?.({
    toolUseID: context.toolUseId!,
    data: { type: 'bash_progress', output: 'Running tests...' },
  });
  // ... execute ...
}

进度消息会立即提交给 UI（不缓冲），实现实时状态更新。

分组渲染

常并发运行的 tool（如 Grep、Glob）可以实现 renderGroupedToolUse，以展示精简视图：

Searched 5 files with Grep  [3 results, 2 no match]

而非显示 5 个独立的 tool 使用/结果块。