claude-agent-sdk 0.35.0 → 0.37.0

data/lib/claude_agent_sdk/railtie.rb

@@ -6,14 +6,25 @@ module ClaudeAgentSDK
   # `require 'rails'`), so non-Rails processes never see it.
   #
   # Deliberately minimal: it contributes the `claude_agent_sdk:*` rake tasks
-  # and nothing else. It installs nothing into callback dispatch — the
-  # generated initializer (`bin/rails g claude_agent_sdk:install`) opts in
-  # to {.callback_wrapper} explicitly, where it is visible and removable.
+  # and anchors CLI discovery to the app root, nothing else. It installs
+  # nothing into callback dispatch — the generated initializer
+  # (`bin/rails g claude_agent_sdk:install`) opts in to {.callback_wrapper}
+  # explicitly, where it is visible and removable.
   class Railtie < ::Rails::Railtie
     rake_tasks do
       load File.expand_path('tasks/claude_agent_sdk.rake', __dir__)
     end
 
+    # Find the vendored CLI under Rails.root/vendor/claude whatever the
+    # process cwd — a daemonized worker or a job runner started elsewhere
+    # would otherwise look under its own cwd and fall through to PATH.
+    # Runs before config/initializers, so an app initializer can still set
+    # CLIInstaller.root (or nil, for the cwd) itself; a root set earlier,
+    # e.g. in config/application.rb, is left alone.
+    initializer 'claude_agent_sdk.cli_installer_root', before: :load_config_initializers do |app|
+      ClaudeAgentSDK::CLIInstaller.root ||= app.root
+    end
+
     # A `callback_wrapper` (see ClaudeAgentOptions#callback_wrapper) that
     # gives SDK callbacks Rails' connection hygiene without deadlocking
     # development code reloading.

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -4,6 +4,7 @@ require 'mcp'
 
 module ClaudeAgentSDK
   # Recursively convert all hash keys to symbols
+  # @api private
   def self.deep_symbolize_keys(obj)
     case obj
     when Hash then obj.transform_keys(&:to_sym).transform_values { |v| deep_symbolize_keys(v) }
@@ -15,6 +16,7 @@ module ClaudeAgentSDK
   # Like deep_symbolize_keys, but also converts Symbol VALUES to strings so a
   # prebuilt schema written with symbols ({ type: :object, ... }) emits clean
   # wire-format JSON Schema.
+  # @api private
   def self.deep_normalize_schema(obj)
     case obj
     when Hash then obj.transform_keys(&:to_sym).transform_values { |v| deep_normalize_schema(v) }
@@ -34,6 +36,7 @@ module ClaudeAgentSDK
   # mangled into nonsense parameter lists ("additionalProperties" as a
   # required string param). A $ref-only schema without type: 'object' remains
   # indistinguishable from a params hash — declare the type alongside $ref.
+  # @api private
   def self.prebuilt_json_schema?(schema)
     return false unless schema.is_a?(Hash)
 
@@ -47,6 +50,7 @@ module ClaudeAgentSDK
   # Single source of truth for tool input schemas: prebuilt schemas are
   # normalized (symbol keys, string values); simple { name: :type } hashes
   # become a full JSON Schema with every param required (string keys).
+  # @api private
   def self.normalize_tool_schema(schema)
     return deep_normalize_schema(schema) if prebuilt_json_schema?(schema)
 
@@ -60,34 +64,29 @@ module ClaudeAgentSDK
     { type: 'object', properties: {} }
   end
 
+  # @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
 
-  # Internal: call a tool handler, reporting SystemExit / SignalException
-  # (Interrupt included) as an ordinary handler failure — re-raised as a
-  # RuntimeError (#cause holds the original) that both tools/call dispatch
-  # boundaries turn into an in-band isError result, so the pending control
-  # response is always written. Must run INSIDE the FiberBoundary.invoke
-  # block: a worker thread that dies with SystemExit has it re-raised by
-  # Ruby on the MAIN thread, tearing down the reactor, while the dispatcher
-  # only sees Async::Stop — a rescue after the hop cannot catch it in
-  # :thread mode. A callback_wrapper therefore observes the RuntimeError.
-  # Deliberately not `rescue Exception`: cancellation (Async::Stop, and
-  # InlineCancellation at an :inline suspension point) must propagate.
+  # Internal: expand a tool handler's String shorthand into a single text
+  # block. Every other value passes through untouched — Hash results behave
+  # exactly as before, and any other non-Hash value still gets the "must
+  # return a hash" diagnostic from the caller. Applied inside the callback
+  # dispatch at both tools/call paths, so a callback_wrapper sees the
+  # expanded Hash.
   # @api private
-  def self.call_tool_handler(handler, arguments)
-    handler.call(arguments)
-  rescue SystemExit, SignalException => e
-    raise e.message
+  def self.normalize_tool_result(result)
+    result.is_a?(String) ? { content: [{ type: 'text', text: result }] } : result
   end
 
   # SDK MCP Server - wraps official MCP::Server with block-based API
@@ -98,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
@@ -152,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
@@ -226,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
@@ -247,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))
@@ -289,12 +295,14 @@ module ClaudeAgentSDK
       # gem's Fiber scheduler is not visible to user code (which may hit
       # AR/PG); in :inline mode it runs in place on the reactor fiber.
       scheduling, wrapper = effective_callback_dispatch
-      result = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
-        ClaudeAgentSDK.call_tool_handler(tool.handler, arguments)
+      # exit / Interrupt from the handler propagate (never an isError
+      # result): see FiberBoundary.invoke_callback.
+      result = FiberBoundary.invoke_callback(scheduling: scheduling, wrapper: wrapper) do
+        ClaudeAgentSDK.normalize_tool_result(tool.handler.call(arguments))
       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
@@ -327,13 +335,13 @@ module ClaudeAgentSDK
       # as `call_tool` above: reader blocks may touch Thread.current-keyed
       # libraries (ActiveRecord, pg, ...) and must run on a plain thread.
       scheduling, wrapper = effective_callback_dispatch
-      content = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
+      content = FiberBoundary.invoke_callback(scheduling: scheduling, wrapper: wrapper) do
         resource.reader.call
       end
 
       # 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
@@ -362,12 +370,12 @@ module ClaudeAgentSDK
       # Hop off the Fiber scheduler before invoking user code — same reason
       # as `call_tool` above.
       scheduling, wrapper = effective_callback_dispatch
-      result = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
+      result = FiberBoundary.invoke_callback(scheduling: scheduling, wrapper: wrapper) do
         prompt.generator.call(arguments)
       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,13 +479,16 @@ 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.
               scheduling, wrapper = @sdk_server.effective_callback_dispatch
-              result = FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) do
-                ClaudeAgentSDK.call_tool_handler(@tool_def.handler, args)
+              # exit / Interrupt propagate past the gem (it rescues only
+              # StandardError) to Query#handle_control_request, which
+              # answers with an isError result and then re-raises them.
+              result = FiberBoundary.invoke_callback(scheduling: scheduling, wrapper: wrapper) do
+                ClaudeAgentSDK.normalize_tool_result(@tool_def.handler.call(args))
               end
 
               # Guard BEFORE flexible_fetch: on a non-Hash it raises
@@ -595,18 +607,26 @@ module ClaudeAgentSDK
   # @param name [String] Unique identifier for the tool
   # @param description [String] Human-readable description
   # @param input_schema [Hash] Schema defining input parameters
-  # @param handler [Proc] Block that implements the tool logic
+  # @param handler [Proc] Block that implements the tool logic. It returns a
+  #   String, sent to Claude as a single text block, or a Hash with a
+  #   +:content+ Array of MCP content blocks plus optional +:is_error+ /
+  #   +:structured_content+. Use the Hash form for error results, structured
+  #   output, images, or several blocks.
   # @return [SdkMcpTool] Tool definition
   #
-  # @example Simple tool
+  # @example Simple tool (a String return becomes one text block)
+  #   tool = create_tool('greet', 'Greet a user', { name: :string }) do |args|
+  #     "Hello, #{args[:name]}!"
+  #   end
+  #
+  # @example The same tool in the Hash form
   #   tool = create_tool('greet', 'Greet a user', { name: :string }) do |args|
   #     { content: [{ type: 'text', text: "Hello, #{args[:name]}!" }] }
   #   end
   #
   # @example Tool with multiple parameters
   #   tool = create_tool('add', 'Add two numbers', { a: :number, b: :number }) do |args|
-  #     result = args[:a] + args[:b]
-  #     { content: [{ type: 'text', text: "Result: #{result}" }] }
+  #     "Result: #{args[:a] + args[:b]}"
   #   end
   #
   # @example Tool with error handling

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
@@ -34,7 +36,7 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id is invalid or title is empty
     # @raise [Errno::ENOENT] if the session file cannot be found
     def rename_session(session_id:, title:, directory: nil)
-      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
       stripped = title.strip
       raise ArgumentError, 'title must be non-empty' if stripped.empty?
@@ -55,7 +57,7 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
     # @raise [Errno::ENOENT] if the session file cannot be found
     def tag_session(session_id:, tag:, directory: nil)
-      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
       if tag
         sanitized = sanitize_unicode(tag).strip
@@ -79,10 +81,12 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id is invalid
     # @raise [Errno::ENOENT] if the session file cannot be found
     def delete_session(session_id:, directory: nil)
-      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      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]
 
@@ -115,12 +119,16 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id or up_to_message_id is invalid
     # @raise [Errno::ENOENT] if the session file cannot be found
     def fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil)
-      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      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 && !up_to_message_id.match?(Sessions::UUID_RE)
+      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)
@@ -159,7 +167,7 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id is invalid or title is empty
     # @raise [Errno::ENOENT] if the session is not found in the store
     def rename_session_via_store(session_store:, session_id:, title:, directory: nil)
-      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
       stripped = title.strip
       raise ArgumentError, 'title must be non-empty' if stripped.empty?
@@ -183,7 +191,7 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
     # @raise [Errno::ENOENT] if the session is not found in the store
     def tag_session_via_store(session_store:, session_id:, tag:, directory: nil)
-      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
 
       if tag
         sanitized = sanitize_unicode(tag).strip
@@ -213,7 +221,7 @@ module ClaudeAgentSDK
     #
     # @raise [ArgumentError] if session_id is invalid
     def delete_session_via_store(session_store:, session_id:, directory: nil)
-      raise ArgumentError, "Invalid session_id: #{session_id}" unless session_id.match?(Sessions::UUID_RE)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_id)
       return unless SessionStore.implements?(session_store, :delete)
 
       key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
@@ -231,8 +239,10 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if session_id/up_to_message_id is invalid or the session has no messages
     # @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 session_id.match?(Sessions::UUID_RE)
-      raise ArgumentError, "Invalid up_to_message_id: #{up_to_message_id}" if up_to_message_id && !up_to_message_id.match?(Sessions::UUID_RE)
+      raise ArgumentError, "Invalid session_id: #{session_id}" unless Sessions.valid_session_id?(session_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)

data/lib/claude_agent_sdk/session_resume.rb

@@ -17,6 +17,8 @@ module ClaudeAgentSDK
   # +config_dir+ is a temp directory laid out like ~/.claude/ — point the
   # subprocess at it via CLAUDE_CONFIG_DIR. +resume_session_id+ is passed as
   # --resume. Call #cleanup after the subprocess exits to remove the temp dir.
+  #
+  # @api private
   class MaterializedResume
     attr_reader :config_dir, :resume_session_id
 
@@ -40,7 +42,7 @@ module ClaudeAgentSDK
       ['.credentials.json', '.claude.json', 'settings.json', 'cowork_settings.json'].each do |name|
         FileUtils.rm_f(File.join(@config_dir, name))
       end
-      warn "Claude SDK: transcript mirror dropped batches; the session store copy is incomplete. " \
+      warn 'Claude SDK: transcript mirror dropped batches; the session store copy is incomplete. ' \
            "Preserving the session transcript under #{File.join(@config_dir, 'projects')} instead of " \
            'deleting it — import it into your session store, then remove the directory.'
     rescue StandardError => e
@@ -55,7 +57,9 @@ module ClaudeAgentSDK
   # store. The CLI only resumes from a local file. This module loads the session
   # from the store, writes it to a temp dir laid out like ~/.claude/, and returns
   # the path so the caller can point the subprocess at it via CLAUDE_CONFIG_DIR.
-  module SessionResume # rubocop:disable Metrics/ModuleLength
+  #
+  # @api private
+  module SessionResume # rubocop:disable Metrics/ModuleLength -- resume materialization and its helpers
     # User settings files seeded into the temp config dir. cowork_settings.json
     # is the alternate filename the CLI reads in cowork-plugins mode.
     SEEDED_SETTINGS_FILES = ['settings.json', 'cowork_settings.json'].freeze
@@ -96,9 +100,9 @@ module ClaudeAgentSDK
     # Build a TranscriptMirrorBatcher for a configured session_store. Shared by
     # both entry points (Client#install_transcript_mirror and the one-shot
     # query()) so projects_dir resolution and the eager/batched threshold choice
-    # live in one place. +env+ supplies the CLAUDE_CONFIG_DIR override used to
-    # locate the projects dir (already repointed at the temp dir when resuming
-    # from a store). Eager flush mode zeroes the buffer thresholds so every
+    # live in one place. +env+ supplies the CLAUDE_CONFIG_DIR / HOME overrides
+    # used to locate the projects dir (already repointed at the temp dir when
+    # resuming from a store). Eager flush mode zeroes the buffer thresholds so every
     # transcript_mirror frame triggers a background flush.
     def build_mirror_batcher(store:, env:, on_error:, eager: false, callback_wrapper: nil)
       TranscriptMirrorBatcher.new(
@@ -116,7 +120,7 @@ module ClaudeAgentSDK
     # (no store, no resume/continue, store has no entries, or the resolved
     # session id is not a valid UUID) — the caller then falls through to the
     # normal spawn path. Raises RuntimeError if a store call fails or times out.
-    def materialize_resume_session(options)
+    def materialize_resume_session(options) # rubocop:disable Metrics/AbcSize -- materialization sequence kept in order
       store = options.session_store
       return nil if store.nil?
       return nil if options.resume.nil? && !options.continue_conversation
@@ -155,7 +159,9 @@ module ClaudeAgentSDK
         # so it can authenticate. Missing files are fine (API-key auth, etc.).
         copy_auth_files(tmp_base, options.env)
 
-        materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper) if SessionStore.implements?(store, :list_subkeys)
+        if SessionStore.implements?(store, :list_subkeys)
+          materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper)
+        end
       rescue Exception # rubocop:disable Lint/RescueException
         # Any failure after mkdtemp leaves tmp_base (which may already hold a
         # .credentials.json copy) on disk with no path for the caller to clean
@@ -172,7 +178,7 @@ module ClaudeAgentSDK
 
     # Load entries for session_id; return [session_id, entries] or nil if empty.
     # Callers pass the result through encode_candidate before writing.
-    def load_candidate(store, project_key, session_id, timeout_s, scheduling, wrapper)
+    def load_candidate(store, project_key, session_id, timeout_s, scheduling, wrapper) # rubocop:disable Metrics/ParameterLists -- store-call context (timeout, scheduling, wrapper) threaded explicitly
       entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}", scheduling, wrapper) do
         store.load('project_key' => project_key, 'session_id' => session_id)
       end
@@ -185,7 +191,7 @@ module ClaudeAgentSDK
     # transcripts are mirrored as ordinary top-level keys and often have the
     # highest mtime, so walk newest->oldest and skip them so --continue resumes
     # the user's conversation, not a subagent's.
-    def resolve_continue_candidate(store, project_key, timeout_s, scheduling, wrapper)
+    def resolve_continue_candidate(store, project_key, timeout_s, scheduling, wrapper) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- newest-first walk with sidechain and validity skips
       sessions = with_timeout(timeout_s, 'SessionStore#list_sessions', scheduling, wrapper) do
         store.list_sessions(project_key)
       end
@@ -193,7 +199,10 @@ module ClaudeAgentSDK
 
       sidechain_flags = sidechain_flags_from_summaries(store, project_key, timeout_s, scheduling, wrapper)
 
-      sessions.sort_by { |s| -Sessions.sortable_mtime(s['mtime']) }.each do |cand|
+      # Same order as the listings (#78): newest first, equal mtimes by
+      # session_id — sort_by is unstable, so an mtime-only key let equal
+      # mtimes resume whichever session the adapter happened to list first.
+      sessions.sort_by { |s| Sessions.listing_sort_key(s['mtime'], s['session_id']) }.each do |cand|
         sid = cand['session_id']
         next unless sid.is_a?(String) && sid.match?(Sessions::UUID_RE)
         # Skip known sidechains without downloading their transcript: the
@@ -293,8 +302,8 @@ module ClaudeAgentSDK
     # thread-hop bound still applies. The session's callback_wrapper
     # composes inside the bound (see FiberBoundary.invoke); a wrapper-raised
     # error surfaces like a store error, with the same context message.
-    def with_timeout(timeout_s, what, scheduling = :thread, wrapper = nil, &block)
-      FiberBoundary.invoke(timeout: timeout_s, scheduling: scheduling, wrapper: wrapper, &block)
+    def with_timeout(timeout_s, what, scheduling = :thread, wrapper = nil, &)
+      FiberBoundary.invoke(timeout: timeout_s, scheduling: scheduling, wrapper: wrapper, &)
     rescue FiberBoundary::JoinTimeout
       raise "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
     rescue RuntimeError
@@ -326,13 +335,17 @@ module ClaudeAgentSDK
     # .claude.json lives at $CLAUDE_CONFIG_DIR/.claude.json when set, else
     # ~/.claude.json (NOT ~/.claude/.claude.json).
     #
-    # Without a usable home (see .home_dir) the home-relative sources are
-    # skipped like missing files: they cannot exist, and raising here aborted
-    # every store-backed resume on a HOME-less host — even API-key auth,
-    # which needs none of them.
-    def copy_auth_files(tmp_base, opt_env)
+    # Both are resolved as the CHILD will see them: CLAUDE_CONFIG_DIR via
+    # env_value, and "~" as the HOME in options.env when it sets one (see
+    # Sessions.home_dir) — seeding from the parent's home would copy another
+    # user's credentials and settings than the ones the CLI would have read.
+    # Without a usable home the home-relative sources are skipped like
+    # missing files: they cannot exist, and raising here aborted every
+    # store-backed resume on a HOME-less host — even API-key auth, which
+    # needs none of them.
+    def copy_auth_files(tmp_base, opt_env) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- each auth source is optional and copied independently
       caller_config_dir = env_value(opt_env, 'CLAUDE_CONFIG_DIR')
-      home = caller_config_dir ? nil : home_dir
+      home = caller_config_dir ? nil : Sessions.home_dir(opt_env)
       source_config_dir = caller_config_dir || (home && File.join(home, '.claude'))
 
       # read_if_present returns raw bytes; the credentials path parses and
@@ -354,7 +367,9 @@ module ClaudeAgentSDK
       write_redacted_credentials(creds_json, File.join(tmp_base, '.credentials.json'))
 
       claude_json_dir = caller_config_dir || home
-      copy_if_present(File.join(claude_json_dir, '.claude.json'), File.join(tmp_base, '.claude.json')) if claude_json_dir
+      if claude_json_dir
+        copy_if_present(File.join(claude_json_dir, '.claude.json'), File.join(tmp_base, '.claude.json'))
+      end
 
       # User settings carry apiKeyHelper (a fourth auth mechanism alongside
       # .credentials.json / Keychain / env vars) plus the user's env, hooks and
@@ -577,7 +592,7 @@ module ClaudeAgentSDK
     end
 
     # Load and write all subagent transcripts/metadata under session_id.
-    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper)
+    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper) # rubocop:disable Metrics/ParameterLists -- store-call context (timeout, scheduling, wrapper) threaded explicitly
       session_dir = File.join(project_dir, session_id)
       subkeys = with_timeout(timeout_s, "SessionStore#list_subkeys for session #{session_id}", scheduling, wrapper) do
         store.list_subkeys('project_key' => project_key, 'session_id' => session_id)
@@ -591,7 +606,8 @@ module ClaudeAgentSDK
           next
         end
 
-        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}", scheduling, wrapper) do
+        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}",
+                                   scheduling, wrapper) do
           store.load('project_key' => project_key, 'session_id' => session_id, 'subpath' => subpath)
         end
         next if sub_entries.nil? || sub_entries.empty?
@@ -627,7 +643,7 @@ module ClaudeAgentSDK
     def encode_agent_metadata(meta_content, subpath)
       JSON.generate(meta_content)
     rescue JSON::JSONError => e
-      warn "Claude SDK: [SessionStore] resume: skipping unserializable agent metadata " \
+      warn 'Claude SDK: [SessionStore] resume: skipping unserializable agent metadata ' \
            "for subpath #{subpath} (#{e.class}: #{e.message})"
       nil
     end
@@ -758,24 +774,12 @@ module ClaudeAgentSDK
       value && (!value.respond_to?(:empty?) || !value.empty?) ? value : nil
     end
 
-    # The parent's home directory, or nil when none is usable. Dir.home raises
-    # ArgumentError when HOME is unset and the uid has no passwd entry (docker
-    # --user in a minimal image), and returns an empty or relative HOME
-    # verbatim — reading under "" or a cwd-relative path would seed files the
-    # CLI never looks at. SubprocessCLITransport#home_dir applies the same rule.
-    def home_dir
-      home = Dir.home
-      home if File.absolute_path?(home)
-    rescue ArgumentError
-      nil
-    end
-
     private_class_method :load_candidate, :resolve_continue_candidate, :with_timeout, :write_jsonl,
                          :copy_auth_files, :write_redacted_credentials, :read_keychain_credentials,
                          :capture_with_timeout, :materialize_subkeys, :write_subagent_files,
                          :resolve_dir, :read_if_present, :chmod_owner_only, :copy_if_present, :env_value,
                          :strip_settings_for_resume, :parse_settings_bytes, :mask_surrogate_escapes,
-                         :redacted_credentials, :home_dir, :encode_candidate, :encode_jsonl_lines, :encode_entry,
+                         :redacted_credentials, :encode_candidate, :encode_jsonl_lines, :encode_entry,
                          :encode_agent_metadata
   end
 end