Agent SDK Hooks & Interception

Using Agent SDK hooks to intercept and transform tool results, enforce business rules at the code level, and implement deterministic compliance guarantees. Learn PostToolUse hooks, tool call interception, and when to choose hooks over prompt instructions.

Quick Reference

→PostToolUse hooks transform tool results BEFORE the model processes them
→Tool call interception hooks can block, modify, or redirect outgoing tool calls
→Hooks provide deterministic guarantees -- they execute every time, unlike prompt instructions
→Use hooks for data normalization: consistent date formats, units, currencies across tools
→Use hooks for compliance enforcement: block operations that exceed thresholds
→Hooks can inject additional context or metadata into tool results
→Hook execution is synchronous -- the model waits for the hook to complete
→Hooks have access to the full tool call input and output for decision-making
→Chain multiple hooks for layered enforcement (normalize -> validate -> audit)
→Hooks should be pure functions when possible -- no hidden side effects

What Are Agent SDK Hooks?

Definition

Agent SDK hooks are callback functions that execute at specific points in the agent lifecycle -- before a tool call is executed, after a tool call returns, or before the model processes results. They allow you to intercept, transform, validate, and enforce business rules at the code level, providing deterministic guarantees that prompt instructions cannot.

Hooks intercept tool calls for validation, blocking, or result transformation

Hooks sit between the agent loop and tool execution. They see everything: which tool was called, with what parameters, and what it returned. This visibility enables powerful patterns: normalizing inconsistent data formats, blocking prohibited operations, injecting audit trails, and enforcing business rules that must never be violated.

The key advantage of hooks over prompt instructions is determinism. A prompt instruction to 'never process refunds over $500' is probabilistic -- it will be followed most of the time, but not 100%. A hook that intercepts refund tool calls and blocks those exceeding $500 is deterministic -- it executes every single time, regardless of what the model attempts.

Hook Types and Lifecycle

Hook Type	When It Fires	Use Case	Can Block?
PreToolCall	Before a tool call is executed	Validate inputs, enforce permissions, block prohibited operations	Yes -- can prevent the tool from executing
PostToolUse	After a tool returns, before model processes the result	Transform output, normalize data, inject metadata	No -- tool already executed, but can modify what the model sees
PreModelCall	Before each API call to the model	Inject system context, modify messages, enforce token limits	Yes -- can modify or block the API call
PostModelCall	After model response, before processing	Log responses, enforce output policies, audit	Can modify but typically should not block

PostToolUse Hooks: Transforming Tool Results

PostToolUse hooks are the most common hook type. They transform tool results before the model processes them. The primary use case is data normalization -- ensuring that data from different tools arrives in a consistent format so the model can reason about it accurately.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.