agent-from-zero 0.5.0 → 0.27.0

package/README.md

@@ -4,7 +4,7 @@
 
 人定方向、做决策、验收,AI 写大部分代码——这既是本仓库的诞生方式,也是这门课教你的工作方式。
 
-课程拆成 10 个 Day,一个 Day 一个 commit,按一晚一章的节奏跟做。**commit 历史就是课程目录**:`git log --oneline` 看大纲,`git checkout dayN` 拿到第 N 章对应的完整代码。
+课程共 35 天——主线 10 天搓出一个能用的 agent,进阶 25 天打磨成工业级 CLI(MCP / 权限裁判 / 长期记忆 / 成本核算 / 调用校验 / 计划模式 / diff 预览 / 撤销 / 模型分级 / 远程 MCP / 会话改动总览 / @file 引用 / 会话选择器 / 终端 UI / 方向键审批 / 多问题表单 / 模型切换 / 推理流 / Skill 系统 / 记忆深化 / Hook 深化);一天一个 commit、一晚一章的节奏跟做。**commit 历史就是课程目录**:`git log --oneline` 看大纲,`git checkout dayN` 拿到第 N 天对应的完整代码。
 
 > **设计有出处,不是凭感觉搭的**:蓝本是《Harness Engineering:从 Claude Code 看 AI 编码工程》提炼的 22 个工程模式——博主在公众号用 30+ 篇拆完了全书(本仓库就是那次拆解的实践篇)。书的收官章,作者用 800 行 Rust 写了一个代码审查 Agent,验证这些模式能跨语言、跨场景活下来;**这个仓库是同一套模式的又一次迁移**:场景换成 Claude Code 式的 CLI 编码 agent,语言换成 TypeScript——不跟着用 Rust,是因为新手教程的第一原则是别让语言难度挡路。
 >
@@ -61,10 +61,31 @@ MINI_AGENT_MODEL=gpt-4.1-mini
 | `day12` | 会话持久化(`--resume`,快照式 + 原子写)+ 本地遥测(事件 JSONL + `/stats`,绝不出本机,`MINI_AGENT_NO_TELEMETRY=1` 关闭) |
 | `day13` | 异步执行:run_bash 换 spawn(不冻 UI、Ctrl+C 秒杀、30s 超时 SIGKILL)、超长输出落盘、只读工具并行;`npm test` 65 例 |
 | `day14` | Hook 生命周期系统:PreToolUse(拦截工具)/PostToolUse(追加校验)/SessionStart(注入上下文)/Stop(测试驱动 AI),退出码协议、stderr 喂回模型;`npm test` 76 例 |
+| `day15` | MCP 接入:stdio JSON-RPC 客户端(握手/行缓冲/id 配对),外部 server 工具注册成内置同款(同一 dispatch + 权限闸门,默认 ask);`npm test` 84 例 |
+| `day16` | 可选 LLM 权限裁判:只看规则判 ask 的灰色地带、只能 ask→allow、prompt 铁死格式、解析 fail closed、自带熔断、默认关闭;`npm test` 98 例 |
+| `day17` | 长期记忆:跨会话的 MEMORY.md(人类可读)+ remember 工具,作为「背景」注入(区别于 AGENT.md 的「命令」),有界 30 条/8KB 且自修复;`npm test` 114 例 |
+| `day18` | 成本核算:从流里捕获 usage(include_usage)、抹平 DeepSeek/OpenAI 格式差异、纯函数算成本与缓存命中率、`/cost` 看花销(命中率即缓存击穿预警);`npm test` 130 例 |
+| `day19` | 工具调用校验:够用就好的 schema 校验(必填/类型/形状)、钉在 dispatch 唯一入口、批量返回精确修复指引、自动覆盖内置+MCP 工具(送出前拦下坏参数);`npm test` 146 例 |
+| `day20` | 计划模式:只读研究、想清楚再交计划由你批准;权限层一个外层过滤器(只收紧不放松、盖过预批准、保留禁飞区理由)+ `exit_plan_mode` 工具借用 ask 流程闭合审批 + `/plan` 开关;`npm test` 167 例 |
+| `day21` | diff 预览:写文件前把真实改动(绿 +/红 -)摊给你看再批准;十几行 LCS 行级 diff、折叠未变动行、复现工具语义无副作用推演、永不抛异常 fail 到 null;在闸门后执行前打印;`npm test` 189 例 |
+| `day22` | `/undo` 撤销上一次写入:写入前埋一行存「之前」快照(有界栈),`/undo` 还原内容或删掉新建文件、复用 Day 21 diff 画出撤销结果;`/clear` 同时清栈;`npm test` 204 例 |
+| `day23` | 子 agent 模型分级:`subAgentModel` 配置让委托跑在不同档位(便宜模型干杂活 / 强模型当顾问审查),纯函数 `subAgentModelFor` 定回落规则,首次用假 client 端到端验证「编排→委托→回归」真换了模型;`npm test` 212 例 |
+| `day24` | 远程 MCP(HTTP/SSE):把 Day 15 的传输从协议里剥成 Transport 接口,新增 HTTP 传输(POST→按 Content-Type 分 JSON/SSE 解析、回带 Mcp-Session-Id、AbortSignal 超时),配置 `url` 即走远程;协议层/发现/注册零改动;`npm test` 218 例 |
+| `day25` | `/diff` 会话改动总览:撤销账本旁加一张「会话起点基线」表(每个文件首次被碰的样子,只记一次),`/diff` 与磁盘现状逐个比、复用 Day 21 渲染净改动、净零跳过,三态 created/modified/deleted;`npm test` 227 例 |
+| `day26` | `@file` 引用:提问里 `@路径` 即把文件内容附进消息省一次 read_file 往返;认行首/空白后的 `@`、剥句尾标点;每个提及过 read_file 权限闸门——密钥文件(.env/*.pem)拒绝不读、被拒出声、没命中静默;`npm test` 244 例 |
+| `day27` | `/resume` 会话选择器:`session.ts` 加 listSessions(摘要)/loadSession(按 id)/sessionTitle(首句当标题、剥 @file 附件),REPL 列表+选号+整体切换(重建宪法、换 id、清读态与撤销栈),会话目录改惰性求值以可测;`npm test` 256 例 |
+| `day28` | 终端 UI:新增 `ui.ts` 收拢外观——圆角欢迎框、`❯` 提示符、`⏺`/`⎿` 活动标记(替 emoji)、走秒 spinner(搭车看门狗);讲透「颜色码污染宽度计算」要先按纯文本对齐再上色;`npm test` 277 例 |
+| `day29` | 方向键审批菜单:审批从「打 y/N」换成 ↑↓ 选(`menu.ts` 借 stdin 进 raw 模式、原地重绘、选完归还),带编号+底部操作提示;中间项「本会话别再问」复用 allow 规则(run_bash 只升 ask 不碰硬 deny);非 TTY 回退打字;`npm test` 289 例 |
+| `day30` | 多问题选择表单:给模型一个 `ask_user` 工具,需用户决策时弹表单(`form.ts` 纯状态机:扁平光标+reduce+提交校验+缺口跳转,`promptForm` 薄键盘层),收集成 question→answer 喂回;输入区改成 Claude Code 式「分隔线+❯」;`npm test` 309 例 |
+| `day31` | 运行时切换模型:`/model` 从只读升级成可切——`/model <name>` 直接设,裸 `/model` 拉端点 `/models` 列表用 Day 29 菜单选;切换只改 `CONFIG.model`、靠主循环每轮重读立即生效;`npm test` 314 例 |
+| `day32` | 让换模型看得见:流式循环多读 `reasoning_content`,把推理模型(R1)的思考灰着流出来(只渲染不进历史,绝不回传);spinner 显示当前模型作为切换生效的证明;`npm test` 324 例 |
+| `day33` | Skill 系统(Markdown 即插件):`SKILL.md`(frontmatter+正文)=一个插件、执行者是模型;渐进披露(列表进上下文/正文按需加载)、`skill` 工具说明书即列表、`disableModelInvocation` 分模型可调/仅用户、`/skills` `/skill <name>`;`npm test` 360 例 |
+| `day34` | 记忆深化:四类型(user/feedback/project/reference,feedback 最值钱)、每轮自动提取(便宜模型读对话存「用户纠正过的」,默认关、永不抛异常)、按类型分组注入、向后兼容旧格式;`npm test` 375 例 |
+| `day35` | Hook 深化:4→10 个时机(加 UserPromptSubmit/SessionEnd/Pre·PostCompact/Subagent*),配置改开放 record、exit 2 语义按事件由调用方解读、SessionEnd 极短超时;**`PreToolUse` 可改写工具参数**(权限三态做不到的「岔道」,严格在安全检查之后);`npm test` 381 例 |
 
 ## 📖 配套教程(免费开源)
 
-**[完整教程在 docs/ 目录](docs/README.md)**——11 章,每章对应一个 tag:为什么这么写、Claude Code 原版怎么做、你会踩的坑。每章五段结构:做完长什么样 → 跟着写 → 为什么 → 坑 → 小结。
+**[完整教程在 docs/ 目录](docs/README.md)**——主线 + 进阶共十几章,每章对应一个 tag:为什么这么写、Claude Code 原版怎么做、你会踩的坑。每章五段结构:做完长什么样 → 跟着写 → 为什么 → 坑 → 小结。
 
 想看更深的「为什么」:公众号的 **Harness Engineering 拆书系列**(30+ 篇)逐章拆了《Harness Engineering:从 Claude Code 看 AI 编码工程》——本仓库每个设计决策背后的原理、数据和事故案例都在那里。公众号 @(待填)。
 

package/dist/agent.js

@@ -3,14 +3,27 @@ import OpenAI from "openai"; // the API client
 import chalk from "chalk"; // terminal colors
 import readline from "node:readline/promises"; // promise-based terminal input
 import { createRequire } from "node:module"; // to read package.json for --version
-import { CONFIG, requireApiKey, PROJECT_SETTINGS_PATH, GLOBAL_SETTINGS_PATH } from "./config.js"; // provider-agnostic settings (.env loaded there)
-import { runLoop, TerminateReason, MAX_ROUNDS, MAX_RETRIES } from "./loop.js"; // the state machine
+import { CONFIG, requireApiKey, saveGlobalSetting, PROJECT_SETTINGS_PATH, GLOBAL_SETTINGS_PATH } from "./config.js"; // provider-agnostic settings (.env loaded there)
+import { runLoop, TerminateReason, MAX_RETRIES } from "./loop.js"; // the state machine
 import { buildSystemMessage } from "./prompt.js"; // the constitution + optional AGENT.md project memory
-import { forgetFilesExcept } from "./tools.js"; // to reset file state on /clear
-import { compactHistory, COMPACT_AT } from "./context.js"; // for the manual /compact command
-import { newSessionId, saveSession, latestSession } from "./session.js"; // conversation persistence (project-local)
+import { forgetFilesExcept, registerExternalTool } from "./tools.js"; // file-state reset + tool registration
+import { compactHistory, estimateHistoryTokens, COMPACT_AT } from "./context.js"; // for the manual /compact command
+import { newSessionId, saveSession, latestSession, listSessions, loadSession } from "./session.js"; // conversation persistence (project-local) + the /resume picker
 import { initTelemetry, emit, statsReport } from "./telemetry.js"; // local-only event log + /stats
 import { runHooks } from "./hooks.js"; // SessionStart lifecycle hook
+import { connectMcpServers } from "./mcp.js"; // external tool servers (MCP)
+import { Judge } from "./judge.js"; // optional LLM permission classifier
+import { isPlanMode, setPlanMode } from "./permissions.js"; // plan mode: research-only until the user approves a plan
+import { undoLast, clearUndo, sessionChanges } from "./undo.js"; // /undo + /diff: take back, or review, this session's writes
+import { renderDiff } from "./diff.js"; // show what /undo put back / what /diff changed, reusing the Day 21 diff renderer
+import path from "node:path"; // shorten paths for the /diff summary
+import { expandMentions } from "./mentions.js"; // @file mentions: pull referenced files into context (secret files refused)
+import { banner, framedPrompt, formatModelChoices, statusLine, inputRule } from "./ui.js"; // welcome box, prompt, model labels, status line
+import { gitBranch, toggleLastCollapsed, cleanup as tuiCleanup } from "./tui.js"; // git branch for the status line + collapsible output
+import { promptSelect, promptForm } from "./menu.js"; // arrow-key approval menu + multi-question form
+import { rememberTool, readMemory, readMemoryTyped, extractMemories, MEMORY_PATH } from "./memory.js"; // long-term project memory + auto-extract
+import { loadSkills, buildSkillTool, findSkill, skillInstructions } from "./skills.js"; // Markdown-as-plugin skills
+import { initCostMeter, DEFAULT_PRICING } from "./cost.js"; // token & cost accounting for /cost
 // package.json sits one level above both src/ (dev) and dist/ (built) — same path either way.
 const pkg = createRequire(import.meta.url)("../package.json");
 // ---- CLI arguments --------------------------------------------------------------
@@ -33,7 +46,6 @@ Configuration (optional):
 In a session, type /help for the in-session commands.`;
 // What we tell the user for every way a query can end. No raw stack traces.
 const EXIT_NOTES = {
-    [TerminateReason.RoundCap]: `Hit the ${MAX_ROUNDS}-round cap. The task may be too big for one go — try splitting it.`,
     [TerminateReason.CircuitBreaker]: "3 API failures in a row — stopping here instead of burning money.",
     [TerminateReason.RetryBudgetExhausted]: `${MAX_RETRIES} failed API calls in this query — giving up. Check your network and try again.`,
     [TerminateReason.RateLimitBudgetExhausted]: "The provider keeps rate-limiting us. Wait a minute, then try again.",
@@ -47,9 +59,20 @@ const SESSION_HELP = `commands:
   /help      this text
   /clear     wipe the conversation (and the file read-state) — fresh start
   /compact   compact the history into a summary right now (happens automatically near the limit)
-  /model     show which model and endpoint this session is talking to
+  /model     switch model for THIS session: "/model" to pick from a list, "/model <name>" to set; "/model save <name>" to make it your default
   /stats     event counts for this session (local telemetry — nothing leaves this machine)
+  /memory    show the durable facts the agent remembers about this project
+  /cost      tokens, cache hit rate and estimated spend this session (local)
+  /plan      toggle plan mode — research-only; the agent presents a plan you approve before any change
+  /undo      revert the most recent file write (write_file / edit_file) this session
+  /diff      show every file changed this session, as a diff from where it started
+  /resume    list recent sessions in this project and continue one of them
+  /skills    list the reusable skills available in this project
+  /skill <name>  run a skill yourself (works even for user-only skills)
   exit       leave (Ctrl+C at the prompt does the same)`;
+// Injected when the user turns plan mode on, so the model knows the rules of the
+// mode it now lives in (the permission gate enforces them regardless).
+const PLAN_MODE_NOTICE = `[plan mode ON] Investigate this request using only read-only tools — read_file, search, and safe read-only shell (ls, cat, git status). Do NOT write files, edit, or run mutating commands; the permission gate will block them. When you have a concrete, ordered plan, call the exit_plan_mode tool with that plan. The user reviews and approves it before you make any change.`;
 async function main() {
     // ---- Flag handling, before anything touches the network -----------------------
     const argv = process.argv.slice(2); // everything after "mini-agent"
@@ -85,6 +108,7 @@ async function main() {
     // -r / --resume picks up the most recent one. The system message is NOT
     // restored from disk — it is rebuilt fresh, because AGENT.md may have changed.
     let sessionId = newSessionId(); // this session's identity (and file name)
+    const sessionStartedAt = Date.now(); // for the status line's elapsed clock
     if (argv.includes("-r") || argv.includes("--resume")) {
         const prev = latestSession(); // newest snapshot in this directory, if any
         if (prev) {
@@ -98,6 +122,36 @@ async function main() {
     }
     initTelemetry(sessionId); // arm the local event log (no-op under MINI_AGENT_NO_TELEMETRY=1)
     emit("agent_session_start", { mode: printTask !== null ? "print" : "repl" }); // how this session was started
+    // Connect to any configured MCP servers and register their tools. This must
+    // finish before the first model call so the tools appear in the manual. A
+    // server that fails to start is skipped, never fatal.
+    const disconnectMcp = await connectMcpServers();
+    process.on("exit", disconnectMcp); // best-effort cleanup of server subprocesses
+    // The optional LLM permission judge, built once if a settings file enabled it.
+    const judge = CONFIG.judge.enabled ? new Judge(client, CONFIG.judge.model || CONFIG.model) : undefined;
+    if (judge)
+        console.log(chalk.dim(`(permission judge on — model ${CONFIG.judge.model || CONFIG.model})`));
+    // The remember tool: let the model save durable facts to long-term memory.
+    // Registered like any tool, so it flows through the same permission gate.
+    registerExternalTool(rememberTool);
+    const memCount = readMemory().length;
+    if (memCount)
+        console.log(chalk.dim(`(long-term memory: ${memCount} facts loaded)`));
+    // Skills: reusable Markdown procedures. The model-invocable ones are exposed
+    // through a single `skill` tool whose description lists them (progressive
+    // disclosure); user-only skills are reachable via /skill <name>.
+    const skills = loadSkills();
+    if (skills.some((s) => !s.disableModelInvocation))
+        registerExternalTool(buildSkillTool(skills));
+    if (skills.length)
+        console.log(chalk.dim(`(skills: ${skills.length} loaded — ${skills.map((s) => s.name).join(", ")})`));
+    // Token/cost meter for this session. Prices come from settings, falling back
+    // to the defaults; the loop records usage into it from every stream.
+    const costMeter = initCostMeter({
+        inputPerM: CONFIG.pricing.inputPerM ?? DEFAULT_PRICING.inputPerM,
+        cachedInputPerM: CONFIG.pricing.cachedInputPerM ?? DEFAULT_PRICING.cachedInputPerM,
+        outputPerM: CONFIG.pricing.outputPerM ?? DEFAULT_PRICING.outputPerM,
+    });
     // SessionStart hooks run once, here. Their stdout is injected as context the
     // model sees on its first turn — e.g. inject the current git branch, an
     // on-call rota, today's deploy freeze status. (exit 2 here is ignored: there
@@ -125,6 +179,8 @@ async function main() {
             model: CONFIG.model,
             signal: controller.signal,
             isInterrupted: () => interrupted,
+            subAgentModel: CONFIG.subAgentModel, // delegated work may run on a different tier
+            judge, // auto-allow clearly-safe commands even unattended (safer than blanket AUTO_APPROVE)
             // Print mode never prompts: unattended means nobody can say yes.
             // MINI_AGENT_AUTO_APPROVE=1 still works for scripted use; hard denies
             // were enforced in permissions.ts long before this runs.
@@ -146,9 +202,8 @@ async function main() {
         return; // the answer itself already streamed to stdout
     }
     // ---- Interactive session (REPL) -------------------------------------------------
-    // The banner: who am I, which model and host am I on, and how to get help.
-    console.log(chalk.bold(`mini-agent ${pkg.version}`) +
-        chalk.dim(` — ${CONFIG.model} @ ${new URL(CONFIG.baseURL).host} | /help for commands · Ctrl+C interrupts a running task`));
+    // The welcome box: who am I, which model and host am I on, and the basics.
+    console.log(banner(pkg.version, CONFIG.model, new URL(CONFIG.baseURL).host));
     // ONE readline interface for the whole session — the task prompt and the
     // permission prompts share it. Two interfaces on one stdin fight each other.
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -202,8 +257,8 @@ async function main() {
     // Fail closed: in a non-interactive session nobody can say yes, so the
     // answer is no. MINI_AGENT_AUTO_APPROVE=1 bypasses the QUESTION, but hard
     // denies were already enforced in permissions.ts before we get here.
-    const confirm = async (question) => {
-        console.log(chalk.yellow(`\n⚠️ approval needed — ${question}`)); // always show what is being asked
+    const confirm = async (question, toolName) => {
+        console.log(chalk.yellow(`\n⚠ approval needed — ${question}`)); // always show what is being asked
         if (process.env.MINI_AGENT_AUTO_APPROVE === "1") {
             console.log(chalk.dim("  auto-approved (MINI_AGENT_AUTO_APPROVE=1)")); // bypass mode — say so out loud
             return true; // approve without asking
@@ -212,26 +267,234 @@ async function main() {
             console.log(chalk.dim("  non-interactive session — denied by default (fail closed)")); // nobody can answer — refuse
             return false; // fail closed
         }
-        const answer = await readUserLine("  Allow? [y/N] "); // wait for the human (shares the line queue)
-        return /^y(es)?$/i.test(answer.trim()); // anything but y/yes means no
+        // Selecting beats typing: ↑/↓ + Enter instead of "type y/N". The middle
+        // option lets the user stop being asked about this tool for the session.
+        const allowLabel = toolName ? `Yes, and don't ask again for ${toolName} this session` : "Yes, and don't ask again this session";
+        const choice = await promptSelect(rl, ["Yes", allowLabel, "No — let me tell the agent what to do instead"]);
+        const approved = choice === 0 || choice === 1;
+        if (choice === 1 && toolName) {
+            CONFIG.permissions.allow.push(`tool:${toolName}`); // remember the grant for the rest of the session
+            console.log(chalk.dim(`  won't ask again for ${toolName} this session`));
+        }
+        console.log(approved ? chalk.green("  ✓ approved") : chalk.yellow("  ✗ declined"));
+        return approved;
+    };
+    // The model's handle on the user: present a multi-question form and return the
+    // selections. Null in a non-interactive session — the model is told to ask in
+    // plain text instead.
+    const askUser = async (questions) => {
+        if (!process.stdin.isTTY)
+            return null;
+        return promptForm(rl, questions);
+    };
+    // Ask the endpoint what models it serves (the OpenAI-compatible /models API).
+    // Empty list on any failure — not every endpoint implements it, and a failed
+    // listing should never break the command.
+    const listModels = async () => {
+        try {
+            const page = await client.models.list();
+            const ids = (page.data ?? []).map((m) => m.id).filter(Boolean);
+            return [...new Set(ids)].sort();
+        }
+        catch {
+            return [];
+        }
+    };
+    // /model — show the current model, or switch. `/model <name>` sets it directly;
+    // bare `/model` lists the endpoint's models and lets you pick one (Day 29 menu).
+    // The switch takes effect next turn: the loop reads CONFIG.model each turn.
+    const handleModelCommand = async (arg) => {
+        // Switching is SESSION-ONLY by default — a quick "/model <name>" to try a
+        // model must never permanently change your default. "/model save <name>"
+        // (or save after picking) writes it to the global settings file.
+        const save = arg === "save" || arg.startsWith("save ");
+        const name = save ? arg.slice(4).trim() : arg;
+        const apply = (next) => {
+            const prev = CONFIG.model;
+            CONFIG.model = next; // any string — the API errors on an unknown one, and the error layer reports it
+            if (save) {
+                saveGlobalSetting("model", next); // persist as the new default
+                console.log(chalk.dim(`(model: ${prev} → ${next} · saved as your default)`));
+            }
+            else {
+                console.log(chalk.dim(`(model: ${prev} → ${next} · this session only — use "/model save ${next}" to keep it)`));
+            }
+        };
+        if (name) {
+            apply(name);
+            return;
+        }
+        // No name: show the current model and a picker.
+        console.log(chalk.dim(`model: ${CONFIG.model}\n` +
+            (CONFIG.subAgentModel ? `sub-agent model: ${CONFIG.subAgentModel} (delegated task work)\n` : "") +
+            `endpoint: ${CONFIG.baseURL}\ncontext window: ${CONFIG.contextWindow} tokens (compaction at ~${COMPACT_AT})`));
+        if (!process.stdin.isTTY)
+            return; // no picker without a TTY — switch with: /model <name>
+        const models = await listModels();
+        if (!models.length) {
+            console.log(chalk.dim("(couldn't list models from this endpoint — switch with: /model <name>)"));
+            return;
+        }
+        console.log(chalk.dim("switch model (this session):"));
+        const choice = await promptSelect(rl, formatModelChoices(models, CONFIG.model));
+        if (choice < 0 || models[choice] === CONFIG.model) {
+            console.log(chalk.dim("(model unchanged)"));
+            return;
+        }
+        apply(models[choice]); // picker is session-only too; "/model save <name>" to persist
     };
     // Handle a /slash command. Returns true if the line was a command.
     const handleCommand = async (line) => {
+        // /model takes an optional argument (/model <name>), so it can't be a plain
+        // switch case — handle it before the exact-match switch.
+        if (line === "/model" || line.startsWith("/model ")) {
+            await handleModelCommand(line.slice("/model".length).trim());
+            return true;
+        }
+        // /skill <name> runs a skill on the user's behalf — inject its instructions
+        // as a turn so the model follows them. Works for user-only skills too.
+        if (line === "/skill" || line.startsWith("/skill ")) {
+            const name = line.slice("/skill".length).trim();
+            if (!name) {
+                console.log(chalk.dim(skills.length ? `usage: /skill <name> — available: ${skills.map((s) => s.name).join(", ")}` : "(no skills in this project — add one at .mini-agent/skills/<name>/SKILL.md)"));
+                return true;
+            }
+            const s = findSkill(skills, name);
+            if (!s) {
+                console.log(chalk.yellow(`(no skill named "${name}")`));
+                return true;
+            }
+            messages.push({ role: "user", content: `Run the "${s.name}" skill.\n\n${skillInstructions(s)}` });
+            console.log(chalk.dim(`(running skill: ${s.name})`));
+            running = true;
+            interrupted = false;
+            controller = new AbortController();
+            const r = await runLoop(messages, { client, model: CONFIG.model, signal: controller.signal, isInterrupted: () => interrupted, confirm, askUser, subAgentModel: CONFIG.subAgentModel, judge });
+            running = false;
+            saveSession(sessionId, CONFIG.model, messages);
+            if (r.reason !== TerminateReason.Done)
+                console.log(chalk.yellow(`\n⚠️ ${EXIT_NOTES[r.reason]}`));
+            return true;
+        }
         switch (line) {
+            case "/skills": {
+                if (!skills.length) {
+                    console.log(chalk.dim("(no skills — add one at .mini-agent/skills/<name>/SKILL.md or ~/.config/mini-agent/skills/)"));
+                    return true;
+                }
+                console.log(chalk.dim(`skills in this project:`));
+                for (const s of skills) {
+                    const who = s.disableModelInvocation ? chalk.yellow("user-only") : chalk.green("model+user");
+                    console.log(chalk.dim(`  ${s.name} [${who}${chalk.dim("]")} — ${(s.whenToUse || s.description).slice(0, 70)}`));
+                }
+                return true;
+            }
             case "/help":
                 console.log(chalk.dim(SESSION_HELP)); // the command reference
                 return true;
             case "/clear":
                 messages = [{ role: "system", content: systemMessage }]; // drop everything but the constitution
                 forgetFilesExcept([]); // the file read-state belongs to the conversation — clear it too
+                clearUndo(); // a fresh conversation should not undo the previous one's writes
                 sessionId = newSessionId(); // a fresh conversation is a fresh session file
                 console.log(chalk.dim("(history cleared)")); // confirm the reset
                 return true;
             case "/stats":
                 console.log(chalk.dim(statsReport())); // local counters, busiest first
                 return true;
-            case "/model":
-                console.log(chalk.dim(`model: ${CONFIG.model}\nendpoint: ${CONFIG.baseURL}\ncontext window: ${CONFIG.contextWindow} tokens (compaction at ~${COMPACT_AT})`)); // where this session points
+            case "/memory": {
+                const entries = readMemoryTyped(); // the durable, typed facts carried across sessions
+                console.log(chalk.dim(entries.length
+                    ? `long-term memory (${MEMORY_PATH}):\n${entries.map((e) => `  [${e.type}] ${e.fact}`).join("\n")}`
+                    : `(no long-term memory yet — the model saves facts with the remember tool${CONFIG.memory.autoExtract ? "" : "; turn on settings.memory.autoExtract to capture them automatically"})`));
+                return true;
+            }
+            case "/cost":
+                console.log(chalk.dim(costMeter.report())); // tokens, cache hit rate, estimated spend (local)
+                return true;
+            case "/undo": {
+                // Revert the most recent write. This is a USER action on the filesystem,
+                // not a turn for the model — the conversation is untouched. If the model
+                // later edits a file it thinks it changed, edit_file's read-before-edit +
+                // exact-match guards will catch the staleness and ask it to re-read.
+                const undone = undoLast();
+                if (!undone) {
+                    console.log(chalk.dim("(nothing to undo — no file writes recorded this session)"));
+                    return true;
+                }
+                console.log(chalk.dim(`↩ ${undone.summary}`));
+                // Show the diff of what was put back (from the current state to the
+                // restored one), reusing the Day 21 renderer.
+                console.log(renderDiff(undone.after ?? "", undone.before ?? ""));
+                return true;
+            }
+            case "/resume": {
+                // List recent sessions in this project and switch to the chosen one.
+                // Swapping mid-conversation is fine: we rebuild from the constitution +
+                // the saved messages, and reset the per-conversation state (read-state,
+                // undo history) so the resumed session behaves like a fresh start of it.
+                const sessions = listSessions(10);
+                if (!sessions.length) {
+                    console.log(chalk.dim("(no saved sessions in this project yet)"));
+                    return true;
+                }
+                console.log(chalk.dim("recent sessions in this project:"));
+                sessions.forEach((s, i) => {
+                    const when = s.savedAt.slice(0, 16).replace("T", " "); // 2026-06-15 10:30
+                    console.log(chalk.dim(`  ${i + 1}. ${when} · ${s.messageCount} msg · ${s.title.slice(0, 60)}`));
+                });
+                const answer = (await readUserLine("  resume which? [number, or Enter to cancel] ")).trim();
+                if (!answer) {
+                    console.log(chalk.dim("(cancelled)"));
+                    return true;
+                }
+                const idx = Number(answer) - 1;
+                if (!Number.isInteger(idx) || idx < 0 || idx >= sessions.length) {
+                    console.log(chalk.dim("(not a valid choice — cancelled)"));
+                    return true;
+                }
+                const chosen = loadSession(sessions[idx].id);
+                if (!chosen) {
+                    console.log(chalk.yellow("(could not load that session — it may be corrupt)"));
+                    return true;
+                }
+                messages = [{ role: "system", content: systemMessage }, ...chosen.messages]; // fresh constitution + saved turns
+                sessionId = chosen.id; // keep appending to the resumed session's file
+                forgetFilesExcept([]); // a resumed conversation must re-read files before editing them
+                clearUndo(); // the previous session's writes are not ours to undo
+                console.log(chalk.dim(`(resumed ${chosen.id} — ${chosen.messages.length} messages; files must be re-read before editing)`));
+                return true;
+            }
+            case "/diff": {
+                // A read-only review of the net effect of this session on the
+                // filesystem — every file whose content differs from where it started,
+                // shown as a diff from baseline → now. Reuses the Day 21 renderer.
+                const changes = sessionChanges();
+                if (!changes.length) {
+                    console.log(chalk.dim("(no file changes this session)"));
+                    return true;
+                }
+                const verb = { created: chalk.green("created"), modified: chalk.yellow("modified"), deleted: chalk.red("deleted") };
+                console.log(chalk.dim(`${changes.length} file${changes.length === 1 ? "" : "s"} changed this session:`));
+                for (const c of changes) {
+                    const short = path.relative(process.cwd(), c.path) || c.path;
+                    console.log(`\n${verb[c.status]} ${short}`);
+                    console.log(renderDiff(c.baseline, c.current));
+                }
+                return true;
+            }
+            case "/plan":
+                // A toggle. Turning it on injects the rules of the mode as a user turn so
+                // the model adopts them; the gate (permissions.ts) enforces them either way.
+                if (isPlanMode()) {
+                    setPlanMode(false);
+                    console.log(chalk.dim("(plan mode OFF — writing and executing tools enabled again)"));
+                }
+                else {
+                    setPlanMode(true);
+                    messages.push({ role: "user", content: PLAN_MODE_NOTICE });
+                    console.log(chalk.dim("(plan mode ON — read-only research; the agent will present a plan for you to approve)"));
+                }
                 return true;
             case "/compact": {
                 if (messages.length <= 1) {
@@ -256,15 +519,50 @@ async function main() {
     };
     // The session loop: ask → run → render → ask again. This is what makes it
     // a conversation instead of a one-shot command.
+    // Listen for Tab key on raw stdin — toggles expand/collapse of hidden tool output.
+    if (process.stdin.isTTY && typeof process.stdin.setRawMode === "function") {
+        process.stdin.on("data", (buf) => {
+            if (buf[0] === 0x09) { // Tab
+                if (!running)
+                    toggleLastCollapsed();
+            }
+        });
+    }
     while (true) {
-        const line = (await readUserLine(chalk.green("\n> "))).trim(); // next input, or "exit" on EOF
+        // Before each prompt, a status line (model · 📁 dir · 🌿 branch · ctx% · $ · time)
+        // then a separator rule, then the "❯". Only in a TTY; piped input is clean.
+        if (process.stdin.isTTY) {
+            const ctxPct = Math.min(100, Math.round((estimateHistoryTokens(messages) / CONFIG.contextWindow) * 100));
+            console.log("\n" + statusLine(CONFIG.model, path.basename(process.cwd()), gitBranch(), ctxPct, costMeter.cost(), Date.now() - sessionStartedAt));
+            console.log(inputRule());
+        }
+        const line = (await readUserLine(framedPrompt(isPlanMode()))).trim(); // next input, or "exit" on EOF
         if (!line)
             continue; // empty line — just re-prompt
         if (line === "exit" || line === "quit")
             break; // explicit goodbye
         if (await handleCommand(line))
             continue; // slash commands never reach the model
-        messages.push({ role: "user", content: line }); // the new turn joins the shared history
+        // UserPromptSubmit hook: a chance to validate/inject before the model sees
+        // the prompt. exit 2 DROPS the prompt entirely (e.g. block a forbidden ask);
+        // stdout becomes extra context for this turn (e.g. inject the current ticket).
+        const submit = await runHooks("UserPromptSubmit", { prompt: line });
+        if (submit.block) {
+            console.log(chalk.yellow(`(prompt blocked by a UserPromptSubmit hook: ${submit.feedback.slice(0, 150)})`));
+            continue; // the prompt is erased — never reaches the model
+        }
+        const injected = submit.stdout ? `\n\n[context added by a UserPromptSubmit hook]\n${submit.stdout}` : "";
+        // @file mentions: if the line references files (@src/loop.ts), attach their
+        // content to the message so the model sees them directly. Secret files are
+        // refused here, exactly as read_file would refuse them.
+        const { augmented, mentions } = expandMentions(line);
+        const attached = mentions.filter((m) => m.status === "ok").map((m) => m.raw);
+        const refused = mentions.filter((m) => m.status === "denied").map((m) => m.raw);
+        if (attached.length)
+            console.log(chalk.dim(`(attached ${attached.length} file${attached.length === 1 ? "" : "s"}: ${attached.join(", ")})`));
+        if (refused.length)
+            console.log(chalk.yellow(`(refused secret file${refused.length === 1 ? "" : "s"}: ${refused.join(", ")})`));
+        messages.push({ role: "user", content: augmented + injected }); // the new turn (with any attached files + hook context) joins the shared history
         running = true; // Ctrl+C now means "interrupt the task"
         interrupted = false; // fresh interrupt state for this task
         controller = new AbortController(); // fresh abort signal for this task
@@ -274,9 +572,25 @@ async function main() {
             signal: controller.signal, // for aborting requests
             isInterrupted: () => interrupted, // for stopping between steps
             confirm, // for permission prompts
+            askUser, // the multi-question form the model can pop
+            subAgentModel: CONFIG.subAgentModel, // delegated work may run on a different tier
+            judge, // optional LLM classifier for the "ask" middle ground
         });
         running = false; // back at the prompt — Ctrl+C means "exit" again
         saveSession(sessionId, CONFIG.model, messages); // snapshot after every turn — crash-safe by construction
+        // Auto-extract memories (opt-in: settings.memory.autoExtract). A cheap pass
+        // that saves durable facts — especially user corrections — so memory
+        // captures itself instead of relying on the model to call `remember`.
+        if (CONFIG.memory.autoExtract && result.reason === TerminateReason.Done) {
+            try {
+                const got = await extractMemories(client, CONFIG.subAgentModel || CONFIG.model, messages);
+                if (got.length)
+                    console.log(chalk.dim(`(remembered ${got.length}: ${got.map((g) => g.fact.slice(0, 50)).join("; ")})`));
+            }
+            catch {
+                /* memory extraction must never break the session */
+            }
+        }
         // Done already streamed its answer to the screen; everything else gets a
         // one-line human explanation. The session continues either way — except a
         // fatal API error, which no amount of chatting will fix.
@@ -288,8 +602,10 @@ async function main() {
                 break; // a bad key won't fix itself mid-session
         }
     }
+    await runHooks("SessionEnd", {}); // cleanup hooks (tiny 1.5s budget — the user may be leaving via Ctrl+C)
     emit("agent_session_end"); // close the books
     rl.close(); // release stdin
+    tuiCleanup(); // restore terminal
     console.log(chalk.dim("bye.")); // a clean goodbye
 }
 main(); // kick everything off

package/dist/config.js

@@ -52,6 +52,10 @@ export const CONFIG = {
         process.env.DEEPSEEK_API_KEY || // ...over the back-compat one
         "", // empty = missing; requireApiKey() turns that into a helpful error
     model: process.env.MINI_AGENT_MODEL || projectSettings.model || globalSettings.model || "deepseek-chat", // must support function calling
+    // Sub-agents (the task tool) can run on a DIFFERENT model than the orchestrator:
+    // a cheap/fast one for grunt work (reading many files, broad search), or a
+    // strong one as an "advisor" to double-check. undefined → use the main model.
+    subAgentModel: process.env.MINI_AGENT_SUBAGENT_MODEL || projectSettings.subAgentModel || globalSettings.subAgentModel || undefined,
     contextWindow: Number(process.env.MINI_AGENT_CONTEXT_WINDOW) || // env override first
         projectSettings.contextWindow || // then files
         globalSettings.contextWindow ||
@@ -62,14 +66,44 @@ export const CONFIG = {
         allow: [...(globalSettings.permissions?.allow ?? []), ...(projectSettings.permissions?.allow ?? [])],
         deny: [...(globalSettings.permissions?.deny ?? []), ...(projectSettings.permissions?.deny ?? [])],
     },
-    hooks: {
-        // Hook lists also concatenate: global hooks run first, then project hooks.
-        PreToolUse: [...(globalSettings.hooks?.PreToolUse ?? []), ...(projectSettings.hooks?.PreToolUse ?? [])],
-        PostToolUse: [...(globalSettings.hooks?.PostToolUse ?? []), ...(projectSettings.hooks?.PostToolUse ?? [])],
-        SessionStart: [...(globalSettings.hooks?.SessionStart ?? []), ...(projectSettings.hooks?.SessionStart ?? [])],
-        Stop: [...(globalSettings.hooks?.Stop ?? []), ...(projectSettings.hooks?.Stop ?? [])],
+    // Hooks for every event, merged across layers (global first, then project) by
+    // a generic union so adding a new event needs no edit here.
+    hooks: (() => {
+        const merged = {};
+        for (const src of [globalSettings.hooks, projectSettings.hooks]) {
+            for (const [event, defs] of Object.entries(src ?? {}))
+                merged[event] = [...(merged[event] ?? []), ...(defs ?? [])];
+        }
+        return merged;
+    })(),
+    // MCP servers: project entries override global ones with the same name.
+    mcpServers: { ...(globalSettings.mcpServers ?? {}), ...(projectSettings.mcpServers ?? {}) },
+    // LLM permission judge: off unless a settings file turns it on. Project wins.
+    judge: {
+        enabled: projectSettings.judge?.enabled ?? globalSettings.judge?.enabled ?? false,
+        model: projectSettings.judge?.model || globalSettings.judge?.model || undefined, // undefined → use the main model
+    },
+    // Token prices for the /cost estimate (defaults applied in cost.ts). Project
+    // overrides global; either may set just the fields it cares about.
+    pricing: { ...(globalSettings.pricing ?? {}), ...(projectSettings.pricing ?? {}) },
+    // Long-term memory: auto-extract durable facts after each turn. Off by default
+    // — it costs an extra (cheap) model call per turn. Project overrides global.
+    memory: {
+        autoExtract: projectSettings.memory?.autoExtract ?? globalSettings.memory?.autoExtract ?? false,
     },
 };
+// Persist a single key to the global settings file, preserving all other keys.
+// Used by /model to remember the user's last choice across sessions.
+export function saveGlobalSetting(key, value) {
+    const dir = path.dirname(GLOBAL_SETTINGS_PATH);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    const current = fs.existsSync(GLOBAL_SETTINGS_PATH)
+        ? JSON.parse(fs.readFileSync(GLOBAL_SETTINGS_PATH, "utf8"))
+        : {};
+    current[key] = value;
+    fs.writeFileSync(GLOBAL_SETTINGS_PATH, JSON.stringify(current, null, 2) + "\n");
+}
 // No key, no point: fail with instructions instead of a stack trace later.
 export function requireApiKey() {
     if (CONFIG.apiKey)