fix(coding-agent): compact before tool-loop continuation

packages/agent/CHANGELOG.md

@@ -8,6 +8,8 @@
 
 ### Fixed
 
+- Skipped next-turn preparation when every tool result terminates the current batch and no queued message requires another provider turn, retained queued input when next-turn preparation fails, and stopped before provider continuation when next-turn preparation aborts.
+
 ### Removed
 
 ## [2026.7.13] - 2026-07-13

packages/agent/src/agent-loop.ts

@@ -16,6 +16,7 @@ import type {
 	AgentContext,
 	AgentEvent,
 	AgentLoopConfig,
+	AgentLoopTurnUpdate,
 	AgentMessage,
 	AgentTool,
 	AgentToolCall,
@@ -182,6 +183,17 @@ async function runLoop(
 	let firstTurn = true;
 	// Check for steering messages at start (user may have typed while waiting)
 	let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || [];
+	let drainedTerminatingQueue: "steering" | "followUp" | undefined;
+	const refreshTerminatingQueueDrain = async (): Promise<void> => {
+		if (!drainedTerminatingQueue || !config.restorePendingMessages) return;
+		await config.restorePendingMessages(drainedTerminatingQueue, pendingMessages);
+		pendingMessages = (await config.getSteeringMessages?.()) || [];
+		drainedTerminatingQueue = pendingMessages.length > 0 ? "steering" : undefined;
+		if (pendingMessages.length === 0) {
+			pendingMessages = (await config.getFollowUpMessages?.()) || [];
+			drainedTerminatingQueue = pendingMessages.length > 0 ? "followUp" : undefined;
+		}
+	};
 
 	// Outer loop: continues when queued follow-up messages arrive after agent would stop
 	while (true) {
@@ -194,6 +206,14 @@ async function runLoop(
 			} else {
 				firstTurn = false;
 			}
+			if (drainedTerminatingQueue) {
+				await refreshTerminatingQueueDrain();
+				if (pendingMessages.length === 0) {
+					await emit({ type: "agent_end", messages: newMessages });
+					return;
+				}
+				drainedTerminatingQueue = undefined;
+			}
 
 			// Process pending messages (inject before next assistant response)
 			if (pendingMessages.length > 0) {
@@ -221,6 +241,7 @@ async function runLoop(
 
 			const toolResults: ToolResultMessage[] = [];
 			hasMoreToolCalls = false;
+			let toolBatchTerminated = false;
 			if (toolCalls.length > 0) {
 				// A "length" stop means the output was cut off by the token limit, so
 				// every tool call in the message may carry truncated arguments. Fail
@@ -230,6 +251,7 @@ async function runLoop(
 						? await failToolCallsFromTruncatedMessage(toolCalls, emit)
 						: await executeToolCalls(currentContext, message, config, signal, emit);
 				toolResults.push(...executedToolBatch.messages);
+				toolBatchTerminated = executedToolBatch.terminate;
 				hasMoreToolCalls = !executedToolBatch.terminate;
 
 				for (const result of toolResults) {
@@ -250,7 +272,36 @@ async function runLoop(
 				context: currentContext,
 				newMessages,
 			};
-			const nextTurnSnapshot = await config.prepareNextTurn?.(nextTurnContext);
+			if (toolBatchTerminated) {
+				if (await config.shouldStopAfterTurn?.(nextTurnContext)) {
+					await emit({ type: "agent_end", messages: newMessages });
+					return;
+				}
+
+				pendingMessages = (await config.getSteeringMessages?.()) || [];
+				if (pendingMessages.length > 0) {
+					drainedTerminatingQueue = "steering";
+				}
+				if (pendingMessages.length === 0) {
+					pendingMessages = (await config.getFollowUpMessages?.()) || [];
+					if (pendingMessages.length > 0) {
+						drainedTerminatingQueue = "followUp";
+					}
+				}
+				if (pendingMessages.length === 0) {
+					await emit({ type: "agent_end", messages: newMessages });
+					return;
+				}
+			}
+			let nextTurnSnapshot: AgentLoopTurnUpdate | undefined;
+			try {
+				nextTurnSnapshot = await config.prepareNextTurn?.(nextTurnContext);
+			} catch (error) {
+				if (drainedTerminatingQueue) {
+					await config.restorePendingMessages?.(drainedTerminatingQueue, pendingMessages);
+				}
+				throw error;
+			}
 			if (nextTurnSnapshot) {
 				currentContext = nextTurnSnapshot.context ?? currentContext;
 				config = {
@@ -264,20 +315,37 @@ async function runLoop(
 								: nextTurnSnapshot.thinkingLevel,
 				};
 			}
+			if (signal?.aborted) {
+				if (drainedTerminatingQueue) {
+					await config.restorePendingMessages?.(drainedTerminatingQueue, pendingMessages);
+				}
+				await emit({ type: "agent_end", messages: newMessages });
+				return;
+			}
+			if (drainedTerminatingQueue) {
+				await refreshTerminatingQueueDrain();
+				if (pendingMessages.length === 0) {
+					await emit({ type: "agent_end", messages: newMessages });
+					return;
+				}
+			}
 
 			if (
-				await config.shouldStopAfterTurn?.({
+				!toolBatchTerminated &&
+				(await config.shouldStopAfterTurn?.({
 					message,
 					toolResults,
 					context: currentContext,
 					newMessages,
-				})
+				}))
 			) {
 				await emit({ type: "agent_end", messages: newMessages });
 				return;
 			}
 
-			pendingMessages = (await config.getSteeringMessages?.()) || [];
+			if (!toolBatchTerminated) {
+				pendingMessages = (await config.getSteeringMessages?.()) || [];
+			}
 		}
 
 		// Agent would stop here. Check for follow-up messages.

packages/agent/src/agent.ts

@@ -123,6 +123,7 @@ export interface AgentOptions {
 
 class PendingMessageQueue {
 	private messages: AgentMessage[] = [];
+	private clearGeneration = 0;
 	public mode: QueueMode;
 
 	constructor(mode: QueueMode) {
@@ -137,6 +138,10 @@ class PendingMessageQueue {
 		return this.messages.length > 0;
 	}
 
+	getClearGeneration(): number {
+		return this.clearGeneration;
+	}
+
 	drain(): AgentMessage[] {
 		if (this.mode === "all") {
 			const drained = this.messages.slice();
@@ -152,8 +157,13 @@ class PendingMessageQueue {
 		return [first];
 	}
 
+	prepend(messages: AgentMessage[]): void {
+		this.messages = [...messages, ...this.messages];
+	}
+
 	clear(): void {
 		this.messages = [];
+		this.clearGeneration++;
 	}
 }
 
@@ -434,6 +444,8 @@ export class Agent {
 
 	private createLoopConfig(options: { skipInitialSteeringPoll?: boolean } = {}): AgentLoopConfig {
 		let skipInitialSteeringPoll = options.skipInitialSteeringPoll === true;
+		let steeringQueueGeneration = this.steeringQueue.getClearGeneration();
+		let followUpQueueGeneration = this.followUpQueue.getClearGeneration();
 		return {
 			model: this._state.model,
 			reasoning: this._state.thinkingLevel === "off" ? undefined : this._state.thinkingLevel,
@@ -464,9 +476,22 @@ export class Agent {
 					skipInitialSteeringPoll = false;
 					return [];
 				}
+				steeringQueueGeneration = this.steeringQueue.getClearGeneration();
 				return this.steeringQueue.drain();
 			},
-			getFollowUpMessages: async () => this.followUpQueue.drain(),
+			getFollowUpMessages: async () => {
+				followUpQueueGeneration = this.followUpQueue.getClearGeneration();
+				return this.followUpQueue.drain();
+			},
+			restorePendingMessages: (queue, messages) => {
+				if (queue === "steering") {
+					if (this.steeringQueue.getClearGeneration() !== steeringQueueGeneration) return;
+					this.steeringQueue.prepend(messages);
+					return;
+				}
+				if (this.followUpQueue.getClearGeneration() !== followUpQueueGeneration) return;
+				this.followUpQueue.prepend(messages);
+			},
 		};
 	}
 

packages/agent/src/harness/agent-harness.ts

@@ -418,6 +418,8 @@ export class AgentHarness<
 		setTurnState: (turnState: AgentHarnessTurnState<TSkill, TPromptTemplate, TTool>) => void,
 	): AgentLoopConfig {
 		const turnState = getTurnState();
+		let steeringQueueAtDrain = this.steerQueue;
+		let followUpQueueAtDrain = this.followUpQueue;
 		return {
 			model: turnState.model,
 			reasoning: turnState.thinkingLevel === "off" ? undefined : turnState.thinkingLevel,
@@ -459,8 +461,27 @@ export class AgentHarness<
 					thinkingLevel: nextTurnState.thinkingLevel,
 				};
 			},
-			getSteeringMessages: async () => this.drainQueuedMessages(this.steerQueue, this.steeringQueueMode),
-			getFollowUpMessages: async () => this.drainQueuedMessages(this.followUpQueue, this.followUpQueueMode),
+			getSteeringMessages: async () => {
+				steeringQueueAtDrain = this.steerQueue;
+				return this.drainQueuedMessages(steeringQueueAtDrain, this.steeringQueueMode);
+			},
+			getFollowUpMessages: async () => {
+				followUpQueueAtDrain = this.followUpQueue;
+				return this.drainQueuedMessages(followUpQueueAtDrain, this.followUpQueueMode);
+			},
+			restorePendingMessages: async (queue, messages) => {
+				const target = queue === "steering" ? this.steerQueue : this.followUpQueue;
+				const drainedQueue = queue === "steering" ? steeringQueueAtDrain : followUpQueueAtDrain;
+				if (target !== drainedQueue) return;
+				for (let index = messages.length - 1; index >= 0; index--) {
+					const message = messages[index];
+					if (message?.role !== "user") {
+						throw new AgentHarnessError("invalid_state", "Only user messages can be restored to input queues");
+					}
+					target.unshift(message);
+				}
+				await this.emitQueueUpdate();
+			},
 		};
 	}
 

packages/agent/src/types.ts

@@ -249,6 +249,12 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	getFollowUpMessages?: () => Promise<AgentMessage[]>;
 
+	/**
+	 * Restores messages previously returned by a queue callback when next-turn preparation cannot continue.
+	 * Restored messages must be placed before messages queued after the drain.
+	 */
+	restorePendingMessages?: (queue: "steering" | "followUp", messages: AgentMessage[]) => Promise<void> | void;
+
 	/**
 	 * Tool execution mode.
 	 * - "sequential": execute tool calls one by one