pi-condense 2.11.0 → 2.11.2

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.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
+
+- The frontier-gap metric prices image blocks at a flat estimate instead of counting base64 as text, so screenshot reads no longer trigger a premature frontier-gap flush that prunes images before the model sees them.
+
 ## [2.11.0] - 2026-09-24
 
 ### Added

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

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.0",
+  "version": "2.11.2",
   "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/context-metrics.test.ts

@@ -260,6 +260,22 @@ describe("computeContextMetrics", () => {
     expect(result.frontierGapTokens).toBe(expected);
   });
 
+  test("frontierGapTokens: image blocks use a flat estimate instead of base64 length", () => {
+    const msgs = [userMsg(100), assistantWithTools(200, ["tc1", "tc2", "tc3"])];
+    for (let i = 0; i < 3; i++) {
+      const result = toolResult(300 + i, `tc${i + 1}`, "read", "screenshot");
+      result.content.push({ type: "image", data: "A".repeat(137000), mimeType: "image/png" });
+      msgs.push(result);
+    }
+    const expected = msgs.slice(2).reduce((sum, msg) => {
+      const stub = { ...msg, content: msg.content.map((block: any) => block.type === "image" ? { type: "image" } : block) };
+      return sum + Math.round((JSON.stringify(stub).length + 1600 * 4) / 4);
+    }, 0);
+    const result = computeContextMetrics(msgs, null, noSummarized, noProtected);
+    expect(result.frontierGapTokens).toBe(expected);
+    expect(result.frontierGapTokens).toBeLessThan(20000);
+  });
+
   test("frontierGapTokens: boundary mid-turn split excludes at-or-before calls, includes later calls in same turn", () => {
     const msgs = [userMsg(100), assistantWithTools(200, ["tc1", "tc2"]), toolResult(300, "tc1"), toolResult(310, "tc2")];
     const frontier = fullFrontier({ lastAttemptedToolCallId: "tc1", lastAttemptedTurnIndex: 0 });

package/src/context-metrics.ts

@@ -2,8 +2,17 @@ import { detectChains, isChainAnchorCustom } from "./chain-detector.js";
 import { occKey, resultTimestampOf } from "./occurrence-key.js";
 import type { ContextMetricsSnapshot, PruneFrontier } from "./types.js";
 
-function charsOf(msg: any): number {
-  return JSON.stringify(msg).length;
+const IMAGE_TOKEN_ESTIMATE = 1600;
+
+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) => {
+    if (block?.type !== "image") return block;
+    imageCount++;
+    return { type: "image" };
+  });
+  return JSON.stringify({ ...msg, content }).length + imageCount * IMAGE_TOKEN_ESTIMATE * 4;
 }
 
 function tokensOf(msg: any): number {

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";
@@ -899,6 +900,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

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);
 }
 
 /**

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.