Hooks

A hook runs at a defined event in an agent session or workflow. It can record an action or provide additional context. It can also apply a check when the application supports that behavior.

Put The Check Near The Action

A formatting hook can run after a source edit. A tool-permission hook can inspect a proposed operation before it executes. A session-start hook can supply a small amount of project context. The event and its timing determine what the hook can actually prevent.

A check that runs after a file has changed cannot prevent that write. It can report the result and stop later work. If an operation must never occur, enforce the restriction before execution and through the underlying permissions.

Prefer A Hook To A Sentence

An instruction asks the model to remember a rule. A hook checks the rule every time, and the model cannot skip it under a full context. If a script can detect a violation, the rule belongs in a hook. Claude Code hooks fire on named events. PreToolUse runs before a tool call and can deny it. Codex documents its own set of events.

• Block destructive commands such as a recursive delete or a hard reset.
• Reject a TypeScript edit that adds a type-check suppression.
• Reject a write that contains something shaped like an API key.
• Deny a test-writing agent any write outside the tests folder.

A denial should state its reason. The model reads the reason and corrects its next attempt. The agent gets steered at the moment of the mistake instead of carrying every rule in its context.

Keep The Contract Small

A hook receives event data and evaluates a condition, then returns a result using the application's documented format. That format and the supported events vary by tool, as does the meaning of exit codes. Copying a configuration between Claude Code and Codex without checking its schema can lose the intended behavior without any error.

A check parses the event using the documented schema before a configured tool action. It compares the operation against the allowed scope and returns an allow or deny result with a specific reason. On invalid input it stops where the boundary requires it.

Hooks Can Start Work Too

A hook can launch a task as well as block one. A session-end hook can start a headless agent that summarizes the finished session into a notes folder. Over time that folder becomes a searchable record of past work. Attach this to the session-end event. A Claude Code stop hook fires each time the agent finishes a response, so a summary there would run again and again.

A hook on each commit can start an agent that reads the diff and updates the matching specification. The documentation then keeps pace with the code without anyone remembering to update it.

Test The Boundary

A string search for a dangerous command is easy to bypass with alternate syntax. A hook is useful for feedback, but do not present it as a complete sandbox. Test both allowed actions and prohibited actions. Try malformed input and a failure of the hook itself.

Keep routine hooks fast and their output brief. Injecting a long explanation after every tool call can recreate the context problem the hook set out to solve.

Tighten gradually. A wall of strict hooks can trap an agent in a cycle of blocked attempts, and a trapped agent may start deleting tests to escape. Add one hook for one observed failure and watch the response before adding the next.

Exercise 9: Block One Command With A Hook

Pick a command an agent should never run in a project, such as a hard reset or a recursive delete, and test in a copy of that project. Before writing code, list the commands the check should allow and the ones it should deny. Then write a hook on the event that fires before a tool runs, so the hook can deny the command and return a reason the model can read.

Trigger one allowed command and one denied command and confirm each behaves as listed. Then try the denied command with different syntax, such as extra flags or a different path, and see whether it gets through. Record what the hook catches and what would still need an operating-system permission to stop.

September, 2026