Skip to content
BENIBIX Learn

Hook Callback

Also known as hooks option, HookCallbackMatcher, Agent SDK hooks, Claude Agent SDK Hook

Your own function that the kit runs at a set step.

Think of it like

It is like a doorbell that rings in your own room.

Example

Leo's hook checks every Write call. If the path is a .env file, it blocks the call and tells Claude why.

Why it matters

It is the first check a tool call meets. It can stop the call before any rule is read.

Definition

A hook callback is a function in your own code that the Agent SDK calls at a set point in the agent loop, such as before a tool runs. You pass them in the hooks option, keyed by event name, such as PreToolUse. A matcher such as Write|Edit limits which tools fire it. The callback can let the call go on, block it, or change its input. Hooks run before any permission rule.

Example code

typescript
hooks: {
  PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }],
}
Run a check before each file write or edit.

Common mistake

Writing hooks in settings files and expecting the SDK to call your function. SDK hooks are passed in code.

Key takeaways

  1. 1
    Your function. Called by the SDK.
  2. 2
    Matcher filters. By tool name.
  3. 3
    First in order. Before rules.