工具契约、注册表与可见性

模型每一步能调用哪些工具、每个工具有什么副作用、出了错怎样告诉模型，都写在一份声明式的“工具契约”里。契约的类型和各工具的 zod schema 放在 @zcode/contracts，具体取值（权限、结果预算、超时、取消）大多写在 core 各 handler 的 ToolEntry 里，ToolEntry 同时挂上 handler 和一组可选钩子。40 个内置条目过了注册门之后，和运行时接入的 MCP 工具一起进同一张 ToolRegistry，再经过几道筛选变成发给模型的 ModelToolContract[]。

本篇讲“声明、注册、可见”：契约有哪些字段、哪些真的有人读；注册表怎样组织；模型看到的清单怎样定下来；参数不合格时模型收到什么。执行器怎样调度、审批和收尾，留给下一篇执行器：调度、审批、超时与结果。

怎么用

注册表不对用户开放，能改变工具清单的入口是这些：

--disallowedTools 接受 Bash(rm:*) 这类带括号的规则，但注册层只取括号前的名字（apps/zcode-cli/packages/core/src/tool/tool-visibility.ts:5）。从代码看，这样一条规则会让整个 Bash 都不注册，而不是只禁掉 rm。权限层怎样解释这些规则，见权限模式与规则。

一个工具声明什么

契约的公共部分在 apps/zcode-cli/packages/contracts/src/tools/contract.ts:168：

export interface ToolContractDeclaration {
  capability: string;
  executionMode?: ToolExecutionMode;
  providerNative?: ProviderNativeToolSpec;
  inputSchema: Record<string, unknown>;
  outputSchema: Record<string, unknown>;
  /**
   * 声明 `inputSchema` **有资格**走 provider 的严格模式（Anthropic `strict: true`：constrained
   * decoding 保证 tool_use.input 恰好满足 schema）。只是资格，不是命令：adapter 按 provider /
   * model 决定是否真的下发，并负责把 strict 子集表达不了的关键字折进 description。缺席即不严格。
   * 首个使用者是 dwf mono 子代理的 typed `submit_result`。
   */
  strict?: boolean;
  requiresUserInteraction?: boolean;
  permission: ToolPermissionSpec;
  resultBudget: ToolResultBudget;
  timeout: ToolTimeoutPolicy;
  cancellation: ToolCancellationPolicy;
  trace: ToolTracePolicy;
}

core 的 ToolEntry 继承它（apps/zcode-cli/packages/core/src/tool/types.ts:269），再加上必填的 metadata（types.ts:65）、handler 和十来个可选钩子。按用途归一下类：

可选钩子让契约能“看入参说话”。全部 40 个内置条目里用到的情况如下：

看一个真实声明。Bash 的权限、结果预算和超时（apps/zcode-cli/packages/core/src/tool/handlers/bash.ts:470）：

  permission: {
    permission: "bash",
    reason: "Bash can run subprocesses and may affect workspace, git, network, or system state",
    riskLevel: "high",
    sideEffectScope: "system",
    needsApproval: true,
    patternSources: ["command"],
    alwaysAllowPatternSources: ["command"],
    denyPriority: "beforeAsk",
  },
  resultBudget: {
    maxInlineBytes: MAX_INLINE_OUTPUT_BYTES,
    maxModelBytes: 30_000,
    strategy: "artifact",
    preview: {
      maxBytes: 30_000,
      direction: "tail",
    },
    artifact: {
      enabled: true,
      retention: "session",
    },
  },
  timeout: {
    defaultMs: DEFAULT_BASH_TIMEOUT_POLICY.defaultTimeoutMs,
    maxMs: DEFAULT_BASH_TIMEOUT_POLICY.maxTimeoutMs,
    allowCallOverride: true,
    cleanupGraceMs: 6_000,
  },

同一个条目的 metadata 里写着 maxOutputBytes: 10_000_000（bash.ts:455），真正卡住模型输入的却是上面的 30000 字节。另外，patternSources、alwaysAllowPatternSources、denyPriority 三个字段在全仓库都没有读取方，只在几处注释里被提到。

AGENTS.md 的要求与实际字段

apps/zcode-cli/AGENTS.md 专门有一节“工具与副作用契约”，第一条是（apps/zcode-cli/AGENTS.md:62）：

每个 tool 都应声明明确的 inputSchema、outputSchema、是否只读、是否破坏性、是否并发安全、最大输出大小、超时、取消语义和权限需求。

逐条对照代码：

七种副作用范围是 none、workspace、git、network、system、session、userInteraction。contracts 在这之上给了两条判定：isWorkspaceMutatingToolCall 判“写”，只认 workspace、git、system，范围缺席按会写处理（contract.ts:30）；isWorldTouchingToolCall 判“碰”，排除 session 和 userInteraction 两档协议范围，其余都算（contract.ts:57）。注释特意说明 Read 的范围是 none，但它的答案取决于工作区，所以读也算“碰”（contract.ts:54）。两条规则都是给动态工作流的导入缓存用的，见动态工作流（三）：从工具调用到落库。

注册表：一张表，两类来源

ToolRegistryImpl 只有两张 Map：规范名到条目、别名到规范名（registry.ts:30）。注册时规范名永远压过别名，同名重复注册会覆盖并告警；别名撞上已有工具或别的别名时直接跳过，以免一次调用被路由到错误的权限和 handler（registry.ts:34）。get 先查别名再查规范名（registry.ts:88），list 按插入顺序返回。toContracts 把条目投影成 ModelToolContract：去掉 providerVisible: false 的条目，拼好描述，带上能力旗标、权限和结果预算，execute 一律置空（registry.ts:104、registry.ts:127），所以模型 SDK 永远不会自己执行工具。

内置工具。注册总表是 builtInTools（apps/zcode-cli/packages/core/src/tool/handlers/index.ts:76），40 个条目；registerBuiltInTools 逐个过门（tool/handlers/index.ts:195），过了门的再交给 resolveBuiltInToolEntryForBranch 按配置造变体（tool/handlers/index.ts:271）：Bash 的描述和 timeout 参数说明随超时策略变化，Agent、Task 的描述带上子 Agent 档案列表，动态工作流关闭时还会去掉“工作流请求必须改用 CreateWorkflow”一句（tool/handlers/index.ts:284）。ApplyPatch 的契约还在 contracts 里，旧的 Workflow 工具也留着注册门，但两者在总表里都被注释掉了（tool/handlers/index.ts:70、tool/handlers/index.ts:80），这一版不会出现在模型面前。

注册入口有两个：运行时构造时的 registerRuntimeBuiltInTools（runtime-tools.ts:46），以及初始化 Shell 环境快照后再跑一次的 refreshBranchAwareBuiltInTools（apps/zcode-cli/packages/core/src/runtime/methods/embedded-search-branch.ts:21）。两处各写一份门的推导曾经漂过：刷新那份漏了动态工作流开关，而这个开关“缺席即开启”，结果灰度关闭的会话里模型仍然调到了 ListSavedWorkflows，于是推导被收进 tool-allowlist.ts 共用（apps/zcode-cli/packages/core/src/runtime/helpers/tool-allowlist.ts:70）。

别名。Task 是 Agent 的完整拷贝，标了 providerVisible: false，描述写明是 “Claude Code-compatible alias”（apps/zcode-cli/packages/core/src/tool/handlers/agent.ts:287）；TaskStop 认 KillShell、KillBash（apps/zcode-cli/packages/core/src/tool/handlers/task-stop.ts:97），TaskOutput 认 BashOutput、AgentOutputTool 等四个名字（apps/zcode-cli/packages/contracts/src/tools/task-output.ts:5）。这些名字不发给模型，但模型或插件说明按旧名调用时照样能找到工具。钩子匹配也有一张别名表：匹配 Task 的钩子对 Agent 生效，反之亦然（apps/zcode-cli/packages/core/src/tool/compat.ts:6），钩子本身见生命周期 Hooks 与工作区信任。

MCP 工具。回合循环每一轮都会调用 initializeMcp（apps/zcode-cli/packages/core/src/runtime/methods/turn-loop.ts:106），但它每个运行时只注册一次：等待连接快照，调用 registerMcpTools 写进同一张注册表，有新工具就清掉工具缓存（apps/zcode-cli/packages/core/src/runtime/methods/mcp.ts:122）。README 说 MCP 工具“registered before the first model request”（apps/zcode-cli/README.md:180），与代码一致。名字是 mcp__<server>__<tool>，两段都把字母、数字、下划线、连字符以外的字符换成下划线（apps/zcode-cli/packages/core/src/mcp/name.ts:3）。能力旗标从 MCP 的 annotations 推出来（core/src/mcp/index.ts:108）：

• readOnlyHint、destructiveHint 直接映射；concurrentSafe 取“只读或幂等”；
• needsApproval 一律为真，副作用范围一律记作 network，只有宿主 node_repl 的 js 记作 system、风险为高；
• 超时取描述里的 timeoutMs，缺省 30000 毫秒（core/src/mcp/index.ts:37）；
• 结果预算：普通 MCP 给模型 50000 字节、超出截断；宿主 node_repl 64 KiB、超出落盘并保留尾部；验明身份的官方 Computer Use 256 KiB（core/src/mcp/index.ts:125）。

官方 Computer Use 的服务在插件命名空间下，工具名本来是 mcp__plugin_zcode-cua_computer-use__*，只有通过不可伪造的宿主凭据校验后才改投成 mcp__computer-use__*，另挂一个 provider 拼写别名（core/src/mcp/index.ts:86）。MCP 的连接、传输与 OAuth 见 MCP。

可见性：从注册表到请求

模型看到的清单要过五层：

回合过滤的细节属于回合循环与 TurnMachine，这里只看前三层里容易误会的几点。

默认没有 Glob 和 Grep。嵌入式搜索分支的总开关写死为 true（apps/zcode-cli/packages/core/src/embedded-search/capability.ts:4），全仓库没有调用方覆盖它；只要 Bash 没被白名单或黑名单拿掉，registerBuiltInTools 就跳过 Glob 和 Grep（tool/handlers/index.ts:206），搜索改由 Bash 里的 find、grep 接管。实现见读、写、改、搜。

会话类型会收窄工具面。toolset 为 explore 时只注册探索工具集 Bash、Glob、Grep、Read、WebFetch、WebSearch、TodoWrite（apps/zcode-cli/packages/core/src/subagent/explore-tools.ts:4），另给了白名单就取交集，子 Agent 会话还会补回 RespondToCoordinator（tool-allowlist.ts:79）；工作流子会话固定禁用 CreateWorkflow、AmendWorkflow、SaveWorkflow、ResumeWorkflowRun、ResolveWorkflowQuestion（tool-allowlist.ts:26）。前三个声明了 alwaysAsk，而工作流子会话被强制成 yolo、交互事件不回传父界面，确认请求会隐形挂起到超时；后两个是“子会话内不得再编排、不得替主代理作答”的结构性禁令（tool-allowlist.ts:18、tool-allowlist.ts:38）。

宿主形态靠端口表达。core 里没有“是不是桌面端”的判断，宿主注入了哪些端口，就有哪些工具。bootstrap 只是转发调用方给的定时任务端口和闲时端口（create-app.ts:775），TUI 与 -p 都不传，所以终端里没有 Cron 与 OffPeak 工具；协议会话总是注入定时任务端口，闲时端口看宿主开关（server-operations.ts:3370、server-operations.ts:3373）。动态工作流的十个工具极性相反：终端不写开关，按“缺席即开启”保留全部工具（tool/handlers/index.ts:178）；协议会话必须写出显式布尔，宿主不开就是 false（server-operations.ts:3337，服务端默认值见 apps/zcode-cli/packages/bootstrap/src/zcode-protocol/server.ts:255）。

权限模式不参与筛选。Plan 模式下模型照样能看到 Write 和 Bash，模式只影响回合里插入的提醒（turn-loop.ts:126）和执行时的权限判定。拦截发生在执行器里，见权限模式与规则。

模型能力。WebSearch 只在当前模型的 supportsNativeWebSearch 为真时出现（config.ts:268），它本身是借模型的原生搜索实现的，见 WebFetch 与 WebSearch；Read 的 pages 参数只对支持 PDF 的模型出现。执行器调用前也用同一个 resolveModelContract 投影一次（apps/zcode-cli/packages/core/src/tool/model-contract.ts:4），保证校验用的 schema 与模型看到的是同一份。

发给模型的契约：schema、描述与顺序

Schema。所有内置工具的 schema 都走 toToolJsonSchema，注释说这是为了让运行时校验与 provider 参数不漂移（apps/zcode-cli/packages/contracts/src/tools/json-schema.ts:20）。它用 zod-to-json-schema 生成 JSON Schema 7，不用 $ref、按输入侧展开 effect，再做一轮归一化：删掉 $schema、$id、$ref、$defs、definitions（tools/json-schema.ts:9），没有 oneOf 时把 anyOf 改名为 oneOf（tools/json-schema.ts:66），缺 type 的节点按 properties、items、enum 等推断出类型，最后标上 draft 2020-12 的 $schema。改名有个副作用：core 自己的校验器对 oneOf 要求恰好命中一个分支（apps/zcode-cli/packages/core/src/tool/json-schema.ts:71），比 anyOf 严。

描述。metadata.description 之外，声明了 modelInstructions 的工具（CronCreate、CronUpdate、OffPeakCreate、ReadSessionContext、RespondToCoordinator）会在描述后追加一段 Usage: 列表（registry.ts:132）。WebSearch 的描述是个 getter，每次读取重新生成，因为描述里带着当前月份，写死会过期（apps/zcode-cli/packages/core/src/tool/handlers/websearch.ts:134）。

顺序。getTools 在生成缓存清单时统一排序（config.ts:264），规则在 apps/zcode-cli/packages/core/src/tool/provider-visible-order.ts:35：

export function orderProviderVisibleToolContracts<T extends { name: string }>(
  tools: readonly T[],
): T[] {
  const referenceTools: T[] = [];
  const localTools: T[] = [];
  for (const tool of tools) {
    if (SORTED_PROVIDER_TOOL_NAMES.has(tool.name)) {
      referenceTools.push(tool);
    } else {
      localTools.push(tool);
    }
  }

  return [
    ...referenceTools.sort((left, right) => left.name.localeCompare(right.name)),
    ...localTools,
  ];
}

名单 SORTED_PROVIDER_TOOL_NAMES 有 31 个名字（provider-visible-order.ts:1），其中 EnterWorktree、ExitWorktree、LSP、NotebookEdit、ScheduleWakeup、TaskCreate、TaskGet、TaskList、TaskUpdate、Workflow 这 10 个 ZCode 这一版并不注册。TaskCreate、TaskGet、TaskList、TaskUpdate 这一组是 Claude Code 的任务工具（见 Claude Code 中文手册），从这些名字看，名单像是参照 Claude Code 的工具集列出的。效果是：名单内的工具按字母序排在最前，其余内置工具按注册顺序跟在后面，MCP 工具最后注册，自然落在末尾。

为什么要稳定？工具清单是请求前缀的一部分，任何增删、改名、换序都会让 provider 的提示词缓存从头失效。代码里有几处印证：getTools 的结果缓存在运行时上（config.ts:137），只在 MCP 注册或搜索分支刷新时清空；submit_result 的注释把“per-ask schema 不进工具声明”归因于 “frozen-tool 缓存不变式”（apps/zcode-cli/packages/core/src/tool/handlers/submit-result.ts:9）；工作流 driver 也提到 “prompt-cache 的 frozen-tools 不变式”（apps/zcode-cli/packages/bootstrap/src/app/workflow-driver.ts:547）。

到 provider 为止。toAiSdkTools 只把描述、inputSchema、严格模式标记和 needsApproval 交给 Vercel AI SDK（tool-transform.ts:35），只读、并发安全、副作用范围这些旗标都留在 ZCode 内部。严格模式要同时满足：契约声明 strict、provider 是 anthropic、模型是 Anthropic 首方模型（tool-transform.ts:85）；声明了 requiresMfjsToolSchema 的模型只接受 #/$defs/ 形式的引用，适配层会把 MCP schema 里其他本地引用提升过去（tool-transform.ts:95）。适配层的其余部分见模型适配层。

参数不合格时，模型收到什么

执行器拿到模型的入参后，先归一化：顶层是 JSON 字符串就解析（有的适配器和钩子路径会把入参交成字符串），再用 zod 的 runtimeInputSchema 跑一遍 safeParse，成功就用补过默认值的结果，失败就保留原始入参和 zod 的 issue（apps/zcode-cli/packages/core/src/tool/input-normalization.ts:40）。随后用 JSON Schema 做准入校验（apps/zcode-cli/packages/core/src/tool/executor/validation.ts:71）。这个校验器是个最小子集：支持 oneOf、const、enum、type、字符串长度、数值范围、数组长度与 items、required、additionalProperties: false，不认 pattern、format（apps/zcode-cli/packages/core/src/tool/json-schema.ts:53）。正则、URL 这类约束靠 zod 的 issue 补进报错。注意准入的硬门是 JSON Schema：它通过而 zod 失败时，调用会继续往下走，交给工具的 validateInput 或 handler 兜底（validation.ts:77）。

校验失败时，给模型的内容由 apps/zcode-cli/packages/core/src/tool/input-validation-model-content.ts:12 组装：

export function createInitialInputValidationModelContent(
  entry: ToolEntry,
  jsonIssues: readonly ToolInputValidationIssue[],
  runtimeIssues: readonly RuntimeInputValidationIssue[] | undefined,
): string {
  const issues = projectInitialModelValidationIssues(entry.inputSchema, jsonIssues, runtimeIssues);
  return `<tool_use_error>InputValidationError: ${formatToolInputValidationError(
    entry.metadata.name,
    issues,
  )}</tool_use_error>`;
}
  // ...
  const lines: string[] = [
    ...missingParameters.map((parameter) => `The required parameter \`${parameter}\` is missing`),
    ...unexpectedParameters.map(
      (parameter) => `An unexpected parameter \`${parameter}\` was provided`,
    ),
    ...wrongTypes.map(
      ({ expected, param, received }) =>
        `The parameter \`${param}\` type is expected as \`${expected}\` but provided as \`${received}\``,
    ),
  ];

缺参数、多参数、类型不对三类问题各给一句人话，有这三类问题时其他问题一概省略（input-validation-model-content.ts:107）；只剩取值不在枚举里、长度超限、正则不匹配这类问题时，才把 issue 列表整个序列化成 JSON 交给模型（input-validation-model-content.ts:65）。比如调用 Read 时漏了 file_path，模型收到的是：

<tool_use_error>InputValidationError: Read failed due to the following issue:
The required parameter `file_path` is missing</tool_use_error>

这些 issue 的形状值得一提：invalid_value、invalid_format、带 origin 的 too_big，以及 Invalid input: expected string, received undefined 这样的措辞（apps/zcode-cli/packages/core/src/tool/tool-input-validation-issues.ts:5、tool-input-validation-issues.ts:87），都是 Zod 4 的格式，而 contracts 依赖的是 Zod 3（apps/zcode-cli/packages/contracts/package.json:99）。投影层专门把 Zod 3 的码翻译成目标格式（input-validation-model-content.ts:331），并逐字段对齐顺序，注释反复强调这些字段的插入顺序“会直接进入 provider-visible JSON fallback，必须保持稳定”（tool-input-validation-issues.ts:1）。

另外几种失败的写法：

• 工具专属校验（validateInput、resolveInput）或 handler 以返回值表达业务失败时，模型看到 <tool_use_error> 包着的那句 message，错误码另记在结果里（apps/zcode-cli/packages/core/src/tool/executor/errors.ts:20）。
• 工具名不存在时模型看到 Tool not found: <name>（apps/zcode-cli/packages/core/src/tool/executor/call-runner.ts:128）；名字是空白时则是 <tool_use_error>Error: No such tool available: </tool_use_error>，末尾原样保留模型返回的空白名（call-runner.ts:138）。
• PreToolUse 钩子改写过的入参会再校验一次，但失败时不再生成上面这段面向模型的说明（validation.ts:79），因为那已经不是模型自己写出的参数。

路径策略

文件类工具都用 resolveWorkspacePath 解析路径（apps/zcode-cli/packages/core/src/tool/path-policy.ts:15）：工作目录和工作区根必须是绝对路径，否则算配置错误；空路径直接报错；绝对路径只做 normalize，相对路径相对于当前工作目录解析。关键在它不做的事（path-policy.ts:32）：

  const resolvedPath = isAbsolute(requestedPath)
    ? normalize(requestedPath)
    : resolve(workingDirectory, requestedPath);

  // Current release intentionally does not hard-block paths outside workspaceRoot.
  // Cause: subagents may need to inspect user-requested sibling repos or external files
  // before the filesystem permission adapter grows explicit ask/deny rules for them.
  return resolvedPath;

也就是说，工具层不以工作区为边界，工作区外的读写只受权限模式约束（Bash 的工作目录另有重置规则，见 Bash：解析、只读判定与后台任务）。比较路径时用的是 normalizeToolPathForComparison（apps/zcode-cli/packages/core/src/tool/path-normalization.ts:15）：Windows 上把 Git Bash 风格的 /c/... 转成 C:\...（path-normalization.ts:30），剥掉 \\?\ 长路径前缀但保留设备命名空间（path-normalization.ts:45），盘符统一大写；所有平台最后都做一次 Unicode NFC 归一。读文件状态表就用它生成键（apps/zcode-cli/packages/core/src/tool/read-file-state.ts:15），避免同一文件因写法不同被当成两个文件。

内置工具全表

下表覆盖 builtInTools 的全部 40 个条目。“只读”是 metadata.readOnly 的声明值；handler 列是 apps/zcode-cli/packages/core/src/tool/handlers/ 下的文件。

几处“只读”要结合副作用范围看：TodoWrite、Agent、Task 都声明了 readOnly: true，范围却是 session（apps/zcode-cli/packages/core/src/tool/handlers/todo.ts:140、agent.ts:229），调度器只把“只读且范围为 none”的调用当作真正的只读（下一篇细说）。Bash 声明为非只读，但会按命令内容重算：判定为只读的命令（如 ls、git status）改记为只读、低风险、免审批、范围 none（bash.ts:77）。

下一篇：执行器：调度、审批、超时与结果——一批工具调用怎样分组并发，单个调用怎样走完校验、钩子、审批、执行与结果投影。