agent-from-zero 0.37.0 → 0.39.0

package/README.md

@@ -49,7 +49,7 @@ export DEEPSEEK_API_KEY=sk-你的key
 
 ### 配置审核模型 judge.model
 
-开启 auto 模式（会话里输入 `/auto`，或启动时加 `--auto`）后，每个需要审批的工具调用会先交给一个审核模型判断：安全的直接执行，有风险或拿不准的仍然问你。审核模型只有两种选择：
+开启 auto 模式（会话里输入 `/auto`，或启动时加 `--auto`）后，每个需要审批的工具调用会先交给一个审核模型判断：安全的直接执行；看不出是你要求的，先退回给 agent，让它换个做法或用表单问你（同一个任务里连续 3 次、累计 20 次还卡住，才弹给你）；你要求了但做了就回不去的（比如删掉 git 恢复不了的文件），弹出来让你确认。审核模型只有两种选择：
 
 1. **主 agent 用的模型**（默认）：和主 agent 共用同一个 API key 和 base URL。没配 `judge.model` 就直接用主 agent 当前的模型。
 2. **Jev**：配好 Jev 的 key 后自动优先用它（见下一节）。
@@ -85,6 +85,18 @@ export TYPESAFE_API_KEY=你的key
 }
 ```
 
+### 信任项目外的目录
+
+auto 模式下，改当前项目、其他 git 仓库或临时目录里的文件不用审批，其他地方的文件每次都要你确认。经常要改的目录（比如全局 skills 目录）可以写进**全局** settings（`~/.config/mini-agent/settings.json`），写在项目级 settings 里不生效：
+
+```json
+{
+  "autoMode": { "trustedDirs": ["~/.config/mini-agent/skills"] }
+}
+```
+
+也可以在确认弹窗里选 "Yes, and trust …/ for this session"，只对本次会话有效。家目录本身和 `/` 不能被信任，`settings.json` 本身永远要你确认。
+
 ### 换别的模型
 
 和 API key 放在同一个地方，设置这三个变量就行，各家的 base URL 写在 [.env.example](.env.example) 里：
@@ -121,6 +133,21 @@ export MINI_AGENT_MODEL=gpt-4.1-mini
 
 生成预测要多调一次模型，但请求内容和刚结束的主调用相同，只在最后加了一条指令，所以基本都能命中 DeepSeek 的前缀缓存，费用很低，也会算进 `/cost`。定时任务和其他实例发来的消息触发的回合不做预测。不想要可以在 `settings.json` 里设 `"promptSuggestions": false`，或者单次运行时设环境变量 `MINI_AGENT_PROMPT_SUGGESTIONS=0`。
 
+### 结果汇报、定时任务和长任务
+
+每轮结束时，agent 都会给一段一眼能看懂的结果：第一行先说结论，没别的要说就到此为止（比如“没有告警，一切正常”）；有问题的话，分段列出要点，每个问题写清楚是什么、在哪、有什么影响，以及需要你决定的事。
+
+定时任务（直接跟 agent 说“每 30 分钟查一次 prod 告警”就能建，`/cron` 查看）每次执行完也按这个格式汇报。因为执行时你多半不在旁边，执行完终端会响一声，标签页会闪几下。
+
+长任务：
+
+- `run_bash` 前台命令默认 2 分钟超时，agent 预计会跑很久时可以把超时设到最多 10 分钟。
+- 更久的任务，或者不需要等它跑完的任务，交给后台（`run_bash_background`）或子 agent。它们跑完时如果 agent 已经停下来了，会自动开一轮，把结果交给 agent 接着处理，不用等你下一次发消息。`/bg` 可以查看后台任务。
+
+### 需要你选择时
+
+agent 需要你做决定时会弹出一个表单，和 Claude Code 的一样：每个问题一个标签页，←/→ 或 Tab 切换，↑/↓ 选择，Enter 确定。每个选项下面有说明；可以多选的问题用 `[✔]` 勾选；选项里没有合适的，选 “Type something” 直接输入；想先聊聊再决定，选 “Chat about this”。最后一页汇总所有回答，确认后提交。表单打开时也可以直接在输入框打字，按 Enter 就作为一条新消息发出去。
+
 ### 多开实例互相通信
 
 在几个终端里各开一个 mini-agent（比如一个在后端仓库、一个在前端仓库），它们会自动互相发现，不用配置。

package/dist/agent.js

@@ -21,7 +21,7 @@ import { parseCli, applyCliOptions, readPrintPrompt, CliUsageError } from "./cli
 import { reservePrintOutput, formatPrintResult, streamJsonInit, streamJsonMessage } from "./print.js";
 import { FollowUpQueue } from "./follow-up.js";
 import { reviewDebugCommand } from "./auto-debug.js";
-import { isPlanMode, setPlanMode } from "./permissions.js"; // plan mode: research-only until the user approves a plan
+import { approvalMenu, isPlanMode, setPlanMode } from "./permissions.js"; // plan mode: research-only until the user approves a plan; the shared approval menu
 import { undoLast, clearUndo, sessionChanges } from "./undo.js"; // /undo + /diff: take back, or review, this session's writes
 import { clearTodos, getTodos, renderTodos } from "./todos.js"; // the agent's plan: /todos to view, cleared with the conversation
 import { renderDiff } from "./diff.js"; // show what /undo put back / what /diff changed, reusing the Day 21 diff renderer
@@ -442,7 +442,7 @@ async function main() {
     // Fail closed: in a non-interactive session nobody can say yes, so the
     // answer is no. MINI_AGENT_AUTO_APPROVE=1 bypasses the QUESTION, but hard
     // denies were already enforced in permissions.ts before we get here.
-    const confirm = async (question, toolName) => {
+    const confirm = async (question, toolName, trustDir) => {
         console.log(chalk.yellow(`\n⚠ approval needed — ${question}`)); // always show what is being asked
         if (!autoMode.enabled && process.env.MINI_AGENT_AUTO_APPROVE === "1") {
             console.log(chalk.dim("  auto-approved (MINI_AGENT_AUTO_APPROVE=1)")); // bypass mode — say so out loud
@@ -453,15 +453,12 @@ async function main() {
             return false; // fail closed
         }
         // Selecting beats typing: ↑/↓ + Enter instead of "type y/N". The middle
-        // option lets the user stop being asked about this tool for the session.
-        const allowLabel = toolName ? `Yes, and don't ask again for ${toolName} this session` : "Yes, and don't ask again this session";
-        const options = autoMode.enabled ? ["Yes, once", "No — let me tell the agent what to do instead"] : ["Yes", allowLabel, "No — let me tell the agent what to do instead"];
-        const choice = await select(options);
-        const approved = choice === 0 || (!autoMode.enabled && choice === 1);
-        if (!autoMode.enabled && choice === 1 && toolName) {
-            CONFIG.permissions.allow.push(`tool:${toolName}`); // remember the grant for the rest of the session
-            console.log(chalk.dim(`  won't ask again for ${toolName} this session`));
-        }
+        // option lets the user stop being asked about this tool (or, in auto mode,
+        // this outside directory) for the session.
+        const menu = approvalMenu(autoMode.enabled, toolName, trustDir);
+        const { approved, granted } = menu.choose(await select(menu.options));
+        if (granted)
+            console.log(chalk.dim(`  ${granted}`));
         console.log(approved ? chalk.green("  ✓ approved") : chalk.yellow("  ✗ declined"));
         return approved;
     };

package/dist/auto-budget.js

@@ -1,14 +1,21 @@
 // One object per root task, shared by descendants and interrupt/resume. An
 // exhausted budget is sticky: a late successful worker cannot reopen the gate.
+// Claude Code's denial limits: 3 in a row or 20 per task. Rules-policy denials
+// stop the task there; score-policy doubts returned to the agent instead turn
+// back into human prompts (escalated) until an action executes again.
 export class AutoReviewBudget {
     consecutive = 0;
     total = 0;
     stopped = false;
     get exhausted() { return this.stopped; }
+    get escalated() { return this.consecutive >= 3 || this.total >= 20; }
     deny() {
+        this.block();
+        this.stopped ||= this.escalated;
+    }
+    block() {
         this.total++;
         this.consecutive++;
-        this.stopped ||= this.consecutive >= 3 || this.total >= 20;
     }
     executed() { if (!this.stopped)
         this.consecutive = 0; }

package/dist/auto-context.js

@@ -51,7 +51,7 @@ export function reviewHistory(messages, inherited) {
                 continue;
             const result = results.get(call.id);
             actions.push({ callId: call.id, tool: call.function.name, input: projectInput(call.function.name, call.function.arguments),
-                outcome: /^\[permission\] Auto-denied/.test(result) ? "auto_denied" : /^\[follow-up\]/.test(result) ? "skipped" : /^\[(?:permission|hook)\]/.test(result) ? "denied" : /^\[error\]/.test(result) ? "failed" : "returned", ...resultEvidence(result) });
+                outcome: /^\[permission\] Auto-(?:denied|blocked)/.test(result) ? "auto_denied" : /^\[follow-up\]/.test(result) ? "skipped" : /^\[(?:permission|hook)\]/.test(result) ? "denied" : /^\[error\]/.test(result) ? "failed" : "returned", ...resultEvidence(result) });
         }
     }
     let bytes = 0;

package/dist/auto-review.js

@@ -50,14 +50,19 @@ export function needsAuthorizationReview(assessment) {
 }
 // The ONLY semantic allow/ask decision. Boolean answers are categorical and keep
 // that representation in the UI. An invalid provider result can never approve.
+// Which dimension failed decides who hears the ask: a doubt about authorization
+// goes back to the agent (it can drop the step or ask the user), while risk with
+// clear authorization is irreversible work the user requested, so the human
+// confirms it.
 export function decideReview(assessment) {
     const { authorized, risky } = assessment;
     if (!valid(authorized) || !valid(risky))
         return { decision: "ask", reason: "Invalid review assessment" };
-    const allow = (typeof authorized === "boolean" ? authorized : authorized >= MIN_AUTHORIZATION)
-        && (typeof risky === "boolean" ? !risky : risky <= MAX_RISK);
+    const requested = typeof authorized === "boolean" ? authorized : authorized >= MIN_AUTHORIZATION;
+    const allow = requested && (typeof risky === "boolean" ? !risky : risky <= MAX_RISK);
     const format = (value) => typeof value === "boolean" ? (value ? "yes" : "no") : value.toFixed(3);
-    return { decision: allow ? "allow" : "ask", reason: `authorization=${format(authorized)}, risk=${format(risky)}${allow ? " — auto-approved" : " — human review required"}` };
+    const outcome = allow ? " — auto-approved" : requested ? " — human review required" : " — not clearly requested";
+    return { decision: allow ? "allow" : "ask", ...(requested ? {} : { unauthorized: true }), reason: `authorization=${format(authorized)}, risk=${format(risky)}${outcome}` };
 }
 // The score policy above remains a deliberate rollout fallback. Rules v1 has
 // no authorization/risk cutoffs: providers report facts, this resolver owns the

package/dist/auto.js

@@ -107,7 +107,8 @@ export class AutoMode {
     status() {
         if (CONFIG.bypassPermissions)
             return "(bypassPermissions — approvals and AI review skipped for this run; hard denies, plan restrictions and hooks still apply)";
-        return `(auto mode ${this.enabled ? "ON" : "OFF"} — ${this.backend}; ${this.enabled ? "uncertain or risky actions require approval" : "use /auto to enable"})`;
+        const enabled = this.policy === "rules" ? "uncertain or risky actions require approval" : "irreversible actions require approval; unrequested ones go back to the agent first";
+        return `(auto mode ${this.enabled ? "ON" : "OFF"} — ${this.backend}; ${this.enabled ? enabled : "use /auto to enable"})`;
     }
     async classify(tool, argsJson, userRequests, signal, options = {}) {
         if (this.policy === "rules")

package/dist/background.js

@@ -1,9 +1,9 @@
 // ============ Background tasks (Day 37) ============
-// The problem: run_bash blocks. A command that takes longer than its 30s
-// watchdog (npm install, a full test run, a build) is SIGKILLed before it
-// finishes, and even a 25s one freezes the agent — we sit idle, paying for
-// tokens we aren't using, while a child process churns. The model cannot think
-// and wait at the same time.
+// The problem: run_bash blocks. A command that takes longer than its watchdog
+// (2 minutes by default, 10 at most) is SIGKILLed before it finishes, and even
+// a shorter slow one (npm install, a full test run, a build) freezes the agent:
+// we sit idle, paying for tokens we aren't using, while a child process churns.
+// The model cannot think and wait at the same time.
 //
 // The fix, mirroring Claude Code: a command can be sent to the BACKGROUND. We
 // spawn it, hand the model a task id immediately, and let the loop keep going.
@@ -34,7 +34,7 @@ function append(task, chunk) {
 }
 // Start a command in the background. Returns its task id immediately — the
 // command keeps running after this returns. Note the deliberate omissions vs
-// run_bash: NO 30s timeout (the whole point is to outlive it) and NO turn
+// run_bash: NO timeout (the whole point is to outlive it) and NO turn
 // AbortSignal (Ctrl+C interrupts the current turn, but a background job is meant
 // to survive into later turns; only killAll, on session exit, stops them).
 export function startBackground(command) {
@@ -107,6 +107,11 @@ export function pendingNotifications() {
     // something it must echo. Tell it plainly that a job it started has finished.
     return `A background task you started has finished. Read the notification, then continue.\n\n${done.join("\n\n")}`;
 }
+// Has a task finished whose notification has not been delivered yet? Lets an
+// idle frontend wake the agent without consuming the notification itself.
+export function hasPendingNotifications() {
+    return [...tasks.values()].some((task) => task.status !== "running" && !task.notified);
+}
 // Read a background task's current state for the bash_output tool. Returns only
 // the output PRODUCED SINCE THE LAST POLL (like Claude Code's BashOutput), so
 // the model can watch a long job without re-reading the whole log each time.

package/dist/config.js

@@ -134,6 +134,11 @@ export const CONFIG = {
         policy: (process.env.MINI_AGENT_AUTO_POLICY ?? projectSettings.autoMode?.policy ?? globalSettings.autoMode?.policy ?? "scores") === "rules" ? "rules" : "scores",
         enabled: process.env.MINI_AGENT_AUTO_MODE !== undefined ? process.env.MINI_AGENT_AUTO_MODE === "1" : (projectSettings.autoMode?.enabled ?? globalSettings.autoMode?.enabled ?? false),
         model: projectSettings.autoMode?.model || globalSettings.autoMode?.model || "jev-1.13.0",
+        // GLOBAL settings only: a cloned repo's settings must never extend auto
+        // mode's write reach into your home. "Trust this directory" in the approval
+        // menu appends here for the rest of the session.
+        trustedDirs: (globalSettings.autoMode?.trustedDirs ?? []).filter((dir) => typeof dir === "string" && dir.trim())
+            .map((dir) => path.resolve(dir.replace(/^~(?=$|\/)/, os.homedir()))),
     },
     // Token prices for the /cost estimate (defaults applied in cost.ts). Project
     // overrides global; either may set just the fields it cares about.

package/dist/cron.js

@@ -162,15 +162,19 @@ export function listJobs() {
 // Shared by both consumers — the in-turn one (injectCronMessages in loop.ts, for
 // a job that fires mid-task) and the idle one (the REPL's idle processor, for a
 // job that fires while the user is at the prompt) — so they behave identically.
+// The report is the run's summary: the user was not watching, so a quiet run is
+// one line and anything wrong is laid out point by point (a prod-alert monitor:
+// "No alerts — all normal.", or each alert with what, where and impact).
 export function cronTriggerContent(job) {
     return [
         `[Cron job "${job.id}" triggered — ${job.cron}]`,
         ``,
         `${job.prompt}`,
         ``,
-        `Execute this now. When done, report the result directly to the user — make it visible and clear.`,
-        `If the task produces output (e.g. a shell command result, a file change, a value), show it.`,
-        `If there's nothing to show, confirm success with one line.`,
+        `Execute this now, then report to the user, who was not watching. Write the report in the language of the task above:`,
+        `- Nothing needs attention: ONE line that says so, e.g. "没有告警，一切正常。" / "No alerts — all normal."`,
+        `- Otherwise: first line the outcome, then bullet points under short bold labels — each problem with what, where and impact, then anything the user must decide or do.`,
+        `- Quote exact values (counts, names, error lines), never a raw log dump.`,
         ``,
         `After this, return to idle — do NOT start additional work unless the user asked for a chain of follow-ups.`,
     ].join("\n");

package/dist/form.js

@@ -1,80 +1,155 @@
 import chalk from "chalk"; // rendering only
-// The cursor walks a flat list of options. Multiple questions add a submit row;
-// with one question, explicitly choosing an option submits it immediately.
-export function formRowCount(questions) {
-    return questions.reduce((n, q) => n + q.options.length, 0) + (questions.length > 1 ? 1 : 0);
+export function formRows(questions, tab) {
+    const q = questions[tab];
+    if (!q)
+        return [{ kind: "submit" }, { kind: "cancel" }];
+    return [
+        ...q.options.map((_, index) => ({ kind: "option", index })),
+        { kind: "typed" },
+        ...(q.multiSelect ? [{ kind: "next" }] : []),
+        { kind: "chat" },
+    ];
 }
-// 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 };
+export function initFormState(questions) {
+    return { tab: 0, cursor: 0, picked: questions.map(() => []), typed: questions.map(() => "") };
 }
-// 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;
+// Is the cursor on a "Type something" row? The drivers route typed keys into
+// their line editor there (and load / clear it as the cursor arrives / leaves).
+export function onTypedRow(questions, state) {
+    return formRows(questions, state.tab)[state.cursor]?.kind === "typed";
 }
-export function initFormState(questions) {
-    return { cursor: 0, selections: questions.map(() => -1) }; // nothing chosen yet
+const answered = (state, q) => state.picked[q].length > 0;
+// Land on a tab with the cursor on its first chosen option, or at the top.
+function goToTab(state, tab) {
+    return { ...state, tab, cursor: Math.max(0, state.picked[tab]?.[0] ?? 0) };
 }
-// 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
+// The one transition function. `text` is what the driver's editor holds while
+// the cursor is on a "Type something" row; it is stored as that question's
+// typed answer before the action runs, so leaving the row keeps it. Returns the
+// next state, and an `outcome` when the form is finished.
+export function reduceForm(questions, state, action, text) {
+    const single = questions.length === 1; // no tabs, no review: picking submits
+    let s = { ...state, picked: state.picked.map((p) => p.slice()), typed: state.typed.slice() };
+    const q = questions[s.tab];
+    const typedIndex = q?.options.length ?? -1;
+    if (q && text !== undefined && onTypedRow(questions, s)) {
+        s.typed[s.tab] = text.trim();
+        // A multi-select typed answer counts as checked exactly while it has text.
+        if (q.multiSelect)
+            s.picked[s.tab] = s.picked[s.tab].filter((i) => i !== typedIndex).concat(s.typed[s.tab] ? [typedIndex] : []);
+    }
+    const rows = formRows(questions, s.tab);
+    const advance = () => single ? (answered(s, 0) ? { state: s, outcome: "submit" } : { state: s }) : { state: goToTab(s, s.tab + 1) };
+    switch (action) {
+        case "up":
+            return { state: { ...s, cursor: Math.max(0, s.cursor - 1) } };
+        case "down":
+            return { state: { ...s, cursor: Math.min(rows.length - 1, s.cursor + 1) } };
+        case "left":
+        case "right":
+            if (single)
+                return { state: s };
+            return { state: goToTab(s, Math.min(questions.length, Math.max(0, s.tab + (action === "left" ? -1 : 1)))) };
+        case "escape":
+            return { state: s, outcome: "cancel" };
     }
-    const selections = state.selections.slice();
-    selections[row.q] = row.opt; // set this question's answer (single-select)
-    return { state: { ...state, selections }, ...(questions.length === 1 ? { done: true } : {}) };
+    // enter
+    const row = rows[s.cursor];
+    switch (row?.kind) {
+        case "option":
+            if (q.multiSelect) {
+                const on = s.picked[s.tab].includes(row.index);
+                s.picked[s.tab] = on ? s.picked[s.tab].filter((i) => i !== row.index) : [...s.picked[s.tab], row.index].sort((a, b) => a - b);
+                return { state: s };
+            }
+            s.picked[s.tab] = [row.index];
+            return advance();
+        case "typed":
+            if (!s.typed[s.tab])
+                return { state: s }; // nothing typed yet
+            if (q.multiSelect)
+                return { state: { ...s, cursor: s.cursor + 1 } }; // checked by having text; move on to Next/Submit
+            s.picked[s.tab] = [typedIndex];
+            return advance();
+        case "next":
+            return advance();
+        case "chat":
+            return { state: s, outcome: "chat" };
+        case "submit": {
+            const gap = questions.findIndex((_, i) => !answered(s, i));
+            return gap < 0 ? { state: s, outcome: "submit" } : { state: goToTab(s, gap) }; // jump to what is still open
+        }
+        case "cancel":
+            return { state: s, outcome: "cancel" };
+    }
+    return { state: s };
+}
+// One question's answer: chosen labels in option order, the typed answer last.
+function answerText(q, state, i) {
+    return state.picked[i].map((p) => (p === q.options.length ? state.typed[i] : q.options[p]?.label ?? "")).filter(Boolean).join(", ");
 }
 // 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)" }));
+    return questions.map((q, i) => ({ question: q.question, answer: answerText(q, state, 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)";
+// The footer: what the keys do right now.
+export function formHint(questions, state) {
+    if (onTypedRow(questions, state))
+        return "Type your answer · Enter to use it · ↑/↓ to move · Esc to cancel";
+    return `Enter to select · ↑/↓ to move${questions.length > 1 ? " · ←/→ or Tab to switch questions" : ""} · Esc to cancel`;
+}
+// Render the current tab. `live` is the driver's editor text, shown on the
+// "Type something" row while the cursor is on it.
+export function renderForm(questions, state, live) {
+    const lines = [];
     if (questions.length > 1) {
-        lines.push(onSubmit ? chalk.green.bold(`❯ ${submitText}`) : chalk.dim(`  ${submitText}`));
-        lines.push("");
+        const tabs = questions.map((q, i) => {
+            const label = ` ${answered(state, i) ? "☒" : "☐"} ${q.header || `Q${i + 1}`} `;
+            return i === state.tab ? chalk.inverse(label) : label;
+        });
+        const submit = state.tab === questions.length ? chalk.inverse(" ✔ Submit ") : " ✔ Submit ";
+        lines.push(`${chalk.dim("←")}${[...tabs, submit].join("")}${chalk.dim("→")}`, "");
+    }
+    const rows = formRows(questions, state.tab);
+    const mark = (i, text) => (i === state.cursor ? chalk.cyan(`❯ ${text}`) : `  ${text}`);
+    const q = questions[state.tab];
+    if (!q) {
+        // The review tab: every question with its answer, then Submit / Cancel.
+        lines.push(chalk.bold("Review your answers"), "");
+        questions.forEach((qq, i) => {
+            const answer = answerText(qq, state, i);
+            lines.push(` ● ${qq.question}`, answer ? chalk.green(`   → ${answer}`) : chalk.yellow("   → (not answered)"));
+        });
+        lines.push("", chalk.dim("Ready to submit your answers?"), "");
+        rows.forEach((row, i) => lines.push(mark(i, `${i + 1}. ${row.kind === "submit" ? "Submit answers" : "Cancel"}`)));
+    }
+    else {
+        lines.push(chalk.bold(q.question), "");
+        const typedIndex = q.options.length;
+        rows.forEach((row, i) => {
+            const box = (on) => (q.multiSelect ? (on ? chalk.green("[✔] ") : "[ ] ") : "");
+            if (row.kind === "option") {
+                const option = q.options[row.index];
+                const on = state.picked[state.tab].includes(row.index);
+                const label = !q.multiSelect && on ? chalk.green(`${option.label} ✔`) : option.label;
+                lines.push(mark(i, `${row.index + 1}. ${box(on)}${label}`));
+                if (option.description)
+                    lines.push(chalk.dim(`     ${q.multiSelect ? "    " : ""}${option.description}`));
+            }
+            else if (row.kind === "typed") {
+                const text = i === state.cursor && live !== undefined ? live : state.typed[state.tab];
+                const on = state.picked[state.tab].includes(typedIndex);
+                const shown = text ? (!q.multiSelect && on ? chalk.green(`${text} ✔`) : text) : chalk.dim("Type something");
+                lines.push(mark(i, `${typedIndex + 1}. ${box(on)}${shown}`));
+            }
+            else if (row.kind === "next") {
+                lines.push(mark(i, `   ${questions.length > 1 && state.tab < questions.length - 1 ? "Next" : "Submit"}`));
+            }
+            else if (row.kind === "chat") {
+                lines.push(chalk.dim("  ─────"), mark(i, `${typedIndex + 2}. Chat about this`));
+            }
+        });
     }
-    lines.push(FORM_HINT);
+    lines.push("", chalk.dim(formHint(questions, state)));
     return lines.join("\n");
 }

package/dist/ink/app.js

@@ -6,14 +6,14 @@ import { Box, Text, Static, useInput, useApp } from "ink";
 import chalk from "chalk";
 import { COMPACTING_VERB, formatElapsed, renderMenu, MENU_HINT, formatModelChoices } from "../ui.js"; // status format + the SAME pure menu renderer the readline REPL uses
 import { renderMarkdown } from "../markdown.js"; // model speaks markdown → ANSI, same as the non-Ink REPL
-import { initFormState, reduceForm, renderForm, collectAnswers } from "../form.js"; // the ask_user form: pure state machine + renderer
+import { initFormState, reduceForm, renderForm, collectAnswers, onTypedRow } from "../form.js"; // the ask_user form: pure state machine + renderer
 import { CONFIG, saveGlobalSetting } from "../config.js"; // session allowlist + /model save
 import { effortMenu, setEffort } from "../effort.js";
 import { useSlashCompletion } from "./completion.js";
 import { generatePromptSuggestion } from "../suggestion.js"; // the predicted next message (Claude Code's prompt suggestion)
 import { lastRequestTools } from "../loop.js"; // resend the main call's tools so the guess hits the prompt cache
 import { commandNames, commandTokenRanges, inlineCommandGhost } from "../completion.js"; // which /command tokens to paint + the mid-text ghost suggestion
-import { TerminateReason, listAgentViews } from "../loop.js"; // how a turn can end
+import { TerminateReason, listAgentViews, finishedWorkPending, takeFinishedWork } from "../loop.js"; // how a turn can end + background work that finished while idle
 import { compactHistory, compactThreshold, contextWindowFor } from "../context.js"; // /compact + /model info
 import { forgetFilesExcept } from "../tools.js"; // /clear resets the file read-state
 import { clearUndo } from "../undo.js";
@@ -28,7 +28,7 @@ import { currentSession, peerInboxPending, readPeerInbox, peerMessageContent, pe
 import { cronItemsPending, consumeCronQueue, cronTriggerContent } from "../cron.js"; // cron scheduler (Day s14): fire scheduled jobs autonomously while idle
 import { newSessionId, saveSession, listSessions, loadSession, setSessionTitle, sessionPath } from "../session.js";
 import { generateSessionTitle, setTerminalTitle, refreshTerminalTitle, flashTerminalTitle } from "../title.js"; // concise session name, generated after the first message + the terminal tab that shows it
-import { isPlanMode, setPlanMode } from "../permissions.js";
+import { approvalMenu, isPlanMode, setPlanMode } from "../permissions.js";
 import { findSkill, recordSkillUsage, skillSource, skillUsageScores, userSkillMessages } from "../skills.js";
 import { SkillsPanel } from "./skills-panel.js"; // /skills: Claude Code's on / user-only / off manager
 import { extractMemories } from "../memory.js";
@@ -253,7 +253,7 @@ export function App({ session, runTurn, clipboard }) {
     // as the prompt (a user highlight bar, or a note for /skill); the loop appends
     // `content` to `messages` itself. The permission menu + ask_user form raise a
     // `pending` prompt that returns a promise the loop awaits.
-    const runConversationTurn = (content, display, attachments = [], goalTurn = false) => {
+    const runConversationTurn = (content, display, attachments = [], goalTurn = false, afterTurn) => {
         setDetails(null);
         setDetailOffset(0);
         if (display)
@@ -279,14 +279,11 @@ export function App({ session, runTurn, clipboard }) {
         const hooks = {
             images: attachments,
             output: sink,
-            confirm: (question, toolName) => new Promise((resolve) => {
-                const allowLabel = toolName ? `Yes, and don't ask again for ${toolName} this session` : "Yes, and don't ask again this session";
-                const options = autoMode.enabled ? ["Yes, once", "No — let me tell the agent what to do instead"] : ["Yes", allowLabel, "No — let me tell the agent what to do instead"];
-                openSelect(`⚠ approval needed — ${question}`, options, (i) => {
-                    const approved = i === 0 || (!autoMode.enabled && i === 1);
-                    if (!autoMode.enabled && approved && i === 1 && toolName)
-                        CONFIG.permissions.allow.push(`tool:${toolName}`); // "don't ask again" → session allowlist
-                    note(`${chalk.yellow("⚠ approval")} — ${question.split("\n")[0]} → ${approved ? chalk.green("✓ approved") : chalk.yellow("✗ declined")}`);
+            confirm: (question, toolName, trustDir) => new Promise((resolve) => {
+                const menu = approvalMenu(autoMode.enabled, toolName, trustDir); // same choices and session grants as the readline REPL
+                openSelect(`⚠ approval needed — ${question}`, menu.options, (i) => {
+                    const { approved, granted } = menu.choose(i);
+                    note(`${chalk.yellow("⚠ approval")} — ${question.split("\n")[0]} → ${approved ? chalk.green("✓ approved") : chalk.yellow("✗ declined")}${granted ? chalk.dim(` (${granted})`) : ""}`);
                     resolve(approved);
                 });
             }),
@@ -349,6 +346,7 @@ export function App({ session, runTurn, clipboard }) {
             // is saved: Stop does not fire on an interrupt or an error, and fires
             // before the save. An orchestrator reads this as "idle, transcript current".
             void runHooks("TurnEnd", { reason: ending.reason, last_assistant_message: ending.text });
+            afterTurn?.();
         });
     };
     // Covers immediate interruption and a message arriving as the turn finishes.
@@ -375,7 +373,29 @@ export function App({ session, runTurn, clipboard }) {
                 return;
             const content = fired.map(cronTriggerContent).join("\n\n---\n\n");
             const label = fired.length === 1 ? `⏰ cron ${fired[0].id} fired (${fired[0].cron})` : `⏰ ${fired.length} cron jobs fired`;
-            runConversationTurn(content, { kind: "note", text: chalk.cyan(label) }); // a cron NOTE (not a user bar); the agent runs it + reports
+            // A cron NOTE (not a user bar); the agent runs it and reports. When the run
+            // is over, ring the bell and blink the tab: you were probably not watching.
+            runConversationTurn(content, { kind: "note", text: chalk.cyan(label) }, [], false, () => flashTerminalTitle(6000, `⏰ ${fired.map((j) => j.id).join(", ")} done`));
+        }, 2000);
+        return () => clearInterval(id);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [busy, pending]);
+    // The FINISHED-WORK idle processor: a background job (run_bash_background) or
+    // a sub-agent (task) can finish after the turn that started it ended. Its
+    // result must still reach the model, so while idle we start a turn with it and
+    // the agent carries on, without waiting for your next message. Bell and tab
+    // blink when that turn is done: long work usually finishes while you're away.
+    useEffect(() => {
+        if (busy || pending || followUps.size)
+            return; // human follow-ups take priority
+        const id = setInterval(() => {
+            if (turn.current || !finishedWorkPending())
+                return;
+            const content = takeFinishedWork();
+            if (!content)
+                return;
+            const ids = [...content.matchAll(/<(?:task_id|id)>([^<]+)<\//g)].map((m) => m[1]).join(", ");
+            runConversationTurn(content, { kind: "note", text: chalk.cyan(`⚙ ${ids || "background work"} finished — the agent picks it up`) }, [], false, () => flashTerminalTitle(6000, `⚙ ${ids || "background work"} done`));
         }, 2000);
         return () => clearInterval(id);
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -1010,31 +1030,54 @@ export function App({ session, runTurn, clipboard }) {
             }
         }
         // The ask_user form is up: reuse form.ts's pure state machine verbatim.
+        // ↑/↓ rows, ←/→ or Tab questions, Enter chooses, Esc cancels. On a "Type
+        // something" row the input box IS the answer's editor: it travels with each
+        // action, is loaded when the cursor arrives and cleared when it leaves.
+        // Anywhere else, text in the input box is a follow-up, as before.
         if (pending?.kind === "form" && formState) {
-            if (key.upArrow) {
-                setFormState(reduceForm(pending.questions, formState, "up").state);
-                return;
-            }
-            else if (key.downArrow || key.tab) {
-                setFormState(reduceForm(pending.questions, formState, "down").state);
-                return;
-            }
-            else if ((key.return || modifiedReturn) && !input.trim()) {
-                const next = reduceForm(pending.questions, formState, "select");
-                setFormState(next.state);
-                if (next.done) {
-                    pending.resolve(collectAnswers(pending.questions, next.state));
+            const questions = pending.questions;
+            const typing = onTypedRow(questions, formState);
+            const act = (action) => {
+                const next = reduceForm(questions, formState, action, typing ? input : undefined);
+                const close = (result) => {
+                    pending.resolve(result);
                     setPending(null);
                     setFormState(null);
+                    if (typing) {
+                        setInput("");
+                        setCursor(0);
+                    }
+                };
+                if (next.outcome === "submit")
+                    return close(collectAnswers(questions, next.state));
+                if (next.outcome === "chat")
+                    return close("chat");
+                if (next.outcome === "cancel")
+                    return close(null);
+                setFormState(next.state);
+                const moved = next.state.tab !== formState.tab || next.state.cursor !== formState.cursor;
+                const stored = next.state.typed[next.state.tab] ?? "";
+                if (onTypedRow(questions, next.state) && moved && stored) {
+                    setInput(stored);
+                    setCursor(stored.length);
                 }
-                return;
-            }
-            else if (key.escape) {
-                pending.resolve(null);
-                setPending(null);
-                setFormState(null);
-                return;
-            }
+                else if (typing && !onTypedRow(questions, next.state)) {
+                    setInput("");
+                    setCursor(0);
+                }
+            };
+            if (key.upArrow)
+                return act("up");
+            if (key.downArrow)
+                return act("down");
+            if (key.tab)
+                return act(key.shift ? "left" : "right");
+            if ((key.leftArrow || key.rightArrow) && !input)
+                return act(key.leftArrow ? "left" : "right");
+            if ((key.return || modifiedReturn) && (typing || !input.trim()))
+                return act("enter");
+            if (key.escape)
+                return act("escape");
         }
         if ((key.tab || (key.rightArrow && !input)) && placeholder) { // Tab (or →) turns the predicted next message into real text; Enter then sends it
             setInput(placeholder);
@@ -1207,7 +1250,7 @@ export function App({ session, runTurn, clipboard }) {
     const agentDetailView = detailPage(selectedAgent?.transcript || "(Waiting for activity…)", agentPage, Math.max(1, Math.min(10, rows - 10)), Math.max(1, columns - 4));
     const detailView = detailPage(details === "tools" ? getToolCalls() ?? "No tool calls this turn." : details === "reasoning" ? getReasoning() ?? "No thinking recorded this turn." : "", detailOffset, Math.max(1, Math.min(12, rows - 9)), Math.max(1, columns - 4));
     const activity = rows >= 20 && busy && !details && !pending && !subAgentDetail && !followUps.size ? summarizeActivity(getToolActivity(), Date.now(), rows >= 30 && !agents.length ? 2 : 1) : [];
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: items, children: (item, i) => _jsx(ItemView, { item: item }, i) }), _jsxs(Box, { flexDirection: "column", height: !pending && (details || selectedAgent) ? Math.max(1, rows - 1) : undefined, overflow: "hidden", children: [live !== null && !details && !pending && !selectedAgent && (_jsxs(Box, { marginTop: rows >= 20 ? 1 : 0, flexDirection: "row", children: [_jsx(Text, { color: "green", children: "\u23FA " }), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { children: live === "" ? chalk.dim("…") : liveTail(live, rows, columns, followUps.size > 0) }) })] })), activity.map((group, i) => (_jsxs(Box, { flexDirection: "column", marginTop: i === 0 ? 1 : 0, children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { color: group.failed ? "yellow" : group.running ? "cyan" : "green", children: "\u25CF " }), _jsx(Text, { bold: true, children: group.title })] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  \u23BF ", group.detail] })] }, i))), !details && !pending && !selectedAgent && (status !== null || busy) && (_jsx(Box, { marginTop: rows >= 20 ? 1 : 0, children: _jsx(SpinnerLine, { text: status?.replace("Ctrl+C to interrupt", "Esc to interrupt") ?? (live !== null ? "Writing…" : "Working…") }) })), rows >= 20 && !details && !selectedAgent && !pending && (busy || getToolCallCount() > 0) && (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  ", getToolCallCount(), " tool calls \u00B7 Ctrl+T details \u00B7 Ctrl+R thinking", busy ? " · Esc interrupt" : ""] })), details && !pending && (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [details === "tools" ? "Tool details" : "Thinking", " \u00B7 ", detailView.pages - detailView.page, "/", detailView.pages, " \u00B7 \u2191\u2193 page \u00B7 Esc close", followUps.size ? ` · ${followUps.size} queued` : ""] }), _jsx(Text, { children: detailView.text })] })), selectedAgent && !pending && (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "blue", paddingX: 1, children: [_jsxs(Text, { bold: true, color: "cyan", wrap: "truncate-end", children: [selectedAgent.name, " \u00B7 ", selectedAgent.model, " \u00B7 ", selectedAgent.status, " \u00B7 Esc main"] }), _jsxs(Box, { children: [selectedAgent.status === "running" && _jsx(Spinner, {}), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [" ", selectedAgent.activity, " \u00B7 ", selectedAgent.toolCalls, " tools \u00B7 PgUp/PgDn details"] })] }), _jsx(Text, { children: agentDetailView.text })] })), pending?.kind === "select" && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "yellow", children: pending.header }), pending.body && _jsx(Box, { marginY: 1, children: _jsx(Text, { children: pending.body }) }), _jsx(Text, { children: renderMenu(pending.options, menuSel) }), _jsx(Text, { children: MENU_HINT })] })), pending?.kind === "skills" && (_jsx(SkillsPanel, { skills: everySkill(), maxRows: Math.max(3, rows - 14), onClose: (summary) => { setPending(null); note(chalk.dim(summary)); } })), pending?.kind === "form" && formState && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: renderForm(pending.questions, formState) }) })), pending && pending.kind !== "skills" && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: "Type a follow-up \u00B7 Enter sends text; empty input selects \u00B7 Esc cancels" }), !details && !selectedAgent && !pending && followUps.size > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: rows >= 20 ? 1 : 0, children: [_jsx(Text, { dimColor: true, wrap: "truncate-end", children: "Messages queued for the next tool boundary \u00B7 Esc / Ctrl+Enter interrupt and send" }), followUps.pending.slice(rows >= 20 ? -2 : -1).map((message, i) => _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  \u21B3 ", message.displayText ?? message.text] }, i)), followUps.size > 2 && _jsxs(Text, { dimColor: true, children: ["  \u2026 ", followUps.size - 2, " earlier messages queued"] })] })), pending?.kind !== "skills" && (_jsx(Box, { borderStyle: "round", borderColor: talkTo || planMode ? "magenta" : CONFIG.bypassPermissions ? "red" : autoEnabled ? "yellow" : "cyan", paddingX: 1, marginTop: rows >= 20 ? 1 : 0, flexDirection: "column", flexShrink: 0, children: (() => {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Static, { items: items, children: (item, i) => _jsx(ItemView, { item: item }, i) }), _jsxs(Box, { flexDirection: "column", height: !pending && (details || selectedAgent) ? Math.max(1, rows - 1) : undefined, overflow: "hidden", children: [live !== null && !details && !pending && !selectedAgent && (_jsxs(Box, { marginTop: rows >= 20 ? 1 : 0, flexDirection: "row", children: [_jsx(Text, { color: "green", children: "\u23FA " }), _jsx(Box, { flexGrow: 1, children: _jsx(Text, { children: live === "" ? chalk.dim("…") : liveTail(live, rows, columns, followUps.size > 0) }) })] })), activity.map((group, i) => (_jsxs(Box, { flexDirection: "column", marginTop: i === 0 ? 1 : 0, children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { color: group.failed ? "yellow" : group.running ? "cyan" : "green", children: "\u25CF " }), _jsx(Text, { bold: true, children: group.title })] }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  \u23BF ", group.detail] })] }, i))), !details && !pending && !selectedAgent && (status !== null || busy) && (_jsx(Box, { marginTop: rows >= 20 ? 1 : 0, children: _jsx(SpinnerLine, { text: status?.replace("Ctrl+C to interrupt", "Esc to interrupt") ?? (live !== null ? "Writing…" : "Working…") }) })), rows >= 20 && !details && !selectedAgent && !pending && (busy || getToolCallCount() > 0) && (_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  ", getToolCallCount(), " tool calls \u00B7 Ctrl+T details \u00B7 Ctrl+R thinking", busy ? " · Esc interrupt" : ""] })), details && !pending && (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [details === "tools" ? "Tool details" : "Thinking", " \u00B7 ", detailView.pages - detailView.page, "/", detailView.pages, " \u00B7 \u2191\u2193 page \u00B7 Esc close", followUps.size ? ` · ${followUps.size} queued` : ""] }), _jsx(Text, { children: detailView.text })] })), selectedAgent && !pending && (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "blue", paddingX: 1, children: [_jsxs(Text, { bold: true, color: "cyan", wrap: "truncate-end", children: [selectedAgent.name, " \u00B7 ", selectedAgent.model, " \u00B7 ", selectedAgent.status, " \u00B7 Esc main"] }), _jsxs(Box, { children: [selectedAgent.status === "running" && _jsx(Spinner, {}), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [" ", selectedAgent.activity, " \u00B7 ", selectedAgent.toolCalls, " tools \u00B7 PgUp/PgDn details"] })] }), _jsx(Text, { children: agentDetailView.text })] })), pending?.kind === "select" && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { color: "yellow", children: pending.header }), pending.body && _jsx(Box, { marginY: 1, children: _jsx(Text, { children: pending.body }) }), _jsx(Text, { children: renderMenu(pending.options, menuSel) }), _jsx(Text, { children: MENU_HINT })] })), pending?.kind === "skills" && (_jsx(SkillsPanel, { skills: everySkill(), maxRows: Math.max(3, rows - 14), onClose: (summary) => { setPending(null); note(chalk.dim(summary)); } })), pending?.kind === "form" && formState && (_jsx(Box, { marginTop: 1, children: _jsx(Text, { children: renderForm(pending.questions, formState, onTypedRow(pending.questions, formState) ? input : undefined) }) })), pending && pending.kind !== "skills" && pending.kind !== "form" && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: "Type a follow-up \u00B7 Enter sends text; empty input selects \u00B7 Esc cancels" }), pending?.kind === "form" && formState && !onTypedRow(pending.questions, formState) && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: "Or type a follow-up below \u00B7 Enter sends it instead of answering" }), !details && !selectedAgent && !pending && followUps.size > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: rows >= 20 ? 1 : 0, children: [_jsx(Text, { dimColor: true, wrap: "truncate-end", children: "Messages queued for the next tool boundary \u00B7 Esc / Ctrl+Enter interrupt and send" }), followUps.pending.slice(rows >= 20 ? -2 : -1).map((message, i) => _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["  \u21B3 ", message.displayText ?? message.text] }, i)), followUps.size > 2 && _jsxs(Text, { dimColor: true, children: ["  \u2026 ", followUps.size - 2, " earlier messages queued"] })] })), pending?.kind !== "skills" && (_jsx(Box, { borderStyle: "round", borderColor: talkTo || planMode ? "magenta" : CONFIG.bypassPermissions ? "red" : autoEnabled ? "yellow" : "cyan", paddingX: 1, marginTop: rows >= 20 ? 1 : 0, flexDirection: "column", flexShrink: 0, children: (() => {
                             const prompt = talkTo ? `→ ${talkTo.name} ❯ ` : "❯ ";
                             const promptColor = talkTo ? "magenta" : planMode ? "magenta" : CONFIG.bypassPermissions ? "red" : autoEnabled ? "yellow" : "cyan";
                             const cols = columns;

package/dist/loop.js

@@ -20,7 +20,7 @@ import { recordToolCall, recordToolResult, recordToolDetail, recordReasoning } f
 import { STDOUT_OUTPUT } from "./output.js"; // where the loop's screen output goes (stdout by default, Ink REPL passes its own)
 import { todoNag, getTodos, renderTodos } from "./todos.js"; // the agent's plan: show it on screen + nag when it goes stale
 import { currentSkills, skillBodyMessages, skillListingReminder, syncSkillTool } from "./skills.js"; // skill listing reminders + launched skill bodies
-import { pendingNotifications } from "./background.js"; // background tasks (Day 37): surface finished jobs as a turn
+import { pendingNotifications, hasPendingNotifications } from "./background.js"; // background tasks (Day 37): surface finished jobs as a turn
 import { consumeCronQueue, cronItemsPending, cronTriggerContent } from "./cron.js"; // cron scheduler (Day s14): scheduled, recurring work
 import { getGoal, updateGoalTool, runUpdateGoal, countGoalToolCall } from "./goal.js"; // /goal (Day 41): the model ends a durable goal with update_goal
 export const MAX_RETRIES = 10; // total failed API calls per query, across all rounds
@@ -105,21 +105,35 @@ const askUserTool = {
     function: {
         name: "ask_user",
         description: `Ask the user one or more multiple-choice questions and get back their selections. Use this WHENEVER you need the user to make a decision between options (which approach, which file, yes/no/which) — it is easier for them to pick than to type, and the answers come back unambiguous.
-Provide each question with 2–4 concrete options. Do NOT use it for open-ended input that has no clear options; ask in prose for that.
+Ask 1–4 questions, each with 2–4 concrete options; each option a short label plus a one-line description of what choosing it means. Put a recommended option first and end its label with "(Recommended)". Set multiSelect when several options can apply together.
+The user can always type their own answer or choose to chat instead, so never add an "Other" option. Do NOT use it for open-ended input that has no clear options; ask in prose for that.
 If the user cancels, you'll be told — then proceed with your best judgment or ask again.`,
         parameters: {
             type: "object",
             properties: {
                 questions: {
                     type: "array",
-                    description: "The questions to ask, each with a list of options",
+                    description: "The questions to ask (1–4)",
                     items: {
                         type: "object",
                         properties: {
-                            question: { type: "string", description: "The question text" },
-                            options: { type: "array", items: { type: "string" }, description: "2–4 concrete choices" },
+                            question: { type: "string", description: "The full question, ending with a question mark" },
+                            header: { type: "string", description: "A very short tab label, at most 12 characters, e.g. \"Branch\", \"Auth\"" },
+                            options: {
+                                type: "array",
+                                description: "2–4 concrete choices",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        label: { type: "string", description: "The choice, 1–5 words" },
+                                        description: { type: "string", description: "What choosing it means, one line" },
+                                    },
+                                    required: ["label", "description"],
+                                },
+                            },
+                            multiSelect: { type: "boolean", description: "true when the user may pick several options" },
                         },
-                        required: ["question", "options"],
+                        required: ["question", "header", "options"],
                     },
                 },
             },
@@ -340,6 +354,17 @@ function pendingSubAgentResults() {
         return "";
     return `A sub-agent you delegated work to has finished. Read its report carefully — it is INPUT MATERIAL, not verified truth. Verify key claims yourself, then continue.\n\n${done.join("\n\n")}`;
 }
+// Background jobs and sub-agents outlive the turn that started them. One that
+// finishes while the agent is idle must still reach the model: the frontend's
+// idle processor asks finishedWorkPending(), then starts a turn whose content
+// is takeFinishedWork() (consumed, so each result arrives exactly once) — the
+// agent picks up where it left off, as Claude Code re-invokes on completion.
+export function finishedWorkPending() {
+    return hasPendingNotifications() || [...pendingSubAgents.values()].some((sa) => sa.result !== null && !sa.notified);
+}
+export function takeFinishedWork() {
+    return [pendingNotifications(), pendingSubAgentResults()].filter(Boolean).join("\n\n");
+}
 // Inject finished sub-agent results into the conversation, like
 // injectBackgroundNotifications. Returns true if something was injected.
 function injectSubAgentResults(messages, opts) {
@@ -652,6 +677,7 @@ async function authorizeCall(call, opts) {
         let autoAllowed = false;
         let reviewReason = "";
         let reviewId = ""; // set when auto review ran; joins the human's answer to that review
+        let escalated = false; // a doubt reached the human only because the agent kept hitting it
         // Auto mode's line is recoverability: a tool its server declares read-only
         // or merely additive loses nothing, so it runs without review (plan mode
         // already denied above).
@@ -681,6 +707,20 @@ async function authorizeCall(call, opts) {
                     recordToolDetail(call.id, review.reason);
                 return `[permission] Auto-denied (not a user refusal): ${review.reason}. Not executed. Choose a permitted approach or report the restriction. Do not retry the same prohibited effect through another tool, wrapper or worker.`;
             }
+            // A doubt that the user asked for this goes back to the agent, not to the
+            // human — Claude Code's denial policy. The agent drops the step, takes one
+            // within the request, or asks with ask_user (a submitted answer is fresh
+            // authorization). Only an agent stuck against the reviewer (3 in a row, 20
+            // per task) brings the question to the human after all. Judge-only
+            // review outside auto mode keeps the ordinary prompt.
+            if (auto && review.unauthorized && !opts.reviewBudget?.escalated) {
+                opts.reviewBudget?.block();
+                emit("agent_tool_auto_blocked", { tool: call.name, ...(reviewId ? { reviewId } : {}) });
+                if (!opts.quiet)
+                    recordToolDetail(call.id, review.reason);
+                return `[permission] Auto-blocked (not a user refusal): ${review.reason}. Not executed: the reviewer could not tie this action to what the user asked for. Drop it, take a step within the request, or, if it is truly needed, ask the user with ask_user (their answer counts as authorization). Do not retry the same effect through another tool, wrapper or worker.`;
+            }
+            escalated = auto && !!review.unauthorized;
             autoAllowed = review.decision === "allow";
             reviewReason = review.reason;
             if (!opts.quiet)
@@ -732,13 +772,14 @@ async function authorizeCall(call, opts) {
             if (preview)
                 sink(opts).note(preview.replace(/^/gm, agentIndent(opts)));
         }
-        const ok = autoAllowed || (!(auto && opts.canPrompt === false) && await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}${reviewReason ? `\n   ${reviewReason}` : ""}`, call.name));
+        const ok = autoAllowed || (!(auto && opts.canPrompt === false) && await opts.confirm(`${call.name} (${v.reason}):\n   ${v.summary}${reviewReason ? `\n   ${reviewReason}` : ""}`, call.name, v.trustDir));
         // Every human prompt in auto mode is an interruption worth counting, with
         // where it came from: the reviewer asked ("review", joinable by reviewId),
-        // or a rule required a human without review ("requires_human"). Approved is
-        // a likely false block, declined a correct one; "unattended" reached no one.
+        // a doubt outlived the agent's retries ("escalated"), or a rule required a
+        // human without review ("requires_human"). Approved is a likely false
+        // block, declined a correct one; "unattended" reached no one.
         if (auto && !autoAllowed)
-            emit("agent_auto_human", { tool: call.name, source: reviewId ? "review" : v.requiresHuman ? "requires_human" : "no_review",
+            emit("agent_auto_human", { tool: call.name, source: reviewId ? (escalated ? "escalated" : "review") : v.requiresHuman ? "requires_human" : "no_review",
                 decision: ok ? "approved" : opts.canPrompt === false ? "unattended" : "declined", ...(reviewId ? { reviewId } : {}) });
         if (!ok)
             emit("agent_tool_declined", { tool: call.name, ...(reviewId ? { reviewId } : {}) }); // the human said no — that is signal
@@ -1147,18 +1188,34 @@ async function runAskUser(call, opts) {
         return "[error] Sub-agents cannot ask the user. Decide yourself, or report back to the parent."; // only the top-level agent talks to the human
     if (!opts.askUser)
         return "[error] No interactive prompt is available in this session — ask in plain text instead.";
-    let questions = [];
+    let raw = [];
     try {
-        questions = JSON.parse(call.args).questions ?? [];
+        raw = JSON.parse(call.args).questions ?? [];
     }
     catch {
         /* fall through */
     }
-    // Keep only well-formed questions (text + at least two options).
-    questions = (questions ?? []).filter((q) => q && typeof q.question === "string" && Array.isArray(q.options) && q.options.length >= 2);
+    // Keep only well-formed questions (text + at least two options). An option may
+    // still arrive as a bare string (the original schema): it becomes a label.
+    const text = (v) => (typeof v === "string" ? v.trim() : "");
+    const option = (o) => {
+        const label = typeof o === "string" ? o.trim() : text(o?.label);
+        const description = typeof o === "object" && o ? text(o.description) : "";
+        return label ? { label, ...(description ? { description } : {}) } : null;
+    };
+    const questions = (Array.isArray(raw) ? raw : []).flatMap((q) => {
+        const question = text(q?.question);
+        const options = (Array.isArray(q?.options) ? q.options : []).map(option).filter((o) => o !== null);
+        if (!question || options.length < 2)
+            return [];
+        const header = text(q.header).slice(0, 16);
+        return [{ question, options, ...(header ? { header } : {}), ...(q.multiSelect === true || q.multiSelect === "true" ? { multiSelect: true } : {}) }];
+    });
     if (!questions.length)
         return "[error] ask_user needs at least one question with two or more options.";
     const answers = await opts.askUser(questions);
+    if (answers === "chat")
+        return "The user chose to talk this through instead of picking an option. Do not act on any of these questions yet: end your turn now and wait for their message.";
     if (!answers)
         return "The user dismissed the question form without answering. Proceed with your best judgment, or ask again if you truly need their input."; // cancelled / non-interactive
     return `The user answered:\n${answers.map((a) => `- ${a.question} → ${a.answer}`).join("\n")}`; // organized, unambiguous
@@ -1383,8 +1440,8 @@ opts) {
     if (askUser && !opts.subAgent)
         opts.askUser = async (questions) => {
             const answers = await askUser(questions);
-            if (!opts.signal.aborted && !opts.isInterrupted()) {
-                for (const answer of answers ?? []) {
+            if (Array.isArray(answers) && !opts.signal.aborted && !opts.isInterrupted()) {
+                for (const answer of answers) {
                     const question = questions.find((q) => q.question === answer.question);
                     if (question && typeof answer.answer === "string" && answer.answer.trim()) {
                         recordHumanInput(`Human form reply (question is context; only the submitted answer expresses the user's choice): ${JSON.stringify({ question: question.question, answer: answer.answer })}`);

package/dist/menu.js

@@ -2,7 +2,7 @@ import readline from "node:readline"; // raw-mode keypress events + the interfac
 import chalk from "chalk";
 import { reduceEditor, truncateToWidth } from "./editor.js";
 import { renderMenu, MENU_HINT } from "./ui.js"; // the pure drawing + the footer hint
-import { initFormState, reduceForm, renderForm, collectAnswers } from "./form.js"; // the multi-question form
+import { initFormState, reduceForm, renderForm, collectAnswers, onTypedRow } from "./form.js"; // the multi-question form
 // Navigation owns arrows; printable text belongs to this editor. Sending a
 // follow-up cancels the pending choice, never implicitly approves it.
 function promptDraft(submit, redraw, cancel) {
@@ -10,6 +10,7 @@ function promptDraft(submit, redraw, cancel) {
     let sending = false;
     let error = "";
     return {
+        hasText: () => state.buffer.length > 0,
         render: () => submit ? `\n${truncateToWidth(`Follow-up ❯ ${state.buffer.slice(0, state.cursor)}${chalk.inverse(state.buffer[state.cursor] ?? " ")}${state.buffer.slice(state.cursor + 1)}`, Math.max(10, (process.stdout.columns || 80) - 1))}\n${truncateToWidth(error || "Type a follow-up · Enter sends text; empty input selects", Math.max(10, (process.stdout.columns || 80) - 1))}` : "",
         handle(str, key) {
             if (sending)
@@ -126,19 +127,27 @@ onFollowUp) {
 // The multi-question form (Day 30): the agent asks several questions at once,
 // the user answers each and submits, and we hand back organized answers. Same
 // raw-mode borrow/return dance as promptSelect; the state machine is in form.ts.
-// Returns the answers, or null if cancelled / not a TTY.
+// Keys: ↑/↓ rows, ←/→ or Tab questions, Enter chooses, Esc cancels. On a "Type
+// something" row the typed keys edit the answer; anywhere else they start a
+// follow-up, which (like promptSelect) cancels the form when sent.
+// Returns the answers, "chat" (talk instead of answering), or null if
+// cancelled / not a TTY.
 export function promptForm(rl, questions, input = process.stdin, onFollowUp) {
     return new Promise((resolve) => {
         if (!input.isTTY || !questions.length)
             return resolve(null); // no form without a terminal or questions
         let state = initFormState(questions);
+        let answer = { buffer: "", cursor: 0 }; // the "Type something" editor
         let done = false;
         const wasRaw = input.isRaw === true; // restore this on exit, not false (see promptSelect)
-        const lineCount = renderForm(questions, state).split("\n").length + (onFollowUp ? 2 : 0);
+        let lineCount = 0; // tabs differ in height: redraw over whatever the last frame was
         const draw = (first) => {
+            const typing = onTypedRow(questions, state);
+            const frame = `${renderForm(questions, state, typing ? answer.buffer : undefined)}${typing ? "" : draft.render()}`;
             if (!first)
-                process.stdout.write(`\x1b[${lineCount}A`); // up over the whole form
-            process.stdout.write(`\x1b[J${renderForm(questions, state)}${draft.render()}\n`);
+                process.stdout.write(`\x1b[${lineCount}A`); // up over the previous frame
+            process.stdout.write(`\x1b[J${frame}\n`);
+            lineCount = frame.split("\n").length;
         };
         const finish = (result) => {
             if (done)
@@ -154,31 +163,60 @@ export function promptForm(rl, questions, input = process.stdin, onFollowUp) {
             rl.resume();
             resolve(result);
         };
+        // Apply one action. The answer editor travels with it while on a typed row,
+        // and follows the cursor: loaded on arrival, cleared on departure.
+        const act = (action) => {
+            const typing = onTypedRow(questions, state);
+            const next = reduceForm(questions, state, action, typing ? answer.buffer : undefined);
+            const arriving = onTypedRow(questions, next.state) && (!typing || next.state.tab !== state.tab || next.state.cursor !== state.cursor);
+            state = next.state;
+            if (next.outcome === "submit")
+                return finish(collectAnswers(questions, state));
+            if (next.outcome === "chat")
+                return finish("chat");
+            if (next.outcome === "cancel")
+                return finish(null);
+            if (arriving) {
+                const text = state.typed[state.tab];
+                answer = { buffer: text, cursor: text.length };
+            }
+            else if (!onTypedRow(questions, state))
+                answer = { buffer: "", cursor: 0 };
+            draw(false);
+        };
         const draft = promptDraft(onFollowUp, () => draw(false), () => finish(null));
         const onKey = (str, key) => {
             if (!key || done)
                 return;
-            if (draft.handle(str, key))
+            if (key.name === "escape" || (key.ctrl && key.name === "c"))
+                return act("escape");
+            const typing = onTypedRow(questions, state);
+            if (key.name === "up")
+                return act("up");
+            if (key.name === "down")
+                return act("down");
+            if (key.name === "tab")
+                return act(key.shift ? "left" : "right");
+            // ←/→ switch questions, unless there is text to move the caret through.
+            if ((key.name === "left" || key.name === "right") && !(typing ? answer.buffer : draft.hasText()))
+                return act(key.name);
+            if (key.name === "return" || key.name === "enter") {
+                if (typing || !draft.handle(str, key))
+                    act("enter"); // a drafted follow-up is sent by its own editor
                 return;
-            if (key.name === "up" || key.name === "k") {
-                state = reduceForm(questions, state, "up").state;
-                draw(false);
             }
-            else if (key.name === "down" || key.name === "j" || key.name === "tab") {
-                state = reduceForm(questions, state, "down").state;
-                draw(false);
-            }
-            else if (key.name === "return" || key.name === "enter" || key.name === "space") {
-                const next = reduceForm(questions, state, "select");
-                state = next.state;
-                if (next.done)
-                    finish(collectAnswers(questions, state)); // submitted with all answered
-                else
+            if (typing) {
+                const next = reduceEditor(answer, str, key);
+                if (next.action === "edit") {
+                    answer = next.state;
                     draw(false);
+                }
+                return;
             }
-            else if (key.name === "escape" || (key.ctrl && key.name === "c")) {
-                finish(null); // cancel
-            }
+            if (draft.handle(str, key))
+                return;
+            if (key.name === "space")
+                act("enter"); // space toggles / chooses too
         };
         try {
             rl.pause();

package/dist/permissions.js

@@ -2,7 +2,7 @@ import path from "node:path"; // used to resolve and split file paths
 import fs from "node:fs"; // resolve symlinks before auto mode grants file access
 import os from "node:os"; // `cd ~` in the recoverable-shell analyzer
 import { execFileSync } from "node:child_process"; // ask git whether a deletion target is disposable
-import { CONFIG } from "./config.js"; // user-configured allow/deny rules from settings files
+import { CONFIG, GLOBAL_SETTINGS_PATH } from "./config.js"; // user-configured allow/deny rules from settings files
 import { emit } from "./telemetry.js"; // a bypassed approval leaves an audit row, not silence
 // ---- The no-fly zone --------------------------------------------------------
 // Writes here are never OK, in any mode. .git can destroy history, shell rc
@@ -216,6 +216,27 @@ export function gitWorkTree(target) {
     }
     return topLevels.get(dir);
 }
+// Trusted ground outside any work tree: autoMode.trustedDirs from global
+// settings, plus directories trusted from the approval menu this session.
+// Home and / never count, for the same reason as above. Nor does the global
+// settings file: it holds this very list, and an agent that could edit it
+// unasked could widen its own reach.
+const tooBroadToTrust = (dir) => dir === os.homedir() || dir === resolveFileTarget(os.homedir()) || dir === path.parse(dir).root;
+const settingsFile = () => resolveFileTarget(GLOBAL_SETTINGS_PATH);
+function trustedDir(target) {
+    if (target === settingsFile())
+        return false;
+    return CONFIG.autoMode.trustedDirs.some((dir) => {
+        let root;
+        try {
+            root = resolveFileTarget(dir);
+        }
+        catch {
+            return false;
+        }
+        return !tooBroadToTrust(root) && inside(root, target);
+    });
+}
 // A deletion is recoverable when the target is scratch (inside a temp dir) or
 // git calls it disposable in its own repo: ignored (build output, caches) with
 // nothing tracked beneath it. Symlinks are left to review: `rm -r link/`
@@ -595,9 +616,13 @@ function basePermission(toolName, argsJson, auto) {
                 return { decision: "deny", reason, summary: args.path };
             const relative = path.relative(fs.realpathSync(process.cwd()), resolved);
             // Outside the start directory is still recoverable in another git work
-            // tree or a temp dir (git, /undo); anywhere else a human decides.
-            if (toolName !== "read_file" && (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) && !inTempDir(resolved) && !gitWorkTree(resolved)) {
-                return { decision: "ask", requiresHuman: true, reason: "resolved write target is outside the project", summary: `${args.path} → ${resolved}` };
+            // tree or a temp dir (git, /undo), and a trusted directory is one the
+            // user vouched for; anywhere else a human decides, and may trust the
+            // file's directory for the session rather than approve every write.
+            if (toolName !== "read_file" && (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) && !inTempDir(resolved) && !gitWorkTree(resolved) && !trustedDir(resolved)) {
+                const dir = path.dirname(resolved);
+                return { decision: "ask", requiresHuman: true, reason: "resolved write target is outside the project", summary: `${args.path} → ${resolved}`,
+                    ...(resolved === settingsFile() || tooBroadToTrust(dir) ? {} : { trustDir: dir }) };
             }
         }
         catch {
@@ -747,3 +772,30 @@ function resolveFileTarget(target) {
     }
     return path.join(fs.realpathSync(current), ...missing);
 }
+// ---- The approval menu ----------------------------------------------------------
+// Both frontends (readline and Ink) offer the same choices and apply the same
+// session grant, so the menu lives next to the rules it widens. Outside auto
+// mode the grant is "don't ask again for this tool"; in auto mode it is "trust
+// this directory", offered only for an outside write. The last option is always
+// "No", and so is -1 (Esc). `granted` is the note to show after a grant.
+export function approvalMenu(auto, toolName, trustDir) {
+    const grant = auto
+        ? (trustDir ? `Yes, and trust ${trustDir}/ for this session` : null)
+        : (toolName ? `Yes, and don't ask again for ${toolName} this session` : "Yes, and don't ask again this session");
+    const options = [auto ? "Yes, once" : "Yes", ...(grant ? [grant] : []), "No — let me tell the agent what to do instead"];
+    const choose = (i) => {
+        if (i < 0 || i >= options.length - 1)
+            return { approved: false };
+        if (i === 0)
+            return { approved: true };
+        if (auto && trustDir) {
+            CONFIG.autoMode.trustedDirs.push(trustDir);
+            return { approved: true, granted: `trusting ${trustDir}/ for this session` };
+        }
+        if (!toolName)
+            return { approved: true };
+        CONFIG.permissions.allow.push(`tool:${toolName}`); // "don't ask again" → session allowlist
+        return { approved: true, granted: `won't ask again for ${toolName} this session` };
+    };
+    return { options, choose };
+}

package/dist/prompt.js

@@ -21,7 +21,7 @@ Behavior rules:
 - You support SKILLS — reusable, named procedures saved as Markdown under .mini-agent/skills/ in the project (or ~/.config/mini-agent/skills/ globally). When a request matches one of the skills listed in the \`skill\` tool, call \`skill\` with its name to load the steps, then carry them out. If there is no \`skill\` tool in this session, none are loaded in this project yet — the capability still exists: the user adds one at .mini-agent/skills/<name>/SKILL.md, runs any with "/skill <name>", and lists them with "/skills". So when asked whether you support skills, the answer is yes — describe this mechanism (and which skills, if any, are currently loaded); never claim your toolset is fixed.
 - Report results accurately. If a test fails, say it failed. Don't claim success when you're not sure. Don't be overly self-doubting either — distinguish "verified working" from "I think it works".
 - Never add comments to code you did not change. Never reformat code you did not change.
-- Keep final answers under 150 words unless the task genuinely requires more.
+- End every turn with a final message the user can take in at a glance. First line: the outcome (done, failed, found X, nothing to report). If that says it all, stop there, e.g. "No alerts — all normal." Otherwise follow it with short sections, each a bold label over bullet points: what you did, what you found (each problem: what, where, impact), what needs the user's decision. One fact per bullet; no filler, no restating the request. Under 150 words unless the task genuinely requires more. Write in the language the user writes in.
 - Between tool calls, write at most one short sentence — usually nothing.
 - A [permission] denial is a hard boundary. Do not attempt workarounds — explain and ask the user.
 - If the task is ambiguous, ask one clarifying question instead of guessing.`;

package/dist/title.js

@@ -41,8 +41,9 @@ export function setTerminalTitle(title) {
 }
 export const refreshTerminalTitle = () => setTerminalTitle(lastTitle);
 // "Which window is this?" — another session asked. Ring the bell and blink the
-// tab title for a few seconds, then put the real title back.
-export function flashTerminalTitle(ms = 6000) {
+// tab title for a few seconds, then put the real title back. A finished cron run
+// uses it too, blinking its own label ("⏰ cron_1 done") instead.
+export function flashTerminalTitle(ms = 6000, label) {
     if (!process.stdout.isTTY)
         return;
     process.stdout.write("\x07");
@@ -59,7 +60,7 @@ export function flashTerminalTitle(ms = 6000) {
             process.stdout.write(terminalTitleSequence(tabTitle(lastTitle)));
             return;
         }
-        process.stdout.write(terminalTitleSequence(on ? `👋 ${name} — HERE 👋` : tabTitle(lastTitle)));
+        process.stdout.write(terminalTitleSequence(on ? label ?? `👋 ${name} — HERE 👋` : tabTitle(lastTitle)));
     }, 500);
     flashing.unref();
 }

package/dist/tools.js

@@ -23,7 +23,8 @@ const TOOL_RESULT_LIMIT = 4000; // cap (chars) for a normal tool result entering
 const READ_LIMIT = 16000; // read_file gets a larger cap of its own
 const SEARCH_MAX_MATCHES = 50; // max matches returned by search
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build"]); // directories search never enters
-const BASH_TIMEOUT_MS = 30_000; // a single command may run this long before we kill it
+const BASH_TIMEOUT_MS = 120_000; // a single command may run this long before we kill it (Claude Code's 2 minutes)
+const BASH_MAX_TIMEOUT_MS = 600_000; // the most a command may ask for; anything longer belongs in the background
 const BASH_OUTPUT_LIMIT = 8_000; // chars of command output kept inline; beyond this we spill to a file
 const SPILL_NOTE_SLACK = 400; // room for the "[...saved to FILE]" note so dispatch's cap never eats it
 // Errors are not exceptions — they are text that tells the model what to do next.
@@ -189,17 +190,27 @@ function spillIfHuge(out, what) {
     const head = out.slice(0, BASH_OUTPUT_LIMIT); // a generous preview
     return `${head}\n\n[...${what} truncated: ${out.length} chars total. Full output saved to ${file} — use read_file to inspect more.]`;
 }
+// The watchdog for one run_bash call: the model may ask for more (or less) than
+// the default, never past the maximum. Anything that isn't a positive number of
+// seconds — missing, "", garbage — gets the default.
+export function bashTimeoutMs(seconds) {
+    const s = Number(seconds);
+    return Number.isFinite(s) && s > 0 ? Math.min(Math.round(s * 1000), BASH_MAX_TIMEOUT_MS) : BASH_TIMEOUT_MS;
+}
 const runBash = {
-    definition: def("run_bash", `Run a bash command on the user's machine (30s timeout) and return its output.
+    definition: def("run_bash", `Run a bash command on the user's machine and return its output. It is killed after 2 minutes unless you pass a longer timeout (up to 600 seconds) — set one when you expect a slow command (a full test suite, a build). Longer, or work you don't need to wait for: run_bash_background.
 Boundaries: only for things that truly need execution — installing dependencies, running tests/scripts, git operations.
 To read files use read_file (not cat), to search use search (not grep/find), to edit files use edit_file (not sed/redirection).
 Dangerous commands require user approval; some are denied outright. A [permission] result is a hard boundary — never try to work around it.
-On error: failures return the error output — analyze it and try a different approach; do not resend the same command unchanged.`, { command: { type: "string", description: "The bash command to run" } }, ["command"]),
+On error: failures return the error output — analyze it and try a different approach; do not resend the same command unchanged.`, {
+        command: { type: "string", description: "The bash command to run" },
+        timeout: { type: "number", description: "Optional: seconds before the command is killed (default 120, max 600)" },
+    }, ["command"]),
     // Async + spawn: the event loop stays responsive while the command runs, so
     // the spinner keeps spinning and Ctrl+C is heard. execSync would freeze
     // everything — the whole process, the UI, the signal handler — until it
     // returned. The AbortSignal lets the loop kill the child on interruption
-    // instead of waiting out the 30s timeout.
+    // instead of waiting out the timeout.
     run: (args, signal) => new Promise((resolve) => {
         const child = spawn(args.command, { shell: true, stdio: ["ignore", "pipe", "pipe"], env: childEnv() }); // shell:true → bash semantics
         let stdout = ""; // captured stdout
@@ -214,10 +225,12 @@ On error: failures return the error output — analyze it and try a different ap
             resolve(text); // hand the result back
         };
         // Hard timeout: SIGKILL the whole process group, never hang the agent.
+        const timeoutMs = bashTimeoutMs(args.timeout);
         const timer = setTimeout(() => {
             child.kill("SIGKILL");
-            done(fail(`Command timed out after ${BASH_TIMEOUT_MS / 1000}s and was killed.${stdout ? `\npartial stdout:\n${stdout.slice(0, 2000)}` : ""}`));
-        }, BASH_TIMEOUT_MS);
+            const hint = timeoutMs < BASH_MAX_TIMEOUT_MS ? ` If it needs longer, rerun with a larger timeout (max ${BASH_MAX_TIMEOUT_MS / 1000}) or use run_bash_background.` : " Use run_bash_background for anything this long.";
+            done(fail(`Command timed out after ${timeoutMs / 1000}s and was killed.${hint}${stdout ? `\npartial stdout:\n${stdout.slice(0, 2000)}` : ""}`));
+        }, timeoutMs);
         // Ctrl+C while a command runs: kill the child immediately.
         const onAbort = () => {
             child.kill("SIGKILL");
@@ -240,17 +253,19 @@ On error: failures return the error output — analyze it and try a different ap
     }),
 };
 // ============ run_bash_background (Day 37) ============
-// run_bash blocks and dies at its 30s watchdog — useless for anything truly
-// slow. This is its asynchronous twin: it spawns the command and returns a task
-// id IMMEDIATELY, so the agent keeps reasoning while the work happens. The loop
-// injects a <task_notification> when the command finishes (background.ts). Use
-// it for installs, builds, full test runs, or servers that never exit — exactly
-// the keywords that signal a slow operation. The command goes through the SAME
-// permission gate as run_bash (see permissions.ts), so the danger rules are
-// identical; only the blocking behavior differs.
+// run_bash blocks, and dies at its watchdog (2 minutes, 10 at most) — useless
+// for anything truly slow. This is its asynchronous twin: it spawns the command
+// and returns a task id IMMEDIATELY, so the agent keeps reasoning while the work
+// happens. The loop injects a <task_notification> when the command finishes
+// (background.ts); if the agent is idle by then, the frontend wakes it with one
+// (loop.ts, takeFinishedWork). Use it for installs, builds, full test runs, or
+// servers that never exit — exactly the keywords that signal a slow operation.
+// The command goes through the SAME permission gate as run_bash (see
+// permissions.ts), so the danger rules are identical; only the blocking
+// behavior differs.
 const runBashBackground = {
     definition: def("run_bash_background", `Run a slow bash command in the BACKGROUND and return immediately with a task id (e.g. bg_1) — do NOT wait for it.
-When to use: anything that would exceed run_bash's 30s limit or block you — installing dependencies (npm/pip install), builds (npm run build, cargo build, make), full test suites (pytest, npm test), deploys, or long-running servers (npm run dev) that never exit.
+When to use: anything that could outlast run_bash's timeout (10 minutes at most) or that you don't need to wait for — installing dependencies (npm/pip install), builds (npm run build, cargo build, make), full test suites (pytest, npm test), deploys, or long-running servers (npm run dev) that never exit.
 What you get back: just the task id. The command keeps running. When it finishes you'll receive a <task_notification> with its status and output tail — react to that. For a server or a job still running, poll it with bash_output.
 Boundaries & permissions are identical to run_bash (dangerous commands are still gated or denied). For quick commands use run_bash instead — waiting on a one-off background job wastes a turn.`, { command: { type: "string", description: "The bash command to run in the background" } }, ["command"]),
     // Fire-and-return: start the process, hand back the id. The output is captured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "type": "module",
   "bin": {
     "mini-agent": "dist/agent.js"