@vincemakes/kiso-code 0.1.15 → 0.1.17

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";
@@ -25,19 +27,8 @@ import { fileURLToPath } from "node:url";
 import { createAgent, disposeExtensions, loadExtensions, loadProjectExtensions, projectArtifacts, recordTrust, SessionStore, trustFor, } from "@vincemakes/kiso-runtime";
 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 { escapeTerminal, foldResult, foldThinking, palette, renderEvent, renderSessionLine, renderStatusLine, renderTerminalGap, renderToolSummary, bannerLines, kUnit, renderRecap, truncateRow, } 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)
@@ -76,17 +67,18 @@ catch {
  *  merges into the third row on TTY and stays a standalone line off-TTY.
  *  v2a: the logo rows stay dim; the TAGLINE (row 2) is the blue identity
  *  accent. */
-const LOGO_TOP = "█ █ ▀█▀ █▀▀ █▀█\n█▀▄  █  ▀▀█ █ █   ";
-const TAGLINE = "the coding agent that survives kill -9";
-const LOGO_BOTTOM = "\n▀ ▀ ▀▀▀ ▀▀▀ ▀▀▀";
 function startupBanner() {
-    // The historical `[N extensions: names]` text merges VERBATIM into the
-    // third row — the existing e2e assertions keep matching (天然不破). E3:
-    // project-level extensions are counted in N and listed after `project:`
-    // — `[3 extensions: safe-defaults · project: lint-rules, mcp]`.
+    // v3 §01: the banner is block-split — three independent logo rows
+    // (TOP / tagline / BOTTOM), then TWO info rows (version,
+    // extensions), each truncated at the window width; < 40 columns
+    // skips the logo. The historical `[N extensions: names]` text rides
+    // the extensions row verbatim (the e2e assertions keep matching).
     const p = palette();
-    const names = bannerExtensionText();
-    return `${p.dim}${LOGO_TOP}${p.blue}${TAGLINE}${p.reset}${p.dim}${LOGO_BOTTOM}   v${VERSION}${names}${p.reset}\n`;
+    // A pty without a winsize reports columns = 0 (not undefined) — treat
+    // it as the default width, never as a 0-column truncation.
+    const W = process.stdout.columns ?? 0;
+    const rows = bannerLines(W > 0 ? W : 80, VERSION, bannerExtensionText().replace(/^ · /, ""));
+    return `${rows.map((r) => `${p.dim}${r}${p.reset}`).join("\n")}\n`;
 }
 /** v2a: the interactive prompt — blue, the identity accent. readline owns
  *  the echo of what the user types; we own the prompt's color. (v2c: the
@@ -203,6 +195,7 @@ function makeLineInput() {
         editor.enter();
         const p = palette();
         dock.bindInput(() => editor.dockState(), `${p.blue}${EDITOR_PROMPT}${p.reset}`);
+        dock.bindMenu(() => editor.menuState()); // v3 §04: the slash-command menu
         return editorInput(editor);
     }
     return readlineInput(createInterface({ input: process.stdin, output: process.stdout }));
@@ -223,27 +216,19 @@ function bodyLog(text) {
 /** v2b: the spinner merged into the STATUS BAR (the v2a standalone glyph
  *  is gone) — docked only, 200ms rotation between the request and the
  *  first event. */
-function startStatusSpinner() {
+function startStatusSpinner(onTick) {
     if (!dock.active)
         return () => { };
-    const GLYPHS = ["◐", "◓", "◑", "◒"];
+    // v3 §03/§05: the working glyph family ▖▘▝▗, 200ms rotation — the
+    // callback repaints the running status line with the new glyph.
+    const GLYPHS = ["▖", "▘", "▝", "▗"];
     let i = 0;
-    const timer = setInterval(() => dock.setTail(GLYPHS[i++ % GLYPHS.length]), 200);
+    const timer = setInterval(() => onTick(GLYPHS[i++ % GLYPHS.length]), 200);
     timer.unref();
-    return () => dock.setTail("");
-}
-/** v2b: "running <tool> Ns" in the status bar while a tool executes. */
-function startRunningTimer(name) {
-    if (!dock.active)
-        return () => { };
-    const started = Date.now();
-    const timer = setInterval(() => dock.setTail(`running ${name} ${Math.round((Date.now() - started) / 1000)}s`), 1000);
-    timer.unref();
-    return () => {
-        clearInterval(timer);
-        dock.setTail("");
-    };
+    return () => clearInterval(timer);
 }
+/** v3 §03: "running <tool> Ns" is gone — the running status line owns
+ *  the wall clock; the per-tool timer was the old tail mechanism. */
 /** The model name for the status bar — set by makeAgent. */
 let agentModel = "faux";
 /** E3: the `[N extensions: ...]` text — user-level names, then project-level
@@ -518,15 +503,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,9 +695,46 @@ 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 };
+    // v3 §02: the recap line derives ENTIRELY from the local event stream
+    // (zero tokens) — wall seconds, tool/edit counts, usage, ctx left.
+    const turnStart = Date.now();
+    let toolCount = 0;
+    let editCount = 0;
     try {
         for await (const ev of run) {
             last = ev;
@@ -727,6 +760,9 @@ async function consumeRun(session, run, input, turnNo, faux, liveInput, statusCb
                     body.thinkingAppend(ev.text);
                     break;
                 case "tool_call_end":
+                    toolCount += 1;
+                    if (ev.name === "edit_file")
+                        editCount += 1;
                     body.toolStart(ev.name, ev.callId, ev.input ?? {});
                     break;
                 case "tool_execution_started":
@@ -762,9 +798,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
@@ -776,13 +815,21 @@ async function consumeRun(session, run, input, turnNo, faux, liveInput, statusCb
                     await session.approve(decisionId, answer.trim().toLowerCase().startsWith("y"));
                     break;
                 }
-                case "terminal":
+                case "terminal": {
+                    // v3 §02: the run's recap line REPLACES the old "done" label
+                    // + status line — one local line, derived from this run's
+                    // events (zero tokens). The dock's status bar still paints.
                     statusCb?.(usage, estimateCtxRatio(session));
-                    // v2a rhythm: the honest label (\ndone\n — the completed
-                    // marker), the status line hugging it, then EXACTLY one blank
-                    // line before the next prompt.
-                    body.terminal(renderEvent(ev).text, renderStatusLine(turnNo, usage, estimateCtxRatio(session), faux) ?? "");
+                    const ratio = estimateCtxRatio(session);
+                    bodyLog(renderRecap({
+                        seconds: Math.round((Date.now() - turnStart) / 1000),
+                        tools: toolCount,
+                        edits: editCount,
+                        usage,
+                        ctxLeftPct: Number.isFinite(ratio) ? (1 - ratio) * 100 : null,
+                    }));
                     break;
+                }
                 default: {
                     // Events without a cell (stop, …) — the generic render, byte-
                     // preserved for the pipe path.
@@ -839,10 +886,20 @@ async function chat(session, faux, input) {
         currentRun = run;
         turnNo += 1;
         const myTurn = turnNo;
+        // v3 §03: the running state owns the status bar — the glyph
+        // rotates every 200ms; the idle state returns after the run.
+        runStart = Date.now();
+        runUsage = { in: null, out: null, cache: null, known: false };
+        const stopSpinner = startStatusSpinner((g) => {
+            runGlyph = g;
+            paintRunning();
+        });
         (async () => {
             let last;
             try {
                 last = await consumeRun(session, run, input, myTurn, faux, liveInput, statusCb);
+                stopSpinner();
+                paintIdle();
                 currentRun = null;
                 // 八: a faux script that ran out of declared turns exits
                 // loudly with a non-zero status — never a silent status 0.
@@ -925,13 +982,33 @@ 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).
-    const statusCb = (u, ctx) => {
+    // v2b: the live status bar (docked only). Modes: /mode switches repaint
+    // it immediately through paintStatus (the last turn stats are kept).
+    // v3 §03: the status bar has TWO states. Idle: the mode is ALWAYS
+    // shown (default included) with the /mode hint. Running: the working
+    // glyph (▖▘▝▗ — the spinner drives it) + wall seconds + ↓ out tokens
+    // + the interrupt hint. ctx left is the live estimate everywhere.
+    let runUsage = { in: null, out: null, cache: null, known: false };
+    let runGlyph = "▖";
+    let runStart = Date.now();
+    const paintRunning = () => {
         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);
+        const ratio = estimateCtxRatio(session);
+        const pct = Number.isFinite(ratio) ? Math.round((1 - ratio) * 100) : null;
+        const out = runUsage.out !== null ? ` ↓ ${kUnit(runUsage.out)} tokens` : "";
+        dock.setStatus(`${runGlyph} working ${Math.max(1, Math.round((Date.now() - runStart) / 1000))}s${out} · esc to interrupt · ctx left ~${pct}%`);
+    };
+    const paintIdle = () => {
+        if (!dock.active)
+            return;
+        const ratio = estimateCtxRatio(session);
+        const pct = Number.isFinite(ratio) ? Math.round((1 - ratio) * 100) : null;
+        dock.setStatus(`▸ ${getMode()} · /mode to switch · ${agentModel} · ctx left ~${pct}%`);
+    };
+    const statusCb = (u, ctx) => {
+        runUsage = u;
+        paintRunning();
     };
     // The ONE dispatcher: slash commands, exit, and turns. The recovery
     // replay routes through it too — a queued "/last" must never become a
@@ -949,6 +1026,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 +1080,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}`);
+                    paintIdle();
+                }
+                input.prompt();
+            });
+            return;
+        }
         if (trimmed === "exit" || trimmed === "") {
             input.close();
             return;
@@ -1063,21 +1164,41 @@ async function resume(session, prompt, faux, input) {
     let currentRun = null;
     let cancelled = false;
     let turnNo = 0;
-    // v2b: the live status bar (docked only).
+    // v3 §03: the two-state status bar (see chat — same shapes).
+    let runUsage = { in: null, out: null, cache: null, known: false };
+    let runGlyph = "▖";
+    let runStart = Date.now();
     const statusCb = (u, ctx) => {
+        runUsage = u;
+        if (!dock.active)
+            return;
+        const pct = Number.isFinite(ctx) ? Math.round((1 - ctx) * 100) : null;
+        const out = runUsage.out !== null ? ` ↓ ${kUnit(runUsage.out)} tokens` : "";
+        dock.setStatus(`${runGlyph} working ${Math.max(1, Math.round((Date.now() - runStart) / 1000))}s${out} · esc to interrupt · ctx left ~${pct}%`);
+    };
+    const paintIdle = () => {
         if (!dock.active)
             return;
-        const st = renderStatusLine(turnNo, u, ctx, faux);
-        dock.setStatus(st === null ? `${session.id} · ${agentModel}` : `${session.id} · ${agentModel} · ${st}`);
+        const ratio = estimateCtxRatio(session);
+        const pct = Number.isFinite(ratio) ? Math.round((1 - ratio) * 100) : null;
+        dock.setStatus(`▸ ${getMode()} · /mode to switch · ${agentModel} · ctx left ~${pct}%`);
     };
     const withRun = async (run) => {
         currentRun = run;
+        runStart = Date.now();
+        runUsage = { in: null, out: null, cache: null, known: false };
+        const stopSpinner = startStatusSpinner((g) => {
+            runGlyph = g;
+            statusCb(runUsage, estimateCtxRatio(session));
+        });
         try {
             turnNo += 1;
             const last = await consumeRun(session, run, input, turnNo, faux, null, statusCb);
             failOnFauxExhaustion(last, faux, input);
         }
         finally {
+            stopSpinner();
+            paintIdle();
             currentRun = null;
         }
     };
@@ -1127,7 +1248,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 +1282,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) {
@@ -1184,7 +1323,7 @@ async function main() {
             }
             case "help": {
                 const p = palette();
-                console.log(`${p.dim}${LOGO_TOP}${p.blue}${TAGLINE}${p.reset}${p.dim}${LOGO_BOTTOM}${p.reset}\n\n` +
+                console.log(`${p.dim}${bannerLines(80, VERSION, "").join("\n")}${p.reset}\n\n` +
                     "kiso — the coding agent that survives kill -9\n\n" +
                     "  kiso [sessionId]         interactive session (default command)\n" +
                     "  kiso chat [sessionId]    same as above\n" +

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

@@ -11,11 +11,14 @@ import { canonicalTargetPath } from "@vincemakes/kiso-tools-node";
  * errors; dim for metadata. NO_COLOR set, or a non-TTY output → every
  * code is empty, so pipes and CI carry ZERO ANSI (the existing byte-level
  * e2e assertions guard it). Everything not listed here is plain.
+ * v3: `bg` — the user-message block background (SGR 48, dark gray 237).
  */
 export interface Palette {
     readonly blue: string;
     readonly dim: string;
     readonly red: string;
+    readonly green: string;
+    readonly bg: string;
     readonly reset: string;
 }
 export declare const COLOR_ON: Palette;
@@ -72,6 +75,8 @@ export declare function renderToolSummary(name: string, input: Record<string, un
     content: string;
     isError: boolean;
 }): string;
+/** k-units for the status line: 12345 → 12.3k, 800 → 800, null → ?. */
+export declare function kUnit(value: number | null): string;
 /** B 区: usage data gathered from the run's usage events. */
 export interface RunUsage {
     readonly in: number | null;
@@ -95,6 +100,31 @@ export declare function renderStatusLine(turn: number, usage: RunUsage, ctxRatio
  * this verbatim; the render tests pin the sequence.
  */
 export declare function renderTerminalGap(statusLine: string | null): string;
+/**
+ * v3 §01 — the banner, block-split. The logo is three INDEPENDENT rows
+ * (TOP / the tagline / BOTTOM), then TWO info rows (version,
+ * extensions). Every row truncates at the terminal width with a " (+N)"
+ * marker (N = the hidden display width); a window narrower than 40
+ * columns skips the logo entirely — only the info rows. Pure.
+ */
+export declare const TAGLINE = "the coding agent that survives kill -9";
+/** v3 §01: truncate a row at `width`, marking the hidden span " (+N)". */
+export declare function truncateRow(row: string, width: number): string;
+/** v3 §01: the banner lines for a width W — logo (skipped under 40
+ *  columns) + version + extensions. */
+export declare function bannerLines(W: number, version: string, extensionsText: string): string[];
+/** v3 §02 — the recap line that ends a run, replacing the "done" label +
+ *  the old status line. All fields derive LOCALLY from the event stream
+ *  (zero tokens): wall seconds, tool counts, usage, cache hit %, ctx left.
+ */
+export interface RecapStats {
+    readonly seconds: number;
+    readonly tools: number;
+    readonly edits: number;
+    readonly usage: RunUsage;
+    readonly ctxLeftPct: number | null;
+}
+export declare function renderRecap(s: RecapStats): string;
 /** One-line summary of a session, for `kiso sessions`. */
 export declare function renderSessionLine(meta: {
     id: string;