模块: tools | Claude Code 源码分析

本章总览

src/tools/ 是 Claude Code 的「能力层」：每个 Tool 实现模型可调用的一个原子能力（Bash、Read、Agent、MCP 等）。根目录 Tool.ts 定义统一接口与 buildTool 工厂，tools.ts 负责注册表与 getTools 过滤，services/tools/StreamingToolExecutor.ts 在 query 流式阶段并行调度工具执行。本页先建立「注册表 → 工具池 → tool_use → tool_result」主线，再把你带到四个最值得深读的子章节。

总览图

渲染图表中…

学完本章你应该能

建立 Tool 接口 → 具体实现 → 注册表 → 执行器的阅读顺序
区分 src/tools/ 目录与根目录 Tool.ts / tools.ts 的职责
能在源码树中从本页跳转到子章节与高亮文件
理解 assembleToolPool 如何把内置工具与 MCP 工具合并

建议学习步骤

浏览下方子章节导航表，选择入口主题
点击 SourceTree 中的 Tool.ts 或 tools/BashTool/ 跳转到对应讲解
建议顺序：tool-interface → bash-tool → streaming-executor → agent-tool

模块在架构中的位置

tools 是 src/ 下的一级目录，共 199 个文件、51,099 行。一句话概括：53 个内置工具 + MCP 动态工具，统一 Tool 接口，支持并发安全标记、权限弹窗、Progress 流式回报。

概览

指标	数值
行数	51,099
文件	199

子章节导航

子章节	主题	核心路径
tool-interface	Tool 类型、buildTool、getTools 注册表	`Tool.ts`、`tools.ts`
bash-tool	Shell 执行、权限、沙箱、UI 折叠	`tools/BashTool/`
streaming-executor	流式 tool_use 并发调度	`services/tools/StreamingToolExecutor.ts`
agent-tool	子 Agent 委派、fork、后台任务	`tools/AgentTool/`

架构分层

Claude Code 工具系统不要按目录数量来理解，而要按职责分层来读：

Tool.ts          — 接口契约、ToolUseContext、buildTool 默认值
tools.ts         — getAllBaseTools / getTools / assembleToolPool
tools/*Tool/     — 各工具实现（call、checkPermissions、render*）
services/tools/  — StreamingToolExecutor、runToolUse、toolHooks
query.ts         — 流式接收 tool_use → 交给 Executor → 收集 tool_result

关键边界：

Tool.ts 不 import 任何具体工具，避免循环依赖；具体工具 import Tool.ts
tools.ts 集中 import 所有内置 Tool 导出，feature gate 与 env 决定是否加入池
permissions/ 调用各 Tool 的 checkPermissions，不在 Tool 内重复规则引擎
components/messages/ 通过 Tool 的 renderToolUseMessage / renderToolResultMessage 渲染 UI

源码树里可见的是 src/tools/ 下的具体实现；根目录 Tool.ts、tools.ts 则是契约与注册表。判断「某个工具为什么不可用」时不要数目录，而要同时打开 getAllBaseTools()、getTools() 与 assembleToolPool()：feature flag、deny 规则、MCP 连接都会改变当前 turn 的真实工具池。

工具池与 MCP 合并

getTools(permissionContext) 返回当前权限上下文下可用的内置工具：过滤 deny 规则、isEnabled()、REPL 模式下的 REPL_ONLY_TOOLS 隐藏、CLAUDE_CODE_SIMPLE 精简模式等。

assembleToolPool 是 REPL 与 coordinator worker 的统一入口：

内置工具经 getTools 过滤
MCP 工具经 filterToolsByDenyRules
分区排序（built-in 前缀 + MCP 后缀）保证 prompt cache 稳定
uniqBy(..., 'name') 去重，内置优先

MCP 工具在运行时动态注入；refreshTools 回调允许 query 中途刷新工具列表。阅读 tool-interface 子章节时对照 getAllBaseTools 注释中的 Statsig 同步要求。

目录树展示 src/tools/ 下全部子目录（BashTool、AgentTool、FileReadTool 等）。根目录 Tool.ts、tools.ts 不在树中但可通过子章节 highlightFiles 跳转。点击 BashTool/ 等目录进入对应深度讲解。

与其他模块的协作

协作方	关系
query.ts	创建 StreamingToolExecutor，流式 addTool，yield tool_result
hooks/useCanUseTool	作为 CanUseToolFn 传入 call() 与 runToolUse
utils/permissions	规则求值 + 各 Tool.checkPermissions
utils/messages	createUserMessage 构造 tool_result；REJECT_MESSAGE
utils/hooks.ts	PreToolUse / PostToolUse / PermissionRequest 事件
components/messages	消费 Tool.render* 方法渲染 transcript

调试「工具不可用」时：先查 getTools 是否过滤掉该工具，再查 StreamingToolExecutor.addTool 的 unknown tool 分支，最后查 runToolUse 内的 validateInput / canUseTool 链路。

本章小结与延伸

tools 模块 = 模型能力的插件系统。先懂接口契约，再读最复杂的 Bash 与 Agent，最后理解流式执行器的并发语义。 继续学习：

Tool 接口