rubino-agent 0.3.0 → 0.5.0

data/lib/rubino/util/output.rb

@@ -19,6 +19,136 @@ module Rubino
       DEFAULT_HEAD = 5
       DEFAULT_TAIL = 10
 
+      # The NUL byte (U+0000) is the one control char that is VALID UTF-8 yet
+      # still breaks the persistence layer: the SQLite3 driver treats it as a
+      # C-string terminator and raises "unrecognized token" (the tool row never
+      # persists), and JSON re-tags the value as BINARY. String#scrub leaves it
+      # alone (it only repairs INVALID bytes), so scrub-to-UTF-8 is necessary
+      # but not sufficient — NUL has to go too.
+      NUL = "\x00"
+
+      # Coerces +text+ to a clean, persistable UTF-8 string: valid encoding AND
+      # free of NUL bytes.
+      #
+      # Tool output is captured raw from a subprocess pipe / file read / MCP
+      # response and can be binary or latin-1 (`head -c 1500 /dev/urandom`,
+      # `cat some.png`). Such bytes are tagged UTF-8 (the pipe's external
+      # encoding) but are NOT valid UTF-8, so the moment they reach
+      # JSON.generate (the LLM request, the run-event store) or the SQLite
+      # driver they raise "source sequence is illegal/malformed utf-8" /
+      # "UTF-8 passed as BINARY" / "unrecognized token" and the tool row never
+      # persists — the model loses the record on --resume. Random binary ALSO
+      # carries NUL bytes, which survive String#scrub (NUL is valid UTF-8) yet
+      # still wedge SQLite, so we strip them here too. Cleaning at the CAPTURE
+      # seam (before the bytes are ever copied into the result) means every
+      # downstream consumer sees a safe string. Idempotent on already-clean
+      # input. Pure.
+      def self.scrub_utf8(text)
+        s = scrub_encoding(text)
+        s.include?(NUL) ? s.delete(NUL) : s
+      end
+
+      # Encoding-only repair: returns a valid-UTF-8 string, leaving control
+      # bytes (incl. NUL) in place. Split out from #scrub_utf8 because the two
+      # consumers want different things downstream of "make it valid UTF-8":
+      # the PERSIST seam (#scrub_utf8) deletes NUL outright (SQLite-fatal), but
+      # the TERMINAL render seam (#sanitize_terminal) wants every control byte
+      # turned into VISIBLE caret notation — so it scrubs encoding here, then
+      # does its own C0/C1 pass instead of pre-deleting NUL. Pure.
+      def self.scrub_encoding(text)
+        s = text.to_s
+        return s if s.encoding == Encoding::UTF_8 && s.valid_encoding?
+
+        s.dup.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      # ESC (0x1B): the introducer for ALL the dangerous sequences — CSI
+      # (cursor move, screen clear, scroll region), OSC (set window title,
+      # hyperlinks, clipboard write), DCS, etc.
+      ESC = "\e"
+      # U+009B is the single-byte CSI introducer: a terminal treats it exactly
+      # like `ESC [`, so stripping ESC alone would leave a working injection
+      # vector. It only exists AFTER UTF-8 decoding (the byte 0x9B on its own
+      # is invalid UTF-8 and scrubbed; U+0085/U+0080–U+009F arrive via valid
+      # 2-byte forms), so we strip the C1 block on the decoded string.
+      C1_RANGE = "€-Ÿ"
+
+      # Neutralizes terminal-control bytes in UNTRUSTED tool output before it
+      # is printed to a real terminal.
+      #
+      # Threat (CWE-150): raw `\e[2J` (clear screen), `\e[41m…\e[0m` (color),
+      # `\e]0;…\a` (set title), `\e]52;…` (clipboard write) embedded in
+      # shell/file/MCP output reach the emulator and EXECUTE — the live tool
+      # tail printed it verbatim. Following git's `core.fsmonitor`-style and
+      # dgl.cx's "sanitize at the render chokepoint" guidance, we strip every
+      # control byte that can move the cursor, repaint, or drive the terminal,
+      # and render what we removed as visible caret/<XX> notation so the user
+      # SEES that bytes were there (silent deletion hides the attack).
+      #
+      # Kept: \t (0x09) and \n (0x0A) — legitimate layout. \r is normalized to
+      # \n (a bare CR rewinds the line and lets later text overwrite what was
+      # already shown — another spoofing vector). Stripped: C0 0x00–0x1F
+      # (except \t/\n), DEL 0x7F, ESC 0x1B, and the C1 block 0x80–0x9F.
+      #
+      # rubino's OWN styling (the @pastel.dim/green wrapper applied AROUND this
+      # content) is a separate, trusted path and is never passed through here.
+      # Pure.
+      def self.sanitize_terminal(text)
+        # Encoding-scrub ONLY (keep NUL et al.) so the C0 pass below can turn
+        # every control byte into visible caret notation — silent deletion
+        # would hide that the tool tried to emit them.
+        s = scrub_encoding(text)
+        # Bare CR (not part of CRLF) → newline, so overwrite-spoofing can't
+        # rewind the rendered line. CRLF collapses to a single LF.
+        s = s.gsub(/\r\n?/, "\n")
+        s = s.gsub(/[\x00-\x08\x0B-\x1F\x7F]/) { |c| caret(c) }
+        s.gsub(/[#{C1_RANGE}]/o) { |c| "<#{format("%02X", c.ord)}>" }
+      end
+
+      # SGR colour/style escapes (`\e[…m`) — the ONE escape class that is SAFE
+      # to keep through the sanitizer: it changes only colour/weight and cannot
+      # move the cursor, clear the screen, set the title, or write the
+      # clipboard. Matched so #sanitize_terminal_keep_sgr can preserve rubino's
+      # OWN styling (e.g. the colored /agents status glyph) while still
+      # neutralizing every dangerous control byte.
+      SGR_RE = /\e\[[0-9;]*m/
+
+      # Like #sanitize_terminal, but PRESERVES SGR colour escapes.
+      #
+      # Some sinks interpolate TRUSTED rubino styling (a pastel-colored cell,
+      # e.g. the /agents table's "● approval" status) THROUGH the same cell
+      # sanitizer that guards untrusted text. Plain #sanitize_terminal rendered
+      # those SGR bytes as visible caret notation (`^[[33m●^[[0m approval`) —
+      # the FRICTION-3 leak. Keep the (inert) SGR sequences, neutralize
+      # everything else exactly as #sanitize_terminal does, so colour survives
+      # but `\e[2J` / `\e]0;…` / cursor moves still can't reach the terminal.
+      # Callers that measure width must strip SGR first (see SGR_RE / the
+      # display-width helpers) since SGR occupies zero columns. Pure.
+      def self.sanitize_terminal_keep_sgr(text)
+        s = scrub_encoding(text)
+        # Carve out the SGR runs, sanitize the gaps, splice the SGR back in.
+        parts = []
+        last  = 0
+        s.to_enum(:scan, SGR_RE).each do
+          m = Regexp.last_match
+          parts << sanitize_terminal(s[last...m.begin(0)])
+          parts << m[0]
+          last = m.end(0)
+        end
+        parts << sanitize_terminal(s[last..]) if last < s.length
+        parts.join
+      end
+
+      # Visible, unambiguous stand-in for a stripped control byte: ESC → "^[",
+      # NUL → "^@", DEL → "^?" — the classic `cat -v` caret notation, so the
+      # user can tell exactly what the tool tried to emit.
+      def self.caret(byte)
+        code = byte.ord
+        return "^?" if code == 0x7F
+
+        "^#{(code ^ 0x40).chr}"
+      end
+
       # Returns either the full text (when total lines <= max) or a
       # head + marker + tail preview. Pure function — no side effects,
       # no IO. Caller decides where to render the result.
@@ -31,17 +161,76 @@ module Rubino
       def self.preview(text, max: DEFAULT_MAX, head: DEFAULT_HEAD, tail: DEFAULT_TAIL)
         return "" if text.nil? || text.to_s.empty?
 
-        lines = text.to_s.lines.map(&:chomp)
-        return lines.join("\n") if lines.size <= max
+        s = text.to_s
+        # Count newlines instead of materializing `s.lines` (#373): a ~1KB
+        # value with a 2-million-element single-line buffer used to allocate a
+        # 2M-element array (+ another 2M chomp'd copy via `.map(&:chomp)`) just
+        # to learn it fits — ~hundreds of MB of churn for a preview the caller
+        # may not even trim. `count("\n")` is O(n) bytes with zero allocation.
+        # total line count = newline count (+1 unless the buffer ends in \n).
+        total = line_count(s)
+        if total <= max
+          # Fits: only NOW materialize, and only to chomp the trailing newlines
+          # of the (already small) line set.
+          return s.lines.map(&:chomp).join("\n")
+        end
 
-        omitted  = lines.size - head - tail
-        head_pt  = lines.first(head)
-        tail_pt  = lines.last(tail)
-        marker   = "… [#{omitted} more lines · full in DB] …"
+        # Trimming: we only need the FIRST `head` and LAST `tail` lines, so
+        # take them off the head/tail SLICES of the buffer rather than splitting
+        # the whole thing into a (potentially huge) lines array. each_line with
+        # a bounded take avoids walking past what we keep on the head side.
+        head_pt = head_lines(s, head)
+        tail_pt = tail_lines(s, tail)
+        omitted = total - head_pt.size - tail_pt.size
+        marker  = "… [#{omitted} more lines · full in DB] …"
 
         (head_pt + [marker] + tail_pt).join("\n")
       end
 
+      # First +keep+ chomp'd lines of +str+, without materializing the whole
+      # buffer into a lines array (#373). Stops scanning after +keep+ lines.
+      def self.head_lines(str, keep)
+        out = []
+        str.each_line do |line|
+          out << line.chomp
+          break if out.size >= keep
+        end
+        out
+      end
+
+      # Line count of +str+ via a single allocation-free newline-BYTE count
+      # (#373): newlines, +1 for a final line with no trailing newline. Used by
+      # both #preview and #truncate to decide over/under cap WITHOUT splitting a
+      # potentially huge buffer into a `.lines` array. Counts on the byte view
+      # (`b`) so a raw, not-yet-scrubbed buffer (invalid UTF-8 / binary tool
+      # output) doesn't raise "invalid byte sequence" — the `\n` byte (0x0A) is
+      # unambiguous regardless of encoding, and `.b` shares the buffer (no copy).
+      def self.line_count(str)
+        return 0 if str.empty?
+
+        bytes = str.b
+        bytes.count("\n") + (bytes.end_with?("\n") ? 0 : 1)
+      end
+
+      # Last +keep+ chomp'd lines of +str+, found by scanning backward from the
+      # end rather than splitting the whole buffer (#373). Slices a bounded tail
+      # of the string by locating the keep-th-from-last newline.
+      def self.tail_lines(str, keep)
+        return [] if keep <= 0
+
+        idx = str.length
+        keep.times do
+          nl = str.rindex("\n", idx - 1)
+          break if nl.nil?
+
+          idx = nl
+        end
+        # idx now sits ON the newline before the kept tail (or 0 if we ran out).
+        slice = str[idx, str.length - idx]
+        slice = slice[1..] if slice.start_with?("\n")
+        slice.to_s.lines.map(&:chomp)
+      end
+
       # Single-line elision to +max+ characters with a trailing ellipsis.
       # Shared by the parent-note tools (AnswerChild/Task/Steer) that all
       # carried a byte-identical private `truncate`. Pure function.
@@ -89,16 +278,44 @@ module Rubino
       # spill.) Pure aside from that injected callback.
       def self.truncate(text, max_bytes:, max_lines:, spill: nil)
         text = text.to_s
+        # Bound PEAK cost BEFORE any whole-buffer work (#373). A 128MB tool
+        # output used to be scrubbed in full (a 128MB copy), then walked twice
+        # by `text.lines` (each a multi-million-element array) just to decide it
+        # was over-cap. Decide over/under with allocation-free passes —
+        # `bytesize` and `count("\n")` — and only ever scrub/slice a BOUNDED
+        # head+tail, never the full buffer. The model-facing cap + spill below
+        # are unchanged; this only stops the materialization blow-up.
         over_bytes = text.bytesize > max_bytes
-        over_lines = text.lines.size > max_lines
-        return text unless over_bytes || over_lines
+        over_lines = line_count(text) > max_lines
+
+        # Under both caps: scrub the (already small) buffer and return. A stray
+        # non-UTF-8 byte (printf '\xe9') OR a NUL (random binary) in SUB-cap
+        # output must still be cleaned, or it crashes JSON.generate / the SQLite
+        # driver and the tool row never persists (lost on --resume).
+        return scrub_utf8(text) unless over_bytes || over_lines
 
+        # Over cap: spill the FULL (raw) output first so nothing is lost, then
+        # shape from bounded head/tail slices. Each slice path scrubs only the
+        # bytes it keeps, so the 128MB buffer is never scrubbed whole.
         spill_path = spill&.call(text)
         text = tail_bias_bytes(text, max_bytes, spill_path) if over_bytes
-        text = tail_bias_lines(text, max_lines, spill_path) if text.lines.size > max_lines
+        # Re-derive the line check on whatever survived the byte pass (the byte
+        # pass already cut to ~max_bytes, so this is now a bounded count).
+        text = scrub_utf8(text) unless over_bytes
+        text = tail_bias_lines(text, max_lines, spill_path) if line_count(text) > max_lines
         text
       end
 
+      # Encoding-scrub + NUL-strip a BOUNDED byteslice (#373). The head/tail
+      # byte path slices BEFORE scrubbing (so the 128MB buffer is never scrubbed
+      # whole); each kept slice still has to be cleaned exactly like scrub_utf8
+      # (invalid bytes dropped, NUL deleted) so JSON/SQLite don't choke.
+      def self.clean_slice(bytes, encoding)
+        s = bytes.to_s.force_encoding(encoding).scrub("")
+        s = s.encode(Encoding::UTF_8) unless s.encoding == Encoding::UTF_8
+        s.include?(NUL) ? s.delete(NUL) : s
+      end
+
       def self.tail_bias_bytes(text, max_bytes, spill_path = nil)
         encoding        = text.encoding
         recover         = spill_path ? " · full output saved to #{spill_path} — read it with offset/limit" : ""
@@ -111,13 +328,13 @@ module Rubino
         # to a simple head truncation (old behavior). Realistic caps go
         # through the head+tail path.
         if tail_budget <= 0
-          truncated = text.byteslice(0, max_bytes).to_s.force_encoding(encoding).scrub("")
+          truncated = clean_slice(text.byteslice(0, max_bytes), encoding)
           tail_note = spill_path ? " · full output: #{spill_path}" : ""
           return "#{truncated}\n... [truncated at #{max_bytes} bytes#{tail_note}]"
         end
 
-        head   = text.byteslice(0, head_budget).to_s.force_encoding(encoding).scrub("")
-        tail   = text.byteslice(-tail_budget, tail_budget).to_s.force_encoding(encoding).scrub("")
+        head   = clean_slice(text.byteslice(0, head_budget), encoding)
+        tail   = clean_slice(text.byteslice(-tail_budget, tail_budget), encoding)
         elided = text.bytesize - head.bytesize - tail.bytesize
         "#{head}#{format(marker_template, elided)}#{tail}"
       end

data/lib/rubino/util/secrets_mask.rb

@@ -33,6 +33,49 @@ module Rubino
         (?<val>"[^"]+"|'[^']+'|(?:Bearer\s+)?[^"'\s]+)
       /xi
 
+      # URL userinfo credentials: `scheme://user:PASSWORD@host`. Masks ONLY the
+      # password, keeping scheme/user/host so the trace still says which
+      # service/account was touched (`postgresql://app:***@db`). The userinfo
+      # username is `[^:@/\s]+` and the password `[^@/\s]+`, both terminating at
+      # the `@`, so a bare `https://host:8080/p` (no `@`), the `host:port` that
+      # follows the `@`, and an IPv6 host `@[::1]:5432` are all left untouched —
+      # only a real `user:pass@` triggers. The unambiguous, industry-standard
+      # form (git/pip redact credentials in URLs exactly this way; RFC 3986
+      # deprecates them outright).
+      URL_USERINFO_RE = %r{
+        (?<scheme>[a-z][a-z0-9+.-]*://)
+        (?<user>[^:@/\s]+)
+        (?<sep>:)
+        (?<pass>[^@/\s]+)
+        (?<at>@)
+      }xi
+
+      # Basic-auth credential pair `-u user:pass` (curl/wget). Unambiguous: the
+      # value carries a colon-separated `user:pass`, so we mask the password half
+      # and keep the username (`-u admin:***`). Both glued (`-uadmin:pw`) and
+      # spaced (`-u admin:pw`) forms match; a bare username with no colon is left
+      # alone (no secret on the line to mask).
+      U_FLAG_CRED_RE = /
+        (?<flag>(?<![\w-])-u)
+        (?<sp>\s*)
+        (?<user>[^\s:'"]+)
+        (?<sep>:)
+        (?<pass>[^\s'"]+)
+      /x
+
+      # Glued DB-client password flag `-p<password>`, scoped to mysql/mariadb
+      # clients ONLY. `-p<val>` is a password there but a PORT/PATH/anything for
+      # most other tools (`ssh -p 22`, `kubectl -p`), so we require BOTH the
+      # value to be GLUED to the flag (`-pSECRET`, no space — mysql's own
+      # convention) AND a mysql-family client word on the same command. A
+      # generic `-p 8080` is never masked, and the spaced `mysql -p` (interactive
+      # prompt) carries no secret on the line so there is nothing to mask.
+      MYSQL_PFLAG_RE = /
+        (?<client>\b(?:mysql|mysqldump|mariadb|mariadb-dump)\b[^\n|;&]*?\s)
+        (?<flag>-p)
+        (?<pass>[^\s'"]+)
+      /xi
+
       MASK = "***"
 
       # True if the given key looks sensitive on its own (used when the
@@ -58,15 +101,35 @@ module Rubino
       # the mask would eat a quote and the rest of the string would look
       # like one long open string.
       def self.mask_inline(text)
-        text.to_s.gsub(INLINE_RE) do
+        masked = text.to_s.gsub(INLINE_RE) do
           m   = Regexp.last_match
           val = m[:val]
-          masked = case val[0]
-                   when '"' then %("#{MASK}")
-                   when "'" then "'#{MASK}'"
-                   else MASK
-                   end
-          "#{m[:key]}#{m[:sep]}#{masked}"
+          inner = case val[0]
+                  when '"' then %("#{MASK}")
+                  when "'" then "'#{MASK}'"
+                  else MASK
+                  end
+          "#{m[:key]}#{m[:sep]}#{inner}"
+        end
+        mask_glued_credentials(masked)
+      end
+
+      # The glued/URL credential forms the keyed INLINE_RE can't see: URL
+      # userinfo passwords, `-u user:pass`, and mysql/mariadb `-p<password>`.
+      # Each keeps the surrounding, non-secret context (scheme/user/host, the
+      # flag, the username) so the trace stays useful while the secret is gone.
+      def self.mask_glued_credentials(text)
+        out = text.gsub(URL_USERINFO_RE) do
+          m = Regexp.last_match
+          "#{m[:scheme]}#{m[:user]}:#{MASK}@"
+        end
+        out = out.gsub(U_FLAG_CRED_RE) do
+          m = Regexp.last_match
+          "#{m[:flag]}#{m[:sp]}#{m[:user]}:#{MASK}"
+        end
+        out.gsub(MYSQL_PFLAG_RE) do
+          m = Regexp.last_match
+          "#{m[:client]}#{m[:flag]}#{MASK}"
         end
       end
 

data/lib/rubino/util/spill_store.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rubino
+  module Util
+    # Lifecycle for the on-disk "spill" artifacts rubino writes outside the
+    # database (#374):
+    #
+    #   * tool-result spills — <home>/tool-results/<call_id>.txt, the full
+    #     pre-truncation output the model can `read` back (ToolExecutor).
+    #   * oversized pastes    — <home>/sessions/<id>/paste_N.txt, a big paste
+    #     the model reads instead of inlining (UI::PasteStore).
+    #
+    # Both were write-only: nothing ever deleted them. A long-running session or
+    # a CI box that runs thousands of large-output tools accumulated these files
+    # FOREVER, and destroying a session (CleanupSessionsJob / Repository#destroy!)
+    # only deleted DB rows, leaving the files orphaned. This module:
+    #
+    #   1. deletes a single session's spill+paste files when it is destroyed
+    #      (#destroy_session_files), and
+    #   2. evicts spill/paste files past an age and/or total-size budget
+    #      (#evict!), called opportunistically and from CleanupSessionsJob.
+    #
+    # All methods are best-effort: an IO error must never take down the agent.
+    module SpillStore
+      # Default eviction policy. Tunable via the cleanup config, but these are
+      # the safe built-ins: drop anything older than the retention window, and
+      # keep the combined on-disk footprint of spills+pastes under the budget by
+      # evicting oldest-first.
+      DEFAULT_MAX_AGE_SECONDS = 7 * 86_400        # 7 days
+      DEFAULT_MAX_TOTAL_BYTES = 512 * 1024 * 1024 # 512 MB
+
+      module_function
+
+      # The directory holding per-call tool-result spills.
+      def tool_results_dir
+        File.join(Rubino.home_path, "tool-results")
+      end
+
+      # The directory holding all per-session subtrees (each session's pastes
+      # live in <sessions>/<id>/paste_N.txt).
+      def sessions_dir
+        File.join(Rubino.home_path, "sessions")
+      end
+
+      # Removes the on-disk spill + paste artifacts owned by +session_id+ when
+      # the session is destroyed (#374). Pastes are session-scoped so the whole
+      # <sessions>/<id> subtree goes; tool-result spills are keyed by call_id, so
+      # the caller passes the session's call_ids (looked up before the DB rows
+      # are deleted) and we remove the matching <tool-results>/<call_id>.txt.
+      # Best-effort; returns nil.
+      def destroy_session_files(session_id, call_ids: [])
+        return if session_id.nil? || session_id.to_s.empty?
+
+        FileUtils.rm_rf(File.join(sessions_dir, session_id.to_s))
+        Array(call_ids).each do |cid|
+          safe = sanitize_call_id(cid)
+          next if safe.nil?
+
+          FileUtils.rm_f(File.join(tool_results_dir, "#{safe}.txt"))
+        end
+        nil
+      rescue StandardError => e
+        Rubino.logger&.warn(event: "spill_store.destroy_failed", error: e.message)
+        nil
+      end
+
+      # Evicts spill + paste files past the age and/or total-size budget. Age
+      # first (drop everything older than max_age), then size (if the survivors
+      # still exceed max_total_bytes, delete oldest-first until under budget).
+      # Empty per-session paste dirs left behind are pruned. Best-effort;
+      # returns the number of files deleted.
+      def evict!(max_age_seconds: DEFAULT_MAX_AGE_SECONDS, max_total_bytes: DEFAULT_MAX_TOTAL_BYTES,
+                 now: Time.now)
+        files   = collect_files
+        deleted = 0
+
+        if max_age_seconds&.positive?
+          cutoff = now - max_age_seconds
+          files.reject! do |f|
+            next false unless f[:mtime] < cutoff
+
+            FileUtils.rm_f(f[:path])
+            deleted += 1
+            true
+          end
+        end
+
+        if max_total_bytes&.positive?
+          total = files.sum { |f| f[:size] }
+          if total > max_total_bytes
+            # Oldest first until back under budget.
+            files.sort_by! { |f| f[:mtime] }
+            files.each do |f|
+              break if total <= max_total_bytes
+
+              FileUtils.rm_f(f[:path])
+              total   -= f[:size]
+              deleted += 1
+            end
+          end
+        end
+
+        prune_empty_session_dirs
+        deleted
+      rescue StandardError => e
+        Rubino.logger&.warn(event: "spill_store.evict_failed", error: e.message)
+        deleted
+      end
+
+      # All spill + paste files as {path:, size:, mtime:} records.
+      def collect_files
+        out = []
+        out.concat(stat_glob(File.join(tool_results_dir, "*.txt")))
+        out.concat(stat_glob(File.join(sessions_dir, "*", "paste_*.txt")))
+        out
+      end
+
+      def stat_glob(pattern)
+        Dir.glob(pattern).filter_map do |path|
+          stat = File.stat(path)
+          next unless stat.file?
+
+          { path: path, size: stat.size, mtime: stat.mtime }
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Removes now-empty per-session paste dirs (a session whose only files
+      # were pastes that got evicted) so the sessions tree doesn't fill with
+      # empty directories. Never touches a dir that still has contents.
+      def prune_empty_session_dirs
+        Dir.glob(File.join(sessions_dir, "*")).each do |dir|
+          next unless File.directory?(dir)
+          next unless (Dir.entries(dir) - %w[. ..]).empty?
+
+          Dir.rmdir(dir)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Mirrors ToolExecutor#spill_full_output's filename sanitization so the
+      # path we delete matches the path that was written.
+      def sanitize_call_id(call_id)
+        id = call_id.to_s.gsub(/[^a-zA-Z0-9_.-]/, "_")
+        id.empty? ? nil : id
+      end
+    end
+  end
+end

data/lib/rubino/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubino
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/rubino/workspace.rb

@@ -21,8 +21,16 @@ module Rubino
       # the same rule Tools::Base#workspace_root has always used, kept as the
       # single source of truth so the @-picker, shell/test cwd, file API and
       # attachment downloader all agree on "the" root.
+      #
+      # terminal.cwd MUST resolve to a String path: a malformed config (e.g. a
+      # YAML `terminal: { cwd: { ... } }` nested mapping) would otherwise hand a
+      # Hash to File.expand_path downstream, which raises "no implicit conversion
+      # of Hash into String" deep in a tool's #call — masking the real outcome
+      # (e.g. a write-denylist refusal) behind an opaque error. Anything that
+      # isn't a non-empty String degrades to the process cwd.
       def primary_root
-        Rubino.configuration&.dig("terminal", "cwd") || Dir.pwd
+        configured = Rubino.configuration&.dig("terminal", "cwd")
+        configured.is_a?(String) && !configured.empty? ? configured : Dir.pwd
       end
 
       # Every allowed root: the primary first, then each added dir, de-duped on