工具系统

工具系统是 Claude Code 的武器库。AI 能做什么、不能做什么，全由这套系统说了算。见过不少插件系统，Claude Code 的工具抽象算是做得相当干净的。

Tool 接口

一个接口，55 个成员。听起来吓人，但逻辑清晰——按生命周期分成几组：

标识

name: string          // 工具名，如 "Read", "Bash"
aliases?: string[]    // 别名
searchHint?: string   // 搜索提示

描述与 Schema

description: string | ((context) => string)  // 支持动态描述
inputSchema: ZodSchema    // 输入参数校验
outputSchema?: ZodSchema  // 输出校验（可选）

描述可以是字符串也可以是函数，因为有些工具的描述会根据上下文变化。比如文件操作工具的描述会包含当前工作目录。

执行

call(input, context): Promise<ToolResult<Output>>

核心方法。注意返回的是 Promise，不是 AsyncGenerator——工具执行是一次性的，不是流式的。

权限

checkPermissions?(input, context): PermissionResult
isReadOnly?: boolean       // 只读工具不需要权限确认
isDestructive?: boolean    // 破坏性操作需要额外确认
isConcurrencySafe?: boolean  // 能否并发执行
isEnabled?(context): boolean   // 运行时启用判断

UI 渲染

10+ 个渲染方法，处理不同状态下的展示——进度条、错误信息、结果预览等。在终端里做出像样的工具执行 UI，这些方法缺一不可。

ToolUseContext

工具执行时的"上下文背包"，40+ 个成员：

• 配置信息（可用命令、工具列表、MCP 客户端）
• 控制信号（AbortController，用于取消执行）
• 状态读写（getAppState / setAppState）
• UI 集成（setToolJSX、通知系统）
• 进度追踪、文件变更记录

每个工具的 call() 方法都能拿到这个 context，需要什么自己取。

工具清单

23 个核心内置工具

类别	工具
文件操作	Read, Write, Edit, MultiEdit
执行	Bash, NotebookEdit
搜索	Glob, Grep
Agent	Agent, Task
Web	WebSearch, WebFetch
协作	MCP 工具（动态注册）
其他	Skill, TodoWrite 等

Feature-gated 工具

部分工具只在特定构建中存在：

• PROACTIVE — 主动建议工具
• KAIROS — 高级时间工具
• AGENT_TRIGGERS — Agent 触发器
• COMPUTER_USE — 计算机操作

工具执行流

AI 决定调用工具
    |
    v
Schema 校验（Zod 验证输入参数）
    |
    v
权限检查
    ├── 白名单匹配 → 直接执行
    ├── 黑名单匹配 → 拒绝
    └── 需要确认 → 弹出用户确认
    |
    v
执行 tool.call(input, context)
    |
    v
结果序列化 → 拼入消息流 → 继续推理

整个流程最关键的是权限检查。一个 rm -rf / 从 AI 到真正执行之间，至少要过权限系统的层层关卡。这是 Claude Code 能让人放心用的核心原因。