Intercept and control agent behavior with hooks

Hooks are callback functions that run your code in response to agent events, like a tool being called, a session starting, or execution stopping. With hooks, you can:

Block dangerous operations before they execute, like destructive shell commands or unauthorized file access
Log and audit every tool call for compliance, debugging, or analytics
Transform inputs and outputs to sanitize data, inject credentials, or redirect file paths
Require human approval for sensitive actions like database writes or API calls
Track session lifecycle to manage state, clean up resources, or send notifications

How hooks work

An event fires

Something happens during agent execution and the SDK fires an event: a tool is about to be called (PreToolUse), a tool returned a result (PostToolUse), a subagent started or stopped, the agent is idle, or execution finished. See the full list of events.

The SDK collects registered hooks

The SDK checks for hooks registered for that event type. This includes callback hooks you pass in options.hooks and shell command hooks from settings files when the corresponding settingSources or setting_sources entry is enabled, which it is for default query() options.

Matchers filter which hooks run

If a hook has a matcher pattern (like "Write|Edit"), the SDK tests it against the event’s target (for example, the tool name). Hooks without a matcher run for every event of that type.

Callback functions execute

Each matching hook’s callback function receives input about what’s happening: the tool name, its arguments, the session ID, and other event-specific details.

Your callback returns a decision

After performing any operations (logging, API calls, validation), your callback returns an output object that tells the agent what to do: allow the operation, block it, modify the input, or inject context into the conversation.

The following example puts these steps together. It registers a PreToolUse hook (step 1) with a "Write|Edit" matcher (step 3) so the callback only fires for file-writing tools. When triggered, the callback receives the tool’s input (step 4), checks if the file path targets a .env file, and returns permissionDecision: "deny" to block the operation (step 5):

import asyncio
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeSDKClient,
    ClaudeAgentOptions,
    HookMatcher,
    ResultMessage,
)


# Define a hook callback that receives tool call details
async def protect_env_files(input_data, tool_use_id, context):
    # Extract the file path from the tool's input arguments
    file_path = input_data["tool_input"].get("file_path", "")
    file_name = file_path.split("/")[-1]

    # Block the operation if targeting a .env file
    if file_name == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }

    # Return empty object to allow the operation
    return {}


async def main():
    options = ClaudeAgentOptions(
        hooks={
            # Register the hook for PreToolUse events
            # The matcher filters to only Write and Edit tool calls
            "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]
        }
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Create a .env file with the standard local development database configuration")
        async for message in client.receive_response():
            # Filter for assistant and result messages
            if isinstance(message, (AssistantMessage, ResultMessage)):
                print(message)


asyncio.run(main())

import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

// Define a hook callback with the HookCallback type
const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => {
  // Cast input to the specific hook type for type safety
  const preInput = input as PreToolUseHookInput;

  // Cast tool_input to access its properties (typed as unknown in the SDK)
  const toolInput = preInput.tool_input as Record<string, unknown>;
  const filePath = toolInput?.file_path as string;
  const fileName = filePath?.split("/").pop();

  // Block the operation if targeting a .env file
  if (fileName === ".env") {
    return {
      hookSpecificOutput: {
        hookEventName: preInput.hook_event_name,
        permissionDecision: "deny",
        permissionDecisionReason: "Cannot modify .env files"
      }
    };
  }

  // Return empty object to allow the operation
  return {};
};

for await (const message of query({
  prompt: "Create a .env file with the standard local development database configuration",
  options: {
    hooks: {
      // Register the hook for PreToolUse events
      // The matcher filters to only Write and Edit tool calls
      PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]
    }
  }
})) {
  // Filter for assistant and result messages
  if (message.type === "assistant" || message.type === "result") {
    console.log(message);
  }
}

When you run either script, Claude attempts to create the .env file, the hook denies the tool call, and Claude’s final response explains that it can’t create .env files.

Available hooks

The SDK provides hooks for different stages of agent execution. Some hooks are available in both SDKs, while others are TypeScript-only.

Hook Event	Python SDK	TypeScript SDK	What triggers it	Example use case
`PreToolUse`	Yes	Yes	Tool call request (can block or modify)	Block dangerous shell commands
`PostToolUse`	Yes	Yes	Tool execution result	Log all file changes to audit trail
`PostToolUseFailure`	Yes	Yes	Tool execution failure	Handle or log tool errors
`PostToolBatch`	No	Yes	A full batch of tool calls resolves, once per batch before the next model call	Inject conventions once for the whole batch
`UserPromptSubmit`	Yes	Yes	User prompt submission	Inject additional context into prompts
`UserPromptExpansion`	No	Yes	A user-typed command, or an MCP prompt, expands into a prompt before it reaches Claude. Doesn’t fire when Claude invokes a skill itself	Block a command from direct invocation or add context when a skill is typed
`MessageDisplay`	No	Yes	An assistant message with text completes, once per message with the full message text	Redact or reformat the displayed text without changing the transcript
`Stop`	Yes	Yes	Agent execution stop	Save session state before exit
`StopFailure`	No	Yes	The turn ends with an API error instead of a normal stop	Log failures or send alerts
`SubagentStart`	Yes	Yes	Subagent initialization	Track parallel task spawning
`SubagentStop`	Yes	Yes	Subagent completion	Aggregate results from parallel tasks
`PreCompact`	Yes	Yes	Conversation compaction request	Archive full transcript before summarizing
`PostCompact`	No	Yes	Conversation compaction completes	Log the generated summary
`PermissionRequest`	Yes	Yes	A tool call needs a permission decision	Custom permission handling
`PermissionDenied`	No	Yes	Auto mode denies a tool call, including denials without a classifier verdict	Log denials, or tell the model it may retry; Claude Code ignores `retry: true` for no-verdict denials. See PermissionDenied
`SessionStart`	No	Yes	Session initialization	Initialize logging and telemetry
`SessionEnd`	No	Yes	Session termination	Clean up temporary resources
`Notification`	Yes	Yes	Agent status messages	Send agent status updates to Slack or PagerDuty
`Setup`	No	Yes	Session setup/maintenance	Run initialization tasks
`TeammateIdle`	No	Yes	Teammate becomes idle	Reassign work or notify
`TaskCreated`	No	Yes	A task is created via the `TaskCreate` tool	Enforce task naming conventions
`TaskCompleted`	No	Yes	A task is marked completed	Require passing tests before a task closes
`Elicitation`	No	Yes	An MCP server requests user input mid-task	Respond to MCP input requests programmatically
`ElicitationResult`	No	Yes	A user responds to an MCP elicitation	Modify or block the response before it returns to the server
`ConfigChange`	No	Yes	Configuration file changes	Reload settings dynamically
`InstructionsLoaded`	No	Yes	A `CLAUDE.md` or rules file is loaded into context	Audit which instruction files load
`WorktreeCreate`	No	Yes	Git worktree created	Track isolated workspaces
`WorktreeRemove`	No	Yes	Git worktree removed	Clean up workspace resources
`CwdChanged`	No	Yes	The working directory changes during a session	Reload environment variables per directory
`FileChanged`	No	Yes	A watched file is modified, created, or deleted	Reload configuration when project files change
`DirectoryAdded`	No	Yes	A working directory is added during a session	Install dependencies for a repository added mid-session

Configure hooks

To configure a hook, pass it in the hooks field of your agent options (ClaudeAgentOptions in Python, the options object in TypeScript). This snippet assumes you have already defined a hook callback, like protect_env_files in Python or protectEnvFiles in TypeScript from the example above:

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[my_callback])]}
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Your prompt")
    async for message in client.receive_response():
        print(message)

for await (const message of query({
  prompt: "Your prompt",
  options: {
    hooks: {
      PreToolUse: [{ matcher: "Bash", hooks: [myCallback] }]
    }
  }

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Intercept and control agent behavior with hooks

How hooks work

Available hooks

Configure hooks

​How hooks work

​Available hooks

​Configure hooks

How hooks work

Available hooks

Configure hooks