Apply Agent SDK hooks for tool call interception and data normalization

Hooks are the Agent SDK's interception points around tool use. They matter for two reasons the exam cares about: data normalization on the way in, and policy enforcement on the way out. Both give you deterministic behavior in a system that is otherwise probabilistic.

PostToolUse: transform results before the model sees them

A PostToolUse hook fires after a tool executes and before the result enters the model's context.¹⁰ That is the right place to normalize heterogeneous formats. In practice an agent talks to several MCP servers written by different teams: one returns Unix epoch seconds, another ISO 8601 strings, a third returns numeric status codes where a fourth returns human labels. Left alone, the model spends tokens reconciling formats and occasionally gets it wrong — comparing a 10-digit epoch to a date string, or guessing that status 3 means shipped.

Normalizing in a PostToolUse hook means the model only ever sees one canonical shape: ISO 8601 timestamps, an enumerated status vocabulary, consistent currency units. The transformation is code, so it is exact and free of reasoning cost. It also keeps tool descriptions honest: you are not documenting four date formats and hoping.

Interception on the outgoing side: enforce policy

The mirror-image pattern intercepts an outgoing tool call and can block it. This is where business rules with hard boundaries live — refunds above $500, deletions outside a sandbox, writes to production. A blocked call should not merely fail: it should redirect to an alternative workflow, typically by returning a denial that tells the agent to escalate instead.¹³ The agent then calls escalate_to_human on the next iteration, and the outcome is a correct escalation rather than an error.

Deterministic vs probabilistic compliance

The decision rule the exam wants: a business rule that must always hold goes in a hook; guidance goes in the prompt.¹¹

Mechanism	Put the rule here when	Compliance you get	Worked example
Interception hook	The rule is a hard boundary that must always hold	Deterministic — checked in code against the actual tool input	"Never refund more than $500 without approval"
Prompt instruction	The rule is guidance the model should weigh	Probabilistic — a non-zero failure rate you have accepted	"Prefer offering a replacement before a refund for damaged goods"

Hooks are also independently auditable: you can point a compliance reviewer at a few lines of code rather than at a distribution of model behavior.

The two patterns compose. Normalize inputs so the model reasons over clean data, gate outputs so its decisions cannot cross a hard line, and reserve the prompt for everything that genuinely requires judgment.

const STATUS_CODES: Record<number, string> = {
  1: 'pending', 2: 'processing', 3: 'shipped', 4: 'delivered', 5: 'canceled',
};

// PostToolUse: runs after the tool executes, before the model sees the result.
function normalizeToolResult(toolName: string, raw: unknown) {
  const out = structuredClone(raw) as Record<string, any>;

  // Unix epoch seconds -> ISO 8601
  for (const key of ['created', 'updated', 'createdAt', 'updatedAt']) {
    const v = out[key];
    if (typeof v === 'number') out[key] = new Date(v * 1000).toISOString();
  }

  // Numeric status codes -> enumerated vocabulary
  if (typeof out.status === 'number') {
    out.status = STATUS_CODES[out.status] ?? 'unknown';
  }

  // Cents -> decimal currency, always with an explicit unit
  if (typeof out.amountCents === 'number') {
    out.amount = out.amountCents / 100;
    out.currency = out.currency ?? 'USD';
    delete out.amountCents;
  }

  return out; // the model only ever sees the canonical shape
}

const REFUND_LIMIT = 500;

function interceptToolCall(toolName: string, input: Record<string, any>) {
  if (toolName === 'process_refund' && Number(input.amount) > REFUND_LIMIT) {
    return {
      decision: 'deny' as const,
      reason:
        'Blocked: refunds above $' + REFUND_LIMIT + ' require human approval. ' +
        'Call escalate_to_human with the customer ID, root cause, amount and a ' +
        'recommended action instead.',
    };
  }
  return { decision: 'allow' as const };
}

// Deterministic: the limit is enforced on the actual tool input, so no prompt
// wording, jailbreak or reasoning slip can exceed it.