@oh-my-pi/pi-agent-core 18.4.1 → 18.4.3

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [18.4.3] - 2026-09-28
+
+### Added
+
+- Added `transformAssistantMessagePreservesToolCalls`, letting stream speculation and direct speculative candidates run under a `transformAssistantMessage` that never rewrites streamed tool calls
+- Added `authorizeLaunch` to the speculative execution host and coordinator so tool stream sessions can start host-approved effectful work (e.g. subagents) before their call dispatches
+
+### Fixed
+
+- Fixed auto-compaction with the `remote` method failing on long Codex/OpenAI sessions with "Remote compaction input exceeds the context window" ([#13611](https://github.com/can1357/oh-my-pi/issues/13611))
+- Fixed passive tool-call context being repeated when several calls in one batch returned the same text; identical per-call context is now delivered once, at its first position ([#13633](https://github.com/can1357/oh-my-pi/pull/13633) by [@andrebrait](https://github.com/andrebrait))
+
+## [18.4.2] - 2026-09-28
+
+### Added
+
+- Added tool_execution_end events that fire as each tool call settles for live UI updates
+
+### Changed
+
+- Emitted tool result messages in the order of tool calls, preserving call order regardless of completion order
+- Reduced repeated token-counting work with a bounded, model-scoped cache of exact text and short-message fragment counts.
+
+### Fixed
+
+- Fixed an issue where streaming tool call arguments could be incorrectly modified in-place
+
 ## [18.4.1] - 2026-09-28
 
 ### Fixed

package/dist/types/agent.d.ts

@@ -221,6 +221,8 @@ export interface AgentOptions {
      * tool-call arguments). See {@link AgentLoopConfig.transformAssistantMessage}.
      */
     transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+    /** See {@link AgentLoopConfig.transformAssistantMessagePreservesToolCalls}. */
+    transformAssistantMessagePreservesToolCalls?: boolean;
     /**
      * Opt-in OpenTelemetry instrumentation. Passing `{}` enables the loop's
      * GenAI-semantic-convention spans using the global tracer provider. See
@@ -257,6 +259,8 @@ export declare class Agent {
      * UI emission, and tool dispatch. Reassign at any time to swap the implementation.
      */
     transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+    /** Declares {@link transformAssistantMessage} never rewrites streamed tool calls; reassign alongside it. */
+    transformAssistantMessagePreservesToolCalls?: boolean;
     /**
      * Hook that peeks whether interrupting IRC asides are queued for the next boundary.
      */

package/dist/types/speculative-execution.d.ts

@@ -1,5 +1,5 @@
 import { type AssistantMessage } from "@oh-my-pi/pi-ai";
-import type { AgentContext, AgentLoopConfig, AgentTool, AgentToolCall, AgentToolResult, SpeculativeChildDefinition, SpeculativeChildHandle, SpeculativeToolExecutionConfig, ToolSpeculationEffect, ToolSpeculationStreamSession } from "./types.js";
+import type { AgentContext, AgentLoopConfig, AgentTool, AgentToolCall, AgentToolResult, SpeculativeAuthorization, SpeculativeChildDefinition, SpeculativeChildHandle, SpeculativeLaunchContext, SpeculativeToolExecutionConfig, ToolSpeculationEffect, ToolSpeculationStreamSession } from "./types.js";
 export type SpeculativeRawOutcome = {
     result: AgentToolResult<unknown>;
     isError: boolean;
@@ -55,6 +55,7 @@ export declare class SpeculativeOperationCoordinator {
      */
     directExecutionArgsFor(toolCallId: string, rawArgs: Readonly<Record<string, unknown>>): Record<string, unknown> | undefined;
     reconcileFinalCalls(calls: ReadonlyMap<string, AgentToolCall>): Promise<void>;
+    authorizeLaunch(context: SpeculativeLaunchContext): Promise<SpeculativeAuthorization>;
     discardChildren(parentToolCallId: string, reason: string): Promise<void>;
     claim(tool: AgentTool | undefined, toolCall: AgentToolCall, args: Record<string, unknown>): Promise<SpeculativeRawOutcome | undefined>;
     admitFinalized(context: AgentContext, toolCall: AgentToolCall, loopConfig: AgentLoopConfig, signal: AbortSignal | undefined): void;

package/dist/types/tool-context.d.ts

@@ -20,8 +20,9 @@ export type ToolResultWithAdditionalContext = ToolResultMessage & {
  */
 export declare function isNonBlankContext(value: unknown): value is string;
 /**
- * Join passive context values in order, dropping blanks. Returns undefined
- * when nothing remains.
+ * Join passive context values in order, dropping blanks and repeats of an
+ * earlier value (compared without surrounding whitespace; the first original
+ * is kept). Returns undefined when nothing remains.
  */
 export declare function joinAdditionalContext(values: Iterable<string | undefined>): string | undefined;
 /**

package/dist/types/types.d.ts

@@ -515,6 +515,13 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * the turn).
      */
     transformAssistantMessage?: (message: AssistantMessage, signal?: AbortSignal) => Promise<void> | void;
+    /**
+     * Declares that {@link transformAssistantMessage} never rewrites or removes a
+     * tool call the model streamed (it may edit text or append new calls). Stream
+     * speculation sessions and direct speculative candidates plan from streamed
+     * calls, so they stay disabled under a transform unless this is set.
+     */
+    transformAssistantMessagePreservesToolCalls?: boolean;
     /**
      * Called after a tool finishes executing, before `tool_execution_end` and the
      * tool-result message are emitted.
@@ -659,8 +666,22 @@ export interface SpeculativeExecutionHost {
     validate?(context: SpeculativeCommitContext): boolean | Promise<boolean>;
     commit?(context: SpeculativeCommitContext, commitDefault: () => Promise<AgentToolResult<unknown>>): Promise<SpeculativeCommitDecision>;
     discard?(context: SpeculativeDiscardContext): void | Promise<void>;
+    /**
+     * Authorize a stream session to start effectful work (e.g. subagents) from
+     * partially streamed arguments. The session owns that work and must abort it
+     * when the finalized call is invalid, blocked, or changed. Hosts without this
+     * hook deny every launch.
+     */
+    authorizeLaunch?(context: SpeculativeLaunchContext): SpeculativeAuthorization | Promise<SpeculativeAuthorization>;
     close?(reason: string): void | Promise<void>;
 }
+/** Effectful work a tool-owned stream session asks to start before its outer call dispatches. */
+export interface SpeculativeLaunchContext {
+    tool: SpeculativeToolReference;
+    toolCall: AgentToolCall;
+    /** Arguments the launch was planned from: the streamed prefix of the outer call. */
+    args: Readonly<Record<string, unknown>>;
+}
 export interface ToolSpeculationStreamContext {
     readonly coordinator: SpeculativeOperationSink;
     readonly parentToolCallId: string;
@@ -703,6 +724,8 @@ export interface ToolSpeculationStreamSession {
 export interface SpeculativeOperationSink {
     readonly maxInFlight: number;
     admit(definition: SpeculativeChildDefinition): Promise<SpeculativeChildHandle | undefined>;
+    /** Host-gated permission for effectful stream work; see {@link SpeculativeExecutionHost.authorizeLaunch}. */
+    authorizeLaunch?(context: SpeculativeLaunchContext): Promise<SpeculativeAuthorization>;
     discardChildren?(parentToolCallId: string, reason: string): void | Promise<void>;
     close(reason: string): void | Promise<void>;
 }
@@ -755,7 +778,8 @@ export interface SpeculativeToolExecutionConfig {
  * ignored when `block` is true.
  *
  * Set `additionalContext` to attach passive model-visible context to this call.
- * Non-empty values from a tool batch are injected in assistant tool-call order
+ * Non-empty values from a tool batch are injected in assistant tool-call order,
+ * a value identical to an earlier one in the batch only once,
  * after every result settles and before the next provider request. It is
  * dropped when the call is blocked or skipped, or when its final result is an
  * error (including an approval denial raised by the tool's own gate). Within a

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.4.1",
+	"version": "18.4.3",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -38,16 +38,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.4.1",
-		"@oh-my-pi/pi-catalog": "18.4.1",
-		"@oh-my-pi/pi-natives": "18.4.1",
-		"@oh-my-pi/pi-utils": "18.4.1",
-		"@oh-my-pi/pi-wire": "18.4.1",
-		"@oh-my-pi/snapcompact": "18.4.1",
+		"@oh-my-pi/pi-ai": "18.4.3",
+		"@oh-my-pi/pi-catalog": "18.4.3",
+		"@oh-my-pi/pi-natives": "18.4.3",
+		"@oh-my-pi/pi-utils": "18.4.3",
+		"@oh-my-pi/pi-wire": "18.4.3",
+		"@oh-my-pi/snapcompact": "18.4.3",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.4.1",
+		"@oh-my-pi/omptype": "18.4.3",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -51,7 +51,7 @@ import {
 	recoverHarmonyToolCall,
 	signalListLabel,
 } from "@oh-my-pi/pi-ai/utils/harmony-leak";
-import { logger, sanitizeText, structuredCloneJSON } from "@oh-my-pi/pi-utils";
+import { cloneJsonTree, logger, sanitizeText, structuredCloneJSON } from "@oh-my-pi/pi-utils";
 import { INTENT_FIELD } from "@oh-my-pi/pi-wire";
 import { LiveSteeringChannel } from "./live-steering";
 import { agentPauseGate } from "./pause";
@@ -377,13 +377,17 @@ function snapshotAssistantContentBlock(block: AssistantContentBlock): AssistantC
 		case "redactedThinking":
 			return { ...block };
 		case "anthropicServerTool":
-			return { ...block, block: structuredCloneJSON(block.block) };
+			return { ...block, block: cloneJsonTree(block.block) };
 		case "fallback":
 			return { ...block, from: { ...block.from }, to: { ...block.to } };
 		case "toolCall": {
 			const snap = {
 				...block,
-				arguments: structuredCloneJSON(block.arguments),
+				// Providers mutate streaming arguments in place (owned-stream, GLM)
+				// as well as replacing them, so containers are always copied; the
+				// strings inside are immutable and shared, keeping the per-delta
+				// cost independent of the argument payload size.
+				arguments: cloneJsonTree(block.arguments),
 				providerMetadata: snapshotToolCallProviderMetadata(block.providerMetadata),
 			};
 			// Object spread copies enumerable symbols in Bun, but the Cursor
@@ -2094,6 +2098,8 @@ async function streamAssistantResponse(
 						signal: requestSignal,
 					})
 				: undefined;
+			const speculationPlansFromStream =
+				!config.transformAssistantMessage || config.transformAssistantMessagePreservesToolCalls === true;
 
 			let providerStreamSettled = false;
 			let speculationSettled = false;
@@ -2323,15 +2329,11 @@ async function streamAssistantResponse(
 						case "toolcall_delta":
 						case "toolcall_end":
 							if (partialMessage) {
-								if (
-									event.type === "toolcall_start" &&
-									speculationCoordinator &&
-									!config.transformAssistantMessage
-								) {
+								if (event.type === "toolcall_start" && speculationCoordinator && speculationPlansFromStream) {
 									// 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.
+									// that may rewrite calls, 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") {
@@ -2428,7 +2430,7 @@ async function streamAssistantResponse(
 								event.type === "toolcall_end" &&
 								speculationCoordinator &&
 								speculationConfig &&
-								!config.transformAssistantMessage
+								speculationPlansFromStream
 							) {
 								speculationCoordinator.admitFinalized(context, event.toolCall, config, requestSignal);
 							}
@@ -3027,6 +3029,11 @@ async function speculativeFinalCalls(
 /**
  * Execute tool calls from an assistant message. Returns model-visible context
  * only after every result has settled, preserving assistant call order.
+ *
+ * `tool_execution_end` fires as each call settles so live UI updates promptly;
+ * result `message_start`/`message_end` events (which append to agent state and
+ * the persisted session) are held until every earlier call has a result, so
+ * history always pairs results in call order regardless of completion order.
  */
 async function executeToolCalls(
 	currentContext: AgentContext,
@@ -3213,6 +3220,18 @@ async function executeToolCalls(
 		await checkAsideInterrupts();
 	};
 
+	// Index of the first record whose result message has not been emitted yet.
+	let nextResultIndex = 0;
+	const flushResultMessages = (): void => {
+		for (; nextResultIndex < records.length; nextResultIndex++) {
+			const message = records[nextResultIndex].toolResultMessage;
+			if (!message) return;
+			emittedToolResults.push(message);
+			stream.push({ type: "message_start", message });
+			stream.push({ type: "message_end", message });
+		}
+	};
+
 	const emitToolResult = (record: (typeof records)[number], result: AgentToolResult<any>, isError: boolean): void => {
 		if (record.resultEmitted) return;
 		const { toolCall } = record;
@@ -3248,10 +3267,7 @@ async function executeToolCalls(
 		record.isError = isError;
 		record.toolResultMessage = toolResultMessage;
 		record.resultEmitted = true;
-		emittedToolResults.push(toolResultMessage);
-
-		stream.push({ type: "message_start", message: toolResultMessage });
-		stream.push({ type: "message_end", message: toolResultMessage });
+		flushResultMessages();
 	};
 
 	const runTool = async (record: (typeof records)[number], index: number): Promise<void> => {

package/src/agent.ts

@@ -346,6 +346,8 @@ export interface AgentOptions {
 	 * tool-call arguments). See {@link AgentLoopConfig.transformAssistantMessage}.
 	 */
 	transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+	/** See {@link AgentLoopConfig.transformAssistantMessagePreservesToolCalls}. */
+	transformAssistantMessagePreservesToolCalls?: boolean;
 
 	/**
 	 * Opt-in OpenTelemetry instrumentation. Passing `{}` enables the loop's
@@ -511,6 +513,8 @@ export class Agent {
 	 * UI emission, and tool dispatch. Reassign at any time to swap the implementation.
 	 */
 	transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+	/** Declares {@link transformAssistantMessage} never rewrites streamed tool calls; reassign alongside it. */
+	transformAssistantMessagePreservesToolCalls?: boolean;
 	/**
 	 * Hook that peeks whether interrupting IRC asides are queued for the next boundary.
 	 */
@@ -576,6 +580,7 @@ export class Agent {
 		this.beforeToolCall = opts.beforeToolCall;
 		this.afterToolCall = opts.afterToolCall;
 		this.transformAssistantMessage = opts.transformAssistantMessage;
+		this.transformAssistantMessagePreservesToolCalls = opts.transformAssistantMessagePreservesToolCalls;
 		this.#telemetry = opts.telemetry;
 		this.#appendOnlyContext = opts.appendOnlyContext;
 		this.#transformProviderContext = opts.transformProviderContext;
@@ -1750,6 +1755,7 @@ export class Agent {
 			transformAssistantMessage: this.transformAssistantMessage
 				? (message, signal) => this.transformAssistantMessage?.(message, signal)
 				: undefined,
+			transformAssistantMessagePreservesToolCalls: this.transformAssistantMessagePreservesToolCalls,
 			onAssistantMessageEvent: this.#onAssistantMessageEvent,
 			onHarmonyLeak: this.#onHarmonyLeak,
 			onTurnEnd: (messages, signal, context) => this.#onTurnEnd?.(messages, signal, context),

package/src/compaction/openai.ts

@@ -110,6 +110,10 @@ function normalizeRemoteCompactionEstimateValue(value: unknown): NormalizedEstim
 	const normalized: Record<string, unknown> = {};
 	let imageTokens = 0;
 	for (const [key, item] of Object.entries(record)) {
+		// Opaque encrypted reasoning/compaction state: its local base64 size far
+		// exceeds what the provider bills, so it stays out of the fit estimate
+		// (same policy as `MessageCountOptions.excludeEncryptedReasoning`).
+		if (key === "encrypted_content" && typeof item === "string") continue;
 		const result = normalizeRemoteCompactionEstimateValue(item);
 		normalized[key] = result.value;
 		imageTokens += result.imageTokens;
@@ -137,9 +141,10 @@ interface RemoteCompactionBudgetProbe {
 /**
  * Cheap-first sizing of a remote-compaction request. Images and the request
  * frame are charged flat, so they come off the budget rather than through the
- * tokenizer; the serialized transcript is then probed with
- * {@link Tokenizer.checkTokenBudget}, which only pays for an exact count when
- * the byte bound cannot already prove the request fits.
+ * tokenizer; opaque `encrypted_content` payloads are excluded. The serialized
+ * transcript is then probed with {@link Tokenizer.checkTokenBudget}, which only
+ * pays for an exact count when the byte bound cannot already prove the request
+ * fits.
  */
 function probeRemoteCompactionInputBudget(
 	input: Array<Record<string, unknown>>,

package/src/speculative-execution.ts

@@ -10,6 +10,7 @@ import type {
 	SpeculativeChildDefinition,
 	SpeculativeChildHandle,
 	SpeculativeCommitContext,
+	SpeculativeLaunchContext,
 	SpeculativeOperationContext,
 	SpeculativePhysicalOutcome,
 	SpeculativeResourceAccess,
@@ -520,6 +521,17 @@ export class SpeculativeOperationCoordinator {
 		}
 	}
 
+	async authorizeLaunch(context: SpeculativeLaunchContext): Promise<SpeculativeAuthorization> {
+		if (this.#closed) return { allowed: false, reason: "speculation coordinator is closed" };
+		const authorize = this.config.host?.authorizeLaunch;
+		if (!authorize) return { allowed: false, reason: "host does not authorize speculative launches" };
+		try {
+			return await authorize.call(this.config.host, context);
+		} catch {
+			return { allowed: false, reason: "host launch authorization failed" };
+		}
+	}
+
 	async discardChildren(parentToolCallId: string, reason: string): Promise<void> {
 		await this.#admission;
 		await Promise.all(

package/src/tokenizer.ts

@@ -1,7 +1,8 @@
 import type { Model } from "@oh-my-pi/pi-ai";
 import type { ModelTokenizer } from "@oh-my-pi/pi-catalog/types";
 import * as natives from "@oh-my-pi/pi-natives";
-import { stringifyJson } from "@oh-my-pi/pi-utils";
+import { materializeString, stringifyJson } from "@oh-my-pi/pi-utils";
+import { LRUCache } from "@oh-my-pi/pi-utils/lru";
 import * as snapcompact from "@oh-my-pi/snapcompact";
 import { isEstimateCacheable, messageEstimateVersion } from "./compaction/message-cache";
 import type { AgentMessage } from "./types";
@@ -67,13 +68,43 @@ interface NativeTokenCount {
 	exact: boolean;
 }
 
+// Growing streamed text and large tool results must not evict the reusable
+// short fragments. Account for UTF-16 key storage plus a per-entry allowance.
+const NATIVE_CACHE_MAX_LENGTH = 16 * 1024;
+
+function countNativeFragment(
+	text: string,
+	encoding: natives.Encoding | null | undefined,
+	counts: LRUCache<string, number>,
+): number {
+	if (text.length > NATIVE_CACHE_MAX_LENGTH) return natives.countTokens(text, encoding);
+	const cached = counts.get(text);
+	if (cached !== undefined) return cached;
+	const tokens = natives.countTokens(text, encoding);
+	// Detach sliced strings so a small key cannot retain a much larger source.
+	counts.set(materializeString(text), tokens);
+	return tokens;
+}
+
 function countTokensNat(
 	text: string | string[],
 	encoding: natives.Encoding | null | undefined,
 	mode: TokenCountMode,
+	counts: LRUCache<string, number>,
 ): NativeTokenCount {
 	try {
-		return { tokens: natives.countTokens(text, encoding), exact: true };
+		let tokens: number;
+		if (typeof text === "string") {
+			tokens = countNativeFragment(text, encoding, counts);
+		} else if (text.length > 0 && text.length < 16) {
+			// The native API sums independent fragments, not their concatenation.
+			// Keep its parallel batch path for arrays of 16 or more fragments.
+			tokens = 0;
+			for (const fragment of text) tokens += countNativeFragment(fragment, encoding, counts);
+		} else {
+			tokens = natives.countTokens(text, encoding);
+		}
+		return { tokens, exact: true };
 	} catch (error) {
 		if (
 			!(error instanceof Error) ||
@@ -131,6 +162,13 @@ interface MessageEstimate {
 export class Tokenizer {
 	readonly #encoding: natives.Encoding | null;
 
+	/** Exact counts only; byte fallbacks remain mode-dependent and uncached. */
+	readonly #nativeCounts = new LRUCache<string, number>({
+		max: 256,
+		maxSize: 512 * 1024,
+		sizeCalculation: (_tokens, text) => text.length * 2 + 64,
+	});
+
 	/**
 	 * Per-message estimate memo. Keyed by message identity, deliberately not a
 	 * symbol-tagged property: callers spread messages to derive throwaway
@@ -150,9 +188,10 @@ export class Tokenizer {
 	}
 
 	countTokens(text: string | string[], mode: TokenCountMode = "approximate"): number {
-		if (mode === "strict") return countTokensNat(text, this.#encoding, mode).tokens;
-		if (!testEnv && this.#encoding !== null) return countTokensNat(text, this.#encoding, mode).tokens;
-		if (accurate) return countTokensNat(text, undefined, mode).tokens;
+		if (mode === "strict") return countTokensNat(text, this.#encoding, mode, this.#nativeCounts).tokens;
+		if (!testEnv && this.#encoding !== null)
+			return countTokensNat(text, this.#encoding, mode, this.#nativeCounts).tokens;
+		if (accurate) return countTokensNat(text, undefined, mode, this.#nativeCounts).tokens;
 		return sumFragments(text, mode === "upperbound" ? byteLength : byteEstimate);
 	}
 
@@ -170,7 +209,7 @@ export class Tokenizer {
 	checkTokenBudget(text: string | string[], budget: number): TokenBudgetCheck {
 		const bound = sumFragments(text, byteLength);
 		if (bound <= budget) return { fits: true, tokens: bound, exact: false };
-		const result = countTokensNat(text, this.#encoding, "strict");
+		const result = countTokensNat(text, this.#encoding, "strict", this.#nativeCounts);
 		return { fits: result.tokens <= budget, tokens: result.tokens, exact: result.exact };
 	}
 

package/src/tool-context.ts

@@ -24,13 +24,19 @@ export function isNonBlankContext(value: unknown): value is string {
 }
 
 /**
- * Join passive context values in order, dropping blanks. Returns undefined
- * when nothing remains.
+ * Join passive context values in order, dropping blanks and repeats of an
+ * earlier value (compared without surrounding whitespace; the first original
+ * is kept). Returns undefined when nothing remains.
  */
 export function joinAdditionalContext(values: Iterable<string | undefined>): string | undefined {
+	const seen = new Set<string>();
 	const kept: string[] = [];
 	for (const value of values) {
-		if (isNonBlankContext(value)) kept.push(value);
+		if (!isNonBlankContext(value)) continue;
+		const key = value.trim();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		kept.push(value);
 	}
 	return kept.length > 0 ? kept.join("\n\n") : undefined;
 }

package/src/types.ts

@@ -595,6 +595,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	transformAssistantMessage?: (message: AssistantMessage, signal?: AbortSignal) => Promise<void> | void;
 
+	/**
+	 * Declares that {@link transformAssistantMessage} never rewrites or removes a
+	 * tool call the model streamed (it may edit text or append new calls). Stream
+	 * speculation sessions and direct speculative candidates plan from streamed
+	 * calls, so they stay disabled under a transform unless this is set.
+	 */
+	transformAssistantMessagePreservesToolCalls?: boolean;
+
 	/**
 	 * Called after a tool finishes executing, before `tool_execution_end` and the
 	 * tool-result message are emitted.
@@ -740,9 +748,24 @@ export interface SpeculativeExecutionHost {
 		commitDefault: () => Promise<AgentToolResult<unknown>>,
 	): Promise<SpeculativeCommitDecision>;
 	discard?(context: SpeculativeDiscardContext): void | Promise<void>;
+	/**
+	 * Authorize a stream session to start effectful work (e.g. subagents) from
+	 * partially streamed arguments. The session owns that work and must abort it
+	 * when the finalized call is invalid, blocked, or changed. Hosts without this
+	 * hook deny every launch.
+	 */
+	authorizeLaunch?(context: SpeculativeLaunchContext): SpeculativeAuthorization | Promise<SpeculativeAuthorization>;
 	close?(reason: string): void | Promise<void>;
 }
 
+/** Effectful work a tool-owned stream session asks to start before its outer call dispatches. */
+export interface SpeculativeLaunchContext {
+	tool: SpeculativeToolReference;
+	toolCall: AgentToolCall;
+	/** Arguments the launch was planned from: the streamed prefix of the outer call. */
+	args: Readonly<Record<string, unknown>>;
+}
+
 export interface ToolSpeculationStreamContext {
 	readonly coordinator: SpeculativeOperationSink;
 	readonly parentToolCallId: string;
@@ -789,6 +812,8 @@ export interface ToolSpeculationStreamSession {
 export interface SpeculativeOperationSink {
 	readonly maxInFlight: number;
 	admit(definition: SpeculativeChildDefinition): Promise<SpeculativeChildHandle | undefined>;
+	/** Host-gated permission for effectful stream work; see {@link SpeculativeExecutionHost.authorizeLaunch}. */
+	authorizeLaunch?(context: SpeculativeLaunchContext): Promise<SpeculativeAuthorization>;
 	discardChildren?(parentToolCallId: string, reason: string): void | Promise<void>;
 	close(reason: string): void | Promise<void>;
 }
@@ -850,7 +875,8 @@ export interface SpeculativeToolExecutionConfig {
  * ignored when `block` is true.
  *
  * Set `additionalContext` to attach passive model-visible context to this call.
- * Non-empty values from a tool batch are injected in assistant tool-call order
+ * Non-empty values from a tool batch are injected in assistant tool-call order,
+ * a value identical to an earlier one in the batch only once,
  * after every result settles and before the next provider request. It is
  * dropped when the call is blocked or skipped, or when its final result is an
  * error (including an approval denial raised by the tool's own gate). Within a