hooks

Hooks

Purpose

Enforce a rule deterministically rather than asking the model to remember it. A hook runs every time, regardless of the model's attention, its context, or its mood — which is exactly what a rule requires.

When to Use

• A rule must hold every time: formatting, a forbidden command, a required check.
• The agent keeps forgetting an instruction despite it being in the instructions.
• Automating a step that should happen around every edit or command.
• Blocking a dangerous action before it executes.

Capabilities

• Lifecycle events: before and after a tool call, on session start, on stop.
• Deterministic enforcement: formatting, linting, blocking.
• Injecting context at the right moment.
• Notification and logging.

Inputs

• The rule and when it must apply.
• The event that should trigger it.
• What should happen when it fails: block, warn, or fix.

Outputs

• Hook configuration that runs reliably.
• Rules enforced without depending on the model's memory.
• A fast hook — one that does not make the agent unpleasant to use.

Workflow

1. Identify the rule that keeps being broken — If an instruction is in the instruction file and is still violated, it is a hook, not an instruction. Instructions are guidance; hooks are enforcement.
2. Choose the event — Before a tool call to block or validate; after one to format or verify; on session start to inject context.
3. Make it fast — A hook runs on every matching event. Two seconds on every file edit is a hostile environment. Under 500ms, or run it asynchronously.
4. Fail informatively — A hook that blocks must say why and what to do instead. A silent block is maddening and the model cannot recover from it.
5. Prefer fixing over blocking — A hook that formats the file is better than one that rejects the edit and demands the model format it.
6. Test the hook itself — A broken hook blocks everything, and the failure mode is confusing.

Best Practices

• A rule the model must remember is a rule the model will eventually forget. If it matters, enforce it in a hook.
• Do not put slow operations in a synchronous hook. A full test suite on every edit is a way to make the agent unusable.
• Blocking hooks must explain themselves. exit 2 with an explanatory message on stderr is what lets the model correct course.
• Match narrowly. A hook that fires on every tool call, including reads, wastes time on operations it does not care about.
• Auto-formatting after an edit is the single most valuable hook: it removes an entire class of diff noise and lint failures for free.
• Guard against the destructive command (rm -rf, a force push, a production deploy) in a pre-tool hook. This is cheap insurance.