rubik 0.1.0

data/lib/rubik/tools/diagnostic_reporter.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require_relative "../storage/layout"
+
+module Rubik
+  module Tools
+    # Generates empathetic, actionable Elm-compiler-style error diagnostics (Plan 56 D-2).
+    # Combines clear problem statements, context inspection, "Did you mean?" suggestions,
+    # and numbered next steps to optimize LLM self-healing on first attempt.
+    class DiagnosticReporter
+      HEADER_WIDTH = 70
+
+      def self.box_header(title)
+        dashes_len = [HEADER_WIDTH - title.length - 4, 4].max
+        "-- #{title.upcase} #{'-' * dashes_len}"
+      end
+
+      # Elm-style diagnostic when a file path does not exist in workspace.
+      def self.render_file_not_found(path, candidates: [], existing_dir_files: [])
+        lines = [box_header("File Not Found")]
+        lines << "I cannot find the file `#{path}` in the project workspace."
+        lines << ""
+
+        if candidates && !candidates.empty?
+          lines << "Did you mean this?"
+          candidates.each { |c| lines << "    • #{c}" }
+          lines << ""
+        end
+
+        if existing_dir_files && !existing_dir_files.empty?
+          dir_name = File.dirname(path)
+          display_dir = dir_name == "." ? "project root" : "`#{dir_name}/`"
+          lines << "Existing files in #{display_dir}:"
+          existing_dir_files.first(8).each { |f| lines << "    • #{f}" }
+          lines << ""
+        end
+
+        lines << "Actionable Next Steps:"
+        lines << if candidates && !candidates.empty?
+                   "  1. If you meant an existing file, call `read_file(path: '#{candidates.first}')`."
+                 else
+                   "  1. Verify the exact path or explore directory structure using `list_files(path: '#{File.dirname(path)}')`."
+                 end
+        lines << "  2. If you want to create this new file, call `write_file(path: '#{path}', content: '...')`."
+        lines << "  3. To search for code containing this filename, call `grep_search(query: '#{File.basename(path)}')`."
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when target_content is not found in the file or range.
+      def self.render_target_not_found(path, target_content, closest_snippet: nil, closest_range: nil, similarity: nil, start_line: nil, end_line: nil)
+        range_str = start_line || end_line ? " within lines #{start_line || 1}..#{end_line || 'end'}" : ""
+        lines = [box_header("Target Content Not Found")]
+        lines << "I could not find the exact `target_content` in `#{path}`#{range_str}."
+        lines << ""
+        lines << "Target content requested:"
+        lines << format_snippet_box(target_content)
+        lines << ""
+
+        if closest_snippet && !closest_snippet.empty?
+          sim_str = similarity ? " (#{similarity}% similarity)" : ""
+          range_label = closest_range ? "lines #{closest_range.begin}..#{closest_range.end}" : "nearby lines"
+          lines << "Closest matching snippet found at #{range_label}#{sim_str}:"
+          lines << format_snippet_box(closest_snippet)
+          lines << ""
+        end
+
+        suggested_offset = closest_range ? [closest_range.begin - 2, 1].max : [start_line.to_i - 5, 1].max
+        lines << "Actionable Next Steps:"
+        lines << "  1. Call `read_file(path: '#{path}', offset: #{suggested_offset}, limit: 25)` to inspect exact indentation, whitespace, and line content."
+        lines << "  2. Re-run `replace_file_content` with the exact verbatim lines from the file."
+        lines << "  3. Or omit `start_line`/`end_line` if the target content moved elsewhere in the file." if start_line || end_line
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when target_content matches multiple locations.
+      def self.render_target_not_unique(path, target_content, match_count, line_occurrences = [])
+        lines = [box_header("Target Content Not Unique")]
+        occ_str = line_occurrences.empty? ? "" : " at lines: #{line_occurrences.join(', ')}"
+        lines << "The specified `target_content` was found #{match_count} times in `#{path}`#{occ_str}."
+        lines << ""
+        lines << "Target content:"
+        lines << format_snippet_box(target_content)
+        lines << ""
+        lines << "Actionable Next Steps:"
+        lines << "  1. Provide more surrounding context lines in `target_content` to make the match unique."
+        if line_occurrences && line_occurrences.size >= 2
+          first_occ = line_occurrences.first
+          start_hint = [first_occ - 2, 1].max
+          end_hint = first_occ + target_content.to_s.lines.size + 2
+          lines << "  2. Or restrict the search range with `start_line` and `end_line` (e.g. `start_line: #{start_hint}, end_line: #{end_hint}`)."
+        else
+          lines << "  2. Or specify `start_line` and `end_line` to target the exact occurrence."
+        end
+        lines << "  3. If you intentionally want to replace ALL #{match_count} occurrences across the entire file, pass `allow_multiple: true`."
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when a tool name is unrecognized.
+      def self.render_unknown_tool(tool_name, candidate_tools: [], all_tools: [])
+        lines = [box_header("Unknown Tool")]
+        lines << "I cannot find an active tool named `#{tool_name}`."
+        lines << ""
+
+        if candidate_tools && !candidate_tools.empty?
+          lines << "Did you mean one of these?"
+          candidate_tools.each { |c| lines << "    • #{c}" }
+          lines << ""
+        end
+
+        if all_tools && !all_tools.empty?
+          formatted_tools = all_tools.map { |t| "`#{t}`" }.join(", ")
+          lines << "Available direct tools in toolbelt:"
+          lines << "    #{formatted_tools}"
+          lines << ""
+        end
+
+        lines << "💡 Need a specialized capability?"
+        lines << "    You can dynamically create and register your own custom tool at runtime using:"
+        lines << "    `synthesize_tool(name: '#{tool_name.to_s.downcase}', description: '...', code: '->(args) { ... }')`"
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when a symbol definition is not found in AST.
+      def self.render_symbol_not_found(sym_name, candidate_symbols: [])
+        lines = [box_header("Symbol Not Found")]
+        lines << "I could not find the symbol `#{sym_name}` in the AST semantic graph."
+        lines << ""
+
+        if candidate_symbols && !candidate_symbols.empty?
+          lines << "Did you mean one of these?"
+          candidate_symbols.each { |s| lines << "    • #{s}" }
+          lines << ""
+        end
+
+        lines << "Actionable Next Steps:"
+        lines << "  1. Search for partial matches using `search_symbols(query: '#{sym_name.to_s[0..4]}')`."
+        lines << "  2. Search for code occurrences across the workspace with `grep_search(query: '#{sym_name}')`."
+        lines << "  3. Inspect a specific file outline with `get_outline(file_path: '...')`."
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when a shell/sandbox command fails.
+      def self.render_command_failed(cmd, exit_code, stderr, suggestions: [])
+        lines = [box_header("Command Execution Failed")]
+        lines << "Command `#{cmd}` failed with exit code #{exit_code}."
+        lines << ""
+        if stderr && !stderr.to_s.strip.empty?
+          lines << "Output / Error:"
+          lines << format_snippet_box(stderr.to_s.strip)
+          lines << ""
+        end
+
+        if suggestions && !suggestions.empty?
+          lines << "Actionable Next Steps:"
+          suggestions.each_with_index { |s, idx| lines << "  #{idx + 1}. #{s}" }
+        end
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when operating system permissions prevent file/directory access (Errno::EACCES).
+      def self.render_permission_denied(path, operation: "read", reason: nil)
+        lines = [box_header("Permission Denied")]
+        reason_str = reason ? " (#{reason})" : " (Errno::EACCES)"
+        op_text = operation.to_s == "read" ? "access" : operation.to_s
+        lines << "I cannot #{op_text} `#{path}` due to operating system permission restrictions#{reason_str}."
+        lines << ""
+        lines << "Actionable Next Steps:"
+        lines << "  1. If this is a scratch or temporary directory, allow it via REPL: `!allow #{path}`"
+        lines << "  2. Ensure the process has proper OS #{operation} permissions for this directory."
+        lines << "  3. Target a specific accessible subfolder using `list_files(path: 'accessible_dir')`."
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when path traversal is blocked outside allowed workspace roots.
+      def self.render_traversal_blocked(path, allowed_roots: [], allowed_exts: []) # rubocop:disable Lint/UnusedMethodArgument -- arayüz kwarg'i korunuyor
+        lines = [box_header("Path Access Restricted (Sandbox Gate)")]
+        lines << "Access to `#{path}` was blocked because it is outside the project workspace."
+        lines << ""
+
+        roots = Array(allowed_roots)
+        unless roots.empty?
+          lines << "Configured Allowed Roots:"
+          roots.each do |root_info|
+            if root_info.is_a?(Hash)
+              tag = root_info[:primary] ? "[PRIMARY]" : "[ALLOWED]"
+              note = root_info[:zero_ast] ? " (Zero-AST)" : ""
+              lines << "    • #{tag} #{root_info[:path]}#{note}"
+            else
+              lines << "    • #{root_info}"
+            end
+          end
+          lines << ""
+        end
+
+        lines << "Actionable Next Steps:"
+        lines << "  1. Use a path relative to the project root (e.g. 'lib', 'src') or explore with `list_files`."
+        lines << "  2. To allow transient I/O and sandbox access to this folder without AST bloat, run:"
+        lines << "     `!allow #{path}`"
+        lines << "  3. To add it as a full workspace root with AST indexing, run:"
+        lines << "     `!workspace add #{path} [--rw]`"
+
+        # Canonical-route hint (incident #1): a blocked path inside the
+        # central Rubik storage can be read through its rubik:// route —
+        # no sandbox widening needed. Best effort; empty outside storage.
+        hints = Rubik::Storage::Layout.storage_route_hints(path)
+        unless hints.empty?
+          lines << "  4. This path is inside the Rubik central storage; read the same content through its canonical route (no sandbox change needed):"
+          hints.each { |hint| lines << "     `read_file #{hint}`" }
+        end
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic when malformed or invalid UTF-8 byte sequences are detected.
+      def self.render_encoding_warning(source, sample_snippet: nil)
+        lines = [box_header("Encoding Warning (Malformed UTF-8)")]
+        lines << "Malformed or invalid UTF-8 byte sequences detected in `#{source}`."
+        lines << "The input has been automatically sanitized with lossless replacement characters."
+        lines << ""
+
+        if sample_snippet && !sample_snippet.to_s.empty?
+          lines << "Sanitized Sample Preview:"
+          lines << format_snippet_box(sample_snippet)
+          lines << ""
+        end
+
+        lines << "Actionable Next Steps:"
+        lines << "  1. Ensure source files and command inputs are encoded in standard UTF-8."
+        lines << "  2. For binary or non-text files, use dedicated binary inspection or base64 decoding."
+
+        lines.join("\n")
+      end
+
+      # Elm-style diagnostic guidance for LLM context window utilization and token management.
+      def self.render_context_status_guidance(stats, token_breakdown: {})
+        lines = [box_header("Context Window & Token Guidance")]
+        stats_hash = stats.is_a?(Hash) ? stats : {}
+        model_name = stats_hash[:model] || stats_hash["model"] || "active model"
+        used_tokens = stats_hash[:consumed_tokens] || stats_hash[:estimated_tokens] || stats_hash["consumed_tokens"] || 0
+        limit_tokens = stats_hash[:context_limit] || stats_hash[:usable_capacity] || stats_hash["context_limit"] || 32_768
+        pct = limit_tokens.positive? ? ((used_tokens.to_f / limit_tokens) * 100).round(1) : 0.0
+
+        lines << "Current Context Utilization: #{used_tokens} / #{limit_tokens} tokens (#{pct}%) for `#{model_name}`"
+        lines << ""
+
+        breakdown_hash = token_breakdown.is_a?(Hash) ? token_breakdown : {}
+        unless breakdown_hash.empty?
+          lines << "Token Breakdown:"
+          breakdown_hash.each do |k, v|
+            lines << "    • #{k}: #{v} tokens"
+          end
+          lines << ""
+        end
+
+        lines << "Actionable Next Steps:"
+        if pct >= 80.0
+          lines << "  1. Context window is nearly full (>=80%). Run `!context compact` to prune older conversation turns."
+          lines << "  2. Switch to a higher-capacity model using `!model default <provider>/<model>`."
+          lines << "  3. Drop unnecessary indexed files using `!context drop <path>`."
+        elsif pct >= 50.0
+          lines << "  1. Context utilization is moderate (>=50%). Use `!context stats` to monitor token growth."
+          lines << "  2. Consider running `!context compact` before lengthy multi-step goal loops."
+        else
+          lines << "  1. Context window is healthy with ample headroom (<50%)."
+          lines << "  2. Continue normal interactions or add context with `!context add <path>`."
+        end
+
+        lines.join("\n")
+      end
+
+      def self.format_snippet_box(text)
+        text.to_s.lines.map { |l| "    #{l.chomp}" }.join("\n")
+      end
+    end
+  end
+end

data/lib/rubik/tools/fuzzy_matcher.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+begin
+  require "diff/lcs"
+rescue LoadError
+  # fallback if not yet installed in some minimal environments
+end
+
+module Rubik
+  module Tools
+    # Provides fast, stdlib-powered spelling suggestions and closest-subsequence
+    # matching for Elm-style actionable diagnostics (Plan 56 D-1).
+    class FuzzyMatcher
+      # Returns the top candidates closest to `query` using DidYouMean::SpellChecker
+      # and Levenshtein similarity ranking.
+      #
+      # @param query [String] Search query or misspelled token
+      # @param candidates [Array<String>] Dictionary of valid identifiers
+      # @param limit [Integer] Maximum number of suggestions to return
+      # @return [Array<String>] Sorted list of closest matches
+      # Single source of truth for the candidate-score cutoff in best_matches
+      # and the length-bound prune inside similarity_ratio - keep them tied.
+      MATCH_THRESHOLD = 0.35
+
+      def self.best_matches(query, candidates, limit: 3)
+        return [] if query.to_s.strip.empty? || candidates.nil? || candidates.empty?
+
+        str_query = query.to_s.downcase.strip
+        str_candidates = candidates.map { |c| c.to_s.downcase.strip }.reject(&:empty?).uniq
+
+        # Direct spell check via stdlib if available
+        dym_matches = []
+        if defined?(DidYouMean::SpellChecker)
+          checker = DidYouMean::SpellChecker.new(dictionary: str_candidates)
+          dym_matches = checker.correct(str_query)
+        end
+
+        # Substring inclusions get prioritized
+        substring_matches = str_candidates.select { |c| c.include?(str_query) || str_query.include?(c) }
+
+        # Rank all candidates by Levenshtein similarity ratio
+        # PERF: pass min_threshold to prune candidates whose length difference
+        # prevents them from ever reaching MATCH_THRESHOLD
+        scored_pairs = str_candidates.map do |cand|
+          score = similarity_ratio(str_query, cand, min_threshold: MATCH_THRESHOLD)
+          [cand, score]
+        end
+        scored = scored_pairs.select { |_c, score| score >= MATCH_THRESHOLD }
+                             .sort_by { |_c, score| -score }
+                             .map(&:first)
+
+        (dym_matches + substring_matches + scored).uniq.first(limit)
+      end
+
+      # Computes normalized string similarity ratio in [0.0, 1.0].
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @param min_threshold [Float, nil] Optional minimum acceptable score for early upper-bound pruning
+      # @return [Float] Similarity score (1.0 = exact match)
+      def self.similarity_ratio(str1, str2, min_threshold: nil)
+        s1 = str1.to_s.downcase
+        s2 = str2.to_s.downcase
+        return 1.0 if s1 == s2
+        return 0.0 if s1.empty? || s2.empty?
+
+        l1 = s1.length
+        l2 = s2.length
+        max_len = l1 > l2 ? l1.to_f : l2.to_f
+
+        if min_threshold
+          len_diff = (l1 - l2).abs
+          # PERF: Upper-bound check on string length difference; if max achievable ratio < min_threshold, prune edit distance calculation
+          return 0.0 if (1.0 - (len_diff / max_len)) < min_threshold
+        end
+
+        dist = levenshtein_distance(s1, s2)
+        [1.0 - (dist / max_len), 0.0].max
+      end
+
+      # Computes Levenshtein edit distance between two strings using standard dynamic programming.
+      def self.levenshtein_distance(str1, str2)
+        return DidYouMean::Levenshtein.distance(str1.to_s, str2.to_s) if defined?(DidYouMean::Levenshtein) && DidYouMean::Levenshtein.respond_to?(:distance)
+
+        s1 = str1.to_s.chars
+        s2 = str2.to_s.chars
+        return s2.length if s1.empty?
+        return s1.length if s2.empty?
+
+        d = Array.new(s1.length + 1) { |i| i }
+
+        s2.each_with_index do |char2, j|
+          new_d = [j + 1]
+          s1.each_with_index do |char1, i|
+            cost = char1 == char2 ? 0 : 1
+            new_d << [
+              d[i + 1] + 1,       # deletion
+              new_d[i] + 1,       # insertion
+              d[i] + cost         # substitution
+            ].min
+          end
+          d = new_d
+        end
+
+        d.last
+      end
+
+      # Finds the closest matching line window in `file_content` for `target_content`
+      # using Longest Common Subsequence (LCS) analysis (Plan 56 D-1/D-3).
+      #
+      # @param target_content [String] The snippet being searched
+      # @param file_content [String] Full file content
+      # @return [Hash, nil] { snippet:, range:, similarity: } or nil if no good match
+      def self.find_closest_subsequence(target_content, file_content)
+        t_raw = target_content.to_s.gsub("\r\n", "\n")
+        f_raw = file_content.to_s.gsub("\r\n", "\n")
+        t_lines = t_raw.lines.map(&:rstrip)
+        f_lines = f_raw.lines.map(&:rstrip)
+        return nil if t_lines.empty? || f_lines.empty?
+
+        k = t_lines.size
+        best_score = 0.0
+        best_range = 1..1
+        best_i = nil
+        best_window_len = nil
+
+        # PERF: memoize raw file lines once before loop to avoid re-splitting inside loop on score updates
+        f_raw_lines = f_raw.lines
+
+        (0...(f_lines.size)).each do |i|
+          window_len = [k, f_lines.size - i].min
+          # PERF: Array#[start, len] slice avoids Range object allocation inside hot loop
+          window = f_lines[i, window_len]
+
+          matches, total =
+            if defined?(Diff::LCS) && Diff::LCS.respond_to?(:LCS)
+              [Diff::LCS.LCS(t_lines, window).size, [t_lines.size, window.size].max]
+            else
+              # Fallback line matching
+              [(0...[t_lines.size, window.size].min).count { |idx| t_lines[idx] == window[idx] },
+               [t_lines.size, window.size].max]
+            end
+          score = total.positive? ? (matches.to_f / total) : 0.0
+
+          if k == 1 && window_len == 1
+            char_score = similarity_ratio(t_lines.first, window.first)
+            score = [score, char_score].max
+          end
+
+          next unless score > best_score
+
+          best_score = score
+          best_range = (i + 1)..(i + window_len)
+          best_i = i
+          best_window_len = window_len
+        end
+
+        return nil if best_score < 0.25 || best_i.nil?
+
+        # PERF: defer snippet string construction until after best match selection
+        best_snippet = f_raw_lines[best_i, best_window_len].join
+
+        {
+          snippet: best_snippet.strip,
+          range: best_range,
+          similarity: (best_score * 100).round
+        }
+      end
+    end
+  end
+end

data/lib/rubik/tools/native_search.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "open3"
+
+begin
+  require "tty/which"
+rescue LoadError
+  nil
+end
+
+module Rubik
+  module Tools
+    # ripgrep shellout for GrepSearchTool's native fast path. The module is
+    # side-effect free: every spawn is call-scoped (stdin closed immediately,
+    # streams closed, process reaped — killed first when the result cap cuts
+    # the stream short, else rg would deadlock on a full stdout pipe) — no
+    # persistent process, thread, or listener outlives a search, so no
+    # dispose inverse is owed.
+    #
+    # Windows stdin trap (measured, Plan 52 §2.4): rg spawned with a pipe
+    # stdin decides from a heuristic to search STDIN instead of "./" and
+    # exits with zero results. The path argument is therefore ALWAYS explicit
+    # and stdin is closed right after spawn; both are regression-tested.
+    #
+    # rg runs parallel: measured on a 5.000-file tree, `-j 1` triples the
+    # scan time (247 → 864 ms) while pruning globs are free. Consequence:
+    # when the result cap cuts the stream, WHICH subset of matches survives
+    # follows rg's arrival order — the merged result is still sorted
+    # (file, line) and correctly capped, and byte-identical reproducibility
+    # remains available via tools.native: off.
+    module NativeSearch
+      BASE_FLAGS = ["--no-messages", "--no-heading", "-n", "--hidden"].freeze
+
+      @mutex = Mutex.new
+      @rg_path = nil
+
+      class << self
+        # Rubik prunes these subtrees itself; the target repo's .gitignore
+        # may not, so the rg-side and Ruby-side file universes stay
+        # identical. Lazily built: Rubik::Context::Scanner may not be loaded
+        # at require time (tools load before context in some entry points).
+        def prune_globs
+          @prune_globs ||= Rubik::Context::Scanner::DEFAULT_IGNORES.flat_map { |p| ["-g", "!#{p}"] }.freeze
+        end
+
+        # Resolved rg executable, or nil. RUBIK_RG_PATH beats PATH lookup
+        # (blank treated as unset); memoized (reset_memoization! for tests).
+        def rg_path(env: ENV)
+          @mutex.synchronize do
+            @rg_path ||= begin
+              override = env["RUBIK_RG_PATH"]
+              override.nil? || override.strip.empty? ? resolve_via_which : override
+            end
+          end
+        end
+
+        def available?(env: ENV)
+          !rg_path(env: env).nil?
+        end
+
+        # ENV beats config; anything other than "off" (auto/on/unknown)
+        # attempts the native path first.
+        def enabled?(config_value, env: ENV)
+          mode = env["RUBIK_NATIVE"] || config_value || "auto"
+          mode.to_s.strip.downcase != "off"
+        end
+
+        # Runs rg and parses "path:line:content" rows into GrepSearchTool's
+        # match hashes. Returns nil when rg could not be trusted (missing
+        # binary, spawn failure, non-0/1 exit such as a regex-usage error) —
+        # the caller must fall back to its Ruby path rather than render a
+        # possibly-wrong result.
+        #
+        # The argument count is inherent to a search request: one pattern,
+        # three scope knobs, a cap, and two injection hooks (env/runner for
+        # test isolation). Grouping them into a bag-hash would hide the
+        # contract without reducing real complexity.
+        def search(pattern, root_dir:, path: ".", glob: nil, case_sensitive: false, max_results: 50, env: ENV, runner: nil)
+          rg = rg_path(env: env)
+          return nil if rg.nil? && runner.nil?
+
+          argv = [rg, *BASE_FLAGS]
+          argv << "-i" unless case_sensitive
+          argv += ["-g", glob] if glob && !glob.empty?
+          argv += prune_globs
+          argv += ["-e", pattern.to_s, path]
+
+          matches = []
+          trusted = run_spawn(argv, root_dir: root_dir, runner: runner) do |raw|
+            m = parse_line(raw, root_dir: root_dir)
+            next false unless m
+
+            matches << m
+            next true if matches.size >= max_results
+
+            false
+          end
+          trusted == true ? matches : nil
+        end
+
+        def reset_memoization!
+          @mutex.synchronize { @rg_path = nil }
+        end
+
+        # "path:12:content". The SPLIT anchors on the FIRST :digits: boundary
+        # and the candidate path is existence-checked against root_dir: a
+        # matched content line like `ts = 12:34:56` must not hijack the line
+        # number (a greedy split would attribute 34 as the line). If no
+        # boundary yields a real file — a path that itself contains :digits:
+        # — fall back to the greedy split. Both the path and the content are
+        # scrubbed to valid UTF-8: rg emits raw bytes, and a broken-encoding
+        # file must not poison JSON payloads downstream.
+        def parse_line(raw, root_dir: nil)
+          match = raw.match(/\A(.+?):(\d+):(.*)\z/m)
+          return nil unless match
+
+          file = scrub_utf8(match[1])
+          if root_dir && !File.exist?(File.join(root_dir, file.tr("\\", "/")))
+            match = raw.match(/\A(.+):(\d+):(.*)\z/m)
+            return nil unless match
+
+            file = scrub_utf8(match[1])
+          end
+
+          content = scrub_utf8(match[3])
+          content = "#{content[0..500]}... [line truncated, #{content.length} chars total]" if content.length > 500
+
+          {
+            file: file.tr("\\", "/").sub(%r{\A\./}, ""),
+            line: match[2].to_i,
+            content: content
+          }
+        end
+
+        private
+
+        def resolve_via_which
+          defined?(TTY::Which) ? TTY::Which.which("rg") : nil
+        end
+
+        # Yields each stdout line; the block's truthy return marks an early
+        # cap. On cap the rg process is killed BEFORE waiter.value, else a
+        # capped rg keeps filling its stdout pipe with no reader and the wait
+        # would deadlock. Without a cap, rg exits 0 (matches) / 1 (no
+        # matches) — trusted. Exit 2 (usage/regex error) and spawn failures
+        # are untrusted → nil → caller falls back.
+        def run_spawn(argv, root_dir:, runner:, &)
+          if runner
+            runner.call(argv, root_dir).each(&)
+            return true
+          end
+
+          cap_reached = false
+          Open3.popen3(*argv, chdir: root_dir, err: File::NULL) do |stdin, stdout, _stderr, waiter|
+            stdin.close
+            stdout.each_line do |raw|
+              cap_reached = yield raw.chomp
+              break if cap_reached
+            end
+            begin
+              Process.kill("KILL", waiter.pid) if cap_reached
+            rescue StandardError
+              nil
+            end
+
+            status = waiter.value
+            cap_reached || (status.exited? && [0, 1].include?(status.exitstatus))
+          end
+        rescue StandardError
+          false
+        end
+
+        def scrub_utf8(str)
+          str = str.dup.force_encoding(Encoding::UTF_8) if str.encoding == Encoding::ASCII_8BIT
+          str.valid_encoding? ? str : str.scrub
+        end
+      end
+    end
+  end
+end

data/lib/rubik/tools/output.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Rubik
+  module Tools
+    # A String tool output that carries an explicit error classification.
+    #
+    # Why a String subclass: the historical builtin-tool contract returns
+    # plain Strings, and StepExecutor inferred success/failure by sniffing
+    # ERROR_PREFIXES — real failures ("AST graph is not available", "LSP
+    # manager is not connected", argument-validation messages) were silently
+    # labeled status="ok" in the tool_result envelope. ToolOutput keeps every
+    # existing string consumer (tests, Truncator, formatters) working while
+    # letting StepExecutor's existing `respond_to?(:error?)` branch classify
+    # the result correctly.
+    class ToolOutput < String
+      def self.ok(text)
+        new(text.to_s, is_error: false)
+      end
+
+      def self.error(text)
+        new(text.to_s, is_error: true)
+      end
+
+      # Display-output contract: the full text is meant for the USER'S
+      # terminal, not for the model's context. StepExecutor emits it as a
+      # :user_output event and feeds only the short stub back into history.
+      def self.display(text, stub:)
+        new(text.to_s, is_error: false, display_stub: stub)
+      end
+
+      def initialize(text = "", is_error: false, display_stub: nil)
+        super(text)
+        @is_error = is_error ? true : false
+        @display_stub = display_stub
+      end
+
+      def error?
+        @is_error
+      end
+
+      def ok?
+        !@is_error
+      end
+
+      def user_display?
+        !@display_stub.nil?
+      end
+
+      def display_stub
+        @display_stub.to_s
+      end
+    end
+  end
+end