agent-from-zero 0.1.0 → 0.5.0

package/README.md

@@ -1,9 +1,15 @@
 # mini-agent
 
-用 DeepSeek API 从零手写一个类 Claude Code 的命令行 Agent,TypeScript 实现。
+**跟着 AI,从零搓一个自己的 Claude Code**——一个能读文件、改代码、跑命令的命令行 Agent。TypeScript 实现,默认 DeepSeek 驱动(任何 OpenAI 兼容模型可配)。
 
-10 天,每天一个 commit。**commit 历史就是课程目录**:`git log --oneline` 看大纲,`git checkout dayN` 拿到第 N 天收工时的完整代码。
+人定方向、做决策、验收,AI 写大部分代码——这既是本仓库的诞生方式,也是这门课教你的工作方式。
 
+课程拆成 10 个 Day,一个 Day 一个 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,是因为新手教程的第一原则是别让语言难度挡路。
+>
+> **用 AI 搓出一个类 Claude Code,这件事本身就是这套方法最好的 demo**——教程里每个「踩过的坑」都真实发生在开发过程中,不是编的。
+>
 > 代码、注释、commit message 用英文——模型的工具调用主要在英文数据上训练,英文指令引导更稳,也方便国际读者;配套教程是中文。
 
 ## 快速开始
@@ -50,9 +56,16 @@ MINI_AGENT_MODEL=gpt-4.1-mini
 | `day7` | 子 agent(task 工具:独立上下文、一层分身不套娃、报告是材料不是结论、文件状态快照隔离)+ 最小 eval(10 道固定题、物证判分、8/10 及格线,`npm run eval`) |
 | `day8` | 封装发布:`bin` 入口 + tsc 构建,npx 一行启动(包名 `agent-from-zero`);内置 .env 加载;缺 key 人话报错 |
 | `day9` | 教程本身:11 章中文教程开源进 [docs/](docs/README.md) |
+| `day10` | Bring your own model:三个环境变量换任意 OpenAI 兼容端点,`npm run eval` 兼职模型横评 |
+| `day11` | 工业级 CLI 表面:settings.json 双层配置(用户权限规则,deny 永远赢)、slash 命令(/help /model /compact)、`-p` 单发模式、`--version`、测试套件进仓库(`npm test`,60 例) |
+| `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 例 |
 
 ## 📖 配套教程(免费开源)
 
 **[完整教程在 docs/ 目录](docs/README.md)**——11 章,每章对应一个 tag:为什么这么写、Claude Code 原版怎么做、你会踩的坑。每章五段结构:做完长什么样 → 跟着写 → 为什么 → 坑 → 小结。
 
+想看更深的「为什么」:公众号的 **Harness Engineering 拆书系列**(30+ 篇)逐章拆了《Harness Engineering:从 Claude Code 看 AI 编码工程》——本仓库每个设计决策背后的原理、数据和事故案例都在那里。公众号 @(待填)。
+
 如果这个项目帮你搞懂了 agent,点个 ⭐ 就是最大的支持。

package/dist/agent.js

@@ -2,32 +2,153 @@
 import OpenAI from "openai"; // the API client
 import chalk from "chalk"; // terminal colors
 import readline from "node:readline/promises"; // promise-based terminal input
-import { CONFIG, requireApiKey } from "./config.js"; // provider-agnostic settings (.env loaded there)
+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 { buildSystemMessage } from "./prompt.js"; // the constitution + optional AGENT.md project memory
 import { forgetFilesExcept } from "./tools.js"; // to reset file state on /clear
-requireApiKey(); // fail fast with instructions, not a stack trace from inside the SDK
-// Build the API client once, for the whole session.
-const client = new OpenAI({
-    baseURL: CONFIG.baseURL, // DeepSeek by default; any OpenAI-compatible endpoint via MINI_AGENT_BASE_URL
-    apiKey: CONFIG.apiKey, // from .env or the shell
-    maxRetries: 0, // we own the retry policy — never let the SDK retry underneath us
-});
+import { compactHistory, COMPACT_AT } from "./context.js"; // for the manual /compact command
+import { newSessionId, saveSession, latestSession } from "./session.js"; // conversation persistence (project-local)
+import { initTelemetry, emit, statsReport } from "./telemetry.js"; // local-only event log + /stats
+import { runHooks } from "./hooks.js"; // SessionStart lifecycle hook
+// 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 --------------------------------------------------------------
+// Tiny by design: a help text, a version, and a one-shot print mode. Anything
+// fancier belongs in settings files, not flags.
+const USAGE = `mini-agent ${pkg.version} — a Claude Code-style CLI agent (any OpenAI-compatible model)
+
+Usage:
+  mini-agent                 interactive session (REPL)
+  mini-agent -r | --resume   continue the most recent session in this directory
+  mini-agent -p "<task>"     one-shot: run a single task, print the result, exit
+  mini-agent -v | --version  print the version
+  mini-agent -h | --help     this text
+
+Configuration (optional):
+  ${GLOBAL_SETTINGS_PATH}   your defaults (model, baseURL, permissions, hooks)
+  ${PROJECT_SETTINGS_PATH}   per-project rules — both layers apply, deny always wins
+  MINI_AGENT_API_KEY / MINI_AGENT_BASE_URL / MINI_AGENT_MODEL override everything.
+
+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]: "DeepSeek keeps rate-limiting us. Wait a minute, then try again.",
+    [TerminateReason.RateLimitBudgetExhausted]: "The provider keeps rate-limiting us. Wait a minute, then try again.",
     [TerminateReason.ContextTooLong]: "The conversation no longer fits the model's context window, and compaction could not shrink it enough. Use /clear to start fresh.",
     [TerminateReason.CompactionFailed]: "Automatic compaction kept failing — stopping instead of looping. Use /clear to start fresh.",
     [TerminateReason.FatalApiError]: "Unrecoverable API error — retrying would not help. Check your API key and request.",
     [TerminateReason.UserInterrupt]: "Interrupted — back at the prompt.",
 };
+// The in-session command reference, shown by /help.
+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
+  /stats     event counts for this session (local telemetry — nothing leaves this machine)
+  exit       leave (Ctrl+C at the prompt does the same)`;
 async function main() {
-    // The banner: who am I, which model and host am I on, and the three things worth knowing.
-    console.log(chalk.bold("mini-agent") +
-        chalk.dim(` — ${CONFIG.model} @ ${new URL(CONFIG.baseURL).host} | "exit" to quit · "/clear" to reset · Ctrl+C interrupts a running task`));
+    // ---- Flag handling, before anything touches the network -----------------------
+    const argv = process.argv.slice(2); // everything after "mini-agent"
+    if (argv.includes("-v") || argv.includes("--version")) {
+        console.log(pkg.version); // just the number — script-friendly
+        return;
+    }
+    if (argv.includes("-h") || argv.includes("--help")) {
+        console.log(USAGE); // the full help text
+        return;
+    }
+    // Print mode: -p / --print takes the task from the remaining arguments.
+    const pIdx = argv.findIndex((a) => a === "-p" || a === "--print"); // where the flag sits
+    const printTask = pIdx >= 0 ? argv.slice(pIdx + 1).join(" ").trim() : null; // everything after it is the task
+    if (pIdx >= 0 && !printTask) {
+        console.error('Usage: mini-agent -p "<task>"'); // -p without a task is a usage error
+        process.exitCode = 2;
+        return;
+    }
+    requireApiKey(); // fail fast with instructions, not a stack trace from inside the SDK
+    // Build the API client once, for the whole session.
+    const client = new OpenAI({
+        baseURL: CONFIG.baseURL, // DeepSeek by default; any OpenAI-compatible endpoint via config
+        apiKey: CONFIG.apiKey, // from .env or the shell
+        maxRetries: 0, // we own the retry policy — never let the SDK retry underneath us
+    });
+    // The system message is built ONCE per session: stable prefix = cache hits
+    // on every request. Nothing session-specific may sneak into it later.
+    const systemMessage = buildSystemMessage();
+    let messages = [{ role: "system", content: systemMessage }]; // the whole conversation lives here, across turns
+    // ---- Session persistence ---------------------------------------------------------
+    // Every conversation is snapshotted to .mini-agent/sessions/ after each turn;
+    // -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)
+    if (argv.includes("-r") || argv.includes("--resume")) {
+        const prev = latestSession(); // newest snapshot in this directory, if any
+        if (prev) {
+            messages.push(...prev.messages); // the old conversation joins the fresh constitution
+            sessionId = prev.id; // keep appending to the same session file
+            console.log(chalk.dim(`(resumed session ${prev.id} — ${prev.messages.length} messages; files must be re-read before editing)`));
+        }
+        else {
+            console.log(chalk.dim("(no previous session here — starting fresh)")); // resume with nothing to resume is not an error
+        }
+    }
+    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
+    // 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
+    // is no tool to block, only context to add.)
+    const sessionStart = await runHooks("SessionStart", {});
+    if (sessionStart.stdout)
+        messages.push({ role: "user", content: `[SessionStart hook]\n${sessionStart.stdout}` });
+    // Per-task interrupt state. `running` decides what Ctrl+C means right now.
+    let running = false; // is a task currently executing?
+    let interrupted = false; // has the current task been interrupted?
+    let controller = new AbortController(); // aborts the in-flight API request
+    // ---- One-shot print mode -------------------------------------------------------
+    // The same loop, the same permission gate (fail closed without a TTY), no REPL.
+    // Designed for scripts: the exit code distinguishes success from every failure.
+    if (printTask !== null) {
+        process.on("SIGINT", () => {
+            if (interrupted)
+                process.exit(130); // second press: force quit
+            interrupted = true; // first press: wind down
+            controller.abort(); // cancel the in-flight request
+        });
+        messages.push({ role: "user", content: printTask }); // the single task
+        const result = await runLoop(messages, {
+            client,
+            model: CONFIG.model,
+            signal: controller.signal,
+            isInterrupted: () => interrupted,
+            // 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.
+            confirm: async (q) => {
+                if (process.env.MINI_AGENT_AUTO_APPROVE === "1")
+                    return true; // explicit bypass
+                console.error(chalk.dim(`[print mode] declined (no prompt available): ${q.split("\n")[0]}`)); // visible in stderr, not stdout
+                return false; // fail closed
+            },
+        });
+        saveSession(sessionId, CONFIG.model, messages); // print-mode runs are resumable too
+        emit("agent_session_end"); // close the books
+        if (result.reason !== TerminateReason.Done) {
+            console.error(chalk.yellow(EXIT_NOTES[result.reason])); // human note on stderr
+            if (result.detail)
+                console.error(chalk.dim(result.detail.slice(0, 300))); // raw detail on stderr
+            process.exitCode = result.reason === TerminateReason.UserInterrupt ? 130 : 1; // scripts can branch on this
+        }
+        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`));
     // 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 });
@@ -61,14 +182,6 @@ async function main() {
         rl.prompt();
         return new Promise((resolve) => lineWaiters.push(resolve)); // wait for the next line
     };
-    // The system message is built ONCE per session: stable prefix = cache hits
-    // on every request. Nothing session-specific may sneak into it later.
-    const systemMessage = buildSystemMessage();
-    let messages = [{ role: "system", content: systemMessage }]; // the whole conversation lives here, across turns
-    // Per-task interrupt state. `running` decides what Ctrl+C means right now.
-    let running = false; // is a task currently executing?
-    let interrupted = false; // has the current task been interrupted?
-    let controller = new AbortController(); // aborts the in-flight API request
     // Ctrl+C semantics, by state:
     // - at the prompt: exit the session (standard REPL behavior)
     // - while running: first press interrupts the task, second press force-quits
@@ -102,6 +215,45 @@ async function main() {
         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
     };
+    // Handle a /slash command. Returns true if the line was a command.
+    const handleCommand = async (line) => {
+        switch (line) {
+            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
+                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
+                return true;
+            case "/compact": {
+                if (messages.length <= 1) {
+                    console.log(chalk.dim("(nothing to compact yet)")); // only the system message so far
+                    return true;
+                }
+                try {
+                    await compactHistory(messages, client, CONFIG.model, new AbortController().signal); // same machinery as automatic compaction
+                }
+                catch (err) {
+                    console.log(chalk.yellow(`compaction failed: ${err.message}`)); // report, don't crash
+                }
+                return true;
+            }
+            default:
+                if (line.startsWith("/")) {
+                    console.log(chalk.dim(`unknown command: ${line} — try /help`)); // typo guard
+                    return true; // still consumed — don't send typos to the model
+                }
+                return false; // a normal task line
+        }
+    };
     // The session loop: ask → run → render → ask again. This is what makes it
     // a conversation instead of a one-shot command.
     while (true) {
@@ -110,12 +262,8 @@ async function main() {
             continue; // empty line — just re-prompt
         if (line === "exit" || line === "quit")
             break; // explicit goodbye
-        if (line === "/clear") {
-            messages = [{ role: "system", content: systemMessage }]; // drop everything but the constitution
-            forgetFilesExcept([]); // the file read-state belongs to the conversation — clear it too
-            console.log(chalk.dim("(history cleared)")); // confirm the reset
-            continue;
-        }
+        if (await handleCommand(line))
+            continue; // slash commands never reach the model
         messages.push({ role: "user", content: line }); // the new turn joins the shared history
         running = true; // Ctrl+C now means "interrupt the task"
         interrupted = false; // fresh interrupt state for this task
@@ -128,6 +276,7 @@ async function main() {
             confirm, // for permission prompts
         });
         running = false; // back at the prompt — Ctrl+C means "exit" again
+        saveSession(sessionId, CONFIG.model, messages); // snapshot after every turn — crash-safe by construction
         // 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.
@@ -139,6 +288,7 @@ async function main() {
                 break; // a bad key won't fix itself mid-session
         }
     }
+    emit("agent_session_end"); // close the books
     rl.close(); // release stdin
     console.log(chalk.dim("bye.")); // a clean goodbye
 }

package/dist/config.js

@@ -1,8 +1,9 @@
-import fs from "node:fs"; // for the minimal .env loader
+import fs from "node:fs"; // reading .env and settings files
+import os from "node:os"; // home directory for the global settings path
+import path from "node:path"; // path joining
 import chalk from "chalk"; // colored error output
 // Minimal .env loader: lets `npx mini-agent` work in any directory that has a
 // .env file — no dotenv dependency, no --env-file flag to remember.
-// Lives here (not in agent.ts) so the eval harness gets it for free too.
 try {
     for (const line of fs.readFileSync(".env", "utf8").split("\n")) {
         const m = line.match(/^([A-Za-z0-9_]+)=(.*)$/); // KEY=value, nothing fancier
@@ -13,20 +14,61 @@ try {
 catch {
     /* no .env here — the variables may come from the shell instead */
 }
-// Provider-agnostic configuration. mini-agent talks the OpenAI wire protocol,
-// so ANY compatible endpoint works — DeepSeek, OpenAI, Kimi, Qwen, GLM,
-// OpenRouter, a local Ollama... three variables and you're on a new model.
-//
-// Resolution order, most specific wins:
-//   MINI_AGENT_* (generic)  >  DEEPSEEK_* (back-compat)  >  DeepSeek defaults
+// ---- Settings files ------------------------------------------------------------
+// Two layers, both optional:
+//   global:  ~/.config/mini-agent/settings.json   (your defaults, every project)
+//   project: ./.mini-agent/settings.json          (this repo's rules, commit it if you like)
+// Scalars (model, baseURL, contextWindow): project wins over global.
+// Permission lists: BOTH layers apply — a deny from either layer is a deny.
+// API keys never live in settings files — secrets stay in the environment.
+export const GLOBAL_SETTINGS_PATH = path.join(os.homedir(), ".config", "mini-agent", "settings.json");
+export const PROJECT_SETTINGS_PATH = path.resolve(".mini-agent", "settings.json");
+// Read one settings file. A broken settings file is a HARD error, not a warning:
+// silently ignoring it would silently drop the user's deny rules — fail closed.
+function readSettings(p) {
+    if (!fs.existsSync(p))
+        return {}; // absent is fine
+    try {
+        return JSON.parse(fs.readFileSync(p, "utf8")); // parse or throw
+    }
+    catch (err) {
+        console.error(chalk.red(`Could not parse settings file: ${p}`));
+        console.error(chalk.dim(`  ${err.message}`));
+        console.error("Fix or delete the file, then run again. (Ignoring it could drop your deny rules.)");
+        process.exit(1); // fail closed — never run with half-loaded security config
+    }
+}
+const globalSettings = readSettings(GLOBAL_SETTINGS_PATH); // the user's defaults
+const projectSettings = readSettings(PROJECT_SETTINGS_PATH); // this project's rules
+// Provider-agnostic configuration. Resolution order, most specific wins:
+//   env MINI_AGENT_*  >  project settings  >  global settings  >  legacy DEEPSEEK_* env  >  defaults
 export const CONFIG = {
-    baseURL: process.env.MINI_AGENT_BASE_URL || // bring your own provider...
-        process.env.DEEPSEEK_BASE_URL || // ...or the original DeepSeek override (kept for back-compat and tests)
-        "https://api.deepseek.com", // the default provider
+    baseURL: process.env.MINI_AGENT_BASE_URL || // explicit env wins...
+        projectSettings.baseURL || // ...then the project file...
+        globalSettings.baseURL || // ...then the user's global file...
+        process.env.DEEPSEEK_BASE_URL || // ...then the legacy override (kept for back-compat and tests)
+        "https://api.deepseek.com", // ...and finally the default provider
     apiKey: process.env.MINI_AGENT_API_KEY || // generic key wins...
         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 || "deepseek-chat", // must support function calling
+    model: process.env.MINI_AGENT_MODEL || projectSettings.model || globalSettings.model || "deepseek-chat", // must support function calling
+    contextWindow: Number(process.env.MINI_AGENT_CONTEXT_WINDOW) || // env override first
+        projectSettings.contextWindow || // then files
+        globalSettings.contextWindow ||
+        1_048_565, // DeepSeek's real window, learned from an actual API error
+    permissions: {
+        // Both layers apply: global rules + project rules. Mutable on purpose —
+        // the test suite injects rules here instead of writing temp files.
+        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 ?? [])],
+    },
 };
 // No key, no point: fail with instructions instead of a stack trace later.
 export function requireApiKey() {

package/dist/context.js

@@ -1,13 +1,14 @@
 import fs from "node:fs"; // re-reading files from disk during recovery
 import chalk from "chalk"; // status lines
+import { CONFIG } from "./config.js"; // the resolved context window (env > settings files > default)
 import { recentFiles, forgetFilesExcept } from "./tools.js"; // session file state (what was read/edited, and when)
 // ---- The context window ------------------------------------------------------
-// 1,048,565 came from a real API error message, not from documentation.
+// The default (1,048,565) came from a real API error message, not from docs.
 // Trust what the API tells you over what you remember reading.
-export const CONTEXT_WINDOW = Number(process.env.MINI_AGENT_CONTEXT_WINDOW || 1_048_565); // overridable for other models
+export const CONTEXT_WINDOW = CONFIG.contextWindow; // resolved in config.ts: env > project file > global file > default
 // Compact well before the hard limit: estimation is approximate and the summary
 // itself needs room. 80% is deliberately conservative.
-export const COMPACT_AT = Number(process.env.MINI_AGENT_COMPACT_AT || Math.floor(CONTEXT_WINDOW * 0.8)); // overridable so tests can trigger compaction cheaply
+export const COMPACT_AT = Number(process.env.MINI_AGENT_COMPACT_AT || Math.floor(CONTEXT_WINDOW * 0.8)); // env override kept so tests can trigger compaction cheaply
 // How many times one query may compact / fail to compact before we give up.
 export const MAX_COMPACTIONS_PER_QUERY = 4; // a query that needs more is too big — stop, don't loop
 export const MAX_COMPACT_FAILURES = 3; // the compaction circuit breaker

package/dist/hooks.js

@@ -0,0 +1,67 @@
+import { spawn } from "node:child_process"; // hooks are external programs
+import chalk from "chalk"; // status lines
+import { CONFIG } from "./config.js"; // user-configured hooks
+import { emit } from "./telemetry.js"; // count hook activity
+// Hooks let users extend the agent without touching its source: an external
+// program runs at a lifecycle moment and can observe — or block — what happens.
+// The contract is deliberately language-agnostic (a shell command, JSON on
+// stdin, the exit code as the verdict) so a hook can be a bash one-liner, a
+// Python script, anything. This is the "keep the core small, bolt business
+// logic on via hooks" architecture.
+//
+// Communication protocol (per event):
+//   exit 0  → allow. stdout is shown to the model only for SessionStart.
+//   exit 2  → block. stderr is fed back to the model as the reason.
+//   other   → the hook itself errored; we log and treat it as allow (a broken
+//             hook must not wedge the agent — but it is loud, not silent).
+const DEFAULT_HOOK_TIMEOUT_MS = 10_000; // a hook gets 10s, then we kill it
+// Run one hook process, feeding it the event payload on stdin.
+function runOne(hook, payload) {
+    return new Promise((resolve) => {
+        const child = spawn(hook.command, { shell: true, stdio: ["pipe", "pipe", "pipe"] }); // shell so users can write one-liners
+        let stdout = "", stderr = "", settled = false; // accumulate; resolve once
+        const done = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ code, stdout: stdout.trim(), stderr: stderr.trim() });
+        };
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL"); // a hung hook is killed, never hangs the agent
+            done(124); // 124 = timed out (treated as "other" → allow, logged)
+        }, hook.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS);
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", () => done(127)); // could not start (e.g. command not found)
+        child.on("close", (code) => done(code ?? 0));
+        child.stdin.end(JSON.stringify(payload)); // the event, as JSON, on stdin
+    });
+}
+// Run every hook registered for an event, in order, and combine their verdicts.
+// `match` (when present) filters by tool name so a hook can target one tool.
+export async function runHooks(event, payload) {
+    const hooks = (CONFIG.hooks[event] ?? []).filter((h) => !h.match || h.match === payload.tool); // applicable hooks only
+    if (!hooks.length)
+        return { block: false, feedback: "", stdout: "" }; // the common case: nothing registered
+    const feedback = []; // stderr from blocking hooks
+    const stdout = []; // stdout from passing hooks
+    let block = false; // did any hook exit 2?
+    for (const hook of hooks) {
+        const { code, stdout: out, stderr: err } = await runOne(hook, { event, ...payload }); // run it
+        emit("agent_hook_run", { event, code }); // observability for hooks themselves
+        if (code === 0) {
+            if (out)
+                stdout.push(out); // passing-hook output (used by SessionStart)
+        }
+        else if (code === 2) {
+            block = true; // a blocking verdict
+            feedback.push(err || `(${event} hook blocked with no message)`); // the reason, for the model
+        }
+        else {
+            // Any other code: the hook is broken. Be loud, but do not wedge the agent.
+            console.error(chalk.yellow(`  [hook] ${event} command exited ${code} (ignored): ${(err || out).slice(0, 120)}`));
+        }
+    }
+    return { block, feedback: feedback.join("\n"), stdout: stdout.join("\n") };
+}

package/dist/loop.js

@@ -1,10 +1,12 @@
 import chalk from "chalk"; // terminal colors for status lines
 import ora from "ora"; // the "thinking..." spinner while waiting for the first token
-import { toolDefinitions, dispatch, snapshotFileState, restoreFileState } from "./tools.js"; // the tool manuals + the executor + file-state isolation
+import { toolDefinitions, dispatch, snapshotFileState, restoreFileState, isReadOnlyTool } from "./tools.js"; // the tool manuals + the executor + file-state isolation
 import { classifyError, ApiErrorKind } from "./errors.js"; // failure taxonomy
 import { checkPermission } from "./permissions.js"; // the allow/ask/deny gate
 import { estimateHistoryTokens, compactHistory, COMPACT_AT, MAX_COMPACTIONS_PER_QUERY, MAX_COMPACT_FAILURES } from "./context.js"; // context management
 import { SUB_AGENT_PROMPT } from "./prompt.js"; // the sub-agent's own constitution
+import { emit } from "./telemetry.js"; // local-only event log (no-op unless the CLI armed it)
+import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / PostToolUse / Stop)
 export const MAX_ROUNDS = 15; // model→tool round cap per query
 export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
 export const MAX_RATE_LIMIT_RETRIES = 3; // 429s get their own, much smaller budget
@@ -50,6 +52,7 @@ On error: a failed sub-agent returns [sub-agent failed: reason] — retry with a
 // Run one sub-agent: a fresh conversation, same tools minus task, same
 // permission gate, and the parent's file read-state protected by a snapshot.
 async function runSubAgent(description, opts) {
+    emit("agent_subagent_spawn"); // delegation is worth counting
     if (!opts.quiet)
         console.log(chalk.blue(`  ⎿ sub-agent started: ${description.slice(0, 100)}`)); // show the delegation
     const snapshot = snapshotFileState(); // what the sub-agent reads, the parent has NOT seen
@@ -102,14 +105,18 @@ opts) {
     // - stall (slow but alive for 30s) → log it and keep waiting
     const watchdog = setInterval(() => {
         const quietMs = Date.now() - lastEvent; // ms since the last event
-        if (quietMs > IDLE_TIMEOUT_MS)
+        if (quietMs > IDLE_TIMEOUT_MS) {
+            emit("agent_watchdog_idle"); // record the cut — these should be rare
             idleAbort.abort(); // dead — cut it
+        }
         else if (quietMs > STALL_WARN_MS && !stallWarned) {
             stallWarned = true; // don't repeat the warning every second
+            emit("agent_watchdog_stall"); // record the slowness — pattern-spotting data
             console.log(chalk.dim(`  [watchdog] stream quiet for ${Math.round(quietMs / 1000)}s — still waiting (slow ≠ dead)`));
         }
     }, 1000);
     try {
+        emit("agent_api_call"); // one event per attempt — retries show up as extra calls
         const stream = await opts.client.chat.completions.create(
         // Sub-agents do NOT get the task tool: one level of delegation only.
         // Nested spawning means orphan processes and debugging hell.
@@ -159,11 +166,70 @@ opts) {
             spinner.stop(); // and never leave a zombie spinner
     }
 }
+// Run one tool call end to end: log it, run it through the permission gate,
+// ask the human if needed, execute, and return the paired result. Read-only
+// calls (allow/deny only, never "ask") are safe to run via this from inside a
+// Promise.all batch; calls that can prompt must be awaited one at a time.
+async function runOneCall(call, opts) {
+    const indent = opts.subAgent ? chalk.blue("  ⎿ ") : ""; // sub-agent activity is visually nested
+    if (!opts.quiet)
+        console.log(indent + chalk.cyan(`🔧 ${call.name}`) + chalk.dim(` ${call.args.slice(0, 120)}`)); // show what the model wants to do
+    // The permission gate sits between the model's intent and execution.
+    const v = checkPermission(call.name, call.args);
+    emit("agent_tool_call", { tool: call.name }); // every attempt, allowed or not
+    let content; // what goes back to the model as the tool result
+    if (v.decision === "deny") {
+        emit("agent_tool_denied", { tool: call.name }); // hard blocks, per tool
+        if (!opts.quiet)
+            console.log(chalk.red(`  ⛔ denied: ${v.reason}`)); // tell the user we blocked it
+        content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
+    }
+    else if (v.decision === "ask") {
+        const ok = await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`); // pause and ask the human
+        if (!ok)
+            emit("agent_tool_declined", { tool: call.name }); // the human said no — that is signal
+        if (!ok && !opts.quiet)
+            console.log(chalk.yellow("  ✋ declined")); // make the refusal visible
+        content = ok
+            ? await runWithHooks(call, opts) // approved — run it (PreToolUse can still block)
+            : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
+    }
+    else {
+        content = await runWithHooks(call, opts); // allow — run it (PreToolUse can still block)
+    }
+    return { id: call.id, content }; // paired by id for the API
+}
+// Run an approved tool call, surrounded by the user's lifecycle hooks.
+// PreToolUse can block (exit 2) — its stderr is fed back to the model as the
+// reason, exactly like a permission denial, so the model adapts instead of
+// retrying. PostToolUse is observational; if it blocks, its message is appended
+// to the tool result as extra context (e.g. "lint failed on the file you just
+// wrote"). Sub-agents skip hooks: hooks are about the human's project policy,
+// not internal delegation.
+async function runWithHooks(call, opts) {
+    if (opts.subAgent)
+        return execute(call, opts); // sub-agents run hook-free
+    const pre = await runHooks("PreToolUse", { tool: call.name, args: call.args }); // before
+    if (pre.block) {
+        emit("agent_hook_block", { event: "PreToolUse", tool: call.name }); // a hook said no
+        if (!opts.quiet)
+            console.log(chalk.red(`  ⛔ blocked by PreToolUse hook`)); // make it visible
+        return `[hook] A PreToolUse hook blocked this call: ${pre.feedback}. Treat this as a hard boundary — adjust your approach.`;
+    }
+    const result = await execute(call, opts); // the actual work
+    const post = await runHooks("PostToolUse", { tool: call.name, args: call.args, result }); // after
+    if (post.block) {
+        // PostToolUse cannot undo the action, but it can tell the model something
+        // is wrong with the result — surface that as appended context.
+        return `${result}\n\n[hook] PostToolUse: ${post.feedback}`;
+    }
+    return result;
+}
 // Execute one approved tool call. The task tool is special — it is not in the
 // registry because running it needs the loop itself (it IS a loop).
 async function execute(call, opts) {
     if (call.name !== "task")
-        return dispatch(call.name, call.args); // ordinary tools go through the registry
+        return dispatch(call.name, call.args, opts.signal); // ordinary tools go through the registry (signal lets Ctrl+C kill run_bash)
     if (opts.subAgent)
         return "[error] Sub-agents cannot spawn sub-agents. Do the work yourself."; // one level of delegation only
     let description = ""; // the sub-task text
@@ -187,10 +253,12 @@ compaction) {
         await compactHistory(messages, opts.client, opts.model, opts.signal); // do the actual work
         compaction.count++; // one more successful compaction this query
         compaction.failures = 0; // success resets the failure streak
+        emit("agent_compaction_ok"); // worth counting — frequent compaction means tasks are too big
         return true;
     }
     catch {
         compaction.failures++; // failed — count it against the breaker
+        emit("agent_compaction_failed"); // a failure streak here trips the breaker
         return false;
     }
 }
@@ -240,6 +308,7 @@ opts) {
                 }
                 if (!e.retryable)
                     return { reason: TerminateReason.FatalApiError, detail: `${e.kind}: ${e.message}` }; // bad key etc. — stop now
+                emit("agent_api_error", { kind: e.kind, attempt: attempts.total + 1 }); // classified, greppable
                 attempts.total++; // every failure consumes the overall budget
                 attempts.consecutive++; // ...and the breaker counter
                 if (e.kind === ApiErrorKind.RateLimited)
@@ -276,33 +345,44 @@ opts) {
                     : {}), // omit the field entirely when there were no calls
             });
             if (!out.toolCalls.length) {
+                // The model wants to stop. A Stop hook gets the last word: if it exits
+                // 2, the agent is NOT done — its stderr becomes a new instruction and
+                // the loop continues. This is how you build test-driven AI: a Stop hook
+                // runs the tests, blocks while they fail, and the agent keeps fixing.
+                // Sub-agents are exempt — Stop hooks are the human's project policy.
+                if (!opts.subAgent) {
+                    const stop = await runHooks("Stop", { finalText: out.content }); // give hooks the last word
+                    if (stop.block) {
+                        emit("agent_hook_block", { event: "Stop" }); // the agent was sent back to work
+                        if (!opts.quiet)
+                            console.log(chalk.yellow(`\n↩ Stop hook: not done yet — ${stop.feedback.slice(0, 120)}`)); // show why
+                        messages.push({ role: "user", content: `[Stop hook] You are not finished: ${stop.feedback}` }); // inject the instruction
+                        break; // exit the inner while → advance the round counter (so a stubborn Stop hook is still bounded by MAX_ROUNDS)
+                    }
+                }
                 return { reason: TerminateReason.Done, finalText: out.content }; // no tool calls = final answer (already streamed to the screen)
             }
-            // Execute every tool call, each behind the permission gate.
-            for (const call of out.toolCalls) {
-                const indent = opts.subAgent ? chalk.blue("  ⎿ ") : ""; // sub-agent activity is visually nested
-                if (!opts.quiet)
-                    console.log(indent + chalk.cyan(`🔧 ${call.name}`) + chalk.dim(` ${call.args.slice(0, 120)}`)); // show what the model wants to do
-                // The permission gate sits between the model's intent and execution.
-                const v = checkPermission(call.name, call.args);
-                let content; // what goes back to the model as the tool result
-                if (v.decision === "deny") {
-                    if (!opts.quiet)
-                        console.log(chalk.red(`  ⛔ denied: ${v.reason}`)); // tell the user we blocked it
-                    content = `[permission] Denied: ${v.reason}. This is a hard rule — do not try to work around it; pick a different approach or ask the user.`; // teach the model the boundary
-                }
-                else if (v.decision === "ask") {
-                    const ok = await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}`); // pause and ask the human
-                    if (!ok && !opts.quiet)
-                        console.log(chalk.yellow("  ✋ declined")); // make the refusal visible
-                    content = ok
-                        ? await execute(call, opts) // approved — actually run it
-                        : `[permission] The user declined this action. Ask them how to proceed, or choose a safer alternative.`; // declined — tell the model
-                }
-                else {
-                    content = await execute(call, opts); // allow — run without ceremony
+            // Execute the tool calls. Read-only calls (read_file/search) in a
+            // contiguous run are executed CONCURRENTLY — they cannot conflict and
+            // never need an interactive prompt. Anything that writes or executes runs
+            // ALONE and in order: writes can depend on each other, and we can only ask
+            // the human one question at a time. This greedy batching mirrors how
+            // Claude Code parallelizes safe reads while serializing risky work.
+            let i = 0; // index into out.toolCalls
+            while (i < out.toolCalls.length) {
+                const batch = []; // a run of safe, parallelizable calls
+                while (i < out.toolCalls.length && isReadOnlyTool(out.toolCalls[i].name))
+                    batch.push(out.toolCalls[i++]);
+                if (batch.length) {
+                    // Run the whole read-only batch at once, preserving result order.
+                    const results = await Promise.all(batch.map((c) => runOneCall(c, opts)));
+                    for (const r of results)
+                        messages.push({ role: "tool", tool_call_id: r.id, content: r.content });
+                    continue; // back to the top — the next call is non-read-only
                 }
-                messages.push({ role: "tool", tool_call_id: call.id, content }); // feed the result back, paired by id
+                // A single non-read-only call: gate, maybe ask, execute — all serial.
+                const r = await runOneCall(out.toolCalls[i++], opts);
+                messages.push({ role: "tool", tool_call_id: r.id, content: r.content });
             }
             break; // round complete, move to the next one
         }

package/dist/permissions.js

@@ -1,4 +1,5 @@
 import path from "node:path"; // used to resolve and split file paths
+import { CONFIG } from "./config.js"; // user-configured allow/deny rules from settings files
 // ---- The no-fly zone --------------------------------------------------------
 // Writes here are never OK, in any mode. .git can destroy history, shell rc
 // files inject code into every future terminal, .ssh/.env leak credentials.
@@ -43,13 +44,26 @@ const BASH_ASK = [
 // Single, read-only-ish commands that run without asking.
 const BASH_ALLOW = new Set(["ls", "pwd", "echo", "wc", "which", "date", "node", "npm", "npx", "cat", "head", "tail"]);
 const GIT_READONLY = new Set(["status", "log", "diff", "show", "branch", "remote", "tag"]); // git subcommands that only read
+// User rules from settings files, split by kind. Computed per call (not cached)
+// so the test suite can mutate CONFIG.permissions and see the effect.
+function userBashRules() {
+    return {
+        allow: CONFIG.permissions.allow.filter((r) => !r.startsWith("tool:")), // bash first-words to trust
+        deny: CONFIG.permissions.deny.filter((r) => !r.startsWith("tool:")), // command substrings to block
+    };
+}
 // Decide what a bash command deserves: deny, ask, or allow.
 function checkBash(command) {
     const summary = command.trim(); // what the user will see in the prompt
-    // Order is the security model: deny first, ask second, allow last.
+    const user = userBashRules(); // the user's configured additions
+    // Order is the security model: built-in deny, then user deny, then ask,
+    // then allow. A user allow can never jump this queue — allow is checked last.
     for (const [re, why] of BASH_DENY)
         if (re.test(command))
             return { decision: "deny", reason: why, summary };
+    for (const d of user.deny)
+        if (command.toLowerCase().includes(d.toLowerCase()))
+            return { decision: "deny", reason: `denied by your settings ("${d}")`, summary };
     for (const [re, why] of BASH_ASK)
         if (re.test(command))
             return { decision: "ask", reason: why, summary };
@@ -61,12 +75,18 @@ function checkBash(command) {
         return { decision: "allow", reason: "read-only git", summary }; // safe git subcommands
     if (BASH_ALLOW.has(words[0]))
         return { decision: "allow", reason: "safe command", summary }; // known-harmless single command
+    if (user.allow.includes(words[0]))
+        return { decision: "allow", reason: "allowed by your settings", summary }; // the user vouched for this command
     // Fail closed: a command we don't recognize is a question for the human.
     return { decision: "ask", reason: "unrecognized command", summary };
 }
 // ---- The single entry point ---------------------------------------------------
 // Called by the loop for EVERY tool call, before anything executes.
 export function checkPermission(toolName, argsJson) {
+    // A user-configured tool block beats everything, including built-in allows.
+    if (CONFIG.permissions.deny.includes(`tool:${toolName}`)) {
+        return { decision: "deny", reason: `tool blocked by your settings ("tool:${toolName}")`, summary: toolName };
+    }
     let args; // the parsed tool arguments
     try {
         args = JSON.parse(argsJson); // arguments arrive as a raw JSON string from the model
@@ -95,6 +115,12 @@ export function checkPermission(toolName, argsJson) {
             const hit = noFlyHit(p); // is it in the no-fly zone?
             if (hit)
                 return { decision: "deny", reason: hit, summary: p }; // hard stop — deny always wins
+            // The user may pre-approve write tools ("tool:edit_file") to skip the
+            // prompt — note this runs AFTER the no-fly check, so it widens "ask",
+            // never "deny".
+            if (CONFIG.permissions.allow.includes(`tool:${toolName}`)) {
+                return { decision: "allow", reason: "pre-approved by your settings", summary: p };
+            }
             return { decision: "ask", reason: "writes to your filesystem", summary: p }; // normal writes need a human yes
         }
         case "run_bash":

package/dist/session.js

@@ -0,0 +1,61 @@
+import fs from "node:fs"; // session files live on disk
+import path from "node:path"; // path joining
+// Sessions are project-local: .mini-agent/sessions/<id>.json under the cwd.
+// Project-local (not global) because a conversation is about a codebase —
+// resuming a refactor of project A from inside project B makes no sense.
+const SESSIONS_DIR = path.resolve(".mini-agent", "sessions");
+const KEEP_SESSIONS = 20; // how many session files survive pruning
+// A fresh, filename-safe session id derived from the wall clock.
+export function newSessionId() {
+    return new Date().toISOString().replace(/[:.]/g, "-"); // 2026-06-12T10-30-00-000Z
+}
+// Persist the conversation. Full snapshot, atomically (tmp + rename): the
+// history is not append-only — compaction rewrites it — so a snapshot is the
+// only representation that is always correct. Crash mid-write leaves the
+// previous snapshot intact.
+export function saveSession(id, model, messages) {
+    fs.mkdirSync(SESSIONS_DIR, { recursive: true }); // first save creates the directory
+    const file = path.join(SESSIONS_DIR, `${id}.json`); // the real destination
+    const existing = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null; // to preserve startedAt
+    const data = {
+        id,
+        startedAt: existing?.startedAt ?? new Date().toISOString(), // first save stamps it, later saves keep it
+        savedAt: new Date().toISOString(), // always refreshed
+        model, // informational — resume does not force the same model
+        messages: messages.filter((m) => m.role !== "system"), // the constitution is rebuilt fresh on resume (AGENT.md may have changed)
+    };
+    const tmp = `${file}.tmp`; // write next to the destination (same filesystem → rename is atomic)
+    fs.writeFileSync(tmp, JSON.stringify(data)); // the new snapshot
+    fs.renameSync(tmp, file); // atomic swap
+    prune(); // keep the directory bounded
+}
+// Load the most recent session, or null if there is none (or it is unreadable —
+// a corrupt session file should not kill the CLI, just start fresh).
+export function latestSession() {
+    if (!fs.existsSync(SESSIONS_DIR))
+        return null; // nothing ever saved here
+    const files = fs
+        .readdirSync(SESSIONS_DIR)
+        .filter((f) => f.endsWith(".json")) // ignore tmp files and strangers
+        .map((f) => ({ f, mtime: fs.statSync(path.join(SESSIONS_DIR, f)).mtimeMs })) // newest by modification time
+        .sort((a, b) => b.mtime - a.mtime);
+    if (!files.length)
+        return null; // empty directory
+    try {
+        return JSON.parse(fs.readFileSync(path.join(SESSIONS_DIR, files[0].f), "utf8")); // the newest snapshot
+    }
+    catch {
+        return null; // unreadable — treat as absent, never crash on resume
+    }
+}
+// Delete everything beyond the newest KEEP_SESSIONS files. A CLI that quietly
+// accumulates unbounded state in every project directory is not industrial.
+function prune() {
+    const files = fs
+        .readdirSync(SESSIONS_DIR)
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => ({ f, mtime: fs.statSync(path.join(SESSIONS_DIR, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime); // newest first
+    for (const { f } of files.slice(KEEP_SESSIONS))
+        fs.rmSync(path.join(SESSIONS_DIR, f)); // drop the tail
+}

package/dist/telemetry.js

@@ -0,0 +1,43 @@
+import fs from "node:fs"; // the event log lives on disk
+import path from "node:path"; // path joining
+// LOCAL-ONLY telemetry. Events go to .mini-agent/telemetry.jsonl in the
+// project directory and NOWHERE else — nothing leaves the machine, ever.
+// It exists because "no data" means every optimization is a guess: which
+// errors actually happen, how often compaction fires, which tools get denied.
+// Opt out entirely with MINI_AGENT_NO_TELEMETRY=1.
+//
+// Naming follows the unified-prefix convention (agent_<domain>_<action>) so
+// the log stays greppable: `grep agent_api_error telemetry.jsonl | wc -l`.
+const TELEMETRY_FILE = path.resolve(".mini-agent", "telemetry.jsonl");
+let sessionId = null; // set by initTelemetry; emit() is a no-op before that
+const tallies = new Map(); // per-session event counts, for /stats
+// Arm telemetry for this session. Tests and the eval harness never call this,
+// so library use stays silent — only the real CLI writes events.
+export function initTelemetry(id) {
+    if (process.env.MINI_AGENT_NO_TELEMETRY === "1")
+        return; // the user opted out — stay disarmed
+    sessionId = id; // armed
+}
+// Record one event. Never throws: a telemetry failure must never break work.
+export function emit(event, fields = {}) {
+    const key = event + (fields.tool ? `:${fields.tool}` : ""); // tool events tally per tool name
+    tallies.set(key, (tallies.get(key) ?? 0) + 1); // /stats counts even when disarmed
+    if (!sessionId)
+        return; // disarmed — counters only, no file
+    try {
+        fs.mkdirSync(path.dirname(TELEMETRY_FILE), { recursive: true }); // ensure the directory
+        fs.appendFileSync(TELEMETRY_FILE, JSON.stringify({ ts: new Date().toISOString(), session: sessionId, event, ...fields }) + "\n"); // one JSON object per line
+    }
+    catch {
+        /* a full disk or a read-only checkout is not our problem to escalate */
+    }
+}
+// The per-session tallies, sorted by count — the data behind /stats.
+export function statsReport() {
+    if (!tallies.size)
+        return "(no events this session yet)"; // nothing happened
+    const lines = [...tallies.entries()]
+        .sort((a, b) => b[1] - a[1]) // busiest first
+        .map(([k, n]) => `  ${String(n).padStart(5)}  ${k}`); // aligned counts
+    return ["events this session:", ...lines, `\nfull log: ${TELEMETRY_FILE} (local only — nothing leaves this machine)`].join("\n");
+}

package/dist/tools.js

@@ -1,6 +1,7 @@
 import fs from "node:fs"; // filesystem reads and writes
+import os from "node:os"; // temp dir for spilled tool output
 import path from "node:path"; // path resolution and joining
-import { execSync } from "node:child_process"; // runs a shell command and waits for it
+import { spawn } from "node:child_process"; // async process execution (does NOT block the event loop)
 // ============ Session state ============
 // The foundation of "read before edit": which files has this session actually read?
 // Files that were never read must not be edited — otherwise the model edits from
@@ -15,6 +16,9 @@ const TOOL_RESULT_LIMIT = 4000; // cap (chars) for a normal tool result entering
 const READ_LIMIT = 16000; // read_file gets a larger cap of its own
 const SEARCH_MAX_MATCHES = 50; // max matches returned by search
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build"]); // directories search never enters
+const BASH_TIMEOUT_MS = 30_000; // a single command may run this long before we kill it
+const BASH_OUTPUT_LIMIT = 8_000; // chars of command output kept inline; beyond this we spill to a file
+const SPILL_NOTE_SLACK = 400; // room for the "[...saved to FILE]" note so dispatch's cap never eats it
 // Errors are not exceptions — they are text that tells the model what to do next.
 const fail = (msg) => `[error] ${msg}`;
 // Small helper to build a tool definition without repeating boilerplate.
@@ -165,24 +169,66 @@ ALWAYS use this tool to search. NEVER run grep/rg/find via run_bash.`, {
     },
 };
 // ============ run_bash ============
+// Spill oversized output to a file and hand the model a preview + the path, so
+// it can read_file deeper if it wants. Returning megabytes inline would blow up
+// the context; truncating silently would hide the part that matters.
+function spillIfHuge(out, what) {
+    if (out.length <= BASH_OUTPUT_LIMIT)
+        return out; // fits inline — return as-is
+    const file = path.join(os.tmpdir(), `mini-agent-output-${Date.now()}.txt`); // a stable place to find it
+    fs.writeFileSync(file, out, "utf8"); // the full output lives on disk
+    const head = out.slice(0, BASH_OUTPUT_LIMIT); // a generous preview
+    return `${head}\n\n[...${what} truncated: ${out.length} chars total. Full output saved to ${file} — use read_file to inspect more.]`;
+}
 const runBash = {
     definition: def("run_bash", `Run a bash command on the user's machine (30s timeout) and return its output.
 Boundaries: only for things that truly need execution — installing dependencies, running tests/scripts, git operations.
 To read files use read_file (not cat), to search use search (not grep/find), to edit files use edit_file (not sed/redirection).
 Dangerous commands require user approval; some are denied outright. A [permission] result is a hard boundary — never try to work around it.
 On error: failures return the error output — analyze it and try a different approach; do not resend the same command unchanged.`, { command: { type: "string", description: "The bash command to run" } }, ["command"]),
-    run: (args) => {
-        try {
-            // stderr is piped (not inherited): it belongs in the tool result for the
-            // model to read, not splattered onto the user's terminal.
-            const out = execSync(args.command, { encoding: "utf8", timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] });
-            return out || "(command succeeded, no output)"; // never return an empty string
-        }
-        catch (err) {
-            const e = err; // execSync attaches the captured stderr on failure
-            return fail(`Command failed: ${e.message}${e.stderr ? `\nstderr: ${e.stderr.slice(0, 1000)}` : ""}`); // failure becomes guidance, not a crash
-        }
-    },
+    // Async + spawn: the event loop stays responsive while the command runs, so
+    // the spinner keeps spinning and Ctrl+C is heard. execSync would freeze
+    // everything — the whole process, the UI, the signal handler — until it
+    // returned. The AbortSignal lets the loop kill the child on interruption
+    // instead of waiting out the 30s timeout.
+    run: (args, signal) => new Promise((resolve) => {
+        const child = spawn(args.command, { shell: true, stdio: ["ignore", "pipe", "pipe"] }); // shell:true → bash semantics
+        let stdout = ""; // captured stdout
+        let stderr = ""; // captured stderr (for the model, not the user's terminal)
+        let settled = false; // resolve exactly once
+        const done = (text) => {
+            if (settled)
+                return; // guard against timeout/exit/abort racing
+            settled = true;
+            clearTimeout(timer); // stop the watchdog
+            signal?.removeEventListener("abort", onAbort); // unhook
+            resolve(text); // hand the result back
+        };
+        // Hard timeout: SIGKILL the whole process group, never hang the agent.
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            done(fail(`Command timed out after ${BASH_TIMEOUT_MS / 1000}s and was killed.${stdout ? `\npartial stdout:\n${stdout.slice(0, 2000)}` : ""}`));
+        }, BASH_TIMEOUT_MS);
+        // Ctrl+C while a command runs: kill the child immediately.
+        const onAbort = () => {
+            child.kill("SIGKILL");
+            done(fail("Command was interrupted by the user."));
+        };
+        signal?.addEventListener("abort", onAbort);
+        child.stdout.on("data", (d) => (stdout += d)); // accumulate
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (err) => done(fail(`Could not start command: ${err.message}`))); // e.g. command not found at the spawn level
+        child.on("close", (code) => {
+            if (code === 0) {
+                done(spillIfHuge(stdout, "output") || "(command succeeded, no output)"); // success
+            }
+            else {
+                // Non-zero exit: combine streams so the model sees the actual error.
+                const combined = [stdout && `stdout:\n${stdout}`, stderr && `stderr:\n${stderr}`].filter(Boolean).join("\n");
+                done(fail(`Command exited with code ${code}.\n${spillIfHuge(combined, "error output")}`));
+            }
+        });
+    }),
 };
 // ============ Registry & dispatch ============
 // One place that knows every tool. Adding a tool = adding one entry here.
@@ -195,9 +241,16 @@ export const tools = {
 };
 // The list of manuals sent to the model on every API call.
 export const toolDefinitions = Object.values(tools).map((t) => t.definition);
+// Read-only tools never touch the filesystem in a conflicting way, so the loop
+// is free to run a batch of them concurrently. Anything that writes or executes
+// runs alone, in order. (See loop.ts for the batching.)
+const READ_ONLY_TOOLS = new Set(["read_file", "search"]);
+export const isReadOnlyTool = (name) => READ_ONLY_TOOLS.has(name);
 // Single entry point: every failure becomes text fed back to the model.
-// It never throws — the main loop must never die because of a tool.
-export function dispatch(name, argsJson) {
+// It never throws — the main loop must never die because of a tool. Async since
+// Day 13 so run_bash can spawn without blocking; the signal lets Ctrl+C kill a
+// running command.
+export async function dispatch(name, argsJson, signal) {
     const tool = tools[name]; // look the tool up by name
     if (!tool)
         return fail(`Unknown tool: ${name}. Available tools: ${Object.keys(tools).join(", ")}`); // model hallucinated a tool → list the real ones
@@ -208,8 +261,14 @@ export function dispatch(name, argsJson) {
     catch {
         return fail(`Arguments are not valid JSON: ${argsJson.slice(0, 200)}`); // malformed JSON → show what we got
     }
+    // Each tool gets a result cap sized to its job. run_bash already manages its
+    // own output (preview + spill-to-disk via spillIfHuge); its cap must leave
+    // room for the spill note, or dispatch would chop off the very pointer the
+    // model needs to read the rest.
+    const cap = name === "read_file" ? READ_LIMIT + 100 : name === "run_bash" ? BASH_OUTPUT_LIMIT + SPILL_NOTE_SLACK : TOOL_RESULT_LIMIT;
     try {
-        return tool.run(args).slice(0, name === "read_file" ? READ_LIMIT + 100 : TOOL_RESULT_LIMIT); // run it, cap the result size
+        const result = await tool.run(args, signal); // await covers both sync and async tools
+        return result.slice(0, cap); // cap the result size
     }
     catch (err) {
         return fail(`Tool crashed: ${err.message}`); // even a crashing tool becomes a readable result

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-from-zero",
-  "version": "0.1.0",
-  "description": "A Claude Code-style CLI agent built from scratch with the DeepSeek API — companion code for a 10-day tutorial",
+  "version": "0.5.0",
+  "description": "Build a Claude Code-style CLI agent from scratch, with AI as your pair programmer — companion code for a 10-day tutorial (DeepSeek by default, any OpenAI-compatible model)",
   "type": "module",
   "bin": {
     "mini-agent": "dist/agent.js"
@@ -15,7 +15,8 @@
     "typecheck": "tsc --noEmit",
     "eval": "tsx --env-file=.env eval/run.ts",
     "build": "tsc -p tsconfig.build.json",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "test": "tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts"
   },
   "engines": {
     "node": ">=20.6"