pi-vision-handoff 0.9.8 → 0.10.1

package/README.md

@@ -45,6 +45,8 @@ No `settings.json` touched. No per-provider glue. Pick a describer once and ever
 - **⚡ Pre-warmed at paste-enter** — the moment you press enter, `before_agent_start` scans the prompt for pasted image temp-file paths — pi-clipboard, localterm-paste, and any other paste mechanism that writes a pasted image to a temp file and inserts the path as text — reads them, and kicks off the ONE batched vision call concurrent with the agent's first response — so by the time the agent reads the files, they're already cache hits.
 - **🚀 Paste-time prewarm (opt-in)** — `prewarmPastedImages` (off by default) wraps the editor so pasted clipboard images are described the *instant* their path lands in the prompt — before you hit enter — not at submit. The vision call starts concurrent with you typing your question. Tradeoff: the description is generated without your typed question as context (the question usually isn't entered yet at paste time), and a paste-then-abandon wastes one vision call. TUI only; inactive if another extension replaces the editor. Toggle with `/vision-handoff prewarm on`.
 - **🏁 Async pasted-path fallback (opt-in)** — `asyncClipboardHandoff` races the normal read path against asynchronous delivery. A direct `read` or nested Fabric `pi.read` of the pasted path cancels the fallback and uses the normal tool-result/context flow; otherwise the completed description is queued as a steering message. Its transcript row is collapsed to one line by default and expands with `Ctrl+O`. Toggle it in the picker with `Ctrl+A` or run `/vision-handoff fallback on`.
+- **🧠 Aware prompt (opt-in)** — `awarePrompt` (off by default) injects a system-prompt note on handoff targets telling the text-only model it CAN read images via the read tool (the handoff swaps image blocks for descriptions). Some models otherwise refuse image-reading requests from self-knowledge even though the description is delivered as text. Toggle with `/vision-handoff aware on`.
+- **💾 Session persistence (opt-in)** — `persistDescriptions` writes each generated description into the session file as a `[Image described: <hash>]` marker + text block next to the read-result blob (the blob stays for kitty rendering). On `/resume` — a new process with an empty in-memory cache — the `context` hook matches the marker to the blob by hash and reuses the persisted description, so a resumed session **never re-calls the vision model** for already-described images (no 30-40s re-describe on the first resumed "ciao"). The persisted description is also seeded into the session cache, so later re-reads of the same image hit too. Toggle with `/vision-handoff persist on`.
 - **🛡️ Graceful degradation** — no API key? Describer unreachable? Aborted? The image is replaced with a clean `[Image: description unavailable]` placeholder instead of crashing your turn.
 - **📋 Error logging** — every describer failure and every `image description failed` warning is appended as a JSONL line to `~/.pi/agent/logs/pi-vision-handoff/errors.log`, so a warning like `image description failed — unknown error` is troubleshootable: the detailed reason (exception stack, `stopReason`, config snapshot) is captured at the describer's failure source even when the in-memory error string was already reset by the time the warning fired. Size-capped with a single `.1` backup.
 - **📊 Usage reporting** — every real describer call reports model + tokens (and Neuralwatt energy/cost when the vision model is a Neuralwatt model), via `pi.appendEntry` + a `vision-handoff:usage` event for live consumers.
@@ -64,6 +66,8 @@ No `settings.json` touched. No per-provider glue. Pick a describer once and ever
 | `/vision-handoff auto on` / `off` | Toggle automatic handoff for all non-vision models |
 | `/vision-handoff prewarm on` / `off` | Toggle paste-time prewarm (opt-in, off by default) |
 | `/vision-handoff fallback on` / `off` | Race matching reads against async pasted-path description injection (opt-in) |
+| `/vision-handoff aware on` / `off` | Tell handoff targets they can read images via the read tool (opt-in, off by default) |
+| `/vision-handoff persist on` / `off` | Persist descriptions to the session file; resumed sessions reuse them with no new vision call (opt-in) |
 | `/vision-handoff add ollama/llava:13b` | Force handoff for an extra model |
 | `/vision-handoff remove ollama/llava:13b` | Stop forcing handoff for a model |
 | `/vision-handoff clear` | Clear the configured vision model |
@@ -81,6 +85,8 @@ Created automatically at `~/.pi/agent/extensions/pi-vision-handoff.json` on firs
   "handoffModels": ["ollama/llava:13b"],
   "prewarmPastedImages": false,
   "asyncClipboardHandoff": false,
+  "awarePrompt": false,
+  "persistDescriptions": false,
   "maxTokens": null,
   "cacheMax": 50,
   "maxDescriptionLines": 0,
@@ -97,6 +103,8 @@ Created automatically at `~/.pi/agent/extensions/pi-vision-handoff.json` on firs
 | `handoffModels` | `[]` | Extra `provider/id` refs that should also receive handoff. |
 | `prewarmPastedImages` | `false` | **Opt-in paste-time prewarm.** When `true`, a custom editor wrapper describes pasted clipboard images the instant their temp-file path lands in the prompt (pre-submit), instead of at submit. Trades a bit of description quality (the description is generated without your typed question as context, since the question usually isn't entered yet at paste time) and a speculative vision call on paste-then-abandon, for earlier prewarm. TUI mode only; inactive if another extension has replaced the editor. |
 | `asyncClipboardHandoff` | `false` | **Opt-in async fallback.** Starts from the existing submit-time prewarm. A matching direct `read` or Fabric-nested `pi.read` cancels message delivery; if no matching read wins, the description is queued asynchronously as a collapsed custom message and triggers/continues the agent turn. |
+| `awarePrompt` | `false` | **Opt-in aware prompt.** When `true`, injects a system-prompt note on handoff targets telling the text-only model it CAN read images via the read tool (the handoff swaps image blocks for descriptions). Some models otherwise refuse image-reading requests from self-knowledge. |
+| `persistDescriptions` | `false` | **Opt-in session persistence.** When `true`, every generated description is written into the session file as a `[Image described: <hash>]` marker + description text block in the read tool-result content, next to the blob (which stays for kitty rendering). On `/resume`, the `context` hook matches the marker to the blob by hash and reuses the persisted description — no vision call, no wait. Only real descriptions are persisted (a failed `[Image: description unavailable]` is not replayed; the next turn re-attempts). |
 | `maxTokens` | _(unset = model max, clamped to context window)_ | Cap on a single description's output. `null`/unset = use the vision model's declared max output (`model.maxTokens`), clamped so `maxTokens + 8192 <= contextWindow` (a model whose declared max equals its full context window would otherwise be rejected with a 400). Set a number only to cap cost/latency. A truncation is always surfaced via a `[... description truncated …]` marker when the model hits the limit, so a cut-off description is never mistaken for complete. |
 | `cacheMax` | `50` | Max described images kept in the in-memory cache per session. |
 | `maxDescriptionLines` | `0` | Cap on description lines (`0` = unbounded). Default keeps the full description so the `read` tool's native collapse (`ctrl+o`) handles compactness and the model gets complete context; setting `> 0` applies a lossy head-cap to both the TUI render and the model. |
@@ -214,9 +222,13 @@ The default submit-time pipeline below runs regardless:
           phase (free time: the agent is just waiting for tool results), so
           the batch is COMPLETE before `context` fires → `context` is a
           non-blocking cache hit, not a cold miss on the critical path
-        • does NOT mutate the result: the image stays in storage for kitty
-          inline rendering and `/resume`; the image→text swap happens in the
-          `context` hook (on the cloned LLM-bound payload only)
+        • does NOT mutate the result by default: the image stays in storage for
+          kitty inline rendering and `/resume`; the image→text swap happens in
+          the `context` hook (on the cloned LLM-bound payload only). With the
+          opt-in `persistDescriptions`, it additionally appends a
+          `[Image described: <hash>]` marker + description text block after
+          each image block, so the description survives in the session file
+          for `/resume` (the blob still stays for kitty rendering)
     → context   (FALLBACK + swap — fires before each LLM call)
         • catches image blocks that didn't go through `read`'s tool_result —
           user-attached images, custom extension-injected messages — and
@@ -225,6 +237,12 @@ The default submit-time pipeline below runs regardless:
           loader's current batch; swaps images for text in the cloned LLM-bound
           payload (`emitContext` does a `structuredClone`), leaving storage
           intact for kitty inline rendering and `/resume`
+        • persistence fast-path (opt-in): on `/resume` — new process, empty
+          in-memory cache — images whose session content carries a
+          `[Image described: <hash>]` marker matching their hash are NOT sent
+          to the vision model at all: the persisted description is reused
+          verbatim (blob dropped from the clone, marker stripped) and seeded
+          into the session cache for later re-reads
 
 Because the describer runs during the **tool-result phase** (before the agent's next turn), not during the `context` transform (the critical path right before the LLM call), the agent gets described text immediately when its turn starts — it never waits on the describer inline.
 
@@ -250,7 +268,7 @@ Because pi runs parallel `read` tool calls via `Promise.all` and fires each read
 
 | Hook | Image block shape | Handling |
 |------|-------------------|----------|
-| `context` (all messages) | `{ type: "image", data, mimeType }` (pi-ai internal) | undescribed → replaced with description text; already-described → dropped |
+| `context` (all messages) | `{ type: "image", data, mimeType }` (pi-ai internal) | undescribed → replaced with description text; already-described (persisted `[Image described: <hash>]` marker present) → image dropped, marker stripped, persisted description reused — **no vision call on resume** |
 | `context` (all messages) | `{ type: "image_url", image_url: { url: "data:…" } }` (OpenAI Chat Completions) | detected by shape → replaced with `{ type: "text", text }` |
 | `context` (all messages) | `{ type: "input_image", image_url: "data:…" }` (OpenAI Responses) | detected by shape → replaced with `{ type: "input_text", text }` |
 | `context` (all messages) | `{ type: "image", source: { type: "base64", media_type, data } }` (Anthropic Messages) | detected by shape → replaced with `{ type: "text", text }` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vision-handoff",
-  "version": "0.9.8",
+  "version": "0.10.1",
   "description": "Give text-only pi models vision — describe images with a vision model you pick via an interactive picker, then hand off the text description to non-vision models",
   "type": "module",
   "author": "Tom X Nguyen",
@@ -31,9 +31,9 @@
     "README.md"
   ],
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.3",
-    "@earendil-works/pi-coding-agent": "0.84.3",
-    "@earendil-works/pi-tui": "0.84.3",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
     "@types/node": "25.9.1",
     "@vitest/coverage-v8": "4.1.7",
     "knip": "6.14.1",

package/src/dataloader.ts

@@ -242,6 +242,22 @@ export class DescriptionLoader implements Disposable {
     return promise;
   }
 
+  /** Seed the in-memory cache with a known description for a hash — used on
+   *  session resume, where the `context` hook recovers persisted descriptions
+   *  from the session file and wants later reads of the same image (same hash)
+   *  in this session to hit the cache instead of re-describing. Respects
+   *  `cacheMax` eviction like a resolved load. No-op when the hash is already
+   *  cached (fresh value wins). */
+  seedDescription(hash: string, description: string): void {
+    if (this.cache.has(hash)) return;
+    const cfg = this.deps.getConfig();
+    if (this.cache.size >= cfg.cacheMax) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) this.cache.delete(firstKey);
+    }
+    this.cache.set(hash, Promise.resolve(description));
+  }
+
   /** Abandon any in-flight batch and clear turn context. Used on session reset
    *  (the batch's turn is gone) — also exposed via `[Symbol.dispose]` so a
    *  `using` binding can scope a loader lifetime. The description cache is

package/src/index.ts

@@ -185,6 +185,15 @@ export interface VisionHandoffConfig {
   prompt?: string;
   /** Override the user-prompt prefix (defaults to DEFAULT_USER_PROMPT_PREFIX). */
   userPromptPrefix?: string;
+  /** Opt-in: when true, generated descriptions are PERSISTED to the session
+   *  file as `[Image described: <hash>]` marker + description text blocks in
+   *  the read tool-result content (the image blob stays for kitty rendering).
+   *  On session resume — when the in-memory cache is empty (new process) — the
+   *  `context` hook matches the marker to the blob by hash and reuses the
+   *  persisted description WITHOUT calling the vision model, eliminating the
+   *  30-40s re-describe latency on every resumed "ciao". Off by default:
+   *  descriptions are generated per-session as before. */
+  persistDescriptions: boolean;
   /** Whether the vision describer should reason (think) before describing.
    *  Off by default — describing images is a perception task, not a reasoning
    *  one, and thinking adds latency + cost. When on, the level below is sent
@@ -195,6 +204,13 @@ export interface VisionHandoffConfig {
    *  {@link THINKING_LEVELS}. Ignored when {@link thinking} is off or the
    *  vision model lacks reasoning support. */
   thinkingLevel: ThinkingLevel;
+  /** Opt-in: inject a system-prompt note on handoff targets telling the
+   *  text-only model it CAN read images via the read tool (the handoff swaps
+   *  image blocks for descriptions). Off by default — without it, some
+   *  models refuse image-reading requests from their own self-knowledge even
+   *  though the description is delivered as text. Toggle with
+   *  `/vision-handoff aware on|off`. */
+  awarePrompt: boolean;
 }
 
 export const DEFAULT_CONFIG: VisionHandoffConfig = {
@@ -205,11 +221,13 @@ export const DEFAULT_CONFIG: VisionHandoffConfig = {
   handoffModels: [],
   prewarmPastedImages: false,
   asyncClipboardHandoff: false,
+  persistDescriptions: false,
   maxTokens: undefined,
   cacheMax: DEFAULT_CACHE_MAX,
   maxDescriptionLines: DEFAULT_MAX_DESCRIPTION_LINES,
   thinking: false,
   thinkingLevel: DEFAULT_THINKING_LEVEL,
+  awarePrompt: false,
 };
 
 /** Parse a "provider/id" reference. Returns null if malformed. */
@@ -264,6 +282,7 @@ export function normalizeConfig(raw: unknown): VisionHandoffConfig {
   if (typeof obj.asyncClipboardHandoff === "boolean") {
     base.asyncClipboardHandoff = obj.asyncClipboardHandoff;
   }
+  if (typeof obj.persistDescriptions === "boolean") base.persistDescriptions = obj.persistDescriptions;
   // maxTokens: optional. undefined (default) = no artificial cap. Only set when
   // a valid positive finite number is given; any other value leaves it unset.
   if (typeof obj.maxTokens === "number" && Number.isFinite(obj.maxTokens) && obj.maxTokens > 0) {
@@ -285,6 +304,7 @@ export function normalizeConfig(raw: unknown): VisionHandoffConfig {
 
   if (typeof obj.thinking === "boolean") base.thinking = obj.thinking;
   if (isThinkingLevel(obj.thinkingLevel)) base.thinkingLevel = obj.thinkingLevel;
+  if (typeof obj.awarePrompt === "boolean") base.awarePrompt = obj.awarePrompt;
 
   return base;
 }
@@ -484,6 +504,50 @@ export function parseBatchedDescriptions(text: string, count: number): (string |
   return out;
 }
 
+/** Marker prefix/suffix framing a PERSISTED image description in the session
+ *  file. When {@link VisionHandoffConfig.persistDescriptions} is on, the read
+ *  tool `tool_result` handler appends a text block of the form
+ *  `[Image described: <hash>]\n<description>` right after the image block (the
+ *  blob stays for kitty inline rendering). On resume the `context` hook matches
+ *  the marker to the blob by hash and reuses the description — no vision call
+ *  for already-described images. */
+export const IMAGE_DESCRIBED_PREFIX = "[Image described: ";
+export const IMAGE_DESCRIBED_SUFFIX = "]";
+
+/** Regex matching a persisted-description text block: the marker (any 32-hex
+ *  hash — `imageHash()`'s sha256 slice) followed by the description body, which
+ *  may span multiple lines (the `[Image: …]` envelope is kept verbatim). */
+const PERSISTED_DESCRIPTION_RE = /\[Image described: ([0-9a-f]{32})\]\r?\n?([\s\S]*)/;
+
+/** Build the persisted-description text block for `hash`: the marker line, then
+ *  the (already wrapped/truncated) description on the following line(s). */
+export function buildPersistedDescriptionBlock(hash: string, description: string): string {
+  return `${IMAGE_DESCRIBED_PREFIX}${hash}${IMAGE_DESCRIBED_SUFFIX}\n${description}`;
+}
+
+/** Parse a persisted-description text block, returning the marker's image hash
+ *  and the description body. Returns null when the text carries no
+ *  `[Image described: <hash>]` marker or the body is empty. Callers decide what
+ *  counts as a usable description (e.g. filter out the UNAVAILABLE placeholder
+ *  so a persisted failure still falls back to a fresh vision call). */
+export function parsePersistedDescriptionBlock(
+  text: string,
+): { hash: string; description: string } | null {
+  const m = PERSISTED_DESCRIPTION_RE.exec(text);
+  if (!m) return null;
+  const description = m[2];
+  if (!description) return null;
+  return { hash: m[1], description };
+}
+
+/** Remove a `[Image described: <hash>]` marker line from a text block, leaving
+ *  just the description. Used by the `context` hook on the LLM-bound clone so
+ *  the model never sees the marker itself (the stored session block keeps it).
+ *  Returns the text unchanged when no marker is present. */
+export function stripPersistedMarker(text: string): string {
+  return text.replace(/\[Image described: [0-9a-f]{32}\]\r?\n?/, "");
+}
+
 /** Truncate (if configured) and wrap a raw description in the `[Image: …]`
  *  placeholder envelope used by every insertion path. Centralises the wrap+
  *  truncate logic shared by the read-tool and context injection paths so both

package/vision-handoff.ts

@@ -43,6 +43,9 @@ import {
   readConfig,
   stripNonVisionImageNote,
   writeConfig,
+  buildPersistedDescriptionBlock,
+  parsePersistedDescriptionBlock,
+  stripPersistedMarker,
   HANDOFF_COMMAND_DESCRIPTION,
   UNAVAILABLE,
   type ExtractedImage,
@@ -61,6 +64,16 @@ import { Text } from "@earendil-works/pi-tui";
 
 let config: VisionHandoffConfig = readConfig();
 
+/** Marker used to dedup the aware-prompt system-prompt note across turns. */
+const AWARE_PROMPT_MARKER = "# Image reading (pi-vision-handoff active)";
+
+/** System-prompt note injected on handoff targets when `awarePrompt` is on.
+ *  Tells the text-only model it CAN read images via the read tool, since the
+ *  handoff swaps image blocks for descriptions. */
+const AWARE_PROMPT_NOTE = `# Image reading (pi-vision-handoff active)
+
+This model lacks native image input, but the pi-vision-handoff extension is enabled: when you call the read tool on an image file, a configured vision model ({visionModel}) describes it and the description is injected as text in the tool result. You CAN read and act on images via the read tool — do not refuse image-reading requests or claim you cannot see images. The "[Current model does not support images…]" note in tool output is stale and is stripped by the extension.`;
+
 /** Most recent describer failure message (auth error, network error, abort,
  *  empty response, etc.). Set by the describer via the loader deps; surfaced
  *  to the user by the `context`/`tool_result` handler via ctx.ui.notify so a
@@ -422,6 +435,23 @@ export default function (pi: ExtensionAPI) {
     if (!isConfigured(config)) return;
     if (!isHandoffTarget(ctx.model, config)) return;
 
+    // Opt-in (`awarePrompt`): note telling text-only handoff targets they CAN
+    // read images via the read tool, since the handoff swaps image blocks for
+    // descriptions — some models otherwise refuse image-reading requests from
+    // self-knowledge even though the description is delivered as text. Must
+    // live in THIS single registration: only one before_agent_start result is
+    // used, and a second registration shadows this handler's fallback
+    // bootstrap (regression: the async pasted-path fallback never fired).
+    const awareSystemPrompt =
+      config.awarePrompt &&
+      config.visionModel &&
+      typeof event.systemPrompt === "string" &&
+      !event.systemPrompt.includes(AWARE_PROMPT_MARKER)
+        ? event.systemPrompt +
+          "\n\n" +
+          AWARE_PROMPT_NOTE.replace("{visionModel}", config.visionModel)
+        : undefined;
+
     // Fresh turn → fresh turn-abort controller. `before_agent_start` fires
     // BEFORE the agent run starts, so `ctx.signal` is undefined here (the run's
     // abort signal doesn't exist yet — it's created in `agent.prompt()` →
@@ -510,6 +540,10 @@ export default function (pi: ExtensionAPI) {
       // original fire-and-forget submit-time prewarm behavior.
       for (const prepared of preparedClipboardImages) prepared.catch(() => {});
     }
+
+    // Aware-prompt note (computed above): only the system prompt is overridden;
+    // the prewarm/fallback side effects above run either way.
+    return awareSystemPrompt !== undefined ? { systemPrompt: awareSystemPrompt } : undefined;
   });
 
   // A direct read and a nested pi.read both emit a read tool_call. If it targets
@@ -658,6 +692,37 @@ export default function (pi: ExtensionAPI) {
         }
       }
     }
+
+    // PERSISTENCE (opt-in, `persistDescriptions`): append a
+    // `[Image described: <hash>]` marker + description text block after each
+    // image block, so the session file carries the description next to the
+    // blob (which stays for kitty inline rendering). On `/resume` — new
+    // process, in-memory cache empty — the `context` hook matches the marker
+    // to the blob by hash and reuses the persisted description, skipping the
+    // vision call entirely (no 30-40s re-describe on every resumed turn).
+    // Only real descriptions are persisted (UNAVAILABLE is a transient
+    // failure, not a description worth replaying — next turn re-attempts).
+    // `imgs`/`descs` are aligned in content order, so walking `next` and
+    // consuming one desc per image block pairs them correctly.
+    if (config.persistDescriptions && hasImageBlock) {
+      const withPersisted: (TextContent | ImageContent)[] = [];
+      let imgIndex = 0;
+      for (const block of next) {
+        withPersisted.push(block);
+        const img = extractImageFromBlock(block);
+        if (img && imgIndex < descs.length) {
+          const desc = descs[imgIndex];
+          if (desc && desc !== UNAVAILABLE) {
+            withPersisted.push({
+              type: "text",
+              text: buildPersistedDescriptionBlock(imageHash(img.mimeType, img.data), desc),
+            });
+          }
+          imgIndex++;
+        }
+      }
+      return { content: withPersisted };
+    }
     if (stripped) return { content: next as (TextContent | ImageContent)[] };
   });
 
@@ -673,12 +738,43 @@ export default function (pi: ExtensionAPI) {
   // replaced them), so this is usually a no-op for the common paste-and-read
   // flow. For the images it does find, `loadDescription()` is a cache hit
   // (warmed by `before_agent_start`) or queues into the loader's current batch.
+  //
+  // PERSISTENCE (opt-in `persistDescriptions`): when the session was persisted
+  // on, a read tool result carries a `[Image described: <hash>]` marker +
+  // description block right next to the blob. On `/resume` (new process, empty
+  // in-memory cache) this hook matches the marker to the blob by hash, reuses
+  // the persisted description, drops the blob from the LLM-bound clone and
+  // strips the marker — NO vision call, no wait. Only images WITHOUT a
+  // persisted description fall through to `loadDescription()`.
   pi.on("context", async (event, ctx) => {
     if (!isConfigured(config)) return;
 
     const messages = event.messages as unknown as Array<Record<string, unknown>>;
     if (!Array.isArray(messages)) return;
 
+    // Persisted descriptions recovered from the session file (markers written
+    // by the read-tool `tool_result` handler when persistDescriptions was on).
+    // Matched by image hash; a UNAVAILABLE persisted body is ignored so a
+    // recorded failure still falls back to a fresh vision call (requirement:
+    // absent-or-failed persisted description → current behavior).
+    const persisted = new Map<string, string>();
+    for (const msg of messages) {
+      const content = msg.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (!block || typeof block !== "object") continue;
+        const b = block as { type?: unknown; text?: unknown };
+        if (b.type !== "text" || typeof b.text !== "string") continue;
+        const parsed = parsePersistedDescriptionBlock(b.text);
+        if (parsed && parsed.description !== UNAVAILABLE && !persisted.has(parsed.hash)) {
+          persisted.set(parsed.hash, parsed.description);
+        }
+      }
+    }
+
+    // Collect image blocks NOT covered by a persisted description. Only these
+    // may need the vision model (cache hits resolve instantly; covered images
+    // never trigger a vision call — the resume fast-path).
     const byHash = new Map<string, ExtractedImage>();
     let anyImage = false;
     for (const msg of messages) {
@@ -688,30 +784,40 @@ export default function (pi: ExtensionAPI) {
         const img = extractImageFromBlock(block);
         if (!img) continue;
         anyImage = true;
-        byHash.set(imageHash(img.mimeType, img.data), img);
+        const hash = imageHash(img.mimeType, img.data);
+        if (!persisted.has(hash)) byHash.set(hash, img);
       }
     }
     if (!anyImage) return;
     if (!isHandoffTarget(ctx.model, config)) return;
     const loader = await getLoader();
     loader.bindTurnContext(ctx);
-    if (!isAnyVisionModelResolvable(ctx.modelRegistry, config)) {
-      notifyUnresolvedVisionModel(ctx, config.visionModel!);
-      return;
-    }
+
+    // Seed the in-memory cache with the persisted descriptions so a later
+    // re-read of the same image (same hash) in this resumed session is a
+    // cache hit too, not a re-describe.
+    for (const [hash, desc] of persisted) loader.seedDescription(hash, desc);
 
     // Cache hits (warmed by before_agent_start / tool_result) resolve
     // instantly; any remaining misses queue into the loader's current batch.
+    // An all-persisted payload skips this block entirely: no vision call,
+    // no wait.
     const imgs = [...byHash.values()];
-    const descArr = await Promise.all(imgs.map((img) => loader.loadDescription(img)));
     const descs = new Map<string, string>();
-    for (let i = 0; i < imgs.length; i++) {
-      descs.set(imageHash(imgs[i].mimeType, imgs[i].data), descArr[i]);
-    }
-
-    if (ctx.signal?.aborted) return;
+    if (imgs.length > 0) {
+      if (!isAnyVisionModelResolvable(ctx.modelRegistry, config)) {
+        notifyUnresolvedVisionModel(ctx, config.visionModel!);
+        return;
+      }
+      const descArr = await Promise.all(imgs.map((img) => loader.loadDescription(img)));
+      if (ctx.signal?.aborted) return;
 
-    warnFailedImages(ctx, imgs, descArr, lastDescriberError ?? "unknown error");
+      warnFailedImages(ctx, imgs, descArr, lastDescriberError ?? "unknown error");
+      for (let i = 0; i < imgs.length; i++) {
+        descs.set(imageHash(imgs[i].mimeType, imgs[i].data), descArr[i]);
+      }
+    }
+    for (const [hash, desc] of persisted) descs.set(hash, desc);
 
     let changed = false;
     for (const msg of messages) {
@@ -722,12 +828,35 @@ export default function (pi: ExtensionAPI) {
       for (const block of content) {
         const img = extractImageFromBlock(block);
         if (img) {
-          next.push({ type: "text", text: descs.get(imageHash(img.mimeType, img.data)) ?? UNAVAILABLE });
-          touched = true;
+          const hash = imageHash(img.mimeType, img.data);
+          if (persisted.has(hash)) {
+            // Already described in this content: the persisted marker + text
+            // block is right there (marker stripped below) — drop the blob so
+            // the model receives the description exactly once.
+            touched = true;
+          } else {
+            next.push({ type: "text", text: descs.get(hash) ?? UNAVAILABLE });
+            touched = true;
+          }
         } else {
           next.push(block);
         }
       }
+      // Strip `[Image described: <hash>]` markers from persisted text blocks on
+      // the clone, so the model sees only the description itself.
+      for (let i = 0; i < next.length; i++) {
+        const block = next[i];
+        if (block && typeof block === "object" && (block as { type?: unknown }).type === "text") {
+          const text = (block as { text?: unknown }).text;
+          if (typeof text === "string") {
+            const stripped = stripPersistedMarker(text);
+            if (stripped !== text) {
+              next[i] = { type: "text", text: stripped };
+              touched = true;
+            }
+          }
+        }
+      }
       if (touched) {
         msg.content = next;
         changed = true;
@@ -753,7 +882,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("vision-handoff", {
     description: HANDOFF_COMMAND_DESCRIPTION,
     getArgumentCompletions(prefix: string) {
-      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "thinking", "prewarm", "fallback", "add", "remove", "clear", "help"];
+      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "thinking", "prewarm", "fallback", "aware", "persist", "add", "remove", "clear", "help"];
       const matches = subcommands.filter((s) => s.startsWith(prefix));
       return matches.length > 0 ? matches.map((s) => ({ value: s, label: s })) : null;
     },
@@ -791,6 +920,10 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
         "                               Toggle describing pasted images at paste-time (opt-in, off by default)",
         "  /vision-handoff fallback <on|off>",
         "                               Inject pasted-image descriptions asynchronously when no matching read wins",
+        "  /vision-handoff aware <on|off>",
+        "                               Tell handoff targets they can read images via the read tool (opt-in, off by default)",
+        "  /vision-handoff persist <on|off>",
+        "                               Persist descriptions to the session file (resume reuses them, no new vision call)",
         "  /vision-handoff add <p/id>     Force handoff for an extra model",
         "  /vision-handoff remove <p/id>  Stop forcing handoff for a model",
         "  /vision-handoff clear          Clear the configured vision model",
@@ -853,6 +986,16 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
     return;
   }
 
+  if (subcommand === "aware") {
+    handleAwareSubcommand(ctx, rest);
+    return;
+  }
+
+  if (subcommand === "persist") {
+    handlePersistSubcommand(ctx, rest);
+    return;
+  }
+
   if (subcommand === "clear") {
     updateConfig(
       ctx,
@@ -1028,6 +1171,60 @@ function handleFallbackSubcommand(ctx: ExtensionCommandContext, rest: string): v
   );
 }
 
+/** Handle /vision-handoff aware <on|off>. */
+function handleAwareSubcommand(ctx: ExtensionCommandContext, rest: string): void {
+  const value = rest.trim().toLowerCase();
+  if (!value) {
+    ctx.ui.notify(
+      `Aware prompt: ${config.awarePrompt ? "on" : "off"}.\n` +
+        "Usage: /vision-handoff aware <on|off>",
+      "info",
+    );
+    return;
+  }
+  if (value !== "on" && value !== "off") {
+    ctx.ui.notify("Usage: /vision-handoff aware <on|off>", "warning");
+    return;
+  }
+  const on = value === "on";
+  updateConfig(
+    ctx,
+    (c) => ({ ...c, awarePrompt: on }),
+    on
+      ? "Aware prompt on — handoff targets are told they can read images via the read tool."
+      : "Aware prompt off.",
+  );
+}
+
+/** Handle /vision-handoff persist <on|off> — toggle persisting descriptions
+ *  to the session file. When on, generated descriptions are written as
+ *  `[Image described: <hash>]` marker + text blocks in the read tool-result
+ *  content; on `/resume` the `context` hook reuses them by hash, skipping the
+ *  vision call entirely (no 30-40s re-describe latency). */
+function handlePersistSubcommand(ctx: ExtensionCommandContext, rest: string): void {
+  const value = rest.trim().toLowerCase();
+  if (!value) {
+    ctx.ui.notify(
+      `Persist descriptions to the session file: ${config.persistDescriptions ? "on" : "off"}.\n` +
+        "Usage: /vision-handoff persist <on|off>",
+      "info",
+    );
+    return;
+  }
+  if (value !== "on" && value !== "off") {
+    ctx.ui.notify("Usage: /vision-handoff persist <on|off>", "warning");
+    return;
+  }
+  const on = value === "on";
+  updateConfig(
+    ctx,
+    (c) => ({ ...c, persistDescriptions: on }),
+    on
+      ? "Persist descriptions on — generated descriptions are saved to the session file; resumed sessions reuse them without a new vision call."
+      : "Persist descriptions off — descriptions are generated per-session as before.",
+  );
+}
+
 async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
   if (!ctx.hasUI) {
     ctx.ui.notify("/vision-handoff requires interactive mode.", "error");
@@ -1122,6 +1319,8 @@ function showStatus(ctx: ExtensionCommandContext): void {
   lines.push(`Thinking: ${config.thinking ? `on (${config.thinkingLevel})` : "off"}`);
   lines.push(`Paste-time prewarm: ${config.prewarmPastedImages ? `on${editorInstalled ? "" : " (inactive — another custom editor is active)"}` : "off"}`);
   lines.push(`Async pasted-path fallback: ${config.asyncClipboardHandoff ? "on" : "off"}`);
+  lines.push(`Aware prompt: ${config.awarePrompt ? "on" : "off"}`);
+  lines.push(`Persist descriptions (session file): ${config.persistDescriptions ? "on" : "off"}`);
   lines.push(`maxTokens: ${config.maxTokens ?? "unbounded"} · cacheMax: ${config.cacheMax} · maxDescriptionLines: ${config.maxDescriptionLines === 0 ? "unbounded" : config.maxDescriptionLines}`);
 
   const model = ctx.model;