@zhushanwen/pi-subagent-workflow 8.6.0 → 8.7.0

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, projectOutcome } 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";
 
 // ============================================================
@@ -126,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（模块内）
 // ============================================================
@@ -386,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）。
@@ -462,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}）
 // ============================================================
@@ -475,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,
@@ -495,6 +734,11 @@ export function adapter(
     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 };
@@ -565,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

@@ -12,22 +12,18 @@
 // 编译本 schema 并断言 required/description/enum/pattern 存活——SW 自身测试环境
 // 把 typebox alias 到 mock（丢 options），SO 侧测试以真实构造为对照基准。
 //
-// 层归属：Interface（工具 schema 的家）。SLUG_MAX_LENGTH 随 schema 迁入：
-// 它的唯一语义就是 tool schema 的 maxLength（见原 execute-options-mapper 注释），
-// execution 侧经 re-export 保持既有 import 路径不变。
+// 层归属：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 "../shared/model-ref.ts";
+import { THINKING_ORDER } from "@zhushanwen/subagent-core/shared/model-ref.ts";
 
-/**
- * slug 最大长度（字符）。subagent/workflow 创建时 slug 超过此值会被截断。
- * subagent/workflow tool schema 的 maxLength 引用此常量（单一真相，勿再硬编码）。
- * 历史值 20 偏紧——描述性 slug 如 "audit-structured-output"（23）/"fix-subagent-wf-tools"（21）
- * 会撞上限，放宽到 35 兼顾「短到能塞进 TUI 标题行」与「容纳合理描述性 kebab-case 名」。
- */
-export const SLUG_MAX_LENGTH = 35;
+import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core/execution/execute-options-mapper.ts";
+
+export { SLUG_MAX_LENGTH };
 
 // Params schema（跨包契约测试的真实 typebox 校验入口）。
 //
@@ -42,8 +38,8 @@ export const SLUG_MAX_LENGTH = 35;
 // （subagent_start / subagent_list / subagent_cancel），让每个 tool 的 schema 真实
 // 反映必填性。勿在此基础上继续堆 action 条件逻辑——要加就拆 tool。
 export const SubagentParams = Type.Object({
-  action: StringEnum(["start", "list", "cancel", "message", "close"], {
-    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).",
+  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).
@@ -150,6 +146,17 @@ export const SubagentParams = Type.Object({
       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）。 */

package/src/interface/subagent-tool.ts

@@ -16,11 +16,11 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme } from "@ea
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import type { Static } from "typebox";
 
-import { getSubagentService } from "../execution/subagent-service.ts";
-import type { SubagentToolResult } from "../execution/types.ts";
+import { getSubagentService } from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import type { SubagentToolResult } from "@zhushanwen/subagent-core/execution/types.ts";
 import { extractAgentName } from "./format.ts";
 import { toGuiCtx } from "./gui-mappers.ts";
-import { adapter, cancelHandler, closeHandler, listHandler, messageHandler, startHandler } from "./subagent-actions.ts";
+import { adapter, cancelHandler, closeHandler, forkFromHandler, listHandler, messageHandler, startHandler } from "./subagent-actions.ts";
 import { SubagentParams } from "./subagent-tool-schema.ts";
 import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
 
@@ -71,13 +71,14 @@ function assertNever(value: never): string {
 }
 
 /** Subagent action 字面量联合（与 parameters schema 的 StringEnum 取值一致）。 */
-type SubagentAction = "start" | "list" | "cancel" | "message" | "close";
+type SubagentAction = "start" | "list" | "cancel" | "message" | "close" | "fork-from";
 
 /** 类型守卫：把 schema 投影出的 string 形式 action 收窄回字面量联合。
  *  typebox v1 的 StringEnum Static 退化为 string，需运行时校验 + 类型收窄
  *  才能恢复 switch 的 exhaustiveness 约束。 */
 function isSubagentAction(value: string): value is SubagentAction {
-  return value === "start" || value === "list" || value === "cancel" || value === "message" || value === "close";
+  return value === "start" || value === "list" || value === "cancel" || value === "message"
+    || value === "close" || value === "fork-from";
 }
 
 /** unknown 是否为含 model/thinkingLevel 的对象（类型守卫，替代全可选结构 `as`）。 */
@@ -165,6 +166,7 @@ action:"list" before action:"start" — a reusable running subagent may exist; c
 - action:"close" — end a running subagent and release its resources. REQUIRED closeParam: { subagentId }. Optional: force (default false; true terminates mid-round immediately). Always close when done.
 - action:"list" — list subagents. Pass listParam: { includeFinished?, limit? } (all optional). Read an item's sessionFile for full detail.
 - action:"cancel" — stop a background subagent (legacy verb; for conversation-mode use close). REQUIRED cancelParam: { subagentId }.
+- action:"fork-from" — recovery for subagents disconnected by a session restart/exit: spawns a NEW subagent inheriting the old one's full history via --fork (source read-only, old record untouched). REQUIRED forkFromParam: { sourceSubagentId }. Optional: prompt (continuation instruction; handover frame injected if omitted). Returns { newSubagentId, sourceSessionFile }. Rejected with guidance: cancelled / worktree-bound / still-running sources.
 
 ## Examples
 
@@ -177,6 +179,7 @@ action:"list" before action:"start" — a reusable running subagent may exist; c
 {"action":"close","closeParam":{"subagentId":"sa-550e8400"}}
 {"action":"list","listParam":{"includeFinished":false,"limit":20}}
 {"action":"cancel","cancelParam":{"subagentId":"sa-550e8400"}}
+{"action":"fork-from","forkFromParam":{"sourceSubagentId":"sa-550e8400","prompt":"continue from where it stopped; verify tests first"}}
 \`\`\`
 
 ## After launching — do NOT wait
@@ -204,7 +207,7 @@ When to use:
 - ✅ Long-interval rounds (>5min apart) → conversation:true + idleTimeoutMs increased
 - ❌ Single exploration/lookup → default (one-shot)
 
-idleTimeoutMs: per-subagent idle timeout (default 300000 / 5min). Env XYZ_SUBAGENT_IDLE_TIMEOUT_MS sets the global default; per-call param takes precedence. Pass 0 or a negative value to disable idle cleanup entirely.
+idleTimeoutMs: per-subagent idle timeout (default 300000 / 5min). Env XYZ_SUBAGENT_IDLE_TIMEOUT_MS sets the global default; per-call param takes precedence.
 
 ## You cannot
 
@@ -323,6 +326,8 @@ const executeSubagent: SubagentExecuteCb = async (
       return adapter({ action: "message", domain: await messageHandler(service, params.messageParam) }, toGuiCtx(_ctx));
     case "close":
       return adapter({ action: "close", domain: await closeHandler(service, params.closeParam) }, toGuiCtx(_ctx));
+    case "fork-from":
+      return adapter({ action: "fork-from", domain: await forkFromHandler(service, params.forkFromParam) }, toGuiCtx(_ctx));
     default:
       // assertNever：让 exhaustiveness 成为承重约束——新增 action 时 tsc 报错，
       // 而非悄悄落入此分支。

package/src/interface/subagents.ts

@@ -9,9 +9,9 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
-import { getSubagentService } from "../execution/subagent-service.ts";
-import type { SubagentService } from "../execution/subagent-service.ts";
-import { displayAgentName } from "../shared/agent-ref.ts";
+import { getSubagentService } from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import type { SubagentService } from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
 import { messageHandler, startHandler } from "./subagent-actions.ts";
 import { parseSubagentRpcCommand } from "./command-actions.ts";
 import type { SubagentRpcAction } from "./command-actions.ts";

package/src/interface/tool-render.ts

@@ -24,8 +24,8 @@ import type { AgentToolResult, Theme } from "@earendil-works/pi-coding-agent";
 import type {
   ListResponse,
   SubagentToolResult,
-} from "../execution/types.ts";
-import { displayAgentName } from "../shared/agent-ref.ts";
+} from "@zhushanwen/subagent-core/execution/types.ts";
+import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
 import {
   extractAgentName,
   firstLine,
@@ -208,6 +208,15 @@ function buildCompactLines(d: SubagentToolResult, theme: ThemeLike): string[] {
       width,
     )];
   }
+  // ── fork-from 分支：接续确认行（[v8.5 B]）──
+  if (d.action === "fork-from" && d.forkFromResponse) {
+    const src = shortSessionLabel(d.forkFromResponse.sourceSessionFile);
+    return [truncLine(
+      `${theme.fg("accent", "⑂")} ${theme.fg("dim", "forked-from ")}${theme.fg("accent", src)}` +
+      ` ${theme.fg("dim", "→ new: ")}${theme.fg("accent", d.subagentId ?? "?")}`,
+      width,
+    )];
+  }
   // ── start 分支：background ──
   if ("bgResponse" in d) {
     return [truncLine(
@@ -234,6 +243,16 @@ function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
       width,
     )];
   }
+  if (d.action === "fork-from" && d.forkFromResponse) {
+    // expanded 与 compact 同形（一次性 block 无细节可展开），另附源文件完整路径行。
+    return [
+      truncLine(
+        `${theme.fg("accent", "⑂")} ${theme.fg("dim", "forked-from ")}${theme.fg("accent", d.forkFromResponse.sourceSessionFile)}` +
+        ` ${theme.fg("dim", "→ new: ")}${theme.fg("accent", d.subagentId ?? "?")}`,
+        width,
+      ),
+    ];
+  }
 
   const lines: string[] = [];
   // bg 占位 expanded 与 compact 同（一次性 block 无细节可展开）
@@ -261,11 +280,24 @@ function isDetailsStructurallyComplete(d: SubagentToolResult): boolean {
       return "listResponse" in d;
     case "cancel":
       return "cancelResponse" in d;
+    case "fork-from":
+      // [v8.5 B] 新 action 直接纳入 guard：缺内层分组才 fallback。
+      // message/close 维持历史现状（不落此 switch 显式分支，走 extractResultError
+      // 回显 content 首行）不变，避免触碰现有渲染回归面——review MF-13 曾引入
+      // message/close 显式分支后回退：无对应渲染分支却判「结构完整」会改走
+      // generic 无响应渲染，属静默行为变更。
+      return "forkFromResponse" in d;
     default:
       return false;
   }
 }
 
+/** fork-from 渲染用的源文件短标签（basename；失败时原样返回——渲染不应抛错）。 */
+function shortSessionLabel(file: string): string {
+  const idx = file.lastIndexOf("/");
+  return idx >= 0 ? file.slice(idx + 1) : file;
+}
+
 /**
  * 从 tool result 的 content 里提取错误文本。
  *

package/src/interface/tool-workflow-script.ts

@@ -30,12 +30,12 @@ import {
   guiResult,
   isGuiCapable,
 } from "@xyz-agent/extension-protocol";
-import type { WorkflowScriptRegistry } from "../orchestration/models/workflow-script-registry.ts";
-import { lintScript } from "../orchestration/script-lint.ts";
-import { deleteWorkflow, saveWorkflow } from "../orchestration/workflow-files.ts";
+import type { WorkflowScriptRegistry } from "@zhushanwen/subagent-core/orchestration/models/workflow-script-registry.ts";
+import { lintScript } from "@zhushanwen/subagent-core/orchestration/script-lint.ts";
+import { deleteWorkflow, saveWorkflow } from "@zhushanwen/subagent-core/orchestration/workflow-files.ts";
 import { toGuiCtx } from "./gui-mappers.ts";
 import { renderTextFallback } from "./views/format.ts";
-import { parseResourceMetaDetailed } from "../shared/meta-parser.ts";
+import { parseResourceMetaDetailed } from "@zhushanwen/subagent-core/shared/meta-parser.ts";
 
 // ── Parameter schema ─────────────────────────────────────────
 

package/src/interface/tool-workflow.ts

@@ -31,12 +31,12 @@ import {
 } from "@xyz-agent/extension-protocol";
 import { type Static, Type } from "typebox";
 
-import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
-import { THINKING_ORDER } from "../execution/model-resolver.ts";
-import type { LauncherDeps } from "../orchestration/launcher.ts";
-import { abortRun, runWorkflow } from "../orchestration/lifecycle.ts";
-import type { RunStore } from "../orchestration/models/ports.ts";
-import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
+import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core/execution/execute-options-mapper.ts";
+import { THINKING_ORDER } from "@zhushanwen/subagent-core/execution/model-resolver.ts";
+import type { LauncherDeps } from "@zhushanwen/subagent-core/orchestration/launcher.ts";
+import { abortRun, runWorkflow } from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
+import type { RunStore } from "@zhushanwen/subagent-core/orchestration/models/ports.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
 import { mapRunIcon, mapRunStatus, toGuiCtx } from "./gui-mappers.ts";
 import {
   acquireReentryGuard,

package/src/interface/views/WorkflowsView.ts

@@ -33,11 +33,11 @@ import {
   countAllToolCalls,
   getAllToolCalls,
   projectLiveProgress,
-} from "../../execution/execution-record.ts";
-import type { ExecutionTraceNode } from "../../orchestration/models/types.ts";
-import type { WorkflowRun } from "../../orchestration/models/workflow-run.ts";
-import { saveWorkflow } from "../../orchestration/workflow-files.ts";
-import { displayAgentName } from "../../shared/agent-ref.ts";
+} from "@zhushanwen/subagent-core/execution/execution-record.ts";
+import type { ExecutionTraceNode } from "@zhushanwen/subagent-core/orchestration/models/types.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
+import { saveWorkflow } from "@zhushanwen/subagent-core/orchestration/workflow-files.ts";
+import { displayAgentName } from "@zhushanwen/subagent-core/shared/agent-ref.ts";
 import {
   BOX_BORDER_CHARS,
   BUDGET_TOKENS_DIVISOR,

package/src/interface/views/__tests__/WorkflowsView-signature.test.ts

@@ -13,9 +13,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 
 import { computeRenderSignature } from "../WorkflowsView.ts";
-import type { ExecutionRecord } from "../../../execution/types.ts";
-import type { ExecutionTraceNode, WorkerLogEntry } from "../../../orchestration/models/types.ts";
-import type { WorkflowRun } from "../../../orchestration/models/workflow-run.ts";
+import type { ExecutionRecord } from "@zhushanwen/subagent-core/execution/types.ts";
+import type { ExecutionTraceNode, WorkerLogEntry } from "@zhushanwen/subagent-core/orchestration/models/types.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
 
 // ── Fixtures（duck typing，对齐 detail-content-session-file.test.ts 先例）──
 

package/src/interface/views/__tests__/detail-content-session-file.test.ts

@@ -9,8 +9,8 @@ import { describe, expect, it } from "vitest";
 
 import { buildDetailContent } from "../detail-content.ts";
 import type { ThemeLike } from "../format.ts";
-import type { ExecutionTraceNode } from "../../../orchestration/models/types.ts";
-import type { WorkflowRun } from "../../../orchestration/models/workflow-run.ts";
+import type { ExecutionTraceNode } from "@zhushanwen/subagent-core/orchestration/models/types.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
 
 /** plain theme: fg/bold 直接返回原文，无 ANSI 色码——测试断言纯文本。 */
 const plainTheme: ThemeLike = {

package/src/interface/views/detail-content.ts

@@ -12,10 +12,10 @@
 
 import { Key, matchesKey } from "@earendil-works/pi-tui";
 
-import { getAllToolCalls, projectLiveProgress } from "../../execution/execution-record.ts";
-import type { AgentEventLogEntry } from "../../execution/types.ts";
-import type { ExecutionTraceNode } from "../../orchestration/models/types.ts";
-import type { WorkflowRun } from "../../orchestration/models/workflow-run.ts";
+import { getAllToolCalls, projectLiveProgress } from "@zhushanwen/subagent-core/execution/execution-record.ts";
+import type { AgentEventLogEntry } from "@zhushanwen/subagent-core/execution/types.ts";
+import type { ExecutionTraceNode } from "@zhushanwen/subagent-core/orchestration/models/types.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
 import {
   BOX_BORDER_CHARS,
   BUDGET_TOKENS_DIVISOR,