robot_lab 0.2.6 → 0.2.8

data/lib/robot_lab/config.rb

@@ -8,7 +8,8 @@ module RobotLab
   # Provides:
   # - Nested configuration with a dedicated `ruby_llm:` section
   # - Environment-specific settings (development, test, production)
-  # - XDG config file loading (~/.config/robot_lab/config.yml)
+  # - XDG config file loading (~/.config/robot_lab/robot_lab.yml — the filename
+  #   repeats the `config_name`; `config.yml` is never read)
   # - Environment variable overrides (ROBOT_LAB_*)
   # - Automatic RubyLLM configuration application
   #
@@ -21,10 +22,14 @@ module RobotLab
   #   # ROBOT_LAB_RUBY_LLM__MODEL=gpt-4
   #   # ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
   #
-  # @example User config file (~/.config/robot_lab/config.yml)
-  #   defaults:
-  #     ruby_llm:
-  #       anthropic_api_key: <%= ENV['ANTHROPIC_API_KEY'] %>
+  # @example User config file (~/.config/robot_lab/robot_lab.yml)
+  #   # Flat keys, or a section named for the current environment. A `defaults:`
+  #   # wrapper is IGNORED here — it applies only to the gem's bundled
+  #   # defaults.yml. This file is NOT run through ERB, so keep secrets in
+  #   # environment variables or in ./config/robot_lab.yml (which is).
+  #   ruby_llm:
+  #     model: claude-sonnet-4
+  #     request_timeout: 120
   #
   class Config < MywayConfig::Base
     config_name :robot_lab
@@ -73,6 +78,8 @@ module RobotLab
 
     private
 
+    # :reek:UncommunicativeParameterName -- `c` is the RubyLLM config being configured; conventional here (RuboCop allows it).
+    # :reek:TooManyStatements -- one set_if_present line per supported provider credential; a loop would obscure the env-var mapping.
     def apply_provider_api_keys(c)
       # Fall back to standard provider env vars when not set in config.
       # This lets users set ANTHROPIC_API_KEY (etc.) directly without
@@ -98,6 +105,7 @@ module RobotLab
       set_if_present(c, :vertexai_location, :vertexai_location, 'GOOGLE_CLOUD_LOCATION')
     end
 
+    # :reek:UncommunicativeParameterName -- `c` is the RubyLLM config being configured; conventional here.
     def apply_provider_endpoints(c)
       c.openai_api_base = ruby_llm.openai_api_base if ruby_llm.openai_api_base
       c.gemini_api_base = ruby_llm.gemini_api_base if ruby_llm.gemini_api_base
@@ -106,12 +114,14 @@ module RobotLab
       c.xai_api_base = ruby_llm.xai_api_base if ruby_llm.xai_api_base
     end
 
+    # :reek:UncommunicativeParameterName -- `c` is the RubyLLM config being configured; conventional here.
     def apply_openai_options(c)
       c.openai_organization_id = ruby_llm.openai_organization_id if ruby_llm.openai_organization_id
       c.openai_project_id = ruby_llm.openai_project_id if ruby_llm.openai_project_id
       c.openai_use_system_role = ruby_llm.openai_use_system_role unless ruby_llm.openai_use_system_role.nil?
     end
 
+    # :reek:UncommunicativeParameterName -- `c` is the RubyLLM config being configured; conventional here.
     def apply_default_models(c)
       c.default_model = ruby_llm.default_model if ruby_llm.default_model
       c.default_embedding_model = ruby_llm.default_embedding_model if ruby_llm.default_embedding_model
@@ -119,6 +129,7 @@ module RobotLab
       c.default_moderation_model = ruby_llm.default_moderation_model if ruby_llm.default_moderation_model
     end
 
+    # :reek:UncommunicativeParameterName -- `c` is the RubyLLM config being configured; conventional here.
     def apply_connection_settings(c)
       c.request_timeout = ruby_llm.request_timeout if ruby_llm.request_timeout
       c.max_retries = ruby_llm.max_retries if ruby_llm.max_retries
@@ -128,6 +139,7 @@ module RobotLab
       c.http_proxy = ruby_llm.http_proxy if ruby_llm.http_proxy
     end
 
+    # :reek:UncommunicativeParameterName -- `c` is the RubyLLM config being configured; conventional here.
     def apply_logging_options(c)
       c.log_file = ruby_llm.log_file if ruby_llm.log_file
       c.log_level = ruby_llm.log_level if ruby_llm.log_level
@@ -145,6 +157,7 @@ module RobotLab
 
     # Set a RubyLLM config attribute from config value or standard env var.
     # Only sets when a non-nil value is found, to avoid overwriting defaults.
+    # :reek:UncommunicativeParameterName -- `c` is the RubyLLM config being configured; conventional here.
     def set_if_present(c, setter, config_key, env_var)
       value = ruby_llm.public_send(config_key) || ENV.fetch(env_var, nil)
       c.public_send(:"#{setter}=", value) if value

data/lib/robot_lab/doom_loop_detector.rb

@@ -33,19 +33,21 @@ module RobotLab
       @sequence << tool_name.to_s
     end
 
+    # :reek:TooManyStatements -- self-contained cycle-detection algorithm; splitting the scan loses the shape of the check.
     def doom_loop?
       seq = @sequence
-      return false if seq.length < @threshold
+      length = seq.length
+      return false if length < @threshold
 
       # Consecutive identical calls: A, A, A
       tail = seq.last(@threshold)
       return true if tail.uniq.length == 1
 
       # Cyclic multi-step patterns: A,B,C, A,B,C, A,B,C
-      max_period = [MAX_PERIOD, seq.length / @threshold].min
+      max_period = [MAX_PERIOD, length / @threshold].min
       (2..max_period).each do |period|
         window = @threshold * period
-        next if seq.length < window
+        next if length < window
 
         chunk = seq.last(window)
         pattern = chunk.first(period)
@@ -79,6 +81,7 @@ module RobotLab
 
     private
 
+    # :reek:TooManyStatements -- mirrors doom_loop?'s scan to report which period matched.
     def detect_period(seq)
       return 1 if seq.last(@threshold).uniq.length == 1
 

data/lib/robot_lab/history_compressor.rb

@@ -59,6 +59,7 @@ module RobotLab
     # Execute compression and return the new message array.
     #
     # @return [Array] compressed message array
+    # :reek:TooManyStatements -- linear classify/score/rebuild pipeline; each early return is a documented no-op case.
     def call
       return @messages if @messages.empty?
 
@@ -113,6 +114,7 @@ module RobotLab
     # Determine the action for one compressible message.
     #
     # @return [Symbol, String] :keep, :drop, or a summary String
+    # :reek:TooManyStatements -- one linear score-then-threshold decision.
     def score_action(reference, msg)
       text = extract_text(msg)
 
@@ -133,6 +135,7 @@ module RobotLab
     end
 
     # Build the final message array from the decided actions.
+    # :reek:FeatureEnvy -- dispatching on the per-message action value (:keep/:drop/summary) is this method's purpose.
     def build_result(actions)
       result = []
 
@@ -157,6 +160,7 @@ module RobotLab
     # System messages and tool-related messages are always pinned.
     # Assistant messages with no text content (tool call dispatchers)
     # are also pinned to avoid breaking tool_use/tool_result pairing.
+    # :reek:FeatureEnvy -- classifying by a message's own role and text; Message stays a plain value object.
     def pinned_message?(msg)
       role = msg.role
 
@@ -187,6 +191,7 @@ module RobotLab
     #
     # @param vectors [Array<Hash{Symbol => Float}>]
     # @return [Hash{Symbol => Float}]
+    # :reek:NestedIterators -- 2-deep each over sparse vectors is the natural element-wise sum.
     def mean_vector(vectors)
       return {} if vectors.empty?
 

data/lib/robot_lab/hook.rb

@@ -31,6 +31,7 @@ module RobotLab
   #   robot.on(AuditHook)
   #   network.on(AuditHook)
   #
+  # :reek:InstanceVariableAssumption -- @namespace is a class-level ivar, initialized here and reset in .inherited; there is no #initialize.
   class Hook
     @namespace = nil
 

data/lib/robot_lab/hook_context.rb

@@ -4,9 +4,11 @@ module RobotLab
   class HookContext
     attr_reader :event, :metadata
 
+    # :reek:ControlParameter -- `metadata || ExtensionState.new` is a nil-safe default, not behavior selection.
     def initialize(event:, metadata: nil)
       @event = event.to_sym
       @metadata = metadata || ExtensionState.new
+      @namespace = nil # no hook namespace active until with_namespace
     end
 
     def ext(name)
@@ -46,6 +48,7 @@ module RobotLab
     attr_reader :robot, :network, :task, :memory, :config
     attr_accessor :request, :response, :error
 
+    # :reek:LongParameterList -- one keyword per run-context field; hooks read them all.
     def initialize(robot:, request:, network: nil, task: nil, memory: nil, config: nil, response: nil, error: nil, **)
       super(event: :run, **)
       @robot = robot
@@ -104,6 +107,7 @@ module RobotLab
     attr_reader :network, :task, :task_name, :robot, :memory, :config
     attr_accessor :result, :error
 
+    # :reek:ControlParameter -- `robot || task.robot` is a fallback default, not behavior selection.
     def initialize(task:, network: nil, robot: nil, memory: nil, config: nil, result: nil, error: nil, **)
       super(event: :task, **)
       @network = network

data/lib/robot_lab/hook_registry.rb

@@ -21,6 +21,7 @@ module RobotLab
     # @param handler_class [Class] a RobotLab::Hook subclass
     # @param context [Hash, nil] optional default values merged into ctx.local on each call
     # @return [Registration]
+    # :reek:FeatureEnvy -- validating the handler_class argument before registering it is this method's job.
     def on(handler_class, context: nil)
       unless handler_class.is_a?(Class) && handler_class < RobotLab::Hook
         raise ArgumentError, "#{handler_class.inspect} must be a RobotLab::Hook subclass"

data/lib/robot_lab/hooks.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 module RobotLab
+  # :reek:DataClump -- stateless module_function dispatchers; registries/per_run_hooks flow through every call by design.
   module Hooks
     module_function
 
+    # :reek:TooManyStatements -- the before/around/after/error hook lifecycle in one linear sequence.
     def run(family, context, registries:, per_run_hooks: nil, &)
       before = registrations(:"before_#{family}", registries, per_run_hooks)
       around = registrations(:"around_#{family}", registries, per_run_hooks)
@@ -53,9 +55,10 @@ module RobotLab
     end
 
     def call_registration(registration, hook_name, context, &)
-      context.with_namespace(registration.namespace) do
-        if registration.context && registration.namespace
-          context.ext(registration.namespace).merge_defaults(registration.context)
+      namespace = registration.namespace
+      context.with_namespace(namespace) do
+        if registration.context && namespace
+          context.ext(namespace).merge_defaults(registration.context)
         end
         registration.handler_class.call(hook_name, context, &)
       end

data/lib/robot_lab/mcp/client.rb

@@ -13,6 +13,7 @@ module RobotLab
     #   tools = client.list_tools
     #   result = client.call_tool("createBranch", { project_id: "abc" })
     #
+    # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every public operation must check it.
     class Client
       # @!attribute [r] server
       #   @return [Server] the MCP server configuration
@@ -45,6 +46,7 @@ module RobotLab
       #
       # @return [self]
       #
+      # :reek:TooManyStatements -- linear connect/register sequence with a best-effort rescue.
       def connect
         return self if @connected
 
@@ -204,8 +206,6 @@ module RobotLab
       end
 
       def parse_response(response)
-        return response[:result] if response.is_a?(Hash) && response[:result]
-
         case response
         when String
           parsed = JSON.parse(response, symbolize_names: true)

data/lib/robot_lab/mcp/connection_poller.rb

@@ -104,15 +104,20 @@ module RobotLab
       # @param timeout [Numeric] seconds before raising MCPError
       # @return [Hash] parsed response
       # @raise [MCPError] on timeout or connection error
+      # :reek:TooManyStatements -- register/write/wait/cleanup must stay in one method so ensure releases the queue.
+      # :reek:DuplicateMethodCall -- the repeated @mutex.synchronize/@clients[io] pairs are deliberately separate short critical
+      #   sections; holding the lock across the blocking write/wait would deadlock the poll loop.
       def send_request(client, message, timeout:)
-        io      = client.transport.stdout
-        queue   = Thread::Queue.new
+        transport = client.transport
+        io        = transport.stdout
+        stdin     = transport.stdin
+        queue     = Thread::Queue.new
 
         @mutex.synchronize { @clients[io][:queue] = queue }
 
         begin
-          client.transport.stdin.puts(message.to_json)
-          client.transport.stdin.flush
+          stdin.puts(message.to_json)
+          stdin.flush
         rescue Errno::EPIPE, IOError => e
           @mutex.synchronize { @clients[io][:queue] = nil }
           raise MCPError.new("MCP connection lost: #{e.message}", retryable: true)
@@ -160,6 +165,7 @@ module RobotLab
         end
       end
 
+      # :reek:TooManyStatements -- read/parse/filter/route steps for each readable IO; each guard skips a non-response line.
       def dispatch(readable_ios)
         readable_ios.each do |io|
           line = io.gets rescue nil
@@ -177,10 +183,12 @@ module RobotLab
       end
 
       def stdio_client?(client)
-        client.respond_to?(:transport) &&
-          client.transport.is_a?(Transports::Stdio) &&
-          client.transport.respond_to?(:stdout) &&
-          !client.transport.stdout.nil?
+        return false unless client.respond_to?(:transport)
+
+        transport = client.transport
+        transport.is_a?(Transports::Stdio) &&
+          transport.respond_to?(:stdout) &&
+          !transport.stdout.nil?
       end
     end
   end

data/lib/robot_lab/mcp/server_discovery.rb

@@ -60,6 +60,7 @@ module RobotLab
       # @param threshold [Float]           minimum cosine score (default 0.05)
       # @return [Array<Hash, MCP::Server>] matching servers, or +from+ as
       #   fallback when no match is found
+      # :reek:TooManyStatements -- linear guard/score/filter pipeline; each early return is a documented fallback.
       def self.select(query, from:, threshold: DEFAULT_THRESHOLD)
         return from if from.empty?
         return from if query.to_s.strip.empty?

data/lib/robot_lab/mcp/transports/sse.rb

@@ -10,6 +10,8 @@ module RobotLab
       # @example
       #   transport = SSE.new(url: "http://localhost:8080/sse")
       #
+      # :reek:InstanceVariableAssumption -- @config is assigned in Base#initialize (reek does not trace super).
+      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every operation must check it.
       class SSE < Base
         # Creates a new SSE transport.
         #
@@ -26,6 +28,7 @@ module RobotLab
         #
         # @return [self]
         # @raise [MCPError] if async-http gem is not available
+        # :reek:TooManyStatements -- linear require/connect/handshake sequence inside the Async block.
         def connect
           return self if @connected
 

data/lib/robot_lab/mcp/transports/stdio.rb

@@ -19,6 +19,8 @@ module RobotLab
       #     timeout: 10
       #   )
       #
+      # :reek:InstanceVariableAssumption -- @config and @timeout are assigned in Base#initialize (reek does not trace super).
+      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every IO operation must check it.
       class Stdio < Base
         # Creates a new Stdio transport.
         #
@@ -41,6 +43,7 @@ module RobotLab
         # @return [self]
         # @raise [MCPError] if the server process cannot be started or does not
         #   respond to the MCP initialize handshake within the timeout period
+        # :reek:TooManyStatements -- linear spawn/verify/handshake sequence with per-failure-mode rescues.
         def connect
           return self if @connected
 
@@ -76,6 +79,7 @@ module RobotLab
         # @param message [Hash] JSON-RPC message
         # @return [Hash] the response
         # @raise [MCPError] if not connected, no response, or timeout
+        # :reek:TooManyStatements -- write-then-read loop must stay inside the one Timeout block.
         def send_request(message)
           raise MCPError, "Not connected" unless @connected
 
@@ -148,6 +152,7 @@ module RobotLab
           @stdin.flush
         end
 
+        # :reek:TooManyStatements -- best-effort teardown; each handle is closed and nilled independently.
         def cleanup_process
           @connected = false
           @stdin&.close  rescue nil

data/lib/robot_lab/mcp/transports/streamable_http.rb

@@ -13,6 +13,8 @@ module RobotLab
       #     session_id: "abc123"
       #   )
       #
+      # :reek:InstanceVariableAssumption -- @config is assigned in Base#initialize (reek does not trace super).
+      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every operation must check it.
       class StreamableHTTP < Base
         # Creates a new StreamableHTTP transport.
         #
@@ -31,6 +33,7 @@ module RobotLab
         #
         # @return [self]
         # @raise [MCPError] if async-http gem is not available
+        # :reek:TooManyStatements -- linear require/connect/handshake sequence inside the Async block.
         def connect
           return self if @connected
 
@@ -60,6 +63,7 @@ module RobotLab
         # @param message [Hash] JSON-RPC message
         # @return [Hash] the response
         # @raise [MCPError] if not connected
+        # :reek:TooManyStatements -- header assembly and POST must stay inside the one Async block.
         def send_request(message)
           raise MCPError, "Not connected" unless @connected
 

data/lib/robot_lab/mcp/transports/websocket.rb

@@ -10,6 +10,8 @@ module RobotLab
       # @example
       #   transport = WebSocket.new(url: "ws://localhost:8080")
       #
+      # :reek:InstanceVariableAssumption -- @config is assigned in Base#initialize (reek does not trace super).
+      # :reek:RepeatedConditional -- @connected is the connection-lifecycle guard; every operation must check it.
       class WebSocket < Base
         # Creates a new WebSocket transport.
         #
@@ -26,6 +28,7 @@ module RobotLab
         #
         # @return [self]
         # @raise [MCPError] if async-websocket gem is not available
+        # :reek:TooManyStatements -- linear require/connect/handshake sequence inside the Async block.
         def connect
           return self if @connected
 

data/lib/robot_lab/memory.rb

@@ -58,6 +58,9 @@ module RobotLab
   #   memory.results  # => []
   #   memory.cache  # => RubyLLM::SemanticCache instance
   #
+  # :reek:TooManyMethods -- Memory is the deliberately broad shared-state facade
+  #   (reserved keys, reactive get/subscribe, history); see CLAUDE.md.
+  # :reek:RepeatedConditional -- `@backend.key?(key)` is the check-under-mutex idiom; each site is a separate critical section.
   class Memory
     include Utils
 
@@ -89,6 +92,7 @@ module RobotLab
     #
     # @example Network-owned memory
     #   Memory.new(network_name: "support_pipeline")
+    # :reek:BooleanParameter -- enable_cache is a documented feature toggle in the public API.
     def initialize(data: {}, results: [], messages: [], session_id: nil, backend: :auto, enable_cache: true,
                    network_name: nil)
       @backend = select_backend(backend)
@@ -144,6 +148,7 @@ module RobotLab
     #
     # @see #set
     #
+    # :reek:TooManyStatements -- one case branch per reserved key; dispatch reads best as a single table.
     def []=(key, value)
       key = key.to_sym
 
@@ -292,6 +297,8 @@ module RobotLab
     #   memory.get(:sentiment, :entities, :keywords, wait: 60)
     #   # => { sentiment: {...}, entities: [...], keywords: [...] }
     #
+    # :reek:BooleanParameter -- `wait` is public API: false, true (block forever) or a numeric timeout.
+    # :reek:FeatureEnvy -- normalizing this method's own varargs before dispatching on arity.
     def get(*keys, wait: false)
       keys = keys.flatten.map(&:to_sym)
 
@@ -370,6 +377,8 @@ module RobotLab
     # @param subscription_id [Object] the subscription identifier from subscribe
     # @return [Boolean] true if subscription was found and removed
     #
+    # :reek:ControlParameter -- subscription_id is matched against stored ids, not used to select behavior.
+    # :reek:NestedIterators -- 2-deep scan of the per-key subscription lists is the natural shape.
     def unsubscribe(subscription_id)
       removed = false
 
@@ -576,6 +585,7 @@ module RobotLab
     #
     # @return [self]
     #
+    # :reek:TooManyStatements -- reserved keys are re-seeded one by one inside a single mutex block.
     def reset
       cached = get_internal(:cache)  # Preserve cache instance
       @mutex.synchronize do
@@ -695,6 +705,7 @@ module RobotLab
       RubyLLM::SemanticCache
     end
 
+    # :reek:ControlParameter -- factory method; the preference symbol is exactly what selects the backend.
     def select_backend(preference)
       case preference
       when :hash
@@ -716,11 +727,11 @@ module RobotLab
       {}
     end
 
-    def redis_available?
+    def redis_available?(config = RobotLab.config)
       return false unless defined?(Redis)
 
       # Check if Redis is configured in RobotLab
-      redis_config = RobotLab.config.respond_to?(:redis) ? RobotLab.config.redis : nil
+      redis_config = config.respond_to?(:redis) ? config.redis : nil
       redis_config || ENV.fetch("REDIS_URL", nil)
     end
 
@@ -766,6 +777,7 @@ module RobotLab
       wait_for_key(key, timeout: timeout)
     end
 
+    # :reek:TooManyStatements -- read-under-mutex then wait-for-missing; splitting would separate lock from wait logic.
     def get_multiple(keys, wait:)
       results = {}
       missing = []
@@ -791,6 +803,7 @@ module RobotLab
       results
     end
 
+    # :reek:TooManyStatements -- double-check locking plus timeout cleanup must stay together for correctness.
     def wait_for_key(key, timeout:)
       waiter = Waiter.new
 
@@ -813,11 +826,13 @@ module RobotLab
       result
     end
 
+    # :reek:UncommunicativeVariableName -- single-char block vars are accepted style here (RuboCop allows them).
     def wake_waiters(key, value)
       waiters = @waiter_mutex.synchronize { @waiters.delete(key) || [] }
       waiters.each { |w| w.signal(value) }
     end
 
+    # :reek:TooManyStatements -- collect/build/coalesce steps share the change object and the scheduling flag.
     def notify_subscribers_async(key, value, old_value)
       # Collect all matching subscribers
       callbacks = []
@@ -860,6 +875,8 @@ module RobotLab
     # Drain all pending notification batches in a single fiber.
     # Loops until the queue is empty, then resets the drainer flag.
     # If new items arrive just before the flag resets, reschedules itself.
+    # :reek:TooManyStatements :reek:NestedIterators -- the drain loop and its ensure-reschedule race guard are one
+    #   atomic unit; batch-of-callbacks iteration is inherently 2-deep.
     def drain_notification_queue
       loop do
         batch = @notification_queue_mutex.synchronize do
@@ -908,8 +925,8 @@ module RobotLab
   #
   # @api private
   class RedisBackend
-    def initialize
-      @redis = create_redis_connection
+    def initialize(config = RobotLab.config)
+      @redis = create_redis_connection(config)
       @namespace = "robot_lab:memory:#{SecureRandom.uuid}"
     end
 
@@ -945,8 +962,8 @@ module RobotLab
 
     private
 
-    def create_redis_connection
-      redis_config = RobotLab.config.respond_to?(:redis) ? RobotLab.config.redis : nil
+    def create_redis_connection(config = RobotLab.config)
+      redis_config = config.respond_to?(:redis) ? config.redis : nil
 
       if redis_config.is_a?(Hash)
         Redis.new(**redis_config)

data/lib/robot_lab/memory_change.rb

@@ -43,6 +43,7 @@ module RobotLab
     # @param timestamp [Time] when the change occurred (defaults to now)
     # @param correlation_id [String, nil] optional correlation ID
     #
+    # :reek:ControlParameter -- `timestamp || Time.now` is a nil-safe default, not behavior selection.
     def initialize(key:, value:, previous: nil, writer: nil, network_name: nil, timestamp: nil, correlation_id: nil)
       @key = key.to_sym
       @value = value

data/lib/robot_lab/message.rb

@@ -178,6 +178,7 @@ module RobotLab
     # @param id [String] the unique identifier for this tool call
     # @param name [String] the name of the tool
     # @param input [Hash, nil] the input arguments
+    # :reek:ControlParameter -- `input || {}` is a nil-safe default, not behavior selection.
     def initialize(id:, name:, input:)
       @id = id
       @name = name
@@ -238,6 +239,7 @@ module RobotLab
     # @param role [String, Symbol] the message role (usually assistant)
     # @param tools [Array<ToolMessage, Hash>] the tool calls
     # @param stop_reason [String, Symbol, nil] the stop reason (defaults to "tool")
+    # :reek:ControlParameter -- `stop_reason || "tool"` is a nil-safe default, not behavior selection.
     def initialize(role:, tools:, stop_reason: nil)
       @tools = normalize_tools(tools)
       super(type: "tool_call", role: role, content: nil, stop_reason: stop_reason || "tool")
@@ -295,6 +297,7 @@ module RobotLab
     # @param tool [ToolMessage, Hash] the tool call that was executed
     # @param content [Hash] the result content (with :data or :error key)
     # @param stop_reason [String, Symbol, nil] the stop reason (defaults to "tool")
+    # :reek:ControlParameter -- `stop_reason || "tool"` is a nil-safe default, not behavior selection.
     def initialize(tool:, content:, stop_reason: nil)
       @tool = normalize_tool(tool)
       super(type: "tool_result", role: "tool_result", content: content, stop_reason: stop_reason || "tool")