rails-ai-context 5.32.2 → 5.34.0

data/lib/rails_ai_context/tools/base_tool.rb

@@ -4,7 +4,7 @@ require "did_you_mean"
 
 require "mcp"
 require "active_support"
-require "active_support/number_helper"
+require "bigdecimal"
 
 module RailsAiContext
   module Tools
@@ -70,6 +70,16 @@ module RailsAiContext
       # for thread safety in multi-threaded servers (e.g., Puma).
       SHARED_CACHE = { mutex: Mutex.new }
 
+      # What a server last saw of its app's files (a Fingerprinter::Snapshot),
+      # when the check now running began, and when the last finished one
+      # did. The snapshot is nil until a server starts, so a process that is
+      # no server (the CLI, rake) never walks the tree. `stale_code` is what a
+      # server that cannot reload found changed since it loaded it
+      # (CodeReloader.changed_code), and `compile_cached` what a server that
+      # can found rewritten where Bootsnap's compile cache cannot see it
+      # (CodeReloader.compile_cached).
+      FILE_CHECK = { mutex: Mutex.new, done: ConditionVariable.new, snapshot: nil, running: nil, finished: nil, stale_code: nil, compile_cached: nil }
+
       # Session-level context tracking. Lets AI avoid redundant queries
       # by recording what tools have been called with what params.
       # In-memory only - resets on server restart.
@@ -80,8 +90,11 @@ module RailsAiContext
       # Mcp-Session-Id gets its own bucket and one client's history stays out
       # of another's.
       # A plain Hash, not one with a default block: a default block writes on
-      # lookup, so merely reading a session's history created it.
-      SESSION_CONTEXT = { mutex: Mutex.new, queries: {} }
+      # lookup, so merely reading a session's history created it. `dropped`
+      # counts, per session, the queries its record no longer keeps. `asked`
+      # numbers queries in the order first asked, which a timestamp cannot
+      # tell apart within one second.
+      SESSION_CONTEXT = { mutex: Mutex.new, queries: {}, dropped: {}, asked: 0 }
 
       DEFAULT_SESSION = :default
 
@@ -91,6 +104,10 @@ module RailsAiContext
       # MAX_SESSIONS is the one least likely to ask about its own history.
       MAX_SESSIONS = 100
       MAX_SESSION_ID_LENGTH = 200
+      # What one session's record holds is capped the same way: its latest
+      # queries, each param kept as an answer echoes it. A client sending a
+      # 100 KB argument on every call otherwise grew the record without end.
+      MAX_SESSION_QUERIES = 200
 
       # One row of the generated tool guide, declared beside the tool's own
       # description so adding a tool touches one file. `order` fixes where the
@@ -119,6 +136,15 @@ module RailsAiContext
           RailsAiContext.configuration
         end
 
+        # Every tool's arguments are checked through ArgumentSchema, so an
+        # app whose locale files do not load still gets argument errors.
+        def input_schema(*args)
+          return super if args.empty?
+
+          value = args.first
+          super(value.is_a?(Hash) ? ArgumentSchema.new(value) : value)
+        end
+
         # A bare `Rails.env` raises NameError under --no-boot or early boot death.
         def rails_env_name
           RailsAiContext.environment_name
@@ -145,12 +171,9 @@ module RailsAiContext
             ttl = RailsAiContext.configuration.cache_ttl
 
             # Fast path: within TTL window, trust the cache and skip the
-            # fingerprint walk entirely. Fingerprinter stats every *.rb file
-            # in WATCHED_DIRS (plus, in dev-mode path: installs, every file
-            # in the gem's own lib/ tree) - measured at ~12ms per call in
-            # dev mode, ~0.5ms in production. Since LiveReload fires
-            # reset_all_caches! on actual file-change events, stale-cache
-            # risk during a short TTL window is already covered.
+            # fingerprint walk entirely. A server has already dropped it if a
+            # file changed: each call asks the files at its start
+            # (refresh_if_files_changed!).
             if SHARED_CACHE[:context] && (now - SHARED_CACHE[:timestamp]) < ttl
               return SHARED_CACHE[:context].deep_dup
             end
@@ -182,7 +205,8 @@ module RailsAiContext
           end
         end
 
-        # Reset the shared cache. Used by LiveReload to invalidate on file change.
+        # Every cache that describes the app's files, dropped once a call's
+        # check finds them moved.
         def reset_all_caches!
           reset_cache!
           session_reset!
@@ -190,6 +214,95 @@ module RailsAiContext
           PathResolver.clear_code_roots
         end
 
+        # Called by every server as it starts - stdio, HTTP, the endpoints
+        # inside the app - live reload or not. From here on each call checks
+        # the files against what they are now.
+        #
+        # A server that cannot read its files still serves; it only goes
+        # without the check.
+        def check_files_per_call!(app)
+          snapshot = Fingerprinter::Snapshot.new(app.root)
+          snapshot.changed?
+          FILE_CHECK[:mutex].synchronize { FILE_CHECK.merge!(snapshot: snapshot, running: nil, finished: nil) }
+        rescue StandardError => e
+          RailsAiContext.debug_fail(e, nil, label: "check_files_per_call!")
+        end
+
+        # Before a call reads anything, it sees every edit made before it
+        # began: when a file moved, the app's code is reloaded on the
+        # calling thread and the caches dropped. Live reload only tells
+        # clients: `listen` delivers a change after its debounce, a second
+        # and a half on, and an agent that edits a model and asks about it
+        # at once was answered from before the edit.
+        #
+        # The check is a stat of each watched directory and file
+        # (Fingerprinter::Snapshot): about a millisecond on a small app, about
+        # 30 at 10,000 files. Only a check that began after a call did can
+        # stand in for that call's own, so two calls one after the other each
+        # check, and concurrent calls wait for one check together. A tool
+        # another tool calls is part of the first call and asks nothing.
+        #
+        # Outside SHARED_CACHE's mutex, unlike the TTL walk: a code reload
+        # waits for running calls to finish, and they may be waiting on it.
+        #
+        # An app that cannot reload keeps what reflection read at boot, so
+        # instead the call notes which of its files changed since they were
+        # loaded, for every answer to name (stale_code_note). One that can
+        # notes the files whose reload Bootsnap answers with their code from
+        # before the last write.
+        def refresh_if_files_changed!
+          return if RunCache.active?
+
+          snapshot = await_check(Process.clock_gettime(Process::CLOCK_MONOTONIC))
+          return unless snapshot
+
+          begin
+            changed = snapshot.changed?
+            react_to_change(snapshot) if changed
+            done = true
+          ensure
+            FILE_CHECK[:mutex].synchronize do
+              FILE_CHECK[:finished] = FILE_CHECK[:running] if done
+              FILE_CHECK[:running] = nil
+              FILE_CHECK[:done].broadcast
+            end
+          end
+        rescue StandardError => e
+          RailsAiContext.debug_fail(e, nil, label: "refresh_if_files_changed!")
+        end
+
+        # Nil once a check that began after the call arrived has finished,
+        # since it saw every edit made before; otherwise the snapshot, for
+        # this call to check with. A call that finds a check running waits
+        # for it, and then for the next if that one began too early.
+        private def await_check(arrived)
+          FILE_CHECK[:mutex].synchronize do
+            loop do
+              return nil unless FILE_CHECK[:snapshot]
+              return nil if FILE_CHECK[:finished] && FILE_CHECK[:finished] >= arrived
+
+              unless FILE_CHECK[:running]
+                FILE_CHECK[:running] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                return FILE_CHECK[:snapshot]
+              end
+              FILE_CHECK[:done].wait(FILE_CHECK[:mutex])
+            end
+          end
+        end
+
+        private def react_to_change(snapshot)
+          if CodeReloader.reloadable?
+            # A request the app serves already ran Rails' own reloader.
+            CodeReloader.reload! unless CodeReloader.inside_app_executor?
+            cached = CodeReloader.compile_cached(snapshot.same_stat_rewrites)
+            FILE_CHECK[:mutex].synchronize { FILE_CHECK[:compile_cached] = cached }
+          else
+            changed = CodeReloader.changed_code
+            FILE_CHECK[:mutex].synchronize { FILE_CHECK[:stale_code] = changed }
+          end
+          reset_all_caches!
+        end
+
         # ── Session context helpers ──────────────────────────────────────
 
         # Run a block against one conversation's session record. The HTTP
@@ -223,27 +336,59 @@ module RailsAiContext
         end
 
         def session_record(tool_name, params, summary = nil)
+          params = recorded_params(params)
           SESSION_CONTEXT[:mutex].synchronize do
             bucket = touch_session
             evict_oldest_sessions
             key = session_key(tool_name, params)
-            existing = bucket[key]
+            # Taken out and put back, so the bucket runs least recently used
+            # first and the cap below drops the query asked longest ago.
+            existing = bucket.delete(key)
             if existing
               existing[:call_count] = (existing[:call_count] || 1) + 1
               existing[:last_timestamp] = Time.now.iso8601
               existing[:summary] = summary if summary
+              bucket[key] = existing
             else
               bucket[key] = {
                 tool: tool_name.to_s,
                 params: params,
                 call_count: 1,
+                asked: SESSION_CONTEXT[:asked] += 1,
                 timestamp: Time.now.iso8601,
                 summary: summary
               }
+              drop_oldest_queries(bucket)
             end
           end
         end
 
+        # How many queries the calling session's record has dropped to stay
+        # within MAX_SESSION_QUERIES.
+        def session_dropped
+          SESSION_CONTEXT[:mutex].synchronize { SESSION_CONTEXT[:dropped].fetch(current_session, 0) }
+        end
+
+        # Each param as an answer would echo it, so the record keeps no more
+        # of a 100 KB argument than a reply does.
+        def recorded_params(params)
+          return echo_input(params) if params.is_a?(String)
+          return params unless params.is_a?(Hash)
+
+          params.transform_values { |value| value.to_s.length > ECHO_LENGTH ? echo_input(value) : value }
+        end
+        private :recorded_params
+
+        # Called with the mutex held.
+        def drop_oldest_queries(bucket)
+          dropped = SESSION_CONTEXT[:dropped]
+          while bucket.size > MAX_SESSION_QUERIES
+            bucket.shift
+            dropped[current_session] = dropped.fetch(current_session, 0) + 1
+          end
+        end
+        private :drop_oldest_queries
+
         # Deep copies: the entries stay live inside the record and keep being
         # mutated by later calls, so handing the originals out would let a
         # caller's snapshot change under it.
@@ -253,9 +398,22 @@ module RailsAiContext
           end
         end
 
+        # Every conversation's record: for a change that makes every earlier
+        # answer stale (live reload), and for a test that starts clean.
         def session_reset!
           SESSION_CONTEXT[:mutex].synchronize do
             SESSION_CONTEXT[:queries].clear
+            SESSION_CONTEXT[:dropped].clear
+          end
+        end
+
+        # The calling conversation's record alone, which is what a client's
+        # `action: "reset"` asks for. One HTTP process serves every client,
+        # and clearing them all let one client empty the others' records.
+        def current_session_reset!
+          SESSION_CONTEXT[:mutex].synchronize do
+            SESSION_CONTEXT[:queries].delete(current_session)
+            SESSION_CONTEXT[:dropped].delete(current_session)
           end
         end
 
@@ -274,7 +432,7 @@ module RailsAiContext
         # Called with the mutex held.
         def evict_oldest_sessions
           queries = SESSION_CONTEXT[:queries]
-          queries.shift while queries.size > MAX_SESSIONS
+          SESSION_CONTEXT[:dropped].delete(queries.shift.first) while queries.size > MAX_SESSIONS
         end
         private :evict_oldest_sessions
 
@@ -307,7 +465,7 @@ module RailsAiContext
         def not_found_response(type, name, available, recovery_tool: nil, note: nil)
           # Don't suggest the exact same string the user typed - that's useless
           suggestions = find_closest_matches(name, available) - [ name ]
-          lines = [ "#{type} '#{name}' not found." ]
+          lines = [ "#{type} '#{echo_input(name)}' not found." ]
           if suggestions.size == 1
             lines << "Did you mean '#{suggestions.first}'?"
           elsif suggestions.any?
@@ -372,8 +530,8 @@ module RailsAiContext
         def response_text(response)
           first = response.content.first
           text = first.is_a?(Hash) ? first[:text].to_s : ""
-          # The composing tool's own response carries the tier banner, once.
-          (banner = static_tier_banner) ? text.gsub(banner, "") : text
+          # The composing tool's own response carries the banners, once.
+          [ static_tier_banner, stale_code_banner ].compact.reduce(text) { |stripped, banner| stripped.gsub(banner, "") }
         end
 
         # One-line banner listing introspectors that failed during context
@@ -472,6 +630,35 @@ module RailsAiContext
           "\n\n---\n_#{note}_"
         end
 
+        # The same, once app code changed under a server that cannot reload:
+        # what reflection read is the code as it booted, whatever the file
+        # says now. Validations and callbacks are read off the source, so
+        # they follow the edit; associations and enums do not. A server that
+        # reloads says the same of a file whose reload Bootsnap answered with
+        # the code from before its last save (CodeReloader.compile_cached).
+        def stale_code_banner
+          note = stale_code_note
+          note && "\n\n---\n_#{note}_"
+        end
+
+        def stale_code_note
+          if (files = FILE_CHECK[:stale_code])&.any?
+            "App code changed since this server booted (#{named_files(files)}); RAILS_ENV=#{RailsAiContext.environment_name} " \
+              "does not reload code, so what reflection reads, such as associations and enums, is as of boot. " \
+              "Restart the server to see the #{files.size == 1 ? "edit" : "edits"}."
+          elsif (files = FILE_CHECK[:compile_cached])&.any?
+            "App code was saved twice within one second at the same size (#{named_files(files)}); Bootsnap's " \
+              "compile cache knows a file by its size and the second it was saved, so what reflection reads, such as " \
+              "associations and enums, may be from the earlier save. Save the #{files.size == 1 ? "file" : "files"} " \
+              "again a second later, or start the server with DISABLE_BOOTSNAP_COMPILE_CACHE=1."
+          end
+        end
+
+        def named_files(files)
+          files.size > 3 ? "#{files.first(3).join(", ")} and #{files.size - 3} more" : files.join(", ")
+        end
+        private :named_files
+
         # The banner without its markdown wrapper, so a JSON body can carry
         # the same sentence under a key instead of a footer that would stop it
         # parsing.
@@ -486,7 +673,7 @@ module RailsAiContext
           else reason ? "App boot failed (#{reason})" : "Static mode"
           end
           "[STATIC] #{headline}. Serving static analysis; runtime-only data is marked " \
-            "[UNAVAILABLE]. Run `rails-ai-context doctor` for details."
+            "[UNAVAILABLE]. Run `#{RailsAiContext.doctor_command}` for details."
         end
 
         # Tools that only make sense against a booted app must refuse in the
@@ -500,7 +687,7 @@ module RailsAiContext
           remedy = case RailsAiContext.static_kind
           when :requested then "Rerun without `--no-boot`."
           when :source_only then "This tree has no `config/environment.rb`; add one (or run from the app root) for runtime data."
-          else "Fix the boot failure (see `rails-ai-context doctor`)."
+          else "Fix the boot failure (see `#{RailsAiContext.doctor_command}`)."
           end
           text_response(
             "[UNAVAILABLE: static tier] #{capability} requires a booted Rails app" \
@@ -520,6 +707,21 @@ module RailsAiContext
           find_closest_matches(input, available).first
         end
 
+        # Longer than any model, controller, table or file name an app has.
+        MAX_NAME_LENGTH = 256
+        ECHO_LENGTH = 80
+
+        # The caller's input as an answer repeats it: a 100 KB argument came
+        # back whole in a "not found", a 100,321-character reply.
+        def echo_input(value)
+          text = value.to_s
+          text.length > ECHO_LENGTH ? "#{text[0, ECHO_LENGTH]}... (#{text.length} characters)" : text
+        end
+
+        def name_too_long?(value)
+          value.to_s.length > MAX_NAME_LENGTH
+        end
+
         # Every name that matches as well as the best one does. A bare
         # `ReportsController` names three real controllers under different
         # namespaces, and answering with one of them arbitrarily hides the
@@ -530,6 +732,9 @@ module RailsAiContext
           # so it would otherwise surface an arbitrary "Did you mean" suggestion
           # for input that isn't a typo at all - just missing.
           return [] if input.to_s.strip.empty?
+          # No name is this long, and spell-checking a 100 KB string against
+          # every model took seconds to find nothing.
+          return [] if input.to_s.length > MAX_NAME_LENGTH
 
           exact = exact_matches(input, available)
           return exact if exact.any?
@@ -746,6 +951,9 @@ module RailsAiContext
             return "skip_callback :#{event}, :#{kind}, #{callback_target(callback[:method])}#{callback_options_tail(callback[:options])}"
           end
 
+          # A broadcast macro is its own declaration: the call is the line the file holds.
+          return callback[:source].to_s.strip.gsub(/\s+/, " ") if callback[:runs]
+
           name = callback[:name] || callback[:type]
           method = callback[:method].to_s
           target = inline_block_callback?(method) ? "do" : callback_target(method)
@@ -813,10 +1021,12 @@ module RailsAiContext
         # the text itself when untruncated) so callers can attach a short trailing
         # note that must survive truncation instead of being cut off with the tail.
         # In static tier, the tier banner rides along on the same mechanism so
-        # every response - caller-suffixed or not - ends with it.
+        # every response - caller-suffixed or not - ends with it, and so does
+        # the note that app code changed under a server that cannot reload.
         def text_response(text, suffix: nil)
-          suffix = [ suffix, static_tier_banner ].compact.join
+          suffix = [ suffix, static_tier_banner, stale_code_banner ].compact.join
           suffix = nil if suffix.empty?
+          text = served_hints(text)
 
           record_call(text)
 
@@ -825,29 +1035,133 @@ module RailsAiContext
             truncated = text[0...max]
             truncated += "\n\n---\n_Response truncated (#{text.length} chars). Use `detail:\"summary\"` for an overview, or filter by a specific item (e.g. `table:\"users\"`)._"
             truncated += suffix if suffix
-            MCP::Tool::Response.new([ { type: "text", text: truncated } ])
+            MCP::Tool::Response.new([ { type: "text", text: cli_form(truncated) } ])
           else
             text += suffix if suffix
-            MCP::Tool::Response.new([ { type: "text", text: text } ])
+            MCP::Tool::Response.new([ { type: "text", text: cli_form(text) } ])
+          end
+        end
+
+        # A call to one of this gem's tools as an answer writes it:
+        # `rails_get_schema(table:"posts")`. Under tool_mode :cli no MCP server
+        # is set up, so the answer names the command that runs instead, as the
+        # context files do; a lone `detail:"summary"` hint becomes `detail=summary`.
+        MCP_CALL = /\b(rails_\w+)\(([^()]*)\)/
+        PARAM_HINT = /`((?:\w+:(?:"[^"`]*"|[\w.]+)(?:,\s*)?)+)`/
+
+        # A `_Next:` hint points at other tools, one pointer per tool, joined
+        # by ` | ` on one line or onto lines of their own. A tool skip_tools
+        # turned off is no next step, so its pointer goes, and a hint left
+        # with none goes whole. Every answer passes here, so no tool has to
+        # check the served set itself.
+        def served_hints(text)
+          return text unless text.is_a?(String) && text.include?("_Next: ")
+
+          skipped = RailsAiContext::Server.skipped_tools
+          return text if skipped.empty?
+
+          lines = text.split("\n", -1)
+          kept = []
+          index = 0
+          while index < lines.size
+            block = [ lines[index] ]
+            if block.first.start_with?("_Next: ")
+              block << lines[index += 1] while lines[index + 1]&.start_with?(" | ")
+              hint = served_hint(block, skipped)
+              if hint
+                kept.concat(hint)
+              elsif kept.last == "" && lines[index + 1].to_s.empty?
+                kept.pop
+              end
+            else
+              kept << block.first
+            end
+            index += 1
+          end
+          kept.join("\n")
+        rescue StandardError => e
+          RailsAiContext.debug_fail(e, text, label: "served_hints")
+        end
+
+        # The hint's lines with the pointers to skipped tools taken out; nil
+        # when none is left.
+        def served_hint(block, skipped)
+          body = block.join("\n").delete_prefix("_Next: ")
+          closing = body[/\.?_\z/].to_s
+          pointers = body.delete_suffix(closing).split(/\n? \| /)
+          served = pointers.reject { |pointer| skipped.include?(pointer[/\brails_\w+/]) }
+          return block if served.size == pointers.size
+          return nil if served.empty?
+
+          "_Next: #{served.join(block.size > 1 ? "\n | " : " | ")}#{closing}".split("\n")
+        end
+        private :served_hint
+
+        def cli_form(text)
+          return text unless RailsAiContext.configuration.tool_mode == :cli && text.is_a?(String)
+
+          names = BaseTool.registered_tools.map { |tool| tool.tool_name.to_s }
+          converted = text.gsub(MCP_CALL) do
+            whole = Regexp.last_match(0)
+            name, args = Regexp.last_match(1), Regexp.last_match(2)
+            params = names.include?(name) && cli_params(args)
+            next whole unless params
+
+            short = name.sub(/\Arails_get_/, "").sub(/\Arails_/, "")
+            command = RailsAiContext::InstallMode.tool_command(short)
+            [ command, *params ].join(" ")
+          end
+          converted.gsub(PARAM_HINT) { (params = cli_params(Regexp.last_match(1))) ? "`#{params.join(' ')}`" : Regexp.last_match(0) }
+        rescue StandardError => e
+          RailsAiContext.debug_fail(e, text, label: "cli_form")
+        end
+
+        # `model:"User", files:["a.rb","b.rb"]` as `model=User files=a.rb,b.rb`,
+        # quoted for a shell where a value needs it; nil when the text is not
+        # keyword arguments.
+        def cli_params(args)
+          return [] if args.strip.empty?
+
+          call = RailsAiContext::AstCache.parse_string("f(#{args})").value.statements.body.first
+          hash = call.is_a?(Prism::CallNode) ? call.arguments&.arguments&.first : nil
+          return nil unless hash.is_a?(Prism::KeywordHashNode)
+
+          hash.elements.map do |pair|
+            return nil unless pair.is_a?(Prism::AssocNode) && pair.key.is_a?(Prism::SymbolNode)
+
+            value = case (node = pair.value)
+            when Prism::StringNode, Prism::SymbolNode then node.unescaped
+            when Prism::ArrayNode then node.elements.map { |e| e.respond_to?(:unescaped) ? e.unescaped : e.slice }.join(",")
+            else node.slice
+            end
+            "#{pair.key.unescaped}=#{value.match?(%r{\A[\w.,/:@+-]*\z}) && !value.empty? ? value : "\"#{value.gsub(/["\\$`]/) { "\\#{Regexp.last_match(0)}" }}\""}"
           end
         end
 
         # Key the static-tier note rides under in a JSON body. Underscored the
         # way JsonBudget's own report key is, so a reader tells it from data.
         STATIC_TIER_KEY = "_static_tier"
+        STALE_CODE_KEY = "_stale_code"
 
-        # A JSON body has to parse, so it cannot take the markdown banner and
+        # A JSON body has to parse, so it cannot take the markdown banners and
         # cannot be sliced at the response cap: JsonBudget drops whole
-        # elements instead, and the tier note rides under a reserved key.
+        # elements instead, and the notes ride under reserved keys.
         def json_response(data)
-          note = static_tier_note
-          data = data.merge(STATIC_TIER_KEY => note) if note && data.is_a?(Hash)
-
-          text = JsonBudget.generate(data, RailsAiContext.configuration.max_tool_response_chars)
+          text = JsonBudget.generate(json_notes(data), RailsAiContext.configuration.max_tool_response_chars)
           record_call(text)
           MCP::Tool::Response.new([ { type: "text", text: text } ])
         end
 
+        # The notes a text answer ends with, under their keys: that the answer
+        # is static analysis, and that what reflection read is not the code
+        # the files hold now. A tool's JSON answer and a resource's body both
+        # carry them, so neither reads as current when it is not.
+        def json_notes(data)
+          return data unless data.is_a?(Hash)
+
+          data.merge({ STATIC_TIER_KEY => static_tier_note, STALE_CODE_KEY => stale_code_note }.compact)
+        end
+
         # Helper: wrap text in an MCP::Tool::Response flagged as an error
         # (isError: true) so MCP clients and the CLI treat the call as failed
         # (non-zero exit). Mirrors the SafeCall rescue wrapper. Use for an
@@ -856,12 +1170,8 @@ module RailsAiContext
         # would not answer. Guidance and "found nothing" stay informational
         # via text_response and empty_response.
         def error_response(text)
-          # A failed call must not leak its recorded params into the next
-          # call's session entry.
-          Thread.current[:rails_ai_context_call_params] = nil
-          banner = static_tier_banner
-          text += banner if banner
-          MCP::Tool::Response.new([ { type: "text", text: text } ], error: true)
+          text += [ static_tier_banner, stale_code_banner ].compact.join
+          MCP::Tool::Response.new([ { type: "text", text: cli_form(text) } ], error: true)
         end
 
         private
@@ -882,22 +1192,32 @@ module RailsAiContext
           Array(RailsAiContext::Payload.section(cached_context, :i18n)&.dig(:available_locales)).map(&:to_s)
         end
 
-        # English units whatever the locale, unless the app offers no English at all.
+        STORAGE_UNITS = %w[Bytes KB MB GB TB PB EB ZB].freeze
+
+        # number_to_human_size's English output, without I18n: an app's backend can raise after a failed boot.
         def human_size(bytes)
-          ActiveSupport::NumberHelper.number_to_human_size(bytes.to_i, locale: :en)
-        rescue I18n::InvalidLocale
-          ActiveSupport::NumberHelper.number_to_human_size(bytes.to_i)
+          bytes = bytes.to_i
+          return "#{bytes} #{bytes == 1 ? "Byte" : "Bytes"}" if bytes < 1024
+
+          exponent = [ (Math.log(bytes) / Math.log(1024)).to_i, STORAGE_UNITS.size - 1 ].min
+          value = bytes.to_f / (1024**exponent)
+          places = 3 - (Math.log10(value) + 1).floor
+          rounded = format("%.#{[ places, 0 ].max}f", BigDecimal(value.to_s).round(places, :half_up))
+          "#{rounded.sub(/(\.\d*?)0+\z/, '\1').delete_suffix(".")} #{STORAGE_UNITS[exponent]}"
         end
 
         # Every answered call is recorded so session_context(action:"status")
-        # can list it. SessionContext itself is skipped to avoid recursion.
+        # can list it: the call SafeCall says the client made, once, with its
+        # own params. A tool another tool called answers it, not the client.
+        # SessionContext itself is skipped to avoid recursion.
         def record_call(text)
+          call = Thread.current[:rails_ai_context_call]
+          return unless call && call[:tool].equal?(self) && !call[:recorded]
           return unless respond_to?(:tool_name) && tool_name != "rails_session_context"
 
           summary = text.lines.first&.strip&.truncate(80)
-          params = Thread.current[:rails_ai_context_call_params] || {}
-          session_record(tool_name, params, summary)
-          Thread.current[:rails_ai_context_call_params] = nil
+          session_record(tool_name, call[:params], summary)
+          call[:recorded] = true
         end
 
         def session_key(tool_name, params)
@@ -935,8 +1255,8 @@ module RailsAiContext
         # @return [String, nil] the refusal for a path the caller may not read
         def unsafe_path_message(path)
           case RailsAiContext::SafePath.locate(path.to_s, under: rails_app.root.to_s).refusal
-          when :traversal, :outside then "Path not allowed: #{path}"
-          when :sensitive then "Path not allowed: #{path} (sensitive file)"
+          when :traversal, :outside then "Path not allowed: #{echo_input(path)}"
+          when :sensitive then "Path not allowed: #{echo_input(path)} (sensitive file)"
           end
         end
 
@@ -986,13 +1306,14 @@ module RailsAiContext
 
         # Whether the loaded model class defines the method: true, false, or
         # nil when there is no loaded class to ask (the static tier, a name
-        # that is not a model). A private method counts as defined, since the
-        # error for calling one says so rather than "undefined".
+        # that is not a model, a model whose file does not compile, which is
+        # never required to ask it). A private method counts as defined, since
+        # the error for calling one says so rather than "undefined".
         def live_method_defined?(receiver, method_name)
           return nil if RailsAiContext.static_tier?
           return nil unless defined?(ActiveRecord::Base)
 
-          klass = receiver.to_s.safe_constantize
+          klass = Introspectors::EagerLoad.constant(receiver)
           return nil unless klass.is_a?(Class) && klass < ActiveRecord::Base
 
           define_attribute_methods(klass)

data/lib/rails_ai_context/tools/brakeman_guard.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Tools
+    # Brakeman's vendored ruby_parser runs `$DEBUG = true if ENV["DEBUG"]`
+    # when it loads, and with $DEBUG on Ruby prints every exception raised
+    # anywhere in the process, rescued or not: a `DEBUG=1` run, which this
+    # gem's own error text tells users to try, printed some 440 lines of them.
+    # Loading and running brakeman with DEBUG out of its sight, and putting
+    # $DEBUG back after, leaves that switch the user's.
+    module BrakemanGuard
+      module_function
+
+      def quietly
+        hidden = ENV.delete("DEBUG")
+        saved = $DEBUG
+        yield
+      ensure
+        $DEBUG = saved
+        ENV["DEBUG"] = hidden if hidden
+      end
+    end
+  end
+end