@gajae-code/agent-core 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-06-14
+
+- Version aligned with the 0.5.1 monorepo release; no functional changes in this package.
+
+## [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

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

@@ -97,6 +97,8 @@ export declare function estimateMessageTokensHeuristic(message: AgentMessage): n
  * counterpart of the native `countTokens(fragments)` aggregate.
  */
 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/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.5",
+	"version": "0.5.1",
 	"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.5",
-		"@gajae-code/natives": "0.4.5",
-		"@gajae-code/utils": "0.4.5",
+		"@gajae-code/ai": "0.5.1",
+		"@gajae-code/natives": "0.5.1",
+		"@gajae-code/utils": "0.5.1",
 		"@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;
@@ -1222,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

@@ -287,6 +287,10 @@ function nativeCountTokens(fragments: string[]): number {
 	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
@@ -299,9 +303,7 @@ function nativeCountTokens(fragments: string[]): number {
  * {@link estimateMessageTokensHeuristic}.
  */
 export function countMessageTokensNativeO200k(message: AgentMessage): number {
-	const { fragments, extra } = collectMessageFragments(message);
-	if (fragments.length === 0) return extra;
-	return extra + nativeCountTokens(fragments);
+	return countCollectedMessageFragments(collectMessageFragments(message));
 }
 
 /**
@@ -413,13 +415,39 @@ function collectMessageFragments(message: AgentMessage): { fragments: string[];
 	return { fragments, extra };
 }
 
-function estimateEntriesTokens(entries: SessionEntry[], startIndex: number, endIndex: number): number {
+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;
+}
+
+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;
+}
+
+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;
 }
@@ -536,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

@@ -10,7 +10,7 @@
 
 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 {
@@ -47,10 +47,73 @@ export interface PruneResult {
 	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;
@@ -58,8 +121,8 @@ 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);
 }
 
@@ -306,14 +369,14 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 
 	const { staleResultIndices } = buildStalenessIndex(entries);
 	const staleOverridable = new Set(config.staleOverridableTools ?? []);
-	const candidates: Array<{ entry: SessionMessageEntry; tokens: number }> = [];
+	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 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
@@ -336,12 +399,18 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 			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) {
@@ -352,7 +421,7 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 	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++;

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.
 	 */