Agent SDK Hooks for Tool Call Interception and Data Normalization

The Agent SDK Hooks feature is where the Claude Certified Architect — Foundations (CCA-F) exam separates candidates who treat Claude as "a smart model with a prompt" from candidates who treat Claude as a component inside a production system. Task statement 1.5 — "Apply Agent SDK hooks for tool call interception and data normalization" — tests exactly one architectural idea: when you need a guarantee, you do not ask the model nicely in the system prompt; you intercept the tool call in code and enforce the guarantee deterministically. That shift — from probabilistic prompt compliance to deterministic programmatic enforcement — is the single most tested mental model in Domain 1 (Agentic Architecture & Orchestration, 27% of the exam).

This study note covers the full surface of Agent SDK Hooks that a CCA-F candidate is expected to recognize in a 60-question, 120-minute, scenario-based exam: the hook lifecycle inside the agentic loop, the difference between PreToolUse and PostToolUse, the canonical use cases (normalizing heterogeneous tool results, scrubbing PII, enforcing refund thresholds, redirecting to human escalation, audit logging), the common exam traps where candidates mis-place enforcement logic, and the scenario-anchor patterns drawn from the Customer Support Resolution Agent cluster that appears most heavily in task 1.5 questions.

What Is a Hook in the Claude Agent SDK?

A hook in the Claude Agent SDK is a user-registered callback that fires at a specific point in the agent's execution lifecycle, giving application code the chance to inspect, mutate, block, or record what is about to happen — or what just happened. Hooks are deterministic: they are regular code that the SDK calls synchronously during the agentic loop, not prompts the model might choose to follow. That determinism is what makes hooks the right tool whenever the system has a non-negotiable business rule.

The two hook types that dominate CCA-F task 1.5 questions are PreToolUse (fires before a tool call leaves the application for execution) and PostToolUse (fires after a tool result comes back but before the result is appended to the conversation and processed by the model). Agent Teams and Claude Code expose additional lifecycle hooks (TeammateIdle, TaskCreated, TaskCompleted, SessionStart, UserPromptSubmit, Stop), but for task 1.5 the exam concentrates on the two tool-call hooks.

Where Hooks Fit in the Agentic Loop — The Execution Lifecycle

To reason about hooks on the exam, you need a crisp mental model of the agentic loop and the exact points at which each hook fires.

The Seven-Step Loop

For each turn of the agentic loop:

1. Application sends message history plus tool definitions to the model.
2. Model produces an assistant message that may contain zero or more tool_use blocks.
3. For each tool_use block, the SDK is about to invoke a tool — PreToolUse fires here.
4. The SDK dispatches the tool call to the tool handler (a function, an MCP server, a built-in like Read/Write/Bash).
5. The tool finishes and returns a result (or an error) — PostToolUse fires here.
6. The SDK injects a tool_result message into the conversation.
7. The loop repeats from step 1 with the new history until the model emits stop_reason: end_turn.

Hooks are deterministic interception points at steps 3 and 5. If you understand this lifecycle, the rest of the topic becomes easy.

Why the Hook Points Matter

Step 3 (PreToolUse) is the last chance to change or block the action before it has any real-world effect. Step 5 (PostToolUse) is the first chance to shape what the model will see in its next turn. Every exam scenario in task 1.5 maps onto exactly one of these two points — and the wrong answer choices are usually hook-type confusions (using PostToolUse when PreToolUse is required, or vice versa).

PreToolUse Hook — Inspecting and Mutating Tool Input Before Execution

The PreToolUse hook receives the tool name and the proposed input arguments. It can do any of the following:

• Pass through — return a signal that means "proceed with the call unchanged." This is the default in the absence of policy violations.
• Mutate input — rewrite the input before it is dispatched. For example, adding a store_id filter that the model forgot, or clamping a numeric field that the model supplied out of range.
• Block and substitute — prevent the call from executing and return a synthetic tool result describing why the call was denied. The model reads that synthetic result and adjusts its next turn.
• Redirect — instead of blocking outright, hand the request off to an alternative workflow (for example, a human-escalation queue) and return a tool result that instructs the model to acknowledge the escalation to the end user.

Canonical PreToolUse Use Cases for CCA-F

• Policy gate on monetary thresholds — the Customer Support Resolution Agent has a process_refund(amount, order_id) tool. Policy says refunds greater than USD 500 require human approval. A PreToolUse hook inspects amount, and if it exceeds the threshold, blocks the call and returns tool_result: "Refund above $500 requires manager approval. Escalation ticket CSR-4412 created." The model then tells the customer a human agent will follow up.
• Input sanitization — blocking a delete_user call that lacks a confirmation token, or scrubbing disallowed characters from a search query.
• Rate and quota enforcement — counting calls per session and blocking further tool use once a quota is hit.
• Tenant-scoping injection — adding the current user's tenant_id filter to every database query to make cross-tenant data access structurally impossible.

PostToolUse Hook — Intercepting and Transforming Tool Output Before Injection

The PostToolUse hook receives the raw tool result — whatever string, JSON, or structured payload the tool produced — plus the original tool input and metadata about the call. It can:

• Pass through the result unchanged.
• Normalize heterogeneous fields into a canonical shape the model will find easier to reason about.
• Redact fields that should not enter the model's context window (PII, secrets, internal identifiers).
• Enrich the result with derived values (adding a computed days_since_order field to a raw order record).
• Log the raw and transformed values for audit, without changing what the model sees.

The Normalization Pattern — Heterogeneous Data Made Canonical

A common CCA-F scenario: an agent calls three different upstream systems (a payments API returning Unix epoch seconds, an orders API returning ISO 8601 strings, and a shipping API returning numeric status codes like 1, 2, 3). The model could in principle figure out each format, but every turn where it has to do so consumes tokens, risks mistakes, and pollutes the conversation with boilerplate reasoning. A PostToolUse hook normalizes all three into a canonical shape — timestamps as ISO 8601 UTC, statuses as named enums (pending, shipped, delivered) — so the model sees a uniform, clean record on every tool result.

This normalization use case is the single most cited exam pattern for PostToolUse. If a CCA-F question describes inconsistent upstream data formats and asks where to apply standardization, the answer is a PostToolUse hook.

The Redaction Pattern — PII Before Context Injection

Customer Support Resolution Agent workflows frequently touch raw database rows that contain full PAN (card numbers), full SSN, or PHI. A PostToolUse hook is the architecturally clean place to redact these fields before they ever enter the conversation: the tool still returns the full record (so the tool handler can log it or forward it to a downstream system), but the version the model sees has been reduced to last-four digits and masked identifiers. This reduces blast radius: the model cannot leak data it never received.

The Enrichment Pattern — Adding Derived Fields

Sometimes the model benefits from pre-computed metadata. A PostToolUse hook can add days_since_order, eligible_for_refund, within_return_window, or region_code to a raw order record, sparing the model from recomputing those values and reducing the chance of arithmetic mistakes in conversation.

Hook Registration — Attaching Hooks to Specific Tool Names vs All Tools

Hook registration is the second decision axis the exam tests (after "PreToolUse vs PostToolUse").

Global Hooks vs Per-Tool Hooks

A global hook fires on every tool call regardless of tool name. Use global hooks for cross-cutting concerns: audit logging, PII redaction on any tool output, quota enforcement per session.

A per-tool hook fires only when a specific named tool is invoked. Use per-tool hooks for business rules that apply to exactly one tool: the USD 500 refund threshold applies only to process_refund, not to lookup_order or send_notification.

Registration Patterns

The Agent SDK accepts hooks either as SDK options when creating the agent (programmatic registration) or through a .claude/settings.json hooks configuration in Claude Code. For CCA-F you do not need to memorize TypeScript signatures or JSON schemas; you need to recognize:

• Hooks are registered at agent construction time, not discovered dynamically.
• A tool name filter narrows a hook to a specific tool.
• Multiple hooks can be registered on the same event; the SDK runs them in a defined order.

Why Specificity Matters

Over-broad hooks create three problems: (a) they add per-call overhead to tools that do not need gating, (b) they risk false blocks on tools whose inputs happen to match a superficial pattern, and (c) they concentrate policy logic that should be modular into a single hook function. Exam questions sometimes present two correct-seeming options that differ only in hook scope — the right answer is almost always the narrower registration.

Hook Ordering and Composition

When multiple hooks are registered on the same event, the SDK executes them in registration order. Two architectural patterns follow:

• Chained transformation — hook A normalizes timestamps, hook B redacts PII, hook C appends audit metadata. Each hook consumes the output of the previous one. Order matters: redaction must run before audit logging if the audit log should not contain PII.
• Short-circuit blocking — a security hook runs first and can block the call entirely; transformation hooks only run if the security hook allowed the call through.

A common exam trap: candidates assume hooks run in parallel or in arbitrary order. They do not. Hook ordering is deterministic and is part of the architectural decision surface.

Hook Error Handling — What Happens When a Hook Itself Throws

Hooks are regular code and can fail. The SDK's default behavior when a hook throws depends on hook type and configuration, but the exam-worthy principles are:

• PreToolUse throwing is typically treated as "block the call" — fail-closed, because a policy gate that errored is safer to treat as a denied call than as an allowed one.
• PostToolUse throwing usually falls back to passing the original unmodified result through and logging the hook error, because the tool has already executed and completely dropping the result would break the loop.
• Hook timeouts — long-running hooks block the agentic loop. Keep hooks fast and defer expensive work (large log uploads, heavy analytics) to async queues.

Exam scenarios sometimes ask "what happens if the normalizer hook crashes?" The principled answer: the system should fail loudly (log + alert) while keeping the agent operational, typically by passing through the raw result and flagging the record for review.

Deterministic Enforcement vs Probabilistic Prompt Compliance — The Core CCA-F Mental Model

This section is the most testable idea in task 1.5. Internalize it until reflexive.

The Two Compliance Regimes

The Selection Heuristic

• If the requirement uses absolute words (must never, always, under no circumstances, guaranteed to), the answer is a hook (or another deterministic gate — strict tool schemas, code-level validation).
• If the requirement uses soft words (prefer, typically, encourage, where appropriate), a system prompt may be adequate.
• If the requirement is legal, financial, or safety-critical, default to deterministic enforcement even if the wording sounds soft.

Why Prompts Are Not Enough for Compliance

Anthropic's own engineering writing emphasizes that system prompts are excellent for guiding the model's default behavior but do not give guaranteed compliance. Models are statistical: on enough invocations, any probabilistic behavior will eventually produce an outlier. For a high-frequency tool call like process_refund, even a 99.9% prompt-compliance rate means roughly one violation per 1,000 calls — far too many for a policy backed by the law or a partner contract. Hooks make compliance a structural property of the system, not an aspiration.

Redirecting Policy-Violating Actions to Alternative Workflows

A PreToolUse hook that merely says "no" to the model is acceptable but leaves the end user hanging. Mature architectures redirect: instead of only blocking, the hook dispatches the request to an alternative workflow and returns a tool result that teaches the model how to communicate the outcome.

The Human-Escalation Pattern

For the Customer Support Resolution Agent refund-threshold example:

1. Model emits tool_use: process_refund(amount=750, order_id="ABC").
2. PreToolUse hook sees amount > 500, blocks the direct refund.
3. Hook creates an escalation ticket in the human-agent queue (e.g. through a Zendesk API) with full context (customer, order, amount requested, conversation summary).
4. Hook returns tool_result: { status: "escalated", ticket_id: "CSR-4412", expected_response_hours: 24 }.
5. Model reads the tool result and explains to the customer: "I've escalated your refund request to a human agent; ticket CSR-4412 will be reviewed within 24 hours."

The model never learns that the refund could have been processed automatically at a lower amount — because the hook never gave it the opportunity. The compliance guarantee is structural.

The Alternative-Tool Pattern

Another variation: PreToolUse blocks a forbidden tool and returns a result that explicitly recommends the correct tool. For example, a model attempts execute_sql(raw_query) against a production database; the hook blocks it and returns tool_result: "Direct SQL denied. Use the read_customer_data tool with the appropriate filter." The model then rewrites the request using the safer tool.

The Tiered-Review Pattern

Hooks can encode approval tiers: refunds under $100 auto-approve, $100–500 require a confirmation message, over $500 escalate to a human. Each tier is a branch inside the hook. The model experiences a uniform interface (call the tool, receive a tool result) while the hook encodes an arbitrarily complex policy tree.

Audit Logging in Hooks — Compliance Evidence and Debugging

Hooks are the natural place to produce audit trails because they see every tool call and every tool result, regardless of what the model does with them.

What to Log in PreToolUse

• Timestamp, session ID, conversation ID.
• Tool name and full input arguments.
• Policy decision (allowed / mutated / blocked / redirected).
• If blocked or redirected: the rule identifier (e.g. POLICY-REFUND-500-CEILING).

What to Log in PostToolUse

• Raw tool result (full, pre-redaction copy, stored in a compliance-scoped log).
• Normalized / redacted version that was injected into the conversation.
• Latency, error flag, tool handler version.

Why Audit Logs Go Here and Not in the Prompt

If you "ask the model to log" by telling it to emit a structured summary, you get probabilistic logs — sometimes right, sometimes missing fields, sometimes hallucinated. Hooks produce deterministic logs. In regulated industries (finance, healthcare, customer data handling), deterministic logs are the only kind that satisfy auditors.

PII Scrubbing, Redaction, and Data-Minimization Patterns

Hooks support several tiered approaches to data minimization:

• Full redaction — fields are replaced with [REDACTED] or removed entirely before the model sees the payload.
• Masking — fields are partially preserved (last-four of SSN, first.l****@example.com) so the model can still reason about the record without seeing sensitive values.
• Tokenization — fields are replaced by opaque tokens; downstream tools accepting the same tokens can resolve them to original values inside the trust boundary.
• Hashing — fields are replaced by hashes to enable correlation without disclosure.

The exam does not test the cryptographic details; it tests that the right place to apply these transforms is a PostToolUse hook, not a prompt instruction telling the model to "please do not repeat the SSN."

Performance Impact of Synchronous Hooks

Every hook adds latency to every tool call. For hooks that make network calls (writing to a SIEM, calling a policy-decision service), that latency is not negligible.

Practical Guidance

• Keep hooks in-process and in-memory where possible; a fast normalizer is ~microseconds.
• Send slow work (log uploads, alert dispatch, cross-system API calls) to a fire-and-forget queue that the hook enqueues synchronously and returns.
• Measure the p99 latency of hook execution against the tool's own latency; a hook that doubles a 5ms tool latency is fine, a hook that doubles a 500ms tool latency may be noticeable in user-facing flows.

Why This Matters for the Exam

Community-sourced exam experience reports note that task 1.5 sometimes asks about the cost of hook interception in high-throughput loops. The correct answer profile is "hooks add synchronous overhead; keep them lightweight and push expensive work to async queues." Avoid the distractor that claims "hooks run asynchronously in parallel with tool execution" — they do not.

Plain-Language Explanation: — Three Analogies for Agent SDK Hooks

Abstract lifecycle diagrams get sticky when anchored to familiar systems. Here are three different analogies, each illuminating a different facet of Agent SDK Hooks.

Analogy 1: The Airport Security Checkpoint (PreToolUse) and Customs (PostToolUse)

Imagine an international airport. Every passenger (tool call) about to board a plane (execute a tool) passes through security screening — a deterministic checkpoint where agents inspect bags, compare IDs to the no-fly list, and either wave you through, make you throw away the 200ml water bottle (input mutation), or pull you aside and deny boarding (block and redirect). That checkpoint is PreToolUse. It happens every time. It does not matter how politely the passenger asks to skip it or how good the airline's loyalty program is — security is structural.

On arrival, every passenger (tool result) passes through customs — inspectors who ensure the bag matches a declared canonical form, confiscate contraband that should not enter the country (redaction), and stamp paperwork (audit logging) before the passenger joins domestic traffic (the conversation context). That is PostToolUse. Customs does not un-take the flight (the side effect already happened) — it shapes what enters the destination system.

This analogy makes three things click: (a) why PreToolUse is the right place for "must never" rules — security is before the plane, not after; (b) why PostToolUse cannot undo a side effect — the plane has landed; and (c) why you would never rely on "nicely asking passengers in the announcement to follow the rules" (a probabilistic prompt) instead of the actual checkpoint (a deterministic hook).

Analogy 2: The Kitchen Expediter

A busy restaurant kitchen has a role called the expediter — the person standing between the line cooks and the dining room. Every plate about to leave the pass is inspected by the expediter: right table (tool name matches), right temperature (input within policy), right garnish (fields enriched), no hair on the steak (PII redacted). Plates that fail inspection are kicked back or sent to a different station.

PreToolUse is the expediter checking an order ticket before it goes to the line: is this dish on today's menu, does this customer have an allergy flag, is the kitchen authorized to make a 48oz steak special for this VIP. PostToolUse is the expediter checking the finished plate before it goes to the dining room: garnish, temperature, presentation, portion size. In neither case does the expediter "suggest to the chef via a polite note" what the rules are — they enforce them structurally at the pass.

The analogy also explains ordering composition: the expediter applies a sequence of checks (plating, then garnish, then temperature) and stops at the first critical failure. Hook ordering is the same idea.

Analogy 3: The Bank Teller's Dual-Control Drawer

A bank teller processes customer transactions, but certain transactions (a withdrawal above a threshold) require a supervisor co-sign before the cash drawer opens. The teller cannot override this even with the friendliest customer — the drawer mechanism itself requires two keys. Smaller transactions flow freely; large ones auto-route to supervisor approval (alternative workflow), and the customer is told "Your request requires manager approval, which typically takes a few minutes" (the synthetic tool result the model communicates to the user).

This is exactly the refund-threshold pattern. The PreToolUse hook is the drawer mechanism. The supervisor queue is the human-escalation workflow. The synthetic tool result is what the teller tells the customer while the supervisor is paged. The customer's request did not get blackholed — it got redirected into a workflow that produces a slower but valid outcome, and the customer is kept informed.

Which Analogy to Use on Exam Day

• Questions about "must never" enforcement and the Pre/Post distinction → the airport analogy.
• Questions about normalization, enrichment, and inspection chains → the expediter analogy.
• Questions about redirect-to-human patterns and alternative workflows → the bank teller analogy.

Hook Use Cases Matrix — When to Reach for Which Hook

Common Exam Traps in Task 1.5

The CCA-F exam aggressively exploits five recurring trap patterns for Agent SDK Hooks.

Trap 1: PostToolUse "Prevents" a Side Effect

Candidates sometimes pick PostToolUse as the enforcement point for "must never execute X." Wrong. PostToolUse fires after the tool has already run. If the tool dropped a production table, PostToolUse cannot un-drop it. For prevention of side effects, the only correct answer is PreToolUse.

Trap 2: Prompt Engineering Instead of a Hook

When a scenario states a hard compliance requirement (legal, financial, safety), distractors suggest "strengthen the system prompt" or "add examples to the tool description." These are probabilistic. The correct CCA-F answer for hard rules is a hook (or another deterministic gate).

Trap 3: Confusing PreToolUse Mutation Scope

A PreToolUse hook that mutates tool input changes what the tool sees, not what the model sees in its message history. If an exam question asks "the model keeps repeating the same mistaken input," a PreToolUse input mutation will not correct the model's belief on its own — the model will still think it called the tool with the original input. Either use a PostToolUse hook to inject a corrective note in the tool result, or append an observation to the conversation history.

Trap 4: Hook Ordering Mis-assumed

Candidates sometimes assume hooks run in parallel or non-deterministic order. They do not. Hook ordering is deterministic and follows registration order. An audit hook registered before a redaction hook will log pre-redaction data; one registered after will log post-redaction data. Order determines semantics.

Trap 5: "Hooks Handle Everything" Overreach

The inverse trap: assuming hooks are the right answer to every architectural question. They are not. Hooks are for deterministic interception of tool calls. Hooks are not the right place for tool discovery, context window management, long-running sub-task delegation (use subagents), session persistence (use SDK session APIs), or model-behavior tuning (use prompts). Read the scenario carefully before reaching for a hook.

Practice Anchors — Task 1.5 Scenario Question Templates

CCA-F scenario questions tied to task 1.5 cluster around the Customer Support Resolution Agent and Developer Productivity scenarios. Five recurring shapes follow.

Template A: Prevention vs Observation

A fintech builds a Customer Support Resolution Agent with a issue_card_replacement tool. Policy states that only one card replacement per 30 days per account is permitted. The team must guarantee this limit holds even under concurrent sessions. Which architectural mechanism should they implement? Correct: PreToolUse hook that checks the replacement counter and blocks further calls. Distractors: stronger system prompt (probabilistic), PostToolUse hook (after-the-fact), tool description refinement (not enforceable).

Template B: Heterogeneous Data Normalization

A Developer Productivity agent calls three APIs that return timestamps in different formats: Unix epoch seconds, ISO 8601, and custom YYYYMMDD-HHMMSS strings. The team wants the model to always see ISO 8601 UTC. Where should the normalization logic live? Correct: PostToolUse hook registered on all three tools, converting each format into ISO 8601 before injection. Distractors: add instructions to the system prompt (token-expensive, probabilistic), fork three separate agents (wrong architectural level).

Template C: PII Redaction for Compliance

A support agent retrieves customer records that include full SSNs. The team must guarantee SSNs never reach the model's context window. Which hook, and why? Correct: PostToolUse — the tool handler has a legitimate need to access the full record for downstream APIs, so the redaction is done on the way into the conversation, not on the way out of the tool. Distractor: PreToolUse (does not help — the issue is the returned data, not the request).

Template D: Redirect to Human Escalation

Customer Support scenario: refund over $500 must go to a human. Which combination of mechanisms? Correct: PreToolUse hook that blocks the direct refund, creates an escalation ticket, and returns a synthetic tool result describing the escalation so the model can communicate the outcome to the user. Distractors: block only with no redirect (poor UX), tell the model via prompt to prefer human escalation above $500 (probabilistic).

Template E: Hook Error Handling

A normalizer hook throws on a malformed upstream response. What is the safest default behavior? Correct: pass the original raw tool result through, log the hook error, and alert operators. Distractor: drop the tool result entirely (breaks the loop), retry the hook indefinitely (adds latency and risks infinite loops).

Relationship to Other Domain 1 Topics

Hooks interact with other Domain 1 topics in ways the exam loves to cross-test.

Hooks vs Subagent Tool Allowlists

Task 1.3 introduces allowedTools — a subagent configuration that restricts which tools a subagent can invoke. allowedTools is a coarse, static, tool-level gate: either the subagent has the tool or it does not. Hooks are fine-grained, dynamic, per-call gates: the subagent has the tool, but the hook inspects each invocation's arguments. Use allowedTools for capability scoping, hooks for behavior gating. The exam sometimes asks which to use; the answer depends on whether the restriction is categorical (use allowedTools) or argument-dependent (use a hook).

Hooks vs Strict Tool Schemas

Task 4.3 introduces strict: true on tool schemas — a schema-validation deterministic gate on output shape. Hooks are a code-level deterministic gate on behavior. Both live on the deterministic-enforcement side of the compliance ledger. For a "the extracted JSON must always have a confidence field" requirement, strict schemas are cleaner; for a "the refund amount must not exceed $500" requirement, hooks are the answer.

Hooks vs Structured Error Responses

Task 2.2 covers structured error responses (errorCategory, isRetryable). Hooks can produce structured errors as the result of a block, aligning naturally with the MCP error convention. When a PreToolUse hook blocks a call, returning a structured error rather than a plain string helps the model decide whether to retry with different inputs or abort.

Agent SDK Hooks Frequently Asked Questions (FAQ)

What is the difference between a PreToolUse hook and a PostToolUse hook on the CCA-F exam?

A PreToolUse hook fires after the model has decided to call a tool but before the SDK dispatches the call — it is the deterministic gate for prevention, input mutation, policy enforcement, and redirecting to alternative workflows. A PostToolUse hook fires after the tool has executed and its result is available but before that result is appended to the conversation — it is the deterministic transformation point for normalization, PII redaction, enrichment, and audit logging. A CCA-F rule of thumb: if the requirement is prevention, the answer is PreToolUse; if the requirement is transformation or observation after the fact, the answer is PostToolUse.

Can a PostToolUse hook prevent a tool from running?

No. By the time PostToolUse fires, the tool has already executed and any side effect (database write, refund issued, email sent) has already happened. PostToolUse can only shape what the model sees after the fact. For prevention of side effects, you must use a PreToolUse hook (or another pre-execution gate) so the tool never runs in the first place. This is one of the highest-frequency CCA-F trap patterns — candidates who pick PostToolUse for a prevention requirement lose points.

When should I use a hook versus a system prompt instruction on the CCA-F exam?

Use a hook whenever the requirement is a hard compliance rule — "must never," "always," "guaranteed to," or anything legal, financial, or safety-critical. Hooks give deterministic enforcement: they always run on every invocation. Use a system prompt for soft guidance: tone, preferences, default styles, typical behaviors. System prompts give probabilistic compliance: the model usually follows them but can deviate on any given call. The exam repeatedly tests this choice by offering two correct-looking answers, one that strengthens the prompt and one that adds a hook. For hard rules, pick the hook.

How do I normalize heterogeneous tool result formats using Agent SDK hooks?

Register a PostToolUse hook on the affected tools. Inside the hook, detect the incoming format and convert it to a canonical shape before the SDK injects the result into the conversation. A typical case: one API returns Unix epoch timestamps, another returns ISO 8601, and a third returns numeric status codes like 1, 2, 3. The hook normalizes all three into ISO 8601 UTC timestamps and named status enums (pending, shipped, delivered) so the model always sees a uniform schema. This removes per-turn format-reasoning overhead and reduces the chance of model errors on inconsistent data.

How does the refund-threshold pattern work in a Customer Support Resolution Agent scenario?

The agent has a process_refund(amount, order_id) tool. Policy says refunds over USD 500 require human approval. Implementation: a PreToolUse hook on process_refund inspects amount. If amount <= 500, the hook passes through and the tool runs normally. If amount > 500, the hook blocks the direct refund, creates an escalation ticket in the human-agent queue (including full context), and returns a synthetic tool result like {status: "escalated", ticket_id: "CSR-4412"}. The model reads that result and tells the customer a human will review within 24 hours. The refund guarantee is structural — the model cannot bypass it even if the prompt were weakened.

What happens if a PreToolUse or PostToolUse hook itself throws an exception?

The SDK's principled default is fail-closed for PreToolUse (treat the errored hook as a block — safer than allowing a potentially non-compliant call) and fail-open-with-logging for PostToolUse (pass the original raw result through and log the hook failure — dropping the result entirely would break the agentic loop). In both cases the system should log and alert so operators can fix the hook. CCA-F scenarios sometimes ask which failure mode is appropriate; the answer depends on whether the hook is a safety gate (fail closed) or an observability transform (fail open).

Are Agent SDK hooks the same as Claude Code slash commands or skills?

No. Hooks are SDK-level lifecycle callbacks that fire on tool-call events and run as regular code in your application process. Slash commands and skills are Claude Code configuration features that affect how the agent is prompted and what commands the user can run interactively. The two live at different layers: hooks shape the agent's runtime tool-call behavior deterministically; slash commands and skills shape prompt composition and user workflows. They can coexist — a Claude Code project can define skills that launch tool-using agents, and those agents can register PreToolUse hooks for policy enforcement.

Further Reading

• Claude Agent SDK Overview: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview
• Subagents in the Agent SDK: https://docs.anthropic.com/en/docs/claude-code/sdk/subagents
• Handle Tool Calls — Tool Result Format: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/handle-tool-calls
• Writing Tools for Agents — Anthropic Engineering: https://www.anthropic.com/engineering/writing-tools-for-agents
• Tool Use Overview: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
• Orchestrate Teams of Claude Code Sessions: https://code.claude.com/docs/en/agent-teams
• CCA-F Exam Guide (official PDF): https://everpath-course-content.s3-accelerate.amazonaws.com/instructor/8lsy243ftffjjy1cx9lm3o2bw/public/1773274827/Claude+Certified+Architect+%E2%80%93+Foundations+Certification+Exam+Guide.pdf

Related ExamHub topics: Agentic Loops for Autonomous Task Execution, Subagent Invocation, Context Passing, and Spawning, Tool Interface Design — Descriptions and Boundaries, Structured Error Responses for MCP Tools.