ruby-skill-bench 1.0.1 → 1.2.0

data/lib/skill_bench/services/junit_formatter.rb

@@ -4,39 +4,89 @@ require 'cgi'
 
 module SkillBench
   module Services
-    # Formats evaluation results as JUnit XML.
+    # Formats evaluation results as JUnit XML for CI consumption.
+    #
+    # Two entry points share the same per-result verdict/score logic:
+    # {.format} emits a single-result suite (one <testcase>), while
+    # {.format_batch} aggregates many results into one suite so a batch
+    # `skill-bench run --all` produces a single JUnit artifact.
     class JUnitFormatter
-      # Format result as JUnit XML.
+      # classname attribute applied to every emitted <testcase>.
+      CLASSNAME = 'SkillBench'
+
+      # Format a single result as a JUnit XML document.
       #
       # Supports both legacy format (result[:pass]) and modern DeltaReport format.
       #
       # @param result [Hash] Eval result.
       # @return [String] JUnit XML-formatted string.
       def self.format(result)
+        suite([result])
+      end
+
+      # Format an aggregate batch envelope as one JUnit XML document.
+      #
+      # Emits a single <testsuite> with one <testcase> per result, adding a
+      # <failure> child for every failing eval.
+      #
+      # @param aggregate [Hash] Aggregate envelope with a :results array.
+      # @return [String] JUnit XML-formatted string.
+      def self.format_batch(aggregate)
+        suite(aggregate[:results] || [])
+      end
+
+      # Builds a <testsuite> wrapping one <testcase> per result.
+      #
+      # @param results [Array<Hash>] Per-eval result envelopes.
+      # @return [String] JUnit XML-formatted string.
+      def self.suite(results)
+        failures = results.count { |result| !passing?(result) }
+        cases = results.map { |result| testcase(result) }.join("\n")
+        <<~XML
+          <?xml version="1.0"?>
+          <testsuite name="#{CLASSNAME}" tests="#{results.size}" failures="#{failures}">
+          #{cases}
+          </testsuite>
+        XML
+      end
+      private_class_method :suite
+
+      # Renders one <testcase> element (indented two spaces) for a result.
+      #
+      # @param result [Hash] A single-eval result envelope.
+      # @return [String] A <testcase> XML fragment.
+      def self.testcase(result)
+        name = CGI.escapeHTML(result[:eval_name].to_s)
+        return %(  <testcase name="#{name}" classname="#{CLASSNAME}"/>) if passing?(result)
+
+        score = CGI.escapeHTML(score_for(result).to_s)
+        [
+          %(  <testcase name="#{name}" classname="#{CLASSNAME}">),
+          %(    <failure message="Score: #{score}">Eval failed</failure>),
+          '  </testcase>'
+        ].join("\n")
+      end
+      private_class_method :testcase
+
+      # Whether a result passed (DeltaReport verdict or legacy :pass).
+      #
+      # @param result [Hash] A single-eval result envelope.
+      # @return [Boolean] true when the eval passed.
+      def self.passing?(result)
+        report = result.dig(:response, :report)
+        report.respond_to?(:verdict) ? report.verdict : result[:pass]
+      end
+      private_class_method :passing?
+
+      # The score reported for a failing eval.
+      #
+      # @param result [Hash] A single-eval result envelope.
+      # @return [Object] DeltaReport context_total or legacy :score.
+      def self.score_for(result)
         report = result.dig(:response, :report)
-        verdict = report.respond_to?(:verdict) ? report.verdict : result[:pass]
-        eval_name = CGI.escapeHTML(result[:eval_name].to_s)
-
-        if verdict
-          <<~XML
-            <?xml version="1.0"?>
-            <testsuite name="SkillBench" tests="1" failures="0">
-              <testcase name="#{eval_name}" classname="SkillBench"/>
-            </testsuite>
-          XML
-        else
-          score = report.respond_to?(:context_total) ? report.context_total : result[:score]
-          escaped_score = CGI.escapeHTML(score.to_s)
-          <<~XML
-            <?xml version="1.0"?>
-            <testsuite name="SkillBench" tests="1" failures="1">
-              <testcase name="#{eval_name}" classname="SkillBench">
-                <failure message="Score: #{escaped_score}">Eval failed</failure>
-              </testcase>
-            </testsuite>
-          XML
-        end
+        report.respond_to?(:context_total) ? report.context_total : result[:score]
       end
+      private_class_method :score_for
     end
   end
 end

data/lib/skill_bench/services/provider_resolver.rb

@@ -51,11 +51,14 @@ module SkillBench
       private
 
       def resolve_provider
-        config = SkillBench::Models::Config.load
+        config = SkillBench::Models::Config.loaded
         provider = config.to_provider
         return provider if provider
 
-        warn 'Config load failed, using mock provider'
+        # Explicit `{"provider":"mock"}` is a valid choice, not a load failure,
+        # so it falls through to the mock provider without a warning. A missing
+        # provider key (genuine misconfiguration) still warns below.
+        warn 'Config load failed, using mock provider' unless config.mock?
         MOCK_PROVIDER.new('mock', 'mock', 'mock', {})
       rescue JSON::ParserError, ArgumentError, Errno::ENOENT => e
         # Config parsing/validation errors or missing config file - fall back to mock

data/lib/skill_bench/services/response_cache.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module SkillBench
+  module Services
+    # Content-addressed, in-memory cache for LLM responses.
+    #
+    # The cache is opt-in and disabled by default. When enabled it lets repeated,
+    # identical LLM requests reuse a previously computed response instead of
+    # hitting the network again. The canonical example is `compare`, which runs
+    # the skill-less baseline twice with identical inputs.
+    #
+    # The backing store is a process-lifetime {Hash} keyed by a stable SHA-256
+    # digest of the request, so the same logical request always maps to the same
+    # entry regardless of hash-key ordering. Access to the store is serialized
+    # with a mutex so concurrent callers (e.g. {Parallel}-driven agents) cannot
+    # corrupt it or double-store a key.
+    class ResponseCache
+      # Environment variable that opts caching on when set to a truthy value.
+      ENV_FLAG = 'SKILL_BENCH_CACHE'
+
+      # Raw env values treated as "on".
+      TRUTHY_VALUES = %w[1 true yes on].freeze
+
+      # Guards every read/write of the shared store. Concurrent agents/judges run
+      # on separate threads; without this, the membership check and the write in
+      # {fetch} could interleave and store a key more than once.
+      MUTEX = Mutex.new
+
+      class << self
+        # Whether response caching is currently enabled.
+        #
+        # Enabled when {ENV_FLAG} is set to a truthy value (one of
+        # {TRUTHY_VALUES}); disabled when unset or set to anything else.
+        #
+        # @return [Boolean] true when caching is on
+        def enabled?
+          raw = ENV.fetch(ENV_FLAG, '').to_s.strip.downcase
+          TRUTHY_VALUES.include?(raw)
+        end
+
+        # Computes a stable content-addressed cache key for a request.
+        #
+        # The inputs are assembled into a canonical structure (hash keys sorted
+        # and stringified recursively) and hashed, so semantically identical
+        # requests always produce the same digest. Request-affecting provider
+        # configuration (endpoint/base URL/etc.) is included so two providers that
+        # share a name but target different endpoints never collide.
+        #
+        # @param provider [Symbol, String] Resolved provider identifier
+        # @param model [String, nil] Model name
+        # @param system_prompt [String] System prompt
+        # @param messages [Array<Hash>] Conversation messages
+        # @param tools [Array<Hash>, nil] Tool definitions, when present
+        # @param temperature [Float, nil] Sampling temperature, when present
+        # @param provider_config [Hash] Request-affecting provider settings such as
+        #   base_url, request_path, endpoint, location, project_id, api_version
+        # @return [String] Hex-encoded SHA-256 digest of the canonical request
+        def key(provider:, model:, system_prompt:, messages:, tools: nil, temperature: nil, provider_config: {})
+          payload = {
+            provider: provider.to_s,
+            model: model,
+            system_prompt: system_prompt,
+            messages: messages,
+            tools: tools,
+            temperature: temperature,
+            provider_config: provider_config
+          }
+          Digest::SHA256.hexdigest(JSON.generate(canonicalize(payload)))
+        end
+
+        # Returns the cached value for a key, computing and storing it on a miss.
+        #
+        # The value is computed outside the lock so requests for distinct keys run
+        # concurrently; the store read and the store write are each serialized by
+        # {MUTEX}, and a missing key is written exactly once (first writer wins).
+        #
+        # @param key [String] Cache key from {key}
+        # @yield Computes the value to cache when the key is absent
+        # @yieldreturn [Object] The value to cache
+        # @return [Object] The cached value (existing on a hit, freshly stored on a miss)
+        def fetch(key)
+          hit = MUTEX.synchronize { store[key] }
+          return hit unless hit.nil?
+
+          value = yield
+          MUTEX.synchronize { store[key] ||= value }
+        end
+
+        # Removes every cached entry.
+        #
+        # @return [void]
+        def clear
+          MUTEX.synchronize { store.clear }
+        end
+
+        private
+
+        # The process-lifetime backing store.
+        #
+        # @return [Hash{String => Object}] digest => cached response
+        def store
+          @store ||= {}
+        end
+
+        # Recursively rewrites a value into a stable form for serialization.
+        #
+        # Hashes get their keys stringified and sorted so that key ordering does
+        # not affect the resulting digest; arrays and scalars are preserved.
+        #
+        # @param value [Object] The value to canonicalize
+        # @return [Object] A canonical, order-stable copy of the value
+        def canonicalize(value)
+          case value
+          when Hash
+            value
+              .sort_by { |entry| entry.first.to_s }
+              .each_with_object({}) { |(name, val), acc| acc[name.to_s] = canonicalize(val) }
+          when Array
+            value.map { |element| canonicalize(element) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skill_bench/services/runner_service.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'parallel'
 require_relative '../evaluation/runner'
 require_relative 'eval_resolver'
 require_relative 'skill_resolver_service'
@@ -10,6 +11,7 @@ require_relative 'context_loader_service'
 require_relative 'judge_params_builder'
 require_relative 'error_response_builder'
 require_relative 'trend_recorder_service'
+require_relative 'cost_calculator'
 require_relative 'output_formatter'
 
 module SkillBench
@@ -61,13 +63,11 @@ module SkillBench
         provider = provider_result[:provider]
         config = provider_result[:config]
 
-        baseline_output = run_baseline_agent(evaluation, provider, config)
-        return agent_error_result(baseline_output, 'baseline', evaluation, provider) if baseline_output[:status] == :error
-
         skill_context = ContextLoaderService.call(skills)
         return empty_context_error_result(evaluation, provider) if skill_context.strip.empty?
 
-        context_output = run_context_agent(evaluation, skills, skill_context, provider, config)
+        baseline_output, context_output = run_agents_concurrently(evaluation, skills, skill_context, provider, config)
+        return agent_error_result(baseline_output, 'baseline', evaluation, provider) if baseline_output[:status] == :error
         return agent_error_result(context_output, 'context', evaluation, provider) if context_output[:status] == :error
 
         context = EvaluationContext.new(
@@ -111,6 +111,29 @@ module SkillBench
         AgentSpawnerService.call(evaluation, context_prompt, provider, config)
       end
 
+      # Runs the baseline and context agents concurrently.
+      #
+      # The two runs are independent: each spawns its own `Dir.mktmpdir`
+      # sandbox and uses a per-call client, and neither reads the other's
+      # state. The work is I/O-bound (HTTP + subprocess), so threads release
+      # the GIL and the agent phase is bound by the slower run instead of the
+      # sum of both. The skill context is built once by the caller and passed
+      # in, so no skill-dependent work is duplicated or moved into the baseline.
+      #
+      # @param evaluation [SkillBench::Models::Eval] The eval being run
+      # @param skills [Array<SkillBench::Models::Skill>] Resolved skills
+      # @param skill_context [String] Combined skill context, built once pre-fork
+      # @param provider [Object] The resolved provider
+      # @param config [Hash, nil] Provider config
+      # @return [Array(Hash, Hash)] Baseline and context outputs, in that order
+      def run_agents_concurrently(evaluation, skills, skill_context, provider, config)
+        runs = [
+          -> { run_baseline_agent(evaluation, provider, config) },
+          -> { run_context_agent(evaluation, skills, skill_context, provider, config) }
+        ]
+        Parallel.map(runs, in_threads: runs.size, &:call)
+      end
+
       def evaluate_and_record_trend(context)
         evaluation = context.evaluation
         provider = context.provider
@@ -133,11 +156,16 @@ module SkillBench
         trend_result = TrendRecorderService.call(result, eval_name, skill_names)
         return enrich_error_result(trend_result, evaluation, provider) unless trend_result[:success]
 
+        tokens = aggregate_usage(context.baseline_output, context.context_output)
+        cost = CostCalculator.call(usage: tokens, model: agent_model(config, provider))
+
         {
           success: true,
           eval_name: eval_name,
           skill_name: skill_names.join(', '),
           provider_name: provider.name,
+          tokens: tokens,
+          cost: cost,
           response: result[:response].merge(
             trend: trend_result[:trend],
             baseline_iterations: context.baseline_output[:iterations] || [],
@@ -145,6 +173,62 @@ module SkillBench
           )
         }
       end
+
+      # Sums the token usage of the baseline and context agent runs.
+      #
+      # Judge-side usage is not yet threaded through (the judge lives under the
+      # untouched `clients/` boundary), so this is scoped to agent usage.
+      #
+      # @param baseline_output [Hash] The baseline agent output (carries :usage).
+      # @param context_output [Hash] The context agent output (carries :usage).
+      # @return [Hash] Combined prompt/completion/total token counts.
+      def aggregate_usage(baseline_output, context_output)
+        add_usage(
+          add_usage(empty_usage, baseline_output[:usage]),
+          context_output[:usage]
+        )
+      end
+
+      # A zeroed token-usage accumulator.
+      #
+      # @return [Hash] Usage hash with prompt/completion/total token counts set to zero.
+      def empty_usage
+        { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+      end
+
+      # Adds one usage hash onto a running total.
+      #
+      # @param total [Hash] The running usage total.
+      # @param usage [Hash, nil] A run's usage hash (may be nil or empty).
+      # @return [Hash] A new summed usage hash.
+      def add_usage(total, usage)
+        usage ||= {}
+        {
+          prompt_tokens: total[:prompt_tokens] + token_count(usage, :prompt_tokens),
+          completion_tokens: total[:completion_tokens] + token_count(usage, :completion_tokens),
+          total_tokens: total[:total_tokens] + token_count(usage, :total_tokens)
+        }
+      end
+
+      # Reads a token count from a usage hash, tolerating string keys.
+      #
+      # @param usage [Hash] The usage hash.
+      # @param key [Symbol] The usage key (e.g. :prompt_tokens).
+      # @return [Integer] The token count, or zero when absent.
+      def token_count(usage, key)
+        (usage[key] || usage[key.to_s] || 0).to_i
+      end
+
+      # Resolves the model name used for pricing from config, falling back to the provider LLM.
+      #
+      # @param config [Hash, nil] Provider config.
+      # @param provider [Object] The resolved provider.
+      # @return [String] The model name (e.g. "gpt-4o").
+      def agent_model(config, provider)
+        return provider.llm unless config.is_a?(Hash)
+
+        config[:model] || config['model'] || provider.llm
+      end
     end
   end
 end

data/lib/skill_bench/services/summary_formatter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module SkillBench
+  module Services
+    # Builds a compact JSON summary of a batch run for CI gating.
+    #
+    # Surfaces the aggregate pass/fail counts plus rolled-up token and cost
+    # usage and the single worst skill-vs-baseline delta across the batch, so
+    # a CI job can gate on (and archive) one machine-readable artifact.
+    class SummaryFormatter
+      # Format an aggregate batch envelope as a pretty JSON summary string.
+      #
+      # @param aggregate [Hash] Aggregate envelope with :results and :summary.
+      # @return [String] Pretty-printed JSON summary.
+      def self.format(aggregate)
+        new(aggregate).format
+      end
+
+      # @param aggregate [Hash] Aggregate envelope with :results and :summary.
+      def initialize(aggregate)
+        @results = aggregate[:results] || []
+        @summary = aggregate[:summary] || {}
+      end
+
+      # Builds the JSON summary document.
+      #
+      # @return [String] Pretty-printed JSON summary.
+      def format
+        JSON.pretty_generate(
+          passed: summary[:passed],
+          failed: summary[:failed],
+          total: summary[:total],
+          tokens: total_tokens,
+          cost: total_cost,
+          worst_delta: worst_delta
+        )
+      end
+
+      private
+
+      attr_reader :results, :summary
+
+      # Sums total_tokens across every result, treating missing usage as 0.
+      #
+      # @return [Integer] Aggregate token count.
+      def total_tokens
+        results.sum { |result| tokens_for(result) }
+      end
+
+      # Reads a single result's total token count.
+      #
+      # @param result [Hash] A single-eval result envelope.
+      # @return [Integer] total_tokens, or 0 when absent.
+      def tokens_for(result)
+        tokens = result[:tokens] || {}
+        tokens[:total_tokens] || tokens['total_tokens'] || 0
+      end
+
+      # Sums non-nil per-result costs.
+      #
+      # @return [Float, nil] Total cost, or nil when no result reports a cost.
+      def total_cost
+        costs = results.filter_map { |result| result[:cost] }
+        costs.empty? ? nil : costs.sum
+      end
+
+      # Finds the eval with the smallest skill-vs-baseline delta.
+      #
+      # @return [Hash, nil] {:eval_name, :delta} for the worst eval, or nil
+      #   when no result carries a delta report.
+      def worst_delta
+        scored = results.filter_map { |result| delta_entry(result) }
+        scored.min_by { |entry| entry[:delta] }
+      end
+
+      # Builds a {eval_name, delta} entry for a result with a delta report.
+      #
+      # @param result [Hash] A single-eval result envelope.
+      # @return [Hash, nil] Entry hash, or nil when the report lacks deltas.
+      def delta_entry(result)
+        report = result.dig(:response, :report)
+        return nil unless report.respond_to?(:context_total) && report.respond_to?(:baseline_total)
+
+        { eval_name: result[:eval_name], delta: report.context_total - report.baseline_total }
+      end
+    end
+  end
+end

data/lib/skill_bench/services/template_registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require_relative '../dimension'
 require_relative 'template_registry/category_data'
 
 module SkillBench
@@ -21,6 +22,24 @@ module SkillBench
       TEMPLATE_TYPES = %i[task_md criteria_json skill_md].freeze
       CATEGORIES = REGISTRY.keys.freeze
 
+      # Score weight per core scoring dimension. Keyed by the canonical
+      # +SkillBench::DEFAULT_DIMENSIONS+ names so scaffolded criteria can never
+      # drift from the names the runtime loader requires; values sum to 100.
+      CRITERIA_DIMENSION_SCORES = {
+        'correctness' => 30,
+        'skill_adherence' => 25,
+        'code_quality' => 20,
+        'test_coverage' => 15,
+        'documentation' => 10
+      }.freeze
+
+      # Canonical dimension descriptions keyed by name, sourced from the runtime defaults.
+      CORE_DIMENSION_DESCRIPTIONS = SkillBench::DEFAULT_DIMENSIONS.to_h { |dimension| [dimension.name, dimension.description] }.freeze
+
+      # Top-level thresholds emitted with scaffolded criteria.
+      CRITERIA_PASS_THRESHOLD = 70
+      CRITERIA_MINIMUM_DELTA = 10
+
       # @param template_type [Symbol, String] Template type (:task_md, :criteria_json, :skill_md)
       # @param category [Symbol, String] Category (:crud, :api, :background_job, etc.)
       # @param variables [Hash{Symbol, String => String}] Variables for interpolation
@@ -105,21 +124,36 @@ module SkillBench
         MARKDOWN
       end
 
+      # Builds runtime-loadable scoring criteria for the category.
+      #
+      # Emits the five core dimensions required by {SkillBench::Criteria}
+      # (+correctness+, +skill_adherence+, +code_quality+, +test_coverage+,
+      # +documentation+) with integer +max_score+ values summing to 100, plus
+      # the top-level +pass_threshold+ and +minimum_delta+ the loader expects.
+      # Category-specific flavor lives only in the dimension descriptions.
+      #
+      # @return [String] Pretty-printed criteria JSON.
       def build_criteria_json
         JSON.pretty_generate(
           category: category.to_s,
-          dimensions: [
-            { name: 'correctness', weight: 30, pass_threshold: 70 },
-            { name: 'adherence',   weight: 25, pass_threshold: 60 },
-            { name: 'quality',     weight: 20, pass_threshold: 60 },
-            { name: 'tests',       weight: 15, pass_threshold: 80 },
-            { name: 'docs',        weight: 10, pass_threshold: 50 }
-          ],
-          minimum_delta: 5,
-          category_specific: category_data.criteria
+          dimensions: criteria_dimensions,
+          pass_threshold: CRITERIA_PASS_THRESHOLD,
+          minimum_delta: CRITERIA_MINIMUM_DELTA
         )
       end
 
+      # @return [Array<Hash>] Core dimensions with integer +max_score+ summing to 100.
+      def criteria_dimensions
+        focus = category_data.criteria[:focus]
+        CRITERIA_DIMENSION_SCORES.map do |name, max_score|
+          {
+            name: name,
+            max_score: max_score,
+            description: "#{CORE_DIMENSION_DESCRIPTIONS.fetch(name)} (#{category} focus: #{focus})"
+          }
+        end
+      end
+
       def build_skill_md
         <<~MARKDOWN
           # Skill: {{skill_name}} (#{category})

data/lib/skill_bench/services/trend_recorder_service.rb

@@ -6,6 +6,13 @@ module SkillBench
   module Services
     # Records evaluation results and computes trends.
     class TrendRecorderService
+      # Serializes the load -> append -> write of the shared trend history
+      # file. Batch runs ({BatchRunnerService}) execute evals concurrently and
+      # the trend file is process-global shared state; without this lock,
+      # concurrent records race on the temp-file rename and silently lose
+      # appended entries.
+      WRITE_MUTEX = Mutex.new
+
       # Records evaluation results and computes trends.
       #
       # @param result [Hash] The evaluation result from Evaluation::Runner
@@ -27,12 +34,14 @@ module SkillBench
 
       # Records evaluation results and computes trends.
       #
+      # Loads the trend history once and reuses it for both the trend
+      # computation and the append+write, avoiding a duplicate parse per run.
+      #
       # @return [Hash] Result with success status and trend data
       def call
         tracker = TrendTracker.new
         enriched = @result.merge(eval_name: @eval_name, skill_names: @skill_names)
-        trend = tracker.trend_for(enriched)
-        record_result = tracker.record(enriched)
+        trend, record_result = record_atomically(tracker, enriched)
 
         record_success = record_result.is_a?(Hash) && record_result[:success]
         unless record_success
@@ -62,6 +71,24 @@ module SkillBench
         SkillBench::ErrorLogger.log_error(e, 'Trend tracking failed')
         { success: false, response: { error: { message: e.message } } }
       end
+
+      private
+
+      # Loads history, computes the trend, and records the entry while holding
+      # {WRITE_MUTEX}, so concurrent batch evals serialize their read-modify-
+      # write of the shared trend file. History is still loaded exactly once
+      # per run and reused for both the trend computation and the append.
+      #
+      # @param tracker [SkillBench::TrendTracker] The trend tracker
+      # @param enriched [Hash] Result enriched with eval_name and skill_names
+      # @return [Array(Hash, Hash)] The computed trend and the record result
+      def record_atomically(tracker, enriched)
+        WRITE_MUTEX.synchronize do
+          history = tracker.history
+          trend = tracker.trend_for(enriched, history)
+          [trend, tracker.record(enriched, history)]
+        end
+      end
     end
   end
 end

data/lib/skill_bench/tools/registry.rb

@@ -8,15 +8,41 @@ module SkillBench
   module Tools
     # Registry for all available tools, providing their definitions to the LLM.
     class Registry
-      # Returns an array of tool definitions in the format expected by the LLM API.
+      # Recursively deep-freezes a tool-definition value (Hash/Array and contents)
+      # so accidental mutation by a downstream consumer raises immediately.
       #
-      # @return [Array<Hash>] The list of available tools with their names, descriptions, and schemas.
-      def self.definitions
+      # @param value [Object] The value to deep-freeze in place.
+      # @return [Object] The same value, frozen along with everything it contains.
+      def self.deep_freeze(value)
+        children = case value
+                   when Hash  then value.values
+                   when Array then value
+                   else []
+                   end
+        children.each { |child| deep_freeze(child) }
+        value.freeze
+      end
+      private_class_method :deep_freeze
+
+      # The static tool definitions sent to the LLM API. The tool schemas are
+      # constant JSON-schema specs (no per-call state or runtime config), so the
+      # array and its nested hashes are built once and deep-frozen for reuse
+      # across every ReAct step instead of being reallocated on each call.
+      #
+      # @return [Array<Hash>] Frozen list of tools with their names, descriptions, and schemas.
+      DEFINITIONS = deep_freeze(
         [
           ReadFile.definition,
           WriteFile.definition,
           RunCommand.definition
         ]
+      )
+
+      # Returns the memoized, frozen array of tool definitions for the LLM API.
+      #
+      # @return [Array<Hash>] The frozen list of available tools with their names, descriptions, and schemas.
+      def self.definitions
+        DEFINITIONS
       end
     end
   end