@aragon-agent/cli 0.4.3 → 0.5.1

package/dist/agent/controller.js

@@ -13,6 +13,8 @@ import { isAdapterProvider } from '../config/schema.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { createBuiltinTools } from '../tools/index.js';
+import { createPlanTools } from '../tools/plan-tools.js';
+import { DENY_ALL_HUMAN_INPUT } from '../tools/human-input.js';
 import { createNodeSkillHost } from '../skills/node-host.js';
 import { SkillService } from '../skills/service.js';
 import { createSkillTools } from '../skills/tools.js';
@@ -33,9 +35,25 @@ export class AgentController {
     onSkillsChanged;
     /** Mutable session cwd — tools resolve relative paths against this. */
     cwd;
+    // -----------------------------------------------------------------------
+    // Plan mode (§3.1) — THE CONTROLLER OWNS THE MODE.
+    //
+    // It is the object the tools close over, so it is the only place that can
+    // answer "may this tool run?" at execute time. `ViewState.agentMode` is a
+    // MIRROR held for rendering, written only from what `setAgentMode` reports it
+    // adopted.
+    // -----------------------------------------------------------------------
+    effectiveMode;
+    pendingMode = null;
+    askRounds = 0;
+    /** Static: whether this session could ever render a question overlay. */
+    planInteractive;
     constructor(config, deps = {}) {
         this.config = config;
         this.cwd = config.cwd;
+        const humanInput = deps.humanInput ?? DENY_ALL_HUMAN_INPUT;
+        this.planInteractive = humanInput.neverPrompts !== true;
+        this.effectiveMode = config.startInPlanMode ? 'plan' : 'build';
         this.providerRegistry = initProviders();
         this.modelRegistry = new ModelRegistry(this.providerRegistry);
         this.skillsEnabled = config.skills.enabled;
@@ -62,15 +80,40 @@ export class AgentController {
             this.skills.discover();
             this.skills.reportUnknownForcedSkills();
         }
+        const confirm = deps.confirm;
         this.tools = createBuiltinTools({
             getCwd: () => this.cwd,
             confirmTools: config.confirmTools,
-            confirm: deps.confirm,
+            // Routed through the same watchdog pause as the plan tools. This is a
+            // pre-existing bug being fixed in passing: a `--confirm` user who took
+            // longer than `idleTimeoutMs` over `Proceed? (y/N)` had their run killed
+            // by the watchdog, and nothing said why (R-P3).
+            ...(confirm ? { confirm: (req) => this.withHumanWait(() => confirm(req)) } : {}),
             // `--no-skills` yields an empty array, so the tool list is byte-identical
             // to the pre-Skills seven (invariant I-S1 / AC-10).
             skillTools: this.skillsEnabled
                 ? createSkillTools(this.skills, deps.version, () => this.toolNames())
                 : [],
+            // Registered ONCE per session, whatever the current mode, and never
+            // rebuilt on a toggle (§3.4). `Agent.setTools()` unregisters and
+            // re-registers entries in the live `ToolRegistry`, and `submit_plan`
+            // mutates the mode from INSIDE a tool execution — rebuilding the array at
+            // that moment would mutate the registry mid-iteration. Keeping the array
+            // immutable removes the hazard entirely; the mode-dependent behaviour
+            // lives in the gate, which is a pure function of `getMode()`.
+            //
+            // Empty in headless mode, so the tool list there is still exactly the 7
+            // (or 11 with skills) it is today.
+            planTools: createPlanTools({
+                gate: humanInput,
+                takeAskRound: () => this.takeAskRound(),
+                withHumanWait: (fn) => this.withHumanWait(fn),
+                onPlanApproved: () => this.setAgentMode('build', { force: true }),
+            }),
+            // Read at CALL time, never cached: the mode flips mid-run when the user
+            // approves a plan, and a cached 'plan' would refuse the work they just
+            // authorized.
+            agentMode: () => this.effectiveMode,
             // Omitted entirely when skills are off, which is what leaves the seven
             // built-ins unwrapped and AC-G17 provable by object identity.
             ...(this.skillsEnabled
@@ -99,6 +142,14 @@ export class AgentController {
                 // Timeout invariant (R1): idle ≥ tool so long tool runs are not killed.
                 toolTimeout: config.toolTimeoutMs,
                 idleTimeout: config.idleTimeoutMs,
+                // A human wait is not a hung tool. 30 minutes by default, and the
+                // number only bites BECAUSE the plan tools race `ctx.signal` — the
+                // executor's timeout is cooperative, so an override is inert for any
+                // tool that does not listen (see API.md, "Blocking on a human").
+                toolTimeoutOverrides: {
+                    ask_user: config.planModeHumanTimeoutMs,
+                    submit_plan: config.planModeHumanTimeoutMs,
+                },
             },
         });
     }
@@ -139,6 +190,9 @@ export class AgentController {
             cwd: this.cwd,
             tools: this.tools,
             skillsBlock: this.skillsEnabled ? this.skills.catalogBlock() + this.skills.alwaysBlock() : '',
+            agentMode: this.effectiveMode,
+            planInteractive: this.planInteractive,
+            planMaxAskRounds: this.config.planModeMaxAskRounds,
         });
     }
     rebuildSystemPrompt() {
@@ -230,6 +284,11 @@ export class AgentController {
         // engine, which is what makes a per-turn scope implementable at all (FG9).
         if (this.skillsEnabled)
             this.skills.beginUserTurn();
+        // The ask-round budget is per USER TURN and resets here for the same reason
+        // the skill frame does. `steer()` deliberately does NOT reset it: a user
+        // steering "actually, use Postgres" into a running plan is answering the
+        // questions, not buying four more rounds of them.
+        this.askRounds = 0;
         return this.agent.prompt(text);
     }
     abort() {
@@ -251,6 +310,100 @@ export class AgentController {
         return this.agent.state.isRunning;
     }
     // -----------------------------------------------------------------------
+    // Plan mode (§3.1 / §3.2)
+    // -----------------------------------------------------------------------
+    getAgentMode() {
+        return this.effectiveMode;
+    }
+    /**
+     * Request a mode change and return what was ACTUALLY ADOPTED.
+     *
+     * Returning the adopted state rather than `void` is the whole point of this
+     * signature. The caller dispatches THIS value into the view, never the value
+     * it asked for — dispatching the request is the one way to make the badge lie
+     * about what the gate will do, and the API shape forecloses it (R-P7).
+     *
+     * The two directions are deliberately asymmetric:
+     *
+     *  - `build -> plan` applies IMMEDIATELY. Tightening a permission mid-run is
+     *    always safe; the user pressed the key *because* the agent is about to do
+     *    something they want to stop.
+     *  - `plan -> build` is DEFERRED to `agent_end`. Applying it live would mean a
+     *    run the user launched under a read-only guarantee could start writing
+     *    files because of one stray keypress.
+     *  - `{ force: true }` is the single exception, used only by `submit_plan`'s
+     *    approval path: the user has just read the plan and authorized exactly
+     *    that work. That is an informed act; a stray Shift+Tab is not. If this
+     *    code is ever refactored, that distinction is the thing to preserve.
+     */
+    setAgentMode(next, opts = {}) {
+        if (next === 'plan') {
+            this.effectiveMode = 'plan';
+            this.pendingMode = null;
+        }
+        else if (this.effectiveMode === 'build') {
+            // Already there. Clear any stale deferral rather than queueing a second.
+            this.pendingMode = null;
+        }
+        else if (opts.force || !this.isRunning()) {
+            this.effectiveMode = 'build';
+            this.pendingMode = null;
+        }
+        else {
+            this.pendingMode = 'build';
+        }
+        this.rebuildSystemPrompt();
+        return { effective: this.effectiveMode, pending: this.pendingMode };
+    }
+    /**
+     * Adopt a deferred `plan -> build` switch. Call from the App's `agent_end`
+     * handling. Returns `null` when nothing was pending, so the caller can skip
+     * both the dispatch and the toast.
+     */
+    applyPendingMode() {
+        if (!this.pendingMode)
+            return null;
+        this.effectiveMode = this.pendingMode;
+        this.pendingMode = null;
+        this.rebuildSystemPrompt();
+        return { effective: this.effectiveMode, pending: null };
+    }
+    /** Named read surface for `/plan status`, so no command reaches into internals. */
+    getPlanStatus() {
+        return {
+            effective: this.effectiveMode,
+            pending: this.pendingMode,
+            askRoundsUsed: this.askRounds,
+            maxAskRounds: this.config.planModeMaxAskRounds,
+        };
+    }
+    /** Spend one `ask_user` round. Called from the tool, never from the UI. */
+    takeAskRound() {
+        const max = this.config.planModeMaxAskRounds;
+        if (this.askRounds >= max) {
+            return { ok: false, used: this.askRounds, remaining: 0, max };
+        }
+        this.askRounds += 1;
+        return { ok: true, used: this.askRounds, remaining: max - this.askRounds, max };
+    }
+    /**
+     * Run `fn` with the idle watchdog paused.
+     *
+     * `try/finally` rather than two sequential calls: a throw inside the overlay
+     * path must not leave the watchdog disarmed for the rest of the run. Also used
+     * by the `--confirm` gate, which had exactly this bug — a user who took four
+     * minutes over `Proceed? (y/N)` had their run killed by the watchdog.
+     */
+    async withHumanWait(fn) {
+        this.agent.pauseIdleWatchdog();
+        try {
+            return await fn();
+        }
+        finally {
+            this.agent.resumeIdleWatchdog();
+        }
+    }
+    // -----------------------------------------------------------------------
     // Mutators
     // -----------------------------------------------------------------------
     setModel(provider, model, baseUrl) {

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

@@ -0,0 +1,18 @@
+/**
+ * The `<plan_mode>` system-prompt block (plan-mode §8).
+ *
+ * Spliced into `buildSystemPrompt` ONLY when the mode is `plan`, exactly as
+ * `skillsBlock` already is, so a build-mode prompt stays byte-identical to the
+ * pre-feature output (invariant I-P1).
+ *
+ * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
+ */
+/** Bump when the wording changes, so a transcript can be dated. */
+export declare const PLAN_MODE_BLOCK_VERSION = "v1-2026-07";
+export interface PlanModeBlockOptions {
+    /** False under `-p` / piped stdin: no overlay can be rendered, so no tools. */
+    interactive: boolean;
+    /** `planModeMaxAskRounds`; substituted into the guidance so the two agree. */
+    maxAskRounds: number;
+}
+export declare function buildPlanModeBlock(options: PlanModeBlockOptions): string;

package/dist/agent/plan-prompt.js

@@ -0,0 +1,93 @@
+/**
+ * The `<plan_mode>` system-prompt block (plan-mode §8).
+ *
+ * Spliced into `buildSystemPrompt` ONLY when the mode is `plan`, exactly as
+ * `skillsBlock` already is, so a build-mode prompt stays byte-identical to the
+ * pre-feature output (invariant I-P1).
+ *
+ * ASCII ONLY — `agent/` is inside the glyph scanner's scope.
+ */
+/** Bump when the wording changes, so a transcript can be dated. */
+export const PLAN_MODE_BLOCK_VERSION = 'v1-2026-07';
+/**
+ * The closing paragraph of the interactive block.
+ *
+ * THIS PARAGRAPH IS LOAD-BEARING, NOT BOILERPLATE (§3.9 / I-P9).
+ *
+ * `runLoopWithLifecycle` passes `systemPrompt: this.systemPrompt` BY VALUE into
+ * `runAgentLoop`, and every LLM call in the loop reads that same captured
+ * string. So the block cannot be rewritten mid-run — which matters most in the
+ * feature's headline flow: the user approves a plan, `submit_plan` flips the
+ * session to Build and returns "implement the plan", and the model is still
+ * holding a system prompt that says "you must not change anything on disk".
+ * The well-aligned resolution of that standoff is to refuse, which would break
+ * the whole point of the approval.
+ *
+ * Two halves must survive any edit: the read-only rule is SCOPED to "while PLAN
+ * MODE is active", and the approval result is NAMED as the authority that
+ * supersedes it. `plan-mode.test.ts` asserts both as a static regex, because
+ * the failure presents as "the model is being unhelpful today" rather than as a
+ * bug in this feature.
+ */
+const SUPERSEDE_PARAGRAPH = [
+    '- This block is written once, when the run starts, and is NOT re-issued if the',
+    '  mode changes during the run. A submit_plan result reporting that the plan was',
+    '  APPROVED is therefore authoritative and supersedes the read-only rule above',
+    '  for the remainder of this run: you are in Build mode, the tools are available,',
+    '  and you should implement the plan in order without asking again.',
+].join('\n');
+/** The headless replacement: there is no overlay, so there is nobody to ask. */
+const HEADLESS_PARAGRAPH = [
+    '- There is no interactive user. Do not ask questions and do not call submit_plan;',
+    '  write the finished plan as your final message in markdown.',
+].join('\n');
+export function buildPlanModeBlock(options) {
+    const { interactive, maxAskRounds } = options;
+    const askStep = interactive
+        ? [
+            '2. If a decision would change the work and you cannot settle it by reading, call',
+            '   ask_user with 3-5 multiple-choice questions in ONE call. Mark exactly one',
+            `   option recommended:true and put the reason in its description. You may ask up`,
+            `   to ${maxAskRounds} rounds; each round costs the user time, so make them count.`,
+        ]
+        : [
+            '2. If a decision would change the work and you cannot settle it by reading, state',
+            '   the assumption you are making and why, then continue. There is nobody to ask.',
+        ];
+    const submitStep = interactive
+        ? [
+            '3. Call submit_plan exactly once, with ordered steps a reviewer could check off.',
+            '   Name the real files you intend to touch. State the risks you actually found.',
+        ]
+        : [
+            '3. Finish with the full plan as your final message: ordered steps a reviewer could',
+            '   check off, the real files you intend to touch, and the risks you actually found.',
+        ];
+    const verdictRule = interactive
+        ? [
+            '- After submit_plan, wait for the verdict. If it is rejected, address the',
+            '  feedback and call submit_plan again.',
+        ]
+        : [];
+    return [
+        '<plan_mode>',
+        'You are in PLAN MODE. The user toggled it with Shift+Tab. This is a research and',
+        'design mode: you must not change anything on disk and must not run commands.',
+        '',
+        'Work in this order:',
+        '1. Ground yourself in the real code. Use read_file, list_dir, glob, grep and any',
+        '   relevant skill. Never plan against a directory structure you have not read.',
+        ...askStep,
+        ...submitStep,
+        '',
+        'Rules:',
+        '- While PLAN MODE is active, write_file, edit_file, bash, skill_install and',
+        '  skill_create are refused. Do not attempt to work around a refusal; finish the',
+        '  plan instead.',
+        '- Never ask a question the workspace already answers.',
+        '- Never invent a path. Cite files you have read.',
+        ...verdictRule,
+        interactive ? SUPERSEDE_PARAGRAPH : HEADLESS_PARAGRAPH,
+        '</plan_mode>',
+    ].join('\n');
+}

package/dist/agent/reducer.d.ts

@@ -11,9 +11,10 @@
  *     synthesizes a generic error notice (a swallowed throw is never a no-op).
  */
 import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agent/core';
+import type { AgentMode } from './agent-mode.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
-export type Overlay = null | 'settings' | 'model' | 'help' | 'confirm';
+export type Overlay = null | 'settings' | 'model' | 'help' | 'confirm' | 'question' | 'plan';
 export type ToolStatus = 'pending' | 'running' | 'done' | 'error';
 /** Ephemeral, auto-dismissed acknowledgement (spec §3.9). */
 export interface Toast {
@@ -72,6 +73,14 @@ export interface ViewState {
     toasts: Toast[];
     /** Which tool cards are expanded to their full stored preview (spec §3.7). */
     expandedToolIds: Record<string, true>;
+    /**
+     * MIRROR of the controller's effective mode, for rendering only (plan-mode
+     * §3.1). Written exclusively from what `controller.setAgentMode()` reports it
+     * adopted — never from what the UI asked for.
+     */
+    agentMode: AgentMode;
+    /** Set only by a DEFERRED `plan -> build`; drives the `PLAN -> BUILD` readout. */
+    pendingAgentMode: AgentMode | null;
     seq: number;
     streamingId?: string;
     turnProduced: boolean;
@@ -152,6 +161,10 @@ export type ViewAction = {
 } | {
     type: 'restoreEntries';
     entries: Entry[];
+} | {
+    type: 'setAgentMode';
+    mode: AgentMode;
+    pending: AgentMode | null;
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;

package/dist/agent/reducer.js

@@ -23,6 +23,10 @@ export function initialViewState() {
         thinkingVisible: true,
         toasts: [],
         expandedToolIds: {},
+        // Seeded to the default posture; the App overrides it once on mount from
+        // `controller.getAgentMode()` so `--plan` renders on the first frame.
+        agentMode: 'build',
+        pendingAgentMode: null,
         seq: 0,
         streamingId: undefined,
         turnProduced: false,
@@ -376,6 +380,11 @@ export function viewReducer(state, action) {
             };
         case 'setOverlay':
             return { ...state, overlay: action.overlay };
+        // Pure mirror write. The App only ever dispatches what
+        // `controller.setAgentMode()` reported it ADOPTED, so this reducer has no
+        // deferral logic of its own to get out of step with (§3.1 / R-P7).
+        case 'setAgentMode':
+            return { ...state, agentMode: action.mode, pendingAgentMode: action.pending };
         case 'toggleThinking':
             return { ...state, thinkingVisible: !state.thinkingVisible };
         case 'pushToast': {

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

@@ -7,6 +7,7 @@
  * the available tools with their working directory.
  */
 import type { AgentTool } from '@aragon-agent/core';
+import type { AgentMode } from './agent-mode.js';
 export interface SystemPromptParams {
     cwd: string;
     tools: AgentTool[];
@@ -21,6 +22,20 @@ export interface SystemPromptParams {
      * an unconditional extra guidance line would quietly break all three.
      */
     skillsBlock?: string;
+    /**
+     * The session's current mode. Absent or `'build'` produces a BYTE-IDENTICAL
+     * prompt to the pre-plan-mode output for a fixed `tools` array (I-P1) — the
+     * `<plan_mode>` block is spliced conditionally, exactly as `skillsBlock` is.
+     */
+    agentMode?: AgentMode;
+    /**
+     * Whether a human can actually be reached. Only read when `agentMode` is
+     * `'plan'`: the headless variant of the block tells the model to write the
+     * plan as its final message instead of calling tools it does not have.
+     */
+    planInteractive?: boolean;
+    /** `planModeMaxAskRounds`, substituted into the block so the two agree. */
+    planMaxAskRounds?: number;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -8,6 +8,7 @@
  */
 import os from 'node:os';
 import process from 'node:process';
+import { buildPlanModeBlock } from './plan-prompt.js';
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export function describeShell() {
     const platform = process.platform;
@@ -30,6 +31,12 @@ export function buildSystemPrompt(params) {
         : `The bash tool runs commands through ${shell} ("/bin/sh -c"). Standard POSIX syntax is fine.`;
     const skillsBlock = params.skillsBlock ?? '';
     const hasSkills = skillsBlock.length > 0;
+    const planBlock = params.agentMode === 'plan'
+        ? buildPlanModeBlock({
+            interactive: params.planInteractive !== false,
+            maxAskRounds: params.planMaxAskRounds ?? 4,
+        })
+        : '';
     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.',
@@ -42,6 +49,7 @@ export function buildSystemPrompt(params) {
         'Available tools:',
         toolList,
         ...(hasSkills ? ['', skillsBlock] : []),
+        ...(planBlock ? ['', planBlock] : []),
         '',
         'Operating guidance:',
         '- Prefer reading files and inspecting the workspace before making changes.',

package/dist/cli.d.ts

@@ -8,4 +8,4 @@
  *
  * The shebang is prepended post-build by scripts/prepend-shebang.mjs.
  */
-export {};
+import '../runtime/insecure-tls-warning.cjs';