rubino-agent 0.3.0 → 0.5.0

data/docs/configuration.md

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

data/docs/getting-started.md

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

data/docs/security.md

@@ -4,7 +4,7 @@ rubino runs real tools — shell, file writes, Ruby, git. The safety model is la
 
 ## Is it safe to enable shell?
 
-Yes. `tools.shell` is **on by default** because the agent ships to run inside an isolated VM where running commands is the whole point. Every command is still gated: by default `security.require_confirmation_for_shell` is `true`, so each shell command goes through an approval prompt, and a hardline floor blocks catastrophic commands regardless of any setting.
+Yes. `tools.shell` is **on by default** because the agent ships to run inside an isolated VM where running commands is the whole point. Every command is still gated: by default `security.confirm_policy` is `dangerous_only`, so a command matching a dangerous pattern goes through an approval prompt (set it to `confirm_all` to prompt on every command), and a hardline floor blocks catastrophic commands regardless of any setting.
 
 ## The approval decision order
 
@@ -51,10 +51,12 @@ Actions: `allow`, `ask`, `deny`. A `deny` rule is a deny-class check and beats e
 
 ## Shell confirmation policy
 
-`security.confirm_policy` (with `security.require_confirmation_for_shell` as a legacy alias):
+`security.confirm_policy`:
 
-- **`confirm_all`** (default; alias `true`) — every shell command not otherwise allowed/denied prompts for approval.
-- **`dangerous_only`** (alias `false`) — safe commands run unprompted; only commands matching a dangerous pattern prompt. The hardline floor and `permissions: deny` still run first, so this never weakens the floor.
+- **`dangerous_only`** (default) — safe commands run unprompted; only commands matching a dangerous pattern prompt. The hardline floor and `permissions: deny` still run first, so this never weakens the floor.
+- **`confirm_all`** — every shell command not otherwise allowed/denied prompts for approval.
+
+(The old `security.require_confirmation_for_shell` key was **removed** — it is no longer honored. Use `security.confirm_policy`.)
 
 ## Command allowlist
 
@@ -65,11 +67,14 @@ security:
   command_allowlist:
     - "git status"
     - "git diff"
-    - "bundle exec rspec"
 ```
 
 An **empty** allowlist pre-approves nothing — pre-approval is opt-in.
 
+A matched entry pre-approves only its **read-only intent**, never a smuggled write/exec form: an allowlisted head can't carry an output/exec flag (`git diff --output FILE`, `sort -o FILE`, `find -exec/-delete`), a git **global** flag (`git -c alias.x='!cmd' x`, `git -c core.sshCommand=…`, `git -C dir`, `--exec-path`), or a mutating/code-loading git subcommand (`git apply`, `git am`, `git push`, hooks). Heads whose argument is itself a program (`awk`, `sed`, `perl`, `python`, `ruby`, `node`, `tar`, `tee`, `xargs`, shells) are **never** auto-approved even if allowlisted — they still prompt. The **shipped default** is read-only git only; test/build runners (`bundle exec rspec`, `rake`, `npm test`) are deliberately not shipped auto-approved because they load and execute arbitrary project code by design — add one explicitly only if you accept that.
+
+> An allowlist is a **convenience** layer, not a security boundary. Per industry practice (Claude Code/Codex, GTFOBins) a deny/allow list of command strings cannot be exhaustive; the OS sandbox is the real floor. This layer is narrowed to close the default-config and bare-`git` RCEs, not to be relied on as the only barrier.
+
 ## Auto-allowed read-only commands
 
 A built-in allowlist layer (`Security::ReadonlyCommands`, **on by default**) lets provably read-only shell commands run without a prompt. It is evaluated at the same decision step as the command allowlist — *below* the hardline floor and `permissions: deny`, which always win, even for commands you add yourself.
@@ -99,6 +104,12 @@ approvals:
     - "docker ps"             # multi-word entry matches those leading tokens
 ```
 
+## Headless / non-interactive approvals fail closed
+
+A one-shot or scripted run (`rubino prompt`, `chat -q`, or any run with no TTY) has **no interactive session to approve from**, so it **fails closed**: 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 single-line `blocked: <tool> needs approval but no interactive session (use --yolo to allow, or allowlist it)` goes to stderr and the run exits **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.
+
+To opt back into full auto-execute, pass **`--yolo`**; **`--no-yolo`** forces fail-closed even if a yolo default was set. `--yolo` is honored **only** as a CLI flag — a project-local or persisted config can never grant it, so an untrusted checkout can't silently switch a scripted run into auto-execute. The hardline floor and explicit `permissions: deny` rules still apply under `--yolo`. (See [commands.md §Exit codes](commands.md#exit-codes-scripting-around-prompt--one-shot).)
+
 ## Deny/approve scope: once vs session
 
 At the approval prompt you can decide for just this call or for the rest of the session. Session approvals are remembered by a **prefix/pattern class**, not the raw command:

data/docs/skills.md

@@ -31,6 +31,12 @@ skills:
 Override the search paths via the `skills.paths` config key. On a name collision
 the **directory** layout wins over the flat-file layout (it is the richer unit).
 
+The registry additionally scans the **agent-neutral** skill dirs — project
+`.agents/skills/` and `~/.agents/skills/` (the emerging cross-agent convention
+used by `npx skills`, Gemini CLI, goose) — at the lowest precedence: a
+rubino-path skill of the same name wins, and nothing changes when those dirs
+are absent. The project-local one is trust-gated exactly like `.rubino/skills`.
+
 ### Two layouts
 
 | Layout | Path | Skill name | Bundled files |
@@ -59,6 +65,31 @@ skills:
   include_builtin: false   # default true
 ```
 
+### Installing skills from git (`rubino skills install`)
+
+Any git repo shipping the `<name>/SKILL.md` layout is a skill source — there is
+no marketplace and nothing else is vendored in the gem. Skills are
+shallow-cloned and copied into `~/.rubino/skills`, where the registry discovers
+them like any hand-written skill:
+
+```bash
+rubino skills install anthropics/skills --list        # see what a source ships
+rubino skills install anthropics/skills --skill pdf   # pick by name (repeatable)
+rubino skills install owner/repo --all                # take everything
+rubino skills install https://gitlab.com/o/r.git      # any git URL works
+rubino skills install --documents                     # anthropics/skills: pdf docx pptx xlsx
+rubino skills update                                  # re-fetch installed skills
+rubino skills remove NAME                             # delete dir + provenance
+```
+
+With no `--skill`/`--all` and multiple skills in the source, the CLI prints the
+catalogue and asks you to pick (off a TTY it just prints the hint). Provenance
+is recorded per installed skill in `~/.rubino/skills/.sources.json`
+(`name → {source, path, commit}`): `rubino skills list` shows it in the Source
+column, and `update` re-fetches from the recorded source, reporting
+*up to date* vs *updated* by comparing commits. `remove` only deletes skills
+this mechanism installed — hand-written skills are never touched.
+
 ### Authoring a `SKILL.md`
 
 A `SKILL.md` is YAML frontmatter followed by the instruction body:

data/docs/troubleshooting.md

@@ -48,7 +48,7 @@ The sqlite backend ranks by direct content relevance (FTS5/BM25) first; graph/re
 
 ## The agent keeps asking to approve every shell command
 
-That's `security.require_confirmation_for_shell: true` (the default `confirm_all` policy). Options: approve for the session at the prompt, add prefixes to `security.command_allowlist`, switch to `dangerous_only` (`security.confirm_policy: dangerous_only`), or use `/mode yolo` / `--yolo` to skip prompts (the hardline floor and `permissions: deny` still apply). See [security.md](security.md).
+That's the `confirm_all` policy (`security.confirm_policy: confirm_all`). The default is `dangerous_only` (only dangerous-pattern commands prompt). Options: switch back with `rubino config set security.confirm_policy dangerous_only`, approve for the session at the prompt, add prefixes to `security.command_allowlist`, or use `/mode yolo` / `--yolo` to skip prompts (the hardline floor and `permissions: deny` still apply). See [security.md](security.md).
 
 ## A command was denied even with `--yolo`
 

data/exe/rubino

@@ -1,9 +1,23 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# On a bare POSIX/C-locale system Ruby's default_external is US-ASCII, so any
+# File.read of a UTF-8 prompt/template (em-dashes etc.) raises
+# Encoding::CompatibilityError before the agent even boots (#273; same class as
+# #250/#251). Pin the process to UTF-8 up front so NO read path can regress,
+# regardless of the user's locale. Promoting to UTF-8 is always safe; only
+# touch it when the locale left us on a non-UTF-8 default.
+Encoding.default_external = Encoding::UTF_8 unless Encoding.default_external == Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8 unless Encoding.default_internal == Encoding::UTF_8
+
 require "rubino"
 
-# Load .env before anything else so ENV vars are available immediately
-Rubino::Config::Loader.new.load
+# Load .env before anything else so ENV vars are available immediately.
+# A malformed config.yml must NOT crash the process with a raw Ruby+Psych
+# backtrace (CFG-1) — ConfigGuard turns it into a clean boot abort so every
+# command (including `rubino doctor`) reports it gracefully.
+# Pass ARGV so the config-issue warning is suppressed for the pure-meta
+# commands (version/help) that never need a configured model.
+Rubino::Boot::ConfigGuard.load!(argv: ARGV)
 
 Rubino::CLI::Commands.start(ARGV)