@estebanforge/pi-antigravity-bridge 1.7.8 → 1.7.10

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.7.10] - 2026-10-07
+
+### Added
+
+- **`readOnly` config key (fail-closed provider kill switch).** `AGY_READONLY` env and `/agy readonly on|off` set it. On: every provider turn is refused with a visible error instead of running, because the agy CLI has no review-only enforcement on any path (probed 2026-10-07, [google-antigravity/antigravity-cli#1181](https://github.com/google-antigravity/antigravity-cli/issues/1181): plan mode stages a plan and executes the write in the same turn on both the `-p` and stream-json paths, with `permission_mode: "request-review"` reported and no permission event for the write; with `--disable-slash-commands` plan is a warned no-op). Built for tool-less callers (`pi -p --no-tools --model antigravity/...`) that must never mutate a workspace. While the knob is on, the `AskAntigravity` tool is refused as well; nothing in this package runs read-only, because the CLI cannot enforce it.
+- **`AskAntigravity` mode default now follows the config.** Omitting `mode` used to hardcode `accept-edits`, so a `mode: "plan"` config still left the delegation tool write-capable by default (issue #3 request 3). The default is now plan when the configured mode is plan; an explicit `mode` param still wins.
+
+### Fixed
+
+- **Plan-shaped provider turns refuse visibly instead of running write-capable.** `/agy mode plan` on the stream-json engine was silently a no-op (the engine warns plan has no effect with slash expansion disabled), and the `-p` path is no better: probed 2026-10-07, plan stages a plan, asks for approval, and executes the write in the same turn on both paths ([#1181](https://github.com/google-antigravity/antigravity-cli/issues/1181)). Provider turns with `mode: "plan"` or `readOnly` on now fail with an error pointing at host-side enforcement and the knob to lift. The README no longer claims provider plan mode "genuinely executes nothing" or that the one-shot path enforces plan.
+- **`readOnly` refusals cover the `AskAntigravity` tool too, and plan runs never carry the skip flag.** `AskAntigravity` is refused while `readOnly` is on (a `mode` param cannot bypass the kill switch), and the tool's plan runs no longer pass `--dangerously-skip-permissions` even when the reviewer agent stages: the CLI does not gate writes under plan mode ([#1181](https://github.com/google-antigravity/antigravity-cli/issues/1181)), so an auto-approved plan run is a write-capable run. Analysis commands in plan runs now fail visibly (headless auto-deny) instead of running approved; `accept-edits` runs keep the flag.
+- **Delegation tool refuses `background: true` (fail-closed).** The param is advertised and always refused with an explanation: a wake from a nested delegation would land in the pi session, and long delegations already have the bridge's own early-ack plus poll flow. No behavior change for existing calls.
+
+
+## [1.7.9] - 2026-10-06
+
+### Changed
+
+- **Breaking: Claude models are effort-tiered now, and the ids moved to the Claude 5.5 family.** Google retired Claude 4.6 on Antigravity and ships Claude Opus 5.5 (2026-09-22) and Claude Sonnet 5.5 (2026-09-28) in its place, each with low/medium/high thinking tiers - the same shape Gemini already had. Claude joins the verified effort-capable families (probed live 2026-10: base slug + `--effort` accepted; a bare base is rejected with "requires --effort"), so `claude-opus-5-5` and `claude-sonnet-5-5` register as single toggleable models whose turns always send `--effort`, instead of per-tier fixed ids. The catalog fixtures mirror the live listing and the no-`agy models` fallback carries its head (3.8 flash, 3.1 pro, sonnet 5.5). A pattern pinned to `antigravity/claude-sonnet-4-6` (settings enabledModels, `--model`, or a scoped-model config) matches nothing after agy's upgrade and must move to `antigravity/claude-sonnet-5-5`; the bare base id itself resolves through the delegation tool to the nearest tier variant.
+- **The `gpt-oss-120b-medium` family is dropped now, not next month.** Upstream announced its removal; nobody used the fixed-thinking single slug and it loses to the cheaper effort-tiered options, so the provider catalog and the delegation tool catalog both filter it before that date lands. The `gpt-oss` alias stops resolving: unrecognized input passes raw to agy and fails loudly there, instead of the tool offering a dying model.
+
 ## [1.7.8] - 2026-09-30
 
 ### Fixed

package/README.md

@@ -135,7 +135,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy                      status summary, or open the full settings picker (TUI)
 /agy doctor               single status surface: bridge state, driver counters, versions, acp state, lifecycle, settings, log dir
 /agy auth                 run the antigravity-acp sign-in now (engine acp): opens the Google login in your browser, shows the URL when no browser opens
-/agy mode plan            review-only: agy plans but writes nothing
+/agy mode plan            provider turns are REFUSED (the CLI cannot enforce review-only, #1181)
 /agy mode accept-edits    agy applies edits directly (default)
 /agy permissions on|off   auto-approve / prompt for tool calls (see warning)
 /agy ask on|off           register the AskAntigravity delegation tool (default on; off keeps only the provider and models, even with pi-ask-antigravity installed)
@@ -158,7 +158,13 @@ pi itself has no built-in approval gate. Unlike codex, claude, or agy running in
 
 Because agy runs non-interactively under this provider (nothing can answer a `y/n` prompt), this extension passes `--dangerously-skip-permissions` by default on `accept-edits` runs. It is technically necessary there: `accept-edits` auto-approves file edits but not shell commands, so a `run_command` would otherwise hang forever waiting for a prompt nothing can answer (upstream [google-antigravity/antigravity-cli#318](https://github.com/google-antigravity/antigravity-cli/issues/318)). The net effect is that agy executes commands the same way pi already executes your other tools: without per-action review.
 
-Plan mode never receives the flag: the flag auto-approves every permission request, including plan mode's own approval gate, which would silently turn review-only into full write access inside the `--add-dir` grant (probed 2026-09-25: with the flag a plan run wrote files; without it, file and command attempts end the run quickly with a "confirm plan" message). So `/agy mode plan` (and `AskAntigravity` with `mode: "plan"`) genuinely executes nothing. Do not combine `--sandbox` with skip-permissions ([#36](https://github.com/google-antigravity/antigravity-cli/issues/36)).
+Plan mode never receives the flag: the flag auto-approves every permission request, so an auto-approved plan run is a write-capable run (the CLI does not gate writes under plan mode, see next paragraph). Do not combine `--sandbox` with skip-permissions ([#36](https://github.com/google-antigravity/antigravity-cli/issues/36)).
+
+**Provider turns cannot run review-only.** Probed 2026-10-07 ([google-antigravity/antigravity-cli#1181](https://github.com/google-antigravity/antigravity-cli/issues/1181)): on every tested path (one-shot `-p` and the stream-json I/O format, with and without `--add-dir`), `--mode plan` stages a plan, asks for review and approval, and executes the requested file write in the same turn (`permission_mode: "request-review"` is reported; no permission event appears for the write). With `--disable-slash-commands` the CLI additionally warns that `--mode plan` has no effect. The `readOnly` knob below exists because of this: plan-shaped provider turns refuse visibly instead of pretending. `AskAntigravity` with `mode: "plan"` adds a staged restricted agent whose toolset omits file-editing tools (probed 2026-09-28 on agy 1.2.12; re-verify on 1.3.x), but plan mode itself does not gate writes anywhere. Treat host-side pi tool restrictions as the only hard read-only wall.
+
+### readOnly
+
+`"readOnly": true` in the config (or `AGY_READONLY=1`, or `/agy readonly on`) is a fail-closed kill switch: every provider turn AND the `AskAntigravity` tool are refused with a visible error instead of running write-capable under a read-only label. Built for callers like `pi -p --no-tools --model antigravity/...` health checks that must never mutate a workspace: with no review-only enforcement available in the CLI (see Permissions), a visible refusal is the only honest behavior. The knob covers provider turns and the ask tool; the web tools still spawn agy for searches. Default false.
 
 For per-action review of agy's mutating native tools (`run_command`, `create_file`, `edit_file`, ...), see the [Approval gate](docs/APPROVAL-GATE.md): with it on, the call must pass a pi-side approval (your permission extension, or the built-in ask/allow/deny fallback) before agy executes it.
 
@@ -175,7 +181,8 @@ For isolation when running any agent that executes commands without a confirmati
 | `AGY_ACP_BIN` | Path to the ACP server binary (`agy_acp_server.par`). Defaults to `agy_acp_server.par` on PATH. Wins over `config.acp.bin`. When neither points at a binary, auto-setup installs one. |
 | `AGY_EXTRA_ARGS` | Extra args appended to every invocation. Whitespace-split. |
 | `AGY_CONVERSATIONS_DIR` | Override the conversations DB directory. |
-| `AGY_MODE` | Override execution mode: `plan` (review-only) or `accept-edits` (default). Wins over the config file. |
+| `AGY_MODE` | Override execution mode: `plan` (provider turns are refused, see Permissions) or `accept-edits` (default). Wins over the config file. |
+| `AGY_READONLY` | `1`/`true`/`on` (or any set value except `0`/`false`/`off`/empty) turns every provider turn and the `AskAntigravity` tool into a visible refusal (fail-closed: the CLI has no review-only enforcement on any path, [#1181](https://github.com/google-antigravity/antigravity-cli/issues/1181)). Wins over the config file. |
 | `AGY_SKIP_PERMISSIONS` | `1`/`true` (default) to pass `--dangerously-skip-permissions` so commands don't hang on an unanswerable prompt in `-p` mode. `0`/`false` to prompt (hangs any `run_command` non-interactively). Wins over the config file. |
 | `AGY_USAGE_ESTIMATE` | ACP token display: `estimate` (default; live client-side per-delta estimates), `direct` (pass through the server's own per-delta counts when it sends them), `off` (no usage display). Anything else falls back to `estimate`. Wins over the config file. |
 | `AGY_DEFAULT_MODEL` | Default model alias for the `AskAntigravity` tool (`flash`/`pro`/`gemini`, or a tier/version qualifier). Wins over the config file. |
@@ -219,6 +226,10 @@ pi-antigravity-bridge practical risk is low, near zero. But not zero: the "in co
 
 This is engineering analysis, not legal advice. Use against your own Antigravity account at your own risk; I am not responsible for any consequence to your account.
 
+## Delegation tool: background is refused
+
+The `AskAntigravity` delegation tool rejects `background: true` by design: a background wake would land in the pi session even when the caller is a nested delegation through the bridge catalog, and long delegations already have the bridge's own async flow (early-ack plus `bridge_poll_result`). Call without `background`; for unattended peer runs launch the CLI directly in a terminal.
+
 ## License
 
 MIT.

package/extensions/index.ts

@@ -1053,6 +1053,7 @@ interface AgyCommandCtx {
 
 interface PendingConfig {
 	mode?: AgyMode;
+	readOnly?: boolean;
 	skipPermissions?: boolean;
 	defaultModel?: string;
 	defaultThinking?: ThinkingTier;
@@ -1074,6 +1075,10 @@ function settingsRows(ctx: AgyCommandCtx): string[] {
 	const row = (label: string, value: string) => `  ${label.padEnd(24)} ${value}`;
 	return [
 		row("mode:", config.mode),
+		row(
+			"readOnly:",
+			config.readOnly ? "on (provider turns are refused)" : "off",
+		),
 		row("permissions:", perm),
 		row("AskAntigravity tool:", config.askTool ? "on" : "off"),
 		row("Web tools:", config.webTools ? "on" : "off"),
@@ -1096,7 +1101,7 @@ function statusText(ctx: AgyCommandCtx): string {
 		`  sessions:      ${ctx.store.size} bound`,
 		`  config:        ${CONFIG_PATH}`,
 		"",
-		"Subcommands: /agy auth, /agy auth-manual, /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy permissions on|off, /agy ask on|off, /agy model <alias>, /agy thinking low|medium|high, /agy agent <name|off>, /agy subagents, /agy quota, /agy artifacts [open <n|name>], /agy tasks [tail <id>], /agy bridge all|mcp|none, /agy tools [hide|show <name>|reset], /agy web on|off, /agy digest on|off, /agy system-prompt on|off, /agy timeout <1-1440|off>, /agy acp-bin <path|auto>, /agy patch-cleanup, /agy clear, /agy doctor",
+		"Subcommands: /agy auth, /agy auth-manual, /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy readonly on|off, /agy permissions on|off, /agy ask on|off, /agy model <alias>, /agy thinking low|medium|high, /agy agent <name|off>, /agy subagents, /agy quota, /agy artifacts [open <n|name>], /agy tasks [tail <id>], /agy bridge all|mcp|none, /agy tools [hide|show <name>|reset], /agy web on|off, /agy digest on|off, /agy system-prompt on|off, /agy timeout <1-1440|off>, /agy acp-bin <path|auto>, /agy patch-cleanup, /agy clear, /agy doctor",
 	].join("\n");
 }
 
@@ -1104,7 +1109,7 @@ function statusText(ctx: AgyCommandCtx): string {
 function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	pi.registerCommand("agy", {
 		description:
-			"Antigravity provider: doctor (health + settings), settings picker, clear sessions. Usage: /agy [doctor|auth|auth-manual|engine stream-json|acp|mode plan|accept-edits|permissions on|off|ask on|off|model <alias>|thinking low|medium|high|agent <name|off>|subagents|quota|artifacts [open <n|name>]|tasks [tail <id>]|bridge all|mcp|none|tools [hide|show <name>|reset]|web on|off|digest on|off|system-prompt on|off|timeout <1-1440|off>|acp-bin <path|auto>|patch-cleanup|clear]",
+			"Antigravity provider: doctor (health + settings), settings picker, clear sessions. Usage: /agy [doctor|auth|auth-manual|engine stream-json|acp|mode plan|accept-edits|readonly on|off|permissions on|off|ask on|off|model <alias>|thinking low|medium|high|agent <name|off>|subagents|quota|artifacts [open <n|name>]|tasks [tail <id>]|bridge all|mcp|none|tools [hide|show <name>|reset]|web on|off|digest on|off|system-prompt on|off|timeout <1-1440|off>|acp-bin <path|auto>|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
 			if (ui) activeUi = ui;
@@ -1387,13 +1392,52 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 			if (sub === "mode") {
 				if (val === "plan" || val === "accept-edits") {
 					if (val === "plan" && ctx.engine === "acp") {
-						ui?.notify("the ACP engine has no plan mode (RC01). /agy engine stream-json first, or /agy mode accept-edits.", "warning");
+						ui?.notify("plan cannot be enforced on provider turns on either engine: the ACP engine has no plan mode (RC01), and the CLI does not gate writes under plan (google-antigravity/antigravity-cli#1181). /agy mode accept-edits.", "warning");
 						return;
 					}
 					const next = saveConfig({ mode: val as AgyMode });
-					ui?.notify(`mode set to ${next.mode}`, "info");
+					// readOnly fail-closes provider turns regardless of this knob;
+					// never let the confirmation imply turns will run. loadConfig, not
+					// next: saveConfig merges the raw file, so an env-only readOnly
+					// would otherwise read as off here.
+					const effectiveReadonly = loadConfig().readOnly;
+					if (effectiveReadonly) {
+						ui?.notify(`mode set to ${next.mode}, but readOnly is on: provider turns are refused. /agy readonly off to lift.`, "info");
+					} else if (val === "plan") {
+						ui?.notify(`mode set to plan: provider turns are REFUSED (the CLI does not gate writes under plan, google-antigravity/antigravity-cli#1181). Only the AskAntigravity tool uses this mode.`, "info");
+					} else {
+						ui?.notify(`mode set to ${next.mode}`, "info");
+					}
+				} else {
+					const cfg = loadConfig();
+					ui?.notify(
+						`current mode: ${cfg.mode}${cfg.readOnly ? " (readOnly on: provider turns are refused)" : ""}\nusage: /agy mode plan|accept-edits`,
+						"info",
+					);
+				}
+				return;
+			}
+			if (sub === "readonly") {
+				if (val === "on" || val === "off") {
+					const next = saveConfig({ readOnly: val === "on" });
+					ui?.notify(
+						next.readOnly
+							? "readOnly is on: provider turns and AskAntigravity are REFUSED (the agy CLI has no review-only enforcement on any path; probed 2026-10-07). Enforce read-only in the host, then /agy readonly off."
+							: "readOnly off: provider turns follow /agy mode again.",
+						"info",
+					);
+					// Compare effective vs saved: the env can force either direction
+					// (AGY_READONLY=1 keeps refusals on after /agy readonly off;
+					// AGY_READONLY=0 silently keeps readOnly off after /agy readonly on).
+					if (loadConfig().readOnly !== next.readOnly) {
+						ui?.notify(`AGY_READONLY is set in this environment and overrides the config: readOnly stays ${loadConfig().readOnly ? "on (refusing)" : "off"} until you unset it.`, "warning");
+					}
 				} else {
-					ui?.notify(`current mode: ${loadConfig().mode}\nusage: /agy mode plan|accept-edits`, "info");
+					const cfg = loadConfig();
+					ui?.notify(
+						`readOnly is ${cfg.readOnly ? "on (provider turns and AskAntigravity are refused)" : "off"}\nusage: /agy readonly on|off. Fail-closed: the CLI has no review-only enforcement on any path (probed 2026-10-07), so on = refuse.`,
+						"info",
+					);
 				}
 				return;
 			}
@@ -1755,10 +1799,18 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			id: "mode",
 			label: "Execution mode",
 			description:
-				"accept-edits: agy applies edits directly. plan: review-only, no writes. Takes effect next turn.",
+				"accept-edits: agy applies edits directly. plan: provider turns are REFUSED (the CLI cannot enforce review-only, upstream #1181); AskAntigravity plan runs add a restricted agent as a damper. Takes effect next turn.",
 			currentValue: config.mode,
 			values: ["accept-edits", "plan"],
 		},
+		{
+			id: "readonly",
+			label: "Read-only provider turns",
+			description:
+				"on: provider turns are REFUSED (fail-closed; the CLI has no review-only enforcement on any path). Enforce read-only in the host instead.",
+			currentValue: config.readOnly ? "on" : "off",
+			values: ["off", "on"],
+		},
 		{
 			id: "permissions",
 			label: "Permissions",
@@ -1845,6 +1897,8 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			(id, newValue) => {
 				if (id === "mode") {
 					pending.mode = newValue as AgyMode;
+				} else if (id === "readonly") {
+					pending.readOnly = newValue === "on";
 				} else if (id === "permissions") {
 					pending.skipPermissions = newValue === "auto-approved";
 				} else if (id === "model") {
@@ -1882,12 +1936,13 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 	if (Object.keys(pending).length === 0) return;
 
 	// The picker cannot switch engines (command-only: /agy engine), but the
-	// mode row can still produce plan while the latched engine is acp. ACP
-	// has no review-only mode (RC01); refuse the combination.
+	// mode row can still produce plan while the latched engine is acp. Plan
+	// cannot be enforced on provider turns on either engine (#1181 + RC01);
+	// refuse the combination.
 	const nextMode = pending.mode ?? config.mode;
 	if (nextMode === "plan" && ctx.engine === "acp") {
 		ui.notify(
-			"plan + acp is not supported (RC01): the ACP engine has no review-only mode. /agy engine stream-json first, or /agy mode accept-edits.",
+			"plan cannot be enforced on provider turns on either engine (google-antigravity/antigravity-cli#1181; ACP additionally has no plan mode, RC01). /agy mode accept-edits.",
 			"warning",
 		);
 		return;
@@ -1897,6 +1952,7 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 		const next = saveConfig(pending);
 		const changed = [
 			pending.mode ? `mode=${next.mode}` : null,
+			pending.readOnly !== undefined ? `readOnly=${next.readOnly ? "on" : "off"}` : null,
 			pending.skipPermissions !== undefined
 				? `permissions=${next.skipPermissions ? "auto-approved" : "prompt"}`
 				: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. Use antigravity/* models in Pi. Full /model picker support. Models runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",
@@ -46,7 +46,7 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/src/approval-gate.ts

@@ -25,7 +25,7 @@
 import type {
 	AgentToolResult,
 	AgentToolUpdateCallback,
-	ExtensionContext,
+	ExtensionToolContext,
 	ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 
@@ -151,7 +151,7 @@ export function createShadowTool(base: AnyToolDefinition, policy: GatePolicy, op
 		params: any,
 		signal: AbortSignal | undefined,
 		onUpdate: AgentToolUpdateCallback<any> | undefined,
-		ctx: ExtensionContext,
+		ctx: ExtensionToolContext,
 	): Promise<AgentToolResult<unknown>> => {
 		const p = (params ?? {}) as Record<string, unknown>;
 		if (p[GATE_MARKER] !== true) {

package/src/ask-tool.ts

@@ -56,16 +56,19 @@ const TIER_RANK: Record<ThinkingTier, number> = { low: 0, medium: 1, high: 2 };
 // Static alias overlay for non-Gemini models agy may or may not surface.
 // Live catalog entries win on case-insensitive full-string equality; the
 // overlay resolves the alias when agy doesn't list it. Names are agy's stable
-// slugs (the same ids `agy models` prints and `--model` accepts).
+// slugs (the same ids `agy models` prints and `--model` accepts). Claude ships
+// tiered like Gemini now, so the overlay carries the full tier spread.
 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" },
 ];
 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"],
 ]);
 
 // agy conversation ids are UUID DB-stems. First char must be alphanumeric so a
@@ -80,8 +83,8 @@ TWO MODES (you choose):
 - **Continued conversation**: pass the conversationId returned in the PREVIOUS call's details (details.conversationId). agy resumes that conversation with full context intact.
 
 EXECUTION MODES (param: mode):
-- **plan**: agy reviews and plans without writing. Use for cross-review and read-only tasks. 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.
-- **accept-edits** (default): agy applies edits directly inside the workspace.
+- **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**: agy applies edits directly inside the workspace. Default unless the configured mode is plan.
 
 COMPACT OUTPUT (param: digest): when true, the prompt is prefixed to request compact digests instead of full file contents. Defaults on for plan, off for accept-edits.
 
@@ -164,19 +167,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
  *  the raw input straight to agy. */
@@ -195,9 +226,12 @@ export function resolveModel(
 	if (exact) return toResolved(exact.full, exact.tier);
 
 	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,
+		);
 	}
 
 	let family: Family | null = lower.includes("flash")
@@ -213,7 +247,19 @@ export function resolveModel(
 	if (!family && (/gemini/.test(lower) || lower === "" || lower === "default")) {
 		family = "flash";
 	}
-	if (!family) return null;
+	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;
+	}
 
 	let candidates = entries.filter((e) => e.family === family);
 	if (candidates.length === 0) return null;
@@ -252,11 +298,18 @@ export function resolveModel(
 	return toResolved(picked.full, picked.tier);
 }
 
+/** Families dropped outright even while `agy models` still lists them (same
+ *  policy as models.ts HIDDEN_FAMILY_RE): never offered, never resolved. */
+const HIDDEN_FAMILY_RE = /^gpt-oss-/;
+
 /** Parse raw `agy models` text into tool-catalog entries (all families, plus
- *  the static sonnet/opus/gpt-oss overlay). Pure: no spawn. */
+ *  the static sonnet/opus overlay). Pure: no spawn. */
 export function toolModelsFromRaw(raw: string): ModelEntry[] {
 	return mergeCatalog(
-		raw.split("\n").map(parseModelLine).filter((e): e is ModelEntry => e !== null),
+		raw
+			.split("\n")
+			.map(parseModelLine)
+			.filter((e): e is ModelEntry => e !== null && !HIDDEN_FAMILY_RE.test(e.full)),
 	);
 }
 
@@ -275,15 +328,17 @@ function extraArgs(): string[] {
 // --- Prompt assembly -------------------------------------------------------
 
 /** 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");
 
@@ -312,11 +367,12 @@ export function buildFinalPrompt(
 	mode: AgyMode,
 	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;
 }
 
@@ -331,12 +387,14 @@ export function askAgentsRoot(): string {
 const ASK_AGENT_PREFIX = "pi-bridge-ask-";
 const ASK_AGENT_TOOLS = ["view_file", "run_command"];
 
-/** 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 a
+ *  guarantee: with no file-editing tool present the model has no edit tool in
+ *  its menu (probed 2026-09-28 on agy 1.2.12: the toolset reports "none" for
+ *  edits; re-verify on 1.3.x), but the CLI itself does not enforce
+ *  review-only under plan mode (upstream google-antigravity/antigravity-cli
+ *  #1181, probed 2026-10-07: the write can execute in the same turn).
+ *  commandExecutionPolicy auto is what lets read commands run headless with
+ *  no user allow rules. Never add a write-capable tool here. */
 export function reviewerAgentMd(name: string): string {
 	return [
 		"---",
@@ -431,8 +489,7 @@ export async function registerAskAntigravityTool(
 			mode: Type.Optional(
 				Type.Union([Type.Literal("plan"), Type.Literal("accept-edits")], {
 					description:
-						"agy execution mode. 'plan' = review-only. 'accept-edits' = agy applies edits (default).",
-					default: "accept-edits",
+						"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. 'accept-edits' = agy applies edits. Omit to follow the configured default (plan when config mode is plan, else accept-edits).",
 				}),
 			),
 			digest: Type.Optional(
@@ -456,6 +513,12 @@ export async function registerAskAntigravityTool(
 						"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:
+						"NOT supported by this tool. The bridge runs agy through its own delegated flow and the answer must return synchronously to the caller. For background runs use the standalone @estebanforge/pi-ask-antigravity extension. Calls with background=true are refused.",
+				}),
+			),
 		}),
 		renderCall(args, theme, _context) {
 			// Show RESOLVED model/thinking/mode (config defaults applied) so the
@@ -471,7 +534,10 @@ export async function registerAskAntigravityTool(
 					thinkingArg ? toAgyEffort(thinkingArg as ThinkingLevel, AGY_EFFORT_ORDER) : undefined,
 				) ?? { model: requestedModel };
 			const thinking: ThinkingTier = resolved.effort ?? cfg.defaultThinking;
-			const mode: AgyMode = (args.mode as AgyMode | undefined) ?? "accept-edits";
+			// Same default rule as execute: plan when the configured mode is
+			// plan, so the row always names what will actually run.
+			const mode: AgyMode =
+				(args.mode as AgyMode | undefined) ?? (cfg.mode === "plan" ? "plan" : "accept-edits");
 			const useDigest = typeof args.digest === "boolean" ? args.digest : mode === "plan";
 			const isContinue =
 				typeof args.conversationId === "string" && CONV_ID_RE.test(args.conversationId);
@@ -545,6 +611,37 @@ export async function registerAskAntigravityTool(
 			}
 
 			const config = loadConfig();
+			// readOnly refusal (fail-closed): the kill switch covers this tool too.
+			// It must not be bypassable with an explicit mode param: the CLI has no
+			// review-only enforcement (upstream google-antigravity/antigravity-cli
+			// #1181), so a plan-labeled run here is not read-only.
+			if (config.readOnly) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: 'readOnly is on: AskAntigravity is refused (fail-closed; the agy CLI has no review-only enforcement, google-antigravity/antigravity-cli#1181). Run /agy readonly off to use this tool.',
+						},
+					],
+					details: emptyDetails(),
+				};
+			}
+			// Background refusal (fail-closed): a wake from this tool would land in
+			// the pi session even when the CALLER is agy (nested delegation via the
+			// bridge catalog), and the bridge already owns an async delegation flow
+			// (early-ack + bridge_poll_result). The standalone pi-ask-antigravity
+			// extension is the background-capable tool.
+			if (params.background) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: 'background is not supported by the bridge\'s AskAntigravity: the answer must return synchronously to the caller. Long delegations are already covered by the bridge\'s own async flow (early-ack + bridge_poll_result); for an unattended peer run, launch agy directly in a terminal instead. Call again without background.',
+						},
+					],
+					details: emptyDetails(),
+				};
+			}
 			const requestedModel = (params.model as string | undefined) ?? config.defaultModel;
 			if (typeof params.model === "string" && params.model.trim().startsWith("-")) {
 				return {
@@ -605,10 +702,13 @@ export async function registerAskAntigravityTool(
 				typeof rawConvId === "string" && rawConvId.length > 0 && CONV_ID_RE.test(rawConvId);
 			const snapshot = isContinuation ? null : snapshotConversations();
 
-			const mode: AgyMode = (params.mode as AgyMode | undefined) ?? "accept-edits";
+			const mode: AgyMode =
+				(params.mode as AgyMode | undefined) ?? (config.mode === "plan" ? "plan" : "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).
+			// 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;
@@ -658,12 +758,14 @@ export async function registerAskAntigravityTool(
 				"info",
 			);
 			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);
@@ -672,16 +774,16 @@ export async function registerAskAntigravityTool(
 			if (reviewerAgent) args.push("--agent", reviewerAgent.name);
 			// Honor the shared permissions setting (same knob as the provider).
 			// accept-edits: the flag keeps commands from hanging on an
-			// unanswerable prompt in -p mode. 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, and plan discipline turned a
-			// create-a-file request into a proposed plan instead of a write. 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 !== false && (mode !== "plan" || reviewerAgent !== null)) {
+			// unanswerable prompt in -p mode. 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 !== false && mode !== "plan") {
 				args.push("--dangerously-skip-permissions");
 			}
 			if (isContinuation) args.push("--conversation", rawConvId as string);

package/src/config.ts

@@ -89,11 +89,24 @@ export interface AgyConfig {
 	/** Official-server ACP engine options (used when engine = "acp"). */
 	acp: AcpConfig;
 	mode: AgyMode;
+	/** Fail-closed kill switch for provider turns. ON = every provider turn
+	 *  is refused visibly: the agy CLI has no review-only enforcement on any
+	 *  path (probed 2026-10-07, upstream #1181: plan mode stages a plan and
+	 *  executes the write in the same turn on -p and stream-json alike; the
+	 *  ACP engine has no plan mode at all). Built for callers like
+	 *  `pi -p --no-tools` health checks that must never mutate a workspace
+	 *  and prefer a visible refusal over a write-capable turn. Wins over
+	 *  `mode`; the AskAntigravity delegation tool is refused while this is on
+	 *  (the CLI has no review-only enforcement, so nothing here can run
+	 *  read-only). Env AGY_READONLY wins over the file.
+	 *  Default false. */
+	readOnly: boolean;
 	/** Auto-approve all agy tool permission requests (--dangerously-skip-permissions).
 	 *  Required for non-interactive use: without it, any `run_command` triggers an
 	 *  interactive y/n prompt that hangs forever in `-p` mode. Defaults true.
 	 *  DANGEROUS: lets agy run arbitrary commands (including destructive ones)
-	 *  without review. Turn off only if you also set mode=plan (no execution). */
+	 *  without review. The ask tool withholds the flag on plan runs;
+	 *  accept-edits runs need it to avoid hanging on the unanswerable prompt. */
 	skipPermissions: boolean;
 	/** AskAntigravity tool: default model alias (flash/pro/gemini or exact). */
 	defaultModel: string;
@@ -176,6 +189,7 @@ export interface AgyConfig {
 const DEFAULTS: AgyConfig = {
 	engine: "stream-json",
 	mode: "accept-edits",
+	readOnly: false,
 	skipPermissions: true,
 	defaultModel: "flash",
 	defaultThinking: "medium",
@@ -212,18 +226,24 @@ export function parseCapMinutes(raw: string | number | undefined, fallback: numb
 	return n >= 1 && n <= MAX_TURN_CAP_MIN ? n : fallback;
 }
 
-/** Load config merged over defaults. Env vars override the file when set. */
-export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
-	let file: Partial<AgyConfig> = {};
+/** Read the raw config file (no defaults, no env). Shared by loadConfig and
+ *  saveConfig so persisted writes can never bake env overrides into the file. */
+function readConfigFile(configPath: string): Partial<AgyConfig> {
 	try {
 		const raw = fs.readFileSync(configPath, "utf8");
 		const parsed = JSON.parse(raw);
 		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-			file = parsed as Partial<AgyConfig>;
+			return parsed as Partial<AgyConfig>;
 		}
 	} catch {
-		/* missing or corrupt  -  fall back to defaults */
+		/* missing or corrupt  -  fall back to empty */
 	}
+	return {};
+}
+
+/** Load config merged over defaults. Env vars override the file when set. */
+export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
+	let file: Partial<AgyConfig> = readConfigFile(configPath);
 
 	// Env overrides file (matches the skipPermissions pattern).
 	// The naive OR `env === "plan" || file.mode === "plan"` would ignore an
@@ -249,6 +269,17 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 			? envPerm === "1" || envPerm.toLowerCase() === "true"
 			: file.skipPermissions ?? DEFAULTS.skipPermissions;
 
+	const envReadOnly = process.env.AGY_READONLY;
+	// Fail-closed parse for a safety knob: empty string means the user
+	// explicitly blanked it (off), but ANY other set value that is not a
+	// spelled-out falsity counts as ON. " 1", "yes", typos: all refuse.
+	const readOnly =
+		envReadOnly !== undefined
+			? envReadOnly === ""
+				? false
+				: !["0", "false", "off"].includes(envReadOnly.trim().toLowerCase())
+			: file.readOnly ?? DEFAULTS.readOnly;
+
 	const defaultModelRaw =
 		process.env.AGY_DEFAULT_MODEL ?? file.defaultModel ?? DEFAULTS.defaultModel;
 	const defaultModel =
@@ -329,6 +360,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		engine,
 		acp,
 		mode,
+		readOnly,
 		skipPermissions,
 		defaultModel,
 		defaultThinking,
@@ -345,10 +377,30 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 	};
 }
 
-/** Atomically persist a config patch (temp + rename). */
+/** Atomically persist a config patch (temp + rename). Merges onto the RAW
+ *  FILE values, never loadConfig(): env overrides must not be baked into the
+ *  file (AGY_READONLY=1 in the env would otherwise persist readOnly: true to
+ *  disk on any unrelated save, outliving the env var). Nested objects are
+ *  re-normalized to their known keys: a raw passthrough would resurrect
+ *  legacy keys (acp.permissions) that loadConfig normalization drops. */
 export function saveConfig(patch: Partial<AgyConfig>, configPath: string = CONFIG_PATH): AgyConfig {
-	const current = loadConfig(configPath);
-	const next: AgyConfig = { ...current, ...patch };
+	const file = readConfigFile(configPath);
+	// Null-safe on nested objects: a hand-edited or legacy file can carry
+	// "acp": null; loadConfig tolerates it, so must saveConfig. Key presence
+	// triggers normalization (a null becomes the default shape, never null).
+	const fileAcp: Partial<AcpConfig> = file.acp && typeof file.acp === "object" ? file.acp : {};
+	const fileApprovals: Partial<GateConfig> = file.approvals && typeof file.approvals === "object" ? file.approvals : {};
+	const next: AgyConfig = {
+		...DEFAULTS,
+		...file,
+		...(file.acp !== undefined
+			? { acp: { bin: fileAcp.bin ?? DEFAULTS.acp.bin, usageEstimate: fileAcp.usageEstimate ?? DEFAULTS.acp.usageEstimate } }
+			: {}),
+		...(file.approvals !== undefined
+			? { approvals: { gateMode: fileApprovals.gateMode ?? DEFAULTS.approvals.gateMode, mode: fileApprovals.mode ?? DEFAULTS.approvals.mode } }
+			: {}),
+		...patch,
+	};
 	const dir = path.dirname(configPath);
 	fs.mkdirSync(dir, { recursive: true });
 	const tmp = `${configPath}.${process.pid}.tmp`;

package/src/driver.ts

@@ -80,10 +80,11 @@ interface ActiveTurn {
 }
 
 /** The skip-permissions flag actually passed to agy. Plan mode never
- *  carries it: the flag auto-approves every permission request including
- *  plan mode's own approval gate, silently turning review-only into full
- *  write access. #start (argv + profile) and #recycleCause (comparison)
- *  must both go through this, or plan turns recycle on every turn. */
+ *  carries it: the flag auto-approves every permission request, and the CLI
+ *  does not gate writes under plan mode (upstream #1181), so an
+ *  auto-approved plan run is a write-capable run. #start (argv + profile)
+ *  and #recycleCause (comparison) must both go through this, or plan turns
+ *  recycle on every turn. */
 function effectiveSkipPermissions(mode: DriverTurnRequest["mode"], skipPermissions: boolean): boolean {
 	return mode !== "plan" && skipPermissions;
 }
@@ -352,12 +353,11 @@ export class StreamDriver implements TurnDriver {
 		this.#generation += 1;
 		const generation = this.#generation;
 		// Plan mode never carries the skip flag: the flag auto-approves ALL
-		// permission requests including plan mode's own approval gate, which
-		// would silently turn "review-only" into full write access (probed
-		// 2026-09-25: with the flag a plan session wrote files; without it,
-		// file and command attempts end exit 0 in ~20-30s with a "confirm
-		// plan" message). The profile stores the EFFECTIVE value so the
-		// recycle comparison stays consistent with the argv.
+		// permission requests, and the CLI does not gate writes under plan
+		// mode (upstream google-antigravity/antigravity-cli#1181, probed
+		// 2026-10-07: the write executes in the same turn). An auto-approved
+		// plan run is a write-capable run. The profile stores the EFFECTIVE
+		// value so the recycle comparison stays consistent with the argv.
 		const skipPermissions = effectiveSkipPermissions(request.mode, request.skipPermissions);
 		this.#profile = {
 			cwd: request.cwd,

package/src/models.ts

@@ -2,20 +2,21 @@
 // they appear in the /model picker as antigravity/<slug>.
 //
 // agy prints TWO columns per line: "<slug>  <display label>". --model takes
-// ONLY the slug (col 1); the label is display-only. Verified live, e.g.:
-//   gemini-3.6-flash-high     Gemini 3.6 Flash (High)
-//   gemini-3.6-flash-medium   Gemini 3.6 Flash (Medium)   (+ -low)
+// ONLY the slug (col 1); the label is display-only. Verified live 2026-10:
+//   gemini-3.8-flash-high     Gemini 3.8 Flash (High)
+//   gemini-3.8-flash-medium   Gemini 3.8 Flash (Medium)   (+ -low)
 //   gemini-3.1-pro-high       Gemini 3.1 Pro (High)        (Pro has NO medium)
-//   claude-sonnet-4-6         Claude Sonnet 4.6 (Thinking) (fixed, no tiers)
-//   gpt-oss-120b-medium       GPT-OSS 120B (Medium)        (fixed, no tiers)
+//   claude-sonnet-5-5-high    Claude Sonnet 5.5 (High)     (+ -medium, -low)
 //
-// Gemini models are collapsed to a BASE slug (gemini-3.6-flash) and exposed
-// with a thinking-effort toggle whose levels match exactly the tiers agy
-// offers that base (verified: Pro rejects medium). The picked level is sent as
-// agy --effort; a base slug is INVALID on its own, so effort is always passed.
-// Claude and GPT-OSS keep agy's exact slug with no toggle: their thinking is
-// fixed and agy rejects --effort for them. Google's Antigravity subscription
-// bills all of these through agy.
+// Gemini AND Claude models are collapsed to a BASE slug (gemini-3.8-flash,
+// claude-sonnet-5-5) and exposed with a thinking-effort toggle whose levels
+// match exactly the tiers agy offers that base (verified: Pro rejects medium;
+// Claude 5.5 accepts low/medium/high). The picked level is sent as agy
+// --effort; a bare base slug is INVALID on its own (agy: "requires --effort"),
+// so effort is always passed. Only unverified families keep agy's exact slug
+// with no toggle, so an unknown future family degrades safely; the retired
+// gpt-oss family is dropped outright (HIDDEN_FAMILY_RE). Google's Antigravity
+// subscription bills all of these through agy.
 
 import { spawn } from "node:child_process";
 import fs from "node:fs";
@@ -81,8 +82,9 @@ export function toAgyEffort(
 }
 
 /** Split an agy slug into (base, tier). tier is null when the slug has no
- *  -high/-medium/-low suffix (claude-sonnet-4-6, gpt-oss-120b-medium's "medium"
- *  IS its suffix here, claude-opus-4-6-thinking is not a tier). */
+ *  -high/-medium/-low suffix - a shape only unverified families should
+ *  produce now, and those stay whole. Every Claude slug carries a tier
+ *  suffix and collapses to its base. */
 const TIER_RE = /^(.+)-(high|medium|low)$/;
 
 /** agy emits clean slug ids (gemini-3.6-flash-high). Validate col1 of each
@@ -97,14 +99,21 @@ const MODEL_LINE_RE = /^[A-Za-z0-9][A-Za-z0-9._]*-[A-Za-z0-9._-]*$/;
  *  to a base slug with a thinking toggle. Any other family stays as agy's exact
  *  qualified slug (always valid on its own), so an unknown or fixed-thinking
  *  family degrades safely instead of forcing an unsupported --effort. Add a
- *  family here only after confirming base+--effort is accepted for it. */
-const EFFORT_CAPABLE_FAMILIES: readonly RegExp[] = [/^gemini-/];
+ *  family here only after confirming base+--effort is accepted for it.
+ *  Claude 5.5 verified live 2026-10: base+--effort accepted; a bare base is
+ *  rejected ("requires --effort"). */
+const EFFORT_CAPABLE_FAMILIES: readonly RegExp[] = [/^gemini-/, /^claude-/];
+
+/** 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-/;
 
 export interface AgyModelEntry {
-	/** Exact agy --model string to pass: a base slug ("gemini-3.6-flash") when
-	 *  effort-driven, else agy's full qualified slug ("claude-opus-4-6-thinking"). */
+	/** Exact agy --model string to pass: a base slug ("gemini-3.8-flash") when
+	 *  effort-driven, else agy's full qualified slug (unverified family). */
 	full: string;
-	/** pi model id, e.g. "gemini-3-6-flash". */
+	/** pi model id, e.g. "gemini-3-8-flash". */
 	id: string;
 	/** Present iff this is an effort-driven base slug. Lists the tiers agy
 	 *  accepts for it; pi's thinking toggle picks among them and we always pass
@@ -284,11 +293,12 @@ export async function loadModelCatalogRaw(
 
 /** Parse raw `agy models` text into the provider's model entries.
  *
- *  Effort-driven Gemini bases (>= 2 tier variants in the catalog) collapse to
- *  one BASE-slug entry carrying the tiers they accept. Models with 0 or 1 tier
- *  variants keep agy's exact qualified slug: a single suffix (gpt-oss-120b-
- *  medium) or none (claude-sonnet-4-6) means fixed thinking, where --effort is
- *  unsupported. Insertion order of first-seen bases is preserved. */
+ *  Effort-driven bases (>= 2 tier variants in the catalog, verified
+ *  effort-capable family) collapse to one BASE-slug entry carrying the tiers
+ *  they accept. Models with 0 or 1 tier variants keep agy's exact qualified
+ *  slug: without a verified effort-capable family match, --effort is never
+ *  risked. Hidden families are dropped outright. Insertion order of
+ *  first-seen bases is preserved. */
 export function entriesFromRaw(raw: string): AgyModelEntry[] {
 	// agy prints TWO columns: "<slug>  <display label>". --model takes only the
 	// slug, so split col1 and validate THAT; the label is display-only. A
@@ -298,6 +308,7 @@ export function entriesFromRaw(raw: string): AgyModelEntry[] {
 	for (const line of raw.split("\n")) {
 		const slug = line.trim().split(/\s+/)[0] ?? "";
 		if (!slug || !MODEL_LINE_RE.test(slug)) continue;
+		if (HIDDEN_FAMILY_RE.test(slug)) continue;
 		const m = TIER_RE.exec(slug);
 		const base = m ? (m[1] as string) : slug;
 		const tier = m ? (m[2] as AgyEffort) : null;
@@ -365,8 +376,8 @@ export function toPiModel(entry: AgyModelEntry, input: Array<"text" | "image"> =
 		// sentinel that no built-in provider claims, so it can never collide.
 		baseUrl: "agy-bridge://antigravity",
 		// reasoning=true only for effort-driven bases => pi shows the toggle.
-		// Fixed models (Claude/GPT-OSS) get no toggle: their thinking can't be
-		// changed and agy rejects --effort for them.
+		// Unverified families get no toggle: --effort support is unknown, so
+		// none is ever sent.
 		reasoning: effortDriven,
 		...(effortDriven ? { thinkingLevelMap: thinkingLevelMapFor(entry.efforts!) } : {}),
 		// Input advertising comes from the caller (engine-dependent): the ACP
@@ -386,9 +397,9 @@ export function toPiModel(entry: AgyModelEntry, input: Array<"text" | "image"> =
  *  can still select a model and get a clear runtime error instead of an empty
  *  list. Update these when agy ships new Gemini versions. */
 export const FALLBACK_MODELS: AgyModelEntry[] = [
-	{ full: "gemini-3.7-flash", id: "gemini-3-7-flash", efforts: ["low", "medium", "high"] },
+	{ full: "gemini-3.8-flash", id: "gemini-3-8-flash", efforts: ["low", "medium", "high"] },
 	{ full: "gemini-3.1-pro", id: "gemini-3-1-pro", efforts: ["low", "high"] },
-	{ full: "claude-sonnet-4-6", id: "claude-sonnet-4-6" },
+	{ full: "claude-sonnet-5-5", id: "claude-sonnet-5-5", efforts: ["low", "medium", "high"] },
 ];
 
 

package/src/provider.ts

@@ -1435,13 +1435,34 @@ export function createStreamSimple(
 		const config = loadConfig();
 		const engine = deps.engine ?? config.engine;
 		const selected = engine === "acp" && deps.acpDriver ? deps.acpDriver : deps.driver;
-		// RC01: ACP modes are permission modes, there is no review-only plan.
-		// A plan turn on ACP would silently run non-plan; fail visibly instead.
-		if (selected === deps.acpDriver && config.mode === "plan") {
+		// Plan-shaped provider turns are fail-closed on BOTH engines. ACP has
+		// no plan mode at all (RC01). Stream-json is worse and probed
+		// 2026-10-07: the engine WARNS that --mode plan is a no-op while
+		// --disable-slash-commands is set, executes file writes even with
+		// slash expansion left on (it stages a plan.md and still writes in the
+		// same turn), ignores --agent toolset restrictions, and file writes
+		// bypass the permission system entirely. A plan-labeled turn here is
+		// write-capable, so refuse visibly instead of running false safety.
+		if (config.readOnly || config.mode === "plan") {
 			const partial = newAssistant(model);
 			const blocks: BlockState = { partial, textIdx: null, thinkingIdx: null, started: false };
-			deps.log?.("turn-error", { reason: "acp-plan-refused" }, "warn");
-			finalize(stream, blocks, "error", "ACP engine has no plan mode. /agy mode accept-edits, or /agy engine stream-json.");
+			if (config.readOnly) {
+				deps.log?.("turn-error", { reason: "readonly-refused" }, "warn");
+				finalize(
+					stream,
+					blocks,
+					"error",
+					"readOnly cannot be enforced on provider turns: the agy CLI has no review-only enforcement on any path. Plan mode stages a plan and executes the write in the same turn (probed 2026-10-07, google-antigravity/antigravity-cli#1181). Enforce read-only in the host (pi tool restrictions or the approval gate), then /agy readonly off.",
+				);
+				return stream;
+			}
+			deps.log?.("turn-error", { reason: "plan-refused" }, "warn");
+			finalize(
+				stream,
+				blocks,
+				"error",
+				"Plan mode cannot be enforced on provider turns: the agy CLI stages a plan and executes writes in the same turn (probed 2026-10-07, google-antigravity/antigravity-cli#1181), and the ACP engine has no plan mode (RC01). /agy mode accept-edits, and enforce review-only in the host.",
+			);
 			return stream;
 		}
 		if (selected && roundTrips) {