@estebanforge/pi-ask-antigravity 1.2.9 → 1.2.11

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.11] - 2026-10-07
+
+### Added
+
+- **Background runs (`background`, opt-in, default blocking).** Detached runs with the shared wake contract: `runId` at once, the answer arrives later as a conversation message with the resume handle (when agy reports one; discovery misses say so) under an UNTRUSTED banner. `/agy-stop [runId]` kills a run. One run per conversation at a time across blocking and background (per-handle lock). Refused in print/json mode; session replacement kills in-flight runs and loses their results; the staged context file and plan-mode reviewer dir are cleaned on every exit path including session shutdown.
+
+
+### Fixed
+
+- **Plan runs are no longer auto-approved and no longer claim enforcement.** The CLI does not gate writes under plan mode ([#1181](https://github.com/google-antigravity/antigravity-cli/issues/1181)): the previously documented "write attempts fail at plan approval" behavior never held, and plan runs carrying the skip-permissions flag (whenever the restricted agent staged) were write-capable. Plan runs now never receive the flag (including via `AGY_EXTRA_ARGS`, filtered by prefix), the restricted agent is documented as a damper, and the tool description, param description, and README no longer call plan review-only or enforced.
+
+## [1.2.10] - 2026-10-06
+
+### Changed
+
+- **Breaking: model aliases track agy's Claude 5.5 tiered catalog.** `sonnet`/`opus` now resolve to `claude-sonnet-5-5`/`claude-opus-5-5` with the tier riding `--effort` (nearest-tier pick against the requested thinking level), replacing the retired fixed `claude-sonnet-4-6`/`claude-opus-4-6-thinking` slugs Google removed from Antigravity. The static overlay carries the full low/medium/high spread so the aliases still resolve when the live catalog omits Claude, and the bare base id (`claude-sonnet-5-5`) resolves to the nearest tier variant because a bare base is rejected upstream. Exact tiered ids (`claude-sonnet-5-5-low`) split to base + effort exactly like Gemini's.
+- **The `gpt-oss` alias and its overlay entry are removed** ahead of upstream's announced removal of that family: nobody used the fixed-thinking slug and it loses to the cheaper tiered options. The alias now resolves to nothing (the raw string passes to agy and fails there) instead of the tool offering a dying model.
+
 ## [1.2.9] - 2026-09-28
 
 ### Fixed

package/README.md

@@ -49,21 +49,20 @@ Verbose `agy models` strings (`Gemini 3.5 Flash (Medium)`) are hostile to natura
 | `pro low` | latest Pro, Low |
 | `3.5 flash` | pinned version, default tier |
 | `3.1 pro` | pinned Pro version (→ High) |
-| `sonnet` | Claude Sonnet 4.6 (Thinking) |
-| `opus` | Claude Opus 4.6 (Thinking) |
-| `gpt-oss` | GPT-OSS 120B (Medium) |
+| `sonnet` | Claude Sonnet 5.5, default tier (Medium) |
+| `opus` | Claude Opus 5.5, default tier (Medium) |
 | `Gemini 3.5 Flash (Medium)` | exact passthrough |
 
 - **Latest** = highest version number available for the family.
 - **Default tier**: Flash → Medium, Pro → High. Overridable per-config (below).
 - When a tier is unavailable for a family, the nearest is chosen with ties broken toward the higher tier (so "latest and greatest" wins).
-- The non-Gemini aliases (`sonnet`, `opus`, `gpt-oss`) are a static overlay merged with the live `agy models` catalog. Live entries always win on case-insensitive full-string equality, so an updated `agy` listing takes precedence over the hardcoded fallback.
+- The non-Gemini aliases (`sonnet`, `opus`) are a static overlay (the full low/medium/high tier spread) merged with the live `agy models` catalog. Live entries always win on case-insensitive full-string equality, so an updated `agy` listing takes precedence over the hardcoded fallback. A bare base id (`claude-sonnet-5-5`) resolves to the nearest tier variant; the retired `gpt-oss` family resolves to nothing.
 
 ## Execution modes (`mode`)
 
 | Mode | Flag | Use when |
 | --- | --- | --- |
-| `plan` | `--mode plan` | agy reviews and plans without writing. Use for cross-review and read-only tasks. Enforced: the skip-permissions flag is never passed in plan mode, so write and command attempts fail visibly at plan approval instead of executing. |
+| `plan` | `--mode plan` | Review-shaped run for cross-review and read-only tasks. NOT a security boundary: the CLI does not gate writes under plan mode ([#1181](https://github.com/google-antigravity/antigravity-cli/issues/1181), probed 2026-10-07: the write can execute in the same turn). The skip-permissions flag is never passed, so nothing runs auto-approved, and a temporary restricted agent (no file-editing tools) stages as a damper. Treat plan output as review material, not as proof nothing happened. |
 | `accept-edits` (default) | `--mode accept-edits` | agy applies edits directly inside the workspace. |
 
 For agy's orthogonal `--sandbox` shell-containment flag, set `AGY_EXTRA_ARGS=--sandbox` in your environment. The extension does not expose it as a `mode` value because `--sandbox` controls command containment, not edit persistence.
@@ -111,7 +110,7 @@ Interactive picker for the default model and default thinking. If the project co
 | `prompt` | yes | Self-contained task. agy cannot see the Pi conversation. |
 | `cwd` | no | Workspace agy runs in. Defaults to the project root. |
 | `model` | no | Alias or exact id. Omit for the configured default. |
-| `mode` | no | `plan` (review-only; enforced via plan approval) or `accept-edits` (agy applies edits, default). |
+| `mode` | no | `plan` (review-shaped; not enforced, see the modes table) or `accept-edits` (agy applies edits, default). |
 | `digest` | no | Prefix the prompt with `(Use compact digests, not full file contents.)`. Defaults on for `plan`, off for `accept-edits`. |
 | `conversationId` | no | Omit for a one-shot (agy starts fresh). Pass the id from a prior call's result (`details.conversationId`) to resume that agy conversation with full context. See [Two modes](#two-modes-one-shot-vs-continued-conversation). |
 | `timeoutMinutes` | no | Hard cap on the run. Default 10. |
@@ -136,6 +135,10 @@ agy mutates the workspace itself, so scope calls to sub-tasks where that is the
 
 Google's [Antigravity ToS](https://antigravity.google/terms) states that using third-party software to access the Service (e.g. driving `agy` from a non-Google editor) is a breach of the Agreement and may be grounds for suspension or termination of your account. `agy` handles its own Google OAuth; this extension only spawns the official binary as a subprocess — but the effect is still a non-Google editor driving the Antigravity service through a third-party tool. **By using this extension against an `agy` session logged into your personal Antigravity account, you accept that risk.**
 
+## Background runs
+
+Set `background: true` on a call to run detached: the tool returns a `runId` at once, the calling agent keeps working, and the full answer arrives later as a message in the conversation (wrapped in an UNTRUSTED banner: it is tool output, never a user instruction). The message carries the resume handle (`conversationId`) when agy reports one; fresh runs where id discovery finds nothing say so instead of inventing a handle. One run per conversation at a time (blocking and background share the lock). Stop a run with `/agy-stop [runId]` (unique id prefix; no arg stops the only running run). Constraints: refused in print/json mode (the process exits before the message could arrive); a `/new`, `/resume`, `/fork`, or `/reload` kills in-flight runs and their results are lost; at most 4 runs at once; failure wakes (timeout, crash) carry up to 400 chars of peer output as the reason, also banner-marked.
+
 ## License
 
 MIT

package/extensions/index.ts

@@ -45,6 +45,13 @@ 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,
+	createStopHandler,
+	createWakeSender,
+	summarizePrompt,
+} from "@estebanforge/pi-ask-shared";
 
 // --- Constants -------------------------------------------------------------
 
@@ -97,9 +104,11 @@ function levelToTier(level: string): ThinkingTier {
 }
 
 // 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
@@ -112,13 +121,15 @@ type Mode = "plan" | "accept-edits";
 // 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-4-6
-//   "opus"     -> claude-opus-4-6-thinking
-//   "gpt-oss"  -> gpt-oss-120b-medium
+//   "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-4-6", family: "other", version: null, tier: null },
-	{ full: "claude-opus-4-6-thinking", family: "other", version: null, tier: null },
-	{ full: "gpt-oss-120b-medium", family: "other", version: null, tier: null },
+	{ 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
@@ -126,11 +137,21 @@ const STATIC_ALIAS_OVERLAY: ReadonlyArray<ModelEntry> = [
 // 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-4-6"],
-	["opus", "claude-opus-4-6-thinking"],
-	["gpt-oss", "gpt-oss-120b-medium"],
+	["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. */
@@ -157,7 +178,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.
 
@@ -302,15 +323,17 @@ export const PLAN_HEADLESS_GUARD = [
 ].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. */
+ *  to PLAN_HEADLESS_GUARD: read commands are the intended analysis path
+ *  here, so the guard forbids FILE MUTATION - by tool or by shell - and
+ *  keeps the answer-from-material discipline. The agent is a damper, not
+ *  enforcement (upstream #1181); a headless command attempt can still be
+ *  auto-denied, which ends the run, so the guard steers toward view_file
+ *  and staged material first. */
 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.",
+	"- Prefer the staged material and view_file for reading. If you run a read-only command (git log, git diff, rg, ls) and it comes back denied, the run ends without an answer: state what you could not check instead of retrying commands.",
 	"- Work from the material provided in this prompt; if information you need is missing, state exactly what is missing in your answer.",
 ].join("\n");
 
@@ -323,11 +346,12 @@ export function buildFinalPrompt(
 	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,
+	 *  toolset is a damper (the CLI does not enforce review-only, upstream
+	 *  #1181), so the prompt may ALLOW read-only commands. */
+	agentDamper = 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;
+	if (mode === "plan") out += agentDamper ? AGENT_REVIEW_GUARD : PLAN_HEADLESS_GUARD;
 	return out;
 }
 
@@ -342,12 +366,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 [
 		"---",
@@ -466,19 +490,47 @@ function nearestTier(available: ThinkingTier[], preferred: ThinkingTier): Thinki
 	return sorted[0] ?? preferred;
 }
 
-/** Build the argv-facing resolution from a picked catalog entry. Gemini bases
- *  (slugs starting "gemini-") accept a separate --effort, so split the tier
- *  suffix out of the slug: the base alone (gemini-3.6-flash) is what --model
- *  wants, and the tier goes to --effort. Fixed-thinking families keep agy's
- *  exact slug even when it carries a -medium suffix (gpt-oss-120b-medium):
- *  agy rejects --effort for them, so the suffix stays part of the slug. */
+/** 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 && full.toLowerCase().startsWith("gemini-")) {
+	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
@@ -499,7 +551,7 @@ export function resolveModel(
 	const exact = entries.find((e) => e.full.toLowerCase() === lower);
 	if (exact) return toResolved(exact.full, exact.tier);
 
-	// 1b. Static short alias ("sonnet" / "opus" / "gpt-oss"). Checked
+	// 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
@@ -509,9 +561,12 @@ export function resolveModel(
 	//     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)) {
-		const target = STATIC_SHORT_ALIAS.get(lower) as string;
-		const fromCatalog = entries.find((e) => e.full.toLowerCase() === target.toLowerCase());
-		return toResolved(fromCatalog?.full ?? target, fromCatalog?.tier ?? null);
+		return resolveTieredBase(
+			STATIC_SHORT_ALIAS.get(lower) as string,
+			entries,
+			defaultThinking,
+			preferredTier,
+		);
 	}
 
 	// 2. Parse the alias.
@@ -529,7 +584,19 @@ export function resolveModel(
 	if (!family && (/gemini/.test(lower) || lower === "" || lower === "default")) {
 		family = "flash";
 	}
-	if (!family) return null; // unknown family -> let agy handle it
+	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);
@@ -670,10 +737,9 @@ async function discoverModels(binary: string): Promise<ModelEntry[]> {
 				finish("");
 			}, DISCOVERY_TIMEOUT_MS);
 		});
-		return text
-			.split("\n")
-			.map(parseModelLine)
-			.filter((e): e is ModelEntry => e !== null);
+		return filterHiddenModels(
+			text.split("\n").map(parseModelLine).filter((e): e is ModelEntry => e !== null),
+		);
 	} catch {
 		return [];
 	}
@@ -914,6 +980,276 @@ 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 as soon as the child exists. */
+	onSpawn?: (kill: () => void) => 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 {
+		// 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: workdir,
+				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;
+				// Safety valve for pathological output; keeps the tail.
+				if (out.length > STDOUT_BUF_MAX_CHARS) out = out.slice(-100_000);
+			});
+			proc.stderr?.on("data", (d: string) => {
+				// Cap: stderr feeds notes and wake messages, not forensics.
+				if (details.stderr.length < 64_000) 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 = () => {
+				try {
+					if (proc.pid) process.kill(-proc.pid, "SIGTERM");
+				} 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);
+				}
+			};
+
+			// Hand the kill switch to the background registry before any terminal event can fire.
+			onSpawn?.(killTree);
+
+			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", () => {
+				cleanup();
+				rejectP(new AgySpawnError("failed to spawn agy"));
+			});
+			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() - 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() };
+	} 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
@@ -933,10 +1269,47 @@ export default async function (pi: ExtensionAPI) {
 	// Discovered once at load; frozen for the session. Run /reload after an
 	// `agy update` to refresh. Failure is non-fatal: resolveModel falls back
 	// to passthrough so exact slugs typed by the user still work. The static
-	// alias overlay (sonnet / opus / gpt-oss) is merged on top so those
+	// alias overlay (sonnet / opus) is merged on top so those
 	// 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
@@ -1107,7 +1480,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",
 					},
 				),
@@ -1135,6 +1508,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
@@ -1162,6 +1541,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(", ")}]`)} `;
@@ -1316,10 +1696,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 {
@@ -1328,7 +1709,7 @@ 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 =
@@ -1367,12 +1748,14 @@ export default async function (pi: ExtensionAPI) {
 
 			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.
+			// Fail-closed on every plan run: AGY_EXTRA_ARGS lands before the mode
+			// flags, so an env-injected skip flag would re-arm exactly what the
+			// never-flag-on-plan rule withholds (upstream #1181: an auto-approved
+			// plan run is write-capable). The reviewer agent is a damper, not a
+			// license for the flag.
 			const extra =
-				mode === "plan" && !reviewerAgent
-					? extraRaw.filter((a) => a !== "--dangerously-skip-permissions")
+				mode === "plan"
+					? extraRaw.filter((a) => !a.startsWith("--dangerously-skip-permissions"))
 					: extraRaw;
 			if (extra.length) args.push(...extra);
 			if (resolved.model) args.push("--model", resolved.model);
@@ -1382,14 +1765,15 @@ export default async function (pi: ExtensionAPI) {
 			// 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)) {
+			// Plan runs NEVER get the flag: it auto-approves every permission
+			// request, and the CLI does not gate writes under plan mode (upstream
+			// google-antigravity/antigravity-cli#1181, probed 2026-10-07), so an
+			// auto-approved plan run is a write-capable run. The reviewer agent's
+			// toolset is a damper, not a guarantee; the 2026-09-28 "safe with the
+			// restricted toolset" probe predates the #1181 evidence. Without the
+			// flag, command attempts fail visibly (headless auto-deny) instead of
+			// running approved.
+			if (config.skipPermissions && mode !== "plan") {
 				args.push("--dangerously-skip-permissions");
 			}
 			if (isContinuation) args.push("--conversation", rawConvId as string);
@@ -1412,261 +1796,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);
@@ -1680,6 +1933,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(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-ask-antigravity",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "description": "Pi tool that delegates a self-contained sub-task to Google Antigravity's agy CLI (the CLI for Gemini). Friendly model aliases (flash/pro/gemini), configurable default model + thinking, and the AskAntigravity delegation tool.",
   "keywords": [
     "pi-package",
@@ -27,6 +27,9 @@
     "access": "public"
   },
   "type": "module",
+  "dependencies": {
+    "@estebanforge/pi-ask-shared": "^0.1.0"
+  },
   "files": [
     "extensions",
     "README.md",
@@ -39,7 +42,7 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {