rubino-agent 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a20b85c30f537ff5bdaf5abec6300eedfcda791d76b899ac3fcd972b71854ac1
-  data.tar.gz: d5692a31f13e338690a3be90bc4d96d27251ddad165b706afee7e0fcdee3fea7
+  metadata.gz: 8a3a48a6f7deb104446c624354a271ff1a1671c9b3ea846cee1144b3f55538db
+  data.tar.gz: cbc407cd78db827d75f150f61045b2cce759b266816e32fdba874c30eb3647c4
 SHA512:
-  metadata.gz: 865a203c91311f039d90a98b4e88ff8f792d0049e7370f10c847e2aeb77458f2f39d80485f133a79d8c2e8d9c1eeb5dec369f53320d210ff79928965a8c0a3f2
-  data.tar.gz: a9435d6746bc743e65db73574e13d4cd65445bf97ec5c9e2387737c176e7ab8726991062cc852a6c295910e3876d8b4a1d8c96420f5a8dd6a83dabf68a280546
+  metadata.gz: 3342a4c8b1856691788ac9625b81eb4058870a0eb5a75946e99e6570ce40a05a7b44475a798863ac0fc92c9fcb505cf6caf27fcedc10a8e1bd9653ba18edf440
+  data.tar.gz: e54077b30f385942dd3591fb7e6c4e7afc0f301e5fea9d3111732c91ce56e63a4c7d192704ebd74ea97ee4a04437784d73a8d398bf02ce6143cdd69b2227a841

data/.rubocop_todo.yml

@@ -256,6 +256,8 @@ Metrics/BlockLength:
 Metrics/ClassLength:
   Exclude:
     - 'lib/rubino/cli/chat_command.rb'
+    - 'lib/rubino/commands/executor.rb'
+    - 'lib/rubino/llm/ruby_llm_adapter.rb'
     - 'lib/rubino/ui/bottom_composer.rb'
     - 'lib/rubino/ui/cli.rb'
 
@@ -406,7 +408,6 @@ Naming/PredicateMethod:
   Exclude:
     - 'lib/rubino/agent/model_call_runner.rb'
     - 'lib/rubino/agent/response_validator.rb'
-    - 'lib/rubino/agent/router.rb'
     - 'lib/rubino/cli/onboarding_wizard.rb'
     - 'lib/rubino/cli/trust_gate.rb'
     - 'lib/rubino/memory/backends/sqlite.rb'
@@ -451,6 +452,7 @@ RSpec/AnyInstance:
     - 'spec/rubino/commands/commands_spec.rb'
     - 'spec/rubino/context/compressor_spec.rb'
     - 'spec/rubino/context/prompt_assembler_active_skill_spec.rb'
+    - 'spec/rubino/context/prompt_assembler_cache_breakpoints_spec.rb'
     - 'spec/rubino/context/prompt_assembler_ignore_rules_spec.rb'
     - 'spec/rubino/context/prompt_assembler_layering_spec.rb'
     - 'spec/rubino/context/prompt_assembler_memory_snapshot_spec.rb'
@@ -462,8 +464,10 @@ RSpec/BeforeAfterAll:
     - '**/spec/spec_helper.rb'
     - '**/spec/rails_helper.rb'
     - '**/spec/support/**/*.rb'
+    - 'spec/rubino/llm/tool_bridge_cache_breakpoint_spec.rb'
     - 'spec/rubino/security/approval_policy_mode_spec.rb'
     - 'spec/rubino/tools/registry_mode_spec.rb'
+    - 'spec/rubino/tools/registry_situational_gating_spec.rb'
     - 'spec/rubino/tools/registry_spec.rb'
 
 # Offense count: 31
@@ -550,7 +554,11 @@ RSpec/DescribeMethod:
     - 'spec/rubino/api/middleware/json_body_size_spec.rb'
     - 'spec/rubino/cli/chat_command_continue_spec.rb'
     - 'spec/rubino/cli/commands_version_spec.rb'
+    - 'spec/rubino/llm/ruby_llm_adapter_cache_spec.rb'
+    - 'spec/rubino/llm/tool_bridge_cache_breakpoint_spec.rb'
+    - 'spec/rubino/tools/registry_situational_gating_spec.rb'
     - 'spec/rubino/context/prompt_assembler_active_skill_spec.rb'
+    - 'spec/rubino/context/prompt_assembler_cache_breakpoints_spec.rb'
     - 'spec/rubino/context/prompt_assembler_ignore_rules_spec.rb'
     - 'spec/rubino/context/prompt_assembler_layering_spec.rb'
     - 'spec/rubino/context/prompt_assembler_memory_snapshot_spec.rb'
@@ -654,12 +662,13 @@ RSpec/LeakyLocalVariable:
   Exclude:
     - 'spec/rubino/no_direct_output_spec.rb'
 
-# Offense count: 7
+# Offense count: 8
 RSpec/MultipleDescribes:
   Exclude:
     - 'spec/rubino/commands/commands_spec.rb'
     - 'spec/rubino/context/prompt_assembler_layering_spec.rb'
     - 'spec/rubino/memory/backends_spec.rb'
+    - 'spec/rubino/tools/encoding_robustness_spec.rb'
     - 'spec/rubino/tools/error_code_spec.rb'
     - 'spec/rubino/tools/tool_fixes_spec.rb'
     - 'spec/rubino/trust_spec.rb'

data/AGENTS.md

@@ -77,7 +77,7 @@ lib/rubino/
 ## Surfaces this project exposes
 
 - **HTTP API** (`/v1/*`) — the canonical interface. See `docs/api/v1.md`.
-- **CLI** — `rubino {setup,chat,prompt,server,config,memory,sessions,jobs,tools,doctor,version}`.
+- **CLI** — `rubino {setup,chat,prompt,server,config,memory,sessions,jobs,skills,tools,tls_cert,doctor,version,update}`.
 - **Library** — `require "rubino"; Rubino.run(...)`.
 
 The interactive CLI ships as part of `rubino chat`. Multi-agent routing, MCP, and plugin hooks are designed in but not fully wired yet.

data/CHANGELOG.md

@@ -1,6 +1,142 @@
 # Changelog
 
-## [Unreleased]
+## [0.5.0] - 2026-06-15
+
+### Added
+
+- **One-shot tool-activity trace.** The non-interactive text path (`rubino
+  prompt` / `-q` / piped `chat`) now prints a concise per-tool activity trace
+  by default — one line per tool completion (`· edit foo.rb`, `· bash npm
+  test`) — routed to STDERR so the final answer on STDOUT stays clean
+  (`x=$(rubino prompt …)` captures only the answer). `--quiet`/`-Q` silences
+  the trace (machine-silent path); `--verbose`/`-v` widens each line's args.
+  `--output-format json`/`stream-json` (structured events on stdout) and the
+  interactive TUI tool-cards are unchanged. Mirrors the Codex/gemini-cli/Hermes
+  stderr-trace norm (Hermes `-q` default / `-Q` quiet).
+
+- **Prompt-cache breakpoints (`cache_control`).** The conversation now inserts
+  cache breakpoints so the stable prefix (system + tool schemas + prior turns)
+  is reused across round-trips, cutting input-token cost/latency.
+- **Situational tool-schema gating.** Tool definitions sent to the model are
+  scoped to the situation instead of always shipping the full set, reducing
+  prompt size and accidental tool selection.
+- **Primary-agent switching.** Switch the active primary agent inline with
+  `/<name>`, the `/agent` command, or `Tab`; `@` remains reserved for file
+  references.
+- **Detached post-turn polishing.** A post-turn polishing pass runs detached and
+  is cancellable with `Esc`, so it never blocks the next prompt.
+- **Stdin pipe for one-shot.** Piped stdin is consumed as the prompt for
+  one-shot runs (`echo … | rubino prompt`), enabling unix-style composition.
+- **Per-round-trip loop accounting.** Round-trips are counted, usage is summed
+  across them, and `tool_calls` are persisted on the streaming path.
+- **Machine-readable headless output (`--output-format json | stream-json`, #312).**
+  `rubino prompt` / `chat -q` can now emit Claude-Code-aligned JSON for
+  CI/automation instead of prose. `--output-format json` (or the `--json` alias)
+  prints a single `{type:"result", subtype, is_error, result, session_id,
+  exit_reason, num_turns, duration_ms, usage:{input/output/cache_* tokens},
+  total_cost_usd, model}` object on stdout at completion; `--output-format
+  stream-json` emits JSONL (a `system`/`init` line, then Messages-API-shaped
+  `assistant`/`user` step objects, then the same final `result`). In both modes
+  ALL JSON goes to stdout and ALL logs/diagnostics/errors to stderr, and markdown
+  rendering is suppressed. The fail-closed / exit-code contract is preserved: a
+  blocked tool still emits the result with `is_error:true` and a non-zero exit.
+  The schema lives in a single shared serializer (`Rubino::Output::ResultSerializer`)
+  so it never drifts. `text` (default) is unchanged.
+- **Higher tool-loop budget with an interactive extension prompt (#399).** The
+  `max_tool_iterations` default is raised from 8 to 25 so longer agent runs no
+  longer hit the cap mid-task. When the cap is reached interactively, the run
+  pauses with a budget-extension prompt — **Continue +N** (grant another batch),
+  **Summarize** (wrap up with what's done), or **Abort** — instead of failing
+  silently; headless runs keep the force-summarize behavior.
+- **TUI: Ctrl-L clear-screen and a resize-while-typing fix (#395 / #401).**
+  `Ctrl-L` now clears the screen from the composer. Fixed a bug where resizing
+  the terminal while typing reflowed and duplicated the in-progress input into
+  the scrollback.
+
+### Security
+
+- **Hardened/narrowed the command-allowlist convenience layer (SEC-R2-1/2/3).**
+  Closes three default-config / bare-`git` paths that could run arbitrary code
+  or write arbitrary files past the headless gate **without `--yolo`**:
+  - removed code-loading test/build runners (`bundle exec rspec`, …) from the
+    **shipped default** `command_allowlist` — they load and execute arbitrary
+    project code by design (`rspec -r FILE`), so they are not safely
+    auto-approvable (SEC-R2-3);
+  - an allowlisted **git** head is now vetted for GLOBAL flags before the
+    subcommand (`git -c alias.x='!cmd' x`, `-c core.sshCommand=…`, `-C dir`,
+    `--exec-path`) and for code-loading/mutating subcommands (`apply`, `am`,
+    `push`, hooks, …); the "approve git always" path now persists only a
+    narrowed `git <read-only verb>`, never bare `git` (SEC-R2-1);
+  - any allowlisted head whose argument is itself a program
+    (`awk`/`sed`/`perl`/`python`/`ruby`/`node`/`tar`/`tee`/`xargs`/shells) is
+    default-denied auto-approval, and write flags on read heads (`sort -o`, …)
+    are rejected (SEC-R2-2).
+
+  An allowlist is a convenience layer, **not** a security boundary (per industry
+  practice the OS sandbox is the real floor, tracked separately); this narrows
+  it to close the above default-config and bare-`git` RCEs.
+
+### Hardening
+
+Four adversarial QA rounds fixed ~45 issues across the agent. Highlights:
+
+- **Security.** Hardline-floor canonicalization; OOXML zip-bomb total-archive
+  cap; CWE-150 argument sanitization; threat-scanner; tightened
+  command-allowlist (see above).
+- **Correctness.** UTF-8-safe edits; atomic compaction with auto-switch-to-child;
+  resume keeps the full tool history; cwd-scoped sessions; corrupt-DB recovery
+  (incl. `NotADatabaseException`); job-queue compare-and-swap; headless job drain
+  so memory works in automation.
+- **Interrupt.** True cancel — stream cancellation with the partial persisted;
+  clean one-shot `SIGINT`/`SIGTERM` labels.
+- **Performance.** Bounded huge-output memory; spill/paste eviction; streaming
+  grep with consistent ignore rules.
+- **UX.** Config validation; `doctor` checks; resilient timeouts and error
+  classification.
+
+Every fix was container-verified (non-root QA image, real MiniMax for live
+behavior, true 0 failures); a full pre-release functionality sweep confirmed all
+subsystems release-ready.
+
+## [0.4.1] - 2026-06-13
+
+### Security
+
+- **Headless approvals now fail closed (#260).** A one-shot / scripted run
+  (`rubino prompt`, `chat -q`, no TTY) no longer auto-runs a tool that would
+  otherwise prompt: a write/edit, or a shell command not covered by your
+  `permissions` / command allowlist / read-only auto-allow, is **blocked, not
+  run**. A `blocked: <tool> needs approval …` line goes to stderr and the run
+  exits **2**, so CI/automation fails loudly instead of silently skipping (or
+  auto-executing). Full auto-exec now requires an explicit **`--yolo`** —
+  honored ONLY as a CLI flag, never grantable by a project-local/persisted
+  config — and **`--no-yolo`** forces fail-closed even over a yolo boot default.
+
+### Fixed — installer
+
+- **`mise` method (#256)** alongside Homebrew and `rv`, with `global`/`local`
+  scope (`RUBINO_INSTALL_SCOPE`); `RUBINO_INSTALL_METHOD` now accepts `mise`.
+- **Activation/PATH is persisted to your shell rc (#268)** (`.zshrc` /
+  `.bashrc` / `.profile`) and a **post-install fresh-shell gate** fails loudly
+  if `rubino` isn't on PATH in a new shell. `RUBINO_NO_MODIFY_RC=1` opts out.
+- **`mise` installs pin the latest published gem version (#258/#268)** instead
+  of drifting to a pre-release / age-gated build.
+- **Method-aware prereq preflight (#272)** (xz/git/toolchain) with real gem
+  error surfacing, and a **Debian-12 / glibc-too-old steer from rv → mise
+  (#241/#242/#272)** so users don't land on a broken musl Ruby.
+
+### Fixed
+
+- **Config corruption + `doctor` crash on a scalar written over a section (#259).**
+- **Streaming persistence (#266):** pre-tool narration is persisted and the
+  `tool_calls` audit is populated.
+- **TUI render (#269):** table columns sized to content, nested/markdown fences
+  consumed, interrupt "ghost" line cleared.
+- **Memory extraction bounded by a per-session cursor (#249)** — no more
+  re-scanning the whole transcript every turn.
+- **Boots under a bare C/POSIX locale (#273)** without
+  `Encoding::CompatibilityError`.
+- **Session summary folded into the single system message (#253/#254).**
 
 ## [0.4.0] - 2026-06-13
 

data/CONTRIBUTING.md

@@ -21,11 +21,20 @@ Run the CLI from the checkout with `bundle exec rubino <command>`.
 ## Tests
 
 ```bash
-bundle exec rspec                 # full suite
+bundle exec rspec                 # full suite (sequential; generates the coverage report)
 bundle exec rspec path/to/file_spec.rb
 bundle exec rake                  # default task == spec
+bundle exec rake parallel:spec    # full suite across all CPU cores (no coverage report)
+bundle exec rake parallel:spec[4] # ...forced to 4 workers
 ```
 
+`parallel:spec` shards the suite across one process per core via the
+`parallel_tests` gem; each worker is isolated by `TEST_ENV_NUMBER`
+(per-worker `RUBINO_HOME`, document fixtures, and example-status file).
+SimpleCov is skipped under parallel runs (the workers would race the
+coverage resultset) — use the sequential `bundle exec rspec` when you need
+the coverage report.
+
 The HTTP boundary is locked by an end-to-end contract suite under `spec/rubino/api/contract/`. When the docs and the contract suite disagree, **the contract suite is canonical** — update the docs to match.
 
 ## Lint

data/README.md

@@ -19,7 +19,15 @@ One line, Linux and macOS (x86_64 / arm64). Installs a compatible Ruby, then the
 curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install.sh | bash
 ```
 
-On **Linux** the installer fetches a precompiled Ruby via [`rv`](https://github.com/spinel-coop/rv). On **macOS**, if [Homebrew](https://brew.sh) is present it asks whether to use Homebrew (`brew install ruby`) or `rv`; without Homebrew it uses `rv` directly. Skip the prompt with `RUBINO_INSTALL_METHOD=brew` or `=rv`.
+The installer supports **three** methods for getting a compatible Ruby + the gem:
+
+- **`rv`** ([`rv`](https://github.com/spinel-coop/rv)) — fetches a precompiled Ruby into user space.
+- **Homebrew** (`brew install ruby`) — offered on **macOS** when [Homebrew](https://brew.sh) is present.
+- **`mise`** ([mise](https://mise.jdx.dev)) — a polyglot tool manager; installs `rubino` via its `gem:` backend and pins the latest published gem version.
+
+On **macOS** (interactive) you're asked to pick Homebrew / `rv` / `mise`; on **Linux** (interactive) you pick `rv` / `mise` (Homebrew is offered only if `brew` is already on PATH). Skip the prompt with `RUBINO_INSTALL_METHOD=brew`, `=rv`, or `=mise`. For the **mise** method, `RUBINO_INSTALL_SCOPE=global` (default, user-wide `~/.config/mise/config.toml`) or `=local` (this directory only, `./mise.toml`) chooses the scope.
+
+On **Debian 12 / old-glibc** systems `rv` would install a musl Ruby this glibc box can't execute; the installer detects that and **steers you from `rv` to `mise`** (precompiled, glibc-correct) so you don't land on a broken `rubino`.
 
 > **Review before you pipe.** Piping a script into your shell runs whatever it contains. Read it first:
 > ```bash
@@ -27,7 +35,7 @@ On **Linux** the installer fetches a precompiled Ruby via [`rv`](https://github.
 > less install.sh && bash install.sh
 > ```
 
-The installer is idempotent — safe to re-run — and prints the exact `PATH` line for the `rubino` executable plus the next step.
+The installer is idempotent — safe to re-run. It **persists the activation / `PATH` line to your shell rc** (`.zshrc` / `.bashrc` / `.profile`) and then runs a **fresh-shell verification gate** — it opens a clean login shell and fails loudly if `rubino` isn't on `PATH` there, instead of merely printing a hint you might miss. Opt out of any rc modification with `RUBINO_NO_MODIFY_RC=1` (the installer then prints the line for you to add yourself).
 
 **Manual install** (if you'd rather not pipe, or already manage Ruby yourself):
 
@@ -99,7 +107,7 @@ model:
 
 agent:
   max_turns: 90
-  max_tool_iterations: 8
+  max_tool_iterations: 25
 
 memory:
   enabled: true
@@ -142,7 +150,7 @@ Full reference (every key, env vars, precedence): **[docs/configuration.md](docs
 
 ## Built-in tools
 
-The agent ships **33 built-in tools**: `read`, `summarize_file`, `write`, `edit`, `multi_edit`, `grep`, `glob`, `git`, `github`, `shell`, `shell_output`, `shell_tail`, `shell_input`, `shell_kill`, `ruby`, `run_tests`, `apply_patch`, `webfetch`, `websearch`, `question`, `todowrite`, `memory`, `session_search`, `attach_file`, `vision`, `skill`, `task`, `task_result`, `task_stop`, `ask_parent`, `steer`, `probe`, `answer_child`. Each is gated by a `tools.<key>` config flag (opt-out) and the approval model. See **[docs/tools.md](docs/tools.md)**.
+The agent ships **27 built-in tools** (the set `rubino tools` lists): `read`, `read_attachment`, `summarize_file`, `write`, `edit`, `multi_edit`, `apply_patch`, `grep`, `glob`, `git`, `github`, `shell`, `shell_output`, `shell_tail`, `shell_input`, `shell_kill`, `ruby`, `run_tests`, `web`, `question`, `todowrite`, `memory`, `session_search`, `attach_file`, `vision`, `skill`, `task`. A single `web` tool gates both fetching a URL and searching (config key `tools.web`, off by default). Each tool is gated by a `tools.<key>` config flag (opt-out) and the approval model. See **[docs/tools.md](docs/tools.md)**.
 
 ## Skills
 
@@ -189,7 +197,8 @@ These are designed-in but not fully wired yet — don't depend on them in produc
 
 ```bash
 bundle install
-bundle exec rspec               # run tests
+bundle exec rspec               # run tests (sequential, with coverage)
+bundle exec rake parallel:spec  # run tests across all CPU cores
 bundle exec rubino doctor   # verify setup
 ```
 

data/Rakefile

@@ -6,3 +6,34 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+# Parallel test execution across CPU cores via the `parallel_tests` gem.
+#
+#   rake parallel:spec            # auto: one worker per core
+#   rake parallel:spec[4]         # force 4 workers
+#
+# Each worker is its own process with a distinct TEST_ENV_NUMBER, so the
+# per-process isolation already baked into spec/spec_helper.rb (RUBINO_HOME,
+# document fixtures, example-status file) keeps workers from colliding.
+# SimpleCov is skipped in parallel (workers would race the resultset); run the
+# plain sequential `rake spec` / `bundle exec rspec` for a coverage report.
+#
+# Balancing: we use parallel_tests' default **filesize** grouping rather than
+# runtime grouping. Runtime grouping (`--group-by runtime`) is strict — it
+# aborts with RuntimeLogTooSmallError whenever the recorded log is missing an
+# entry for any current spec file (i.e. the first run after ANY new spec is
+# added), which makes the entrypoint brittle. The wall-clock floor here is a
+# single ~70s example (agent_e2e error-retry) that cannot be split across
+# workers regardless of grouping, so filesize grouping already lands the
+# longest worker on essentially that floor while staying deterministic and
+# never breaking on a freshly-added spec.
+namespace :parallel do
+  desc "Run the RSpec suite in parallel across CPU cores (rake parallel:spec[N])"
+  task :spec, [:count] do |_t, args|
+    count = args[:count]
+    cmd = %w[bundle exec parallel_rspec]
+    cmd += ["-n", count.to_s] if count && !count.empty?
+    cmd += ["--", "spec"]
+    sh(*cmd)
+  end
+end

data/docs/agents.md

@@ -1,15 +1,22 @@
 # Agents & Subagents
 
-rubino has two distinct multi-agent surfaces. Only the first one ships today:
+rubino has two distinct multi-agent surfaces, and **both ship today**:
 
 1. **Background subagents** (✅ shipping) — the agent delegates bounded sub-tasks
    to isolated subagent runs via its `task` tool, and you supervise them with
-   `/agents` and `/reply`. This is the surface you will actually use.
-2. **Primary-agent switching** (⏳ not yet wired) — Tab-cycling between primary
-   agents and `@mention` routing. The machinery exists (`Agent::Router`,
-   `Agent::Definition`, `AgentRegistry`) but no call site passes an agent
-   definition yet, so the default (build) agent handles every turn. See
-   [the last section](#planned-primary-agent-switching--mentions-not-yet-wired).
+   `/agents` and `/reply`.
+2. **Primary-agent switching** (✅ shipping) — pick the primary agent that
+   handles your turns: `/agent <name>` (or a bare `/<name>` for a primary)
+   pins it for the session, **Tab** cycles through the primaries, and a one-shot
+   `/<name> <message>` routes a single message to any agent. The selected agent's
+   Definition (its system prompt and tool scope) is threaded into the runner each
+   turn, so the choice actually changes the model's persona/tools. See
+   [Primary-agent switching](#primary-agent-switching) below.
+
+> **Channels are cleanly separated:** `@` is the **workspace file** picker
+> (`@path/to/file`), and `/` is the **agent/command** channel. There are no
+> `@mention` agent routes — a filename like `@explore.rb` is always a file, never
+> an agent. Use `/explore`, `/plan`, etc. to reach an agent.
 
 ---
 
@@ -132,14 +139,15 @@ apply (hardline floor still enforced — see [security.md](security.md)).
 ## Built-in agent definitions
 
 These definitions exist in `Agent::AgentRegistry` today. The two *subagents*
-are live as `task` targets; the two *primary* agents are only reachable as the
-default (`build`) or via the plan **mode** (`/mode plan`), not via agent
-switching; the *utility* agents are internal.
+are live as `task` targets; the two *primary* agents are switchable per session
+(`/agent <name>`, a bare `/<name>`, or Tab — see
+[Primary-agent switching](#primary-agent-switching)); the *utility* agents are
+internal.
 
 | Agent | Type | Access | Description |
 |-------|------|--------|-------------|
-| **build** | primary | Full tools | Default development agent. Handles every turn today. |
-| **plan** | primary | Read-only | Analysis/planning definition (the shipping read-only surface is `/mode plan`). |
+| **build** | primary | Full tools | Default development agent (the registry default). |
+| **plan** | primary | Read-only | Analysis/planning agent. Switch to it with `/agent plan`; `/mode plan` is the orthogonal read-only run **mode**. |
 | **explore** | subagent | Read-only | Fast codebase search and navigation (`task` target). |
 | **general** | subagent | Full tools | Complex multi-step tasks (`task` target). |
 | **compaction** | utility | None | Internal: compresses context. Hidden. |
@@ -173,18 +181,29 @@ pattern-based permission overrides (merged over the global rules by
 
 ---
 
-## Planned: primary-agent switching & @mentions (not yet wired)
+## Primary-agent switching
 
-> **Status:** the machinery exists — `Agent::Router` (@mention detection,
-> Tab-cycling, default routing) and the `agent_definition:` plumbing through the
-> runner — but **no call site passes an agent definition**, so Tab and
-> `@explore`/`@plan`/`@general` mentions currently do nothing. Use the
-> background-subagent surface above for real work.
-
-The intended design: press **Tab** to cycle through primary agents, or route a
-single message with an `@mention`:
+You choose which primary agent handles your turns. The pinned agent is a
+process-level slot (`Rubino::ActiveAgent`, sibling to `Rubino::Modes`): a fresh
+`rubino chat` boots on the registry default (`build`), and an explicit switch
+takes effect for the rest of that process (no premature persistence). Switching
+is entirely on the **slash** channel and **Tab** — there is no `@mention` agent
+routing (`@` is the workspace file picker).
 
 ```
-you > @explore Where is the database connection configured?
-you > @plan How should we restructure the auth module?
+you > /agent plan          # pin a primary agent for the session
+you > /plan                # bare /<name> — same, for a primary agent
+you > <Tab>                # cycle through the primary agents, wrapping around
+you > /explore Where is the database connection configured?   # one-shot route a single message
 ```
+
+- **`/agent <name>`** (or a bare **`/<name>`** when `<name>` is a primary) pins
+  the agent for the session. Only **primary** agents are switchable; subagents
+  (`explore`/`general`) are never pinned.
+- **Tab** cycles through the primary agents.
+- **`/<name> <message>`** routes a single message to any agent (primary or
+  subagent) without changing the sticky selection.
+
+The selected agent's Definition — its system prompt and tool scope — is threaded
+into the runner on every turn, so switching actually changes the model's
+persona and the tools it can call, not just a cosmetic label.

data/docs/architecture.md

@@ -148,8 +148,8 @@ User Input
   ├─→ Commands::Executor (if /command)
   │     └─→ Render template → feed to agent
   │
-  ├─→ Agent::Router (if @mention)
-  │     └─→ Select agent definition
+  ├─→ ActiveAgent (if /agent, /<name>, or Tab)
+  │     └─→ Select primary agent definition
   │
   └─→ Interaction::Lifecycle
         │

data/docs/commands.md

@@ -60,7 +60,9 @@ is set.
 | `--new` | | Start a fresh session (bare `chat` resumes the last one by default) |
 | `--model` | `-m` | Override the model (e.g. `claude-sonnet-4-5`) |
 | `--provider` | | Override the provider (e.g. `anthropic`, `bedrock`) |
-| `--yolo` | | Skip approval prompts (equivalent to `/mode yolo`) |
+| `--yolo` | | Skip approval prompts (equivalent to `/mode yolo`). Honored **only** as a CLI flag — cannot be set from config |
+| `--no-yolo` | | Force fail-closed approvals even over a yolo default (the security half of [#260](#exit-codes-scripting-around-prompt--one-shot)) |
+| `--add-dir` | | Add an extra allowed workspace directory write/edit can reach (repeatable) |
 | `--max-turns` | | Max tool iterations per turn |
 | `--ignore-rules` | | Skip `AGENTS.md` and context files |
 
@@ -93,6 +95,18 @@ Pasting **text** into the chat input goes through the file-backed paste pipeline
   policy along the way (a write outside the workspace boundary, a denied
   approval, a hardline-blocked command). A refusal the agent handled and
   explained is expected behavior, not an error.
+- **Headless approvals fail closed (security).** A one-shot / scripted run has
+  no interactive session, so a tool that would otherwise prompt for approval —
+  a write/edit, or a shell command **not** covered by your `permissions` /
+  command allowlist / read-only auto-allow — is **blocked, not run**. A
+  single-line `blocked: <tool> needs approval but no interactive session (use
+  --yolo to allow, or allowlist it)` goes to stderr and the run exits
+  **non-zero (2)**, so automation/CI fails loudly instead of silently skipping
+  (or, worse, auto-executing) the action. Anything you already allowlisted, and
+  every read-only command, still runs unprompted. Pass `--yolo` to opt back
+  into full auto-execute; `--no-yolo` forces fail-closed even if a yolo default
+  was set. `--yolo` is honored **only** as a CLI flag — a project-local config
+  can never grant it.
 - It exits **non-zero** when the run itself fails: no usable credentials, the
   `--resume`/`--session` target doesn't exist or is ambiguous, or the provider
   call errors out. The reason is printed to stderr; the answer (when any) stays
@@ -160,9 +174,11 @@ Type these inside `rubino chat`. Generated from `BuiltIns::DESCRIPTIONS` (drift-
 | `/compact` | Compact the context now: older turns become a summary |
 | `/export` | Write the session transcript as markdown (/export [path]) |
 | `/memory` | Inspect/search/forget what the agent remembers (show ID, backend, --all) |
+| `/agent` | Switch the primary agent (/agent <name>; a bare /<name> or Tab cycles) |
 | `/agents` | List background subagents; steer/probe a running one, or view output |
 | `/tasks` | Alias for /agents |
 | `/reply` | Answer a subagent that is blocked waiting on you (ask_parent) |
+| `/stop` | Stop a running subagent (/stop <id>; alias for /agents <id> --stop) |
 | `/jobs` | List the background job queue (status counts); /jobs <id> for detail |
 | `/skills` | List skills; activate one ('none' clears), or enable/disable NAME |
 | `/mcp` | List MCP servers and their tools; restart or disable one |
@@ -371,6 +387,17 @@ Custom commands live as Markdown templates in `.rubino/commands/` (project) or `
 
 `/commands` lists the available custom commands and explains how to author them. See the [README](../README.md) for the template format (`$ARGUMENTS`, YAML frontmatter).
 
+### Primary agents: `/agent`, `/<name>`, and Tab
+
+Each turn runs under an **agent** — a persona with its own system prompt and tool scope. The built-ins are `build` (full access, the default) and `plan` (read-only analysis); `explore` and `general` are subagents you invoke one-shot. Switching the primary agent changes who answers the *next* turn:
+
+- `/agent` lists the switchable primaries (the current one marked `▸`) and the one-shot subagents.
+- `/agent <name>` — or a bare `/<name>` for a primary — **pins** that agent for the rest of the session (sticky). The active agent shows as an `agent <name>` chip in the status bar (omitted when it's the default `build`).
+- **Tab** on an empty prompt cycles the primary agents (the agent counterpart of Shift+Tab's mode cycle), updating the chip live.
+- `/<name> <message>` routes a **single** turn to that agent — any visible agent, primary or subagent (e.g. `/explore where is the parser`) — without disturbing your sticky pick.
+
+Distinct from `/agents` (plural), which drills into the background `task` subagents. `@` is the file picker, so a filename like `@explore.rb` is never shadowed by an agent named `explore`; agent switching lives entirely on the slash channel and Tab.
+
 ### Modes
 
 `/mode` (or the `--yolo` flag) switches between the modes below. **Shift+Tab** cycles them from the prompt (default → plan → yolo), updates the mode token that LEADS the status bar under the input (dim `default`, yellow `plan`, red `yolo`), and shows a transient `mode <old> → <new>` footer. Entering `yolo` from the cycle takes a second deliberate Shift+Tab to confirm (the toast says so, and warns when running background subagents would lose their approval gates); an explicit `/mode yolo` switches directly.

data/docs/configuration.md

@@ -102,8 +102,10 @@ auxiliary:
 ```yaml
 agent:
   max_turns: 90                              # Max turns per session
-  max_tool_iterations: 8                     # Max consecutive tool calls
-  max_turn_seconds: 120                      # Timeout per turn
+  max_tool_iterations: 25                    # Max per-turn model<->tool round-trips (cap)
+  budget_extension_prompt: true              # At the cap, prompt continue/summarize/abort (interactive only)
+  budget_extension_step: null                # "+N" per extension (null = max_tool_iterations)
+  max_turn_seconds: 120                      # Timeout per turn (outer rail; extensions never raise it)
   api_max_retries: 5                         # LLM API retry count (exp backoff)
   api_retry_backoff_cap_seconds: 16          # Max per-retry backoff draw
   api_retry_backoff_overload_cap_seconds: 60 # Higher cap used only for overload (529/503)
@@ -287,7 +289,7 @@ tools:
   workspace_strict: true  # Sandbox write/edit/delete to workspace_root; false = any reachable path
   git: true
   shell: true             # ON by default (the agent ships to run inside an isolated VM);
-                          # every command is still gated by security.require_confirmation_for_shell
+                          # dangerous commands are still gated by security.confirm_policy
   ruby: true
   web: false              # Gates BOTH the webfetch and websearch tools
   memory: true
@@ -372,12 +374,13 @@ attachments:
 
 ```yaml
 security:
-  # confirm_policy: "confirm_all"      # confirm_all (default) | dangerous_only; derived from the alias below when absent
-  require_confirmation_for_shell: true  # legacy alias for confirm_policy; true => confirm_all
-  command_allowlist:                    # prefix-matched commands pre-approved (empty = approve nothing)
+  confirm_policy: "dangerous_only"      # dangerous_only (default) | confirm_all
+                                        # (the old require_confirmation_for_shell key was removed)
+  command_allowlist:                    # pre-approved commands (read-only intent only; empty = approve nothing)
     - "git status"
     - "git diff"
-    - "bundle exec rspec"
+    # Test/build runners (bundle exec rspec, rake, npm test) are NOT shipped here:
+    # they load and run arbitrary project code, so add one only if you accept that.
   website_blocklist:
     enabled: false
     domains: []
@@ -461,20 +464,6 @@ formatters:
   "*.py": "black"
 ```
 
-### agents
-
-Custom agent definitions:
-
-```yaml
-agents:
-  security:
-    type: subagent
-    model: "anthropic/claude-sonnet-4-20250514"
-    description: "Security-focused code review"
-    tools: [read, grep, glob]
-    mcp_servers: []
-```
-
 ### prompts
 
 System-prompt layering. The defaults ship the built-in role prompts.
@@ -513,9 +502,17 @@ formatters:
   "*.py": "black"
 ```
 
-### agents (planned)
+### agents (planned — not yet read)
+
+> **Status: planned, has no effect today.** The `agents:` key is reserved but is
+> **not read** by the registry, so declaring custom agents in `config.yml` does
+> nothing yet. Primary-agent *switching* among the built-in agents already ships
+> (`/agent`, `/<name>`, Tab — see [agents.md](agents.md#primary-agent-switching));
+> what is not wired is authoring NEW agents from config. To register a custom
+> agent today, use `AgentRegistry#register` programmatically (see
+> [agents.md](agents.md#custom-agents-via-code)).
 
-Custom agent definitions (multi-agent routing is not fully wired yet — see [agents.md](agents.md)):
+The intended shape, once config-authored agents land:
 
 ```yaml
 agents:

data/docs/getting-started.md

@@ -4,7 +4,7 @@ From nothing to a working first answer in about five minutes. This is the happy
 
 ## 1. Install
 
-The fastest path on Linux (x86_64 / arm64) is the one-line installer. It installs a compatible Ruby via [`rv`](https://github.com/spinel-coop/rv), then the gem — all in user space, no sudo:
+The fastest path on Linux and macOS (x86_64 / arm64) is the one-line installer. It installs a compatible Ruby and then the gem — all in user space, no sudo:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install.sh | bash
@@ -17,7 +17,9 @@ curl -fsSL https://raw.githubusercontent.com/Jhonnyr97/rubino-agent/main/install
 less install.sh && bash install.sh
 ```
 
-The installer is idempotent (safe to re-run) and prints the exact `PATH` line for the `rubino` executable when it finishes.
+On Linux it offers a choice of Ruby provider — [`rv`](https://github.com/spinel-coop/rv) or [`mise`](https://mise.jdx.dev) (and Homebrew if `brew` is already present on macOS); pick non-interactively with `RUBINO_INSTALL_METHOD=rv|mise|brew`. On a **Debian 12 / old-glibc** box, prefer **mise**: `rv`'s musl build there yields a Ruby this glibc system can't run, so the installer steers `rv → mise` automatically. (For the mise method, `RUBINO_INSTALL_SCOPE=global|local` chooses user-wide vs this-directory-only. See the [README install matrix](../README.md#install).)
+
+The installer is idempotent (safe to re-run). When it finishes it **persists the activation / `PATH` line to your shell rc** (`.zshrc` / `.bashrc` / `.profile`) and then **verifies in a fresh shell** that `rubino` is on `PATH`, failing loudly if it isn't — so a new terminal just works. Opt out of rc edits with `RUBINO_NO_MODIFY_RC=1` (it then prints the line for you to add).
 
 **Already manage Ruby yourself?** Requirements are Ruby >= 3.1 and SQLite3; then:
 
@@ -85,7 +87,7 @@ The first thing you see is a banner with the workspace, git branch, and model. T
 
 ```
 ▍❯ what does this project do?
- default · MiniMax-M3 · ctx ~0/128k
+ default · openai/gpt-4.1 · ctx ~0/128k
 ```
 
 > If you skipped the wizard during `setup`, a bare `rubino chat` re-runs it before the first turn (when on a TTY). If you're piping input or using `-q`, there's no prompt to run — instead you get a clear, actionable error telling you how to set a key (see below).