fix(task): lead each request user message with its tool_result blocks

src/core/task/Task.ts

@@ -140,6 +140,7 @@
 import { MessageManager } from "../message-manager"
 import { validateAndFixToolResultIds } from "./validateToolResultIds"
 import { mergeConsecutiveApiMessages } from "./mergeConsecutiveApiMessages"
+import { orderToolResultsFirst } from "./orderToolResultsFirst"
 import { prepareApiConversationMessage } from "./apiConversationHistory"
 import { shouldAddUserMessageToHistory } from "./messageCounting"
 import { type TaskExecutionContext } from "./providerHandoff"
@@ -5844,7 +5845,11 @@
 		const messagesSinceLastSummary = getMessagesSinceLastSummary(effectiveHistory)
 		// For API only: merge consecutive user messages (excludes summary messages per
 		// mergeConsecutiveApiMessages implementation) without mutating stored history.
-		const mergedForApi = mergeConsecutiveApiMessages(messagesSinceLastSummary, { roles: ["user"] })
+		// Then lead each user message with its tool_result blocks, which also repairs history saved
+		// with images between results (#1774) so a stuck task can retry successfully.
+		const mergedForApi = orderToolResultsFirst(
+			mergeConsecutiveApiMessages(messagesSinceLastSummary, { roles: ["user"] }),
+		)
 		const messagesWithoutImages = maybeRemoveImageBlocks(mergedForApi, this.api)
 		const cleanConversationHistory = this.buildCleanConversationHistory(
 			messagesWithoutImages as ApiMessage[],

src/core/task/__tests__/Task.spec.ts

@@ -2942,6 +2942,63 @@ describe("Cline", () => {
 				expect(Object.keys(cleanConversationHistory[0]!)).toEqual(["role", "content"])
 			})
 
+			it("sends tool_result blocks first when stored history has images between them (#1774)", async () => {
+				const cline = new Task({
+					provider: mockProvider,
+					apiConfiguration: mockApiConfig,
+					task: "test task",
+					startTask: false,
+				})
+				vi.spyOn(getTaskTestAccess(cline), "getSystemPrompt").mockResolvedValue("mock system prompt")
+				const mockStream = {
+					async *[Symbol.asyncIterator]() {
+						yield { type: "text", text: "response" }
+					},
+				} as AsyncGenerator<ApiStreamChunk>
+				const createMessageSpy = vi.spyOn(cline.api, "createMessage").mockReturnValue(mockStream)
+
+				// History as persisted by a turn that read an image alongside another tool call.
+				cline.apiConversationHistory = [
+					{ role: "user", content: [{ type: "text", text: "read the logo and list files" }], ts: 1 },
+					{
+						role: "assistant",
+						content: [
+							{ type: "tool_use", id: "read", name: "read_file", input: { path: "logo.jpg" } },
+							{ type: "tool_use", id: "cmd", name: "execute_command", input: { command: "ls" } },
+						],
+						ts: 2,
+					},
+					{
+						role: "user",
+						content: [
+							{ type: "tool_result", tool_use_id: "read", content: "File: logo.jpg" },
+							{ type: "image", source: { type: "base64", media_type: "image/jpeg", data: "abc" } },
+							{ type: "tool_result", tool_use_id: "cmd", content: "Exit code: 0" },
+							{ type: "text", text: "<environment_details>" },
+						],
+						ts: 3,
+					},
+				]
+
+				const iterator = cline.attemptApiRequest(0)
+				await iterator.next()
+
+				const [, sentHistory] = requireDefined(createMessageSpy.mock.calls[0])
+				const lastUserContent = requireDefined(sentHistory.at(-1)).content as Array<{ type: string }>
+				expect(lastUserContent.slice(0, 2)).toMatchObject([
+					{ type: "tool_result", tool_use_id: "read" },
+					{ type: "tool_result", tool_use_id: "cmd" },
+				])
+				expect(lastUserContent.slice(2).some((block) => block.type === "tool_result")).toBe(false)
+				// The stored history keeps its original shape.
+				expect(requireDefined(cline.apiConversationHistory.at(-1)).content).toMatchObject([
+					{ type: "tool_result" },
+					{ type: "image" },
+					{ type: "tool_result" },
+					{ type: "text" },
+				])
+			})
+
 			it("should shape image blocks for API compatibility before request construction", async () => {
 				const conversationHistory = [
 					{

src/core/task/__tests__/orderToolResultsFirst.spec.ts

@@ -0,0 +1,85 @@
+// npx vitest run core/task/__tests__/orderToolResultsFirst.spec.ts
+
+import type { Anthropic } from "@anthropic-ai/sdk"
+
+import type { ApiMessage } from "../../task-persistence"
+import { mergeConsecutiveApiMessages } from "../mergeConsecutiveApiMessages"
+import { orderToolResultsFirst } from "../orderToolResultsFirst"
+
+const toolResult = (id: string, content = `result ${id}`): Anthropic.Messages.ToolResultBlockParam => ({
+	type: "tool_result",
+	tool_use_id: id,
+	content,
+})
+const image = (data: string): Anthropic.Messages.ImageBlockParam => ({
+	type: "image",
+	source: { type: "base64", media_type: "image/jpeg", data },
+})
+const text = (value: string): Anthropic.Messages.TextBlockParam => ({ type: "text", text: value })
+
+describe("orderToolResultsFirst", () => {
+	it("repairs the persisted #1774 shape so every tool_result leads the message", () => {
+		// [tool_result, image, tool_result, text] as saved when read_file on an image ran
+		// alongside another tool call in the same turn.
+		const stuck: ApiMessage = {
+			role: "user",
+			ts: 16,
+			content: [toolResult("read"), image("jpeg"), toolResult("cmd"), text("<environment_details>")],
+		}
+
+		const [repaired] = orderToolResultsFirst([stuck])
+
+		expect(repaired.content).toEqual([
+			toolResult("read"),
+			toolResult("cmd"),
+			image("jpeg"),
+			text("<environment_details>"),
+		])
+		expect(repaired.ts).toBe(16)
+		// Stored history is untouched.
+		expect(stuck.content).toEqual([
+			toolResult("read"),
+			image("jpeg"),
+			toolResult("cmd"),
+			text("<environment_details>"),
+		])
+	})
+
+	it("keeps the order of results and of other blocks with several interleaved images", () => {
+		const [repaired] = orderToolResultsFirst([
+			{
+				role: "user",
+				content: [toolResult("a"), toolResult("b"), image("1"), toolResult("c"), image("2"), text("t")],
+			},
+		])
+
+		expect(repaired.content).toEqual([
+			toolResult("a"),
+			toolResult("b"),
+			toolResult("c"),
+			image("1"),
+			image("2"),
+			text("t"),
+		])
+	})
+
+	it("repairs interleaving introduced by merging consecutive user messages", () => {
+		const merged = mergeConsecutiveApiMessages([
+			{ role: "user", content: [toolResult("a"), text("note")] },
+			{ role: "user", content: [toolResult("b")] },
+		])
+
+		expect(orderToolResultsFirst(merged)[0].content).toEqual([toolResult("a"), toolResult("b"), text("note")])
+	})
+
+	it("returns already-ordered, string, and assistant messages unchanged", () => {
+		const ordered: ApiMessage = { role: "user", content: [toolResult("a"), image("1"), text("t")] }
+		const plain: ApiMessage = { role: "user", content: "hello" }
+		const noResults: ApiMessage = { role: "user", content: [text("a"), image("1")] }
+		const assistant: ApiMessage = { role: "assistant", content: [text("a")] }
+
+		const out = orderToolResultsFirst([ordered, plain, noResults, assistant])
+
+		out.forEach((message, index) => expect(message).toBe([ordered, plain, noResults, assistant][index]))
+	})
+})

src/core/task/orderToolResultsFirst.ts

@@ -0,0 +1,33 @@
+import type { ApiMessage } from "../task-persistence"
+
+/**
+ * Moves `tool_result` blocks to the front of each user message, keeping the relative order of
+ * the results and of the remaining blocks.
+ *
+ * Anthropic requires the results for the previous turn's `tool_use` blocks to lead the next user
+ * message. History saved with image blocks between results (#1307, #1774), or produced by merging
+ * consecutive user messages, is otherwise rejected with a 400 on every retry.
+ *
+ * Used for *API request shaping only* (do not use for storage). Messages already in order are
+ * returned unchanged.
+ */
+export function orderToolResultsFirst(messages: ApiMessage[]): ApiMessage[] {
+	return messages.map((message) => {
+		if (message.role !== "user" || !Array.isArray(message.content)) {
+			return message
+		}
+		const firstOther = message.content.findIndex((block) => block.type !== "tool_result")
+		const hasLaterResult =
+			firstOther !== -1 && message.content.slice(firstOther).some((block) => block.type === "tool_result")
+		if (!hasLaterResult) {
+			return message
+		}
+		return {
+			...message,
+			content: [
+				...message.content.filter((block) => block.type === "tool_result"),
+				...message.content.filter((block) => block.type !== "tool_result"),
+			],
+		}
+	})
+}