pi-jar 0.1.0

package/src/delegate.ts

@@ -0,0 +1,208 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import type { ModelRoleManager } from "./model-roles.ts";
+import { ROLE_PREFIX } from "./status.ts";
+import { cleanText } from "./status.ts";
+
+export const DELEGATE_TOOL = "jar_delegate";
+/** Set in child processes so a subagent never delegates again. */
+export const CHILD_ENV = "PI_JAR_CHILD";
+export const MAX_DELEGATES = 4;
+export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls"] as const;
+const MAX_OUTPUT_CHARS = 12_000;
+const TIMEOUT_MS = 20 * 60_000;
+const STATUS_REFRESH_MS = 10_000;
+
+export type DelegateState = "queued" | "working" | "done" | "failed";
+export interface DelegateRun {
+  index: number;
+  name: string;
+  task: string;
+  role: string;
+  model?: string;
+  state: DelegateState;
+  activity?: string;
+  tools: number;
+  turns: number;
+  cost: number;
+  output: string;
+  error?: string;
+}
+
+type Spawn = (command: string, args: string[], options: Parameters<typeof spawn>[2]) => ChildProcess;
+
+/** How to run Pi again: the current script under the current runtime, or `pi` on PATH. */
+export function piInvocation(args: string[], argv = process.argv, execPath = process.execPath): { command: string; args: string[] } {
+  const script = argv[1];
+  if (script && !script.startsWith("/$bunfs/") && existsSync(script)) return { command: execPath, args: [script, ...args] };
+  if (!/^(node|bun)(\.exe)?$/i.test(basename(execPath))) return { command: execPath, args };
+  return { command: "pi", args };
+}
+
+/** CLI arguments for one subagent: JSON events, one-shot, no session, read-only tools unless `write`. */
+export function delegateArgs(task: string, model: string | undefined, thinking: string | undefined, write: boolean): string[] {
+  const args = ["--mode", "json", "-p", "--no-session"];
+  if (model) args.push("--model", model);
+  if (thinking) args.push("--thinking", thinking);
+  if (!write) args.push("--tools", READ_ONLY_TOOLS.join(","));
+  const rules = write
+    ? "You may edit files. Stay strictly within the task; other subagents may be working in the same repository at the same time."
+    : "You are read-only: investigate and report, do not attempt to modify anything.";
+  args.push(`You are a focused subagent working for another agent. ${rules} Finish with a concise, self-contained report of your findings or changes (include file paths).\n\nTask: ${task}`);
+  return args;
+}
+
+const textOf = (message: { content?: unknown }) => Array.isArray(message.content)
+  ? message.content.filter((part: { type?: string }) => part?.type === "text").map((part: { text?: string }) => part.text ?? "").join("\n")
+  : typeof message.content === "string" ? message.content : "";
+
+/** Run one child Pi, feeding progress into `run` and calling `update` on every change. */
+export function runDelegate(run: DelegateRun, args: string[], cwd: string, signal: AbortSignal | undefined, update: () => void, spawnProcess: Spawn = spawn as Spawn): Promise<void> {
+  return new Promise((resolve) => {
+    const invocation = piInvocation(args);
+    let child: ChildProcess;
+    try {
+      child = spawnProcess(invocation.command, invocation.args, { cwd, shell: false, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, [CHILD_ENV]: "1" } });
+    } catch (error) {
+      run.state = "failed"; run.error = error instanceof Error ? error.message : String(error); update(); resolve(); return;
+    }
+    run.state = "working";
+    run.activity = "starting";
+    update();
+    let buffer = "";
+    let stderr = "";
+    let finished = false;
+    const finish = (state: DelegateState, error?: string) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      run.state = state;
+      if (error) run.error = error;
+      run.activity = undefined;
+      update();
+      resolve();
+    };
+    const stop = () => { child.kill("SIGTERM"); setTimeout(() => { if (child.exitCode === null) child.kill("SIGKILL"); }, 3000).unref?.(); };
+    const abort = () => { stop(); finish("failed", "aborted"); };
+    const timer = setTimeout(() => { stop(); finish("failed", "timed out"); }, TIMEOUT_MS);
+    timer.unref?.();
+    if (signal?.aborted) { abort(); return; }
+    signal?.addEventListener("abort", abort, { once: true });
+    const line = (raw: string) => {
+      if (!raw.trim()) return;
+      let event: any;
+      try { event = JSON.parse(raw); } catch { return; }
+      if (event.type === "tool_execution_start") { run.tools++; run.activity = cleanText(String(event.toolName ?? "tool"), 24); update(); }
+      else if (event.type === "message_end" && event.message?.role === "assistant") {
+        run.turns++;
+        run.cost += Number(event.message.usage?.cost?.total) || 0;
+        const text = textOf(event.message).trim();
+        if (text) run.output = text.slice(0, MAX_OUTPUT_CHARS);
+        if (event.message.stopReason === "error" && event.message.errorMessage) run.error = cleanText(String(event.message.errorMessage), 200);
+        run.activity = "thinking";
+        update();
+      }
+    };
+    child.stdout?.on("data", (chunk) => {
+      buffer += String(chunk);
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const item of lines) line(item);
+    });
+    child.stderr?.on("data", (chunk) => { stderr = (stderr + String(chunk)).slice(-4000); });
+    child.on("error", (error) => finish("failed", error.message));
+    child.on("close", (code) => {
+      if (buffer) line(buffer);
+      if (code === 0 && !run.error) finish("done");
+      else finish("failed", run.error ?? (cleanText(stderr, 300) || `exited ${code}`));
+    });
+  });
+}
+
+const Parameters = Type.Object({
+  tasks: Type.Array(Type.Object({
+    task: Type.String({ description: "A complete, self-contained instruction: the subagent sees nothing else." }),
+    name: Type.Optional(Type.String({ description: "Short label, e.g. \"auth scout\"." })),
+    role: Type.Optional(Type.String({ description: "pi-jar role for the model (default \"task\", falls back to the current model)." }))
+  }), { minItems: 1, maxItems: MAX_DELEGATES }),
+  write: Type.Optional(Type.Boolean({ description: "Allow file edits (default false: read-only tools)." }))
+});
+
+const glyph = (state: DelegateState) => state === "done" ? "✔" : state === "failed" ? "✖" : state === "working" ? "●" : "○";
+const color = (state: DelegateState) => state === "done" ? "success" : state === "failed" ? "error" : state === "working" ? "accent" : "dim";
+
+export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, spawnProcess?: Spawn): void {
+  if (process.env[CHILD_ENV] || typeof (pi as ExtensionAPI & { registerTool?: unknown }).registerTool !== "function") return;
+  let batch = 0;
+  pi.registerTool({
+    name: DELEGATE_TOOL,
+    label: "delegate",
+    description: `Run up to ${MAX_DELEGATES} subagents in parallel, each an isolated Pi with a fresh context, on a pi-jar model role (default "task"). Read-only unless write is true. Returns each subagent's report.`,
+    promptSnippet: "Use jar_delegate to fan out independent investigations to parallel subagents.",
+    promptGuidelines: [
+      "Use jar_delegate for independent, parallelizable investigation (scouting several areas, reviewing, researching); give each task complete context because subagents see nothing else.",
+      "Keep delegated work read-only by default. Only set write for clearly separated edits that cannot conflict; never have two subagents edit the same files."
+    ],
+    parameters: Parameters,
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const id = ++batch;
+      const write = params.write === true;
+      const runs: DelegateRun[] = params.tasks.slice(0, MAX_DELEGATES).map((item, index) => {
+        const role = cleanText(item.role ?? "task", 32) || "task";
+        const resolved = roles.resolve(role) ?? roles.resolve("default");
+        const model = resolved ? `${resolved.provider}/${resolved.model}` : ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+        return { index: index + 1, name: cleanText(item.name ?? `agent ${index + 1}`, 24), task: item.task, role, ...(model ? { model } : {}),
+          state: "queued", tools: 0, turns: 0, cost: 0, output: "" };
+      });
+      const thinking = (role: string) => (roles.resolve(role) ?? roles.resolve("default"))?.thinking;
+      // Live teammates: the welcome TEAM row and the footer read this public status contract.
+      const publish = () => {
+        if (!ctx.hasUI) return;
+        for (const run of runs) {
+          try {
+            ctx.ui.setStatus(`${ROLE_PREFIX}delegate-${id}-${run.index}`, run.state === "done" || run.state === "failed" ? undefined : JSON.stringify({
+              name: run.name, label: run.name.slice(0, 12), state: run.state === "queued" ? "waiting" : "working", task: cleanText(run.task, 60), expiresAt: Date.now() + 25_000
+            }));
+          } catch { /* status is decoration */ }
+        }
+      };
+      const details = () => ({ runs: runs.map((run) => ({ ...run })), write });
+      const update = () => {
+        publish();
+        onUpdate?.({ content: [{ type: "text", text: runs.map((run) => `${run.name}: ${run.state}`).join("\n") }], details: details() });
+      };
+      const refresh = setInterval(publish, STATUS_REFRESH_MS);
+      refresh.unref?.();
+      try {
+        update();
+        await Promise.all(runs.map((run) => runDelegate(run, delegateArgs(run.task, run.model, thinking(run.role), write), ctx.cwd, signal, update, spawnProcess)));
+      } finally {
+        clearInterval(refresh);
+        for (const run of runs) if (run.state !== "done") run.state = "failed";
+        publish();
+      }
+      const report = runs.map((run) => `## [${run.index}] ${run.name} (${run.role}${run.model ? " · " + run.model : ""}) — ${run.state}${run.error ? ": " + run.error : ""}\n${run.output || "(no report)"}`).join("\n\n");
+      return { content: [{ type: "text", text: report }], details: details() };
+    },
+    renderCall(args, theme) {
+      const count = Array.isArray(args.tasks) ? args.tasks.length : 0;
+      return new Text(theme.fg("toolTitle", theme.bold("delegate")) + " " + theme.fg("accent", `${count} subagent${count === 1 ? "" : "s"}`)
+        + theme.fg("dim", args.write ? " · can edit" : " · read-only"), 0, 0);
+    },
+    renderResult(result, { expanded }, theme) {
+      const runs = (result.details as { runs?: DelegateRun[] } | undefined)?.runs ?? [];
+      const rows = runs.map((run) => {
+        const meta = [run.role, run.activity, run.tools ? `${run.tools} tools` : "", run.cost ? `$${run.cost.toFixed(3)}` : "", run.error].filter(Boolean).join(" · ");
+        let row = theme.fg(color(run.state) as never, `  ${glyph(run.state)} ${run.name}`) + theme.fg("dim", " · " + meta);
+        if (expanded && run.output) row += "\n" + run.output.split("\n").map((line) => theme.fg("muted", "    " + line)).join("\n");
+        return row;
+      });
+      return new Text(rows.join("\n") || theme.fg("dim", "No subagents."), 0, 0);
+    }
+  });
+}

package/src/dialogs.ts

@@ -0,0 +1,127 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Input, Key, matchesKey, truncateToWidth, wrapTextWithAnsi, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { todoMark, type Todo } from "./tasks.ts";
+import { cleanText } from "./status.ts";
+
+const fit = (line: string, width: number) => truncateToWidth(line, Math.max(0, width));
+
+/** Pi-jar owns these dialogs; Pi's normal and other extensions' questions are untouched. */
+export async function promptText(ctx: ExtensionContext, title: string, question: string, initial = ""): Promise<string | undefined> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return undefined;
+  return ctx.ui.custom<string | undefined>((tui, theme, _keys, done) => {
+    const input = new Input({ prompt: "❯ ", placeholder: "Type your answer" });
+    input.focused = true;
+    input.setValue(initial);
+    input.onSubmit = (value) => done(value.trim() || undefined);
+    input.onEscape = () => done(undefined);
+    let footerRow = 0;
+    return {
+      invalidate() { input.invalidate(); },
+      handleInput(data: string) { input.handleInput(data); tui.requestRender(); },
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type !== "click" || event.button !== "left") return;
+        if (event.y === footerRow) { done(input.getValue().trim() || undefined); return { handled: true }; }
+      },
+      render(width: number): string[] {
+        const lines = [
+          fit(theme.fg("accent", `╭─ ${cleanText(title, 56)} ─`), width),
+          ...wrapTextWithAnsi(cleanText(question, 160), Math.max(1, width - 2)).map((line) => fit(theme.fg("muted", `│ ${line}`), width)),
+          ...input.render(Math.max(1, width - 2)).map((line) => fit("│ " + line, width)),
+          fit(theme.fg("dim", "╰─ Enter: confirm · Esc: cancel"), width)
+        ];
+        footerRow = lines.length - 1;
+        return lines;
+      }
+    };
+  });
+}
+
+export async function promptChoice(ctx: ExtensionContext, title: string, question: string, choices: readonly string[], initial = 0): Promise<number | undefined> {
+  if (!ctx.hasUI || ctx.mode !== "tui" || !choices.length) return undefined;
+  return ctx.ui.custom<number | undefined>((tui, theme, _keys, done) => {
+    let selected = Math.max(0, Math.min(choices.length - 1, initial));
+    let firstChoiceRow = 0;
+    return {
+      invalidate() {},
+      handleInput(data: string) {
+        if (matchesKey(data, Key.escape)) return done(undefined);
+        if (matchesKey(data, Key.enter)) return done(selected);
+        if (matchesKey(data, Key.up)) selected = (selected + choices.length - 1) % choices.length;
+        if (matchesKey(data, Key.down)) selected = (selected + 1) % choices.length;
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type !== "click" || event.button !== "left") return;
+        const index = event.y - firstChoiceRow;
+        if (index >= 0 && index < choices.length) { selected = index; done(index); return { handled: true }; }
+      },
+      render(width: number): string[] {
+        const heading = [
+          fit(theme.fg("accent", `╭─ ${cleanText(title, 56)} ─`), width),
+          ...wrapTextWithAnsi(cleanText(question, 160), Math.max(1, width - 2)).map((line) => fit(theme.fg("muted", `│ ${line}`), width))
+        ];
+        firstChoiceRow = heading.length;
+        return [
+          ...heading,
+          ...choices.map((choice, index) => fit(theme.fg(index === selected ? "accent" : "dim", `${index === selected ? "❯" : " "} ${cleanText(choice, 80)}`), width)),
+          fit(theme.fg("dim", "╰─ ↑↓: choose · Enter: confirm · Esc: cancel"), width)
+        ];
+      }
+    };
+  });
+}
+
+export type TodoFilter = "all" | "open" | "done";
+export type TodoAction = { kind: "add" | "toggle" | "edit" | "delete"; id?: string };
+
+export async function todoView(ctx: ExtensionContext, todos: () => Todo[], filter: { value: TodoFilter }): Promise<TodoAction | undefined> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return undefined;
+  return ctx.ui.custom<TodoAction | undefined>((tui, theme, _keys, done) => {
+    let selected = 0;
+    const filtered = () => todos().filter((item) => filter.value === "all" || (filter.value === "done") === item.done);
+    let firstVisible = 0;
+    return {
+      invalidate() {},
+      handleInput(data: string) {
+        const items = filtered();
+        if (matchesKey(data, Key.escape) || data === "q") return done(undefined);
+        if (matchesKey(data, Key.up)) selected = Math.max(0, selected - 1);
+        else if (matchesKey(data, Key.down)) selected = Math.min(Math.max(0, items.length - 1), selected + 1);
+        else if (data === "f") {
+          const next: Record<TodoFilter, TodoFilter> = { all: "open", open: "done", done: "all" };
+          filter.value = next[filter.value]; selected = 0;
+        } else if (data === "a") return done({ kind: "add" });
+        else if (items[selected] && (data === " " || matchesKey(data, Key.enter))) return done({ kind: "toggle", id: items[selected].id });
+        else if (items[selected] && data === "e") return done({ kind: "edit", id: items[selected].id });
+        else if (items[selected] && data === "d") return done({ kind: "delete", id: items[selected].id });
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        if (event.type === "wheel" && event.wheelDelta) {
+          selected = Math.max(0, Math.min(filtered().length - 1, selected + Math.sign(event.wheelDelta)));
+          tui.requestRender(); return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left") return;
+        const index = firstVisible + event.y - 1;
+        const item = filtered()[index];
+        if (event.y >= 1 && event.y <= 12 && item) {
+          selected = index; done({ kind: "toggle", id: item.id }); return { handled: true };
+        }
+      },
+      render(width: number): string[] {
+        const items = filtered();
+        selected = Math.min(selected, Math.max(0, items.length - 1));
+        const count = todos().filter((item) => !item.done).length;
+        const start = Math.max(0, selected - 11);
+        firstVisible = start;
+        return [
+          fit(theme.fg("accent", `╭─ pi-jar to-do · ${count} open · ${filter.value} ─`), width),
+          ...(items.length ? items.slice(start, start + 12).map((item, index) =>
+            fit(theme.fg(start + index === selected ? "accent" : item.done ? "dim" : item.status === "in_progress" ? "warning" : "muted", `${start + index === selected ? "❯" : " "} ${todoMark(item)} ${item.title}`), width))
+            : [fit(theme.fg("dim", "  No items in this view"), width)]),
+          fit(theme.fg("dim", "╰─ ↑↓: select · Space: check · a: add · e: edit · d: delete · f: filter · Esc: close"), width)
+        ];
+      }
+    };
+  });
+}

package/src/diff-view.ts

@@ -0,0 +1,160 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { diffRows, lineDiff, type ChangeTracker, type DiffRow, type FileChange } from "./changes.ts";
+import { contentRows, optionList, sidebarWidth, splitFrame } from "./split-view.ts";
+
+const ACTIONS = [
+  { key: "a", label: "Accept this file (keep it, stop tracking)" },
+  { key: "r", label: "Revert this file (asks to confirm)" },
+  { key: "A", label: "Accept all files" },
+  { key: "R", label: "Revert all files (asks to confirm)" }
+] as const;
+
+const STATUS_MARK = { added: "A", modified: "M", deleted: "D" } as const;
+
+/** Keep indentation but drop escape sequences and control characters that would break layout. */
+export const safeLine = (text: string) => text.slice(0, 4000).replace(/\t/g, "  ")
+  .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)?|\x1b\[[0-?]*[ -/]*[@-~]|\x1b./g, "").replace(/[\x00-\x1f\x7f-\x9f]/g, "·");
+
+/** Styled diff rows for one file, with a gutter of old/new line numbers. */
+export function renderDiff(change: FileChange, width: number, fg: (color: string, text: string) => string): string[] {
+  const ops = lineDiff(change.before, change.after);
+  if (!ops) return [fg("warning", `Too large for an inline diff: +${change.added} −${change.removed} lines.`)];
+  const rows: DiffRow[] = diffRows(ops);
+  if (!rows.length) return [fg("dim", "No textual changes.")];
+  const gutter = Math.max(3, String(Math.max(...rows.map((row) => Math.max(row.oldLine ?? 0, row.newLine ?? 0)))).length);
+  const num = (value?: number) => (value ? String(value) : "").padStart(gutter);
+  return rows.map((row) => {
+    if (row.kind === "hunk") return fg("accent", row.text);
+    const text = truncateToWidth(safeLine(row.text), Math.max(1, width - gutter * 2 - 4));
+    const prefix = fg("dim", `${num(row.oldLine)} ${num(row.newLine)} `);
+    if (row.kind === "add") return prefix + fg("success", "+" + text);
+    if (row.kind === "remove") return prefix + fg("error", "-" + text);
+    return prefix + fg("muted", " " + text);
+  });
+}
+
+/**
+ * Review what the agent changed: files on the left, the selected diff on the right.
+ * `a` accepts (stops tracking) and `r` then `y` reverts a file; `A`/`R` apply to all.
+ */
+export async function openDiffView(ctx: ExtensionContext, tracker: ChangeTracker): Promise<void> {
+  if (!ctx.hasUI || ctx.mode !== "tui") return;
+  let changes = tracker.changes();
+  if (!changes.length) { ctx.ui.notify("pi-jar: no agent changes to review", "info"); return; }
+  await ctx.ui.custom<void>((tui, theme, _keys, done) => {
+    let selected = 0;
+    let scroll = 0;
+    let listScroll = 0;
+    let bodyRows = 0;
+    let width = 80;
+    let armed: "one" | "all" | undefined;
+    let message = "";
+    let layout = { top: 1, rows: 0, leftWidth: 0, bodyX: 2, footerTop: 0 };
+    let cache: { key: string; lines: string[] } | undefined;
+    const fg = (color: string, text: string) => theme.fg(color as never, text);
+    const refresh = () => {
+      changes = tracker.changes();
+      cache = undefined;
+      selected = Math.min(selected, Math.max(0, changes.length - 1));
+      scroll = 0;
+      if (!changes.length) done();
+    };
+    const run = (label: string, action: () => void) => {
+      try { action(); message = label; }
+      catch (error) { message = "failed: " + (error instanceof Error ? error.message : String(error)); ctx.ui.notify("pi-jar: " + message, "error"); }
+      refresh();
+    };
+    const select = (index: number) => { selected = Math.max(0, Math.min(changes.length - 1, index)); scroll = 0; };
+    const scrollBody = (delta: number) => { scroll = Math.max(0, Math.min(Math.max(0, (cache?.lines.length ?? 0) - bodyRows), scroll + delta)); };
+    const component = {
+      invalidate() { cache = undefined; },
+      handleInput(data: string) {
+        const current = changes[selected];
+        if (armed && (data === "y" || (armed === "one" && data === "r") || (armed === "all" && data === "R"))) {
+          const scope = armed; armed = undefined;
+          if (scope === "all") run(`reverted ${changes.length} file(s)`, () => { for (const change of changes) tracker.revert(change.path); });
+          else if (current) run(`reverted ${current.rel}`, () => tracker.revert(current.path));
+          tui.requestRender(); return;
+        }
+        armed = undefined;
+        if (matchesKey(data, Key.escape) || data === "q") return done();
+        if (data === "a" && current) run(`accepted ${current.rel}`, () => tracker.accept(current.path));
+        else if (data === "A") run(`accepted ${changes.length} file(s)`, () => tracker.acceptAll());
+        else if (data === "r" && current) { armed = "one"; message = `revert ${current.rel}? press r or y to confirm`; }
+        else if (data === "R") { armed = "all"; message = `revert all ${changes.length} files? press R or y to confirm`; }
+        else if (matchesKey(data, Key.up) || data === "k") select(selected - 1);
+        else if (matchesKey(data, Key.down) || data === "j") select(selected + 1);
+        else if (matchesKey(data, Key.pageDown) || data === " ") scrollBody(Math.max(1, bodyRows - 2));
+        else if (matchesKey(data, Key.pageUp)) scrollBody(-Math.max(1, bodyRows - 2));
+        else if (data === "g") scrollBody(-Infinity);
+        else if (data === "G") scrollBody(Infinity);
+        tui.requestRender();
+      },
+      handleMouse(event: TuiMouseEvent) {
+        const row = event.y - layout.top;
+        const inContent = row >= 0 && row < layout.rows;
+        const inList = layout.leftWidth > 0 && event.x < layout.leftWidth + 3;
+        if (event.type === "wheel" && event.wheelDelta) {
+          if (inContent && inList) select(selected + Math.sign(event.wheelDelta)); else scrollBody(Math.sign(event.wheelDelta) * 3);
+          tui.requestRender(); return { handled: true };
+        }
+        if (event.type !== "click" || event.button !== "left") return;
+        if (event.y === 0 && event.x >= width - 3) { done(); return { handled: true }; }
+        if (inContent && inList && listScroll + row < changes.length) { select(listScroll + row); tui.requestRender(); return { handled: true, focus: true }; }
+        const action = ACTIONS[event.y - layout.footerTop];
+        if (action) { component.handleInput(action.key); return { handled: true }; }
+      },
+      render(available: number): string[] {
+        width = Math.max(24, available);
+        bodyRows = contentRows(6 + ACTIONS.length, 6);
+        const listWidth = sidebarWidth(width, 20, 36);
+        const bodyWidth = listWidth ? width - listWidth - 6 : width - 4;
+        const current = changes[selected];
+        if (!current) return [];
+        const key = `${selected}:${bodyWidth}:${current.after.length}`;
+        if (cache?.key !== key) cache = { key, lines: renderDiff(current, bodyWidth, fg) };
+        const header = listWidth ? [] : [fg("accent", `‹ ${selected + 1}/${changes.length} ${current.rel} ›`), ""];
+        const content = [...header, ...cache.lines];
+        scroll = Math.max(0, Math.min(scroll, Math.max(0, content.length - bodyRows)));
+        if (selected < listScroll) listScroll = selected;
+        if (selected >= listScroll + bodyRows) listScroll = selected - bodyRows + 1;
+        const list = changes.slice(listScroll, listScroll + bodyRows).map((change, index) => {
+          const active = listScroll + index === selected;
+          const counts = fg("success", `+${change.added}`) + fg("error", ` −${change.removed}`);
+          const name = truncateToWidth((active ? "▌" : " ") + STATUS_MARK[change.status] + " " + change.rel, Math.max(4, listWidth - String(change.added).length - String(change.removed).length - 4));
+          return fg(active ? "accent" : "muted", name) + " " + counts;
+        });
+        const totals = changes.reduce((sum, change) => [sum[0]! + change.added, sum[1]! + change.removed], [0, 0]);
+        const title = `± CHANGES · ${changes.length} file${changes.length === 1 ? "" : "s"} · +${totals[0]} −${totals[1]}`;
+        const footer = [
+          ...optionList(theme, ACTIONS.map((item) => item.label), -1, ACTIONS.map((item) => item.key)),
+          message ? fg(armed ? "warning" : "dim", message) : fg("dim", "↑↓ file · PgUp/PgDn scroll · press a key or click an action · Esc close")
+        ];
+        const split = splitFrame(theme, width, title, list, content.slice(scroll, scroll + bodyRows), footer, bodyRows, listWidth);
+        layout = split.layout;
+        return split.lines;
+      }
+    };
+    return component;
+  }, { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%" } });
+}
+
+/** Track edit/write targets before they run, and expose `/diff` plus ctrl+alt+d. */
+export function registerChangeReview(pi: ExtensionAPI, tracker: () => ChangeTracker | undefined, changed: () => void): void {
+  pi.on("tool_call", (event) => {
+    if (event.toolName !== "edit" && event.toolName !== "write") return;
+    const path = (event.input as { path?: unknown }).path;
+    if (typeof path === "string" && path.trim()) tracker()?.capture(path);
+  });
+  pi.on("tool_result", (event) => { if (event.toolName === "edit" || event.toolName === "write") changed(); });
+  const open = async (ctx: ExtensionContext) => {
+    const current = tracker();
+    if (!current) return;
+    try { await openDiffView(ctx, current); }
+    catch (error) { ctx.ui.notify("pi-jar: " + String(error), "error"); }
+    changed();
+  };
+  pi.registerCommand("diff", { description: "Review, accept or revert the files the agent changed", handler: async (_args, ctx) => open(ctx) });
+  pi.registerShortcut?.(Key.ctrlAlt("d"), { description: "Review agent changes (pi-jar)", handler: async (ctx) => open(ctx) });
+}