Claude Code hook

A user-defined command or prompt that Claude Code runs automatically at a named lifecycle event, such as before or after a tool call, enabling deterministic enforcement of rules the agent cannot skip.

How it works

A hook binds a command or prompt to a named lifecycle event, and the Claude Code runtime invokes that binding when the event fires rather than leaving the decision to the agent. The hook sits outside the agent's decision loop: it sees the action the agent is about to take and either passes, modifies the inputs, or blocks the action entirely, regardless of what the agent intended.

Why it matters

Inverting the trust model is what makes a rule deterministic: the agent cannot route around a gate it does not control. The trade-offs are structural: a hook can only gate inputs and not the decision itself, latency added per triggering event compounds for frequent PreToolUse hooks, and blocking is opt-in via an explicit exit signal, so a hook that aspires to block but exits with the wrong signal lets the action proceed silently. Fail-open is the failure mode to design against, not fail-closed.

In practice

A check bound to the event before a file write inspects the pending change and blocks it when it violates a rule; the agent that triggered the write does not see the gate as a tool it could skip, and the prohibited write never lands regardless of how the agent arrived at it.

Practical considerations

Hooks bind to a discrete set of named lifecycle events. The most common pair is PreToolUse (runs before a tool call; can modify or block its inputs) and PostToolUse (runs after; sees the result); other events cover additional points such as SubagentStop, UserPromptSubmit, and SessionStart. Each event fires only at its anchor, so a hook bound to PreToolUse cannot inspect the result of the tool it gated, and a PostToolUse hook cannot block the call that produced the result it sees. The choice of which event to bind to is rule-structural rather than discretionary: a rule that should block a write fires PreToolUse; a rule that should log what happened fires PostToolUse. A chatty PreToolUse hook on a frequent event amplifies any flakiness in its command: the latency cost is paid every trigger, and intermittent failures surface as silent fail-opens because the runtime only treats an explicit exit signal as blocking, not any non-zero exit.

Defined by Ready Solutions AI