@aragon-agent/cli 0.5.12 → 0.6.2

package/CHANGELOG.md

@@ -5,10 +5,110 @@ 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.
 
+## 0.6.0
+
+### Added
+
+- **`aragon exec` — a second, machine-facing face on the same binary.** The
+  package already installed from npm and already ran from a terminal, so "it has
+  a CLI" was true. It was nonetheless not *callable* by another program:
+  everything it exposed was shaped for a person, and a build script, a CI job, a
+  web backend or a second agent had to spawn it, capture free text, and guess.
+  There was no way to read the answer without also reading the narration, no way
+  to carry a conversation across two invocations, no way to say "you may read but
+  not write" when there is no human to answer `--confirm`, and no way to bound
+  what a run may spend.
+
+  `aragon exec` adds a **contract** rather than a feature: a versioned JSON event
+  schema on stdout, a session identifier the caller may mint itself, a tool
+  permission policy enforced at the tool boundary, caller-set budgets with their
+  own exit code, and a discovery command so a wrapper can ask what it just
+  installed before depending on it. Everything underneath is reused unchanged —
+  the same controller, the same tools, the same config resolution, the same
+  skills, teams, todo and fast-tier subsystems.
+
+  - `--output-format text | json | stream-json`. `stream-json` is NDJSON: one
+    object per line, `system/init` first, exactly one `result` last, on every
+    exit path including error, budget and signal. `text` is byte-identical to
+    `aragon -p`, because it **delegates** to the same renderer rather than
+    reimplementing it.
+  - `--session-id` / `--resume` / `--continue`, backed by `~/.aragon-agent/
+    sessions/` and an exclusive lock, so two runs cannot interleave and lose a
+    turn. A second run on a held id exits 2 with `session_busy` rather than
+    blocking.
+  - `--permission-mode auto|plan|strict` plus `--allow-tool` / `--deny-tool`.
+    A denied tool is **not registered at all**, so the model never sees it and
+    never plans around it — and the policy reaches subagents, so one `task` call
+    cannot bypass it.
+  - `--max-turns` / `--max-duration`, both aborting through the same path `Esc`
+    uses, both reporting `isError: false` and exit **3**: a budget firing is not
+    a malfunction, but it is not a complete answer either, and a shell script has
+    to be able to tell without parsing JSON.
+  - `--append-system-prompt` / `--append-system-prompt-file`. Appending only;
+    there is deliberately no full `--system-prompt` replacement, because the
+    builtin prompt carries tool discipline, todo planning, the skills catalog and
+    the plan-mode block, and replacing it silently disables half the product.
+  - `--input-format stream-json`, so one process can serve several turns from a
+    pipe. A malformed line is skipped with a non-fatal `error` event; an unknown
+    message type is ignored.
+  - **`aragon sessions`** (`list` / `show` / `rm` / `prune` / `path`),
+    **`aragon info [--json]`** and **`aragon doctor [--json] [--probe]`**.
+
+  Documented in full under
+  [Use it from another project](./README.md#use-it-from-another-project),
+  including an honest Limits section: there is no filesystem sandbox, process
+  exit is terminal on Windows whether or not a `result` arrived, an exec session
+  resumed in the TUI shows no scrollback, and `sessions prune` shares a directory
+  with the TUI's `/save`.
+
+### Changed
+
+- **Exit code `3` is new, and the signal row is now stated as `128 + signo`.**
+  `3` means "stopped by a budget you set" and is reachable only from
+  `aragon exec`. The signal codes are unchanged in behaviour — this CLI has
+  always exited `128 + signo`, so `SIGTERM` has always been `143` — but the
+  README previously simplified all of them to `130`, which is fine for prose
+  about a CLI a human interrupts and not good enough for a wire contract.
+- `interrupt` handling now settles the run before exiting when `aragon exec`
+  owns it, so a wrapper reading NDJSON gets a final `result` on Ctrl-C instead of
+  having to time out to learn the run ended. `aragon`, `aragon -p` and every
+  other subcommand keep the previous bare-exit behaviour byte for byte.
+
+### Unchanged, and asserted rather than claimed
+
+- `aragon`, `aragon -p`, every existing flag, every slash command and every byte
+  of their output. `aragon exec --output-format text` and `runHeadless` are
+  compared for byte equality on **both** stdout and stderr by a regression test,
+  and `createBuiltinTools` with no permission policy is proven by object identity
+  to return the tools it returned before.
+
 ## Unreleased
 
 ### Fixed
 
+- **The working spinner no longer disappears when an ack takes its row.** Steer a
+  run, approve a plan, or press `Ctrl+T` while the agent is working, and the row
+  above the composer traded its spinner for the acknowledgement — and for that
+  ack's full two and a half seconds, nothing anywhere on screen moved. The status
+  bar still read `running` and the tool card still read `running`, so no
+  information had left the frame; only the evidence that the process was alive
+  had, during exactly the long tool calls where "is it stuck?" is the question you
+  are already asking. Consecutive acks extended the window, and steering is
+  something the composer invites on every run.
+
+  That row was made the sole owner of animation in this same release, and
+  everything else on screen holds still for as long as the row is believed to be
+  showing one. Believed, not checked: an ack won the row outright, so the belief
+  and the frame disagreed, and the disagreement was invisible to every test
+  because no component was wrong on its own.
+
+  The ack still owns the row and keeps every word of its text. The spinner now
+  rides beside it as a bare glyph — no phrase, no clock — so there is exactly one
+  animation at every instant of a run, with an ack up or without one: never none,
+  and never the several this release set out to remove. Terminals without Unicode
+  and anyone running with `reducedMotion` come out byte for byte unchanged; they
+  had no animation to lose, and nothing is prefixed to their acks.
+
 - **`/clear` now takes the todo panel with it.** Finish a plan, type `/clear`,
   and the transcript emptied while the `7/7 done` rail stayed exactly where it
   was — on a screen you had just asked to be cleared. It stayed until your next

package/README.md

@@ -10,6 +10,36 @@ steer / configure the session — all without leaving the terminal.
 > and there is **no per-action approval gate by default**. Only run it in
 > workspaces you trust. An opt-in confirmation mode is available via `--confirm`.
 
+## Requirements
+
+Node **≥ 18**, any platform.
+
+**On Windows with Node < 22.17.0 (or 24.0/24.1), aragon turns the missing
+console flag on itself at startup**, which restores `Shift+Tab` on most
+machines. Where that is blocked — a locked-down PowerShell, an old console
+host — **`Ctrl+P` toggles the mode instead**; it is bound on every platform and
+does not depend on the console mode, the Node version, or anything else.
+Everything else — the agent loop, every tool, skills, teams, `aragon -p` — works
+exactly the same on Node 18 and 20, which is why `engines` stays at `>=18`
+rather than locking those users out.
+
+The reason is not the terminal emulator and not a setting: on Windows both
+`Shift+Tab` (`CSI Z`) and mouse reporting exist only while the console input
+handle has `ENABLE_VIRTUAL_TERMINAL_INPUT` set, and Node only sets it from
+v22.17.0 / v24.2.0 onward. On older versions libuv translates console input
+itself, and that translation has no entry for `Shift+Tab` (it arrives as a
+plain `Tab`) and discards mouse records outright. Node 20 is the current
+Windows default LTS, so this is a common configuration rather than an exotic
+one — it is why the same build behaves differently on two machines. Below that
+version aragon sets `ENABLE_VIRTUAL_TERMINAL_INPUT` itself, from a short
+PowerShell helper, right after it puts the console into raw mode — the flag is a
+property of the console, not of Node, so any process attached to it can turn it
+on. When that works, `Shift+Tab` arrives as `CSI Z` again and mouse reporting
+goes back on with it — the wheel should follow by the same route, though only
+the key has been measured. When it does not work, aragon says so at startup and
+turns mouse reporting off rather than asking for reports that can never arrive;
+`Ctrl+P` and `/plan` switch mode, and `Shift+↑` / `Shift+↓` scroll.
+
 ## Install
 
 ```bash
@@ -38,11 +68,268 @@ aragon "summarize README.md" # interactive, auto-submitting the prompt
 echo "list files" | aragon -p   # one-shot, prints to stdout then exits
 ```
 
+## Use it from another project
+
+`aragon exec` is the machine-facing face of the same binary: a versioned JSON
+event stream on stdout, sessions that survive across process boundaries, tool
+permissions enforced at the tool boundary, and budgets with their own exit code.
+Install the package, spawn it, read the JSON — that is the whole integration
+story. Nothing about the interactive TUI changes, and `aragon -p` keeps working
+exactly as it always has.
+
+```bash
+npm i -g @aragon-agent/cli    # or add it as a devDependency and use npx
+
+aragon exec --output-format json "summarize src/index.ts" | jq -r .result
+```
+
+### Discover what you installed
+
+```bash
+aragon info --json     # version, schema version, tools, formats, features
+aragon doctor          # "is this machine configured to run me?" — exit 0 = yes
+```
+
+`info.features` is a flat list of strings, on purpose: a wrapper that tests
+`features.includes('sessions')` keeps working across versions that add
+capabilities.
+
+### Output formats
+
+| Format | Stdout carries | Use it when |
+| --- | --- | --- |
+| `text` (default) | Exactly what `aragon -p` prints | A human reads the output, or you already parse `-p` |
+| `json` | One `result` object, pretty-printed | You want the answer and the totals, nothing else |
+| `stream-json` | One JSON object per line (NDJSON) | You want tool calls, todos and progress as they happen |
+
+```bash
+# text — byte-identical to `aragon -p "hi"`
+aragon exec "hi"
+
+# json — one object, ideal for `jq`
+aragon exec --output-format json "hi"
+
+# stream-json — NDJSON, one object per line
+aragon exec --output-format stream-json "read package.json and name the deps"
+```
+
+A `stream-json` run looks like this (elided for width):
+
+```jsonc
+{"type":"system","subtype":"init","schemaVersion":1,"sessionId":"6f2…","cli":"0.6.0","cwd":"/w","model":{"provider":"anthropic","id":"claude-…","baseUrl":null},"permissionMode":"auto","tools":["read_file","write_file",…],"resumed":false}
+{"type":"user","sessionId":"6f2…","turn":1,"text":"read package.json…","source":"caller"}
+{"type":"tool_call","sessionId":"6f2…","turn":1,"id":"t1","name":"read_file","input":{"path":"package.json"}}
+{"type":"tool_result","sessionId":"6f2…","turn":1,"id":"t1","name":"read_file","isError":false,"durationMs":4,"output":"{\n  \"name\": …"}
+{"type":"assistant","sessionId":"6f2…","turn":1,"text":"The dependencies are …"}
+{"type":"result","schemaVersion":1,"sessionId":"6f2…","isError":false,"stopReason":"end_turn","exitCode":0,"result":"The dependencies are …","turns":1,"durationMs":4120,"usage":{"inputTokens":1204,"outputTokens":88,"totalTokens":1292},"cost":{"amount":0.0049,"currency":"USD","known":true},"model":{"provider":"anthropic","id":"claude-…"},"todos":null,"error":null}
+```
+
+Event types: `system` · `user` · `text_delta` · `thinking` · `assistant` ·
+`tool_call` · `tool_result` · `todo` · `team` · `fast_review` · `retry` ·
+`error` · `result`. `text_delta` and `thinking` are opt-in
+(`--partial-messages`, `--include-thinking`) — a per-token line is thousands of
+lines per turn and is only wanted by a caller rendering a live UI.
+
+**Forward compatibility, stated as a contract.** `schemaVersion` appears on
+`system` and on `result`. **Ignore event types you do not know, and ignore
+fields you do not know**: adding either never bumps the version, and renaming or
+removing one does. A consumer that holds up its end of that keeps working across
+upgrades; one that does not will break on a release that adds an event.
+
+One practical note: a `tool_result.output` line can approach 100 KB, so read
+stdout with a line reader that has no small buffer cap.
+
+### Tool permissions
+
+`--confirm` needs a human. For a program embedding an agent there are two
+orthogonal controls instead, and both are enforced by the wiring — a denied tool
+is **not registered at all**, so the model never sees it and never plans around
+it.
+
+| Flag | Meaning |
+| --- | --- |
+| `--permission-mode auto` | Every tool (the default) |
+| `--permission-mode plan` | Every tool registered; the five that write refuse at call time. Exactly `aragon -p --plan` |
+| `--permission-mode strict` | Nothing, until `--allow-tool` says otherwise |
+| `--allow-tool <names>` | **Adds** to the baseline. Repeatable; comma lists accepted |
+| `--deny-tool <names>` | **Removes**. Wins over `--allow-tool` |
+
+Each of these reads as one sentence:
+
+```bash
+# a research agent that cannot touch anything
+aragon exec --permission-mode strict --allow-tool read_file,grep,glob,list_dir \
+  --output-format json "which files define the retry policy?"
+
+# do anything except shell out
+aragon exec --deny-tool bash --output-format json "fix the failing test"
+
+# read-only research and a written plan, no edits
+aragon exec --permission-mode plan --output-format json "how would you add OAuth?"
+```
+
+The policy reaches **subagents**: a `task` dispatch cannot hand a child a tool
+the parent was denied. An unknown tool name is a usage error (exit 2) rather
+than a silent no-op.
+
+### Sessions across invocations
+
+A wrapper that respawns per turn — a CI step, an HTTP handler, a queue worker —
+needs the conversation to outlive the process.
+
+```bash
+aragon exec --session-id ci-42 --output-format json "start the migration plan"
+aragon exec --session-id ci-42 --output-format json "now do step 1"
+```
+
+| Flag | If the session exists | If it does not |
+| --- | --- | --- |
+| `--session-id <id>` | Resume it | **Create** it (the wrapper-friendly upsert) |
+| `--resume <id\|path>` | Resume it | Exit 2, `session_not_found` |
+| `-c, --continue` | Resume the newest session for this directory | Exit 2, `no_session_for_cwd` |
+| `--no-save-session` | — | Run statelessly; write nothing |
+
+Sessions live in `~/.aragon-agent/sessions/`. An id must match
+`[A-Za-z0-9][A-Za-z0-9._-]{0,63}` — it becomes a filename, and the caller
+supplying it is frequently the least trusted input in the pipeline.
+
+```bash
+aragon sessions list [--json] [-n 20] [--all]
+aragon sessions show <id> [--json]
+aragon sessions rm <id> --yes
+aragon sessions prune [--older-than 7] [--dry-run] [--all] --yes
+aragon sessions path
+```
+
+Two same-id runs cannot interleave: the second exits 2 with `session_busy`
+rather than blocking, because a wrapper that wants a queue can build one and a
+CLI that blocks on a lock it cannot show you is a hang.
+
+### Budgets
+
+```bash
+aragon exec --max-turns 20 --max-duration 600000 --output-format json "…"
+```
+
+`--max-turns <n>` bounds assistant turns; `--max-duration <ms>` bounds the whole
+run's wall clock. Both abort through the same path `Esc` uses, so subagents are
+torn down and the engine settles normally. **Neither is an error** — `isError`
+stays `false` — but both exit **3**, so a shell script can tell "ran out of
+budget" from "finished" and from "broke" without parsing JSON.
+
+Two neighbours they do not replace: `--idle-timeout` bounds a *silent stretch*
+inside the run and still applies (a `--max-duration` longer than the idle
+watchdog will usually be pre-empted by it, which surfaces as
+`stopReason: "error"`); `--tool-timeout` bounds a *single tool call*.
+
+A run that finishes on its own in exactly `--max-turns` turns exits `0` with
+`stopReason: "end_turn"`. The budget fires only when a further turn would start.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Agent / runtime error (the run started and failed) |
+| `2` | Configuration or usage error (the run never started; stdout is empty) |
+| `3` | Stopped by a caller-set budget (`--max-turns`, `--max-duration`) |
+| `130` / `143` / `129` | Interrupted by `SIGINT` / `SIGTERM` / `SIGHUP` (`128 + signo`) |
+
+### Spawning it from Node
+
+```js
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+
+function runAragon(prompt, args = []) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      'aragon',
+      ['exec', '--output-format', 'stream-json', ...args, prompt],
+      { stdio: ['ignore', 'pipe', 'inherit'] },
+    );
+
+    let result = null;
+    const lines = readline.createInterface({ input: child.stdout });
+    lines.on('line', (line) => {
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        return; // Never fatal: forward compatibility runs both ways.
+      }
+      if (event.type === 'result') result = event;
+      // Ignore every type you do not know. That is the contract.
+    });
+
+    // RESOLVE ON EXIT AS WELL AS ON `result`. Process exit is terminal whether
+    // or not a `result` arrived — see Limits below — and a consumer that waits
+    // only for `result` hangs when the run is killed.
+    child.on('error', reject);
+    child.on('close', (code) => resolve({ code, result }));
+  });
+}
+```
+
+### In CI
+
+```bash
+aragon exec \
+  --permission-mode plan \
+  --max-turns 20 \
+  --max-duration 900000 \
+  --output-format json \
+  --session-id "ci-${GITHUB_RUN_ID}" \
+  "Review the diff on this branch and list the risks." \
+  | jq -r .result
+```
+
+`aragon doctor --json` exits 1 with a named failing check when the machine is
+not configured, which makes a good first step in the job.
+
+Feeding several turns to one process:
+
+```bash
+printf '%s\n' \
+  '{"type":"user","text":"list the files you would change"}' \
+  '{"type":"user","text":"now change the first one"}' \
+  '{"type":"end"}' \
+| aragon exec --input-format stream-json --output-format stream-json
+```
+
+### Limits
+
+Four things this does **not** do, stated plainly because the audience for this
+section is the one that would be misled by their omission.
+
+1. **There is no filesystem sandbox.** Tool paths are not confined to the
+   working directory: an absolute path resolves to itself. Tool permission —
+   not a directory allowlist — is the boundary that is real, and a run with
+   `bash` enabled can reach anything the invoking user can. There is deliberately
+   no `--add-dir`, because it would be a promise the wiring does not keep.
+2. **Process exit is terminal, `result` or no `result`.** On POSIX, `SIGINT`,
+   `SIGTERM` and `SIGHUP` all produce a final `result` before the process ends.
+   **On Windows only Ctrl-C does** — Node does not deliver the other two to
+   listeners, so `taskkill` ends the process outright. Resolve on process exit as
+   well as on `result`, or a killed run hangs your parent process.
+3. **A session created by `aragon exec` and resumed with `aragon --resume`
+   carries the model's full memory and shows no scrollback** for the turns that
+   ran headlessly. The reverse direction is fully faithful: a TUI `/save` resumed
+   by `aragon exec --resume <id>` keeps everything.
+4. **`aragon sessions prune` shares a directory with the TUI's `/save`**, so it
+   only ever touches sessions `exec` created — files that carry an exec `meta`
+   block — unless you pass `--all`. `sessions show` and `sessions rm` accept any
+   id, because you named it.
+
 ## Usage
 
 ```
 aragon [prompt]                 Start the interactive TUI (or one-shot with -p / piped stdin)
 aragon -p, --print [prompt]     Headless: stream the answer to stdout, then exit
+aragon exec [prompt]            Machine-facing run: JSON events, sessions, permissions, budgets
+aragon sessions <sub> [id]      Manage exec sessions: list | show | rm | prune | path
+aragon info [--json]            Print what this installation supports
+aragon doctor [--json] [--probe] Check this machine is configured to run aragon
 aragon config                   Open the settings screen
 aragon config set <key> <value> Non-interactive config write (e.g. model, provider)
 aragon config path              Print the config file path
@@ -51,6 +338,11 @@ aragon --version | -v           Print the version
 aragon --help  | -h             Print help
 ```
 
+`aragon exec` is documented in full under
+[Use it from another project](#use-it-from-another-project). Every global flag
+below works there too, in either position — `aragon --model m exec "…"` and
+`aragon exec --model m "…"` parse identically.
+
 ### Global flags
 
 | Flag | Meaning |
@@ -95,7 +387,8 @@ aragon --help  | -h             Print help
 | `--quiet` | (print mode) suppress tool/usage lines on stderr |
 
 Exit codes: `0` success · `1` agent/runtime error · `2` config/usage error ·
-`130` interrupted.
+`3` stopped by a caller-set budget (`aragon exec` only) · `128 + signo` when a
+signal ends the run (`130` SIGINT, `143` SIGTERM, `129` SIGHUP).
 
 ## Slash commands (interactive)
 
@@ -138,7 +431,8 @@ 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` |
+| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
+| `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
 | `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) |
@@ -146,7 +440,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+O` | Expand / collapse the most recent tool card — including its diff |
 | `PgUp` / `PgDn` | Scroll the transcript a page (full-screen mode) |
 | `Shift+↑` / `Shift+↓` | Scroll the transcript a line (full-screen mode) |
-| Mouse wheel | Scroll the transcript (or the open overlay) |
+| Mouse wheel | Scroll the transcript (or the open overlay). On Windows needs Node ≥ 22.17 — see [Requirements](#requirements) |
 | `Shift`+wheel | Scroll the transcript a page |
 | `Home` / `End`, `Ctrl+A` / `Ctrl+E` | Cursor to line start / end |
 | `Alt/Ctrl+←` / `→` | Word-wise cursor jump |
@@ -177,6 +471,9 @@ before you meet them:
   something this CLI can opt out of while still reading wheel events.
 - **`tmux` with `mouse on` keeps the wheel for itself**, so the app never sees
   it. `set -g mouse off` hands it back.
+- **A Windows console on Node below 22.17.0 cannot report the wheel at all**,
+  so aragon does not ask it to. See [Requirements](#requirements); `PgUp` /
+  `PgDn` and `Shift+↑` / `Shift+↓` scroll from the keyboard meanwhile.
 
 Turn the whole thing off with `--no-mouse`, `ARAGON_MOUSE=0`, or
 `aragon config set mouse false`. With mouse support off the wheel simply does
@@ -460,9 +757,28 @@ 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.
+**Press `Ctrl+P`.** It is the same toggle and it does not depend on any of the
+machinery below.
+
+To find out why, run this in the same terminal, press `Shift+Tab` once, then
+`Ctrl+C`:
+
+```powershell
+node -e "process.stdin.setRawMode(true);process.stdin.resume();process.stdin.on('data',b=>{console.log(b.toString('hex'));if(b[0]===3)process.exit(0)})"
+```
+
+| It prints | What it means |
+| --- | --- |
+| `09` | The console is swallowing the modifier — the key is arriving as an ordinary `Tab`. Check `node -v`: below 22.17.0 (or on 24.0/24.1) this is expected, and aragon's own attempt to fix it was blocked. See [Requirements](#requirements) |
+| `1b5b5a` | The key reaches the process fine, so something inside aragon is eating it — most often an overlay is open, or the run is still going and the switch is pending (the status bar shows `BUILD → PLAN`) |
+| nothing | Your terminal, multiplexer or remote-desktop stack never sent it; some never send `CSI Z` at all |
+
+On the first row the wheel is dead for the same reason, and with the `/` palette
+or an `@` popup open the stray `Tab` completes that entry over your draft.
+
+`/plan`, `/plan on`, `/plan off` and `/plan status` are first-class equivalents
+in every case, and `--plan` / `ARAGON_PLAN=1` / `planModeDefault` cover the
+startup case. `aragon doctor` reports this machine's answer as `vt-input`.
 
 ### Headless
 

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

@@ -28,6 +28,45 @@ export declare const MODE_LABEL: Record<AgentMode, string>;
  * and nothing else. Two ship today (§1 non-goals).
  */
 export declare function nextMode(current: AgentMode): AgentMode;
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+p` IS MEASURED, not guessed. On the lossy path it arrives as `0x10`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/l/t/o,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'p'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export declare const MODE_TOGGLE_KEYS: {
+    readonly primary: "shift+tab";
+    readonly fallback: "ctrl+p";
+};
 /** The two tools that only exist because a human is attached. */
 export declare const PLAN_TOOL_NAMES: readonly ["ask_user", "submit_plan"];
 /**

package/dist/agent/agent-mode.js

@@ -30,6 +30,42 @@ export function nextMode(current) {
     const index = AGENT_MODES.indexOf(current);
     return AGENT_MODES[(index + 1) % AGENT_MODES.length];
 }
+/**
+ * The keys that toggle the mode, as the user sees them written
+ * (shift-tab-mode-toggle-still-dead-on-windows, C2).
+ *
+ * `fallback` exists because `primary` CANNOT be made to work everywhere. On a
+ * Windows console without `ENABLE_VIRTUAL_TERMINAL_INPUT`, libuv takes the
+ * character branch for `VK_TAB` and drops the modifier wholesale, so `Shift+Tab`
+ * and `Ctrl+Tab` both arrive as a bare `0x09` - byte-identical to `Tab`. C1
+ * turns that bit back on where it can, but it has three known ways to fail that
+ * are outside this package (an old conhost refusing the bit, a locked-down
+ * PowerShell, a foreign process resetting the mode), so a rung that depends on
+ * NOTHING has to exist underneath it.
+ *
+ * `ctrl+p` IS MEASURED, not guessed. On the lossy path it arrives as `0x10`,
+ * because Windows generates a real control character for `Ctrl+<letter>` and
+ * libuv's character branch forwards it untouched; `Alt+M` produces no bytes at
+ * all and `Ctrl+Tab` collapses exactly like `Shift+Tab` (analysis section 3.6).
+ * Any idle `Ctrl+<letter>` in the `0x01-0x1A` range would work; this one is free
+ * throughout the package - `keymap.ts` claims a/e/w/u/k, `App` claims c/l/t/o,
+ * and `PromptInput` returns early on every `key.ctrl` - so binding it takes no
+ * behaviour away from anyone. `Ctrl+B` survives the same path but is tmux's
+ * default prefix, and this binding is unconditional and cross-platform, so it
+ * would be silently dead for a whole class of macOS and Linux users.
+ *
+ * BOUND UNCONDITIONALLY, on every platform. A binding that only exists where it
+ * is needed cannot be documented in one place, cannot be taught by muscle
+ * memory, and is missing on precisely the machine whose capability probe was
+ * wrong.
+ *
+ * THESE ARE THE LABELS, NOT THE BINDING. Editing a value here changes only what
+ * the user is TOLD to press - the hint row, the startup notice, `doctor`. The
+ * key that is actually listened for is `input === 'p'` in `App`'s `useInput`,
+ * and the help overlay and README spell both keys out in their own title case.
+ * Change one without the others and the product advertises a key it ignores.
+ */
+export const MODE_TOGGLE_KEYS = { primary: 'shift+tab', fallback: 'ctrl+p' };
 /** The two tools that only exist because a human is attached. */
 export const PLAN_TOOL_NAMES = ['ask_user', 'submit_plan'];
 /**

package/dist/agent/controller.d.ts

@@ -11,6 +11,7 @@
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
 import type { CliConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
+import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
 import type { FilePatch } from '../tools/patch.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
@@ -70,6 +71,28 @@ export interface ControllerDeps {
      * mid-run, and the sentence is guidance rather than a contract.
      */
     todoPanelCapable?: boolean;
+    /**
+     * The `aragon exec` tool policy (cli-integration-surface §4.2).
+     *
+     * FORWARDED TO **TWO** PLACES, AND BOTH ARE REQUIRED (R-4 / R-5). It goes into
+     * `createBuiltinTools` for the lead's own array, and into `TeamRuntimeDeps` so
+     * children inherit it. Without the second, `--deny-tool bash` is bypassed by
+     * one `task` call and NOTHING ANYWHERE REPORTS IT — a security control that
+     * silently does not hold. Plan mode's "reaches one level down" guarantee is
+     * the precedent; AC-12 is the test.
+     *
+     * Absent on every existing path (the TUI, `-p`, every subcommand), which is
+     * what keeps the tool array identical there — see the option's own comment in
+     * `tools/index.ts`.
+     */
+    permission?: ToolPermission;
+    /**
+     * `--append-system-prompt` text, appended verbatim to the composed prompt
+     * (§4.1). Threaded through `composeSystemPrompt` so it survives every rebuild
+     * — a `/cwd` change, a skills rescan, a mode flip — rather than being spliced
+     * once at construction and lost at the first `rebuildSystemPrompt()`.
+     */
+    appendSystemPrompt?: string;
 }
 /** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
 export interface AgentModeState {
@@ -98,6 +121,15 @@ export declare class AgentController {
     private onSkillsChanged?;
     /** Mutable session cwd — tools resolve relative paths against this. */
     private cwd;
+    /**
+     * `--append-system-prompt` text (cli-integration-surface §4.1).
+     *
+     * A FIELD, NOT A LOCAL, because `composeSystemPrompt()` is called again on
+     * every rebuild — a `/cwd` change, a skills rescan, a plan-mode flip — and a
+     * value spliced once at construction would silently vanish at the first one.
+     * Empty on every path but `aragon exec`.
+     */
+    private readonly appendSystemPrompt;
     private effectiveMode;
     private pendingMode;
     private askRounds;