1.5 Agent SDK hooks for interception and normalization
Hooks are the mechanism that turns probabilistic behaviour into a guarantee — see the hooks reference for the full event list. The design goal is a fail-safe: the gate holds even when the model does not comply.
| Hook role | Fires | Typical use |
|---|---|---|
PostToolUse | After a tool returns, before the model sees the result | Normalize heterogeneous data, trim verbose payloads, redact |
| Tool-call interception (pre-execution) | Before a tool executes | Enforce policy, block the call, redirect to another workflow |
PostToolUse for data normalization
Different MCP tools return different shapes for the same concept — Unix timestamps, ISO 8601 strings, numeric status codes. Normalizing in a hook means the agent never has to reason about format:
- TypeScript
- Python
// Illustrative PostToolUse transformation.
function normalizeOrder(raw: Record<string, unknown>) {
return {
order_id: raw.id ?? raw.order_number,
// Unix seconds, Unix millis, and ISO 8601 all collapse to one format.
placed_at: toIso8601(raw.created ?? raw.created_at ?? raw.placed_at),
// Numeric status codes collapse to a shared enum.
status: STATUS_CODES[raw.status as number] ?? String(raw.status),
};
}
# Illustrative PostToolUse transformation.
def normalize_order(raw: dict) -> dict:
return {
"order_id": raw.get("id") or raw.get("order_number"),
# Unix seconds, Unix millis, and ISO 8601 all collapse to one format.
"placed_at": to_iso8601(
raw.get("created") or raw.get("created_at") or raw.get("placed_at")
),
# Numeric status codes collapse to a shared enum.
"status": STATUS_CODES.get(raw["status"], str(raw["status"])),
}
Interception for compliance
Block policy-violating actions and redirect to an alternative workflow — a refund over $500 is not merely denied, it is routed to human escalation:
- TypeScript
- Python
// Illustrative pre-tool-use interception.
if (toolName === "process_refund" && Number(input.amount) > 500) {
return {
allow: false,
reason:
"Refunds above $500 require human approval. Call escalate_to_human with a structured handoff summary instead.",
};
}
# Illustrative pre-tool-use interception.
if tool_name == "process_refund" and float(tool_input["amount"]) > 500:
return {
"allow": False,
"reason": (
"Refunds above $500 require human approval. Call escalate_to_human "
"with a structured handoff summary instead."
),
}
Choosing hooks over prompts
Choose hooks when business rules require guaranteed compliance. Choose prompts when you want influence, not a gate.
Quiz
- Question 1
Three MCP tools report time differently: get_customer returns Unix epoch seconds, lookup_order returns ISO 8601 with a timezone offset, and the legacy billing tool returns a US-format date string alongside a numeric status code. The agent regularly miscomputes "days since order" and has quoted the wrong return window to customers. You cannot change the three backends. Which change fixes this for all of them at once?
- Question 2
Extracted documents occasionally contain customer national identity numbers, and policy forbids those values from entering the model’s context at all. The OCR service that returns document text belongs to another team and cannot be changed on your timeline. Where does the redaction belong?
- Question 3
A hook blocks process_refund calls above the $500 policy cap and returns {"error": "blocked"}. In production the agent retries the same call two or three times, then tells the customer the system is unavailable and ends the conversation. What should the hook return instead?
- Question 4
The legacy billing tool returns status as an integer — 0 success, 1 pending, 2 failed, 7 reversed. The agent has read "2" as a quantity and told a customer their refund was "processed twice". The billing service is owned by another team and is frozen for the quarter. What is the fix?