@estebanforge/pi-antigravity-bridge 1.8.7 → 1.9.0

package/src/driver-types.ts

@@ -32,7 +32,8 @@ export interface DriverTurnRequest extends DriverProfile {
 	prompt: string;
 	/** Image blocks riding with the prompt. ACP forwards them as typed
 	 *  content blocks (probe 2026-09-03: 64x64 two-tone PNG answered
-	 *  correctly); the stream-json CLI prompt is text-only and ignores them. */
+	 *  correctly); on stream-json the provider stages them to files, so the
+	 *  driver itself ignores this field. */
 	images?: Array<{ data: string; mimeType: string }>;
 	/** ACP only: pi-side context delivered as a native `embeddedContext`
 	 *  resource block instead of inline prompt text (G1 on ACP). Stream-json

package/src/driver.ts

@@ -21,7 +21,9 @@ import { isKnownNoiseLine, MAX_FRAME_BYTES, stripGluedNoise } from "./frame-guar
 import { bridgeMcpConfigDir, bridgeMcpConfigExists } from "./mcp-server.js";
 import { gateHooksStaged } from "./approval-hook.js";
 import { parkedTurnAnswer } from "./parked-turn.js";
+import { defaultCliSettingsPath, ensureQueuedMessagesInFile } from "./queued-messages.js";
 import { redactText } from "./redact.js";
+import { StreamSanitizer, sanitizeSystemMessage } from "./stream-sanitizer.js";
 import type {
 	AgyUsage,
 	DriverActivity,
@@ -44,6 +46,8 @@ export type {
 	TurnOutcome,
 } from "./driver-types.js";
 
+export { StreamSanitizer, sanitizeSystemMessage };
+
 const LIFECYCLE_LIMIT = 24;
 const THINKING_TOKEN_FLOOR = 64;
 
@@ -61,6 +65,8 @@ interface ActiveTurn {
 	idleTimer?: NodeJS.Timeout;
 	onAbort?: () => void;
 	response: string;
+	rawResponse: string;
+	sanitizer: StreamSanitizer;
 	usage?: AgyUsage;
 	conversationId?: string;
 	/** Wall clock at turn creation; the parked-turn probe filters
@@ -305,6 +311,8 @@ export class StreamDriver implements TurnDriver {
 			resolve,
 			outcome,
 			response: "",
+			rawResponse: "",
+			sanitizer: new StreamSanitizer(),
 			sawResult: false,
 			sawModelStep: false,
 			cumulativeText: undefined,
@@ -370,6 +378,8 @@ export class StreamDriver implements TurnDriver {
 		this.#boundConversation = request.conversationId ?? undefined;
 		this.#stderrTail = "";
 
+		ensureQueuedMessagesInFile(defaultCliSettingsPath());
+
 		const args: string[] = ["--add-dir", request.cwd];
 		// The bridge dir carries .agents/mcp_config.json (tool bridge) and, when
 		// the approval gate is on, .agents/hooks.json (gate staging). Only this
@@ -571,7 +581,11 @@ export class StreamDriver implements TurnDriver {
 				const ok = r.status === "OK" || r.status === "SUCCESS";
 				const status = ok ? "OK" : "ERROR";
 				// Prefer the streamed accumulation, fall back to the result body.
-				const response = turn.response || (typeof r.response === "string" ? r.response : "");
+				const fallback = typeof r.response === "string" ? sanitizeSystemMessage(r.response) : "";
+				const response = turn.response || fallback;
+				if (!turn.response && fallback) {
+					turn.sanitizer.reset();
+				}
 				turn.response = response;
 				this.#settle(turn, {
 					conversationId: turn.conversationId,
@@ -596,36 +610,54 @@ export class StreamDriver implements TurnDriver {
 		// misflips (round-7 review): short accumulations never flip, and a
 		// cumulative frame that no longer extends the accumulator is evidence
 		// of a misflip - fall back to append mode.
+		let rawDelta = "";
 		if (turn.cumulativeText === undefined) {
 			turn.cumulativeText = false;
 		} else if (
 			!turn.cumulativeText &&
-			shouldFlipToCumulative(turn.response, text)
+			shouldFlipToCumulative(turn.rawResponse, text)
 		) {
 			turn.cumulativeText = true;
 		}
 		if (turn.cumulativeText) {
-			if (!text.startsWith(turn.response)) {
+			if (!text.startsWith(turn.rawResponse)) {
 				// Misflip evidence: back to deltas.
 				turn.cumulativeText = false;
-				turn.response += text;
-				emit(turn, { type: "text", delta: text });
+				turn.rawResponse += text;
+				rawDelta = text;
+			} else if (text.length > turn.rawResponse.length) {
+				rawDelta = text.slice(turn.rawResponse.length);
+				turn.rawResponse = text;
+			} else {
 				return;
 			}
-			if (text.length > turn.response.length) {
-				const delta = text.slice(turn.response.length);
-				turn.response = text;
-				emit(turn, { type: "text", delta });
+		} else {
+			turn.rawResponse += text;
+			rawDelta = text;
+		}
+
+		if (rawDelta.length > 0) {
+			const sanitizedDelta = turn.sanitizer.push(rawDelta);
+			if (sanitizedDelta.length > 0) {
+				turn.response += sanitizedDelta;
+				emit(turn, { type: "text", delta: sanitizedDelta });
 			}
-			return;
 		}
-		turn.response += text;
-		emit(turn, { type: "text", delta: text });
 	}
 
 	#settle(turn: ActiveTurn, outcome: TurnOutcome): void {
 		if (turn.closed) return;
 		turn.closed = true;
+		const flushed = turn.sanitizer.flush();
+		if (flushed.length > 0) {
+			turn.response += flushed;
+			emit(turn, { type: "text", delta: flushed });
+		}
+		if (outcome.deadline && outcome.status === "OK") {
+			outcome.response = outcome.response || turn.response;
+		} else {
+			outcome.response = turn.response || outcome.response;
+		}
 		if (turn.overallTimer) clearTimeout(turn.overallTimer);
 		if (turn.idleTimer) clearTimeout(turn.idleTimer);
 		if (turn.onAbort && turn.request.signal) {
@@ -680,7 +712,7 @@ export class StreamDriver implements TurnDriver {
 			this.#settle(turn, {
 				conversationId: turn.conversationId,
 				status: "OK",
-				response: parked,
+				response: sanitizeSystemMessage(parked),
 				usage: turn.usage,
 				finished: true,
 				aborted: false,

package/src/mcp-registration.ts

@@ -221,7 +221,12 @@ function bestEffortWriteMarker(file: string, marker: SuppressionMarker): void {
 	}
 }
 
-const suppressionRefs = new Map<string, number>();
+// Pi replaces the runtime on /new,/resume,/fork,/reload: module state dies
+// but globalThis survives within the process. The refcount must live there,
+// or an old runtime's late release re-enables entries under a new runtime's
+// live delegation.
+const SUPPRESSION_REFS_KEY = Symbol.for("pi-antigravity-bridge.suppression-refs");
+const suppressionRefs: Map<string, number> = ((globalThis as Record<symbol, unknown>)[SUPPRESSION_REFS_KEY] ??= new Map()) as Map<string, number>;
 
 /** Reference-counted suppression for a self-spawned agy process (AskAntigravity
  *  delegation). First acquire disables every pi-bridge-* entry AND records

package/src/models.ts

@@ -361,9 +361,8 @@ function thinkingLevelMapFor(efforts: readonly AgyEffort[]): ThinkingLevelMap {
 }
 
 /** Project an agy entry to pi's Model shape. `input` advertises accepted
- *  inputs: text-only (default) or text+image. The ACP engine forwards image
- *  blocks natively (probe 2026-09-03); the stream-json CLI prompt is text-only, so
- *  the extension decides by engine at load time. */
+ *  inputs; both engines accept images (ACP native content blocks,
+ *  stream-json staged files), so callers pass ["text", "image"] uniformly. */
 export function toPiModel(entry: AgyModelEntry, input: Array<"text" | "image"> = ["text"]): Model<Api> {
 	const effortDriven = !!entry.efforts && entry.efforts.length > 0;
 	return {
@@ -380,9 +379,8 @@ export function toPiModel(entry: AgyModelEntry, input: Array<"text" | "image"> =
 		// none is ever sent.
 		reasoning: effortDriven,
 		...(effortDriven ? { thinkingLevelMap: thinkingLevelMapFor(entry.efforts!) } : {}),
-		// Input advertising comes from the caller (engine-dependent): the ACP
-		// engine forwards image blocks; advertising images on the stream engine
-		// would let pi offer image attach only for them to be dropped.
+		// Input advertising comes from the caller: both engines deliver
+		// user-attached images now.
 		input,
 		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
 		// Gemini long context. agy doesn't expose the real per-model window in

package/src/prompt-images.ts

@@ -0,0 +1,92 @@
+// Stream-json prompt staging: user-attached image blocks cannot ride the CLI's
+// text-only turn input, so they are staged to temp files and the prompt points
+// the model at them. The model views them through the bridge read tool, whose
+// tool-result image content the CLI's MCP client delivers (probe 2026-09-07).
+// The ACP engine does not use this module: image blocks ride session/prompt
+// natively.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const STAGE_DIR_PREFIX = "pi-bridge-img-";
+
+/** Retention for staged files: the model may re-read them on later turns of
+ *  the same conversation, so sweeps cannot delete a dir this turn's prompt
+ *  still references. */
+export const STAGE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface StagedImage {
+	data: string;
+	mimeType: string;
+}
+
+const EXT_BY_MIME: Record<string, string> = {
+	"image/png": ".png",
+	"image/jpeg": ".jpg",
+	"image/gif": ".gif",
+	"image/webp": ".webp",
+	"image/bmp": ".bmp",
+};
+
+function sweepStale(root: string): void {
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(root);
+	} catch {
+		return;
+	}
+	const cutoff = Date.now() - STAGE_MAX_AGE_MS;
+	for (const entry of entries) {
+		if (!entry.startsWith(STAGE_DIR_PREFIX)) continue;
+		const full = path.join(root, entry);
+		try {
+			// lstat: never follow a symlink planted at our prefix in a shared tmp.
+			if (!fs.lstatSync(full).isDirectory()) continue;
+			if (fs.statSync(full).mtimeMs < cutoff) fs.rmSync(full, { recursive: true, force: true });
+		} catch {
+			// Raced with another process's sweep or deletion: nothing to do.
+		}
+	}
+}
+
+/** Write image blocks to a fresh staging dir under `root` (default the OS tmp
+ *  dir). Returns null on any failure (including an empty/malformed payload):
+ *  the turn then runs text-only instead of failing. */
+export function stagePromptImages(
+	images: Array<StagedImage>,
+	root?: string,
+): { dir: string; paths: string[] } | null {
+	const base = root ?? os.tmpdir();
+	let dir: string | null = null;
+	try {
+		sweepStale(base);
+		dir = fs.mkdtempSync(path.join(base, STAGE_DIR_PREFIX));
+		const paths = images.map((img, i) => {
+			const bytes = Buffer.from(img.data, "base64");
+			if (bytes.length === 0) throw new Error("empty image payload");
+			const ext = EXT_BY_MIME[img.mimeType] ?? ".bin";
+			const file = path.join(dir!, `image-${i + 1}${ext}`);
+			fs.writeFileSync(file, bytes, { mode: 0o600 });
+			return file;
+		});
+		return { dir, paths };
+	} catch {
+		// A mid-write failure must not leak a partial dir; the 24h sweep would
+		// reap it anyway, but the next staging call in this process is likely
+		// seconds away.
+		if (dir) {
+			try {
+				fs.rmSync(dir, { recursive: true, force: true });
+			} catch {
+				// Sweep reaps it later.
+			}
+		}
+		return null;
+	}
+}
+
+export function buildImageNote(paths: string[]): string {
+	const list = paths.map((p) => `- ${p}`).join("\n");
+	return `[The user attached ${paths.length} image(s) to this message. They are staged at:\n${list}\nView them by calling the pi read tool on these exact paths; the image content is delivered to you directly.]`;
+}

package/src/provider.ts

@@ -20,6 +20,7 @@
 import {
 	createAssistantMessageEventStream,
 	getCurrentSystemPrompt,
+	getCurrentTools,
 	type AssistantMessage,
 	type AssistantMessageEventStream,
 	type JsonValue,
@@ -44,6 +45,7 @@ import type { ApprovalDecision, ApprovalPayload, ApprovalParkApi } from "./mcp-s
 import path from "node:path";
 import { TurnDiffContext, createExecGitOps, formatInlineDiff, parseEditToolInput } from "./diff-render.js";
 import { stageSyspromptAgent } from "./sysprompt-agent.js";
+import { buildImageNote, stagePromptImages } from "./prompt-images.js";
 
 const DEFAULT_TIMEOUT_MIN = 10;
 
@@ -51,6 +53,29 @@ const DEFAULT_TIMEOUT_MIN = 10;
  *  the staged carrier agent (issue #2 inline-block fallback). */
 let warnedUserAgentConflict = false;
 
+/** Set of caller-scoped tool names declared by pi-observational-memory background workers.
+ *  Antigravity models run a closed tool loop on the backend CLI/ACP process and do not
+ *  support caller-scoped local tools. */
+export const OM_WORKER_TOOL_NAMES = new Set([
+	"record_observations",
+	"record_reflections",
+	"drop_observations",
+]);
+
+/** Detect if a turn belongs to a pi-observational-memory background worker. */
+export function isObservationalMemoryContext(context: TranscriptContext): boolean {
+	const currentTools = getCurrentTools(context.messages);
+	return currentTools.some((t) => OM_WORKER_TOOL_NAMES.has(t.name));
+}
+
+/** Track whether we have warned about observational-memory tool mismatch in this process. */
+let warnedObservationalMemoryMismatch = false;
+
+/** Reset latch for unit testing. */
+export function _resetObservationalMemoryWarnedForTesting(): void {
+	warnedObservationalMemoryMismatch = false;
+}
+
 /** conversationId -> staged carrier agent name. Gate-closed turns look the
  *  name up here so a conversation's agent field never flips: a change would
  *  recycle the agy process mid-conversation (profile drift), and a respawn
@@ -80,7 +105,8 @@ function extractUserPrompt(context: TranscriptContext): string | null {
 	if (!last || last.role !== "user") return null;
 	const content = last.content;
 	if (typeof content === "string") return content;
-	// Flatten text blocks; images ride separately via extractImages (ACP only).
+	// Flatten text blocks; images ride separately via extractImages (native
+	// blocks on ACP, staged files on stream-json via prompt-images.ts).
 	return content
 		.filter((b): b is { type: "text"; text: string } => b.type === "text")
 		.map((b) => b.text)
@@ -89,8 +115,9 @@ function extractUserPrompt(context: TranscriptContext): string | null {
 }
 
 /** Image blocks of the latest user message (pi-ai ImageContent: base64 data
- *  + mimeType). The ACP engine forwards them as typed content blocks; the
- *  stream-json CLI prompt is text-only, so its driver simply ignores these. */
+ *  + mimeType). On the ACP engine they ride session/prompt as native
+ *  content blocks; on stream-json they are staged to temp files and the
+ *  prompt names the paths (see prompt-images.ts). */
 function extractImages(context: TranscriptContext): Array<{ data: string; mimeType: string }> {
 	const last = context.messages[context.messages.length - 1];
 	if (!last || last.role !== "user" || typeof last.content === "string") return [];
@@ -140,7 +167,7 @@ export const SYSTEM_PROMPT_END = "[END SYSTEM PROMPT]";
  *  the user's machine must go through the bridge. 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. Your native file tools such as view_file only read brain artifacts and reject real filesystem paths; for any path on the user's machine use the Pi Bridge tools (read, ls, grep, find, edit, execute). Delegate subagent work the same way: when pi's tool list includes a delegation tool (for example subagent, Agent, agent_spawn, agent_wait, or subagent_run), always delegate through it and never through the native invoke_subagent, run_subagent, or manage_subagents; use native ones only if no pi delegation tool is listed, because native subagents run inside agy and are invisible to pi and anything watching it. Long-running bridge calls do not fail: after ~20 seconds the bridge answers STILL RUNNING with a callId; fetch the result with bridge_poll_result and poll until it lands. For work you already know is long, prefer exec_command's session-output pattern or background agents so you keep working while it runs.]";
+	"[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. Your native file tools such as view_file only read brain artifacts and reject real filesystem paths; for any path on the user's machine use the Pi Bridge tools (read, ls, grep, find, edit, execute). Image files are visible to you: the Pi Bridge read tool returns image files as visible images (png, jpg, webp, gif, bmp), so never claim you cannot view images. When a bridge call answers STILL RUNNING, poll bridge_poll_result before doing other work: until you poll, the result (including any image) stays undelivered to you. Delegate subagent work the same way: when pi's tool list includes a delegation tool (for example subagent, Agent, agent_spawn, agent_wait, or subagent_run), always delegate through it and never through the native invoke_subagent, run_subagent, or manage_subagents; use native ones only if no pi delegation tool is listed, because native subagents run inside agy and are invisible to pi and anything watching it. Long-running bridge calls do not fail: after ~20 seconds the bridge answers STILL RUNNING with a callId; fetch the result with bridge_poll_result and poll until it lands. For work you already know is long, prefer exec_command's session-output pattern or background agents so you keep working while it runs.]";
 
 /** Assemble the full agy prompt: system prompt block, pi-side digest, user
  *  prompt. Empty parts are dropped. Pure; exported for unit testing.
@@ -922,7 +949,8 @@ export class ToolRoundTrips {
 	/** Complete a parked call from a pi toolResult message. Returns false when
 	 *  the id matches nothing pending. Image blocks ride the result on both
 	 *  engines (probe-verified on each); the late-delivery prompt stays
-	 *  text-only (see PI-BRIDGE-GAPS). */
+	 *  text-only and its images re-attach through driver.run (native blocks on
+	 *  ACP, staged files on stream-json). */
 	resolve(
 		toolCallId: string,
 		text: string,
@@ -1033,6 +1061,9 @@ export interface LateToolResult {
 	reason: string;
 	text: string;
 	isError: boolean;
+	/** Image blocks of the stranded result (read on an image file). The
+	 *  redelivery prompt is text-only, so they ride driver.run images. */
+	images?: Array<{ data: string; mimeType: string }>;
 }
 
 /** Frame late tool results so agy treats them as the results its bridge calls
@@ -1308,8 +1339,10 @@ async function runTurnDriver(
 	// Images ride tool results on BOTH engines (ACP probe 2026-09-05;
 	// stream-json probe 2026-09-07: the CLI's MCP client delivers tool-result
 	// image content to the model — two-tone PNG named from the result alone,
-	// no decoders in the frame trail). The late-delivery prompt and the
-	// stream-json prompt attachments stay text-only by design.
+	// no decoders in the frame trail). The late-delivery PROMPT stays
+	// text-only: image blocks ride driver.run images instead, so both
+	// engines deliver them (ACP native prompt blocks; stream-json staged
+	// files).
 	for (const r of results)
 		deps.roundTrips.resolve(r.toolCallId, r.text, r.isError, r.images);
 
@@ -1326,7 +1359,14 @@ async function runTurnDriver(
 	if (!isContinuation) {
 		for (const r of collectToolResults(context.messages, deps.roundTrips.deadIds)) {
 			const dead = deps.roundTrips.consumeDead(r.toolCallId);
-			if (dead) late.push({ name: dead.name, reason: dead.reason, text: r.text, isError: r.isError });
+			if (dead)
+				late.push({
+					name: dead.name,
+					reason: dead.reason,
+					text: r.text,
+					isError: r.isError,
+					images: r.images.length > 0 ? r.images : undefined,
+				});
 		}
 		if (late.length > 0) {
 			deps.log?.("late-result", { tools: late.map((l) => l.name), freshConversation: !existing?.conversationId }, "info");
@@ -1353,8 +1393,25 @@ async function runTurnDriver(
 				reason: "you never received this result: you ended your turn without calling bridge_poll_result",
 				text: view.text ?? "(no output)",
 				isError: view.isError ?? false,
+				images: view.images,
 			};
 		});
+	/** Stream-json has no image channel in the turn input: stage the blocks
+	 *  to temp files and let the note point the model at the bridge read
+	 *  tool, whose result images the CLI delivers (probe 2026-09-07). ACP
+	 *  rides native content blocks; no staging there. */
+	const stageImageNote = (imgs: Array<{ data: string; mimeType: string }>): string => {
+		if (deps.engine === "acp" || imgs.length === 0) return "";
+		const staged = stagePromptImages(imgs);
+		if (!staged) {
+			deps.log?.("turn-warning", { reason: "image-staging-failed", count: imgs.length }, "warn");
+			// Silence would strand the pixels forever: on a redelivery the claim
+			// is already consumed, so the model must at least learn the image
+			// existed and re-request it.
+			return `\n\n[${imgs.length} image(s) could not be delivered to this turn; ask the user to re-attach or re-read the original path.]`;
+		}
+		return `\n\n${buildImageNote(staged.paths)}`;
+	};
 
 	const entry = entries.find((e) => e.id === model.id) ?? null;
 	const agyModel = entry?.full ?? model.id;
@@ -1457,10 +1514,15 @@ async function runTurnDriver(
 				agent = stagedAgentByConversation.get(existing.conversationId);
 			}
 		}
+		// Late/stranded image results ride driver.run images (the redelivery
+		// prompt is text-only); user-message images ride them on ACP natively
+		// and staged files on stream-json.
+		const runImages = [...images, ...late.flatMap((l) => l.images ?? [])];
 		const fullPrompt =
-			late.length > 0
+			(late.length > 0
 				? buildLateResultPrompt(late, prompt || undefined)
-				: buildFullPrompt(sysPrompt, embeddedDigest ? "" : digest, prompt ?? "");
+				: buildFullPrompt(sysPrompt, embeddedDigest ? "" : digest, prompt ?? "")) +
+			stageImageNote(runImages);
 		try {
 			handle = await deps.driver.run({
 				cwd,
@@ -1472,7 +1534,7 @@ async function runTurnDriver(
 				inactivityMin: config.inactivityTimeoutMin,
 				conversationId: redeliveryConversation ?? existing?.conversationId ?? null,
 				prompt: fullPrompt,
-				images: images.length > 0 ? images : undefined,
+				images: runImages.length > 0 ? runImages : undefined,
 				agent,
 				contextBlock: embeddedDigest
 					? {
@@ -1569,6 +1631,7 @@ async function runTurnDriver(
 		if (more.length > 0) {
 			const conv = redeliveryConversation ?? outcome.conversationId ?? existing?.conversationId ?? null;
 			deps.log?.("escalated-redelivery-turn", { tools: more.map((s) => s.name), conversation: conv }, "info");
+			const moreImages = more.flatMap((s) => s.images ?? []);
 			try {
 				const lateHandle = await deps.driver.run({
 					cwd,
@@ -1579,7 +1642,8 @@ async function runTurnDriver(
 					timeoutMin: config.turnTimeoutMin,
 					inactivityMin: config.inactivityTimeoutMin,
 					conversationId: conv,
-					prompt: buildLateResultPrompt(more),
+					prompt: buildLateResultPrompt(more) + stageImageNote(moreImages),
+					images: moreImages.length > 0 ? moreImages : undefined,
 					agent: config.agent ?? (conv ? stagedAgentByConversation.get(conv) : undefined),
 					signal: options?.signal,
 				});
@@ -1650,6 +1714,34 @@ export function createStreamSimple(
 
 	return function streamSimple(model, context, options) {
 		const stream = createAssistantMessageEventStream();
+
+		// Short-circuit pi-observational-memory background workers.
+		// Observational memory workers declare caller-scoped tools (record_observations,
+		// record_reflections, drop_observations). Antigravity models run in a closed backend
+		// process with their own tool execution loop and do not support caller-scoped tools.
+		// If dispatched to agy, the model sees tool instructions without tools and enters
+		// an autonomous loop searching the disk for their implementation.
+		// Returning a clean stop with empty content triggers OM's empty-observer backoff,
+		// preventing high-frequency retries on subsequent turns.
+		if (isObservationalMemoryContext(context)) {
+			if (!warnedObservationalMemoryMismatch) {
+				warnedObservationalMemoryMismatch = true;
+				deps.log?.(
+					"turn-warning",
+					{
+						reason: "observational-memory-unsupported",
+						message:
+							"Observational memory background workers cannot run against Antigravity models (caller-scoped tools unsupported). Configure a dedicated model under 'observational-memory.model' in settings.json.",
+					},
+					"warn",
+				);
+			}
+			const partial = newAssistant(model);
+			const blocks: BlockState = { partial, textIdx: null, thinkingIdx: null, started: false };
+			finalize(stream, blocks, "stop");
+			return stream;
+		}
+
 		// Fire the async turn; return the stream synchronously per pi's contract.
 		// Engine selection: the latched load-time engine when the extension
 		// provides one, else the per-call config read (tests). One loadConfig()

package/src/queued-messages.ts

@@ -0,0 +1,171 @@
+// Settings manager for Antigravity's "Queued Messages" delivery strategy.
+//
+// In agy v1.2.14+, agy introduced the "Queued Messages" option:
+// - "queue" (agy default): hold follow-up / steering messages until current turn ends
+// - "send-immediately": interrupt the agent with follow-up / steering messages immediately
+//
+// Pi expects immediate message delivery / steering during interactive chat.
+// This module ensures that both the stream-json engine (~/.gemini/antigravity-cli/settings.json)
+// and ACP engine (~/.gemini/antigravity-acp/settings.json) default to "send-immediately"
+// so user steering works as expected in Pi without manual user configuration.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const QUEUED_MESSAGES_SEND_IMMEDIATELY = "send-immediately";
+
+export function defaultCliSettingsPath(): string {
+	return path.join(os.homedir(), ".gemini", "antigravity-cli", "settings.json");
+}
+
+export function defaultAcpSettingsPath(): string {
+	return path.join(os.homedir(), ".gemini", "antigravity-acp", "settings.json");
+}
+
+export interface EnsureFileResult {
+	path: string;
+	updated: boolean;
+	value: string;
+	error?: string;
+}
+
+export interface EnsureFileOptions {
+	defaultValue?: string;
+	onlyIfDirExists?: boolean;
+}
+
+/**
+ * Ensure `queuedMessages` is present in the specified settings.json file.
+ * If unset or empty, writes `send-immediately`.
+ *
+ * Safety guards:
+ * - If the file exists but has invalid JSON or is not an object, does NOT clobber; returns updated: false.
+ * - If the file already specifies a non-empty `queuedMessages`, leaves it untouched.
+ * - Resolves symlinks before writing to protect dotfiles managers.
+ * - Writes via temp file and atomic rename.
+ * - Traps any I/O exceptions so callers never crash on read-only or permission-denied files.
+ */
+export function ensureQueuedMessagesInFile(
+	filePath: string,
+	opts: EnsureFileOptions | string = {},
+): EnsureFileResult {
+	const options: EnsureFileOptions =
+		typeof opts === "string" ? { defaultValue: opts } : opts;
+	const defaultValue = options.defaultValue ?? QUEUED_MESSAGES_SEND_IMMEDIATELY;
+	const onlyIfDirExists = options.onlyIfDirExists ?? false;
+
+	let resolvedPath = filePath;
+	try {
+		if (fs.existsSync(filePath)) {
+			resolvedPath = fs.realpathSync(filePath);
+		}
+	} catch {
+		// Keep original path if realpath fails
+	}
+
+	const dir = path.dirname(resolvedPath);
+	if (onlyIfDirExists && !fs.existsSync(dir)) {
+		return { path: resolvedPath, updated: false, value: "" };
+	}
+
+	let settings: Record<string, unknown> = {};
+	let fileExists = false;
+
+	try {
+		const raw = fs.readFileSync(resolvedPath, "utf8");
+		fileExists = true;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(raw);
+		} catch (parseErr) {
+			// Malformed JSON: do NOT clobber the user's file.
+			return {
+				path: resolvedPath,
+				updated: false,
+				value: "",
+				error: `malformed JSON in ${resolvedPath}: ${String(parseErr)}`,
+			};
+		}
+
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return {
+				path: resolvedPath,
+				updated: false,
+				value: "",
+				error: `settings in ${resolvedPath} is not a JSON object`,
+			};
+		}
+		settings = parsed as Record<string, unknown>;
+	} catch (err: unknown) {
+		const code = (err as { code?: string })?.code;
+		if (code !== "ENOENT") {
+			// Read error other than absent file (e.g. EACCES): do not overwrite.
+			return {
+				path: resolvedPath,
+				updated: false,
+				value: "",
+				error: `failed reading ${resolvedPath}: ${String(err)}`,
+			};
+		}
+	}
+
+	const current = settings.queuedMessages;
+	if (typeof current === "string" && current.trim().length > 0) {
+		return { path: resolvedPath, updated: false, value: current };
+	}
+
+	settings.queuedMessages = defaultValue;
+
+	let tmpPath = "";
+	try {
+		fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+		tmpPath = path.join(dir, `.${path.basename(resolvedPath)}.${process.pid}.${Date.now()}.tmp`);
+		fs.writeFileSync(tmpPath, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+		fs.renameSync(tmpPath, resolvedPath);
+		return { path: resolvedPath, updated: true, value: defaultValue };
+	} catch (err) {
+		if (tmpPath) {
+			try {
+				fs.unlinkSync(tmpPath);
+			} catch {
+				/* ignore */
+			}
+		}
+		return {
+			path: resolvedPath,
+			updated: false,
+			value: "",
+			error: `failed writing ${resolvedPath}: ${String(err)}`,
+		};
+	}
+}
+
+export interface EnsureQueuedMessagesOptions {
+	cliSettingsPath?: string;
+	acpSettingsPath?: string;
+	defaultValue?: string;
+	onlyIfDirExists?: boolean;
+}
+
+export interface EnsureQueuedMessagesReport {
+	cli: EnsureFileResult;
+	acp: EnsureFileResult;
+}
+
+/**
+ * Ensure both stream-json (CLI) and ACP engines default to "send-immediately".
+ */
+export function ensureQueuedMessagesDefaults(
+	opts: EnsureQueuedMessagesOptions = {},
+): EnsureQueuedMessagesReport {
+	const cliPath = opts.cliSettingsPath ?? defaultCliSettingsPath();
+	const acpPath = opts.acpSettingsPath ?? defaultAcpSettingsPath();
+	const defVal = opts.defaultValue ?? QUEUED_MESSAGES_SEND_IMMEDIATELY;
+	const onlyIfDirExists = opts.onlyIfDirExists ?? false;
+
+	const cli = ensureQueuedMessagesInFile(cliPath, { defaultValue: defVal, onlyIfDirExists });
+	const acp = ensureQueuedMessagesInFile(acpPath, { defaultValue: defVal, onlyIfDirExists });
+
+	return { cli, acp };
+}