The agent loop of D1.1 runs the model’s tool calls automatically. Hooks are how the architect gets between the model and those calls — to block a dangerous one, rewrite its input, or clean up its output — without editing the model’s prompt. The exam tests three things: which events exist, the two modes of intervention, and who wins when hooks disagree.

Do I know this already? Diagnostic

Answer these confidently and you can skim ahead to Exam essentials; if any is shaky, read closely — each is developed below.

What is a hook, and does it consume the agent’s context window?
Which event gates a call before it runs, and which normalizes a result after?
Name the four decisions a PreToolUse hook can return — and say what defer does.
Three hooks return ask, allow, and deny on one event. What happens, and why?
A subagent can’t use a tool the parent could. Why — and what hook cleanly pre-approves it?

Check your answers

A hook is a callback that runs your code in response to an agent event, running in your application process — it does not consume the agent’s context window.
PreToolUse gates a call before it runs; PostToolUse normalizes the result before the model sees it.
allow, ask, deny, and defer — defer ends the query so the host can resume it later from the persisted session, a pause-and-hand-back, not an allow or a block.
The call is blocked: matching hooks run in parallel and the most restrictive result wins, per the precedence deny > defer > ask > allow.
Because subagents do not inherit the parent’s permissions — each runs its own evaluation chain; a PreToolUse hook cleanly pre-approves the tool.

Hooks intercept the loop at named events

A hook is a callback that runs your code in response to an agent event: “Hooks are callback functions that run your code in response to agent events, like a tool being called, a session starting, or execution stopping.” [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original They arrive through two channels that share one lifecycle — programmatic hooks (callbacks in your query() options) and filesystem hooks (shell commands in settings.json, loaded via settingSources). [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original

The events you must recognize

Hooks fire at named lifecycle points. The Python SDK exposes ten; the TypeScript SDK extends the same set to twenty. [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original The ones an architect must recognize:

Event	Fires when	Typical use
`PreToolUse`	a tool call is requested	block or rewrite the call before it runs
`PostToolUse`	a tool returns a result	normalize or replace the result before the model sees it
`PostToolUseFailure`	a tool execution fails	log or handle the error
`UserPromptSubmit`	a prompt is submitted	inject extra context
`Stop`	the agent stops	persist state before exit
`SubagentStart` / `SubagentStop`	a subagent begins / ends	track spawned parallel work
`PreCompact`	compaction is about to run	archive the full transcript first
`PermissionRequest`	a permission dialog would appear	custom permission handling
`Notification`	an agent status message	forward to Slack / PagerDuty

The TypeScript-only additions (PostToolBatch, SessionStart, SessionEnd, Setup, and others) are why SessionStart / SessionEnd are not available as Python SDK callbacks — Python apps needing them load filesystem hooks from settings instead. [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original

`PreToolUse` gates; `PostToolUse` normalizes

The two most-tested events define the two interception modes, and they sit on opposite sides of tool execution. [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original

PreToolUse gates — it runs before the tool and returns a permissionDecision of allow, deny, ask, or defer, optionally with updatedInput to rewrite the call. Blocking a write to a .env file is a PreToolUse hook matching Write|Edit that returns deny when the target path ends in .env.
PostToolUse normalizes — it runs after the tool and returns either additionalContext (appended to the result) or updatedToolOutput (which replaces the output before Claude sees it). Stripping noise, redacting secrets, or reshaping a tool’s response into a clean form is PostToolUse work.

Matchers select which calls a hook sees: they are regex strings tested against the tool name — "Write|Edit", "^mcp__" for all MCP tools, or omitted to match everything. [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original Matchers do not filter by argument; filter on the file path or command inside the callback.

A PreToolUse gate: forbid writes to .env Worked example

The rule: the agent may never write a .env file. That is a gate (a decision before the tool runs), so it is a PreToolUse hook. The matcher selects the write tools; the callback inspects the path and returns a decision:

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Cannot modify .env files"
  }
}

Wiring: a PreToolUse hook with matcher "Write|Edit"; inside the callback, if the target path ends in .env, return the object above; otherwise return "allow". Note what the matcher does not do — it selects by tool name, not by argument, so the .env test must happen inside the callback on the call’s input. Because this is a gate, it has to be PreToolUse: at PostToolUse the write has already happened.

Precedence: `deny` beats `defer` beats `ask` beats `allow`

When several hooks (or permission rules) act on one event, the outcome is decided by a fixed precedence, not by who ran first: “When multiple hooks or permission rules apply, deny takes priority over defer, which takes priority over ask, which takes priority over allow. If any hook returns deny, the operation is blocked regardless of other hooks.” [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original The four decisions are not symmetric, and defer is the one candidates miss:

Hooks and subagents

Two subagent-aware events — SubagentStart and SubagentStop — let you track spawned work, but the operational gotcha is about permissions. As D1.3 established, subagents do not inherit the parent’s permissions; each runs its own evaluation chain. [Official] Configure permissions · AnthropicT1-official original The clean way to pre-approve a subagent’s tools is a PreToolUse hook rather than re-prompting inside every child. [Official] Intercept and control agent behavior with hooks · AnthropicT1-official original

Practice

Exercise solutions

Solution ↑ Exercise

(a) is a gate, (b) is a normalization — opposite sides of tool execution, so they need different events. (a) Use a PreToolUse hook with a matcher of "Write|Edit"; in the callback, inspect the target path and return hookSpecificOutput.permissionDecision: "deny" when it ends in .env. The decision must come before the write runs. (b) Use a PostToolUse hook with a matcher of "Bash"; return hookSpecificOutput.updatedToolOutput containing the result with ANSI codes stripped — updatedToolOutput replaces the output before Claude sees it. (b) can’t reuse PreToolUse because the output does not exist yet when the call is requested; you can only normalize a result after the tool has produced it.

Solution ↑ Exercise

The call is blocked. All matching hooks run in parallel and the most restrictive result wins, so the deny overrides the allow and the ask — the precedence is deny > defer > ask > allow. The one-word rule is restrictive (equivalently, “deny wins”): one hook saying deny is enough to block; permitting requires every hook to agree.

Solution ↑ Exercise

Both expectations are wrong. defer does not run the call — it ends the query so the host can resume it later from the persisted session (a pause-and-hand-back, not an allow). And updatedInput is ignored with defer — that field applies only to allow (or ask). To run a rewritten command, the hook must return allow with updatedInput, not defer.

Exam essentials

A hook is a callback at a named lifecycle event, delivered programmatically (query options) or via filesystem settings. It runs in your process and does not consume agent context.
Two interception modes: PreToolUse gates (returns allow/deny/ask/defer + optional updatedInput); PostToolUse normalizes (updatedToolOutput replaces the result, additionalContext appends).
The four decisions: allow / ask / deny, and defer — ends the query so the host can resume it later from the persisted session (and updatedInput is ignored with defer).
Precedence is deny > defer > ask > allow. Matching hooks run in parallel; the most restrictive wins; one deny blocks.
Don’t rely on hook order (non-deterministic) — write each hook independently.
Subagents don’t inherit permissions; pre-approve their tools with a PreToolUse hook. Watch the silent-failure traps: case-sensitive names, max_turns cut-offs, recursive subagent loops.

Hooks intercept the loop at named events

The events you must recognize

PreToolUse gates; PostToolUse normalizes

Precedence: deny beats defer beats ask beats allow

Hooks and subagents

Practice

Exercise solutions

Exam essentials

`PreToolUse` gates; `PostToolUse` normalizes

Precedence: `deny` beats `defer` beats `ask` beats `allow`