Claude Code 工具系统详解
工具（Tools）是编程 Agent 的「手脚」——模型的能力边界由它能调用的工具决定。这一页详解 Claude Code 的工具系统：工具如何定义/注册/调用、各类核心工具的设计要点、以及任务管理的双轨架构。架构见 代码架构，机制见 核心机制。
一、工具的本质：模型输出意图，框架执行
再次强调这个关键认知：模型不直接执行任何操作。它只输出结构化的「工具调用」——{工具名, 参数}，框架负责：查注册表 → 校验参数 → 权限检查 → 真正执行 → 把结果回喂模型。底层走 Function Calling。
一个工具的定义通常包含：
| 字段 | 作用 |
|---|---|
| name | 工具名（模型据此调用） |
| description | 说明「何时用、怎么用」——模型路由的唯一依据 |
| input schema | 参数的 JSON Schema（约束 + 校验） |
| 执行函数 | 真正干活的逻辑 |
| 权限要求 | 是否只读、是否需要确认 |
工具描述写得好不好，直接决定模型用不用对、用没用错——这是工具设计的第一性原则。
二、文件操作工具（Read / Edit / Write）
编程 Agent 最高频的工具，设计上有几个讲究：
- Read：按行读取、支持分段（大文件不一次性灌爆上下文）、记录「已读」状态。
- Edit：用**「旧文本 → 新文本」的精确替换**，而非整文件覆盖——更安全（只改该改的）、diff 清晰、不易误删。要求 old_string 唯一匹配，否则报错让模型重试。
- Write：整文件写入（新建或完全替换），通常原子写（先写临时文件再替换，防止中途崩溃损坏文件）。
- 去重缓存：避免重复读同一文件浪费 token；常要求「编辑前必须先读过」，保证模型基于最新内容修改。
三、搜索与导航工具（Glob / Grep）
这是 agentic search 的基础——让模型像人一样自己探索代码库：
- Glob：按文件名模式找文件（
**/*.ts），快速定位。 - Grep：按内容正则搜索代码，基于 ripgrep（极快），支持按文件类型、上下文行数过滤。
- 价值：精确、永远看最新代码、无需预建索引——模型先 grep 定位、再 read 细看，按需拉取上下文，比「预先 embedding 整个库」更可靠。
四、命令执行工具（Bash）
最强大也最危险的工具——能跑任意 shell 命令：
- 只读检测：解析命令判断是否有副作用（
ls/cat只读 vsrm/git push有副作用），只读命令可放宽权限。 - AST / 语法解析：解析命令结构（如用 tree-sitter 解析 bash），更准地判断风险、拆分复合命令。
- 输出截断：长输出（如全量测试日志）截断/摘要，防止吃爆上下文。
- 超时控制：防止命令挂死。
- 权限上它是重点管控对象（见 核心机制 - 权限）。
五、任务管理：TodoWrite vs Task 双轨
复杂任务需要「记住要做什么、做到哪了」，Claude Code 有两套：
| TodoWrite（待办） | Task（子任务/子 Agent） | |
|---|---|---|
| 存储 | 内存级、当前会话 | 文件系统级、可跨会话 |
| 用途 | 给当前任务列待办、跟踪进度 | 派发独立子任务给子 Agent |
| 上下文 | 共享主上下文 | 独立上下文（隔离） |
| 适合 | 单 Agent 的多步骤清单 | 需要隔离/并行的复杂子任务 |
TodoWrite 让 Agent「边做边列清单、勾掉完成项」，长任务不迷路；Task 则用于派生子 Agent（见 子 Agent 与多 Agent）。
六、工具调用的工程细节
- 并行调用：模型一次可发起多个相互独立的工具调用（如同时 grep 几个关键词、读几个文件），框架并发执行、一起回传，省往返延迟。
- 结果回喂：工具结果作为新消息加入上下文，模型据此决定下一步。
- 失败处理：错误信息原样回喂，模型通常能读懂报错并自我修正（如改正 Edit 的 old_string）。
- 结果体积控制：大结果截断 + 提示「已截断，可分页读取」，平衡信息量与上下文成本。
高频追问
Q：Edit 工具为什么用「旧文本→新文本」而不是整文件覆盖？ 更安全、更精确：只改该改的部分，避免模型「重写整个文件」时误删或改坏无关代码；diff 清晰可审查；要求 old_string 唯一匹配，强制模型基于真实内容定位，减少幻觉式修改。整文件覆盖只在新建或彻底重写时用 Write。
Q：为什么 Bash 工具要做只读检测和 AST 解析？ 为了权限和安全：区分只读命令（ls/grep，可放宽自动执行）和有副作用命令（rm/git push，需确认/拦截）；AST 解析能更准地理解复合命令结构、识别危险操作，避免简单字符串匹配被绕过。
Q：TodoWrite 和 Task 有什么区别？ TodoWrite 是当前会话内存里的「待办清单」，帮 Agent 跟踪多步骤进度、共享主上下文；Task 是派发给子 Agent 的独立子任务，有自己的隔离上下文、可文件系统持久化。一个是「自己的 to-do list」，一个是「外包给子 Agent」。
Q：为什么搜索用 grep 而不是 embedding 检索？ grep（ripgrep）精确、快、永远基于最新代码、无需维护索引；模型「先 grep 定位、再 read 细看」的 agentic search 比「预先把代码 embedding 后猜哪段相关」更可靠，也没有索引过期问题。详见 编程 Agent 底层架构。
Q：工具结果太长会怎样？ 会被截断或摘要，并提示模型「结果已截断、可分页/缩小范围再查」。这是上下文预算管理的一部分——单个工具输出（如全量日志、超大文件）不能一次塞爆 200K 窗口，否则挤掉其他关键信息。