@aragon-agent/cli 0.5.4 → 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

@@ -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
@@ -602,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.js

@@ -9,6 +9,8 @@ import { isAbsolute, resolve } from 'node:path';
 import process from 'node:process';
 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';
@@ -220,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)',
@@ -296,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}`);
             }
@@ -312,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/env.js

@@ -134,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;

package/dist/config/load.d.ts

@@ -52,6 +52,33 @@ export interface CliFlags {
     team?: boolean;
     /** `--team-max <n>` — override `team.maxSubagents` for this run (still clamped). */
     teamMax?: string | number;
+    /**
+     * `--todo` ⇒ true, `--no-todo` ⇒ false, absent ⇒ undefined
+     * (todo-plan-execution §4.3).
+     */
+    todo?: boolean;
+    /**
+     * `--todo-panel` ⇒ true, `--no-todo-panel` ⇒ false, absent ⇒ undefined.
+     *
+     * DECLARED AS A PAIR, like `--todo` above, and unlike `--no-skills` (P1-8).
+     * `panel` is a PERSISTED setting, so "not passed" has to stay distinguishable
+     * from `true` — otherwise commander's lone-`--no-x` default silently
+     * overwrites a config-file `panel: false` on every run that passes no flag at
+     * all. `--no-skills` escapes the rule only because nothing needs to
+     * distinguish `--skills` from silence.
+     */
+    todoPanel?: boolean;
+    /**
+     * `--todo-follow <mode>` — `notify` | `auto` | `off`
+     * (todo-plan-followthrough §4.2).
+     *
+     * A VALUE FLAG, NOT A PAIR, so commander materializes it only when passed and
+     * the `!== undefined` rule above applies to its presence rather than to a
+     * synthesized `true`. Typed `string` and not `FollowThroughMode`: an
+     * unrecognized value is CLAMPED to the default by `clampTodoConfig`, never
+     * rejected, which is what every other key in this file does.
+     */
+    todoFollow?: string;
     /** `--log-level <lv>` — this run only, never persisted. */
     logLevel?: string;
     /** `--log-file` ⇒ true, `--no-log-file` ⇒ false, absent ⇒ undefined. */

package/dist/config/load.js

@@ -6,7 +6,7 @@
  * legitimately long single tool run can never be watchdog-killed.
  */
 import process from 'node:process';
-import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampTheme, clampThinkingLevel, clampMaxTokens, clampTranscriptWindow, coercePositiveInt, isAutoToken, isSkillsToolPolicyMode, } from './schema.js';
 import { loadDotenv, readEnvConfig, readEnvDisabledSkills } from './env.js';
 import { readConfigFile } from './store.js';
 import { getConfigPath } from './app-paths.js';
@@ -97,6 +97,29 @@ function resolveTeamConfig(flags, env, file) {
             : {}),
     });
 }
+/**
+ * Merge the `todo` section across all four layers (defaults › file › env ›
+ * flags), todo-plan-execution §4.3.
+ *
+ * `!== undefined` ON BOTH FLAGS, and that is the whole point (P1-8). `commander`
+ * materializes a lone `--no-x` as `opts.x = true` when the flag is absent, so a
+ * truthiness check cannot tell `--no-todo-panel` from "not passed" — and both
+ * keys here are persisted, so both need the distinction. This is the same rule
+ * `resolveTeamConfig` above states, one feature later.
+ */
+function resolveTodoConfig(flags, env, file) {
+    return clampTodoConfig({
+        ...DEFAULT_CONFIG.todo,
+        ...(file.todo ?? {}),
+        ...(env.todo ?? {}),
+        ...(flags.todo !== undefined ? { enabled: flags.todo } : {}),
+        ...(flags.todoPanel !== undefined ? { panel: flags.todoPanel } : {}),
+        // `!== undefined` for the third time, though for a value flag the risk is
+        // milder: commander leaves `opts.todoFollow` absent unless it was passed.
+        // Written this way anyway so the three lines read as one rule.
+        ...(flags.todoFollow !== undefined ? { followThrough: flags.todoFollow } : {}),
+    });
+}
 /** Merge the `log` section across all four layers (defaults › file › env › flags). */
 function resolveLogConfig(flags, env, file) {
     const merged = clampLogConfig({
@@ -285,6 +308,7 @@ export function loadConfig(flags = {}) {
         },
         log: resolveLogConfig(flags, env.partial, file),
         team: resolveTeamConfig(flags, env.partial, file),
+        todo: resolveTodoConfig(flags, env.partial, file),
         cwd,
         color,
         colorLevel,

package/dist/config/schema.d.ts

@@ -7,6 +7,7 @@
  */
 import { type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
+import type { FollowThroughMode } from '../todo/types.js';
 /**
  * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
  * registers only three adapters. Running a model whose provider has no adapter
@@ -239,6 +240,40 @@ export declare const DEFAULT_TEAM_CONFIG: TeamConfig;
  * the two disagree would make the panel's `n/m` readout confusing for no gain.
  */
 export declare function clampTeamConfig(raw: unknown): TeamConfig;
+export interface TodoConfig {
+    /** Register `todo_write` at all. Default TRUE. */
+    enabled: boolean;
+    /**
+     * Render the right rail.
+     *
+     * INDEPENDENT OF `enabled` ON PURPOSE (D-16): a screen-reader user wants the
+     * planning discipline without the column, and the prompt block varies one
+     * sentence rather than disappearing (§3.7).
+     */
+    panel: boolean;
+    /**
+     * What happens when a run ends with unfinished steps
+     * (todo-plan-followthrough §4.1). Default `'notify'`, which reproduces round
+     * 1's behaviour byte for byte.
+     *
+     * THE THIRD SCALAR, and it stays a scalar for the reason the section header
+     * above gives: `store.ts` merges this section BY HAND, and both of its merges
+     * spread the whole object (`{ ...DEFAULT_CONFIG.todo, ...(partial.todo ?? {}) }`
+     * and `{ ...current.todo, ...(patch.todo ?? {}) }`), so a third scalar key is
+     * carried automatically and needs no change there. A NESTED field would not
+     * be, and would mean replacing both merges first.
+     */
+    followThrough: FollowThroughMode;
+}
+export declare const DEFAULT_TODO_CONFIG: TodoConfig;
+/**
+ * THE single gate for every todo-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` for the reason
+ * those record: hardening only the read path leaves a bad value on disk that
+ * reverts to the default on every launch, which presents to the user as "my
+ * setting won't stick".
+ */
+export declare function clampTodoConfig(raw: unknown): TodoConfig;
 export interface PersistedConfig {
     version: number;
     provider: string;
@@ -305,6 +340,8 @@ export interface PersistedConfig {
     log: LogConfig;
     /** Team mode. The FOURTH nested object; scalars only (see TeamConfig). */
     team: TeamConfig;
+    /** Todo planning. The FIFTH nested object; scalars only (see TodoConfig). */
+    todo: TodoConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -399,6 +436,16 @@ export interface CliConfig {
      * `/team` flips is a separate flag on the controller.
      */
     team: TeamConfig;
+    /**
+     * Resolved todo-planning settings (todo-plan-execution §4.2).
+     *
+     * `enabled` here decides whether `todo_write` is REGISTERED, which happens
+     * once at construction and can never be undone (C-1). The live on/off switch
+     * `/todo` flips is a separate flag on the controller; `panel` is read at
+     * RENDER time through `controller.getConfig()`, which is why `/todo panel`
+     * must call `setTodoConfig` as well as persisting (P1-2).
+     */
+    todo: TodoConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -312,6 +312,40 @@ export function clampTeamConfig(raw) {
         maxTurnsPerSubagent: clampInt(src.maxTurnsPerSubagent, DEFAULT_TEAM_CONFIG.maxTurnsPerSubagent, TURNS_RANGE),
     };
 }
+export const DEFAULT_TODO_CONFIG = {
+    enabled: true,
+    panel: true,
+    followThrough: 'notify',
+};
+/**
+ * There is no enum helper in this file, so this follows the `isThinkingLevel`
+ * shape already here rather than inventing a second idiom.
+ */
+const FOLLOW_THROUGH_MODES = ['notify', 'auto', 'off'];
+function followMode(value, fallback) {
+    return typeof value === 'string' && FOLLOW_THROUGH_MODES.includes(value)
+        ? value
+        : fallback;
+}
+/**
+ * THE single gate for every todo-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` for the reason
+ * those record: hardening only the read path leaves a bad value on disk that
+ * reverts to the default on every launch, which presents to the user as "my
+ * setting won't stick".
+ */
+export function clampTodoConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        enabled: bool(src.enabled, DEFAULT_TODO_CONFIG.enabled),
+        panel: bool(src.panel, DEFAULT_TODO_CONFIG.panel),
+        // CLAMPED TO THE DEFAULT, NEVER REJECTED — the discipline every other key in
+        // this file follows, and the trade round 1 already made for `--thinking`.
+        // `ARAGON_TODO_FOLLOW=garbage` therefore resolves to `'notify'` and throws
+        // nothing (AC-5).
+        followThrough: followMode(src.followThrough, DEFAULT_TODO_CONFIG.followThrough),
+    };
+}
 export const DEFAULT_CONFIG = {
     version: CONFIG_VERSION,
     provider: 'anthropic',
@@ -340,6 +374,10 @@ export const DEFAULT_CONFIG = {
     skills: DEFAULT_SKILLS_CONFIG,
     log: DEFAULT_LOG_CONFIG,
     team: DEFAULT_TEAM_CONFIG,
+    // The load path's first spread is what supplies the section to a user with no
+    // `todo` key at all, so this line is as required as the two merges in
+    // `store.ts` (P0-1).
+    todo: DEFAULT_TODO_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -14,7 +14,7 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampMaxTokens, clampSkillsConfig, clampTeamConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampMaxTokens, clampSkillsConfig, clampTeamConfig, clampTodoConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -122,6 +122,10 @@ export function loadPersistedConfig() {
         log: clampLogConfig({ ...DEFAULT_CONFIG.log, ...(partial.log ?? {}) }),
         // `team` is the fourth. Same one-level rule, same merge.
         team: clampTeamConfig({ ...DEFAULT_CONFIG.team, ...(partial.team ?? {}) }),
+        // `todo` is the fifth. Same one-level rule, same merge — and this line is
+        // the READ half of the pair that keeps `/todo panel off` from silently
+        // unregistering the tool on the next launch (P0-1 / AC-35).
+        todo: clampTodoConfig({ ...DEFAULT_CONFIG.todo, ...(partial.todo ?? {}) }),
     };
 }
 /**
@@ -168,6 +172,11 @@ export function updatePersistedConfig(patch) {
         // 4` sends `{ team: { maxSubagents: 4 } }`, which a shallow spread would
         // turn into "changing the fan-out width silently reverted every timeout".
         team: clampTeamConfig({ ...current.team, ...(patch.team ?? {}) }),
+        // The fifth section, and its omission is the worst of the five (P0-1):
+        // `/todo panel off` sends `{ todo: { panel: false } }`, which a shallow
+        // spread turns into "turning the panel off silently unregisters the tool",
+        // permanently, from the next launch onward, with nothing anywhere saying so.
+        todo: clampTodoConfig({ ...current.todo, ...(patch.todo ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;