@aragon-agent/cli 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,137 @@ All notable changes to `@aragon-agent/cli` are documented here. Entries at
 — those releases really were published under that name, so they are left as they
 were written.
 
+## Unreleased
+
+### Changed
+
+- **Your files moved to `~/.aragon-agent/`.** Config, sessions, installed skills
+  and the usage counters now live in one directory in your home — on Windows
+  `C:\Users\<you>\.aragon-agent\`, and the same path on macOS and Linux. They
+  used to be split across `%APPDATA%\aragon-agent-nodejs\Config` and
+  `%LOCALAPPDATA%\aragon-agent-nodejs\Data` (or the XDG equivalents), which are
+  correct locations and terrible answers to "where do I change the model?".
+
+  **The move happens once, automatically, on first launch, and prints a line on
+  stderr when it does.** Nothing is deleted: `config.json` is COPIED rather than
+  moved, and the old directories are left where they are, so reinstalling 0.5.0
+  remains lossless. `aragon config home` prints the new location and names the
+  old ones. Once you are satisfied, you can delete them yourself.
+
+  `ARAGON_HOME` relocates the whole tree. It has to be a real environment
+  variable — the path is resolved before any `.env` is read, so putting it in a
+  `.env` will not work. `aragon config home` always prints what is actually in
+  use.
+
+### Added
+
+- **Logging.** Records go to `~/.aragon-agent/logs/aragon-<date>.log` as JSON
+  Lines: startup and exit, config writes, turn boundaries with token counts,
+  tool names with durations, skill loads, and every uncaught error. Files rotate
+  by day and by size (`log.maxFileBytes`, default 5 MiB) and the oldest beyond
+  `log.maxFiles` (default 10) are deleted.
+
+  **`info`, the default, records no conversation content**, so attaching a log
+  to a bug report is safe. `--log-level debug` (or `--verbose`) adds prompts,
+  replies and tool arguments truncated to `log.previewChars`; `trace` adds them
+  in full. Those two write what you typed — check before sharing one.
+
+  API keys are removed at every level by two independent passes: fields whose
+  name looks like a credential are blanked whatever they hold, and every string
+  is scanned both for known key formats and for the literal keys this process is
+  holding — which is what covers a custom endpoint whose key looks like nothing
+  in particular. `log.redactSecrets false` turns both off and warns you on
+  stdout when you set it.
+
+  Nothing is ever uploaded. There is no network path out of this subsystem.
+
+  New commands: `aragon logs path | list | tail [-n N] [--follow] [--level lv]
+  [--json] | clear --yes | open`, and `/logs` inside the TUI. New flags:
+  `--log-level`, `--verbose`, `--log-file` / `--no-log-file`, `--log-dir`. New
+  environment variables: `ARAGON_LOG_LEVEL`, `ARAGON_LOG_FILE`, `ARAGON_LOG_DIR`
+  — these three, unlike `ARAGON_HOME`, can come from a `.env`.
+
+- **`aragon config get <key>` / `list [--json]` / `edit` / `home`.** `get` and
+  `list` mask every secret, `--json` included. `edit` opens `config.json` in
+  `$VISUAL` / `$EDITOR` (`notepad` on Windows), takes a `config.json.bak` first,
+  and re-parses on exit — an invalid edit is reported immediately, and the
+  backup is named in the message.
+
+- **`/reload`** re-reads `config.json` into the running session, for when you
+  have edited it in another window. Refused while a run is in progress: swapping
+  the model mid-turn would let the second half of an answer come from different
+  settings than the first, with nothing afterwards able to explain the result.
+
+- **Log level in the settings screen**, alongside provider / model / thinking.
+  The rest of the log settings — and `redactSecrets` above all — stay
+  command-line-only, so the one switch that can put credentials on disk cannot
+  be flipped with an arrow key.
+
+### Fixed
+
+- **A malformed `config.json` no longer resets everything in silence.** A stray
+  comma used to send the model, theme, timeouts, skills and (as far as you could
+  tell) your API key back to defaults, with nothing anywhere explaining it. The
+  fallback is unchanged — a bad config still never stops the CLI from starting —
+  but it now says so, and records why.
+
+- **Ctrl+C now flushes pending log records in every mode.** The signal handlers
+  only existed in the full-screen branch, so `-p`, the inline renderer and every
+  subcommand took Node's default termination, which does not run exit handlers.
+
+### Added
+
+- **Plan mode.** `Shift+Tab` toggles between `BUILD` (everything as before) and
+  `PLAN`, a read-only research-and-design posture. `/plan [on|off|status]` is a
+  first-class equivalent for terminals that swallow `CSI Z`, and `--plan` /
+  `--no-plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the startup case.
+
+  In `PLAN`, `write_file`, `edit_file`, `bash`, `skill_install` and
+  `skill_create` are refused **at the tool boundary**, so read-only is a
+  property of the wiring rather than a promise in a prompt. `bash` is refused in
+  full, `git status` included: a shell string cannot be classified reliably, and
+  a gate that is right most of the time is worse than one that is always right,
+  because you stop trusting the badge. The refusal names `read_file` / `glob` /
+  `grep` as the alternatives.
+
+  Two tools exist only while a human is attached. `ask_user` renders a
+  keyboard-driven wizard - 1-5 questions, 2-4 options each, exactly one marked
+  `RECOMMENDED`, plus an `Other...` free-text option - where pressing `Enter`
+  through the wizard accepts every recommendation. `submit_plan` renders the
+  plan as a scrollable card: `a` approves, `r` sends written feedback (`<-`
+  returns to the card), `Esc` dismisses. **Approving flips the session to
+  `BUILD` immediately and the same run continues into implementation.**
+
+  Dismissing a plan asks for a better one rather than stopping - the agent is
+  told to refine and resubmit - so the way out of a run is `Esc` twice: the
+  first closes the card, the second aborts the run.
+
+  Toggling mid-run is asymmetric on purpose: `build -> plan` applies at once,
+  `plan -> build` is deferred to the end of the run (the status bar shows
+  `PLAN -> BUILD` meanwhile) so a run launched under a read-only guarantee
+  cannot start writing files because of one stray keypress.
+
+  `aragon -p --plan "..."` registers no question or plan tool - there is nobody
+  to ask - but the read-only gate still applies, so it means "tell me how you
+  would do this, and do not touch my repository".
+
+- Three flat config keys: `planModeDefault` (default `false`),
+  `planModeMaxAskRounds` (default `4`, clamped `[1, 10]`) and
+  `planModeHumanTimeoutMs` (default `1800000`, clamped `[60000, 7200000]`). All
+  three are settable with `aragon config set`. Additive, as always: a config
+  file written by an earlier version loads unchanged.
+
+### Fixed
+
+- A `--confirm` prompt no longer races the idle watchdog. Taking longer than
+  `idleTimeoutMs` over `Proceed? (y/N)` used to abort the run with no
+  explanation; every human wait now suspends the watchdog and restarts it in a
+  `finally`.
+
+- Honor an explicit `NODE_TLS_REJECT_UNAUTHORIZED=0` setting in the CLI and the
+  official npm release workflow while hiding only Node's standard insecure-TLS
+  warning. Other process warnings remain visible.
+
 ## 0.5.0
 
 ### Breaking

package/README.md

@@ -71,6 +71,7 @@ aragon --help  | -h             Print help
 | `--fullscreen` | Force the full-screen TUI, overriding the automatic downgrades |
 | `--no-fullscreen` | Force the inline renderer (the 0.2.0 behavior) |
 | `--no-exit-transcript` | Do not replay the session summary after exiting |
+| `--plan` / `--no-plan` | Start the session in PLAN mode (read-only research + review) or force BUILD |
 | `--no-skills` | Disable the skill system entirely (no catalog, no skill tools) |
 | `--skill <name>` | Force-load a skill's full body for this run (repeatable) |
 | `--skills-yes` | Approve skill installs for this run (CI / headless) |
@@ -94,9 +95,12 @@ Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
 | `/cwd [dir]` | Show / change the tool working directory |
 | `/save [file]` | Save the session to JSON |
 | `/resume [file]` | Load a saved session |
+| `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
 | `/theme <auto\|warm\|cool\|light>` | Switch the color theme live (persisted) |
 | `/expand [n]` | Expand / collapse the n-th-from-last (default last) tool card |
 | `/copy` | Copy the last answer to the clipboard |
+| `/logs` | Show where this session is being logged, and at what level |
+| `/reload` | Re-read `config.json` after editing it in another window (refused mid-run) |
 | `/skills [sub]` | List and manage skills (see below) |
 | `/<skill-name> [args]` | Run an installed skill directly |
 | `/exit` (`/quit`) | Exit |
@@ -111,6 +115,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | --- | --- |
 | `Enter` | Submit (idle) / queue a steering message (running) |
 | `Alt+Enter` / `Shift+Enter` | Insert a newline |
+| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan` |
 | `Esc` | Abort the run / close an overlay / close a popup |
 | `Ctrl+C` ×2 | Exit (first press warns) |
 | `Ctrl+L` | Redraw the frame (clear the screen in inline mode) |
@@ -184,6 +189,90 @@ this mode, and mouse tracking is deliberately left off because enabling it costs
 text selection and copy in most terminals. If a crash ever strands your terminal
 on the alternate screen, `reset` restores it.
 
+## Plan mode
+
+`aragon` has two postures, and `Shift+Tab` switches between them. `/plan` does
+the same thing for terminals that swallow the key (see below).
+
+| Mode | What it means |
+| --- | --- |
+| `BUILD` | The default, and unchanged from earlier versions: you ask, the agent does it. |
+| `PLAN` | Research and design only. The agent reads, asks you the decisions it cannot settle by reading, and submits a plan for approval before anything is written. |
+
+`BUILD` is right for "rename this symbol". `PLAN` is right for "add multi-tenant
+support" — anything where you want to see and steer the *approach* before a
+single byte changes.
+
+### What plan mode actually stops
+
+In `PLAN`, five tools are refused at the tool boundary: `write_file`,
+`edit_file`, `bash`, `skill_install` and `skill_create`. That is a property of
+the wiring, not a promise in a prompt — the refusal happens before the tool runs,
+so the badge is telling you something that is structurally true.
+
+**`bash` is refused in full, `git status` included.** This is the most likely
+question this feature generates, so: there is no reliable way to classify a shell
+string as read-only, and a gate that is right 95 % of the time is worse than one
+that is always right, because you stop trusting the badge. Use `read_file`,
+`list_dir`, `glob` and `grep`, which stay available; the refusal message names
+them so the agent has somewhere to go. There is no allowlist and there will not
+be one built out of substring matching.
+
+Everything else still works: reading, searching, loading skills, and asking you
+questions.
+
+### The two plan-mode tools
+
+- **`ask_user`** renders a keyboard-driven wizard: 1–5 questions, 2–4 options
+  each, exactly one marked `RECOMMENDED`, plus an `Other…` free-text option.
+  `↑`/`↓` choose, `Enter` confirms and advances, `←` goes back, `Esc` cancels.
+  Pressing `Enter` through the whole wizard accepts every recommendation, which
+  is a deliberate "use your judgement" path rather than an accident. A last
+  screen lets you review before submitting.
+- **`submit_plan`** renders the plan as a scrollable card: `a` approves, `r`
+  opens a one-line feedback field (`Enter` sends it, `←` goes back to the card),
+  `Esc` dismisses. **Approving flips the session to `BUILD` immediately and the
+  same run continues straight into implementation** — you do not have to re-ask.
+
+Cancelling either one is not an error. The agent is told to proceed on stated
+assumptions rather than to retry.
+
+**Dismissing a plan is not how you stop.** `Esc` on a plan card asks for a
+*better* plan — the agent is told to refine it and submit again — so a model that
+keeps submitting keeps getting cards. To stop the run itself, **press `Esc`
+twice**: the first closes the card, the second aborts the run. `Ctrl+C` twice
+still exits the session outright.
+
+### Where the mode is shown
+
+The status bar always names a non-default mode (`PLAN`, or `PLAN → BUILD` while
+a switch is pending), including on short terminals, with `--no-hints`, and in
+inline mode. The composer additionally shows a `PLAN` chip on its hint row and
+tints its border, where there is room for it.
+
+### Switching mid-run
+
+Tightening applies at once; loosening waits. Pressing `Shift+Tab` toward `PLAN`
+during a run takes effect immediately — you pressed it *because* the agent is
+about to do something. Pressing it toward `BUILD` during a run is **deferred to
+the end of the run**, so a session you launched under a read-only guarantee
+cannot start writing files because of one stray keypress. The status bar shows
+`PLAN → BUILD` while that is pending. Approving a plan is the one exception, and
+it is an informed act rather than a stray keypress.
+
+### If `Shift+Tab` does nothing
+
+Some multiplexers and remote-desktop stacks never send `CSI Z`. `/plan`,
+`/plan on`, `/plan off` and `/plan status` are first-class equivalents, and
+`--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the startup case.
+
+### Headless
+
+`aragon -p --plan "add SSO"` is a useful combination: the read-only gate still
+applies, so it means *"tell me how you would do this, and do not touch my
+repository"*. No question or plan tool is registered there — there is nobody to
+ask — and the agent writes the finished plan as its final message in markdown.
+
 ## Built-in tools
 
 `read_file`, `write_file`, `edit_file`, `list_dir`, `glob`, `grep`, `bash` — all
@@ -484,17 +573,26 @@ 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_FULLSCREEN`, `ARAGON_SKILLS` (`0` disables), `ARAGON_SKILLS_PATH`,
-  `ARAGON_SKILLS_DISABLED` (comma-separated names).
+  `ARAGON_FULLSCREEN`, `ARAGON_PLAN` (`1` starts in plan mode),
+  `ARAGON_SKILLS` (`0` disables), `ARAGON_SKILLS_PATH`,
+  `ARAGON_SKILLS_DISABLED` (comma-separated names), `ARAGON_LOG_LEVEL`,
+  `ARAGON_LOG_FILE` (`0` disables), `ARAGON_LOG_DIR`.
+  `ARAGON_HOME` is the exception that **cannot** come from `.env`: it is read
+  before any `.env` is loaded. See [Files & logs](#files--logs).
 - **User config file** (`aragon config path`): JSON, written `0600` on POSIX.
   Holds provider/model/keys and MRU lists. Keys are masked in the UI and never
-  logged.
+  logged. It lives in your home directory — see [Files & logs](#files--logs) —
+  and editing it by hand is supported: `aragon config edit` opens it, and an
+  invalid edit is reported rather than silently resetting every setting.
 
 | Config key | Default | Meaning |
 | --- | --- | --- |
 | `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`. |
+| `planModeDefault` | `false` | Start every session in plan mode. `--no-plan` still overrides it for a single run. |
+| `planModeMaxAskRounds` | `4` | `ask_user` rounds allowed per user message, clamped to `[1, 10]`. The counter resets on your next message; steering does **not** reset it. |
+| `planModeHumanTimeoutMs` | `1800000` | Ceiling on a single question / plan wait, clamped to `[60000, 7200000]`. Thirty minutes is far outside "went to get coffee", but a ceiling has to exist so an unattended terminal cannot wedge a CI job forever. |
 | `skills.enabled` | `true` | Master switch for the skill system. |
 | `skills.requireApproval` | `true` | Require a human to approve `skill_install` / `skill_create`. |
 | `skills.catalogMaxBytes` | `6000` | Level 1 catalog ceiling, in UTF-8 **bytes**, clamped to `[500, 40000]`. |
@@ -505,6 +603,13 @@ env / `.env` → CLI flags**.
 | `skills.integrity` | `warn` | What to do when `SKILL.md` no longer matches the copy you approved. `off` skips the check; `warn` flags it in `/skills list` and once per session; `strict` removes it from the catalog and makes `skill()` refuse it. Defaults to `warn` because editing an installed skill is a legitimate thing to do — `strict` suits CI and managed environments. |
 | `skills.usageTracking` | `true` | Keep local per-skill use counters to rank the catalog. Name, count and timestamp only; never transmitted. Inspect with `aragon skills usage`, erase with `--reset --yes`. |
 | `skills.toolPolicy` | `enforce` | How hard a skill's `allowed-tools` bites, for the turn it is loaded in. `off` disables it and says nothing about it to the model; `warn` runs the tool and reports it; `enforce` refuses. Unlike `skills.integrity`, a false positive here means a skill AUTHOR under-declared their own skill — which `aragon skills doctor` reports before it can bite. |
+| `log.level` | `info` | `silent` · `error` · `warn` · `info` · `debug` · `trace`. See [Files & logs](#files--logs) for what each level records. |
+| `log.toFile` | `true` | Write records to a file at all. `false` here is respected; `--log-file` overrides it for one run. |
+| `log.dir` | `""` | Log directory. Empty means `<home>/logs`. Only **absolute** paths are accepted — a relative one would mean a different directory for every working directory you launch from. |
+| `log.maxFileBytes` | `5242880` | Rotate once a file would exceed this, clamped to `[65536, 268435456]`. |
+| `log.maxFiles` | `10` | Files kept in the log directory, clamped to `[1, 200]`. The oldest beyond this are deleted — on rotation **and** on the first write of each day. |
+| `log.redactSecrets` | `true` | Run every record through redaction. Setting it to `false` is the one way to get credentials onto disk, so it prints a warning and has no settings-screen entry. |
+| `log.previewChars` | `512` | How much user content `debug` keeps per field, clamped to `[0, 8192]`. `trace` is never truncated. |
 
 Byte, not character: `ToolExecutor` truncates at 100 000 **bytes**, so a
 character-based budget would be roughly triple its nominal size for CJK text
@@ -513,6 +618,108 @@ and would get cut mid-tag.
 These are additive: a config file written by an earlier version loads
 unchanged, with no migration and no version bump.
 
+## Files & logs
+
+Everything AragonAgent keeps for you lives under one directory in your home:
+
+```
+~/.aragon-agent/                    (Windows: C:\Users\<you>\.aragon-agent\)
+├── config.json                     settings + API keys (0600 on POSIX)
+├── config.json.bak                 written by `aragon config edit` before it opens
+├── logs/
+│   ├── aragon-2026-07-27.log       today, JSON Lines
+│   └── aragon-2026-07-27.1.log     rotated at log.maxFileBytes
+├── sessions/                       /save and /resume
+├── skills/                         aragon skills install
+└── skill-usage.json
+```
+
+`ARAGON_HOME` moves the whole tree. **It cannot come from a `.env` file** — the
+path is resolved when the process starts, long before a `.env` is read — so set
+it as a real environment variable. `aragon config home` always prints the
+directory actually in use.
+
+Upgrading from 0.5.0 or earlier moves your config, sessions and skills here
+automatically, once, and prints a line on stderr when it does. The old
+`%APPDATA%\aragon-agent-nodejs` / `%LOCALAPPDATA%\aragon-agent-nodejs`
+directories are **left in place** so that reinstalling an older build stays
+lossless; `aragon config home` names them, and you can delete them once you are
+satisfied.
+
+### What gets logged
+
+Logs are local files. Nothing is uploaded, ever — there is no network path out
+of this subsystem at all.
+
+| Level | Records | Contains your content? |
+| --- | --- | --- |
+| `error` | crashes, failed requests, config write/parse failures | no |
+| `warn` | degraded migrations, clamped values, dropped records | no |
+| `info` *(default)* | start/exit, config writes, turn boundaries with token counts, tool names and durations | **no** |
+| `debug` | the above, plus prompts, replies and tool arguments truncated to `log.previewChars` | yes, truncated |
+| `trace` | full message bodies and full tool output | yes, in full |
+
+The default is `info` specifically so that attaching a log to a bug report is
+safe. **`debug` and `trace` write what you typed and what the model replied** —
+check before sharing one.
+
+API keys are removed at every level, by two independent passes: any field whose
+name looks like a credential is blanked whatever it holds, and every string is
+scanned for known key formats *and* for the literal keys this process is
+holding. The second half is what covers a custom endpoint whose key looks like
+nothing in particular. Setting `log.redactSecrets false` disables both, and says
+so on stdout when you do.
+
+### Commands
+
+```bash
+aragon logs path              # where records are going right now, and at what level
+aragon logs list              # files, sizes, timestamps
+aragon logs tail -n 50        # render the last 50 records
+aragon logs tail --follow     # keep printing new ones
+aragon logs tail --json       # raw JSON Lines, for jq
+aragon logs tail --level warn # only warn and above
+aragon logs clear --yes       # delete every log file
+aragon logs open              # open the directory in your file manager
+
+aragon config home            # the user-state root (and whether ARAGON_HOME set it)
+aragon config get log.level   # one value; secrets always masked
+aragon config list --json     # everything; secrets always masked here too
+aragon config edit            # open config.json in $VISUAL / $EDITOR
+```
+
+Per-run overrides, none of which are persisted:
+
+```bash
+aragon --log-level debug "…"   # or --verbose, which means the same thing
+aragon --no-log-file "…"       # nothing reaches a file this run
+aragon --log-dir D:\logs "…"
+```
+
+`ARAGON_LOG_LEVEL`, `ARAGON_LOG_FILE=0` and `ARAGON_LOG_DIR` do the same from the
+environment, and unlike `ARAGON_HOME` these three *can* come from a `.env`.
+
+### Insecure TLS opt-in
+
+When `NODE_TLS_REJECT_UNAUTHORIZED` is the exact string `0`, the installed or
+locally built `aragon` process honors that setting and suppresses only Node's
+standard insecure-TLS warning. Every unrelated process warning remains visible,
+and any other value leaves warning behavior unchanged. The check happens when a
+warning is emitted, so a `0` loaded from the project `.env` is covered too; the
+CLI never creates, normalizes, or persists this variable.
+
+> **Security warning:** `0` genuinely disables certificate verification. It does
+> not make an insecure connection safe and can expose credentials or request
+> contents to interception. Use it only in a controlled environment where you
+> accept that risk.
+
+The automatic filter starts with the `aragon` process. An earlier `npm install`
+or `npx` bootstrap belongs to npm and is outside the installed package's process
+boundary, so that parent may still print Node's warning. The official repository
+release flow covers its npm children through `publish-latest.ps1`; callers that
+own another npm/npx parent must preload the filter in that parent themselves if
+quiet output is required.
+
 ### Theming & color
 
 `--theme` / `config.theme` / `/theme` pick a palette: `warm`, `cool`, `light`, or
@@ -552,6 +759,23 @@ node packages/cli/dist/cli.js --version
 - `echo "list files" | node dist/cli.js -p` prints an answer and exits `0`.
 - A missing/invalid key produces a visible, actionable message (never a blank
   screen), both in the TUI and headless.
+- `Shift+Tab` at 40, 80 and 120 columns - the chip, the hint and the status bar
+  are all legible and nothing wraps onto a second row.
+- The question wizard at 24 rows with 5 questions x 4 options - no clipping, and
+  the `n/N` counter matches what is on screen.
+- Approve a plan and watch the SAME run start writing files, with no second
+  prompt.
+- `--no-color` on a legacy `cmd.exe` - the chip renders `[PLAN]`, radios render
+  `*`/`o`, checkboxes render `[x]`/`[ ]`, no mojibake anywhere.
+- A plan with a 600-character summary and a 400-character step detail - the text
+  wraps and scrolls, the footer count matches the real number of rows, and
+  nothing is truncated to a single line.
+- `--no-hints` on a 20-row terminal in plan mode - the status bar still says
+  `PLAN` with no chip on screen.
+- Dismiss a plan card with `Esc`, let the agent resubmit, then press `Esc` twice:
+  the run aborts and the session returns to an idle prompt. Do this one BY HAND
+  as well as in a test - the point of the check is whether the exit is findable,
+  which no assertion can tell you.
 
 ## License
 

package/dist/agent/agent-mode.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Agent mode vocabulary (plan-mode §5.1).
+ *
+ * Pure: no React, no I/O, no `node:*`. Imported by the controller, the tool
+ * gate, the prompt builder, the slash command and four UI components, which is
+ * exactly why it must stay free of every one of their dependencies.
+ *
+ * `PLAN_MODE_BLOCKED_TOOLS` is deliberately NOT here. It lives in
+ * `tools/index.ts` beside `SKILL_TOOL_FLOOR`, because the invariant worth having
+ * is that the two sets PARTITION `HOST_TOOL_NAMES` — and a partition test is
+ * only as trustworthy as the distance between the two definitions. This file
+ * owns the mode vocabulary; that file owns which tools the modes act on.
+ *
+ * ASCII ONLY in every string literal below. `agent/` is inside the glyph
+ * scanner's scope (`glyphs.test.ts`), so a stray ellipsis here fails the build —
+ * which is why `OTHER_OPTION_LABEL` is a bare word and the ellipsis is appended
+ * at render time from `glyphs.ellipsis`.
+ */
+export type AgentMode = 'build' | 'plan';
+export declare const AGENT_MODES: readonly AgentMode[];
+/** The user-visible word for each mode. English, per the repo convention. */
+export declare const MODE_LABEL: Record<AgentMode, string>;
+/**
+ * The next mode in the cycle.
+ *
+ * Written as a cycle rather than a boolean flip so that adding Claude Code's
+ * "auto-accept edits" as a third posture is a one-line change to `AGENT_MODES`
+ * and nothing else. Two ship today (§1 non-goals).
+ */
+export declare function nextMode(current: AgentMode): AgentMode;
+/** The two tools that only exist because a human is attached. */
+export declare const PLAN_TOOL_NAMES: readonly ["ask_user", "submit_plan"];
+/**
+ * The synthetic free-text option appended to every question.
+ *
+ * Plain `Other`, with no ellipsis: this module is inside the glyph scanner's
+ * scope, and the overlay appends `glyphs.ellipsis` itself so the label degrades
+ * to `Other...` on a terminal without Unicode.
+ */
+export declare const OTHER_OPTION_LABEL = "Other";
+/**
+ * Why a mutating tool was refused in plan mode.
+ *
+ * The wording carries weight beyond politeness (§3.9). A run that flips
+ * `build -> plan` mid-flight keeps its original system prompt to the end — the
+ * loop reads `ctx.systemPrompt`, which was copied by value when the run
+ * started — so for the rest of that run this refusal is the ONLY place the
+ * model learns that plan mode is on. A bare "not permitted" reads as a tool
+ * malfunction and gets retried.
+ */
+export declare function planRefusal(tool: string): string;
+/** Why `submit_plan` was refused outside plan mode. */
+export declare function submitPlanRefusal(): string;

package/dist/agent/agent-mode.js

@@ -0,0 +1,69 @@
+/**
+ * Agent mode vocabulary (plan-mode §5.1).
+ *
+ * Pure: no React, no I/O, no `node:*`. Imported by the controller, the tool
+ * gate, the prompt builder, the slash command and four UI components, which is
+ * exactly why it must stay free of every one of their dependencies.
+ *
+ * `PLAN_MODE_BLOCKED_TOOLS` is deliberately NOT here. It lives in
+ * `tools/index.ts` beside `SKILL_TOOL_FLOOR`, because the invariant worth having
+ * is that the two sets PARTITION `HOST_TOOL_NAMES` — and a partition test is
+ * only as trustworthy as the distance between the two definitions. This file
+ * owns the mode vocabulary; that file owns which tools the modes act on.
+ *
+ * ASCII ONLY in every string literal below. `agent/` is inside the glyph
+ * scanner's scope (`glyphs.test.ts`), so a stray ellipsis here fails the build —
+ * which is why `OTHER_OPTION_LABEL` is a bare word and the ellipsis is appended
+ * at render time from `glyphs.ellipsis`.
+ */
+export const AGENT_MODES = ['build', 'plan'];
+/** The user-visible word for each mode. English, per the repo convention. */
+export const MODE_LABEL = { build: 'BUILD', plan: 'PLAN' };
+/**
+ * The next mode in the cycle.
+ *
+ * Written as a cycle rather than a boolean flip so that adding Claude Code's
+ * "auto-accept edits" as a third posture is a one-line change to `AGENT_MODES`
+ * and nothing else. Two ship today (§1 non-goals).
+ */
+export function nextMode(current) {
+    const index = AGENT_MODES.indexOf(current);
+    return AGENT_MODES[(index + 1) % AGENT_MODES.length];
+}
+/** The two tools that only exist because a human is attached. */
+export const PLAN_TOOL_NAMES = ['ask_user', 'submit_plan'];
+/**
+ * The synthetic free-text option appended to every question.
+ *
+ * Plain `Other`, with no ellipsis: this module is inside the glyph scanner's
+ * scope, and the overlay appends `glyphs.ellipsis` itself so the label degrades
+ * to `Other...` on a terminal without Unicode.
+ */
+export const OTHER_OPTION_LABEL = 'Other';
+/** Read-only alternatives named in every refusal, so the model has somewhere to go. */
+const READ_ONLY_ALTERNATIVES = 'read_file / list_dir / glob / grep';
+/**
+ * Why a mutating tool was refused in plan mode.
+ *
+ * The wording carries weight beyond politeness (§3.9). A run that flips
+ * `build -> plan` mid-flight keeps its original system prompt to the end — the
+ * loop reads `ctx.systemPrompt`, which was copied by value when the run
+ * started — so for the rest of that run this refusal is the ONLY place the
+ * model learns that plan mode is on. A bare "not permitted" reads as a tool
+ * malfunction and gets retried.
+ */
+export function planRefusal(tool) {
+    const extra = tool === 'bash'
+        ? ' bash is refused in full, including read-only commands like "git status":' +
+            ' a shell string cannot be classified reliably, and a gate that is right' +
+            ' most of the time is worse than one that is always right.'
+        : '';
+    return (`Plan mode is active, so ${tool} is refused.${extra}` +
+        ` Use ${READ_ONLY_ALTERNATIVES} to research, then call submit_plan.` +
+        ' Do not try to work around this; finish the plan instead.');
+}
+/** Why `submit_plan` was refused outside plan mode. */
+export function submitPlanRefusal() {
+    return ('submit_plan is only available in Plan mode. You are in Build mode - ' +
+        'just do the work and summarize when you are done.');
+}

package/dist/agent/controller.d.ts

@@ -11,7 +11,9 @@
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
 import type { CliConfig, ThemeName } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
+import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
+import type { AgentMode } from './agent-mode.js';
 import type { NoticeLevel } from './reducer.js';
 /** Approval gate used whenever there is provably no human to ask (headless). */
 export declare const DENY_ALL_APPROVAL: ApprovalGate;
@@ -37,6 +39,24 @@ export interface ControllerDeps {
     onSkillsChanged?: () => void;
     /** Transcript notices from the skill subsystem. */
     notify?: (level: NoticeLevel, text: string) => void;
+    /**
+     * The plan-mode human channel (§3.5). Defaults to `DENY_ALL_HUMAN_INPUT`, so
+     * forgetting to pass one registers NO plan tools rather than registering tools
+     * that would hang. A THIRD approval channel on purpose: `confirm` auto-approves
+     * when unattached and `approval` denies, but neither can render a question
+     * wizard or a plan card.
+     */
+    humanInput?: HumanInputGate;
+}
+/** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
+export interface AgentModeState {
+    effective: AgentMode;
+    /** Non-null only while a `plan -> build` switch is waiting for `agent_end`. */
+    pending: AgentMode | null;
+}
+export interface PlanStatus extends AgentModeState {
+    askRoundsUsed: number;
+    maxAskRounds: number;
 }
 export interface PreflightResult {
     ok: boolean;
@@ -55,6 +75,11 @@ export declare class AgentController {
     private onSkillsChanged?;
     /** Mutable session cwd — tools resolve relative paths against this. */
     private cwd;
+    private effectiveMode;
+    private pendingMode;
+    private askRounds;
+    /** Static: whether this session could ever render a question overlay. */
+    private readonly planInteractive;
     constructor(config: CliConfig, deps?: ControllerDeps);
     private resolveKey;
     /**
@@ -110,6 +135,50 @@ export declare class AgentController {
     steer(text: string): void;
     followUp(text: string): void;
     isRunning(): boolean;
+    getAgentMode(): AgentMode;
+    /**
+     * 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: AgentMode, opts?: {
+        force?: boolean;
+    }): AgentModeState;
+    /**
+     * 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(): AgentModeState | null;
+    /** Named read surface for `/plan status`, so no command reaches into internals. */
+    getPlanStatus(): PlanStatus;
+    /** Spend one `ask_user` round. Called from the tool, never from the UI. */
+    private takeAskRound;
+    /**
+     * 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.
+     */
+    withHumanWait<T>(fn: () => Promise<T>): Promise<T>;
     setModel(provider: string, model: string, baseUrl?: string): void;
     setThinkingLevel(level: ThinkingLevel): void;
     setMaxTokens(value: number | undefined): void;