What is an Agent SDK hook?

Developer-written code that runs at a specific point in an agent's execution lifecycle. A PreToolUse hook runs after the model has chosen a tool but before that tool executes, so it can allow, block or rewrite the call. A PostToolUse hook runs after the tool executes but before the model sees the result, so it can normalize, redact, annotate or log it.

What is the difference between PreToolUse and PostToolUse?

Timing, and therefore power. PreToolUse runs while the outcome is still undecided, so it is the only one of the two that can prevent a side effect. PostToolUse runs after the tool has already done its work, so it can inspect, clean and log the result but cannot un-send an email or reverse a transfer.

Why not just put the rule in the system prompt?

A prompt influences the model; a hook runs outside it. The model can misunderstand a prompt, ignore it, or be manipulated away from it by injected instructions. It cannot bypass application code that runs before the tool is allowed to execute. Use prompts for behaviour you want, and hooks plus backend checks for behaviour you need to enforce.

Do hooks make an agent safe?

No. Hooks are one layer. A complete production system also needs authentication, role-based access control, transaction limits, backend authorization, rate limits, monitoring and human review for high-risk actions. A hook only protects the routes that pass through it, so if another tool can cause the same side effect it needs the same policy.

Agent SDK Hooks: How to Add Reliable Controls Around AI Agent Tool Use

A hook is developer-written code that runs at a fixed point in an agent's lifecycle. This project builds both hook points from scratch: a PreToolUse hook that refuses a refund before any money moves, an AML prerequisite that reads session state instead of trusting the model, and a PostToolUse hook that turns three messy tool results into one schema before the model reads them.

AI agents are useful because they can do more than answer questions.

They can call tools, inspect results, and take actions in outside systems. That is also what makes them risky. A customer-support agent might issue refunds. A finance agent might start a transfer. A coding agent might edit files or run shell commands. Once an agent can affect real systems, prompt instructions alone are not enough. Some rules need to be enforced by application code.

That is the job of Agent SDK hooks. A hook is developer-written code that runs at a specific point in an agent's execution lifecycle. In plain English: a hook is a checkpoint. When the agent is about to use a tool, or has just received a tool result, the application can run your code to inspect, block, modify, log, or clean up what is happening.

Hooks matter because the language model is probabilistic, while ordinary application code is deterministic. A probabilistic system can behave slightly differently from one run to another. A deterministic system follows explicit logic: if the same input reaches the same code path, the same rule is applied. Hooks use this kind of deterministic logic around the model's decisions.

Fig. 1 · Where hooks sit. A PreToolUse hook runs after the model has chosen a tool but before that tool executes. A PostToolUse hook runs after it executes but before the model sees the result. Everything inside the dashed box is ordinary application code, which is why it behaves the same way every run.

The practical lesson is simple: prompt instructions are useful for shaping behaviour, and hooks are better for enforcing rules that should not be bypassed.

Sign in to view this build.

Create a free account to access the full build walkthrough on kevinsomany.com.

No account yet? Sign up free and come back here.

Agent SDK Hooks: How to Add Reliable Controls Around AI Agent Tool Use

Sign in to view this build.

Sign in or create an account.

Check your inbox.

Something went wrong.