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

NAME

Claude::Agent::Hook::Result - Build hook callback results

SYNOPSIS

use Claude::Agent::Hook::Result;

return Claude::Agent::Hook::Result->proceed;

return Claude::Agent::Hook::Result->allow(
    updated_input => { command => 'safe command' },
    reason        => 'Modified for safety',
);

return Claude::Agent::Hook::Result->deny(
    reason => 'Operation not permitted',
);

return Claude::Agent::Hook::Result->merge(
    Claude::Agent::Hook::Result->add_context('The build is red.', event => 'UserPromptSubmit'),
    Claude::Agent::Hook::Result->system_message('Context added'),
);

DESCRIPTION

Every method returns a plain hashref in the shape the CLI reads from a hook, so a callback can also build the hash by hand. The permission methods write hookSpecificOutput for the event named by event, which defaults to PreToolUse.

CLASS METHODS

proceed

An empty hash: the event continues as it would without the hook.

allow

allow(reason => $text, updated_input => \%input, event => 'PreToolUse')

Let the tool run, bypassing the permission system, optionally with new input.

deny

deny(reason => $text, event => 'PreToolUse')

Stop the tool. The reason is shown to the model.

ask

ask(reason => $text)

Make the CLI ask for permission as if no rule matched.

defer

defer(reason => $text)

Let the CLI exit and resume later for a decision that takes a long time.

block

block(reason => $text)

{ decision => 'block', reason => $text }: for Stop, SubagentStop, UserPromptSubmit and PostToolUse, where it blocks the stop, the prompt, or feeds the reason back to the model.

stop

stop(reason => $text)

{ continue => false, stopReason => $text }: end the turn now.

add_context

add_context($text, event => 'UserPromptSubmit')

Add text to the model's context for this event.

update_tool_output

update_tool_output($output, event => 'PostToolUse')

Replace what the model sees as the tool's output.

system_message

system_message($text)

Show a message to the person.

suppress_output

Hide the hook's output from the transcript.

async

async(timeout => $seconds)

Tell the CLI the hook keeps running in the background.

merge

merge(@results)

Combine several results into one hash; later keys win and hookSpecificOutput hashes are merged key by key.

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