Agent SDK hooks for interception and normalization

Use hooks when a rule must be enforced by code instead of left to model judgment.

An epoch timestamp represents a date and time as a number counted from January 1, 1970, in Coordinated Universal Time (UTC). In this example, the value counts seconds. The hook converts it to the ISO 8601 date format before the model receives it:

// Runs in a PostToolUse hook, before the result reaches the model.
function normalizeDeliveryDate(result) {
  if (typeof result.deliveredAt === 'number') {
    result.deliveredAt = new Date(result.deliveredAt * 1000).toISOString();
  }
  return result;
}

# Runs in a PostToolUse hook, before the result reaches the model.
def normalize_delivery_date(result):
    if isinstance(result.get("deliveredAt"), (int, float)):
        result["deliveredAt"] = datetime.fromtimestamp(
            result["deliveredAt"], tz=timezone.utc
        ).isoformat()
    return result

The model receives the converted date, so it doesn't need to interpret the epoch value itself.

A hook is ordinary code that runs at the tool-call boundary. It is separate from the prompt and runs every time the tool is called. That repeated code, not a prompt instruction, provides the guarantee.

PostToolUse: normalize before the model reads it

Real backends disagree with each other. One tool returns Unix timestamps, another ISO 8601, a third numeric status codes with a lookup table nobody has read since 2019.

You can ask the model to reconcile those formats, but it may occasionally interpret one incorrectly. Those errors can be difficult to notice.

A PostToolUse hook transforms results into one consistent format before they reach the model. The model then receives one predictable format instead of having to convert each result itself.

A hook can only apply a rule you can write down. Epoch seconds map to one calendar date, so the transform is safe. A note reading "should arrive early next week" doesn't, and a hook that guesses a date replaces visible uncertainty with a confident wrong value. The limit is whether the rule has one right answer, not whether the data arrived as a structured field.

Before cooking, you can convert every measurement in the recipe to grams, or convert each one in your head as you go. Converting first removes a whole class of mistake. It also only works for measurements that convert; a pinch doesn't.

Interception: block before it happens

Hooks also sit on the outgoing side. A refund above a policy threshold can be blocked at the tool-call boundary — and, importantly, redirected. Blocking alone leaves the agent stuck; blocking and routing to human escalation leaves the customer served.

The decision rule

Ask what happens when the rule is broken. If the answer involves money, legal exposure, or safety, you need a deterministic guarantee, and a hook is how you get one. Prompt instructions are for guidance, tone, and preference — the things where an occasional miss is survivable.