Agent SDK Hooks

Estimated time: 3 minutes

Two hook directions, easy to conflate, that do genuinely different jobs:

  • PostToolUse hooks intercept tool results before the model ever sees them. The canonical use is normalization — three MCP tools returning dates as a Unix timestamp, an ISO 8601 string, and a numeric status code respectively, unified into one representation before the model has to reason about any of them.
  • Interception hooks intercept outgoing tool calls, to enforce compliance deterministically — blocking a refund above a policy threshold and redirecting to escalation, before the call ever executes.

Hooks give guarantees; prompts give probabilities. Choose a hook whenever a business rule requires guaranteed compliance rather than usually-followed guidance — which is the same underlying principle as §4, applied at the tool-call layer instead of the workflow layer.

The trap that looks reasonable and usually is: asking the model to normalize formats itself, or simply documenting the formats in the system prompt. That works most of the time — which is exactly why it's the wrong answer whenever a scenario mentions something like date arithmetic feeding a policy decision or an audit requirement, where "usually correct" isn't the bar.