ClaudeAgentSDK.Hooks (claude_agent_sdk v0.11.0)

Type definitions and utilities for Claude Code Hooks.

Hooks are callback functions invoked by the Claude Code CLI at specific lifecycle events during agent execution. They enable:

Intercepting tool calls before/after execution
Adding contextual information automatically
Controlling execution flow based on runtime conditions
Implementing security policies and validation
Monitoring and auditing agent behavior

Hook Events

:pre_tool_use - Before a tool executes
:post_tool_use - After a tool executes
:post_tool_use_failure - After a tool execution fails
:user_prompt_submit - When user submits a prompt
:stop - When the agent finishes
:subagent_start - When a subagent spawns
:subagent_stop - When a subagent finishes
:pre_compact - Before context compaction
:notification - When agent sends a notification
:permission_request - When a permission dialog would be shown
:session_start - When a session begins
:session_end - When a session ends

Examples

# Define a hook callback
def check_bash(input, _tool_use_id, _context) do
  case input do
    %{"tool_name" => "Bash", "tool_input" => %{"command" => cmd}} ->
      if String.contains?(cmd, "rm -rf") do
        Output.deny("Dangerous command blocked")
      else
        Output.allow()
      end
    _ -> %{}
  end
end

# Configure hooks
hooks = %{
  pre_tool_use: [
    Matcher.new("Bash", [&check_bash/3])
  ]
}

See: https://docs.anthropic.com/en/docs/claude-code/hooks

Summary

Types

hook_callback()

hook_config()

Hook configuration map.

hook_context()

Context information passed to hook callbacks.

hook_event()

Hook event types supported by the SDK.

hook_input()

Input data passed to hook callbacks.

hook_output()

Hook callback function signature.

Functions

all_valid_events()

Returns all valid hook event atoms.

event_to_string(atom)

Converts an Elixir hook event atom to CLI string format.

string_to_event(arg1)

Converts a CLI hook event string to Elixir atom.

validate_config(config)

Validates a hook configuration.

Types

hook_callback()

@type hook_callback() :: (hook_input(), String.t() | nil, hook_context() ->
                      hook_output())

hook_config()

@type hook_config() :: %{required(hook_event()) => [ClaudeAgentSDK.Hooks.Matcher.t()]}

Hook configuration map.

Maps hook events to lists of matchers.

Example

%{
  pre_tool_use: [
    %Matcher{matcher: "Bash", hooks: [&check_bash/3]},
    %Matcher{matcher: "Write|Edit", hooks: [&check_files/3]}
  ],
  post_tool_use: [
    %Matcher{matcher: "*", hooks: [&log_usage/3]}
  ]
}

hook_context()

@type hook_context() :: %{
  optional(:signal) => ClaudeAgentSDK.AbortSignal.t(),
  optional(atom()) => term()
}

Context information passed to hook callbacks.

Currently contains:

signal - Optional abort signal reference for cooperative cancellation

Note: Can be an empty map initially.

hook_event()

@type hook_event() ::
  :pre_tool_use
  | :post_tool_use
  | :post_tool_use_failure
  | :user_prompt_submit
  | :stop
  | :subagent_start
  | :subagent_stop
  | :pre_compact
  | :notification
  | :permission_request
  | :session_start
  | :session_end

Hook event types supported by the SDK.

hook_input()

@type hook_input() :: %{
  :hook_event_name => String.t(),
  :session_id => String.t(),
  :transcript_path => String.t(),
  :cwd => String.t(),
  optional(:tool_name) => String.t(),
  optional(:tool_input) => map(),
  optional(:tool_response) => term(),
  optional(:tool_use_id) => String.t(),
  optional(:agent_id) => String.t(),
  optional(:agent_transcript_path) => String.t(),
  optional(:agent_type) => String.t(),
  optional(:error) => String.t(),
  optional(:is_interrupt) => boolean(),
  optional(:message) => String.t(),
  optional(:title) => String.t(),
  optional(:notification_type) => String.t(),
  optional(:permission_suggestions) => [map()],
  optional(:permission_mode) => String.t(),
  optional(:source) => String.t(),
  optional(:reason) => String.t(),
  optional(:prompt) => String.t(),
  optional(:trigger) => String.t(),
  optional(:custom_instructions) => String.t(),
  optional(:stop_hook_active) => boolean(),
  optional(atom()) => term()
}

Input data passed to hook callbacks.

The structure varies by hook event. Common fields:

hook_event_name - String name of the event
session_id - Session identifier
transcript_path - Path to conversation transcript
cwd - Current working directory

Event-specific fields:

PreToolUse/PostToolUse/PostToolUseFailure/PermissionRequest: tool_name, tool_input
PostToolUse: tool_response
PostToolUseFailure: error, is_interrupt
UserPromptSubmit: prompt
Stop/SubagentStop: stop_hook_active
SubagentStart/SubagentStop: agent_id, agent_type, agent_transcript_path
Notification: message, title, notification_type
PermissionRequest: permission_suggestions, permission_mode
SessionStart: source
SessionEnd: reason
PreCompact: trigger, custom_instructions

hook_output()

@type hook_output() :: ClaudeAgentSDK.Hooks.Output.t() | term()

Hook callback function signature.

Receives:

Input data (varies by event)
Tool use ID (for tool-related hooks, nil otherwise)
Context with abort signal

Returns:

Hook output map controlling behavior (see Output)

Functions

all_valid_events()

@spec all_valid_events() :: [hook_event()]

Returns all valid hook event atoms.

Examples

iex> events = ClaudeAgentSDK.Hooks.all_valid_events()
iex> :pre_tool_use in events
true
iex> length(events)
12

event_to_string(atom)

@spec event_to_string(hook_event()) :: String.t()

Converts an Elixir hook event atom to CLI string format.

Examples

iex> ClaudeAgentSDK.Hooks.event_to_string(:pre_tool_use)
"PreToolUse"

iex> ClaudeAgentSDK.Hooks.event_to_string(:post_tool_use)
"PostToolUse"

string_to_event(arg1)

@spec string_to_event(String.t()) :: hook_event() | nil

Converts a CLI hook event string to Elixir atom.

Returns nil for unknown event strings.

Examples

iex> ClaudeAgentSDK.Hooks.string_to_event("PreToolUse")
:pre_tool_use

iex> ClaudeAgentSDK.Hooks.string_to_event("UnknownEvent")
nil

validate_config(config)

@spec validate_config(hook_config()) :: :ok | {:error, String.t()}

Validates a hook configuration.

Returns :ok if valid, {:error, reason} otherwise.

Examples

iex> matcher = %ClaudeAgentSDK.Hooks.Matcher{
...>   matcher: "Bash",
...>   hooks: [fn _, _, _ -> %{} end]
...> }
iex> ClaudeAgentSDK.Hooks.validate_config(%{pre_tool_use: [matcher]})
:ok

iex> ClaudeAgentSDK.Hooks.validate_config(%{invalid_event: []})
{:error, "Invalid hook event: invalid_event"}