vigthoria-cli 1.8.19 → 1.9.5

package/dist/utils/tools.js

@@ -52,12 +52,234 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgenticTools = exports.ToolErrorType = void 0;
+exports.installUpdateWindows = installUpdateWindows;
+exports.robustifyStreamResponse = robustifyStreamResponse;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
 const chalk_1 = __importDefault(require("chalk"));
 const logger_js_1 = require("./logger.js");
 const api_js_1 = require("./api.js");
+const STREAM_RESPONSE_MAX_YIELD_CHARS = 32 * 1024;
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+function resolveWindowsInstallerPath() {
+    const configuredPath = process.env.VIGTHORIA_WINDOWS_INSTALLER || process.env.VIGTHORIA_UPDATE_INSTALLER;
+    if (configuredPath && configuredPath.trim().length > 0) {
+        return path.resolve(configuredPath);
+    }
+    const executableDir = path.dirname(process.execPath);
+    const cwd = process.cwd();
+    const candidates = [
+        path.resolve(cwd, 'dist', 'VigthoriaSetup.exe'),
+        path.resolve(cwd, 'release', 'VigthoriaSetup.exe'),
+        path.resolve(cwd, 'VigthoriaSetup.exe'),
+        path.resolve(executableDir, 'VigthoriaSetup.exe'),
+        path.resolve(executableDir, '..', 'VigthoriaSetup.exe'),
+    ];
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? candidates[0];
+}
+async function installUpdateWindows() {
+    const installerPath = resolveWindowsInstallerPath();
+    try {
+        if (!fs.existsSync(installerPath)) {
+            return { success: false, platform: 'windows', error: 'ENOENT' };
+        }
+        await fs.promises.access(installerPath, fs.constants.F_OK);
+        await new Promise((resolve, reject) => {
+            const child = (0, child_process_1.spawn)(installerPath, [], {
+                cwd: path.dirname(installerPath),
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: false,
+            });
+            child.once('error', reject);
+            child.once('spawn', () => {
+                child.unref();
+                resolve();
+            });
+        });
+        return { success: true, platform: 'windows' };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return { success: false, platform: 'windows', error: 'ENOENT' };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, platform: 'windows', error: message };
+    }
+}
+async function* robustifyStreamResponse(res) {
+    const MAX_YIELD_CHARS = STREAM_RESPONSE_MAX_YIELD_CHARS;
+    const MAX_BUFFER_CHARS = 256 * 1024;
+    const body = res?.body ?? res;
+    const decoder = new TextDecoder('utf-8');
+    let reader = null;
+    let lineBuffer = '';
+    const emitContent = async function* (type, content) {
+        for (let offset = 0; offset < content.length; offset += MAX_YIELD_CHARS) {
+            const part = content.slice(offset, offset + MAX_YIELD_CHARS);
+            if (part.length > 0) {
+                yield { type, content: part };
+            }
+        }
+    };
+    const textFromObject = (value) => {
+        if (!value || typeof value !== 'object')
+            return '';
+        if (typeof value.content === 'string')
+            return value.content;
+        if (typeof value.text === 'string')
+            return value.text;
+        if (typeof value.delta === 'string')
+            return value.delta;
+        if (typeof value.delta?.text === 'string')
+            return value.delta.text;
+        if (typeof value.message?.content === 'string')
+            return value.message.content;
+        if (typeof value.choices?.[0]?.delta?.content === 'string')
+            return value.choices[0].delta.content;
+        if (typeof value.choices?.[0]?.message?.content === 'string')
+            return value.choices[0].message.content;
+        if (typeof value.error === 'string')
+            return value.error;
+        if (typeof value.error?.message === 'string')
+            return value.error.message;
+        return '';
+    };
+    const stringifyChunk = (chunk) => {
+        if (typeof chunk === 'string')
+            return chunk;
+        if (Buffer.isBuffer(chunk))
+            return chunk.toString('utf8');
+        if (chunk instanceof Uint8Array)
+            return Buffer.from(chunk).toString('utf8');
+        if (chunk instanceof ArrayBuffer)
+            return Buffer.from(chunk).toString('utf8');
+        if (chunk === null || chunk === undefined)
+            return '';
+        const objectText = textFromObject(chunk);
+        return objectText || String(chunk);
+    };
+    const decodeLine = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed === 'event: ping' || trimmed === ':' || trimmed === 'data: [DONE]' || trimmed === '[DONE]') {
+            return null;
+        }
+        const payload = trimmed.startsWith('data:') ? trimmed.slice(5).trimStart() : trimmed;
+        if (!payload || payload === '[DONE]')
+            return null;
+        if ((payload.startsWith('{') && payload.endsWith('}')) || (payload.startsWith('[') && payload.endsWith(']'))) {
+            try {
+                const parsed = JSON.parse(payload);
+                const parsedText = textFromObject(parsed);
+                if (parsedText) {
+                    const type = parsed.error ? 'error' : 'delta';
+                    return { type, content: parsedText };
+                }
+            }
+            catch (error) {
+                console.debug(`Stream JSON fragment preserved as text: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (payload.startsWith('event:') || payload.startsWith('id:') || payload.startsWith('retry:')) {
+            return null;
+        }
+        return { type: 'delta', content: payload };
+    };
+    const consumeText = async function* (text, flush = false) {
+        if (text) {
+            lineBuffer += text;
+        }
+        while (lineBuffer.length > MAX_BUFFER_CHARS) {
+            const newlineIndex = lineBuffer.indexOf('\n', Math.max(0, MAX_BUFFER_CHARS - MAX_YIELD_CHARS));
+            const cutIndex = newlineIndex >= 0 ? newlineIndex + 1 : MAX_BUFFER_CHARS;
+            const overflow = lineBuffer.slice(0, cutIndex);
+            lineBuffer = lineBuffer.slice(cutIndex);
+            const decoded = decodeLine(overflow);
+            if (decoded) {
+                yield* emitContent(decoded.type, decoded.content);
+            }
+            else {
+                yield* emitContent('delta', overflow);
+            }
+        }
+        const lines = lineBuffer.split(/\r?\n/);
+        const partialLine = lines.pop() ?? '';
+        for (const line of lines) {
+            const decoded = decodeLine(line);
+            if (decoded) {
+                yield* emitContent(decoded.type, decoded.content);
+            }
+        }
+        if (flush) {
+            lineBuffer = '';
+            if (partialLine) {
+                const decoded = decodeLine(partialLine);
+                if (decoded) {
+                    yield* emitContent(decoded.type, decoded.content);
+                }
+            }
+        }
+        else {
+            lineBuffer = partialLine;
+        }
+    };
+    try {
+        if (!body) {
+            return;
+        }
+        if (typeof body.getReader === 'function') {
+            reader = body.getReader();
+            const streamReader = reader;
+            const decoder = new TextDecoder();
+            while (true) {
+                const { done, value } = await streamReader.read();
+                if (done)
+                    break;
+                const content = decoder.decode(value, { stream: true });
+                if (content.length > 0) {
+                    yield* consumeText(content);
+                }
+            }
+            const tail = decoder.decode();
+            if (tail.length > 0) {
+                yield* consumeText(tail);
+            }
+            yield* consumeText('', true);
+            return;
+        }
+        if (typeof body[Symbol.asyncIterator] === 'function') {
+            for await (const chunk of body) {
+                const content = stringifyChunk(chunk);
+                if (content.length > 0) {
+                    yield* consumeText(content);
+                }
+            }
+            yield* consumeText('', true);
+            return;
+        }
+        const content = stringifyChunk(body);
+        if (content.length > 0) {
+            yield* emitContent('text', content);
+        }
+    }
+    catch (error) {
+        const content = error instanceof Error ? error.message : String(error);
+        yield { type: 'error', content };
+    }
+    finally {
+        lineBuffer = '';
+        try {
+            reader?.releaseLock();
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.debug(`Stream reader release failed: ${message}`);
+        }
+    }
+}
 const TOOL_ARG_ALIASES = {
     read_file: {
         path: ['file', 'filePath', 'filepath', 'target', 'targetPath'],
@@ -141,16 +363,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 +520,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 +546,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 +832,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 +970,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 +1029,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 +1443,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 +1629,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 +1687,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 +1706,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 +1726,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 +1769,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,