@estebanforge/pi-antigravity-bridge 1.4.10 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.1] - 2026-09-15
+
+### Fixed
+
+- Delegated agy no longer sees the pi tool bridge. `AskAntigravity` spawns `agy -p`, and any agy on the machine discovers MCP servers from the global `~/.gemini/config/mcp_config.json`, which carries a live `pi-bridge-*` entry for every running pi session. A delegation could therefore connect to a host bridge and call tools (observed live: `memory_search`), which the round-trip store denies fail-closed with "no active antigravity turn" the moment no provider turn is streaming - a dead end for the delegation and an error toast in the host session. The bridge entries are now suppressed while a delegated agy starts: disabled before the spawn, re-enabled on process close or after a 5s grace, whichever lands first. Suppression is reference-counted, so overlapping delegations cannot re-enable early; session start re-enables any entries a crashed delegation left disabled. Foreign MCP servers in the file are never touched. Residual race, documented in code: another session's provider agy respawning inside the window reads the entries disabled and that process lacks bridge tools until its next recycle.
+- Real bridge tool-call failures now land on disk in default mode. The daily log records only errors, and `call-tool-fail` was logged at warn tier (toast only), so a failure like the one above left no durable trace. Genuine rejections now log at error tier; routine turn-end and shutdown aborts stay silent, with the reasons shared as constants between the emit sites and the log classifier so the two cannot drift.
+
+### Changed
+
+- README corrected: the bridge mechanism section described only the dir-scoped discovery and claimed the user's global agy config is never touched. Global per-pid registration shipped earlier and is now documented, along with the delegation suppression and its window.
+
+## [1.5.0] - 2026-09-08
+
+### Added
+
+- First-run engine picker. The choice of engine is left to the user: on a fresh install (no `config.json`, no `AGY_ENGINE`), the first interactive pi start opens a modal that explains both engines - stream-json needs the `agy` CLI installed and authenticated; ACP needs a second Google sign-in plus a ~1.5 GB server binary downloaded from Google. stream-json is preselected as the default; `esc` defers (nothing is written, the modal reappears next start). Headless sessions and existing installs are never asked.
+- The ACP pick chains setup immediately instead of waiting for a restart: the ~1.5 GB server binary downloads right away (live percent in the status bar, phase milestones as chat lines), the Google sign-in opens when it lands, and a restart applies the engine. The next start's self-heal sees binary + auth settled and stays silent.
+- `/agy engine` with no arguments (TUI) opens the same picker modal with identical semantics: plan mode blocks acp, an acp pick chains the download + sign-in, same-engine picks ack, esc acknowledges. Direct `/agy engine acp|stream-json` and the headless usage line are unchanged.
+- Missing-CLI warning: while the stream-json engine is active and the `agy` binary cannot be found (PATH or `AGY_BIN`), every pi start warns with the official install URL (toast in the TUI, stderr headless) until the binary is detected. Auth state is not checked, presence only.
+
+### Fixed
+
+- The picker's ACP line no longer claims "adds image input and native diffs": tool-result images ride both engines (probe-verified 2026-09-07) and stream-json has its own diff rendering. A negative test pin keeps the claim from returning.
+
+### Changed
+
+- README streamlined: the engine capability table, switching, and setup/auth details moved to docs/ENGINES.md; the approval-gate mechanics, configuration, and sample extension moved to docs/APPROVAL-GATE.md. Both stay linked from the README, which now carries the quick surface and states that engine choice is the user's.
+- Dependencies: fast-uri 3.1.5 → 3.1.7 clears four high-severity advisories (repeated hostname percent-decoding SSRF, malformed IPv6 normalization SSRF, percent-encoded scheme and IDN host confusion; in-range lockfile bump under ajv's `^3.0.1`), qs 6.15.3 → 6.16.0 clears a moderate pair (via express, dev surface). npm audit reports zero.
+
 ## [1.4.10] - 2026-09-07
 
 ### Added

package/README.md

@@ -2,11 +2,16 @@
 
 A Gemini model provider **and** the `AskAntigravity` delegation tool for [pi](https://github.com/earendil-works/pi-coding-agent), built on Google's official Antigravity binaries: the `agy` CLI by default, or **Google's official ACP server** (opt-in). It registers `antigravity/gemini-*` models in pi's `/model` picker (streaming), and provides the `AskAntigravity` tool for one-shot delegation - the same combined shape as `pi-claude-bridge`.
 
-<img width="2566" height="1723" alt="SCR-20260903-sefo" src="https://github.com/user-attachments/assets/20f0c04c-d622-4b11-962a-3478f64570c2" align="center"/>
+<p>
+  <img width="1374" height="869" alt="image" src="https://github.com/user-attachments/assets/fdd6c1f0-5144-40ef-9371-77a94de50b76" align="center" />
+</p>
+<p>
+  <img width="1376" height="451" alt="SCR-20260908-mbox" src="https://github.com/user-attachments/assets/d105c8a7-1ace-42f7-8285-642150453761" align="center" />
+</p>
+<p>
+  <img width="1375" height="1342" alt="SCR-20260908-mbvc" src="https://github.com/user-attachments/assets/bb614c55-e0f8-4677-bb0e-6541071e91ef" align="center" />
+</p>
 
-<br/><br/>
-
-<img width="1272" height="842" alt="SCR-20260903-sfcu" src="https://github.com/user-attachments/assets/c483613b-10ff-4d2f-9893-027d84130ac6" align="center" />
 
 If you also have [`@estebanforge/pi-ask-antigravity`](https://github.com/EstebanForge/pi-ask-antigravity) installed, this bridge takes over: pi-ask-antigravity detects the bridge and registers nothing, so the `AskAntigravity` tool is never duplicated.
 
@@ -21,35 +26,13 @@ Multi-turn works. The provider binds a pi session to an agy conversation id (per
 Turns run through one of two engines behind the same provider surface (`config.engine`, default `stream-json`):
 
 - **stream-json** (default): the persistent `agy` CLI process. The tested default; live token usage; conversation resume via `--conversation`.
-- **acp** (beta): Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery (see `scripts/parity-live.mjs`). Two known RC01 gaps remain: no usage fields (token display shows zero) and no cancel (abort tears the server down and reloads it next turn).
+- **acp** (beta): Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery (see `scripts/parity-live.mjs`). Two known RC01 gaps remain: no usage fields (token display shows client-side ESTIMATES until Google ships usage; `acp.usageEstimate` off to keep zeros) and no cancel (abort tears the server down and reloads it next turn).
 
-Engine-dependent features: pi image attachments ride natively only on the ACP engine (the picker offers image attach automatically when `config.engine` is `acp`; the stream-json CLI prompt is text-only). With the optional G1 digest enabled, its delivery also differs: ACP ships it as a native `embeddedContext` resource block, stream-json prepends it to the prompt text. The `AskAntigravity` delegation tool is unaffected by `config.engine` and runs the `stream-json` CLI (`agy -p`) across both configurations.
+The choice of engine is left to the user, with the trade-offs explained in the tool: a first-run picker modal asks once on a fresh install (stream-json preselected; `esc` defers, and the modal reappears next start), and `/agy engine` with no arguments reopens it anytime. An `acp` pick downloads the ~1.5 GB server binary and starts the Google sign-in immediately; a restart applies the engine. With stream-json active and the `agy` binary missing, pi warns on every start until the binary is found.
 
-| Capability | `stream-json` (default) | `acp` (beta) |
-| --- | --- | --- |
-| Show thinking text | No (token count only, floor 64, no text body) | Yes (streams thought text via `agent_thought_chunk`; sparse on RC01 where reasoning often arrives in message text) |
-| Live token usage | Yes (live metrics from CLI step events) | No (absent in RC01, displays zero tokens) |
-| Image prompt input | No (CLI prompt is text-only; images dropped) | Yes (native image blocks forwarded to server) |
-| Image tool results | Yes (bridge tool results carry pixels; probe-verified 2026-09-07) | Yes (probe-verified 2026-09-05) |
-| Audio prompt input | No (dropped) | Protocol advertised (`promptCapabilities.audio: true`) |
-| Review-only plan mode | Yes (`--mode plan` review-only via `/agy mode plan`) | No (RC01 modes are permission levels; plan mode refused) |
-| Leading slash commands in prompt | Disabled via `--disable-slash-commands` (sent as plain text) | Server intercepts recognized commands (e.g. `/plan`) and executes them under the active policy |
-| Dynamic model / effort switch | Recycles process on model or effort change | Dynamic per-turn via `session/set_config_option` (no restart) |
-| Process lifecycle | 1 persistent `agy` process per provider; recycles on drift | 1 persistent server process hosting N sessions concurrently |
-| Session resume & persistence | Client-side map in `sessions.json` via `--conversation <id>` | Server-side session store via `session/load` and `session/new` |
-| Turn cancel / abort | Kills process group; in-flight turn terminates | Teardown, kill, and auto-reload on RC01 (-32601 fallback) |
-| MCP tool bridge routing | Injected filesystem config via `--add-dir` | Direct `mcpServers` param in `session/new` and `session/load` |
-| Tool execution & visibility | Native re-exec (read-only) + wrapper replay (mutating) | Server executes tools natively; events stream with content |
-| Inline file edit diffs | Sourced from git working tree in thinking block | Sourced from `tool_call content[]` or disk vs git HEAD |
-| Permission handling | `--dangerously-skip-permissions` (unattended CLI requirement) | Protocol-native `session/request_permission` (auto-approve when `skipPermissions` is on; auto-deny when off) |
-| Context digest delivery (G1) | Prepend plain text inline in prompt | Native `embeddedContext` resource block |
-| System prompt delivery (G10) | Prepend to first prompt of conversation | Prepend to first prompt of conversation |
-| Authentication methods | Inherits existing `agy` CLI OAuth state | 4 methods: `oauth-personal`, `oauth-business`, `gemini-api-key`, `agent-platform` |
-| Wire protocol | Undocumented CLI NDJSON stream format | Versioned JSON-RPC 2.0 over stdio (`protocolVersion: 1`) |
-| Diagnostics (`/agy doctor`) | Child PID, state, process spawns, recycles, queue stats | Server version, agentInfo, session counts, reconnect count, cancel support |
-| Integration channel | Spawns internal CLI stream-json dialect | Official Google first-party ACP server binary |
-
-Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: the same account and plan you use for the Antigravity CLI (`agy`). Sign in explicitly with `/agy auth` (engine `acp` selected): it opens the Google login in your browser and completes when you finish it. If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy auth-manual`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
+Full capability comparison, switching, and setup/auth details: [docs/ENGINES.md](docs/ENGINES.md).
+
+Switch and setup details live in [docs/ENGINES.md](docs/ENGINES.md): switching to `acp` self-installs Google's official server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) and prepares the login (your Antigravity subscription, same account as the `agy` CLI; the extension never sees your credentials). `/agy auth` signs in explicitly, `/agy doctor` diagnoses, and a session start self-heals silently when everything is ready. Sessions are engine-scoped, so switching engines never crosses conversations.
 
 ## What it cannot do
 
@@ -58,20 +41,20 @@ agy runs its own closed tool loop (`read_file`, `write_file`, `edit_file`, `run_
 Residual limits (with or without the bridge):
 
 - agy's own edits still land directly on disk; pi's inline diff review does not engage for them.
-- agy commands run without per-action approval by default, same as every other tool in pi. The [Approval gate](#approval-gate-agy-native-tools) can put pi-side review in front of agy's mutating native tools (off by default; `auto` enables it only when a pi permission extension is installed). See also [Permissions](#permissions) below.
+- agy commands run without per-action approval by default, same as every other tool in pi. The [Approval gate](docs/APPROVAL-GATE.md) can put pi-side review in front of agy's mutating native tools (off by default; `auto` enables it only when a pi permission extension is installed). See also [Permissions](#permissions) below.
 - No cost accounting: cost stays zero because agy runs on your subscription quota. Token usage is live.
 
 ## MCP tool bridge (agy uses pi's tools)
 
 While agy is the active model it normally cannot see pi's universe of extensions: agentmemory, codegraph, web search, slack/asana, the `Ask*` delegations, and any other installed pi tool. This extension optionally bridges that gap.
 
-The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and a `tools/call` routes into pi's own tool loop via the round-trip described below. agy discovers the server through a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the provider passes that dir as an extra `--add-dir` when it spawns agy. The user's global agy config (`~/.gemini/config/mcp_config.json`) is never touched, so standalone agy outside pi is unaffected.
+The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and a `tools/call` routes into pi's own tool loop via the round-trip described below. Discovery has two layers. The provider's agy gets a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the driver passes that dir as an extra `--add-dir` when it spawns agy. A per-pid entry (`pi-bridge-<pid>`) is also registered in the user's global agy config (`~/.gemini/config/mcp_config.json`; foreign servers preserved, stale entries swept at start), so agy builds that read only the global config still find the bridge.
 
 **No patch required.** Bridge calls park in the provider's round-trip store; the provider ends the pi assistant message with a `toolUse` stop reason for the real pi tool, pi executes it in its own loop (native cards, permissions, hooks), and the toolResult completes the parked MCP response on the next stream call. This is the same mechanism tianzuo/pi-antigravity uses; upstream pi APIs only.
 
 **Long calls don't die.** agy's MCP client abandons a `tools/call` request at a flat ~180s, which used to kill any pi tool that ran longer (a long peer review, a build, a commit preview waiting for you). A call still running after ~20 seconds now settles its HTTP request with a `STILL RUNNING` answer carrying a `callId` while pi keeps executing; agy fetches the result through the bridge-local `bridge_poll_result` tool and polls until it lands. Escalated calls get their own 30-minute budget, so human-gated tools can take as long as the human takes. Fast calls stay fully synchronous and never see any of this. If a park does fail (abort, timeout, recycle), the late result is re-routed to agy as a follow-up prompt in the same conversation instead of being lost.
 
-**Recursion safety.** Only the provider's agy receives the extra `--add-dir`. The `AskAntigravity` tool spawns its own agy with just the workspace, so that inner agy starts plain (no pi tools) and cannot re-enter. `AskAntigravity` is also filtered from the exposed tool list. Standalone agy is unaffected because nothing is written to its global config.
+**Recursion safety.** Only the provider's agy receives the extra `--add-dir`. `AskAntigravity` is also filtered from the exposed tool list. Its delegated `agy -p` spawns with just the workspace, and while it starts the bridge suppresses its global per-pid entries: disabled before the spawn, re-enabled on process close or after a 5s grace (whichever lands first), refcounted across overlapping delegations, and re-enabled at every session start. The inner agy therefore sees no bridge and cannot re-enter pi. A hand-run agy outside pi that starts inside the seconds-wide window briefly misses the bridge; foreign servers in the global config are never touched.
 
 **Cost / fan-out.** Every registered pi tool except builtins (and `AskAntigravity`) is exposed, including other delegation tools like `AskClaude`/`AskCodex`. agy can therefore chain into other models via the bridge, which is a new cost/time fan-out vector that did not exist before this feature.
 
@@ -94,35 +77,9 @@ bridge port, and the last lifecycle events without spending tokens.
 
 ## Approval gate (agy native tools)
 
-agy is not a plain model: it runs its own agent loop with its own native tools (`run_command`, `create_file`, `edit_file`, ...). Those calls execute inside agy with no pi involvement, so pi's permission extensions never saw them. The approval gate closes that gap: agy native tool calls pass through a pi-side approval in a form the existing permission-extension ecosystem gates with zero changes.
-
-Mechanics: the extension stages an `.agents/hooks.json` group in the workspace; the Antigravity server/CLI fires a `PreToolUse` hook before each mutating native tool runs. The hook script (generated, per-pid, mode 0600 because it embeds the bridge token) POSTs the call to the bridge and polls for a decision. The bridge parks it, the provider interrupts the pi-side view of the agy turn with a `toolUse` for a SHADOW tool named `bash`/`write`/`edit` (same schema as the real builtin plus internal `__agy*` marker fields), and pi's whole `tool_call` surface applies: any installed permission extension gates the call unchanged, and only if nothing blocks does the fallback policy run. The decision travels back to the hook and agy enforces it; on deny the reason text is what agy's model sees. Marker calls never execute locally (a ticket check denies forged ones); non-marker calls delegate to a factory twin of the real builtin, so normal pi bash/write/edit behavior is unchanged. Read-only agy tools stay ungated. Every decision lands in the daily log with tool names, source, and latency.
-
-Configuration (`/agy` config keys or environment):
+agy runs its own agent loop with native tools (`run_command`, `create_file`, `edit_file`, ...), which pi's permission extensions never saw. The optional approval gate routes those calls through a pi-side approval: a staged PreToolUse hook parks the call, the provider surfaces it as a shadow `bash`/`write`/`edit` toolUse, and your permission extension (or the built-in ask/allow/deny fallback) decides before agy executes it. Off by default (`approvals.gateMode: auto` enables it only when a pi permission extension is detected); denials fail closed; read-only agy tools stay ungated.
 
-```jsonc
-{
-  "approvals": {
-    "gateMode": "auto",  // auto | shadow | dedicated | off
-    "mode": "ask"        // ask | allow | deny  (fallback when no extension gates)
-  }
-}
-// env: AGY_APPROVALS=shadow AGY_APPROVALS_MODE=ask
-```
-
-`auto` (default) keeps the gate OFF until one of the known pi permission packages is detected (pi settings `packages` name-match or known config markers). `shadow` forces it on; `off` forces it off. `dedicated` currently stages the same shadow tools (the explicit `antigravity_approve` variant is planned; the config value is accepted today so the schema is stable). The fallback `mode` is consulted only when no extension blocked the call: `ask` shows a pi confirm dialog (headless runs deny, fail-closed), `allow` approves, `deny` blocks. Timeouts deny fail-closed: the staged hook timeout always exceeds the park budget, but a hook that outlives its timeout soft-passes upstream (verified against the ACP server), so the park always answers first.
-
-If you write your own gate extension, it sees a normal pi tool call:
-
-```typescript
-export default function (pi) {
-	pi.on("tool_call", async (event) => {
-		if (event.input?.__agyGate && event.input.command?.startsWith("rm ")) {
-			return { block: true, reason: "rm is not allowed through the agy gate" };
-		}
-	});
-}
-```
+Full mechanics, configuration, and a sample gate extension: [docs/APPROVAL-GATE.md](docs/APPROVAL-GATE.md).
 
 ## Install
 
@@ -134,7 +91,7 @@ Install with pi's package manager:
 pi install npm:@estebanforge/pi-antigravity-bridge
 ```
 
-Requires the **`agy` CLI** installed and authenticated. If you don't have it, follow Google's [official install guide](https://antigravity.google/docs/cli/install) for your platform, then run `agy` once to complete Google OAuth. The extension resolves `agy` on `$PATH`, or via the `AGY_BIN` environment variable.
+Requires the **`agy` CLI** installed and authenticated. If you don't have it, follow Google's [official install guide](https://antigravity.google/docs/cli/install) for your platform, then run `agy` once to complete Google OAuth. The extension resolves `agy` on `$PATH`, or via the `AGY_BIN` environment variable. While the stream-json engine is active and the binary cannot be found, pi warns on every start (toast in the TUI, stderr headless) pointing at the install guide; the warning stops once the binary is detected.
 
 ## Usage
 
@@ -190,7 +147,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy system-prompt on|off send pi's system prompt + AGENTS.md + the Pi Bridge tool-priority note to new agy conversations (default on)
 /agy bridge all|mcp|none  which pi tools the MCP bridge exposes to agy (default all; none = bridge off)
 /agy acp-bin <path|auto>  point the ACP engine at a specific server binary (auto = setup installs, or AGY_ACP_BIN; applies on the next ACP turn)
-/agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp is beta and runs self-service setup: binary install + auth bootstrap)
+/agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp is beta and runs self-service setup: binary install + auth bootstrap). No arguments opens the engine picker modal (TUI)
 /agy auth-manual             manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
 /agy patch-cleanup        restore the original pi files if an older version patched them
 /agy clear                drop all session bindings (force fresh conversations)
@@ -204,7 +161,7 @@ Because agy runs non-interactively under this provider (nothing can answer a `y/
 
 If you want agy to execute nothing, use `/agy mode plan`. Do not combine `--sandbox` with skip-permissions ([#36](https://github.com/google-antigravity/antigravity-cli/issues/36)).
 
-For per-action review of agy's mutating native tools (`run_command`, `create_file`, `edit_file`, ...), see the [Approval gate](#approval-gate-agy-native-tools): 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.
+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.
 
 ### Run pi inside a sandbox
 

package/docs/APPROVAL-GATE.md

@@ -0,0 +1,33 @@
+# Approval gate (agy native tools)
+
+agy is not a plain model: it runs its own agent loop with its own native tools (`run_command`, `create_file`, `edit_file`, ...). Those calls execute inside agy with no pi involvement, so pi's permission extensions never saw them. The approval gate closes that gap: agy native tool calls pass through a pi-side approval in a form the existing permission-extension ecosystem gates with zero changes.
+
+Mechanics: the extension stages an `.agents/hooks.json` group in the workspace; the Antigravity server/CLI fires a `PreToolUse` hook before each mutating native tool runs. The hook script (generated, per-pid, mode 0600 because it embeds the bridge token) POSTs the call to the bridge and polls for a decision. The bridge parks it, the provider interrupts the pi-side view of the agy turn with a `toolUse` for a SHADOW tool named `bash`/`write`/`edit` (same schema as the real builtin plus internal `__agy*` marker fields), and pi's whole `tool_call` surface applies: any installed permission extension gates the call unchanged, and only if nothing blocks does the fallback policy run. The decision travels back to the hook and agy enforces it; on deny the reason text is what agy's model sees. Marker calls never execute locally (a ticket check denies forged ones); non-marker calls delegate to a factory twin of the real builtin, so normal pi bash/write/edit behavior is unchanged. Read-only agy tools stay ungated. Every decision lands in the daily log with tool names, source, and latency.
+
+Configuration (`/agy` config keys or environment):
+
+```jsonc
+{
+  "approvals": {
+    "gateMode": "auto",  // auto | shadow | dedicated | off
+    "mode": "ask"        // ask | allow | deny  (fallback when no extension gates)
+  }
+}
+// env: AGY_APPROVALS=shadow AGY_APPROVALS_MODE=ask
+```
+
+`auto` (default) keeps the gate OFF until one of the known pi permission packages is detected (pi settings `packages` name-match or known config markers). `shadow` forces it on; `off` forces it off. `dedicated` currently stages the same shadow tools (the explicit `antigravity_approve` variant is planned; the config value is accepted today so the schema is stable). The fallback `mode` is consulted only when no extension blocked the call: `ask` shows a pi confirm dialog (headless runs deny, fail-closed), `allow` approves, `deny` blocks. Timeouts deny fail-closed: the staged hook timeout always exceeds the park budget, but a hook that outlives its timeout soft-passes upstream (verified against the ACP server), so the park always answers first.
+
+If you write your own gate extension, it sees a normal pi tool call:
+
+```typescript
+export default function (pi) {
+	pi.on("tool_call", async (event) => {
+		if (event.input?.__agyGate && event.input.command?.startsWith("rm ")) {
+			return { block: true, reason: "rm is not allowed through the agy gate" };
+		}
+	});
+}
+```
+
+Live end-to-end verification (drive a real mutating agy turn through the gate) is still pending; see docs/TODO.md section 1.

package/docs/ARCHITECTURE.md

@@ -27,11 +27,12 @@ src/config.ts         persisted runtime config (engine + acp block, bridgeTools,
 src/daily-log.ts      daily NDJSON support log (one file per day, 14-day retention, secret redaction, AGY_DEBUG verbose gate); fed by both drivers, the bridge, round-trips, /agy, and ask-tool
 src/ask-tool.ts       the AskAntigravity one-shot delegation tool (model/thinking defaults)
 src/mcp-server.ts     MCP tool bridge server: ferries tools/list + tools/call; calls park in the provider round-trip. Also the approval park: POST /approval (ticket early-ack) + GET /approval/<id>, fail-closed on timeout/unwired/close
-src/mcp-registration.ts registers/unregisters the bridge in ~/.gemini/config/mcp_config.json for the stream-json CLI (per-pid, atomic, stale sweep)
+src/mcp-registration.ts registers/unregisters the bridge in ~/.gemini/config/mcp_config.json for the stream-json CLI (per-pid, atomic, stale sweep) and flips our entries off around AskAntigravity spawns (refcounted; session start re-enables)
 src/approval-gate.ts  shadow tool factory (bash/write/edit): marker calls are ticket-verified approval round-trips, non-marker calls delegate; maps agy native tools onto the shadow surface
 src/approval-detect.ts third-party pi permission-extension detection; resolves approvals.gateMode auto (off until a gate extension exists)
 src/approval-hook.ts  merge-safe .agents/hooks.json staging (PreToolUse) + generated 0600 early-ack/poll hook script; staged timeout exceeds the park budget (hook timeouts soft-pass)
 src/diff-render.ts    stream-json: render agy's file edits as git diffs in pi's thinking stream; formatInlineDiff (no git) renders ACP's native diffs
+src/engine-picker.ts  first-run onboarding: engine picker overlay (SelectList + DynamicBorder), first-run gate (no config file + no AGY_ENGINE), agy binary detection (PATH / AGY_BIN), missing-CLI toast copy
 src/driver-types.ts   TurnDriver contract shared by both engines (request/handle/snapshot types)
 src/acp/jsonrpc.ts    NDJSON JSON-RPC 2.0 framing with line buffering and typed error results
 src/acp/connection.ts ACP server process + protocol (initialize, session/new+load, prompt with image/resource blocks, config options, cancel probing, auto permissions)

package/docs/DEVELOPMENT.md

@@ -98,7 +98,8 @@ Most "stuck" reports trace to one of:
 - `tests/acp-driver.test.ts` - the ACP driver over the fake server (`tests/helpers/fake-acp-server.mjs`, scenario-selected): happy flow, load-replay, permission auto-answer, Gate D abort (cancel probe, teardown, `cancelSupported` memory), the stale-exit race (a killed connection's late exit must not fail its replacement - `ACP_FAKE_SLOW_DEATH_MS`), auth errors, park/kickIdle timer pause with remaining budget.
 - `tests/acp-config.test.ts` - engine selection narrowing (`AGY_ENGINE`/`config.engine`), acp block parsing.
 - `tests/daily-log.test.ts` - the support log: day rotation, retention cutoff boundary, secret redaction (incl. header blocks), the 4 KB record cap, never-throw on a broken dir, and the two-tier gate (debug records dropped unless `AGY_DEBUG`).
-- `tests/mcp-registration.test.ts` - the `~/.gemini/config/mcp_config.json` registration for the stream-json CLI: exact agy entry shape, foreign servers preserved, corrupt config refused, atomic writes, stale-entry sweep.
+- `tests/mcp-registration.test.ts` - the `~/.gemini/config/mcp_config.json` registration for the stream-json CLI: exact agy entry shape, foreign servers preserved, corrupt config refused, atomic writes, stale-entry sweep, delegation suppression (`setBridgeEntriesDisabled` flip/restore/idempotence, refcounted `acquireBridgeSuppression`).
+- `tests/engine-picker.test.ts` - first-run onboarding: picker gate (no config file + no AGY_ENGINE, fail-closed fs), option order (stream-json first), the ACP download/sign-in disclosure pins (intro + saved toast), agy binary detection (PATH scan, explicit path, fail-closed), missing-CLI toast copy.
 - `tests/provider-escalation.test.ts` - the early-ack + poll pipeline (escalation registry, poll views, late-delivery tombstones) and tool-result image forwarding on both engines.
 - `tests/approval-gate.test.ts` - the shadow tool factory: marker calls never execute, ticket verification denies forged/stale markers before the policy, denials throw, native-to-shadow mapping.
 - `tests/approval-park.test.ts` - the approval park end-to-end over a real (port 0) server: POST ticket early-ack, poll pending -> terminal, timeout deny, ungated/unwired deny, close fail-closed, provider round-trip (allow / block-deny / timeout), `__agy*` strip on G9 args.

package/docs/ENGINES.md

@@ -0,0 +1,46 @@
+# Engines
+
+Turns run through one of two engines behind the same provider surface (`config.engine`, default `stream-json`). The choice of engine is left to the user: a first-run picker explains the trade-offs and asks once, and `/agy engine` (no arguments, TUI) reopens the same modal anytime. Direct switches work too: `/agy engine acp|stream-json`.
+
+- **stream-json** (default): the persistent `agy` CLI process. The tested default; live token usage; conversation resume via `--conversation`.
+- **acp** (beta): Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery (see `scripts/parity-live.mjs`). Two known RC01 gaps remain: no usage fields (token display shows client-side ESTIMATES until Google ships usage; `acp.usageEstimate` off to keep zeros) and no cancel (abort tears the server down and reloads it next turn).
+
+## First run
+
+On a fresh install (no `config.json` yet), the first interactive pi start opens a picker modal that explains both engines - stream-json needs the `agy` CLI installed and authenticated; ACP needs a second Google sign-in plus a ~1.5 GB server binary downloaded from Google. stream-json is preselected (the default); `esc` decides later (nothing is written, the modal reappears on the next start).
+
+Picking **acp** starts the server download immediately (progress in the status bar, milestones in the chat), then opens the Google sign-in; a restart applies the engine. Picking **stream-json** persists and toasts; while that engine is active and the `agy` binary is missing, pi warns on every start with the install link until the binary shows up.
+
+## Capabilities
+
+| Capability | `stream-json` (default) | `acp` (beta) |
+| --- | --- | --- |
+| Show thinking text | No (token count only, floor 64, no text body) | Yes (streams thought text via `agent_thought_chunk`; sparse on RC01 where reasoning often arrives in message text) |
+| Live token usage | Yes (live metrics from CLI step events) | Estimated client-side (absent in RC01; `acp.usageEstimate`, default on) |
+| Image prompt input | No (CLI prompt is text-only; images dropped) | Yes (native image blocks forwarded to server) |
+| Image tool results | Yes (bridge tool results carry pixels; probe-verified 2026-09-07) | Yes (probe-verified 2026-09-05) |
+| Audio prompt input | No (dropped) | Protocol advertised (`promptCapabilities.audio: true`) |
+| Review-only plan mode | Yes (`--mode plan` review-only via `/agy mode plan`) | No (RC01 modes are permission levels; plan mode refused) |
+| Leading slash commands in prompt | Disabled via `--disable-slash-commands` (sent as plain text) | Server intercepts recognized commands (e.g. `/plan`) and executes them under the active policy |
+| Dynamic model / effort switch | Recycles process on model or effort change | Dynamic per-turn via `session/set_config_option` (no restart) |
+| Process lifecycle | 1 persistent `agy` process per provider; recycles on drift | 1 persistent server process hosting N sessions concurrently |
+| Session resume & persistence | Client-side map in `sessions.json` via `--conversation <id>` | Server-side session store via `session/load` and `session/new` |
+| Turn cancel / abort | Kills process group; in-flight turn terminates | Teardown, kill, and auto-reload on RC01 (-32601 fallback) |
+| MCP tool bridge routing | Injected filesystem config via `--add-dir` | Direct `mcpServers` param in `session/new` and `session/load` |
+| Tool execution & visibility | Native re-exec (read-only) + wrapper replay (mutating) | Server executes tools natively; events stream with content |
+| Inline file edit diffs | Sourced from git working tree in thinking block | Sourced from `tool_call content[]` or disk vs git HEAD |
+| Permission handling | `--dangerously-skip-permissions` (unattended CLI requirement) | Protocol-native `session/request_permission` (auto-approve when `skipPermissions` is on; auto-deny when off) |
+| Context digest delivery (G1) | Prepend plain text inline in prompt | Native `embeddedContext` resource block |
+| System prompt delivery (G10) | Prepend to first prompt of conversation | Prepend to first prompt of conversation |
+| Authentication methods | Inherits existing `agy` CLI OAuth state | 4 methods: `oauth-personal`, `oauth-business`, `gemini-api-key`, `agent-platform` |
+| Wire protocol | Undocumented CLI NDJSON stream format | Versioned JSON-RPC 2.0 over stdio (`protocolVersion: 1`) |
+| Diagnostics (`/agy doctor`) | Child PID, state, process spawns, recycles, queue stats | Server version, agentInfo, session counts, reconnect count, cancel support |
+| Integration channel | Spawns internal CLI stream-json dialect | Official Google first-party ACP server binary |
+
+## Engine-dependent features
+
+pi image attachments ride natively only on the ACP engine (the picker offers image attach automatically when `config.engine` is `acp`; the stream-json CLI prompt is text-only). With the optional G1 digest enabled, its delivery also differs: ACP ships it as a native `embeddedContext` resource block, stream-json prepends it to the prompt text. The `AskAntigravity` delegation tool is unaffected by `config.engine` and runs the `stream-json` CLI (`agy -p`) across both configurations.
+
+## Switching and setup
+
+Switch with `/agy engine acp|stream-json` (takes effect on restart), or run `/agy engine` with no arguments for the same picker modal as first run (an `acp` pick there runs the same download + sign-in chain). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: the same account and plan you use for the Antigravity CLI (`agy`). Sign in explicitly with `/agy auth` (engine `acp` selected): it opens the Google login in your browser and completes when you finish it. If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy auth-manual`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.

package/docs/TODO.md

@@ -2,7 +2,7 @@
 
 ## 1. Approval gate: live end-to-end verification
 
-The gate is wired and unit-pinned (304 tests) but has never run against a live
+The gate is wired and unit-pinned (333 tests) but has never run against a live
 agy turn. Enable it, drive an agy turn that mutates a file, and watch the
 round trip: PreToolUse hook -> POST /approval park -> shadow toolUse ->
 decision -> hook stdout -> agy enforces.

package/extensions/index.ts

@@ -66,11 +66,13 @@ import { setupAuthUrlCapture } from "../src/acp/browser-capture.js";
 import { ensureAcpReady, inspectAcpSetup } from "../src/acp/setup.js";
 import type { TurnDriver, TurnOutcome } from "../src/driver-types.js";
 import { CONFIG_PATH, loadConfig, logsDir, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
+import { agyMissingMessage, isAgyInstalled, savedEngineMessage, showEnginePicker, shouldOfferEnginePicker } from "../src/engine-picker.js";
 import { createDailyLogger, type DailyLogger } from "../src/daily-log.js";
 import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.js";
 import { startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
 import {
 	registerBridgeServer,
+	setBridgeEntriesDisabled,
 	sweepStaleBridgeServers,
 	unregisterBridgeServer,
 } from "../src/mcp-registration.js";
@@ -130,6 +132,12 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	const modelInput: Array<"text" | "image"> = engine === "acp" ? ["text", "image"] : ["text"];
 	const models = entries.map((e) => toPiModel(e, modelInput));
 
+	// failAll reasons the bridge treats as routine (turn end / shutdown
+	// sweep), not faults. Shared by the emitters below and the mcpLog
+	// classifier so the substring match cannot drift from the text.
+	const FAIL_REASON_TURN_END = "antigravity turn ended with an unresolved pi tool call";
+	const FAIL_REASON_SHUTDOWN = "antigravity session shut down";
+
 	// Daily file log: every sink below feeds ~/.pi/extensions-data/
 	// estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson (see
 	// src/daily-log.ts). Fire-and-forget, secrets redacted, old days pruned.
@@ -139,14 +147,15 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// routine disk traffic), so a warn that never reaches the UI is lost.
 	// Every warn toasts here instead; AGY_DEBUG=1 restores the full file
 	// trail. Silent exceptions: deliberate aborts (pi already shows
-	// "Operation aborted"), connection exits (the turn's own error block
-	// carries real crashes), and call-tool-fail (same-instant duplicate of
-	// round-trip-fail). No UI (headless): warn text falls back to stderr.
+	// "Operation aborted") and connection exits (the turn's own error block
+	// carries real crashes). call-tool-fail needs no exclusion here: its tier
+	// is debug or error, never warn. No UI (headless): warn text falls back
+	// to stderr.
 	const rawFileLog = fileLog.log.bind(fileLog);
 	fileLog.log = (event, data, level) => {
 		rawFileLog(event, data, level);
 		if (level !== "warn") return;
-		if (event.startsWith("abort:") || event === "connection-exited" || event === "call-tool-fail") return;
+		if (event.startsWith("abort:") || event === "connection-exited") return;
 		const d = (data ?? {}) as Record<string, unknown>;
 		let text: string;
 		if (event === "round-trip-fail") {
@@ -181,6 +190,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// ACP self-heal runs once per process (session_start re-fires on /reload;
 	// a ready setup is two file stats, so re-running is harmless anyway).
 	let acpSelfHealRan = false;
+	// Warn-once-per-process flag for the missing-agy-CLI toast (stream-json).
+	let agyMissingWarned = false;
 	// OAuth URL capture: the server hands the login URL only to the
 	// browser-open call (nothing on stdio), so a BROWSER wrapper records it
 	// and the driver logs it as "auth-url". Local users keep the automatic
@@ -276,6 +287,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		// Resolved per connection: the setup flow can install the binary and
 		// update acp.bin mid-session; the next turn picks it up (no restart).
 		bin: () => loadConfig().acp.bin,
+		// Resolved per turn: /agy and AGY_USAGE_ESTIMATE changes apply without
+		// a restart. Without this the driver defaults to "estimate" and the
+		// config knob (incl. "off") is dead.
+		usageEstimate: () => loadConfig().acp.usageEstimate,
 		...(authCapture ? { extraEnv: authCapture.browserEnv, authUrlFile: authCapture.file } : {}),
 		log: acpLog,
 		mcpServers: () => {
@@ -334,7 +349,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			{ status: outcome.status, error: outcome.error?.slice(0, 500), aborted: outcome.aborted },
 			outcome.status === "OK" ? "info" : "warn",
 		);
-		roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
+		roundTrips.failAll(FAIL_REASON_TURN_END);
 	};
 	streamDriver.onTurnEnd = onTurnEnd;
 	acpDriver.onTurnEnd = onTurnEnd;
@@ -380,6 +395,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		acpLog,
 		fileLog,
 		authCapture: authCapture ?? null,
+		runAcpPickSetup,
 	});
 
 	// AskAntigravity tool: one-shot delegation to agy (ported from
@@ -412,12 +428,115 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		},
 	});
 
+	/** ACP pick follow-through (first-run wizard): the same self-service
+	 *  setup the /agy engine acp command runs, but immediately - the 1.5 GB
+	 *  download starts while the toast is still on screen, progress rides the
+	 *  footer status, and the Google sign-in opens when the install lands.
+	 *  Restart still applies the engine (drivers wire at load); this only
+	 *  removes the wait. Fire-and-forget: the caller already toasted the
+	 *  promise, failures land in the daily log + a warning toast. */
+	// eslint-disable-next-line @typescript-eslint/no-inner-declarations -- hoisted: registerAgyCommand below injects it
+	async function runAcpPickSetup(ctx: { ui: ExtensionUIContext }): Promise<void> {
+		acpSelfHealRan = true;
+		let lastPhase = "";
+		ctx.ui.setStatus("agy-acp", "downloading ACP server…");
+		try {
+			const status = await ensureAcpReady({
+				configBin: loadConfig().acp.bin,
+				onProgress: (m) => {
+					// Dual surface: the status bar carries the live percent (cleared
+					// on completion, zero footprint); the chat window gets phase
+					// milestones only (download start, unpacking, installed) - same
+					// line-in-chat feel as other extensions' notify() notices. The
+					// percent variant updates every chunk and would spam the chat.
+					ctx.ui.setStatus("agy-acp", m);
+					if (m !== lastPhase && !/\d+%/.test(m)) {
+						ctx.ui.notify(m, "info");
+						lastPhase = m;
+					}
+				},
+			});
+			ctx.ui.setStatus("agy-acp", undefined);
+			fileLog.log(
+				"acp-setup",
+				status.ok
+					? { ok: true, binarySource: status.binarySource, needsLogin: status.needsLogin }
+					: { ok: false, error: status.error },
+				status.ok ? "info" : "warn",
+			);
+			if (!status.ok) {
+				ctx.ui.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
+				return;
+			}
+			// Spread, not a bare acp patch: a bare {bin} patch would drop
+			// sibling keys (usageEstimate) from the file.
+			saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
+			if (!status.needsLogin) {
+				ctx.ui.notify(`ACP server ready (auth: ${status.auth}). Restart applies the engine.`, "info");
+				return;
+			}
+			ctx.ui.notify(
+				"ACP server ready. Signing in: the Google sign-in opens in your browser and completes when you finish it.",
+				"info",
+			);
+			const r = await runAcpAuth({
+				bin: status.bin,
+				...(authCapture ? { extraEnv: authCapture.browserEnv, authUrlFile: authCapture.file } : {}),
+				log: acpLog,
+			});
+			fileLog.log("acp-auth", r.ok ? { ok: true } : { ok: false, error: r.error }, r.ok ? "info" : "warn");
+			if (r.ok) ctx.ui.notify("Signed in. The ACP engine is ready; restart applies it.", "info");
+			else ctx.ui.notify(`ACP sign-in failed (${r.error}).\nRun /agy auth to retry; /agy auth-manual has manual steps.`, "warning");
+		} catch (err) {
+			ctx.ui.setStatus("agy-acp", undefined);
+			fileLog.log("acp-setup", { error: String(err) }, "warn");
+			ctx.ui.notify(`ACP setup failed (${String(err)}). /agy auth retries; /agy doctor inspects.`, "warning");
+		}
+	}
+
 	// MCP tool bridge: expose pi's tools to agy over localhost Streamable HTTP.
 	// Calls park in the provider's round-trip store and complete through pi's
 	// normal toolUse loop (native cards, permissions, hooks) - no patch, no
 	// privileged API. Started on session_start, torn down on session_shutdown.
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (event, ctx) => {
 		if (ctx.hasUI) activeUi = ctx.ui;
+		// First-run engine picker: ask once, on the first interactive start,
+		// which turn engine to use. Skipped headless (ctx.mode !== "tui"),
+		// when AGY_ENGINE is set, or once any config file exists (any save -
+		// even of an unrelated knob - means the user has been here before).
+		// esc = decide later: nothing is written, the picker reappears next
+		// start. Like /agy engine, the choice applies on the next start
+		// (drivers wire at load). The await intentionally runs before the
+		// bridge startup below: on a genuine first run the modal blocks input
+		// anyway, so the delay is invisible.
+		if (event.reason === "startup" && ctx.mode === "tui" && shouldOfferEnginePicker(CONFIG_PATH)) {
+			// Best-effort, like the legacy-patch notice below: a picker failure
+			// (mid-prompt TUI teardown, resize races) must never take down the
+			// rest of session_start - the MCP bridge startup included. The
+			// default engine keeps working untouched.
+			try {
+				const picked = await showEnginePicker(ctx.ui);
+				if (picked) {
+					saveConfig({ engine: picked });
+					ctx.ui.notify(savedEngineMessage(picked), "info");
+					if (picked === "acp") void runAcpPickSetup(ctx);
+				}
+			} catch (err) {
+				fileLog.log("engine-picker", { error: String(err) }, "warn");
+				console.error(`[antigravity-bridge] engine picker failed: ${String(err)}`);
+			}
+		}
+		// agy presence check (stream-json engine): the CLI is the whole engine,
+		// so a missing binary means every Antigravity turn would fail. Warn on
+		// every process start until it is installed (per-process flag so /new,
+		// /resume and /reload re-fires do not nag mid-session). Runs after the
+		// picker above, so a first-run stream-json pick warns immediately.
+		if (engine === "stream-json" && !agyMissingWarned && !isAgyInstalled(binary)) {
+			agyMissingWarned = true;
+			const msg = agyMissingMessage();
+			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
+			else console.error(`[antigravity-bridge] ${msg}`);
+		}
 		// Legacy cleanup: users who ran the old consent-gated patcher still
 		// carry pi.invokeTool in their installed pi. Inert, but tell them once
 		// and offer /agy patch-cleanup. Never auto-edits the install.
@@ -451,7 +570,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 				);
 				if (status.ok) {
 					if (status.binarySource === "installed" || status.binarySource === "existing") {
-						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+						saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
 					}
 					if (status.needsLogin) {
 						const msg = acpLoginPending();
@@ -482,18 +601,27 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			// filters below only decide what reaches the user. Bridge calls
 			// start/end at info (one record per tool call, the fragile-path
 			// skeleton); list-tools and startup chatter stay verbose.
-			const level = failures.has(s)
-				? "warn"
-				: s === "call-tool" || s === "call-tool-ok"
+			// Routine abort traffic (failAll on turn end / session shutdown
+			// answers every parked call with an error) is not a fault: debug
+			// only. Any other call-tool-fail is a real rejection (e.g. "no
+			// active antigravity turn" from a client that should not see the
+			// bridge) and lands at error tier - default mode records errors
+			// only, so this is the sole durable trace of the incident.
+			const detail = (d as { msg?: string } | undefined)?.msg ?? "";
+			const routineAbort =
+				s === "call-tool-fail" &&
+				(detail.includes(FAIL_REASON_TURN_END) || detail.includes(FAIL_REASON_SHUTDOWN));
+			const level = !failures.has(s)
+				? s === "call-tool" || s === "call-tool-ok"
 					? "info"
-					: "debug";
+					: "debug"
+				: routineAbort
+					? "debug"
+					: s === "call-tool-fail"
+						? "error"
+						: "warn";
 			fileLog.log(s, d, level);
-			// Routine abort traffic: failAll fires on turn end / session shutdown
-			// and the bridge answers every parked call with an error. Not a fault.
-			if (s === "call-tool-fail") {
-				const detail = (d as { msg?: string } | undefined)?.msg ?? "";
-				if (detail.includes("unresolved pi tool call") || detail.includes("session shut down")) return;
-			}
+			if (routineAbort) return;
 			if (!failures.has(s)) return;
 			const msg = `[antigravity-bridge mcp] ${s}${d !== undefined ? " " + JSON.stringify(d) : ""}`;
 			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
@@ -597,11 +725,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		);
 		if (r.ok && r.handle) {
 			mcpHandle = r.handle;
-			// Stream-json engine registration: the agy CLI discovers MCP servers
-			// from ~/.gemini/config/mcp_config.json (ACP uses session/new
-			// mcpServers instead; verified live 2026-09-07). Per-pid entry,
-			// removed at session_shutdown; stale entries swept at start.
+			// Stale entries swept at start; entries a crashed delegation left
+			// suppressed are healed here (live bridges start every session
+			// enabled).
 			sweepStaleBridgeServers();
+			setBridgeEntriesDisabled(false);
 			registerBridgeServer({
 				pid: process.pid,
 				port: r.handle.port,
@@ -705,7 +833,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		const h = mcpHandle;
 		mcpHandle = null;
 		await h?.close();
-		roundTrips.failAll("antigravity session shut down");
+		roundTrips.failAll(FAIL_REASON_SHUTDOWN);
 		// "recycle", NOT "shutdown": pi fires session_shutdown on /new, /resume
 		// and /fork (docs/extensions.md session lifecycle), not only on process
 		// exit. The drivers are process-lifetime singletons; closing them with
@@ -755,6 +883,9 @@ interface AgyCommandCtx {
 	acpLog: (msg: string, data?: unknown) => void;
 	/** Daily file logger (src/daily-log.ts); command + doctor surfacing. */
 	fileLog: DailyLogger;
+	/** Wizard-pick follow-through (download now + chained sign-in); reused
+	 *  by /agy engine's no-args modal so both entry points behave alike. */
+	runAcpPickSetup: (cmdCtx: { ui: ExtensionUIContext }) => Promise<void>;
 	/** BROWSER-capture handles; null when unavailable (Windows, unwritable
 	 *  data dir). /agy auth passes them to the sign-in process. */
 	authCapture: { browserEnv: Record<string, string>; file: string } | null;
@@ -866,7 +997,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
 						return;
 					}
-					saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+					saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
 					if (status.needsLogin) {
 						ui?.notify(
 							`ACP engine set. ${acpLoginPending()}`,
@@ -875,6 +1006,28 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					} else {
 						ui?.notify(`ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`, "info");
 					}
+				} else if (!val && mode === "tui" && ui) {
+					// Same modal as the first-run wizard: switching engines deserves
+					// the explanations, not a bare usage line. Semantics match the
+					// direct path above: plan blocks acp, an acp pick chains setup
+					// + sign-in immediately, restart applies the switch.
+					const current = loadConfig().engine;
+					const picked = await showEnginePicker(ui);
+					if (picked === null) {
+						ui.notify(`engine unchanged: ${current}.`, "info");
+						return;
+					}
+					if (picked === current) {
+						ui.notify(`engine is already ${current}. Restart applies it if set this session.`, "info");
+						return;
+					}
+					if (picked === "acp" && loadConfig().mode === "plan") {
+						ui.notify("mode is plan; the ACP engine has no plan mode. /agy mode accept-edits first.", "warning");
+						return;
+					}
+					saveConfig({ engine: picked });
+					ui.notify(savedEngineMessage(picked), "info");
+					if (picked === "acp") void ctx.runAcpPickSetup({ ui });
 				} else {
 					ui?.notify(`current engine: ${loadConfig().engine}\nusage: /agy engine stream-json|acp`, "info");
 				}
@@ -901,7 +1054,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
 					return;
 				}
-				saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+				saveConfig({ acp: { ...loadConfig().acp, bin: status.bin } });
 				if (!status.needsLogin) {
 					ui?.notify(`Already signed in (auth: ${status.auth}). Nothing to do.`, "info");
 					return;
@@ -929,7 +1082,9 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				if (rest.length > 0) {
 					// Only the keyword compares case-insensitively; the path keeps its case.
 					const bin = rest.toLowerCase() === "auto" ? "" : rest.replace(/^~(?=\/|$)/, os.homedir());
-					saveConfig({ acp: { bin, permissions: loadConfig().acp.permissions } });
+					// Spread, not a bare acp patch: a bare {bin, permissions} object
+					// would drop sibling keys (usageEstimate) from the file.
+					saveConfig({ acp: { ...loadConfig().acp, bin } });
 					ui?.notify(
 						bin
 							? `acp.bin set to ${bin}. The next ACP turn (re)connects with it.`
@@ -999,6 +1154,8 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					// line the day it starts (then real usage mapping is worth wiring).
 					if (snap.acp.usageSeen) {
 						lines.push("  acp tokens:    AVAILABLE in server payloads (wire real usage mapping next)");
+					} else if (config.acp.usageEstimate !== "off") {
+						lines.push(`  acp tokens:    ESTIMATED client-side (mode: ${config.acp.usageEstimate}; auto-off once the server sends real usage)`);
 					}
 				}
 				if (snap.lifecycle.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.4.10",
+  "version": "1.5.1",
   "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. antigravity/* models in Pi's /model picker, no-patch MCP bridge: agy runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",

package/src/acp/driver.ts

@@ -19,9 +19,12 @@
 //     in-connection (plan §9.3); no provider involvement
 
 import { randomUUID } from "node:crypto";
+import type { UsageEstimate } from "../config.js";
 import { AcpConnection, resolveAcpBinary, type AcpMcpServer } from "./connection.js";
 import { mapStopReason, mapUpdate, TextAccumulator, type AcpEditDiff } from "./events.js";
+import { estimateTokens, synthesizeUsage } from "./usage-estimate.js";
 import type {
+	AgyUsage,
 	DriverActivity,
 	DriverSnapshot,
 	DriverState,
@@ -46,6 +49,10 @@ export interface AcpDriverOptions {
 	authUrlFile?: string;
 	/** Bridge registration for session/new AND session/load. */
 	mcpServers?: () => AcpMcpServer[];
+	/** Gate B stopgap: how ACP turns synthesize usage while the server sends
+	 *  none. A function is resolved per turn (follows live config, like bin).
+	 *  Default "estimate". */
+	usageEstimate?: UsageEstimate | (() => UsageEstimate);
 	log?: (msg: string, data?: unknown) => void;
 }
 
@@ -59,6 +66,13 @@ interface ActiveTurn {
 	resolve: (o: TurnOutcome) => void;
 	outcome: Promise<TurnOutcome>;
 	response: TextAccumulator;
+	/** Usage-synthesis counters: per-delta token sums (estimate mode) and
+	 *  delta counts (direct mode). Sums are taken per delta, never over the
+	 *  joined text, so a word split across chunks stays two words. */
+	textTokens: number;
+	thoughtTokens: number;
+	textDeltas: number;
+	thoughtDeltas: number;
 	sawResult: boolean;
 	/** True once the prompt RPC was issued. Abort before this point has
 	 *  nothing to cancel: probing would risk a success-as-noop answer from a
@@ -359,10 +373,16 @@ export class AcpDriver implements TurnDriver {
 		switch (mapped.kind) {
 			case "text": {
 				const emit = turn.response.append(mapped.delta);
-				if (emit) this.#emit(turn, { type: "text", delta: emit });
+				if (emit) {
+					turn.textDeltas += 1;
+					turn.textTokens += estimateTokens(emit);
+					this.#emit(turn, { type: "text", delta: emit });
+				}
 				return;
 			}
 			case "thought": {
+				turn.thoughtDeltas += 1;
+				turn.thoughtTokens += estimateTokens(mapped.delta);
 				this.#emit(turn, { type: "thought", delta: mapped.delta });
 				return;
 			}
@@ -543,6 +563,10 @@ export class AcpDriver implements TurnDriver {
 			resolve,
 			outcome,
 			response: new TextAccumulator(),
+			textTokens: 0,
+			thoughtTokens: 0,
+			textDeltas: 0,
+			thoughtDeltas: 0,
 			sawResult: false,
 		promptStarted: false,
 			aborted: false,
@@ -643,6 +667,16 @@ export class AcpDriver implements TurnDriver {
 
 	#settle(turn: ActiveTurn, outcome: TurnOutcome): void {
 		if (turn.closed) return;
+		// Gate B stopgap: synthesize usage on clean turns while the server sends
+		// none. Runs BEFORE close so the usage activity drains through the
+		// normal #nextActivity loop (provider maps it onto partial.usage).
+		if (outcome.status === "OK" && !outcome.aborted && outcome.usage === undefined) {
+			const usage = this.#syntheticUsage(turn);
+			if (usage) {
+				outcome.usage = usage;
+				this.#emit(turn, { type: "usage", usage });
+			}
+		}
 		turn.closed = true;
 		if (turn.overallTimer) clearTimeout(turn.overallTimer);
 		if (turn.idleTimer) clearTimeout(turn.idleTimer);
@@ -671,6 +705,29 @@ export class AcpDriver implements TurnDriver {
 		});
 	}
 
+	/** Usage synthesis mode, resolved per turn (follows live config). */
+	#usageMode(): UsageEstimate {
+		const opt = this.#opts.usageEstimate;
+		return (typeof opt === "function" ? opt() : opt) ?? "estimate";
+	}
+
+	#syntheticUsage(turn: ActiveTurn): AgyUsage | undefined {
+		const mode = this.#usageMode();
+		if (mode === "off") return undefined;
+		// Gate B latch: any server frame with usage/token keys means real
+		// usage exists upstream; estimates must never shadow it.
+		if (this.#conn?.usageSeen) return undefined;
+		return synthesizeUsage({
+			mode,
+			prompt: turn.request.prompt,
+			contextText: turn.request.contextBlock?.text,
+			textTokens: turn.textTokens,
+			thoughtTokens: turn.thoughtTokens,
+			textDeltas: turn.textDeltas,
+			thoughtDeltas: turn.thoughtDeltas,
+		});
+	}
+
 	#log(msg: string, data?: unknown): void {
 		const line = `${new Date().toISOString().slice(11, 19)} ${msg}${data !== undefined ? ` ${JSON.stringify(data)}` : ""}`;
 		this.#lifecycle.push(line);

package/src/acp/usage-estimate.ts

@@ -0,0 +1,59 @@
+// Gate B stopgap: synthesize AgyUsage for ACP turns until Google ships a
+// real token-usage layer in agy_acp_server. Counting mechanism copied from
+// the pi-token-speed extension (npm:pi-token-speed, src/engine.ts): a
+// word/punctuation regex, 1 match = 1 token. The numbers are client-side
+// ESTIMATES, never provider data: the connection's usageSeen latch (Gate B
+// watch) keeps synthesis off the day real usage appears in any frame, so
+// estimates can never shadow real numbers.
+
+import type { UsageEstimate } from "../config.js";
+import type { AgyUsage } from "../driver-types.js";
+
+const TOKEN_REGEX = /\w+|[^\s\w]/g;
+
+/** Word-boundary token estimate (pi-token-speed's estimateTokens). */
+export function estimateTokens(text: string): number {
+	if (!text) return 0;
+	const matches = text.match(TOKEN_REGEX);
+	return matches ? matches.length : 0;
+}
+
+export interface UsageEstimateInput {
+	mode: UsageEstimate;
+	/** Full outgoing prompt text (input side; always regex-estimated). */
+	prompt: string;
+	/** ACP embeddedContext resource text (G1 digest): also reaches the model. */
+	contextText?: string;
+	/** Per-delta token sums (mode "estimate"). Summing per delta, like
+	 *  pi-token-speed's recordDelta, avoids word-merge artifacts when a
+	 *  chunk boundary splits a word. */
+	textTokens: number;
+	thoughtTokens: number;
+	/** Streamed delta counts (mode "direct": 1 token per delta). */
+	textDeltas: number;
+	thoughtDeltas: number;
+}
+
+/** Synthesize usage for a finished turn, or undefined when nothing is worth
+ *  reporting (mode off, or a turn with no prompt and no output). */
+export function synthesizeUsage(input: UsageEstimateInput): AgyUsage | undefined {
+	if (input.mode === "off") return undefined;
+	const inputTokens = estimateTokens(
+		input.contextText ? `${input.prompt}\n${input.contextText}` : input.prompt,
+	);
+	const thoughtTokens =
+		input.mode === "direct" ? input.thoughtDeltas : input.thoughtTokens;
+	const textTokens =
+		input.mode === "direct" ? input.textDeltas : input.textTokens;
+	// Thinking folds INTO output (OpenAI convention: reasoning tokens bill as
+	// output). toPiUsage drops thinking_tokens, and thinking time is inside
+	// elapsed wall time, so folding keeps the tokens/time ratio honest.
+	const outputTokens = textTokens + thoughtTokens;
+	if (inputTokens === 0 && outputTokens === 0) return undefined;
+	return {
+		input_tokens: inputTokens,
+		output_tokens: outputTokens,
+		thinking_tokens: thoughtTokens,
+		total_tokens: inputTokens + outputTokens,
+	};
+}

package/src/ask-tool.ts

@@ -25,6 +25,7 @@ import {
 	snapshotConversations,
 } from "./discovery.js";
 import { loadConfig, type AgyMode, type ThinkingTier } from "./config.js";
+import { acquireBridgeSuppression } from "./mcp-registration.js";
 import { spawnAgyModelsRaw } from "./models.js";
 
 // --- Constants -------------------------------------------------------------
@@ -46,6 +47,15 @@ const FAMILY_DEFAULT_TIER: Record<Family, ThinkingTier> = {
 	pro: "high",
 	other: "medium",
 };
+
+/** Bridge-suppression grace for a delegated `agy -p`. The shared config stays
+ *  disabled for min(process close, this): agy reads it once at startup, so
+ *  this bound covers that read without staying disabled for the whole run.
+ *  Residual race: a provider agy respawn in ANOTHER session landing inside
+ *  the window reads the entries disabled and that process lacks bridge tools
+ *  until its next recycle (session start heals the file). Fail-open past the
+ *  window = status-quo behavior. */
+const BRIDGE_SUPPRESS_MS = 5000;
 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.
@@ -510,6 +520,31 @@ export async function registerAskAntigravityTool(
 			const binary = process.env.AGY_BIN || "agy";
 			let out = "";
 
+			// Delegation isolation: any agy on this machine reads the global
+			// mcp_config.json, so this spawned `agy -p` would discover live
+			// pi-bridge-* entries and call tools the host bridge cannot serve
+			// outside a live provider turn ("no active antigravity turn").
+			// Delegation isolation: any agy on this machine reads the global
+			// mcp_config.json, so this spawned `agy -p` would discover live
+			// pi-bridge-* entries and call tools the host bridge cannot serve
+			// outside a live provider turn ("no active antigravity turn").
+			// Window = min(close, grace): the release fires on process close or
+			// after BRIDGE_SUPPRESS_MS, whichever lands first. Refcounted, so an
+			// overlapping delegation cannot re-enable early. A refused config
+			// fail-opens to the status quo.
+			const releaseBridge = acquireBridgeSuppression();
+			let suppressTimer: ReturnType<typeof setTimeout> | undefined = setTimeout(
+				releaseBridge,
+				BRIDGE_SUPPRESS_MS,
+			);
+			const restoreBridge = (): void => {
+				if (suppressTimer) {
+					clearTimeout(suppressTimer);
+					suppressTimer = undefined;
+				}
+				releaseBridge();
+			};
+
 			const statusInterval = onUpdate
 				? setInterval(() => {
 						const elapsed = Math.floor((Date.now() - start) / 1000);
@@ -592,6 +627,7 @@ export async function registerAskAntigravityTool(
 						if (watchdog) clearTimeout(watchdog);
 						if (sigkillTimer) clearTimeout(sigkillTimer);
 						if (signal) signal.removeEventListener("abort", onAbort);
+						restoreBridge();
 					};
 					const onAbort = () => killTree();
 
@@ -698,6 +734,9 @@ export async function registerAskAntigravityTool(
 				return { content: [{ type: "text", text: `failed to run agy: ${msg}` }], details };
 			}
 			finally {
+				// Belt and braces: cleanup() already restores on close/error; this
+				// covers paths that never reached the process (sync spawn throw).
+				restoreBridge();
 				if (contextFile) {
 					try {
 						fs.unlinkSync(contextFile);

package/src/config.ts

@@ -44,6 +44,12 @@ export type AgyMode = "accept-edits" | "plan";
 export type ThinkingTier = "low" | "medium" | "high";
 export type BridgeTools = "none" | "mcp" | "all";
 
+/** How ACP turns report token usage while Gate B stands (agy sends none).
+ *  "estimate" (default): word-boundary regex over prompt/response/thought
+ *  text (pi-token-speed's mechanism). "direct": 1 token per streamed delta.
+ *  "off": keep zero-usage. Real server usage (usageSeen latch) always wins. */
+export type UsageEstimate = "estimate" | "direct" | "off";
+
 /** How the approval gate activates (docs/TODO.md section 2.5).
  *
  *  "auto" (default): OFF until a third-party pi permission extension is
@@ -74,6 +80,10 @@ export interface AcpConfig {
 	 *  (parity with skipPermissions). Kept as a key so future policies do not
 	 *  change the config shape. */
 	permissions: "auto";
+	/** Gate B stopgap: client-side token estimates for ACP turns so pi's
+	 *  usage surfaces show nonzero numbers. Estimates are labeled as such in
+	 *  /agy doctor and auto-disable when the server sends real usage. */
+	usageEstimate: UsageEstimate;
 }
 
 export interface AgyConfig {
@@ -149,7 +159,7 @@ const DEFAULTS: AgyConfig = {
 	digest: false,
 	systemPrompt: true,
 	approvals: { gateMode: "auto", mode: "ask" },
-	acp: { bin: "", permissions: "auto" },
+	acp: { bin: "", permissions: "auto", usageEstimate: "estimate" },
 };
 
 /** Load config merged over defaults. Env vars override the file when set. */
@@ -232,11 +242,19 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 			: "ask";
 
 	const fileAcp = (typeof file.acp === "object" && file.acp !== null ? file.acp : {}) as Partial<AcpConfig>;
+	// Unknown values fall back to "estimate" (same narrow-parse pattern as
+	// gateMode: a typo must never silently change behavior).
+	const usageRaw = String(
+		process.env.AGY_USAGE_ESTIMATE ?? fileAcp.usageEstimate ?? DEFAULTS.acp.usageEstimate,
+	).toLowerCase();
+	const usageEstimate: UsageEstimate =
+		usageRaw === "direct" || usageRaw === "off" ? usageRaw : "estimate";
 	const acp: AcpConfig = {
 		bin:
 			process.env.AGY_ACP_BIN ??
 			(typeof fileAcp.bin === "string" ? fileAcp.bin : DEFAULTS.acp.bin),
 		permissions: "auto",
+		usageEstimate,
 	};
 
 	return {

package/src/engine-picker.ts

@@ -0,0 +1,155 @@
+// First-run onboarding: the engine picker plus the agy-presence warning.
+//
+// On the first interactive start (no config file yet, no AGY_ENGINE env) pi
+// asks which turn engine to use: the stream-json `agy` CLI or Google's
+// official ACP server. The choice persists via saveConfig({ engine }) and,
+// like /agy engine, takes effect on the next pi start (drivers wire at load).
+// Every start with the stream-json engine active also re-checks that the
+// `agy` binary exists and warns until it does (re-auth is out of scope).
+//
+// UI: tui.md "Pattern 1" - SelectList framed by DynamicBorder inside pi's
+// native overlay (the window feel pi-rtk builds its modal on).
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	type SelectItem,
+	SelectList,
+	Spacer,
+	Text,
+} from "@earendil-works/pi-tui";
+import fs from "node:fs";
+import path from "node:path";
+import type { Engine } from "./config.js";
+
+/** Picker order is the default answer order: stream-json first. */
+export const ENGINE_PICKER_ITEMS: SelectItem[] = [
+	{
+		value: "stream-json",
+		label: "Stream-JSON CLI",
+		description: "default, recommended",
+	},
+	{
+		value: "acp",
+		label: "ACP server (official Google)",
+		description: "second sign-in, ~1.5 GB binary download",
+	},
+];
+
+/** Intro paragraph above the list. Text wraps, so explanations stay here and
+ *  SelectItem descriptions stay one-liners (SelectList truncates long lines). */
+export const ENGINE_PICKER_INTRO = [
+	"Pick the engine that runs your Antigravity turns. Switch anytime with /agy engine (restart applies it).",
+	"",
+	"stream-json: the `agy` CLI you already installed and authenticated. Persistent process, streamed output. Tested default.",
+	"ACP: Google's official server (agy_acp_server.par). Needs a second Google sign-in and a ~1.5 GB server binary downloaded from Google (automatic, one-time, unavoidable: the server is not part of the agy CLI).",
+].join("\n");
+
+/** True only for a genuine first interactive run: no saved config yet (any
+ *  existing file means the user has been here before) and no AGY_ENGINE env
+ *  (env wins over the file, so the wizard would fight it). Fails closed to
+ *  false - an fs error must never nag the user with a dialog. */
+export function shouldOfferEnginePicker(
+	configPath: string,
+	env: NodeJS.ProcessEnv = process.env,
+): boolean {
+	if (env.AGY_ENGINE !== undefined) return false;
+	try {
+		return !fs.existsSync(configPath);
+	} catch {
+		return false;
+	}
+}
+
+/** Narrow a picker value to an Engine. Items are our own constants, but an
+ *  unknown value must never reach config as a cast string: it falls back to
+ *  the tested default. */
+export function toEngine(value: string): Engine {
+	return value === "acp" ? "acp" : "stream-json";
+}
+
+/** Toast copy shown after the choice is saved. ACP names the promise that
+ *  matters: the binary download starts NOW (not on restart), sign-in follows
+ *  when it lands, restart applies the engine. */
+export function savedEngineMessage(engine: Engine): string {
+	return engine === "acp"
+		? "Engine saved: acp. The ~1.5 GB server binary downloads now; the Google sign-in opens when it lands. Restart applies the engine."
+		: "Engine saved: stream-json. Restart pi to apply.";
+}
+
+/** True when the `agy` CLI binary can be found. A binRef with a path
+ *  separator (AGY_BIN=/opt/agy/agy) must exist as a file; a bare name is
+ *  searched on PATH. statSync cannot throw through the guards, but a race
+ *  (file removed between listing and stat) fails closed to false. */
+export function isAgyInstalled(binRef: string, env: NodeJS.ProcessEnv = process.env): boolean {
+	if (binRef.includes("/")) {
+		try {
+			return fs.statSync(binRef).isFile();
+		} catch {
+			return false;
+		}
+	}
+	return (env.PATH ?? "")
+		.split(path.delimiter)
+		.filter(Boolean)
+		.some((dir) => {
+			try {
+				return fs.statSync(path.join(dir, binRef)).isFile();
+			} catch {
+				return false;
+			}
+		});
+}
+
+/** Toast copy for the missing-CLI warning. Fires every pi start while the
+ *  stream-json engine is active and the binary is absent. */
+export function agyMissingMessage(): string {
+	return "The `agy` CLI is not installed. Install it from https://antigravity.google/product/antigravity-cli and log in on it to use Antigravity models.";
+}
+
+/** Render the picker overlay. Resolves with the chosen engine, or null when
+ *  the user pressed esc (decide later - nothing is persisted). */
+export async function showEnginePicker(ctx: ExtensionUIContext): Promise<Engine | null> {
+	return ctx.custom<Engine | null>(
+		(tui, theme, _keybindings, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold("Antigravity Bridge: choose your engine")), 1, 0),
+			);
+			container.addChild(new Text(theme.fg("muted", ENGINE_PICKER_INTRO), 1, 0));
+			container.addChild(new Spacer(1));
+
+			const list = new SelectList(ENGINE_PICKER_ITEMS, ENGINE_PICKER_ITEMS.length, {
+				selectedPrefix: (t: string) => theme.fg("accent", t),
+				selectedText: (t: string) => theme.fg("accent", t),
+				description: (t: string) => theme.fg("muted", t),
+				scrollInfo: (t: string) => theme.fg("dim", t),
+				noMatch: (t: string) => theme.fg("warning", t),
+			});
+			list.onSelect = (item) => done(toEngine(item.value));
+			list.onCancel = () => done(null);
+			container.addChild(list);
+
+			container.addChild(new Spacer(1));
+			container.addChild(
+				new Text(theme.fg("dim", "↑↓ navigate · enter select · esc decide later"), 1, 0),
+			);
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+			return {
+				render: (width: number) => container.render(width),
+				invalidate: () => container.invalidate(),
+				handleInput: (data: string) => {
+					list.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: { anchor: "center" as const, width: 80, maxHeight: "85%" as const, margin: 1 },
+		},
+	);
+}

package/src/mcp-registration.ts

@@ -93,6 +93,61 @@ export function unregisterBridgeServer(pid: number, configPath: string = mcpConf
 	return { wrote: true };
 }
 
+/** Flip `disabled` on every pi-bridge-* entry (foreign servers untouched).
+ *
+ *  (1) Delegation isolation: the global config is read by ANY agy on the
+ *  machine, so an `agy -p` we spawn ourselves (AskAntigravity) would discover
+ *  live bridge entries and call tools the round-trip store cannot serve
+ *  outside a live provider turn (fail-closed "no active antigravity turn",
+ *  observed live 2026-09-15). agy reads the config once at startup, so a
+ *  short suppression window around the spawn hides the bridge from it.
+ *
+ *  (2) Startup healing (disabled=false): clears entries a crashed delegation
+ *  left suppressed. */
+export function setBridgeEntriesDisabled(
+	disabled: boolean,
+	configPath: string = mcpConfigPath(),
+): { wrote: boolean; changed: number; reason?: string } {
+	const read = readConfig(configPath);
+	if (!read.ok) return { wrote: false, changed: 0, reason: read.reason };
+	let changed = 0;
+	for (const [name, entry] of Object.entries(read.config.mcpServers)) {
+		if (!/^pi-bridge-\d+$/.test(name)) continue;
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const e = entry as { disabled?: unknown };
+		if ((e.disabled === true) === disabled) continue;
+		e.disabled = disabled;
+		changed++;
+	}
+	if (changed === 0) return { wrote: false, changed: 0 };
+	writeConfig(configPath, read.config);
+	return { wrote: true, changed };
+}
+
+const suppressionRefs = new Map<string, number>();
+
+/** Reference-counted suppression for a self-spawned agy process (AskAntigravity
+ *  delegation). First acquire disables every pi-bridge-* entry, last release
+ *  re-enables; nested acquires are free, so overlapping delegations in one
+ *  process cannot clobber each other's window. Same-process only: delegations
+ *  from two pi sessions still race on the shared file - accepted, fail-open
+ *  to the status-quo error. */
+export function acquireBridgeSuppression(configPath: string = mcpConfigPath()): () => void {
+	const key = path.resolve(configPath);
+	const refs = (suppressionRefs.get(key) ?? 0) + 1;
+	suppressionRefs.set(key, refs);
+	if (refs === 1) setBridgeEntriesDisabled(true, configPath);
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		const left = Math.max(0, (suppressionRefs.get(key) ?? 1) - 1);
+		if (left === 0) suppressionRefs.delete(key);
+		else suppressionRefs.set(key, left);
+		if (left === 0) setBridgeEntriesDisabled(false, configPath);
+	};
+}
+
 /** Default liveness probe: can the signal be delivered? */
 function pidAlive(pid: number): boolean {
 	try {