Task statement 1.5 · Agentic architecture and orchestration

Apply Agent SDK hooks for tool call interception and data normalization

Policy lets the support agent refund up to $500 on its own, and anything larger goes to a human. Agent SDK hooks let your own code hold that limit on every process_refund call, and clean up what the MCP tools return before the agent reads it.

Scenario switchThis section stays on the Customer Support Resolution Agent, like 1.4, because the guide writes 1.5 in refund vocabulary: a $500 refund limit, and mixed data formats coming back from different MCP tools.
Why it's tested

The tempting fix for an over-limit refund is a firmer system prompt. That makes violations rarer, but prompt compliance is probabilistic, so across thousands of chats some refunds above $500 still go through, and each one moves money. Checking the amount in PostToolUse is too late, because that event fires after the refund has been paid. For mixed data formats, a prompt that documents each tool's conventions still leaves the model decoding them on every turn.

KnowledgeHow an SDK hook intercepts a tool call

In the Agent SDK, a hook is a callback function that you pass in the hooks field of the query options (ClaudeAgentOptions in Python). That field maps an event name, such as PreToolUse, to a list of HookMatcher entries, and each entry holds a matcher pattern plus the callbacks to run. The pattern is tested against the tool name, and MCP tools are named mcp__<server>__<tool>, so mcp__support__process_refund selects one tool on the support server. The callback receives the event's input, including tool_name and tool_input, and returns an object. The SDK runs it on every matching call, so the guarantee is deterministic rather than a request the model may ignore.

PreToolUse fires before the tool executes, so it can prevent an action. Its callback sets permissionDecision to "deny" to refuse the call or "allow" to approve it without a permission prompt, and returning {} leaves the call to the normal permission rules. PostToolUse fires after the tool has returned, and its input adds tool_response, the result. It cannot undo what the tool did, but it can replace what Claude reads by returning updatedToolOutput. So a rule that must prevent a refund belongs in PreToolUse, and a transformation of results belongs in PostToolUse.

  1. Claude requests process_refund with amount: 800 for order 10024871.
  2. Before the call runs, the SDK matches mcp__support__process_refund and calls your PreToolUse callback.
  3. The callback, ordinary code with no model involved, compares 800 with 500.
  4. It returns "deny" with a permissionDecisionReason, so the refund tool never runs.
  5. Claude reads the reason and takes the alternative workflow: escalate_to_human.

Interactive · one PreToolUse callback, three outcomes

A process_refund tool call flowing downward into a PreToolUse callback. Returning an empty object lets the refund tool run. Returning deny with a reason, or timing out, stops the tool from running, and Claude reads why. process_refund amount: 180.00 or 800.00 amount: 180.00 amount: 800.00 amount: 300.00 tool call, not yet executed PreToolUse callback amount > 500 ? deny : return {} 180 > 500 ? no → return {} 800 > 500 ? yes → deny no return before timeout → cancelled returns {} deny + reason blocked (timeout) refund tool runs customer refunded tool never runs Claude reads reason, escalates Claude told: hook timed out

Choose what the refund callback meets.

Within the limit: the callback returns {} and the call goes ahead.

Over the limit: the callback denies before the tool runs.

Callback timed out: the SDK blocks the call.

The callback decides before the tool runs: $180 gets {} and runs, $800 is denied with a reason, and a timed-out callback blocks the call. $180 is within the $500 limit, so the callback returns {} and the refund tool runs as normal. $800 is over the limit, so the callback returns permissionDecision: "deny" with a reason. The tool never runs, and the reason sends Claude to escalate_to_human. The callback is still waiting on a slow service when its timeout expires. A timed-out SDK callback on PreToolUse blocks the call, even for a $300 refund, and Claude receives a result saying the hook did not respond.

Here is the whole gate. The reason matters as much as the denial, because Claude reads it, so it learns which workflow to take instead of retrying.

# PreToolUse: refuse refunds above the limit, redirect to a human
async def refund_limit(input_data, tool_use_id, context):
    amount = input_data["tool_input"]["amount"]
    if amount <= 500:
        return {}
    return {"hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": f"${amount} is over the $500 limit. "
            "Call escalate_to_human with order, amount and reason."}}

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

More precise than the guide. The guide does not say what happens when a hook is slow. An SDK callback runs under the timeout on its HookMatcher (600 seconds by default), and a PreToolUse callback that exceeds it blocks the call: the tool does not run, and Claude receives a result saying the hook did not respond. A shell command hook from a settings file does the opposite and lets the call continue (checked 2026-09-30). Exam answer: a PreToolUse hook guarantees the rule, and a timed-out SDK callback blocks the call.

SkillNormalising what the MCP tools return

A customer asks when order 10024871 arrived. lookup_order returns "delivered": 1789221900, a Unix timestamp, and "status": 4, a numeric status code, while get_customer sends ISO 8601 strings such as "2023-10-11T16:00:00Z". The agent says the order is still in transit, because it guessed that 4 means shipped, and in the order system 4 means delivered. The cause is raw backend formats that the model must decode on every turn. The fix is one PostToolUse callback whose matcher, ^mcp__support__, covers every support tool. It rewrites dates as ISO 8601 and codes as names, and returns updatedToolOutput, which replaces what Claude sees before the agent processes it.

# PostToolUse: one format for every support tool
async def normalise(input_data, tool_use_id, context):
    data = parse(input_data["tool_response"])
    data = unix_to_iso(data)                 # 1789221900 → "2026-09-12"
    data = status_names(data)                # 4 → "delivered"
    return {"hookSpecificOutput": {"hookEventName": "PostToolUse",
        "updatedToolOutput": repack(data)}}   # same shape as the original

HookMatcher(matcher="^mcp__support__", hooks=[normalise])
Before the hook

What lookup_order returns

"order_id": "10024871",
"delivered": 1789221900,
"status": 4
After the hook

What Claude reads

"order_id": "10024871",
"delivered": "2026-09-12",
"status": "delivered"
The decision test Would one violation in a thousand calls be acceptable? No → the business rule needs guaranteed compliance, so enforce it in a PreToolUse callback that denies with a reason pointing to the alternative workflow. Yes → a prompt instruction is cheaper, and its probabilistic compliance is good enough.
Takeaway
  • SDK hooks are callbacks registered as HookMatcher entries under hooks in the query options, and MCP tools match as mcp__<server>__<tool>.
  • permissionDecisionReason redirects the agent after a deny. A timed-out SDK callback also blocks the call.
  • PostToolUse cannot undo a refund, but updatedToolOutput can replace mixed timestamps and status codes before Claude reads them.

check yourself

0 / 3 answered

Support leads want the agent to share the carrier's tracking link whenever lookup_order shows an order in transit. When the agent forgets, the customer simply asks for the link, and nothing else is affected. The team already maintains two SDK hooks and wants no more code to own than it needs.Which is the most proportionate way to get this behaviour?

Select one.

A PreToolUse callback on process_refund asks a fraud-scoring service before every refund, and its HookMatcher sets timeout=5. The service answers in 3 to 9 seconds. For 4% of refunds the tool never runs, and Claude receives a result saying the hook did not respond. Finance requires a fraud score before any refund, and human agents are at capacity.Which change best stops these failures while preserving the fraud-score requirement?

Select one.

Finance forbids refunds to any payment method other than the order's original one, yet the agent sometimes passes a different card ID to process_refund. Separately, get_customer returns loyalty tier as "tier": 2, and the agent has told Gold customers they are Silver. Support leads want the tier right in every reply. Neither backend can change this quarter.Which TWO hook registrations best fix both problems?

Select two.

sources

  1. Claude Docs, Agent SDK, "Intercept and control agent behavior with hooks": callbacks in the hooks option, HookMatcher with matcher, hooks and timeout, the mcp__<server>__<action> tool-name pattern, permissionDecision ("allow", "deny", "ask", "defer") and permissionDecisionReason telling the model why, updatedToolOutput for any tool with updatedMCPToolOutput deprecated, and "Hook timeout": a timed-out PreToolUse callback means the tool call does not run. Checked 2026-09-30.
  2. Claude Docs, "Hooks reference": tool_response in the PostToolUse input, updatedToolOutput changing only what Claude sees, and "Timeouts": a timed-out command, http or mcp_tool hook does not block the call, while an Agent SDK callback does. Checked 2026-09-30.
  3. The $500 refund limit, human escalation, and the Unix timestamp, ISO 8601 and numeric status code example: Claude Certified Architect — Foundations Exam Guide v1.0, Domain 1.5. Tool names: the guide's Scenario 1. The helpers parse, unix_to_iso, status_names and repack stand for your own code.