@estebanforge/pi-antigravity-bridge 1.4.8 → 1.4.10

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.10] - 2026-09-07
+
+### Added
+
+- Approval gate for agy native tool calls. agy runs its own agent loop, and its mutating native tools (`run_command`, `create_file`, `edit_file`, ...) executed with no pi involvement: pi's permission extensions never saw them. The gate routes the calls through a pi-side approval in builtin shape, so the existing permission-extension ecosystem gates them with zero changes: a staged `.agents/hooks.json` `PreToolUse` hook parks the call in the bridge, the provider emits a pi `toolUse` for a builtin-shaped shadow tool (`bash`/`write`/`edit`), and the decision - allow, or deny with a reason the model sees - travels back to the hook. Marker calls never execute locally and are verified against the bridge's pending-ticket set (a forged marker denies even in allow mode); non-marker calls delegate to factory twins of the real builtins, so normal pi behavior is unchanged. Read-only agy tools stay ungated. Opt-in via `approvals.gateMode` (`auto`, the default, keeps it off until a known pi permission extension is detected; `shadow` forces on; `off` forces off) and `approvals.mode` (`ask`, the default, shows a pi confirm dialog and denies headless; `allow`/`deny` skip the dialog). Timeout, an unwired gate, and shutdown all deny fail-closed. Every decision lands in the daily log with tool names, source, and latency. README has the full section plus a sample gate extension.
+
+### Fixed
+
+- Concurrent pi sessions on the same workspace no longer disable each other's approval gate. The staged `hooks.json` group was one shared key, so a second session resolving the gate to `off` deleted the first session's live gate, and two gate-on sessions overwrote each other's port/token/script. Groups are now keyed per session (`pi-bridge-gate-<pid>`), shutdown removes only the session's own group, and the next staging sweeps groups whose owning session is dead (found by an external pre-release audit).
+- The shared `~/.gemini/config/mcp_config.json` now lands `0600` (dir `0700`). It carries the bridge's shared-secret token and previously landed at the umask default (typically world-readable) (found by an external pre-release audit).
+- Bridge tools now register for the stream-json engine. That engine registered nothing: the agy CLI discovers MCP servers from `~/.gemini/config/mcp_config.json`, which the bridge never wrote (only the per-invocation `--add-dir` config existed), and the gap was masked because the daily engine is ACP. The bridge now registers itself there per-pid (`pi-bridge-<pid>`) at session start, sweeps stale entries left by crashed sessions, and unregisters on shutdown. Foreign servers in the shared file are preserved; a corrupt file is refused, never rewritten. Probe-verified live: agy discovers the server and completes tool calls through its native `call_mcp_tool` wrapper.
+- Image blocks in tool results now reach the model on the stream-json engine too (they were ACP-only). The engine gate downgraded pixels to a text label over an unverified transport concern; a live probe settled it - the CLI's MCP client delivers tool-result image content, and the model named a two-tone PNG's halves from the tool result alone with no decoders in the frame trail. `read` on an image file now gives agy real pixels on both engines. Stream-json prompt attachments and the late-delivery prompt stay text-only by design.
+
+## [1.4.9] - 2026-09-05
+
+### Added
+
+- Warn toasts in the pi UI: bridge tool failures, stalls, timeouts, process exits, and other warnings surface as native warning notifications the moment they happen, so users see them and can report them. Over SSH or without a UI the same text falls back to stderr. Deliberate aborts, connection exits (the turn's own error block carries real crashes), and `call-tool-fail` (same-instant duplicate of `round-trip-fail`) stay silent.
+- Gate B watch in `/agy doctor`: the ACP connection latches the first `session/update` payload that carries usage/token fields, and doctor prints one "acp tokens: AVAILABLE" line when that happens. Silent until then; the day the line appears, wiring real token counts becomes a small mapping job. Auth-style string `"token"` keys inside tool frames cannot trip the latch.
+
+### Fixed
+
+- Esc-abort on the ACP engine no longer dumps the dying server's raw stderr tail (a google3 stack trace) into the transcript. Teardown exits (abort kill, shutdown, idle recycle) are marked expected and never render; a genuine mid-turn crash surfaces as the turn's own clean error block instead. Raw tails still land in the file log for post-mortems.
+
+### Changed
+
+- The ACP engine is now beta. Parity is verified live against RC01 (text streaming, multi-turn resume, bridge tools, effort switching, serialization, abort recovery - see `scripts/parity-live.mjs`), so it graduates from opt-in-experimental to a supported alternative engine. It stays behind `config.engine` for now; the two known RC01 gaps (no usage fields, kill+reload abort) are documented in the README.
+- Daily log volume: the default tier now writes ONLY errors, so a regular session costs the disk nothing. Warns live in the UI (see above); `AGY_DEBUG=1` restores the full debug/info/warn/error trail for reproducing a problem. Docs: README debug-logs section, `/agy doctor` hint.
+- The tool-priority note now steers agy's native `view_file` (artifact-sandboxed on RC01) to the Pi Bridge file tools (`read`, `ls`, `grep`, `find`, `edit`, `execute`) for any real filesystem path. Observed live: repeated `invalid_args` rejections on `operator/pkg/tmux/client.go` before the model fell back to `edit`.
+
 ## [1.4.8] - 2026-09-05
 
 ### Added

package/README.md

@@ -21,15 +21,16 @@ 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**: Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Opt-in while it matures: the current build (RC01) ships no usage fields (token display shows zero) and no cancel (abort tears the server down and reloads it next turn). Everything else is parity-verified live - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery - see `scripts/parity-live.mjs`.
+- **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).
 
 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.
 
-| Capability | `stream-json` (default) | `acp` |
+| 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 |
@@ -57,7 +58,7 @@ 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, same as every other tool in pi. See [Permissions](#permissions) below.
+- 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.
 - 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)
@@ -91,6 +92,38 @@ your pi Agent Skills catalog; calling it returns the SKILL.md body. The bridge
 answers it directly, no pi round-trip. `/agy doctor` prints driver counters,
 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):
+
+```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" };
+		}
+	});
+}
+```
+
 ## Install
 
 > **No patch required.** The bridge runs on pi's public APIs only; the extension never edits your pi install. If an older version of this extension patched your pi (adding `pi.invokeTool()`), the leftover is inert and a pi update removes it. The extension detects it once and offers `/agy patch-cleanup` to restore the original files from the backup immediately.
@@ -157,7 +190,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 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)
 /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)
@@ -171,6 +204,8 @@ 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.
+
 ### Run pi inside a sandbox
 
 For isolation when running any agent that executes commands without a confirmation gate, run pi inside [**construct-cli**](https://github.com/EstebanForge/construct-cli) - EstebanForge's sandbox for AI agents. Isolated container, no path escape, ephemeral filesystem, `strict` / `offline` network modes, secret redaction. The blast radius of a bad command stays in the container, not your host. Install and usage instructions are in that repo.
@@ -188,7 +223,7 @@ For isolation when running any agent that executes commands without a confirmati
 | `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_DEFAULT_MODEL` | Default model alias for the `AskAntigravity` tool (`flash`/`pro`/`gemini`, or a tier/version qualifier). Wins over the config file. |
 | `AGY_DEFAULT_THINKING` | Default thinking tier for the `AskAntigravity` tool: `low`/`medium`/`high`. Anything else falls back to `medium`. Wins over the config file. |
-| `AGY_DEBUG` | `1`/`true`/`on` writes verbose debug records to the daily log (driver lifecycle, raw bridge traffic). Default off: only the light info/warn/error stream. |
+| `AGY_DEBUG` | `1`/`true`/`on` writes the full trail to the daily log (driver lifecycle, raw bridge traffic). Default off: **only `error` records land on disk** - routine disk writes are zero for regular users, and warnings surface as UI toasts instead. |
 
 ## Debug logs
 
@@ -198,14 +233,14 @@ The extension keeps a daily log on your machine, sorted by day:
 ~/.pi/extensions-data/estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson
 ```
 
-One JSON record per line. Two verbosity tiers keep the disk cost negligible for regular users: by default only `info`/`warn`/`error` records land on disk, which is the useful skeleton: turn starts and outcomes with error text (both engines), bridge tool calls, escalations and poll traffic, late deliveries, and round-trip failures, `AskAntigravity` runs, `/agy` commands, ACP setup/self-heal, auth URLs, and every driver failure (stall, abort, timeout, nonzero exit). Set `AGY_DEBUG=1` before reproducing a problem for the full trail: per-event driver lifecycle (spawn, exit, session load/new, unparks), list-tools traffic, recycle causes, and the raw bridge chatter. `/agy doctor` prints the log directory.
+One JSON record per line. Two verbosity tiers keep the disk cost at zero for regular users: by default only `error` records land on disk - everything routine (turn starts, tool calls, escalations, commands, driver failures) is withheld. Warnings are not lost: the extension toasts each one in the pi UI (bridge tool failures, stalls, timeouts, process exits), so users see them and can report them; deliberate aborts and failures pi already renders as the turn's own error block stay silent. Set `AGY_DEBUG=1` before reproducing a problem for the full trail: per-event driver lifecycle (spawn, exit, session load/new, unparks), turn starts and outcomes, bridge tool calls, escalations and poll traffic, late deliveries, list-tools traffic, recycle causes, and the raw bridge chatter. `/agy doctor` prints the log directory.
 
 Notes:
 
 - Retention: 14 days. Older files are pruned automatically.
 - Privacy: prompt text, tool arguments, and tool output never land in the log. Secret-shaped values (tokens, API keys, credentials, header blocks) are redacted, and long strings are truncated. The `auth-url` record strips the login URL's query string.
 - Logging never throws: an unwritable directory is skipped silently and retried on the next record.
-- SSD wear: default volume is a handful of records per turn. Verbose mode (`AGY_DEBUG=1`) writes more; turn it off after reproducing.
+- SSD wear: default volume is effectively zero until something actually errors. Verbose mode (`AGY_DEBUG=1`) writes more; turn it off after reproducing.
 
 When you report an issue, attach the last day or two of files from that directory. For anything that needs reproduction, run with `AGY_DEBUG=1` once and attach that day's file. They usually contain the exact failure sequence (engine, session, bridge call, error) with no need to guess.
 

package/docs/ACP-ADOPTION-PLAN.md

@@ -46,8 +46,11 @@ Adopt the official Google ACP server (`agy_acp_server.par`, registry id
 `antigravity-acp`) as a second turn engine for the bridge, behind a config
 switch. The existing stream-json engine stays the default until the ACP
 engine proves parity. Every change is an improvement or a one-to-one
-replacement. No functionality is removed until a later phase deletes the
-streaming engine on purpose.
+replacement.
+
+STANDING DECISION (user, 2026-09-07): BOTH engines are permanently
+maintained peers. The streaming engine is never deleted - no phase removes
+it, regardless of upstream progress (including Gate B).
 
 Cross-references: [ARCHITECTURE.md](./ARCHITECTURE.md),
 [PI-BRIDGE-GAPS.md](./PI-BRIDGE-GAPS.md), [DEVELOPMENT.md](./DEVELOPMENT.md).
@@ -165,8 +168,8 @@ is an unmaintained contract. ACP is the maintained one.
 | Module | Role today | Disposition under ACP |
 | --- | --- | --- |
 | `src/provider.ts` | streamSimple: pi Context to agy turn to pi events; G9 round-trips; G1 digest; G10 system prompt | KEEP unchanged (additive thought-delta `if` only). Engine-agnostic by contract |
-| `src/driver.ts` | persistent stream-json process, turn queue, recycle, timers | KEEP as streaming engine. DELETE in phase 4 |
-| `src/stream-events.ts` | NDJSON parser + usage mapping | KEEP as streaming. DELETE in phase 4 |
+| `src/driver.ts` | persistent stream-json process, turn queue, recycle, timers | KEEP permanently - both engines are maintained peers |
+| `src/stream-events.ts` | NDJSON parser + usage mapping | KEEP permanently - both engines are maintained peers |
 | `src/sessions.ts` | pi session to agy conversation store | KEEP. Add `engine` tag (section 9.4) |
 | `src/config.ts` | runtime config | KEEP. Add engine + acp block (section 9.5) |
 | `src/models.ts` | `agy models` to pi Model projection | KEEP. Catalog source stays the CLI until ACP exposes one (probe A.6) |
@@ -200,7 +203,7 @@ in git history.
 | Cancel | Kill process group; in-flight turn dies | `session/cancel` to `stopReason: cancelled`, process survives | **REGRESSION-MANAGED (Gate D FAIL on RC01): cancel NOT implemented.** Fallback kill + `session/load` VERIFIED; re-check per build |
 | Process lifecycle | One agy child per provider; recycle on model/effort/mode/cwd/conversation drift | One server hosts N sessions | IMPROVEMENT |
 | Model + effort selection | CLI flags + recycle | `session/set_config_option` (`configId`) | PASS (VERIFIED live, Gate A): per-session switching, no recycle |
-| Usage tokens | `toPiUsage` from step events | Not in any payload (Gate B FINAL) | **ABSENT on RC01.** Zero-usage documented; stream-json retained as secondary engine; phase-4 deletion conditioned on Gate B lift |
+| Usage tokens | `toPiUsage` from step events | Not in any payload (Gate B FINAL) | **ABSENT on RC01.** Zero-usage documented and ACCEPTED for the flip (user decision 2026-09-07: Gate B no longer blocks the default). Both engines are permanently maintained - no deletion |
 | MCP tools (G9) | Our HTTP bridge server via `--add-dir` config | `mcpServers` param (`{name,type:"http",url,headers:[]}`) | PARITY at shape level (verified). Phase-1 acceptance: bridge `tools/list`+`tools/call` end-to-end |
 | Skills | `--disable-slash-commands`; bridge owns skills | Unknown slash behavior; `available_commands_update` exists | PARITY. Keep our bridge; probe F.7 |
 | G1 digest, G10 system prompt | Provider-side prompt assembly | Same (we compose the prompt either way) | PARITY. `embeddedContext` is a later enhancement |
@@ -318,7 +321,7 @@ Tested with the parity suite (section 11) and `scripts/parity-live.mjs`
 
 | Risk | Impact | Mitigation |
 | --- | --- | --- |
-| Usage tokens absent (CONFIRMED, Gate B) | Cost/token display zeros on ACP | Zero-usage documented; stream-json retained as SECONDARY engine until upstream ships usage — phase-4 deletion is conditioned on Gate B lifting (review 4, finding 2) |
+| Usage tokens absent (CONFIRMED, Gate B) | Cost/token display zeros on ACP | ACCEPTED 2026-09-07 (user decision): Gate B no longer blocks the default flip - zero-usage is documented behavior on ACP. Both engines are permanently maintained; no deletion (standing decision), so zero-usage is opt-in per user forever (review 4, finding 2, as amended) |
 | ~~No model/effort switch per session~~ RESOLVED: Gate A PASS | — | `session/set_config_option` verified live; per-session switching, no recycle |
 | Slash commands expanded server-side | Could double-expand with our prompt assembly | Probe F.7. If present: keep our prefixes out of command-looking lines, or ignore server command list |
 | `request_permission` with no pi-side permission UI | Cannot render a native dialog | Single `auto` policy (parity with `skipPermissions: true`); per-tool gating for pi tools belongs to the tools/extensions and is preserved end-to-end by G9 (9.3). Never hang |
@@ -463,7 +466,7 @@ src/acp/connection.ts  process lifecycle: spawn AGY_ACP_BIN, initialize
                        / load / prompt / cancel / set_config_option, client-side
                        method handlers (request_permission policy, fs, terminal),
                        outbound event queue.
-src/acp/driver.ts      AcpDriver: implements the AgyDriver surface (section 9.2)
+src/acp/driver.ts      AcpDriver: implements the StreamDriver surface (section 9.2)
                        so provider.ts keeps working unchanged. State machine,
                        timers, parks, snapshot, close.
 src/acp/events.ts      session/update to DriverActivity mapping + stopReason
@@ -475,7 +478,7 @@ scripts/smoke-acp.mjs  live smoke, gated by AGY_ACP_LIVE=1 (spends quota),
 
 ### 9.2 Driver contract (unchanged surface, additive only)
 
-`AcpDriver` matches the existing `AgyDriver` public surface: `state`,
+`AcpDriver` matches the existing `StreamDriver` public surface: `state`,
 `activeHandle`, `run()`, `reentry()`, `kickIdle()`, `set onTurnEnd()`,
 `snapshot()`, `close()`. `DriverActivity` gains one additive variant; the
 streaming engine never emits it:
@@ -490,8 +493,9 @@ streaming engine never emits it:
 the current token-count behavior. One `if`, additive, streaming untouched.
 
 Interface extraction (review 2, finding 7): `provider.ts` imports the
-concrete `AgyDriver` class today; deleting `driver.ts` in phase 4 would break
-the import. Phase 1 extracts a `TurnDriver` interface into a neutral module
+concrete `StreamDriver` class today; without a neutral type the two engine
+wirings would each drag the other's module in. Phase 1 extracts a
+`TurnDriver` interface into a neutral module
 (`src/driver-types.ts`); both drivers implement it; `provider.ts` and
 `ToolRoundTrips` depend on the interface only. `/agy engine` changes require
 a pi restart (driver wiring happens at extension load); a live engine router
@@ -771,21 +775,22 @@ Acceptance: parity suite remains 14/14, doctor parity, no breakage to stream-jso
 
 Status: 🚧 Phase 3 remaining items are COMPLETE (2026-09-04): 168/168 tests,
 tsc clean, live parity 14/14, embeddedContext verified live (resource block
-with a secret word answered correctly). Remaining phase-3 acceptance:
-deleted-code census lands with phase 4's deletions (nothing deletes in
-phase 3 — the streaming modules stay for the `stream-json` engine).
+with a secret word answered correctly). Phase-3 acceptance: nothing deletes
+in phase 3 — the streaming modules stay (permanently, see the standing
+decision at the top and Phase 4).
 
-### Phase 4: default flip and streaming deletion (deferred, next month)
+### Phase 4: default flip (deferred)
 
 All items below are deferred until a full soak cycle of both engines has completed and upstream conditions are met:
 
 1. AskAntigravity migration to ACP one-shot (migrating while `stream-json` is default breaks streaming-only users who haven't onboarded ACP auth; streaming conversation ids cannot resume under ACP). `mode: "plan"` delegations keep the `agy -p --mode plan` path (committed exception).
 2. Delete `src/discovery.ts` (`/proc` fd-scan) once AskAntigravity migration completes.
-3. Default flip: `config.engine` default becomes `"acp"` after one full release soak cycle with both engines shipping. Gate A PASS is verified.
-4. Upstream Gate B resolution: Google ships usage counters in ACP payloads.
-5. Streaming engine deletion: `src/driver.ts`, `src/stream-events.ts`, and streaming tests deleted one release after the flip AND only once Gate B has lifted (so zero-usage is never forced).
+3. Default flip: `config.engine` default becomes `"acp"` after one full release soak cycle with both engines shipping. Gate A PASS is verified. Gate B is NOT a precondition (lifted as a blocker 2026-09-07); the soft items in section 17 ship in the same release.
+4. Upstream Gate B resolution (optional, informational): Google ships usage counters in ACP payloads. The `/agy doctor` watch reports it when it happens. Mapping it in is a small additive job; the streaming engine stays regardless.
+
+NO deletion phase: the streaming engine is a permanently maintained peer (standing user decision, 2026-09-07). The old phase-4 "streaming deletion" item is void.
 
-Acceptance: default-flip release ships with the parity suite as acceptance evidence; deletion release has zero references to the removed modules.
+Acceptance: the default-flip release ships with the parity suite as acceptance evidence.
 
 ## 11. Test strategy
 
@@ -873,3 +878,63 @@ answers: model catalog ships in `session/new` (CLI catalog unnecessary on
 ACP); edits surface as diffs inside `tool_call` content even with fs
 capabilities off; no usage fields anywhere; available_commands_update carries
 `plan` and `logout`; cold start ~5-6 s, steady RSS ~327 MB.
+
+## 17. Default-flip readiness (phase 4) — analysis as of 2026-09-07
+
+Standing analysis so nobody re-derives it: what blocks flipping the default
+engine from stream-json to ACP. Re-verify only the dated facts (Gate B
+status via `/agy doctor`); the structural conclusions hold.
+
+**Verdict: nothing blocks the flip. Gate B was REMOVED as a blocker on
+2026-09-07 (user decision: token usage does not matter for the extension's
+purpose - agy runs on subscription quota, cost stays zero either way).
+Zero-usage on ACP is accepted as documented behavior. Remaining before the
+flip: the four soft items below, shipped in the same release.**
+
+Already green:
+
+- Parity contract (section 6) is ALL `[x]`, live-verified on both engines
+  (parity suite 14/14).
+- Everything shipped since 1.4.9 is engine-aware: bridge registration is
+  ACP-native (`session/new` mcpServers) AND stream-json-native
+  (`~/.gemini/config/mcp_config.json`); tool-result images ride both engines
+  (probe-verified on each); the approval gate's ACP hook firing is the
+  LIVE-verified side (stream-json is docs-attested only), so the flip does
+  not weaken it.
+- Rollback is one config flip; sessions are engine-scoped so bindings never
+  cross.
+
+Former blocker — Gate B, LIFTED 2026-09-07:
+
+- RC01 sends no usage/token fields in ANY payload, so ACP shows zero
+  tokens. This used to block the default flip; the user lifted it: agy
+  runs on subscription quota and cost is zero regardless, so the display
+  gap is cosmetic for this extension. Zero-usage on ACP is documented
+  behavior.
+- Both engines are PERMANENTLY maintained (standing user decision
+  2026-09-07): no deletion phase exists, regardless of Gate B. stream-json
+  is the supported fallback/secondary forever; zero-usage is opt-in per
+  user by choosing the engine.
+- The `/agy doctor` Gate B watch stays armed as INFORMATIONAL: it prints
+  "acp tokens: AVAILABLE" if upstream ever ships usage, at which point the
+  mapping is a small additive job.
+
+Soft items to ship alongside the flip (not blockers):
+
+1. Clean-machine first-run: ACP as DEFAULT means fresh installs hit the
+   self-setup path (binary install + auth bootstrap) immediately. Self-heal
+   exists; never tested as the first-run experience. Test once on a clean
+   env.
+2. User-visible abort change: Esc on ACP = kill + reconnect + reload (RC01
+   has no `session/cancel`). Document in README and `/agy status`.
+3. Pull soak evidence from the daily logs (warn rates per engine, 1.4.9+)
+   and attach to this section.
+4. Note that `AskAntigravity` stays on `agy -p` regardless (phase 4+).
+
+Mechanics of the flip (minutes): default in `src/config.ts` + the
+`acp-config` test default + README engine table + AGENTS.md + beta wording.
+`AGY_ENGINE` env override keeps an escape hatch either way.
+
+Recommendation on record: Gate B is no longer a condition. Remaining
+pre-flip work is the soft items above; the flip itself is a small,
+mechanical change whenever the soak cycle is judged complete.

package/docs/ACP-PROTOCOL-REFERENCE.md

@@ -259,9 +259,10 @@ unreachable on RC01 — no cancel method).
 
 NO usage/token fields appeared anywhere in `initialize`, `session/new`,
 `set_config_option`, `agent_message_chunk`, prompt results, or tool flows
-(run 6). Gate B FINAL: ABSENT on RC01. Consequence in the plan: stream-json
-is retained as a secondary engine until upstream ships usage (phase-4
-deletion conditioned on Gate B lifting).
+(run 6). Gate B FINAL: ABSENT on RC01. Consequence in the plan (updated
+2026-09-07): Gate B is INFORMATIONAL - zero-usage is documented and accepted
+on ACP, never a blocker. Both engines are permanently maintained peers; no
+deletion is planned.
 
 ## session/cancel
 

package/docs/ARCHITECTURE.md

@@ -26,7 +26,11 @@ src/sessions.ts       atomic JSON store: pi session -> agy conversation + waterm
 src/config.ts         persisted runtime config (engine + acp block, bridgeTools, digest, mode, permissions, model/thinking defaults)
 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
+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/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/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
@@ -71,9 +75,10 @@ The pre-1.3.0 engine (spawn `agy -p`, poll the SQLite conversation DB, decode pr
 
 `config.engine: "acp"` (or `/agy engine acp`) routes turns through Google's
 official ACP server (`agy_acp_server.par`, registry id `antigravity-acp`)
-over JSON-RPC stdio. Off by default; stream-json remains the default and a
-supported secondary — phase-4 deletion is conditioned on upstream shipping
-usage fields (Gate B), per docs/ACP-ADOPTION-PLAN.md.
+over JSON-RPC stdio. Off by default; stream-json remains the default. BOTH
+engines are permanently maintained peers (standing decision - no deletion,
+regardless of Gate B). Gate B (absent usage fields) is informational:
+zero-usage is documented on ACP. See docs/ACP-ADOPTION-PLAN.md section 17.
 
 Modules: `src/acp/jsonrpc.ts` (framing/correlation), `src/acp/connection.ts`
 (process + protocol methods + in-connection `auto` permission answering),
@@ -85,7 +90,9 @@ Phase-2/3 additions (all ACP-only, verified live):
 
 - **Images**: pi image attachments ride as typed content blocks in the
   prompt array; models advertise `input: ["text","image"]` only when the
-  engine is `acp` (decided at extension load). stream-json stays text-only.
+  engine is `acp` (decided at extension load). stream-json prompt input
+  stays text-only (tool-RESULT images ride both engines; see
+  PI-BRIDGE-GAPS).
 - **Digest delivery**: with `config.digest` on, ACP ships the G1 digest as
   a native `embeddedContext` resource block (images → resource → text);
   stream-json keeps it inline. Same cache churn either way.

package/docs/DEVELOPMENT.md

@@ -57,6 +57,18 @@ AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
 AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
   npx tsx scripts/probe-acp-phase2.mjs
 
+# Live probe: does the ACP server deliver MCP tool-result IMAGE content to
+# the model? One bridge tool returns a two-tone PNG in its result; the model
+# must name both halves from the tool result alone.
+AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
+  npx tsx scripts/probe-acp-image-result.mjs
+
+# Live probe: same image question for the stream-json engine. AGY
+# bridge tool returns a two-tone PNG in its result; model must name both
+# halves. AGY_PROBE_REG_ONLY=1 skips the turn and dumps MCP registration
+# state (no quota).
+AGY_LIVE=1 npx tsx scripts/probe-stream-json-image.mjs
+
 # Live parity run: the SAME scenario set (streaming, continuity, bridge
 # round-trip, effort switch, serialization, abort+recover, usage) through
 # BOTH engines. Needs the agy CLI AND the ACP binary. Spends ~13 flash-low
@@ -86,6 +98,10 @@ 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/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.
 
 ## Module map
 

package/docs/PI-BRIDGE-GAPS.md

@@ -61,13 +61,34 @@ Weighed and rejected; kept so they are not re-proposed.
   credentials, so agy already uses pi's creds for every tool; a
   credential never crosses the bridge. A `pi_get_setting` accessor was
   predicated on credential reuse that does not apply.
-- **Image / binary content blocks over the bridge** — NOT NEEDED. pi shares
-  the path to any image it produces (e.g. `/tmp/pi-clipboard-<uuid>.png`), and agy
+- **Image / binary content blocks over the bridge** — DONE (ACP engine).
+  Reopened 2026-09-05: the prior verdict below was falsified. On the ACP
+  engine, native `view_file` rejects real filesystem paths (artifact sandbox;
+  the tool-priority note steers agy to bridge tools), and bridge `read`
+  flattened pi's tool result with `blocksToText`, which drops the image block.
+  agy received only the label text and fell back to shell + `mcp-cli-ent
+  ai-vision`. Probe `scripts/probe-acp-image-result.mjs` (2026-09-05) proved
+  the ACP server delivers MCP tool-result image content to the model (PASS:
+  the model identified a two-tone PNG from the tool result alone, with no
+  image in the prompt). Fix: image blocks in parked pi tool results now ride
+  bridge results as MCP image content on the ACP engine (fast resolve path,
+  escalation registry, and `bridge_poll_result`), so `read` on an image file
+  gives agy real pixels. DONE on stream-json too (probe
+  `scripts/probe-stream-json-image.mjs`, 2026-09-07: the CLI's MCP client
+delivers tool-result image content to the model — two-tone PNG named from
+the result alone, bridge tool called once, zero decoders in the frame
+trail). Image blocks now ride parked pi tool results on both engines
+(fast resolve path, escalation registry, and `bridge_poll_result`), so
+`read` on an image file gives agy real pixels everywhere. Still
+text-only, deliberately: the late-delivery prompt
+(`buildLateResultPrompt`), and the stream-json prompt attachments.
+  Superseded verdict (kept for the record): NOT NEEDED. pi shares the path to
+  any image it produces (e.g. `/tmp/pi-clipboard-<uuid>.png`), and agy
   reaches and reads those files directly via the bridge's `read` tool, so
   returning image content blocks over the transport would duplicate a path
-  that already works end-to-end. No agy transport change or pi patch required.
-  Update (2026-09-04): user-provided image *attachments* now ride natively on
-  the ACP engine as typed prompt content blocks (see README, Two
+  that already works end-to-end. No agy transport change or pi patch
+  required. Update (2026-09-04): user-provided image *attachments* now ride
+  natively on the ACP engine as typed prompt content blocks (see README, Two
   engines); the stream-json CLI prompt stays text-only, and the bridge
   direction above is unchanged.
 - **File-watching / live state** — DECLINED. agy is request-response

package/docs/TODO.md

@@ -0,0 +1,21 @@
+# TODO
+
+## 1. Approval gate: live end-to-end verification
+
+The gate is wired and unit-pinned (304 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.
+
+- Enable without a third-party extension: `AGY_APPROVALS=shadow AGY_APPROVALS_MODE=ask` (interactive pi; headless denies). Deny path: a fake gate extension that blocks marker calls (`pi.on("tool_call")` + `{block: true, reason}`).
+- Probe artifacts live outside the repo: `~/tmp/pi-antigravity-bridge-probes/` (run scripts via `npx tsx` from the repo cwd - they import src/*.ts).
+- Live-behavior risks to watch: hook timeout soft-passes (V3) - the staged timeout must keep exceeding the park budget; denied calls emit no `tool_call` session/update frames on ACP (V2); edit-class arg names beyond `create_file` are docs-attested, never live-captured - check the confirm-dialog text on a real `run_command` and a real `replace_file_content`.
+- On pass: clear the "NOT yet live-verified" notes (AGENTS.md, this file).
+
+## 2. Explicit `antigravity_approve` variant (dedicated mode)
+
+`approvals.gateMode: "dedicated"` currently stages the same shadow tools
+(warn-logged remap). Planned: one registered tool `antigravity_approve` with
+input `{toolName, args}`, for setups that prefer explicit names (gotgenes
+`shellTools` alias users). Full v2 spec preserved in git history:
+`dd7845b:docs/TODO.md` (sections 2.1-2.9).