工具注册、调用与审批流水线
本页概述仓库中可核实的工具调用与审批接缝，并明确当前证据未能覆盖的注册和运行时实现细节。
目的与范围
范围限定为工具执行路径中与审批、守卫和结果处理有关的可见设计说明。文件系统工具的 fs/* 检查、PTC 子调用以及权限预设仅说明它们与流水线的交点；各自的完整机制应由对应专题介绍。由于本次源码读取预算已用尽，未能读取工具注册表、审批服务或 agent 调用入口的实际实现；以下不把生成文档脚本中的描述冒充经过实现验证的 API 契约。
概述
仓库的文档图生成脚本把审批称为 approval/request 上的一次性决策：应答方是监听者；没有应答方时以 unavailable 关闭请求。该脚本还说明工具执行由通用前后置 waterfall、ctx.approval、不可放宽的守卫和 tools/execute 周围的包装器参与；工具结果随后进入 tools/result。这是脚本中陈述的设计，不是本页独立验证过的运行时代码。参见 gen-doc-graphs.ts 和 gen-doc-graphs.ts。
架构
下图仅表示文档图生成脚本明确写出的关系；未展示未经核实的类、存储或 HTTP 端点。
Source: gen-doc-graphs.ts；gen-doc-graphs.ts
图中的顺序依照脚本对审批、守卫、执行包装与结果观察的叙述；具体注册方法、调用参数以及异常传播尚需核对运行时代码。
调用与审批流程
脚本中用于生成流程图的边表明：前置检查可以拒绝，也可以进入 ask；审批得到 allowed-once 后才进入守卫；拒绝、取消或不可用会跳过工具主体；审批抛出异常则进入归一化路径。守卫被描述为“monotonic”（只能拒绝或弃权，不能改变身份），用以保留不可被审批结果覆盖的所有者策略。以上是脚本记录的流程，具体事件订阅、错误对象和调用顺序仍须以实现为准。参见 gen-doc-graphs.ts、gen-doc-graphs.ts。
Source: gen-doc-graphs.ts
执行后结果
脚本说明 registry 对候选结果执行无损快照，快照失败会归一化；之后使用可见定义中快照保存的 finalizeContent 回调，遵守同步、仅修改内容的约束，最后 tools/result 观察不可变的无损 JSON 结果。它还指出超时等横切关注点包装 tools/execute，而非与单一工具族耦合。这里没有足够的实现证据确定快照格式、异常类型或回调的具体签名。参见 gen-doc-graphs.ts。
相关调用类型
脚本注明：文件系统读前编辑检查位于 tool-fs 的 fs/* 事件下方；PTC 模式让保留的 run_code 传输及序列化子调用经过流水线，子调用携带父令牌、记录 tool/ptc-dispatch，拒绝转为绑定拒绝，且省略 additionalContexts 以保持调用与结果邻接。这些是交互边界，而不是该模式的完整实现说明。参见 gen-doc-graphs.ts。
使用示例与 API 边界
No code example available：本次工具预算仅允许发现文件与搜索片段，未能使用 ReadFile 读取实现，因此不能提供符合“从已读真实源码提取”的代码示例，也不能给出未经核实的方法签名、参数、返回值或异常类型。已发现可能需要继续核对的工具入口为 packages/core/tools/src/index.ts，类型文件为 packages/core/tools/src/types.ts；此处不推断其中内容。
配置与权限边界
文档图生成脚本描述 permission/preset 会写入沙箱模式与审批策略两个设置事件；它提及 workspace-write 和 danger-full-access 预设。由于没有读取配置实现，不能确认类型、默认值、优先级或这些预设的实际授权效果。参见 gen-doc-graphs.ts。
| 可见标识 | 类型与默认值 | 已核实的作用范围 |
|---|---|---|
permission/preset | 未核实 | 脚本描述为一次切换写入，并传递到两个设置事件 |
workspace-write、danger-full-access | 未核实 | 脚本列举的面向用户的预设名称 |
失败模式与运行注意事项
- 无审批应答者：脚本称审批失败关闭为
unavailable；不可用、取消、拒绝均不运行工具主体。审批接缝、流程分支。 - 审批抛出异常：生成图描述为进入归一化分支；候选结果快照失败同样被脚本描述为归一化。具体归一化数据结构和是否重试未找到实现证据。gen-doc-graphs.ts、gen-doc-graphs.ts。
- 并发与性能：脚本只明确 PTC 子调用被序列化以及超时可作为
tools/execute周边关注点；无证据支持对并发限制、超时默认值、队列或重试机制下结论。gen-doc-graphs.ts。