@zhushanwen/pi-subagent-workflow 7.0.0 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -41,7 +41,7 @@
     ]
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "^0.3.1",
+    "@xyz-agent/extension-protocol": "^0.4.0",
     "ajv": "^8.20.0",
     "yaml": "^2.9.0",
     "@zhushanwen/pi-extension-logger": "0.2.0"
@@ -52,7 +52,7 @@
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
     "@zhushanwen/pi-pending-notifications": "0.3.1",
-    "@zhushanwen/pi-structured-output": "5.0.0"
+    "@zhushanwen/pi-structured-output": "5.0.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/execution/__tests__/execute-and-await-worktree.test.ts

@@ -1,10 +1,9 @@
 // src/__tests__/execute-and-await-worktree.test.ts
 //
-// executeAndAwait 的 worktree 前置守卫 + 失败收尾测试（W1 code review 修复回归锁）。
+// executeAndAwait 的 worktree 失败收尾测试（W1 code review 修复回归锁）。
 //
-// 覆盖两点：
-//   1. [MF#7] worktree:true && !fork 在任何副作用之前 fail-fast 抛错
-//   2. worktreeManager.create 抛错时 record 被 finalizeFailed（status→failed）且原错外抛
+// 覆盖：worktreeManager.create 抛错时 record 被 finalizeFailed（status→failed）且原错外抛。
+// （worktree 与 fork 解耦后，worktree:true+fork:false 的解耦验证见 subagent-service.test.ts。）
 //
 // ── mock 策略 ──
 //
@@ -153,33 +152,11 @@ function getStore(service: SubagentService): RecordStore {
   return Reflect.get(service, "store") as RecordStore;
 }
 
-describe("executeAndAwait worktree 前置守卫 + 失败收尾", () => {
+describe("executeAndAwait worktree 失败收尾", () => {
   afterEach(() => {
     vi.restoreAllMocks();
   });
 
-  // ============================================================
-  // [MF#7] worktree:true && !fork → fail-fast 抛错（任何副作用之前）
-  // ============================================================
-  it("[MF#7] worktree:true 且 fork 未设时抛 'worktree:true requires fork:true'", async () => {
-    const { service } = setup();
-
-    // guard 在 BC-12 深度检查之后、步骤 1 之前——无需 fork:true，worktree:true 即触发。
-    // 传入完整 ExecuteOptions（补全 slug 必填字段），不再用 `as` 掩盖缺失字段——让缺字段在类型层可见。
-    await expect(
-      service.executeAndAwait({
-        task: "needs worktree without fork",
-        slug: "mf7-worktree-without-fork",
-        worktree: true,
-        fork: undefined,
-        ctxModel,
-      }),
-    ).rejects.toThrow(/worktree:true requires fork:true/);
-
-    // 无副作用：guard 在 createRecordForMode 之前 → store 无 running record。
-    expect(getStore(service).listRunning()).toHaveLength(0);
-  });
-
   // ============================================================
   // worktreeManager.create 抛错 → record 收尾为 failed + 原错外抛
   // ============================================================

package/src/execution/__tests__/subagent-service.test.ts

@@ -385,24 +385,22 @@ describe("SubagentService", () => {
   });
 
   // ============================================================
-  // execute() worktree fail-fast 校验 [MF#7]（commit 8e8e75966）
+  // execute() worktree 路径（worktree 与 fork 解耦后）
   // ============================================================
   //
-  // [MF#7] execute 入口校验 `worktree:true && !fork` → fail-fast 抛错。
-  // 否则下面三个 worktree 分支都不命中，worktreeHandle 恒 undefined → 子 agent
-  // 零文件隔离且零报错（静默 no-op）。此组验证该校验的三种 fork/worktree 组合：
-  //   1. worktree:true + fork:false → 抛 "requires fork"（fail-fast 命中）
-  //   2. worktree:true + fork:true  → 不命中校验（执行越过 guard，后续因副作用失败）
-  //   3. worktree:false + fork:false → 不命中校验（默认路径，执行越过 guard）
+  // worktree（文件隔离）与 fork（上下文继承）已解耦：worktree:true 可独立于 fork 工作
+  // （worktreeManager.create 只看 opts.worktree，不读 fork）。此组验证三种 fork/worktree
+  // 组合下 worktree 路径的行为（均不应抛 'requires fork'——该 guard 已移除）：
+  //   1. worktree:true + fork:false → 解耦后正常（创建 worktree 路径，不抛 requires fork）
+  //   2. worktree:true + fork:true  → 创建 worktree 路径（测试环境 git 失败，抛非 requires fork 错）
+  //   3. worktree:false + fork:false → 默认路径（不创建 worktree）
   //
-  // 被测点是 execute() 入口的 guard（subagent-service.ts L277-282），在任何副作用
-  // （record 创建 / worktree 创建 / spawn）之前。本文件不 mock spawn（保持与文件头
-  // 声明一致——execute 集成测试在 execute-nesting / run-spawn-integration），
-  // 因此 case 2/3 验证「guard 放行」而非「执行完成」：执行越过 guard 后在后续步骤
-  // （worktreeManager.create 调 git / runSpawn 调 spawn）抛与 fork/worktree 无关的错。
-  // 用 try/catch 断言抛出的不是 guard 错误，精确锁住 guard 的触发条件。
-
-  describe("execute() worktree fail-fast 校验 [MF#7]", () => {
+  // 本文件不 mock spawn（保持与文件头声明一致——execute 集成测试在 execute-nesting /
+  // run-spawn-integration），因此 case 验证「不抛 requires fork」而非「执行完成」：
+  // 执行越过 worktree 创建后在后续步骤（worktreeManager.create 调 git / runSpawn 调
+  // spawn）抛与 fork/worktree 无关的错。用 try/catch 断言抛出的不是 requires fork。
+
+  describe("execute() worktree 路径（worktree 与 fork 解耦）", () => {
     /** 构造已就绪的 service（initSession + initModel 注入 ctxModel，使 resolveIdentity 不因 model 拗错）。 */
     function makeReadyService(): SubagentService {
       const service = new SubagentService({ cwd: agentDir, modelService });
@@ -422,24 +420,25 @@ describe("SubagentService", () => {
       return service;
     }
 
-    it("worktree:true + fork:false → fail-fast 抛错含 'requires fork'（guard 命中）", async () => {
+    it("worktree:true + fork:false → 解耦后不抛 'requires fork'（worktree 独立于 fork）", async () => {
       const service = makeReadyService();
-      // guard 在所有副作用之前：无 record 创建、无 spawn
-      await expect(
-        service.execute({
-          task: "worktree without fork",
+      // 解耦后 worktree:true+fork:false 不再 throw requires fork（worktreeManager.create 只看 worktree）
+      try {
+        await service.execute({
+          task: "worktree without fork (decoupled)",
           worktree: true,
           fork: false,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
-        }),
-      ).rejects.toThrow(/requires fork/);
-      // 无副作用：record 未创建（guard 在 createRecordForMode 之前）
-      expect(service.collectRecords(10)).toHaveLength(0);
+        });
+      } catch (err) {
+        // 解耦后绝不抛 requires fork（执行继续到 worktreeManager.create/spawn 才可能抛其他错）
+        expect((err as Error).message).not.toMatch(/requires fork/);
+      }
     });
 
-    it("worktree:true + fork:true → 不命中 guard（执行越过 guard，不抛 'requires fork'）", async () => {
+    it("worktree:true + fork:true → 创建 worktree 路径（不抛 'requires fork'）", async () => {
       const service = makeReadyService();
-      // guard 放行 → 执行继续：先创建 record，然后 worktreeManager.create 调 git（测试环境无 repo → 抛与 fork 无关的错）
+      // 执行继续：先创建 record，然后 worktreeManager.create 调 git（测试环境无 repo → 抛与 fork 无关的错）
       try {
         await service.execute({
           task: "worktree with fork",
@@ -454,9 +453,9 @@ describe("SubagentService", () => {
       }
     });
 
-    it("worktree:false + fork:false → 不命中 guard（默认路径越过 guard，不抛 'requires fork'）", async () => {
+    it("worktree:false + fork:false → 默认路径（不创建 worktree，不抛 'requires fork'）", async () => {
       const service = makeReadyService();
-      // guard 放行 → 执行继续：runSpawn 调 child_process.spawn（测试环境无真实 pi → 抛与 fork 无关的错）
+      // 默认路径：runSpawn 调 child_process.spawn（测试环境无真实 pi → 抛与 fork 无关的错）
       try {
         await service.execute({
           task: "default path",

package/src/execution/notifier.ts

@@ -19,7 +19,7 @@ export interface BgNotifyRecord {
   error?: string;
   startedAt: number;
   endedAt: number | undefined;
-  /** [MF#1] fork+worktree 模式下子 agent 改动的 patch 路径（worktree 外，cleanup 后留存）。
+  /** [MF#1] worktree 模式下子 agent 改动的 patch 路径（worktree 外，cleanup 后留存）。
    *  done 时通知文本显式提示 `git apply`，否则 background 子 agent 在隔离 worktree 的改动
    *  会静默丢失——父 LLM 不知 patch 路径，无法应用。 */
   patchFile?: string;

package/src/execution/subagent-service.ts

@@ -421,16 +421,6 @@ export class SubagentService {
       );
     }
 
-    // [MF#7] worktree:true 需要 fork:true——否则下面三个 worktree 分支都不命中，
-    // worktreeHandle 恒 undefined → 子 agent 零文件隔离且零报错（静默 no-op）。此处在
-    // 任何副作用（record 创建 / worktree 创建）之前 fail-fast，不吞误用。
-    if (opts.worktree === true && !opts.fork) {
-      throw new Error(
-        "worktree:true requires fork:true (worktree isolation only applies to forked sessions). " +
-          "Set fork:true together with worktree:true.",
-      );
-    }
-
     // mode 固定 background（sync 模式已删除）
     const mode: ExecutionMode = "background";
     const ctx = this.buildSessionRunnerContext(opts.cwd);
@@ -451,7 +441,7 @@ export class SubagentService {
       // 传入的是已创建的 WorktreeHandle
       worktreeHandle = opts.worktree;
     } else if (opts.worktree === true) {
-      // worktree===true（显式要求）——创建新 worktree。MF#7 已保证此处 fork 必为 true。
+      // worktree===true（显式要求）——创建新 worktree。与 fork 正交（worktree 文件隔离不依赖 fork 上下文继承）。
       try {
         worktreeHandle = this.worktreeManager.create(this.cwd, record.id);
         record.worktreeHandle = worktreeHandle;
@@ -524,15 +514,6 @@ export class SubagentService {
       );
     }
 
-    // [MF#7] worktree:true requires fork:true — symmetric with execute() guard.
-    // Fails fast before any side effect (record creation / worktree creation).
-    if (opts.worktree === true && !opts.fork) {
-      throw new Error(
-        "worktree:true requires fork:true (worktree isolation only applies to forked sessions). " +
-          "Set fork:true together with worktree:true.",
-      );
-    }
-
     // ── 步骤 1: IDENTITY 解析 ──
     const identity = await this.resolveIdentity(opts);
 
@@ -543,8 +524,8 @@ export class SubagentService {
     // ── 步骤 2.5: worktree creation (only worktree===true; handle injection is execute()'s path) ──
     // Workflow path receives boolean only (AgentCallOpts.worktree: boolean) — WorktreeHandle is a
     // main-thread non-serializable object that cannot cross worker postMessage, so no object branch
-    // here (unlike execute() :445-447 which serves the subagent-tool path). MF#7 guard above ensures
-    // fork===true when worktree===true. On create failure, finalizeFailed cleans up the record, then
+    // here (unlike execute() :445-447 which serves the subagent-tool path).
+    // On create failure, finalizeFailed cleans up the record, then
     // throw lets SAR.run() convert it to an AgentResult.error (not return-handle like execute()).
     let worktreeHandle: WorktreeHandle | undefined;
     if (opts.worktree === true) {

package/src/execution/types.ts

@@ -231,7 +231,7 @@ export interface AgentResult {
  */
 /**
  * worktree handle 值对象。仅 worktree:true 时持有——worktree 是独立维度，
- * 需显式开启（且要求 fork:true），fork alone 不创建 worktree。
+ * 需显式开启，fork alone 不创建 worktree。
  * Object.freeze 守卫保证不可变。
  */
 export interface WorktreeHandle {
@@ -339,7 +339,7 @@ export interface ExecutionRecord {
   /** session jsonl 文件名。session 创建成功后由 session-runner.run() 回填（窗口期内 undefined）。 */
   sessionFile?: string;
 
-  /** [MF#3] fork+worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+  /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
   patchFile?: string;
 
   /** worktree 隔离时的 handle（仅 worktree:true 时存在；fork alone 无此字段）。 */
@@ -383,7 +383,7 @@ export interface SubagentToolDetails {
   parsedOutput?: unknown;
   /** session jsonl 文件名（不含目录）。窗口期内可能 undefined（session 尚未创建成功）。 */
   sessionFile?: string;
-  /** [MF#3] fork+worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+  /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
   patchFile?: string;
 }
 
@@ -419,7 +419,7 @@ export interface ExecuteOptions {
   onComplete?: (record: RecordSnapshot) => void;
   /** 是否继承父会话上下文（fork 模式，只继承上下文）。 */
   fork?: boolean;
-  /** 文件系统隔离：true=创建新 git worktree（要求 fork:true），WorktreeHandle=复用外部已创建的；undefined=不隔离（parent cwd）。 */
+  /** 文件系统隔离：true=创建新 git worktree，WorktreeHandle=复用外部已创建的；undefined=不隔离（parent cwd）。 */
   worktree?: boolean | WorktreeHandle;
   /** 覆盖执行 cwd（默认 mainCwd）。 */
   cwd?: string;
@@ -527,7 +527,7 @@ export interface SubagentRecord {
   result?: string;
   error?: string;
   sessionFile?: string;
-  /** [MF#3] fork+worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+  /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
   patchFile?: string;
   /** 外部 Pi 实例（进程隔离模式下由外部启动的子进程）。 */
   externalInstance?: AliveMarker;

package/src/interface/bg-notify-render.ts

@@ -57,7 +57,7 @@ interface BgNotifyRecord {
   model?: string;
   result?: string;
   error?: string;
-  /** [MF#1] fork+worktree background 完成通知携带的 patch 文件路径。 */
+  /** [MF#1] worktree background 完成通知携带的 patch 文件路径。 */
   patchFile?: string;
 }
 
@@ -275,7 +275,7 @@ function extractBgNotifyRecord(details: unknown): BgNotifyRecord | undefined {
     model: typeof d.model === "string" ? d.model : undefined,
     result: typeof d.result === "string" ? d.result : undefined,
     error: typeof d.error === "string" ? d.error : undefined,
-    // [MF#1] 提取 patchFile（fork+worktree background 完成通知携带）。
+    // [MF#1] 提取 patchFile（worktree background 完成通知携带）。
     patchFile: typeof d.patchFile === "string" ? d.patchFile : undefined,
   };
 }

package/src/interface/subagent-tool.ts

@@ -105,10 +105,10 @@ const SubagentParams = Type.Object({
     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. Use worktree:true (requires fork:true) for file-system isolation.",
+    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 (requires fork:true): run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session. Prevents concurrent file-write conflicts between parent and subagent. Only takes effect when fork:true; passing worktree:true without fork:true throws an error.",
+    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. Defaults to the parent session\'s cwd.',

package/src/orchestration/models/types.ts

@@ -142,9 +142,9 @@ export interface AgentCallOpts {
  * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
  */
   cwd?: string;
-  /** Inherit parent session context (fork mode). Required when worktree isolation is enabled. */
+  /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
   fork?: boolean;
-  /** Filesystem isolation: when true, creates a new git worktree for the agent (requires fork: true). */
+  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
   worktree?: boolean;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
    * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */