claude-agent-sdk 0.35.0 → 0.36.0

data/lib/claude_agent_sdk/session_resume.rb

@@ -96,9 +96,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(
@@ -193,7 +193,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 +296,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 +329,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.
+    # 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)
       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
@@ -758,24 +765,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

data/lib/claude_agent_sdk/session_store.rb

@@ -94,13 +94,13 @@ module ClaudeAgentSDK
     end
 
     # List sessions for a project_key as [{ 'session_id', 'mtime' }]. Optional —
-    # if unimplemented, list_sessions_from_store raises.
+    # if unimplemented, list_sessions(session_store:) raises.
     def list_sessions(_project_key)
       raise NotImplementedError
     end
 
     # Return incrementally-maintained summaries for all sessions in one call.
-    # Optional — if unimplemented, list_sessions_from_store falls back to
+    # Optional — if unimplemented, list_sessions(session_store:) falls back to
     # list_sessions + per-session load.
     def list_session_summaries(_project_key)
       raise NotImplementedError
@@ -396,27 +396,37 @@ module ClaudeAgentSDK
             '(checkpoints are local-disk only and would diverge from the mirrored transcript)'
     end
 
-    # Path to the rel-from base where session transcripts live, honoring a
-    # CLAUDE_CONFIG_DIR override passed to the subprocess via options.env.
-    # Mirrors Sessions#config_dir but consults an explicit env override first.
+    # Path to the rel-from base where the CLI subprocess writes session
+    # transcripts: its CLAUDE_CONFIG_DIR, else ~/.claude under the home the
+    # CHILD sees. Mirrors Sessions#config_dir but resolves both through the
+    # options.env passed to the subprocess.
     #
     # Presence is detected by KEY, not value: the transport treats an explicit
     # nil value as "unset the var for the child", so the CLI then writes under
     # the default ~/.claude — not under the parent's CLAUDE_CONFIG_DIR. Empty
-    # strings get the same treatment (the Node CLI treats "" as unset).
+    # strings get the same treatment (the Node CLI treats "" as unset). A HOME
+    # in options.env likewise moves that default (see Sessions.home_dir).
+    #
+    # Returns nil when the default is needed but there is no usable home
+    # (#120). This runs at connect for every session with a session_store, so
+    # raising (as Sessions.config_dir does) would abort a fresh session over
+    # its secondary copy; the TranscriptMirrorBatcher instead reports the
+    # frames it cannot key as MirrorErrorMessage.
     def projects_dir(env_override = nil)
-      if env_override.respond_to?(:key?) &&
-         (env_override.key?('CLAUDE_CONFIG_DIR') || env_override.key?(:CLAUDE_CONFIG_DIR))
-        override = env_override['CLAUDE_CONFIG_DIR'] || env_override[:CLAUDE_CONFIG_DIR]
-        override = nil if override.respond_to?(:empty?) && override.empty?
-        # NFC like Python's _get_projects_dir(env_override) — a decomposed
-        # Unicode override would otherwise mismatch the NFC paths used for
-        # the mirror's projects-dir prefix comparison and drop every frame.
-        override = override.unicode_normalize(:nfc) if override
-        return File.join(override || File.expand_path('~/.claude'), 'projects')
-      end
-
-      File.join(Sessions.config_dir, 'projects')
+      override = if env_override.respond_to?(:key?) &&
+                    (env_override.key?('CLAUDE_CONFIG_DIR') || env_override.key?(:CLAUDE_CONFIG_DIR))
+                   env_override['CLAUDE_CONFIG_DIR'] || env_override[:CLAUDE_CONFIG_DIR]
+                 else
+                   ENV.fetch('CLAUDE_CONFIG_DIR', nil)
+                 end
+      override = nil if override.respond_to?(:empty?) && override.empty?
+      # NFC like Python's _get_projects_dir(env_override) — a decomposed
+      # Unicode override would otherwise mismatch the NFC paths used for
+      # the mirror's projects-dir prefix comparison and drop every frame.
+      return File.join(override.unicode_normalize(:nfc), 'projects') if override
+
+      home = Sessions.home_dir(env_override)
+      home && File.join(home, '.claude', 'projects').unicode_normalize(:nfc)
     end
   end
 end

data/lib/claude_agent_sdk/session_summary.rb

@@ -7,7 +7,7 @@ module ClaudeAgentSDK
   # Incremental session-summary derivation for SessionStore adapters.
   #
   # fold_session_summary lets a store maintain a per-session summary sidecar
-  # incrementally inside #append so list_sessions_from_store can fetch all
+  # incrementally inside #append so list_sessions(session_store:) can fetch all
   # metadata in a single #list_session_summaries call instead of N per-session
   # #load calls. Every derived field is append-incremental (set-once or
   # last-wins) so adapters never need to re-read previously appended entries.
@@ -69,8 +69,10 @@ module ClaudeAgentSDK
         data['created_at'] = ms if ms
 
         unless data.key?('cwd')
+          # First non-blank cwd (Sessions.presence: whitespace-only and
+          # invalidly encoded count as blank, as on the disk path).
           cwd = entry['cwd']
-          data['cwd'] = cwd if cwd.is_a?(String) && !cwd.empty?
+          data['cwd'] = cwd if cwd.is_a?(String) && presence(cwd)
         end
 
         fold_first_prompt(data, entry)
@@ -113,7 +115,10 @@ module ClaudeAgentSDK
       SDKSessionInfo.new(
         session_id: entry['session_id'],
         summary: summary,
-        last_modified: entry['mtime'],
+        # Integer epoch ms as documented, whatever shape the adapter stamped
+        # (ISO String, numeric String, Float, Time) — the value the listing
+        # orders by. Python passes entry["mtime"] through raw.
+        last_modified: Sessions.epoch_ms_mtime(entry['mtime']),
         # file_size is a JSONL byte count — meaningful only for the local-disk
         # path. Stores have no equivalent.
         file_size: nil,

data/lib/claude_agent_sdk/sessions.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'open3'
 require 'pathname'
+require_relative 'errors'
 require_relative 'session_store'
 require_relative 'session_summary'
 require_relative 'transcript_mirror_batcher'
@@ -176,11 +177,53 @@ module ClaudeAgentSDK
     # Get the Claude config directory (respects CLAUDE_CONFIG_DIR; an empty
     # value is treated as unset, matching the Node CLI and the Python SDK).
     # NFC-normalized on both branches like Python's _get_claude_config_home_dir.
+    #
+    # @raise [ConfigDirError] when CLAUDE_CONFIG_DIR is unset and there is no
+    #   usable home directory (see .home_dir) for the default ~/.claude.
+    #   Python raises too (Path.home() -> RuntimeError); `~` expansion here
+    #   raised a bare ArgumentError from deep inside every disk session API.
     def config_dir
       dir = ENV.fetch('CLAUDE_CONFIG_DIR', nil)
       return dir.unicode_normalize(:nfc) if dir && !dir.empty?
 
-      File.expand_path('~/.claude').unicode_normalize(:nfc)
+      home = home_dir
+      unless home
+        raise ConfigDirError,
+              'Cannot locate the Claude config directory: CLAUDE_CONFIG_DIR is unset and the home directory ' \
+              'could not be resolved (HOME is unset, empty or relative, and the user has no passwd entry). ' \
+              'Set CLAUDE_CONFIG_DIR to the directory holding your Claude Code data (normally ~/.claude).'
+      end
+
+      File.join(home, '.claude').unicode_normalize(:nfc)
+    end
+
+    # A usable home directory, or nil when there is none. The ONE definition
+    # of "home" for the SDK (CLI discovery, disk session APIs, the transcript
+    # mirror, store-backed resume seeding).
+    #
+    # Without +env+, the parent process's home: 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 — a path
+    # under "" or a cwd-relative dir is not where the user's data lives (and
+    # a relative CLI hit would be spawned from options.cwd, i.e. a different
+    # file), so both read as "no home".
+    #
+    # With +env+ (a ClaudeAgentOptions#env Hash), the home the CLI CHILD will
+    # see: a HOME key there wins, by key presence like the CLAUDE_CONFIG_DIR
+    # override, and must be absolute. An explicit nil (the transport unsets
+    # HOME for the child, which then falls back to its passwd entry) is also
+    # treated as no home rather than guessing that entry.
+    #
+    # @api private
+    def home_dir(env = nil)
+      home = if env.respond_to?(:key?) && (env.key?('HOME') || env.key?(:HOME))
+               env['HOME'] || env[:HOME]
+             else
+               Dir.home
+             end
+      home if home.is_a?(String) && File.absolute_path?(home)
+    rescue ArgumentError
+      nil
     end
 
     # Find the project directory for a given path
@@ -239,7 +282,11 @@ module ClaudeAgentSDK
     # top-level shape can't be checked, and dropping it would regress the
     # common case of a true entry cut by the 64KB window. Unverified blanks
     # cannot clear a previously verified value: they may be nested tool inputs.
-    def extract_top_level_string_field(text, key, last: false)
+    #
+    # +skip_blank+ passes over verified blank values too, for set-once fields
+    # the store fold only takes when non-blank (cwd): there a blank entry is
+    # absent, not a clearing entry.
+    def extract_top_level_string_field(text, key, last: false, skip_blank: false)
       positions = field_match_positions(text, key)
       positions.reverse! if last
       parsed_lines = {}
@@ -250,9 +297,9 @@ module ClaudeAgentSDK
         end
         if entry
           value = entry[key]
-          return value if value.is_a?(String)
+          return value if value.is_a?(String) && (!skip_blank || presence(value))
 
-          next # parseable line without a top-level string value: nested/false match
+          next # parseable line without a usable top-level string value: nested/false match
         end
         value = extract_json_string_value(text, value_start)
         value = presence(unescape_json_string(value)) if value
@@ -334,6 +381,8 @@ module ClaudeAgentSDK
     # a NoMethodError from deep inside (`123.match?`, `123.empty?`) — and so
     # does an invalidly encoded String, on which the regexp match itself
     # raises ArgumentError ("invalid byte sequence").
+    #
+    # @api private
     def valid_session_id?(session_id)
       session_id.is_a?(String) && session_id.valid_encoding? && session_id.match?(UUID_RE)
     end
@@ -352,12 +401,26 @@ module ClaudeAgentSDK
     # bare ArgumentError. Coerce defensively wherever an adapter mtime is
     # ordered or compared: numeric strings and ISO-8601 both order
     # correctly; anything else sorts last rather than crashing.
+    #
+    # A Time (e.g. an ActiveRecord updated_at) counts as its instant in epoch
+    # ms. Non-finite values (Infinity, "1e400") also read as 0: they cannot be
+    # ordered against real clocks nor reported as epoch ms.
     def sortable_mtime(value)
-      case value
-      when Numeric then value
-      when String then Float(value, exception: false) || parse_iso_timestamp_ms(value) || 0
-      else 0
-      end
+      ms = case value
+           when Numeric then value
+           when Time then value.to_r * 1000
+           when String then Float(value, exception: false) || parse_iso_timestamp_ms(value)
+           end
+      ms.is_a?(Numeric) && ms.real? && ms.finite? ? ms : 0
+    end
+
+    # An adapter mtime as SDKSessionInfo#last_modified promises it: Integer
+    # epoch milliseconds. Same coercion as sortable_mtime (so a row reports
+    # the value it is ordered by), truncated to whole milliseconds.
+    #
+    # @api private
+    def epoch_ms_mtime(value)
+      sortable_mtime(value).to_i
     end
 
     # Sort key shared by every session listing, disk and store: newest first,
@@ -365,6 +428,8 @@ module ClaudeAgentSDK
     # the secondary key equal mtimes (coarse adapter clocks, bulk imports)
     # ordered arbitrarily between calls and offset/limit paging could skip or
     # repeat sessions; one key also keeps the two paths in the same order.
+    #
+    # @api private
     def listing_sort_key(mtime, session_id)
       [-sortable_mtime(mtime), session_id.to_s]
     end
@@ -495,7 +560,9 @@ module ClaudeAgentSDK
                               extract_top_level_string_field(head, 'customTitle', last: true)) ||
                      presence(extract_top_level_string_field(tail, 'aiTitle', last: true) ||
                               extract_top_level_string_field(head, 'aiTitle', last: true))
-      first_prompt = extract_first_prompt_from_head(head)
+      # nil, not '', when there is no prompt — the store path's answer, and
+      # Python's (`_extract_first_prompt_from_head(head) or None`).
+      first_prompt = presence(extract_first_prompt_from_head(head))
       # lastPrompt tail entry shows what the user was most recently doing.
       summary = custom_title ||
                 presence(extract_top_level_string_field(tail, 'lastPrompt', last: true)) ||
@@ -528,7 +595,11 @@ module ClaudeAgentSDK
         # (SessionSummary.summary_entry_to_sdk_info) reports it.
         git_branch: presence(extract_json_string_field(tail, 'gitBranch', last: true) ||
                              extract_json_string_field(head, 'gitBranch', last: false)),
-        cwd: presence(extract_json_string_field(head, 'cwd', last: false)) || project_path,
+        # The first non-blank TOP-LEVEL cwd, exactly what the store fold keeps
+        # (set-once, blank skipped): taking the first match even when blank
+        # fell back to the project path where the store read a later entry's
+        # cwd, and the raw scan also matched cwd keys nested in tool inputs.
+        cwd: extract_top_level_string_field(head, 'cwd', skip_blank: true) || project_path,
         tag: tag_value,
         created_at: created_at
       )
@@ -1011,7 +1082,7 @@ module ClaudeAgentSDK
         # its mtime) rather than aborting the whole listing — matches the disk
         # path's per-file rescue and the store path's degrade-the-row contract.
         warn "Claude SDK: [SessionStore] gap-fill load failed for session #{sid}: #{e.message}"
-        return SDKSessionInfo.new(session_id: sid, summary: '', last_modified: slot[:mtime])
+        return SDKSessionInfo.new(session_id: sid, summary: '', last_modified: epoch_ms_mtime(slot[:mtime]))
       end
       return nil if entries.nil? || entries.empty?
 
@@ -1288,7 +1359,9 @@ module ClaudeAgentSDK
       return [] unless File.directory?(projects_dir)
 
       all_sessions = []
-      Dir.children(projects_dir).each do |child|
+      # Sorted: the scan order is deduplicate_sessions' last tiebreak, and
+      # Dir.children returns filesystem order.
+      Dir.children(projects_dir).sort.each do |child|
         dir = File.join(projects_dir, child)
         next unless File.directory?(dir)
 
@@ -1298,15 +1371,26 @@ module ClaudeAgentSDK
       deduplicate_sessions(all_sessions)
     end
 
+    # One entry per session_id when the same session sits in several project
+    # dirs (copied config dirs, worktrees). The newest last_modified wins; on
+    # equal mtimes the larger file (the more complete copy), and then the
+    # copy scanned first — project dirs in name order for the global listing,
+    # worktrees in `git worktree list` order (main worktree first) for a
+    # directory listing. Python keeps the first copy seen in iterdir() order
+    # (sessions.py _deduplicate_by_session_id), which is arbitrary on a tie.
     def deduplicate_sessions(sessions)
       by_id = {}
       sessions.each do |s|
         existing = by_id[s.session_id]
-        by_id[s.session_id] = s if existing.nil? || s.last_modified > existing.last_modified
+        by_id[s.session_id] = s if existing.nil? || (dedup_rank(s) <=> dedup_rank(existing)).positive?
       end
       by_id.values
     end
 
+    def dedup_rank(session)
+      [session.last_modified, session.file_size.to_i]
+    end
+
     # Probe git for the worktree list with a hard 5-second cap. A stale
     # git lock or hung network mount must not block the listing path
     # forever. Stdlib `Timeout.timeout` raises across threads via
@@ -1544,12 +1628,12 @@ module ClaudeAgentSDK
 
     private_class_method :get_session_info_for_directory,
                          :list_sessions_for_directory, :list_all_sessions,
-                         :deduplicate_sessions,
+                         :deduplicate_sessions, :dedup_rank,
                          :find_session_file, :stat_candidate, :resolve_subagents_dir,
                          :collect_agent_files, :parse_jsonl_entries,
                          :build_conversation_chain, :walk_to_leaf, :walk_to_root,
                          :filter_visible_messages, :read_head_tail, :build_session_info, :user_entry_texts,
-                         :valid_session_id?, :valid_agent_id?, :listing_sort_key, :sidechain_head?,
+                         :valid_agent_id?, :sidechain_head?,
                          :list_sessions_via_summaries, :paginate_resolving_gaps, :resolve_gap_slot,
                          :derive_info_from_entries, :mtime_from_entries, :apply_sort_limit_offset,
                          :filter_transcript_entries, :entries_to_messages,
@@ -1557,7 +1641,9 @@ module ClaudeAgentSDK
                          :import_subagent_files, :append_jsonl_file_in_batches, :collect_jsonl_files,
                          :read_agent_metadata_sidecar, :parent_ids_from_agent_metadata
 
-    # These remain accessible for SessionMutations:
-    # config_dir, sanitize_path, find_project_dir, detect_worktrees
+    # These remain accessible for SessionMutations / SessionResume:
+    # config_dir, sanitize_path, find_project_dir, detect_worktrees,
+    # valid_session_id? (mutation boundary checks), listing_sort_key
+    # (--continue candidate order)
   end
 end

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'
@@ -689,7 +688,7 @@ module ClaudeAgentSDK
       # Ignore
     end
 
-    def read_messages(&block)
+    def read_messages(&)
       return enum_for(:read_messages) unless block_given?
 
       raise CLIConnectionError, 'Not connected' unless @process && @stdout
@@ -1050,18 +1049,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

@@ -360,7 +360,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)

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -56,7 +56,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 +257,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

data/lib/claude_agent_sdk/types.rb

@@ -257,13 +257,13 @@ module ClaudeAgentSDK
       end
     end
 
-    def inspect_container(value, open, close, depth, seen, &render)
+    def inspect_container(value, open, close, depth, seen, &)
       return "#{open}#{close}" if value.empty?
       return "#{open}…(#{value.size})#{close}" if depth > INSPECT_MAX_DEPTH || seen.key?(value)
 
       seen[value] = true
       begin
-        parts = value.first(INSPECT_MAX_ITEMS).map(&render)
+        parts = value.first(INSPECT_MAX_ITEMS).map(&)
         parts << "…(+#{value.size - INSPECT_MAX_ITEMS} more)" if value.size > INSPECT_MAX_ITEMS
         "#{open}#{parts.join(', ')}#{close}"
       ensure

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.35.0'
+  VERSION = '0.36.0'
 end