@semalt-ai/code 1.19.0 → 1.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semalt-ai/code",
-  "version": "1.19.0",
+  "version": "1.20.1",
   "description": "Self-hosted AI Coding Assistant CLI",
   "main": "./lib/sdk.js",
   "//exports": "Two-tier embedding surface (Task 5.2): '.' is the STABLE createAgent facade; './internals' is the UNSTABLE building blocks (no semver guarantee). The boundary is enforced here, not just in docs. Works for both require() and import.",

package/test/anim-driver.test.js

@@ -0,0 +1,153 @@
+'use strict';
+
+// Single animation driver (Output Refactor — Phase 3).
+//
+// THE CHANGE: the status bar used to own TWO independent setIntervals — a 1 Hz
+// clock tick and a 100 ms spinner glyph cycle — that each repainted the whole
+// live region without coordinating. Phase 3 replaces both with ONE driver
+// (lib/ui/anim.js). The clock and spinner are now subscribers: one timer, one
+// frame counter, and at most ONE coordinated repaint per tick.
+//
+// These tests drive the single timer via node:test mock timers and assert that
+// (a) only one interval is ever created by a constructed status bar, (b)
+// advancing it updates BOTH the clock field and the spinner glyph, and (c) a
+// tick that fires more than one subscriber still produces exactly one repaint.
+
+const { test, mock } = require('node:test');
+const assert = require('node:assert');
+
+const { AnimDriver, BASE_INTERVAL_MS, TICKS_PER_SECOND } = require('../lib/ui/anim');
+const { FullStatusBar } = require('../lib/ui/status-bar');
+
+const layout = { cols: 200 };
+
+// ---------------------------------------------------------------------------
+// Exactly one interval is created — the clock and spinner share it.
+// ---------------------------------------------------------------------------
+
+test('a constructed status bar creates exactly one setInterval (one driver, not two)', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let intervalsCreated = 0;
+    const realSetInterval = global.setInterval;
+    global.setInterval = (...args) => { intervalsCreated++; return realSetInterval(...args); };
+    let bar;
+    try {
+      bar = new FullStatusBar(layout, () => {});
+      // Entering an animating state must NOT create a second timer — the
+      // spinner is a subscriber to the one driver, not its own interval.
+      bar.update('tool', 'running');
+    } finally {
+      global.setInterval = realSetInterval;
+    }
+    assert.strictEqual(intervalsCreated, 1, 'only one interval for clock + spinner');
+    bar.destroy();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Advancing the one driver updates BOTH the clock and the spinner glyph.
+// ---------------------------------------------------------------------------
+
+test('advancing the single driver updates both the clock and the spinner', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let redraws = 0;
+    const bar = new FullStatusBar(layout, () => { redraws++; });
+
+    // Animating state → the spinner glyph cycles. Capture the rendered glyph
+    // across two base-interval ticks; it must change.
+    bar.update('thinking', 'Thinking');
+    const glyphAt = () => {
+      const line = bar.renderLine();
+      // First non-space visible char after stripping ANSI is the spinner glyph.
+      const stripped = line.replace(/\x1b\[[0-9;]*m/g, '');
+      return stripped.trimStart()[0];
+    };
+    const g0 = glyphAt();
+    mock.timers.tick(BASE_INTERVAL_MS);
+    const g1 = glyphAt();
+    assert.notStrictEqual(g0, g1, 'spinner glyph advances on a driver tick');
+
+    // And the clock still ticks once per second off the SAME driver. Over a
+    // full second the driver fires repaints (the clock subscriber gates on
+    // frame % TICKS_PER_SECOND); assert at least the spinner cadence redraws.
+    redraws = 0;
+    mock.timers.tick(1000);
+    assert.ok(redraws >= TICKS_PER_SECOND - 1, 'driver repaints at the spinner cadence while animating');
+
+    bar.destroy();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// One coordinated repaint per tick — even when multiple subscribers fire.
+// ---------------------------------------------------------------------------
+
+test('a tick that fires multiple subscribers still yields exactly one repaint', () => {
+  // Pure driver-level check: two subscribers both request a repaint on the
+  // same frame; the driver coalesces them into a single _repaint call.
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let repaints = 0;
+    const d = new AnimDriver();
+    d.onRepaint(() => { repaints++; });
+    d.subscribe(() => true);  // always wants a repaint
+    d.subscribe(() => true);  // also always wants a repaint
+    d.start();
+    mock.timers.tick(BASE_INTERVAL_MS);
+    assert.strictEqual(repaints, 1, 'two truthy subscribers → one coordinated repaint');
+    mock.timers.tick(BASE_INTERVAL_MS);
+    assert.strictEqual(repaints, 2, 'one repaint per subsequent tick too');
+    d.stop();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// A tick where no subscriber wants a repaint produces none (idle clock gap).
+// ---------------------------------------------------------------------------
+
+test('a tick with no truthy subscriber produces no repaint', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let repaints = 0;
+    const d = new AnimDriver();
+    d.onRepaint(() => { repaints++; });
+    d.subscribe(() => false);
+    d.start();
+    mock.timers.tick(BASE_INTERVAL_MS * 5);
+    assert.strictEqual(repaints, 0, 'no repaint when nothing requests one');
+    d.stop();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// start()/stop() are idempotent — no stacked timers (the 5404bd0 lesson).
+// ---------------------------------------------------------------------------
+
+test('AnimDriver start()/stop() are idempotent and never stack timers', () => {
+  mock.timers.enable({ apis: ['setInterval'] });
+  try {
+    let ticks = 0;
+    const d = new AnimDriver();
+    d.subscribe(() => { ticks++; return false; });
+    d.start(); d.start(); d.start();  // three starts → one timer
+    mock.timers.tick(BASE_INTERVAL_MS);
+    assert.strictEqual(ticks, 1, 'one tick per interval despite repeated start()');
+    d.stop(); d.stop();               // two stops → no error, fully stopped
+    ticks = 0;
+    mock.timers.tick(BASE_INTERVAL_MS * 5);
+    assert.strictEqual(ticks, 0, 'no ticks after stop()');
+    assert.strictEqual(d.isRunning(), false, 'isRunning() reflects stopped state');
+  } finally {
+    mock.timers.reset();
+  }
+});

package/test/ask-user-display.test.js

@@ -0,0 +1,226 @@
+'use strict';
+
+// ask_user UX improvements (display-only):
+//   1. The full QUESTION renders as wrapped, clamped header rows above the menu.
+//   2. The prompt header shows ONLY prose; options live ONLY in the menu (no dup).
+//   3. The chosen ANSWER is surfaced as a meta segment on the result line and
+//      survives serialize→replay.
+//
+// All three are DISPLAY-ONLY: the model-facing tool result still carries the
+// FULL original question + answer. These tests lock that split in place and
+// prove interactiveSelect (model/rewind/permission pickers) is untouched.
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ui = require('../lib/ui');
+const { createApiClient } = require('../lib/api');
+const { createToolExecutor, extractToolCalls, parseAskMenu } = require('../lib/tools');
+const { createPermissionManager } = require('../lib/permissions');
+const { createAgentRunner } = require('../lib/agent');
+const { wrapPromptLines } = require('../lib/ui/format');
+const { stripAnsi } = require('../lib/ui/utils');
+const { buildToolOperation, serializeOperation, descriptorFromStored } = require('../lib/ui/tool-operation');
+const { renderOperation } = require('../lib/ui/render-operation');
+const { interactiveSelect } = require('../lib/ui/select');
+const { startMockLLM } = require('./harness/mock-llm');
+
+let prevKey;
+let CWD;
+let PREV_CWD;
+before(() => {
+  prevKey = process.env.SEMALT_API_KEY; process.env.SEMALT_API_KEY = 'test-key';
+  PREV_CWD = process.cwd();
+  CWD = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-askdisp-')));
+  process.chdir(CWD);
+});
+after(() => {
+  process.chdir(PREV_CWD);
+  if (prevKey === undefined) delete process.env.SEMALT_API_KEY; else process.env.SEMALT_API_KEY = prevKey;
+});
+
+// Runner whose interactive menu is spied: `selectCalls` records the FULL menu
+// object handed to captureSelect ({ prompt, options }) so we can assert the
+// display-only split. Returns selectPick (or options[0] in non-TTY auto-answer).
+function buildRunner(base, { selectPick = null } = {}) {
+  const config = {
+    api_base: base, api_key: 'test-key', default_model: 'test-model',
+    temperature: 0.5, request_timeout_ms: 5000, stream: true, models: [],
+  };
+  const selectCalls = [];
+  const api = createApiClient({ getConfig: () => config, saveConfig: () => {}, ui });
+  const pm = createPermissionManager(ui, { approver: () => true });
+  pm.setUICallbacks({
+    onAddMessage: () => {}, onShowModal: () => {}, onCloseModal: () => {}, onCaptureNavigation: () => () => {},
+    captureSelect: (menu) => { selectCalls.push(menu); return selectPick != null ? selectPick : (menu.options && menu.options[0]); },
+  });
+  const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(pm, ui, () => config);
+  const runner = createAgentRunner({
+    chatStream: api.chatStream, extractToolCalls, agentExecShell, agentExecFile,
+    describePermission, permissionManager: pm, ui, getConfig: () => config,
+  });
+  return { runner, selectCalls };
+}
+
+function allToolText(messages) {
+  return messages
+    .filter((m) => m.role === 'tool' || (m.role === 'user' && /Tool execution results/.test(m.content || '')))
+    .map((m) => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content)))
+    .join('\n');
+}
+
+// ── (a) parse helper split: prose → prompt, numbered → options, no duplication ──
+
+test('(a) parseAskMenu splits prose prompt from numbered options — no duplication', () => {
+  const r = parseAskMenu('Which fruit do you prefer?\nPick one:\n1. Apples\n2) Bananas');
+  assert.deepStrictEqual(r.options, ['Apples', 'Bananas'], 'both numbered options parsed (1. and 2) forms)');
+  assert.strictEqual(r.prompt, 'Which fruit do you prefer?\nPick one:', 'prompt is the prose only');
+  assert.ok(!/Apples|Bananas/.test(r.prompt), 'option labels never appear in the prompt header');
+});
+
+test('(a) executor menu gets options only; header gets prompt only (display-only split)', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('ask_user', { question: 'Which fruit?\nChoose:\n1. Apples\n2. Bananas' });
+  mock.replyWith('done');
+  try {
+    const { runner, selectCalls } = buildRunner(mock.base, { selectPick: 'Bananas' });
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+    assert.strictEqual(selectCalls.length, 1);
+    assert.deepStrictEqual(selectCalls[0].options, ['Apples', 'Bananas'], 'menu gets the options');
+    assert.strictEqual(selectCalls[0].prompt, 'Which fruit?\nChoose:', 'header gets the prose only');
+    assert.ok(!/Apples|Bananas/.test(selectCalls[0].prompt), 'no option duplication in the header');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ── (b) model-facing result still carries the FULL original question + answer ──
+
+test('(b) model-facing result keeps the FULL original question (prose + options) + answer', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('ask_user', { question: 'Which fruit?\n1. Apples\n2. Bananas' });
+  mock.replyWith('done');
+  try {
+    const { runner } = buildRunner(mock.base, { selectPick: 'Bananas' });
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+    const text = allToolText(messages);
+    assert.ok(/User answered/.test(text), 'model sees the answered string');
+    assert.ok(text.includes('Which fruit?'), 'full prose present for the model');
+    assert.ok(text.includes('1. Apples') && text.includes('2. Bananas'), 'full numbered options present for the model (NOT stripped)');
+    assert.ok(/:\s*Bananas/.test(text), 'the chosen answer is present');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ── (c) long question → header wraps + clamps; never overflows the modal band ──
+
+test('(c) wrapPromptLines clamps a long question to the cap with a "… N more lines" tail', () => {
+  const long = Array.from({ length: 40 }, (_, i) => `prompt line number ${i}`).join('\n');
+  const out = wrapPromptLines(long, { cols: 80, maxLines: 12 });
+  assert.strictEqual(out.length, 13, '12 visible lines + 1 tail row');
+  assert.match(out[12], /… 28 more lines/, 'tail counts exactly the hidden lines');
+});
+
+test('(c) wrapPromptLines word-wraps to the column budget and hard-breaks long tokens', () => {
+  const wrapped = wrapPromptLines('alpha beta gamma delta', { cols: 12, maxLines: 12 });
+  assert.ok(wrapped.every((l) => l.length <= 12), 'every wrapped line fits the column budget');
+  assert.ok(wrapped.length > 1, 'wrapped across multiple rows');
+  const huge = wrapPromptLines('x'.repeat(30), { cols: 10, maxLines: 12 });
+  assert.ok(huge.every((l) => l.length <= 10), 'an over-long single token is hard-broken to the budget');
+  assert.deepStrictEqual(wrapPromptLines('   \n  ', { cols: 80 }), [], 'whitespace-only prompt yields no header rows');
+});
+
+// ── (d) the chosen answer rides the result line as meta, and survives replay ──
+
+test('(d) the result line shows the chosen answer as a meta segment, and it survives replay', () => {
+  const spec = { tag: 'ask_user', arg: 'Pick', attrs: { question: 'Pick' }, status: 'ok', durationMs: 0, meta: { answer: 'Bananas' }, noDuration: true };
+  const op = buildToolOperation(spec);
+  const line = stripAnsi(renderOperation(op, { mode: 'ansi', phase: 'result' }));
+  assert.ok(line.includes('→ Bananas'), 'fresh result line carries "→ <answer>"');
+
+  // Replay: serialize → descriptorFromStored → render again (rides _display).
+  const stored = serializeOperation(op);
+  assert.deepStrictEqual(stored.meta, { answer: 'Bananas' }, 'meta is persisted in the serialized core');
+  const rebuilt = descriptorFromStored(stored);
+  const line2 = stripAnsi(renderOperation(rebuilt, { mode: 'ansi', phase: 'result' }));
+  assert.ok(line2.includes('→ Bananas'), 'answer renders identically on reload');
+});
+
+test('(d) a long chosen answer is truncated so the result line stays one row', () => {
+  const op = buildToolOperation({ tag: 'ask_user', arg: 'q', attrs: { question: 'q' }, status: 'ok', durationMs: 0, meta: { answer: 'y'.repeat(100) }, noDuration: true });
+  const line = stripAnsi(renderOperation(op, { mode: 'ansi', phase: 'result' }));
+  assert.ok(line.includes('…'), 'long answer is truncated with an ellipsis');
+  // The answer segment itself stays well under a terminal row.
+  const seg = line.split(' · ').find((s) => s.includes('→'));
+  assert.ok(seg && stripAnsi(seg).length <= 45, 'answer meta segment is bounded');
+});
+
+// ── (e) edge: no prose before the numbers → fall back to the raw question ──
+
+test('(e) question with no prose → empty prompt → header falls back to the raw question', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<ask_user question="1. Red\n2. Blue"/>');
+  mock.replyWith('done');
+  try {
+    const { runner, selectCalls } = buildRunner(mock.base, { selectPick: 'Blue' });
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+    assert.strictEqual(selectCalls.length, 1);
+    assert.deepStrictEqual(selectCalls[0].options, ['Red', 'Blue']);
+    assert.strictEqual(selectCalls[0].prompt, '1. Red\n2. Blue', 'no prose → raw question used as header (never empty)');
+    // parseAskMenu itself reports the empty prompt; the fallback is the executor's.
+    assert.strictEqual(parseAskMenu('1. Red\n2. Blue').prompt, '', 'parse helper reports empty prose');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ── (f) headless auto-answer path still works (no crash from the split) ──
+
+test('(f) headless auto-answer (non-TTY): the split helper does not crash; first option answered', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('ask_user', { question: 'Prose?\n1. First\n2. Second' });
+  mock.replyWith('done');
+  try {
+    const { runner } = buildRunner(mock.base, { selectPick: null }); // no pick → auto options[0]
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+    assert.ok(/:\s*First/.test(allToolText(messages)), 'auto-answer resolved to the first option without crashing');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ── (g) interactiveSelect (model/rewind/permission pickers) is UNCHANGED ──
+
+test('(g) interactiveSelect still returns the selected index via captureNavigation (signature intact)', async () => {
+  // Suppress the modal's escape writes so TAP output stays clean; the contract
+  // under test is the index-returning navigation, not the rendering.
+  const origWrite = process.stdout.write;
+  process.stdout.write = () => true;
+  try {
+    let handler;
+    const p = interactiveSelect(
+      ['A', 'B', 'C'],
+      (item, sel) => (sel ? '> ' : '  ') + item,
+      { initialIndex: 0, captureNavigation: (h) => { handler = h; return () => {}; } },
+    );
+    handler('next'); handler('next'); handler('select');
+    const idx = await p;
+    assert.strictEqual(idx, 2, 'navigation + select returns the selected index — behavior unchanged');
+
+    let h2;
+    const p2 = interactiveSelect(['A', 'B'], (i) => i, { captureNavigation: (h) => { h2 = h; return () => {}; } });
+    h2('cancel');
+    assert.strictEqual(await p2, null, 'cancel still returns null');
+  } finally {
+    await new Promise((r) => setImmediate(r));
+    process.stdout.write = origWrite;
+  }
+});

package/test/ask-user-gate.test.js

@@ -0,0 +1,231 @@
+'use strict';
+
+// ask_user gate + menu tests.
+//
+// Covers two coupled changes:
+//   1. The model is told (in prompts.js) that a numbered list in the question
+//      renders an interactive menu. (Wording is asserted at the bottom.)
+//   2. ask_user carries a NULL permission descriptor, so:
+//        - it never fires the redundant "may I ask you?" approval gate;
+//        - it is available during plan mode (read-only-style, not withheld);
+//        - in non-TTY it reaches its executor and auto-answers (not refused).
+//
+// Isolation is proven by running a real effectful tool (exec) through the SAME
+// runner: its gate STILL fires. The gate is observed via a programmatic
+// `approver` (records every gate consultation) and the menu via a spied
+// `captureSelect` (records every interactive select).
+
+const { test, before, after } = require('node:test');
+const assert = require('node:assert');
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ui = require('../lib/ui');
+const { createApiClient } = require('../lib/api');
+const { createToolExecutor, extractToolCalls } = require('../lib/tools');
+const { createPermissionManager } = require('../lib/permissions');
+const { createAgentRunner } = require('../lib/agent');
+const { startMockLLM } = require('./harness/mock-llm');
+
+let prevKey;
+let CWD;
+let PREV_CWD;
+before(() => {
+  prevKey = process.env.SEMALT_API_KEY; process.env.SEMALT_API_KEY = 'test-key';
+  PREV_CWD = process.cwd();
+  CWD = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-askuser-')));
+  process.chdir(CWD);
+});
+after(() => {
+  process.chdir(PREV_CWD);
+  if (prevKey === undefined) delete process.env.SEMALT_API_KEY; else process.env.SEMALT_API_KEY = prevKey;
+});
+
+// Build a runner whose permission manager is observable. `approver` records
+// every gate consultation; `captureSelect` records every menu render and
+// returns the configured pick. When `approver` is null, NO programmatic
+// approver is wired (so a gate that fires in non-TTY refuses — exactly headless).
+function buildRunner(base, { approverFn = null, selectPick = null } = {}) {
+  const config = {
+    api_base: base, api_key: 'test-key', default_model: 'test-model',
+    temperature: 0.5, request_timeout_ms: 5000, stream: true, models: [],
+  };
+  const gateCalls = [];
+  const selectCalls = [];
+  const api = createApiClient({ getConfig: () => config, saveConfig: () => {}, ui });
+  const approver = approverFn
+    ? (info) => { gateCalls.push(info); return approverFn(info); }
+    : null;
+  const pm = createPermissionManager(ui, { approver });
+  pm.setUICallbacks({
+    onAddMessage: () => {}, onShowModal: () => {}, onCloseModal: () => {}, onCaptureNavigation: () => () => {},
+    captureSelect: (menu) => { selectCalls.push(menu); return selectPick != null ? selectPick : (menu.options && menu.options[0]); },
+  });
+  const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(pm, ui, () => config);
+  const runner = createAgentRunner({
+    chatStream: api.chatStream, extractToolCalls, agentExecShell, agentExecFile,
+    describePermission, permissionManager: pm, ui, getConfig: () => config,
+  });
+  return { runner, gateCalls, selectCalls };
+}
+
+// The two rails feed tool output back differently — the XML rail bundles it in a
+// user-role "Tool execution results" block, the native rail emits role:'tool'
+// messages. Scan every message's content so an assertion works on both rails.
+function allToolText(messages) {
+  return messages
+    .filter((m) => m.role === 'tool' || (m.role === 'user' && /Tool execution results/.test(m.content || '')))
+    .map((m) => (typeof m.content === 'string' ? m.content : JSON.stringify(m.content)))
+    .join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// (a) numbered-list question → menu path, NO permission gate
+// ---------------------------------------------------------------------------
+
+test('ask_user with a numbered list renders the menu and fires NO permission gate', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('ask_user', { question: '1. Apples\n2. Bananas' });
+  mock.replyWith('done');
+  try {
+    const { runner, gateCalls, selectCalls } = buildRunner(mock.base, {
+      approverFn: () => true, // would approve IF asked
+      selectPick: 'Bananas',
+    });
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+
+    assert.strictEqual(selectCalls.length, 1, 'the interactive menu was rendered exactly once');
+    assert.deepStrictEqual(selectCalls[0].options, ['Apples', 'Bananas'], 'parsed both numbered options');
+    assert.strictEqual(gateCalls.length, 0, 'NO permission gate fired before the menu');
+    assert.ok(/Bananas/.test(allToolText(messages)), 'the chosen option was fed back to the model');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// (b) free-text question → free-text path, NO permission gate
+// ---------------------------------------------------------------------------
+
+test('ask_user free-text question fires NO permission gate and auto-answers in non-TTY', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('ask_user', { question: 'What is your name?' });
+  mock.replyWith('done');
+  try {
+    const { runner, gateCalls, selectCalls } = buildRunner(mock.base, { approverFn: () => true });
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+
+    assert.strictEqual(gateCalls.length, 0, 'NO permission gate fired for free-text ask_user');
+    assert.strictEqual(selectCalls.length, 0, 'no menu (free-text)');
+    assert.ok(/answered[^\n]*:\s*y\b/.test(allToolText(messages)), 'non-TTY auto-answer reached the executor (answer "y")');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// (c) ISOLATION: a real effectful tool STILL fires its gate
+// ---------------------------------------------------------------------------
+
+test('isolation: exec STILL fires the permission gate through the same runner', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<exec>echo hi</exec>');
+  mock.replyWith('done');
+  try {
+    const { runner, gateCalls } = buildRunner(mock.base, { approverFn: () => true });
+    const messages = [{ role: 'user', content: 'run it' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+
+    assert.strictEqual(gateCalls.length, 1, 'exec consulted the permission gate exactly once');
+    assert.strictEqual(gateCalls[0].actionType, 'shell', 'gate saw the shell action type — unchanged');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// (d) non-TTY / headless: ask_user is NOT refused by the gate (regression of
+//     the old wart, where the non-null descriptor made the gate refuse in
+//     non-TTY before the executor's auto-answer could run). No approver, not
+//     skip-permissions — i.e. an effectful tool here WOULD be refused.
+// ---------------------------------------------------------------------------
+
+test('non-TTY without an approver: ask_user still reaches its executor (not gate-refused)', async () => {
+  const mock = await startMockLLM();
+  mock.replyWithToolCall('ask_user', { question: 'Proceed?' });
+  mock.replyWith('done');
+  try {
+    const { runner, gateCalls } = buildRunner(mock.base, { approverFn: null });
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+
+    assert.strictEqual(gateCalls.length, 0, 'no gate (and so no non-TTY refusal) for ask_user');
+    assert.ok(/answered[^\n]*:\s*y\b/.test(allToolText(messages)), 'executor auto-answered "y" — unchanged headless behavior');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// (e) PLAN MODE: ask_user is now allowed (runs) while an effectful tool in the
+//     SAME response is withheld. Proves the null descriptor lifts the plan-mode
+//     withhold for ask_user only, not for effectful tools.
+// ---------------------------------------------------------------------------
+
+test('plan mode: ask_user runs (clarifying question allowed) while write_file is withheld', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<write_file path="planned.txt">x</write_file>\n<ask_user question="1. Yes\n2. No"/>');
+  mock.replyWith('plan ready');
+  try {
+    const { runner, gateCalls, selectCalls } = buildRunner(mock.base, { approverFn: () => true, selectPick: 'Yes' });
+    const messages = [{ role: 'user', content: 'plan it' }];
+    const res = await runner.runAgentLoop(messages, 'test-model', 10, null, { planMode: true });
+
+    const withheldTags = res.withheldActions.map((a) => a.tag);
+    assert.ok(withheldTags.includes('write'), 'write_file is still withheld in plan mode');
+    assert.ok(!withheldTags.includes('ask_user'), 'ask_user is NOT withheld in plan mode');
+    assert.strictEqual(selectCalls.length, 1, 'ask_user actually rendered its menu during planning');
+    assert.strictEqual(gateCalls.length, 0, 'ask_user did not consult the approval gate while planning');
+    assert.ok(!fs.existsSync(path.join(CWD, 'planned.txt')), 'the withheld write did not touch the disk');
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Convergence: the XML rail produces the same ['ask_user', question] tuple and
+// behaves identically (menu, no gate).
+// ---------------------------------------------------------------------------
+
+test('XML rail converges: <ask_user> numbered list also renders the menu with no gate', async () => {
+  const mock = await startMockLLM();
+  mock.replyWith('<ask_user question="1. Red\n2. Blue"/>');
+  mock.replyWith('done');
+  try {
+    const { runner, gateCalls, selectCalls } = buildRunner(mock.base, { approverFn: () => true, selectPick: 'Blue' });
+    const messages = [{ role: 'user', content: 'ask me' }];
+    await runner.runAgentLoop(messages, 'test-model', 10, null, {});
+
+    assert.strictEqual(selectCalls.length, 1, 'XML rail rendered the menu');
+    assert.deepStrictEqual(selectCalls[0].options, ['Red', 'Blue']);
+    assert.strictEqual(gateCalls.length, 0, 'XML rail fired no gate either');
+    assert.ok(/Blue/.test(allToolText(messages)));
+  } finally {
+    await mock.close();
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Prompt wording: the inventory now documents the numbered-list menu trigger so
+// the model knows how to surface a choice.
+// ---------------------------------------------------------------------------
+
+test('prompts.js ask_user inventory documents the numbered-list menu', () => {
+  const { TOOL_TAG_SPECS } = require('../lib/prompts');
+  const purpose = TOOL_TAG_SPECS.ask_user.purpose;
+  assert.ok(/numbered list/i.test(purpose), 'mentions a numbered list');
+  assert.ok(/menu/i.test(purpose), 'mentions the menu rendering');
+});