/ 
Claude-Agent-0.13
/ Claude::Agent::Hook::Executor

NAME

Claude::Agent::Hook::Executor - Executes Perl hooks for Claude Agent SDK

SYNOPSIS

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

my $executor = Claude::Agent::Hook::Executor->new(
    hooks => {
        PreToolUse => [
            Claude::Agent::Hook::Matcher->new(
                matcher => 'Bash',
                hooks   => [sub {
                    my ($input, $tool_use_id, $context) = @_;
                    if ($input->{tool_input}{command} =~ /rm -rf/) {
                        return Claude::Agent::Hook::Result->deny(
                            reason => 'Dangerous command blocked',
                        );
                    }
                    return Claude::Agent::Hook::Result->proceed();
                }],
            ),
        ],
    },
    session_id => $session_id,
);

# Execute pre-tool-use hooks
my $result = $executor->run_pre_tool_use($tool_name, $tool_input, $tool_use_id);

if ($result->{decision} eq 'deny') {
    # Block the tool
}

DESCRIPTION

This module executes Perl hook callbacks when tool use events occur. It intercepts tool calls in the Query layer and runs matching hooks.

ATTRIBUTES

hooks

HashRef of hook event names to arrayrefs of Claude::Agent::Hook::Matcher objects.

session_id

Current session ID (set after init message).

cwd

Current working directory.

loop

Optional IO::Async::Loop for async hook execution.

METHODS

run_pre_tool_use

my $future = $executor->run_pre_tool_use($tool_name, $tool_input, $tool_use_id);

Execute PreToolUse hooks for a tool call. Returns a Future that resolves to a hashref with:

{
    decision      => 'continue' | 'allow' | 'deny',
    reason        => 'optional reason',
    updated_input => { ... },  # for 'allow' decision
}

run_post_tool_use

my $result = $executor->run_post_tool_use($tool_name, $tool_input, $tool_use_id, $tool_result);

Execute PostToolUse hooks after a tool completes successfully.

run_post_tool_use_failure

my $result = $executor->run_post_tool_use_failure($tool_name, $tool_input, $tool_use_id, $error);

Execute PostToolUseFailure hooks after a tool fails.

run_notification

my $future = $executor->run_notification($notification_type, $data);

Execute Notification hooks. Returns a Future.

run_stop

my $future = $executor->run_stop($reason);

Execute Stop hooks when the agent stops. Returns a Future.

has_hooks_for

if ($executor->has_hooks_for('PreToolUse')) { ... }

Returns true if there are hooks registered for the given event.

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