--- name: avizmarlon/hooks-for-enforcement source: https://app.decimal.ai/s/avizmarlon-hooks-for-enforcement@1/SKILL.md source_sha256: a502e8bb5ee3 --- ## Hooks as Enforcement Mechanism for AI Behavior When AI behavior requires **enforcement** (preventing a repeated failure mode despite written rules), hooks are the structural solution — not additional rules, not wrapper skills, not optional validators. ### Why Hooks Matter - **Written rules** are interpreted during generation and depend on the AI's inference loop. The same attention/pattern-matching mechanism that fails under load may skip the rule. - **Skills and wrapper agents** are invoked *by* the AI. If the AI is failing to invoke them or forgetting to apply them, adding more rules about invoking them repeats the problem. - **Hooks** are invoked *by the system* at fixed lifecycle points, outside the generation loop. The AI cannot skip them, forget them, or pattern-match around them. ### When to Use Hooks: Decision Tree | Problem | Wrong Approach | Right Approach | |---------|---|---| | AI breaks a rule in generation despite rule being written | Add more detailed rule text to instructions | Hook that executes at a fixed lifecycle point (e.g., before output) | | AI forgets to invoke a critical skill | Write "remember to invoke skill X" | Hook that blocks/gates generation until invoked, or hook that injects the skill's effect | | AI needs to check a fact every turn | Add fact to instructions as a bullet | Hook that injects the fact into context at SessionStart or UserPromptSubmit | | AI must stop before producing incorrect output | Write "verify before responding" | Hook that audits the response text at Stop, before delivery | ### Implementation Pattern A hook executes at a known lifecycle event with access to the AI system state: - **SessionStart** — inject context, prime state, load reference data - **UserPromptSubmit** — validate/enrich the user's message before sending to model - **PreToolUse** — gate or validate tool invocations - **PostToolUse** — audit tool output, detect failure modes - **Stop** — audit response text before delivery to user, block unsafe outputs ### When to Switch from Rules to Hooks If a rule has **failed ≥2 times by the same failure mode** despite being documented and despite the AI acknowledging it, writing more rule text will not fix it. The design was wrong. Switch to a hook at the appropriate lifecycle point. ### Anti-Patterns (Do Not Do These) - Adding a 6th, 7th, or 8th restatement of a rule that already failed twice → use a hook instead. - Creating a "verify-before-responding" skill that the AI is supposed to invoke → the AI will forget or skip it; same bug, different form. - Creating a wrapper agent that the AI can optionally call → optional means no enforcement. - Expecting rule text to prevent a behavior the AI's inference loop is optimizing toward. ### Example: Preventing Confabulated Citations **Wrong approach (fails):** Add rule "never cite a fact without checking the transcript first." The AI reads the rule, nods, and then in generation (high token velocity, pattern matching) produces a plausible-sounding citation without checking. The rule was there; the inference loop optimized it away. **Right approach (works):** Hook at Stop that parses the response text, finds citations, cross-checks them against the session transcript, and blocks the response if citation is not present. The hook runs outside the generation loop. The AI cannot skip it. The citation either exists or the output is rejected. ### Distribution Across AI Platforms - **Claude Code** — full lifecycle hook support via `~/.claude/hooks/` - **Codex CLI** — lifecycle hooks available via feature flag - **Cursor / Gemini / Other platforms** — limited or no lifecycle hook access currently. For these, rules remain the primary mechanism. If a behavior mode fails repeatedly and requires hooks to fix, escalate to a platform with hook support (Claude Code / Codex) for audit/enforcement, then sync the result back. ### Governance Hooks are powerful and should be used deliberately: 1. **Diagnosis first** — confirm that the rule is written, clear, and the AI is aware of it (appeared in a prior turn or is in system instructions). 2. **Attempt ≥2 times** — run the scenario ≥2 times with the rule in place. If it fails the same way both times, rule-based approach is insufficient. 3. **Hook scope** — hooks should be narrow (audit one thing, block one failure mode) and well-documented (what does this hook enforce? why is it needed?). 4. **Lifecycle choice** — pick the earliest lifecycle point where enforcement is possible. SessionStart hooks scale better than Stop hooks because fewer tokens flow before rejection. ### Documentation Template When adding a hook: ``` Hook name: Lifecycle: Trigger condition: Mechanism: Why not a rule: Audit/rollback: ``` ### See Also - Claude Code documentation on hooks and lifecycle events - Your platform's hook/plugin system documentation