hook-governance-layerlisted

# Hook Governance Layer ## Overview Design hooks as a governance layer, not as the execution layer itself. Hooks should inject policy, add context, modify MCP output, or stop continuation without corrupting the underlying tool protocol. ## Source Anchors - `src/services/tools/toolHooks.ts` - `src/services/tools/toolExecution.ts` ## Workflow 1. Define the lifecycle events first: `PreToolUse`, `PostToolUse`, and `PostToolUseFailure`. 2. For each event, define the allowed result fields such as `updatedInput`, `permissionBehavior`, `additionalContexts`, `blockingError`, `preventContinuation`, and `updatedMCPToolOutput`. 3. Resolve pre-hook permission results through the base permission system so hook allow does not bypass rule-based deny or ask decisions. 4. Normalize post-hook side effects into separate channels for messages, blocking, added context, continuation control, and MCP output changes. 5. Treat hook cancellation and hook error as visible but non-fatal events unless product policy explicitly requires fail-closed behavior. 6. Measure wall-clock hook time so "the system feels stuck" can be diagnosed accurately. ## Design Rules - Keep the hook contract strongly typed instead of encoding control semantics in free text. - Deduplicate blocking output so one policy decision does not render twice in the UI. - Allow `updatedMCPToolOutput` only for MCP tools. - Let hooks add context, but do not let them silently redefine the base execution protocol. - Model continuation c