view release on metacpan or  search on metacpan

lib/Claude/Agent/Hook/Matcher.pm  view on Meta::CPAN

package Claude::Agent::Hook::Matcher;

use 5.020;
use strict;
use warnings;

use Claude::Agent::Logger '$log';
use Scalar::Util qw(blessed);
use Try::Tiny;
use Future;
use Types::Common -types;
use Marlin
    'matcher',                    # Regex pattern for tool names (optional)
    'hooks'   => sub { [] },      # ArrayRef of coderefs
    'timeout' => sub { 60 };      # Timeout in seconds

=head1 NAME

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

=head1 DESCRIPTION

Defines a hook matcher that triggers callbacks for specific tools.

=head2 ATTRIBUTES

=over 4

=item * matcher - Optional regex pattern to match tool names

=item * hooks - ArrayRef of callback coderefs

=item * timeout - Timeout in seconds (default: 60)

=back

=head2 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',
            });
        });
    }

=head2 METHODS

=head3 matches

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