# Claude Code 内置工具全景盘点（源码调查素材）

> 基于 `claude-code/src` 实际目录（39 个工具目录 + testing/ + shared/）。行号均相对 `claude-code/src/`。
> 注册逻辑：`getAllBaseTools()`（tools.ts:193-251）是唯一事实来源；核心工具约 14 个无条件启用，其余靠 feature()/环境变量门控。

## 一、文件操作组

### Read（FileReadTool/FileReadTool.ts:338）
- 功能：读取本地文件（文本按行、图片/PDF 走多模态），模型"看代码"的主入口。只读✅ 并发安全✅ 默认启用✅
- 参数：`file_path`（绝对路径，必填）、`offset`（起始行）、`limit`（行数）
- 例子：改 bug 前 `Read {file_path:"/src/index.ts", offset:100, limit:80}`
- 细节：双重输出上限——文件 >256KB 直接拒绝（utils/file.ts:48 MAX_OUTPUT_SIZE），输出超 25000 token 报错（limits.ts:18，env CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS 可覆盖）；maxResultSizeChars: Infinity（:342）截断自己做；limits.ts:9-13 注释记录了"截断 vs 报错"A/B 实验回滚

### Edit（FileEditTool/）
- 功能：精确字符串替换 old_string→new_string，改代码主力。只读❌ 并发❌ 默认✅
- 参数（types.ts:6-19）：`file_path`、`old_string`、`new_string`、`replace_all`（默认 false）
- 例子：`Edit {file_path:"…/app.ts", old_string:"const x = 1", new_string:"const x = 2"}`
- 细节：**先读后写**——没 Read 过的文件报错 "File has not been read yet"（FileEditTool.ts:281），外部改过后要求重新 Read；.ipynb 拒绝并引导去 NotebookEdit（:270）

### Write（FileWriteTool/FileWriteTool.ts:95）
- 功能：整文件写入/覆盖。参数：`file_path`、`content`
- 细节：覆盖已存在文件前同样强制"先 Read"，检测"自我上次读取后文件被用户/linter 改过"（:203、:216），防盲覆盖

### NotebookEdit（NotebookEditTool/）
- 功能：编辑 Jupyter notebook 的 cell。参数：`notebook_path`、`cell_id`、`new_source`、`cell_type`(code/markdown)、`edit_mode`(replace/insert/delete)
- 细节：`shouldDefer: true`（:94）——会被 ToolSearch 延迟加载

## 二、搜索组

### Glob（GlobTool/GlobTool.ts:58）
- 功能：按 glob 模式找文件名，按修改时间排序。只读✅ 并发✅
- 参数：`pattern`（如 `**/*.ts`）、`path`（搜索根，默认 cwd）
- 例子："找所有测试文件"→ `Glob {pattern:"**/*.test.ts"}`
- 细节：ant 内部构建内嵌 bfs/ugrep 后 Glob/Grep 整体从工具列表移除（tools.ts:198-201）

### Grep（GrepTool/GrepTool.ts:161）
- 功能：基于 ripgrep 的内容正则搜索。只读✅ 并发✅
- 参数：`pattern`、`path`、`glob`、`output_mode`(content/files_with_matches/count)、`-A/-B/-C`、`-n`、`-i`、`type`、`head_limit`(默认250)、`offset`、`multiline`
- 例子：`Grep {pattern:"fetchUser", output_mode:"content", -n:true}`
- 细节：`maxResultSizeChars: 20_000`（:164）最紧输出上限之一，强迫模型精确收口

## 三、命令执行组

### Bash（BashTool/BashTool.tsx:421）
- 功能：执行 shell 命令，模型的"双手"。默认✅
- 参数（:227-247）：`command`、`timeout`、`description`（必填的通俗描述）、`run_in_background`、`dangerouslyDisableSandbox`
- 例子：`Bash {command:"npm test", description:"Run test suite"}`
- 细节1：**动态只读判定** isReadOnly(input) 分析命令本身——解析复合命令判断是否纯只读（:434-441）；preparePermissionMatcher 把 `ls && git push` 拆成子命令逐条匹配 `Bash(git *)` 规则（:447-465）
- 细节2：**隐藏内部字段** `_simulatedSedEdit` 是 sed 预览被批准后的内部字段，刻意从模型可见 schema 中 omit，防模型借它绕过权限沙箱任意写文件（:249-259 注释）；输出上限 30000 字符，超大落盘返回 persistedOutputPath（:424、:292）

### PowerShell（PowerShellTool/）
- 功能：Windows 上的 PowerShell 版 Bash，参数几乎相同（:228-233）
- 启用：`getPlatform()==='windows'` 且（ant 默认开/外部需 CLAUDE_CODE_USE_POWERSHELL_TOOL）（utils/shell/shellToolUtils.ts:17-22；tools.ts:242）；目录内含 gitSafety.ts、destructiveCommandWarning.ts 安全检查

### REPL（REPLTool/constants.ts:11）
- 功能：ant 内部"批量操作 VM"模式：开启后 Read/Write/Edit/Glob/Grep/Bash/NotebookEdit/Agent 8 个原语工具对模型隐藏（REPL_ONLY_TOOLS :37-46），模型必须通过 REPL 在 VM 里调用
- 启用：USER_TYPE==='ant' 且 CLI 入口，CLAUDE_CODE_REPL=0 可关（:23-30）；SDK 不默认开

## 四、网络组

### WebFetch（WebFetchTool/WebFetchTool.ts）
- 功能：抓取 URL 内容并用一个小 prompt 让模型对内容提问加工后返回。只读✅ shouldDefer✅
- 参数：`url`、`prompt`（对抓取内容做什么）
- 例子：`WebFetch {url:"https://docs…", prompt:"提取安装步骤"}`
- 细节：preapproved.ts:14 维护"代码相关域名白名单"，仅允许 WebFetch 的 GET 免审，文件头 SECURITY WARNING 不许其他工具复用（:5-11）

### WebSearch（WebSearchTool/WebSearchTool.ts）
- 功能：联网搜索。参数：`query`（≥2字符）、`allowed_domains`、`blocked_domains`。shouldDefer✅
- 细节：isEnabled() 按 API provider 判定——firstParty 直接开，Vertex 要求 Claude 4.0+ 模型

## 五、子代理与任务管理组

### Agent（AgentTool/AgentTool.tsx:226）
- 功能：派生子 agent 独立完成任务（隔离上下文，可并行、可后台）。默认✅
- 参数（:82-126）：`description`(3-5词)、`prompt`(任务书)、`subagent_type`、`model`(sonnet/opus/haiku)、`run_in_background`、`name`/`team_name`、`mode`、`isolation:worktree`、`cwd`
- 例子：三次 `Agent {description:"调研方案A", prompt:"…", run_in_background:true}` 并行探索
- 细节：isReadOnly()=true——Agent 本身不写盘，权限检查全部下放给子 agent 内部工具（:1264-1266）；输出上限 100000 字符（:229）

### TaskOutput（TaskOutputTool/）
- 功能：读取后台任务输出，可阻塞等待。参数：`task_id`、`block`(默认true)、`timeout`(≤600000ms 默认30000)
- 细节：只读；isEnabled() 写死 `"external"!=='ant'`——ant 内部版反而禁用（:163 附近）

### TaskStop（TaskStopTool/）
- 功能：终止后台任务。参数：`task_id`（兼容旧 shell_id）。shouldDefer✅（:53）

### TaskCreate / TaskGet / TaskUpdate / TaskList（TodoV2）
- 功能：结构化任务清单增/查/改/列，支持阻塞关系 addBlocks/addBlockedBy、owner、metadata；TaskUpdate status 接受 'deleted'
- 启用：isTodoV2Enabled()（tools.ts:218-220）——非交互会话强制开，CLAUDE_CODE_ENABLE_TASKS 强开（utils/tasks.ts:133-139）。全部 shouldDefer✅

### TodoWrite（TodoWriteTool/）
- 功能：经典待办清单写入（content/status/activeForm）
- 细节：与 TaskCreate 系互斥——isEnabled(){return !isTodoV2Enabled()}（:51 附近），新旧二选一

## 六、多 Agent 协作组

### SendMessage（SendMessageTool/）
- 功能：给队友 agent 发消息（`to` 支持队友名、`*` 广播，UDS_INBOX 下支持 uds:<socket>、bridge:<session> 跨进程投递）
- 参数：`to`、`summary`(5-10词UI预览)、`message`
- 细节：isReadOnly(input) 动态判定——纯文本消息算只读；isEnabled()=isAgentSwarmsEnabled()

### TeamCreate / TeamDelete
- 功能：创建/解散 agent 团队（TeamCreate 参数：team_name、description、agent_type）
- 启用：isAgentSwarmsEnabled()——ant 恒开，外部需 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 或 --agent-teams（utils/agentSwarmsEnabled.ts:24-32；tools.ts:228-230 lazy require 打破循环依赖）

## 七、用户交互与配置组

### AskUserQuestion（AskUserQuestionTool/AskUserQuestionTool.tsx:110）
- 功能：向用户弹 1-4 个选择题（带选项注解），拿结构化回答。默认✅ 只读✅ 并发✅
- 参数：`questions`（数组，1-4 个，带唯一性校验 refine）
- 细节：--channels（Telegram/Discord）激活时 isEnabled()=false——没人坐在终端前，弹窗会挂死会话（:135-145）

### Brief / SendUserMessage（BriefTool/BriefTool.ts:137）
- 功能：KAIROS（主动式助手）模式下给用户发富文本消息，可带附件，status:proactive 主动推送
- 细节：目录名叫 Brief 但 API 名 SendUserMessage（prompt.ts:1）；isEnabled() 需 feature('KAIROS')+运行时 entitlement 双重通过（:122-135）

### Skill（SkillTool/SkillTool.ts）
- 功能：按名调用已安装 Skill（注入其 SKILL.md 指令）。参数：`skill`、`args`。例子：`Skill {skill:"commit"}`

### Config（ConfigTool/ConfigTool.ts:68）
- 功能：读/改设置项。参数：`setting`、`value`（省略=读取）
- 细节：isReadOnly(input) 动态判定——不传 value 的读取算只读（:90-92）；仅 USER_TYPE==='ant' 注册（tools.ts:214）

## 八、模式切换组

### EnterPlanMode / ExitPlanMode
- EnterPlanMode：无参数，进入"只规划不动手"（EnterPlanModeTool.ts:21-26）
- ExitPlanMode（V2 :148）：提交计划求批准，参数 `allowedPrompts`——声明实施计划所需权限类别（描述动作类别而非具体命令）；channels 激活时进出两个工具一起禁用，避免"进得去出不来"（:167-178）

### EnterWorktree / ExitWorktree
- EnterWorktree：创建临时 git worktree 隔离工作区，参数 name（slug 校验，可选）
- ExitWorktree：action: keep|remove；**isDestructive 按入参判定**——remove 才算破坏性（:168-170）；有未提交改动时必须显式 discard_changes:true；会话级 scope guard 只认本会话创建的 worktree（:177-182）
- 启用：isWorktreeModeEnabled() 当前恒 true（tools.ts:225）

## 九、调度与触发组

### Sleep（SleepTool/prompt.ts:3）
- 功能：等待指定时长（不占 shell 进程，可被打断；prompt 建议优于 Bash(sleep)，提醒"每次唤醒一次 API 调用、prompt cache 5 分钟过期"）
- 启用：feature('PROACTIVE')||feature('KAIROS')（tools.ts:25-28）；快照只有 prompt.ts

### CronCreate / CronDelete / CronList（ScheduleCronTool/）
- 功能：注册 cron 定时任务到点把 prompt 入队。CronCreate 参数：`cron`(5字段本地时间)、`prompt`、`recurring`(false=一次性)、`durable`(true 持久化到 .claude/scheduled_tasks.json 跨重启)
- 启用：feature('AGENT_TRIGGERS')（tools.ts:29-35）。均 shouldDefer✅

### RemoteTrigger（RemoteTriggerTool/）
- 功能：管理远程触发器，action: list|get|create|update|run + trigger_id + body
- 启用：feature('AGENT_TRIGGERS_REMOTE')（tools.ts:36-38）

## 十、MCP 与工具发现组（重点）

### MCPTool 包装机制
MCPTool/MCPTool.ts 是占位模板（name:'mcp'，方法标注 "Overridden in mcpClient.ts"）。真正包装在 services/mcp/client.ts:1743-1832 fetchToolsForClient：
1. 向 MCP server 发 tools/list
2. 每个工具 {...MCPTool, name: fullyQualifiedName, ...} 展开覆盖（:1769-1773）
3. **命名规则** mcp__<normalize(server)>__<tool>（mcpStringUtils.ts:48）；SDK server 可设 CLAUDE_AGENT_SDK_MCP_NO_PREFIX 跳过前缀（:1760-1763）
4. **安全元数据来自 MCP 注解**：annotations.readOnlyHint→isReadOnly/isConcurrencySafe，destructiveHint→isDestructive，openWorldHint→isOpenWorld（:1795-1809）；mcpInfo 供权限规则（mcp__server 整服务器拒绝）
5. 描述超长截断 MAX_MCP_DESCRIPTION_LENGTH（:1789-1794）；权限默认 passthrough 并建议加 localSettings allow 规则

**McpAuthTool**（:63）：server 需 OAuth 时动态注册 mcp__<server>__authenticate 工具引导授权（client.ts:2318/2331）

**ListMcpResourcesTool / ReadMcpResourceTool**：列/读 MCP 资源（参数 server? / server+uri）。在 getAllBaseTools 末尾（tools.ts:245-246）但被 getTools() 当 specialTools 按需添加（:301-307）

### ToolSearch 的 defer_loading 机制
背景：工具一多，工具定义 token 开销爆炸。
1. **谁被延迟**：isDeferredTool()（ToolSearchTool/prompt.ts:62-108）——所有 MCP 工具一律延迟；内置标了 shouldDefer:true 的 26 个延迟（NotebookEdit、AskUserQuestion、WebFetch、WebSearch、EnterPlanMode、ExitPlanMode、TodoWrite、TaskCreate/Get/Update/List、TaskOutput、TaskStop、SendMessage、TeamCreate/Delete、CronCreate/Delete/List、ReadMcpResource、ListMcpResources、EnterWorktree、ExitWorktree、Config、LSP、RemoteTrigger）。alwaysLoad:true（MCP 可用 _meta['anthropic/alwaysLoad'] 豁免，client.ts:1785）和 ToolSearch 自身永不延迟
2. **模式**：ENABLE_TOOL_SEARCH 环境变量——'tst'（默认总延迟）、'tst-auto'（超阈值才启用，checkAutoThreshold utils/toolSearch.ts:444-467）、'standard'（关闭）。Haiku 不支持 tool_reference 自动降级（:204、239-252）
3. **发请求时**：被延迟工具以 defer_loading:true 发给 API（utils/api.ts:211-223），模型只看到工具名清单无 schema
4. **使用时**：模型调 ToolSearch {query:"select:Read,Edit"} 精确选择或 {query:"slack send"} 关键词（MCP 按 mcp__server__action 拆词、内置按 CamelCase 拆词打分，ToolSearchTool.ts:132-216），返回匹配项完整 JSONSchema 包在 <functions> 块
5. 注册：isToolSearchEnabledOptimistic() 为真才放进工具列表（tools.ts:247-249）

## 十一、LSP 与内部/测试工具

### LSP（LSPTool/LSPTool.ts）
- 功能：调语言服务器做语义代码导航。参数：operation（goToDefinition/findReferences/hover/documentSymbol/workspaceSymbol/goToImplementation/prepareCallHierarchy/incomingCalls/outgoingCalls）、filePath、line、character（1-based）
- 启用：ENABLE_LSP_TOOL 环境变量（tools.ts:224）

### StructuredOutput（SyntheticOutputTool/:20）
- 功能：非交互（SDK/headless）模式下让模型按调用方给的 JSON Schema 输出结构化结果（Ajv 校验）
- 启用：仅非交互会话（:24-28）

### TestingPermissionTool（tools/testing/）
- 测试专用模拟权限弹窗；仅 NODE_ENV==='test' 注册（tools.ts:244）

## 补充：全局机制

1. **三标记体系**：isReadOnly/isConcurrencySafe/isDestructive 默认全 false（Tool.ts:750-761），可静态或按入参动态覆写；并发调度靠 isConcurrencySafe，权限警示靠 isDestructive
2. **maxResultSizeChars**：Bash 30000、Grep 20000、Read Infinity、多数 100000；超限普遍"落盘+返回 persistedOutputPath"
3. **getTools() 二次过滤**（tools.ts:271-327）：CLAUDE_CODE_SIMPLE 极简模式只留 Bash/Read/Edit；deny 规则在模型看到工具列表前整体剔除（filterToolsByDenyRules :262-269）；REPL 模式隐藏原语
4. **assembleToolPool()**（:345-367）：内置与 MCP 合并去重（内置优先），各自按名排序、内置作为连续前缀——为 prompt cache 稳定，MCP 插进内置中间会打翻所有下游缓存键
5. **快照缺失但 tools.ts 引用的工具**（feature 门控实验/内部）：TungstenTool、SuggestBackgroundPRTool、MonitorTool、SendUserFileTool、PushNotificationTool、SubscribePRTool、VerifyPlanExecutionTool（CLAUDE_CODE_VERIFY_PLAN=true）、OverflowTestTool、CtxInspectTool、TerminalCaptureTool、WebBrowserTool、SnipTool、ListPeersTool、WorkflowTool