@gajae-code/agent-core 0.15.6 → 0.16.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.16.1] - 2026-09-03
+
+### Changed
+
+- `Agent.steer()` now performs enqueue-time admission and returns a `SteerAdmission` result. A steer is pushed onto the steering queue only while a run is live and its signal is not aborted; otherwise it returns `{ admitted: false, reason: "idle" | "aborting" }` and queues nothing. A steer submitted after a turn ended, or during an abort, can no longer sit orphaned in the queue and get consumed by whichever unrelated later prompt polls it first. Callers that need delivery when no run is live route the message themselves (the coding-agent session queues it as a sequential follow-up owned by the next turn).
+- `AgentOptions.interruptMode` (`"immediate" | "wait"`) is renamed to `toolInterruptPolicy` (`"abort_tools" | "finish_tools"`), with `setToolInterruptPolicy()` / `getToolInterruptPolicy()` replacing the old accessors and `AgentLoopConfig.toolInterruptPolicy` replacing `interruptMode`. The behaviour is unchanged: it only decides whether a steer aborts the tools still running in the current batch; a steer is always consumed at the next tool/turn boundary regardless. `Agent.steer()` accepts `{ forceOneAtATime: true }` so a message is delivered on its own even under `steeringMode: "all"` (the follow-up queue already had this override). `waitForSteeringArrival()` now resolves only on a steer admitted after the wait started (or abort), so a message already queued cannot interrupt a later observation window.
+- Every run exit now disowns steering it admitted but never consumed: `Agent` clears its steering queue when the run's `agent_end` is finalized (completed, aborted, cancelled, error, or `forceAbort`) and reports the messages on the event's new `disownedSteering` field, so the owner decides once what happens to them and no later, unrelated run can consume them. The admission fence (a fold winding the turn down) only stops the run from POLLING the queue; it no longer keeps the queue past the terminal, so ownership always transfers to the owner. Added `Agent.markFollowUpSequential()` for callers that restore a message ahead of the follow-up queue but still want prompt-by-prompt delivery under `followUpMode: "all"`.
+
+## [0.16.0] - 2026-09-02
+
 ## [0.15.6] - 2026-08-30
 
 ## [0.15.5] - 2026-08-29

package/README.md

@@ -250,14 +250,19 @@ Queue messages to inject during tool execution (steering) or after the agent wou
 
 ```typescript
 agent.setSteeringMode("one-at-a-time");
-agent.setInterruptMode("immediate");
+agent.setToolInterruptPolicy("abort_tools");
 
-// While agent is running tools
-agent.steer({
+// A steer is admitted ONLY into a live, non-aborted run.
+const admission = agent.steer({
 	role: "user",
 	content: "Stop! Do this instead.",
 	timestamp: Date.now(),
 });
+if (!admission.admitted) {
+	// admission.reason is "idle" (no run to steer) or "aborting" (the run is
+	// winding down). Nothing was queued: the caller owns routing the message,
+	// e.g. as a fresh prompt or a follow-up of the next turn.
+}
 
 // Queue a follow-up to run after the current turn completes
 agent.followUp({
@@ -267,8 +272,13 @@ agent.followUp({
 });
 ```
 
-Steering messages are checked after each tool call by default. Set `interruptMode` to `"wait"` to defer
-steering until the current turn completes.
+Steering messages are checked after each tool call by default. Set `toolInterruptPolicy` to
+`"finish_tools"` to let the running tool batch finish before the steering turn opens; the steer is
+still consumed at the next tool/turn boundary either way.
+
+A run that ends (completed, aborted, or error) never keeps steering it did not consume: the Agent
+clears its queue and reports the messages on `agent_end.disownedSteering`, so the owner decides once
+whether to re-route or drop them.
 
 ## Custom Message Types
 

package/dist/types/agent.d.ts

@@ -39,11 +39,15 @@ export interface AgentOptions {
      */
     followUpMode?: "all" | "one-at-a-time";
     /**
-     * When to interrupt tool execution for steering messages.
-     * - "immediate": check after each tool call (default)
-     * - "wait": defer steering until the current turn completes
+     * Whether a steering message aborts the tool calls still running in the
+     * current batch.
+     * - "abort_tools": abort the remaining tools and open the steering turn (default)
+     * - "finish_tools": let the batch finish, then open the steering turn
+     *
+     * This never changes WHEN a steer is consumed: the loop picks it up at the
+     * next tool/turn boundary either way.
      */
-    interruptMode?: "immediate" | "wait";
+    toolInterruptPolicy?: "abort_tools" | "finish_tools";
     /** Cooperative pause checkpoint passed through to AgentLoopConfig.shouldPause. */
     shouldPause?: AgentLoopConfig["shouldPause"];
     /**
@@ -186,6 +190,13 @@ export interface AgentPromptOptions {
     fallbackManaged?: boolean;
     /** Continue a cooperative maintenance checkpoint under its existing logical run and cancellation domain. */
     maintenanceContinuation?: boolean;
+    /**
+     * Skip the loop's INITIAL steering poll for this run. Used when the caller
+     * seeds the steering queue at run acceptance but the run's first model call
+     * must answer its own prompt first; the steering is then consumed at the
+     * first turn boundary instead of being merged into the opening call.
+     */
+    skipInitialSteeringPoll?: boolean;
     /** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
     onRunAccepted?: (handle: AttemptRunHandle, acceptance: {
         consumedQueuedMessages: readonly AgentMessage[];
@@ -201,6 +212,18 @@ export type AgentQueueSnapshot = {
     steering: AgentMessage[];
     followUp: AgentMessage[];
 };
+/**
+ * Result of `Agent.steer()`. A steer is admitted only into a live, non-aborted
+ * run; otherwise the message is NOT queued and the caller (the session) owns
+ * routing it — as a fresh prompt when idle, or after the unwind when aborting.
+ */
+export type SteerAdmission = {
+    admitted: true;
+    runId: number;
+} | {
+    admitted: false;
+    reason: "idle" | "aborting";
+};
 export declare class Agent {
     #private;
     get intentTracing(): boolean;
@@ -367,7 +390,9 @@ export declare class Agent {
      * immediate-interrupt path), so a cooperative stop alone cannot prevent one
      * more old-turn model call once a steering message has already been dequeued.
      * While the fence returns true the poll yields no messages AND does not
-     * dequeue, so the queue survives intact for the next turn.
+     * dequeue, so the winding-down run cannot consume it. The message is not
+     * retained past the run's terminal either: `agent_end.disownedSteering`
+     * hands it to the owner, which re-routes it onto the next turn.
      */
     setSteeringAdmissionFence(fn: (() => boolean) | undefined): void;
     setMaintainContext(fn: AgentLoopConfig["maintainContext"] | undefined): void;
@@ -392,8 +417,8 @@ export declare class Agent {
     getSteeringMode(): "all" | "one-at-a-time";
     setFollowUpMode(mode: "all" | "one-at-a-time"): void;
     getFollowUpMode(): "all" | "one-at-a-time";
-    setInterruptMode(mode: "immediate" | "wait"): void;
-    getInterruptMode(): "immediate" | "wait";
+    setToolInterruptPolicy(policy: "abort_tools" | "finish_tools"): void;
+    getToolInterruptPolicy(): "abort_tools" | "finish_tools";
     setTools(t: AgentTool<any>[]): void;
     replaceMessages(ms: AgentMessage[], options?: {
         historyRewrite?: {
@@ -411,11 +436,18 @@ export declare class Agent {
     /**
      * Queue a steering message to interrupt the agent mid-run.
      * Delivered after current tool execution, skips remaining tools.
+     *
+     * Enqueue-time admission: the message is pushed only when a run is live and
+     * its signal is not aborted, so a steer can never be orphaned in the queue
+     * waiting for whichever unrelated run polls next.
      */
-    steer(m: AgentMessage): void;
+    steer(m: AgentMessage, options?: {
+        forceOneAtATime?: boolean;
+    }): SteerAdmission;
     /**
-     * Resolves when a steering message is queued (or is already queued), or when
-     * `signal` aborts. The queue is not consumed. Long observation tools use this
+     * Resolves when a steering message is admitted AFTER this wait started, or
+     * when `signal` aborts. The queue is not consumed and a message already
+     * queued before the wait does not resolve it. Long observation tools use this
      * to end their wait early so a busy user message is handled at the next tool
      * boundary instead of after the full wait window.
      */
@@ -431,6 +463,14 @@ export declare class Agent {
     followUp(m: AgentMessage, options?: {
         forceOneAtATime?: boolean;
     }): void;
+    /**
+     * Mark a follow-up message for prompt-by-prompt delivery under `all` mode
+     * without queueing it. Used when a message is restored ahead of the queue
+     * (e.g. steering disowned by an ended run and re-routed as a follow-up).
+     */
+    markFollowUpSequential(m: AgentMessage): void;
+    /** Preserve one atomic delivery cohort when messages are re-routed into the follow-up queue. */
+    markFollowUpBatch(messages: readonly AgentMessage[]): void;
     clearSteeringQueue(): void;
     clearFollowUpQueue(): void;
     clearAllQueues(): void;
@@ -468,19 +508,9 @@ export declare class Agent {
     popLastFollowUp(): AgentMessage | undefined;
     removeFollowUpAt(index: number): AgentMessage | undefined;
     moveFollowUp(fromIndex: number, toIndex: number): boolean;
-    /**
-     * Remove ALL queued STEERING messages without touching the follow-up queue.
-     * Used by the terminal-abort path to purge steering queued for the aborted
-     * turn (the loop may exit on the abort signal without polling it); the
-     * follow-up queue is preserved because it may carry owned-completion
-     * resumes that must still deliver.
-     */
-    clearSteeringMessages(): void;
     /**
      * Remove queued steering/follow-up messages matching `predicate`, preserving
-     * order of the rest. `scope` restricts the removal to one queue — the
-     * terminal-abort steering purge must not wipe the follow-up queue, which
-     * the owned-completion resume policy preserves.
+     * order of the rest. `scope` restricts the removal to one queue.
      */
     removeQueuedMessages(predicate: (message: AgentMessage) => boolean, scope?: "both" | "steering" | "followUp"): {
         steering: number;

package/dist/types/types.d.ts

@@ -223,11 +223,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
     /** Scope allocated by the owning Agent for the first attempt in this loop. */
     initialScope?: AttemptScope;
     /**
-     * When to interrupt tool execution for steering messages.
-     * - "immediate" = check after each tool call (default)
-     * - "wait" = defer steering until the current turn completes
+     * Whether a steering message aborts the tool calls still running in the
+     * current batch.
+     * - "abort_tools": abort the remaining tools and open the steering turn (default)
+     * - "finish_tools": let the batch finish, then open the steering turn
+     *
+     * This never changes WHEN a steer is consumed: the loop picks it up at the
+     * next tool/turn boundary either way.
      */
-    interruptMode?: "immediate" | "wait";
+    toolInterruptPolicy?: "abort_tools" | "finish_tools";
     /**
      * Optional session identifier forwarded to LLM providers.
      * Used by providers that support session-based caching (e.g., OpenAI code provider).
@@ -302,7 +306,7 @@ 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".
+     * Called after each tool execution to check for user interruptions unless toolInterruptPolicy is "finish_tools".
      * If messages are returned, remaining tool calls are skipped and
      * these messages are added to the context before the next LLM call.
      */
@@ -719,6 +723,13 @@ export type AgentEvent = {
     stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
     /** Present iff `stopReason === "maintenance"`; the maintenance outcome. */
     maintenanceOutcome?: MidRunMaintenanceOutcome;
+    /**
+     * Steering that was admitted into this run but never consumed before it
+     * ended (the loop exited on abort, error, pause, or completion without a
+     * further poll). The Agent clears its queue on every run exit; the owner
+     * decides once here whether to re-route or drop these messages.
+     */
+    disownedSteering?: AgentMessage[];
     /** Present iff `AgentTelemetryConfig` was supplied on this run. */
     telemetry?: AgentRunSummary;
     coverage?: AgentRunCoverage;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.15.6",
+	"version": "0.16.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.15.6",
-		"@gajae-code/natives": "0.15.6",
-		"@gajae-code/utils": "0.15.6",
+		"@gajae-code/ai": "0.16.1",
+		"@gajae-code/natives": "0.16.1",
+		"@gajae-code/utils": "0.16.1",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -4316,6 +4316,11 @@ async function runLoopBody(
 				config.requeueSteeringMessages?.(pendingMessages);
 				break;
 			}
+			// An aborted run must not open another turn: the provider rejects it before
+			// the first token and the attempt only appends an aborted assistant message.
+			// The run's steering (which the poll above deliberately leaves queued once
+			// the signal is aborted) is disowned by the terminal instead.
+			if (loopSignal.aborted) break;
 			if (config.shouldPause?.()) {
 				publishAgentEnd(
 					stream,
@@ -5006,7 +5011,7 @@ async function executeToolCalls(
 	const tools = currentContext.tools;
 	const {
 		getSteeringMessages,
-		interruptMode = "immediate",
+		toolInterruptPolicy = "abort_tools",
 		getToolContext,
 		transformToolCallArguments,
 		intentTracing,
@@ -5020,7 +5025,7 @@ async function executeToolCalls(
 	const emittedToolResults: ToolResultMessage[] = [];
 	const toolCallInfos = toolCalls.map(call => ({ id: call.id, name: call.name }));
 	const batchId = `${assistantMessage.timestamp ?? Date.now()}_${toolCalls[0]?.id ?? "batch"}`;
-	const shouldInterruptImmediately = interruptMode !== "wait";
+	const shouldInterruptImmediately = toolInterruptPolicy !== "finish_tools";
 	const steeringAbortController = new AbortController();
 	const toolSignals = [
 		...(signal ? [signal] : []),

package/src/agent.ts

@@ -117,6 +117,27 @@ function sanitizeAgentFailure(error: unknown, runtimeClassifiedCode?: string): {
 	return { code, message: "Agent run failed." };
 }
 
+/** Only runtime-authenticated built-in constructors may contribute a name. */
+const TRUSTED_ERROR_CONSTRUCTORS = new Map<Function, string>([
+	[Error, "Error"],
+	[TypeError, "TypeError"],
+	[RangeError, "RangeError"],
+	[SyntaxError, "SyntaxError"],
+	[ReferenceError, "ReferenceError"],
+	[URIError, "URIError"],
+	[EvalError, "EvalError"],
+	[AggregateError, "AggregateError"],
+]);
+
+function safeErrorName(error: unknown): string | undefined {
+	try {
+		if (!(error instanceof Error)) return undefined;
+		return TRUSTED_ERROR_CONSTRUCTORS.get(error.constructor);
+	} catch {
+		return undefined;
+	}
+}
+
 /** Guarded HTTP-status extraction for untrusted provider errors: a throwing
  * getter must never escape the failure handler and suppress terminalization
  * (exact-head review P1). */
@@ -246,11 +267,15 @@ export interface AgentOptions {
 	followUpMode?: "all" | "one-at-a-time";
 
 	/**
-	 * When to interrupt tool execution for steering messages.
-	 * - "immediate": check after each tool call (default)
-	 * - "wait": defer steering until the current turn completes
+	 * Whether a steering message aborts the tool calls still running in the
+	 * current batch.
+	 * - "abort_tools": abort the remaining tools and open the steering turn (default)
+	 * - "finish_tools": let the batch finish, then open the steering turn
+	 *
+	 * This never changes WHEN a steer is consumed: the loop picks it up at the
+	 * next tool/turn boundary either way.
 	 */
-	interruptMode?: "immediate" | "wait";
+	toolInterruptPolicy?: "abort_tools" | "finish_tools";
 	/** Cooperative pause checkpoint passed through to AgentLoopConfig.shouldPause. */
 	shouldPause?: AgentLoopConfig["shouldPause"];
 
@@ -412,6 +437,13 @@ export interface AgentPromptOptions {
 	fallbackManaged?: boolean;
 	/** Continue a cooperative maintenance checkpoint under its existing logical run and cancellation domain. */
 	maintenanceContinuation?: boolean;
+	/**
+	 * Skip the loop's INITIAL steering poll for this run. Used when the caller
+	 * seeds the steering queue at run acceptance but the run's first model call
+	 * must answer its own prompt first; the steering is then consumed at the
+	 * first turn boundary instead of being merged into the opening call.
+	 */
+	skipInitialSteeringPoll?: boolean;
 	/** Called synchronously after this invocation claims the agent run, before asynchronous provider work. */
 	onRunAccepted?: (handle: AttemptRunHandle, acceptance: { consumedQueuedMessages: readonly AgentMessage[] }) => void;
 	/** Called once immediately before every managed upstream request. */
@@ -433,6 +465,13 @@ export type AgentQueueSnapshot = {
 	followUp: AgentMessage[];
 };
 
+/**
+ * Result of `Agent.steer()`. A steer is admitted only into a live, non-aborted
+ * run; otherwise the message is NOT queued and the caller (the session) owns
+ * routing it — as a fresh prompt when idle, or after the unwind when aborting.
+ */
+export type SteerAdmission = { admitted: true; runId: number } | { admitted: false; reason: "idle" | "aborting" };
+
 export class Agent {
 	#state: AgentState = {
 		systemPrompt: [],
@@ -461,9 +500,11 @@ export class Agent {
 	#steeringWaiters = new Set<() => void>();
 	#followUpQueue: AgentMessage[] = [];
 	#followUpForceOneAtATime = new WeakSet<AgentMessage>();
+	#followUpBatches = new WeakMap<AgentMessage, readonly AgentMessage[]>();
+	#steeringForceOneAtATime = new WeakSet<AgentMessage>();
 	#steeringMode: "all" | "one-at-a-time";
 	#followUpMode: "all" | "one-at-a-time";
-	#interruptMode: "immediate" | "wait";
+	#toolInterruptPolicy: "abort_tools" | "finish_tools";
 	#sessionId?: string;
 	#providerSessionId?: string;
 	#metadata?: Record<string, unknown>;
@@ -506,7 +547,7 @@ export class Agent {
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#shouldPause?: AgentLoopConfig["shouldPause"];
-	/** While set and returning true, steering is neither admitted nor dequeued. */
+	/** While set and returning true, the run does not DEQUEUE steering (admission is unaffected). */
 	#steeringAdmissionFence?: () => boolean;
 	#maintainContext?: AgentLoopConfig["maintainContext"];
 	#telemetry?: AgentLoopConfig["telemetry"];
@@ -572,7 +613,7 @@ export class Agent {
 		this.#transformContext = opts.transformContext;
 		this.#steeringMode = opts.steeringMode || "one-at-a-time";
 		this.#followUpMode = opts.followUpMode || "one-at-a-time";
-		this.#interruptMode = opts.interruptMode || "immediate";
+		this.#toolInterruptPolicy = opts.toolInterruptPolicy || "abort_tools";
 		this.streamFn = opts.streamFn || streamSimple;
 		this.#sessionId = opts.sessionId;
 		this.#providerSessionId = opts.providerSessionId;
@@ -912,7 +953,9 @@ export class Agent {
 	 * immediate-interrupt path), so a cooperative stop alone cannot prevent one
 	 * more old-turn model call once a steering message has already been dequeued.
 	 * While the fence returns true the poll yields no messages AND does not
-	 * dequeue, so the queue survives intact for the next turn.
+	 * dequeue, so the winding-down run cannot consume it. The message is not
+	 * retained past the run's terminal either: `agent_end.disownedSteering`
+	 * hands it to the owner, which re-routes it onto the next turn.
 	 */
 	setSteeringAdmissionFence(fn: (() => boolean) | undefined): void {
 		this.#steeringAdmissionFence = fn;
@@ -1109,12 +1152,12 @@ export class Agent {
 		return this.#followUpMode;
 	}
 
-	setInterruptMode(mode: "immediate" | "wait") {
-		this.#interruptMode = mode;
+	setToolInterruptPolicy(policy: "abort_tools" | "finish_tools") {
+		this.#toolInterruptPolicy = policy;
 	}
 
-	getInterruptMode(): "immediate" | "wait" {
-		return this.#interruptMode;
+	getToolInterruptPolicy(): "abort_tools" | "finish_tools" {
+		return this.#toolInterruptPolicy;
 	}
 
 	setTools(t: AgentTool<any>[]) {
@@ -1166,21 +1209,31 @@ export class Agent {
 	/**
 	 * Queue a steering message to interrupt the agent mid-run.
 	 * Delivered after current tool execution, skips remaining tools.
+	 *
+	 * Enqueue-time admission: the message is pushed only when a run is live and
+	 * its signal is not aborted, so a steer can never be orphaned in the queue
+	 * waiting for whichever unrelated run polls next.
 	 */
-	steer(m: AgentMessage) {
+	steer(m: AgentMessage, options?: { forceOneAtATime?: boolean }): SteerAdmission {
 		assertUserImagePlaceholdersHavePayload([m]);
+		const runId = this.#activeRunId;
+		if (runId === undefined || !this.#state.isStreaming) return { admitted: false, reason: "idle" };
+		if (this.#abortController?.signal.aborted) return { admitted: false, reason: "aborting" };
+		if (options?.forceOneAtATime) this.#steeringForceOneAtATime.add(m);
 		this.#steeringQueue.push(m);
 		for (const notify of [...this.#steeringWaiters]) notify();
+		return { admitted: true, runId };
 	}
 
 	/**
-	 * Resolves when a steering message is queued (or is already queued), or when
-	 * `signal` aborts. The queue is not consumed. Long observation tools use this
+	 * Resolves when a steering message is admitted AFTER this wait started, or
+	 * when `signal` aborts. The queue is not consumed and a message already
+	 * queued before the wait does not resolve it. Long observation tools use this
 	 * to end their wait early so a busy user message is handled at the next tool
 	 * boundary instead of after the full wait window.
 	 */
 	waitForSteeringArrival(signal: AbortSignal): Promise<void> {
-		if (this.#steeringQueue.length > 0 || signal.aborted) return Promise.resolve();
+		if (signal.aborted) return Promise.resolve();
 		const { promise, resolve } = Promise.withResolvers<void>();
 		let settled = false;
 		const settle = () => {
@@ -1192,7 +1245,6 @@ export class Agent {
 		};
 		this.#steeringWaiters.add(settle);
 		signal.addEventListener("abort", settle, { once: true });
-		if (this.#steeringQueue.length > 0 || signal.aborted) settle();
 		return promise;
 	}
 
@@ -1212,6 +1264,21 @@ export class Agent {
 		this.#followUpQueue.push(m);
 	}
 
+	/**
+	 * Mark a follow-up message for prompt-by-prompt delivery under `all` mode
+	 * without queueing it. Used when a message is restored ahead of the queue
+	 * (e.g. steering disowned by an ended run and re-routed as a follow-up).
+	 */
+	markFollowUpSequential(m: AgentMessage): void {
+		this.#followUpForceOneAtATime.add(m);
+	}
+
+	/** Preserve one atomic delivery cohort when messages are re-routed into the follow-up queue. */
+	markFollowUpBatch(messages: readonly AgentMessage[]): void {
+		const first = messages[0];
+		if (first && messages.length > 1) this.#followUpBatches.set(first, messages.slice());
+	}
+
 	clearSteeringQueue() {
 		this.#steeringQueue = [];
 	}
@@ -1284,23 +1351,37 @@ export class Agent {
 			}
 			return [];
 		}
-		const steering = this.#steeringQueue.slice();
-		this.#steeringQueue = [];
+		// "all" batches within ONE poll only; a per-message sequential mark still
+		// delivers that message on its own, mirroring the follow-up override.
+		const first = this.#steeringQueue[0];
+		if (!first) return [];
+		if (this.#steeringForceOneAtATime.has(first)) {
+			this.#steeringQueue = this.#steeringQueue.slice(1);
+			return [first];
+		}
+		const forcedIndex = this.#steeringQueue.findIndex(message => this.#steeringForceOneAtATime.has(message));
+		const takeCount = forcedIndex === -1 ? this.#steeringQueue.length : forcedIndex;
+		const steering = this.#steeringQueue.slice(0, takeCount);
+		this.#steeringQueue = this.#steeringQueue.slice(takeCount);
 		return steering;
 	}
 
 	#dequeueFollowUpMessages(): AgentMessage[] {
-		if (this.#followUpMode === "one-at-a-time") {
-			if (this.#followUpQueue.length > 0) {
-				const first = this.#followUpQueue[0];
-				this.#followUpQueue = this.#followUpQueue.slice(1);
-				return [first];
+		const first = this.#followUpQueue[0];
+		if (!first) return [];
+		const batch = this.#followUpBatches.get(first);
+		if (batch) {
+			this.#followUpBatches.delete(first);
+			if (batch.every((message, index) => this.#followUpQueue[index] === message)) {
+				this.#followUpQueue = this.#followUpQueue.slice(batch.length);
+				return [...batch];
 			}
-			return [];
+		}
+		if (this.#followUpMode === "one-at-a-time") {
+			this.#followUpQueue = this.#followUpQueue.slice(1);
+			return [first];
 		}
 
-		const first = this.#followUpQueue[0];
-		if (!first) return [];
 		if (this.#followUpForceOneAtATime.has(first)) {
 			this.#followUpQueue = this.#followUpQueue.slice(1);
 			return [first];
@@ -1357,22 +1438,9 @@ export class Agent {
 		return true;
 	}
 
-	/**
-	 * Remove ALL queued STEERING messages without touching the follow-up queue.
-	 * Used by the terminal-abort path to purge steering queued for the aborted
-	 * turn (the loop may exit on the abort signal without polling it); the
-	 * follow-up queue is preserved because it may carry owned-completion
-	 * resumes that must still deliver.
-	 */
-	clearSteeringMessages(): void {
-		this.#steeringQueue = [];
-	}
-
 	/**
 	 * Remove queued steering/follow-up messages matching `predicate`, preserving
-	 * order of the rest. `scope` restricts the removal to one queue — the
-	 * terminal-abort steering purge must not wipe the follow-up queue, which
-	 * the owned-completion resume policy preserves.
+	 * order of the rest. `scope` restricts the removal to one queue.
 	 */
 	removeQueuedMessages(
 		predicate: (message: AgentMessage) => boolean,
@@ -1834,7 +1902,7 @@ export class Agent {
 			repetitionPenalty: this.#repetitionPenalty,
 			serviceTier: this.#serviceTier,
 			hideThinkingSummary: this.#hideThinkingSummary,
-			interruptMode: this.#interruptMode,
+			toolInterruptPolicy: this.#toolInterruptPolicy,
 			sessionId: this.#sessionId,
 			providerSessionId: this.#providerSessionId,
 			metadata: this.#metadataResolver ? undefined : this.#metadata,
@@ -1939,11 +2007,18 @@ export class Agent {
 					return [];
 				}
 				// Fenced: yield nothing and dequeue nothing, so a steer submitted while a
-				// fold is being claimed is neither consumed by the run being wound down
-				// nor lost.
+				// fold is being claimed is not consumed by the run being wound down. It
+				// is not lost either: the terminal disowns it to the owner.
 				if (this.#steeringAdmissionFence?.() === true) {
 					return [];
 				}
+				// An aborted run cannot deliver steering: the loop hands drained
+				// messages back and ends. Dequeuing here would fire the in-run
+				// consumption hook for a message the run never delivers, so its SDK
+				// submission would settle as consumed instead of removed at disown.
+				if (abortController.signal.aborted) {
+					return [];
+				}
 				const queued = this.#dequeueSteeringMessages();
 				if (this.#activeRunId !== runId) {
 					this.#steeringQueue = [...queued, ...this.#steeringQueue];
@@ -2128,6 +2203,8 @@ export class Agent {
 			const runtimeFailureCode = abortController.signal.aborted
 				? "aborted"
 				: (managedLocalErrorDiagnostic(err)?.errorKind ?? providerCode);
+			const sanitized = sanitizeAgentFailure(err, runtimeFailureCode);
+			const errorName = safeErrorName(err);
 
 			const errorMsg: AgentMessage = {
 				role: "assistant",
@@ -2144,7 +2221,9 @@ export class Agent {
 					cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
 				},
 				stopReason: abortController.signal.aborted ? "aborted" : "error",
-				errorMessage: sanitizeAgentFailure(err).message,
+				errorMessage: sanitized.message,
+				errorCode: sanitized.code,
+				...(errorName ? { errorName } : {}),
 				errorStatus: safeErrorStatus(err),
 				// Local-diagnostic authority (`errorKind` + structured
 				// `bufferOverflow`) comes from ONE identity check: a foreign error
@@ -2302,6 +2381,15 @@ export class Agent {
 			scope: handle?.scope,
 		};
 		if (handle) terminalEvent.scope = handle.scope;
+		// The run is over: nothing will poll the steering queue again. Disown
+		// whatever it still holds — unconditionally, so no ownership exception can
+		// leave an ended run's steering behind for an unrelated run to consume —
+		// and hand it to the owner on the terminal event to re-route, hold, or
+		// drop exactly once.
+		if (this.#steeringQueue.length > 0) {
+			terminalEvent.disownedSteering = this.#steeringQueue;
+			this.#steeringQueue = [];
+		}
 		if (domain) {
 			setAgentTerminalOwnerContext(terminalEvent, {
 				resourceRunId,

package/src/types.ts

@@ -246,11 +246,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	initialScope?: AttemptScope;
 
 	/**
-	 * When to interrupt tool execution for steering messages.
-	 * - "immediate" = check after each tool call (default)
-	 * - "wait" = defer steering until the current turn completes
+	 * Whether a steering message aborts the tool calls still running in the
+	 * current batch.
+	 * - "abort_tools": abort the remaining tools and open the steering turn (default)
+	 * - "finish_tools": let the batch finish, then open the steering turn
+	 *
+	 * This never changes WHEN a steer is consumed: the loop picks it up at the
+	 * next tool/turn boundary either way.
 	 */
-	interruptMode?: "immediate" | "wait";
+	toolInterruptPolicy?: "abort_tools" | "finish_tools";
 
 	/**
 	 * Optional session identifier forwarded to LLM providers.
@@ -332,7 +336,7 @@ 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".
+	 * Called after each tool execution to check for user interruptions unless toolInterruptPolicy is "finish_tools".
 	 * If messages are returned, remaining tool calls are skipped and
 	 * these messages are added to the context before the next LLM call.
 	 */
@@ -803,6 +807,13 @@ export type AgentEvent =
 			stopReason?: "completed" | "paused" | "cancelled" | "maintenance";
 			/** Present iff `stopReason === "maintenance"`; the maintenance outcome. */
 			maintenanceOutcome?: MidRunMaintenanceOutcome;
+			/**
+			 * Steering that was admitted into this run but never consumed before it
+			 * ended (the loop exited on abort, error, pause, or completion without a
+			 * further poll). The Agent clears its queue on every run exit; the owner
+			 * decides once here whether to re-route or drop these messages.
+			 */
+			disownedSteering?: AgentMessage[];
 			/** Present iff `AgentTelemetryConfig` was supplied on this run. */
 			telemetry?: AgentRunSummary;
 			coverage?: AgentRunCoverage;