# ADR-0133：不可变 Tool Registry 与 Policy-fenced Invocation Plan

- 状态：Accepted（profile-neutral ToolDefinition registry、受限 JSON Schema、
  Project Policy 聚合、Agent Approval 判定和 digest-bound invocation plan 已实现；
  handler、StepRun、preview、ApprovalRequest publisher、MCP/HTTP adapter 与生产组合仍
  未开放）
- 日期：2026-07-24
- 关联 RFC：QL-RFC-0001 D-08、D-09、D-131

## 背景

AI Agent、MCP、Package 和内置功能都需要调用 Tool。如果每个入口各自：

- 解析一份 Tool schema；
- 猜测权限和审批要求；
- 直接持有 handler；
- 在运行期注册或扫描 Tool；

就会出现权限旁路、不同输入语义、插件移除后的行为漂移和低配设备常驻开销。
现有 `ProjectPolicyEngine` 已经提供稳定 Principal、Project permission 和
Project/RoleBinding version fence；Tool 层必须复用它，不能建立第二套 RBAC。

## 决策

### 1. Tool Registry 留在 `@qinglong/runtime-core`

新增 `tool-registry` subpath，不新增 workspace package或第三方依赖。Registry 在受信
composition root 中一次性接收 0–128 个 definition，构造后冻结，不提供 `register`、
目录扫描、watcher、timer、socket、数据库或 handler 注入。

同一 `(name, version)` 只能出现一次。Tool name 必须是小写分段标识，version 必须
是 canonical SemVer。调用必须精确指定 version，不提供 latest、wildcard 或运行期
fallback。

### 2. 首版只实现有界 JSON Schema 子集

QL3 不在核心中接受任意 JSON Schema draft。首版只允许：

- `null`、`boolean`；
- 有显式 `maxLength` 的 `string`，可选 `minLength` 和有界 enum；
- 有显式安全上下界的 `number`、`integer`；
- 有显式 `maxItems` 的 array，可选 `minItems`、`uniqueItems`；
- `additionalProperties: false` 的 object，显式 properties 和 required。

拒绝 `$ref`、`oneOf`、`anyOf`、任意 regex、默认值、coercion、未知 keyword 和
开放 additional properties。Schema 深度最多 8、节点最多 256、object properties
最多 64、enum 最多 64、array 最多 256 项。

Tool input 根必须是 object。canonical input 最大 64 KiB，output 最大 256 KiB。
没有 `outputSchema` 的 Tool 只能返回 `null`，不能把“未声明 output”解释为任意输出。

### 3. Registry 不拥有执行能力

Definition 只包含：

- name、version、description；
- input/output schema；
- `read | write | execute | external` effect；
- `low | medium | high | critical` risk；
- 最多 16 个 Project permission；
- 1–3600 秒 timeout。

Registry 只规范化 definition/input/output 和生成 invocation plan。Definition、
Registry 和 plan 均不包含 `execute`、handler、数据库 service 或网络 client。
Package、MCP 或 Agent 不能通过注册 Definition 把代码注入控制面。

### 4. 每次调用先 Policy，后解析输入

`prepareToolInvocation` 固定执行：

1. 精确解析 request envelope 和 Tool identity；
2. 验证当前 Principal；
3. 对 `tool.call:{name}` 和 Definition 的每项 required permission 调用既有
   `ProjectPolicyEngine.authorize` 端口；
4. 任一 deny 立即停止，且不解析 Tool input；
5. 所有非 deny decision 必须包含完全相同的 Project/RoleBinding fence；
6. 任一 decision 为 `require_approval` 时生成 `approval_required` plan；
7. 只有之后才按 schema 规范化 input，并生成 input/action SHA-256。

Policy 存储异常、畸形 decision、空 fence 或不同 fence 混用全部失败关闭。这样多
permission Tool 不能把不同 Project 版本或 revoke 前后的授权拼成一个调用。

### 5. Action digest 是 Approval/Dispatch 的稳定输入，不是执行授权

action digest 绑定：

- `qinglong/tool-invocation@v1`；
- Project、稳定 actor subject；
- exact Tool name/version；
- `tool.call:{name}` 和 required permissions；
- effect、risk、timeout；
- canonical input digest。

它不保存 input、Prompt、Secret 或 handler，也不等于已审批。`approval_required`
仍必须由后续 preview builder 产生 preview digest，再进入既有
ApprovalRequest/immutable dispatch/start barrier。`ready` plan 也必须由受审 handler
registry、StepRun/Trace/Audit 组合消费；本 ADR 不提供直接 execute seam。

## 影响

- AI Agent 通过真实 Project Policy 调用任意 Tool 时，`tool.call:*` 继续返回
  `require_approval`。
- MCP、Package 和内置 Tool 共用同一 schema、permission 和 fence 语义。
- edge 只在显式 Tool 调用时支付 schema/input 规范化成本；禁用 Tool 时零 timer、
  socket、数据库和后台进程。
- `packages/` 数量不增加，runtime-core 只增加一个源码文件和 subpath。

## 未完成边界

以下内容仍需独立闭环：

- built-in/package Tool handler registry；
- ADR-0150 已完成 Package Tool JSON 到 ToolDefinition 的来源/PackageLock/
  generation 绑定；全部 active generation 的全局 immutable snapshot 仍未完成；
- preview/dry-run 和 ApprovalRequest publisher；
- Approved Action handler、receipt/evidence provider；
- StepRun、Trace、redaction 和 durable audit；
- MCP Server、MCP Client、HTTP/API 与 Agent adapter；
- Tool version retirement 与历史 Run/PackageLock 解析。

在这些能力完成前，Tool Registry 保持 production unreachable。

## 验证

测试必须覆盖：

1. immutable registry、exact version 和无 runtime register；
2. root/subpath 导出一致；
3. JSON Schema exact subset；
4. schema depth/node/property 上限；
5. canonical input/output、未知字段与 unique array；
6. 无 output schema 时只允许 null；
7. 同一 Policy fence 的 digest-bound ready plan；
8. 真实 Project Policy 下 Agent Tool call 需要审批；
9. deny 在 input 解析前短路；
10. Policy unavailable、畸形 decision 和 mixed fence；
11. 过期 Principal 与扩展 request 拒绝；
12. canonical envelope byte budget；
13. 无 filesystem/process/network/timer/execute authority。