# `ClaudeAgentSDK.Hooks.Matcher`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.15.0/lib/claude_agent_sdk/hooks/matcher.ex#L1)

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
- **Per-matcher timeout**: Optional `timeout_ms` (default 60s, floored to 1s) for callback execution (serialized to seconds for the CLI)

## 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])

# `t`

```elixir
@type t() :: %ClaudeAgentSDK.Hooks.Matcher{
  hooks: [ClaudeAgentSDK.Hooks.hook_callback()],
  matcher: String.t() | nil,
  timeout_ms: pos_integer() | 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
- `timeout_ms` - Optional timeout (ms) applied to callbacks matched by this matcher (sent as seconds to the CLI)

# `new`

```elixir
@spec new(String.t() | nil, [ClaudeAgentSDK.Hooks.hook_callback()], keyword()) :: 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`)
- `opts` - Optional keyword list
  - `:timeout_ms` - Timeout in milliseconds for callbacks matched by this matcher (serialized to seconds for CLI initialization)

## 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`

```elixir
@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
- `"timeout"` - Optional timeout in seconds

## 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"]}

---

*Consult [api-reference.md](api-reference.md) for complete listing*