Agent SDK hooks: CCAR-F task statement 1.5

Task statement 1.5 sits in Agentic Architecture & Orchestration, 27% of the CCAR-F exam. It tests one decision above all: when a business rule must hold every time, enforce it in code with a hook, not with an instruction in the prompt.

What the official guide covers

The Claude Certified Architect Foundations exam guide (version 1.0, effective July 2026) lists this under task statement 1.5, "Apply Agent SDK hooks for tool call interception and data normalization":

What hooks do

A hook is your own function that the Agent SDK runs at a set point in the agent's work. Two hooks matter most for this task statement:

A matcher chooses which tools a hook applies to, for example "process_refund" or "^mcp__" for every MCP tool. If several hooks match, a deny from any of them blocks the call.

Why the exam prefers hooks for hard rules

An instruction in the system prompt, such as "never refund more than $500", works most of the time. The guide calls this probabilistic compliance. A PreToolUse hook checks every process_refund call in code, so a refund above the limit cannot run. When the question says a rule must hold "every time", "always" or "never", the answer is a hook.

Return a clear reason with every deny. Claude reads permissionDecisionReason, does not retry the blocked call, and can tell the customer what happens next, for example that a person will review the refund.

A refund limit as a hook (Python)

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

REFUND_LIMIT = 500

async def enforce_refund_limit(input_data, tool_use_id, context):
    amount = input_data["tool_input"].get("amount", 0)
    if amount > REFUND_LIMIT:
        create_review_ticket(input_data["tool_input"])   # your escalation workflow
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": (
                    f"Refunds over ${REFUND_LIMIT} need human approval. "
                    "A review ticket has been created."
                ),
            }
        }
    return {}   # allow the call unchanged

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="mcp__billing__process_refund", hooks=[enforce_refund_limit])
        ]
    }
)

The hook runs in your code on every process_refund call. Claude never sees a path around it. A PostToolUse hook follows the same pattern: it reads the tool's result and returns updatedToolOutput with the converted data, so Claude only ever reads the normalised version.

Hook, prompt or permission?

Where it appears in the exam

Domain 1 is a primary domain in three of the six exam scenarios: Customer Support Resolution Agent, Multi-Agent Research System and Developer Productivity with Claude. Refund limits and escalation fit the customer support scenario. Normalising data from several tools fits the research scenario.

Two sample questions

These are original Timo practice questions. They are not official exam questions.

Question 1

A support agent built with the Claude Agent SDK can issue refunds through a process_refund tool. Company policy says refunds over $500 must be approved by a person. In testing, the agent followed a system prompt instruction about the limit in 97 of 100 cases. What should the architect do?

A. Repeat the limit three times in the system prompt and add examples of refunds to refuse.B. Add a PreToolUse hook on process_refund that denies amounts over $500 with a reason, and route those cases to a person.C. Ask Claude to state its confidence before each refund and block refunds below 90% confidence.D. Review a sample of refunds each week and reverse any that broke the policy.

Answer: B. The hook checks every call in code, so the rule holds every time. A improves the odds but stays probabilistic. C measures the wrong thing; confidence does not show whether an amount is over the limit. D finds the problem after the money has gone.

Question 2

A research agent calls three MCP tools that return dates as Unix timestamps, ISO 8601 strings and "DD/MM/YYYY" text. Claude sometimes puts events in the wrong order. Which change fixes the cause?

A. Add a PostToolUse hook that converts every date in the results to ISO 8601 before Claude reads them.B. Tell Claude in the system prompt to convert all dates before comparing them.C. Ask the three MCP server vendors to change their date formats.D. Raise the model's effort level so it reasons more carefully about dates.

Answer: A. The hook converts the results in code, so Claude always reads one format. B relies on Claude converting correctly every time. C is outside the team's control, and D does not remove the mixed formats that cause the errors.

Build exercise

1. Give an Agent SDK agent a process_refund tool and add the PreToolUse hook above.
2. Ask for a $200 refund and a $900 refund. Confirm the first runs and the second is denied with the reason shown to Claude.
3. Add a second tool that returns dates as Unix timestamps. Write a PostToolUse hook that converts them to ISO 8601 and check what Claude reads.
4. Remove the hook and put the refund limit in the system prompt instead. Run 50 mixed requests and count how often the limit is broken. That count is the difference between probabilistic and deterministic compliance.

Practise this topic

• Claude Certified Architect practice exam: free, 20 questions, no sign-up
• Claude Certified Architect hub
• CCAR-F study guide: all topics
• Worked example: Claude Agent SDK hooks
• Previous topic: 1.4 Workflow enforcement and handoff
• Next topic: 1.6 Task decomposition

Sources

• Claude Certified Architect Foundations Exam Guide, version 1.0, effective July 2026 (Anthropic), task statement 1.5
• Claude Agent SDK documentation: Hooks
• Anthropic: Building effective agents