7.3 — Claude Hooks

CCDV-F Domain 7 · Task 7.3

What You Need to Know

A hook is your own code, wired to a named point in the agent’s lifecycle. It gives deterministic control: certain actions always happen rather than relying on the LLM to choose.

Blocking With PreToolUse

PreToolUse fires before a tool call executes. Exit code 2 blocks (reason on stderr reaches Claude). Exit 0 means no objection (normal permission flow still applies). Any other non-zero exit with plain-text/empty stdout is a non-blocking error — the action proceeds. Set onFailure: "block" to make any failed run block.

JSON form: hookSpecificOutput with permissionDecision of allow, deny, ask or defer. Precedence when several hooks differ: deny → defer → ask → allow. Exit 2 wins regardless.

Matchers

Exact name (letters, digits, _, -, spaces, commas, |) or unanchored JavaScript regex (any other character). mcp__archive matches no tool; mcp__archive__.* matches every tool on that server including ones added later.

Other Safety Events

• UserPromptSubmit — before Claude processes the prompt; decision: "block" stops it. Can keep a pasted secret from the model, not from local history.
• PostToolUse — cannot undo a call that has run; updatedToolOutput replaces the output before it reaches Claude. PreToolUse for outbound inputs; PostToolUse for inbound results.

Where It Sits in the Permission Order

Hooks evaluate first. A blocking hook stops the call before permission rules are consulted. In bypassPermissions mode, hooks still execute and can block. A hook returning allow does not clear a matching deny or ask rule.

What a Hook Cannot Do

Only what you can express as a check on an observable action (tool name + input). Intent rules are not hook-shaped. Async hooks cannot block. A command hook that times out does not block. prompt and agent hook types are model evaluations — not deterministic. Where the rule is a boundary, use command.