view release on metacpan or  search on metacpan

lib/Acme/Claude/Shell/Tools.pm  view on Meta::CPAN

use IO::Async::Process;
use Future;
use Cwd qw(abs_path getcwd);
use File::Spec;
use Term::ANSIColor qw(colored);

=head1 NAME

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

=head1 SYNOPSIS

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

    my $tools = shell_tools($session);

=head1 DESCRIPTION

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

=head2 Tools

=over 4

=item * B<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.

=item * B<read_file> - Read file contents (safe, no confirmation)

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

=item * B<list_directory> - List directory contents (safe, no confirmation)

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

=item * B<search_files> - Search for files by pattern (safe, no confirmation)

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

=item * B<get_system_info> - Get system information (safe, no confirmation)

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

=item * B<get_working_directory> - Get current working directory (safe)

Returns the current working directory path.

=back

=head2 Command Approval

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

=over 4

=item * B<[a]> Approve and run the command

=item * B<[d]> Dry-run (preview only, don't execute)

=item * B<[e]> Edit the command before running

=item * B<[x]> Cancel

=back

=head2 Dangerous Command Detection

The following patterns trigger additional safety warnings:

=over 4

=item * C<rm -rf>, C<rm --recursive>, C<rm --force>

=item * C<sudo> commands

=item * C<mkfs>, C<dd of=>, device writes

=item * C<chmod 777>, C<chown -R>

=item * C<kill -9>, C<reboot>, C<shutdown>, C<halt>, C<poweroff>

=item * Fork bombs, remote script piping (curl/wget | sh)

=back

=cut

sub shell_tools {
    my ($session) = @_;

    return [
        # execute_command tool - ALL shell operations go through this
        # so the PreToolUse hook can confirm each command
        tool(
            'execute_command',
            'Execute a shell command and return its output. Use this for ALL shell operations including listing files, reading files, etc. The user will be prompted to approve each command.',
            {
                type       => 'object',
                properties => {
                    command => {
                        type        => 'string',
                        description => 'The shell command to execute (e.g., "ls -la", "cat file.txt", "find . -name *.pl")',
                    },
                    working_dir => {
                        type        => 'string',
                        description => 'Directory to run command in (optional, defaults to current directory)',
                    },
                },
                required => ['command'],
            },
            sub {
                my ($params, $loop) = @_;