@oh-my-pi/pi-agent-core 16.2.13 → 16.3.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [16.3.0] - 2026-07-02
+
+### Added
+
+- Added support for Anthropic fallback content blocks in agent-loop assistant messages, ensuring they are preserved across session persistence and event fanout.
+
+### Fixed
+
+- Fixed an issue where legacy steering messages were prematurely consumed and dropped during in-flight tool execution polls.
+- Fixed an issue where skipped tool results in queued messages were incorrectly treated as completed, preventing necessary retries.
+- Improved branch summaries to preserve informative tool results from abandoned branches while filtering out redundant output.
+- Fixed interruptible tool waits to properly abort on host-provided IRC interrupts in addition to user steering.
+- Fixed schema validation errors for closed union tools by correctly injecting intent tracing into each variant.
+- Fixed token compaction reserve-budget logic to honor explicit reserveTokens values equal to the built-in default, and clamped the fallback reserve to at least one token for very small context windows.
+
 ## [16.2.4] - 2026-06-28
 
 ### Changed

package/dist/types/agent.d.ts

@@ -222,6 +222,10 @@ export declare class Agent {
      * UI emission, and tool dispatch. Reassign at any time to swap the implementation.
      */
     transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+    /**
+     * Hook that peeks whether interrupting IRC asides are queued for the next boundary.
+     */
+    hasIrcInterrupts?: AgentLoopConfig["hasIrcInterrupts"];
     constructor(opts?: AgentOptions);
     /**
      * Get the current session ID used for provider caching.

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

@@ -34,7 +34,15 @@ export interface CompactionSettings {
     thresholdPercent?: number;
     thresholdTokens?: number;
     midTurnEnabled?: boolean;
-    reserveTokens: number;
+    /**
+     * Tokens reserved below the context window for the next prompt + response.
+     *
+     * Leave unset to use {@link DEFAULT_RESERVE_TOKENS}; the unset state is the
+     * provenance signal that lets small-window recovery replace the default with
+     * a proportional reserve (see {@link resolveBudgetReserveTokens}). An
+     * explicit value — even one equal to the default — is always honored.
+     */
+    reserveTokens?: number;
     keepRecentTokens: number;
     autoContinue?: boolean;
     remoteEnabled?: boolean;
@@ -42,6 +50,8 @@ export interface CompactionSettings {
     remoteStreamingV2Enabled?: boolean;
     v2RetainedMessageBudget?: number;
 }
+/** Reserve applied when {@link CompactionSettings.reserveTokens} is unset. */
+export declare const DEFAULT_RESERVE_TOKENS = 16384;
 export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
 /**
  * Calculate total context tokens from usage.
@@ -54,9 +64,23 @@ export declare function calculatePromptTokens(usage: Usage): number;
  */
 export declare function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined;
 /**
- * Effective reserve: at least 15% of context window or the configured floor, whichever is larger.
+ * Effective reserve: at least 15% of context window or the configured floor
+ * (defaulting to {@link DEFAULT_RESERVE_TOKENS} when unset), whichever is larger.
  */
 export declare function effectiveReserveTokens(contextWindow: number, settings: CompactionSettings): number;
+/**
+ * Reserve used when deciding whether a prompt still fits inside the model window.
+ *
+ * The default absolute reserve predates small bundled windows and can leave no
+ * practical budget there; recover a DEFAULTED reserve that is impossible for
+ * the window with the 15% proportional reserve (clamped to >= 1 so the derived
+ * threshold stays strictly below the window even for tiny test windows).
+ * Explicit valid reserves — including one that happens to equal the default —
+ * still win, because they intentionally shrink the usable prompt budget;
+ * provenance is carried by `settings.reserveTokens` being unset, never by
+ * comparing values against the default.
+ */
+export declare function resolveBudgetReserveTokens(contextWindow: number, settings: CompactionSettings): number;
 /**
  * Check if compaction should trigger based on context usage.
  */

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

@@ -45,6 +45,10 @@ export declare function computeFileLists(fileOps: FileOperations): {
 };
 export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string;
 export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string;
+/**
+ * Truncate tool results to the same representation used in summarization prompts.
+ */
+export declare function truncateToolResultForSummary(text: string): string;
 /**
  * Serialize LLM messages to text for summarization.
  * This prevents the model from treating it as a conversation to continue.

package/dist/types/types.d.ts

@@ -158,6 +158,14 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * messages are still delivered at the next injection boundary.
      */
     hasSteeringMessages?: () => boolean | Promise<boolean>;
+    /**
+     * Peeks whether IRC messages should interrupt an interruptible waiting tool.
+     *
+     * Uses the same delivery rules as steering: the poll is non-consuming, only
+     * runs for interruptible tools, and is ignored when interruptMode is "wait".
+     * The host owns message injection at the next boundary.
+     */
+    hasIrcInterrupts?: () => boolean | Promise<boolean>;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "16.2.13",
+	"version": "16.3.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,12 +35,12 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "16.2.13",
-		"@oh-my-pi/pi-catalog": "16.2.13",
-		"@oh-my-pi/pi-natives": "16.2.13",
-		"@oh-my-pi/pi-utils": "16.2.13",
-		"@oh-my-pi/pi-wire": "16.2.13",
-		"@oh-my-pi/snapcompact": "16.2.13",
+		"@oh-my-pi/pi-ai": "16.3.0",
+		"@oh-my-pi/pi-catalog": "16.3.0",
+		"@oh-my-pi/pi-natives": "16.3.0",
+		"@oh-my-pi/pi-utils": "16.3.0",
+		"@oh-my-pi/pi-wire": "16.3.0",
+		"@oh-my-pi/snapcompact": "16.3.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -156,6 +156,8 @@ function snapshotAssistantContentBlock(block: AssistantContentBlock): AssistantC
 			return { ...block };
 		case "redactedThinking":
 			return { ...block };
+		case "fallback":
+			return { ...block, from: { ...block.from }, to: { ...block.to } };
 		case "toolCall":
 			return { ...block, arguments: structuredCloneJSON(block.arguments) };
 	}
@@ -535,6 +537,7 @@ export function normalizeMessagesForProvider(
 }
 
 const INTENT_FIELD_DESCRIPTION = "concise intent";
+const INTENT_SCHEMA_UNION_KEYS = ["anyOf", "oneOf"] as const;
 
 function injectIntentIntoSchema(
 	schema: unknown,
@@ -544,10 +547,30 @@ function injectIntentIntoSchema(
 	if (!schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
 	const schemaRecord = schema as Record<string, unknown>;
 	const propertiesValue = schemaRecord.properties;
-	const properties =
-		propertiesValue && typeof propertiesValue === "object" && !Array.isArray(propertiesValue)
-			? (propertiesValue as Record<string, unknown>)
-			: {};
+	const hasOwnProperties =
+		propertiesValue !== null && typeof propertiesValue === "object" && !Array.isArray(propertiesValue);
+
+	// Pure union root (anyOf/oneOf with no own properties): push `i` into each
+	// alternative branch so each closed shape keeps `additionalProperties: false`
+	// honest with intent tracing. Adding a sibling root `properties: { i }` /
+	// `required: [i]` would force every input to satisfy both root *and* a
+	// branch, leaving no satisfiable shape because each branch's
+	// `additionalProperties: false` rejects every other field — and OpenAI
+	// strict sanitization later promotes that sibling to a closed root
+	// `type: "object"` that rejects every non-`i` key outright. allOf is not
+	// alternation (its members are sub-constraints), so we don't recurse into it.
+	if (!hasOwnProperties) {
+		for (const key of INTENT_SCHEMA_UNION_KEYS) {
+			const variants = schemaRecord[key];
+			if (!Array.isArray(variants)) continue;
+			return {
+				...schemaRecord,
+				[key]: variants.map(variant => injectIntentIntoSchema(variant, mode, describeIntent)),
+			};
+		}
+	}
+
+	const properties = hasOwnProperties ? (propertiesValue as Record<string, unknown>) : {};
 	const requiredValue = schemaRecord.required;
 	const required = Array.isArray(requiredValue)
 		? requiredValue.filter((item): item is string => typeof item === "string")
@@ -1647,7 +1670,7 @@ async function executeToolCalls(
 	const tools = currentContext.tools;
 	const {
 		hasSteeringMessages,
-		getSteeringMessages,
+		hasIrcInterrupts,
 		interruptMode = "immediate",
 		getToolContext,
 		transformToolCallArguments,
@@ -1662,54 +1685,73 @@ async function executeToolCalls(
 	const batchId = `${assistantMessage.timestamp ?? Date.now()}_${toolCalls[0]?.id ?? "batch"}`;
 	const shouldInterruptImmediately = interruptMode !== "wait";
 	const steeringAbortController = new AbortController();
-	const toolSignal = signal
+	const ircAbortController = new AbortController();
+	// Interruptible tools observe steering + external + IRC aborts; every other
+	// tool only sees steering + external, so an IRC-only interrupt never kills a
+	// partially side-effecting foreground tool (e.g. `bash`) running alongside a
+	// pure wait (e.g. `job` poll).
+	const nonInterruptibleSignal: AbortSignal = signal
 		? AbortSignal.any([signal, steeringAbortController.signal])
 		: steeringAbortController.signal;
+	const interruptibleSignal: AbortSignal = signal
+		? AbortSignal.any([signal, steeringAbortController.signal, ircAbortController.signal])
+		: AbortSignal.any([steeringAbortController.signal, ircAbortController.signal]);
 	const interruptState = { triggered: false };
 
-	const records = toolCalls.map(toolCall => ({
-		toolCall,
+	const records = toolCalls.map(toolCall => {
 		// Tools emitted via OpenAI's custom-tool path (e.g. `apply_patch` on GPT-5)
 		// come back under their wire-level name, which may differ from the
 		// harness-internal `name`. Match on either, preferring `name` for
 		// determinism if both somehow collide.
-		tool:
+		const tool =
 			tools?.find(t => t.name === toolCall.name) ??
-			tools?.find(t => t.customWireName !== undefined && t.customWireName === toolCall.name),
-		args: toolCall.arguments as Record<string, unknown>,
-		started: false,
-		result: undefined as AgentToolResult<any> | undefined,
-		isError: false,
-		skipped: false,
-		toolResultMessage: undefined as ToolResultMessage | undefined,
-		resultEmitted: false,
-	}));
+			tools?.find(t => t.customWireName !== undefined && t.customWireName === toolCall.name);
+		return {
+			toolCall,
+			tool,
+			args: toolCall.arguments as Record<string, unknown>,
+			signal: tool?.interruptible ? interruptibleSignal : nonInterruptibleSignal,
+			started: false,
+			result: undefined as AgentToolResult<any> | undefined,
+			isError: false,
+			skipped: false,
+			toolResultMessage: undefined as ToolResultMessage | undefined,
+			resultEmitted: false,
+		};
+	});
 
 	const checkSteering = async (): Promise<void> => {
 		// `signal` (external/user abort) is checked separately from the internal
-		// steeringAbortController: once the run is externally aborted it is
-		// unwinding and the interrupt would be redundant.
-		if (!shouldInterruptImmediately || interruptState.triggered || signal?.aborted) {
+		// abort controllers: once the run is externally aborted it is unwinding
+		// and the interrupt would be redundant.
+		if (!shouldInterruptImmediately || signal?.aborted) {
 			return;
 		}
-		// Prefer the non-consuming peek (`hasSteeringMessages`) when available.
-		// Fall back to calling `getSteeringMessages` directly when only it is
-		// provided (e.g. in tests or minimal integrations without a separate
-		// peek function). In that case the message is consumed here rather than
-		// at the outer injection boundary, but the interrupt still fires.
-		let hasMessages: boolean;
+		// Mid-batch steering detection must be non-consuming. If a direct
+		// integration only provides getSteeringMessages(), the queue drains at the
+		// injection boundary below; polling it here would strand or drop messages.
+		let steeringQueued = false;
 		if (hasSteeringMessages) {
-			hasMessages = await hasSteeringMessages();
-		} else if (getSteeringMessages) {
-			const msgs = await getSteeringMessages();
-			hasMessages = (msgs?.length ?? 0) > 0;
-		} else {
+			steeringQueued = await hasSteeringMessages();
+		}
+		if (steeringQueued) {
+			// User steering upgrades an in-flight IRC interrupt: it aborts the
+			// shared signal so foreground tools stop as they do for a user Esc.
+			// Idempotent — a second steer poll after the abort is a no-op.
+			if (!steeringAbortController.signal.aborted) {
+				interruptState.triggered = true;
+				steeringAbortController.abort();
+			}
 			return;
 		}
-		if (hasMessages) {
-			if (interruptState.triggered || signal?.aborted) return;
+		// IRC only fires once: a peer interrupt already recorded on interruptState
+		// must not re-abort, and (unlike steering above) never re-consume a queue.
+		if (interruptState.triggered) return;
+		if (hasIrcInterrupts && (await hasIrcInterrupts())) {
+			// Peer IRC only aborts interruptible waits: a foreground bash / write
+			// mid-execution keeps running so we never leave partial side effects.
 			interruptState.triggered = true;
-			steeringAbortController.abort();
+			ircAbortController.abort();
 		}
 	};
 
@@ -1820,14 +1862,14 @@ async function executeToolCalls(
 		}
 
 		record.args = effectiveArgs;
-		if (toolSignal.aborted) {
+		if (record.signal.aborted) {
 			record.skipped = true;
 			recordSkippedTool(telemetry, {
 				toolCallId: toolCall.id,
 				toolName: toolCall.name,
 				status: "aborted",
 			});
-			emitToolResult(record, createToolSignalAbortedResult(toolSignal), true);
+			emitToolResult(record, createToolSignalAbortedResult(record.signal), true);
 			return;
 		}
 		record.started = true;
@@ -1858,8 +1900,8 @@ async function executeToolCalls(
 		await runInActiveSpan(toolSpan, async () => {
 			try {
 				if (!tool) throw new Error(`Tool ${toolCall.name} not found`);
-				if (toolSignal.aborted) {
-					result = createToolSignalAbortedResult(toolSignal);
+				if (record.signal.aborted) {
+					result = createToolSignalAbortedResult(record.signal);
 					isError = true;
 					return;
 				}
@@ -1872,14 +1914,14 @@ async function executeToolCalls(
 							args: effectiveArgs,
 							context: currentContext,
 						},
-						toolSignal,
+						record.signal,
 					);
 					if (beforeResult?.block) {
 						throw new ToolCallBlockedError(beforeResult.reason);
 					}
 				}
-				if (toolSignal.aborted) {
-					result = createToolSignalAbortedResult(toolSignal);
+				if (record.signal.aborted) {
+					result = createToolSignalAbortedResult(record.signal);
 					isError = true;
 					return;
 				}
@@ -1899,7 +1941,7 @@ async function executeToolCalls(
 				const rawResult = await tool.execute(
 					toolCall.id,
 					executionArgs,
-					toolSignal,
+					record.signal,
 					partialResult => {
 						stream.push({
 							type: "tool_execution_update",
@@ -1924,7 +1966,7 @@ async function executeToolCalls(
 				isError = true;
 			}
 
-			if (afterToolCall && (!toolSignal.aborted || completedToolExecution)) {
+			if (afterToolCall && (!record.signal.aborted || completedToolExecution)) {
 				try {
 					const after = await afterToolCall(
 						{
@@ -1935,7 +1977,7 @@ async function executeToolCalls(
 							isError,
 							context: currentContext,
 						},
-						toolSignal,
+						record.signal,
 					);
 					if (after) {
 						// Re-normalize the post-hook result: `afterToolCall` is untyped user/extension
@@ -1963,30 +2005,33 @@ async function executeToolCalls(
 		});
 
 		const interrupted = interruptState.triggered;
-		const abortedDuringExecution = toolSignal.aborted && isError;
-		if (interrupted && isError) {
-			// Steering/abort fired AND this tool failed — it was cut off before producing a
-			// usable result, so report it as skipped.
+		const perToolAborted = record.signal.aborted;
+		const abortedDuringExecution = perToolAborted && isError;
+		if (interrupted && perToolAborted && isError) {
+			// This tool's own signal fired AND it failed — it was cut off before producing
+			// a usable result, so report it as skipped.
 			record.skipped = true;
 			emitToolResult(record, createSkippedToolResult(), true);
 		} else {
-			// No interrupt, or the tool finished (successfully or with a genuine error) before
-			// the interrupt landed. Keep its real result: a completed tool already ran its side
-			// effects, so the model must see what actually happened rather than a false "skipped".
+			// No interrupt on this signal, or the tool finished (successfully or with a
+			// genuine error) before the interrupt landed. Keep its real result: a completed
+			// tool already ran its side effects, so the model must see what actually
+			// happened rather than a false "skipped". A peer-IRC interrupt on the batch
+			// leaves non-interruptible tools' signals untouched — their genuine errors
+			// survive here instead of being clobbered into "skipped".
 			emitToolResult(record, result, isError);
 		}
 
 		const firstTextBlock = result.content?.[0];
 		const errorMessageForSpan =
 			caughtError === undefined && isError && firstTextBlock?.type === "text" ? firstTextBlock.text : undefined;
-		const status =
-			(interrupted && isError) || abortedDuringExecution
-				? "aborted"
-				: caughtError instanceof ToolCallBlockedError
-					? "blocked"
-					: isError
-						? "error"
-						: "ok";
+		const status = abortedDuringExecution
+			? "aborted"
+			: caughtError instanceof ToolCallBlockedError
+				? "blocked"
+				: isError
+					? "error"
+					: "ok";
 		finishExecuteToolSpan(telemetry, toolSpan, {
 			result,
 			isError,
@@ -2030,15 +2075,15 @@ async function executeToolCalls(
 		}
 	}
 
-	// While an interruptible tool is in flight (e.g. a `job` poll blocking on
-	// background work), a queued steer would otherwise wait out the tool's own
-	// window. Poll the steering queue and let checkSteering() abort the shared
-	// tool signal so the wait returns early; the boundary dequeue below then
-	// injects it. Gated on immediate-interrupt mode + an interruptible tool;
-	// checkSteering is idempotent (no-op once triggered).
+	// While an interruptible tool is in flight (e.g. a `job`/`irc` wait
+	// blocking on external work), queued steering or interrupting IRC would
+	// otherwise wait out the tool's own window. Poll only non-consuming queues
+	// and abort the shared tool signal so the boundary dequeue below injects
+	// the message promptly. Gated on immediate-interrupt mode + an
+	// interruptible tool; checkSteering is idempotent (no-op once triggered).
 	const watchSteeringWhileRunning =
 		shouldInterruptImmediately &&
-		(hasSteeringMessages !== undefined || getSteeringMessages !== undefined) &&
+		(hasSteeringMessages !== undefined || hasIrcInterrupts !== undefined) &&
 		records.some(r => r.tool?.interruptible === true);
 	const steeringWatchTimer = watchSteeringWhileRunning
 		? setInterval(() => void checkSteering(), STEERING_INTERRUPT_POLL_MS)
@@ -2131,7 +2176,12 @@ function createToolSignalAbortedResult(signal: AbortSignal): AgentToolResult<unk
 
 function createSkippedToolResult(): AgentToolResult<any> {
 	return {
-		content: [{ type: "text", text: "Skipped due to queued user message." }],
+		content: [
+			{
+				type: "text",
+				text: "Skipped due to queued user message. Do not count this skipped result as completed work or verification. After the queued message is handled on the next step, retry the skipped tool if it is still needed.",
+			},
+		],
 		details: {},
 	};
 }

package/src/agent.ts

@@ -414,6 +414,10 @@ export class Agent {
 	 * UI emission, and tool dispatch. Reassign at any time to swap the implementation.
 	 */
 	transformAssistantMessage?: AgentLoopConfig["transformAssistantMessage"];
+	/**
+	 * Hook that peeks whether interrupting IRC asides are queued for the next boundary.
+	 */
+	hasIrcInterrupts?: AgentLoopConfig["hasIrcInterrupts"];
 
 	constructor(opts: AgentOptions = {}) {
 		this.#state = { ...this.#state, ...opts.initialState };
@@ -1182,6 +1186,7 @@ export class Agent {
 				return this.#dequeueSteeringMessages();
 			},
 			hasSteeringMessages: () => this.#steeringQueue.length > 0,
+			hasIrcInterrupts: this.hasIrcInterrupts,
 			getFollowUpMessages: async () => this.#dequeueFollowUpMessages(),
 			getAsideMessages: async () => (await this.#asideMessageProvider?.()) ?? [],
 			onBeforeYield: () => this.#onBeforeYield?.(),

package/src/compaction/branch-summarization.ts

@@ -29,6 +29,7 @@ import {
 	SUMMARIZATION_SYSTEM_PROMPT,
 	serializeConversation,
 	stripReadSelector,
+	truncateToolResultForSummary,
 	upsertFileOperations,
 } from "./utils";
 
@@ -168,8 +169,12 @@ export function collectEntriesForBranchSummary(
 function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
 	switch (entry.type) {
 		case "message":
-			// Skip tool results - context is in assistant's tool call
-			if (entry.message.role === "toolResult") return undefined;
+			// Useless non-error tool results are dropped by serializeConversation()
+			// downstream. Skip them here so a large useless payload can't eat the
+			// branch-summary token budget and starve older useful entries.
+			if (entry.message.role === "toolResult" && entry.message.useless === true && entry.message.isError !== true) {
+				return undefined;
+			}
 			return entry.message;
 
 		case "custom_message":
@@ -202,6 +207,19 @@ function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
 	}
 }
 
+function estimateBranchSummaryTokens(message: AgentMessage): number {
+	if (message.role !== "toolResult") return estimateTokens(message);
+	const text = message.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map(c => c.text)
+		.join("");
+	if (!text) return 0;
+	return estimateTokens({
+		...message,
+		content: [{ type: "text", text: truncateToolResultForSummary(text) }],
+	});
+}
+
 /**
  * Prepare entries for summarization with token budget.
  *
@@ -247,7 +265,7 @@ export function prepareBranchEntries(entries: SessionEntry[], tokenBudget: numbe
 		// Extract file ops from assistant messages (tool calls)
 		extractFileOpsFromMessage(message, fileOps);
 
-		const tokens = estimateTokens(message);
+		const tokens = estimateBranchSummaryTokens(message);
 
 		// Check budget before adding
 		if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {

package/src/compaction/compaction.ts

@@ -161,7 +161,15 @@ export interface CompactionSettings {
 	thresholdPercent?: number;
 	thresholdTokens?: number;
 	midTurnEnabled?: boolean;
-	reserveTokens: number;
+	/**
+	 * Tokens reserved below the context window for the next prompt + response.
+	 *
+	 * Leave unset to use {@link DEFAULT_RESERVE_TOKENS}; the unset state is the
+	 * provenance signal that lets small-window recovery replace the default with
+	 * a proportional reserve (see {@link resolveBudgetReserveTokens}). An
+	 * explicit value — even one equal to the default — is always honored.
+	 */
+	reserveTokens?: number;
 	keepRecentTokens: number;
 	autoContinue?: boolean;
 	remoteEnabled?: boolean;
@@ -170,13 +178,18 @@ export interface CompactionSettings {
 	v2RetainedMessageBudget?: number;
 }
 
+/** Reserve applied when {@link CompactionSettings.reserveTokens} is unset. */
+export const DEFAULT_RESERVE_TOKENS = 16384;
+
+// reserveTokens is deliberately absent: an unset reserve is what marks it as
+// defaulted, which resolveBudgetReserveTokens needs to distinguish "user never
+// chose a reserve" from "user explicitly configured the default value".
 export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
 	enabled: true,
 	strategy: "context-full",
 	thresholdPercent: -1,
 	thresholdTokens: -1,
 	midTurnEnabled: true,
-	reserveTokens: 16384,
 	keepRecentTokens: 20000,
 	autoContinue: true,
 	remoteEnabled: true,
@@ -233,10 +246,34 @@ export function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefine
 }
 
 /**
- * Effective reserve: at least 15% of context window or the configured floor, whichever is larger.
+ * Effective reserve: at least 15% of context window or the configured floor
+ * (defaulting to {@link DEFAULT_RESERVE_TOKENS} when unset), whichever is larger.
  */
 export function effectiveReserveTokens(contextWindow: number, settings: CompactionSettings): number {
-	return Math.max(Math.floor(contextWindow * 0.15), settings.reserveTokens);
+	return Math.max(Math.floor(contextWindow * 0.15), settings.reserveTokens ?? DEFAULT_RESERVE_TOKENS);
+}
+
+/**
+ * Reserve used when deciding whether a prompt still fits inside the model window.
+ *
+ * The default absolute reserve predates small bundled windows and can leave no
+ * practical budget there; recover a DEFAULTED reserve that is impossible for
+ * the window with the 15% proportional reserve (clamped to >= 1 so the derived
+ * threshold stays strictly below the window even for tiny test windows).
+ * Explicit valid reserves — including one that happens to equal the default —
+ * still win, because they intentionally shrink the usable prompt budget;
+ * provenance is carried by `settings.reserveTokens` being unset, never by
+ * comparing values against the default.
+ */
+export function resolveBudgetReserveTokens(contextWindow: number, settings: CompactionSettings): number {
+	const reserveTokens = effectiveReserveTokens(contextWindow, settings);
+	const proportionalReserveTokens = Math.max(1, Math.floor(contextWindow * 0.15));
+	const reserveWasDefaulted = settings.reserveTokens === undefined;
+	const defaultReserveIsEffectivelyImpossible =
+		reserveWasDefaulted && reserveTokens >= contextWindow - proportionalReserveTokens;
+	const reserveExceedsWindow = reserveTokens >= contextWindow;
+
+	return defaultReserveIsEffectivelyImpossible || reserveExceedsWindow ? proportionalReserveTokens : reserveTokens;
 }
 
 /**
@@ -275,10 +312,19 @@ export function resolveThresholdTokens(contextWindow: number, settings: Compacti
 		return Math.min(contextWindow - 1, Math.max(1, thresholdTokens));
 	}
 
-	// Percentage-based threshold
+	// Percentage-based threshold. The default absolute reserve can exceed bundled
+	// small-context windows, or nearly consume a 16k-class window; in those
+	// known-impossible default configurations, fall back to the proportional
+	// reserve so threshold/recovery-band checks stay usable. Explicit valid
+	// configured reserves still define the usable prompt budget. Cap at
+	// contextWindow - 1 (matching the fixed-token clamp above) so the threshold
+	// never reaches the whole window even when the reserve resolves to 0.
 	const thresholdPercent = settings.thresholdPercent;
 	if (typeof thresholdPercent !== "number" || !Number.isFinite(thresholdPercent) || thresholdPercent <= 0) {
-		return contextWindow - effectiveReserveTokens(contextWindow, settings);
+		return Math.max(
+			0,
+			Math.min(contextWindow - 1, contextWindow - resolveBudgetReserveTokens(contextWindow, settings)),
+		);
 	}
 	const clampedThresholdPercent = Math.min(99, Math.max(1, thresholdPercent));
 	return Math.floor(contextWindow * (clampedThresholdPercent / 100));
@@ -1223,6 +1269,8 @@ export async function compact(
 		settings,
 	} = preparation;
 
+	const reserveTokens = settings.reserveTokens ?? DEFAULT_RESERVE_TOKENS;
+
 	const summaryOptions: SummaryOptions = {
 		promptOverride: options?.promptOverride,
 		extraContext: options?.extraContext,
@@ -1383,7 +1431,7 @@ export async function compact(
 				? generateSummary(
 						messagesToSummarize,
 						model,
-						settings.reserveTokens,
+						reserveTokens,
 						apiKey,
 						signal,
 						customInstructions,
@@ -1391,7 +1439,7 @@ export async function compact(
 						summaryOptions,
 					)
 				: Promise.resolve("No prior history."),
-			generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, signal, summaryOptions),
+			generateTurnPrefixSummary(turnPrefixMessages, model, reserveTokens, apiKey, signal, summaryOptions),
 		]);
 		// Merge into single summary
 		summary = `${historyResult}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixResult}`;
@@ -1400,7 +1448,7 @@ export async function compact(
 		summary = await generateSummary(
 			messagesToSummarize,
 			model,
-			settings.reserveTokens,
+			reserveTokens,
 			apiKey,
 			signal,
 			customInstructions,
@@ -1417,7 +1465,7 @@ export async function compact(
 
 	const shortSummary = usedRemoteCompaction
 		? "Remote compaction"
-		: await generateShortSummary(recentMessages, summary, model, settings.reserveTokens, apiKey, signal, {
+		: await generateShortSummary(recentMessages, summary, model, reserveTokens, apiKey, signal, {
 				extraContext: options?.extraContext,
 				remoteEndpoint: summaryOptions.remoteEndpoint,
 				initiatorOverride: summaryOptions.initiatorOverride,

package/src/compaction/utils.ts

@@ -199,13 +199,12 @@ export function upsertFileOperations(
 const TOOL_RESULT_MAX_CHARS = 2000;
 
 /**
- * Truncate text to a maximum character length for summarization.
- * Keeps the beginning and appends a truncation marker.
+ * Truncate tool results to the same representation used in summarization prompts.
  */
-function truncateForSummary(text: string, maxChars: number): string {
-	if (text.length <= maxChars) return text;
-	const truncatedChars = text.length - maxChars;
-	return `${text.slice(0, maxChars)}\n\n[... ${truncatedChars} more characters truncated]`;
+export function truncateToolResultForSummary(text: string): string {
+	if (text.length <= TOOL_RESULT_MAX_CHARS) return text;
+	const truncatedChars = text.length - TOOL_RESULT_MAX_CHARS;
+	return `${text.slice(0, TOOL_RESULT_MAX_CHARS)}\n\n[... ${truncatedChars} more characters truncated]`;
 }
 
 /**
@@ -241,7 +240,7 @@ export function serializeConversation(messages: Message[], dialect?: Dialect): s
 				if (!text) continue;
 				processed.push({
 					...msg,
-					content: [{ type: "text", text: truncateForSummary(text, TOOL_RESULT_MAX_CHARS) }],
+					content: [{ type: "text", text: truncateToolResultForSummary(text) }],
 				});
 				continue;
 			}
@@ -293,7 +292,7 @@ export function serializeConversation(messages: Message[], dialect?: Dialect): s
 				.map(c => c.text)
 				.join("");
 			if (content) {
-				const text = truncateForSummary(content, TOOL_RESULT_MAX_CHARS);
+				const text = truncateToolResultForSummary(content);
 				parts.push(`[Tool Result]: ${text}`);
 			}
 		}

package/src/types.ts

@@ -199,6 +199,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	hasSteeringMessages?: () => boolean | Promise<boolean>;
 
+	/**
+	 * Peeks whether IRC messages should interrupt an interruptible waiting tool.
+	 *
+	 * Uses the same delivery rules as steering: the poll is non-consuming, only
+	 * runs for interruptible tools, and is ignored when interruptMode is "wait".
+	 * The host owns message injection at the next boundary.
+	 */
+	hasIrcInterrupts?: () => boolean | Promise<boolean>;
+
 	/**
 	 * Returns follow-up messages to process after the agent would otherwise stop.
 	 *