@estebanforge/pi-antigravity-bridge 1.4.9 → 1.4.10

package/src/approval-gate.ts

@@ -0,0 +1,208 @@
+// Approval-gate shadow tools (docs/TODO.md section 2.5, design v2).
+//
+// When the approval gate is active, the bridge re-registers pi's mutating
+// builtins (bash, write, edit) as SHADOW tools: same name, same schema plus
+// internal __agy* marker fields. Two behaviors, keyed on the marker:
+//
+//   - marker absent: delegate to the captured real builtin. Normal pi
+//     behavior (including the G9 path, where pi tools execute for real) is
+//     untouched.
+//   - marker present: the call is an approval round-trip for an agy NATIVE
+//     tool. NEVER execute locally. Ask the policy for a decision; agy runs
+//     the tool in its own loop either way.
+//
+// Decision mapping (consumed by the provider's /approval park):
+//   resolve (success result)      -> {"decision":"allow"}
+//   throw                         -> {"decision":"deny","reason": message}
+// pi's tool executor converts thrown errors into error tool results with
+// the message as text, matching how builtins report failures (write.js,
+// edit-diff.js). A tool_call handler that blocks the shadow call upstream
+// (any third-party permission extension) produces the same error result
+// without execute() running, so both paths land on the same deny mapping.
+//
+// Run: npm test
+
+import type {
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ExtensionContext,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+/** Marker flag: this shadow-tool call is an approval round-trip, not a real
+ *  invocation. The bridge's provider sets it when composing the toolUse. */
+export const GATE_MARKER = "__agyGate";
+
+/** Internal context fields the provider may attach next to the marker.
+ *  Stripped before delegating to the real builtin. */
+export const MARKER_FIELDS = [GATE_MARKER, "__agyTicket", "__agyTool"] as const;
+
+export type AnyToolDefinition = ToolDefinition<any, any, any>;
+
+export interface GateDecision {
+	allow: boolean;
+	reason?: string;
+}
+
+/** Fallback policy: consulted only when NO extension blocked the shadow
+ *  tool_call. Implementations map approvals.mode: ask -> ctx.ui.confirm
+ *  (guarded by ctx.hasUI), allow -> {allow:true}, deny -> {allow:false}. */
+export type GatePolicy = (call: {
+	tool: string;
+	params: Record<string, unknown>;
+	ctx: unknown;
+}) => Promise<GateDecision> | GateDecision;
+
+/** Marker schemas injected into the shadow parameters. Optional, so the
+ *  model's own calls stay valid; audited permission extensions match only
+ *  their known fields (command/path) and ignore these. */
+const MARKER_SCHEMAS: Record<string, unknown> = {
+	[GATE_MARKER]: {
+		type: "boolean",
+		description:
+			"Internal bridge approval marker. Never set this yourself; calls without local execution intent must not set it.",
+	},
+	__agyTicket: { type: "string" },
+	__agyTool: { type: "string", description: "Native agy tool this approval round-trip is for." },
+};
+
+/** Clone a tool's parameter schema with the marker fields added as optional
+ *  properties. Field-exact for everything the permission extensions match on
+ *  (command, path, edits, ...). Does not mutate the base schema. */
+export function withGateMarkerSchema(base: AnyToolDefinition["parameters"]): AnyToolDefinition["parameters"] {
+	const src = base as { properties?: Record<string, unknown> };
+	return { ...base, properties: { ...src.properties, ...MARKER_SCHEMAS } } as AnyToolDefinition["parameters"];
+}
+
+/** Copy of params without the internal marker fields, for delegation. */
+export function stripMarkerFields(params: Record<string, unknown>): Record<string, unknown> {
+	const out = { ...params };
+	for (const field of MARKER_FIELDS) delete out[field];
+	return out;
+}
+
+export interface ShadowMapping {
+	shadow: "bash" | "write" | "edit";
+	input: Record<string, unknown>;
+}
+
+/** Map an agy native tool call (hook stdin payload) onto the shadow surface.
+ *  Field names follow the TODO 2.5 table: create_file is live-captured (F1);
+ *  the edit-class arg names are docs-attested and degrade gracefully - a
+ *  wrong guess only weakens the confirm-dialog text, never the decision
+ *  (the tool runs in agy's loop either way). Unknown names return null:
+ *  read-only tools are not gated. */
+export function mapNativeToShadow(name: string, args: Record<string, unknown>): ShadowMapping | null {
+	const a = args ?? {};
+	const str = (v: unknown): string => (typeof v === "string" ? v : v === undefined || v === null ? "" : String(v));
+	switch (name) {
+		case "run_command": {
+			const input: Record<string, unknown> = { command: str(a.CommandLine) };
+			if (a.Cwd !== undefined && a.Cwd !== null && a.Cwd !== "") input.cwd = str(a.Cwd);
+			return { shadow: "bash", input };
+		}
+		case "write_to_file":
+		case "create_file":
+			return { shadow: "write", input: { path: str(a.TargetFile), content: str(a.CodeContent) } };
+		case "replace_file_content":
+		case "edit_file":
+			return {
+				shadow: "edit",
+				input: {
+					path: str(a.TargetFile),
+					edits: [{ oldText: str(a.SearchText), newText: str(a.ReplacementContent) }],
+				},
+			};
+		case "multi_replace_file_content": {
+			const chunks = Array.isArray(a.ReplacementChunks) ? a.ReplacementChunks : [];
+			return {
+				shadow: "edit",
+				input: {
+					path: str(a.TargetFile),
+					edits: chunks.map((c) => {
+						const chunk = (c ?? {}) as Record<string, unknown>;
+						return { oldText: str(chunk.SearchText), newText: str(chunk.ReplacementContent) };
+					}),
+				},
+			};
+		}
+		default:
+			return null;
+	}
+}
+
+/** Options for the shadow factory. */
+export interface ShadowOptions {
+	/** Registry lookup for the park's ticket. When set, a marker call whose
+	 *  __agyTicket is missing or unrecognized throws (deny) BEFORE the policy
+	 *  runs: a model that sets __agyGate:true itself can then never produce a
+	 *  fake-approved result, even under approvals.mode "allow". */
+	verifyTicket?: (ticket: string) => boolean;
+}
+
+/** Build the shadow definition for one builtin. `base` MUST be a definition
+ *  of the real builtin - the extension passes factory twins created with
+ *  pi's public createBashToolDefinition/createWriteToolDefinition/
+ *  createEditToolDefinition (pi.getAllTools() returns ToolInfo, which strips
+ *  execute, so the live definition cannot be captured). */
+export function createShadowTool(base: AnyToolDefinition, policy: GatePolicy, opts: ShadowOptions = {}): AnyToolDefinition {
+	const execute = async (
+		toolCallId: string,
+		params: any,
+		signal: AbortSignal | undefined,
+		onUpdate: AgentToolUpdateCallback<any> | undefined,
+		ctx: ExtensionContext,
+	): Promise<AgentToolResult<unknown>> => {
+		const p = (params ?? {}) as Record<string, unknown>;
+		if (p[GATE_MARKER] !== true) {
+			return base.execute(toolCallId, stripMarkerFields(p), signal, onUpdate, ctx);
+		}
+		const native = typeof p.__agyTool === "string" && p.__agyTool.length > 0 ? p.__agyTool : base.name;
+		// Ticket binding (peer review 2026-09-07): only calls the provider parked
+		// carry a live ticket. Anything else with the marker set was forged by
+		// the model (or the park is gone); fail closed without consulting the
+		// policy, so approvals.mode "allow" can never bless it either.
+		const ticket = typeof p.__agyTicket === "string" ? p.__agyTicket : "";
+		if (!ticket || !opts.verifyTicket?.(ticket)) {
+			throw new Error(
+				`approval gate: unrecognized or stale approval ticket; refusing to decide (${native}).`,
+			);
+		}
+		if (signal?.aborted) {
+			throw new Error(`approval gate aborted before a decision was reached (${native}).`);
+		}
+		let decision: GateDecision;
+		// Race the policy against the abort signal: a cancelled turn must
+		// unblock execute() instead of hanging on a human decision.
+		const aborted = new Error(`approval gate aborted before a decision was reached (${native}).`);
+		const abortp = new Promise<never>((_, reject) => {
+			signal?.addEventListener("abort", () => reject(aborted), { once: true });
+		});
+		abortp.catch(() => {}); // late rejection must not become unhandled
+		try {
+			decision = await Promise.race([Promise.resolve(policy({ tool: native, params: p, ctx })), abortp]);
+		} catch (err) {
+			if (signal?.aborted) throw aborted;
+			// Fail closed: a broken policy must never look like an approval.
+			throw new Error(`approval gate policy failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (signal?.aborted) {
+			// Sync-abort inside the policy settles the policy promise BEFORE the
+			// race starts, so the rejection loses the ordering tie. Re-check.
+			throw aborted;
+		}
+		if (!decision.allow) {
+			throw new Error(decision.reason || `blocked by approval gate (${native}).`);
+		}
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Approved by approval gate: ${native}. No local execution happened; the tool runs in the Antigravity agent loop.`,
+				},
+			],
+			details: { gate: "allow", native },
+		};
+	};
+	return { ...base, parameters: withGateMarkerSchema(base.parameters), execute } as AnyToolDefinition;
+}

package/src/approval-hook.ts

@@ -0,0 +1,252 @@
+// Staging for the approval-gate hooks.json (docs/TODO.md 2.5).
+//
+// The ACP server and the agy CLI fire workspace `.agents/hooks.json`
+// PreToolUse hooks (V2: deny honored, reason reaches the model; V3: hook
+// TIMEOUT = soft-pass, agy proceeds ungated). Therefore:
+//   - the staged handler timeout must exceed the whole park budget with
+//     margin (never rely on timeout as a deny), and
+//   - the staged command delegates to the bundled poll script, which
+//     early-acks and polls the bridge for the terminal decision.
+//
+// Merge rules: never clobber a foreign hooks.json. Parse failures abort
+// staging; first-time modification of an existing file writes a
+// timestamped backup next to it (the 2026-09-05 incident rule: every
+// destructive path gets a guard).
+//
+// Run: npm test
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const HOOK_GROUP = "pi-bridge-gate";
+
+/** Group-key namespace. Each pi session stages its OWN group keyed per-pid
+ *  (`pi-bridge-gate-<pid>`): hooks.json lives in the SHARED workspace, and
+ *  two concurrent sessions must never remove or overwrite each other's gate
+ *  (audit 2026-09-07: a single shared key let a gate-off session silently
+ *  strip a gate-on session's PreToolUse matchers). */
+export const GATE_GROUP_PREFIX = "pi-bridge-gate";
+
+/** This session's group key. */
+export function gateGroupKey(pid: number = process.pid): string {
+	return `${GATE_GROUP_PREFIX}-${pid}`;
+}
+
+/** True if the process is running (EPERM counts: alive but not ours). */
+function pidAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Which session a gate group belongs to, parsed from the script path its
+ *  command embeds (`.../approval-hook-<pid>.js`). The pid is the ownership
+ *  proof: the script is per-pid (0600, written by that session). Returns
+ *  null for groups we cannot attribute (foreign/future formats - never
+ *  touched). */
+function gateGroupPid(group: unknown): number | null {
+	const m = /approval-hook-(\d+)\.js/.exec(JSON.stringify(group));
+	return m ? Number(m[1]) : null;
+}
+
+/** agy native tools worth gating: everything that mutates the machine. */
+export const GATED_AGY_TOOLS =
+	"create_file|write_to_file|replace_file_content|multi_replace_file_content|edit_file|run_command";
+
+/** The same list as a set, for the bridge's POST /approval validation: a
+ *  payload for anything else is answered with a direct deny (defense in
+ *  depth - the hooks matcher should never let one through). */
+export const GATED_AGY_TOOL_SET: ReadonlySet<string> = new Set(GATED_AGY_TOOLS.split("|"));
+
+export interface StageOptions {
+	/** Bridge HTTP port (the approval endpoints live on the bridge server). */
+	port: number;
+	/** Bridge shared secret (x-bridge-token). */
+	token: string;
+	/** Path to the bundled poll script (written by the caller). */
+	scriptPath: string;
+	/** Full park budget in ms; the staged hook timeout exceeds it. */
+	parkBudgetMs: number;
+}
+
+/** Source of the staged poll script. Written to disk by the caller (data
+ *  dir), referenced by absolute path from the staged hooks.json. Early-acks
+ *  via POST /approval, then polls GET /approval/<ticket> until a terminal
+ *  decision or the deadline. Terminal: prints the JSON decision on stdout.
+ *  Deadline hit: prints {"decision":"deny", ...} (fail closed) - agy may
+ *  still soft-pass a timed-out hook, but a printed deny is honored (V2). */
+export function hookScriptSource(opts: { port: number; token: string; deadlineMs: number }): string {
+	return `#!/usr/bin/env node
+// Bridge approval hook (generated; do not edit). Polls the pi-antigravity-bridge.
+const PORT = ${opts.port};
+const TOKEN = ${JSON.stringify(opts.token)};
+const DEADLINE = Date.now() + ${opts.deadlineMs};
+let body = "";
+process.stdin.setEncoding("utf8");
+for await (const chunk of process.stdin) body += chunk;
+let ticket = "";
+try {
+	const res = await fetch(\`http://127.0.0.1:\${PORT}/approval\`, {
+		method: "POST",
+		headers: { "content-type": "application/json", "x-bridge-token": TOKEN },
+		body,
+	});
+	const json = await res.json();
+	// Ungated payloads get a terminal decision right on the POST (no park).
+	if (json && typeof json === "object" && "decision" in json) {
+		console.log(JSON.stringify(json.decision));
+		process.exit(0);
+	}
+	ticket = json.ticket ?? "";
+} catch {}
+if (!ticket) {
+	console.log(JSON.stringify({ decision: "deny", reason: "approval gate unreachable (bridge down?)" }));
+	process.exit(0);
+}
+while (Date.now() < DEADLINE) {
+	await new Promise((r) => setTimeout(r, 500));
+	try {
+		const res = await fetch(\`http://127.0.0.1:\${PORT}/approval/\${encodeURIComponent(ticket)}\`, {
+			headers: { "x-bridge-token": TOKEN },
+		});
+		const json = await res.json();
+		if (json.status !== "pending") {
+			console.log(JSON.stringify(json.decision ?? { decision: "deny", reason: "gate returned no decision" }));
+			process.exit(0);
+		}
+	} catch {}
+}
+console.log(JSON.stringify({ decision: "deny", reason: "approval gate deadline exceeded" }));
+`;
+}
+
+/** Hook timeout (seconds) staged for a given park budget: the budget plus a
+ *  60s margin, minimum 60s. V3: a timed-out hook soft-passes, so this must
+ *  never be smaller than the human can plausibly need. */
+export function stagedTimeoutSeconds(parkBudgetMs: number): number {
+	return Math.max(60, Math.ceil(parkBudgetMs / 1000) + 60);
+}
+
+/** Build our hooks.json group for one workspace staging. */
+export function buildGateGroup(opts: StageOptions): Record<string, unknown> {
+	const command = `node ${JSON.stringify(opts.scriptPath)}`;
+	return {
+		enabled: true,
+		PreToolUse: [
+			{
+				matcher: GATED_AGY_TOOLS,
+				hooks: [
+					{
+						type: "command",
+						command,
+						timeout: stagedTimeoutSeconds(opts.parkBudgetMs),
+					},
+				],
+			},
+		],
+	};
+}
+
+export interface StageResult {
+	wrote: boolean;
+	/** Backup file written before first modification of a foreign file. */
+	backup?: string;
+	/** Why nothing was written (parse failure, already current, ...). */
+	reason?: string;
+}
+
+/** Stage the gate group into <workspaceDir>/.agents/hooks.json under THIS
+ *  session's per-pid key. Merge-safe:
+ *  - foreign groups are preserved;
+ *  - gate groups of DEAD sessions are swept (their bridge is gone; the hook
+ *    would fail closed forever), groups of live sessions never touched;
+ *  - a foreign file is backed up before its first modification;
+ *  - unparseable files are never touched. */
+export function stageGateHooks(workspaceDir: string, opts: StageOptions): StageResult {
+	const dir = path.join(workspaceDir, ".agents");
+	const file = path.join(dir, "hooks.json");
+	const group = buildGateGroup(opts);
+	const ownKey = gateGroupKey();
+	let current: Record<string, unknown> = {};
+	const existed = fs.existsSync(file);
+	if (existed) {
+		try {
+			if (fs.lstatSync(file).isSymbolicLink()) {
+				return { wrote: false, reason: "hooks.json is a symlink; refusing to follow it" };
+			}
+		} catch {
+			return { wrote: false, reason: "hooks.json vanished while staging" };
+		}
+		try {
+			const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+				return { wrote: false, reason: "hooks.json is not an object; refusing to touch it" };
+			}
+			current = parsed as Record<string, unknown>;
+		} catch {
+			return { wrote: false, reason: "hooks.json is not valid JSON; refusing to touch it" };
+		}
+		// Sweep gate groups whose owning session is gone. Never touch groups of
+		// live sessions (concurrent pi sessions share this workspace) or groups
+		// we cannot attribute.
+		let swept = 0;
+		for (const key of Object.keys(current)) {
+			if (key === ownKey) continue;
+			const isGateGroup = key === GATE_GROUP_PREFIX || key.startsWith(`${GATE_GROUP_PREFIX}-`);
+			if (!isGateGroup) continue;
+			const pid = gateGroupPid(current[key]);
+			if (pid === null || pidAlive(pid)) continue;
+			delete current[key];
+			swept += 1;
+		}
+		if (swept > 0 && JSON.stringify(current[ownKey]) === JSON.stringify(group)) {
+			// Own group already current; the pass only swept dead peers.
+			fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n");
+			return { wrote: true, reason: `swept ${swept} dead gate group(s)` };
+		}
+		if (JSON.stringify(current[ownKey]) === JSON.stringify(group)) {
+			return { wrote: false, reason: "already staged" };
+		}
+	}
+	const backup =
+		existed && current[ownKey] === undefined
+			? `${file}.backup-${new Date().toISOString().replace(/[:.]/g, "-")}`
+			: undefined;
+	if (backup) fs.copyFileSync(file, backup);
+	current[ownKey] = group;
+	fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(file, JSON.stringify(current, null, 2) + "\n");
+	return { wrote: true, backup };
+}
+
+/** Remove ONLY this session's gate group (or the given pid's). Other
+ *  sessions' groups - including live ones in a shared workspace - are never
+ *  touched: a gate-off session must not strip a gate-on session's matchers
+ *  (audit 2026-09-07). Foreign content stays; an object file is left in
+ *  place (harmless). */
+export function removeGateHooks(workspaceDir: string, pid: number = process.pid): StageResult {
+	const file = path.join(workspaceDir, ".agents", "hooks.json");
+	if (!fs.existsSync(file)) return { wrote: false, reason: "no hooks.json" };
+	try {
+		if (fs.lstatSync(file).isSymbolicLink()) {
+			return { wrote: false, reason: "hooks.json is a symlink; refusing to follow it" };
+		}
+	} catch {
+		return { wrote: false, reason: "hooks.json vanished while removing" };
+	}
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+		if (!parsed || typeof parsed !== "object") return { wrote: false, reason: "not an object; refusing" };
+		const ownKey = gateGroupKey(pid);
+		if (parsed[ownKey] === undefined) return { wrote: false, reason: "not staged" };
+		delete parsed[ownKey];
+		fs.writeFileSync(file, JSON.stringify(parsed, null, 2) + "\n");
+		return { wrote: true };
+	} catch {
+		return { wrote: false, reason: "not valid JSON; refusing" };
+	}
+}

package/src/config.ts

@@ -44,6 +44,29 @@ export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
 export type BridgeTools = "none" | "mcp" | "all";
 
+/** How the approval gate activates (docs/TODO.md section 2.5).
+ *
+ *  "auto" (default): OFF until a third-party pi permission extension is
+ *  detected (src/approval-detect.ts). When one is found, the gate runs in
+ *  "shadow" mode so that extension gates agy's native tool calls with zero
+ *  configuration on its side.
+ *
+ *  "shadow" / "dedicated": force the gate on in that shape. "off": never
+ *  gate, even when a permission extension is installed. NOTE: "dedicated"
+ *  currently stages the same shadow tools as "shadow" (warn-logged remap);
+ *  the explicit antigravity_approve variant is planned - see docs/TODO.md. */
+export type GateMode = "auto" | "shadow" | "dedicated" | "off";
+
+/** Fallback decision when no extension blocked a gated call: "ask" uses
+ *  ctx.ui.confirm (headless = deny, fail-closed), "allow" auto-approves,
+ *  "deny" auto-rejects. */
+export type GateAskMode = "ask" | "allow" | "deny";
+
+export interface GateConfig {
+	gateMode: GateMode;
+	mode: GateAskMode;
+}
+
 export interface AcpConfig {
 	/** Path to agy_acp_server.par. Empty = env AGY_ACP_BIN > PATH. */
 	bin: string;
@@ -108,6 +131,11 @@ export interface AgyConfig {
 	 *  digest (per-turn) is not. Turn off for agy-native behavior (agy's own
 	 *  system prompt only). */
 	systemPrompt: boolean;
+	/** Approval gate over agy NATIVE tool calls (create_file, run_command,
+	 *  ...). pi tools agy calls already pass through pi's gates via the G9
+	 *  round-trip; this covers the rest. Default auto (off until a
+	 *  third-party permission extension is detected). See docs/TODO.md 2.5. */
+	approvals: GateConfig;
 }
 
 const DEFAULTS: AgyConfig = {
@@ -120,6 +148,7 @@ const DEFAULTS: AgyConfig = {
 	bridgeTools: "all",
 	digest: false,
 	systemPrompt: true,
+	approvals: { gateMode: "auto", mode: "ask" },
 	acp: { bin: "", permissions: "auto" },
 };
 
@@ -189,6 +218,19 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		? ["1", "true", "on"].includes(envSys.toLowerCase())
 		: file.systemPrompt ?? DEFAULTS.systemPrompt;
 
+	// Approval gate (docs/TODO.md 2.5). Unknown values fall back to "auto"
+	// so a typo can never silently force the gate on.
+	const gateRaw = (process.env.AGY_APPROVALS ?? file.approvals?.gateMode ?? DEFAULTS.approvals.gateMode).toLowerCase();
+	const gateMode: GateMode =
+		gateRaw === "shadow" || gateRaw === "dedicated" || gateRaw === "off"
+			? gateRaw
+			: "auto";
+	const askRaw = (process.env.AGY_APPROVALS_MODE ?? file.approvals?.mode ?? DEFAULTS.approvals.mode).toLowerCase();
+	const gateAskMode: GateAskMode =
+		askRaw === "allow" || askRaw === "deny"
+			? askRaw
+			: "ask";
+
 	const fileAcp = (typeof file.acp === "object" && file.acp !== null ? file.acp : {}) as Partial<AcpConfig>;
 	const acp: AcpConfig = {
 		bin:
@@ -208,6 +250,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		bridgeTools,
 		digest,
 		systemPrompt,
+		approvals: { gateMode, mode: gateAskMode },
 		patchCleanupNotified: file.patchCleanupNotified === true,
 	};
 }

package/src/driver-types.ts

@@ -1,9 +1,9 @@
 // Engine-agnostic turn-driver contract.
 //
-// Both turn engines (legacy stream-json driver in `driver.ts`, ACP driver in
+// Both turn engines (stream-json driver in `driver.ts`, ACP driver in
 // `acp/driver.ts`) implement `TurnDriver`, and everything above them — the
 // provider's stream loop, the G9 round-trip store, the extension wiring —
-// depends on this interface only. Types live here so the legacy module can be
+// depends on this interface only. Types live here so the stream module can be
 // deleted (phase 4) without breaking imports.
 //
 // The ACP driver implements the same surface with protocol-native mechanics:
@@ -21,17 +21,17 @@ export interface DriverProfile {
 }
 
 export interface DriverTurnRequest extends DriverProfile {
-	/** Existing conversation/session to resume. Legacy: agy conversation id via
+	/** Existing conversation/session to resume. Stream-json: agy conversation id via
 	 *  `--conversation`. ACP: sessionId via `session/load` (falls back to
 	 *  `session/new` when the server no longer knows it). */
 	conversationId?: string | null;
 	prompt: string;
 	/** Image blocks riding with the prompt. ACP forwards them as typed
 	 *  content blocks (probe 2026-09-03: 64x64 two-tone PNG answered
-	 *  correctly); the legacy CLI prompt is text-only and ignores them. */
+	 *  correctly); the stream-json CLI prompt is text-only and ignores them. */
 	images?: Array<{ data: string; mimeType: string }>;
 	/** ACP only: pi-side context delivered as a native `embeddedContext`
-	 *  resource block instead of inline prompt text (G1 on ACP). Legacy
+	 *  resource block instead of inline prompt text (G1 on ACP). Stream-json
 	 *  embeds the digest in the prompt string and ignores this. */
 	contextBlock?: { uri: string; text: string };
 	signal?: AbortSignal;
@@ -52,7 +52,7 @@ export type AgyUsage = {
 
 export type DriverActivity =
 	| { type: "text"; delta: string }
-	/** Legacy emits a token count only; ACP carries the actual thought text in
+	/** 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> }
@@ -64,7 +64,7 @@ export type DriverActivity =
 			output?: string;
 			durationSeconds?: number;
 			/** ACP only: the server's native edit diff from `tool_call`
-			 *  content[] ({type:"diff", path, oldText?, newText}). Legacy never
+			 *  content[] ({type:"diff", path, oldText?, newText}). Stream-json never
 			 *  sets it; the provider renders it without any git subprocess. */
 			diff?: { path: string; oldText?: string; newText: string };
 	  }
@@ -108,7 +108,7 @@ export interface DriverSnapshot {
 		recycleReasons: Record<string, number>;
 	};
 	lifecycle: string[];
-	/** Present on ACP snapshots; absent on legacy. */
+	/** Present on ACP snapshots; absent on stream-json. */
 	engine?: "acp";
 	acp?: {
 		sessionId?: string;
@@ -133,7 +133,7 @@ export interface DriverSnapshot {
 }
 
 /** The engine contract. Everything above the driver depends on this interface
- *  only; `AgyDriver` and `AcpDriver` both implement it. */
+ *  only; `StreamDriver` and `AcpDriver` both implement it. */
 export interface TurnDriver {
 	readonly state: DriverState;
 	readonly activeHandle: TurnHandle | null;

package/src/driver.ts

@@ -122,7 +122,7 @@ export function shouldFlipToCumulative(accumulated: string, next: string): boole
 	return accumulated.length >= CUMULATIVE_FLIP_MIN_CHARS && isCumulativeResend(accumulated, next);
 }
 
-export class AgyDriver implements TurnDriver {
+export class StreamDriver implements TurnDriver {
 	#state: DriverState = "idle";
 	#child: ChildProcess | undefined;
 	#generation = 0;
@@ -130,7 +130,6 @@ export class AgyDriver implements TurnDriver {
 	#boundConversation: string | undefined;
 	#active: ActiveTurn | undefined;
 	#queueTail: Promise<void> = Promise.resolve();
-	#shutdown = false;
 	#stderrTail = "";
 	// Frames can split across pipe chunks; the trailing partial line lives here
 	// until its newline arrives (same scheme as JsonRpcSession.feed). Dropping
@@ -218,7 +217,10 @@ export class AgyDriver implements TurnDriver {
 	}
 
 	async #runExclusive(request: DriverTurnRequest): Promise<TurnHandle> {
-		if (this.#shutdown) throw new Error("agy driver is shut down.");
+		// No shutdown latch: pi fires session_shutdown on /new, /resume and
+		// /fork (not only process exit), so a closed driver must respawn on the
+		// next turn instead of rejecting forever. Parity with the ACP driver
+		// fix (regression 2026-09-07).
 		if (request.signal?.aborted) throw new Error("aborted before start");
 
 		const cause = this.#recycleCause(request);
@@ -588,7 +590,6 @@ export class AgyDriver implements TurnDriver {
 	}
 
 	async close(reason: "recycle" | "shutdown", cause?: string): Promise<void> {
-		if (reason === "shutdown") this.#shutdown = true;
 		const child = this.#child;
 		if (!child) {
 			this.#state = reason === "shutdown" ? "dead" : "idle";
@@ -602,7 +603,7 @@ export class AgyDriver implements TurnDriver {
 		this.#log(`close:${reason}${cause ? `:${cause}` : ""}`);
 		const turn = this.#active;
 		if (turn && !turn.closed) {
-			this.#failTurn(turn, `agy driver ${reason}ed mid-turn${cause ? ` (${cause})` : ""}`);
+			this.#failTurn(turn, `agy driver ${reason === "recycle" ? "recycled" : "shut down"} mid-turn${cause ? ` (${cause})` : ""}`);
 		}
 		this.#killChild();
 		this.#state = reason === "shutdown" ? "dead" : "idle";