ClaudeAgentSDK.Hooks.Matcher (claude_agent_sdk v0.5.3)

View Source

Hook matcher configuration.

Defines which hooks should run for which tool patterns. Matchers support:

  • Exact matching: "Bash" matches only the Bash tool
  • Regex patterns: "Write|Edit" matches Write or Edit tools
  • Wildcard: "*" or nil matches all tools
  • Multiple hooks: Each matcher can have multiple callback functions

Examples

# Match specific tool
Matcher.new("Bash", [&MyModule.check_bash/3])

# Match multiple tools with regex
Matcher.new("Write|Edit", [&check_file_edit/3])

# Match all tools
Matcher.new("*", [&log_all_tools/3])
Matcher.new(nil, [&log_all_tools/3])

# Multiple hooks for same pattern
Matcher.new("Bash", [&security_check/3, &audit_log/3])

Summary

Types

t()

Hook matcher struct.

Functions

new(matcher, hooks)

Creates a new hook matcher.

to_cli_format(matcher, callback_id_fn)

Converts matcher to CLI format for initialization.

Types

t()

@type t() :: %ClaudeAgentSDK.Hooks.Matcher{
  hooks: [ClaudeAgentSDK.Hooks.hook_callback()],
  matcher: String.t() | nil
}

Hook matcher struct.

Fields:

  • matcher - Tool name pattern (nil, "*", "ToolName", or regex like "Tool1|Tool2")
  • hooks - List of callback functions to invoke when pattern matches

Functions

new(matcher, hooks)

@spec new(String.t() | nil, [ClaudeAgentSDK.Hooks.hook_callback()]) :: t()

Creates a new hook matcher.

Parameters

  • matcher - Tool name pattern. Can be:
    • nil - Matches all tools
    • "*" - Matches all tools
    • "ToolName" - Matches specific tool exactly
    • "Tool1|Tool2" - Regex pattern matching multiple tools
  • hooks - List of callback functions (each with signature (input, tool_use_id, context) -> output)

Examples

# Match Bash tool only
Matcher.new("Bash", [&check_bash/3])

# Match Write or Edit tools
Matcher.new("Write|Edit", [&check_file_edit/3])

# Match all tools
Matcher.new(nil, [&log_all_tools/3])

# Multiple hooks for same pattern
Matcher.new("Bash", [&security_check/3, &audit_log/3])

to_cli_format(matcher, callback_id_fn)

@spec to_cli_format(t(), (ClaudeAgentSDK.Hooks.hook_callback() -> String.t())) ::
  map()

Converts matcher to CLI format for initialization.

The callback_id_fn function is called for each hook to get its unique ID from the registry.

Parameters

  • matcher - The matcher struct
  • callback_id_fn - Function that takes a callback and returns its ID string

Returns

Map with CLI-compatible format:

  • "matcher" - Tool pattern string or nil
  • "hookCallbackIds" - List of callback ID strings

Examples

matcher = Matcher.new("Bash", [&check_bash/3])
id_fn = fn callback -> Registry.get_id(registry, callback) end

Matcher.to_cli_format(matcher, id_fn)
# => %{"matcher" => "Bash", "hookCallbackIds" => ["hook_0"]}