工具策略与审批状态机实战：pipeline + exec approvals

这一章是实现手册：把“工具安全”落到可编码的 pipeline 与审批状态机。

入口（概念版）：

• 工具策略与执行审批
• Sandbox vs tool policy vs elevated

对应源码入口（可选）

• src/agents/pi-tools.ts
• src/agents/tool-policy-pipeline.ts
• src/agents/pi-tools.before-tool-call.ts
• src/agents/pi-tool-definition-adapter.ts
• src/infra/exec-approvals.ts
• src/gateway/exec-approval-manager.ts
• src/gateway/server-methods/exec-approval.ts

你要复刻的两条主线

1. 工具策略 pipeline：把“哪些工具可用”做成可解释的过滤链路。
2. exec approvals：把“高风险命令是否执行”做成可观测的两阶段状态机。

工具策略 pipeline（建议固定 5 步）

1. owner-only 裁剪（默认安全：非 owner 不暴露高风险能力）
2. 多层策略过滤（按固定顺序收紧）
3. schema 规范化（避免 provider 因 schema 形态拒绝）
4. before_tool_call 注入（改参/阻断）
5. 可选：abort signal 贯穿执行（让取消语义可传递）

exec approvals 状态机（请求 → 等待 → 决策 → 超时）

你至少需要保证这些行为：

• 同一审批 id 的 waitDecision 幂等（不会分裂为多个 Promise）
• 超时返回 null（调用方显式处理）
• 已决条目保留短暂 grace 窗口，避免两阶段调用竞态

失败场景与排障入口

• waitDecision 偶发拿不到 id：优先检查“先 register 再响应 accepted”的时序；用 Gateway 协议 对照方法调用顺序。
• after_tool_call 审计丢失：确认失败路径也会触发 after_tool_call，且以 fire-and-forget 方式运行（避免阻塞主链路）。

验收清单

1. pipeline 顺序固定，可解释“哪一步过滤掉了工具”。
2. before_tool_call 可改参/阻断，after_tool_call 成功/失败都触发。
3. 审批超时可恢复，不会无限挂起。
4. 高并发下不会因参数暂存机制无上限导致内存增长。