@estebanforge/pi-antigravity-bridge 1.8.8 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.9.0] - 2026-10-27
+
+### Fixed
+
+- **`/agy-stop` no longer discards an answer that already finished computing.** Between the agy process closing and the run settling (conversation discovery + classification, up to ~500ms), a stop settled the run failed and silently dropped the computed answer. The stop handler now consults a finishing guard (the new opt-in `guard` option on pi-ask-shared's `createStopHandler`) and refuses with "already finished; its result is being delivered" while that window is open; the wake then delivers normally.
+
+- **`details.stderr` is redacted at the boundary.** Tool-result details are persisted in session files, and raw stderr can carry auth material; the stored field now passes through the bridge's redactor. The blocking answer text stays raw, like every other ask tool. This rides the same change as the background feature, which introduced the background-run stderr wake path that made the asymmetry visible.
+
+- **The suppression refcount survives `/reload`.** It lived in module state, so a runtime replacement reset it to zero and the old runtime's late release (its kill path is async) could re-enable the bridge's global entries while the new runtime's delegation was still live. It now lives in a `Symbol.for`-keyed `globalThis` slot, shared by every runtime instance in the process.
+
+### Changed
+
+- **Refusal results render with the error glyph.** Refusal paths returned `exitCode: 0`, so pi showed "✓ AskAntigravity" for calls that never ran. They now carry `details.refused`, and `renderResult` flips to ✗. Details only; refusal text is unchanged.
+
+### Added
+
+- **`AskAntigravity` supports background runs, 1:1 with the standalone pi-ask-antigravity extension.** The old `background: true` refusal is gone: the call returns a `bg_` runId at once and the full answer arrives as an UNTRUSTED-tagged wake message (customType `ask-antigravity-result`, secret-redacted through the bridge's redactor) when the detached `agy -p` tree settles, carrying the conversationId resume handle. New `/agy-stop [runId]` command kills a run by id prefix, or the only running one with no argument. Shared `pi-ask-shared` machinery gives the same semantics as every other ask tool: concurrency cap 4 with a visible refusal, settle-once so a stop and a natural close can never double-wake, TTL sweep, and `session_shutdown` killing in-flight runs silently (pi's `/new`, `/resume`, `/fork`, `/reload` wipe module state and take the runs with them). Background is refused in print/json mode, where the process exits before the wake could arrive. Two behavior fixes ride along: the MCP-suppression window now spans background runs too (execute() returns while agy is still alive, so the release moved into the run lifecycle and fires exactly once per run), and the per-conversation lock (one run per conversationId, since two runs resuming the same conversation interleave turns inside agy's SQLite state) now also covers blocking calls. The delegation path itself is unchanged and engine-independent: always a fresh one-shot `agy -p`, never the ACP or stream-json turn engine. Review hardening riding in the same change: the detached run now settles on stream close instead of process exit (an exit-time settle could truncate the answer and disarmed the SIGKILL escalation while group members were still dying), stdout/stderr buffers carry valves (1M/64k) so a runaway child cannot grow memory over a days-long timeout, the timeout wake's partial-output slice is redacted before cutting (a sliced secret can fall under the redactor's length thresholds), and the suppression release is exactly-once at the call site, not just inside the callee's refcount guard.
+
 ## [1.8.8] - 2026-10-27
 
 ### Fixed

package/README.md

@@ -150,6 +150,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy engine acp|stream-json   switch the turn engine (restart to apply; default acp, stream-json is the fallback; acp runs self-service setup: binary install + auth bootstrap). No arguments opens the engine picker modal (TUI)
 /agy auth-manual             manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
 /agy clear                drop all session bindings (force fresh conversations)
+/agy-stop [runId]         stop a background AskAntigravity run (id prefix, or the only running one with no argument)
 ```
 
 ### Permissions
@@ -226,9 +227,9 @@ pi-antigravity-bridge practical risk is low, near zero. But not zero: the "in co
 
 This is engineering analysis, not legal advice. Use against your own Antigravity account at your own risk; I am not responsible for any consequence to your account.
 
-## Delegation tool: background is refused
+## Delegation tool: background runs
 
-The `AskAntigravity` delegation tool rejects `background: true` by design: a background wake would land in the pi session even when the caller is a nested delegation through the bridge catalog, and long delegations already have the bridge's own async flow (early-ack plus `bridge_poll_result`). Call without `background`; for unattended peer runs launch the CLI directly in a terminal.
+`AskAntigravity` accepts `background: true` (1:1 with the standalone pi-ask-antigravity extension): the call returns a `bg_` runId at once and the full answer arrives later as an UNTRUSTED-tagged message (secret-redacted) carrying the resume handle. `/agy-stop [runId]` stops a run by id prefix, or the only running one with no argument; the concurrency cap is 4. A stop landing after agy already closed but before the result settles (the discovery window) is refused with "already finished; its result is being delivered" instead of dropping the answer. Background is refused in pi's print/json modes (the process exits before the message could arrive), and `/new`, `/resume`, `/fork`, `/reload` kill in-flight runs. Delegation always spawns a one-shot `agy -p` process - never the ACP or stream-json turn engine.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.8.8",
+  "version": "1.9.0",
   "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. Use antigravity/* models in Pi. Full /model picker support. Models runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",
@@ -54,7 +54,7 @@
     }
   },
   "dependencies": {
-    "@estebanforge/pi-ask-shared": "^0.1.2",
+    "@estebanforge/pi-ask-shared": "^0.1.3",
     "@estebanforge/pi-tui-dialogs": "^0.1.2",
     "@modelcontextprotocol/sdk": "^1.31.0"
   }

package/src/ask-tool.ts

@@ -21,9 +21,13 @@ import { Text } from "@earendil-works/pi-tui";
 import { contentText, type ThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import {
+	BackgroundRunRegistry,
+	backgroundFlagText,
 	buildAgyArgs,
 	buildFinalPrompt,
 	buildTimeBudgetNotice,
+	createStopHandler,
+	createWakeSender,
 	MAX_TIMEOUT_MINUTES,
 	CONVERSATIONS_DIR,
 	CONV_ID_RE,
@@ -33,6 +37,7 @@ import {
 	parseModelLine,
 	resolveAgyModel,
 	snapshotConversations,
+	summarizePrompt,
 	type ModelEntry,
 	type Mode,
 } from "@estebanforge/pi-ask-shared";
@@ -165,6 +170,266 @@ export function stageReviewerAgent(root: string): { name: string; dir: string }
 
 const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
 
+// --- One-shot agy run -------------------------------------------------------
+
+type AskLogFn = (event: string, data?: unknown, level?: "debug" | "info" | "warn" | "error") => void;
+
+/** Terminal result of one `agy -p` lifecycle. */
+interface AgyOutcome {
+	exitCode: number;
+	aborted: boolean;
+	timedOut: boolean;
+	/** Full stdout, trimmed. Empty means the headless auto-deny failure mode. */
+	answerText: string;
+}
+
+/** Tool-result shape the execute path returns; keeps the background helper's literals narrow. */
+interface AskToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: AgyDetails;
+}
+
+/**
+ * Spawns `agy -p` and resolves when the process tree closes. Blocking and
+ * background runs share this lifecycle. Owns the delegation-suppression
+ * window for the WHOLE run: agy watches the global mcp_config and
+ * hot-reloads it, so a mid-run re-enable pokes the live delegation
+ * (observed live 2026-09-09). Background runs outlive execute()'s return,
+ * which is why the window lives here and not in the caller's finally.
+ */
+async function runAgyProcess(o: {
+	binary: string;
+	args: string[];
+	cwd: string;
+	timeoutMin: number;
+	startAt: number;
+	/** Mutated in place: conversationId discovery, stderr, outcome fields. */
+	details: AgyDetails;
+	isContinuation: boolean;
+	snapshot: ReturnType<typeof snapshotConversations> | null;
+	background: boolean;
+	/** Blocking passes pi's per-run signal; background passes none on purpose: a later Esc must not kill a detached run. */
+	signal?: AbortSignal;
+	/** Blocking only: throttled progress partials. */
+	onPartial?: (text: string) => void;
+	/** Background only: hands over the tree-kill switch as soon as it exists. */
+	registerKill?: (kill: () => void) => void;
+	/** Background only: the child closed; discovery/classification still running. Arms the stop handler's finishing guard. */
+	onClose?: () => void;
+	log?: AskLogFn;
+}): Promise<AgyOutcome> {
+	const restoreBridge = acquireBridgeSuppression();
+	let bridgeReleased = false;
+	const releaseBridge = () => {
+		if (bridgeReleased) return;
+		bridgeReleased = true;
+		restoreBridge();
+	};
+	let out = "";
+	// Local: o.snapshot narrowing does not survive into the bind-poll closure.
+	const snapshot = o.snapshot;
+	const statusInterval = o.onPartial
+		? setInterval(() => {
+				const elapsed = Math.floor((Date.now() - o.startAt) / 1000);
+				const tail = out.slice(-STATUS_TAIL_CHARS);
+				const text = tail ? `(running ${elapsed}s)\n…${tail}` : `(running ${elapsed}s)`;
+				o.onPartial!(text);
+			}, STATUS_INTERVAL_MS)
+		: null;
+
+	try {
+		// Bind the conversation id DURING the run (agy is alive then) so the
+		// pid-based /proc FD resolver can disambiguate when a concurrent agy
+		// also drops a new .db. Awaited after the run; the post-exit loop
+		// below is the fallback for runs that exit before the poll binds.
+		let bindDuringRun: Promise<void> = Promise.resolve();
+		const outcome = await new Promise<{ exitCode: number; aborted: boolean; timedOut: boolean }>((resolveP, rejectP) => {
+			const proc = spawn(o.binary, o.args, {
+				cwd: o.cwd,
+				stdio: ["ignore", "pipe", "pipe"],
+				shell: false,
+				detached: true,
+			});
+			proc.stdout?.setEncoding("utf8");
+			proc.stderr?.setEncoding("utf8");
+			// Valve: a runaway child must not grow these without bound over a
+			// detached run's lifetime (timeouts can reach days).
+			proc.stdout?.on("data", (d: string) => {
+				if (out.length < 1_000_000) out += d;
+			});
+			proc.stderr?.on("data", (d: string) => {
+				if (o.details.stderr.length < 65_536) o.details.stderr += d;
+			});
+
+			if (!o.isContinuation && snapshot && proc.pid) {
+				bindDuringRun = (async () => {
+					for (let attempt = 0; attempt < DISCOVERY_POLL_ATTEMPTS; attempt++) {
+						if (o.details.conversationId) return;
+						if (proc.exitCode !== null) return; // agy gone: scan useless now
+						const found = newConversationId(CONVERSATIONS_DIR, snapshot, {
+							pid: proc.pid,
+						});
+						if (found) {
+							o.details.conversationId = found;
+							return;
+						}
+						await sleep(DISCOVERY_POLL_MS);
+					}
+				})().catch(() => {
+					/* best-effort: a bind error must never fail an otherwise-OK turn */
+				});
+			}
+
+			let sigkillTimer: ReturnType<typeof setTimeout> | undefined;
+			let watchdog: ReturnType<typeof setTimeout> | undefined;
+			let settled = false;
+			let timedOut = false;
+
+			const killTree = () => {
+				try {
+					if (proc.pid) process.kill(-proc.pid, "SIGTERM");
+				} catch {
+					/* process group already gone */
+				}
+				if (!sigkillTimer) {
+					sigkillTimer = setTimeout(() => {
+						try {
+							if (proc.pid) process.kill(-proc.pid, "SIGKILL");
+						} catch {
+							/* give up */
+						}
+					}, GRACE_AFTER_TIMEOUT_MS);
+				}
+			};
+
+			// Hand the tree-kill switch to the background registry before the
+			// watchdog arms, so /agy-stop can land the moment the run exists.
+			o.registerKill?.(killTree);
+
+			const cleanup = () => {
+				if (watchdog) clearTimeout(watchdog);
+				if (sigkillTimer) clearTimeout(sigkillTimer);
+				if (o.signal) o.signal.removeEventListener("abort", onAbort);
+				releaseBridge();
+				o.onClose?.();
+			};
+			const onAbort = () => killTree();
+
+			watchdog = setTimeout(() => {
+				timedOut = true;
+				killTree();
+			}, o.timeoutMin * 60_000);
+
+			if (o.signal) {
+				if (o.signal.aborted) killTree();
+				else o.signal.addEventListener("abort", onAbort, { once: true });
+			}
+
+			const finish = (code: number | null) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				resolveP({ exitCode: code ?? 0, aborted: !!o.signal?.aborted, timedOut });
+			};
+
+			proc.on("error", (err) => {
+				cleanup();
+				rejectP(err);
+			});
+			// Settle on close, never exit: exit can strand unread stdout
+			// (truncated answer) and would clear the SIGKILL escalation while
+			// group members are still dying.
+			proc.on("close", finish);
+		});
+
+		// Let the during-run bind poll finish (it bails immediately once agy
+		// has exited, so this rarely blocks).
+		await bindDuringRun;
+
+		o.details.exitCode = outcome.exitCode;
+		o.details.aborted = outcome.aborted;
+		o.details.timedOut = outcome.timedOut;
+		// details ride the tool result and are persisted in session files;
+		// stderr can carry auth material, so it is scrubbed at this boundary.
+		o.details.stderr = redactText(o.details.stderr);
+		o.details.durationMs = Date.now() - o.startAt;
+		o.log?.(
+			"ask-end",
+			{ exitCode: outcome.exitCode, aborted: outcome.aborted, timedOut: outcome.timedOut, empty: !out.trim(), background: o.background, durationMs: o.details.durationMs, conversationId: o.details.conversationId },
+			outcome.exitCode !== 0 || outcome.aborted || outcome.timedOut || !out.trim() ? "warn" : "info",
+		);
+
+		if (!o.isContinuation && !o.details.conversationId && snapshot) {
+			for (let attempt = 0; attempt < DISCOVERY_POLL_ATTEMPTS; attempt++) {
+				const found = newConversationId(CONVERSATIONS_DIR, snapshot);
+				if (found) {
+					o.details.conversationId = found;
+					break;
+				}
+				await sleep(DISCOVERY_POLL_MS);
+			}
+		}
+
+		return { ...outcome, answerText: out.trim() };
+	} finally {
+		if (statusInterval) clearInterval(statusInterval);
+		// Belt and braces: cleanup() already releases on close/error; this
+		// covers paths that never reached the process (sync spawn throw).
+		releaseBridge();
+	}
+}
+
+/**
+ * Builds the model/user-facing answer text for every terminal outcome.
+ * Pure except the empty-output marker it stamps on details. Blocking and
+ * background share it so both surfaces read identically.
+ */
+function shapeFinalText(details: AgyDetails, outcome: AgyOutcome, timeoutMin: number): string {
+	const text = outcome.answerText;
+
+	if (outcome.aborted) {
+		return text ? `agy was aborted. Partial output:\n\n${text}` : "agy was aborted before producing output.";
+	}
+
+	if (outcome.timedOut) {
+		const note = `agy exceeded the ${timeoutMin}m timeout and was killed`;
+		return text ? `${text}\n\n[${note}]` : note;
+	}
+
+	if (outcome.exitCode !== 0) {
+		// stderr can carry auth material; the note is chat-visible.
+		const stderr = redactText(details.stderr.trim());
+		const note = stderr
+			? `agy exited with status ${outcome.exitCode}: ${stderr}`
+			: `agy exited with status ${outcome.exitCode}`;
+		return text ? `${text}\n\n[${note}]` : note;
+	}
+
+	// Exit 0 with nothing on stdout is still a failure for the
+	// delegator: headless agy auto-denies a permission-gated tool call
+	// (e.g. the command gate in plan mode), prints the reason only to
+	// stderr, and ends cleanly. Falling through to the success path here
+	// returned just the conversation footer, which read as an empty
+	// success (silent-failure bug found 2026-09-25).
+	if (!text) {
+		details.empty = true;
+		const stderr = redactText(details.stderr.trim());
+		const note = [
+			"agy exited cleanly but produced no output.",
+			stderr ? `stderr: ${stderr}` : null,
+			"Common cause: a tool call needed a permission that headless mode cannot prompt for (typically the command gate in plan mode), so it was auto-denied and the turn ended with no answer. Recovery: retry in plan mode with all needed content inlined in the prompt - plan runs cannot fetch it, commands are denied. Or rerun outside plan mode with skipPermissions, or add your own permissions.allow rules in ~/.gemini/antigravity-cli/settings.json.",
+		]
+			.filter(Boolean)
+			.join(" ");
+		return note;
+	}
+
+	const footer = details.conversationId
+		? `\n\n[agy conversationId: ${details.conversationId} - pass as conversationId to continue this conversation]`
+		: "";
+	return text + footer;
+}
+
 // --- Registration ----------------------------------------------------------
 
 /** Register the AskAntigravity tool. Call once from the extension entry.
@@ -184,6 +449,209 @@ export async function registerAskAntigravityTool(
 	} catch {
 		// a sweep failure must never block registration
 	}
+
+	// --- Background-run state (one set per registration/load) ----------------
+	// Pi wipes module state on /new, /resume, /fork and /reload: an in-flight
+	// background run is killed and its result is never delivered. Accepted
+	// trade-off, same as the standalone pi-ask-antigravity extension.
+	const registry = new BackgroundRunRegistry({ toolName: "ask-antigravity" });
+	const kills = new Map<string, () => void>();
+	// Staged-artifact cleanup (contextFile + reviewer agent dir), keyed by run:
+	// the session_shutdown backstop runs these when a hard exit would skip the
+	// close-path cleanup.
+	const cleanups = new Map<string, () => void>();
+	// One run per conversationId at a time: two runs resuming the same
+	// conversation interleave their turns inside agy's SQLite state.
+	const busyHandles = new Set<string>();
+	// The child closed but the answer is not settled yet (discovery +
+	// classification): a stop in this window must refuse instead of settling
+	// failed and discarding a computed answer.
+	const finishing = new Set<string>();
+	// The wake is chat-visible and persisted: run it through the bridge's
+	// secret redactor like every other reassembled-output boundary.
+	const sendWake = createWakeSender(pi, {
+		customType: "ask-antigravity-result",
+		isDisposed: () => registry.isDisposed(),
+		redact: redactText,
+	});
+	const stopBackground = createStopHandler(registry, {
+		kill: (run) => kills.get(run.runId)?.(),
+		onStopped: (run) =>
+			sendWake({
+				toolLabel: "agy",
+				runId: run.runId,
+				ok: false,
+				elapsedS: Math.round((Date.now() - run.startedAt) / 1000),
+				error: "stopped via /agy-stop",
+			}),
+		// The guard keeps /agy-stop from discarding an answer that already
+		// finished computing and is riding discovery to its wake.
+		guard: (run) =>
+			finishing.has(run.runId) ? `Run ${run.runId} already finished; its result is being delivered.` : null,
+	});
+	pi.on("session_shutdown", () => {
+		// Latch first so close-handler wakes stay silent, then kill children,
+		// then sweep staged artifacts (a hard exit would skip the close path).
+		for (const run of registry.dispose()) kills.get(run.runId)?.();
+		for (const fn of cleanups.values()) fn();
+		cleanups.clear();
+		kills.clear();
+	});
+	pi.registerCommand("agy-stop", {
+		description: "Stop a background AskAntigravity run (id prefix, or the only running one). Usage: /agy-stop [runId]",
+		handler: async (args, ctx) => {
+			const message = await stopBackground(args ?? "");
+			if (ctx.hasUI) ctx.ui.notify(message, "info");
+		},
+	});
+
+	/** Fire-and-forget background run: registry slot, detached agy, wake on
+	 *  settle. Mirrors the standalone pi-ask-antigravity extension call for
+	 *  call; only the suppression window and the redaction are bridge-local. */
+	const startBackgroundRun = (o: {
+		summary: string;
+		binary: string;
+		args: string[];
+		workdir: string;
+		timeoutMin: number;
+		startAt: number;
+		details: AgyDetails;
+		contextFile: string | null;
+		reviewerAgent: { name: string; dir: string } | null;
+		modelLabel: string;
+		isContinuation: boolean;
+		snapshot: ReturnType<typeof snapshotConversations> | null;
+		conversationId?: string;
+	}): AskToolResult => {
+		const cleanupStaging = () => {
+			// Both staged artifacts must outlive the execute() return in
+			// background mode: agy reads them mid-run.
+			if (o.contextFile) {
+				try {
+					fs.unlinkSync(o.contextFile);
+				} catch {}
+			}
+			if (o.reviewerAgent) {
+				try {
+					fs.rmSync(o.reviewerAgent.dir, { recursive: true, force: true });
+				} catch {}
+			}
+		};
+		registry.sweep();
+		if (o.conversationId && busyHandles.has(o.conversationId)) {
+			cleanupStaging();
+			return {
+				content: [
+					{
+						type: "text",
+						text: `background refused: conversation ${o.conversationId} already has a background run. Wait for its wake message, or use blocking mode.`,
+					},
+				],
+				details: { ...o.details, refused: true },
+			};
+		}
+		if (o.conversationId) busyHandles.add(o.conversationId);
+		let run;
+		try {
+			run = registry.start(summarizePrompt(o.summary));
+		} catch (err) {
+			if (o.conversationId) busyHandles.delete(o.conversationId);
+			cleanupStaging();
+			const msg = err instanceof Error ? err.message : String(err);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `background refused: ${msg}. Use blocking (omit background) or free a slot with /agy-stop.`,
+					},
+				],
+				details: { ...o.details, refused: true },
+			};
+		}
+		const runId = run.runId;
+		cleanups.set(runId, cleanupStaging);
+		log?.(
+			"ask-start",
+			{ model: o.details.resolvedModel, thinking: o.details.thinking, mode: o.details.mode, digest: o.details.digest, continue: o.isContinuation, timeoutMin: o.timeoutMin, background: true },
+			"info",
+		);
+		void runAgyProcess({
+			binary: o.binary,
+			args: o.args,
+			cwd: o.workdir,
+			timeoutMin: o.timeoutMin,
+			startAt: o.startAt,
+			details: o.details,
+			isContinuation: o.isContinuation,
+			snapshot: o.snapshot,
+			background: true,
+			registerKill: (kill) => {
+				kills.set(runId, kill);
+			},
+			onClose: () => finishing.add(runId),
+			log,
+		})
+			.then((outcome) => {
+				kills.delete(runId);
+				const finalText = shapeFinalText(o.details, outcome, o.timeoutMin);
+				const elapsedS = Math.round((Date.now() - o.startAt) / 1000);
+				const handle = o.details.conversationId ? `conversationId=${o.details.conversationId}` : undefined;
+				const failed = outcome.timedOut || outcome.exitCode !== 0 || !outcome.answerText;
+				// The settle latch makes /agy-stop and shutdown win races
+				// against this handler: a false return means their wake went out.
+				const settled = registry.settle(runId, {
+					status: failed ? "failed" : "done",
+					output: finalText,
+					handle,
+					error: outcome.timedOut
+						? `timeout after ${o.timeoutMin}m`
+						: outcome.exitCode !== 0
+							? `exit status ${outcome.exitCode}`
+							: !outcome.answerText
+								? "agy exited cleanly but produced no output"
+								: undefined,
+				});
+				if (!settled) return;
+				if (outcome.timedOut) {
+					const partial = outcome.answerText
+						? ` Partial output: ${redactText(outcome.answerText).slice(0, 400)}`
+						: "";
+					sendWake({ toolLabel: "agy", runId, ok: false, elapsedS, error: `timeout after ${o.timeoutMin}m.${partial}`, handle });
+				} else if (outcome.exitCode !== 0) {
+					// stderr can carry auth material; the reason is chat-visible.
+					const reason = redactText(o.details.stderr.trim()).slice(0, 400) || `exit status ${outcome.exitCode}`;
+					sendWake({ toolLabel: "agy", runId, ok: false, elapsedS, error: reason, handle });
+				} else if (!outcome.answerText) {
+					sendWake({ toolLabel: "agy", runId, ok: false, elapsedS, error: "agy exited cleanly but produced no output (headless auto-deny?)", handle });
+				} else {
+					sendWake({ toolLabel: "agy", runId, ok: true, elapsedS, handle }, finalText);
+				}
+			})
+			.catch((err) => {
+				kills.delete(runId);
+				const msg = err instanceof Error ? err.message : String(err);
+				// Settle first: an /agy-stop that won the race owns the wake.
+				const settled = registry.settle(runId, { status: "failed", error: msg });
+				if (!settled) return;
+				sendWake({ toolLabel: "agy", runId, ok: false, error: `failed to run agy: ${msg}` });
+			})
+			.finally(() => {
+				cleanups.delete(runId);
+				finishing.delete(runId);
+				cleanupStaging();
+				if (o.conversationId) busyHandles.delete(o.conversationId);
+			});
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Background run ${runId} started (model=${o.modelLabel}). The result arrives as a message when agy finishes; the resume handle (conversationId) comes with it when agy reports one. Do not poll. Continue with other work or end the turn.`,
+				},
+			],
+			details: { ...o.details },
+		};
+	};
+
 	pi.registerTool({
 		name: "AskAntigravity",
 		label: "Ask Antigravity",
@@ -245,8 +713,8 @@ export async function registerAskAntigravityTool(
 			),
 			background: Type.Optional(
 				Type.Boolean({
-					description:
-						"NOT supported by this tool. The bridge runs agy through its own delegated flow and the answer must return synchronously to the caller. For background runs use the standalone @estebanforge/pi-ask-antigravity extension. Calls with background=true are refused.",
+					description: backgroundFlagText("conversationId"),
+					default: false,
 				}),
 			),
 		}),
@@ -277,6 +745,7 @@ export async function registerAskAntigravityTool(
 			if (useDigest) tags.push("digest");
 			if (isContinue) tags.push("continue");
 			if (args.includeContext) tags.push("context=full");
+			if (args.background) tags.push("bg");
 
 			let text = theme.fg("mdLink", theme.bold("AskAntigravity "));
 			text += `${theme.fg("accent", `[${tags.join(", ")}]`)} `;
@@ -299,7 +768,7 @@ export async function registerAskAntigravityTool(
 
 			const body = result.content[0]?.type === "text" ? result.content[0].text : "";
 			const errored =
-		d?.exitCode !== 0 || !!d?.aborted || !!d?.timedOut || !!d?.empty;
+			!!d?.refused || d?.exitCode !== 0 || !!d?.aborted || !!d?.timedOut || !!d?.empty;
 
 			let text = errored
 				? theme.fg("error", "✗ AskAntigravity error")
@@ -356,22 +825,6 @@ export async function registerAskAntigravityTool(
 					details: emptyDetails(),
 				};
 			}
-			// Background refusal (fail-closed): a wake from this tool would land in
-			// the pi session even when the CALLER is agy (nested delegation via the
-			// bridge catalog), and the bridge already owns an async delegation flow
-			// (early-ack + bridge_poll_result). The standalone pi-ask-antigravity
-			// extension is the background-capable tool.
-			if (params.background) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: 'background is not supported by the bridge\'s AskAntigravity: the answer must return synchronously to the caller. Long delegations are already covered by the bridge\'s own async flow (early-ack + bridge_poll_result); for an unattended peer run, launch agy directly in a terminal instead. Call again without background.',
-						},
-					],
-					details: emptyDetails(),
-				};
-			}
 			const requestedModel = (params.model as string | undefined) ?? config.defaultModel;
 			if (typeof params.model === "string" && params.model.trim().startsWith("-")) {
 				return {
@@ -496,7 +949,7 @@ export async function registerAskAntigravityTool(
 
 			log?.(
 				"ask-start",
-				{ model: resolved.model, thinking: resolved.effort ?? config.defaultThinking, mode, digest: useDigest, continue: isContinuation, timeoutMin },
+				{ model: resolved.model, thinking: resolved.effort ?? config.defaultThinking, mode, digest: useDigest, continue: isContinuation, timeoutMin, background: false },
 				"info",
 			);
 			// Build argv via the shared peer adapter (see buildAgyArgs there for
@@ -532,246 +985,126 @@ export async function registerAskAntigravityTool(
 			};
 
 			const binary = process.env.AGY_BIN || "agy";
-			let out = "";
-
-			// Delegation isolation: any agy on this machine discovers MCP servers
-			// from the global mcp_config.json, so this spawned `agy -p` would find
-			// live pi-bridge-* entries and call tools the host bridge cannot serve
-			// outside a live provider turn ("no active antigravity turn"). agy also
-			// WATCHES that file (ReloadMcpConfig): re-enabling mid-run pokes the live
-			// delegation to reconnect. The old 5s grace timer did exactly that -
-			// observed live 2026-09-09 as a call-tool-fail ~50s into a delegation -
-			// so the entries now stay hidden for the WHOLE delegated run. The release
-			// fires only on process close/error (cleanup + finally below); if pi
-			// itself dies first, session start heals the file
-			// (healBridgeSuppression in extensions/index.ts, marker-aware). Cross-
-			// process coordination rides the suppression marker in mcp-registration.
-			// Refcounted, so overlapping delegations in this process cannot release
-			// each other's window early. A refused config fail-opens to the status quo.
-			const restoreBridge = acquireBridgeSuppression();
-
-			const statusInterval = onUpdate
-				? setInterval(() => {
-						const elapsed = Math.floor((Date.now() - start) / 1000);
-						const tail = out.slice(-STATUS_TAIL_CHARS);
-						const text = tail ? `(running ${elapsed}s)\n…${tail}` : `(running ${elapsed}s)`;
-						onUpdate({
-							content: [{ type: "text", text }],
-							details: { ...details, durationMs: Date.now() - start },
-						});
-					}, STATUS_INTERVAL_MS)
-				: null;
 
-			try {
-				// Bind the conversation id DURING the run (agy is alive then) so the
-				// pid-based /proc FD resolver can disambiguate when a concurrent agy
-				// also drops a new .db. Awaited after the run; the post-exit loop
-				// below is the fallback for runs that exit before the poll binds.
-				let bindDuringRun: Promise<void> = Promise.resolve();
-				const outcome = await new Promise<{
-					exitCode: number;
-					aborted: boolean;
-					timedOut: boolean;
-				}>((resolveP, rejectP) => {
-					const proc = spawn(binary, args, {
-						cwd,
-						stdio: ["ignore", "pipe", "pipe"],
-						shell: false,
-						detached: true,
-					});
-					proc.stdout?.setEncoding("utf8");
-					proc.stderr?.setEncoding("utf8");
-					proc.stdout?.on("data", (d: string) => (out += d));
-					proc.stderr?.on("data", (d: string) => (details.stderr += d));
-
-					// Concurrent bind: poll for the new id while agy is alive. The FD
-					// resolver needs a live process tree, so this stops (and the post-
-					// exit fallback below takes over) once agy has exited.
-					if (!isContinuation && snapshot && proc.pid) {
-						bindDuringRun = (async () => {
-							for (let attempt = 0; attempt < DISCOVERY_POLL_ATTEMPTS; attempt++) {
-								if (details.conversationId) return;
-								if (proc.exitCode !== null) return; // agy gone: scan useless now
-								const found = newConversationId(CONVERSATIONS_DIR, snapshot, {
-									pid: proc.pid,
-								});
-								if (found) {
-									details.conversationId = found;
-									return;
-								}
-								await sleep(DISCOVERY_POLL_MS);
-							}
-						})().catch(() => {
-							/* best-effort: a bind error must never fail an otherwise-OK turn */
-						});
-					}
-
-					let sigkillTimer: ReturnType<typeof setTimeout> | undefined;
-					let watchdog: ReturnType<typeof setTimeout> | undefined;
-					let settled = false;
-					let timedOut = false;
-
-					const killTree = () => {
-						try {
-							if (proc.pid) process.kill(-proc.pid, "SIGTERM");
-						} catch {
-							/* process group already gone */
-						}
-						if (!sigkillTimer) {
-							sigkillTimer = setTimeout(() => {
-								try {
-									if (proc.pid) process.kill(-proc.pid, "SIGKILL");
-								} catch {
-									/* give up */
-								}
-							}, GRACE_AFTER_TIMEOUT_MS);
-						}
-					};
-
-					const cleanup = () => {
-						if (watchdog) clearTimeout(watchdog);
-						if (sigkillTimer) clearTimeout(sigkillTimer);
-						if (signal) signal.removeEventListener("abort", onAbort);
-						restoreBridge();
-					};
-					const onAbort = () => killTree();
-
-					watchdog = setTimeout(() => {
-						timedOut = true;
-						killTree();
-					}, timeoutMin * 60_000);
-
-					if (signal) {
-						if (signal.aborted) killTree();
-						else signal.addEventListener("abort", onAbort, { once: true });
-					}
-
-					const finish = (code: number | null) => {
-						if (settled) return;
-						settled = true;
-						cleanup();
-						resolveP({
-							exitCode: code ?? 0,
-							aborted: !!signal?.aborted,
-							timedOut,
-						});
-					};
-
-					proc.on("error", (err) => {
-						cleanup();
-						rejectP(err);
-					});
-					proc.on("close", finish);
-					proc.on("exit", finish);
-				});
-
-				if (statusInterval) clearInterval(statusInterval);
-
-				// Let the during-run bind poll finish (it bails immediately once agy
-				// has exited, so this rarely blocks).
-				await bindDuringRun;
-
-				details.exitCode = outcome.exitCode;
-				details.aborted = outcome.aborted;
-				details.timedOut = outcome.timedOut;
-				details.durationMs = Date.now() - start;
-				const text = out.trim();
-				log?.(
-					"ask-end",
-					{ exitCode: outcome.exitCode, aborted: outcome.aborted, timedOut: outcome.timedOut, empty: !text, durationMs: details.durationMs, conversationId: details.conversationId },
-					outcome.exitCode !== 0 || outcome.aborted || outcome.timedOut || !text ? "warn" : "info",
-				);
-
-				if (!isContinuation && !details.conversationId && snapshot) {
-					for (let attempt = 0; attempt < DISCOVERY_POLL_ATTEMPTS; attempt++) {
-						const found = newConversationId(CONVERSATIONS_DIR, snapshot);
-						if (found) {
-							details.conversationId = found;
-							break;
-						}
-						await sleep(DISCOVERY_POLL_MS);
-					}
+			const cleanupStaging = () => {
+				if (contextFile) {
+					try {
+						fs.unlinkSync(contextFile);
+					} catch {}
 				}
+				if (reviewerAgent) {
+					try {
+						fs.rmSync(reviewerAgent.dir, { recursive: true, force: true });
+					} catch {}
+				}
+			};
 
-				if (outcome.aborted) {
+			// Background: hand the run to the registry and return at once. The
+			// result travels back through sendMessage (wake), not this call.
+			if (params.background) {
+				if (ctx.mode === "print" || ctx.mode === "json") {
+					cleanupStaging();
 					return {
 						content: [
 							{
 								type: "text",
-								text: text
-									? `agy was aborted. Partial output:\n\n${text}`
-									: "agy was aborted before producing output.",
+								text: "background is not available in print/json mode: the process exits before the result message can arrive. Call again without background.",
 							},
 						],
-						details,
+						details: { ...details, refused: true },
 					};
 				}
+				return startBackgroundRun({
+					summary: params.prompt,
+					binary,
+					args,
+					workdir: cwd,
+					timeoutMin,
+					startAt: start,
+					details,
+					contextFile,
+					reviewerAgent,
+					modelLabel: resolved.model ?? requestedModel,
+					isContinuation,
+					snapshot,
+					conversationId: isContinuation ? (rawConvId as string) : undefined,
+				});
+			}
 
-				if (outcome.timedOut) {
-					const note = `agy exceeded the ${timeoutMin}m timeout and was killed`;
+			// One run per conversationId at a time, blocking included: a blocking
+			// resume and a background resume of the same conversation would
+			// interleave turns inside agy's session state. Declared out here so
+			// the finally can see it; set only when THIS call takes the lock.
+			let lockAcquired = false;
+			try {
+				if (isContinuation && busyHandles.has(rawConvId as string)) {
+					cleanupStaging();
 					return {
-						content: [{ type: "text", text: text ? `${text}\n\n[${note}]` : note }],
-						details,
+						content: [
+							{
+								type: "text",
+								text: `conversation ${rawConvId} already has a run in flight. Wait for its result; if it is a background run, /agy-stop can stop it.`,
+							},
+						],
+						details: emptyDetails(requestedModel, resolved.model),
 					};
 				}
+				lockAcquired = isContinuation;
+				if (lockAcquired) busyHandles.add(rawConvId as string);
+
+				const outcome = await runAgyProcess({
+					binary,
+					args,
+					cwd,
+					timeoutMin,
+					startAt: start,
+					details,
+					isContinuation,
+					snapshot,
+					background: false,
+					signal,
+					onPartial: onUpdate
+						? (text) => {
+								onUpdate({
+									content: [{ type: "text", text }],
+									details: { ...details, durationMs: Date.now() - start },
+								});
+							}
+						: undefined,
+					log,
+				});
 
-				if (outcome.exitCode !== 0) {
-					// stderr can carry auth material; the note is chat-visible.
-					const stderr = redactText(details.stderr.trim());
-					const note = stderr
-						? `agy exited with status ${outcome.exitCode}: ${stderr}`
-						: `agy exited with status ${outcome.exitCode}`;
-					return {
-						content: [{ type: "text", text: text ? `${text}\n\n[${note}]` : note }],
-						details,
-					};
+				const finalText = shapeFinalText(details, outcome, timeoutMin);
+
+				if (outcome.aborted || outcome.timedOut || outcome.exitCode !== 0) {
+					return { content: [{ type: "text", text: finalText }], details };
 				}
 
-				// Exit 0 with nothing on stdout is still a failure for the
-				// delegator: headless agy auto-denies a permission-gated tool call
-				// (e.g. the command gate in plan mode), prints the reason only to
-				// stderr, and ends cleanly. Falling through to the success path here
-				// returned just the conversation footer, which read as an empty
-				// success (silent-failure bug found 2026-09-25).
-				if (!text) {
-					details.empty = true;
-					const stderr = redactText(details.stderr.trim());
-					const note = [
-						"agy exited cleanly but produced no output.",
-						stderr ? `stderr: ${stderr}` : null,
-						"Common cause: a tool call needed a permission that headless mode cannot prompt for (typically the command gate in plan mode), so it was auto-denied and the turn ended with no answer. Recovery: retry in plan mode with all needed content inlined in the prompt - plan runs cannot fetch it, commands are denied. Or rerun outside plan mode with skipPermissions, or add your own permissions.allow rules in ~/.gemini/antigravity-cli/settings.json.",
-					]
-						.filter(Boolean)
-						.join(" ");
-					return { content: [{ type: "text", text: note }], details };
+				// Exit 0 with no output keeps its dedicated failure result
+				// (headless auto-deny); see shapeFinalText for the note.
+				if (!outcome.answerText) {
+					return { content: [{ type: "text", text: finalText }], details };
 				}
 
-				onUpdate?.({ content: [{ type: "text", text: "" }], details: { ...details } });
-				const footer = details.conversationId
-					? `\n\n[agy conversationId: ${details.conversationId} - pass as conversationId to continue this conversation]`
-					: "";
-				return { content: [{ type: "text", text: text + footer }], details };
+				// Clear the last partial status line (claude-bridge idiom) so the
+				// running-tail preview doesn't linger under the final answer.
+				onUpdate?.({
+					content: [{ type: "text", text: "" }],
+					details: { ...details },
+				});
+
+				return {
+					content: [{ type: "text", text: finalText }],
+					details,
+				};
 			} catch (err) {
-				if (statusInterval) clearInterval(statusInterval);
 				details.durationMs = Date.now() - start;
 				const msg = err instanceof Error ? err.message : String(err);
 				log?.("ask-fail", { error: msg, durationMs: details.durationMs }, "error");
 				return { content: [{ type: "text", text: `failed to run agy: ${msg}` }], details };
-			}
-			finally {
-				// Belt and braces: cleanup() already restores on close/error; this
-				// covers paths that never reached the process (sync spawn throw).
-				restoreBridge();
-				if (contextFile) {
-					try {
-						fs.unlinkSync(contextFile);
-					} catch {}
-				}
-				if (reviewerAgent) {
-					try {
-						fs.rmSync(reviewerAgent.dir, { recursive: true, force: true });
-					} catch {}
-				}
+			} finally {
+				if (lockAcquired) busyHandles.delete(rawConvId as string);
+				cleanupStaging();
 			}
 		},
 	});
@@ -857,6 +1190,9 @@ interface AgyDetails {
 	// Exit 0 with no answer on stdout (the empty-output failure branch).
 	// renderResult flips to the error glyph on it.
 	empty?: boolean;
+	// The call was refused before any spawn (validation, lock, cap, kill
+	// switch). renderResult flips to the error glyph on it.
+	refused?: boolean;
 	durationMs: number;
 	stderr: string;
 }
@@ -880,5 +1216,7 @@ function emptyDetails(
 		timedOut: false,
 		durationMs: 0,
 		stderr: "",
+		// Every emptyDetails caller is a refusal path.
+		refused: true,
 	};
 }

package/src/mcp-registration.ts

@@ -221,7 +221,12 @@ function bestEffortWriteMarker(file: string, marker: SuppressionMarker): void {
 	}
 }
 
-const suppressionRefs = new Map<string, number>();
+// Pi replaces the runtime on /new,/resume,/fork,/reload: module state dies
+// but globalThis survives within the process. The refcount must live there,
+// or an old runtime's late release re-enables entries under a new runtime's
+// live delegation.
+const SUPPRESSION_REFS_KEY = Symbol.for("pi-antigravity-bridge.suppression-refs");
+const suppressionRefs: Map<string, number> = ((globalThis as Record<symbol, unknown>)[SUPPRESSION_REFS_KEY] ??= new Map()) as Map<string, number>;
 
 /** Reference-counted suppression for a self-spawned agy process (AskAntigravity
  *  delegation). First acquire disables every pi-bridge-* entry AND records