@aragon-agent/cli 0.5.2 → 0.5.3

package/dist/agent/headless.js

@@ -4,7 +4,7 @@
  * derived from the event stream (R2), not from the resolved promise:
  *   0 = success, 1 = agent error (incl. a silently-swallowed throw), 2 = config.
  */
-import { formatCost, formatTokens, computeCost } from './usage.js';
+import { formatCost, formatTokens, formatDuration, computeCost } from './usage.js';
 import { formatStreamError } from './reducer.js';
 /** Run a single prompt headlessly and resolve with the process exit code. */
 export async function runHeadless(controller, prompt, options = {}) {
@@ -57,11 +57,51 @@ export async function runHeadless(controller, prompt, options = {}) {
                 break;
         }
     });
+    // Team mode is ON in headless: a fan-out needs no human (§3.12). What the
+    // children's spend must NOT do is vanish from the footer — the `[usage]` line
+    // is the only cost readout `-p` has, and a dispatch is where most of the
+    // tokens go.
+    const started = new Set();
+    const finished = new Set();
+    const unsubscribeTeam = controller.subscribeTeam?.((event) => {
+        if (event.type === 'usage') {
+            total.inputTokens += event.usage.inputTokens;
+            total.outputTokens += event.usage.outputTokens;
+            return;
+        }
+        if (quiet)
+            return;
+        if (event.type === 'dispatch_start') {
+            err.write(`\n[team] dispatch ${event.specs.length} subagents\n`);
+            return;
+        }
+        if (event.type === 'agent_update') {
+            const { run } = event;
+            if (run.phase !== 'queued' && !started.has(run.label)) {
+                started.add(run.label);
+                err.write(`[team] ${run.label} start "${run.description}"\n`);
+            }
+            const terminal = run.phase === 'done' || run.phase === 'failed' || run.phase === 'aborted';
+            if (terminal && !finished.has(run.label)) {
+                finished.add(run.label);
+                const ms = Math.max(0, (run.endedAt ?? 0) - (run.startedAt ?? 0));
+                const verdict = run.phase === 'done' && !run.error ? 'ok' : run.phase;
+                err.write(`[team] ${run.label} ${verdict} ${formatDuration(ms)} ${run.toolCalls} tools\n`);
+            }
+            return;
+        }
+        if (event.type === 'dispatch_end') {
+            const ok = event.outcome.runs.filter((r) => r.phase === 'done' && !r.error).length;
+            err.write(`[team] done ${ok}/${event.outcome.runs.length} ok` +
+                `${event.outcome.aborted ? ' (aborted)' : ''}\n`);
+        }
+    });
     try {
         await controller.prompt(prompt);
     }
     finally {
         unsubscribe();
+        unsubscribeTeam?.();
     }
     // Ensure a trailing newline so piped output is well-formed.
     if (wroteText)

package/dist/agent/reducer.d.ts

@@ -12,6 +12,7 @@
  */
 import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agent/core';
 import type { AgentMode } from './agent-mode.js';
+import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
 export type Overlay = null | 'settings' | 'model' | 'help' | 'confirm' | 'question' | 'plan';
@@ -55,6 +56,28 @@ export type Entry = {
     kind: 'notice';
     level: NoticeLevel;
     text: string;
+}
+/**
+ * A team dispatch (team-subagents §5.3). JSON-SERIALIZABLE by construction, so
+ * `/save` and `/resume` need no format change.
+ *
+ * `active: true` is normalized away ON LOAD, in `session/persist.ts`, not here
+ * (P1-5). A session saved mid-dispatch would otherwise resume with a card that
+ * claims to be running while nothing is: it spins forever, and because
+ * `Transcript`'s settled boundary is MONOTONIC an entry that never settles
+ * never reaches `<Static>` and is re-rendered on every frame for the rest of
+ * the session. The reducer never legitimately sees a stale-active entry — only
+ * the file does — which is why the fix belongs in the load path.
+ */
+ | {
+    id: string;
+    kind: 'team';
+    dispatchId: string;
+    requested: number;
+    runs: SubagentRun[];
+    aborted: boolean;
+    durationMs?: number;
+    active: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
@@ -81,7 +104,17 @@ export interface ViewState {
     agentMode: AgentMode;
     /** Set only by a DEFERRED `plan -> build`; drives the `PLAN -> BUILD` readout. */
     pendingAgentMode: AgentMode | null;
+    /**
+     * The live team roster, or `null` when no dispatch is running.
+     *
+     * NEVER PERSISTED. `/save` writes `entries`, and the settled `team` entry is
+     * the history; this field is the ephemeral panel, and a resumed session has no
+     * live dispatch to show (§6.4).
+     */
+    team: TeamSnapshot | null;
     seq: number;
+    /** The `kind: 'team'` entry the live dispatch is writing into. */
+    teamEntryId?: string;
     streamingId?: string;
     turnProduced: boolean;
     errorNoticed: boolean;
@@ -165,6 +198,21 @@ export type ViewAction = {
     type: 'setAgentMode';
     mode: AgentMode;
     pending: AgentMode | null;
+} | {
+    type: 'teamStart';
+    dispatchId: string;
+    requested: number;
+    specs: SubagentSpec[];
+} | {
+    type: 'teamUpdate';
+    snapshot: TeamSnapshot;
+} | {
+    type: 'teamUsage';
+    usage: TokenUsage;
+    costDelta: number;
+} | {
+    type: 'teamEnd';
+    outcome: DispatchOutcome;
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;

package/dist/agent/reducer.js

@@ -27,7 +27,9 @@ export function initialViewState() {
         // `controller.getAgentMode()` so `--plan` renders on the first frame.
         agentMode: 'build',
         pendingAgentMode: null,
+        team: null,
         seq: 0,
+        teamEntryId: undefined,
         streamingId: undefined,
         turnProduced: false,
         errorNoticed: false,
@@ -367,8 +369,17 @@ export function viewReducer(state, action) {
                 entries: mapEntry(state.entries, state.streamingId, (e) => e.kind === 'assistant' ? { ...e, streaming: false, aborted: true } : e),
             };
         }
+        // `teamEntryId` is dropped with the entries it pointed at. Keeping it would
+        // leave `teamUpdate` mapping an id that no longer exists — harmless today,
+        // and a dangling reference the next reader has to reason about.
         case 'clearTranscript':
-            return { ...state, entries: [], streamingId: undefined, expandedToolIds: {} };
+            return {
+                ...state,
+                entries: [],
+                streamingId: undefined,
+                expandedToolIds: {},
+                teamEntryId: undefined,
+            };
         case 'resetConversation':
             return {
                 ...state,
@@ -377,6 +388,7 @@ export function viewReducer(state, action) {
                 expandedToolIds: {},
                 contextTokens: 0,
                 usageTotal: { inputTokens: 0, outputTokens: 0, costUsd: 0 },
+                teamEntryId: undefined,
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
@@ -407,13 +419,90 @@ export function viewReducer(state, action) {
                 next[action.id] = true;
             return { ...state, expandedToolIds: next };
         }
+        // --- Team mode (team-subagents §5.3) ---------------------------------
+        case 'teamStart': {
+            const { id, seq } = nextId(state);
+            const runs = action.specs.map((spec) => ({
+                label: spec.label,
+                description: spec.description,
+                phase: 'queued',
+                turns: 0,
+                toolCalls: 0,
+                usage: { inputTokens: 0, outputTokens: 0 },
+                filesTouched: [],
+                messagesSent: 0,
+            }));
+            const entry = {
+                id,
+                kind: 'team',
+                dispatchId: action.dispatchId,
+                requested: action.requested,
+                runs,
+                aborted: false,
+                active: true,
+            };
+            return {
+                ...state,
+                seq,
+                entries: [...state.entries, entry],
+                teamEntryId: id,
+                team: {
+                    dispatchId: action.dispatchId,
+                    active: true,
+                    runs,
+                    requested: action.requested,
+                    startedAt: Date.now(),
+                    messageCount: 0,
+                },
+            };
+        }
+        case 'teamUpdate': {
+            // One `mapEntry` on the KNOWN id, never a scan: this action arrives at up
+            // to `maxConcurrent` x 8/s and a reverse search over a long transcript on
+            // every one of them is exactly the cost the coalescer exists to avoid.
+            const entries = state.teamEntryId
+                ? mapEntry(state.entries, state.teamEntryId, (e) => e.kind === 'team' ? { ...e, runs: action.snapshot.runs } : e)
+                : state.entries;
+            return { ...state, entries, team: action.snapshot };
+        }
+        case 'teamUsage':
+            // `usageTotal` AND NOTHING ELSE (§3.9 / AC-15). In particular NOT
+            // `contextTokens`: that gauge shows the LEAD's context occupancy against
+            // the model's window, and folding five children into it would read 180%
+            // on a perfectly healthy session. Child spend is real money and has to
+            // appear in the cost readout; it is not the lead's context.
+            return {
+                ...state,
+                usageTotal: {
+                    inputTokens: state.usageTotal.inputTokens + action.usage.inputTokens,
+                    outputTokens: state.usageTotal.outputTokens + action.usage.outputTokens,
+                    costUsd: state.usageTotal.costUsd + action.costDelta,
+                },
+            };
+        case 'teamEnd': {
+            const { outcome } = action;
+            const entries = state.teamEntryId
+                ? mapEntry(state.entries, state.teamEntryId, (e) => e.kind === 'team'
+                    ? {
+                        ...e,
+                        runs: outcome.runs,
+                        aborted: outcome.aborted,
+                        durationMs: Math.max(0, outcome.endedAt - outcome.startedAt),
+                        active: false,
+                    }
+                    : e)
+                : state.entries;
+            // `team: null` is what makes the panel disappear — the requirement's
+            // "(dang you de shi hou)": it renders only while a dispatch is running.
+            return { ...state, entries, team: null, teamEntryId: undefined };
+        }
         case 'restoreEntries': {
             // Adopt a seq beyond any restored id to keep future ids unique.
             const maxSeq = action.entries.reduce((acc, e) => {
                 const n = Number.parseInt(e.id.replace(/^e/, ''), 10);
                 return Number.isFinite(n) ? Math.max(acc, n) : acc;
             }, state.seq);
-            return { ...state, entries: [...action.entries], seq: maxSeq };
+            return { ...state, entries: [...action.entries], seq: maxSeq, teamEntryId: undefined };
         }
         default:
             return state;

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

@@ -36,6 +36,23 @@ export interface SystemPromptParams {
     planInteractive?: boolean;
     /** `planModeMaxAskRounds`, substituted into the block so the two agree. */
     planMaxAskRounds?: number;
+    /**
+     * The rendered `<team_mode>` block for a LEAD with team mode on, or `''`.
+     *
+     * Spliced conditionally exactly as `skillsBlock` and the plan block are, which
+     * is what keeps invariant I-8 true: `team.enabled: false` (and `--no-team`)
+     * produce the pre-team prompt BYTE FOR BYTE.
+     */
+    teamBlock?: string;
+    /**
+     * The rendered `<subagent_role>` block for a CHILD, or `''`.
+     *
+     * Never set together with `teamBlock`: a child has no `task` tool (D-3), and a
+     * lead is not a subagent. Two fields rather than one because the two blocks
+     * carry opposite instructions and a single "team text" parameter would make
+     * mixing them a one-character mistake.
+     */
+    subagentBlock?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -37,6 +37,8 @@ export function buildSystemPrompt(params) {
             maxAskRounds: params.planMaxAskRounds ?? 4,
         })
         : '';
+    const teamBlock = params.teamBlock ?? '';
+    const subagentBlock = params.subagentBlock ?? '';
     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.',
@@ -50,6 +52,8 @@ export function buildSystemPrompt(params) {
         toolList,
         ...(hasSkills ? ['', skillsBlock] : []),
         ...(planBlock ? ['', planBlock] : []),
+        ...(teamBlock ? ['', teamBlock] : []),
+        ...(subagentBlock ? ['', subagentBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

package/dist/cli.js

@@ -21,8 +21,10 @@ import { loadConfig } from './config/load.js';
 import { getConfigPath, readConfigFile, updatePersistedConfig } from './config/store.js';
 import { formatMigrationNotice, migrateLegacyState } from './config/migrate-legacy-state.js';
 import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
-import { LOG_CONFIG_SET_KEYS, applyLogConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
-import { attachAgentEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
+import { migrateStateOutOfConfig } from './config/migrate-state-out-of-config.js';
+import { runHistoryCommand } from './config/history-commands.js';
+import { LOG_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, applyLogConfigSet, applyTeamConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+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';
@@ -79,6 +81,11 @@ function toFlags(opts) {
         skillsYes: opts.skillsYes,
         skillToolPolicy: opts.skillToolPolicy,
         plan: opts.plan,
+        // These two lines are the same failure the `mouse` note above records, one
+        // feature later (P1-4): without them `--no-team` and `--team-max` never
+        // reach `CliFlags` and are inert, with no compile error and no runtime error.
+        team: opts.team,
+        teamMax: opts.teamMax,
         // `--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),
@@ -166,6 +173,11 @@ function runInteractive(flags, extras = {}) {
     const logger = getLogger();
     logger.info('cli', 'run_interactive', { mode, provider: config.provider, model: config.model });
     attachAgentEvents(logger, controller);
+    // The team stream is CLI-local (D-10), so `attachAgentEvents` cannot see it.
+    // Without this a dispatch leaves NO trace in the log file at all — the wrong
+    // outcome for the one feature here that runs five agents the user cannot
+    // watch (§3.13 / P1-2 / R-19).
+    attachTeamEvents(logger, controller);
     let screen = null;
     let replayed = false;
     // --- Mouse wheel region routing (mouse-wheel-region-routing §4.2). -------
@@ -264,11 +276,16 @@ function runInteractive(flags, extras = {}) {
         .then(() => {
         screen?.restore();
         disposeMouse();
+        // Orphaned subagents survive `Ctrl+C` otherwise, and a live child holds
+        // the event loop open so `aragon` never returns to the shell (R-15). The
+        // App's unmount cleanup also calls this; `dispose()` is idempotent.
+        controller.dispose();
         replayTranscript();
     })
         .catch(() => {
         screen?.restore();
         disposeMouse();
+        controller.dispose();
     });
 }
 async function runOneShot(flags, prompt, quiet) {
@@ -282,6 +299,11 @@ async function runOneShot(flags, prompt, quiet) {
     // toast channel `App.tsx` uses does not exist here.
     logger.onFailure((reason) => process.stderr.write(`[log] ${reason}\n`));
     attachAgentEvents(logger, controller);
+    // The team stream is CLI-local (D-10), so `attachAgentEvents` cannot see it.
+    // Without this a dispatch leaves NO trace in the log file at all — the wrong
+    // outcome for the one feature here that runs five agents the user cannot
+    // watch (§3.13 / P1-2 / R-19).
+    attachTeamEvents(logger, controller);
     const untrusted = controller.getSkillService().untrustedDirs();
     for (const dir of untrusted) {
         process.stderr.write(`[skills] project skills in ${dir} skipped (untrusted). Run: aragon skills trust ${dir}\n`);
@@ -354,6 +376,7 @@ const CONFIG_SET_KEYS = new Set([
     // falls through every case, writes nothing, and still prints
     // `Set mouse = false` (P1-2) -- exactly what happened to `density`/`hints`.
     'mouse',
+    'historyEnabled',
     'planModeDefault',
     'planModeMaxAskRounds',
     'planModeHumanTimeoutMs',
@@ -368,6 +391,11 @@ const CONFIG_SET_KEYS = new Set([
     // `log.*` keys are handled by `applyLogConfigSet` below, NOT by the switch:
     // that switch is already past this package's complexity ceiling.
     ...LOG_CONFIG_SET_KEYS,
+    // `team.*` keys are handled by `applyTeamConfigSet`, for the same reason
+    // `log.*` are: the switch below is already past this package's complexity
+    // ceiling, and a key listed here but forgotten there writes nothing while
+    // still printing `Set team.enabled = false`.
+    ...TEAM_CONFIG_SET_KEYS,
 ]);
 function runConfigSet(key, value) {
     if (!CONFIG_SET_KEYS.has(key)) {
@@ -382,6 +410,16 @@ function runConfigSet(key, value) {
         process.stdout.write(`Set ${key} = ${value}\n`);
         return;
     }
+    const teamPatch = applyTeamConfigSet(key, value);
+    if (teamPatch) {
+        // The written value is echoed from the CLAMPED result rather than from the
+        // input, so `config set team.maxSubagents 40` says 10 instead of silently
+        // reporting a number that was never stored (R-g).
+        const merged = updatePersistedConfig(teamPatch);
+        const field = key.slice('team.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.team[field])}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -429,6 +467,11 @@ function runConfigSet(key, value) {
         case 'mouse':
             patch.mouse = value === 'true' || value === '1';
             break;
+        // Turning this off stops new prompts being recorded; it does NOT delete
+        // what is already in `prompt-history.jsonl` (that is `aragon history clear`).
+        case 'historyEnabled':
+            patch.historyEnabled = value === 'true' || value === '1';
+            break;
         // Clamped rather than rejected, for the same reason as `theme` and
         // `skills.integrity`: hardening only the READ path leaves a bad value on
         // disk that reverts to the default on every launch, which presents as
@@ -525,6 +568,13 @@ function buildProgram() {
         // config layer win when neither flag was given.
         .option('--plan', 'Start the session in PLAN mode (read-only research + review)')
         .option('--no-plan', 'Start the session in BUILD mode (overrides planModeDefault)')
+        // BOTH FORMS, positive first, and the pair is mandatory (team-subagents
+        // §4.4 / P1-4). Declaring only `--no-team` would make commander default
+        // `opts.team` to `true`, at which point the flag is indistinguishable from
+        // its own default and silently overrides `config.json` on every run.
+        .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)')
         .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)')
@@ -618,6 +668,16 @@ function buildProgram() {
         .action(async (subcommand, opts) => {
         process.exitCode = await runLogsCommand(subcommand ?? 'path', opts, toFlags(program.opts()));
     });
+    // aragon history <sub> [-n N] [--json] [--yes]
+    program
+        .command('history [subcommand]')
+        .description('Inspect the prompt history: path | list | clear')
+        .option('-n, --lines <n>', 'Entries for `history list` (default 20)')
+        .option('--json', 'Print raw entries instead of rendered lines')
+        .option('--yes', 'Confirm destructive actions (required by `history clear`)')
+        .action((subcommand, opts) => {
+        process.exitCode = runHistoryCommand(subcommand ?? 'path', opts);
+    });
     // aragon skills <sub> [arg] [--scope] [--name] [--description] [--yes] [--json]
     program
         .command('skills [subcommand] [argument]')
@@ -666,6 +726,10 @@ async function main() {
     // may just have created. What ① and ② did is replayed from `pending` rather
     // than lost.
     installLogging({ pending: migrationNotes(legacy, home) });
+    // ③.5 — after ③ because it writes a log record, and before anything that
+    // resolves config because every `loadConfig()` from here on must already see
+    // the post-migration world. Never throws, never prints (D-8).
+    migrateStateOutOfConfig();
     // An unparseable config.json still falls back to defaults — the CLI has to
     // start — but it must not do so in silence, or a stray comma presents as
     // "every setting I ever chose is gone". stderr, never stdout, so

package/dist/commands/builtins.js

@@ -90,6 +90,88 @@ const COMMANDS = [
             ctx.applyAgentMode(target);
         },
     },
+    {
+        name: 'team',
+        description: 'Team subagents: status | on | off | max <n>',
+        /**
+         * `/team on` CANNOT turn team mode on in a session that started without it,
+         * and this command must not pretend otherwise (§4.5 / D-17 / P0-2).
+         *
+         * `controller.ts` builds the tool array ONCE and its own comment forbids
+         * rebuilding it: `Agent.setTools()` mutates the live `ToolRegistry`, and
+         * `submit_plan` flips the session mode from INSIDE a tool execution, so a
+         * rebuild at that moment would mutate the registry mid-iteration. But
+         * `rebuildSystemPrompt()` IS a live path — so the naive reading of `/team on`
+         * (flip a flag, re-splice `<team_mode>`) produces a session where the model
+         * is told it has a `task` tool that was never registered. Every call comes
+         * back "unknown tool", and the model has no way to discover why.
+         *
+         * So the answer splits by what was decided at construction, and the honest
+         * branch — persist it, say the session is unchanged — is the whole point.
+         */
+        run: (ctx) => {
+            const arg = ctx.args.trim().toLowerCase();
+            const [verb, value] = arg.split(/\s+/, 2);
+            const controller = ctx.controller;
+            // Refused mid-dispatch for the reason `/reload` already records: half a
+            // dispatch under one ceiling and half under another produces a result
+            // nothing can afterwards explain.
+            if (verb && verb !== 'status' && controller.isTeamBusy()) {
+                ctx.notify('warn', 'Cannot change team settings mid-dispatch.');
+                return;
+            }
+            if (!verb || verb === 'status') {
+                const cfg = controller.getTeamConfig();
+                const state = !controller.isTeamRegistered()
+                    ? 'off for this session (started with --no-team)'
+                    : controller.isTeamEnabled()
+                        ? 'on'
+                        : 'off';
+                const snapshot = controller.getTeamSnapshot();
+                const roster = snapshot
+                    ? `\nRunning: ${snapshot.runs.map((r) => `${r.label} (${r.phase})`).join(', ')}`
+                    : '';
+                ctx.notify('info', `Team mode: ${state}. Max subagents: ${cfg.maxSubagents}, ` +
+                    `concurrent: ${cfg.maxConcurrent}.${roster}`);
+                return;
+            }
+            if (verb === 'on' || verb === 'off') {
+                const enabled = verb === 'on';
+                // A PARTIAL `team` section, safe only because `updatePersistedConfig`
+                // deep-merges it — the same contract `/skills disable` relies on.
+                ctx.persistConfig({ team: { enabled } });
+                if (!controller.isTeamRegistered()) {
+                    // The bottom-right cell of §4.5's table. It is honest, it is one
+                    // sentence, and it keeps AC-11 intact: a `--no-team` session never
+                    // grows a wrapper or an entry, whatever the user types afterwards.
+                    ctx.notify('info', enabled
+                        ? 'Team mode is off for this session (started with --no-team). Saved for next launch.'
+                        : 'Team mode is already off for this session. Saved for next launch.');
+                    return;
+                }
+                controller.setTeamEnabled(enabled);
+                ctx.toast('success', `Team mode ${enabled ? 'on' : 'off'}.`);
+                return;
+            }
+            if (verb === 'max') {
+                const n = Number.parseInt(value ?? '', 10);
+                if (!Number.isFinite(n) || n <= 0) {
+                    ctx.notify('warn', 'Usage: /team max <n>');
+                    return;
+                }
+                // Clamped by `setTeamConfig` and again on the persist path, so a value
+                // above the requirement's ceiling can reach neither the runtime nor the
+                // file (R-g).
+                const applied = controller.setTeamConfig({ maxSubagents: n });
+                ctx.persistConfig({
+                    team: { maxSubagents: applied.maxSubagents },
+                });
+                ctx.toast('success', `Max subagents set to ${applied.maxSubagents}.`);
+                return;
+            }
+            ctx.notify('warn', `Unknown argument "${verb}" - use /team [status|on|off|max <n>].`);
+        },
+    },
     {
         name: 'expand',
         description: 'Expand / collapse a recent tool card (default: last)',

package/dist/config/app-paths.d.ts

@@ -12,11 +12,18 @@
  *   ~/.aragon-agent/
  *   ├── config.json            persisted config (0600 on POSIX)
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
+ *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
+ *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
  *   ├── logs/                  JSONL logs (0700 on POSIX)
  *   ├── sessions/              /save · /resume
  *   ├── skills/                `aragon skills install` target
  *   └── skill-usage.json
  *
+ * The two files added by config-state-separation are DIRECT CHILDREN of the
+ * root, siblings of `skill-usage.json` rather than children of any directory
+ * here: `logs/`, `sessions/` and `skills/` are all scan roots, and every extra
+ * file inside one is another thing each walk has to recognise and skip.
+ *
  * The same path on all three platforms, deliberately. Claude Code, git and npm
  * all put their dot-directory in the user's home; one path means documentation,
  * support scripts and community answers have exactly one thing to say. A user
@@ -62,6 +69,16 @@ export declare function getHomeRoot(): string;
 export declare function getConfigPath(): string;
 /** Written by `aragon config edit` before spawning the editor. */
 export declare function getConfigBackupPath(): string;
+/**
+ * `<home>/prompt-history.jsonl` — the prompts the user submitted, one JSON
+ * object per line. Deliberately NOT under `logs/`: that directory is governed
+ * by `log.toFile`, `log.maxFiles` and `aragon logs clear`, and turning
+ * diagnostics off or reclaiming disk must not also delete the user's `↑`
+ * recall (config-state-separation D-1).
+ */
+export declare function getPromptHistoryPath(): string;
+/** `<home>/state.json` — UI bookkeeping scalars only; see `ui-state.ts`. */
+export declare function getUiStatePath(): string;
 export declare function getLogsDir(): string;
 export declare function getSessionsDir(): string;
 /** `<home>` — parent of `skills/`, and where sidecar state such as usage lives. */

package/dist/config/app-paths.js

@@ -12,11 +12,18 @@
  *   ~/.aragon-agent/
  *   ├── config.json            persisted config (0600 on POSIX)
  *   ├── config.json.bak        `aragon config edit` pre-edit backup
+ *   ├── prompt-history.jsonl   submitted prompts, append-only (0600 on POSIX)
+ *   ├── state.json             UI bookkeeping scalars (0600 on POSIX)
  *   ├── logs/                  JSONL logs (0700 on POSIX)
  *   ├── sessions/              /save · /resume
  *   ├── skills/                `aragon skills install` target
  *   └── skill-usage.json
  *
+ * The two files added by config-state-separation are DIRECT CHILDREN of the
+ * root, siblings of `skill-usage.json` rather than children of any directory
+ * here: `logs/`, `sessions/` and `skills/` are all scan roots, and every extra
+ * file inside one is another thing each walk has to recognise and skip.
+ *
  * The same path on all three platforms, deliberately. Claude Code, git and npm
  * all put their dot-directory in the user's home; one path means documentation,
  * support scripts and community answers have exactly one thing to say. A user
@@ -119,6 +126,20 @@ export function getConfigPath() {
 export function getConfigBackupPath() {
     return join(resolution.root, 'config.json.bak');
 }
+/**
+ * `<home>/prompt-history.jsonl` — the prompts the user submitted, one JSON
+ * object per line. Deliberately NOT under `logs/`: that directory is governed
+ * by `log.toFile`, `log.maxFiles` and `aragon logs clear`, and turning
+ * diagnostics off or reclaiming disk must not also delete the user's `↑`
+ * recall (config-state-separation D-1).
+ */
+export function getPromptHistoryPath() {
+    return join(resolution.root, 'prompt-history.jsonl');
+}
+/** `<home>/state.json` — UI bookkeeping scalars only; see `ui-state.ts`. */
+export function getUiStatePath() {
+    return join(resolution.root, 'state.json');
+}
 export function getLogsDir() {
     return join(resolution.root, 'logs');
 }