NAME

Acme::Claude::Shell::Hooks - Safety hooks for Acme::Claude::Shell

SYNOPSIS

use Acme::Claude::Shell::Hooks qw(safety_hooks);

my $hooks = safety_hooks($session);

DESCRIPTION

Provides hooks for Acme::Claude::Shell. These hooks integrate with the Claude::Agent SDK hook system to provide logging, statistics, and error handling.

Note: Command approval is handled directly in the tool handler (Tools.pm) to ensure it happens synchronously before execution.

Hooks

• PreToolUse - Audit logging of tool calls

  Triggered before any shell-tools MCP tool executes. Logs tool usage in verbose mode and tracks calls in an audit log if $session->{audit_log} is enabled.

• PostToolUse - Stop spinner after command execution

  Triggered after execute_command completes successfully. Stops the execution spinner and increments the tool usage counter.

• PostToolUseFailure - Handle tool failures gracefully

  Triggered when any shell-tools MCP tool fails. Displays a user-friendly error message and tracks error count for session statistics.

• Stop - Show session statistics when agent stops

  Triggered when the agent stops (end of session). Displays:

  • Session duration

  • Number of tools used

  • Number of tool errors (if any)

  • Commands in history

• Notification - Log important events

  Triggered for SDK notifications. Logs notification types in verbose mode.

Session Options

The following session attributes affect hook behavior:

• verbose - Enable verbose logging of tool calls and notifications

• audit_log - Enable detailed audit logging to $session->{_audit_log}

• colorful - Use colored output (default: auto-detect TTY)

AUTHOR

LNATION, <email at lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)