@estebanforge/pi-antigravity-bridge 1.4.9 → 1.5.0

package/src/acp/driver.ts

@@ -1,8 +1,8 @@
 // AcpDriver: the ACP turn engine. Implements the same TurnDriver surface as
-// the legacy stream-json driver (see src/driver-types.ts) so provider.ts and
+// the stream-json driver (see src/driver-types.ts) so provider.ts and
 // the G9 round-trip store work unchanged.
 //
-// Engine differences vs legacy, all verified live (docs/ACP-PROTOCOL-REFERENCE.md):
+// Engine differences vs stream-json, all verified live (docs/ACP-PROTOCOL-REFERENCE.md):
 //   - no process recycle on profile drift: one server process, sessions
 //     selected per turn via session/new / session/load
 //   - model/effort via session/set_config_option (configId "model", FULL slug
@@ -19,9 +19,12 @@
 //     in-connection (plan §9.3); no provider involvement
 
 import { randomUUID } from "node:crypto";
+import type { UsageEstimate } from "../config.js";
 import { AcpConnection, resolveAcpBinary, type AcpMcpServer } from "./connection.js";
 import { mapStopReason, mapUpdate, TextAccumulator, type AcpEditDiff } from "./events.js";
+import { estimateTokens, synthesizeUsage } from "./usage-estimate.js";
 import type {
+	AgyUsage,
 	DriverActivity,
 	DriverSnapshot,
 	DriverState,
@@ -46,6 +49,10 @@ export interface AcpDriverOptions {
 	authUrlFile?: string;
 	/** Bridge registration for session/new AND session/load. */
 	mcpServers?: () => AcpMcpServer[];
+	/** Gate B stopgap: how ACP turns synthesize usage while the server sends
+	 *  none. A function is resolved per turn (follows live config, like bin).
+	 *  Default "estimate". */
+	usageEstimate?: UsageEstimate | (() => UsageEstimate);
 	log?: (msg: string, data?: unknown) => void;
 }
 
@@ -59,6 +66,13 @@ interface ActiveTurn {
 	resolve: (o: TurnOutcome) => void;
 	outcome: Promise<TurnOutcome>;
 	response: TextAccumulator;
+	/** Usage-synthesis counters: per-delta token sums (estimate mode) and
+	 *  delta counts (direct mode). Sums are taken per delta, never over the
+	 *  joined text, so a word split across chunks stays two words. */
+	textTokens: number;
+	thoughtTokens: number;
+	textDeltas: number;
+	thoughtDeltas: number;
 	sawResult: boolean;
 	/** True once the prompt RPC was issued. Abort before this point has
 	 *  nothing to cancel: probing would risk a success-as-noop answer from a
@@ -110,7 +124,6 @@ export class AcpDriver implements TurnDriver {
 	#generation = 0;
 	#active: ActiveTurn | undefined;
 	#queueTail: Promise<void> = Promise.resolve();
-	#shutdown = false;
 	#lifecycle: string[] = [];
 	#onTurnEnd: ((outcome: TurnOutcome) => void) | undefined;
 	#stats = {
@@ -168,7 +181,7 @@ export class AcpDriver implements TurnDriver {
 	}
 
 	/** Turns are serialized; a parked turn stays open and the continuation
-	 *  path uses reentry() (same contract as the legacy driver). */
+	 *  path uses reentry() (same contract as the stream-json driver). */
 	run(request: DriverTurnRequest): Promise<TurnHandle> {
 		let release!: () => void;
 		const prev = this.#queueTail;
@@ -190,7 +203,10 @@ export class AcpDriver implements TurnDriver {
 	}
 
 	#runExclusive(request: DriverTurnRequest): Promise<TurnHandle> {
-		if (this.#shutdown) return Promise.reject(new Error("ACP driver is shut down."));
+		// No shutdown latch here: pi fires session_shutdown on /new, /resume and
+		// /fork (not only process exit), so a closed driver must respawn on the
+		// next turn instead of rejecting forever. Regression 2026-09-07:
+		// /compact after a model switch failed with "ACP driver is shut down."
 		if (request.signal?.aborted) return Promise.reject(new Error("aborted before start"));
 
 		const turn = this.#createTurn(request);
@@ -218,7 +234,7 @@ export class AcpDriver implements TurnDriver {
 		}
 
 		// Execute asynchronously: the handle returns as soon as the prompt is
-		// dispatched, and activities stream through next() (legacy contract).
+		// dispatched, and activities stream through next() (stream-json contract).
 		void this.#executeTurn(turn).catch((err: unknown) => {
 			this.#failTurn(turn, `ACP turn failed: ${describe(err)}`);
 		});
@@ -357,10 +373,16 @@ export class AcpDriver implements TurnDriver {
 		switch (mapped.kind) {
 			case "text": {
 				const emit = turn.response.append(mapped.delta);
-				if (emit) this.#emit(turn, { type: "text", delta: emit });
+				if (emit) {
+					turn.textDeltas += 1;
+					turn.textTokens += estimateTokens(emit);
+					this.#emit(turn, { type: "text", delta: emit });
+				}
 				return;
 			}
 			case "thought": {
+				turn.thoughtDeltas += 1;
+				turn.thoughtTokens += estimateTokens(mapped.delta);
 				this.#emit(turn, { type: "thought", delta: mapped.delta });
 				return;
 			}
@@ -541,6 +563,10 @@ export class AcpDriver implements TurnDriver {
 			resolve,
 			outcome,
 			response: new TextAccumulator(),
+			textTokens: 0,
+			thoughtTokens: 0,
+			textDeltas: 0,
+			thoughtDeltas: 0,
 			sawResult: false,
 		promptStarted: false,
 			aborted: false,
@@ -641,6 +667,16 @@ export class AcpDriver implements TurnDriver {
 
 	#settle(turn: ActiveTurn, outcome: TurnOutcome): void {
 		if (turn.closed) return;
+		// Gate B stopgap: synthesize usage on clean turns while the server sends
+		// none. Runs BEFORE close so the usage activity drains through the
+		// normal #nextActivity loop (provider maps it onto partial.usage).
+		if (outcome.status === "OK" && !outcome.aborted && outcome.usage === undefined) {
+			const usage = this.#syntheticUsage(turn);
+			if (usage) {
+				outcome.usage = usage;
+				this.#emit(turn, { type: "usage", usage });
+			}
+		}
 		turn.closed = true;
 		if (turn.overallTimer) clearTimeout(turn.overallTimer);
 		if (turn.idleTimer) clearTimeout(turn.idleTimer);
@@ -669,6 +705,29 @@ export class AcpDriver implements TurnDriver {
 		});
 	}
 
+	/** Usage synthesis mode, resolved per turn (follows live config). */
+	#usageMode(): UsageEstimate {
+		const opt = this.#opts.usageEstimate;
+		return (typeof opt === "function" ? opt() : opt) ?? "estimate";
+	}
+
+	#syntheticUsage(turn: ActiveTurn): AgyUsage | undefined {
+		const mode = this.#usageMode();
+		if (mode === "off") return undefined;
+		// Gate B latch: any server frame with usage/token keys means real
+		// usage exists upstream; estimates must never shadow it.
+		if (this.#conn?.usageSeen) return undefined;
+		return synthesizeUsage({
+			mode,
+			prompt: turn.request.prompt,
+			contextText: turn.request.contextBlock?.text,
+			textTokens: turn.textTokens,
+			thoughtTokens: turn.thoughtTokens,
+			textDeltas: turn.textDeltas,
+			thoughtDeltas: turn.thoughtDeltas,
+		});
+	}
+
 	#log(msg: string, data?: unknown): void {
 		const line = `${new Date().toISOString().slice(11, 19)} ${msg}${data !== undefined ? ` ${JSON.stringify(data)}` : ""}`;
 		this.#lifecycle.push(line);
@@ -679,7 +738,6 @@ export class AcpDriver implements TurnDriver {
 	// --- TurnDriver surface ----------------------------------------------------
 
 	async close(reason: "recycle" | "shutdown", cause?: string): Promise<void> {
-		if (reason === "shutdown") this.#shutdown = true;
 		this.#log(`close:${reason}${cause ? `:${cause}` : ""}`);
 		const turn = this.#active;
 		if (turn && !turn.closed) {
@@ -687,7 +745,7 @@ export class AcpDriver implements TurnDriver {
 				conversationId: turn.sessionId,
 				status: "ERROR",
 				response: turn.response.text,
-				error: `ACP driver ${reason}ed mid-turn${cause ? ` (${cause})` : ""}`,
+				error: `ACP driver ${reason === "recycle" ? "recycled" : "shut down"} mid-turn${cause ? ` (${cause})` : ""}`,
 				finished: true,
 				aborted: false,
 			});

package/src/acp/usage-estimate.ts

@@ -0,0 +1,59 @@
+// Gate B stopgap: synthesize AgyUsage for ACP turns until Google ships a
+// real token-usage layer in agy_acp_server. Counting mechanism copied from
+// the pi-token-speed extension (npm:pi-token-speed, src/engine.ts): a
+// word/punctuation regex, 1 match = 1 token. The numbers are client-side
+// ESTIMATES, never provider data: the connection's usageSeen latch (Gate B
+// watch) keeps synthesis off the day real usage appears in any frame, so
+// estimates can never shadow real numbers.
+
+import type { UsageEstimate } from "../config.js";
+import type { AgyUsage } from "../driver-types.js";
+
+const TOKEN_REGEX = /\w+|[^\s\w]/g;
+
+/** Word-boundary token estimate (pi-token-speed's estimateTokens). */
+export function estimateTokens(text: string): number {
+	if (!text) return 0;
+	const matches = text.match(TOKEN_REGEX);
+	return matches ? matches.length : 0;
+}
+
+export interface UsageEstimateInput {
+	mode: UsageEstimate;
+	/** Full outgoing prompt text (input side; always regex-estimated). */
+	prompt: string;
+	/** ACP embeddedContext resource text (G1 digest): also reaches the model. */
+	contextText?: string;
+	/** Per-delta token sums (mode "estimate"). Summing per delta, like
+	 *  pi-token-speed's recordDelta, avoids word-merge artifacts when a
+	 *  chunk boundary splits a word. */
+	textTokens: number;
+	thoughtTokens: number;
+	/** Streamed delta counts (mode "direct": 1 token per delta). */
+	textDeltas: number;
+	thoughtDeltas: number;
+}
+
+/** Synthesize usage for a finished turn, or undefined when nothing is worth
+ *  reporting (mode off, or a turn with no prompt and no output). */
+export function synthesizeUsage(input: UsageEstimateInput): AgyUsage | undefined {
+	if (input.mode === "off") return undefined;
+	const inputTokens = estimateTokens(
+		input.contextText ? `${input.prompt}\n${input.contextText}` : input.prompt,
+	);
+	const thoughtTokens =
+		input.mode === "direct" ? input.thoughtDeltas : input.thoughtTokens;
+	const textTokens =
+		input.mode === "direct" ? input.textDeltas : input.textTokens;
+	// Thinking folds INTO output (OpenAI convention: reasoning tokens bill as
+	// output). toPiUsage drops thinking_tokens, and thinking time is inside
+	// elapsed wall time, so folding keeps the tokens/time ratio honest.
+	const outputTokens = textTokens + thoughtTokens;
+	if (inputTokens === 0 && outputTokens === 0) return undefined;
+	return {
+		input_tokens: inputTokens,
+		output_tokens: outputTokens,
+		thinking_tokens: thoughtTokens,
+		total_tokens: inputTokens + outputTokens,
+	};
+}

package/src/approval-detect.ts

@@ -0,0 +1,146 @@
+// Third-party pi permission-extension detection for the approval gate
+// (docs/TODO.md 2.5). The gate defaults to "auto": OFF until one of these
+// extensions is present. Detection reads pi's settings (the packages array
+// is the primary, name-exact signal) plus known on-disk config markers for
+// the audited permission packages (sources: ~/tmp/pi-perm-research/, audit
+// 2026-09-07). Best effort by design: a miss only means the user enables
+// the gate manually; a false positive stages hooks.json, which is inert
+// unless the ACP/CLI server loads it, and observation-only hooks are safe.
+//
+// Run: npm test
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** npm names of the audited pi permission packages (docs/TODO.md 2.4). */
+export const KNOWN_GATE_PACKAGES = [
+	"@gotgenes/pi-permission-system",
+	"@zhushanwen/pi-permission",
+	"pi-permission-system",
+	"@xzzpig/pi-permission-system",
+	"@diegopetrucci/pi-permission-gate",
+	"pi-permission-modes",
+	"@inobit/pi-permission",
+	"@thurstonsand/pi-permissions",
+	"@monroewilliams/pi-permission-system",
+	"@rhedbull/pi-permissions",
+] as const;
+
+export interface GateExtensionHit {
+	/** The known package name matched. */
+	name: string;
+	/** How it was detected: "settings:<path>" or "config:<path>". */
+	evidence: string;
+}
+
+function readJsonIfPresent(file: string): { packages?: unknown } | undefined {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function packagesFrom(settingsFile: string): string[] {
+	const parsed = readJsonIfPresent(settingsFile);
+	const raw = parsed?.packages;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((entry): entry is string => typeof entry === "string");
+}
+
+function nameMatchesPackage(entry: string): string | undefined {
+	// entries look like "npm:@scope/name@1.2.3", "git:...", or a bare path.
+	// Boundary-aware match: the known name must start after :/@ (or the
+	// string start) and must not be a prefix of a longer package name
+	// ("pi-permission-system-clone" must NOT match). Version suffix @x.y is
+	// fine. Peer review 2026-09-07 finding 4.
+	const lower = entry.toLowerCase();
+	let best: string | undefined;
+	for (const name of KNOWN_GATE_PACKAGES) {
+		if (containsName(lower, name) && (best === undefined || name.length > best.length)) best = name;
+	}
+	// Longest match wins: "@xzzpig/pi-permission-system" must resolve to the
+	// scoped name, not to the shorter unscoped fork "pi-permission-system".
+	return best;
+}
+
+function containsName(lower: string, name: string): boolean {
+	let idx = lower.indexOf(name);
+	while (idx >= 0) {
+		const before = idx === 0 ? "" : lower[idx - 1];
+		const after = lower[idx + name.length] ?? "";
+		const okBefore = before === "" || ":/@".includes(before);
+		const okAfter = after === "" || after === "@" || !/[a-z0-9_-]/.test(after);
+		if (okBefore && okAfter) return true;
+		idx = lower.indexOf(name, idx + 1);
+	}
+	return false;
+}
+
+/**
+ * Detect installed third-party permission extensions.
+ *
+ * @param opts.home  HOME override for tests.
+ * @param opts.cwd   project dir override for tests (project settings).
+ * @param opts.settingsFiles  extra settings files to scan (tests).
+ */
+export function detectPermissionGateExtensions(
+	opts: { home?: string; cwd?: string; settingsFiles?: string[] } = {},
+): GateExtensionHit[] {
+	const home = opts.home ?? os.homedir();
+	const cwd = opts.cwd ?? process.cwd();
+	const hits: GateExtensionHit[] = [];
+	const seen = new Set<string>();
+
+	const settingsCandidates = [
+		...(opts.settingsFiles ?? []),
+		path.join(home, ".pi", "agent", "settings.json"),
+		path.join(cwd, ".pi", "settings.json"),
+	];
+	for (const file of settingsCandidates) {
+		for (const entry of packagesFrom(file)) {
+			const name = nameMatchesPackage(entry);
+			if (name && !seen.has(name)) {
+				seen.add(name);
+				hits.push({ name, evidence: `settings:${file}` });
+			}
+		}
+	}
+
+	// Known config-file markers from the audit. Presence of the config does
+	// not prove the extension is installed, but every audited package writes
+	// its config only after install + first run, which is evidence enough for
+	// an opt-in default.
+	const markers: Array<{ file: string; name: string }> = [
+		{ file: path.join(home, ".pi", "agent", "extensions", "pi-permission-system"), name: "@gotgenes/pi-permission-system" },
+		{ file: path.join(home, ".agent", "pi-permissions.jsonc"), name: "@monroewilliams/pi-permission-system" },
+		{ file: path.join(home, ".pi", "agent", "extensions", "permissions.json"), name: "@rhedbull/pi-permissions" },
+		{ file: path.join(cwd, ".pi", "agent", "pi-permissions.jsonc"), name: "@gotgenes/pi-permission-system" },
+	];
+	for (const marker of markers) {
+		if (!seen.has(marker.name)) {
+			try {
+				fs.statSync(marker.file);
+				seen.add(marker.name);
+				hits.push({ name: marker.name, evidence: `config:${marker.file}` });
+			} catch {
+				/* absent - fine */
+			}
+		}
+	}
+
+	return hits;
+}
+
+/** Resolve the effective gate shape from config + detection. "auto" defers
+ *  to detection (shadow when any gate extension is present, else off). */
+export function resolveGateMode(
+	gateMode: "auto" | "shadow" | "dedicated" | "off",
+	hits: GateExtensionHit[],
+): "shadow" | "dedicated" | "off" {
+	if (gateMode === "off") return "off";
+	if (gateMode === "shadow" || gateMode === "dedicated") return gateMode;
+	return hits.length > 0 ? "shadow" : "off";
+}

package/src/approval-gate.ts

@@ -0,0 +1,208 @@
+// Approval-gate shadow tools (docs/TODO.md section 2.5, design v2).
+//
+// When the approval gate is active, the bridge re-registers pi's mutating
+// builtins (bash, write, edit) as SHADOW tools: same name, same schema plus
+// internal __agy* marker fields. Two behaviors, keyed on the marker:
+//
+//   - marker absent: delegate to the captured real builtin. Normal pi
+//     behavior (including the G9 path, where pi tools execute for real) is
+//     untouched.
+//   - marker present: the call is an approval round-trip for an agy NATIVE
+//     tool. NEVER execute locally. Ask the policy for a decision; agy runs
+//     the tool in its own loop either way.
+//
+// Decision mapping (consumed by the provider's /approval park):
+//   resolve (success result)      -> {"decision":"allow"}
+//   throw                         -> {"decision":"deny","reason": message}
+// pi's tool executor converts thrown errors into error tool results with
+// the message as text, matching how builtins report failures (write.js,
+// edit-diff.js). A tool_call handler that blocks the shadow call upstream
+// (any third-party permission extension) produces the same error result
+// without execute() running, so both paths land on the same deny mapping.
+//
+// Run: npm test
+
+import type {
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ExtensionContext,
+	ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+
+/** Marker flag: this shadow-tool call is an approval round-trip, not a real
+ *  invocation. The bridge's provider sets it when composing the toolUse. */
+export const GATE_MARKER = "__agyGate";
+
+/** Internal context fields the provider may attach next to the marker.
+ *  Stripped before delegating to the real builtin. */
+export const MARKER_FIELDS = [GATE_MARKER, "__agyTicket", "__agyTool"] as const;
+
+export type AnyToolDefinition = ToolDefinition<any, any, any>;
+
+export interface GateDecision {
+	allow: boolean;
+	reason?: string;
+}
+
+/** Fallback policy: consulted only when NO extension blocked the shadow
+ *  tool_call. Implementations map approvals.mode: ask -> ctx.ui.confirm
+ *  (guarded by ctx.hasUI), allow -> {allow:true}, deny -> {allow:false}. */
+export type GatePolicy = (call: {
+	tool: string;
+	params: Record<string, unknown>;
+	ctx: unknown;
+}) => Promise<GateDecision> | GateDecision;
+
+/** Marker schemas injected into the shadow parameters. Optional, so the
+ *  model's own calls stay valid; audited permission extensions match only
+ *  their known fields (command/path) and ignore these. */
+const MARKER_SCHEMAS: Record<string, unknown> = {
+	[GATE_MARKER]: {
+		type: "boolean",
+		description:
+			"Internal bridge approval marker. Never set this yourself; calls without local execution intent must not set it.",
+	},
+	__agyTicket: { type: "string" },
+	__agyTool: { type: "string", description: "Native agy tool this approval round-trip is for." },
+};
+
+/** Clone a tool's parameter schema with the marker fields added as optional
+ *  properties. Field-exact for everything the permission extensions match on
+ *  (command, path, edits, ...). Does not mutate the base schema. */
+export function withGateMarkerSchema(base: AnyToolDefinition["parameters"]): AnyToolDefinition["parameters"] {
+	const src = base as { properties?: Record<string, unknown> };
+	return { ...base, properties: { ...src.properties, ...MARKER_SCHEMAS } } as AnyToolDefinition["parameters"];
+}
+
+/** Copy of params without the internal marker fields, for delegation. */
+export function stripMarkerFields(params: Record<string, unknown>): Record<string, unknown> {
+	const out = { ...params };
+	for (const field of MARKER_FIELDS) delete out[field];
+	return out;
+}
+
+export interface ShadowMapping {
+	shadow: "bash" | "write" | "edit";
+	input: Record<string, unknown>;
+}
+
+/** Map an agy native tool call (hook stdin payload) onto the shadow surface.
+ *  Field names follow the TODO 2.5 table: create_file is live-captured (F1);
+ *  the edit-class arg names are docs-attested and degrade gracefully - a
+ *  wrong guess only weakens the confirm-dialog text, never the decision
+ *  (the tool runs in agy's loop either way). Unknown names return null:
+ *  read-only tools are not gated. */
+export function mapNativeToShadow(name: string, args: Record<string, unknown>): ShadowMapping | null {
+	const a = args ?? {};
+	const str = (v: unknown): string => (typeof v === "string" ? v : v === undefined || v === null ? "" : String(v));
+	switch (name) {
+		case "run_command": {
+			const input: Record<string, unknown> = { command: str(a.CommandLine) };
+			if (a.Cwd !== undefined && a.Cwd !== null && a.Cwd !== "") input.cwd = str(a.Cwd);
+			return { shadow: "bash", input };
+		}
+		case "write_to_file":
+		case "create_file":
+			return { shadow: "write", input: { path: str(a.TargetFile), content: str(a.CodeContent) } };
+		case "replace_file_content":
+		case "edit_file":
+			return {
+				shadow: "edit",
+				input: {
+					path: str(a.TargetFile),
+					edits: [{ oldText: str(a.SearchText), newText: str(a.ReplacementContent) }],
+				},
+			};
+		case "multi_replace_file_content": {
+			const chunks = Array.isArray(a.ReplacementChunks) ? a.ReplacementChunks : [];
+			return {
+				shadow: "edit",
+				input: {
+					path: str(a.TargetFile),
+					edits: chunks.map((c) => {
+						const chunk = (c ?? {}) as Record<string, unknown>;
+						return { oldText: str(chunk.SearchText), newText: str(chunk.ReplacementContent) };
+					}),
+				},
+			};
+		}
+		default:
+			return null;
+	}
+}
+
+/** Options for the shadow factory. */
+export interface ShadowOptions {
+	/** Registry lookup for the park's ticket. When set, a marker call whose
+	 *  __agyTicket is missing or unrecognized throws (deny) BEFORE the policy
+	 *  runs: a model that sets __agyGate:true itself can then never produce a
+	 *  fake-approved result, even under approvals.mode "allow". */
+	verifyTicket?: (ticket: string) => boolean;
+}
+
+/** Build the shadow definition for one builtin. `base` MUST be a definition
+ *  of the real builtin - the extension passes factory twins created with
+ *  pi's public createBashToolDefinition/createWriteToolDefinition/
+ *  createEditToolDefinition (pi.getAllTools() returns ToolInfo, which strips
+ *  execute, so the live definition cannot be captured). */
+export function createShadowTool(base: AnyToolDefinition, policy: GatePolicy, opts: ShadowOptions = {}): AnyToolDefinition {
+	const execute = async (
+		toolCallId: string,
+		params: any,
+		signal: AbortSignal | undefined,
+		onUpdate: AgentToolUpdateCallback<any> | undefined,
+		ctx: ExtensionContext,
+	): Promise<AgentToolResult<unknown>> => {
+		const p = (params ?? {}) as Record<string, unknown>;
+		if (p[GATE_MARKER] !== true) {
+			return base.execute(toolCallId, stripMarkerFields(p), signal, onUpdate, ctx);
+		}
+		const native = typeof p.__agyTool === "string" && p.__agyTool.length > 0 ? p.__agyTool : base.name;
+		// Ticket binding (peer review 2026-09-07): only calls the provider parked
+		// carry a live ticket. Anything else with the marker set was forged by
+		// the model (or the park is gone); fail closed without consulting the
+		// policy, so approvals.mode "allow" can never bless it either.
+		const ticket = typeof p.__agyTicket === "string" ? p.__agyTicket : "";
+		if (!ticket || !opts.verifyTicket?.(ticket)) {
+			throw new Error(
+				`approval gate: unrecognized or stale approval ticket; refusing to decide (${native}).`,
+			);
+		}
+		if (signal?.aborted) {
+			throw new Error(`approval gate aborted before a decision was reached (${native}).`);
+		}
+		let decision: GateDecision;
+		// Race the policy against the abort signal: a cancelled turn must
+		// unblock execute() instead of hanging on a human decision.
+		const aborted = new Error(`approval gate aborted before a decision was reached (${native}).`);
+		const abortp = new Promise<never>((_, reject) => {
+			signal?.addEventListener("abort", () => reject(aborted), { once: true });
+		});
+		abortp.catch(() => {}); // late rejection must not become unhandled
+		try {
+			decision = await Promise.race([Promise.resolve(policy({ tool: native, params: p, ctx })), abortp]);
+		} catch (err) {
+			if (signal?.aborted) throw aborted;
+			// Fail closed: a broken policy must never look like an approval.
+			throw new Error(`approval gate policy failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		if (signal?.aborted) {
+			// Sync-abort inside the policy settles the policy promise BEFORE the
+			// race starts, so the rejection loses the ordering tie. Re-check.
+			throw aborted;
+		}
+		if (!decision.allow) {
+			throw new Error(decision.reason || `blocked by approval gate (${native}).`);
+		}
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Approved by approval gate: ${native}. No local execution happened; the tool runs in the Antigravity agent loop.`,
+				},
+			],
+			details: { gate: "allow", native },
+		};
+	};
+	return { ...base, parameters: withGateMarkerSchema(base.parameters), execute } as AnyToolDefinition;
+}