Hook 与插件注入状态机实战：优先级、并行、故障隔离

这一章补齐 Hook 与插件治理 的“实现手册”部分。

对应源码入口（可选）

• src/plugins/loader.ts
• src/plugins/registry.ts
• src/plugins/hook-runner-global.ts
• src/plugins/hooks.ts
• src/agents/pi-tools.before-tool-call.ts
• src/agents/pi-embedded-runner/run/attempt.ts
• src/agents/pi-embedded-subscribe.handlers.tools.ts

注册期状态机（加载阶段）

目标：冲突不覆盖，必须拒绝并留下 diagnostics（method/route/command 等）。

执行期状态机（HookRunner）

你需要两种执行模型：

1. void hooks：并行执行（吞吐优先），默认 catchErrors=true，单插件失败不拖垮主流程。
2. modifying hooks：按 priority 串行执行（结果可预测），并用稳定 merge 规则合并。

主链路注入点（位置比“能注入”更重要）

1. Agent 启动前（prepend context）
2. 工具调用前（before_tool_call：改参/阻断）
3. 工具调用后（after_tool_call：审计，成功/失败都触发）
4. Agent 结束（汇总快照与耗时）

失败场景与排障入口

• 单个插件拖垮主链路：优先检查 hookRunner 是否默认 catchErrors=true，以及 after_tool_call 是否 fire-and-forget。
• 多插件结果不可预测：确认 modifying hooks 按 priority 顺序执行，并且 merge 规则稳定可解释。

验收清单

1. priority 高的 hook 先执行。
2. void hooks 并行且不阻塞主回复。
3. 注册冲突会输出 diagnostics，而不是静默覆盖。