claude-agent-sdk 0.33.0 → 0.34.0

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -61,6 +61,8 @@ module ClaudeAgentSDK
   end
 
   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)
     case type
     when :string, String then { type: 'string' }
     when :integer, Integer then { type: 'integer' }
@@ -70,6 +72,24 @@ module ClaudeAgentSDK
     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.
+  # @api private
+  def self.call_tool_handler(handler, arguments)
+    handler.call(arguments)
+  rescue SystemExit, SignalException => e
+    raise e.message
+  end
+
   # SDK MCP Server - wraps official MCP::Server with block-based API
   #
   # Unlike external MCP servers that run as separate processes, SDK MCP servers
@@ -79,6 +99,19 @@ 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
+    # 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.
+    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')"
+        end
+
+        super
+      end
+    end
+
     attr_reader :name, :version, :tools, :resources, :prompts, :mcp_server
 
     # Default for where user handlers run when this server is invoked
@@ -257,7 +290,7 @@ module ClaudeAgentSDK
       # 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
-        tool.handler.call(arguments)
+        ClaudeAgentSDK.call_tool_handler(tool.handler, arguments)
       end
 
       # Guard before flexible_fetch: it raises on non-Hash inputs.
@@ -376,6 +409,15 @@ module ClaudeAgentSDK
       # mode at call time — same pattern as prompt classes.
       sdk_server = self
       tools.map do |tool_def|
+        # 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')"
+        end
+
         # Create a new class that extends MCP::Tool
         Class.new(MCP::Tool) do
           @tool_def = tool_def
@@ -407,11 +449,11 @@ module ClaudeAgentSDK
                 schema = ClaudeAgentSDK.normalize_tool_schema(@tool_def.input_schema)
                 schema = schema.except(:required) if schema[:required].is_a?(Array) && schema[:required].empty?
                 begin
-                  MCP::Tool::InputSchema.new(schema)
+                  ToolInputSchema.new(schema)
                 rescue ArgumentError => e
                   warn "Claude SDK: tool '#{@tool_def.name}' schema not draft4-compatible " \
                        "(#{e.message.lines.first&.strip}); argument validation disabled for this tool"
-                  MCP::Tool::InputSchema.new({ type: 'object', properties: {} })
+                  ToolInputSchema.new({ type: 'object', properties: {} })
                 end
               end
             end
@@ -434,7 +476,7 @@ module ClaudeAgentSDK
               # 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
-                @tool_def.handler.call(args)
+                ClaudeAgentSDK.call_tool_handler(@tool_def.handler, args)
               end
 
               # Guard BEFORE flexible_fetch: on a non-Hash it raises
@@ -453,6 +495,16 @@ module ClaudeAgentSDK
                 error: !!is_error,
                 structured_content: structured_content
               )
+            rescue StandardError => e
+              # Report handler failures in-band HERE rather than letting them
+              # reach the gem: mcp >= 1.2 deliberately drops e.message from
+              # its "Internal error calling tool X" wrapper (CWE-209), which
+              # would hide the text the model needs to self-correct. Bare
+              # e.message like Python's str(e) and #call_tool — no prefix.
+              # Nothing gem-internal can be swallowed here today: handlers get
+              # no server_context, so MCP::CancelledError never originates
+              # inside this method. Revisit if cancellation is ever plumbed in.
+              MCP::Tool::Response.new([{ type: 'text', text: e.message }], error: true)
             end
           end
         end

data/lib/claude_agent_sdk/session_mutations.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'securerandom'
 require 'fileutils'
+require 'tempfile'
 require_relative 'sessions'
 require_relative 'session_store'
 
@@ -38,8 +39,7 @@ module ClaudeAgentSDK
       stripped = title.strip
       raise ArgumentError, 'title must be non-empty' if stripped.empty?
 
-      data = "#{JSON.generate({ type: 'custom-title', customTitle: stripped, sessionId: session_id },
-                              space_size: 0)}\n"
+      data = "#{JSON.generate({ type: 'custom-title', customTitle: stripped, sessionId: session_id })}\n"
 
       append_to_session(session_id, data, directory)
     end
@@ -64,8 +64,7 @@ module ClaudeAgentSDK
         tag = sanitized
       end
 
-      data = "#{JSON.generate({ type: 'tag', tag: tag || '', sessionId: session_id },
-                              space_size: 0)}\n"
+      data = "#{JSON.generate({ type: 'tag', tag: tag || '', sessionId: session_id })}\n"
 
       append_to_session(session_id, data, directory)
     end
@@ -137,17 +136,14 @@ module ClaudeAgentSDK
       )
 
       fork_path = File.join(project_dir, "#{forked_session_id}.jsonl")
-      io = nil
-      fd = IO.sysopen(fork_path, File::WRONLY | File::CREAT | File::EXCL, 0o600)
-      begin
-        io = IO.new(fd)
+      # Stage beside the destination, outside the *.jsonl browsing glob. A hard
+      # link publishes the closed, complete file atomically without overwriting
+      # an existing UUID (rename would replace it). Tempfile owns only the
+      # staging name, so failure cleanup never removes somebody else's session.
+      Tempfile.create(['.claude-fork-', '.tmp'], project_dir) do |io|
         io.write("#{lines.join("\n")}\n")
-      ensure
-        if io
-          io.close
-        else
-          IO.for_fd(fd).close rescue nil # rubocop:disable Style/RescueModifier
-        end
+        io.close
+        File.link(io.path, fork_path)
       end
 
       ForkSessionResult.new(session_id: forked_session_id)
@@ -161,6 +157,7 @@ module ClaudeAgentSDK
     # by entry["uuid"] (per the SessionStore#append contract) treat it correctly.
     #
     # @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)
 
@@ -168,6 +165,7 @@ module ClaudeAgentSDK
       raise ArgumentError, 'title must be non-empty' if stripped.empty?
 
       key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
+      ensure_store_session_exists(session_store, key)
       session_store.append(key, [{
                              'type' => 'custom-title',
                              'customTitle' => stripped,
@@ -183,6 +181,7 @@ module ClaudeAgentSDK
     # Unicode-sanitized before storing.
     #
     # @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)
 
@@ -194,6 +193,7 @@ module ClaudeAgentSDK
       end
 
       key = { 'project_key' => Sessions.project_key_for_directory(directory), 'session_id' => session_id }
+      ensure_store_session_exists(session_store, key)
       session_store.append(key, [{
                              'type' => 'tag',
                              'tag' => tag || '',
@@ -253,6 +253,27 @@ module ClaudeAgentSDK
 
     # -- Private helpers --
 
+    # Raise Errno::ENOENT (as the disk counterparts and fork_session_via_store
+    # do) unless the store holds entries for +key+. Without this probe, a
+    # rename/tag of a typo'd or stale id APPENDED metadata to a never-written
+    # key, creating a phantom session — permanent on WORM/append-only stores.
+    #
+    # #load is the probe because it is the only exact per-session existence
+    # check the contract offers: it is required, and returns nil for a key
+    # that was never written. The optional methods don't fit: list_subkeys
+    # returns [] for "no subagents" and "no session" alike,
+    # list_session_summaries is an advisory sidecar that may be stale, and
+    # list_sessions scans the whole project (no cheaper than one load in the
+    # reference adapters).
+    #
+    # Check-then-act: a concurrent delete between this probe and the append
+    # can still recreate the key. That window is inherent to the store API
+    # (there is no conditional append), so no locking is attempted.
+    def ensure_store_session_exists(session_store, key)
+      entries = session_store.load(key)
+      raise Errno::ENOENT, "Session #{key['session_id']} not found" if entries.nil? || entries.empty?
+    end
+
     # Locate the JSONL file for a session and return [file_path, project_dir].
     def find_session_file_with_dir(session_id, directory)
       file_name = "#{session_id}.jsonl"
@@ -602,7 +623,10 @@ module ClaudeAgentSDK
       File.open(path, File::WRONLY | File::APPEND) do |file|
         return false if file.stat.size.zero? # rubocop:disable Style/ZeroLengthPredicate
 
-        file.write(data)
+        # The final JSONL record need not have a newline (or may be truncated).
+        # Append the boundary and metadata together, without a racy read/check
+        # or requiring read access. Readers already ignore empty lines.
+        file.write("\n#{data}")
         true
       end
     rescue Errno::ENOENT, Errno::ENOTDIR
@@ -644,6 +668,7 @@ module ClaudeAgentSDK
                          :parse_fork_transcript, :derive_fork_title, :build_forked_entry, :resolve_parent_uuid,
                          :append_to_session, :append_to_session_in_directory,
                          :append_to_session_global, :try_append, :sanitize_unicode, :unicode_category,
-                         :iso_now, :build_fork_lines, :partition_fork_entries, :derive_title_from_entries
+                         :iso_now, :build_fork_lines, :partition_fork_entries, :derive_title_from_entries,
+                         :ensure_store_session_exists
   end
 end

data/lib/claude_agent_sdk/session_resume.rb

@@ -138,18 +138,18 @@ module ClaudeAgentSDK
           # prevent traversal and match every other resume path.
           return nil unless options.resume.match?(Sessions::UUID_RE)
 
-          load_candidate(store, project_key, options.resume, timeout_s, scheduling, wrapper)
+          encode_candidate(load_candidate(store, project_key, options.resume, timeout_s, scheduling, wrapper))
         else
           resolve_continue_candidate(store, project_key, timeout_s, scheduling, wrapper)
         end
       return nil if resolved.nil?
 
-      session_id, entries = resolved
+      session_id, lines = resolved
       tmp_base = Dir.mktmpdir('claude-resume-')
       begin
         project_dir = File.join(tmp_base, 'projects', project_key)
         FileUtils.mkdir_p(project_dir)
-        write_jsonl(File.join(project_dir, "#{session_id}.jsonl"), entries)
+        write_jsonl(File.join(project_dir, "#{session_id}.jsonl"), lines)
 
         # The subprocess runs with CLAUDE_CONFIG_DIR=tmp_base; copy auth config
         # so it can authenticate. Missing files are fine (API-key auth, etc.).
@@ -171,6 +171,7 @@ module ClaudeAgentSDK
     # -- Helpers --
 
     # 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)
       entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}", scheduling, wrapper) do
         store.load('project_key' => project_key, 'session_id' => session_id)
@@ -192,7 +193,7 @@ module ClaudeAgentSDK
 
       sidechain_flags = sidechain_flags_from_summaries(store, project_key, timeout_s, scheduling, wrapper)
 
-      sessions.sort_by { |s| -sortable_mtime(s['mtime']) }.each do |cand|
+      sessions.sort_by { |s| -Sessions.sortable_mtime(s['mtime']) }.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
@@ -203,14 +204,62 @@ module ClaudeAgentSDK
         loaded = load_candidate(store, project_key, sid, timeout_s, scheduling, wrapper)
         next if loaded.nil?
 
-        first = loaded[1][0]
-        next if first.is_a?(Hash) && first['isSidechain'] == true
+        encoded = encode_candidate(loaded)
+        next if encoded.nil?
 
-        return loaded
+        # Classify from the first entry that is actually written (the first
+        # surviving object), not the raw head: a poisoned or non-Hash first
+        # entry would otherwise hide the isSidechain flag the rest carry and
+        # --continue would resume a subagent. Same rule as the disk reader.
+        head = encoded[2]
+        next if head && head['isSidechain'] == true
+
+        return encoded
       end
       nil
     end
 
+    # [session_id, entries] -> [session_id, jsonl_lines, head], or nil when no
+    # entry survives encoding; head is the first surviving Hash entry (nil if
+    # none). Encoding happens BEFORE the temp dir exists so a session whose
+    # entries are all unusable behaves exactly like an empty one: --resume
+    # falls through to the normal spawn path and --continue moves on to the
+    # next candidate.
+    def encode_candidate(loaded)
+      return nil if loaded.nil?
+
+      session_id, entries = loaded
+      what = "session #{session_id}"
+      head = nil
+      lines = entries.filter_map do |entry|
+        line = encode_entry(entry, what)
+        head ||= entry if line && entry.is_a?(Hash)
+        line
+      end
+      lines.empty? ? nil : [session_id, lines, head]
+    end
+
+    # Encode entries as JSON lines, dropping unserializable ones (see encode_entry).
+    def encode_jsonl_lines(entries, what)
+      entries.filter_map { |entry| encode_entry(entry, what) }
+    end
+
+    # Encode one store entry as a compact JSON line, or nil (with a warning
+    # naming its uuid when it has one) if it cannot be serialized:
+    # NaN/Infinity, invalid UTF-8, circular or over-deep nesting —
+    # JSON::NestingError is a ParserError, hence the JSONError rescue. Entries
+    # are opaque adapter pass-through, so one poisoned entry must not abort
+    # the whole resume: like an unusable sidecar on the disk side, an unusable
+    # entry is treated as absent.
+    def encode_entry(entry, what)
+      JSON.generate(entry)
+    rescue JSON::JSONError => e
+      uuid = entry.is_a?(Hash) ? entry['uuid'] : nil
+      warn "Claude SDK: [SessionStore] resume: skipping unserializable entry#{" uuid=#{uuid.inspect}" if uuid} " \
+           "in #{what} (#{e.class}: #{e.message})"
+      nil
+    end
+
     # session_id => true for sessions the summary sidecar marks as sidechains;
     # nil when the store doesn't implement list_session_summaries or the call
     # fails (callers then fall back to checking each full load). The per-load
@@ -231,22 +280,6 @@ module ClaudeAgentSDK
       nil
     end
 
-    # Adapters contractually report mtime as an epoch-ms Numeric (the
-    # conformance suite asserts it), but SQL timestamps naturally arrive as
-    # ISO-8601 Strings through JSON. Unary minus on a String is String#-@
-    # (frozen-string dedup), so String mtimes sorted lexicographically
-    # ASCENDING — --continue silently resumed the OLDEST session — and mixed
-    # Integer/String lists raised a bare ArgumentError. Coerce defensively:
-    # numeric strings and ISO-8601 both order correctly; anything else sorts
-    # last rather than crashing resume.
-    def sortable_mtime(value)
-      case value
-      when Numeric then value
-      when String then Float(value, exception: false) || Sessions.parse_iso_timestamp_ms(value) || 0
-      else 0
-      end
-    end
-
     # Run a store call (user code) on a plain thread bounded by timeout_s,
     # re-raising failures/timeouts as RuntimeError with context. The thread hop
     # (the default for FiberBoundary with a timeout) both keeps the async
@@ -270,12 +303,13 @@ module ClaudeAgentSDK
       raise "#{what} failed during resume materialization: #{e}"
     end
 
-    # Stream-write entries as one compact JSON line each (mode 0600).
-    def write_jsonl(path, entries)
+    # Write pre-encoded JSON lines (see encode_jsonl_lines), one per line,
+    # mode 0600.
+    def write_jsonl(path, lines)
       FileUtils.mkdir_p(File.dirname(path))
       File.open(path, 'w') do |f|
-        entries.each do |entry|
-          f.write(JSON.generate(entry))
+        lines.each do |line|
+          f.write(line)
           f.write("\n")
         end
       end
@@ -291,14 +325,20 @@ module ClaudeAgentSDK
     # cowork_settings.json live under the config dir (default ~/.claude/), while
     # .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)
       caller_config_dir = env_value(opt_env, 'CLAUDE_CONFIG_DIR')
-      source_config_dir = caller_config_dir || File.join(Dir.home, '.claude')
+      home = caller_config_dir ? nil : home_dir
+      source_config_dir = caller_config_dir || (home && File.join(home, '.claude'))
 
       # read_if_present returns raw bytes; the credentials path parses and
       # re-serializes JSON, so hand it a UTF-8-tagged string (invalid bytes
       # simply fail to parse and get written through, as before).
-      creds_bytes = read_if_present(File.join(source_config_dir, '.credentials.json'))
+      creds_bytes = source_config_dir && read_if_present(File.join(source_config_dir, '.credentials.json'))
       creds_json = creds_bytes&.dup&.force_encoding(Encoding::UTF_8)
 
       # macOS default keeps OAuth tokens in the Keychain, not a file. Redirecting
@@ -313,8 +353,8 @@ module ClaudeAgentSDK
 
       write_redacted_credentials(creds_json, File.join(tmp_base, '.credentials.json'))
 
-      claude_json_src = caller_config_dir ? File.join(caller_config_dir, '.claude.json') : File.join(Dir.home, '.claude.json')
-      copy_if_present(claude_json_src, File.join(tmp_base, '.claude.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
 
       # User settings carry apiKeyHelper (a fourth auth mechanism alongside
       # .credentials.json / Keychain / env vars) plus the user's env, hooks and
@@ -323,6 +363,8 @@ module ClaudeAgentSDK
       # cowork_settings.json is the alternate filename the CLI reads in
       # cowork-plugins mode. Both pass through strip_settings_for_resume so
       # plugin declarations don't reconcile against the empty tmp_base cache.
+      return unless source_config_dir
+
       transform = ->(content) { strip_settings_for_resume(content) }
       SEEDED_SETTINGS_FILES.each do |name|
         copy_if_present(File.join(source_config_dir, name), File.join(tmp_base, name), transform)
@@ -565,22 +607,40 @@ module ClaudeAgentSDK
       metadata, transcript = Sessions.split_agent_metadata(entries)
       sub_file = File.join(session_dir, "#{subpath}.jsonl")
 
-      write_jsonl(sub_file, transcript) unless transcript.empty?
+      lines = encode_jsonl_lines(transcript, "subpath #{subpath}")
+      write_jsonl(sub_file, lines) unless lines.empty?
 
       return if metadata.nil?
 
       # Strip the synthetic type field.
-      meta_content = metadata.except('type')
+      meta_json = encode_agent_metadata(metadata.except('type'), subpath)
+      return if meta_json.nil?
+
       meta_file = Sessions.agent_metadata_sidecar_path(sub_file)
       FileUtils.mkdir_p(File.dirname(meta_file))
-      File.write(meta_file, JSON.generate(meta_content))
+      File.write(meta_file, meta_json)
       chmod_owner_only(meta_file)
     end
 
-    # Reject subpaths that are empty, absolute, drive/UNC-prefixed, contain "."
-    # or ".." components or a NUL byte, or escape session_dir after resolution.
+    # An unserializable metadata sidecar is skipped (unusable = absent, as on
+    # the disk side) rather than aborting the resume.
+    def encode_agent_metadata(meta_content, subpath)
+      JSON.generate(meta_content)
+    rescue JSON::JSONError => e
+      warn "Claude SDK: [SessionStore] resume: skipping unserializable agent metadata " \
+           "for subpath #{subpath} (#{e.class}: #{e.message})"
+      nil
+    end
+
+    # Reject subpaths that are not Strings, empty, absolute, drive/UNC-prefixed,
+    # contain "." or ".." components or a NUL byte, or escape session_dir after
+    # resolution. A non-String subkey (Symbol, Integer) is an adapter contract
+    # violation: reject it like any other unsafe subkey (skip that entry)
+    # rather than guess at a coercion — calling String methods on it used to
+    # raise NoMethodError and abort the whole resume.
     def safe_subpath?(subpath, session_dir)
-      return false if subpath.nil? || subpath.empty?
+      return false unless subpath.is_a?(String)
+      return false if subpath.empty?
       return false if subpath.start_with?('/', '\\')
       return false if subpath.match?(/\A[a-zA-Z]:/) # drive-prefixed (C:foo) / UNC
       return false if subpath.split(%r{[\\/]}).any? { |part| ['.', '..'].include?(part) }
@@ -698,11 +758,24 @@ module ClaudeAgentSDK
       value && (!value.respond_to?(:empty?) || !value.empty?) ? value : nil
     end
 
-    private_class_method :load_candidate, :resolve_continue_candidate, :sortable_mtime, :with_timeout, :write_jsonl,
+    # 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
+                         :redacted_credentials, :home_dir, :encode_candidate, :encode_jsonl_lines, :encode_entry,
+                         :encode_agent_metadata
   end
 end

data/lib/claude_agent_sdk/session_store.rb

@@ -29,6 +29,9 @@ module ClaudeAgentSDK
   # All keys/entries cross the adapter boundary as Hashes with STRING keys:
   #   - SessionKey: { 'project_key' => String, 'session_id' => String,
   #                   'subpath' => String (optional; omit for the main transcript) }
+  #     Subagent reads on a store without #list_subkeys synthesize the subpath
+  #     `subagents/agent-<agent_id>` from the caller's agent_id, which the SDK
+  #     first restricts to [A-Za-z0-9._-]+ (never '.' or '..').
   #   - entries: raw JSONL transcript objects (opaque pass-through blobs)
   #   - list_sessions result: [{ 'session_id' => String, 'mtime' => Integer }]
   #   - summary entries: { 'session_id', 'mtime', 'data' } (see SessionSummary)
@@ -138,6 +141,8 @@ module ClaudeAgentSDK
       return if entries.nil? || entries.empty?
 
       @mutex.synchronize do
+        key = copy_json(key)
+        entries = copy_json(entries)
         k = key_to_string(key)
         (@store[k] ||= []).concat(entries)
         now_ms = next_mtime
@@ -160,7 +165,7 @@ module ClaudeAgentSDK
     def load(key)
       @mutex.synchronize do
         entries = @store[key_to_string(key)]
-        entries&.dup
+        copy_json(entries)
       end
     end
 
@@ -187,7 +192,7 @@ module ClaudeAgentSDK
         @summaries.filter_map do |(pk, _sid), summary|
           next unless pk == project_key
 
-          { 'session_id' => summary['session_id'], 'mtime' => summary['mtime'], 'data' => summary['data'].dup }
+          copy_json(summary)
         end
       end
     end
@@ -224,7 +229,7 @@ module ClaudeAgentSDK
 
     # All entries for a key (empty array if absent).
     def get_entries(key)
-      @mutex.synchronize { (@store[key_to_string(key)] || []).dup }
+      load(key) || []
     end
 
     # Number of stored sessions (main transcripts only).
@@ -248,6 +253,17 @@ module ClaudeAgentSDK
 
     private
 
+    # JSON values are mutable down to their strings. Keep stored snapshots and
+    # returned values detached, just like a serialization-backed adapter.
+    def copy_json(value)
+      case value
+      when Hash then value.to_h { |k, v| [k, copy_json(v)] }
+      when Array then value.map { |v| copy_json(v) }
+      when String then value.dup
+      else value
+      end
+    end
+
     # True for a main-transcript key: no subpath, or an empty-string subpath
     # (which key_to_string already folds into the main key).
     def main_transcript_key?(key)

data/lib/claude_agent_sdk/session_summary.rb

@@ -126,12 +126,12 @@ module ClaudeAgentSDK
       )
     end
 
-    # Python's `x or None`: nil for nil/empty-string, else the value.
+    # Python's `x or None`, delegating to the disk path's Sessions.presence
+    # so both summary paths share ONE definition of blank (whitespace-only
+    # included). A local copy that only rejected "" let the store path list
+    # a session under an invisible whitespace summary the disk path hid.
     def presence(val)
-      return nil if val.nil?
-      return nil if val.is_a?(String) && val.empty?
-
-      val
+      Sessions.presence(val)
     end
 
     # Replicate Sessions#extract_first_prompt_from_head for a single parsed