@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/__tests__/subagent-tool-gate-mode.test.ts

@@ -66,6 +66,40 @@ mock.module("../daemon/conversation-skill-tools.js", () => ({
   })),
 }));
 
+// Records every wire tool surface the resolver persists (conversation id +
+// tool names + the hash it already knew), and lets a test make the write fail.
+type RecordedSurface = {
+  tools: ToolDefinition[];
+  delegateIndependentTasks: boolean | null;
+};
+let recordedSurfaces: Array<{
+  conversationId: string;
+  toolNames: string[];
+  delegateIndependentTasks: boolean | null;
+  knownHash: string | undefined;
+}> = [];
+let recordSurfaceThrows: Error | null = null;
+mock.module("../persistence/conversation-tool-surface.js", () => ({
+  recordConversationToolSurface: (
+    conversationId: string,
+    surface: RecordedSurface,
+    knownHash?: string,
+  ) => {
+    recordedSurfaces.push({
+      conversationId,
+      toolNames: surface.tools.map((t) => t.name),
+      delegateIndependentTasks: surface.delegateIndependentTasks,
+      knownHash,
+    });
+    if (recordSurfaceThrows) {
+      throw recordSurfaceThrows;
+    }
+    return `hash:${surface.tools.map((t) => t.name).join(",")}`;
+  },
+  hashConversationToolSurface: (surface: RecordedSurface) =>
+    `hash:${surface.tools.map((t) => t.name).join(",")}`,
+}));
+
 // ---------------------------------------------------------------------------
 // Imports after mocks are in place
 // ---------------------------------------------------------------------------
@@ -75,6 +109,7 @@ import { createSurfaceMutex } from "../daemon/conversation-surfaces.js";
 import {
   createResolveToolsCallback,
   createToolExecutor,
+  createWireToolSurfaceRecorder,
   isRefusedInReadOnlyPass,
   type SubagentToolStats,
 } from "../daemon/conversation-tool-setup.js";
@@ -1117,3 +1152,194 @@ describe("createResolveToolsCallback — read-only hides dynamic MCP tools", ()
     expect(resolve(EMPTY_HISTORY).map((t) => t.name)).toContain("srv_send");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Resolver: wire tool surface record + replay (fork cache parity)
+// ---------------------------------------------------------------------------
+
+describe("createResolveToolsCallback: wire tool surface record and replay", () => {
+  beforeEach(() => {
+    recordedSurfaces = [];
+    recordSurfaceThrows = null;
+    projectedSkillToolNames = [];
+  });
+
+  test("the resolver itself never records: out-of-band callers read it too", () => {
+    const toolDefs = [makeToolDef("remember"), makeToolDef("tool_b")];
+    const ctx = makeProjectionCtx({ conversationId: "conv-live" });
+    const resolve = createResolveToolsCallback(toolDefs, ctx)!;
+
+    // The `/compact` token count resolves outside any turn, where presence
+    // reads clientless; recording here would overwrite the sent surface.
+    resolve(EMPTY_HISTORY);
+
+    expect(recordedSurfaces).toEqual([]);
+    expect(ctx.recordedToolSurfaceHash).toBeUndefined();
+  });
+
+  test("the send-boundary recorder records the sent array, keyed by conversation, and remembers its hash", () => {
+    const ctx = makeProjectionCtx({
+      conversationId: "conv-live",
+      renderedDelegateIndependentTasks: true,
+    });
+    const record = createWireToolSurfaceRecorder(ctx);
+    const sent = [makeToolDef("remember"), makeToolDef("web_search")];
+
+    record(sent);
+    record(sent);
+
+    // Every provider call records; the persistence layer dedupes on the hash
+    // handed back from the previous call.
+    expect(recordedSurfaces).toEqual([
+      {
+        conversationId: "conv-live",
+        toolNames: ["remember", "web_search"],
+        delegateIndependentTasks: true,
+        knownHash: undefined,
+      },
+      {
+        conversationId: "conv-live",
+        toolNames: ["remember", "web_search"],
+        delegateIndependentTasks: true,
+        knownHash: "hash:remember,web_search",
+      },
+    ]);
+    expect(ctx.recordedToolSurfaceHash).toBe("hash:remember,web_search");
+  });
+
+  test("the recorder records the state the prompt build captured, never a re-derivation", () => {
+    const sent = [makeToolDef("remember")];
+
+    // The loop sends the prompt built before the run, so the captured state
+    // is recorded as is even where the live scope would now derive the
+    // opposite: a spawn path excluded after the build (here, an allowlist
+    // with none) still records the section on...
+    createWireToolSurfaceRecorder(
+      makeProjectionCtx({
+        conversationId: "conv-captured-on",
+        subagentAllowedTools: new Set(["remember"]),
+        renderedDelegateIndependentTasks: true,
+      }),
+    )(sent);
+    // ...and a path restored after the build still records it off.
+    createWireToolSurfaceRecorder(
+      makeProjectionCtx({
+        conversationId: "conv-captured-off",
+        renderedDelegateIndependentTasks: false,
+      }),
+    )(sent);
+    // A verbatim system-prompt override captures unknown.
+    createWireToolSurfaceRecorder(
+      makeProjectionCtx({
+        conversationId: "conv-override",
+        renderedDelegateIndependentTasks: null,
+      }),
+    )(sent);
+    // No prompt built yet: unknown as well.
+    createWireToolSurfaceRecorder(
+      makeProjectionCtx({ conversationId: "conv-unbuilt" }),
+    )(sent);
+
+    expect(
+      recordedSurfaces.map((r) => [
+        r.conversationId,
+        r.delegateIndependentTasks,
+      ]),
+    ).toEqual([
+      ["conv-captured-on", true],
+      ["conv-captured-off", false],
+      ["conv-override", null],
+      ["conv-unbuilt", null],
+    ]);
+  });
+
+  test("a failed record is swallowed and still counts as recorded", () => {
+    recordSurfaceThrows = new Error("no such table");
+    const record = createWireToolSurfaceRecorder(
+      makeProjectionCtx({ conversationId: "conv-live" }),
+    );
+
+    expect(() => record([makeToolDef("remember")])).not.toThrow();
+    record([makeToolDef("remember")]);
+
+    // The second call carries the hash from the failed first one, so a
+    // persistent failure is retried once per distinct surface, not per call.
+    expect(recordedSurfaces.map((r) => r.knownHash)).toEqual([
+      undefined,
+      "hash:remember",
+    ]);
+  });
+
+  test("the recorder skips arrays that are not the conversation's own surface", () => {
+    const tools = [makeToolDef("remember")];
+
+    // A replaying wake sends its source's array.
+    createWireToolSurfaceRecorder(
+      makeProjectionCtx({ conversationId: "conv-fork", wireToolReplay: tools }),
+    )(tools);
+    // A tools-disabled call sends nothing; a fork replaying [] could never
+    // call remember.
+    createWireToolSurfaceRecorder(
+      makeProjectionCtx({ conversationId: "conv-live" }),
+    )([]);
+    // Disk-pressure cleanup narrows the wire to cleanup tools.
+    createWireToolSurfaceRecorder(
+      makeProjectionCtx({
+        conversationId: "conv-live",
+        diskPressureCleanupModeActive: true,
+      }),
+    )(tools);
+
+    expect(recordedSurfaces).toEqual([]);
+  });
+
+  test("replays wireToolReplay verbatim on the wire while execution still derives from the fork's own context", () => {
+    projectedSkillToolNames = ["scaffold_managed_skill"];
+    const replay: ToolDefinition[] = [
+      makeToolDef("bash"),
+      makeToolDef("remember"),
+      makeToolDef("bell_jingle"),
+      {
+        type: "web_search_20250305",
+        name: "web_search",
+        max_uses: 5,
+      } as unknown as ToolDefinition,
+    ];
+    // The fork's own registry lacks bell_jingle (a user-plugin tool the
+    // worker never loads) and web_search (a server tool the loop appends).
+    const toolDefs = [makeToolDef("remember"), makeToolDef("bash")];
+    const ctx = makeProjectionCtx({
+      conversationId: "conv-fork",
+      subagentAllowedTools: new Set(["remember"]),
+      subagentToolGateMode: "execution",
+      wireToolReplay: replay,
+    });
+    const resolve = createResolveToolsCallback(toolDefs, ctx)!;
+
+    const tools = resolve(EMPTY_HISTORY);
+
+    // Byte-identical to the source's recorded array, in the source's order,
+    // including definitions this process could never resolve.
+    expect(JSON.stringify(tools)).toBe(JSON.stringify(replay));
+    // Execution-side inventory is still the fork's own derivation (plus the
+    // preactivated skill tools), never widened by the replayed definitions.
+    expect(ctx.allowedToolNames).toEqual(
+      new Set(["remember", "bash", "scaffold_managed_skill"]),
+    );
+  });
+
+  test("replay returns a fresh array each call so the loop cannot mutate the recorded one", () => {
+    const replay = [makeToolDef("remember")];
+    const ctx = makeProjectionCtx({
+      conversationId: "conv-fork",
+      wireToolReplay: replay,
+    });
+    const resolve = createResolveToolsCallback([makeToolDef("remember")], ctx)!;
+
+    const first = resolve(EMPTY_HISTORY);
+    first.push(makeToolDef("injected"));
+
+    expect(resolve(EMPTY_HISTORY).map((t) => t.name)).toEqual(["remember"]);
+    expect(replay.map((t) => t.name)).toEqual(["remember"]);
+  });
+});

package/src/__tests__/terminal-tools.test.ts

@@ -44,6 +44,7 @@ import {
   formatShellOutput,
   MAX_OUTPUT_LENGTH,
   OUTPUT_TRUNCATED_TAG,
+  SHELL_DID_NOT_START_MESSAGE,
 } from "../tools/shared/shell-output.js";
 import {
   ALWAYS_INJECTED_ENV_VARS,
@@ -334,6 +335,13 @@ describe("formatShellOutput", () => {
     expect(result.isError).toBe(false);
   });
 
+  test("a close with exit 0 and empty pipes is an error when the process never started", () => {
+    const result = formatShellOutput("", "", 0, false, 120, { started: false });
+    expect(result.content).toBe(SHELL_DID_NOT_START_MESSAGE);
+    expect(result.isError).toBe(true);
+    expect(result.content).not.toBe("<command_completed />");
+  });
+
   test("failed command with no output shows exit code tag and descriptive message", () => {
     const result = formatShellOutput("", "", 1, false, 120);
     expect(result.content).toContain('<command_exit code="1" />');

package/src/__tests__/tool-result-follow-up.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildToolResultFollowUp } from "../agent/tool-result-follow-up.js";
+import type { ContentBlock, Message, TextContent } from "../providers/types.js";
+
+const opener: Message = {
+  role: "user",
+  content: [{ type: "text", text: "Check both" }],
+};
+
+/** Assistant turn calling two client tools and a native web search together. */
+const mixedTurn: Message = {
+  role: "assistant",
+  content: [
+    { type: "tool_use", id: "tu_a", name: "web_fetch", input: {} },
+    { type: "tool_use", id: "tu_b", name: "file_read", input: {} },
+    {
+      type: "server_tool_use",
+      id: "srvtoolu_deferred",
+      name: "web_search",
+      input: { query: "news" },
+    },
+  ],
+};
+
+/** The same turn without the search: nothing is deferred. */
+const clientOnlyTurn: Message = {
+  role: "assistant",
+  content: mixedTurn.content.filter((b) => b.type === "tool_use"),
+};
+
+const erroredResult: ContentBlock = {
+  type: "tool_result",
+  tool_use_id: "tu_a",
+  content: "Error: HTTP 404",
+  is_error: true,
+};
+
+const okResult: ContentBlock = {
+  type: "tool_result",
+  tool_use_id: "tu_b",
+  content: "file contents",
+  is_error: false,
+};
+
+const guidance: TextContent = {
+  type: "text",
+  text: "<system_notice>retry</system_notice>",
+};
+
+describe("buildToolResultFollowUp", () => {
+  test("returns the results untouched when there is no guidance", () => {
+    const results = [erroredResult, okResult];
+
+    expect(buildToolResultFollowUp([opener, mixedTurn], results, [])).toBe(
+      results,
+    );
+  });
+
+  test("appends guidance as separate blocks when no server tool is deferred", () => {
+    const followUp = buildToolResultFollowUp(
+      [opener, clientOnlyTurn],
+      [erroredResult, okResult],
+      [guidance],
+    );
+
+    expect(followUp).toEqual([erroredResult, okResult, guidance]);
+  });
+
+  test("folds guidance into the errored tool_result when a server tool is deferred", () => {
+    const followUp = buildToolResultFollowUp(
+      [opener, mixedTurn],
+      [erroredResult, okResult],
+      [guidance],
+    );
+
+    expect(followUp.map((b) => b.type)).toEqual(["tool_result", "tool_result"]);
+    expect(followUp[0]).toEqual({
+      ...erroredResult,
+      content: `Error: HTTP 404\n\n${guidance.text}`,
+    });
+    expect(followUp[1]).toBe(okResult);
+  });
+
+  test("falls back to the last tool_result when none errored", () => {
+    const followUp = buildToolResultFollowUp(
+      [opener, mixedTurn],
+      [okResult, { ...okResult, tool_use_id: "tu_a" }],
+      [guidance],
+    );
+
+    expect(followUp.map((b) => b.type)).toEqual(["tool_result", "tool_result"]);
+    expect(followUp[0]).toBe(okResult);
+    expect(followUp[1]).toMatchObject({
+      tool_use_id: "tu_a",
+      content: `file contents\n\n${guidance.text}`,
+    });
+  });
+});

package/src/__tests__/tool-result-metadata-plumbing.test.ts

@@ -27,6 +27,7 @@ mock.module("../persistence/llm-request-log-store.js", () => ({
 
 // ── Imports (after mocks) ─────────────────────────────────────────────────────
 import type { AssistantEvent } from "../api/index.js";
+import { toolImageFilename } from "../daemon/assistant-attachments.js";
 import type {
   EventHandlerDeps,
   EventHandlerState,
@@ -34,6 +35,7 @@ import type {
 import {
   createEventHandlerState,
   handleToolResult,
+  handleToolUse,
 } from "../daemon/conversation-agent-loop-handlers.js";
 import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
 
@@ -139,3 +141,64 @@ describe("tool_result activityMetadata plumbing", () => {
     expect(toolResultEvent?.activityMetadata).toBeUndefined();
   });
 });
+
+describe("computer-use screenshot capture", () => {
+  test("tracks direct and wrapped invocations but excludes their images from ordinary promotion", () => {
+    const state = createEventHandlerState();
+    const { deps } = createCollectorDeps();
+
+    handleToolUse(state, deps, {
+      type: "tool_use",
+      id: "direct-call",
+      name: "computer_use_click",
+      input: { x: 10, y: 20 },
+    });
+    handleToolUse(state, deps, {
+      type: "tool_use",
+      id: "wrapped-call",
+      name: "skill_execute",
+      input: { tool: "computer_use_scroll" },
+    });
+    handleToolUse(state, deps, {
+      type: "tool_use",
+      id: "ordinary-call",
+      name: "browser_screenshot",
+      input: {},
+    });
+    handleToolResult(state, deps, {
+      type: "tool_result",
+      toolUseId: "wrapped-call",
+      content: "scrolled",
+      isError: false,
+      contentBlocks: [
+        {
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: "image/png",
+            data: "c2NyZWVuc2hvdA==",
+          },
+        },
+      ],
+    });
+
+    expect(state.computerUseToolUseIds).toEqual([
+      "direct-call",
+      "wrapped-call",
+    ]);
+    expect(state.computerUseToolNames).toEqual(
+      new Map([
+        ["direct-call", "computer_use_click"],
+        ["wrapped-call", "computer_use_scroll"],
+      ]),
+    );
+    expect(
+      toolImageFilename(
+        "image/png",
+        state.computerUseToolNames.get("wrapped-call"),
+      ),
+    ).toBe("computer-use-scroll.png");
+    expect(state.computerUseScreenshotBlocks.has("wrapped-call")).toBe(true);
+    expect(state.accumulatedToolContentBlocks).toEqual([]);
+  });
+});

package/src/__tests__/unicode.test.ts

@@ -4,6 +4,7 @@ import {
   safeStringSlice,
   stripOrphanedSurrogates,
   stripOrphanedSurrogatesDeep,
+  surrogateSafeWindow,
 } from "../util/unicode.js";
 
 // U+1F389 PARTY POPPER = "\uD83C\uDF89" (a surrogate pair).
@@ -302,3 +303,38 @@ describe("stripOrphanedSurrogatesDeep", () => {
     expect(() => JSON.parse(json)).not.toThrow();
   });
 });
+
+describe("surrogateSafeWindow", () => {
+  const codeAt = (text: string) => (i: number) => text.charCodeAt(i);
+
+  test("a start that lands on a low surrogate backs up to include the pair", () => {
+    const text = `a${EMOJI}b`;
+    expect(surrogateSafeWindow(text.length, codeAt(text), 2, 10)).toEqual({
+      start: 1,
+      end: 4,
+    });
+  });
+
+  test("an end that would cut a pair backs off one unit", () => {
+    const text = `ab${EMOJI}cd`;
+    expect(surrogateSafeWindow(text.length, codeAt(text), 0, 3)).toEqual({
+      start: 0,
+      end: 2,
+    });
+  });
+
+  test("a one-unit window on a pair takes the whole pair so paging advances", () => {
+    const text = `${EMOJI}x`;
+    expect(surrogateSafeWindow(text.length, codeAt(text), 0, 1)).toEqual({
+      start: 0,
+      end: 2,
+    });
+  });
+
+  test("clamps to the text bounds", () => {
+    expect(surrogateSafeWindow(3, codeAt("abc"), 10, 5)).toEqual({
+      start: 3,
+      end: 3,
+    });
+  });
+});

package/src/agent/loop.ts

@@ -42,6 +42,7 @@ import type {
   Provider,
   ProviderResponse,
   SendMessageOptions,
+  TextContent,
   ToolDefinition,
   ToolResultContent,
 } from "../providers/types.js";
@@ -74,6 +75,7 @@ import {
   isRepairableOrderingError,
   isUserTerminalHistoryError,
 } from "./history-repair/history-repair.js";
+import { buildToolResultFollowUp } from "./tool-result-follow-up.js";
 
 const log = getLogger("agent-loop");
 
@@ -1047,6 +1049,17 @@ export interface AgentLoopConstructorOptions {
   tools?: ToolDefinition[];
   toolExecutor?: LoopToolExecutor;
   resolveTools?: (history: Message[]) => ToolDefinition[];
+  /**
+   * Observer for the final tool array of each provider call, invoked
+   * immediately before the request leaves with exactly what goes on the wire
+   * (after any provider-native tool is appended, past the inter-call throttle
+   * and the pre-model hooks, and not at all once the run is aborted). This is
+   * the only point that sees the sent array: the dynamic `resolveTools`
+   * callback is also consulted out of band (token counting, compaction
+   * estimates), so a consumer that needs "what the last request sent"
+   * subscribes here rather than wrapping the resolver. Must not throw.
+   */
+  onToolsSent?: (tools: ToolDefinition[]) => void;
   /**
    * Conversation this loop drives. Scopes the loop-held compaction circuit
    * breaker and is the source of truth the loop's pipeline contexts and
@@ -1087,6 +1100,7 @@ export class AgentLoop {
   private config: AgentLoopConfig;
   private tools: ToolDefinition[];
   private resolveTools: ((history: Message[]) => ToolDefinition[]) | null;
+  private onToolsSent: ((tools: ToolDefinition[]) => void) | null;
   private toolExecutor: LoopToolExecutor | null;
 
   /**
@@ -1122,6 +1136,7 @@ export class AgentLoop {
       tools,
       toolExecutor,
       resolveTools,
+      onToolsSent,
       conversationId,
       resolveConversationDir,
       transformCompactedHistory,
@@ -1131,6 +1146,7 @@ export class AgentLoop {
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.tools = tools ?? [];
     this.resolveTools = resolveTools ?? null;
+    this.onToolsSent = onToolsSent ?? null;
     this.toolExecutor = toolExecutor ?? null;
     this.conversationId = conversationId;
     this.resolveConversationDir = resolveConversationDir ?? null;
@@ -1544,7 +1560,7 @@ export class AgentLoop {
       turn: number,
     ): Promise<{
       resultBlocks: ContentBlock[];
-      additionalContextBlocks: ContentBlock[];
+      additionalContextBlocks: TextContent[];
     }> => {
       if (conversationDir) {
         const toolCallByUseId = new Map(
@@ -1569,7 +1585,7 @@ export class AgentLoop {
         180_000;
 
       const resultBlocks: ContentBlock[] = [];
-      const additionalContextBlocks: ContentBlock[] = [];
+      const additionalContextBlocks: TextContent[] = [];
       for (const block of rawBlocks) {
         if (block.type !== "tool_result") {
           resultBlocks.push(block);
@@ -2241,6 +2257,11 @@ export class AgentLoop {
         // Latency: the request is about to leave for the provider. The span
         // from here to the first streamed token is time-to-first-token.
         latencyTracker?.mark("request_sent");
+        // Every await that could cancel the call is behind us; a run aborted
+        // during the throttle or a hook never reports an array it did not send.
+        if (!signal?.aborted) {
+          this.onToolsSent?.(currentTools);
+        }
         let response: ProviderResponse;
         try {
           response = await traceAsyncSection("agent-loop:provider-send", () =>
@@ -2945,16 +2966,20 @@ export class AgentLoop {
 
         toolUseTurns++;
 
-        // Append any guidance a post-tool-use hook surfaced via
-        // `additionalContext` (e.g. tool-error retry coaching) as separate
-        // blocks. They join the provider-bound history below but were not part
-        // of the tool_result events emitted above, so the model sees the
-        // guidance while the client-facing and persisted tool output stay the
-        // tool's actual result.
-        resultBlocks.push(...additionalContextBlocks);
-
-        // Add tool results as a user message and continue the loop.
-        history.push({ role: "user", content: resultBlocks });
+        // Add the tool results, plus any guidance a post-tool-use hook
+        // surfaced via `additionalContext` (e.g. tool-error retry coaching),
+        // as a user message and continue the loop. The guidance joins the
+        // provider-bound history only: it was not part of the tool_result
+        // events emitted above, so the client-facing and persisted tool
+        // output stay the tool's actual result.
+        history.push({
+          role: "user",
+          content: buildToolResultFollowUp(
+            history,
+            resultBlocks,
+            additionalContextBlocks,
+          ),
+        });
 
         // Invoke checkpoint callback after tool results are in history.
         // Handoff takes precedence over the budget gate: a handoff decision

package/src/agent/tool-result-follow-up.ts

@@ -0,0 +1,70 @@
+// Content of the user message that answers a tool-calling assistant turn:
+// the tool_result blocks plus any guidance a post-tool-use hook surfaced via
+// `additionalContext`.
+
+import { analyzeServerToolPairing } from "../providers/server-tool-pairing.js";
+import type {
+  ContentBlock,
+  Message,
+  TextContent,
+  ToolResultContent,
+} from "../providers/types.js";
+
+/**
+ * Hook guidance rides as separate blocks after the results, so the model sees
+ * it while each tool_result stays the tool's actual output. The exception is
+ * an assistant turn that left a server tool (native web search) deferred: the
+ * provider runs a deferred server tool only when the answering message holds
+ * tool_result blocks alone, and any block after the results closes the
+ * assistant turn, after which the provider rejects the unanswered server tool
+ * as unpaired. The guidance is then folded into the content of the last
+ * errored tool_result (the last tool_result when none errored), where the
+ * model still sees it and the search still runs.
+ */
+export function buildToolResultFollowUp(
+  history: ReadonlyArray<Message>,
+  resultBlocks: ContentBlock[],
+  additionalContextBlocks: ReadonlyArray<TextContent>,
+): ContentBlock[] {
+  if (additionalContextBlocks.length === 0) {
+    return resultBlocks;
+  }
+  const targetIndex = foldTargetIndex(resultBlocks);
+  const pairing = analyzeServerToolPairing([
+    ...history,
+    { role: "user", content: resultBlocks },
+  ]);
+  if (pairing.deferredUseIds.size === 0 || targetIndex < 0) {
+    return [...resultBlocks, ...additionalContextBlocks];
+  }
+  const target = resultBlocks[targetIndex] as ToolResultContent;
+  const folded: ToolResultContent = {
+    ...target,
+    content: [target.content, ...additionalContextBlocks.map((b) => b.text)]
+      .filter((text) => text.length > 0)
+      .join("\n\n"),
+  };
+  return resultBlocks.map((block, index) =>
+    index === targetIndex ? folded : block,
+  );
+}
+
+/** Index of the last errored tool_result, else the last tool_result, else -1. */
+function foldTargetIndex(blocks: ReadonlyArray<ContentBlock>): number {
+  let lastResult = -1;
+  for (let index = blocks.length - 1; index >= 0; index--) {
+    const block = blocks[index];
+    // guard:allow-tool-result-only: the answering user message carries client
+    // tool_result blocks only; server-side results live in assistant messages.
+    if (block.type !== "tool_result") {
+      continue;
+    }
+    if (block.is_error) {
+      return index;
+    }
+    if (lastResult < 0) {
+      lastResult = index;
+    }
+  }
+  return lastResult;
+}