# Agent SDK hooks for interception and normalization

*Claude Certified Architect - Foundations Study Guide · Agentic Architecture & Orchestration · Last updated October 22, 2026 · https://www.certifyforce.com/study-guide/claude-certified-architect-foundations/agentic-architecture-and-orchestration/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.

- Certification: Claude Certified Architect - Foundations
- Exam section: Agentic Architecture & Orchestration
- Study guide: https://www.certifyforce.com/study-guide/claude-certified-architect-foundations

**Official exam objective:**

> Apply Agent SDK hooks for tool call interception and data normalization

## 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 `PreToolUse` hook that blocks a policy-violating call (a refund above $500) and redirects Claude to an alternative workflow such as human escalation.
- Implement a `PostToolUse` hook 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, `hookSpecificOutput` nesting, whole-object `updatedInput`, 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

| Fact | Detail | Source |
|---|---|---|
| Hooks vs CLAUDE.md | CLAUDE.md is advisory; hooks are deterministic and guarantee the action happens | [Best practices](https://code.claude.com/docs/en/best-practices) |
| PreToolUse decisions | `allow`, `deny`, `ask`, `defer`, inside `hookSpecificOutput` | [SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks) |
| Who reads `permissionDecisionReason` on deny | Claude | [Hooks reference](https://code.claude.com/docs/en/hooks) |
| `systemMessage` | Shown to the user, not the model | [SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks) |
| `updatedInput` | Replaces the entire input object; include unchanged fields | [Hooks reference](https://code.claude.com/docs/en/hooks) |
| Several hooks disagree | `deny` > `defer` > `ask` > `allow`; hooks run in parallel | [SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks) |
| Exact-match matcher | Only letters, digits, `_`, `-`, spaces, `,`, `\|`; `mcp__server` alone matches nothing | [Hooks reference](https://code.claude.com/docs/en/hooks) |
| Matchers filter | Tool names only; check arguments in `tool_input` | [SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks) |
| `updatedToolOutput` | Any tool, both SDKs; `updatedMCPToolOutput` is MCP-only | [SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks) |
| Built-in output mismatch | Replacement ignored, original output used | [Hooks reference](https://code.claude.com/docs/en/hooks) |
| Async hook output | Agent proceeds without waiting; cannot block, modify or inject context, so use only for logging-style side effects | [SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks) |
| Subagent calls | Hooks fire; input has `agent_id` and `agent_type` | [SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks) |
| Hook deny and permission modes | Hooks run first; a deny applies even in `bypassPermissions` | [Configure permissions](https://code.claude.com/docs/en/agent-sdk/permissions) |

## Check yourself

- Why does a `PreToolUse` deny guarantee a refund limit when a capitalised system-prompt rule does not?
- When does a `PostToolUse` `updatedToolOutput` value for `Bash` get ignored?
- Why does the matcher `mcp__billing` never fire?
- Which hook field tells Claude why a call was blocked, and which only informs the user?

## Sources

- [Intercept and control agent behavior with hooks](https://code.claude.com/docs/en/agent-sdk/hooks)
- [Hooks reference](https://code.claude.com/docs/en/hooks)
- [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide)
- [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices)
- [Use Claude Code features in the SDK](https://code.claude.com/docs/en/agent-sdk/claude-code-features)
- [Configure permissions](https://code.claude.com/docs/en/agent-sdk/permissions)
- [Claude Certified Architect – Foundations Exam Guide v1.0](https://everpath-course-content.s3-accelerate.amazonaws.com/instructor%2F6nizmqk8tpzpfjvt6qmmav7rh%2Fpublic%2F1783542750%2FClaude+Certified+Architect+%E2%80%93+Foundations+Exam+Guide.pdf)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 12 linked practice questions, and unlimited timed mock exams are included with the Claude Certified Architect - Foundations pack (USD $19): https://www.certifyforce.com/practice-exams