Controls
Claude Code hooks
definition
Hooks are user-defined shell commands that Claude Code executes automatically at specific lifecycle events, allowing deterministic control over what an agent is permitted to do.
In depth
Prompting an agent not to do something is a request. A hook is a rule. Hooks are configured in settings and fire at defined points in the session — before a tool runs, after it runs, when the user submits a prompt, when the session starts or ends, when the agent is about to stop, before context is compacted.
The event that matters most for control is the pre-tool-use hook, because it runs *before* the action and can block it. The hook receives structured JSON about the pending tool call on standard input and signals its decision through its exit code and output — allow, block with a reason the model sees, or ask the user. That is how a team enforces something like 'never write to this directory' or 'no network calls to hosts outside the allowlist' in a way the model cannot talk its way past.
Post-tool hooks are the other common shape and are usually about hygiene rather than security: run the formatter after a file is edited, run the type checker, append a line to an audit log. Because they run automatically, they turn conventions the team keeps forgetting into properties of the environment.
The trade-off is that hooks are code on the critical path of every session. A slow hook makes the agent feel slow; a buggy hook blocks legitimate work and gets disabled by a frustrated engineer, at which point the control is gone and nobody knows.
Why it matters for governance
Hooks are the most powerful control point an agent host offers and the most dangerous artifact to distribute, because a hook is a shell command that runs automatically with the engineer's full permissions and no confirmation prompt. A malicious hook is a better payload than a malicious skill: it does not need the model to cooperate. Any hook arriving from outside the team — a plugin, a shared dotfiles repository, a template — deserves the scrutiny of a shell script you are about to run as yourself, which is exactly what it is. Distribute hooks centrally, pin them, scan them for credential reads and outbound network calls, and detect when a machine's hooks diverge from what was approved.
Frequently asked
- Can a hook stop the agent from doing something?
- Yes. A pre-tool-use hook runs before the tool call and can deny it, returning a reason that goes back to the model. This is the difference between a policy and a suggestion.
- Do hooks run with my full permissions?
- Yes — they are shell commands executed as the user running the agent. That is what makes them effective and what makes an untrusted hook a serious supply-chain risk.
Sources
Primary sources for the claims on this page. Specifications and vendor documentation change — verify against the source if a detail is load-bearing for a decision you are making.