Hooks: checks that run on their own
Commands that run automatically at specific moments of the agent’s work, such as before editing a file or when it finishes, so the important steps do not depend on the agent remembering them.
Before you start
- Verification and evaluationTechnique
How to check that the agent did the job right without taking its word for it: give it ways to verify itself, review both the result and the process, and compare setups honestly.
Published
Key idea: if something has to happen every time, do not leave it to an instruction. A hook is a command that runs on its own at a specific moment —for example, when the agent finishes— whether the agent remembers it or not.
The problem
In Verification and evaluation you saw that the agent should check its work with tests, type checks, or a linter. You usually ask for this in AGENTS.md. The agent reads it and almost always does it.
“Almost always” is the problem. An instruction is a request: the model decides whether to follow it. In a long session with a lot of context, it can forget it or decide it is not needed this time. Then it hands you a change with broken tests.
How it works
Think of a car’s seatbelt warning: it does not depend on you remembering to buckle up, it goes off on its own. A hook works the same way. You tell the program around the agent: “when this happens, run this command”.
Three moments are enough to get started. The names are the ones Claude Code uses:
| Moment | Name in Claude Code | Example use |
|---|---|---|
| Before using a tool | PreToolUse |
Block edits to .env |
| After using a tool | PostToolUse |
Format the file it just edited |
| When the agent is about to finish | Stop |
Run the tests before calling the work done |
When it finishes, the hook answers with a number, its exit code. You only need to remember two:
- Code 0: no objections. Everything carries on as usual.
- Code 2: “not yet”. If the hook runs before a tool, Claude Code blocks it. If it runs at the end, the agent cannot finish yet. In both cases, the agent receives the hook’s error message and can fix the problem.
Other agents have similar mechanisms under other names. If yours does not, a Git hook such as pre-commit or continuous integration does a similar job, only later: when the change is saved, not while the agent is working.
Practical example
Continue with the summarizeReading task. You want the agent to be unable to call it done if the tests fail. In Claude Code, add this to .claude/settings.json, the same file where permissions are written:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "node --test >&2 || exit 2"
}
]
}
]
}
}
What each part does:
"Stop"is the moment: the hook runs every time the agent is about to finish its response.node --testruns the project’s tests.>&2sends the test output to the error output. That is the text Claude Code shows the agent when something fails, so it knows which test failed.|| exit 2means “if the tests fail, finish with code 2”. The agent cannot finish yet: it receives the error and keeps working.
If the tests pass, nothing visible happens. If they fail, the agent sees the error and fixes it before handing you the work. The instruction in AGENTS.md is still useful, because it explains how the project is tested, but it is no longer the only thing that guarantees it.
Instruction, permission, or hook?
| If you want… | Use |
|---|---|
| The agent to know how work is done in the project | AGENTS.md |
| The agent to be unable to take a specific action | Permissions |
| A command to always run at a specific moment | A hook |
They work together: AGENTS.md explains, permissions prevent, and hooks automate.
Common mistakes
- Slow hooks. The
Stophook runs every time the agent finishes responding, even when it only answers a question. Use fast checks and leave the slow ones for continuous integration. - A check that can never pass. If the tests fail because of something the agent cannot fix, you force it to keep trying. Claude Code stops after several attempts in a row, but it is better if the check can actually be met.
- Thinking a hook sees everything. A hook that blocks edits to
.envdoes not see changes the agent makes with a terminal command. To really prevent something, combine it with permissions and isolation, as Safe agent execution explains. - Copying hooks without reading them. A hook is a command that runs on your machine with your permissions. Review the hooks in someone else’s project the same way you would review any script before running it.
- Turning everything into a hook. If a step is only needed in some tasks, it fits better in a Skill. Keep hooks for what has to happen every time.
When to use it
When you see the agent forget the same step more than once, or when a step must never be skipped. Start with just one, such as running the tests at the end, and add another when a new, repeated slip appears.
Next step
With checks automated, you can split work up without losing control. Subagents and delegation explains when to divide a task among several agents and how to bring their results together.
Sources
Accessed on 2026-10-08.
- Automate actions with hooks, Claude Code documentation.
- Hooks reference, Claude Code documentation. Details what each exit code means at each moment.
Related content
- AGENTS.md: persistent project instructionsTechnique
A Markdown file at the root of the repository that tells the agent how your project works: commands, conventions, and how to check changes. It is a guide, not a control mechanism.
Published - Tools and permissionsTechnique
What a tool is, how an agent uses one, and how to decide what it can do without asking, what needs your approval, and what is off limits.
Published