pi-subagents 0.11.3 → 0.11.4

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.11.4] - 2026-03-19
+
+### Added
+- Added explicit execution context mode for tool calls: `context: "fresh" | "fork"` (default: `fresh`).
+- Added true forked-context execution for single, parallel, and chain runs. In `fork` mode each child run now starts from a real branched session file created from the parent session's current leaf.
+- Added `--fork` slash-command flag for `/run`, `/chain`, and `/parallel` to forward `context: "fork"`.
+- Added regression coverage for fork execution/session wiring and fork badge rendering, including slash command forwarding tests.
+
+### Changed
+- Session argument wiring now supports `--session <file>` in addition to `--session-dir`, enabling exact leaf-preserving forks without summary injection.
+- Async runner step payloads now carry per-step session files so background single/chain/parallel executions can also honor `context: "fork"`.
+- Clarified docs for foreground vs background semantics so `--bg` behavior is explicit.
+
+### Fixed
+- `context: "fork"` now fails fast with explicit errors when parent session state is unavailable (missing persisted session, missing current leaf, or failed branch extraction), with no silent fallback to `fresh`.
+- Fork-session creation errors are now surfaced as tool errors instead of bubbling as uncaught exceptions during execution.
+- Session directory preparation now fails loudly with actionable errors (instead of silently swallowing mkdir failures).
+- Async launch now fails with explicit errors when the async run directory cannot be created.
+- Share logs now correctly include forked session files even when no session directory exists.
+- Tool-call and result rendering now explicitly show `[fork]` when `context: "fork"` is used, including empty-result responses.
+- `subagent_status` now surfaces async result-file read failures instead of returning a misleading missing-status message.
+
 ## [0.11.3] - 2026-03-17
 
 ### Changed

package/README.md

@@ -172,7 +172,24 @@ Add `--bg` at the end of any slash command to run in the background:
 /parallel scout "scan frontend" -> scout "scan backend" -> scout "scan infra" --bg
 ```
 
-Background tasks run asynchronously and notify you when complete. Check status with `subagent_status`.
+Without `--bg`, the run is foreground: the tool call stays active and streams progress until completion. With `--bg`, the run is launched asynchronously: control returns immediately, and completion arrives later via notification. In both cases subagents run as separate processes. Check status with `subagent_status`.
+
+### Forked Context Execution
+
+Add `--fork` at the end of `/run`, `/chain`, or `/parallel` to run with `context: "fork"`:
+
+```
+/run reviewer "review this diff" --fork
+/chain scout "analyze this branch" -> planner "plan next steps" --fork
+/parallel scout "audit frontend" -> reviewer "audit backend" --fork
+```
+
+You can combine `--fork` and `--bg` in any order:
+
+```
+/run reviewer "review this diff" --fork --bg
+/run reviewer "review this diff" --bg --fork
+```
 
 ## Agents Manager
 
@@ -285,7 +302,9 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 | Chain | Yes | `{ chain: [{agent, task}...] }` with `{task}`, `{previous}`, `{chain_dir}` variables |
 | Parallel | Yes | `{ tasks: [{agent, task}...] }` - via TUI toggle or converted to chain for async |
 
-All modes support background/async execution. For programmatic async, use `clarify: false, async: true`. For interactive async, use `clarify: true` and press `b` in the TUI to toggle background mode before running. Chains with parallel steps (`{ parallel: [...] }`) run concurrently with configurable `concurrency` and `failFast` options.
+Execution context defaults to `context: "fresh"`, which starts each child run from a clean session. Set `context: "fork"` to start each child from a real branched session created from the parent's current leaf.
+
+All modes support foreground and background execution. Foreground is the default (the call waits and streams progress). For programmatic background launch, use `clarify: false, async: true`. For interactive background launch, use `clarify: true` and press `b` in the TUI before running. Chains with parallel steps (`{ parallel: [...] }`) run concurrently with configurable `concurrency` and `failFast` options.
 
 **Clarify TUI for single/parallel:**
 
@@ -397,9 +416,15 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
 { agent: "scout", task: "find todos", maxOutput: { lines: 1000 } }
 { agent: "scout", task: "investigate", output: false }  // disable file output
 
-// Parallel (sync only)
+// Single agent from parent-session fork (real branched session at current leaf)
+{ agent: "worker", task: "continue this thread", context: "fork" }
+
+// Parallel
 { tasks: [{ agent: "scout", task: "a" }, { agent: "scout", task: "b" }] }
 
+// Parallel with forked context (each task gets its own isolated fork)
+{ tasks: [{ agent: "scout", task: "audit frontend" }, { agent: "reviewer", task: "audit backend" }], context: "fork" }
+
 // Chain with TUI clarification (default)
 { chain: [
   { agent: "scout", task: "Gather context for auth refactor" },
@@ -408,6 +433,12 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
   { agent: "reviewer" }
 ]}
 
+// Chain with forked context (each step gets its own isolated fork of the same parent leaf)
+{ chain: [
+  { agent: "scout", task: "Analyze current branch decisions" },
+  { agent: "planner", task: "Plan from {previous}" }
+], context: "fork" }
+
 // Chain without TUI (enables async)
 { chain: [...], clarify: false, async: true }
 
@@ -529,6 +560,7 @@ Notes:
 | `model` | string | agent default | Override model for single agent |
 | `tasks` | `{agent, task, cwd?, skill?}[]` | - | Parallel tasks (sync only) |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
+| `context` | `"fresh" \| "fork"` | `fresh` | Execution context mode. `fork` uses a real branched session from the parent's current leaf for each child run |
 | `chainDir` | string | `<tmpdir>/pi-chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h) |
 | `clarify` | boolean | true (chains) | Show TUI to preview/edit chain; implies sync mode |
 | `agentScope` | `"user" \| "project" \| "both"` | `both` | Agent discovery scope (project wins on name collisions) |
@@ -540,6 +572,8 @@ Notes:
 | `share` | boolean | false | Upload session to GitHub Gist (see [Session Sharing](#session-sharing)) |
 | `sessionDir` | string | - | Override session log directory (takes precedence over `defaultSessionDir` and parent-session-derived path) |
 
+`context: "fork"` fails fast when the parent session is not persisted, the current leaf is missing, or a branched child session cannot be created. It never silently downgrades to `fresh`.
+
 **ChainItem** can be either a sequential step or a parallel step:
 
 *Sequential step fields:*
@@ -651,6 +685,8 @@ Files per task:
 
 Session files (JSONL) are stored under a per-run session directory. Directory selection follows the same precedence as session root resolution: explicit `sessionDir` > `config.defaultSessionDir` > parent-session-derived path. The session file path is shown in output.
 
+When `context: "fork"` is used, each child run starts with `--session <branched-session-file>` produced from the parent's current leaf. This is a real session fork, not injected summary text.
+
 ## Session Sharing
 
 When `share: true` is passed, the extension will:

package/async-execution.ts

@@ -12,7 +12,7 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
 import { applyThinkingSuffix } from "./pi-args.js";
 import { injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
-import { isParallelStep, resolveStepBehavior, type ChainStep, type ParallelStep, type SequentialStep, type StepOverrides } from "./settings.js";
+import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep, type StepOverrides } from "./settings.js";
 import type { RunnerStep } from "./parallel-utils.js";
 import { resolvePiPackageRoot } from "./pi-spawn.js";
 import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.js";
@@ -40,7 +40,9 @@ const jitiCliPath: string | undefined = (() => {
 		try {
 			const p = candidate();
 			if (fs.existsSync(p)) return p;
-		} catch {}
+		} catch {
+			// Candidate not available in this install, continue probing.
+		}
 	}
 	return undefined;
 })();
@@ -62,6 +64,7 @@ export interface AsyncChainParams {
 	shareEnabled: boolean;
 	sessionRoot?: string;
 	chainSkills?: string[];
+	sessionFilesByFlatIndex?: (string | undefined)[];
 }
 
 export interface AsyncSingleParams {
@@ -75,6 +78,7 @@ export interface AsyncSingleParams {
 	artifactConfig: ArtifactConfig;
 	shareEnabled: boolean;
 	sessionRoot?: string;
+	sessionFile?: string;
 	skills?: string[];
 	output?: string | false;
 }
@@ -119,7 +123,18 @@ export function executeAsyncChain(
 	id: string,
 	params: AsyncChainParams,
 ): AsyncExecutionResult {
-	const { chain, agents, ctx, cwd, maxOutput, artifactsDir, artifactConfig, shareEnabled, sessionRoot } = params;
+	const {
+		chain,
+		agents,
+		ctx,
+		cwd,
+		maxOutput,
+		artifactsDir,
+		artifactConfig,
+		shareEnabled,
+		sessionRoot,
+		sessionFilesByFlatIndex,
+	} = params;
 	const chainSkills = params.chainSkills ?? [];
 
 	// Validate all agents exist before building steps
@@ -141,10 +156,17 @@ export function executeAsyncChain(
 	const asyncDir = path.join(ASYNC_DIR, id);
 	try {
 		fs.mkdirSync(asyncDir, { recursive: true });
-	} catch {}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: `Failed to create async run directory '${asyncDir}': ${message}` }],
+			isError: true,
+			details: { mode: "chain" as const, results: [] },
+		};
+	}
 
 	/** Build a resolved runner step from a SequentialStep */
-	const buildSeqStep = (s: SequentialStep) => {
+	const buildSeqStep = (s: SequentialStep, sessionFile?: string) => {
 		const a = agents.find((x) => x.name === s.agent)!;
 		const stepSkillInput = normalizeSkillInput(s.skill);
 		const stepOverrides: StepOverrides = { skills: stepSkillInput };
@@ -174,9 +196,17 @@ export function executeAsyncChain(
 			systemPrompt,
 			skills: resolvedSkills.map((r) => r.name),
 			outputPath,
+			sessionFile,
 		};
 	};
 
+	let flatStepIndex = 0;
+	const nextSessionFile = (): string | undefined => {
+		const sessionFile = sessionFilesByFlatIndex?.[flatStepIndex];
+		flatStepIndex++;
+		return sessionFile;
+	};
+
 	// Build runner steps — sequential steps become flat objects,
 	// parallel steps become { parallel: [...], concurrency?, failFast? }
 	const steps: RunnerStep[] = chain.map((s) => {
@@ -189,12 +219,12 @@ export function executeAsyncChain(
 					skill: t.skill,
 					model: t.model,
 					output: t.output,
-				})),
+				}, nextSessionFile())),
 				concurrency: s.concurrency,
 				failFast: s.failFast,
 			};
 		}
-		return buildSeqStep(s as SequentialStep);
+		return buildSeqStep(s as SequentialStep, nextSessionFile());
 	});
 
 	const runnerCwd = cwd ?? ctx.cwd;
@@ -258,7 +288,19 @@ export function executeAsyncSingle(
 	id: string,
 	params: AsyncSingleParams,
 ): AsyncExecutionResult {
-	const { agent, task, agentConfig, ctx, cwd, maxOutput, artifactsDir, artifactConfig, shareEnabled, sessionRoot } = params;
+	const {
+		agent,
+		task,
+		agentConfig,
+		ctx,
+		cwd,
+		maxOutput,
+		artifactsDir,
+		artifactConfig,
+		shareEnabled,
+		sessionRoot,
+		sessionFile,
+	} = params;
 	const skillNames = params.skills ?? agentConfig.skills ?? [];
 	const { resolved: resolvedSkills } = resolveSkills(skillNames, ctx.cwd);
 	let systemPrompt = agentConfig.systemPrompt?.trim() || null;
@@ -270,7 +312,14 @@ export function executeAsyncSingle(
 	const asyncDir = path.join(ASYNC_DIR, id);
 	try {
 		fs.mkdirSync(asyncDir, { recursive: true });
-	} catch {}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: `Failed to create async run directory '${asyncDir}': ${message}` }],
+			isError: true,
+			details: { mode: "single" as const, results: [] },
+		};
+	}
 
 	const runnerCwd = cwd ?? ctx.cwd;
 	const outputPath = resolveSingleOutputPath(params.output, ctx.cwd, cwd);
@@ -290,6 +339,7 @@ export function executeAsyncSingle(
 					systemPrompt,
 					skills: resolvedSkills.map((r) => r.name),
 					outputPath,
+					sessionFile,
 				},
 			],
 			resultPath: path.join(RESULTS_DIR, `${id}.json`),

package/chain-execution.ts

@@ -70,6 +70,7 @@ export interface ChainExecutionParams {
 	cwd?: string;
 	shareEnabled: boolean;
 	sessionDirForIndex: (idx?: number) => string | undefined;
+	sessionFileForIndex?: (idx?: number) => string | undefined;
 	artifactsDir: string;
 	artifactConfig: ArtifactConfig;
 	includeProgress?: boolean;
@@ -103,6 +104,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 		cwd,
 		shareEnabled,
 		sessionDirForIndex,
+		sessionFileForIndex,
 		artifactsDir,
 		artifactConfig,
 		includeProgress,
@@ -333,6 +335,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						runId,
 						index: globalTaskIndex + taskIndex,
 						sessionDir: sessionDirForIndex(globalTaskIndex + taskIndex),
+						sessionFile: sessionFileForIndex?.(globalTaskIndex + taskIndex),
 						share: shareEnabled,
 						artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 						artifactConfig,
@@ -489,6 +492,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				runId,
 				index: globalTaskIndex,
 				sessionDir: sessionDirForIndex(globalTaskIndex),
+				sessionFile: sessionFileForIndex?.(globalTaskIndex),
 				share: shareEnabled,
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,

package/execution.ts

@@ -56,7 +56,7 @@ export async function runSync(
 	}
 
 	const shareEnabled = options.share === true;
-	const sessionEnabled = Boolean(options.sessionDir) || shareEnabled;
+	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
 	const effectiveModel = modelOverride ?? agent.model;
 	const modelArg = applyThinkingSuffix(effectiveModel, agent.thinking);
 
@@ -74,6 +74,7 @@ export async function runSync(
 		task,
 		sessionEnabled,
 		sessionDir: options.sessionDir,
+		sessionFile: options.sessionFile,
 		model: effectiveModel,
 		thinking: agent.thinking,
 		tools: agent.tools,
@@ -263,7 +264,9 @@ export async function runSync(
 					}
 					scheduleUpdate();
 				}
-			} catch {}
+			} catch {
+				// Non-JSON stdout lines are expected; only structured events are parsed.
+			}
 		};
 
 		let stderrBuf = "";
@@ -307,7 +310,9 @@ export async function runSync(
 	if (closeJsonlWriter) {
 		try {
 			await closeJsonlWriter();
-		} catch {}
+		} catch {
+			// JSONL artifact flush is best effort.
+		}
 	}
 
 	cleanupTempDir(tempDir);
@@ -379,8 +384,9 @@ export async function runSync(
 		}
 	}
 
-	if (shareEnabled && options.sessionDir) {
-		const sessionFile = findLatestSessionFile(options.sessionDir);
+	if (shareEnabled) {
+		const sessionFile = options.sessionFile
+			?? (options.sessionDir ? findLatestSessionFile(options.sessionDir) : null);
 		if (sessionFile) {
 			result.sessionFile = sessionFile;
 			// HTML export disabled - module resolution issues with global pi installation

package/fork-context.ts

@@ -0,0 +1,56 @@
+export type SubagentExecutionContext = "fresh" | "fork";
+
+export interface ForkableSessionManager {
+	getSessionFile(): string | undefined;
+	getLeafId(): string | null;
+	createBranchedSession(leafId: string): string | undefined;
+}
+
+export interface ForkContextResolver {
+	sessionFileForIndex(index?: number): string | undefined;
+}
+
+export function resolveSubagentContext(value: unknown): SubagentExecutionContext {
+	return value === "fork" ? "fork" : "fresh";
+}
+
+export function createForkContextResolver(
+	sessionManager: ForkableSessionManager,
+	requestedContext: unknown,
+): ForkContextResolver {
+	if (resolveSubagentContext(requestedContext) !== "fork") {
+		return {
+			sessionFileForIndex: () => undefined,
+		};
+	}
+
+	const parentSessionFile = sessionManager.getSessionFile();
+	if (!parentSessionFile) {
+		throw new Error("Forked subagent context requires a persisted parent session.");
+	}
+
+	const leafId = sessionManager.getLeafId();
+	if (!leafId) {
+		throw new Error("Forked subagent context requires a current leaf to fork from.");
+	}
+
+	const cachedSessionFiles = new Map<number, string>();
+
+	return {
+		sessionFileForIndex(index = 0): string | undefined {
+			const cached = cachedSessionFiles.get(index);
+			if (cached) return cached;
+			try {
+				const sessionFile = sessionManager.createBranchedSession(leafId);
+				if (!sessionFile) {
+					throw new Error("Session manager did not return a session file.");
+				}
+				cachedSessionFiles.set(index, sessionFile);
+				return sessionFile;
+			} catch (error) {
+				const cause = error instanceof Error ? error : new Error(String(error));
+				throw new Error(`Failed to create forked subagent session: ${cause.message}`, { cause });
+			}
+		},
+	};
+}

package/index.ts

@@ -59,7 +59,9 @@ function loadConfig(): ExtensionConfig {
 		if (fs.existsSync(configPath)) {
 			return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
 		}
-	} catch {}
+	} catch (error) {
+		console.error(`Failed to load subagent config from '${configPath}':`, error);
+	}
 	return {};
 }
 
@@ -81,7 +83,9 @@ function ensureAccessibleDir(dirPath: string): void {
 	} catch {
 		try {
 			fs.rmSync(dirPath, { recursive: true, force: true });
-		} catch {}
+		} catch {
+			// Best effort: retry mkdir/access even if cleanup fails.
+		}
 		fs.mkdirSync(dirPath, { recursive: true });
 		fs.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
 	}
@@ -143,6 +147,7 @@ EXECUTION (use exactly ONE mode):
 • SINGLE: { agent, task } - one task
 • CHAIN: { chain: [{agent:"scout"}, {agent:"planner"}] } - sequential pipeline
 • PARALLEL: { tasks: [{agent,task}, ...] } - concurrent execution
+• Optional context: { context: "fresh" | "fork" } (default: "fresh")
 
 CHAIN TEMPLATE VARIABLES (use in task strings):
 • {task} - The original task/request from the user
@@ -179,20 +184,21 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			}
 			const isParallel = (args.tasks?.length ?? 0) > 0;
 			const asyncLabel = args.async === true && !isParallel ? theme.fg("warning", " [async]") : "";
+			const contextLabel = args.context === "fork" ? theme.fg("warning", " [fork]") : "";
 			if (args.chain?.length)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}chain (${args.chain.length})${asyncLabel}`,
+					`${theme.fg("toolTitle", theme.bold("subagent "))}chain (${args.chain.length})${asyncLabel}${contextLabel}`,
 					0,
 					0,
 				);
 			if (isParallel)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${args.tasks!.length})`,
+					`${theme.fg("toolTitle", theme.bold("subagent "))}parallel (${args.tasks!.length})${contextLabel}`,
 					0,
 					0,
 				);
 			return new Text(
-				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent || "?")}${asyncLabel}`,
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent || "?")}${asyncLabel}${contextLabel}`,
 				0,
 				0,
 			);
@@ -277,7 +283,14 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 					const lines = [`Run: ${data.id ?? params.id}`, `State: ${status}`, `Result: ${resultPath}`];
 					if (data.summary) lines.push("", data.summary);
 					return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
-				} catch {}
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					return {
+						content: [{ type: "text", text: `Failed to read async result file: ${message}` }],
+						isError: true,
+						details: { mode: "single" as const, results: [] },
+					};
+				}
 			}
 
 			return {
@@ -311,7 +324,9 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			if (sessionFile) {
 				cleanupOldArtifacts(getArtifactsDir(sessionFile), DEFAULT_ARTIFACT_CONFIG.cleanupDays);
 			}
-		} catch {}
+		} catch {
+			// Cleanup failures should not block session lifecycle events.
+		}
 	};
 
 	const resetSessionState = (ctx: ExtensionContext) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/parallel-utils.ts

@@ -16,6 +16,7 @@ export interface RunnerSubagentStep {
 	systemPrompt?: string | null;
 	skills?: string[];
 	outputPath?: string;
+	sessionFile?: string;
 }
 
 /** Parallel step group — multiple agents running concurrently */

package/pi-args.ts

@@ -10,6 +10,7 @@ export interface BuildPiArgsInput {
 	task: string;
 	sessionEnabled: boolean;
 	sessionDir?: string;
+	sessionFile?: string;
 	model?: string;
 	thinking?: string;
 	tools?: string[];
@@ -36,14 +37,16 @@ export function applyThinkingSuffix(model: string | undefined, thinking: string
 export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	const args = [...input.baseArgs];
 
-	if (!input.sessionEnabled) {
-		args.push("--no-session");
-	}
-	if (input.sessionDir) {
-		try {
+	if (input.sessionFile) {
+		args.push("--session", input.sessionFile);
+	} else {
+		if (!input.sessionEnabled) {
+			args.push("--no-session");
+		}
+		if (input.sessionDir) {
 			fs.mkdirSync(input.sessionDir, { recursive: true });
-		} catch {}
-		args.push("--session-dir", input.sessionDir);
+			args.push("--session-dir", input.sessionDir);
+		}
 	}
 
 	const modelArg = applyThinkingSuffix(input.model, input.thinking);
@@ -118,5 +121,7 @@ export function cleanupTempDir(tempDir: string | null | undefined): void {
 	if (!tempDir) return;
 	try {
 		fs.rmSync(tempDir, { recursive: true, force: true });
-	} catch {}
+	} catch {
+		// Temp cleanup is best effort.
+	}
 }

package/render.ts

@@ -184,7 +184,8 @@ export function renderSubagentResult(
 	if (!d || !d.results.length) {
 		const t = result.content[0];
 		const text = t?.type === "text" ? t.text : "(no output)";
-		return new Text(truncLine(text, getTermWidth() - 4), 0, 0);
+		const contextPrefix = d?.context === "fork" ? `${theme.fg("warning", "[fork]")} ` : "";
+		return new Text(truncLine(`${contextPrefix}${text}`, getTermWidth() - 4), 0, 0);
 	}
 
 	const mdTheme = getMarkdownTheme();
@@ -197,6 +198,7 @@ export function renderSubagentResult(
 			: r.exitCode === 0
 				? theme.fg("success", "ok")
 				: theme.fg("error", "X");
+		const contextBadge = d.context === "fork" ? theme.fg("warning", " [fork]") : "";
 		const output = r.truncation?.text || getFinalOutput(r.messages);
 
 		const progressInfo = isRunning && r.progress
@@ -207,7 +209,7 @@ export function renderSubagentResult(
 
 		const w = getTermWidth() - 4;
 		const c = new Container();
-		c.addChild(new Text(truncLine(`${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${progressInfo}`, w), 0, 0));
+		c.addChild(new Text(truncLine(`${icon} ${theme.fg("toolTitle", theme.bold(r.agent))}${contextBadge}${progressInfo}`, w), 0, 0));
 		c.addChild(new Spacer(1));
 		const taskMaxLen = Math.max(20, w - 8);
 		const taskPreview = r.task.length > taskMaxLen
@@ -285,6 +287,7 @@ export function renderSubagentResult(
 			: "";
 
 	const modeLabel = d.mode;
+	const contextBadge = d.context === "fork" ? theme.fg("warning", " [fork]") : "";
 	// For parallel-in-chain, show task count (results) for consistency with step display
 	// For sequential chains, show logical step count
 	const hasParallelInChain = d.chainAgents?.some((a) => a.startsWith("["));
@@ -324,7 +327,7 @@ export function renderSubagentResult(
 	const c = new Container();
 	c.addChild(
 		new Text(
-			truncLine(`${icon} ${theme.fg("toolTitle", theme.bold(modeLabel))}${stepInfo}${summaryStr}`, w),
+			truncLine(`${icon} ${theme.fg("toolTitle", theme.bold(modeLabel))}${contextBadge}${stepInfo}${summaryStr}`, w),
 			0,
 			0,
 		),

package/schemas.ts

@@ -76,6 +76,10 @@ export const SubagentParams = Type.Object({
 	})),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task}, ...]" })),
 	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential pipeline where each step's response becomes {previous} for the next. Use {task}, {previous}, {chain_dir} in task templates." })),
+	context: Type.Optional(Type.String({
+		enum: ["fresh", "fork"],
+		description: "Execution context mode: 'fresh' (default) starts clean, 'fork' starts from a real fork of the parent session leaf",
+	})),
 	chainDir: Type.Optional(Type.String({ description: "Persistent directory for chain artifacts. Default: <tmpdir>/pi-chain-runs/ (auto-cleaned after 24h)" })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),

package/slash-commands.ts

@@ -49,11 +49,26 @@ const parseAgentToken = (token: string): { name: string; config: InlineConfig }
 	return { name: token.slice(0, bracket), config: parseInlineConfig(token.slice(bracket + 1, end !== -1 ? end : undefined)) };
 };
 
-const extractBgFlag = (args: string): { args: string; bg: boolean } => {
-	if (args.endsWith(" --bg") || args === "--bg") {
-		return { args: args.slice(0, args.length - (args === "--bg" ? 4 : 5)).trim(), bg: true };
+const extractExecutionFlags = (rawArgs: string): { args: string; bg: boolean; fork: boolean } => {
+	let args = rawArgs.trim();
+	let bg = false;
+	let fork = false;
+
+	while (true) {
+		if (args.endsWith(" --bg") || args === "--bg") {
+			bg = true;
+			args = args === "--bg" ? "" : args.slice(0, -5).trim();
+			continue;
+		}
+		if (args.endsWith(" --fork") || args === "--fork") {
+			fork = true;
+			args = args === "--fork" ? "" : args.slice(0, -7).trim();
+			continue;
+		}
+		break;
 	}
-	return { args, bg: false };
+
+	return { args, bg, fork };
 };
 
 function setupDirectRun(ctx: ExtensionContext, getSubagentSessionRoot: (parentSessionFile: string | null) => string) {
@@ -62,7 +77,10 @@ function setupDirectRun(ctx: ExtensionContext, getSubagentSessionRoot: (parentSe
 	const sessionRoot = path.join(getSubagentSessionRoot(parentSessionFile), runId);
 	try {
 		fs.mkdirSync(sessionRoot, { recursive: true });
-	} catch {}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to create session directory '${sessionRoot}': ${message}`);
+	}
 	return {
 		runId,
 		shareEnabled: false,
@@ -130,7 +148,7 @@ async function openAgentManager(
 					const id = randomUUID();
 					const asyncCtx = { pi, cwd: ctx.cwd, currentSessionId: ctx.sessionManager.getSessionId() ?? id };
 					const asyncSessionRoot = getSubagentSessionRoot(ctx.sessionManager.getSessionFile() ?? null);
-					try { fs.mkdirSync(asyncSessionRoot, { recursive: true }); } catch {}
+					fs.mkdirSync(asyncSessionRoot, { recursive: true });
 					executeAsyncChain(id, {
 						chain: r.requestedAsync.chain,
 						agents,
@@ -268,16 +286,16 @@ export function registerSlashCommands(
 	});
 
 	pi.registerCommand("run", {
-		description: "Run a subagent directly: /run agent[output=file] task [--bg]",
+		description: "Run a subagent directly: /run agent[output=file] task [--bg] [--fork]",
 		getArgumentCompletions: makeAgentCompletions(state, false),
 		handler: async (args, ctx) => {
-			const { args: cleanedArgs, bg } = extractBgFlag(args);
+			const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
 			const input = cleanedArgs.trim();
 			const firstSpace = input.indexOf(" ");
-			if (firstSpace === -1) { ctx.ui.notify("Usage: /run <agent> <task> [--bg]", "error"); return; }
+			if (firstSpace === -1) { ctx.ui.notify("Usage: /run <agent> <task> [--bg] [--fork]", "error"); return; }
 			const { name: agentName, config: inline } = parseAgentToken(input.slice(0, firstSpace));
 			const task = input.slice(firstSpace + 1).trim();
-			if (!task) { ctx.ui.notify("Usage: /run <agent> <task> [--bg]", "error"); return; }
+			if (!task) { ctx.ui.notify("Usage: /run <agent> <task> [--bg] [--fork]", "error"); return; }
 
 			const agents = discoverAgents(state.baseCwd, "both").agents;
 			if (!agents.find((a) => a.name === agentName)) { ctx.ui.notify(`Unknown agent: ${agentName}`, "error"); return; }
@@ -291,15 +309,16 @@ export function registerSlashCommands(
 			if (inline.skill !== undefined) params.skill = inline.skill;
 			if (inline.model) params.model = inline.model;
 			if (bg) params.async = true;
+			if (fork) params.context = "fork";
 			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify({ ...params, agentScope: "both" })}`);
 		},
 	});
 
 	pi.registerCommand("chain", {
-		description: "Run agents in sequence: /chain scout \"task\" -> planner [--bg]",
+		description: "Run agents in sequence: /chain scout \"task\" -> planner [--bg] [--fork]",
 		getArgumentCompletions: makeAgentCompletions(state, true),
 		handler: async (args, ctx) => {
-			const { args: cleanedArgs, bg } = extractBgFlag(args);
+			const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
 			const parsed = parseAgentArgs(state, cleanedArgs, "chain", ctx);
 			if (!parsed) return;
 			const chain = parsed.steps.map(({ name, config, task: stepTask }, i) => ({
@@ -313,15 +332,16 @@ export function registerSlashCommands(
 			}));
 			const params: Record<string, unknown> = { chain, task: parsed.task, clarify: false, agentScope: "both" };
 			if (bg) params.async = true;
+			if (fork) params.context = "fork";
 			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify(params)}`);
 		},
 	});
 
 	pi.registerCommand("parallel", {
-		description: "Run agents in parallel: /parallel scout \"task1\" -> reviewer \"task2\" [--bg]",
+		description: "Run agents in parallel: /parallel scout \"task1\" -> reviewer \"task2\" [--bg] [--fork]",
 		getArgumentCompletions: makeAgentCompletions(state, true),
 		handler: async (args, ctx) => {
-			const { args: cleanedArgs, bg } = extractBgFlag(args);
+			const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
 			const parsed = parseAgentArgs(state, cleanedArgs, "parallel", ctx);
 			if (!parsed) return;
 			if (parsed.steps.length > MAX_PARALLEL) { ctx.ui.notify(`Max ${MAX_PARALLEL} parallel tasks`, "error"); return; }
@@ -336,6 +356,7 @@ export function registerSlashCommands(
 			}));
 			const params: Record<string, unknown> = { chain: [{ parallel: tasks }], task: parsed.task, clarify: false, agentScope: "both" };
 			if (bg) params.async = true;
+			if (fork) params.context = "fork";
 			pi.sendUserMessage(`Call the subagent tool with these exact parameters: ${JSON.stringify(params)}`);
 		},
 	});

package/subagent-executor.ts

@@ -21,6 +21,7 @@ import {
 } from "./settings.js";
 import { discoverAvailableSkills, normalizeSkillInput } from "./skills.js";
 import { executeAsyncChain, executeAsyncSingle, isAsyncAvailable } from "./async-execution.js";
+import { createForkContextResolver } from "./fork-context.js";
 import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
 import { getFinalOutput, mapConcurrent } from "./utils.js";
 import {
@@ -55,6 +56,7 @@ interface SubagentParamsLike {
 	task?: string;
 	chain?: ChainStep[];
 	tasks?: TaskParam[];
+	context?: "fresh" | "fork";
 	async?: boolean;
 	clarify?: boolean;
 	share?: boolean;
@@ -91,6 +93,7 @@ interface ExecutionContextData {
 	shareEnabled: boolean;
 	sessionRoot: string;
 	sessionDirForIndex: (idx?: number) => string;
+	sessionFileForIndex: (idx?: number) => string | undefined;
 	artifactConfig: ArtifactConfig;
 	artifactsDir: string;
 	parallelDowngraded: boolean;
@@ -167,8 +170,71 @@ function validateExecutionInput(
 	return null;
 }
 
+function getRequestedModeLabel(params: SubagentParamsLike): Details["mode"] {
+	if ((params.chain?.length ?? 0) > 0) return "chain";
+	if ((params.tasks?.length ?? 0) > 0) return "parallel";
+	if (params.agent && params.task) return "single";
+	return "single";
+}
+
+function withForkContext(
+	result: AgentToolResult<Details>,
+	context: SubagentParamsLike["context"],
+): AgentToolResult<Details> {
+	if (context !== "fork" || !result.details) return result;
+	return {
+		...result,
+		details: {
+			...result.details,
+			context: "fork",
+		},
+	};
+}
+
+function toExecutionErrorResult(params: SubagentParamsLike, error: unknown): AgentToolResult<Details> {
+	const message = error instanceof Error ? error.message : String(error);
+	return withForkContext(
+		{
+			content: [{ type: "text", text: message }],
+			isError: true,
+			details: { mode: getRequestedModeLabel(params), results: [] },
+		},
+		params.context,
+	);
+}
+
+function collectChainSessionFiles(
+	chain: ChainStep[],
+	sessionFileForIndex: (idx?: number) => string | undefined,
+): (string | undefined)[] {
+	const sessionFiles: (string | undefined)[] = [];
+	let flatIndex = 0;
+	for (const step of chain) {
+		if (isParallelStep(step)) {
+			for (let i = 0; i < step.parallel.length; i++) {
+				sessionFiles.push(sessionFileForIndex(flatIndex));
+				flatIndex++;
+			}
+			continue;
+		}
+		sessionFiles.push(sessionFileForIndex(flatIndex));
+		flatIndex++;
+	}
+	return sessionFiles;
+}
+
 function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentToolResult<Details> | null {
-	const { params, agents, ctx, shareEnabled, sessionRoot, artifactConfig, artifactsDir, effectiveAsync } = data;
+	const {
+		params,
+		agents,
+		ctx,
+		shareEnabled,
+		sessionRoot,
+		sessionFileForIndex,
+		artifactConfig,
+		artifactsDir,
+		effectiveAsync,
+	} = data;
 	const hasChain = (params.chain?.length ?? 0) > 0;
 	const hasSingle = Boolean(params.agent && params.task);
 	if (!effectiveAsync) return null;
@@ -197,6 +263,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			shareEnabled,
 			sessionRoot,
 			chainSkills,
+			sessionFilesByFlatIndex: collectChainSessionFiles(params.chain as ChainStep[], sessionFileForIndex),
 		});
 	}
 
@@ -204,13 +271,15 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		const a = agents.find((x) => x.name === params.agent);
 		if (!a) {
 			return {
-				content: [{ type: "text", text: `Unknown: ${params.agent}` }],
+				content: [{ type: "text", text: `Unknown agent: ${params.agent}` }],
 				isError: true,
 				details: { mode: "single" as const, results: [] },
 			};
 		}
 		const rawOutput = params.output !== undefined ? params.output : a.output;
 		const effectiveOutput: string | false | undefined = rawOutput === true ? a.output : (rawOutput as string | false | undefined);
+		const normalizedSkills = normalizeSkillInput(params.skill);
+		const skills = normalizedSkills === false ? [] : normalizedSkills;
 		return executeAsyncSingle(id, {
 			agent: params.agent!,
 			task: params.task!,
@@ -222,12 +291,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			artifactConfig,
 			shareEnabled,
 			sessionRoot,
-			skills: (() => {
-				const normalized = normalizeSkillInput(params.skill);
-				if (normalized === false) return [];
-				if (normalized === undefined) return undefined;
-				return normalized;
-			})(),
+			sessionFile: sessionFileForIndex(0),
+			skills,
 			output: effectiveOutput,
 		});
 	}
@@ -236,7 +301,20 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 }
 
 async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
-	const { params, agents, ctx, signal, runId, shareEnabled, sessionDirForIndex, artifactsDir, artifactConfig, onUpdate, sessionRoot } = data;
+	const {
+		params,
+		agents,
+		ctx,
+		signal,
+		runId,
+		shareEnabled,
+		sessionDirForIndex,
+		sessionFileForIndex,
+		artifactsDir,
+		artifactConfig,
+		onUpdate,
+		sessionRoot,
+	} = data;
 	const normalized = normalizeSkillInput(params.skill);
 	const chainSkills = normalized === false ? [] : (normalized ?? []);
 	const chainResult = await executeChain({
@@ -249,6 +327,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		cwd: params.cwd,
 		shareEnabled,
 		sessionDirForIndex,
+		sessionFileForIndex,
 		artifactsDir,
 		artifactConfig,
 		includeProgress: params.includeProgress,
@@ -279,6 +358,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			shareEnabled,
 			sessionRoot,
 			chainSkills: chainResult.requestedAsync.chainSkills,
+			sessionFilesByFlatIndex: collectChainSessionFiles(chainResult.requestedAsync.chain, sessionFileForIndex),
 		});
 	}
 
@@ -286,7 +366,21 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 }
 
 async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
-	const { params, agents, ctx, signal, runId, sessionDirForIndex, shareEnabled, artifactConfig, artifactsDir, parallelDowngraded, onUpdate, sessionRoot } = data;
+	const {
+		params,
+		agents,
+		ctx,
+		signal,
+		runId,
+		sessionDirForIndex,
+		sessionFileForIndex,
+		shareEnabled,
+		artifactConfig,
+		artifactsDir,
+		parallelDowngraded,
+		onUpdate,
+		sessionRoot,
+	} = data;
 	const allProgress: AgentProgress[] = [];
 	const allArtifactPaths: ArtifactPaths[] = [];
 	const tasks = params.tasks!;
@@ -385,6 +479,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				shareEnabled,
 				sessionRoot,
 				chainSkills: [],
+				sessionFilesByFlatIndex: tasks.map((_, index) => sessionFileForIndex(index)),
 			});
 		}
 	}
@@ -401,6 +496,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			runId,
 			index: i,
 			sessionDir: sessionDirForIndex(i),
+			sessionFile: sessionFileForIndex(i),
 			share: shareEnabled,
 			artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 			artifactConfig,
@@ -465,7 +561,20 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 }
 
 async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
-	const { params, agents, ctx, signal, runId, sessionDirForIndex, shareEnabled, artifactConfig, artifactsDir, onUpdate, sessionRoot } = data;
+	const {
+		params,
+		agents,
+		ctx,
+		signal,
+		runId,
+		sessionDirForIndex,
+		sessionFileForIndex,
+		shareEnabled,
+		artifactConfig,
+		artifactsDir,
+		onUpdate,
+		sessionRoot,
+	} = data;
 	const allProgress: AgentProgress[] = [];
 	const allArtifactPaths: ArtifactPaths[] = [];
 	const agentConfig = agents.find((a) => a.name === params.agent);
@@ -541,6 +650,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				artifactConfig,
 				shareEnabled,
 				sessionRoot,
+				sessionFile: sessionFileForIndex(0),
 				skills: skillOverride === false ? [] : skillOverride,
 				output: effectiveOutput,
 			});
@@ -551,17 +661,19 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, params.cwd);
 	task = injectSingleOutputInstruction(task, outputPath);
 
-	const effectiveSkills = skillOverride === false
-		? []
-		: skillOverride === undefined
-			? undefined
-			: skillOverride;
+	let effectiveSkills: string[] | undefined;
+	if (skillOverride === false) {
+		effectiveSkills = [];
+	} else {
+		effectiveSkills = skillOverride;
+	}
 
 	const r = await runSync(ctx.cwd, agents, params.agent!, task, {
 		cwd: params.cwd,
 		signal,
 		runId,
 		sessionDir: sessionDirForIndex(0),
+		sessionFile: sessionFileForIndex(0),
 		share: shareEnabled,
 		artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 		artifactConfig,
@@ -659,31 +771,26 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		const agents = deps.discoverAgents(ctx.cwd, scope).agents;
 		const runId = randomUUID().slice(0, 8);
 		const shareEnabled = params.share === true;
-		const sessionRoot = params.sessionDir
-			? path.resolve(deps.expandTilde(params.sessionDir))
-			: path.join(
-				deps.config.defaultSessionDir
-					? path.resolve(deps.expandTilde(deps.config.defaultSessionDir))
-					: deps.getSubagentSessionRoot(parentSessionFile),
-				runId,
-			);
-		try {
-			fs.mkdirSync(sessionRoot, { recursive: true });
-		} catch {}
-		const sessionDirForIndex = (idx?: number) =>
-			path.join(sessionRoot, `run-${idx ?? 0}`);
-
 		const hasChain = (params.chain?.length ?? 0) > 0;
 		const hasTasks = (params.tasks?.length ?? 0) > 0;
 		const hasSingle = Boolean(params.agent && params.task);
 
+		const validationError = validateExecutionInput(params, agents, hasChain, hasTasks, hasSingle);
+		if (validationError) return validationError;
+
+		let sessionFileForIndex: (idx?: number) => string | undefined = () => undefined;
+		try {
+			sessionFileForIndex = createForkContextResolver(ctx.sessionManager, params.context).sessionFileForIndex;
+		} catch (error) {
+			return toExecutionErrorResult(params, error);
+		}
+
 		const requestedAsync = params.async ?? deps.asyncByDefault;
 		const parallelDowngraded = hasTasks && requestedAsync;
-		const effectiveAsync = requestedAsync && !hasTasks && (
-			hasChain
-				? params.clarify === false
-				: params.clarify !== true
-		);
+		let effectiveAsync = false;
+		if (requestedAsync && !hasTasks) {
+			effectiveAsync = hasChain ? params.clarify === false : params.clarify !== true;
+		}
 
 		const artifactConfig: ArtifactConfig = {
 			...DEFAULT_ARTIFACT_CONFIG,
@@ -691,45 +798,72 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		};
 		const artifactsDir = effectiveAsync ? deps.tempArtifactsDir : getArtifactsDir(parentSessionFile);
 
-		const validationError = validateExecutionInput(params, agents, hasChain, hasTasks, hasSingle);
-		if (validationError) return validationError;
+		let sessionRoot: string;
+		if (params.sessionDir) {
+			sessionRoot = path.resolve(deps.expandTilde(params.sessionDir));
+		} else {
+			const baseSessionRoot = deps.config.defaultSessionDir
+				? path.resolve(deps.expandTilde(deps.config.defaultSessionDir))
+				: deps.getSubagentSessionRoot(parentSessionFile);
+			sessionRoot = path.join(baseSessionRoot, runId);
+		}
+		try {
+			fs.mkdirSync(sessionRoot, { recursive: true });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return toExecutionErrorResult(
+				params,
+				new Error(`Failed to create session directory '${sessionRoot}': ${message}`),
+			);
+		}
+		const sessionDirForIndex = (idx?: number) =>
+			path.join(sessionRoot, `run-${idx ?? 0}`);
+
+		const onUpdateWithContext = onUpdate
+			? (r: AgentToolResult<Details>) => onUpdate(withForkContext(r, params.context))
+			: undefined;
 
 		const execData: ExecutionContextData = {
 			params,
 			ctx,
 			signal,
-			onUpdate,
+			onUpdate: onUpdateWithContext,
 			agents,
 			runId,
 			shareEnabled,
 			sessionRoot,
 			sessionDirForIndex,
+			sessionFileForIndex,
 			artifactConfig,
 			artifactsDir,
 			parallelDowngraded,
 			effectiveAsync,
 		};
 
-		const asyncResult = runAsyncPath(execData, deps);
-		if (asyncResult) return asyncResult;
+		try {
+			const asyncResult = runAsyncPath(execData, deps);
+			if (asyncResult) return withForkContext(asyncResult, params.context);
 
-		if (hasChain && params.chain) {
-			return runChainPath(execData, deps);
-		}
+			if (hasChain && params.chain) {
+				return withForkContext(await runChainPath(execData, deps), params.context);
+			}
 
-		if (hasTasks && params.tasks) {
-			return runParallelPath(execData, deps);
-		}
+			if (hasTasks && params.tasks) {
+				return withForkContext(await runParallelPath(execData, deps), params.context);
+			}
 
-		if (hasSingle) {
-			return runSinglePath(execData, deps);
+			if (hasSingle) {
+				return withForkContext(await runSinglePath(execData, deps), params.context);
+			}
+		} catch (error) {
+			return toExecutionErrorResult(params, error);
 		}
 
-		return {
+		return withForkContext({
 			content: [{ type: "text", text: "Invalid params" }],
 			isError: true,
 			details: { mode: "single" as const, results: [] },
-		};
+		}, params.context);
 	};
 
 	return { execute };

package/subagent-runner.ts

@@ -64,6 +64,7 @@ function findLatestSessionFile(sessionDir: string): string | null {
 		files.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
 		return files[0] ?? null;
 	} catch {
+		// Session lookup is optional metadata.
 		return null;
 	}
 }
@@ -89,10 +90,13 @@ function parseSessionTokens(sessionDir: string): TokenUsage | null {
 					input += entry.usage.inputTokens ?? entry.usage.input ?? 0;
 					output += entry.usage.outputTokens ?? entry.usage.output ?? 0;
 				}
-			} catch {}
+			} catch {
+				// Ignore malformed lines while scanning usage entries.
+			}
 		}
 		return { input, output, total: input + output };
 	} catch {
+		// Usage extraction should not fail the run.
 		return null;
 	}
 }
@@ -143,7 +147,9 @@ function resolvePiPackageRootFallback(): string {
 		try {
 			const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
 			if (pkg.name === "@mariozechner/pi-coding-agent") return dir;
-		} catch {}
+		} catch {
+			// Keep walking up until a readable package.json is found.
+		}
 		dir = path.dirname(dir);
 	}
 	throw new Error("Could not resolve @mariozechner/pi-coding-agent package root");
@@ -277,11 +283,14 @@ async function runSingleStep(
 ): Promise<{ agent: string; output: string; exitCode: number | null; artifactPaths?: ArtifactPaths }> {
 	const placeholderRegex = new RegExp(ctx.placeholder.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
 	const task = step.task.replace(placeholderRegex, () => ctx.previousOutput);
+	const sessionEnabled = Boolean(step.sessionFile) || ctx.sessionEnabled;
+	const sessionDir = step.sessionFile ? undefined : ctx.sessionDir;
 	const { args, env, tempDir } = buildPiArgs({
 		baseArgs: ["-p"],
 		task,
-		sessionEnabled: ctx.sessionEnabled,
-		sessionDir: ctx.sessionDir,
+		sessionEnabled,
+		sessionDir,
+		sessionFile: step.sessionFile,
 		model: step.model,
 		tools: step.tools,
 		extensions: step.extensions,
@@ -349,15 +358,18 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	const results: StepResult[] = [];
 	const overallStartTime = Date.now();
 	const shareEnabled = config.share === true;
-	const sessionEnabled = Boolean(config.sessionDir) || shareEnabled;
 	const asyncDir = config.asyncDir;
 	const statusPath = path.join(asyncDir, "status.json");
 	const eventsPath = path.join(asyncDir, "events.jsonl");
 	const logPath = path.join(asyncDir, `subagent-log-${id}.md`);
 	let previousCumulativeTokens: TokenUsage = { input: 0, output: 0, total: 0 };
+	let latestSessionFile: string | undefined;
 
 	// Flatten steps for status tracking (parallel groups expand to individual entries)
 	const flatSteps = flattenSteps(steps);
+	const sessionEnabled = Boolean(config.sessionDir)
+		|| shareEnabled
+		|| flatSteps.some((step) => Boolean(step.sessionFile));
 	const statusPayload: {
 		runId: string;
 		mode: "single" | "chain";
@@ -480,6 +492,9 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 						outputFile: path.join(asyncDir, `output-${fi}.log`),
 						piPackageRoot: config.piPackageRoot,
 					});
+					if (task.sessionFile) {
+						latestSessionFile = task.sessionFile;
+					}
 
 					const taskEndTime = Date.now();
 					const taskDuration = taskEndTime - taskStartTime;
@@ -580,6 +595,9 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				outputFile: path.join(asyncDir, `output-${flatIndex}.log`),
 				piPackageRoot: config.piPackageRoot,
 			});
+			if (seqStep.sessionFile) {
+				latestSessionFile = seqStep.sessionFile;
+			}
 
 			previousOutput = singleResult.output;
 			results.push({
@@ -652,11 +670,17 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 	let gistUrl: string | undefined;
 	let shareError: string | undefined;
 
-	if (shareEnabled && config.sessionDir) {
-		sessionFile = findLatestSessionFile(config.sessionDir) ?? undefined;
+	if (shareEnabled) {
+		sessionFile = config.sessionDir
+			? (findLatestSessionFile(config.sessionDir) ?? undefined)
+			: undefined;
+		if (!sessionFile && latestSessionFile) {
+			sessionFile = latestSessionFile;
+		}
 		if (sessionFile) {
 			try {
-				const htmlPath = await exportSessionHtml(sessionFile, config.sessionDir, config.piPackageRoot);
+				const exportDir = config.sessionDir ?? path.dirname(sessionFile);
+				const htmlPath = await exportSessionHtml(sessionFile, exportDir, config.piPackageRoot);
 				const share = createShareLink(htmlPath);
 				if ("error" in share) shareError = share.error;
 				else {
@@ -671,11 +695,12 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		}
 	}
 
+	const effectiveSessionFile = sessionFile ?? latestSessionFile;
 	const runEndedAt = Date.now();
 	statusPayload.state = results.every((r) => r.success) ? "complete" : "failed";
 	statusPayload.endedAt = runEndedAt;
 	statusPayload.lastUpdate = runEndedAt;
-	statusPayload.sessionFile = sessionFile;
+	statusPayload.sessionFile = effectiveSessionFile;
 	statusPayload.shareUrl = shareUrl;
 	statusPayload.gistUrl = gistUrl;
 	statusPayload.shareError = shareError;
@@ -710,7 +735,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		summary,
 		truncated,
 		artifactsDir,
-		sessionFile,
+		sessionFile: effectiveSessionFile,
 		shareUrl,
 		shareError,
 	});
@@ -740,7 +765,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				cwd,
 				asyncDir,
 				sessionId: config.sessionId,
-				sessionFile,
+				sessionFile: effectiveSessionFile,
 				shareUrl,
 				gistUrl,
 				shareError,
@@ -760,7 +785,9 @@ if (configArg) {
 		const config = JSON.parse(configJson) as SubagentRunConfig;
 		try {
 			fs.unlinkSync(configArg);
-		} catch {}
+		} catch {
+			// Temp config cleanup is best effort.
+		}
 		runSubagent(config).catch((runErr) => {
 			console.error("Subagent runner error:", runErr);
 			process.exit(1);

package/types.ts

@@ -101,6 +101,7 @@ export interface SingleResult {
 
 export interface Details {
 	mode: "single" | "parallel" | "chain" | "management";
+	context?: "fresh" | "fork";
 	results: SingleResult[];
 	asyncId?: string;
 	asyncDir?: string;
@@ -226,6 +227,7 @@ export interface RunSyncOptions {
 	runId: string;
 	index?: number;
 	sessionDir?: string;
+	sessionFile?: string;
 	share?: boolean;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;