rubino-agent 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db2afff4be97c340cbe86b9fb1b7509f1457abdfe812ac8c376e03421229ada1
-  data.tar.gz: efc19c01b592b21c70304f82fe9dbc4b76fea60b9dbdd63ed15fe5b5d0548f57
+  metadata.gz: 8a3a48a6f7deb104446c624354a271ff1a1671c9b3ea846cee1144b3f55538db
+  data.tar.gz: cbc407cd78db827d75f150f61045b2cce759b266816e32fdba874c30eb3647c4
 SHA512:
-  metadata.gz: fb700fb3a191d046737ad40b53d69c66a1e2c0cba573e04c6d3cfa803fa94cc2f1c74c09390ebda03424e6b30d19b9d4a948ee1ecfaba44926576b31c92d089a
-  data.tar.gz: 2eef17e973b05eb0eb5e6c0f7ee79ac8c8c440ea32f2c6ef589c06512319d0b03fac46879a480ee92923bf18167ede7fbd9ae14178ede83e32571058791890f6
+  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,177 @@
 # 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
+
+### Added — skills from git (#4)
+
+- **`rubino skills install <owner/repo | git-URL>`** — install skills from any
+  git repo shipping the `<name>/SKILL.md` layout (`--skill NAME` / `--all` /
+  `--list`; `--documents` is shorthand for the four `anthropics/skills`
+  document skills). Provenance lands in `~/.rubino/skills/.sources.json`, so
+  **`rubino skills update`** re-fetches from the recorded source (up-to-date vs
+  updated by commit) and **`rubino skills remove NAME`** only deletes what this
+  mechanism installed. `rubino skills list` gains a Source column.
+- The skill registry now also discovers the agent-neutral `.agents/skills/`
+  and `~/.agents/skills/` dirs (the `npx skills` / Gemini CLI convention) —
+  additive, lowest precedence, trust-gated like `.rubino/skills`.
+
+### Added
+
+- **`/agents <id>` watch — live tool-output tail (#5).** The drill-in watch grows an `output:` block showing the tail of the running subagent's current tool output, clearing when the tool finishes.
+- **`soffice` and `qpdf` in the `[Environment]` probe (#4/#6)** so the agent honestly reports whether LibreOffice/qpdf are available for the document skills.
+
+### Fixed
+
+- **`read_attachment` extension-spoof gate now covers document MIMEs (#239).** A text file named `report.docx` reads inline as text instead of bouncing off the document converter; a real `.docx` (ZIP magic) still classifies as a document.
+- **No more CLI crash under a C/POSIX locale (#250).** Skill and context files are read as UTF-8 rather than the ambient (US-ASCII) encoding, so `rubino skills list` and prompt assembly no longer raise `invalid byte sequence` on minimal Linux/Docker images.
+- **Installer no longer always exits 1 on a fresh Linux box (#240).** Fixed an unbound `rv_bin` under `set -u` and an invalid `gem environment gembindir` call; `curl … | bash` now installs cleanly and is idempotent.
+
+### Internal
+
+- **Test stability (#236):** PTY capture specs read to the child's EOF instead of treating a 0.5s quiet window as end-of-output, removing a rare 2-failure flake under concurrent suite load.
+- **Approval-handoff guard (#10):** the #80 unit guard now genuinely fails on a full revert; the PTY handoff spec is relabeled as a happy-path check.
+
+## [0.3.0] - 2026-06-06
+
+Major capability release: the core conversation loop was ported 1:1 from the reference implementation (formalized LLM boundary, retry/backoff/fallback, degenerate-response recovery), background subagents became the default delegation path, the memory subsystem grew a pluggable backend contract with a tiny-Zep SQLite backend that is now the default, CLI gained image/file input and a scroll-native redesign, and a reference-aligned approval model (hardline floor, dangerous-pattern deny, prefix-derived rules) landed. Consolidated from `feature/subagent-view` (#48) plus #49-#58.
 
 ### Added — CLI redesign & in-chat surfaces
 
@@ -107,10 +278,6 @@ The GitHub repository is `github.com/Jhonnyr97/rubino-agent`. Publishing the ren
 
 - `docs/api/v1.md` aligned to the real API surface (#165, #166, #167): SSE catalogue documents the non-streaming contract (no `message.delta`/`reasoning.delta`), the approval decision enum lists all seven accepted values with semantics, and `GET /v1/sessions`, `/v1/memory*`, `/v1/tasks*` are documented. A doc-drift spec locks the documented route list to the registered routes.
 
-## [0.3.0] - 2026-06-06
-
-Major capability release: the core conversation loop was ported 1:1 from the reference implementation (formalized LLM boundary, retry/backoff/fallback, degenerate-response recovery), background subagents became the default delegation path, the memory subsystem grew a pluggable backend contract with a tiny-Zep SQLite backend that is now the default, CLI gained image/file input and a scroll-native redesign, and a reference-aligned approval model (hardline floor, dangerous-pattern deny, prefix-derived rules) landed. Consolidated from `feature/subagent-view` (#48) plus #49-#58.
-
 ### Breaking / upgrade notes
 
 - **Default memory backend is now SQLite (tiny-Zep).** `memory.backend` now defaults to `"sqlite"` (previously `"default"`). The new backend reads/writes the `:memory_facts` table; the old `"default"` backend used the `:memories` table. On upgrade, users who were on the previous `"default"` backend and do **not** pin `memory.backend: "default"` in their config will stop reading their prior memory store — the new backend looks only at `:memory_facts`. Your old data in `:memories` is **not deleted**, just no longer read. **No automatic backfill is shipped.** To keep old recall, pin `memory.backend: "default"` in config. (Acceptable for alpha; documented here.)

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

@@ -13,7 +13,7 @@ Two surfaces: **CLI subcommands** (run from your shell) and **slash commands** (
 | `rubino memory SUBCOMMAND` | Manage persistent memories (`list` / `show` / `delete` / `backend`) |
 | `rubino sessions SUBCOMMAND` | Manage chat sessions |
 | `rubino jobs SUBCOMMAND` | Manage background jobs |
-| `rubino skills SUBCOMMAND` | Manage skills (`list` / `show` / `enable` / `disable`) |
+| `rubino skills SUBCOMMAND` | Manage skills (`list` / `show` / `enable` / `disable` / `install` / `update` / `remove`) |
 | `rubino tools` | List available tools and their enabled/disabled state |
 | `rubino server` | Start the JSON API + SSE server |
 | `rubino tls-cert` | Print the agent's self-signed TLS certificate PEM (generating it if absent) |
@@ -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
@@ -129,10 +143,15 @@ rubino jobs list
 rubino jobs process          # run pending jobs now (manual mode)
 rubino jobs worker           # start a background worker
 
-rubino skills list           # list skills with enabled/disabled markers
+rubino skills list           # list skills with enabled/disabled markers + provenance
 rubino skills show NAME      # print a skill's SKILL.md body (review before enabling)
 rubino skills enable NAME    # put a skill back in the index (every session)
 rubino skills disable NAME   # drop a skill from the index (every session)
+
+rubino skills install owner/repo --skill NAME   # install skills from a git repo (#4)
+rubino skills install --documents               # anthropics/skills: pdf docx pptx xlsx
+rubino skills update [NAME ...]                 # re-fetch from the recorded sources
+rubino skills remove NAME                       # delete an installed skill + provenance
 ```
 
 `config get`/`config show` mask secret-named keys (`api_key`, tokens, …) on display — the file keeps the real value. See [memory.md](memory.md) for the memory backends, [jobs.md](jobs.md) for the queue/cron system and [skills.md](skills.md) for the skill model.
@@ -155,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 |
@@ -366,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.