Claude Code Hooks: Deterministic Gates for Agentic Coding

Use hooks when forgetting is unacceptable

Instructions are advisory. Hooks are executable. If a rule must run every time, put it in a hook or another deterministic gate. Common examples include formatting after edits, blocking writes to protected paths, alerting when Claude needs input, and preventing a turn from ending until a check passes.

Do not use hooks for everything. Hooks add latency and can create confusing failures if they are too broad. Reserve them for policies where consistency matters more than conversational flexibility.

Primary-source anchor: Anthropic describes hooks as deterministic control that can run commands at specific lifecycle points.

Know the lifecycle cadence before writing hooks

Hook events do not all fire at the same rate. Some are once per session, some are once per turn, and some fire on every tool call. That cadence determines cost and risk.

A slow command on every tool call will make Claude Code feel broken. A slow command at Stop may be acceptable if it prevents false completion. Design hooks around the frequency of the event.

• Session cadence Use for setup, teardown, loading notifications, or audit boundaries.
• Turn cadence Use for prompt checks, Stop gates, and completion policy.
• Tool cadence Use sparingly for path restrictions, command filters, or high-value audit events.

Primary-source anchor: the hooks reference groups events into session, turn, and tool-call cadences.

The most useful first hook is a Stop gate

A Stop hook can keep a session from ending until a command passes or a required artifact exists. For example, a repository can require a targeted test after source edits or require a build after package changes.

Keep the first Stop hook simple. It should print a clear failure message that Claude can act on. If the message is vague, Claude will waste turns guessing what to fix.

If files under src/ changed:
  run npm test -- --runInBand
  if it fails, print the failing command and exit non-zero
If package files changed:
  run npm run build
  if it fails, print the failing command and exit non-zero

Hooks are part of the trust boundary

A hook runs commands because your configuration told it to. That means hook files deserve code review. A malicious or sloppy hook can leak secrets, mutate files unexpectedly, or make every session unsafe.

For team repos, keep hooks small, readable, and committed with the same discipline as build scripts. Prefer allowlisted commands, explicit paths, clear stderr, and no hidden network calls.

• Review hook scripts in PRs.
• Avoid secret-printing commands.
• Avoid broad recursive deletes or file rewrites.
• Print actionable failure messages.
• Keep slow checks at lower-frequency lifecycle events.

Use prompt or agent hooks only when judgment is required

Command hooks are deterministic and usually easiest to reason about. Prompt-based or agent-based hooks can help when a rule needs judgment, but they also introduce model behavior into the gate itself.

If a shell script can answer the question, use a shell script. If the rule needs semantic review, make the judgment visible and keep a human or CI gate in the final acceptance path.