rubino-agent 0.3.0 → 0.5.0

data/lib/rubino/agent/tool_executor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Rubino
   module Agent
     # Executes tool calls with approval checks and result formatting.
@@ -9,16 +11,29 @@ module Rubino
       # Loop#handle_tool_result.
       attr_writer :on_result
 
+      # True once any tool was BLOCKED for approval in a non-interactive session
+      # (#260): a write/edit/shell that needed a prompt no one could answer. The
+      # one-shot CLI reads this after the run to exit NON-ZERO so CI/automation
+      # fails loudly instead of treating a silently-skipped action as success.
+      def blocked_for_approval?
+        @blocked_for_approval == true
+      end
+
       def initialize(registry:, approval_policy:, ui:, config:,
                      tool_call_repository: Tools::ToolCallRepository.new,
                      cancel_token: nil, read_tracker: nil, event_bus: nil,
-                     on_result: nil)
+                     on_result: nil, session_id: nil)
         @registry             = registry
         @approval_policy      = approval_policy
         @ui                   = ui
         @config               = config
         @tool_call_repository = tool_call_repository
         @cancel_token         = cancel_token
+        # Session the audit row is attributed to. The tool_calls table requires
+        # a non-null session_id FK, so without this every audit insert violated
+        # the constraint and was swallowed by the repository's rescue — leaving
+        # the table empty on every execution, streaming or not (#262).
+        @session_id           = session_id
         # Optional sink the Loop registers so a tool that runs on the STREAMING
         # path (ruby_llm dispatches it mid-stream via ToolBridge → straight into
         # #execute, never returning through Loop#execute_tool_calls) is still
@@ -44,6 +59,17 @@ module Rubino
 
       # Executes a single tool call, returns a Tools::Result.
       def execute(name:, arguments:, call_id:)
+        # Cancellation checkpoint BEFORE the tool runs (#335b). On the streaming
+        # path ruby_llm dispatches tool calls mid-stream through ToolBridge into
+        # here, and the loop's per-iteration #check! is far above us — so without
+        # this a cancel that arrived while a PREVIOUS tool was running (or during
+        # the thinking phase) wouldn't be observed until the model resumed
+        # streaming, letting the next tool fire after the user already hit
+        # interrupt. Raising here halts the in-flight turn at the next tool
+        # boundary, the soonest safe checkpoint, so "esc to interrupt" actually
+        # stops the agent instead of letting it run one more tool.
+        @cancel_token&.check!
+
         tool = @registry.find(name)
         raise ToolError, "Unknown tool: #{name}" unless tool
 
@@ -58,6 +84,29 @@ module Rubino
                         result: denied, reason: "policy-denied")
           return finish(name, arguments, call_id, denied)
         when :ask
+          # Headless FAIL-CLOSED floor (#260). A tool the policy wants to ASK
+          # about — a write/edit, or a shell command not covered by the
+          # permissions allowlist / read-only auto-allow — cannot be approved
+          # when there is no interactive session (one-shot `rubino prompt`/`-q`,
+          # a pipe, a gate-less embed). Auto-running it (the old UI::Null#confirm
+          # → true bug) is the prompt-injection→RCE foot-gun; hanging on a prompt
+          # no one can answer is the opencode bug. So DENY with a clear,
+          # single-line block message and record the block so the run can exit
+          # non-zero. Anything the user already allowlisted resolved to :allow
+          # before reaching here, so this never regresses a configured command.
+          unless @ui.interactive?
+            @blocked_for_approval = true
+            message = approval_block_message(tool, arguments)
+            @ui.warning(message) if @ui.respond_to?(:warning)
+            # Let the headless adapter latch the block so the one-shot CLI can
+            # exit non-zero (#260) without threading a flag up through the loop.
+            @ui.tool_blocked(message) if @ui.respond_to?(:tool_blocked)
+            blocked = Tools::Result.denied(name: name, call_id: call_id, reason: :noninteractive)
+            record_denied(name: name, call_id: call_id, arguments: arguments,
+                          result: blocked, reason: "noninteractive-blocked")
+            return finish(name, arguments, call_id, blocked)
+          end
+
           unless request_approval(tool, arguments)
             denied = Tools::Result.denied(name: name, call_id: call_id, reason: :user)
             record_denied(name: name, call_id: call_id, arguments: arguments,
@@ -66,6 +115,18 @@ module Rubino
           end
         end
 
+        # Warn-not-block doom-loop guard (#414): when the detector tripped but
+        # hard_stop is off (the default), the call is ALLOWED — surface a
+        # one-time warning so a stuck autopilot is visible without hard-denying a
+        # legitimate repeated/idempotent call.
+        if @approval_policy.respond_to?(:doom_loop_warning) &&
+           @approval_policy.doom_loop_warning && @ui.respond_to?(:warning)
+          @ui.warning(
+            "doom-loop guard: '#{name}' called with identical arguments repeatedly — " \
+            "proceeding (set doom_loop.hard_stop:true to block)"
+          )
+        end
+
         notify_yolo_if_applicable(tool, arguments)
         emit_started(name, arguments)
         started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -105,7 +166,11 @@ module Rubino
         if tool.respond_to?(:stream_chunk=) && (@ui.respond_to?(:tool_chunk) || @event_bus)
           tool.stream_chunk = lambda do |chunk|
             streamed = true
-            @ui.tool_chunk(name, chunk) if @ui.respond_to?(:tool_chunk)
+            # Read stream_kind LAZILY: the tool only knows its output kind
+            # (e.g. :diff for `git diff`) once #call has inspected the command,
+            # which happens AFTER this lambda is installed.
+            kind = tool.respond_to?(:stream_kind) ? (tool.stream_kind || :plain) : :plain
+            @ui.tool_chunk(name, chunk, kind: kind) if @ui.respond_to?(:tool_chunk)
             # Mirror the chunk onto the bus so the API/SSE stream isn't silent
             # during a long tool call: the Recorder maps TOOL_PROGRESS to a
             # `tool.progress` event, which resets the idle watchdog. Without
@@ -155,13 +220,13 @@ module Rubino
           error_code: error_code&.to_sym,
           artifact: artifact
         )
-        @tool_call_repository.record(name: name, call_id: call_id, arguments: arguments,
-                                     result: result, status: "completed")
+        record_audit(name: name, call_id: call_id, arguments: arguments,
+                     result: result, status: "completed")
         result
       rescue StandardError => e
         result = Tools::Result.error(name: name, call_id: call_id, error: e.message)
-        @tool_call_repository.record(name: name, call_id: call_id, arguments: arguments,
-                                     result: result, status: "failed", error: e.message)
+        record_audit(name: name, call_id: call_id, arguments: arguments,
+                     result: result, status: "failed", error: e.message)
         result
       ensure
         tool.cancel_token = nil if tool.respond_to?(:cancel_token=)
@@ -243,9 +308,12 @@ module Rubino
           masked = Util::SecretsMask.mask_value(value, key: key)
           memo[key.to_s] = truncate_for_event(masked.to_s)
         end
-      rescue StandardError
+      rescue StandardError => e
         # Never block the run because of a serialisation hiccup — drop the
-        # arguments rather than crash the tool emission path.
+        # arguments rather than crash the tool emission path. Log it so a coding
+        # bug here doesn't silently blank every tool event's arguments.
+        Rubino.logger&.warn(event: "tool_executor.sanitize_arguments_failed",
+                            error: e.message, error_class: e.class.name)
         nil
       end
 
@@ -265,7 +333,7 @@ module Rubino
       end
 
       def record_denied(name:, call_id:, arguments:, result:, reason:)
-        @tool_call_repository.record(
+        record_audit(
           name: name,
           call_id: call_id,
           arguments: arguments,
@@ -273,8 +341,21 @@ module Rubino
           status: "denied",
           error: reason
         )
-      rescue StandardError
-        # Don't fail the user's request just because the audit write failed.
+      rescue StandardError => e
+        # Don't fail the user's request just because the audit write failed —
+        # but log it, so a silently dropped denial-audit row is traceable.
+        Rubino.logger&.warn(event: "tool_executor.record_denied_failed",
+                            error: e.message, error_class: e.class.name)
+      end
+
+      # Stamps the executor's session id onto the Result (built deep in the tool
+      # pipeline with no session context) before the audit write, so the
+      # NOT-NULL session_id FK on tool_calls is satisfied (#262). Single
+      # chokepoint for every record call — success, failure, and denial.
+      def record_audit(name:, call_id:, arguments:, result:, status:, error: nil)
+        result.session_id = @session_id if result.respond_to?(:session_id=)
+        @tool_call_repository.record(name: name, call_id: call_id, arguments: arguments,
+                                     result: result, status: status, error: error)
       end
 
       # The reason behind the policy's :deny, when the policy exposes one
@@ -285,6 +366,19 @@ module Rubino
         @approval_policy.last_deny_reason || :policy
       end
 
+      # The single-line "blocked" notice surfaced to stderr (via @ui.warning)
+      # when a tool needs approval but there is no interactive session (#260).
+      # Names the tool and the actionable escape hatches so a scripted run shows
+      # WHY nothing happened instead of failing silently.
+      def approval_block_message(tool, arguments)
+        cmd = Security::ApprovalPolicy.command_string(tool, arguments).to_s
+        cmd = cmd.lines.first.to_s.rstrip
+        cmd = "#{cmd[0, 57]}…" if cmd.length > 60
+        suffix = cmd.empty? ? "" : " (#{cmd})"
+        "blocked: #{tool.name}#{suffix} needs approval but no interactive session " \
+          "(use --yolo to allow, or allowlist it)"
+      end
+
       def request_approval(tool, arguments)
         command = Security::ApprovalPolicy.command_string(tool, arguments)
         _hit, pattern_key, description = Security::DangerousPatterns.detect(command)
@@ -347,13 +441,21 @@ module Rubino
         # header followed by nothing reads as a truncated/broken card (#109).
         return "#{tool.name} wants to run" if pairs.empty?
 
+        # multi_edit carries an `edits` ARRAY whose generic .to_s render is an
+        # unreadable escaped Ruby hash (literal \n, truncated). Lay it out as
+        # clean per-edit `- old` / `+ new` blocks, matching how the single
+        # `edit` tool already previews — so the user can see what will change.
+        if (edits_preview = multi_edit_preview(tool, arguments))
+          return edits_preview
+        end
+
         # The common case — ONE short single-line argument (a shell command, a
-        # file path) — inlines onto the header: `shell wants:  touch hello.txt`
+        # file path) — inlines onto the header: `shell wants: touch hello.txt`
         # (P7). Multi-arg / multi-line calls keep the per-key layout below.
         if pairs.size == 1
           key, value = pairs.first
           text = Util::SecretsMask.mask_value(value, key: key).to_s
-          return "#{tool.name} wants:  #{text}" if !text.include?("\n") && text.length <= 120
+          return "#{tool.name} wants: #{text}" if !text.include?("\n") && text.length <= 120
         end
 
         lines = ["#{tool.name} wants:"]
@@ -378,6 +480,42 @@ module Rubino
         end
       end
 
+      # Clean per-edit preview for multi_edit: a header with the file path then,
+      # for each edit, its `- old` / `+ new` lines (edits blank-line separated),
+      # trimmed to a sane line budget. nil for any other tool / shape so the
+      # generic per-key formatter handles it. Mirrors EditTool's diff preview.
+      MULTI_EDIT_PREVIEW_LINES = 16
+      def multi_edit_preview(tool, arguments)
+        return nil unless tool.name == "multi_edit"
+
+        edits = arguments["edits"] || arguments[:edits]
+        return nil unless edits.is_a?(Array) && !edits.empty?
+
+        path  = arguments["file_path"] || arguments[:file_path]
+        lines = ["multi_edit wants: #{path} (#{edits.size} edit#{"s" if edits.size != 1})"]
+        body  = []
+        edits.each_with_index do |edit, idx|
+          old_s = edit["old_string"] || edit[:old_string]
+          new_s = edit["new_string"] || edit[:new_string]
+          body << "" unless idx.zero?
+          body.concat(Util::SecretsMask.mask_value(old_s, key: "old_string").to_s.lines.map { |l| "  - #{l.chomp}" })
+          body.concat(Util::SecretsMask.mask_value(new_s, key: "new_string").to_s.lines.map { |l| "  + #{l.chomp}" })
+        end
+        if body.size > MULTI_EDIT_PREVIEW_LINES
+          dropped = body.size - MULTI_EDIT_PREVIEW_LINES
+          body    = body.first(MULTI_EDIT_PREVIEW_LINES)
+          body << "  [… #{dropped} more line(s)]"
+        end
+        (lines + body).join("\n")
+      rescue StandardError => e
+        # A preview is cosmetic — fall back to the generic per-key formatter
+        # rather than crash the approval prompt. Log it so a malformed-shape
+        # coding bug here doesn't silently disable the multi_edit diff preview.
+        Rubino.logger&.warn(event: "tool_executor.multi_edit_preview_failed",
+                            error: e.message, error_class: e.class.name)
+        nil
+      end
+
       # Persists the complete (pre-truncation) output to a per-call file under
       # the rubino home so the model can read back whatever the inline
       # head+tail elided (the spill seam Util::Output.truncate calls back into
@@ -391,7 +529,21 @@ module Rubino
         dir = File.join(Rubino.home_path, "tool-results")
         FileUtils.mkdir_p(dir)
         path = File.join(dir, "#{id}.txt")
-        File.write(path, text)
+        # Write ATOMICALLY (temp + rename): a plain File.write can be cut MID-
+        # WRITE by an Interrupt (Ctrl+C) — which is NOT a StandardError, so the
+        # rescue below never catches it — leaving a TRUNCATED recovery file the
+        # marker still points the model at, so it reads back a silently partial
+        # output. rename(2) on the same filesystem is atomic, so a reader sees
+        # either the old file or the complete new one, never a torn one; the temp
+        # is cleaned up if the interrupt lands before the rename.
+        tmp = "#{path}.#{Process.pid}.#{SecureRandom.hex(4)}.tmp"
+        begin
+          File.write(tmp, text)
+          File.rename(tmp, path)
+        rescue Exception # rubocop:disable Lint/RescueException
+          FileUtils.rm_f(tmp)
+          raise
+        end
         path
       rescue StandardError => e
         Rubino.logger&.warn(event: "tool_output.spill_failed", error: e.message)

data/lib/rubino/agent/truncation_continuation.rb

@@ -103,7 +103,10 @@ module Rubino
           thinking: request.thinking,
           prefill: request.prefill,
           image_paths: request.image_paths,
-          stream: request.stream?
+          stream: request.stream?,
+          on_intermediate_message: request.on_intermediate_message,
+          on_round_trip: request.on_round_trip,
+          budget_exhausted: request.budget_exhausted
         )
       end
 

data/lib/rubino/api/server.rb

@@ -2,6 +2,7 @@
 
 require "rack"
 require "uri"
+require "json"
 require "puma"
 require "puma/configuration"
 require "puma/launcher"
@@ -62,10 +63,28 @@ module Rubino
           c.bind(bind_url)
           c.app(app)
           c.quiet
+          # Errors raised below the Rack stack (e.g. Puma's HTTP parser rejecting
+          # an oversized QUERY_STRING) bypass ErrorHandler and would otherwise
+          # render Puma's verbose default page — leaking the Puma version and
+          # gem file paths/line numbers (S5-1). Render the same clean envelope
+          # with no internals instead.
+          c.lowlevel_error_handler(Server.lowlevel_error_handler)
         end
         Puma::Launcher.new(config).run
       end
 
+      # A Puma lowlevel_error_handler that mirrors ErrorHandler's
+      # {error:{code,message}} JSON envelope and never exposes the exception
+      # class, message, backtrace, Puma version, or file paths.
+      #
+      # @return [Proc] callable Puma invokes as (error, env=nil, status=nil)
+      def self.lowlevel_error_handler
+        lambda do |_error, _env = nil, _status = nil|
+          body = JSON.generate(error: { code: "bad_request", message: "bad request" })
+          [400, { "content-type" => "application/json" }, [body]]
+        end
+      end
+
       # Composes the Rack middleware stack around the router. Order matters:
       # Observability is outermost (sees every status, including 500s from
       # ErrorHandler), then ErrorHandler, then RateLimit (so /v1/health and

data/lib/rubino/attachments/classify.rb

@@ -35,19 +35,35 @@ module Rubino
       ].freeze
       IMAGE_EXTS = %w[.png .jpg .jpeg .gif .webp .bmp .tiff .tif].freeze
 
-      # Leading magic bytes per recognised image MIME (WebP is special-cased:
-      # RIFF container + WEBP tag). Marcel lets the file NAME break the tie
-      # when the content sniff only yields a generic type (text/plain,
-      # octet-stream), so a text file renamed fake.png came back image/png and
-      # was shipped to the provider (#158). An image verdict must therefore be
-      # backed by the actual signature.
-      IMAGE_SIGNATURES = {
+      # Leading magic bytes per recognised image/document MIME (WebP is
+      # special-cased: RIFF container + WEBP tag). Marcel lets the file NAME
+      # break the tie when the content sniff only yields a generic type
+      # (text/plain, octet-stream), so a text file renamed fake.png came back
+      # image/png and was shipped to the provider (#158) — and a text file
+      # renamed report.docx came back as :document and got a shell-hint
+      # instead of reading inline (#239). An image or document verdict must
+      # therefore be backed by the actual signature.
+      OLE2 = "\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1".b
+      SIGNATURES = {
         "image/png" => ["\x89PNG\r\n\x1a\n".b],
         "image/jpeg" => ["\xFF\xD8\xFF".b],
         "image/gif" => ["GIF87a".b, "GIF89a".b],
         "image/bmp" => ["BM".b],
         "image/x-ms-bmp" => ["BM".b],
-        "image/tiff" => ["II*\x00".b, "MM\x00*".b]
+        "image/tiff" => ["II*\x00".b, "MM\x00*".b],
+        "application/pdf" => ["%PDF".b],
+        # OOXML and ODF are ZIP containers.
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document" => ["PK".b],
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" => ["PK".b],
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation" => ["PK".b],
+        "application/vnd.oasis.opendocument.text" => ["PK".b],
+        "application/vnd.oasis.opendocument.spreadsheet" => ["PK".b],
+        # Legacy Office is an OLE2 compound file.
+        "application/msword" => [OLE2],
+        "application/vnd.ms-excel" => [OLE2],
+        "application/vnd.ms-powerpoint" => [OLE2],
+        "application/rtf" => ["{\\rtf".b],
+        "text/rtf" => ["{\\rtf".b]
       }.freeze
 
       module_function
@@ -97,12 +113,14 @@ module Rubino
         basename = File.basename(real)
         mime = Marcel::MimeType.for(Pathname(real), name: basename).to_s
 
-        # Extension-spoof gate (#158): an image verdict that the magic bytes
-        # don't back up came from the extension, not the content. Re-resolve
-        # from content alone (no name:); when that is generic too, the text/
-        # binary sniff names the honest type — so fake.png full of text is
-        # rejected at the staging gate as text/plain, before any network call.
-        if IMAGE_MIMES.include?(mime) && !image_signature?(real, mime)
+        # Extension-spoof gate (#158, #239): an image or document verdict that
+        # the magic bytes don't back up came from the extension, not the
+        # content. Re-resolve from content alone (no name:); when that is
+        # generic too, the text/binary sniff names the honest type — so
+        # fake.png full of text is rejected at the staging gate as text/plain
+        # before any network call, and report.docx full of text reads inline
+        # as text instead of bouncing off the document converter.
+        if (IMAGE_MIMES.include?(mime) || DOCUMENT_MIMES.include?(mime)) && !signature?(real, mime)
           mime = Marcel::MimeType.for(Pathname(real)).to_s
           if mime.empty? || mime == "application/octet-stream"
             return base_helper.send(:binary?, real) ? [:binary, "application/octet-stream"] : [:text, "text/plain"]
@@ -136,12 +154,12 @@ module Rubino
       end
 
       # True when the file's leading bytes carry the signature +mime+ claims.
-      # Unknown image MIMEs fail closed (no signature -> not verified).
-      def image_signature?(real, mime)
+      # MIMEs without a known signature fail closed (not verified).
+      def signature?(real, mime)
         head = File.binread(real, 16).to_s.b
         return head.start_with?("RIFF") && head[8, 4] == "WEBP" if mime == "image/webp"
 
-        Array(IMAGE_SIGNATURES[mime]).any? { |sig| head.start_with?(sig) }
+        Array(SIGNATURES[mime]).any? { |sig| head.start_with?(sig) }
       end
 
       # JSON/XML/YAML/JS and friends arrive as application/* but are text.

data/lib/rubino/boot/config_guard.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Boot
+    # Loads configuration at process startup, turning a malformed/corrupt
+    # config.yml into a clean, actionable boot abort instead of a raw Ruby +
+    # Psych double backtrace (CFG-1).
+    #
+    # The entrypoint (`exe/rubino`) calls {Config::Loader#load} for EVERY
+    # command, before Thor dispatch. Any {Config::ConfigError} (or a
+    # {Psych::SyntaxError} that escapes the loader) used to propagate all the
+    # way out of `exe/rubino:16`, so a single typo in config.yml killed the
+    # process with a stack trace — even `rubino doctor`, whose graceful
+    # corruption handler (#259) was never reached because boot died first.
+    #
+    # {.load!} runs the load behind a rescue that writes a single-line
+    # diagnostic (what's wrong + the config path + how to fix it) to $stderr
+    # and exits non-zero — boot abort, not exception, mirroring
+    # {EncryptionKey.validate!}. doctor's own handling still works: doctor
+    # re-loads via the Loader and reports corruption itself, so a clean boot
+    # here does not mask it.
+    module ConfigGuard
+      # The Loader normalizes every malformed config shape into a
+      # {Config::ConfigError} at the source. The remaining classes here are a
+      # defensive backstop: should any raw Psych/IO failure ever slip past the
+      # loader (a new shape, a refactor), it still becomes a clean boot abort
+      # rather than a double backtrace on every command (CFG-R2).
+      def self.load!(loader: Config::Loader.new, stderr: $stderr, argv: [])
+        loader.load
+        # LOAD-time schema validation (F8): a HAND-EDITED config.yml with an
+        # unknown key or a wrong-typed value used to load SILENTLY (the validator
+        # only ran at `config set` time) and only blow up later. Surface those as
+        # a clear, NON-FATAL warning here — the boot chokepoint every command
+        # already passes through — so the user is told at startup instead of
+        # discovering it as a runtime crash / provider 4xx. Never fatal: a
+        # warning must not block a usable config, and a probe hiccup is ignored.
+        # Pure-meta commands (version/help) never need a configured model, so the
+        # config-issue warning is noise on `rubino --version`/`--help` — skip it.
+        warn_config_issues(loader, stderr) unless meta_command?(argv)
+        nil
+      rescue Config::ConfigError, Psych::Exception, SystemCallError, IOError => e
+        stderr.puts "rubino: config error — #{e.message}"
+        stderr.puts "rubino: fix #{loader.config_path}, restore a backup, or re-run 'rubino setup'."
+        exit 1
+      end
+
+      # `--version`/`-v`/`version` and `--help`/`-h`/`help` are pure-meta: they
+      # print static text and exit, so a config-issue warning on them is pure
+      # noise. True when the invocation is one of those (the meta flag/word is the
+      # FIRST token, matching how Commands.start dispatches them).
+      def self.meta_command?(argv)
+        first = Array(argv).first.to_s
+        %w[--version -v version --help -h help].include?(first)
+      end
+
+      # Emits a one-line-per-issue config WARNING to stderr (F8), or nothing when
+      # the config is clean. Best-effort — any failure here is swallowed so a
+      # validation hiccup can never break boot.
+      def self.warn_config_issues(loader, stderr)
+        issues = Config::Validator.warnings(loader.raw_config)
+        return if issues.empty?
+
+        stderr.puts "rubino: warning: #{loader.config_path} has #{issues.size} " \
+                    "config issue#{"s" if issues.size != 1} (run `rubino doctor` for details):"
+        issues.first(5).each { |msg| stderr.puts "rubino:   - #{msg}" }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rubino/cli/chat/completion_builder.rb

@@ -52,7 +52,7 @@ module Rubino
           rescue StandardError
             []
           end
-          names  = (::Rubino::Commands::BuiltIns::NAMES + custom).uniq
+          names  = (::Rubino::Commands::BuiltIns::NAMES + agent_command_names + custom).uniq
           files  = -> { Rubino::Workspace.primary_root }
           # ARGUMENT sources: the dropdown completes the argument of these commands
           # the same way it completes `/command` and `@file`.
@@ -79,10 +79,22 @@ module Rubino
           #     verbs + the known config keys flattened from the defaults tree.
           #   * /skills — the `✗ none` clear entry + the enable/disable verbs +
           #     the skill names (#188); after a toggle verb, the names again.
-          arg_sources = {
+          Rubino::UI::CompletionSource.new(commands: names, files: files,
+                                           arg_sources: arg_sources,
+                                           descriptions: completion_descriptions)
+        end
+
+        private
+
+        # The per-command ARGUMENT completion sources (#39): the dropdown
+        # completes the argument of these commands the same way it completes
+        # `/command` and `@file`. See the per-entry notes inline.
+        def arg_sources
+          {
             "skills" => ->(args) { skills_arg_candidates(args) },
             "agents" => ->(args) { agents_arg_candidates(args) },
             "tasks" => ->(args) { agents_arg_candidates(args) },
+            "agent" => ->(args) { args.empty? ? primary_agent_names : [] },
             "reply" => ->(args) { args.empty? ? blocked_subagent_ids : [] },
             "mcp" => ->(args) { mcp_arg_candidates(args) },
             "mode" => ->(args) { args.empty? ? Rubino::Modes::ALL.map(&:to_s) : [] },
@@ -97,12 +109,35 @@ module Rubino
             "jobs" => ->(args) { args.empty? ? recent_job_ids : [] },
             "config" => ->(args) { config_arg_candidates(args) }
           }
-          Rubino::UI::CompletionSource.new(commands: names, files: files,
-                                           arg_sources: arg_sources,
-                                           descriptions: completion_descriptions)
         end
 
-        private
+        # Agent slash commands (#320): every visible agent is reachable as a
+        # `/<name>` (a bare `/<primary>` switches, `/<name> <msg>` routes one
+        # turn). Surfaced in the dropdown alongside the built-ins so they're
+        # discoverable; resolved lazily so a freshly registered agent appears.
+        def agent_command_names
+          ::Rubino.agent_registry.all.reject(&:hidden?).map { |a| "/#{a.name}" }
+        rescue StandardError
+          []
+        end
+
+        # The switchable primary-agent names, for the `/agent <name>` argument.
+        def primary_agent_names
+          ::Rubino.agent_registry.primary_agents.map(&:name)
+        rescue StandardError
+          []
+        end
+
+        # Describe each `/<name>` agent command so the dropdown explains what
+        # switching/routing to it does — primaries switch, subagents run one-shot.
+        def merge_agent_descriptions!(descriptions)
+          ::Rubino.agent_registry.all.reject(&:hidden?).each do |a|
+            verb = a.primary? ? "switch to" : "run one turn as"
+            descriptions["/#{a.name}"] = "#{verb} the #{a.name} agent — #{a.description}"
+          end
+        rescue StandardError
+          nil
+        end
 
         # Argument candidates per /agents position: ids → subcommands → nothing.
         def agents_arg_candidates(args)
@@ -247,6 +282,7 @@ module Rubino
           rescue StandardError
             nil
           end
+          merge_agent_descriptions!(descriptions)
           descriptions.merge(
             "steer" => "park a note the subagent folds in at its next turn",
             "probe" => "ask the subagent an ephemeral question (not saved)",

data/lib/rubino/cli/chat/idle_card_host.rb

@@ -53,7 +53,13 @@ module Rubino
               paint
               break unless children_live?
             end
-          rescue StandardError
+          rescue StandardError => e
+            # The ticker exits on any error so a hiccup never crashes the REPL,
+            # but a swallowed coding bug would silently kill the live-card refresh
+            # for the rest of the session with no trace. Log it once (this rescue
+            # only ever fires once per ticker — the loop is already dead here).
+            Rubino.logger.warn(event: "cli.idle_card_ticker.crashed",
+                               error: e.message, error_class: e.class.name)
             nil
           end
         end