@oh-my-pi/pi-agent-core 18.10.4 → 18.11.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [18.11.0] - 2026-10-14
+
+### Breaking Changes
+
+- Removed `ApprovalDetailsOptions`; `formatApprovalDetails` takes only `args` again, since the compact approval prompt no longer shows tool details ([#15642](https://github.com/can1357/oh-my-pi/pull/15642) by [@H4vC](https://github.com/H4vC))
+
+### Added
+
+- `AgentTool.delegationGuidance`: instructions a same-name extension replacement inherits in its description when it delegates to the native tool ([#15477](https://github.com/can1357/oh-my-pi/pull/15477) by [@iliaal](https://github.com/iliaal))
+- `CompactionPreparation.lastSummarizedEntryId` and `CompactionResult.providerReplayThroughEntryId`: a remote compaction that could only fit the history before the kept tail reports the last entry its native history covers; later entries replay normally ([#15712](https://github.com/can1357/oh-my-pi/pull/15712) by [@H4vC](https://github.com/H4vC))
+
+### Fixed
+
+- Fixed native (OpenAI/Codex) remote compaction refusing or truncating sessions that fit the window: its preflight counted the JSON-escaped request, inflating quote-, backslash- and newline-heavy tool output such as disassembly by ~10–20%; it now counts text as the model reads it ([#15712](https://github.com/can1357/oh-my-pi/pull/15712) by [@H4vC](https://github.com/H4vC))
+- Fixed OpenAI V1/V2 remote compaction failing outright when the history, kept tail included, exceeds the context window (a large final response or tool output after the last check); it retries on the history before the kept tail ([#15712](https://github.com/can1357/oh-my-pi/pull/15712) by [@H4vC](https://github.com/H4vC))
+- Fixed fitted output caps overflowing the context window on strict hosts (llama.cpp-family) after turns with many parallel tool results; chat-template framing is now charged per locally counted message ([#15699](https://github.com/can1357/oh-my-pi/issues/15699))
+- Fixed leaked DeepSeek DSML markup reaching saved history from reasoning blocks and from turns that also made a valid tool call ([#15485](https://github.com/can1357/oh-my-pi/issues/15485))
+
 ## [18.10.4] - 2026-10-13
 
 ### Added

package/dist/types/compaction/compaction.d.ts

@@ -28,6 +28,12 @@ export interface CompactionResult<T = unknown> {
     details?: T;
     /** Hook-provided data to persist alongside compaction entry. */
     preserveData?: Record<string, unknown>;
+    /**
+     * Last entry the provider-native replay history covers. Set when a remote
+     * compaction could only fit the history before the kept tail; later entries
+     * replay normally after the native history.
+     */
+    providerReplayThroughEntryId?: string;
 }
 export interface CompactionSettings {
     enabled: boolean;
@@ -321,6 +327,8 @@ export interface CompactionPreparation {
     recentMessages: AgentMessage[];
     /** Entry IDs parallel to recentMessages, for an Anthropic-safe keep-tail boundary. */
     recentEntryIds?: string[];
+    /** Last entry before the kept tail; a remote compaction that cannot fit the tail covers history through it. */
+    lastSummarizedEntryId?: string;
     /** Whether this is a split turn (cut point in middle of turn) */
     isSplitTurn: boolean;
     tokensBefore: number;

package/dist/types/compaction/openai.d.ts

@@ -31,7 +31,7 @@ export declare const CONTEXT_WINDOW_TRUNCATED_OUTPUT_MESSAGE: string;
 /**
  * Tokens of stored Responses replacement history. Retained `input_image` parts
  * count at their image estimate rather than as base64 text; everything else,
- * opaque compaction state included, counts as serialized.
+ * opaque compaction state included, counts as decoded text.
  */
 export declare function countResponsesHistoryTokens(items: unknown[], tokenizer: Tokenizer): number;
 export interface TrimRemoteCompactionInputResult {
@@ -46,6 +46,15 @@ export interface TrimRemoteCompactionInputResult {
      */
     fits: boolean;
 }
+/** Options for {@link trimRemoteCompactionInputToContextWindow}. */
+export interface TrimRemoteCompactionOptions {
+    /**
+     * Whether oversized trailing tool outputs may be rewritten (default true).
+     * False when a caller can compact a shorter prefix instead, so a kept tool
+     * result replays intact rather than being replaced.
+     */
+    rewriteOutputs?: boolean;
+}
 /**
  * Preserve the full native transcript unless trailing tool outputs alone push a
  * remote compaction request beyond the model window. Replacing only those
@@ -54,7 +63,7 @@ export interface TrimRemoteCompactionInputResult {
  * fits but whose image estimate does not is still sendable: refusing it on an
  * image guess would skip native compaction the provider would have accepted.
  */
-export declare function trimRemoteCompactionInputToContextWindow(input: Array<Record<string, unknown>>, tokenizer: Tokenizer, contextWindow: number | null | undefined, instructions: string, tools?: unknown[]): TrimRemoteCompactionInputResult;
+export declare function trimRemoteCompactionInputToContextWindow(input: Array<Record<string, unknown>>, tokenizer: Tokenizer, contextWindow: number | null | undefined, instructions: string, tools?: unknown[], options?: TrimRemoteCompactionOptions): TrimRemoteCompactionInputResult;
 /**
  * Refuse a native compaction request whose prepared input cannot fit the model
  * window, before any network I/O. Re-expanded history behind an unreadable
@@ -117,6 +126,8 @@ export declare function requestOpenAiRemoteCompaction(model: Model, apiKey: stri
     sessionId?: string;
     providerSessionState?: Map<string, ProviderSessionState>;
     codexCompaction?: CodexCompactionContext;
+    /** Forwarded to {@link trimRemoteCompactionInputToContextWindow}. */
+    rewriteOutputs?: boolean;
 }): Promise<OpenAiRemoteCompactionResponse>;
 /**
  * Generic remote-compaction POST. Two wire shapes are auto-selected by

package/dist/types/output-budget.d.ts

@@ -2,14 +2,22 @@ import type { Context, Model } from "@oh-my-pi/pi-ai";
 import type { Tokenizer } from "./tokenizer.js";
 /** Smallest output cap {@link fitOutputTokensToContextWindow} will request. */
 export declare const MIN_FITTED_OUTPUT_TOKENS = 1024;
+/**
+ * Chat-template framing charged per locally counted message. `Tokenizer.countMessage`
+ * counts content only, but every template wraps each message in role markers and
+ * separators, and tool results in response wrappers: about 5 tokens per merged
+ * Qwen3 `<tool_response>` or Llama 3 turn, 10–15 for harmony or Mistral tool results.
+ * The proportional margin scales with content, so many short messages (a turn's
+ * parallel tool results) leave this uncovered. Provider-anchored messages need no
+ * charge: the host's own report already includes their framing.
+ */
+export declare const MESSAGE_FRAMING_TOKENS = 16;
 /**
  * Absolute headway subtracted from the remaining room (unconditionally, on anchored and
- * fully-local counts alike). Proportional padding covers
- * tokenizer drift that scales with the prompt, but a host can still count a few tokens more
- * than any local estimate can see (chat-template framing, reasoning wrappers). Measured
- * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were rejected
- * with 400s. 64 tokens covers the observed drift with margin to spare; the
- * {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
+ * fully-local counts alike). Covers per-request framing no message count sees: the
+ * generation prompt, the anchoring turn's end marker, reasoning wrappers. Measured
+ * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were
+ * rejected with 400s. The {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
  */
 export declare const OUTPUT_FIT_HEADWAY_TOKENS = 64;
 /**
@@ -27,7 +35,9 @@ export declare const OUTPUT_FIT_HEADWAY_TOKENS = 64;
  * The prompt size is the provider's own report from the newest trustworthy
  * assistant turn (see {@link findRequestUsageAnchor}) plus a local count of
  * only the messages appended after it; the whole context is counted locally
- * only when no turn can anchor (fresh or freshly rewritten context).
+ * only when no turn can anchor (fresh or freshly rewritten context). Local
+ * counts carry a proportional tokenizer margin plus
+ * {@link MESSAGE_FRAMING_TOKENS} per message.
  *
  * Returns `maxTokens` unchanged when the requested cap already fits, the
  * model declares no window, the host ends generation at the window itself

package/dist/types/types.d.ts

@@ -637,19 +637,10 @@ export interface SpeculativePhysicalOutcome {
     /** Opaque evidence binding the result to the local bytes actually consumed. */
     evidence?: unknown;
 }
-/** How an approval prompt will show what `formatApprovalDetails` returns. */
-export interface ApprovalDetailsOptions {
-    /**
-     * The prompt keeps only each detail's first line plus a count of the rest (the transcript
-     * shows the call in full): return bodies untruncated so the count is the whole value's.
-     * The host truncates the rows it keeps. Otherwise truncate long values as usual.
-     */
-    compact?: boolean;
-}
 export interface SpeculativeToolReference {
     name: string;
     approval?: ToolApproval;
-    formatApprovalDetails?: (args: unknown, options?: ApprovalDetailsOptions) => string | string[] | undefined;
+    formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
 }
 export interface SpeculativeOperationContext extends ToolSpeculationExecutionContext {
     tool: SpeculativeToolReference;
@@ -1018,6 +1009,11 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
     loadMode?: ToolLoadMode;
     /** Short one-line summary used for tool discovery indexes. */
     summary?: string;
+    /**
+     * Instructions a same-name extension replacement inherits in its description, because results it
+     * obtains by delegating to this native tool through `ctx.invokeTool` follow this tool's contract.
+     */
+    readonly delegationGuidance?: string;
     /**
      * On-demand documentation topics (`topic → markdown`), readable as
      * `xd://<tool>/<topic>`. Lets a tool keep large sub-surfaces out of its
@@ -1091,7 +1087,7 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
     /** Capability tier declaration used by approval gates. Omitted means "exec". */
     approval?: ToolApproval;
     /** Lines appended after the standard approval prompt header. */
-    formatApprovalDetails?: (args: unknown, options?: ApprovalDetailsOptions) => string | string[] | undefined;
+    formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
     /** The main execution callback for this tool. */
     execute: AgentToolExecFn<TParameters, TDetails, TTheme>;
     /** Optional custom rendering for tool call display (returns UI component) */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.10.4",
+	"version": "18.11.0",
 	"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.10.4",
-		"@oh-my-pi/pi-catalog": "18.10.4",
-		"@oh-my-pi/pi-natives": "18.10.4",
-		"@oh-my-pi/pi-utils": "18.10.4",
-		"@oh-my-pi/pi-wire": "18.10.4",
-		"@oh-my-pi/snapcompact": "18.10.4",
+		"@oh-my-pi/pi-ai": "18.11.0",
+		"@oh-my-pi/pi-catalog": "18.11.0",
+		"@oh-my-pi/pi-natives": "18.11.0",
+		"@oh-my-pi/pi-utils": "18.11.0",
+		"@oh-my-pi/pi-wire": "18.11.0",
+		"@oh-my-pi/snapcompact": "18.11.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.10.4",
+		"@oh-my-pi/omptype": "18.11.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -2228,17 +2228,15 @@ async function streamAssistantResponse(
 							}
 						}
 						finalMessage = snapshotAssistantMessage(finalMessage);
-						// Unhealed DSML tool-call markup must never reach history: replaying
-						// it teaches the model to keep writing calls as text (#10556). Strip
-						// it before the context, the UI, and the session see the message.
-						// Only DSML-speaking models qualify; from others it is prose.
-						if (
-							dsmlLeakRecoveryEnabled &&
-							finalMessage.stopReason === "stop" &&
-							!finalMessage.content.some(block => block.type === "toolCall") &&
-							removeDsmlToolMarkupLeak(finalMessage)
-						) {
-							dsmlLeakMessages.add(finalMessage);
+						// Unhealed DSML markup must not reach history, including reasoning
+						// and turns with a valid structured call. Only a failed text-only
+						// call needs the recovery nudge.
+						if (dsmlLeakRecoveryEnabled) {
+							const hasToolCall = finalMessage.content.some(block => block.type === "toolCall");
+							const removed = removeDsmlToolMarkupLeak(finalMessage);
+							if (removed && finalMessage.stopReason === "stop" && !hasToolCall) {
+								dsmlLeakMessages.add(finalMessage);
+							}
 						}
 						// Expand inline macros (and any other registered rewrite) on the
 						// finalized message before it reaches the context, the UI, or tool

package/src/compaction/compaction.ts

@@ -152,6 +152,12 @@ export interface CompactionResult<T = unknown> {
 	details?: T;
 	/** Hook-provided data to persist alongside compaction entry. */
 	preserveData?: Record<string, unknown>;
+	/**
+	 * Last entry the provider-native replay history covers. Set when a remote
+	 * compaction could only fit the history before the kept tail; later entries
+	 * replay normally after the native history.
+	 */
+	providerReplayThroughEntryId?: string;
 }
 
 // ============================================================================
@@ -1268,6 +1274,8 @@ export interface CompactionPreparation {
 	recentMessages: AgentMessage[];
 	/** Entry IDs parallel to recentMessages, for an Anthropic-safe keep-tail boundary. */
 	recentEntryIds?: string[];
+	/** Last entry before the kept tail; a remote compaction that cannot fit the tail covers history through it. */
+	lastSummarizedEntryId?: string;
 	/** Whether this is a split turn (cut point in middle of turn) */
 	isSplitTurn: boolean;
 	tokensBefore: number;
@@ -1480,6 +1488,7 @@ export function prepareCompaction(
 		turnPrefixMessages,
 		recentMessages,
 		recentEntryIds,
+		lastSummarizedEntryId: compactionEntries[cutPoint.firstKeptEntryIndex - 1]?.id,
 		isSplitTurn: cutPoint.isSplitTurn,
 		tokensBefore,
 		previousSummary: previousCompaction?.summary,
@@ -1587,6 +1596,13 @@ function formatRemoteCompactionSummary(inputTokens: number): string {
 	);
 }
 
+/** A V2 remote-compaction request's history and the user items its replacement history retains. */
+interface RemoteCompactionV2Input {
+	codexBody: OpenAICodexCompactionBody | undefined;
+	remoteHistory: Array<Record<string, unknown>>;
+	retainedUserItems: unknown[];
+}
+
 /**
  * Generate summaries for compaction using prepared data.
  * Returns CompactionResult - SessionManager adds id/parentId when saving.
@@ -1608,6 +1624,7 @@ export async function compact(
 		turnPrefixMessages,
 		recentMessages,
 		recentEntryIds,
+		lastSummarizedEntryId,
 		isSplitTurn,
 		tokensBefore,
 		previousSummary,
@@ -1688,15 +1705,50 @@ export async function compact(
 		withOpenAiRemoteCompactionPreserveData(previousPreserveData, undefined),
 		undefined,
 	);
-	const remoteMessages: AgentMessage[] = [
+	const remotePrefixMessages: AgentMessage[] = [
 		...(previousSummaryMigrationMessage ? [previousSummaryMigrationMessage] : []),
 		...(snapcompactArchiveMigrationMessage ? [snapcompactArchiveMigrationMessage] : []),
 		...messagesToSummarize,
 		...turnPrefixMessages,
-		...recentMessages,
 	];
+	const remoteMessages: AgentMessage[] = [...remotePrefixMessages, ...recentMessages];
 	let usedRemoteCompaction = false;
+	let remoteReplayThroughEntryId: string | undefined;
 	let nativeCompactionError: unknown;
+	/**
+	 * Remote compaction replaces the whole history, so its request carries the
+	 * kept tail too. A turn can leave that history over the window (a large
+	 * response or tool output after the last check), which no request can
+	 * send. Then compact the history before the tail instead; the tail replays
+	 * normally after the native history, as a speculative snapshot's later
+	 * turns do. While that fallback exists, the whole-history attempt must not
+	 * rewrite the tail's trailing tool outputs: the prefix keeps them intact.
+	 */
+	const canCompactBeforeTail = lastSummarizedEntryId !== undefined && recentMessages.length > 0;
+	const sendRemoteCompaction = async (
+		sendWhole: () => Promise<void>,
+		sendPrefix: () => Promise<boolean>,
+	): Promise<void> => {
+		try {
+			await sendWhole();
+		} catch (err) {
+			if (
+				signal?.aborted ||
+				!canCompactBeforeTail ||
+				!AIError.is(AIError.classify(err), AIError.Flag.ContextOverflow)
+			) {
+				throw err;
+			}
+			logger.info("Remote compaction history overflows the context window; compacting before the kept tail", {
+				model: model.id,
+				provider: model.provider,
+				keptMessages: recentMessages.length,
+				error: err instanceof Error ? err.message : String(err),
+			});
+			if (!(await sendPrefix())) throw err;
+			remoteReplayThroughEntryId = lastSummarizedEntryId;
+		}
+	};
 	if (
 		settings.remoteEnabled !== false &&
 		settings.remoteStreamingV2Enabled !== false &&
@@ -1708,126 +1760,147 @@ export async function compact(
 				? previousRemoteCompaction.replacementHistory
 				: undefined;
 		const convertToLlm = summaryOptions.convertToLlm ?? defaultConvertToLlm;
-		const messages = convertToLlm(remoteMessages);
 		// Replacement history keeps what the user wrote. Summaries, archive
 		// migrations, and custom/hook messages can serialize as user-role items
 		// too, so pick the user's own messages before serialization erases that,
 		// then serialize each one exactly as the request does.
 		const isUserAuthored = summaryOptions.isUserAuthored ?? ((message: AgentMessage) => message.role === "user");
-		const userMessages = convertToLlm(
-			[...messagesToSummarize, ...turnPrefixMessages, ...recentMessages].filter(isUserAuthored),
-		);
-		const retainedUserItems: unknown[] = [...(previousReplacementHistory ?? [])];
 		const remoteSystemPrompt = summaryOptions.remoteSystemPrompt ?? [SUMMARIZATION_SYSTEM_PROMPT];
-		let codexBody: OpenAICodexCompactionBody | undefined;
-		let remoteHistory: Array<Record<string, unknown>>;
-		if (isCodexResponsesModel(model)) {
-			const previousCodexInput: CodexInputItem[] = [];
-			for (const item of previousReplacementHistory ?? []) {
-				if (!isCodexInputItem(item)) {
-					throw new Error("Stored Codex V2 compaction history contains an invalid input item");
-				}
-				previousCodexInput.push(item);
-			}
-			codexBody = await buildTransformedCodexRequestBody(
-				model,
-				{ systemPrompt: remoteSystemPrompt, messages, tools: summaryOptions.tools },
-				{
-					reasoning: resolveCompactionEffort(model, summaryOptions.thinkingLevel),
-					forceReasoningOff: summaryOptions.thinkingLevel === ThinkingLevel.Off,
-					responsesLite: model.useResponsesLite,
-					sessionId: summaryOptions.sessionId,
-					promptCacheKey: summaryOptions.promptCacheKey,
-					providerSessionState: summaryOptions.providerSessionState,
-					codexCompaction: createOpenAICodexCompactionRequestContext({
-						context: summaryOptions.codexCompaction,
-						implementation: "responses_compaction_v2",
-					}),
-				},
-				undefined,
-				previousCodexInput,
+		const buildV2Input = async (includeTail: boolean): Promise<RemoteCompactionV2Input> => {
+			const messages = convertToLlm(includeTail ? remoteMessages : remotePrefixMessages);
+			const userMessages = convertToLlm(
+				[...messagesToSummarize, ...turnPrefixMessages, ...(includeTail ? recentMessages : [])].filter(
+					isUserAuthored,
+				),
 			);
-			const input = Array.isArray(codexBody.input) ? codexBody.input : [];
-			const nativeInput: Array<Record<string, unknown>> = [];
-			for (const item of input) {
-				if (!isRecord(item)) {
-					throw new Error("Codex V2 compaction input contains a non-object item");
+			const retainedUserItems: unknown[] = [...(previousReplacementHistory ?? [])];
+			let codexBody: OpenAICodexCompactionBody | undefined;
+			let remoteHistory: Array<Record<string, unknown>>;
+			if (isCodexResponsesModel(model)) {
+				const previousCodexInput: CodexInputItem[] = [];
+				for (const item of previousReplacementHistory ?? []) {
+					if (!isCodexInputItem(item)) {
+						throw new Error("Stored Codex V2 compaction history contains an invalid input item");
+					}
+					previousCodexInput.push(item);
 				}
-				nativeInput.push(item);
-			}
-			remoteHistory = stripOpenAIResponsesOutputOnlyStatusesForReplay(nativeInput);
-			codexBody.input = remoteHistory;
-			for (const message of userMessages) {
-				const userBody = await buildTransformedCodexRequestBody(
+				codexBody = await buildTransformedCodexRequestBody(
 					model,
-					{ messages: [message] },
-					{ responsesLite: model.useResponsesLite },
+					{ systemPrompt: remoteSystemPrompt, messages, tools: summaryOptions.tools },
+					{
+						reasoning: resolveCompactionEffort(model, summaryOptions.thinkingLevel),
+						forceReasoningOff: summaryOptions.thinkingLevel === ThinkingLevel.Off,
+						responsesLite: model.useResponsesLite,
+						sessionId: summaryOptions.sessionId,
+						promptCacheKey: summaryOptions.promptCacheKey,
+						providerSessionState: summaryOptions.providerSessionState,
+						codexCompaction: createOpenAICodexCompactionRequestContext({
+							context: summaryOptions.codexCompaction,
+							implementation: "responses_compaction_v2",
+						}),
+					},
+					undefined,
+					previousCodexInput,
 				);
-				retainedUserItems.push(...(userBody.input ?? []));
+				const input = Array.isArray(codexBody.input) ? codexBody.input : [];
+				const nativeInput: Array<Record<string, unknown>> = [];
+				for (const item of input) {
+					if (!isRecord(item)) {
+						throw new Error("Codex V2 compaction input contains a non-object item");
+					}
+					nativeInput.push(item);
+				}
+				remoteHistory = stripOpenAIResponsesOutputOnlyStatusesForReplay(nativeInput);
+				codexBody.input = remoteHistory;
+				for (const message of userMessages) {
+					const userBody = await buildTransformedCodexRequestBody(
+						model,
+						{ messages: [message] },
+						{ responsesLite: model.useResponsesLite },
+					);
+					retainedUserItems.push(...(userBody.input ?? []));
+				}
+			} else {
+				remoteHistory = buildOpenAiResponsesCompactionInput(messages, model, previousReplacementHistory);
+				for (const message of userMessages) {
+					retainedUserItems.push(...buildOpenAiResponsesCompactionInput([message], model, undefined));
+				}
 			}
-		} else {
-			remoteHistory = buildOpenAiResponsesCompactionInput(messages, model, previousReplacementHistory);
-			for (const message of userMessages) {
-				retainedUserItems.push(...buildOpenAiResponsesCompactionInput([message], model, undefined));
+			return { codexBody, remoteHistory, retainedUserItems };
+		};
+		const sendV2 = async (
+			{ codexBody, remoteHistory, retainedUserItems }: RemoteCompactionV2Input,
+			rewriteOutputs: boolean,
+		): Promise<void> => {
+			const instructions = codexBody
+				? typeof codexBody.instructions === "string"
+					? codexBody.instructions
+					: ""
+				: remoteSystemPrompt.join("\n\n");
+			const tools = codexBody
+				? Array.isArray(codexBody.tools)
+					? codexBody.tools
+					: undefined
+				: summaryOptions.tools
+					? convertTools(summaryOptions.tools, model.compat.supportsStrictMode, model)
+					: undefined;
+			const trimmed = trimRemoteCompactionInputToContextWindow(
+				remoteHistory,
+				new Tokenizer(model),
+				model.contextWindow,
+				instructions,
+				tools,
+				{ rewriteOutputs },
+			);
+			if (trimmed.rewrittenOutputs > 0) {
+				logger.info("Rewrote trailing tool outputs before OpenAI V2 remote compaction", {
+					model: model.id,
+					provider: model.provider,
+					rewrittenOutputs: trimmed.rewrittenOutputs,
+					estimatedTokensBefore: trimmed.estimatedTokensBefore,
+					estimatedTokensAfter: trimmed.estimatedTokensAfter,
+					contextWindow: model.contextWindow,
+				});
 			}
-		}
-		if (remoteHistory.length > 0) {
-			try {
-				const instructions = codexBody
-					? typeof codexBody.instructions === "string"
-						? codexBody.instructions
-						: ""
-					: remoteSystemPrompt.join("\n\n");
-				const tools = codexBody
-					? Array.isArray(codexBody.tools)
-						? codexBody.tools
-						: undefined
-					: summaryOptions.tools
-						? convertTools(summaryOptions.tools, model.compat.supportsStrictMode, model)
-						: undefined;
-				const trimmed = trimRemoteCompactionInputToContextWindow(
-					remoteHistory,
-					new Tokenizer(model),
-					model.contextWindow,
-					instructions,
-					tools,
-				);
-				if (trimmed.rewrittenOutputs > 0) {
-					logger.info("Rewrote trailing tool outputs before OpenAI V2 remote compaction", {
-						model: model.id,
-						provider: model.provider,
-						rewrittenOutputs: trimmed.rewrittenOutputs,
-						estimatedTokensBefore: trimmed.estimatedTokensBefore,
-						estimatedTokensAfter: trimmed.estimatedTokensAfter,
-						contextWindow: model.contextWindow,
+			assertRemoteCompactionInputFits(trimmed, model);
+			const requestOptions = {
+				sessionId: summaryOptions.sessionId,
+				promptCacheKey: summaryOptions.promptCacheKey,
+				retainedMessageBudget: settings.v2RetainedMessageBudget,
+				retainedUserItems,
+			};
+			const request = codexBody
+				? buildCompactionV2RequestFromBody(model, { ...codexBody, input: trimmed.input }, requestOptions)
+				: buildCompactionV2Request(model, trimmed.input, instructions, {
+						...requestOptions,
+						tools,
+						reasoning: buildCompactionV2Reasoning(model, summaryOptions.thinkingLevel),
 					});
-				}
-				assertRemoteCompactionInputFits(trimmed, model);
-				const requestOptions = {
-					sessionId: summaryOptions.sessionId,
-					promptCacheKey: summaryOptions.promptCacheKey,
-					retainedMessageBudget: settings.v2RetainedMessageBudget,
-					retainedUserItems,
-				};
-				const request = codexBody
-					? buildCompactionV2RequestFromBody(model, { ...codexBody, input: trimmed.input }, requestOptions)
-					: buildCompactionV2Request(model, trimmed.input, instructions, {
-							...requestOptions,
-							tools,
-							reasoning: buildCompactionV2Reasoning(model, summaryOptions.thinkingLevel),
-						});
-				const remote = await withAuth(
-					apiKey,
-					key =>
-						requestCompactionV2Streaming(model, key, request, signal, {
-							fetch: summaryOptions.fetch,
-							providerSessionState: summaryOptions.providerSessionState,
-							preferWebsockets: summaryOptions.preferWebsockets,
-							codexCompaction: summaryOptions.codexCompaction,
-						}),
-					{ signal },
+			const remote = await withAuth(
+				apiKey,
+				key =>
+					requestCompactionV2Streaming(model, key, request, signal, {
+						fetch: summaryOptions.fetch,
+						providerSessionState: summaryOptions.providerSessionState,
+						preferWebsockets: summaryOptions.preferWebsockets,
+						codexCompaction: summaryOptions.codexCompaction,
+					}),
+				{ signal },
+			);
+			preserveData = { ...preserveData, ...storeCompactionV2PreserveData(remote, model) };
+		};
+		const whole = await buildV2Input(true);
+		if (whole.remoteHistory.length > 0) {
+			try {
+				await sendRemoteCompaction(
+					() => sendV2(whole, !canCompactBeforeTail),
+					async () => {
+						const prefix = await buildV2Input(false);
+						if (prefix.remoteHistory.length === 0) return false;
+						await sendV2(prefix, true);
+						return true;
+					},
 				);
-				preserveData = { ...preserveData, ...storeCompactionV2PreserveData(remote, model) };
 				usedRemoteCompaction = true;
 			} catch (err) {
 				// A user/session abort is a cancellation, not a remote failure —
@@ -1859,33 +1932,52 @@ export async function compact(
 				: previousV2Compaction?.provider === model.provider
 					? previousV2Compaction.replacementHistory
 					: undefined;
-		const remoteHistory = buildOpenAiNativeHistory(
-			(summaryOptions.convertToLlm ?? defaultConvertToLlm)(remoteMessages),
+		const convertToLlm = summaryOptions.convertToLlm ?? defaultConvertToLlm;
+		const supportsOriginalDetail = openAiCompatSupportsImageDetailOriginal(model);
+		const sendV1 = async (remoteHistory: Array<Record<string, unknown>>, rewriteOutputs: boolean): Promise<void> => {
+			const remote = await withAuth(
+				apiKey,
+				key =>
+					requestOpenAiRemoteCompaction(
+						model,
+						key,
+						remoteHistory,
+						summaryOptions.remoteSystemPrompt?.join("\n\n") ?? SUMMARIZATION_SYSTEM_PROMPT,
+						signal,
+						{
+							fetch: summaryOptions.fetch,
+							sessionId: summaryOptions.sessionId,
+							providerSessionState: summaryOptions.providerSessionState,
+							codexCompaction: summaryOptions.codexCompaction,
+							rewriteOutputs,
+						},
+					),
+				{ signal },
+			);
+			preserveData = withOpenAiRemoteCompactionPreserveData(preserveData, remote);
+		};
+		const whole = buildOpenAiNativeHistory(
+			convertToLlm(remoteMessages),
 			model,
 			previousReplacementHistory,
-			openAiCompatSupportsImageDetailOriginal(model),
+			supportsOriginalDetail,
 		);
-		if (remoteHistory.length > 0) {
+		if (whole.length > 0) {
 			try {
-				const remote = await withAuth(
-					apiKey,
-					key =>
-						requestOpenAiRemoteCompaction(
+				await sendRemoteCompaction(
+					() => sendV1(whole, !canCompactBeforeTail),
+					async () => {
+						const prefix = buildOpenAiNativeHistory(
+							convertToLlm(remotePrefixMessages),
 							model,
-							key,
-							remoteHistory,
-							summaryOptions.remoteSystemPrompt?.join("\n\n") ?? SUMMARIZATION_SYSTEM_PROMPT,
-							signal,
-							{
-								fetch: summaryOptions.fetch,
-								sessionId: summaryOptions.sessionId,
-								providerSessionState: summaryOptions.providerSessionState,
-								codexCompaction: summaryOptions.codexCompaction,
-							},
-						),
-					{ signal },
+							previousReplacementHistory,
+							supportsOriginalDetail,
+						);
+						if (prefix.length === 0) return false;
+						await sendV1(prefix, true);
+						return true;
+					},
 				);
-				preserveData = withOpenAiRemoteCompactionPreserveData(preserveData, remote);
 				usedRemoteCompaction = true;
 			} catch (err) {
 				// A user/session abort is a cancellation, not a remote failure —
@@ -2157,6 +2249,7 @@ export async function compact(
 		tokensBefore,
 		details: { readFiles, modifiedFiles } as CompactionDetails,
 		preserveData: finalPreserveData,
+		...(remoteReplayThroughEntryId ? { providerReplayThroughEntryId: remoteReplayThroughEntryId } : {}),
 	};
 }
 

package/src/compaction/openai.ts

@@ -89,27 +89,34 @@ const REMOTE_COMPACTION_REQUEST_OVERHEAD_TOKENS = 256;
 const remoteImageTokenCache = new WeakMap<Record<string, unknown>, { billingKey: string; tokens: number }>();
 const TOOL_RESULT_IMAGE_ATTACHMENT_TEXT = "Attached image(s) from tool result:";
 
-interface NormalizedEstimateValue {
-	value: unknown;
+/**
+ * A request as the model reads it: every string value decoded (no quoting or
+ * escapes), with keys and scalar values kept as one framing fragment.
+ */
+interface RemoteEstimateParts {
+	fragments: string[];
+	framing: string[];
 	imageTokens: number;
 }
 
-function normalizeRemoteCompactionEstimateValue(
+function collectRemoteCompactionEstimate(
 	value: unknown,
 	tokenizer: Tokenizer,
-	dropEncrypted = true,
-): NormalizedEstimateValue {
+	dropEncrypted: boolean,
+	parts: RemoteEstimateParts,
+): void {
+	if (typeof value === "string") {
+		if (value) parts.fragments.push(value);
+		return;
+	}
 	if (Array.isArray(value)) {
-		const normalized: unknown[] = [];
-		let imageTokens = 0;
-		for (const item of value) {
-			const result = normalizeRemoteCompactionEstimateValue(item, tokenizer, dropEncrypted);
-			normalized.push(result.value);
-			imageTokens += result.imageTokens;
-		}
-		return { value: normalized, imageTokens };
+		for (const item of value) collectRemoteCompactionEstimate(item, tokenizer, dropEncrypted, parts);
+		return;
+	}
+	if (value === null || typeof value !== "object") {
+		if (value !== undefined) parts.framing.push(String(value));
+		return;
 	}
-	if (!value || typeof value !== "object") return { value, imageTokens: 0 };
 
 	const record = value as Record<string, unknown>;
 	if (record.type === "input_image") {
@@ -125,31 +132,44 @@ function normalizeRemoteCompactionEstimateValue(
 			};
 			remoteImageTokenCache.set(record, cached);
 		}
-		return { value: { ...record, image_url: "<image>" }, imageTokens: cached.tokens };
+		parts.imageTokens += cached.tokens;
+		return;
 	}
-	const normalized: Record<string, unknown> = {};
-	let imageTokens = 0;
-	for (const [key, item] of Object.entries(record)) {
+	for (const key in record) {
+		const item = record[key];
 		// 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 (dropEncrypted && key === "encrypted_content" && typeof item === "string") continue;
-		const result = normalizeRemoteCompactionEstimateValue(item, tokenizer, dropEncrypted);
-		normalized[key] = result.value;
-		imageTokens += result.imageTokens;
+		if (item === undefined || (dropEncrypted && key === "encrypted_content" && typeof item === "string")) continue;
+		parts.framing.push(key);
+		collectRemoteCompactionEstimate(item, tokenizer, dropEncrypted, parts);
 	}
-	return { value: normalized, imageTokens };
+}
+
+/**
+ * Text fragments and image tokens for `value`. Strings count decoded: JSON
+ * escaping inflates quote-, backslash- and newline-dense text (code,
+ * disassembly) well past what the model reads.
+ */
+function remoteCompactionEstimateParts(
+	value: unknown,
+	tokenizer: Tokenizer,
+	dropEncrypted: boolean,
+): { fragments: string[]; imageTokens: number } {
+	const parts: RemoteEstimateParts = { fragments: [], framing: [], imageTokens: 0 };
+	collectRemoteCompactionEstimate(value, tokenizer, dropEncrypted, parts);
+	if (parts.framing.length > 0) parts.fragments.push(parts.framing.join(" "));
+	return { fragments: parts.fragments, imageTokens: parts.imageTokens };
 }
 
 /**
  * Tokens of stored Responses replacement history. Retained `input_image` parts
  * count at their image estimate rather than as base64 text; everything else,
- * opaque compaction state included, counts as serialized.
+ * opaque compaction state included, counts as decoded text.
  */
 export function countResponsesHistoryTokens(items: unknown[], tokenizer: Tokenizer): number {
-	const normalized = normalizeRemoteCompactionEstimateValue(items, tokenizer, false);
-	const serialized = stringifyJson(normalized.value);
-	return (serialized === undefined ? 0 : tokenizer.countTokens(serialized)) + normalized.imageTokens;
+	const { fragments, imageTokens } = remoteCompactionEstimateParts(items, tokenizer, false);
+	return (fragments.length === 0 ? 0 : tokenizer.countTokens(fragments)) + imageTokens;
 }
 
 export interface TrimRemoteCompactionInputResult {
@@ -178,10 +198,10 @@ interface RemoteCompactionBudgetProbe {
 /**
  * Cheap-first sizing of a remote-compaction request. Images (priced from their
  * dimensions) and the request frame come off the budget rather than through
- * the 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.
+ * the tokenizer; opaque `encrypted_content` payloads are excluded. The decoded
+ * request text 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>>,
@@ -190,16 +210,16 @@ function probeRemoteCompactionInputBudget(
 	tools: unknown[] | undefined,
 	contextWindow: number | null | undefined,
 ): RemoteCompactionBudgetProbe {
-	const normalized = normalizeRemoteCompactionEstimateValue(
+	const { fragments, imageTokens } = remoteCompactionEstimateParts(
 		{ instructions, input, ...(tools ? { tools } : {}) },
 		tokenizer,
+		true,
 	);
-	const serialized = stringifyJson(normalized.value) ?? "";
-	const flatTokens = normalized.imageTokens + REMOTE_COMPACTION_REQUEST_OVERHEAD_TOKENS;
+	const flatTokens = imageTokens + REMOTE_COMPACTION_REQUEST_OVERHEAD_TOKENS;
 	if (!contextWindow || contextWindow <= 0) {
-		return { tokens: tokenizer.countTokens(serialized, "upperbound") + flatTokens, fits: true, textFits: true };
+		return { tokens: tokenizer.countTokens(fragments, "upperbound") + flatTokens, fits: true, textFits: true };
 	}
-	const budget = tokenizer.checkTokenBudget(serialized, Math.max(0, contextWindow - flatTokens));
+	const budget = tokenizer.checkTokenBudget(fragments, Math.max(0, contextWindow - flatTokens));
 	return {
 		tokens: budget.tokens + flatTokens,
 		fits: budget.fits,
@@ -231,6 +251,16 @@ function isToolResultImageAttachment(item: Record<string, unknown>): boolean {
 	return hasLabel && hasImage;
 }
 
+/** Options for {@link trimRemoteCompactionInputToContextWindow}. */
+export interface TrimRemoteCompactionOptions {
+	/**
+	 * Whether oversized trailing tool outputs may be rewritten (default true).
+	 * False when a caller can compact a shorter prefix instead, so a kept tool
+	 * result replays intact rather than being replaced.
+	 */
+	rewriteOutputs?: boolean;
+}
+
 /**
  * Preserve the full native transcript unless trailing tool outputs alone push a
  * remote compaction request beyond the model window. Replacing only those
@@ -245,15 +275,16 @@ export function trimRemoteCompactionInputToContextWindow(
 	contextWindow: number | null | undefined,
 	instructions: string,
 	tools?: unknown[],
+	options?: TrimRemoteCompactionOptions,
 ): TrimRemoteCompactionInputResult {
 	const before = probeRemoteCompactionInputBudget(input, tokenizer, instructions, tools, contextWindow);
-	if (before.fits) {
+	if (before.fits || options?.rewriteOutputs === false) {
 		return {
 			input,
 			rewrittenOutputs: 0,
 			estimatedTokensBefore: before.tokens,
 			estimatedTokensAfter: before.tokens,
-			fits: true,
+			fits: before.fits || before.textFits,
 		};
 	}
 
@@ -828,6 +859,8 @@ export async function requestOpenAiRemoteCompaction(
 		sessionId?: string;
 		providerSessionState?: Map<string, ProviderSessionState>;
 		codexCompaction?: CodexCompactionContext;
+		/** Forwarded to {@link trimRemoteCompactionInputToContextWindow}. */
+		rewriteOutputs?: boolean;
 	},
 ): Promise<OpenAiRemoteCompactionResponse> {
 	let fetchImpl: FetchImpl = opts?.fetch ?? fetch;
@@ -841,6 +874,8 @@ export async function requestOpenAiRemoteCompaction(
 		new Tokenizer(model),
 		model.contextWindow,
 		instructions,
+		undefined,
+		{ rewriteOutputs: opts?.rewriteOutputs },
 	);
 	if (trimmed.rewrittenOutputs > 0) {
 		logger.info("Rewrote trailing tool outputs before OpenAI remote compaction", {

package/src/output-budget.ts

@@ -17,14 +17,23 @@ export const MIN_FITTED_OUTPUT_TOKENS = 1024;
  */
 const PROMPT_ESTIMATE_MARGIN_DIVISOR = 10;
 
+/**
+ * Chat-template framing charged per locally counted message. `Tokenizer.countMessage`
+ * counts content only, but every template wraps each message in role markers and
+ * separators, and tool results in response wrappers: about 5 tokens per merged
+ * Qwen3 `<tool_response>` or Llama 3 turn, 10–15 for harmony or Mistral tool results.
+ * The proportional margin scales with content, so many short messages (a turn's
+ * parallel tool results) leave this uncovered. Provider-anchored messages need no
+ * charge: the host's own report already includes their framing.
+ */
+export const MESSAGE_FRAMING_TOKENS = 16;
+
 /**
  * Absolute headway subtracted from the remaining room (unconditionally, on anchored and
- * fully-local counts alike). Proportional padding covers
- * tokenizer drift that scales with the prompt, but a host can still count a few tokens more
- * than any local estimate can see (chat-template framing, reasoning wrappers). Measured
- * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were rejected
- * with 400s. 64 tokens covers the observed drift with margin to spare; the
- * {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
+ * fully-local counts alike). Covers per-request framing no message count sees: the
+ * generation prompt, the anchoring turn's end marker, reasoning wrappers. Measured
+ * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were
+ * rejected with 400s. The {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
  */
 export const OUTPUT_FIT_HEADWAY_TOKENS = 64;
 
@@ -43,7 +52,9 @@ export const OUTPUT_FIT_HEADWAY_TOKENS = 64;
  * The prompt size is the provider's own report from the newest trustworthy
  * assistant turn (see {@link findRequestUsageAnchor}) plus a local count of
  * only the messages appended after it; the whole context is counted locally
- * only when no turn can anchor (fresh or freshly rewritten context).
+ * only when no turn can anchor (fresh or freshly rewritten context). Local
+ * counts carry a proportional tokenizer margin plus
+ * {@link MESSAGE_FRAMING_TOKENS} per message.
  *
  * Returns `maxTokens` unchanged when the requested cap already fits, the
  * model declares no window, the host ends generation at the window itself
@@ -122,12 +133,14 @@ function withMargin(localTokens: number): number {
 function countPromptTokens(context: Context, tokenizer: Tokenizer): number {
 	const { messages } = context;
 	const anchor = findRequestUsageAnchor(messages);
-	if (!anchor) return withMargin(countContextTokens(context, tokenizer));
+	if (!anchor) {
+		return withMargin(countContextTokens(context, tokenizer)) + messages.length * MESSAGE_FRAMING_TOKENS;
+	}
 	let tail = 0;
 	for (let index = anchor.index + 1; index < messages.length; index++) {
 		tail += tokenizer.countMessage(messages[index]);
 	}
-	return anchor.tokens + withMargin(tail);
+	return anchor.tokens + withMargin(tail) + (messages.length - anchor.index - 1) * MESSAGE_FRAMING_TOKENS;
 }
 
 function countContextTokens(context: Context, tokenizer: Tokenizer): number {

package/src/types.ts

@@ -718,20 +718,10 @@ export interface SpeculativePhysicalOutcome {
 	evidence?: unknown;
 }
 
-/** How an approval prompt will show what `formatApprovalDetails` returns. */
-export interface ApprovalDetailsOptions {
-	/**
-	 * The prompt keeps only each detail's first line plus a count of the rest (the transcript
-	 * shows the call in full): return bodies untruncated so the count is the whole value's.
-	 * The host truncates the rows it keeps. Otherwise truncate long values as usual.
-	 */
-	compact?: boolean;
-}
-
 export interface SpeculativeToolReference {
 	name: string;
 	approval?: ToolApproval;
-	formatApprovalDetails?: (args: unknown, options?: ApprovalDetailsOptions) => string | string[] | undefined;
+	formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
 }
 
 export interface SpeculativeOperationContext extends ToolSpeculationExecutionContext {
@@ -1152,6 +1142,11 @@ export interface AgentTool<
 	loadMode?: ToolLoadMode;
 	/** Short one-line summary used for tool discovery indexes. */
 	summary?: string;
+	/**
+	 * Instructions a same-name extension replacement inherits in its description, because results it
+	 * obtains by delegating to this native tool through `ctx.invokeTool` follow this tool's contract.
+	 */
+	readonly delegationGuidance?: string;
 	/**
 	 * On-demand documentation topics (`topic → markdown`), readable as
 	 * `xd://<tool>/<topic>`. Lets a tool keep large sub-surfaces out of its
@@ -1228,7 +1223,7 @@ export interface AgentTool<
 	approval?: ToolApproval;
 
 	/** Lines appended after the standard approval prompt header. */
-	formatApprovalDetails?: (args: unknown, options?: ApprovalDetailsOptions) => string | string[] | undefined;
+	formatApprovalDetails?: (args: unknown) => string | string[] | undefined;
 
 	/** The main execution callback for this tool. */
 	execute: AgentToolExecFn<TParameters, TDetails, TTheme>;