vigthoria-cli 1.8.15 → 1.9.2

package/dist/utils/task-display.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Vigthoria CLI — Multi-Step Terminal Task Display
+ *
+ * Renders a live, updating task progress list in the terminal using ANSI
+ * escape codes and chalk — no external UI framework required.
+ *
+ * Only activates when stderr is a real TTY; JSON mode and piped output stay clean.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskDisplay = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const ICONS = {
+    pending: chalk_1.default.gray('○'),
+    running: chalk_1.default.cyan('⟳'),
+    done: chalk_1.default.green('✓'),
+    error: chalk_1.default.red('✗'),
+    skipped: chalk_1.default.gray('\u2013'),
+};
+const LABEL_FN = {
+    pending: (s) => chalk_1.default.gray(s),
+    running: (s) => chalk_1.default.cyan.bold(s),
+    done: (s) => chalk_1.default.gray(s),
+    error: (s) => chalk_1.default.red(s),
+    skipped: (s) => chalk_1.default.gray(s),
+};
+class TaskDisplay {
+    tasks = [];
+    linesRendered = 0;
+    enabled;
+    constructor(labels, enabled = true) {
+        this.enabled = enabled && process.stderr.isTTY === true;
+        this.tasks = labels.map((label) => ({ label, status: 'pending' }));
+    }
+    clearLines() {
+        if (this.linesRendered > 0) {
+            process.stderr.write(`\u001b[${this.linesRendered}A\u001b[0J`);
+        }
+    }
+    renderLines() {
+        return this.tasks.map((t) => {
+            const icon = ICONS[t.status];
+            const label = LABEL_FN[t.status](t.label);
+            const detail = t.detail ? chalk_1.default.gray(` \u2014 ${t.detail.slice(0, 60)}`) : '';
+            return `  ${icon} ${label}${detail}`;
+        });
+    }
+    render() {
+        if (!this.enabled)
+            return;
+        this.clearLines();
+        const lines = this.renderLines();
+        process.stderr.write(lines.join('\n') + '\n');
+        this.linesRendered = lines.length;
+    }
+    start(index, detail) {
+        if (!this.enabled || index < 0 || index >= this.tasks.length)
+            return;
+        this.tasks[index].status = 'running';
+        if (detail !== undefined)
+            this.tasks[index].detail = detail;
+        this.render();
+    }
+    complete(index, detail) {
+        if (!this.enabled || index < 0 || index >= this.tasks.length)
+            return;
+        this.tasks[index].status = 'done';
+        if (detail !== undefined)
+            this.tasks[index].detail = detail;
+        this.render();
+    }
+    fail(index, detail) {
+        if (!this.enabled || index < 0 || index >= this.tasks.length)
+            return;
+        this.tasks[index].status = 'error';
+        if (detail !== undefined)
+            this.tasks[index].detail = detail;
+        this.render();
+    }
+    skip(index, detail) {
+        if (!this.enabled || index < 0 || index >= this.tasks.length)
+            return;
+        this.tasks[index].status = 'skipped';
+        if (detail !== undefined)
+            this.tasks[index].detail = detail;
+        this.render();
+    }
+    setDetail(index, detail) {
+        if (!this.enabled || index < 0 || index >= this.tasks.length)
+            return;
+        this.tasks[index].detail = detail;
+        this.render();
+    }
+    clear() {
+        if (!this.enabled)
+            return;
+        this.clearLines();
+        this.linesRendered = 0;
+    }
+    finalize() {
+        if (!this.enabled)
+            return;
+        this.clearLines();
+        const lines = this.renderLines();
+        process.stderr.write(lines.join('\n') + '\n');
+        this.linesRendered = 0;
+    }
+    get isEnabled() {
+        return this.enabled;
+    }
+}
+exports.TaskDisplay = TaskDisplay;

package/dist/utils/tools.d.ts

@@ -70,11 +70,22 @@ export declare class AgenticTools {
     private undoStack;
     private maxUndoStack;
     private retryConfig;
+    private formatExternalToolError;
+    private externalToolFailure;
+    private cleanupAfterToolError;
+    private runExternalCommand;
+    private isNonEmptyString;
+    private describeInvalidValue;
+    private assertStringRecord;
+    private requireNonEmptyString;
+    private requireArgsObject;
     private sessionApprovedTools;
     private static permissionsFile;
     constructor(logger: Logger, cwd: string, permissionCallback: (action: string, options?: {
         batchApproval?: boolean;
     }) => Promise<boolean | 'batch' | 'persist'>, autoApprove?: boolean);
+    private getErrorMessage;
+    private assertToolCall;
     /**
      * Load persistent permissions for the current project
      */
@@ -125,6 +136,10 @@ export declare class AgenticTools {
      * Check if an error is retryable
      */
     private isRetryableError;
+    /**
+     * Safely stringify tool arguments without dumping very large payloads into logs.
+     */
+    private safeStringifyArgs;
     /**
      * Validate tool parameters
      */

package/dist/utils/tools.js

@@ -141,16 +141,154 @@ class AgenticTools {
         maxDelayMs: 10000,
         retryableErrors: ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'ECONNREFUSED', 'EAI_AGAIN'],
     };
+    formatExternalToolError(toolName, operation, error) {
+        if (error instanceof Error) {
+            const processError = error;
+            const details = [
+                `External tool call failed in ${toolName} during ${operation}: ${error.message}`,
+                processError.code !== undefined ? `code=${processError.code}` : undefined,
+                processError.status !== undefined ? `status=${processError.status}` : undefined,
+                processError.signal ? `signal=${processError.signal}` : undefined,
+                processError.stderr ? `stderr=${processError.stderr.toString().trim()}` : undefined,
+                processError.stdout ? `stdout=${processError.stdout.toString().trim()}` : undefined,
+            ].filter(Boolean);
+            return details.join(' | ');
+        }
+        return `External tool call failed in ${toolName} during ${operation}: ${String(error)}`;
+    }
+    externalToolFailure(toolName, operation, error, suggestion) {
+        const message = this.formatExternalToolError(toolName, operation, error);
+        this.logger.debug(message);
+        this.logger.warn(message);
+        return {
+            success: false,
+            error: message,
+            suggestion: suggestion || 'Review the command, arguments, permissions, and environment, then retry.',
+            canRetry: true,
+        };
+    }
+    cleanupAfterToolError(toolName, operation, cleanup) {
+        try {
+            cleanup();
+        }
+        catch (cleanupError) {
+            const message = this.formatExternalToolError(toolName, `${operation} cleanup`, cleanupError);
+            this.logger.debug(message);
+            this.logger.warn(message);
+        }
+    }
+    runExternalCommand(toolName, operation, command, options, cleanup) {
+        if (!this.isNonEmptyString(toolName)) {
+            throw new Error('Invalid tool execution: toolName must be a non-empty string.');
+        }
+        if (!this.isNonEmptyString(operation)) {
+            throw new Error(`Invalid external command for ${toolName}: operation must be a non-empty string.`);
+        }
+        if (!this.isNonEmptyString(command)) {
+            throw new Error(`Invalid external command for ${toolName} during ${operation}: command must be a non-empty string.`);
+        }
+        try {
+            return (0, child_process_1.execSync)(command, options);
+        }
+        catch (error) {
+            if (cleanup) {
+                this.cleanupAfterToolError(toolName, operation, cleanup);
+            }
+            const message = this.formatExternalToolError(toolName, operation, error);
+            const wrapped = new Error(message);
+            wrapped.cause = error;
+            throw wrapped;
+        }
+    }
+    isNonEmptyString(value) {
+        return typeof value === 'string' && value.trim().length > 0;
+    }
+    describeInvalidValue(value) {
+        if (value === null)
+            return 'null';
+        if (value === undefined)
+            return 'undefined';
+        if (Array.isArray(value))
+            return 'array';
+        return typeof value;
+    }
+    assertStringRecord(value, context) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error(`${context} must be an object with string values; received ${this.describeInvalidValue(value)}.`);
+        }
+        for (const [key, entryValue] of Object.entries(value)) {
+            if (!this.isNonEmptyString(key)) {
+                throw new Error(`${context} contains an invalid empty parameter name.`);
+            }
+            if (typeof entryValue !== 'string') {
+                throw new Error(`${context}.${key} must be a string; received ${this.describeInvalidValue(entryValue)}.`);
+            }
+        }
+    }
+    requireNonEmptyString(value, fieldName, toolName) {
+        if (!this.isNonEmptyString(value)) {
+            throw new Error(`Invalid arguments for ${toolName}: ${fieldName} is required and must be a non-empty string.`);
+        }
+        return value;
+    }
+    requireArgsObject(args, toolName) {
+        this.assertStringRecord(args, `Invalid arguments for ${toolName}: args`);
+    }
     // Session-based tool approvals - remembers which tools user approved for this turn
     sessionApprovedTools = new Set();
     // Persistent permissions - tool allowlists per project
     static permissionsFile = path.join(process.env.HOME || process.env.USERPROFILE || '~', '.vigthoria', 'permissions.json');
     constructor(logger, cwd, permissionCallback, autoApprove = false) {
+        if (!logger) {
+            throw new Error('AgenticTools initialization failed: logger is required.');
+        }
+        if (typeof cwd !== 'string' || cwd.trim().length === 0) {
+            throw new Error('AgenticTools initialization failed: cwd must be a non-empty string.');
+        }
+        if (typeof permissionCallback !== 'function') {
+            throw new Error('AgenticTools initialization failed: permissionCallback must be a function.');
+        }
+        if (typeof autoApprove !== 'boolean') {
+            throw new Error('AgenticTools initialization failed: autoApprove must be a boolean.');
+        }
         this.logger = logger;
         this.cwd = cwd;
         this.permissionCallback = permissionCallback;
         this.autoApprove = autoApprove;
     }
+    getErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === 'string') {
+            return error;
+        }
+        try {
+            return JSON.stringify(error);
+        }
+        catch {
+            return String(error);
+        }
+    }
+    assertToolCall(call) {
+        if (!call || typeof call !== 'object') {
+            throw new Error('Invalid tool call: call must be an object.');
+        }
+        if (typeof call.tool !== 'string' || call.tool.trim().length === 0) {
+            throw new Error('Invalid tool call: tool name must be a non-empty string.');
+        }
+        if (!call.args || typeof call.args !== 'object' || Array.isArray(call.args)) {
+            throw new Error(`Invalid tool call for ${call.tool}: args must be an object.`);
+        }
+        for (const [key, value] of Object.entries(call.args)) {
+            if (typeof key !== 'string' || key.trim().length === 0) {
+                throw new Error(`Invalid tool call for ${call.tool}: argument names must be non-empty strings.`);
+            }
+            if (typeof value !== 'string') {
+                throw new Error(`Invalid argument "${key}" for ${call.tool}: expected string, received ${typeof value}.`);
+            }
+        }
+    }
     /**
      * Load persistent permissions for the current project
      */
@@ -160,8 +298,10 @@ class AgenticTools {
                 return JSON.parse(fs.readFileSync(AgenticTools.permissionsFile, 'utf-8'));
             }
         }
-        catch {
-            // Corrupted file - ignore
+        catch (error) {
+            const message = this.formatExternalToolError('permissions', `read ${AgenticTools.permissionsFile}`, error);
+            this.logger.debug(message);
+            this.logger.warn(message);
         }
         return {};
     }
@@ -184,8 +324,10 @@ class AgenticTools {
                 fs.mkdirSync(dir, { recursive: true });
             fs.writeFileSync(AgenticTools.permissionsFile, JSON.stringify(permissions, null, 2), 'utf-8');
         }
-        catch {
-            // Non-critical - permission won't persist
+        catch (error) {
+            const message = this.formatExternalToolError('permissions', `write ${AgenticTools.permissionsFile}`, error);
+            this.logger.debug(message);
+            this.logger.warn(message);
         }
     }
     /**
@@ -468,9 +610,21 @@ class AgenticTools {
      * Execute a tool call with enhanced error handling and retry logic
      */
     async execute(call) {
-        // Guard against malformed tool calls with undefined or empty tool names
+        // Guard against malformed tool calls before accessing fields.
+        if (!call || typeof call !== 'object') {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid tool call: expected an object, received ${call === null ? 'null' : typeof call}`, 'Provide a valid ToolCall object with a non-empty tool name and args object.');
+        }
         if (!call.tool || typeof call.tool !== 'string' || !call.tool.trim()) {
-            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid tool call: tool name is ${call.tool === undefined ? 'undefined' : 'empty'}`, `Provide a valid tool name. Available tools: ${AgenticTools.getToolDefinitions().map(t => t.name).join(', ')}`);
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid tool call: tool name is ${call.tool === undefined ? 'undefined' : typeof call.tool === 'string' ? 'empty' : typeof call.tool}`, `Provide a valid tool name. Available tools: ${AgenticTools.getToolDefinitions().map(t => t.name).join(', ')}`);
+        }
+        if (!call.args || typeof call.args !== 'object' || Array.isArray(call.args)) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid tool call for '${call.tool}': args must be a key/value object`, 'Provide args as an object with string values, for example { path: "src/index.ts" }.');
+        }
+        try {
+            this.assertStringRecord(call.args, `Invalid tool call for '${call.tool}': args`);
+        }
+        catch (error) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, this.getErrorMessage(error), 'All tool argument names must be non-empty strings and every argument value must be a string.');
         }
         const normalizedCall = this.normalizeToolCall(call);
         const tool = AgenticTools.getToolDefinitions().find(t => t.name === normalizedCall.tool);
@@ -594,39 +748,57 @@ class AgenticTools {
      * Execute the actual tool operation
      */
     async executeTool(call) {
-        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);
-            case 'repo':
-                return this.repo(call.args);
-            case 'fetch_url':
-                return this.fetchUrl(call.args);
-            case 'browser':
-                return this.browserTool(call.args);
-            case 'ssh_exec':
-                return this.sshExec(call.args);
-            case 'task':
-                return this.task(call.args);
-            case 'multi_edit':
-                return this.multiEdit(call.args);
-            case 'codebase_search':
-                return this.codebaseSearch(call.args);
-            default:
-                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Tool not implemented: ${call.tool}`);
+        try {
+            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);
+                case 'repo':
+                    return this.repo(call.args);
+                case 'fetch_url':
+                    return this.fetchUrl(call.args);
+                case 'browser':
+                    return this.browserTool(call.args);
+                case 'ssh_exec':
+                    return this.sshExec(call.args);
+                case 'task':
+                    return this.task(call.args);
+                case 'multi_edit':
+                    return this.multiEdit(call.args);
+                case 'codebase_search':
+                    return this.codebaseSearch(call.args);
+                default:
+                    return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Tool not implemented: ${call.tool}`);
+            }
+        }
+        catch (error) {
+            const context = `Tool '${call.tool}' failed while executing with args ${this.safeStringifyArgs(call.args)}`;
+            const stderr = error?.stderr?.toString?.().trim();
+            const stdout = error?.stdout?.toString?.().trim();
+            const status = error?.status !== undefined ? `exit status ${error.status}` : undefined;
+            const signal = error?.signal ? `signal ${error.signal}` : undefined;
+            const details = [context, status, signal, stderr || error?.message || String(error)].filter(Boolean).join(': ');
+            this.logger.error(details);
+            return {
+                success: false,
+                output: stdout,
+                error: details,
+                suggestion: 'Review the tool arguments and subprocess output above, then retry with corrected input.',
+                canRetry: this.isRetryableError(details),
+            };
         }
     }
     /**
@@ -635,13 +807,108 @@ class AgenticTools {
     isRetryableError(error) {
         return this.retryConfig.retryableErrors.some(e => error.includes(e));
     }
+    /**
+     * Safely stringify tool arguments without dumping very large payloads into logs.
+     */
+    safeStringifyArgs(args) {
+        try {
+            const json = JSON.stringify(args ?? {}, (_key, value) => {
+                if (typeof value === 'string' && value.length > 500) {
+                    return `${value.slice(0, 500)}...<truncated ${value.length - 500} chars>`;
+                }
+                return value;
+            });
+            return json || '{}';
+        }
+        catch (error) {
+            return `[unserializable args: ${error instanceof Error ? error.message : String(error)}]`;
+        }
+    }
     /**
      * Validate tool parameters
      */
     validateParameters(call, tool) {
+        if (!call || typeof call !== 'object') {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, 'Invalid tool call: expected an object with tool and args fields', 'Pass a ToolCall object shaped like { tool: "read_file", args: { path: "file.ts" } }.');
+        }
+        if (!call.args || typeof call.args !== 'object' || Array.isArray(call.args)) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid arguments for ${tool.name}: args must be a key/value object`, `Pass ${tool.name} arguments as an object. Received: ${this.safeStringifyArgs(call.args)}`);
+        }
+        for (const [key, value] of Object.entries(call.args)) {
+            if (!key || typeof key !== 'string') {
+                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid argument key for ${tool.name}: keys must be non-empty strings`, 'Use documented parameter names for this tool.');
+            }
+            if (typeof value !== 'string') {
+                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid argument '${key}' for ${tool.name}: expected string value, received ${Array.isArray(value) ? 'array' : typeof value}`, `Convert '${key}' to a string before invoking ${tool.name}.`);
+            }
+        }
         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}`);
+            const value = call.args[param.name];
+            if (param.required && (value === undefined || value.trim() === '')) {
+                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Missing required parameter '${param.name}' for tool '${call.tool}'`, `The ${call.tool} tool requires the '${param.name}' parameter. ${param.description}`);
+            }
+        }
+        const pathLikeParams = ['path', 'working_dir', 'cwd'];
+        for (const paramName of pathLikeParams) {
+            const value = call.args[paramName];
+            if (typeof value === 'string' && value.includes('\0')) {
+                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid ${paramName} for ${tool.name}: paths cannot contain null bytes`, 'Remove null bytes from the path and retry.');
+            }
+        }
+        if (call.args.start_line !== undefined && (!/^\d+$/.test(call.args.start_line) || Number(call.args.start_line) < 1)) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid start_line for ${tool.name}: expected a positive integer, received '${call.args.start_line}'`, 'Use a 1-based positive integer for start_line.');
+        }
+        if (call.args.end_line !== undefined && (!/^\d+$/.test(call.args.end_line) || Number(call.args.end_line) < 0)) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid end_line for ${tool.name}: expected a non-negative integer, received '${call.args.end_line}'`, 'Use 0 for end-of-file or a positive 1-based line number for end_line.');
+        }
+        if (call.args.start_line !== undefined && call.args.end_line !== undefined) {
+            const startLine = Number(call.args.start_line);
+            const endLine = Number(call.args.end_line);
+            if (endLine !== 0 && endLine < startLine) {
+                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid line range for ${tool.name}: end_line (${endLine}) is before start_line (${startLine})`, 'Use an end_line greater than or equal to start_line, or 0 to read through EOF.');
+            }
+        }
+        if (call.args.timeout !== undefined && (!/^\d+$/.test(call.args.timeout) || Number(call.args.timeout) < 1)) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid timeout for ${tool.name}: expected a positive integer number of seconds, received '${call.args.timeout}'`, 'Use a positive integer timeout in seconds.');
+        }
+        if (call.args.max_results !== undefined && (!/^\d+$/.test(call.args.max_results) || Number(call.args.max_results) < 1)) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid max_results for ${tool.name}: expected a positive integer, received '${call.args.max_results}'`, 'Use a positive integer for max_results.');
+        }
+        if (call.tool === 'list_dir' && call.args.recursive !== undefined && !['true', 'false', '1', '0', 'yes', 'no'].includes(call.args.recursive.toLowerCase())) {
+            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid recursive value for list_dir: expected true or false, received '${call.args.recursive}'`, 'Use recursive="true" or recursive="false".');
+        }
+        if (call.tool === 'fetch_url' && call.args.url !== undefined) {
+            try {
+                const parsed = new URL(call.args.url);
+                if (!['http:', 'https:'].includes(parsed.protocol)) {
+                    return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid URL protocol for fetch_url: '${parsed.protocol}'`, 'Use an http:// or https:// URL.');
+                }
+            }
+            catch (error) {
+                const message = this.getErrorMessage(error);
+                this.logger.debug(`Invalid URL for fetch_url '${call.args.url}': ${message}`);
+                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid URL for fetch_url: '${call.args.url}'`, 'Provide a fully-qualified http:// or https:// URL.');
+            }
+        }
+        if (call.tool === 'multi_edit' && call.args.edits !== undefined) {
+            try {
+                const edits = JSON.parse(call.args.edits);
+                if (!Array.isArray(edits) || edits.length === 0) {
+                    return this.createErrorResult(ToolErrorType.INVALID_ARGS, 'Invalid edits for multi_edit: expected a non-empty JSON array', 'Provide edits as a JSON array of { path, old_text, new_text } objects.');
+                }
+                for (const [index, edit] of edits.entries()) {
+                    if (!edit || typeof edit !== 'object' || Array.isArray(edit)) {
+                        return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid edit at index ${index}: expected an object`);
+                    }
+                    for (const field of ['path', 'old_text', 'new_text']) {
+                        if (typeof edit[field] !== 'string') {
+                            return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid edit at index ${index}: '${field}' must be a string`);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                return this.createErrorResult(ToolErrorType.INVALID_ARGS, `Invalid edits JSON for multi_edit: ${error instanceof Error ? error.message : String(error)}`, 'Pass a valid JSON array string for the edits parameter.');
             }
         }
         return null;
@@ -954,18 +1221,27 @@ class AgenticTools {
     validateJavaScriptSyntax(source) {
         const tempFile = path.join(this.cwd, `.vigthoria-temp-${Date.now()}.js`);
         try {
-            fs.writeFileSync(tempFile, source, 'utf-8');
-            (0, child_process_1.execSync)(`node --check "${tempFile}"`, { stdio: 'pipe' });
-            return null;
-        }
-        catch (error) {
-            const stderr = error.stderr?.toString()?.trim();
-            return stderr || error.message || 'JavaScript syntax check failed.';
+            try {
+                fs.writeFileSync(tempFile, source, 'utf-8');
+            }
+            catch (writeError) {
+                return this.formatExternalToolError('syntax_check', `write temporary file ${tempFile}`, writeError);
+            }
+            try {
+                this.runExternalCommand('syntax_check', `node --check ${tempFile}`, `node --check "${tempFile}"`, { stdio: 'pipe' });
+                return null;
+            }
+            catch (error) {
+                const stderr = error.stderr?.toString()?.trim();
+                return stderr || error.message || this.formatExternalToolError('syntax_check', `node --check ${tempFile}`, error);
+            }
         }
         finally {
-            if (fs.existsSync(tempFile)) {
-                fs.unlinkSync(tempFile);
-            }
+            this.cleanupAfterToolError('syntax_check', `remove temporary file ${tempFile}`, () => {
+                if (fs.existsSync(tempFile)) {
+                    fs.unlinkSync(tempFile);
+                }
+            });
         }
     }
     validateHtmlContent(content) {
@@ -1131,7 +1407,7 @@ class AgenticTools {
                 // Use /bin/sh on Unix-like systems (more portable than bash)
                 execOptions.shell = '/bin/sh';
             }
-            const output = (0, child_process_1.execSync)(args.command, execOptions);
+            const output = this.runExternalCommand('bash', args.command, args.command, execOptions);
             const duration = Date.now() - startTime;
             return {
                 success: true,
@@ -1189,12 +1465,16 @@ class AgenticTools {
             (0, child_process_1.execSync)('rg --version', { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
             return this.grepWithRg(args, searchPath);
         }
-        catch { /* rg not available */ }
+        catch (error) {
+            this.logger.debug(this.formatExternalToolError('grep', 'checking ripgrep availability on Windows', error));
+        }
         // 2. Try PowerShell Select-String
         try {
             return this.grepWithSelectString(args, searchPath);
         }
-        catch { /* Select-String failed */ }
+        catch (error) {
+            this.logger.debug(this.formatExternalToolError('grep', 'running PowerShell Select-String fallback', error));
+        }
         // 3. Fall back to Node-native recursive file scanner
         return this.grepNodeNative(args, searchPath);
     }
@@ -1204,10 +1484,13 @@ class AgenticTools {
     grepUnix(args, searchPath, platform) {
         // Try ripgrep first if available
         try {
-            (0, child_process_1.execSync)('rg --version', { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
+            this.runExternalCommand('grep', 'checking ripgrep availability on Unix', 'rg --version', { encoding: 'utf-8', timeout: 5000, stdio: 'pipe' });
             return this.grepWithRg(args, searchPath);
         }
-        catch { /* rg not available, fall through to system grep */ }
+        catch (error) {
+            this.logger.debug(this.formatExternalToolError('grep', 'checking ripgrep availability on Unix', error));
+            // rg not available, fall through to system grep
+        }
         const isMac = platform === 'darwin';
         let cmd;
         if (isMac) {
@@ -1221,7 +1504,7 @@ class AgenticTools {
                 : `grep -rn --color=never "${args.pattern}" "${searchPath}"`;
         }
         try {
-            const output = (0, child_process_1.execSync)(cmd, {
+            const output = this.runExternalCommand('grep', 'system grep search', cmd, {
                 cwd: this.cwd,
                 encoding: 'utf-8',
                 maxBuffer: 5 * 1024 * 1024,
@@ -1264,7 +1547,7 @@ class AgenticTools {
         }
         cmd += ` "${args.pattern}" "${searchPath}"`;
         try {
-            const output = (0, child_process_1.execSync)(cmd, {
+            const output = this.runExternalCommand('grep', 'ripgrep search', cmd, {
                 cwd: this.cwd,
                 encoding: 'utf-8',
                 maxBuffer: 5 * 1024 * 1024,