fix(tools): 修掉两个假阳性与一个改得动的内部状态，按两轮独立评审

代码审查（新鲜上下文，只给 diff 与验收标准）报了五条影响正确性的，逐条核实全部成立：

1. spec_for() 交出去的 parameters 就是注册表内部那份真字典。docstring 承诺的快照只挡住了
   「调用方改自己那份」，没挡住「从注册表取出来往里伸一层改」——而后者一下同时改掉模型
   看见的 schema 和校验用的 schema。改成逐层冻成只读视图，schema_for_model 出口再化回
   普通字典与列表。
2. {type: integer} 拒掉 3.0。JSON Schema draft-06 起小数部分为零的浮点数是合法整数，
   模型写 1e2 时 json.loads 给的就是 float。这是我自己在注释里点名最怕的那种假阳性。
3. additionalProperties: false 撞上 patternProperties 时拒掉一切匹配 pattern 的键。
   那些正是这份 schema 专门要收的键，模型改名也绕不过去。patternProperties 在场就跳过。
4. 工具名不校验类型、纯空白名放行。名字要落进发给模型的 schema，不是字符串会让整个请求
   被网关拒掉，报错指向请求体不指向注册表。
5. _by_name 是可变 dict，两条查询路径能被就地改到分岔。换成只读视图。

不可哈希那条不修，改在 docstring 里写明（参数 schema 是映射，注册表放不进 set）。
scope.md 的行号引用换成条目名——行号是最容易漂的一种参数，插一行就静默指错。

0008 按一轮硕士生冷读重写：字段位置那段原来自相矛盾（一边说位置是公共承诺、插在中间会
静默改掉后面字段的含义，一边就插在中间，且没讨论追加在末尾这个同一判据下的显然选项），
改成追加在末尾并说明规则；补上四个名字的就地解释（重放策略、两条完成通路、动作结果五个
字段、restrict_to）；决策四那张表原来只有三列却被正文说成填五个字段，恒定的两个单列出来
并各自给了理由；补上 validate 不通过为什么算未执行、executor() 为什么全查、为什么必须是
具体类而不是闭包、异常栈去哪了。

research-wiki/design/0008-tool-handlers.md

@@ -22,8 +22,30 @@
 任何 handler，直接合成未执行」），但从没有任何一处把它写成字段或签名。所以这不是被写在别处
 的东西，是从没写过的东西。
 
-它和 `0007` 那三个问题是同一族：散文读着通顺，只有要写出那行代码时才发现缺了一样。这次是
-写实现时撞出来的，不是写契约测试时。
+它和 `0007` 那三个问题是同一族：散文读着通顺，只有要写出那行代码时才发现缺了一样。那三个是
+写契约测试时撞出来的，这一个是写实现时撞出来的。
+
+## 读本文需要的四个名字
+
+它们都定在别处，这里各给一句，免得读到一半得去翻另外三份文档。
+
+**`ReplayPolicy`（重放策略）** 是一个工具对「我幂等吗」的回答，两个取值：`SAFE` 说重复执行
+一次无害（读文件、检索），`NEVER` 说有不可重复的副作用（写文件、调外部服务）。它只在恢复
+时被用到：进程崩在「动作意图已写、结果还没写」之间，那个动作到底执行没执行是未知的，
+`SAFE` 的可以再跑一次，`NEVER` 的不敢（`0002` 决策四）。
+
+**两条完成通路，可信度不同。** `ToolSpec.completes_run` 是**注册表侧**的标记：这个工具一旦
+被成功执行就代表目标达成。它是 agent 自报——agent 调一个提交型工具宣布自己做完了，环境
+状态一点没变。`ActionOutcome.env_reported_completion` 是**环境侧**的信号：去问环境「目标达成
+了吗」，环境说达成了。两者都能让一次运行以「目标达成」收尾，但一个有环境侧证据、一个没有，
+所以不折算、不合并（`0006` 决策五）。
+
+**`ActionOutcome`（动作结果）** 是动作执行接缝的返回，五个字段：`status`（已执行 / 未执行 /
+环境故障）、`observation`（回填进模型对话历史的那段文本）、`observation_is_synthetic`
+（这段观察是不是库自己合成的，不是环境产出的）、`env_reported_completion`（上一段那个）、
+`observation_truncated_chars`（产出这段观察的人截掉了多少字）。
+
+**`restrict_to`** 是注册表上的收窄方法：按名字取子集，返回一个新注册表，原来那个不变。
 
 ## 决策一：实现挂在 `ToolSpec` 上，不另开一份清单
 
@@ -32,9 +54,9 @@ class ToolSpec:
     name: str
     description: str
     parameters: Mapping[str, object]
-    handler: ToolHandler | None = None      # 新增
     replay_policy: ReplayPolicy = ReplayPolicy.NEVER
     completes_run: bool = False
+    handler: ToolHandler | None = None      # 新增，追加在末尾
 ```
 
 另一条路是让 `executor()` 收一份「名字到实现」的映射。不选它，理由和 `0003` 决策四拒绝把
@@ -42,9 +64,10 @@ class ToolSpec:
 「模型调了一个它看得见的工具，库说找不到实现」——它看起来像模型不听话，不像配置错了。
 挂在规格上则不可能漂移：`restrict_to` 收窄的时候实现跟着规格一起走。
 
-**字段位置排在 `parameters` 之后、两个有默认值的字段之前。** 位置是公共承诺的一部分——
-下游按位置传参的那一天，插在中间会静默改掉每一个参数的含义。这个位置的理由是它和前三个
-一样属于「这个工具是什么」，后两个属于「怎么对待它」。
+**新字段追加在末尾，不插在中间。** 按位置传参的调用方那里，插在中间会静默改掉后面每一个
+参数的含义。现在还没有任何下游装上这个库，插在中间其实是安全的——但那样「这次能不能插」
+就成了一个每次都要重新判断的问题，而判断错的那次不会当场报错。**规则是「新字段一律追加
+在末尾」**，代价是 `handler` 和它语义上的近亲（前三个字段都在说「这个工具是什么」）隔开了。
 
 ## 决策二：`handler` 可以为空，缺了在 `executor()` 那一刻就报错
 
@@ -56,13 +79,16 @@ class ToolSpec:
 一致性校验。必填的话，这种项目要给每个工具写一个永远不会被调用的空壳。
 
 代价是「注册了工具却没有实现」变成一种可构造的状态。**这个代价由 `executor()` 兜**：它在
-被调用的那一刻检查本注册表里的每一份规格，只要有一份没有实现就直接报错，不等到分发时才
-发现。分发时才发现的话，那是运行到第几步才炸，而前几步已经花了钱、留了轨迹。
+被调用的那一刻检查本注册表里的每一份规格，只要有一份没有实现就直接报错。
+
+**全查而不是等分发时按需查。** 按需查的话，一个缺实现的工具要等到模型正好调它的那一步才
+炸，而那时前几步已经花了钱、留了轨迹，而且不同的运行会在不同的步数上炸。全查是一次遍历，
+工具数量是几十的量级，`executor()` 又只在装配时调用，成本可以忽略。
 
 ## 决策三：`handler` 是协程，收参数、返回一段观察文本
 
 ```python
-class ToolHandler(Protocol):
+class ToolHandler(Protocol):        # polyloop.tools
     async def __call__(self, arguments: Mapping[str, object]) -> str: ...
 ```
 
@@ -74,23 +100,30 @@ class ToolHandler(Protocol):
 调用对象递进去，实现就有机会去读 `name` 然后按名字分支，而那正好把「一个规格一个实现」这条
 结构拆掉。
 
-**返回一段观察文本，不返回 `ActionOutcome`。** 返回完整结果的话，一个被标了完成标记的工具
-可以在返回值里把完成位填成假，于是注册表上那个标记成了装饰品——`0003` 决策四要求完成标记
-必须和注册表的其余职责同源，正是为了防这个。状态、完成位、截断计数这三样由派生出来的执行器
-按决策四那张表填。
+**返回一段观察文本，不返回 `ActionOutcome`。** 返回完整结果的话，实现可以在返回值里把
+`env_reported_completion` 填成真——于是一个 agent 侧的工具就伪造出了一条环境侧证据，而上面
+那两条完成通路的区分正是为了不让这件事发生。同理，实现也可以把 `status` 填成「未执行」来
+逃掉预算计数。这些字段由派生执行器按决策四填，实现碰不到。
 
-**已知代价：截断计数填不进来。** `ActionOutcome.observation_truncated_chars` 记的是「产出这段
-观察的人截掉了多少字」，而返回 `str` 的实现没有地方报这个数。派生执行器一律填 0——它自己
-不截断，所以 0 是真值不是占位。一个在内部截断了输出的实现，那个数就丢了。
+**已知代价：截断计数填不进来。** `observation_truncated_chars` 记的是「产出这段观察的人截掉
+了多少字」，而返回 `str` 的实现没有地方报这个数。派生执行器一律填 0——它自己不截断，所以
+0 是这条路径上的真值，不是一个「不知道就填 0」的占位。一个在内部截断了输出的实现，那个数
+就丢了。
 
-现在接受这个代价，因为两个已知消费者都没有这个需求：那个字段是给「环境自己截断了输出」
-那条路用的，而那条路走的是项目自己写的执行器，不经过这里。真需要的那天，把返回类型从
-`str` 换成一个带默认值的小结构是破坏性变更——所以这一条是本文最该被驳回的一条，见文末。
+现在接受这个代价，因为两个已知消费者都没有这个需求：那个字段是给「环境自己截断了输出」那条
+路用的，而那条路走的是项目自己写的执行器，不经过这里。真需要的那天，把返回类型从 `str` 换成
+一个带默认值的小结构是破坏性变更——所以这一条是本文最该被驳回的一条，见文末。
 
-## 决策四：派生执行器怎么填 `ActionOutcome` 的五个字段
+## 决策四：派生执行器怎么填 `ActionOutcome`
 
-`executor()` 返回 `polyloop.tools` 里一个具体类的实例，它持有派生它的那个注册表。
-`RunRequest` 靠 `isinstance` 认出它、再比对注册表（`0006` 决策三）。
+`executor()` 返回 `RegistryExecutor`（住 `polyloop.tools`）的实例，它持有派生它的那个注册表。
+`RunRequest` 构造时用 `isinstance` 认出它，再比对它持有的注册表与本次可见的注册表
+（`0006` 决策三）。
+
+**返回一个具体类的实例，不是闭包也不是函数。** 那条一致性校验要在运行时判断「这个执行器是
+不是注册表派生的」，闭包和函数从外面看不出来源；具体类是唯一能被 `isinstance` 认出的形态。
+
+前三个字段随情况变：
 
 | 遇到什么 | `status` | `observation` | `observation_is_synthetic` |
 |---|---|---|---|
@@ -101,29 +134,43 @@ class ToolHandler(Protocol):
 | 实现正常返回 | `EXECUTED` | 它返回的那段 | 假 |
 | 实现抛 `CancelledError` | 不产出，原样穿出去 | | |
 
-`env_reported_completion` 恒为假，`observation_truncated_chars` 恒为 0。
+后两个字段恒定：`env_reported_completion` 恒为假，`observation_truncated_chars` 恒为 0。
 
-**「动作没有工具调用」这一档是装配错了**，不是模型错了：一个只认工具调用的执行器收到一段
-代码，说明这次运行把两种动作语言配串了。判成未执行而不是抛异常，是因为抛异常会终止整次
-运行，而这一档在轨迹里留一条记录、让停止判定按未执行走，事后能看见它发生过几次。
+**完成信号恒为假，是因为这条路径上根本没有环境可问。** 注册表派生的执行器手上只有一份工具
+清单，它问不出「目标达成了吗」。走这条路的运行靠 `completes_run` 收尾，而那一档由停止判定
+去查注册表，不经过动作结果（`0006` 决策六）。填成真会凭空造出一条环境侧证据。
+
+**`validate` 不通过算「未执行」，因为动作确实没有进入环境。** 工具名不认得、必填参数缺了，
+这两种情况下没有任何代码被执行、没有任何副作用发生，判成「已执行」会让预算计数把一次
+空转算成一次真的动作。它也不终止运行：模型收到一段说明之后完全可能下一步就调对了。
+
+**「动作没有工具调用」这一档是装配错了**，不是模型错了。库支持两种动作语言：一种是模型输出
+一次工具调用（工具名加参数），一种是模型输出一整段代码交给环境执行。一个只认工具调用的
+执行器收到后一种，说明这次运行把解释器和执行器配成了不同的语言。判成未执行而不是抛异常，
+是因为抛异常会终止整次运行，而这一档在轨迹里留一条记录、让停止判定按未执行走，事后能看见
+它发生过几次。
 
 **实现抛普通异常算「已执行」**，这条是 `0003` 决策四的原话：项目自定义工具里抛一个普通
 `ValueError`（参数解析时极常见）如果被判成「工具无效、不计有效步」，模型就能无限重试同一个
-坏工具直到上界耗尽。观察填成异常的类名加文本，不带调用栈——模型要的是「哪里错了」，调用栈
-对它没用，还会把库内部的路径喂进提示词。
+坏工具直到把步数上限耗尽——无效的工具调用不计入有效动作数，只计入总步数，靠总步数收敛。
 
-**`ToolEnvironmentError` 是新增的公共异常，让实现有办法说「环境坏了」。** 没有它，派生执行器
-永远产不出 `ENV_ERROR`，于是后端挂掉时模型会一遍遍重试、把预算烧光，而轨迹上表现成「预算
-耗尽」——`0003` 决策四点名过这种「安静地跑到预算耗尽」正是要防的。
+观察填成异常的类名加文本，**不带调用栈**。模型要的是「哪里错了」，调用栈对它没用，还会把库
+内部的路径喂进提示词。代价是排障时那个栈就没了：它既不进历史也不进事件流，因为异常对象在
+这一层已经被吃掉。真需要的话补在事件流那份 design doc 里，本文不预留。
 
-**这两档的观察都会被库丢掉。** `0007` 决策二定了未执行与环境故障两档的观察由库从
-`SyntheticObservations` 取，执行器给的那段不进历史。这里仍然认真填，是因为那段文本将来要
-靠事件流送出去做审计——进历史的东西必须可复现，进审计的不必。
+**`ToolEnvironmentError`（住 `polyloop.tools`）是新增的公共异常**，让实现有办法说「环境坏
+了」。没有它，派生执行器永远产不出 `ENV_ERROR`，于是后端挂掉时模型会一遍遍重试、把预算烧
+光，而轨迹上表现成「预算耗尽」——`0003` 决策四点名过这种「安静地跑到预算耗尽」正是要防的。
+
+**未执行与环境故障这两档的观察都会被库丢掉。** `0007` 决策二定了这两档回填进历史的观察由库
+从 `SyntheticObservations` 取，执行器给的那段不进历史。这里仍然认真填，是因为那段文本将来要
+靠事件流送出去做审计。两条路的要求不同：进历史的东西会被模型看见，因而必须可复现——同一份
+配置跑两次，模型两次看见的必须是同一段字；进审计的只被人看见，变了也不影响任何一次运行。
 
 ## 留给后续的
 
-**`observation_truncated_chars` 是本文最该被驳回的一条。** 决策三让实现返回 `str`，于是
-那个字段在这条路径上永远是 0。另一条路是返回一个带默认值的小结构（`observation` 加
+**`observation_truncated_chars` 是本文最该被驳回的一条。** 决策三让实现返回 `str`，于是那个
+字段在这条路径上永远是 0。另一条路是返回一个带默认值的小结构（`observation` 加
 `truncated_chars`），代价是多一个公共类型、而那个类型的第二个字段现在没有消费者。
 
 两条路的不对称在于改的方向：现在选 `str`、将来要改，是破坏性变更；现在选结构、将来不需要，