rubino-agent 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a3a48a6f7deb104446c624354a271ff1a1671c9b3ea846cee1144b3f55538db
-  data.tar.gz: cbc407cd78db827d75f150f61045b2cce759b266816e32fdba874c30eb3647c4
+  metadata.gz: c1debe685b923c625e0dc4dcf95da3c9fc12fcd6c73bdff71e35164279e62b06
+  data.tar.gz: 5451e122fc13bfdd4ffeba0e680cad9fb6b976dfabe8f9dcfd894e5215ac9688
 SHA512:
-  metadata.gz: 3342a4c8b1856691788ac9625b81eb4058870a0eb5a75946e99e6570ce40a05a7b44475a798863ac0fc92c9fcb505cf6caf27fcedc10a8e1bd9653ba18edf440
-  data.tar.gz: e54077b30f385942dd3591fb7e6c4e7afc0f301e5fea9d3111732c91ce56e63a4c7d192704ebd74ea97ee4a04437784d73a8d398bf02ce6143cdd69b2227a841
+  metadata.gz: bf657914d128053ffa39d7911a5c2c12e491ff45b1907e8bc78a694b8f8d7540a1e8d1182ee5831670af17e5e64b16148202d987ebc9e2c75604a88f78148d36
+  data.tar.gz: eefe6fbbcd977bff1cf8b7a189fdaf73daee9ca6b12ca55b82876a99c55ede529dc78ba3f5146f8b34a7e6e6b6b38dab454c9d6cdcf3baca8e754187f49c6829

data/.rubocop.yml

@@ -27,6 +27,12 @@ AllCops:
     # Test fixtures are sample input documents (e.g. a .rb code sample for the
     # plain-text converter), not project source -- they must not be linted.
     - "spec/fixtures/**/*"
+    # Eval-harness fixtures are deliberately tiny/imperfect sample projects the
+    # agent edits at eval time (INPUT, not source); results/ is generated output.
+    # The eval/.rubocop.yml excludes these for an in-eval run; mirror it here so
+    # the whole-repo lint from the root is clean too.
+    - "eval/fixtures/**/*"
+    - "eval/results/**/*"
 
 # --- House style: strings ----------------------------------------------------
 

data/.rubocop_todo.yml

@@ -538,6 +538,7 @@ RSpec/DescribeClass:
     - 'spec/rubino/skills/skills_spec.rb'
     - 'spec/rubino/tools/edit_read_gate_spec.rb'
     - 'spec/rubino/tools/shell_background_spec.rb'
+    - 'spec/rubino/tools/shell_background_completion_spec.rb'
     - 'spec/rubino/tools/shell_input_spec.rb'
     - 'spec/rubino/tools/tool_fixes_spec.rb'
     - 'spec/rubino/ui/bottom_composer_approval_handoff_pty_spec.rb'

data/CHANGELOG.md

@@ -1,5 +1,322 @@
 # Changelog
 
+## [0.5.1] - 2026-06-25
+
+### Added
+
+- **Tool-output compression (deterministic, off by default).** A no-LLM content
+  router at the single `Agent::ToolExecutor` seam compresses high-volume tool
+  output before it reaches the model: test/build/lint logs are reduced to their
+  failures + summary (≈97% fewer tokens on a failing suite, every failure kept),
+  and a whole-file source read can be returned as a skeleton (signatures kept,
+  large bodies elided behind a `read offset:/limit:` pointer). Diffs, grep/search
+  results, JSON, and short output pass through **byte-identical**. Reversibility
+  reuses the existing spill: the full original is written to
+  `tool-results/<call_id>.txt` and the compressed output points the model there —
+  no separate store/tool. When enabled, `read` and `shell` expose a `compress`
+  parameter (default true) so the model can opt a single call out and get the
+  verbatim output. Master switch `tool_output_compression.enabled` (default
+  `false`); `rubino setup` offers to turn it on. See
+  [configuration.md](docs/configuration.md#tool_output_compression).
+- **Multi-language code compression.** The whole-file source-skeleton compressor
+  now covers more than Ruby. `tool_output_compression.code.languages` (default
+  `["ruby"]`) selects which languages get skeletonised: Ruby (built-in Prism
+  parser), Python (stdlib `ast` via your `python3` — a no-op if `python3` isn't
+  on PATH), and JavaScript / TypeScript / TSX (via the optional
+  `tree_sitter_language_pack` gem — a no-op until it's installed). A read in an
+  unlisted language passes through verbatim. `rubino setup` adds a language
+  picker and, if you choose JS/TS, offers to install the parser gem.
+- **Agent-attach view.** At the idle prompt, `↓` opens the subagent picker and
+  `Enter` now **attaches** to the highlighted background subagent: the screen
+  switches to that agent's OWN full timeline (its tool calls and what it said,
+  replayed from its session) and the input prompt becomes scoped — `sa_xxxx ❯`.
+  While attached, typed text steers the running child (or answers it when it's
+  blocked on you); `←` on the empty prompt (or the picker's `◂ main` row) returns
+  to the main timeline, and the picker doubles as a switcher between agents. This
+  replaces the bounded registry snapshot the picker's Enter used to show with the
+  agent's real conversation, and makes the global `/agents <id> steer/probe` and
+  `/reply <id>` forms redundant while attached. The attached view **live-tails**
+  the child's stream (tool rows and streaming prose) exactly like the main agent
+  instead of freezing on a snapshot, and `/back` / `/detach` return to the main
+  agent regardless of composer-draft state (#82, #85, #87).
+- **`api.allow_public_bind` gate.** Because the API server can execute shell
+  tools, binding it to a non-loopback address (`--host 0.0.0.0`,
+  `RUBINO_API_HOST`) now **refuses to boot** unless `api.allow_public_bind: true`
+  is set in `config.yml`; when opted in, the server prints a one-time exposure
+  warning. Loopback binds are unaffected (#577).
+- **MCP tool transparency + parallel startup.** An MCP tool's display label now
+  carries its source — the live tool card and the approval card both show
+  `<bare> (mcp:<server>)`, so you can tell at a glance that an out-of-process
+  server is running (the model-facing tool name is unchanged) (#582). MCP
+  servers also now connect **in parallel** at boot, so one hanging server no
+  longer serializes startup (#576).
+- **Read-only meta-commands run immediately while a turn is active.** A small
+  set of non-mutating slash commands (`/agents`, `/tasks`, `/stop`, `/status`,
+  `/jobs`, `/help`, `/commands`, `/dirs`) now execute **immediately** mid-turn
+  instead of queuing — so you can drill into a sub-agent, stop the run, or check
+  status without interrupting. State-mutating commands (`/model`, `/clear`,
+  `/new`, `/config`, `/mode`, …) show a transient `⚠ <cmd> is not available
+  during an active turn — press Esc to interrupt first` notice; plain text still
+  queues, and `Esc` interrupts.
+- **Interactive CLI session picker.** A bare `rubino sessions` on a TTY opens an
+  interactive picker (id, title, message count, dir, age; arrow-key highlight,
+  type-to-filter, `Esc` cancels) and `Enter` resumes the chosen session. On a
+  pipe / non-TTY it prints a script-safe list; `sessions list` stays list-only.
+  The picker is cwd-scoped by default; `--all` unscopes it.
+- **`/sessions rename <id|title> <new title>`.** Rename a session from the REPL
+  (#45).
+- **Aux-LLM session titles.** When `auxiliary.title` names a concrete backend,
+  new sessions get an LLM-generated, length-capped summary title; the
+  deterministic derivation stays the default and the fallback (#45).
+- **Streaming GFM table rendering (#89).** A markdown table now renders as a
+  live, correctly-fitted table as it streams — a sliding window of recent rows
+  grows in place — instead of leaking raw `| col | col |` pipes that only snap
+  into a table once the message completes.
+
+### Changed
+
+- **Provider auto-routing.** With `model.provider: "auto"` (the default), the
+  concrete provider is derived from the model id (`openai/*` → OpenAI); the
+  setup wizard / auto-detect write an explicit provider when a non-OpenAI
+  backend is chosen.
+- **Credential check uses provider-specific env vars.** The credential check
+  and key resolution now read the env var for the configured provider
+  (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `BEDROCK_API_KEY`,
+  `MINIMAX_API_KEY`, and `<PROVIDER>_API_KEY` for anything else, e.g.
+  `DEEPSEEK_API_KEY`). A non-OpenAI provider no longer silently falls back to
+  `OPENAI_API_KEY` (only providers explicitly marked `openai_compatible` /
+  `anthropic_compatible` fall back to `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`).
+- **`security.confirm_policy` default is `dangerous_only`.** Safe shell commands
+  run unprompted; only commands matching a dangerous pattern prompt. Set
+  `confirm_policy: confirm_all` to restore prompt-on-everything. The
+  non-bypassable hardline floor and `permissions: deny` always run first
+  regardless of policy.
+- **Removed the built-in `run_tests` and `github` tools.** Running tests and
+  GitHub/git operations now go through the generic `shell` tool (with its
+  hardened git arg parsing), matching the field norm and shrinking the tool
+  surface.
+- **Blocked-tool results are now typed errors.** When a tool call is blocked
+  (denied by approval, sandbox, or policy), its result is returned to the model
+  as a typed error with explicit anti-confabulation wording, so the model is told
+  the action did NOT happen instead of being free to assume success (#583).
+- **Single status bar during a turn.** The animated facet activity row is folded
+  into the model/ctx footer (one bar, not two); the "esc to interrupt" hint shows
+  exactly once, and a mid-stream **waiting indicator** resurfaces beneath the
+  in-flight tail after a short window of model/transport silence and drops away
+  the instant tokens resume (#21, #56b — `/status` now also shows the workspace
+  cwd line).
+- **FIFO approval queue for concurrent subagents.** When multiple subagents need
+  approval at once, one modal shows at a time with an "(N more queued)"
+  indicator that dequeues on resolve, and async-completion notices no longer
+  print over an active modal. Subagent approvals also **escalate to the parent's
+  approval card at any nesting depth**, so a nested child no longer fail-closes
+  with a noninteractive block (#86).
+- **Slash commands dispatch while attached to a subagent** (`/stop <id>`,
+  `/agents`, `/status`, …) instead of being steered into the child as text;
+  `/skills list` / `/skills ls` show the skills list rather than trying to
+  activate a skill named `list`; `/think off` hides the reasoning aside for
+  always-thinking models unless an explicit `/reasoning` is set; `/config <key>`
+  resolves the short labels `/status` advertises (`reasoning`, `effort`,
+  `think`) (#62, #66, #87).
+- **`/new` returns instantly.** The end-of-session memory flush is enqueued as a
+  background job instead of running a synchronous aux-LLM extract, so starting a
+  new session no longer freezes the prompt for 2–3s.
+- **Headless one-shot drains only its own jobs.** `rubino -q` now emits and
+  flushes the JSON result envelope before draining, and scopes the post-turn job
+  drain to the run's own session, so a one-shot returns immediately even with a
+  background job backlog.
+- **Subagent cards are distinguishable + carry the task id.** Concurrent
+  subagent cards label by a dimension drawn from the task prompt (rather than the
+  bare agent type), background "done" markers carry the task id, and the live
+  elapsed counter shows seconds (`1m05s`) so it visibly advances (#44, #570).
+- **Pastes coalesce into a single placeholder**, input history is recalled and
+  persisted, `Enter` accepts the highlighted dropdown candidate, and
+  `task_result` running-polls no longer flood the transcript (#524, #525).
+- **System-prompt grounding for control + tools.** The cap / continuation /
+  summary control is framed as trusted `[harness control]` so MiniMax-M3 stops
+  treating it as prompt-injection (#75); the background-shell lifecycle is primed
+  so the model uses `shell_output` / `shell_kill` correctly; the verification
+  step is scoped to never modify the environment and to stop honestly.
+- **Memory-flush best-effort boundary** made airtight (#471), so a failure
+  flushing memory at shutdown can't take down the run.
+
+### Removed
+
+- **Child→parent `ask_parent` / `answer_child` tools.** Subagents are
+  non-blocking background workers and can no longer pause mid-task to ask their
+  parent (or the human) a question; instead they make sensible default calls and
+  surface open decisions in their result. The two model-facing tools that
+  implemented that channel — `ask_parent` (the child→parent escalation) and
+  `answer_child` (the parent's reply) — are gone. The parent→child `steer` /
+  `probe` tools and the human approval gate (`/reply` for a child parked on an
+  approval) are unchanged. `tasks.ask_parent_timeout` is now vestigial.
+- **`streaming.cursor` config key.** It was dead config (assigned, never read)
+  and is no longer accepted — remove it from any `config.yml`.
+- **`security.require_confirmation_for_shell` config key.** Replaced by
+  `security.confirm_policy` (`dangerous_only` | `confirm_all`); the old key is no
+  longer honored.
+
+### Security
+
+- **Hermes-style secret handling (#506).** Adopts the Hermes secret model across
+  the agent: the structured `read` tool blocks `.env` and credential files
+  outright, and secret **values** are redacted in the output of `read`, `grep`,
+  `shell` (including the live stream seam, not just the final buffer, #507),
+  `summarize`, and `read_attachment` (#511/#512). A `security.redact_secrets`
+  toggle (default **on**) controls redaction. The earlier per-read secret-file
+  approval gate was removed in favour of this block-list + redaction model
+  (#480). Over-broad redaction was then narrowed: the `ENV_ASSIGN` pattern is
+  anchored so `AUTHORS` / `SECRETARY` pass through while `API_KEY` / `AUTH_TOKEN`
+  still redact, the Telegram-token pattern is pinned to its canonical shape, and
+  fully-masked secrets carry an explicit marker rather than a bare `***`
+  (#67, #516).
+- **Secrets are no longer persisted to memory (#99).** A `Security::SecretDetector`
+  is wired into the memory write path (it refuses an explicit save and the
+  auto-extract persist path) and into the redactor, catching prefixed key
+  shapes, prefix-less AWS secret keys, and a high-entropy heuristic — previously
+  an `sk-proj-…` key could be saved verbatim and re-injected into every future
+  system prompt.
+- **Removed the dedicated `git` tool (RCE bypass).** Git now runs through the
+  hardened `shell` with strict arg parsing that rejects exec vectors
+  (`--ext-diff`, `-c`, textconv, …) plus a `GIT_HARDENED_ENV`, instead of a tool
+  that could be steered into arbitrary command execution (#536/#553).
+- **Dangerous write/exec flag-forms prompt under the default gate (#61).**
+  `git -c` / `--output`, `sed -i`, `sort -o`, `find -delete` / `-exec`,
+  `tar --to-command`, `tee`, interpreter `-c` / `-e` / `--eval`, etc. no longer
+  auto-run under `dangerous_only`, while bare interpreters and read-only forms
+  still auto-run. A shared `Security::CommandNormalizer` also closes
+  line-continuation evasion (e.g. `rm -r\<newline>f` no longer slips past the
+  danger/approval layer).
+- **Extended HOME credential read-block.** Reading credential stores under HOME
+  is blocked and a base64-decode-pipe-to-shell (`echo … | base64 -d | sh`) is
+  flagged dangerous (#519); the denylist now covers `.ssh`, `.aws`, `.netrc`,
+  `.git-credentials`, `.kube`, `.docker`, `.gnupg`, `.azure`, and `.config/gh`
+  (#537). A write through a **dangling in-workspace symlink** can no longer
+  escape the sandbox — the link target is resolved before the create-new-file
+  fallback (#62).
+- **Tighten the `ruby_llm` floor to `>= 1.16` (#508).** The adapter wires native
+  providers through ruby_llm's generic `<provider>_api_base=` setters
+  (deepseek/mistral/etc., #482), which only exist from ruby_llm 1.16.0. The
+  gemspec previously allowed `~> 1.0`, so a fresh `gem install` could resolve
+  ruby_llm 1.15 and crash at runtime with `NoMethodError`. The dependency is now
+  `>= 1.16, < 2.0`.
+- **Secret masking on `config set`.** `rubino config set` now masks the echoed
+  value when the key looks secret (`api_key`, `token`, `password`, `secret`,
+  `authorization`, …) and when the value itself contains inline credentials
+  (`key=value`, `Bearer …`, URL userinfo, `curl -u`, `mysql -p…`), so keys are
+  not printed in the clear to the terminal/scrollback.
+- **Sanitized untrusted text rendered to the terminal (CWE-150).** Text that
+  originates from the model, tools, or filenames (subagent cards, `/`-palette and
+  `@`-picker menu labels, and the remaining CLI aside sinks — probe, reasoning,
+  open-fence, branch title) is now defanged of ANSI/OSC escape sequences before
+  it is written, closing an escape-injection class (#563/#564/#565–#568).
+- **Vision egress hardening.** The `vision` tool now honours
+  `attachments.policy.aux_vision_egress` (default `true`): set it to `false` and
+  the tool refuses to send an image to an external auxiliary model, returning a
+  clean error instead of egressing the bytes (#578). Before any egress it also
+  **content-sniffs** the file (magic bytes win over the extension, fail-closed),
+  so a mislabelled or non-image file can't be smuggled to the external host
+  (#579).
+- **OS sandbox covers more executors.** The OS write-jail (Landlock / Seatbelt)
+  now also confines background shells, `ruby`, and `run_tests`, with relaxation
+  gated on verified enforcement; a write-jail `EACCES` outside the workspace
+  produces an attributable "blocked by write-jail" hint (#74).
+
+### Fixed
+
+- **MiniMax-M3 pre-tool-call "freeze".** Thinking/reasoning now defaults ON for
+  every provider (it was deliberately off for MiniMax-family ids). On the
+  anthropic-compatible path rubino now sends `thinking: {type: enabled,
+  budget_tokens: …}` and streams the model's reasoning deltas — so the multi-
+  second window where M3 reasons toward a tool-call is filled with visible
+  streamed reasoning instead of dead air (the symptom that read as the agent
+  "freezing" when it spawned subagents). Matches the reference agent's default
+  `reasoning_effort: medium`. A backend that rejects the budget is caught and
+  retried once without it (#75), so default-on is safe; set
+  `providers.<name>.supports_thinking: false` to opt out.
+- **MCP `degraded` server state.** `/mcp` and `rubino doctor` now distinguish a
+  reachable server (`●`) from a **degraded** one (`⚠` — the process is alive but
+  a protocol call such as `tools/list` failed), instead of reporting it as plain
+  reachable (#575).
+- **Session-title length cap.** A renamed session title is now length-capped at
+  rename and truncated on render, so an over-long title can't disrupt status /
+  session-list layout (#581).
+- **Streaming fidelity.** A streaming turn no longer re-executes or re-surfaces
+  tool calls it already ran (no double "started" line or duplicate final tool)
+  (#53), and a split think/fence sentinel is held across the message-boundary
+  flush so reasoning no longer leaks into the body and prose isn't torn apart
+  (#43/#54). A committed markdown table glued to trailing prose no longer leaks
+  raw pipes, and a too-wide table fits the pane instead of tearing the border.
+- **Subagent / multiplexer UI.** A running `blocked_on_parent` sub stays visible
+  in the footer while listed; cap-rejected delegation renders a neutral
+  "at capacity" row instead of a phantom failed card; the close-row / replay use
+  the per-call subagent name instead of a shared stale one (#35); the agent
+  picker opens reliably on `↓` and `←`/`↑` backs out; picking `◂ main` returns to
+  main immediately mid-turn; a nested child's menu no longer crashes it; and the
+  parent autonomously resumes at idle when background subagents finish while
+  detached (#37, #44, #51, #561).
+- **Interrupt handling.** `Esc` at the tool-dispatch boundary raises a clean
+  interrupt instead of a malformed continuation that the backend rejects as
+  "invalid params"; a stray `Ctrl-C` exits cleanly (130) with no raw `net/http`
+  backtrace; and a background thread never dumps a backtrace on death.
+- **Input papercuts.** Backspace (`DEL 0x7f`) deletes instead of inserting a
+  space (#522); a single `Ctrl-D` at an idle empty composer no longer hangs, and
+  fast input bursts coalesce their redraws (#520). Several composer
+  render/input races and resize-while-typing reflows that duplicated the
+  in-progress input into the scrollback are fixed, including chained resizes and
+  the resize REPAINT path (#481/#485/#486/#499/#500/#501/#503).
+- **`edit` no longer crashes on non-UTF-8 / binary buffers.** Fuzzy-match
+  normalization passes invalid-encoding bytes through verbatim (#47), atomic
+  writes are binmode'd so binary buffers never transcode (the intermittent
+  in-session edit crash on accented files) (#65), and `clean_slice` reinterprets
+  binary as UTF-8 rather than calling `.encode` (#58). A failed edit / read /
+  write now shows `✗` instead of a green `✓`.
+- **Background jobs and shells.** The job queue drains reliably — stale `running`
+  rows are reclaimed after the lease expires (#76) and `ExtractMemoryJob` is
+  prioritized over `SummarizeSessionJob` so save→recall doesn't lag (#79);
+  finished background shells are retired with their buffer and exit status
+  retained, so `shell_output` / `shell_tail` / `shell_kill` stay reachable next
+  turn (#78); shell cancel no longer orphans the child process group, and a
+  finished background shell auto-wakes the model.
+- **Turn-ledger honesty.** Blocked / errored tools no longer count toward the
+  "N tools ran / M edits" ledger, so a turn whose only tool was refused stops
+  telling you to review nonexistent changes; the force-summary and closing-summary
+  nudges are grounded in the truthful turn ledger so the model can't confabulate
+  having done nothing (#36/#84). MiniMax HTTP 429 / quota errors are categorized
+  as retryable rate-limit (honouring `Retry-After`) instead of "Invalid request",
+  and the anti-confabulation note no longer over-fires on accurate local caveats.
+- **Sessions / resume / doctor.** A per-session `flock` guard stops a concurrent
+  `--continue` from forking a moving transcript (#543), replay renders only the
+  new tail of a restated final message (#542), `--resume <id>` is validated
+  before the boot banner (#521), and `doctor` warns instead of false-green when
+  no usable credential exists and no longer implies an unverified key is
+  validated (#541/#546).
+- **Non-native provider wiring (#482).** Fixed the preflight that falsely
+  reported non-native providers (deepseek/mistral/…) as ready; they are now
+  wired through the generic `<provider>_api_base=` setters and the run stops
+  on an unreachable endpoint instead of failing later. Transient name-resolution
+  failures (`EAI_AGAIN`) are retried rather than fatal, and a stream that ends
+  without a finish signal is recovered instead of failing the turn.
+- **Parent-death reaps child shells (#478).** When the agent process dies, the
+  long-running child shells it spawned are reaped instead of being orphaned,
+  using a trap-safe SIGTERM/SIGHUP handler (no `Mutex` inside the signal trap).
+- **Compaction no-op loop (#484).** Stopped a busy-loop on an over-budget
+  session that has too few messages to compact. The `doom_loop.threshold`
+  default is also no longer rejected by its own validator (#60).
+- **Memory polish indicator no longer flashes every turn (#59).** The polish
+  worker starts only when a row was actually enqueued, the indicator composes
+  alongside the ctx bar instead of replacing it, and a verbatim repeat
+  short-circuits to the existing row at the write seam.
+- **`/exit` and exit codes.** `/exit` routes through the quit-guard, and an
+  interactive session exits non-zero on an auth/credential error (#154).
+- **CLI DX papercuts.** Fixed the bare-`rubino "prompt"` one-shot path, help-
+  session clutter, a bare-prompt did-you-mean edge case, and a `read_attachment`
+  hint that suggested markitdown for raster images instead of OCR.
+- **Input hardening.** Fixed a raw SQLite3 exception on session input with
+  hostile/NUL bytes (#498) and cleaned up `Errno` error messages on the failure
+  paths; tightened mcp args validation and assorted low-severity
+  config/sessions/resume/CLI papercuts.
+
 ## [0.5.0] - 2026-06-15
 
 ### Added

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:
@@ -111,7 +161,7 @@ agent:
 
 memory:
   enabled: true
-  backend: "sqlite"           # tiny-Zep FTS5 + graph-lite recall (default)
+  backend: "sqlite"           # SQLite FTS5 + graph-lite recall (default)
   auto_extract: true
 
 compression:
@@ -126,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
 ```
 
@@ -142,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)**
@@ -150,7 +200,7 @@ Full reference (every key, env vars, precedence): **[docs/configuration.md](docs
 
 ## Built-in tools
 
-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)**.
+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
 
@@ -191,7 +241,6 @@ 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
 

data/Rakefile

@@ -7,6 +7,23 @@ 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

data/docs/agents.md

@@ -68,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`
 
@@ -86,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.
@@ -99,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.
@@ -113,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
 

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
@@ -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
         │