agent-from-zero 0.5.0 → 0.28.0

package/dist/editor.js

@@ -0,0 +1,307 @@
+import readline from "node:readline"; // raw-mode keypress decoding + the interface we pause
+// ---- pure editing logic -----------------------------------------------------
+// Map a keypress onto a new state + an action. Emacs-style bindings, the ones a
+// terminal user expects. Everything printable (letters, digits, punctuation,
+// pasted text, CJK) falls through to insertion at the cursor.
+export function reduceEditor(s, str, key) {
+    const { buffer, cursor } = s;
+    const name = key?.name;
+    if (key?.ctrl) {
+        switch (name) {
+            case "c":
+                return { state: s, action: "cancel" }; // Ctrl+C → caller decides (at the prompt: quit)
+            case "d":
+                return buffer.length === 0 ? { state: s, action: "eof" } : forwardDelete(s); // Ctrl+D empty → EOF, else delete
+            case "a":
+                return { state: { buffer, cursor: 0 }, action: "edit" }; // start of line
+            case "e":
+                return { state: { buffer, cursor: buffer.length }, action: "edit" }; // end of line
+            case "u":
+                return { state: { buffer: buffer.slice(cursor), cursor: 0 }, action: "edit" }; // kill to start
+            case "k":
+                return { state: { buffer: buffer.slice(0, cursor), cursor }, action: "edit" }; // kill to end
+            case "w":
+                return killWordBack(s); // kill the word before the cursor
+            case "b":
+                return { state: { buffer, cursor: Math.max(0, cursor - 1) }, action: "edit" }; // back one char
+            case "f":
+                return { state: { buffer, cursor: Math.min(buffer.length, cursor + 1) }, action: "edit" }; // forward one char
+            default:
+                return { state: s, action: "none" };
+        }
+    }
+    switch (name) {
+        case "return":
+        case "enter":
+            return { state: s, action: "submit" };
+        case "backspace":
+            return cursor > 0
+                ? { state: { buffer: buffer.slice(0, cursor - 1) + buffer.slice(cursor), cursor: cursor - 1 }, action: "edit" }
+                : { state: s, action: "none" };
+        case "delete":
+            return forwardDelete(s);
+        case "left":
+            return { state: { buffer, cursor: Math.max(0, cursor - 1) }, action: "edit" };
+        case "right":
+            return { state: { buffer, cursor: Math.min(buffer.length, cursor + 1) }, action: "edit" };
+        case "home":
+            return { state: { buffer, cursor: 0 }, action: "edit" };
+        case "end":
+            return { state: { buffer, cursor: buffer.length }, action: "edit" };
+        case "up":
+            return { state: s, action: "histPrev" };
+        case "down":
+            return { state: s, action: "histNext" };
+        case "escape":
+            return { state: { buffer: "", cursor: 0 }, action: "edit" }; // Esc clears the line
+        case "tab":
+            return { state: s, action: "tab" };
+        default:
+            // Printable insertion. A paste arrives as a multi-char string; insert it whole.
+            if (str && !key?.meta && isPrintable(str)) {
+                return { state: { buffer: buffer.slice(0, cursor) + str + buffer.slice(cursor), cursor: cursor + str.length }, action: "edit" };
+            }
+            return { state: s, action: "none" };
+    }
+}
+function forwardDelete(s) {
+    const { buffer, cursor } = s;
+    return cursor < buffer.length ? { state: { buffer: buffer.slice(0, cursor) + buffer.slice(cursor + 1), cursor }, action: "edit" } : { state: s, action: "none" };
+}
+function killWordBack(s) {
+    const { buffer, cursor } = s;
+    let i = cursor;
+    while (i > 0 && /\s/.test(buffer[i - 1]))
+        i--; // skip trailing spaces
+    while (i > 0 && !/\s/.test(buffer[i - 1]))
+        i--; // then the word
+    return { state: { buffer: buffer.slice(0, i) + buffer.slice(cursor), cursor: i }, action: "edit" };
+}
+function isPrintable(str) {
+    return [...str].every((c) => c >= " " && c !== "\x7f"); // no control chars (incl. lone newlines/DEL)
+}
+// ---- width + wrapping math --------------------------------------------------
+const ANSI = /\x1b\[[0-9;]*m/g; // SGR color codes — they take zero display columns
+// Display width of a string, ANSI-aware and CJK-aware (full-width glyphs are 2
+// columns; String.length would miscount them and break wrapping/cursor math).
+export function displayWidth(s) {
+    let w = 0;
+    for (const ch of s.replace(ANSI, ""))
+        w += charWidth(ch.codePointAt(0));
+    return w;
+}
+function charWidth(cp) {
+    if (cp >= 0x1100 &&
+        (cp <= 0x115f || // Hangul Jamo
+            cp === 0x2329 ||
+            cp === 0x232a ||
+            (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) || // CJK … Yi
+            (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+            (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+            (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+            (cp >= 0xff00 && cp <= 0xff60) || // fullwidth forms
+            (cp >= 0xffe0 && cp <= 0xffe6) ||
+            (cp >= 0x1f300 && cp <= 0x1faff) || // emoji
+            (cp >= 0x20000 && cp <= 0x3fffd)) // CJK extension B+
+    )
+        return 2;
+    return 1;
+}
+// Clip a (possibly ANSI-styled) string to a display width: keep escape codes
+// (zero width) intact, never split a wide glyph. This stops a long status footer
+// from wrapping — a wrapped footer row occupies TWO physical rows, which would
+// desync the editor's row math and drop the caret a line too low (and then every
+// repaint clears from the wrong row, stacking a fresh prompt each keystroke).
+export function truncateToWidth(s, width) {
+    let w = 0;
+    let out = "";
+    let i = 0;
+    while (i < s.length) {
+        if (s[i] === "\x1b") {
+            const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i)); // an SGR colour code — copy it, it has no width
+            if (m) {
+                out += m[0];
+                i += m[0].length;
+                continue;
+            }
+        }
+        const cp = s.codePointAt(i);
+        const ch = String.fromCodePoint(cp);
+        const cw = charWidth(cp);
+        if (w + cw > width)
+            return out + "\x1b[0m"; // would overflow → stop, closing any open colour
+        out += ch;
+        w += cw;
+        i += ch.length;
+    }
+    return out;
+}
+// Wrap the input across the terminal width and find where the cursor lands.
+// Row 0 begins after the prompt (promptW columns); continuation rows start at 0.
+// Returns the buffer text per row (the driver prepends the prompt to row 0) plus
+// the cursor's (row, col) — so a wrapped line keeps the caret exactly right.
+export function layout(buffer, cursor, promptW, cols) {
+    const width = Math.max(2, cols);
+    const rows = [""];
+    let row = 0;
+    let col = promptW;
+    let cursorRow = 0;
+    let cursorCol = promptW;
+    let set = false;
+    let cu = 0; // code-unit offset, to match `cursor`
+    for (const ch of buffer) {
+        if (!set && cu === cursor) {
+            cursorRow = row;
+            cursorCol = col;
+            set = true;
+        }
+        const w = charWidth(ch.codePointAt(0));
+        if (col + w > width) {
+            row++;
+            col = 0;
+            rows[row] = "";
+        }
+        rows[row] += ch;
+        col += w;
+        cu += ch.length;
+    }
+    if (!set) {
+        cursorRow = row;
+        cursorCol = col; // cursor at the very end
+    }
+    if (cursorCol >= width) {
+        // caret sat exactly at the right edge — it belongs at the start of the next row
+        cursorRow++;
+        cursorCol = 0;
+        if (rows.length <= cursorRow)
+            rows.push("");
+    }
+    return { rows, cursorRow, cursorCol };
+}
+// Read one line with the full editor + pinned footer. Resolves with the line, or
+// cancel (Ctrl+C) / eof (Ctrl+D on an empty line) for the caller to interpret.
+export function editLine(rl, opts) {
+    return new Promise((resolve) => {
+        const input = opts.input ?? process.stdin;
+        const out = process.stdout;
+        if (!input.isTTY)
+            return resolve({ type: "eof" }); // caller guards, but be safe
+        const promptW = displayWidth(opts.prompt);
+        const footerRows = opts.footer ? opts.footer.split("\n") : [];
+        const history = opts.history ?? [];
+        let hi = history.length; // history cursor; == length means "the live draft"
+        let draft = "";
+        let state = { buffer: opts.initial ?? "", cursor: (opts.initial ?? "").length };
+        let done = false;
+        let first = true;
+        let prevCursorRow = 0; // where the caret sits within the block, to climb back next repaint
+        const wasRaw = input.isRaw === true; // restore THIS on exit (forcing false would close the live readline)
+        const cols = () => out.columns || 80;
+        // The session's readline keeps its OWN 'keypress' handler on stdin. Once
+        // readline has been activated (after the first resume), that handler fires on
+        // every key alongside ours and fights us for the cursor — the line stacks
+        // instead of redrawing in place. Detach the other keypress listeners while we
+        // own the input, and restore them exactly on exit (menu/confirm still need them).
+        let otherKeypress = [];
+        // Repaint the whole block in place: climb to its top, clear downward, reprint
+        // input rows + footer, then drop the caret onto its computed (row, col).
+        const draw = () => {
+            const { rows, cursorRow, cursorCol } = layout(state.buffer, state.cursor, promptW, cols());
+            if (!first) {
+                if (prevCursorRow > 0)
+                    out.write(`\x1b[${prevCursorRow}A`); // up to the block's top row
+                out.write("\r");
+            }
+            out.write("\x1b[0J"); // clear from the top of the block to end of screen
+            const inputRows = rows.map((r, i) => (i === 0 ? opts.prompt + r : r));
+            // Truncate each footer row so it can't wrap — otherwise its extra physical
+            // row throws off the cursor math below (caret lands low → prompts stack).
+            const fr = footerRows.map((f) => truncateToWidth(f, Math.max(1, cols() - 1)));
+            const all = [...inputRows, ...fr];
+            out.write(all.join("\r\n"));
+            const lastRow = all.length - 1; // every row is now exactly one physical line
+            if (lastRow > cursorRow)
+                out.write(`\x1b[${lastRow - cursorRow}A`); // up from the last footer row
+            out.write("\r");
+            if (cursorCol > 0)
+                out.write(`\x1b[${cursorCol}C`); // right to the caret column
+            prevCursorRow = cursorRow;
+            first = false;
+        };
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            input.off("keypress", onKey);
+            for (const l of otherKeypress)
+                input.on("keypress", l); // give readline its keypress handler back
+            // Leave the typed command on screen, drop the footer, land on a fresh line.
+            const { rows } = layout(state.buffer, state.cursor, promptW, cols());
+            if (prevCursorRow > 0)
+                out.write(`\x1b[${prevCursorRow}A`);
+            out.write("\r\x1b[0J");
+            const inputRows = rows.map((r, i) => (i === 0 ? opts.prompt + r : r));
+            out.write(inputRows.join("\r\n") + "\r\n");
+            try {
+                input.setRawMode(wasRaw); // hand stdin back exactly as we found it
+            }
+            catch {
+                /* not all streams support it */
+            }
+            rl.resume();
+            resolve(result);
+        };
+        const onKey = (str, key) => {
+            if (done)
+                return;
+            const next = reduceEditor(state, str, key || {});
+            state = next.state;
+            switch (next.action) {
+                case "submit":
+                    return finish({ type: "line", value: state.buffer });
+                case "cancel":
+                    return finish({ type: "cancel" });
+                case "eof":
+                    return finish({ type: "eof" });
+                case "histPrev":
+                    if (hi > 0) {
+                        if (hi === history.length)
+                            draft = state.buffer; // stash the live draft on the way up
+                        hi--;
+                        state = { buffer: history[hi], cursor: history[hi].length };
+                    }
+                    return draw();
+                case "histNext":
+                    if (hi < history.length) {
+                        hi++;
+                        const b = hi === history.length ? draft : history[hi];
+                        state = { buffer: b, cursor: b.length };
+                    }
+                    return draw();
+                case "tab":
+                    opts.onTab?.(); // may print above us (e.g. expand a collapsed block) and scroll
+                    first = true; // so the next paint lands fresh at the cursor, not a stale climb-up
+                    return draw();
+                case "edit":
+                    return draw();
+                case "none":
+                    return;
+            }
+        };
+        try {
+            rl.pause(); // stop the session reader from turning our keystrokes into lines
+            if (input === process.stdin)
+                readline.emitKeypressEvents(input); // decode raw bytes into named keys
+            otherKeypress = input.listeners("keypress"); // readline's handler(s)…
+            for (const l of otherKeypress)
+                input.off("keypress", l); // …detached so only we drive the cursor
+            input.setRawMode(true);
+            input.resume(); // rl.pause() also paused the stream — resume it or no keys arrive
+            input.on("keypress", onKey);
+            draw();
+        }
+        catch {
+            finish({ type: "eof" }); // setup failed (non-TTY etc.) → behave like EOF
+        }
+    });
+}

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

@@ -10,13 +10,21 @@ import { emit } from "./telemetry.js"; // count hook activity
 // 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.
+//   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; // a hook gets 10s, then we kill it
+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) {
+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
@@ -30,7 +38,7 @@ function runOne(hook, payload) {
         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);
+        }, 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)
@@ -47,12 +55,29 @@ export async function runHooks(event, payload) {
     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 }); // run it
+        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)
+            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
@@ -63,5 +88,5 @@ export async function runHooks(event, payload) {
             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") };
+    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
+        }
+    }
+}