/ 
Claude-Agent-0.10
/ 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

Hooks receive input data, tool use ID, context, and an optional IO::Async::Loop. They can return either a hashref (synchronous) or a Future (asynchronous).

# Synchronous hook (backward compatible)
sub callback {
    my ($input_data, $tool_use_id, $context, $loop) = @_;

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

    # $loop is the IO::Async::Loop (optional, may be undef)

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

# Asynchronous hook (returns Future)
sub async_callback {
    my ($input_data, $tool_use_id, $context, $loop) = @_;

    # Use loop for async operations (e.g., HTTP requests)
    return $loop->delay_future(after => 0.1)->then(sub {
        # Perform async validation...
        return Future->done({
            decision => 'allow',
        });
    });
}

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), a post-execution time check is performed, but this cannot interrupt a regex that hangs indefinitely - it only detects slow patterns after completion. 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. For security-critical applications, especially on Windows, consider using re::engine::PCRE2 or Regexp::Timeout for proper cross-platform timeout support, or use pre-validated patterns only.

run_hooks

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

Run all hooks and return a Future that resolves to an arrayref of results. Hooks may return either a hashref (synchronous) or a Future (asynchronous).

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