rubino-agent 0.4.0 → 0.5.1

data/README.md

@@ -5,12 +5,62 @@ A coding & automation **agent** — small, self-contained, and built to run *whe
 ## Why rubino
 
 - **Runs where the work is** — a single gem on the machine (or VM) that holds the code, not a remote service you pipe files to.
-- **Persistent memory** — a tiny SQLite "Zep"-style fact store that learns about you and the project across sessions.
+- **Persistent memory** — a tiny SQLite fact store that learns about you and the project across sessions.
 - **Context compaction** — automatic compression with session lineage when the conversation outgrows the window.
 - **CLI *and* HTTP API** — an interactive terminal session for humans, a bearer-protected JSON + SSE API for programs.
-- **Real tools, gated** — read/write/edit, shell, ruby, git/github, grep/glob, a structured test runner, vision, and more, behind an approval model with a non-bypassable hardline floor.
+- **Real tools, gated** — read/write/edit, shell, ruby, grep/glob, apply_patch, vision, and more (git, GitHub, and tests run through the hardened shell), behind an approval model with a non-bypassable hardline floor.
 - **Built on ruby_llm** — provider-agnostic: MiniMax, OpenAI, Anthropic, Gemini, or an OpenAI-compatible gateway.
 
+## Cache-friendly compaction (measured)
+
+A long agent session only stays cheap if the cached prompt prefix survives
+compaction. rubino is built so that when the conversation is compressed into a
+summary, the summary lands *after* the cached head (system + tools + stable
+history) — so the provider's prompt cache keeps **hitting** the head instead of
+re-encoding it cold every time the session is compacted.
+
+Measured with the model held fixed (local oMLX `Qwen3.6-35B-A3B`,
+Anthropic-style `cache_control`) on a 25-turn coding session that triggers
+compaction **9 times**:
+
+| metric | rubino |
+|---|---|
+| cached prefix retained right after each compaction | **44–94%** (survives — never resets to 0) |
+| cumulative cache-read over the whole session | **88%** |
+| prefix byte-stability across turns | **0.95** |
+| task solved through all 9 compactions | **10/10** hidden tests, 0 wasted work |
+
+Holding the model fixed isolates the **engine** — any difference is the
+scaffolding (prompt assembly, where the compaction summary is placed, cache
+breakpoints), not the model. This is a single model and a single scenario:
+indicative of the design, not a leaderboard. The harness lives in a separate
+benchmark project.
+
+## Tool-output compression (measured)
+
+Test logs, diffs and large command dumps are mostly noise. rubino can route
+each tool output through a **deterministic (no-ML)** compressor that keeps the
+signal and drops the rest — opt-in (`tool_output_compression`), with a
+byte-identical passthrough for anything already small and a `retrieve_output`
+pointer back to the full text. Token-honest: counts are the **exact**
+`prompt_tokens` reported by the server (local oMLX `Qwen3.6-35B-A3B`), not
+chars/4 estimates.
+
+| tool output | reduction | fidelity (verified) |
+|---|---:|---|
+| rspec full suite (21 failures, ~8k lines) | **97%** | all 21 failures + the tally kept |
+| `git log --stat` / `ls -R` | **94%** | boundary/keyword lines kept |
+| large source diff (9 files) | **42%** | all 575 ± lines, 13 hunks, 9 headers |
+| `package-lock.json` diff (60 bumps) | **99%** | file header + summary (body elided) |
+| whole-file Ruby read → skeleton | **27%** | signatures + structure kept |
+| JSON (kubectl / docker / gh, uniform rows) | **40–88%** | error rows + outliers always kept |
+| rubocop (already signal-dense) | 11% | floor — every offense kept |
+
+End-to-end A/B on real edit tasks: **12/12 tasks passed with compression ON and
+OFF** — it never broke a task, and every forced-failure run still recovered the
+single failing line out of a long log. Routing is verified (each output goes to
+the right strategy) and small inputs pass through **byte-identical**.
+
 ## Install
 
 One line, Linux and macOS (x86_64 / arm64). Installs a compatible Ruby, then the gem — all in user space, no sudo:
@@ -19,7 +69,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 +85,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,11 +157,11 @@ model:
 
 agent:
   max_turns: 90
-  max_tool_iterations: 8
+  max_tool_iterations: 25
 
 memory:
   enabled: true
-  backend: "sqlite"           # tiny-Zep FTS5 + graph-lite recall (default)
+  backend: "sqlite"           # SQLite FTS5 + graph-lite recall (default)
   auto_extract: true
 
 compression:
@@ -118,7 +176,7 @@ tools:
   git: true
   shell: true                 # ON by default; every command is still approval-gated
   ruby: true
-  web: false                  # gates BOTH webfetch and websearch
+  web: true                   # ON by default (keyless DuckDuckGo backend); gates BOTH webfetch and websearch
   memory: true
 ```
 
@@ -134,7 +192,7 @@ Full reference (every key, env vars, precedence): **[docs/configuration.md](docs
 - **[Configuration](docs/configuration.md)** — full config + env vars + precedence
 - **[Tools](docs/tools.md)** — the built-in tool set and approval behavior
 - **[Skills](docs/skills.md)** — reusable instruction packs, the 3-level disclosure, and `SKILL_LOADED` observability
-- **[Memory](docs/memory.md)** — the SQLite tiny-Zep backend
+- **[Memory](docs/memory.md)** — the SQLite memory backend
 - **[Security](docs/security.md)** — approval model, hardline floor, TLS
 - **[Troubleshooting](docs/troubleshooting.md)** — keyed on the exact error strings
 - **[HTTP API](docs/api/v1.md)** · **[Jobs & cron](docs/jobs.md)** · **[OAuth providers](docs/oauth-providers.md)** · **[Architecture](docs/architecture.md)**
@@ -142,7 +200,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`, on by default via the keyless DuckDuckGo backend; it degrades gracefully when no search backend is reachable). Each tool is gated by a `tools.<key>` config flag (opt-out) and the approval model. See **[docs/tools.md](docs/tools.md)**.
 
 ## Skills
 
@@ -183,13 +241,13 @@ These are designed-in but not fully wired yet — don't depend on them in produc
 
 - **MCP Support** — connect to Model Context Protocol servers via [ruby_llm-mcp](https://github.com/patvice/ruby_llm-mcp) ([docs/mcp.md](docs/mcp.md)).
 - **Multi-Agent** — Build / Plan / Explore agents with `@mention` routing ([docs/agents.md](docs/agents.md)).
-- **Plugin Hooks** — event hooks for extending behavior ([docs/plugins.md](docs/plugins.md)).
 
 ## Development
 
 ```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,51 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+# API documentation. `rake rdoc` regenerates the HTML API docs into doc/rdoc
+# (gitignored); the .github/workflows/docs.yml workflow publishes the same
+# output to GitHub Pages. Guarded so the Rakefile still loads if the `rdoc`
+# default gem is somehow absent.
+begin
+  require "rdoc/task"
+
+  RDoc::Task.new(:rdoc) do |rdoc|
+    rdoc.rdoc_dir = "doc/rdoc"
+    rdoc.main     = "README.md"
+    rdoc.title    = "rubino-agent API documentation"
+    rdoc.rdoc_files.include("lib/**/*.rb", "exe/*", "README.md", "CHANGELOG.md", "docs/*.md")
+  end
+rescue LoadError
+  # `rdoc` unavailable -> the `rake rdoc` task is simply not defined.
+end
+
+# 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.
 
 ---
 
@@ -61,15 +68,21 @@ message instead of fanning out unbounded work:
 | Glyph | Status | Meaning | You act via |
 |---|---|---|---|
 | `●` | `running` | Working (last activity shown) | — |
-| `●` | `needs_approval` | A child tool needs your approval | `/agents <id>` |
-| `⛔` | `blocked_on_human` | Asked a question only YOU can answer (`ask_parent` escalated to the human) | `/reply <id> <answer>` |
-| `◷` | `blocked_on_parent` | Asked its agent-parent a question — the PARENT MODEL answers (`answer_child`); not your job unless you choose to step in with `/reply` | (optional) `/reply <id>` |
+| `●` | `needs_approval` | A child tool needs your approval (or a budget request) | `/agents <id>` or `/reply <id>` |
+| `⛔` | `blocked_on_human` | Vocabulary glyph for a child parked on the human (not raised in normal operation now that subagents are non-blocking) | `/reply <id> <answer>` |
+| `◷` | `blocked_on_parent` | Vocabulary glyph for a child parked on its agent-parent (likewise not raised now that subagents are non-blocking) | (optional) `/reply <id>` |
 | `◌` | `stopping` | Stop requested; unwinding at its next checkpoint | — |
 | `✓` | `done` | Finished; result available | `/agents <id>` |
 | `✗` | `failed` | Errored; error available | `/agents <id>` |
-| `⊘` | `stopped` | Cancelled by you (`--stop`); blocked descendants unwound; tools that completed before the stop may have left side effects | `/agents <id>` |
+| `⊘` | `stopped` | Cancelled by you (`--stop`); descendants unwound; tools that completed before the stop may have left side effects | `/agents <id>` |
 
-A `⛔ N subagent waiting on you` marker persists until you `/reply`.
+Subagents are **non-blocking** background workers: they never pause to ask you a
+mid-task question. The one way a child waits on you is an **approval** — its next
+tool needs your go-ahead, so it parks as `needs_approval` and a marker persists
+until you resolve it (via `/agents <id>` or `/reply <id>`). The `⛔
+blocked_on_human` / `◷ blocked_on_parent` glyphs remain in the status vocabulary
+the `/agents` surface can render, but with the child→parent ask channel removed
+they are no longer raised in normal operation.
 
 ### Supervising from the CLI: `/agents` and `/reply`
 
@@ -79,12 +92,31 @@ A `⛔ N subagent waiting on you` marker persists until you `/reply`.
 /agents <id> --stop           # cancel a running subagent (blocked descendants unwind too)
 /agents <id> steer "note"     # park a note folded into the child's context at its next turn
 /agents <id> probe "question" # ephemeral read-only peek — nothing is saved to the child
-/reply <id> <answer>          # answer a child blocked on an ask_parent question
+/reply <id> <answer>          # answer a child blocked on you (e.g. an approval)
 /reply                        # bare: list the subagents currently blocked on you
 ```
 
 `/tasks` is an alias for `/agents`. Stopping a node cancels its descendants'
-ask-gates too, so a blocking question anywhere in the subtree unwinds at once.
+approval gates too, so anything parked anywhere in the subtree unwinds at once.
+
+#### Attach to a subagent (agent-view)
+
+The typed forms above work by id from anywhere, but the fastest way to focus on
+one running child is to **attach**. At the idle prompt press `↓` to open the
+subagent picker, arrow to one, and `Enter`:
+
+- the screen switches to that agent's **own full timeline** — its tool calls and
+  what it said, replayed from its session (not the bounded activity snapshot the
+  picker used to show);
+- the prompt becomes **scoped** to it: `sa_xxxx ❯`;
+- while attached, just **type** to steer the running child (or answer it if it's
+  blocked on you) — no id needed; `←` on the empty prompt (or `/detach`) returns
+  to the main timeline.
+
+So attaching makes `/agents <id> steer/probe` and `/reply <id>` redundant for the
+focused child — they're the same operations, just addressed by id. Attach is a
+between-turns action (it owns the screen): while a parent turn is still streaming
+the picker's `Enter` toasts "attach when the turn ends" — attach once it's idle.
 
 **steer** is a persistent course-correction: the note enters the child's context
 at its next turn boundary and changes its trajectory.
@@ -92,12 +124,15 @@ at its next turn boundary and changes its trajectory.
 child's transcript; the answer is shown to you and discarded — nothing is
 appended to the child's history.
 
-### Parent↔child channels (model-driven)
+### Parent→child channels (model-driven)
 
-The same three verbs are MODEL-callable tools, so an agent-parent can supervise
-its own children the way you supervise yours. All are gated by `tools.task` and
-**ownership-scoped at call time** — a caller can only touch its own direct
-children (see [tools.md](tools.md) for parameters):
+Both verbs are MODEL-callable tools, so an agent-parent can supervise its own
+children the way you supervise yours. They are **parent→child only** — a
+subagent has no channel to ask its parent a question mid-task (subagents are
+non-blocking; they make sensible default calls and surface open decisions in
+their result instead). Both are gated by `tools.task` and **ownership-scoped at
+call time** — a caller can only touch its own direct children (see
+[tools.md](tools.md) for parameters):
 
 - **`steer(task_id, note)`** — park a persistent note on one of your running
   children; it folds into the child's context at its next turn.
@@ -106,19 +141,6 @@ children (see [tools.md](tools.md) for parameters):
   activity, recent lines); `live: true` is a billed one-shot model peek over the
   child's transcript, budgeted per child (`tasks.max_live_probes_per_child`,
   default 5).
-- **`ask_parent(question, blocking:)`** — the child→parent escalation (only
-  available to subagents). `blocking: false` (default) keeps the child working
-  and folds the answer in later; `blocking: true` parks the child until answered,
-  bounded by `tasks.ask_parent_timeout` (default 900s — on expiry the child
-  proceeds with its best judgement instead of hanging).
-  Routing depends on who spawned the child: an agent-parent gets the question as
-  a note and answers with `answer_child` (child shows `◷ blocked_on_parent`); a
-  human-spawned child escalates straight to you (`⛔ blocked_on_human`, answered
-  via `/reply`). A parent that cannot answer from its own context escalates by
-  calling its OWN `ask_parent` — questions bubble up the tree to the human.
-- **`answer_child(task_id, answer)`** — the agent-parent's `/reply`: delivers
-  the answer into the asking child's context (unblocks a blocking ask, folds in
-  for a non-blocking one).
 
 ### Approvals inside a background child
 
@@ -132,14 +154,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 +196,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

@@ -17,9 +17,8 @@ Infrastructure Layer   →  LLM Adapter, Database, MCP, OAuth
 1. **All output goes through UI** — No `puts`/`print` in core modules
 2. **LLM is isolated** — Only `LLM::RubyLLMAdapter` talks to ruby_llm
 3. **SQLite is the single database** — Sessions, memory, jobs, events
-4. **Event-driven** — Core emits events, UI/plugins subscribe
-5. **Plugin hooks** — 38 declared extension points for customization (design surface; few are wired today)
-6. **Config is not architecture** — Configuration describes what; architecture decides how
+4. **Event-driven** — Core emits events, UI subscribes
+5. **Config is not architecture** — Configuration describes what; architecture decides how
 
 ## Module Map
 
@@ -96,11 +95,6 @@ Experimental — booted at chat startup when `mcp.servers` is configured
 - `DoomLoopDetector` — Detects repeated identical tool calls
 - `CommandAllowlist` — Pre-approved shell commands
 
-### `plugins/`
-- `Registry` — Central hook registry; the hook set (38 points) is declared in
-  `plugins.rb` as a design surface, with few hooks wired today
-- Loaded from `.rubino/plugins/`
-
 ### `skills/`
 - `Skill` — Parsed SKILL.md with YAML frontmatter
 - `Registry` — Discovery from configured paths
@@ -148,8 +142,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
         │
@@ -167,7 +161,6 @@ User Input
         │    │    ├─ Check permissions (ApprovalPolicy)
         │    │    ├─ Check doom loop (DoomLoopDetector)
         │    │    ├─ Execute tool (ToolExecutor)
-        │    │    ├─ Run plugin hooks
         │    │    └─ Loop back to LLM
         │    └─ Final text response
         │

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 |
 
@@ -83,6 +85,7 @@ Pasting **text** into the chat input goes through the file-backed paste pipeline
 - `--new` forces a fresh session; `--continue`/`-c` resumes the latest; `--resume`/`-r <id|title>` resumes a specific one.
 - `--resume` matches an ID prefix first, then a case-insensitive substring of the session title **or its full first prompt** — so a memorable phrase from the tail of a long first message works even though the stored title is truncated. More than one match is an error listing the candidates; no match exits non-zero with a pointer to `rubino sessions list`.
 - One-shot mode (`-q` / `prompt`) does **not** auto-resume — automation isn't silently hijacked onto a past session; pass `--resume`/`--continue` explicitly if you want it.
+- A bare **`rubino sessions`** on a real terminal opens an arrow-key resume picker over this directory's sessions (`--all` for every dir); ↑↓ select, Enter loads the chosen session into the chat REPL (the same as `rubino chat --session <id>`), Esc cancels. Off a TTY (piped/redirected) it prints the static `list` table so scripts stay deterministic; `rubino sessions list` is always the table.
 - One-shot output: when stdout is a **terminal** the answer renders through the same markdown pipeline as interactive chat (styled text, fitted tables, wrapping); when stdout is **piped/redirected** the answer stays plain raw text and diagnostics go to stderr, so `$(rubino prompt …)` stays clean.
 - Sessions are marked ended on clean exit, terminal close (SIGHUP), or kill (SIGTERM), so a closed window doesn't leave a session looking active.
 
@@ -93,6 +96,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
@@ -120,6 +135,7 @@ rubino memory show ID
 rubino memory delete ID
 rubino memory backend [NAME] # show the active memory backend, or switch to NAME
 
+rubino sessions             # on a TTY: arrow-key resume picker (Enter loads, Esc cancels); piped: lists
 rubino sessions list
 rubino sessions show ID
 rubino sessions compact ID
@@ -160,9 +176,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) |
-| `/agents` | List background subagents; steer/probe a running one, or view output |
+| `/agent` | Switch the primary agent (/agent <name>; a bare /<name> or Tab cycles) |
+| `/agents` | List background subagents; ↓+Enter to attach & steer one live, or steer/probe/view by id |
 | `/tasks` | Alias for /agents |
-| `/reply` | Answer a subagent that is blocked waiting on you (ask_parent) |
+| `/reply` | Answer a subagent that is blocked waiting on you (e.g. an approval) |
+| `/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 |
@@ -186,9 +204,10 @@ Type these inside `rubino chat`. Generated from `BuiltIns::DESCRIPTIONS` (drift-
 
 You can keep typing while a turn is running — the pinned input stays live:
 
-- **Enter** interrupts the current turn and runs your line as the **next** turn (the partial answer is kept and marked `⎿ interrupted`).
-- **Alt+Enter** queues the line **without** interrupting: it runs after the current turn finishes, with a live `⏳ queued:` indicator above the input until it does. At idle (no turn running) there is nothing to queue behind, so Alt+Enter submits the line immediately, same as Enter.
-- **`/queued <message>`** is the terminal-independent fallback for Alt+Enter (some terminals don't deliver the chord) — it queues the message the same way.
+- **Enter** queues the line **without** interrupting (the queue-by-default / type-ahead model, #421): the current turn keeps running, the line waits behind any earlier-queued items (FIFO) with a live `⏳ queued:` indicator above the input, and it is committed as a normal message when its turn runs. At idle (no turn running) Enter submits immediately.
+- **Esc** interrupts the current turn (the partial answer is kept and marked `⎿ interrupted`); any queued lines then run as the next turns.
+- **`/queued <message>`** queues a message explicitly — the terminal-independent way to enqueue without typing it into the live input.
+- **Read-only meta-commands run immediately, mid-turn.** A small set of non-mutating slash commands — `/agents` (and `/tasks`), `/stop`, `/status`, `/jobs`, `/help`, `/commands`, `/dirs` — execute **right away** while a turn is running, so you can drill into a sub-agent, stop the run, or check status without interrupting. State-mutating commands (`/model`, `/clear`, `/new`, `/config`, `/mode`, `/reasoning`, `/think`, …) are not available mid-turn: they show a transient `⚠ <cmd> is not available during an active turn — press Esc to interrupt first` notice instead of running.
 
 ### Keys: `Esc Esc` — rewind to an earlier message
 
@@ -308,12 +327,21 @@ The agent spawns background subagents with its `task` tool; these commands are t
 /agents <id> --stop           # cancel a running subagent (blocked descendants unwind too)
 /agents <id> steer "note"     # park a note folded into the child's context at its next turn
 /agents <id> probe "question" # ephemeral read-only peek — nothing is saved to the child
-/reply <id> <answer>          # answer a subagent blocked on an ask_parent question
+/reply <id> <answer>          # answer a subagent blocked on you (e.g. an approval)
 /reply                        # bare: list the subagents currently blocked on you
 ```
 
 `/tasks` is an alias for `/agents`.
 
+**Attach to a subagent (agent-view).** Instead of typing ids, press `↓` at the
+idle prompt to open the subagent picker, arrow to one, and `Enter` to **attach**:
+the screen switches to that agent's own full timeline (its tool calls and what it
+said, replayed) and the prompt becomes scoped — `sa_xxxx ❯`. While attached, just
+type to steer the running child (or answer it if it's blocked on you); `←` on the
+empty prompt (or `/detach`) returns to the main timeline. The scoped prompt makes
+the global `/agents <id> steer/probe` and `/reply <id>` forms redundant — they're
+the same operations, by id, from anywhere.
+
 ### Workspace roots: `/add-dir` and `/dirs`
 
 The workspace sandbox confines write/edit/delete tools to the workspace roots. `/add-dir <path>` adds an extra allowed root mid-session (and runs the one-time folder-trust gate, so the new root's `AGENTS.md`/skills are only honored once vouched for); `/dirs` lists the current roots and their trust state. Typing `/add-dir ` opens a directory-path dropdown (relative, absolute, and `~` paths complete as you type).
@@ -371,6 +399,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.