claude-agent-sdk 0.17.0 → 0.18.0

data/lib/claude_agent_sdk/sessions.rb

@@ -134,6 +134,11 @@ module ClaudeAgentSDK
     # realpath can't resolve it (e.g. the directory does not exist yet) — Ruby's
     # File.realpath raises on missing paths whereas Python's os.path.realpath is
     # lexical for the missing suffix, so expand_path restores that behavior.
+    # Known divergence: for a MISSING path Python still resolves symlinks in
+    # the existing prefix (so a deleted /tmp/proj on macOS canonicalizes to
+    # /private/tmp/proj and its project dir is found); the expand_path
+    # fallback resolves none, so deleted-directory lookups under symlinked
+    # prefixes can miss.
     def canonicalize_path(dir)
       File.realpath(dir).unicode_normalize(:nfc)
     rescue SystemCallError
@@ -153,9 +158,14 @@ module ClaudeAgentSDK
       sanitize_path(canonicalize_path(directory.nil? ? '.' : directory.to_s))
     end
 
-    # Get the Claude config directory
+    # 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.
     def config_dir
-      ENV.fetch('CLAUDE_CONFIG_DIR', File.expand_path('~/.claude'))
+      dir = ENV.fetch('CLAUDE_CONFIG_DIR', nil)
+      return dir.unicode_normalize(:nfc) if dir && !dir.empty?
+
+      File.expand_path('~/.claude').unicode_normalize(:nfc)
     end
 
     # Find the project directory for a given path
@@ -319,10 +329,13 @@ module ClaudeAgentSDK
       tag_value = tag_line ? extract_json_string_field(tag_line, 'tag', last: true) : nil
       tag_value = nil if tag_value && tag_value.empty?
 
-      # created_at from first entry's ISO timestamp (epoch ms). More reliable
-      # than stat().birthtime which is unsupported on some filesystems.
-      first_line = head.lines.first || ''
-      first_timestamp = extract_json_string_field(first_line, 'timestamp', last: false)
+      # created_at from the first ISO timestamp found in the head (epoch ms).
+      # More reliable than stat().birthtime which is unsupported on some
+      # filesystems. Scans the whole head rather than only the first line
+      # because the first record may be a metadata-only entry (e.g.
+      # permission-mode) with no timestamp field; the first user/assistant
+      # record that follows does carry one (Python #907).
+      first_timestamp = extract_json_string_field(head, 'timestamp', last: false)
       created_at = parse_iso_timestamp_ms(first_timestamp) if first_timestamp
 
       SDKSessionInfo.new(
@@ -433,7 +446,14 @@ module ClaudeAgentSDK
       file_path = find_session_file(session_id, directory)
       return [] unless file_path && File.exist?(file_path)
 
-      entries = parse_jsonl_entries(file_path)
+      begin
+        entries = parse_jsonl_entries(file_path)
+      rescue SystemCallError
+        # TOCTOU between resolution and read (file deleted by another
+        # process) — return [] like Python's except OSError, and like the
+        # sibling get_subagent_messages.
+        return []
+      end
       chain = build_conversation_chain(entries)
       messages = filter_visible_messages(chain)
 
@@ -443,6 +463,55 @@ module ClaudeAgentSDK
       messages
     end
 
+    # List subagent IDs recorded for a session on local disk (counterpart to
+    # list_subagents_from_store). Scans
+    # <projectDir>/<sessionId>/subagents/**/agent-<id>.jsonl, including nested
+    # workflows/<runId>/ paths, in sorted walk order. Mirrors the Python SDK's
+    # list_subagents (#825) — no dedupe (the store variant dedupes because
+    # adapter subkey ordering is adapter-defined; the sorted disk walk is
+    # already deterministic).
+    # @param session_id [String] The session UUID
+    # @param directory [String, nil] Working directory to search in (strictly
+    #   scopes to that project + its worktrees; nil searches all projects)
+    # @return [Array<String>] Subagent IDs
+    def list_subagents(session_id:, directory: nil)
+      return [] unless session_id.match?(UUID_RE)
+
+      subagents_dir = resolve_subagents_dir(session_id, directory)
+      return [] if subagents_dir.nil?
+
+      collect_agent_files(subagents_dir).map(&:first)
+    end
+
+    # Read a subagent's conversation messages from local disk (counterpart to
+    # get_subagent_messages_from_store). First match in sorted walk order wins
+    # when the same agent id exists at multiple depths (mirrors Python).
+    # @param session_id [String] The session UUID
+    # @param agent_id [String] The subagent ID (without the agent- prefix)
+    # @param directory [String, nil] Working directory to search in
+    # @param limit [Integer, nil] Maximum number of messages
+    # @param offset [Integer] Number of messages to skip
+    # @return [Array<SessionMessage>] Ordered messages from the subagent
+    def get_subagent_messages(session_id:, agent_id:, directory: nil, limit: nil, offset: 0)
+      return [] unless session_id.match?(UUID_RE)
+      return [] if agent_id.nil? || agent_id.empty?
+
+      subagents_dir = resolve_subagents_dir(session_id, directory)
+      return [] if subagents_dir.nil?
+
+      _id, path = collect_agent_files(subagents_dir).find { |id, _path| id == agent_id }
+      return [] if path.nil?
+
+      begin
+        entries = parse_jsonl_entries(path)
+      rescue SystemCallError
+        # TOCTOU between the walk and the read (mirrors Python's
+        # `except OSError: return []`).
+        return []
+      end
+      entries_to_subagent_messages(entries, limit, offset)
+    end
+
     # ---- SessionStore-backed reads (store counterparts to the disk readers) ----
 
     # List sessions from a SessionStore. Store-backed counterpart to
@@ -854,7 +923,10 @@ module ClaudeAgentSDK
     end
 
     def get_session_info_for_directory(file_name, directory)
-      canonical = File.realpath(directory).unicode_normalize(:nfc)
+      # canonicalize_path (not raw realpath): a nonexistent directory must
+      # canonicalize lexically and yield nil from find_project_dir — Python's
+      # os.path.realpath never raises here.
+      canonical = canonicalize_path(directory)
       project_dir = find_project_dir(canonical)
       if project_dir
         info = read_session_lite(File.join(project_dir, file_name), canonical)
@@ -876,7 +948,7 @@ module ClaudeAgentSDK
     end
 
     def list_sessions_for_directory(directory, include_worktrees)
-      path = File.realpath(directory).unicode_normalize(:nfc)
+      path = canonicalize_path(directory)
 
       worktree_paths = []
       worktree_paths = detect_worktrees(path) if include_worktrees
@@ -978,36 +1050,83 @@ module ClaudeAgentSDK
       projects_dir = File.join(config_dir, 'projects')
       return nil unless File.directory?(projects_dir)
 
+      file_name = "#{session_id}.jsonl"
+
       if directory
-        path = File.realpath(directory).unicode_normalize(:nfc)
-        project_dir = find_project_dir(path)
-        if project_dir
-          candidate = File.join(project_dir, "#{session_id}.jsonl")
-          return candidate if File.exist?(candidate)
-        end
+        path = canonicalize_path(directory)
+        found = stat_candidate(find_project_dir(path), file_name)
+        return found if found
 
-        # Try worktrees
         detect_worktrees(path).each do |wt_path|
-          pd = find_project_dir(wt_path)
-          next unless pd
+          next if wt_path == path # already tried above
 
-          candidate = File.join(pd, "#{session_id}.jsonl")
-          return candidate if File.exist?(candidate)
+          found = stat_candidate(find_project_dir(wt_path), file_name)
+          return found if found
         end
+
+        # An explicit directory strictly scopes the search — never fall
+        # through to the global scan, which could resolve an unrelated
+        # project's same-id session (mirrors Python's _resolve_session_file_path).
+        return nil
       end
 
-      # Scan all project dirs
+      # No directory provided — search all project directories.
       Dir.children(projects_dir).each do |child|
         dir = File.join(projects_dir, child)
         next unless File.directory?(dir)
 
-        candidate = File.join(dir, "#{session_id}.jsonl")
-        return candidate if File.exist?(candidate)
+        found = stat_candidate(dir, file_name)
+        return found if found
       end
 
       nil
     end
 
+    # Mirrors Python's _stat_candidate: a candidate counts only when it
+    # exists AND is non-empty — a 0-byte stub in one project dir must not
+    # stop the search when the real transcript lives under another
+    # worktree's project dir (same hazard SessionMutations.try_append guards).
+    def stat_candidate(project_dir, file_name)
+      return nil if project_dir.nil?
+
+      candidate = File.join(project_dir, file_name)
+      File.size(candidate).positive? ? candidate : nil
+    rescue SystemCallError
+      nil
+    end
+
+    # Resolve the on-disk subagents directory for a session:
+    # <projectDir>/<sessionId>/subagents (mirrors Python's
+    # _resolve_subagents_dir). nil when the session transcript can't be found.
+    def resolve_subagents_dir(session_id, directory)
+      resolved = find_session_file(session_id, directory)
+      return nil if resolved.nil?
+
+      File.join(resolved.delete_suffix('.jsonl'), 'subagents')
+    end
+
+    # Depth-first sorted walk collecting [agent_id, path] pairs for
+    # agent-<id>.jsonl files, recursing into subdirectories (e.g.
+    # workflows/<runId>/) in the same sorted interleave. Mirrors Python's
+    # _collect_agent_files: no dedupe; [] for a missing/unreadable base dir.
+    def collect_agent_files(base_dir, results = [])
+      begin
+        children = Dir.children(base_dir).sort
+      rescue SystemCallError
+        return results
+      end
+
+      children.each do |name|
+        path = File.join(base_dir, name)
+        if File.directory?(path)
+          collect_agent_files(path, results)
+        elsif File.file?(path) && name.start_with?('agent-') && name.end_with?('.jsonl')
+          results << [name.delete_prefix('agent-').delete_suffix('.jsonl'), path]
+        end
+      end
+      results
+    end
+
     def parse_jsonl_entries(file_path)
       entries = []
 
@@ -1113,7 +1232,8 @@ module ClaudeAgentSDK
     private_class_method :get_session_info_for_directory,
                          :list_sessions_for_directory, :list_all_sessions,
                          :deduplicate_sessions,
-                         :find_session_file, :parse_jsonl_entries,
+                         :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,
                          :list_sessions_via_summaries, :paginate_resolving_gaps, :resolve_gap_slot,

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -14,6 +14,8 @@ module ClaudeAgentSDK
   class SubprocessCLITransport < Transport
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
+    SKIP_VERSION_CHECK_ENV_VAR = 'CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK'
+    VERSION_CHECK_TIMEOUT_SECONDS = 2 # mirrors Python's anyio.fail_after(2)
     RECENT_STDERR_LINES_LIMIT = 20
 
     # Track live CLI subprocesses so we can terminate them when the parent Ruby
@@ -143,6 +145,37 @@ module ClaudeAgentSDK
       )
     end
 
+    # Inject W3C trace context (TRACEPARENT/TRACESTATE, plus BAGGAGE) into the
+    # subprocess env when an OTel span is active. Guard via defined? +
+    # respond_to?, not require: an active span implies the constant is loaded,
+    # and requiring here would break against the test mock / optional gem
+    # 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.
+    def inject_otel_trace_context(process_env, custom_env)
+      return unless defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:propagation)
+
+      carrier = {}
+      OpenTelemetry.propagation.inject(carrier)
+      return unless carrier.key?('traceparent')
+
+      # Active span: scrub stale inherited W3C context (CI/k8s ambient env)
+      # before writing fresh values, so an inherited TRACESTATE is never
+      # paired with a new TRACEPARENT. nil actively unsets (spawn overlay
+      # semantics — see the CLAUDECODE note in #connect; Python pops from a
+      # complete env dict instead). Explicit options.env keys always win.
+      %w[TRACEPARENT TRACESTATE].each do |key|
+        process_env[key] = nil unless custom_env.key?(key)
+      end
+      carrier.each do |key, value|
+        env_key = key.upcase
+        process_env[env_key] = value unless custom_env.key?(env_key)
+      end
+    rescue StandardError, ScriptError
+      # Best-effort tracing must never break connect() (Python: except
+      # Exception). ScriptError too: NotImplementedError < ScriptError.
+    end
+
     def build_command
       CommandBuilder.new(@cli_path, @options).build
     end
@@ -161,8 +194,18 @@ module ClaudeAgentSDK
       # 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
       # the env hash on top of the parent environment; a nil value actively unsets.
-      process_env = ENV.to_h.merge('CLAUDECODE' => nil, 'CLAUDE_AGENT_SDK_VERSION' => VERSION).merge(custom_env)
-      process_env['CLAUDE_CODE_ENTRYPOINT'] ||= 'sdk-rb'
+      # ENTRYPOINT defaults to sdk-rb regardless of inherited process env
+      # (the old ||= let an inherited 'cli' win and mis-attribute telemetry);
+      # options.env may still override it. VERSION is merged last: always
+      # set by the SDK, never overridable (Python merge-order parity).
+      process_env = ENV.to_h
+                       .merge('CLAUDECODE' => nil, 'CLAUDE_CODE_ENTRYPOINT' => 'sdk-rb')
+                       .merge(custom_env)
+                       .merge('CLAUDE_AGENT_SDK_VERSION' => VERSION)
+      # Propagate the active OTel trace context to the CLI so its spans parent
+      # under the caller's distributed trace (Python SDK #821 parity). No-op
+      # when opentelemetry is not loaded or there is no active span.
+      inject_otel_trace_context(process_env, custom_env)
       process_env['CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING'] = 'true' if @options.enable_file_checkpointing
       process_env['PWD'] = @cwd.to_s if @cwd
 
@@ -171,9 +214,22 @@ module ClaudeAgentSDK
 
       begin
         # Start process using Open3
-        opts = { chdir: @cwd&.to_s }.compact
+        # :uid mirrors Python's anyio.open_process(user=...): String username
+        # or Integer uid (Unix; requires privileges — typically root). The
+        # .compact is mandatory: uid: nil raises TypeError on every connect.
+        # On Windows spawn raises for :uid, wrapped below into
+        # CLIConnectionError — fail-loud instead of the old silent ignore.
+        opts = { chdir: @cwd&.to_s, uid: @options.user }.compact
 
         @stdin, @stdout, @stderr, @process = Open3.popen3(process_env, *cmd, opts)
+        # The CLI emits UTF-8 regardless of the parent locale. popen3 pipes
+        # default to Encoding.default_external (US-ASCII under LANG=C/LC_ALL=C
+        # — minimal Docker images, systemd, CI), which makes String#strip on
+        # multibyte CLI output raise Encoding::CompatibilityError and kill the
+        # read loop (its rescue only catches IOError). Mirrors the Python
+        # SDK's TextReceiveStream(stdout), which always decodes UTF-8.
+        @stdout&.set_encoding(Encoding::UTF_8)
+        @stderr&.set_encoding(Encoding::UTF_8)
         self.class.register_active_process(@process)
 
         # Always drain stderr to prevent pipe buffer deadlock.
@@ -209,7 +265,10 @@ module ClaudeAgentSDK
         error = CLINotFoundError.new("Claude Code not found at: #{@cli_path}")
         @exit_error = error
         raise error
-      rescue StandardError => e
+      rescue StandardError, NotImplementedError => e
+        # NotImplementedError < ScriptError, not StandardError (the trap this
+        # repo keeps hitting): spawn raises it for :uid on platforms without
+        # setuid (Windows), and it must wrap like every other spawn failure.
         error = CLIConnectionError.new("Failed to start Claude Code: #{e}")
         @exit_error = error
         raise error
@@ -219,7 +278,7 @@ module ClaudeAgentSDK
     def handle_stderr
       return unless @stderr
 
-      @stderr.each_line do |line|
+      @stderr.each_line("\n", @max_buffer_size + 1) do |line|
         line_str = line.chomp
         next if line_str.empty?
 
@@ -257,7 +316,7 @@ module ClaudeAgentSDK
     def drain_stderr_with_accumulation
       return unless @stderr
 
-      @stderr.each_line do |line|
+      @stderr.each_line("\n", @max_buffer_size + 1) do |line|
         line_str = line.chomp
         next if line_str.empty?
 
@@ -400,14 +459,21 @@ module ClaudeAgentSDK
     end
 
     def end_input
-      return unless @stdin
+      # Under @stdin_mutex like write/close (the transport's documented
+      # locking protocol; Python's end_input takes _write_lock too). The
+      # nil-guard must live INSIDE the critical section or the TOCTOU
+      # returns. NOTE: non-reentrant — close() inlines its own stdin
+      # handling and must never delegate here.
+      @stdin_mutex.synchronize do
+        return unless @stdin
 
-      begin
-        @stdin.close
-      rescue StandardError
-        # Ignore
+        begin
+          @stdin.close
+        rescue StandardError
+          # Ignore
+        end
+        @stdin = nil
       end
-      @stdin = nil
     end
 
     def read_messages(&block)
@@ -418,43 +484,59 @@ module ClaudeAgentSDK
       json_buffer = ''
 
       begin
-        @stdout.each_line do |line|
-          line_str = line.strip
-          next if line_str.empty?
-
-          json_lines = line_str.split("\n")
-
-          json_lines.each do |json_line|
-            json_line = json_line.strip
-            next if json_line.empty?
-
-            # When no partial JSON is buffered, the next line must start with
-            # `{` to be a valid stream-json message. Stray stderr-like text
+        # The limit bounds per-read allocation: a line longer than
+        # max_buffer_size+1 arrives as bounded chunks that the existing
+        # accumulation + cap machinery below handles (mirrors Python, where
+        # TextReceiveStream yields <=64KB chunks and the cap fires
+        # incrementally). +1 so an exactly-max line plus "\n" arrives whole.
+        # With UTF-8 external encoding Ruby extends a few bytes past the
+        # limit rather than splitting a multibyte char. Without the limit,
+        # an oversized line was fully allocated BEFORE the 1MB cap could
+        # fire — unbounded memory on hostile/buggy stdout.
+        @stdout.each_line("\n", @max_buffer_size + 1) do |line|
+          # Position-aware whitespace handling: a chunk of an over-limit line
+          # must keep its interior whitespace — a blanket per-chunk strip
+          # deleted spaces inside JSON strings straddling the chunk boundary
+          # and could let a just-over-cap line PARSE with bytes silently
+          # missing instead of raising. Only safe edges are trimmed: full
+          # single-chunk lines strip both ends (the common path, original
+          # behavior); a truncated line-initial chunk keeps its tail; a
+          # continuation chunk keeps its head and only drops the newline.
+          ends_line = line.end_with?("\n")
+          if json_buffer.empty?
+            chunk = ends_line ? line.strip : line.lstrip
+            next if chunk.empty?
+
+            # When no partial JSON is buffered, the line must start with `{`
+            # to be a valid stream-json message. Stray stderr-like text
             # (e.g., debug warnings the CLI occasionally writes to stdout)
             # would otherwise be appended into json_buffer, poisoning every
             # subsequent parse until the buffer overflows. Matches the Python
-            # SDK's `if not json_buffer and not json_line.startswith("{")` guard.
-            next if json_buffer.empty? && !json_line.start_with?('{')
-
-            json_buffer += json_line
-
-            if json_buffer.bytesize > @max_buffer_size
-              buffer_length = json_buffer.bytesize
-              json_buffer = ''
-              raise CLIJSONDecodeError.new(
-                "JSON message exceeded maximum buffer size",
-                StandardError.new("Buffer size #{buffer_length} exceeds limit #{@max_buffer_size}")
-              )
-            end
+            # SDK's `if not json_buffer and not json_line.startswith("{")`.
+            next unless chunk.start_with?('{')
+          else
+            chunk = ends_line ? line.chomp : line
+          end
 
-            begin
-              data = JSON.parse(json_buffer, symbolize_names: true)
-              json_buffer = ''
-              yield data
-            rescue JSON::ParserError
-              # Continue accumulating
-              next
-            end
+          json_buffer += chunk
+
+          if json_buffer.bytesize > @max_buffer_size
+            buffer_length = json_buffer.bytesize
+            json_buffer = ''
+            raise CLIJSONDecodeError.new(
+              "JSON message exceeded maximum buffer size",
+              StandardError.new("Buffer size #{buffer_length} exceeds limit #{@max_buffer_size}")
+            )
+          end
+
+          begin
+            data = JSON.parse(json_buffer, symbolize_names: true)
+            json_buffer = ''
+            yield data
+          rescue JSON::ParserError
+            # Continue accumulating (multi-line JSON, or a truncated chunk
+            # awaiting the rest of its line)
+            next
           end
         end
       rescue IOError
@@ -499,23 +581,34 @@ module ClaudeAgentSDK
     end
 
     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.
+      skip = ENV.fetch(SKIP_VERSION_CHECK_ENV_VAR, nil)
+      return if skip && !skip.empty?
+
       begin
-        stdout, stderr, = Open3.capture3(@cli_path.to_s, '-v')
-        output = (stdout.to_s + stderr.to_s).strip
+        output = capture_cli_version_output
+        # Residual divergence from Python (anchored re.match over the first
+        # 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]+)/)
           version = match[1]
           version_parts = version.split('.').map(&:to_i)
           min_parts = MINIMUM_CLAUDE_CODE_VERSION.split('.').map(&:to_i)
 
-          if version_parts < min_parts
-            warning = "Warning: Claude Code version #{version} is unsupported in the Agent SDK. " \
+          # Array has no #< — the old `version_parts < min_parts` raised
+          # NoMethodError into the blanket rescue, so the warning never fired.
+          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."
             warn warning
           end
         end
       rescue StandardError
-        # Ignore version check errors
+        # Ignore version check errors — including Timeout::Error from the
+        # probe deadline, mirroring Python's `except Exception: pass`.
       end
     end
 
@@ -525,6 +618,47 @@ module ClaudeAgentSDK
 
     private
 
+    # Run `claude -v` with a hard deadline. Arg-vector popen3 — no shell, same
+    # injection-safety as capture3. Raises Timeout::Error past
+    # VERSION_CHECK_TIMEOUT_SECONDS (swallowed by check_claude_version's
+    # blanket rescue, mirroring Python's `except Exception: pass` around
+    # anyio.fail_after(2)). Monotonic-deadline poll instead of stdlib
+    # Timeout.timeout for the same reason as wait_process_with_timeout:
+    # Thread#raise corrupts Async fiber-scheduler state, and connect runs
+    # inside the reactor. Divergence: Python takes a single stdout chunk; we
+    # 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
+      stdin, stdout, stderr, wait_thr = Open3.popen3(@cli_path.to_s, '-v')
+      stdin.close
+      drainer = Thread.new { [stdout.read, stderr.read] }
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + VERSION_CHECK_TIMEOUT_SECONDS
+      task = defined?(Async::Task) ? Async::Task.current? : nil
+      until drainer.join(0)
+        raise Timeout::Error if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        task ? task.sleep(0.05) : sleep(0.05)
+      end
+      out, err = drainer.value
+      (out.to_s + err.to_s).force_encoding(Encoding::UTF_8).scrub.strip
+    ensure
+      if wait_thr&.alive?
+        begin
+          Process.kill('TERM', wait_thr.pid)
+          Process.kill('KILL', wait_thr.pid) if !wait_thr.join(0.5) && wait_thr.alive?
+        rescue StandardError
+          # ESRCH etc. — probe already gone
+        end
+      end
+      drainer&.kill if drainer&.alive?
+      [stdout, stderr].each do |io|
+        io&.close
+      rescue StandardError
+        # already closed
+      end
+    end
+
     # Append a stderr line to the recent-stderr ring, dropping the oldest
     # entry once the buffer exceeds RECENT_STDERR_LINES_LIMIT. Used to surface the
     # last few lines in ProcessError when the CLI exits non-zero.

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -15,6 +15,17 @@ module ClaudeAgentSDK
 
     # Assert the 15 SessionStore behavioral contracts against an adapter.
     #
+    # Contracts 1-14 mirror the Python SDK's run_session_store_conformance.
+    # Contract 15 is a Ruby SDK extension locking empty-subpath delete
+    # coherence ('' == no subpath, the same addressing append/load already
+    # use in every implementation in both SDKs); it runs only for stores
+    # implementing #delete, and skip_optional: %w[delete] excludes the
+    # delete contracts wholesale. Note: a store ported 1:1 from Python's
+    # reference patterns that gates its delete cascade on
+    # `subpath is not None` will fail contract 15 — that pattern orphans
+    # subkeys (a known upstream incoherence; Python's own postgres example
+    # passes while its redis/s3 examples fail).
+    #
     # Framework-agnostic: raises ConformanceError on the first violated
     # contract, otherwise returns nil. Call it from any test framework, e.g.
     #
@@ -205,7 +216,10 @@ module ClaudeAgentSDK
       [key, sub1, sub2].each { |k| store.append(k, [entry('n' => 1)]) }
       store.delete(key.merge('subpath' => ''))
       assert(store.load(key).nil?, 'delete with empty subpath must remove the main transcript')
-      assert(store.load(sub1).nil?, 'delete with empty subpath must cascade to subkeys')
+      assert(store.load(sub1).nil?,
+             'delete with empty subpath must cascade to subkeys ' \
+             '(gate the cascade on sub.nil? || sub.empty? — a nil?-only gate, ' \
+             'the direct port of Python\'s `is not None`, orphans subkeys)')
       if has_list_sessions
         listed = store.list_sessions(key['project_key']).map { |s| s['session_id'] }
         assert(!listed.include?(key['session_id']), 'session deleted via empty subpath must not be listed')