rubino-agent 0.3.0

data/lib/rubino/agent/router.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Routes user input to the appropriate agent.
+    # Handles @mention syntax for subagent invocation and agent switching.
+    class Router
+      MENTION_REGEX = /\A@(\w+)\s+(.+)/m
+
+      def initialize(registry:, ui:)
+        @registry = registry
+        @ui = ui
+        @current_agent = registry.default
+      end
+
+      attr_reader :current_agent
+
+      # Switches to a different primary agent
+      def switch_to(agent_name)
+        agent = @registry.find(agent_name)
+        unless agent
+          @ui.error("unknown agent: #{agent_name}")
+          return false
+        end
+
+        unless agent.primary?
+          @ui.error("cannot switch to subagent '#{agent_name}'. Use @#{agent_name} to invoke it.")
+          return false
+        end
+
+        @current_agent = agent
+        @ui.info("Switched to agent: #{agent.name}")
+        true
+      end
+
+      # Routes input, returning [agent_definition, cleaned_input]
+      def route(input)
+        # Check for @mention
+        if input.match?(MENTION_REGEX)
+          match = input.match(MENTION_REGEX)
+          agent_name = match[1]
+          actual_input = match[2]
+
+          agent = @registry.find(agent_name)
+          return [agent, actual_input] if agent && (agent.subagent? || agent.primary?)
+
+          @ui.warning("Unknown agent '#{agent_name}', using current agent")
+
+        end
+
+        [@current_agent, input]
+      end
+
+      # Returns available agent names for autocomplete
+      def available_mentions
+        @registry.subagents.map { |a| "@#{a.name}" }
+      end
+
+      # Returns primary agent names for switching
+      def switchable_agents
+        @registry.primary_agents.map(&:name)
+      end
+    end
+  end
+end

data/lib/rubino/agent/runner.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Top-level orchestrator for a single user interaction.
+    # Coordinates session management, the agent loop, and post-turn jobs.
+    class Runner
+      attr_reader :session
+
+      # The resolved model id this runner runs against. Read by SubagentProbe so an
+      # ephemeral peek uses the child's OWN model, not the global default.
+      attr_reader :model_id
+
+      def initialize(session_id: nil, model_override: nil, provider_override: nil,
+                     max_turns: nil, ignore_rules: false, ui: nil, agent_definition: nil,
+                     event_bus: nil, announce_session: true)
+        @ui = ui || Rubino.ui
+        # An in-chat rewind/fork builds a runner on the child session but has its
+        # own purpose-built "┄ rewound to message N — editing ┄" marker, so the
+        # generic "Resuming session: <id>…" plumbing line must not also leak into
+        # the transcript (#220). Off-rewind callers keep the announcement.
+        @announce_session = announce_session
+        # Defaults to the process-global bus for the single-run CLI path; the
+        # HTTP Executor injects a fresh per-run bus so concurrent runs don't
+        # cross-contaminate each other's events/output (architecture audit A1).
+        @event_bus = event_bus || Rubino.event_bus
+        @config = Rubino.configuration
+        @session_repo = Session::Repository.new
+        @message_store = Session::Store.new
+        @explicit_model_override = model_override
+        @model_id = model_override || @config.model_default
+        @provider_override = provider_override
+        @max_turns = max_turns
+        @ignore_rules = ignore_rules
+        @agent_definition = agent_definition
+        # Pre-instantiate so cancel! is meaningful between turns and during the
+        # window between Signal.trap install and run() — a too-early Ctrl+C
+        # used to land on a nil token and silently no-op, then the next run
+        # started fresh and the user's cancel was lost.
+        @cancel_token = Interaction::CancelToken.new
+        @session = load_or_create_session(session_id)
+      end
+
+      # Executes a full interaction turn, swallowing failures so CLI callers
+      # can stay in the REPL after a model/tool error. The friendly UI
+      # message is emitted, but the bus event INTERACTION_FAILED is NOT
+      # re-emitted here — Interaction::Lifecycle is the single source of
+      # truth for that, and it already emitted before re-raising. Use
+      # +run!+ from non-CLI callers (HTTP executor) that need the
+      # exception to propagate so the run row can be marked failed.
+      def run(input, image_paths: [], input_queue: nil, paste_expansions: [])
+        run!(input, image_paths: image_paths, input_queue: input_queue,
+                    paste_expansions: paste_expansions)
+      rescue Interrupted
+        # Standardized single interrupt notice: a dim `⎿ interrupted` marker
+        # right after the partial answer the Loop already committed via
+        # #stream_end. Replaces the old "⚠ interrupted by user" warning so the
+        # Ctrl+C path and the interrupt-by-default type-ahead path read the same.
+        @ui.turn_interrupted
+        nil
+      rescue SystemExit, Interrupt, SignalException
+        raise
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        @ui.error(friendly_error_message(e))
+        nil
+      end
+
+      # Like +run+ but propagates exceptions to the caller. The HTTP
+      # Executor uses this so it can transition the run row to "failed"
+      # (instead of mark_completed!) when the lifecycle raises. The
+      # ScriptError / Exception net is kept here too so the Executor sees
+      # LoadError etc. as a real failure rather than nil-and-completed.
+      def run!(input, image_paths: [], input_queue: nil, paste_expansions: [])
+        # Each turn gets a fresh token. A CancelToken is one-shot, so reusing a
+        # cancelled one would poison every subsequent turn (it would raise
+        # Interrupted immediately at the first poll point). The per-turn SIGINT
+        # trap (CLI) / stop-watcher (HTTP) is wired to #cancel! against this new
+        # token before any LLM/tool work runs, so an in-flight interrupt still
+        # cancels the current turn.
+        @cancel_token = Interaction::CancelToken.new
+
+        lifecycle = Interaction::Lifecycle.new(
+          session: @session,
+          event_bus: @event_bus,
+          ui: @ui,
+          config: @config,
+          ignore_rules: @ignore_rules,
+          agent_definition: @agent_definition,
+          cancel_token: @cancel_token,
+          model_override: @explicit_model_override,
+          provider_override: @provider_override,
+          max_tool_iterations: @max_turns
+        )
+
+        lifecycle.execute(input, image_paths: image_paths, input_queue: input_queue,
+                                 paste_expansions: paste_expansions)
+      end
+
+      # Flips the current turn's cancel token. Called from the UI thread when
+      # the user hits Esc or a second Ctrl+C while the worker is mid-stream.
+      # No-op when no turn is in flight.
+      def cancel!
+        @cancel_token&.cancel!
+      end
+
+      # Switches the LIVE model for this runner (the in-chat `/model <name>`).
+      # Lifecycle builds the adapter per turn from
+      # `@explicit_model_override || @session[:model]`, and the CLI always
+      # passes a model_override at boot — so both fields must move for the
+      # NEXT turn to actually hit the new model. The session hash is mutated
+      # in place (statusbar and /status read it) and the persisted row is
+      # updated so resume/--continue agree; an unpersisted lazy session gets
+      # the new value via Repository#persist! on its first message instead.
+      def switch_model!(model_id)
+        @explicit_model_override = model_id
+        @model_id = model_id
+        @session[:model] = model_id
+        @session[:provider] = @provider_override ||
+                              LLM::ProviderResolver.resolve(model_id, explicit_provider: @config.model_provider)
+        if @session_repo.persisted?(@session[:id])
+          @session_repo.update(@session[:id], model: model_id, provider: @session[:provider])
+        end
+        model_id
+      end
+
+      # Marks the current session ended (#100). Called from the CLI on a clean
+      # REPL teardown (and best-effort on terminal close) so a session stops
+      # showing as "active" forever and cleanup/list/--continue can tell a
+      # finished session from a live one. Best-effort: a failure here must never
+      # crash the exit path.
+      def end_session!
+        # Nothing to end for a session that was never persisted (the user opened
+        # chat and left without sending a message, #144) — there's no row.
+        return if @session.nil? || (@session[:persisted] == false && !@session_repo.persisted?(@session[:id]))
+
+        @session_repo.end_session!(@session[:id])
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      # Translates upstream errors into actionable messages instead of
+      # bare stack-trace fragments. (issue #16)
+      def friendly_error_message(error)
+        msg = error.message.to_s
+        case msg
+        when /\b401\b|unauthorized|invalid[_ ]?api[_ ]?key/i
+          "authentication failed (#{msg}). Check your API key in ~/.rubino/.env " \
+          "or run `rubino setup`."
+        when /\b404\b|model.*not.*found|invalid[_ ]?model|unknown[_ ]?model/i
+          "model '#{@model_id}' not available with the current provider/plan. " \
+          "Check `model.default` in config.yml; details: #{msg}"
+        when /\b(429|rate[_ ]?limit)\b/i
+          "rate-limited by the provider. Wait a moment and retry. Details: #{msg}"
+        when /\b(timeout|timed out|connection reset)\b/i
+          "network error reaching the LLM (#{msg}). Check connectivity and retry."
+        else
+          "error: #{msg}"
+        end
+      end
+
+      def load_or_create_session(session_id)
+        if session_id
+          # Support resume by title/first-prompt substring as well as ID
+          session = @session_repo.find_by_id_or_title(session_id)
+          unless session
+            raise SessionError,
+                  "Session not found: #{session_id}. " \
+                  "Try `rubino sessions list`, or resume by id prefix."
+          end
+
+          # An existing row is already in the DB; mark it so the lazy-persist
+          # path (#144) treats it as persisted and never re-inserts.
+          session[:persisted] = true
+          @ui.status("Resuming session: #{session[:id][0..7]}...") if @announce_session
+          session
+        else
+          # Build an UNSAVED session: no row is written until the first user
+          # message is committed (#144), so opening `chat` and leaving without
+          # typing anything never pollutes `/sessions` with empty rows. The
+          # record carries a real id so the whole turn pipeline works unchanged;
+          # Lifecycle#persist_user_message flips it to a real row on demand.
+          session = @session_repo.build(
+            source: "cli",
+            model: @model_id,
+            provider: @provider_override || LLM::ProviderResolver.resolve(@model_id)
+          )
+          @ui.status("New session: #{session[:id][0..7]}")
+          session
+        end
+      end
+    end
+  end
+end

data/lib/rubino/agent/tool_executor.rb

@@ -0,0 +1,402 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Executes tool calls with approval checks and result formatting.
+    class ToolExecutor
+      # The Loop registers its count+persist sink here after construction (the
+      # executor is built first so the adapter/ToolBridge can share it). See
+      # Loop#handle_tool_result.
+      attr_writer :on_result
+
+      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)
+        @registry             = registry
+        @approval_policy      = approval_policy
+        @ui                   = ui
+        @config               = config
+        @tool_call_repository = tool_call_repository
+        @cancel_token         = cancel_token
+        # 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
+        # counted in the turn summary and persisted as a `tool` message. Called
+        # once per completed/denied tool with (name:, arguments:, call_id:,
+        # result:). The non-streaming path routes through the same sink so the
+        # count/persist happens in exactly one place regardless of mode.
+        @on_result            = on_result
+        # Optional event bus so this executor emits TOOL_STARTED/TOOL_FINISHED
+        # for the API mode timeline. ToolBridge already emits these when no
+        # executor is wired (test/one-shot path); the production path went
+        # through here and dropped them, so the web UI timeline never saw
+        # the tool call as a discrete event.
+        @event_bus            = event_bus
+        # One tracker shared across every tool call so the read registered by
+        # ReadTool is visible to a later EditTool. The production path
+        # (Interaction::Lifecycle) injects the SESSION-scoped tracker so the
+        # gate spans turns (#151). Default to a fresh tracker if the caller
+        # didn't supply one; an isolated unit test can pass
+        # `read_tracker: nil` to skip the gate.
+        @read_tracker         = read_tracker.equal?(false) ? nil : (read_tracker || Tools::ReadTracker.new)
+      end
+
+      # Executes a single tool call, returns a Tools::Result.
+      def execute(name:, arguments:, call_id:)
+        tool = @registry.find(name)
+        raise ToolError, "Unknown tool: #{name}" unless tool
+
+        case @approval_policy.decide(tool, arguments: arguments)
+        when :deny
+          # A policy denial must NOT read "denied by user" to the model — the
+          # policy records why it fired (#last_deny_reason) and the Result
+          # maps it to a reason-specific message, so a child agent never
+          # blames the human for an automatic deny (#143).
+          denied = Tools::Result.denied(name: name, call_id: call_id, reason: policy_deny_reason)
+          record_denied(name: name, call_id: call_id, arguments: arguments,
+                        result: denied, reason: "policy-denied")
+          return finish(name, arguments, call_id, denied)
+        when :ask
+          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,
+                          result: denied, reason: "user-denied")
+            return finish(name, arguments, call_id, denied)
+          end
+        end
+
+        notify_yolo_if_applicable(tool, arguments)
+        emit_started(name, arguments)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = nil
+        begin
+          result = run_tool(tool, name: name, arguments: arguments, call_id: call_id)
+        ensure
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+          emit_artifact(result) if result.respond_to?(:artifact) && result&.artifact
+          emit_finished(name, result: result, duration_ms: duration_ms, arguments: arguments)
+        end
+        finish(name, arguments, call_id, result)
+      end
+
+      private
+
+      # Single exit point: notifies the Loop's on_result sink (count + persist)
+      # for every completed/denied tool, then returns the result unchanged. This
+      # is the one place both the streaming (ToolBridge → #execute) and the
+      # non-streaming (Loop#execute_tool_calls → #execute) paths funnel through,
+      # so the turn-summary count and the `tool` message rows stay accurate
+      # regardless of streaming mode. Best-effort: a sink failure must not take
+      # down the tool call the model is waiting on.
+      def finish(name, arguments, call_id, result)
+        @on_result&.call(name: name, arguments: arguments, call_id: call_id, result: result)
+        result
+      rescue StandardError => e
+        Rubino.logger&.warn(event: "tool_executor.on_result_failed", error: e.message)
+        result
+      end
+
+      def run_tool(tool, name:, arguments:, call_id:)
+        tool.cancel_token = @cancel_token if tool.respond_to?(:cancel_token=)
+        tool.read_tracker = @read_tracker if tool.respond_to?(:read_tracker=)
+        streamed = false
+        last_progress_at = nil
+        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)
+            # 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
+            # this a busy tool (summarize_file: ~30 sequential aux-LLM calls,
+            # no run-events) is killed at the 300s idle timeout. Throttled so a
+            # chatty tool (shell streaming thousands of stdout lines) doesn't
+            # write a DB row + SSE frame per line — one heartbeat per interval
+            # is enough to keep the watchdog satisfied.
+            last_progress_at = emit_tool_progress(name, chunk, last_progress_at) if @event_bus
+          end
+        end
+        raw = tool.call(arguments)
+        # Tools can return either a String (plain output) or a Hash carrying
+        # {output:, metrics:, body:, body_kind:}. The Hash form lets a tool emit
+        #   - a `metrics` one-liner for the done header ("42 lines · 0.1s")
+        #   - a `body` block (diff, preview) printed inside the tool box
+        #   - a `body_kind` (:diff | :plain) selecting the CLI coloring for body
+        # without having to reverse-engineer them from the formatted output.
+        if raw.is_a?(Hash)
+          text       = raw[:output]     || raw["output"]
+          metrics    = raw[:metrics]    || raw["metrics"]
+          body       = raw[:body]       || raw["body"]
+          body_kind  = raw[:body_kind]  || raw["body_kind"] || :plain
+          error_code = raw[:error_code] || raw["error_code"]
+          artifact   = raw[:artifact]   || raw["artifact"]
+        else
+          text = raw
+          metrics = nil
+          body = nil
+          body_kind = :plain
+          error_code = nil
+          artifact = nil
+        end
+        # Skip the body block when the tool already streamed its output line by
+        # line via #tool_chunk: `body` is the SAME content (e.g. ShellTool's
+        # Util::Output.preview of the captured stdout), so rendering it again
+        # would duplicate every line in the timeline. Tools that don't stream
+        # (read, grep, edit, glob, github) still render their body here.
+        @ui.tool_body(body, kind: body_kind.to_sym) if body && !body.to_s.empty? && !streamed
+        result = Tools::Result.success(
+          name: name,
+          call_id: call_id,
+          output: Util::Output.truncate(text, max_bytes: @config.tool_output_max_bytes,
+                                              max_lines: @config.tool_output_max_lines,
+                                              spill: ->(full) { spill_full_output(full, call_id) }),
+          metrics: metrics,
+          error_code: error_code&.to_sym,
+          artifact: artifact
+        )
+        @tool_call_repository.record(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)
+        result
+      ensure
+        tool.cancel_token = nil if tool.respond_to?(:cancel_token=)
+        tool.read_tracker = nil if tool.respond_to?(:read_tracker=)
+        tool.stream_chunk = nil if tool.respond_to?(:stream_chunk=)
+      end
+
+      # Cap on per-event size we forward to SSE consumers (the web UI timeline,
+      # CLI logs). Tools already truncate their textual output via
+      # truncate_output for the model's eyes; this is a second guard so a
+      # huge payload doesn't bloat the event bus / DB run_events rows.
+      EVENT_PREVIEW_MAX = 4_000
+
+      # Minimum gap between TOOL_PROGRESS heartbeats forwarded to the bus. Well
+      # under the SSE idle watchdog window (300s) so the stream never goes
+      # silent, but coarse enough that a chatty per-line tool doesn't flood the
+      # event store. The first chunk always emits (nil last-emit time).
+      TOOL_PROGRESS_INTERVAL = 5.0
+
+      # Emits a throttled TOOL_PROGRESS heartbeat on the bus. Returns the
+      # monotonic time of this emit (or the unchanged previous time when the
+      # chunk was throttled) so the caller can track the cadence.
+      def emit_tool_progress(name, chunk, last_at)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return last_at if last_at && (now - last_at) < TOOL_PROGRESS_INTERVAL
+
+        @event_bus&.emit(Interaction::Events::TOOL_PROGRESS,
+                         name: name, chunk: truncate_for_event(chunk.to_s))
+        now
+      end
+
+      def emit_started(name, arguments)
+        sanitized = sanitize_arguments_for_event(arguments)
+        @ui.tool_started(name, arguments: arguments) if @ui.respond_to?(:tool_started)
+        payload = { name: name, arguments: sanitized }
+        # Boundary event for delegation: tag the `task` call with the target
+        # subagent name (+ the task prompt) so an SSE consumer (the web UI)
+        # can render "delegated to X" without parsing the raw arguments. The
+        # subagent's own inner events are NOT streamed in Phase 1 — boundary only.
+        payload.merge!(subagent_tag(arguments)) if name == "task"
+        @event_bus&.emit(Interaction::Events::TOOL_STARTED, **payload)
+      end
+
+      def emit_finished(name, result: nil, duration_ms: nil, arguments: nil)
+        @ui.tool_finished(name, result: result) if @ui.respond_to?(:tool_finished)
+        payload = {
+          name: name,
+          output: truncate_for_event(result&.output.to_s),
+          duration_ms: duration_ms,
+          error_code: result.respond_to?(:error_code) ? result&.error_code : nil
+        }
+        # On completion the `output` already carries the subagent's returned
+        # summary; tag the subagent name (recovered from the call arguments) so
+        # the consumer can render "X answered" and group it with the start.
+        if name == "task" && arguments.is_a?(Hash)
+          subagent = arguments["subagent"] || arguments[:subagent]
+          payload[:subagent] = subagent.to_s unless subagent.nil?
+        end
+        @event_bus&.emit(Interaction::Events::TOOL_FINISHED, **payload)
+      end
+
+      # Extracts the { subagent:, prompt: } boundary tag from a `task` call's
+      # arguments. Nil-tolerant so a malformed call still emits the event.
+      def subagent_tag(arguments)
+        return {} unless arguments.is_a?(Hash)
+
+        subagent = arguments["subagent"] || arguments[:subagent]
+        prompt   = arguments["prompt"]   || arguments[:prompt]
+        tag = {}
+        tag[:subagent] = subagent.to_s unless subagent.nil?
+        tag[:prompt]   = truncate_for_event(prompt.to_s) unless prompt.nil?
+        tag
+      end
+
+      def sanitize_arguments_for_event(arguments)
+        return arguments unless arguments.is_a?(Hash)
+
+        arguments.each_with_object({}) do |(key, value), memo|
+          masked = Util::SecretsMask.mask_value(value, key: key)
+          memo[key.to_s] = truncate_for_event(masked.to_s)
+        end
+      rescue StandardError
+        # Never block the run because of a serialisation hiccup — drop the
+        # arguments rather than crash the tool emission path.
+        nil
+      end
+
+      def truncate_for_event(text)
+        return text if text.nil? || text.bytesize <= EVENT_PREVIEW_MAX
+
+        head = text.byteslice(0, EVENT_PREVIEW_MAX).to_s.force_encoding(text.encoding).scrub("")
+        "#{head}\n…[truncated at #{EVENT_PREVIEW_MAX} bytes]"
+      end
+
+      # ARTIFACT_CREATED is what SSE consumers (e.g. the web UI) latch onto to
+      # render a download card for tools like attach_file. Emit it here so the
+      # streaming path (ToolBridge → ToolExecutor, never lands in Loop's
+      # execute_tool_calls) propagates the artifact too.
+      def emit_artifact(result)
+        @event_bus&.emit(Interaction::Events::ARTIFACT_CREATED, **result.artifact)
+      end
+
+      def record_denied(name:, call_id:, arguments:, result:, reason:)
+        @tool_call_repository.record(
+          name: name,
+          call_id: call_id,
+          arguments: arguments,
+          result: result,
+          status: "denied",
+          error: reason
+        )
+      rescue StandardError
+        # Don't fail the user's request just because the audit write failed.
+      end
+
+      # The reason behind the policy's :deny, when the policy exposes one
+      # (test doubles may not). nil falls back to the generic policy message.
+      def policy_deny_reason
+        return :policy unless @approval_policy.respond_to?(:last_deny_reason)
+
+        @approval_policy.last_deny_reason || :policy
+      end
+
+      def request_approval(tool, arguments)
+        command = Security::ApprovalPolicy.command_string(tool, arguments)
+        _hit, pattern_key, description = Security::DangerousPatterns.detect(command)
+        @ui.confirm(
+          approval_question(tool, arguments),
+          scope: approval_scope(tool, arguments),
+          tool: tool.name,
+          command: command,
+          pattern_key: pattern_key,
+          description: description
+        )
+      end
+
+      # Build a stable string identifier for (tool, arguments) so the
+      # UI layer can short-circuit on a prior "session"/"always"
+      # decision. Reuses the same command extractor ApprovalPolicy
+      # already uses for pattern-rule matching to keep the granularity
+      # consistent — approving `shell ls` will NOT auto-approve
+      # `shell rm -rf /`.
+      def approval_scope(tool, arguments)
+        cmd = Security::ApprovalPolicy.command_string(tool, arguments)
+        cmd.empty? ? tool.name.to_s : "#{tool.name}:#{cmd}"
+      end
+
+      # --yolo / approvals.mode: "skip" bypasses request_approval entirely.
+      # Without any visual signal the user can't tell that the model just
+      # ran (e.g.) `rm -rf` until it's done. Print a single-line warning for
+      # risky tools so silence can't mask the auto-approval. Low-risk tools
+      # (read, glob, grep) stay quiet — yolo for those is no different from
+      # the normal allow path.
+      def notify_yolo_if_applicable(tool, arguments)
+        return unless @config.dig("approvals", "mode") == "skip"
+        return unless tool.respond_to?(:risky?) && tool.risky?
+
+        preview = if arguments.is_a?(Hash)
+                    arguments.map { |k, v| "#{k}=#{summarize_yolo_value(v, key: k)}" }.join(" ")
+                  else
+                    Util::SecretsMask.mask_inline(arguments.to_s)
+                  end
+        @ui.warning("⚡ yolo: #{tool.name} #{preview}")
+      end
+
+      def summarize_yolo_value(value, key: nil)
+        masked = Util::SecretsMask.mask_value(value, key: key).to_s
+        masked = masked.lines.first.to_s.rstrip if masked.include?("\n")
+        masked.length > 60 ? "#{masked[0, 57]}…" : masked
+      end
+
+      # Multi-line aware args formatter for the approval prompt.
+      #
+      # arguments.inspect on a Hash with newline values (shell scripts, file
+      # contents) collapses everything into one giant line, which the terminal
+      # then truncates at the right edge. The user sees "command=\"ls -la"
+      # and approves — without ever seeing the trailing `; rm -rf` that the
+      # model actually sent. Lay each key out on its own line; clip long
+      # values explicitly; tag dropped lines so silence can't mask intent.
+      def approval_question(tool, arguments)
+        pairs = Array(arguments)
+        # No arguments (e.g. a bare run_tests run) ⇒ no dangling "wants:" — a
+        # header followed by nothing reads as a truncated/broken card (#109).
+        return "#{tool.name} wants to run" if pairs.empty?
+
+        # The common case — ONE short single-line argument (a shell command, a
+        # 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
+        end
+
+        lines = ["#{tool.name} wants:"]
+        pairs.each { |key, value| lines.concat(format_arg_pair(key, value)) }
+        lines.join("\n")
+      end
+
+      def format_arg_pair(key, value)
+        # Mask credentials before any rendering: the approval prompt is the
+        # one place a real secret value could land in the user's scrollback
+        # if the model passed it through unwrapped.
+        text = Util::SecretsMask.mask_value(value, key: key).to_s
+        if text.include?("\n")
+          body = text.lines
+          head = body.first(5).map(&:rstrip)
+          tail = body.size > 5 ? ["  [… #{body.size - 5} more line(s)]"] : []
+          ["  #{key}:", *head.map { |l| "    #{l}" }, *tail]
+        elsif text.length > 120
+          ["  #{key}: #{text[0, 117]}…"]
+        else
+          ["  #{key}: #{text}"]
+        end
+      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
+      # on overflow — Util keeps the pure shaping, the executor keeps the IO).
+      # Best-effort: a write failure just yields no path and the marker falls
+      # back to its grep/head hint. Returns the path or nil.
+      def spill_full_output(text, call_id)
+        id = call_id.to_s.gsub(/[^a-zA-Z0-9_.-]/, "_")
+        return nil if id.empty?
+
+        dir = File.join(Rubino.home_path, "tool-results")
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "#{id}.txt")
+        File.write(path, text)
+        path
+      rescue StandardError => e
+        Rubino.logger&.warn(event: "tool_output.spill_failed", error: e.message)
+        nil
+      end
+    end
+  end
+end