@corbat-tech/coco 2.4.2 → 2.5.0

package/dist/cli/index.js

@@ -10,6 +10,7 @@ import os4__default, { homedir } from 'os';
 import * as fs32 from 'fs/promises';
 import fs32__default, { mkdir, writeFile, readFile, access, readdir, rm } from 'fs/promises';
 import JSON5 from 'json5';
+import { Logger } from 'tslog';
 import Anthropic from '@anthropic-ai/sdk';
 import OpenAI from 'openai';
 import { jsonrepair } from 'jsonrepair';
@@ -21,7 +22,6 @@ import chalk25 from 'chalk';
 import { execSync, execFileSync, spawn, execFile, exec } from 'child_process';
 import { promisify } from 'util';
 import { GoogleGenerativeAI, FunctionCallingMode } from '@google/generative-ai';
-import { Logger } from 'tslog';
 import matter from 'gray-matter';
 import { minimatch } from 'minimatch';
 import hljs from 'highlight.js/lib/core';
@@ -760,6 +760,106 @@ var init_retry = __esm({
     };
   }
 });
+
+// src/utils/logger.ts
+var logger_exports = {};
+__export(logger_exports, {
+  createChildLogger: () => createChildLogger,
+  createLogger: () => createLogger,
+  getLogger: () => getLogger,
+  initializeLogging: () => initializeLogging,
+  logEvent: () => logEvent,
+  logTiming: () => logTiming,
+  setLogger: () => setLogger
+});
+function levelToNumber(level) {
+  const levels = {
+    silly: 0,
+    trace: 1,
+    debug: 2,
+    info: 3,
+    warn: 4,
+    error: 5,
+    fatal: 6
+  };
+  return levels[level];
+}
+function createLogger(config = {}) {
+  const finalConfig = { ...DEFAULT_CONFIG, ...config };
+  const logger = new Logger({
+    name: finalConfig.name,
+    minLevel: levelToNumber(finalConfig.level),
+    prettyLogTemplate: finalConfig.prettyPrint ? "{{yyyy}}-{{mm}}-{{dd}} {{hh}}:{{MM}}:{{ss}} {{logLevelName}} [{{name}}] " : void 0,
+    prettyLogTimeZone: "local",
+    stylePrettyLogs: finalConfig.prettyPrint
+  });
+  if (finalConfig.logToFile && finalConfig.logDir) {
+    setupFileLogging(logger, finalConfig.logDir, finalConfig.name);
+  }
+  return logger;
+}
+function setupFileLogging(logger, logDir, name) {
+  if (!fs49__default.existsSync(logDir)) {
+    fs49__default.mkdirSync(logDir, { recursive: true });
+  }
+  const logFile = path34__default.join(logDir, `${name}.log`);
+  logger.attachTransport((logObj) => {
+    const line = JSON.stringify(logObj) + "\n";
+    fs49__default.appendFileSync(logFile, line);
+  });
+}
+function createChildLogger(parent, name) {
+  return parent.getSubLogger({ name });
+}
+function getLogger() {
+  if (!globalLogger) {
+    globalLogger = createLogger();
+  }
+  return globalLogger;
+}
+function setLogger(logger) {
+  globalLogger = logger;
+}
+function initializeLogging(projectPath, level = "info") {
+  const logDir = path34__default.join(projectPath, ".coco", "logs");
+  const logger = createLogger({
+    name: "coco",
+    level,
+    prettyPrint: process.stdout.isTTY ?? true,
+    logToFile: true,
+    logDir
+  });
+  setLogger(logger);
+  return logger;
+}
+function logEvent(logger, event, data = {}) {
+  logger.info({ event, ...data });
+}
+async function logTiming(logger, operation, fn) {
+  const start = performance.now();
+  try {
+    const result = await fn();
+    const duration = performance.now() - start;
+    logger.debug({ operation, durationMs: duration.toFixed(2), status: "success" });
+    return result;
+  } catch (error) {
+    const duration = performance.now() - start;
+    logger.error({ operation, durationMs: duration.toFixed(2), status: "error", error });
+    throw error;
+  }
+}
+var DEFAULT_CONFIG, globalLogger;
+var init_logger = __esm({
+  "src/utils/logger.ts"() {
+    DEFAULT_CONFIG = {
+      name: "coco",
+      level: "info",
+      prettyPrint: true,
+      logToFile: false
+    };
+    globalLogger = null;
+  }
+});
 function createAnthropicProvider(config) {
   const provider = new AnthropicProvider();
   if (config) {
@@ -787,6 +887,7 @@ var init_anthropic = __esm({
   "src/providers/anthropic.ts"() {
     init_errors();
     init_retry();
+    init_logger();
     DEFAULT_MODEL = "claude-opus-4-6-20260115";
     CONTEXT_WINDOWS = {
       // Kimi Code model (Anthropic-compatible endpoint)
@@ -978,8 +1079,8 @@ var init_anthropic = __esm({
                 try {
                   currentToolCall.input = currentToolInputJson ? JSON.parse(currentToolInputJson) : {};
                 } catch {
-                  console.warn(
-                    `[Anthropic] Failed to parse tool call arguments: ${currentToolInputJson?.slice(0, 100)}`
+                  getLogger().warn(
+                    `Failed to parse tool call arguments: ${currentToolInputJson?.slice(0, 100)}`
                   );
                   currentToolCall.input = {};
                 }
@@ -5143,106 +5244,6 @@ var init_types2 = __esm({
   }
 });
 
-// src/utils/logger.ts
-var logger_exports = {};
-__export(logger_exports, {
-  createChildLogger: () => createChildLogger,
-  createLogger: () => createLogger,
-  getLogger: () => getLogger,
-  initializeLogging: () => initializeLogging,
-  logEvent: () => logEvent,
-  logTiming: () => logTiming,
-  setLogger: () => setLogger
-});
-function levelToNumber(level) {
-  const levels = {
-    silly: 0,
-    trace: 1,
-    debug: 2,
-    info: 3,
-    warn: 4,
-    error: 5,
-    fatal: 6
-  };
-  return levels[level];
-}
-function createLogger(config = {}) {
-  const finalConfig = { ...DEFAULT_CONFIG2, ...config };
-  const logger = new Logger({
-    name: finalConfig.name,
-    minLevel: levelToNumber(finalConfig.level),
-    prettyLogTemplate: finalConfig.prettyPrint ? "{{yyyy}}-{{mm}}-{{dd}} {{hh}}:{{MM}}:{{ss}} {{logLevelName}} [{{name}}] " : void 0,
-    prettyLogTimeZone: "local",
-    stylePrettyLogs: finalConfig.prettyPrint
-  });
-  if (finalConfig.logToFile && finalConfig.logDir) {
-    setupFileLogging(logger, finalConfig.logDir, finalConfig.name);
-  }
-  return logger;
-}
-function setupFileLogging(logger, logDir, name) {
-  if (!fs49__default.existsSync(logDir)) {
-    fs49__default.mkdirSync(logDir, { recursive: true });
-  }
-  const logFile = path34__default.join(logDir, `${name}.log`);
-  logger.attachTransport((logObj) => {
-    const line = JSON.stringify(logObj) + "\n";
-    fs49__default.appendFileSync(logFile, line);
-  });
-}
-function createChildLogger(parent, name) {
-  return parent.getSubLogger({ name });
-}
-function getLogger() {
-  if (!globalLogger) {
-    globalLogger = createLogger();
-  }
-  return globalLogger;
-}
-function setLogger(logger) {
-  globalLogger = logger;
-}
-function initializeLogging(projectPath, level = "info") {
-  const logDir = path34__default.join(projectPath, ".coco", "logs");
-  const logger = createLogger({
-    name: "coco",
-    level,
-    prettyPrint: process.stdout.isTTY ?? true,
-    logToFile: true,
-    logDir
-  });
-  setLogger(logger);
-  return logger;
-}
-function logEvent(logger, event, data = {}) {
-  logger.info({ event, ...data });
-}
-async function logTiming(logger, operation, fn) {
-  const start = performance.now();
-  try {
-    const result = await fn();
-    const duration = performance.now() - start;
-    logger.debug({ operation, durationMs: duration.toFixed(2), status: "success" });
-    return result;
-  } catch (error) {
-    const duration = performance.now() - start;
-    logger.error({ operation, durationMs: duration.toFixed(2), status: "error", error });
-    throw error;
-  }
-}
-var DEFAULT_CONFIG2, globalLogger;
-var init_logger = __esm({
-  "src/utils/logger.ts"() {
-    DEFAULT_CONFIG2 = {
-      name: "coco",
-      level: "info",
-      prettyPrint: true,
-      logToFile: false
-    };
-    globalLogger = null;
-  }
-});
-
 // src/skills/loader/markdown-loader.ts
 var markdown_loader_exports = {};
 __export(markdown_loader_exports, {
@@ -7847,6 +7848,179 @@ Use /compact --force to compact anyway.
     };
   }
 });
+
+// src/utils/error-humanizer.ts
+function extractQuotedPath(msg) {
+  const single = msg.match(/'([^']+)'/);
+  if (single?.[1]) return single[1];
+  const double = msg.match(/"([^"]+)"/);
+  return double?.[1] ?? null;
+}
+function humanizeError(message, toolName) {
+  const msg = message.trim();
+  if (!msg) return msg;
+  if (/ECONNREFUSED/i.test(msg)) {
+    return "Connection refused \u2014 the server may not be running";
+  }
+  if (/ENOTFOUND/i.test(msg)) {
+    return "Host not found \u2014 check the URL or your internet connection";
+  }
+  if (/EHOSTUNREACH/i.test(msg)) {
+    return "Host unreachable \u2014 check your network connection";
+  }
+  if (/ECONNRESET/i.test(msg)) {
+    return "Connection reset \u2014 the server closed the connection unexpectedly";
+  }
+  if (/ERR_INVALID_URL/i.test(msg)) {
+    return "Invalid URL format \u2014 check the URL syntax";
+  }
+  if (/CERT_|ERR_CERT_|SSL_ERROR|UNABLE_TO_VERIFY_LEAF_SIGNATURE/i.test(msg)) {
+    return "SSL/TLS certificate error \u2014 the server certificate may be untrusted";
+  }
+  if (/fetch failed|network error|Failed to fetch/i.test(msg)) {
+    return "Network request failed \u2014 check your internet connection";
+  }
+  if (/ENOENT/i.test(msg)) {
+    const path54 = extractQuotedPath(msg);
+    return path54 ? `File or directory not found: ${path54}` : "File or directory not found";
+  }
+  if (/EACCES/i.test(msg)) {
+    const path54 = extractQuotedPath(msg);
+    return path54 ? `Permission denied: ${path54}` : "Permission denied \u2014 check file permissions";
+  }
+  if (/EISDIR/i.test(msg)) {
+    return "Expected a file but found a directory at the specified path";
+  }
+  if (/ENOTDIR/i.test(msg)) {
+    return "Expected a directory but found a file in the path";
+  }
+  if (/EEXIST/i.test(msg)) {
+    return "File or directory already exists";
+  }
+  if (/ENOSPC/i.test(msg)) {
+    return "No disk space left \u2014 free up some space and try again";
+  }
+  if (/EROFS/i.test(msg)) {
+    return "Write failed \u2014 the file system is read-only";
+  }
+  if (/EMFILE|ENFILE/i.test(msg)) {
+    return "Too many open files \u2014 try restarting and running again";
+  }
+  if (/not a git repository/i.test(msg)) {
+    return "Not a git repository \u2014 run 'git init' to initialize one";
+  }
+  if (/nothing to commit/i.test(msg)) {
+    return "Nothing to commit \u2014 the working tree is clean";
+  }
+  if (/merge conflict|CONFLICT/i.test(msg)) {
+    return "Merge conflict detected \u2014 resolve the conflicts before continuing";
+  }
+  if (/non-fast-forward|rejected.*push/i.test(msg)) {
+    return "Push rejected \u2014 pull the latest changes first (git pull)";
+  }
+  if (/authentication failed/i.test(msg) && /git/i.test(msg)) {
+    return "Git authentication failed \u2014 check your credentials or SSH key";
+  }
+  if (/branch.*already exists/i.test(msg)) {
+    return "Branch already exists \u2014 choose a different name or use the existing branch";
+  }
+  if (/detached HEAD/i.test(msg)) {
+    return "Detached HEAD \u2014 checkout a branch to start committing";
+  }
+  if (/(bad revision|does not exist on|unknown revision)/i.test(msg)) {
+    return "Git reference not found \u2014 the branch or commit may not exist";
+  }
+  if (/Unexpected token.*JSON|JSON\.parse|Unexpected end of JSON/i.test(msg)) {
+    return "Failed to parse JSON \u2014 the data may be malformed";
+  }
+  if (/SyntaxError.*Unexpected token/i.test(msg)) {
+    return "Syntax error in the data \u2014 check for formatting issues";
+  }
+  const moduleMatch = msg.match(/Cannot find module ['"]([^'"]+)['"]/i);
+  if (moduleMatch) {
+    return `Module not found: '${moduleMatch[1]}' \u2014 run the install command to add it`;
+  }
+  if (/ERR_MODULE_NOT_FOUND|MODULE_NOT_FOUND/i.test(msg)) {
+    return "Required module not found \u2014 run the install command first";
+  }
+  if (/ERR_REQUIRE_ESM/i.test(msg)) {
+    return "Module format mismatch \u2014 this package requires ESM (type: module)";
+  }
+  if (/command not found/i.test(msg) || /spawn.*ENOENT/i.test(msg) && toolName === "bash_exec") {
+    const cmdMatch = msg.match(/Command '([^']+)' not found|spawn ([^\s]+) ENOENT/);
+    const cmd = cmdMatch?.[1] ?? cmdMatch?.[2];
+    return cmd ? `Command '${cmd}' not found \u2014 is it installed and in your PATH?` : "Command not found \u2014 check it is installed and available in PATH";
+  }
+  if (/permission denied/i.test(msg) && /spawn|exec/i.test(msg)) {
+    return "Permission denied \u2014 the script may not be executable (try: chmod +x)";
+  }
+  if (/\b401\b|Unauthorized/i.test(msg)) {
+    return "Authentication failed (401) \u2014 check your API key or credentials";
+  }
+  if (/\b403\b|Forbidden/i.test(msg)) {
+    return "Access denied (403) \u2014 you don't have permission for this action";
+  }
+  if (/\b429\b|rate.?limit/i.test(msg)) {
+    return "Rate limit exceeded (429) \u2014 too many requests, wait a moment and retry";
+  }
+  if (/\b503\b|Service Unavailable/i.test(msg)) {
+    return "Service temporarily unavailable (503) \u2014 try again in a few minutes";
+  }
+  if (/invalid.*api.?key|api.?key.*invalid|api.?key.*not.*found/i.test(msg)) {
+    return "Invalid or missing API key \u2014 check your provider credentials";
+  }
+  return msg;
+}
+function looksLikeTechnicalJargon(message) {
+  return JARGON_PATTERNS.some((p45) => p45.test(message));
+}
+async function humanizeWithLLM(errorMessage, toolName, provider) {
+  const prompt = [
+    `A developer tool called "${toolName}" produced this error:`,
+    ``,
+    `"""`,
+    errorMessage.slice(0, 500),
+    `"""`,
+    ``,
+    `In 1\u20132 sentences, explain what went wrong in plain English and suggest the most likely fix.`,
+    `Reply with only the explanation \u2014 no preamble, no code blocks.`
+  ].join("\n");
+  try {
+    const response = await Promise.race([
+      provider.chat([{ role: "user", content: prompt }], { maxTokens: 120, temperature: 0 }),
+      new Promise((resolve4) => setTimeout(() => resolve4(null), LLM_TIMEOUT_MS))
+    ]);
+    if (!response || !("content" in response)) return null;
+    return response.content.trim() || null;
+  } catch {
+    return null;
+  }
+}
+var JARGON_PATTERNS, LLM_TIMEOUT_MS;
+var init_error_humanizer = __esm({
+  "src/utils/error-humanizer.ts"() {
+    JARGON_PATTERNS = [
+      /\bE[A-Z]{3,}\b/,
+      // POSIX error codes: EPERM, ENOENT, EACCES, …
+      /0x[0-9a-f]{4,}/i,
+      // hex addresses
+      /at \w[\w.]*\s*\(/,
+      // stack trace "at functionName ("
+      /ERR_[A-Z_]{3,}/,
+      // Node.js ERR_ codes
+      /TypeError:|ReferenceError:|RangeError:|SyntaxError:/,
+      /zod|ZodError|ZodIssue/i,
+      /Cannot read propert/i,
+      /is not a function\b/i,
+      /Cannot destructure property/i,
+      /undefined is not/i,
+      /null is not/i,
+      /TS\d{4}:/
+      // TypeScript error codes
+    ];
+    LLM_TIMEOUT_MS = 6e3;
+  }
+});
 function zodToJsonSchema(schema) {
   try {
     if (schema instanceof z.ZodObject) {
@@ -7893,6 +8067,7 @@ var ToolRegistry;
 var init_registry4 = __esm({
   "src/tools/registry.ts"() {
     init_logger();
+    init_error_humanizer();
     ToolRegistry = class {
       tools = /* @__PURE__ */ new Map();
       logger = getLogger();
@@ -7983,7 +8158,17 @@ var init_registry4 = __esm({
           };
         } catch (error) {
           const duration = performance.now() - startTime;
-          const errorMessage = error instanceof Error ? error.message : String(error);
+          let errorMessage;
+          if (error instanceof z.ZodError) {
+            const fields = error.issues.map((issue) => {
+              const field = issue.path.join(".") || "input";
+              return `${field} (${issue.message.toLowerCase()})`;
+            });
+            errorMessage = `Invalid tool input \u2014 ${fields.join(", ")}`;
+          } else {
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            errorMessage = humanizeError(rawMessage, name);
+          }
           this.logger.error(`Tool '${name}' failed`, { error: errorMessage, duration });
           options?.onProgress?.({
             phase: "failed",
@@ -19082,7 +19267,7 @@ var init_input_echo = __esm({
     DEFAULT_CONFIG7 = {
       maxVisibleChars: 60,
       prompt: "\u203A ",
-      placeholder: "Escribe para modificar o a\xF1adir tareas\u2026"
+      placeholder: "Type to modify or add tasks\u2026"
     };
   }
 });
@@ -24439,7 +24624,7 @@ async function runConfigInit() {
   p25.outro(chalk25.green("Configuration saved to .coco/config.json"));
 }
 var CONFIG_PATH = join(process.cwd(), ".coco", "config.json");
-var DEFAULT_CONFIG = {
+var DEFAULT_CONFIG2 = {
   provider: {
     type: "anthropic",
     model: "claude-sonnet-4-20250514"
@@ -24459,9 +24644,9 @@ async function loadConfig2() {
   try {
     const raw = await fs52.readFile(CONFIG_PATH, "utf-8");
     const parsed = JSON.parse(raw);
-    return { ...DEFAULT_CONFIG, ...parsed };
+    return { ...DEFAULT_CONFIG2, ...parsed };
   } catch {
-    return { ...DEFAULT_CONFIG };
+    return { ...DEFAULT_CONFIG2 };
   }
 }
 async function saveConfig2(config) {
@@ -31647,7 +31832,8 @@ var resumeCommand = {
 init_version();
 var NPM_REGISTRY_URL = "https://registry.npmjs.org/@corbat-tech/coco";
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
-var FETCH_TIMEOUT_MS = 3e3;
+var FETCH_TIMEOUT_MS = 2e3;
+var STARTUP_TIMEOUT_MS = 2500;
 var CACHE_DIR = path34__default.join(os4__default.homedir(), ".coco");
 var CACHE_FILE = path34__default.join(CACHE_DIR, "version-check-cache.json");
 function compareVersions(a, b) {
@@ -31767,13 +31953,16 @@ function printUpdateBanner(updateInfo) {
   console.log();
 }
 async function checkForUpdatesInteractive() {
-  const updateInfo = await checkForUpdates();
+  const updateInfo = await Promise.race([
+    checkForUpdates(),
+    new Promise((resolve4) => setTimeout(() => resolve4(null), STARTUP_TIMEOUT_MS))
+  ]);
   if (!updateInfo) return;
   const p45 = await import('@clack/prompts');
   printUpdateBanner(updateInfo);
   const answer = await p45.confirm({
     message: "Exit now to update?",
-    initialValue: false
+    initialValue: true
   });
   if (!p45.isCancel(answer) && answer) {
     console.log();
@@ -42715,6 +42904,8 @@ async function executeAgentTurn(session, userMessage, provider, toolRegistry, op
   const tools = toolRegistry.getToolDefinitionsForLLM();
   let iteration = 0;
   const maxIterations = session.config.agent.maxToolIterations;
+  const toolErrorCounts = /* @__PURE__ */ new Map();
+  const MAX_CONSECUTIVE_TOOL_ERRORS = 3;
   while (iteration < maxIterations) {
     iteration++;
     if (options.signal?.aborted) {
@@ -42943,6 +43134,35 @@ async function executeAgentTurn(session, userMessage, provider, toolRegistry, op
         });
       }
     }
+    let stuckInErrorLoop = false;
+    for (const executedCall of executedTools) {
+      if (!executedCall.result.success && executedCall.result.error) {
+        const errorKey = `${executedCall.name}:${executedCall.result.error.slice(0, 120).toLowerCase()}`;
+        const count = (toolErrorCounts.get(errorKey) ?? 0) + 1;
+        toolErrorCounts.set(errorKey, count);
+        if (count >= MAX_CONSECUTIVE_TOOL_ERRORS) {
+          stuckInErrorLoop = true;
+          const idx = toolResults.findIndex((r) => r.tool_use_id === executedCall.id);
+          if (idx >= 0) {
+            toolResults[idx] = {
+              ...toolResults[idx],
+              content: [
+                executedCall.result.error,
+                "",
+                `\u26A0\uFE0F This tool has now failed ${count} consecutive times with the same error.`,
+                "Do NOT retry with the same parameters.",
+                "Explain to the user what is missing or wrong, and ask for clarification if needed."
+              ].join("\n"),
+              is_error: true
+            };
+          }
+        }
+      } else {
+        for (const key of toolErrorCounts.keys()) {
+          if (key.startsWith(`${executedCall.name}:`)) toolErrorCounts.delete(key);
+        }
+      }
+    }
     const assistantContent = response.content ? [{ type: "text", text: response.content }, ...toolUses] : toolUses;
     addMessage(session, {
       role: "assistant",
@@ -42952,6 +43172,9 @@ async function executeAgentTurn(session, userMessage, provider, toolRegistry, op
       role: "user",
       content: toolResults
     });
+    if (stuckInErrorLoop) {
+      break;
+    }
   }
   options.onStream?.({ type: "done" });
   return {
@@ -43293,7 +43516,6 @@ function createIntentRecognizer(config = {}) {
       "status",
       "trust",
       "ship",
-      "open",
       "help",
       "exit"
     ];
@@ -43384,9 +43606,10 @@ function createIntentRecognizer(config = {}) {
         }
         return { command: "ship", args };
       case "open":
-        if (intent.entities.args?.[0]) {
-          args.push(intent.entities.args[0]);
+        if (!intent.entities.args?.[0]) {
+          return null;
         }
+        args.push(intent.entities.args[0]);
         if (intent.entities.flags?.includes("exec")) {
           args.push("--exec");
         }
@@ -43505,6 +43728,7 @@ function renderStatusBar(projectPath, config, gitCtx) {
 
 // src/cli/repl/index.ts
 init_subprocess_registry();
+init_error_humanizer();
 async function startRepl(options = {}) {
   const projectPath = options.projectPath ?? process.cwd();
   registerGlobalCleanup();
@@ -43869,6 +44093,7 @@ async function startRepl(options = {}) {
       const turnActionedInterruptions = [];
       const turnQueuedMessages = [];
       const pendingClassifications = [];
+      const pendingExplanations = [];
       concurrentCapture.reset();
       inputEcho.reset();
       concurrentCapture.start(
@@ -43939,6 +44164,9 @@ async function startRepl(options = {}) {
           }
           renderToolStart(result2.name, result2.input);
           renderToolEnd(result2);
+          if (!result2.result.success && result2.result.error && looksLikeTechnicalJargon(result2.result.error)) {
+            pendingExplanations.push(humanizeWithLLM(result2.result.error, result2.name, provider));
+          }
           if (isQualityLoop()) {
             setSpinner("Processing results & checking quality...");
           } else {
@@ -43975,7 +44203,7 @@ async function startRepl(options = {}) {
           clearSpinner();
         },
         onToolPreparing: (toolName) => {
-          setSpinner(`Preparing: ${toolName}\u2026`);
+          setSpinner(getToolPreparingDescription(toolName));
         },
         onBeforeConfirmation: () => {
           inputEcho.suspend();
@@ -44043,6 +44271,19 @@ async function startRepl(options = {}) {
         continue;
       }
       console.log();
+      if (pendingExplanations.length > 0) {
+        const settled = await Promise.race([
+          Promise.allSettled(pendingExplanations),
+          new Promise((resolve4) => setTimeout(() => resolve4(null), 2e3))
+        ]);
+        if (settled) {
+          for (const r of settled) {
+            if (r.status === "fulfilled" && r.value) {
+              console.log(chalk25.dim(`   \u{1F4A1} ${r.value}`));
+            }
+          }
+        }
+      }
       if (isQualityLoop() && result.content) {
         const qualityResult = parseQualityLoopReport(result.content);
         if (qualityResult) {
@@ -44240,6 +44481,29 @@ async function checkProjectTrust(projectPath) {
   console.log(chalk25.green("  \u2713 Access granted") + chalk25.dim(" \u2022 /trust to manage"));
   return true;
 }
+function getToolPreparingDescription(toolName) {
+  switch (toolName) {
+    case "write_file":
+      return "Generating file content\u2026";
+    case "edit_file":
+      return "Planning edits\u2026";
+    case "bash_exec":
+      return "Building command\u2026";
+    case "web_search":
+      return "Building search query\u2026";
+    case "web_fetch":
+      return "Preparing request\u2026";
+    case "run_tests":
+      return "Setting up test run\u2026";
+    case "git_commit":
+      return "Composing commit\u2026";
+    case "semantic_search":
+    case "grep_search":
+      return "Building search\u2026";
+    default:
+      return `Preparing ${toolName}\u2026`;
+  }
+}
 function getToolRunningDescription(name, input) {
   switch (name) {
     case "codebase_map":
@@ -44266,8 +44530,11 @@ function getToolRunningDescription(name, input) {
     }
     case "list_directory":
       return "Listing directory\u2026";
-    case "bash_exec":
-      return "Running command\u2026";
+    case "bash_exec": {
+      const cmd = typeof input.command === "string" ? input.command.trim() : "";
+      const displayCmd = cmd.replace(/^[\w=]+=\S+\s+/, "").slice(0, 55);
+      return displayCmd ? `Running: ${displayCmd}\u2026` : "Running command\u2026";
+    }
     case "run_tests":
       return "Running tests\u2026";
     case "git_status":