@zhushanwen/pi-subagent-workflow 2.0.1 → 3.0.0

package/src/orchestration/__tests__/worker-script-builder-runtime.test.ts

@@ -99,6 +99,10 @@ interface RunOptions {
   args?: Record<string, unknown>;
   /** 按 agent-call 顺序回发的 parsedOutput（默认每个回发 {ok:true}）。 */
   agentResults?: unknown[];
+  /** 按 agent-call 顺序回发的完整 agent-result 对象（覆盖 agentResults 的 content/parsedOutput 默认形）。
+   *  用于 returnMeta 测试：回发包含 sessionFile/worktreePath/error 的完整 result，
+   *  worker handler 会原样取这些字段 resolve。未提供该项的索引退回 {content:"fallback", parsedOutput: agentResults[idx]}。 */
+  agentResultObjects?: Record<string, unknown>[];
   /** 主线程对收到的 workflow-call 的处理：回发 workflow-result。 */
   handleWorkflowCall?: (msg: WorkflowCallMsg) => unknown;
   /** 是否在收到首个 agent-call 后立即发 abort（测 abort 路径）。 */
@@ -156,11 +160,14 @@ function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult
           return;
         }
         const parsed = opts.agentResults?.[agentCallIdx] ?? { ok: true };
+        // returnMeta 测试路径：若调用方提供完整 result 对象（含 sessionFile/worktreePath/error），
+        // 原样回发；否则用既有 {content, parsedOutput} 默认形。
+        const fullResult = opts.agentResultObjects?.[agentCallIdx];
         agentCallIdx++;
         worker.postMessage({
           type: "agent-result",
           callId: raw.callId,
-          result: { content: "fallback", parsedOutput: parsed },
+          result: fullResult ?? { content: "fallback", parsedOutput: parsed },
           cached: false,
         });
       } else if (isWorkflowCall(raw)) {
@@ -345,3 +352,100 @@ describe("buildWorkerScript runtime — 之前缺失的路径覆盖", () => {
     expect(res.exitCode).not.toBe(1);
   });
 });
+
+// ── W2: agent() returnMeta 模式运行时验证 ───────────────────────────
+// 现有 worker-script-builder.test.ts 的 16 条 returnMeta 断言全是字符串 toContain，
+// 无法验证「真实 Worker 线程执行时 agent({returnMeta:true}) resolve 出对象、
+// 不设 returnMeta resolve 单值」。此处补运行时验证（对称 handler 9b 分支）。
+
+describe("buildWorkerScript runtime — W2 agent() returnMeta mode", () => {
+  it("agent({prompt, returnMeta:true}) resolve 出 {value, sessionFile, worktreePath, error}（非单值）", async () => {
+    // returnMeta:true → worker handler 走 9b 分支，resolve 包含 4 字段的对象。
+    // 主线程回发的 result 带 sessionFile/worktreePath/error，验证它们被原样透传。
+    const script = `
+      const r = await agent({ prompt: "with-meta", returnMeta: true });
+      return r;
+    `;
+    const res = await runWorker(script, {
+      agentResultObjects: [
+        {
+          content: "raw-text",
+          parsedOutput: { ok: true },
+          sessionFile: "/tmp/sess-1.jsonl",
+          worktreePath: "/tmp/wt-abc",
+          error: undefined,
+        },
+      ],
+    });
+    expect(res.agentCalls).toHaveLength(1);
+    // agent-call 消息应透传 returnMeta（验证 m1 修复：prompt 分支本就透传）
+    expect(res.agentCalls[0]!.opts.returnMeta).toBe(true);
+    expect(res.workerError).toBeUndefined();
+    // value = parsedOutput ?? content = {ok:true}（结构化输出优先）
+    expect(res.returnValue).toEqual({
+      value: { ok: true },
+      sessionFile: "/tmp/sess-1.jsonl",
+      worktreePath: "/tmp/wt-abc",
+      error: undefined,
+    });
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("不设 returnMeta 时 agent() resolve 单值（向后兼容）", async () => {
+    // 无 returnMeta → handler 走 else 分支，resolve 裸 _value（向后兼容）。
+    const script = `
+      const r = await agent({ prompt: "no-meta" });
+      return r;
+    `;
+    const res = await runWorker(script, {
+      agentResultObjects: [
+        {
+          content: "raw-text",
+          parsedOutput: { ok: true },
+          sessionFile: "/tmp/sess-2.jsonl",
+          worktreePath: "/tmp/wt-def",
+        },
+      ],
+    });
+    expect(res.agentCalls).toHaveLength(1);
+    expect(res.agentCalls[0]!.opts.returnMeta).toBeUndefined();
+    expect(res.workerError).toBeUndefined();
+    // 单值：parsedOutput 优先（{ok:true}），sessionFile/worktreePath 被丢弃
+    expect(res.returnValue).toEqual({ ok: true });
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("agent({task, returnMeta:true}) task/agent 快捷分支也透传 returnMeta（m1 修复）", async () => {
+    // m1 修复：task/agent 快捷分支现在透传 returnMeta（之前丢弃）。
+    // 用 task 而非 prompt 触发快捷分支，验证 returnMeta 生效。
+    const script = `
+      const r = await agent({ task: "via-task-branch", returnMeta: true });
+      return r;
+    `;
+    const res = await runWorker(script, {
+      agentResultObjects: [
+        {
+          content: "task-raw",
+          parsedOutput: "task-value",
+          sessionFile: "/tmp/sess-3.jsonl",
+          worktreePath: "/tmp/wt-ghi",
+          error: "soft-fail-msg",
+        },
+      ],
+    });
+    expect(res.agentCalls).toHaveLength(1);
+    // 快捷分支透传 returnMeta（m1 修复点）
+    expect(res.agentCalls[0]!.opts.returnMeta).toBe(true);
+    expect(res.agentCalls[0]!.opts.prompt).toBe("via-task-branch");
+    expect(res.workerError).toBeUndefined();
+    // returnMeta 生效 → resolve 对象（非单值）
+    expect(res.returnValue).toEqual({
+      value: "task-value",
+      sessionFile: "/tmp/sess-3.jsonl",
+      worktreePath: "/tmp/wt-ghi",
+      error: "soft-fail-msg",
+    });
+    expect(res.exitCode).not.toBe(1);
+  });
+});
+

package/src/orchestration/__tests__/worker-script-builder.test.ts

@@ -131,3 +131,94 @@ describe("buildWorkerScript — W1 postMessage defense & parallel degrade", () =
     });
   });
 });
+
+// ── W2: agent() returnMeta 模式 ──
+// 验证 returnMeta 标志：known fields 放行 + handler resolve 分支 + 缓存重放分支，
+// 且两处分支结构对称（returnMeta===true → {value, sessionFile, worktreePath, error}）。
+
+describe("buildWorkerScript — W2 agent() returnMeta mode", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  describe("returnMeta known field whitelist", () => {
+    it("includes returnMeta in _knownFields Set", () => {
+      expect(script).toContain('"returnMeta"');
+    });
+
+    it("includes returnMeta in unknown-fields warning text", () => {
+      expect(script).toContain("cwd, fork, worktree, returnMeta");
+    });
+
+    it("does NOT warn about returnMeta when only returnMeta is passed (parity with fork/worktree)", () => {
+      // fork/worktree 已是 known fields；returnMeta 加入后不应触发 warn 文案中的 returnMeta。
+      // 简化断言：warning 文案里 Known 列表含 returnMeta（即被识别）。
+      expect(script).toMatch(/Known fields:.*returnMeta/);
+    });
+  });
+
+  describe("_pendingCalls stores returnMeta flag", () => {
+    it("stores returnMeta: opts.returnMeta === true in _pendingCalls.set", () => {
+      expect(script).toContain(
+        "returnMeta: opts.returnMeta === true",
+      );
+    });
+  });
+
+  describe("agent-result handler resolve branch (改动 9b)", () => {
+    it("branches on pending.returnMeta", () => {
+      expect(script).toContain("if (pending.returnMeta)");
+    });
+
+    it("resolve branch returns {value, sessionFile, worktreePath, error}", () => {
+      const handlerBlock = script.match(
+        /if \(pending\.returnMeta\) \{[\s\S]*?\} else \{[\s\S]*?pending\.resolve\(_value\);[\s\S]*?\}/,
+      );
+      expect(handlerBlock).toBeTruthy();
+      expect(handlerBlock![0]).toContain("value: _value");
+      expect(handlerBlock![0]).toContain("sessionFile: msg.result.sessionFile");
+      expect(handlerBlock![0]).toContain("worktreePath: msg.result.worktreePath");
+      expect(handlerBlock![0]).toContain("error: msg.result.error");
+    });
+
+    it("fallback resolve single value uses msg.result.parsedOutput ?? msg.result.content", () => {
+      expect(script).toContain(
+        "const _value = msg.result.parsedOutput ?? msg.result.content;",
+      );
+    });
+  });
+
+  describe("cache replay returnMeta branch (改动 9c)", () => {
+    it("early-returns undefined when !cached", () => {
+      expect(script).toContain("if (!cached) return undefined;");
+    });
+
+    it("branches on opts.returnMeta === true", () => {
+      expect(script).toContain("if (opts.returnMeta === true)");
+    });
+
+    it("cache replay returns {value, sessionFile, worktreePath, error} from cached", () => {
+      const cacheBlock = script.match(
+        /if \(opts\.returnMeta === true\) \{[\s\S]*?return _cachedValue;/,
+      );
+      expect(cacheBlock).toBeTruthy();
+      expect(cacheBlock![0]).toContain("value: _cachedValue");
+      expect(cacheBlock![0]).toContain("sessionFile: cached.sessionFile");
+      expect(cacheBlock![0]).toContain("worktreePath: cached.worktreePath");
+      expect(cacheBlock![0]).toContain("error: cached.error");
+    });
+
+    it("cache replay fallback uses cached.parsedOutput ?? cached.content", () => {
+      expect(script).toContain(
+        "const _cachedValue = cached.parsedOutput ?? cached.content;",
+      );
+    });
+  });
+
+  describe("handler (9b) and cache replay (9c) branch symmetry", () => {
+    it("both expose worktreePath field (CL-1/DEC-2 core)", () => {
+      // handler 读 msg.result.worktreePath；cache replay 读 cached.worktreePath。
+      expect(script).toContain("msg.result.worktreePath");
+      expect(script).toContain("cached.worktreePath");
+    });
+  });
+});
+

package/src/orchestration/error-recovery.ts

@@ -25,6 +25,8 @@
  * 参考：domain-models.md §失败处理矩阵。
  */
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import { SLUG_MAX_LENGTH } from "../execution/execute-options-mapper.ts";
 import { createRecord, updateFromEvent } from "../execution/execution-record.ts";
 import { SubagentStream } from "../execution/stream-sink.ts";
@@ -40,6 +42,8 @@ import type { AgentCallOpts, AgentResult, ExecutionTraceNode } from "./models/ty
 import type { WorkflowRun } from "./models/workflow-run.ts";
 import type { WorkerHandle } from "./worker-handle.ts";
 
+const logger = getLogger("subagents");
+
 // ── 常量 ─────────────────────────────────────────────────────
 
 /**
@@ -225,7 +229,7 @@ function dispatchAgentCall(
   if (typeof msg.callId !== "number" || !Number.isFinite(msg.callId) ||
       typeof msg.opts !== "object" || msg.opts === null ||
       typeof msg.opts.prompt !== "string") {
-    console.error(`[workflow] malformed agent-call message: callId=${JSON.stringify(msg.callId)}, opts=${JSON.stringify(msg.opts)?.slice(0, 200)}`);
+    logger.error(`[workflow] malformed agent-call message: callId=${JSON.stringify(msg.callId)}, opts=${JSON.stringify(msg.opts)?.slice(0, 200)}`);
     return;
   }
 
@@ -299,7 +303,7 @@ function dispatchAgentCall(
     });
     postAgentResult(run, msg.callId, errorResult, false);
     deps.store.save(run).catch((e: unknown) => {
-      console.error(`[workflow] store.save failed (resolveAgentOpts): ${e instanceof Error ? e.message : String(e)}`);
+      logger.error(`[workflow] store.save failed (resolveAgentOpts): ${e instanceof Error ? e.message : String(e)}`);
     });
     return;
   }
@@ -352,7 +356,7 @@ function dispatchAgentCall(
       postBudgetUpdate(run);
       deps.store.save(run).catch((e: unknown) => {
         const m = e instanceof Error ? e.message : String(e);
-        console.error(`[workflow] store.save failed (agent call ${msg.callId}): ${m}`);
+        logger.error(`[workflow] store.save failed (agent call ${msg.callId}): ${m}`);
       });
 
  // C-2：budget 超限 → 终止整个 run（避免继续 spawn 烧预算）
@@ -374,7 +378,7 @@ function dispatchAgentCall(
         if (transitioned) {
           deps.store.save(run).catch((e: unknown) => {
             const m = e instanceof Error ? e.message : String(e);
-            console.error(`[workflow] store.save failed (budget done): ${m}`);
+            logger.error(`[workflow] store.save failed (budget done): ${m}`);
           });
           deps.log?.("debug", "workflow:error-recovery", "run saved after budget done", { runId: run.runId, reason: run.state.reason });
           // M12: onRunDone/emit 单独 try——这些是真实副作用，错误不应被静默吞掉
@@ -385,7 +389,7 @@ function dispatchAgentCall(
             deps.onRunDone?.(run);
           } catch (err) {
             const m = err instanceof Error ? err.message : String(err);
-            console.error(`[workflow] onRunDone/emit failed (budget done): ${m}`);
+            logger.error(`[workflow] onRunDone/emit failed (budget done): ${m}`);
           }
         }
       }
@@ -394,7 +398,7 @@ function dispatchAgentCall(
  // withSlot 在 queued + signal-aborted 时 reject AbortError——预期，不记错。
       if (err instanceof Error && err.name === "AbortError") return;
       const message = err instanceof Error ? err.message : String(err);
-      console.error(`[workflow] agent call ${msg.callId} failed: ${message}`);
+      logger.error(`[workflow] agent call ${msg.callId} failed: ${message}`);
  // 兜底回发：executeAgentCall 抛非 Abort 异常时（如 runner undefined 的 TypeError、
  // gate.withSlot 内部 bug）原 catch 仅 console.error，worker 内对 callId 的 pending
  // Promise 永不 resolve → agent() 永久 await → worker 脚本挂死。构造 failed AgentResult
@@ -422,7 +426,7 @@ function dispatchAgentCall(
       // S2: 与 .then 对称——catch 路径也同步 worker $BUDGET（幂等）
       postBudgetUpdate(run);
       deps.store.save(run).catch((e: unknown) => {
-        console.error(`[workflow] store.save failed (catch fallback): ${e instanceof Error ? e.message : String(e)}`);
+        logger.error(`[workflow] store.save failed (catch fallback): ${e instanceof Error ? e.message : String(e)}`);
       });
     });
 }
@@ -432,8 +436,12 @@ function dispatchAgentCall(
  *
  * postResult（workflow-call）与 postAgentResult（agent-call）各自前缀不同，故 prefix 参数化，
  * 共享返回类型与构造逻辑，避免字面量重复导致形状漂移。
+ *
+ * W2 防御关键纯函数——export 供独立单测（error-recovery-serialize-failed-result.test.ts）验证
+ * 返回 shape `{content:"", error:"<prefix>: <errMsg>"}`，确保两条 fallback 路径（workflow-call /
+ * agent-call）共享同一构造逻辑不漂移。
  */
-function makeSerializeFailedResult(
+export function makeSerializeFailedResult(
   prefix: string,
   errMsg: string,
 ): { content: string; error: string } {
@@ -456,7 +464,7 @@ function dispatchWorkflowCall(
   if (typeof msg.callId !== "number" || !Number.isFinite(msg.callId) ||
       typeof msg.name !== "string" ||
       typeof msg.args !== "object" || msg.args === null) {
-    console.error(`[workflow] malformed workflow-call message: callId=${JSON.stringify(msg.callId)}, name=${JSON.stringify(msg.name)}`);
+    logger.error(`[workflow] malformed workflow-call message: callId=${JSON.stringify(msg.callId)}, name=${JSON.stringify(msg.name)}`);
     return;
   }
 
@@ -474,7 +482,7 @@ function dispatchWorkflowCall(
       });
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
-      console.error(`[workflow] postResult (workflow-call callId=${msg.callId}) failed: ${errMsg}. Sending error fallback.`);
+      logger.error(`[workflow] postResult (workflow-call callId=${msg.callId}) failed: ${errMsg}. Sending error fallback.`);
       // 回发纯字符串 fallback result（必可克隆），让 worker pending resolve
       try {
         run.runtime?.worker.postMessage({
@@ -484,7 +492,7 @@ function dispatchWorkflowCall(
         });
       } catch {
         // fallback 也失败——worker 此 callId 的 pending 只能靠 timeout 兜底
-        console.error(`[workflow] postResult fallback also failed (callId=${msg.callId}): worker pending will hang until timeout`);
+        logger.error(`[workflow] postResult fallback also failed (callId=${msg.callId}): worker pending will hang until timeout`);
       }
     }
   };
@@ -515,7 +523,7 @@ function dispatchWorkflowCall(
  * postMessage 同步抛 DataCloneError。若冒泡到 dispatchAgentCall 的 .then 回调，会中断
  * 后续 postBudgetUpdate/store.save/budget 检查，run 卡在 running。故内部 try/catch：
  * 失败时记录诊断 + 回发纯字符串 fallback result（必可克隆），让 worker pending resolve。
- * 函数签名不变（所有调用点无需改动），仅用 console.error 记日志（deps 不在手边）。
+ * 函数签名不变（所有调用点无需改动），仅用共享 logger 记日志（deps 不在手边）。
  */
 function postAgentResult(
   run: WorkflowRun,
@@ -527,7 +535,7 @@ function postAgentResult(
     run.runtime?.worker.postMessage({ type: "agent-result", callId, result, cached });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    console.error(`[workflow] postAgentResult failed (callId=${callId}): ${msg}. Result likely contains non-cloneable value.`);
+    logger.error(`[workflow] postAgentResult failed (callId=${callId}): ${msg}. Result likely contains non-cloneable value.`);
     // 回发纯字符串 fallback result（必可克隆），让 worker pending resolve（避免永久挂起）
     try {
       run.runtime?.worker.postMessage({
@@ -539,7 +547,7 @@ function postAgentResult(
       });
     } catch {
       // fallback 也失败——worker 此 callId 的 pending 只能靠 timeout/exit 兜底
-      console.error(`[workflow] postAgentResult fallback also failed (callId=${callId}): worker pending will hang until timeout`);
+      logger.error(`[workflow] postAgentResult fallback also failed (callId=${callId}): worker pending will hang until timeout`);
     }
   }
 }
@@ -565,7 +573,7 @@ export function postBudgetUpdate(run: WorkflowRun): void {
     const msg = err instanceof Error ? err.message : String(err);
     // budget 是纯 number 不太可能失败，但防御性兜底——budget 同步非关键（worker 仍可
     // 基于 $BUDGET.spent() 自行累计），失败仅记日志，不中断调用方流程。
-    console.error(`[workflow] postBudgetUpdate failed: ${msg}. Budget sync to worker skipped (non-critical).`);
+    logger.error(`[workflow] postBudgetUpdate failed: ${msg}. Budget sync to worker skipped (non-critical).`);
   }
 }
 

package/src/orchestration/lifecycle.ts

@@ -30,6 +30,8 @@
  * 参考：domain-models.md §1（聚合根状态机）。
  */
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import { ConcurrencyGate, DEFAULT_CONCURRENCY } from "./concurrency-gate.ts";
 import {
   handleWorkerError,
@@ -45,6 +47,8 @@ import type { DoneReason } from "./models/types.ts";
 import { WorkflowRun } from "./models/workflow-run.ts";
 import type { WorkerHandle } from "./worker-handle.ts";
 
+const logger = getLogger("subagents");
+
 // ── 常量 ─────────────────────────────────────────────────────
 
 /** runId 生成：wf-<timestamp>-<base36 random 6 chars>。 */
@@ -115,7 +119,7 @@ export function scheduleTimeBudget(
     void abortRun(runId, deps, "Time budget exceeded", "time_limited").catch(
       (err: unknown) => {
         const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[workflow] time budget abort failed: ${msg}`);
+        logger.error(`[workflow] time budget abort failed: ${msg}`);
       },
     );
   }, budgetTimeMs);
@@ -174,7 +178,7 @@ export async function runWorkflow(
       () => {
         void abortRun(runId, deps, "External signal aborted").catch((err: unknown) => {
           const msg = err instanceof Error ? err.message : String(err);
-          console.error(`[workflow] abortRun on signal failed: ${msg}`);
+          logger.error(`[workflow] abortRun on signal failed: ${msg}`);
         });
       },
       { once: true },

package/src/orchestration/models/types.ts

@@ -135,6 +135,13 @@ export interface AgentCallOpts {
  * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
  */
   cwd?: string;
+  /** Inherit parent session context (fork mode). Required when worktree isolation is enabled. */
+  fork?: boolean;
+  /** Filesystem isolation: when true, creates a new git worktree for the agent (requires fork: true). */
+  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). */
+  returnMeta?: boolean;
 }
 
 /**
@@ -194,6 +201,17 @@ export interface AgentResult {
  * 窗口期内可能 undefined（session 尚未创建成功）。
  */
   sessionFile?: string;
+ /**
+ * Absolute path of the git worktree used for filesystem isolation (set when
+ * worktree isolation is active). Injected by executeAndAwait from record.worktreeHandle.path.
+ *
+ * ⚠️ Diagnostic only, may not exist: executeAndAwait's finalizeRecord cleans up the
+ * worktree (git worktree remove --force) before returning, so by the time this field
+ * reaches the caller the directory has typically been deleted. Use it only for log/trace
+ * correlation (e.g. attributing a session jsonl to its worktree origin) — never as a cwd
+ * for a subsequent agent or filesystem operation (would ENOENT).
+ */
+  worktreePath?: string;
  /** All tool calls collected from JSONL stream (FR-7). */
   toolCalls?: ToolCallEntry[];
 }

package/src/orchestration/worker-script-builder.ts

@@ -141,7 +141,18 @@ export function buildWorkerScript(userScript: string): string {
     '        // 不丢失。失败 resolve 为空字符串是既定容错策略。',
     '        // parsedOutput: validated data object from structured-output execute().',
     '        // Fallback to content (raw text) when no schema was requested or on error.',
-    '        pending.resolve(msg.result.parsedOutput ?? msg.result.content);',
+    '        // W2 改动 9(b)：returnMeta===true 时 resolve {value,sessionFile,worktreePath,error}（对称缓存重放 9c）；否则单值。',
+    '        const _value = msg.result.parsedOutput ?? msg.result.content;',
+    '        if (pending.returnMeta) {',
+    '          pending.resolve({',
+    '            value: _value,',
+    '            sessionFile: msg.result.sessionFile,',
+    '            worktreePath: msg.result.worktreePath,',
+    '            error: msg.result.error,',
+    '          });',
+    '        } else {',
+    '          pending.resolve(_value);',
+    '        }',
     '      }',
     '    } else if (msg.type === "workflow-result") {',
     '      const pending = _pendingCalls.get(msg.callId);',
@@ -185,6 +196,8 @@ export function buildWorkerScript(userScript: string): string {
     '      if (firstArg.prompt) {',
     '        opts = firstArg;',
     '      } else if (firstArg.task || firstArg.agent) {',
+    '        // fork/worktree/returnMeta forwarded here (parity with agent({prompt,...}) and direct-pass',
+    '        // branches). Previously this shortcut dropped them (w1 only noted, not wired).',
     '        opts = {',
     '          prompt: firstArg.task || firstArg.prompt || "",',
     '          description: firstArg.label || firstArg.description,',
@@ -195,6 +208,9 @@ export function buildWorkerScript(userScript: string): string {
     '          skill: firstArg.skill,',
     '          timeoutMs: firstArg.timeoutMs,',
     '          cwd: firstArg.cwd,',
+    '          fork: firstArg.fork,',
+    '          worktree: firstArg.worktree,',
+    '          returnMeta: firstArg.returnMeta,',
     '        };',
     '      } else {',
     '        opts = firstArg;',
@@ -204,10 +220,10 @@ export function buildWorkerScript(userScript: string): string {
     '    }',
     '',
     '    // Validate known agent() fields to catch API misuse early',
-    '    const _knownFields = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd"]);',
+    '    const _knownFields = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta"]);',
     '    const _unknownFields = Object.keys(opts).filter((k) => !_knownFields.has(k));',
     '    if (_unknownFields.length > 0) {',
-    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd"]);',
+    '      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta"]);',
     '    }',
     '',
     '    const callId = _callIdCounter;',
@@ -217,7 +233,18 @@ export function buildWorkerScript(userScript: string): string {
     '      const cached = _callCache.get(callId);',
     '      // 与 live handler 对齐：失败也 resolve（回退 content），不 throw。',
     '      // 见 agent-result 消息处理的注释：拒绝传播失败到 agent 外部。',
-    '      return cached ? (cached.parsedOutput ?? cached.content) : undefined;',
+    '      // W2 改动 9(c)：returnMeta 分支（对称 handler 9b），opts 仍在闭包作用域。',
+    '      if (!cached) return undefined;',
+    '      const _cachedValue = cached.parsedOutput ?? cached.content;',
+    '      if (opts.returnMeta === true) {',
+    '        return {',
+    '          value: _cachedValue,',
+    '          sessionFile: cached.sessionFile,',
+    '          worktreePath: cached.worktreePath,',
+    '          error: cached.error,',
+    '        };',
+    '      }',
+    '      return _cachedValue;',
     '    }',
     '',
     '    const _effectivePhase = opts.phase || _currentPhase;\n' +
@@ -227,7 +254,7 @@ export function buildWorkerScript(userScript: string): string {
     '      return Promise.reject(new Error("postMessage failed for agent-call (callId=" + callId + "): see workerLogs"));',
     '    }',
     '    return new Promise((resolve, reject) => {',
-    '      _pendingCalls.set(callId, { resolve, reject });',
+    '      _pendingCalls.set(callId, { resolve, reject, returnMeta: opts.returnMeta === true });',
     '    });',
     '  }',
     '',