工具注册与发现

概述

Claude Code 的工具系统是一个模块化的插件架构，管理着 60+ 内置工具和动态加载的 MCP 工具。工具注册在 tools.ts 中完成。

Source: src/tools.ts

工具组装流程

getAllBaseTools()

Source: src/tools.ts:193-251

主工具列表，按条件组装：

始终加载

工具	功能
AgentTool	生成子代理执行任务
BashTool	执行 Shell 命令
FileReadTool	读取文件内容
FileEditTool	编辑文件（行级 diff）
FileWriteTool	创建新文件
GlobTool	文件模式匹配
GrepTool	正则搜索文件内容
WebFetchTool	抓取 URL 内容
WebSearchTool	网络搜索
TodoWriteTool	管理 Todo 列表
AskUserQuestionTool	向用户提问
SkillTool	调用技能
NotebookEditTool	编辑 Jupyter Notebook
EnterPlanModeTool	进入计划模式
ExitPlanModeV2Tool	退出计划模式
TaskOutputTool	获取后台任务输出
TaskStopTool	停止后台任务
BriefTool	简报工具

条件加载

// Source: src/tools.ts:201-249

// 嵌入式搜索工具（替代 GlobTool/GrepTool）
if (hasEmbeddedSearchTools()) {
  // 使用 bfs/ugrep 替代
}

// Ant 内部专用
if (USER_TYPE === 'ant') {
  tools.push(ConfigTool, TungstenTool);
}

// feature() 门控（反编译版全部禁用）
if (feature('WEB_BROWSER_TOOL')) tools.push(WebBrowserTool);
if (isTodoV2Enabled()) tools.push(TaskCreateTool, TaskUpdateTool, ...);
if (feature('PROACTIVE')) tools.push(REPLTool);
if (isToolSearchEnabled()) tools.push(ToolSearchTool);

getTools() — 权限过滤

Source: src/tools.ts:271-327

Simple 模式

当 CLAUDE_CODE_SIMPLE=1（--bare 标志）时，只提供最小工具集：

if (isSimpleMode()) {
  return [BashTool, FileReadTool, FileEditTool];
}

正常模式

1. 移除特殊工具（ListMcpResourcesTool 等）
2. 应用 filterToolsByDenyRules() — 根据权限规则过滤
3. 应用 tool.isEnabled() 检查

assembleToolPool() — 合并内置与 MCP 工具

Source: src/tools.ts:345-367

export function assembleToolPool(
  permissionContext: ToolPermissionContext,
  mcpTools: Tool[],
): Tool[] {
  const builtIns = getTools(permissionContext);
  const filteredMcp = filterToolsByDenyRules(mcpTools, permissionContext);
  
  // 分别排序以保持缓存稳定性
  const sortedBuiltIns = builtIns.sort(byName);
  const sortedMcp = filteredMcp.sort(byName);
  
  // 去重：内置工具优先
  return uniqBy([...sortedBuiltIns, ...sortedMcp], t => t.name);
}

工具延迟加载 (Deferred Tools)

部分工具标记为 shouldDefer: true，不会在初始提示中发送给 API。用户需要通过 ToolSearchTool 搜索并加载这些工具：

// 工具定义中
{
  name: 'NotebookEditTool',
  shouldDefer: true,  // 不在初始工具列表中
  searchHint: 'edit jupyter notebook cells',  // 搜索关键词
}

ToolSearchTool 允许 Claude 按需发现和加载延迟工具，减少初始 token 开销。

工具目录一览

src/tools/
├── AgentTool/          # 69KB — 子代理生成
├── BashTool/           # 46KB + bashPermissions.ts (98KB)
│                       #      + bashSecurity.ts (102KB)
├── FileEditTool/       # 20KB — 文件编辑
├── FileReadTool/       # 读取文件
├── FileWriteTool/      # 创建文件
├── GlobTool/           # 文件模式匹配
├── GrepTool/           # 20KB — 正则搜索 (ripgrep)
├── WebFetchTool/       # URL 抓取
├── WebSearchTool/      # 网络搜索
├── SkillTool/          # 技能调用
├── AskUserQuestionTool/  # 用户交互
├── NotebookEditTool/   # Jupyter Notebook
├── ToolSearchTool/     # 工具搜索
├── EnterPlanModeTool/  # 计划模式
├── ExitPlanModeV2Tool/ # 退出计划
├── TaskCreateTool/     # 任务创建
├── TaskUpdateTool/     # 任务更新
├── TaskGetTool/        # 任务查询
├── TaskListTool/       # 任务列表
├── SendMessageTool/    # 多代理消息
├── TeamCreateTool/     # 团队创建
├── TeamDeleteTool/     # 团队删除
├── PowerShellTool/     # PowerShell
├── SleepTool/          # 延时
├── CronCreateTool/     # 定时任务
├── RemoteTriggerTool/  # 远程触发
└── ... (共 58 个工具目录)

下一步

• 工具接口设计 — Tool 类型的完整定义
• 权限控制 — 工具权限系统