@linxiraos/pi-agent-core 1.1.13 → 1.1.15

package/src/agent-loop.ts

@@ -34,6 +34,7 @@ import * as AIError from "@linxiraos/pi-ai/error";
 import {
 	type CursorExecResolvedCarrier,
 	copyCursorExecResolved,
+	getStreamingPartialJson,
 	kCursorExecResolved,
 } from "@linxiraos/pi-ai/utils/block-symbols";
 import {
@@ -50,6 +51,7 @@ import { logger, sanitizeText, structuredCloneJSON } from "@linxiraos/pi-utils";
 import { INTENT_FIELD } from "@linxiraos/pi-wire";
 import { agentPauseGate } from "./pause";
 import { type AgentRunCoverage, type AgentRunSummary, ToolCallBlockedError } from "./run-collector";
+import { SpeculativeOperationCoordinator } from "./speculative-execution";
 import {
 	type AgentTelemetry,
 	failChatSpan,
@@ -85,9 +87,13 @@ import type {
 	SteeringQueueState,
 	StreamFn,
 } from "./types";
-import { ASIDE_MESSAGE_COMMIT, ASIDE_MESSAGE_DISCARD, isSoftToolRequirement } from "./types";
+import {
+	ASIDE_MESSAGE_COMMIT,
+	ASIDE_MESSAGE_DISCARD,
+	isSoftToolRequirement,
+	SPECULATIVE_STREAM_SESSION,
+} from "./types";
 import { yieldIfDue } from "./utils/yield";
-
 /** Stop-details marker for a provider error after assistant content/tool args already streamed. */
 export const STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL = "stream_interrupted_after_content";
 
@@ -1267,6 +1273,28 @@ async function runLoopBody(
 						hostToolChoice,
 						softRequirementState.forcedToolChoice,
 						preparedProviderCall,
+						message => {
+							const finalToolCalls = message.content.filter(
+								(content): content is Extract<AssistantMessage["content"][number], { type: "toolCall" }> =>
+									content.type === "toolCall" &&
+									(content as CursorExecResolvedCarrier)[kCursorExecResolved] !== true,
+							);
+							if (
+								finalToolCalls.length === 0 ||
+								(message.stopReason !== "toolUse" && message.stopReason !== "stop") ||
+								isDeadlineExceeded(config.deadline)
+							) {
+								return false;
+							}
+							const softGateActive =
+								softRequiredTool !== undefined && !hardToolChoiceBlocks(config.toolChoice, softRequiredTool);
+							return (
+								!softGateActive ||
+								finalToolCalls.every(
+									toolCall => softSatisfies?.(toolCall) ?? toolCall.name === softRequiredTool,
+								)
+							);
+						},
 					);
 					harmonyRetryAttempt = 0;
 					harmonyTruncateResumeCount = 0;
@@ -1404,6 +1432,7 @@ async function runLoopBody(
 
 				const toolResults: ToolResultMessage[] = [];
 				if (softNonCompliant && softRequiredTool !== undefined) {
+					SpeculativeOperationCoordinator.discardForMessage(message, "soft tool requirement deferred execution");
 					if (softRequirementState.escalations >= MAX_SOFT_TOOL_ESCALATIONS) {
 						throw new Error(
 							`Soft tool requirement '${softRequiredTool}' was not satisfied after ${MAX_SOFT_TOOL_ESCALATIONS} forced turns; aborting to avoid an unbounded force loop.`,
@@ -1452,6 +1481,11 @@ async function runLoopBody(
 						newMessages.push(result);
 					}
 				} else if (toolCalls.length > 0) {
+					SpeculativeOperationCoordinator.discardForMessage(
+						message,
+						deadlinePassed ? "deadline exceeded before dispatch" : "final message was not runnable",
+						deadlinePassed ? "aborted" : "discarded",
+					);
 					// Turn ended on a non-runnable reason (`length` truncation) or deadline was exceeded
 					// but left toolCall blocks behind. pair each with a placeholder result.
 					const skipReason = deadlinePassed ? "aborted" : message.stopReason === "length" ? "length" : "skipped";
@@ -1656,6 +1690,7 @@ async function streamAssistantResponse(
 	hostToolChoice?: ToolChoice,
 	forcedToolChoice?: ToolChoice,
 	prepared?: PreparedProviderCall,
+	canDispatchFinalToolCalls?: (message: AssistantMessage) => boolean,
 ): Promise<AssistantMessage> {
 	const providerCall = prepared ?? (await prepareProviderCall(context, config, signal));
 	const { model, context: llmContext, promptToolWireTools, ownedDialect } = providerCall;
@@ -1790,7 +1825,18 @@ async function streamAssistantResponse(
 				}
 				argStreams.clear();
 			};
-
+			const speculationConfig =
+				config.speculativeToolExecution?.enabled === true ? config.speculativeToolExecution : undefined;
+			const speculationCoordinator = speculationConfig
+				? new SpeculativeOperationCoordinator(speculationConfig, {
+						context,
+						loopConfig: config,
+						signal: requestSignal,
+					})
+				: undefined;
+
+			let providerStreamSettled = false;
+			let speculationSettled = false;
 			const responseIterator = response[Symbol.asyncIterator]();
 			const finishAbortedStream = async (): Promise<AssistantMessage> => {
 				try {
@@ -1799,6 +1845,8 @@ async function streamAssistantResponse(
 				} catch {
 					// Provider cancellation failures cannot change the committed aborted message.
 				}
+				await speculationCoordinator?.discardAll("run aborted", "aborted");
+				speculationSettled = true;
 				const aborted = emitAbortedAssistantMessage(
 					partialMessage,
 					addedPartial,
@@ -1840,7 +1888,10 @@ async function streamAssistantResponse(
 					} else {
 						next = await responseIterator.next();
 					}
-					if (next.done) break;
+					if (next.done) {
+						providerStreamSettled = true;
+						break;
+					}
 
 					const event = next.value;
 					if (event.type === "done" || event.type === "error") {
@@ -1872,16 +1923,40 @@ async function streamAssistantResponse(
 						if (config.transformAssistantMessage) {
 							await config.transformAssistantMessage(finalMessage, requestSignal);
 						}
-						// Prepare tool dispatch (validation + the `beforeToolCall` hook)
-						// BEFORE the message is snapshotted for consumers: a hook args
-						// revision is written back into this message's toolCall blocks,
-						// so history, the UI, persistence, provider replay, scheduling,
-						// and execution all carry the revised arguments.
-						if (finalMessage.content.some(c => c.type === "toolCall")) {
-							preparedDispatchByMessage.set(
-								finalMessage,
-								await prepareToolCallDispatch(finalMessage, context, config, requestSignal),
-							);
+						// A pre-dispatch hook may request approval or change external state, so
+						// do not run it until the outer loop has established this tool turn can
+						// actually dispatch. The same gate keeps host-deferred speculation from
+						// being released for truncated, expired, or soft-tool-rejected turns.
+						const finalToolCallsCanDispatch =
+							!requestSignal?.aborted &&
+							(canDispatchFinalToolCalls?.(finalMessage) ??
+								(finalMessage.stopReason !== "error" &&
+									finalMessage.stopReason !== "aborted" &&
+									finalMessage.stopReason !== "length"));
+						const preparedDispatch = finalToolCallsCanDispatch
+							? await prepareToolCallDispatch(finalMessage, context, config, requestSignal)
+							: undefined;
+						if (preparedDispatch?.size) {
+							preparedDispatchByMessage.set(finalMessage, preparedDispatch);
+						}
+						if (speculationCoordinator) {
+							if (!finalToolCallsCanDispatch || !preparedDispatch) {
+								await speculationCoordinator.discardAll(
+									"final message cannot reach tool dispatch",
+									requestSignal?.aborted ? "aborted" : "discarded",
+								);
+							} else {
+								await speculationCoordinator.reconcileFinalCalls(
+									await speculativeFinalCalls(
+										finalMessage,
+										preparedDispatch,
+										config.transformToolCallArguments,
+										speculationCoordinator,
+									),
+								);
+								await speculationCoordinator.finalizeAdmissions();
+								speculationCoordinator.attach(finalMessage);
+							}
 						}
 						if (addedPartial) {
 							context.messages[context.messages.length - 1] = finalMessage;
@@ -1893,6 +1968,8 @@ async function streamAssistantResponse(
 						}
 						stream.push({ type: "message_end", message: snapshotAssistantMessage(finalMessage) });
 						await finishChat(finalMessage);
+						speculationSettled = true;
+						providerStreamSettled = true;
 						return finalMessage;
 					}
 					if (requestSignal?.aborted) {
@@ -1983,8 +2060,69 @@ async function streamAssistantResponse(
 						case "toolcall_delta":
 						case "toolcall_end":
 							if (partialMessage) {
+								if (
+									event.type === "toolcall_start" &&
+									speculationCoordinator &&
+									!config.transformAssistantMessage
+								) {
+									// Stream sessions plan from pre-transform arguments, exactly like
+									// direct candidates (see admitFinalized below): with a transformer
+									// installed the authoritative call may differ, so any speculative
+									// work started from the original would be phantom I/O.
+									speculationCoordinator.register(event.contentIndex);
+									const toolCall = event.partial.content[event.contentIndex];
+									if (toolCall?.type === "toolCall") {
+										const tool = context.tools?.find(candidate => candidate.name === toolCall.name);
+										try {
+											const session = await tool?.speculation?.stream?.open({
+												coordinator: speculationCoordinator,
+												parentToolCallId: toolCall.id,
+											});
+											if (session) {
+												if (!speculationCoordinator.registerStreamSession(toolCall.id, session)) {
+													await session.discard("stream speculation coordinator rejected session");
+												}
+											}
+										} catch {
+											await speculationCoordinator.discardStreamSession(
+												toolCall.id,
+												"stream speculation policy failed to open",
+											);
+										}
+									}
+								}
+								if (event.type === "toolcall_delta") {
+									const toolCall = event.partial.content[event.contentIndex];
+									if (toolCall?.type === "toolCall") {
+										try {
+											await speculationCoordinator
+												?.streamSession(toolCall.id)
+												?.update(toolCall, getStreamingPartialJson(toolCall));
+										} catch {
+											await speculationCoordinator?.discardStreamSession(
+												toolCall.id,
+												"stream speculation update failed",
+											);
+										}
+									}
+								}
 								if (event.type === "toolcall_end") {
 									completedToolCallIds.add(event.toolCall.id);
+									const session = speculationCoordinator?.streamSession(event.toolCall.id);
+									try {
+										await session?.finalize({
+											toolCall: event.toolCall,
+											args:
+												event.toolCall.arguments && typeof event.toolCall.arguments === "object"
+													? (event.toolCall.arguments as Record<string, unknown>)
+													: {},
+										});
+									} catch {
+										await speculationCoordinator?.discardStreamSession(
+											event.toolCall.id,
+											"stream speculation finalize failed",
+										);
+									}
 								}
 								partialMessage = event.partial;
 								context.messages[context.messages.length - 1] = partialMessage;
@@ -2000,39 +2138,94 @@ async function streamAssistantResponse(
 									message: messageSnapshot,
 								});
 							}
+							if (
+								event.type === "toolcall_end" &&
+								speculationCoordinator &&
+								speculationConfig &&
+								!config.transformAssistantMessage
+							) {
+								speculationCoordinator.admitFinalized(context, event.toolCall, config, requestSignal);
+							}
 							break;
 					}
 				}
 			} finally {
 				detachAbortListener?.();
 				cancelArgStreams();
+				if (!providerStreamSettled) {
+					await speculationCoordinator?.discardAll("provider stream failed", "aborted");
+					speculationSettled = true;
+				}
 			}
 
-			let trailing = await response.result();
-			if (harmonyMitigationEnabled) {
-				const detection = detectHarmonyLeakInAssistantMessage(trailing);
-				if (detection) {
-					const recovered = recoverHarmonyToolCall(trailing, detection);
-					const removed = recovered?.removed ?? extractHarmonyRemoved(trailing, detection);
-					if (addedPartial) {
-						emitDiscardedHarmonyPartial(
-							partialMessage,
-							stream,
-							`Discarded after GPT-5 Harmony protocol leakage (${signalListLabel(detection.signals)})`,
+			try {
+				let trailing = await response.result();
+				if (harmonyMitigationEnabled) {
+					const detection = detectHarmonyLeakInAssistantMessage(trailing);
+					if (detection) {
+						const recovered = recoverHarmonyToolCall(trailing, detection);
+						const removed = recovered?.removed ?? extractHarmonyRemoved(trailing, detection);
+						if (addedPartial) {
+							emitDiscardedHarmonyPartial(
+								partialMessage,
+								stream,
+								`Discarded after GPT-5 Harmony protocol leakage (${signalListLabel(detection.signals)})`,
+							);
+							context.messages.pop();
+							addedPartial = false;
+						}
+						throw new HarmonyLeakInterruption(detection, removed, recovered);
+					}
+				}
+				if (config.transformAssistantMessage) {
+					await config.transformAssistantMessage(trailing, requestSignal);
+				}
+				trailing = snapshotAssistantMessage(trailing);
+				const finalToolCallsCanDispatch =
+					!requestSignal?.aborted &&
+					(canDispatchFinalToolCalls?.(trailing) ??
+						(trailing.stopReason !== "error" &&
+							trailing.stopReason !== "aborted" &&
+							trailing.stopReason !== "length"));
+				const preparedDispatch = finalToolCallsCanDispatch
+					? await prepareToolCallDispatch(trailing, context, config, requestSignal)
+					: undefined;
+				if (preparedDispatch?.size) {
+					preparedDispatchByMessage.set(trailing, preparedDispatch);
+				}
+				if (speculationCoordinator) {
+					if (!finalToolCallsCanDispatch || !preparedDispatch) {
+						await speculationCoordinator.discardAll(
+							"final message cannot reach tool dispatch",
+							requestSignal?.aborted ? "aborted" : "discarded",
+						);
+					} else {
+						await speculationCoordinator.reconcileFinalCalls(
+							await speculativeFinalCalls(
+								trailing,
+								preparedDispatch,
+								config.transformToolCallArguments,
+								speculationCoordinator,
+							),
 						);
-						context.messages.pop();
-						addedPartial = false;
+						await speculationCoordinator.finalizeAdmissions();
+						speculationCoordinator.attach(trailing);
 					}
-					throw new HarmonyLeakInterruption(detection, removed, recovered);
 				}
+				if (addedPartial) {
+					context.messages[context.messages.length - 1] = trailing;
+					stream.push({ type: "message_end", message: snapshotAssistantMessage(trailing) });
+				}
+				await finishChat(trailing);
+				speculationSettled = true;
+				providerStreamSettled = true;
+				return trailing;
+			} catch (error) {
+				if (!speculationSettled) {
+					await speculationCoordinator?.discardAll("provider stream finalization failed", "aborted");
+				}
+				throw error;
 			}
-			trailing = snapshotAssistantMessage(trailing);
-			if (addedPartial) {
-				context.messages[context.messages.length - 1] = trailing;
-				stream.push({ type: "message_end", message: snapshotAssistantMessage(trailing) });
-			}
-			await finishChat(trailing);
-			return trailing;
 		});
 	} catch (err) {
 		failChatSpan(telemetry, chatSpan, {
@@ -2236,6 +2429,10 @@ interface PreparedToolCall {
 	tool: AgentTool<any> | undefined;
 	/** Validated (possibly hook-revised) execution args; raw args when validation failed. */
 	args: Record<string, unknown>;
+	/** Transformed args shared by final reconciliation and eventual dispatch. */
+	executionArgs?: Record<string, unknown>;
+	/** Transform failure retained for execution's scheduled error result. */
+	transformError?: unknown;
 	validationErrorMessage?: string;
 	blocked?: boolean;
 	blockReason?: string;
@@ -2264,11 +2461,87 @@ function resolveToolForCall(
 		tools?.find(t => t.name === toolCall.name) ??
 		tools?.find(t => t.customWireName !== undefined && t.customWireName === toolCall.name) ??
 		// Not in the advertised set: let the host route side-transport tools
-		// (e.g. xd:// device mounts) called by their top-level name.
-		resolveFallbackTool?.(toolCall.name)
+		// (e.g. xd:// device mounts) called by their top-level name. It receives
+		// the snapshot searched above, never the agent's live tools, so a
+		// mid-stream roster change cannot widen what this request can reach.
+		resolveFallbackTool?.(toolCall.name, tools ?? [])
 	);
 }
 
+/** Shortest suggestable segment; below this the match is noise (`id`, `to`). */
+const MIN_TOOL_NAME_SUGGESTION_SEGMENT = 3;
+/** Cap on names listed for an ambiguous miss, so the error stays readable. */
+const MAX_TOOL_NAME_SUGGESTIONS = 3;
+
+/**
+ * Tool names sharing a trailing `_`-delimited segment with `name`.
+ *
+ * A model that mis-transcribes a long opaque tool name reliably keeps the
+ * trailing verb — that segment is the only part carrying meaning, while any
+ * leading id segments are high-entropy and mnemonic-free. Matching on it turns
+ * an otherwise dead `not found` into a self-correcting one.
+ *
+ * Both the last `__` and last `_` boundary are tried, so a name that lost only
+ * its separator (`…__resolve_library_id`) and one that lost a whole id segment
+ * (`…__read`) both recover. `fallbackNames` adds targets the host can route but
+ * never advertises (`xd://` device mounts); without them a corrupted device
+ * call is the one miss with nothing to suggest, because the capability exists
+ * in the session yet appears in no advertised name. Purely advisory: this only
+ * builds an error string and never selects a tool, so dispatch semantics are
+ * unchanged.
+ */
+function suggestToolNames(
+	name: string,
+	tools: ReadonlyArray<Pick<AgentTool, "name" | "customWireName">> | undefined,
+	fallbackNames?: Iterable<string>,
+): string[] {
+	const candidates: string[] = [];
+	for (const tool of tools ?? []) {
+		candidates.push(tool.name);
+		if (tool.customWireName !== undefined) candidates.push(tool.customWireName);
+	}
+	// Devices rank after the advertised set: when one verb matches both, the
+	// tool the model was actually offered is the better guess.
+	if (fallbackNames !== undefined) for (const fallbackName of fallbackNames) candidates.push(fallbackName);
+	if (candidates.length === 0) return [];
+	const segments: string[] = [];
+	for (const boundary of ["__", "_"]) {
+		const idx = name.lastIndexOf(boundary);
+		if (idx < 0) continue;
+		const segment = name.slice(idx + boundary.length);
+		if (segment.length >= MIN_TOOL_NAME_SUGGESTION_SEGMENT && !segments.includes(segment)) segments.push(segment);
+	}
+	if (segments.length === 0) return [];
+	// Longest tail first. A distinctive `__` tail (`resolve_library_get`) is a
+	// far stronger signal than the generic `_` tail it contains (`get`), and the
+	// caller truncates the list — so the strongest match has to sort ahead of
+	// however many tools happen to share the weak one.
+	segments.sort((a, b) => b.length - a.length);
+	const matches: string[] = [];
+	for (const segment of segments) {
+		for (const candidate of candidates) {
+			if (candidate === name || matches.includes(candidate)) continue;
+			if (candidate === segment || candidate.endsWith(`_${segment}`)) matches.push(candidate);
+		}
+	}
+	return matches;
+}
+
+/**
+ * `Tool <name> not found`, plus a suggestion when the session holds a plausible
+ * intended target. Exact wording is not a contract; the model reads it.
+ */
+function formatToolNotFoundMessage(
+	name: string,
+	tools: ReadonlyArray<Pick<AgentTool, "name" | "customWireName">> | undefined,
+	fallbackNames?: Iterable<string>,
+): string {
+	const suggestions = suggestToolNames(name, tools, fallbackNames);
+	if (suggestions.length === 0) return `Tool ${name} not found`;
+	if (suggestions.length === 1) return `Tool ${name} not found. Did you mean ${suggestions[0]}?`;
+	return `Tool ${name} not found. Closest available: ${suggestions.slice(0, MAX_TOOL_NAME_SUGGESTIONS).join(", ")}`;
+}
+
 /**
  * Pre-dispatch phase for every pending tool call on `assistantMessage`, run in
  * call order: intent extraction, argument validation, and the `beforeToolCall`
@@ -2285,7 +2558,7 @@ async function prepareToolCallDispatch(
 	config: AgentLoopConfig,
 	signal: AbortSignal | undefined,
 ): Promise<Map<string, PreparedToolCall>> {
-	const { resolveFallbackTool, intentTracing, beforeToolCall } = config;
+	const { resolveFallbackTool, suggestFallbackToolNames, intentTracing, beforeToolCall } = config;
 	const prepared = new Map<string, PreparedToolCall>();
 	for (const toolCall of assistantMessage.content) {
 		if (toolCall.type !== "toolCall") continue;
@@ -2312,7 +2585,9 @@ async function prepareToolCallDispatch(
 		}
 		const validate = (args: Record<string, unknown>): Record<string, unknown> | undefined => {
 			try {
-				if (!tool) throw new Error(`Tool ${toolCall.name} not found`);
+				if (!tool) {
+					throw new Error(formatToolNotFoundMessage(toolCall.name, context.tools, suggestFallbackToolNames?.()));
+				}
 				return validateToolArguments(tool, { ...toolCall, arguments: args });
 			} catch (validationError) {
 				if (tool?.lenientArgValidation) {
@@ -2361,6 +2636,76 @@ async function prepareToolCallDispatch(
 	}
 	return prepared;
 }
+
+/**
+ * Final calls that can still reach tool execution after pre-dispatch policy.
+ * Omitting a call is deliberate: reconciliation discards its direct candidate
+ * and streamed children before final admission can release deferred work.
+ */
+function transformedExecutionArgs(
+	prepared: PreparedToolCall,
+	toolCall: AgentToolCall,
+	transformToolCallArguments: AgentLoopConfig["transformToolCallArguments"],
+): Record<string, unknown> | undefined {
+	if (prepared.transformError !== undefined) return undefined;
+	if (prepared.executionArgs !== undefined) return prepared.executionArgs;
+	try {
+		const args = transformToolCallArguments
+			? transformToolCallArguments(prepared.args, toolCall.name)
+			: prepared.args;
+		prepared.executionArgs = args;
+		return args;
+	} catch (error) {
+		prepared.transformError = error;
+		return undefined;
+	}
+}
+
+async function speculativeFinalCalls(
+	assistantMessage: AssistantMessage,
+	preparedDispatch: ReadonlyMap<string, PreparedToolCall>,
+	transformToolCallArguments: AgentLoopConfig["transformToolCallArguments"],
+	speculationCoordinator: SpeculativeOperationCoordinator | undefined,
+): Promise<Map<string, AgentToolCall>> {
+	// Settle admissions first: a slow assessment would otherwise look like a
+	// missing candidate and force a second transform application below.
+	await speculationCoordinator?.settleAdmissions();
+	const calls = new Map<string, AgentToolCall>();
+	for (const content of assistantMessage.content) {
+		if (content.type !== "toolCall" || (content as CursorExecResolvedCarrier)[kCursorExecResolved] === true) {
+			continue;
+		}
+		const prepared = preparedDispatch.get(content.id);
+		if (
+			!prepared ||
+			prepared.blocked ||
+			prepared.prepareError !== undefined ||
+			prepared.validationErrorMessage !== undefined
+		) {
+			continue;
+		}
+		// Reuse the admission-time transform when the finalized raw call is
+		// unchanged, so a stateful transform runs exactly once end-to-end and
+		// the reconciled path is the path already accessed. Changed raw args
+		// (e.g. a beforeToolCall revision) fall through to a single fresh
+		// transform, leaving the stale candidate for reconciliation to discard.
+		const reused = speculationCoordinator?.directExecutionArgsFor(
+			content.id,
+			content.arguments as Record<string, unknown>,
+		);
+		let executionArgs: Record<string, unknown> | undefined;
+		if (reused !== undefined) {
+			prepared.executionArgs = reused;
+			executionArgs = reused;
+		} else {
+			executionArgs = transformedExecutionArgs(prepared, content, transformToolCallArguments);
+		}
+		if (executionArgs === undefined) continue;
+		calls.set(content.id, { ...content, arguments: executionArgs });
+	}
+	return calls;
+}
+
 /**
  * Execute tool calls from an assistant message.
  */
@@ -2379,8 +2724,10 @@ async function executeToolCalls(
 		hasIrcInterrupts,
 		interruptMode = "immediate",
 		getToolContext,
+
 		transformToolCallArguments,
 		resolveFallbackTool,
+		suggestFallbackToolNames,
 		afterToolCall,
 	} = config;
 	type ToolCallContent = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
@@ -2420,6 +2767,7 @@ async function executeToolCalls(
 	const preparedDispatch =
 		preparedDispatchByMessage.get(assistantMessage) ??
 		(await prepareToolCallDispatch(assistantMessage, currentContext, config, signal));
+	const speculationCoordinator = SpeculativeOperationCoordinator.take(assistantMessage);
 
 	const records = toolCalls.map(toolCall => {
 		const prepared = preparedDispatch.get(toolCall.id) ?? {
@@ -2457,6 +2805,8 @@ async function executeToolCalls(
 			blocked: prepared.blocked === true,
 			blockReason: prepared.blockReason,
 			prepareError: prepared.prepareError,
+			executionArgs: prepared.executionArgs,
+			transformError: prepared.transformError,
 		};
 	});
 
@@ -2637,7 +2987,9 @@ async function executeToolCalls(
 
 		await runInActiveSpan(toolSpan, async () => {
 			try {
-				if (!tool) throw new Error(`Tool ${toolCall.name} not found`);
+				if (!tool) {
+					throw new Error(formatToolNotFoundMessage(toolCall.name, tools, suggestFallbackToolNames?.()));
+				}
 				if (record.signal.aborted) {
 					result = createToolSignalAbortedResult(record.signal);
 					isError = true;
@@ -2648,45 +3000,71 @@ async function executeToolCalls(
 				if (record.blocked) {
 					throw new ToolCallBlockedError(record.blockReason);
 				}
-				const executionArgs = transformToolCallArguments
-					? transformToolCallArguments(effectiveArgs, toolCall.name)
-					: effectiveArgs;
+				if (record.transformError !== undefined) throw record.transformError;
+				const executionArgs =
+					record.executionArgs ??
+					(transformToolCallArguments ? transformToolCallArguments(effectiveArgs, toolCall.name) : effectiveArgs);
 				record.args = executionArgs;
 
-				// The cooperative steering signal rides the loop-owned
-				// ToolCallContext (surfacing as `ctx.toolCall.steeringSignal`):
-				// AgentToolContext itself is app-built via declaration merging, so
-				// the loop cannot construct or extend one structurally.
-				const toolContext = getToolContext
-					? getToolContext({
-							batchId,
-							index,
-							total: toolCalls.length,
-							toolCalls: toolCallInfos,
-							steeringSignal: steeringSoftController.signal,
-							providerMetadata: toolCall.providerMetadata,
-						})
+				const speculativeOutcome = speculationCoordinator
+					? await speculationCoordinator.claim(tool, toolCall, executionArgs)
 					: undefined;
-				executionStarted = true;
-				const rawResult = await tool.execute(
-					toolCall.id,
-					executionArgs,
-					record.signal,
-					partialResult => {
-						stream.push({
-							type: "tool_execution_update",
-							toolCallId: toolCall.id,
-							toolName: toolCall.name,
-							args: executionArgs,
-							partialResult: coerceToolResult(partialResult).result,
-						});
-					},
-					toolContext,
-				);
-				completedToolExecution = true;
-				const coerced = coerceToolResult(rawResult);
-				result = coerced.result;
-				if (coerced.malformed || result.isError) isError = true;
+				if (speculativeOutcome) {
+					// Normalize exactly like the ordinary execute path below: third-party
+					// speculation policies/hosts may return malformed results (missing or
+					// non-array content) that must never persist verbatim in history.
+					const coerced = coerceToolResult(speculativeOutcome.result);
+					result = coerced.result;
+					if (coerced.malformed || result.isError) isError = true;
+					completedToolExecution = true;
+					executionStarted = true;
+				}
+
+				if (!completedToolExecution) {
+					// The cooperative steering signal rides the loop-owned
+					// ToolCallContext (surfacing as `ctx.toolCall.steeringSignal`):
+					// AgentToolContext itself is app-built via declaration merging, so
+					// the loop cannot construct or extend one structurally.
+					const streamSession = speculationCoordinator?.takeStreamSession(toolCall.id);
+					const toolContext = getToolContext?.({
+						batchId,
+						index,
+						total: toolCalls.length,
+						toolCalls: toolCallInfos,
+						steeringSignal: steeringSoftController.signal,
+						providerMetadata: toolCall.providerMetadata,
+					});
+					if (streamSession && toolContext) {
+						toolContext[SPECULATIVE_STREAM_SESSION] = streamSession;
+					} else if (streamSession && !streamSession.contextIndependent) {
+						await streamSession.discard("outer tool context cannot carry stream speculation");
+					}
+					executionStarted = true;
+					let rawResult: unknown;
+					try {
+						rawResult = await tool.execute(
+							toolCall.id,
+							executionArgs,
+							record.signal,
+							partialResult => {
+								stream.push({
+									type: "tool_execution_update",
+									toolCallId: toolCall.id,
+									toolName: toolCall.name,
+									args: executionArgs,
+									partialResult: coerceToolResult(partialResult).result,
+								});
+							},
+							toolContext,
+						);
+					} finally {
+						await streamSession?.discard("outer tool completed without committing stream speculation");
+					}
+					completedToolExecution = true;
+					const coerced = coerceToolResult(rawResult);
+					result = coerced.result;
+					if (coerced.malformed || result.isError) isError = true;
+				}
 			} catch (e) {
 				caughtError = e;
 				result = {
@@ -2887,6 +3265,7 @@ async function executeToolCalls(
 			emitToolResult(record, createSkippedToolResult(interruptState.source, false), true);
 		}
 	}
+	await speculationCoordinator?.discardAll("candidate was not dispatched");
 
 	return { toolResults: emittedToolResults };
 }