/ 
Claude-Agent-0.15
/ Claude::Agent::Hook::Matcher

NAME

Claude::Agent::Hook::Matcher - Which tools a set of hook callbacks applies to

SYNOPSIS

use Claude::Agent::Hook::Matcher;

my $matcher = Claude::Agent::Hook::Matcher->new(
    matcher => 'Bash',
    hooks   => [sub { ... }, sub { ... }],
    timeout => 30,
);

my $any = Claude::Agent::Hook::Matcher->new(
    hooks => [sub { ... }],
);

DESCRIPTION

A matcher groups callbacks with the pattern the CLI uses to decide which tool uses they fire for. The pattern is sent to the CLI with the initialize request and the CLI does the matching; matches mirrors that matching for code that wants to test a matcher locally.

ATTRIBUTES

matcher

A tool name, or a regular expression matched against it, such as Write|Edit or mcp__.*. Unset matches every tool. For events that are not about tools the matcher is ignored.

hooks

ArrayRef of callbacks. Each is registered with the CLI separately and the CLI runs them in order.

timeout

Seconds the CLI allows each callback. Unset leaves the CLI's default.

METHODS

new

Takes a flat list of name/value pairs. Unknown names are ignored.

matches

if ($matcher->matches('Bash')) { ... }

True when the pattern matches the tool name, the way the CLI decides it: a pattern with no regular expression metacharacter is an exact match, so shell-tools__ matches nothing and mcp__shell-tools__.* is needed; anything else is a regular expression, run with a one second alarm and refused outright when it nests quantifiers.

AUTHOR

LNATION, <email at lnation.org>

LICENSE

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under The Artistic License 2.0 (GPL Compatible).