codemini-cli 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",

package/src/cli.js

@@ -4,7 +4,7 @@ import { handleConfig } from './commands/config.js';
 import { handleDoctor } from './commands/doctor.js';
 import { handleSkill } from './commands/skill.js';
 
-const VERSION = '0.2.8';
+const VERSION = '0.2.9';
 
 function printHelp() {
   console.log(`codemini ${VERSION}

package/src/tui/chat-app.js

@@ -2,6 +2,20 @@ import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { Box, Text, useApp, useInput } from 'ink';
 import { shouldCaptureEscapeSequence } from './input-escape.js';
 import { classifyCommandIntent } from '../core/shell.js';
+import {
+  buildInterToolNotice as buildRegisteredInterToolNotice,
+  buildPreToolNotice as buildRegisteredPreToolNotice,
+  buildSyntheticCompletionText as buildRegisteredSyntheticCompletionText
+} from './tool-narration.js';
+import {
+  describeToolActivity as describeRegisteredToolActivity,
+  isCodeGenerationActivityName
+} from './tool-activity/index.js';
+import {
+  describeAutoSkillActivity as describeRegisteredAutoSkillActivity,
+  describeSkillActivity as describeRegisteredSkillActivity,
+  formatAutoSkillBadge as formatRegisteredAutoSkillBadge
+} from './skill-activity/index.js';
 
 const h = React.createElement;
 const SUGGESTION_PAGE_SIZE = 8;
@@ -675,33 +689,8 @@ function parseToolDisplayName(name) {
   };
 }
 
-function isCodeGenerationActivityName(name) {
-  return String(name || '').trim() === 'Code generation';
-}
-
 export function buildPreToolNotice(name, copy) {
-  const parsed = parseToolDisplayName(name);
-  const base = parsed.base;
-  const target = parsed.target ? trimText(parsed.target, 48) : '';
-  const isEnglish = String(copy?.roleLabels?.coder || '').trim() === 'CODER' && String(copy?.roleLabels?.you || '').trim() === 'YOU';
-
-  if (isEnglish) {
-    if (base === 'read') return target ? `I'll inspect ${target} first.` : `I'll inspect the relevant file first.`;
-    if (base === 'list' || base === 'glob') return target ? `I'll inspect the ${target} directory first.` : `I'll inspect the relevant directory first.`;
-    if (base === 'grep') return `I'll search the relevant code first.`;
-    if (base === 'edit' || base === 'write' || base === 'patch' || base === 'generate_diff') {
-      return `I'll inspect the current code first, then make the change.`;
-    }
-    if (base === 'run') return `I'll verify the current project state first.`;
-    return `I'll check the relevant project context first.`;
-  }
-
-  if (base === 'read') return target ? `我先查看 ${target} 的内容。` : '我先查看相关文件内容。';
-  if (base === 'list' || base === 'glob') return target ? `我先查看 ${target} 目录里的内容。` : '我先查看相关目录内容。';
-  if (base === 'grep') return '我先搜索相关代码位置。';
-  if (base === 'edit' || base === 'write' || base === 'patch' || base === 'generate_diff') return '我先确认当前代码上下文，再动手修改。';
-  if (base === 'run') return '我先检查当前项目状态。';
-  return '我先查看相关上下文。';
+  return buildRegisteredPreToolNotice(name, copy);
 }
 
 export function shouldInjectPreToolNotice(msg) {
@@ -712,6 +701,33 @@ export function shouldInjectPreToolNotice(msg) {
   return !text && !hasTextSegment;
 }
 
+function getLastToolActivity(msg, statuses = []) {
+  const allowed = new Set((Array.isArray(statuses) ? statuses : []).map((status) => String(status)));
+  const segments = Array.isArray(msg?.segments) ? msg.segments : [];
+  for (let idx = segments.length - 1; idx >= 0; idx -= 1) {
+    const segment = segments[idx];
+    if (segment?.type !== 'tool' && segment?.type !== 'system_tool') continue;
+    if (allowed.size === 0 || allowed.has(String(segment.status || ''))) return segment;
+  }
+  return null;
+}
+
+function hasOnlySyntheticNarration(msg) {
+  if (!msg?.syntheticPrelude) return false;
+  const segments = Array.isArray(msg?.segments) ? msg.segments : [];
+  const hasToolRows = segments.some((segment) => segment?.type === 'tool' || segment?.type === 'system_tool');
+  const textSegments = segments.filter((segment) => segment?.type === 'text' && String(segment.text || '').trim());
+  return hasToolRows && textSegments.length <= 1;
+}
+
+export function buildInterToolNotice(previousActivity, nextToolName, copy) {
+  return buildRegisteredInterToolNotice(previousActivity, nextToolName, copy);
+}
+
+export function buildSyntheticCompletionText(msg, copy) {
+  return buildRegisteredSyntheticCompletionText(msg, copy);
+}
+
 function formatDurationMs(ms) {
   const safeMs = Math.max(0, Number(ms) || 0);
   return `${(safeMs / 1000).toFixed(1)}s`;
@@ -818,168 +834,19 @@ export function shouldShowCompletionFooter(msg) {
 }
 
 function describeToolActivity(name, copy, { done = false, blocked = false } = {}) {
-  const parsed = parseToolDisplayName(name);
-  if (parsed.base === 'project_index') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: project index`
-      : done
-        ? copy.toolActivity.doneProjectIndex
-        : copy.toolActivity.doingProjectIndex;
-  }
-  if (parsed.base === 'file_index') {
-    const safeTarget = trimText(parsed.target || '.codemini-project/file-index.json', 72);
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${safeTarget}`
-      : done
-        ? `${copy.toolActivity.doneFileIndex}: ${safeTarget}`
-        : `${copy.toolActivity.doingFileIndex}: ${safeTarget}`;
-  }
-  if (parsed.base === 'run' || parsed.base === 'start_service') {
-    const intent = classifyCommandIntent(parsed.target);
-    const target = parsed.target || intent.kind || 'command';
-    if (intent.kind === 'install') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneInstall}: ${target}`
-          : `${copy.toolActivity.doingInstall}: ${target}`;
-    }
-    if (intent.kind === 'build') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneBuild}: ${target}`
-          : `${copy.toolActivity.doingBuild}: ${target}`;
-    }
-    if (intent.kind === 'test') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneTest}: ${target}`
-          : `${copy.toolActivity.doingTest}: ${target}`;
-    }
-    if (intent.kind === 'frontend-service') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneFrontend}: ${target}`
-          : `${copy.toolActivity.doingFrontend}: ${target}`;
-    }
-    if (intent.kind === 'backend-service') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneBackend}: ${target}`
-          : `${copy.toolActivity.doingBackend}: ${target}`;
-    }
-    if (intent.kind === 'database-service') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneDatabase}: ${target}`
-          : `${copy.toolActivity.doingDatabase}: ${target}`;
-    }
-    if (intent.kind === 'docker-service') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneDocker}: ${target}`
-          : `${copy.toolActivity.doingDocker}: ${target}`;
-    }
-    if (intent.kind === 'service') {
-      return blocked
-        ? `${copy.toolActivity.blocked}: ${target}`
-        : done
-          ? `${copy.toolActivity.doneGeneric}: ${target}`
-          : `${copy.toolActivity.doingGeneric}: ${target}`;
-    }
-  }
-  if (isCodeGenerationActivityName(name)) {
-    return blocked
-      ? `${copy.toolActivity.blocked}: code generation`
-      : done
-        ? copy.toolActivity.doneCodeGeneration
-        : copy.toolActivity.doingCodeGeneration;
-  }
-  const { raw, base, target } = parseToolDisplayName(name);
-  const safeTarget = trimText(target, 72);
-  if (base === 'read') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${base}(${safeTarget || '.'})`
-      : done
-        ? `${copy.toolActivity.doneRead}: ${safeTarget || '.'}`
-        : `${copy.toolActivity.doingRead}: ${safeTarget || '.'}`;
-  }
-  if (base === 'edit') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${base}(${safeTarget || '.'})`
-      : done
-        ? `${copy.toolActivity.doneEdit}: ${safeTarget || '.'}`
-        : `${copy.toolActivity.doingEdit}: ${safeTarget || '.'}`;
-  }
-  if (base === 'write') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${base}(${safeTarget || '.'})`
-      : done
-        ? `${copy.toolActivity.doneWrite}: ${safeTarget || '.'}`
-        : `${copy.toolActivity.doingWrite}: ${safeTarget || '.'}`;
-  }
-  if (base === 'patch') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${base}(${safeTarget || '.'})`
-      : done
-        ? `${copy.toolActivity.donePatch}: ${safeTarget || '.'}`
-        : `${copy.toolActivity.doingPatch}: ${safeTarget || '.'}`;
-  }
-  if (base === 'list' || base === 'glob' || base === 'grep') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${base}(${safeTarget || '.'})`
-      : done
-        ? `${copy.toolActivity.doneList}: ${safeTarget || '.'}`
-        : `${copy.toolActivity.doingList}: ${safeTarget || '.'}`;
-  }
-  if (base === 'run') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${safeTarget || base}`
-      : done
-        ? `${copy.toolActivity.doneCommand}: ${safeTarget || base}`
-        : `${copy.toolActivity.doingCommand}: ${safeTarget || base}`;
-  }
-  if (base === 'start_service' || base === 'list_services' || base === 'get_service_status' || base === 'get_service_logs' || base === 'stop_service') {
-    return blocked
-      ? `${copy.toolActivity.blocked}: ${safeTarget || base}`
-      : done
-        ? `${copy.toolActivity.doneGeneric}: ${safeTarget || base}`
-        : `${copy.toolActivity.doingGeneric}: ${safeTarget || base}`;
-  }
-  if (base === 'create_task') {
-    return blocked ? `${copy.toolActivity.blocked}: create_task` : done ? copy.toolActivity.doneCreateTask : copy.toolActivity.doingCreateTask;
-  }
-  if (base === 'update_task') {
-    return blocked ? `${copy.toolActivity.blocked}: update_task` : done ? copy.toolActivity.doneUpdateTask : copy.toolActivity.doingUpdateTask;
-  }
-  return blocked ? `${copy.toolActivity.blocked}: ${raw}` : done ? `${copy.toolActivity.doneGeneric}: ${raw}` : `${copy.toolActivity.doingGeneric}: ${raw}`;
+  return describeRegisteredToolActivity(copy, name, { done, blocked });
 }
 
 function describeSkillActivity(name, copy, { done = false, failed = false } = {}) {
-  if (failed) return `${copy.runtime.skillFailed}: /${name}`;
-  if (done) return `${copy.toolActivity.doneSkill}: /${name}`;
-  return `${copy.toolActivity.doingSkill}: /${name}`;
+  return describeRegisteredSkillActivity(copy, name, { done, failed });
 }
 
 function describeAutoSkillActivity(names, copy) {
-  const safeNames = Array.isArray(names) ? names.filter(Boolean) : [];
-  if (safeNames.length === 0) return '';
-  return copy.runtime.autoSkillInjected(safeNames);
+  return describeRegisteredAutoSkillActivity(copy, names);
 }
 
 function formatAutoSkillBadge(names, copy) {
-  const safeNames = Array.isArray(names) ? names.filter(Boolean) : [];
-  if (safeNames.length === 0) return '';
-  const [first, ...rest] = safeNames;
-  const suffix = rest.length > 0 ? ` +${rest.length}` : '';
-  const prefix = copy?.roleLabels?.system === 'SYSTEM' ? 'AUTO' : '自动';
-  return `${prefix} /${first}${suffix}`;
+  return formatRegisteredAutoSkillBadge(copy, names);
 }
 
 function normalizeRuntimeStatus(status, copy) {
@@ -2967,6 +2834,26 @@ export function ChatApp({ runtime, sessionId, model, language = 'zh', shellName
     return aid;
   };
 
+  const maybeRefreshSyntheticNarration = (nextToolName) => {
+    const targetId = activeAssistantIdRef.current;
+    if (!targetId || !nextToolName) return;
+    setMessages((prev) =>
+      prev.map((m) => {
+        if (m.id !== targetId) return m;
+        if (!hasOnlySyntheticNarration(m)) return m;
+        const previousActivity = getLastToolActivity(m, ['done', 'running']);
+        if (!previousActivity) return m;
+        const bridge = buildInterToolNotice(previousActivity, nextToolName, copy);
+        if (!bridge) return m;
+        return {
+          ...m,
+          text: bridge,
+          syntheticPrelude: true
+        };
+      })
+    );
+  };
+
   const runSubmission = (line, userMessageId = null) => {
     inFlightRef.current = true;
     activeUserMessageIdRef.current = userMessageId;
@@ -3060,9 +2947,15 @@ export function ChatApp({ runtime, sessionId, model, language = 'zh', shellName
             setMessages((prev) =>
               prev.map((m) => {
                 if (m.id !== targetId) return m;
+                const responseText = typeof event.text === 'string' ? event.text.trim() : '';
+                const shouldSynthesizeCompletion = !responseText && m.syntheticPrelude;
                 return {
                   ...m,
-                  ...(typeof event.text === 'string' && event.text.length > 0 ? { text: event.text } : {}),
+                  ...(responseText
+                    ? { text: event.text, syntheticPrelude: false }
+                    : shouldSynthesizeCompletion
+                      ? { text: buildSyntheticCompletionText(m, copy), syntheticPrelude: false }
+                      : {}),
                   loading: false,
                   phase: undefined,
                   liveStatus: undefined,
@@ -3086,6 +2979,7 @@ export function ChatApp({ runtime, sessionId, model, language = 'zh', shellName
         }
         if (event?.type === 'tool:start') {
           ensureActiveAssistant();
+          maybeRefreshSyntheticNarration(event.name);
           const detail = describeToolActivity(event.name, copy);
           setRuntimeStatus(makeStatus(copy.runtime.toolRunning, detail, 'magentaBright'));
           setInputStage('tooling');

package/src/tui/skill-activity/index.js

@@ -0,0 +1,20 @@
+export function describeSkillActivity(copy, name, { done = false, failed = false } = {}) {
+  if (failed) return `${copy.runtime.skillFailed}: /${name}`;
+  if (done) return `${copy.toolActivity.doneSkill}: /${name}`;
+  return `${copy.toolActivity.doingSkill}: /${name}`;
+}
+
+export function describeAutoSkillActivity(copy, names) {
+  const safeNames = Array.isArray(names) ? names.filter(Boolean) : [];
+  if (safeNames.length === 0) return '';
+  return copy.runtime.autoSkillInjected(safeNames);
+}
+
+export function formatAutoSkillBadge(copy, names) {
+  const safeNames = Array.isArray(names) ? names.filter(Boolean) : [];
+  if (safeNames.length === 0) return '';
+  const [first, ...rest] = safeNames;
+  const suffix = rest.length > 0 ? ` +${rest.length}` : '';
+  const prefix = copy?.roleLabels?.system === 'SYSTEM' ? 'AUTO' : '自动';
+  return `${prefix} /${first}${suffix}`;
+}

package/src/tui/tool-activity/common.js

@@ -0,0 +1,29 @@
+import { classifyCommandIntent } from '../../core/shell.js';
+
+export function parseToolDisplayName(name) {
+  const raw = String(name || '').trim();
+  const match = raw.match(/^([^(]+)\((.*)\)$/);
+  return {
+    raw,
+    base: match ? match[1] : raw,
+    target: match ? match[2] : ''
+  };
+}
+
+export function trimText(text, max = 72) {
+  const value = String(text || '').trim();
+  if (!value) return '';
+  return value.length > max ? `${value.slice(0, Math.max(0, max - 3)).trimEnd()}...` : value;
+}
+
+export function makeBlocked(copy, target) {
+  return `${copy.toolActivity.blocked}: ${target}`;
+}
+
+export function makePhase(copy, doneLabel, doingLabel, target) {
+  return target ? `${doneLabel}: ${target}` : doneLabel || doingLabel;
+}
+
+export function classifyRunIntent(target) {
+  return classifyCommandIntent(target);
+}

package/src/tui/tool-activity/index.js

@@ -0,0 +1,17 @@
+import { parseToolDisplayName } from './common.js';
+import { describeCommandToolActivity } from './presenters/command.js';
+import { describeFileToolActivity } from './presenters/files.js';
+import { describeMiscToolActivity } from './presenters/misc.js';
+import { describeSystemToolActivity } from './presenters/system.js';
+
+export { isCodeGenerationActivityName } from './presenters/misc.js';
+
+export function describeToolActivity(copy, name, options = {}) {
+  const parsed = parseToolDisplayName(name);
+  return (
+    describeSystemToolActivity(copy, parsed, options) ||
+    describeCommandToolActivity(copy, parsed, options) ||
+    describeFileToolActivity(copy, parsed, options) ||
+    describeMiscToolActivity(copy, parsed, name, options)
+  );
+}

package/src/tui/tool-activity/presenters/command.js

@@ -0,0 +1,29 @@
+import { classifyRunIntent, makeBlocked, trimText } from '../common.js';
+
+function phaseText(copy, blocked, done, target, doingLabel, doneLabel) {
+  if (blocked) return makeBlocked(copy, target);
+  return done ? `${doneLabel}: ${target}` : `${doingLabel}: ${target}`;
+}
+
+export function describeCommandToolActivity(copy, parsed, { done = false, blocked = false } = {}) {
+  const target = parsed.target || 'command';
+  const intent = classifyRunIntent(parsed.target);
+
+  if (parsed.base === 'run' || parsed.base === 'start_service') {
+    if (intent.kind === 'install') return phaseText(copy, blocked, done, target, copy.toolActivity.doingInstall, copy.toolActivity.doneInstall);
+    if (intent.kind === 'build') return phaseText(copy, blocked, done, target, copy.toolActivity.doingBuild, copy.toolActivity.doneBuild);
+    if (intent.kind === 'test') return phaseText(copy, blocked, done, target, copy.toolActivity.doingTest, copy.toolActivity.doneTest);
+    if (intent.kind === 'frontend-service') return phaseText(copy, blocked, done, target, copy.toolActivity.doingFrontend, copy.toolActivity.doneFrontend);
+    if (intent.kind === 'backend-service') return phaseText(copy, blocked, done, target, copy.toolActivity.doingBackend, copy.toolActivity.doneBackend);
+    if (intent.kind === 'database-service') return phaseText(copy, blocked, done, target, copy.toolActivity.doingDatabase, copy.toolActivity.doneDatabase);
+    if (intent.kind === 'docker-service') return phaseText(copy, blocked, done, target, copy.toolActivity.doingDocker, copy.toolActivity.doneDocker);
+    if (intent.kind === 'service') return phaseText(copy, blocked, done, target, copy.toolActivity.doingGeneric, copy.toolActivity.doneGeneric);
+    if (parsed.base === 'run') return phaseText(copy, blocked, done, trimText(target, 72) || parsed.base, copy.toolActivity.doingCommand, copy.toolActivity.doneCommand);
+  }
+
+  if (parsed.base === 'start_service' || parsed.base === 'list_services' || parsed.base === 'get_service_status' || parsed.base === 'get_service_logs' || parsed.base === 'stop_service') {
+    return phaseText(copy, blocked, done, trimText(parsed.target, 72) || parsed.base, copy.toolActivity.doingGeneric, copy.toolActivity.doneGeneric);
+  }
+
+  return '';
+}

package/src/tui/tool-activity/presenters/files.js

@@ -0,0 +1,26 @@
+import { makeBlocked, trimText } from '../common.js';
+
+function describePathTool(copy, parsed, labels, { done = false, blocked = false } = {}) {
+  const safeTarget = trimText(parsed.target, 72) || '.';
+  if (blocked) return makeBlocked(copy, `${parsed.base}(${safeTarget})`);
+  return done ? `${labels.done}: ${safeTarget}` : `${labels.doing}: ${safeTarget}`;
+}
+
+export function describeFileToolActivity(copy, parsed, options = {}) {
+  if (parsed.base === 'read') {
+    return describePathTool(copy, parsed, { done: copy.toolActivity.doneRead, doing: copy.toolActivity.doingRead }, options);
+  }
+  if (parsed.base === 'edit') {
+    return describePathTool(copy, parsed, { done: copy.toolActivity.doneEdit, doing: copy.toolActivity.doingEdit }, options);
+  }
+  if (parsed.base === 'write') {
+    return describePathTool(copy, parsed, { done: copy.toolActivity.doneWrite, doing: copy.toolActivity.doingWrite }, options);
+  }
+  if (parsed.base === 'patch') {
+    return describePathTool(copy, parsed, { done: copy.toolActivity.donePatch, doing: copy.toolActivity.doingPatch }, options);
+  }
+  if (parsed.base === 'list' || parsed.base === 'glob' || parsed.base === 'grep') {
+    return describePathTool(copy, parsed, { done: copy.toolActivity.doneList, doing: copy.toolActivity.doingList }, options);
+  }
+  return '';
+}

package/src/tui/tool-activity/presenters/misc.js

@@ -0,0 +1,19 @@
+import { makeBlocked } from '../common.js';
+
+export function isCodeGenerationActivityName(name) {
+  return String(name || '').trim() === 'Code generation';
+}
+
+export function describeMiscToolActivity(copy, parsed, rawName, { done = false, blocked = false } = {}) {
+  if (isCodeGenerationActivityName(rawName)) {
+    if (blocked) return `${copy.toolActivity.blocked}: code generation`;
+    return done ? copy.toolActivity.doneCodeGeneration : copy.toolActivity.doingCodeGeneration;
+  }
+  if (parsed.base === 'create_task') {
+    return blocked ? makeBlocked(copy, 'create_task') : done ? copy.toolActivity.doneCreateTask : copy.toolActivity.doingCreateTask;
+  }
+  if (parsed.base === 'update_task') {
+    return blocked ? makeBlocked(copy, 'update_task') : done ? copy.toolActivity.doneUpdateTask : copy.toolActivity.doingUpdateTask;
+  }
+  return blocked ? `${copy.toolActivity.blocked}: ${parsed.raw}` : done ? `${copy.toolActivity.doneGeneric}: ${parsed.raw}` : `${copy.toolActivity.doingGeneric}: ${parsed.raw}`;
+}

package/src/tui/tool-activity/presenters/system.js

@@ -0,0 +1,14 @@
+import { makeBlocked, trimText } from '../common.js';
+
+export function describeSystemToolActivity(copy, parsed, { done = false, blocked = false } = {}) {
+  if (parsed.base === 'project_index') {
+    if (blocked) return `${copy.toolActivity.blocked}: project index`;
+    return done ? copy.toolActivity.doneProjectIndex : copy.toolActivity.doingProjectIndex;
+  }
+  if (parsed.base === 'file_index') {
+    const safeTarget = trimText(parsed.target || '.codemini-project/file-index.json', 72);
+    if (blocked) return makeBlocked(copy, safeTarget);
+    return done ? `${copy.toolActivity.doneFileIndex}: ${safeTarget}` : `${copy.toolActivity.doingFileIndex}: ${safeTarget}`;
+  }
+  return '';
+}

package/src/tui/tool-narration/common.js

@@ -0,0 +1,37 @@
+export function trimText(text, max = 48) {
+  const value = String(text || '').trim();
+  if (!value) return '';
+  return value.length > max ? `${value.slice(0, Math.max(0, max - 3)).trimEnd()}...` : value;
+}
+
+export function parseToolDisplayName(name) {
+  const raw = String(name || '').trim();
+  const match = raw.match(/^([^(]+)\((.*)\)$/);
+  return {
+    raw,
+    base: match ? match[1] : raw,
+    target: match ? match[2] : ''
+  };
+}
+
+export function isEnglishCopy(copy) {
+  return String(copy?.roleLabels?.coder || '').trim() === 'CODER' && String(copy?.roleLabels?.you || '').trim() === 'YOU';
+}
+
+export function renderLocalizedEntry(entry, copy, context) {
+  if (!entry) return '';
+  const locale = isEnglishCopy(copy) ? 'en' : 'zh';
+  const renderer = entry[locale];
+  return typeof renderer === 'function' ? renderer(context) : '';
+}
+
+export function getLastToolActivity(msg, statuses = []) {
+  const allowed = new Set((Array.isArray(statuses) ? statuses : []).map((status) => String(status)));
+  const segments = Array.isArray(msg?.segments) ? msg.segments : [];
+  for (let idx = segments.length - 1; idx >= 0; idx -= 1) {
+    const segment = segments[idx];
+    if (segment?.type !== 'tool' && segment?.type !== 'system_tool') continue;
+    if (allowed.size === 0 || allowed.has(String(segment.status || ''))) return segment;
+  }
+  return null;
+}

package/src/tui/tool-narration/presenters/change.js

@@ -0,0 +1,109 @@
+function buildPreludeEntry() {
+  return {
+    en: ({ changeKind, target, verb }) => {
+      if (changeKind === 'readme') return `I'll inspect the project structure first, then write the README.`;
+      if (changeKind === 'doc') return `I'll inspect the existing context first, then update the document.`;
+      if (target) return `I'll inspect ${target} first, then ${verb} it.`;
+      return `I'll inspect the current code first, then make the change.`;
+    },
+    zh: ({ changeKind, target, verbZh }) => {
+      if (changeKind === 'readme') return '我先看一下项目内容和结构，再开始写 README。';
+      if (changeKind === 'doc') return '我先看一下现有内容，再开始整理这份文档。';
+      if (target) return `我先看一下 ${target} 的上下文，再开始${verbZh}。`;
+      return '我先确认当前代码上下文，再动手修改。';
+    }
+  };
+}
+
+function buildCompletionEntry() {
+  return {
+    en: ({ changeKind, target }) => {
+      if (changeKind === 'readme') return 'The README is in place. If you want, I can also add a quick start, feature summary, or usage example.';
+      if (changeKind === 'doc') return 'The document is updated. If you want, I can also polish the wording, structure, or add an example section.';
+      if (changeKind === 'test') {
+        return target
+          ? `${target} is ready. If you want, I can keep going with verification, more test coverage, or a quick review of edge cases.`
+          : 'That test-related change is ready. If you want, I can keep going with verification or edge-case review.';
+      }
+      return target
+        ? `${target} is ready. If you want, I can also add tests, update docs, or do a quick edge-case pass.`
+        : 'That part is ready. If you want, I can also add tests, update docs, or do a quick edge-case pass.';
+    },
+    zh: ({ changeKind, target }) => {
+      if (changeKind === 'readme') return 'README 已经写好了。要不要我顺手再补一个快速开始、功能概览，或者使用示例？';
+      if (changeKind === 'doc') return '文档已经更新好了。要不要我继续顺一下语气、结构，或者补一段示例？';
+      if (changeKind === 'test') {
+        return target
+          ? `${target} 已经处理好了。要不要我继续补验证、扩一下测试覆盖，或者再过一遍边界情况？`
+          : '这部分测试相关修改已经处理好了。要不要我继续补验证，或者再过一遍边界情况？';
+      }
+      return target
+        ? `${target} 已经处理好了。要不要我继续补测试、更新文档，或者再检查一遍边界情况？`
+        : '这部分已经处理好了。要不要我继续补测试、更新文档，或者再检查一遍边界情况？';
+    }
+  };
+}
+
+function buildBridgeEntry() {
+  return {
+    en: ({ changeKind, nextTarget, verb, hasContext }) => {
+      if (changeKind === 'readme') return hasContext ? 'I have enough context now, so I can write the README.' : 'I can write the README next.';
+      if (changeKind === 'doc') return hasContext ? 'I have enough context now, so I can update the document.' : 'I can update the document next.';
+      if (nextTarget) return hasContext ? `I have enough context now, so I'll ${verb} ${nextTarget}.` : `I'll ${verb} ${nextTarget} next.`;
+      return hasContext ? 'I have enough context now, so I can make the change.' : 'I can make the change next.';
+    },
+    zh: ({ changeKind, nextTarget, verbZh, hasContext }) => {
+      if (changeKind === 'readme') return hasContext ? '相关内容我已经看过了，现在开始写 README。' : '现在开始写 README。';
+      if (changeKind === 'doc') return hasContext ? '需要的上下文我已经看过了，现在开始整理这份文档。' : '现在开始整理这份文档。';
+      if (nextTarget) return hasContext ? `需要的上下文我已经看过了，现在${verbZh} ${nextTarget}。` : `现在${verbZh} ${nextTarget}。`;
+      return hasContext ? '需要的上下文我已经看过了，现在开始修改。' : '现在开始修改。';
+    }
+  };
+}
+
+export function inferChangeKind(target) {
+  const lowerTarget = String(target || '').toLowerCase();
+  if (lowerTarget.includes('readme')) return 'readme';
+  if (lowerTarget.endsWith('.md')) return 'doc';
+  if (/test|spec/i.test(lowerTarget)) return 'test';
+  return 'generic';
+}
+
+export function createChangePresenter({ verb, verbZh }) {
+  return {
+    prelude: buildPreludeEntry(),
+    completion: buildCompletionEntry(),
+    bridges: {
+      inspect: buildBridgeEntry(),
+      search: {
+        en: ({ changeKind, nextTarget, verb }) => {
+          if (changeKind === 'readme') return 'I found what I needed, so I can write the README.';
+          if (changeKind === 'doc') return 'I found what I needed, so I can update the document.';
+          if (nextTarget) return `I found the right spot, so I'll ${verb} ${nextTarget}.`;
+          return 'I found the right spot, so I can make the change.';
+        },
+        zh: ({ changeKind, nextTarget, verbZh }) => {
+          if (changeKind === 'readme') return '相关位置我已经找到了，现在开始写 README。';
+          if (changeKind === 'doc') return '相关位置我已经找到了，现在开始整理这份文档。';
+          if (nextTarget) return `相关位置我已经找到了，现在${verbZh} ${nextTarget}。`;
+          return '相关位置我已经找到了，现在开始修改。';
+        }
+      },
+      run: {
+        en: ({ changeKind, nextTarget, verb }) => {
+          if (changeKind === 'readme') return 'I have the result I needed, so I can write the README next.';
+          if (changeKind === 'doc') return 'I have the result I needed, so I can update the document next.';
+          if (nextTarget) return `I have the result I needed, so I'll ${verb} ${nextTarget}.`;
+          return 'I have the result I needed, so I can make the follow-up change.';
+        },
+        zh: ({ changeKind, nextTarget, verbZh }) => {
+          if (changeKind === 'readme') return '结果我已经拿到了，现在开始写 README。';
+          if (changeKind === 'doc') return '结果我已经拿到了，现在开始整理这份文档。';
+          if (nextTarget) return `结果我已经拿到了，现在${verbZh} ${nextTarget}。`;
+          return '结果我已经拿到了，现在继续做后续修改。';
+        }
+      }
+    },
+    meta: { verb, verbZh }
+  };
+}

package/src/tui/tool-narration/presenters/edit.js

@@ -0,0 +1,3 @@
+import { createChangePresenter } from './change.js';
+
+export const editPresenter = createChangePresenter({ verb: 'update', verbZh: '修改' });

package/src/tui/tool-narration/presenters/generic.js

@@ -0,0 +1,10 @@
+export const genericPresenter = {
+  prelude: {
+    en: () => `I'll check the relevant project context first.`,
+    zh: () => '我先查看相关上下文。'
+  },
+  completion: {
+    en: () => 'The requested work is done. If you want, I can keep going with tests, docs, or a quick review.',
+    zh: () => '这部分已经处理好了。你要是愿意，我可以继续补测试、文档，或者再帮你快速检查一遍。'
+  }
+};

package/src/tui/tool-narration/presenters/glob.js

@@ -0,0 +1,11 @@
+export const globPresenter = {
+  prelude: {
+    en: ({ target }) => (target ? `I'll inspect the ${target} directory first.` : 'I\'ll inspect the relevant directory first.'),
+    zh: ({ target }) => (target ? `我先查看 ${target} 目录里的内容。` : '我先查看相关目录内容。')
+  },
+  completion: {
+    en: () => 'I have the relevant context now. Do you want me to make the change next, or summarize the findings first?',
+    zh: () => '相关上下文我已经看完了。接下来你要我直接动手改，还是先把结论整理给你？'
+  },
+  meta: { bridgeGroup: 'inspect' }
+};

package/src/tui/tool-narration/presenters/grep.js

@@ -0,0 +1,11 @@
+export const grepPresenter = {
+  prelude: {
+    en: () => `I'll search the relevant code first.`,
+    zh: () => '我先搜索相关代码位置。'
+  },
+  completion: {
+    en: () => 'I found the relevant spots. Do you want me to make the change next, or summarize the findings first?',
+    zh: () => '相关位置我已经找到了。接下来你要我直接动手改，还是先把结论整理给你？'
+  },
+  meta: { bridgeGroup: 'search' }
+};

package/src/tui/tool-narration/presenters/list.js

@@ -0,0 +1,11 @@
+export const listPresenter = {
+  prelude: {
+    en: ({ target }) => (target ? `I'll inspect the ${target} directory first.` : 'I\'ll inspect the relevant directory first.'),
+    zh: ({ target }) => (target ? `我先查看 ${target} 目录里的内容。` : '我先查看相关目录内容。')
+  },
+  completion: {
+    en: () => 'I have the relevant context now. Do you want me to make the change next, or summarize the findings first?',
+    zh: () => '相关上下文我已经看完了。接下来你要我直接动手改，还是先把结论整理给你？'
+  },
+  meta: { bridgeGroup: 'inspect' }
+};

package/src/tui/tool-narration/presenters/patch.js

@@ -0,0 +1,3 @@
+import { createChangePresenter } from './change.js';
+
+export const patchPresenter = createChangePresenter({ verb: 'patch', verbZh: '修改' });

package/src/tui/tool-narration/presenters/read.js

@@ -0,0 +1,11 @@
+export const readPresenter = {
+  prelude: {
+    en: ({ target }) => (target ? `I'll inspect ${target} first.` : 'I\'ll inspect the relevant file first.'),
+    zh: ({ target }) => (target ? `我先查看 ${target} 的内容。` : '我先查看相关文件内容。')
+  },
+  completion: {
+    en: () => 'I have the relevant context now. Do you want me to make the change next, or summarize the findings first?',
+    zh: () => '相关上下文我已经看完了。接下来你要我直接动手改，还是先把结论整理给你？'
+  },
+  meta: { bridgeGroup: 'inspect' }
+};

package/src/tui/tool-narration/presenters/run.js

@@ -0,0 +1,29 @@
+export const runPresenter = {
+  prelude: {
+    en: () => `I'll verify the current project state first.`,
+    zh: () => '我先检查当前项目状态。'
+  },
+  completion: {
+    en: () => 'That step is finished. Do you want me to act on the result next, or summarize what it means first?',
+    zh: () => '这一步已经跑完了。接下来要我根据结果继续处理，还是先把结论整理给你？'
+  },
+  bridges: {
+    'generic-change': {
+      en: () => 'I have the result I needed, so I can make the follow-up change.',
+      zh: () => '结果我已经拿到了，现在继续做后续修改。'
+    },
+    'doc-change': {
+      en: () => 'I have the result I needed, so I can make the follow-up change.',
+      zh: () => '结果我已经拿到了，现在继续做后续修改。'
+    },
+    'readme-change': {
+      en: () => 'I have the result I needed, so I can make the follow-up change.',
+      zh: () => '结果我已经拿到了，现在继续做后续修改。'
+    },
+    'test-change': {
+      en: () => 'I have the result I needed, so I can make the follow-up change.',
+      zh: () => '结果我已经拿到了，现在继续做后续修改。'
+    }
+  },
+  meta: { bridgeGroup: 'run' }
+};

package/src/tui/tool-narration/presenters/write.js

@@ -0,0 +1,3 @@
+import { createChangePresenter } from './change.js';
+
+export const writePresenter = createChangePresenter({ verb: 'write', verbZh: '写' });

package/src/tui/tool-narration.js

@@ -0,0 +1,67 @@
+import { getLastToolActivity, parseToolDisplayName, renderLocalizedEntry, trimText } from './tool-narration/common.js';
+import { inferChangeKind } from './tool-narration/presenters/change.js';
+import { editPresenter } from './tool-narration/presenters/edit.js';
+import { genericPresenter } from './tool-narration/presenters/generic.js';
+import { globPresenter } from './tool-narration/presenters/glob.js';
+import { grepPresenter } from './tool-narration/presenters/grep.js';
+import { listPresenter } from './tool-narration/presenters/list.js';
+import { patchPresenter } from './tool-narration/presenters/patch.js';
+import { readPresenter } from './tool-narration/presenters/read.js';
+import { runPresenter } from './tool-narration/presenters/run.js';
+import { writePresenter } from './tool-narration/presenters/write.js';
+
+const BASE_PRESENTERS = {
+  read: readPresenter,
+  list: listPresenter,
+  glob: globPresenter,
+  grep: grepPresenter,
+  write: writePresenter,
+  edit: editPresenter,
+  patch: patchPresenter,
+  generate_diff: patchPresenter,
+  run: runPresenter
+};
+
+function resolveNarrationContext(name) {
+  const { base, target } = parseToolDisplayName(name);
+  const presenter = BASE_PRESENTERS[base] || genericPresenter;
+  const changeKind = inferChangeKind(target);
+  return {
+    base,
+    target: trimText(target, 48),
+    presenter,
+    bridgeGroup: presenter?.meta?.bridgeGroup || 'generic',
+    verb: presenter?.meta?.verb || 'update',
+    verbZh: presenter?.meta?.verbZh || '修改',
+    changeKind
+  };
+}
+
+export function buildPreToolNotice(name, copy) {
+  const context = resolveNarrationContext(name);
+  return renderLocalizedEntry(context.presenter.prelude, copy, context);
+}
+
+export function buildInterToolNotice(previousActivity, nextToolName, copy) {
+  const previousContext = resolveNarrationContext(previousActivity?.name);
+  const nextContext = resolveNarrationContext(nextToolName);
+  const bridge = nextContext.presenter?.bridges?.[previousContext.bridgeGroup];
+  return renderLocalizedEntry(bridge, copy, {
+    ...nextContext,
+    nextTarget: nextContext.target,
+    hasContext: previousContext.bridgeGroup !== 'generic'
+  });
+}
+
+export function buildSyntheticCompletionText(msg, copy) {
+  const activity = getLastToolActivity(msg, ['done', 'running']);
+  if (!activity) {
+    return renderLocalizedEntry(genericPresenter.completion, copy, {});
+  }
+
+  const context = resolveNarrationContext(activity.name);
+  return renderLocalizedEntry(context.presenter.completion, copy, {
+    ...context,
+    target: trimText(context.target, 56)
+  });
+}