@gajae-code/agent-core 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-13
+
+### Fixed
+
+- Fixed compaction cut-point selection when the newest retained context ends in an uncuttable tool result, so automatic compaction can keep the latest assistant/tool-result pair instead of falling back to a no-op cut.
+
+### Changed
+
+- Optimization Suite v3 Lane 2 (context cost): compaction token estimates now use a shared per-entry cache (`estimateEntryTokens`) keyed by a boundary-lossless fingerprint of the exact estimator fragments, covering `estimateEntriesTokens`, the `findCutPoint` reverse walk, and pruning candidate scoring — repeated full-session estimate p95 −97%, token totals exactly equal to fresh estimates and never stale after prune mutation. Pruned bash/search/grep tool results now carry a one-line digest notice (exit code, match/file count, first error line; capped at 1.25× the generic notice cost) instead of a bare truncation notice, with savings computed from the exact notice string; reads and other tools keep the generic notice. `trimOpenAiCompactInput` is O(n) via per-item serialized lengths and a running character sum (5k-item trim −99.9%) and is now exported.
+- Optimization Suite v3 Lane 3 (serialization): `cloneJson` in the append-only context now uses a typed JSON-semantic recursive clone instead of a `JSON.parse(JSON.stringify())` round-trip (−36% median on clone-heavy paths), with exact JSON.stringify byte parity including the toJSON holder-key protocol (single get, no re-dispatch on replacement values), function/symbol dropping, sparse arrays, Dates, and prototype-bearing objects; the helper is now exported.
+
+## [0.4.5] - 2026-06-12
+
+### Changed
+
+- Made tool-output pruning staleness-aware: results superseded by a later same-target result (re-read file, re-run search) or invalidated by a later successful edit/write are pruned before merely-old ones, including inside the recency protect window. New optional `PruneConfig.staleOverridableTools` (default `["read"]`) waives protected-tool immunity for superseded results while the most recent result per target stays protected. Target identity uses collision-proof canonical JSON tuple keys.
+- `PruneResult` now returns `prunedEntries` so callers whose entry source materializes copies (e.g. blob-externalized session entries) can write mutations back into their canonical store.
+
+### Fixed
+
+- Preserved Cursor-native tool call rendering and execution through the agent tool-call path, including runtime tool details.
+
+## [0.4.4] - 2026-06-10
+
+- Version aligned with the 0.4.4 monorepo release; no functional changes in this package.
+
 ## [0.4.3] - 2026-06-10
 
 ### Fixed

package/dist/types/agent.d.ts

@@ -80,6 +80,8 @@ export interface AgentOptions {
      * Use this when abort decisions must happen before buffered events continue flowing.
      */
     onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+    /** Called for non-content tool-choice incapability stream events. */
+    onToolChoiceIncapability?: AgentLoopConfig["onToolChoiceIncapability"];
     /**
      * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
      */

package/dist/types/append-only-context.d.ts

@@ -121,3 +121,4 @@ export declare class AppendOnlyContextManager {
     invalidate(): void;
     reset(context: AgentContext, options: BuildOptions): void;
 }
+export declare function cloneJson<T>(value: T): T;

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

@@ -68,11 +68,37 @@ export declare function effectiveReserveTokens(contextWindow: number, settings:
 export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): boolean;
 export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): number;
 /**
- * Estimate token count for a message using cl100k_base via the native
- * tokenizer. This is not Anthropic's first-party tokenizer (Anthropic doesn't
- * publish one) but is within ~5–10% across English/code text.
+ * Estimate token count for a message using the native o200k tokenizer.
+ * Exact for o200k only; an approximation for Anthropic/other model families
+ * (Anthropic doesn't publish a tokenizer) within ~5–10% on English/code text.
+ *
+ * This materializes the native BPE table (~50MB RSS) on first call. Use it
+ * only for context-changing decisions (compaction trigger/cut points, pruning
+ * budgets, branch summarization, fork-context seeding, context-limit
+ * enforcement). For display-only totals use
+ * {@link estimateMessageTokensHeuristic}.
+ */
+export declare function countMessageTokensNativeO200k(message: AgentMessage): number;
+/**
+ * Backwards-compatible alias for {@link countMessageTokensNativeO200k}.
+ * Existing callers treat this as the canonical message-token estimator for
+ * context-changing decisions.
+ */
+export declare const estimateTokens: typeof countMessageTokensNativeO200k;
+/**
+ * Cheap, native-free token estimate for a message. Suitable ONLY for
+ * display/init surfaces (status line, /context report, HUD totals) — never
+ * for context-changing decisions, which must use
+ * {@link countMessageTokensNativeO200k}.
+ */
+export declare function estimateMessageTokensHeuristic(message: AgentMessage): number;
+/**
+ * Cheap, native-free token estimate for plain string fragments. Display-only
+ * counterpart of the native `countTokens(fragments)` aggregate.
  */
-export declare function estimateTokens(message: AgentMessage): number;
+export declare function estimateTextTokensHeuristic(fragments: string | readonly string[]): number;
+export declare function estimateEntryTokens(entry: SessionEntry): number;
+export declare function estimateEntriesTokens(entries: SessionEntry[], startIndex: number, endIndex: number): number;
 /**
  * Find the user message (or bashExecution) that starts the turn containing the given entry index.
  * Returns -1 if no turn start found before the index.

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

@@ -20,6 +20,12 @@ export interface ModelChangeEntry extends SessionEntryBase {
     model: string;
     /** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
     role?: string;
+    /** Requested model before a runtime substitution/fallback, in "provider/modelId" format. */
+    previousModel?: string;
+    /** Machine-readable reason for runtime model substitution/fallback. */
+    reason?: string;
+    /** Effective thinking level when the change was recorded. */
+    thinkingLevel?: string | null;
 }
 export interface ServiceTierChangeEntry extends SessionEntryBase {
     type: "service_tier_change";

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

@@ -41,6 +41,8 @@ export interface RemoteCompactionResponse {
 export declare function shouldUseOpenAiRemoteCompaction(model: Model): boolean;
 export declare function getPreservedOpenAiRemoteCompactionData(preserveData: Record<string, unknown> | undefined): OpenAiRemoteCompactionPreserveData | undefined;
 export declare function withOpenAiRemoteCompactionPreserveData(preserveData: Record<string, unknown> | undefined, remoteCompaction: OpenAiRemoteCompactionPreserveData | undefined): Record<string, unknown> | undefined;
+export declare function estimateOpenAiCompactInputTokens(input: Array<Record<string, unknown>>, instructions: string): number;
+export declare function trimOpenAiCompactInput(input: Array<Record<string, unknown>>, contextWindow: number, instructions: string): Array<Record<string, unknown>>;
 /**
  * Build the OpenAI Responses-API native history array from LLM messages.
  *

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

@@ -1,7 +1,13 @@
 /**
  * Tool output pruning utilities for compaction.
+ *
+ * Candidate selection is staleness-aware: tool results that have been
+ * superseded by a later result for the same target (same file read again,
+ * same search re-run) or invalidated by a later successful edit/write to a
+ * covered file are pruned in preference to merely-old results. Protect-window
+ * and minimum-savings hysteresis semantics are unchanged.
  */
-import type { SessionEntry } from "./entries";
+import type { SessionEntry, SessionMessageEntry } from "./entries";
 export interface PruneConfig {
     /** Keep the most recent tool output tokens intact. */
     protectTokens: number;
@@ -9,10 +15,23 @@ export interface PruneConfig {
     minimumSavings: number;
     /** Tool names that should never be pruned. */
     protectedTools: string[];
+    /**
+     * Tools in `protectedTools` whose protection is waived once the result is
+     * superseded (a later result for the same target, or a later successful
+     * edit/write to the covered file). The most recent result per target is
+     * never considered superseded. Optional; defaults to none.
+     */
+    staleOverridableTools?: string[];
 }
 export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
 export interface PruneResult {
     prunedCount: number;
     tokensSaved: number;
+    /**
+     * The mutated message entries. Callers whose entry source returns
+     * materialized copies (not live references) must write these back into
+     * their canonical store by id.
+     */
+    prunedEntries: SessionMessageEntry[];
 }
 export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;

package/dist/types/types.d.ts

@@ -154,6 +154,10 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Callers may abort synchronously to stop consuming buffered provider events.
      */
     onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+    /** Called for non-content tool-choice incapability stream events. */
+    onToolChoiceIncapability?: (event: Extract<AssistantMessageEvent, {
+        type: "toolChoiceIncapability";
+    }>) => void;
     /**
      * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
      */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.4.4",
+	"version": "0.5.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.4.4",
-		"@gajae-code/natives": "0.4.4",
-		"@gajae-code/utils": "0.4.4",
+		"@gajae-code/ai": "0.5.0",
+		"@gajae-code/natives": "0.5.0",
+		"@gajae-code/utils": "0.5.0",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -815,6 +815,10 @@ async function streamAssistantResponse(
 							stream.push({ type: "message_start", message: { ...partialMessage } });
 							break;
 
+						case "toolChoiceIncapability":
+							config.onToolChoiceIncapability?.(event);
+							break;
+
 						case "text_start":
 						case "text_delta":
 						case "text_end":

package/src/agent.ts

@@ -151,6 +151,8 @@ export interface AgentOptions {
 	 * Use this when abort decisions must happen before buffered events continue flowing.
 	 */
 	onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+	/** Called for non-content tool-choice incapability stream events. */
+	onToolChoiceIncapability?: AgentLoopConfig["onToolChoiceIncapability"];
 
 	/**
 	 * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
@@ -309,6 +311,7 @@ export class Agent {
 	#onResponse?: SimpleStreamOptions["onResponse"];
 	#onSseEvent?: SimpleStreamOptions["onSseEvent"];
 	#onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+	#onToolChoiceIncapability?: AgentLoopConfig["onToolChoiceIncapability"];
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#shouldPause?: AgentLoopConfig["shouldPause"];
@@ -373,6 +376,7 @@ export class Agent {
 		this.#intentTracing = opts.intentTracing === true;
 		this.#getToolChoice = opts.getToolChoice;
 		this.#onAssistantMessageEvent = opts.onAssistantMessageEvent;
+		this.#onToolChoiceIncapability = opts.onToolChoiceIncapability;
 		this.#onHarmonyLeak = opts.onHarmonyLeak;
 		this.#shouldPause = opts.shouldPause;
 		this.beforeToolCall = opts.beforeToolCall;
@@ -680,7 +684,11 @@ export class Agent {
 		if (!source) return undefined;
 
 		const guarded: CursorExecHandlers = {};
-		const read = source.read;
+		// Bind each handler to `source`: they are methods of a CursorExecHandlers
+		// instance that reference private fields via `this`. Extracting them bare
+		// (`const read = source.read`) and calling `read(args)` would invoke them with
+		// `this === undefined`, throwing "undefined is not an object (this.#optionsForCall)".
+		const read = source.read?.bind(source);
 		if (read) {
 			guarded.read = async args => {
 				this.#assertActiveRun(runId);
@@ -689,7 +697,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const ls = source.ls;
+		const ls = source.ls?.bind(source);
 		if (ls) {
 			guarded.ls = async args => {
 				this.#assertActiveRun(runId);
@@ -698,7 +706,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const grep = source.grep;
+		const grep = source.grep?.bind(source);
 		if (grep) {
 			guarded.grep = async args => {
 				this.#assertActiveRun(runId);
@@ -707,7 +715,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const write = source.write;
+		const write = source.write?.bind(source);
 		if (write) {
 			guarded.write = async args => {
 				this.#assertActiveRun(runId);
@@ -716,7 +724,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const deleteHandler = source.delete;
+		const deleteHandler = source.delete?.bind(source);
 		if (deleteHandler) {
 			guarded.delete = async args => {
 				this.#assertActiveRun(runId);
@@ -725,7 +733,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const shell = source.shell;
+		const shell = source.shell?.bind(source);
 		if (shell) {
 			guarded.shell = async args => {
 				this.#assertActiveRun(runId);
@@ -734,7 +742,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const shellStream = source.shellStream;
+		const shellStream = source.shellStream?.bind(source);
 		if (shellStream) {
 			guarded.shellStream = async (args, callbacks) => {
 				this.#assertActiveRun(runId);
@@ -743,7 +751,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const diagnostics = source.diagnostics;
+		const diagnostics = source.diagnostics?.bind(source);
 		if (diagnostics) {
 			guarded.diagnostics = async args => {
 				this.#assertActiveRun(runId);
@@ -752,7 +760,7 @@ export class Agent {
 				return result;
 			};
 		}
-		const mcp = source.mcp;
+		const mcp = source.mcp?.bind(source);
 		if (mcp) {
 			guarded.mcp = async call => {
 				this.#assertActiveRun(runId);
@@ -1218,6 +1226,12 @@ export class Agent {
 						this.#onAssistantMessageEvent?.(message, event);
 					}
 				: undefined,
+			onToolChoiceIncapability: this.#onToolChoiceIncapability
+				? event => {
+						if (this.#activeRunId !== runId) return;
+						this.#onToolChoiceIncapability?.(event);
+					}
+				: undefined,
 			onHarmonyLeak: this.#onHarmonyLeak,
 			getToolChoice,
 			getReasoning: () => this.#state.thinkingLevel,

package/src/append-only-context.ts

@@ -46,6 +46,9 @@ export interface BuildOptions {
 export class StablePrefix {
 	#snapshot: StablePrefixSnapshot | null = null;
 	#version = 0;
+	#sourceSystemPrompt: readonly string[] | null = null;
+	#sourceTools: AgentContext["tools"] | null = null;
+	#sourceIntentTracing: boolean | null = null;
 
 	get fingerprint(): string {
 		return this.#snapshot?.fingerprint ?? "<unbuilt>";
@@ -65,6 +68,9 @@ export class StablePrefix {
 		const systemPrompt = cloneJson(snapshot.systemPrompt);
 		const tools = normalizeImportedTools(snapshot.tools, options);
 		const fingerprint = computeFingerprint(systemPrompt, tools, options);
+		this.#sourceSystemPrompt = null;
+		this.#sourceTools = null;
+		this.#sourceIntentTracing = null;
 		if (fingerprint !== snapshot.fingerprint) {
 			throw new Error(
 				`StablePrefix.importSnapshot() fingerprint mismatch: expected ${fingerprint}, received ${snapshot.fingerprint}`,
@@ -79,11 +85,26 @@ export class StablePrefix {
 	 * Returns `true` if the prefix actually changed (cache miss imminent).
 	 */
 	build(context: AgentContext, options: BuildOptions): boolean {
+		if (
+			this.#snapshot &&
+			this.#sourceSystemPrompt === context.systemPrompt &&
+			this.#sourceTools === context.tools &&
+			this.#sourceIntentTracing === options.intentTracing
+		) {
+			const sourceFingerprint = takeSnapshot(context, options).fingerprint;
+			if (this.#snapshot.fingerprint === sourceFingerprint) return false;
+		}
 		const snapshot = takeSnapshot(context, options);
 		if (this.#snapshot && this.#snapshot.fingerprint === snapshot.fingerprint) {
+			this.#sourceSystemPrompt = context.systemPrompt;
+			this.#sourceTools = context.tools;
+			this.#sourceIntentTracing = options.intentTracing;
 			return false;
 		}
 		this.#snapshot = snapshot;
+		this.#sourceSystemPrompt = context.systemPrompt;
+		this.#sourceTools = context.tools;
+		this.#sourceIntentTracing = options.intentTracing;
 		this.#version++;
 		return true;
 	}
@@ -91,6 +112,9 @@ export class StablePrefix {
 	/** Force rebuild on the next `build()` call. */
 	invalidate(): void {
 		this.#snapshot = null;
+		this.#sourceSystemPrompt = null;
+		this.#sourceTools = null;
+		this.#sourceIntentTracing = null;
 	}
 
 	/**
@@ -175,8 +199,8 @@ export class AppendOnlyContextManager {
 	readonly log = new AppendOnlyLog();
 	/** How many normalized messages were synced into the log as of the last sync. */
 	#lastSyncCount = 0;
-	/** Rolling digest of synced message content — detects in-place rewrites. */
-	#syncedDigest = 0;
+	/** Fingerprint plus source bytes of synced message content — detects in-place rewrites with no hash-only equality. */
+	#syncedDigest = emptyMessageDigest();
 	/** Number of provider-normalized messages that were seeded before child-local messages. */
 	#seededPrefixCount = 0;
 
@@ -208,19 +232,22 @@ export class AppendOnlyContextManager {
 	 * (same length, changed content via a rolling digest).
 	 */
 	syncMessages(normalizedMessages: any[]): void {
-		const seededPrefix = this.#seededPrefixCount > 0 ? this.log.toMessages().slice(0, this.#seededPrefixCount) : [];
+		const seededPrefixLength = this.#seededPrefixCount;
 		const includesSeedPrefix =
-			seededPrefix.length > 0 &&
-			normalizedMessages.length >= seededPrefix.length &&
-			this.#computeDigest(normalizedMessages.slice(0, seededPrefix.length)) === this.#computeDigest(seededPrefix);
+			seededPrefixLength > 0 &&
+			normalizedMessages.length >= seededPrefixLength &&
+			this.#computeDigestRange(normalizedMessages, 0, seededPrefixLength).source ===
+				this.#computeDigestRange(this.log.entries(), 0, seededPrefixLength).source;
 		const messagesToSync =
-			seededPrefix.length > 0 && !includesSeedPrefix ? [...seededPrefix, ...normalizedMessages] : normalizedMessages;
+			seededPrefixLength > 0 && !includesSeedPrefix
+				? [...this.log.entries().slice(0, seededPrefixLength), ...normalizedMessages]
+				: normalizedMessages;
 
 		// Detect in-place rewrites of already-synced messages.
 		if (
 			this.#lastSyncCount > 0 &&
 			this.#lastSyncCount <= messagesToSync.length &&
-			this.#computeDigest(messagesToSync.slice(0, this.#lastSyncCount)) !== this.#syncedDigest
+			this.#computeDigestRange(messagesToSync, 0, this.#lastSyncCount).source !== this.#syncedDigest.source
 		) {
 			if (this.#seededPrefixCount > 0) {
 				throw new Error("AppendOnlyContextManager.syncMessages() seed prefix changed");
@@ -266,7 +293,7 @@ export class AppendOnlyContextManager {
 		this.prefix.invalidate();
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = 0;
+		this.#syncedDigest = emptyMessageDigest();
 		this.#seededPrefixCount = 0;
 	}
 
@@ -274,7 +301,7 @@ export class AppendOnlyContextManager {
 	resetSyncCursor(): void {
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = 0;
+		this.#syncedDigest = emptyMessageDigest();
 		this.#seededPrefixCount = 0;
 	}
 
@@ -294,36 +321,28 @@ export class AppendOnlyContextManager {
 		this.prefix.invalidate();
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = 0;
+		this.#syncedDigest = emptyMessageDigest();
 		this.#seededPrefixCount = 0;
 		this.prefix.build(context, options);
 	}
 
 	/**
-	 * Deterministic digest over every field the provider may serialize — role,
-	 * content, tool calls (both `toolCalls` and OpenAI-wire `tool_calls`),
-	 * `tool_call_id`, `name`, `id`. Hashed with the same FNV-style rolling
-	 * accumulator so in-place rewrites of *any* of these fields are visible.
+	 * Deterministic digest over the provider-visible message payload. The source
+	 * string is kept and compared for equality so the hash is only a fast summary,
+	 * never the authority for accepting append-only sync state.
 	 */
-	#computeDigest(messages: readonly unknown[]): number {
-		let hash = 0;
-		for (let i = 0; i < messages.length; i++) {
-			const msg = messages[i];
-			if (!msg || typeof msg !== "object") continue;
-			const m = msg as Record<string, unknown>;
-			const payload = JSON.stringify({
-				r: m.role ?? null,
-				c: m.content ?? null,
-				tc: m.toolCalls ?? m.tool_calls ?? null,
-				tcid: m.tool_call_id ?? null,
-				n: m.name ?? null,
-				id: m.id ?? null,
-			});
-			for (let j = 0; j < payload.length; j++) {
-				hash = ((hash << 5) - hash + payload.charCodeAt(j)) | 0;
-			}
+	#computeDigest(messages: readonly unknown[]): MessageDigest {
+		return this.#computeDigestRange(messages, 0, messages.length);
+	}
+
+	#computeDigestRange(messages: readonly unknown[], start: number, end: number): MessageDigest {
+		let source = "[";
+		for (let i = start; i < end; i++) {
+			if (i > start) source += ",";
+			source += JSON.stringify(messages[i]) ?? "null";
 		}
-		return hash >>> 0;
+		source += "]";
+		return { hash: hashSource(source), source };
 	}
 }
 
@@ -331,6 +350,27 @@ export class AppendOnlyContextManager {
 // Snapshot helpers
 // ---------------------------------------------------------------------------
 
+type MessageDigest = {
+	hash: number | bigint;
+	source: string;
+};
+
+function emptyMessageDigest(): MessageDigest {
+	return { hash: hashSource("[]"), source: "[]" };
+}
+
+function hashSource(source: string): number | bigint {
+	return typeof Bun !== "undefined" ? Bun.hash(source) : hashString32(source);
+}
+
+function hashString32(value: string): number {
+	let hash = 0;
+	for (let i = 0; i < value.length; i++) {
+		hash = ((hash << 5) - hash + value.charCodeAt(i)) | 0;
+	}
+	return hash >>> 0;
+}
+
 function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
 	const systemPrompt = [...context.systemPrompt];
 	const tools = normalizeTools(context.tools, options.intentTracing) ?? [];
@@ -347,8 +387,42 @@ function normalizeImportedTools(tools: readonly Tool[], options: BuildOptions):
 	return cloneJson(normalizedTools);
 }
 
-function cloneJson<T>(value: T): T {
-	return JSON.parse(JSON.stringify(value)) as T;
+export function cloneJson<T>(value: T): T {
+	return cloneJsonValue(value) as T;
+}
+
+function cloneJsonValue(value: unknown, key = "", applyToJson = true): unknown {
+	if (value === null) return null;
+	const type = typeof value;
+	if (type === "number") return Number.isFinite(value) ? value : null;
+	// JSON.stringify drops function/symbol/undefined values (object props
+	// omitted, array elements become null via the array walk below).
+	if (type === "undefined" || type === "function" || type === "symbol") return undefined;
+	if (type !== "object") return value;
+	if (applyToJson) {
+		// JSON.stringify performs a single Get of `toJSON` per holder/key and
+		// serializes the returned replacement WITHOUT re-dispatching the
+		// replacement's own toJSON at the same level (nested properties still
+		// dispatch normally). Mirror that exactly to keep byte parity.
+		const toJSON = (value as { toJSON?: unknown }).toJSON;
+		if (typeof toJSON === "function") {
+			return cloneJsonValue(toJSON.call(value, key), key, false);
+		}
+	}
+	if (Array.isArray(value)) {
+		const cloned: unknown[] = new Array(value.length);
+		for (let i = 0; i < value.length; i++) {
+			const item = Object.hasOwn(value, i) ? cloneJsonValue(value[i], String(i)) : undefined;
+			cloned[i] = item === undefined ? null : item;
+		}
+		return cloned;
+	}
+	const cloned: Record<string, unknown> = {};
+	for (const key of Object.keys(value as object)) {
+		const clonedValue = cloneJsonValue((value as Record<string, unknown>)[key], key);
+		if (clonedValue !== undefined) cloned[key] = clonedValue;
+	}
+	return cloned;
 }
 
 function computeFingerprint(systemPrompt: string[], tools: Tool[], options: BuildOptions): string {

package/src/compaction/compaction.ts

@@ -13,7 +13,6 @@ import {
 	type Model,
 	type Usage,
 } from "@gajae-code/ai";
-import { countTokens } from "@gajae-code/natives";
 import { logger, prompt } from "@gajae-code/utils";
 import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
 import type { AgentMessage, AgentTool } from "../types";
@@ -268,18 +267,97 @@ export function resolveThresholdTokens(
 const IMAGE_TOKEN_ESTIMATE = 1200;
 
 /**
- * Estimate token count for a message using cl100k_base via the native
- * tokenizer. This is not Anthropic's first-party tokenizer (Anthropic doesn't
- * publish one) but is within ~5–10% across English/code text.
+ * Lazily-required native `countTokens`. `@gajae-code/natives` dlopens a ~39MB
+ * addon; importing it at module scope would put that cost on every cold path
+ * that touches compaction exports (status line, print mode, context report).
+ * Deferring the require to the first context-changing call keeps the trivial
+ * `-p` / display paths native-free.
  */
-export function estimateTokens(message: AgentMessage): number {
+let cachedNativeCountTokens: ((input: string | string[], encoding?: unknown) => number) | null = null;
+
+function nativeCountTokens(fragments: string[]): number {
+	if (!cachedNativeCountTokens) {
+		const { createRequire } = require("node:module") as typeof import("node:module");
+		const requireFromHere = createRequire(import.meta.url);
+		const natives = requireFromHere("@gajae-code/natives") as {
+			countTokens: (input: string | string[], encoding?: unknown) => number;
+		};
+		cachedNativeCountTokens = natives.countTokens;
+	}
+	return cachedNativeCountTokens(fragments);
+}
+
+function countCollectedMessageFragments(collected: { fragments: string[]; extra: number }): number {
+	return nativeCountTokens(collected.fragments) + collected.extra;
+}
+
+/**
+ * Estimate token count for a message using the native o200k tokenizer.
+ * Exact for o200k only; an approximation for Anthropic/other model families
+ * (Anthropic doesn't publish a tokenizer) within ~5–10% on English/code text.
+ *
+ * This materializes the native BPE table (~50MB RSS) on first call. Use it
+ * only for context-changing decisions (compaction trigger/cut points, pruning
+ * budgets, branch summarization, fork-context seeding, context-limit
+ * enforcement). For display-only totals use
+ * {@link estimateMessageTokensHeuristic}.
+ */
+export function countMessageTokensNativeO200k(message: AgentMessage): number {
+	return countCollectedMessageFragments(collectMessageFragments(message));
+}
+
+/**
+ * Backwards-compatible alias for {@link countMessageTokensNativeO200k}.
+ * Existing callers treat this as the canonical message-token estimator for
+ * context-changing decisions.
+ */
+export const estimateTokens = countMessageTokensNativeO200k;
+
+/**
+ * Average bytes per token for the cheap heuristic. ~4 bytes/token is the
+ * conventional approximation for English/code text under modern BPE
+ * vocabularies; it intentionally errs slightly low-precision in exchange for
+ * never touching the native tokenizer (and its ~50MB BPE table).
+ */
+const HEURISTIC_BYTES_PER_TOKEN = 4;
+
+/**
+ * Cheap, native-free token estimate for a message. Suitable ONLY for
+ * display/init surfaces (status line, /context report, HUD totals) — never
+ * for context-changing decisions, which must use
+ * {@link countMessageTokensNativeO200k}.
+ */
+export function estimateMessageTokensHeuristic(message: AgentMessage): number {
+	const { fragments, extra } = collectMessageFragments(message);
+	let bytes = 0;
+	for (const fragment of fragments) {
+		bytes += fragment.length;
+	}
+	return extra + Math.ceil(bytes / HEURISTIC_BYTES_PER_TOKEN);
+}
+
+/**
+ * Cheap, native-free token estimate for plain string fragments. Display-only
+ * counterpart of the native `countTokens(fragments)` aggregate.
+ */
+export function estimateTextTokensHeuristic(fragments: string | readonly string[]): number {
+	if (typeof fragments === "string") return Math.ceil(fragments.length / HEURISTIC_BYTES_PER_TOKEN);
+	let bytes = 0;
+	for (const fragment of fragments) {
+		bytes += fragment.length;
+	}
+	return Math.ceil(bytes / HEURISTIC_BYTES_PER_TOKEN);
+}
+
+/** Shared content walk for both the native and heuristic estimators. */
+function collectMessageFragments(message: AgentMessage): { fragments: string[]; extra: number } {
 	const fragments: string[] = [];
 	let extra = 0;
 	if ((message as { role?: string }).role === "bashExecution") {
 		const bash = message as { command?: unknown; output?: unknown };
 		if (typeof bash.command === "string") fragments.push(bash.command);
 		if (typeof bash.output === "string") fragments.push(bash.output);
-		return fragments.length === 0 ? 0 : countTokens(fragments);
+		return { fragments, extra };
 	}
 
 	switch (message.role) {
@@ -331,20 +409,45 @@ export function estimateTokens(message: AgentMessage): number {
 			break;
 		}
 		default:
-			return 0;
+			break;
+	}
+
+	return { fragments, extra };
+}
+
+function entryTokenFingerprint(
+	entry: SessionEntry,
+	message: AgentMessage,
+	collected: { fragments: string[]; extra: number },
+): string {
+	const maybePruned = message as { prunedAt?: unknown };
+	let fingerprint = `${entry.type.length}:${entry.type}${(entry.id ?? "").length}:${entry.id ?? ""}${message.role.length}:${message.role}${String(collected.extra).length}:${String(collected.extra)}${collected.fragments.length}:`;
+	for (const fragment of collected.fragments) fingerprint += `${fragment.length}:${fragment}`;
+	if (maybePruned.prunedAt !== undefined) {
+		const prunedAt = String(maybePruned.prunedAt);
+		fingerprint += `prunedAt${prunedAt.length}:${prunedAt}`;
 	}
+	return fingerprint;
+}
 
-	if (fragments.length === 0) return extra;
-	return extra + countTokens(fragments);
+const entryTokenCache = new WeakMap<SessionEntry, { fingerprint: string; tokens: number }>();
+
+export function estimateEntryTokens(entry: SessionEntry): number {
+	const msg = getMessageFromEntry(entry);
+	if (!msg) return 0;
+	const collected = collectMessageFragments(msg);
+	const fingerprint = entryTokenFingerprint(entry, msg, collected);
+	const cached = entryTokenCache.get(entry);
+	if (cached?.fingerprint === fingerprint) return cached.tokens;
+	const tokens = countCollectedMessageFragments(collected);
+	entryTokenCache.set(entry, { fingerprint, tokens });
+	return tokens;
 }
 
-function estimateEntriesTokens(entries: SessionEntry[], startIndex: number, endIndex: number): number {
+export function estimateEntriesTokens(entries: SessionEntry[], startIndex: number, endIndex: number): number {
 	let total = 0;
 	for (let i = startIndex; i < endIndex; i++) {
-		const msg = getMessageFromEntry(entries[i]);
-		if (msg) {
-			total += estimateTokens(msg);
-		}
+		total += estimateEntryTokens(entries[i]);
 	}
 	return total;
 }
@@ -461,18 +564,23 @@ export function findCutPoint(
 		if (entry.type !== "message") continue;
 
 		// Estimate this message's size
-		const messageTokens = estimateTokens(entry.message);
+		const messageTokens = estimateEntryTokens(entry);
 		accumulatedTokens += messageTokens;
 
 		// Check if we've exceeded the budget
 		if (accumulatedTokens >= keepRecentTokens) {
 			// Find the closest valid cut point at or after this entry
+			let foundCutPoint = false;
 			for (let c = 0; c < cutPoints.length; c++) {
 				if (cutPoints[c] >= i) {
 					cutIndex = cutPoints[c];
+					foundCutPoint = true;
 					break;
 				}
 			}
+			if (!foundCutPoint) {
+				cutIndex = cutPoints[cutPoints.length - 1];
+			}
 			break;
 		}
 	}

package/src/compaction/entries.ts

@@ -24,6 +24,12 @@ export interface ModelChangeEntry extends SessionEntryBase {
 	model: string;
 	/** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
 	role?: string;
+	/** Requested model before a runtime substitution/fallback, in "provider/modelId" format. */
+	previousModel?: string;
+	/** Machine-readable reason for runtime model substitution/fallback. */
+	reason?: string;
+	/** Effective thinking level when the change was recorded. */
+	thinkingLevel?: string | null;
 }
 
 export interface ServiceTierChangeEntry extends SessionEntryBase {

package/src/compaction/openai.ts

@@ -154,7 +154,7 @@ export function withOpenAiRemoteCompactionPreserveData(
 // Input/output filtering for OpenAI compact endpoint
 // ============================================================================
 
-function estimateOpenAiCompactInputTokens(input: Array<Record<string, unknown>>, instructions: string): number {
+export function estimateOpenAiCompactInputTokens(input: Array<Record<string, unknown>>, instructions: string): number {
 	let chars = instructions.length;
 	for (const item of input) {
 		chars += JSON.stringify(item).length;
@@ -200,22 +200,31 @@ function shouldKeepOpenAiCompactOutputItem(item: Record<string, unknown>): boole
 	return shouldKeepOpenAiCompactOutputUserMessage(item);
 }
 
-function trimOpenAiCompactInput(
+export function trimOpenAiCompactInput(
 	input: Array<Record<string, unknown>>,
 	contextWindow: number,
 	instructions: string,
 ): Array<Record<string, unknown>> {
+	const itemLengths = input.map(item => JSON.stringify(item).length);
+	let chars = instructions.length;
+	for (const length of itemLengths) chars += length;
+
+	function removeAt(index: number): void {
+		chars -= itemLengths[index] ?? 0;
+		trimmed.splice(index, 1);
+		itemLengths.splice(index, 1);
+	}
 	const trimmed = [...input];
-	while (trimmed.length > 0 && estimateOpenAiCompactInputTokens(trimmed, instructions) > contextWindow) {
+	while (trimmed.length > 0 && Math.ceil(chars / 4) > contextWindow) {
 		const last = trimmed[trimmed.length - 1];
 		if (last?.type === "function_call_output" || last?.type === "custom_tool_call_output") {
 			const callId = typeof last.call_id === "string" ? last.call_id : undefined;
 			const callType = last.type === "custom_tool_call_output" ? "custom_tool_call" : "function_call";
-			trimmed.pop();
+			removeAt(trimmed.length - 1);
 			if (callId) {
 				const matchingCallIndex = trimmed.findLastIndex(item => item.type === callType && item.call_id === callId);
 				if (matchingCallIndex >= 0) {
-					trimmed.splice(matchingCallIndex, 1);
+					removeAt(matchingCallIndex);
 				}
 			}
 			continue;
@@ -223,7 +232,7 @@ function trimOpenAiCompactInput(
 		if (!last || !shouldTrimOpenAiCompactInputItem(last)) {
 			break;
 		}
-		trimmed.pop();
+		removeAt(trimmed.length - 1);
 	}
 	return trimmed;
 }

package/src/compaction/pruning.ts

@@ -1,10 +1,16 @@
 /**
  * Tool output pruning utilities for compaction.
+ *
+ * Candidate selection is staleness-aware: tool results that have been
+ * superseded by a later result for the same target (same file read again,
+ * same search re-run) or invalidated by a later successful edit/write to a
+ * covered file are pruned in preference to merely-old results. Protect-window
+ * and minimum-savings hysteresis semantics are unchanged.
  */
 
-import type { ToolResultMessage } from "@gajae-code/ai";
+import type { ToolCall, ToolResultMessage } from "@gajae-code/ai";
 import type { AgentMessage } from "../types";
-import { estimateTokens } from "./compaction";
+import { estimateEntryTokens } from "./compaction";
 import type { SessionEntry, SessionMessageEntry } from "./entries";
 
 export interface PruneConfig {
@@ -14,23 +20,100 @@ export interface PruneConfig {
 	minimumSavings: number;
 	/** Tool names that should never be pruned. */
 	protectedTools: string[];
+	/**
+	 * Tools in `protectedTools` whose protection is waived once the result is
+	 * superseded (a later result for the same target, or a later successful
+	 * edit/write to the covered file). The most recent result per target is
+	 * never considered superseded. Optional; defaults to none.
+	 */
+	staleOverridableTools?: string[];
 }
 
 export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
 	protectTokens: 40_000,
 	minimumSavings: 20_000,
 	protectedTools: ["skill", "read"],
+	staleOverridableTools: ["read"],
 };
 
 export interface PruneResult {
 	prunedCount: number;
 	tokensSaved: number;
+	/**
+	 * The mutated message entries. Callers whose entry source returns
+	 * materialized copies (not live references) must write these back into
+	 * their canonical store by id.
+	 */
+	prunedEntries: SessionMessageEntry[];
 }
 
-function createPrunedNotice(tokens: number): string {
+const DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER = 1.25;
+
+function createGenericPrunedNotice(tokens: number): string {
 	return `[Output truncated - ${tokens} tokens]`;
 }
 
+function firstTextContent(message: ToolResultMessage): string {
+	if (typeof message.content === "string") return message.content;
+	const block = message.content.find(part => part.type === "text");
+	return block?.type === "text" ? block.text : "";
+}
+
+function firstErrorLine(text: string): string | undefined {
+	return text
+		.split(/\r?\n/)
+		.find(line => /error|failed|exception|panic/i.test(line))
+		?.trim();
+}
+
+function truncateField(value: string, maxLength: number): string {
+	if (value.length <= maxLength) return value;
+	if (maxLength <= 1) return "…";
+	return `${value.slice(0, maxLength - 1)}…`;
+}
+
+function resultDigest(message: ToolResultMessage): string | undefined {
+	const toolName = message.toolName.toLowerCase();
+	const text = firstTextContent(message);
+	if (toolName === "bash") {
+		const details = message as { details?: { exitCode?: unknown } };
+		const exitCode =
+			typeof details.details?.exitCode === "number" ? details.details.exitCode : message.isError ? 1 : 0;
+		const tail = text.trim().split(/\r?\n/).filter(Boolean).at(-1) ?? "";
+		const error = firstErrorLine(text);
+		return [`exit=${exitCode}`, tail ? `tail=${tail}` : undefined, error ? `error=${error}` : undefined]
+			.filter((part): part is string => part !== undefined)
+			.join("; ");
+	}
+	if (toolName === "search" || toolName === "grep") {
+		const match = text.match(/(\d+)\s+matches?/i) ?? text.match(/totalMatches["']?:\s*(\d+)/i);
+		const files = text.match(/(\d+)\s+files?/i) ?? text.match(/filesWithMatches["']?:\s*(\d+)/i);
+		const error = firstErrorLine(text);
+		return (
+			[
+				match ? `matches=${match[1]}` : undefined,
+				files ? `files=${files[1]}` : undefined,
+				error ? `error=${error}` : undefined,
+			]
+				.filter((part): part is string => part !== undefined)
+				.join("; ") || "search digest unavailable"
+		);
+	}
+	return undefined;
+}
+
+function createPrunedNotice(tokens: number, message?: ToolResultMessage): string {
+	const generic = createGenericPrunedNotice(tokens);
+	const digest = message ? resultDigest(message) : undefined;
+	if (!digest) return generic;
+	const genericTokens = Math.ceil(generic.length / 4);
+	const maxTokens = Math.max(genericTokens, Math.floor(genericTokens * DIGEST_NOTICE_TOKEN_CAP_MULTIPLIER));
+	const prefix = `[Output truncated - ${tokens} tokens; `;
+	const suffix = "]";
+	const maxChars = Math.max(0, maxTokens * 4 - prefix.length - suffix.length);
+	return `${prefix}${truncateField(digest, maxChars)}${suffix}`;
+}
+
 function getToolResultMessage(entry: SessionEntry): ToolResultMessage | undefined {
 	if (entry.type !== "message") return undefined;
 	const message = entry.message as AgentMessage;
@@ -38,55 +121,311 @@ function getToolResultMessage(entry: SessionEntry): ToolResultMessage | undefine
 	return message as ToolResultMessage;
 }
 
-function estimatePrunedSavings(tokens: number): number {
-	const noticeTokens = Math.ceil(createPrunedNotice(tokens).length / 4);
+function estimatePrunedSavings(tokens: number, notice: string): number {
+	const noticeTokens = Math.ceil(notice.length / 4);
 	return Math.max(0, tokens - noticeTokens);
 }
 
+const EDIT_TOOL_NAMES = new Set(["edit", "write", "apply_patch", "ast_edit"]);
+
+/** Extract the file-path argument from a tool call, when the tool has one. */
+function toolCallPath(call: ToolCall): string | undefined {
+	const args = call.arguments;
+	const path = args.path ?? args.file_path ?? args.filePath;
+	return typeof path === "string" && path.length > 0 ? path : undefined;
+}
+
+/**
+ * `*** Add|Update|Delete File: <path>` headers open a hunk; `*** Move to:
+ * <path>` attaches a rename destination to the current hunk. Move
+ * destinations count as touched paths: a rename onto a file invalidates
+ * earlier reads of that destination.
+ */
+const APPLY_PATCH_HEADER = /^\*\*\* (?:((?:Add|Update|Delete) File)|(Move to)): (.+)$/gm;
+
+/**
+ * Paths touched by an edit-class tool call, grouped per hunk so a failed
+ * hunk can be excluded wholesale (its rename destination included). Most
+ * edit tools carry a single path argument; apply_patch envelopes carry an
+ * `input` string with per-file headers instead. The envelope shape can
+ * arrive under the custom `apply_patch` tool OR the regular `edit` tool
+ * (providers without custom-tool support fall back to the JSON function), so
+ * any edit-class call with a string `input` is parsed for headers.
+ */
+function editToolPathGroups(call: ToolCall): string[][] {
+	const path = toolCallPath(call);
+	if (path !== undefined) return [[path]];
+	const input = call.arguments.input;
+	if (typeof input !== "string") return [];
+	const groups: string[][] = [];
+	for (const match of input.matchAll(APPLY_PATCH_HEADER)) {
+		const headerPath = match[3]?.trim();
+		if (!headerPath) continue;
+		const isMoveTo = match[2] !== undefined;
+		if (isMoveTo && groups.length > 0) {
+			groups[groups.length - 1].push(headerPath);
+		} else {
+			groups.push([headerPath]);
+		}
+	}
+	return groups;
+}
+
+/**
+ * Trailing read selectors (`:50`, `:50-200`, `:50+150`, `:5-16,960-973`,
+ * `:raw`, `:conflicts`), possibly stacked (`:2-4:raw`). Stripped to resolve
+ * the underlying file for edit invalidation.
+ */
+const READ_SELECTOR_SUFFIX = /:(?:raw|conflicts|\d+(?:[-+]\d+)?(?:,\d+(?:[-+]\d+)?)*)$/;
+
+/** Base file path of a read target with any line/mode selectors stripped. */
+function readBasePath(path: string): string {
+	let base = path;
+	while (READ_SELECTOR_SUFFIX.test(base)) {
+		base = base.replace(READ_SELECTOR_SUFFIX, "");
+	}
+	return base;
+}
+
+/**
+ * Stable identity for "the same logical lookup": same tool re-targeting the
+ * same subject. A later result with the same key supersedes earlier ones.
+ * Keys are canonical JSON tuples so user-controlled text (patterns, paths)
+ * can never collide via delimiter ambiguity. Search keys include pagination
+ * (`skip`) and result-shaping flags (`i`, `gitignore`): a later page or a
+ * differently-shaped search complements earlier output, it does not replace it.
+ */
+function toolTargetKey(call: ToolCall): string | undefined {
+	const path = toolCallPath(call);
+	if (path !== undefined) return JSON.stringify([call.name, "path", path]);
+	const pattern = call.arguments.pattern;
+	if (typeof pattern === "string" && pattern.length > 0) {
+		const paths = call.arguments.paths;
+		const pathList = Array.isArray(paths) ? paths.filter((p): p is string => typeof p === "string") : [];
+		const skip = typeof call.arguments.skip === "number" ? call.arguments.skip : 0;
+		const caseInsensitive = call.arguments.i === true;
+		const gitignore = call.arguments.gitignore !== false;
+		return JSON.stringify([call.name, "pattern", pattern, pathList, skip, caseInsensitive, gitignore]);
+	}
+	return undefined;
+}
+
+/**
+ * Files actually mutated according to a tool result's details. Used for
+ * AST-edit-shaped results (`ast_edit` direct-apply and the hidden `resolve`
+ * apply step), which report `{ applied: true, files: [...] }` — the resolve
+ * tool nests that payload under `details.sourceResultDetails`. Conservative:
+ * returns nothing unless the details explicitly mark the change as applied.
+ * Checked even on `isError` results: a stale-preview apply reports an error
+ * while still having mutated the listed files.
+ */
+function resultDetailFiles(message: ToolResultMessage): string[] {
+	const raw = message.details as { applied?: unknown; files?: unknown; sourceResultDetails?: unknown } | undefined;
+	const candidates = [raw, raw?.sourceResultDetails as { applied?: unknown; files?: unknown } | undefined];
+	for (const details of candidates) {
+		if (details?.applied === true && Array.isArray(details.files)) {
+			return details.files.filter((file): file is string => typeof file === "string" && file.length > 0);
+		}
+	}
+	return [];
+}
+
+/**
+ * Paths that FAILED in a per-file edit result (`details.perFileResults`) and
+ * were NOT mutated by any same-path entry. Multi-file apply_patch catches
+ * per-file failures and still returns a non-error result; a purely-failed
+ * path was not mutated and must not stale reads. But apply_patch can emit
+ * multiple entries for the same path (e.g. several hunks): if any same-path
+ * entry succeeded the file still mutated, so it must NOT be suppressed.
+ * Conservative: only an entry explicitly marked `isError === true` counts as
+ * a failure; anything else (including ambiguous/malformed entries) counts as
+ * a success and keeps the path out of the suppression set.
+ */
+function failedEditPaths(message: ToolResultMessage): Set<string> {
+	const details = message.details as { perFileResults?: unknown } | undefined;
+	const perFile = details?.perFileResults;
+	if (!Array.isArray(perFile)) return new Set();
+	const failed = new Set<string>();
+	const succeeded = new Set<string>();
+	for (const item of perFile) {
+		const entry = item as { path?: unknown; isError?: unknown };
+		if (typeof entry?.path !== "string") continue;
+		if (entry.isError === true) failed.add(entry.path);
+		else succeeded.add(entry.path);
+	}
+	// A path mutated if any same-path entry succeeded, even when another
+	// same-path entry failed; drop those from the suppression set.
+	for (const path of succeeded) failed.delete(path);
+	return failed;
+}
+
+/**
+ * Concrete file path a `read` result actually came from, when the tool
+ * reported one (`details.resolvedPath`). Suffix resolution can map a bare
+ * filename argument onto a different concrete path.
+ */
+function readResolvedPath(message: ToolResultMessage): string | undefined {
+	const details = message.details as { resolvedPath?: unknown } | undefined;
+	const resolved = details?.resolvedPath;
+	return typeof resolved === "string" && resolved.length > 0 ? resolved : undefined;
+}
+
+interface StalenessIndex {
+	/** Entry indices of toolResults superseded by a later same-target result or a later edit. */
+	staleResultIndices: Set<number>;
+}
+
+/**
+ * Build a staleness index over session entries (oldest -> newest):
+ * - a toolResult is stale when a later non-error toolResult shares its target key;
+ * - a `read` result is stale when a later non-error edit/write touches its file.
+ * The most recent result per target is never stale.
+ */
+function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
+	const callsById = new Map<string, ToolCall>();
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		const message = entry.message as AgentMessage;
+		if (message.role !== "assistant") continue;
+		for (const content of message.content) {
+			if (content.type === "toolCall") callsById.set(content.id, content);
+		}
+	}
+
+	const lastResultIndexByKey = new Map<string, number>();
+	const resultMeta = new Map<number, { key?: string; call: ToolCall; message: ToolResultMessage }>();
+	const lastEditIndexByPath = new Map<string, number>();
+
+	for (let i = 0; i < entries.length; i++) {
+		const message = getToolResultMessage(entries[i]);
+		if (!message) continue;
+		const call = callsById.get(message.toolCallId);
+		if (!call) continue;
+
+		// AST edits mutate files when previews are applied via the hidden
+		// `resolve` tool; the call args carry globs, not concrete paths. Both
+		// tools report actually-touched files in result details. Collected
+		// BEFORE the error gate: a stale-preview apply reports an error while
+		// still having mutated the listed files.
+		if (call.name === "resolve" || call.name === "ast_edit") {
+			for (const editPath of resultDetailFiles(message)) {
+				lastEditIndexByPath.set(editPath, i);
+			}
+		}
+		if (message.isError) continue;
+
+		const key = toolTargetKey(call);
+		resultMeta.set(i, { key, call, message });
+		if (key !== undefined) lastResultIndexByKey.set(key, i);
+		if (EDIT_TOOL_NAMES.has(call.name)) {
+			// Per-file edit results record failures in details.perFileResults;
+			// a failed hunk mutated nothing, so exclude its whole path group
+			// (rename destination included) from touched paths.
+			const failed = failedEditPaths(message);
+			for (const group of editToolPathGroups(call)) {
+				if (group.some(groupPath => failed.has(groupPath))) continue;
+				for (const editPath of group) {
+					lastEditIndexByPath.set(editPath, i);
+				}
+			}
+		}
+	}
+
+	const staleResultIndices = new Set<number>();
+	for (const [index, meta] of resultMeta) {
+		if (meta.key !== undefined) {
+			const lastIndex = lastResultIndexByKey.get(meta.key);
+			if (lastIndex !== undefined && lastIndex > index) {
+				staleResultIndices.add(index);
+				continue;
+			}
+		}
+		if (meta.call.name === "read") {
+			// Check both the call argument (selectors stripped) and the resolved
+			// path from result details: suffix resolution can map a bare filename
+			// onto a different concrete path, and edits may use either form.
+			const lookupPaths = new Set<string>();
+			const argPath = toolCallPath(meta.call);
+			if (argPath !== undefined) lookupPaths.add(readBasePath(argPath));
+			const resolved = readResolvedPath(meta.message);
+			if (resolved !== undefined) lookupPaths.add(resolved);
+			for (const lookupPath of lookupPaths) {
+				const editIndex = lastEditIndexByPath.get(lookupPath);
+				if (editIndex !== undefined && editIndex > index) {
+					staleResultIndices.add(index);
+					break;
+				}
+			}
+		}
+	}
+
+	return { staleResultIndices };
+}
+
 export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
 	let accumulatedTokens = 0;
 	let tokensSaved = 0;
 	let prunedCount = 0;
 
-	const candidates: Array<{ entry: SessionMessageEntry; tokens: number }> = [];
+	const { staleResultIndices } = buildStalenessIndex(entries);
+	const staleOverridable = new Set(config.staleOverridableTools ?? []);
+	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; notice: string; savings: number }> = [];
 
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
 		const message = getToolResultMessage(entry);
 		if (!message) continue;
 
-		const tokens = estimateTokens(message as AgentMessage);
-		const isProtected = config.protectedTools.includes(message.toolName);
+		const tokens = estimateEntryTokens(entry);
+		const isStale = staleResultIndices.has(i);
+		// Staleness waives protected-tool immunity for overridable tools
+		// (e.g. a superseded `read`); the most recent result per target is
+		// never stale, so the latest read of each file stays protected.
+		const isProtected =
+			config.protectedTools.includes(message.toolName) && !(isStale && staleOverridable.has(message.toolName));
 
 		if (message.prunedAt !== undefined) {
 			accumulatedTokens += tokens;
 			continue;
 		}
 
-		if (accumulatedTokens < config.protectTokens || isProtected) {
+		// Stale results are prunable even inside the recency protect window —
+		// they are superseded, so recency no longer implies relevance. They
+		// still count toward window accounting so non-stale protection is
+		// unchanged.
+		const insideProtectWindow = accumulatedTokens < config.protectTokens;
+		if ((insideProtectWindow && !isStale) || isProtected) {
 			accumulatedTokens += tokens;
 			continue;
 		}
 
-		candidates.push({ entry: entry as SessionMessageEntry, tokens });
+		const notice = createPrunedNotice(tokens, message);
+		candidates.push({
+			entry: entry as SessionMessageEntry,
+			tokens,
+			notice,
+			savings: estimatePrunedSavings(tokens, notice),
+		});
 		accumulatedTokens += tokens;
 	}
 
 	for (const candidate of candidates) {
-		tokensSaved += estimatePrunedSavings(candidate.tokens);
+		tokensSaved += candidate.savings;
 	}
 
 	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
-		return { prunedCount: 0, tokensSaved: 0 };
+		return { prunedCount: 0, tokensSaved: 0, prunedEntries: [] };
 	}
 
 	const prunedAt = Date.now();
+	const prunedEntries: SessionMessageEntry[] = [];
 	for (const candidate of candidates) {
 		const message = candidate.entry.message as ToolResultMessage;
-		message.content = [{ type: "text", text: createPrunedNotice(candidate.tokens) }];
+		message.content = [{ type: "text", text: candidate.notice }];
 		message.prunedAt = prunedAt;
+		prunedEntries.push(candidate.entry);
 		prunedCount++;
 	}
 
-	return { prunedCount, tokensSaved };
+	return { prunedCount, tokensSaved, prunedEntries };
 }

package/src/types.ts

@@ -189,6 +189,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
 
+	/** Called for non-content tool-choice incapability stream events. */
+	onToolChoiceIncapability?: (event: Extract<AssistantMessageEvent, { type: "toolChoiceIncapability" }>) => void;
+
 	/**
 	 * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
 	 */