工具系统解析：Tool 抽象与 tools 注册表

Claude Code 的强执行力不仅依赖底层模型，更离不开其外部工具系统的精密设计。本文将深入解析该系统的核心架构：通过 Tool.ts 定义的统一抽象协议、ToolUseContext 提供的丰富运行时上下文，以及 tools.ts 实现的动态注册与权限过滤机制，揭示该系统如何构建出一个安全、可扩展且高度可控的工程代理执行层。

Tool.ts 并非某个具体工具的实现，而是全系统的工具抽象层。其核心价值在于两点：

• 统一语义：标准化工具的输入结构、输出格式、上下文依赖与权限边界。
• 固化契约：为所有工具提供一致的执行规范，确保系统能准确理解与调度。

该文件定义了系统的关键类型接口：

• ToolInputJSONSchema
• ToolUseContext
• ToolPermissionContext
• 进度追踪与状态管理类型

export type ToolInputJSONSchema = {
  [x: string]: unknown
  type: 'object'
  properties?: {
    [x: string]: unknown
  }
}

这段定义虽短，却确立了系统的设计基线：工具不是随意的文本描述或 Prompt 技巧，而是具备明确输入结构、可枚举参数、且能被系统层级理解的契约对象。 这正是工程化工具系统与单纯提示词工程的本质区别。

ToolUseContext 承载了工具执行时所需的全部运行时资源，证明工具在系统中并非孤立函数，而是深度嵌入完整会话生态的能力节点：

• 能力路由：当前工具集合 (tools)、命令集合 (commands)、MCP Client/Resource
• 状态管理：AppState 读写方法、文件读取缓存 (readFileState)
• 交互控制：通知能力、中断逻辑 (abortController)、消息历史流 (messages)
• 元数据追踪：attribution / fileHistory 更新器

export type ToolUseContext = {
  options: {
    commands: Command[]
    debug: boolean
    mainLoopModel: string
    tools: Tools
    verbose: boolean
    thinkingConfig: ThinkingConfig
    mcpClients: MCPServerConnection[]
    mcpResources: Record<string, ServerResource[]>
  }
  abortController: AbortController
  readFileState: FileStateCache
  getAppState(): AppState
  setAppState(f: (prev: AppState) => AppState): void
  messages: Message[]
}

一个工具的执行，实际上是被注入完整运行时沙箱中进行的。它依赖的不仅是参数，而是整个 Agent 会话的状态、配置与生命周期控制。

如果说 Tool.ts 定义了协议，tools.ts 则维护着本次系统实际暴露的能力清单。其覆盖范围已远超基础 CRUD，呈现高度模块化的智能体工作流特征：

export function getAllBaseTools(): Tools {
  return [
    AgentTool, TaskOutputTool, BashTool,
    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),
    ExitPlanModeV2Tool, FileReadTool, FileEditTool, FileWriteTool,
    WebFetchTool, TodoWriteTool, WebSearchTool, AskUserQuestionTool,
    SkillTool, EnterPlanModeTool,
    ...(isEnvTruthy(process.env.ENABLE_LSP_TOOL) ? [LSPTool] : []),
    ListMcpResourcesTool, ReadMcpResourceTool,
  ]
}

工具集并非静态硬编码。系统会根据环境变量 (process.env)、平台特性与 Feature Flag 动态决定最终清单，体现出极强的构建期配置能力。

Claude Code 从不将全部代码级工具直接暴露给模型。在模型实际调度前，工具集会经历严格的环境检测与权限过滤：

export function filterToolsByDenyRules<
  T extends {
    name: string
    mcpInfo?: { serverName: string; toolName: string }
  },
>(tools: readonly T[], permissionContext: ToolPermissionContext): T[] {
  return tools.filter(tool => !getDenyRuleForTool(permissionContext, tool))
}

这一设计体现两大安全与工程原则：

1. 最小权限动态暴露：模型实际可见的工具集 ≠ 代码库中的工具总量。系统通过规则引擎按需裁剪能力边界。
2. 安全前置（Shift-Left Security）：权限控制不依赖执行时的运行时拦截，而是在能力挂载阶段直接过滤。无效/危险工具甚至不会出现在模型的 Prompt 上下文中，从根本上降低了越权调用的概率。

从该工具系统的架构取舍中，可清晰识别出 Claude Code 的核心工程取向：

• 能力统一封装：先定义抽象协议与上下文模型，再挂载具体实现，解耦协议层与业务层。
• 权限前置与环境驱动：通过构建期配置与声明式规则控制能力面，而非依赖运行时的补丁式安全。
• 扩展优先（Extension-First）：MCP、LSP、Agent 协作、Worktree 等均作为“插件式”节点接入统一协议，无需修改核心调度逻辑。

这也解释了系统后续的演进路径。当工具协议稳定后，新增能力的路径变得高度可预测：

1. 实现符合 ToolInputJSONSchema 的新工具类
2. 注入标准 ToolUseContext 与权限上下文
3. 注册至 tools.ts 并配置启用条件
4. 按需暴露给模型

Claude Code 的工具系统，本质上是用统一的 Tool 协议，将文件系统、终端、搜索、外部集成和智能体能力包装成模型可调用、可控、可扩展的执行层。理解这层架构，便能明白它并非“聊天模型 + 插件”的简单拼凑，而是一个具备完整工程代理能力的操作中枢。

• 协议驱动执行：Tool.ts 通过强类型输入 Schema 与标准契约，将工具从 Prompt 依赖转变为系统级可调度对象。
• 上下文即资源：ToolUseContext 提供完整会话沙箱，工具在状态感知、权限控制与中断管理下协同工作。
• 注册表动态化：tools.ts 结合环境变量与 Feature Flag 实现构建期裁剪，模型可见能力严格受控于安全规则。
• 架构演进红利：统一抽象层使得扩展新能力（MCP/LSP/Agent协作）可复用现有调度与安全基础设施，大幅降低系统熵增。