pi-subagents 0.11.3 → 0.11.5

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [0.11.5] - 2026-03-20
+
+### Added
+- Added fork context preamble: tasks run with `context: "fork"` are now wrapped with a default preamble that anchors the subagent to its task, preventing it from continuing the parent conversation. The default is `DEFAULT_FORK_PREAMBLE` in `types.ts`. Internal/programmatic callers can use `wrapForkTask(task, false)` to disable it or pass a custom string (this is not exposed as a tool parameter).
+- Added a prompt-template delegation bridge (`prompt-template-bridge.ts`) on the shared extension event bus. The subagent extension now listens for `prompt-template:subagent:request` and emits correlated `started`/`response`/`update` events, with cwd safety checks and race-safe cancellation handling.
+- Added delegated progress streaming via `prompt-template:subagent:update`, mapped from subagent executor `onUpdate` progress payloads.
+
+### Changed
+- Session lifecycle reset now preserves the latest extension context for event-bus delegated runs.
+- `[fork]` badge is now shown only on the result row, not duplicated on both the tool-call and result rows.
+
+## [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

@@ -27,6 +27,7 @@ import { createSubagentExecutor } from "./subagent-executor.js";
 import { createAsyncJobTracker } from "./async-job-tracker.js";
 import { createResultWatcher } from "./result-watcher.js";
 import { registerSlashCommands } from "./slash-commands.js";
+import { registerPromptTemplateDelegationBridge } from "./prompt-template-bridge.js";
 import {
 	type Details,
 	type ExtensionConfig,
@@ -59,7 +60,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 +84,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);
 	}
@@ -134,6 +139,27 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		discoverAgents,
 	});
 
+	const promptTemplateBridge = registerPromptTemplateDelegationBridge({
+		events: pi.events,
+		getContext: () => state.lastUiContext,
+		execute: async (requestId, request, signal, ctx, onUpdate) =>
+			executor.execute(
+				requestId,
+				{
+					agent: request.agent,
+					task: request.task,
+					context: request.context,
+					cwd: request.cwd,
+					model: request.model,
+					async: false,
+					clarify: false,
+				},
+				signal,
+				onUpdate,
+				ctx,
+			),
+	});
+
 	const tool: ToolDefinition<typeof SubagentParams, Details> = {
 		name: "subagent",
 		label: "Subagent",
@@ -143,6 +169,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
@@ -277,7 +304,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,12 +345,15 @@ 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) => {
 		state.baseCwd = ctx.cwd;
 		state.currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+		state.lastUiContext = ctx;
 		cleanupSessionArtifacts(ctx);
 		resetJobs(ctx);
 	};
@@ -339,6 +376,8 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 		}
 		state.cleanupTimers.clear();
 		state.asyncJobs.clear();
+		promptTemplateBridge.cancelAll();
+		promptTemplateBridge.dispose();
 		if (state.lastUiContext?.hasUI) {
 			state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "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.
+	}
 }