oira666_pi-subagent 0.2.3 → 0.2.5

package/README.md

@@ -24,6 +24,7 @@ pi remove npm:oira666_pi-subagent
 
 Each subagent runs as a **separate `pi` process** — fully isolated memory, its own model/tool loop.
 Processes are spawned via the operating system and communicate through JSON-line stdout.
+Subagent sessions are persisted separately under a `sessions-subagents` directory (a sibling of Pi's normal `sessions` directory), so they can be resumed without mixing into the main session list.
 
 - Full OS-level isolation — a crashed subagent cannot affect the parent
 - True parallel execution across all CPU cores
@@ -119,6 +120,20 @@ pi --no-subagent-prevent-cycles   # allow cycles (not recommended)
 | `PI_SUBAGENT_MAX_PARALLEL_TASKS` | `16`    | Max tasks per single call                |
 | `PI_SUBAGENT_MAX_CONCURRENCY`    | `8`     | Max subagents running simultaneously     |
 
+## Subagent Session Resume
+
+Subagent subprocesses save sessions in `sessions-subagents`. When a main Pi session is resumed and its latest branch contains an unfinished `subagent` tool call (aborted, errored, or closed by Pi's synthetic unfinished-tool error), the extension can resume that delegation from the saved subagent sessions.
+
+- TUI mode asks: **Resume subagents?**
+- Non-UI modes (`pi -p`, JSON/RPC) resume automatically.
+- Already-finished subagents are reused as completed; unfinished ones continue from their own saved sessions.
+- Nested subagents use the same mechanism recursively.
+
+| Env Var | Default | Description |
+| --- | --- | --- |
+| `PI_SUBAGENT_RESUME_PROMPT` | `true` | Set to `false` to suppress the TUI yes/no prompt and auto-resume. |
+| `PI_SUBAGENT_DISABLE_RESUME` | `false` | Set to `true` to disable automatic subagent resume detection entirely. |
+
 ## Agent Discovery
 
 | Env Var                 | Description                                                  |

package/index.ts

@@ -9,10 +9,25 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  createAssistantMessageEventStream,
+  streamSimple as streamModelSimple,
+} from "@mariozechner/pi-ai";
 import { Type } from "@sinclair/typebox";
 import { type AgentConfig, discoverAgents } from "./agents.js";
 import { renderCall, renderResult } from "./render.js";
 import { runAgentSubprocess, executeParallelSubprocess } from "./runner.js";
+import {
+  SUBAGENT_RESUME_DISABLE_ENV,
+  SUBAGENT_RESUME_PROMPT_ENV,
+  buildSubagentSessionDir,
+  findLatestResumableSubagentCall,
+  getDefaultSubagentSessionRoot,
+  isFinishedResult,
+  parseBooleanEnv,
+  sameTasks,
+  type ResumableSubagentCall,
+} from "./resume.js";
 import {
   DEFAULT_MAX_PARALLEL_TASKS,
   SUBAGENT_MAX_PARALLEL_TASKS_ENV,
@@ -339,11 +354,82 @@ function getProjectAgentSessionKey(projectAgentsDir: string | null): string {
   return projectAgentsDir ?? "(unknown-project-agents-dir)";
 }
 
+function ensureSubagentToolActive(pi: ExtensionAPI): void {
+  const activeTools = pi.getActiveTools();
+  if (!activeTools.includes("subagent")) {
+    pi.setActiveTools([...activeTools, "subagent"]);
+  }
+}
+
+function hasCliInitialPrompt(argv: string[]): boolean {
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-p" || arg === "--print") return true;
+  }
+  return false;
+}
+
+const RESUME_PROVIDER = "pi-subagent-resume";
+const RESUME_MODEL_ID = "synthetic-tool-call";
+const RESUME_STATE_KEY = "__piSubagentResumeState";
+
+type SyntheticResumeState = {
+  plan: ResumableSubagentCall | null;
+  phase: "tool" | "final";
+};
+
+function clearSyntheticResumeState(): void {
+  const state = getSyntheticResumeState();
+  state.plan = null;
+  state.phase = "tool";
+}
+
+function getSyntheticResumeState(): SyntheticResumeState {
+  const g = globalThis as any;
+  if (!g[RESUME_STATE_KEY]) {
+    g[RESUME_STATE_KEY] = { plan: null, phase: "tool" } satisfies SyntheticResumeState;
+  }
+  return g[RESUME_STATE_KEY] as SyntheticResumeState;
+}
+
+function emptyModelUsage() {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}
+
+function getMessageText(message: any): string {
+  const content = message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => (part?.type === "text" && typeof part.text === "string" ? part.text : ""))
+    .join("");
+}
+
+function isSyntheticResumePrompt(context: any, taskCount: number): boolean {
+  const messages = Array.isArray(context?.messages) ? context.messages : [];
+  const lastUser = [...messages].reverse().find((message) => message?.role === "user");
+  return getMessageText(lastUser).trim() === `Resuming ${taskCount} subagents...`;
+}
+
+function formatModelFlag(model: any): string | undefined {
+  if (!model?.id || !model?.provider) return undefined;
+  return `${model.provider}/${model.id}`;
+}
+
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
 
 export default function (pi: ExtensionAPI) {
+  let resumeModelRegistry: any | undefined;
+
   pi.registerFlag("subagent-max-depth", {
     description: "Maximum allowed subagent delegation depth (default: 3).",
     type: "string",
@@ -354,6 +440,97 @@ export default function (pi: ExtensionAPI) {
     type: "boolean",
   });
 
+  pi.registerProvider(RESUME_PROVIDER, {
+    baseUrl: "http://127.0.0.1/pi-subagent-resume",
+    api: "openai-responses",
+    apiKey: "pi-subagent-resume-noop-key",
+    streamSimple: async (model, context, options) => {
+      const stream = createAssistantMessageEventStream();
+      const state = getSyntheticResumeState();
+      const plan = state.plan;
+      const phase = state.phase;
+      if (plan && phase === "tool" && isSyntheticResumePrompt(context, plan.tasks.length)) {
+        state.phase = "final";
+        const toolCall = {
+          type: "toolCall" as const,
+          id: `resume_subagent_${Date.now()}`,
+          name: "subagent",
+          arguments: { tasks: plan.tasks },
+        };
+        const message = {
+          role: "assistant" as const,
+          content: [toolCall],
+          api: model.api,
+          provider: model.provider,
+          model: model.id,
+          usage: emptyModelUsage(),
+          stopReason: "toolUse" as const,
+          timestamp: Date.now(),
+        };
+        queueMicrotask(() => {
+          stream.push({ type: "start", partial: message });
+          stream.push({ type: "toolcall_start", contentIndex: 0, partial: message });
+          stream.push({ type: "toolcall_end", contentIndex: 0, toolCall, partial: message });
+          stream.push({ type: "done", reason: "toolUse", message });
+          stream.end(message);
+        });
+        return stream;
+      }
+
+      if (phase === "final" && modelToRestoreAfterResume) {
+        const restore = modelToRestoreAfterResume;
+        const auth = resumeModelRegistry
+          ? await resumeModelRegistry.getApiKeyAndHeaders(restore)
+          : { ok: true, apiKey: undefined, headers: undefined };
+        if (!auth.ok) {
+          throw new Error(auth.error);
+        }
+        return streamModelSimple(restore, context, {
+          ...options,
+          apiKey: auth.apiKey,
+          headers: auth.headers,
+        });
+      }
+
+      if (!(plan && phase === "tool")) {
+        state.plan = null;
+        state.phase = "tool";
+      }
+      const message = {
+        role: "assistant" as const,
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: emptyModelUsage(),
+        stopReason: "stop" as const,
+        timestamp: Date.now(),
+      };
+      queueMicrotask(() => {
+        stream.push({ type: "start", partial: message });
+        stream.push({ type: "done", reason: "stop", message });
+        stream.end(message);
+      });
+      return stream;
+    },
+    models: [
+      {
+        id: RESUME_MODEL_ID,
+        name: "Pi Subagent Resume",
+        api: "openai-responses",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        // Keep this large so Pi's pre-prompt auto-compaction does not call the
+        // synthetic provider before the visible resume prompt is appended. That
+        // would consume the tool-call phase during compaction and the real
+        // resume turn would only see the final text message.
+        contextWindow: 1_000_000,
+        maxTokens: 16,
+      },
+    ],
+  });
+
   const depthConfig = resolveDelegationDepthConfig(pi);
   const { currentDepth, maxDepth, canDelegate, ancestorAgentStack, preventCycles } =
     depthConfig;
@@ -362,14 +539,35 @@ export default function (pi: ExtensionAPI) {
     DEFAULT_MAX_PARALLEL_TASKS;
 
   let discoveredAgents: AgentConfig[] = [];
+  let currentSessionId = "ephemeral";
+  let currentSubagentSessionRoot = "";
+  let pendingResumePlan: ResumableSubagentCall | null = null;
+  let modelToRestoreAfterResume: any | undefined;
   const approvedProjectAgentDirsForSession = new Set<string>();
 
+  async function restoreModelAfterResumeFailure(ctx?: { ui?: { notify?: (message: string, type?: "info" | "warning" | "error") => void } }) {
+    const restore = modelToRestoreAfterResume;
+    modelToRestoreAfterResume = undefined;
+    pendingResumePlan = null;
+    clearSyntheticResumeState();
+    if (!restore) return;
+    try {
+      await pi.setModel(restore);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx?.ui?.notify?.(`Failed to restore model after subagent resume error: ${message}`, "error");
+      console.error("[pi-subagent] Failed to restore model after resume error:", err);
+    }
+  }
+
   // Auto-discover agents on session start
-  pi.on("session_start", async (_event, ctx) => {
+  pi.on("session_start", async (event, ctx) => {
     if (!canDelegate) return;
     try {
       const discovery = discoverAgents(ctx.cwd, "both");
       discoveredAgents = discovery.agents;
+      currentSessionId = ctx.sessionManager.getSessionId?.() ?? "ephemeral";
+      currentSubagentSessionRoot = getDefaultSubagentSessionRoot(ctx);
 
       if (discoveredAgents.length > 0 && ctx.hasUI) {
         const list = discoveredAgents
@@ -380,11 +578,56 @@ export default function (pi: ExtensionAPI) {
           "info",
         );
       }
+
+      const resumeDisabled = parseBooleanEnv(process.env[SUBAGENT_RESUME_DISABLE_ENV]) === true;
+      if (resumeDisabled || (event.reason !== "resume" && event.reason !== "startup")) return;
+
+      const plan = findLatestResumableSubagentCall(ctx);
+      if (!plan) return;
+
+      let shouldResume = true;
+      const shouldPrompt = parseBooleanEnv(process.env[SUBAGENT_RESUME_PROMPT_ENV]) !== false;
+      if (ctx.hasUI && shouldPrompt) {
+        shouldResume = await ctx.ui.confirm(
+          "Resume subagents?",
+          `The resumed session has an unfinished subagent call (${plan.tasks.length} task${plan.tasks.length === 1 ? "" : "s"}). Resume it from saved subagent sessions?`,
+        );
+      }
+      if (!shouldResume) return;
+
+      pendingResumePlan = plan;
+      const resumeState = getSyntheticResumeState();
+      resumeState.plan = plan;
+      resumeState.phase = "tool";
+      modelToRestoreAfterResume = ctx.model;
+      resumeModelRegistry = ctx.modelRegistry;
+      ensureSubagentToolActive(pi);
+      const resumeModel = ctx.modelRegistry.find(RESUME_PROVIDER, RESUME_MODEL_ID);
+      if (!resumeModel || !(await pi.setModel(resumeModel))) {
+        ctx.ui.notify("Failed to switch to synthetic subagent resume model.", "error");
+        await restoreModelAfterResumeFailure(ctx);
+        return;
+      }
+
+      // In print/json subprocesses there is already an initial CLI prompt about
+      // to be sent. That prompt will be answered by the synthetic provider with
+      // a real assistant subagent tool call. In interactive mode, submit a short
+      // visible prompt that triggers the same synthetic provider path.
+      if (hasCliInitialPrompt(process.argv)) {
+        if (ctx.hasUI) ctx.ui.notify(`Resuming ${plan.tasks.length} subagents...`, "info");
+      } else {
+        pi.sendUserMessage(`Resuming ${plan.tasks.length} subagents...`);
+      }
     } catch (err) {
       console.error("[pi-subagent] Error in session_start:", err);
+      await restoreModelAfterResumeFailure(ctx);
     }
   });
 
+  pi.on("agent_end", async () => {
+    await restoreModelAfterResumeFailure();
+  });
+
   // Inject available agents into the system prompt
   pi.on("before_agent_start", async (event) => {
     try {
@@ -453,7 +696,7 @@ calls one after another. Do NOT put dependent tasks in the same array.
       ].join("\n"),
       parameters: SubagentParams,
 
-      async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      async execute(toolCallId, params, signal, onUpdate, ctx) {
         try {
           const discovery = discoverAgents(ctx.cwd, "both");
           const { agents } = discovery;
@@ -558,6 +801,14 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
             }
           }
 
+          const resumePlan =
+            pendingResumePlan && sameTasks(pendingResumePlan.tasks, tasks)
+              ? pendingResumePlan
+              : null;
+          if (resumePlan) {
+            pendingResumePlan = null;
+          }
+
           if (tasks.length === 1) {
             const [task] = tasks;
             return executeSingle(
@@ -569,6 +820,10 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
               signal,
               onUpdate,
               makeDetails,
+              resumePlan?.details?.results[0],
+              getSessionDirForTask(resumePlan?.previousToolCallId ?? toolCallId, 0),
+              !!resumePlan,
+              formatModelFlag(modelToRestoreAfterResume),
             );
           }
 
@@ -579,6 +834,10 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
             signal,
             onUpdate,
             makeDetails,
+            resumePlan?.details?.results,
+            (index) => getSessionDirForTask(resumePlan?.previousToolCallId ?? toolCallId, index),
+            !!resumePlan,
+            formatModelFlag(modelToRestoreAfterResume),
           );
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -592,12 +851,21 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
 
       },
 
-      renderCall: (args, theme) => renderCall(args, theme),
+      renderCall: (args, theme, context) => renderCall(args, theme, context),
       renderResult: (result, { expanded }, theme) =>
         renderResult(result, expanded, theme),
     });
   }
 
+  function getSessionDirForTask(toolCallId: string, index: number): string {
+    const root = currentSubagentSessionRoot || pathlessSubagentRootFallback();
+    return buildSubagentSessionDir(root, currentSessionId, toolCallId, index);
+  }
+
+  function pathlessSubagentRootFallback(): string {
+    return `${process.env.HOME ?? "."}/.pi/agent/sessions-subagents`;
+  }
+
   // -----------------------------------------------------------------------
   // Mode implementations
   // -----------------------------------------------------------------------
@@ -611,7 +879,23 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
     signal: AbortSignal | undefined,
     onUpdate: ((partial: any) => void) | undefined,
     makeDetails: ReturnType<typeof makeDetailsFactory>,
+    previousResult: SingleResult | undefined,
+    sessionDir: string,
+    resumeExistingSession: boolean,
+    fallbackModel?: string,
   ) {
+    if (previousResult && isFinishedResult(previousResult)) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: getFinalOutput(previousResult.messages) || "(no output)",
+          },
+        ],
+        details: makeDetails("single")([previousResult]),
+      };
+    }
+
     const result = await runAgentSubprocess({
       cwd: defaultCwd,
       agents,
@@ -625,6 +909,11 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
       signal,
       onUpdate,
       makeDetails: makeDetails("single"),
+      sessionDir: previousResult?.sessionDir ?? sessionDir,
+      sessionRoot: currentSubagentSessionRoot,
+      resumeSession: resumeExistingSession,
+      initialResult: previousResult,
+      fallbackModel,
     });
 
     if (isResultError(result)) {
@@ -662,6 +951,10 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
     signal: AbortSignal | undefined,
     onUpdate: ((partial: any) => void) | undefined,
     makeDetails: ReturnType<typeof makeDetailsFactory>,
+    resumeResults: SingleResult[] | undefined,
+    getSessionDir: (index: number) => string,
+    resumeExistingSessions: boolean,
+    fallbackModel?: string,
   ) {
     return executeParallelSubprocess(
       tasks,
@@ -674,6 +967,11 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
       signal,
       onUpdate,
       makeDetails("parallel"),
+      resumeResults,
+      (index) => getSessionDir(index),
+      resumeExistingSessions,
+      currentSubagentSessionRoot,
+      fallbackModel,
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-subagent",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Subagent extension for Pi coding agent. Delegate tasks to specialized agents.",
   "type": "module",
   "main": "index.ts",
@@ -8,6 +8,7 @@
     "index.ts",
     "agents.ts",
     "runner.ts",
+    "resume.ts",
     "shared.ts",
     "render.ts",
     "types.ts",

package/render.ts

@@ -180,21 +180,56 @@ function buildNodesFromNestedResult(nested: NestedSubagentResult): TreeNode[] {
 	return nested.details.results.map((result) => buildResultNode(result));
 }
 
+function subagentCallSignature(call: PendingSubagentCall): string {
+	return JSON.stringify(call.tasks.map((task) => ({ agent: task.agent, task: task.task ?? "" })));
+}
+
+function nestedResultIsHealthy(nested: NestedSubagentResult | undefined): boolean {
+	if (!nested || nested.isError) return false;
+	return nested.details.results.every((result) => !isResultError(result));
+}
+
 function buildNestedChildren(result: SingleResult): TreeNode[] {
+	const parentIsRunning = result.exitCode === -1;
 	const completedByToolCallId = new Map<string, NestedSubagentResult>();
 	for (const nested of getNestedSubagentResults(result.messages)) {
 		completedByToolCallId.set(nested.toolCallId, nested);
 	}
 
+	const calls = extractPendingSubagentCalls(result.messages);
+	const laterResumeBySignature = new Map<string, number>();
+	calls.forEach((call, index) => {
+		const completed = completedByToolCallId.get(call.toolCallId);
+		// A resumed call has the same task signature as the interrupted call but a
+		// newer toolCallId. Prefer that newer running/successful tree over the old
+		// synthetic/aborted result so resumed nested subagents render in-place.
+		if (!completed || nestedResultIsHealthy(completed)) {
+			laterResumeBySignature.set(subagentCallSignature(call), index);
+		}
+	});
+
 	const nodes: TreeNode[] = [];
-	for (const call of extractPendingSubagentCalls(result.messages)) {
+	calls.forEach((call, index) => {
 		const completed = completedByToolCallId.get(call.toolCallId);
+		const newerEquivalent = laterResumeBySignature.get(subagentCallSignature(call));
+		if (
+			newerEquivalent !== undefined &&
+			newerEquivalent > index &&
+			(!completed || completed.isError || !nestedResultIsHealthy(completed))
+		) {
+			return;
+		}
+
 		if (completed && isSubagentDetails(completed.details)) {
 			nodes.push(...buildNodesFromNestedResult(completed));
-			continue;
+			return;
 		}
-		nodes.push(...buildPendingNodes(call));
-	}
+		// Unmatched subagent tool calls are useful while the parent is still
+		// running (they show live pending children). Once the parent finished,
+		// unmatched calls are stale history from an interrupted/resumed session and
+		// must not keep the whole tree in a perpetual "running" state.
+		if (parentIsRunning) nodes.push(...buildPendingNodes(call));
+	});
 	return nodes;
 }
 
@@ -365,14 +400,23 @@ function topLevelSummary(details: SubagentDetails, counts: TreeCounts): string {
 // renderCall — shown while the tool is being invoked
 // ---------------------------------------------------------------------------
 
-export function renderCall(args: Record<string, any>, theme: { fg: ThemeFg; bold: (s: string) => string }): Text {
+export function renderCall(
+	args: Record<string, any>,
+	theme: { fg: ThemeFg; bold: (s: string) => string },
+	context?: { isPartial?: boolean; isError?: boolean },
+): Text {
 	const tasks = Array.isArray(args.tasks) ? args.tasks : [];
 	const count = tasks.length;
+	const icon = context?.isPartial === false
+		? context.isError
+			? theme.fg("error", "❌")
+			: theme.fg("success", "✅")
+		: theme.fg("warning", "⏳");
 	let text = `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `${count} task${count === 1 ? "" : "s"}`)}`;
 	for (const task of tasks.slice(0, 6)) {
 		const agent = typeof task?.agent === "string" ? task.agent : "...";
 		const preview = typeof task?.task === "string" ? ` ${truncate(task.task, 56)}` : "";
-		text += `\n  ${theme.fg("warning", "⏳")} ${theme.fg("accent", agent)}${theme.fg("dim", preview)}`;
+		text += `\n  ${icon} ${theme.fg("accent", agent)}${theme.fg("dim", preview)}`;
 	}
 	if (tasks.length > 6) text += `\n  ${theme.fg("muted", `... +${tasks.length - 6} more`)}`;
 	return new Text(text, 0, 0);

package/resume.ts

@@ -0,0 +1,182 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { isResultError, isSubagentDetails, type SingleResult, type SubagentDetails } from "./types.js";
+
+export const SUBAGENT_RESUME_PROMPT_ENV = "PI_SUBAGENT_RESUME_PROMPT";
+export const SUBAGENT_RESUME_DISABLE_ENV = "PI_SUBAGENT_DISABLE_RESUME";
+export const SUBAGENT_SESSION_ROOT_ENV = "PI_SUBAGENT_SESSION_ROOT";
+
+type SessionEntry = ReturnType<ExtensionContext["sessionManager"]["getEntries"]>[number];
+
+export interface ResumableSubagentCall {
+  previousToolCallId: string;
+  tasks: Array<{ agent: string; task: string; cwd?: string }>;
+  details?: SubagentDetails;
+}
+
+export function parseBooleanEnv(raw: unknown): boolean | null {
+  if (typeof raw === "boolean") return raw;
+  if (typeof raw !== "string") return null;
+  const normalized = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return null;
+}
+
+export function getDefaultSubagentSessionRoot(ctx: ExtensionContext): string {
+  const inheritedRoot = process.env[SUBAGENT_SESSION_ROOT_ENV];
+  if (inheritedRoot) return inheritedRoot;
+
+  const mainSessionDir = ctx.sessionManager.getSessionDir?.();
+  if (typeof mainSessionDir === "string" && mainSessionDir.length > 0) {
+    return path.join(path.dirname(mainSessionDir), "sessions-subagents");
+  }
+  return path.join(os.homedir(), ".pi", "agent", "sessions-subagents");
+}
+
+export function buildSubagentSessionDir(
+  root: string,
+  parentSessionId: string,
+  toolCallId: string,
+  index: number,
+): string {
+  const safeParent = parentSessionId.replace(/[^a-zA-Z0-9_.-]+/g, "_");
+  const safeTool = toolCallId.replace(/[^a-zA-Z0-9_.-]+/g, "_");
+  return path.join(root, safeParent, safeTool, String(index));
+}
+
+export function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+function branchEntries(ctx: ExtensionContext): SessionEntry[] {
+  const leafId = ctx.sessionManager.getLeafId?.();
+  if (leafId) {
+    const branch = ctx.sessionManager.getBranch?.(leafId);
+    if (Array.isArray(branch)) return branch as SessionEntry[];
+  }
+  const entries = ctx.sessionManager.getEntries?.();
+  return Array.isArray(entries) ? entries as SessionEntry[] : [];
+}
+
+function getSubagentToolCalls(message: any): Array<{ id: string; args: any }> {
+  if (!message || message.role !== "assistant" || !Array.isArray(message.content)) return [];
+  const calls: Array<{ id: string; args: any }> = [];
+  for (const part of message.content) {
+    if (part?.type === "toolCall" && part.name === "subagent" && typeof part.id === "string") {
+      calls.push({ id: part.id, args: part.arguments });
+    }
+  }
+  return calls;
+}
+
+function normalizeTasks(args: any): Array<{ agent: string; task: string; cwd?: string }> | null {
+  const rawTasks = args?.tasks;
+  if (!Array.isArray(rawTasks) || rawTasks.length === 0) return null;
+  const tasks: Array<{ agent: string; task: string; cwd?: string }> = [];
+  for (const task of rawTasks) {
+    if (typeof task?.agent !== "string" || typeof task?.task !== "string") return null;
+    tasks.push({
+      agent: task.agent,
+      task: task.task,
+      ...(typeof task.cwd === "string" ? { cwd: task.cwd } : {}),
+    });
+  }
+  return tasks;
+}
+
+function hasUnfinishedResults(details: SubagentDetails | undefined): boolean {
+  if (!details) return true;
+  return details.results.some((result) => result.exitCode === -1 || isResultError(result));
+}
+
+function messageHasNonEmptyText(message: any): boolean {
+  const content = message?.content;
+  if (typeof content === "string") return content.trim().length > 0;
+  if (!Array.isArray(content)) return false;
+  return content.some((part) => part?.type === "text" && typeof part.text === "string" && part.text.trim().length > 0);
+}
+
+function messageHasToolCall(message: any): boolean {
+  return Array.isArray(message?.content) && message.content.some((part: any) => part?.type === "toolCall");
+}
+
+function isIgnorableTrailingAbortMessage(entry: any): boolean {
+  if (entry?.type !== "message") return true;
+  const message = entry.message;
+  if (!message) return true;
+
+  // Pi may append a final aborted/error assistant message after it has already
+  // closed an interrupted tool with a synthetic toolResult. That message is not
+  // user-visible progress after the subagent activity, so it must not prevent
+  // resume detection.
+  if (
+    message.role === "assistant" &&
+    (message.stopReason === "aborted" || message.stopReason === "error") &&
+    !messageHasNonEmptyText(message) &&
+    !messageHasToolCall(message)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function hasOnlyIgnorableTrailingEntries(entries: SessionEntry[], activityOrder: number): boolean {
+  for (let i = activityOrder + 1; i < entries.length; i++) {
+    if (!isIgnorableTrailingAbortMessage(entries[i])) return false;
+  }
+  return true;
+}
+
+export function findLatestResumableSubagentCall(ctx: ExtensionContext): ResumableSubagentCall | null {
+  const entries = branchEntries(ctx);
+  const calls = new Map<string, { tasks: Array<{ agent: string; task: string; cwd?: string }>; order: number }>();
+  const results = new Map<string, { details?: SubagentDetails; isError: boolean; order: number }>();
+
+  entries.forEach((entry: any, order) => {
+    if (entry?.type !== "message") return;
+    const msg = entry.message;
+    for (const call of getSubagentToolCalls(msg)) {
+      const tasks = normalizeTasks(call.args);
+      if (tasks) calls.set(call.id, { tasks, order });
+    }
+    if (msg?.role === "toolResult" && msg.toolName === "subagent" && typeof msg.toolCallId === "string") {
+      results.set(msg.toolCallId, {
+        details: isSubagentDetails(msg.details) ? msg.details : undefined,
+        isError: msg.isError === true,
+        order,
+      });
+    }
+  });
+
+  const candidates: Array<ResumableSubagentCall & { activityOrder: number }> = [];
+  for (const [toolCallId, call] of calls) {
+    const result = results.get(toolCallId);
+    const unfinished = !result || result.isError || hasUnfinishedResults(result.details);
+    if (!unfinished) continue;
+    candidates.push({
+      previousToolCallId: toolCallId,
+      tasks: call.tasks,
+      details: result?.details,
+      activityOrder: result?.order ?? call.order,
+    });
+  }
+
+  const latest = candidates.at(-1);
+  if (!latest || !hasOnlyIgnorableTrailingEntries(entries, latest.activityOrder)) return null;
+  return latest;
+}
+
+export function sameTasks(
+  a: Array<{ agent: string; task: string; cwd?: string }>,
+  b: Array<{ agent: string; task: string; cwd?: string }>,
+): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function isFinishedResult(result: SingleResult | undefined): boolean {
+  return !!result && result.exitCode === 0 && !isResultError(result);
+}

package/runner.ts

@@ -21,6 +21,7 @@ import {
   getFinalOutput,
   getNestedSubagentErrorSummary,
 } from "./types.js";
+import { SUBAGENT_SESSION_ROOT_ENV } from "./resume.js";
 import {
   DEFAULT_MAX_PARALLEL_TASKS,
   DEFAULT_MAX_CONCURRENCY,
@@ -51,6 +52,7 @@ const SUBAGENT_DEPTH_ENV = "PI_SUBAGENT_DEPTH";
 const SUBAGENT_MAX_DEPTH_ENV = "PI_SUBAGENT_MAX_DEPTH";
 const SUBAGENT_STACK_ENV = "PI_SUBAGENT_STACK";
 const SUBAGENT_PREVENT_CYCLES_ENV = "PI_SUBAGENT_PREVENT_CYCLES";
+const SUBAGENT_FALLBACK_MODEL_ENV = "PI_SUBAGENT_FALLBACK_MODEL";
 // PI_OFFLINE intentionally removed: setting it on child processes blocks all API
 // calls and renders subagents unable to do any LLM work. Children inherit the
 // parent's PI_OFFLINE value via process.env spread if needed.
@@ -81,25 +83,6 @@ function cleanupTempDir(dir: string | null): void {
   }
 }
 
-function resolveWorkingDirectory(input: string, fallbackBase: string): string {
-  if (input.startsWith("~/")) return path.join(os.homedir(), input.slice(2));
-  if (path.isAbsolute(input)) return input;
-  return path.resolve(fallbackBase, input);
-}
-
-function getInvalidWorkingDirectoryMessage(input: string, resolved: string): string | null {
-  try {
-    const stat = fs.statSync(resolved);
-    if (!stat.isDirectory()) {
-      return `Invalid cwd "${input}" resolved to "${resolved}", but it is not a directory.`;
-    }
-    return null;
-  } catch (err) {
-    const detail = err instanceof Error ? err.message : String(err);
-    return `Invalid cwd "${input}" resolved to "${resolved}": ${detail}`;
-  }
-}
-
 function getCurrentPiCliScript(): string | null {
   const script = process.argv[1];
   if (!script) return null;
@@ -324,7 +307,7 @@ export function processJsonLine(line: string, result: SingleResult): boolean {
         result.usage.cost += usage.cost?.total || 0;
         result.usage.contextTokens = usage.totalTokens || 0;
       }
-      if (!result.model && msg.model) result.model = msg.model;
+      if (msg.model && msg.model !== "synthetic-tool-call") result.model = msg.model;
       if (msg.stopReason) result.stopReason = msg.stopReason;
       if (msg.errorMessage) result.errorMessage = msg.errorMessage;
     }
@@ -384,18 +367,23 @@ function buildPiArgs(
   agent: AgentConfig,
   systemPromptPath: string | null,
   task: string,
+  sessionDir: string | undefined,
+  resumeSession: boolean,
+  fallbackModelOverride?: string,
 ): string[] {
   const args: string[] = [
     "--mode",
     "json",
     ..._inheritedCliArgs.extensionArgs,
     ..._inheritedCliArgs.alwaysProxy,
-    "-p",
-    "--no-session",
   ];
 
+  if (sessionDir) args.push("--session-dir", sessionDir);
+  if (resumeSession) args.push("--continue");
+  args.push("-p");
+
   // Agent config takes priority; fall back to parent CLI value
-  const model = agent.model ?? _inheritedCliArgs.fallbackModel;
+  const model = agent.model ?? fallbackModelOverride ?? process.env[SUBAGENT_FALLBACK_MODEL_ENV] ?? _inheritedCliArgs.fallbackModel;
   if (model) args.push("--model", model);
 
   const thinking = agent.thinking ?? _inheritedCliArgs.fallbackThinking;
@@ -420,7 +408,11 @@ function buildPiArgs(
   }
 
   if (systemPromptPath) args.push("--append-system-prompt", systemPromptPath);
-  args.push(`Task: ${task}`);
+  args.push(
+    resumeSession
+      ? `Continue the previous task from where you left off. Original task: ${task}`
+      : `Task: ${task}`,
+  );
   return args;
 }
 
@@ -453,6 +445,16 @@ export interface RunAgentOptions {
   onUpdate?: OnUpdateCallback;
   /** Factory to wrap results into SubagentDetails. */
   makeDetails: (results: SingleResult[]) => SubagentDetails;
+  /** Dedicated session directory for this subagent process. */
+  sessionDir?: string;
+  /** Top-level root for all subagent session directories in this delegation tree. */
+  sessionRoot?: string;
+  /** Continue the most recent session in sessionDir instead of creating a new one. */
+  resumeSession?: boolean;
+  /** Previously captured state for this same subagent, used to render resumed nested trees. */
+  initialResult?: SingleResult;
+  /** Fallback model to use when the agent config does not pin one. */
+  fallbackModel?: string;
 }
 
 /**
@@ -474,6 +476,11 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
     signal,
     onUpdate,
     makeDetails,
+    sessionDir,
+    sessionRoot,
+    resumeSession = false,
+    initialResult,
+    fallbackModel,
   } = opts;
 
   const agent = agents.find((a) => a.name === agentName);
@@ -491,6 +498,7 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
       completedTurns: 0,
       turnInProgress: false,
       liveLog: [],
+      sessionDir: opts.sessionDir,
     };
   }
 
@@ -499,14 +507,16 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
     agentSource: agent.source,
     task,
     exitCode: -1,
-    messages: [],
-    stderr: "",
-    usage: emptyUsage(),
-    toolCalls: {},
-    model: agent.model,
-    completedTurns: 0,
+    messages: initialResult?.messages ? [...initialResult.messages] : [],
+    stderr: initialResult?.stderr ?? "",
+    usage: initialResult?.usage ? { ...initialResult.usage } : emptyUsage(),
+    toolCalls: initialResult?.toolCalls ? { ...initialResult.toolCalls } : {},
+    model: initialResult?.model ?? agent.model,
+    completedTurns: initialResult?.completedTurns ?? 0,
     turnInProgress: false,
-    liveLog: [],
+    liveToolExecutions: initialResult?.liveToolExecutions,
+    liveLog: initialResult?.liveLog ? [...initialResult.liveLog] : [],
+    sessionDir,
   };
 
   const emitUpdate = () => {
@@ -523,18 +533,6 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
 
   emitUpdate();
 
-  const requestedCwd = taskCwd ?? cwd;
-  const resolvedCwd = resolveWorkingDirectory(requestedCwd, cwd);
-  const invalidCwdMessage = getInvalidWorkingDirectoryMessage(requestedCwd, resolvedCwd);
-  if (invalidCwdMessage) {
-    result.exitCode = 1;
-    result.stopReason = "error";
-    result.errorMessage = invalidCwdMessage;
-    result.stderr = invalidCwdMessage;
-    emitUpdate();
-    return result;
-  }
-
   // Write system prompt to temp file if needed
   let promptTmpDir: string | null = null;
   let promptTmpPath: string | null = null;
@@ -549,6 +547,9 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
       agent,
       promptTmpPath,
       task,
+      sessionDir,
+      resumeSession,
+      fallbackModel,
     );
     let wasAborted = false;
 
@@ -564,7 +565,7 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
       const spawnCmd = currentPiCli ? process.execPath : "pi";
       const spawnArgs = currentPiCli ? [currentPiCli, ...piArgs] : piArgs;
       const proc = spawn(spawnCmd, spawnArgs, {
-        cwd: resolvedCwd,
+        cwd: taskCwd ?? cwd,
         shell: false,
         stdio: ["ignore", "pipe", "pipe"],
         env: {
@@ -573,6 +574,8 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
           [SUBAGENT_MAX_DEPTH_ENV]: String(propagatedMaxDepth),
           [SUBAGENT_STACK_ENV]: JSON.stringify(propagatedStack),
           [SUBAGENT_PREVENT_CYCLES_ENV]: preventCycles ? "1" : "0",
+          ...(sessionRoot ? { [SUBAGENT_SESSION_ROOT_ENV]: sessionRoot } : {}),
+          ...(fallbackModel ? { [SUBAGENT_FALLBACK_MODEL_ENV]: fallbackModel } : {}),
           // PI_OFFLINE is NOT forced here — see explanation near PI_OFFLINE_ENV.
         },
       });
@@ -698,10 +701,9 @@ export async function runAgentSubprocess(opts: RunAgentOptions): Promise<SingleR
       });
 
       proc.on("error", (err) => {
-        const message = `Failed to spawn pi process in cwd "${resolvedCwd}": ${err.message}`;
-        result.stderr += result.stderr ? `\n${message}` : message;
+        result.stderr += `Spawn error: ${err.message}`;
         result.stopReason = "error";
-        result.errorMessage = message;
+        result.errorMessage = `Failed to spawn pi process: ${err.message}`;
         doResolve(1);
       });
 
@@ -768,6 +770,11 @@ export async function executeParallelSubprocess(
   signal: AbortSignal | undefined,
   onUpdate: OnUpdateCallback | undefined,
   makeDetails: (results: SingleResult[]) => SubagentDetails,
+  resumeResults?: SingleResult[],
+  getSessionDir?: (index: number, task: { agent: string; task: string; cwd?: string }) => string | undefined,
+  resumeExistingSessions = false,
+  sessionRoot?: string,
+  fallbackModel?: string,
 ): Promise<{
   content: Array<{ type: "text"; text: string }>;
   details: SubagentDetails;
@@ -802,7 +809,7 @@ export async function executeParallelSubprocess(
     };
   }
 
-  const allResults: SingleResult[] = tasks.map((t) => ({
+  const allResults: SingleResult[] = tasks.map((t, index) => resumeResults?.[index] ?? ({
     agent: t.agent,
     agentSource: "unknown" as const,
     task: t.task,
@@ -814,6 +821,7 @@ export async function executeParallelSubprocess(
     completedTurns: 0,
     turnInProgress: false,
     liveLog: [],
+    sessionDir: getSessionDir?.(index, t),
   }));
 
   const emitProgress = () => {
@@ -842,6 +850,13 @@ export async function executeParallelSubprocess(
   let results: SingleResult[];
   try {
     results = await mapConcurrent(tasks, maxConcurrency, async (t, index) => {
+      const previousResult = resumeResults?.[index];
+      if (previousResult?.exitCode === 0) {
+        allResults[index] = previousResult;
+        emitProgress();
+        return previousResult;
+      }
+      const sessionDir = previousResult?.sessionDir ?? getSessionDir?.(index, t);
       const result = await runAgentSubprocess({
         cwd: defaultCwd,
         agents,
@@ -853,6 +868,11 @@ export async function executeParallelSubprocess(
         maxDepth,
         preventCycles,
         signal,
+        sessionDir,
+        sessionRoot,
+        resumeSession: resumeExistingSessions && !!sessionDir,
+        initialResult: previousResult,
+        fallbackModel,
         onUpdate: (partial) => {
           if (partial.details?.results[0]) {
             allResults[index] = partial.details.results[0];
@@ -872,8 +892,7 @@ export async function executeParallelSubprocess(
   const successCount = results.filter((r) => r.exitCode === 0).length;
   const summaries = results.map((r) => {
     const output = getFinalOutput(r.messages);
-    const error = r.errorMessage || r.stderr;
-    return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}: ${output || error || "(no output)"}`;
+    return `[${r.agent}] ${r.exitCode === 0 ? "completed" : "failed"}: ${output || "(no output)"}`;
   });
 
   return {

package/types.ts

@@ -45,6 +45,8 @@ export interface SingleResult {
 	model?: string;
 	stopReason?: string;
 	errorMessage?: string;
+	/** Session directory used by this subagent process, when persisted. */
+	sessionDir?: string;
 	/** Number of LLM turns completed so far in this agent run. */
 	completedTurns: number;
 	/** True while an LLM call is currently in flight (between turn_start and turn_end). */