agent-from-zero 0.1.0 → 0.27.0

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,21 +14,96 @@ 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
+    // 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 ||
+        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 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)

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/cost.js

@@ -0,0 +1,93 @@
+// Token & cost accounting. The most-emphasized lesson of the Harness book is
+// token economics: "cache breaks are silent", "90% of the bill is re-sending
+// the same prompt". You cannot manage what you cannot see — so every model
+// call's usage is metered, and /cost shows tokens, the cache hit rate, and an
+// estimated spend. Nothing here leaves the machine; it is just arithmetic over
+// the `usage` the API already returns.
+export const DEFAULT_PRICING = {
+    inputPerM: 0.27, // $ / 1M — check your provider; override in settings.pricing
+    cachedInputPerM: 0.07, // cache hits are ~4x cheaper — this is why hit rate matters
+    outputPerM: 1.1, // output is the pricey one — don't let the model ramble
+};
+// Normalize a provider `usage` object into our four fields. Handles DeepSeek
+// (prompt_cache_hit_tokens / prompt_cache_miss_tokens) and OpenAI
+// (prompt_tokens_details.cached_tokens) shapes; falls back gracefully.
+export function normalizeUsage(usage) {
+    if (!usage)
+        return { inputUncached: 0, inputCached: 0, output: 0 };
+    const prompt = Number(usage.prompt_tokens ?? 0); // total input tokens
+    const output = Number(usage.completion_tokens ?? 0); // total output tokens
+    // DeepSeek reports the split directly:
+    const dsHit = Number(usage.prompt_cache_hit_tokens ?? NaN);
+    const dsMiss = Number(usage.prompt_cache_miss_tokens ?? NaN);
+    if (!Number.isNaN(dsHit) && !Number.isNaN(dsMiss)) {
+        return { inputUncached: dsMiss, inputCached: dsHit, output };
+    }
+    // OpenAI reports only the cached count, nested:
+    const details = usage.prompt_tokens_details;
+    const cached = Number(details?.cached_tokens ?? 0);
+    return { inputUncached: Math.max(0, prompt - cached), inputCached: cached, output };
+}
+// Estimated dollar cost of some usage under some pricing. Pure — easy to test.
+export function costOf(u, p) {
+    return (u.inputUncached * p.inputPerM + u.inputCached * p.cachedInputPerM + u.output * p.outputPerM) / 1_000_000;
+}
+// Cache hit rate over input tokens, 0..1. The single most useful number for
+// spotting a silent cache break: if it drops, you are paying full price for a
+// prefix that should have been free.
+export function cacheHitRate(u) {
+    const input = u.inputUncached + u.inputCached;
+    return input === 0 ? 0 : u.inputCached / input;
+}
+// The process-wide meter. The loop records into it from every stream; the CLI
+// builds it once (with the configured prices) and /cost reads it. A module
+// singleton because metering is ambient — threading it through every call would
+// add noise for a cross-cutting concern. Tests construct their own CostMeter.
+let sessionMeter = null;
+export function initCostMeter(pricing) {
+    sessionMeter = new CostMeter(pricing);
+    return sessionMeter;
+}
+export function recordUsage(usage) {
+    sessionMeter?.record(usage); // no-op until the CLI initializes it (tests stay silent)
+}
+// Accumulates usage across a session and formats /cost.
+export class CostMeter {
+    pricing;
+    total = { inputUncached: 0, inputCached: 0, output: 0 };
+    calls = 0; // how many model calls were metered
+    constructor(pricing) {
+        this.pricing = pricing;
+    }
+    // Fold one response's usage into the running total.
+    record(usage) {
+        const u = normalizeUsage(usage);
+        if (u.inputUncached + u.inputCached + u.output === 0)
+            return; // a chunk with no usage — ignore
+        this.total.inputUncached += u.inputUncached;
+        this.total.inputCached += u.inputCached;
+        this.total.output += u.output;
+        this.calls++;
+    }
+    // Numbers for the status line: estimated spend so far and total tokens.
+    cost() {
+        return costOf(this.total, this.pricing);
+    }
+    inputTokens() {
+        return this.total.inputUncached + this.total.inputCached;
+    }
+    outputTokens() {
+        return this.total.output;
+    }
+    // The /cost report. Estimated, local-only.
+    report() {
+        const t = this.total;
+        const input = t.inputUncached + t.inputCached;
+        return [
+            `tokens this session (${this.calls} model calls):`,
+            `  input:  ${input} (${t.inputCached} cached, ${(cacheHitRate(t) * 100).toFixed(0)}% hit rate)`,
+            `  output: ${t.output}`,
+            `  estimated cost: $${costOf(t, this.pricing).toFixed(4)} (rough — prices set in settings.pricing)`,
+        ].join("\n");
+    }
+}

package/dist/diff.js

@@ -0,0 +1,135 @@
+import fs from "node:fs"; // read the target file to diff against
+import path from "node:path"; // resolve the file path
+import chalk from "chalk"; // color the +/- lines (auto-disabled when output isn't a TTY)
+// Longest-common-subsequence over lines → an ordered list of ops. Classic DP:
+// lcs[i][j] = length of the LCS of a[i:] and b[j:]. Walking it forwards turns the
+// table into the smallest set of removals + additions that turns a into b.
+export function diffLines(oldText, newText) {
+    const a = oldText.length ? oldText.split("\n") : []; // empty string = no lines (not [""])
+    const b = newText.length ? newText.split("\n") : [];
+    const n = a.length;
+    const m = b.length;
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0)); // (n+1)×(m+1), last row/col are zeros
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]); // match extends the subsequence; else take the better side
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j])
+            ops.push({ kind: " ", line: a[i++] }), j++; // common line — keep it as context
+        else if (lcs[i + 1][j] >= lcs[i][j + 1])
+            ops.push({ kind: "-", line: a[i++] }); // dropping a[i] keeps more of the LCS → it was removed
+        else
+            ops.push({ kind: "+", line: b[j++] }); // otherwise b[j] is an addition
+    }
+    while (i < n)
+        ops.push({ kind: "-", line: a[i++] }); // leftover old lines were all removed
+    while (j < m)
+        ops.push({ kind: "+", line: b[j++] }); // leftover new lines were all added
+    return ops;
+}
+const CONTEXT = 3; // unchanged lines to keep around each change, for readability
+const MAX_LINES = 60; // hard cap on rendered lines — a huge diff must not flood the prompt
+// Paint one line by its kind. chalk no-ops when colors are off, so the plain
+// text is always present (and assertable in tests).
+function paint(kind, text) {
+    if (kind === "+")
+        return chalk.green(text);
+    if (kind === "-")
+        return chalk.red(text);
+    return chalk.dim(text);
+}
+// Render ops as a compact unified diff: a "+A -B" summary header, the changed
+// lines with a few lines of context, and long runs of untouched lines collapsed
+// to a "⋮ (N unchanged lines)" marker so the reader sees the change, not the file.
+export function renderDiff(oldText, newText, color = true) {
+    const ops = diffLines(oldText, newText);
+    const added = ops.filter((o) => o.kind === "+").length;
+    const removed = ops.filter((o) => o.kind === "-").length;
+    // Keep any unchanged line within CONTEXT of a change; drop the rest.
+    const keep = new Array(ops.length).fill(false);
+    ops.forEach((op, idx) => {
+        if (op.kind === " ")
+            return;
+        for (let k = Math.max(0, idx - CONTEXT); k <= Math.min(ops.length - 1, idx + CONTEXT); k++)
+            keep[k] = true;
+    });
+    const out = [];
+    let i = 0;
+    while (i < ops.length) {
+        if (keep[i]) {
+            out.push(color ? paint(ops[i].kind, `${ops[i].kind} ${ops[i].line}`) : `${ops[i].kind} ${ops[i].line}`);
+            i++;
+        }
+        else {
+            let skipped = 0;
+            while (i < ops.length && !keep[i])
+                skipped++, i++; // collapse the whole untouched run at once
+            const note = `   ⋮ (${skipped} unchanged line${skipped === 1 ? "" : "s"})`;
+            out.push(color ? chalk.dim(note) : note);
+        }
+    }
+    const body = out.length > MAX_LINES ? [...out.slice(0, MAX_LINES), `   … (${out.length - MAX_LINES} more diff lines)`] : out;
+    const header = `  +${added} -${removed}`;
+    return [color ? chalk.dim(header) : header, ...body].join("\n");
+}
+const MAX_PREVIEW_BYTES = 200_000; // don't read+diff an enormous file just to preview it
+// Read a file for diffing, or null if it shouldn't be diffed (missing, too big,
+// or binary). A preview must never break a tool call, so every failure is null.
+function safeRead(p) {
+    try {
+        if (fs.statSync(p).size > MAX_PREVIEW_BYTES)
+            return null; // too big to preview cheaply
+        const text = fs.readFileSync(p, "utf8");
+        return text.includes("\0") ? null : text; // a NUL byte means binary — don't diff it
+    }
+    catch {
+        return null; // unreadable / missing
+    }
+}
+// Build the diff preview shown before a write/edit runs. Returns null when there
+// is nothing useful to show (not a write tool, unparseable args, binary file).
+// NEVER throws.
+export function previewChange(toolName, argsJson) {
+    let args;
+    try {
+        args = JSON.parse(argsJson);
+    }
+    catch {
+        return null; // dispatch will report the JSON error; nothing to preview
+    }
+    try {
+        if (toolName === "write_file") {
+            const p = path.resolve(args.path ?? "");
+            const exists = fs.existsSync(p);
+            const oldText = exists ? safeRead(p) : ""; // new file → empty "before"
+            if (oldText === null)
+                return null; // existing but binary/oversized
+            return `  ${exists ? "overwrite" : "create"} ${args.path}\n${renderDiff(oldText, String(args.content ?? ""))}`;
+        }
+        if (toolName === "edit_file") {
+            const p = path.resolve(args.path ?? "");
+            if (!fs.existsSync(p))
+                return null; // edit of a missing file → the tool will error
+            const oldText = safeRead(p);
+            if (oldText === null)
+                return null;
+            const occurrences = args.old_string ? oldText.split(args.old_string).length - 1 : 0;
+            // The tool only applies a unique match. If it's unique, diff the real
+            // before/after; otherwise just show the intended swap (the tool will
+            // reject a 0/ambiguous match anyway, but the human still sees the intent).
+            const newText = occurrences === 1 ? oldText.split(args.old_string).join(args.new_string ?? "") : null;
+            return newText !== null
+                ? `  edit ${args.path}\n${renderDiff(oldText, newText)}`
+                : `  edit ${args.path}\n${renderDiff(String(args.old_string ?? ""), String(args.new_string ?? ""))}`;
+        }
+    }
+    catch {
+        return null; // anything unexpected → no preview, never a crash
+    }
+    return null; // not a file-changing tool
+}

package/dist/form.js

@@ -0,0 +1,78 @@
+import chalk from "chalk"; // rendering only
+// The rows are a flat list: every option of every question, then one submit row.
+// rowCount = total options + 1. The cursor walks this flat list.
+export function formRowCount(questions) {
+    return questions.reduce((n, q) => n + q.options.length, 0) + 1; // +1 for "Submit"
+}
+// Map a flat cursor to either a question/option, or the submit row.
+export function rowAt(questions, cursor) {
+    let i = cursor;
+    for (let q = 0; q < questions.length; q++) {
+        if (i < questions[q].options.length)
+            return { q, opt: i };
+        i -= questions[q].options.length;
+    }
+    return { submit: true };
+}
+// The flat cursor position of a question's first option — used to jump the
+// cursor to the first unanswered question when the user tries to submit early.
+function cursorForQuestion(questions, q) {
+    let c = 0;
+    for (let i = 0; i < q; i++)
+        c += questions[i].options.length;
+    return c;
+}
+export function initFormState(questions) {
+    return { cursor: 0, selections: questions.map(() => -1) }; // nothing chosen yet
+}
+// The one transition function. Returns the next state, and `done: true` only
+// when the user submits with every question answered.
+export function reduceForm(questions, state, action) {
+    const rows = formRowCount(questions);
+    if (action === "up")
+        return { state: { ...state, cursor: Math.max(0, state.cursor - 1) } };
+    if (action === "down")
+        return { state: { ...state, cursor: Math.min(rows - 1, state.cursor + 1) } };
+    // select (Enter / Space)
+    const row = rowAt(questions, state.cursor);
+    if ("submit" in row) {
+        const firstUnanswered = state.selections.findIndex((s) => s < 0);
+        if (firstUnanswered < 0)
+            return { state, done: true }; // all answered → submit for real
+        return { state: { ...state, cursor: cursorForQuestion(questions, firstUnanswered) } }; // nudge to the gap
+    }
+    const selections = state.selections.slice();
+    selections[row.q] = row.opt; // set this question's answer (single-select)
+    return { state: { ...state, selections } };
+}
+// Turn a completed form into question→answer pairs for the model.
+export function collectAnswers(questions, state) {
+    return questions.map((q, i) => ({ question: q.question, answer: q.options[state.selections[i]] ?? "(unanswered)" }));
+}
+const FORM_HINT = chalk.dim("↑↓ to move · Enter to choose / submit · Esc to cancel");
+// Render the whole form: each question with radio-style options, the cursor on
+// one row, then a submit row. Line count is constant for a given question set
+// (selections don't add/remove lines), which is what lets the driver redraw in
+// place by moving the cursor up a fixed number of lines.
+export function renderForm(questions, state) {
+    const lines = ["The agent needs your input:", ""];
+    let flat = 0;
+    questions.forEach((q, qi) => {
+        lines.push(chalk.bold(`${qi + 1}. ${q.question}`));
+        q.options.forEach((opt, oi) => {
+            const onCursor = state.cursor === flat;
+            const chosen = state.selections[qi] === oi;
+            const text = `${chosen ? "●" : "○"} ${opt}`; // filled radio = chosen
+            lines.push(onCursor ? chalk.cyan.bold(`❯ ${text}`) : chosen ? chalk.cyan(`  ${text}`) : chalk.dim(`  ${text}`));
+            flat++;
+        });
+        lines.push("");
+    });
+    const onSubmit = state.cursor === flat; // the submit row is last
+    const allAnswered = state.selections.every((s) => s >= 0);
+    const submitText = allAnswered ? "▶ Submit answers" : "▶ Submit answers (answer every question first)";
+    lines.push(onSubmit ? chalk.green.bold(`❯ ${submitText}`) : chalk.dim(`  ${submitText}`));
+    lines.push("");
+    lines.push(FORM_HINT);
+    return lines.join("\n");
+}

package/dist/hooks.js

@@ -0,0 +1,92 @@
+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 captured (SessionStart/UserPromptSubmit inject it
+//             as context; a PreToolUse hook may emit {"toolInput":{…}} to REWRITE
+//             the tool's arguments — something the 3-state permission gate can't).
+//   exit 2  → block. stderr is fed back to the model. The MEANING of "block"
+//             differs by event and is the caller's to interpret (PreToolUse →
+//             don't run; Stop → keep going; UserPromptSubmit → drop the prompt;
+//             observational events just ignore it).
+//   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; // most hooks get 10s, then we kill it
+// Differentiated timeouts: SessionEnd fires when the user is leaving (often via
+// Ctrl+C) — it MUST return almost instantly, so it gets a tiny budget.
+const EVENT_TIMEOUT_MS = { SessionEnd: 1_500 };
+// Run one hook process, feeding it the event payload on stdin.
+function runOne(hook, payload, timeoutMs) {
+    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 ?? timeoutMs);
+        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?
+    let rewrite; // a PreToolUse hook's replacement args
+    const timeout = EVENT_TIMEOUT_MS[event] ?? DEFAULT_HOOK_TIMEOUT_MS; // SessionEnd gets a tiny budget
+    for (const hook of hooks) {
+        const { code, stdout: out, stderr: err } = await runOne(hook, { event, ...payload }, timeout); // 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 / UserPromptSubmit)
+                // A PreToolUse hook can REWRITE the tool's arguments by printing
+                // {"toolInput": {...}} — the "side road" the permission gate can't take
+                // (it only allows/denies). Classic use: rewrite `git commit` to add a
+                // trailer. Last writer wins if several hooks rewrite.
+                if (event === "PreToolUse") {
+                    try {
+                        const parsed = JSON.parse(out);
+                        if (parsed && parsed.toolInput && typeof parsed.toolInput === "object")
+                            rewrite = JSON.stringify(parsed.toolInput);
+                    }
+                    catch {
+                        /* not control JSON — just plain stdout */
+                    }
+                }
+            }
+        }
+        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"), rewrite };
+}

package/dist/judge.js

@@ -0,0 +1,77 @@
+import { emit } from "./telemetry.js"; // observe the judge's decisions
+// An OPTIONAL second layer over the rule-based permission gate. The rules
+// (permissions.ts) own deny and the obvious allows; whatever they mark "ask"
+// is the ambiguous middle — an unfamiliar-but-maybe-harmless command like
+// `ffmpeg ...`. Asking the human about every one of those is approval fatigue.
+//
+// The judge looks ONLY at those "ask" verdicts and answers one question: is
+// this clearly safe? If yes, we skip the prompt; if no (or it is unsure, or it
+// errors), we keep asking. Two invariants make this safe to add:
+//   1. The judge NEVER sees a deny — deny always wins, the rules decide it.
+//   2. The judge can only DOWNGRADE ask→allow for the clearly safe. It can
+//      never create an allow the rules denied, and any doubt stays "ask".
+// In other words: the judge reduces friction, it never reduces safety.
+// The judge prompt is deliberately blunt and asks for a single rigid token, so
+// parsing is unambiguous. "Err on the side of NO" is the load-bearing line.
+const JUDGE_SYSTEM = `You are a security classifier for a coding agent. You are shown ONE shell command that the agent wants to run. Decide whether it is CLEARLY SAFE to run without asking a human.
+
+CLEARLY SAFE = read-only or trivially reversible, no data loss, no network exfiltration, no privilege change, no writes outside the project, no credential access.
+NOT clearly safe = anything that deletes, overwrites, installs, pushes, sends data out, changes permissions, or that you are unsure about.
+
+Err strongly on the side of NO. When in doubt, answer no.
+Respond with EXACTLY one line and nothing else: <safe>yes</safe> or <safe>no</safe>`;
+const JUDGE_MAX_TOKENS = 16; // we only need one tiny tagged token — keep it cheap and fast
+const MAX_CONSECUTIVE_JUDGE_ERRORS = 3; // after this many failures, disable the judge for the session
+// Parse the judge's reply. PURE function (no I/O) so the safety logic is unit
+// testable without the network. Fail closed: anything that is not an
+// unambiguous "yes" means "ask".
+export function interpretJudgeOutput(text) {
+    const m = text.toLowerCase().match(/<safe>\s*(yes|no)\s*<\/safe>/); // strict tag, nothing else trusted
+    if (!m)
+        return "ask"; // no clean verdict → ask (fail closed)
+    return m[1] === "yes" ? "allow" : "ask"; // only a clear yes downgrades
+}
+// Tracks the judge's health across a session so a flaky/misconfigured judge
+// degrades gracefully to "always ask" instead of silently failing on every call.
+export class Judge {
+    client;
+    model;
+    consecutiveErrors = 0; // resets on any successful classification
+    disabled = false; // tripped after too many consecutive errors
+    constructor(client, // same client as the loop
+    model) {
+        this.client = client;
+        this.model = model;
+    }
+    // Classify one "ask" command. Returns "allow" only when the judge is
+    // confident it is safe; "ask" in every other case (unsure, error, disabled).
+    async classify(command) {
+        if (this.disabled)
+            return "ask"; // circuit breaker tripped — back to asking
+        try {
+            const res = await this.client.chat.completions.create({
+                model: this.model,
+                max_tokens: JUDGE_MAX_TOKENS, // tiny — this must be cheap
+                temperature: 0, // deterministic classification
+                messages: [
+                    { role: "system", content: JUDGE_SYSTEM },
+                    { role: "user", content: `Command:\n${command}` }, // ONLY the command — no chat history to be injected through
+                ],
+            });
+            this.consecutiveErrors = 0; // a clean call resets the breaker
+            const verdict = interpretJudgeOutput(res.choices[0]?.message?.content ?? "");
+            emit("agent_judge_verdict", { verdict }); // allow / ask, for tuning
+            return verdict;
+        }
+        catch {
+            // A judge that errors must never accidentally allow something. Count the
+            // failure, and after a few in a row, stop trying (degrade to asking).
+            this.consecutiveErrors++;
+            if (this.consecutiveErrors >= MAX_CONSECUTIVE_JUDGE_ERRORS) {
+                this.disabled = true;
+                emit("agent_judge_disabled", {}); // we gave up on the judge this session
+            }
+            return "ask"; // fail closed
+        }
+    }
+}