@nanhara/hara 0.95.2 → 0.98.1

package/dist/agent/loop.js

@@ -7,6 +7,7 @@ import { skillsDigest } from "../skills/skills.js";
 import { runHooks } from "../hooks.js";
 import { mapLimit, maxParallel } from "../concurrency.js";
 import { decideCommand, loadPermissionRules } from "../security/permissions.js";
+import { classifyRisk, guardianVeto, guardianEnabled, newBreaker, recordBlock } from "../security/guardian.js";
 import { subdirHint } from "../context/subdir-hints.js";
 import { classifyError, failoverAction, errorHint } from "./failover.js";
 import { currentTodos } from "../tools/todo.js";
@@ -80,6 +81,11 @@ export async function runAgent(history, opts) {
     const toolCounts = new Map();
     let blindShots = 0;
     let nudged = false;
+    // Guardian: engaged only on HIGH-RISK actions (see classifyRisk). `on` gates the whole layer so normal
+    // work never pays for it; the breaker is per-run (a hard stop after repeated blocks).
+    const guardianOn = !!opts.guardian && (opts.guardian.enabled ?? true) && guardianEnabled();
+    const breaker = newBreaker();
+    let breakerHalt = false; // set when a tripped breaker aborts this run
     for (;;) {
         // Type-ahead steering: fold in anything the user submitted while the previous step ran, so it
         // reaches the model on this next call (drained after the last tool round; empty on the 1st pass).
@@ -206,6 +212,12 @@ export async function runAgent(history, opts) {
             return;
         const plans = [];
         for (const tu of r.toolUses) {
+            if (breakerHalt) {
+                // Circuit-breaker halted the run: refuse every remaining call in this round with a clear message
+                // (no hang, no further tools) so the model + user get a definitive stop.
+                plans.push({ tu, tool: getTool(tu.name), denied: "Guardian circuit-breaker halted this run (too many high-risk actions blocked). Ask the user to review and re-run." });
+                continue;
+            }
             const tool = getTool(tu.name);
             if (!tool) {
                 plans.push({ tu, tool: undefined, denied: `Unknown tool: ${tu.name}` });
@@ -224,6 +236,50 @@ export async function runAgent(history, opts) {
                 plans.push({ tu, tool, denied: "Denied by a permission rule (~/.hara/permissions.json). Loosen the rule or run it yourself." });
                 continue;
             }
+            // Guardian layer — runs AFTER permission rules, alongside/just before the confirm gate. The
+            // deterministic classifier short-circuits FIRST: read tools, in-project edits, and ordinary shell
+            // commands classify `low` (pure Node, no LLM) and skip everything below — zero added latency. Only a
+            // genuinely HIGH-RISK action pays for a cheap-model veto, and that veto fails OPEN on any glitch.
+            if (guardianOn && !breakerHalt) {
+                const risk = classifyRisk(tu.name, tool.kind, input, ctx.cwd);
+                if (risk.level === "high") {
+                    const detail = String(input.command ?? input.path ?? "").replace(/\s+/g, " ").trim().slice(0, 400);
+                    const verdict = await guardianVeto(opts.guardian.provider, { tool: tu.name, detail, classifierReason: risk.reason }, history, { signal: opts.signal });
+                    if (verdict.decision === "block") {
+                        const tripped = recordBlock(breaker); // deterministic circuit-breaker: N blocks → hard stop
+                        plans.push({
+                            tu,
+                            tool,
+                            denied: `Guardian blocked this high-risk action: ${verdict.reason || risk.reason}. Reconsider — take a safer, in-scope step, or ask the user before doing this.`,
+                        });
+                        if (!opts.quiet) {
+                            const note = `⛔ guardian blocked ${tu.name} — ${verdict.reason || risk.reason}`;
+                            if (sink)
+                                sink.notice(note);
+                            else
+                                out(c.yellow(`  ${note}\n`));
+                        }
+                        if (tripped) {
+                            // Circuit-breaker tripped — a HARDER stop than the soft stuck-guard. On an INTERACTIVE run
+                            // (an `ask` channel exists), require an explicit human OK to continue. In headless/no-UI
+                            // (gateway/cron/-p, where `confirm` is auto-yes and there's no real user), abort SAFELY —
+                            // never auto-continue past the breaker, and never hang.
+                            const interactive = !!ctx.ask;
+                            const cont = interactive
+                                ? await opts.confirm(`${c.red("⛔ guardian circuit-breaker")} — ${breaker.blocks} high-risk actions blocked this turn. Continue anyway?`)
+                                : false;
+                            if (cont === false) {
+                                breakerHalt = true;
+                            }
+                            else {
+                                breaker.tripped = false;
+                                breaker.blocks = 0; // user vouched → reset the counter, keep classifying
+                            }
+                        }
+                        continue;
+                    }
+                }
+            }
             if (cmdDecision !== "allow" && needsConfirm(tool.kind, opts.approval) && (alwaysGate || !opts.autoApprove?.has(tu.name))) {
                 const reply = await opts.confirm(`${c.yellow("⚠")}  ${c.bold(tu.name)} ${c.dim(preview)} — run?`);
                 if (reply === false) {
@@ -288,6 +344,18 @@ export async function runAgent(history, opts) {
         }
         await flush();
         history.push({ role: "tool", results });
+        if (breakerHalt) {
+            // A tripped-and-declined circuit-breaker is a hard stop: end the run cleanly (the denial messages are
+            // already in `results` so the model/user see why). Never spin further.
+            if (!opts.quiet) {
+                const note = "⛔ guardian circuit-breaker: run halted (too many high-risk actions blocked). Review and re-run.";
+                if (sink)
+                    sink.notice(note);
+                else
+                    out(c.red(`${note}\n`));
+            }
+            return;
+        }
         if (guard && !nudged) {
             for (const p of plans)
                 if (p.tool && p.tool.kind !== "read")

package/dist/config.js

@@ -10,9 +10,27 @@ const PROVIDER_DEFAULTS = {
     },
     "qwen-oauth": { model: "coder-model", envKey: "QWEN_OAUTH_TOKEN" },
     openai: { model: "gpt-4o-mini", envKey: "OPENAI_API_KEY" },
+    // GLM / DeepSeek / OpenRouter are OpenAI-compatible: buildProvider routes them through the
+    // openai path (createOpenAIProvider) using the preset baseURL below. The preset baseURL is
+    // applied by loadConfig (merged.baseURL ?? d.baseURL), so the setup wizard never asks for a URL.
+    glm: {
+        model: "glm-4.6",
+        baseURL: "https://open.bigmodel.cn/api/paas/v4",
+        envKey: "GLM_API_KEY",
+    },
+    deepseek: {
+        model: "deepseek-chat",
+        baseURL: "https://api.deepseek.com",
+        envKey: "DEEPSEEK_API_KEY",
+    },
+    openrouter: {
+        model: "openai/gpt-4o-mini",
+        baseURL: "https://openrouter.ai/api/v1",
+        envKey: "OPENROUTER_API_KEY",
+    },
     "hara-gateway": { model: "", envKey: "HARA_GATEWAY_TOKEN" }, // B-end: enrolled device → token in ~/.hara/org.json, routed by the gateway
 };
-export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey", "routeModel", "routeBaseURL", "routeApiKey", "guardian", "notify", "vimMode", "autoCompact", "fileCheckpoints", "fallbackModel", "fallbackBaseURL", "fallbackApiKey", "reasoningEffort"];
 export const REASONING_EFFORTS = ["off", "low", "medium", "high"];
 export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
 export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
@@ -133,6 +151,9 @@ export function loadConfig(opts = {}) {
         ...(overlay.mcpServers ?? {}),
     };
     const hooks = (merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {});
+    // Guardian: default ON; env HARA_GUARDIAN=0/off/false or config guardian:"off" disables it.
+    const guardianRaw = process.env.HARA_GUARDIAN ?? merged.guardian;
+    const guardian = guardianRaw === "0" || guardianRaw === "off" || guardianRaw === "false" ? "off" : "on";
     const notify = (process.env.HARA_NOTIFY ?? merged.notify ?? "off");
     const vimMode = process.env.HARA_VIM === "1" || merged.vimMode === true || merged.vimMode === "true";
     const autoCompact = !(process.env.HARA_AUTO_COMPACT === "0" || merged.autoCompact === false || merged.autoCompact === "false"); // default ON
@@ -144,8 +165,13 @@ export function loadConfig(opts = {}) {
     const reasoningEffort = reasoningRaw && ["off", "low", "medium", "high"].includes(reasoningRaw)
         ? reasoningRaw
         : undefined;
-    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, routeModel, routeBaseURL, routeApiKey, guardian, hooks, notify, vimMode, autoCompact, fileCheckpoints, fallbackModel, fallbackBaseURL, fallbackApiKey, reasoningEffort, mcpServers, cwd: process.cwd() };
 }
 export function providerEnvKey(provider) {
     return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;
 }
+/** Preset base URL for a provider (undefined for anthropic/openai which use their SDK defaults).
+ *  Used by `hara setup` to write a self-contained baseURL for GLM/DeepSeek/OpenRouter. */
+export function providerDefaultBaseURL(provider) {
+    return PROVIDER_DEFAULTS[provider]?.baseURL;
+}

package/dist/index.js

@@ -14,7 +14,7 @@ import { readFileSync, existsSync, writeFileSync, rmSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, join, relative } from "node:path";
-import { loadConfig, configPath, readRawConfig, writeConfigValue, setModelVisionOverride, providerEnvKey, CONFIG_KEYS, APPROVAL_MODES, SANDBOX_MODES, REASONING_EFFORTS, } from "./config.js";
+import { loadConfig, configPath, readRawConfig, writeConfigValue, setModelVisionOverride, providerEnvKey, providerDefaultBaseURL, CONFIG_KEYS, APPROVAL_MODES, SANDBOX_MODES, REASONING_EFFORTS, } from "./config.js";
 import { runAgent } from "./agent/loop.js";
 import { notifyDone } from "./notify.js";
 import { startMcpServer, mcpServeToolNames } from "./mcp/server.js";
@@ -69,6 +69,7 @@ import "./tools/codebase.js"; // register codebase_search (repo as a knowledge b
 import "./tools/todo.js"; // register todo_write (inline task checklist)
 import "./tools/send.js"; // register send_file (self-gates on HARA_GATEWAY — pushes a file to the chat)
 import "./tools/external_agent.js"; // register external_agent (delegate to claude-code / codex headless)
+import "./tools/ask_user.js"; // register ask_user (pause mid-turn to ask the user a structured question)
 import { computerBackends } from "./tools/computer.js"; // register the computer tool + expose the backend probe
 const here = dirname(fileURLToPath(import.meta.url));
 // Version: from a build-time define in the compiled single-binary (no package.json on its virtual FS),
@@ -107,7 +108,10 @@ async function buildProvider(cfg) {
     // override (so `--profile`/`HARA_PROFILE`-overridden values flow + sidecar provider builds work).
     const provider = (cfg.provider && cfg.provider !== "hara-gateway" ? cfg.provider : ap.provider) || "anthropic";
     const apiKey = cfg.apiKey ?? ap.apiKey;
-    const baseURL = cfg.baseURL ?? ap.baseURL;
+    // Resolve base URL: explicit (cfg → profile) wins; otherwise fall back to the provider's preset
+    // (GLM/DeepSeek/OpenRouter). This keeps `profile add --byok --provider glm` working even when the
+    // user didn't pass --base-url (anthropic/openai stay undefined → their SDK defaults).
+    const baseURL = cfg.baseURL ?? ap.baseURL ?? providerDefaultBaseURL(provider);
     const model = cfg.model || effectiveModel(ap);
     if (provider === "qwen-oauth") {
         const auth = await getValidQwenAuth();
@@ -131,6 +135,19 @@ async function withRouting(primary, cfg) {
     const alt = await buildProvider({ ...cfg, model: cfg.routeModel, baseURL: cfg.routeBaseURL ?? cfg.baseURL, apiKey: cfg.routeApiKey ?? cfg.apiKey });
     return alt ? routingProvider(primary, alt) : primary;
 }
+/** Guardian veto model: the CHEAP tier if `routeModel` is configured (a small classifier call, not real
+ *  work), else the primary provider. Never blocks startup — any build failure just yields the fallback (and
+ *  the guardian fails open when even that is absent). Returns the `{ provider, enabled }` shape runAgent wants,
+ *  or undefined when guardian is off in config/env. */
+async function buildGuardian(cfg, primary) {
+    if (cfg.guardian === "off")
+        return undefined;
+    let gp = primary;
+    if (cfg.routeModel && cfg.routeModel !== cfg.model) {
+        gp = (await buildProvider({ ...cfg, model: cfg.routeModel, baseURL: cfg.routeBaseURL ?? cfg.baseURL, apiKey: cfg.routeApiKey ?? cfg.apiKey })) ?? primary;
+    }
+    return { provider: gp, enabled: true };
+}
 function authHint(cfg) {
     const ap = loadActiveProfile();
     if (ap.kind === "gateway")
@@ -140,8 +157,121 @@ function authHint(cfg) {
         return `Run ${c.bold("hara login qwen")} to authenticate.`;
     return `Set ${c.bold(providerEnvKey(provider))} (or ${c.bold("HARA_API_KEY")}), or run ${c.bold("hara setup")}.`;
 }
-const SETUP_DEFAULT_MODEL = { anthropic: "claude-opus-4-8", qwen: "qwen-plus", openai: "gpt-4o-mini", "qwen-oauth": "coder-model" };
-/** Interactive first-run setup: pick a provider, (optional) base URL, API key, and model → ~/.hara/config.json. */
+const SETUP_DEFAULT_MODEL = { anthropic: "claude-opus-4-8", qwen: "qwen-plus", openai: "gpt-4o-mini", glm: "glm-4.6", deepseek: "deepseek-chat", openrouter: "openai/gpt-4o-mini", "qwen-oauth": "coder-model" };
+/** Numbered provider menu for `hara setup`. Order is the displayed order; `id` maps to a ProviderId
+ *  (or the special "custom"/"qwen-oauth" routes). GLM/DeepSeek carry a preset base URL so the user
+ *  never types one; "custom" prompts for an OpenAI-compatible base URL. */
+const SETUP_MENU = [
+    { label: "Anthropic", id: "anthropic" },
+    { label: "OpenAI", id: "openai" },
+    { label: "GLM (Zhipu)", id: "glm" },
+    { label: "DeepSeek", id: "deepseek" },
+    { label: "Qwen (DashScope key)", id: "qwen" },
+    { label: "OpenAI-compatible (custom base URL)", id: "custom" },
+    { label: "Qwen — free, no key (browser sign-in)", id: "qwen-oauth" },
+];
+/** Read a secret from the TTY without echoing it (shows `*` per char). Falls back to a plain
+ *  readline question when stdin isn't a raw-capable TTY (piped input / odd terminals) so scripted
+ *  `printf 'key\n' | hara setup` still works. Handles backspace, Enter, and Ctrl-C/Ctrl-D. */
+function readSecret(prompt, rl) {
+    const input = stdin;
+    if (!input.isTTY || typeof input.setRawMode !== "function") {
+        // Non-TTY (piped/scripted): can't suppress echo at the terminal level; read it plainly.
+        return rl.question(prompt);
+    }
+    return new Promise((resolve, reject) => {
+        stdout.write(prompt);
+        let buf = "";
+        const prevRaw = input.isRaw ?? false;
+        // Pause the readline interface so it doesn't also consume keystrokes / echo while we read raw.
+        // We restore it in cleanup() before the next rl.question() runs.
+        rl.pause();
+        input.setRawMode(true);
+        input.resume();
+        const onData = (chunk) => {
+            const s = chunk.toString("utf8");
+            for (const ch of s) {
+                const code = ch.charCodeAt(0);
+                if (ch === "\r" || ch === "\n") {
+                    cleanup();
+                    stdout.write("\n");
+                    resolve(buf);
+                    return;
+                }
+                else if (code === 3) {
+                    // Ctrl-C → abort the wizard (mirror readline's SIGINT behavior).
+                    cleanup();
+                    stdout.write("\n");
+                    reject(new Error("cancelled"));
+                    return;
+                }
+                else if (code === 4) {
+                    // Ctrl-D → end of input; resolve with whatever we have.
+                    cleanup();
+                    stdout.write("\n");
+                    resolve(buf);
+                    return;
+                }
+                else if (code === 127 || code === 8) {
+                    // Backspace/Delete.
+                    if (buf.length) {
+                        buf = buf.slice(0, -1);
+                        stdout.write("\b \b");
+                    }
+                }
+                else if (code >= 32) {
+                    buf += ch;
+                    stdout.write("*");
+                }
+            }
+        };
+        const cleanup = () => {
+            input.removeListener("data", onData);
+            try {
+                input.setRawMode(prevRaw);
+            }
+            catch {
+                /* best-effort */
+            }
+            // Hand control back to readline for the next prompt (model question).
+            rl.resume();
+        };
+        input.on("data", onData);
+    });
+}
+/** One-shot validation ping: build the provider exactly as the runtime would (anthropic vs the
+ *  OpenAI-compatible path with the resolved base URL) and send a tiny prompt with a short timeout.
+ *  Never throws — returns true on a clean turn, false on any error/timeout. Used only to print a
+ *  friendly "connected" hint; the wizard saves config regardless. */
+async function pingProvider(args) {
+    const { provider, apiKey, model, baseURL } = args;
+    if (!apiKey || !model)
+        return false;
+    const prov = provider === "anthropic"
+        ? createAnthropicProvider({ apiKey, model, baseURL })
+        : createOpenAIProvider({ apiKey, model, baseURL, label: provider });
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 12_000);
+    try {
+        const r = await prov.turn({
+            system: "Reply with the single word: ok",
+            history: [{ role: "user", content: "ping" }],
+            tools: [],
+            onText: () => { },
+            signal: ctrl.signal,
+        });
+        return r.stop !== "error";
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Interactive first-run setup: pick a provider (numbered menu), API key (masked), and model →
+ *  ~/.hara/config.json. GLM/DeepSeek/OpenRouter and "custom" route through the OpenAI-compatible
+ *  path; "Qwen free" routes to the device-login flow. Storage model is unchanged (config.json 0600). */
 async function runSetup() {
     if (!stdin.isTTY) {
         out(c.yellow("`hara setup` is interactive — run it in a terminal, or use `hara config set <key> <value>` in scripts.\n"));
@@ -150,14 +280,42 @@ async function runSetup() {
     const rl = createInterface({ input: stdin, output: stdout });
     try {
         out(c.bold("hara setup") + c.dim(" — configure a provider, key, and model (Ctrl-C to cancel)\n\n"));
-        const provider = ((await rl.question(`Provider ${c.dim("anthropic / qwen / openai")} [anthropic]: `)).trim() || "anthropic").toLowerCase();
+        SETUP_MENU.forEach((m, i) => out(`  ${c.bold(String(i + 1))}) ${m.label}\n`));
+        out("\n");
+        const pick = (await rl.question(`Provider [1]: `)).trim() || "1";
+        const idx = Number.parseInt(pick, 10);
+        const choice = Number.isInteger(idx) && idx >= 1 && idx <= SETUP_MENU.length ? SETUP_MENU[idx - 1] : SETUP_MENU[0];
+        // Route 7: Qwen free device login — no key, no model prompt. Reuse the existing flow + config writes.
+        if (choice.id === "qwen-oauth") {
+            try {
+                await qwenDeviceLogin((m) => out(m + "\n"));
+                writeConfigValue("provider", "qwen-oauth");
+                writeConfigValue("model", "coder-model");
+                out(c.green("\n✓ Qwen OAuth complete — provider set to qwen-oauth (model coder-model).\n") + c.dim(`Check it with ${c.bold("hara doctor")}, then just run ${c.bold("hara")}.\n`));
+            }
+            catch (e) {
+                out(c.red(`\nQwen OAuth failed: ${e?.message ?? e}\n`));
+            }
+            return;
+        }
+        // Resolve the concrete provider id + base URL. "custom" = OpenAI-compatible: ask for the base
+        // URL and store the chosen provider as "openai" (the generic OpenAI-compatible dispatch).
+        let provider;
         let baseURL = "";
-        if (provider === "qwen" || provider === "openai") {
-            baseURL = (await rl.question(`Base URL ${c.dim("(blank = default; set for an OpenAI-compatible endpoint, e.g. GLM/Kimi/DashScope)")}: `)).trim();
+        if (choice.id === "custom") {
+            provider = "openai";
+            baseURL = (await rl.question(`Base URL ${c.dim("(OpenAI-compatible endpoint, e.g. https://your-host/v1)")}: `)).trim();
+        }
+        else {
+            provider = choice.id;
+            // GLM/DeepSeek/OpenRouter carry a preset base URL (PROVIDER_DEFAULTS) — written explicitly so
+            // the personal profile is self-contained. anthropic/openai use their built-in defaults.
+            baseURL = providerDefaultBaseURL(provider) ?? "";
         }
         const envKey = providerEnvKey(provider);
-        const apiKey = (await rl.question(`API key ${c.dim(`(blank = use the ${envKey} env var)`)}: `)).trim();
-        const model = (await rl.question(`Model [${SETUP_DEFAULT_MODEL[provider] ?? "?"}]: `)).trim() || SETUP_DEFAULT_MODEL[provider] || "";
+        const apiKey = (await readSecret(`API key ${c.dim(`(masked; blank = use the ${envKey} env var)`)}: `, rl)).trim();
+        const defaultModel = SETUP_DEFAULT_MODEL[choice.id === "custom" ? "openai" : provider] ?? "";
+        const model = (await rl.question(`Model [${defaultModel || "?"}]: `)).trim() || defaultModel;
         writeConfigValue("provider", provider);
         if (baseURL)
             writeConfigValue("baseURL", baseURL);
@@ -165,8 +323,20 @@ async function runSetup() {
             writeConfigValue("apiKey", apiKey);
         if (model)
             writeConfigValue("model", model);
+        // One-shot validation ping (best-effort; never blocks saving). Only when we have a key + model.
+        if (apiKey && model) {
+            out(c.dim("\nChecking connection… "));
+            const ok = await pingProvider({ provider, apiKey, model, baseURL: baseURL || undefined });
+            out(ok ? c.green("✓ connected\n") : c.yellow(`⚠ couldn't reach ${provider} (saved anyway)\n`));
+        }
         out(c.green(`\n✓ saved to ${configPath()}\n`) + c.dim(`Check it with ${c.bold("hara doctor")}, then just run ${c.bold("hara")}.\n`));
     }
+    catch (e) {
+        if (e?.message === "cancelled")
+            out(c.dim("\n(cancelled)\n"));
+        else
+            throw e;
+    }
     finally {
         rl.close();
     }
@@ -1050,7 +1220,7 @@ profileCmd
     .option("--code <code>", "(gateway) enrollment code from your admin")
     .option("--label <label>", "human-friendly label for the profile")
     .option("--byok", "(byok) BYOK profile — bring your own provider key")
-    .option("--provider <id>", "(byok) anthropic | qwen | openai | qwen-oauth")
+    .option("--provider <id>", "(byok) anthropic | openai | glm | deepseek | openrouter | qwen | qwen-oauth")
     .option("--key <key>", "(byok) API key (else read from the provider's env var at use-time)")
     .option("--base-url <url>", "(byok) override the provider base URL (OpenAI-compatible endpoints)")
     .option("--model <model>", "(byok) default model for this profile")
@@ -1109,7 +1279,7 @@ profileCmd
         out(c.dim(`Switch to it with \`hara profile use ${id}\`.\n`));
         return;
     }
-    out(c.red("usage:\n") + c.dim("  hara profile add <id> --gateway <url> --code <code> [--label …]\n") + c.dim("  hara profile add <id> --byok --provider anthropic|qwen|openai|qwen-oauth [--key … --base-url … --model …]\n"));
+    out(c.red("usage:\n") + c.dim("  hara profile add <id> --gateway <url> --code <code> [--label …]\n") + c.dim("  hara profile add <id> --byok --provider anthropic|openai|glm|deepseek|openrouter|qwen|qwen-oauth [--key … --base-url … --model …]\n"));
     process.exit(1);
 });
 profileCmd
@@ -1847,6 +2017,7 @@ program.action(async (opts) => {
     const provider0 = await withRouting(await buildProvider(cfg), cfg);
     const fallbackProvider = provider0 && cfg.fallbackModel && cfg.fallbackModel !== cfg.model ? await buildProvider({ ...cfg, model: cfg.fallbackModel, baseURL: cfg.fallbackBaseURL ?? cfg.baseURL, apiKey: cfg.fallbackApiKey ?? cfg.apiKey }) : null;
     const fbOpt = fallbackProvider ? { provider: fallbackProvider } : undefined; // app-failover for the main chat turns
+    const guardianOpt = await buildGuardian(cfg, provider0); // internal safety layer (high-risk actions only)
     if (!provider0) {
         // First-run friendliness: offer the setup wizard instead of just erroring (interactive TTY only).
         if (stdin.isTTY && !opts.print) {
@@ -1994,6 +2165,7 @@ program.action(async (opts) => {
             projectContext,
             memory: memoryDigest(cwd),
             stats,
+            guardian: guardianOpt, // safety layer stays on in headless -p (fail-open; breaker aborts, never hangs)
         });
         if (meta) {
             // Long-session safety: auto-compact before saving so a long chat/cron thread never overflows context.
@@ -2022,6 +2194,22 @@ program.action(async (opts) => {
         },
     });
     const confirm = async (q) => (await rl.question(`${q} ${c.dim("[y/N]")} `)).trim().toLowerCase().startsWith("y");
+    // ask_user (classic REPL): print the question + a numbered menu (matching the setup menu look) and read the
+    // answer through the SAME rl.question channel confirm uses. A bare option number selects it; any other text
+    // is taken as a free-text answer — so the user can always type their own response.
+    const askUser = async (q, options) => {
+        out(c.bold("\n? ") + q + "\n");
+        const opts = (options ?? []).map((o) => o.trim()).filter(Boolean);
+        opts.forEach((o, i) => out(`  ${c.bold(String(i + 1))}) ${o}\n`));
+        const hint = opts.length ? c.dim(`(1-${opts.length} to pick, or type your own answer) `) : c.dim("(type your answer) ");
+        const raw = (await rl.question(`${c.cyan("›")} ${hint}`)).trim();
+        if (opts.length) {
+            const n = Number.parseInt(raw, 10);
+            if (Number.isInteger(n) && n >= 1 && n <= opts.length)
+                return opts[n - 1];
+        }
+        return raw;
+    };
     // shift+tab cycles the approval mode (classic REPL only; the TUI handles its own keys).
     // Bare /approval is the reliable fallback everywhere.
     if (stdin.isTTY && !useTui) {
@@ -2804,7 +2992,7 @@ program.action(async (opts) => {
                             // fall back to "suggest" so we keep the user's confirm gate without crashing the type check.
                             const __skApproval = h.approval === "plan" ? "suggest" : h.approval;
                             try {
-                                await runAgent(history, { provider, ctx: { cwd, sandbox, spawn, ui: { text: h.sink.assistantDelta, reasoning: h.sink.reasoningDelta, tool: h.sink.tool, diff: h.sink.diff, notice: h.sink.notice }, describeImage: describeScreenshot, locate: locateScreenshot }, approval: __skApproval, confirm: h.confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: h.signal, fallback: fbOpt });
+                                await runAgent(history, { provider, ctx: { cwd, sandbox, spawn, ui: { text: h.sink.assistantDelta, reasoning: h.sink.reasoningDelta, tool: h.sink.tool, diff: h.sink.diff, notice: h.sink.notice }, ask: h.ask, describeImage: describeScreenshot, locate: locateScreenshot }, approval: __skApproval, confirm: h.confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: h.signal, fallback: fbOpt, guardian: guardianOpt });
                             }
                             catch (e) {
                                 h.sink.notice(`[error] ${e?.message ?? e}`);
@@ -2850,7 +3038,7 @@ program.action(async (opts) => {
                     const pout = stats.output;
                     await runAgent(history, {
                         provider,
-                        ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot, locate: locateScreenshot },
+                        ctx: { cwd, sandbox, spawn, ui, ask: h.ask, describeImage: describeScreenshot, locate: locateScreenshot },
                         approval: "suggest",
                         confirm: h.confirm,
                         toolFilter: (n) => READONLY_TOOLS.has(n),
@@ -2879,7 +3067,7 @@ program.action(async (opts) => {
                         const xout = stats.output;
                         await runAgent(history, {
                             provider,
-                            ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot, locate: locateScreenshot },
+                            ctx: { cwd, sandbox, spawn, ui, ask: h.ask, describeImage: describeScreenshot, locate: locateScreenshot },
                             approval: choice,
                             memory: buildMemory(),
                             confirm: h.confirm,
@@ -2888,6 +3076,7 @@ program.action(async (opts) => {
                             stats,
                             signal: h.signal,
                             pendingInput,
+                            guardian: guardianOpt,
                         });
                         h.sink.usage(stats.input - xin, stats.output - xout);
                         saveSession(meta, history);
@@ -2907,7 +3096,7 @@ program.action(async (opts) => {
                 const beforeOut = stats.output;
                 await runAgent(history, {
                     provider,
-                    ctx: { cwd, sandbox, spawn, ui, describeImage: describeScreenshot, locate: locateScreenshot },
+                    ctx: { cwd, sandbox, spawn, ui, ask: h.ask, describeImage: describeScreenshot, locate: locateScreenshot },
                     approval: appr,
                     memory: buildMemory(),
                     confirm: h.confirm,
@@ -2917,6 +3106,7 @@ program.action(async (opts) => {
                     signal: h.signal,
                     pendingInput,
                     fallback: fbOpt,
+                    guardian: guardianOpt,
                 });
                 if (!meta.title) {
                     meta.title = await nameSession(provider, history);
@@ -2969,7 +3159,7 @@ program.action(async (opts) => {
                     });
                     currentTurn = new AbortController();
                     try {
-                        await runAgent(history, { provider, ctx: { cwd, sandbox, spawn }, approval, confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: currentTurn.signal, fallback: fbOpt });
+                        await runAgent(history, { provider, ctx: { cwd, sandbox, spawn, ask: askUser }, approval, confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: currentTurn.signal, fallback: fbOpt, guardian: guardianOpt });
                     }
                     catch (e) {
                         out(c.red(`\n[error] ${e.message}\n`));
@@ -3000,7 +3190,7 @@ program.action(async (opts) => {
         currentTurn = new AbortController();
         const t0 = Date.now();
         try {
-            await runAgent(history, { provider, ctx: { cwd, sandbox, spawn }, approval, confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: currentTurn.signal, fallback: fbOpt });
+            await runAgent(history, { provider, ctx: { cwd, sandbox, spawn, ask: askUser }, approval, confirm, autoApprove, projectContext, memory: buildMemory(), stats, signal: currentTurn.signal, fallback: fbOpt, guardian: guardianOpt });
         }
         catch (e) {
             out(c.red(`\n[error] ${e.message}\n`));

package/dist/security/guardian.js

@@ -0,0 +1,261 @@
+// Guardian — an internal safety layer that sits ON TOP of the existing stack (permission rules →
+// PreToolUse hooks → approval gate → soft stuck-guard). It exists for the one failure mode those don't
+// cover: a genuinely dangerous, irreversible action that slips through (no deny rule, auto-approved mode,
+// a cron/gateway run with `confirm: () => true`). Two moving parts:
+//
+//   1. A DETERMINISTIC risk classifier that runs FIRST and is the whole point of "zero latency on normal
+//      work": read tools, in-project edits, and ordinary shell commands are classified `low` in pure Node
+//      (no LLM, no I/O) and skip the guardian entirely. Only a handful of genuinely destructive shapes
+//      (rm -rf, dd, mkfs, curl|sh, sudo, force-push, broad chmod -R, writes outside the project root, …)
+//      are classified `high` and escalate.
+//   2. A conservative LLM veto that runs ONLY on `high` actions: it asks a cheap model "is this action
+//      clearly dangerous or clearly off-task?" and defaults to ALLOW. Any glitch (timeout, error, no model
+//      configured) FAILS OPEN — a guardian hiccup must never break legitimate work, because the permission
+//      rules + the user's own approval gate still apply independently.
+//
+// Plus a deterministic circuit-breaker: N guardian BLOCKS in one run (or an escalating-destructive runaway)
+// trips a hard stop that requires explicit user confirmation to continue — a harder stop than the soft
+// stuck-guard nudge, and one that aborts safely (never hangs) when there's no interactive user.
+import { resolve, isAbsolute } from "node:path";
+import { canonicalize, splitCompound } from "./permissions.js";
+// ── Deterministic risk classifier ────────────────────────────────────────────────────────────────────
+// The classifier is intentionally NARROW: false positives here cost latency + an LLM call + potential
+// annoyance, so we only flag shapes that are destructive/irreversible in practice. Everything else is `low`.
+// A path is "broad" (a whole tree / outside the sandbox) when it's `/`, a top-level system dir, a home dir,
+// `.`/`*`/`~`, or absolute-outside-cwd. `chmod -R`/`chown -R`/`rm -rf` on a broad path is the danger, not on
+// a project-local subdir.
+const SYSTEM_ROOTS = /^(\/|\/(bin|boot|dev|etc|home|lib|opt|proc|root|sbin|srv|sys|usr|var|Users|Applications|System|Library|Volumes)(\/|$)|~|\$HOME)/;
+/** Genuinely destructive/irreversible single-command shapes (checked against the canonical form of each
+ *  part of a compound command). Kept tight — see the module header. */
+function isDestructiveCommand(canonical) {
+    const c = canonical;
+    if (!c)
+        return false;
+    // rm -rf / rm -fr / recursive-forced removal (the classic).
+    if (/\brm\s+(-[a-z]*r[a-z]*f|-[a-z]*f[a-z]*r|-r\s+-f|-f\s+-r|--recursive\s+--force|--force\s+--recursive)\b/.test(c))
+        return true;
+    // rm -r/-rf targeting a broad/system path (rm -rf / , rm -rf ~ , rm -r /etc …).
+    if (/\brm\s+-[a-z]*r/.test(c) && /\brm\s+-[a-z]*r[a-z]*\s+(\/|~|\$HOME|\*|\.\s|\.$)/.test(c))
+        return true;
+    // Raw-disk / filesystem-destroying tools.
+    if (/\b(dd)\b/.test(c) && /\bof=\/dev\//.test(c))
+        return true;
+    if (/\b(mkfs(\.\w+)?|mke2fs|fdisk|parted|wipefs|shred)\b/.test(c))
+        return true;
+    if (/\bdiskutil\s+(erase|reformat|partitionDisk)/i.test(c))
+        return true;
+    // Fork bomb.
+    if (/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(c) || /\.\(\)\{\s*\.\|\.&\s*\}/.test(c))
+        return true;
+    // Pipe-to-shell from the network (curl … | sh, wget … | bash) — arbitrary remote code execution.
+    if (/\b(curl|wget|fetch)\b[^|]*\|\s*(sudo\s+)?(ba|z)?sh\b/.test(c))
+        return true;
+    // Privilege escalation.
+    if (/\bsudo\b/.test(c))
+        return true;
+    if (/\bkillall\b/.test(c))
+        return true;
+    // Force-push (rewrites shared history irreversibly).
+    if (/\bgit\s+push\b[^\n]*(--force\b|--force-with-lease\b|(^|\s)-f\b)/.test(c))
+        return true;
+    // Broad recursive permission/ownership change.
+    if (/\b(chmod|chown|chgrp)\s+(-[a-z]*R|--recursive)/.test(c)) {
+        if (SYSTEM_ROOTS.test(commandTarget(c)) || /\s(\/|~|\$HOME|\*|\.)(\s|$)/.test(c))
+            return true;
+    }
+    // Destructive git tree resets / clean.
+    if (/\bgit\s+clean\b[^\n]*-[a-z]*f/.test(c) && /-[a-z]*d/.test(c))
+        return true;
+    // History overwrite: `> /path` (truncation) onto a system/absolute-outside path is handled by the
+    // out-of-project write check below (redirection carries a path); nothing extra here.
+    return false;
+}
+/** The last whitespace token that looks like a path target of a command (best-effort, for chmod/chown). */
+function commandTarget(canonical) {
+    const toks = canonical.split(/\s+/).filter((t) => t && !t.startsWith("-"));
+    return toks[toks.length - 1] ?? "";
+}
+/** Extract `> file` / `>> file` redirection targets from a canonical command (quote-naive; classifier only). */
+function redirectionTargets(canonical) {
+    const out = [];
+    const re = />>?\s*("([^"]*)"|'([^']*)'|([^\s;|&]+))/g;
+    let m;
+    while ((m = re.exec(canonical))) {
+        const p = m[2] ?? m[3] ?? m[4];
+        if (p && p !== "/dev/null" && !p.startsWith("&") && !/^\d$/.test(p))
+            out.push(p);
+    }
+    return out;
+}
+/** True if `p` resolves OUTSIDE the project/cwd root (a write/delete escaping the sandbox). Non-file
+ *  pseudo-paths (/dev/null) and empties are treated as in-scope. */
+export function isOutsideRoot(p, cwd) {
+    if (!p || p === "/dev/null" || p === "-")
+        return false;
+    const expanded = p.replace(/^~(?=\/|$)/, process.env.HOME ?? "~");
+    const abs = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
+    const root = resolve(cwd);
+    return abs !== root && !abs.startsWith(root + "/");
+}
+/** Collect the file paths an edit-kind tool would write/delete, from its tool input. */
+export function editPaths(name, input) {
+    const paths = [];
+    if (typeof input.path === "string")
+        paths.push(input.path);
+    // apply_patch: { changes: [{ path, ... }] }
+    if (Array.isArray(input.changes)) {
+        for (const ch of input.changes)
+            if (ch && typeof ch.path === "string")
+                paths.push(ch.path);
+    }
+    return paths;
+}
+/** Deterministic risk classifier. Runs FIRST, in pure Node — this is what keeps normal work at zero cost.
+ *  Returns `low` for read tools, in-project edits, and ordinary shell commands (→ guardian is skipped
+ *  entirely); `high` only for destructive/irreversible bash or writes/deletes outside the project root. */
+export function classifyRisk(toolName, toolKind, input, cwd) {
+    if (toolKind === "read" || !input)
+        return { level: "low", reason: "" };
+    if (toolKind === "edit") {
+        for (const p of editPaths(toolName, input)) {
+            if (isOutsideRoot(p, cwd))
+                return { level: "high", reason: `writes/deletes outside the project root: ${p}` };
+        }
+        return { level: "low", reason: "" };
+    }
+    if (toolKind === "exec" && typeof input.command === "string") {
+        const command = input.command;
+        const whole = canonicalize(command);
+        // Whole-command check FIRST — catches cross-part shapes a compound split would hide (curl … | sh, where
+        // the danger is the pipe connecting two individually-benign parts).
+        if (isDestructiveCommand(whole))
+            return { level: "high", reason: `destructive/irreversible command: ${whole.slice(0, 120)}` };
+        // Then per-part: strictest part wins; if we can't safely parse it, fall back to the whole canonical form.
+        const parts = splitCompound(command) ?? [whole];
+        for (const part of parts) {
+            if (isDestructiveCommand(part))
+                return { level: "high", reason: `destructive/irreversible command: ${part.slice(0, 120)}` };
+            for (const t of redirectionTargets(part)) {
+                if (isOutsideRoot(t, cwd))
+                    return { level: "high", reason: `writes outside the project root via redirection: ${t}` };
+                if (SYSTEM_ROOTS.test(t))
+                    return { level: "high", reason: `writes to a system path: ${t}` };
+            }
+        }
+        return { level: "low", reason: "" };
+    }
+    // computer / unknown non-read kinds are already gated hard elsewhere (always-confirm); leave them to that.
+    return { level: "low", reason: "" };
+}
+// ── LLM veto (conservative; high-risk only) ──────────────────────────────────────────────────────────
+const GUARDIAN_SYSTEM = `You are a safety guardian for a coding agent. You are shown a SINGLE high-risk action the agent is about ` +
+    `to take, plus a short summary of the user's task. Decide whether to ALLOW or BLOCK it. Default to ALLOW. ` +
+    `Only BLOCK when the action is CLEARLY dangerous/irreversible AND not plausibly part of the stated task ` +
+    `(e.g. deleting unrelated files, wiping a disk, exfiltrating data, force-pushing over shared history when ` +
+    `the task never asked for it), or when it is CLEARLY misaligned with the task. If the action is a ` +
+    `reasonable step toward the task — even a destructive one the user likely wants — ALLOW it. When unsure, ` +
+    `ALLOW. Reply with ONLY compact JSON: {"decision":"allow"|"block","reason":"<one short sentence>"}.`;
+/** Parse the model's reply into a verdict. Anything we can't confidently read as a BLOCK is treated as
+ *  ALLOW (fail-open on ambiguity). */
+export function parseVerdict(text) {
+    const raw = (text ?? "").trim();
+    // Try strict JSON first, then the first {...} blob.
+    const tryParse = (s) => {
+        try {
+            const j = JSON.parse(s);
+            if (j && (j.decision === "block" || j.decision === "allow")) {
+                return { decision: j.decision, reason: typeof j.reason === "string" ? j.reason : "" };
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        return null;
+    };
+    const direct = tryParse(raw);
+    if (direct)
+        return direct;
+    const m = /\{[\s\S]*\}/.exec(raw);
+    if (m) {
+        const blob = tryParse(m[0]);
+        if (blob)
+            return blob;
+    }
+    // No parseable verdict → fail open.
+    return { decision: "allow", reason: "" };
+}
+/** A brief, safe task-context summary for the guardian prompt: the most recent genuine user message,
+ *  truncated. Kept short (cheap call, and we don't want to leak the whole transcript). */
+export function taskSummary(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const m = history[i];
+        if (m.role === "user" && typeof m.content === "string" && m.content.trim()) {
+            return m.content.trim().replace(/\s+/g, " ").slice(0, 500);
+        }
+    }
+    return "(no task context available)";
+}
+const DEFAULT_TIMEOUT_MS = 6000;
+/** Ask the cheap model to veto a single high-risk action. Conservative + fail-open:
+ *   - no provider            → allow (guardian effectively off; deterministic layers still apply)
+ *   - timeout / error        → allow (a guardian glitch must never break legit work)
+ *   - unparseable reply      → allow
+ *  Only a clean, parsed `block` blocks. */
+export async function guardianVeto(provider, action, history, opts = {}) {
+    if (!provider)
+        return { decision: "allow", reason: "" }; // fail-open: no model → deterministic layers still guard
+    const prompt = `TASK CONTEXT:\n${taskSummary(history)}\n\n` +
+        `HIGH-RISK ACTION (flagged: ${action.classifierReason}):\n` +
+        `tool: ${action.tool}\n${action.detail}\n\n` +
+        `Allow or block this action? Reply with only the JSON verdict.`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    // Chain the caller's interrupt signal so Esc also aborts the guardian call.
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            ac.abort();
+        else
+            opts.signal.addEventListener("abort", () => ac.abort(), { once: true });
+    }
+    try {
+        const r = await provider.turn({
+            system: GUARDIAN_SYSTEM,
+            history: [{ role: "user", content: prompt }],
+            tools: [],
+            onText: () => { },
+            signal: ac.signal,
+        });
+        if (r.stop === "error")
+            return { decision: "allow", reason: "" }; // fail-open on model error
+        return parseVerdict(r.text);
+    }
+    catch {
+        return { decision: "allow", reason: "" }; // fail-open on timeout/abort/throw
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function newBreaker() {
+    return { blocks: 0, tripped: false };
+}
+/** Record a guardian BLOCK; trip the breaker at the threshold. Returns the (possibly updated) state's
+ *  tripped flag. Deterministic — a harder stop than the soft stuck-guard nudge. */
+export function recordBlock(state, threshold = GUARDIAN_BLOCK_THRESHOLD) {
+    state.blocks += 1;
+    if (state.blocks >= threshold)
+        state.tripped = true;
+    return state.tripped;
+}
+export const GUARDIAN_BLOCK_THRESHOLD = 3;
+// ── Config ─────────────────────────────────────────────────────────────────────────────────────────────
+/** Guardian is ON by default and only engages on high-risk actions (so normal turns are untouched).
+ *  Off via `HARA_GUARDIAN=0` (or config key `guardian: "off"`). Any other value / unset → on. */
+export function guardianEnabled(config) {
+    const env = process.env.HARA_GUARDIAN;
+    if (env !== undefined)
+        return !(env === "0" || env.toLowerCase() === "off" || env.toLowerCase() === "false");
+    if (config?.guardian !== undefined)
+        return !(config.guardian === "off" || config.guardian === "false");
+    return true; // default on
+}

package/dist/tools/ask_user.js

@@ -0,0 +1,64 @@
+// ask_user — pause mid-turn to ask the user a structured question and continue with their answer.
+// Mirrors Claude Code's AskUserQuestion / cc-haha + hermes `ask_user`: use it ONLY when genuinely blocked
+// on a decision only the user can make (an ambiguous requirement, a real fork in approach) — never for
+// anything you can derive from the code/context. The question (and optional numbered choices) is shown
+// through the SAME input channel as the approval prompt (ctx.ask), so it works in both the classic REPL and
+// the TUI. In headless / non-TTY / `-p` / gateway runs there is no interactive user (ctx.ask is absent) — the
+// tool returns a clear "proceed with your best judgment" string instead of hanging. kind:"read" so it never
+// itself triggers the approval gate (the interaction IS the prompt).
+import { registerTool } from "./registry.js";
+/** Returned when nobody can answer (headless / non-TTY / -p / gateway / sub-agent). Phrased so the model
+ *  keeps going on its own judgment rather than re-asking or stalling. */
+export const NO_INTERACTIVE_USER = "(no interactive user available — proceed with your best judgment)";
+registerTool({
+    name: "ask_user",
+    description: "Ask the user ONE structured question mid-turn and wait for their answer, then continue. " +
+        "Use this ONLY when you are genuinely blocked on a decision that ONLY the user can make — an ambiguous " +
+        "requirement, a missing preference, or a real fork in approach where guessing wrong is costly. " +
+        "Do NOT use it for anything you can infer from the code, files, or context, and do NOT use it to narrate " +
+        "or ask permission for an action (the approval gate already handles that). " +
+        "Provide `options` (a short list of likely answers) when the choice is constrained — they are shown as a " +
+        "numbered menu — but the user may always type a free-text answer instead. The tool returns the user's " +
+        "answer (chosen option or free text) as its result. " +
+        "In a non-interactive run (no terminal) it returns a 'proceed with your best judgment' note instead of " +
+        "blocking, so prefer making a reasonable call over asking when context already answers the question.",
+    kind: "read", // the prompt itself is the interaction; never route it through the approval gate
+    input_schema: {
+        type: "object",
+        properties: {
+            question: { type: "string", description: "the single, specific question to put to the user" },
+            options: {
+                type: "array",
+                items: { type: "string" },
+                description: "optional likely answers, shown as a numbered menu (the user may still type their own answer)",
+            },
+            header: { type: "string", description: "optional short label/topic for the question (e.g. 'Database choice')" },
+            context: { type: "string", description: "optional one-line context shown before the question (keep it short)" },
+        },
+        required: ["question"],
+    },
+    async run(input, ctx) {
+        const question = typeof input.question === "string" ? input.question.trim() : "";
+        if (!question)
+            return "ask_user needs a non-empty `question`.";
+        // No interactive user (headless / non-TTY / -p / gateway / sub-agent): do NOT block — let the model proceed.
+        if (typeof ctx.ask !== "function")
+            return NO_INTERACTIVE_USER;
+        const options = Array.isArray(input.options)
+            ? input.options.map((o) => String(o ?? "").trim()).filter((o) => o.length > 0)
+            : undefined;
+        const header = typeof input.header === "string" ? input.header.trim() : "";
+        const context = typeof input.context === "string" ? input.context.trim() : "";
+        // Compose a compact prompt: [header] (context) question — the channel renders it.
+        const prompt = [header ? `[${header}] ` : "", context ? `${context}\n` : "", question].join("");
+        try {
+            const answer = await ctx.ask(prompt, options && options.length ? options : undefined);
+            const text = typeof answer === "string" ? answer.trim() : "";
+            return text || "(the user gave an empty answer)";
+        }
+        catch (e) {
+            // If the interactive prompt fails for any reason, degrade gracefully rather than crash the turn.
+            return `${NO_INTERACTIVE_USER} (ask failed: ${e?.message ?? e})`;
+        }
+    },
+});

package/dist/tui/App.js

@@ -18,6 +18,22 @@ import { currentTodos, onTodosChange } from "../tools/todo.js";
 let _id = 0;
 const nid = () => ++_id;
 const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, "");
+/** Prepare a finalized turn item for the append-only `<Static>` scrollback. A completed reasoning
+ *  block collapses to a single-line "✻ thought · N lines" notice (its full text preserved in `full`
+ *  for the Ctrl+T overlay) — mirroring codex writing finalized rows to scrollback ONCE. Every other
+ *  kind passes through unchanged. Used both mid-turn (as blocks finalize) and at turn end so a given
+ *  turn's reasoning is emitted to Static exactly once and never re-rendered/re-emitted. */
+function foldForHistory(it) {
+    if (it.kind !== "reasoning")
+        return it;
+    const lines = it.text.split("\n").filter((l) => l.trim()).length;
+    return { ...it, kind: "notice", text: `✻ thought · ${lines} lines`, full: it.text };
+}
+/** Redraw throttle for the LIVE region (~30fps). A fast token stream or a slow/remote terminal can
+ *  push deltas far faster than a human perceives; without a cap ink re-diffs the growing dynamic
+ *  block on every token, which over a laggy link leaves stale duplicate lines + jitter. 33ms clamps
+ *  the live re-render rate while state itself stays exact (nothing is dropped, only coalesced). */
+const LIVE_FRAME_MS = 33;
 function Block({ item, open }) {
     switch (item.kind) {
         case "user":
@@ -217,6 +233,9 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
     const [status, setStatus] = useState({ ...initialStatus, agents: 0 });
     const [prompt, setPrompt] = useState(null);
     const [promptSel, setPromptSel] = useState(0);
+    // Free-text question prompt (ask_user with no/declined options): re-enables the InputBox to capture one
+    // line, then resolves the awaiting tool with that text. Separate from `prompt` (the select-only path).
+    const [askText, setAskText] = useState(null);
     const [reasoningOpen, setReasoningOpen] = useState(false);
     const [showTranscript, setShowTranscript] = useState(false); // Ctrl+T full-transcript overlay
     // Live checklist mirror: TodoPanel reads this, and `Working` derives its spinner verb from the
@@ -230,15 +249,25 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
     const queueRef = useRef([]); // type-ahead: FIFO of messages entered while working
     const [pool, setPool] = useState([]); // type-ahead pool: queued message lines, shown above the input
     const drainingRef = useRef(false); // idempotency guard so the drain effect can't double-send one item
-    const currentRef = useRef([]);
-    currentRef.current = current;
     const statusRef = useRef(status);
     statusRef.current = status;
+    // Live-region write path (codex-style): deltas mutate `liveRef` synchronously (exact, never dropped),
+    // and a throttled flush (~30fps) reconciles it into the `current` React state that actually renders.
+    // As each block finalizes (a new block kind begins) its predecessors are appended to `history`
+    // (`<Static>`, rendered once) and dropped from the live buffer — so only the tail block stays dynamic.
+    const liveRef = useRef([]);
+    const flushTimerRef = useRef(null);
+    const toStaticRef = useRef([]); // finalized blocks awaiting append to <Static> on the next flush
     useEffect(() => {
         const fn = () => setStatus((s) => ({ ...s, agents: activity.running }));
         activity.onChange(fn);
         return () => activity.onChange(null);
     }, []);
+    // Cancel any pending live-region flush on unmount so a timer can't fire after teardown.
+    useEffect(() => () => {
+        if (flushTimerRef.current)
+            clearTimeout(flushTimerRef.current);
+    }, []);
     // Subscribe to todo_write updates so the panel re-renders when the agent edits the checklist.
     useEffect(() => {
         const unsub = onTodosChange((list) => {
@@ -255,14 +284,46 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
                 clearTimeout(collapseTimerRef.current);
         };
     }, []);
-    const pushCurrent = useCallback((kind, text, merge = false) => {
-        setCurrent((cur) => {
-            const last = cur[cur.length - 1];
-            if (merge && last && last.kind === kind)
-                return [...cur.slice(0, -1), { ...last, text: last.text + text }];
-            return [...cur, { id: nid(), kind, text }];
-        });
+    // Reconcile the synchronously-mutated live buffer into React state, at most once per ~33ms. First
+    // append any finalized blocks to <Static> (once, in order), then publish the remaining live tail.
+    // The array identities are fresh each flush so React/ink re-render exactly the minimal live region.
+    const flushLive = useCallback(() => {
+        flushTimerRef.current = null;
+        if (toStaticRef.current.length) {
+            const graduated = toStaticRef.current;
+            toStaticRef.current = [];
+            setHistory((h) => [...h, ...graduated]);
+        }
+        setCurrent(liveRef.current.slice());
     }, []);
+    // Schedule a throttled flush. Coalesces a burst of deltas into one re-render per LIVE_FRAME_MS —
+    // the leading edge is immediate (snappy first paint) and subsequent deltas ride the timer.
+    const scheduleFlush = useCallback(() => {
+        if (flushTimerRef.current)
+            return;
+        flushTimerRef.current = setTimeout(flushLive, LIVE_FRAME_MS);
+    }, [flushLive]);
+    const pushCurrent = useCallback((kind, text, merge = false) => {
+        const live = liveRef.current;
+        const last = live[live.length - 1];
+        if (merge && last && last.kind === kind) {
+            // Same streaming block continues — grow it in place in the live buffer (no new React item).
+            live[live.length - 1] = { ...last, text: last.text + text };
+        }
+        else {
+            // A new block begins. Everything before it in the live buffer is now finalized: graduate it
+            // to <Static> (folding reasoning) so it's written to scrollback ONCE and never re-rendered.
+            if (live.length) {
+                for (const it of live)
+                    toStaticRef.current.push(foldForHistory(it));
+                liveRef.current = [{ id: nid(), kind, text }];
+            }
+            else {
+                live.push({ id: nid(), kind, text });
+            }
+        }
+        scheduleFlush();
+    }, [scheduleFlush]);
     // Lazy vision notice: 顾雅 spec — the header no longer carries an always-on "👁 …" line.
     // Instead, the first time an image attachment shows up in this session, we print the
     // routing notice once (inline). `visionShownRef` is the session-scoped flag.
@@ -290,6 +351,14 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
     }, [pushCurrent, noteVisionIfNeeded]);
     const handleSubmit = useCallback(async (line, images) => {
         const t = line.trim();
+        // A free-text question (ask_user) is awaiting an answer: this submission IS the answer, not a new turn.
+        if (askText) {
+            const r = askText.resolve;
+            setAskText(null);
+            setHistory((h) => [...h, { id: nid(), kind: "user", text: t }]);
+            r(t);
+            return;
+        }
         if ((!t && !images?.length) || prompt)
             return; // nothing to send, or a choice is pending
         if (working) {
@@ -323,24 +392,43 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
             { label: "No  (esc)", value: false, key: "n" },
         ]);
         const selectFn = (title, options) => openPrompt(title, options);
+        // Free-text question: re-enable the InputBox to read one line (resolves via handleSubmit's askText branch).
+        const askTextFn = (title) => new Promise((resolve) => setAskText({ title, resolve }));
+        // ask_user: when options are given, offer them as a select + a "type my own" escape hatch; otherwise (or
+        // when the user chooses to type their own) capture a free-text line. Returns the chosen/typed answer.
+        const OTHER = "__ask_other__"; // sentinel value for the "type my own" option
+        const askFn = async (question, options) => {
+            if (options && options.length) {
+                const choice = await openPrompt(question, [
+                    ...options.map((o) => ({ label: o, value: o })),
+                    { label: "✎ Type my own answer", value: OTHER },
+                ]);
+                if (choice !== OTHER)
+                    return choice;
+            }
+            return askTextFn(question);
+        };
         const setApprovalFn = (m) => setStatus((s) => ({ ...s, approval: m }));
         try {
-            await onSubmit(t, { sink, confirm: confirmFn, select: selectFn, setApproval: setApprovalFn, signal: ctrl.signal, exit, approval: statusRef.current.approval, drainQueue }, images);
+            await onSubmit(t, { sink, confirm: confirmFn, select: selectFn, ask: askFn, setApproval: setApprovalFn, signal: ctrl.signal, exit, approval: statusRef.current.approval, drainQueue }, images);
         }
         catch (e) {
             pushCurrent("notice", `error: ${e instanceof Error ? e.message : String(e)}`);
         }
-        // Commit this turn's items to scrollback. Read the LIVE current via the updater — currentRef only
-        // syncs on render (line ~225), so a fast slash-only turn (/design, /help, /skills…) that pushes a
-        // notice and returns before any re-render would otherwise commit nothing and lose the notice.
-        setCurrent((cur) => {
-            const committed = cur.map((it) => it.kind === "reasoning"
-                ? { ...it, kind: "notice", text: `✻ thought · ${it.text.split("\n").filter((l) => l.trim()).length} lines`, full: it.text }
-                : it);
-            if (committed.length)
-                setHistory((h) => [...h, ...committed]);
-            return [];
-        });
+        // Commit this turn's items to scrollback. The authoritative source is the synchronous live
+        // buffer (liveRef + any blocks already graduated to toStaticRef), NOT the throttled `current`
+        // React state — so a fast slash-only turn (/design, /help, /skills…) that pushes a notice and
+        // returns before a flush fires still commits it, and a pending throttle timer can't double-emit.
+        if (flushTimerRef.current) {
+            clearTimeout(flushTimerRef.current);
+            flushTimerRef.current = null;
+        }
+        const committed = [...toStaticRef.current, ...liveRef.current.map(foldForHistory)];
+        toStaticRef.current = [];
+        liveRef.current = [];
+        if (committed.length)
+            setHistory((h) => [...h, ...committed]);
+        setCurrent([]);
         setWorking(false);
         ctrlRef.current = null;
         // Schedule a panel collapse: if there was a checklist this turn, fold it to a one-line summary
@@ -357,11 +445,11 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
                 collapseTimerRef.current = null;
             }, 30_000);
         }
-    }, [working, prompt, onSubmit, pushCurrent, model, exit, drainQueue, noteVisionIfNeeded]);
+    }, [working, prompt, askText, onSubmit, pushCurrent, model, exit, drainQueue, noteVisionIfNeeded]);
     // Drain the type-ahead pool: when the turn finishes (working → false) and nothing awaits a choice, COALESCE
     // every pooled message into ONE turn and send it — additions/clarifications go to the agent together, in order.
     useEffect(() => {
-        if (working || prompt || drainingRef.current || !queueRef.current.length)
+        if (working || prompt || askText || drainingRef.current || !queueRef.current.length)
             return;
         drainingRef.current = true;
         const batch = queueRef.current;
@@ -372,12 +460,21 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
         void Promise.resolve(handleSubmit(line, images.length ? images : undefined)).finally(() => {
             drainingRef.current = false;
         });
-    }, [working, prompt, handleSubmit]);
+    }, [working, prompt, askText, handleSubmit]);
     useInput((input, key) => {
         if (key.ctrl && input === "t")
             return setShowTranscript((x) => !x); // open/close the full-transcript overlay
         if (showTranscript)
             return; // while open, the overlay's own useInput owns every key (scroll / esc)
+        // Free-text question awaiting an answer: Esc cancels (empty answer); all other keys belong to the InputBox.
+        if (askText) {
+            if (key.escape) {
+                const r = askText.resolve;
+                setAskText(null);
+                r("");
+            }
+            return;
+        }
         if (prompt) {
             const opts = prompt.options;
             if (key.upArrow)
@@ -420,5 +517,5 @@ export function App({ initialStatus, model, cwd, header, onSubmit, cycleApproval
     });
     if (showTranscript)
         return _jsx(Transcript, { items: [...history, ...current], onClose: () => setShowTranscript(false) });
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: header ? [{ id: -1, kind: "notice", text: "" }, ...history] : history, children: (item) => (item.id === -1 ? _jsx(HeaderCard, { ...header }, "hdr") : _jsx(Block, { item: item }, item.id)) }), current.map((item) => (_jsx(Block, { item: item, open: reasoningOpen }, item.id))), !prompt && _jsx(TodoPanel, { todos: todos }), working && !prompt && _jsx(Working, { todos: todos }), prompt && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "yellow", children: `  ${stripAnsi(prompt.title)}` }), prompt.options.map((o, i) => (_jsx(Text, { color: i === promptSel ? "cyan" : undefined, bold: i === promptSel, children: (i === promptSel ? " ❯ " : "   ") + `${i + 1}. ` + o.label }, i))), _jsx(Text, { dimColor: true, children: `   ↑↓ or 1–${prompt.options.length} to choose · Enter · Esc cancels` })] })), pool.length > 0 && !prompt && (_jsx(Box, { flexDirection: "column", children: pool.map((l, i) => (_jsx(Text, { color: accent(), children: `  › ${l.length > 72 ? l.slice(0, 72) + "…" : l}` }, i))) })), _jsx(InputBox, { status: status, cwd: cwd, isActive: !prompt, working: working, queued: pool.length, vim: vim, onSubmit: handleSubmit, onClipboardImage: onClipboardImage })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: header ? [{ id: -1, kind: "notice", text: "" }, ...history] : history, children: (item) => (item.id === -1 ? _jsx(HeaderCard, { ...header }, "hdr") : _jsx(Block, { item: item }, item.id)) }), current.map((item) => (_jsx(Block, { item: item, open: reasoningOpen }, item.id))), !prompt && _jsx(TodoPanel, { todos: todos }), working && !prompt && _jsx(Working, { todos: todos }), prompt && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "yellow", children: `  ${stripAnsi(prompt.title)}` }), prompt.options.map((o, i) => (_jsx(Text, { color: i === promptSel ? "cyan" : undefined, bold: i === promptSel, children: (i === promptSel ? " ❯ " : "   ") + `${i + 1}. ` + o.label }, i))), _jsx(Text, { dimColor: true, children: `   ↑↓ or 1–${prompt.options.length} to choose · Enter · Esc cancels` })] })), askText && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "yellow", children: `  ? ${stripAnsi(askText.title)}` }), _jsx(Text, { dimColor: true, children: "   type your answer below · Enter to send · Esc cancels" })] })), pool.length > 0 && !prompt && !askText && (_jsx(Box, { flexDirection: "column", children: pool.map((l, i) => (_jsx(Text, { color: accent(), children: `  › ${l.length > 72 ? l.slice(0, 72) + "…" : l}` }, i))) })), _jsx(InputBox, { status: status, cwd: cwd, isActive: !prompt, working: working && !askText, queued: pool.length, vim: vim, onSubmit: handleSubmit, onClipboardImage: onClipboardImage })] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanhara/hara",
-  "version": "0.95.2",
+  "version": "0.98.1",
   "description": "hara — a coding agent CLI that runs like an engineering org.",
   "bin": {
     "hara": "dist/index.js"