Apply Agent SDK hooks for tool call interception and data normalization

Hooks are callbacks the Agent SDK runs at fixed points in the agentic loop. Unlike the system prompt, which is advice the model may or may not follow, a hook is ordinary code that runs every time its event fires. That makes hooks the right tool whenever an outcome must be guaranteed rather than merely encouraged.

You register hooks in the SDK options, keyed by event name. Each entry is a HookMatcher whose matcher field filters which tool names trigger the hook (it accepts a regex such as 'Write|Edit') plus a list of callback functions.

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

options = ClaudeAgentOptions(
    hooks={
        'PreToolUse':  [HookMatcher(matcher='process_refund', hooks=[block_large_refund])],
        'PostToolUse': [HookMatcher(matcher='lookup_order',   hooks=[normalize_order])],
    }
)

Each callback receives (input_data, tool_use_id, context). input_data carries hook_event_name, tool_name, and tool_input; a PostToolUse callback also gets tool_response. The callback returns a dict, and an empty dict means 'proceed unchanged'.

The two events that matter for this task statement are PreToolUse, which fires before a tool runs, and PostToolUse, which fires after it returns. Everything below builds on that timing distinction.

PreToolUse fires after the model has decided to call a tool but before the tool actually executes. It is the interception point for enforcing compliance, because it is the only place you can stop a side effect from happening at all.

The callback returns a hookSpecificOutput object. Set permissionDecision to 'deny' to block the call, 'allow' to force-approve it, or 'ask' to request confirmation. Always include permissionDecisionReason: that text is fed back to the model, so a good reason lets the model recover by choosing another path (for example, escalating to a human) instead of stalling.

async def block_large_refund(input_data, tool_use_id, context):
    if input_data['tool_name'] == 'process_refund':
        amount = input_data['tool_input'].get('amount', 0)
        if amount > 500:
            return {
                'hookSpecificOutput': {
                    'hookEventName': 'PreToolUse',
                    'permissionDecision': 'deny',
                    'permissionDecisionReason': 'Refunds over $500 need human approval. Call escalate_to_human instead.'
                }
            }
    return {}

PreToolUse can also rewrite arguments before execution by returning updatedInput, which is handy for injecting safety flags or clamping parameters. But its headline use is the hard gate: a policy-violating action never reaches your backend.

PostToolUse fires after a tool returns but before the result is handed back to the model. Its input includes tool_response, the raw output of the tool. This is the correct place to normalize heterogeneous data so the model always reasons over one consistent shape.

Production systems wire many MCP tools to different backends, each with its own conventions: one returns a Unix epoch timestamp, another ISO 8601, a third a numeric status code like 2. If you leave this to the model, it must infer formats on every turn, burns tokens, and eventually errs. A PostToolUse hook converts everything deterministically. Return the rewritten payload in updatedToolOutput, or attach clarifying text with additionalContext.

STATUS = {0: 'pending', 1: 'shipped', 2: 'delivered', 3: 'returned'}

async def normalize_order(input_data, tool_use_id, context):
    order = dict(input_data['tool_response'])
    ts = order.get('created_at')
    if isinstance(ts, (int, float)):            # Unix epoch to ISO 8601
        order['created_at'] = datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()
    if isinstance(order.get('status'), int):    # numeric code to label
        order['status'] = STATUS.get(order['status'], 'unknown')
    return {
        'hookSpecificOutput': {
            'hookEventName': 'PostToolUse',
            'updatedToolOutput': order
        }
    }

Because the hook is centralized, you fix format drift in one place instead of teaching every prompt and every tool the same rules.

The core judgement this task tests is knowing when a hook is the answer versus a prompt instruction. A system prompt such as 'never process a refund above $500' is guidance: the model obeys most of the time, but its compliance is probabilistic and a non-zero failure rate is expected, especially under ambiguous or adversarial input. When money moves, identity is verified, or PII is redacted, 'most of the time' is not acceptable.

A hook is code on the execution path. If the callback denies process_refund for amounts over 500, there is no phrasing, ordering, or jailbreak that lets a $750 refund through. The guarantee is structural, not persuasive.

The rule to memorize: choose hooks over prompt-based enforcement whenever a business rule must be guaranteed. Reserve prompts and few-shot examples for shaping judgement and tone, where some variance is tolerable. This mirrors task statement 1.4's split between programmatic enforcement and prompt-based guidance.

The single most tested nuance is timing. PreToolUse runs before execution; PostToolUse runs after. That ordering decides which hook fits which job.

To block or alter a side-effecting action, you must use PreToolUse. If you tried to enforce the refund cap in a PostToolUse hook on process_refund, the refund would already be issued by the time your code ran, so blocking it then is too late. Conversely, you cannot normalize data in PreToolUse, because the result does not exist yet; normalization belongs in PostToolUse, where tool_response is available.

A compact way to remember it: PreToolUse guards the door, PostToolUse cleans the delivery. Prevention and compliance go in front, transformation and sanitization go behind.

A denied tool call does not end the conversation. When PreToolUse returns a deny decision, the model receives the permissionDecisionReason as feedback and continues the agentic loop, now free to pick a different action. This is how a hook redirects a blocked path onto an approved workflow.

In the support scenario, blocking a large refund with the reason 'call escalate_to_human instead' nudges the model to invoke escalate_to_human on its next turn. The hook enforced the policy; the model performed the graceful recovery. A deny with no reason wastes this: the model sees a blocked action, has no guidance, and may retry the same call or give up. Always pair a block with a reason that names the correct alternative.