附录 B：工具完整清单

本附录列出 Claude Code 架构中注册的全部工具，按功能分类索引。工具是智能体与外部世界交互的基本能力单元，每个工具都通过统一的接口协议注册到工具注册表中，接受对话主循环的调度。

权限模型字段含义：

readOnly：工具是否仅执行读取操作，不修改文件系统或外部状态。只读工具通常权限约束更宽松，在 plan 模式下也可使用
destructive：工具是否执行不可逆操作（删除、覆盖、发送）。破坏性工具在权限检查中会受到更严格的审查
concurrencySafe：工具是否可安全并行执行（不依赖共享可变状态）。并行安全的工具可以被流式工具执行器同时调度

表中 true/false 表示始终返回该值；动态 表示根据输入参数运行时判定。未在源码中显式覆盖的方法使用 buildTool 默认值（均为 false）。

交叉参考：工具的定义协议详见附录 A.4.3 “工具类型系统的标准协议”；工具的注册与发现机制参见第 3 章；工具的权限检查流程参见附录 A.3 “权限判定路径”。

flowchart LR
    subgraph 文件操作["文件操作"]
        FR["FileReadTool"]
        FW["FileWriteTool"]
        FE["FileEditTool"]
        NB["NotebookEditTool"]
    end

    subgraph 搜索["搜索"]
        GB["GlobTool"]
        GP["GrepTool"]
        TS["ToolSearchTool"]
    end

    subgraph 执行["执行"]
        Bash["BashTool"]
        PS["PowerShellTool"]
    end

    subgraph 网络["网络"]
        WF["WebFetchTool"]
        WS["WebSearchTool"]
    end

    subgraph 智能体["智能体"]
        AT["AgentTool"]
        SM["SendMessageTool"]
        TC["TeamCreateTool"]
    end

    subgraph 其他["其他"]
        TD["TodoWriteTool"]
        LSP["LSPTool"]
        MC["MCP 工具"]
        CR["Cron 工具"]
    end

    classDef ro fill:#8fbc8f,stroke:#5a8a5a,color:#fff
    classDef rw fill:#4a90d9,stroke:#2c5f8a,color:#fff
    classDef dyn fill:#ff9800,stroke:#e65100,color:#fff

    class FR,GB,GP,TS,WF,WS ro
    class FW,FE,NB,AT,SM,TC,TD rw
    class Bash,PS dyn

1. 文件操作

文件操作工具是智能体处理代码和数据的基础能力。这组工具覆盖了从读取到编辑到创建的完整文件操作链。

工具名称	readOnly	destructive	concurrencySafe	简要说明
FileReadTool	`true`	`false`	`true`	读取文件内容，支持行号范围、PDF 分页、图片、notebook 格式
FileWriteTool	`false`	`false`	`false`	写入文件，覆盖已有内容或创建新文件
FileEditTool	`false`	`false`	`false`	精确字符串替换式编辑，支持单处/全局替换
NotebookEditTool	`false`	`false`	`false`	编辑 Jupyter Notebook 单元格（替换/插入/删除）

使用场景详解：

FileReadTool：适用于代码审查（逐段读取大文件）、文档分析（PDF 分页读取）、图片理解（多模态输入）等场景。其并发安全性使得可以同时读取多个文件来加速信息收集
FileWriteTool：适用于创建新文件（如配置文件、脚手架代码）或完全重写文件内容。由于写入是不可逆的，建议在重要文件上先使用 FileReadTool 确认当前内容
FileEditTool：适用于精确修改已有文件中的特定内容。其字符串匹配机制确保修改位置的准确性，replace_all 模式支持批量重命名等操作。这是日常代码编辑中最常用的工具
NotebookEditTool：专门为 Jupyter Notebook 设计，支持在特定位置插入代码或 markdown 单元格、修改已有单元格内容、删除单元格。适用于数据分析和科学计算场景

工具间的协作模式：典型的代码修改工作流为 FileReadTool -> 分析 -> FileEditTool/FileWriteTool。先读取理解现状，再决定使用精确编辑还是整体重写。

2. 搜索

搜索工具是智能体在代码库中定位信息的基础能力。文件名搜索和内容搜索互为补充，覆盖了从结构定位到语义查找的完整搜索需求。

工具名称	readOnly	destructive	concurrencySafe	简要说明
GlobTool	`true`	`false`	`true`	文件名 glob 模式匹配搜索，按修改时间排序
GrepTool	`true`	`false`	`true`	基于 ripgrep 的正则内容搜索，支持多模式输出
ToolSearchTool	`false`	`false`	`false`	工具发现搜索，按关键词匹配延迟加载的工具

使用场景详解：

GlobTool：适用于按文件类型（如 **/*.ts）、按目录结构（如 src/**/*.test.js）、按修改时间（最新变更的文件排在前面）查找文件。常用于项目结构探索和变更文件定位
GrepTool：适用于在文件内容中搜索特定模式，支持正则表达式。三种输出模式（files_with_matches、content、count）满足不同需求。常用于 API 使用查找、配置项定位、代码模式分析
ToolSearchTool：当可用工具数量很多时（特别是启用 MCP 动态工具后），此工具帮助模型按关键词快速定位需要的工具，避免将所有工具描述都纳入上下文

搜索策略推荐：

探索陌生项目时：先用 GlobTool 了解文件结构，再用 GrepTool 搜索关键符号
定位特定代码时：GrepTool 的 content 模式最为高效
统计代码规模时：GrepTool 的 count 模式配合 GlobTool 的文件列表

3. 执行

执行工具是智能体与操作系统交互的桥梁。BashTool 是通用性最强的工具之一，几乎所有命令行操作都通过它完成。

工具名称	readOnly	destructive	concurrencySafe	简要说明
BashTool	`动态`	`false`	`动态`	Shell 命令执行，只读命令可并行，写命令串行。权限依据命令内容动态判定
PowerShellTool	`动态`	`false`	`动态`	Windows PowerShell 命令执行（条件启用，功能与 BashTool 对等）

使用场景详解：

BashTool：这是 Claude Code 中使用频率最高的工具之一。适用于：构建和测试（npm test、cargo build）、版本控制（git 操作）、系统管理（文件操作、进程管理）、脚本执行、包管理等。其 readOnly 和 concurrencySafe 属性是动态判定的，取决于命令内容
PowerShellTool：在 Windows 环境中自动替代 BashTool，提供等效的命令执行能力。仅在检测到 Windows PowerShell 环境时启用

执行工具的特殊机制：

只读检测：BashTool 内部维护一个只读命令清单，匹配到的命令（如 ls、cat、git status）被标记为 readOnly，可以在权限更宽松的条件下执行
并行执行：当多个 BashTool 调用都被判定为 concurrencySafe 时，流式工具执行器可以并行调度它们，显著提升效率
超时管理：长时间运行的命令有超时机制，防止无限阻塞
输出截断：命令输出超过限制时会被截断，剩余部分持久化到磁盘

4. 网络

网络工具为智能体提供了访问互联网信息的能力，包括网页内容获取和网络搜索两种互补的方式。

工具名称	readOnly	destructive	concurrencySafe	简要说明
WebFetchTool	`true`	`false`	`true`	抓取 URL 内容并转换为 markdown
WebSearchTool	`true`	`false`	`true`	执行网络搜索，返回结构化搜索结果

使用场景详解：

WebFetchTool：适用于获取特定网页的完整内容（如 API 文档、技术博客）。将 HTML 转换为 markdown 格式，便于模型理解和引用。常用于查阅最新文档和验证技术细节
WebSearchTool：适用于开放式信息查询。返回结构化的搜索结果（标题、摘要、链接），帮助模型快速了解某个主题的最新信息。常用于技术调研和问题排查

组合使用模式：先用 WebSearchTool 进行广度搜索，定位相关资源后用 WebFetchTool 深度获取具体页面内容。

5. 智能体

智能体工具实现了 Claude Code 的递归组合能力，允许智能体创建和管理子智能体、在多智能体之间通信、以及组建协作团队。

工具名称	readOnly	destructive	concurrencySafe	简要说明
AgentTool	`false`	`false`	`false`	启动子智能体（内置/自定义），支持 fork、resume、后台执行
SendMessageTool	`动态`	`false`	`false`	向其他智能体或频道发送消息，纯文本消息为 readOnly
TeamCreateTool	`false`	`false`	`false`	创建多智能体团队（条件启用：Agent Swarms 模式）
TeamDeleteTool	`false`	`false`	`false`	删除已创建的团队

使用场景详解：

AgentTool：核心的子智能体管理工具。适用于将复杂任务分解为子任务并行处理、调用内置智能体（如 ExploreAgent、PlanAgent）完成特定阶段、在隔离的上下文中执行高风险操作等。参见第 9 章子智能体详解
SendMessageTool：在多智能体场景中用于跨智能体通信。支持向特定智能体或频道发送消息。参见第 10 章协调器模式
TeamCreateTool / TeamDeleteTool：在 Agent Swarms 模式下用于创建和管理多智能体团队。团队中的智能体可以并行处理分配给它们的子任务

6. 任务管理

任务管理工具提供了后台任务的生命周期管理能力，从创建到监控到停止的完整控制链。

工具名称	readOnly	destructive	concurrencySafe	简要说明
TaskCreateTool	`false`	`false`	`false`	创建后台任务（条件启用：Todo V2）
TaskGetTool	`true`	`false`	`true`	获取单个任务详情
TaskUpdateTool	`false`	`false`	`false`	更新任务状态/内容
TaskListTool	`true`	`false`	`true`	列出所有任务
TaskOutputTool	`动态`	`false`	`动态`	获取任务输出流，readOnly 时 concurrencySafe
TaskStopTool	`false`	`false`	`true`	停止正在运行的任务

使用场景详解：任务管理工具组构成了一个完整的 CRUD + 监控接口。典型工作流为：TaskCreateTool 创建任务 -> TaskListTool 查看进度 -> TaskGetTool 检查详情 -> TaskOutputTool 获取输出 -> TaskStopTool 在需要时停止任务。

7. 计划

计划模式工具提供了安全规划的能力，在执行前先制定方案。

工具名称	readOnly	destructive	concurrencySafe	简要说明
EnterPlanModeTool	`true`	`false`	`true`	进入计划模式，限制为只读工具集
ExitPlanModeV2Tool	`true`	`false`	`true`	退出计划模式，恢复正常工具权限

使用场景详解：计划模式是一种安全策略，在进入后智能体只能使用只读工具（如 FileReadTool、GrepTool）进行信息收集和分析，不能执行任何修改操作。适用于在执行复杂变更前进行方案设计、风险评估和影响分析。参见第 14 章结构化工作流。

8. 工作树

工作树工具为并行任务提供文件系统级别的隔离。

工具名称	readOnly	destructive	concurrencySafe	简要说明
EnterWorktreeTool	`false`	`false`	`false`	创建 git worktree 并切换工作目录（条件启用）
ExitWorktreeTool	`false`	`false`	`false`	退出 worktree，保留或移除工作目录

使用场景详解：工作树工具基于 git worktree 实现工作目录隔离。适用于多个子智能体并行处理不同任务时避免文件冲突、在不影响主工作区的情况下进行实验性修改、在不同分支上同时工作等场景。

9. 调度

调度工具提供了时间驱动的自动化能力，允许智能体按计划执行任务。

工具名称	readOnly	destructive	concurrencySafe	简要说明
CronCreateTool	`false`	`false`	`false`	创建 cron 定时任务（条件启用：AGENT_TRIGGERS）
CronDeleteTool	`false`	`false`	`false`	删除 cron 定时任务
CronListTool	`true`	`false`	`true`	列出所有 cron 定时任务
RemoteTriggerTool	`动态`	`false`	`false`	远程触发器管理（条件启用：AGENT_TRIGGERS_REMOTE）

使用场景详解：调度工具组实现了智能体的时间驱动自动化。CronCreateTool 支持标准 cron 表达式定义执行计划，适用于定期代码审查、自动化测试、定时报告生成等场景。RemoteTriggerTool 扩展了触发能力到远程环境。

10. 交互

交互工具管理智能体与用户以及其他系统组件之间的交互。

工具名称	readOnly	destructive	concurrencySafe	简要说明
AskUserQuestionTool	`true`	`false`	`true`	向用户提问并等待回复
SkillTool	`false`	`false`	`false`	调用已注册的 slash command 技能
ConfigTool	`动态`	`false`	`false`	运行时配置查看/修改（仅 ant 构建可用）

使用场景详解：

AskUserQuestionTool：当智能体在执行过程中遇到歧义或需要额外信息时，通过此工具向用户提问。这是智能体与用户之间的主动沟通渠道
SkillTool：调用通过技能系统注册的 slash command。技能是可扩展的能力包，通过提示词模板和工具定义扩展智能体在特定领域的专业能力。参见第 11 章技能系统

11. MCP

MCP 工具提供了与 MCP 服务器交互的能力，让智能体可以访问外部资源。

工具名称	readOnly	destructive	concurrencySafe	简要说明
ListMcpResourcesTool	`true`	`false`	`true`	列出 MCP 服务器提供的资源
ReadMcpResourceTool	`true`	`false`	`true`	读取 MCP 服务器上的特定资源

使用场景详解：MCP 工具是 Model Context Protocol 客户端的资源访问接口。ListMcpResourcesTool 用于发现可用的外部资源（如数据库表、API 端点），ReadMcpResourceTool 用于读取特定资源的内容。这两个工具都是只读的，可以安全并行执行。参见第 12 章 MCP 集成。

12. 其他

工具名称	readOnly	destructive	concurrencySafe	简要说明
TodoWriteTool	`false`	`false`	`false`	待办事项面板写入（UI 联动，结果不渲染到 transcript）
BriefTool	`false`	`false`	`true`	控制输出简洁性模式
LSPTool	`true`	`false`	`true`	LSP 语言服务协议操作（条件启用：ENABLE_LSP_TOOL）
SleepTool	`false`	`false`	`false`	延时等待（条件启用：PROACTIVE / KAIROS）
TungstenTool	`false`	`false`	`false`	内部工具（仅 ant 构建可用）
SyntheticOutputTool	`true`	`false`	`true`	合成输出工具（内部基础设施）
SnipTool	`false`	`false`	`false`	历史消息裁剪（条件启用：HISTORY_SNIP）
MonitorTool	`false`	`false`	`false`	监控工具（条件启用：MONITOR_TOOL）
WorkflowTool	`false`	`false`	`false`	工作流脚本执行（条件启用：WORKFLOW_SCRIPTS）
ListPeersTool	`false`	`false`	`false`	列出对等智能体（条件启用：UDS_INBOX）
REPLTool	`false`	`false`	`false`	REPL 包装器，在 VM 中提供 Bash/Read/Edit（仅 ant 构建）
SuggestBackgroundPRTool	`false`	`false`	`false`	建议后台 PR 创建（仅 ant 构建）
WebBrowserTool	`false`	`false`	`false`	浏览器工具（条件启用：WEB_BROWSER_TOOL）
SendUserFileTool	`false`	`false`	`false`	向用户发送文件（条件启用：KAIROS）
PushNotificationTool	`false`	`false`	`false`	推送通知（条件启用：KAIROS）
SubscribePRTool	`false`	`false`	`false`	PR Webhook 订阅（条件启用：KAIROS_GITHUB_WEBHOOKS）
CtxInspectTool	`false`	`false`	`false`	上下文检查器（条件启用：CONTEXT_COLLAPSE）
TerminalCaptureTool	`false`	`false`	`false`	终端截图捕获（条件启用：TERMINAL_PANEL）
VerifyPlanExecutionTool	`false`	`false`	`false`	计划执行验证（条件启用：CLAUDE_CODE_VERIFY_PLAN）
OverflowTestTool	`false`	`false`	`false`	溢出测试工具（内部测试用）
TestingPermissionTool	`true`	`false`	`true`	权限测试工具（仅 NODE_ENV=test）

工具启用条件速查

部分工具通过 feature flag 或环境变量条件启用。下表列出了所有条件启用工具及其对应的标志：

条件标识	启用的工具	对应章节
`USER_TYPE === 'ant'`	ConfigTool, TungstenTool, REPLTool, SuggestBackgroundPRTool	—
`PROACTIVE` / `KAIROS`	SleepTool	第 5 章
`AGENT_TRIGGERS`	CronCreateTool, CronDeleteTool, CronListTool	第 9 章
`AGENT_TRIGGERS_REMOTE`	RemoteTriggerTool	第 9 章
`MONITOR_TOOL`	MonitorTool	第 7 章
`KAIROS`	SendUserFileTool, PushNotificationTool	第 6 章
`KAIROS_GITHUB_WEBHOOKS`	SubscribePRTool	第 6 章
`ENABLE_LSP_TOOL`	LSPTool	第 7 章
`WORKFLOW_SCRIPTS`	WorkflowTool	第 9 章
`HISTORY_SNIP`	SnipTool	第 4 章
`UDS_INBOX`	ListPeersTool	第 7 章
`WEB_BROWSER_TOOL`	WebBrowserTool	第 7 章
`CONTEXT_COLLAPSE`	CtxInspectTool	第 4 章
`TERMINAL_PANEL`	TerminalCaptureTool	第 12 章
`COORDINATOR_MODE`	coordinator 模式额外启用 AgentTool, TaskStopTool, SendMessageTool	第 8 章
`Todo V2`	TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool	—
`Agent Swarms`	TeamCreateTool, TeamDeleteTool	第 8 章
`Worktree Mode`	EnterWorktreeTool, ExitWorktreeTool	第 9 章
`CLAUDE_CODE_SIMPLE`	精简模式仅保留 BashTool, FileReadTool, FileEditTool	—
`ToolSearch`	ToolSearchTool	第 3 章
`CLAUDE_CODE_VERIFY_PLAN`	VerifyPlanExecutionTool	第 14 章

交叉参考：功能标志的详细说明参见附录 C；工具的动态注册机制参见附录 A.3 “MCP 工具动态注册路径”。

工具注册流程

所有工具通过统一的工具工厂函数创建，该函数为未显式定义的方法填充安全默认值：

isEnabled() 默认返回 true
isReadOnly() 默认返回 false
isConcurrencySafe() 默认返回 false
isDestructive() 默认返回 false
checkPermissions() 默认返回允许（allow）
toAutoClassifierInput() 默认返回空字符串
userFacingName() 默认返回工具名称

工具注册入口在全局工具注册函数中，返回一个工具数组。运行时通过工具池组装函数将内置工具与 MCP 动态工具合并，按名称排序后去重（内置工具优先）。

flowchart TD
    A["buildTool 工厂函数<br/>填充安全默认值"] --> B["全局工具注册函数<br/>返回内置工具数组"]
    C["MCP 服务器<br/>动态工具发现"] --> D["MCP 工具适配<br/>转换为内部接口"]
    B --> E["工具池组装函数"]
    D --> E
    E --> F["按名称排序"]
    F --> G["去重<br/>内置工具同名优先"]
    G --> H["最终工具注册表"]

    classDef factory fill:#4a90d9,stroke:#2c5f8a,color:#fff
    classDef builtin fill:#8fbc8f,stroke:#5a8a5a,color:#fff
    classDef mcp fill:#ce93d8,stroke:#7b1fa2,color:#fff
    classDef merge fill:#ff9800,stroke:#e65100,color:#fff
    classDef result fill:#66bb6a,stroke:#2e7d32,color:#fff

    class A,B builtin
    class C,D mcp
    class E,F,G merge
    class H result

工具组合使用推荐模式

以下列出几种常用的工具组合模式，帮助读者理解工具间的协作关系：

模式一：代码探索与理解

flowchart LR
    GlobTool --> GrepTool --> FileReadTool

先用 GlobTool 定位文件结构，用 GrepTool 搜索关键符号，用 FileReadTool 阅读具体代码。

模式二：代码修改

flowchart LR
    FileReadTool --> FileEditTool --> BashTool["BashTool<br/>(test)"]

先读取目标文件，使用 FileEditTool 进行精确修改，然后用 BashTool 运行测试验证。

模式三：信息调研

flowchart LR
    WebSearchTool --> WebFetchTool --> FileWriteTool

先用 WebSearchTool 搜索相关信息，用 WebFetchTool 获取具体页面内容，最后用 FileWriteTool 整理结果。

模式四：多任务并行

flowchart TD
    Fork["AgentTool fork"] --> SA1["子智能体 1"]
    Fork --> SA2["子智能体 2"]
    Fork --> SA3["子智能体 N"]
    SA1 --> Merge["结果汇总"]
    SA2 --> Merge
    SA3 --> Merge

通过 AgentTool fork 出多个子智能体，每个子智能体独立处理子任务，最终由父智能体汇总结果。

模式五：安全规划

flowchart LR
    Plan["EnterPlanModeTool"] --> ReadOnly["只读工具集"] --> Exec["ExitPlanModeV2Tool"] --> Execute["执行工具集"]

先进入计划模式进行安全分析，完成规划后退出计划模式开始执行。

模式六：外部集成

flowchart LR
    MCP["MCP 连接初始化"] --> List["ListMcpResourcesTool"] --> Read["ReadMcpResourceTool"] --> Local["本地工具处理"]

通过 MCP 工具访问外部资源，结合本地工具进行处理。

工具性能特征概览

理解工具的性能特征有助于在使用时做出合理的选择：

工具类别	典型延迟	Token 消耗	并行能力	注意事项
文件读取	低（本地 I/O）	中（取决于文件大小）	高（均并发安全）	大文件输出会被截断
文件写入	低（本地 I/O）	低	不支持并行	写入前建议先读取确认
文件编辑	低（本地 I/O）	低	不支持并行	需精确匹配原始字符串
搜索（Glob/Grep）	低（本地操作）	中（取决于结果量）	高（均并发安全）	结果量限制防止 token 溢出
Bash 执行	可变（取决于命令）	可变（取决于输出）	只读命令可并行	长时间命令有超时机制
网络操作	高（网络延迟）	中（取决于页面内容）	高（均并发安全）	受网络状况影响大
子智能体	高（递归 API 调用）	高（独立上下文）	高（独立执行）	注意嵌套深度限制
MCP 操作	中（进程间通信）	中（取决于资源大小）	取决于 MCP 服务器	连接状态影响可用性