工具定义原语与执行管线

结论：ToolRuntime 不是函数表，而是一条把不可信模型调用提交为可重放结果的事务边界

最值得学习的不是“有 hooks”，而是每一层能改什么都不同：pre 不能改已记录参数；guard 只能拒绝；around 只能临时替换 signal 并包裹 body；post 可以替换 canonical value 或 model content；finalizer 只能改 content；result observer 什么都不能改。

1. 一个工具定义同时包含四份合同

2. 模型 schema、执行 value、耐久 content 与 UI meta 是四种不同数据

model args string
→ parsed + lossless snapshot + frozen arguments
→ execute() returns canonical JSON value
→ output.schema validates value
→ output.render(args, value) produces model-facing ContentBlocks
→ presentationMeta(args, value) optionally produces replayable UI JSON

execution-local result: { value, content, meta? }
durable tool/result:     { content, isError, errorInfo?, meta? }
future model Surface:    content only

这让 Code Mode 可以把结构化 value 交给程序继续计算，同时主模型只看到渲染后的受控文本；也避免 UI 为了显示 diff、line numbers 或 web sources 去反向解析自然语言结果。

3. Schema DSL 是受约束的 JSON Schema 子集，不是完整规范

参数根由 DSL 编译成隐式 open object；嵌套显式 object 必须写 additionalProperties: true|false。因此“工具参数默认拒绝额外键”并不成立，除非作者在相应显式对象层选择 closed shape。

4. 只有 defineTool() 自动执行参数校验

这不是第一方工具的缺口——它们使用 helper——但它是 extension author 的重要 trust boundary。把 raw registration 当作“registry 会替我 validate”会把任意 JSON 送进 body。

5. Scope view 先解析继承能力，再应用限制和本地 shadow

global tools
→ ancestor scope registrations (nearer shadows farther)
→ intersect every restriction along the scope chain
→ exact scope's own registrations (exempt from inherited filter)
→ reserved run_code transport when mode requires it

get()、model schema、SDK 和 dispatch 共用这个 view，降低“提示看见 A、执行却调用 B”的漂移。但定义与限制是 live effects：排队中的调用到真正 start 前仍可看到 registry change，这也是第 18 章重分类语义的基础。

6. Native、Code 与 Both 改的是模型入口，不是三套工具实现

在 code-only mode，native name 虽然用于 SDK catalog 仍“可见”，但 model-direct execution 会在 pre hooks、审批和 guards 之前确定性拒绝，避免 policy 误批准一个注定不能执行的入口；错误文本告诉模型应从 run_code 内调用。

7. 每次调用先获得不可伪造 identity，再进入 policy

8. 完整管线：不同扩展点拥有不同权限

9. Pre-policy 与 Guard 刻意不能改 arguments

模型原始 argument string 已经作为 tool/call 写入日志，UI 也会用它展示 pending state。若 pre hook 可以替换 args，日志会声称执行了 A，body 实际收到 B，request replay 与审计都失真。因此 PreToolDecision 没有 rewrite arm。

审批的细节留给第 19 章；这里的核心性质是：可扩展 policy 可以提出允许意图，owner guard 仍有不可逆的最后拒绝权。

10. Around wrapper 可以换 signal，但不能切断 caller cancellation

tools/execute 适合 timeout、retry、metrics 等 around concerns。Wrapper 可以在委托期间替换 mutable exec.signal；ToolRuntime 在 body 前把这个 signal 与原 caller signal 融合，body settle 后移除 listeners 并恢复 wrapper view。

11. 成功 value 必须先过三道边界，才能成为 canonical result

12. Post-policy 可替换 value 或 content，但两者不能同时替换

Content replacement 是刻意的 presentation/policy seam：它可以做脱敏、spill preview 或纠正反馈，而无需伪造新的 canonical value。代价是日志里的文本不再能证明 body 原始 render；需要 telemetry 或 tool-owned事件保留更早证据。

13. finalizeContent 是工具拥有的最后不变量

Finalizer 在调用开始时就从当时 visible definition 捕获，防止 arguments getter 或热重载在 snapshot 期间替换回调。它在所有 normalized outcome 上恰好尝试一次，包括 pre/around/post failure；它只能返回替换 content，不能改 isError、value、meta、contexts 或 concludesTurn。

14. Additional context 和 conclude-turn 是结果携带的控制信号

Tool body 可调用 exec.deferContext(userMessage)；post policy 也可附加 contexts。它们不在 body 中直接 append，而随最终 result 回到 Agent loop。Loop 先按模型顺序写完对应 tool/result，再把 contexts 放进 active-batch FIFO，下一 Step 才以拥有各自 source/meta 的 user messages 提交。

这避免 side-channel context 插进 call/result 邻接中间，也让 composite transport 把 nested context/terminal signal 通过父结果显式转发，而不是直接突变父 Agent 的 inbox。

15. 顶层工具耐久性由 Agent loop 拥有，Registry 本身不写 Session

assistant/tool_call block
→ append tool/call (raw argument string)
→ ToolRuntime staged pipeline
→ append tool/result (final content + isError + error info + meta)
→ accept result.additionalContexts
→ next Step boundary

直接从其它进程内组件调用 ctx.tools.execute() 只得到 frozen result，不会自动产生顶层 Session events；若没有 Agent，审批 ask 也无法路由并 fail closed。Code Mode 是特例：outer run_code 仍由 loop 记账，bridge 另写 log-only nested dispatch events。

16. UI Presenter 是 provider-neutral render intent，并且必须可 replay

17. 失败归一化按“body 是否启动”和“失败在哪一层”分类

errorMessage() 还对 hostile thrown value 做 total fallback，防止错误规范化自身再 throw。成功与失败最终都必须成为 lossless frozen snapshot，调用方无需用 exception control flow 区分普通工具失败。TOOL-DECISIONSTOOL-CANCELLATION

18. Runtime invariant 证明顺序与冻结，但不证明业务策略正确

它不会验证某个 raw tool 是否真的按 parameters schema 校验输入、timeout wrapper 是否加载、isConcurrencySafe 声明是否业务上安全、presenter 是否纯，也不会判断 policy 给出的 allow/deny 是否符合组织规则。Invariant 保护协议形状，不替代 capability owner 的策略测试。

19. 已确认的边界、动态窗口与设计取舍

20. 设计评价与验证状态