vigthoria-cli 1.0.0

package/src/utils/tools.ts

@@ -0,0 +1,933 @@
+/**
+ * Vigthoria CLI Tools - Agentic Tool System
+ * 
+ * This module provides Claude Code-like autonomous tool execution.
+ * Tools can be called by the AI to perform actions.
+ * 
+ * Enhanced with:
+ * - Risk-based permission system
+ * - Automatic retry logic with exponential backoff
+ * - Undo functionality for file operations
+ * - Detailed error messages with suggestions
+ * 
+ * @version 1.1.0
+ * @author Vigthoria Labs
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync, spawn } from 'child_process';
+import chalk from 'chalk';
+import { Logger } from './logger.js';
+
+// Risk levels for operations
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+
+export interface ToolResult {
+  success: boolean;
+  output?: string;
+  error?: string;
+  suggestion?: string;  // Actionable suggestion for errors
+  canRetry?: boolean;   // Whether operation can be retried
+  undoable?: boolean;   // Whether operation can be undone
+  metadata?: {          // Additional tool-specific data
+    [key: string]: any;
+  };
+}
+
+export interface ToolCall {
+  tool: string;
+  args: Record<string, string>;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: {
+    name: string;
+    description: string;
+    required: boolean;
+  }[];
+  requiresPermission: boolean;
+  dangerous: boolean;
+  riskLevel: RiskLevel;  // NEW: Risk classification
+  category: 'read' | 'write' | 'execute' | 'search';  // NEW: Tool category
+}
+
+// Undo operation tracking
+interface UndoOperation {
+  id: string;
+  tool: string;
+  timestamp: number;
+  filePath?: string;
+  originalContent?: string | null;  // null means file was created (delete on undo)
+  description: string;
+}
+
+// Error types for better handling
+export enum ToolErrorType {
+  FILE_NOT_FOUND = 'FILE_NOT_FOUND',
+  PERMISSION_DENIED = 'PERMISSION_DENIED',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  TIMEOUT = 'TIMEOUT',
+  INVALID_ARGS = 'INVALID_ARGS',
+  EXECUTION_FAILED = 'EXECUTION_FAILED',
+  USER_CANCELLED = 'USER_CANCELLED',
+}
+
+export class AgenticTools {
+  private logger: Logger;
+  private cwd: string;
+  private permissionCallback: (action: string) => Promise<boolean>;
+  private autoApprove: boolean;
+  private undoStack: UndoOperation[] = [];
+  private maxUndoStack: number = 50;
+  private retryConfig = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+    retryableErrors: ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ECONNREFUSED', 'EAI_AGAIN'],
+  };
+
+  constructor(
+    logger: Logger,
+    cwd: string,
+    permissionCallback: (action: string) => Promise<boolean>,
+    autoApprove: boolean = false
+  ) {
+    this.logger = logger;
+    this.cwd = cwd;
+    this.permissionCallback = permissionCallback;
+    this.autoApprove = autoApprove;
+  }
+
+  /**
+   * Get the undo stack for inspection
+   */
+  getUndoStack(): UndoOperation[] {
+    return [...this.undoStack];
+  }
+
+  /**
+   * Undo the last file operation
+   */
+  async undo(): Promise<ToolResult> {
+    const lastOp = this.undoStack.pop();
+    
+    if (!lastOp) {
+      return {
+        success: false,
+        error: 'Nothing to undo',
+        suggestion: 'The undo stack is empty. Only file write/edit operations can be undone.',
+      };
+    }
+
+    if (lastOp.filePath) {
+      try {
+        if (lastOp.originalContent === null) {
+          // File was created, so delete it
+          if (fs.existsSync(lastOp.filePath)) {
+            fs.unlinkSync(lastOp.filePath);
+            return {
+              success: true,
+              output: `✓ Undone: ${lastOp.description}\n  File deleted: ${lastOp.filePath}`,
+              metadata: { remainingUndos: this.undoStack.length },
+            };
+          }
+        } else if (lastOp.originalContent !== undefined) {
+          // Restore original content
+          fs.writeFileSync(lastOp.filePath, lastOp.originalContent, 'utf-8');
+          return {
+            success: true,
+            output: `✓ Undone: ${lastOp.description}\n  File restored: ${lastOp.filePath}`,
+            metadata: { remainingUndos: this.undoStack.length },
+          };
+        }
+      } catch (error) {
+        return {
+          success: false,
+          error: `Failed to undo: ${(error as Error).message}`,
+          suggestion: 'The file may have been moved or permissions changed.',
+        };
+      }
+    }
+
+    return {
+      success: false,
+      error: 'This operation cannot be undone',
+    };
+  }
+
+  /**
+   * List of available tools - similar to Claude Code
+   * Enhanced with risk levels and categories
+   */
+  static getToolDefinitions(): ToolDefinition[] {
+    return [
+      {
+        name: 'read_file',
+        description: 'Read the contents of a file',
+        parameters: [
+          { name: 'path', description: 'File path (relative or absolute)', required: true },
+          { name: 'start_line', description: 'Start line (1-indexed)', required: false },
+          { name: 'end_line', description: 'End line (1-indexed)', required: false },
+        ],
+        requiresPermission: false,
+        dangerous: false,
+        riskLevel: 'low',
+        category: 'read',
+      },
+      {
+        name: 'write_file',
+        description: 'Write content to a file (creates if not exists)',
+        parameters: [
+          { name: 'path', description: 'File path', required: true },
+          { name: 'content', description: 'Content to write', required: true },
+        ],
+        requiresPermission: true,
+        dangerous: false,
+        riskLevel: 'medium',
+        category: 'write',
+      },
+      {
+        name: 'edit_file',
+        description: 'Make specific edits to a file by replacing text',
+        parameters: [
+          { name: 'path', description: 'File path', required: true },
+          { name: 'old_text', description: 'Text to replace', required: true },
+          { name: 'new_text', description: 'New text', required: true },
+        ],
+        requiresPermission: true,
+        dangerous: false,
+        riskLevel: 'medium',
+        category: 'write',
+      },
+      {
+        name: 'bash',
+        description: 'Run a shell command',
+        parameters: [
+          { name: 'command', description: 'Shell command to execute', required: true },
+          { name: 'cwd', description: 'Working directory', required: false },
+          { name: 'timeout', description: 'Timeout in seconds', required: false },
+        ],
+        requiresPermission: true,
+        dangerous: true,
+        riskLevel: 'high',
+        category: 'execute',
+      },
+      {
+        name: 'grep',
+        description: 'Search for patterns in files',
+        parameters: [
+          { name: 'pattern', description: 'Search pattern (regex)', required: true },
+          { name: 'path', description: 'File or directory path', required: false },
+          { name: 'include', description: 'File pattern to include (e.g., *.ts)', required: false },
+        ],
+        requiresPermission: false,
+        dangerous: false,
+        riskLevel: 'low',
+        category: 'search',
+      },
+      {
+        name: 'list_dir',
+        description: 'List contents of a directory',
+        parameters: [
+          { name: 'path', description: 'Directory path', required: true },
+          { name: 'recursive', description: 'List recursively', required: false },
+        ],
+        requiresPermission: false,
+        dangerous: false,
+        riskLevel: 'low',
+        category: 'read',
+      },
+      {
+        name: 'glob',
+        description: 'Find files matching a pattern',
+        parameters: [
+          { name: 'pattern', description: 'Glob pattern (e.g., **/*.ts)', required: true },
+        ],
+        requiresPermission: false,
+        dangerous: false,
+        riskLevel: 'low',
+        category: 'search',
+      },
+      {
+        name: 'git',
+        description: 'Run git commands',
+        parameters: [
+          { name: 'args', description: 'Git command arguments', required: true },
+        ],
+        requiresPermission: true,
+        dangerous: false,
+        riskLevel: 'medium',
+        category: 'execute',
+      },
+    ];
+  }
+
+  /**
+   * Execute a tool call with enhanced error handling and retry logic
+   */
+  async execute(call: ToolCall): Promise<ToolResult> {
+    const tool = AgenticTools.getToolDefinitions().find(t => t.name === call.tool);
+    
+    if (!tool) {
+      return this.createErrorResult(
+        ToolErrorType.INVALID_ARGS,
+        `Unknown tool: ${call.tool}`,
+        `Available tools: ${AgenticTools.getToolDefinitions().map(t => t.name).join(', ')}`
+      );
+    }
+
+    // Validate required parameters
+    const validationError = this.validateParameters(call, tool);
+    if (validationError) {
+      return validationError;
+    }
+
+    // Check permission for dangerous/modifying actions
+    if (tool.requiresPermission && !this.autoApprove) {
+      const approved = await this.permissionCallback(
+        this.formatPermissionRequest(call, tool)
+      );
+      
+      if (!approved) {
+        return {
+          success: false,
+          error: 'Permission denied by user',
+          canRetry: true,
+        };
+      }
+    }
+
+    // Execute with retry logic for applicable operations
+    return this.executeWithRetry(call, tool);
+  }
+
+  /**
+   * Execute tool with automatic retry for transient failures
+   */
+  private async executeWithRetry(call: ToolCall, tool: ToolDefinition): Promise<ToolResult> {
+    let lastError: ToolResult | null = null;
+    
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      try {
+        const result = await this.executeTool(call);
+        
+        if (result.success) {
+          return result;
+        }
+
+        // Check if error is retryable
+        const isRetryable = result.canRetry !== false && 
+          this.isRetryableError(result.error || '');
+
+        if (!isRetryable || attempt === this.retryConfig.maxRetries) {
+          return result;
+        }
+
+        lastError = result;
+        
+        // Calculate delay with exponential backoff
+        const delay = Math.min(
+          this.retryConfig.baseDelayMs * Math.pow(2, attempt),
+          this.retryConfig.maxDelayMs
+        );
+        
+        this.logger.warn(`Retrying ${call.tool} in ${delay}ms (attempt ${attempt + 2}/${this.retryConfig.maxRetries + 1})...`);
+        await this.sleep(delay);
+        
+      } catch (error) {
+        lastError = this.createErrorResult(
+          ToolErrorType.EXECUTION_FAILED,
+          (error as Error).message
+        );
+        
+        if (attempt === this.retryConfig.maxRetries) {
+          return lastError;
+        }
+      }
+    }
+
+    return lastError || this.createErrorResult(
+      ToolErrorType.EXECUTION_FAILED,
+      'Unknown error after retries'
+    );
+  }
+
+  /**
+   * Execute the actual tool operation
+   */
+  private async executeTool(call: ToolCall): Promise<ToolResult> {
+    switch (call.tool) {
+      case 'read_file':
+        return this.readFile(call.args);
+      case 'write_file':
+        return this.writeFile(call.args);
+      case 'edit_file':
+        return this.editFile(call.args);
+      case 'bash':
+        return this.bash(call.args);
+      case 'grep':
+        return this.grep(call.args);
+      case 'list_dir':
+        return this.listDir(call.args);
+      case 'glob':
+        return this.glob(call.args);
+      case 'git':
+        return this.git(call.args);
+      default:
+        return this.createErrorResult(
+          ToolErrorType.INVALID_ARGS,
+          `Tool not implemented: ${call.tool}`
+        );
+    }
+  }
+
+  /**
+   * Check if an error is retryable
+   */
+  private isRetryableError(error: string): boolean {
+    return this.retryConfig.retryableErrors.some(e => error.includes(e));
+  }
+
+  /**
+   * Validate tool parameters
+   */
+  private validateParameters(call: ToolCall, tool: ToolDefinition): ToolResult | null {
+    for (const param of tool.parameters) {
+      if (param.required && !call.args[param.name]) {
+        return this.createErrorResult(
+          ToolErrorType.INVALID_ARGS,
+          `Missing required parameter: ${param.name}`,
+          `The ${call.tool} tool requires the '${param.name}' parameter. ${param.description}`
+        );
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Create a standardized error result
+   */
+  private createErrorResult(
+    type: ToolErrorType,
+    message: string,
+    suggestion?: string
+  ): ToolResult {
+    const suggestions: Record<ToolErrorType, string> = {
+      [ToolErrorType.FILE_NOT_FOUND]: 'Check if the file path is correct. Use list_dir to see available files.',
+      [ToolErrorType.PERMISSION_DENIED]: 'You may need elevated permissions. Try using sudo or check file ownership.',
+      [ToolErrorType.NETWORK_ERROR]: 'Check your internet connection. The operation will retry automatically.',
+      [ToolErrorType.TIMEOUT]: 'The operation took too long. Try with a shorter timeout or simpler command.',
+      [ToolErrorType.INVALID_ARGS]: 'Check the tool documentation for correct parameter usage.',
+      [ToolErrorType.EXECUTION_FAILED]: 'Review the command syntax and try again.',
+      [ToolErrorType.USER_CANCELLED]: 'Operation cancelled. You can retry if needed.',
+    };
+
+    return {
+      success: false,
+      error: message,
+      suggestion: suggestion || suggestions[type],
+      canRetry: type !== ToolErrorType.USER_CANCELLED && type !== ToolErrorType.INVALID_ARGS,
+    };
+  }
+
+  /**
+   * Enhanced permission request with risk visualization
+   */
+  private formatPermissionRequest(call: ToolCall, tool: ToolDefinition): string {
+    const riskColors: Record<RiskLevel, (text: string) => string> = {
+      low: chalk.green,
+      medium: chalk.yellow,
+      high: chalk.red,
+      critical: chalk.bgRed.white,
+    };
+    
+    const riskIcons: Record<RiskLevel, string> = {
+      low: '🟢',
+      medium: '🟡',
+      high: '🔴',
+      critical: '⛔',
+    };
+
+    const riskColor = riskColors[tool.riskLevel];
+    const riskIcon = riskIcons[tool.riskLevel];
+    
+    let msg = `\n${riskIcon} ${riskColor(`${tool.riskLevel.toUpperCase()} RISK`)} - AI wants to use ${chalk.cyan.bold(call.tool)}\n`;
+    msg += chalk.gray('─'.repeat(50)) + '\n';
+    
+    // Tool-specific details
+    if (call.tool === 'bash') {
+      msg += `${chalk.gray('├─')} ${chalk.white('Command:')} ${chalk.yellow(call.args.command)}\n`;
+      if (call.args.cwd) {
+        msg += `${chalk.gray('├─')} ${chalk.white('Directory:')} ${call.args.cwd}\n`;
+      }
+      msg += `${chalk.gray('├─')} ${chalk.white('Timeout:')} ${call.args.timeout || '30'}s\n`;
+    } else if (call.tool === 'write_file') {
+      msg += `${chalk.gray('├─')} ${chalk.white('File:')} ${chalk.cyan(call.args.path)}\n`;
+      const preview = call.args.content.substring(0, 100);
+      msg += `${chalk.gray('├─')} ${chalk.white('Content preview:')} ${chalk.gray(preview)}${call.args.content.length > 100 ? '...' : ''}\n`;
+      msg += `${chalk.gray('├─')} ${chalk.white('Size:')} ${call.args.content.length} bytes\n`;
+    } else if (call.tool === 'edit_file') {
+      msg += `${chalk.gray('├─')} ${chalk.white('File:')} ${chalk.cyan(call.args.path)}\n`;
+      msg += `${chalk.gray('├─')} ${chalk.white('Replace:')} ${chalk.red(call.args.old_text.substring(0, 50))}${call.args.old_text.length > 50 ? '...' : ''}\n`;
+      msg += `${chalk.gray('├─')} ${chalk.white('With:')} ${chalk.green(call.args.new_text.substring(0, 50))}${call.args.new_text.length > 50 ? '...' : ''}\n`;
+    } else if (call.tool === 'git') {
+      msg += `${chalk.gray('├─')} ${chalk.white('Command:')} git ${chalk.yellow(call.args.args)}\n`;
+    }
+    
+    // Safety info
+    msg += chalk.gray('─'.repeat(50)) + '\n';
+    
+    const canUndo = ['write_file', 'edit_file'].includes(call.tool);
+    msg += `${chalk.gray('├─')} ${chalk.white('Undo:')} ${canUndo ? chalk.green('✓ Available (use /undo)') : chalk.gray('✗ Not available')}\n`;
+    msg += `${chalk.gray('└─')} ${chalk.white('Category:')} ${tool.category}\n`;
+    
+    if (tool.dangerous) {
+      msg += `\n${chalk.red.bold('⚠️  WARNING: This is a potentially dangerous action!')}\n`;
+      msg += chalk.red('   The AI is requesting to execute commands on your system.\n');
+    }
+    
+    return msg;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  // Tool implementations with enhanced error handling and undo support
+
+  /**
+   * Read file with enhanced error handling and suggestions
+   */
+  private readFile(args: Record<string, string>): ToolResult {
+    const filePath = this.resolvePath(args.path);
+    
+    if (!fs.existsSync(filePath)) {
+      // Try to find similar files
+      const dir = path.dirname(filePath);
+      const basename = path.basename(filePath);
+      let suggestions: string[] = [];
+      
+      if (fs.existsSync(dir)) {
+        const files = fs.readdirSync(dir);
+        suggestions = files
+          .filter(f => f.toLowerCase().includes(basename.toLowerCase().slice(0, 3)))
+          .slice(0, 3);
+      }
+      
+      return this.createErrorResult(
+        ToolErrorType.FILE_NOT_FOUND,
+        `File not found: ${args.path}`,
+        suggestions.length > 0 
+          ? `Did you mean one of these? ${suggestions.join(', ')}`
+          : 'Use list_dir to see available files in the directory.'
+      );
+    }
+
+    try {
+      const stats = fs.statSync(filePath);
+      if (stats.size > 1024 * 1024) { // 1MB warning
+        this.logger.warn(`Large file (${(stats.size / 1024 / 1024).toFixed(2)}MB) - consider using start_line/end_line`);
+      }
+      
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+      
+      const startLine = args.start_line ? parseInt(args.start_line) - 1 : 0;
+      const endLine = args.end_line ? parseInt(args.end_line) : lines.length;
+      
+      // Validate line numbers
+      if (startLine < 0 || startLine >= lines.length) {
+        return this.createErrorResult(
+          ToolErrorType.INVALID_ARGS,
+          `Invalid start_line: ${args.start_line}. File has ${lines.length} lines.`
+        );
+      }
+      
+      const selectedLines = lines.slice(startLine, Math.min(endLine, lines.length));
+      
+      return {
+        success: true,
+        output: selectedLines.join('\n'),
+        metadata: {
+          totalLines: lines.length,
+          linesReturned: selectedLines.length,
+          filePath: args.path,
+        },
+      };
+    } catch (error: any) {
+      if (error.code === 'EACCES') {
+        return this.createErrorResult(ToolErrorType.PERMISSION_DENIED, `Permission denied: ${args.path}`);
+      }
+      return this.createErrorResult(ToolErrorType.EXECUTION_FAILED, error.message);
+    }
+  }
+
+  /**
+   * Write file with undo support
+   */
+  private writeFile(args: Record<string, string>): ToolResult {
+    const filePath = this.resolvePath(args.path);
+    const dir = path.dirname(filePath);
+    
+    // Save original content for undo if file exists
+    let originalContent: string | null = null;
+    if (fs.existsSync(filePath)) {
+      originalContent = fs.readFileSync(filePath, 'utf-8');
+    }
+    
+    try {
+      // Create directory if needed
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+      }
+      
+      fs.writeFileSync(filePath, args.content, 'utf-8');
+      
+      // Store undo operation
+      const undoOp: UndoOperation = {
+        id: `undo-${Date.now()}`,
+        tool: 'write_file',
+        timestamp: Date.now(),
+        filePath: filePath,
+        originalContent: originalContent,
+        description: originalContent 
+          ? `Restore ${args.path} to previous version`
+          : `Delete ${args.path} (was created)`,
+      };
+      this.undoStack.push(undoOp);
+      
+      // Limit undo stack size
+      if (this.undoStack.length > 50) {
+        this.undoStack.shift();
+      }
+      
+      const isNew = originalContent === null;
+      return {
+        success: true,
+        output: `File ${isNew ? 'created' : 'updated'}: ${args.path}`,
+        metadata: {
+          bytes: args.content.length,
+          isNew,
+          canUndo: true,
+        },
+      };
+    } catch (error: any) {
+      if (error.code === 'EACCES') {
+        return this.createErrorResult(ToolErrorType.PERMISSION_DENIED, `Permission denied writing to: ${args.path}`);
+      }
+      if (error.code === 'ENOSPC') {
+        return this.createErrorResult(ToolErrorType.EXECUTION_FAILED, 'No space left on device');
+      }
+      return this.createErrorResult(ToolErrorType.EXECUTION_FAILED, error.message);
+    }
+  }
+
+  /**
+   * Edit file with undo support and helpful error messages
+   */
+  private editFile(args: Record<string, string>): ToolResult {
+    const filePath = this.resolvePath(args.path);
+    
+    if (!fs.existsSync(filePath)) {
+      return this.createErrorResult(
+        ToolErrorType.FILE_NOT_FOUND,
+        `File not found: ${args.path}`,
+        'Use write_file to create a new file, or check the path.'
+      );
+    }
+
+    try {
+      let content = fs.readFileSync(filePath, 'utf-8');
+      const originalContent = content;
+      
+      if (!content.includes(args.old_text)) {
+        // Try to help identify the issue
+        const lines = content.split('\n');
+        const searchTerms = args.old_text.split('\n')[0].trim().slice(0, 30);
+        const possibleMatches = lines
+          .map((line, i) => ({ line: i + 1, content: line }))
+          .filter(l => l.content.includes(searchTerms.slice(0, 10)))
+          .slice(0, 3);
+        
+        let suggestion = 'The exact text was not found. ';
+        if (possibleMatches.length > 0) {
+          suggestion += `Similar content found at lines: ${possibleMatches.map(m => m.line).join(', ')}. `;
+        }
+        suggestion += 'Ensure whitespace and indentation match exactly.';
+        
+        return this.createErrorResult(
+          ToolErrorType.EXECUTION_FAILED,
+          'Old text not found in file',
+          suggestion
+        );
+      }
+      
+      // Check for multiple matches
+      const matchCount = (content.match(new RegExp(args.old_text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')) || []).length;
+      if (matchCount > 1) {
+        this.logger.warn(`Found ${matchCount} matches - only replacing first occurrence`);
+      }
+      
+      content = content.replace(args.old_text, args.new_text);
+      fs.writeFileSync(filePath, content, 'utf-8');
+      
+      // Store undo operation
+      const undoOp: UndoOperation = {
+        id: `undo-${Date.now()}`,
+        tool: 'edit_file',
+        timestamp: Date.now(),
+        filePath: filePath,
+        originalContent: originalContent,
+        description: `Restore ${args.path} (reverts edit)`,
+      };
+      this.undoStack.push(undoOp);
+      
+      // Limit undo stack size
+      if (this.undoStack.length > 50) {
+        this.undoStack.shift();
+      }
+      
+      return {
+        success: true,
+        output: `File edited: ${args.path}`,
+        metadata: {
+          matchesFound: matchCount,
+          canUndo: true,
+        },
+      };
+    } catch (error: any) {
+      if (error.code === 'EACCES') {
+        return this.createErrorResult(ToolErrorType.PERMISSION_DENIED, `Permission denied: ${args.path}`);
+      }
+      return this.createErrorResult(ToolErrorType.EXECUTION_FAILED, error.message);
+    }
+  }
+
+  /**
+   * Execute bash command with enhanced error handling
+   */
+  private bash(args: Record<string, string>): ToolResult {
+    const cwd = args.cwd ? this.resolvePath(args.cwd) : this.cwd;
+    const timeout = args.timeout ? parseInt(args.timeout) * 1000 : 30000;
+    
+    // Validate working directory
+    if (!fs.existsSync(cwd)) {
+      return this.createErrorResult(
+        ToolErrorType.FILE_NOT_FOUND,
+        `Working directory not found: ${cwd}`,
+        'Check that the directory exists or use an absolute path.'
+      );
+    }
+    
+    try {
+      const startTime = Date.now();
+      const output = execSync(args.command, {
+        cwd,
+        timeout,
+        encoding: 'utf-8',
+        maxBuffer: 10 * 1024 * 1024, // 10MB
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      
+      const duration = Date.now() - startTime;
+      
+      return {
+        success: true,
+        output: output.trim(),
+        metadata: {
+          durationMs: duration,
+          cwd,
+        },
+      };
+    } catch (error: any) {
+      // Command failed but may have output
+      const output = error.stdout || '';
+      const stderr = error.stderr || '';
+      
+      // Provide helpful error messages for common cases
+      if (error.killed) {
+        return this.createErrorResult(
+          ToolErrorType.TIMEOUT,
+          `Command timed out after ${timeout/1000}s`,
+          'Try increasing the timeout or breaking the command into smaller parts.'
+        );
+      }
+      
+      if (stderr.includes('command not found') || stderr.includes('not recognized')) {
+        const cmd = args.command.split(' ')[0];
+        return this.createErrorResult(
+          ToolErrorType.EXECUTION_FAILED,
+          `Command not found: ${cmd}`,
+          'Check that the command is installed and in PATH.'
+        );
+      }
+      
+      if (stderr.includes('Permission denied')) {
+        return this.createErrorResult(
+          ToolErrorType.PERMISSION_DENIED,
+          'Permission denied executing command',
+          'Try using sudo or check file/directory permissions.'
+        );
+      }
+      
+      return {
+        success: false,
+        output,
+        error: stderr || error.message,
+        suggestion: 'Check command syntax and try again.',
+        canRetry: !error.killed,
+      };
+    }
+  }
+
+  private grep(args: Record<string, string>): ToolResult {
+    const searchPath = args.path ? this.resolvePath(args.path) : this.cwd;
+    const include = args.include || '*';
+    
+    let cmd = `grep -rn --color=never "${args.pattern}" ${searchPath}`;
+    if (args.include) {
+      cmd = `grep -rn --color=never --include="${args.include}" "${args.pattern}" ${searchPath}`;
+    }
+    
+    try {
+      const output = execSync(cmd, {
+        cwd: this.cwd,
+        encoding: 'utf-8',
+        maxBuffer: 5 * 1024 * 1024,
+        timeout: 30000,
+      });
+      
+      return { success: true, output: output.trim() };
+    } catch (error: any) {
+      if (error.status === 1) {
+        // No matches found
+        return { success: true, output: 'No matches found' };
+      }
+      return { success: false, error: error.message };
+    }
+  }
+
+  private listDir(args: Record<string, string>): ToolResult {
+    const dirPath = this.resolvePath(args.path);
+    
+    if (!fs.existsSync(dirPath)) {
+      return { success: false, error: `Directory not found: ${args.path}` };
+    }
+
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    const output = entries.map(e => {
+      const suffix = e.isDirectory() ? '/' : '';
+      return e.name + suffix;
+    }).join('\n');
+    
+    return { success: true, output };
+  }
+
+  private glob(args: Record<string, string>): ToolResult {
+    const { globSync } = require('glob');
+    
+    try {
+      const files = globSync(args.pattern, { cwd: this.cwd });
+      return { success: true, output: files.join('\n') };
+    } catch (error) {
+      return { success: false, error: (error as Error).message };
+    }
+  }
+
+  private git(args: Record<string, string>): ToolResult {
+    try {
+      const output = execSync(`git ${args.args}`, {
+        cwd: this.cwd,
+        encoding: 'utf-8',
+        timeout: 60000,
+      });
+      return { success: true, output: output.trim() };
+    } catch (error: any) {
+      return { success: false, error: error.stderr || error.message };
+    }
+  }
+
+  private resolvePath(p: string): string {
+    if (path.isAbsolute(p)) {
+      return p;
+    }
+    return path.join(this.cwd, p);
+  }
+
+  /**
+   * Parse tool calls from AI response (Claude Code format)
+   */
+  static parseToolCalls(text: string): ToolCall[] {
+    const calls: ToolCall[] = [];
+    
+    // Match <tool_call>...</tool_call> blocks
+    const toolCallRegex = /<tool_call>\s*(\{[\s\S]*?\})\s*<\/tool_call>/g;
+    let match;
+    
+    while ((match = toolCallRegex.exec(text)) !== null) {
+      try {
+        const parsed = JSON.parse(match[1]);
+        if (parsed.tool && parsed.args) {
+          calls.push(parsed);
+        }
+      } catch (e) {
+        // Invalid JSON, skip
+      }
+    }
+    
+    // Also match ```tool format
+    const codeBlockRegex = /```tool\s*\n(\{[\s\S]*?\})\n```/g;
+    while ((match = codeBlockRegex.exec(text)) !== null) {
+      try {
+        const parsed = JSON.parse(match[1]);
+        if (parsed.tool && parsed.args) {
+          calls.push(parsed);
+        }
+      } catch (e) {
+        // Invalid JSON, skip
+      }
+    }
+    
+    return calls;
+  }
+
+  /**
+   * Get tools formatted for AI system prompt
+   */
+  static getToolsForPrompt(): string {
+    const tools = AgenticTools.getToolDefinitions();
+    
+    let prompt = `You have access to these tools to help accomplish tasks:
+
+`;
+    
+    for (const tool of tools) {
+      prompt += `## ${tool.name}
+${tool.description}
+Parameters:
+${tool.parameters.map(p => `  - ${p.name}${p.required ? ' (required)' : ''}: ${p.description}`).join('\n')}
+
+`;
+    }
+    
+    prompt += `
+To use a tool, respond with a tool_call block:
+\`\`\`tool
+{
+  "tool": "tool_name",
+  "args": {
+    "param1": "value1"
+  }
+}
+\`\`\`
+
+You can use multiple tool calls in one response. After tool execution, you'll receive the results and can continue.
+Always explain what you're doing before using tools.
+`;
+    
+    return prompt;
+  }
+}