@aragon-agent/cli 0.6.38 → 0.6.40

package/CHANGELOG.md

@@ -8,6 +8,247 @@ were written.
 ## Unreleased
 
 ### Added
+- **Automatic skill triage, and no round limit on questions.** Two changes that
+  share one idea: replace a hard limit with guidance the agent can act on.
+  `ask_user` is no longer capped at four rounds per turn — the cap, its prompt
+  wording (`you may ask up to 4 rounds`), its tool-result counters
+  (`roundsUsed` / `roundsRemaining`) and its `/plan status` readout are all gone,
+  because an agent that is told it is running out of questions behaves like it.
+  What replaced it is a de-duplication guard: a question batch you have already
+  **answered** in this turn returns a note instead of reopening the overlay, while
+  a **cancelled** one records nothing, so an accidental `Esc` never retires a
+  question. Steering does not reset the guard, because a steer resumes the same
+  turn. `planModeMaxAskRounds` is retired rather than defaulted to a large number:
+  `config set` names the reason and exits `2`, and the key disappears from
+  `config.json` at the next write. The single-wait ceiling
+  (`planModeHumanTimeoutMs`) is untouched — it protects an unattended terminal, not
+  the agent's vocabulary.
+  Skill use now begins with a step instead of a hope. Every task gets a
+  `<skill_triage>` protocol fixing *when* to decide (after the project guidance and
+  the directory listing, before any plan or edit) plus up to three ranked
+  `<skill_candidates>` computed locally from your message against the installed
+  records — no model call, no file read, no `SKILL.md` body, so the disclosure
+  ladder keeps its lower levels untouched. When a strongly-matching skill was
+  available and the turn did real work without loading it, the run ends with one
+  `info` line and a pointer to `/skills route`; that fires at most once per skill
+  per session, because a line printed every turn is a line you learn to skip.
+  `/skills route <text>` explains any decision (including the runner-up and the
+  threshold on a miss), `/skills triage on|off` flips the feature live, and
+  `skills.triage` (default `true`) makes it permanent — off restores the previous
+  prompt byte for byte. Subagents are deliberately not triaged: a child has no
+  `skill` tool, so candidates would advertise a capability it does not have.
+- **`/subagent`: force a parallel fan-out with one command.** The escape hatch for
+  "I want a team on this, not the model's judgement": `/subagent -n 6 review the error
+  handling in packages/cli/src/team`, `/subagent --parts api,ui,docs audit the request
+  path`, `/subagent --read-only profile the parser`. With no argument it reports live
+  capacity, the subagent model, the supervisor and the team switch, and it answers even in
+  a `--no-team` session rather than pretending. The command compiles your intent into ONE
+  user turn that tells the lead to call `task` once, so it shares the single dispatch path
+  (same Esc, same report, same spend accounting) - the forcing is instruction-level, and
+  the notice says what the next turn will do instead of claiming children have started.
+  A count above `team.maxSubagents` is narrowed AND disclosed (`asked for 12;
+  team.maxSubagents is 8`), a parts list is narrowed by both the structural 8 and the
+  configured width, and `-n 0` is an error rather than a silent 1.
+- **`/settings` → `Subagent fan-out`.** A fourth root row holding `Max subagents`,
+  `Run at once` and `Supervisor`, adjusted with `Left` / `Right` and saved by the same
+  single transaction as every other settings row (`Ctrl+S` on the main page; the fan-out
+  page's footer says so instead of promising a key it does not listen for). Narrowing the
+  population narrows the pool with it, and the follow-down is committed, so widening again
+  does not silently restore a pool you did not choose.
+- **`--threads`: one process, N isolated conversations.** A headless `aragon exec`
+  process used to be one conversation: the seventh tenant's messages appeared in the
+  third tenant's history, one `todo` list served everybody, and `interrupt` ended the
+  process for all of them. `--threads` (with `--input-format bridge` and
+  `--output-format stream-json`) makes a conversation an OBJECT: `thread_open` /
+  `thread_close` / `thread_list`, and every frame may carry a `threadId` (absent means
+  the default thread `main`, which is auto-opened, so a v1 caller is unchanged). Each
+  thread owns its controller, history, `todo`s, prompt queue, session file
+  (`<base>-<threadId>`) and account; three things are shared and only three - one
+  writer (so `seq` stays global), one emitter (one `result`), one registry.
+  `--max-open-threads` (default 4) bounds how many exist and `--thread-concurrency`
+  (default 2) how many hold a request in flight, released per request through a FIFO
+  gate. Isolation is an ownership fact rather than a promise: every line carries its own
+  `threadId`, a thread's provider error cannot end another thread or the process, and
+  `result.threads.items` reports each tenant's own `requests`/`turns`/`usage`/`cost`
+  while `result.usage` stays the sum. `--max-turns` is refused with `--threads` (use
+  `--request-max-turns`), and `interrupt` stays process-level:
+  `interrupt{threadId}` answers `interrupt_is_process_level` instead of silently becoming
+  "cancel one request", because the two have different exit codes and only one writes
+  `result`. See [Many conversations in one process](README.md#many-conversations-in-one-process).
+- **Lifecycle hooks: the caller can now change what the model says and sees.**
+  `hook_register` installs programmatic middleware at four points - `prompt_pre`
+  (rewrite or refuse the caller's text), `turn_start` (inject context through the one
+  safe steering checkpoint), `tool_pre` (rewrite a tool's arguments, or refuse it) and
+  `tool_post` (replace, redact or withhold a tool's result). Every round trip is one
+  `hook_request` with its own `hookRequestId` and exactly one `hook_resolved`
+  (`answered` / `timeout` / `aborted` / `invalid` / `saturated` / `unregistered`), bounded
+  by `--hook-timeout` (default 5 s) and failing closed by default
+  (`--on-hook-timeout deny|allow|error`; `allow` clamps to 30 s so two round trips cannot
+  consume a tool's 120 s budget). `tool_pre` rewrites are re-validated against the tool's
+  own schema so a hook's bug is never reported as the model's; `tool_post` is the
+  outermost wrapper, so it also covers denial text, a tool's own error output and the
+  `<job_notices>` tail of a background job. Hooks are per thread - one tenant's redactor
+  never sees another's data - and they deliberately do not wrap caller-registered tools.
+  See [Intervene in the data flow](README.md#intervene-in-the-data-flow-lifecycle-hooks).
+- `aragon info --json` reports `threadLimits` and `hookLimits` (both from their own
+  `*_LIMITS` constants) beside the existing bridge budgets, and advertises the new
+  `threads` / `hooks` capability strings from the same `execCapabilities()` derivation
+  point `system/init` uses - so a caller can read what the build accepts before deciding
+  which frames to send.
+- `examples/bridge-host-threads.mjs` (in `packages/cli/examples`, beside `bridge-host.mjs`): a dependency-free reference host with two threads
+  and one redactor, including the five things a host gets wrong (back-to-back
+  `thread_open` + `prompt`, answering `hookRequestId`, closing threads so `result` can be
+  written, and reading per-tenant accounting). `--dry-run` prints the frames without
+  spawning anything.
+
+### Changed
+- **The subagent fan-out default is now 8 per dispatch and 8 in flight at once** (it was
+  5 and 3). The perceived "only 3 subagents" was the concurrency ceiling, not the
+  population - changing only the population would have shown nothing, because children
+  4..8 would simply queue. `maxConcurrent` stays a separate knob precisely so a single API
+  key collecting 429s can be fixed by lowering `Run at once`; the settings row and the
+  README both say which number to lower. The hard ceiling is unchanged at 10: 8 is a
+  default you can move, 10 is the limit you cannot. **A persisted `5`/`3` pair from an
+  older install is migrated to `8`/`8` once**, with a `team.fanoutMigrated` marker so a
+  deliberate return to 5/3 sticks instead of being widened again on every launch. A
+  configuration whose values are anything else is never touched.
+- `makeExecController` now separates PROCESS-LEVEL log mounts from PER-CONTROLLER ones:
+  `run_exec`, the `onFailure` handler and the untrusted-skill notices happen once per
+  process (selected by the new `ExecControllerDeps.processLevelMounts`, which only the
+  default thread sets), while `attachAgentEvents` / `attachTeamEvents` are attached for
+  **every** thread and disposed when it closes. Skipping the latter would have left every
+  tenant but the first invisible in the log - an observability regression, not an
+  optimisation. Deriving the first half from `threadId` instead would have been wrong in
+  the other direction: the default thread has an id too (`main`).
+- `ExecRunner` gained `threadId`, `onRequestSettled`, `beforeTurn`, `hookPort` and
+  `installSignalTerminator`. All are optional; with none of them set the runner writes
+  the same bytes it wrote before.
+
+### Fixed
+- Changing only the fan-out width no longer drops the subagent model a session kit
+  installed. The settings save read "the `team` section was written" as "the user
+  re-decided the subagent slot", so adjusting `Max subagents` silently released a slot the
+  kit held - with every value on screen still correct. Only an explicit `model` /
+  `modelProfileId` decision releases the slot now, and the fan-out page can express
+  nothing else.
+- The `task` tool's description no longer states a fixed width (`2-5 independent
+  subagents`, `hard maximum 10`), which contradicted the configured maximum in the very
+  same request. It points at `<team_mode>`, which is generated from the live config.
+- A process-level signal now has exactly ONE owner in thread mode (it used to be
+  installed by every runner into a single process-wide slot, so the last one won): the
+  terminator fans out to all threads, `result` is written before the process exits, and a
+  second signal still exits immediately - after attempting `result`.
+- `--max-duration` is one process-level timer in thread mode instead of N timers with N
+  opinions, and `decideProcessOutcome` is the single place a stop reason and exit code
+  are decided.
+- A thread's runner now really is given its own bridge channel: `runner.attachBridge(server,
+  source)` was missing from the per-thread assembly, so prompts got no `ack`, turns wrote no
+  `request_end`, `steer` answered `not_running` and `cancel_request` was dropped in silence.
+  The runtime now owns the queue it serves (`ThreadRuntimeDeps.source`) and wires it before
+  the first prompt can arrive.
+- The admission slot is released by the queue that took it. It used to be released straight
+  on the gate, which left the queue believing it still held a slot - so from a thread's
+  second request onward `--thread-concurrency` silently stopped applying - and a prompt
+  cancelled while its thread waited for a slot left that slot held forever.
+- `interrupt{requestId}` in thread mode no longer stops the process: it withdraws one queued
+  turn (exit code 0), which is what it has always meant; `interrupt{threadId}` is still
+  refused and `interrupt` without either is still process-level.
+- Thread frames sent to a run WITHOUT `--threads` are answered `ack{accepted:false,
+  code:'threads_disabled'}` instead of being ignored, and `thread_close{mode}` rejects an
+  unknown mode instead of coercing it to `settle`.
+- `--on-hook-timeout allow` no longer rewinds a chain: when a later hook stays silent, the
+  rewrites and redactions earlier hooks already made are kept instead of being replaced by
+  the original text. A `tool_post` `replace` whose content array holds a part without a
+  `type` is refused (`hook_invalid_answer`) rather than stored - it would have been an HTTP
+  400 on the next request and on every resume of that session.
+- The `turn_start` injection budget is per REQUEST again (it was effectively per thread,
+  because nothing reset it), a budget stop no longer reports a non-existent
+  `injection_stranded`, and `--on-hook-timeout error` now actually marks the request as
+  failed instead of only setting a code.
+- A thread at `maxRequestsPerThread` answers `thread_capacity` (the ceiling existed as a
+  constant nothing consulted), and the per-point hook ceiling counts `"*"` as every tool.
+
+- **`--result-schema`: the answer becomes a contract, not a paragraph.** The model
+  submits its result through a `submit_result` tool whose parameter schema IS your
+  JSON Schema, so a machine (not a parser you write and then distrust) decides
+  whether the answer conforms. A violation comes back as field paths the model can
+  fix inside the same prompt, and `--result-repair-turns` (default 1, max 2) bounds
+  how many times it may try. `result.structured` carries the accepted value,
+  `result.result` becomes its canonical JSON so the `| jq -r .result` idiom still
+  means "the answer", and the model's prose moves to `result.text`. Failure is a
+  shape rather than a mood: an explicit `null` plus
+  `error.code: "result_schema_unsatisfied"`, with `--on-result-unsatisfied
+  error|continue` deciding whether the run stops (exit 1) or keeps serving with
+  `result.isError: true`. Validation is two layers - Core's optional `ajv` plus a
+  bounded validator of this CLI's own that enforces `required`, nested
+  `properties`, `items` and `additionalProperties: false` on machines without it -
+  and `aragon doctor` / `aragon info --json` say which one is in force. See
+  [Hand back a typed result](README.md#hand-back-a-typed-result).
+- **Requests are first class in bridge mode.** A long-lived `aragon exec
+  --input-format bridge` process used to have one set of budgets and one bill for
+  everything it ever did. Now every `prompt` ends with its own `request_end` -
+  `stopReason`, `turns`, `durationMs`, `usage`, `cost`, the last assistant text and
+  (under a schema) the accepted value - and the numbers are differences, so two
+  requests add up to the process total. `--request-max-turns` and
+  `--request-max-duration` bound ONE request without ending the process: its
+  `request_end` reports `max_turns` / `timeout` and the next caller is served
+  normally. `cancel_request{requestId?}` withdraws a single request - a queued one
+  is deleted and accounted as `cancelled` with `turns: 0`, an in-flight one is
+  aborted, and one that is already finished is refused with `unknown_turn` instead
+  of aborting a healthy run. `interrupt` still stops the whole run: two questions,
+  two frames. `aragon info --json` gained the `request_scope` capability and the
+  ceilings. See [One request at a time](README.md#one-request-at-a-time-budgets-billing-and-cancellation).
+- **`--input-format bridge`: the headless mode can now be driven, not just piped.**
+  Four new surfaces on one switch, all additive - without the flag every event,
+  field and tool object is exactly what it was:
+  - **The caller decides.** `--permission-mode ask` makes `write_file` /
+    `edit_file` / `bash` / `skill_create` send a `decision_request` and wait for a
+    `decision` frame before they run (answer `allow`, `deny` with a reason, or
+    `allow` with `scope: "session"` to stop asking for that tool). `ask_user` and
+    `submit_plan` become reachable headlessly for the first time
+    (`decision_request{kind:'questions'|'plan'}`), and `skill_install` asks the
+    same way instead of being denied outright. A denial is a readable
+    `tool_result` the model can route around - never a crash, never a silent skip.
+  - **The caller serves tools.** `tool_register` declares up to 32 tools of your
+    own (`db_query`, `open_ticket`), full-replacement semantics, validated
+    (name, reserved names, JSON Schema, size) before anything is written; the
+    model then calls them and the CLI sends `tool_invoke` and waits for
+    `tool_result`, with the same timeout, cancellation and 100 KB clip the built-in
+    tools get. Registration lands at a turn boundary, never mid-iteration.
+  - **Requests are correlatable.** `prompt{id}` / `steer{id}` / `interrupt` in,
+    `ack` / `steering{steeringIds}` / `pong` out, plus `seq` on every stdout line
+    and `requestId` on `user` / `turn_state` / `assistant` / `tool_call` /
+    `tool_result`. `result` is still exactly once and last; `init` is still first.
+  - **Budgets for the new channel.** `--decision-timeout <ms>` (default 300000,
+    max 1800000), `--on-decision-timeout deny|error`, `--caller-tool-timeout <ms>`
+    (default 60000, max 600000). All three are usage errors without
+    `--input-format bridge`, as are a positional prompt and `--prompt-file`,
+    because bridge prompts come from stdin.
+
+  `aragon info --json` now reports `inputFormats` with `bridge`, `permissionModes`
+  with `ask`, and a `bridge` block (`protocolVersion`, `capabilities`,
+  `decisionKinds`, `gatedTools`, `limits`). `packages/cli/examples/bridge-host.mjs`
+  is a zero-dependency reference host. See
+  [Let the caller decide](README.md#let-the-caller-decide) and
+  [Serve your own tools](README.md#serve-your-own-tools).
+- **The keyboard drawer (`Ctrl+G`), and a task label in the header.** The header now
+  teaches exactly ONE key: `^G more`. Pressing it slides a right-hand drawer in over
+  the current screen and lists EVERY binding top to bottom - the key, a one-or-two
+  word keyword, and the sentence that explains it on the selected row - grouped
+  COMPOSE / RUN / PANELS / SESSION / VIEW. The keyword column is DERIVED from the
+  table rather than fixed, so a keyword that cannot fit makes its row stack instead
+  of being cut; paging moves the cursor, so the selected row and its detail line can
+  never leave the screen. `d` toggles the status detail row and `r` regenerates the
+  label. The same list is reachable without a keyboard: `/keys [query]` opens it
+  pre-filtered. The header also says WHAT you are doing: the first prompt of a task is
+  compressed by the FAST tier into a few words in the language you wrote in, shown to
+  the right of the working directory, and cleared by `/clear` (and rebuilt from the
+  restored conversation after `/resume`). `/task` reports what the label says and
+  where it came from; `/task refresh` regenerates it. When the fast tier cannot run,
+  the label falls back to a prefix of your own words - which cannot lie - and
+  `taskSummary.fallback=false` shows nothing instead. New
+  `taskSummary.enabled` / `taskSummary.fallback` keys plus `ARAGON_TASK_SUMMARY`. See
+  [Keyboard drawer and task label](README.md#keyboard-drawer-and-task-label).
 - **Acceptance criteria: a plan now has to say how you would know it is done.**
   `todo_write` takes a second array in the SAME call - one checkable statement per
   line plus the check the model will run for it - so the steps and the criteria can
@@ -110,6 +351,28 @@ were written.
 
 ### Changed
 
+- **`Ctrl+G` opens the keyboard drawer; the status detail row moved to `d`.** The key
+  used to expand the extra status line, and its header hint competed with `^L`, `^P`,
+  `^I` and `^K` for room - so what a user saw depended on the terminal width instead of
+  on what keys exist. Those five clauses are gone from the header (`^G more` is the
+  only one left) and the detail row is now toggled by `d` INSIDE the drawer, which
+  also shows its `on`/`off` state. The status detail row's own hint now reads `^G then
+  d` rather than `^G less`, because `^G less` no longer does anything. `/help` gained
+  the `Ctrl+O` row it had always been missing and now describes `Ctrl+G` as the drawer.
+- **`Ctrl+G` does not take the keyboard from an overlay that is waiting for a
+  decision.** With any other overlay open it replaces that overlay with the drawer;
+  with `confirm`, `question` or `plan` it stays inert, because those three hold an
+  unresolved promise to the agent and only `Esc` settles it - taking the dialog away
+  would hide it and leave the run waiting for ever.
+- **`prompts.hint` is retired.** Its only reader was the `^P prompts` header clause,
+  which the drawer replaced, and a config key that cannot reach any surface is a lie.
+  An older `config.json` still loads (unknown keys are ignored) and `config list` no
+  longer prints it. Hand-editing was already the only way to set it: it was never in
+  `config set`.
+- **`/keys` and `/task` shadow same-named skills.** Commands registered by the CLI win
+  over skill names, so a user with a skill called `keys` or `task` now reaches it as
+  `/skill:keys` / `/skill:task`. Both names are deliberately unaliased - an alias would
+  multiply the same shadowing.
 - **BREAKING DEFAULT: the TUI now scrolls with your terminal (`scrollMode: native`).**
   Until now the interactive TUI ran in the terminal's alternate screen with its own
   scrollbar, wheel handling and drag-selection. The default is now **native scroll