@aragon-agent/cli 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -9,6 +9,35 @@ were written.
 
 ### Added
 
+- **Output token limits that cannot themselves fail a run.** Every model and
+  every provider now defaults to 64000 output tokens, and that number is
+  configurable from the TUI, from a flag, from `ARAGON_MAX_TOKENS`, and by hand
+  in `~/.aragon-agent/config.json`. Leave it alone and it stays 64000.
+
+  What is new is that the number is an *ambition*. `gpt-4o` caps at 16384 and
+  `gemini-1.5-pro` at 8192; sending 64000 to either is an HTTP 400 that ends the
+  turn with a raw provider string in the transcript. The cap is now clamped down
+  to whatever the target model actually accepts, from a per-model table plus
+  whatever the provider's own model list reports. For a model nothing knows — a
+  proxy, a `--base-url` endpoint, something that shipped last week — the request
+  goes out at 64000, and if the provider objects, `aragon` reads the real ceiling
+  out of the error text, repairs the request, sends it exactly once more, and
+  remembers the answer for the rest of the session. One warning line; the run
+  continues.
+
+  Two combinations that were a guaranteed 400 on every request are fixed with
+  it: `--thinking xhigh` asks for a 65536-token budget while Anthropic requires
+  `max_tokens` to be strictly greater than it, and OpenAI's reasoning family
+  (`o1`, `o3`, `gpt-5`) rejects the `max_tokens` parameter name outright in
+  favour of `max_completion_tokens`.
+
+  New surfaces: `/max-tokens [<n>|auto|default]`, which with no argument reports
+  the setting *and* the effective cap for the live model; an `Effective:` line
+  under the settings screen's `Max tokens` field, so a value the model will not
+  honour is visible before you save it; `--max-tokens auto`; and
+  `aragon config set maxTokens <n|auto|default>`, which echoes the value that was
+  actually stored rather than the one you typed.
+
 - **Team subagents.** The agent can now hand independent parts of a job to up to
   five short-lived subagents that run in parallel, then read one combined report
   of what each of them found. It decides for itself whether to delegate, so a
@@ -71,6 +100,14 @@ were written.
 
 ### Changed
 
+- **`"maxTokens": null` in `config.json` now means AUTO** — use each model's own
+  ceiling, never above 64000. It previously resolved to 64000 by accident (the
+  layered resolver skipped `null`), and there was no way to express AUTO through
+  any supported write path. If you have a `null` there today, the only difference
+  is a downward clamp on models whose real ceiling is below 64000 — the direction
+  that prevents failures rather than causing them. Absent still means 64000, and
+  an explicit number still means that number.
+
 - **`config.json` holds settings again.** The prompts you type are no longer
   stored in it. They move to `~/.aragon-agent/prompt-history.jsonl` — one JSON
   object per line, `0600` on POSIX — and the submit counter and the "notice

package/README.md

@@ -60,7 +60,7 @@ aragon --help  | -h             Print help
 | `--base-url <url>` | Override the provider base URL (OpenAI-compatible endpoints) |
 | `--api-key <key>` | One-shot key override (not persisted) |
 | `--thinking <level>` | `off\|minimal\|low\|medium\|high\|xhigh` |
-| `--max-tokens <n>` | Output token cap |
+| `--max-tokens <n\|auto>` | Output token cap: a number, or `auto` for the model's own ceiling (default `64000`) |
 | `--cwd <dir>` | Working directory for tools |
 | `--confirm` | Confirm each mutating tool call |
 | `--tool-timeout <ms>` | Per-tool executor ceiling (default 180000) |
@@ -91,6 +91,7 @@ Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
 | `/model` | Open the model picker |
 | `/settings` | Open the settings screen |
 | `/thinking <level>` | Set the thinking level |
+| `/max-tokens [<n>\|auto\|default]` | Output token cap; with no argument, reports the setting **and** the effective cap for the live model |
 | `/tools` | List active tools |
 | `/clear` | Clear the visible transcript |
 | `/reset` | New conversation |
@@ -674,7 +675,9 @@ env / `.env` → CLI flags**.
 
 - **Env / `.env`**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
   `GOOGLE_API_KEY` / `GEMINI_API_KEY`, plus `ARAGON_PROVIDER`, `ARAGON_MODEL`,
-  `ARAGON_BASE_URL`, `ARAGON_THINKING`, `ARAGON_MAX_TOKENS`, `ARAGON_THEME`,
+  `ARAGON_BASE_URL`, `ARAGON_THINKING`,
+  `ARAGON_MAX_TOKENS` (a number, or `auto` / `0` for the per-model ceiling),
+  `ARAGON_THEME`,
   `ARAGON_FULLSCREEN`, `ARAGON_PLAN` (`1` starts in plan mode),
   `ARAGON_TEAM` (`0` disables team subagents), `ARAGON_TEAM_MAX` (fan-out width),
   `ARAGON_SKILLS` (`0` disables), `ARAGON_SKILLS_PATH`,
@@ -692,6 +695,7 @@ env / `.env` → CLI flags**.
 
 | Config key | Default | Meaning |
 | --- | --- | --- |
+| `maxTokens` | `64000` | Output token cap, clamped to `[256, 200000]`. `null` means **auto** — use each model's own ceiling, never above 64000. Absent means the default. See [Output token limits](#output-token-limits). |
 | `fullscreen` | `true` | Use the full-screen TUI (still subject to the automatic downgrades). Setting it to `false` opts out permanently; leaving it `true` is *not* a force — only `--fullscreen` / `ARAGON_FULLSCREEN=1` override the heuristics. |
 | `exitTranscript` | `true` | Replay a plain-text session summary after exiting (full-screen only). |
 | `transcriptWindow` | `300` | How many trailing entries the full-screen viewport renders, clamped to `[50, 2000]`. The full history stays in memory and in `/save`. |
@@ -727,6 +731,65 @@ Byte, not character: `ToolExecutor` truncates at 100 000 **bytes**, so a
 character-based budget would be roughly triple its nominal size for CJK text
 and would get cut mid-tag.
 
+### Output token limits
+
+Every model and every provider defaults to **64000** output tokens. You never
+have to configure this, and if you never touch it the number stays 64000.
+
+The number you set is an **ambition, not a promise**: it is clamped down to
+whatever the target model actually accepts. `gpt-4o` caps at 16384 and
+`gemini-1.5-pro` at 8192, and sending 64000 to either is an HTTP 400 that ends
+the turn — so `aragon` sends what the model will take, silently. When the model
+is one it has never seen (a proxy, an endpoint behind `--base-url`, a model that
+shipped last week), it sends 64000, and if the provider objects it reads the real
+ceiling out of the provider's own error, repairs the request, sends it again, and
+remembers the answer for the rest of the session. You see one warning line and
+the run continues.
+
+Four ways to change it, highest priority first:
+
+```bash
+aragon --max-tokens 32000            # this run only
+aragon --max-tokens auto             # this run only, per-model ceiling
+ARAGON_MAX_TOKENS=32000 aragon       # env layer, between the flag and the file
+aragon config set maxTokens 32000    # persisted; prints "Set maxTokens = 32000"
+aragon config set maxTokens auto     # persisted as null
+aragon config set maxTokens default  # back to 64000
+aragon config get maxTokens          # "64000" | "auto"
+```
+
+Inside the TUI, `/max-tokens` reports the current setting **and** the effective
+cap for the live model, and `/max-tokens <n|auto|default>` changes it. The
+settings screen (`/settings`) has the same field with an `Effective:` line under
+it, so a value the model will not honour is visible before you save it.
+
+And by hand, in `~/.aragon-agent/config.json` (`aragon config path` prints the
+exact location; `aragon config edit` opens it, and `/reload` picks up an edit
+made in another window):
+
+```jsonc
+{
+  "version": 1,
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-5-20250929",
+
+  // Output token cap.
+  //   64000  (or any 256..200000 integer) — an explicit cap, clamped down to
+  //          the target model's real ceiling when that ceiling is lower.
+  //   null   — auto: use each model's own ceiling, never above 64000.
+  //   absent — the product default, 64000.
+  "maxTokens": 64000
+}
+```
+
+Out-of-range numbers are clamped on the way in **and** on the way out, so a
+hand-edited `900000` becomes `200000` on disk rather than reverting to the
+default on every launch.
+
+Extended thinking is reconciled with the cap automatically: `--thinking xhigh`
+asks for a 65536-token budget, Anthropic requires `max_tokens` to be strictly
+greater than it, and the two are resolved together rather than left to collide.
+
 These are additive: a config file written by an earlier version loads
 unchanged, with no migration and no version bump.
 

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';
@@ -397,6 +397,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 +433,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 +464,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 +567,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)')

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,14 @@
 /**
  * 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 { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 import { loadConfig } from '../config/load.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
@@ -43,6 +44,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)',

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');

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, clampTranscriptWindow, coerceMaxTokens, coercePositiveInt, isSkillsToolPolicyMode, } from './schema.js';
+import { DEFAULT_CONFIG, IDLE_TIMEOUT_MARGIN_MS, clampAskRounds, clampDensity, clampHumanTimeout, clampLogConfig, clampSkillsConfig, clampTeamConfig, 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';
@@ -118,6 +118,44 @@ function pick(...vals) {
     }
     return undefined;
 }
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/**
+ * Resolve the output cap: flag › env › file › default, where an EXPLICIT `null`
+ * at any layer means AUTO (`undefined` — let the resolver pick per model).
+ *
+ * THIS CANNOT USE `pick()`, and that is the whole point. `pick` skips `null`, so
+ * a config file holding `"maxTokens": null` silently resolves to 64000 and AUTO
+ * is unreachable through every supported write path. Detecting it needs an
+ * own-property test, not a truthiness test — `null` is exactly the value we are
+ * looking for.
+ *
+ * An unparseable layer falls through to the next one rather than becoming AUTO:
+ * a typo in `ARAGON_MAX_TOKENS` must not silently discard the number in the
+ * config file underneath it.
+ */
+function resolveMaxTokens(flags, env, file) {
+    const layers = [
+        { name: '--max-tokens', value: flags.maxTokens },
+        { name: 'ARAGON_MAX_TOKENS', value: hasOwn(env, 'maxTokens') ? env.maxTokens : undefined },
+        { name: 'config.json maxTokens', value: hasOwn(file, 'maxTokens') ? file.maxTokens : undefined },
+    ];
+    for (const layer of layers) {
+        if (layer.value === undefined)
+            continue; // this layer said nothing
+        if (layer.value === null || isAutoToken(layer.value))
+            return undefined; // AUTO
+        const n = clampMaxTokens(layer.value);
+        if (n !== undefined)
+            return n;
+        getLogger().warn('config', 'max_tokens_unusable', {
+            source: layer.name,
+            value: String(layer.value),
+        });
+    }
+    return DEFAULT_CONFIG.maxTokens ?? undefined;
+}
 /**
  * Resolve the effective config by merging all layers, then derive the runtime
  * (non-persisted) fields and enforce the timeout invariant.
@@ -142,7 +180,7 @@ export function loadConfig(flags = {}) {
     const model = pick(flags.model, env.partial.model, file.model) ?? DEFAULT_CONFIG.model;
     const baseUrl = pick(flags.baseUrl, env.partial.baseUrl ?? undefined, file.baseUrl ?? undefined);
     const thinkingLevel = clampThinkingLevel(pick(flags.thinking, env.partial.thinkingLevel, file.thinkingLevel), DEFAULT_CONFIG.thinkingLevel);
-    const maxTokens = coerceMaxTokens(pick(flags.maxTokens, env.partial.maxTokens, file.maxTokens));
+    const maxTokens = resolveMaxTokens(flags, env.partial, file);
     // `clampTheme` is also where the v0.3.0 `dark` name is migrated to `cool`,
     // so reading a legacy config file needs no extra step here (§4.5 / R-4).
     const theme = clampTheme(pick(flags.theme, env.partial.theme, file.theme), DEFAULT_CONFIG.theme);
@@ -274,6 +312,9 @@ function recordResolvedConfig(config) {
         model: config.model,
         baseUrl: config.baseUrl,
         thinkingLevel: config.thinkingLevel,
+        // Four layers feed this one and none of them used to leave a trace, so
+        // "why is my output truncated" was unanswerable after the fact.
+        maxTokens: config.maxTokens ?? 'auto',
         theme: config.theme,
         fullscreen: config.fullscreen,
         toolTimeoutMs: config.toolTimeoutMs,

package/dist/config/schema.d.ts

@@ -5,7 +5,7 @@
  * See spec §3.5 (resolution pipeline), §6.1 (config file), and §3.8 (timeout
  * invariant).
  */
-import type { ThinkingLevel } from '@aragon-agent/core';
+import { type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
 /**
  * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
@@ -245,6 +245,18 @@ export interface PersistedConfig {
     model: string;
     baseUrl: string | null;
     thinkingLevel: ThinkingLevel;
+    /**
+     * Output token cap.
+     *
+     *   a number — an explicit cap, clamped to `[256, 200000]` on the way in AND
+     *              on the way out, then clamped again at request time down to the
+     *              target model's real ceiling when that ceiling is lower.
+     *   `null`   — AUTO: use each model's own ceiling, never above 64000.
+     *   absent   — the product default, 64000.
+     *
+     * `null` MEANS AUTO. It used to resolve to 64000 by accident (`pick()` skips
+     * `null`), which left the user no way to express "let the model decide".
+     */
     maxTokens: number | null;
     theme: ThemeName;
     /** Replace spinners with a static glyph for calmer, low-motion output. */
@@ -324,6 +336,7 @@ export interface CliConfig {
     model: string;
     baseUrl?: string;
     thinkingLevel: ThinkingLevel;
+    /** The resolved cap, or `undefined` for AUTO (per-model ceiling, ≤ 64000). */
     maxTokens?: number;
     theme: ThemeName;
     reducedMotion: boolean;
@@ -406,8 +419,57 @@ export interface CliConfig {
     /** One-shot `--api-key` override; applies to the active provider only. */
     apiKeyOverride?: string;
 }
-/** Coerce an arbitrary value into a positive integer, or `undefined`. */
+/**
+ * Coerce an arbitrary value into a positive integer, or `undefined`.
+ *
+ * Kept because callers outside this feature still use it, and deliberately
+ * WITHOUT the range clamp so its behaviour for in-range values is byte-identical
+ * to what it always was. New code wants `clampMaxTokens`.
+ */
 export declare function coerceMaxTokens(v: unknown): number | undefined;
+/**
+ * The accepted range for an explicit output cap.
+ *
+ * The floor is the engine's: below it a turn cannot produce a usable tool call.
+ * The ceiling is a sanity bound on a hand-edited file, not a model limit — the
+ * real per-model ceiling is applied later, by `resolveOutputTokens`.
+ */
+export declare const MAX_TOKENS_RANGE: {
+    min: number;
+    max: number;
+};
+/** `auto`, an empty string and `0` all mean AUTO — "let the model decide". */
+export declare function isAutoToken(v: unknown): boolean;
+/**
+ * THE single gate for every `maxTokens` read AND write, in the shape
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` already use.
+ *
+ * Both directions on purpose: hardening only the read path leaves a bad value on
+ * disk that reverts to a default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Returns `undefined` for AUTO and for anything unusable — the caller decides
+ * which of the two it was, because they mean different things.
+ */
+export declare function clampMaxTokens(v: unknown): number | undefined;
+/**
+ * Parse text typed into the settings screen, a slash command, or `config set`.
+ *
+ * Distinguishes AUTO from "the user typed nonsense", which `clampMaxTokens`
+ * cannot: both come back as `undefined` there, and treating a typo as AUTO would
+ * silently discard the number the user meant to set.
+ */
+export declare function parseMaxTokensInput(raw: string): {
+    kind: 'auto';
+} | {
+    kind: 'value';
+    value: number;
+    clamped: boolean;
+} | {
+    kind: 'invalid';
+};
+/** The product default, re-exported so the CLI never spells the number itself. */
+export declare const DEFAULT_MAX_TOKENS = 64000;
 /** Coerce a value into a positive integer with a fallback (for timeouts). */
 export declare function coercePositiveInt(v: unknown, fallback: number): number;
 /**

package/dist/config/schema.js

@@ -6,6 +6,7 @@
  * invariant).
  */
 import { isAbsolute } from 'node:path';
+import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
 import { TEAM_LIMITS } from '../team/limits.js';
 // ---------------------------------------------------------------------------
@@ -317,7 +318,9 @@ export const DEFAULT_CONFIG = {
     model: DEFAULT_MODEL,
     baseUrl: null,
     thinkingLevel: 'off',
-    maxTokens: null,
+    // The engine owns this number; spelling it here again is how the CLI and the
+    // provider adapters end up disagreeing about what "the default" is.
+    maxTokens: DEFAULT_MAX_OUTPUT_TOKENS,
     theme: 'auto',
     reducedMotion: false,
     fullscreen: true,
@@ -376,7 +379,7 @@ export function stripLegacyStateKeys(raw) {
 // Coercion / validation helpers
 // ---------------------------------------------------------------------------
 /** Coerce an arbitrary value into a positive integer, or `undefined`. */
-export function coerceMaxTokens(v) {
+function coerceTokenCount(v) {
     if (v === null || v === undefined || v === '')
         return undefined;
     const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
@@ -384,6 +387,74 @@ export function coerceMaxTokens(v) {
         return undefined;
     return Math.floor(n);
 }
+/**
+ * Coerce an arbitrary value into a positive integer, or `undefined`.
+ *
+ * Kept because callers outside this feature still use it, and deliberately
+ * WITHOUT the range clamp so its behaviour for in-range values is byte-identical
+ * to what it always was. New code wants `clampMaxTokens`.
+ */
+export function coerceMaxTokens(v) {
+    return coerceTokenCount(v);
+}
+/**
+ * The accepted range for an explicit output cap.
+ *
+ * The floor is the engine's: below it a turn cannot produce a usable tool call.
+ * The ceiling is a sanity bound on a hand-edited file, not a model limit — the
+ * real per-model ceiling is applied later, by `resolveOutputTokens`.
+ */
+export const MAX_TOKENS_RANGE = {
+    min: MIN_MAX_OUTPUT_TOKENS,
+    max: ABSOLUTE_MAX_OUTPUT_TOKENS,
+};
+/** `auto`, an empty string and `0` all mean AUTO — "let the model decide". */
+export function isAutoToken(v) {
+    if (v === 0)
+        return true;
+    if (typeof v !== 'string')
+        return false;
+    const trimmed = v.trim().toLowerCase();
+    return trimmed === '' || trimmed === 'auto' || trimmed === '0';
+}
+/**
+ * THE single gate for every `maxTokens` read AND write, in the shape
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` already use.
+ *
+ * Both directions on purpose: hardening only the read path leaves a bad value on
+ * disk that reverts to a default on every launch, which presents to the user as
+ * "my setting won't stick".
+ *
+ * Returns `undefined` for AUTO and for anything unusable — the caller decides
+ * which of the two it was, because they mean different things.
+ */
+export function clampMaxTokens(v) {
+    const n = coerceTokenCount(v);
+    if (n === undefined)
+        return undefined;
+    return Math.min(MAX_TOKENS_RANGE.max, Math.max(MAX_TOKENS_RANGE.min, n));
+}
+/**
+ * Parse text typed into the settings screen, a slash command, or `config set`.
+ *
+ * Distinguishes AUTO from "the user typed nonsense", which `clampMaxTokens`
+ * cannot: both come back as `undefined` there, and treating a typo as AUTO would
+ * silently discard the number the user meant to set.
+ */
+export function parseMaxTokensInput(raw) {
+    const trimmed = String(raw ?? '').trim();
+    if (isAutoToken(trimmed))
+        return { kind: 'auto' };
+    if (!/^\d+$/.test(trimmed))
+        return { kind: 'invalid' };
+    const parsed = Number.parseInt(trimmed, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return { kind: 'invalid' };
+    const value = Math.min(MAX_TOKENS_RANGE.max, Math.max(MAX_TOKENS_RANGE.min, parsed));
+    return { kind: 'value', value, clamped: value !== parsed };
+}
+/** The product default, re-exported so the CLI never spells the number itself. */
+export const DEFAULT_MAX_TOKENS = DEFAULT_MAX_OUTPUT_TOKENS;
 /** Coerce a value into a positive integer with a fallback (for timeouts). */
 export function coercePositiveInt(v, fallback) {
     if (v === null || v === undefined || v === '')

package/dist/config/store.js

@@ -14,7 +14,23 @@ 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, clampSkillsConfig, clampTeamConfig, stripLegacyStateKeys, } from './schema.js';
+import { CONFIG_VERSION, DEFAULT_CONFIG, clampLogConfig, clampMaxTokens, clampSkillsConfig, clampTeamConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+/**
+ * Normalize `maxTokens` for both directions of the config file.
+ *
+ * `null` MEANS AUTO and must survive untouched; a number is clamped to the
+ * accepted range; anything else on a hand-edited file (a string, a float, a
+ * negative) becomes AUTO rather than a silent default. Same discipline as
+ * `clampSkillsConfig` — read AND write pass through one gate, or a bad value on
+ * disk reverts on every launch and presents as "my setting won't stick".
+ */
+function normalizeMaxTokens(v) {
+    if (v === undefined)
+        return DEFAULT_CONFIG.maxTokens;
+    if (v === null || isAutoToken(v))
+        return null;
+    return clampMaxTokens(v) ?? null;
+}
 // Re-exported so the many existing importers of `store.js` keep working; the
 // definitions live in `app-paths.ts` because they are pure path arithmetic.
 export { getConfigPath, getSessionsDir };
@@ -92,6 +108,12 @@ export function loadPersistedConfig() {
         ...DEFAULT_CONFIG,
         ...partial,
         version: CONFIG_VERSION,
+        // Own-property aware, because `null` is the value we need to preserve: a
+        // spread cannot tell "the key is absent" (⇒ the default) from "the key is
+        // null" (⇒ AUTO), and those are different settings.
+        maxTokens: Object.prototype.hasOwnProperty.call(partial, 'maxTokens')
+            ? normalizeMaxTokens(partial.maxTokens)
+            : DEFAULT_CONFIG.maxTokens,
         apiKeys: { ...DEFAULT_CONFIG.apiKeys, ...(partial.apiKeys ?? {}) },
         // `skills` is the second nested object in this file and needs the same
         // treatment `apiKeys` gets — see the note on updatePersistedConfig below.
@@ -131,6 +153,11 @@ export function updatePersistedConfig(patch) {
         ...current,
         ...patch,
         version: CONFIG_VERSION,
+        // The write half of the gate: without it `config set maxTokens 900000` puts
+        // a number on disk that the read path silently rewrites on every launch.
+        maxTokens: Object.prototype.hasOwnProperty.call(patch, 'maxTokens')
+            ? normalizeMaxTokens(patch.maxTokens)
+            : current.maxTokens,
         apiKeys: { ...current.apiKeys, ...(patch.apiKeys ?? {}) },
         skills: clampSkillsConfig({ ...current.skills, ...(patch.skills ?? {}) }),
         // Without this line, changing the log level from the settings screen would

package/dist/ui/App.d.ts

@@ -7,7 +7,7 @@
 import React from 'react';
 import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
-import { type Overlay } from '../agent/reducer.js';
+import { type Overlay, type ToastLevel } from '../agent/reducer.js';
 import { type RenderMode } from './layout/frame.js';
 import { type FrameGeometry } from './layout/regions.js';
 import type { MouseSource } from '../input/stdin-mouse-filter.js';
@@ -15,6 +15,27 @@ import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
     handler: ((req: ConfirmRequest) => Promise<boolean>) | null;
 }
+/** What the settings screen's `Max tokens` field resolved to. */
+export interface SettingsMaxTokens {
+    /** Pushed into the live controller. `undefined` is AUTO. */
+    applied: number | undefined;
+    /** Written to the config file, or `'skip'` to leave the stored value alone. */
+    persist: number | null | 'skip';
+    /** Replaces the generic "Settings saved." acknowledgement when present. */
+    toast?: [ToastLevel, string];
+}
+/**
+ * Decide what the `Max tokens` field means, WITHOUT letting a bad value in it
+ * discard the rest of the form.
+ *
+ * The three outcomes are genuinely different and must stay distinguishable:
+ * `auto` is a setting, a clamped number is a setting the user should be told
+ * about, and nonsense is not a setting at all — it keeps the previous value and
+ * says so, rather than silently resolving to a default the user never chose.
+ *
+ * Exported for the tests; there is no other caller.
+ */
+export declare function resolveSettingsMaxTokens(raw: string, previous: number | undefined): SettingsMaxTokens;
 export interface AppProps {
     controller: AgentController;
     version: string;

package/dist/ui/App.js

@@ -11,7 +11,7 @@ import { Box, Text, useApp, useInput, useStdout } from 'ink';
 import { initialViewState, reduceEvent, viewReducer, } from '../agent/reducer.js';
 import { mergeDeltas } from '../agent/coalesce.js';
 import { computeCost } from '../agent/usage.js';
-import { coerceMaxTokens, DEFAULT_TRANSCRIPT_WINDOW, } from '../config/schema.js';
+import { parseMaxTokensInput, DEFAULT_TRANSCRIPT_WINDOW, } from '../config/schema.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { appendPrompt, loadPromptHistory } from '../config/prompt-history.js';
 import { bumpSubmitCount, setMouseNoticeSeen } from '../config/ui-state.js';
@@ -50,6 +50,41 @@ import { CommandRegistry, runSlashInput } from '../commands/registry.js';
 import { registerBuiltinCommands } from '../commands/builtins.js';
 import { makeSkillsCommand, registerSkillCommands } from '../commands/skills.js';
 import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+/**
+ * Decide what the `Max tokens` field means, WITHOUT letting a bad value in it
+ * discard the rest of the form.
+ *
+ * The three outcomes are genuinely different and must stay distinguishable:
+ * `auto` is a setting, a clamped number is a setting the user should be told
+ * about, and nonsense is not a setting at all — it keeps the previous value and
+ * says so, rather than silently resolving to a default the user never chose.
+ *
+ * Exported for the tests; there is no other caller.
+ */
+export function resolveSettingsMaxTokens(raw, previous) {
+    const parsed = parseMaxTokensInput(raw);
+    if (parsed.kind === 'auto') {
+        return {
+            applied: undefined,
+            persist: null,
+            toast: ['info', 'Max tokens: auto (per-model ceiling).'],
+        };
+    }
+    if (parsed.kind === 'value') {
+        return {
+            applied: parsed.value,
+            persist: parsed.value,
+            ...(parsed.clamped
+                ? { toast: ['warn', `Max tokens clamped to ${parsed.value}.`] }
+                : {}),
+        };
+    }
+    return {
+        applied: previous,
+        persist: 'skip',
+        toast: ['warn', 'Max tokens must be a number or "auto".'],
+    };
+}
 /** Merge pending delta actions ~33 ms and flush the coalescer buffer. */
 const COALESCE_MS = 33;
 export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, geometryOverride, }) {
@@ -518,10 +553,13 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         submitMessage(raw.startsWith('//') ? raw.slice(1) : raw);
     };
     const handleSettingsSave = (values) => {
-        const maxTokens = coerceMaxTokens(values.maxTokens);
+        // An unusable cap must NOT discard the rest of the form: the same Enter
+        // press is often carrying a freshly pasted API key, and losing that to a
+        // typo in an unrelated field is the worst outcome available here.
+        const cap = resolveSettingsMaxTokens(values.maxTokens, controller.getConfig().maxTokens);
         controller.setModel(values.provider, values.model, values.baseUrl || undefined);
         controller.setThinkingLevel(values.thinkingLevel);
-        controller.setMaxTokens(maxTokens);
+        controller.setMaxTokens(cap.applied);
         const key = values.apiKey.trim();
         if (key.length > 0) {
             // Registration site 4 (§4.4.3), and the one that matters most: this is how
@@ -536,7 +574,9 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             model: values.model,
             baseUrl: values.baseUrl.trim() ? values.baseUrl.trim() : null,
             thinkingLevel: values.thinkingLevel,
-            maxTokens: maxTokens ?? null,
+            // Omitted entirely when the field was unusable, so the previous value
+            // survives instead of being overwritten with a guess.
+            ...(cap.persist !== 'skip' ? { maxTokens: cap.persist } : {}),
         };
         if (key.length > 0)
             patch.apiKeys = { [values.provider]: key };
@@ -547,7 +587,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         persistConfig(patch);
         getLogger().reconfigure({ ...controller.getConfig().log, level: values.logLevel });
         dispatch({ type: 'setOverlay', overlay: null });
-        toast('success', 'Settings saved.');
+        toast(cap.toast?.[0] ?? 'success', cap.toast?.[1] ?? 'Settings saved.');
     };
     const handleModelSelect = (provider, model) => {
         controller.setModel(provider, model);
@@ -767,7 +807,9 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             model: cfg.model,
             baseUrl: cfg.baseUrl ?? '',
             thinkingLevel: cfg.thinkingLevel,
-            maxTokens: cfg.maxTokens ? String(cfg.maxTokens) : '',
+            // `auto`, not an empty string: an empty field reads as "unset", which
+            // is indistinguishable from AUTO and is not a state this can be in.
+            maxTokens: cfg.maxTokens ? String(cfg.maxTokens) : 'auto',
             apiKey: '',
             logLevel: cfg.log.level,
         }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onSave: handleSettingsSave })) : overlay === 'confirm' && confirmState ? (_jsx(ConfirmDialog, { state: confirmState, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onClose: closeConfirm })) : overlay === 'question' && humanRequest?.kind === 'questions' ? (_jsx(QuestionOverlay, { questions: humanRequest.questions, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onSubmit: (answers) => resolveHuman({ kind: 'answers', answers, cancelled: false }) })) : overlay === 'plan' && humanRequest?.kind === 'plan' ? (_jsx(PlanReviewOverlay, { plan: humanRequest.plan, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onVerdict: handlePlanVerdict })) : null;

package/dist/ui/overlays/HelpOverlay.js

@@ -25,6 +25,7 @@ const COMMANDS = [
     ['/plan [on|off|status]', 'Toggle plan mode (same as Shift+Tab)'],
     ['/theme <name>', 'auto | warm | cool | light'],
     ['/thinking <level>', 'Set thinking level'],
+    ['/max-tokens [n|auto]', 'Output token cap; no argument reports the effective one'],
     ['/team [on|off|max n]', 'Team subagents: status, switch, fan-out width'],
     ['/tools', 'List active tools'],
     ['/clear', 'Clear the visible transcript'],

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

@@ -8,7 +8,7 @@
  * otherwise.
  */
 import React from 'react';
-import type { ThinkingLevel } from '@aragon-agent/core';
+import { type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../../logging/levels.js';
 import type { Theme } from '../theme.js';
 import type { TermCapabilities } from '../capabilities.js';
@@ -40,5 +40,16 @@ interface SettingsScreenProps {
     caps: TermCapabilities;
     onSave: (values: SettingsValues) => void;
 }
+/**
+ * The cap this setting will ACTUALLY produce against the selected model.
+ *
+ * Exported for the tests, and computed on every render rather than in an effect:
+ * `resolveOutputTokens` is pure, allocation-light and does no I/O — the ceiling
+ * lookup is a `Map.get` plus at most seven regex tests.
+ *
+ * Without this row the settings screen can only show what the user typed, and
+ * "I set 64000 but answers still stop early" has no answer anywhere in the UI.
+ */
+export declare function effectiveCapLine(values: Pick<SettingsValues, 'provider' | 'model' | 'maxTokens'>): string;
 export declare function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }: SettingsScreenProps): React.ReactElement;
 export {};

package/dist/ui/overlays/SettingsScreen.js

@@ -10,7 +10,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useState } from 'react';
 import { Text, useInput } from 'ink';
-import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret } from '../../config/schema.js';
+import { DEFAULT_MAX_OUTPUT_TOKENS, resolveOutputTokens, } from '@aragon-agent/core';
+import { ADAPTER_PROVIDERS, THINKING_LEVELS, maskSecret, parseMaxTokensInput, } from '../../config/schema.js';
 import { LOG_LEVEL_NAMES } from '../../logging/levels.js';
 import { pickGlyphs } from '../glyphs.js';
 import { OverlayFrame } from '../layout/OverlayFrame.js';
@@ -23,6 +24,34 @@ const FIELDS = [
     { key: 'apiKey', label: 'API key', kind: 'secret' },
     { key: 'logLevel', label: 'Log level', kind: 'enum', options: LOG_LEVEL_NAMES },
 ];
+/**
+ * The cap this setting will ACTUALLY produce against the selected model.
+ *
+ * Exported for the tests, and computed on every render rather than in an effect:
+ * `resolveOutputTokens` is pure, allocation-light and does no I/O — the ceiling
+ * lookup is a `Map.get` plus at most seven regex tests.
+ *
+ * Without this row the settings screen can only show what the user typed, and
+ * "I set 64000 but answers still stop early" has no answer anywhere in the UI.
+ */
+export function effectiveCapLine(values) {
+    const parsed = parseMaxTokensInput(values.maxTokens);
+    if (parsed.kind === 'invalid')
+        return 'Effective: -  (not a number; use a value or "auto")';
+    const requested = parsed.kind === 'value' ? parsed.value : undefined;
+    const resolution = resolveOutputTokens({
+        providerId: values.provider,
+        modelId: values.model,
+        ...(requested !== undefined ? { requested } : {}),
+    });
+    if (resolution.clampedBy === 'ceiling') {
+        const ambition = requested ?? DEFAULT_MAX_OUTPUT_TOKENS;
+        return `Effective: ${resolution.value}  (clamped from ${ambition} by the ${values.model} ceiling)`;
+    }
+    if (requested === undefined)
+        return `Effective: ${resolution.value}  (auto)`;
+    return `Effective: ${resolution.value}`;
+}
 export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset, onScrollClamp, theme, caps, onSave, }) {
     const [values, setValues] = useState(initial);
     const [index, setIndex] = useState(0);
@@ -99,6 +128,10 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
         }
         if (f.kind === 'enum')
             return raw;
+        // An empty cap field is AUTO, not "unset". `(none)` would read as a missing
+        // setting, which is the one thing this field can never be.
+        if (f.key === 'maxTokens' && raw.length === 0)
+            return 'auto';
         return raw.length > 0 ? raw : selected ? '(type to set)' : '(none)';
     };
     // One element per row, each `wrap="truncate"` — the contract for OverlayFrame's
@@ -108,6 +141,10 @@ export function SettingsScreen({ initial, apiKeys, maxRows, cols, scrollOffset,
         const selected = i === index;
         return (_jsxs(Text, { wrap: "truncate", children: [_jsx(Text, { color: selected ? theme.accent : theme.muted, children: selected ? `${glyphs.caret} ` : '  ' }), _jsx(Text, { color: selected ? theme.assistant : theme.muted, children: (f.key === 'apiKey' ? `API key (${values.provider})` : f.label).padEnd(18) }), _jsx(Text, { color: selected ? theme.primary : theme.muted, children: displayValue(f, selected) }), f.kind === 'enum' && selected && (_jsxs(Text, { color: theme.muted, children: [' (', glyphs.arrowLeft, "/", glyphs.arrowRight, ')'] }))] }, f.key));
     });
+    // One element, `wrap="truncate"`, pushed like every other row — OverlayFrame's
+    // controlled mode slices by ELEMENT, so a row that wraps desynchronises the
+    // position indicator.
+    rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: effectiveCapLine(values) }, "__effective"));
     rows.push(_jsx(Text, { wrap: "truncate", color: theme.muted, children: "Enter saves. Keys persist to the config file (0600)." }, "__save"));
     return (_jsx(OverlayFrame, { title: "Settings", hint: `${glyphs.arrowUp}${glyphs.arrowDown} field ${glyphs.midDot} ${glyphs.arrowLeft}${glyphs.arrowRight} change ${glyphs.midDot} Enter save ${glyphs.midDot} Esc close`, maxRows: maxRows, cols: cols, rows: rows, scrollOffset: scrollOffset, onScrollClamp: onScrollClamp, theme: theme, caps: caps }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/cli",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "AragonAgent CLI — a Claude-Code / Codex-style interactive terminal UI (TUI) on top of the @aragon-agent/core engine. Installable and runnable via npm / npx.",
   "license": "MIT",
   "author": "AragonAgent contributors",
@@ -51,7 +51,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@aragon-agent/core": "^0.2.3",
+    "@aragon-agent/core": "^0.2.4",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.0.0",
     "commander": "^12.1.0",