@estebanforge/pi-antigravity-bridge 1.4.2 → 1.4.4

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.4] - 2026-09-04
+
+### Added
+
+- The Google sign-in URL now surfaces in pi. The ACP server hands the OAuth URL only to the browser-open call (nothing on stdout/stderr, headless or not), so a `BROWSER` wrapper script records the URL and forwards to the real opener; the connection watches the record file and logs it as an `auth-url` event. The extension toasts it at warning level with the ssh port-forward command for the redirect port, so logins work from SSH sessions on remote machines; local users keep the automatic browser open and get the URL as a fallback. An existing `BROWSER` setting is chained, not replaced.
+
+### Fixed
+
+- ACP login pending was reported only at the moment setup wrote `settings.json`, so after the restart, with `settings.json` in place but the browser login never completed, every check went silent: no toast, no hint, while the first ACP message had no token to use. `needsLogin` now tracks the token file (stat only, never read): `oauth-personal` without `acp_token.json` is login-pending, so the switch-time toast, the picker, and the `session_start` self-heal keep saying so on every start until the login is done.
+
+### Changed
+
+- Engine switching is command-only now: `/agy engine stream-json|acp`. The bare-`/agy` settings picker no longer carries an Engine row (nor the post-save setup run), so the switch surface cannot be hit accidentally; `/agy engine acp` keeps the self-service setup (binary + auth) and the login warning. The picker's plan+acp (RC01) guard stays in a narrower form: the mode row alone can still produce `plan` while the engine is `acp`.
+- ACP login-pending messages rewritten for end users: what happens (the server opens the Google sign-in page in your browser on the first Antigravity message), when (after the restart or immediately, per moment), and which account (your Antigravity subscription, the same Google account as the `agy` CLI). No URL to open manually. All remaining moments (engine switch, session start) now toast at warning level so the pending action stands out.
+- The "Turn engine" wording became "Engine" in the README env table, the config comment, and the architecture doc heading; the picker row itself is gone (engine switching is command-only, see above).
+
+## [1.4.3] - 2026-09-04
+
+### Added
+
+- AskAntigravity tool toggle: `/agy ask on|off`, an "AskAntigravity tool" row in the bare-`/agy` picker, and the `askTool` config key (env `AGY_ASK_TOOL`). Default on; `off` skips registering the AskAntigravity one-shot delegation tool entirely, for users who want only the provider and its models and no delegation tool in the model's window context. When the separate pi-ask-antigravity package is also installed, `off` means no delegation tool from either package (no fallback). Takes effect on the next pi start (or /reload); `/agy status` shows the state.
+
+### Changed
+### Changed
+
+- The bare-`/agy` settings picker gains a Turn engine row (`stream-json`/`acp`). Saving `acp` persists the switch, then runs the same self-service setup as `/agy engine acp` (binary install + auth bootstrap, `acp.bin` updated). The plan+acp RC01 guard now evaluates the effective engine AND mode after the save, so a config already in `plan` plus a fresh `acp` pick is refused instead of persisting an invalid combination (peer-review find).
+- "Tool default model/thinking" renamed to "AskAntigravity model/thinking" across the picker, `/agy status`, and toasts; descriptions and README now state the values are fallbacks that callers may override per call.
+- All ACP login-pending messages share one wording that names the antigravity-acp server and its place in Google's Antigravity suite (agy desktop, agy editor, agy cli, agy acp), and clarifies the login: same Google account as the agy CLI, separate login with its own token file.
+
 ## [1.4.2] - 2026-09-04
 
 ### Changed

package/README.md

@@ -25,7 +25,7 @@ Turns run through one of two engines behind the same provider surface (`config.e
 
 Engine-dependent features: pi image attachments ride natively only on the ACP engine (the picker offers image attach automatically when `config.engine` is `acp`; the stream-json CLI prompt is text-only). With the optional G1 digest enabled, its delivery also differs: ACP ships it as a native `embeddedContext` resource block, stream-json prepends it to the prompt text.
 
-Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: on your first ACP message the server opens the Google login in your browser, and you sign in with the same account and plan you use for the Antigravity CLI (`agy`). It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy acp-auth`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
+Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: on your first ACP message the server opens the Google login in your browser, and you sign in with the same account and plan you use for the Antigravity CLI (`agy`). If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy acp-auth`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
 
 ## What it cannot do
 
@@ -104,11 +104,12 @@ 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` |
 | `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) or `off` (agy-native behavior) | `on` |
 
-Env overrides: `AGY_BRIDGE_TOOLS`, `AGY_DIGEST`, `AGY_SYSTEM_PROMPT`. 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_DIGEST`, `AGY_SYSTEM_PROMPT`. 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.
 
@@ -123,8 +124,9 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy mode plan            review-only: agy plans but writes nothing
 /agy mode accept-edits    agy applies edits directly (default)
 /agy permissions on|off   auto-approve / prompt for tool calls (see warning)
-/agy model flash|pro|gemini   default model alias for the AskAntigravity tool
-/agy thinking low|medium|high default thinking tier for the AskAntigravity tool
+/agy ask on|off           register the AskAntigravity delegation tool (default on; off keeps only the provider and models, even with pi-ask-antigravity installed)
+/agy model flash|pro|gemini   fallback model for the AskAntigravity tool; callers may override per call
+/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 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)
@@ -152,7 +154,7 @@ For isolation when running any agent that executes commands without a confirmati
 | Variable | Purpose |
 | --- | --- |
 | `AGY_BIN` | Path to the agy binary. Defaults to `agy` on PATH. |
-| `AGY_ENGINE` | Turn engine: `stream-json` (default) or `acp`. Wins over the config file. |
+| `AGY_ENGINE` | Engine: `stream-json` (default) or `acp`. Wins over the config file. |
 | `AGY_ACP_BIN` | Path to the ACP server binary (`agy_acp_server.par`). Defaults to `agy_acp_server.par` on PATH. Wins over `config.acp.bin`. When neither points at a binary, auto-setup installs one. |
 | `AGY_EXTRA_ARGS` | Extra args appended to every invocation. Whitespace-split. |
 | `AGY_CONVERSATIONS_DIR` | Override the conversations DB directory. |

package/docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 How the provider works internally. For build/test/debug workflow see [DEVELOPMENT.md](./DEVELOPMENT.md).
 
-## Turn engine
+## Engine
 
 The provider ships two turn engines behind one contract (`TurnDriver`,
 `src/driver-types.ts`): the default **stream-json engine** (below) and the

package/extensions/index.ts

@@ -40,6 +40,7 @@ import { SessionStore } from "../src/sessions.js";
 import { ToolRoundTrips, WrapperReplay, createStreamSimple } from "../src/provider.js";
 import { AgyDriver } from "../src/driver.js";
 import { AcpDriver } from "../src/acp/driver.js";
+import { setupAuthUrlCapture } from "../src/acp/browser-capture.js";
 import { ensureAcpReady, inspectAcpSetup } from "../src/acp/setup.js";
 import type { TurnDriver } from "../src/driver-types.js";
 import { CONFIG_PATH, loadConfig, saveConfig, type AgyMode, type BridgeTools, type Engine, type ThinkingTier } from "../src/config.js";
@@ -58,6 +59,12 @@ import { mapAgyToolToNative } from "../src/native-tools.js";
 import { Type } from "typebox";
 import { patchStatus, restorePatch } from "../src/patch-cleanup.js";
 
+// Last UI seen (session_start / /agy commands). The ACP login URL arrives
+// via the driver log sink, which has no command context; the stash lets that
+// sink toast instead of only logging to stderr. Module scope: both the
+// default export (session_start, log sink) and registerAgyCommand assign it.
+let activeUi: ExtensionUIContext | null = null;
+
 function resolveAgyBinary(): string {
 	return process.env.AGY_BIN || "agy";
 }
@@ -102,6 +109,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// ACP self-heal runs once per process (session_start re-fires on /reload;
 	// a ready setup is two file stats, so re-running is harmless anyway).
 	let acpSelfHealRan = false;
+	// OAuth URL capture: the server hands the login URL only to the
+	// browser-open call (nothing on stdio), so a BROWSER wrapper records it
+	// and the driver logs it as "auth-url". Local users keep the automatic
+	// browser open; over SSH the URL surfaces for copy-paste with the
+	// port-forward command.
+	const authCapture = setupAuthUrlCapture();
+	if (!authCapture && process.platform !== "win32") {
+		// Rare (unwritable data dir). Surfacing the diagnostic: without it,
+		// login URLs would silently stop appearing on headless boxes.
+		console.error("[antigravity-bridge] OAuth URL capture unavailable; login URL surfacing is off (setup failed).");
+	}
 	// Two turn engines behind one contract (plan §9): stream-json (tested
 	// default) and the official ACP server (opt-in via config.engine, off by
 	// default). Neither spawns anything until its first turn.
@@ -121,7 +139,17 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		// Resolved per connection: the setup flow can install the binary and
 		// update acp.bin mid-session; the next turn picks it up (no restart).
 		bin: () => loadConfig().acp.bin,
+		...(authCapture ? { extraEnv: authCapture.browserEnv, authUrlFile: authCapture.file } : {}),
 		log: (msg, data) => {
+			if (msg === "auth-url") {
+				const { url, port } = (data ?? {}) as { url?: string; port?: number | null };
+				if (!url) return;
+				const ssh = port ? `\nSSH session? Forward the port on your machine first:\n  ssh -N -L ${port}:127.0.0.1:${port} <user@host>` : "";
+				const text = `Google sign-in URL for the ACP engine:\n${url}${ssh}`;
+				if (activeUi) activeUi.notify(text, "warning");
+				else console.error(`[antigravity-bridge acp] ${text}`);
+				return;
+			}
 			if (!acpFailures.has(msg)) return;
 			console.error(`[antigravity-bridge acp] ${msg}${data !== undefined ? " " + JSON.stringify(data) : ""}`);
 		},
@@ -209,8 +237,13 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// AskAntigravity tool: one-shot delegation to agy (ported from
 	// pi-ask-antigravity). When both extensions are installed, the bridge wins
 	// and pi-ask-antigravity registers nothing (its load-time defer guard
-	// detects this package via import.meta.resolve).
-	await registerAskAntigravityTool(pi, toolModels);
+	// detects this package via import.meta.resolve). Opt-out: askTool=false
+	// (config file, AGY_ASK_TOOL, /agy ask, or the picker) skips registration
+	// entirely - users who want only the provider keep a clean tool list.
+	// Note: the active flag below is set regardless of askTool, so
+	// 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);
 
 	// Display-only wrapper tool: the provider emits mutating agy steps as
 	// toolCalls against it (never re-executed - execute() replays the output
@@ -236,6 +269,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// normal toolUse loop (native cards, permissions, hooks) - no patch, no
 	// privileged API. Started on session_start, torn down on session_shutdown.
 	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.hasUI) activeUi = ctx.ui;
 		// Legacy cleanup: users who ran the old consent-gated patcher still
 		// carry pi.invokeTool in their installed pi. Inert, but tell them once
 		// and offer /agy patch-cleanup. Never auto-edits the install.
@@ -265,9 +299,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
 					}
 					if (status.needsLogin) {
-						const msg =
-							"ACP: one-time Google login pending. Your next antigravity message opens the browser; sign in with your Antigravity subscription account (the same login as the agy CLI). Tokens stay on your machine.";
-						if (ctx.hasUI) ctx.ui.notify(msg, "info");
+						const msg = acpLoginPending("Your next Antigravity message opens the Google sign-in page in your browser.");
+						if (ctx.hasUI) ctx.ui.notify(msg, "warning");
 						else console.error(`[antigravity-bridge] ${msg}`);
 					}
 					return;
@@ -368,6 +401,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		}
 	});
 	pi.on("session_shutdown", async () => {
+		// The UI is going away; a later auth-url must fall back to stderr
+		// instead of toasting into a dead UI (where it would be lost).
+		activeUi = null;
 		const h = mcpHandle;
 		mcpHandle = null;
 		await h?.close();
@@ -379,6 +415,14 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 
 // --- /agy command -----------------------------------------------------------
 
+/** Shared body for every ACP-login-pending moment (session_start self-heal,
+ *  /agy engine acp, picker). End-user simple: what happens, when, which
+ *  account. The server opens the browser itself, so there is no URL to
+ *  open manually. `browserTrigger` says when that happens. */
+function acpLoginPending(browserTrigger: string): string {
+	return `One-time sign-in needed to finish ACP setup. ${browserTrigger} Use the Google account of your Antigravity subscription (the same account as your agy CLI login). If no browser opens, pi shows the sign-in URL to copy. The token stays on your machine; this extension never sees it.`;
+}
+
 interface AgyCommandCtx {
 	entries: AgyModelEntry[];
 	store: SessionStore;
@@ -395,6 +439,7 @@ interface PendingConfig {
 	skipPermissions?: boolean;
 	defaultModel?: string;
 	defaultThinking?: ThinkingTier;
+	askTool?: boolean;
 	bridgeTools?: BridgeTools;
 	digest?: boolean;
 	systemPrompt?: boolean;
@@ -404,21 +449,25 @@ function statusText(ctx: AgyCommandCtx): string {
 	const config = loadConfig();
 	const source = ctx.usingFallback ? "fallback (agy models failed)" : "discovered";
 	const perm = config.skipPermissions ? "auto-approved (DANGEROUS)" : "prompt (hangs in -p)";
+	// padEnd keyed to the longest label ("AskAntigravity thinking:") so the
+	// value column stays aligned as labels grow.
+	const row = (label: string, value: string) => `  ${label.padEnd(24)} ${value}`;
 	return [
 		"Antigravity bridge",
-		`  engine:        ${config.engine}${config.engine === "acp" ? " (official server, opt-in)" : ""}`,
-		`  models:        ${ctx.entries.length} ${source}`,
-		`  mode:          ${config.mode}`,
-		`  permissions:   ${perm}`,
-		`  tool model:    ${config.defaultModel}`,
-		`  tool thinking: ${config.defaultThinking}`,
-		`  sessions:      ${ctx.store.size} bound`,
-		`  config:        ${CONFIG_PATH}`,
-		`  bridge tools:  ${config.bridgeTools}`,
-		`  digest:        ${config.digest ? "on" : "off"}`,
-		`  system prompt: ${config.systemPrompt ? "on" : "off"}`,
+		row("engine:", `${config.engine}${config.engine === "acp" ? " (official server, opt-in)" : ""}`),
+		row("models:", `${ctx.entries.length} ${source}`),
+		row("mode:", config.mode),
+		row("permissions:", perm),
+		row("AskAntigravity tool:", config.askTool ? "on" : "off"),
+		row("AskAntigravity model:", config.defaultModel),
+		row("AskAntigravity thinking:", config.defaultThinking),
+		row("sessions:", `${ctx.store.size} bound`),
+		row("config:", CONFIG_PATH),
+		row("bridge tools:", config.bridgeTools),
+		row("digest:", config.digest ? "on" : "off"),
+		row("system prompt:", config.systemPrompt ? "on" : "off"),
 		"",
-		"Subcommands: /agy engine stream-json|acp, /agy mode plan|accept-edits, /agy permissions on|off, /agy bridge all|mcp|none, /agy model <alias>, /agy thinking low|medium|high, /agy digest on|off, /agy system-prompt on|off, /agy acp-bin <path|auto>, /agy acp-auth, /agy patch-cleanup, /agy clear",
+		"Subcommands: /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 acp-auth, /agy patch-cleanup, /agy clear",
 	].join("\n");
 }
 
@@ -426,9 +475,10 @@ 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|engine stream-json|acp|mode plan|accept-edits|permissions on|off|bridge all|mcp|none|model <alias>|thinking low|medium|high|digest on|off|system-prompt on|off|acp-bin <path|auto>|acp-auth|patch-cleanup|clear]",
+			"Antigravity provider: status, doctor, settings picker, clear sessions. Usage: /agy [status|doctor|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|acp-bin <path|auto>|acp-auth|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
+			if (ui) activeUi = ui;
 			const mode = cmdCtx.mode;
 			const sub = (args ?? "").trim().split(/\s+/)[0]?.toLowerCase();
 			const val = (args ?? "").trim().split(/\s+/)[1]?.toLowerCase();
@@ -483,12 +533,14 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						return;
 					}
 					saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
-					ui?.notify(
-						status.needsLogin
-							? "ACP engine ready. Your first ACP message opens the Google login in your browser: sign in with the account of your Antigravity subscription (the same login as the Antigravity CLI, agy). One-time; tokens stay on your machine and this extension never sees them. Takes effect on the next pi start (or /reload)."
-							: `ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`,
-						"info",
-					);
+					if (status.needsLogin) {
+						ui?.notify(
+							`ACP engine set. ${acpLoginPending("After the restart (pi restart or /reload), your first Antigravity message opens the Google sign-in page in your browser.")}`,
+							"warning",
+						);
+					} else {
+						ui?.notify(`ACP engine ready (auth: ${status.auth}). Takes effect on the next pi start (or /reload).`, "info");
+					}
 				} else {
 					ui?.notify(`current engine: ${loadConfig().engine}\nusage: /agy engine stream-json|acp`, "info");
 				}
@@ -529,8 +581,10 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						"   the antigravity-acp registry; point acp.bin or AGY_ACP_BIN at it.",
 						'2. Default: put {"auth":{"type":"oauth-personal"}} in',
 						"   ~/.gemini/antigravity-acp/settings.json, run one turn, and complete the",
-						"   Google login that opens in your browser (headless: tunnel 127.0.0.1:<port>",
-						"   over ssh, then open the URL on your machine).",
+						"   Google login that opens in your browser. No browser (SSH session)?",
+						"   pi shows the sign-in URL to copy; forward the redirect port over ssh",
+						"   (ssh -N -L <port>:127.0.0.1:<port> <user@host>), then open the URL",
+						"   on your machine.",
 						'   Headless alternative: GEMINI_API_KEY + {"auth":{"type":"gemini-api-key"}}',
 						"   (metered paid API - not your Antigravity plan). The key is used only",
 						"   when that type is selected; with the default oauth-personal in place,",
@@ -617,9 +671,23 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 			if (sub === "model") {
 				if (val && val.length > 0) {
 					const next = saveConfig({ defaultModel: val });
-					ui?.notify(`tool default model set to ${next.defaultModel}`, "info");
+					ui?.notify(`AskAntigravity default model set to ${next.defaultModel}`, "info");
 				} else {
-					ui?.notify(`tool model: ${loadConfig().defaultModel}\nusage: /agy model flash|pro|gemini|<exact>`, "info");
+					ui?.notify(`AskAntigravity model: ${loadConfig().defaultModel} (fallback; callers may override per call)\nusage: /agy model flash|pro|gemini|<exact>`, "info");
+				}
+				return;
+			}
+			if (sub === "ask") {
+				if (val === "on" || val === "off") {
+					const next = saveConfig({ askTool: val === "on" });
+					ui?.notify(
+						next.askTool
+							? "AskAntigravity tool on. Registered on the next pi start (or /reload)."
+							: "AskAntigravity tool off. It is removed from the model's tool list on the next pi start (or /reload). Provider and models stay.",
+						"info",
+					);
+				} else {
+					ui?.notify(`AskAntigravity tool: ${loadConfig().askTool ? "on" : "off"}\nusage: /agy ask on|off`, "info");
 				}
 				return;
 			}
@@ -655,9 +723,9 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 			if (sub === "thinking") {
 				if (val === "low" || val === "medium" || val === "high") {
 					const next = saveConfig({ defaultThinking: val as ThinkingTier });
-					ui?.notify(`tool default thinking set to ${next.defaultThinking}`, "info");
+					ui?.notify(`AskAntigravity default thinking set to ${next.defaultThinking}`, "info");
 				} else {
-					ui?.notify(`tool thinking: ${loadConfig().defaultThinking}\nusage: /agy thinking low|medium|high`, "info");
+					ui?.notify(`AskAntigravity thinking: ${loadConfig().defaultThinking} (fallback; callers may override per call)\nusage: /agy thinking low|medium|high`, "info");
 				}
 				return;
 			}
@@ -679,10 +747,10 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 	});
 }
 
-/** Interactive settings picker (TUI only). Rows: the full runtime config
- *  surface (mode, permissions, model, thinking, bridge, digest, system
- *  prompt). Engine stays a subcommand: switching runs install + auth setup
- *  and needs a restart. */
+/** Interactive settings picker (TUI only). Rows: the runtime config surface
+ *  (mode, permissions, model, thinking, bridge, digest, system prompt).
+ *  Engine switching is command-only: /agy engine stream-json|acp (the
+ *  command also runs self-service binary + auth setup for acp). */
 async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promise<void> {
 	const config = loadConfig();
 	const pending: PendingConfig = {};
@@ -704,19 +772,27 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			currentValue: config.skipPermissions ? "auto-approved" : "prompt",
 			values: ["auto-approved", "prompt"],
 		},
+		{
+			id: "ask",
+			label: "AskAntigravity tool",
+			description:
+				"Register the AskAntigravity one-shot delegation tool. off removes it from the model's tool list (provider and models stay, even with the separate pi-ask-antigravity package installed). Takes effect on the next pi start (or /reload).",
+			currentValue: config.askTool ? "on" : "off",
+			values: ["on", "off"],
+		},
 		{
 			id: "model",
-			label: "Tool default model",
+			label: "AskAntigravity model",
 			description:
-				"Alias used when the AskAntigravity tool omits its model param. flash/pro/gemini, or an exact id.",
+				"AskAntigravity one-shot delegation tool: model used when its caller omits the model param. Callers may override per call; this is only the fallback. flash/pro/gemini, or an exact id. Does not affect the provider model you pick in /model.",
 			currentValue: config.defaultModel,
 			values: ["flash", "pro", "gemini"],
 		},
 		{
 			id: "thinking",
-			label: "Tool default thinking",
+			label: "AskAntigravity thinking",
 			description:
-				"Thinking tier used when the model alias names none. Pro has no Medium; it falls back to nearest.",
+				"AskAntigravity one-shot delegation tool: thinking tier used when the call names none. Callers may override per call; this is only the fallback. Pro has no Medium; it falls back to nearest.",
 			currentValue: config.defaultThinking,
 			values: ["low", "medium", "high"],
 		},
@@ -764,6 +840,8 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 					pending.defaultModel = newValue;
 				} else if (id === "thinking") {
 					pending.defaultThinking = newValue as ThinkingTier;
+				} else if (id === "ask") {
+					pending.askTool = newValue === "on";
 				} else if (id === "bridge") {
 					pending.bridgeTools = newValue as BridgeTools;
 				} else if (id === "digest") {
@@ -788,8 +866,15 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 
 	if (Object.keys(pending).length === 0) return;
 
-	if (pending.mode === "plan" && ctx.engine === "acp") {
-		ui.notify("the ACP engine has no plan mode (RC01). Switch /agy engine stream-json first.", "warning");
+	// The picker cannot switch engines (command-only: /agy engine), but the
+	// mode row can still produce plan while the latched engine is acp. ACP
+	// has no review-only mode (RC01); refuse the combination.
+	const nextMode = pending.mode ?? config.mode;
+	if (nextMode === "plan" && ctx.engine === "acp") {
+		ui.notify(
+			"plan + acp is not supported (RC01): the ACP engine has no review-only mode. /agy engine stream-json first, or /agy mode accept-edits.",
+			"warning",
+		);
 		return;
 	}
 
@@ -800,8 +885,9 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			pending.skipPermissions !== undefined
 				? `permissions=${next.skipPermissions ? "auto-approved" : "prompt"}`
 				: null,
-			pending.defaultModel !== undefined ? `tool model=${next.defaultModel}` : null,
-			pending.defaultThinking !== undefined ? `tool thinking=${next.defaultThinking}` : null,
+			pending.askTool !== undefined ? `AskAntigravity tool=${next.askTool ? "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,
 			pending.digest !== undefined ? `digest=${next.digest ? "on" : "off"}` : null,
 			pending.systemPrompt !== undefined ? `system-prompt=${next.systemPrompt ? "on" : "off"}` : null,
@@ -815,5 +901,4 @@ async function openAgyPicker(ui: ExtensionUIContext, ctx: AgyCommandCtx): Promis
 			"error",
 		);
 	}
-	void ctx;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "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/browser-capture.ts

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// The ACP server hands the Google OAuth URL ONLY to the browser-open call:
+// nothing on stdout or stderr, headless or not (verified per
+// docs/ACP-PROTOCOL-REFERENCE.md). The capture makes the URL visible:
+// BROWSER points at a wrapper that appends the URL to a record file and then
+// execs the real opener, and the connection watches the record file to log
+// "auth-url". Local users keep the automatic browser open; over SSH the user
+// copies the URL and forwards the redirect port.
+
+export interface AuthUrlCapture {
+	/** Spawn env for the ACP server (BROWSER -> wrapper script). */
+	browserEnv: Record<string, string>;
+	/** Record file the connection watches. */
+	file: string;
+	/** Most recent URL in the record file, or null. */
+	lastUrl(): string | null;
+}
+
+/** First existing executable named `name` on `env.PATH`, or null. */
+export function findOnPath(name: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+		if (!dir) continue;
+		const candidate = path.join(dir, name);
+		try {
+			const st = fs.statSync(candidate);
+			if (st.isFile() && (st.mode & 0o111) !== 0) return candidate;
+		} catch {
+			/* not here */
+		}
+	}
+	return null;
+}
+
+/** Last http(s) line of `file`, or null (absent/unreadable counts as empty). */
+export function readLastUrl(file: string): string | null {
+	try {
+		const lines = fs.readFileSync(file, "utf8").split("\n").filter((l) => /^https?:\/\//.test(l));
+		return lines.at(-1) ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/** Port of the OAuth loopback redirect (redirect_uri param), or null. */
+export function parseAuthPort(url: string): number | null {
+	try {
+		const redirect = new URL(url).searchParams.get("redirect_uri");
+		if (!redirect) return null;
+		const port = new URL(redirect).port;
+		return port ? Number(port) : null;
+	} catch {
+		return null;
+	}
+}
+
+const shQuote = (s: string): string => `'${s.replace(/'/g, "'\\''")}'`;
+
+/** Create the capture (record file + wrapper script) and return the spawn
+ *  env. Idempotent: the wrapper is rewritten only when content changes. The
+ *  opener to forward to is resolved once, at write time: an existing BROWSER
+ *  wins, then xdg-open, then macOS open; with none available the wrapper
+ *  records the URL and exits (headless: capture without an opener). The
+ *  forward word-splits the BROWSER value, so flag forms (`open -a Chrome`)
+ *  work; a BROWSER path containing spaces does not (rare, and BROWSER lists
+ *  are not honored either - the first entry is what chains). Windows browser
+ *  resolution differs; no capture there. */
+export function setupAuthUrlCapture(dataDir = path.join(os.homedir(), ".pi", "agent", "antigravity-bridge"), env: NodeJS.ProcessEnv = process.env): AuthUrlCapture | null {
+	if (process.platform === "win32") return null;
+	const file = path.join(dataDir, "acp-auth-urls.log");
+	const wrapper = path.join(dataDir, "acp-browser-wrapper.sh");
+	try {
+		fs.mkdirSync(dataDir, { recursive: true });
+		// Truncate: the file mirrors the current login attempt only. OAuth
+		// URLs carry state + PKCE challenges, so keep the record private.
+		fs.writeFileSync(file, "", { mode: 0o600 });
+		const opener = env.BROWSER?.trim() || findOnPath("xdg-open", env) || findOnPath("open", env) || "";
+		const body = [
+			"#!/usr/bin/env sh",
+			"# Antigravity bridge: records the Google OAuth URL the ACP server hands",
+			"# to the browser, then forwards to the real opener. The bridge watches",
+			"# the record file and shows the URL in pi (copy it when logging in over",
+			"# SSH; forward the redirect port first).",
+			`printf '%s\\n' "$@" >> ${shQuote(file)}`,
+			`REAL=${shQuote(opener)}`,
+			'if [ -n "$REAL" ]; then set -f; exec $REAL "$@"; fi',
+			"",
+		].join("\n");
+		const write = (p: string, content: string, mode: number): void => {
+			try {
+				if (fs.readFileSync(p, "utf8") === content) return;
+			} catch {
+				/* new file */
+			}
+			fs.writeFileSync(p, content, { mode });
+		};
+		write(wrapper, body, 0o755);
+		return { browserEnv: { BROWSER: wrapper }, file, lastUrl: () => readLastUrl(file) };
+	} catch {
+		return null; // capture is best effort; login still works without it
+	}
+}

package/src/acp/connection.ts

@@ -20,8 +20,10 @@
 //     LIST; a dead URL is accepted at session time (lazy connect)
 
 import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { parseAuthPort, readLastUrl } from "./browser-capture.js";
 import { JsonRpcResponseError, JsonRpcSession } from "./jsonrpc.js";
 
 export interface AcpMcpServer {
@@ -63,6 +65,11 @@ export interface AcpConnectionOptions {
 	 *  "auto" selects the first allow option; "deny" fail-closes to the first
 	 *  reject option. Absent = deny (fail closed). */
 	permissions?: () => "auto" | "deny";
+	/** Record file for BROWSER-captured OAuth URLs (src/acp/browser-capture.ts).
+	 *  The server hands the login URL only to the browser-open call, so the
+	 *  wrapper records it there; the connection watches the file and logs
+	 *  "auth-url" {url, port} for every new URL. */
+	authUrlFile?: string;
 }
 
 const INIT_TIMEOUT_MS = 30_000;
@@ -80,6 +87,8 @@ export class AcpConnection {
 	agentInfo: Record<string, unknown> | undefined;
 	/** Last known mode/model config echo from set_config_option results. */
 	lastConfigOptions: unknown = undefined;
+	#authUrlWatcher: fs.FSWatcher | undefined;
+	#lastAuthUrl: string | null = null;
 
 	constructor(opts: AcpConnectionOptions) {
 		this.#opts = opts;
@@ -117,6 +126,7 @@ export class AcpConnection {
 			...(this.#opts.extraEnv ? { env: { ...process.env, ...this.#opts.extraEnv } } : {}),
 		});
 		this.#child = child;
+		if (this.#opts.authUrlFile) this.#watchAuthUrl();
 		child.stdout?.setEncoding("utf8");
 		child.stderr?.setEncoding("utf8");
 		// Pipe failures arrive asynchronously as stream 'error' events; the sync
@@ -373,9 +383,36 @@ export class AcpConnection {
 		}
 	}
 
+	/** Surface OAuth login URLs captured by the BROWSER wrapper: every new
+	 *  URL in the record file is logged once as "auth-url" {url, port}. Best
+	 *  effort only - a broken watch never affects turns. */
+	#watchAuthUrl(): void {
+		const file = this.#opts.authUrlFile!;
+		try {
+			const watcher = fs.watch(file, () => this.#emitAuthUrl());
+			// Without a listener, a watch 'error' event escapes as uncaught.
+			watcher.on("error", () => {
+				/* record file gone: login URL surfacing is off until respawn */
+			});
+			this.#authUrlWatcher = watcher;
+		} catch {
+			/* no watch; the one-shot check below still covers earlier writes */
+		}
+		this.#emitAuthUrl(); // URLs recorded before the watch started
+	}
+
+	#emitAuthUrl(): void {
+		const url = readLastUrl(this.#opts.authUrlFile!);
+		if (!url || url === this.#lastAuthUrl) return;
+		this.#lastAuthUrl = url;
+		this.#opts.log("auth-url", { url, port: parseAuthPort(url) });
+	}
+
 	#finish(reason: string): void {
 		if (this.#exited) return;
 		this.#exited = true;
+		this.#authUrlWatcher?.close();
+		this.#authUrlWatcher = undefined;
 		this.abortAll(`connection exited: ${reason || "process gone"}`);
 		this.#opts.onExit({ code: null, signal: null, stderrTail: this.#stderrTail });
 	}

package/src/acp/driver.ts

@@ -41,6 +41,9 @@ export interface AcpDriverOptions {
 	/** Extra argv for the binary (tests: node + fake-server script). */
 	binArgs?: string[];
 	extraEnv?: Record<string, string>;
+	/** Record file for BROWSER-captured OAuth URLs; passed to the connection,
+	 *  which logs "auth-url" when the server tries to open a login. */
+	authUrlFile?: string;
 	/** Bridge registration for session/new AND session/load. */
 	mcpServers?: () => AcpMcpServer[];
 	log?: (msg: string, data?: unknown) => void;
@@ -422,6 +425,7 @@ export class AcpDriver implements TurnDriver {
 			bin: resolveAcpBinary(typeof this.#opts.bin === "function" ? this.#opts.bin() : this.#opts.bin),
 			binArgs: this.#opts.binArgs,
 			extraEnv: this.#opts.extraEnv,
+			authUrlFile: this.#opts.authUrlFile,
 			cwd: request.cwd,
 			mcpServers: this.#opts.mcpServers,
 			log: (msg, data) => this.#log(msg, data),

package/src/acp/setup.ts

@@ -227,6 +227,18 @@ export interface AuthState {
 	type?: string;
 }
 
+/** Token presence WITHOUT reading any credential value: acp_token.json is
+ *  stat()ed, never opened. The token only exists after the browser login
+ *  round-trip, so this is the real proof of a completed login. */
+function tokenPresent(target: string): boolean {
+	try {
+		fs.statSync(path.join(target, "acp_token.json"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 /** Auth state WITHOUT reading any credential value: settings.json carries
  *  only auth.type (+ non-secret gcp placement), acp_token.json is stat()ed. */
 export function readAuthState(dir?: string): AuthState {
@@ -240,12 +252,7 @@ export function readAuthState(dir?: string): AuthState {
 	} catch {
 		/* absent or garbage = unconfigured */
 	}
-	try {
-		fs.statSync(path.join(target, "acp_token.json"));
-		return { configured: true, type: "token" };
-	} catch {
-		return { configured: false };
-	}
+	return tokenPresent(target) ? { configured: true, type: "token" } : { configured: false };
 }
 
 /** Write a minimal auth block into settings.json. The server reads this file
@@ -344,12 +351,18 @@ export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupS
 			};
 		}
 	}
+	// settings.json alone proves nothing: setup writes it before the login,
+	// the token file only appears after the browser round-trip. oauth-personal
+	// without a token = login still pending, and every caller (switch toast,
+	// session_start self-heal) must keep saying so until the token exists.
+	// gemini-api-key has no browser login; a present token file means done.
+	const needsLogin = auth.type !== "gemini-api-key" && !tokenPresent(gdir);
 	return {
 		ok: true,
 		bin: binary.bin!,
 		binarySource: binary.source!,
 		auth: auth.type ?? "token",
-		needsLogin: false,
+		needsLogin,
 		actions,
 	};
 }

package/src/config.ts

@@ -39,7 +39,7 @@ export interface AcpConfig {
 }
 
 export interface AgyConfig {
-	/** Turn engine. Switching requires a pi restart (drivers wire at load). */
+	/** Engine. Switching requires a pi restart (drivers wire at load). */
 	engine: Engine;
 	/** Official-server ACP engine options (used when engine = "acp"). */
 	acp: AcpConfig;
@@ -54,6 +54,11 @@ export interface AgyConfig {
 	defaultModel: string;
 	/** AskAntigravity tool: default thinking tier when the alias names none. */
 	defaultThinking: ThinkingTier;
+	/** Register the AskAntigravity one-shot delegation tool. Default on.
+	 *  off removes the tool entirely for users who want only the provider
+	 *  and models (no delegation tool in the model's window context).
+	 *  Takes effect at pi start (or /reload). */
+	askTool: boolean;
 	/** Set after the one-time notice about a leftover legacy invokeTool patch
 	 *  on the installed pi. The notice never repeats; /agy patch-cleanup is
 	 *  always available. */
@@ -96,6 +101,7 @@ const DEFAULTS: AgyConfig = {
 	skipPermissions: true,
 	defaultModel: "flash",
 	defaultThinking: "medium",
+	askTool: true,
 	bridgeTools: "all",
 	digest: false,
 	systemPrompt: true,
@@ -149,6 +155,10 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 	const defaultThinking: ThinkingTier =
 		thinkRaw === "low" || thinkRaw === "high" ? thinkRaw : "medium";
 
+	const askTool = process.env.AGY_ASK_TOOL !== undefined
+		? ["1", "true", "on"].includes(process.env.AGY_ASK_TOOL.toLowerCase())
+		: file.askTool ?? DEFAULTS.askTool;
+
 	const bridgeRaw = (process.env.AGY_BRIDGE_TOOLS ?? file.bridgeTools ?? DEFAULTS.bridgeTools).toLowerCase();
 	const bridgeTools: BridgeTools =
 		bridgeRaw === "none" || bridgeRaw === "all" || bridgeRaw === "mcp"
@@ -179,6 +189,7 @@ export function loadConfig(configPath: string = CONFIG_PATH): AgyConfig {
 		skipPermissions,
 		defaultModel,
 		defaultThinking,
+		askTool,
 		bridgeTools,
 		digest,
 		systemPrompt,