rubino-agent 0.5.2.1 → 0.5.2.2

data/lib/rubino/llm/ruby_llm_adapter.rb

@@ -3,6 +3,8 @@
 require "ruby_llm"
 require "faraday"
 require "net/http"
+require "uri"
+require "ipaddr"
 require_relative "tool_bridge"
 require_relative "cache_breakpoint_middleware"
 require_relative "inline_think_filter"
@@ -198,7 +200,7 @@ module Rubino
         think_filter  = InlineThinkFilter.new
         buffered      = +""
         last_chunk_at = monotonic_now
-        stale_after   = stale_chunk_timeout
+        stale_after   = stale_chunk_timeout(messages)
         chunks_seen   = 0
         # #488: a tool that ruby_llm runs MID-STREAM (e.g. a blocking
         # `question`/clarify parked on a human answer for up to the clarify
@@ -228,6 +230,9 @@ module Rubino
         # glued on. The headless one-shot `result` surfaces this, not `buffered`.
         last_block      = +""
         last_block_seen = message_block_id
+        # Tool-call ids already announced as "preparing" this stream, so the
+        # per-chunk arg deltas of one call surface the name exactly once (#608).
+        announced_tools = {}
 
         emit = lambda do |type, text|
           next if text.nil? || text.empty?
@@ -313,9 +318,10 @@ module Rubino
         # stalled SSE / a 200 that never sends an event), nothing inside the
         # callback ever runs and the only backstop is the 600s socket
         # read-timeout. Bound the idle gap INDEPENDENTLY of chunk arrival with a
-        # watchdog thread that wakes on `stale_after` (300s default, well below
-        # 600s; configurable via providers.<name>.stale_timeout_seconds) and, on
-        # observing an idle past the deadline, raises StreamStaleError INTO this
+        # watchdog thread that wakes on `stale_after` (90s remote default,
+        # DISABLED for local endpoints, configurable via
+        # providers.<name>.stale_timeout_seconds — see #stale_chunk_timeout) and,
+        # on observing an idle past the deadline, raises StreamStaleError INTO this
         # streaming thread to break it out of the blocking socket read. The
         # rescue below then surfaces a clear "stream stalled" and lets the retry
         # ladder run. The closure reads `last_chunk_at`/`chunks_seen` live (they
@@ -344,6 +350,13 @@ module Rubino
               emit.call(:thinking, thinking_text)
             end
             think_filter.feed(chunk.content, &emit) if chunk.content.is_a?(String) && !chunk.content.empty?
+            # A tool-call delta (the streaming arguments of a long `write`, etc.)
+            # carries neither thinking nor textual content. Surface BOTH the tool
+            # NAME once per call (:tool_preparing, so the timeline can open the
+            # tool card the moment the call starts) AND every argument FRAGMENT
+            # (:tool_args, so the UI streams the params live and the token meter
+            # keeps climbing instead of freezing while a big file streams). #608.
+            announce_tool_stream(chunk, announced_tools, &emit)
           end
         rescue Rubino::Interrupted
           # Flush whatever the filter has buffered, then re-raise. Loop will
@@ -363,13 +376,13 @@ module Rubino
           end
           log_safely(event: "llm.stream.partial", error: e.message, buffered_bytes: buffered.bytesize)
           flush_filter(think_filter, &emit)
-          return partial_response(buffered)
+          return partial_response(buffered, usage)
         rescue JSON::ParserError => e
           # Preserve whatever we've buffered so far so the user sees partial
           # output instead of a blank failure. (issues #12, #22)
           log_safely(event: "llm.stream.partial", error: e.message, buffered_bytes: buffered.bytesize)
           flush_filter(think_filter, &emit)
-          return partial_response(buffered)
+          return partial_response(buffered, usage)
         rescue *STREAM_DROP_ERRORS => e
           # A genuine transport drop (the observed M3 EOF, a connection reset, a
           # read timeout, …). If NOTHING was emitted yet, re-raise so the runner
@@ -382,7 +395,7 @@ module Rubino
           log_safely(event: "llm.stream.partial_interrupted", error: e.message,
                      buffered_bytes: buffered.bytesize)
           flush_filter(think_filter, &emit)
-          return partial_response(buffered)
+          return partial_response(buffered, usage)
         ensure
           # Always tear the watchdog down — on success, on partial-return, and on
           # a raised StreamStaleError/transport drop — so it never leaks a thread
@@ -453,11 +466,27 @@ module Rubino
         {
           content: msg.respond_to?(:content) ? msg.content : nil,
           tool_calls: normalize_message_tool_calls(msg),
+          # Carry the reasoning forward so the Loop persists it and later turns
+          # replay it (KV-cache prefix stability, #608b — see load_history).
+          reasoning: message_reasoning_text(msg),
           input_tokens: msg.respond_to?(:input_tokens) ? msg.input_tokens.to_i : 0,
           output_tokens: msg.respond_to?(:output_tokens) ? msg.output_tokens.to_i : 0
         }
       end
 
+      # The reasoning text on a ruby_llm Message (its `thinking` is a
+      # RubyLLM::Thinking with `#text`), or nil. Best-effort: a chunk-shape quirk
+      # must never break the intermediate-persist path.
+      def message_reasoning_text(msg)
+        return nil unless msg.respond_to?(:thinking) && msg.thinking
+
+        t = msg.thinking
+        text = t.respond_to?(:text) ? t.text : t.to_s
+        text.to_s.empty? ? nil : text
+      rescue StandardError
+        nil
+      end
+
       def normalize_message_tool_calls(msg)
         return [] unless msg.respond_to?(:tool_calls) && msg.tool_calls
 
@@ -475,14 +504,56 @@ module Rubino
         log_safely(event: event, error: e.message)
       end
 
+      # Surface a streaming tool call to the UI as two signals (#608):
+      #   * `:tool_preparing` — the tool NAME, emitted ONCE per call (deduped via
+      #     +announced+, keyed by id), the instant the call first appears. The
+      #     timeline uses it to open the tool card at the START of the call.
+      #   * `:tool_args` — every argument FRAGMENT as it streams. ruby_llm yields
+      #     the per-delta chunk (not the accumulator), so `tc.arguments` here is
+      #     the NEW fragment, not the cumulative string — forward it as-is. The UI
+      #     streams these as the live params and counts them toward the token
+      #     meter, so a long `write` shows progress instead of a frozen footer.
+      # Both ride the stream's (type, text) lambda, so they share the same
+      # error-handled path as content/thinking. Best-effort: never let a
+      # chunk-shape quirk break the stream.
+      def announce_tool_stream(chunk, announced, &emit)
+        calls = chunk.respond_to?(:tool_calls) ? chunk.tool_calls : nil
+        return unless calls.respond_to?(:each_value)
+
+        calls.each_value do |tc|
+          name = tc.respond_to?(:name) ? tc.name : nil
+          if name && !name.empty?
+            id = (tc.respond_to?(:id) && tc.id) || name
+            unless announced[id]
+              announced[id] = true
+              emit.call(:tool_preparing, name.to_s)
+            end
+          end
+
+          args = tc.respond_to?(:arguments) ? tc.arguments : nil
+          emit.call(:tool_args, args) if args.is_a?(String) && !args.empty?
+        end
+      rescue StandardError => e
+        log_safely(event: "llm.stream.tool_stream_error", error: e.message)
+      end
+
       # Buffered-partial AdapterResponse returned when a stream is cut after at
       # least one chunk (parse error, stale, or post-first-chunk transport drop).
       # Flagged +interrupted+ so the Loop fails the turn (run.failed) instead of
       # mistaking the truncated buffer for a finished answer (the silent
       # "completed-but-empty" bug — see Rubino::StreamInterruptedError).
-      def partial_response(buffered)
-        AdapterResponse.new(content: buffered, tool_calls: [], input_tokens: 0,
-                            output_tokens: 0, model_id: @model_id, interrupted: true)
+      #
+      # Token accounting (#token-loss): a cut stream still SPENT the tokens of
+      # every round-trip ruby_llm already completed inside this one ask() — the
+      # `usage` accumulator (wire_round_trip_callbacks) holds their summed spend
+      # at the moment of the drop. A multi-round-trip TOOL turn against a flaky
+      # transport is exactly where this fires, so zeroing the tokens here made
+      # tool/file-writing turns report no token spend at all. Carry the
+      # accumulated usage through so the turn summary still counts what was spent.
+      def partial_response(buffered, usage = nil)
+        summed_in, summed_out = usage ? [usage[:input].to_i, usage[:output].to_i] : [0, 0]
+        AdapterResponse.new(content: buffered, tool_calls: [], input_tokens: summed_in,
+                            output_tokens: summed_out, model_id: @model_id, interrupted: true)
       end
 
       def configure_ruby_llm!
@@ -971,15 +1042,86 @@ module Rubino
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
 
-      def stale_chunk_timeout
+      # The stale-stream watchdog deadline, ported from Hermes'
+      # _compute_non_stream_stale_timeout (run_agent.py). Priority:
+      #   1. providers.<id>.stale_timeout_seconds — explicit always wins.
+      #   2. LOCAL endpoint (localhost / 127.x / host.docker.internal / RFC-1918
+      #      / Tailscale CGNAT) with NO explicit config ⇒ DISABLED (0): a large
+      #      local model can legitimately PREFILL for minutes before the first
+      #      token, and a local box isn't a flaky remote provider — the 600s
+      #      socket read-timeout still backstops a genuinely dead connection.
+      #      This is the fix for "no chunk received for 30s" on local models.
+      #   3. Remote default 90s (Hermes parity; was 30/300), scaled UP for large
+      #      contexts whose prefill is inherently slower (>50k→150, >100k→240).
+      # 0 disables the watchdog (start_stale_watchdog / check_stream_stale! both
+      # early-return on a non-positive deadline).
+      def stale_chunk_timeout(messages = nil)
         explicit = @config.dig("providers", @provider, "stale_timeout_seconds")
         return explicit if explicit
 
-        return 30 if openai_compatible_provider? || anthropic_compatible_provider?
+        return 0 if local_endpoint?
 
-        @config.dig("providers", "openai", "stale_timeout_seconds") || 300
+        scale_stale_for_context(default_remote_stale_timeout, messages)
       end
 
+      DEFAULT_REMOTE_STALE_SECONDS = 90
+
+      def default_remote_stale_timeout
+        @config.dig("providers", "openai", "stale_timeout_seconds") || DEFAULT_REMOTE_STALE_SECONDS
+      end
+
+      # Bump the base deadline for large requests — prefill (time-to-first-token)
+      # grows with context, so a flat timeout false-positives on big prompts.
+      def scale_stale_for_context(base, messages)
+        est = estimate_context_tokens(messages)
+        return [base, 240].max if est > 100_000
+        return [base, 150].max if est > 50_000
+
+        base
+      end
+
+      # Cheap context-size estimate (~4 chars/token) over the request messages,
+      # only used to pick a timeout tier — never for billing/truncation. Tolerant
+      # of either symbol/string content keys and any odd shape (→ 0).
+      def estimate_context_tokens(messages)
+        return 0 unless messages.respond_to?(:sum)
+
+        chars = messages.sum do |m|
+          content = m[:content] || m["content"] if m.respond_to?(:[])
+          content.to_s.length
+        end
+        chars / 4
+      rescue StandardError
+        0
+      end
+
+      # True when the configured base_url points at the local machine / private
+      # network — a faithful port of Hermes' agent.model_metadata.is_local_endpoint.
+      # Such endpoints auto-disable the stale watchdog (slow local prefill is
+      # normal, not a stall). Any parse failure ⇒ treat as remote (false).
+      def local_endpoint?
+        url = present_base_url(provider_cfg).to_s
+        return false if url.empty?
+
+        host = (URI.parse(url).host || URI.parse("http://#{url}").host).to_s.downcase
+        return false if host.empty?
+        return true if LOCAL_HOSTS.include?(host)
+        return true if CONTAINER_LOCAL_SUFFIXES.any? { |s| host.end_with?(s) }
+
+        ip = IPAddr.new(host)
+        ip.loopback? || ip.private? || ip.link_local? || TAILSCALE_CGNAT.include?(ip)
+      rescue URI::InvalidURIError, IPAddr::Error
+        false
+      end
+
+      LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1 0.0.0.0].freeze
+      # Container/VM internal DNS (host.docker.internal, *.lima.internal, …) and
+      # the mDNS .local suffix all resolve to the host loopback in practice.
+      CONTAINER_LOCAL_SUFFIXES = %w[.internal .local .localhost].freeze
+      # Tailscale CGNAT 100.64.0.0/10 — a remote-but-trusted local box reached
+      # over a Tailscale mesh gets the same treatment as localhost.
+      TAILSCALE_CGNAT = IPAddr.new("100.64.0.0/10")
+
       def check_stream_stale!(last_chunk_at, stale_after)
         return if stale_after.to_f <= 0
         return if (monotonic_now - last_chunk_at) <= stale_after
@@ -1095,7 +1237,13 @@ module Rubino
             chat_instance.messages << RubyLLM::Message.new(
               role: role,
               content: content,
-              tool_calls: tool_calls
+              tool_calls: tool_calls,
+              # Replay the stored reasoning as the wire `reasoning_content`
+              # (openai/chat.rb#format_thinking) so the prompt prefix byte-matches
+              # the server's KV cache, which holds this turn's reasoning tokens
+              # (#608b). Omitting it diverged the prefix at the reasoning boundary
+              # and forced a full re-prefill every turn.
+              thinking: rebuild_thinking(msg[:reasoning] || msg["reasoning"])
             )
           when :tool
             chat_instance.messages << build_tool_message(
@@ -1175,6 +1323,16 @@ module Rubino
         end
       end
 
+      # Reconstructs the RubyLLM::Thinking carrying a replayed assistant turn's
+      # reasoning (#608b), or nil when there is none. RubyLLM::Thinking.build
+      # already drops empty text, so a blank/absent reasoning yields nil and the
+      # message replays without a reasoning_content field (unchanged behaviour).
+      def rebuild_thinking(reasoning)
+        return nil if reasoning.nil? || reasoning.to_s.empty?
+
+        RubyLLM::Thinking.build(text: reasoning.to_s)
+      end
+
       # +buffered+ (streaming path) is every assistant TEXT block of the turn
       # concatenated, not just the final one. ruby_llm runs tools mid-stream and
       # returns a response whose #content is only the LAST block, so any text the
@@ -1330,13 +1488,13 @@ module Rubino
 
       # Reasoning text/summary if ruby_llm surfaced it on the message; nil
       # otherwise. Kept defensive — older builds carry no reasoning field.
+      # ruby_llm exposes a completed message's reasoning as #thinking (a
+      # RubyLLM::Thinking with #text) — there is no #reasoning method, so the old
+      # probe (response.reasoning) always rescued to nil and the final turn's
+      # reasoning was never persisted; its replay then busted the KV-cache prefix
+      # (#608b). Same extraction the intermediate path uses (#message_reasoning_text).
       def extract_thinking(response)
-        return nil unless response.respond_to?(:reasoning) && response.reasoning
-
-        r = response.reasoning
-        r.respond_to?(:text) ? r.text : r.to_s
-      rescue StandardError
-        nil
+        message_reasoning_text(response)
       end
 
       def extract_tool_calls(response)

data/lib/rubino/security/redactor.rb

@@ -11,7 +11,7 @@ module Rubino
     # `grep` match content (both with code_file:true to skip the ENV/JSON
     # assignment patterns that false-positive on source), `shell`/background
     # shell output (full patterns — `cat .env` / `printenv` leak keys), and
-    # the `summarize_file` chunks shipped to the auxiliary model.
+    # converted-document content from `read_attachment` before it enters context.
     #
     # Short tokens (< 18 chars) are fully masked; longer ones preserve the
     # first 6 and last 4 characters for debuggability — matching Hermes'

data/lib/rubino/session/message.rb

@@ -65,6 +65,18 @@ module Rubino
         # Surface assistant tool_calls (persisted as metadata) so the adapter
         # can rebuild the toolUse block expected by strict providers on resume.
         msg[:tool_calls] = @metadata[:tool_calls] if @metadata.is_a?(Hash) && @metadata[:tool_calls]
+        # Replay the assistant's reasoning on every later turn (Hermes
+        # conversation_loop.py:940 "pass reasoning back to the API for ALL
+        # assistant messages"). The local server's KV cache, after generating a
+        # turn, holds the reasoning tokens; a replay that OMITS them diverges
+        # from that cache at the point the reasoning was generated, forcing a
+        # full re-prefill of the whole context every turn. Re-emitting the stored
+        # reasoning keeps the prompt prefix byte-stable so the server reuses the
+        # cache (verified: same assistant row got a KV hit WITH reasoning, a miss
+        # WITHOUT). The adapter rebuilds it into the wire `reasoning_content`.
+        if @role == "assistant" && @metadata.is_a?(Hash) && (reasoning = @metadata[:reasoning])
+          msg[:reasoning] = reasoning
+        end
         # #583: re-derive the error flag from the persisted outcome so a
         # denied/errored tool result replays to the model marked as an error
         # (is_error) on the next turn, exactly as it was sent live — never as a

data/lib/rubino/tools/background_tasks.rb

@@ -59,10 +59,24 @@ module Rubino
       # to remember); the parking/wake/stop-cancel plumbing is identical.
       Entry = Struct.new(
         :id, :subagent, :prompt, :status, :result, :error,
+        # How the child's turn TERMINATED (Agent::Loop#stop_reason). :completed on
+        # a real answer; :max_time / :max_iterations / :stream_incomplete when the
+        # run was force-summarized/truncated. Lets the completion notice, the card,
+        # and task_result all report a truncated run as PARTIAL, not "completed".
+        :stop_reason,
         :thread, :runner, :started_at, :finished_at,
         :last_activity, :tool_count, :activity_log, :output_tail,
         :approval_gate, :approval_id, :approval_question, :approval_command,
         :budget_request,
+        # "Decide later" (#586): the user dismissed this request's AUTO-modal
+        # without deciding it. The child stays parked on its gate and the
+        # `wants +budget` card stays visible, but auto_resolve stops re-popping
+        # the modal at idle — the user re-engages it deliberately via the picker /
+        # `/agents <id>` (the manual path presents regardless). This is what makes
+        # the picker's ↓+Enter gesture non-destructive: a stray gesture lands on
+        # "Decide later" (defers) instead of "Summarize now". Cleared when the
+        # approval is (re)opened or decided. nil/false ⇒ auto-pops normally.
+        :approval_snoozed,
         # Monotonic stamp of the instant this child blocked on its approval gate
         # (begin_approval), used to order the approval MODAL QUEUE FIFO: only one
         # approval modal is presented at a time (awaiting_approval.first), and a
@@ -98,6 +112,36 @@ module Rubino
           session_id = runner&.session&.dig(:id)
           session_id ? ::Rubino::Session::Store.new.for_session(session_id) : []
         end
+
+        # A subagent IS NOT a shell — the discriminator the shared /stop, steer,
+        # probe and attach paths dispatch on (ShellEntryAdapter#shell? ⇒ true).
+        def shell? = false
+
+        # Parent→child steer: park a turn-boundary note on the child's queue
+        # (folded in at its next iteration). The shell analogue is a stdin write.
+        def steer(text)
+          return false unless steer_queue
+
+          steer_queue.push(text)
+          true
+        end
+
+        # Ephemeral read-only peek: a synchronous LLM side-inference over the
+        # child's current context. The shell analogue is an output snapshot.
+        def peek(question)
+          ::Rubino::Tools::SubagentProbe.new.peek(entry: self, question: question)
+        end
+
+        # A dim hint shown ABOVE a probe answer, or nil. A just-spawned subagent has
+        # an empty context, so its honest "I'm not doing anything yet" reply would
+        # read as broken (#112) without this; a shell has no such notion (its peek
+        # IS its output), so the adapter returns nil.
+        def peek_hint
+          return unless tool_count.to_i.zero?
+
+          "(snapshot at this instant — the child just started and its context is " \
+            "still empty; probe again in a moment)"
+        end
       end
 
       # How many recent activity lines the drill-in shows (the live `recent:` ring).
@@ -254,12 +298,13 @@ module Rubino
       # omitted from `undelivered`, yet reported delivered. Returns the notes
       # that were still queued at finalize time (never delivered to the child),
       # so the caller can surface them as undelivered.
-      def complete(entry, status:, result: nil, error: nil)
+      def complete(entry, status:, result: nil, error: nil, stop_reason: nil)
         @mutex.synchronize do
           status            = :stopped if entry.status == :stopping && status == :failed
           entry.status      = status
           entry.result      = result
           entry.error       = error
+          entry.stop_reason = stop_reason
           entry.finished_at = Time.now
           # Drain UNDER the mutex: anything still here is undelivered (the child
           # has no further turn to fold it in), and once status is terminal no
@@ -334,11 +379,26 @@ module Rubino
           entry.approval_question = question.to_s
           entry.approval_command  = command.to_s
           entry.budget_request    = budget ? true : false
+          entry.approval_snoozed  = false
           entry.approval_seq      = (@approval_seq += 1)
           entry.status            = :needs_approval
         end
       end
 
+      # "Decide later" (#586): stop auto-popping THIS request's modal at idle
+      # without deciding its gate — the child stays parked and the card stays
+      # visible; the user re-engages via the picker / `/agents <id>`. Mirrors
+      # begin/end_approval (one mutex-guarded mutation of the entry's approval
+      # state); a no-op if the entry is gone.
+      def snooze_approval(id)
+        @mutex.synchronize do
+          entry = @entries[id]
+          return unless entry
+
+          entry.approval_snoozed = true
+        end
+      end
+
       # Clears the approval state and returns the entry to :running once a
       # decision has been delivered (or the child unwinds).
       def end_approval(id)
@@ -351,6 +411,7 @@ module Rubino
           entry.approval_question = nil
           entry.approval_command  = nil
           entry.budget_request    = false
+          entry.approval_snoozed  = false
           entry.approval_seq      = nil
           entry.status            = :running if entry.status == :needs_approval
         end
@@ -373,15 +434,15 @@ module Rubino
       # is no window in which a note is pushed onto a queue nobody will drain yet
       # reported delivered. Pushing inside the mutex is safe: InputQueue#push has
       # its own lock and never calls back into the registry, so no lock cycle.
+      # Send input to a background worker. The registry owns the liveness guard
+      # (one place); the ACTION is polymorphic on the entry — a subagent parks a
+      # turn-boundary steer note, a shell writes straight to its stdin.
       def steer(id, text)
-        @mutex.synchronize do
-          entry = @entries[id]
-          return false unless entry&.steer_queue
-          return false if terminal_status?(entry.status)
+        entry = find(id)
+        return false unless entry
+        return false if terminal_status?(entry.status)
 
-          entry.steer_queue.push(text)
-          true
-        end
+        entry.steer(text)
       end
 
       # Records a BILLED live probe against a child (S3): bumps probe_count
@@ -424,12 +485,29 @@ module Rubino
       end
 
       def find(id)
-        @mutex.synchronize { @entries[id] }
+        @mutex.synchronize { @entries[id] } || shell_adapter_for(id)
+      end
+
+      # A read-time adapter for a background SHELL by id (bg_*), or nil. Lets the
+      # shared /stop and attach paths resolve a shell exactly like a subagent
+      # without the shell living in @entries (no cap/steer/sync coupling).
+      def shell_adapter_for(id)
+        shell = ShellRegistry.instance.find(id)
+        shell ? ShellEntryAdapter.new(shell) : nil
       end
 
-      # All entries, newest first — for a `task` listing (the /tasks analogue).
+      # All entries, newest first — for a `task` listing (the /tasks analogue) and
+      # the /agents list + /status count. Includes background shells (same unified
+      # set as #running) so a running shell is never visible in the picker/cards
+      # yet absent from the list/count.
       def list
-        @mutex.synchronize { @entries.values.sort_by(&:started_at).reverse }
+        subs = @mutex.synchronize { @entries.values }
+        # The list (/agents table, /status count) keeps FINISHED subagents, so it
+        # keeps finished-but-retained shells too (running + retired) for symmetry —
+        # otherwise a just-finished shell vanished from /agents while a finished
+        # subagent lingered. #running stays running-only (the live picker/cards).
+        shells = ShellRegistry.instance.listable_entries.map { |e| ShellEntryAdapter.new(e) }
+        (subs + shells).sort_by(&:started_at).reverse
       end
 
       # Live (still-running) children — used by the parent stop path to cancel
@@ -437,7 +515,18 @@ module Rubino
       # approval (:needs_approval) is STILL live (its thread is alive, holding a
       # slot), so it counts as running here.
       def running
-        @mutex.synchronize { @entries.values.select { |e| live_status?(e.status) } }
+        subs = @mutex.synchronize { @entries.values.select { |e| live_status?(e.status) } }
+        subs + shell_adapters
+      end
+
+      # Background SHELLS, presented as read-time adapters that duck-type a
+      # subagent entry — the ONE place shells join the unified live set, so every
+      # surface that lists "background work" (cards, picker, /agents list, /status
+      # count) includes them with zero shell-specific branches. No second registry
+      # entry ⇒ no status sync / double completion notice / concurrency-cap
+      # pollution / dead steer_queue.
+      def shell_adapters
+        ShellRegistry.instance.running_entries.map { |e| ShellEntryAdapter.new(e) }
       end
 
       def remove(id)
@@ -455,10 +544,16 @@ module Rubino
       # non-live status), so #cancel_all can call it across the whole registry.
       def stop_entry(entry)
         return unless entry
+        # A shell stops by killing its process group (polymorphic #stop on the
+        # adapter), not by the cooperative subagent cancel.
+        return entry.stop if entry.respond_to?(:shell?) && entry.shell?
 
         request_stop(entry.id)
         entry.approval_gate&.cancel!
         entry.runner&.cancel!
+        # Cascade-kill the child background shells this subagent opened — stopping
+        # a subagent stops its resources (Hermes kill_all(task_id)).
+        ShellRegistry.instance.terminate_owned_by(entry.id)
       end
 
       # Structured-concurrency teardown seam: cancel EVERY live subagent so the

data/lib/rubino/tools/base.rb

@@ -295,7 +295,7 @@ module Rubino
       end
 
       # Typed "outside workspace" error gate, retained for the AUX-LLM read
-      # tools (summarize_file, vision) ONLY. Those route the raw file bytes
+      # tools (vision) ONLY. Those route the raw file bytes
       # through a third-party auxiliary model, so an out-of-workspace read would
       # EXFILTRATE a sibling-repo secret / ~/.ssh file — a stronger threat than
       # the in-process read/grep/glob, which were relaxed to broad in #406. A