@aragon-agent/cli 0.5.3 → 0.5.6

package/dist/agent/system-prompt.d.ts

@@ -53,6 +53,14 @@ export interface SystemPromptParams {
      * mixing them a one-character mistake.
      */
     subagentBlock?: string;
+    /**
+     * The rendered `<todo_planning>` block, or `''` (todo-plan-execution §3.7).
+     *
+     * Spliced conditionally exactly as `skillsBlock`, the plan block and
+     * `teamBlock` are, which is what keeps C-10 / I-5 true: `todo.enabled: false`
+     * (and `--no-todo`) produce the pre-todo prompt BYTE FOR BYTE.
+     */
+    todoBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -39,6 +39,7 @@ export function buildSystemPrompt(params) {
         : '';
     const teamBlock = params.teamBlock ?? '';
     const subagentBlock = params.subagentBlock ?? '';
+    const todoBlock = params.todoBlock ?? '';
     return [
         'You are AragonAgent, an autonomous coding assistant operating inside a terminal (TUI).',
         'You help the user accomplish software-engineering tasks by reasoning step by step and using the provided tools.',
@@ -54,6 +55,7 @@ export function buildSystemPrompt(params) {
         ...(planBlock ? ['', planBlock] : []),
         ...(teamBlock ? ['', teamBlock] : []),
         ...(subagentBlock ? ['', subagentBlock] : []),
+        ...(todoBlock ? ['', todoBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

package/dist/cli.js

@@ -27,7 +27,7 @@ import { LOG_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, applyLogConfigSet, applyTeam
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
-import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isAdapterProvider, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, } from './config/schema.js';
+import { ADAPTER_PROVIDERS, clampDensity, clampTheme, clampThinkingLevel, clampAskRounds, clampHumanTimeout, clampSkillsIntegrity, clampSkillsToolPolicy, clampTranscriptWindow, coercePositiveInt, isAdapterProvider, parseMaxTokensInput, DEFAULT_MAX_TOKENS, DEFAULT_PLAN_HUMAN_TIMEOUT_MS, DEFAULT_PLAN_MAX_ASK_ROUNDS, DEFAULT_SKILLS_CONFIG, } from './config/schema.js';
 import { makeGetApiKey } from './config/load.js';
 import { AgentController, DENY_ALL_APPROVAL } from './agent/controller.js';
 import { runSkillsCommand } from './skills/cli-commands.js';
@@ -86,6 +86,17 @@ function toFlags(opts) {
         // reach `CliFlags` and are inert, with no compile error and no runtime error.
         team: opts.team,
         teamMax: opts.teamMax,
+        // Site three of three for `--todo` / `--todo-panel`, and the one this
+        // package has now paid for twice (`mouse` P1-2, `team` P1-4): a flag needs
+        // the `.option()` declaration below, a field on `CliFlags`, AND a line here.
+        // Miss this one and the flag is inert with no compile error and no runtime
+        // error.
+        todo: opts.todo,
+        todoPanel: opts.todoPanel,
+        // Site three of three for `--todo-follow` as well (todo-plan-followthrough
+        // C-9). A value flag is no less inert than a boolean one when this line is
+        // missing.
+        todoFollow: opts.todoFollow,
         // `--verbose` is just a shorthand for `--log-level debug`; an explicit
         // `--log-level` still wins, so the two can be combined without surprise.
         logLevel: opts.logLevel ?? (opts.verbose ? 'debug' : undefined),
@@ -120,12 +131,21 @@ function makeController(flags, opts = { interactive: true }) {
     // resolved a bootstrap level — it ran before commander and before `.env` were
     // readable — and without this hand-off the fully resolved one never applies.
     getLogger().reconfigure(config.log);
+    // Whether this session could EVER show the todo rail (todo-plan-execution
+    // §3.7 / P1-6). It varies ONE sentence of `<todo_planning>`; `decideRenderMode`
+    // is pure and `runInteractive` calls it again with the same inputs, so
+    // computing it here rather than threading it back costs nothing and keeps the
+    // controller's construction self-contained.
+    const todoPanelCapable = opts.interactive &&
+        decideRenderMode({ fullscreen: config.fullscreen }, process.env, process.stdout) ===
+            'fullscreen';
     const confirmBridge = { handler: null };
     // `cancelPending` is replaced by the App's own implementation on mount; this
     // no-op keeps the object total so nothing has to null-check it.
     const humanInputBridge = { handler: null, cancelPending: () => { } };
     const controller = new AgentController(config, {
         version: VERSION,
+        todoPanelCapable,
         confirm: (req) => confirmBridge.handler ? confirmBridge.handler(req) : Promise.resolve(true),
         approval: opts.interactive
             ? {
@@ -308,7 +328,13 @@ async function runOneShot(flags, prompt, quiet) {
     for (const dir of untrusted) {
         process.stderr.write(`[skills] project skills in ${dir} skipped (untrusted). Run: aragon skills trust ${dir}\n`);
     }
-    const code = await runHeadless(controller, prompt, { quiet });
+    // `followThrough` is read off the REAL controller here rather than through
+    // `HeadlessController`, which is deliberately the minimal surface a test can
+    // satisfy with an object literal (todo-plan-followthrough §3.6).
+    const code = await runHeadless(controller, prompt, {
+        quiet,
+        followThrough: controller.getTodoConfig().followThrough,
+    });
     // Flushed HERE and not inside `runHeadless`: that module is deliberately
     // injectable (its own controller interface, its own stdout/stderr) and has an
     // early `return 2`, so a singleton dependency in there would be both a new
@@ -397,6 +423,29 @@ const CONFIG_SET_KEYS = new Set([
     // still printing `Set team.enabled = false`.
     ...TEAM_CONFIG_SET_KEYS,
 ]);
+/**
+ * `aragon config set maxTokens <n|auto|default>`.
+ *
+ * REJECTS nonsense rather than clamping it, unlike `theme` and `thinkingLevel`.
+ * Those two clamp because their bad values are out-of-VOCABULARY; here a
+ * non-numeric argument is almost always a typo for a number the user meant, and
+ * storing 64000 for `3200O` would quietly discard their intent. An out-of-RANGE
+ * number is still clamped, in both directions, by the store's single gate.
+ */
+function runConfigSetMaxTokens(value) {
+    const raw = value.trim().toLowerCase();
+    const parsed = raw === 'default'
+        ? { kind: 'value', value: DEFAULT_MAX_TOKENS, clamped: false }
+        : parseMaxTokensInput(value);
+    if (parsed.kind === 'invalid') {
+        process.stderr.write(`Invalid maxTokens "${value}". Use a number, "auto", or "default".\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const stored = parsed.kind === 'auto' ? null : parsed.value;
+    const merged = updatePersistedConfig({ maxTokens: stored });
+    process.stdout.write(`Set maxTokens = ${merged.maxTokens ?? 'auto'}\n`);
+}
 function runConfigSet(key, value) {
     if (!CONFIG_SET_KEYS.has(key)) {
         process.stderr.write(`Unknown config key "${key}". Known keys: ${[...CONFIG_SET_KEYS].join(', ')}.\n`);
@@ -410,6 +459,13 @@ function runConfigSet(key, value) {
         process.stdout.write(`Set ${key} = ${value}\n`);
         return;
     }
+    // Handled ahead of the switch because it needs to echo the STORED value, not
+    // the typed one: `config set maxTokens 900000` must not report a number that
+    // was never written. Same reason `team.*` has its own branch.
+    if (key === 'maxTokens') {
+        runConfigSetMaxTokens(value);
+        return;
+    }
     const teamPatch = applyTeamConfigSet(key, value);
     if (teamPatch) {
         // The written value is echoed from the CLAMPED result rather than from the
@@ -434,9 +490,6 @@ function runConfigSet(key, value) {
         case 'thinkingLevel':
             patch.thinkingLevel = clampThinkingLevel(value, 'off');
             break;
-        case 'maxTokens':
-            patch.maxTokens = coerceMaxTokens(value) ?? null;
-            break;
         case 'theme':
             patch.theme = clampTheme(value, 'auto');
             break;
@@ -540,7 +593,7 @@ function buildProgram() {
         .option('--base-url <url>', 'Override the provider base URL')
         .option('--api-key <key>', 'One-shot API key override (not persisted)')
         .option('--thinking <level>', 'off|minimal|low|medium|high|xhigh')
-        .option('--max-tokens <n>', 'Output token cap')
+        .option('--max-tokens <n|auto>', 'Output token cap: a number, or "auto" for the model ceiling (default 64000)')
         .option('--cwd <dir>', 'Working directory for tools')
         .option('--confirm', 'Confirm each mutating tool call')
         .option('--tool-timeout <ms>', 'Per-tool executor ceiling (default 180000)')
@@ -575,6 +628,19 @@ function buildProgram() {
         .option('--team', 'Enable team subagents for this session (the default)')
         .option('--no-team', 'Disable team subagents (the task tool is not registered at all)')
         .option('--team-max <n>', 'Max subagents per dispatch for this run (1-10)')
+        // BOTH PAIRS, positive first (todo-plan-execution §4.3 / P1-8). `--todo` is
+        // the `--team` story verbatim; `--todo-panel` needs the pair for a second
+        // reason on top of it — `panel` is PERSISTED, so a lone `--no-todo-panel`
+        // would make commander default `opts.todoPanel` to `true` and silently
+        // overwrite a stored `panel: false` on every run that passed no flag.
+        .option('--todo', 'Enable todo planning for this session (the default)')
+        .option('--no-todo', 'Disable todo planning (the todo_write tool is not registered at all)')
+        .option('--todo-panel', 'Show the todo plan in a right-hand rail (the default)')
+        .option('--no-todo-panel', 'Keep todo planning but do not render the rail')
+        // NOT A PAIR, and it does not need to be: a value flag is absent unless
+        // passed, so `!== undefined` in `resolveTodoConfig` already distinguishes it
+        // from silence. An unrecognized mode is clamped to `notify`, not rejected.
+        .option('--todo-follow <mode>', 'What to do when a run ends with unfinished steps: notify (default) | auto | off')
         .option('--no-skills', 'Disable the skill system entirely (no catalog, no skill tools)')
         .option('--skill <name>', 'Force-load a skill at Level 2 for this run (repeatable)', (value, previous = []) => [...previous, value])
         .option('--skills-yes', 'Approve skill installs for this run (CI / headless)')

package/dist/commands/builtins.d.ts

@@ -1,7 +1,7 @@
 /**
  * Built-in slash commands (spec §5.2):
- * /help /model /settings /thinking /tools /clear /reset /cwd /save /resume
- * /copy /exit (/quit).
+ * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
+ * /resume /copy /exit (/quit).
  */
 import { CommandRegistry } from './registry.js';
 export declare function registerBuiltinCommands(registry: CommandRegistry): void;

package/dist/commands/builtins.js

@@ -1,13 +1,16 @@
 /**
  * Built-in slash commands (spec §5.2):
- * /help /model /settings /thinking /tools /clear /reset /cwd /save /resume
- * /copy /exit (/quit).
+ * /help /model /settings /thinking /max-tokens /tools /clear /reset /cwd /save
+ * /resume /copy /exit (/quit).
  */
 import { spawn } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import process from 'node:process';
-import { clampThinkingLevel, clampTheme, isThemeName, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
+import { resolveOutputTokens } from '@aragon-agent/core';
+import { clampThinkingLevel, clampTheme, isThemeName, parseMaxTokensInput, DEFAULT_MAX_TOKENS, LEGACY_DARK_THEME, THEME_NAMES, THINKING_LEVELS, } from '../config/schema.js';
+import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
+import { buildContinuationMessage } from '../todo/follow-through.js';
 import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
@@ -43,6 +46,53 @@ const COMMANDS = [
             ctx.toast('info', `Thinking level set to "${clamped}".`);
         },
     },
+    {
+        name: 'max-tokens',
+        description: 'Show or set the output token cap (<n> | auto | default)',
+        /**
+         * Exists next to the settings screen for the reason `/theme` and `/plan` do:
+         * the slash palette is the discoverable surface, and this is one keystroke
+         * instead of five arrow presses.
+         *
+         * The no-argument branch reports the EFFECTIVE cap, not just the setting.
+         * "I set 64000" and "this model will produce 8192" are different facts, and
+         * only the second one explains a truncated answer.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim();
+            const cfg = ctx.controller.getConfig();
+            if (!arg) {
+                const resolution = resolveOutputTokens({
+                    providerId: cfg.provider,
+                    modelId: cfg.model,
+                    ...(cfg.maxTokens !== undefined ? { requested: cfg.maxTokens } : {}),
+                });
+                const setting = cfg.maxTokens === undefined ? 'auto' : String(cfg.maxTokens);
+                const why = resolution.clampedBy === 'ceiling' ? ` (${cfg.model} ceiling)` : '';
+                ctx.notify('info', `Max tokens: ${setting}. Effective for ${cfg.provider}:${cfg.model}: ` +
+                    `${resolution.value}${why}.\nUse /max-tokens <n|auto|default>.`);
+                return;
+            }
+            const parsed = arg.toLowerCase() === 'default'
+                ? { kind: 'value', value: DEFAULT_MAX_TOKENS, clamped: false }
+                : parseMaxTokensInput(arg);
+            if (parsed.kind === 'invalid') {
+                // Change NOTHING on a typo: silently resolving it to a default would
+                // discard the number the user meant to type.
+                ctx.notify('warn', `Invalid value "${arg}" - use /max-tokens <n|auto|default>.`);
+                return;
+            }
+            if (parsed.kind === 'auto') {
+                ctx.controller.setMaxTokens(undefined);
+                ctx.persistConfig({ maxTokens: null });
+                ctx.toast('success', 'Max tokens: auto (per-model ceiling).');
+                return;
+            }
+            ctx.controller.setMaxTokens(parsed.value);
+            ctx.persistConfig({ maxTokens: parsed.value });
+            ctx.toast('success', `Max tokens set to ${parsed.value}.`);
+        },
+    },
     {
         name: 'theme',
         description: 'Switch the color theme (auto|warm|cool|light)',
@@ -172,6 +222,160 @@ const COMMANDS = [
             ctx.notify('warn', `Unknown argument "${verb}" - use /team [status|on|off|max <n>].`);
         },
     },
+    {
+        name: 'todo',
+        description: 'Todo planning: status | on | off | panel on|off | follow <mode> | clear | continue',
+        /**
+         * `/todo on` CANNOT turn planning on in a session that started with
+         * `--no-todo`, for the reason `/team on` above records at length: the tool
+         * array is built ONCE and rebuilding it is forbidden (C-1), while
+         * `rebuildSystemPrompt()` IS a live path — so the naive reading produces a
+         * session where the model is told about a `todo_write` that was never
+         * registered.
+         *
+         * TWO CALLS, IN THIS ORDER, FOR BOTH `on|off` AND `panel on|off`, and
+         * neither pair is optional:
+         *
+         *   `setTodoEnabled`  re-splices `<todo_planning>` (P1-1). Without it the
+         *                     block survives `/todo off` and every call comes back
+         *                     refused while the instructions to keep calling are
+         *                     still in the model's context.
+         *   `setTodoConfig`   updates the object `App` reads at RENDER time (P1-2).
+         *                     `persistConfig` only writes the file, so without it
+         *                     `/todo panel off` reports success and changes nothing
+         *                     until the next launch.
+         *   `persistConfig`   is what survives the session, in both cases.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim().toLowerCase();
+            const [verb, value] = arg.split(/\s+/, 2);
+            const controller = ctx.controller;
+            if (!verb || verb === 'status') {
+                const snapshot = controller.getTodoSnapshot();
+                const state = !controller.isTodoRegistered()
+                    ? 'off for this session (started with --no-todo)'
+                    : controller.isTodoEnabled()
+                        ? 'on'
+                        : 'off';
+                const todoCfg = controller.getTodoConfig();
+                const panel = todoCfg.panel ? 'on' : 'off';
+                // THE COUNTERS APPEAR ONLY IN `auto` MODE (§4.3): printing `0/25` under
+                // `notify` would advertise a budget nothing is spending.
+                const follow = todoCfg.followThrough === 'auto'
+                    ? `auto (${ctx.followBudget?.used ?? 0}/` +
+                        `${TODO_FOLLOW_LIMITS.maxAutoContinuesPerList} used)`
+                    : todoCfg.followThrough;
+                if (!snapshot) {
+                    ctx.notify('info', `No todo list. Todo planning: ${state}. Panel: ${panel}. ` +
+                        `Follow-through: ${follow}.`);
+                    return;
+                }
+                const active = snapshot.activeIndex >= 0
+                    ? ` In progress: "${snapshot.items[snapshot.activeIndex]?.content ?? ''}".`
+                    : '';
+                ctx.notify('info', `Todos: ${snapshot.doneCount}/${snapshot.total} done.${active} Panel: ${panel}. ` +
+                    `Follow-through: ${follow}.`);
+                return;
+            }
+            if (verb === 'on' || verb === 'off') {
+                const enabled = verb === 'on';
+                // A PARTIAL `todo` section, safe only because `updatePersistedConfig`
+                // deep-merges it — the contract §4.2 spells out in full.
+                ctx.persistConfig({ todo: { enabled } });
+                if (!controller.isTodoRegistered()) {
+                    ctx.notify('info', enabled
+                        ? 'Todo planning is off for this session (started with --no-todo). Saved for next launch.'
+                        : 'Todo planning is already off for this session. Saved for next launch.');
+                    return;
+                }
+                controller.setTodoEnabled(enabled);
+                ctx.toast('success', `Todo planning ${enabled ? 'on' : 'off'}.`);
+                return;
+            }
+            if (verb === 'panel') {
+                if (value !== 'on' && value !== 'off') {
+                    ctx.notify('warn', 'Usage: /todo panel <on|off>');
+                    return;
+                }
+                const panel = value === 'on';
+                controller.setTodoConfig({ panel });
+                ctx.persistConfig({ todo: { panel } });
+                ctx.toast('success', `Todo panel ${panel ? 'on' : 'off'}.`);
+                return;
+            }
+            if (verb === 'follow') {
+                if (value !== 'notify' && value !== 'auto' && value !== 'off') {
+                    ctx.notify('warn', 'Usage: /todo follow <notify|auto|off>');
+                    return;
+                }
+                const followThrough = value;
+                // THE SAME TWO-CALL RULE AS `panel` ABOVE, minus `setTodoEnabled`:
+                // nothing in `<todo_planning>` mentions follow-through (D-3), so
+                // `todoEnabled` has no bearing here.
+                //
+                // `setTodoConfig` REBUILDS THE SYSTEM PROMPT UNCONDITIONALLY
+                // (`controller.ts`), and that is fine and must be left alone: the
+                // rebuild is idempotent for this key (the block does not mention
+                // follow-through, so the output is byte-identical), it costs one string
+                // composition PER COMMAND INVOCATION rather than per turn, and
+                // `setTodoConfig` is the ONLY method that updates the object `App` reads
+                // at decision time. A branch that bypassed it to avoid the rebuild would
+                // trade a free string concatenation for the exact "reports success,
+                // changes nothing" bug the method exists to prevent (P1-1 / P2-10).
+                controller.setTodoConfig({ followThrough });
+                ctx.persistConfig({ todo: { followThrough } });
+                ctx.toast('success', followThrough === 'auto'
+                    ? `Follow-through: auto (up to ${TODO_FOLLOW_LIMITS.maxAutoContinuesPerList} ` +
+                        'continuations per plan).'
+                    : `Follow-through: ${followThrough}.`);
+                return;
+            }
+            if (verb === 'clear') {
+                // REFUSED MID-RUN, which bounds the model/panel disagreement window to
+                // zero (§1.2): between turns the model's next `todo_write` is a full
+                // replacement anyway.
+                if (controller.isRunning()) {
+                    ctx.notify('warn', 'Cannot clear the todo list while a run is in progress.');
+                    return;
+                }
+                if (!controller.getTodoSnapshot()) {
+                    ctx.notify('info', 'No todo list.');
+                    return;
+                }
+                controller.clearTodos();
+                ctx.toast('info', 'Todo list cleared.');
+                return;
+            }
+            if (verb === 'continue') {
+                // REFUSED WHILE RUNNING TOO (P2-7). `ctx.submit` is the App's
+                // `submitMessage`, which routes to `controller.steer()` when the status
+                // is `running` — so the un-refused form would inject "continue the
+                // remaining items" into the run that is already doing exactly that.
+                if (controller.isRunning()) {
+                    ctx.notify('warn', 'Already running.');
+                    return;
+                }
+                const snapshot = controller.getTodoSnapshot();
+                if (!snapshot || snapshot.doneCount >= snapshot.total) {
+                    ctx.notify('info', 'Nothing left to continue.');
+                    return;
+                }
+                // THE SAME FUNCTION THE AUTO PATH USES, which is what keeps the two from
+                // drifting (D-11 / D-12). Round 1's fixed string "Continue with the
+                // remaining todo items." was a REFERENCE to a `todo_write` call that a
+                // long session may have scrolled out of view.
+                //
+                // `{ userInitiated: false }`: the user typed `/todo continue`, which the
+                // slash history already has. Putting this canned paragraph under the
+                // composer's up-arrow as well would be the same event recorded twice, in
+                // the more verbose of the two forms (AC-17).
+                ctx.submit(buildContinuationMessage(snapshot), { userInitiated: false });
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use ` +
+                '/todo [status|on|off|panel on|off|follow <mode>|clear|continue].');
+        },
+    },
     {
         name: 'expand',
         description: 'Expand / collapse a recent tool card (default: last)',
@@ -248,6 +452,9 @@ const COMMANDS = [
                     },
                     messages: ctx.controller.getMessages(),
                     entries: ctx.state.entries,
+                    // `/resume` restores `messages`, so the belief that justifies the
+                    // panel comes back — and the panel has to come back with it (§3.13).
+                    todos: ctx.controller.getTodoSnapshot()?.items ?? [],
                 });
                 ctx.notify('info', `Saved session to ${path}`);
             }
@@ -264,6 +471,13 @@ const COMMANDS = [
                 const path = resolveSessionPath(ctx.args, ctx.controller.getCwd());
                 const session = loadSession(path);
                 ctx.controller.replaceMessages(session.messages);
+                // IN THE SAME `try`, IMMEDIATELY AFTER `replaceMessages`, so a malformed
+                // file fails the whole resume rather than half of it — and AN ABSENT
+                // `todos` CLEARS RATHER THAN SKIPPING (P0-2 / D-22). `replaceMessages`
+                // has just discarded the conversation the current list belonged to, so
+                // leaving the rail up produces a panel that disagrees with the model,
+                // which §1.2 ranks below having no panel at all.
+                ctx.controller.restoreTodos(session.todos ?? []);
                 ctx.dispatch({ type: 'restoreEntries', entries: session.entries });
                 if (session.model?.providerId && session.model?.modelId) {
                     ctx.controller.setModel(session.model.providerId, session.model.modelId, session.model.baseUrl);

package/dist/commands/registry.d.ts

@@ -6,6 +6,7 @@ import type { AgentController } from '../agent/controller.js';
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
 import type { PersistedConfig } from '../config/schema.js';
+import type { FollowThroughBudget } from '../todo/follow-through.js';
 export interface CommandContext {
     /** Raw argument string after the command word (may be empty). */
     args: string;
@@ -24,8 +25,33 @@ export interface CommandContext {
      * idle). Dynamic skill commands need this: they turn `/pdf-forms a.pdf` into a
      * real user message. It is a separate entry point from `handleSubmit` on
      * purpose — routing back through that would re-enter slash-command parsing.
+     *
+     * `userInitiated: false` suppresses `recordPrompt` (todo-plan-followthrough
+     * C-12 / AC-17), which skips TWO things and both are wanted: the prompt-history
+     * append, and the `submitCount` bump that drives the composer's hint fade. A
+     * canned string the user did not type belongs in neither. The parameter is
+     * named for the CAUSE rather than for one of its effects, because a flag
+     * called `recordHistory` would have made the second one look like a bug.
+     *
+     * WIDENING THIS SIGNATURE IS THE WHOLE REASON THIS FILE IS IN THE CHANGE PLAN
+     * (P1-5): `builtins.ts` reaches `submitMessage` only through here, so
+     * `/todo continue` cannot opt out of prompt history without it.
+     */
+    submit: (text: string, opts?: {
+        userInitiated?: boolean;
+    }) => void;
+    /**
+     * The live auto-continue budget, for `/todo status`'s `(2/25 used)` clause
+     * (todo-plan-followthrough §4.3).
+     *
+     * READ-ONLY AND OPTIONAL. It lives in an `App` ref rather than on the
+     * controller or in `ViewState` (§4.4 / §5.2) because it counts a SESSION'S
+     * INTERACTION WITH THE USER, not the model's plan — so this is the only way a
+     * command can see it, and `makeCtx` is the only place that supplies it.
+     * Optional so the many test contexts that build this object by literal need no
+     * change; absent means the clause degrades to naming the ceiling alone.
      */
-    submit: (text: string) => void;
+    followBudget?: FollowThroughBudget;
     /** Rebuild the system prompt and the dynamic command list after a skill change. */
     refreshSkills: () => void;
     /**

package/dist/config/cli-commands.js

@@ -135,6 +135,20 @@ function maskConfig(config) {
     }
     return { ...config, apiKeys };
 }
+/**
+ * The human-readable label for a value whose raw form would mislead, or
+ * `undefined` to leave the caller's own formatting alone.
+ *
+ * `maxTokens: null` is AUTO, not "unset". Printing a bare `null` reads as a
+ * missing setting and sends the user looking for a bug that is not there.
+ * `get` and `list` format everything else differently (unquoted vs. JSON), so
+ * this deliberately overrides one case rather than replacing both renderers.
+ */
+function displayOverride(key, value) {
+    if (key === 'maxTokens' && value === null)
+        return 'auto';
+    return undefined;
+}
 /** Resolve a flat or one-level-dotted key against the persisted config. */
 function readKey(config, key) {
     const [head, tail] = key.split('.', 2);
@@ -153,10 +167,14 @@ export function runConfigGet(key) {
         process.exitCode = 2;
         return;
     }
-    process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value)}\n`);
+    const shown = displayOverride(key, value)
+        ?? (typeof value === 'string' ? value : JSON.stringify(value));
+    process.stdout.write(`${shown}\n`);
 }
 export function runConfigList(opts = {}) {
     const masked = maskConfig(loadPersistedConfig());
+    // `--json` stays RAW on purpose: it mirrors the file, and a consumer parsing
+    // it must see the `null` that is actually on disk.
     if (opts.json) {
         process.stdout.write(`${JSON.stringify(masked, null, 2)}\n`);
         return;
@@ -168,7 +186,7 @@ export function runConfigList(opts = {}) {
             }
             continue;
         }
-        process.stdout.write(`${key} = ${JSON.stringify(value)}\n`);
+        process.stdout.write(`${key} = ${displayOverride(key, value) ?? JSON.stringify(value)}\n`);
     }
 }
 // ---------------------------------------------------------------------------

package/dist/config/env.d.ts

@@ -5,7 +5,8 @@
  *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
  *     GEMINI_API_KEY.
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
- *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
+ *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
  *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first

package/dist/config/env.js

@@ -5,7 +5,8 @@
  *   - Provider secrets: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY /
  *     GEMINI_API_KEY.
  *   - Overrides: ARAGON_PROVIDER, ARAGON_MODEL, ARAGON_BASE_URL, ARAGON_THINKING,
- *     ARAGON_MAX_TOKENS, ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
+ *     ARAGON_MAX_TOKENS (a number, or `auto` / `0` for the per-model ceiling),
+ *     ARAGON_THEME, ARAGON_MOUSE, ARAGON_PLAN, ARAGON_TEAM,
  *     ARAGON_TEAM_MAX, ARAGON_LOG_LEVEL, ARAGON_LOG_FILE, ARAGON_LOG_DIR.
  *
  * NOT here: `ARAGON_HOME`. It is read when `config/app-paths.ts` is first
@@ -18,7 +19,7 @@ import process from 'node:process';
 import dotenv from 'dotenv';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
 import { clampLogLevel } from '../logging/levels.js';
-import { clampTheme, clampThinkingLevel, coerceMaxTokens, } from './schema.js';
+import { clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, } from './schema.js';
 /**
  * Load a project `.env` from the given directory into `process.env` (existing
  * process env wins — dotenv never overrides already-set variables).
@@ -58,9 +59,20 @@ export function readEnvConfig() {
     if (process.env.ARAGON_THINKING) {
         partial.thinkingLevel = clampThinkingLevel(process.env.ARAGON_THINKING.trim(), 'off');
     }
-    if (process.env.ARAGON_MAX_TOKENS) {
-        const mt = coerceMaxTokens(process.env.ARAGON_MAX_TOKENS);
-        partial.maxTokens = mt ?? null;
+    // `auto` / `0` mean AUTO (`null`); a number is clamped to the accepted range.
+    // Anything else is LEFT ABSENT rather than written as `null`: a typo here used
+    // to become AUTO and silently discard the number in the config file under it,
+    // which is the opposite of what the user asked for.
+    const maxTokens = process.env.ARAGON_MAX_TOKENS?.trim();
+    if (maxTokens !== undefined && maxTokens.length > 0) {
+        if (isAutoToken(maxTokens)) {
+            partial.maxTokens = null;
+        }
+        else {
+            const clamped = clampMaxTokens(maxTokens);
+            if (clamped !== undefined)
+                partial.maxTokens = clamped;
+        }
     }
     if (process.env.ARAGON_THEME) {
         partial.theme = clampTheme(process.env.ARAGON_THEME.trim(), 'auto');
@@ -122,6 +134,49 @@ export function readEnvConfig() {
         if (Object.keys(section).length > 0)
             partial.team = section;
     }
+    // ARAGON_TODO=0 turns todo planning off entirely (no tool, no rail). Parsed by
+    // the POSITIVE list, exactly as ARAGON_FULLSCREEN / ARAGON_MOUSE / ARAGON_PLAN
+    // / ARAGON_TEAM are — NOT by `envBool` below, which uses a negative list. The
+    // two readers disagree on values like `ARAGON_TODO=disable`, and this file
+    // already records that once for team mode.
+    //
+    // There is no `ARAGON_TODO_PANEL`: the panel is a per-machine display
+    // preference, which is what `config.json` is for, and every env var here
+    // exists because a flag and a config file are BOTH unreachable in the channel
+    // it serves (containers, SSH, being spawned by another tool).
+    //
+    // ARAGON_TODO_FOLLOW=notify|auto|off PASSES THAT SAME TEST (D-18), which is
+    // why it exists where `ARAGON_TODO_PANEL` does not: follow-through is exactly
+    // the knob an unattended `-p` run in a container with a fixed entrypoint needs
+    // and can reach no other way.
+    //
+    // ONE ACCUMULATED SECTION, ASSIGNED ONCE — the shape the `team` branch above
+    // already uses, and NOT two `if` blocks each assigning `partial.todo` (P1-4).
+    // THE CAST IS WHAT WOULD MAKE THAT MISTAKE SILENT: a second assignment
+    // compiles clean and drops `enabled`, so `ARAGON_TODO=0 ARAGON_TODO_FOLLOW=auto`
+    // would quietly re-enable the tool the user turned off.
+    const todo = process.env.ARAGON_TODO?.trim().toLowerCase();
+    const todoFollow = process.env.ARAGON_TODO_FOLLOW?.trim().toLowerCase();
+    if ((todo !== undefined && todo.length > 0) ||
+        (todoFollow !== undefined && todoFollow.length > 0)) {
+        // Keyed by `TodoConfig` but VALUED `unknown`, which is what lets the mode be
+        // written through unvalidated (below) while still failing to compile if a
+        // future key is misspelled.
+        const section = {};
+        if (todo !== undefined && todo.length > 0) {
+            section.enabled = todo === '1' || todo === 'true' || todo === 'on' || todo === 'yes';
+        }
+        // Written through unvalidated: `clampTodoConfig` clamps an unrecognized mode
+        // to the default rather than rejecting it, so validating here would be a
+        // second gate that can disagree with the first.
+        if (todoFollow !== undefined && todoFollow.length > 0) {
+            section.followThrough = todoFollow;
+        }
+        // A PARTIAL section, safe only because every consumer deep-merges it — the
+        // same contract `partial.skills`, `partial.log` and `partial.team` rely on.
+        if (Object.keys(section).length > 0)
+            partial.todo = section;
+    }
     const log = readEnvLogConfig();
     if (log)
         partial.log = log;