@oh-my-pi/pi-agent-core 15.11.2 → 15.11.4

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [15.11.4] - 2026-06-12
+### Added
+
+- Added `hasSteeringMessages` to `AgentLoopConfig` (wired by `Agent` to its steering queue): a peek used by the immediate-interrupt poll during tool execution, so the loop can detect queued steering without dequeuing and the queue keeps owning its messages until the injection boundary
+- The agent loop now re-samples after a non-terminal stop (`stopReason: "stop"` with `stopDetails: { type: "pause_turn" }`, emitted by the Codex providers for `end_turn: false` commentary-only responses): the assistant message is committed to history and the model is called again without ending the turn. Consecutive pause continuations without an intervening tool call are capped at 8 to bound a backend that never stops pausing.
+
+### Changed
+
+- Changed steering handling so queued steering messages are now dequeued only at injection boundaries, with immediate mid-batch interrupt polling using `hasSteeringMessages`. Consumers constructing `AgentLoopConfig` directly with only `getSteeringMessages` no longer get mid-batch interrupts — steering degrades to boundary-only delivery until they also supply `hasSteeringMessages`
+- Compaction, handoff, short-summary, and branch-summarization helpers now accept an `ApiKey` (static string or resolver) instead of a pre-resolved string, so a 401 mid-compaction force-refreshes and rotates the credential through the central auth-retry policy before any model-level fallback. The remote OpenAI compaction request is wrapped in `withAuth` and its HTTP failures now carry `.status`, so the retry classifier actually fires on remote-compaction 401s.
+- `transformProviderContext` now receives the dispatch model as a second argument (`(context, model) => Context`), so per-request transforms can gate on model capabilities (vision input, provider, API family). Existing single-argument implementations keep working unchanged.
+- Remote-compaction and summarization failures now throw pi-ai's typed `ProviderHttpError` instead of mutating plain `Error`s with a `.status` property; the generic `requestRemoteCompaction` error now carries `.status` (and response headers) too.
+
+### Fixed
+
+- Fixed a regression where steering messages could be injected into history during an aborted in-flight tool batch, leaving them hidden from queue consumers for post-abort continue
+
 ## [15.11.2] - 2026-06-11
 
 ### Added

package/dist/types/agent.d.ts

@@ -21,7 +21,7 @@ export interface AgentOptions {
      * Optional transform applied after provider context assembly and before
      * telemetry capture/provider send.
      */
-    transformProviderContext?: (context: Context) => Context;
+    transformProviderContext?: (context: Context, model: Model) => Context;
     /**
      * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
      */

package/dist/types/compaction/branch-summarization.d.ts

@@ -4,7 +4,7 @@
  * When navigating to a different point in the session tree, this generates
  * a summary of the branch being left so context isn't lost.
  */
-import type { Model } from "@oh-my-pi/pi-ai";
+import type { ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { type AgentTelemetry } from "../telemetry";
 import type { AgentMessage } from "../types";
 import type { ReadonlySessionManager, SessionEntry } from "./entries";
@@ -41,7 +41,7 @@ export interface GenerateBranchSummaryOptions {
     /** Model to use for summarization */
     model: Model;
     /** API key for the model */
-    apiKey: string;
+    apiKey: ApiKey;
     /** Abort signal for cancellation */
     signal: AbortSignal;
     /** Optional custom instructions for summarization */

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

@@ -4,7 +4,7 @@
  * Pure functions for compaction logic. The session manager handles I/O,
  * and after compaction the session is reloaded.
  */
-import { type FetchImpl, type MessageAttribution, type Model, type Tool, type Usage } from "@oh-my-pi/pi-ai";
+import { type ApiKey, type FetchImpl, type MessageAttribution, type Model, type Tool, type Usage } from "@oh-my-pi/pi-ai";
 import { type AgentTelemetry } from "../telemetry";
 import { ThinkingLevel } from "../thinking";
 import type { AgentMessage } from "../types";
@@ -128,7 +128,7 @@ export interface SummaryOptions {
     /** Optional fetch implementation threaded into remote compaction calls. */
     fetch?: FetchImpl;
 }
-export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: ApiKey, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
 export interface HandoffOptions {
     /** Live agent system prompt — passed verbatim so providers hit the cached prefix. */
     systemPrompt: string[];
@@ -152,7 +152,7 @@ export interface HandoffOptions {
     thinkingLevel?: ThinkingLevel;
 }
 export declare function renderHandoffPrompt(customInstructions?: string): string;
-export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: string, options: HandoffOptions, signal?: AbortSignal): Promise<string>;
+export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: ApiKey, options: HandoffOptions, signal?: AbortSignal): Promise<string>;
 export interface CompactionPreparation {
     /** UUID of first entry to keep */
     firstKeptEntryId: string;
@@ -182,4 +182,4 @@ export declare function prepareCompaction(pathEntries: SessionEntry[], settings:
  * @param preparation - Pre-calculated preparation from prepareCompaction()
  * @param customInstructions - Optional custom focus for the summary
  */
-export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string, customInstructions?: string, signal?: AbortSignal, options?: SummaryOptions): Promise<CompactionResult>;
+export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: ApiKey, customInstructions?: string, signal?: AbortSignal, options?: SummaryOptions): Promise<CompactionResult>;

package/dist/types/types.d.ts

@@ -84,7 +84,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * normalization, and append-only context handling, but before telemetry capture
      * and provider send.
      */
-    transformProviderContext?: (context: Context) => Context;
+    transformProviderContext?: (context: Context, model: Model) => Context;
     /**
      * Resolves an API key dynamically for each LLM call.
      *
@@ -95,11 +95,26 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /**
      * Returns steering messages to inject into the conversation mid-run.
      *
-     * Called after each tool execution to check for user interruptions unless interruptMode is "wait".
-     * If messages are returned, remaining tool calls are skipped and
-     * these messages are added to the context before the next LLM call.
+     * Called at injection boundaries only (loop start and after a tool batch
+     * fully settles), so dequeued messages are immediately injected. The
+     * mid-batch interrupt poll uses {@link hasSteeringMessages} instead and
+     * never consumes the queue.
      */
     getSteeringMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Peeks whether steering messages are queued, without consuming them.
+     *
+     * Called after each tool execution (unless interruptMode is "wait") to decide
+     * whether to skip the remaining tool calls in the batch. The queue keeps
+     * owning its messages until the loop reaches the next injection boundary and
+     * dequeues via {@link getSteeringMessages} — so callers can still cancel or
+     * restore queued messages while in-flight tools settle, and an external
+     * abort in that window leaves the queue intact for a post-abort continue.
+     *
+     * When omitted, steering never interrupts a running tool batch; queued
+     * messages are still delivered at the next injection boundary.
+     */
+    hasSteeringMessages?: () => 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": "15.11.2",
+	"version": "15.11.4",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,11 +35,11 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "15.11.2",
-		"@oh-my-pi/pi-catalog": "15.11.2",
-		"@oh-my-pi/pi-natives": "15.11.2",
-		"@oh-my-pi/pi-utils": "15.11.2",
-		"@oh-my-pi/snapcompact": "15.11.2",
+		"@oh-my-pi/pi-ai": "15.11.4",
+		"@oh-my-pi/pi-catalog": "15.11.4",
+		"@oh-my-pi/pi-natives": "15.11.4",
+		"@oh-my-pi/pi-utils": "15.11.4",
+		"@oh-my-pi/snapcompact": "15.11.4",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -58,6 +58,14 @@ import { yieldIfDue } from "./utils/yield";
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
 const ABORTED: unique symbol = Symbol("agent-loop-aborted");
 
+/**
+ * Cap on consecutive re-samples triggered by a non-terminal stop
+ * (`stopDetails.type === "pause_turn"`) without an intervening tool call. Each
+ * continuation is a full model request, so a backend that never stops pausing
+ * must not spin the loop forever. Resets whenever a turn carries tool calls.
+ */
+const MAX_PAUSED_TURN_CONTINUATIONS = 8;
+
 class HarmonyLeakInterruption extends Error {
 	constructor(
 		readonly detection: HarmonyDetection,
@@ -586,6 +594,7 @@ async function runLoopBody(
 	let pendingMessages: AgentMessage[] = signal?.aborted ? [] : (await config.getSteeringMessages?.()) || [];
 	let harmonyRetryAttempt = 0;
 	let harmonyTruncateResumeCount = 0;
+	let pausedTurnContinuations = 0;
 
 	// Outer loop: continues when queued follow-up messages arrive after agent would stop
 	while (true) {
@@ -667,7 +676,6 @@ async function runLoopBody(
 				stream.push({ type: "message_end", message: snapshotAssistantMessage(message) });
 			}
 			newMessages.push(message);
-			let steeringMessagesFromExecution: AgentMessage[] | undefined;
 
 			if (message.stopReason === "error" || message.stopReason === "aborted") {
 				// Create placeholder tool results for any tool calls in the aborted message
@@ -728,7 +736,6 @@ async function runLoopBody(
 				);
 
 				toolResults.push(...executionResult.toolResults);
-				steeringMessagesFromExecution = executionResult.steeringMessages;
 
 				for (const result of toolResults) {
 					currentContext.messages.push(result);
@@ -759,14 +766,32 @@ async function runLoopBody(
 				}
 			}
 
+			if (toolCalls.length > 0) {
+				pausedTurnContinuations = 0;
+			} else if (
+				!hasMoreToolCalls &&
+				message.stopReason === "stop" &&
+				message.stopDetails?.type === "pause_turn" &&
+				pausedTurnContinuations < MAX_PAUSED_TURN_CONTINUATIONS
+			) {
+				// Non-terminal stop: the provider ended the response but not the turn
+				// (e.g. Codex `end_turn: false` on a commentary-only progress update).
+				// Re-sample with the assistant message replayed so the model keeps
+				// working; the next round folds steering/asides in like any other
+				// mid-work turn.
+				pausedTurnContinuations++;
+				hasMoreToolCalls = true;
+			}
+
 			stream.push({ type: "turn_end", message, toolResults });
 
 			// On external abort (user interrupt), leave the steering queue intact: the
 			// session aborts then continues, delivering the queue into a fresh run.
 			// Draining it here would inject the messages right before a model call that
-			// instantly aborts — message lands in history, agent never responds.
-			const steering =
-				steeringMessagesFromExecution ?? (signal?.aborted ? [] : (await config.getSteeringMessages?.()) || []);
+			// instantly aborts — message lands in history, agent never responds. The
+			// mid-batch interrupt poll only peeks (hasSteeringMessages), so the queue
+			// still owns every message until this dequeue.
+			const steering = signal?.aborted ? [] : (await config.getSteeringMessages?.()) || [];
 			if (hasMoreToolCalls) {
 				// Mid-work: fold any non-interrupting asides into the next turn alongside steering.
 				const asides = resolveAsides(await config.getAsideMessages?.());
@@ -854,7 +879,7 @@ async function streamAssistantResponse(
 		};
 	}
 	if (config.transformProviderContext) {
-		llmContext = config.transformProviderContext(llmContext);
+		llmContext = config.transformProviderContext(llmContext, config.model);
 	}
 
 	const streamFunction = streamFn || streamSimple;
@@ -1233,9 +1258,10 @@ async function executeToolCalls(
 	config: AgentLoopConfig,
 	telemetry: AgentTelemetry | undefined,
 	invokeAgentSpan: Span | undefined,
-): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> {
+): Promise<{ toolResults: ToolResultMessage[] }> {
 	const tools = currentContext.tools;
 	const {
+		hasSteeringMessages,
 		getSteeringMessages,
 		interruptMode = "immediate",
 		getToolContext,
@@ -1255,8 +1281,6 @@ async function executeToolCalls(
 		? AbortSignal.any([signal, steeringAbortController.signal])
 		: steeringAbortController.signal;
 	const interruptState = { triggered: false };
-	let steeringMessages: AgentMessage[] | undefined;
-	let steeringCheckTail: Promise<void> = Promise.resolve();
 
 	const records = toolCalls.map(toolCall => ({
 		toolCall,
@@ -1279,23 +1303,29 @@ async function executeToolCalls(
 	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 draining the steering queue here would strand the
-		// messages in the dying run instead of leaving them for the post-abort
-		// continue (interruptAndFlushQueuedMessages → Agent.continue()).
-		if (!shouldInterruptImmediately || !getSteeringMessages || interruptState.triggered || signal?.aborted) {
+		// unwinding and the interrupt would be redundant.
+		if (!shouldInterruptImmediately || interruptState.triggered || signal?.aborted) {
 			return;
 		}
-		const check = steeringCheckTail.then(async () => {
+		// 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;
+		if (hasSteeringMessages) {
+			hasMessages = await hasSteeringMessages();
+		} else if (getSteeringMessages) {
+			const msgs = await getSteeringMessages();
+			hasMessages = (msgs?.length ?? 0) > 0;
+		} else {
+			return;
+		}
+		if (hasMessages) {
 			if (interruptState.triggered || signal?.aborted) return;
-			const steering = await getSteeringMessages();
-			if (steering.length > 0) {
-				steeringMessages = steering;
-				interruptState.triggered = true;
-				steeringAbortController.abort();
-			}
-		});
-		steeringCheckTail = check.catch(() => {});
-		await check;
+			interruptState.triggered = true;
+			steeringAbortController.abort();
+		}
 	};
 
 	const emitToolResult = (record: (typeof records)[number], result: AgentToolResult<any>, isError: boolean): void => {
@@ -1604,7 +1634,7 @@ async function executeToolCalls(
 		}
 	}
 
-	return { toolResults: emittedToolResults, steeringMessages };
+	return { toolResults: emittedToolResults };
 }
 
 /**

package/src/agent.ts

@@ -98,7 +98,7 @@ export interface AgentOptions {
 	 * Optional transform applied after provider context assembly and before
 	 * telemetry capture/provider send.
 	 */
-	transformProviderContext?: (context: Context) => Context;
+	transformProviderContext?: (context: Context, model: Model) => Context;
 
 	/**
 	 * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
@@ -285,7 +285,7 @@ export class Agent {
 	#abortController?: AbortController;
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
-	#transformProviderContext?: (context: Context) => Context;
+	#transformProviderContext?: (context: Context, model: Model) => Context;
 	#steeringQueue: AgentMessage[] = [];
 	#followUpQueue: AgentMessage[] = [];
 	#steeringMode: "all" | "one-at-a-time";
@@ -1009,6 +1009,7 @@ export class Agent {
 				}
 				return this.#dequeueSteeringMessages();
 			},
+			hasSteeringMessages: () => this.#steeringQueue.length > 0,
 			getFollowUpMessages: async () => this.#dequeueFollowUpMessages(),
 			getAsideMessages: async () => (await this.#asideMessageProvider?.()) ?? [],
 			onBeforeYield: () => this.#onBeforeYield?.(),

package/src/compaction/branch-summarization.ts

@@ -5,7 +5,7 @@
  * a summary of the branch being left so context isn't lost.
  */
 
-import type { Model } from "@oh-my-pi/pi-ai";
+import type { ApiKey, Model } from "@oh-my-pi/pi-ai";
 import { prompt } from "@oh-my-pi/pi-utils";
 import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
 import type { AgentMessage } from "../types";
@@ -71,7 +71,7 @@ export interface GenerateBranchSummaryOptions {
 	/** Model to use for summarization */
 	model: Model;
 	/** API key for the model */
-	apiKey: string;
+	apiKey: ApiKey;
 	/** Abort signal for cancellation */
 	signal: AbortSignal;
 	/** Optional custom instructions for summarization */

package/src/compaction/compaction.ts

@@ -6,19 +6,22 @@
  */
 
 import {
+	type ApiKey,
 	type AssistantMessage,
 	Effort,
 	type FetchImpl,
 	type Message,
 	type MessageAttribution,
 	type Model,
+	ProviderHttpError,
 	type Tool,
 	type Usage,
+	withAuth,
 } from "@oh-my-pi/pi-ai";
 import { clampThinkingLevelForModel } from "@oh-my-pi/pi-catalog/model-thinking";
 import { countTokens } from "@oh-my-pi/pi-natives";
 import { logger, prompt } from "@oh-my-pi/pi-utils";
-import { SNAPCOMPACT_FRAME_TOKEN_ESTIMATE } from "@oh-my-pi/snapcompact";
+import * as snapcompact from "@oh-my-pi/snapcompact";
 import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
 import { ThinkingLevel } from "../thinking";
 import type { AgentMessage } from "../types";
@@ -324,7 +327,7 @@ export function estimateTokens(message: AgentMessage): number {
 			fragments.push(message.summary);
 			if (message.role === "compactionSummary" && message.images) {
 				// Snapcompact frames render at ≥1568px; providers bill the downscaled cap.
-				extra += message.images.length * SNAPCOMPACT_FRAME_TOKEN_ESTIMATE;
+				extra += message.images.length * snapcompact.FRAME_TOKEN_ESTIMATE;
 			}
 			break;
 		}
@@ -579,11 +582,8 @@ function resolveCompactionEffort(model: Model, level: ThinkingLevel | undefined)
  * message-based check is still required upstream — see issue #986.
  */
 function createSummarizationError(prefix: string, response: AssistantMessage): Error {
-	const error: Error & { status?: number } = new Error(`${prefix}: ${response.errorMessage || "Unknown error"}`);
-	if (response.errorStatus !== undefined) {
-		error.status = response.errorStatus;
-	}
-	return error;
+	const text = `${prefix}: ${response.errorMessage || "Unknown error"}`;
+	return response.errorStatus === undefined ? new Error(text) : new ProviderHttpError(text, response.errorStatus);
 }
 
 /**
@@ -622,7 +622,7 @@ export async function generateSummary(
 	currentMessages: AgentMessage[],
 	model: Model,
 	reserveTokens: number,
-	apiKey: string,
+	apiKey: ApiKey,
 	signal?: AbortSignal,
 	customInstructions?: string,
 	previousSummary?: string,
@@ -736,7 +736,7 @@ export function renderHandoffPrompt(customInstructions?: string): string {
 export async function generateHandoff(
 	messages: AgentMessage[],
 	model: Model,
-	apiKey: string,
+	apiKey: ApiKey,
 	options: HandoffOptions,
 	signal?: AbortSignal,
 ): Promise<string> {
@@ -784,7 +784,7 @@ async function generateShortSummary(
 	historySummary: string | undefined,
 	model: Model,
 	reserveTokens: number,
-	apiKey: string,
+	apiKey: ApiKey,
 	signal?: AbortSignal,
 	options?: SummaryOptions,
 ): Promise<string> {
@@ -981,7 +981,7 @@ const TURN_PREFIX_SUMMARIZATION_PROMPT = prompt.render(compactionTurnPrefixPromp
 export async function compact(
 	preparation: CompactionPreparation,
 	model: Model,
-	apiKey: string,
+	apiKey: ApiKey,
 	customInstructions?: string,
 	signal?: AbortSignal,
 	options?: SummaryOptions,
@@ -1032,13 +1032,18 @@ export async function compact(
 		);
 		if (remoteHistory.length > 0) {
 			try {
-				const remote = await requestOpenAiRemoteCompaction(
-					model,
+				const remote = await withAuth(
 					apiKey,
-					remoteHistory,
-					summaryOptions.remoteInstructions ?? SUMMARIZATION_SYSTEM_PROMPT,
-					signal,
-					{ fetch: summaryOptions.fetch },
+					key =>
+						requestOpenAiRemoteCompaction(
+							model,
+							key,
+							remoteHistory,
+							summaryOptions.remoteInstructions ?? SUMMARIZATION_SYSTEM_PROMPT,
+							signal,
+							{ fetch: summaryOptions.fetch },
+						),
+					{ signal },
 				);
 				preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, remote);
 			} catch (err) {
@@ -1137,7 +1142,7 @@ async function generateTurnPrefixSummary(
 	messages: AgentMessage[],
 	model: Model,
 	reserveTokens: number,
-	apiKey: string,
+	apiKey: ApiKey,
 	signal?: AbortSignal,
 	options?: SummaryOptions,
 ): Promise<string> {

package/src/compaction/openai.ts

@@ -12,6 +12,7 @@
  *   with `{ summary, shortSummary? }`.
  */
 
+import { ProviderHttpError } from "@oh-my-pi/pi-ai/errors";
 import { parseTextSignature } from "@oh-my-pi/pi-ai/providers/openai-responses-shared";
 import { transformMessages } from "@oh-my-pi/pi-ai/providers/transform-messages";
 import type { AssistantMessage, FetchImpl, Message, Model } from "@oh-my-pi/pi-ai/types";
@@ -467,7 +468,13 @@ export async function requestOpenAiRemoteCompaction(
 			statusText: response.statusText,
 			errorText,
 		});
-		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
+		throw new ProviderHttpError(
+			`Remote compaction failed (${response.status} ${response.statusText})`,
+			response.status,
+			{
+				headers: response.headers,
+			},
+		);
 	}
 
 	const data = (await response.json()) as { output?: unknown[] } | undefined;
@@ -519,7 +526,13 @@ export async function requestRemoteCompaction(
 			statusText: response.statusText,
 			errorText,
 		});
-		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
+		throw new ProviderHttpError(
+			`Remote compaction failed (${response.status} ${response.statusText})`,
+			response.status,
+			{
+				headers: response.headers,
+			},
+		);
 	}
 
 	const data = (await response.json()) as RemoteCompactionResponse | undefined;

package/src/types.ts

@@ -113,7 +113,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * normalization, and append-only context handling, but before telemetry capture
 	 * and provider send.
 	 */
-	transformProviderContext?: (context: Context) => Context;
+	transformProviderContext?: (context: Context, model: Model) => Context;
 
 	/**
 	 * Resolves an API key dynamically for each LLM call.
@@ -126,12 +126,28 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	/**
 	 * Returns steering messages to inject into the conversation mid-run.
 	 *
-	 * Called after each tool execution to check for user interruptions unless interruptMode is "wait".
-	 * If messages are returned, remaining tool calls are skipped and
-	 * these messages are added to the context before the next LLM call.
+	 * Called at injection boundaries only (loop start and after a tool batch
+	 * fully settles), so dequeued messages are immediately injected. The
+	 * mid-batch interrupt poll uses {@link hasSteeringMessages} instead and
+	 * never consumes the queue.
 	 */
 	getSteeringMessages?: () => Promise<AgentMessage[]>;
 
+	/**
+	 * Peeks whether steering messages are queued, without consuming them.
+	 *
+	 * Called after each tool execution (unless interruptMode is "wait") to decide
+	 * whether to skip the remaining tool calls in the batch. The queue keeps
+	 * owning its messages until the loop reaches the next injection boundary and
+	 * dequeues via {@link getSteeringMessages} — so callers can still cancel or
+	 * restore queued messages while in-flight tools settle, and an external
+	 * abort in that window leaves the queue intact for a post-abort continue.
+	 *
+	 * When omitted, steering never interrupts a running tool batch; queued
+	 * messages are still delivered at the next injection boundary.
+	 */
+	hasSteeringMessages?: () => boolean | Promise<boolean>;
+
 	/**
 	 * Returns follow-up messages to process after the agent would otherwise stop.
 	 *