Hooks + Plugins (Implementation): priority, parallelism, fault isolation

This page complements Hooks + plugins governance with an implementation-oriented view.

Code entry points (optional)

• 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

Registration-time state machine

Conflicts must be rejected with diagnostics (methods/routes/commands); don’t “last writer wins”.

Runtime state machine (HookRunner)

You need two execution models:

1. void hooks: run in parallel; default catchErrors=true.
2. modifying hooks: run serially by priority; merge rules must be stable.

Injection points (placement matters)

1. before agent start (prepend context)
2. before tool call (patch/block)
3. after tool call (audit, success + failure)
4. agent end (summary snapshot + duration)

Failure modes and troubleshooting

• A single plugin breaks the main flow: confirm catchErrors and fire-and-forget audits.
• Unpredictable multi-plugin behavior: verify priority ordering and deterministic merge rules.

Acceptance checks

1. higher-priority hooks run first.
2. void hooks don’t block main replies.
3. conflicts produce diagnostics, not silent overrides.