call(args, context, canUseTool, parentMessage, onProgress?)  // 唯一的"执行"方法：args 已经过 inputSchema 校验，context 是整个世界（下节细讲）    : Promise<ToolResult<Output>>  // Output 泛型 = 该工具自己的输出类型；canUseTool 回调让工具在执行中也能二次询问权限description(input, options): Promise<string>  // 动态描述：可以按会话状态/权限上下文改变给模型看的措辞，不是写死的字符串readonly inputSchema: Input  // Zod schema——对模型是 JSON Schema（API 参数），对运行时是 args 的校验器，一份定义两用readonly inputJSONSchema?: ToolInputJSONSchema  // MCP 工具可直接提供原生 JSON Schema，跳过 Zod→JSON 的转换环节outputSchema?: z.ZodType<unknown>  // 输出类型声明；源码注释写着 "TODO: Make it required"——目前还允许缺省inputsEquivalent?(a, b): boolean  // 判断两次调用是否等价——供去重/缓存类优化做决策用isConcurrencySafe(input): boolean  // 这次调用能否与其他工具并行？默认 false = 假设不安全，宁可串行isEnabled(): boolean  // 运行时开关：这个会话里要不要把我注册进工具列表（区别于编译期的 feature gate）isReadOnly(input): boolean  // 只读还是写操作——权限系统对这两类的默认态度完全不同isDestructive?(input): boolean  // 不可逆操作（删除/覆盖/发送）；注释明说"Defaults to false，只在真做破坏性动作时设 true"interruptBehavior?(): 'cancel' | 'block'  // 工具运行中用户发来新消息：cancel=停下丢弃结果，block=继续跑、让新消息排队

export type ToolUseContext = {  // 每次工具调用都收到的"世界对象"：配置、状态、UI 钩子、身份，全在这里  options: {  // 会话级静态配置块    commands: Command[]  // slash command 列表——工具可以查询当前有哪些 /命令可用    mainLoopModel: string  // 主循环模型名——需要"用哪个模型做二次判断"的工具从这里拿    tools: Tools  // 本会话完整工具表——子代理/组合型工具可以查其他工具的 schema    mcpClients: MCPServerConnection[]  // 已连接的 MCP server 列表    isNonInteractiveSession: boolean  // 是否 headless（-p / SDK）：决定能不能弹 UI、问用户    refreshTools?: () => Tools  // 拉取最新工具表的回调——MCP server 可能在查询中途才连上  }  abortController: AbortController  // 全局中断句柄：用户按 Esc，所有长操作都该检查这个 signal  readFileState: FileStateCache  // 文件读取状态 LRU 缓存——防重复读、给 CLAUDE.md 注入做去重  getAppState(): AppState  // 读全局应用状态（权限上下文、MCP 状态、后台任务……）  setAppState(f): void  // 写回全局状态；注释警告：对异步子代理这是 no-op，见 createSubagentContext  handleElicitation?: (serverName, params, signal) => Promise<ElicitResult>  // MCP -32042 URL elicitation 回调：print/SDK 模式委托给 structuredIO  setToolJSX?: SetToolJSXFn  // 注入自定义 React UI——local JSX command 用它渲染自己的界面  addNotification?: (notif) => void  // 往通知中心推一条消息（OS 级或应用内）  appendSystemMessage?: (msg: Exclude<SystemMessage, SystemLocalCommandMessage>) => void  // 追加"仅 UI"系统消息：在 normalizeMessagesForAPI 边界被剥掉，Exclude<> 让类型系统强制这一点  // ……（中间约 25 个字段：文件历史、commit 归属状态、skill 触发器、denial 计数、内容替换预算……）  messages: Message[]  // 当前会话消息流——AgentTool 这类工具靠它把任务上下文传给子代理  agentId?: AgentId  // 仅子代理设置：hooks 用它区分"主线程调用"还是"子代理调用"

type DefaultableToolKeys =  // buildTool 提供默认值的 8 个方法：ToolDef 里可以省略它们  | 'isEnabled'  | 'isConcurrencySafe'  | 'isReadOnly'  | 'isDestructive'  | 'checkPermissions'  | 'toAutoClassifierInput'  | 'userFacingName'const TOOL_DEFAULTS = {  // 默认值集合——注释原话："Defaults (fail-closed where it matters)"  isEnabled: () => true,  // 默认可用（opt-out）：想禁用要显式声明，而不是默认藏着  isConcurrencySafe: (_input?) => false,  // 假设不可并行 → 调度器串行执行，安全侧兜底  isReadOnly: (_input?) => false,  // 假设是写操作 → 权限系统按更高风险对待，宁可多问一次  isDestructive: (_input?) => false,  // 默认非破坏性（只有真做删除/覆盖才设 true）  checkPermissions: (input, _ctx?) => Promise.resolve({ behavior: 'allow', updatedInput: input }),  // 无工具特化逻辑 → 放行给通用权限系统裁决，不自己拍板  toAutoClassifierInput: (_input?) => '',  // 空串 = 跳过 auto-mode 安全分类器；注释警告：安全相关工具必须覆盖它  userFacingName: (_input?) => '',  // 占位——下面 buildTool 会立刻用 name 覆盖掉}export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {  // 注释要求：所有工具导出都走这里，默认值只活在一个地方  return {  // 运行时就是一个 spread：先铺默认值……    ...TOOL_DEFAULTS,    userFacingName: () => def.name,  // ……显示名默认 = 工具自己的 name（覆盖上面的空串占位）    ...def,  // ……最后铺工具自身定义——"安全默认 + 显式覆盖"，调用方永远拿到完整 Tool  } as BuiltTool<D>  // 类型层面用 BuiltTool<D> 镜像这个 spread：0-error typecheck across all 60+ tools（源码注释）

export const GrepTool = buildTool({  // 一个对象字面量就是全部"注册表"：契约的每个槽位在这里各就各位  name: GREP_TOOL_NAME,  // 主名 'Grep'——模型按这个名字发起调用  searchHint: 'search file contents with regex (ripgrep)',  // ToolSearch 关键词匹配用的一句话能力描述（规范要求 3-10 词）  maxResultSizeChars: 20_000,  // 结果超 2 万字符 → 落盘，模型只拿预览+路径（源码注释：persistence threshold）  strict: true,  // 严格模式：API 端更严格遵守工具说明和参数 schema  async description() { return getDescription() },  // 动态描述函数——可以按环境变化措辞  userFacingName() { return 'Search' },  // UI 显示名：模型调的是 Grep，用户看到的是 Search（两个名字各服务一个读者）  get inputSchema(): InputSchema { return inputSchema() },  // Zod schema：pattern/path/glob/type/output_mode/-A/-B/-C/head_limit……  isConcurrencySafe() { return true },  // 纯读搜索 → 显式声明可并行（覆盖默认的 false），调度器可以和其他调用并发跑  isReadOnly() { return true },  // 只读 → 权限系统可按"低风险"处理  toAutoClassifierInput(input) {  // auto-mode 安全分类器的紧凑输入：把参数压成一行可读文本    return input.path ? `${input.pattern} in ${input.path}` : input.pattern  // "pattern in path"——分类器一眼看懂这次搜索的范围  },  isSearchOrReadCommand() { return { isSearch: true, isRead: false } },  // UI 折叠标记：搜索类调用在紧凑视图里合并显示  getPath({ path }) { return path || getCwd() },  // 提取文件路径——权限规则（如 Grep(src/**)）就是拿它做匹配的  async preparePermissionMatcher({ pattern }) {  // hook if 条件匹配器：每个输入只调用一次，昂贵解析放这里    return rulePattern => matchWildcardPattern(rulePattern, pattern)  // 返回闭包逐条规则模式匹配——"准备一次、匹配多次"的两段式设计  },

// —— validateInput 摘录：一个藏在输入校验里的安全细节 ——if (absolutePath.startsWith('\\\\') || absolutePath.startsWith('//')) {  // UNC 网络路径（\\server\share）——源码注释：防止 NTLM 凭据泄漏  return { result: true }  // 直接跳过 fs.stat：不去触碰网络共享，把风险挡在文件系统调用之外// —— call() 摘录：工具如何把模型参数翻译成真实命令 ——async call({ pattern, path, glob, type, output_mode = 'files_with_matches', '-B': context_before, ... }, { abortController, getAppState }) {  // 解构 args；'-B'/'-A'/'-C' 是 ripgrep 风格 flag（带连字符的 key 必须加引号）  const absolutePath = path ? expandPath(path) : getCwd()  // 没给路径 → 从当前工作目录搜起  const args = ['--hidden']  // 也搜隐藏文件：.env、.gitignore 这类模型经常需要的东西默认是隐藏的  for (const dir of VCS_DIRECTORIES_TO_EXCLUDE) {  // 排除版本控制元数据目录，减少 .git/objects 之类的噪音    args.push('--glob', `!${dir}`)  // ripgrep 的 --glob !pattern = 排除匹配项  }  args.push('--max-columns', '500')  // 单行超 500 字符就截断——防 base64/压缩代码把上下文灌爆（源码注释原话）  if (multiline) { args.push('-U', '--multiline-dotall') }  // 多行模式只在显式要求时开：默认关闭避免误伤性能  if (case_insensitive) { args.push('-i') }  // 大小写不敏感 flag 透传  if (output_mode === 'files_with_matches') { args.push('-l') }  // -l = 只列文件名（默认模式）  else if (output_mode === 'count') { args.push('-c') }  // -c = 按文件统计匹配数  if (show_line_numbers && output_mode === 'content') { args.push('-n') }  // 行号只在 content 模式下有意义，其他模式加了是噪音  if (pattern.startsWith('-')) { args.push('-e', pattern) }  // 以连字符开头的 pattern → 用 -e 显式声明"这是模式不是 flag"  else { args.push(pattern) }  // 常规情况直接透传

export function getAllBaseTools(): Tools {  // "当前环境里所有可能可用的工具"——注释自称 source of truth  return [    AgentTool,  // 子代理派生——多智能体编排的核心入口    TaskOutputTool,  // 读后台任务输出（配合 TaskCreate/Stop 构成任务系统）    BashTool,  // shell 执行——能力最强也最危险的工具    ...(hasEmbeddedSearchTools() ? [] : [GlobTool, GrepTool]),  // Ant 内部构建把 bfs/ugrep 嵌进 bun 二进制 → 专用搜索工具冗余，直接不注册    ExitPlanModeV2Tool,  // 退出计划模式（v2）    FileReadTool, FileEditTool, FileWriteTool,  // 文件读/编辑/写三件套    NotebookEditTool,  // Jupyter ipynb 单元格编辑    WebFetchTool, TodoWriteTool, WebSearchTool, TaskStopTool,  // 抓取 / todo 列表 / 联网搜索 / 停任务    AskUserQuestionTool, SkillTool, EnterPlanModeTool,  // 向用户澄清 / 加载技能 / 进入计划模式    ...(process.env.USER_TYPE === 'ant' ? [ConfigTool] : []),  // Ant 内部专用：配置工具，外部构建里根本不存在    ...(isTodoV2Enabled() ? [TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool] : []),  // todo v2 = 任务管理四件套（运行时开关）    ...(isEnvTruthy(process.env.ENABLE_LSP_TOOL) ? [LSPTool] : []),  // LSP 语言服务——环境变量门控，默认关    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ExitWorktreeTool] : []),  // git worktree 隔离模式进出    getSendMessageTool(),  // agent 间消息——注意是函数调用：lazy require 打破循环依赖（见下）    ...(isAgentSwarmsEnabled() ? [getTeamCreateTool(), getTeamDeleteTool()] : []),  // 多智能体团队（swarm）创建/删除    ...(process.env.NODE_ENV === 'test' ? [TestingPermissionTool] : []),  // 仅测试环境存在的权限工具——生产构建里不存在    ListMcpResourcesTool, ReadMcpResourceTool,  // MCP 资源读取——常开（MCP server 连上才有实际内容）    ...(isToolSearchEnabledOptimistic() ? [ToolSearchTool] : []),  // 工具搜索：乐观检查，真正"延迟加载哪些工具"在请求时由 claude.ts 决定  ]}

export const getTools = (permissionContext: ToolPermissionContext): Tools => {  // 本会话最终工具表 = 基础清单 × 权限上下文  if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) {  // SIMPLE 模式（--bare）：最小工具集，面向嵌入场景的"最小权限"需求    const simpleTools: Tool[] = [BashTool, FileReadTool, FileEditTool]  // 只留 Bash/Read/Edit 三件套——其余一律不存在    if (feature('COORDINATOR_MODE') && coordinatorModeModule?.isCoordinatorMode()) {  // 若同时开了协调器模式……      simpleTools.push(AgentTool, TaskStopTool, getSendMessageTool())  // ……补上编排三件套：coordinator 要派任务、停任务、发消息（源码注释）    }    return filterToolsByDenyRules(simpleTools, permissionContext)  // 最小模式也要过 deny 规则——权限过滤没有豁免通道  }  const specialTools = new Set([ListMcpResourcesTool.name, ReadMcpResourceTool.name, SYNTHETIC_OUTPUT_TOOL_NAME])  // "特殊工具"：别处按条件单独添加，这里先剔除防重复注册  const tools = getAllBaseTools().filter(tool => !specialTools.has(tool.name))  // 基础清单减去特殊工具  let allowedTools = filterToolsByDenyRules(tools, permissionContext)  // blanket deny（如 mcp__server 整服禁用）——在模型看到之前就删掉，不是调用时才拒绝  if (isReplModeEnabled()) {  // REPL 模式：原始工具被包进 VM 沙箱里……    allowedTools = allowedTools.filter(tool => !REPL_ONLY_TOOLS.has(tool.name))  // ……所以从直用列表隐藏，防止绕过沙箱直接调（源码注释）  }  const isEnabled = allowedTools.map(_ => _.isEnabled())  // 运行期开关：每个工具自己决定这个会话要不要出现  return allowedTools.filter((_, i) => isEnabled[i])  // 最终表 = 基础清单 − 特殊工具 − deny − REPL 隐藏，再 × isEnabled

export function assembleToolPool(permissionContext: ToolPermissionContext, mcpTools: Tools): Tools {  // 内置 + MCP 统一工具池——REPL.tsx 和 runAgent.ts（coordinator worker）共用这一个入口  const builtInTools = getTools(permissionContext)  // 第一步：内置工具（已经过模式/权限/isEnabled 全套过滤）  const allowedMcpTools = filterToolsByDenyRules(mcpTools, permissionContext)  // 第二步：MCP 工具同样过 deny 规则——外部 server 的工具没有豁免权  const byName = (a: Tool, b: Tool) => a.name.localeCompare(b.name)  // 排序比较器：按名字字母序  return uniqBy(  // 第三步：按 name 去重——内置工具优先（uniqBy 保留插入顺序，冲突时先出现的赢）    [...builtInTools].sort(byName).concat(allowedMcpTools.sort(byName)),  // 关键：两个分区各自排序后拼接，内置保持连续前缀    'name',  )}

一次工具调用的完整旅程（契约成员 → 管线环节）

▼

▼

▼

▼

▼