Agent SDK hooks for interception and normalization
How Agent SDK hooks turn business rules into code: a PreToolUse hook that denies a policy-violating call and redirects Claude to escalation, a PostToolUse hook that normalizes or redacts tool results before Claude reads them, and how to decide which rules need a hook instead of a prompt.
Apply Agent SDK hooks for tool call interception and data normalization
~8 min read · 12 practice questions ·
What the exam expects
- Choose a hook over prompt or CLAUDE.md instructions when a business rule must hold on every call, and leave judgement and style rules in the prompt.
- Implement a
PreToolUsehook that blocks a policy-violating call (a refund above $500) and redirects Claude to an alternative workflow such as human escalation. - Implement a
PostToolUsehook that normalizes heterogeneous tool results (Unix timestamps, ISO 8601, numeric status codes) or redacts them before Claude reasons over them. - Debug a hook that does not fire or whose output is ignored (matcher syntax,
hookSpecificOutputnesting, whole-objectupdatedInput, output shape), and predict how several hooks combine and whether they cover subagents.
Key terms: hook (a callback your code registers for an agent event); matcher (the pattern that filters which tool names fire a hook); hookSpecificOutput (the object that carries an event's decision fields); updatedInput (rewritten tool arguments); updatedToolOutput (a replacement tool result); deterministic vs probabilistic compliance (code that always runs vs instructions the model may not follow).
Key facts
- Detail
- CLAUDE.md is advisory; hooks are deterministic and guarantee the action happens
- Detail
allow,deny,ask,defer, insidehookSpecificOutput
permissionDecisionReason on deny- Detail
- Claude
systemMessage- Detail
- Shown to the user, not the model
updatedInput- Detail
- Replaces the entire input object; include unchanged fields
- Detail
deny>defer>ask>allow; hooks run in parallel
- Detail
- Only letters, digits,
_,-, spaces,,,|;mcp__serveralone matches nothing
- Detail
- Tool names only; check arguments in
tool_input
updatedToolOutput- Detail
- Any tool, both SDKs;
updatedMCPToolOutputis MCP-only
- Detail
- Replacement ignored, original output used
- Detail
- Agent proceeds without waiting; cannot block, modify or inject context, so use only for logging-style side effects
- Detail
- Hooks fire; input has
agent_idandagent_type
- Detail
- Hooks run first; a deny applies even in
bypassPermissions
- Why does a
PreToolUsedeny guarantee a refund limit when a capitalised system-prompt rule does not? - When does a
PostToolUseupdatedToolOutputvalue forBashget ignored? - Why does the matcher
mcp__billingnever fire? - Which hook field tells Claude why a call was blocked, and which only informs the user?
The questions are free to read. Answers with their sources and self-grading are included with the pack.
Keep reading with the Claude Certified Architect - Foundations pack
- Core concepts
- Exam traps
- Worked scenario
The pack includes:
- All 30 lessons of the Claude Certified Architect - Foundations guide, with reading progress
- Interactive decision walks and step-by-step sequence steppers
- Inline practice questions and one-click topic practice (12 questions for this lesson)
- An official source cited for every claim
- An AI tutor that answers from the guide
- Unlimited timed practice exams
Practice for the Claude Certified Architect - Foundations exam
Certifyforce is an independent study resource and is not affiliated with, endorsed by or sponsored by Anthropic. Claude is a trademark of Anthropic.