@linxiraos/pi-agent-core 1.1.14 → 1.1.16

package/src/agent.ts

@@ -50,6 +50,8 @@ import type {
 	AgentToolContext,
 	AgentTurnEndContext,
 	AsideMessage,
+	PrepareQueuedMessages,
+	SpeculativeToolExecutionConfig,
 	StreamFn,
 	ToolCallContext,
 	ToolChoiceDirective,
@@ -242,13 +244,22 @@ export interface AgentOptions {
 	 * Use for deobfuscating secrets or rewriting arguments.
 	 */
 	transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
+	/** Host authorization and telemetry for opt-in speculative tool execution. */
+	speculativeToolExecution?: SpeculativeToolExecutionConfig;
 
 	/**
 	 * Resolve a tool call whose name matched no advertised tool. Lets hosts
 	 * route calls to tools exposed through side transports (e.g. `xd://`
 	 * device mounts) instead of failing with "Tool not found".
 	 */
-	resolveFallbackTool?: (name: string) => AgentTool<any> | undefined;
+	resolveFallbackTool?: (name: string, advertised: readonly AgentTool<any>[]) => AgentTool<any> | undefined;
+
+	/**
+	 * Names routable by {@link resolveFallbackTool} that the advertised set
+	 * omits (e.g. `xd://` device mounts), used only to suggest a target when a
+	 * call misses.
+	 */
+	suggestFallbackToolNames?: () => Iterable<string>;
 
 	/** Enable intent tracing schema injection/stripping in the harness. */
 	intentTracing?: boolean;
@@ -352,6 +363,13 @@ interface CursorToolResultEntry {
 	pending?: Promise<void>;
 }
 
+type QueuedMessageQueue = "steering" | "followUp";
+
+interface QueuedMessageClaim {
+	messages: AgentMessage[];
+	controller: AbortController;
+}
+
 export class Agent {
 	#state: AgentState = {
 		systemPrompt: [],
@@ -373,6 +391,14 @@ export class Agent {
 	#transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
 	#steeringQueue: AgentMessage[] = [];
 	#followUpQueue: AgentMessage[] = [];
+	#queuedMessageClaims: Partial<Record<QueuedMessageQueue, QueuedMessageClaim>> = {};
+	/** Dequeued originals remain recoverable until their transcript events arrive. */
+	#queuedMessageDeliveries = new Set<{
+		queue: QueuedMessageQueue;
+		controller: AbortController | undefined;
+		messages: AgentMessage[];
+		next: number;
+	}>();
 	#steeringWaiters = new Set<() => void>();
 
 	#steeringMode: "all" | "one-at-a-time";
@@ -407,7 +433,9 @@ export class Agent {
 	#kimiApiFormat?: "openai" | "anthropic";
 	#preferWebsockets?: boolean;
 	#transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
-	#resolveFallbackTool?: (name: string) => AgentTool<any> | undefined;
+	#speculativeToolExecution?: SpeculativeToolExecutionConfig;
+	#resolveFallbackTool?: (name: string, advertised: readonly AgentTool<any>[]) => AgentTool<any> | undefined;
+	#suggestFallbackToolNames?: () => Iterable<string>;
 	#intentTracing: boolean;
 	#pruneToolDescriptions: boolean;
 	#dialect?: Dialect;
@@ -433,9 +461,12 @@ export class Agent {
 
 	/** Buffered Cursor tool results with text length at time of call (for correct ordering) */
 	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
+	#cursorToolResultDrain: CursorToolResultEntry[] | undefined;
 
 	streamFn: StreamFn;
 	getApiKey?: (model: Model) => Promise<ApiKey | undefined> | ApiKey | undefined;
+	/** Prepare actual queue deliveries after dequeue gates; commit runs only while ownership remains valid. */
+	prepareQueuedMessages?: PrepareQueuedMessages;
 	/**
 	 * Hook invoked after tool arguments are validated and before execution.
 	 * Reassign at any time to swap the implementation (e.g. on extension reload).
@@ -496,7 +527,9 @@ export class Agent {
 		this.#kimiApiFormat = opts.kimiApiFormat;
 		this.#preferWebsockets = opts.preferWebsockets;
 		this.#transformToolCallArguments = opts.transformToolCallArguments;
+		this.#speculativeToolExecution = opts.speculativeToolExecution;
 		this.#resolveFallbackTool = opts.resolveFallbackTool;
+		this.#suggestFallbackToolNames = opts.suggestFallbackToolNames;
 		this.#intentTracing = opts.intentTracing === true;
 		this.#pruneToolDescriptions = opts.pruneToolDescriptions === true;
 		this.#dialect = opts.dialect;
@@ -829,16 +862,90 @@ export class Agent {
 		for (const hook of this.#beforeQueuedMessageDequeueHooks) await hook(signal);
 	}
 
-	async #dequeueSteeringMessagesAfterHooks(signal?: AbortSignal): Promise<AgentMessage[]> {
-		if (signal?.aborted || this.#steeringQueue.length === 0) return [];
+	async #dequeueSteeringMessagesAfterHooks(signal: AbortSignal): Promise<AgentMessage[]> {
+		if (signal.aborted || this.#steeringQueue.length === 0) return [];
 		await this.#runBeforeQueuedMessageDequeueHooks(signal);
-		return signal?.aborted ? [] : this.#dequeueSteeringMessages();
+		return signal.aborted ? [] : this.#prepareQueuedMessageBatch("steering", signal);
 	}
 
-	async #dequeueFollowUpMessagesAfterHooks(signal?: AbortSignal): Promise<AgentMessage[]> {
-		if (signal?.aborted || this.#followUpQueue.length === 0) return [];
+	async #dequeueFollowUpMessagesAfterHooks(signal: AbortSignal): Promise<AgentMessage[]> {
+		if (signal.aborted || this.#followUpQueue.length === 0) return [];
 		await this.#runBeforeQueuedMessageDequeueHooks(signal);
-		return signal?.aborted ? [] : this.#dequeueFollowUpMessages();
+		return signal.aborted ? [] : this.#prepareQueuedMessageBatch("followUp", signal);
+	}
+
+	async #prepareQueuedMessageBatch(queue: QueuedMessageQueue, signal: AbortSignal): Promise<AgentMessage[]> {
+		if (this.#queuedMessageClaims[queue]) return [];
+		const messages = queue === "steering" ? this.#dequeueSteeringMessages() : this.#dequeueFollowUpMessages();
+		const prepare = this.prepareQueuedMessages;
+		if (messages.length === 0) return messages;
+		const runController = this.#abortController;
+		if (!prepare) {
+			this.#queuedMessageDeliveries.add({ queue, controller: runController, messages, next: 0 });
+			return messages;
+		}
+
+		const claim: QueuedMessageClaim = { messages, controller: new AbortController() };
+		this.#queuedMessageClaims[queue] = claim;
+		const preparationSignal = AbortSignal.any([signal, claim.controller.signal]);
+		try {
+			const preparation = await prepare(messages, preparationSignal);
+			signal.throwIfAborted();
+			if (preparationSignal.aborted || this.#queuedMessageClaims[queue] !== claim) return [];
+			const additional = preparation?.commit();
+			if (preparationSignal.aborted || this.#queuedMessageClaims[queue] !== claim) return [];
+			if (preparation && additional === undefined) {
+				// Stop this attempt before the loop can immediately reclaim the restored batch.
+				runController?.abort();
+				throw new DOMException("Queued message preparation cancelled", "AbortError");
+			}
+			delete this.#queuedMessageClaims[queue];
+			this.#queuedMessageDeliveries.add({ queue, controller: runController, messages, next: 0 });
+			return additional?.length ? [...messages, ...additional] : messages;
+		} catch (error) {
+			if (signal.aborted) throw error;
+			if (preparationSignal.aborted || this.#queuedMessageClaims[queue] !== claim) return [];
+			throw error;
+		} finally {
+			if (this.#queuedMessageClaims[queue] === claim) this.#cancelQueuedMessagePreparation(queue, true);
+		}
+	}
+
+	#cancelQueuedMessagePreparation(queue: QueuedMessageQueue, restore = false): void {
+		if (!restore) {
+			for (const delivery of this.#queuedMessageDeliveries) {
+				if (delivery.queue === queue) this.#queuedMessageDeliveries.delete(delivery);
+			}
+		}
+		const claim = this.#queuedMessageClaims[queue];
+		if (!claim) return;
+		delete this.#queuedMessageClaims[queue];
+		if (restore) {
+			if (queue === "steering") {
+				this.#steeringQueue = [...claim.messages, ...this.#steeringQueue];
+				this.#notifySteeringWaiters();
+			} else {
+				this.#followUpQueue = [...claim.messages, ...this.#followUpQueue];
+			}
+		}
+		claim.controller.abort();
+	}
+
+	#restoreUndeliveredQueuedMessages(controller: AbortController): void {
+		if (this.#queuedMessageDeliveries.size === 0) return;
+		const restored: Record<QueuedMessageQueue, AgentMessage[]> = { steering: [], followUp: [] };
+		for (const delivery of this.#queuedMessageDeliveries) {
+			if (delivery.controller !== controller) continue;
+			this.#queuedMessageDeliveries.delete(delivery);
+			for (let i = delivery.next; i < delivery.messages.length; i++) {
+				restored[delivery.queue].push(delivery.messages[i]);
+			}
+		}
+		if (restored.steering.length > 0) {
+			this.#steeringQueue = [...restored.steering, ...this.#steeringQueue];
+			this.#notifySteeringWaiters();
+		}
+		if (restored.followUp.length > 0) this.#followUpQueue = [...restored.followUp, ...this.#followUpQueue];
 	}
 
 	setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void {
@@ -973,11 +1080,18 @@ export class Agent {
 	replaceQueues(steering: AgentMessage[], followUp: AgentMessage[]) {
 		this.#steeringQueue = steering.slice();
 		this.#followUpQueue = followUp.slice();
+		this.#cancelQueuedMessagePreparation("steering");
+		this.#cancelQueuedMessagePreparation("followUp");
 		this.#notifySteeringWaiters();
 	}
 
 	appendMessage(m: AgentMessage) {
 		this.#state.messages.push(m);
+		for (const delivery of this.#queuedMessageDeliveries) {
+			if (delivery.messages[delivery.next] !== m) continue;
+			if (++delivery.next === delivery.messages.length) this.#queuedMessageDeliveries.delete(delivery);
+			break;
+		}
 	}
 
 	popMessage(): AgentMessage | undefined {
@@ -1007,11 +1121,13 @@ export class Agent {
 
 	clearSteeringQueue() {
 		this.#steeringQueue = [];
+		this.#cancelQueuedMessagePreparation("steering");
 		this.#notifySteeringWaiters();
 	}
 
 	clearFollowUpQueue() {
 		this.#followUpQueue = [];
+		this.#cancelQueuedMessagePreparation("followUp");
 	}
 
 	/**
@@ -1026,26 +1142,43 @@ export class Agent {
 	clearAllQueues() {
 		this.#steeringQueue = [];
 		this.#followUpQueue = [];
+		this.#cancelQueuedMessagePreparation("steering");
+		this.#cancelQueuedMessagePreparation("followUp");
 		this.#notifySteeringWaiters();
 		this.clearDeferredToolDirectives();
 	}
 
 	hasQueuedMessages(): boolean {
-		return this.#steeringQueue.length > 0 || this.#followUpQueue.length > 0;
+		return (
+			this.#steeringQueue.length > 0 ||
+			this.#followUpQueue.length > 0 ||
+			this.#queuedMessageClaims.steering !== undefined ||
+			this.#queuedMessageClaims.followUp !== undefined
+		);
 	}
 
 	/** Non-consuming view of the pending steering queue (insertion order, newest
 	 *  last). The session layer derives its queued-message display/count from
 	 *  this live view instead of a mirror, so the agent-core queue stays the
-	 *  single source of truth. */
+	 *  single source of truth. Includes exclusively claimed originals while
+	 *  preparation is pending, so editor restoration can cancel their delivery. */
 	peekSteeringQueue(): readonly AgentMessage[] {
-		return this.#steeringQueue;
+		const claim = this.#queuedMessageClaims.steering;
+		return claim ? [...claim.messages, ...this.#steeringQueue] : this.#steeringQueue;
 	}
 
 	/** Non-consuming view of the pending follow-up queue. See
 	 *  {@link peekSteeringQueue}. */
 	peekFollowUpQueue(): readonly AgentMessage[] {
-		return this.#followUpQueue;
+		const claim = this.#queuedMessageClaims.followUp;
+		return claim ? [...claim.messages, ...this.#followUpQueue] : this.#followUpQueue;
+	}
+
+	/** Nonblocking snapshot of the latest results, including provisional payloads while transforms are pending. */
+	getPendingToolResults(): readonly ToolResultMessage[] {
+		const results = this.#cursorToolResultDrain?.map(({ toolResult }) => toolResult) ?? [];
+		for (const { toolResult } of this.#cursorToolResultBuffer) results.push(toolResult);
+		return results;
 	}
 
 	get isAborting(): boolean {
@@ -1085,6 +1218,7 @@ export class Agent {
 	 * Used by dequeue keybinding.
 	 */
 	popLastSteer(): AgentMessage | undefined {
+		if (this.#steeringQueue.length === 0) this.#cancelQueuedMessagePreparation("steering", true);
 		return this.#steeringQueue.pop();
 	}
 
@@ -1093,6 +1227,7 @@ export class Agent {
 	 * Used by dequeue keybinding.
 	 */
 	popLastFollowUp(): AgentMessage | undefined {
+		if (this.#followUpQueue.length === 0) this.#cancelQueuedMessagePreparation("followUp", true);
 		return this.#followUpQueue.pop();
 	}
 
@@ -1132,15 +1267,19 @@ export class Agent {
 	}
 
 	reset() {
+		if (this.#queuedMessageClaims.steering || this.#queuedMessageClaims.followUp) {
+			this.#abortController?.abort();
+			this.#abortController = undefined;
+			this.#resolveRunningPrompt?.();
+			this.#runningPrompt = undefined;
+			this.#resolveRunningPrompt = undefined;
+		}
 		this.#state.messages.length = 0;
 		this.#state.isStreaming = false;
 		this.#state.streamMessage = null;
 		this.#state.pendingToolCalls.clear();
 		this.#state.error = undefined;
-		this.#steeringQueue = [];
-		this.#followUpQueue = [];
-		this.#notifySteeringWaiters();
-		this.clearDeferredToolDirectives();
+		this.clearAllQueues();
 	}
 
 	/** Send a prompt with an AgentMessage */
@@ -1228,7 +1367,7 @@ export class Agent {
 		this.#state.error = undefined;
 
 		try {
-			const dequeueSignal = this.#continuationDequeueSignal(signal);
+			const dequeueSignal = this.#continuationDequeueSignal(signal) ?? continuationAbortController.signal;
 			const messages = this.#state.messages;
 			if (messages.length === 0) {
 				// An empty transcript has nothing to resume, but a queued steer/follow-up
@@ -1238,11 +1377,13 @@ export class Agent {
 				// microtask because hasQueuedMessages() never clears, spinning an unbounded
 				// allocation loop until OOM (issue #6344).
 				const queuedSteering = await this.#dequeueSteeringMessagesAfterHooks(dequeueSignal);
+				if (this.#abortController !== continuationAbortController) return;
 				if (queuedSteering.length > 0) {
 					await this.#runLoop(queuedSteering, { skipInitialSteeringPoll: true }, signal, true);
 					return;
 				}
 				const queuedFollowUp = await this.#dequeueFollowUpMessagesAfterHooks(dequeueSignal);
+				if (this.#abortController !== continuationAbortController) return;
 				if (queuedFollowUp.length > 0) {
 					await this.#runLoop(queuedFollowUp, undefined, signal, true);
 					return;
@@ -1260,12 +1401,14 @@ export class Agent {
 					return;
 				}
 				const queuedSteering = await this.#dequeueSteeringMessagesAfterHooks(dequeueSignal);
+				if (this.#abortController !== continuationAbortController) return;
 				if (queuedSteering.length > 0) {
 					await this.#runLoop(queuedSteering, { skipInitialSteeringPoll: true }, signal, true);
 					return;
 				}
 
 				const queuedFollowUp = await this.#dequeueFollowUpMessagesAfterHooks(dequeueSignal);
+				if (this.#abortController !== continuationAbortController) return;
 				if (queuedFollowUp.length > 0) {
 					await this.#runLoop(queuedFollowUp, undefined, signal, true);
 					return;
@@ -1276,6 +1419,7 @@ export class Agent {
 
 			await this.#runLoop(undefined, undefined, signal, true);
 		} finally {
+			this.#restoreUndeliveredQueuedMessages(continuationAbortController);
 			resolve();
 			if (this.#abortController === continuationAbortController) {
 				this.#state.isStreaming = false;
@@ -1461,7 +1605,9 @@ export class Agent {
 			cwd: this.#cwd,
 			getCwd: this.#cwdResolver,
 			transformToolCallArguments: this.#transformToolCallArguments,
+			speculativeToolExecution: this.#speculativeToolExecution,
 			resolveFallbackTool: this.#resolveFallbackTool,
+			suggestFallbackToolNames: this.#suggestFallbackToolNames,
 			intentTracing: this.#intentTracing,
 			pruneToolDescriptions: this.#pruneToolDescriptions,
 			dialect: this.#dialect,
@@ -1489,7 +1635,7 @@ export class Agent {
 					skipInitialSteeringPoll = false;
 					return [];
 				}
-				return this.#dequeueSteeringMessagesAfterHooks(signal);
+				return this.#dequeueSteeringMessagesAfterHooks(signal ?? loopSignal);
 			},
 			hasSteeringMessages: () => {
 				if (this.#steeringQueue.length === 0) {
@@ -1514,7 +1660,7 @@ export class Agent {
 			},
 			waitForSteeringMessages: signal => this.#waitForSteeringMessages(signal),
 			hasIrcInterrupts: this.hasIrcInterrupts,
-			getFollowUpMessages: signal => this.#dequeueFollowUpMessagesAfterHooks(signal),
+			getFollowUpMessages: signal => this.#dequeueFollowUpMessagesAfterHooks(signal ?? loopSignal),
 			getAsideMessages: async () => (await this.#asideMessageProvider?.()) ?? [],
 			onBeforeYield: () => this.#onBeforeYield?.(),
 			telemetry: this.#telemetry,
@@ -1530,6 +1676,7 @@ export class Agent {
 				: agentLoopContinue(context, config, loopSignal, this.streamFn);
 
 			for await (const event of stream) {
+				if (this.#abortController !== loopAbortController) return;
 				if (event.type === "turn_start") turnOpen = true;
 				if (event.type === "turn_end") turnOpen = false;
 				// Update internal state based on events
@@ -1600,6 +1747,7 @@ export class Agent {
 				}
 			}
 		} catch (err) {
+			if (this.#abortController !== loopAbortController) return;
 			const stoppedForAbort = loopSignal.aborted;
 			const errorMessage = stoppedForAbort
 				? abortReasonText(loopSignal)
@@ -1704,6 +1852,7 @@ export class Agent {
 				this.#emit({ type: "agent_end", messages: [errorMsg] });
 			}
 		} finally {
+			this.#restoreUndeliveredQueuedMessages(loopAbortController);
 			resolveRun?.();
 			if (this.#abortController === loopAbortController) {
 				this.#state.isStreaming = false;
@@ -1751,29 +1900,25 @@ export class Agent {
 	 * multi-text turns, producing duplicated text on replay.
 	 */
 	async #emitCursorSplitAssistantMessage(assistantMessage: AssistantMessage): Promise<void> {
-		// Snapshot and detach immediately so a still-pending `cursorOnToolResult`
-		// cannot push into a drained buffer. Entries already reserved stay paired
-		// with their toolCall.
 		const buffer = this.#cursorToolResultBuffer;
 		this.#cursorToolResultBuffer = [];
+		this.#cursorToolResultDrain = buffer;
+		try {
+			// Keep the detached batch observable while its transforms finish.
+			const pending = buffer.filter(entry => entry.pending !== undefined).map(entry => entry.pending);
+			if (pending.length > 0) await Promise.all(pending);
 
-		// Await any transformer still running for a reserved entry before reading
-		// its payload. The provider dispatches with `void handleServerMessage(…)`,
-		// so a `message_end` from the same chunk can reach this point while a
-		// transformer is mid-flight; without the await its rewrite would land on
-		// the detached entry after the original was already appended and emitted.
-		// Each `pending` swallows its own rejection, so this cannot throw.
-		const pending = buffer.filter(entry => entry.pending !== undefined).map(entry => entry.pending);
-		if (pending.length > 0) await Promise.all(pending);
-
-		this.#state.streamMessage = null;
-		this.appendMessage(assistantMessage);
-		this.#emit({ type: "message_end", message: assistantMessage });
+			this.#state.streamMessage = null;
+			this.appendMessage(assistantMessage);
+			this.#emit({ type: "message_end", message: assistantMessage });
 
-		for (const { toolResult } of buffer) {
-			this.#emit({ type: "message_start", message: toolResult });
-			this.appendMessage(toolResult);
-			this.#emit({ type: "message_end", message: toolResult });
+			for (const { toolResult } of buffer) {
+				this.#emit({ type: "message_start", message: toolResult });
+				this.appendMessage(toolResult);
+				this.#emit({ type: "message_end", message: toolResult });
+			}
+		} finally {
+			this.#cursorToolResultDrain = undefined;
 		}
 	}
 }

package/src/append-only-context.ts

@@ -14,7 +14,9 @@
  *    message delta is a cache miss each turn.
  */
 
+import type { AgentTool } from "./types";
 import type { Context, Message, Tool } from "@linxiraos/pi-ai";
+import { toolWireSchema } from "@linxiraos/pi-ai";
 import { normalizeTools } from "./agent-loop";
 import { messageEstimateVersion } from "./compaction/message-cache";
 import type { AgentContext, AgentMessage } from "./types";
@@ -23,6 +25,52 @@ import type { AgentContext, AgentMessage } from "./types";
 // StablePrefix (formerly ImmutablePrefix)
 // ---------------------------------------------------------------------------
 
+/**
+ * Cheap per-tool wire-identity key: every field normalizeTools and
+ * computeFingerprint read. The resolved parameters contribute by object
+ * identity — the wire-schema memo is stamp-keyed on the parameters object,
+ * so identity equals normalized bytes (modulo intent injection, a pure
+ * function of the mode flags compared separately). `customFormat` and
+ * `examples` contribute by reference: both are treated as immutable config
+ * (a registry swap replaces the object), matching how the snapshot consumes
+ * them. `intent` functions are compared by reference — same closure means
+ * same mode resolution.
+ */
+function toolKeyForPrefix(tool: AgentTool): string {
+	const params = toolWireSchema(tool);
+	const customFormat = tool.customFormat;
+	const examples = (tool as { examples?: unknown }).examples;
+	// Identity strings for objects (Map-assigned ids, no string-build cost
+	// on the hot path beyond the first sighting per object).
+	return [
+		tool.name ?? "",
+		tool.description ?? "",
+		String(tool.strict ?? ""),
+		tool.customWireName ?? "",
+		typeof tool.intent === "function" ? `fn:${objectId(tool.intent)}` : `mode:${tool.intent ?? "require"}`,
+		objectId(params),
+		objectId(customFormat),
+		objectId(examples),
+	].join("\u0000");
+}
+
+const objectIds = new WeakMap<object, number>();
+let nextObjectId = 1;
+
+function objectId(obj: unknown): number {
+	if (obj === null || obj === undefined || (typeof obj !== "object" && typeof obj !== "function")) {
+		// Primitives contribute by value below via String(); the id path is
+		// only for reference-identity comparison of config objects.
+		return 0;
+	}
+	let id = objectIds.get(obj);
+	if (id === undefined) {
+		id = nextObjectId++;
+		objectIds.set(obj, id);
+	}
+	return id;
+}
+
 /** Frozen system prompt + tool spec snapshot. */
 export interface StablePrefixSnapshot {
 	systemPrompt: string[];
@@ -63,10 +111,42 @@ export class StablePrefix {
 	/**
 	 * Build or rebuild from live context.
 	 * Returns `true` if the prefix actually changed (cache miss imminent).
+	 *
+	 * Steady-state fast path: when the live prompt reference is unchanged
+	 * AND every tool resolves to the same normalized parameters identity as
+	 * last build, the fingerprint cannot have changed, so the full snapshot
+	 * + stringify is skipped. Comparing resolved parameters (not the tool
+	 * container) is load-bearing: tools like ReadTool expose `parameters` as
+	 * a getter over live settings (`skillful`, `memory.backend`), so the
+	 * schema can swap under stable tool references when a setting toggles.
+	 * Any other in-place mutation must go through `invalidate()`.
 	 */
+	#lastPrompt: readonly string[] | undefined;
+	// Joined prompt bytes snapshot: the prompt array is caller-owned and
+	// mutable in place (Agent.setSystemPrompt stores the caller's array;
+	// anyone holding it can push/splice), so reference equality alone cannot
+	// prove the bytes are unchanged. Compared by value on the fast path.
+	#lastPromptText: string | undefined;
+	// Per-tool wire-identity snapshot: every field normalizeTools and
+	// computeFingerprint read (name, description, resolved parameters,
+	// strict, customFormat, customWireName, intent mode, examples
+	// reference). A registry swap that keeps name/description/parameters
+	// but changes any of these must miss the fast path.
+	#lastToolKey: readonly string[] | undefined;
+	#lastIntentTracing: boolean | undefined;
+	#lastPruneToolDescriptions: boolean | undefined;
+
 	build(context: AgentContext, options: BuildOptions): boolean {
+		const prev = this.#snapshot;
+		if (prev !== null && this.#fastPathHit(context, options)) {
+			return false;
+		}
 		const snapshot = takeSnapshot(context, options);
-		if (this.#snapshot && this.#snapshot.fingerprint === snapshot.fingerprint) {
+		this.#recordFastPathKey(context, options, snapshot.tools);
+		if (prev && prev.fingerprint === snapshot.fingerprint) {
+			// Identity changed but bytes did not (e.g. equivalent rebuild):
+			// keep serving the cached snapshot so downstream memo identity
+			// (stamp-keyed schema caches) stays stable.
 			return false;
 		}
 		this.#snapshot = snapshot;
@@ -74,9 +154,50 @@ export class StablePrefix {
 		return true;
 	}
 
+	/** True when the cheap key matches: prompt + per-tool resolved identity. */
+	#fastPathHit(context: AgentContext, options: BuildOptions): boolean {
+		if (
+			this.#lastIntentTracing !== options.intentTracing ||
+			this.#lastPruneToolDescriptions !== options.pruneToolDescriptions
+		) {
+			return false;
+		}
+		// Prompt by reference first (steady state), then by joined bytes so
+		// an in-place push/splice of the same array still misses.
+		if (this.#lastPrompt !== context.systemPrompt) return false;
+		if (this.#lastPromptText !== undefined) {
+			const text = context.systemPrompt.join("\u0000");
+			if (text !== this.#lastPromptText) return false;
+		}
+		const tools = context.tools ?? [];
+		if (this.#lastToolKey === undefined || this.#lastToolKey.length !== tools.length) {
+			return false;
+		}
+		for (let i = 0; i < tools.length; i++) {
+			if (this.#lastToolKey[i] !== toolKeyForPrefix(tools[i]!)) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	#recordFastPathKey(context: AgentContext, options: BuildOptions, normalized: Tool[]): void {
+		this.#lastPrompt = context.systemPrompt;
+		this.#lastPromptText = context.systemPrompt.join("\u0000");
+		this.#lastIntentTracing = options.intentTracing;
+		this.#lastPruneToolDescriptions = options.pruneToolDescriptions;
+		this.#lastToolKey = (context.tools ?? []).map(tool => toolKeyForPrefix(tool));
+		void normalized;
+	}
+
 	/** Force rebuild on the next `build()` call. */
 	invalidate(): void {
 		this.#snapshot = null;
+		this.#lastPrompt = undefined;
+		this.#lastPromptText = undefined;
+		this.#lastToolKey = undefined;
+		this.#lastIntentTracing = undefined;
+		this.#lastPruneToolDescriptions = undefined;
 	}
 
 	/**