@estebanforge/pi-antigravity-bridge 1.6.4 → 1.7.0

package/CHANGELOG.md

@@ -2,11 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.7.0] - 2026-09-23
+
+### Added
+
+- **Opt-in web tools for any provider's model** (`agy_web_search`, `agy_read_url`). Pi ships no web tools and no MCP by default, so sessions driven by non-Antigravity models had no way to search or fetch. With `webTools: on` (`AGY_WEB_TOOLS`, `/agy web on`; off by default because Antigravity sessions already have native web tools on both engines), each call spawns a one-shot search-only `agy` agent (`--mode plan`, bridge MCP inheritance off, per-call agent dir under `~/.gemini/config/agents/pi-bridge-web-*` removed in `finally`), enforces a 120 s deadline and a 2 MiB output cap, tolerates agy's `OK`/`SUCCESS` result-status drift, requires an observed native `search_web`/`read_url_content` step before trusting the answer, and refuses the call if the agent touches any disallowed tool - the init frame advertises a broad tool list regardless of the agent's `tools:` restriction, so the response-side gate is the real anti-hallucination device. Stale agent dirs from crashed calls are swept by pid liveness at registration (marker-less dirs after a 24 h grace); dir names carry a random nonce so same-millisecond parallel calls cannot collide. URLs are scheme-allowlisted (http/https); queries cap at 2000 chars. Every call spends Antigravity subscription quota.
+- **ACP native tool display cards.** The ACP engine had no card story: agy's own tool steps surfaced only as thinking-stream labels. agy's tool events now render as display-only pi entries (status icon plus the file path with colored diff lines, the first command line, or the captured output; persisted content bounded at 4000/12000/500 chars), streamed as steps start and complete. Events attributed to `mcpServer: "pi-bridge"` are filtered out, so bridge round-trips that already produce genuine pi tool cards never double-render. Stream-json keeps its stronger native re-exec cards.
+- **Live ACP usage estimates.** The ACP engine showed zeros until a turn settled (Gate B). Estimates now stream live: the turn's prompt is tokenized once, each text/thought delta updates the running counts, and an `ACP ≈ X in / Y out` status line tracks the turn (suppressed when `acp.usageEstimate` is `off`). Estimates are superseded only by a real `PromptResponse.usage` the day the server sends one; diagnostic usage-shaped frames (context windows, occupancy) never disable them.
+- **`/agy tools` session-only catalog control.** `hide <name>` / `show <name>` / `reset` filter the bridge catalog for the current session only (multi-word names OK; names validated against pi's registered tools; saved config never touched). Bare `/agy tools` lists exposed and hidden tools.
+
+### Changed
+
+- **The bridge catalog is computed live and guarded at dispatch.** The exposed set used to be computed once at registration; `/mcp` or `pi.setActiveTools()` changes mid-session left stale tools callable. The catalog is now derived from pi's live active set on every `tools/list` AND re-checked immediately before every `tools/call` - a call for anything outside the fresh set is rejected (`a cached MCP catalog is not authorization`). The bridge's own internal tools (AskAntigravity, the display-only `antigravity` wrapper, `activate_skill`, `bridge_poll_result`, `agy_web_search`/`agy_read_url`) are excluded from the catalog, closing a gap where the wrapper tool was exposed. `/agy bridge` mode changes apply to a running server immediately; a stopped one picks them up on the next start.
+- **Global MCP registration is stream-json-only; hygiene is universal.** Registering and unregistering the bridge's per-pid entry in `~/.gemini/config/mcp_config.json` now happens only for the stream-json engine (ACP supplies the bridge per-session and never touches the global config), while the stale-entry sweep and the stuck-suppression heal run for BOTH engines - an ACP-only session no longer leaves dead entries or a stuck suppression flag behind by a crashed stream-json session.
+
+### Fixed
+
+- **Concurrent native tool results no longer cross-pair on ACP.** When several of agy's tools ran at once, a completed event for one could attach its diff/output to a different pending call. Adoption now happens only when exactly one call is pending, finished and errored ids leave the tracking map, and a known-acceptable residual is documented at the site: a done event for a genuinely unrelated call can still pair with the single pending entry.
+- **Diagnostic usage frames can no longer kill ACP estimates.** The old suppression latch tripped on ANY usage-shaped frame and lived for the whole connection, so one context-window notice in turn one silenced the live estimates for every later turn, with no exact data ever replacing them. Suppression now keys on a real per-turn `PromptResponse.usage` only; a two-turn regression test pins that estimates survive the diagnostic frames.
+
 ## [1.6.3] - 2026-09-22
 
 ### Fixed
 
-- **The approval gate no longer leaks into standalone sessions, and its verdicts parse.** Thanks @explesy for the report (https://github.com/EstebanForge/pi-antigravity-bridge/issues/5). Two defects in the generated hook script and its staging. Every terminal path printed the bare decision scalar (`"deny"` / `"allow"`) instead of a JSON object, so any session that loaded a staged gate failed hook parsing outright (`protojson: syntax error`): the direct-POST and polling branches now print the full response object guarded by a `typeof json.decision === "string"` check, fall back to a fail-closed deny object on malformed bodies, and read ticket and poll status through `json?.`. The gate group itself was staged into the shared workspace `.agents/hooks.json`, so any standalone IDE or CLI session in that workspace loaded pi's gate: tool calls were denied with "no active antigravity turn" while pi sat idle, and mid-turn they parked into pi's approval queue. A live probe of the CLI settled the discovery rule (hooks load from `--add-dir` directories in stream-json and interactive sessions; print mode reads only the global config), and the gate now stages `.agents/hooks.json` into the session-private per-pid bridge dir beside `mcp_config.json`, which only this session's agy receives as an extra `--add-dir`. Staging into a pid-private file dropped the merge/backup/symlink surface to a plain atomic replace; the driver passes the dir when the gate is staged even without an MCP config; a legacy sweep at session start strips groups that dead sessions left in workspace files (live and foreign groups are never touched). The hook also gained per-fetch aborts (`AbortSignal.timeout`, POST capped at 10s, polls bounded by the remaining park budget) so a hung bridge request can never outlive the park deadline into an ungated soft-pass. Seven stub-server hook-execution regression tests pin the object contract; the staging suite covers the private-dir semantics and the sweep. 364 tests, tsc clean.
+- **The approval gate no longer leaks into standalone sessions, and its verdicts parse.** Thanks @explesy for the report (issue #5). Two defects in the generated hook script and its staging. Every terminal path printed the bare decision scalar (`"deny"` / `"allow"`) instead of a JSON object, so any session that loaded a staged gate failed hook parsing outright (`protojson: syntax error`): the direct-POST and polling branches now print the full response object guarded by a `typeof json.decision === "string"` check, fall back to a fail-closed deny object on malformed bodies, and read ticket and poll status through `json?.`. The gate group itself was staged into the shared workspace `.agents/hooks.json`, so any standalone IDE or CLI session in that workspace loaded pi's gate: tool calls were denied with "no active antigravity turn" while pi sat idle, and mid-turn they parked into pi's approval queue. A live probe of the CLI settled the discovery rule (hooks load from `--add-dir` directories in stream-json and interactive sessions; print mode reads only the global config), and the gate now stages `.agents/hooks.json` into the session-private per-pid bridge dir beside `mcp_config.json`, which only this session's agy receives as an extra `--add-dir`. Staging into a pid-private file dropped the merge/backup/symlink surface to a plain atomic replace; the driver passes the dir when the gate is staged even without an MCP config; a legacy sweep at session start strips groups that dead sessions left in workspace files (live and foreign groups are never touched). The hook also gained per-fetch aborts (`AbortSignal.timeout`, POST capped at 10s, polls bounded by the remaining park budget) so a hung bridge request can never outlive the park deadline into an ungated soft-pass. Seven stub-server hook-execution regression tests pin the object contract; the staging suite covers the private-dir semantics and the sweep. 364 tests, tsc clean.
 
 ## [1.6.2] - 2026-09-19
 

package/README.md

@@ -1,16 +1,6 @@
 # pi-antigravity-bridge
 
-A Gemini model provider **and** the `AskAntigravity` delegation tool for [pi](https://github.com/earendil-works/pi-coding-agent), built on Google's official Antigravity binaries: the `agy` CLI by default, or **Google's official ACP server** (opt-in). It registers `antigravity/gemini-*` models in pi's `/model` picker (streaming), and provides the `AskAntigravity` tool for one-shot delegation - the same combined shape as `pi-claude-bridge`.
-
-<p>
-  <img width="1374" height="869" alt="image" src="https://github.com/user-attachments/assets/fdd6c1f0-5144-40ef-9371-77a94de50b76" align="center" />
-</p>
-<p>
-  <img width="1376" height="451" alt="SCR-20260908-mbox" src="https://github.com/user-attachments/assets/d105c8a7-1ace-42f7-8285-642150453761" align="center" />
-</p>
-<p>
-  <img width="1375" height="1342" alt="SCR-20260908-mbvc" src="https://github.com/user-attachments/assets/bb614c55-e0f8-4677-bb0e-6541071e91ef" align="center" />
-</p>
+A Gemini model provider **and** the `AskAntigravity` delegation tool for [pi](https://github.com/earendil-works/pi), built on Google's official Antigravity binaries: the `agy` CLI by default, or **Google's official ACP server** (opt-in). It registers `antigravity/gemini-*` models in pi's `/model` picker (streaming), and provides the `AskAntigravity` tool for one-shot delegation - the same combined shape as `pi-claude-bridge`.
 
 
 If you also have [`@estebanforge/pi-ask-antigravity`](https://github.com/EstebanForge/pi-extensions/tree/main/packages/pi-ask-antigravity) installed, this bridge takes over: pi-ask-antigravity detects the bridge and registers nothing, so the `AskAntigravity` tool is never duplicated.
@@ -26,7 +16,7 @@ Multi-turn works. The provider binds a pi session to an agy conversation id (per
 Turns run through one of two engines behind the same provider surface (`config.engine`, default `stream-json`):
 
 - **stream-json** (default): the persistent `agy` CLI process. The tested default; live token usage; conversation resume via `--conversation`.
-- **acp** (beta): Google's official ACP server (`agy_acp_server.par`), JSON-RPC 2.0 over stdio. Beta: parity-verified live against the current build (RC01) - text streaming, multi-turn resume via `session/load`, bridge tools, effort switching, serialization, abort recovery (see `scripts/parity-live.mjs`). Two known RC01 gaps remain: no usage fields (token display shows client-side ESTIMATES until Google ships usage; `acp.usageEstimate` off to keep zeros) and no cancel (abort tears the server down and reloads it next turn).
+- **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 runs on live client-side estimates via `acp.usageEstimate`, default `estimate`, streamed per delta and superseded automatically the day the server starts sending real per-turn usage) and no cancel (abort tears the server down and reloads it next turn).
 
 The choice of engine is left to the user, with the trade-offs explained in the tool: a first-run picker modal asks once on a fresh install (stream-json preselected; `esc` defers, and the modal reappears next start), and `/agy engine` with no arguments reopens it anytime. An `acp` pick downloads the ~1.5 GB server binary and starts the Google sign-in immediately; a restart applies the engine. With stream-json active and the `agy` binary missing, pi warns on every start until the binary is found.
 
@@ -48,7 +38,7 @@ Residual limits (with or without the bridge):
 
 While agy is the active model it normally cannot see pi's universe of extensions: agentmemory, codegraph, web search, slack/asana, the `Ask*` delegations, and any other installed pi tool. This extension optionally bridges that gap.
 
-The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and a `tools/call` routes into pi's own tool loop via the round-trip described below. Discovery has two layers. The provider's agy gets a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the driver passes that dir as an extra `--add-dir` when it spawns agy. A per-pid entry (`pi-bridge-<pid>`) is also registered in the user's global agy config (`~/.gemini/config/mcp_config.json`; foreign servers preserved, stale entries swept at start), so agy builds that read only the global config still find the bridge.
+The bridge starts a localhost MCP server inside pi's process. The exposed catalog is computed live from pi's active tools on every `tools/list` and re-checked immediately before every `tools/call`: the `bridgeTools` mode, the session's `/agy tools` hidden set, and the bridge's own internal tools (`AskAntigravity`, the display-only `antigravity` wrapper, `activate_skill`, `bridge_poll_result`, the `agy_web_search`/`agy_read_url` wrappers) are filtered each time, and a call for anything outside the fresh set is rejected - a cached MCP catalog is not authorization. A call that passes routes into pi's own tool loop via the round-trip described below. Discovery has two layers. The provider's agy gets a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the driver passes that dir as an extra `--add-dir` when it spawns agy. A per-pid entry (`pi-bridge-<pid>`) is also registered in the user's global agy config (`~/.gemini/config/mcp_config.json`; foreign servers preserved, stale entries swept at start), so agy builds that read only the global config still find the bridge.
 
 **No patch required.** Bridge calls park in the provider's round-trip store; the provider ends the pi assistant message with a `toolUse` stop reason for the real pi tool, pi executes it in its own loop (native cards, permissions, hooks), and the toolResult completes the parked MCP response on the next stream call. This is the same mechanism tianzuo/pi-antigravity uses; upstream pi APIs only.
 
@@ -56,7 +46,7 @@ The bridge starts a localhost MCP server inside pi's process. `tools/list` retur
 
 **Recursion safety.** Only the provider's agy receives the extra `--add-dir`. `AskAntigravity` is also filtered from the exposed tool list. Its delegated `agy -p` spawns with just the workspace, and for the whole delegated run the bridge hides its global per-pid entries: disabled before the spawn, released only on process close or error - agy watches the config and hot-reloads MCP servers on file changes, so a mid-run re-enable would poke the live delegation back into pi. A cross-process marker (`suppression.json` in the bridge's extensions-data dir) coordinates concurrent delegations: entries come back only when no live delegation remains, a session starting mid-delegation registers its own entry disabled, and the session-start heal re-enables only once the last delegator is gone (dead entries pruned by pid liveness with a 24h age bound). The inner agy therefore sees no bridge and cannot re-enter pi. Foreign servers in the global config are never touched.
 
-**Cost / fan-out.** Every registered pi tool except builtins (and `AskAntigravity`) is exposed, including other delegation tools like `AskClaude`/`AskCodex`. agy can therefore chain into other models via the bridge, which is a new cost/time fan-out vector that did not exist before this feature.
+**Cost / fan-out.** Every registered pi tool except builtins and the bridge's own internal tools is exposed (respecting the `bridgeTools` mode and any `/agy tools` hides), including other delegation tools like `AskClaude`/`AskCodex`. agy can therefore chain into other models via the bridge, which is a new cost/time fan-out vector that did not exist before this feature.
 
 **Security.** The MCP server binds to `127.0.0.1` only and requires a per-session shared-secret header (`x-bridge-token`) that agy sends from the bridge config; browsers cannot set custom headers on a simple cross-origin POST, so this blocks web CSRF against the loopback server. Request bodies are size-capped. This is intended for single-user developer machines: any local process running as the same user can read the token from the per-pid config and call the exposed tools, so do not run it on a shared host where you do not trust other same-user processes.
 
@@ -75,6 +65,12 @@ 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.
 
+On the ACP engine there is no re-exec: agy's own native tool steps render as
+display-only cards in pi instead - a status icon plus the file path with
+colored diff lines, the command line, or the captured output - streamed as the
+steps start and complete. The stream-json engine keeps its native re-exec
+cards for read-only steps.
+
 ## Approval gate (agy native tools)
 
 agy runs its own agent loop with native tools (`run_command`, `create_file`, `edit_file`, ...), which pi's permission extensions never saw. The optional approval gate routes those calls through a pi-side approval: a staged PreToolUse hook parks the call, the provider surfaces it as a shadow `bash`/`write`/`edit` toolUse, and your permission extension (or the built-in ask/allow/deny fallback) decides before agy executes it. Off by default (`approvals.gateMode: auto` enables it only when a pi permission extension is detected); denials fail closed; read-only agy tools stay ungated.
@@ -120,13 +116,14 @@ If `agy models` fails at load (binary missing, auth not done, network stall), a
 | Key | Values | Default |
 | --- | --- | --- |
 | `askTool` | `on` (register the AskAntigravity delegation tool), `off` (no delegation tool; provider and models only) | `on` |
+| `webTools` | `off` (no web tools), `on` (register `agy_web_search` + `agy_read_url` as Pi tools, usable by ANY provider's model). Each call spawns a one-shot search-only `agy` agent (plan mode, bridge MCP inheritance off), gates the answer on an observed native `search_web`/`read_url_content` step, and spends Antigravity quota. Off by default: Antigravity sessions already have native web tools on both engines; these serve other providers | `off` |
 | `bridgeTools` | `none` (bridge off), `all` (every non-builtin tool, incl. other `Ask*` delegations), `mcp` (pi-mcp-adapter tools + skills bridge only) | `all` |
 | `digest` | `off` (stable prompts; agy's prompt cache hits) or `on` (inject a delta of pi-side context - compaction summaries, other-provider turns - into each agy prompt; the delta changes every turn, so agy re-bills the full context). Enable for mixed-provider sessions where agy must see pi-side context | `off` |
 | `systemPrompt` | `on` (prepend pi's system prompt - operating instructions plus the global agent-dir `AGENTS.md` and ancestor `AGENTS.md`/`CLAUDE.md` - to the first prompt of each new agy conversation, plus a tool-priority note: Pi Bridge tools win over agy's native interactive ones, which never reach the user) or `off` (agy-native behavior) | `on` |
 | `turnTimeoutMin` | Overall cap on ONE agy turn, minutes, both engines. When it fires, the bridge kills the agy process mid-task ("ACP turn exceeded the 10m deadline" / "agy exceeded the 10m turn timeout") - it is a bridge cap, not a Google server limit. Default is TTY-aware: `0` (no cap) on an interactive pi - you are the backstop with Esc; `20` headless, where nobody can abort and one runaway turn blocks the serialized turn queue. Opt into a gate with 1-1440 (free type via `config.json` or `/agy timeout <1-1440|off>`, or the `/agy` picker's preset list); `0` disables explicitly; anything else falls back to the TTY-aware default. The 5m inactivity stall guard always still bounds a hung server | `0` TTY / `20` headless |
 | `inactivityTimeoutMin` | Silence cap, minutes, both engines: no stream-json stdout / no ACP session/update for this long fails the turn as a stall. `0` disables the guard | `5` |
 
-Env overrides: `AGY_BRIDGE_TOOLS`, `AGY_ASK_TOOL`, `AGY_DIGEST`, `AGY_SYSTEM_PROMPT`, `AGY_TURN_TIMEOUT_MIN`, `AGY_INACTIVITY_TIMEOUT_MIN`. Env wins over the file, so while `AGY_DIGEST` or `AGY_SYSTEM_PROMPT` is set, the matching `/agy digest` or `/agy system-prompt` toggle persists a value that never takes effect.
+Env overrides: `AGY_BRIDGE_TOOLS`, `AGY_ASK_TOOL`, `AGY_WEB_TOOLS`, `AGY_DIGEST`, `AGY_SYSTEM_PROMPT`, `AGY_TURN_TIMEOUT_MIN`, `AGY_INACTIVITY_TIMEOUT_MIN`. Env wins over the file, so while `AGY_DIGEST` or `AGY_SYSTEM_PROMPT` is set, the matching `/agy digest` or `/agy system-prompt` toggle persists a value that never takes effect.
 
 The `activate_skill` catalog mirrors pi's directory-based skill discovery: the two global dirs plus project dirs, the latter only when pi has trusted the project (same gate pi itself applies). Pi's other skill sources - the `skills` settings array, `package.json` entries, and `--skill` CLI paths - are not mirrored and won't appear in the catalog.
 
@@ -147,7 +144,9 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy thinking low|medium|high fallback thinking tier for the AskAntigravity tool; callers may override per call
 /agy digest on|off        inject pi-side context into agy prompts (default off; see table above)
 /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 bridge all|mcp|none  which pi tools the MCP bridge exposes to agy (default all; none = bridge off; a running server picks up the new catalog immediately, a stopped one on the next start)
+/agy tools [hide|show <name>|reset]   session-only bridge-catalog hides (multi-word names OK; reset restores the full set; bare lists exposed + hidden; never touches saved config)
+/agy web on|off            register the agy_web_search + agy_read_url pi tools for ANY provider's model (default off; applies on the next pi start or /reload; every call spawns agy and spends Antigravity quota)
 /agy acp-bin <path|auto>  point the ACP engine at a specific server binary (auto = setup installs, or AGY_ACP_BIN; applies on the next ACP turn)
 /agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp is beta and runs self-service setup: binary install + auth bootstrap). No arguments opens the engine picker modal (TUI)
 /agy auth-manual             manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
@@ -180,9 +179,12 @@ For isolation when running any agent that executes commands without a confirmati
 | `AGY_CONVERSATIONS_DIR` | Override the conversations DB directory. |
 | `AGY_MODE` | Override execution mode: `plan` (review-only) or `accept-edits` (default). Wins over the config file. |
 | `AGY_SKIP_PERMISSIONS` | `1`/`true` (default) to pass `--dangerously-skip-permissions` so commands don't hang on an unanswerable prompt in `-p` mode. `0`/`false` to prompt (hangs any `run_command` non-interactively). Wins over the config file. |
+| `AGY_USAGE_ESTIMATE` | ACP token display: `estimate` (default; live client-side per-delta estimates), `direct` (pass through the server's own per-delta counts when it sends them), `off` (no usage display). Anything else falls back to `estimate`. Wins over the config file. |
 | `AGY_DEFAULT_MODEL` | Default model alias for the `AskAntigravity` tool (`flash`/`pro`/`gemini`, or a tier/version qualifier). Wins over the config file. |
 | `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 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. |
+| `AGY_APPROVALS` | Approval gate mode: `auto` (default; gate on only when a pi permission extension is detected), `shadow` (force the shadow-tool gate on), `dedicated`, `off`. Unknown values fall back to `auto`, so a typo can never force the gate on. Wins over `config.approvals.gateMode`. |
+| `AGY_APPROVALS_MODE` | Fallback decision when no permission extension answers a gated call: `ask` (interactive prompt), `allow`, `deny` (headless default). Wins over `config.approvals.mode`. |
 
 ## Debug logs
 

package/extensions/index.ts

@@ -50,6 +50,7 @@ import {
 	createStreamSimple,
 	formatEscalatedAck,
 	formatPollAnswer,
+	type NativeDisplayEvent,
 } from "../src/provider.js";
 import {
 	createShadowTool,
@@ -69,6 +70,7 @@ import { CONFIG_PATH, loadConfig, logsDir, MAX_TURN_CAP_MIN, parseCapMinutes, sa
 import { agyMissingMessage, isAgyInstalled, savedEngineMessage, showEnginePicker, shouldOfferEnginePicker } from "../src/engine-picker.js";
 import { createDailyLogger, type DailyLogger } from "../src/daily-log.js";
 import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.js";
+import { registerWebTools } from "../src/web-tools.js";
 import { bridgeMcpConfigDir, startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
 import {
 	registerBridgeServer,
@@ -86,6 +88,7 @@ import {
 	type SkillLite,
 } from "../src/skills.js";
 import { mapAgyToolToNative } from "../src/native-tools.js";
+import { bridgedPiTools } from "../src/bridge-catalog.js";
 import { Type } from "typebox";
 import { patchStatus, restorePatch } from "../src/patch-cleanup.js";
 import { withDialogLock } from "../src/dialog-lock.js";
@@ -177,7 +180,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	};
 	fileLog.log(
 		"extension-load",
-		{ engine, models: models.length, fallback: usingFallback, bridge: loadConfig().bridgeTools, askTool: loadConfig().askTool },
+		{ engine, models: models.length, fallback: usingFallback, bridge: loadConfig().bridgeTools, askTool: loadConfig().askTool, webTools: loadConfig().webTools },
 		"info",
 	);
 
@@ -185,6 +188,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// MCP bridge handle, declared early: the ACP engine reads the bridge port
 	// at session/new / session/load time.
 	let mcpHandle: McpServerHandle | null = null;
+	// Session-only visibility overrides; never change either application's MCP config.
+	const hiddenBridgeTools = new Set<string>();
+	const getBridgeTools = () => bridgedPiTools(pi.getAllTools(), pi.getActiveTools(), loadConfig().bridgeTools, hiddenBridgeTools);
 	// Approval-gate hook script (per-pid, token embedded). Written at session
 	// start when the gate is active; removed at session_shutdown.
 	let gateScriptPath: string | null = null;
@@ -328,12 +334,53 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			),
 	);
 	const replay = new WrapperReplay();
+	// ACP tool activity is display-only: durable Pi entries with native-looking
+	// titles and optional diffs. Unlike a synthetic Pi toolCall this does not
+	// re-execute edits, park the turn, or add tool results to model context.
+	if (engine === "acp") {
+		pi.registerEntryRenderer<NativeDisplayEvent>("agy-native-event", (entry, { expanded }, theme) => {
+			const event = entry.data;
+			const title = (event?.path ? path.basename(event.path) : event?.command?.split(/\r?\n/, 1)[0] ?? event?.name ?? "tool").slice(0, 160);
+			const status = event?.status === "failed" ? theme.fg("error", "✗") : theme.fg("success", "✓");
+			const lines = [`${status} ${theme.fg("toolTitle", event?.name ?? "Antigravity")} ${theme.fg("muted", title)}`];
+			if (expanded) {
+				if (event?.path) lines.push(theme.fg("dim", event.path));
+				if (event?.diff) {
+					for (const line of event.diff.split("\n")) {
+						const color = line.startsWith("+") ? "toolDiffAdded" : line.startsWith("-") ? "toolDiffRemoved" : "toolDiffContext";
+						lines.push(theme.fg(color, line));
+					}
+				}
+				if (event?.output && (!event.diff || event.status === "failed")) lines.push(theme.fg("toolOutput", event.output));
+			}
+			return new Text(lines.join("\n"), 0, 0);
+		});
+	}
+	let pendingNativeTools = 0;
+	const onNativeEvent = (event: NativeDisplayEvent): void => {
+		if (engine !== "acp" || event.mcpServer === "pi-bridge") return;
+		// MCP calls through our own pi-bridge already have genuine Pi tool cards;
+		// only native Antigravity / other MCP events need display-only entries.
+		if (event.status === "started") {
+			pendingNativeTools++;
+			activeUi?.setStatus("agy-native", `agy ${event.name}… (${pendingNativeTools})`);
+			return;
+		}
+		pendingNativeTools = Math.max(0, pendingNativeTools - 1);
+		if (pendingNativeTools === 0) activeUi?.setStatus("agy-native", undefined);
+		// Bound persisted session size; the ACP result and diff may be megabytes.
+		pi.appendEntry<NativeDisplayEvent>("agy-native-event", {
+			...event,
+			output: event.output?.slice(0, 4000),
+			diff: event.diff?.slice(0, 12000),
+			command: event.command?.slice(0, 500),
+		});
+	};
 	// Native re-exec only emits for builtins actually active in the session;
 	// anything else (or an unknown name) falls back to the wrapper card.
 	const nativeActive = (name: string): boolean => {
 		try {
-			const getAll = (pi as unknown as { getAllTools: () => Array<{ name: string }> }).getAllTools.bind(pi);
-			return getAll().some((t) => t.name === name);
+			return pi.getActiveTools().includes(name);
 		} catch {
 			return false;
 		}
@@ -354,6 +401,35 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	};
 	streamDriver.onTurnEnd = onTurnEnd;
 	acpDriver.onTurnEnd = onTurnEnd;
+	// Pi's normal footer receives the incremental usage above. Mark the
+	// numbers as estimates in the status area too; ACP currently drops the
+	// SDK's exact usage metadata before it reaches the client.
+	if (engine === "acp") {
+		let lastUsageStatus = "";
+		pi.on("message_update", (event, ctx) => {
+			if (!ctx.hasUI || event.message.role !== "assistant" || event.message.provider !== "antigravity" || loadConfig().acp.usageEstimate === "off") return;
+			const { input, output } = event.message.usage;
+			const status = `ACP ≈ ${input} in / ${output} out`;
+			if (status !== lastUsageStatus) {
+				lastUsageStatus = status;
+				ctx.ui.setStatus("agy-usage", status);
+			}
+		});
+		const clearUsageStatus = (_event: unknown, ctx: { hasUI: boolean; ui: ExtensionUIContext }) => {
+			lastUsageStatus = "";
+			if (ctx.hasUI) ctx.ui.setStatus("agy-usage", undefined);
+		};
+		pi.on("agent_end", (event, ctx) => {
+			clearUsageStatus(event, ctx);
+			pendingNativeTools = 0;
+			if (ctx.hasUI) ctx.ui.setStatus("agy-native", undefined);
+		});
+		pi.on("session_shutdown", (event, ctx) => {
+			clearUsageStatus(event, ctx);
+			pendingNativeTools = 0;
+			if (ctx.hasUI) ctx.ui.setStatus("agy-native", undefined);
+		});
+	}
 	const streamSimple = createStreamSimple({
 		entries,
 		store,
@@ -362,6 +438,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		roundTrips,
 		replay,
 		nativeActive,
+		onNativeEvent,
 		engine,
 		log: fileLog.log.bind(fileLog),
 	});
@@ -393,6 +470,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		acpDriver,
 		engine,
 		getMcpPort: () => mcpHandle?.port ?? null,
+		bridgeTools: getBridgeTools,
+		hiddenBridgeTools,
 		acpLog,
 		fileLog,
 		authCapture: authCapture ?? null,
@@ -409,6 +488,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// pi-ask-antigravity keeps deferring even then: off means NO delegation
 	// tool from either package, not a fallback to pi-ask-antigravity.
 	if (loadConfig().askTool) await registerAskAntigravityTool(pi, toolModels, fileLog.log.bind(fileLog));
+	// Web tools are opt-in (config.webTools, default off): Antigravity sessions
+	// already have native web tools; these serve NON-Antigravity providers.
+	if (loadConfig().webTools) registerWebTools(pi, { log: fileLog.log.bind(fileLog) });
 
 	// Display-only wrapper tool: the provider emits mutating agy steps as
 	// toolCalls against it (never re-executed - execute() replays the output
@@ -633,22 +715,13 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		const bridgeMode: BridgeTools = loadConfig().bridgeTools;
 		if (bridgeMode === "none") return; // user opted out
 		if (mcpHandle) return; // already running (reload re-fires session_start)
-		const SKIP = new Set(["AskAntigravity"]);
 		// pi loads project skill locations only after the project is trusted;
 		// mirror that gate. Global skill dirs are always scanned.
 		const skills: SkillLite[] = scanSkills(ctx.isProjectTrusted() ? process.cwd() : undefined);
-		const getAll = (pi as unknown as {
-			getAllTools: () => Array<{ name: string; description?: string; parameters?: object; sourceInfo?: { source?: string } }>;
-		}).getAllTools.bind(pi);
 		const listTools = () => {
-			const all = getAll();
-			const filtered =
-				bridgeMode === "mcp"
-					? all.filter((t) => /pi-mcp-adapter/.test(t.sourceInfo?.source ?? ""))
-					: all.filter((t) => t.sourceInfo?.source !== "builtin");
-			const tools = filtered
-				.filter((t) => !SKIP.has(t.name))
-				.map((t) => {
+			// /mcp and pi.setActiveTools() update the same live catalog. ACP gets
+			// this endpoint through session/new or session/load; no global config write.
+			const tools = getBridgeTools().map((t) => {
 					let inputSchema: object = { type: "object", properties: {}, additionalProperties: true };
 					try {
 						if (t.parameters) inputSchema = JSON.parse(JSON.stringify(t.parameters)) as object;
@@ -657,7 +730,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 					}
 					return { name: t.name, description: t.description ?? t.name, inputSchema };
 				});
-			if (skills.length > 0) {
+			if (skills.length > 0 && loadConfig().bridgeTools !== "none") {
 				tools.push({
 					name: ACTIVATE_SKILL_TOOL_NAME,
 					description: `Activate a pi Agent Skill by name. Catalog:\n${catalogSummary(skills)}`,
@@ -695,6 +768,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 				return Promise.resolve(formatPollAnswer(wanted, roundTrips.poll(wanted)));
 			}
 			if (name !== ACTIVATE_SKILL_TOOL_NAME) {
+				// A cached MCP catalog is not authorization. An inactive/hidden tool
+				// must not get parked into Pi, even if agy retained its old schema.
+				if (!getBridgeTools().some((tool) => tool.name === name)) {
+					return Promise.resolve({ content: [{ type: "text", text: `Pi tool ${name} is not active or not exposed to Antigravity` }], isError: true });
+				}
 				return roundTrips.onToolCall(callId, name, args, signal).then((r) => {
 					// Early-ack: answer the HTTP request before agy's ~180s client
 					// deadline with a poll handle; pi keeps executing meanwhile.
@@ -704,7 +782,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 				});
 			}
 			const wanted = typeof args.name === "string" ? args.name : "";
-			const skill = findSkillByName(skills, wanted);
+			const skill = loadConfig().bridgeTools !== "none" ? findSkillByName(skills, wanted) : undefined;
 			const body = skill ? readSkillBody(skill) : `unknown skill: ${wanted || "(none given)"}`;
 			return Promise.resolve({
 				content: [
@@ -730,14 +808,21 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			// suppressed are healed here - but only when no live delegation is in
 			// flight anywhere (marker-aware heal). A blind re-enable used to
 			// un-hide the bridge during another session's active delegation.
+			// Global-config hygiene runs on BOTH engines: a crashed stream-json
+			// session must not leave dead-pid entries or stuck suppression flags
+			// for the next one.
 			sweepStaleBridgeServers();
 			healBridgeSuppression();
-			registerBridgeServer({
-				pid: process.pid,
-				port: r.handle.port,
-				token: r.handle.token,
-				tokenHeader: TOKEN_HEADER,
-			});
+			// ACP supplies the bridge per-session (session/new | session/load);
+			// only the stream-json CLI reads the global MCP config.
+			if (engine === "stream-json") {
+				registerBridgeServer({
+					pid: process.pid,
+					port: r.handle.port,
+					token: r.handle.token,
+					tokenHeader: TOKEN_HEADER,
+				});
+			}
 			// --- Approval gate (docs/TODO.md 2.5) ------------------------------
 			// agy native tool calls pass through a pi-side approval: a PreToolUse
 			// hook parks in the bridge, the provider emits a shadow toolUse, and
@@ -862,7 +947,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		// ("quit") - the connection kill is identical and nothing runs after.
 		await streamDriver.close("recycle", "session shutdown");
 		await acpDriver.close("recycle", "session shutdown");
-		unregisterBridgeServer(process.pid);
+		if (engine === "stream-json") unregisterBridgeServer(process.pid);
+		hiddenBridgeTools.clear();
 		// Approval gate: unstage hooks and remove the per-pid script. Pending
 		// approvals already failed closed via handle close (bridge shutdown deny).
 		const unstaged = removeGateHooks();
@@ -897,6 +983,8 @@ interface AgyCommandCtx {
 	/** Engine latched at extension load (see the provider wiring note). */
 	engine: Engine;
 	getMcpPort: () => number | null;
+	bridgeTools: () => Array<{ name: string }>;
+	hiddenBridgeTools: Set<string>;
 	/** Shared ACP log sink (login URL surfacing + failure events). */
 	acpLog: (msg: string, data?: unknown) => void;
 	/** Daily file logger (src/daily-log.ts); command + doctor surfacing. */
@@ -916,6 +1004,7 @@ interface PendingConfig {
 	defaultThinking?: ThinkingTier;
 	turnTimeoutMin?: number;
 	askTool?: boolean;
+	webTools?: boolean;
 	bridgeTools?: BridgeTools;
 	digest?: boolean;
 	systemPrompt?: boolean;
@@ -935,6 +1024,7 @@ function statusText(ctx: AgyCommandCtx): string {
 		row("mode:", config.mode),
 		row("permissions:", perm),
 		row("AskAntigravity tool:", config.askTool ? "on" : "off"),
+		row("Web tools:", config.webTools ? "on" : "off"),
 		row("AskAntigravity model:", config.defaultModel),
 		row("AskAntigravity thinking:", config.defaultThinking),
 		row("sessions:", `${ctx.store.size} bound`),
@@ -943,7 +1033,7 @@ function statusText(ctx: AgyCommandCtx): string {
 		row("digest:", config.digest ? "on" : "off"),
 		row("system prompt:", config.systemPrompt ? "on" : "off"),
 		"",
-		"Subcommands: /agy auth, /agy auth-manual, /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy permissions on|off, /agy ask on|off, /agy model <alias>, /agy thinking low|medium|high, /agy bridge all|mcp|none, /agy digest on|off, /agy system-prompt on|off, /agy acp-bin <path|auto>, /agy patch-cleanup, /agy clear",
+		"Subcommands: /agy auth, /agy auth-manual, /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy permissions on|off, /agy ask on|off, /agy model <alias>, /agy thinking low|medium|high, /agy bridge all|mcp|none, /agy tools [hide|show <name>|reset], /agy web on|off, /agy digest on|off, /agy system-prompt on|off, /agy acp-bin <path|auto>, /agy patch-cleanup, /agy clear",
 	].join("\n");
 }
 
@@ -951,7 +1041,7 @@ function statusText(ctx: AgyCommandCtx): string {
 function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	pi.registerCommand("agy", {
 		description:
-			"Antigravity provider: status, doctor, settings picker, clear sessions. Usage: /agy [status|doctor|auth|auth-manual|engine stream-json|acp|mode plan|accept-edits|permissions on|off|ask on|off|model <alias>|thinking low|medium|high|bridge all|mcp|none|digest on|off|system-prompt on|off|timeout <1-1440|off>|acp-bin <path|auto>|patch-cleanup|clear]",
+			"Antigravity provider: status, doctor, settings picker, clear sessions. Usage: /agy [status|doctor|auth|auth-manual|engine stream-json|acp|mode plan|accept-edits|permissions on|off|ask on|off|model <alias>|thinking low|medium|high|bridge all|mcp|none|tools [hide|show <name>|reset]|web on|off|digest on|off|system-prompt on|off|timeout <1-1440|off>|acp-bin <path|auto>|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
 			if (ui) activeUi = ui;
@@ -1245,13 +1335,31 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				if (val === "all" || val === "mcp" || val === "none") {
 					const next = saveConfig({ bridgeTools: val });
 					ui?.notify(
-						next.bridgeTools === "none"
-							? "bridge off. The MCP tool bridge will not start on the next pi start (or /reload)."
-							: `bridge tools set to ${next.bridgeTools}. The catalog rebuilds on the next pi start (or /reload).`,
+						ctx.getMcpPort() === null
+							? `bridge ${next.bridgeTools}. The bridge server is not running; /reload to apply.`
+							: `bridge ${next.bridgeTools}. The active catalog and call guard update now; ACP may retain cached schemas until the next session/load.`,
 						"info",
 					);
 				} else {
-					ui?.notify(`bridge: ${loadConfig().bridgeTools}\nusage: /agy bridge all|mcp|none\n  all: every non-builtin pi tool (default). mcp: pi-mcp-adapter tools + skills only. none: bridge off.`, "info");
+					ui?.notify(`bridge: ${loadConfig().bridgeTools}\nusage: /agy bridge all|mcp|none\n  all: active non-builtin pi tools. mcp: active pi-mcp-adapter tools + skills. none: bridge off.`, "info");
+				}
+				return;
+			}
+			if (sub === "tools") {
+				const name = (args ?? "").trim().split(/\s+/).slice(2).join(" ");
+				if (val === "reset") {
+					ctx.hiddenBridgeTools.clear();
+					ui?.notify("Antigravity tool visibility reset for this Pi session. Pi's active tools are unchanged.", "info");
+				} else if ((val === "hide" || val === "show") && name) {
+					if (!pi.getAllTools().some((tool) => tool.name === name)) {
+						ui?.notify(`Unknown Pi tool: ${name}`, "error");
+						return;
+					}
+					if (val === "hide") ctx.hiddenBridgeTools.add(name);
+					else ctx.hiddenBridgeTools.delete(name);
+					ui?.notify(`${name}: ${val === "hide" ? "hidden from Antigravity" : "visible if active in Pi"}. No MCP config changed.`, "info");
+				} else {
+					ui?.notify(`Exposed active Pi tools: ${ctx.bridgeTools().map((tool) => tool.name).join(", ") || "(none)"}\nHidden in this session: ${[...ctx.hiddenBridgeTools].join(", ") || "(none)"}\n/agy tools hide|show <exact Pi tool name> | reset\nUse Pi's /mcp or pi.setActiveTools() to change the underlying active tools.`, "info");
 				}
 				return;
 			}
@@ -1278,6 +1386,20 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				}
 				return;
 			}
+			if (sub === "web") {
+				if (val === "on" || val === "off") {
+					const next = saveConfig({ webTools: val === "on" });
+					ui?.notify(
+						next.webTools
+							? "Web tools on: agy_web_search and agy_read_url register on the next pi start (or /reload). Each call spends Antigravity quota."
+							: "Web tools off: agy_web_search and agy_read_url will not register on the next pi start (or /reload).",
+						"info",
+					);
+				} else {
+					ui?.notify(`Web tools: ${loadConfig().webTools ? "on" : "off"}\nusage: /agy web on|off\nExposes agy_web_search + agy_read_url as Pi tools for ANY provider (Antigravity sessions already have native web tools). Default off; each call spends Antigravity quota.`, "info");
+				}
+				return;
+			}
 			if (sub === "digest") {
 				if (val === "on" || val === "off") {
 					const next = saveConfig({ digest: val === "on" });
@@ -1367,6 +1489,14 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			currentValue: config.askTool ? "on" : "off",
 			values: ["on", "off"],
 		},
+		{
+			id: "web",
+			label: "Web tools",
+			description:
+				"Register agy_web_search + agy_read_url as Pi tools for ANY provider. Default off: Antigravity sessions already have native web tools, and each call spends Antigravity quota. Takes effect on the next pi start (or /reload).",
+			currentValue: config.webTools ? "on" : "off",
+			values: ["on", "off"],
+		},
 		{
 			id: "model",
 			label: "AskAntigravity model",
@@ -1437,6 +1567,8 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 					pending.defaultThinking = newValue as ThinkingTier;
 				} else if (id === "ask") {
 					pending.askTool = newValue === "on";
+				} else if (id === "web") {
+					pending.webTools = newValue === "on";
 				} else if (id === "bridge") {
 					pending.bridgeTools = newValue as BridgeTools;
 				} else if (id === "turn-cap") {
@@ -1483,6 +1615,7 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 				? `permissions=${next.skipPermissions ? "auto-approved" : "prompt"}`
 				: null,
 			pending.askTool !== undefined ? `AskAntigravity tool=${next.askTool ? "on" : "off"}` : null,
+			pending.webTools !== undefined ? `webTools=${next.webTools ? "on" : "off"}` : null,
 			pending.defaultModel !== undefined ? `AskAntigravity model=${next.defaultModel}` : null,
 			pending.defaultThinking !== undefined ? `AskAntigravity thinking=${next.defaultThinking}` : null,
 			pending.bridgeTools !== undefined ? `bridge=${next.bridgeTools}` : null,

package/package.json

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

package/src/acp/connection.ts

@@ -25,6 +25,7 @@ import os from "node:os";
 import path from "node:path";
 import { parseAuthPort, readLastUrl } from "./browser-capture.js";
 import { frameCarriesUsage } from "./events.js";
+import type { AgyUsage } from "../driver-types.js";
 import { JsonRpcResponseError, JsonRpcSession } from "./jsonrpc.js";
 
 export interface AcpMcpServer {
@@ -82,6 +83,10 @@ export class AcpConnection {
 	#rpc: JsonRpcSession | undefined;
 	#stderrTail = "";
 	#usageSeen = false;
+	/** Set ONLY by a parsed PromptResponse.usage; this gates estimate
+	 *  suppression. #usageSeen stays diagnostic: any usage-shaped frame trips
+	 *  it, and the connection outlives turns. */
+	#exactUsageSeen = false;
 	#exited = false;
 	#killed = false;
 	#suppressUpdates = false;
@@ -115,6 +120,11 @@ export class AcpConnection {
 		return this.#usageSeen;
 	}
 
+	/** True once the server sent real per-turn usage (PromptResponse.usage). */
+	get exactUsageSeen(): boolean {
+		return this.#exactUsageSeen;
+	}
+
 	/** While true, session/update notifications are dropped: they are the
 	 *  full-text history replay that precedes a session/load response, never
 	 *  live generation (run 6). */
@@ -237,7 +247,7 @@ export class AcpConnection {
 		text: string,
 		images: Array<{ data: string; mimeType: string }> = [],
 		contextBlock?: { uri: string; text: string },
-	): Promise<{ stopReason: string }> {
+	): Promise<{ stopReason: string; usage?: AgyUsage }> {
 		// Block order: images, then the embedded-context resource (pi-side
 		// digest), then the text question last (it refers to everything before
 		// it). Shapes per the ACP v1 content-block schema; embeddedContext is
@@ -264,7 +274,15 @@ export class AcpConnection {
 		if (typeof stopReason !== "string") {
 			throw new Error("ACP session/prompt returned no stopReason");
 		}
-		return { stopReason };
+		// Optional, unstable ACP PromptResponse.usage: absent on 1.1.1 but
+		// parsed for the day the server forwards its SDK usage_metadata. Never
+		// infer exact counts from a context-window usage_update ({used,size}).
+		const usage = parseAcpTurnUsage(result?.usage);
+		if (usage) {
+			this.#usageSeen = true;
+			this.#exactUsageSeen = true;
+		}
+		return { stopReason, ...(usage ? { usage } : {}) };
 	}
 
 	/** Probe-and-cancel. Returns supported:false when the server does not
@@ -430,6 +448,28 @@ export class AcpConnection {
 	}
 }
 
+/** ACP's optional (unstable) per-turn PromptResponse.usage, not the
+ *  session/usage_update context-window occupancy notification. */
+export function parseAcpTurnUsage(value: unknown): AgyUsage | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const u = value as Record<string, unknown>;
+	const count = (v: unknown): number | undefined =>
+		typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? v : undefined;
+	const input = count(u.inputTokens);
+	const output = count(u.outputTokens);
+	const total = count(u.totalTokens);
+	const thought = count(u.thoughtTokens);
+	const cacheRead = count(u.cachedReadTokens);
+	if (input === undefined || output === undefined || total === undefined) return undefined;
+	return {
+		input_tokens: input,
+		output_tokens: output,
+		total_tokens: total,
+		...(thought === undefined ? {} : { thinking_tokens: thought }),
+		...(cacheRead === undefined ? {} : { cache_read_tokens: cacheRead }),
+	};
+}
+
 export function translateError(method: string, err: unknown): Error {
 	if (err instanceof AcpAuthError) return err;
 	if (err instanceof JsonRpcResponseError) {