/ 
Claude-Agent-0.05
/ Claude::Agent::Hook::Matcher

NAME

Claude::Agent::Hook::Matcher - Hook matcher for Claude Agent SDK

DESCRIPTION

Defines a hook matcher that triggers callbacks for specific tools.

ATTRIBUTES

  • matcher - Optional regex pattern to match tool names

  • hooks - ArrayRef of callback coderefs

  • timeout - Timeout in seconds (default: 60)

CALLBACK SIGNATURE

sub callback {
    my ($input_data, $tool_use_id, $context) = @_;

    # $input_data contains:
    # - tool_name: Name of the tool
    # - tool_input: Input parameters for the tool

    # $context contains:
    # - session_id: Current session ID
    # - cwd: Current working directory

    # Return hashref with decision:
    return {
        decision => 'continue',  # or 'allow', 'deny'
        reason   => 'Optional reason',
        # For 'allow', can include:
        updated_input => { ... },
    };
}

METHODS

matches

my $bool = $matcher->matches($tool_name);

Check if this matcher matches the given tool name.

IMPORTANT - Platform Limitation: Regex timeout protection uses alarm() which only works on Unix-like systems. On Windows (MSWin32, cygwin), malicious regex patterns will NOT be interrupted and could cause the process to hang indefinitely. Pattern length is limited to 1000 characters and basic nested quantifier detection is performed to provide additional ReDoS protection, but sophisticated ReDoS attacks with shorter patterns may still be possible. Consider using pre-validated patterns or a regex library with built-in timeout support (e.g., re::engine::PCRE2) for security-critical applications on Windows.

run_hooks

my $results = $matcher->run_hooks($input_data, $tool_use_id, $context);

Run all hooks and return their results.

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).