/ 
Acme-Claude-Shell-0.03
/ Acme::Claude::Shell::Tools

NAME

Acme::Claude::Shell::Tools - SDK MCP tool definitions for Acme::Claude::Shell

SYNOPSIS

use Acme::Claude::Shell::Tools qw(shell_tools);

my $tools = shell_tools($session);

DESCRIPTION

Defines the SDK MCP tools that Claude can use to interact with the shell. Each tool returns a Future for async execution.

Tools

  • execute_command - Run shell commands (with user confirmation)

    Executes arbitrary shell commands. The user is prompted to approve, edit, dry-run, or cancel each command before execution. Dangerous commands (rm -rf, sudo, mkfs, etc.) trigger additional warnings.

  • read_file - Read file contents (safe, no confirmation)

    Read file contents directly without shell commands. Supports lines parameter to read first N lines, and tail parameter to read last N lines.

  • list_directory - List directory contents (safe, no confirmation)

    List directory contents with optional glob pattern filtering, long_format for detailed output, and show_hidden for dotfiles.

  • search_files - Search for files by pattern (safe, no confirmation)

    Search recursively by filename pattern (glob) or file content (grep). Supports max_depth limit. Results capped at 100 matches.

  • get_system_info - Get system information (safe, no confirmation)

    Returns OS, disk, memory, and process information. Use info_type to filter: 'all', 'os', 'disk', 'memory', or 'processes'.

  • get_working_directory - Get current working directory (safe)

    Returns the current working directory path.

Command Approval

The execute_command tool handles user approval directly (not via hooks) to ensure synchronous confirmation before execution. Users can:

  • [a] Approve and run the command

  • [d] Dry-run (preview only, don't execute)

  • [e] Edit the command before running

  • [x] Cancel

Dangerous Command Detection

The following patterns trigger additional safety warnings:

  • rm -rf, rm --recursive, rm --force

  • sudo commands

  • mkfs, dd of=, device writes

  • chmod 777, chown -R

  • kill -9, reboot, shutdown, halt, poweroff

  • Fork bombs, remote script piping (curl/wget | sh)

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)