lsd-pi 1.2.4 → 1.3.6

package/src/resources/extensions/subagent/index.ts

@@ -12,49 +12,240 @@
  * Uses JSON mode to capture structured output from subagents.
  */
 
-import { spawn, execFileSync, type ChildProcess } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentToolResult } from "@gsd/pi-agent-core";
-import type { Message } from "@gsd/pi-ai";
+import type { ImageContent, Message } from "@gsd/pi-ai";
 import { StringEnum } from "@gsd/pi-ai";
 import {
     type ExtensionAPI,
-    getAgentDir,
     getMarkdownTheme,
 } from "@gsd/pi-coding-agent";
 import { Container, Key, Markdown, Spacer, Text } from "@gsd/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { formatTokenCount, shortcutDesc } from "../shared/mod.js";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
-import { buildSubagentProcessArgs, getBundledExtensionPathsFromEnv } from "./launch-helpers.js";
 import {
     type IsolationEnvironment,
-    type IsolationMode,
     type MergeResult,
     createIsolation,
     mergeDeltaPatches,
     readIsolationMode,
 } from "./isolation.js";
 import { registerWorker, updateWorker } from "./worker-registry.js";
-import { handleSubagentPermissionRequest, isSubagentPermissionRequest } from "./approval-proxy.js";
 import { resolveConfiguredSubagentModel } from "./configured-model.js";
-import {
-    normalizeSubagentModel,
-    resolveSubagentModel,
-} from "./model-resolution.js";
+import { resolveSubagentModel } from "./model-resolution.js";
 import { loadEffectivePreferences } from "../shared/preferences.js";
+import {
+    readBudgetSubagentModelFromSettings,
+    runLegacySingleAgent,
+    stopLegacySubagents,
+} from "./legacy-runner.js";
+import {
+    MAX_IN_PROCESS_SUBAGENT_DEPTH,
+    startInProcessSingleAgent,
+    type SubagentHandle,
+} from "./in-process-runner.js";
 import { CmuxClient, shellEscape } from "../cmux/index.js";
 import { BackgroundJobManager, type BackgroundSubagentJob } from "./background-job-manager.js";
 import { runSubagentInBackground } from "./background-runner.js";
+import { showAgentSwitcher } from "./agent-switcher-component.js";
+import {
+    buildAgentSwitchTargets,
+    type AgentSwitchTarget,
+} from "./agent-switcher-model.js";
 
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
 const COLLAPSED_ITEM_COUNT = 10;
 const DEFAULT_AWAIT_SUBAGENT_TIMEOUT_SECONDS = 120;
-const liveSubagentProcesses = new Set<ChildProcess>();
+const USE_IN_PROCESS_SUBAGENT = process.env.LSD_SUBAGENT_IN_PROCESS !== "0";
+
+type AgentSessionState = "running" | "completed" | "failed";
+
+interface AgentSessionLink {
+    id: string;
+    agentName: string;
+    task: string;
+    parentSessionFile: string;
+    subagentSessionFile: string;
+    createdAt: number;
+    updatedAt: number;
+    state: AgentSessionState;
+}
+
+const agentSessionLinksById = new Map<string, AgentSessionLink>();
+const agentSessionIdsByParent = new Map<string, string[]>();
+const parentSessionByChild = new Map<string, string>();
+
+interface LiveSubagentRuntime {
+    sessionFile?: string;
+    parentSessionFile?: string;
+    agentName: string;
+    isBusy: () => boolean;
+    sendPrompt: (text: string, images?: ImageContent[]) => Promise<void>;
+    sendSteer: (text: string, images?: ImageContent[]) => Promise<void>;
+    sendFollowUp: (text: string, images?: ImageContent[]) => Promise<void>;
+}
+
+const liveRuntimeBySessionFile = new Map<string, LiveSubagentRuntime>();
+const inProcessSubagentDepthBySessionId = new Map<string, number>();
+const inProcessSubagentAncestryBySessionId = new Map<string, string[]>();
+let agentSessionLinkCounter = 0;
+
+function listSessionFiles(sessionDir: string): string[] {
+    if (!fs.existsSync(sessionDir)) return [];
+    try {
+        return fs
+            .readdirSync(sessionDir)
+            .filter((name) => name.endsWith(".jsonl"))
+            .map((name) => path.join(sessionDir, name));
+    } catch {
+        return [];
+    }
+}
+
+function registerAgentSessionLink(link: Omit<AgentSessionLink, "id" | "createdAt" | "updatedAt">): AgentSessionLink {
+    const now = Date.now();
+    const id = `agent-${++agentSessionLinkCounter}`;
+    const full: AgentSessionLink = { ...link, id, createdAt: now, updatedAt: now };
+    agentSessionLinksById.set(id, full);
+    const list = agentSessionIdsByParent.get(link.parentSessionFile) ?? [];
+    list.push(id);
+    agentSessionIdsByParent.set(link.parentSessionFile, list);
+    parentSessionByChild.set(link.subagentSessionFile, link.parentSessionFile);
+    return full;
+}
+
+function updateAgentSessionLinkState(subagentSessionFile: string, state: AgentSessionState): void {
+    for (const link of agentSessionLinksById.values()) {
+        if (link.subagentSessionFile === subagentSessionFile) {
+            link.state = state;
+            link.updatedAt = Date.now();
+            return;
+        }
+    }
+}
+
+function upsertAgentSessionLink(
+    agentName: string,
+    task: string,
+    parentSessionFile: string,
+    subagentSessionFile: string,
+    state: AgentSessionState,
+): void {
+    const existingParent = parentSessionByChild.get(subagentSessionFile);
+    if (!existingParent) {
+        registerAgentSessionLink({
+            agentName,
+            task,
+            parentSessionFile,
+            subagentSessionFile,
+            state,
+        });
+        return;
+    }
+
+    updateAgentSessionLinkState(subagentSessionFile, state);
+}
+
+function getAgentSessionLinksForParent(parentSessionFile: string): AgentSessionLink[] {
+    const ids = agentSessionIdsByParent.get(parentSessionFile) ?? [];
+    return ids
+        .map((id) => agentSessionLinksById.get(id))
+        .filter((entry): entry is AgentSessionLink => Boolean(entry))
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+}
+
+function readSessionHeader(sessionFile: string): {
+    parentSession?: string;
+    subagentName?: string;
+    subagentTask?: string;
+    subagentSystemPrompt?: string;
+    subagentTools?: string[];
+} | null {
+    try {
+        const content = fs.readFileSync(sessionFile, "utf-8");
+        const firstLine = content.split("\n").find((line) => line.trim().length > 0);
+        if (!firstLine) return null;
+        const parsed = JSON.parse(firstLine);
+        if (!parsed || parsed.type !== "session") return null;
+        return {
+            parentSession: typeof parsed.parentSession === "string" ? parsed.parentSession : undefined,
+            subagentName: typeof parsed.subagentName === "string" ? parsed.subagentName : undefined,
+            subagentTask: typeof parsed.subagentTask === "string" ? parsed.subagentTask : undefined,
+            subagentSystemPrompt: typeof parsed.subagentSystemPrompt === "string" ? parsed.subagentSystemPrompt : undefined,
+            subagentTools: Array.isArray(parsed.subagentTools)
+                ? parsed.subagentTools.filter((tool: unknown): tool is string => typeof tool === "string")
+                : undefined,
+        };
+    } catch {
+        return null;
+    }
+}
+
+function backfillAgentSessionLinksForParent(parentSessionFile: string, sessionDir: string): AgentSessionLink[] {
+    for (const sessionFile of listSessionFiles(sessionDir)) {
+        if (sessionFile === parentSessionFile) continue;
+        const header = readSessionHeader(sessionFile);
+        if (header?.parentSession !== parentSessionFile) continue;
+        const existingParent = parentSessionByChild.get(sessionFile);
+        if (!existingParent) {
+            registerAgentSessionLink({
+                agentName: header.subagentName ?? "subagent",
+                task: header.subagentTask ?? "Recovered from persisted session lineage",
+                parentSessionFile,
+                subagentSessionFile: sessionFile,
+                state: "completed",
+            });
+        }
+    }
+    return getAgentSessionLinksForParent(parentSessionFile);
+}
+
+function formatSwitchTargetSummary(target: AgentSwitchTarget): string {
+    const current = target.isCurrent ? " (current)" : "";
+    if (target.kind === "parent") {
+        return `● parent — main session${current}`;
+    }
+
+    const icon = target.state === "running" ? "▶" : target.state === "failed" ? "✗" : "✓";
+    return `${icon} ${target.agentName} — ${target.taskPreview}${current}`;
+}
+
+function buildSwitchTargetsForParent(
+    parentSessionFile: string,
+    currentSessionFile: string,
+    currentCwd: string,
+    trackedLinks: AgentSessionLink[],
+    runningJobs: BackgroundSubagentJob[],
+): AgentSwitchTarget[] {
+    return buildAgentSwitchTargets({
+        currentSessionFile,
+        rootParentSessionFile: parentSessionFile,
+        currentCwd,
+        trackedLinks: trackedLinks.map((link) => ({
+            id: link.id,
+            agentName: link.agentName,
+            task: link.task,
+            parentSessionFile: link.parentSessionFile,
+            subagentSessionFile: link.subagentSessionFile,
+            updatedAt: link.updatedAt,
+            state: link.state,
+        })),
+        runningJobs: runningJobs.map((job) => ({
+            id: job.id,
+            agentName: job.agentName,
+            task: job.task,
+            startedAt: job.startedAt,
+            parentSessionFile: job.parentSessionFile,
+            sessionFile: job.sessionFile,
+            cwd: job.cwd,
+        })),
+    });
+}
 
 const AwaitSubagentParams = Type.Object({
     jobs: Type.Optional(
@@ -72,40 +263,7 @@ const AwaitSubagentParams = Type.Object({
 });
 
 export async function stopLiveSubagents(): Promise<void> {
-    const active = Array.from(liveSubagentProcesses);
-    if (active.length === 0) return;
-
-    for (const proc of active) {
-        try {
-            proc.kill("SIGTERM");
-        } catch {
-            /* ignore */
-        }
-    }
-
-    await Promise.all(
-        active.map(
-            (proc) =>
-                new Promise<void>((resolve) => {
-                    const done = () => resolve();
-                    const timer = setTimeout(done, 500);
-                    proc.once("exit", () => {
-                        clearTimeout(timer);
-                        resolve();
-                    });
-                }),
-        ),
-    );
-
-    for (const proc of active) {
-        if (proc.exitCode === null) {
-            try {
-                proc.kill("SIGKILL");
-            } catch {
-                /* ignore */
-            }
-        }
-    }
+    await stopLegacySubagents();
 }
 
 function formatBackgroundSubagentResults(jobs: BackgroundSubagentJob[]): string {
@@ -325,20 +483,8 @@ interface SingleResult {
     errorMessage?: string;
     step?: number;
     backgroundJobId?: string;
-}
-
-interface ForegroundSingleRunControl {
-    agentName: string;
-    task: string;
-    cwd: string;
-    abortController: AbortController;
-    resultPromise: Promise<{ summary: string; stderr: string; exitCode: number; model?: string }>;
-    adoptToBackground: (jobId: string) => boolean;
-}
-
-interface ForegroundSingleRunHooks {
-    onStart?: (control: ForegroundSingleRunControl) => void;
-    onFinish?: () => void;
+    sessionFile?: string;
+    parentSessionFile?: string;
 }
 
 interface SubagentDetails {
@@ -395,343 +541,8 @@ async function mapWithConcurrencyLimit<TIn, TOut>(
     return results;
 }
 
-function writePromptToTempFile(agentName: string, prompt: string): { dir: string; filePath: string } {
-    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
-    const safeName = agentName.replace(/[^\w.-]+/g, "_");
-    const filePath = path.join(tmpDir, `prompt-${safeName}.md`);
-    fs.writeFileSync(filePath, prompt, { encoding: "utf-8", mode: 0o600 });
-    return { dir: tmpDir, filePath };
-}
-
-function readBudgetSubagentModelFromSettings(): string | undefined {
-    try {
-        const settingsPath = path.join(getAgentDir(), "settings.json");
-        if (!fs.existsSync(settingsPath)) return undefined;
-        const raw = fs.readFileSync(settingsPath, "utf-8");
-        const parsed = JSON.parse(raw) as { budgetSubagentModel?: unknown };
-        return typeof parsed.budgetSubagentModel === "string"
-            ? normalizeSubagentModel(parsed.budgetSubagentModel)
-            : undefined;
-    } catch {
-        return undefined;
-    }
-}
-
-function resolveSubagentCliPath(defaultCwd: string): string | null {
-    const candidates = [process.env.GSD_BIN_PATH, process.env.LSD_BIN_PATH, process.argv[1]]
-        .map((value) => value?.trim())
-        .filter((value): value is string => Boolean(value && value !== "undefined"));
-
-    for (const candidate of candidates) {
-        if (path.isAbsolute(candidate) && fs.existsSync(candidate)) return candidate;
-    }
-
-    const cwdCandidates = [path.join(defaultCwd, "dist", "loader.js"), path.join(defaultCwd, "scripts", "dev-cli.js")];
-    for (const candidate of cwdCandidates) {
-        if (fs.existsSync(candidate)) return candidate;
-    }
-
-    for (const binName of ["lsd", "gsd"]) {
-        try {
-            const resolved = execFileSync("which", [binName], { encoding: "utf-8" }).trim();
-            if (resolved) return resolved;
-        } catch {
-            /* ignore */
-        }
-    }
-
-    return null;
-}
-
-function processSubagentEventLine(
-    line: string,
-    currentResult: SingleResult,
-    emitUpdate: () => void,
-    proc?: ChildProcess,
-): boolean {
-    if (!line.trim()) return false;
-    let event: any;
-    try {
-        event = JSON.parse(line);
-    } catch {
-        return false;
-    }
-
-    if (proc && isSubagentPermissionRequest(event)) {
-        void handleSubagentPermissionRequest(event, proc);
-        return false;
-    }
-
-    if ((event.type === "message_end" || event.type === "turn_end") && event.message) {
-        const msg = event.message as Message;
-        currentResult.messages.push(msg);
-
-        if (msg.role === "assistant") {
-            currentResult.usage.turns++;
-            const usage = msg.usage;
-            if (usage) {
-                currentResult.usage.input += usage.input || 0;
-                currentResult.usage.output += usage.output || 0;
-                currentResult.usage.cacheRead += usage.cacheRead || 0;
-                currentResult.usage.cacheWrite += usage.cacheWrite || 0;
-                currentResult.usage.cost += usage.cost?.total || 0;
-                currentResult.usage.contextTokens = usage.totalTokens || 0;
-            }
-            if (msg.model && (!currentResult.model || msg.model.includes("/"))) currentResult.model = msg.model;
-            if (msg.stopReason) currentResult.stopReason = msg.stopReason;
-            if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
-        }
-        emitUpdate();
-    }
-
-    if (event.type === "tool_result_end" && event.message) {
-        currentResult.messages.push(event.message as Message);
-        emitUpdate();
-    }
-
-    return event.type === "agent_end";
-}
-
-async function waitForFile(filePath: string, signal: AbortSignal | undefined, timeoutMs = 30 * 60 * 1000): Promise<boolean> {
-    const started = Date.now();
-    while (Date.now() - started < timeoutMs) {
-        if (signal?.aborted) return false;
-        if (fs.existsSync(filePath)) return true;
-        await new Promise((resolve) => setTimeout(resolve, 150));
-    }
-    return false;
-}
-
 type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
-async function runSingleAgent(
-    defaultCwd: string,
-    agents: AgentConfig[],
-    agentName: string,
-    task: string,
-    cwd: string | undefined,
-    step: number | undefined,
-    modelOverride: string | undefined,
-    parentModel: { provider: string; id: string } | undefined,
-    signal: AbortSignal | undefined,
-    onUpdate: OnUpdateCallback | undefined,
-    makeDetails: (results: SingleResult[]) => SubagentDetails,
-    foregroundHooks?: ForegroundSingleRunHooks,
-): Promise<SingleResult> {
-    const agent = agents.find((a) => a.name === agentName);
-
-    if (!agent) {
-        const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
-        return {
-            agent: agentName,
-            agentSource: "unknown",
-            task,
-            exitCode: 1,
-            messages: [],
-            stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
-            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-            step,
-        };
-    }
-
-    let tmpPromptDir: string | null = null;
-    let tmpPromptPath: string | null = null;
-
-    const preferences = loadEffectivePreferences()?.preferences;
-    const settingsBudgetModel = readBudgetSubagentModelFromSettings();
-    const resolvedModel = resolveConfiguredSubagentModel(agent, preferences, settingsBudgetModel);
-    const inferredModel = resolveSubagentModel(
-        { name: agent.name, model: resolvedModel },
-        { overrideModel: modelOverride, parentModel },
-    );
-
-    const currentResult: SingleResult = {
-        agent: agentName,
-        agentSource: agent.source,
-        task,
-        exitCode: 0,
-        messages: [],
-        stderr: "",
-        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-        model: inferredModel,
-        step,
-    };
-
-    const emitUpdate = () => {
-        if (onUpdate) {
-            onUpdate({
-                content: [{ type: "text", text: getFinalOutput(currentResult.messages) || "(running...)" }],
-                details: makeDetails([currentResult]),
-            });
-        }
-    };
-
-    let wasAborted = false;
-    let deferTempPromptCleanup = false;
-    let tempPromptCleanupDone = false;
-
-    const cleanupTempPromptFiles = () => {
-        if (tempPromptCleanupDone) return;
-        tempPromptCleanupDone = true;
-        if (tmpPromptPath)
-            try {
-                fs.unlinkSync(tmpPromptPath);
-            } catch {
-                /* ignore */
-            }
-        if (tmpPromptDir)
-            try {
-                fs.rmdirSync(tmpPromptDir);
-            } catch {
-                /* ignore */
-            }
-    };
-
-    try {
-        if (agent.systemPrompt.trim()) {
-            const tmp = writePromptToTempFile(agent.name, agent.systemPrompt);
-            tmpPromptDir = tmp.dir;
-            tmpPromptPath = tmp.filePath;
-        }
-        const args = buildSubagentProcessArgs(agent, task, tmpPromptPath, inferredModel);
-
-        const exitCode = await new Promise<number>((resolve) => {
-            const bundledPaths = getBundledExtensionPathsFromEnv();
-            const extensionArgs = bundledPaths.flatMap((p) => ["--extension", p]);
-            const cliPath = resolveSubagentCliPath(cwd ?? defaultCwd);
-            if (!cliPath) {
-                currentResult.stderr += "Unable to resolve LSD/GSD CLI path for subagent launch.";
-                resolve(1);
-                return;
-            }
-            const proc = spawn(
-                process.execPath,
-                [cliPath, ...extensionArgs, ...args],
-                { cwd: cwd ?? defaultCwd, shell: false, stdio: ["pipe", "pipe", "pipe"] },
-            );
-            // Keep stdin open so approval/classifier responses can be proxied back
-            // into the child process. Closing it here can leave the subagent stuck
-            // after its first turn when it requests permission for a tool call.
-            liveSubagentProcesses.add(proc);
-            let buffer = "";
-            let completionSeen = false;
-            let resolved = false;
-            let foregroundReleased = false;
-            const procAbortController = new AbortController();
-            let resolveBackgroundResult: ((value: { summary: string; stderr: string; exitCode: number; model?: string }) => void) | undefined;
-            let rejectBackgroundResult: ((reason?: unknown) => void) | undefined;
-            const backgroundResultPromise = new Promise<{ summary: string; stderr: string; exitCode: number; model?: string }>((resolveBg, rejectBg) => {
-                resolveBackgroundResult = resolveBg;
-                rejectBackgroundResult = rejectBg;
-            });
-
-            const finishForeground = (code: number) => {
-                if (resolved) return;
-                resolved = true;
-                resolve(code);
-            };
-
-            const adoptToBackground = (jobId: string): boolean => {
-                if (resolved || foregroundReleased) return false;
-                foregroundReleased = true;
-                deferTempPromptCleanup = true;
-                currentResult.backgroundJobId = jobId;
-                finishForeground(0);
-                return true;
-            };
-
-            backgroundResultPromise.finally(() => {
-                if (deferTempPromptCleanup) cleanupTempPromptFiles();
-            });
-
-            foregroundHooks?.onStart?.({
-                agentName,
-                task,
-                cwd: cwd ?? defaultCwd,
-                abortController: procAbortController,
-                resultPromise: backgroundResultPromise,
-                adoptToBackground,
-            });
-
-            proc.stdout.on("data", (data) => {
-                buffer += data.toString();
-                const lines = buffer.split("\n");
-                buffer = lines.pop() || "";
-                for (const line of lines) {
-                    if (processSubagentEventLine(line, currentResult, emitUpdate, proc)) {
-                        completionSeen = true;
-                        try {
-                            proc.kill("SIGTERM");
-                        } catch {
-                            /* ignore */
-                        }
-                    }
-                }
-            });
-
-            proc.stderr.on("data", (data) => {
-                currentResult.stderr += data.toString();
-            });
-
-            proc.on("close", (code) => {
-                liveSubagentProcesses.delete(proc);
-                if (buffer.trim()) {
-                    const completedOnFlush = processSubagentEventLine(buffer, currentResult, emitUpdate, proc);
-                    completionSeen = completionSeen || completedOnFlush;
-                }
-                const finalExitCode = completionSeen && (code === null || code === 143 || code === 15) ? 0 : (code ?? 0);
-                currentResult.exitCode = finalExitCode;
-                resolveBackgroundResult?.({
-                    summary: getFinalOutput(currentResult.messages),
-                    stderr: currentResult.stderr,
-                    exitCode: finalExitCode,
-                    model: currentResult.model,
-                });
-                foregroundHooks?.onFinish?.();
-                finishForeground(finalExitCode);
-            });
-
-            proc.on("error", (error) => {
-                liveSubagentProcesses.delete(proc);
-                rejectBackgroundResult?.(error);
-                foregroundHooks?.onFinish?.();
-                finishForeground(1);
-            });
-
-            const killProc = () => {
-                wasAborted = true;
-                procAbortController.abort();
-                proc.kill("SIGTERM");
-                setTimeout(() => {
-                    if (!proc.killed) proc.kill("SIGKILL");
-                }, 5000);
-            };
-
-            if (signal) {
-                if (signal.aborted) killProc();
-                else signal.addEventListener("abort", killProc, { once: true });
-            }
-
-            if (procAbortController.signal.aborted) {
-                killProc();
-            } else {
-                procAbortController.signal.addEventListener("abort", () => {
-                    proc.kill("SIGTERM");
-                    setTimeout(() => {
-                        if (!proc.killed) proc.kill("SIGKILL");
-                    }, 5000);
-                }, { once: true });
-            }
-        });
-
-        currentResult.exitCode = exitCode;
-        if (wasAborted) throw new Error("Subagent was aborted");
-        return currentResult;
-    } finally {
-        if (!deferTempPromptCleanup) cleanupTempPromptFiles();
-    }
-}
-
 const TaskItem = Type.Object({
     agent: Type.String({ description: "Name of the agent to invoke" }),
     task: Type.String({ description: "Task to delegate to the agent" }),
@@ -803,17 +614,91 @@ export default function(pi: ExtensionAPI) {
     let bgManager: BackgroundJobManager | null = null;
     const foregroundSubagentStatusKey = "foreground-subagent";
     const foregroundSubagentHint = "Ctrl+B: move foreground subagent to background";
-    type ActiveForegroundSubagent = ForegroundSingleRunControl & { claimed: boolean };
+    type ActiveForegroundSubagent = {
+        claimed: boolean;
+        agentName: string;
+        task: string;
+        cwd: string;
+        parentSessionFile?: string;
+        resultPromise: Promise<{
+            summary: string;
+            stderr: string;
+            exitCode: number;
+            model?: string;
+            sessionFile?: string;
+            parentSessionFile?: string;
+        }>;
+        adoptToBackground: (jobId: string) => boolean;
+        abortController?: AbortController;
+        handle?: SubagentHandle;
+        sendPrompt?: (text: string, images?: ImageContent[]) => Promise<void>;
+        sendSteer?: (text: string, images?: ImageContent[]) => Promise<void>;
+        sendFollowUp?: (text: string, images?: ImageContent[]) => Promise<void>;
+        isBusy?: () => boolean;
+    };
     let activeForegroundSubagent: ActiveForegroundSubagent | null = null;
+    let activeSessionFileForUi: string | undefined;
+    const liveStreamBufferBySession = new Map<string, string>();
+
+    function flushLiveStream(sessionFile: string): void {
+        const buffered = liveStreamBufferBySession.get(sessionFile);
+        if (!buffered || !buffered.trim()) return;
+        liveStreamBufferBySession.set(sessionFile, "");
+        pi.sendMessage(
+            {
+                customType: "live_subagent_stream",
+                content: buffered,
+                display: true,
+            },
+            { deliverAs: "followUp" },
+        );
+    }
+
+    function pushLiveStreamDelta(sessionFile: string, delta: string): void {
+        const prev = liveStreamBufferBySession.get(sessionFile) ?? "";
+        const next = prev + delta;
+        liveStreamBufferBySession.set(sessionFile, next);
+        if (next.length >= 120 || next.includes("\n")) {
+            flushLiveStream(sessionFile);
+        }
+    }
+
+    function getCurrentSessionSubagentMetadata(sessionFile: string | undefined) {
+        if (!sessionFile) return null;
+        return readSessionHeader(sessionFile);
+    }
+
+    function applyCurrentSessionSubagentTools(ctx: any): void {
+        const metadata = getCurrentSessionSubagentMetadata(ctx.sessionManager.getSessionFile());
+        if (metadata?.subagentTools && metadata.subagentTools.length > 0) {
+            ctx.setActiveTools(metadata.subagentTools);
+        }
+    }
 
     function getBgManager(): BackgroundJobManager {
         if (!bgManager) throw new Error("BackgroundJobManager not initialized.");
         return bgManager;
     }
 
-    pi.on("session_start", async () => {
+    pi.on("session_start", async (_event, ctx) => {
+        activeSessionFileForUi = ctx.sessionManager.getSessionFile();
         bgManager = new BackgroundJobManager({
             onJobComplete: (job) => {
+                if (job.sessionFile && job.parentSessionFile) {
+                    const existingParent = parentSessionByChild.get(job.sessionFile);
+                    if (!existingParent) {
+                        registerAgentSessionLink({
+                            agentName: job.agentName,
+                            task: job.task,
+                            parentSessionFile: job.parentSessionFile,
+                            subagentSessionFile: job.sessionFile,
+                            state: job.status === "failed" ? "failed" : "completed",
+                        });
+                    } else {
+                        updateAgentSessionLinkState(job.sessionFile, job.status === "failed" ? "failed" : "completed");
+                    }
+                }
+
                 if (job.awaited) return;
                 const statusEmoji = job.status === "completed" ? "✓" : job.status === "cancelled" ? "✗ cancelled" : "✗ failed";
                 const elapsed = ((Date.now() - job.startedAt) / 1000).toFixed(1);
@@ -839,25 +724,94 @@ export default function(pi: ExtensionAPI) {
                 );
             },
         });
+        applyCurrentSessionSubagentTools(ctx);
     });
 
+    pi.on("session_switch", async (_event, ctx) => {
+        activeSessionFileForUi = ctx.sessionManager.getSessionFile();
+        applyCurrentSessionSubagentTools(ctx);
+    });
 
-    pi.on("session_before_switch", async () => {
-        activeForegroundSubagent = null;
-        if (bgManager) {
-            for (const job of bgManager.getRunningJobs()) {
-                bgManager.cancel(job.id);
+    pi.on("before_agent_start", async (event, ctx) => {
+        const metadata = getCurrentSessionSubagentMetadata(ctx.sessionManager.getSessionFile());
+        if (!metadata?.subagentSystemPrompt) return;
+        const subagentName = metadata.subagentName ?? "subagent";
+        const taskNote = metadata.subagentTask
+            ? `Original delegated task: ${metadata.subagentTask}`
+            : "Continue operating as the delegated subagent for this session.";
+        const antiRecursion = [
+            `You are already the ${subagentName} subagent for this session.`,
+            "Do not spawn or delegate to another subagent with the same name as yourself.",
+            `If the user asks you to continue ${subagentName} work, do that work directly in this session.`,
+            taskNote,
+        ].join("\n");
+        return {
+            systemPrompt: `${event.systemPrompt}\n\n${antiRecursion}\n\n${metadata.subagentSystemPrompt}`,
+        };
+    });
+    pi.on("input", async (event, ctx) => {
+        const sessionFile = ctx.sessionManager.getSessionFile();
+        const runtimeFromSession = sessionFile ? liveRuntimeBySessionFile.get(sessionFile) : undefined;
+        const runtimeFromForeground = (!runtimeFromSession && activeForegroundSubagent && !activeForegroundSubagent.claimed &&
+            activeForegroundSubagent.sendPrompt && activeForegroundSubagent.sendSteer && activeForegroundSubagent.sendFollowUp && activeForegroundSubagent.isBusy &&
+            sessionFile && activeForegroundSubagent.parentSessionFile === sessionFile)
+            ? {
+                agentName: activeForegroundSubagent.agentName,
+                isBusy: activeForegroundSubagent.isBusy,
+                sendPrompt: activeForegroundSubagent.sendPrompt,
+                sendSteer: activeForegroundSubagent.sendSteer,
+                sendFollowUp: activeForegroundSubagent.sendFollowUp,
+            }
+            : undefined;
+        const runtime = runtimeFromSession ?? runtimeFromForeground;
+        if (!runtime) return;
+
+        const text = event.text?.trim();
+        if (!text) return { action: "handled" as const };
+
+        const isSlashCommand = text.startsWith("/");
+        if (isSlashCommand) return;
+
+        try {
+            if (runtime.isBusy()) {
+                await runtime.sendSteer(text, event.images);
+                ctx.ui.notify(`Sent steer to running subagent ${runtime.agentName}.`, "info");
+            } else {
+                await runtime.sendPrompt(text, event.images);
+                ctx.ui.notify(`Sent prompt to live subagent ${runtime.agentName}.`, "info");
             }
+            return { action: "handled" as const };
+        } catch (error) {
+            ctx.ui.notify(
+                `Failed to send input to live subagent ${runtime.agentName}: ${error instanceof Error ? error.message : String(error)}`,
+                "error",
+            );
+            return { action: "handled" as const };
         }
     });
 
+
+    pi.on("session_before_switch", async () => {
+        if (activeSessionFileForUi) flushLiveStream(activeSessionFileForUi);
+        activeForegroundSubagent = null;
+    });
+
     pi.on("session_shutdown", async () => {
+        if (activeSessionFileForUi) flushLiveStream(activeSessionFileForUi);
+        activeSessionFileForUi = undefined;
         activeForegroundSubagent = null;
         await stopLiveSubagents();
         if (bgManager) {
             bgManager.shutdown();
             bgManager = null;
         }
+        agentSessionLinksById.clear();
+        agentSessionIdsByParent.clear();
+        parentSessionByChild.clear();
+        liveRuntimeBySessionFile.clear();
+        inProcessSubagentDepthBySessionId.clear();
+        inProcessSubagentAncestryBySessionId.clear();
+        liveStreamBufferBySession.clear();
     });
 
     // /subagents command
@@ -972,6 +926,189 @@ export default function(pi: ExtensionAPI) {
         },
     });
 
+    // /agent command - switch to the parent or a tracked subagent session
+    pi.registerCommand("agent", {
+        description: "Switch focus to parent/subagent sessions (/agent picker, /agent <id|index|name>, /agent parent)",
+        handler: async (args: string, ctx) => {
+            const currentSessionFile = ctx.sessionManager.getSessionFile();
+            if (!currentSessionFile) {
+                ctx.ui.notify("Current session is in-memory only; /agent requires a persisted session file.", "warning");
+                return;
+            }
+
+            const arg = args.trim();
+            const parentSessionFile = parentSessionByChild.get(currentSessionFile);
+            const currentParent = parentSessionFile ?? currentSessionFile;
+            const currentSessionDir = path.dirname(currentParent);
+
+            let tracked = getAgentSessionLinksForParent(currentParent).filter((entry) => fs.existsSync(entry.subagentSessionFile));
+            if (tracked.length === 0) {
+                tracked = backfillAgentSessionLinksForParent(currentParent, currentSessionDir)
+                    .filter((entry) => fs.existsSync(entry.subagentSessionFile));
+            }
+
+            const runningJobs = bgManager?.getRunningJobs() ?? [];
+            const switchTargets = buildSwitchTargetsForParent(
+                currentParent,
+                currentSessionFile,
+                ctx.cwd,
+                tracked,
+                runningJobs,
+            );
+
+            const applySwitchTarget = async (target: AgentSwitchTarget): Promise<void> => {
+                if (target.selectionAction === "blocked") {
+                    ctx.ui.notify(target.blockedReason ?? "That target cannot be selected yet.", "warning");
+                    return;
+                }
+
+                if (target.selectionAction === "attach_live") {
+                    if (!fs.existsSync(target.sessionFile)) {
+                        ctx.ui.notify(`Live subagent session file is missing: ${target.sessionFile}`, "error");
+                        return;
+                    }
+                    const liveRuntime = liveRuntimeBySessionFile.get(target.sessionFile);
+                    if (!liveRuntime) {
+                        ctx.ui.notify("Live runtime is no longer available for this subagent. It may have completed.", "warning");
+                        return;
+                    }
+                    const switched = await ctx.switchSession(target.sessionFile);
+                    if (switched.cancelled) {
+                        ctx.ui.notify("Session switch was cancelled.", "warning");
+                        return;
+                    }
+                    ctx.ui.notify(`Attached to running subagent ${target.agentName}. Prompts in this session are routed live (busy => steer, idle => prompt). Use /agent parent to return.`, "info");
+                    return;
+                }
+
+                if (target.kind === "parent") {
+                    if (!fs.existsSync(target.sessionFile)) {
+                        ctx.ui.notify(`Parent session file not found: ${target.sessionFile}`, "error");
+                        return;
+                    }
+                    const switched = await ctx.switchSession(target.sessionFile);
+                    if (switched.cancelled) {
+                        ctx.ui.notify("Session switch was cancelled.", "warning");
+                        return;
+                    }
+                    ctx.ui.notify("Switched to parent session.", "info");
+                    return;
+                }
+
+                if (!fs.existsSync(target.sessionFile)) {
+                    ctx.ui.notify(`Subagent session file is missing: ${target.sessionFile}`, "error");
+                    return;
+                }
+
+                const switched = await ctx.switchSession(target.sessionFile);
+                if (switched.cancelled) {
+                    ctx.ui.notify("Session switch was cancelled.", "warning");
+                    return;
+                }
+                updateAgentSessionLinkState(target.sessionFile, target.state === "failed" ? "failed" : "completed");
+                ctx.ui.notify(`Switched to subagent ${target.agentName}. This resumes the saved subagent session; use /agent parent to return.`, "info");
+            };
+
+            if (!arg) {
+                const subagentTargets = switchTargets.filter((target) => target.kind === "subagent");
+                if (ctx.hasUI) {
+                    if (subagentTargets.length === 0 && !parentSessionFile) {
+                        ctx.ui.notify("No tracked subagent sessions for this parent session yet. Run a single-mode subagent first (foreground or background).", "info");
+                        return;
+                    }
+
+                    const selected = await showAgentSwitcher(ctx, switchTargets);
+                    if (!selected) return;
+                    await applySwitchTarget(selected);
+                    return;
+                }
+
+                if (subagentTargets.length === 0 && !parentSessionFile) {
+                    ctx.ui.notify("No tracked subagent sessions for this parent session yet. Run a single-mode subagent first (foreground or background).", "info");
+                    return;
+                }
+
+                const lines = ["Agent switch targets:"];
+                switchTargets.forEach((target, index) => {
+                    lines.push(`${index + 1}. ${formatSwitchTargetSummary(target)}`);
+                });
+                lines.push("", "Use `/agent <index|id|name>` for explicit targeting, or `/agent parent`.");
+                ctx.ui.notify(lines.join("\n"), "info");
+                return;
+            }
+
+            if (arg === "parent" || arg === "main") {
+                if (!parentSessionFile) {
+                    ctx.ui.notify("You are already in the parent/main session.", "info");
+                    return;
+                }
+                if (!fs.existsSync(parentSessionFile)) {
+                    ctx.ui.notify(`Parent session file not found: ${parentSessionFile}`, "error");
+                    return;
+                }
+                const switched = await ctx.switchSession(parentSessionFile);
+                if (switched.cancelled) {
+                    ctx.ui.notify("Session switch was cancelled.", "warning");
+                    return;
+                }
+                ctx.ui.notify("Switched to parent session.", "info");
+                return;
+            }
+
+            let target: AgentSessionLink | undefined;
+            if (/^\d+$/.test(arg)) {
+                const index = Number.parseInt(arg, 10) - 1;
+                target = tracked[index];
+            }
+            if (!target) {
+                target = tracked.find((entry) => entry.id === arg);
+            }
+            if (!target) {
+                target = tracked.find((entry) => entry.agentName === arg);
+            }
+            if (!target) {
+                target = tracked.find((entry) => path.basename(entry.subagentSessionFile) === arg);
+            }
+
+            if (!target) {
+                const runningTarget = switchTargets.find((entry) => entry.id === arg && entry.kind === "subagent");
+                if (runningTarget?.state === "running") {
+                    ctx.ui.notify(runningTarget.blockedReason ?? "Selected subagent is still running. Live attach is not implemented yet.", "warning");
+                    return;
+                }
+                ctx.ui.notify(`Unknown subagent target: ${arg}. Run /agent to list available targets.`, "warning");
+                return;
+            }
+
+            if (!fs.existsSync(target.subagentSessionFile)) {
+                ctx.ui.notify(`Subagent session file is missing: ${target.subagentSessionFile}`, "error");
+                return;
+            }
+
+            if (target.state === "running") {
+                const liveRuntime = liveRuntimeBySessionFile.get(target.subagentSessionFile);
+                if (!liveRuntime) {
+                    ctx.ui.notify("Live runtime is no longer available for this subagent. It may have completed.", "warning");
+                    return;
+                }
+                const switched = await ctx.switchSession(target.subagentSessionFile);
+                if (switched.cancelled) {
+                    ctx.ui.notify("Session switch was cancelled.", "warning");
+                    return;
+                }
+                ctx.ui.notify(`Attached to running subagent ${target.agentName}. Prompts in this session are routed live (busy => steer, idle => prompt). Use /agent parent to return.`, "info");
+                return;
+            }
+
+            const switched = await ctx.switchSession(target.subagentSessionFile);
+            if (switched.cancelled) {
+                ctx.ui.notify("Session switch was cancelled.", "warning");
+                return;
+            }
+            updateAgentSessionLinkState(target.subagentSessionFile, target.state === "failed" ? "failed" : "completed");
+            ctx.ui.notify(`Switched to subagent ${target.agentName}. This resumes the saved subagent session; use /agent parent to return.`, "info");
+        },
+    });
     pi.registerShortcut(Key.ctrl("b"), {
         description: shortcutDesc("Move foreground subagent to background", "/subagents list"),
         handler: async (ctx) => {
@@ -986,13 +1123,31 @@ export default function(pi: ExtensionAPI) {
             running.claimed = true;
             let jobId: string;
             try {
-                jobId = manager.adoptRunning(
-                    running.agentName,
-                    running.task,
-                    running.cwd,
-                    running.abortController,
-                    running.resultPromise,
-                );
+                if (running.handle) {
+                    jobId = manager.adoptHandle(
+                        running.agentName,
+                        running.task,
+                        running.cwd,
+                        running.handle,
+                        running.resultPromise,
+                        {
+                            parentSessionFile: running.parentSessionFile ?? ctx.sessionManager.getSessionFile(),
+                        },
+                    );
+                } else if (running.abortController) {
+                    jobId = manager.adoptRunning(
+                        running.agentName,
+                        running.task,
+                        running.cwd,
+                        running.abortController,
+                        running.resultPromise,
+                        {
+                            parentSessionFile: running.parentSessionFile ?? ctx.sessionManager.getSessionFile(),
+                        },
+                    );
+                } else {
+                    throw new Error("Foreground subagent cannot be moved to background (missing runtime handle).");
+                }
             } catch (error) {
                 running.claimed = false;
                 ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
@@ -1075,6 +1230,18 @@ export default function(pi: ExtensionAPI) {
             const confirmProjectAgents = params.confirmProjectAgents ?? false;
             const cmuxClient = CmuxClient.fromPreferences(loadEffectivePreferences()?.preferences);
             const cmuxSplitsEnabled = cmuxClient.getConfig().splits;
+            const invokingSessionFile = ctx.sessionManager.getSessionFile();
+            const invokingSessionId = ctx.sessionManager.getSessionId();
+            const invokingMetadata = getCurrentSessionSubagentMetadata(invokingSessionFile);
+            const currentSubagentName = invokingMetadata?.subagentName;
+            const trackedAncestry = inProcessSubagentAncestryBySessionId.get(invokingSessionId);
+            const currentAncestry = trackedAncestry ?? (currentSubagentName ? [currentSubagentName] : []);
+            const inferredCurrentDepth = currentSubagentName ? Math.max(currentAncestry.length, 1) : 0;
+            const currentSubagentDepth = Math.max(
+                inProcessSubagentDepthBySessionId.get(invokingSessionId) ?? 0,
+                inferredCurrentDepth,
+            );
+            const nextSubagentDepth = currentSubagentDepth + 1;
 
             // Resolve isolation mode
             const isolationMode = readIsolationMode();
@@ -1094,6 +1261,37 @@ export default function(pi: ExtensionAPI) {
                         results,
                     });
 
+            const trackInProcessDepth = (
+                started: { handle: SubagentHandle; resultPromise: Promise<SingleResult> },
+                depth: number,
+                ancestry: string[],
+            ) => {
+                const sessionId = started.handle.sessionId;
+                if (!sessionId) return;
+                inProcessSubagentDepthBySessionId.set(sessionId, depth);
+                inProcessSubagentAncestryBySessionId.set(sessionId, ancestry);
+                void started.resultPromise.finally(() => {
+                    inProcessSubagentDepthBySessionId.delete(sessionId);
+                    inProcessSubagentAncestryBySessionId.delete(sessionId);
+                });
+            };
+
+            const buildChildAncestry = (childAgentName: string): string[] => [...currentAncestry, childAgentName];
+
+            const requestedAgentNames = hasSingle
+                ? [params.agent!]
+                : hasChain
+                    ? (params.chain ?? []).map((step) => step.agent)
+                    : (params.tasks ?? []).map((task) => task.agent);
+
+            if (currentSubagentName && requestedAgentNames.some((name) => name === currentSubagentName)) {
+                return {
+                    content: [{ type: "text", text: `Subagent "${currentSubagentName}" cannot spawn another subagent with the same name as itself.` }],
+                    details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+                    isError: true,
+                };
+            }
+
             if (modeCount !== 1) {
                 const available = agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
                 return {
@@ -1115,6 +1313,22 @@ export default function(pi: ExtensionAPI) {
                 };
             }
 
+            if (params.background && currentSubagentDepth > 0) {
+                return {
+                    content: [{ type: "text", text: "Nested background subagent launches are not supported yet. Run the nested subagent in foreground mode." }],
+                    details: makeDetails("single")([]),
+                    isError: true,
+                };
+            }
+
+            if (USE_IN_PROCESS_SUBAGENT && nextSubagentDepth > MAX_IN_PROCESS_SUBAGENT_DEPTH) {
+                return {
+                    content: [{ type: "text", text: `Max subagent depth (${MAX_IN_PROCESS_SUBAGENT_DEPTH}) exceeded.` }],
+                    details: makeDetails(hasChain ? "chain" : hasTasks ? "parallel" : "single")([]),
+                    isError: true,
+                };
+            }
+
             if ((agentScope === "project" || agentScope === "both") && confirmProjectAgents && ctx.hasUI) {
                 const requestedAgentNames = new Set<string>();
                 if (params.chain) for (const step of params.chain) requestedAgentNames.add(step.agent);
@@ -1163,19 +1377,45 @@ export default function(pi: ExtensionAPI) {
                         }
                         : undefined;
 
-                    const result = await runSingleAgent(
-                        ctx.cwd,
-                        agents,
-                        step.agent,
-                        taskWithContext,
-                        step.cwd,
-                        i + 1,
-                        step.model,
-                        ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
-                        signal,
-                        chainUpdate,
-                        makeDetails("chain"),
-                    );
+                    const result = USE_IN_PROCESS_SUBAGENT
+                        ? await (async () => {
+                            const started = await startInProcessSingleAgent(
+                                ctx.cwd,
+                                agents,
+                                step.agent,
+                                taskWithContext,
+                                step.cwd,
+                                i + 1,
+                                step.model,
+                                ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                                signal,
+                                chainUpdate,
+                                makeDetails("chain"),
+                                invokingSessionFile,
+                                nextSubagentDepth,
+                                invokingSessionId,
+                                currentAncestry,
+                            );
+                            trackInProcessDepth(started, nextSubagentDepth, buildChildAncestry(step.agent));
+                            return started.resultPromise;
+                        })()
+                        : await runLegacySingleAgent(
+                            ctx.cwd,
+                            agents,
+                            step.agent,
+                            taskWithContext,
+                            step.cwd,
+                            i + 1,
+                            step.model,
+                            ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                            signal,
+                            chainUpdate,
+                            makeDetails("chain"),
+                            invokingSessionFile,
+                            false,
+                            undefined,
+                            undefined,
+                        );
                     results.push(result);
 
                     const isError =
@@ -1246,24 +1486,54 @@ export default function(pi: ExtensionAPI) {
                 const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
                     const workerId = registerWorker(t.agent, t.task, index, batchSize, batchId);
                     const runTask = () =>
-                        runSingleAgent(
-                            ctx.cwd,
-                            agents,
-                            t.agent,
-                            t.task,
-                            t.cwd,
-                            undefined,
-                            t.model,
-                            ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
-                            signal,
-                            (partial) => {
-                                if (partial.details?.results[0]) {
-                                    allResults[index] = partial.details.results[0];
-                                    emitParallelUpdate();
-                                }
-                            },
-                            makeDetails("parallel"),
-                        );
+                        USE_IN_PROCESS_SUBAGENT
+                            ? (async () => {
+                                const started = await startInProcessSingleAgent(
+                                    ctx.cwd,
+                                    agents,
+                                    t.agent,
+                                    t.task,
+                                    t.cwd,
+                                    undefined,
+                                    t.model,
+                                    ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                                    signal,
+                                    (partial) => {
+                                        if (partial.details?.results[0]) {
+                                            allResults[index] = partial.details.results[0];
+                                            emitParallelUpdate();
+                                        }
+                                    },
+                                    makeDetails("parallel"),
+                                    invokingSessionFile,
+                                    nextSubagentDepth,
+                                    invokingSessionId,
+                                    currentAncestry,
+                                );
+                                trackInProcessDepth(started, nextSubagentDepth, buildChildAncestry(t.agent));
+                                return started.resultPromise;
+                            })()
+                            : runLegacySingleAgent(
+                                ctx.cwd,
+                                agents,
+                                t.agent,
+                                t.task,
+                                t.cwd,
+                                undefined,
+                                t.model,
+                                ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                                signal,
+                                (partial) => {
+                                    if (partial.details?.results[0]) {
+                                        allResults[index] = partial.details.results[0];
+                                        emitParallelUpdate();
+                                    }
+                                },
+                                makeDetails("parallel"),
+                                invokingSessionFile,
+                                false,
+                                undefined,
+                            );
                     let result = await runTask();
 
                     // Auto-retry failed tasks (likely API rate limit or transient error)
@@ -1330,36 +1600,130 @@ export default function(pi: ExtensionAPI) {
 
                     let jobId: string;
                     try {
-                        jobId = runSubagentInBackground(
-                            manager,
-                            agents,
-                            params.agent,
-                            params.task,
-                            params.cwd,
-                            params.model,
-                            { defaultCwd: ctx.cwd, model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined },
-                            async (bgSignal) => {
-                                const result = await runSingleAgent(
-                                    ctx.cwd,
-                                    agents,
-                                    params.agent!,
-                                    params.task!,
-                                    params.cwd,
-                                    undefined,
-                                    params.model,
-                                    ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
-                                    bgSignal,
-                                    undefined, // no streaming updates for background jobs
-                                    makeDetails("single"),
-                                );
-                                return {
-                                    exitCode: result.exitCode,
-                                    finalOutput: getFinalOutput(result.messages),
+                        if (USE_IN_PROCESS_SUBAGENT) {
+                            const started = await startInProcessSingleAgent(
+                                ctx.cwd,
+                                agents,
+                                params.agent,
+                                params.task,
+                                params.cwd,
+                                undefined,
+                                params.model,
+                                ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                                undefined,
+                                undefined,
+                                makeDetails("single"),
+                                invokingSessionFile,
+                                nextSubagentDepth,
+                                invokingSessionId,
+                                currentAncestry,
+                            );
+                            trackInProcessDepth(started, nextSubagentDepth, buildChildAncestry(params.agent));
+
+                            const effectiveCwd = params.cwd ?? ctx.cwd;
+                            jobId = manager.adoptHandle(
+                                params.agent,
+                                params.task,
+                                effectiveCwd,
+                                started.handle,
+                                started.resultPromise.then((result) => ({
+                                    summary: (getFinalOutput(result.messages) || "(no output)").slice(0, 300),
                                     stderr: result.stderr,
+                                    exitCode: result.exitCode,
                                     model: result.model,
-                                };
-                            },
-                        );
+                                    sessionFile: result.sessionFile,
+                                    parentSessionFile: result.parentSessionFile,
+                                })),
+                                {
+                                    parentSessionFile: invokingSessionFile,
+                                    model: bgInferredModel,
+                                },
+                            );
+                        } else {
+                            jobId = runSubagentInBackground(
+                                manager,
+                                agents,
+                                params.agent,
+                                params.task,
+                                params.cwd,
+                                params.model,
+                                { defaultCwd: ctx.cwd, model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined, parentSessionFile: invokingSessionFile },
+                                async (bgSignal) => {
+                                    let liveSessionFile: string | undefined;
+                                    let liveRuntime: LiveSubagentRuntime | undefined;
+                                    const result = await runLegacySingleAgent(
+                                        ctx.cwd,
+                                        agents,
+                                        params.agent!,
+                                        params.task!,
+                                        params.cwd,
+                                        undefined,
+                                        params.model,
+                                        ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                                        bgSignal,
+                                        undefined, // no streaming updates for background jobs
+                                        makeDetails("single"),
+                                        invokingSessionFile,
+                                        true,
+                                        (info) => {
+                                            if (!invokingSessionFile || !info.sessionFile) return;
+                                            upsertAgentSessionLink(
+                                                params.agent!,
+                                                params.task!,
+                                                invokingSessionFile,
+                                                info.sessionFile,
+                                                "running",
+                                            );
+                                            liveSessionFile = info.sessionFile;
+                                            if (liveRuntime) {
+                                                liveRuntime.sessionFile = info.sessionFile;
+                                                liveRuntime.parentSessionFile = info.parentSessionFile ?? invokingSessionFile;
+                                                liveRuntimeBySessionFile.set(info.sessionFile, liveRuntime);
+                                            }
+                                        },
+                                        (event, partial) => {
+                                            const sessionFile = partial.sessionFile;
+                                            if (!sessionFile || activeSessionFileForUi !== sessionFile) return;
+                                            if (event?.type === "message_update" && event.assistantMessageEvent?.type === "text_delta") {
+                                                const delta = String(event.assistantMessageEvent.delta ?? "");
+                                                if (delta) pushLiveStreamDelta(sessionFile, delta);
+                                            }
+                                            if (event?.type === "message_end") {
+                                                flushLiveStream(sessionFile);
+                                            }
+                                        },
+                                        {
+                                            onStart: (control) => {
+                                                if (!control.sendPrompt || !control.sendSteer || !control.sendFollowUp || !control.isBusy) return;
+                                                liveRuntime = {
+                                                    sessionFile: liveSessionFile,
+                                                    parentSessionFile: invokingSessionFile,
+                                                    agentName: params.agent!,
+                                                    isBusy: control.isBusy,
+                                                    sendPrompt: control.sendPrompt,
+                                                    sendSteer: control.sendSteer,
+                                                    sendFollowUp: control.sendFollowUp,
+                                                };
+                                                if (liveSessionFile) {
+                                                    liveRuntimeBySessionFile.set(liveSessionFile, liveRuntime);
+                                                }
+                                            },
+                                            onFinish: () => {
+                                                if (liveSessionFile) liveRuntimeBySessionFile.delete(liveSessionFile);
+                                            },
+                                        },
+                                    );
+                                    return {
+                                        exitCode: result.exitCode,
+                                        finalOutput: getFinalOutput(result.messages),
+                                        stderr: result.stderr,
+                                        model: result.model,
+                                        sessionFile: result.sessionFile,
+                                        parentSessionFile: result.parentSessionFile,
+                                    };
+                                },
+                            );
+                        }
                     } catch (err) {
                         return {
                             content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
@@ -1387,31 +1751,170 @@ export default function(pi: ExtensionAPI) {
                         isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
                     }
 
-                    const result = await runSingleAgent(
-                        ctx.cwd,
-                        agents,
-                        params.agent,
-                        params.task,
-                        isolation ? isolation.workDir : params.cwd,
-                        undefined,
-                        params.model,
-                        ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
-                        signal,
-                        onUpdate,
-                        makeDetails("single"),
-                        !isolation
-                            ? {
-                                onStart: (control) => {
-                                    activeForegroundSubagent = { ...control, claimed: false };
-                                    ctx.ui.setStatus(foregroundSubagentStatusKey, foregroundSubagentHint);
-                                },
-                                onFinish: () => {
-                                    activeForegroundSubagent = null;
-                                    ctx.ui.setStatus(foregroundSubagentStatusKey, undefined);
-                                },
-                            }
-                            : undefined,
-                    );
+                    let result: SingleResult;
+                    if (USE_IN_PROCESS_SUBAGENT && !isolation) {
+                        const started = await startInProcessSingleAgent(
+                            ctx.cwd,
+                            agents,
+                            params.agent,
+                            params.task,
+                            params.cwd,
+                            undefined,
+                            params.model,
+                            ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                            signal,
+                            onUpdate,
+                            makeDetails("single"),
+                            invokingSessionFile,
+                            nextSubagentDepth,
+                            invokingSessionId,
+                            currentAncestry,
+                        );
+                        trackInProcessDepth(started, nextSubagentDepth, buildChildAncestry(params.agent));
+
+                        const effectiveRunCwd = params.cwd ?? ctx.cwd;
+                        let releaseToBackground: ((jobId: string) => void) | undefined;
+                        const movedToBackground = new Promise<string>((resolve) => {
+                            releaseToBackground = resolve;
+                        });
+
+                        activeForegroundSubagent = {
+                            claimed: false,
+                            agentName: params.agent,
+                            task: params.task,
+                            cwd: effectiveRunCwd,
+                            parentSessionFile: invokingSessionFile,
+                            handle: started.handle,
+                            resultPromise: started.resultPromise.then((done) => ({
+                                summary: getFinalOutput(done.messages) || "(no output)",
+                                stderr: done.stderr,
+                                exitCode: done.exitCode,
+                                model: done.model,
+                                sessionFile: done.sessionFile,
+                                parentSessionFile: done.parentSessionFile,
+                            })),
+                            adoptToBackground: (jobId: string) => {
+                                if (!releaseToBackground) return false;
+                                releaseToBackground(jobId);
+                                releaseToBackground = undefined;
+                                return true;
+                            },
+                            sendPrompt: started.handle.prompt,
+                            sendSteer: started.handle.steer,
+                            sendFollowUp: started.handle.followUp,
+                            isBusy: started.handle.isBusy,
+                        };
+                        ctx.ui.setStatus(foregroundSubagentStatusKey, foregroundSubagentHint);
+
+                        const winner = await Promise.race([
+                            started.resultPromise.then((done) => ({ type: "done" as const, done })),
+                            movedToBackground.then((jobId) => ({ type: "background" as const, jobId })),
+                        ]);
+
+                        if (winner.type === "background") {
+                            activeForegroundSubagent = null;
+                            ctx.ui.setStatus(foregroundSubagentStatusKey, undefined);
+                            result = {
+                                ...started.currentResult,
+                                backgroundJobId: winner.jobId,
+                            };
+                        } else {
+                            activeForegroundSubagent = null;
+                            ctx.ui.setStatus(foregroundSubagentStatusKey, undefined);
+                            result = winner.done;
+                        }
+                    } else {
+                        let liveSessionFile: string | undefined;
+                        let liveRuntime: LiveSubagentRuntime | undefined;
+                        result = await runLegacySingleAgent(
+                            ctx.cwd,
+                            agents,
+                            params.agent,
+                            params.task,
+                            isolation ? isolation.workDir : params.cwd,
+                            undefined,
+                            params.model,
+                            ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                            signal,
+                            onUpdate,
+                            makeDetails("single"),
+                            invokingSessionFile,
+                            !isolation,
+                            !isolation
+                                ? (info) => {
+                                    if (!invokingSessionFile || !info.sessionFile) return;
+                                    upsertAgentSessionLink(
+                                        params.agent!,
+                                        params.task!,
+                                        invokingSessionFile,
+                                        info.sessionFile,
+                                        "running",
+                                    );
+                                    liveSessionFile = info.sessionFile;
+                                    if (liveRuntime) {
+                                        liveRuntime.sessionFile = info.sessionFile;
+                                        liveRuntime.parentSessionFile = info.parentSessionFile ?? invokingSessionFile;
+                                        liveRuntimeBySessionFile.set(info.sessionFile, liveRuntime);
+                                    }
+                                }
+                                : undefined,
+                            !isolation
+                                ? (event, partial) => {
+                                    const sessionFile = partial.sessionFile;
+                                    if (!sessionFile || activeSessionFileForUi !== sessionFile) return;
+                                    if (event?.type === "message_update" && event.assistantMessageEvent?.type === "text_delta") {
+                                        const delta = String(event.assistantMessageEvent.delta ?? "");
+                                        if (delta) pushLiveStreamDelta(sessionFile, delta);
+                                    }
+                                    if (event?.type === "message_end") {
+                                        flushLiveStream(sessionFile);
+                                    }
+                                }
+                                : undefined,
+                            !isolation
+                                ? {
+                                    onStart: (control) => {
+                                        activeForegroundSubagent = { ...control, claimed: false };
+                                        ctx.ui.setStatus(foregroundSubagentStatusKey, foregroundSubagentHint);
+
+                                        if (!control.sendPrompt || !control.sendSteer || !control.sendFollowUp || !control.isBusy) return;
+                                        liveRuntime = {
+                                            sessionFile: liveSessionFile,
+                                            parentSessionFile: invokingSessionFile,
+                                            agentName: params.agent!,
+                                            isBusy: control.isBusy,
+                                            sendPrompt: control.sendPrompt,
+                                            sendSteer: control.sendSteer,
+                                            sendFollowUp: control.sendFollowUp,
+                                        };
+                                        if (liveSessionFile && liveRuntime) {
+                                            liveRuntimeBySessionFile.set(liveSessionFile, liveRuntime);
+                                        }
+                                    },
+                                    onFinish: () => {
+                                        activeForegroundSubagent = null;
+                                        ctx.ui.setStatus(foregroundSubagentStatusKey, undefined);
+                                        if (liveSessionFile) liveRuntimeBySessionFile.delete(liveSessionFile);
+                                    },
+                                }
+                                : undefined,
+                        );
+                    }
+
+                    if (result.sessionFile && invokingSessionFile) {
+                        const existingParent = parentSessionByChild.get(result.sessionFile);
+                        if (!existingParent) {
+                            registerAgentSessionLink({
+                                agentName: result.agent,
+                                task: result.task,
+                                parentSessionFile: invokingSessionFile,
+                                subagentSessionFile: result.sessionFile,
+                                state: result.exitCode === 0 ? "completed" : "failed",
+                            });
+                        } else {
+                            updateAgentSessionLinkState(result.sessionFile, result.exitCode === 0 ? "completed" : "failed");
+                        }
+                    }
 
                     if (result.backgroundJobId) {
                         return {
@@ -1429,11 +1932,12 @@ export default function(pi: ExtensionAPI) {
                     }
 
                     const isError = result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+                    const agentSwitchHint = result.sessionFile ? "\n\nTip: run `/agent` to switch focus to this subagent session." : "";
                     if (isError) {
                         const errorMsg =
                             result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
                         return {
-                            content: [{ type: "text", text: `Agent ${result.stopReason || "failed"}: ${errorMsg}` }],
+                            content: [{ type: "text", text: `Agent ${result.stopReason || "failed"}: ${errorMsg}${agentSwitchHint}` }],
                             details: makeDetails("single")([result]),
                             isError: true,
                         };
@@ -1444,6 +1948,7 @@ export default function(pi: ExtensionAPI) {
                     if (mergeResult && !mergeResult.success) {
                         outputText += `\n\n⚠ Patch merge failed: ${mergeResult.error || "unknown error"}`;
                     }
+                    if (agentSwitchHint) outputText += agentSwitchHint;
                     return {
                         content: [{ type: "text", text: outputText }],
                         details: makeDetails("single")([result]),