jaitus 0.3.24 → 0.3.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaitus",
-  "version": "0.3.24",
+  "version": "0.3.25",
   "description": "Jaitus — a coding agent in your terminal.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node tests/source-sanity.js && node tests/react-build.js && node tests/stalls.js && node tests/clipboard-write.js && node tests/rewind-images.js && node tests/rules.js && node tests/run.js && node tests/commands.js && node tests/login.js && node tests/session.js && node tests/openUrl.js && node tests/ink-tui.js && node tests/tui-render.js && node tests/mouse-e2e.js && node tests/environment.js && node tests/update.js && node tests/service-notices.js && node tests/continuation.js && node tests/steps.js && node tests/files.js && node tests/processes.js && node tests/security.js && node tests/context-budget.js && node tests/context-trim.js && node tests/compaction.js && node tests/copy-clean.js && node tests/parallel-tools.js && node tests/plan-percent.js && node tests/orb.js && node tests/update-required.js && node tests/update-policy.js && node tests/select-scroll.js && node tests/project-identity.js",
+    "test": "node tests/source-sanity.js && node tests/ask-user.js && node tests/ad-slots.js && node tests/memory.js && node tests/mcp-remote.js && node tests/parallel-subagents.js && node tests/react-build.js && node tests/stalls.js && node tests/clipboard-write.js && node tests/rewind-images.js && node tests/rules.js && node tests/run.js && node tests/commands.js && node tests/login.js && node tests/session.js && node tests/openUrl.js && node tests/ink-tui.js && node tests/tui-render.js && node tests/mouse-e2e.js && node tests/environment.js && node tests/update.js && node tests/service-notices.js && node tests/continuation.js && node tests/steps.js && node tests/files.js && node tests/processes.js && node tests/security.js && node tests/context-budget.js && node tests/context-trim.js && node tests/compaction.js && node tests/copy-clean.js && node tests/parallel-tools.js && node tests/plan-percent.js && node tests/orb.js && node tests/update-required.js && node tests/update-policy.js && node tests/select-scroll.js && node tests/project-identity.js",
     "preview": "node scripts/tui-preview.js",
     "prepublishOnly": "npm test"
   },

package/src/adSlots.js

@@ -0,0 +1,140 @@
+// ─── Sponsored lines: which ad is up, and when it counts as seen ──────────────────
+//
+// The plan pays for itself on Free, Starter and Pro with one text line, always labelled
+// "Sponsored", in the CLI's own chrome — never in the conversation. The server decides
+// whether this person sees ads at all (Max never does); this file only asks, shows what
+// it is given, and reports a view honestly:
+//
+//   • A view is reported only after the line has been on screen for one CONTINUOUS
+//     second (the MRC viewable-impression rule advertisers pay by). Covered by a dialog
+//     or a panel, the clock starts again.
+//   • Each serve is reported at most once, and never retried into a double count (the
+//     server would refuse a second report anyway).
+//   • Nothing here can slow or break the CLI: every call has a short timeout, every
+//     failure is silent, and a placement with nothing to show is not asked again for a
+//     while.
+//
+// Placements: 'thinking' (under the work bar while the model works), 'idle' (above the
+// prompt while waiting for you), 'usage' (inside /usage).
+
+export const VIEWABLE_MS = 1000;
+const TICK_MS = 200;
+const ROTATE_THINKING_MS = 60_000;        // a long turn shows a fresh ad each minute
+const IDLE_REUSE_MS = 45_000;             // a quick back-and-forth keeps the same idle ad
+const EMPTY_BACKOFF_MS = 5 * 60_000;      // nothing to show here: ask again in 5 minutes
+const ERROR_BACKOFF_MS = 10 * 60_000;     // the service failed: leave it alone for 10
+
+/**
+ * source: { next(placement) → Promise<ad|null>, seen(token, shownMs) → Promise }
+ * isVisible(slot): is this slot's line on screen right now (drawn, not covered)?
+ * onChange(): redraw.
+ */
+export function createAdSlots({ source, isVisible, onChange, now = () => Date.now(), timers = { setInterval, clearInterval } }) {
+  let current = null;        // { placement, ad, at, visibleMs, reported }
+  let wanted = null;
+  let lastIdle = null;       // { slot, at } — reused for a quick return to idle
+  let timer = null;
+  let lastTick = 0;
+  let stopped = false;
+  const backoff = new Map();
+  const inFlight = new Set();
+
+  const set = (slot) => { current = slot; onChange?.(); };
+
+  function ensureTimer() {
+    if (timer || stopped) return;
+    lastTick = now();
+    timer = timers.setInterval(tick, TICK_MS);
+    timer?.unref?.();
+  }
+  function stopTimer() { if (timer) { timers.clearInterval(timer); timer = null; } }
+
+  function tick() {
+    const t = now();
+    const elapsed = Math.max(0, t - lastTick);
+    lastTick = t;
+    if (!current) { stopTimer(); return; }
+    if (!current.reported) {
+      if (isVisible(current)) {
+        current.visibleMs += elapsed;
+        if (current.visibleMs >= VIEWABLE_MS) {
+          current.reported = true;
+          const shown = Math.round(current.visibleMs);
+          Promise.resolve().then(() => source.seen(current.ad.token, shown)).catch(() => {});
+        }
+      } else {
+        current.visibleMs = 0;        // continuous, or it does not count
+      }
+    }
+    if (current.placement === 'thinking' && wanted === 'thinking' && t - current.at >= ROTATE_THINKING_MS) {
+      void fetchFor('thinking', { replace: true });
+    }
+  }
+
+  async function fetchFor(placement, { replace = false } = {}) {
+    if (stopped || inFlight.has(placement)) return;
+    if ((backoff.get(placement) || 0) > now()) { if (!replace) set(null); return; }
+    inFlight.add(placement);
+    let ad = null;
+    let failed = false;
+    try { ad = await source.next(placement); } catch { failed = true; }
+    inFlight.delete(placement);
+    if (stopped) return;
+    if (!ad || typeof ad.text !== 'string' || !ad.token) {
+      backoff.set(placement, now() + (failed ? ERROR_BACKOFF_MS : EMPTY_BACKOFF_MS));
+      if (wanted === placement && !replace) set(null);
+      return;
+    }
+    // The person moved on while it was being fetched (the turn ended): not shown.
+    if (wanted !== placement) return;
+    const slot = { placement, ad, at: now(), visibleMs: 0, reported: false };
+    if (placement === 'idle') lastIdle = { slot, at: slot.at };
+    set(slot);
+    ensureTimer();
+  }
+
+  return {
+    /** Which slot should have an ad now ('thinking' | 'idle' | 'usage' | null). */
+    want(placement) {
+      if (stopped) return;
+      wanted = placement || null;
+      if (!wanted) { set(null); return; }
+      if (current?.placement === wanted) return;
+      if (wanted === 'idle' && lastIdle && now() - lastIdle.at < IDLE_REUSE_MS) {
+        // Back to waiting moments after the last wait: the same line, not a new serve.
+        set(lastIdle.slot);
+        ensureTimer();
+        return;
+      }
+      set(null);
+      void fetchFor(wanted);
+    },
+    current: () => current,
+    stop() { stopped = true; stopTimer(); current = null; },
+    _tick: tick,
+  };
+}
+
+/** The one line as it is drawn, fitted to `width` columns: label, text, domain. */
+export function adLineParts(ad, width) {
+  const label = 'Sponsored';
+  const domain = String(ad.domain || '');
+  const room = Math.max(0, width - label.length - domain.length - 8);
+  const text = String(ad.text || '');
+  const shown = room <= 0 ? '' : (text.length <= room ? text : `${text.slice(0, Math.max(0, room - 1))}…`);
+  return { label, text: shown, domain };
+}
+
+/** The ad source on Jaitus's API: short timeouts, and any failure is just "no ad". */
+export function adSourceFor(client, { timeoutMs = 2500 } = {}) {
+  const call = (path, init = {}) => client.api(path, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+  return {
+    async next(placement) {
+      const r = await call(`/ads/cli/next?placement=${encodeURIComponent(placement)}`);
+      return r.ok ? (r.body?.data?.ad || null) : null;
+    },
+    async seen(token, shownMs) {
+      await call('/ads/cli/seen', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token, shownMs }) });
+    },
+  };
+}

package/src/agent/askUser.js

@@ -0,0 +1,161 @@
+// The model asks the person a question and waits for the answer — multiple choice, with
+// a way to answer in their own words. Without it a model that hit a real decision either
+// guessed (and built the wrong thing) or ended its turn with a question in prose, which
+// throws away everything it had in flight.
+//
+// The answer always comes back as text the model can act on: what was picked, what was
+// typed, or that the person closed the question. A run with nobody to ask (a script, -p,
+// a subagent) never pretends to ask.
+
+export const MAX_QUESTIONS = 4;
+export const MAX_OPTIONS = 6;
+export const OTHER_VALUE = '__own_words__';
+const OTHER_LABEL = 'Type my own answer';
+
+/** True when the input already contains an answer the user can always pick. */
+function isOtherLabel(label) {
+  return /^(other|something else|none of (the|these)|custom|type (my|your) own)/i.test(String(label).trim());
+}
+
+function text(value) {
+  return typeof value === 'string' ? value.trim() : (typeof value === 'number' ? String(value) : '');
+}
+
+/**
+ * Normalise what the model sent. Models trained on other agents send `question` alone,
+ * options as plain strings, `choices` for `options`, `multi_select` or `allowMultiple` —
+ * all of which mean the same thing and are taken as such rather than refused.
+ * Returns { questions } or { error }.
+ */
+export function normaliseQuestions(input = {}) {
+  let list = Array.isArray(input.questions) ? input.questions
+    : (input.question || input.options || input.choices) ? [input] : [];
+  if (!list.length) return { error: 'Give questions: [{ question, options: [{ label, description }] }].' };
+  if (list.length > MAX_QUESTIONS) return { error: `Ask at most ${MAX_QUESTIONS} questions at a time.` };
+  const questions = [];
+  for (const [n, raw] of list.entries()) {
+    const q = typeof raw === 'string' ? { question: raw } : (raw || {});
+    const question = text(q.question) || text(q.prompt) || text(q.text);
+    if (!question) return { error: `Question ${n + 1} has no question text.` };
+    const rawOptions = Array.isArray(q.options) ? q.options : Array.isArray(q.choices) ? q.choices : [];
+    const options = [];
+    const seen = new Set();
+    for (const o of rawOptions) {
+      const opt = typeof o === 'string' || typeof o === 'number' ? { label: String(o) } : (o || {});
+      const label = text(opt.label) || text(opt.value) || text(opt.title) || text(opt.name);
+      // "Other" is always offered by the interface; one the model wrote itself would
+      // appear twice and only one of them would let the person type.
+      if (!label || isOtherLabel(label) || seen.has(label.toLowerCase())) continue;
+      seen.add(label.toLowerCase());
+      options.push({ label: label.slice(0, 120), description: text(opt.description).slice(0, 400) });
+    }
+    if (options.length < 2) return { error: `Question ${n + 1} needs at least 2 options (the person can always type their own answer as well).` };
+    if (options.length > MAX_OPTIONS) return { error: `Question ${n + 1} has ${options.length} options; give at most ${MAX_OPTIONS}.` };
+    const header = (text(q.header) || text(q.title)).slice(0, 24);
+    const multi = [q.multiSelect, q.multi_select, q.multiple, q.allowMultiple].some((v) => v === true);
+    questions.push({ question: question.slice(0, 600), header, options, multi });
+  }
+  return { questions };
+}
+
+/** Lines that describe the options when the dialog cannot show a description per row. */
+function descriptionLines(options) {
+  return options.filter((o) => o.description).map((o) => `${o.label} — ${o.description}`);
+}
+
+/**
+ * Ask one question. `tui.richDialog` (the full-screen interface) shows descriptions,
+ * check boxes and a text field itself. Anything else gets the same answers through the
+ * plain numbered dialog every renderer has: one pick at a time for several choices, and
+ * `tui.askText` for words.
+ * Resolves { picked: [labels], text } or null when closed.
+ */
+async function askOne(tui, q, { index, total, signal }) {
+  const title = `${total > 1 ? `Question ${index + 1} of ${total}` : 'Question'}${q.header ? ` · ${q.header}` : ''}`;
+  const choices = [
+    ...q.options.map((o) => ({ label: o.label, value: o.label, description: o.description })),
+    { label: OTHER_LABEL, value: OTHER_VALUE, text: true, description: 'Answer in your own words.' },
+  ];
+
+  if (tui.richDialog) {
+    const answer = await tui.askDialog(q.question, choices, [], { title, multi: q.multi, signal, hideComment: true, kind: 'question' });
+    if (!answer) return null;
+    const values = Array.isArray(answer.values) ? answer.values : [answer.value];
+    return { picked: values.filter((v) => v && v !== OTHER_VALUE), text: text(answer.text) };
+  }
+
+  const preview = descriptionLines(q.options);
+  // A renderer answers a closed dialog with null, or (the classic one) with a value that
+  // is none of the options — 'deny'. Neither may be read as a pick.
+  const known = new Set([...q.options.map((o) => o.label), OTHER_VALUE, '__done__']);
+  const closed = (answer) => !answer || signal?.aborted || !known.has(answer.value);
+  let picked = [];
+  if (q.multi) {
+    const chosen = new Set();
+    for (;;) {
+      const options = [
+        ...q.options.map((o) => ({ label: `[${chosen.has(o.label) ? 'x' : ' '}] ${o.label}`, value: o.label })),
+        { label: OTHER_LABEL, value: OTHER_VALUE },
+        { label: chosen.size ? `Done (${chosen.size} chosen)` : 'Done', value: '__done__' },
+      ];
+      const answer = await tui.askDialog(`${q.question} (pick each that applies, then Done)`, options, preview, { title, signal, hideComment: true });
+      if (closed(answer)) return null;
+      if (answer.value === '__done__') { if (chosen.size) break; continue; }
+      if (answer.value === OTHER_VALUE) {
+        const typed = await askWords(tui, q.question, { title, signal });
+        if (typed === null) continue;
+        return { picked: [...chosen], text: typed };
+      }
+      if (chosen.has(answer.value)) chosen.delete(answer.value); else chosen.add(answer.value);
+    }
+    picked = [...chosen];
+    return { picked, text: '' };
+  }
+  for (;;) {
+    const answer = await tui.askDialog(q.question, choices.map(({ label, value }) => ({ label, value })), preview, { title, signal, hideComment: true });
+    if (closed(answer)) return null;
+    if (answer.value !== OTHER_VALUE) return { picked: [answer.value], text: '' };
+    const typed = await askWords(tui, q.question, { title, signal });
+    if (typed !== null) return { picked: [], text: typed };
+  }
+}
+
+/** Free text from a renderer without a text field in its dialog. null = went back. */
+async function askWords(tui, question, { title, signal }) {
+  if (!tui.askText) return null;
+  const typed = text(await tui.askText(`${question} — type your answer`, { title, signal }));
+  return typed || null;
+}
+
+function quote(s) { return `"${String(s).replace(/"/g, '\\"')}"`; }
+
+/** The tool result: one line per question, in the person's own terms. */
+export function formatAnswers(questions, answers) {
+  const lines = ['The user answered:'];
+  questions.forEach((q, i) => {
+    const a = answers[i];
+    const parts = [];
+    if (a.picked.length) parts.push(a.picked.join(', '));
+    if (a.text) parts.push(`in their own words: ${quote(a.text)}`);
+    lines.push(`${i + 1}. ${quote(q.question)} → ${parts.join('; ')}`);
+  });
+  lines.push('Act on these answers. Their own words take precedence over any option you offered.');
+  return lines.join('\n');
+}
+
+export const CLOSED_NOTE = 'The user closed the question without answering. Do not guess and do not ask it again: stop here, say briefly what you need decided, and wait for their next message.';
+export const NOBODY_NOTE = 'Nobody can answer questions in this run (it is not interactive). Choose the most sensible option yourself, state it as an assumption in your reply, and continue.';
+
+/** Run the whole exchange. Returns the text for the tool result. */
+export async function askUser(input, { tui, signal, canAsk } = {}) {
+  const { questions, error } = normaliseQuestions(input);
+  if (error) return { error };
+  if (!canAsk || !tui?.askDialog) return { text: NOBODY_NOTE };
+  const answers = [];
+  for (const [index, q] of questions.entries()) {
+    const answer = await askOne(tui, q, { index, total: questions.length, signal });
+    if (!answer || (!answer.picked.length && !answer.text)) return { text: CLOSED_NOTE, closed: true };
+    answers.push(answer);
+  }
+  return { text: formatAnswers(questions, answers), answers };
+}

package/src/agent/loop.js

@@ -27,7 +27,7 @@ import { PermissionDenied } from './permissions.js';
 import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';
-import { loadContext, loadIgnore, CONTEXT_FILE } from '../project.js';
+import { loadContext, loadUserContext, loadIgnore, CONTEXT_FILE } from '../project.js';
 import { c, out, write, spinner, glyph } from '../ui.js';
 import { discoverMcpTools } from '../mcp.js';
 import { unifiedDiff } from '../diff.js';
@@ -97,7 +97,7 @@ const TOOL_MARKS = {
   run_command: ['$', '$'], read_file: ['→', '>'], read_image: ['→', '>'],
   list_files: ['→', '>'], write_file: ['←', '<'], edit_file: ['←', '<'],
   search: ['✱', '*'], web_fetch: ['%', '%'], web_search: ['◈', 'o'],
-  background_run: ['◉', 'o'], todo_write: ['⚙', '*'],
+  background_run: ['◉', 'o'], todo_write: ['⚙', '*'], ask_user: ['?', '?'],
 };
 const toolMark = (name) => {
   const [uni, ascii] = TOOL_MARKS[name] || ['⚙', '*'];
@@ -127,7 +127,9 @@ How to work:
 How to talk:
 - Be concise. This is a terminal, not a document.
 - Say what you did and what happened, not what you are about to do.
-- If something is blocked or you are missing information, say so plainly and ask.
+- If something is blocked or you are missing information, say so plainly and ask. When a
+  decision is genuinely the user's (a preference, an unclear requirement, a real trade-off),
+  ask it with ask_user rather than guessing; decide everything else yourself.
 - No preamble, no restating the question back.`;
 
 /**
@@ -193,9 +195,20 @@ ${listing || '(empty)'}
 
 export function systemPrompt(cwd) {
   const project = cwd ? loadContext(cwd) : null;
-  const base = `${SYSTEM_PROMPT}${environmentBlock(cwd)}`;
-  if (!project) return base;
-  return `${base}
+  const personal = loadUserContext();
+  let out = `${SYSTEM_PROMPT}${environmentBlock(cwd)}`;
+  if (personal) {
+    out += `
+
+The user keeps personal notes for you that apply in every project: how they like to work.
+Follow them unless this project's own notes say otherwise for this codebase.
+
+<user-notes>
+${personal}
+</user-notes>`;
+  }
+  if (project) {
+    out += `
 
 The project you are working in ships a ${CONTEXT_FILE} with notes for you. Follow it where
 it applies, and prefer what it says over your own assumptions about this codebase.
@@ -203,6 +216,8 @@ it applies, and prefer what it says over your own assumptions about this codebas
 <${CONTEXT_FILE}>
 ${project}
 </${CONTEXT_FILE}>`;
+  }
+  return out;
 }
 
 /**
@@ -315,7 +330,10 @@ export function clearOldToolResults(messages, { at = TRIM_AT, keep, atLeast = TR
 }
 
 // Tools that change nothing and ask nothing: several in one batch run at the same time.
-const PARALLEL_SAFE = new Set(['read_file', 'glob', 'list_files', 'search', 'web_search', 'web_fetch', 'background_list', 'background_read', 'load_skill']);
+// `task` (a read-only subagent) is here too: several investigations in one turn run side
+// by side, two at a time (SUBAGENTS_AT_ONCE) so they fit any plan's concurrent requests.
+const PARALLEL_SAFE = new Set(['read_file', 'glob', 'list_files', 'search', 'web_search', 'web_fetch', 'background_list', 'background_read', 'load_skill', 'task']);
+export const SUBAGENTS_AT_ONCE = 2;
 
 export const IMAGE_BUDGET = 6_000_000;
 export function withinImageBudget(messages, budget = IMAGE_BUDGET) {
@@ -528,8 +546,11 @@ export async function runAgent({
   // subagents is an unbounded fan-out on a metered gateway, and the depth that would
   // actually help — one — is the depth that is safe.
   const subagent = subagents ? makeSubagentTool({ client, model, cwd, signal, tui, permissions }) : null;
+  // ask_user is offered only when someone is there to answer: a model shown a question
+  // tool in a script or a subagent asks, gets "nobody can answer" and has wasted a turn.
+  const canAsk = !!tui?.askDialog && permissions?.canAsk !== false;
   const availableTools = [
-    ...toolSchemas(),
+    ...toolSchemas().filter((t) => canAsk || t.name !== 'ask_user'),
     ...(subagent ? [{ name: subagent.name, description: subagent.description, input_schema: subagent.input_schema }] : []),
     ...mcp.map((tool) => ({ name: tool.name, description: tool.description, input_schema: tool.input_schema })),
   ];
@@ -828,7 +849,9 @@ export async function runAgent({
       // silent when animations are off — progress you can watch, not noise).
       let elapsedTimer = null;
       const stopElapsed = () => { if (elapsedTimer) { clearInterval(elapsedTimer); elapsedTimer = null; } };
-      if (tui && tui.animationsOn?.()) {
+      if (tui && call.name === 'ask_user') {
+        tui.setStatus(`${c.brand(glyph('•', '*'))} Waiting for your answer`);
+      } else if (tui && tui.animationsOn?.()) {
         const toolStatus = () => `${c.brand(glyph('•', '*'))} ${call.name}: ${c.dim(String(label).slice(0, 60))} ${c.dim(`· ${((Date.now() - toolStarted) / 1000).toFixed(0)}s`)}`;
         tui.setStatus(toolStatus());
         elapsedTimer = setInterval(() => tui.setStatus(toolStatus()), 1000);
@@ -846,7 +869,7 @@ export async function runAgent({
         } else if (journal && call.name === 'run_command') {
           journal.snapshotTracked(cwd);
         }
-        const output = await (early.get(call.id) ?? tool.run(call.input, { cwd, signal }));
+        const output = await (early.get(call.id) ?? tool.run(call.input, { cwd, signal, tui, canAsk }));
         spin2.stop(); stopElapsed();
         const took = ((Date.now() - toolStarted) / 1000).toFixed(1);
         // opencode tool icons: $ shell, ← edits, → reads, ✱ search,
@@ -950,14 +973,22 @@ export async function runAgent({
  * subagent the user never sees must not be able to change the disk.
  */
 function makeSubagentTool({ client, model, cwd, signal, tui, permissions = null }) {
-  return {
+  // At most SUBAGENTS_AT_ONCE run together; the rest wait their turn. Every plan allows
+  // at least two requests at once, and the main agent is idle while its tools run — so
+  // side-by-side subagents never trip the plan's limit and fail on a retry budget.
+  let running = 0;
+  const waiting = [];
+  const enter = () => (running < SUBAGENTS_AT_ONCE ? (running += 1, Promise.resolve()) : new Promise((r) => waiting.push(r)));
+  const leave = () => { const next = waiting.shift(); if (next) next(); else running -= 1; };
+  const tool = {
     name: 'task',
     needsPermission: false,
     description: 'Delegate a read-only investigation to a separate agent with its own context window. '
       + 'Use it when answering needs a lot of searching and reading whose intermediate output you do not need to keep — '
       + '"find every caller of X", "work out how Y is wired", "check whether Z is covered by tests". '
       + 'The subagent can read, list, search and fetch, but cannot write files or run commands. '
-      + 'Give it a self-contained brief: it cannot see this conversation. It returns its findings as text.',
+      + 'Give it a self-contained brief: it cannot see this conversation. It returns its findings as text. '
+      + 'Several task calls in the same turn run at the same time, so split independent investigations into separate calls.',
     input_schema: {
       type: 'object',
       properties: {
@@ -967,7 +998,11 @@ function makeSubagentTool({ client, model, cwd, signal, tui, permissions = null
       required: ['description', 'prompt'],
     },
     summarise: (input) => String(input.description || 'subagent'),
-    async run(input, { cwd: runCwd }) {
+    async run(input, { cwd: runCwd } = {}) {
+      await enter();
+      try { return await tool.investigate(input, runCwd); } finally { leave(); }
+    },
+    async investigate(input, runCwd) {
       const { createPermissions } = await import('./permissions.js');
       const messages = [{ role: 'user', content: String(input.prompt || '') }];
       let answer = '';
@@ -994,6 +1029,7 @@ function makeSubagentTool({ client, model, cwd, signal, tui, permissions = null
       return `${trimmed}\n\n[subagent: ${result.tools} tool calls, ${result.input + result.output} tokens]`;
     },
   };
+  return tool;
 }
 
 /**

package/src/agent/permissions.js

@@ -46,6 +46,8 @@ export function createPermissions({
     get rules() { return { allow: [...savedAllow], deny: [...savedDeny], session: [...sessionAllow] }; },
     /** Saved rules that take a whole tool out of the mode's hands (see wideAllows). */
     get wide() { return wideAllows(savedAllow); },
+    /** Whether anyone is there to answer a question (false for -p, scripts and subagents). */
+    get canAsk() { return interactive && !!process.stdin.isTTY; },
 
     /** Add a rule. `persist` writes it to settings via onRulesChange. */
     addRule(rule, { persist = false, kind = 'allow' } = {}) {

package/src/agent/tools.js

@@ -20,6 +20,7 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { loadIgnore, IGNORE_FILE } from '../project.js';
 import { searchWeb, formatResults } from './websearch.js';
+import { askUser } from './askUser.js';
 
 const MAX_OUTPUT = 60_000;      // characters returned to the model per tool call
 const MAX_READ_LINES = 2_000;
@@ -762,6 +763,57 @@ export const TOOLS = [
     },
   },
 
+  {
+    name: 'ask_user',
+    description:
+      'Ask the user one to four multiple-choice questions and wait for the answers. Use it when you are blocked on a decision that is genuinely theirs to make: a preference, an ambiguous requirement, a choice between approaches with real trade-offs. Do not use it for things you can find out from the code or by running something, and never to ask permission to act (actions that need approval are confirmed separately). Give 2 to 4 short, distinct options per question, each with a one-line description of what it means or costs. If you recommend one, put it first and end its label with "(Recommended)". The user can always type their own answer instead, so never add an "Other" option. Set multiSelect when several options can apply together.',
+    needsPermission: false,
+    input_schema: {
+      type: 'object',
+      properties: {
+        questions: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 4,
+          description: 'The questions, asked one after another.',
+          items: {
+            type: 'object',
+            properties: {
+              question: { type: 'string', description: 'The full question, ending with a question mark.' },
+              header: { type: 'string', description: 'A label of at most 12 characters shown above the question, e.g. "Database".' },
+              options: {
+                type: 'array',
+                minItems: 2,
+                maxItems: 4,
+                items: {
+                  type: 'object',
+                  properties: {
+                    label: { type: 'string', description: 'The choice, in 1 to 5 words.' },
+                    description: { type: 'string', description: 'What choosing it means, or its trade-off.' },
+                  },
+                  required: ['label'],
+                },
+              },
+              multiSelect: { type: 'boolean', description: 'true when several options may be chosen together.' },
+            },
+            required: ['question', 'options'],
+          },
+        },
+      },
+      required: ['questions'],
+    },
+    summarise: (i) => {
+      const first = Array.isArray(i.questions) ? i.questions[0] : i;
+      const q = String(first?.question || first?.prompt || 'question').replace(/\s+/g, ' ');
+      return q.length > 70 ? `${q.slice(0, 69)}…` : q;
+    },
+    async run(input, { tui, signal, canAsk } = {}) {
+      const answer = await askUser(input, { tui, signal, canAsk });
+      if (answer.error) throw new ToolError(answer.error);
+      return answer.text;
+    },
+  },
+
   {
     name: 'read_image',
     description: