@vincemakes/kiso-code 0.1.15 → 0.1.16

package/dist/body.d.ts

@@ -39,6 +39,9 @@ export type BodyCell = {
     state: "pending" | "approval" | "running" | "done";
     isError: boolean;
     resultText: string;
+    diff: import("./diff.js").DiffLine[] | null;
+    added: number;
+    removed: number;
     startedAt: number | null;
     doneAt: number | null;
     done: boolean;
@@ -96,7 +99,7 @@ export declare class Body {
     thinkingAppend(text: string): void;
     thinkingEnd(): void;
     toolStart(name: string, callId: string, input: Record<string, unknown>): void;
-    toolApproval(callId: string): void;
+    toolApproval(callId: string, diff: import("./diff.js").DiffResult | null): void;
     toolRunning(callId: string): void;
     toolSucceeded(callId: string): void;
     toolFailed(callId: string, error: string): void;

package/dist/body.js

@@ -23,6 +23,7 @@
  * NoticeCell / raw block) — deliberately NOT pi's Component interface
  * shape (ADR-0040).
  */
+import { truncateDiff } from "./diff.js";
 import { displayWidth } from "./editor.js";
 import { escapeTerminal, foldResult, foldThinking, palette, renderTerminalGap, renderToolSummary, } from "./render.js";
 /** The spinner glyphs, cycled by the heartbeat. */
@@ -35,7 +36,7 @@ export class Body {
     #opts;
     #cells = [];
     #nextFrozen = 0; // index of the first not-yet-printed cell
-    #frozenRows = 0; // rows of the region occupied by printed cells
+    #frozenRows = 0; // the frozen area's rows filled WITHOUT scrolling (then the real LFs take over)
     #oldTailTop = 0; // the tail's previous first row — for the clear pass
     #frameTimer = null;
     #heartbeat = null;
@@ -90,11 +91,13 @@ export class Body {
     userLine(text) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
+            this.#closeOpenText();
             const p = palette();
             this.#write(`${p.blue}you> ${escapeTerminal(text)}${p.reset}\n`);
             return;
         }
         this.#closeOpenThinking();
+        this.#closeOpenText();
         this.#cells.push({ kind: "user", text, done: true });
         this.#mark();
     }
@@ -129,19 +132,27 @@ export class Body {
         this.#pendingCalls.set(callId, { name, input, result: { content: "", isError: false } });
         if (!this.#isActive()) {
             this.#closeOpenThinking();
+            this.#closeOpenText();
             process.stdout.write(`→ ${escapeTerminal(name)}(${escapeTerminal(JSON.stringify(input).slice(0, 200))})\n`);
             return;
         }
         this.#toolCells.set(callId, this.#cells.length);
-        this.#cells.push({ kind: "tool", name, input: summary, state: "pending", isError: false, resultText: "", startedAt: null, doneAt: null, done: false });
+        this.#cells.push({ kind: "tool", name, input: summary, state: "pending", isError: false, resultText: "", diff: null, added: 0, removed: 0, startedAt: null, doneAt: null, done: false });
         this.#mark();
     }
-    toolApproval(callId) {
+    toolApproval(callId, diff) {
         if (!this.#isActive())
             return;
         const cell = this.#toolCell(callId);
-        if (cell !== null && cell.kind === "tool" && !cell.done)
+        if (cell !== null && cell.kind === "tool" && !cell.done) {
             cell.state = "approval";
+            // v2e: the mini-diff renders BELOW the tool line at the approval
+            // moment — the human sees the change before deciding. Auto-allowed
+            // tools pass null (nobody is looking — no diff, no cost).
+            cell.diff = diff === null ? null : truncateDiff(diff.lines);
+            cell.added = diff?.added ?? 0;
+            cell.removed = diff?.removed ?? 0;
+        }
         this.#mark();
     }
     toolRunning(callId) {
@@ -196,6 +207,7 @@ export class Body {
     textAppend(text) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
+            this.#closeOpenText();
             process.stdout.write(escapeTerminal(text));
             return;
         }
@@ -205,6 +217,7 @@ export class Body {
         }
         else {
             this.#closeOpenThinking();
+            this.#closeOpenText();
             this.#cells.push({ kind: "text", text, done: false });
         }
         this.#mark();
@@ -223,21 +236,25 @@ export class Body {
     terminal(label, statusLine) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
+            this.#closeOpenText();
             // the v2c bytes: the terminal label (\ndone\n) + the status gap.
             process.stdout.write(label + renderTerminalGap(statusLine));
             return;
         }
         this.#closeOpenThinking();
+        this.#closeOpenText();
         this.#cells.push({ kind: "terminal", label: label.trim(), line: statusLine, done: true });
         this.#mark();
     }
     notice(text) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
+            this.#closeOpenText();
             process.stdout.write(`${text}\n`);
             return;
         }
         this.#closeOpenThinking();
+        this.#closeOpenText();
         this.#cells.push({ kind: "notice", text, done: true });
         this.#mark();
     }
@@ -246,11 +263,13 @@ export class Body {
     raw(lines) {
         if (!this.#isActive()) {
             this.#closeOpenThinking();
+            this.#closeOpenText();
             for (const line of lines)
                 process.stdout.write(`${line}\n`);
             return;
         }
         this.#closeOpenThinking();
+        this.#closeOpenText();
         this.#cells.push({ kind: "raw", lines, done: true });
         this.#mark();
     }
@@ -280,34 +299,47 @@ export class Body {
             return;
         const H = this.#opts.height();
         const W = this.#opts.width();
-        const regionBottom = H - 3;
-        if (regionBottom < 1)
+        if (H < 4)
             return;
         const out = [];
-        out.push("\x1b[?2026h");
-        // 1. freeze completed cells — print their final form at the frozen
-        // area's next rows. The terminal scrolls the region when full.
-        while (this.#nextFrozen < this.#cells.length && this.#cells[this.#nextFrozen].done) {
-            const cell = this.#cells[this.#nextFrozen];
-            const lines = this.#cellLines(cell, W);
-            for (const line of lines) {
-                const row = Math.min(this.#frozenRows + 1, regionBottom);
-                out.push(`\x1b[${row};1H\x1b[0K${line}`);
-                if (this.#frozenRows + 1 > regionBottom) {
-                    out.push("\n"); // the region scrolls — the frozen rows shift up
+        // #13 (P1), v2d-B: NO DECSTBM — overflow scrolls with a REAL LF at
+        // the screen's last row, so the frozen lines enter the terminal's
+        // NATIVE scrollback deterministically (region-scrolled lines are
+        // terminal-dependent; some terminals drop them — the measured v2d-A
+        // defect). The body fills from the top without scrolling; once full,
+        // every new frozen line scrolls the whole screen (\x1b[H;1H\n — the
+        // top line leaves into the scrollback) and lands at the body's
+        // bottom row, just above the active tail. The dock is redrawn after.
+        // The tail (the remaining ACTIVE cells) and its geometry — computed
+        // FIRST from the final nextFrozen, so the frozen cells are NOT in it
+        // (a stale tail would re-draw them — the double-render).
+        let nextFrozen = this.#nextFrozen;
+        while (nextFrozen < this.#cells.length && this.#cells[nextFrozen].done)
+            nextFrozen += 1;
+        const tail = this.#cells.slice(nextFrozen);
+        const tailHeight = tail.reduce((n, c) => n + this.#cellHeight(c, W), 0);
+        const tailTop = Math.max(1, H - 2 - tailHeight);
+        const writeRow = Math.max(1, tailTop - 1); // the frozen area's bottom row
+        let scrolled = 0;
+        for (let i = this.#nextFrozen; i < nextFrozen; i += 1) {
+            for (const line of this.#cellLines(this.#cells[i], W)) {
+                if (this.#frozenRows < writeRow) {
+                    this.#frozenRows += 1;
+                    out.push(`\x1b[${this.#frozenRows};1H\x1b[0K${line}`);
                 }
                 else {
-                    this.#frozenRows += 1;
+                    out.push(`\x1b[${H};1H\n`); // the REAL LF — the whole screen scrolls
+                    out.push(`\x1b[${writeRow};1H\x1b[0K${line}`);
+                    scrolled += 1;
                 }
             }
             this.#nextFrozen += 1;
         }
-        // 2. the active tail — clear its old area, draw the cells.
-        const tail = this.#cells.slice(this.#nextFrozen);
-        const tailHeight = tail.reduce((n, c) => n + this.#cellHeight(c, W), 0);
-        const tailTop = Math.max(1, regionBottom - tailHeight + 1);
-        const clearFrom = Math.min(this.#oldTailTop === 0 ? tailTop : this.#oldTailTop, tailTop);
-        for (let row = clearFrom; row <= regionBottom; row += 1) {
+        // 2. the active tail — clear its old area (shifted up by the freeze
+        // scrolls) and the current area, draw the cells at the body's bottom.
+        out.push("\x1b[?2026h");
+        const clearFrom = Math.min(this.#oldTailTop === 0 ? tailTop : this.#oldTailTop - scrolled, tailTop);
+        for (let row = clearFrom; row <= H - 3; row += 1) {
             out.push(`\x1b[${row};1H\x1b[0K`);
         }
         let row = tailTop;
@@ -317,11 +349,13 @@ export class Body {
                 row += 1;
             }
         }
-        this.#oldTailTop = tailTop;
         // 3. the cursor home — the input line's edit column.
         out.push(`\x1b[${H};${this.#opts.editCol()}H`);
         out.push("\x1b[?2026l");
         this.#write(out.join(""));
+        // 4. the dock rows — the freeze scrolls shifted them; redraw (the
+        // dock's own redraw re-pins the cursor at the edit position).
+        this.#opts.onDock?.();
     }
     // ---- cell → lines ----
     #cellLines(cell, W) {
@@ -345,10 +379,25 @@ export class Body {
                         const err = escapeTerminal(cell.resultText.split("\n")[0].slice(0, 60));
                         return [`${p.red}✗ ${name} (${err}, ${elapsed}s)${p.reset}`];
                     }
-                    return [`${p.blue}✓ ${name}${p.reset} (${summary}, ${elapsed}s)`];
+                    const delta = cell.added + cell.removed > 0 ? `, +${cell.added} -${cell.removed}` : "";
+                    return [`${p.blue}✓ ${name}${p.reset} (${summary}${delta}, ${elapsed}s)`];
+                }
+                if (cell.state === "approval") {
+                    const lines = [`→ ${name} ${summary} ${p.blue}⏸${p.reset}`];
+                    // v2e: the mini-diff — ▎ blue edge (the brick motif), - red /
+                    // + green / context dim; NO_COLOR keeps the ± prefixes plain.
+                    if (cell.diff !== null) {
+                        for (const d of cell.diff) {
+                            const body = d.kind === "-"
+                                ? `${p.red}- ${escapeTerminal(d.text)}${p.reset}`
+                                : d.kind === "+"
+                                    ? `${p.green}+ ${escapeTerminal(d.text)}${p.reset}`
+                                    : `${p.dim}  ${escapeTerminal(d.text)}${p.reset}`;
+                            lines.push(`${p.blue}▎${p.reset}${body}`);
+                        }
+                    }
+                    return lines;
                 }
-                if (cell.state === "approval")
-                    return [`→ ${name} ${summary} ${p.blue}⏸${p.reset}`];
                 if (cell.state === "running") {
                     const elapsed = cell.startedAt !== null ? Math.max(1, Math.round((Date.now() - cell.startedAt) / 1000)) : 1;
                     return [`→ ${name} ${summary} ${p.blue}${SPINNER[this.#spinnerI % SPINNER.length]}${p.reset} ${elapsed}s`];
@@ -401,6 +450,16 @@ export class Body {
         const i = this.#toolCells.get(callId);
         return i === undefined ? null : (this.#cells[i] ?? null);
     }
+    /** Close an open TEXT cell when a new cell starts — the runtime emits
+     *  no text_end (it is an adapter-level event), so the stream's next
+     *  cell is the close signal; without it the freeze blocks behind the
+     *  open text and everything after it re-renders in the tail forever
+     *  (the #13 flood reproduced the overwrite). */
+    #closeOpenText() {
+        const last = this.#cells[this.#cells.length - 1];
+        if (last !== undefined && last.kind === "text" && !last.done)
+            last.done = true;
+    }
     /** Close an open thinking cell when a new cell starts (the block's
      *  fold freezes at the transition). */
     #closeOpenThinking() {

package/dist/diff.d.ts

@@ -0,0 +1,32 @@
+/**
+ * v2e — the diff renderer: edit/write changes as inline ± lines, zero
+ * dependencies, no syntax highlighting (the spec's scope line). Shown at
+ * the approval moment ONLY — the frozen summary stays one line (v2d's
+ * anti-leak principle), /last has the full data.
+ *
+ * edit_file diffs IN PLACE (the search→replace windows are known — no
+ * general engine needed); write_file does a row-level LCS over the old
+ * file (small files are the target). Context: 2 rows each side. The
+ * RENDERER truncates (18 head + 18 tail + "… N lines"); the stats come
+ * from the full diff.
+ */
+/** The diff block's per-row kind. */
+export type DiffLine = {
+    kind: "-" | "+" | " ";
+    text: string;
+};
+export interface DiffResult {
+    /** The FULL diff (with context, not truncated) — the display truncates. */
+    lines: DiffLine[];
+    added: number;
+    removed: number;
+}
+/** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
+export declare function truncateDiff(diff: DiffLine[]): DiffLine[];
+/** edit_file: the search→replace windows replace in place — the changed
+ *  region is KNOWN, so the diff is the old window vs the new window,
+ *  context from the surrounding file. */
+export declare function editFileDiff(oldContent: string, search: string, replace: string): DiffResult;
+/** write_file: a new file is all +; an existing file diffs row-level
+ *  against its old content. */
+export declare function writeFileDiff(oldContent: string | null, newContent: string): DiffResult;

package/dist/diff.js

@@ -0,0 +1,122 @@
+/**
+ * v2e — the diff renderer: edit/write changes as inline ± lines, zero
+ * dependencies, no syntax highlighting (the spec's scope line). Shown at
+ * the approval moment ONLY — the frozen summary stays one line (v2d's
+ * anti-leak principle), /last has the full data.
+ *
+ * edit_file diffs IN PLACE (the search→replace windows are known — no
+ * general engine needed); write_file does a row-level LCS over the old
+ * file (small files are the target). Context: 2 rows each side. The
+ * RENDERER truncates (18 head + 18 tail + "… N lines"); the stats come
+ * from the full diff.
+ */
+/** A line-level LCS diff — the classic two-row DP, ~small inputs. */
+function lcsDiff(oldLines, newLines) {
+    const n = oldLines.length;
+    const m = newLines.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            dp[i][j] = oldLines[i] === newLines[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (oldLines[i] === newLines[j]) {
+            out.push({ kind: " ", text: oldLines[i] });
+            i += 1;
+            j += 1;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            out.push({ kind: "-", text: oldLines[i] });
+            i += 1;
+        }
+        else {
+            out.push({ kind: "+", text: newLines[j] });
+            j += 1;
+        }
+    }
+    while (i < n) {
+        out.push({ kind: "-", text: oldLines[i] });
+        i += 1;
+    }
+    while (j < m) {
+        out.push({ kind: "+", text: newLines[j] });
+        j += 1;
+    }
+    return out;
+}
+/** Keep 2 context rows around each change — the unified-style window. */
+function withContext(diff) {
+    const out = [];
+    let lastAdded = -10;
+    for (let k = 0; k < diff.length; k += 1) {
+        if (diff[k].kind === " ")
+            continue;
+        const from = Math.max(0, k - 2);
+        const to = Math.min(diff.length - 1, k + 2);
+        for (let c = from; c <= to; c += 1) {
+            if (c > lastAdded) {
+                out.push(diff[c]);
+                lastAdded = c;
+            }
+        }
+        lastAdded = to;
+    }
+    return out;
+}
+const MAX_DIFF_LINES = 40; // the RENDERED cap
+const TRUNCATE_KEEP = 18;
+/** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
+export function truncateDiff(diff) {
+    if (diff.length <= MAX_DIFF_LINES)
+        return diff;
+    const omitted = diff.length - 2 * TRUNCATE_KEEP;
+    return [
+        ...diff.slice(0, TRUNCATE_KEEP),
+        { kind: " ", text: `… ${omitted} lines (/last for full)` },
+        ...diff.slice(diff.length - TRUNCATE_KEEP),
+    ];
+}
+function stats(diff) {
+    let added = 0;
+    let removed = 0;
+    for (const d of diff) {
+        if (d.kind === "+")
+            added += 1;
+        else if (d.kind === "-")
+            removed += 1;
+    }
+    return { added, removed };
+}
+/** edit_file: the search→replace windows replace in place — the changed
+ *  region is KNOWN, so the diff is the old window vs the new window,
+ *  context from the surrounding file. */
+export function editFileDiff(oldContent, search, replace) {
+    const oldLines = oldContent.split("\n");
+    const searchLines = search.split("\n");
+    const replaceLines = replace.split("\n");
+    // Locate the search window (the first occurrence — the edit tool's own
+    // semantics); no occurrence → the whole file is the old side.
+    let at = -1;
+    for (let i = 0; i + searchLines.length <= oldLines.length; i += 1) {
+        if (oldLines.slice(i, i + searchLines.length).join("\n") === search) {
+            at = i;
+            break;
+        }
+    }
+    const lines = at < 0 ? withContext(lcsDiff(oldLines, replaceLines)) : withContext(lcsDiff(oldLines, [...oldLines.slice(0, at), ...replaceLines, ...oldLines.slice(at + searchLines.length)]));
+    return { lines, ...stats(lines) };
+}
+/** write_file: a new file is all +; an existing file diffs row-level
+ *  against its old content. */
+export function writeFileDiff(oldContent, newContent) {
+    if (oldContent === null) {
+        const lines = newContent.split("\n").map((text) => ({ kind: "+", text }));
+        return { lines, added: lines.length, removed: 0 };
+    }
+    const lines = withContext(lcsDiff(oldContent.split("\n"), newContent.split("\n")));
+    return { lines, ...stats(lines) };
+}

package/dist/dock.d.ts

@@ -27,7 +27,11 @@ export declare class Dock {
         line: string;
         cursor: number;
     }, prompt: string): void;
-    /** Enter docked mode: DECSTBM the scroll region, draw the chrome. A
+    /** Enter docked mode: draw the chrome. #13 (P1): the DECSTBM scroll
+     *  region is GONE — v2d-B (ADR-0040): the body uses plain LF scrolling
+     *  so frozen lines enter the native scrollback deterministically
+     *  (region-scrolled lines are terminal-dependent — some terminals drop
+     *  them). The dock rows are redrawn by the body after every scroll. A
      *  TTY without a real window size (rows < 4) stays in the v2a line
      *  mode — the bottom three rows need room to exist. */
     enter(): void;
@@ -36,21 +40,8 @@ export declare class Dock {
      *  from main's finally on EVERY exit path (kill -9 excepted — README:
      *  `reset` saves it). */
     exit(): void;
-    /** SIGWINCH: recompute the region, redraw the chrome. */
+    /** SIGWINCH: recompute the size, redraw the chrome. */
     onResize(): void;
-    /** Body output: position the cursor inside the scroll region at the
-     *  body's tracked position, write, and hand the cursor back to the
-     *  input line's EDIT position. The row/col tracking is approximate for
-     *  width-wrapped and wide-char lines (documented) — the region clamp
-     *  keeps the bottom rows safe regardless.
-     *
-     *  The edit-position return is a correctness requirement, not
-     *  cosmetics: readline tracks its cursor internally and NEVER
-     *  re-syncs after an external move — a body write that left the
-     *  cursor at column 1 made the next keystroke overwrite the prompt
-     *  (probe-confirmed; the dock's redraw self-repaired ~200ms later,
-     *  which read the user as cursor drift). */
-    writeBody(text: string): void;
     /** The input line's edit column — prompt width + cursor + 1. The
      *  dock's redraw and the body's cursor return both end here, so the
      *  ACTUAL cursor always equals what the editor tracks. The width is

package/dist/dock.js

@@ -41,7 +41,11 @@ export class Dock {
         this.#inputState = state;
         this.#inputPrompt = prompt;
     }
-    /** Enter docked mode: DECSTBM the scroll region, draw the chrome. A
+    /** Enter docked mode: draw the chrome. #13 (P1): the DECSTBM scroll
+     *  region is GONE — v2d-B (ADR-0040): the body uses plain LF scrolling
+     *  so frozen lines enter the native scrollback deterministically
+     *  (region-scrolled lines are terminal-dependent — some terminals drop
+     *  them). The dock rows are redrawn by the body after every scroll. A
      *  TTY without a real window size (rows < 4) stays in the v2a line
      *  mode — the bottom three rows need room to exist. */
     enter() {
@@ -53,7 +57,6 @@ export class Dock {
         this.#width = process.stdout.columns ?? 80;
         this.#bodyRow = 1;
         this.#bodyCol = 1;
-        process.stdout.write(`\x1b[1;${this.#height - 3}r`); // scroll region: top .. H-3
         this.redraw();
         this.#resizeHandler = () => this.onResize();
         process.stdout.on("resize", this.#resizeHandler);
@@ -77,47 +80,14 @@ export class Dock {
         }
         process.stdout.write(`\x1b[${H};1H`);
     }
-    /** SIGWINCH: recompute the region, redraw the chrome. */
+    /** SIGWINCH: recompute the size, redraw the chrome. */
     onResize() {
         if (!this.#active)
             return;
         this.#height = process.stdout.rows ?? this.#height;
         this.#width = process.stdout.columns ?? this.#width;
-        process.stdout.write(`\x1b[1;${this.#height - 3}r`);
         this.redraw();
     }
-    /** Body output: position the cursor inside the scroll region at the
-     *  body's tracked position, write, and hand the cursor back to the
-     *  input line's EDIT position. The row/col tracking is approximate for
-     *  width-wrapped and wide-char lines (documented) — the region clamp
-     *  keeps the bottom rows safe regardless.
-     *
-     *  The edit-position return is a correctness requirement, not
-     *  cosmetics: readline tracks its cursor internally and NEVER
-     *  re-syncs after an external move — a body write that left the
-     *  cursor at column 1 made the next keystroke overwrite the prompt
-     *  (probe-confirmed; the dock's redraw self-repaired ~200ms later,
-     *  which read the user as cursor drift). */
-    writeBody(text) {
-        if (!this.#active) {
-            process.stdout.write(text);
-            return;
-        }
-        const row = Math.min(this.#bodyRow, this.#height - 3);
-        const col = this.#bodyCol > this.#width ? this.#width : this.#bodyCol;
-        process.stdout.write(`\x1b[${row};${col}H`);
-        process.stdout.write(text);
-        for (const ch of text) {
-            if (ch === "\n") {
-                this.#bodyRow += 1;
-                this.#bodyCol = 1;
-            }
-            else {
-                this.#bodyCol += 1;
-            }
-        }
-        process.stdout.write(`\x1b[${this.#height};${this.#inputCol()}H`); // back to the edit position
-    }
     /** The input line's edit column — prompt width + cursor + 1. The
      *  dock's redraw and the body's cursor return both end here, so the
      *  ACTUAL cursor always equals what the editor tracks. The width is

package/dist/index.js

@@ -18,6 +18,8 @@
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { createInterface } from "node:readline";
 import { Body } from "./body.js";
+import { editFileDiff, writeFileDiff } from "./diff.js";
+import { MODES, getMode, modeExtensions, modeFromEnv, modeSystemPrompt, setMode } from "./mode.js";
 import { Editor, PROMPT as EDITOR_PROMPT } from "./editor.js";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
@@ -27,17 +29,6 @@ import { createFauxProvider } from "@vincemakes/kiso-evals";
 import { createCodingTools } from "@vincemakes/kiso-tools-node";
 import { escapeTerminal, foldResult, foldThinking, palette, renderEvent, renderSessionLine, renderStatusLine, renderTerminalGap, renderToolSummary, } from "./render.js";
 import { Dock } from "./dock.js";
-const PERMISSION_POLICY = {
-    rules: [
-        { tool: "read_file", action: "allow" },
-        { tool: "list_dir", action: "allow" },
-        { tool: "search_text", action: "allow" },
-        { tool: "write_file", action: "defer" },
-        { tool: "edit_file", action: "defer" },
-        { tool: "shell", action: "defer" },
-    ],
-    default: "deny",
-};
 /** 发现#11: KISO_HOME is the ONE root — every default path derives from
  *  it (sessions, trust, extensions, mcp config, skills). The dedicated
  *  env vars (KISO_EXTENSIONS_DIR / KISO_MCP_CONFIG / KISO_SKILLS_DIR)
@@ -260,6 +251,21 @@ function bannerExtensionText() {
         parts.push(`project: ${projectExtensions.map((e) => e.name).join(", ")}`);
     return ` · [${total} extension${total === 1 ? "" : "s"}: ${parts.join(" · ")}]`;
 }
+/** Modes: the status-bar indicator — the default tier shows nothing; the
+ *  others show their blue name, the dangerous ones (plan/bypass) with the
+ *  ⚠ prefix. */
+function modeStatusText() {
+    if (getMode() === "default")
+        return "";
+    const p = palette();
+    const danger = getMode() === "plan" || getMode() === "bypass" ? "⚠ " : "";
+    return `${p.blue}${danger}${getMode()}${p.reset}`;
+}
+/** Modes: append the mode indicator to a composed status base. */
+function statusWithMode(base) {
+    const mode = modeStatusText();
+    return mode === "" ? base : `${base} · ${mode}`;
+}
 /** E1: the startup banner line(s) — TTY: logo + merged extensions; off-TTY:
  *  the historical `[N extensions: ...]` standalone line (zero change). */
 function extensionsBanner() {
@@ -518,15 +524,26 @@ async function makeAgent(fauxSkipTurns = 0, input) {
         // Area 5: the coding tools are bound to the workspace — every path
         // they touch is canonicalized inside cwd, escapes are refused.
         tools: [...createCodingTools({ workspaceRoot: process.cwd() })],
-        permissionPolicy: PERMISSION_POLICY,
-        systemPrompt: composeSystemPrompt(process.cwd()),
+        // Modes: the five tiers ride the E1 policy chain (mode:<tier>
+        // extensions, current tier first) — the old static PERMISSION_POLICY
+        // is gone, its semantics live in the "default" tier. The banner
+        // still counts loadedExtensions only — the modes are in-process,
+        // never a file extension.
+        systemPrompt: (() => {
+            const sp = composeSystemPrompt(process.cwd());
+            const extra = modeSystemPrompt();
+            return extra === undefined ? sp : `${sp}\n\n${extra}`;
+        })(),
         // C 区: microcompact is ON by default in the product — threshold =
         // half the model window (KISO_CONTEXT_WINDOW override included;
         // 200k window → 100k tokens). Long sessions compact old read/list/
         // search/shell outputs instead of silently growing past the window.
         microcompact: { thresholdTokens: contextWindowTokens() / 2 },
         maxTurns: 20,
-        extensions: loadedExtensions,
+        // Modes: the five tiers join at the CHAIN HEAD, before the user/
+        // project extensions (the deny>ask>allow composition keeps a user
+        // deny winning over any mode tier — bypass included).
+        extensions: [...modeExtensions(), ...loadedExtensions],
         ...(provider !== undefined
             ? {
                 provider,
@@ -699,6 +716,38 @@ const DEFAULT_CONTEXT_WINDOW = 200_000;
  * line's form; `liveInput` (non-null only in interactive chat) carries the
  * last line THIS process's readline consumed — the double-echo filter.
  */
+/** v2e: the approval-moment mini-diff — edit_file/write_file changes as
+ *  ± lines; other tools get null (no diff, no cost). The file read is
+ *  best-effort: an unreadable file yields NO diff, never a failure —
+ *  the diff must never break the approval. */
+function approvalDiff(name, input) {
+    if (name !== "edit_file" && name !== "write_file")
+        return null;
+    const path = typeof input.path === "string" ? input.path : "";
+    if (path === "")
+        return null;
+    let oldContent = null;
+    try {
+        oldContent = readFileSync(path, "utf8");
+    }
+    catch {
+        // a new write_file target (or an unreadable one) — all + degrades
+    }
+    try {
+        if (name === "edit_file") {
+            const search = typeof input.search === "string" ? input.search : "";
+            const replace = typeof input.replace === "string" ? input.replace : "";
+            if (search === "")
+                return null;
+            return editFileDiff(oldContent ?? "", search, replace);
+        }
+        const content = typeof input.content === "string" ? input.content : "";
+        return writeFileDiff(oldContent, content);
+    }
+    catch {
+        return null; // never let the diff break the approval
+    }
+}
 async function consumeRun(session, run, input, turnNo, faux, liveInput, statusCb) {
     let last;
     let usage = { in: null, out: null, cache: null, known: false };
@@ -762,9 +811,12 @@ async function consumeRun(session, run, input, turnNo, faux, liveInput, statusCb
                 case "permission_requested": {
                     // v2d: the ToolCell shows the ⏸ badge; the question takes over
                     // the dock status position; the answer lands at the input line.
-                    body.toolApproval(ev.callId);
-                    const decisionId = ev.decisionId;
+                    // v2e: the mini-diff for edit/write at the approval moment —
+                    // the human sees the change BEFORE deciding (auto-allowed tools
+                    // skip the diff: nobody is looking).
                     const name = ev.name;
+                    body.toolApproval(ev.callId, approvalDiff(name, ev.input ?? {}));
+                    const decisionId = ev.decisionId;
                     const answer = await ask(input, `approve ${escapeTerminal(name)}? (y/n) `);
                     if (answer === CANCELLED) {
                         // 十: a cancellation is a CONSERVATIVE denial, explicitly
@@ -777,6 +829,7 @@ async function consumeRun(session, run, input, turnNo, faux, liveInput, statusCb
                     break;
                 }
                 case "terminal":
+                    statusCb?.(usage, estimateCtxRatio(session));
                     statusCb?.(usage, estimateCtxRatio(session));
                     // v2a rhythm: the honest label (\ndone\n — the completed
                     // marker), the status line hugging it, then EXACTLY one blank
@@ -925,13 +978,20 @@ async function chat(session, faux, input) {
     // v2c: turns submitted while another runs are QUEUED on the chain — the
     // live count rides the status bar (+N queued).
     let queued = 0;
-    // v2b: the live status bar (docked only).
+    // v2b: the live status bar (docked only). Modes: /mode switches repaint
+    // it immediately through paintStatus (the last turn stats are kept).
+    let statusSt = null;
     const statusCb = (u, ctx) => {
         if (!dock.active)
             return;
-        const st = renderStatusLine(turnNo, u, ctx, faux);
-        const base = st === null ? `${session.id} · ${agentModel}` : `${session.id} · ${agentModel} · ${st}`;
-        dock.setStatus(queued > 0 ? `${base} · +${queued} queued` : base);
+        statusSt = renderStatusLine(turnNo, u, ctx, faux);
+        paintStatus();
+    };
+    const paintStatus = () => {
+        if (!dock.active)
+            return;
+        const base = statusSt === null ? `${session.id} · ${agentModel}` : `${session.id} · ${agentModel} · ${statusSt}`;
+        dock.setStatus(`${statusWithMode(base)}${queued > 0 ? ` · +${queued} queued` : ""}`);
     };
     // The ONE dispatcher: slash commands, exit, and turns. The recovery
     // replay routes through it too — a queued "/last" must never become a
@@ -949,6 +1009,7 @@ async function chat(session, faux, input) {
                 bodyLog(cmd("/think", "show the last full thinking block"));
                 bodyLog(cmd("/last", "show the most recent tool call's input and output"));
                 bodyLog(cmd("/status", "show session id, event count, and context estimate"));
+                bodyLog(cmd("/mode", "show the approval tier; /mode <name> switches (manual/default/accept-edits/plan/bypass)"));
                 bodyLog(cmd("exit", "leave the session"));
                 input.prompt();
             });
@@ -1002,6 +1063,29 @@ async function chat(session, faux, input) {
             });
             return;
         }
+        if (trimmed === "/mode" || trimmed.startsWith("/mode ")) {
+            // Modes: /mode alone prints the current tier + the list;
+            // /mode <name> switches — the notice cell leaves the audit
+            // line in the body, the status bar repaints at once.
+            chain = chain.then(async () => {
+                const m = MODES.find((x) => x === trimmed.slice(5).trim());
+                if (trimmed.slice(5).trim() === "") {
+                    bodyLog(`mode ${getMode()}`);
+                    bodyLog(`tiers: ${MODES.join(" ")}`);
+                }
+                else if (m === undefined) {
+                    bodyLog(`no such mode: ${trimmed.slice(5).trim()}`);
+                    bodyLog(`tiers: ${MODES.join(" ")}`);
+                }
+                else {
+                    setMode(m);
+                    body.notice(`mode → ${m}`);
+                    paintStatus();
+                }
+                input.prompt();
+            });
+            return;
+        }
         if (trimmed === "exit" || trimmed === "") {
             input.close();
             return;
@@ -1068,7 +1152,8 @@ async function resume(session, prompt, faux, input) {
         if (!dock.active)
             return;
         const st = renderStatusLine(turnNo, u, ctx, faux);
-        dock.setStatus(st === null ? `${session.id} · ${agentModel}` : `${session.id} · ${agentModel} · ${st}`);
+        const base = st === null ? `${session.id} · ${agentModel}` : `${session.id} · ${agentModel} · ${st}`;
+        dock.setStatus(statusWithMode(base));
     };
     const withRun = async (run) => {
         currentRun = run;
@@ -1127,7 +1212,24 @@ async function resume(session, prompt, faux, input) {
     }
 }
 async function main() {
-    const [command, arg] = process.argv.slice(2);
+    // Modes: --mode <name> wins over KISO_MODE — both applied before the
+    // first makeAgent (the tier extensions read `current` live). The flag
+    // is stripped from the positional args, so it works in any position.
+    const args = process.argv.slice(2);
+    const modeFlag = args.indexOf("--mode");
+    if (modeFlag !== -1) {
+        const m = MODES.find((x) => x === args[modeFlag + 1]);
+        if (m === undefined) {
+            console.error(`unknown mode: ${args[modeFlag + 1]} (tiers: ${MODES.join(", ")})`);
+            process.exit(2);
+        }
+        setMode(m);
+        args.splice(modeFlag, 2);
+    }
+    else {
+        setMode(modeFromEnv());
+    }
+    const [command, arg] = args;
     // 八: faux mode is the keyless demo script — an exhausted script must
     // exit non-zero, never masquerade as a successful provider run.
     const faux = process.env.ANTHROPIC_API_KEY === undefined && process.env.OPENAI_API_KEY === undefined;
@@ -1144,6 +1246,7 @@ async function main() {
         height: () => process.stdout.rows ?? 24,
         width: () => process.stdout.columns ?? 80,
         editCol: () => dock.editCol(),
+        onDock: () => dock.redraw(), // v2d-B: the freeze scrolls the dock up — re-pin it
     });
     try {
         switch (command) {

package/dist/mode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Modes — the five built-in approval tiers, built ON the E1 policy chain
+ * (the kernel is untouched). Each tier is an in-process "mode:<name>"
+ * extension whose decide() is live — it only speaks when it is the
+ * CURRENT tier (otherwise abstain = no opinion, ADR-0042), so /mode
+ * switches take effect immediately. The extension NAME rides the runtime's decidedBy
+ * field: an automated denial records decidedBy: "mode:<name>" — the
+ * audit sell. User-level extensions stay on the chain AFTER the mode
+ * tiers; a user deny always wins (the chain's deny>ask>allow
+ * monotonicity — bypass cannot override an extension deny).
+ */
+import type { KisoExtension } from "@vincemakes/kiso-runtime";
+export type Mode = "manual" | "default" | "accept-edits" | "plan" | "bypass";
+export declare const MODES: readonly Mode[];
+export declare function getMode(): Mode;
+export declare function setMode(m: Mode): void;
+/** The startup mode: KISO_MODE env (or the --mode flag — the CLI applies
+ *  it before the first makeAgent). */
+export declare function modeFromEnv(): Mode;
+/** The five built-in mode tiers as chain extensions — named "mode:<tier>"
+ *  so the runtime's decidedBy records exactly that (the runtime derives
+ *  approvalPolicies from extensions[].approvals, tagging each with the
+ *  extension name). The CURRENT tier is first: an all-allow chain records
+ *  decidedBy = the FIRST SPEAKER, so an auto-allow under the startup mode
+ *  names that mode honestly. Order never affects verdicts — the chain is
+ *  deny>ask>allow over the SPEAKING verdicts (abstain = no opinion), so a
+ *  user extension's deny wins over any mode tier, bypass included (the
+ *  monotonicity e2e pins it). */
+export declare function modeExtensions(): readonly KisoExtension[];
+/** The plan tier's system prompt addition — injected at startup when the
+ *  initial mode is plan (the session prompt is fixed at creation; runtime
+ *  switches are guided by the deny reason). */
+export declare function modeSystemPrompt(): string | undefined;

package/dist/mode.js

@@ -0,0 +1,93 @@
+/**
+ * Modes — the five built-in approval tiers, built ON the E1 policy chain
+ * (the kernel is untouched). Each tier is an in-process "mode:<name>"
+ * extension whose decide() is live — it only speaks when it is the
+ * CURRENT tier (otherwise abstain = no opinion, ADR-0042), so /mode
+ * switches take effect immediately. The extension NAME rides the runtime's decidedBy
+ * field: an automated denial records decidedBy: "mode:<name>" — the
+ * audit sell. User-level extensions stay on the chain AFTER the mode
+ * tiers; a user deny always wins (the chain's deny>ask>allow
+ * monotonicity — bypass cannot override an extension deny).
+ */
+export const MODES = ["manual", "default", "accept-edits", "plan", "bypass"];
+/** The read-only tool set (plan): reading is allowed, everything else
+ *  denied with the guiding reason. */
+const READ_TOOLS = new Set(["read_file", "list_dir", "search_text", "read_skill"]);
+let current = "default";
+export function getMode() {
+    return current;
+}
+export function setMode(m) {
+    current = m;
+}
+/** The startup mode: KISO_MODE env (or the --mode flag — the CLI applies
+ *  it before the first makeAgent). */
+export function modeFromEnv() {
+    const raw = process.env.KISO_MODE;
+    const m = MODES.find((x) => x === raw);
+    return m ?? "default";
+}
+/** The per-tier verdict for a tool call — only when this tier is current. */
+function tierVerdict(tier, call) {
+    if (tier !== current)
+        return { action: "abstain" }; // not our tier — no opinion
+    switch (tier) {
+        case "manual":
+            return { action: "ask" }; // every tool asks
+        case "default":
+            if (READ_TOOLS.has(call.name))
+                return { action: "allow" };
+            if (call.name === "write_file" || call.name === "edit_file" || call.name === "shell")
+                return { action: "ask" };
+            // Abstain (ADR-0042): an extension-provided tool is the
+            // EXTENSIONS' business — the tier neither allows nor denies.
+            // The chain falls to the ask flow when nobody else speaks, so
+            // an uncovered external tool STILL meets the human (the P2
+            // finding: "allow"-as-no-opinion auto-approved it).
+            return { action: "abstain" };
+        case "accept-edits":
+            if (READ_TOOLS.has(call.name))
+                return { action: "allow" };
+            if (call.name === "write_file" || call.name === "edit_file")
+                return { action: "allow" };
+            if (call.name === "shell")
+                return { action: "ask" };
+            return { action: "abstain" }; // see "default"
+        case "plan":
+            if (READ_TOOLS.has(call.name))
+                return { action: "allow" };
+            return { action: "deny", reason: "plan mode: read-only" };
+        case "bypass":
+            return { action: "allow" }; // everything — a REAL allow, never an abstain
+    }
+}
+/** The five built-in mode tiers as chain extensions — named "mode:<tier>"
+ *  so the runtime's decidedBy records exactly that (the runtime derives
+ *  approvalPolicies from extensions[].approvals, tagging each with the
+ *  extension name). The CURRENT tier is first: an all-allow chain records
+ *  decidedBy = the FIRST SPEAKER, so an auto-allow under the startup mode
+ *  names that mode honestly. Order never affects verdicts — the chain is
+ *  deny>ask>allow over the SPEAKING verdicts (abstain = no opinion), so a
+ *  user extension's deny wins over any mode tier, bypass included (the
+ *  monotonicity e2e pins it). */
+export function modeExtensions() {
+    return [...MODES.filter((m) => m === current), ...MODES.filter((m) => m !== current)].map((m) => ({
+        name: `mode:${m}`,
+        approvals: [
+            {
+                decide: async (payload) => tierVerdict(m, { name: payload.name }),
+            },
+        ],
+    }));
+}
+/** The plan tier's system prompt addition — injected at startup when the
+ *  initial mode is plan (the session prompt is fixed at creation; runtime
+ *  switches are guided by the deny reason). */
+export function modeSystemPrompt() {
+    if (current !== "plan")
+        return undefined;
+    return ("plan mode: read-only. You may inspect the workspace (read_file, list_dir, search_text, " +
+        "read_skill) but every write/edit/shell call is DENIED with 'plan mode: read-only'. " +
+        "Produce a concrete plan (files, searches, proposed edits) as your output; the human " +
+        "switches to another mode to execute it.");
+}

package/dist/render.d.ts

@@ -16,6 +16,7 @@ export interface Palette {
     readonly blue: string;
     readonly dim: string;
     readonly red: string;
+    readonly green: string;
     readonly reset: string;
 }
 export declare const COLOR_ON: Palette;

package/dist/render.js

@@ -3,8 +3,8 @@
  * the lines a human sees. Colors are raw ANSI — no dependencies.
  */
 import { canonicalTargetPath } from "@vincemakes/kiso-tools-node";
-export const COLOR_ON = { blue: "\x1b[38;5;75m", dim: "\x1b[2m", red: "\x1b[31m", reset: "\x1b[0m" };
-export const COLOR_OFF = { blue: "", dim: "", red: "", reset: "" };
+export const COLOR_ON = { blue: "\x1b[38;5;75m", dim: "\x1b[2m", red: "\x1b[31m", green: "\x1b[32m", reset: "\x1b[0m" };
+export const COLOR_OFF = { blue: "", dim: "", red: "", green: "", reset: "" };
 export function palette() {
     return process.env.NO_COLOR === undefined && process.stdout.isTTY ? COLOR_ON : COLOR_OFF;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-code",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "kiso CLI — the coding-agent reference product: kiso chat / kiso resume / kiso sessions.",
   "type": "module",
   "license": "MIT",
@@ -18,12 +18,12 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-core": "0.1.15",
-    "@vincemakes/kiso-evals": "0.1.15",
-    "@vincemakes/kiso-provider-anthropic": "0.1.15",
-    "@vincemakes/kiso-provider-openai": "0.1.15",
-    "@vincemakes/kiso-runtime": "0.1.15",
-    "@vincemakes/kiso-tools-node": "0.1.15"
+    "@vincemakes/kiso-core": "0.1.16",
+    "@vincemakes/kiso-evals": "0.1.16",
+    "@vincemakes/kiso-provider-anthropic": "0.1.16",
+    "@vincemakes/kiso-provider-openai": "0.1.16",
+    "@vincemakes/kiso-runtime": "0.1.16",
+    "@vincemakes/kiso-tools-node": "0.1.16"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",