pi-vision-handoff 0.3.2 → 0.4.1

package/README.md

@@ -10,6 +10,8 @@ _Describe images with a vision model you pick, then feed the text to models that
 [![npm](https://img.shields.io/npm/v/pi-vision-handoff)](https://www.npmjs.com/package/pi-vision-handoff)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
+<img src="https://raw.githubusercontent.com/monotykamary/pi-vision-handoff/main/assets/vision-handoff.jpg" alt="Vision Handoff picker — an interactive TUI listing every model, vision-capable ones marked with an eye, to choose the describer for text-only models" width="820">
+
 </div>
 
 ---
@@ -35,7 +37,7 @@ No `settings.json` touched. No per-provider glue. Pick a describer once and ever
 ## Features
 
 - **🎮 Interactive picker** — `/vision-handoff` opens a TUI listing every model, vision-capable ones first (👁), to choose your describer.
-- **🖼️ DataLoader-batched descriptions** — the `read` tools are `load()` callers: N parallel reads coalesce into ONE batched vision call (dispatched after the microtask cascade settles), awaited during the tool-result phase (free time) so the agent's next turn never blocks on the describer. Descriptions are ready before `context` fires, so the swap is a non-blocking cache hit.
+- **🖼️ DataLoader-batched descriptions** — the `read` tools are `load()` callers: N parallel reads coalesce into ONE batched vision call (dispatched via `setImmediate` after the poll phase, so reads completing together batch instead of splitting), awaited during the tool-result phase (free time) so the agent's next turn never blocks on the describer. Descriptions are ready before `context` fires, so the swap is a non-blocking cache hit.
 - **🧹 Hides pi's "model does not support images" note** — on read results the extension strips pi's `[Current model does not support images…]` note from the text block (it's misleading once the handoff delivers the image's content as text), while keeping the image block for kitty inline rendering and `/resume`.
 - **🔌 Provider-agnostic** — uses pi's own model execution machinery (`@earendil-works/pi-ai`'s `complete()`), so it works with any provider/configured model, including custom provider extensions.
 - **🧠 Automatic targets** — by default, handoff applies to *every* model that lacks native vision. Opt out with `/vision-handoff auto off`.
@@ -137,7 +139,8 @@ pi -e ./vision-handoff.ts
 The extension implements the **Facebook DataLoader pattern** for image
 descriptions. The `read` tools are the `load()` callers; a per-image cache
 memoizes promises; all `load()` calls in the same execution frame coalesce
-into ONE batched vision call, dispatched after the microtask cascade settles.
+into ONE batched vision call, dispatched via `setImmediate` after the poll
+phase (so reads completing together batch instead of splitting into N calls).
 
     → before_agent_start
         • captures this turn's user prompt (shared by every image description)
@@ -160,10 +163,12 @@ into ONE batched vision call, dispatched after the microtask cascade settles.
         • pi runs `read` calls in parallel (Promise.all); each read's
           tool_result handler calls `loadDescription(img)` for its image
           blocks and AWAITS the shared batch
-        • DataLoader: all `load()` calls in the same microtask frame land in
-          ONE batch → ONE `complete()` vision call for the whole read set
-          (dispatched after the microtask cascade via enqueuePostPromiseJob:
-          `Promise.resolve().then(() => process.nextTick(dispatch))`)
+        • DataLoader: all `load()` calls in one event-loop poll iteration
+          land in ONE batch → ONE `complete()` vision call for the whole read
+          set. `enqueuePostPromiseJob` schedules dispatch via `setImmediate`
+          (the check phase, which runs AFTER the whole poll phase — not
+          `process.nextTick`, which would drain between the reads' I/O
+          callbacks and split them into N single-image calls)
         • awaits the shared batch — runs the describer during the tool-result
           phase (free time: the agent is just waiting for tool results), so
           the batch is COMPLETE before `context` fires → `context` is a
@@ -191,24 +196,35 @@ A single frame's image set is described with **one** vision-model call, not
 one per image. `loadDescription(img)` is synchronous: on a cache miss it
 pushes the image's key (hash) into the current batch and returns a memoized
 promise; on a cache hit it returns the existing (in-flight or resolved)
-promise. `enqueuePostPromiseJob` schedules dispatch after the microtask
-cascade settles, so every `load()` caller in the frame registers its key
-before the single vision call fires — exactly DataLoader's `getCurrentBatch`
-+ `enqueuePostPromiseJob`. The batched call sends every uncached image in a
-single user message with per-image `<<<IMAGE k>>> … <<<END>>>` delimiters; the
-response is parsed back into per-image descriptions (keyed by
-`sha256(mime + base64)` in the per-image cache). If the vision model ignores
-the delimiter format and the batched response can't be split, each unparsed
-image falls back to its own single-image `complete()` call **in parallel**
-(no delimiters to cooperate with) — descriptions still arrive together. Only
-when a per-image call itself genuinely fails (auth, timeout, empty) does that
-image degrade to `[Image: description unavailable]`; one bad image never
-voids the rest.
-
-Because pi runs parallel `read` tool calls via `Promise.all` and fires the
-`tool_result` event inside that `Promise.all` (via `agent.afterToolCall` →
-`finalizeExecutedToolCall`), N parallel reads' `load()` calls share ONE
-microtask frame → ONE batch → ONE vision call, all resolving together.
+promise. `enqueuePostPromiseJob` schedules dispatch via `setImmediate` (the
+check phase, after the whole poll phase AND after the microtask queue
+drains), so every `load()` caller — whether from sync code, a `.then`
+cascade, or a separate I/O callback in the same poll iteration — registers
+its key before the single vision call fires. This is why N parallel reads
+coalesce into one call rather than splitting into N single-image calls:
+`setImmediate` defers past the entire poll phase, whereas DataLoader's
+classic `process.nextTick` would drain between the reads' I/O callbacks and
+fire a dispatch after the first read but before the second. The batched call
+sends every uncached image in a single user message with per-image
+`<<<IMAGE k>>> … <<<END>>>` delimiters; the response is parsed back into
+per-image descriptions (keyed by `sha256(mime + base64)` in the per-image
+cache). If the vision model ignores the delimiter format and the batched
+response can't be split, each unparsed image falls back to its own
+single-image `complete()` call **in parallel** (no delimiters to cooperate
+with) — descriptions still arrive together. Only when a per-image call
+itself genuinely fails (auth, timeout, empty) does that image degrade to
+`[Image: description unavailable]`; one bad image never voids the rest.
+
+Because pi runs parallel `read` tool calls via `Promise.all` and fires
+each read's `tool_result` event as that read's I/O completes (poll phase) —
+via `agent.afterToolCall` → `finalizeExecutedToolCall` — the loader's
+`setImmediate` dispatch defers to the check phase AFTER the whole poll
+iteration, so reads completing together share ONE batch → ONE vision call,
+all resolving together. Reads completing in separate poll iterations get
+separate calls, but always in parallel, never sequential. (The per-image
+cache also dedupes a duplicate `load()` of the same image in one frame:
+dispatch resolves every callback by hash, so a second load whose first cache
+entry was evicted mid-frame still resolves — it never hangs.)
 
 **Failures are never cached.**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vision-handoff",
-  "version": "0.3.2",
+  "version": "0.4.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",

package/src/dataloader.ts

@@ -4,19 +4,23 @@
  * `loadDescription(img)` returns a memoized Promise for the description and
  * pushes the image's key (hash) into the CURRENT batch. All `load()` calls in
  * the same execution frame (+ its microtask cascade) coalesce into ONE batch
- * object. Dispatch is scheduled after the microtask queue settles (via
- * `enqueuePostPromiseJob`), so every load in the frame lands in the single
- * batch before the ONE vision call fires. Each load()'s promise then resolves
- * with its description.
+ * object. Dispatch is scheduled via `setImmediate` (see `enqueuePostPromiseJob`),
+ * so every load in the frame — and every load from a separate I/O callback in
+ * the same poll iteration — lands in the single batch before the ONE vision
+ * call fires. Each load()'s promise then resolves with its description.
  *
  * Mapping: the `read` tools are the `load()` callers. Their `tool_result`
- * handler awaits the shared batch — so N parallel reads (pi runs `read` via
- * `Promise.all`) block on the SAME single vision call and all resolve together,
- * the descriptions landing in the tool results BEFORE the agent's next turn.
- * The agent's tool-result wait is free time, so this adds zero latency to the
- * critical path. `context` then sees text-described tool results (no image
- * blocks to swap); any remaining images (user-attached, custom-injected) are
- * cache hits.
+ * handler awaits the shared batch — so N parallel reads coalesce into the SAME
+ * single vision call and all resolve together, the descriptions landing in the
+ * tool results BEFORE the agent's next turn. pi fires each read's `tool_result`
+ * as that read's I/O completes (poll phase); the loader's `setImmediate`
+ * dispatch defers to the check phase, AFTER the whole poll iteration, so reads
+ * completing together (the common case for cached local files) land in ONE
+ * batch — and reads completing in separate iterations get separate calls, but
+ * always in parallel, never sequential. The agent's tool-result wait is free
+ * time, so this adds zero latency to the critical path. `context` then sees
+ * text-described tool results (no image blocks to swap); any remaining images
+ * (user-attached, custom-injected) are cache hits.
  *
  * All mutable state (batch, cache, turn context) lives on the instance — no
  * module-level globals — and the class implements `Disposable` so a `using`
@@ -43,7 +47,12 @@ export const UNAVAILABLE = `${IMAGE_PLACEHOLDER_PREFIX}description unavailable${
 interface DescriptionBatch {
   keys: string[];
   imgs: ExtractedImage[];
-  callbacks: { resolve: (v: string) => void; reject: (e: Error) => void }[];
+  /** One per `loadDescription()` call. A duplicate load (same hash, but its
+   *  first cache entry was evicted mid-frame so it couldn't short-circuit on
+   *  the cache) pushes a second callback for an existing key — so
+   *  `callbacks.length` can exceed `keys.length`. `dispatchBatch` resolves by
+   *  hash so every callback is reached. */
+  callbacks: { hash: string; resolve: (v: string) => void; reject: (e: Error) => void }[];
 }
 
 /** Engine-provided resolver for the configured vision model. */
@@ -59,16 +68,21 @@ export interface LoaderDeps extends DescriberDeps {
   resolveVisionModel: VisionModelResolver;
 }
 
-const resolvedMicrotask = Promise.resolve();
-
-/** Defer `fn` until after the current microtask cascade settles, so every
- *  `loadDescription()` in the same frame coalesces into one batch before the
- *  single vision call fires. Mirrors DataLoader's enqueuePostPromiseJob: a
- *  Promise Job enqueues a global Job (process.nextTick), guaranteeing dispatch
- *  runs after "PromiseJobs" ends — after all `load()` callers in the frame
- *  have registered their keys. */
+/** Defer `fn` to the next check phase (`setImmediate`), so every
+ *  `loadDescription()` — whether called from sync code, a microtask cascade,
+ *  or a separate I/O callback in the same poll iteration — coalesces into one
+ *  batch before the single vision call fires.
+ *
+ *  Why `setImmediate` and not DataLoader's classic `process.nextTick`:
+ *  nextTick drains between I/O callbacks in the poll phase, so dispatch would
+ *  fire after the first parallel `read`'s `tool_result` but before the
+ *  second's — splitting N reads into N single-image calls. `setImmediate` runs
+ *  in the check phase, AFTER the whole poll phase, so all `tool_result`
+ *  handlers that fire in one poll iteration land in ONE batch. The check phase
+ *  also runs after the microtask queue drains, so loads issued from a `.then`
+ *  cascade (e.g. the clipboard pre-warm) still coalesce. */
 function enqueuePostPromiseJob(fn: () => void): void {
-  resolvedMicrotask.then(() => process.nextTick(fn));
+  setImmediate(fn);
 }
 
 export class DescriptionLoader implements Disposable {
@@ -119,12 +133,14 @@ export class DescriptionLoader implements Disposable {
       batch.imgs.push(img);
       idx = batch.keys.length - 1;
     } else {
-      // Same image loaded twice in the frame — share one cache slot, but give
-      // this caller its own promise.
+      // Same image loaded twice in the frame (the first load's cache entry was
+      // evicted mid-frame, else the second load would have short-circuited on
+      // the cache). Share the one key/image slot but give this caller its own
+      // promise — dispatch resolves it by hash alongside the first caller's.
       batch.imgs[idx] = img;
     }
     const promise = new Promise<string>((resolve, reject) => {
-      batch.callbacks.push({ resolve, reject });
+      batch.callbacks.push({ hash, resolve, reject });
     });
     const cfg = this.deps.getConfig();
     if (this.cache.size >= cfg.cacheMax) {
@@ -161,7 +177,14 @@ export class DescriptionLoader implements Disposable {
   /** Dispatch the current batch: ONE batched `runBatch` vision call for every
    *  key collected this frame, then resolve each load()'s promise with its
    *  description (or {@link UNAVAILABLE} on failure). Failures are evicted from
-   *  the cache so the next turn re-attempts. */
+   *  the cache so the next turn re-attempts.
+   *
+   *  Results are resolved BY HASH and fanned out to EVERY callback: a batch can
+   *  hold more callbacks than keys when the same image was loaded twice in one
+   *  frame (its first cache entry was evicted mid-frame, so the second load
+   *  pushed a second callback for the same hash). Indexing callbacks by key
+   *  would skip those duplicates and hang their promises; iterating callbacks
+   *  and looking up each one's hash fans the one result to all of them. */
   private async dispatchBatch(): Promise<void> {
     this.dispatchScheduled = false;
     const batch = this.batch;
@@ -172,10 +195,8 @@ export class DescriptionLoader implements Disposable {
       return;
     }
     if (this.turnSignal?.aborted) {
-      for (let i = 0; i < batch.keys.length; i++) {
-        this.cache.delete(batch.keys[i]);
-        batch.callbacks[i].resolve(UNAVAILABLE);
-      }
+      for (const key of batch.keys) this.cache.delete(key);
+      for (const cb of batch.callbacks) cb.resolve(UNAVAILABLE);
       return;
     }
     this.deps.setLastError(null); // clear before a fresh attempt
@@ -190,19 +211,27 @@ export class DescriptionLoader implements Disposable {
       this.deps,
       this.turnSignal,
     );
+    // Build per-hash results, then fan them out to every callback. This reaches
+    // duplicate-hash callbacks that a key-indexed loop would have skipped (and
+    // left hanging).
+    const results = new Map<string, string>();
     for (let i = 0; i < batch.keys.length; i++) {
-      const raw = parsed.get(batch.keys[i]);
+      const key = batch.keys[i];
+      const raw = parsed.get(key);
       if (raw) {
         const final = wrapDescription(raw, cfg);
-        this.cache.set(batch.keys[i], Promise.resolve(final));
-        batch.callbacks[i].resolve(final);
+        results.set(key, final);
+        // Cache the resolved value so later loads (this frame or next) hit.
+        this.cache.set(key, Promise.resolve(final));
       } else {
         // Genuine failure — do NOT cache; next turn re-attempts (and surfaces
         // the real error). Resolve (not reject) with UNAVAILABLE to match the
         // graceful-degradation contract and avoid unhandled rejections.
-        this.cache.delete(batch.keys[i]);
-        batch.callbacks[i].resolve(UNAVAILABLE);
+        this.cache.delete(key);
       }
     }
+    for (const cb of batch.callbacks) {
+      cb.resolve(results.get(cb.hash) ?? UNAVAILABLE);
+    }
   }
 }

package/src/describer.ts

@@ -18,7 +18,7 @@
  * abort listener.
  */
 
-import type { Api, ImageContent, Message, Model, TextContent } from "@earendil-works/pi-ai";
+import type { Api, ImageContent, Message, Model, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
 import { complete } from "@earendil-works/pi-ai/compat";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import {
@@ -76,6 +76,26 @@ export function resolveMaxTokens(
   return Math.max(1, Math.min(requested, cap));
 }
 
+/** Resolve the `reasoning` (thinking) level to pass to `complete()`, or
+ *  `undefined` to leave thinking off.
+ *
+ *  - Returns `undefined` when thinking is disabled in config.
+ *  - Returns `undefined` when the vision model doesn't declare reasoning
+ *    support (`model.reasoning === false`) — sending a `reasoning` level to a
+ *    non-reasoning model would be ignored at best and rejected at worst.
+ *  - Otherwise returns the configured {@link VisionHandoffConfig.thinkingLevel}.
+ *
+ *  Mirrors pi core's `createSummarizationOptions` guard so the describer's
+ *  thinking behaviour matches the rest of pi. */
+export function resolveReasoning(
+  cfg: VisionHandoffConfig,
+  visionModel: Model<Api>,
+): ThinkingLevel | undefined {
+  if (!cfg.thinking) return undefined;
+  if (!visionModel.reasoning) return undefined;
+  return cfg.thinkingLevel;
+}
+
 /** Dependencies the describer can't own itself (held by the engine). */
 export interface DescriberDeps {
   /** Report a usage+energy record for one real describer call (cache hits emit none). */
@@ -126,6 +146,7 @@ export async function runBatch(
 
   const timeoutMs = describeTimeoutMs(misses.length);
   const maxTokens = resolveMaxTokens(cfg, visionModel);
+  const reasoning = resolveReasoning(cfg, visionModel);
   const controller = new AbortController();
   let timedOut = false;
   using fetchGuard = fetchInterceptorGuard();
@@ -141,7 +162,7 @@ export async function runBatch(
       complete(
         visionModel,
         { systemPrompt, messages: [userMessage] },
-        { apiKey: auth.apiKey, headers: auth.headers, signal: controller.signal, maxTokens },
+        { apiKey: auth.apiKey, headers: auth.headers, signal: controller.signal, maxTokens, reasoning },
       ),
     );
     const capture = await readCapture(describeCtx);
@@ -239,6 +260,7 @@ export async function describeSingle(
   const userMessage: Message = { role: "user", content, timestamp: Date.now() };
   const timeoutMs = describeTimeoutMs(1);
   const maxTokens = resolveMaxTokens(cfg, visionModel);
+  const reasoning = resolveReasoning(cfg, visionModel);
   const controller = new AbortController();
   let timedOut = false;
   using fetchGuard = fetchInterceptorGuard();
@@ -254,7 +276,7 @@ export async function describeSingle(
       complete(
         visionModel,
         { systemPrompt, messages: [userMessage] },
-        { apiKey: auth.apiKey, headers: auth.headers, signal: controller.signal, maxTokens },
+        { apiKey: auth.apiKey, headers: auth.headers, signal: controller.signal, maxTokens, reasoning },
       ),
     );
     const capture = await readCapture(describeCtx);

package/src/index.ts

@@ -5,7 +5,7 @@
  * convention pi-model-sort uses for picker-backed extensions.
  */
 
-import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { ImageContent, TextContent, ThinkingLevel } from "@earendil-works/pi-ai";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -57,6 +57,26 @@ export function markDescriptionTruncated(text: string): string {
 /** Default vision cache size (number of described images kept in memory per session). */
 export const DEFAULT_CACHE_MAX = 50;
 
+/** The pi thinking levels, ordered from lightest to deepest reasoning.
+ *  Mirrors `@earendil-works/pi-ai`'s `ThinkingLevel`; "off" is handled
+ *  separately via {@link VisionHandoffConfig.thinking} (a boolean on/off
+ *  switch) so the level persists across toggles. */
+export const THINKING_LEVELS: readonly ThinkingLevel[] = [
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+];
+
+/** Default thinking effort for the vision describer when thinking is enabled. */
+export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium";
+
+/** Whether `level` is one of the supported {@link ThinkingLevel} values. */
+export function isThinkingLevel(level: unknown): level is ThinkingLevel {
+  return typeof level === "string" && (THINKING_LEVELS as readonly string[]).includes(level);
+}
+
 /** Per-description request timeout. Generous because the describer generates an
  *  exhaustive multi-paragraph description per image; a single image commonly
  *  takes ~20s, and a batched call over websocket transport scales with image
@@ -135,6 +155,16 @@ export interface VisionHandoffConfig {
   prompt?: string;
   /** Override the user-prompt prefix (defaults to DEFAULT_USER_PROMPT_PREFIX). */
   userPromptPrefix?: string;
+  /** 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
+   *  to the vision model via pi-ai's `reasoning` option (only honoured when
+   *  the configured vision model declares `reasoning: true`). */
+  thinking: boolean;
+  /** Thinking effort for the describer when {@link thinking} is on. One of
+   *  {@link THINKING_LEVELS}. Ignored when {@link thinking} is off or the
+   *  vision model lacks reasoning support. */
+  thinkingLevel: ThinkingLevel;
 }
 
 export const DEFAULT_CONFIG: VisionHandoffConfig = {
@@ -145,6 +175,8 @@ export const DEFAULT_CONFIG: VisionHandoffConfig = {
   maxTokens: undefined,
   cacheMax: DEFAULT_CACHE_MAX,
   maxDescriptionLines: DEFAULT_MAX_DESCRIPTION_LINES,
+  thinking: false,
+  thinkingLevel: DEFAULT_THINKING_LEVEL,
 };
 
 /** Parse a "provider/id" reference. Returns null if malformed. */
@@ -208,6 +240,9 @@ export function normalizeConfig(raw: unknown): VisionHandoffConfig {
   if (typeof obj.prompt === "string" && obj.prompt.trim()) base.prompt = obj.prompt;
   if (typeof obj.userPromptPrefix === "string") base.userPromptPrefix = obj.userPromptPrefix;
 
+  if (typeof obj.thinking === "boolean") base.thinking = obj.thinking;
+  if (isThinkingLevel(obj.thinkingLevel)) base.thinkingLevel = obj.thinkingLevel;
+
   return base;
 }
 

package/src/vision-model-selector.ts

@@ -23,8 +23,9 @@ import {
   Text,
 } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ThinkingLevel } from "@earendil-works/pi-ai";
 import { DynamicBorder, keyText } from "@earendil-works/pi-coding-agent";
-import { formatModelRef, isVisionModel } from "./index.js";
+import { formatModelRef, isVisionModel, THINKING_LEVELS } from "./index.js";
 
 interface DisplayItem {
   /** "provider/id", or null for the synthetic "None" row. */
@@ -33,6 +34,8 @@ interface DisplayItem {
   modelId: string;
   modelName: string;
   vision: boolean;
+  /** Whether the model declares reasoning (thinking) support. */
+  reasoning: boolean;
   none?: boolean;
 }
 
@@ -41,6 +44,10 @@ export interface VisionModelSelectorResult {
   ref: string | null;
   /** True if the user cancelled (esc) — config should not change. */
   cancelled: boolean;
+  /** Thinking on/off chosen in the picker. */
+  thinking: boolean;
+  /** Thinking effort chosen in the picker. */
+  thinkingLevel: ThinkingLevel;
 }
 
 export class VisionModelSelectorComponent implements Component {
@@ -56,6 +63,8 @@ export class VisionModelSelectorComponent implements Component {
   private footerText: Text;
 
   private currentRef: string | null;
+  private thinking: boolean;
+  private thinkingLevel: ThinkingLevel;
 
   private _focused = false;
   get focused(): boolean {
@@ -68,13 +77,23 @@ export class VisionModelSelectorComponent implements Component {
 
   constructor(
     theme: Theme,
-    allModels: Array<{ provider: string; id: string; name: string; input?: ("text" | "image")[] }>,
+    allModels: Array<{
+      provider: string;
+      id: string;
+      name: string;
+      input?: ("text" | "image")[];
+      reasoning?: boolean;
+    }>,
     currentRef: string | null,
+    currentThinking: boolean,
+    currentThinkingLevel: ThinkingLevel,
     done: (result: VisionModelSelectorResult) => void,
   ) {
     this.theme = theme;
     this.done = done;
     this.currentRef = currentRef;
+    this.thinking = currentThinking;
+    this.thinkingLevel = currentThinkingLevel;
     this.allItems = this.buildItems(allModels);
     this.filteredItems = this.allItems;
 
@@ -161,6 +180,22 @@ export class VisionModelSelectorComponent implements Component {
       return;
     }
 
+    // Thinking controls — reuse pi's own app.thinking.* keybindings so the
+    // hints and behaviour match the rest of pi: ctrl+t toggles thinking
+    // on/off, shift+tab cycles the effort level. Intercepted before the
+    // search input so they never get swallowed as filter text.
+    if (kb.matches(data, "app.thinking.toggle")) {
+      this.thinking = !this.thinking;
+      this.updateList();
+      return;
+    }
+
+    if (kb.matches(data, "app.thinking.cycle")) {
+      this.cycleThinkingLevel();
+      this.updateList();
+      return;
+    }
+
     this.searchInput.handleInput(data);
     this.refresh();
   }
@@ -174,7 +209,13 @@ export class VisionModelSelectorComponent implements Component {
   // Internal helpers
 
   private buildItems(
-    allModels: Array<{ provider: string; id: string; name: string; input?: ("text" | "image")[] }>,
+    allModels: Array<{
+      provider: string;
+      id: string;
+      name: string;
+      input?: ("text" | "image")[];
+      reasoning?: boolean;
+    }>,
   ): DisplayItem[] {
     const items: DisplayItem[] = [
       {
@@ -183,6 +224,7 @@ export class VisionModelSelectorComponent implements Component {
         modelId: "none",
         modelName: "None — disable vision handoff",
         vision: false,
+        reasoning: false,
         none: true,
       },
     ];
@@ -192,12 +234,14 @@ export class VisionModelSelectorComponent implements Component {
       id: string;
       name: string;
       input?: ("text" | "image")[];
+      reasoning?: boolean;
     }): DisplayItem => ({
       ref: formatModelRef(m.provider, m.id),
       provider: m.provider,
       modelId: m.id,
       modelName: m.name || m.id,
       vision: isVisionModel(m),
+      reasoning: !!m.reasoning,
     });
 
     // Vision-capable first (registry order), then the rest (registry order).
@@ -217,6 +261,8 @@ export class VisionModelSelectorComponent implements Component {
     const parts: string[] = [
       `${keyText("tui.select.confirm")} select`,
       `ctrl+s done`,
+      `${keyText("app.thinking.toggle")} thinking`,
+      `${keyText("app.thinking.cycle")} effort`,
       `esc cancel`,
       this.searchInput.getValue() ? `${this.filteredItems.length - 1} match` : `${totalCount} models · ${visionCount} vision`,
     ];
@@ -318,16 +364,52 @@ export class VisionModelSelectorComponent implements Component {
           ),
         );
       }
+      this.renderThinkingDetail(selected);
     }
 
     this.footerText.setText(this.getFooterText());
   }
 
+  /** Append the thinking on/off + effort line to the detail pane, with a
+   *  warning when the highlighted model can't reason (so the setting would
+   *  be silently ignored by the describer). */
+  private renderThinkingDetail(selected: DisplayItem): void {
+    const state = this.thinking
+      ? this.theme.fg("success", `on (${this.thinkingLevel})`)
+      : this.theme.fg("muted", "off");
+    this.listContainer.addChild(
+      new Text(this.theme.fg("dim", `  Thinking: ${state}`), 0, 0),
+    );
+    if (this.thinking && !selected.none && !selected.reasoning) {
+      this.listContainer.addChild(
+        new Text(
+          this.theme.fg(
+            "warning",
+            `  ⚠ ${selected.modelId} declares no reasoning — thinking will be ignored`,
+          ),
+          0, 0,
+        ),
+      );
+    }
+  }
+
   private confirm(item: DisplayItem): void {
-    this.done({ ref: item.ref, cancelled: false });
+    this.done({ ref: item.ref, cancelled: false, thinking: this.thinking, thinkingLevel: this.thinkingLevel });
   }
 
   private finish(cancelled: boolean): void {
-    this.done({ ref: null, cancelled });
+    this.done({ ref: null, cancelled, thinking: this.thinking, thinkingLevel: this.thinkingLevel });
+  }
+
+  /** Cycle the thinking effort forward through {@link THINKING_LEVELS},
+   *  wrapping from the last back to the first. Cycling implicitly turns
+   *  thinking on (you don't usually cycle a switch you want off) — matching
+   *  pi's own `app.thinking.cycle` behaviour, which is a no-op only when the
+   *  active model has no reasoning. */
+  private cycleThinkingLevel(): void {
+    if (!this.thinking) this.thinking = true;
+    const idx = THINKING_LEVELS.indexOf(this.thinkingLevel);
+    const next = THINKING_LEVELS[(idx + 1) % THINKING_LEVELS.length]!;
+    this.thinkingLevel = next;
   }
 }

package/vision-handoff.ts

@@ -33,6 +33,7 @@ import type { Api, ImageContent, Model, TextContent } from "@earendil-works/pi-a
 import {
   extractImageFromBlock,
   formatModelRef,
+  isThinkingLevel,
   isVisionModel,
   NON_VISION_IMAGE_NOTE,
   parseModelRef,
@@ -209,7 +210,8 @@ export default function (pi: ExtensionAPI) {
     //
     // Both sources flow through the same loader: `load()` is synchronous and
     // memoized, so all images in this frame (attached + clipboard-path)
-    // coalesce into ONE batch dispatched after the microtask cascade.
+    // coalesce into ONE batch dispatched via `setImmediate` after the
+    // microtask cascade settles.
     for (const image of event.images ?? []) {
       if (!image || image.type !== "image" || !image.data) continue;
       loader.loadDescription({ data: image.data, mimeType: image.mimeType || "image/png" }).catch(() => {});
@@ -243,12 +245,14 @@ export default function (pi: ExtensionAPI) {
   // When the agent reads image files, this fires for each read result. It
   // calls the loader's `loadDescription(img)` for every image block and
   // AWAITS the shared batch — so N parallel reads (pi runs `read` via
-  // Promise.all) coalesce into ONE batched vision call (DataLoader: all
-  // load() calls in the same microtask frame share one batch, dispatched
-  // after the cascade settles) and all resolve together. The descriptions
-  // replace the image blocks in the returned `content`, so by the time the
-  // agent's next turn starts the tool results already carry text — the
-  // agent never sees raw image blocks it can't process.
+  // Promise.all) coalesce into ONE batched vision call: pi fires each read's
+  // `tool_result` as its I/O completes (poll phase), and the loader's
+  // `setImmediate` dispatch defers to the check phase AFTER the whole poll
+  // iteration, so reads completing together land in ONE batch and all resolve
+  // together. The descriptions replace the image blocks in the returned
+  // `content`, so by the time the agent's next turn starts the tool results
+  // already carry text — the agent never sees raw image blocks it can't
+  // process.
   //
   // Why block here and not in `context`: the tool-result phase is free time
   // (the agent is just waiting for tool results), so running the describer
@@ -276,9 +280,13 @@ export default function (pi: ExtensionAPI) {
     }
 
     // load() each image — synchronous calls that push into the current batch
-    // and return memoized promises — then await them all. Parallel reads'
-    // load() calls land in the SAME batch (same microtask frame), so this is
-    // ONE vision call for the whole read set, not N. Awaiting here runs the
+    // and return memoized promises — then await them all. pi fires each read's
+    // `tool_result` event as that read's I/O completes (poll phase); the
+    // loader's `setImmediate` dispatch defers to the check phase, AFTER the
+    // whole poll iteration, so reads completing together (the common case for
+    // cached local files) land in ONE batch — ONE vision call for the whole
+    // read set, not N. Reads completing in separate iterations get separate
+    // calls, but always in parallel, never sequential. Awaiting here runs the
     // describer during the tool-result phase (free time — the agent is just
     // waiting for tool results), so the batch is COMPLETE before `context`
     // fires, making `context` a non-blocking cache hit instead of a cold miss
@@ -412,7 +420,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", "add", "remove", "clear", "help"];
+      const subcommands = ["select", "model", "status", "enable", "disable", "auto", "thinking", "add", "remove", "clear", "help"];
       const matches = subcommands.filter((s) => s.startsWith(prefix));
       return matches.length > 0 ? matches.map((s) => ({ value: s, label: s })) : null;
     },
@@ -444,6 +452,8 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
         "  /vision-handoff enable         Enable vision handoff",
         "  /vision-handoff disable        Disable vision handoff (keeps configured model)",
         "  /vision-handoff auto <on|off>  Toggle automatic handoff for all non-vision models",
+        "  /vision-handoff thinking <off|minimal|low|medium|high|xhigh>",
+        "                               Set the vision describer's thinking effort (off = disabled)",
         "  /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",
@@ -489,6 +499,11 @@ async function handleHandoffCommand(ctx: ExtensionCommandContext, args: string):
     return;
   }
 
+  if (subcommand === "thinking") {
+    handleThinkingSubcommand(ctx, rest);
+    return;
+  }
+
   if (subcommand === "clear") {
     updateConfig(
       ctx,
@@ -582,6 +597,38 @@ function updateConfig(
   ctx.ui.notify(`${message} (config: ${path})`, "info");
 }
 
+/** Resolve a `/vision-handoff thinking <level>` argument into a
+ *  `(thinking, thinkingLevel)` pair. `off` disables thinking; any of the
+ *  {@link THINKING_LEVELS} enables it at that effort. */
+function handleThinkingSubcommand(ctx: ExtensionCommandContext, rest: string): void {
+  const arg = rest.trim().toLowerCase();
+  if (!arg) {
+    ctx.ui.notify(
+      `Thinking: ${config.thinking ? `on (${config.thinkingLevel})` : "off"}.\n` +
+        `Usage: /vision-handoff thinking <off|minimal|low|medium|high|xhigh>`,
+      "info",
+    );
+    return;
+  }
+  if (arg === "off") {
+    updateConfig(ctx, (c) => ({ ...c, thinking: false }), "Vision describer thinking off.");
+    return;
+  }
+  if (!isThinkingLevel(arg)) {
+    ctx.ui.notify(
+      `Unknown thinking level: "${arg}". Use off, minimal, low, medium, high, or xhigh.`,
+      "error",
+    );
+    return;
+  }
+  const level = arg;
+  updateConfig(
+    ctx,
+    (c) => ({ ...c, thinking: true, thinkingLevel: level }),
+    `Vision describer thinking on (${level}).`,
+  );
+}
+
 async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
   if (!ctx.hasUI) {
     ctx.ui.notify("/vision-handoff requires interactive mode.", "error");
@@ -590,10 +637,17 @@ async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
 
   const allModels = ctx.modelRegistry
     .getAll()
-    .map((m) => ({ provider: m.provider, id: m.id, name: m.name, input: m.input }));
+    .map((m) => ({ provider: m.provider, id: m.id, name: m.name, input: m.input, reasoning: m.reasoning }));
 
   const result = await ctx.ui.custom<VisionModelSelectorResult>((tui, theme, _kb, done) => {
-    const selector = new VisionModelSelectorComponent(theme, allModels, config.visionModel, (r) => done(r));
+    const selector = new VisionModelSelectorComponent(
+      theme,
+      allModels,
+      config.visionModel,
+      config.thinking,
+      config.thinkingLevel,
+      (r) => done(r),
+    );
     return {
       render(width: number) {
         return selector.render(width);
@@ -614,7 +668,18 @@ async function showSelector(ctx: ExtensionCommandContext): Promise<void> {
   }
 
   const ref = result.ref;
-  updateConfig(ctx, (c) => ({ ...c, visionModel: ref }), ref ? `Vision model set to ${ref}` : "Vision model cleared");
+  const thinking = result.thinking;
+  const thinkingLevel = result.thinkingLevel;
+  updateConfig(
+    ctx,
+    (c) => ({ ...c, visionModel: ref, thinking, thinkingLevel }),
+    ref ? `Vision model set to ${ref}` : "Vision model cleared",
+  );
+  ctx.ui.notify(
+    `Thinking: ${thinking ? `on (${thinkingLevel})` : "off"}` +
+      (thinking && ref ? " — applies only if the vision model supports reasoning" : ""),
+    "info",
+  );
   if (!ref) {
     ctx.ui.notify("Handoff is inactive until you pick a vision model.", "warning");
   }
@@ -626,6 +691,7 @@ function showStatus(ctx: ExtensionCommandContext): void {
   lines.push(`Vision model: ${config.visionModel ?? "(none — pick one with /vision-handoff)"}`);
   lines.push(`Auto handoff (non-vision models): ${config.autoHandoff ? "on" : "off"}`);
   lines.push(`Handoff targets (explicit): ${config.handoffModels.length ? config.handoffModels.join(", ") : "(none)"}`);
+  lines.push(`Thinking: ${config.thinking ? `on (${config.thinkingLevel})` : "off"}`);
   lines.push(`maxTokens: ${config.maxTokens ?? "unbounded"} · cacheMax: ${config.cacheMax} · maxDescriptionLines: ${config.maxDescriptionLines === 0 ? "unbounded" : config.maxDescriptionLines}`);
 
   const model = ctx.model;