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

NAME

Claude::Agent::Hook - Hook system for Claude Agent SDK

SYNOPSIS

use Claude::Agent::Hook qw(:events);
use Claude::Agent::Options;

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

DESCRIPTION

Hooks are Perl callbacks the CLI runs at points in its own loop. They are registered with the CLI when a query starts, the CLI decides when each matcher applies, and it calls back over the SDK control channel with the same input a hook command would read on standard input. A hook can let the event proceed, change a tool's input, allow or deny a tool, add context, or stop the turn.

CALLBACKS

sub {
    my ($input, $tool_use_id, $context) = @_;
    ...
    return Claude::Agent::Hook::Result->proceed;
}

$input is the CLI's hook input: hook_event_name, session_id, transcript_path, cwd, permission_mode, and for tool events tool_name, tool_input and tool_use_id, plus event-specific keys such as prompt (UserPromptSubmit) or tool_response (PostToolUse). $tool_use_id is the tool use the event concerns, or undef. $context is a Claude::Agent::Hook::Context, which also carries the event loop and the query.

The callback returns a hashref in the CLI's hook output shape, most easily built with Claude::Agent::Hook::Result, or a Future that resolves to one. A hashref of the 0.13 shape (decision of continue, allow or deny) is translated with a warning. A callback that dies or whose Future fails is reported to the CLI as a hook error.

EVENTS

Each constant is exported on request, or all of them with the :events tag; @EVENTS lists them.

  • PreToolUse - before a tool runs; may allow, deny, ask or change the input

  • PostToolUse - after a tool succeeds; may add context or replace the output

  • PostToolUseFailure - after a tool fails

  • Notification - the CLI wants to tell the person something

  • UserPromptSubmit - a prompt was submitted; may block it or add context

  • SessionStart, SessionEnd, Setup

  • Stop, StopFailure - the model stopped; may block the stop

  • SubagentStart, SubagentStop

  • PreCompact, PostCompact

  • PermissionRequest, PermissionDenied

  • ConfigChange, InstructionsLoaded, CwdChanged, FileChanged

  • WorktreeCreate, WorktreeRemove

  • Elicitation, ElicitationResult

  • TaskCompleted, TeammateIdle

CLASSES

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