version: "1.0.0" name: hook-governance-layer description: Design, review, or extend hook-based governance layers for tool runtimes with pre and post hooks, permission mediation, continuation control, additional context injection, and non-fatal hook errors. Use when Codex needs to build or audit hook systems, policy middleware, or execution governance around tools.

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 control with a dedicated signal instead of overloading deny behavior.
• Make hook errors observable without turning the governance layer into a single point of failure.

Failure Modes

• Treating hook allow as final allow and bypassing core permission rules.
• Emitting both blockingError and hook_blocking_error for the same event.
• Letting hook exceptions kill the whole tool pipeline.
• Giving non-MCP tools the ability to rewrite output through MCP-specific pathways.
• Leaving continuation behavior implicit and forcing callers to guess from text.

Output

• Produce a hook contract matrix for each lifecycle event.
• Produce governance merge rules that define how hooks interact with the permission system.
• Produce a non-fatal error policy that says which hook failures block and which only inform.