@gajae-code/agent-core 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [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/compaction/compaction.d.ts

@@ -68,11 +68,35 @@ 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;
 /**
  * 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/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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.4.4",
+	"version": "0.4.5",
 	"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.4.5",
+		"@gajae-code/natives": "0.4.5",
+		"@gajae-code/utils": "0.4.5",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent.ts

@@ -680,7 +680,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 +693,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 +702,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 +711,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 +720,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 +729,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 +738,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 +747,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 +756,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);

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,95 @@ 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);
+}
+
+/**
+ * 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 {
+	const { fragments, extra } = collectMessageFragments(message);
+	if (fragments.length === 0) return extra;
+	return extra + nativeCountTokens(fragments);
+}
+
+/**
+ * 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,11 +407,10 @@ export function estimateTokens(message: AgentMessage): number {
 			break;
 		}
 		default:
-			return 0;
+			break;
 	}
 
-	if (fragments.length === 0) return extra;
-	return extra + countTokens(fragments);
+	return { fragments, extra };
 }
 
 function estimateEntriesTokens(entries: SessionEntry[], startIndex: number, endIndex: number): number {

package/src/compaction/pruning.ts

@@ -1,8 +1,14 @@
 /**
  * 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 type { SessionEntry, SessionMessageEntry } from "./entries";
@@ -14,17 +20,31 @@ 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 {
@@ -43,11 +63,249 @@ function estimatePrunedSavings(tokens: number): number {
 	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 { staleResultIndices } = buildStalenessIndex(entries);
+	const staleOverridable = new Set(config.staleOverridableTools ?? []);
 	const candidates: Array<{ entry: SessionMessageEntry; tokens: number }> = [];
 
 	for (let i = entries.length - 1; i >= 0; i--) {
@@ -56,14 +314,24 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 		if (!message) continue;
 
 		const tokens = estimateTokens(message as AgentMessage);
-		const isProtected = config.protectedTools.includes(message.toolName);
+		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;
 		}
@@ -77,16 +345,18 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 	}
 
 	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.prunedAt = prunedAt;
+		prunedEntries.push(candidate.entry);
 		prunedCount++;
 	}
 
-	return { prunedCount, tokensSaved };
+	return { prunedCount, tokensSaved, prunedEntries };
 }