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.
share
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.
- Claude requests
process_refundwithamount: 800for order 10024871. - Before the call runs, the SDK matches
mcp__support__process_refundand calls yourPreToolUsecallback. - The callback, ordinary code with no model involved, compares 800 with 500.
- It returns
"deny"with apermissionDecisionReason, so the refund tool never runs. - Claude reads the reason and takes the alternative workflow:
escalate_to_human.
Interactive · one PreToolUse callback, three outcomes
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.
{} 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])
What lookup_order returns
"order_id": "10024871", "delivered": 1789221900, "status": 4
What Claude reads
"order_id": "10024871", "delivered": "2026-09-12", "status": "delivered"
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.- SDK hooks are callbacks registered as
HookMatcherentries underhooksin the query options, and MCP tools match asmcp__<server>__<tool>. permissionDecisionReasonredirects the agent after a deny. A timed-out SDK callback also blocks the call.PostToolUsecannot undo a refund, butupdatedToolOutputcan replace mixed timestamps and status codes before Claude reads them.