Hook events fire at Claude Code tool boundaries the agent can't opt out of — match each event to its causal window so security gates run before damage, completion contracts run after work, and audit runs independent of timing.

Guide

How to Use Hooks

Pick the event

The right decision is a matrix, not a guess.

Start from the causal window — then the event chooses itself.

Ask first What am I trying to enforce, and when does the damage happen?

Before damage

PreToolUse

Hard gate. Reject the tool call outright — nothing has touched disk yet.

block rm -rf

block writes to /etc

At completion

Stop / SubagentStop

Contract verification. Compare declared work vs ledger vs disk state before releasing turn.

filesExpected ⟷ changed

no phantom edits

Independent of timing

PostToolUse

Observation without blocking. Capture bundles, log events, roll up history.

Context Bundle writer

tool-call ledger

Wrong event = overreach (blocks unrelated ops) or underreach (fires too late). The window picks the event.

See the causal window

Where each event sits on the tool-call timeline.

One tool call, four possible interception points.

PreToolUse

can block

before run

→

tool runs

disk mutates

here

→

PostToolUse

observe, log,

bundle

→

Stop

verify the

whole turn

Before the line Only PreToolUse can prevent the effect. After this, damage is already on disk — recovery, not prevention.

After the line PostToolUse audits. Stop verifies the contract. Neither unwinds what ran — they only judge it.

Other events exist for lifecycle moments — UserPromptSubmit (prompt discipline), PreCompact, Notification. Same rule: match the window.

The canonical pattern

Three components. All three, or the contract breaks.

Hook-Enforced Contract — eliminates phantom edits.

filesExpected

Agent declares up front which files it will touch. A commitment, not a prediction.

ledger recording

PostToolUse hook logs every actual write to a tamper-evident ledger.

Stop verification

At turn end, compare declared vs ledger vs disk. Mismatch = block.

Together: self-reported completion becomes provable.

Any one missing — the contract is theater. Declaration without audit is a wish; audit without verification is logging.

What a hook actually is

A shell script. JSON on stdin. Exit code is the verdict.

.claude/hooks/block-dangerous.sh

blocking

#!/usr/bin/env bash

# PreToolUse hook — reads tool call, decides allow/block.

input=$(cat)# JSON payload on stdin

cmd=$(echo"$input" | jq -r '.tool_input.command')

if [[ "$cmd" == *"rm -rf"\* ]]; then

echo"Blocked: rm -rf is banned. Use targeted deletes."

exit2# stdout becomes the agent's repair prompt

exit0

exit 0 — allow Tool call proceeds. Silent pass.

exit 2 — block Tool call rejected. Stdout becomes the agent's next instruction — make it specific and actionable.

A blocking hook's error text is a prompt. "Blocked" teaches nothing; "Blocked — use targeted deletes" steers the repair.

What to read, in order

Six nodes. The teaching order respects dependency.

Trust But Verify

The why behind every enforcement hook. Agent self-reports are claims, not facts. Disk state is the judge.

Fix the System Not the Issue

Hooks encode fixes at the class level. "Block rm -rf in PreToolUse" is a system fix; "tell the agent not to" is an individual fix that rots.

Hook-Enforced Contract

filesExpected + ledger + Stop verification. The canonical pattern that eliminates phantom edits. Three components — any one missing and the guarantee breaks.

Hook Event Selection

The decision matrix. PreToolUse for gates, PostToolUse for audit, Stop for completion, SubagentStop for nested, UserPromptSubmit for prompt discipline.

Hook

The shell-script artifact. JSON on stdin, exit 0 or 2. A blocking hook's stdout becomes the agent's repair instruction.

Context Bundle

An underused PostToolUse pattern. Capture tool-call history into time-bucketed bundles; future agents reload as warm context.

Adjacent: how-to-author-templates (hook script skeleton) and how-to-prompt (a block message is a prompt).

The discipline

Hooks are power the agent can't opt out of — which means the wrong window is worse than no hook at all.

Gate before damage. Verify at completion. Audit independent of timing. Match event to causal window — or overreach blocks honest work while underreach lets the failure ship.

How to Use Hooks ​

The right decision is a matrix, not a guess. ​

Where each event sits on the tool-call timeline. ​

Three components. All three, or the contract breaks. ​

A shell script. JSON on stdin. Exit code is the verdict. ​

Six nodes. The teaching order respects dependency. ​