@aragon-agent/cli 0.5.0 → 0.5.1

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)
@@ -77,5 +84,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, }: 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, }) {
     const [buffer, setBuffer] = useState('');
     const [cursor, setCursor] = useState(0);
     const [historyIndex, setHistoryIndex] = useState(null);
@@ -263,6 +263,14 @@ export function PromptInput({ isActive, running, history, commands, cwd, theme,
     };
     // --- 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 +361,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;

package/dist/ui/glyphs.js

@@ -35,6 +35,8 @@ const UNICODE_GLYPHS = {
     gaugeEmpty: '░',
     keyOn: '●',
     keyOff: '○',
+    boxChecked: '☑',
+    boxEmpty: '☐',
     wordmark: '◇',
     ellipsis: '…',
     emDash: '—',
@@ -63,6 +65,8 @@ const UNICODE_GLYPHS = {
         glob: '⌕',
         grep: '⌕',
         list_dir: '▤',
+        ask_user: '?',
+        submit_plan: '◈',
     },
     toolDefault: '•',
 };
@@ -83,6 +87,8 @@ const ASCII_GLYPHS = {
     gaugeEmpty: '-',
     keyOn: '*',
     keyOff: 'o',
+    boxChecked: '[x]',
+    boxEmpty: '[ ]',
     wordmark: '<>',
     ellipsis: '...',
     emDash: '--',
@@ -111,6 +117,8 @@ const ASCII_GLYPHS = {
         glob: '/',
         grep: '/',
         list_dir: '=',
+        ask_user: '?',
+        submit_plan: '#',
     },
     toolDefault: '*',
 };

package/dist/ui/layout/wrap-rows.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `wrapToRows` — the prose wrapper for `OverlayFrame`'s controlled (mode A)
+ * content (plan-mode §6.6).
+ *
+ * Mode A's contract is *one element per row, each already `wrap="truncate"`*,
+ * and `sliceWindow` counts ELEMENTS, not lines. Help and Settings satisfy that
+ * naturally because their content is a list of short rows. A plan is not: its
+ * summary runs to 600 characters and a step detail to 400, so handing either
+ * over as a single `<Text>` renders the whole paragraph as one truncated line —
+ * the single worst failure available to a plan review card, and one that also
+ * makes the frame's `1-14/22` position indicator a false statement.
+ *
+ * The repo had no wrapper before this (no `wrapText`, no `wordWrap`), so here is
+ * one: pure, no Ink, unit-tested.
+ */
+/**
+ * Break `text` into lines of at most `width` columns.
+ *
+ * Prefers spaces; hard-breaks any single token longer than `width` (a URL or a
+ * long path, which must not be dropped and cannot be wrapped politely).
+ * Existing newlines are honoured as paragraph breaks. Returns `[]` for empty
+ * input so callers can splice the result without an emptiness branch.
+ */
+export declare function wrapToRows(text: string, width: number): string[];

package/dist/ui/layout/wrap-rows.js

@@ -0,0 +1,74 @@
+/**
+ * `wrapToRows` — the prose wrapper for `OverlayFrame`'s controlled (mode A)
+ * content (plan-mode §6.6).
+ *
+ * Mode A's contract is *one element per row, each already `wrap="truncate"`*,
+ * and `sliceWindow` counts ELEMENTS, not lines. Help and Settings satisfy that
+ * naturally because their content is a list of short rows. A plan is not: its
+ * summary runs to 600 characters and a step detail to 400, so handing either
+ * over as a single `<Text>` renders the whole paragraph as one truncated line —
+ * the single worst failure available to a plan review card, and one that also
+ * makes the frame's `1-14/22` position indicator a false statement.
+ *
+ * The repo had no wrapper before this (no `wrapText`, no `wordWrap`), so here is
+ * one: pure, no Ink, unit-tested.
+ */
+/**
+ * Break `text` into lines of at most `width` columns.
+ *
+ * Prefers spaces; hard-breaks any single token longer than `width` (a URL or a
+ * long path, which must not be dropped and cannot be wrapped politely).
+ * Existing newlines are honoured as paragraph breaks. Returns `[]` for empty
+ * input so callers can splice the result without an emptiness branch.
+ */
+export function wrapToRows(text, width) {
+    if (typeof text !== 'string' || text.length === 0)
+        return [];
+    const limit = Math.max(1, Math.floor(width));
+    const rows = [];
+    for (const paragraph of text.split('\n')) {
+        if (paragraph.trim().length === 0) {
+            // A blank line in the source is a deliberate separator; keep it as a row
+            // rather than collapsing it, or the summary and the steps run together.
+            rows.push('');
+            continue;
+        }
+        rows.push(...wrapParagraph(paragraph, limit));
+    }
+    return rows;
+}
+function wrapParagraph(paragraph, limit) {
+    const rows = [];
+    let current = '';
+    for (const word of paragraph.split(/\s+/).filter((w) => w.length > 0)) {
+        if (word.length > limit) {
+            // Flush what we have, then chop the over-long token into full-width
+            // pieces. Its tail becomes the new `current` so the next word can still
+            // join it.
+            if (current.length > 0) {
+                rows.push(current);
+                current = '';
+            }
+            let rest = word;
+            while (rest.length > limit) {
+                rows.push(rest.slice(0, limit));
+                rest = rest.slice(limit);
+            }
+            current = rest;
+            continue;
+        }
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= limit) {
+            current = `${current} ${word}`;
+        }
+        else {
+            rows.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0)
+        rows.push(current);
+    return rows;
+}

package/dist/ui/overlays/HelpOverlay.js

@@ -7,6 +7,7 @@ function keyRows(times) {
         ['Enter', 'Submit (idle) / queue steering (running); re-pins to the newest output'],
         ['Alt+Enter / Shift+Enter', 'Insert newline'],
         ['Esc', 'Abort run / close overlay'],
+        ['Shift+Tab', 'Toggle plan mode (same as /plan)'],
         [`Ctrl+C ${times}2`, 'Exit'],
         ['Ctrl+L', 'Redraw the frame'],
         ['Ctrl+T', 'Toggle thinking blocks'],
@@ -19,6 +20,7 @@ const COMMANDS = [
     ['/help', 'Show this help'],
     ['/model', 'Open the model picker'],
     ['/settings', 'Open the settings screen'],
+    ['/plan [on|off|status]', 'Toggle plan mode (same as Shift+Tab)'],
     ['/theme <name>', 'auto | warm | cool | light'],
     ['/thinking <level>', 'Set thinking level'],
     ['/tools', 'List active tools'],
@@ -41,6 +43,14 @@ const SKILL_ROWS = [
     ['/<skill-name> [args]', 'Run a skill directly ($ARGUMENTS / $1..$9)'],
     ['skill / skill_install', 'Tools the model uses to load and install skills'],
 ];
+const PLAN_ROWS = [
+    ['Shift+Tab / /plan', 'Switch between BUILD (do it now) and PLAN (research first)'],
+    ['In PLAN mode', 'write_file, edit_file, bash, skill_install and skill_create are refused'],
+    ['bash', 'Refused in full, including git status - use read_file / glob / grep'],
+    ['ask_user', 'The agent asks 1-5 multiple-choice questions; Enter takes the recommendation'],
+    ['submit_plan', 'The agent submits a plan: a approve, r revise, Esc dismiss'],
+    ['--plan / --no-plan', 'Start a session in a given mode (also ARAGON_PLAN=1)'],
+];
 /** Build the overlay's rows. Exported so `app.test.tsx` can count them. */
 export function helpRows(theme, caps) {
     const glyphs = pickGlyphs(caps);
@@ -53,6 +63,9 @@ export function helpRows(theme, caps) {
     rows.push(section('Slash commands'));
     for (const [c, d] of COMMANDS)
         rows.push(pair(c, d));
+    rows.push(section('Plan mode'));
+    for (const [c, d] of PLAN_ROWS)
+        rows.push(pair(c, d));
     rows.push(section('Skills'));
     for (const [c, d] of SKILL_ROWS)
         rows.push(pair(c, d));

package/dist/ui/overlays/PlanReviewOverlay.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PlanReviewOverlay — the reviewable card `submit_plan` renders (plan-mode §6.6).
+ *
+ * `OverlayFrame` MODE A (`rows`), because a 20-step plan must scroll and mode A
+ * is the only mode with a position indicator.
+ *
+ * MODE A SLICES BY ELEMENT, SO THE PROSE IS PRE-WRAPPED. `sliceWindow` counts
+ * elements, not lines, and each element must be exactly one row. The summary
+ * runs to 600 characters and a step detail to 400 — handing either over as a
+ * single `<Text>` would render the whole paragraph as one truncated line and
+ * make the frame's `1-14/22` a false statement. `wrapToRows` is what keeps the
+ * count honest.
+ *
+ * ACTIONS LIVE IN THE FRAME HINT, NOT IN `rows`. Mode A slices `rows`; an action
+ * row placed there would scroll off exactly when a long plan needs it most.
+ * Single-key actions also avoid a second selection cursor competing with the
+ * scroll cursor.
+ *
+ * `Esc` IS NOT HANDLED HERE, and neither is any resolution of the pending
+ * request: `App` owns Esc, and the bridge's `settle()` is the only place a human
+ * request is answered (R-P12). That holds in the revise sub-state too, which is
+ * why the way back from the feedback field is `<-` rather than `Esc` (R2-P1-2).
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import type { NormalizedPlan } from '../../tools/human-input.js';
+export type PlanVerdict = {
+    decision: 'approved' | 'revise';
+    feedback: string;
+};
+interface PlanReviewOverlayProps {
+    plan: NormalizedPlan;
+    maxRows: number;
+    cols: number;
+    scrollOffset: number;
+    onScrollClamp: (offset: number) => void;
+    theme: Theme;
+    caps: TermCapabilities;
+    onVerdict: (verdict: PlanVerdict) => void;
+}
+export declare function PlanReviewOverlay({ plan, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onVerdict, }: PlanReviewOverlayProps): React.ReactElement;
+/**
+ * Flatten the plan into one-row elements.
+ *
+ * Exported for `plan-mode.test.ts`, which asserts that a 600-character summary
+ * really does become many rows rather than one truncated line (P1-3).
+ */
+export declare function buildPlanRows(plan: NormalizedPlan, width: number, theme: Theme, bullet: string): React.ReactElement[];
+export {};

package/dist/ui/overlays/PlanReviewOverlay.js

@@ -0,0 +1,117 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * PlanReviewOverlay — the reviewable card `submit_plan` renders (plan-mode §6.6).
+ *
+ * `OverlayFrame` MODE A (`rows`), because a 20-step plan must scroll and mode A
+ * is the only mode with a position indicator.
+ *
+ * MODE A SLICES BY ELEMENT, SO THE PROSE IS PRE-WRAPPED. `sliceWindow` counts
+ * elements, not lines, and each element must be exactly one row. The summary
+ * runs to 600 characters and a step detail to 400 — handing either over as a
+ * single `<Text>` would render the whole paragraph as one truncated line and
+ * make the frame's `1-14/22` a false statement. `wrapToRows` is what keeps the
+ * count honest.
+ *
+ * ACTIONS LIVE IN THE FRAME HINT, NOT IN `rows`. Mode A slices `rows`; an action
+ * row placed there would scroll off exactly when a long plan needs it most.
+ * Single-key actions also avoid a second selection cursor competing with the
+ * scroll cursor.
+ *
+ * `Esc` IS NOT HANDLED HERE, and neither is any resolution of the pending
+ * request: `App` owns Esc, and the bridge's `settle()` is the only place a human
+ * request is answered (R-P12). That holds in the revise sub-state too, which is
+ * why the way back from the feedback field is `<-` rather than `Esc` (R2-P1-2).
+ */
+import { useState } from 'react';
+import { Text, useInput } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { OverlayFrame } from '../layout/OverlayFrame.js';
+import { wrapToRows } from '../layout/wrap-rows.js';
+/** The frame's border plus its one-column padding on each side. */
+const FRAME_CHROME_COLS = 4;
+export function PlanReviewOverlay({ plan, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onVerdict, }) {
+    const glyphs = pickGlyphs(caps);
+    const [feedback, setFeedback] = useState(null);
+    useInput((input, key) => {
+        if (key.escape)
+            return; // App owns dismiss.
+        if (feedback !== null) {
+            if (key.return) {
+                onVerdict({ decision: 'revise', feedback: feedback.trim() });
+                return;
+            }
+            // THE WAY BACK TO THE CARD, and the reason it is `<-` and not `Esc`:
+            // `App` owns Esc here and settles the pending request with it, so a second
+            // Esc consumer in this overlay would be the `ConfirmDialog` double-resolve
+            // pattern R-P12 exists to keep out. `QuestionOverlay` already spends `<-`
+            // on "back", so this costs no key ownership. Without it the field is a
+            // one-way door — it consumes printable input and Backspace, and the only
+            // other exit throws the whole review away (R2-P1-2).
+            if (key.leftArrow) {
+                setFeedback(null);
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setFeedback(feedback.slice(0, -1));
+                return;
+            }
+            if (input && !key.ctrl && !key.meta && !key.tab)
+                setFeedback(feedback + input);
+            return;
+        }
+        if (input === 'a' || input === 'A')
+            onVerdict({ decision: 'approved', feedback: '' });
+        else if (input === 'r' || input === 'R')
+            setFeedback('');
+    });
+    const width = Math.max(20, cols - FRAME_CHROME_COLS);
+    const rows = buildPlanRows(plan, width, theme, glyphs.bullet);
+    if (feedback !== null) {
+        // `esc dismiss`, NOT "esc back to the plan": `App` owns Esc for this overlay
+        // (R-P12) and settles the pending request with `null`, so Esc throws the
+        // whole review away from either sub-state. `<-` is the route back to the
+        // card, which is why it is named here too.
+        const feedbackHint = `${glyphs.enterKey} send ${glyphs.midDot} ${glyphs.arrowLeft} back ${glyphs.midDot} esc dismiss`;
+        return (_jsxs(OverlayFrame, { title: "What should change?", hint: feedbackHint, maxRows: maxRows, cols: cols, theme: theme, caps: caps, children: [_jsx(Text, { wrap: "truncate", color: theme.muted, children: "The agent revises the plan and submits it again." }), _jsxs(Text, { wrap: "truncate", children: [_jsxs(Text, { color: theme.primary, bold: true, children: [glyphs.caret, ' '] }), feedback.length > 0 ? (_jsx(Text, { children: feedback })) : (_jsx(Text, { color: theme.muted, children: "e.g. use the existing session store instead" })), _jsx(Text, { inverse: true, children: " " })] })] }));
+    }
+    return (_jsx(OverlayFrame, { title: "Review plan", hint: `a approve ${glyphs.midDot} r revise ${glyphs.midDot} esc dismiss ${glyphs.midDot} ${glyphs.arrowUp}${glyphs.arrowDown} scroll`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
+}
+/**
+ * Flatten the plan into one-row elements.
+ *
+ * Exported for `plan-mode.test.ts`, which asserts that a 600-character summary
+ * really does become many rows rather than one truncated line (P1-3).
+ */
+export function buildPlanRows(plan, width, theme, bullet) {
+    const rows = [];
+    let key = 0;
+    const push = (node, color, bold) => {
+        rows.push(_jsx(Text, { wrap: "truncate", color: color, bold: bold, children: node }, `p${key++}`));
+    };
+    push(plan.title, theme.assistant, true);
+    for (const line of wrapToRows(plan.summary, width))
+        push(line || ' ', theme.muted);
+    push(' ');
+    push('Steps', theme.accent, true);
+    plan.steps.forEach((step, i) => {
+        const number = String(i + 1).padStart(2, ' ');
+        push(`${number}  ${step.title}`);
+        for (const line of wrapToRows(step.detail, Math.max(10, width - 4))) {
+            push(`    ${line}`, theme.muted);
+        }
+    });
+    const section = (label, items) => {
+        if (items.length === 0)
+            return;
+        push(' ');
+        push(label, theme.accent, true);
+        for (const item of items) {
+            for (const line of wrapToRows(`${bullet} ${item}`, width))
+                push(line, theme.muted);
+        }
+    };
+    section('Files', plan.filesTouched);
+    section('Risks', plan.risks);
+    section('Open questions', plan.openQuestions);
+    return rows;
+}