Hooks: The Enforcement Layer
Rules propose. Hooks enforce.
The Learner Brain's meta-learning loop ends at codify: a correction becomes a rule, the rule is loaded into context, and the agent is expected to follow it. Most of the time it does. But every experienced user knows the failure mode — the rule the agent keeps ignoring anyway.
Hooks close that gap. A hook is a small shell script that fires at a fixed point in the agent loop — before a tool runs, after a file is edited, when the agent tries to stop. Instead of hoping the agent follows the rule, the hook guarantees the outcome: the dangerous command is denied, the typecheck runs, the stop is blocked until tests pass.
The Enforcement Ladder
Every behavior in a Learner Brain lives at one of three levels. The goal is to climb the ladder only as far as the behavior requires:
1. Proposed
A rule in context. The agent reads it and is expected to follow it.
Cheap, flexible, occasionally ignored.
2. Enforced
A hook in the loop. The behavior is guaranteed by a script, not by attention.
Deterministic, testable, slightly higher maintenance.
3. Governed
The hook itself is reviewed, versioned, and git-tracked like any other code.
Hooks are rules too — they answer to the same governance.
The one-sentence version
Why the Meta-Learning Loop Needs Hooks
The original loop — work, hit friction, detect the pattern, propose the upgrade, codify the memory — assumes that codified means followed. In practice there's a second kind of friction: the rule exists, the agent violates it anyway, and you pay the correction cost again. That's the same Dumb Agent Tax wearing a different hat.
Hooks extend the loop with one extra edge:
Work → Friction → Pattern Detected → Upgrade Proposed
→ You Approve → Codified as a Rule
→ Rule violated again? → Graduates to a Hook
→ Enforcement is now deterministic
→ The correction never reaches you againThe result is the same as every other Learner Brain upgrade: fewer corrections over time — except this time the correction never even reaches you, because the hook caught it first.
When a Rule Graduates to a Hook
Not every rule should become a hook. Hooks add maintenance surface, and a hook for a preference ("prefer early returns") is unenforceable nonsense. Graduate a rule only when all four are true:
The rule has been violated 3+ times
One miss is a mistake. Three misses means the rule is not being loaded, weighted, or followed — stop hoping and start enforcing.
The check is deterministic
A script can verify it in under a second: a path pattern, a command pattern, a lint result, a test exit code.
False positives are rare
A hook that blocks legitimate work gets disabled within a week. Test the pattern against your real history first.
The script is fast
Hooks run inside the agent loop. Anything slower than a few seconds taxes every single turn.
The reverse is also true
Platform Support
Hooks are a platform capability, not a file convention — so support varies more than the rest of the methodology. Where your tool exposes lifecycle hooks, the Learner Brain enforcement layer plugs in directly:
Claude Code
PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, SubagentStop, PreCompact, Notification, SessionEnd
Browse the libraryCodex (CLI + VS Code)
before_tool_use / after_tool_use — deterministic shell actions registered in Codex's TOML config. The CLI and VS Code extension share the same engine.
Browse the libraryCursor
beforeSubmitPrompt, beforeShellExecution, afterFileEdit, stop
Browse the libraryOther platforms
Where a tool has no hooks system, keep the rule in instructions and revisit when the platform adds one. The scripts in these libraries are portable — when your tool adds hooks, they move with you.
See templatesThe Risk Framework
Every hook in the Learner Brain libraries carries a risk level. It maps to how much you should trust the hook on day one:
Low risk
Reminders, context injection, logging. Cannot block anything — safe to enable immediately.
Medium risk
Runs project commands (lint, typecheck) or blocks specific patterns. Test on real work first.
High risk
Gates the agent loop itself (blocking stop until tests pass). Powerful — enable last, watch closely.
Hooks run real commands
Hooks Are Rules Too
The human-in-the-loop principle does not relax for hooks — it extends to them:
Hooks enforce rules you already approved — they never introduce new policy on their own.
Every hook is git-tracked with the brain. If you can't explain why a hook exists, delete it.
A hook change is a brain change. Review it like a rule proposal: does it reduce future work? Is it reversible?
Audit hooks with the brain: which ones never fired in 30 days? Which ones you keep cursing at? Prune.
Start Enforcing
Pick your platform and copy a starter set. All three libraries follow the same rules: every script is copy-ready, risk-labeled, and sourced from the official docs.