claude-agent-sdk 0.35.0 → 0.37.0

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -2,7 +2,6 @@
 
 require 'json'
 require 'open3'
-require 'set'
 require 'timeout'
 require_relative 'transport'
 require_relative 'errors'
@@ -12,17 +11,26 @@ require_relative 'cli_installer'
 
 module ClaudeAgentSDK
   # Subprocess transport using Claude Code CLI
-  class SubprocessCLITransport < Transport
+  class SubprocessCLITransport < Transport # rubocop:disable Metrics/ClassLength -- subprocess lifecycle: discovery, spawn, IO, teardown
+    # @api private
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
+    # @api private
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
+    # @api private
     SKIP_VERSION_CHECK_ENV_VAR = 'CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK'
+    # @api private
     CLI_PATH_ENV_VAR = 'CLAUDE_CLI_PATH'
+    # @api private
     VERSION_CHECK_TIMEOUT_SECONDS = 2 # mirrors Python's anyio.fail_after(2)
+    # @api private
     RECENT_STDERR_LINES_LIMIT = 20
     # After stdout EOF the child has closed (or lost) its last stdout handle,
     # so it is normally already exiting; a CLI still running this long
     # afterwards is wedged and gets the same TERM -> KILL ladder as #close.
+    #
+    # @api private
     EOF_EXIT_GRACE_SECONDS = 5
+    # @api private
     EOF_TERM_GRACE_SECONDS = 2
 
     # Track live CLI subprocesses so we can terminate them when the parent Ruby
@@ -40,27 +48,36 @@ module ClaudeAgentSDK
     # `self.class.register_active_process` would otherwise reach a nil mutex and
     # raise mid-#connect, orphaning the just-spawned child. The base-class
     # at_exit handler must be able to see every subprocess, a subclass's too.
+    #
+    # @api private
     ACTIVE_PROCESSES = Set.new
+    # @api private
     ACTIVE_PROCESSES_MUTEX = Mutex.new
 
     class << self
       # Public readers (the test suite uses `described_class.active_processes`);
       # they return the shared constants so subclasses observe the same objects.
+      #
+      # @api private
       def active_processes
         ACTIVE_PROCESSES
       end
 
+      # @api private
       def active_processes_mutex
         ACTIVE_PROCESSES_MUTEX
       end
 
       # +wait_thr+ is the Process::Waiter returned by Open3.popen3.
+      #
+      # @api private
       def register_active_process(wait_thr)
         return unless wait_thr
 
         active_processes_mutex.synchronize { active_processes.add(wait_thr) }
       end
 
+      # @api private
       def deregister_active_process(wait_thr)
         return unless wait_thr
 
@@ -80,6 +97,8 @@ module ClaudeAgentSDK
       # raises (e.g. ThreadError if reached from a trap context, or a
       # concurrent-modification error from the unlocked read), honoring the
       # "never interrupt interpreter shutdown" contract.
+      #
+      # @api private
       def kill_active_processes
         active_processes.to_a.each do |wait_thr|
           next unless wait_thr.alive?
@@ -95,6 +114,7 @@ module ClaudeAgentSDK
     end
 
     def initialize(options_or_prompt = nil, options = nil)
+      super() # Transport defines no state today; keep the chain intact if it ever does
       # Support both new single-arg form and legacy two-arg form
       @options = options.nil? ? options_or_prompt : options
       @cli_path = @options.cli_path || find_cli
@@ -135,7 +155,9 @@ module ClaudeAgentSDK
     #      whatever version happens to be installed globally on the host.
     #   3. `which claude`.
     #   4. Well-known install locations.
-    def find_cli
+    #
+    # @api private
+    def find_cli # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- ordered discovery probes (env, vendored, PATH, known locations)
       env_path = ENV.fetch(CLI_PATH_ENV_VAR, nil).to_s
       unless env_path.empty?
         # Absolutize against the CURRENT working directory, which is where the
@@ -189,18 +211,17 @@ module ClaudeAgentSDK
         return path if File.file?(path) && File.executable?(path)
       end
 
-      raise CLINotFoundError.new(
-        "Claude Code not found. Install with:\n" \
-        "  npm install -g @anthropic-ai/claude-code\n" \
-        "\nIf already installed locally, try:\n" \
-        '  export PATH="$HOME/node_modules/.bin:$PATH"' \
-        "\n\nOr provide the path via ClaudeAgentOptions:\n" \
-        "  ClaudeAgentOptions.new(cli_path: '/path/to/claude')" \
-        "\n\nFor hermetic deploys (Docker/CI), vendor a pinned CLI into the project:\n" \
-        "  ClaudeAgentSDK::CLIInstaller.install_pinned  # installs #{CLIInstaller::PINNED_CLI_VERSION}" \
-        "\n\nOr point the SDK at an existing binary:\n" \
-        "  export #{CLI_PATH_ENV_VAR}=/path/to/claude"
-      )
+      raise CLINotFoundError,
+            "Claude Code not found. Install with:\n  " \
+            "npm install -g @anthropic-ai/claude-code\n" \
+            "\nIf already installed locally, try:\n  " \
+            'export PATH="$HOME/node_modules/.bin:$PATH"' \
+            "\n\nOr provide the path via ClaudeAgentOptions:\n  " \
+            "ClaudeAgentOptions.new(cli_path: '/path/to/claude')" \
+            "\n\nFor hermetic deploys (Docker/CI), vendor a pinned CLI into the project:\n  " \
+            "ClaudeAgentSDK::CLIInstaller.install_pinned  # installs #{CLIInstaller::PINNED_CLI_VERSION}" \
+            "\n\nOr point the SDK at an existing binary:\n  " \
+            "export #{CLI_PATH_ENV_VAR}=/path/to/claude"
     end
 
     # Inject W3C trace context (TRACEPARENT/TRACESTATE, plus BAGGAGE) into the
@@ -210,6 +231,8 @@ module ClaudeAgentSDK
     # group. Gate on the carrier's traceparent key (the W3C propagator writes
     # it only for a valid span context) so a baggage-only carrier or a noop
     # propagator preserves inherited env.
+    #
+    # @api private
     def inject_otel_trace_context(process_env, custom_env)
       return unless defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:propagation)
 
@@ -234,11 +257,12 @@ module ClaudeAgentSDK
       # Exception). ScriptError too: NotImplementedError < ScriptError.
     end
 
+    # @api private
     def build_command
       CommandBuilder.new(@cli_path, @options).build
     end
 
-    def connect
+    def connect # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- spawn sequence kept in order
       return if @process
 
       check_claude_version
@@ -247,7 +271,7 @@ module ClaudeAgentSDK
 
       # Build environment
       # Convert symbol keys to strings for spawn compatibility
-      custom_env = @options.env.transform_keys { |k| k.to_s }
+      custom_env = @options.env.transform_keys(&:to_s)
       # Explicitly unset CLAUDECODE to prevent "nested session" detection when the SDK
       # launches Claude Code from within an existing Claude Code terminal.
       # NOTE: Must set to nil (not just omit the key) — Ruby's spawn only overlays
@@ -313,7 +337,7 @@ module ClaudeAgentSDK
 
         # Always keep stdin open — streaming mode uses it for the control protocol
         @ready = true
-      rescue Errno::ENOENT => e
+      rescue Errno::ENOENT
         # Check if error is from cwd or CLI
         if @cwd && !File.directory?(@cwd.to_s)
           error = CLIConnectionError.new("Working directory does not exist: #{@cwd}")
@@ -333,6 +357,7 @@ module ClaudeAgentSDK
       end
     end
 
+    # @api private
     def handle_stderr
       return unless @stderr
 
@@ -376,6 +401,7 @@ module ClaudeAgentSDK
       # Stream-level error (pipe closed mid-read); the loop naturally ends here.
     end
 
+    # @api private
     def drain_stderr_with_accumulation
       return unless @stderr
 
@@ -388,7 +414,7 @@ module ClaudeAgentSDK
       end
     end
 
-    def close
+    def close # rubocop:disable Metrics/MethodLength -- teardown ordering is load-bearing
       @ready = false
       return unless @process
 
@@ -466,7 +492,9 @@ module ClaudeAgentSDK
     # graceful exit after stdin EOF, escalate TERM → KILL on timeout. Runs on
     # the reactor and suspends at several points; #close's ensure covers the
     # cancellation-abandoned case.
-    def teardown_process
+    #
+    # @api private
+    def teardown_process # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- TERM/KILL escalation and reaping; ordering is load-bearing
       cleanup_errors = []
 
       # Kill stderr thread
@@ -544,9 +572,7 @@ module ClaudeAgentSDK
       end
 
       # Log any cleanup errors (non-fatal)
-      if cleanup_errors.any?
-        warn "Claude SDK: Cleanup warnings: #{cleanup_errors.join(', ')}"
-      end
+      warn "Claude SDK: Cleanup warnings: #{cleanup_errors.join(', ')}" if cleanup_errors.any?
 
       self.class.deregister_active_process(@process)
     end
@@ -559,6 +585,8 @@ module ClaudeAgentSDK
     # left either way. The alive? guard also makes the delayed KILL
     # pid-reuse-safe: while the waiter thread reports alive (not yet reaped),
     # the pid cannot have been recycled.
+    #
+    # @api private
     def force_terminate_in_background(process, grace_seconds: 2)
       return unless process
 
@@ -577,20 +605,18 @@ module ClaudeAgentSDK
       end
 
       Thread.new do
-        begin
-          unless process.join(grace_seconds)
-            begin
-              Process.kill('KILL', pid) if process.alive?
-            rescue Errno::ESRCH
-              # Still wait for the waiter when exit raced the signal.
-            end
-            process.join(grace_seconds)
+        unless process.join(grace_seconds)
+          begin
+            Process.kill('KILL', pid) if process.alive?
+          rescue Errno::ESRCH
+            # Still wait for the waiter when exit raced the signal.
           end
-        rescue StandardError
-          nil # best-effort; retain ownership if termination/reaping failed
-        ensure
-          self.class.deregister_active_process(process) unless process.alive?
+          process.join(grace_seconds)
         end
+      rescue StandardError
+        nil # best-effort; retain ownership if termination/reaping failed
+      ensure
+        self.class.deregister_active_process(process) unless process.alive?
       end
     end
 
@@ -599,6 +625,8 @@ module ClaudeAgentSDK
     # across threads via Thread#raise and corrupts Async fiber-scheduler state
     # (close is always called inside an Async task). Yields to the current
     # Async task when one is active so the reactor keeps running.
+    #
+    # @api private
     def wait_process_with_timeout(timeout_seconds, process = @process)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
       task = defined?(Async::Task) ? Async::Task.current? : nil
@@ -614,6 +642,8 @@ module ClaudeAgentSDK
     # Process::Waiter#join(timeout): under a Fiber scheduler Ruby 3.2's
     # Thread#join ignores its timeout and never returns for a live thread
     # (probed on 3.2.0; 3.3/3.4 honor it).
+    #
+    # @api private
     def process_exited_within?(process, seconds)
       wait_process_with_timeout(seconds, process)
       true
@@ -622,7 +652,7 @@ module ClaudeAgentSDK
     end
 
     def write(data)
-      raise CLIConnectionError, "Cannot write to terminated process" if @process && !@process.alive?
+      raise CLIConnectionError, 'Cannot write to terminated process' if @process && !@process.alive?
       raise CLIConnectionError, "Cannot write to process that exited with error: #{@exit_error}" if @exit_error
 
       # Snapshot @stdin under the lock so close() nilling it concurrently is
@@ -689,7 +719,7 @@ module ClaudeAgentSDK
       # Ignore
     end
 
-    def read_messages(&block)
+    def read_messages(&) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- concurrency-sensitive read loop; kept whole on purpose
       return enum_for(:read_messages) unless block_given?
 
       raise CLIConnectionError, 'Not connected' unless @process && @stdout
@@ -748,7 +778,7 @@ module ClaudeAgentSDK
             buffer_length = json_buffer.bytesize
             json_buffer = ''
             raise CLIJSONDecodeError.new(
-              "JSON message exceeded maximum buffer size",
+              'JSON message exceeded maximum buffer size',
               StandardError.new("Buffer size #{buffer_length} exceeds limit #{@max_buffer_size}")
             )
           end
@@ -866,6 +896,7 @@ module ClaudeAgentSDK
       )
     end
 
+    # @api private
     def check_claude_version
       # Mirrors Python's os.environ.get truthiness: any non-empty value skips,
       # including '0'/'false'/' '; unset or empty string runs the check.
@@ -878,7 +909,7 @@ module ClaudeAgentSDK
         # stdout chunk): this searches anywhere in stdout+stderr, so leading
         # noise (a shim's own version line) could be mistaken for the CLI
         # version. Pre-existing shape; the check is best-effort only.
-        if match = output.match(/([0-9]+\.[0-9]+\.[0-9]+)/)
+        if (match = output.match(/([0-9]+\.[0-9]+\.[0-9]+)/))
           version = match[1]
           version_parts = version.split('.').map(&:to_i)
           min_parts = MINIMUM_CLAUDE_CODE_VERSION.split('.').map(&:to_i)
@@ -888,7 +919,7 @@ module ClaudeAgentSDK
           if (version_parts <=> min_parts).negative?
             warning = "Warning: Claude Code version #{version} at #{@cli_path} is unsupported in the Agent SDK. " \
                       "Minimum required version is #{MINIMUM_CLAUDE_CODE_VERSION}. " \
-                      "Some features may not work correctly."
+                      'Some features may not work correctly.'
             warn warning
           end
         end
@@ -915,7 +946,7 @@ module ClaudeAgentSDK
     # read both pipes to EOF (pre-existing capture3 shape), so the deadline
     # also bounds CLI exit. ensure always reaps the probe (mirrors Python's
     # finally: terminate(); wait()).
-    def capture_cli_version_output
+    def capture_cli_version_output # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- bounded subprocess probe: drained pipes, reaping
       stdin, stdout, stderr, wait_thr = Open3.popen3(@cli_path.to_s, '-v')
       stdin.close
       drainer = Thread.new { [stdout.read, stderr.read] }
@@ -1050,18 +1081,10 @@ module ClaudeAgentSDK
       end
     end
 
-    # The home directory for the well-known install probes, 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 — probing under "" or a relative path
-    # would check files that are not where the user's install lives (and a
-    # relative hit would be spawned from options.cwd, i.e. a different file).
-    # SessionResume.home_dir applies the same rule.
+    # The (parent's) home directory for the well-known install probes, or nil
+    # when none is usable — see Sessions.home_dir, the one definition.
     def home_dir
-      home = Dir.home
-      home if File.absolute_path?(home)
-    rescue ArgumentError
-      nil
+      Sessions.home_dir
     end
   end
 end

data/lib/claude_agent_sdk/tasks/claude_agent_sdk.rake

@@ -9,11 +9,18 @@ unless Rake::Task.task_defined?('claude_agent_sdk:install_cli')
     desc 'Install the Claude Code CLI into vendor/claude: the version this gem is tested with, ' \
          'or CLAUDE_CLI_VERSION=x.y.z / stable / latest'
     task :install_cli do
-      # Under Rails, anchor to the app root instead of the process cwd (the
-      # app is not booted: no :environment dependency, so this runs in a
-      # Docker build without credentials). Resolved when the task runs.
-      root = Rails.root if defined?(Rails) && Rails.respond_to?(:root)
-      dir = root&.join('vendor', 'claude')&.to_s
+      # Install where discovery looks. An explicitly set CLIInstaller.root
+      # (config/application.rb, the Rakefile) wins: nil dir means
+      # CLIInstaller.default_dir, i.e. <root>/vendor/claude. Otherwise, under
+      # Rails, anchor to the app root instead of the process cwd — the same
+      # root the Railtie gives discovery at boot. The app is not booted here
+      # (no :environment dependency, so this runs in a Docker build without
+      # credentials), so that initializer has not run. Resolved when the
+      # task runs.
+      unless ClaudeAgentSDK::CLIInstaller.root
+        root = Rails.root if defined?(Rails) && Rails.respond_to?(:root)
+        dir = root&.join('vendor', 'claude')&.to_s
+      end
       # Not the conventional rake `VERSION`: Rails' own db:migrate uses it and
       # build environments often export it for the app's version or git SHA.
       version = ENV.fetch('CLAUDE_CLI_VERSION', '').strip

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -5,7 +5,7 @@ require_relative '../session_summary'
 
 module ClaudeAgentSDK
   # Test helpers shipped in the gem for third-party SessionStore adapter authors.
-  module Testing # rubocop:disable Metrics/ModuleLength
+  module Testing # rubocop:disable Metrics/ModuleLength -- the whole conformance suite in one module
     # Raised by run_session_store_conformance when a behavioral contract fails.
     class ConformanceError < StandardError; end
 
@@ -100,7 +100,7 @@ module ClaudeAgentSDK
 
     # -- Required: append + load -------------------------------------------
 
-    def check_append_and_load(fresh, has_list_sessions) # rubocop:disable Metrics/MethodLength
+    def check_append_and_load(fresh, has_list_sessions) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- linear assertion script
       # 1. append then load returns same entries in same order.
       store = fresh.call
       store.append(key, [entry('uuid' => 'b', 'n' => 1), entry('uuid' => 'a', 'n' => 2)])
@@ -165,7 +165,7 @@ module ClaudeAgentSDK
 
     # -- Optional: list_sessions -------------------------------------------
 
-    def check_list_sessions(fresh)
+    def check_list_sessions(fresh) # rubocop:disable Metrics/AbcSize -- linear assertion script
       # 7. list_sessions returns session_ids for project.
       store = fresh.call
       store.append({ 'project_key' => 'proj', 'session_id' => 'a' }, [entry('n' => 1)])
@@ -197,7 +197,7 @@ module ClaudeAgentSDK
 
     # -- Optional: list_session_summaries ----------------------------------
 
-    def check_list_session_summaries(fresh, has_list_sessions, has_delete) # rubocop:disable Metrics/MethodLength
+    def check_list_session_summaries(fresh, has_list_sessions, has_delete) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- linear assertion script
       # 14. persisted fold output round-trips through fold_session_summary.
       store = fresh.call
       summ_key = { 'project_key' => 'proj', 'session_id' => 'summ-sess' }
@@ -236,8 +236,10 @@ module ClaudeAgentSDK
       # Subagent appends must NOT affect the main session's summary.
       store.append(summ_key.merge('subpath' => 'subagents/agent-1'),
                    [entry('timestamp' => '2024-01-01T00:00:09.000Z', 'customTitle' => 'subagent')])
-      after_sub = summaries_by_id(store, 'proj', ['summ-sess'],
-                                  'list_session_summaries must still return one row per session after a subagent append')
+      after_sub = summaries_by_id(
+        store, 'proj', ['summ-sess'],
+        'list_session_summaries must still return one row per session after a subagent append'
+      )
       assert_eq(after_sub['summ-sess']['data'], summ['data'], 'subagent appends must not change the main summary')
       assert_eq(store.list_session_summaries('never-appended-project'), [], 'unknown project must list no summaries')
 
@@ -249,7 +251,7 @@ module ClaudeAgentSDK
 
     # -- Optional: delete --------------------------------------------------
 
-    def check_delete(fresh, has_list_subkeys, has_list_sessions) # rubocop:disable Metrics/MethodLength
+    def check_delete(fresh, has_list_subkeys, has_list_sessions) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- linear assertion script
       # 9. delete main then load returns nil (delete of never-written is a no-op).
       store = fresh.call
       store.delete('project_key' => 'proj', 'session_id' => 'never-written')
@@ -308,7 +310,7 @@ module ClaudeAgentSDK
 
     # -- Optional: list_subkeys --------------------------------------------
 
-    def check_list_subkeys(fresh)
+    def check_list_subkeys(fresh) # rubocop:disable Metrics/AbcSize -- linear assertion script
       # 12. list_subkeys returns subpaths (scoped to the session).
       store = fresh.call
       store.append(key, [entry('n' => 1)])
@@ -317,7 +319,8 @@ module ClaudeAgentSDK
       store.append({ 'project_key' => key['project_key'], 'session_id' => 'other-sess',
                      'subpath' => 'subagents/agent-x' }, [entry('n' => 1)])
       subkeys = store.list_subkeys(key)
-      assert_eq(subkeys.sort, ['subagents/agent-1', 'subagents/agent-2'], "list_subkeys must return this session's subpaths")
+      assert_eq(subkeys.sort, ['subagents/agent-1', 'subagents/agent-2'],
+                "list_subkeys must return this session's subpaths")
       assert(!subkeys.include?('subagents/agent-x'), "list_subkeys must not leak another session's subkeys")
 
       # 13. list_subkeys excludes the main transcript.
@@ -360,7 +363,7 @@ module ClaudeAgentSDK
     # Fetch summaries, asserting on the RAW rows before collapsing into a hash:
     # a store returning one row per append (every historical fold version)
     # would otherwise pass — and then surface duplicate sessions from
-    # list_sessions_from_store.
+    # list_sessions(session_store:).
     def summaries_by_id(store, project, expected_ids, message)
       rows = Array(store.list_session_summaries(project))
       assert_eq(rows.map { |s| s['session_id'] }.sort, expected_ids.sort, message)
@@ -381,7 +384,8 @@ module ClaudeAgentSDK
       return if actual == expected
 
       raise ConformanceError,
-            "SessionStore conformance failed: #{message}\n  expected: #{expected.inspect}\n  actual:   #{actual.inspect}"
+            "SessionStore conformance failed: #{message}\n  " \
+            "expected: #{expected.inspect}\n  actual:   #{actual.inspect}"
     end
 
     private_class_method :check_callback_scheduling_declaration, :check_append_and_load, :check_list_sessions,

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -44,6 +44,8 @@ module ClaudeAgentSDK
   # may remain permanently HALF-applied in the store. The drop is surfaced
   # (MirrorErrorMessage, batches_dropped?); the local transcript remains the
   # source of truth.
+  #
+  # @api private
   class TranscriptMirrorBatcher
     # Eager-flush thresholds (exposed for tests).
     MAX_PENDING_ENTRIES = 500
@@ -56,7 +58,9 @@ module ClaudeAgentSDK
     MIRROR_APPEND_BACKOFF_S = [0.2, 0.8].freeze
 
     # @param store [SessionStore] the adapter to mirror into
-    # @param projects_dir [String] base dir for file_path -> SessionKey mapping
+    # @param projects_dir [String, nil] base dir for file_path -> SessionKey
+    #   mapping; nil when it could not be resolved (every frame is then
+    #   dropped and reported via +on_error+)
     # @param on_error [#call] called as on_error.call(key, message) after a batch
     #   exhausts retries; must not raise
     # @param callback_wrapper [#call, nil] the session's
@@ -255,6 +259,20 @@ module ClaudeAgentSDK
       by_path.each do |file_path, entries|
         next if entries.empty? # avoid phantom keys in adapters that touch storage on append([])
 
+        if @projects_dir.nil?
+          # No CLAUDE_CONFIG_DIR and no usable home (SessionStores.projects_dir,
+          # #120): the frame cannot be mapped to a SessionKey. Unlike a path
+          # outside a KNOWN projects dir, this is a host misconfiguration that
+          # loses the whole mirror, so it is surfaced as a MirrorErrorMessage.
+          @dropped_batches += 1
+          message = "cannot mirror #{file_path}: the Claude config directory is unknown (CLAUDE_CONFIG_DIR is " \
+                    'unset and the home directory could not be resolved); set CLAUDE_CONFIG_DIR in the ' \
+                    'environment or options.env'
+          errors << [nil, message]
+          warn "Claude SDK: [SessionStore] #{message}"
+          next
+        end
+
         key = SessionStores.file_path_to_session_key(file_path, @projects_dir)
         if key.nil?
           @dropped_batches += 1