Agent SDK Hooks

Agent SDK hooks inject deterministic behavior into an otherwise probabilistic system. They sit at the boundary between the model's decisions and real-world execution, intercepting tool calls and tool results to enforce business rules and normalize data. Two hook types dominate the exam, and the entire trick is knowing which runs before execution and which runs after.

PreToolUse: block before execution

A PreToolUse hook runs *before* a tool executes. It can block, modify, or redirect the outgoing call, which makes it the tool for policy enforcement and prerequisite gates. Because it fires first, a non-compliant action never happens. Typical uses:

• Block process_refund when the amount exceeds $500 and redirect to human escalation.
• Block transfer_funds until an AML check has returned a verified pass.
• Pause approve_discount above 20% and route it into an approval queue.

PostToolUse: normalize after execution

A PostToolUse hook runs *after* the tool completes but *before* the model sees the result. Its main job is data normalization - guaranteeing clean, consistent data reaches the model no matter which tool produced it. For example, three MCP tools might return Unix timestamps, ISO 8601 dates, and DD/MM/YYYY dates, plus numeric, English, and single-character status codes. Without normalization the model re-interprets that chaos every iteration and makes parsing errors; a PostToolUse hook converts everything to one format first.

// PreToolUse: enforce a refund ceiling BEFORE the tool runs.
const preToolUse = async (toolName: string, input: any) => {
  if (toolName === "process_refund" && input.amount > 500) {
    return { decision: "block", reason: "Refunds over $500 need approval." };
  }
  return { decision: "allow" };
};

// PostToolUse: normalize timestamps AFTER the tool runs.
const postToolUse = async (toolName: string, output: any) => {
  if (output.created_at && typeof output.created_at === "number") {
    output.created_at = new Date(output.created_at * 1000).toISOString();
  }
  return { updatedToolOutput: output };
};

// PostToolUse - too late, money already moved
if (output.amount > 500) return { decision: "block" };

// PreToolUse - blocks before the tool runs
if (input.amount > 500) return { decision: "block" };