bermudis-pi-goodies 0.22.0 → 0.23.0

package/README.md

@@ -13,19 +13,19 @@ extensions. One entry point, twelve independent features.
 | `keep-model-on-new` | hook (no command)            | Keep the active model when `/new` starts a fresh session instead of reverting to pi's saved default model.                                    |
 | `model-thinking`   | `/model-thinking`             | Per-model default thinking levels: save the current level as this model's default and get it back on every switch to that model, instead of pi's global default. |
 | `clean-tui`        | tool overrides (no command)   | Collapse built-in tool output for a cleaner TUI: back-to-back same-tool calls share one block (e.g. `read ×2`) until a boundary — visible text (assistant prose or a typed user message) or a thinking block (even an empty one, as OpenAI emits between tool calls) — so reasoning-per-call models render one block per call. Images stay visible without expanding, expand a row with ctrl+o to see the full command and results/diffs. Long bash commands get an AI-generated summary once you pick a model with `/goodies summary-model <provider/model>` (see "Smart summaries" below) — expanding a row swaps the summary back out for the raw command. While enabled, also flips `@bermudi/pi-codex`'s `apply_patch`/`web_search` into the same burst style. Long thinking runs can show a live plain-English line above the editor (`/goodies thinking-summaries on`) instead of a static `Thinking...` — see "Smart summaries". |
-| `review`           | `/review`, `/end-review`      | Code review workflow: review uncommitted changes, a branch, a commit, a GitHub PR, or folders. Prioritized findings with actionable follow-ups. |
+| `review`           | `/review`, `/end-review`      | Code review workflow: review uncommitted changes, a branch, a commit, a GitHub PR, or folders. Prioritized findings with actionable follow-ups. Targets tab-complete. |
 | `kilo`             | provider                      | Access Kilo Gateway models via `/login kilo` or `KILO_API_KEY`.                                                                                 |
 | `provider-balance` | footer (no command)           | Show remaining Kilo, OpenRouter, or CommandCode credits, z.ai token-plan quota, or OpenAI Codex quota on the right side of the working-directory footer line. |
 | `tps`              | hook (no command)             | Notify tokens/sec and in/out/cache token usage at the end of each agent turn.                                                                   |
 | `vision`           | `vision` tool, `/vision`      | Ask a vision model targeted questions about an image file and get a text answer — for models that can't see images. Follow-ups via `followUp: true`. Self-hides when the active model has image input. |
-| `goodies`          | `/goodies`                    | Toggle individual features on/off without losing the rest. Also supports `/goodies summary-model [provider/model]` to pick the model used for AI bash-command summaries, and `/goodies thinking-summaries <on\|off>` for live thinking summaries. State persists to `~/.pi/agent/goodies.json`. |
+| `goodies`          | `/goodies`                    | Toggle individual features on/off without losing the rest. Also supports `/goodies summary-model [provider/model]` to pick the model used for AI bash-command summaries, and `/goodies thinking-summaries <on\|off>` for live thinking summaries. State persists to `~/.pi/agent/goodies.json`. Arguments tab-complete. |
 
 ## Install
 
 After publishing the package to npm:
 
 ```bash
-pi install npm:bermudis-pi-goodies@0.22.0
+pi install npm:bermudis-pi-goodies@0.23.0
 ```
 
 Remove any old `bermudis-pi-goodies.ts` symlink before reloading Pi. Each
@@ -311,7 +311,9 @@ this feature never stores credentials.
 ```
 
 `/vision set` live-validates: typos get "did you mean" suggestions, text-only
-models and missing auth are rejected immediately. Config lives in
+models and missing auth are rejected immediately. Arguments tab-complete:
+subcommands, then `model=` / bare model ids (image-capable models from pi's
+registry, ranked), then `maxTokens=`. Config lives in
 `~/.pi/agent/vision.json` (0600, follows `PI_CODING_AGENT_DIR`); env fallback
 `VISION_MODEL=provider/model`.
 
@@ -328,5 +330,9 @@ Behavior notes:
   capped at 8 threads / 10 turns, in-memory only.
 - Answers return as plain text (same trust model as any tool output); the
   vision model's own system prompt refuses instructions embedded in the image.
+- Rows render in the clean-tui burst style while that feature is enabled
+  (header = path + question, follow-ups annotated, answers on expand,
+  same-tool calls group as `vision ×N`); with clean-tui disabled the tool
+  falls back to pi's default rendering.
 - Nested completion usage is reported back, so pi's session stats stay
   accurate.

package/clean-tui.ts

@@ -103,7 +103,7 @@ function getBuiltInTools(cwd: string): BuiltInTools {
   return tools;
 }
 
-function shortenPath(path: string): string {
+export function shortenPath(path: string): string {
   const home = homedir();
   // Only a real subpath of home shortens: a bare startsWith turns a sibling
   // like `/home/me-other/x` into `~-other/x`.
@@ -1359,6 +1359,106 @@ function makeBox(
   return box;
 }
 
+/** While set, sibling extension tools in this package render in burst style
+ *  (same contract @bermudi/pi-codex mirrors via Symbol.for). Set at load,
+ *  cleared when the feature is disabled, so /reload converges. Consumers must
+ *  read it at registration time — rendering never happens before all
+ *  extensions load. */
+export function isCleanTuiActive(): boolean {
+  return (globalThis as Record<symbol, unknown>)[CLEAN_TUI_ACTIVE] === true;
+}
+
+/** Format spec for a burst-style tool. The shared skeleton below carries the
+ *  grouped/solo/pending/error rules once for every tool that uses it. */
+export type BurstToolSpec = {
+  name: string;
+  /** Required when registering via registerBurstTool (built-in override);
+   *  createBurstRenderer ignores these — the tool keeps its own definition. */
+  description?: any;
+  parameters?: any;
+  /** Bullet line for one entry inside a grouped header. */
+  bullet: (entry: Entry, theme: any) => string;
+  /** Extra lines appended to the grouped header when expanded (or ""). */
+  groupedDetails: (entries: Entry[], theme: any) => string;
+  /** Solo (ungrouped) header line, without expanded output. */
+  soloHeader: (args: any, theme: any, ctx: any) => string;
+  /** Extra lines appended to the solo header when expanded (or ""). */
+  soloExpanded: (entry: Entry, args: any, theme: any) => string;
+  /** Hook run right after upsertEntry (bash: request a summary). */
+  onUpsert?: (entry: Entry, args: any, ctx: any) => void;
+};
+
+/** The shared burst render hooks (renderShell + renderCall + renderResult),
+ *  split out of registerBurstTool so extension-owned tools in this package
+ *  (vision) can attach the identical skeleton to their own registration —
+ *  one implementation of the grouped/solo/pending/error rules, no copy. */
+export function createBurstRenderer(spec: BurstToolSpec): {
+  renderShell: "self";
+  renderCall: (args: any, theme: any, ctx: any) => any;
+  renderResult: (result: any, _opts: any, _theme: any, ctx: any) => Container;
+} {
+  return {
+    renderShell: "self",
+    renderCall(args: any, theme: any, ctx: any) {
+      const entry = upsertEntry(
+        ctx.toolCallId,
+        spec.name,
+        args,
+        ctx.invalidate,
+      );
+      spec.onUpsert?.(entry, args, ctx);
+      const burst = getBurstForId(ctx.toolCallId);
+      const isGrouped = burst && burst.entries.length > 1;
+      const isLeader =
+        isGrouped && burst.entries[0].toolCallId === ctx.toolCallId;
+      // The burst box is shared by every call in the group, so its background
+      // never takes the error color — a failure (the leader included) is
+      // marked on its own bullet instead. Pending does aggregate: the box
+      // stays in its running state until every call in the burst has landed.
+      // (b80a14d "follow the leader" painted the whole block red whenever the
+      // first call itself failed; this rule — formerly only on bash — now
+      // applies to every burst tool.)
+      const pending = isGrouped
+        ? burst.entries.some((e) => !e.result)
+        : !entry.result;
+      const isError = isGrouped ? false : !!entry.isError;
+
+      if (isGrouped && !isLeader) {
+        // Refresh the leader's header/count. Single hop: a leader's renderCall
+        // never invalidates anything, so this cannot loop.
+        const lead = invalidateById.get(burst.entries[0].toolCallId);
+        if (lead) lead();
+        return new Container();
+      }
+
+      if (isGrouped && isLeader) {
+        let header = `${theme.fg("toolTitle", theme.bold(spec.name))} ${theme.fg("muted", `×${burst.entries.length}`)}`;
+        header += `\n${burst.entries.map((e) => spec.bullet(e, theme)).join("\n")}`;
+        if (ctx.expanded) {
+          const details = spec.groupedDetails(burst.entries, theme);
+          if (details) header += details;
+        }
+        return makeBox(theme, pending, isError, header);
+      }
+
+      // solo
+      let line = spec.soloHeader(args, theme, ctx);
+      if (ctx.expanded) {
+        const extra = spec.soloExpanded(entry, args, theme);
+        if (extra) line += `\n${extra}`;
+      }
+      return makeBox(theme, pending, isError, line);
+    },
+    renderResult(result: any, _opts: any, _theme: any, ctx: any) {
+      recordResult(entryById.get(ctx.toolCallId), result, ctx);
+      // All visual work is done in renderCall (unified box); keep the result
+      // slot empty. Images are rendered by Pi's ToolExecutionComponent image
+      // layer even when we return empty here.
+      return new Container();
+    },
+  };
+}
+
 // ── Per-tool helpers ────────────────────────────────────────────
 function formatReadHeader(args: any, theme: any): string {
   const path = shortenPath(args.path || "");
@@ -1637,98 +1737,25 @@ export default function cleanTui(pi: ExtensionAPI): void {
   });
 
   // ── Shared burst-tool skeleton ─────────────────────────────────
-  // Every burst tool (read/bash/write/edit/find/grep/ls) shares one render
-  // skeleton: upsert → burst → leader/follower split → grouped box or solo
-  // box. Per-tool behavior is a spec of formatters. This deletes ~450 lines of
-  // copy-paste and, more importantly, makes the divergence class impossible:
-  // the "one failed row paints the whole burst red" bug was fixed twice for
-  // bash (b80a14d, then the isGrouped?false rule) but the other six tools still
+  // registerBurstTool = createBurstRenderer (module-level, shared with
+  // vision's own registration) + execute delegation to the cached built-in
+  // tool. Every burst tool (read/bash/write/edit/find/grep/ls) shares that one
+  // render skeleton, which makes the divergence class impossible: the "one
+  // failed row paints the whole burst red" bug was fixed twice for bash
+  // (b80a14d, then the isGrouped?false rule) but the other six tools still
   // shipped `isGrouped ? entries.some(e => e.isError)` — the shared skeleton
   // carries the single correct rule for all of them.
-  type BurstToolSpec = {
-    name: string;
-    description: any;
-    parameters: any;
-    /** Bullet line for one entry inside a grouped header. */
-    bullet: (entry: Entry, theme: any) => string;
-    /** Extra lines appended to the grouped header when expanded (or ""). */
-    groupedDetails: (entries: Entry[], theme: any) => string;
-    /** Solo (ungrouped) header line, without expanded output. */
-    soloHeader: (args: any, theme: any, ctx: any) => string;
-    /** Extra lines appended to the solo header when expanded (or ""). */
-    soloExpanded: (entry: Entry, args: any, theme: any) => string;
-    /** Hook run right after upsertEntry (bash: request a summary). */
-    onUpsert?: (entry: Entry, args: any, ctx: any) => void;
-  };
-
   function registerBurstTool(spec: BurstToolSpec): void {
     pi.registerTool({
       name: spec.name,
       label: spec.name,
       description: spec.description,
       parameters: spec.parameters,
-      renderShell: "self",
+      ...createBurstRenderer(spec),
       async execute(toolCallId, params, signal, onUpdate, ctx) {
         const tool = (getBuiltInTools(ctx.cwd) as any)[spec.name];
         return tool.execute(toolCallId, params, signal, onUpdate);
       },
-      renderCall(args, theme, ctx: any) {
-        const entry = upsertEntry(
-          ctx.toolCallId,
-          spec.name,
-          args,
-          ctx.invalidate,
-        );
-        spec.onUpsert?.(entry, args, ctx);
-        const burst = getBurstForId(ctx.toolCallId);
-        const isGrouped = burst && burst.entries.length > 1;
-        const isLeader =
-          isGrouped && burst.entries[0].toolCallId === ctx.toolCallId;
-        // The burst box is shared by every call in the group, so its background
-        // never takes the error color — a failure (the leader included) is
-        // marked on its own bullet instead. Pending does aggregate: the box
-        // stays in its running state until every call in the burst has landed.
-        // (b80a14d "follow the leader" painted the whole block red whenever the
-        // first call itself failed; this rule — formerly only on bash — now
-        // applies to every burst tool.)
-        const pending = isGrouped
-          ? burst.entries.some((e) => !e.result)
-          : !entry.result;
-        const isError = isGrouped ? false : !!entry.isError;
-
-        if (isGrouped && !isLeader) {
-          // Refresh the leader's header/count. Single hop: a leader's renderCall
-          // never invalidates anything, so this cannot loop.
-          const lead = invalidateById.get(burst.entries[0].toolCallId);
-          if (lead) lead();
-          return new Container();
-        }
-
-        if (isGrouped && isLeader) {
-          let header = `${theme.fg("toolTitle", theme.bold(spec.name))} ${theme.fg("muted", `×${burst.entries.length}`)}`;
-          header += `\n${burst.entries.map((e) => spec.bullet(e, theme)).join("\n")}`;
-          if (ctx.expanded) {
-            const details = spec.groupedDetails(burst.entries, theme);
-            if (details) header += details;
-          }
-          return makeBox(theme, pending, isError, header);
-        }
-
-        // solo
-        let line = spec.soloHeader(args, theme, ctx);
-        if (ctx.expanded) {
-          const extra = spec.soloExpanded(entry, args, theme);
-          if (extra) line += `\n${extra}`;
-        }
-        return makeBox(theme, pending, isError, line);
-      },
-      renderResult(result: any, _opts: any, _theme: any, ctx: any) {
-        recordResult(entryById.get(ctx.toolCallId), result, ctx);
-        // All visual work is done in renderCall (unified box); keep the result
-        // slot empty. Images are rendered by Pi's ToolExecutionComponent image
-        // layer even when we return empty here.
-        return new Container();
-      },
     });
   }
 

package/goodies.ts

@@ -22,6 +22,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { reportFailure } from "./goodies-log.ts";
 import { writeJsonFileAtomic, describeError } from "./json-file.ts";
+import { rankCandidates } from "./vision-core.ts";
 
 let CONFIG_PATH = join(homedir(), ".pi", "agent", "goodies.json");
 
@@ -337,6 +338,19 @@ export function completeGoodiesArguments(
       ? matches.map((v) => ({ value: `${verb} ${v}`, label: v }))
       : null;
   }
+  if (verb === "summary-model") {
+    // Single value token (model ids contain no spaces): "off"/"default"
+    // clear the setting; anything else matches the catalogue, ranked.
+    const q = valuePrefix.toLowerCase();
+    const items: AutocompleteItem[] = [];
+    for (const w of ["off", "default"]) {
+      if (w.startsWith(q)) items.push({ value: w, label: w });
+    }
+    for (const c of rankCandidates(completionModels, q).slice(0, 20)) {
+      items.push({ value: c, label: c });
+    }
+    return items.length ? items : null;
+  }
   return null;
 }
 
@@ -395,10 +409,28 @@ export function wrapGoodiesAutocomplete(
 
 let autocompleteWrapped = false;
 
+/**
+ * All catalogue models as "provider/id", stashed at session start for
+ * summary-model argument completion — completion callbacks are synchronous
+ * and context-free, so the registry must be captured beforehand. No auth
+ * filtering: getApiKeyAndHeaders can refresh OAuth tokens, far too heavy for
+ * keystrokes; a keyless pick hits the existing set-time warning instead.
+ */
+let completionModels: string[] = [];
+
+export function __setCompletionModelsForTesting(models: string[]): void {
+  completionModels = models;
+}
+
 export default function goodies(pi: ExtensionAPI): void {
   // Once per extension load: session_start also fires on /new, /resume, and
   // /fork, where the first session's wrapper is still installed.
   pi.on("session_start", (_event, ctx) => {
+    if (ctx.modelRegistry) {
+      completionModels = ctx.modelRegistry
+        .getAvailable()
+        .map((m) => `${m.provider}/${m.id}`);
+    }
     if (autocompleteWrapped) return;
     autocompleteWrapped = true;
     ctx.ui.addAutocompleteProvider(wrapGoodiesAutocomplete);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bermudis-pi-goodies",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bermudi/agent-extensions.git",

package/review.ts

@@ -54,6 +54,8 @@ import {
   SelectList,
   Spacer,
   Text,
+  type AutocompleteItem,
+  type AutocompleteProvider,
 } from "@earendil-works/pi-tui";
 import path from "node:path";
 import { promises as fs } from "node:fs";
@@ -383,6 +385,27 @@ async function getLocalBranches(pi: ExtensionAPI): Promise<string[]> {
     .filter((b) => b.trim());
 }
 
+/**
+ * Get list of remote-tracking branches (e.g. origin/main, origin/master).
+ *
+ * Filters out the bare remote name (`origin`), the symbolic HEAD refs
+ * (origin/HEAD), and any non-origin remotes — origin is the conventional
+ * upstream and the only one the merge-base fallback path is meaningful for.
+ */
+async function getRemoteBranches(pi: ExtensionAPI): Promise<string[]> {
+  const { stdout, code } = await pi.exec("git", [
+    "branch",
+    "--remotes",
+    "--format=%(refname:short)",
+  ]);
+  if (code !== 0) return [];
+  return stdout
+    .trim()
+    .split("\n")
+    .map((b) => b.trim())
+    .filter((b) => b.startsWith("origin/") && !b.endsWith("/HEAD"));
+}
+
 /**
  * Get list of recent commits
  */
@@ -722,7 +745,7 @@ const REVIEW_PRESETS = [
   {
     value: "baseBranch",
     label: "Review against a base branch",
-    description: "(local)",
+    description: "(local or origin/*)",
   },
   { value: "commit", label: "Review a commit", description: "" },
   {
@@ -742,6 +765,112 @@ type ReviewPresetValue =
   | (typeof REVIEW_PRESETS)[number]["value"]
   | typeof TOGGLE_CUSTOM_INSTRUCTIONS_VALUE;
 
+// ── /review argument completion ─────────────────────────────────────────
+
+const REVIEW_VERBS_WITH_ARGUMENT = new Set([
+  "branch",
+  "commit",
+  "folder",
+  "pr",
+  "--extra",
+]);
+const REVIEW_VERBS = [
+  "uncommitted",
+  "branch",
+  "commit",
+  "folder",
+  "pr",
+  "--extra",
+];
+
+/**
+ * Complete /review arguments: the target verb (uncommitted/branch/commit/
+ * folder/pr) and the --extra flag. Values are refs, paths, or free text —
+ * no synchronous completion can do those justice, so returning null lets
+ * pi fall back to file completion (right for folder, harmless for refs).
+ */
+export function completeReviewArgument(
+  prefix: string,
+): AutocompleteItem[] | null {
+  if (!/\s/.test(prefix)) {
+    const query = prefix.trim().toLowerCase();
+    const matches = REVIEW_VERBS.filter((w) => w.startsWith(query));
+    return matches.length
+      ? matches.map((w) => ({
+          value: REVIEW_VERBS_WITH_ARGUMENT.has(w) ? `${w} ` : w,
+          label: w,
+        }))
+      : null;
+  }
+  const m = prefix.match(/^(\S+)\s+([\s\S]*)$/);
+  if (!m) return null;
+  const rest = m[2];
+  const tokens = rest.split(/\s+/).filter(Boolean);
+  const cur = /\s$/.test(rest) ? "" : (tokens[tokens.length - 1] ?? "");
+  // Only a partial flag completes past the verb; values stay free-form.
+  if (cur.startsWith("-")) {
+    return "--extra".startsWith(cur)
+      ? [{ value: "--extra ", label: "--extra" }]
+      : null;
+  }
+  return null;
+}
+
+/** The argument text of a /review line, or null outside that context. */
+function reviewArgumentText(
+  lines: string[],
+  cursorLine: number,
+  cursorCol: number,
+): string | null {
+  if (cursorLine !== 0) return null;
+  const match = /^\/review\s+(.*)$/.exec((lines[0] ?? "").slice(0, cursorCol));
+  return match ? match[1] : null;
+}
+
+/**
+ * Pi's editor turns Tab in slash-command argument context into a forced file
+ * completion that never consults the command's getArgumentCompletions, so Tab
+ * after "/review " would list cwd paths. Claim that context and answer from
+ * the command's own completions — mirrors goodies' wrapGoodiesAutocomplete.
+ * Returning null (values, unknown flags) falls back to file completion.
+ */
+export function wrapReviewAutocomplete(
+  current: AutocompleteProvider,
+): AutocompleteProvider {
+  return {
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      if (options.force) {
+        const argumentText = reviewArgumentText(lines, cursorLine, cursorCol);
+        if (argumentText !== null) {
+          const items = completeReviewArgument(argumentText);
+          return items ? { items, prefix: argumentText } : null;
+        }
+      }
+      return current.getSuggestions(lines, cursorLine, cursorCol, options);
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(
+        lines,
+        cursorLine,
+        cursorCol,
+        item,
+        prefix,
+      );
+    },
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      if (reviewArgumentText(lines, cursorLine, cursorCol) !== null) {
+        return true;
+      }
+      return (
+        current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ??
+        true
+      );
+    },
+  };
+}
+
+let reviewAutocompleteWrapped = false;
+
 export default function reviewExtension(pi: ExtensionAPI) {
   function persistReviewSettings() {
     pi.appendEntry(REVIEW_SETTINGS_TYPE, {
@@ -845,6 +974,22 @@ export default function reviewExtension(pi: ExtensionAPI) {
 
   pi.on("session_start", (_event, ctx) => {
     applyAllReviewState(ctx);
+    // Claim the /review forced-Tab context once per extension load (guarded:
+    // harness stubs and limited contexts lack addAutocompleteProvider).
+    const ui = (
+      ctx as {
+        ui?: {
+          addAutocompleteProvider?: (
+            factory: (current: AutocompleteProvider) => AutocompleteProvider,
+          ) => void;
+        };
+      }
+    ).ui;
+    const add = ui?.addAutocompleteProvider;
+    if (!reviewAutocompleteWrapped && typeof add === "function") {
+      reviewAutocompleteWrapped = true;
+      add(wrapReviewAutocomplete);
+    }
   });
 
   pi.on("session_tree", (_event, ctx) => {
@@ -1022,14 +1167,29 @@ export default function reviewExtension(pi: ExtensionAPI) {
   async function showBranchSelector(
     ctx: ExtensionContext,
   ): Promise<ReviewTarget | null> {
-    const branches = await getLocalBranches(pi);
+    const [localBranches, remoteBranches] = await Promise.all([
+      getLocalBranches(pi),
+      getRemoteBranches(pi),
+    ]);
     const currentBranch = await getCurrentBranch(pi);
     const defaultBranch = await getDefaultBranch(pi);
 
-    // Never offer the current branch as a base branch (reviewing against itself is meaningless).
+    // Combine local and remote-tracking branches. Dedupe by name (a local
+    // branch and its origin/<name> counterpart are distinct refs, so both
+    // stay — the user explicitly asked for origin/main | origin/master).
+    const seen = new Set<string>();
+    const combined = [...localBranches, ...remoteBranches].filter((b) => {
+      if (seen.has(b)) return false;
+      seen.add(b);
+      return true;
+    });
+
+    // Never offer the current branch as a base branch (reviewing against
+    // itself is meaningless). Remote-tracking branches are never equal to a
+    // local current-branch name, so they pass through untouched.
     const candidateBranches = currentBranch
-      ? branches.filter((b) => b !== currentBranch)
-      : branches;
+      ? combined.filter((b) => b !== currentBranch)
+      : combined;
 
     if (candidateBranches.length === 0) {
       ctx.ui.notify(
@@ -1041,18 +1201,28 @@ export default function reviewExtension(pi: ExtensionAPI) {
       return null;
     }
 
-    // Sort branches with default branch first
+    const defaultRemote = `origin/${defaultBranch}`;
+
+    // Sort: default local branch first, then its origin/<default> counterpart,
+    // then remaining locals, then remaining remotes — each group alphabetical.
     const sortedBranches = candidateBranches.sort((a, b) => {
       if (a === defaultBranch) return -1;
       if (b === defaultBranch) return 1;
+      if (a === defaultRemote) return -1;
+      if (b === defaultRemote) return 1;
+      const aRemote = a.startsWith("origin/");
+      const bRemote = b.startsWith("origin/");
+      if (aRemote !== bRemote) return aRemote ? 1 : -1;
       return a.localeCompare(b);
     });
 
-    const items: SelectItem[] = sortedBranches.map((branch) => ({
-      value: branch,
-      label: branch,
-      description: branch === defaultBranch ? "(default)" : "",
-    }));
+    const items: SelectItem[] = sortedBranches.map((branch) => {
+      let description = "";
+      if (branch === defaultBranch) description = "(default)";
+      else if (branch === defaultRemote) description = "(remote default)";
+      else if (branch.startsWith("origin/")) description = "(remote)";
+      return { value: branch, label: branch, description };
+    });
 
     const result = await ctx.ui.custom<string | null>(
       (tui, theme, keybindings, done) => {
@@ -1534,6 +1704,7 @@ export default function reviewExtension(pi: ExtensionAPI) {
   pi.registerCommand("review", {
     description:
       "Review code changes (PR, uncommitted, branch, commit, or folder)",
+    getArgumentCompletions: completeReviewArgument,
     handler: async (args, ctx) => {
       if (!ctx.hasUI) {
         ctx.ui.notify("Review requires interactive mode", "error");

package/vision-core.ts

@@ -214,6 +214,97 @@ export function parseVisionArgs(args: string): {
   return { action: "set", values };
 }
 
+// --- argument completion -------------------------------------------------------
+
+export interface CompletionItem {
+  value: string;
+  label: string;
+}
+
+/** Sort candidates by match quality against q: startsWith, then contains,
+ *  then alphabetical. Stable and predictable — completion must not jump.
+ *  Shared by /vision and /goodies summary-model completion. */
+export function rankCandidates(candidates: string[], q: string): string[] {
+  const lower = candidates.map((c) => ({ c, l: c.toLowerCase() }));
+  return lower
+    .map((e) => {
+      const rank = e.l.startsWith(q) ? 0 : e.l.includes(q) ? 1 : 2;
+      return { c: e.c, rank };
+    })
+    .filter((e) => e.rank < 2)
+    .sort((a, b) => a.rank - b.rank || a.c.localeCompare(b.c))
+    .map((e) => e.c);
+}
+
+const VISION_SUBCOMMANDS = ["set", "show", "status", "reset"];
+
+/**
+ * Complete /vision arguments from `candidates` (vision models as
+ * "provider/id"). Pure: the caller supplies candidates, so this is testable
+ * without a registry. Returns null when nothing matches (pi then falls back).
+ *
+ * Shapes completed:
+ *   "" | "s"            → subcommands ("set " keeps its trailing space)
+ *   "set "              → keys (model=, maxTokens=2000) + model candidates
+ *   "set zai"           → bare model candidates matching "zai"
+ *   "set model=goog"    → model= candidates
+ *   "set model=x maxTo" → maxTokens=2000
+ * A model already given (model= or bare) suppresses further model items;
+ * maxTokens= given → null (nothing left to complete).
+ */
+export function completeVisionArgument(
+  prefix: string,
+  candidates: string[],
+  limit = 20,
+): CompletionItem[] | null {
+  // No whitespace yet → completing the subcommand itself (empty and partial
+  // words alike; the verb regex below only makes sense past the first space).
+  if (!/\s/.test(prefix)) {
+    const query = prefix.trim();
+    const subs = VISION_SUBCOMMANDS.filter((s) => s.startsWith(query));
+    return subs.length
+      ? subs.map((s) => ({ value: s === "set" ? "set " : s, label: s }))
+      : null;
+  }
+  const verbMatch = prefix.match(/^(\S+)\s+([\s\S]*)$/);
+  if (!verbMatch || verbMatch[1] !== "set") return null;
+  const rest = verbMatch[2] ?? "";
+
+  // Completed tokens vs the trailing partial ("" right after a space), so
+  // "set a/b " completes the next key instead of a second model.
+  const tokens = rest.split(/\s+/).filter(Boolean);
+  const trailingSpace = /\s$/.test(rest);
+  const cur = trailingSpace ? "" : (tokens[tokens.length - 1] ?? "");
+  const earlier = trailingSpace ? tokens : tokens.slice(0, -1);
+
+  const hasModel = earlier.some(
+    (t) => t.startsWith("model=") || !/^[a-zA-Z]+=/.test(t),
+  );
+  if (earlier.some((t) => t.startsWith("maxTokens="))) return null;
+
+  const q = cur.toLowerCase();
+  const items: CompletionItem[] = [];
+  if (cur.startsWith("model=")) {
+    if (!hasModel) {
+      for (const c of rankCandidates(candidates, cur.slice(6).toLowerCase()))
+        items.push({ value: `model=${c}`, label: `model=${c}` });
+    }
+  } else if (/^maxtokens/i.test(cur)) {
+    if ("maxtokens=2000".startsWith(q))
+      items.push({ value: "maxTokens=2000", label: "maxTokens=2000" });
+  } else {
+    if (!hasModel && "model=".startsWith(q))
+      items.push({ value: "model=", label: "model=" });
+    if ("maxtokens=2000".startsWith(q))
+      items.push({ value: "maxTokens=2000", label: "maxTokens=2000" });
+    if (!hasModel) {
+      for (const c of rankCandidates(candidates, q))
+        items.push({ value: c, label: c });
+    }
+  }
+  return items.length ? items.slice(0, limit) : null;
+}
+
 // --- model resolution ----------------------------------------------------------
 
 /**

package/vision.ts

@@ -24,6 +24,7 @@ import { completeSimple } from "@earendil-works/pi-ai/compat";
 import { Type } from "typebox";
 import {
   applyVisionToolVisibility,
+  completeVisionArgument,
   configPath,
   createConversationStore,
   loadConfig,
@@ -37,14 +38,147 @@ import {
   type ContentBlockLike,
   type ModelLike,
 } from "./vision-core.ts";
+import type {
+  AutocompleteItem,
+  AutocompleteProvider,
+} from "@earendil-works/pi-tui";
+import {
+  createBurstRenderer,
+  isCleanTuiActive,
+  shortenPath,
+} from "./clean-tui.ts";
 
 /** Follow-up threads live per pi process: capped, in-memory, never persisted. */
 const conversations = createConversationStore();
 
+// ── /vision argument completion ─────────────────────────────────
+// Image-capable models as "provider/id", stashed at session start — the
+// completion callbacks are synchronous and receive no context, so the
+// registry must be captured beforehand (same shape as clean-tui's stash).
+let completionModels: string[] = [];
+let autocompleteWrapped = false;
+
+/** The argument text of a /vision line, or null outside that context. */
+function visionArgumentText(
+  lines: string[],
+  cursorLine: number,
+  cursorCol: number,
+): string | null {
+  if (cursorLine !== 0) return null;
+  const match = /^\/vision\s+(.*)$/.exec((lines[0] ?? "").slice(0, cursorCol));
+  return match ? match[1] : null;
+}
+
+/**
+ * Pi's editor turns Tab in slash-command argument context into a forced file
+ * completion that never consults the command's getArgumentCompletions, so Tab
+ * after "/vision set " would list cwd paths. Claim that context and answer
+ * from the command's own completions — mirrors goodies' wrapGoodiesAutocomplete.
+ */
+export function wrapVisionAutocomplete(
+  current: AutocompleteProvider,
+): AutocompleteProvider {
+  return {
+    async getSuggestions(lines, cursorLine, cursorCol, options) {
+      if (options.force) {
+        const argumentText = visionArgumentText(lines, cursorLine, cursorCol);
+        if (argumentText !== null) {
+          const items = completeVisionArgument(argumentText, completionModels);
+          return items ? { items, prefix: argumentText } : null;
+        }
+      }
+      return current.getSuggestions(lines, cursorLine, cursorCol, options);
+    },
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(
+        lines,
+        cursorLine,
+        cursorCol,
+        item,
+        prefix,
+      );
+    },
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      if (visionArgumentText(lines, cursorLine, cursorCol) !== null) {
+        return true;
+      }
+      return (
+        current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ??
+        true
+      );
+    },
+  };
+}
+
+/** Live completion for /vision arguments (non-forced path). */
+function completeVisionArguments(prefix: string): AutocompleteItem[] | null {
+  return completeVisionArgument(prefix, completionModels);
+}
+
+export function __setCompletionModelsForTesting(models: string[]): void {
+  completionModels = models;
+}
+
+/** First line of a question, hard-capped — prompts can be long/multi-line. */
+function questionPreview(prompt: unknown, cap: number): string {
+  const s = typeof prompt === "string" ? prompt : "";
+  if (!s) return "";
+  const nl = s.indexOf("\n");
+  let head = nl === -1 ? s : s.slice(0, nl);
+  if (head.length > cap) head = head.slice(0, cap - 1) + "…";
+  return head;
+}
+
+/** Answer text of a recorded vision result (its content is one text block). */
+function answerText(result: unknown): string {
+  const content = (result as { content?: Array<{ text?: string }> } | undefined)
+    ?.content;
+  return String(content?.[0]?.text ?? "").trim();
+}
+
+/** Burst-rendering spec (clean-tui style): header = path + question, the
+ *  answer stays hidden until the row is expanded. Same skeleton the built-in
+ *  tools use — attached only while clean-tui is active, else pi's default
+ *  rendering. */
+const visionBurstSpec = {
+  name: "vision",
+  bullet(entry: any, theme: any) {
+    const accent = (s: string) =>
+      theme.fg(entry.isError ? "error" : "accent", s);
+    const q = questionPreview(entry.args.prompt, 80);
+    const follow = entry.args.followUp ? theme.fg("muted", " (follow-up)") : "";
+    const label = `${accent(shortenPath(entry.args.path || "..."))}${follow}`;
+    return `  ${theme.fg("muted", "•")} ${label}${q ? theme.fg("toolOutput", ` — "${q}"`) : ""}`;
+  },
+  groupedDetails(entries: any[], theme: any) {
+    return entries
+      .map((e) => {
+        const label = `— ${shortenPath(e.args.path || "...")}${e.args.followUp ? " (follow-up)" : ""}: "${questionPreview(e.args.prompt, 90)}"`;
+        if (!e.result) return `\n${theme.fg("warning", `${label} (pending)`)}`;
+        const txt = answerText(e.result);
+        if (!txt) return `\n${theme.fg("muted", label)}`;
+        return `\n${theme.fg("muted", label)}\n${e.isError ? theme.fg("error", txt) : theme.fg("toolOutput", txt)}`;
+      })
+      .join("");
+  },
+  soloHeader(args: any, theme: any) {
+    const follow = args.followUp ? theme.fg("muted", " (follow-up)") : "";
+    const q = questionPreview(args.prompt, 90);
+    return `${theme.fg("toolTitle", theme.bold("vision"))} ${theme.fg("accent", shortenPath(args.path || "..."))}${follow}${q ? ` ${theme.fg("toolOutput", `"${q}"`)}` : ""}`;
+  },
+  soloExpanded(entry: any, _args: any, theme: any) {
+    if (!entry.result) return "";
+    const txt = answerText(entry.result);
+    if (!txt) return "";
+    return entry.isError ? theme.fg("error", txt) : theme.fg("toolOutput", txt);
+  },
+};
+
 export default function (pi: ExtensionAPI): void {
   pi.registerCommand("vision", {
     description:
       "Configure the vision tool (set/show/reset the vision model used for image Q&A)",
+    getArgumentCompletions: completeVisionArguments,
     handler: async (args, ctx) => {
       let parsed: ReturnType<typeof parseVisionArgs>;
       try {
@@ -116,6 +250,30 @@ export default function (pi: ExtensionAPI): void {
   }
   pi.on("session_start", (_event, ctx) => {
     syncVisionToolVisibility(ctx.model);
+    // Stash image-capable models for argument completion (only when a
+    // registry exists — stub contexts without one keep the previous stash).
+    if (ctx.modelRegistry) {
+      completionModels = ctx.modelRegistry
+        .getAvailable()
+        .filter(modelSupportsImages)
+        .map((m) => `${m.provider}/${m.id}`);
+    }
+    // Claim the /vision forced-Tab context once per extension load (guarded:
+    // harness stubs and limited contexts lack addAutocompleteProvider).
+    const ui = (
+      ctx as {
+        ui?: {
+          addAutocompleteProvider?: (
+            factory: (current: AutocompleteProvider) => AutocompleteProvider,
+          ) => void;
+        };
+      }
+    ).ui;
+    const add = ui?.addAutocompleteProvider;
+    if (!autocompleteWrapped && typeof add === "function") {
+      autocompleteWrapped = true;
+      add(wrapVisionAutocomplete);
+    }
   });
   pi.on("model_select", (event) => {
     syncVisionToolVisibility(event.model);
@@ -148,6 +306,10 @@ export default function (pi: ExtensionAPI): void {
         }),
       ),
     }),
+    // Burst-style rows while clean-tui is active (flag is settled before this
+    // loads — index.ts registers clean-tui first); pi's default rendering
+    // otherwise. Read at registration time, like the pi-codex contract.
+    ...(isCleanTuiActive() ? createBurstRenderer(visionBurstSpec) : {}),
     async execute(toolCallId, params, signal, onUpdate, ctx) {
       // Delegate image loading to pi's own read tool: photon resize,
       // magic-byte mime detection, size caps — battle-tested behavior.