@estebanforge/pi-ask-antigravity 1.2.10 → 1.2.12

package/extensions/index.ts

@@ -28,7 +28,7 @@
  *       so values containing spaces are not supported).
  */
 
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -45,17 +45,48 @@ import {
 import { Container, SettingsList, Text, type SettingItem } from "@earendil-works/pi-tui";
 import { contentText } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
+import {
+	BackgroundRunRegistry,
+	backgroundFlagText,
+	buildAgyArgs,
+	buildFinalPrompt,
+	buildTimeBudgetNotice,
+	MAX_TIMEOUT_MINUTES,
+	compareVersionsDesc,
+	CONVERSATIONS_DIR,
+	CONV_ID_RE,
+	configPaths,
+	createStopHandler,
+	createWakeSender,
+	DEFAULT_LINE_BUF_MAX_CHARS,
+	filterHiddenModels,
+	levelToTier,
+	loadLayeredRaw,
+	mergeCatalog,
+	newConversationId,
+	parseModelLine,
+	resolveAgyModel,
+	RunSpawnError,
+	runProcess,
+	saveLayeredConfig,
+	snapshotConversations,
+	summarizePrompt,
+	tryReadJson,
+	type Mode,
+	type ModelEntry,
+	type ResolvedModel,
+	type SaveResult,
+	type ThinkingTier,
+} from "@estebanforge/pi-ask-shared";
 
 // --- Constants -------------------------------------------------------------
 
 const DEFAULT_TIMEOUT_MIN = 10;
-const GRACE_AFTER_TIMEOUT_MS = 5000;
 const STATUS_INTERVAL_MS = 1000;
 const STATUS_TAIL_CHARS = 160;
 const DISCOVERY_TIMEOUT_MS = 8_000;
 const DISCOVERY_POLL_ATTEMPTS = 5;
 const DISCOVERY_POLL_MS = 100;
-const GLOBAL_CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "ask-antigravity.json");
 
 // renderCall / renderResult preview limits (match pi-claude-bridge).
 const PREVIEW_MAX_CHARS = 1000;
@@ -67,100 +98,23 @@ const DEFAULT_THINKING = "medium";
 // non-interactive -p mode (accept-edits auto-approves edits, NOT commands).
 const DEFAULT_SKIP_PERMISSIONS = true;
 
-// Per-family fallback tier when none is specified and no config default.
-// Flash defaults to medium (per spec); Pro only ships Low/High, so "latest
-// and greatest" = high.
-const FAMILY_DEFAULT_TIER: Record<Family, ThinkingTier> = {
-	flash: "medium",
-	pro: "high",
-	other: "medium",
-};
-
-const TIER_RANK: Record<ThinkingTier, number> = { low: 0, medium: 1, high: 2 };
-
-/** pi thinking-level vocabulary -> agy tier, for the thinking/effort tool
- *  params. Unknown values fall to low (agy always thinks something). */
-function levelToTier(level: string): ThinkingTier {
-	switch (level) {
-		case "minimal":
-		case "low":
-			return "low";
-		case "medium":
-			return "medium";
-		case "high":
-		case "xhigh":
-		case "max":
-			return "high";
-		default:
-			return "low";
-	}
-}
+// Per-family fallback tier, the pi->agy tier clamp (levelToTier), the static
+// alias overlay, and the line grammar now live in the shared peer adapter
+// (pi-ask-shared peers/antigravity.ts) alongside the argv builder and the
+// conversation-discovery technique, so pi-antigravity-bridge and pi-unblock
+// reuse the exact same resolution contract.
 
 // Mode = which agy tool-loop policy to apply. Distinct from the alias layer.
-//   "plan"         → --mode plan     (no edits; review-only — the skip-
-//                                      permissions flag is withheld in plan
-//                                      mode so the plan-approval gate holds)
+//   "plan"         → --mode plan     (review-shaped; NOT a security boundary:
+//                                      the CLI does not gate writes under
+//                                      plan, upstream #1181. The skip-
+//                                      permissions flag is still withheld so
+//                                      nothing runs auto-approved.)
 //   "accept-edits" → --mode accept-edits (agy applies edits)
 //
 // Note: agy's --sandbox flag is an orthogonal shell-containment setting
 // (not an "edit preview" mode), so it is not exposed here. Users who need
 // it can pass it via the AGY_EXTRA_ARGS env var.
-type Mode = "plan" | "accept-edits";
-
-// Static alias overlay for non-Gemini models agy may or may not surface in
-// `agy models` depending on plan. When the live catalog contains an entry
-// whose full string equals the overlay target, the live entry wins. When it
-// does not (older agy, missing model, plan gate), the overlay entry resolves
-// the alias so the user can still type "sonnet" and get a working answer.
-//   "sonnet"   -> claude-sonnet-5-5 (tiered low/medium/high like Gemini)
-//   "opus"     -> claude-opus-5-5 (tiered low/medium/high like Gemini)
-const STATIC_ALIAS_OVERLAY: ReadonlyArray<ModelEntry> = [
-	{ full: "claude-sonnet-5-5-low", family: "other", version: null, tier: "low" },
-	{ full: "claude-sonnet-5-5-medium", family: "other", version: null, tier: "medium" },
-	{ full: "claude-sonnet-5-5-high", family: "other", version: null, tier: "high" },
-	{ full: "claude-opus-5-5-low", family: "other", version: null, tier: "low" },
-	{ full: "claude-opus-5-5-medium", family: "other", version: null, tier: "medium" },
-	{ full: "claude-opus-5-5-high", family: "other", version: null, tier: "high" },
-];
-
-// Short alias → overlay full string. Used by resolveModel to recognize
-// friendly short names ("sonnet") that the family-parser (flash/pro) does
-// not match. The overlay entries are also merged into the live catalog for
-// exact-string passthrough, so this map only needs to cover the short names.
-const STATIC_SHORT_ALIAS: ReadonlyMap<string, string> = new Map([
-	["sonnet", "claude-sonnet-5-5"],
-	["opus", "claude-opus-5-5"],
-]);
-
-/** Families dropped outright even while `agy models` still lists them: the
- *  fixed-thinking single slug loses to the cheaper effort-tiered options and
- *  its removal upstream is already announced, so we stop offering it now. */
-const HIDDEN_FAMILY_RE = /^gpt-oss-/;
-
-/** Drop families we refuse to offer. Exported pure so tests exercise the
- *  same filter the live parse runs; discoverModels applies it per load. */
-export function filterHiddenModels(entries: ModelEntry[]): ModelEntry[] {
-	return entries.filter((e) => !HIDDEN_FAMILY_RE.test(e.full));
-}
-
-/** Merge the live catalog with the static alias overlay. Live entries win on
- *  case-insensitive full-string equality so an updated `agy models` listing
- *  always takes precedence over the hardcoded fallback. */
-export function mergeCatalog(live: ModelEntry[]): ModelEntry[] {
-	const seen = new Set(live.map((e) => e.full.toLowerCase()));
-	const merged = [...live];
-	for (const entry of STATIC_ALIAS_OVERLAY) {
-		if (!seen.has(entry.full.toLowerCase())) merged.push(entry);
-	}
-	return merged;
-}
-
-// agy conversation ids are UUID DB-stems (e.g. "9e6fdc2f-f9f9-4096-95fc-7852528b50cc").
-// Reject anything that isn't, so a leading-dash value can't misbind on agy's
-// arg parser as the token after --conversation. First char must be
-// alphanumeric (rejects leading-dash flag injection); hyphens allowed in the
-// body because real UUIDs contain them.
-const CONV_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/;
 
 const AGY_DESCRIPTION = `Delegate a self-contained sub-task to Google Antigravity. agy is the CLI for Gemini, so this tool is reached under three equivalent names the user may use interchangeably: **gemini**, **antigravity**, and **agy**. When the user says "ask gemini", "ask antigravity", "ask agy", or otherwise refers to any of these, call THIS tool. agy runs its OWN tool loop: it can read, write, edit, and execute inside the workspace, then returns its final answer. Use for a second opinion from a different model family, Gemini-specific reasoning, or isolated sub-tasks you do not need to drive step-by-step. Provide a complete, self-contained task description; agy will not see this conversation.
 
@@ -169,7 +123,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 — use for follow-ups, multi-turn refinement, or when the user says "ask agy to follow up / continue / now do X based on what you just did". Thread the id from each result into the next call.
 
 EXECUTION MODES (param: mode):
-- **plan**: agy reviews and plans without writing. Use for cross-review and read-only tasks. Enforced: plan runs execute in a temporary restricted agent whose toolset has NO file-editing tools (hard block); the reviewer may still execute arbitrary shell commands, kept read-only by the prompt guard alone. Inline the material to review - a plan run cannot fetch it.
+- **plan**: agy proposes a plan for review-shaped tasks. NOT a security boundary: the CLI does not gate writes under plan mode (upstream google-antigravity/antigravity-cli#1181, probed 2026-10-07: the write can execute in the same turn). The run additionally stages a temporary restricted agent whose toolset has no file-editing tools, as a damper, and the skip-permissions flag is never passed. Inline the material to review - a plan run cannot fetch it.
 - **accept-edits** (default): agy applies edits directly inside the workspace.
 - For agy's orthogonal \`--sandbox\` shell-containment flag, set the \`AGY_EXTRA_ARGS=--sandbox\` env var.
 
@@ -182,24 +136,9 @@ THINKING LEVEL (params: thinking, effort - SYNONYMS for one knob):
 
 // --- Types -----------------------------------------------------------------
 
-type ThinkingTier = "low" | "medium" | "high";
 type Family = "flash" | "pro" | "other";
 
-export interface ModelEntry {
-	full: string; // exact agy slug, e.g. "gemini-3.6-flash-medium"
-	family: Family;
-	version: string | null; // "3.6"
-	tier: ThinkingTier | null;
-}
-
-/** Argv-facing model resolution: the exact --model slug plus an optional
- *  --effort tier. Gemini bases split the tier out (the base slug alone is
- *  invalid without --effort); fixed-thinking families keep agy's exact slug
- *  and carry no effort. */
-export interface ResolvedModel {
-	model: string;
-	effort?: ThinkingTier;
-}
+// --- Config ----------------------------------------------------------------
 
 interface Config {
 	defaultModel: string;
@@ -209,41 +148,18 @@ interface Config {
 	skipPermissions: boolean;
 }
 
-// --- Version helpers -------------------------------------------------------
-
-/** Descending numeric version compare. "3.10" > "3.9" (lexical sort would
- *  wrongly rank "3.9" higher because '9' > '1'). */
-function compareVersionsDesc(a: string, b: string): number {
-	const pa = a.split(".").map(Number);
-	const pb = b.split(".").map(Number);
-	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-		const da = pa[i] ?? 0;
-		const db = pb[i] ?? 0;
-		if (da !== db) return db - da; // descending
-	}
-	return 0;
-}
-
-// --- Config ----------------------------------------------------------------
-
-function projectConfigPath(): string {
-	return path.join(process.cwd(), ".pi", "ask-antigravity.json");
-}
-
-function tryReadJson(filePath: string): Record<string, unknown> {
-	if (!fs.existsSync(filePath)) return {};
-	try {
-		const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"));
-		return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
-	} catch {
-		return {};
-	}
+/** Layered config paths: global is ~/.pi/agent (homedir, NOT getAgentDir —
+ *  today's shipped resolution for this extension); project is <cwd>/.pi. */
+function configPathsFor() {
+	return configPaths({
+		globalDir: path.join(os.homedir(), ".pi", "agent"),
+		projectDir: path.join(process.cwd(), ".pi"),
+		fileName: "ask-antigravity.json",
+	});
 }
 
 function loadConfig(): Config {
-	const global = tryReadJson(GLOBAL_CONFIG_PATH);
-	const project = tryReadJson(projectConfigPath());
-	const merged = { ...global, ...project };
+	const { merged } = loadLayeredRaw(configPathsFor());
 
 	const thinkingRaw = String(merged.defaultThinking ?? DEFAULT_THINKING).toLowerCase();
 	const thinking: ThinkingTier =
@@ -262,86 +178,19 @@ function loadConfig(): Config {
 	};
 }
 
-interface SaveResult {
-	path: string;
-	/** Keys whose effect is shadowed by a project config (info only). */
-	routedToProject: boolean;
-}
-
-/** Persist a config patch. If the project config already defines any patched
- *  key, write to the PROJECT file so the change actually takes effect
- *  (project shadows global on load); otherwise write to global.
- *  Atomic: temp file + rename, with temp cleanup on failure. */
+/** Persist a config patch via the shared all-or-nothing router: if any
+ *  patched key is already project-defined, the whole patch goes to the
+ *  project file (it shadows global on load). Atomic write inside. */
 function saveConfig(patch: Partial<Config>): SaveResult {
-	const projectRaw = tryReadJson(projectConfigPath());
-	const projectShadows = Object.keys(patch).some((k) => k in projectRaw);
-	const targetPath = projectShadows ? projectConfigPath() : GLOBAL_CONFIG_PATH;
-
-	const existing = tryReadJson(targetPath);
-	const next = { ...existing, ...patch };
-	const dir = path.dirname(targetPath);
-	fs.mkdirSync(dir, { recursive: true });
-
-	const tmp = `${targetPath}.${process.pid}.tmp`;
-	try {
-		fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
-		fs.renameSync(tmp, targetPath);
-	} catch (err) {
-		try {
-			fs.unlinkSync(tmp);
-		} catch {}
-		throw err;
-	}
-	return { path: targetPath, routedToProject: projectShadows };
+	return saveLayeredConfig(configPathsFor(), patch as Record<string, unknown>);
 }
 
-// --- Prompt assembly -------------------------------------------------------
-
-/** Appended to every headless plan-mode prompt. `agy -p` cannot answer
- *  permission prompts: in plan mode a run_command attempt is soft-denied and
- *  the turn ends AT the denial (exit 0, empty stdout, notice only on stderr -
- *  the empty-output branch in execute). Probed 2026-09-28 on agy 1.2.12:
- *  allow rules ARE consulted (a verbatim allow-listed `git log` runs), but
- *  --sandbox does NOT relax the command gate, so the only input every user
- *  is guaranteed is the prompt itself. The guard steers the model to answer
- *  from that material. accept-edits runs keep their tools and never get it. */
-export const PLAN_HEADLESS_GUARD = [
-	"",
-	"--- Headless session constraints ---",
-	"- Do not run shell commands. Command execution is denied in this session, and any attempt ends the session immediately with no answer.",
-	"- Work only from the material provided in this prompt.",
-	"- If information you need is missing, state exactly what is missing in your answer instead of trying to fetch it.",
-].join("\n");
-
-/** Guard for plan runs backed by the restricted reviewer agent. Difference
- *  to PLAN_HEADLESS_GUARD: commands are the analysis capability here (the
- *  agent's commandExecutionPolicy auto-approves them headless, probed
- *  2026-09-28), so the guard forbids FILE MUTATION - by tool or by shell -
- *  and keeps the answer-from-material discipline. */
-export const AGENT_REVIEW_GUARD = [
-	"",
-	"--- Review constraints ---",
-	"- Read-only review. Do not create, modify, or delete any files, including through shell commands (no redirects, tee, rm, mv, git commit).",
-	"- Read-only commands (git log, git diff, git show, rg, ls, cat, test runners) are allowed for analysis.",
-	"- Work from the material provided in this prompt; if information you need is missing, state exactly what is missing in your answer.",
-].join("\n");
-
-/** Assemble the prompt sent to agy: digest marker first (existing behavior),
- *  then the caller's prompt, then the plan-mode guard last - the position
- *  the model reads with the most recency. No user-config mutation: this is
- *  the only plan-mode lever the tool itself owns. */
-export function buildFinalPrompt(
-	prompt: string,
-	mode: Mode,
-	digest: boolean,
-	/** True when the restricted reviewer agent is staged: its empty edit
-	 *  toolset is the hard block, so the prompt may ALLOW read-only commands. */
-	agentEnforced = false,
-): string {
-	let out = digest ? `(Use compact digests, not full file contents.)\n${prompt}` : prompt;
-	if (mode === "plan") out += agentEnforced ? AGENT_REVIEW_GUARD : PLAN_HEADLESS_GUARD;
-	return out;
-}
+// --- Prompt assembly: shared peer adapter ----------------------------------
+// The plan-mode guards (PLAN_HEADLESS_GUARD / AGENT_REVIEW_GUARD) and the
+// prompt assembler (buildFinalPrompt) live in pi-ask-shared
+// (peers/antigravity.ts) so the bridge's ask-tool and pi-unblock consults
+// inherit the identical guard discipline.
+export { AGENT_REVIEW_GUARD, PLAN_HEADLESS_GUARD } from "@estebanforge/pi-ask-shared";
 
 // --- Plan-mode reviewer agent ----------------------------------------------
 
@@ -354,12 +203,12 @@ export function askAgentsRoot(): string {
 	return process.env.AGY_AGENTS_ROOT ?? path.join(os.homedir(), ".gemini", "config", "agents");
 }
 
-/** agent.md for the plan-mode reviewer. The tools list is the ENFORCEMENT:
- *  with no file-editing tool present the model cannot emit an edit call at
- *  all (probed 2026-09-28 on agy 1.2.12: the toolset reports "none" for
- *  edits, with and without the skip flag). commandExecutionPolicy auto is
- *  what lets read commands run headless with no user allow rules. Never add
- *  a write-capable tool here. */
+/** agent.md for the plan-mode reviewer. The tools list is a damper, not
+ *  enforcement: with no file-editing tool present the model cannot emit an
+ *  edit call through the agent toolset, but the CLI does not enforce
+ *  review-only (upstream #1181 - writes bypass the permission system and
+ *  the toolset is not honored reliably on 1.3.x). Prefer view_file for
+ *  reads here too. Never add a write-capable tool. */
 export function reviewerAgentMd(name: string): string {
 	return [
 		"---",
@@ -439,204 +288,10 @@ function pidAlive(pid: number): boolean {
 	}
 }
 
-// --- Model parsing + alias resolution --------------------------------------
-
-/** Parse one `agy models` line into a structured entry. */
-export function parseModelLine(line: string): ModelEntry | null {
-	// agy prints TWO columns: "<slug>  <display label>". --model takes only the
-	// slug (col 1), so split it off; the label is display-only. A bare-slug line
-	// (no whitespace) splits to itself.
-	const full = line.trim().split(/\s+/)[0] ?? "";
-	if (!full) return null;
-
-	const lower = full.toLowerCase();
-	const family: Family = lower.includes("flash")
-		? "flash"
-		: lower.includes("pro")
-			? "pro"
-			: "other";
-
-	const versionMatch = lower.match(/(\d+\.\d+)/);
-	const version = versionMatch ? versionMatch[1] : null;
-
-	const tierMatch = lower.match(/-(low|medium|high)$/);
-	const tier = tierMatch ? (tierMatch[1] as ThinkingTier) : null;
-
-	return { full, family, version, tier };
-}
-
-/** Pick the available tier closest in rank to the preferred one. Distance
- *  ties (e.g. Low/High around Medium) break toward the higher tier so
- *  "latest and greatest" wins when a family lacks the requested tier. */
-function nearestTier(available: ThinkingTier[], preferred: ThinkingTier): ThinkingTier {
-	if (available.includes(preferred)) return preferred;
-	const sorted = [...available].sort((a, b) => {
-		const da = Math.abs(TIER_RANK[a] - TIER_RANK[preferred]);
-		const db = Math.abs(TIER_RANK[b] - TIER_RANK[preferred]);
-		return da !== db ? da - db : TIER_RANK[b] - TIER_RANK[a];
-	});
-	return sorted[0] ?? preferred;
-}
-
-/** Build the argv-facing resolution from a picked catalog entry. Gemini and
- *  Claude bases (slugs starting "gemini-"/"claude-") accept a separate
- *  --effort, so split the tier suffix out of the slug: the base alone
- *  (claude-sonnet-5-5) is what --model wants, and the tier goes to --effort
- *  (agy rejects a bare base: "requires --effort"). Only unverified families
- *  keep agy's exact slug whole, so an unknown suffix can never trigger an
- *  unsupported --effort. */
-function toResolved(full: string, tier: ThinkingTier | null): ResolvedModel {
-	if (tier && /^(gemini|claude)-/.test(full.toLowerCase())) {
-		return { model: full.replace(/-(low|medium|high)$/, ""), effort: tier };
-	}
-	return { model: full };
-}
-
-/** Resolve a tiered base id - a short-alias target ("claude-sonnet-5-5") or a
- *  bare base slug the provider itself advertises - to the catalog variant
- *  nearest the requested tier. A bare base alone is invalid upstream
- *  ("requires --effort"), so the pick always rides the split in toResolved;
- *  with no variants in the catalog, the overlay/exact entry or the raw base
- *  passes through unchanged. */
-function resolveTieredBase(
-	base: string,
-	entries: ModelEntry[],
-	defaultThinking: ThinkingTier,
-	preferredTier: ThinkingTier | undefined,
-): ResolvedModel {
-	const needle = base.toLowerCase();
-	const variants = entries.filter((e) => e.full.toLowerCase().startsWith(`${needle}-`));
-	if (variants.length > 0) {
-		const tiers = variants.map((e) => e.tier).filter((t): t is ThinkingTier => t !== null);
-		const preferred =
-			preferredTier ??
-			(tiers.includes(defaultThinking) ? defaultThinking : FAMILY_DEFAULT_TIER.other);
-		const chosen = nearestTier(tiers, preferred);
-		const picked = variants.find((e) => e.tier === chosen) ?? variants[0];
-		return toResolved(picked.full, picked.tier);
-	}
-	const fromCatalog = entries.find((e) => e.full.toLowerCase() === needle);
-	return toResolved(fromCatalog?.full ?? base, fromCatalog?.tier ?? null);
-}
-
-/**
- * Resolve a friendly alias / partial name to an argv-facing {model, effort?}.
- * Returns null only when the family is unrecognized; the caller then passes
- * the raw input straight to agy.
- */
-export function resolveModel(
-	input: string,
-	entries: ModelEntry[],
-	defaultThinking: ThinkingTier,
-	/** Explicit thinking param (thinking/effort). Beats a tier embedded in
-	 *  the alias ("flash high") and the configured default; clamped to the
-	 *  family's real tiers, ignored for fixed-thinking families. */
-	preferredTier?: ThinkingTier,
-): ResolvedModel | null {
-	const lower = input.toLowerCase().trim();
-
-	// 1. Exact full-string match (case-insensitive).
-	const exact = entries.find((e) => e.full.toLowerCase() === lower);
-	if (exact) return toResolved(exact.full, exact.tier);
-
-	// 1b. Static short alias ("sonnet" / "opus"). Checked
-	//     before the family parser because none of these names contain
-	//     "flash" or "pro" and would otherwise return null below. The
-	//     resolved full string is then re-validated against the catalog
-	//     in step 1's second pass on the next call, so renaming the
-	//     overlay entry in code still wins on exact-string match.
-	//     The case-insensitive lookup matches mergeCatalog's dedup logic
-	//     so the "live entries win" guarantee holds even when agy lists
-	//     the model under different casing than the overlay.
-	if (STATIC_SHORT_ALIAS.has(lower)) {
-		return resolveTieredBase(
-			STATIC_SHORT_ALIAS.get(lower) as string,
-			entries,
-			defaultThinking,
-			preferredTier,
-		);
-	}
-
-	// 2. Parse the alias.
-	let family: Family | null = lower.includes("flash")
-		? "flash"
-		: lower.includes("pro")
-			? "pro"
-			: null;
-	const versionMatch = lower.match(/(\d+\.\d+)/);
-	const version = versionMatch ? versionMatch[1] : null;
-	const tierMatch = lower.match(/\b(low|medium|high)\b/);
-	const tier = tierMatch ? (tierMatch[1] as ThinkingTier) : null;
-
-	// "gemini" alone, "default", or empty -> default family (flash).
-	if (!family && (/gemini/.test(lower) || lower === "" || lower === "default")) {
-		family = "flash";
-	}
-	if (!family) {
-		// A bare base slug the provider itself advertises ("claude-sonnet-5-5",
-		// the id behind the antigravity/ entry in pi's picker) is invalid
-		// upstream without an effort: resolve it to the nearest tier variant
-		// exactly like the short aliases.
-		if (
-			entries.some((e) => e.full.toLowerCase().startsWith(`${lower}-`)) ||
-			entries.some((e) => e.full.toLowerCase() === lower)
-		) {
-			return resolveTieredBase(lower, entries, defaultThinking, preferredTier);
-		}
-		return null; // unknown family -> let agy handle it
-	}
-
-	// 3. Filter by family.
-	let candidates = entries.filter((e) => e.family === family);
-	if (candidates.length === 0) return null;
-
-	// 4. Pin version if specified; otherwise pick the HIGHEST version
-	//    (numeric compare, not lexical — see compareVersionsDesc).
-	if (version) {
-		const versioned = candidates.filter((e) => e.version === version);
-		if (versioned.length > 0) candidates = versioned;
-	} else {
-		// Prefer Google's official `gemini-*-latest` aliases (entries with no
-		// parseable version in their name, e.g. "Gemini Flash Latest") when
-		// the user did NOT pin a specific version. The alias is the
-		// versionless pointer Google intends for "the current release" and
-		// hot-swaps on every release, while versioned entries like
-		// "Gemini 3.6 Flash (Medium)" stay available via explicit pinning
-		// (e.g. "3.6 flash medium"). Falls back to the highest versioned
-		// entry if no alias is present in the catalog.
-		const aliases = candidates.filter((e) => e.version === null);
-		if (aliases.length > 0) {
-			candidates = aliases;
-		} else {
-			const versions = candidates
-				.map((e) => e.version)
-				.filter((v): v is string => v !== null)
-				.sort(compareVersionsDesc);
-			if (versions.length > 0) {
-				const top = versions[0];
-				const latest = candidates.filter((e) => e.version === top);
-				if (latest.length > 0) candidates = latest;
-			}
-		}
-	}
-
-	// 5. Pick tier: explicit > config default (if the family offers it) >
-	//    family default. Pro has no Medium, so "pro" + default medium falls
-	//    back to the Pro family default (High), not nearest-Medium.
-	const familyTiers = new Set(
-		candidates.map((e) => e.tier).filter((t): t is ThinkingTier => t !== null),
-	);
-	if (familyTiers.size === 0) return toResolved(candidates[0].full, null); // no tiers on any entry
-
-	const preferred =
-		preferredTier ??
-		tier ??
-		(familyTiers.has(defaultThinking) ? defaultThinking : FAMILY_DEFAULT_TIER[family]);
-	const chosenTier = nearestTier([...familyTiers], preferred);
-	const picked = candidates.find((e) => e.tier === chosenTier) ?? candidates[0];
-	return toResolved(picked.full, picked.tier);
-}
-
+// --- Model parsing + alias resolution: shared peer adapter ---------------
+// parseModelLine, the tier ladder, and resolveModel (family/version/tier
+// resolution incl. the static sonnet/opus overlay) live in pi-ask-shared
+// (peers/antigravity.ts); discoverModels below feeds them the live catalog.
 // --- agy process helpers ---------------------------------------------------
 
 function resolveAgy(): string {
@@ -738,150 +393,10 @@ function extraArgs(): string[] {
 	return raw ? raw.split(/\s+/).filter((s) => s.length > 0) : [];
 }
 
-// --- Conversation discovery (the one technique borrowed from antigravity-acp) --
-// agy -p does NOT print the conversation id, so for a fresh prompt we snapshot
-// the conversations dir before spawn and pick the single new .db after. For a
-// continued call we pass --conversation <id> and agy reuses it (no new file).
-
-const CONVERSATIONS_DIR =
-	process.env.AGY_CONVERSATIONS_DIR ||
-	path.join(os.homedir(), ".gemini", "antigravity-cli", "conversations");
-
-/** Snapshot the set of conversation ids (*.db stems) currently on disk. */
-function snapshotConversations(dir: string): Set<string> {
-	const out = new Set<string>();
-	let entries: string[];
-	try {
-		entries = fs.readdirSync(dir);
-	} catch {
-		return out;
-	}
-	for (const f of entries) {
-		if (f.endsWith(".db")) out.add(f.slice(0, -3));
-	}
-	return out;
-}
-
-/** Resolve which of the `candidates` DB ids is held open by the process tree
- *  rooted at `rootPid`. Used to disambiguate concurrent agy runs. Returns the
- *  single matching id, or null when none/several are open or /proc is
- *  unavailable. Ported from pi-antigravity-bridge src/discovery.ts; keep in
- *  sync. */
-type OpenDbResolver = (
-	rootPid: number,
-	dir: string,
-	candidates: Set<string>,
-) => string | null;
-
-function readProcStat(pid: number): { pid: number; ppid: number } | null {
-	let raw: string;
-	try {
-		raw = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
-	} catch {
-		return null;
-	}
-	const closeParen = raw.lastIndexOf(")");
-	if (closeParen < 0) return null;
-	const fields = raw.slice(closeParen + 2).trim().split(/\s+/);
-	const ppid = Number(fields[1]);
-	if (!Number.isFinite(ppid)) return null;
-	return { pid, ppid };
-}
-
-function collectDescendants(rootPid: number): Set<number> {
-	const out = new Set<number>([rootPid]);
-	let entries: string[];
-	try {
-		entries = fs.readdirSync("/proc");
-	} catch {
-		return out;
-	}
-	const ppidOf = new Map<number, number>();
-	for (const e of entries) {
-		if (!/^\d+$/.test(e)) continue;
-		const s = readProcStat(Number(e));
-		if (s) ppidOf.set(s.pid, s.ppid);
-	}
-	let changed = true;
-	while (changed) {
-		changed = false;
-		for (const [pid, ppid] of ppidOf) {
-			if (out.has(pid)) continue;
-			if (out.has(ppid)) {
-				out.add(pid);
-				changed = true;
-			}
-		}
-	}
-	return out;
-}
-
-function safeRealpath(p: string): string | null {
-	try {
-		return fs.realpathSync(p);
-	} catch {
-		return null;
-	}
-}
-
-const procTreeOpenDbResolver: OpenDbResolver = (rootPid, dir, candidates) => {
-	if (candidates.size <= 1) return null;
-	if (process.platform !== "linux") return null;
-	const dirResolved = safeRealpath(dir);
-	const tree = collectDescendants(rootPid);
-	const found = new Set<string>();
-	for (const pid of tree) {
-		let fds: string[];
-		try {
-			fds = fs.readdirSync(`/proc/${pid}/fd`);
-		} catch {
-			continue;
-		}
-		for (const fd of fds) {
-			let target: string;
-			try {
-				target = fs.readlinkSync(`/proc/${pid}/fd/${fd}`);
-			} catch {
-				continue;
-		}
-			const base = path.basename(target);
-			if (!base.endsWith(".db")) continue;
-			if (dirResolved && safeRealpath(path.dirname(target)) !== dirResolved) continue;
-			const id = base.slice(0, -3);
-			if (candidates.has(id)) found.add(id);
-		}
-	}
-	if (found.size === 1) return [...found][0] ?? null;
-	return null;
-};
-
-interface BindOptions {
-	pid?: number;
-	resolveOpenDb?: OpenDbResolver;
-}
-
-/** Find the conversation id created since `before`. Returns null when none
- *  appeared, or when several appeared and we cannot tie one to our process.
- *  Pass `opts.pid` (the spawned agy) to enable concurrent-run disambiguation
- *  via the process-tree FD scan. */
-function newConversationId(
-	dir: string,
-	before: Set<string>,
-	opts: BindOptions = {},
-): string | null {
-	const created = [...snapshotConversations(dir)].filter((id) => !before.has(id));
-	if (created.length === 0) return null;
-	if (created.length === 1) return created[0] ?? null;
-	// Ambiguous: try to authoritatively identify ours via the spawned
-	// process's open files. Fail safe to null when we can't pick exactly one.
-	if (opts.pid !== undefined) {
-		const resolve = opts.resolveOpenDb ?? procTreeOpenDbResolver;
-		const hit = resolve(opts.pid, dir, new Set(created));
-		if (hit && created.includes(hit)) return hit;
-	}
-	return null;
-}
-
+// --- Conversation discovery: shared peer adapter ---------------------------
+// The .db snapshot / new-id pick / /proc FD disambiguation technique lives
+// in pi-ask-shared (peers/antigravity.ts): snapshotConversations +
+// newConversationId. CONVERSATIONS_DIR (env-overridable) is exported there.
 // --- Full-context export (opt-in includeContext) --------------------------
 // NOTE: duplicated per pi-ask-* package (each is self-contained). Duck-typed
 // over role/content to tolerate AgentMessage's union + custom message types.
@@ -968,6 +483,207 @@ interface AgyDetails {
 	stderr: string;
 }
 
+
+// --- Background-mode plumbing ----------------------------------------------
+// Shared shape for both call styles: blocking awaits it, background lets it
+// run detached and pushes the outcome through the wake sender on close.
+
+const STDOUT_BUF_MAX_CHARS = 1_000_000;
+
+/** Spawn failure (binary vanished between resolve and spawn). */
+class AgySpawnError extends Error {}
+
+interface ProcessRunOptions {
+	binary: string;
+	args: string[];
+	workdir: string;
+	timeoutMin: number;
+	startAt: number;
+	/** Mutated in place: conversationId discovery, stderr, durationMs. */
+	details: AgyDetails;
+	isContinuation: boolean;
+	snapshot: ReturnType<typeof snapshotConversations> | null;
+	/** 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 plus the live child
+	 *  handle (pid for the FD-disambiguation poll) as soon as the child exists. */
+	onSpawn?: (kill: () => void, proc: ChildProcess) => void;
+}
+
+interface ProcessRunOutcome {
+	exitCode: number;
+	aborted: boolean;
+	timedOut: boolean;
+	/** Full stdout, trimmed. Empty means the headless auto-deny failure mode. */
+	answerText: string;
+}
+
+/** Tool-result shape this extension returns; keeps the background helper's literals narrow. */
+interface AskToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: AgyDetails;
+}
+
+/**
+ * Spawns agy -p, accumulates stdout, runs conversation-id discovery (during
+ * the run via the /proc FD resolver, then the post-exit scan fallback), and
+ * resolves when the process tree closes.
+ */
+async function runAgyProcess(opts: ProcessRunOptions): Promise<ProcessRunOutcome> {
+	const { binary, args, workdir, timeoutMin, startAt, details, isContinuation, snapshot, signal, onPartial, onSpawn } = opts;
+	let out = "";
+
+	const statusInterval = onPartial
+		? setInterval(() => {
+				const elapsed = Math.floor((Date.now() - startAt) / 1000);
+				const tail = out.slice(-STATUS_TAIL_CHARS);
+				const text = tail ? `(running ${elapsed}s)\n…${tail}` : `(running ${elapsed}s)`;
+				onPartial(text);
+			}, STATUS_INTERVAL_MS)
+		: null;
+
+	try {
+		// Concurrent bind poll: while agy is ALIVE, the pid-based /proc FD
+		// resolver can disambiguate when a concurrent agy also drops a new
+		// .db. runProcess hands us the kill switch plus the spawned process
+		// through onSpawn; the pid is only useful while the tree lives, and
+		// the post-exit scan below is the fallback once it is gone.
+		let bindDuringRun: Promise<void> = Promise.resolve();
+
+		const outcome = await runProcess({
+			binary,
+			args,
+			cwd: workdir,
+			timeoutMs: timeoutMin * 60_000,
+			signal,
+			// Raw chunks stream live so the status tail matches the old
+			// during-run accumulation. The 1MB valve lives in runProcess for
+			// stdoutRaw; this accumulator applies the original's own valve
+			// (past 1MB, keep the last 100k) so a pathological stream cannot
+			// balloon memory through the live tail.
+			onChunk: (chunk) => {
+				out += chunk;
+				if (out.length > DEFAULT_LINE_BUF_MAX_CHARS) out = out.slice(-100_000);
+			},
+			onSpawn: (kill, proc) => {
+				// Hand the kill switch to the background registry first, then
+				// start the bind poll against the live pid.
+				onSpawn?.(kill, proc);
+				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 */
+					});
+				}
+			},
+		});
+
+		if (statusInterval) clearInterval(statusInterval);
+
+		// Let the during-run bind poll finish (it bails immediately once agy
+		// has exited, so this rarely blocks).
+		await bindDuringRun;
+
+		// stderr feeds notes and wake messages, not forensics; runProcess
+		// applies the same 64k cap the inline accumulator used to.
+		details.stderr = outcome.stderr;
+		details.exitCode = outcome.exitCode;
+		details.aborted = outcome.aborted;
+		details.timedOut = outcome.timedOut;
+		details.durationMs = Date.now() - startAt;
+
+		// For a fresh run, discover the conversation id agy just created
+		// (agy -p never prints it). Retry briefly since agy may flush its
+		// SQLite DB a moment after the process closes. A continuation run
+		// reuses the provided id (already set on details).
+		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);
+			}
+		}
+
+		return { ...outcome, answerText: out.trim() };
+	} catch (err) {
+		// Preserve the extension's spawn-error contract (fixed message).
+		if (err instanceof RunSpawnError) throw new AgySpawnError("failed to spawn agy");
+		throw err;
+	} finally {
+		if (statusInterval) clearInterval(statusInterval);
+	}
+}
+
+/**
+ * Builds the user/model-facing answer text for every terminal outcome.
+ * Pure except the empty-output marker it stamps on details.
+ */
+function shapeFinalText(details: AgyDetails, outcome: ProcessRunOutcome, timeoutMin: number): string {
+	const text = outcome.answerText;
+
+	// Aborted: a distinct result so the caller knows it was cancelled, not a silent success.
+	if (outcome.aborted) {
+		return text ? `agy was aborted. Partial output:\n\n${text}` : "agy was aborted before producing output.";
+	}
+
+	// Timeout: distinct from a genuine non-zero exit (the watchdog
+	// killed the tree because the configured cap elapsed).
+	if (outcome.timedOut) {
+		const note = `agy exceeded the ${timeoutMin}m timeout and was killed`;
+		return text ? `${text}\n\n[${note}]` : note;
+	}
+
+	// Non-zero exit: surface the failure even when partial text exists.
+	if (outcome.exitCode !== 0) {
+		const note = details.stderr.trim()
+			? `agy exited with status ${outcome.exitCode}: ${details.stderr.trim()}`
+			: `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
+	// caller: 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 note = [
+			"agy exited cleanly but produced no output.",
+			details.stderr.trim() ? `stderr: ${details.stderr.trim()}` : 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;
+	}
+
+	// Success. Conversation footer lets the orchestrating model thread the id.
+	const footer = details.conversationId
+		? `\n\n[agy conversationId: ${details.conversationId} — pass as conversationId to continue this conversation]`
+		: "";
+
+	return text + footer;
+}
+
 export default async function (pi: ExtensionAPI) {
 	// If pi-antigravity-bridge is installed, it owns the AskAntigravity tool
 	// (and the provider). Stay silent and register nothing to avoid a
@@ -991,6 +707,43 @@ export default async function (pi: ExtensionAPI) {
 	// aliases resolve even when agy doesn't surface them in the live catalog.
 	const discovered = mergeCatalog(await discoverModels(binary).catch(() => []));
 
+	// --- Background-run state (one set per extension 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, documented in the README.
+	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 finally.
+	const cleanups = new Map<string, () => void>();
+	// One background 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>();
+	const sendWake = createWakeSender(pi, {
+		customType: "ask-antigravity-result",
+		isDisposed: () => registry.isDisposed(),
+	});
+	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",
+			}),
+	});
+	pi.on("session_shutdown", () => {
+		// Latch first so close-handler wakes stay silent, then kill children,
+		// then sweep staged artifacts (hard exit would skip the close-path cleanup).
+		for (const run of registry.dispose()) kills.get(run.runId)?.();
+		for (const fn of cleanups.values()) fn();
+		cleanups.clear();
+		kills.clear();
+	});
+
 	// --- /agy: view / change default model + thinking ---------------------
 
 	// Friendly model options offered in the picker. Exact strings also work
@@ -1012,7 +765,7 @@ export default async function (pi: ExtensionAPI) {
 						`  defaultModel:    ${config.defaultModel}`,
 						`  defaultThinking: ${config.defaultThinking}`,
 						`  permissions:     ${config.skipPermissions ? "auto-approved" : "prompt"}`,
-						`  resolved:        ${resolveModel(config.defaultModel, discovered, config.defaultThinking)?.model ?? "(agy default)"}`,
+						`  resolved:        ${resolveAgyModel(config.defaultModel, discovered, config.defaultThinking)?.model ?? "(agy default)"}`,
 						``,
 						`Edit: ~/.pi/agent/ask-antigravity.json`,
 					].join("\n"),
@@ -1023,7 +776,7 @@ export default async function (pi: ExtensionAPI) {
 
 			// Resolve the display string for the current default model.
 			const currentResolved =
-				resolveModel(config.defaultModel, discovered, config.defaultThinking)?.model ?? config.defaultModel;
+				resolveAgyModel(config.defaultModel, discovered, config.defaultThinking)?.model ?? config.defaultModel;
 
 			const items: SettingItem[] = [
 				{
@@ -1033,7 +786,7 @@ export default async function (pi: ExtensionAPI) {
 						"Friendly alias resolved to the latest matching agy model. 'flash' = latest Flash, 'pro' = latest Pro, 'gemini' = latest Flash.",
 					currentValue: `${config.defaultModel} → ${currentResolved}`,
 					values: MODEL_OPTIONS.map((m) => {
-						const r = resolveModel(m, discovered, config.defaultThinking)?.model ?? m;
+						const r = resolveAgyModel(m, discovered, config.defaultThinking)?.model ?? m;
 						return `${m} → ${r}`;
 					}),
 				},
@@ -1161,7 +914,7 @@ export default async function (pi: ExtensionAPI) {
 					],
 					{
 						description:
-							"agy execution mode. 'plan' = review-only (--mode plan in a temporary restricted agent: file-editing tools are hard-blocked; arbitrary shell commands remain prompt-guarded only; with skipPermissions on, commands still run for analysis). 'accept-edits' = agy applies edits directly (--mode accept-edits, default). For agy's orthogonal --sandbox shell-containment flag, set the AGY_EXTRA_ARGS env var.",
+							"agy execution mode. 'plan' = plan-shaped run: the CLI does not enforce review-only (see the tool description); the staged reviewer agent's toolset omits file-editing tools as a damper, and the skip-permissions flag is never passed. 'accept-edits' = agy applies edits directly (--mode accept-edits, default). For agy's orthogonal --sandbox shell-containment flag, set the AGY_EXTRA_ARGS env var.",
 						default: "accept-edits",
 					},
 				),
@@ -1180,7 +933,7 @@ export default async function (pi: ExtensionAPI) {
 			),
 			timeoutMinutes: Type.Optional(
 				Type.Number({
-					description: `Hard cap on the agy run in minutes. Default ${DEFAULT_TIMEOUT_MIN}.`,
+					description: `Hard cap on the agy run in minutes. Default ${DEFAULT_TIMEOUT_MIN}. Fractional minutes allowed; must be above 0 and at most ${MAX_TIMEOUT_MINUTES}. The prompt carries a matching [TIME BUDGET] notice.`,
 				}),
 			),
 			includeContext: Type.Optional(
@@ -1189,6 +942,12 @@ export default async function (pi: ExtensionAPI) {
 						"When true, export the current pi conversation (resolved, as markdown) to a temp file inside the workspace and tell agy to read it first. Default false (isolated one-shot). Opt in only when the user explicitly wants agy to see the full conversation; it costs agy tokens to read.",
 				}),
 			),
+			background: Type.Optional(
+				Type.Boolean({
+					description: backgroundFlagText("conversationId"),
+					default: false,
+				}),
+			),
 		}),
 		renderCall(args, theme, _context) {
 			// Show RESOLVED model/thinking/mode (config defaults applied) so the
@@ -1198,8 +957,8 @@ export default async function (pi: ExtensionAPI) {
 			const cfg = loadConfig();
 			const requestedModel = (args.model as string | undefined)?.trim() || cfg.defaultModel;
 			const thinkingArg = (args.thinking as string | undefined) ?? (args.effort as string | undefined);
-			const resolved =
-				resolveModel(
+			const resolved: ResolvedModel =
+				resolveAgyModel(
 					requestedModel,
 					discovered,
 					cfg.defaultThinking,
@@ -1216,6 +975,7 @@ export default async function (pi: ExtensionAPI) {
 			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(", ")}]`)} `;
@@ -1325,8 +1085,8 @@ export default async function (pi: ExtensionAPI) {
 				};
 			}
 			const thinkingArg = (params.thinking as string | undefined) ?? (params.effort as string | undefined);
-			const resolved =
-				resolveModel(
+			const resolved: ResolvedModel =
+				resolveAgyModel(
 					requestedModel,
 					discovered,
 					config.defaultThinking,
@@ -1355,6 +1115,14 @@ export default async function (pi: ExtensionAPI) {
 			}
 
 			const timeoutMin = params.timeoutMinutes ?? DEFAULT_TIMEOUT_MIN;
+			if (!(timeoutMin > 0 && Number.isFinite(timeoutMin) && timeoutMin <= MAX_TIMEOUT_MINUTES)) {
+				// timeoutMinutes: 0 would arm runProcess's watchdog with a 0ms
+				// timeout (Node clamps to 1ms) and kill the peer instantly.
+				return {
+					content: [{ type: "text", text: `timeoutMinutes must be a positive number of minutes up to ${MAX_TIMEOUT_MINUTES} (for example 0.5 for 30 seconds).` }],
+					details: emptyDetails(requestedModel, resolved.model),
+				};
+			}
 
 			// Continuity: if a conversationId is provided AND validates as an agy
 			// id (UUID-ish DB stem, never a leading-dash flag), resume it; otherwise
@@ -1370,10 +1138,11 @@ export default async function (pi: ExtensionAPI) {
 
 			const mode: Mode = (params.mode as Mode | undefined) ?? "accept-edits";
 			// Plan runs stage a restricted reviewer agent: its tools list has NO
-			// file-editing tool, which is the hard edit block (the prompt guard
-			// alone was observed failing once - a sub-agent still edited files).
-			// Staging failure degrades to the legacy fallback: no agent, no skip
-			// flag, the stricter command-forbidding guard.
+			// file-editing tool, a toolset-level damper on edits (the prompt
+			// guard alone was observed failing once - a sub-agent still edited
+			// files; the CLI itself does not enforce review-only, upstream
+			// #1181). Staging failure degrades to the legacy fallback: no agent,
+			// no skip flag, the stricter command-forbidding guard.
 			let reviewerAgent: { name: string; dir: string } | null = null;
 			if (mode === "plan") {
 				try {
@@ -1382,15 +1151,20 @@ export default async function (pi: ExtensionAPI) {
 					reviewerAgent = null;
 				}
 			}
-			// digest default: on for plan (review-only contexts where full file
+			// digest default: on for plan (review-shaped contexts where full file
 			// contents are noise), off for accept-edits (agy applies edits and
 			// may need richer context for diffs).
 			const useDigest: boolean =
 				typeof params.digest === "boolean"
 					? params.digest
 					: mode === "plan";
+			// Budget notice into the prompt BEFORE buildFinalPrompt: the plan-mode
+			// guard banners must stay the final text (last-read recency), so the
+			// notice can't go after them. The builder itself stays notice-free so
+			// callers can't double-wrap.
+			const budget = buildTimeBudgetNotice(timeoutMin * 60_000);
 			const finalPrompt: string = buildFinalPrompt(
-				params.prompt,
+				budget ? `${params.prompt}\n\n${budget}` : params.prompt,
 				mode,
 				useDigest,
 				reviewerAgent !== null,
@@ -1419,37 +1193,20 @@ export default async function (pi: ExtensionAPI) {
 				? `The full pi conversation context (as markdown) is at: ${contextFile}\nRead that file first for context, then do the task below.\n\n---\n\n${finalPrompt}`
 				: finalPrompt;
 
-			const args: string[] = ["--add-dir", cwd];
-			const extraRaw = extraArgs();
-			// Fail-closed on the fallback path: AGY_EXTRA_ARGS lands before the
-			// mode flags, so an env-injected skip flag would re-arm what the
-			// plan-mode rule strips. Only the enforced agent makes the flag safe.
-			const extra =
-				mode === "plan" && !reviewerAgent
-					? extraRaw.filter((a) => a !== "--dangerously-skip-permissions")
-					: extraRaw;
-			if (extra.length) args.push(...extra);
-			if (resolved.model) args.push("--model", resolved.model);
-			if (resolved.effort) args.push("--effort", resolved.effort);
-			args.push("--mode", mode);
-			if (reviewerAgent) args.push("--agent", reviewerAgent.name);
-			// accept-edits auto-approves file edits but NOT shell commands, so a
-			// run_command would hang on an unanswerable y/n prompt in non-interactive
-			// -p mode. Honor the shared permissions setting (same knob as the bridge).
-			// Plan runs WITH the reviewer agent: the flag is safe again because the
-			// agent's toolset has no file-editing tool - the 2026-09-25 write
-			// incident rode edit tools that existed then; probed 2026-09-28 the
-			// restricted toolset reports "none" for edits even with the flag. The
-			// flag is what lets analysis commands (builds, test runners) run for
-			// users without allow rules. Plan fallback (staging failed): strict
-			// legacy behavior, no flag - the prompt guard is all that is left.
-			if (config.skipPermissions && (mode !== "plan" || reviewerAgent !== null)) {
-				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());
-			args.push("-p", effectivePrompt);
+			// Build argv via the shared peer adapter (see buildAgyArgs there for
+			// the flag-order contract and the fail-closed plan-run rules).
+			const args = buildAgyArgs({
+				cwd,
+				resolved,
+				mode,
+				reviewerAgentName: reviewerAgent?.name ?? null,
+				skipPermissions: config.skipPermissions,
+				conversationId: isContinuation ? (rawConvId as string) : null,
+				timeoutMinutes: timeoutMin,
+				addDirs: contextFile ? [askContextDir()] : [],
+				extraArgs: extraArgs(),
+				prompt: effectivePrompt,
+			});
 
 			const details: AgyDetails = {
 				model: requestedModel,
@@ -1466,261 +1223,130 @@ export default async function (pi: ExtensionAPI) {
 				stderr: "",
 			};
 
-			let out = "";
-
-			// Throttled status updates (claude-bridge pattern): emit a short
-			// status line on an interval instead of the full buffer on every
-			// stdout chunk, avoiding O(n²) re-renders on long runs.
-			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) => {
-					// detached: true so we can signal the whole process group.
-					// agy spawns its own exec subprocesses in -p mode; a direct
-					// kill would orphan those grandchildren.
-					const proc = spawn(binary, args, {
-						cwd,
-						stdio: ["ignore", "pipe", "pipe"],
-						shell: false,
-						detached: true,
-					});
-
-					// Decode at the stream level so multibyte UTF-8 split across
-					// pipe chunks doesn't corrupt (Gemini output is non-ASCII).
-					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;
-
-					// Kill the whole process group; SIGTERM first, then SIGKILL
-					// after a grace period if it hasn't exited.
-					const killTree = () => {
+			// Background: hand the run to the registry and return at once. The
+			// result travels back through pi.sendMessage (wake), not this call.
+			if (params.background) {
+				if (ctx.mode === "print" || ctx.mode === "json") {
+					if (contextFile) {
 						try {
-							if (proc.pid) process.kill(-proc.pid, "SIGTERM");
+							fs.unlinkSync(contextFile);
 						} catch {}
-						// Only arm the SIGKILL timer once.
-						if (!sigkillTimer) {
-							sigkillTimer = setTimeout(() => {
-								try {
-									if (proc.pid) process.kill(-proc.pid, "SIGKILL");
-								} catch {}
-							}, GRACE_AFTER_TIMEOUT_MS);
-						}
-					};
-
-					const cleanup = () => {
-						if (watchdog) clearTimeout(watchdog);
-						if (sigkillTimer) clearTimeout(sigkillTimer);
-						if (signal) signal.removeEventListener("abort", onAbort);
-					};
-
-					const onAbort = () => killTree();
-
-					// Enforce the timeout cap ourselves (not just via
-					// --print-timeout, which agy could ignore or not support).
-					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();
-						// Distinguish an aborted run from a normal close: if the
-						// abort signal fired, treat as cancelled regardless of
-						// exit code (killTree produces a non-zero code, but be
-						// explicit and order-independent). Likewise surface a
-						// timeout distinctly from a genuine non-zero exit.
-						resolveP({
-							exitCode: code ?? 0,
-							aborted: !!signal?.aborted,
-							timedOut,
-						});
-					};
-
-					proc.on("error", (err) => {
-						cleanup();
-						rejectP(err);
-					});
-					proc.on("close", 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;
-
-				// For a fresh run, discover the conversation id agy just created
-				// (agy -p never prints it). Retry briefly since agy may flush its
-				// SQLite DB a moment after the process closes. A continuation run
-				// reuses the provided id (already set on details).
-				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);
+					if (reviewerAgent) {
+						try {
+							fs.rmSync(reviewerAgent.dir, { recursive: true, force: true });
+						} catch {}
 					}
-				}
-
-				const text = out.trim();
-
-				// Aborted: return a distinct result so the caller knows it was
-				// cancelled, not a silent success.
-				if (outcome.aborted) {
 					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 },
 					};
 				}
+				return startBackgroundRun({
+					summary: params.prompt,
+					binary,
+					args,
+					workdir: cwd,
+					timeoutMin,
+					startAt: start,
+					details,
+					contextFile,
+					reviewerAgent,
+					modelLabel: resolved.model ?? requestedModel,
+					isContinuation,
+					conversationId: isContinuation ? (rawConvId as string) : undefined,
+				});
+			}
 
-				// Timeout: distinct from a genuine non-zero exit (the watchdog
-				// killed the tree because the configured cap elapsed).
-				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)) {
+					if (contextFile) {
+						try {
+							fs.unlinkSync(contextFile);
+						} catch {}
+					}
+					if (reviewerAgent) {
+						try {
+							fs.rmSync(reviewerAgent.dir, { recursive: true, force: true });
+						} catch {}
+					}
 					return {
 						content: [
-							{ type: "text", text: text ? `${text}\n\n[${note}]` : note },
+							{
+								type: "text",
+								text: `conversation ${rawConvId} already has a run in flight. Wait for its result, or stop it with /agy-stop.`,
+							},
 						],
-						details,
+						details: emptyDetails(requestedModel, resolved.model),
 					};
 				}
+				// Track acquisition: the finally must only release a lock THIS call
+				// took, never the one held by the run that caused a refusal.
+				lockAcquired = isContinuation;
+				if (isContinuation) busyHandles.add(rawConvId as string);
+				const outcome = await runAgyProcess({
+					binary,
+					args,
+					workdir: cwd,
+					timeoutMin,
+					startAt: start,
+					details,
+					isContinuation,
+					snapshot,
+					signal,
+					onPartial: onUpdate
+						? (text) => {
+								onUpdate({
+									content: [{ type: "text", text }],
+									details: { ...details, durationMs: Date.now() - start },
+								});
+							}
+						: undefined,
+				});
 
-				// Non-zero exit: surface the failure even when partial text
-				// exists, instead of returning silent success.
-				if (outcome.exitCode !== 0) {
-					const note = details.stderr.trim()
-						? `agy exited with status ${outcome.exitCode}: ${details.stderr.trim()}`
-						: `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
-				// caller: 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 note = [
-						"agy exited cleanly but produced no output.",
-						details.stderr.trim() ? `stderr: ${details.stderr.trim()}` : 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 };
 				}
 
 				// Success. Clear the last partial status line (claude-bridge
 				// idiom) so the running-tail preview doesn't linger under the final
-				// answer, then append a conversation footer so the orchestrating model
-				// can see (and thread) the id without inspecting details.
+				// answer.
 				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 }],
+					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);
 				return {
 					content: [{ type: "text", text: `failed to run agy: ${msg}` }],
 					details,
 				};
-			}
-			finally {
+			} finally {
+				if (isContinuation && lockAcquired) busyHandles.delete(rawConvId as string);
 				if (contextFile) {
 					try {
 						fs.unlinkSync(contextFile);
@@ -1734,6 +1360,156 @@ export default async function (pi: ExtensionAPI) {
 			}
 		},
 	});
+	// --- /agy-stop: kill a background run ----------------------------------
+
+	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");
+		},
+	});
+
+	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;
+		conversationId?: string;
+	}): AskToolResult => {
+		registry.sweep();
+		// Per-handle lock: two background runs resuming the same conversation
+		// would interleave turns inside agy's session state.
+		if (o.conversationId && busyHandles.has(o.conversationId)) {
+			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 },
+			};
+		}
+		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);
+			if (o.contextFile) {
+				try {
+					fs.unlinkSync(o.contextFile);
+				} catch {}
+			}
+			if (o.reviewerAgent) {
+				try {
+					fs.rmSync(o.reviewerAgent.dir, { recursive: true, force: true });
+				} catch {}
+			}
+			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 },
+			};
+		}
+		const runId = run.runId;
+		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 {}
+			}
+		};
+		cleanups.set(runId, cleanupStaging);
+		void runAgyProcess({
+			binary: o.binary,
+			args: o.args,
+			workdir: o.workdir,
+			timeoutMin: o.timeoutMin,
+			startAt: o.startAt,
+			details: o.details,
+			isContinuation: o.isContinuation,
+			snapshot: o.isContinuation ? null : snapshotConversations(CONVERSATIONS_DIR),
+			onSpawn: (kill) => {
+				kills.set(runId, kill);
+			},
+		})
+			.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: ${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) {
+					const reason = 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);
+				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 },
+		};
+	};
 }
 
 function emptyDetails(