@oh-my-pi/pi-agent-core 18.8.4 → 18.8.6

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [18.8.6] - 2026-10-08
+
+### Added
+
+- Added support for warm-cache-aware conversation pruning, keeping pruned history within the model’s prompt-cache lookback window while preserving Anthropic prompt-cache efficiency.
+- Added `AgentLoopConfig.hasQueuedAsides` (also available on `Agent`) to allow interruptible waits to detect queued asides without consuming them or signaling other tools.
+
 ## [18.8.1] - 2026-10-07
 
 ### Added

package/dist/types/agent.d.ts

@@ -270,6 +270,11 @@ export declare class Agent {
      * are queued for the next boundary.
      */
     hasBackgroundCompletions?: AgentLoopConfig["hasBackgroundCompletions"];
+    /**
+     * Hook that peeks whether a passive aside is queued for the next boundary;
+     * ends an interruptible wait without interrupting other tools.
+     */
+    hasQueuedAsides?: AgentLoopConfig["hasQueuedAsides"];
     constructor(opts?: AgentOptions);
     /**
      * Get the current session ID used for provider caching.
@@ -457,7 +462,8 @@ export declare class Agent {
     /**
      * Provide a source of non-interrupting "aside" messages (e.g. background-job
      * completions, late LSP diagnostics) drained at each step boundary. Never
-     * aborts in-flight tools. See `AgentLoopConfig.getAsideMessages`.
+     * aborts foreground tools; an interruptible `wait` may end early through the
+     * peek hooks. See `AgentLoopConfig.getAsideMessages`.
      */
     setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void;
     emitExternalEvent(event: AgentEvent): void;

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

@@ -1,5 +1,6 @@
 import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "@oh-my-pi/pi-ai";
 import type { AgentMessage } from "../types.js";
+import type { SessionEntry } from "./entries.js";
 export interface CustomMessage<T = unknown> {
     role: "custom";
     customType: string;
@@ -110,3 +111,8 @@ export declare function convertMessageToLlm(message: AgentMessage): Message | un
  * core LLM roles and the compaction messages owned by this package.
  */
 export declare function defaultConvertToLlm(messages: AgentMessage[]): Message[];
+/**
+ * The context message a session entry contributes, or `undefined` for entries
+ * that don't reach the LLM (compaction markers, labels, model changes, ...).
+ */
+export declare function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined;

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

@@ -4,8 +4,26 @@
 import type { ToolResultMessage } from "@oh-my-pi/pi-ai";
 import type { Tokenizer } from "../tokenizer.js";
 import type { SessionEntry } from "./entries.js";
+import { type ConvertToLlm } from "./messages.js";
 import { type ProtectedToolMatcher } from "./tool-protection.js";
-export interface PruneConfig {
+/** Bound warm-cache pruning by the provider's prompt-cache lookback window. */
+export interface CacheLookbackConfig {
+    /**
+     * Prompt-cache lookback of the model the next request goes to, in block
+     * positions (catalog `prompt-cache-lookback`; Anthropic: 20). When set,
+     * warm-cache pruning also leaves a result whose rewrite would put the next
+     * request's cache lookup out of reach, whatever its token suffix (see
+     * `cacheLookbackFloor`). Undefined = no lookback bound.
+     */
+    cacheLookbackPositions?: number;
+    /**
+     * Projects context messages to what the provider receives, so lookback
+     * positions count app roles (file mentions, command output, custom
+     * messages) as sent. Default {@link defaultConvertToLlm}.
+     */
+    convertToLlm?: ConvertToLlm;
+}
+export interface PruneConfig extends CacheLookbackConfig {
     /** Keep the most recent tool output tokens intact. */
     protectTokens: number;
     /** Only prune if total savings meets this threshold. */
@@ -37,7 +55,8 @@ export interface PruneConfig {
      * already-sent cache prefix: mutating it forces the provider to re-write the
      * whole suffix (cacheWrite premium). Such results — including superseded and
      * useless ones, which otherwise bypass {@link protectTokens} — are left for
-     * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+     * compaction/shake (which rebuild the cache anyway) to reclaim, as are
+     * results beyond {@link CacheLookbackConfig.cacheLookbackPositions}. Undefined =
      * no cache guard (legacy: superseded/useless prune at any depth).
      */
     cacheWarmSuffixTokens?: number;
@@ -72,7 +91,7 @@ export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) =
  * range reads). A summary, truncated page, or notice is not complete.
  */
 export type SupersedeCompleteFn = (message: ToolResultMessage) => boolean;
-export interface SupersedePruneConfig {
+export interface SupersedePruneConfig extends CacheLookbackConfig {
     /** Supersede key function; a newer successful result with the same key supersedes older ones (see {@link SupersedeKeyFn}). */
     supersedeKey?: SupersedeKeyFn;
     /**
@@ -90,7 +109,11 @@ export interface SupersedePruneConfig {
     supersedeComplete?: SupersedeCompleteFn;
     /** Also prune results flagged useless by their tool. Default false. */
     pruneUseless?: boolean;
-    /** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
+    /**
+     * Prune a candidate now when all messages after it total at most this many
+     * estimated tokens and it sits within
+     * {@link CacheLookbackConfig.cacheLookbackPositions}. Default 8 000.
+     */
     suffixTokenLimit?: number;
     /**
      * Prune all candidates when the last message is at least this old: the

package/dist/types/types.d.ts

@@ -269,6 +269,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * background.
      */
     hasBackgroundCompletions?: () => boolean | Promise<boolean>;
+    /**
+     * Peeks whether a passive aside (an extension or user message queued with
+     * `deliverAs: "aside"`) is waiting for injection at the next boundary.
+     *
+     * Same rules as {@link hasBackgroundCompletions}: non-consuming, ends only
+     * *interruptible* waits, never raises {@link ToolCallContext.steeringSignal}.
+     * The host still injects the aside once at the boundary; ordinary running
+     * tools finish first.
+     */
+    hasQueuedAsides?: () => boolean | Promise<boolean>;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *
@@ -281,7 +291,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Returns non-interrupting "aside" messages to inject at a step boundary.
      *
      * Polled after each tool batch (before the next LLM call) AND at the yield
-     * check. Unlike steering, these NEVER abort in-flight tools — they are passive
+     * check. Unlike steering, these never abort foreground tools (only an
+     * interruptible `wait` ends early, via the peek hooks) — they are passive
      * notifications (e.g. background-job completions, late LSP diagnostics) that
      * should reach the model between requests without waiting for the agent to
      * fully stop. Returned messages are appended to the context with normal

package/package.json

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

package/src/agent-loop.ts

@@ -3204,6 +3204,7 @@ async function executeToolCalls(
 		hasSteeringMessages,
 		hasIrcInterrupts,
 		hasBackgroundCompletions,
+		hasQueuedAsides,
 		interruptMode = "immediate",
 		getToolContext,
 
@@ -3305,11 +3306,12 @@ async function executeToolCalls(
 		// (only when soft interrupts are enabled; otherwise nothing is left).
 		if (signal?.aborted) return;
 		if (interruptState.triggered && (!softInterrupts || steeringSoftController.signal.aborted)) return;
-		// Peer IRC and background completions (finished jobs, exited supervised
-		// processes) hard-abort interruptible waits only; foreground tools keep
-		// running (no partial side effects).
+		// Peer IRC, queued asides and background completions (finished jobs,
+		// exited supervised processes) hard-abort interruptible waits only;
+		// foreground tools keep running (no partial side effects).
 		let source: AsideInterruptSource | undefined;
 		if (hasIrcInterrupts && (await hasIrcInterrupts())) source = "irc";
+		else if (!interruptState.triggered && hasQueuedAsides && (await hasQueuedAsides())) source = "aside";
 		else if (!interruptState.triggered && hasBackgroundCompletions && (await hasBackgroundCompletions()))
 			source = "background";
 		if (!source) return;
@@ -3326,7 +3328,7 @@ async function executeToolCalls(
 		// also cascades: the freshly detached job's own completion re-triggers
 		// this check for the next command, so millisecond-long commands chain
 		// into separate background deliveries (#12869).
-		if (source !== "background" && softInterrupts) steeringSoftController.abort();
+		if (source === "irc" && softInterrupts) steeringSoftController.abort();
 	};
 
 	const checkSteering = async (): Promise<void> => {
@@ -3697,7 +3699,8 @@ async function executeToolCalls(
 	// (auto-background bash), so the boundary dequeue below injects the message
 	// promptly. In "wait" mode only a batch holding an interruptible wait needs
 	// the watch; checkSteering is idempotent (no-op once triggered).
-	const hasAsidePeek = hasIrcInterrupts !== undefined || hasBackgroundCompletions !== undefined;
+	const hasAsidePeek =
+		hasIrcInterrupts !== undefined || hasBackgroundCompletions !== undefined || hasQueuedAsides !== undefined;
 	const watchSteeringWhileRunning =
 		(softInterrupts || records.some(record => record.interruptible)) &&
 		(hasSteeringMessages !== undefined || hasAsidePeek);
@@ -3983,8 +3986,8 @@ function createToolSignalAbortedResult(signal: AbortSignal): AgentToolResult<unk
 	};
 }
 
-/** Origin of a mid-batch interrupt: queued steering, a peer IRC, or a background completion notice. */
-type AsideInterruptSource = SteeringInterruptSource | "irc" | "background";
+/** Origin of a mid-batch interrupt: queued steering, a peer IRC, a queued aside, or a background completion notice. */
+type AsideInterruptSource = SteeringInterruptSource | "irc" | "aside" | "background";
 
 function createSkippedToolResult(
 	source: AsideInterruptSource | undefined,
@@ -4004,6 +4007,9 @@ function createSkippedToolResult(
 	} else if (source === "irc") {
 		reason = "pending peer interrupt";
 		blocker = "interrupt";
+	} else if (source === "aside") {
+		reason = "a queued aside message";
+		blocker = "aside";
 	} else if (source === "background") {
 		reason = "a queued background completion (job or supervised process)";
 		blocker = "completion notice";

package/src/agent.ts

@@ -539,6 +539,11 @@ export class Agent {
 	 * are queued for the next boundary.
 	 */
 	hasBackgroundCompletions?: AgentLoopConfig["hasBackgroundCompletions"];
+	/**
+	 * Hook that peeks whether a passive aside is queued for the next boundary;
+	 * ends an interruptible wait without interrupting other tools.
+	 */
+	hasQueuedAsides?: AgentLoopConfig["hasQueuedAsides"];
 
 	constructor(opts: AgentOptions = {}) {
 		this.#state = { ...this.#state, ...opts.initialState };
@@ -1174,7 +1179,8 @@ export class Agent {
 	/**
 	 * Provide a source of non-interrupting "aside" messages (e.g. background-job
 	 * completions, late LSP diagnostics) drained at each step boundary. Never
-	 * aborts in-flight tools. See `AgentLoopConfig.getAsideMessages`.
+	 * aborts foreground tools; an interruptible `wait` may end early through the
+	 * peek hooks. See `AgentLoopConfig.getAsideMessages`.
 	 */
 	setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void {
 		this.#asideMessageProvider = fn;
@@ -1913,6 +1919,7 @@ export class Agent {
 			onLiveSteeringTaken: messages => this.#adoptLiveSteering(messages),
 			hasIrcInterrupts: this.hasIrcInterrupts,
 			hasBackgroundCompletions: this.hasBackgroundCompletions,
+			hasQueuedAsides: this.hasQueuedAsides,
 			getFollowUpMessages: signal => this.#dequeueFollowUpMessagesAfterHooks(signal ?? loopSignal),
 			getAsideMessages: async () => (await this.#asideMessageProvider?.()) ?? [],
 			onBeforeYield: () => this.#onBeforeYield?.(),

package/src/compaction/compaction.ts

@@ -64,10 +64,9 @@ import type { CompactionEntry, SessionEntry } from "./entries";
 import { NativeCompactionError } from "./errors";
 import {
 	type ConvertToLlm,
-	createBranchSummaryMessage,
 	createCompactionSummaryMessage,
-	createCustomMessage,
 	defaultConvertToLlm,
+	getMessageFromEntry,
 } from "./messages";
 import {
 	assertRemoteCompactionInputFits,
@@ -142,34 +141,6 @@ function extractFileOperations(
 	return fileOps;
 }
 
-// ============================================================================
-// Message Extraction
-// ============================================================================
-
-/**
- * Extract AgentMessage from an entry if it produces one.
- * Returns undefined for entries that don't contribute to LLM context.
- */
-function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
-	if (entry.type === "message") {
-		return entry.message;
-	}
-	if (entry.type === "custom_message") {
-		return createCustomMessage(
-			entry.customType,
-			entry.content,
-			entry.display,
-			entry.details,
-			entry.timestamp,
-			entry.attribution,
-		);
-	}
-	if (entry.type === "branch_summary") {
-		return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
-	}
-	return undefined;
-}
-
 /** Result from compact() - SessionManager adds uuid/parentUuid when saving */
 export interface CompactionResult<T = unknown> {
 	summary: string;

package/src/compaction/messages.ts

@@ -8,6 +8,7 @@ import type {
 } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import type { AgentMessage } from "../types";
+import type { SessionEntry } from "./entries";
 import branchSummaryContextPrompt from "./prompts/branch-summary-context.md" with { type: "text" };
 import compactionSummaryContextPrompt from "./prompts/compaction-summary-context.md" with { type: "text" };
 import handoffSummaryContextPrompt from "./prompts/handoff-summary-context.md" with { type: "text" };
@@ -291,3 +292,27 @@ export function convertMessageToLlm(message: AgentMessage): Message | undefined
 export function defaultConvertToLlm(messages: AgentMessage[]): Message[] {
 	return messages.map(convertMessageToLlm).filter(message => message !== undefined);
 }
+
+/**
+ * The context message a session entry contributes, or `undefined` for entries
+ * that don't reach the LLM (compaction markers, labels, model changes, ...).
+ */
+export function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
+	if (entry.type === "message") {
+		return entry.message;
+	}
+	if (entry.type === "custom_message") {
+		return createCustomMessage(
+			entry.customType,
+			entry.content,
+			entry.display,
+			entry.details,
+			entry.timestamp,
+			entry.attribution,
+		);
+	}
+	if (entry.type === "branch_summary") {
+		return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
+	}
+	return undefined;
+}

package/src/compaction/pruning.ts

@@ -7,6 +7,7 @@ import type { Tokenizer } from "../tokenizer";
 import type { AgentMessage, AgentToolCall } from "../types";
 import type { SessionEntry, SessionMessageEntry } from "./entries";
 import { invalidateMessageCache } from "./message-cache";
+import { type ConvertToLlm, defaultConvertToLlm, getMessageFromEntry } from "./messages";
 import {
 	collectToolCallsById,
 	getToolResultMessage,
@@ -16,7 +17,25 @@ import {
 } from "./tool-protection";
 import { isAlternateFormReadSelector, splitReadSelector } from "./utils";
 
-export interface PruneConfig {
+/** Bound warm-cache pruning by the provider's prompt-cache lookback window. */
+export interface CacheLookbackConfig {
+	/**
+	 * Prompt-cache lookback of the model the next request goes to, in block
+	 * positions (catalog `prompt-cache-lookback`; Anthropic: 20). When set,
+	 * warm-cache pruning also leaves a result whose rewrite would put the next
+	 * request's cache lookup out of reach, whatever its token suffix (see
+	 * `cacheLookbackFloor`). Undefined = no lookback bound.
+	 */
+	cacheLookbackPositions?: number;
+	/**
+	 * Projects context messages to what the provider receives, so lookback
+	 * positions count app roles (file mentions, command output, custom
+	 * messages) as sent. Default {@link defaultConvertToLlm}.
+	 */
+	convertToLlm?: ConvertToLlm;
+}
+
+export interface PruneConfig extends CacheLookbackConfig {
 	/** Keep the most recent tool output tokens intact. */
 	protectTokens: number;
 	/** Only prune if total savings meets this threshold. */
@@ -48,7 +67,8 @@ export interface PruneConfig {
 	 * already-sent cache prefix: mutating it forces the provider to re-write the
 	 * whole suffix (cacheWrite premium). Such results — including superseded and
 	 * useless ones, which otherwise bypass {@link protectTokens} — are left for
-	 * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+	 * compaction/shake (which rebuild the cache anyway) to reclaim, as are
+	 * results beyond {@link CacheLookbackConfig.cacheLookbackPositions}. Undefined =
 	 * no cache guard (legacy: superseded/useless prune at any depth).
 	 */
 	cacheWarmSuffixTokens?: number;
@@ -117,7 +137,7 @@ export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) =
  */
 export type SupersedeCompleteFn = (message: ToolResultMessage) => boolean;
 
-export interface SupersedePruneConfig {
+export interface SupersedePruneConfig extends CacheLookbackConfig {
 	/** Supersede key function; a newer successful result with the same key supersedes older ones (see {@link SupersedeKeyFn}). */
 	supersedeKey?: SupersedeKeyFn;
 	/**
@@ -135,7 +155,11 @@ export interface SupersedePruneConfig {
 	supersedeComplete?: SupersedeCompleteFn;
 	/** Also prune results flagged useless by their tool. Default false. */
 	pruneUseless?: boolean;
-	/** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
+	/**
+	 * Prune a candidate now when all messages after it total at most this many
+	 * estimated tokens and it sits within
+	 * {@link CacheLookbackConfig.cacheLookbackPositions}. Default 8 000.
+	 */
 	suffixTokenLimit?: number;
 	/**
 	 * Prune all candidates when the last message is at least this old: the
@@ -160,6 +184,99 @@ export interface SupersedePruneConfig {
 const DEFAULT_SUFFIX_TOKEN_LIMIT = 8_000;
 const DEFAULT_IDLE_FLUSH_MS = 30 * 60_000;
 
+/**
+ * Positions kept free for the next request's own input (prompt, date/cwd
+ * reminder, attachments) and for request projections the count below does not
+ * model (orphan-result notes, replayed compaction file metadata, tool-change
+ * controls): with Anthropic's 20, stored history gets at most 13.
+ */
+const RESERVED_LOOKBACK_POSITIONS = 6;
+
+type LookbackBlock = "tool_use" | "tool_result" | undefined;
+
+/**
+ * Index of the oldest tool result that can be rewritten while the next request
+ * still reaches a cache entry, given the model's prompt-cache `lookback` in
+ * block positions (a breakpoint counts itself; a run of consecutive `tool_use`
+ * blocks, or of consecutive `tool_result` blocks, is one position). A
+ * conservative estimate, not an exact count: a skipped prune costs its tokens,
+ * a missed lookup the whole cache.
+ *
+ * Each request writes its tail cache entry at its last block, so rewriting a
+ * result invalidates every entry from its issuing assistant turn on, and once a
+ * request has 15 user turns its other breakpoint sits on an older decimation
+ * checkpoint. The next request's tail breakpoint then reaches the newest
+ * surviving entry, which ends the message before the issuing turn, only when
+ * the issuing turn, its tool-result batch, everything after and the next input
+ * fit in the lookback window; otherwise the lookup falls back to that
+ * checkpoint and the whole conversation since is re-written, not the small
+ * suffix the token limits budget for. Each entry is projected through
+ * `convertToLlm` and counted the way the Anthropic request converter emits it.
+ */
+function cacheLookbackFloor(
+	entries: readonly SessionEntry[],
+	start: number,
+	lookback: number | undefined,
+	convertToLlm: ConvertToLlm,
+): number {
+	if (lookback === undefined) return start;
+	let positions = RESERVED_LOOKBACK_POSITIONS;
+	let later: LookbackBlock;
+	let runHoistsImages = false;
+	let newerIsAssistant = false;
+	const add = (block: LookbackBlock): void => {
+		if (block === undefined || block !== later) positions++;
+		later = block;
+	};
+	let floor = entries.length;
+	for (let i = entries.length - 1; i >= start; i--) {
+		const message = getMessageFromEntry(entries[i]);
+		const sent = message === undefined ? [] : convertToLlm([message]);
+		for (let m = sent.length - 1; m >= 0; m--) {
+			const llm = sent[m];
+			if (llm.role === "toolResult") {
+				if (later !== "tool_result") runHoistsImages = false;
+				add("tool_result");
+				// Anthropic rejects images in error results, so the converter moves
+				// them after the result run behind one explanatory text block.
+				let images = 0;
+				if (llm.isError) {
+					for (const block of llm.content) if (block.type === "image") images++;
+				}
+				if (images > 0) {
+					positions += runHoistsImages ? images : images + 1;
+					runHoistsImages = true;
+				}
+				newerIsAssistant = false;
+			} else if (llm.role === "assistant") {
+				// The converter pads consecutive assistant turns with a user turn and
+				// drops assistant images, blank text, and turns left empty.
+				let pad = newerIsAssistant;
+				for (let b = llm.content.length - 1; b >= 0; b--) {
+					const block = llm.content[b];
+					if (block.type === "image" || (block.type === "text" && block.text.trim().length === 0)) continue;
+					if (pad) {
+						add(undefined);
+						pad = false;
+					}
+					add(block.type === "toolCall" ? "tool_use" : undefined);
+					newerIsAssistant = true;
+				}
+			} else {
+				// The converter drops blank user/developer turns.
+				const blocks =
+					typeof llm.content === "string" ? (llm.content.trim().length > 0 ? 1 : 0) : llm.content.length;
+				if (blocks === 0) continue;
+				for (let b = blocks; b > 0; b--) add(undefined);
+				newerIsAssistant = false;
+			}
+		}
+		if (positions >= lookback) return floor;
+		if (message?.role === "assistant") floor = i;
+	}
+	return start;
+}
+
 function createPrunedNotice(tokens: number): string {
 	return `[Output truncated - ${tokens} tokens]`;
 }
@@ -387,13 +504,20 @@ export function pruneSupersededToolResults(
 	} else {
 		// Mutating a candidate re-writes its suffix (tokens of every message
 		// strictly after it) in the warm cache, so prune only when that suffix is
-		// small. The suffix only grows walking back, so stop at the first index
-		// past the limit instead of measuring the whole branch.
+		// small and the next request's cache lookup stays in reach. The suffix
+		// only grows walking back, so stop at the first index past either limit
+		// instead of measuring the whole branch.
 		const suffixTokenLimit = config.suffixTokenLimit ?? DEFAULT_SUFFIX_TOKEN_LIMIT;
+		const lookbackFloor = cacheLookbackFloor(
+			entries,
+			boundaryIndex,
+			config.cacheLookbackPositions,
+			config.convertToLlm ?? defaultConvertToLlm,
+		);
 		toPrune = [];
 		let suffixTokens = 0;
 		let next = candidates.length - 1;
-		for (let i = entries.length - 1; next >= 0 && suffixTokens <= suffixTokenLimit; i--) {
+		for (let i = entries.length - 1; next >= 0 && suffixTokens <= suffixTokenLimit && i >= lookbackFloor; i--) {
 			while (next >= 0 && candidates[next].index === i) toPrune.push(candidates[next--]);
 			const entry = entries[i];
 			if (entry.type === "message") suffixTokens += tokenizer.countMessage(entry.message as AgentMessage);
@@ -451,6 +575,15 @@ export function pruneToolOutputs(
 			: undefined;
 
 	const cacheWarmSuffixTokens = config.cacheWarmSuffixTokens;
+	const lookbackFloor =
+		cacheWarmSuffixTokens === undefined
+			? boundaryIndex
+			: cacheLookbackFloor(
+					entries,
+					boundaryIndex,
+					config.cacheLookbackPositions,
+					config.convertToLlm ?? defaultConvertToLlm,
+				);
 	// Tokens of every message strictly after entry `i` (cache guard only).
 	let messageSuffix = 0;
 
@@ -470,10 +603,12 @@ export function pruneToolOutputs(
 
 		// Prompt-cache guard: a result whose all-message suffix exceeds the
 		// warm-cache window sits in the already-sent cached prefix — mutating it
-		// re-writes the whole suffix (cacheWrite premium). The suffix only grows
-		// walking back, so every older result is in the warm prefix too. Deeper,
-		// still-cached superseded/useless copies are left for compaction/shake.
-		if (cacheWarmSuffixTokens !== undefined && suffixAfter > cacheWarmSuffixTokens) break;
+		// re-writes the whole suffix (cacheWrite premium), or the whole
+		// conversation once the next request's cache lookup is out of reach.
+		// Both only worsen walking back, so every older result is in the warm
+		// prefix too. Deeper, still-cached superseded/useless copies are left for
+		// compaction/shake.
+		if (cacheWarmSuffixTokens !== undefined && (suffixAfter > cacheWarmSuffixTokens || i < lookbackFloor)) break;
 
 		if (message.prunedAt !== undefined) {
 			accumulatedTokens += tokens;

package/src/types.ts

@@ -328,6 +328,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * background.
 	 */
 	hasBackgroundCompletions?: () => boolean | Promise<boolean>;
+	/**
+	 * Peeks whether a passive aside (an extension or user message queued with
+	 * `deliverAs: "aside"`) is waiting for injection at the next boundary.
+	 *
+	 * Same rules as {@link hasBackgroundCompletions}: non-consuming, ends only
+	 * *interruptible* waits, never raises {@link ToolCallContext.steeringSignal}.
+	 * The host still injects the aside once at the boundary; ordinary running
+	 * tools finish first.
+	 */
+	hasQueuedAsides?: () => boolean | Promise<boolean>;
 
 	/**
 	 * Returns follow-up messages to process after the agent would otherwise stop.
@@ -341,7 +351,8 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * Returns non-interrupting "aside" messages to inject at a step boundary.
 	 *
 	 * Polled after each tool batch (before the next LLM call) AND at the yield
-	 * check. Unlike steering, these NEVER abort in-flight tools — they are passive
+	 * check. Unlike steering, these never abort foreground tools (only an
+	 * interruptible `wait` ends early, via the peek hooks) — they are passive
 	 * notifications (e.g. background-job completions, late LSP diagnostics) that
 	 * should reach the model between requests without waiting for the agent to
 	 * fully stop. Returned messages are appended to the context with normal