@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

package/src/interface/list-component.ts

@@ -11,10 +11,10 @@
 import type { Component } from "@earendil-works/pi-tui";
 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 { computeElapsedSeconds } from "@zhushanwen/subagent-core/execution/execution-record.ts";
+import type { SubagentService } from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import type { SubagentRecord } from "@zhushanwen/subagent-core/execution/types.ts";
+import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
 import {
   firstLine,
   formatDisplayItem,

package/src/interface/list-shared.ts

@@ -6,8 +6,8 @@
 // 按键处理 processKey 仍留 list-view，由 list-view factory 注入给组件（KeyHandler 类型在此），
 // 故 list-component 无需 import list-view，循环消除。
 
-import type { SubagentService } from "../execution/subagent-service.ts";
-import type { SubagentRecord } from "../execution/types.ts";
+import type { SubagentService } from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import type { SubagentRecord } from "@zhushanwen/subagent-core/execution/types.ts";
 
 // ============================================================
 // 常量

package/src/interface/list-view.ts

@@ -35,8 +35,8 @@
 import { matchesKey } from "@earendil-works/pi-tui";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import type { SubagentService } from "../execution/subagent-service.ts";
-import type { SubagentRecord } from "../execution/types.ts";
+import type { SubagentService } from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import type { SubagentRecord } from "@zhushanwen/subagent-core/execution/types.ts";
 import { type ThemeLike } from "./format.ts";
 import { SubagentsListComponent } from "./list-component.ts";
 import {

package/src/interface/subagent-actions.ts

@@ -16,25 +16,27 @@ import {
   isGuiCapable,
 } from "@xyz-agent/extension-protocol";
 
-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 { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core/execution/execute-options-mapper.ts";
+import { computeElapsedSeconds, projectOutcome } from "@zhushanwen/subagent-core/execution/execution-record.ts";
+import { isResumable } from "@zhushanwen/subagent-core/execution/lifecycle-predicates.ts";
+import type { ExecutionRecord } from "@zhushanwen/subagent-core/execution/types.ts";
+import type { ModelInfo } from "@zhushanwen/subagent-core/execution/model-resolver.ts";
+import type { SubagentService } from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
 import type {
   BgResponse,
   CancelResponse,
   CloseResponse,
   ExecutionStatus,
   ExternalState,
+  ForkFromResponse,
   ListResponse,
   MessageResponse,
   SubagentListItem,
   SubagentRecord,
   SubagentToolResult,
-} from "../execution/types.ts";
+} from "@zhushanwen/subagent-core/execution/types.ts";
+import { ResurrectDeniedError } from "@zhushanwen/subagent-core/execution/types.ts";
 import { mapRunIcon, mapRunStatus } from "./gui-mappers.ts";
 
 // ============================================================
@@ -49,6 +51,9 @@ const MAX_LIST_LIMIT = 100;
 /** background 启动提示文案（spec FR-3 bgResponse.message）。 */
 const BG_MESSAGE = "detached, will notify on completion (auto-injected message, do not poll)";
 
+/** 通知投递契约回显恒值（U1 预置，U2 账本兑现，见 BgResponse.notifyContract）。 */
+const NOTIFY_CONTRACT = "ledger+at-least-once" as const;
+
 /** subagentId（UUID）在 GUI header 的截断显示长度。 */
 const SUBAGENT_ID_PREVIEW = 8;
 
@@ -79,7 +84,10 @@ export interface StartHandlerInput {
   cwd?: string;
   /** 可持续对话模式（true = chatMode，轮次完成进 idle 等续聊）。 */
   conversation?: boolean;
-  /** 空闲超时毫秒数（仅 conversation 模式有意义，覆盖默认 5min）。 */
+  /**
+   * 空闲超时毫秒数（仅 conversation 模式有意义，覆盖默认 5min）。
+   * 显式传 0/负数 = 禁用 idle GC（不挂 timer）；不传走 env/默认优先级。
+   */
   idleTimeoutMs?: number;
   /** 执行引擎（D4 三层路由第一层：本参数 > agent frontmatter engine > config defaultEngine）。 */
   engine?: string;
@@ -92,6 +100,11 @@ export type StartHandlerResult = {
   sessionFile: string | undefined;
   /** 短标签，来自 record（handle.details.slug）。用于 result 行展示。 */
   slug: string;
+  /**
+   * registry 全等回显（U1）：handle.details.model = record.model = `${provider}/${id}`，
+   * 源头是 resolveModel 裁决放行的条目——通过校验 = 子进程必然按此名执行。
+   */
+  model: string;
   response: BgResponse;
 };
 
@@ -115,6 +128,100 @@ export interface CancelHandlerResult {
   response: CancelResponse;
 }
 
+// ============================================================
+// [v8.5 A1/B] message 拒绝文案分流 + fork-from 引导语框架
+// ============================================================
+
+/**
+ * [v8.5 A1] message 拒绝时的可行动文案分流。
+ *
+ * 背景：getRecordForAction 冷查只认 status==='running'（SP-2 可续聊重建），任何终态/
+ * 异归属记录都落到同一个「not found or not owned」错误，把两类完全不同的场景混为一谈：
+ *   - user-close/cancelled：用户主动告别，记录真没了 → 引导 start 新的
+ *   - parent-shutdown/gc/orphan 等：父会话重启/进程退出导致的断联，对话 jsonl 完好，
+ *     resume/fork 基建现成 → 引导 fork-from 从旧记录接续
+ *
+ * 分流规则（消费方是 LLM，保持正交简单）：
+ *   - 找不到记录 → 原样透传 getRecordForAction 错误（id 打错最常见，原文案最准）
+ *   - closed + user-close/cancelled →「已主动关闭，无法续聊」文案
+ *   - 其余（closed 其他 reason / running 但异归属）→「断联可接续」文案
+ */
+export function endedMessageGuard(service: SubagentService, id: string, original: unknown): Error {
+  // [v8.5 D] 透明重生守卫拒绝（worktree/异进程占用）原样透传——错误自带完整行动语言，
+  // 若被下方 fork-from 指引改写会误导 agent 走已被判死的通道（types.ts 契约声明）。
+  if (original instanceof ResurrectDeniedError) return original;
+  let snap: SubagentRecord | undefined;
+  try {
+    snap = service.lookupRecordAnyState(id);
+  } catch {
+    snap = undefined;
+  }
+  if (!snap) {
+    return original instanceof Error ? original : new Error(String(original));
+  }
+  if (snap.status === "closed") {
+    if (snap.closedReason === "cancelled" || snap.closedReason === "user-close") {
+      return new Error(
+        `subagent ${id} was deliberately closed by user (closedReason: ${snap.closedReason}) — ` +
+        `it cannot be messaged or resumed; nothing can reattach to it. ` +
+        `Recovery: start a new subagent (action:'start'); use action:'list' with includeFinished:true to review its final output.`,
+      );
+    }
+    return new Error(
+      `subagent ${id} is ended but reconnectable (closedReason: ${snap.closedReason ?? "unknown"}` +
+      `${describeClosedContext(snap)}). Its conversation history is intact at ${snap.sessionFile ?? "(session file unavailable)"}. ` +
+      `Recovery: resume from that history with {"action":"fork-from","forkFromParam":{"sourceSubagentId":"${id}"}}, ` +
+      `or read key points directly from the session file.`,
+    );
+  }
+  // running 但未通过 getRecordForAction：记录属于当前进程外的另一个 session 树
+  //（主会话重启前的遗留态，或其他并发 pi 进程的活跃 subagent）。无论哪种，历史
+  // jsonl 只读安全，fork-from 快照接续均有效。
+  return new Error(
+    `subagent ${id} is alive but belongs to a different session tree than this one` +
+    `${describeClosedContext(snap)}. You cannot message it from here. ` +
+    `Recovery: branch from its history with {"action":"fork-from","forkFromParam":{"sourceSubagentId":"${id}"}}` +
+    `${snap.sessionFile ? ` (source session: ${snap.sessionFile})` : ``}; otherwise start a new subagent.`,
+  );
+}
+
+/** 终态快照的上下文人话短语（仅作补充描述，主分支逻辑在 endedMessageGuard）。 */
+function describeClosedContext(r: SubagentRecord): string {
+  switch (r.closedReason) {
+    case "parent-shutdown":
+      return " — it was disconnected when the previous parent session exited";
+    case "parent-fork":
+      return " — it was detached when the previous parent session forked";
+    case "parent-new":
+      return " — it was detached when the previous parent session switched";
+    case "disconnected":
+      return " — it ended in a previous session (exact cause unknown)";
+    default:
+      return "";
+  }
+}
+
+/**
+ * [v8.5 B] fork-from 开场引导语框架（prompt 未指定时注入）：先从继承的历史重建状态
+ * 再继续，防猜。
+ */
+const FORK_FROM_DEFAULT_PROMPT =
+  "You are taking over work from a previous subagent whose full conversation history you inherited (--fork). " +
+  "First reconstruct state from that history: list what was already done, decided, and left unfinished (a few bullet lines). " +
+  "Then continue the remaining work to completion.";
+
+/**
+ * [v8.5 B] 有显式接续指令时的包裹框架：指令在前、上下文重建要求在后——指令首见即达，
+ * 不湮没在元说明里（弱模型友好）。
+ */
+function wrapForkFromPrompt(prompt: string): string {
+  return (
+    prompt.trim() +
+    "\n\n(You are continuing a previous subagent's inherited conversation via --fork. " +
+    "Reconstruct state from that history first — what was done, decided, and remains — then execute the instruction above.)"
+  );
+}
+
 // ============================================================
 // helpers（模块内）
 // ============================================================
@@ -154,9 +261,11 @@ export function mapExternalState(status: ExecutionStatus): ExternalState {
 }
 
 /** 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 注入）。
+ *  [v4 A-6] 新增 parent/resumable：parent 从 record.parentRecordId 派生（配合 A-5 直接父
+ *  守卫），resumable 从 isResumable 派生（B-1「可续聊」对外表达）。
+ *  [U3 C-outcome] 新增 outcome 一等终态语义（projectOutcome 唯一出口）；closedReason
+ *  退出对外 JSON（保留为 record 内部诊断字段），对外成败判读收口到 outcome，消费方
+ *  零手写推导（三处同构 switch 已收敛删除）。
  *  agent 是 GUI/TUI list 共用的显示名——取 basename 短名（displayAgentName），
  *  完整路径保留在 record.agent（数据层）。 */
 export function recordToListItem(r: SubagentRecord): SubagentListItem {
@@ -173,7 +282,7 @@ export function recordToListItem(r: SubagentRecord): SubagentListItem {
     sessionFile: r.sessionFile,
     parent: r.parentRecordId,
     resumable: isResumable(r),
-    closedReason: r.closedReason,
+    outcome: projectOutcome(r),
   };
 }
 
@@ -232,10 +341,13 @@ export async function startHandler(
     subagentId: handle.subagentId,
     sessionFile: handle.sessionFile,
     slug: handle.details.slug,
+    // [U1] registry 全等回显：record.model 由 resolved（裁决放行条目）拼接，原样透出。
+    model: handle.details.model,
     response: {
       status: "running",
       mode: "background",
       message: BG_MESSAGE,
+      notifyContract: NOTIFY_CONTRACT,
     },
   };
 }
@@ -370,8 +482,16 @@ export async function messageHandler(
   );
   const interrupt = input?.interrupt === true;
 
-  // 归属守卫（决策 3）：getRecordForAction 内部校验 rootSessionId
-  const record = service.getRecordForAction(id);
+  // 归属守卫（决策 3）：getRecordForAction 内部校验 rootSessionId。
+  // [v8.5 A1] 拒绝时经 endedMessageGuard 分流：找不到 → 原错误；user-close/cancelled
+  // → 「已主动关闭」；断联/已完成/异归属 → fork-from 可行动指引。仅 message action
+  // 升级文案——close/cancel 维持原语义（它们不需要恢复通道）。
+  let record: ExecutionRecord;
+  try {
+    record = service.getRecordForAction(id, { allowReconnect: true });
+  } catch (err) {
+    throw endedMessageGuard(service, id, err);
+  }
 
   // SP-5 one-shot upgrade：非 chatMode 的 active record（running/idle）收到 message 时
   // 自动升级为 chatMode，后续走 deliverMessage 统一投递路径（热路径或冷路径 resume）。
@@ -446,6 +566,140 @@ export async function closeHandler(
   return { kind: "close", subagentId: id, response: { closed: true } };
 }
 
+// ============================================================
+// fork-from handler（[v8.5 B] 断联恢复通道）
+// ============================================================
+
+export interface ForkFromHandlerInput {
+  sourceSubagentId?: string;
+  prompt?: string;
+}
+
+/** fork-from 领域对象（adapter 包成 forkFromResponse）。 */
+export type ForkFromHandlerResult = {
+  kind: "fork-from";
+  /** 新 subagent 的 record id（后续续聊用 action:'message'）。 */
+  subagentId: string;
+  /** 作为 --fork 继承源的旧记录 session 文件。 */
+  sourceSessionFile: string;
+  response: ForkFromResponse;
+};
+
+/**
+ * fork-from action handler：从旧 subagent 的会话历史 spawn 新 id 接续。
+ *
+ * 用于 subagent 因会话重启/进程退出而断联后的恢复：新进程以 --fork 指向旧 session
+ * 文件（copy-on-write 建分支会话），继承全部对话历史；源文件只读不续写。
+ * 旧记录本身不动——closed 单向状态机不变量、tryTransition 语义均不触碰。
+ *
+ * 守卫链（拒绝原因与行动语言对齐现有 MF-4 风格）：
+ *   1. 本进程内存 running → 还活着，应走 message（防双写同一子 session 文件）
+ *   2. 不存在            → 引导 list 确认
+ *   3. 异进程活跃（磁盘 .alive pid 存活 / running 快照）→ 别处正跑，不可从此接续
+ *      （同 id 双写风险；等待其结束或在其所属会话内操作）
+ *   4. tombstone/cancelled → 用户主动取消，真没了（不提供接续通道）
+ *   5. worktree 记录     → checkout 不可复用，fork 子进程 cwd 会回落主仓破坏隔离
+ *      （对齐 deliverMessage 的 hadWorktree 守卫语义）
+ *   6. 无子 session 文件  → 无历史可继承（entry-only 孤儿：spawn 窗口期中断）
+ *
+ * @throws Error 各守卫命中 / service.execute 失败（引擎不支持等）
+ */
+export async function forkFromHandler(
+  service: SubagentService,
+  input: ForkFromHandlerInput | undefined,
+): Promise<ForkFromHandlerResult> {
+  const id = input?.sourceSubagentId?.trim();
+  if (!id) throw new Error("forkFromParam.sourceSubagentId is required for action:'fork-from'");
+  const prompt = input?.prompt?.trim() ?? "";
+  const task = prompt ? wrapForkFromPrompt(prompt) : FORK_FROM_DEFAULT_PROMPT;
+
+  const source = assertAndLookupForkFromSource(service, id);
+
+  // slug 派生：源 slug + -resumed 后缀（截断到上限）。仅展示标签，不需唯一。
+  const baseSlug = (source.slug || source.agent || "resumed").slice(0, SLUG_MAX_LENGTH - "-resumed".length);
+  const handle = await service.execute({
+    task,
+    slug: `${baseSlug}-resumed`,
+    forkFromSessionFile: source.sessionFile,
+  });
+
+  return {
+    kind: "fork-from",
+    subagentId: handle.subagentId,
+    sourceSessionFile: source.sessionFile,
+    response: { newSubagentId: handle.subagentId, sourceSessionFile: source.sessionFile },
+  };
+}
+
+/** forkFromHandler 的守卫链（fork-from handler doc 的守卫 1–6 原样提取）：按序校验
+ *  源记录可接续，命中即抛带行动语言的 Error；全部通过则返回源 SubagentRecord
+ *  （守卫 6 已保证 sessionFile 非空，返回类型随之收窄）。 */
+function assertAndLookupForkFromSource(service: SubagentService, id: string): SubagentRecord & { sessionFile: string } {
+  // 守卫 1：本进程内存 running —— 直接 message 即可，fork-from 会双写其 session 文件。
+  if (service.findRecord(id)) {
+    throw new Error(
+      `subagent ${id} is still active in this process — use action:'message' to continue it directly. ` +
+      `If you want a parallel branch from its history, close it first (action:'close'), then fork-from.`,
+    );
+  }
+
+  // 守卫 2：全态查找（内存 archived + 磁盘重建）。
+  const source = service.lookupRecordAnyState(id);
+  if (!source) {
+    throw new Error(
+      `No subagent record with id "${id}". It may never have existed or been garbage-collected — ` +
+      `use action:'list' with includeFinished:true to verify the id.`,
+    );
+  }
+
+  // 守卫 3：异进程活跃（磁盘分支 3 externalInstance = 另一进程的活 pid marker）。
+  // 双写防护：fork 虽 copy-on-write（历史 jsonl 只读），但源仍在异进程运行时接续容易
+  // 读到半截历史，等它结束再接更安全。判据只认 externalInstance（真实活 pid 探针
+  // 命中），不拦 status==='running' 的快照——后者含 B-1 跨重启回退重建的 running 记录
+  //（无活 pid，历史已完整落盘），它们正是 endedMessageGuard 指引 fork-from 的目标；
+  // 拦了会让 agent 在「建议 fork-from」与「fork-from 拒绝 running」两条错误间死循环。
+  if (source.externalInstance !== undefined) {
+    throw new Error(
+      `subagent ${id} is still running in another process (alive pid marker present). ` +
+      `Recovery: wait until it finishes, or operate it in its own session; then retry fork-from.`,
+    );
+  }
+
+  // 守卫 4：主动告别（cancelled tombstone / user-close 正式关闭）——close 语义无旁路：
+  // fork-from 与 message 一致拒绝（guard 一致性规格），文案升级为统一「主动关闭」形态
+  // （含 closedReason 显式列入），与 deliverMessage 的 X 分支同语系不同落地（此处强调不可 branch）。
+  if (source.status === "closed" && (source.closedReason === "cancelled" || source.closedReason === "user-close")) {
+    throw new Error(
+      `subagent ${id} was deliberately closed by user (closedReason: ${source.closedReason}) — ` +
+      `deliberately-closed records cannot be resumed or branched from; nothing can reattach to them. ` +
+      `Recovery: start a fresh subagent (action:'start'); use action:'list' with includeFinished:true to review its final output.`,
+    );
+  }
+
+  // 守卫 5：worktree 记录 —— WorktreeHandle 不可序列化，checkout 已被 reaper/cleanup
+  // 回收；fork 子进程若复用旧路径会回落主 repo（破坏文件隔离）。与 deliverMessage 的
+  // hadWorktree 守卫同一判据同一理由。
+  if (source.worktree === true) {
+    throw new Error(
+      `subagent ${id} was created with worktree isolation; that binding was lost when its parent process ended. ` +
+      `Resuming from its history would run outside the original worktree isolation. ` +
+      `Recovery: start a new subagent with action:'start' and carry over key findings manually ` +
+      `(read ${source.sessionFile ?? "its session file"} if needed).`,
+    );
+  }
+
+  // 守卫 6：无子 session 文件（entry-born 孤儿：spawn 窗口期中断，从未开跑）。
+  const sessionFile = source.sessionFile;
+  if (!sessionFile) {
+    throw new Error(
+      `subagent ${id} has no child session file to inherit from (it never started successfully). ` +
+      `Recovery: start a fresh subagent (action:'start') describing the task again.`,
+    );
+  }
+
+  return { ...source, sessionFile };
+}
+
 // ============================================================
 // adapter（领域对象 → SubagentToolResult + {content, details}）
 // ============================================================
@@ -459,7 +713,8 @@ type AdapterInput =
   | { action: "list"; domain: ListHandlerResult }
   | { action: "cancel"; domain: CancelHandlerResult }
   | { action: "message"; domain: MessageHandlerResult }
-  | { action: "close"; domain: CloseHandlerResult };
+  | { action: "close"; domain: CloseHandlerResult }
+  | { action: "fork-from"; domain: ForkFromHandlerResult };
 
 export function adapter(
   input: AdapterInput,
@@ -471,13 +726,19 @@ export function adapter(
     const d = input.domain;
     // 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 };
+    // [U1] model 为 registry 全等回显（放行即全等）。
+    result = { action, subagentId: d.subagentId, sessionFile: null, slug: d.slug, model: d.model, bgResponse: d.response };
   } else if (action === "list") {
     result = { action, subagentId: null, sessionFile: null, listResponse: input.domain.response };
   } 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 if (action === "fork-from") {
+    // MF-3 同款瘦身：sourceSessionFile 真实路径只在 forkFromResponse 内层（LLM 接续
+    // 不需要拼路径，需要时 list/details 可取）；顶层 sessionFile 保持 null 一致性。
+    const d = input.domain;
+    result = { action, subagentId: d.subagentId, sessionFile: null, forkFromResponse: d.response };
   } else {
     // action === "close"
     result = { action, subagentId: input.domain.subagentId, sessionFile: null, closeResponse: input.domain.response };
@@ -491,7 +752,7 @@ export function adapter(
   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 };
+    detailsBase = { action: "start", subagentId: d.subagentId, sessionFile: d.sessionFile ?? null, slug: d.slug, model: d.model, bgResponse: d.response };
   }
 
   // GUI 协议：RPC 模式下附加结构化渲染数据（union 各成员已声明 __gui__?，无需强转）
@@ -503,7 +764,7 @@ export function adapter(
   // reminder 作为第二个 text block（独立追加，不污染 details/JSON schema）。
   // 只有 list 触发——start 的 reminder 已在 BG_MESSAGE 里；cancel 无需。
   const reminder = action === "list"
-    ? "\n\nReminder: Subagent completion is auto-notified via injected message (deliverAs: steer). Do NOT poll in a loop — there is no poll action. Use action:'list' only when you concretely need state, then continue working or stop."
+    ? "\n\nReminder: Subagent completion is auto-notified via auto-injected message (turn-triggering on idle). Do NOT poll in a loop — there is no poll action. Use action:'list' only when you concretely need state, then continue working or stop." // g4-allow: 契约文案——reminder 字符串描述自动注入通道（triggerTurn 单通道，U2/D5 无 deliverAs），非实际投递调用
     : "";
 
   return {
@@ -548,6 +809,14 @@ export function buildGuiComponent(
       items: [{ label: "messaged", value: input.domain.subagentId, severity: "ok" }],
     });
   }
+  if (action === "fork-from") {
+    return guiComponent("stats-line", {
+      items: [
+        { label: "forked-from", value: input.domain.sourceSessionFile },
+        { label: "new subagent", value: input.domain.subagentId, severity: "ok" },
+      ],
+    });
+  }
   if (action === "close") {
     return guiComponent("stats-line", {
       items: [{ label: "closed", value: input.domain.subagentId, severity: "warn" }],

package/src/interface/subagent-tool-schema.ts

@@ -0,0 +1,163 @@
+// src/interface/subagent-tool-schema.ts
+//
+// `subagent` 工具的参数 schema 纯常量叶子（零运行时依赖，先例 shared/schema-env.ts）。
+//
+// 抽取自 subagent-tool.ts（跨包契约另一半）：subagent-tool 依赖树沉重（pi SDK /
+// handler / render 链），structured-output 侧的跨包契约测试若从它 import schema
+// 会把整条依赖树拖进测试进程。本模块只含 schema 常量，运行时 import 仅
+// typebox（Type 构造）与 pi-ai（StringEnum helper），为 structured-output 侧
+//（及任何消费者）的跨包契约测试提供稳定 import 点。
+//
+// [跨包契约] structured-output 的 cross-package-contract.test.ts 经真实 typebox
+// 编译本 schema 并断言 required/description/enum/pattern 存活——SW 自身测试环境
+// 把 typebox alias 到 mock（丢 options），SO 侧测试以真实构造为对照基准。
+//
+// 层归属：Interface（工具 schema 的家）。SLUG_MAX_LENGTH 权威定义回归 core 侧
+// execution/execute-options-mapper.ts（subagent-core 包抽离 u1-move：core 切面不得
+// 反向 import 壳侧 interface，常量随之内化）——此处 re-export 保持既有 import 路径。
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+import { THINKING_ORDER } from "@zhushanwen/subagent-core/shared/model-ref.ts";
+
+import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core/execution/execute-options-mapper.ts";
+
+export { SLUG_MAX_LENGTH };
+
+// Params schema（跨包契约测试的真实 typebox 校验入口）。
+//
+// action:"start" 的 13 字段（task/slug/agent/model/...）拍平在顶层，不再用 startParam
+// 嵌套容器包。原因：弱模型（GLM/DeepSeek）信任 schema 结构信号 > 文本信号，经常省略
+// startParam 嵌套层把 task/slug 直接平铺到顶层导致调用失败。拍平后 schema 结构与模型
+// 的自然倾向一致，消除这层误用。task/slug 必填性由 startHandler runtime 校验（flat
+// JSON Schema 无法表达「action 条件必填」）。
+//
+// TODO(long-term, option-A): listParam/cancelParam 仍标 Optional 也是 flat JSON Schema
+// 表达「action 分发条件必填」的妥协——长期方案是拆成 3 个独立 tool
+// （subagent_start / subagent_list / subagent_cancel），让每个 tool 的 schema 真实
+// 反映必填性。勿在此基础上继续堆 action 条件逻辑——要加就拆 tool。
+export const SubagentParams = Type.Object({
+  action: StringEnum(["start", "list", "cancel", "message", "close", "fork-from"], {
+    description: "Operation: 'start' runs a subagent, 'list' shows subagents, 'cancel' stops a background subagent, 'message' sends a follow-up to a running subagent (one-shot subagents are auto-upgraded to conversation mode on first message), 'close' ends a running subagent (conversation-mode or one-shot), 'fork-from' spawns a NEW subagent inheriting an older one's history (recovery for restart-disconnected subagents; the old record is untouched).",
+  }),
+  // ── action:"start" fields (flattened to top level). task/slug REQUIRED for start. ──
+  // Missing/empty task or slug throws at runtime (startHandler).
+  // (flat JSON Schema can't express conditional requirement — see file-level TODO.)
+  task: Type.Optional(Type.String({
+    description: "REQUIRED for action:'start'. The task for the subagent to execute. Throws if missing or whitespace-only.",
+  })),
+  slug: Type.Optional(Type.String({
+    description:
+      "REQUIRED for action:'start'. Short label (≤35 chars) for this subagent, e.g. 'fix-login', 'extract-urls'. " +
+      "Shown in TUI to distinguish concurrent subagents.",
+    maxLength: SLUG_MAX_LENGTH,
+  })),
+  agent: Type.Optional(Type.String({
+    description: 'Agent ref: absolute path to the agent .md file (use <location> from <available_subagents>). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Do not invent names — only use paths from the injected list.',
+  })),
+  model: Type.Optional(Type.String({
+    description: 'Model override in "provider/modelId" format. CASE-SENSITIVE: the string must equal a registry entry exactly, including letter case (e.g. "zai-coding-cn/GLM-5.3-Flash", NOT "zai-coding-cn/glm-5.3-flash"). A non-exact match is rejected immediately with "Did you mean" suggestions — retry with the exact suggested string; the system never auto-corrects your input. Resolution order (top wins): (1) this param, (2) agent .md frontmatter model, (3) the main agent\'s current model (zero-config default). An explicit model (param or frontmatter) that is missing or unauthorized THROWS — there is no silent fallback to the main model. Omit this param to inherit the main model.',
+  })),
+  thinkingLevel: Type.Optional(StringEnum(THINKING_ORDER, {
+    description: "Thinking depth override (derived from THINKING_ORDER SSOT, includes 'max'). Omit to default to the model's highest available level (not the main agent's level).",
+  })),
+  skillPath: Type.Optional(Type.String({
+    description:
+      "Absolute path to a skill directory, injected into the subagent's pi process via --skill " +
+      "(e.g. a path under .agents/skills/ already resolved for the caller). Must be an absolute path; " +
+      "'..' traversal segments are rejected.",
+    pattern: "^/",
+  })),
+  appendSystemPrompt: Type.Optional(Type.Array(Type.String())),
+  schema: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  maxTurns: Type.Optional(Type.Number({
+    description: "Turn limit. The subagent is terminated via SIGTERM after maxTurns turn_end events + graceTurns of slack. There is no graceful wrap-up message — the process is killed. 0 or omitted = unlimited.",
+  })),
+  graceTurns: Type.Optional(Type.Number({
+    description: "Extra turns allowed after maxTurns is reached before SIGTERM (default 2). Only meaningful when maxTurns is set.",
+  })),
+  fork: Type.Optional(Type.Boolean({
+    description: "Fork mode: inherit the parent's conversation context. When true, the subagent receives the parent's session file via --fork and builds a branched conversation (it sees prior turns/messages). The subagent still runs in a separate spawned child process (process isolation) — fork is about context inheritance, not process sharing; independent of worktree (file-system isolation, see worktree param). When to use: only when the task extends from the parent and genuinely needs key information from the parent's conversation history that a self-contained task prompt cannot carry — most tasks a plain prompt can describe do NOT need fork, so keep false by default and enable only when the user explicitly asks or the task truly depends on seeing prior turns. Caveat: fork drags in the parent's dispatch records and unrelated task context, polluting the subagent (it cannot tell 'context meant for me' from 'parent dispatching me'); when state lives in an external store the subagent can query (e.g., cw handoff), prefer that over fork.",
+  })),
+  worktree: Type.Optional(Type.Boolean({
+    description: "Worktree isolation: run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session (prevents concurrent file-write conflicts). Independent of fork — worktree may be combined with fork:false (file isolation does not require context inheritance). When to use: parallel development scenarios where multiple agents write files concurrently and need isolated working directories (each gets its own checkout; merge later); leave false for single-agent or read-only tasks.",
+  })),
+  cwd: Type.Optional(Type.String({
+    description: 'Override the working directory for the subagent execution. Must be an absolute path (no "~" shorthand, no relative paths); ".." segments are rejected. Defaults to the parent session\'s cwd.',
+    pattern: "^/",
+  })),
+  conversation: Type.Optional(Type.Boolean({
+    description:
+      "Enable continuous chat with this subagent. When true, the subagent stays available after each reply — you can send follow-up messages (action:'message') and it keeps the full conversation context across rounds, with no need to re-spawn or re-explain. " +
+      "\nUse conversation:true for: multi-round collaboration (iterative review-fix loops, back-and-forth refinement), any task where you expect to send follow-up messages after the initial result. " +
+      "\nOmit (or false) for: one-shot tasks — single exploration, lookup, file read, code generation that needs no follow-up. The subagent runs once, notifies on completion, and is cleaned up automatically (default). " +
+      "\nFor long-interval collaboration (each round spaced >5min apart), set conversation:true AND increase idleTimeoutMs to avoid premature timeout. " +
+      "Cost: a conversation-mode subagent holds resources (memory, and a worktree if enabled) until you explicitly end it with action:'close'. Always close when done.",
+  })),
+  idleTimeoutMs: Type.Optional(Type.Number({
+    description:
+      "Idle timeout in milliseconds for conversation-mode subagents. Controls how long an idle subagent (between rounds) stays alive before automatic cleanup. " +
+      "Default: 300000 (5min). Override for long-interval collaboration where each round is spaced >5min apart. " +
+      "Pass 0 or a negative value to DISABLE idle cleanup entirely (subagent stays alive until explicitly closed). " +
+      "Only meaningful with conversation:true; ignored for one-shot subagents.",
+  })),
+  engine: Type.Optional(StringEnum(["pi", "zcode"], {
+    description:
+      "Execution engine for this subagent. Omit to inherit the global config. " +
+      "Three-layer priority: this parameter > agent .md frontmatter engine > config.json defaultEngine. " +
+      "Non-pi engines do not support conversation/fork/worktree (rejected before the subagent is created).",
+  })),
+  // action:"list" → listParam OPTIONAL (all fields optional, defaults apply). Ignored by other actions.
+  listParam: Type.Optional(Type.Object({
+    includeFinished: Type.Optional(Type.Boolean({
+      description: "Include finished (done/failed/cancelled) records. Default false (running only).",
+    })),
+    limit: Type.Optional(Type.Number({
+      description: "Max items to return. Default 20, clamped to [1, 100].",
+    })),
+  })),
+  // action:"cancel" → cancelParam.subagentId REQUIRED. Throws if missing. Ignored by other actions.
+  cancelParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'cancel'. The subagentId to cancel. Throws if missing. Only background subagents can be cancelled.",
+    }),
+  })),
+  // action:"message" → messageParam.subagentId + text REQUIRED. Any RUNNING subagent works —
+  // one-shot subagents are auto-upgraded to conversation mode on first message (SP-5); ended ones throw.
+  messageParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'message'. The subagentId to message (any running subagent; a one-shot subagent is auto-upgraded to conversation mode on first message, so you may also message one-shot subagents that are still running).",
+    }),
+    text: Type.String({
+      description: "REQUIRED for action:'message'. The message to send. Whitespace-only throws.",
+    }),
+    interrupt: Type.Optional(Type.Boolean({
+      description: "If true, interrupt the subagent's current work immediately (in-progress output stops, it switches to your new message). If false (default), the message is queued and processed after the current round completes. When the subagent is idle (between rounds), interrupt has no effect — the message always starts a new round.",
+    })),
+  })),
+  // action:"close" → closeParam.subagentId REQUIRED. Ends a running subagent (conversation-mode
+  // or one-shot — closeSubagent behavior split covers both).
+  closeParam: Type.Optional(Type.Object({
+    subagentId: Type.String({
+      description: "REQUIRED for action:'close'. The subagentId to close (any running subagent, conversation-mode or one-shot).",
+    }),
+    force: Type.Optional(Type.Boolean({
+      description: "If true, terminate immediately even if mid-round (in-progress work is lost). If false (default), let the current round finish, then close. When idle, the subagent closes immediately regardless.",
+    })),
+  })),
+  // action:"fork-from" → forkFromParam.sourceSubagentId REQUIRED ([v8.5 B] 断联恢复通道).
+  // 从旧 subagent 的会话历史 spawn 新 id：新进程 --fork 指向旧 session 文件（copy-on-write，
+  // 源文件只读不续写）；旧记录/状态机不动。pi 引擎限定（非 pi 在 execute 层拒绝）。
+  forkFromParam: Type.Optional(Type.Object({
+    sourceSubagentId: Type.String({
+      description: "REQUIRED for action:'fork-from'. The OLD subagentId whose conversation history becomes the inherited context of the new subagent. Works for records disconnected by a session restart or already finished; cancelled/worktree-bound/still-running ones are rejected with guidance.",
+    }),
+    prompt: Type.Optional(Type.String({
+      description: "Continuation instruction for the new subagent (what to do next on top of the inherited history). When omitted, a standard handover frame is injected: reconstruct done/decided/remaining from the inherited history, then continue to completion. Whitespace-only treated as omitted.",
+    })),
+  })),
+});
+
+/** Params schema 的 Static 投影（消费方经 `Static<typeof SubagentParams>` 使用，见 subagent-tool.ts）。 */
+export type SubagentParamsStatic = Static<typeof SubagentParams>;