@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/ui/Composer.d.ts

@@ -18,6 +18,7 @@ import React from 'react';
 import type { Theme } from './theme.js';
 import type { TermCapabilities } from './capabilities.js';
 import { type CommandOption } from './PromptInput.js';
+import { type AgentMode } from '../agent/agent-mode.js';
 export interface ComposerProps {
     /** False while an overlay owns the keyboard (the input is visually blurred). */
     isActive: boolean;
@@ -31,10 +32,17 @@ export interface ComposerProps {
     submitCount: number;
     /** User opt-out (`--no-hints` / `hints: false`). */
     hintsEnabled: boolean;
+    /** Mirror of the controller's effective mode; drives the chip and the border. */
+    agentMode: AgentMode;
     popupMaxRows?: number;
+    /** Pure pass-through to `PromptInput` (mouse-wheel-region-routing §5.6). */
+    historyIntent?: {
+        dir: 'up' | 'down';
+        nonce: number;
+    };
     theme: Theme;
     caps: TermCapabilities;
     onSubmit: (text: string) => void;
     onHelp?: () => void;
 }
-export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, popupMaxRows, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;
+export declare function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, historyIntent, theme, caps, onSubmit, onHelp, }: ComposerProps): React.ReactElement;

package/dist/ui/Composer.js

@@ -20,6 +20,8 @@ import { Box, Text } from 'ink';
 import { pickGlyphs } from './glyphs.js';
 import { HINT_FADE_AFTER } from '../config/schema.js';
 import { PromptInput } from './PromptInput.js';
+import { ModeChip } from './ModeChip.js';
+import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 /**
  * Build the hint row.
  *
@@ -30,32 +32,49 @@ import { PromptInput } from './PromptInput.js';
  * Progressive disclosure is for teaching discoverable things, not for retiring
  * an emergency exit (§4.6 / A-14 / M-10b).
  */
-function hintText(running, submitCount, glyphs) {
+function hintText(running, submitCount, glyphs, mode) {
     const dot = ` ${glyphs.midDot} `;
     if (running) {
         return [`${glyphs.enterKey} steer`, 'esc abort', `ctrl+c${glyphs.times}2 exit`].join(dot);
     }
+    // The hint names the DESTINATION, not the current state — the correct label
+    // for a toggle affordance, and the reason the mode word here is the OPPOSITE
+    // of the one on the chip beside it.
+    const toggle = `shift+tab ${MODE_LABEL[nextMode(mode)].toLowerCase()}`;
+    // The faded form KEEPS the mode toggle. Progressive disclosure exists to
+    // retire things the user has demonstrably learned, and `submitCount` counts
+    // submissions — a user can send fifty messages without ever discovering
+    // Shift+Tab. Same argument that keeps `esc abort` un-faded above.
     if (submitCount >= HINT_FADE_AFTER)
-        return '? help';
+        return [toggle, '? help'].join(dot);
     return [
         `${glyphs.enterKey} send`,
         `${glyphs.shiftEnter} newline`,
         '/ commands',
         '@ files',
+        toggle,
         '? help',
     ].join(dot);
 }
-export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, popupMaxRows, theme, caps, onSubmit, onHelp, }) {
+export function Composer({ isActive, running, history, commands, cwd, showHint, submitCount, hintsEnabled, agentMode, popupMaxRows, historyIntent, theme, caps, onSubmit, onHelp, }) {
     const [hasDraft, setHasDraft] = useState(false);
     const onDraftChange = useCallback((next) => setHasDraft(next), []);
+    // Plan mode inserts ONE branch, above `draft` and below `running`. The
+    // ordering is load-bearing: an in-flight run's border must stay `toolRunning`,
+    // because "is it running" is more urgent than "which mode".
     const borderColor = !isActive
         ? theme.toolPending
         : running
             ? theme.toolRunning
-            : hasDraft
-                ? theme.focusBorder ?? theme.primary
-                : theme.idleBorder ?? theme.border;
+            : agentMode === 'plan'
+                ? theme.accent
+                : hasDraft
+                    ? theme.focusBorder ?? theme.primary
+                    : theme.idleBorder ?? theme.border;
     const glyphs = pickGlyphs(caps);
     const visible = showHint && hintsEnabled;
-    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsx(PromptInput, { isActive: isActive, running: running, history: history, commands: commands, cwd: cwd, theme: theme, caps: caps, popupMaxRows: popupMaxRows, onSubmit: onSubmit, onHelp: onHelp, bordered: { color: borderColor }, onDraftChange: onDraftChange }), visible && (_jsxs(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: ['  ', hintText(running, submitCount, glyphs)] }))] }));
+    return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [_jsx(PromptInput, { isActive: isActive, running: running, history: history, commands: commands, cwd: cwd, theme: theme, caps: caps, popupMaxRows: popupMaxRows, onSubmit: onSubmit, onHelp: onHelp, agentMode: agentMode, bordered: { color: borderColor }, onDraftChange: onDraftChange, historyIntent: historyIntent }), visible && (
+            // The chip rides the EXISTING hint row rather than adding one, so it
+            // costs zero rows on a 24-row terminal.
+            _jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsx(Text, { children: '  ' }), _jsx(ModeChip, { mode: agentMode, theme: theme, caps: caps }), _jsx(Text, { wrap: "truncate", color: theme.hintFg ?? theme.muted, children: hintText(running, submitCount, glyphs, agentMode) })] }))] }));
 }

package/dist/ui/ModeChip.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ModeChip — the `PLAN` badge on the composer's hint row (plan-mode §6.1).
+ *
+ * `theme.chip = { fg, bg }` exists in every palette and was, until now, unused.
+ * A mode badge is what it was for.
+ *
+ * SHOWN ONLY IN PLAN MODE. `BUILD` is the default, and a badge that is always on
+ * is furniture rather than signal; it also means the Build-mode composer renders
+ * exactly as it did before this feature existed.
+ *
+ * THE CHIP IS AN ENHANCEMENT, NOT THE GUARANTEE (P1-6). It rides the hint row,
+ * which disappears on a short terminal (`showHint`), under `hints: false`, and
+ * in inline render mode (which mounts a bare `PromptInput` and never mounts
+ * `Composer` at all). The GUARANTEED carrier is the status-bar word, which
+ * renders in both `AppShell` branches and has no opt-out. If you ever move the
+ * mode indicator, that is the constraint to preserve: the status bar must always
+ * name a non-default mode; the chip may.
+ */
+import React from 'react';
+import type { Theme } from './theme.js';
+import type { TermCapabilities } from './capabilities.js';
+import { type AgentMode } from '../agent/agent-mode.js';
+interface ModeChipProps {
+    mode: AgentMode;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function ModeChip({ mode, theme, caps }: ModeChipProps): React.ReactElement | null;
+export {};

package/dist/ui/ModeChip.js

@@ -0,0 +1,15 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { MODE_LABEL } from '../agent/agent-mode.js';
+export function ModeChip({ mode, theme, caps }) {
+    if (mode !== 'plan')
+        return null;
+    const label = MODE_LABEL[mode];
+    // `Box backgroundColor` degrades to plain text at colorLevel 0, where the chip
+    // would become invisible against the hint row. Brackets carry the same
+    // "this is a badge" reading with no color at all.
+    if (caps.colorLevel === 0) {
+        return (_jsxs(Text, { wrap: "truncate", bold: true, children: ["[", label, "]", ' '] }));
+    }
+    return (_jsx(Box, { flexShrink: 0, marginRight: 1, children: _jsxs(Text, { backgroundColor: theme.chip.bg, color: theme.chip.fg, bold: true, children: [' ', label, ' '] }) }));
+}

package/dist/ui/PromptInput.d.ts

@@ -13,6 +13,7 @@ import type { Theme } from './theme.js';
 import type { TermCapabilities } from './capabilities.js';
 import { type EditIntent } from '../input/keymap.js';
 import { type Suggestion } from './AutocompletePopup.js';
+import type { AgentMode } from '../agent/agent-mode.js';
 export interface CommandOption {
     name: string;
     description: string;
@@ -37,6 +38,12 @@ interface PromptInputProps {
     popupMaxRows?: number;
     onSubmit: (text: string) => void;
     onHelp?: () => void;
+    /**
+     * Mirror of the session mode. Read for the placeholder only — the toggle
+     * itself belongs to `App`, and this component's job is to get out of its way
+     * (see the first statement of the input handler).
+     */
+    agentMode?: AgentMode;
     /**
      * Set by `Composer` in full-screen mode: draw the rounded frame around the
      * input row only, so the autocomplete popup lands OUTSIDE it (spec §4.7)
@@ -48,6 +55,20 @@ interface PromptInputProps {
     };
     /** Fires only when the draft flips empty ⇄ non-empty, for the border color. */
     onDraftChange?: (hasDraft: boolean) => void;
+    /**
+     * One prompt-history step, pushed by the wheel router when a notch lands on
+     * the composer band (mouse-wheel-region-routing §5.6). `nonce` is monotonic
+     * so two notches in the same direction are two steps.
+     *
+     * Applied through the SAME `verticalOrHistory` / popup-selection branches the
+     * keyboard uses, deliberately: it means the wheel and `↑`/`↓` cannot drift
+     * apart, and the "never clobber an in-progress draft" guard protects the
+     * wheel for free.
+     */
+    historyIntent?: {
+        dir: 'up' | 'down';
+        nonce: number;
+    };
 }
 /** Apply an edit intent as a pure buffer/cursor transform. */
 export declare function applyEdit(buffer: string, cursor: number, intent: EditIntent): {
@@ -77,5 +98,5 @@ export declare function fileTokenAt(buffer: string, cursor: number): {
     end: number;
     query: string;
 } | null;
-export declare function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, onSubmit, onHelp, bordered, onDraftChange, }: PromptInputProps): React.ReactElement;
+export declare function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, historyIntent, }: PromptInputProps): React.ReactElement;
 export {};

package/dist/ui/PromptInput.js

@@ -127,7 +127,7 @@ function isControlSeq(input) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, onSubmit, onHelp, bordered, onDraftChange, }) {
+export function PromptInput({ isActive, running, history, commands, cwd, theme, caps, popupMaxRows, agentMode, onSubmit, onHelp, bordered, onDraftChange, historyIntent, }) {
     const [buffer, setBuffer] = useState('');
     const [cursor, setCursor] = useState(0);
     const [historyIndex, setHistoryIndex] = useState(null);
@@ -261,8 +261,53 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
                 recallDown();
         }
     };
+    // --- Wheel-driven history step (mouse-wheel-region-routing §5.6). ---------
+    // The applier closes over the buffer, the cursor and the popup state, so it
+    // is re-created on every render and reached through a ref: depending on it
+    // directly would re-fire the effect on every keystroke.
+    const applyHistoryIntent = useRef(() => { });
+    applyHistoryIntent.current = (dir) => {
+        // Mirrors the keyboard branch exactly — with the completion popup open,
+        // Up/Down move the selection rather than recalling history.
+        if (popupItems.length > 0) {
+            setSel(dir === 'up'
+                ? Math.max(0, clampedSel - 1)
+                : Math.min(popupItems.length - 1, clampedSel + 1));
+            return;
+        }
+        verticalOrHistory(dir);
+    };
+    const historyIntentRef = useRef(historyIntent);
+    historyIntentRef.current = historyIntent;
+    // I-9: seeded from the incoming nonce during the FIRST render, so a mount
+    // that inherits a nonce cannot replay it. This component really does remount
+    // — `App` returns the terminal-too-small placeholder before `AppShell` —
+    // so without the guard, shrinking the window mid-wheel and growing it back
+    // recalls a history entry with no gesture behind it.
+    const lastHistoryNonce = useRef(historyIntent?.nonce);
+    const historyNonce = historyIntent?.nonce ?? 0;
+    useEffect(() => {
+        const current = historyIntentRef.current;
+        if (!current || !isActive)
+            return;
+        if (current.nonce === lastHistoryNonce.current)
+            return;
+        lastHistoryNonce.current = current.nonce;
+        applyHistoryIntent.current(current.dir);
+        // Keyed on the nonce alone, same reasoning as `ScrollViewport`'s intent
+        // effect: `historyIntent` is a fresh object on every parent render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [historyNonce]);
     // --- Input handling. -----------------------------------------------------
     useInput((input, key) => {
+        // FIRST STATEMENT, BEFORE THE POPUP BRANCH, AND IT HAS TO STAY THERE.
+        // `App` owns the Shift+Tab mode toggle. The popup branch below treats
+        // `key.tab` as "accept the highlighted completion", so without this guard
+        // pressing Shift+Tab with the `/` palette or an `@` file popup open would
+        // BOTH rewrite the user's draft and change the mode — a bug that only
+        // appears with a popup open and is therefore easy to ship (AC-P3 / R-P2).
+        if (key.tab && key.shift)
+            return;
         // Popup navigation owns Up/Down/Tab/→/Enter/Esc while it is open.
         if (popupItems.length > 0) {
             if (key.upArrow) {
@@ -353,7 +398,9 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
     const markerColor = running ? theme.toolRunning : theme.primary;
     const placeholder = running
         ? `Type to steer the run, Esc to abort${glyphs.ellipsis}`
-        : `Send a message (/ for commands, @ for files)${glyphs.ellipsis}`;
+        : agentMode === 'plan'
+            ? `Describe what you want to build; I'll research and plan it first${glyphs.ellipsis}`
+            : `Send a message (/ for commands, @ for files)${glyphs.ellipsis}`;
     const lines = renderWithCursor(buffer, cursor, isActive);
     const inputRow = (_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: markerColor, bold: true, children: [marker, ' '] }), _jsx(Box, { flexDirection: "column", children: buffer.length === 0 ? (_jsx(Text, { color: theme.muted, children: placeholder })) : (lines.map((line, i) => _jsx(Text, { children: line }, i))) })] }));
     return (_jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [popupItems.length > 0 && (_jsx(AutocompletePopup, { items: popupItems, selected: clampedSel, theme: theme, caps: caps, maxRows: popupMaxRows })), bordered ? (_jsx(Box, { flexDirection: "column", flexShrink: 0, borderStyle: glyphs.boxStyle, borderColor: bordered.color, paddingX: 1, children: inputRow })) : (inputRow)] }));

package/dist/ui/StatusBar.d.ts

@@ -11,6 +11,7 @@ import React from 'react';
 import type { Theme } from './theme.js';
 import type { TermCapabilities } from './capabilities.js';
 import type { UsageTotal } from '../agent/reducer.js';
+import { type AgentMode } from '../agent/agent-mode.js';
 interface StatusBarProps {
     model: string;
     provider: string;
@@ -34,6 +35,20 @@ interface StatusBarProps {
      * Ctrl+L redraw carrier — invariant I-5 (spec §4.13). See `redrawChar`.
      */
     redrawNonce?: number;
+    /**
+     * The session mode. THIS IS THE GUARANTEED MODE INDICATOR (plan-mode §6.4 /
+     * P1-6): the composer chip disappears on a short terminal, under
+     * `hints: false`, and in inline render mode, but `StatusBar` renders in both
+     * `AppShell` branches and its left cluster has no opt-out and no width gate.
+     *
+     * Design intent, stated here so it survives a later refactor: the status bar
+     * must ALWAYS name a non-default mode; the chip may. Do not give this a
+     * `cols >= N` breakpoint, and do not move it into the right cluster — those
+     * children are flexible and drop characters under pressure.
+     */
+    agentMode?: AgentMode;
+    /** Non-null while a deferred `plan -> build` waits for `agent_end`. */
+    pendingAgentMode?: AgentMode | null;
 }
 export declare function StatusBar(props: StatusBarProps): React.ReactElement;
 export {};

package/dist/ui/StatusBar.js

@@ -3,6 +3,7 @@ import { Box, Text, useStdout } from 'ink';
 import { pickGlyphs } from './glyphs.js';
 import { formatCost, formatTokens, formatDuration } from '../agent/usage.js';
 import { buildGauge } from './gauge.js';
+import { MODE_LABEL } from '../agent/agent-mode.js';
 /**
  * I-5 — DO NOT "CLEAN THIS UP". Ink short-circuits identical output at TWO
  * gates (`ink.js:132` and `log-update.js:13`), so a fixed frame whose React
@@ -22,7 +23,7 @@ function redrawChar(nonce) {
     return nonce % 2 === 0 ? ' ' : NBSP;
 }
 export function StatusBar(props) {
-    const { model, provider, usageTotal, contextTokens, contextWindow, contextWindowKnown, status, elapsedMs, thinkingLevel, tokPerSec, theme, caps, scrolledLines = 0, redrawNonce = 0, } = props;
+    const { model, provider, usageTotal, contextTokens, contextWindow, contextWindowKnown, status, elapsedMs, thinkingLevel, tokPerSec, theme, caps, scrolledLines = 0, redrawNonce = 0, agentMode = 'build', pendingAgentMode = null, } = props;
     const { stdout } = useStdout();
     const cols = stdout?.columns ?? 80;
     const running = status === 'running';
@@ -32,6 +33,13 @@ export function StatusBar(props) {
     const pctLabel = `${contextWindowKnown ? '' : '~'}${gauge.pct}%`;
     const tokens = `${formatTokens(usageTotal.inputTokens)}${glyphs.arrowUp} ${formatTokens(usageTotal.outputTokens)}${glyphs.arrowDown}`;
     const statusGlyph = running ? theme.symbols.toolRunning : theme.symbols.toolPending;
+    // Nothing at all in build mode with nothing pending: the default posture is
+    // not news, and a permanent word here would be furniture.
+    const modeWord = agentMode === 'build' && !pendingAgentMode
+        ? ''
+        : pendingAgentMode
+            ? `${MODE_LABEL[agentMode]} ${glyphs.arrowRight} ${MODE_LABEL[pendingAgentMode]}`
+            : MODE_LABEL[agentMode];
     return (
     // `flexShrink={0}` on the left cluster is not cosmetic. When the two clusters
     // over-subscribe the row, yoga shrinks the flexible children and Ink's text
@@ -39,5 +47,5 @@ export function StatusBar(props) {
     // and "? hel" rather than truncating cleanly at one end. Pinning the left
     // cluster keeps the run status and model intact and makes the degradation
     // land in one predictable place.
-    _jsxs(Box, { flexDirection: "row", justifyContent: "space-between", flexShrink: 0, children: [_jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsxs(Text, { color: running ? theme.toolRunning : theme.toolDone, children: [redrawChar(redrawNonce), statusGlyph, " ", running ? 'running' : 'idle'] }), cols >= 60 && (_jsxs(Text, { color: theme.muted, children: ['  ', provider, ":", model] })), thinkingLevel !== 'off' && cols >= 72 && (_jsxs(Text, { color: theme.accent, children: ["  think:", thinkingLevel] }))] }), _jsxs(Box, { flexDirection: "row", children: [scrolledLines > 0 && (_jsxs(Text, { color: theme.noticeWarn, children: [glyphs.arrowUp, scrolledLines, '  '] })), cols >= 60 && (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "[" }), _jsx(Text, { color: gauge.fillColor, children: gauge.filled }), _jsx(Text, { color: gauge.trackColor, children: gauge.empty }), _jsx(Text, { color: theme.muted, children: "] " })] })), _jsx(Text, { color: theme.muted, children: pctLabel }), cols >= 72 && _jsxs(Text, { color: theme.muted, children: ["  ", tokens] }), _jsxs(Text, { color: theme.muted, children: ["  ", formatCost(usageTotal.costUsd)] }), running && (_jsxs(Text, { color: theme.muted, children: [tokPerSec > 0 && cols >= 72 ? `  ${tokPerSec} tok/s` : '', "  ", formatDuration(elapsedMs)] }))] })] }));
+    _jsxs(Box, { flexDirection: "row", justifyContent: "space-between", flexShrink: 0, children: [_jsxs(Box, { flexDirection: "row", flexShrink: 0, children: [_jsxs(Text, { color: running ? theme.toolRunning : theme.toolDone, children: [redrawChar(redrawNonce), statusGlyph, " ", running ? 'running' : 'idle'] }), modeWord && (_jsxs(Text, { color: theme.accent, bold: true, children: ['  ', modeWord] })), cols >= 60 && (_jsxs(Text, { color: theme.muted, children: ['  ', provider, ":", model] })), thinkingLevel !== 'off' && cols >= 72 && (_jsxs(Text, { color: theme.accent, children: ["  think:", thinkingLevel] }))] }), _jsxs(Box, { flexDirection: "row", children: [scrolledLines > 0 && (_jsxs(Text, { color: theme.noticeWarn, children: [glyphs.arrowUp, scrolledLines, '  '] })), cols >= 60 && (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: "[" }), _jsx(Text, { color: gauge.fillColor, children: gauge.filled }), _jsx(Text, { color: gauge.trackColor, children: gauge.empty }), _jsx(Text, { color: theme.muted, children: "] " })] })), _jsx(Text, { color: theme.muted, children: pctLabel }), cols >= 72 && _jsxs(Text, { color: theme.muted, children: ["  ", tokens] }), _jsxs(Text, { color: theme.muted, children: ["  ", formatCost(usageTotal.costUsd)] }), running && (_jsxs(Text, { color: theme.muted, children: [tokPerSec > 0 && cols >= 72 ? `  ${tokPerSec} tok/s` : '', "  ", formatDuration(elapsedMs)] }))] })] }));
 }

package/dist/ui/entries/ToolPreview.d.ts

@@ -34,6 +34,8 @@ export declare function parseWriteFile(text: string): {
     bytes: number;
     path: string;
 } | null;
+/** `3 questions · Postgres · REST` — or `dismissed`. */
+export declare function summarizeAskUser(lines: string[]): string | null;
 export interface ListRow {
     kind: 'dir' | 'file';
     name: string;

package/dist/ui/entries/ToolPreview.js

@@ -44,6 +44,40 @@ export function parseWriteFile(text) {
         return null;
     return { bytes: Number.parseInt(m[1], 10), path: m[2] };
 }
+/**
+ * Parse the JSON tail of a tool result whose first line is prose.
+ *
+ * FAILS SOFT, ALWAYS. This runs inside a render pass, and the stored preview may
+ * have been truncated at `STORED_PREVIEW_CHARS` or restored from a session file
+ * written by another build. `null` means "fall through to the generic
+ * renderer", never "throw while drawing the transcript".
+ */
+function parseJsonTail(lines) {
+    const start = lines.findIndex((l) => l.trimStart().startsWith('{'));
+    if (start < 0)
+        return null;
+    try {
+        return JSON.parse(lines.slice(start).join('\n'));
+    }
+    catch {
+        return null;
+    }
+}
+/** `3 questions · Postgres · REST` — or `dismissed`. */
+export function summarizeAskUser(lines) {
+    const parsed = parseJsonTail(lines);
+    if (!parsed || !Array.isArray(parsed.answers))
+        return null;
+    if (parsed.cancelled)
+        return 'dismissed';
+    const count = parsed.answers.length;
+    const picks = parsed.answers
+        .map((a) => (typeof a.custom === 'string' && a.custom.length > 0
+        ? a.custom
+        : Array.isArray(a.selected) ? a.selected.join('/') : ''))
+        .filter((s) => s.length > 0);
+    return [`${count} question${count === 1 ? '' : 's'}`, ...picks].join(' - ');
+}
 /** Parse a real `list_dir` row (`dir <name>/` / `file <name> (<n>b)`) (P2-9). */
 export function parseListRow(line) {
     const dir = /^dir\s+(.*?)\/?\s*$/.exec(line);
@@ -113,6 +147,30 @@ function renderGlob(lines, theme) {
         return (_jsxs(Text, { children: [_jsx(Text, { color: theme.muted, children: line.slice(0, slash + 1) }), line.slice(slash + 1)] }, i));
     });
 }
+function renderAskUser(lines, theme) {
+    const summary = summarizeAskUser(lines);
+    // An unparseable preview falls through to the generic renderer rather than
+    // rendering nothing: a truncated result is still information.
+    if (!summary)
+        return renderPlain(lines, theme, false);
+    return [
+        _jsx(Text, { color: theme.muted, children: summary }, "q"),
+    ];
+}
+/**
+ * `Plan approved.` / `Plan rejected. ...` — the verdict is the whole content of
+ * a `submit_plan` result, and it is the first line, so this needs no parsing.
+ */
+function renderSubmitPlan(lines, theme) {
+    const first = lines.find((l) => l.trim().length > 0) ?? '';
+    const approved = /^Plan approved/.test(first);
+    const rejected = /^Plan rejected/.test(first);
+    if (!approved && !rejected)
+        return renderPlain(lines, theme, false);
+    return [
+        _jsx(Text, { color: approved ? theme.toolDone : theme.noticeWarn, children: first }, "v"),
+    ];
+}
 function renderPlain(lines, theme, error) {
     return lines.map((line, i) => (_jsx(Text, { color: error ? theme.toolError : theme.muted, children: line.length > 0 ? line : ' ' }, i)));
 }
@@ -137,6 +195,12 @@ export function ToolPreview({ name, lines, theme, isError }) {
         case 'glob':
             body = renderGlob(lines, theme);
             break;
+        case 'ask_user':
+            body = renderAskUser(lines, theme);
+            break;
+        case 'submit_plan':
+            body = renderSubmitPlan(lines, theme);
+            break;
         default:
             body = renderPlain(lines, theme, isError);
     }

package/dist/ui/glyphs.d.ts

@@ -37,6 +37,15 @@ export interface Glyphs {
     gaugeEmpty: string;
     keyOn: string;
     keyOff: string;
+    /**
+     * Checkbox pair for a multi-select question (`allowMultiple`).
+     *
+     * Distinct from `keyOn` / `keyOff`, which are radios: a user looking at a list
+     * has to be able to tell "pick one" from "pick several" without reading the
+     * footer, and that distinction is exactly what the two shapes carry.
+     */
+    boxChecked: string;
+    boxEmpty: string;
     wordmark: string;
     ellipsis: string;
     emDash: string;
@@ -63,6 +72,18 @@ export interface Glyphs {
     railVertical: string;
     railBranch: string;
     railEnd: string;
+    /**
+     * Scroll-position indicator on the viewport's right edge (mouse-wheel §4.8).
+     *
+     * These are byte-for-byte identical to `railVertical` / `gaugeFull` in both
+     * tiers, and that is DELIBERATE (P2-2). This file's header mandates "add a
+     * field here instead" of a new exception, and semantic field names are what
+     * make the ASCII tier reviewable at a glance. Reusing `gaugeFull` would
+     * couple the scroll thumb to the context-window gauge, so that restyling one
+     * silently restyles the other — do not "deduplicate" them.
+     */
+    scrollTrack: string;
+    scrollThumb: string;
     /** Redaction dot for `maskSecret` in the settings screen (§4.1 tier B). */
     maskDot: string;
     /**

package/dist/ui/glyphs.js

@@ -35,6 +35,8 @@ const UNICODE_GLYPHS = {
     gaugeEmpty: '░',
     keyOn: '●',
     keyOff: '○',
+    boxChecked: '☑',
+    boxEmpty: '☐',
     wordmark: '◇',
     ellipsis: '…',
     emDash: '—',
@@ -53,6 +55,8 @@ const UNICODE_GLYPHS = {
     railVertical: '│',
     railBranch: '├',
     railEnd: '╰',
+    scrollTrack: '│',
+    scrollThumb: '█',
     maskDot: '•',
     boxStyle: 'round',
     tool: {
@@ -63,6 +67,8 @@ const UNICODE_GLYPHS = {
         glob: '⌕',
         grep: '⌕',
         list_dir: '▤',
+        ask_user: '?',
+        submit_plan: '◈',
     },
     toolDefault: '•',
 };
@@ -83,6 +89,8 @@ const ASCII_GLYPHS = {
     gaugeEmpty: '-',
     keyOn: '*',
     keyOff: 'o',
+    boxChecked: '[x]',
+    boxEmpty: '[ ]',
     wordmark: '<>',
     ellipsis: '...',
     emDash: '--',
@@ -101,6 +109,8 @@ const ASCII_GLYPHS = {
     railVertical: '|',
     railBranch: '|',
     railEnd: '\\',
+    scrollTrack: '|',
+    scrollThumb: '#',
     maskDot: '*',
     boxStyle: 'classic',
     tool: {
@@ -111,6 +121,8 @@ const ASCII_GLYPHS = {
         glob: '/',
         grep: '/',
         list_dir: '=',
+        ask_user: '?',
+        submit_plan: '#',
     },
     toolDefault: '*',
 };

package/dist/ui/layout/AppShell.d.ts

@@ -11,6 +11,7 @@
  */
 import React from 'react';
 import { type RenderMode } from './frame.js';
+import { type FrameGeometry } from './regions.js';
 export interface AppShellProps {
     mode: RenderMode;
     rows: number;
@@ -20,5 +21,13 @@ export interface AppShellProps {
     toast: React.ReactNode;
     composer: React.ReactNode;
     status: React.ReactNode;
+    /**
+     * Where the wheel router reads the composer band boundary from (mouse-wheel
+     * §4.5). Written in a LAYOUT EFFECT to a MUTABLE REF, never to state: the
+     * measurement happens on every commit, and routing it through `setState`
+     * would add a re-render to the streaming path for a value nothing renders
+     * (R-7).
+     */
+    geometryRef?: React.MutableRefObject<FrameGeometry>;
 }
-export declare function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, }: AppShellProps): React.ReactElement;
+export declare function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, geometryRef, }: AppShellProps): React.ReactElement;

package/dist/ui/layout/AppShell.js

@@ -1,9 +1,44 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { Box } from 'ink';
+/**
+ * AppShell (spec §4.3) — the frame that makes R2 true.
+ *
+ * In `fullscreen` the root box has a FIXED height of `frameHeight(rows)` and the
+ * middle viewport is the only `flexGrow` child, so the bottom chrome (toast /
+ * composer / status bar) is physically the last thing on the screen from the
+ * very first frame — empty session, long session, mid-scroll, overlay open.
+ *
+ * In `inline` the same children are emitted in the same order with no height
+ * constraint, i.e. byte-for-byte the v0.2.0 document-flow behavior.
+ */
+import { useLayoutEffect, useRef } from 'react';
+import { Box, measureElement } from 'ink';
 import { frameHeight } from './frame.js';
-export function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, }) {
+import { UNMEASURED_GEOMETRY } from './regions.js';
+export function AppShell({ mode, rows, cols, header, viewport, toast, composer, status, geometryRef, }) {
+    const bottomRef = useRef(null);
+    // DECLARED ABOVE THE INLINE EARLY RETURN, and it has to stay there: React
+    // keys hooks by call order, and a hook that only runs in one mode changes
+    // that order between modes.
+    //
+    // Ink computes yoga layout in `onRender`, which React runs BEFORE layout
+    // effects, so this reflects the commit that just happened — the same
+    // mechanism `ScrollViewport` already relies on.
+    useLayoutEffect(() => {
+        if (!geometryRef)
+            return;
+        if (mode === 'inline' || !bottomRef.current) {
+            geometryRef.current = UNMEASURED_GEOMETRY;
+            return;
+        }
+        geometryRef.current = {
+            // 1 in the alternate screen — see the note on `FrameGeometry.top`.
+            top: 1,
+            height: frameHeight(rows),
+            bottom: measureElement(bottomRef.current).height,
+        };
+    });
     if (mode === 'inline') {
         return (_jsxs(Box, { flexDirection: "column", children: [header, viewport, toast, composer, status] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [toast, composer, status] })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: frameHeight(rows), width: cols, overflow: "hidden", children: [_jsx(Box, { flexDirection: "column", flexShrink: 0, children: header }), _jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden", children: viewport }), _jsxs(Box, { ref: bottomRef, flexDirection: "column", flexShrink: 0, children: [toast, composer, status] })] }));
 }

package/dist/ui/layout/ScrollIndicator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ScrollIndicator (mouse-wheel-region-routing §4.8) — the one-column scroll
+ * position rail on the viewport's right edge.
+ *
+ * NAMING (P2-1): this is NOT `layout/Gutter.tsx`. That one is the two-column
+ * left rail every transcript entry sits in, and it carries an invariant of its
+ * own. Two components called a gutter, on opposite edges, for unrelated
+ * purposes, is how a codebase stops being able to say what it means.
+ *
+ * THE COLUMN IS RESERVED UNCONDITIONALLY, track glyph and all. Showing it only
+ * while scrolled would change the content width, re-wrap every line, change the
+ * content height, and feed that back into the measurement that decides whether
+ * to show it — a shimmer at the exact moment the user is reading. Constant
+ * width, no feedback loop (D-9); `width={1}` and `flexShrink={0}` hold the
+ * column even on the first frame, before anything has been measured.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { ThumbRange } from './scroll-indicator.js';
+/** Below this width a column of content is worth more than the affordance. */
+export declare const MIN_INDICATOR_COLS = 50;
+export interface ScrollIndicatorProps {
+    /** Viewport height in rows, as measured by `ScrollViewport`. */
+    rows: number;
+    /** `null` when the content fits — the rail is drawn as bare track. */
+    thumb: ThumbRange | null;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+export declare function ScrollIndicator({ rows, thumb, theme, caps, }: ScrollIndicatorProps): React.ReactElement;

package/dist/ui/layout/ScrollIndicator.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+/** Below this width a column of content is worth more than the affordance. */
+export const MIN_INDICATOR_COLS = 50;
+export function ScrollIndicator({ rows, thumb, theme, caps, }) {
+    const glyphs = pickGlyphs(caps);
+    const count = Math.max(0, Math.floor(rows) || 0);
+    const cells = [];
+    for (let i = 0; i < count; i += 1) {
+        const onThumb = !!thumb && i >= thumb.start && i < thumb.start + thumb.size;
+        cells.push(_jsx(Text, { color: onThumb ? theme.primary : theme.border, children: onThumb ? glyphs.scrollThumb : glyphs.scrollTrack }, i));
+    }
+    return (_jsx(Box, { flexDirection: "column", flexShrink: 0, width: 1, children: cells }));
+}