protoagent 0.0.3 → 0.0.4

package/dist/tools/run-shell-command.js

@@ -1,8 +1,76 @@
 import { spawn } from 'child_process';
-import inquirer from 'inquirer';
 import { logger } from '../utils/logger.js';
+import { UserCancellationError } from '../utils/user-cancellation.js';
+import { enhancedPrompt } from '../utils/enhanced-prompt.js';
+import path from 'path';
+import fs from 'fs';
 // Current working directory for file operations
 const workingDirectory = process.cwd();
+/**
+ * Parse compound shell commands and extract directory changes
+ * Handles patterns like: cd directory && command args
+ */
+function parseCompoundCommand(command, args) {
+    // Join command and args to analyze the full command string
+    const fullCommand = args.length > 0 ? `${command} ${args.join(' ')}` : command;
+    // Check for cd && pattern
+    const cdPattern = /^cd\s+([^&]+)\s*&&\s*(.+)$/;
+    const match = fullCommand.match(cdPattern);
+    if (match) {
+        const directory = match[1].trim();
+        const remainingCommand = match[2].trim();
+        // Parse the remaining command into command and args
+        const parts = remainingCommand.split(/\s+/);
+        const actualCommand = parts[0];
+        const actualArgs = parts.slice(1);
+        logger.debug('🔄 Parsed compound command', {
+            component: 'ShellCommand',
+            original: fullCommand,
+            extractedDirectory: directory,
+            extractedCommand: actualCommand,
+            extractedArgs: actualArgs
+        });
+        return {
+            directory,
+            actualCommand,
+            actualArgs
+        };
+    }
+    // No compound command detected, return as-is
+    return {
+        actualCommand: command,
+        actualArgs: args
+    };
+}
+/**
+ * Validate and resolve a subdirectory path safely
+ * Ensures the directory is within the working directory
+ */
+async function validateAndResolveDirectory(requestedDir) {
+    if (!requestedDir) {
+        return workingDirectory;
+    }
+    // Resolve the path relative to working directory
+    const resolvedPath = path.resolve(workingDirectory, requestedDir);
+    // Ensure the resolved path is within the working directory
+    if (!resolvedPath.startsWith(workingDirectory)) {
+        throw new Error(`Directory access denied - path outside working directory: ${requestedDir}`);
+    }
+    // Check if directory exists
+    try {
+        const stats = await fs.promises.stat(resolvedPath);
+        if (!stats.isDirectory()) {
+            throw new Error(`Path is not a directory: ${requestedDir}`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Directory does not exist: ${requestedDir}`);
+        }
+        throw error;
+    }
+    return resolvedPath;
+}
 // Global flags and session state
 let globalConfig = null;
 let dangerouslyAcceptAll = false;
@@ -15,18 +83,346 @@ const SAFE_COMMANDS = [
     'npm list', 'npm ls', 'yarn list', 'node --version', 'npm --version',
     'python --version', 'python3 --version', 'which', 'type', 'file'
 ];
+/**
+ * Detect if a command is likely to be interactive
+ */
+function isInteractiveCommand(commandString) {
+    const cmd = commandString.toLowerCase();
+    // Commands that are commonly interactive
+    const interactivePatterns = [
+        /npm create/,
+        /npm init(?!\s+\-y)/, // npm init without -y flag
+        /yarn create/,
+        /yarn init(?!\s+\-y)/,
+        /git commit(?!.*\-m)/, // git commit without -m flag
+        /git rebase\s+\-i/,
+        /git add\s+\-p/,
+        /npx create\-/,
+        /vue create/,
+        /ng new/,
+        /rails new/,
+        /django\-admin startproject/,
+        /composer create\-project/,
+        /cargo new/,
+        /dotnet new/
+    ];
+    return interactivePatterns.some(pattern => pattern.test(cmd));
+}
+/**
+ * Run an interactive command with direct terminal access
+ */
+async function runInteractiveCommand(command, args = [], executionDirectory) {
+    logger.consoleLog(`\n🎯 Running interactive command...`);
+    logger.consoleLog(`📁 Directory: ${executionDirectory}`);
+    logger.consoleLog(`🖥️  Command: ${command} ${args.join(' ')}`);
+    logger.consoleLog(`\n💡 You can interact with this command directly. Press Ctrl+C if needed.\n`);
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: executionDirectory,
+            stdio: 'inherit', // Allow direct interaction with terminal
+            shell: true,
+            env: { ...process.env, PATH: process.env.PATH }
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                logger.consoleLog(`\n✅ Interactive command completed successfully (exit code: ${code})`);
+                resolve(`Interactive command executed successfully (exit code: ${code})\n\nCommand: ${command} ${args.join(' ')}\nDirectory: ${executionDirectory}`);
+            }
+            else {
+                logger.consoleLog(`\n⚠️  Interactive command exited with code ${code}`);
+                resolve(`Interactive command exited with code ${code}\n\nCommand: ${command} ${args.join(' ')}\nDirectory: ${executionDirectory}\n\nNote: Non-zero exit codes don't always indicate errors for interactive commands.`);
+            }
+        });
+        child.on('error', (error) => {
+            logger.consoleLog(`\n❌ Interactive command failed: ${error.message}`);
+            reject(new Error(`Failed to execute interactive command: ${error.message}`));
+        });
+    });
+}
+/**
+ * Show detailed preview of what a shell command will do
+ */
+async function showShellCommandPreview(commandString, directory) {
+    logger.consoleLog(`\n🔐 Shell Command Preview`);
+    logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+    logger.consoleLog(`🖥️  Command: ${commandString}`);
+    logger.consoleLog(`📁 Working Directory: ${directory}`);
+    // Show relative path for better readability
+    const relativePath = path.relative(workingDirectory, directory);
+    if (relativePath && relativePath !== '.') {
+        logger.consoleLog(`📂 Subdirectory: ${relativePath}`);
+    }
+    // Analyze the command and show what it will do
+    const analysis = analyzeShellCommand(commandString);
+    // Show risk assessment
+    const riskColor = analysis.riskLevel === 'LOW' ? '🟢' : analysis.riskLevel === 'MEDIUM' ? '🟡' : '🔴';
+    logger.consoleLog(`${riskColor} Risk Level: ${analysis.riskLevel} - ${analysis.riskReason}`);
+    logger.consoleLog(`\n📋 Command Analysis:`);
+    logger.consoleLog(`   • Purpose: ${analysis.purpose}`);
+    logger.consoleLog(`   • Expected output: ${analysis.expectedOutput}`);
+    logger.consoleLog(`   • Side effects: ${analysis.sideEffects}`);
+    if (analysis.fileSystemChanges.length > 0) {
+        logger.consoleLog(`\n📁 Potential file system changes:`);
+        analysis.fileSystemChanges.forEach(change => {
+            logger.consoleLog(`   • ${change}`);
+        });
+    }
+    if (analysis.networkActivity) {
+        logger.consoleLog(`\n🌐 Network activity: ${analysis.networkActivity}`);
+    }
+    if (analysis.warnings.length > 0) {
+        logger.consoleLog(`\n⚠️  Warnings:`);
+        analysis.warnings.forEach(warning => {
+            logger.consoleLog(`   • ${warning}`);
+        });
+    }
+    if (analysis.suggestions.length > 0) {
+        logger.consoleLog(`\n💡 Suggestions:`);
+        analysis.suggestions.forEach(suggestion => {
+            logger.consoleLog(`   • ${suggestion}`);
+        });
+    }
+    logger.consoleLog(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+}
+/**
+ * Analyze a shell command to understand what it will do
+ */
+function analyzeShellCommand(commandString) {
+    const cmd = commandString.toLowerCase();
+    const parts = commandString.split(' ');
+    const baseCommand = parts[0].toLowerCase();
+    // Initialize analysis result
+    let analysis = {
+        riskLevel: 'LOW',
+        riskReason: 'Standard read-only operation',
+        purpose: 'Unknown command',
+        expectedOutput: 'Command output',
+        sideEffects: 'None',
+        fileSystemChanges: [],
+        networkActivity: undefined,
+        warnings: [],
+        suggestions: []
+    };
+    // Check if this is an interactive command
+    if (isInteractiveCommand(commandString)) {
+        analysis.warnings.push('This is an interactive command - you will be able to interact directly with it');
+        analysis.suggestions.push('The command will run with direct terminal access for interaction');
+        analysis.expectedOutput = 'Interactive session with prompts';
+    }
+    // Analyze based on command type
+    switch (baseCommand) {
+        case 'ls':
+        case 'dir':
+            analysis.purpose = 'List directory contents';
+            analysis.expectedOutput = 'File and folder names with details';
+            break;
+        case 'find':
+            analysis.purpose = 'Search for files and directories';
+            analysis.expectedOutput = 'Paths matching search criteria';
+            if (cmd.includes('-exec') || cmd.includes('-delete')) {
+                analysis.riskLevel = 'HIGH';
+                analysis.riskReason = 'Find command with execution or deletion flags';
+                analysis.sideEffects = 'May modify or delete files';
+            }
+            break;
+        case 'grep':
+            analysis.purpose = 'Search text within files';
+            analysis.expectedOutput = 'Matching lines with context';
+            break;
+        case 'cat':
+        case 'head':
+        case 'tail':
+            analysis.purpose = 'Display file contents';
+            analysis.expectedOutput = 'File content';
+            break;
+        case 'git':
+            const gitSubcommand = parts[1]?.toLowerCase();
+            switch (gitSubcommand) {
+                case 'status':
+                case 'log':
+                case 'diff':
+                case 'show':
+                case 'branch':
+                    analysis.purpose = `Show git ${gitSubcommand} information`;
+                    analysis.expectedOutput = `Git ${gitSubcommand} output`;
+                    break;
+                case 'add':
+                    analysis.purpose = 'Stage files for commit';
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Modifies git index';
+                    analysis.sideEffects = 'Stages files for next commit';
+                    break;
+                case 'commit':
+                    analysis.purpose = 'Create a new commit';
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Creates permanent git history';
+                    analysis.sideEffects = 'Adds commit to repository history';
+                    if (!cmd.includes('-m')) {
+                        analysis.warnings.push('Missing commit message - will open interactive editor');
+                        analysis.suggestions.push('Add -m "message" to avoid interactive mode');
+                    }
+                    break;
+                case 'push':
+                case 'pull':
+                case 'fetch':
+                    analysis.purpose = `Synchronize with remote repository (${gitSubcommand})`;
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Network operation affecting repository';
+                    analysis.networkActivity = `Git ${gitSubcommand} to remote repository`;
+                    analysis.sideEffects = 'May update local or remote repository';
+                    break;
+                default:
+                    analysis.purpose = `Execute git ${gitSubcommand} command`;
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Git operation with unknown effects';
+            }
+            break;
+        case 'npm':
+        case 'yarn':
+            const packageSubcommand = parts[1]?.toLowerCase();
+            switch (packageSubcommand) {
+                case 'install':
+                case 'i':
+                    analysis.purpose = 'Install package dependencies';
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Downloads and installs packages from internet';
+                    analysis.networkActivity = 'Downloads packages from npm registry';
+                    analysis.fileSystemChanges = ['Creates/updates node_modules/', 'Updates package-lock.json'];
+                    analysis.sideEffects = 'Installs dependencies and updates lock file';
+                    break;
+                case 'create':
+                    analysis.purpose = 'Create new project from template';
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Creates new project structure';
+                    analysis.networkActivity = 'Downloads project template';
+                    analysis.fileSystemChanges = ['Creates new project directory', 'Installs dependencies'];
+                    analysis.expectedOutput = 'Interactive prompts for project configuration';
+                    analysis.sideEffects = 'Creates project files and installs dependencies interactively';
+                    if (!cmd.includes('--template')) {
+                        analysis.warnings.push('Interactive command - you will be prompted to choose template and options');
+                        analysis.suggestions.push('You can answer prompts directly in the terminal');
+                    }
+                    else {
+                        analysis.suggestions.push('Template specified - fewer interactive prompts expected');
+                    }
+                    break;
+                case 'run':
+                case 'start':
+                case 'build':
+                case 'test':
+                    analysis.purpose = `Run ${packageSubcommand} script`;
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Executes custom scripts defined in package.json';
+                    analysis.sideEffects = 'Depends on script contents - may build, test, or start server';
+                    break;
+                default:
+                    analysis.purpose = `Execute ${baseCommand} ${packageSubcommand} command`;
+                    analysis.riskLevel = 'MEDIUM';
+                    analysis.riskReason = 'Package manager operation';
+            }
+            break;
+        case 'mkdir':
+            analysis.purpose = 'Create directories';
+            analysis.riskLevel = 'LOW';
+            analysis.fileSystemChanges = [`Creates directory: ${parts.slice(1).join(', ')}`];
+            analysis.sideEffects = 'Creates new directories';
+            break;
+        case 'rm':
+            analysis.purpose = 'Remove files and directories';
+            analysis.riskLevel = 'HIGH';
+            analysis.riskReason = 'Permanently deletes files';
+            analysis.sideEffects = 'PERMANENTLY DELETES FILES';
+            analysis.fileSystemChanges = [`Deletes: ${parts.slice(1).join(', ')}`];
+            analysis.warnings.push('DESTRUCTIVE OPERATION - files will be permanently deleted');
+            if (cmd.includes('-rf')) {
+                analysis.warnings.push('Recursive force delete - EXTREMELY DANGEROUS');
+            }
+            break;
+        case 'cp':
+        case 'copy':
+            analysis.purpose = 'Copy files or directories';
+            analysis.riskLevel = 'LOW';
+            analysis.sideEffects = 'Creates file copies';
+            analysis.fileSystemChanges = ['Creates copies of specified files'];
+            break;
+        case 'mv':
+        case 'move':
+            analysis.purpose = 'Move or rename files';
+            analysis.riskLevel = 'MEDIUM';
+            analysis.riskReason = 'Modifies file locations';
+            analysis.sideEffects = 'Moves or renames files';
+            analysis.fileSystemChanges = ['Moves/renames specified files'];
+            break;
+        case 'chmod':
+            analysis.purpose = 'Change file permissions';
+            analysis.riskLevel = 'MEDIUM';
+            analysis.riskReason = 'Modifies file security permissions';
+            analysis.sideEffects = 'Changes file permissions';
+            if (cmd.includes('777')) {
+                analysis.riskLevel = 'HIGH';
+                analysis.riskReason = 'Setting permissions to 777 (world-writable) is dangerous';
+                analysis.warnings.push('chmod 777 makes files writable by everyone - security risk');
+            }
+            break;
+        case 'curl':
+        case 'wget':
+            analysis.purpose = 'Download content from internet';
+            analysis.riskLevel = 'MEDIUM';
+            analysis.riskReason = 'Network operation downloading external content';
+            analysis.networkActivity = 'Downloads content from specified URL';
+            if (cmd.includes('-o') || cmd.includes('--output')) {
+                analysis.fileSystemChanges = ['Creates downloaded file'];
+            }
+            break;
+        case 'python':
+        case 'python3':
+        case 'node':
+            analysis.purpose = 'Execute script';
+            analysis.riskLevel = 'MEDIUM';
+            analysis.riskReason = 'Executes code with unknown effects';
+            analysis.sideEffects = 'Depends on script contents';
+            break;
+        default:
+            analysis.purpose = 'Execute command';
+            analysis.riskLevel = 'MEDIUM';
+            analysis.riskReason = 'Unknown command with unpredictable effects';
+            analysis.warnings.push('Unknown command - effects cannot be predicted');
+    }
+    // Check for dangerous patterns
+    if (cmd.includes('sudo')) {
+        analysis.riskLevel = 'HIGH';
+        analysis.riskReason = 'Requires elevated privileges';
+        analysis.warnings.push('Sudo command requires administrator privileges');
+    }
+    if (cmd.includes('rm -rf')) {
+        analysis.riskLevel = 'HIGH';
+        analysis.riskReason = 'Recursive force deletion';
+        analysis.warnings.push('DANGER: rm -rf can delete entire directory trees');
+    }
+    if (cmd.includes('format') || cmd.includes('mkfs') || cmd.includes('fdisk')) {
+        analysis.riskLevel = 'HIGH';
+        analysis.riskReason = 'Disk formatting/partitioning commands';
+        analysis.warnings.push('DANGER: Disk formatting commands can destroy data');
+    }
+    return analysis;
+}
 export function setShellConfig(config) {
     globalConfig = config;
 }
 export function setDangerouslyAcceptAll(accept) {
     dangerouslyAcceptAll = accept;
 }
-export async function runShellCommand(command, args = [], timeoutMs = 30000) {
-    return await runShellCommandWithRetry(command, args, timeoutMs, 0);
+export async function runShellCommand(command, args = [], timeoutMs = 30000, directory) {
+    // Parse compound commands like "cd directory && command"
+    const parsed = parseCompoundCommand(command, args);
+    const finalDirectory = parsed.directory || directory; // Parsed directory takes precedence
+    return await runShellCommandWithRetry(parsed.actualCommand, parsed.actualArgs, timeoutMs, 0, finalDirectory);
 }
-async function runShellCommandWithRetry(command, args = [], timeoutMs = 30000, retryCount = 0) {
+async function runShellCommandWithRetry(command, args = [], timeoutMs = 30000, retryCount = 0, directory) {
     const maxRetries = 2;
     try {
+        // Validate and resolve the directory parameter
+        const executionDirectory = await validateAndResolveDirectory(directory);
         // Security: Basic validation to prevent obviously dangerous commands
         const dangerousCommands = ['rm -rf', 'sudo', 'su', 'chmod 777', 'dd if=', 'mkfs', 'fdisk', 'format'];
         const fullCommand = `${command} ${args.join(' ')}`.toLowerCase();
@@ -59,21 +455,12 @@ async function runShellCommandWithRetry(command, args = [], timeoutMs = 30000, r
                 }
                 else {
                     // Require user confirmation with enhanced options
-                    logger.consoleLog(`\n🔐 Shell Command Requested: ${commandString}`);
-                    logger.consoleLog(`📁 Working Directory: ${workingDirectory}`);
-                    const { choice } = await inquirer.prompt([
-                        {
-                            type: 'list',
-                            name: 'choice',
-                            message: 'Choose your action:',
-                            choices: [
-                                { name: '1. ✅ Execute this command now', value: 'execute' },
-                                { name: `2. ✅ Execute and approve all "${baseCommand}" commands for this session`, value: 'approve_session' },
-                                { name: '3. ❌ Cancel and suggest alternative', value: 'cancel' }
-                            ],
-                            default: 'execute'
-                        }
-                    ]);
+                    await showShellCommandPreview(commandString, executionDirectory);
+                    const choice = await enhancedPrompt('Choose your action:', [
+                        { name: '1. ✅ Execute this command now', value: 'execute' },
+                        { name: `2. ✅ Execute and approve all "${baseCommand}" commands for this session`, value: 'approve_session' },
+                        { name: '3. ❌ Cancel and suggest alternative', value: 'cancel' }
+                    ], 'execute');
                     switch (choice) {
                         case 'execute':
                             logger.consoleLog(`🚀 Executing: ${commandString}`);
@@ -84,9 +471,9 @@ async function runShellCommandWithRetry(command, args = [], timeoutMs = 30000, r
                             logger.consoleLog(`🚀 Executing: ${commandString}`);
                             break;
                         case 'cancel':
-                            return getSuggestion(commandString);
+                            throw new UserCancellationError(`shell command: ${commandString}`, 'User chose to cancel and suggest alternative');
                         default:
-                            return `Command execution cancelled by user: ${commandString}`;
+                            throw new UserCancellationError(`shell command: ${commandString}`, 'User did not approve the command');
                     }
                 }
             }
@@ -94,9 +481,14 @@ async function runShellCommandWithRetry(command, args = [], timeoutMs = 30000, r
         else {
             logger.consoleLog(`🔄 Retry attempt ${retryCount}/${maxRetries}: ${commandString}`);
         }
+        // Check if this is an interactive command and handle it differently
+        if (isInteractiveCommand(commandString)) {
+            logger.consoleLog(`🎯 Detected interactive command: ${commandString}`);
+            return await runInteractiveCommand(command, args, executionDirectory);
+        }
         return new Promise((resolve, reject) => {
             const child = spawn(command, args, {
-                cwd: workingDirectory,
+                cwd: executionDirectory,
                 stdio: ['pipe', 'pipe', 'pipe'], // Capture all input/output for AI processing
                 shell: true,
                 env: { ...process.env, PATH: process.env.PATH }
@@ -178,6 +570,15 @@ async function analyzeTimeoutAndRetry(command, args = [], originalTimeout, retry
 function analyzeCommandForTimeout(command, args) {
     const fullCommand = `${command} ${args.join(' ')}`.toLowerCase();
     const baseCommand = command.toLowerCase();
+    // First check if this is an interactive command that should use direct terminal access
+    if (isInteractiveCommand(fullCommand)) {
+        return {
+            reason: "This is an interactive command that requires user input",
+            suggestion: "Interactive commands should use direct terminal access, not captured I/O",
+            suggestedArgs: args,
+            suggestedTimeout: 30000
+        };
+    }
     // Interactive command detection
     if (baseCommand === 'npm' && args.length > 0) {
         const npmSubcommand = args[0].toLowerCase();
@@ -186,7 +587,7 @@ function analyzeCommandForTimeout(command, args) {
             if (npmSubcommand === 'create' && !args.some(arg => arg.includes('--template'))) {
                 return {
                     reason: "npm create command likely waiting for interactive template selection",
-                    suggestion: "Add --template flag to avoid interactive prompts",
+                    suggestion: "Add --template flag to avoid interactive prompts, or use interactive mode",
                     suggestedArgs: [...args, '--template', 'vanilla'],
                     suggestedTimeout: 60000
                 };
@@ -195,7 +596,7 @@ function analyzeCommandForTimeout(command, args) {
             if (!args.some(arg => arg.includes('-y') || arg.includes('--yes'))) {
                 return {
                     reason: "npm command likely waiting for interactive confirmation",
-                    suggestion: "Add -y flag to auto-confirm prompts",
+                    suggestion: "Add -y flag to auto-confirm prompts, or use interactive mode",
                     suggestedArgs: [...args, '-y'],
                     suggestedTimeout: 60000
                 };
@@ -315,13 +716,13 @@ export const runShellCommandTool = {
     type: 'function',
     function: {
         name: 'run_shell_command',
-        description: 'Execute a shell command in the current working directory. Commands run non-interactively and output is captured for analysis. For tools that normally prompt for input (like npm create), provide all necessary flags to avoid interactive prompts. Safe commands (ls, find, grep, git status, etc.) run automatically. Other commands may require user confirmation unless running with --dangerously-accept-all flag. Examples: find . -name "*.js", grep -r "TODO" ., npm create vite@latest my-app --template react --no-interactive',
+        description: 'Execute a shell command in the current working directory or a specific subdirectory. Commands run non-interactively and output is captured for analysis. Supports compound commands like "cd subdirectory && npm install" which will automatically change to the subdirectory and run the command there. For tools that normally prompt for input (like npm create), provide all necessary flags to avoid interactive prompts. Safe commands (ls, find, grep, git status, etc.) run automatically. Other commands may require user confirmation unless running with --dangerously-accept-all flag. Examples: find . -name "*.js", grep -r "TODO" ., npm create vite@latest my-app --template react --no-interactive, cd frontend && npm install',
         parameters: {
             type: 'object',
             properties: {
                 command: {
                     type: 'string',
-                    description: 'The command to execute. Examples: "find", "grep", "ls", "git", "npm", "python", "node", "yarn"'
+                    description: 'The command to execute. Can be a simple command like "find" or a compound command like "cd directory && npm install". Examples: "find", "grep", "ls", "git", "npm", "python", "node", "yarn", "cd frontend && npm install"'
                 },
                 args: {
                     type: 'array',
@@ -333,6 +734,10 @@ export const runShellCommandTool = {
                 timeout_ms: {
                     type: 'integer',
                     description: 'Timeout in milliseconds for the command execution. Default is 30000 (30 seconds). Use higher values for long-running operations.'
+                },
+                directory: {
+                    type: 'string',
+                    description: 'Optional: Subdirectory path relative to the working directory where the command should be executed. Must be within the current working directory for security. Examples: "src", "src/components", "tests". Leave empty to execute in the current directory.'
                 }
             },
             required: ['command']

package/dist/tools/task-complete.js

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { logger } from '../utils/logger.js';
+/**
+ * Tool for the AI to explicitly signal that a task is complete
+ * This gives the AI control over when to stop the agentic loop
+ */
+const taskCompleteSchema = z.object({
+    summary: z.string().describe("Brief summary of what was accomplished"),
+    nextSteps: z.string().optional().describe("Optional suggestions for next steps or follow-up actions")
+});
+async function taskComplete(args) {
+    logger.debug('🏁 AI signaled task completion', { component: 'TaskComplete', summary: args.summary });
+    logger.consoleLog(`\n🏁 Task Complete: ${args.summary}`);
+    if (args.nextSteps) {
+        logger.consoleLog(`💡 Next Steps: ${args.nextSteps}`);
+    }
+    // Return a special marker that the agentic loop can detect
+    return "TASK_COMPLETE";
+}
+export const taskCompleteTool = {
+    name: 'task_complete',
+    description: 'Signal that the current task has been completed successfully. Use this when you have finished all requested work and want to return control to the user.',
+    inputSchema: taskCompleteSchema,
+    handler: taskComplete
+};
+export { taskComplete };

package/dist/tools/write-file.js

@@ -2,6 +2,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { randomBytes } from 'crypto';
 import { requestFileOperationApproval } from '../utils/file-operations-approval.js';
+import { isUserCancellation } from '../utils/user-cancellation.js';
 import { logger } from '../utils/logger.js';
 // Current working directory for file operations
 const workingDirectory = process.cwd();
@@ -65,14 +66,17 @@ export async function writeFile(filePath, content) {
             description: fileExists
                 ? `Overwrite existing file with ${content.length} characters of new content`
                 : `Create new file with ${content.length} characters of content`,
-            contentPreview: content.length > 500
-                ? `${content.substring(0, 250)}...\n\n...${content.substring(content.length - 250)}`
-                : content
+            contentPreview: undefined, // Will be shown in the enhanced preview
+            newContent: content,
+            changeContext: {
+                linesAdded: content.split('\n').length,
+                linesRemoved: fileExists ? 0 : 0, // We don't know the old content yet
+                totalLines: content.split('\n').length,
+                affectedLineNumbers: []
+            }
         };
-        const approved = await requestFileOperationApproval(approvalContext);
-        if (!approved) {
-            return `Write operation cancelled by user: ${filePath}`;
-        }
+        // Request user approval for write operation (throws UserCancellationError if cancelled)
+        await requestFileOperationApproval(approvalContext);
         logger.debug(`📝 Writing file: ${filePath} (${content.length} chars)`, { component: 'WriteFile', operation: 'writeFile' });
         try {
             // Security: 'wx' flag ensures exclusive creation - fails if file/symlink exists,
@@ -106,6 +110,10 @@ export async function writeFile(filePath, content) {
         return `Successfully wrote to ${filePath}`;
     }
     catch (error) {
+        // Re-throw UserCancellationError without modification
+        if (isUserCancellation(error)) {
+            throw error;
+        }
         if (error instanceof Error) {
             throw new Error(`Failed to write file: ${error.message}`);
         }

package/dist/utils/enhanced-prompt.js

@@ -0,0 +1,23 @@
+/**
+ * Enhanced prompt utility that supports both arrow key navigation + enter
+ * AND displays clear number shortcuts for faster interaction
+ */
+import inquirer from 'inquirer';
+/**
+ * Enhanced prompt that uses standard inquirer with clear number indicators
+ * Users can still use arrow keys + enter as normal, but numbers make it clear what to select
+ */
+export async function enhancedPrompt(message, choices, defaultValue) {
+    // Add instruction about keyboard shortcuts
+    const enhancedMessage = `${message}\n💡 Use arrow keys + Enter, or press the number key + Enter`;
+    const result = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'choice',
+            message: enhancedMessage,
+            choices: choices,
+            default: defaultValue
+        }
+    ]);
+    return result.choice;
+}