@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/interface/list-component.ts

@@ -14,6 +14,7 @@ import { visibleWidth } from "@earendil-works/pi-tui";
 import { computeElapsedSeconds } from "../execution/execution-record.ts";
 import type { SubagentService } from "../execution/subagent-service.ts";
 import type { SubagentRecord } from "../execution/types.ts";
+import { displayAgentName } from "../shared/agent-ref.ts";
 import {
   firstLine,
   formatDisplayItem,
@@ -76,6 +77,15 @@ const DETAIL_LEN_PROBE_WIDTH = 9999;
 const VERT_CENTER_DIVISOR = 2;
 /** spinner 帧切换粒度（与 Date.now() 配合选帧）。 */
 const SPINNER_FRAME_MS = 250;
+/**
+ * [perf] 同帧 records 共享窗口（swf-perf-impl cleanup TC3/IF3/DM5）。
+ * 250ms 动画帧内 hasRunning 与 buildLines（含 detail 路径 children 计算）各自
+ * collectRecords(LIST_LIMIT) 全量合并扫描（内存 running + 磁盘 light 重建）——帧内合一。
+ * 取值 50：须 < store 事件 debounce 120ms（事件驱动渲染大概率 TTL 已过走新鲜扫描）
+ * 且 > 同 tick 内 hasRunning→render 微秒级间隔（命中复用）。最坏滞后 = 渲染合帧场景下
+ * 50ms 内旧快照一帧，下一 animTimer tick / 事件渲染自愈，对 250ms 动画无感知差异。
+ */
+const FRAME_TTL_MS = 50;
 /** 顶框嵌入标题（分屏模式）。 */
 const TITLE_SPLIT = "Subagents";
 /** 分屏分区线左/右嵌入标题。 */
@@ -85,7 +95,8 @@ const TITLE_RIGHT = "Detail";
 /**
  * 全屏带框左右分屏 list 组件。
  *
- * 不缓存行（records 每次 render 都从 service.collectRecords 拉最新——保证 store 变化后刷新）。
+ * 不缓存行（render 每次重建；records 经 collectRecordsFrame 帧缓存拉取——TTL 50ms 内
+ * 同帧共享一份，保证 store 变化后刷新由 TTL/事件 debounce 兜底，见 FRAME_TTL_MS）。
  * 缓存的是「上次 render 的 width×rows」（用于 invalidate 后强制重建）。
  */
 export class SubagentsListComponent implements Component {
@@ -94,6 +105,9 @@ export class SubagentsListComponent implements Component {
   private closeFn: () => void = () => {};
   /** 动画 timer 句柄（dispose 兜底清理）。 */
   private animTimer: ReturnType<typeof setInterval> | undefined;
+  /** [perf] 帧缓存：TTL 内复用同一份 records（collectRecordsFrame，TC3/IF3/DM5）。 */
+  private frameRecords: SubagentRecord[] | undefined;
+  private frameAt = 0;
 
   constructor(
     private readonly service: SubagentService,
@@ -117,7 +131,29 @@ export class SubagentsListComponent implements Component {
 
   /** 是否有 running record（动画 timer 据此决定是否刷新）。 */
   hasRunning(): boolean {
-    return this.service.collectRecords(LIST_LIMIT).some((r) => r.status === "running");
+    return this.collectRecordsFrame().some((r) => r.status === "running");
+  }
+
+  /**
+   * [perf] 帧缓存读取（TC3/IF3/DM5）：TTL（FRAME_TTL_MS=50ms）内复用同一份 records，
+   * 过期/未缓存则调 service.collectRecords 刷新 {frameRecords, frameAt}。
+   * hasRunning / handleInput / buildLines / buildDetailContent(children) 四个消费点统一走这里。
+   * invalidate() 刻意不清帧缓存：invalidate 在 timer 序列（hasRunning→invalidate→requestRender）
+   * 的共享路径中间，清了共享即失效；新鲜度由 TTL 独立保证 + animTimer 250ms tick 双重兜底。
+   */
+  private collectRecordsFrame(): SubagentRecord[] {
+    if (this.frameRecords !== undefined && Date.now() - this.frameAt <= FRAME_TTL_MS) {
+      return this.frameRecords;
+    }
+    const records = this.service.collectRecords(LIST_LIMIT);
+    this.frameRecords = records;
+    this.frameAt = Date.now();
+    return records;
+  }
+
+  /** [perf] 选中项详情数据：优先全量（懒加载 + per-file 缓存），拿不到回退 light。 */
+  private fullRecordOf(r: SubagentRecord): SubagentRecord {
+    return this.service.getFullRecord(r.id) ?? r;
   }
 
   invalidate(): void {
@@ -138,16 +174,17 @@ export class SubagentsListComponent implements Component {
   handleInput(data: string): void {
     if (this.state.disposed) return;
 
-    const records = applyFilter(this.service.collectRecords(LIST_LIMIT), this.state.filterText);
+    const records = applyFilter(this.collectRecordsFrame(), this.state.filterText);
     const selected = records[this.state.selectedIdx] ?? null;
     // 详情翻屏上下文：视口高 = 右侧 body 高（内框高 - SPLIT_FIXED_LINES），
     // contentLines = 详情内容总行数（含元数据/段头/eventLog/result/error，单一数据源）。
     // 与 renderRightDetail 的 viewH + max 计算保持一致。
+    // [perf] 详情长度需重数据：选中项懒加载全量（带缓存）。
     const innerRows = Math.max(MIN_INNER_ROWS, this.termRows() - PAD_ROWS);
     const bodyH = Math.max(1, innerRows - SPLIT_FIXED_LINES);
     const detailCtx: DetailKeyContext = {
       viewportHeight: bodyH,
-      contentLines: selected ? this.detailContentLength(selected) : 0,
+      contentLines: selected ? this.detailContentLength(this.fullRecordOf(selected)) : 0,
     };
 
     const result = this.keyHandler(data, records, this.state, selected, this.service, detailCtx, this.notify);
@@ -192,7 +229,7 @@ export class SubagentsListComponent implements Component {
     const innerWidth = Math.max(MIN_INNER_WIDTH, width - PAD_COLS);
     const innerRows = Math.max(MIN_INNER_ROWS, rows - PAD_ROWS);
 
-    const allRecords = this.service.collectRecords(LIST_LIMIT);
+    const allRecords = this.collectRecordsFrame();
     const records = applyFilter(allRecords, this.state.filterText);
 
     // 先在内框尺寸下生成框行
@@ -302,9 +339,12 @@ export class SubagentsListComponent implements Component {
 
     const selected = records[this.state.selectedIdx] ?? null;
     const inDetail = this.state.detailMode; // 阶段 2：右侧滚动焦点
+    // [perf] 预览/详情需重数据（displayItems/turns/tokens/result）：选中项按需全量加载
+    // （per-file 缓存，stat 校验）；列表其余行保持 light（identity+状态），列表扫描不开销全量解析。
+    const selectedFull = selected ? this.fullRecordOf(selected) : null;
     // 预构建详情内容（inDetail 时）：分区线标题(detailScrollInfo 算长度)与右列(renderRightDetail 渲染)
     // 共用同一份，避免每帧双倍构建（animTimer 250ms 触发，长 eventLog 下有感）。
-    const detailContent = inDetail && selected ? this.buildDetailContent(selected, rightWidth) : null;
+    const detailContent = inDetail && selectedFull ? this.buildDetailContent(selectedFull, rightWidth) : null;
 
     const lines: string[] = [];
 
@@ -313,7 +353,7 @@ export class SubagentsListComponent implements Component {
 
     // filter 行（阶段 2 时隐藏 filter 提示，显示锚定提示）
     const filterLine = inDetail
-      ? t.fg("dim", `Pinned: ${selected?.agent ?? ""} · Esc to return to list`)
+      ? t.fg("dim", `Pinned: ${selected?.agent ? displayAgentName(selected.agent) : ""} · Esc to return to list`)
       : (this.state.filterText
         ? `${t.fg("dim", "filter: ")}${t.bold(this.state.filterText)}${t.fg("accent", "_")}`
         : `${t.fg("dim", "filter: ")}${t.fg("accent", "_")}`);
@@ -322,7 +362,7 @@ export class SubagentsListComponent implements Component {
     // 分区线（嵌入左/右标题，分段着色）
     const leftTitleStyled = t.fg("accent", t.bold(` ${TITLE_LEFT} `));
     const rightTitleStyled = inDetail
-      ? t.fg("accent", t.bold(` ${TITLE_RIGHT}${this.detailScrollInfo(selected, bodyH, detailContent?.length)} `))
+      ? t.fg("accent", t.bold(` ${TITLE_RIGHT}${this.detailScrollInfo(selectedFull, bodyH, detailContent?.length)} `))
       : t.fg("accent", t.bold(` ${TITLE_RIGHT} `));
     lines.push(
       this.b("├") + segFillColored(leftTitleStyled, this.dash(), leftWidth)
@@ -346,8 +386,8 @@ export class SubagentsListComponent implements Component {
       ));
       leftLines = this.renderLeftColumn(records, leftWidth, leftStart, bodyH);
       rightLines = inDetail
-        ? this.renderRightDetail(selected, rightWidth, bodyH, detailContent)
-        : this.renderRightPreview(selected, rightWidth, bodyH);
+        ? this.renderRightDetail(selectedFull, rightWidth, bodyH, detailContent)
+        : this.renderRightPreview(selectedFull, rightWidth, bodyH);
     }
     const bodyRows = Math.max(leftLines.length, rightLines.length, bodyH);
     for (let i = 0; i < bodyRows; i++) {
@@ -421,7 +461,7 @@ export class SubagentsListComponent implements Component {
       const depthTag = r.depth > 0 ? ` ${t.fg("dim", `[L${r.depth + 1}]`)}` : "";
       // slug 非空时在 agent 后展示（accent 色），空串时省略。
       const slugTag = r.slug ? ` ${t.fg("accent", r.slug)}` : "";
-      const label = `${iconStr} ${sid}${depthTag} ${r.agent}${slugTag} ${t.fg("dim", modeTag)} ${t.fg("dim", dur)}`;
+      const label = `${iconStr} ${sid}${depthTag} ${displayAgentName(r.agent)}${slugTag} ${t.fg("dim", modeTag)} ${t.fg("dim", dur)}`;
       // 阶段 2：锚定行 accent + ▶；其余行 dim。阶段 1：选中 accent + →，其余正常。
       const content = inDetail
         ? (selected ? t.fg("accent", label) : t.fg("dim", label))
@@ -449,7 +489,7 @@ export class SubagentsListComponent implements Component {
         lines.push("");
       }
     }
-    lines.push(truncLine(`${t.bold(record.agent)} ${t.fg("dim", `· ${record.model}`)}`, width));
+    lines.push(truncLine(`${t.bold(displayAgentName(record.agent))} ${t.fg("dim", `· ${record.model}`)}`, width));
     lines.push(truncLine(
       t.fg("dim", `${record.status} · ${record.turns} turns · ${formatTokens(record.totalTokens)} · ${formatElapsedSeconds(elapsedSec(record))}`),
       width,
@@ -550,8 +590,7 @@ export class SubagentsListComponent implements Component {
     // parent 不需外部数据；children 需查同 session 的 record（collectRecords 有磁盘缓存，开销可接受）。
     const parentLabel = record.parentRecordId ? shortId(record.parentRecordId) : "(root)";
     content.push(truncLine(t.fg("dim", `parent: ${parentLabel}`), width));
-    const childIds = this.service
-      .collectRecords(LIST_LIMIT)
+    const childIds = this.collectRecordsFrame()
       .filter((r) => r.parentRecordId === record.id)
       .map((r) => shortId(r.id));
     content.push(truncLine(

package/src/interface/subagent-actions.ts

@@ -18,12 +18,19 @@ import {
 
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { computeElapsedSeconds } from "../execution/execution-record.ts";
+import { isResumable } from "../execution/lifecycle-predicates.ts";
+import type { ExecutionRecord } from "../execution/types.ts";
 import type { ModelInfo } from "../execution/model-resolver.ts";
 import type { SubagentService } from "../execution/subagent-service.ts";
+import { displayAgentName } from "../shared/agent-ref.ts";
 import type {
   BgResponse,
   CancelResponse,
+  CloseResponse,
+  ExecutionStatus,
+  ExternalState,
   ListResponse,
+  MessageResponse,
   SubagentListItem,
   SubagentRecord,
   SubagentToolResult,
@@ -70,6 +77,10 @@ export interface StartHandlerInput {
   worktree?: boolean;
   /** 覆盖子 agent 工作目录（默认 mainCwd）。 */
   cwd?: string;
+  /** 可持续对话模式（true = chatMode，轮次完成进 idle 等续聊）。 */
+  conversation?: boolean;
+  /** 空闲超时毫秒数（仅 conversation 模式有意义，覆盖默认 5min）。 */
+  idleTimeoutMs?: number;
 }
 
 /** start 领域对象（adapter 包成 bgResponse）。 */
@@ -114,18 +125,53 @@ export interface CancelHandlerResult {
  * 不新增 sessionId 到 ExecutionRecord（YAGNI，修跨 session 清理是独立问题）。
  */
 
-/** SubagentRecord → SubagentListItem（8 字段，duration 实时计算）。 */
-function recordToListItem(r: SubagentRecord): SubagentListItem {
+/** exhaustiveness 兜底：default 分支把 status 收敛为 never，ExecutionStatus 加态时 tsc 报错。 */
+function assertNever(value: never): string {
+  return String(value);
+}
+
+/**
+ * 内部 ExecutionStatus → 对外 state 映射（设计决策 10 细则 3）。
+ * v4 B-1 两态收敛后的真实映射只有两条：
+ *   running → active / closed → ended（closed 统一终态，含 cancelled）
+ * ExternalState 仍声明 waiting/error 四态联合（对外契约不变），但当前状态机不产生
+ * 这两个值——它们是历史多态映射（idle→waiting / failed+crashed→error）的遗留声明。
+ * 未来内部加态必须扩展此处，漏加会在 default 分支编译报错（而非静默返回 undefined
+ * 让 state 字段以无主值进入 listResponse JSON）。
+ */
+export function mapExternalState(status: ExecutionStatus): ExternalState {
+  switch (status) {
+    case "running":
+      return "active";
+    case "closed":
+      // v4 B-1: closed 统一终态（含 cancelled）。对外映射为 ended。
+      return "ended";
+    default:
+      throw new Error(`mapExternalState: unhandled ExecutionStatus ${assertNever(status)}`);
+  }
+}
+
+/** SubagentRecord → SubagentListItem（state 四态主字段 + status 调试字段，duration 实时计算）。
+ *  [v4 A-6] 新增 parent/resumable/closedReason：parent 从 record.parentRecordId 派生
+ *  （配合 A-5 直接父守卫），resumable 从 isResumable 派生（B-1「可续聊」对外表达），
+ *  closedReason 透传（SP-4 级联关闭告知替代 before_agent_start 注入）。
+ *  agent 是 GUI/TUI list 共用的显示名——取 basename 短名（displayAgentName），
+ *  完整路径保留在 record.agent（数据层）。 */
+export function recordToListItem(r: SubagentRecord): SubagentListItem {
   return {
     subagentId: r.id,
-    agent: r.agent,
+    agent: displayAgentName(r.agent),
     slug: r.slug,
+    state: mapExternalState(r.status),
     status: r.status,
     mode: r.mode,
     duration: computeElapsedSeconds(r),
     model: r.model,
     totalTokens: r.totalTokens,
     sessionFile: r.sessionFile,
+    parent: r.parentRecordId,
+    resumable: isResumable(r),
+    closedReason: r.closedReason,
   };
 }
 
@@ -171,10 +217,11 @@ export async function startHandler(
     fork: input.fork,
     worktree: input.worktree,
     cwd: input.cwd,
+    conversation: input.conversation,
+    idleTimeoutMs: input.idleTimeoutMs,
     ctxModel,
     signal,
-    // background 不回流 onUpdate：detached 运行，完成由 notify 驱动新 turn。
-    onUpdate: undefined,
+    // background detached 运行，完成由 notify 驱动新 turn。
   });
 
   return {
@@ -207,7 +254,12 @@ export function listHandler(
   // 防截断（先多取再过滤）已下沉到 store 层——这里直接传 limit + filter。
   const filter = includeFinished ? "all" : "running";
   const all = service.collectRecords(limit, filter);
-  const items: SubagentListItem[] = all.map(recordToListItem);
+  // [perf] collectRecords 磁盘源是 light（无 totalTokens/model 等）：SubagentListItem 对
+  // LLM 消费方暴露 totalTokens/model，逐项 getFullRecord 补全（per-file 缓存，仅首次
+  // 全量解析；显式 tool 调用非渲染热路径，成本可接受）。
+  const items: SubagentListItem[] = all.map((r) =>
+    recordToListItem(service.getFullRecord(r.id) ?? r),
+  );
   const running = items.filter((i) => i.status === "running").length;
 
   return { response: { running, items } };
@@ -245,6 +297,14 @@ export async function cancelHandler(
   if (rec.mode !== "background") {
     throw new Error(`Cannot cancel subagent ${id} (unsupported mode: ${rec.mode})`);
   }
+  // 对话模式 cancel = close(force:true) 别名（设计决策 5）：chatMode record（running/idle）
+  // 走 close 行为路径（idle 终态化 done；running 立即 SIGTERM cancelled），
+  // 返回 cancel 响应（向后兼容 cancel action 的返回类型）。非 chatMode 保持现有 cancel 行为。
+  if (rec.chatMode) {
+    const chatRecord = service.getRecordForAction(id);
+    await service.closeSubagent(chatRecord, true);
+    return { subagentId: id, response: { cancelled: true } };
+  }
   // step 3: service.cancel boolean（list-view 契约不变）；false = 已终态（CAS 抢锁失败）。
   // 注意：不嵌入 rec.status——findRecord 快照可能已过期（TOCTOU：cancel 期间 detached
   // 路径 CAS 到 done/failed）。重新查当前状态，避免「status: running」与「already finished」矛盾。
@@ -259,6 +319,127 @@ export async function cancelHandler(
   return { subagentId: id, response: { cancelled: true } };
 }
 
+// ============================================================
+// message handler（M2-B3 对话模式续聊/插入）
+// ============================================================
+
+export interface MessageHandlerInput {
+  subagentId?: string;
+  text?: string;
+  interrupt?: boolean;
+}
+
+/** message 领域对象（adapter 包成 messageResponse）。 */
+export type MessageHandlerResult = {
+  kind: "message";
+  subagentId: string;
+  response: MessageResponse;
+};
+
+/**
+ * message action handler：向对话模式 subagent 续聊/插入消息。
+ *
+ * 状态 × interrupt 自动映射（agent 只表达意图）：
+ *   running → deliverMessage 热路径（进程活：prompt + streamingBehavior，interrupt=true
+ *             抢占 / false 排队，pi 权威裁决 busy/idle）
+ *   进程死  → deliverMessage 冷路径（resumeRound 重开 session + prompt，interrupt 自动
+ *             退化，agent 无感）
+ *   终态    → throw ended（正常路径不命中——终态 record 已 archive，getRecordForAction 先 throw not found）
+ * （旧 deliverToRunning busy 投递已删除——SP-5 upgrade 后 running 恒走 deliverMessage）
+ *
+ * 归属守卫（决策 3）：getRecordForAction 内部校验 rootSessionId。
+ *
+ * @throws Error subagentId/text 缺失 / 不存在或非本 session 所有 / 已结束
+ */
+export async function messageHandler(
+  service: SubagentService,
+  input: MessageHandlerInput | undefined,
+): Promise<MessageHandlerResult> {
+  const id = input?.subagentId?.trim();
+  if (!id) throw new Error("messageParam.subagentId is required for action:'message'");
+  const text = input?.text?.trim();
+  if (!text) throw new Error(
+    "messageParam.text is required for action:'message' (must not be whitespace-only). " +
+    'Correct: {"action":"message","messageParam":{"subagentId":"sa-...","text":"your follow-up"}}',
+  );
+  const interrupt = input?.interrupt === true;
+
+  // 归属守卫（决策 3）：getRecordForAction 内部校验 rootSessionId
+  const record = service.getRecordForAction(id);
+
+  // SP-5 one-shot upgrade：非 chatMode 的 active record（running/idle）收到 message 时
+  // 自动升级为 chatMode，后续走 deliverMessage 统一投递路径（热路径或冷路径 resume）。
+  // closed/cancelled 终态 record 不可 upgrade（getRecordForAction 已抛 not found）。
+  // chatMode 是 ExecutionRecord 的 readonly 字段，用 Mutable<T> 显式断言绕过 readonly 约束（upgrade 语义）。
+  // Object.assign 隐式绕过 readonly 不可追踪，改为单字段显式赋值。
+  // [v4 A-3] 进程内 upgrade 入口（SP-5）——one-shot 首条 message 触发 upgrade 置位
+  // chatMode=true。与 subagent-service.ts getRecordForAction 磁盘重建（跨重启恢复入口）
+  // 分工：本入口服务进程内 one-shot，跨重启路径恒被 getRecordForAction 磁盘重建绕过
+  // （该处无条件 chatMode=true）。改动这两处必须协同，带 S3 回归。
+  if (!record.chatMode && record.status === "running") {
+    type Mutable<T> = { -readonly [K in keyof T]: T[K] };
+    (record as Mutable<ExecutionRecord>).chatMode = true;
+  }
+
+  // [V2 决策 3] chatMode 统一投递：按进程死活分流（热路径 prompt+streamingBehavior / 冷路径 resume），
+  // 不按 record.status（V2 进程长驻，idle 态进程仍活，续聊走热路径 prompt 而非重开 session）。
+  // SP-5：upgrade 后 record.chatMode 已为 true，统一进此分支。
+  if (record.chatMode) {
+    await service.deliverMessage(record, text, interrupt);
+  } else {
+    // 终态（closed/cancelled）：防御性兜底（终态 record 已 archive，正常走 not found）
+    throw new Error(
+      `subagent ${id} has ended (status: ${record.status}), cannot message. ` +
+      `Recovery: use action:'close' to clean up, then action:'start' a new subagent.`,
+    );
+  }
+  return { kind: "message", subagentId: id, response: { delivered: true } };
+}
+
+// ============================================================
+// close handler（M2-B3 对话模式结束）
+// ============================================================
+
+export interface CloseHandlerInput {
+  subagentId?: string;
+  force?: boolean;
+}
+
+/** close 领域对象（adapter 包成 closeResponse）。 */
+export type CloseHandlerResult = {
+  kind: "close";
+  subagentId: string;
+  response: CloseResponse;
+};
+
+/**
+ * close action handler：结束 subagent（对话模式为主，one-shot 同样支持）。
+ *
+ * force 语义（设计决策 5/10，v4 B-1 两态收敛 + M5 修正）：
+ *   force:false（默认）= 优雅关闭——
+ *     无在跑轮（等待续聊 timer armed / 无活进程）→ 立即终态化（closed + user-close，回收保活进程）
+ *     有活进程在跑轮 → 置 closeAfterRound，轮完成时终态化（chatMode 消费点 onRoundSettled，
+ *     one-shot 在 runAndFinalize 轮完成分支）——返回 {closed:true} 即承诺轮结束后资源已释放
+ *   force:true = 立即终止——running 立即 SIGTERM（cancelBackground 显式 kill）+ closed+cancelled
+ *
+ * 行为分流委托 service.closeSubagent（归属守卫由 getRecordForAction 把关）。
+ * 已终态 record 由 getRecordForAction throw not found（「已结束的不能再操作」语义）。
+ */
+export async function closeHandler(
+  service: SubagentService,
+  input: CloseHandlerInput | undefined,
+): Promise<CloseHandlerResult> {
+  const id = input?.subagentId?.trim();
+  if (!id) throw new Error("closeParam.subagentId is required for action:'close'");
+  const force = input?.force === true;
+
+  // 归属守卫（决策 3）+ 行为分流（service.closeSubagent）
+  const record = service.getRecordForAction(id);
+  await service.closeSubagent(record, force);
+
+  return { kind: "close", subagentId: id, response: { closed: true } };
+}
+
 // ============================================================
 // adapter（领域对象 → SubagentToolResult + {content, details}）
 // ============================================================
@@ -270,7 +451,9 @@ export async function cancelHandler(
 type AdapterInput =
   | { action: "start"; domain: StartHandlerResult }
   | { action: "list"; domain: ListHandlerResult }
-  | { action: "cancel"; domain: CancelHandlerResult };
+  | { action: "cancel"; domain: CancelHandlerResult }
+  | { action: "message"; domain: MessageHandlerResult }
+  | { action: "close"; domain: CloseHandlerResult };
 
 export function adapter(
   input: AdapterInput,
@@ -280,20 +463,35 @@ export function adapter(
   let result: SubagentToolResult;
   if (action === "start") {
     const d = input.domain;
-    result = { action, subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, slug: d.slug, bgResponse: d.response };
+    // MF-3（决策 10 细则 4）：LLM content (text) 用 null 瘦身，防诱导 agent 用 read 绕过工具
+    // 直接读 session 文件。真实 sessionFile 仅 details 保留（供 GUI/程序化消费）。
+    result = { action, subagentId: d.subagentId, sessionFile: null, slug: d.slug, bgResponse: d.response };
   } else if (action === "list") {
     result = { action, subagentId: null, sessionFile: null, listResponse: input.domain.response };
-  } else {
+  } else if (action === "cancel") {
     result = { action, subagentId: input.domain.subagentId, sessionFile: null, cancelResponse: input.domain.response };
+  } else if (action === "message") {
+    result = { action, subagentId: input.domain.subagentId, sessionFile: null, messageResponse: input.domain.response };
+  } else {
+    // action === "close"
+    result = { action, subagentId: input.domain.subagentId, sessionFile: null, closeResponse: input.domain.response };
   }
 
   // content JSON：LLM 看的结构化结果（schema 模式 parsedOutput 作为嵌套 JSON 值可接受）。
   const text = JSON.stringify(result);
 
+  // MF-3：start 的 LLM content 已瘦身（sessionFile:null），details 保留真实 sessionFile 供 GUI/程序化消费。
+  // result 已是合法 SubagentToolResult（start 变体 sessionFile:null）；start 时重建一个带真实 sessionFile 的副本。
+  let detailsBase: SubagentToolResult = result;
+  if (action === "start") {
+    const d = input.domain;
+    detailsBase = { action: "start", subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, slug: d.slug, bgResponse: d.response };
+  }
+
   // GUI 协议：RPC 模式下附加结构化渲染数据（union 各成员已声明 __gui__?，无需强转）
   const details: SubagentToolResult = ctx && isGuiCapable(ctx)
-    ? { ...result, __gui__: guiResult(buildGuiComponent(action, input, result)) }
-    : result;
+    ? { ...detailsBase, __gui__: guiResult(buildGuiComponent(input, result)) }
+    : detailsBase;
 
   // [W3 修复] list action 追加 reminder text block：LLM 调 list 时提醒不要轮询。
   // reminder 作为第二个 text block（独立追加，不污染 details/JSON schema）。
@@ -308,16 +506,20 @@ export function adapter(
   };
 }
 
-/** 按 action 构造对应的 GuiComponent。 */
+/**
+ * 按 input.action 构造对应的 GuiComponent。
+ * 分支判定用 discriminated key（input.action）而非独立宽类型参数——TS 自动
+ * 收窄 input.domain 到对应 HandlerResult，无需 `as` 断言（与 adapter() 同款模式）。
+ */
 export function buildGuiComponent(
-  action: string,
   input: AdapterInput,
   _result: SubagentToolResult,
 ) {
+  const { action } = input;
   if (action === "start") {
     // subagent-trace 多层语义（agent名+slug+状态）用 card(stats-line) 组合表达。
     // 利用 input.domain 的身份信息，让并发 subagent 可区分。
-    const d = input.domain as StartHandlerResult;
+    const d = input.domain;
     return guiComponent("card", {
       header: d.slug ? `${d.slug}` : d.subagentId.slice(0, SUBAGENT_ID_PREVIEW),
       body: [guiComponent("stats-line", {
@@ -326,7 +528,7 @@ export function buildGuiComponent(
     });
   }
   if (action === "list") {
-    const listResp = input.domain as ListHandlerResult;
+    const listResp = input.domain;
     return guiComponent("list-tree", {
       items: listResp.response.items.map((it) => ({
         label: it.slug ? `${it.agent} · ${it.slug} · ${it.subagentId}` : `${it.agent} · ${it.subagentId}`,
@@ -335,8 +537,24 @@ export function buildGuiComponent(
       })),
     });
   }
-  // cancel
+  if (action === "message") {
+    return guiComponent("stats-line", {
+      items: [{ label: "messaged", value: input.domain.subagentId, severity: "ok" }],
+    });
+  }
+  if (action === "close") {
+    return guiComponent("stats-line", {
+      items: [{ label: "closed", value: input.domain.subagentId, severity: "warn" }],
+    });
+  }
+  // cancel（fall-through：前四分支已 return）。
+  // 穷尽检查（同 mapExternalState 的 assertNever 先例）：AdapterInput 未来新增
+  // action 时，action 在此不再收窄为 "cancel"，assertNever 的 never 参数处编译
+  // 报错——防止新分支静默落入 cancelled 渲染。
+  if (action !== "cancel") {
+    throw new Error(`buildGuiComponent: unhandled action ${assertNever(action)}`);
+  }
   return guiComponent("stats-line", {
-    items: [{ label: "cancelled", value: (input.domain as CancelHandlerResult).subagentId, severity: "warn" }],
+    items: [{ label: "cancelled", value: input.domain.subagentId, severity: "warn" }],
   });
 }