agent-from-zero 0.36.0 → 0.39.0

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,20 +772,27 @@ 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
         if (!ok && !opts.quiet)
             sink(opts).note(mark.declined); // make the refusal visible
-        if (!ok)
+        if (!ok) {
+            // Say what actually happened. An unattended worker was never declined by
+            // anyone — saying so teaches the model to rephrase and retry against a
+            // refusal that never existed.
+            if (opts.canPrompt === false)
+                return `[permission] Nobody is reachable to approve this here${reviewReason ? `: ${reviewReason}` : "."} Not executed. Report it in your result and continue with what the rules allow; do not retry the same effect through another tool, wrapper or worker.`;
             return `[permission] Action not approved${reviewReason ? `: ${reviewReason}` : ". The user declined this action"}. Ask the user how to proceed, or choose a safer alternative.`;
+        }
     }
     if (opts.reviewBudget?.exhausted)
         return "[permission] Review limit reached; not executed. Wait for human direction.";
@@ -1141,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
@@ -1377,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();