claude-agent-sdk 0.19.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc9c6b243b2a7ac982141db36c55d510d9a08cb18caeffb5dd2d9ed59fefc42d
-  data.tar.gz: 7ce8124f1cebd923857fda75532caa8332a89d930564ff9c474e847e57fcb1d8
+  metadata.gz: 408fe2ed3f2f1f00866e3cef0b1795e67dc50dafd3292fc016985f62c10f1b6e
+  data.tar.gz: 045b04fee0681072fe7e99c81ab7a99d51d2eec362baf282a45c8d825cc38135
 SHA512:
-  metadata.gz: 7c548159588586dd908b4a51173bdf89abac417ceab753d8eb8b313095463770dbf5fc44e7af9c90dce26df651f11ae5b25eca28d755a17e2c5b68984eff1ccb
-  data.tar.gz: 0a46ae5342425411af912c98ab5f96607bdf4d8ec76f027a7388b5519c3dc7d425a79e03a4b82c7317e9f983dcd232c7375d91f23feb33ecb758289f57dcce3b
+  metadata.gz: 91b04e46d137103527e3af91d089acc01be96b69a8b0e6902eecb603654567ee826c8284ac0f9b797f180af64220ecfe0d71c3ab6f5e755e03525d596fcff85e
+  data.tar.gz: fb7e3d0a535522e98ed3c7a0180f1ac35ca5057a29dfdb3429b07cd896375672c0c94e114d92809325680f599ca39d8dee2f7fc3a658a73fabd744cf4a987946

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-07-03
+
+Design-decision fix batch (Batch C) from the 2026-07-03 full-codebase audit (`AUDIT-2026-07-03.md`, PR #43), plus three teardown-race hardenings from its adversarial review. Minor (not patch) because three fixes change observable behavior for previously-broken flows: a missing settings file with sandbox no longer raises, a raising initial prompt stream no longer notifies observers, and teardown can now preserve (instead of delete) the materialized resume dir.
+
+### Fixed
+- `Query#close` (and therefore `Client#disconnect`) is now safe to call from any thread. Calling it from a FiberBoundary worker — e.g. a tool handler, hook, or permission callback ending the session — crashed with `NoMethodError` (nil `Fiber.scheduler`) and left the read/child tasks running, hanging the enclosing reactor. A transient reactor-side watcher now serves closes marshaled from foreign threads with identical semantics; once the reactor is gone, close falls back to a direct (fiber-dead-safe) teardown. `close` is also idempotent now — concurrent or repeated closes no longer re-run teardown against half-torn-down state.
+- Eager-mode mirror failures during the last flush of a stream are reported before the `'end'` sentinel: the `MirrorErrorMessage` for an in-flight dropped batch could previously be enqueued after `'end'` and never delivered, violating the documented "failures surface as MirrorErrorMessage" guarantee.
+- Disk session listings no longer report tool-argument text as the session summary/title: the head/tail byte-scans for `summary`/`customTitle`/`aiTitle`/`lastPrompt` now verify each match against the top level of its containing JSONL line (the same keys the SessionStore fold reads), so keys nested inside tool_use inputs (subagent/teammate tool arguments) are ignored. Lines truncated at the 64KB window edge keep the raw-scan value.
+- Resume-from-store teardown no longer deletes the only copy of turns the mirror failed to persist: when the batcher dropped batches (tracked via `TranscriptMirrorBatcher#batches_dropped?` / `Query#mirror_batches_dropped?`, including drains cancelled mid-flight), the materialized temp `CLAUDE_CONFIG_DIR` is preserved — credential copies scrubbed, transcripts kept, warning with the path — instead of removed.
+- A missing settings file with `sandbox` set now warns and continues with sandbox-only settings (Python parity) instead of raising `CLIConnectionError`.
+- `Client#connect` no longer fires observer `on_error` for a raising initial Enumerator prompt: input-stream errors are swallowed-with-warn (documented `Observer#on_error` contract, `query()` and Python parity). Notifying them also marked still-live OTel traces as failed.
+- Postgres reference adapter (`examples/session_stores/postgres_session_store.rb`): all DB round-trips now serialize through an internal mutex — mirror appends run on fresh worker threads and can overlap after a send-timeout abandon, which pg's single-connection thread rules forbid. The "a single PG::Connection suffices" concurrency guidance was wrong and has been rewritten.
+
+## [0.20.0] - 2026-07-03
+
+Behavioral fix batch (Batch B) from the 2026-07-03 full-codebase audit (`AUDIT-2026-07-03.md`, PR #42). Every fix aligns code with a documented contract or Python SDK behavior and changes behavior only for inputs that previously produced wrong results, hangs, or crashes. Minor (not patch) because two fixes raise where the SDK previously reported success: a signal-killed CLI now raises `ProcessError`, and assistant messages without `message.model` now raise `MessageParseError`.
+
+### Fixed
+- A CLI process killed by a signal (OOM-kill SIGKILL, SIGSEGV, ...) now raises `ProcessError` ("Command terminated by signal N", `exit_code: -N` — Python returncode parity) instead of reporting a **truncated** response as clean end-of-stream success.
+- A trailing title-clearing entry (`{"customTitle":""}`, or whitespace-only) no longer silently drops the whole session from `list_sessions`/`get_session_info` disk listings: blank values now fall through the summary/title fallback chains exactly like the SessionStore path and Python (`or` semantics).
+- `continue_conversation: true` with a SessionStore adapter that reports mtimes as Strings (the natural SQL-timestamp-through-JSON shape) no longer silently resumes the **oldest** session: String mtimes (ISO-8601 or numeric) are coerced and ordered chronologically, and mixed Integer/String lists no longer raise a bare `ArgumentError`. The conformance suite already pins the epoch-ms Numeric contract.
+- One malformed line in a transcript head (non-Hash entry, string `message`, non-string `text`) no longer drops the whole session from disk listings — the guards ported from Python skip just the bad line. An assistant line whose tool_use input embeds `"type":"user"` can no longer donate its text as the session's first prompt.
+- A user message block that leaks `StopIteration` (e.g. `.next` on an exhausted Enumerator) no longer silently ends message reception mid-turn — previously the `ResultMessage` was dropped and `receive_response`/`query()` returned as if the turn had completed; the error now propagates.
+- Top-level `query()` now validates the prompt like `Client#query` and fails fast at the call site: a bare Hash (which would stream `[key, value]` garbage to the CLI) and non-String/non-`#each` prompts (which hung forever) raise `ArgumentError`.
+- One-shot `query()` now sends `exclude_dynamic_sections` from a preset system prompt in the initialize request (it was silently dropped; `Client` and Python both send it).
+- `ClaudeAgentOptions#dup_with` now deep-duplicates nested containers: mutating a derived variant (`variant.allowed_tools << 'Bash'`) no longer bleeds into the base options and every sibling variant — including the security-relevant allow/deny lists. Leaf objects (callbacks, SDK MCP server instances, store adapters) keep identity, mirroring `Configuration#default_options`. Container deep-dup (both here and in `Configuration#default_options` merging) now also preserves Hash/Array subclasses — a Rails `HashWithIndifferentAccess` config no longer flattens into a plain Hash whose symbol lookups silently return nil.
+- Sandbox gating in command building now matches Python's `sandbox is not None`: `sandbox: true` (the boolean toggle) no longer crashes with `NoMethodError: undefined method 'empty?' for true`, and an explicit `sandbox: false` / `{}` is forwarded to the CLI instead of silently dropped — so `sandbox: false` can actually override a sandbox enabled in the settings JSON.
+- `output_format: { type: 'json_schema' }` with a nil/absent schema no longer emits `--json-schema null` (which the CLI rejects at spawn); the flag is skipped, matching Python's `schema is not None` guard.
+- A non-Hash `message` field in a user/assistant CLI message now raises the documented `MessageParseError` instead of a raw `TypeError`.
+- Assistant messages missing `message.model` now raise `MessageParseError` (Python parity) instead of silently constructing `AssistantMessage(model: nil)`.
+
 ## [0.19.1] - 2026-07-03
 
 Zero-risk fix batch from the 2026-07-03 full-codebase audit (`AUDIT-2026-07-03.md`, PR #41).

data/README.md

@@ -68,7 +68,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.19.1'
+gem 'claude-agent-sdk', '~> 0.21.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/sessions.md

@@ -152,6 +152,12 @@ during resume materialization, default `60_000`).
 > `.claude/*` still applies (it resolves from `cwd`), and hooks/options passed
 > programmatically via `ClaudeAgentOptions` are unaffected. This matches the
 > Python and TypeScript SDKs.
+>
+> The temp dir is deleted at disconnect — **unless the mirror dropped batches**
+> (adapter failures that exhausted retries, surfaced as `MirrorErrorMessage`):
+> the store copy is then incomplete and the temp dir holds the only copy of the
+> dropped turns, so the SDK scrubs the credential copies, keeps the transcripts,
+> and warns with the preserved path so you can import them into the store.
 
 ### Implementing an adapter
 

data/lib/claude_agent_sdk/command_builder.rb

@@ -156,8 +156,13 @@ module ClaudeAgentSDK
       cmd.push("--resume-session-at", @options.resume_session_at.to_s)
     end
 
+    # Sandbox gating is `!nil?` throughout — Python's `sandbox is not None`.
+    # Booleans and {} are forwarded verbatim: an explicit `sandbox: false`
+    # must reach the CLI so it can override a sandbox enabled in the
+    # settings JSON (`sandbox: true`, the boolean toggle, used to crash on
+    # true.empty?; false and {} were silently dropped).
     def append_settings(cmd)
-      return unless @options.settings || @options.sandbox
+      return unless @options.settings || !@options.sandbox.nil?
 
       settings_hash = {}
       settings_is_path = false
@@ -167,11 +172,11 @@ module ClaudeAgentSDK
           begin
             settings_hash = JSON.parse(@options.settings)
           rescue JSON::ParserError
-            if @options.sandbox
-              settings_hash = load_settings_file(@options.settings)
-            else
+            if @options.sandbox.nil?
               settings_is_path = true
               cmd.push("--settings", @options.settings)
+            else
+              settings_hash = load_settings_file(@options.settings)
             end
           end
         elsif @options.settings.is_a?(Hash)
@@ -179,9 +184,8 @@ module ClaudeAgentSDK
         end
       end
 
-      if !settings_is_path && @options.sandbox
-        sandbox_hash = @options.sandbox.is_a?(SandboxSettings) ? @options.sandbox.to_h : @options.sandbox
-        settings_hash[:sandbox] = sandbox_hash unless sandbox_hash.empty?
+      if !settings_is_path && !@options.sandbox.nil?
+        settings_hash[:sandbox] = @options.sandbox.is_a?(SandboxSettings) ? @options.sandbox.to_h : @options.sandbox
       end
 
       cmd.push("--settings", JSON.generate(settings_hash)) if !settings_is_path && !settings_hash.empty?
@@ -292,6 +296,11 @@ module ClaudeAgentSDK
                else
                  @options.output_format
                end
+      # A json_schema output_format with a nil/absent schema must skip the
+      # flag — `--json-schema null` is rejected by the CLI (Python guards
+      # `schema is not None`).
+      return if schema.nil?
+
       schema_json = schema.is_a?(String) ? schema : JSON.generate(schema)
       cmd.push("--json-schema", schema_json)
     end
@@ -367,7 +376,14 @@ module ClaudeAgentSDK
     end
 
     def load_settings_file(path)
-      raise CLIConnectionError, "Settings file not found: #{path}" unless File.file?(path)
+      # Missing file: warn and continue with sandbox-only settings (Python
+      # parity: logger.warning("Settings file not found: ...") and an empty
+      # settings object). Raising here turned a misconfiguration the CLI
+      # tolerates into a hard connect failure.
+      unless File.file?(path)
+        warn "Claude SDK: Settings file not found: #{path}"
+        return {}
+      end
 
       JSON.parse(File.read(path))
     end

data/lib/claude_agent_sdk/message_parser.rb

@@ -46,6 +46,9 @@ module ClaudeAgentSDK
       tool_use_result = data[:tool_use_result]
       message_data = data[:message]
       raise MessageParseError.new("Missing message field in user message", data: data) unless message_data
+      # A non-Hash message (malformed CLI output) raised a raw TypeError from
+      # message_data[:content] instead of the documented MessageParseError.
+      raise MessageParseError.new("Invalid message field in user message (expected Hash, got #{message_data.class})", data: data) unless message_data.is_a?(Hash)
 
       content = message_data[:content]
       raise MessageParseError.new("Missing content in user message", data: data) unless content
@@ -61,19 +64,27 @@ module ClaudeAgentSDK
     end
 
     def self.parse_assistant_message(data)
-      content = data.dig(:message, :content)
+      message_data = data[:message]
+      # A non-Hash message (malformed CLI output) raised a raw TypeError from
+      # dig instead of the documented MessageParseError.
+      raise MessageParseError.new("Invalid message field in assistant message (expected Hash, got #{message_data.class})", data: data) unless message_data.is_a?(Hash)
+
+      content = message_data[:content]
       raise MessageParseError.new("Missing content in assistant message", data: data) unless content
       raise MessageParseError.new("Invalid assistant content (expected Array, got #{content.class})", data: data) unless content.is_a?(Array)
 
       content_blocks = parse_content_blocks(content, data)
       AssistantMessage.new(
         content: content_blocks,
-        model: data.dig(:message, :model),
+        # model is required, like Python — fetch raises KeyError when absent,
+        # which parse's rescue wraps into MessageParseError, instead of
+        # silently constructing model: nil.
+        model: message_data.fetch(:model),
         parent_tool_use_id: data[:parent_tool_use_id],
         error: data[:error], # authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
-        usage: data.dig(:message, :usage),
-        message_id: data.dig(:message, :id),
-        stop_reason: data.dig(:message, :stop_reason),
+        usage: message_data[:usage],
+        message_id: message_data[:id],
+        stop_reason: message_data[:stop_reason],
         session_id: data[:session_id],
         uuid: data[:uuid]
       )

data/lib/claude_agent_sdk/query.rb

@@ -77,6 +77,16 @@ module ClaudeAgentSDK
       @closed = false
       @initialization_result = nil
       @transcript_mirror_batcher = nil
+
+      # Cross-thread close marshaling (see #close). Thread::Queue is the one
+      # primitive that is both fiber-scheduler-aware on the reactor side and
+      # thread-safe on the caller side (push -> scheduler#unblock).
+      @close_requests = ::Thread::Queue.new
+      @close_watcher = nil
+      @owning_scheduler = nil
+      # First-caller-wins guard for close_now (see there).
+      @close_mutex = Mutex.new
+      @close_started = false
     end
 
     # Initialize control protocol if in streaming mode
@@ -178,7 +188,24 @@ module ClaudeAgentSDK
       parent = Async::Task.current?
       raise CLIConnectionError, 'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})' unless parent
 
+      @owning_scheduler = Fiber.scheduler
       @task = parent.async { read_messages }
+      # Reactor-side agent for #close calls arriving from foreign threads
+      # (FiberBoundary callbacks, plain user threads): Async::Task#stop needs
+      # the owning thread's Fiber.scheduler, so the off-thread caller hands the
+      # whole close over and waits. Transient: must never keep the reactor
+      # alive, and is stopped automatically when the parent task finishes.
+      # One-shot: after serving a close it is done; a reactor-side close wakes
+      # it via @close_requests.close (pop -> nil) so it exits without serving.
+      @close_watcher = parent.async(transient: true) do
+        if (reply = @close_requests.pop)
+          begin
+            close
+          ensure
+            reply << true
+          end
+        end
+      end
     end
 
     # Spawn a child task that is stopped by #close (mirrors the Python SDK's
@@ -206,6 +233,14 @@ module ClaudeAgentSDK
       @transcript_mirror_batcher = batcher
     end
 
+    # True when the mirror dropped at least one batch (store copy incomplete).
+    # Meaningful after #close, which runs the final flush. Consulted by the
+    # resume-from-store teardown to decide whether the materialized temp dir
+    # holds the only copy of some turns and must be preserved.
+    def mirror_batches_dropped?
+      !!@transcript_mirror_batcher&.batches_dropped?
+    end
+
     # Synthesize a `mirror_error` system message and put it on the SDK message
     # stream so consumers learn a mirror batch was dropped after exhausting
     # retries. Non-blocking: the message queue is unbounded, so unlike the
@@ -1139,7 +1174,11 @@ module ClaudeAgentSDK
     def receive_messages(&block)
       return enum_for(:receive_messages) unless block
 
-      loop do
+      # NOT Kernel#loop: it rescues StopIteration, so a user block leaking one
+      # (e.g. calling .next on an exhausted Enumerator) would silently end
+      # reception — ResultMessage dropped, the query reported as complete, and
+      # on_error never fired. `while` propagates it like any other error.
+      while true # rubocop:disable Style/InfiniteLoop
         message = @message_queue.dequeue
         break if message[:type] == 'end'
         raise message[:error] if message[:type] == 'error'
@@ -1148,8 +1187,45 @@ module ClaudeAgentSDK
       end
     end
 
-    # Close the query and transport
+    # Close the query and transport.
+    #
+    # Callable from any thread. Async::Task#stop needs the reactor's
+    # Fiber.scheduler (per-thread), which foreign callers — FiberBoundary
+    # workers running a tool handler / hook that calls client.disconnect, or
+    # plain user threads — don't have; stopping from one raised NoMethodError
+    # and left the read/child tasks running. Such callers hand the close to
+    # the reactor-side watcher (spawned in #start) and wait for it to finish,
+    # so close semantics are identical regardless of the calling thread.
     def close
+      if @close_watcher&.alive? && !Fiber.scheduler.equal?(@owning_scheduler)
+        marshal_close_to_reactor
+      else
+        # Same scheduler (reactor-side caller, including the watcher itself),
+        # or no live watcher: when the reactor is gone its task fibers are
+        # dead, so stopping them no longer touches Fiber.scheduler.
+        close_now
+      end
+    end
+
+    private
+
+    def close_now
+      # First caller wins: a reactor-side close racing a watcher-served
+      # foreign close (or a repeated disconnect) must not re-run teardown
+      # against half-torn-down state — transport.close can suspend mid-reap,
+      # and a second pass would race it. Later callers return immediately;
+      # the SDK's outer teardown ensures (query() / Client#disconnect) close
+      # the transport independently, so nothing is left dangling even if the
+      # first pass failed partway.
+      first_caller = @close_mutex.synchronize do
+        if @close_started
+          false
+        else
+          @close_started = true
+        end
+      end
+      return unless first_caller
+
       @closed = true
       # Wake pending control-request waiters (same shape as the read-loop
       # rescue broadcast): close stops the read task with Async::Stop, which
@@ -1167,10 +1243,43 @@ module ClaudeAgentSDK
       # Stop tracked child tasks (e.g. stream_input) before the read task and
       # transport so a parked input stream can never keep the reactor alive
       # (mirrors Python close() cancelling _child_tasks).
-      @child_tasks.each(&:stop)
-      @child_tasks.clear
-      @task&.stop
+      begin
+        @child_tasks.each(&:stop)
+        @child_tasks.clear
+        @task&.stop
+      rescue NoMethodError, FiberError => e
+        # Schedulerless fallback close (the watcher died unserved) racing
+        # reactor teardown: a task fiber can still be unwinding, and stopping
+        # it needs the owning thread's Fiber.scheduler. The dying reactor
+        # stops its own tasks; the transport close below (plain IO + kill)
+        # still runs. On the reactor itself this is a real bug — re-raise.
+        raise unless Fiber.scheduler.nil?
+
+        warn "Claude SDK: skipped stopping tasks during off-reactor close: #{e.message}"
+      end
       @transport.close
+      # Release a still-parked close watcher: pop returns nil and it exits
+      # without serving. Any foreign-thread close arriving after this point
+      # falls back to a direct close (safe — the fibers are now dead).
+      @close_requests.close
+    end
+
+    # Hand the close to the reactor and wait for completion. Polls watcher
+    # liveness instead of waiting forever: if the reactor shuts down
+    # concurrently (the transient watcher is stopped without serving the
+    # request), no reply will ever arrive — fall back to a direct close,
+    # which is safe once the reactor's fibers are dead.
+    def marshal_close_to_reactor
+      reply = ::Thread::Queue.new
+      @close_requests << reply
+      loop do
+        return if reply.pop(timeout: 0.1)
+        break unless @close_watcher&.alive?
+      end
+      close_now
+    rescue ClosedQueueError
+      # The push raced a reactor-side close_now that closed @close_requests.
+      close_now
     end
   end
 end

data/lib/claude_agent_sdk/session_resume.rb

@@ -28,6 +28,23 @@ module ClaudeAgentSDK
     def cleanup
       SessionResume.rmtree_with_retry(@config_dir)
     end
+
+    # Teardown when the transcript mirror dropped batches: the CLI's
+    # authoritative transcript lives in this temp dir, and the store copy is
+    # missing the dropped turns — deleting the dir would permanently lose
+    # them. Keep the transcripts (projects/), remove the redacted credential
+    # copies, and tell the user where the data is so they can import it into
+    # the store manually. Never raises.
+    def preserve_transcripts
+      ['.credentials.json', '.claude.json'].each do |name|
+        FileUtils.rm_f(File.join(@config_dir, name))
+      end
+      warn "Claude SDK: transcript mirror dropped batches; the session store copy is incomplete. " \
+           "Preserving the session transcript under #{File.join(@config_dir, 'projects')} instead of " \
+           'deleting it — import it into your session store, then remove the directory.'
+    rescue StandardError => e
+      warn "Claude SDK: failed to scrub preserved transcript dir #{@config_dir}: #{e.message}"
+    end
   end
 
   # Materialize a SessionStore-backed resume into a temp CLAUDE_CONFIG_DIR.
@@ -151,7 +168,7 @@ module ClaudeAgentSDK
       end
       return nil if sessions.nil? || sessions.empty?
 
-      sessions.sort_by { |s| -(s['mtime'] || 0) }.each do |cand|
+      sessions.sort_by { |s| -sortable_mtime(s['mtime']) }.each do |cand|
         sid = cand['session_id']
         next unless sid.is_a?(String) && sid.match?(Sessions::UUID_RE)
 
@@ -166,6 +183,22 @@ 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
     # (FiberBoundary with a timeout always hops) both keeps the async scheduler
@@ -436,7 +469,7 @@ module ClaudeAgentSDK
       value && (!value.respond_to?(:empty?) || !value.empty?) ? value : nil
     end
 
-    private_class_method :load_candidate, :resolve_continue_candidate, :with_timeout, :write_jsonl,
+    private_class_method :load_candidate, :resolve_continue_candidate, :sortable_mtime, :with_timeout, :write_jsonl,
                          :copy_auth_files, :write_redacted_credentials, :read_keychain_credentials,
                          :capture_with_timeout, :materialize_subkeys, :write_subagent_files,
                          :resolve_dir, :read_file_if_present, :chmod_owner_only, :copy_if_present, :env_value

data/lib/claude_agent_sdk/sessions.rb

@@ -213,6 +213,65 @@ module ClaudeAgentSDK
       result
     end
 
+    # Byte-scan for `"key":"` like extract_json_string_field, but verify each
+    # match by JSON-parsing its containing line and reading the key at the TOP
+    # LEVEL of the entry. The raw scan also matches keys nested inside
+    # tool_use inputs (real transcripts carry unescaped `"summary":"..."` in
+    # subagent/teammate tool arguments), which made the disk path report
+    # tool-argument text as the session summary/title while the store fold —
+    # which reads only top-level keys — disagreed. A line that doesn't parse
+    # (truncated at the head/tail window edge) keeps the raw-scan value: its
+    # top-level shape can't be checked, and dropping it would regress the
+    # common case of a true entry cut by the 64KB window.
+    def extract_top_level_string_field(text, key, last: false)
+      positions = field_match_positions(text, key)
+      positions.reverse! if last
+      parsed_lines = {}
+      positions.each do |idx, value_start|
+        line_start = (text.rindex("\n", idx) || -1) + 1
+        entry = parsed_lines.fetch(line_start) do
+          parsed_lines[line_start] = parse_containing_line(text, line_start, idx)
+        end
+        if entry
+          value = entry[key]
+          return value if value.is_a?(String)
+
+          next # parseable line without a top-level string value: nested/false match
+        end
+        value = extract_json_string_value(text, value_start)
+        return unescape_json_string(value) if value
+      end
+      nil
+    end
+
+    # Match positions of both compact and spaced `"key":` patterns, sorted by
+    # position so first/last selection is by document order (the pattern-major
+    # order of extract_json_string_field is wrong when spacings mix).
+    def field_match_positions(text, key)
+      positions = []
+      ["\"#{key}\":\"", "\"#{key}\": \""].each do |pattern|
+        pos = 0
+        while (idx = text.index(pattern, pos))
+          value_start = idx + pattern.length
+          positions << [idx, value_start]
+          pos = value_start
+        end
+      end
+      positions.sort_by!(&:first)
+      positions
+    end
+
+    # Parse the JSONL line containing byte offset +idx+. Returns the entry
+    # Hash, {} for parseable non-Hash lines (a match inside one is nested by
+    # definition), or nil when the line doesn't parse (window truncation).
+    def parse_containing_line(text, line_start, idx)
+      line_end = text.index("\n", idx) || text.length
+      entry = JSON.parse(text[line_start...line_end])
+      entry.is_a?(Hash) ? entry : {}
+    rescue StandardError
+      nil
+    end
+
     # Extract string value starting at pos (handles escapes)
     def extract_json_string_value(text, start)
       pos = start
@@ -236,6 +295,19 @@ module ClaudeAgentSDK
       str
     end
 
+    # Python's `x or None` for the summary/title fallback chains: Ruby's ||
+    # treats "" as truthy, so a CLI title-clearing entry ({"customTitle":""})
+    # would win over a real first prompt and then fail the summary presence
+    # check — silently dropping the whole session from disk listings (the
+    # store path, SessionSummary.presence, already falls through correctly).
+    # Whitespace-only counts as blank because the final gate strips.
+    def presence(val)
+      return nil if val.nil?
+      return nil if val.is_a?(String) && val.strip.empty?
+
+      val
+    end
+
     # Extract the first meaningful user prompt from the head of a JSONL file
     def extract_first_prompt_from_head(head)
       command_fallback = nil
@@ -247,16 +319,8 @@ module ClaudeAgentSDK
         next if line.include?('"isCompactSummary":true') || line.include?('"isCompactSummary": true')
 
         entry = JSON.parse(line, symbolize_names: false)
-        content = entry.dig('message', 'content')
-        next unless content
-
-        texts = if content.is_a?(String)
-                  [content]
-                elsif content.is_a?(Array)
-                  content.filter_map { |block| block['text'] if block.is_a?(Hash) && block['type'] == 'text' }
-                else
-                  next
-                end
+        texts = user_entry_texts(entry)
+        next unless texts
 
         texts.each do |text|
           text = text.gsub(/\n+/, ' ').strip
@@ -278,6 +342,29 @@ module ClaudeAgentSDK
       command_fallback || ''
     end
 
+    # Text blocks of a genuine user entry, or nil when the line should be
+    # skipped. Shape guards ported from Python: the byte pre-filter can match
+    # `"type":"user"` nested inside a tool_use input on an assistant line, so
+    # the parsed type is rechecked; and a malformed head line (non-Hash entry,
+    # string `message`, non-string `text`) must skip just that line rather
+    # than blow up into read_session_lite's blanket rescue and silently drop
+    # the whole session from disk listings.
+    def user_entry_texts(entry)
+      return nil unless entry.is_a?(Hash) && entry['type'] == 'user'
+
+      message = entry['message']
+      return nil unless message.is_a?(Hash)
+
+      content = message['content']
+      if content.is_a?(String)
+        [content]
+      elsif content.is_a?(Array)
+        content.filter_map do |block|
+          block['text'] if block.is_a?(Hash) && block['type'] == 'text' && block['text'].is_a?(String)
+        end
+      end
+    end
+
     # Read a single session file with lite (head/tail) strategy
     def read_session_lite(file_path, project_path)
       stat = File.stat(file_path)
@@ -311,15 +398,21 @@ module ClaudeAgentSDK
     def build_session_info(file_path, head, tail, stat, project_path)
       # User-set title (customTitle) wins over AI-generated title (aiTitle).
       # Head fallback covers short sessions where the title entry may not be in tail.
-      custom_title = extract_json_string_field(tail, 'customTitle', last: true) ||
-                     extract_json_string_field(head, 'customTitle', last: true) ||
-                     extract_json_string_field(tail, 'aiTitle', last: true) ||
-                     extract_json_string_field(head, 'aiTitle', last: true)
+      # Each candidate passes through presence so a blank value (e.g. a
+      # trailing title-clearing entry) falls through instead of short-circuiting.
+      # Summary-chain fields use the top-level-verified scan: a raw byte scan
+      # also matches these keys nested inside tool_use inputs, reporting tool
+      # arguments as the session title/summary (and diverging from the store
+      # fold, which reads top-level keys only).
+      custom_title = presence(extract_top_level_string_field(tail, 'customTitle', last: true)) ||
+                     presence(extract_top_level_string_field(head, 'customTitle', last: true)) ||
+                     presence(extract_top_level_string_field(tail, 'aiTitle', last: true)) ||
+                     presence(extract_top_level_string_field(head, 'aiTitle', last: true))
       first_prompt = extract_first_prompt_from_head(head)
       # lastPrompt tail entry shows what the user was most recently doing.
       summary = custom_title ||
-                extract_json_string_field(tail, 'lastPrompt', last: true) ||
-                extract_json_string_field(tail, 'summary', last: true) ||
+                presence(extract_top_level_string_field(tail, 'lastPrompt', last: true)) ||
+                presence(extract_top_level_string_field(tail, 'summary', last: true)) ||
                 first_prompt
       return nil if summary.nil? || summary.strip.empty?
 
@@ -1235,7 +1328,7 @@ module ClaudeAgentSDK
                          :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,
+                         :filter_visible_messages, :read_head_tail, :build_session_info, :presence, :user_entry_texts,
                          :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,

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -556,9 +556,14 @@ module ClaudeAgentSDK
       # concurrently and reset it) or already waited on (Errno::ECHILD on
       # double-wait). Both are non-fatal — the message loop just exits.
       returncode = nil
+      termsig = nil
       begin
         status = @process&.value
+        # exitstatus is nil when the child died from a signal (OOM-kill
+        # SIGKILL, SIGSEGV, ...) — that end-of-stream is a TRUNCATED response,
+        # not a clean success. Python surfaces it as a negative returncode.
         returncode = status&.exitstatus
+        termsig = status.termsig if status&.signaled?
       rescue Errno::ECHILD
         # Process was already reaped (e.g., by close()); no exit status to surface.
         returncode = nil
@@ -571,7 +576,7 @@ module ClaudeAgentSDK
       # #close still sees @process (left set here) for its termination logic.
       self.class.deregister_active_process(@process)
 
-      if returncode && returncode != 0
+      if termsig || (returncode && returncode != 0)
         # Wait briefly for stderr thread to finish draining
         @stderr_task&.join(1)
 
@@ -579,8 +584,9 @@ module ClaudeAgentSDK
         stderr_text = 'No stderr output captured' if stderr_text.empty?
 
         @exit_error = ProcessError.new(
-          "Command failed with exit code #{returncode}",
-          exit_code: returncode,
+          termsig ? "Command terminated by signal #{termsig}" : "Command failed with exit code #{returncode}",
+          # Negative-signal exit_code mirrors Python's subprocess returncode.
+          exit_code: termsig ? -termsig : returncode,
           stderr: stderr_text
         )
         raise @exit_error

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -55,12 +55,24 @@ module ClaudeAgentSDK
       @pending = []
       @pending_entries = 0
       @pending_bytes = 0
+      # Batches that exhausted retries (or could not be keyed) and never
+      # reached the store. Written only under @lock; read cross-thread by
+      # #batches_dropped? (a plain Integer read is safe under the GVL).
+      @dropped_batches = 0
       # Fiber-aware lock: the critical section blocks on SessionStore#append
       # (a thread hop), so a Thread::Mutex would deadlock the reactor. The
       # semaphore serializes drains so append ordering matches enqueue order.
       @lock = Async::Semaphore.new(1)
     end
 
+    # True when at least one batch of entries never reached the store — the
+    # mirror copy is incomplete. Consulted at teardown by the resume-from-store
+    # cleanup so the materialized temp dir (which then holds the only copy of
+    # the dropped turns) is preserved instead of deleted.
+    def batches_dropped?
+      @dropped_batches.positive?
+    end
+
     # Buffer a frame; schedule an eager background flush if thresholds are
     # exceeded. Synchronous and fire-and-forget.
     #
@@ -112,27 +124,47 @@ module ClaudeAgentSDK
       @pending_bytes = 0
 
       errors = []
-      @lock.acquire do
-        # Emptiness is checked INSIDE the lock (matching the Python batcher):
-        # an empty #flush/#close still serializes behind any in-flight or
-        # queued drain, so they are true barriers — at result-yield and at
-        # teardown the store really is up to date, and Query#close can't stop
-        # the read task while a detached batch is still being appended.
-        next if items.empty?
-
-        do_flush(items, errors)
-      rescue StandardError => e
-        # do_flush already guards each append; this guards any remaining path
-        # so the "never raises" contract holds against future regressions.
-        warn "Claude SDK: TranscriptMirrorBatcher drain failed: #{e.message}"
-      end
-
-      # Report errors after releasing the lock so a slow on_error callback can't
-      # block subsequent drains (which only need the lock for append ordering).
-      errors.each do |key, message|
-        @on_error.call(key, message)
-      rescue StandardError => e
-        warn "Claude SDK: TranscriptMirrorBatcher on_error callback raised: #{e.message}"
+      # Cancellation (Async::Stop — not a StandardError) delivered while
+      # waiting on the lock or inside the append's thread join loses the
+      # detached items without either rescue firing. Teardown would then read
+      # batches_dropped? as false and delete a materialized resume dir holding
+      # the only copy of these entries — count the batch as dropped unless the
+      # flush path ran to completion (do_flush counts its own failures).
+      accounted = items.empty?
+      begin
+        @lock.acquire do
+          # Emptiness is checked INSIDE the lock (matching the Python batcher):
+          # an empty #flush/#close still serializes behind any in-flight or
+          # queued drain, so they are true barriers — at result-yield and at
+          # teardown the store really is up to date, and Query#close can't stop
+          # the read task while a detached batch is still being appended.
+          next if items.empty?
+
+          begin
+            do_flush(items, errors)
+          rescue StandardError => e
+            # do_flush already guards each append; this guards any remaining path
+            # so the "never raises" contract holds against future regressions.
+            @dropped_batches += 1
+            warn "Claude SDK: TranscriptMirrorBatcher drain failed: #{e.message}"
+          end
+          accounted = true
+
+          # Report errors BEFORE releasing the lock: flush/close are barriers, so
+          # a caller observing flush completion must also observe the error
+          # report. Reporting after release let an in-flight eager drain enqueue
+          # its MirrorErrorMessage after the read loop's 'end' sentinel — past
+          # the point where consumers stop dequeuing, i.e. never delivered. The
+          # production on_error (Query#report_mirror_error) is a non-blocking
+          # queue push, so holding the lock across it costs nothing.
+          errors.each do |key, message|
+            @on_error.call(key, message)
+          rescue StandardError => e
+            warn "Claude SDK: TranscriptMirrorBatcher on_error callback raised: #{e.message}"
+          end
+        end
+      ensure
+        @dropped_batches += 1 unless accounted
       end
     end
 
@@ -149,6 +181,7 @@ module ClaudeAgentSDK
 
         key = SessionStores.file_path_to_session_key(file_path, @projects_dir)
         if key.nil?
+          @dropped_batches += 1
           warn "Claude SDK: [SessionStore] dropping mirror frame: filePath #{file_path} is not under " \
                "#{@projects_dir} -- subprocess CLAUDE_CONFIG_DIR likely differs from parent (custom env / container?)"
           next
@@ -180,8 +213,11 @@ module ClaudeAgentSDK
         end
       end
 
-      errors << [key, last_err.to_s] unless succeeded
-      warn "Claude SDK: TranscriptMirrorBatcher flush failed for #{file_path}: #{last_err}" unless succeeded
+      return if succeeded
+
+      @dropped_batches += 1
+      errors << [key, last_err.to_s]
+      warn "Claude SDK: TranscriptMirrorBatcher flush failed for #{file_path}: #{last_err}"
     end
 
     # Run SessionStore#append (user code) on a plain thread via FiberBoundary,

data/lib/claude_agent_sdk/types.rb

@@ -1586,6 +1586,15 @@ module ClaudeAgentSDK
 
     def dup_with(**changes)
       new_options = self.dup
+      # A shallow #dup shares nested containers, so mutating a derived copy
+      # (e.g. `variant.allowed_tools << 'Bash'`) would bleed into the base and
+      # every sibling — including the security-relevant allow/deny lists.
+      # Deep-dup Hash/Array containers only; non-container values (procs,
+      # SDK MCP server instances, store adapters) must keep their identity.
+      new_options.instance_variables.each do |ivar|
+        value = new_options.instance_variable_get(ivar)
+        new_options.instance_variable_set(ivar, deep_dup_containers(value)) if value.is_a?(Hash) || value.is_a?(Array)
+      end
       changes.each { |key, value| new_options[key] = value }
       new_options
     end
@@ -1687,10 +1696,20 @@ module ClaudeAgentSDK
 
     # Recurse ONLY into Hash/Array; leaves keep object identity (observer
     # factories, callbacks, SDK MCP server instances must not be duped).
+    # Rebuild via dup.clear (never Hash#to_h / Array#map) to preserve
+    # container SUBCLASSES: to_h flattens e.g. Rails'
+    # HashWithIndifferentAccess into a plain Hash, silently breaking symbol
+    # lookups on the copy (config[:type] == 'sdk' → nil).
     def deep_dup_containers(value)
       case value
-      when Hash then value.to_h { |k, v| [k, deep_dup_containers(v)] }
-      when Array then value.map { |v| deep_dup_containers(v) }
+      when Hash
+        copy = value.dup.clear
+        value.each { |k, v| copy[k] = deep_dup_containers(v) }
+        copy
+      when Array
+        copy = value.dup.clear
+        value.each { |v| copy << deep_dup_containers(v) }
+        copy
       else value
       end
     end

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -62,6 +62,23 @@ module ClaudeAgentSDK
     servers
   end
 
+  # Internal: pull exclude_dynamic_sections out of a preset system prompt for
+  # the initialize request (older CLIs ignore unknown initialize fields).
+  # Shared by Client#connect and the one-shot query() path.
+  def self.extract_exclude_dynamic_sections(system_prompt)
+    if system_prompt.is_a?(SystemPromptPreset)
+      eds = system_prompt.exclude_dynamic_sections
+      return eds if [true, false].include?(eds)
+    elsif system_prompt.is_a?(Hash)
+      type = system_prompt[:type] || system_prompt['type']
+      if type == 'preset'
+        eds = system_prompt.fetch(:exclude_dynamic_sections) { system_prompt['exclude_dynamic_sections'] }
+        return eds if [true, false].include?(eds)
+      end
+    end
+    nil
+  end
+
   # Safely call a method on each observer, suppressing any errors.
   # Each observer is invoked through FiberBoundary so that user code runs
   # on a plain thread (no Fiber scheduler) even when called from inside
@@ -371,6 +388,13 @@ module ClaudeAgentSDK
   #     puts message
   #   end
   def self.query(prompt:, options: nil, transport: nil, &block)
+    # Validate BEFORE the block-less enum_for return so a bad prompt fails at
+    # the call site, not on first iteration. Mirrors Client#query: a bare Hash
+    # responds to #each and would stream [key, value] pairs' to_s garbage to
+    # the CLI; nil/Integer would hang forever waiting for input.
+    raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)' if prompt.is_a?(Hash)
+    raise ArgumentError, "prompt must be a String or respond to #each (got #{prompt.class})" unless prompt.is_a?(String) || prompt.respond_to?(:each)
+
     return enum_for(:query, prompt: prompt, options: options, transport: transport) unless block
 
     options ||= ClaudeAgentOptions.new
@@ -451,6 +475,7 @@ module ClaudeAgentSDK
           hooks: hooks,
           agents: configured_options.agents,
           sdk_mcp_servers: sdk_mcp_servers,
+          exclude_dynamic_sections: ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt),
           skills: configured_options.skills
         )
 
@@ -530,8 +555,13 @@ module ClaudeAgentSDK
         ensure
           # Remove the materialized resume temp dir (which holds a redacted
           # .credentials.json copy) AFTER the subprocess has exited, even when
-          # close itself raises.
-          materialized&.cleanup
+          # close itself raises — unless the mirror dropped batches: the store
+          # copy is then incomplete and the temp dir holds the only copy of
+          # the dropped turns, so it is preserved (scrubbed of credentials)
+          # with a warning instead of deleted.
+          if materialized
+            query_handler&.mirror_batches_dropped? ? materialized.preserve_transcripts : materialized.cleanup
+          end
         end
       end
     end.wait
@@ -884,6 +914,10 @@ module ClaudeAgentSDK
       # state, and removes the materialized temp dir (which holds a redacted
       # .credentials.json copy) — so disconnect can never leave the client
       # half-open or leak the temp dir. The original error still propagates.
+      # Keep a handle on the query handler past the nil-out below: whether the
+      # mirror dropped batches is only final AFTER #close ran its last flush,
+      # and the materialized-dir decision at the bottom needs to ask it.
+      query_handler = @query_handler
       begin
         @query_handler&.close
       ensure
@@ -893,9 +927,17 @@ module ClaudeAgentSDK
         ensure
           @transport = nil
           @connected = false
-          # Remove the materialized resume temp dir AFTER the subprocess exited.
+          # Remove the materialized resume temp dir AFTER the subprocess
+          # exited — unless the mirror dropped batches: the store copy is then
+          # incomplete and the temp dir holds the only copy of the dropped
+          # turns, so it is preserved (scrubbed of credentials) with a warning
+          # instead of deleted.
           if @materialized
-            @materialized.cleanup
+            if query_handler&.mirror_batches_dropped?
+              @materialized.preserve_transcripts
+            else
+              @materialized.cleanup
+            end
             @materialized = nil
           end
         end
@@ -935,7 +977,7 @@ module ClaudeAgentSDK
 
       # Extract exclude_dynamic_sections from preset system prompt for the
       # initialize request (older CLIs ignore unknown initialize fields)
-      exclude_dynamic_sections = extract_exclude_dynamic_sections(configured_options.system_prompt)
+      exclude_dynamic_sections = ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt)
 
       # Create Query handler
       @query_handler = Query.new(
@@ -972,22 +1014,13 @@ module ClaudeAgentSDK
         # yielding deadlocked connect — and serialized Hash messages with
         # to_s (Ruby inspect, not JSON). stream_input JSON-generates Hashes
         # and is tracked on the Query so close() stops it. Stream errors are
-        # notified to observers once, then swallowed-with-warn by
-        # stream_input (Python parity) — they no longer abort connect.
+        # swallowed-with-warn by stream_input (Python parity) — they don't
+        # abort connect, and observers are NOT notified (the documented
+        # Observer#on_error contract; notifying a swallowed error would mark
+        # a still-live OTel trace as failed). Same behavior as query()'s
+        # streaming path.
         observed = ClaudeAgentSDK.observing_prompt_stream(prompt, @resolved_observers)
-        notifying = error_notifying_stream(observed)
-        @query_handler.spawn_task { @query_handler.stream_input(notifying) }
-      end
-    end
-
-    # Wrap a stream so a raising user enumerator fires on_error exactly once
-    # before stream_input's swallow-with-warn handling takes over.
-    def error_notifying_stream(stream)
-      Enumerator.new do |yielder|
-        stream.each { |message| yielder << message }
-      rescue StandardError => e
-        notify_error(e)
-        raise
+        @query_handler.spawn_task { @query_handler.stream_input(observed) }
       end
     end
 
@@ -1058,20 +1091,6 @@ module ClaudeAgentSDK
       internal_hooks
     end
 
-    def extract_exclude_dynamic_sections(system_prompt)
-      if system_prompt.is_a?(SystemPromptPreset)
-        eds = system_prompt.exclude_dynamic_sections
-        return eds if [true, false].include?(eds)
-      elsif system_prompt.is_a?(Hash)
-        type = system_prompt[:type] || system_prompt['type']
-        if type == 'preset'
-          eds = system_prompt.fetch(:exclude_dynamic_sections) { system_prompt['exclude_dynamic_sections'] }
-          return eds if [true, false].include?(eds)
-        end
-      end
-      nil
-    end
-
     def writeln(string)
       write string.end_with?("\n") ? string : "#{string}\n"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.19.1
+  version: 0.21.0
 platform: ruby
 authors:
 - Community Contributors