@estebanforge/pi-antigravity-bridge 1.7.2 → 1.7.4

package/src/agy-paths.ts

@@ -0,0 +1,33 @@
+// agy per-engine state dirs ("brain" trees).
+//
+// Both engines keep per-conversation state on disk; the roots differ
+// (live-probed 2026-09-24, this machine):
+//   stream-json CLI:  ~/.gemini/antigravity-cli/brain/<conversationId>/
+//   ACP server:       ~/.gemini/antigravity-acp/brain/<conversationId>/
+// The ACP tree mirrors the CLI layout (.system_generated/tasks/,
+// .system_generated/steps/), so downstream scans (tasks, artifacts) work
+// unchanged once the right root is picked. A third tree exists —
+// ~/.gemini/antigravity-cli/conversations/<uuid>.db — but it serves
+// one-shot print-mode calls (AskAntigravity), NOT these features; do not
+// conflate the two. Conversation ids are the raw ids agy reports, no
+// hashing; the ids our session store persists match these dir names.
+
+import os from "node:os";
+import path from "node:path";
+import type { Engine } from "./config.js";
+
+/** Brain root for one engine. `home` injectable for tests. */
+export function agyBrainRoot(engine: Engine, home: string = os.homedir()): string {
+	const scope = engine === "acp" ? "antigravity-acp" : "antigravity-cli";
+	return path.join(home, ".gemini", scope, "brain");
+}
+
+/** Per-conversation state dir. `conversationId` is the raw id agy reports
+ *  (and what the session store persists). */
+export function agyConversationDir(
+	engine: Engine,
+	conversationId: string,
+	home: string = os.homedir(),
+): string {
+	return path.join(agyBrainRoot(engine, home), conversationId);
+}

package/src/agy-version.ts

@@ -0,0 +1,137 @@
+// agy CLI version gate.
+//
+// An agy older than MIN_AGY_VERSION fails stream-json turns with raw stream
+// errors that look like bridge bugs, so we detect it once per process and
+// say so plainly (session-start warning + /agy doctor) instead of letting
+// users debug parse noise. Pure functions here; the only subprocess is
+// `agy --version`, memoized per binary because discovery already spawns agy
+// once per load and the version will not change mid-process.
+//
+// The ACP server reports its own version at initialize (agentInfo.version,
+// e.g. "agy_acp_server_1.1.1") and /agy doctor already prints it. ACP build
+// numbering is a different lineage from the CLI, so no floor is enforced
+// there: the one known-good build must not be locked out by a CLI number.
+
+import { spawn } from "node:child_process";
+
+/** Floor for the stream-json CLI. Matches the protocol grammar our driver
+ *  and the event mapping rely on; older agy predates verified fields. */
+export const MIN_AGY_VERSION = "1.1.22";
+
+const VERSION_TIMEOUT_MS = 5_000;
+
+export type AgyVersionStatus =
+	| "ok"
+	| "unsupported"
+	| "development"
+	| "invalid"
+	| "unavailable";
+
+export interface AgyVersionCheck {
+	status: AgyVersionStatus;
+	/** Extracted triple when status is ok/unsupported; raw dev token for development. */
+	version?: string;
+	/** Full --version output, for doctor detail. */
+	raw: string;
+}
+
+/** Pull the first strict triple (`1.2.10`) out of arbitrary version output.
+ *  Prefixed forms like "agy_acp_server_1.1.1" and banner text both match;
+ *  anything without a triple is not a version we can gate on. */
+export function parseAgyVersionTriple(text: string): string | undefined {
+	return /\d+\.\d+\.\d+/.exec(text)?.[0];
+}
+
+/** Numeric triple compare; 1.10.0 > 1.9.9, unlike string compare. */
+export function compareVersionTuples(a: string, b: string): number {
+	const pa = a.split(".").map(Number);
+	const pb = b.split(".").map(Number);
+	for (let i = 0; i < 3; i++) {
+		const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+		if (d !== 0) return d;
+	}
+	return 0;
+}
+
+/** Classify raw `--version` output against a floor. Pure: unit-tested for
+ *  every status; checkAgyCliVersion wraps this with the subprocess. */
+export function agyVersionVerdict(
+	raw: string,
+	floor: string = MIN_AGY_VERSION,
+): AgyVersionCheck {
+	// Development builds (agy from source) self-identify as dev, HEAD, or the
+	// spelled-out word; never gate any of them.
+	if (/\b(dev|head|development)\b/i.test(raw))
+		return { status: "development", version: "dev", raw };
+	const triple = parseAgyVersionTriple(raw);
+	if (!triple) return { status: "invalid", raw };
+	if (compareVersionTuples(triple, floor) < 0) return { status: "unsupported", version: triple, raw };
+	return { status: "ok", version: triple, raw };
+}
+
+const checkCache = new Map<string, Promise<AgyVersionCheck>>();
+
+/** Run `binary --version` and classify the result. Memoized per binary for
+ *  the process lifetime (resetAgyVersionCache clears it for tests). Fail
+ *  paths: spawn error (ENOENT etc.) and watchdog timeout are "unavailable",
+ *  a distinct status so doctor can say "could not run" instead of blaming
+ *  the version string. */
+export function checkAgyCliVersion(binary: string = "agy"): Promise<AgyVersionCheck> {
+	const cached = checkCache.get(binary);
+	if (cached) return cached;
+	const run = new Promise<AgyVersionCheck>((resolve) => {
+		let out = "";
+		let done = false;
+		const finish = (check: AgyVersionCheck) => {
+			if (done) return;
+			done = true;
+			clearTimeout(watchdog);
+			resolve(check);
+		};
+		let proc: ReturnType<typeof spawn>;
+		try {
+			proc = spawn(binary, ["--version"], { stdio: ["ignore", "pipe", "ignore"], shell: false });
+		} catch {
+			finish({ status: "unavailable", raw: "" });
+			return;
+		}
+		proc.stdout?.setEncoding("utf8");
+		proc.stdout?.on("data", (d: string) => (out = (out + d).slice(0, 4096)));
+		proc.on("error", () => finish({ status: "unavailable", raw: "" }));
+		// Exit code is ignored on purpose: `agy --version` failures print to
+		// stderr (ignored) and leave junk or empty stdout, which classifies as
+		// invalid — close enough in effect to unavailable for a warn-only gate.
+		proc.on("close", () => finish(agyVersionVerdict(out)));
+		const watchdog = setTimeout(() => {
+			try {
+				proc.kill("SIGKILL");
+			} catch {
+				/* already gone */
+			}
+			finish({ status: "unavailable", raw: out });
+		}, VERSION_TIMEOUT_MS);
+	});
+	checkCache.set(binary, run);
+	return run;
+}
+
+/** Test seam: drop all memoized checks. */
+export function resetAgyVersionCache(): void {
+	checkCache.clear();
+}
+
+/** One-line doctor rendering. */
+export function describeAgyVersionCheck(check: AgyVersionCheck): string {
+	switch (check.status) {
+		case "ok":
+			return check.version ?? "ok";
+		case "unsupported":
+			return `${check.version} TOO OLD`;
+		case "development":
+			return "development build";
+		case "invalid":
+			return "unreadable version output";
+		case "unavailable":
+			return "could not run --version";
+	}
+}

package/src/artifacts-ui.ts

@@ -0,0 +1,86 @@
+// /agy artifacts overlay: SelectList over one conversation's artifacts.
+//
+// UI mirrors the engine picker (tui.md "Pattern 1"): SelectList framed by
+// DynamicBorder inside pi's native overlay. Read-only on purpose: enter
+// opens the selected file with the OS default handler, r rescans (the list
+// is always a fresh scan), esc closes. No delete keys — agy's files are
+// agy's to manage.
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+import type { AgyArtifact } from "./artifacts.js";
+
+export type ArtifactsBrowserAction =
+	| { type: "open"; artifact: AgyArtifact }
+	| { type: "rescan" }
+	| { type: "close" };
+
+function humanBytes(n: number): string {
+	if (n < 1024) return `${n}B`;
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+	return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export function artifactItems(artifacts: AgyArtifact[]): SelectItem[] {
+	return artifacts.map((a, i) => {
+		const when = new Date(a.modifiedMs);
+		const stamp = `${when.getFullYear()}-${String(when.getMonth() + 1).padStart(2, "0")}-${String(when.getDate()).padStart(2, "0")} ${String(when.getHours()).padStart(2, "0")}:${String(when.getMinutes()).padStart(2, "0")}`;
+		return {
+			value: String(i),
+			label: a.name,
+			description: `${a.kind} · ${a.mediaType} · ${humanBytes(a.bytes)} · ${stamp}`,
+		};
+	});
+}
+
+/** Render the overlay. Resolves with what the user asked for: open (with the
+ *  selected artifact), rescan, or close. */
+export async function showArtifactsBrowser(
+	ctx: ExtensionUIContext,
+	artifacts: AgyArtifact[],
+): Promise<ArtifactsBrowserAction> {
+	const items = artifactItems(artifacts);
+	return ctx.custom<ArtifactsBrowserAction>((tui, theme, _keybindings, done) => {
+		const container = new Container();
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+		container.addChild(
+			new Text(theme.fg("accent", theme.bold(`Antigravity artifacts (${artifacts.length})`)), 1, 0),
+		);
+		container.addChild(new Spacer(1));
+
+		const list = new SelectList(items, Math.min(items.length, 12), {
+			selectedPrefix: (t: string) => theme.fg("accent", t),
+			selectedText: (t: string) => theme.fg("accent", t),
+			description: (t: string) => theme.fg("muted", t),
+			scrollInfo: (t: string) => theme.fg("dim", t),
+			noMatch: (t: string) => theme.fg("warning", t),
+		});
+		list.onSelect = (item) => done({ type: "open", artifact: artifacts[Number(item.value)] });
+		list.onCancel = () => done({ type: "close" });
+		container.addChild(list);
+
+		container.addChild(new Spacer(1));
+		container.addChild(
+			new Text(theme.fg("dim", "↑↓ navigate · enter open · r rescan · esc close"), 1, 0),
+		);
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				// r rescan; enter opens (via onSelect), esc cancels (via onCancel).
+				if (data.trim().toLowerCase() === "r") {
+					done({ type: "rescan" });
+					return;
+				}
+				list.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	}, {
+		overlay: true,
+		overlayOptions: { anchor: "center" as const, width: 84, maxHeight: "85%" as const, margin: 1 },
+	});
+}

package/src/artifacts.ts

@@ -0,0 +1,144 @@
+// Read-only artifact scan over one agy conversation's brain dir.
+//
+// agy drops files in three places under brain/<conversationId>/: the
+// conversation root itself, .tempmediaStorage/ (media agy generated), and
+// .user_uploaded/ (files the user handed it). Nothing else surfaces them,
+// so this module lists them for pi (live-probed 2026-09-24: both trees
+// exist per engine; media dirs are created on demand and may be absent).
+//
+// Read-only by design: list and open, never delete. Each entry is
+// realpath'd and containment-checked canonical-to-canonical, which defeats
+// symlinks pointing outside the conversation root and stays correct when
+// the conversation dir itself is reached through a symlinked ancestor
+// (macOS /var -> /private/var, symlinked homes). A file could still be
+// swapped for a symlink between listing and a later `open` — the OS opener
+// would follow it; that is outside this module's guarantee and acceptable
+// for a single-user, own-home tool.
+
+import { readdir, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+export type AgyArtifactKind = "conversation" | "generated" | "uploaded";
+export type AgyArtifactMediaType =
+	| "image"
+	| "audio"
+	| "video"
+	| "pdf"
+	| "markdown"
+	| "text"
+	| "other";
+
+export interface AgyArtifact {
+	name: string;
+	absolutePath: string;
+	kind: AgyArtifactKind;
+	mediaType: AgyArtifactMediaType;
+	bytes: number;
+	modifiedMs: number;
+}
+
+const EXT_TO_MEDIA: Record<string, AgyArtifactMediaType> = {
+	png: "image",
+	jpg: "image",
+	jpeg: "image",
+	gif: "image",
+	webp: "image",
+	svg: "image",
+	bmp: "image",
+	mp3: "audio",
+	wav: "audio",
+	ogg: "audio",
+	m4a: "audio",
+	flac: "audio",
+	mp4: "video",
+	mov: "video",
+	webm: "video",
+	mkv: "video",
+	pdf: "pdf",
+	md: "markdown",
+	markdown: "markdown",
+	txt: "text",
+	csv: "text",
+	json: "text",
+};
+
+function mediaTypeFor(name: string): AgyArtifactMediaType {
+	return EXT_TO_MEDIA[path.extname(name).slice(1).toLowerCase()] ?? "other";
+}
+
+/** Files that are agy bookkeeping, not user-facing artifacts. */
+function isSkippedName(name: string): boolean {
+	return name.startsWith(".") || name.endsWith(".metadata.json");
+}
+
+const SCAN_ROOTS: Array<{ sub: string | null; kind: AgyArtifactKind }> = [
+	{ sub: null, kind: "conversation" },
+	{ sub: ".tempmediaStorage", kind: "generated" },
+	{ sub: ".user_uploaded", kind: "uploaded" },
+];
+
+/** List artifacts under one conversation dir. Missing subdirs are normal
+ *  (created on demand) and skip silently; a missing conversation dir
+ *  returns []. Newest first. */
+export async function listAgyArtifacts(conversationDir: string): Promise<AgyArtifact[]> {
+	// Canonicalize ONCE and derive everything from the canonical root: a
+	// raw-vs-canonical containment check silently rejects every entry when
+	// any ancestor is a symlink (the relative prefix comparison crosses
+	// resolved/unresolved segments and yields a bogus "..").
+	let root: string;
+	try {
+		root = await realpath(conversationDir);
+	} catch {
+		return [];
+	}
+	const byPath = new Map<string, AgyArtifact>();
+	for (const { sub, kind } of SCAN_ROOTS) {
+		const dir = sub === null ? root : path.join(root, sub);
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (!entry.isFile()) continue; // Dirent type: symlinks excluded here
+			if (isSkippedName(entry.name)) continue;
+			// Re-resolve per entry and re-check containment on the canonical
+			// path: catches anything swapped in between readdir and use.
+			let canonical: string;
+			let stats;
+			try {
+				canonical = await realpath(path.join(dir, entry.name));
+				if (!containedIn(root, canonical)) continue;
+				stats = await stat(canonical);
+			} catch {
+				continue;
+			}
+			if (!stats.isFile()) continue;
+			const key = canonical;
+			if (byPath.has(key)) continue;
+			byPath.set(key, {
+				name: entry.name,
+				absolutePath: canonical,
+				kind,
+				mediaType: mediaTypeFor(entry.name),
+				bytes: stats.size,
+				modifiedMs: stats.mtimeMs,
+			});
+		}
+	}
+	return [...byPath.values()].sort((a, b) => b.modifiedMs - a.modifiedMs);
+}
+
+function containedIn(root: string, candidate: string): boolean {
+	const rel = path.relative(root, candidate);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/** OS open command for the user's default handler. Undefined on unknown
+ *  platforms (caller renders a message instead of spawning blind). */
+export function artifactOpenCommand(): { cmd: string } | undefined {
+	if (process.platform === "darwin") return { cmd: "open" };
+	if (process.platform === "linux") return { cmd: "xdg-open" };
+	return undefined;
+}

package/src/ask-tool.ts

@@ -78,7 +78,7 @@ TWO MODES (you choose):
 - **Continued conversation**: pass the conversationId returned in the PREVIOUS call's details (details.conversationId). agy resumes that conversation with full context intact.
 
 EXECUTION MODES (param: mode):
-- **plan**: agy reviews and plans without writing. Use for cross-review and read-only tasks.
+- **plan**: agy reviews and plans without writing. Use for cross-review and read-only tasks. Enforced: plan runs never receive the skip-permissions flag, so a write or command attempt ends the run quickly with a "confirm plan" message instead of executing.
 - **accept-edits** (default): agy applies edits directly inside the workspace.
 
 COMPACT OUTPUT (param: digest): when true, the prompt is prefixed to request compact digests instead of full file contents. Defaults on for plan, off for accept-edits.
@@ -536,7 +536,16 @@ export async function registerAskAntigravityTool(
 			// Honor the shared permissions setting (same knob as the provider). Non-
 			// interactive -p can't answer a permission prompt, so when this is off
 			// any run_command will hang - but the setting must mean what it says.
-			if (config.skipPermissions !== false) args.push("--dangerously-skip-permissions");
+			// Plan mode never gets the flag even when the knob is on: the flag
+			// auto-approves ALL permission requests including plan mode's own
+			// approval gate, which would silently turn "review-only" into full
+			// write access inside --add-dir (probed 2026-09-25: with the flag a
+			// plan run wrote files; without it, file and command attempts end
+			// exit 0 in ~20-30s with a "confirm plan" message - fail-visible,
+			// never a hang). Omitting it is what makes "plan = review-only" true.
+			if (mode !== "plan" && config.skipPermissions !== false) {
+				args.push("--dangerously-skip-permissions");
+			}
 			if (isContinuation) args.push("--conversation", rawConvId as string);
 			args.push("--print-timeout", `${timeoutMin}m`);
 			if (contextFile) args.push("--add-dir", askContextDir());

package/src/config.ts

@@ -13,6 +13,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { normalizeAgyAgentName } from "./agents.js";
 
 const CONFIG_PATH = path.join(
 	os.homedir(),
@@ -112,6 +113,9 @@ export interface AgyConfig {
 	 *  on the installed pi. The notice never repeats; /agy patch-cleanup is
 	 *  always available. */
 	patchCleanupNotified?: boolean;
+	/** Custom agy agent for stream-json turns (`--agent`, /agy agent).
+	 *  Absent = agy's default agent. ACP turns ignore it (no protocol slot). */
+	agent?: string;
 	/** Which pi tools the MCP bridge exposes to agy: "none" (bridge off),
 	 *  "all" (every registered non-builtin tool incl. other Ask* delegations;
 	 *  default - users expect the bridge working out of the box, and the
@@ -316,6 +320,11 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		usageEstimate,
 	};
 
+	// Custom agent for stream-json turns (--agent). Env wins over the file
+	// (same pattern as mode). Normalized (trim/cap/control-strip); an empty
+	// result means agy's default agent.
+	const agent = normalizeAgyAgentName(process.env.AGY_AGENT ?? file.agent);
+
 	return {
 		engine,
 		acp,
@@ -330,6 +339,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		systemPrompt,
 		turnTimeoutMin,
 		inactivityTimeoutMin,
+		agent,
 		approvals: { gateMode, mode: gateAskMode },
 		patchCleanupNotified: file.patchCleanupNotified === true,
 	};

package/src/driver-types.ts

@@ -18,6 +18,10 @@ export interface DriverProfile {
 	effort?: string;
 	mode: string;
 	skipPermissions: boolean;
+	/** Custom agy agent (stream-json `--agent`). ACP has no agent slot in the
+	 *  protocol (RC01) and ignores it; the /agy agent command refuses to set
+	 *  one while the ACP engine is active. */
+	agent?: string;
 }
 
 export interface DriverTurnRequest extends DriverProfile {
@@ -55,13 +59,15 @@ export type DriverActivity =
 	/** Stream-json emits a token count only; ACP carries the actual thought text in
 	 *  `delta`. The provider renders whichever is present. */
 	| { type: "thought"; tokens?: number; delta?: string }
-	| { type: "tool_start"; stepId?: number; name: string; args: Record<string, unknown>; mcpServer?: string }
+	| { type: "tool_start"; stepId?: number; name: string; args: Record<string, unknown>; mcpServer?: string; /** ACP only: the protocol toolCallId (stream-json carries numeric stepId instead). */ toolCallId?: string }
 	| {
 			type: "tool_done";
 			stepId?: number;
 			name: string;
 			args: Record<string, unknown>;
 			mcpServer?: string;
+			/** ACP only: the protocol toolCallId; pairs done/error with their start. */
+			toolCallId?: string;
 			output?: string;
 			durationSeconds?: number;
 			/** ACP only: the server's native edit diff from `tool_call`
@@ -69,7 +75,7 @@ export type DriverActivity =
 			 *  sets it; the provider renders it without any git subprocess. */
 			diff?: { path: string; oldText?: string; newText: string };
 	  }
-	| { type: "tool_error"; stepId?: number; name: string; message: string; mcpServer?: string }
+	| { type: "tool_error"; stepId?: number; name: string; message: string; mcpServer?: string; toolCallId?: string }
 	| { type: "usage"; usage: AgyUsage }
 	/** Synthetic: injected by the provider when the MCP bridge receives a call
 	 *  (G9). Parks the turn: output is expected to stall while pi executes the

package/src/driver.ts

@@ -7,7 +7,7 @@
 //
 // Recycle semantics: the child is killed and respawned when the next turn's
 // process profile (model / effort / mode / cwd / conversation) drifts from the
-// running one, mirroring tianzuo/pi-antigravity's driver. Stats and a bounded
+// running one. Stats and a bounded
 // lifecycle log feed /agy doctor.
 //
 // The driver never talks to the MCP bridge directly: the provider owns the
@@ -20,6 +20,7 @@ import { parseAgyLine } from "./stream-events.js";
 import { isKnownNoiseLine, MAX_FRAME_BYTES, stripGluedNoise } from "./frame-guard.js";
 import { bridgeMcpConfigDir, bridgeMcpConfigExists } from "./mcp-server.js";
 import { gateHooksStaged } from "./approval-hook.js";
+import { parkedTurnAnswer } from "./parked-turn.js";
 import { redactText } from "./redact.js";
 import type {
 	AgyUsage,
@@ -62,6 +63,9 @@ interface ActiveTurn {
 	response: string;
 	usage?: AgyUsage;
 	conversationId?: string;
+	/** Wall clock at turn creation; the parked-turn probe filters
+	 *  transcript steps to those written after this. */
+	startedAt: number;
 	sawResult: boolean;
 	/** Text-dedupe guard state (delta vs cumulative response_text). */
 	cumulativeText: boolean | undefined;
@@ -71,6 +75,15 @@ interface ActiveTurn {
 	parks: number;
 }
 
+/** The skip-permissions flag actually passed to agy. Plan mode never
+ *  carries it: the flag auto-approves every permission request including
+ *  plan mode's own approval gate, silently turning review-only into full
+ *  write access. #start (argv + profile) and #recycleCause (comparison)
+ *  must both go through this, or plan turns recycle on every turn. */
+function effectiveSkipPermissions(mode: DriverTurnRequest["mode"], skipPermissions: boolean): boolean {
+	return mode !== "plan" && skipPermissions;
+}
+
 function emit(turn: ActiveTurn, activity: DriverActivity): void {
 	if (turn.closed) return;
 	if (turn.wake.length > 0) turn.wake.shift()!();
@@ -171,10 +184,7 @@ export class StreamDriver implements TurnDriver {
 			// 0 disables the stall guard (config inactivityTimeoutMin: 0).
 			if (idleMin > 0) {
 				turn.idleTimer = setTimeout(() => {
-					if (turn.closed) return;
-					this.#log(`stall:${turn.id}`);
-					this.#killChild();
-					this.#failTurn(turn, `agy stalled for ${idleMin}m with no output`);
+					void this.#turnDeadlineGuard(turn, "stall", `agy stalled for ${idleMin}m with no output`);
 				}, idleMin * 60_000);
 			}
 		}
@@ -279,6 +289,7 @@ export class StreamDriver implements TurnDriver {
 			sawResult: false,
 			cumulativeText: undefined,
 			parks: 0,
+			startedAt: Date.now(),
 		};
 		if (request.signal) {
 			turn.onAbort = () => {
@@ -306,19 +317,13 @@ export class StreamDriver implements TurnDriver {
 		const totalMin = turn.request.timeoutMin ?? 10;
 		if (totalMin > 0) {
 			turn.overallTimer = setTimeout(() => {
-				if (turn.closed) return;
-				this.#log(`timeout:${turn.id}`);
-				this.#killChild();
-				this.#failTurn(turn, `agy exceeded the ${totalMin}m turn timeout`);
+				void this.#turnDeadlineGuard(turn, "timeout", `agy exceeded the ${totalMin}m turn timeout`);
 			}, totalMin * 60_000);
 		}
 		const idleMin = turn.request.inactivityMin ?? 5;
 		if (idleMin > 0) {
 			turn.idleTimer = setTimeout(() => {
-				if (turn.closed) return;
-				this.#log(`stall:${turn.id}`);
-				this.#killChild();
-				this.#failTurn(turn, `agy stalled for ${idleMin}m with no output`);
+				void this.#turnDeadlineGuard(turn, "stall", `agy stalled for ${idleMin}m with no output`);
 			}, idleMin * 60_000);
 		}
 	}
@@ -327,12 +332,21 @@ export class StreamDriver implements TurnDriver {
 		this.#state = "starting";
 		this.#generation += 1;
 		const generation = this.#generation;
+		// Plan mode never carries the skip flag: the flag auto-approves ALL
+		// permission requests including plan mode's own approval gate, which
+		// would silently turn "review-only" into full write access (probed
+		// 2026-09-25: with the flag a plan session wrote files; without it,
+		// file and command attempts end exit 0 in ~20-30s with a "confirm
+		// plan" message). The profile stores the EFFECTIVE value so the
+		// recycle comparison stays consistent with the argv.
+		const skipPermissions = effectiveSkipPermissions(request.mode, request.skipPermissions);
 		this.#profile = {
 			cwd: request.cwd,
 			model: request.model,
 			effort: request.effort,
 			mode: request.mode,
-			skipPermissions: request.skipPermissions,
+			skipPermissions,
+			agent: request.agent,
 		};
 		this.#boundConversation = request.conversationId ?? undefined;
 		this.#stderrTail = "";
@@ -346,7 +360,8 @@ export class StreamDriver implements TurnDriver {
 		args.push("--model", request.model);
 		if (request.effort) args.push("--effort", request.effort);
 		args.push("--mode", request.mode);
-		if (request.skipPermissions) args.push("--dangerously-skip-permissions");
+		if (request.agent) args.push("--agent", request.agent);
+		if (skipPermissions) args.push("--dangerously-skip-permissions");
 		if (request.conversationId) args.push("--conversation", request.conversationId);
 		args.push(
 			"--input-format",
@@ -607,6 +622,40 @@ export class StreamDriver implements TurnDriver {
 		}
 	}
 
+	/** Stall / total-timeout guard shared by both timer sites. Kills the
+	 *  child FIRST (bumping the generation so a racing exit handler cannot
+	 *  settle the turn ERROR mid-probe), then probes the conversation's
+	 *  brain transcript for a clean final-response step written during the
+	 *  turn (parked turn: agy finished its answer but never streamed it).
+	 *  One found, the turn settles OK with the withheld answer instead of
+	 *  discarding finished work; either way the next turn respawns into a
+	 *  known state. */
+	async #turnDeadlineGuard(turn: ActiveTurn, label: string, message: string): Promise<void> {
+		if (turn.closed) return;
+		this.#log(`${label}:${turn.id}`);
+		this.#killChild();
+		let parked: string | undefined;
+		try {
+			parked = turn.conversationId
+				? await parkedTurnAnswer(turn.conversationId, turn.startedAt)
+				: undefined;
+		} catch {
+			parked = undefined; // the guard must never throw
+		}
+		if (parked !== undefined) {
+			this.#settle(turn, {
+				conversationId: turn.conversationId,
+				status: "OK",
+				response: parked,
+				usage: turn.usage,
+				finished: true,
+				aborted: false,
+			});
+			return;
+		}
+		this.#failTurn(turn, message);
+	}
+
 	#failTurn(turn: ActiveTurn, message: string): void {
 		this.#settle(turn, {
 			conversationId: turn.conversationId,
@@ -626,7 +675,10 @@ export class StreamDriver implements TurnDriver {
 		if (cur.model !== next.model) return "model";
 		if (cur.effort !== next.effort) return "effort";
 		if (cur.mode !== next.mode) return "mode";
-		if (cur.skipPermissions !== next.skipPermissions) return "permissions";
+		if (cur.skipPermissions !== effectiveSkipPermissions(next.mode, next.skipPermissions)) {
+			return "permissions";
+		}
+		if (cur.agent !== next.agent) return "agent";
 		if (!next.conversationId) return this.#boundConversation ? "conversation-reset" : undefined;
 		return next.conversationId === this.#boundConversation ? undefined : "conversation";
 	}