claude-agent-sdk 0.36.0 → 1.0.0

data/lib/claude_agent_sdk/message_parser.rb

@@ -5,9 +5,11 @@ require_relative 'errors'
 
 module ClaudeAgentSDK
   # Parse message from CLI output into typed Message objects
+  #
+  # @api private
   class MessageParser
-    def self.parse(data)
-      raise MessageParseError.new("Invalid message data type", data: data) unless data.is_a?(Hash)
+    def self.parse(data) # rubocop:disable Metrics/CyclomaticComplexity -- flat dispatch over CLI message types
+      raise MessageParseError.new('Invalid message data type', data: data) unless data.is_a?(Hash)
 
       message_type = data[:type]
       raise MessageParseError.new("Message missing 'type' field", data: data) unless message_type
@@ -47,13 +49,17 @@ module ClaudeAgentSDK
       uuid = data[:uuid] # UUID for rewind support
       tool_use_result = data[:tool_use_result]
       message_data = data[:message]
-      raise MessageParseError.new("Missing message field in user message", data: data) unless message_data
+      raise MessageParseError.new('Missing message field in user message', data: data) unless message_data
       # A non-Hash message (malformed CLI output) raised a raw TypeError from
       # message_data[:content] instead of the documented MessageParseError.
-      raise MessageParseError.new("Invalid message field in user message (expected Hash, got #{message_data.class})", data: data) unless message_data.is_a?(Hash)
+      unless message_data.is_a?(Hash)
+        raise MessageParseError.new(
+          "Invalid message field in user message (expected Hash, got #{message_data.class})", data: data
+        )
+      end
 
       content = message_data[:content]
-      raise MessageParseError.new("Missing content in user message", data: data) unless content
+      raise MessageParseError.new('Missing content in user message', data: data) unless content
 
       origin = parse_origin(data)
 
@@ -85,11 +91,17 @@ module ClaudeAgentSDK
       message_data = data[:message]
       # A non-Hash message (malformed CLI output) raised a raw TypeError from
       # dig instead of the documented MessageParseError.
-      raise MessageParseError.new("Invalid message field in assistant message (expected Hash, got #{message_data.class})", data: data) unless message_data.is_a?(Hash)
+      unless message_data.is_a?(Hash)
+        raise MessageParseError.new(
+          "Invalid message field in assistant message (expected Hash, got #{message_data.class})", data: data
+        )
+      end
 
       content = message_data[:content]
-      raise MessageParseError.new("Missing content in assistant message", data: data) unless content
-      raise MessageParseError.new("Invalid assistant content (expected Array, got #{content.class})", data: data) unless content.is_a?(Array)
+      raise MessageParseError.new('Missing content in assistant message', data: data) unless content
+      unless content.is_a?(Array)
+        raise MessageParseError.new("Invalid assistant content (expected Array, got #{content.class})", data: data)
+      end
 
       content_blocks = parse_content_blocks(content, data)
       AssistantMessage.new(
@@ -194,7 +206,9 @@ module ClaudeAgentSDK
     # opaque TypeError/NoMethodError from `block[:type]` deep in parsing.
     def self.parse_content_blocks(content, data)
       content.map do |block|
-        raise MessageParseError.new("Invalid content block (expected Hash, got #{block.class})", data: data) unless block.is_a?(Hash)
+        unless block.is_a?(Hash)
+          raise MessageParseError.new("Invalid content block (expected Hash, got #{block.class})", data: data)
+        end
 
         parse_content_block(block)
       end

data/lib/claude_agent_sdk/observer.rb

@@ -39,7 +39,8 @@ module ClaudeAgentSDK
     # Client#query/#receive_messages/#receive_response/#connect (after
     # argument/configuration validation — usage errors such as 'Not
     # connected' or invalid options do not notify) — including errors raised
-    # by the user's own message block — before on_close where both fire. query() fires on_close even for connect-phase failures (its
+    # by the user's own message block — before on_close where both fire.
+    # query() fires on_close even for connect-phase failures (its
     # ensure always runs); a Client#connect failure before the handshake
     # completes fires on_error WITHOUT on_close (the session never opened).
     # Not notified (by design): errors raised by control-request methods

data/lib/claude_agent_sdk/option_warnings.rb

@@ -2,6 +2,8 @@
 
 module ClaudeAgentSDK
   # Advisory warnings for option combinations that silently change behavior.
+  #
+  # @api private
   module OptionWarnings
     @emitted = Set.new
     @mutex = Mutex.new

data/lib/claude_agent_sdk/query.rb

@@ -19,9 +19,17 @@ module ClaudeAgentSDK
   # - Tool permission callbacks
   # - Message streaming
   # - Initialization handshake
-  class Query
+  #
+  # @api private
+  class Query # rubocop:disable Metrics/ClassLength -- control-protocol hub: routing, hooks, permissions, MCP bridge
     attr_reader :transport, :is_streaming_mode, :sdk_mcp_servers
 
+    # The CLI's response to the initialize control request (nil before
+    # #initialize_protocol completes). Read by Client#server_info.
+    #
+    # @api private
+    attr_reader :initialization_result
+
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
 
@@ -63,7 +71,7 @@ module ClaudeAgentSDK
       end
     end
 
-    def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil,
+    def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- initializes every control-protocol concern in one place
                    exclude_dynamic_sections: nil, system_prompt_snapshot: nil, skills: nil,
                    forward_subagent_text: false, agent_progress_summaries: nil,
                    callback_scheduling: :thread, callback_wrapper: nil)
@@ -132,7 +140,7 @@ module ClaudeAgentSDK
 
     # Initialize control protocol if in streaming mode
     # @return [Hash, nil] Initialize response with supported commands, or nil if not streaming
-    def initialize_protocol
+    def initialize_protocol # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- builds the initialize request from every optional option
       return nil unless @is_streaming_mode
 
       # Build hooks configuration for initialization
@@ -237,7 +245,10 @@ module ClaudeAgentSDK
       return if @task
 
       parent = Async::Task.current?
-      raise CLIConnectionError, 'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})' unless parent
+      unless parent
+        raise CLIConnectionError,
+              'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})'
+      end
 
       @owning_scheduler = Fiber.scheduler
       # Async child fibers do not inherit OTel's fiber-local current context.
@@ -322,8 +333,8 @@ module ClaudeAgentSDK
       DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS
     end
 
-    def read_messages
-      @transport.read_messages do |message|
+    def read_messages # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- concurrency-sensitive read loop; kept whole on purpose
+      @transport.read_messages do |message| # rubocop:disable Metrics/BlockLength -- see read_messages
         break if @closed
 
         msg_type = message[:type]
@@ -338,14 +349,12 @@ module ClaudeAgentSDK
           # nothing keeps running after close; bare Async do may root at the
           # reactor and leak past shutdown.
           handler_task = Async::Task.current.async(&FiberBoundary.capture_otel_context do
-            begin
-              handle_control_request(message)
-            ensure
-              # Identity-guarded: if the CLI ever reused an in-flight request
-              # id, the later handler owns the slot and must stay cancellable.
-              if request_id && @inflight_control_request_tasks[request_id].equal?(Async::Task.current)
-                @inflight_control_request_tasks.delete(request_id)
-              end
+            handle_control_request(message)
+          ensure
+            # Identity-guarded: if the CLI ever reused an in-flight request
+            # id, the later handler owns the slot and must stay cancellable.
+            if request_id && @inflight_control_request_tasks[request_id].equal?(Async::Task.current)
+              @inflight_control_request_tasks.delete(request_id)
             end
           end)
           # A handler that never suspends (MCP metadata, unsupported-subtype
@@ -383,11 +392,7 @@ module ClaudeAgentSDK
               @first_result_received = true
               @first_result_condition.signal
             end
-            if message[:is_error]
-              @last_error_result = message
-            else
-              @last_error_result = nil
-            end
+            @last_error_result = message[:is_error] ? message : nil
           elsif !(msg_type == 'system' && message[:subtype] == 'session_state_changed')
             # Anything other than the post-turn session_state_changed marker
             # means the conversation moved on; a ProcessError now is a fresh
@@ -533,11 +538,12 @@ module ClaudeAgentSDK
       waiter = @pending_control_responses[request_id]
       return unless waiter
 
-      if response[:subtype] == 'error'
-        @pending_control_results[request_id] = StandardError.new(response[:error] || 'Unknown error')
-      else
-        @pending_control_results[request_id] = response
-      end
+      @pending_control_results[request_id] =
+        if response[:subtype] == 'error'
+          StandardError.new(response[:error] || 'Unknown error')
+        else
+          response
+        end
 
       # Signal that response is ready. INVARIANT: the result slot above
       # MUST be written before this signal — senders check the slot before
@@ -545,7 +551,7 @@ module ClaudeAgentSDK
       waiter.signal
     end
 
-    def handle_control_request(request)
+    def handle_control_request(request) # rubocop:disable Metrics/MethodLength -- subtype dispatch plus the shared error response
       request_id = request[:request_id] || request[:requestId]
       request_data = request[:request]
       subtype = request_data[:subtype]
@@ -636,7 +642,7 @@ module ClaudeAgentSDK
       nil
     end
 
-    def handle_permission_request(request_data, request_id: nil)
+    def handle_permission_request(request_data, request_id: nil) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- permission round-trip: input, callback, result conversion
       raise 'canUseTool callback is not provided' unless @can_use_tool
 
       signal = CancellationSignal.new
@@ -644,13 +650,17 @@ module ClaudeAgentSDK
       original_input = request_data[:input]
 
       # Field order mirrors Python _internal/query.py's can_use_tool branch.
-      # Suggestions are hydrated into PermissionUpdate (Python #920); a
-      # malformed entry raises here, on the reactor, and becomes an error
-      # control_response — same observable behavior as Python.
+      # Suggestions are hydrated into PermissionUpdate (Python #920) through
+      # the lenient .wrap, so fields a newer CLI adds never trip the
+      # strict-attribute warning meant for user-built updates. A nil (or
+      # false) entry becomes an empty PermissionUpdate, as PermissionUpdate.new
+      # made it before; any other non-Hash entry raises here, on the reactor,
+      # and becomes an error control_response — same observable behavior as
+      # Python.
       context = ToolPermissionContext.new(
         signal: signal,
         request_id: request_id,
-        suggestions: (request_data[:permission_suggestions] || []).map { |s| PermissionUpdate.new(s) },
+        suggestions: (request_data[:permission_suggestions] || []).map { |s| PermissionUpdate.wrap(s || {}) },
         tool_use_id: request_data[:tool_use_id],
         agent_id: request_data[:agent_id],
         blocked_path: request_data[:blocked_path],
@@ -681,9 +691,7 @@ module ClaudeAgentSDK
           behavior: 'allow',
           updatedInput: response.updated_input || original_input
         }
-        if response.updated_permissions
-          result[:updatedPermissions] = response.updated_permissions.map(&:to_h)
-        end
+        result[:updatedPermissions] = response.updated_permissions.map(&:to_h) if response.updated_permissions
         result
       when PermissionResultDeny
         result = { behavior: 'deny', message: response.message }
@@ -699,7 +707,7 @@ module ClaudeAgentSDK
       untrack_callback_signal(request_id, signal)
     end
 
-    def handle_hook_callback(request_data, request_id: nil)
+    def handle_hook_callback(request_data, request_id: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- hook round-trip: timeout, callback, output conversion
       callback_id = request_data[:callback_id]
       callback = @hook_callbacks[callback_id]
       raise "No hook callback found for ID: #{callback_id}" unless callback
@@ -784,7 +792,7 @@ module ClaudeAgentSDK
       @callback_request_signals.delete(request_id)
     end
 
-    def parse_hook_input(input_data)
+    def parse_hook_input(input_data) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength -- one branch per hook event type
       event_name = input_data[:hook_event_name] || input_data['hook_event_name']
       fetch = lambda do |key|
         if input_data.key?(key)
@@ -1017,11 +1025,9 @@ module ClaudeAgentSDK
       { mcp_response: mcp_response }
     end
 
-    def convert_hook_output_for_cli(hook_output)
+    def convert_hook_output_for_cli(hook_output) # rubocop:disable Metrics/CyclomaticComplexity -- one optional field per hook output key
       # Handle typed output objects
-      if hook_output.respond_to?(:to_h) && !hook_output.is_a?(Hash)
-        return hook_output.to_h
-      end
+      return hook_output.to_h if hook_output.respond_to?(:to_h) && !hook_output.is_a?(Hash)
 
       return {} unless hook_output.is_a?(Hash)
 
@@ -1135,7 +1141,7 @@ module ClaudeAgentSDK
       end
     end
 
-    def handle_sdk_mcp_request(server_name, message)
+    def handle_sdk_mcp_request(server_name, message) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength -- JSON-RPC method dispatch for SDK MCP servers
       # Carry this session's scheduling mode and callback wrapper across the
       # dispatch into the (possibly session-shared) SdkMcpServer via fiber
       # storage — set on the dispatching fiber, read back by the server's
@@ -1162,7 +1168,7 @@ module ClaudeAgentSDK
           jsonrpc: '2.0',
           id: message[:id],
           error: {
-            code: -32601,
+            code: -32_601,
             message: "Server '#{server_name}' not found"
           }
         }
@@ -1193,14 +1199,14 @@ module ClaudeAgentSDK
         {
           jsonrpc: '2.0',
           id: message[:id],
-          error: { code: -32601, message: "Method '#{method}' not found" }
+          error: { code: -32_601, message: "Method '#{method}' not found" }
         }
       end
     rescue StandardError => e
       {
         jsonrpc: '2.0',
         id: message[:id],
-        error: { code: -32603, message: e.message }
+        error: { code: -32_603, message: e.message }
       }
     ensure
       dispatch_scope&.close
@@ -1429,6 +1435,7 @@ module ClaudeAgentSDK
       wrote_message = false
       stream.each do |message|
         break if @closed
+
         serialized = message.is_a?(Hash) ? JSON.generate(message) : message.to_s
         writeln(serialized)
         wrote_message = true

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -67,13 +67,14 @@ module ClaudeAgentSDK
   # @api private
   def self.ruby_type_to_json_schema(type)
     # Class#=== matches instances, not the class object used in { id: Integer }.
-    type = { String => :string, Integer => :integer, Float => :float, TrueClass => :boolean, FalseClass => :boolean }.fetch(type, type)
+    type = { String => :string, Integer => :integer, Float => :float,
+             TrueClass => :boolean, FalseClass => :boolean }.fetch(type, type)
     case type
     when :string, String then { type: 'string' }
     when :integer, Integer then { type: 'integer' }
     when :float, Float, :number then { type: 'number' }
     when :boolean, TrueClass, FalseClass then { type: 'boolean' }
-    else { type: 'string' } # Default fallback
+    else { type: 'string' } # rubocop:disable Lint/DuplicateBranch -- default fallback; the :string arm stays explicit
     end
   end
 
@@ -96,14 +97,17 @@ module ClaudeAgentSDK
   #
   # This class wraps the official MCP Ruby SDK and provides a simpler block-based
   # API for defining tools, resources, and prompts.
-  class SdkMcpServer
+  class SdkMcpServer # rubocop:disable Metrics/ClassLength -- one facade over MCP::Server tools, resources and prompts
     # The gem validates arguments before injecting its server_context keyword.
     # Guard actual keys here, independent of schema composition/$ref support,
     # and retain this guard even when schema validation falls back to permissive.
+    #
+    # @api private
     class ToolInputSchema < MCP::Tool::InputSchema
       def validate_arguments(arguments)
         if arguments.is_a?(Hash) && (arguments.key?(:server_context) || arguments.key?('server_context'))
-          raise ValidationError, "Tool argument 'server_context' is reserved by the MCP SDK; rename it (e.g. 'request_context')"
+          raise ValidationError,
+                "Tool argument 'server_context' is reserved by the MCP SDK; rename it (e.g. 'request_context')"
         end
 
         super
@@ -150,7 +154,9 @@ module ClaudeAgentSDK
     # Validated at set time so a non-callable fails here, not later as a
     # NoMethodError inside a tool dispatch.
     def callback_wrapper=(value)
-      raise ArgumentError, "callback_wrapper must be a callable or nil (got #{value.inspect})" unless value.nil? || value.respond_to?(:call)
+      unless value.nil? || value.respond_to?(:call)
+        raise ArgumentError, "callback_wrapper must be a callable or nil (got #{value.inspect})"
+      end
 
       @callback_wrapper = value
     end
@@ -224,6 +230,7 @@ module ClaudeAgentSDK
     # Handle a JSON-RPC request
     # @param json_string [String] JSON-RPC request
     # @return [String] JSON-RPC response
+    # @api private
     def handle_json(json_string)
       @mcp_server.handle_json(json_string)
     end
@@ -245,6 +252,7 @@ module ClaudeAgentSDK
     # Responses are built from per-call locals (safe), but the gem's
     # instrumentation_callback attribution (@instrumentation_data ivar) can
     # cross-contaminate under concurrency — harmless with the default no-op.
+    # @api private
     def handle_message(message)
       original_id = message[:id]
       response = @mcp_server.handle(message.merge(jsonrpc: '2.0', id: 0))
@@ -294,7 +302,7 @@ module ClaudeAgentSDK
       end
 
       # Guard before flexible_fetch: it raises on non-Hash inputs.
-      content = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, "content", "content") : nil
+      content = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, 'content', 'content') : nil
       return error_tool_result("Tool '#{name}' must return a hash with :content key") unless content
 
       result
@@ -333,7 +341,7 @@ module ClaudeAgentSDK
 
       # Ensure content has the expected format (symbol or string keys; guard
       # before flexible_fetch — it raises on non-Hash inputs)
-      contents = content.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(content, "contents", "contents") : nil
+      contents = content.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(content, 'contents', 'contents') : nil
       raise "Resource '#{uri}' must return a hash with :contents key" if contents.nil?
 
       content
@@ -367,7 +375,7 @@ module ClaudeAgentSDK
       end
 
       # Ensure result has the expected format (symbol or string keys)
-      messages = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, "messages", "messages") : nil
+      messages = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, 'messages', 'messages') : nil
       raise "Prompt '#{name}' must return a hash with :messages key" if messages.nil?
 
       result
@@ -379,7 +387,7 @@ module ClaudeAgentSDK
     # in content with isError: true, returned as a *successful* JSON-RPC
     # result.
     def error_tool_result(text)
-      { content: [{ type: "text", text: text }], isError: true }
+      { content: [{ type: 'text', text: text }], isError: true }
     end
 
     # The mcp gem's tools/call error behavior swung across 0.x releases:
@@ -404,18 +412,19 @@ module ClaudeAgentSDK
     end
 
     # Create dynamic Tool classes from tool definitions
-    def create_tool_classes(tools)
+    def create_tool_classes(tools) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- builds each dynamic MCP::Tool subclass inline
       # Captured so the dynamic class can resolve the effective scheduling
       # mode at call time — same pattern as prompt classes.
       sdk_server = self
-      tools.map do |tool_def|
+      tools.map do |tool_def| # rubocop:disable Metrics/BlockLength -- see create_tool_classes
         # The gem injects server_context AFTER expanding the tool arguments,
         # overwriting a user value before our call method can recover it.
         # Check at registration (including raw SdkMcpTool definitions), not in
         # input_schema_value's permissive schema-error fallback.
         schema = ClaudeAgentSDK.normalize_tool_schema(tool_def.input_schema)
         if schema[:properties]&.key?(:server_context)
-          raise ArgumentError, "Tool '#{tool_def.name}' input property 'server_context' is reserved by the MCP SDK; rename it (e.g. 'request_context')"
+          raise ArgumentError, "Tool '#{tool_def.name}' input property 'server_context' is reserved by the MCP SDK; " \
+                               "rename it (e.g. 'request_context')"
         end
 
         # Create a new class that extends MCP::Tool
@@ -470,7 +479,7 @@ module ClaudeAgentSDK
               @tool_def.meta
             end
 
-            def call(server_context: nil, **args)
+            def call(server_context: nil, **args) # rubocop:disable Lint/UnusedMethodArgument -- declared to strip it from args
               # Filter out server_context and pass remaining args to handler.
               # Hop to a plain thread (default) so user handlers don't see
               # the Fiber scheduler; :inline runs in place on the reactor.

data/lib/claude_agent_sdk/session_mutations.rb

@@ -13,7 +13,9 @@ module ClaudeAgentSDK
   # Ported from Python SDK's _internal/session_mutations.py.
   # Appends typed metadata entries to the session's JSONL file,
   # matching the CLI pattern. Safe to call from any SDK host process.
-  module SessionMutations # rubocop:disable Metrics/ModuleLength
+  #
+  # @api private
+  module SessionMutations # rubocop:disable Metrics/ModuleLength -- rename/tag/delete/fork share transcript helpers
     module_function
 
     # Transcript entry types kept in fork output. Mirrors Python's
@@ -82,7 +84,9 @@ module ClaudeAgentSDK
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
       result = find_session_file_with_dir(session_id, directory)
-      raise Errno::ENOENT, "Session #{session_id} not found#{" in project directory for #{directory}" if directory}" unless result
+      unless result
+        raise Errno::ENOENT, "Session #{session_id} not found#{" in project directory for #{directory}" if directory}"
+      end
 
       path = result[0]
 
@@ -117,10 +121,14 @@ module ClaudeAgentSDK
     def fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
-      raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}" if up_to_message_id && !Sessions.valid_session_id?(up_to_message_id)
+      if up_to_message_id && !Sessions.valid_session_id?(up_to_message_id)
+        raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}"
+      end
 
       result = find_session_file_with_dir(session_id, directory)
-      raise Errno::ENOENT, "Session #{session_id} not found#{" in project directory for #{directory}" if directory}" unless result
+      unless result
+        raise Errno::ENOENT, "Session #{session_id} not found#{" in project directory for #{directory}" if directory}"
+      end
 
       file_path, project_dir = result
       file_size = File.size(file_path)
@@ -232,7 +240,9 @@ module ClaudeAgentSDK
     # @raise [Errno::ENOENT] if the source session is not found in the store
     def fork_session_via_store(session_store:, session_id:, directory: nil, up_to_message_id: nil, title: nil)
       raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
-      raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}" if up_to_message_id && !Sessions.valid_session_id?(up_to_message_id)
+      if up_to_message_id && !Sessions.valid_session_id?(up_to_message_id)
+        raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}"
+      end
 
       project_key = Sessions.project_key_for_directory(directory)
       raw = session_store.load('project_key' => project_key, 'session_id' => session_id)
@@ -382,7 +392,7 @@ module ClaudeAgentSDK
     # +derive_title+ is a callable invoked ONLY when no explicit +title+ is
     # given, so the disk path's head/tail byte scan and the store path's
     # entry-object scan each run only when needed.
-    def build_fork_lines(transcript, content_replacements, session_id, up_to_message_id, title, derive_title) # rubocop:disable Metrics/MethodLength
+    def build_fork_lines(transcript, content_replacements, session_id, up_to_message_id, title, derive_title) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/ParameterLists, Metrics/PerceivedComplexity -- single fork rewrite pass: UUID remap, truncation, title
       transcript = transcript.reject { |e| e['isSidechain'] }
       raise ArgumentError, "Session #{session_id} has no messages to fork" if transcript.empty?
 
@@ -520,7 +530,7 @@ module ClaudeAgentSDK
     end
 
     # Build a single forked entry with remapped UUIDs.
-    def build_forked_entry(original, index, total, uuid_mapping, by_uuid,
+    def build_forked_entry(original, index, total, uuid_mapping, by_uuid, # rubocop:disable Metrics/ParameterLists -- per-entry step of build_fork_lines; its state is threaded explicitly
                            forked_session_id, source_session_id, now)
       new_uuid = uuid_mapping[original['uuid']]
 
@@ -603,7 +613,9 @@ module ClaudeAgentSDK
 
     def append_to_session_global(session_id, data, file_name)
       projects_dir = File.join(Sessions.config_dir, 'projects')
-      raise Errno::ENOENT, "Session #{session_id} not found (no projects directory)" unless File.directory?(projects_dir)
+      unless File.directory?(projects_dir)
+        raise Errno::ENOENT, "Session #{session_id} not found (no projects directory)"
+      end
 
       found = Dir.children(projects_dir).any? do |child|
         candidate = File.join(projects_dir, child, file_name)