# ACP Adoption Plan: Official Google `antigravity-acp` Server

Status: PROPOSED. Phase 0 COMPLETE + Phase 1 COMPLETE (2026-09-03): ACP engine
implemented behind `config.engine` (default off), full suite green, live smoke
PASS through the full stack. Gate F VERIFIED live (`scripts/smoke-acp-bridge.mjs`):
the real server lists bridge tools and completes a tool call through the
registered mcpServers entry. §6 parity run LIVE on both engines: 14/14
(`scripts/parity-live.mjs`). Phase-1 acceptance: ALL `[x]` (docs included).
Gates: A PASS, B ABSENT (managed — streaming engine retained
until upstream ships usage), C PASS, D FAIL on RC01 (kill+reload fallback
VERIFIED live, incl. the stale-exit race fix), E PASS, F PASS (verified
live 2026-09-03). Verdicts in section 8.1; full captured protocol data in
[ACP-PROTOCOL-REFERENCE.md](./ACP-PROTOCOL-REFERENCE.md); raw traffic
gitignored in `probe-logs/`.
Peer review 1: Claude, 2026-09-03. Verdict PROCEED WITH CHANGES. Findings 1-6
integrated: third round-trip kind for permissions (P1), parked-overall-timer
pause (P1), cumulative-resend guard port, deferred-capability dispositions,
capability-posture prose, concurrency note.
Peer review 2: Antigravity (agy), 2026-09-03. Verdict PROCEED WITH CHANGES.
7 findings integrated: Gate A made a blocking gate for the default flip (the
ACP binary takes no model flags, so the recycle fallback could not carry a
model), sessions re-keyed per engine (`@acp` suffix) after the engine-field
design was shown to erase streaming bindings on rollback, parked-timer pause
changed to remaining-budget semantics, acp-permission plumbing specified
through a TurnDriver interface, session/cancel + session/close pulled into
phase 1, AskAntigravity migration moved from phase 3 to phase 4.
Peer reviews 3-4 (plan-stage second rounds, Claude and agy): findings folded
into the two entries above and the section 8/9 design; no separate deltas.
Peer review 5 (implementation): Antigravity (agy), 2026-09-03. Verdict
PROCEED WITH CHANGES. 7 findings, all valid, all fixed: P0 jsonrpc line
buffering (stdio chunks are not newline-aligned; partial frames were dropped),
P1 tool args preserved through tool_done, P1 typed protocol errors survive
translation (cancelSupported stuck null), P1 parked-deadline nulled on pause,
P2 tilde expansion, P2 per-turn config read dedup, P2 coverage gaps filled.
Peer review 6 (post-build): Claude, 2026-09-03, isolated and read-only.
Verdict PROCEED WITH CHANGES. 6 findings, 5 valid, all fixed: P1 bridge 403
gate had no vitest coverage (HTTP-level test added: no header / wrong-length /
same-length wrong token → 403, correct → 200), P1 sessionKey recorded the
config engine instead of the selected driver's (fixed), P2 arm-time park
left a stale deadline (fixed: paused-from-birth invariant), P2 duplicated
timeout body (extracted), P2 abort-before-prompt probed cancel (now guarded
by promptStarted). Sixth finding (untracked parity script) resolved by
commit.

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.

Cross-references: [ARCHITECTURE.md](./ARCHITECTURE.md),
[PI-BRIDGE-GAPS.md](./PI-BRIDGE-GAPS.md), [DEVELOPMENT.md](./DEVELOPMENT.md).

## 1. Decision summary

| Question | Answer |
| --- | --- |
| Adopt? | Yes, phased, behind `config.engine: "acp"` |
| Why | Protocol-native permissions, image prompts, thought text, graceful cancel, session resume/list, sanctioned auth path, stable public protocol |
| Why not a rewrite | The provider layer (G1 digest, G10 system prompt, G9 park/resume, pi event mapping) is engine-agnostic and already proven. The driver is the only engine-coupled part |
| Default flip | Phase 4, after a soak release with both engines |
| Regression guard | Parity checklist (section 6) must be all `[x]` before the default flips |

## 2. Verified evidence

All facts below were verified live on 2026-09-03, not taken from docs. Probe
artifacts live in `~/tmp/agy-acp-probe/` (binary, handshake transcripts).

### 2.1 The registry entry

Source: `agentclientprotocol/registry`, path `antigravity-acp/agent.json`
(folder contains only `agent.json` + `icon.svg`).

| Field | Value |
| --- | --- |
| id | `antigravity-acp` |
| name / publisher | Google Antigravity / Google LLC, proprietary |
| version | 1.0.0 |
| build | `agy_acp_server_20260818_01_RC01` |
| binaries | darwin-aarch64, linux-x86_64, linux-aarch64, windows-x86_64, windows-aarch64 |
| linux cmd | `./agy_acp_server.par`, registry args `["--uid="]` |
| flags | `--[no]debug`, `--[no]notices` only. No model/effort/conversation flags |

The registry README states agents are CI-verified to return valid
`authMethods` in the handshake, and the index is re-fetched hourly.

### 2.2 Live initialize response

Sent:

```json
{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":true,"writeTextFile":true},"terminal":false}}}
```

Got (abridged to capability names):

```json
{"protocolVersion":1,
 "agentCapabilities":{
   "loadSession":true,
   "promptCapabilities":{"image":true,"audio":true,"embeddedContext":true},
   "mcpCapabilities":{"http":true,"sse":true},
   "sessionCapabilities":{"list":{},"resume":{}},
   "auth":{"logout":{}}},
 "authMethods":[
   {"id":"oauth-personal","name":"Log in with Google"},
   {"id":"oauth-business","name":"Log in with Gemini Enterprise"},
   {"id":"gemini-api-key","name":"Gemini API key"},
   {"id":"agent-platform","name":"Gemini Enterprise Agent Platform"}],
 "agentInfo":{"name":"antigravity-acp","title":"Google Antigravity",
   "version":"agy_acp_server_20260818_01_RC01"}}
```

### 2.3 Unauthenticated session/new

`session/new` returned `-32000 Authentication required` with the full recipe:
call `authenticate`, or set `auth.type` in
`~/.gemini/antigravity-acp/settings.json`. Accepted settings types:
`oauth-personal`, `gemini-api-key` (reads `GEMINI_API_KEY`), `oauth-business`
(needs `gcp.project` + `gcp.location`), `agent-platform` (ADC or
`GOOGLE_API_KEY`, project/location from `GOOGLE_CLOUD_PROJECT` /
`GOOGLE_CLOUD_LOCATION`). Confirmed by the official Zed setup page
(`antigravity.google/docs/ide/extensions/zed/`), which publishes exactly these
`settings.json` shapes.

### 2.4 Binary

1,529,513,909 bytes ELF x86-64, plus a 117 MB `localharness_external`
sibling. Cold start measured at a few seconds on this machine (handshake
answered well inside the probe timeout).

### 2.5 ACP v1 method surface

From `agentclientprotocol/agent-client-protocol` schema source (`v1/agent.rs`,
`v1/client.rs`):

- Client to agent: `initialize`, `authenticate`, `session/new`, `session/load`,
  `session/prompt`, `session/cancel`, `session/list`, `session/resume`,
  `session/fork`, `session/close`, `session/delete`, `session/set_mode`,
  `session/set_config_option`.
- Agent to client (requests): `session/request_permission`,
  `fs/read_text_file`, `fs/write_text_file`, `terminal/create`, `terminal/kill`,
  `terminal/output`, `terminal/release`, `terminal/wait_for_exit`.
- Agent to client (notifications): `session/update`.
- Extension namespace observed in schema: `nes/*` (IDE edit surfaces). Ignore
  for this plan.

### 2.6 Governance

`zed-industries/zed#57221` records the chain: Zed maintainers declined a
standalone SDK integration, waited for Google, and Google shipped the official
server. The same thread documents the Antigravity FAQ position that
third-party access to an Antigravity login violates ToS. The community
adapters carry that risk. Google's own server is the sanctioned client
channel. Our undocumented stream-json driver carries the same class of risk
today. Adoption retires it.

Also dated in that thread: Gemini CLI / Code Assist stop serving 2026-06-18.
`agy` is the only first-party CLI going forward, and its stream-json dialect
is an unmaintained contract. ACP is the maintained one.

## 3. Current architecture inventory and disposition

| 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/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) |
| `src/mcp-server.ts` | bridge HTTP MCP server; G9 park | KEEP unchanged. Registered via `mcpServers` under ACP |
| `src/skills.ts` | `activate_skill` bridge | KEEP unchanged |
| `src/native-tools.ts` | agy read-only steps to pi builtins | KEEP through phase 2. Phase 3 re-evaluates against `tool_call` content (gate C) |
| `WrapperReplay` (provider.ts) | display-only `antigravity` wrapper tool | Same: re-evaluate in phase 3 (gate C) |
| `src/diff-render.ts` | git-sourced diffs for agy edits | KEEP while agy self-executes edits (our fs capabilities off) |
| `src/ask-tool.ts` | AskAntigravity one-shot via `agy -p` | MIGRATE to ACP one-shot in phase 3 |
| `src/discovery.ts` | snapshot-diff + `/proc` fd-scan conversation binding | DELETE in phase 3 (ACP returns real session ids) |
| `src/patch-cleanup.ts` | pre-1.3.0 patch cleanup | KEEP unrelated |
| `extensions/index.ts` | registration, `/agy` command, notices | EXTEND: engine switch, acp auth command, doctor rebuild |

## 4. Capability matrix

Verdicts: IMPROVEMENT (strictly better), PARITY (equal), RISK (may regress,
mitigation required). Originally assessed pre-probe; verdict column SYNCED to
the Phase 0 results (§8.1, 2026-09-03). Pre-probe reasoning for any row lives
in git history.

| Dimension | Bridge today (stream-json) | Official ACP | Verdict |
| --- | --- | --- | --- |
| Wire contract | Undocumented NDJSON, shapes captured live, cumulative-resend heuristic, `OK`/`SUCCESS` mapping | Public versioned protocol, negotiated handshake | IMPROVEMENT |
| Text streaming | `text_delta` + dedupe guard | `agent_message_chunk` deltas, native | PARITY |
| Thinking | Token count only, floor 64, no text body | `agent_thought_chunk` carries text | IMPROVEMENT |
| Tool call visibility | start/done/error + native re-exec + wrapper replay | `tool_call` / `tool_call_update` with kind, status, content, locations, rawInput/output | IMPROVEMENT (VERIFIED: diffs arrive in content; Gate C PASS — machinery retirement confirmed for phase 3) |
| Permissions | `skipPermissions: true` default, `--dangerously-skip-permissions`, commands run unreviewed | `session/request_permission` flows to the client | PARITY under adoption (`auto` policy, 9.3). The primitive exists for whoever gates later; per-tool gating stays extension-owned via G9 |
| Images in prompt | Dropped in `extractUserPrompt` | `promptCapabilities.image: true` | IMPROVEMENT (VERIFIED end-to-end, run 6: "Red") |
| Audio | Dropped | `promptCapabilities.audio: true` | IMPROVEMENT (low priority) |
| Session resume | `sessions.json` + `--conversation` flag, per pi session only | `session/load`, `list`, `resume`, server-side | IMPROVEMENT (load VERIFIED across restart, run 6; full-text replay rules in 9.2) |
| 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 |
| 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 |
| Diagnostics | `/agy doctor`: snapshot, lifecycle, recycle stats | Nothing equivalent | PARITY work: rebuild on ACP events (section 10) |
| Auth | Piggybacks `agy` CLI login state | First-class: 4 methods, `authenticate`, `logout`, settings.json | IMPROVEMENT. One-time re-login cost |
| One-shot delegation (AskAntigravity) | `agy -p` + snapshot-diff + `/proc` fd-scan | `session/new` + `prompt`, real ids | IMPROVEMENT. Deletes discovery.ts |
| ToS exposure | Undocumented CLI driving | Sanctioned Google client channel | IMPROVEMENT |

## 5. Improvements in detail

1. **Permission flow.** Today any agy `run_command` executes unreviewed; the
   config comment says so in plain words. ACP makes approval a protocol
   primitive (`session/request_permission`, verified live). Under the single
   `auto` policy (9.3) adoption is parity; the primitive is in place for
   whoever wants to gate later.
2. **Thought text.** `agent_thought_chunk` delivers the model's actual
   thinking text. Today pi renders `[thinking]` labels and token counts only.
   Provider change is additive: extend the `thought` activity with an optional
   `delta` field (9.2).
3. **Images.** `promptCapabilities.image` lets us forward pi image blocks as
   ACP image content instead of dropping them in `extractUserPrompt`.
   Community reports say the `agy` CLI itself had broken image upload, so the
   live probe (A.4) verifies end-to-end delivery before we claim this.
4. **Graceful cancel.** `session/cancel` converts to a clean
   `stopReason: cancelled` prompt response. Today abort kills the process
   group and orphans the turn. Maps onto pi's `aborted` stop reason.
5. **Server-side sessions.** `session/load` restores a conversation after a
   pi restart without our store being the source of truth, and
   `session/list` / `session/resume` make `/agy conversations`-style tooling
   possible later. Sessions outlive the process; no recycle on drift.
6. **Protocol stability.** `initialize` negotiates `protocolVersion`. Unknown
   fields degrade instead of silently misparsing (compare: the 1.3.2 sqlite
   incident, issue #1).
7. **Sanctioned channel.** Section 2.6. Risk of account action and of silent
   dialect drift both drop.
8. **One-shot cleanup.** `discovery.ts` exists only because `agy -p` never
   prints its conversation id. ACP returns real session ids. The
   snapshot-diff + `/proc` fd-scan machinery and its ambiguity heuristics get
   deleted.
9. **Enterprise auth.** `oauth-business` / `agent-platform` bring VPC-SC and
   data-residency posture the CLI path never exposed to us.
10. **Deferred, deliberately.** `session/fork` (future multi-branch feature),
   `session/close` / `session/delete` (candidates for a later
   `/agy conversations` cleanup command), `terminal/*` and client-side `fs/*`
   delegation declined: agy keeps executing its own commands and file ops as
   today (parity), and answering them would put execution inside our process
   for no parity gain; our terminal and fs client capabilities stay false.
   `nes/*` IDE-edit extension (ignore), `audio` prompts (phase 2, optional).

## 6. Parity contract (no-regression checklist)

Every box must be `[x]` on the ACP engine before phase 4 flips the default.
Tested with the parity suite (section 11) and `scripts/parity-live.mjs`
(live, both engines: 14/14, 2026-09-03).

- [x] Text streams token-adjacent to streaming (no full-text re-sends) — live
      both engines, delta stream + cumulative-resend guard held
- [x] Multi-turn conversation continuity via `session/load` or our store —
      live: ACP `session/load` (history suppressed, clean reply), streaming
      `--conversation` resume; the provider's session store supplies the id
- [x] Turn serialization: two concurrent streamSimple calls never interleave
      — live both engines (queue releases only on settle) + driver tests
- [x] Bridge tool round-trip (G9) works: bridge MCP `tools/call` parks, pi
      executes, `toolResult` resumes the same agy turn — live both engines
      through the real bridge server; the pi-side park/resume is engine-
      independent (proven live on stream-json; the ACP parity run answers
      deps directly to isolate the agy-side HTTP client)
- [x] Idle timer suspends while a G9 park is open, resumes on `kickIdle` —
      fake-server tests (park/kickIdle remaining-budget deadline)
- [x] Overall turn timeout (10m) and inactivity timeout (5m) still fire and
      fail the turn visibly — driver tests (deadline fires with remaining
      budget after resume); inactivity shares the timer machinery
- [x] Abort: pi user abort produces `aborted`, the server process survives,
      the next turn on the session works — live both engines (aborted=true,
      recovery turn OK). "Process survives" holds on NEITHER engine and is
      the documented Gate D behavior: streaming kills the child; RC01 has no
      cancel, ACP tears down after the -32601 probe and reloads next turn
- [x] pi session restart resumes the right conversation (engine-tagged) —
      engine-scoped key tests + live `session/load`
- [x] Engine rollback preserves the other engine's conversation bindings
      (engine-scoped keys, 9.4) — sessions tests (per-entry engine field
      rejected precisely because set() would erase the streaming binding)
- [x] Model catalog: same `antigravity/*` model ids and effort tiers resolve
      — shared provider catalog, engine-independent by construction
- [x] Model/effort switch takes effect (gate A mechanism) — live: ACP
      `set_config_option` on a LOADED session; streaming recycle+resume
- [x] G1 digest and G10 system prompt reach the prompt identically — shared
      prompt assembly in the provider; the driver receives the final prompt
- [x] Skills `activate_skill` answered by the bridge as today — bridge
      server dep, same server serves both engines (ACP transport live)
- [x] Usage counters: present (mapped) or documented-absent (zero-usage),
      per gate B — live: streaming mapped, ACP absent (Gate B row in the
      parity matrix)
- [x] `/agy doctor` shows connection state, session id, prompt/session stats,
      lifecycle log — implemented engine-aware (phase 1); re-verify in pi
      before the phase 4 default flip
- [x] Error paths: spawn failure, auth failure, protocol error all surface as
      visible turn errors, never as silent empty messages — fake tests
      (auth-required, load-fails) + live: a bad-shape registration surfaced
      as a visible `ACP session failed: Invalid params` turn error in the
      first parity attempt, exactly as designed
- [x] `ask-tool` one-shot returns text, duration, abort/timeout states, and a
      resumable session id — unchanged `agy -p` path (phase-2 probe
      decides whether it moves to ACP)
- [x] Overall-turn timer pauses while any round-trip is parked; a slow human
      permission decision cannot kill the turn — fake tests (park/kickIdle
      remaining budget)
- [x] Cumulative-resend defensive guard on message chunks (port of
      `isCumulativeResend`), with a fake-server test. Note: provably inert
      on live RC01 (run-5 stress showed pure mid-token deltas); the fake
      server is the only surface that can exercise it — confirmed inert
      again in the live parity run

## 7. Regression risks and mitigations

| 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) |
| ~~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 |
| Human decision latency on parked G9 tool round-trips exceeds the 10m overall-turn cap | Turn killed mid-wait | `AcpDriver` pauses the overall timer while parked, re-armed with REMAINING budget; every park carries its own timeout (9.3) |
| Binary size (1.5 GB + 117 MB) | Disk + update churn | Pinned install layout (section 12), registry pin by build id |
| aarch64 TCMalloc startup failure (forum report, Chromebook) | arch-specific | x86_64 unaffected; gate install per-arch, link the forum issue in README |
| Separate auth state from `agy` CLI | First-run auth friction | `/agy acp-auth` prints exact instructions; `gemini-api-key` path works headless via `GEMINI_API_KEY`. The agent never writes credentials |
| Thought text changes rendering volume | Noisy transcript | Route through the existing thinking block pipeline, close-on-switch unchanged; no new block types |
| Two engines drift on behavior | Confusing support surface | Shared provider layer + shared parity suite run against both engines in CI |

## 8. Phase 0: probes and decision gates

One authenticated live session answers every UNKNOWN. No product code in this
phase. Deliverable: findings appended to this doc as section 8.1 (or
`docs/ACP-PROBE-NOTES.md`), and each gate marked PASS / FALLBACK.

Probe scripts (JSON-RPC over stdio, one object per line):

```jsonc
// P1 handshake with MINIMAL client capabilities (our phase-1 posture)
{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}}}

// P2 auth (pick one; api-key path is headless)
//   export GEMINI_API_KEY=... first
{"jsonrpc":"2.0","id":1,"method":"authenticate","params":{"method":"gemini-api-key"}}

// P3 session + bridge registration (exact mcpServers param shape is itself a probe item)
{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/abs/cwd","mcpServers":[{"name":"pi-bridge","type":"http","url":"http://127.0.0.1:<port><path>","headers":[]}]}}

// P4 model/effort switch attempts, in order until one works
{"jsonrpc":"2.0","id":3,"method":"session/set_config_option","params":{"sessionId":"<sid>","configOptionId":"model","value":"<slug>"}}
{"jsonrpc":"2.0","id":4,"method":"session/set_config_option","params":{"sessionId":"<sid>","configOptionId":"effort","value":"high"}}
{"jsonrpc":"2.0","id":5,"method":"session/set_mode","params":{"sessionId":"<sid>","modeId":"<id>"}}

// P5 prompt: stream a simple prompt; capture every session/update verbatim
{"jsonrpc":"2.0","id":6,"method":"session/prompt","params":{"sessionId":"<sid>","prompt":[{"type":"text","text":"Say hello and list the files in this directory."}]}}

// P6 mid-stream cancel: send during P5, observe prompt response stopReason
{"jsonrpc":"2.0","id":7,"method":"session/cancel","params":{"sessionId":"<sid>"}}

// P7 image prompt (small png data URL), verify the model actually sees it
{"jsonrpc":"2.0","id":8,"method":"session/prompt","params":{"sessionId":"<sid>","prompt":[{"type":"image","data":"<base64>","mimeType":"image/png"},{"type":"text","text":"What does this image show?"}]}}

// P8 session lifecycle: list, resume, load across server restart
{"jsonrpc":"2.0","id":9,"method":"session/list"}
{"jsonrpc":"2.0","id":10,"method":"session/resume","params":{"sessionId":"<sid>","cwd":"/abs/cwd"}}

// P9 tool exercise: prompt that forces an edit + a command run; capture
// tool_call / tool_call_update shapes and any session/request_permission
```

As executed, live param corrections were applied against these planned
scripts: `methodId` (not `method`), `configId` (not `configOptionId`), and
mcpServers http entries require `headers: []` (a LIST). See 8.1 and the
reference doc.

Capability posture, fixed for phases 1-3 and for every probe: `fs` false,
`terminal` false in the initialize client capabilities. Rationale (corrected
during the skeptical re-check of the peer review): parity, not philosophy.
agy keeps executing its own tools exactly as it does today; answering `fs/*`
or `terminal/*` would put file and process execution inside our process (new
machinery to build, secure, and hold at parity with agy's native behavior)
for no phase-1 gain. Diff-render and the permission surface stay meaningful.
This is a decision, not a default; revisit only as a phase 3+ enhancement
with its own design pass.

Concurrency note: the driver design is one active turn per connection (the
`#active` singleton). No probe exercises a second concurrent session while a
permission request is pending. Unverified by design, not by omission.

What to record for each gate:

| Gate | Question | PASS means | FALLBACK (still parity) |
| --- | --- | --- | --- |
| A | Model + effort switch per session? | `set_config_option` (or equivalent) switches both; next prompt uses them | NONE viable: the ACP binary takes no model flags, so respawn-per-switch cannot carry a model; a settings.json rewrite per switch is the only theoretical path and is rejected (unproven, racy). Gate A FAIL blocks the phase 4 default flip; ACP stays opt-in; the gap goes upstream |
| B | Usage anywhere? | Any update or `_meta` carries token counts | Zero-usage documented; README notes it |
| C | `tool_call` content richness | rawInput/output/locations enough to retire WrapperReplay + native-tools | Keep current replay machinery unchanged |
| D | Cancel latency + state | `stopReason: cancelled` within ~2s; session reusable after | Keep kill semantics on streaming; on ACP keep kill as escalation path |
| E | Startup cost | Cold start < 5s, steady RSS sane for a long-lived process | Spawn per turn-group only (like the streaming recycle cadence) |
| F | MCP `mcpServers` registration | Bridge `tools/list` visible to the agent mid-turn | Keep bridge wired some other protocol-sanctioned way; if none, G9 parking breaks and phase 1 is BLOCKED |
| F.7 | Slash behavior | Commands not auto-expanded against our prompt text | Prefix-safe prompt assembly unchanged |

Also verify in P5 whether permission requests arrive at all with `auto`
capabilities off, and whether `fs/write_text_file` requests appear for edits
(they should NOT, with our fs capabilities false; if they do, we answer them
with real local writes, same trust domain).

### 8.1 Phase 0 findings (COMPLETE, 2026-09-03)

Auth completed live: oauth-personal via the BROWSER-capture trick plus an
`ssh -L` loopback tunnel (the server never surfaces the URL headless; full
flow documented in [ACP-PROTOCOL-REFERENCE.md](./ACP-PROTOCOL-REFERENCE.md)).
Run 5 (authenticated, P1-P6) and run 6 (post-restart: load, tools, image,
Gate F) complete. Raw traffic: `probe-logs/acp-traffic-run5.jsonl` (600
JSONL lines) and `acp-traffic-run6-restart-load-tools.jsonl` (28 lines);
conversation store snapshot + schema: `probe-logs/acp-server-conversations/`.

| Gate | Verdict | Evidence |
| --- | --- | --- |
| A: model/effort switch | **PASS (live)** | `session/set_config_option` `{configId:"model", value:"gemini-3.8-flash-low"}` changed `currentValue`. Effort baked into full slugs; full catalog + default (`gemini-3.7-flash-high`) ships in `session/new` — the `agy models` CLI is not needed on the ACP engine |
| B: usage | **ABSENT on RC01** | zero token fields in every payload across both runs, including tool flows. Accept zero-usage (existing documented fallback); re-check per build |
| C: tool_call content | **PASS** | `tool_call`/`tool_call_update` carry kind, status lifecycle, `content` with `{type:"diff", path, newText}` (edits arrive AS DIFFS), `locations`, `rawInput`, optional `rawOutput`. Enough to retire wrapper-replay rendering in phase 3 |
| D: cancel | **FAIL on RC01** | `session/cancel` → `-32601 Method not found` (verified). Abort fallback **kill + `session/load` VERIFIED WORKING** (run 6): session restored with full history after process death |
| E: startup cost | **PASS** | initialize ~5-6 s cold (three runs); steady RSS ~327 MB (5 min mixed load) |
| F: bridge via mcpServers | **PASS (shape)** | `{name, type:"http", url, headers:[]}` accepted; dead URL tolerated at creation (lazy connect). Phase-1 TODO: real bridge `tools/list`+`tools/call` end-to-end (G9) |

Additional live-verified facts (details in the reference doc): token
persistence across restart PASS; `session/load` replays history as FULL-TEXT
chunks (driver must treat as replay, not live); config does NOT persist
across restart (driver re-applies model/effort/mode after every restart);
`session/request_permission` flow verified (options `allow`/`deny`,
kinds `allow_once`/`reject_once`; answer `{outcome:{outcome:"selected",
optionId}}`); image prompts PASS end-to-end; `set_mode` and per-session
`session/close` work; approved tool call may be superseded by another
toolCallId (track effects, not ids).

Schema corrections captured live (all in the reference doc): `authenticate`
takes `methodId` (not `method`); `set_config_option` takes `configId` (not
`configOptionId`); `settings.json` is read at server STARTUP only; -32602
error bodies carry `data.errors[].loc` field paths (use as correction
oracle). Streaming is pure-delta on live prompts (mid-token chunk splits; no
cumulative resends). Modes `default`/`auto_edit`/`yolo` map to our
`mode`/`skipPermissions`. The ACP conversation store is per-session SQLite
with opaque `steps.step_payload` blobs — same two-phase-write family as
legacy issue #1; never poll these DBs (re-validated decision).

Probe list CLOSED. Phase 0 go/no-go: GO for phase 1, with Gate D's kill+
reload abort path and the Gate F bridge end-to-end check as phase-1
acceptance items.

## 9. Target architecture

### 9.1 New modules

```
src/acp/jsonrpc.ts     newline-delimited JSON-RPC 2.0 framing: request/response
                       correlation map, concurrent requests, error responses,
                       notification + server-request dispatch, malformed-line
                       tolerance. Pure transport, no agy knowledge.
src/acp/connection.ts  process lifecycle: spawn AGY_ACP_BIN, initialize
                       handshake, authenticate detection (-32000), session/new
                       / 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)
                       so provider.ts keeps working unchanged. State machine,
                       timers, parks, snapshot, close.
src/acp/events.ts      session/update to DriverActivity mapping + stopReason
                       mapping. Pure functions, unit-tested against captured
                       probe transcripts.
scripts/smoke-acp.mjs  live smoke, gated by AGY_ACP_LIVE=1 (spends quota),
                       mirrors smoke-stream-json.mjs.
```

### 9.2 Driver contract (unchanged surface, additive only)

`AcpDriver` matches the existing `AgyDriver` public surface: `state`,
`activeHandle`, `run()`, `reentry()`, `kickIdle()`, `set onTurnEnd()`,
`snapshot()`, `close()`. `DriverActivity` gains one additive variant; the
streaming engine never emits it:

```ts
// stream-events/driver today:            { type: "thought"; tokens: number }
// ACP addition:
| { type: "thought"; tokens?: number; delta?: string }
```

`provider.ts` change: when `delta` is present call `appendThinking`, else keep
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
(`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
is explicitly deferred as speculative.

Teardown contract (review 3, finding 1 — the Gate D kill+reload path needs
an explicit answer for in-flight JSON-RPC state): when the connection dies
or is killed, `AcpConnection.abortAll()` rejects every outstanding
correlation-map entry (the pending `session/prompt` request, any unanswered
client-side requests), the driver settles the turn outcome as
`ERROR`/`aborted` (never left pending), and `onTurnEnd` fires so the
provider's `roundTrips.failAll()` fails parked round-trips exactly as the
streaming driver's `failTurn` path does. Nothing is ever written to a dead
socket; no promise survives the kill. Mirrors `ToolRoundTrips.failAll()`.

Event mapping (`src/acp/events.ts`):

| ACP | DriverActivity | pi mapping (provider.ts, existing) |
| --- | --- | --- |
| `agent_message_chunk` | `{type:"text", delta}` | text block deltas |
| `agent_thought_chunk` | `{type:"thought", delta}` | thinking block deltas |
| `tool_call` (first) | `{type:"tool_start", name, args}` | buffered; render on completion |
| `tool_call_update` completed | `{type:"tool_done", name, args, output}` | thinking label / native re-exec / wrapper (gate C) |
| `tool_call_update` failed | `{type:"tool_error", name, message}` | thinking label |
| `plan` | (phase 2+) thinking label `[agy plan]` | no pi plan block exists yet |
| `available_commands_update` | snapshot field only | `/agy doctor` |
| usage (if found, gate B) | `{type:"usage", usage}` | `toPiUsage` |
| prompt response `end_turn` | TurnOutcome OK | `stopReason: "stop"` |
| `cancelled` | TurnOutcome aborted | `stopReason: "aborted"` |
| `refusal` / `max_turn_requests` / `max_tokens` | TurnOutcome ERROR / OK+note | `error` / `stop` + `errorMessage` |
| `user_message_chunk` (during `session/load` only) | suppressed (history replay) | never emitted to pi as live text |

Defensive guard ported from the streaming engine: if an `agent_message_chunk`
repeats the full accumulated text instead of a delta, detect and slice (the
`isCumulativeResend` lesson; same agy binary lineage, same quirk class).
Guard plus test ship in phase 1. Honest labeling: the ACP spec defines chunks
as deltas, so on a compliant server the guard stays inert; it earns its ten
lines because this exact failure mode was observed in the wild on the same
backend's private protocol, and its steady-state cost is one prefix
comparison per chunk.

Load-replay rules (run 6, verified): `session/load` replays the full
conversation as `user_message_chunk`/`agent_message_chunk` PAIRS carrying
FULL TEXT, not the original deltas. `AcpDriver` marks replay chunks as
history and swallows them; none reach pi as live generation. Two more
restart rules: config does NOT persist across restart (model/effort/mode are
re-applied via `set_config_option` after every restart/load), and
`session/load` takes the same `mcpServers` param as `session/new` — the
bridge registration is passed on both.

### 9.3 Permission policy (simplified per decision 2026-09-03)

pi has no native permission-gate concept; extensions that want gating
implement it inside their own tools. G9 preserves that end-to-end: a pi tool
called by agy executes in pi's loop, where the tool's own gating runs. The
bridge-side `bridge` policy (routing `request_permission` through
`ask_user_question` with a third round-trip kind and a decision cache) was
REJECTED by decision: it built permission UX pi does not have, for agy-native
tools, at real complexity cost. The full design lives in review-3 history if
upstream ever ships allow-always kinds and the calculus changes.

One policy ships:

- `auto`: answer `session/request_permission` in-connection with the allow
  option. Byte-for-byte parity with today's `skipPermissions: true`. No
  round-trip, no provider involvement, no third kind; the once-only options
  quirk (run 6) is irrelevant under auto. Hard rule unchanged: the handler
  never hangs and never blocks the `session/prompt` response path.

Consequence: `provider.ts` is truly UNCHANGED by adoption (its only additive
line is the thought-delta `if`). Gate D teardown (9.2) still applies: on
connection death the unanswered permission request dies with the socket and
`abortAll()` settles everything.

Timer interaction (reviews 1-2, design retained; scope narrowed by the 9.3
decision to G9 tool parks): the overall-turn timer is armed once per turn and
only the idle timer pauses while a round-trip is parked. A human answer
through a parked pi tool (e.g. `ask_user_question`) can legitimately outrun
10 minutes. `AcpDriver` pauses the overall timer while any round-trip is
parked and, on settle, re-arms it with the REMAINING budget (`deadline -
now`), never a fresh cap: the overall timer is a turn DEADLINE, not an
inactivity guard. Every park carries its own timeout (`BRIDGE_TIMEOUT_MS`),
so a paused deadline cannot hang forever. Driver-local (AcpDriver only);
streaming behavior untouched; ships in phase 1.

### 9.4 Sessions schema (engine-scoped keys)

The first design (a per-entry `engine` field) was rejected in review 2:
`set()` overwrites the single `sid:<pi-session>` key, so one ACP turn ERASES
the streaming conversation binding, and a rollback loses continuity, breaking
the section 13 guarantee. Engines scope at the KEY level instead:

```jsonc
// ~/.pi/agent/antigravity-bridge/sessions.json
{
  "sid:<pi-session>":     { "conversationId": "<streaming id>", "lastStepIdx": -1, "lastMessageCount": 42 },
  "sid:<pi-session>@acp": { "conversationId": "<ACP sessionId>", "lastStepIdx": -1, "lastMessageCount": 42 }
}
```

- Un-suffixed keys belong to the streaming engine, byte-compatible with every
  persisted store; ACP keys carry an `@acp` suffix appended by
  `sessionKey()` when `config.engine === "acp"`.
- Engines never touch each other's keys: rollback keeps both continuations,
  `narrowStoreMap` needs no change (keys pass through untouched), and no
  migration runs.
- Under ACP the stored id is the ACP sessionId; `session/load` is attempted
  first on resume, our store only remembers which id to load.

### 9.5 Config schema

```jsonc
// ~/.pi/agent/antigravity-bridge/config.json (additive)
{
  "engine": "stream-json",            // "stream-json" | "acp"; default stream-json
  "acp": {
    "bin": "",                        // path to agy_acp_server.par; empty = resolve
    "permissions": "auto"             // auto-approve request_permission; single policy (9.3)
  }
}
```

- Env: `AGY_ENGINE`, `AGY_ACP_BIN`, `AGY_ACP_PERMISSIONS` (file < env, the
  documented precedence pattern).
- History note: an `engine` key existed before 1.3.2 (sqlite engine) and was
  removed; stale values in old config files are already dropped by narrowing.
  Values narrow to `"stream-json" | "acp"`, anything else falls back to the
  default. The sqlite engine is not coming back.
- Binary resolution order: `AGY_ACP_BIN` > `acp.bin` > `agy_acp_server.par`
  on PATH > install layout default (section 12). Resolution failure is a
  visible turn error naming what was tried.

## 10. Phase plan

### Phase 0: probes, gates, install, auth (no product code) — ✅ COMPLETE (2026-09-03)

- [x] Run probes P1-P9 (section 8). Gate verdicts recorded in 8.1; captured
      protocol in ACP-PROTOCOL-REFERENCE.md; raw traffic in `probe-logs/`.
- [x] Install layout + pin (section 12): binary at
      `~/.local/opt/agy-acp/<build>/` + `current` symlink + zip.sha256.
- [x] Auth onboarded: oauth-personal (token persisted, survives restart —
      verified run 6).
- [x] Deliverable: gates marked — A PASS, B ABSENT (managed), C PASS,
      D FAIL + fallback VERIFIED, E PASS, F PASS-shape. GO for phase 1.

### Phase 1: ACP transport engine, parity only — 🔨 BUILT (2026-09-03), acceptance open

Files: new `src/acp/*`, `src/config.ts` (engine + acp block), `src/sessions.ts`
(engine tag → shipped as engine-scoped KEYS, see 9.4), `extensions/index.ts`
(engine selection + doctor additions), `src/provider.ts` (driver injection
point; `createStreamSimple` already takes the driver as a dep; no other
provider change).

- [x] `jsonrpc.ts` + `connection.ts` + `events.ts` + `driver.ts` as specified
      (+ `TurnDriver` extraction to `src/driver-types.ts`).
- [x] `extractUserPrompt` unchanged (text only in phase 1; images in phase 2).
- [x] `mcpServers` registration of the bridge server at `session/new` AND
      `session/load` (run 6: load takes the same param; resumed sessions must
      keep bridge access). REGISTERED — live end-to-end still pending, see
      acceptance below.
- [x] Permission policy locked to `auto` (single policy; no bridge policy, see
      9.3).
- [x] `session/cancel` wired to pi abort and `session/close` sent on shutdown
      (pulled up from phase 2 by review 2, finding 6: abort must not kill the
      server process, and shutdown should not leak session state server-side).
      RC01 has no cancel: probe-once → -32601 → teardown+kill+reload, probed
      state shown in doctor.
- [x] Overall-turn timer pause while parked, REMAINING-budget semantics
      (9.3), covered by tests (park/kickIdle deadline test).
- [x] Fake-server suites: jsonrpc framing (incl. partial-line buffer), events
      mapping, driver flows (happy, load-replay suppression, permission auto,
      Gate D abort, auth error), engine config narrowing — suite green.
- [x] `/agy engine acp|stream-json` command + `/agy doctor` shows engine,
      server version, session counts, cancel support.
- [x] Live smoke through the full stack (`scripts/smoke-acp.mjs`, quota-
      gated): PASS.
- [x] Round-5 implementation review (agy): P0 framing buffer + 3 P1 + 3 P2
      all fixed.

Open acceptance (blocking "phase 1 done"):

- [x] Bridge `tools/list` + `tools/call` end-to-end on the ACP engine (Gate F
      live) — VERIFIED 2026-09-03, `scripts/smoke-acp-bridge.mjs`, 3/3 runs:
      real server accepted the registration, listed the bridge catalog, called
      `bridge_echo`, and finished its turn with the result (`ECHO:BRIDGE-E2E-777`).
      The check also found and fixed a real defect: the bridge 403s any request
      without the `x-bridge-token` shared secret, but the ACP registration sent
      `headers: []`. Fix: `McpServerHandle` now exposes `token` (and
      `TOKEN_HEADER` is exported); the extension builds the registration headers
      from the handle. Known cosmetic gap (phase 2): `tool_done.output` carries
      agy's tool title ("Bridge echo call"), not the result content — the model
      DID receive the result; only the activity display lacks it. The pi-side G9
      park/resume is engine-independent (proven live on stream-json); the smoke
      answers deps directly to isolate the agy-side HTTP client, the only part
      no fake server could stand in for.
- [x] §6 parity checklist executed LIVE on both engines — 2026-09-03,
      `scripts/parity-live.mjs`, 14/14 (7 scenarios × 2 engines). The run
      caught a REAL driver bug: a killed connection's late exit (RC01's
      signal handler intercepts SIGTERM and outlives its replacement)
      clobbered `#conn` and failed the recovery turn with the old stderr.
      Fixed: exit handling is connection-scoped (`stale-connection-exited`
      logged and ignored); regression test reproduces the race
      deterministically via `ACP_FAKE_SLOW_DEATH_MS`.
- [x] README / DEVELOPMENT / CHANGELOG updates — README (two engines,
      `/agy engine`, `/agy acp-auth`, `AGY_ENGINE`/`AGY_ACP_BIN`, ToS
      wording covers both official binaries), DEVELOPMENT (ACP suites +
      3 live scripts), CHANGELOG `[Unreleased]` (engine, token fix,
      stale-exit fix, RC01 limitations).

Acceptance gate: every section 6 box `[x]` on the ACP engine, or explicitly
marked with its gate fallback.

### Phase 2: protocol-native wins — ✅ COMPLETE (2026-09-03)

Probe evidence: `probe-logs/acp-phase2-traffic.jsonl` + shapes recorded in
ACP-PROTOCOL-REFERENCE.md "Phase-2 probe findings".

- ~~`permissions: "bridge"` policy~~: REMOVED by decision 2026-09-03 (pi has no
  native permission concept; per-tool gating belongs to the tools themselves
  and is preserved by G9; see 9.3).
- [x] Plan-mode equivalence probe: ACP modes are permission modes only
  (default/auto_edit/yolo) — NO review-only mode exists. The server's
  `/plan` command is intercepted server-side (F.7) and WRITES the plan
  artifact under auto policy. Verdict: plan delegations keep
  `agy -p --mode plan` (the committed exception); do not route mode:plan
  through ACP.
- [x] Image prompt blocks forwarded from pi content — driver `images`
  param, `connection.prompt` builds typed blocks ahead of the text,
  provider extracts image blocks from the user message, models advertise
  `input: ["text","image"]` on the ACP engine only (engine read at load;
  engine switches require a restart). Verified live: 64x64 two-tone PNG
  through the full driver stack (`scripts/smoke-acp-image.mjs`) and in the
  probe.
- [x] Thought text deltas through the thinking pipeline — already wired in
  phase 1 (provider renders `thought` deltas into the thinking block);
  probe finding: chunks are SPARSE on RC01 (a step-by-step prompt produced
  zero; reasoning ships as plain message text). No further work justified.
- [x] `session/cancel` parity — landed in phase 1 (Gate D fallback,
  abort-recover live on both engines).
- [x] Model/effort switching via the gate A mechanism — PASS (live,
  including on a loaded session; parity scenario).
- [x] Tool-frame display fixes (found by the probe, shipped with this
  phase): `tool_call_update` output prefers `content[]` text over the
  display-title `rawOutput`; MCP args unwrap the `arguments` envelope;
  tool name prefers `_meta.mcp.tool` over the "<server>_<tool>" title.
- [x] "Plan updates rendered as thinking labels" — OBSERVED-ABSENT on
  RC01: no `plan` sessionUpdate type exists; artifacts arrive as ordinary
  edit tool_calls (already rendered as cards). Item closed as not
  applicable, not deferred.
- Acceptance: no parity regression (14/14 re-run after the mapping
  changes); cancel probe done (phase 1); image probe end-to-end (probe +
  live smoke).

### Phase 3: consolidation (immediate priority, opt-in only)

Hard rule: Keep both engines in the extension. Default engine remains `stream-json`. All items below are non-breaking opt-in enhancements for the ACP engine that do NOT alter default behavior or touch streaming paths.

Queue:
1. [x] Gate C evaluation: `native-tools.ts` + `WrapperReplay` retired on the ACP engine (retained for the streaming (`stream-json`) engine). ACP turns emit thinking labels for tool executions without parking turns for synthetic re-execution or wrapper cards; bridge MCP tools (`bridge_call`) continue parking natively. Verified: live parity 14/14 held.
2. [x] Retire `diff-render.ts` (git path) on the ACP engine — DONE 2026-09-04. The phase-2 probe proved ACP surfaces edit diffs natively (`tool_call` `content[]` `{type:"diff", path, oldText?, newText}`), which is richer AND cheaper than the git-sourced path: implemented as (a) `events.ts` extracts the first diff entry into the `tool_done` activity (`AcpEditDiff`); (b) `provider.ts` renders it on ACP turns via the new `formatInlineDiff` (in-memory `generateDiffString`, same line-numbered format, ZERO git subprocesses) instead of `TurnDiffContext.diffEdit`; (c) `diff-render.ts` git machinery remains solely for the `stream-json` engine. Tests: diff extraction (with/without `oldText`), ACP thinking-stream rendering (`+2 B` line-numbered), label-only fallback, no parking, streaming path unchanged. Verified: 165/165 vitest, tsc clean, live parity 14/14.
3. [x] `/agy doctor` diagnostics expansion — DONE 2026-09-04. The ACP
      snapshot now carries `reconnects` (connections beyond the first =
      Gate D kills + stale-exit replacements) and the handshake `agentInfo`
      name/title; `/agy doctor` surfaces both (reconnects in the stats line,
      agent title next to the server version). Regression test pins
      `reconnects = 1` on the stale-exit flow.
4. [x] G1 digest via `embeddedContext` resource blocks — DONE 2026-09-04
      (the optional enhancement, adopted as the ACP delivery path). On the
      ACP engine the digest ships as a native `{type:"resource"}` block in
      the prompt array (`connection.prompt` builds images → resource →
      text) instead of inline prompt text; `stream-json` keeps the inline
      default. Verified live: a resource block with a secret word was read
      and answered correctly by RC01 (`promptCapabilities.embeddedContext`
      is functional, not just advertised).

Acceptance: parity suite remains 14/14, doctor parity, no breakage to stream-json default.

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).

### Phase 4: default flip and streaming deletion (deferred, next month)

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).

Acceptance: default-flip release ships with the parity suite as acceptance evidence; deletion release has zero references to the removed modules.

## 11. Test strategy

- **Framing** (`jsonrpc.ts`): correlation, concurrency, error responses,
  notifications vs requests, malformed lines, backpressure. Pure unit tests.
- **Mapping** (`events.ts`): every session/update variant from captured probe
  transcripts to DriverActivity; stopReason table; unknown-variant tolerance
  (the `parseAgyLine` lesson, re-applied).
- **Driver** (`driver.ts`): scripted fake ACP server (a tiny stdio JSON-RPC
  node script under `tests/helpers/`) covering: handshake, session/new fail
  auth, streaming prompt, park suspends idle timer, kickIdle rearm, cancel
  mid-stream, connection death mid-turn, recycle fallback path.
- **Provider**: the existing `provider-streaming` / `provider-digest` /
  `provider-sysprompt` suites run against both engines via the shared driver
  contract. New case: thought delta path.
- **Sessions**: engine-tag matching, streaming-file compatibility (no tag),
  cross-engine miss starts fresh.
- **Config**: narrowing of stale/garbage `engine` values, env precedence.
- **Parity suite**: the section 6 checklist encoded as an integration run
  against the fake server for both engines; live parity runs stay
  `AGY_ACP_LIVE=1` gated (quota).

## 12. Binary management, pinning, auth onboarding

Install layout:

```
~/.local/opt/agy-acp/<build>/
  agy_acp_server.par
  localharness_external
~/.local/opt/agy-acp/current -> <build>     # symlink; AGY_ACP_BIN default
```

- Pin by build-stamped registry URL (`...20260818_01_RC01-...zip`), not by
  the moving registry index. The registry updates hourly; a float could
  change the engine under a running install mid-release.
- The registry publishes no checksums. Record the zip SHA-256 at install time
  in the install dir for drift detection. Propose an upstream checksum
  request (issue) once we depend on this.
- `--uid=` from the linux registry entry: the server ran without it here.
  Treat as a launcher artifact; revisit if a future build refuses to start.
- Auth onboarding: `/agy acp-auth` prints the four methods with exact
  `settings.json` shapes (source: official Zed docs, section 2.3). Headless
  path: `GEMINI_API_KEY` + `auth.type: "gemini-api-key"`. The agent NEVER
  writes or reads credentials; it prints instructions and verifies by
  re-running `session/new` until the error clears.

## 13. Rollback

At any phase: `AGY_ENGINE=stream-json` (or `/agy engine stream-json`) returns
to the streaming engine. Sessions are keyed per engine (9.4), so the streaming
engine resumes its own conversations untouched. The streaming engine is only deleted in
phase 4, one release after the flip, so rollback stays possible throughout.

## 14. Documentation updates

| Doc | Change | Phase |
| --- | --- | --- |
| `README.md` | engine section, binary install, auth, arch note | 1, 4 |
| `docs/ARCHITECTURE.md` | ACP engine section alongside stream-json | 1 |
| `docs/DEVELOPMENT.md` | smoke-acp, fake server, probe workflow | 1 |
| `docs/ACP-ADOPTION-PLAN.md` | this file; gate results appended | 0 |
| `docs/PI-BRIDGE-GAPS.md` | G1 note: per-tool gating stays extension-owned; G9 preserves it under ACP | 1 |
| `CHANGELOG.md` | per phase, house style | each |

## 15. Risk register

| # | Risk | L | I | Response |
| --- | --- | --- | --- | --- |
| R1 | Gate A fails (no model switch) | M | H | default flip blocked; ACP stays opt-in; escalate upstream. No ship-anyway: model switching is not optional |
| R2 | Gate F fails (bridge not registrable) | L | H | BLOCKS phase 1; escalate upstream, keep streaming |
| R3 | Usage absent (CONFIRMED, Gate B) | H | M | zero-usage documented on ACP; stream-json retained as secondary engine; phase-4 deletion conditioned on Gate B lift (review 4) |
| R4 | Binary churn (hourly registry, RC builds) | M | M | pin by build id, record sha256 |
| R5 | Server rejects second simultaneous session | L | M | one session per connection (today's model), N connections instead |
| R6 | Thought text floods transcript | M | L | thinking pipeline unchanged, same close-on-switch |
| R7 | ToS posture shifts again | L | H | official channel is Google's own; monitor registry + FAQ |
| R8 | aarch64 breakage | L | L | per-arch gating |
| R9 | ~~`bridge` permission throughput~~ removed with the bridge policy (9.3) | - | - | n/a |

## 16. Open questions

CLOSED 2026-09-03 — every item was answered by the Phase 0 probes (section
8.1, [ACP-PROTOCOL-REFERENCE.md](./ACP-PROTOCOL-REFERENCE.md)). Notable
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.