@estebanforge/pi-antigravity-bridge 1.4.4 → 1.4.6

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.4.6] - 2026-09-04
+
+### Added
+
+- Tool-priority note in the system prompt block (`systemPrompt` setting, on by default): agy runs embedded in pi, so its native interactive tools (the live example was `ask_question` vs the bridge's `ask_user_question`) never reach the user. The note tells agy to always prefer the Pi Bridge tool when one covers the same purpose. The old preamble sentence that allowed "your own tools or the pi tool bridge" is gone, since that ambiguity was the cause.
+
+### Fixed
+
+- `/agy auth` reports a distinct failure instead of a false "Signed in." when the server accepts the sign-in but `acp_token.json` never appears within the 5 s post-authenticate grace window (peer-review find; the poll result was never read).
+- Test-infra: the fake ACP server's request log was lost on SIGTERM (buffered write stream + Gate D teardown), which flaked the Gate D abort test ~1-in-3 suite runs; the log now appends synchronously.
+
+### Changed
+
+- The sign-in URL toast fences the URL with blank lines so it stays readable and copyable next to the ssh port-forward hint.
+
+## [1.4.5] - 2026-09-04
+
+### Added
+
+- Tool-priority note in the system prompt block (`systemPrompt` setting, on by default): agy runs embedded in pi, so its native interactive tools (the live example was `ask_question` vs the bridge's `ask_user_question`) never reach the user. The note tells agy to always prefer the Pi Bridge tool when one covers the same purpose. The old preamble sentence that allowed "your own tools or the pi tool bridge" is gone, since that ambiguity was the cause.
+
+- `/agy auth` subcommand: runs the antigravity-acp sign-in on demand (spawns the server, sends `authenticate`, waits for the browser round-trip to complete; minutes-scale). Signing in no longer rides the first Antigravity message, and both login-pending moments now point at `/agy auth`. The sign-in URL toast (and its ssh port-forward hint) fires during `/agy auth` exactly as it does during turns, and a second concurrent `/agy auth` fails fast instead of racing the token write.
+
+### Changed
+
+- `/agy acp-auth` renamed to `/agy auth-manual` (no alias): it prints the manual credential setup for those who want it. Auth-error remediation, MANUAL_SETUP, README, and docs now point at `/agy auth` / `/agy auth-manual`, and the stale first-message login wording is gone from the manual steps.
+
 ## [1.4.4] - 2026-09-04
 
 ### Added

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`). 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.
+Switch with `/agy engine acp|stream-json` (takes effect on restart). Setup is automatic: switching to `acp` installs Google's official ACP server binary from the [antigravity-acp registry entry](https://github.com/agentclientprotocol/registry) (`~/.local/opt/agy-acp/<build>/` + a `current` symlink, zip sha256 recorded; layout and pinning in [docs/ACP-ADOPTION-PLAN.md](docs/ACP-ADOPTION-PLAN.md)) and prepares the login. The login is your Antigravity subscription: the same account and plan you use for the Antigravity CLI (`agy`). Sign in explicitly with `/agy auth` (engine `acp` selected): it opens the Google login in your browser and completes when you finish it. If no browser is available (an SSH session on a remote machine), pi shows the sign-in URL to copy, plus the ssh port-forward command for the login redirect. It is no different from logging into the CLI; the server just keeps its own token file on your machine, like any Google tool, and this extension never sees your credentials. If you also export `GEMINI_API_KEY`, it is ignored: the server uses the auth type in settings.json, and setup always writes `oauth-personal`. A session start self-heals the same way, silently when everything is ready. Manual instructions (`/agy auth-manual`) surface only when a step fails. Sessions are engine-scoped, so switching engines never crosses conversations.
 
 ## What it cannot do
 
@@ -107,7 +107,7 @@ If `agy models` fails at load (binary missing, auth not done, network stall), a
 | `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` |
+| `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` |
 
 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.
 
@@ -121,6 +121,7 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /agy                      status, or open the full settings picker (TUI)
 /agy status               print current settings + session counts
 /agy doctor               bridge state, driver counters, bridge port, last lifecycle events
+/agy auth                 run the antigravity-acp sign-in now (engine acp): opens the Google login in your browser, shows the URL when no browser opens
 /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)
@@ -128,11 +129,11 @@ The `activate_skill` catalog mirrors pi's directory-based skill discovery: the t
 /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 system-prompt on|off send pi's system prompt + AGENTS.md + the Pi Bridge tool-priority note to new agy conversations (default on)
 /agy bridge all|mcp|none  which pi tools the MCP bridge exposes to agy (default all; none = bridge off)
 /agy acp-bin <path|auto>  point the ACP engine at a specific server binary (auto = setup installs, or AGY_ACP_BIN; applies on the next ACP turn)
 /agy engine acp|stream-json   switch the turn engine (restart to apply; default stream-json; acp runs self-service setup: binary install + auth bootstrap)
-/agy acp-auth                 manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
+/agy auth-manual             manual ACP credential setup (fallback; auto-setup normally covers this; default login = your Antigravity subscription, same account as the agy CLI)
 /agy patch-cleanup        restore the original pi files if an older version patched them
 /agy clear                drop all session bindings (force fresh conversations)
 ```

package/docs/ACP-ADOPTION-PLAN.md

@@ -325,7 +325,7 @@ Tested with the parity suite (section 11) and `scripts/parity-live.mjs`
 | Human decision latency on parked G9 tool round-trips exceeds the 10m overall-turn cap | Turn killed mid-wait | `AcpDriver` pauses the overall timer while parked, re-armed with REMAINING budget; every park carries its own timeout (9.3) |
 | Binary size (1.5 GB + 117 MB) | Disk + update churn | Pinned install layout (section 12), registry pin by build id |
 | aarch64 TCMalloc startup failure (forum report, Chromebook) | arch-specific | x86_64 unaffected; gate install per-arch, link the forum issue in README |
-| Separate auth state from `agy` CLI | First-run auth friction | `/agy acp-auth` prints exact instructions; `gemini-api-key` path works headless via `GEMINI_API_KEY`. The agent never writes credentials |
+| Separate auth state from `agy` CLI | First-run auth friction | `/agy auth-manual` prints exact instructions; `gemini-api-key` path works headless via `GEMINI_API_KEY`. The agent never writes credentials |
 | Thought text changes rendering volume | Noisy transcript | Route through the existing thinking block pipeline, close-on-switch unchanged; no new block types |
 | Two engines drift on behavior | Confusing support surface | Shared provider layer + shared parity suite run against both engines in CI |
 
@@ -827,7 +827,7 @@ Install layout:
   request (issue) once we depend on this.
 - `--uid=` from the linux registry entry: the server ran without it here.
   Treat as a launcher artifact; revisit if a future build refuses to start.
-- Auth onboarding: `/agy acp-auth` prints the four methods with exact
+- Auth onboarding: `/agy auth-manual` prints the four methods with exact
   `settings.json` shapes (source: official Zed docs, section 2.3). Headless
   path: `GEMINI_API_KEY` + `auth.type: "gemini-api-key"`. The agent NEVER
   writes or reads credentials; it prints instructions and verifies by

package/docs/DEVELOPMENT.md

@@ -37,7 +37,7 @@ AGY_LIVE=1 node --experimental-strip-types scripts/smoke-stream-json.mjs
 
 # Live smoke for the ACP engine through OUR driver stack. OPT-IN: spends a
 # little quota. Needs AGY_ACP_BIN (or acp on PATH) and a one-time
-# /agy acp-auth credential setup.
+# /agy auth-manual credential setup.
 AGY_ACP_LIVE=1 AGY_ACP_BIN=~/.local/opt/agy-acp/current/agy_acp_server.par \
   npx tsx scripts/smoke-acp.mjs
 

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 { runAcpAuth } from "../src/acp/auth.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";
@@ -135,24 +136,36 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		"unsupported-server-request",
 	]);
 	const legacyDriver = new AgyDriver();
+	// Shared ACP log sink (driver turns AND /agy auth): the login URL event
+	// toasts so SSH users can copy it; genuine failures reach stderr.
+	const acpLog = (msg: string, data?: unknown): void => {
+		if (msg === "auth-url") {
+			const { url, port } = (data ?? {}) as { url?: string; port?: number | null };
+			if (!url) return;
+			// Blank lines fence the URL off from the rest of the text: it is long
+			// and wraps, so separation keeps it readable and copyable.
+			const parts = ["Google sign-in URL for the ACP engine:", "", url];
+			if (port) {
+				parts.push(
+					"",
+					"SSH session? Forward the port on your machine first:",
+					`  ssh -N -L ${port}:127.0.0.1:${port} <user@host>`,
+				);
+			}
+			const text = parts.join("\n");
+			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) : ""}`);
+	};
 	const acpDriver = new AcpDriver({
 		// 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) : ""}`);
-		},
+		log: acpLog,
 		mcpServers: () => {
 			const handle = mcpHandle;
 			if (!handle) return [];
@@ -232,6 +245,8 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		acpDriver,
 		engine,
 		getMcpPort: () => mcpHandle?.port ?? null,
+		acpLog,
+		authCapture: authCapture ?? null,
 	});
 
 	// AskAntigravity tool: one-shot delegation to agy (ported from
@@ -299,7 +314,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 						saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
 					}
 					if (status.needsLogin) {
-						const msg = acpLoginPending("Your next Antigravity message opens the Google sign-in page in your browser.");
+						const msg = acpLoginPending();
 						if (ctx.hasUI) ctx.ui.notify(msg, "warning");
 						else console.error(`[antigravity-bridge] ${msg}`);
 					}
@@ -416,11 +431,11 @@ 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.`;
+ *  /agy engine acp). End-user simple: what to run, what happens, which
+ *  account. Sign-in is explicit (/agy auth); it never rides the first
+ *  message. */
+function acpLoginPending(): string {
+	return `One-time sign-in needed to finish ACP setup. Run /agy auth: the Google sign-in opens in your browser. 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 {
@@ -432,6 +447,11 @@ interface AgyCommandCtx {
 	/** Engine latched at extension load (see the provider wiring note). */
 	engine: Engine;
 	getMcpPort: () => number | null;
+	/** Shared ACP log sink (login URL surfacing + failure events). */
+	acpLog: (msg: string, data?: unknown) => void;
+	/** BROWSER-capture handles; null when unavailable (Windows, unwritable
+	 *  data dir). /agy auth passes them to the sign-in process. */
+	authCapture: { browserEnv: Record<string, string>; file: string } | null;
 }
 
 interface PendingConfig {
@@ -467,7 +487,7 @@ function statusText(ctx: AgyCommandCtx): string {
 		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 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",
+		"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",
 	].join("\n");
 }
 
@@ -475,7 +495,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|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]",
+			"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|acp-bin <path|auto>|patch-cleanup|clear]",
 		handler: async (args, cmdCtx: ExtensionCommandContext) => {
 			const ui = cmdCtx.ui;
 			if (ui) activeUi = ui;
@@ -535,7 +555,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 					saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
 					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.")}`,
+							`ACP engine set. ${acpLoginPending()}`,
 							"warning",
 						);
 					} else {
@@ -546,6 +566,42 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				}
 				return;
 			}
+			if (sub === "auth") {
+				// Gate on the CONFIGURED engine (disk + env), not the latched one:
+				// /agy engine acp followed by /agy auth in the same session works,
+				// no restart needed before signing in.
+				if (loadConfig().engine !== "acp") {
+					ui?.notify(`the selected engine is ${loadConfig().engine}. /agy engine acp first, then /agy auth.`, "warning");
+					return;
+				}
+				ui?.notify("Preparing the ACP server (binary + auth settings)…", "info");
+				const status = await ensureAcpReady({ configBin: loadConfig().acp.bin, onProgress: (m) => ui?.notify(m, "info") });
+				if (!status.ok) {
+					ui?.notify(`ACP auto-setup failed (${status.error}).\n${status.manual}`, "warning");
+					return;
+				}
+				saveConfig({ acp: { bin: status.bin, permissions: loadConfig().acp.permissions } });
+				if (!status.needsLogin) {
+					ui?.notify(`Already signed in (auth: ${status.auth}). Nothing to do.`, "info");
+					return;
+				}
+				ui?.notify(
+					"Signing in: the Google sign-in opens in your browser and completes when you finish it (minutes-scale). If no browser opens, pi shows the sign-in URL to copy.",
+					"info",
+				);
+				const r = await runAcpAuth({
+					bin: status.bin,
+					extraEnv: ctx.authCapture?.browserEnv,
+					authUrlFile: ctx.authCapture?.file,
+					log: ctx.acpLog,
+				});
+				if (r.ok) {
+					ui?.notify("Signed in. The ACP engine is ready; takes effect on the next pi start (or /reload).", "info");
+				} else {
+					ui?.notify(`ACP sign-in failed (${r.error}).\nRun /agy auth to retry; /agy auth-manual has manual steps.`, "warning");
+				}
+				return;
+			}
 			if (sub === "acp-bin") {
 				const rest = (args ?? "").trim().split(/\s+/).slice(1).join(" ");
 				if (rest.length > 0) {
@@ -564,7 +620,7 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 				}
 				return;
 			}
-			if (sub === "acp-auth") {
+			if (sub === "auth-manual") {
 				ui?.notify(
 					[
 						"ACP engine authentication (one-time; usually automatic -",
@@ -580,16 +636,16 @@ function registerAgyCommand(pi: ExtensionAPI, ctx: AgyCommandCtx): void {
 						"1. Server binary: auto-setup installs it. Manual: agy_acp_server.par from",
 						"   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. 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.",
+						"   ~/.gemini/antigravity-acp/settings.json, run /agy auth, and complete",
+						"   the 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,",
 						"   an exported key is ignored.",
-						"3. Run one turn; /agy doctor shows the server version when auth is OK.",
+						"3. /agy doctor shows the server version when auth is OK.",
 					].join("\n"),
 					"info",
 				);

package/package.json

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

@@ -0,0 +1,81 @@
+import { AcpConnection } from "./connection.js";
+import { hasAcpToken } from "./setup.js";
+
+// Explicit sign-in (/agy auth): spawn a short-lived server, send
+// `authenticate` (the RPC that fires the loopback listener + browser OAuth
+// flow), and wait for the token to land in the shared acp_token.json. A
+// dedicated process keeps the minutes-scale login ritual away from live
+// turns; the next driver connection picks the token up. The real server
+// blocks until the browser round-trip completes; the observed window is
+// minutes-scale (one flow timed out at ~8.5 minutes), so the timeout is
+// generous.
+
+export const AUTH_TIMEOUT_MS = 10 * 60_000;
+
+export interface AcpAuthOptions {
+	bin: string;
+	binArgs?: string[];
+	cwd?: string;
+	extraEnv?: Record<string, string>;
+	authUrlFile?: string;
+	/** Directory holding acp_token.json. Default: ~/.gemini/antigravity-acp.
+	 *  Tests point this at a fixture dir; production callers use the default. */
+	tokenDir?: string;
+	/** The server is expected to have written acp_token.json by the time
+	 *  authenticate replies, but write-after-reply is unverified; after a
+	 *  successful reply the run polls for the token up to this long before
+	 *  SIGTERM, so a laggard write is never killed mid-flight. A token that
+	 *  never appears is a distinct failure, not silent success. */
+	tokenGraceMs?: number;
+	timeoutMs?: number;
+	log?: (msg: string, data?: unknown) => void;
+}
+
+export interface AcpAuthResult {
+	ok: boolean;
+	/** Failure reason (spawn, timeout, -32000 family, concurrent run). Absent when ok. */
+	error?: string;
+}
+
+let authInFlight: Promise<AcpAuthResult> | null = null;
+
+export function runAcpAuth(opts: AcpAuthOptions): Promise<AcpAuthResult> {
+	const conn = new AcpConnection({
+		bin: opts.bin,
+		binArgs: opts.binArgs,
+		cwd: opts.cwd ?? process.cwd(),
+		extraEnv: opts.extraEnv,
+		authUrlFile: opts.authUrlFile,
+		log: opts.log ?? (() => {}),
+		onUpdate: () => {},
+		onExit: () => {},
+	});
+	const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+	const grace = opts.tokenGraceMs ?? 5_000;
+	const run = async (): Promise<AcpAuthResult> => {
+		try {
+			await conn.start();
+			await conn.request("authenticate", { methodId: "oauth-personal" }, opts.timeoutMs ?? AUTH_TIMEOUT_MS);
+			const deadline = Date.now() + grace;
+			while (!hasAcpToken(opts.tokenDir) && Date.now() < deadline) await sleep(200);
+			if (!hasAcpToken(opts.tokenDir)) {
+				return {
+					ok: false,
+					error: `the server accepted the sign-in, but no token file appeared in ${opts.tokenDir ?? "~/.gemini/antigravity-acp"} within ${Math.round(grace / 1000)}s`,
+				};
+			}
+			return { ok: true };
+		} catch (err) {
+			return { ok: false, error: err instanceof Error ? err.message : String(err) };
+		} finally {
+			conn.kill();
+		}
+	};
+	// One sign-in at a time: two concurrent runs would race the OAuth loopback
+	// and the token write. A second invocation fails fast instead.
+	if (authInFlight) return Promise.resolve({ ok: false, error: "a sign-in is already running; wait for it to finish" });
+	authInFlight = run();
+	return authInFlight.finally(() => {
+		authInFlight = null;
+	});
+}

package/src/acp/connection.ts

@@ -38,7 +38,7 @@ export interface AcpSessionInfo {
 }
 
 /** Auth failed (-32000 family). Message carries the remediation the server
- *  provided plus the /agy acp-auth pointer. */
+ *  provided plus the /agy auth-manual pointer. */
 export class AcpAuthError extends Error {
 	constructor(message: string) {
 		super(message);
@@ -424,7 +424,7 @@ export function translateError(method: string, err: unknown): Error {
 		if (err.code === -32000) {
 			const detail = typeof err.data === "object" && err.data !== null ? (err.data as { message?: unknown }).message : undefined;
 			const detailText = typeof detail === "string" ? `: ${detail}` : `: ${err.message}`;
-			return new AcpAuthError(`ACP authentication required for ${method}${detailText}. Run /agy acp-auth for setup instructions.`);
+			return new AcpAuthError(`ACP authentication required for ${method}${detailText}. Run /agy auth to sign in; /agy auth-manual has manual steps.`);
 		}
 		// Typed protocol errors survive: callers probe .code (-32601 cancel-
 		// unsupported, -32602 param shape). The method prefix is lost — describe()

package/src/acp/setup.ts

@@ -48,8 +48,8 @@ export type AcpSetupStatus =
 			bin: string;
 			binarySource: "env" | "config" | "installed" | "existing";
 			auth: string;
-			/** True when auth was just set to oauth-personal: the server opens
-			 *  Google login in the browser on the first ACP message. */
+			/** True when auth was just set to oauth-personal: /agy auth opens
+			 *  the Google login in the browser. */
 			needsLogin: boolean;
 			/** Human-readable actions taken (empty when everything was ready). */
 			actions: string[];
@@ -70,10 +70,10 @@ export const MANUAL_SETUP = [
 	"   (~/.local/opt/agy-acp/current/agy_acp_server.par works; 'current' is a",
 	"   symlink to the build dir).",
 	'3. Log in: put {"auth":{"type":"oauth-personal"}} in',
-	"   ~/.gemini/antigravity-acp/settings.json and complete the Google login that",
-	"   opens in your browser on your first ACP message. That login IS your",
+	"   ~/.gemini/antigravity-acp/settings.json and run /agy auth, then complete",
+	"   the Google login that opens in your browser. That login IS your",
 	"   Antigravity subscription (Google AI Plus/Pro/Ultra).",
-	"Details: /agy acp-auth",
+	"Details: /agy auth-manual",
 ].join("\n");
 
 export function platformKey(): string {
@@ -239,6 +239,11 @@ function tokenPresent(target: string): boolean {
 	}
 }
 
+/** Whether a login token exists (default dir, or an explicit one). */
+export function hasAcpToken(dir?: string): boolean {
+	return tokenPresent(dir ?? path.join(os.homedir(), ".gemini", "antigravity-acp"));
+}
+
 /** 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 {
@@ -334,7 +339,7 @@ export async function ensureAcpReady(opts: SetupOptions = {}): Promise<AcpSetupS
 	// before the first spawn, so a fresh write takes effect. oauth-personal is
 	// THE default: it is the Antigravity subscription (same Google account and
 	// plan as the agy CLI login). gemini-api-key (metered paid API) stays a
-	// manual option for headless boxes (/agy acp-auth); never the default.
+	// manual option for headless boxes (/agy auth-manual); never the default.
 	const gdir = defaultGeminiDir(opts);
 	const auth = readAuthState(gdir);
 	if (!auth.configured) {

package/src/provider.ts

@@ -108,10 +108,19 @@ const DIGEST_PREAMBLE =
 // afterwards, and agy's server-side prompt cache keeps hitting.
 
 export const SYSTEM_PROMPT_PREAMBLE =
-	"[The following is the system prompt of the pi session that spawned this conversation: operating instructions plus project context (AGENTS.md files). Apply it for this whole conversation. Tool guidance may reference pi-side tools; use your own tools or the pi tool bridge for those actions.]";
+	"[The following is the system prompt of the pi session that spawned this conversation: operating instructions plus project context (AGENTS.md files). Apply it for this whole conversation.]";
 
 export const SYSTEM_PROMPT_END = "[END SYSTEM PROMPT]";
 
+/** Brief tool-priority note appended inside every system prompt block: agy
+ *  runs embedded in pi, so its native interactive tools never reach the
+ *  user. Equivalent Pi Bridge tools must win. Concrete clash observed live:
+ *  agy picked its native ask_question over the bridge's ask_user_question
+ *  and the question never displayed. Rides the systemPrompt gate: the note
+ *  ships only when the system prompt ships. */
+export const TOOL_PRIORITY_NOTE =
+	"[Tool priority: this conversation runs inside pi, not as a standalone agy session; the user only sees what surfaces in pi. Native interactive tools, for example ask_question, never reach the user. When a Pi Bridge tool covers the same purpose, always use the Pi Bridge tool; for user questions use ask_user_question.]";
+
 /** Assemble the full agy prompt: system prompt block, pi-side digest, user
  *  prompt. Empty parts are dropped. Pure; exported for unit testing.
  *  Pass systemPrompt only on a fresh conversation (see runTurnDriver). */
@@ -122,7 +131,7 @@ export function buildFullPrompt(
 ): string {
 	const parts: string[] = [];
 	if (systemPrompt) {
-		parts.push(`${SYSTEM_PROMPT_PREAMBLE}\n\n${systemPrompt}\n\n${SYSTEM_PROMPT_END}`);
+		parts.push(`${SYSTEM_PROMPT_PREAMBLE}\n\n${systemPrompt}\n\n${TOOL_PRIORITY_NOTE}\n\n${SYSTEM_PROMPT_END}`);
 	}
 	if (digest) {
 		parts.push(`${DIGEST_PREAMBLE}\n\n${digest}`);