gsd-pi 2.82.0 → 3.0.0

package/dist/resources/extensions/subagent/index.js

@@ -28,6 +28,9 @@ import { registerWorker, updateWorker } from "./worker-registry.js";
 import { loadEffectiveGSDPreferences } from "../gsd/preferences.js";
 import { emitJournalEvent } from "../gsd/journal.js";
 import { CmuxClient, shellEscape } from "../cmux/index.js";
+import { buildShellEnvAssignments, createSubagentLaunchPlan, isSubagentChildProcess, } from "./launch.js";
+import { SubagentRunStore, createInitialRunRecord, createSubagentTrackingName, deriveRunStatus, } from "./run-store.js";
+export { buildSubagentProcessArgs } from "./launch.js";
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
 const COLLAPSED_ITEM_COUNT = 10;
@@ -195,18 +198,6 @@ function writePromptToTempFile(agentName, prompt) {
     fs.writeFileSync(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
     return { dir: tmpDir, filePath };
 }
-export function buildSubagentProcessArgs(agent, task, tmpPromptPath, modelOverride) {
-    const args = ["--mode", "json", "-p", "--no-session"];
-    const effectiveModel = modelOverride ?? agent.model;
-    if (effectiveModel)
-        args.push("--model", effectiveModel);
-    if (agent.tools && agent.tools.length > 0)
-        args.push("--tools", agent.tools.join(","));
-    if (tmpPromptPath)
-        args.push("--append-system-prompt", tmpPromptPath);
-    args.push(`Task: ${task}`);
-    return args;
-}
 function processSubagentEventLine(line, currentResult, emitUpdate) {
     if (!line.trim())
         return;
@@ -256,12 +247,68 @@ async function waitForFile(filePath, signal, timeoutMs = 30 * 60 * 1000) {
     }
     return false;
 }
-async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride) {
+function resultStatus(result) {
+    if (result.stopReason === "aborted")
+        return "interrupted";
+    return result.exitCode === 0 ? "succeeded" : "failed";
+}
+function resultToChildArtifact(result, index, cwd) {
+    const running = result.running === true || result.exitCode === -1;
+    return {
+        index,
+        agent: result.agent,
+        trackingName: result.trackingName,
+        task: result.task,
+        status: running ? "running" : resultStatus(result),
+        exitCode: result.exitCode,
+        cwd,
+        sessionFile: result.sessionFile,
+        completedAt: running ? undefined : new Date().toISOString(),
+        output: getFinalOutput(result.messages),
+        stderr: result.stderr || undefined,
+        errorMessage: result.errorMessage,
+        stopReason: result.stopReason,
+        model: result.model,
+        usage: result.usage,
+        merge: result.mergeResult
+            ? {
+                success: result.mergeResult.success,
+                appliedPatches: result.mergeResult.appliedPatches,
+                failedPatches: result.mergeResult.failedPatches,
+                error: result.mergeResult.error,
+            }
+            : undefined,
+    };
+}
+function formatAgentLabel(agent, trackingName) {
+    return trackingName ? `${trackingName} / ${agent}` : agent;
+}
+function formatRunRecord(record) {
+    if (!record)
+        return "Subagent run not found.";
+    const lines = [
+        `Run ${record.runId}: ${record.status}`,
+        `Mode: ${record.mode}`,
+        `Context: ${record.contextMode}`,
+        `Updated: ${record.updatedAt}`,
+    ];
+    for (const child of record.children) {
+        const exit = child.exitCode === undefined ? "" : ` (exit ${child.exitCode})`;
+        lines.push(`- [${child.status}] ${formatAgentLabel(child.agent, child.trackingName)}${exit}: ${child.output || child.errorMessage || child.stderr || child.task}`);
+        if (child.sessionFile)
+            lines.push(`  session: ${child.sessionFile}`);
+    }
+    if (record.failure)
+        lines.push(`Failure: ${record.failure.message}`);
+    return lines.join("\n");
+}
+async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride, contextMode = "fresh", parentSessionManager, sessionOverride, trackingName) {
     const agent = agents.find((a) => a.name === agentName);
     if (!agent) {
         const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
         return {
             agent: agentName,
+            trackingName,
             agentSource: "unknown",
             task,
             exitCode: 1,
@@ -277,6 +324,7 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
         if (activePhase && agent.conflictsWith.includes(activePhase)) {
             return {
                 agent: agentName,
+                trackingName,
                 agentSource: agent.source,
                 task,
                 exitCode: 1,
@@ -291,9 +339,11 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
     let tmpPromptPath = null;
     const currentResult = {
         agent: agentName,
+        trackingName,
         agentSource: agent.source,
         task,
-        exitCode: 0,
+        exitCode: -1,
+        running: true,
         messages: [],
         stderr: "",
         usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -314,12 +364,24 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             tmpPromptDir = tmp.dir;
             tmpPromptPath = tmp.filePath;
         }
-        const args = buildSubagentProcessArgs(agent, task, tmpPromptPath, modelOverride);
+        const launch = createSubagentLaunchPlan({
+            agent,
+            task,
+            tmpPromptPath,
+            modelOverride,
+            contextMode,
+            parentSessionManager,
+            session: sessionOverride,
+            cwd,
+            defaultCwd,
+        });
+        if (launch.session.mode === "fork")
+            currentResult.sessionFile = launch.session.sessionFile;
         let wasAborted = false;
         const exitCode = await new Promise((resolve) => {
             const bundledPaths = (process.env.GSD_BUNDLED_EXTENSION_PATHS ?? "").split(path.delimiter).map(s => s.trim()).filter(Boolean);
             const extensionArgs = bundledPaths.flatMap(p => ["--extension", p]);
-            const proc = spawn(process.execPath, [process.env.GSD_BIN_PATH, ...extensionArgs, ...args], { cwd: cwd ?? defaultCwd, shell: false, stdio: ["ignore", "pipe", "pipe"] });
+            const proc = spawn(process.execPath, [process.env.GSD_BIN_PATH, ...extensionArgs, ...launch.args], { cwd: launch.cwd, env: launch.env, shell: false, stdio: ["ignore", "pipe", "pipe"] });
             liveSubagentProcesses.add(proc);
             let buffer = "";
             proc.stdout.on("data", (data) => {
@@ -358,6 +420,7 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             }
         });
         currentResult.exitCode = exitCode;
+        currentResult.running = false;
         if (wasAborted)
             throw new Error("Subagent was aborted");
         return currentResult;
@@ -379,19 +442,21 @@ async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, si
             }
     }
 }
-async function runSingleAgentInCmuxSplit(cmuxClient, directionOrSurfaceId, defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride) {
+async function runSingleAgentInCmuxSplit(cmuxClient, directionOrSurfaceId, defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride, contextMode = "fresh", parentSessionManager, sessionOverride, trackingName) {
     const agent = agents.find((a) => a.name === agentName);
     if (!agent) {
-        return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride);
+        return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride, contextMode, parentSessionManager, sessionOverride, trackingName);
     }
     let tmpPromptDir = null;
     let tmpPromptPath = null;
     let tmpOutputDir = null;
     const currentResult = {
         agent: agentName,
+        trackingName,
         agentSource: agent.source,
         task,
-        exitCode: 0,
+        exitCode: -1,
+        running: true,
         messages: [],
         stderr: "",
         usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
@@ -423,30 +488,63 @@ async function runSingleAgentInCmuxSplit(cmuxClient, directionOrSurfaceId, defau
             ? await cmuxClient.createSplit(directionOrSurfaceId)
             : directionOrSurfaceId;
         if (!cmuxSurfaceId) {
-            return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride);
+            return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride, contextMode, parentSessionManager, sessionOverride, trackingName);
         }
         const bundledPaths = (process.env.GSD_BUNDLED_EXTENSION_PATHS ?? "").split(path.delimiter).map((s) => s.trim()).filter(Boolean);
         const extensionArgs = bundledPaths.flatMap((p) => ["--extension", p]);
-        const processArgs = [process.env.GSD_BIN_PATH, ...extensionArgs, ...buildSubagentProcessArgs(agent, task, tmpPromptPath, modelOverride)];
+        const launch = createSubagentLaunchPlan({
+            agent,
+            task,
+            tmpPromptPath,
+            modelOverride,
+            contextMode,
+            parentSessionManager,
+            session: sessionOverride,
+            cwd,
+            defaultCwd,
+        });
+        if (launch.session.mode === "fork")
+            currentResult.sessionFile = launch.session.sessionFile;
+        const processArgs = [process.env.GSD_BIN_PATH, ...extensionArgs, ...launch.args];
         // Normalize all paths to forward slashes before embedding in bash strings.
         // On Windows, backslashes are interpreted as escape characters by bash,
         // mangling paths like C:\Users\user into C:Useruser (#1436).
         const bashPath = (p) => shellEscape(p.replaceAll("\\", "/"));
+        const envPrefix = buildShellEnvAssignments(launch.env).join(" ");
+        const commandPrefix = envPrefix ? `${envPrefix} ` : "";
         const innerScript = [
-            `cd ${bashPath(cwd ?? defaultCwd)}`,
+            `cd ${bashPath(launch.cwd)}`,
             "set -o pipefail",
-            `${bashPath(process.execPath)} ${processArgs.map(a => bashPath(a)).join(" ")} 2> >(tee ${bashPath(stderrPath)} >&2) | tee ${bashPath(stdoutPath)}`,
+            `${commandPrefix}${bashPath(process.execPath)} ${processArgs.map(a => bashPath(a)).join(" ")} 2> >(tee ${bashPath(stderrPath)} >&2) | tee ${bashPath(stdoutPath)}`,
             "status=${PIPESTATUS[0]}",
             `printf '%s' "$status" > ${bashPath(exitPath)}`,
         ].join("; ");
         const sent = await cmuxClient.sendSurface(cmuxSurfaceId, `bash -lc ${shellEscape(innerScript)}`);
         if (!sent) {
-            return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride);
+            return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride, contextMode, parentSessionManager, sessionOverride, trackingName);
         }
         const finished = await waitForFile(exitPath, signal);
         if (!finished) {
+            // Terminate the child running inside the cmux split: send Ctrl-C
+            // so bash interrupts the pipeline and writes the exit code, instead
+            // of leaving an orphaned subagent that can keep editing after cancel.
+            try {
+                await cmuxClient.sendInterrupt(cmuxSurfaceId);
+            }
+            catch {
+                /* ignore — best-effort */
+            }
+            // Give the shell a brief window to reap the killed child and write exit.code.
+            await waitForFile(exitPath, undefined, 5000);
             currentResult.exitCode = 1;
+            currentResult.running = false;
             currentResult.stderr = "cmux split execution timed out or was aborted";
+            if (fs.existsSync(stdoutPath)) {
+                const stdout = fs.readFileSync(stdoutPath, "utf-8");
+                for (const line of stdout.split("\n")) {
+                    processSubagentEventLine(line, currentResult, emitUpdate);
+                }
+            }
             return currentResult;
         }
         if (fs.existsSync(stdoutPath)) {
@@ -459,6 +557,7 @@ async function runSingleAgentInCmuxSplit(cmuxClient, directionOrSurfaceId, defau
             currentResult.stderr = fs.readFileSync(stderrPath, "utf-8");
         }
         currentResult.exitCode = Number.parseInt(fs.readFileSync(exitPath, "utf-8").trim() || "1", 10) || 0;
+        currentResult.running = false;
         return currentResult;
     }
     finally {
@@ -490,23 +589,44 @@ const TaskItem = Type.Object({
     task: Type.String({ description: "Task to delegate to the agent" }),
     cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
     model: Type.Optional(Type.String({ description: "Model override for this task (e.g. 'claude-sonnet-4-6')" })),
+    context: Type.Optional(StringEnum(["fresh", "fork"], {
+        description: 'Context mode for this task. "fresh" keeps the existing isolated context behavior; "fork" branches the parent session.',
+        default: "fresh",
+    })),
 });
 const ChainItem = Type.Object({
     agent: Type.String({ description: "Name of the agent to invoke" }),
     task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
     cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
     model: Type.Optional(Type.String({ description: "Model override for this step (e.g. 'claude-sonnet-4-6')" })),
+    context: Type.Optional(StringEnum(["fresh", "fork"], {
+        description: 'Context mode for this step. "fresh" keeps the existing isolated context behavior; "fork" branches the parent session.',
+        default: "fresh",
+    })),
 });
 const AgentScopeSchema = StringEnum(["user", "project", "both"], {
     description: 'Which agent directories to use. Default: "both" (user + project-local).',
     default: "both",
 });
+const ContextModeSchema = StringEnum(["fresh", "fork"], {
+    description: 'Context mode for delegated work. "fresh" is the default existing behavior; "fork" branches the parent session.',
+    default: "fresh",
+});
+const SubagentActionSchema = StringEnum(["launch", "status", "resume"], {
+    description: 'Run action. "launch" starts delegated work, "status" inspects a persisted run, and "resume" follows up a child session from a run.',
+    default: "launch",
+});
 const SubagentParams = Type.Object({
+    action: Type.Optional(SubagentActionSchema),
+    runId: Type.Optional(Type.String({ description: "Persisted subagent run id for status or resume actions" })),
     agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (for single mode)" })),
     task: Type.Optional(Type.String({ description: "Task to delegate (for single mode)" })),
     tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
     chain: Type.Optional(Type.Array(ChainItem, { description: "Array of {agent, task} for sequential execution" })),
     agentScope: Type.Optional(AgentScopeSchema),
+    context: Type.Optional(ContextModeSchema),
+    background: Type.Optional(Type.Boolean({ description: "Return after starting the run and keep status in the persisted run record. Default: false.", default: false })),
+    followUp: Type.Optional(Type.String({ description: "Follow-up instruction for resume action. Falls back to task when omitted." })),
     confirmProjectAgents: Type.Optional(Type.Boolean({ description: "Prompt before running project-local agents. Default: false.", default: false })),
     cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
     model: Type.Optional(Type.String({ description: "Model override for the subagent (e.g. 'claude-sonnet-4-6'). Takes precedence over the agent's frontmatter model." })),
@@ -518,6 +638,8 @@ const SubagentParams = Type.Object({
     })),
 });
 export default function (pi) {
+    if (isSubagentChildProcess())
+        return;
     pi.on("session_shutdown", async () => {
         await stopLiveSubagents();
     });
@@ -562,11 +684,16 @@ export default function (pi) {
             const confirmProjectAgents = params.confirmProjectAgents ?? false;
             const cmuxClient = CmuxClient.fromPreferences(loadEffectiveGSDPreferences()?.preferences);
             const cmuxSplitsEnabled = cmuxClient.getConfig().splits;
+            const runStore = new SubagentRunStore();
+            const action = params.action ?? "launch";
+            const contextMode = params.context ?? "fresh";
+            const taskParams = Array.isArray(params.tasks) ? params.tasks : [];
+            const chainParams = Array.isArray(params.chain) ? params.chain : [];
             // Resolve isolation mode
             const isolationMode = readIsolationMode();
             const useIsolation = Boolean(params.isolated) && isolationMode !== "none";
-            const hasChain = (params.chain?.length ?? 0) > 0;
-            const hasTasks = (params.tasks?.length ?? 0) > 0;
+            const hasChain = chainParams.length > 0;
+            const hasTasks = taskParams.length > 0;
             const hasSingle = Boolean(params.agent && params.task);
             const modeCount = Number(hasChain) + Number(hasTasks) + Number(hasSingle);
             const makeDetails = (mode) => (results) => ({
@@ -575,6 +702,68 @@ export default function (pi) {
                 projectAgentsDir: discovery.projectAgentsDir,
                 results,
             });
+            if (action === "status") {
+                if (!params.runId) {
+                    return {
+                        content: [{ type: "text", text: "Status requires runId." }],
+                        details: makeDetails("single")([]),
+                        isError: true,
+                    };
+                }
+                const record = runStore.get(params.runId);
+                return {
+                    content: [{ type: "text", text: formatRunRecord(record) }],
+                    details: makeDetails("single")([]),
+                    ...(record ? {} : { isError: true }),
+                };
+            }
+            if (action === "resume") {
+                if (!params.runId) {
+                    return {
+                        content: [{ type: "text", text: "Resume requires runId." }],
+                        details: makeDetails("single")([]),
+                        isError: true,
+                    };
+                }
+                const record = runStore.get(params.runId);
+                if (!record) {
+                    return {
+                        content: [{ type: "text", text: `Subagent run not found: ${params.runId}` }],
+                        details: makeDetails("single")([]),
+                        isError: true,
+                    };
+                }
+                const followUp = params.followUp ?? params.task;
+                if (!followUp) {
+                    return {
+                        content: [{ type: "text", text: "Resume requires followUp or task." }],
+                        details: makeDetails("single")([]),
+                        isError: true,
+                    };
+                }
+                const sessionChildren = record.children.filter((child) => child.sessionFile);
+                const matches = params.agent
+                    ? sessionChildren.filter((child) => child.agent === params.agent)
+                    : sessionChildren;
+                const selected = matches.length === 1 ? matches[0] : undefined;
+                if (!selected?.sessionFile) {
+                    const available = sessionChildren.map((child) => formatAgentLabel(child.agent, child.trackingName)).join(", ") || "none";
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Resume requires exactly one child session or an agent selector. Available resumable agents: ${available}`,
+                            }],
+                        details: makeDetails("single")([]),
+                        isError: true,
+                    };
+                }
+                const result = await runSingleAgent(ctx.cwd, agents, selected.agent, followUp, selected.cwd, undefined, signal, onUpdate, makeDetails("single"), params.model, "fresh", ctx.sessionManager, { mode: "fork", sessionFile: selected.sessionFile, sessionDir: path.dirname(selected.sessionFile) }, selected.trackingName);
+                return {
+                    content: [{ type: "text", text: getFinalOutput(result.messages) || result.errorMessage || result.stderr || "(no output)" }],
+                    details: makeDetails("single")([result]),
+                    ...(result.exitCode === 0 ? {} : { isError: true }),
+                };
+            }
             if (modeCount !== 1) {
                 const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
                 return {
@@ -592,16 +781,16 @@ export default function (pi) {
             // auto-mode flowId; per-dispatch ids still let us measure frequency, batch size, mode).
             const dispatchMode = hasChain ? "chain" : hasTasks ? "parallel" : "single";
             const dispatchAgents = hasChain
-                ? params.chain.map((s) => s.agent)
+                ? chainParams.map((s) => s.agent)
                 : hasTasks
-                    ? params.tasks.map((t) => t.agent)
+                    ? taskParams.map((t) => t.agent)
                     : params.agent
                         ? [params.agent]
                         : [];
             const dispatchTasks = hasChain
-                ? params.chain.map((s) => s.task)
+                ? chainParams.map((s) => s.task)
                 : hasTasks
-                    ? params.tasks.map((t) => t.task)
+                    ? taskParams.map((t) => t.task)
                     : params.task
                         ? [params.task]
                         : [];
@@ -609,6 +798,85 @@ export default function (pi) {
             const dispatchStartMs = Date.now();
             let finalResults = [];
             let dispatchCompletedEmitted = false;
+            const usedTrackingNames = new Set();
+            const dispatchTrackingNames = dispatchAgents.map(() => {
+                const trackingName = createSubagentTrackingName(usedTrackingNames);
+                usedTrackingNames.add(trackingName);
+                return trackingName;
+            });
+            const dispatchContextMode = hasChain && chainParams.some((step) => (step.context ?? contextMode) === "fork")
+                ? "fork"
+                : hasTasks && taskParams.some((task) => (task.context ?? contextMode) === "fork")
+                    ? "fork"
+                    : contextMode;
+            const dispatchChildren = dispatchAgents.map((agent, index) => ({
+                agent,
+                trackingName: dispatchTrackingNames[index],
+                task: dispatchTasks[index] ?? "",
+                cwd: hasChain
+                    ? chainParams[index]?.cwd
+                    : hasTasks
+                        ? taskParams[index]?.cwd
+                        : params.cwd,
+            }));
+            try {
+                runStore.create(createInitialRunRecord({
+                    runId: dispatchId,
+                    mode: dispatchMode,
+                    contextMode: dispatchContextMode,
+                    cwd: ctx.cwd,
+                    children: dispatchChildren,
+                }));
+            }
+            catch {
+                // Persistence is observability; execution remains authoritative.
+            }
+            const persistRunResults = (results, completed = false) => {
+                try {
+                    runStore.update(dispatchId, (record) => {
+                        const children = [...record.children];
+                        for (let index = 0; index < results.length; index++) {
+                            const result = results[index];
+                            if (!result)
+                                continue;
+                            children[index] = {
+                                ...children[index],
+                                ...resultToChildArtifact(result, index, children[index]?.cwd),
+                            };
+                        }
+                        if (completed) {
+                            for (let index = 0; index < children.length; index++) {
+                                const child = children[index];
+                                if (child.status === "queued" || child.status === "running") {
+                                    children[index] = {
+                                        ...child,
+                                        status: "failed",
+                                        completedAt: new Date().toISOString(),
+                                        errorMessage: "Subagent run ended before this child completed.",
+                                    };
+                                }
+                            }
+                        }
+                        const status = completed ? deriveRunStatus(children) : "running";
+                        const failed = children.find((child) => child.status === "failed");
+                        const interrupted = children.find((child) => child.status === "interrupted");
+                        return {
+                            ...record,
+                            children,
+                            status,
+                            ...(completed && status !== "running" ? { completedAt: new Date().toISOString() } : {}),
+                            ...(interrupted
+                                ? { failure: { type: "interrupted", message: interrupted.errorMessage || interrupted.stderr || "Subagent run was interrupted" } }
+                                : failed
+                                    ? { failure: { type: failed.merge?.success === false ? "merge-failed" : "child-failed", message: failed.errorMessage || failed.stderr || `Subagent ${failed.agent} failed` } }
+                                    : {}),
+                        };
+                    });
+                }
+                catch {
+                    // Persistence is observability; execution remains authoritative.
+                }
+            };
             emitJournalEvent(ctx.cwd, {
                 ts: new Date().toISOString(),
                 flowId: dispatchId,
@@ -633,10 +901,12 @@ export default function (pi) {
                 turns: 0,
             });
             const errorMessageFor = (err) => err instanceof Error ? err.message : String(err || "subagent dispatch failed");
-            const makeFailureResult = (err, agent, task, step) => {
+            const makeFailureResult = (err, agent, task, step, trackingName) => {
                 const message = errorMessageFor(err);
+                const dispatchIndex = dispatchAgents.findIndex((dispatchAgent, index) => dispatchAgent === agent && dispatchTasks[index] === task);
                 return {
                     agent,
+                    trackingName: trackingName ?? (dispatchIndex >= 0 ? dispatchTrackingNames[dispatchIndex] : undefined),
                     agentSource: "unknown",
                     task,
                     exitCode: 1,
@@ -671,18 +941,19 @@ export default function (pi) {
                     if (nextIndex > 0) {
                         return [
                             ...finalResults,
-                            makeFailureResult(err, dispatchAgents[nextIndex] ?? "unknown", dispatchTasks[nextIndex] ?? "", dispatchMode === "chain" ? nextIndex + 1 : undefined),
+                            makeFailureResult(err, dispatchAgents[nextIndex] ?? "unknown", dispatchTasks[nextIndex] ?? "", dispatchMode === "chain" ? nextIndex + 1 : undefined, dispatchTrackingNames[nextIndex]),
                         ];
                     }
                 }
                 const agentsForFailure = dispatchAgents.length > 0 ? dispatchAgents : ["unknown"];
-                return agentsForFailure.map((agent, index) => makeFailureResult(err, agent, dispatchTasks[index] ?? "", dispatchMode === "chain" ? index + 1 : undefined));
+                return agentsForFailure.map((agent, index) => makeFailureResult(err, agent, dispatchTasks[index] ?? "", dispatchMode === "chain" ? index + 1 : undefined, dispatchTrackingNames[index]));
             };
             const finishDispatch = (results) => {
                 if (dispatchCompletedEmitted)
                     return;
                 finalResults = results;
                 dispatchCompletedEmitted = true;
+                persistRunResults(results, true);
                 const successCount = results.filter((r) => r.exitCode === 0).length;
                 const failureCount = results.filter((r) => r.exitCode !== 0).length;
                 const totalCost = results.reduce((s, r) => s + (r.usage?.cost ?? 0), 0);
@@ -709,11 +980,11 @@ export default function (pi) {
             try {
                 if ((agentScope === "project" || agentScope === "both") && confirmProjectAgents && ctx.hasUI) {
                     const requestedAgentNames = new Set();
-                    if (params.chain)
-                        for (const step of params.chain)
+                    if (hasChain)
+                        for (const step of chainParams)
                             requestedAgentNames.add(step.agent);
-                    if (params.tasks)
-                        for (const t of params.tasks)
+                    if (hasTasks)
+                        for (const t of taskParams)
                             requestedAgentNames.add(t.agent);
                     if (params.agent)
                         requestedAgentNames.add(params.agent);
@@ -733,29 +1004,86 @@ export default function (pi) {
                         }
                     }
                 }
-                if (params.chain && params.chain.length > 0) {
+                if (params.background) {
+                    if (!params.agent || !params.task || hasTasks || hasChain) {
+                        const failure = makeFailureResult(new Error("Background launch currently requires single mode with agent and task."), params.agent ?? "unknown", params.task ?? "");
+                        finishDispatch([failure]);
+                        return {
+                            content: [{ type: "text", text: failure.errorMessage ?? failure.stderr }],
+                            details: makeDetails("single")([failure]),
+                            isError: true,
+                        };
+                    }
+                    void (async () => {
+                        let isolation = null;
+                        try {
+                            const effectiveCwd = params.cwd ?? ctx.cwd;
+                            if (useIsolation) {
+                                const taskId = crypto.randomUUID();
+                                isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
+                            }
+                            const result = await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, undefined, (partial) => {
+                                if (partial.details?.results[0])
+                                    persistRunResults([partial.details.results[0]]);
+                            }, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0]);
+                            if (isolation && result.exitCode === 0) {
+                                const patches = await isolation.captureDelta();
+                                if (patches.length > 0) {
+                                    const mergeResult = await mergeDeltaPatches(effectiveCwd, patches);
+                                    result.mergeResult = mergeResult;
+                                    if (!mergeResult.success) {
+                                        result.exitCode = 1;
+                                        result.stopReason = "error";
+                                        result.errorMessage = `Patch merge failed: ${mergeResult.error || "unknown error"}`;
+                                        result.stderr = result.stderr || result.errorMessage;
+                                    }
+                                }
+                            }
+                            finalResults = [result];
+                            finishDispatch([result]);
+                        }
+                        catch (err) {
+                            finalResults = synthesizeFailureResults(err);
+                            finishDispatch(finalResults);
+                        }
+                        finally {
+                            if (isolation)
+                                await isolation.cleanup();
+                        }
+                    })();
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Started background subagent run ${dispatchId}. Use action: "status" with runId: "${dispatchId}" to inspect it.`,
+                            }],
+                        details: makeDetails("single")([]),
+                    };
+                }
+                if (chainParams.length > 0) {
                     const results = [];
                     finalResults = results;
                     let previousOutput = "";
-                    for (let i = 0; i < params.chain.length; i++) {
-                        const step = params.chain[i];
+                    for (let i = 0; i < chainParams.length; i++) {
+                        const step = chainParams[i];
                         const taskWithContext = step.task.replace(/\{previous\}/g, previousOutput);
                         // Create update callback that includes all previous results
-                        const chainUpdate = onUpdate
-                            ? (partial) => {
-                                // Combine completed results with current streaming result
-                                const currentResult = partial.details?.results[0];
-                                if (currentResult) {
-                                    const allResults = [...results, currentResult];
+                        const chainUpdate = (partial) => {
+                            // Combine completed results with current streaming result
+                            const currentResult = partial.details?.results[0];
+                            if (currentResult) {
+                                const allResults = [...results, currentResult];
+                                persistRunResults(allResults);
+                                if (onUpdate) {
                                     onUpdate({
                                         content: partial.content,
                                         details: makeDetails("chain")(allResults),
                                     });
                                 }
                             }
-                            : undefined;
-                        const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), step.model || params.model);
+                        };
+                        const result = await runSingleAgent(ctx.cwd, agents, step.agent, taskWithContext, step.cwd, i + 1, signal, chainUpdate, makeDetails("chain"), step.model || params.model, step.context ?? contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[i]);
                         results.push(result);
+                        persistRunResults(results);
                         const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
                         if (isError) {
                             const errorMsg = result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
@@ -774,27 +1102,28 @@ export default function (pi) {
                         details: makeDetails("chain")(results),
                     };
                 }
-                if (params.tasks && params.tasks.length > 0) {
-                    if (params.tasks.length > MAX_PARALLEL_TASKS) {
+                if (taskParams.length > 0) {
+                    if (taskParams.length > MAX_PARALLEL_TASKS) {
                         finishDispatch([]);
                         return {
                             content: [
                                 {
                                     type: "text",
-                                    text: `Too many parallel tasks (${params.tasks.length}). Max is ${MAX_PARALLEL_TASKS}.`,
+                                    text: `Too many parallel tasks (${taskParams.length}). Max is ${MAX_PARALLEL_TASKS}.`,
                                 },
                             ],
                             details: makeDetails("parallel")([]),
                         };
                     }
                     // Track all results for streaming updates
-                    const allResults = new Array(params.tasks.length);
+                    const allResults = new Array(taskParams.length);
                     // Initialize placeholder results
-                    for (let i = 0; i < params.tasks.length; i++) {
+                    for (let i = 0; i < taskParams.length; i++) {
                         allResults[i] = {
-                            agent: params.tasks[i].agent,
+                            agent: taskParams[i].agent,
+                            trackingName: dispatchTrackingNames[i],
                             agentSource: "unknown",
-                            task: params.tasks[i].task,
+                            task: taskParams[i].task,
                             exitCode: -1, // -1 = still running
                             messages: [],
                             stderr: "",
@@ -816,27 +1145,53 @@ export default function (pi) {
                     };
                     const MAX_RETRIES = 1; // Retry failed tasks once
                     const batchId = crypto.randomUUID();
-                    const batchSize = params.tasks.length;
+                    const batchSize = taskParams.length;
                     // Pre-create a grid layout for cmux splits so agents get a clean tiled arrangement
                     const gridSurfaces = cmuxSplitsEnabled
                         ? await cmuxClient.createGridLayout(Math.min(batchSize, MAX_CONCURRENCY))
                         : [];
-                    const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
+                    const results = await mapWithConcurrencyLimit(taskParams, MAX_CONCURRENCY, async (t, index) => {
                         const workerId = registerWorker(t.agent, t.task, index, batchSize, batchId);
                         const taskModel = t.model || params.model;
-                        const runTask = () => cmuxSplitsEnabled
-                            ? runSingleAgentInCmuxSplit(cmuxClient, gridSurfaces[index] ?? (index % 2 === 0 ? "right" : "down"), ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
-                                if (partial.details?.results[0]) {
-                                    allResults[index] = partial.details.results[0];
-                                    emitParallelUpdate();
+                        const updateParallelResult = (partial) => {
+                            if (partial.details?.results[0]) {
+                                allResults[index] = partial.details.results[0];
+                                persistRunResults([...allResults]);
+                                emitParallelUpdate();
+                            }
+                        };
+                        const executeOnce = (runCwd) => cmuxSplitsEnabled
+                            ? runSingleAgentInCmuxSplit(cmuxClient, gridSurfaces[index] ?? (index % 2 === 0 ? "right" : "down"), ctx.cwd, agents, t.agent, t.task, runCwd, undefined, signal, updateParallelResult, makeDetails("parallel"), taskModel, t.context ?? contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[index])
+                            : runSingleAgent(ctx.cwd, agents, t.agent, t.task, runCwd, undefined, signal, updateParallelResult, makeDetails("parallel"), taskModel, t.context ?? contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[index]);
+                        const runTask = async () => {
+                            let isolation = null;
+                            const effectiveCwd = t.cwd ?? ctx.cwd;
+                            try {
+                                if (useIsolation) {
+                                    const taskId = crypto.randomUUID();
+                                    isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
                                 }
-                            }, makeDetails("parallel"), taskModel)
-                            : runSingleAgent(ctx.cwd, agents, t.agent, t.task, t.cwd, undefined, signal, (partial) => {
-                                if (partial.details?.results[0]) {
-                                    allResults[index] = partial.details.results[0];
-                                    emitParallelUpdate();
+                                const result = await executeOnce(isolation ? isolation.workDir : t.cwd);
+                                if (isolation && result.exitCode === 0) {
+                                    const patches = await isolation.captureDelta();
+                                    const mergeResult = patches.length > 0
+                                        ? await mergeDeltaPatches(effectiveCwd, patches)
+                                        : { success: true, appliedPatches: [], failedPatches: [] };
+                                    result.mergeResult = mergeResult;
+                                    if (!mergeResult.success) {
+                                        result.exitCode = 1;
+                                        result.stopReason = "error";
+                                        result.errorMessage = `Patch merge failed: ${mergeResult.error || "unknown error"}`;
+                                        result.stderr = result.stderr || result.errorMessage;
+                                    }
                                 }
-                            }, makeDetails("parallel"), taskModel);
+                                return result;
+                            }
+                            finally {
+                                if (isolation)
+                                    await isolation.cleanup();
+                            }
+                        };
                         let result = await runTask();
                         // Auto-retry failed tasks (likely API rate limit or transient error)
                         const isFailed = result.exitCode !== 0 || (result.messages.length === 0 && !signal?.aborted);
@@ -845,6 +1200,7 @@ export default function (pi) {
                         }
                         updateWorker(workerId, result.exitCode === 0 ? "completed" : "failed");
                         allResults[index] = result;
+                        persistRunResults([...allResults]);
                         emitParallelUpdate();
                         return result;
                     });
@@ -855,7 +1211,7 @@ export default function (pi) {
                         const output = isError
                             ? (r.errorMessage || r.stderr || getFinalOutput(r.messages) || "(no output)")
                             : getFinalOutput(r.messages);
-                        return `[${r.agent}] ${r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`}: ${output || "(no output)"}`;
+                        return `[${formatAgentLabel(r.agent, r.trackingName)}] ${r.exitCode === 0 ? "completed" : `failed (exit ${r.exitCode})`}: ${output || "(no output)"}`;
                     });
                     finishDispatch(results);
                     return {
@@ -877,15 +1233,28 @@ export default function (pi) {
                             const taskId = crypto.randomUUID();
                             isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
                         }
+                        const singleUpdate = (partial) => {
+                            if (partial.details?.results[0])
+                                persistRunResults([partial.details.results[0]]);
+                            if (onUpdate)
+                                onUpdate(partial);
+                        };
                         const result = cmuxSplitsEnabled
-                            ? await runSingleAgentInCmuxSplit(cmuxClient, "right", ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, onUpdate, makeDetails("single"), params.model)
-                            : await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, onUpdate, makeDetails("single"), params.model);
+                            ? await runSingleAgentInCmuxSplit(cmuxClient, "right", ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, singleUpdate, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0])
+                            : await runSingleAgent(ctx.cwd, agents, params.agent, params.task, isolation ? isolation.workDir : params.cwd, undefined, signal, singleUpdate, makeDetails("single"), params.model, contextMode, ctx.sessionManager, undefined, dispatchTrackingNames[0]);
                         finalResults = [result];
                         // Capture and merge delta if isolated
                         if (isolation) {
                             const patches = await isolation.captureDelta();
                             if (patches.length > 0) {
                                 mergeResult = await mergeDeltaPatches(effectiveCwd, patches);
+                                result.mergeResult = mergeResult;
+                                if (!mergeResult.success) {
+                                    result.exitCode = 1;
+                                    result.stopReason = "error";
+                                    result.errorMessage = `Patch merge failed: ${mergeResult.error || "unknown error"}`;
+                                    result.stderr = result.stderr || result.errorMessage;
+                                }
                             }
                         }
                         const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
@@ -927,7 +1296,8 @@ export default function (pi) {
                 throw err;
             }
             finally {
-                finishDispatch(finalResults);
+                if (!params.background)
+                    finishDispatch(finalResults);
             }
         },
         renderCall(args, theme) {
@@ -1004,7 +1374,7 @@ export default function (pi) {
                 const finalOutput = getFinalOutput(r.messages);
                 if (expanded) {
                     const container = new Container();
-                    let header = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+                    let header = `${icon} ${theme.fg("toolTitle", theme.bold(formatAgentLabel(r.agent, r.trackingName)))}${theme.fg("muted", ` (${r.agentSource})`)}`;
                     if (isError && r.stopReason)
                         header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
                     container.addChild(new Text(header, 0, 0));
@@ -1035,7 +1405,7 @@ export default function (pi) {
                     }
                     return container;
                 }
-                let text = `${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${theme.fg("muted", ` (${r.agentSource})`)}`;
+                let text = `${icon} ${theme.fg("toolTitle", theme.bold(formatAgentLabel(r.agent, r.trackingName)))}${theme.fg("muted", ` (${r.agentSource})`)}`;
                 if (isError && r.stopReason)
                     text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
                 if (isError && r.errorMessage)
@@ -1078,7 +1448,7 @@ export default function (pi) {
                         const displayItems = getDisplayItems(r.messages);
                         const finalOutput = getFinalOutput(r.messages);
                         container.addChild(new Spacer(1));
-                        container.addChild(new Text(`${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", r.agent)} ${rIcon}`, 0, 0));
+                        container.addChild(new Text(`${theme.fg("muted", `─── Step ${r.step}: `) + theme.fg("accent", formatAgentLabel(r.agent, r.trackingName))} ${rIcon}`, 0, 0));
                         container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
                         // Show tool calls
                         for (const item of displayItems) {
@@ -1110,7 +1480,7 @@ export default function (pi) {
                 for (const r of details.results) {
                     const rIcon = r.exitCode === 0 ? theme.fg("success", "✓") : theme.fg("error", "✗");
                     const displayItems = getDisplayItems(r.messages);
-                    text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", r.agent)} ${rIcon}`;
+                    text += `\n\n${theme.fg("muted", `─── Step ${r.step}: `)}${theme.fg("accent", formatAgentLabel(r.agent, r.trackingName))} ${rIcon}`;
                     if (displayItems.length === 0)
                         text += `\n${theme.fg("muted", "(no output)")}`;
                     else
@@ -1143,7 +1513,7 @@ export default function (pi) {
                         const displayItems = getDisplayItems(r.messages);
                         const finalOutput = getFinalOutput(r.messages);
                         container.addChild(new Spacer(1));
-                        container.addChild(new Text(`${theme.fg("muted", "─── ") + theme.fg("accent", r.agent)} ${rIcon}`, 0, 0));
+                        container.addChild(new Text(`${theme.fg("muted", "─── ") + theme.fg("accent", formatAgentLabel(r.agent, r.trackingName))} ${rIcon}`, 0, 0));
                         container.addChild(new Text(theme.fg("muted", "Task: ") + theme.fg("dim", r.task), 0, 0));
                         // Show tool calls
                         for (const item of displayItems) {
@@ -1176,7 +1546,7 @@ export default function (pi) {
                             ? theme.fg("success", "✓")
                             : theme.fg("error", "✗");
                     const displayItems = getDisplayItems(r.messages);
-                    text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", r.agent)} ${rIcon}`;
+                    text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", formatAgentLabel(r.agent, r.trackingName))} ${rIcon}`;
                     if (displayItems.length === 0)
                         text += `\n${theme.fg("muted", r.exitCode === -1 ? "(running...)" : "(no output)")}`;
                     else