pi-condense 2.11.1 → 2.11.3

package/CHANGELOG.md

@@ -7,6 +7,21 @@ Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense) (
 Pushing a `vX.Y.Z` tag triggers `.github/workflows/release.yml`, which runs the tests and
 publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
+## [2.11.3] - 2026-10-04
+
+### Fixed
+
+- Error purge keeps a failed tool call's argument keys, types, and array lengths and shrinks only strings over 200 characters, so grammar-constrained tools such as `codemode` no longer fail every later request with `Grammar tool call "codemode" requires argument "code" to be a string` after a purge. (#19)
+
+## [2.11.2] - 2026-09-29
+
+### Fixed
+
+- Summaries of image-bearing tool results now say an image was returned instead of reporting the read as empty; the summarizer is told never to describe an image it cannot see.
+- `context_tree_query` returns the original image blocks of a pruned image result instead of only its text.
+- Pre-flush dedup no longer aliases different screenshots whose tool text is identical; image data is part of the dedup key.
+- The live reclaim figure prices image blocks at the flat 1,600-token estimate instead of counting base64 as text.
+
 ## [2.11.1] - 2026-09-29
 
 ### Fixed

package/PRUNING.md

@@ -312,7 +312,7 @@ The intended recovery flow is:
 3. The model decides the summary is not enough and wants exact raw output.
 4. The model calls `context_tree_query({ toolCallIds: ["t1", ...] })`. The tool accepts short refs and full `toolCallId`s interchangeably (`indexer.resolveToolCallId`).
 5. The tool looks up those IDs in the pruner index.
-6. The tool returns the original stored output back into the current turn.
+6. The tool returns the original stored output back into the current turn. For each `[image returned: ...]` marker in a recovered record, it appends the original image block from the current session branch whose SHA-256 prefix matches; a record with no marker, or whose image is off the branch, returns text only.
 7. The model can now inspect that raw result and continue reasoning.
 
 ### ASCII: end-to-end "prune, then re-read" flow
@@ -690,10 +690,12 @@ Mechanism:
    - Keying by occurrence key, not bare id, means a duplicate is only ever aliased to the specific earlier *occurrence* it matches byte-for-byte - a reused id whose later occurrence has different content is not conflated with the stale one.
    - A `context-prune-dedup-alias` custom entry is persisted so `reconstructFromSession` rebuilds the maps after a restart.
 4. The duplicate is removed from the batch — no summarizer call, no new index entry.
-5. Later, `pruneMessages` stub-replaces the duplicate's `ToolResultMessage` using the original's short ref, and `context_tree_query` returns the original's record whether the model passes the duplicate's id or the original's.
+5. Later, `pruneMessages` stub-replaces the duplicate's `ToolResultMessage` using the original's short ref, and `context_tree_query` returns the original's record whether the model passes the duplicate's id or the original's. An aliased image result recovers the original's image blocks (see [How the Model Re-reads Raw Outputs](#how-the-model-re-reads-raw-outputs)).
 
 Normalization is conservative: `\r\n` → `\n`, per-line trailing whitespace stripping, final `trim()`. Internal whitespace, tabs, and capitalization are preserved so two genuinely different outputs do **not** collide.
 
+Image blocks enter `resultText` as leading marker lines `[image returned: <mimeType> sha256:<8hex>]` (`extractToolResultText`, `src/batch-capture.ts`), so the marker is part of the dedup key and two image results alias only when their base64 data matches to the 8-hex prefix. Results captured before the marker existed carry none.
+
 Typical wins: re-reading an unchanged file, repeated `git status` / `ls`, retries of the same command. v1 only matches against records **already in the indexer** (cross-flush dedup); intra-flush dedup is deferred so canonicals that get skipped as oversized / trivial never produce dangling aliases.
 
 Edit with `/pruner dedup on|off|status` or the settings overlay.
@@ -715,7 +717,7 @@ The frontier's `lastAttemptedTurnIndex` uses a session-wide numbering domain: it
 - **Tree browser (`/pruner tree`):** interactive, foldable tree of pruned tool calls grouped under their summaries. `Ctrl-O` on a summary node opens the full markdown summary in a bordered overlay.
 - **Configurable summarizer thinking (`summarizerThinking`):** trade summary cost / latency for quality (`off` / `minimal` / `low` / `medium` / `high` / `xhigh`). `default` omits the option entirely so the provider chooses.
 - **Cumulative stats:** `context-prune-stats` entries track input/output tokens and cost of every summarizer call; full detail surfaces in `/pruner stats`. Cost is also emitted on the `cost:external` pi.events channel for external aggregators (cumulative per session, live only).
-- **Live reclaim ratio:** measured once per `pruneMessages` call via `sizeMessages(messages) = JSON.stringify(messages).length`, comparing the input array before pruning to the result after. Estimated tokens = chars / 4. The measurement covers all five phases in a single point (stub-replace, supersede, error-purge, chain-range-prune, orphan-sweep); appears on the status line as `│ prune: ON · 92.0k->14.0k (-85%)` once at least one prune has occurred (the leading `│` keeps the segment visually isolated in the shared footer, load-order independent - there is no trailing divider, since the footer's own space-join between segments already provides one).
+- **Live reclaim ratio:** measured once per `pruneMessages` call via `sizeMessages(messages)` = the sum of `charsOf(message)` (`src/context-metrics.ts`): whole-message JSON chars with each image block priced at a flat 1,600 tokens (6,400 chars) instead of its base64 length, the same estimate the frontier-gap trigger uses. This compares the input array before pruning to the result after. Estimated tokens = chars / 4. The measurement covers all five phases in a single point (stub-replace, supersede, error-purge, chain-range-prune, orphan-sweep); appears on the status line as `│ prune: ON · 92.0k->14.0k (-85%)` once at least one prune has occurred (the leading `│` keeps the segment visually isolated in the shared footer, load-order independent - there is no trailing divider, since the footer's own space-join between segments already provides one).
 - **Live progress for `/pruner now`:** an `aboveEditor` widget shows one row per pending batch with braille spinner, streamed summary-char count, and ✓ / ⚠ status.
 
 ### Summarizer outage fallback
@@ -1094,23 +1096,26 @@ Short refs (`tN`) always resolve 1:1 - one ref, one record - and are the primary
 
 Failed tool calls often embed large argument bodies in the assistant message — a `write` call with a 30 KB file body, an `edit` call with a multiline diff. The error result is small (e.g. `"Error: file not found"`), but the original `arguments` stay in the assistant turn indefinitely.
 
-Error purge replaces those arg bodies with compact stubs after the error has cooled down:
+Error purge shrinks the large string values inside those argument bodies after the error has cooled down. Every key, JSON type, and array length survives; only strings longer than 200 characters (`PURGE_STRING_MIN_CHARS` in `src/error-purge.ts`, not configurable) become a placeholder carrying the original length:
 
 ```
-{ "_purged": "<purged-errored-args size=\"N\"/>" }
+{ "path": "src/foo.ts", "content": "<purged-errored-args size=\"30000\"/>" }
 ```
 
+Providers validate replayed tool calls against the declared schema - pi-ai's grammar-constrained tools (`codemode`) require the input property to be a string - so the shape must stay intact. The 200-character floor keeps `path`, a short `command`, or a small `newText` readable; it is a constant because nobody has a reason to tune a readability guard.
+
 **What triggers a purge:**
 
 - The matching `ToolResultMessage` has `isError: true`.
 - The error occurred at least `purgeErrors.cooldownTurns` assistant turns ago (default 2). The cooldown gives the model 1–2 turns to retry before context is mutated.
-- The JSON-stringified argument body is at least `purgeErrors.minArgChars` characters long (default 500). Small args are not worth the substitution.
+- The JSON-stringified argument body is at least `purgeErrors.minArgChars` characters long (default 500). Small args are not worth the substitution. A body that qualifies but holds no string over 200 characters is returned unchanged.
 
 **What error purge does NOT touch:**
 
 - The `ToolResultMessage` content — the error message stays visible so the model can see what went wrong.
 - Non-errored `toolCall` argument bodies.
 - Argument bodies below `minArgChars`.
+- Keys, non-string values, array lengths, and strings of 200 characters or fewer inside a purged body.
 - Anything when `purgeErrors.enabled` is `false`.
 
 **Transform position:** Error purge runs in Phase 2, after stub-replace and before chain range prune.
@@ -1125,7 +1130,7 @@ Error purge replaces those arg bodies with compact stubs after the error has coo
 |---|---|---|
 | `purgeErrors.enabled` | `true` | Master toggle |
 | `purgeErrors.cooldownTurns` | `2` | Turns to wait after error before purging |
-| `purgeErrors.minArgChars` | `500` | Minimum argument body size to purge |
+| `purgeErrors.minArgChars` | `500` | Minimum JSON body size for a failed call to be scanned; only strings over 200 chars inside it are replaced |
 
 ---
 

package/README.md

@@ -82,7 +82,7 @@ Every summarizer cost update is emitted on the shared `pi.events` channel `cost:
 | Term | Meaning |
 |---|---|
 | Stub | The short breadcrumb (`[Summarized in pruner summary, ref \`t1\`...]`) that replaces a pruned tool result in context |
-| `context_tree_query` | The tool the model calls to recover a stubbed original by ref (`tN`) or `toolCallId`. A reused id returns every matching occurrence, not just one, including any that were content-deduplicated to an earlier record - see [PRUNING.md § Occurrence Identity](PRUNING.md#occurrence-identity) |
+| `context_tree_query` | The tool the model calls to recover a stubbed original by ref (`tN`) or `toolCallId`. Image results come back with their original image blocks. A reused id returns every matching occurrence, not just one, including any that were content-deduplicated to an earlier record - see [PRUNING.md § Occurrence Identity](PRUNING.md#occurrence-identity) |
 | Batch vs chain | A batch is one flush's worth of tool calls; a chain is a longer closed sequence eligible for range compression |
 | Prune frontier | The last attempted prune boundary - advances even on a skip, so nothing is reconsidered twice |
 | Diagnostics (`diag u/m/o/b`) | A self-hiding status-line segment surfacing prune-time degradations: `u` = unresolved chain range, `m` = detection/render id mismatch (informational, does not change what's dropped), `o` = orphan tool-result sweep, `b` = a zero-coverage chain with nothing left to backfill (genuine span mismatch, see below). Each letter's count is omitted when zero; the whole segment disappears when all four are zero. Backing session entries are `context-prune-diagnostic` - see below |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.11.1",
+  "version": "2.11.3",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/batch-capture.test.ts

@@ -3,10 +3,14 @@ import {
   captureBatch,
   captureUnindexedBatchesFromSession,
   deriveLiveTurnIndex,
+  extractToolResultText,
+  imageDigest,
+  imageMarkerDigests,
   projectBranchMessages,
   serializeBatchForSummarizer,
 } from "./batch-capture.js";
 import type { CapturedBatch, CapturedToolCall } from "./types.js";
+import { ToolCallIndexer } from "./indexer.js";
 
 function toolCall(overrides: Partial<CapturedToolCall> = {}): CapturedToolCall {
   return {
@@ -278,3 +282,62 @@ describe("custom-anchor group boundary", () => {
     expect(batches[0].userTurnGroup).toBe(batches[1].userTurnGroup);
   });
 });
+
+const img = (data: string, mimeType = "image/png") => ({ type: "image", data, mimeType });
+
+describe("image markers", () => {
+  test("markers lead the text, in block order, with mime type and 8-hex hash", () => {
+    const text = extractToolResultText({
+      content: [{ type: "text", text: "Read image file [image/png]" }, img("AAAA"), img("BBBB", "image/jpeg")],
+    });
+    expect(text.split("\n")).toEqual([
+      `[image returned: image/png sha256:${imageDigest("AAAA")}]`,
+      `[image returned: image/jpeg sha256:${imageDigest("BBBB")}]`,
+      "Read image file [image/png]",
+    ]);
+    expect(imageDigest("AAAA")).toMatch(/^[0-9a-f]{8}$/);
+  });
+
+  test("same base64 -> same marker, different base64 -> different marker", () => {
+    const a1 = extractToolResultText({ content: [img("AAAA")] });
+    const a2 = extractToolResultText({ content: [img("AAAA")] });
+    const b = extractToolResultText({ content: [img("BBBB")] });
+    expect(a1).toBe(a2);
+    expect(a1).not.toBe(b);
+  });
+
+  test("text-only content is unchanged", () => {
+    expect(extractToolResultText({ content: [{ type: "text", text: "a" }, { type: "text", text: "b" }] })).toBe("a\nb");
+  });
+
+  test("imageMarkerDigests reads the digests back in marker order", () => {
+    const text = extractToolResultText({ content: [img("AAAA"), { type: "text", text: "x" }, img("BBBB")] });
+    expect(imageMarkerDigests(text)).toEqual([imageDigest("AAAA"), imageDigest("BBBB")]);
+    expect(imageMarkerDigests("no markers here")).toEqual([]);
+  });
+
+  test("a result with >2,000 text chars plus an image keeps the marker in the summarizer input", () => {
+    const message = { role: "assistant", content: [{ type: "toolCall", id: "r1", name: "read", input: { path: "a.png" } }], timestamp: 1 };
+    const results = [
+      { role: "toolResult", toolCallId: "r1", toolName: "read", content: [{ type: "text", text: "x".repeat(5000) }, img("AAAA")], isError: false, timestamp: 2 },
+    ];
+    const out = serializeBatchForSummarizer(captureBatch(message, results, 0, 9999));
+    expect(out).toContain(`[image returned: image/png sha256:${imageDigest("AAAA")}]`);
+  });
+
+  test("identical text with different data misses lookupByContent; identical data hits", () => {
+    const captureRead = (id: string, data: string, ts: number) =>
+      captureBatch(
+        { role: "assistant", content: [{ type: "toolCall", id, name: "read", input: { path: "s.png" } }], timestamp: ts },
+        [{ role: "toolResult", toolCallId: id, toolName: "read", content: [{ type: "text", text: "Read image file [image/png]" }, img(data)], isError: false, timestamp: ts + 1 }],
+        0,
+        ts
+      );
+    const idx = new ToolCallIndexer();
+    idx.addBatch(captureRead("r1", "AAAA", 100), () => {});
+    const other = captureRead("r2", "BBBB", 200).toolCalls[0];
+    expect(idx.lookupByContent(other.toolName, other.resultText)).toBeUndefined();
+    const same = captureRead("r3", "AAAA", 300).toolCalls[0];
+    expect(idx.lookupByContent(same.toolName, same.resultText)).toBe("r1@101");
+  });
+});

package/src/batch-capture.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { CapturedBatch, CapturedToolCall, BatchingMode } from "./types.js";
 import { occKey, resultTimestampOf } from "./occurrence-key.js";
@@ -44,13 +45,28 @@ function projectCustomMessageEntry(e: any): any {
   return { role: "custom", customType: e.customType, content: e.content, display: e.display, details: e.details, timestamp: new Date(e.timestamp).getTime() };
 }
 
-/** Joins the text blocks of a ToolResultMessage into a single string. */
+export function imageDigest(data: string): string {
+  return createHash("sha256").update(data).digest("hex").slice(0, 8);
+}
+
+const IMAGE_MARKER_DIGEST = /\[image returned: [^\]\n]* sha256:([0-9a-f]{8})\]/g;
+
+export function imageMarkerDigests(text: string): string[] {
+  return [...text.matchAll(IMAGE_MARKER_DIGEST)].map((m) => m[1]);
+}
+
+/**
+ * Joins a ToolResultMessage's content into one string: one marker line per
+ * image block, then the text blocks. Markers lead because the summarizer
+ * input keeps only the first 2,000 result chars.
+ */
 export function extractToolResultText(msg: any): string {
   const content: any[] = Array.isArray(msg?.content) ? msg.content : [];
-  return content
-    .filter((c: any) => c.type === "text")
-    .map((c: any) => c.text)
-    .join("\n");
+  const markers = content
+    .filter((c: any) => c.type === "image")
+    .map((c: any) => `[image returned: ${c.mimeType} sha256:${imageDigest(c.data)}]`);
+  const texts = content.filter((c: any) => c.type === "text").map((c: any) => c.text);
+  return [...markers, ...texts].join("\n");
 }
 
 /**

package/src/commands.ts

@@ -675,7 +675,7 @@ export function registerCommands(
               label: "Error purge",
               values: ["true", "false"],
               currentValue: String(config.purgeErrors.enabled),
-              description: `Replace failed toolCall argument bodies with compact stubs after a cooldown. Reclaims context from large write/edit args that will never succeed. Currently ${config.purgeErrors.enabled ? "ON" : "OFF"}.`,
+              description: `Shrink long strings inside failed toolCall arguments after a cooldown, keeping argument shape. Reclaims context from large write/edit args that will never succeed. Currently ${config.purgeErrors.enabled ? "ON" : "OFF"}.`,
             },
             {
               id: "purgeErrorsCooldown",

package/src/context-metrics.ts

@@ -4,7 +4,7 @@ import type { ContextMetricsSnapshot, PruneFrontier } from "./types.js";
 
 const IMAGE_TOKEN_ESTIMATE = 1600;
 
-function charsOf(msg: any): number {
+export function charsOf(msg: any): number {
   if (!Array.isArray(msg.content)) return JSON.stringify(msg).length;
   let imageCount = 0;
   const content = msg.content.map((block: any) => {

package/src/error-purge.test.ts

@@ -8,6 +8,9 @@ const defaultConfig: ErrorPurgeConfig = {
   minArgChars: 10,
 };
 
+const LONG = "x".repeat(300);
+const PLACEHOLDER_RE = /^<purged-errored-args size="\d+"\/>$/;
+
 function makeAssistant(toolCallId: string, argsObj: Record<string, any>, turnN?: number) {
   return {
     role: "assistant",
@@ -47,7 +50,7 @@ describe("purgeErroredArgs", () => {
   it("does not purge while still within cooldown", () => {
     // Error at turn 1, current = turn 2, age = 1 < cooldownTurns 2
     const messages = [
-      makeAssistant("tc1", { content: "a very long argument body here" }),
+      makeAssistant("tc1", { content: LONG }),
       makeToolResult("tc1", true),
       makeAssistant("tc2", { cmd: "ls" }),
       makeToolResult("tc2", false),
@@ -55,11 +58,11 @@ describe("purgeErroredArgs", () => {
     const result = purgeErroredArgs(messages, { ...defaultConfig, cooldownTurns: 2 });
     expect(result).toBe(messages);
     const asstMsg = result[0] as any;
-    expect(asstMsg.content[0].arguments).toEqual({ content: "a very long argument body here" });
+    expect(asstMsg.content[0].arguments).toEqual({ content: LONG });
   });
 
   it("purges args after cooldown when args meet minArgChars", () => {
-    const largeArgs = { content: "a very long argument body here" };
+    const largeArgs = { content: LONG };
     const messages = [
       makeAssistant("tc1", largeArgs),
       makeToolResult("tc1", true),
@@ -71,9 +74,8 @@ describe("purgeErroredArgs", () => {
     const result = purgeErroredArgs(messages, { ...defaultConfig, cooldownTurns: 2, minArgChars: 10 });
     expect(result).not.toBe(messages);
     const purgedAsst = result[0] as any;
-    const originalArgLen = JSON.stringify(largeArgs).length;
     expect(purgedAsst.content[0].arguments).toEqual({
-      _purged: `<purged-errored-args size="${originalArgLen}"/>`,
+      content: `<purged-errored-args size="${LONG.length}"/>`,
     });
     // toolResult stays unchanged
     expect((result[1] as any).content[0].text).toBe("Error: file not found");
@@ -81,7 +83,7 @@ describe("purgeErroredArgs", () => {
 
   it("does not purge when args are below minArgChars", () => {
     const messages = [
-      makeAssistant("tc1", { x: "hi" }), // JSON is only ~10 chars
+      makeAssistant("tc1", { x: LONG }),
       makeToolResult("tc1", true),
       makeAssistant("tc2", { cmd: "ls" }),
       makeToolResult("tc2", false),
@@ -94,7 +96,7 @@ describe("purgeErroredArgs", () => {
 
   it("does not purge when isError is false", () => {
     const messages = [
-      makeAssistant("tc1", { content: "a very long argument body here" }),
+      makeAssistant("tc1", { content: LONG }),
       makeToolResult("tc1", false), // NOT an error
       makeAssistant("tc2", { cmd: "ls" }),
       makeToolResult("tc2", false),
@@ -106,7 +108,7 @@ describe("purgeErroredArgs", () => {
   });
 
   it("only purges errored toolCalls in a multi-toolCall assistant message", () => {
-    const largeArgs = { content: "a very long argument body here that is big" };
+    const largeArgs = { content: LONG };
     const okArgs = { cmd: "ls" };
     const messages = [
       // One assistant with two toolCalls: tc-err is errored, tc-ok is not
@@ -129,16 +131,15 @@ describe("purgeErroredArgs", () => {
     expect(result).not.toBe(messages);
     const asst = result[0] as any;
     // errored one is purged
-    const originalArgLen = JSON.stringify(largeArgs).length;
     expect(asst.content[0].arguments).toEqual({
-      _purged: `<purged-errored-args size="${originalArgLen}"/>`,
+      content: `<purged-errored-args size="${LONG.length}"/>`,
     });
     // non-errored one is untouched
     expect(asst.content[1].arguments).toEqual(okArgs);
   });
 
   it("does not mutate the input messages array or any message object", () => {
-    const largeArgs = { content: "a very long argument body here" };
+    const largeArgs = { content: LONG };
     const messages = [
       makeAssistant("tc1", largeArgs),
       makeToolResult("tc1", true),
@@ -156,8 +157,8 @@ describe("purgeErroredArgs", () => {
   });
 
   it("exactly-at-cooldown boundary: age === cooldownTurns is purged", () => {
-    // Error at turn 1, 2 more assistant turns → age = 2 = cooldownTurns (should purge)
-    const largeArgs = { content: "argument body that is long enough to purge" };
+    // Error at turn 1, 2 more assistant turns -> age = 2 = cooldownTurns (should purge)
+    const largeArgs = { content: LONG };
     const messages = [
       makeAssistant("tc1", largeArgs),
       makeToolResult("tc1", true),
@@ -168,12 +169,12 @@ describe("purgeErroredArgs", () => {
     ];
     const result = purgeErroredArgs(messages, { ...defaultConfig, cooldownTurns: 2, minArgChars: 5 });
     expect(result).not.toBe(messages);
-    expect((result[0] as any).content[0].arguments._purged).toBeDefined();
+    expect((result[0] as any).content[0].arguments.content).toMatch(PLACEHOLDER_RE);
   });
 
   it("one-below-cooldown boundary: age === cooldownTurns - 1 is NOT purged", () => {
-    // Error at turn 1, 1 more assistant turn → age = 1 < cooldownTurns 2
-    const largeArgs = { content: "argument body that is long enough to purge" };
+    // Error at turn 1, 1 more assistant turn -> age = 1 < cooldownTurns 2
+    const largeArgs = { content: LONG };
     const messages = [
       makeAssistant("tc1", largeArgs),
       makeToolResult("tc1", true),
@@ -183,4 +184,90 @@ describe("purgeErroredArgs", () => {
     const result = purgeErroredArgs(messages, { ...defaultConfig, cooldownTurns: 2, minArgChars: 5 });
     expect(result).toBe(messages);
   });
+
+  function purgedAfterCooldown(args: Record<string, any>, name: string, minArgChars: number) {
+    const messages = [
+      { ...makeAssistant("tc1", args), content: [{ type: "toolCall", id: "tc1", name, arguments: args }] },
+      { ...makeToolResult("tc1", true), toolName: name },
+      makeAssistant("tc2", { cmd: "ls" }),
+      makeToolResult("tc2", false),
+      makeAssistant("tc3", { cmd: "pwd" }),
+      makeToolResult("tc3", false),
+    ];
+    const result = purgeErroredArgs(messages, { ...defaultConfig, cooldownTurns: 2, minArgChars });
+    return { messages, result, args: (result[0] as any).content[0].arguments };
+  }
+
+  it("keeps a grammar tool's input property a string (codemode, #19)", () => {
+    const { messages, result, args } = purgedAfterCooldown({ code: "x".repeat(1000) }, "codemode", 500);
+    expect(result).not.toBe(messages);
+    expect(typeof args.code).toBe("string");
+    expect(Object.keys(args)).toEqual(["code"]);
+    expect(args.code).toBe('<purged-errored-args size="1000"/>');
+    expect(JSON.stringify(args).length).toBeLessThan(500);
+  });
+
+  it("write-shaped call keeps path verbatim and shrinks content", () => {
+    const { args } = purgedAfterCooldown({ path: "src/foo.ts", content: "x".repeat(30000) }, "write", 500);
+    expect(args.path).toBe("src/foo.ts");
+    expect(args.content).toBe('<purged-errored-args size="30000"/>');
+    expect(JSON.stringify(args).length).toBeLessThan(100);
+  });
+
+  it("edit-shaped call keeps the edits array length and shrinks only long values", () => {
+    const original = {
+      path: "src/foo.ts",
+      edits: [
+        { oldText: "a".repeat(15000), newText: "x" },
+        { oldText: "y", newText: "b".repeat(15000) },
+      ],
+    };
+    const { args } = purgedAfterCooldown(original, "edit", 500);
+    expect(args.path).toBe("src/foo.ts");
+    expect(Array.isArray(args.edits)).toBe(true);
+    expect(args.edits).toHaveLength(2);
+    expect(args.edits[0]).toEqual({ oldText: '<purged-errored-args size="15000"/>', newText: "x" });
+    expect(args.edits[1]).toEqual({ oldText: "y", newText: '<purged-errored-args size="15000"/>' });
+    expect(JSON.stringify(args).length).toBeLessThan(500);
+  });
+
+  it("non-string scalars and short strings pass through by type", () => {
+    const { args } = purgedAfterCooldown({ line: 42, force: true, z: null, s: "short", big: "x".repeat(201) }, "bash", 10);
+    expect(args.line).toBe(42);
+    expect(args.force).toBe(true);
+    expect(args.z).toBeNull();
+    expect(args.s).toBe("short");
+    expect(args.big).toBe('<purged-errored-args size="201"/>');
+  });
+
+  it("a string of exactly 200 chars stays verbatim", () => {
+    const { messages, result } = purgedAfterCooldown({ s: "x".repeat(200) }, "bash", 10);
+    expect(result).toBe(messages);
+  });
+
+  it("eligible body made only of short strings is returned by identity", () => {
+    const original: Record<string, string> = {};
+    for (let i = 0; i < 600; i++) original[`k${i}`] = "v";
+    const { messages, result } = purgedAfterCooldown(original, "bash", 500);
+    expect(result).toBe(messages);
+  });
+
+  it("a second pass over purged output returns the same reference", () => {
+    const { result } = purgedAfterCooldown({ path: "src/foo.ts", content: "x".repeat(1000) }, "write", 10);
+    expect(purgeErroredArgs(result, { ...defaultConfig, cooldownTurns: 2, minArgChars: 10 })).toBe(result);
+  });
+
+  it("preserves own JSON keys even when a key is __proto__", () => {
+    const original = JSON.parse(`{"__proto__":"${LONG}","content":"${LONG}"}`);
+    const { args } = purgedAfterCooldown(original, "write", 10);
+    expect(Object.keys(args)).toEqual(Object.keys(original));
+    expect(args.__proto__).toBe('<purged-errored-args size="300"/>');
+  });
+
+  it("never mutates the original nested arguments", () => {
+    const original = { path: "src/foo.ts", edits: [{ oldText: "a".repeat(300), newText: "x" }] };
+    const snapshot = structuredClone(original);
+    purgedAfterCooldown(original, "edit", 10);
+    expect(original).toEqual(snapshot);
+  });
 });

package/src/error-purge.transport.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "bun:test";
+import { getGrammarToolInput } from "@earendil-works/pi-ai/api/constrained-sampling";
+import { stream } from "@earendil-works/pi-ai/api/openai-completions";
+import type { Model, Tool } from "@earendil-works/pi-ai";
+import { purgeErroredArgs } from "./error-purge.js";
+
+// Chat Completions and Responses share getGrammarToolInput; one transport covers the throw.
+const model: Model<"openai-completions"> = {
+  id: "grammar-test",
+  name: "grammar-test",
+  api: "openai-completions",
+  provider: "openai",
+  baseUrl: "http://127.0.0.1:9",
+  reasoning: false,
+  input: ["text"],
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 128000,
+  maxTokens: 4096,
+  compat: { supportsOpenAIGrammarTools: true },
+};
+
+const codemode: Tool = {
+  name: "codemode",
+  description: "run code",
+  parameters: {
+    type: "object",
+    properties: { code: { type: "string" } },
+    required: ["code"],
+  } as any,
+  constrainedSampling: { type: "grammar", variants: { openai_lark: 'start: /[\\s\\S]*/' } },
+};
+
+const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+const meta = { api: "openai-completions", provider: "openai", model: "grammar-test", usage };
+
+function history(codeArgs: Record<string, unknown>) {
+  return [
+    { role: "user", content: "run it", timestamp: 1 },
+    { role: "assistant", content: [{ type: "toolCall", id: "tc1", name: "codemode", arguments: codeArgs }], ...meta, stopReason: "toolUse", timestamp: 2 },
+    { role: "toolResult", toolCallId: "tc1", toolName: "codemode", content: [{ type: "text", text: "Error: boom" }], isError: true, timestamp: 3 },
+    { role: "assistant", content: [{ type: "text", text: "retrying" }], ...meta, stopReason: "stop", timestamp: 4 },
+    { role: "user", content: "again", timestamp: 5 },
+    { role: "assistant", content: [{ type: "text", text: "ok" }], ...meta, stopReason: "stop", timestamp: 6 },
+    { role: "user", content: "go", timestamp: 7 },
+  ] as any[];
+}
+
+async function request(messages: any[]) {
+  let calls = 0;
+  const fetchStub = (async () => {
+    calls++;
+    throw new Error("connection refused by stub");
+  }) as unknown as typeof fetch;
+  const result = await stream(model, { messages, tools: [codemode] }, { apiKey: "test", fetch: fetchStub, maxRetries: 0 }).result();
+  return { result, calls };
+}
+
+describe("error purge x pi-ai grammar tools (#19)", () => {
+  const config = { enabled: true, cooldownTurns: 2, minArgChars: 500 };
+
+  it("purged codemode args pass getGrammarToolInput (reporter repro)", () => {
+    const purged = purgeErroredArgs(history({ code: "x".repeat(1000) }), config);
+    const args = purged[1].content[0].arguments;
+    expect(typeof args.code).toBe("string");
+    expect(Object.keys(args)).toEqual(["code"]);
+    expect(JSON.stringify(args).length).toBeLessThan(500);
+    expect(() => getGrammarToolInput("codemode", args, "code")).not.toThrow();
+  });
+
+  it("request building succeeds on purged history; failure is the connection, not the grammar", async () => {
+    const purged = purgeErroredArgs(history({ code: "x".repeat(1000) }), config);
+    expect(purged[1].content[0].arguments.code).toMatch(/^<purged-errored-args size=/);
+    const { result, calls } = await request(purged);
+    expect(result.stopReason).toBe("error");
+    // The OpenAI SDK wraps fetch rejections in APIConnectionError and drops the cause message.
+    expect(result.errorMessage).toMatch(/Connection error/);
+    expect(result.errorMessage).not.toMatch(/Grammar tool call/);
+    expect(calls).toBe(1);
+  });
+
+  it("negative control: the old { _purged } shape throws the grammar error before any request", async () => {
+    const legacy = history({ code: "x".repeat(1000) });
+    legacy[1].content[0].arguments = { _purged: '<purged-errored-args size="1012"/>' };
+    const { result, calls } = await request(legacy);
+    expect(result.stopReason).toBe("error");
+    expect(result.errorMessage).toMatch(/Grammar tool call "codemode" requires argument "code" to be a string/);
+    expect(calls).toBe(0);
+  });
+});

package/src/error-purge.ts

@@ -1,8 +1,42 @@
 import type { ErrorPurgeConfig } from "./types.js";
 
+// Keep short paths and commands readable while reclaiming large failed-call bodies.
+const PURGE_STRING_MIN_CHARS = 200;
+
+function shrinkStrings(value: unknown): [unknown, boolean] {
+  if (typeof value === "string") {
+    if (value.length > PURGE_STRING_MIN_CHARS) return [`<purged-errored-args size="${value.length}"/>`, true];
+    return [value, false];
+  }
+  if (Array.isArray(value)) {
+    let out: unknown[] | undefined;
+    for (let i = 0; i < value.length; i++) {
+      const [next, changed] = shrinkStrings(value[i]);
+      if (!changed) continue;
+      out ??= value.slice();
+      out[i] = next;
+    }
+    return out ? [out, true] : [value, false];
+  }
+  if (value !== null && typeof value === "object") {
+    const object = value as Record<string, unknown>;
+    let out: Record<string, unknown> | undefined;
+    for (const key of Object.keys(object)) {
+      const [next, changed] = shrinkStrings(object[key]);
+      if (!changed) continue;
+      // Spread creates own data properties, including JSON's possible __proto__ key.
+      out ??= { ...object };
+      out[key] = next;
+    }
+    return out ? [out, true] : [value, false];
+  }
+  return [value, false];
+}
+
 /**
- * Replaces the `arguments` body of failed toolCall blocks with a compact stub
- * once the error is old enough to be beyond the cooldown window.
+ * Shrinks long strings in failed toolCall arguments after the cooldown window.
+ * Keys and JSON types must survive because pi-ai validates grammar-tool input
+ * properties when replaying calls.
  *
  * Why only the arguments, not the whole toolCall or its toolResult:
  *   - The toolResult content (e.g. "Error: file not found") is small and carries
@@ -58,8 +92,11 @@ export function purgeErroredArgs(messages: any[], config: ErrorPurgeConfig): any
       const argBody = JSON.stringify(block.arguments);
       if (argBody.length < config.minArgChars) return block;
 
+      const [shrunk, changed] = shrinkStrings(block.arguments);
+      if (!changed) return block;
+
       contentModified = true;
-      return { ...block, arguments: { _purged: `<purged-errored-args size="${argBody.length}"/>` } };
+      return { ...block, arguments: shrunk };
     });
 
     if (!contentModified) return msg;

package/src/pruner.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import { pruneMessages, sizeMessages } from "./pruner.js";
+import { charsOf } from "./context-metrics.js";
 import { ToolCallIndexer } from "./indexer.js";
 import { CUSTOM_TYPE_INDEX } from "./types.js";
 import type { ChainCompressionConfig, ChainCompressionEntry } from "./types.js";
@@ -277,7 +278,7 @@ describe("pruneMessages", () => {
 
   it("purges errored toolCall args through errorPurge wiring", () => {
     const indexer = makeMockIndexer();
-    const largeArgs = { content: "x".repeat(200) };
+    const largeArgs = { path: "src/foo.ts", content: "x".repeat(300) };
     const messages: any[] = [
       {
         role: "assistant",
@@ -343,7 +344,8 @@ describe("pruneMessages", () => {
     expect(pruned).toBe(true);
     const errAsst = out.find((m: any) => m.role === "assistant" && m.timestamp === 100) as any;
     expect(errAsst).toBeDefined();
-    expect(errAsst.content[0].arguments._purged).toMatch(/^<purged-errored-args size=/);
+    expect(errAsst.content[0].arguments.path).toBe("src/foo.ts");
+    expect(errAsst.content[0].arguments.content).toMatch(/^<purged-errored-args size=/);
   });
 
   it("spill stub tolerates absent spillBytes/resultPreview", () => {
@@ -899,6 +901,19 @@ describe("occurrence-keyed coverage via mock indexer (spill / protection / grace
 });
 
 describe("sizeMessages", () => {
+  it("prices an image block with the flat charsOf estimate, not its base64 length", () => {
+    const msg = {
+      role: "toolResult",
+      toolCallId: "r1",
+      toolName: "read",
+      content: [{ type: "text", text: "Read image file [image/png]" }, { type: "image", data: "A".repeat(137000), mimeType: "image/png" }],
+      isError: false,
+      timestamp: 1,
+    };
+    expect(sizeMessages([msg])).toBe(charsOf(msg));
+    expect(sizeMessages([msg])).toBeLessThan(JSON.stringify(msg).length / 10);
+  });
+
   it("counts hidden fields (thinking blocks), not just visible text", () => {
     // Two messages with identical visible .text but different hidden content.
     // sizeMessages must count the full serialized weight so all reclaim
@@ -995,7 +1010,7 @@ describe("G4/C3: orphan-sweep zero-fire proof across pruner fixtures", () => {
     }],
     ["purges errored toolCall args through errorPurge wiring", () => {
       const indexer = makeMockIndexer();
-      const largeArgs = { content: "x".repeat(200) };
+      const largeArgs = { path: "src/foo.ts", content: "x".repeat(300) };
       const messages: any[] = [
         { role: "assistant", content: [{ type: "toolCall", id: "tc-err", name: "write", arguments: largeArgs }], timestamp: 100, usage: {}, stopReason: "tool_use" },
         { role: "toolResult", toolCallId: "tc-err", toolName: "write", content: [{ type: "text", text: "Error: permission denied" }], isError: true, timestamp: 110 },

package/src/pruner.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { charsOf } from "./context-metrics.js";
 import type { ToolCallIndexer } from "./indexer.js";
 import type { ChainCompressionConfig, ErrorPurgeConfig } from "./types.js";
 import { isProtected, type ProtectionConfig } from "./protected.js";
@@ -11,13 +12,13 @@ import type { DiagnosticSink } from "./diagnostics.js";
 import { applySupersede, type SupersedeState } from "./supersede.js";
 
 /**
- * Estimate of a message array's context weight. Serializing the whole array
- * (not just visible text) is deliberate: it counts tool-call argument bodies
- * (error-purge) and tool-result arrays (stub-replace / chain-range) so all
- * reclaim mechanisms register.
+ * Estimate of a message array's context weight: whole-message JSON chars
+ * (tool-call arguments, tool-result arrays, hidden blocks) so every reclaim
+ * mechanism registers, with image blocks at the flat estimate `charsOf`
+ * shares with the frontier-gap trigger.
  */
 export function sizeMessages(messages: any[]): number {
-  return JSON.stringify(messages).length;
+  return messages.reduce((sum, message) => sum + charsOf(message), 0);
 }
 
 /**
@@ -154,7 +155,7 @@ export function pruneMessages(
     }
   }
 
-  // Phase 2: error purge — replace failed toolCall arg bodies after cooldown
+  // Phase 2: error purge - shrink long strings in failed toolCall args after cooldown
   if (errorPurge?.enabled) {
     const afterPurge = purgeErroredArgs(current, errorPurge);
     if (afterPurge !== current) {

package/src/query-tool.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { registerQueryTool } from "./query-tool.js";
+import { imageDigest } from "./batch-capture.js";
 import { ToolCallIndexer } from "./indexer.js";
 import type { CapturedBatch } from "./types.js";
 
@@ -23,14 +24,72 @@ const captureLegacy = (idx: ToolCallIndexer, id: string, timestamp: number, text
   idx.addBatch(batch, () => {});
 };
 
-// execute returns { content: [{ type: "text", text }], details } (src/query-tool.ts:73-76)
-const runTool = async (indexer: ToolCallIndexer, toolCallIds: string[]): Promise<string> => {
+const runToolResult = async (indexer: ToolCallIndexer, toolCallIds: string[], branch: any[] = []): Promise<any> => {
   let registered: any;
   registerQueryTool({ registerTool: (def: any) => (registered = def) } as any, indexer);
-  const result = await registered.execute("call-1", { toolCallIds }, undefined, undefined, undefined);
-  return result.content[0].text as string;
+  return registered.execute("call-1", { toolCallIds }, undefined, undefined, { sessionManager: { getBranch: () => branch } });
 };
 
+const runTool = async (indexer: ToolCallIndexer, toolCallIds: string[], branch: any[] = []): Promise<string> =>
+  (await runToolResult(indexer, toolCallIds, branch)).content[0].text as string;
+
+const png = (data: string) => ({ type: "image", data, mimeType: "image/png" });
+const branchWith = (...images: any[]) => [
+  { type: "message", message: { role: "toolResult", toolCallId: "x", content: [{ type: "text", text: "Read image file [image/png]" }, ...images] } },
+];
+const markerText = (data: string) => `[image returned: image/png sha256:${imageDigest(data)}]\nRead image file [image/png]`;
+
+describe("context_tree_query image recovery", () => {
+  test("short ref returns only the image named by its marker", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "read_1", 1150, markerText("AAAA"), 0);
+    idx.registerSummaryRefs([{ shortId: "t1", toolCallId: "read_1", resultTimestamp: 1150 }]);
+    const result = await runToolResult(idx, ["t1"], branchWith(png("AAAA"), png("BBBB")));
+    expect(result.content[0].type).toBe("text");
+    expect(result.content.slice(1)).toEqual([png("AAAA")]);
+  });
+
+  test("explicit occurrence key returns the image", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "read_1", 1150, markerText("AAAA"), 0);
+    const result = await runToolResult(idx, ["read_1@1150"], branchWith(png("AAAA")));
+    expect(result.content.slice(1)).toEqual([png("AAAA")]);
+  });
+
+  test("bare alias id returns its original's image", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "read_1", 1150, markerText("AAAA"), 0);
+    idx.registerDuplicate("read_2@2150", "read_1@1150", () => {});
+    const result = await runToolResult(idx, ["read_2"], branchWith(png("AAAA")));
+    expect(result.content.slice(1)).toEqual([png("AAAA")]);
+  });
+
+  test("legacy record without marker returns text only", async () => {
+    const idx = new ToolCallIndexer();
+    captureLegacy(idx, "read_1", 1000, "Read image file [image/png]", 0);
+    expect((await runToolResult(idx, ["read_1"], branchWith(png("AAAA")))).content).toHaveLength(1);
+  });
+
+  test("image off the current branch returns text only", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "read_1", 1150, markerText("AAAA"), 0);
+    expect((await runToolResult(idx, ["read_1"], branchWith(png("BBBB")))).content).toHaveLength(1);
+  });
+
+  test("pre-change alias between different images returns text only", async () => {
+    const idx = new ToolCallIndexer();
+    capture(idx, "read_1", 1150, "Read image file [image/png]", 0);
+    idx.registerDuplicate("read_2@2150", "read_1@1150", () => {});
+    expect((await runToolResult(idx, ["read_2"], branchWith(png("AAAA"), png("BBBB")))).content).toHaveLength(1);
+  });
+
+  test("description mentions image blocks", () => {
+    let registered: any;
+    registerQueryTool({ registerTool: (def: any) => (registered = def) } as any, new ToolCallIndexer());
+    expect(registered.description).toContain("image blocks");
+  });
+});
+
 describe("context_tree_query occurrence handling", () => {
   test("a bare id with two occurrences returns both blocks, chronologically", async () => {
     const idx = new ToolCallIndexer();

package/src/query-tool.ts

@@ -2,6 +2,8 @@ import { readFile } from "node:fs/promises";
 import { Type } from "@sinclair/typebox";
 import { truncateHead, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ImageContent } from "@earendil-works/pi-ai";
+import { imageDigest, imageMarkerDigests } from "./batch-capture.js";
 import type { ToolCallIndexer } from "./indexer.js";
 import { QUERY_TOOL_NAME } from "./types.js";
 
@@ -19,7 +21,7 @@ export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): v
     name: QUERY_TOOL_NAME,
     label: "Query Original Tool History",
     description:
-      "Retrieve original tool call results that have been pruned from active context. Pass the short refs listed in a pruner-summary message, e.g. context_tree_query({ toolCallIds: [\"t12\", \"t3\"] }), to get back the full original outputs. A raw id that was reused returns every occurrence, each labelled id@timestamp.",
+      "Retrieve original tool call results that have been pruned from active context. Pass the short refs listed in a pruner-summary message, e.g. context_tree_query({ toolCallIds: [\"t12\", \"t3\"] }), to get back the full original outputs. A raw id that was reused returns every occurrence, each labelled id@timestamp. Results include the original image blocks when the pruned output carried images.",
     promptSnippet: "Retrieve original pruned tool outputs by short ref",
     promptGuidelines: [
       "When you need the full output of a tool call that was summarized and pruned from context, use context_tree_query with the short refs listed in the relevant pruner-summary message.",
@@ -30,7 +32,15 @@ export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): v
       }),
     }),
 
-    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const branchImages = new Map<string, ImageContent>();
+      for (const entry of ctx.sessionManager.getBranch()) {
+        if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+        for (const block of entry.message.content) {
+          if (block.type === "image") branchImages.set(imageDigest(block.data), block);
+        }
+      }
+      const images: ImageContent[] = [];
       const foundRecords: Record<string, any> = {};
       const blocks: string[] = [];
 
@@ -70,6 +80,11 @@ export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): v
             }
           }
 
+          for (const digest of imageMarkerDigests(raw)) {
+            const image = branchImages.get(digest);
+            if (image) images.push(image);
+          }
+
           const t = truncateHead(raw, {
             maxLines: DEFAULT_MAX_LINES,
             maxBytes: DEFAULT_MAX_BYTES,
@@ -87,7 +102,7 @@ export function registerQueryTool(pi: ExtensionAPI, indexer: ToolCallIndexer): v
       const combined = blocks.join("\n\n---\n\n");
 
       return {
-        content: [{ type: "text", text: combined }],
+        content: [{ type: "text", text: combined }, ...images],
         details: { results: foundRecords },
       };
     },

package/src/spill.test.ts

@@ -152,7 +152,7 @@ describe("G4/C4: legacy bare-id sidecar recovery", () => {
 
       let registered: any;
       registerQueryTool({ registerTool: (def: any) => (registered = def) } as any, indexer);
-      const result = await registered.execute("call-1", { toolCallIds: ["bash_7"] }, undefined, undefined, undefined);
+      const result = await registered.execute("call-1", { toolCallIds: ["bash_7"] }, undefined, undefined, { sessionManager: { getBranch: () => [] } });
       const text = result.content[0].text as string;
 
       expect(text).toContain("OLD SPILLED BODY");

package/src/summarizer.test.ts

@@ -1,5 +1,26 @@
-import { describe, it, expect } from "bun:test";
-import { isUsableSummary } from "./summarizer.js";
+import { describe, it, expect, mock } from "bun:test";
+import * as actualCompat from "@earendil-works/pi-ai/compat";
+
+let seenInput: any;
+mock.module("@earendil-works/pi-ai/compat", () => ({
+  ...actualCompat,
+  stream: (_model: any, input: any) => {
+    seenInput = input;
+    return {
+      async *[Symbol.asyncIterator]() {},
+      async result() {
+        return {
+          stopReason: "stop",
+          content: [{ type: "text", text: "- summary" }],
+          usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        };
+      },
+    };
+  },
+}));
+
+const { isUsableSummary, summarizeBatch } = await import("./summarizer.js");
+const { DEFAULT_CONFIG } = await import("./types.js");
 
 describe("isUsableSummary", () => {
   it("accepts non-empty text that stopped normally", () => {
@@ -15,3 +36,26 @@ describe("isUsableSummary", () => {
     expect(isUsableSummary("- partial", "length")).toBe(false);
   });
 });
+
+describe("summarizer prompt", () => {
+  it("tells the model that an image marker is an image it cannot see", async () => {
+    const model = { id: "m", provider: "p", name: "M" };
+    const ctx = {
+      model,
+      modelRegistry: {
+        find: () => model,
+        getApiKeyAndHeaders: async () => ({ ok: true, apiKey: "k", headers: {} }),
+        getProviderAuth: async () => undefined,
+      },
+      ui: { notify() {} },
+    } as any;
+    const batch = {
+      turnIndex: 0,
+      timestamp: 0,
+      assistantText: "",
+      toolCalls: [{ toolCallId: "a", toolName: "read", args: {}, resultText: "[image returned: image/png sha256:3f9a2c1e]\nRead image file [image/png]", isError: false }],
+    } as any;
+    await summarizeBatch(batch, DEFAULT_CONFIG, ctx);
+    expect(JSON.stringify(seenInput)).toContain("means the tool returned an image you cannot see");
+  });
+});

package/src/summarizer.ts

@@ -20,6 +20,8 @@ For each tool call provide:
 
 Keep each tool call to 1-3 bullet points. Skip calls that succeeded with nothing reusable to record. Be concise.
 
+A result line of the form [image returned: <type> sha256:<hash>] means the tool returned an image you cannot see: state that an image was returned, and never describe or guess its content.
+
 Begin the first bullet of each tool call with that tool's [[N:toolname]] label, copied verbatim (both the number and the name) from its line in the input, as the plain, first thing on the line - no bold, backticks, or list numbering around it. Do not renumber, rename, or invent labels; if you skip a tool, skip its label too.`;
 
 const RANGE_SYSTEM_PROMPT = `You are fusing several per-step summaries of one CLOSED sub-task from an AI coding assistant's history into a SINGLE cohesive summary.