claude-agent-sdk 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35da7de1ea5624dce1116d0c031a6141549e1d554434f3636cf47f5bcc81ca70
-  data.tar.gz: f9093848753fc2b583aed232d30013c8f328e36c6a958dc44f7d30c6ff319ae8
+  metadata.gz: 408fe2ed3f2f1f00866e3cef0b1795e67dc50dafd3292fc016985f62c10f1b6e
+  data.tar.gz: 045b04fee0681072fe7e99c81ab7a99d51d2eec362baf282a45c8d825cc38135
 SHA512:
-  metadata.gz: f73779c80dfced4d4600384853900a68d658db1dcb9a73813949c49bced1593641a8b68085d83d6127178a533cb5a6daf2d045ffdaac4f526fc8d21f24db3636
-  data.tar.gz: 8e1022e4c20937b7464f46636636d2d9c6c160dfce9937617d1b56c5fae1c0abce401e6d9795fe4b566d2c59ba6e628c6c8dbf6e090278743eeac54a9a8a8489
+  metadata.gz: 91b04e46d137103527e3af91d089acc01be96b69a8b0e6902eecb603654567ee826c8284ac0f9b797f180af64220ecfe0d71c3ab6f5e755e03525d596fcff85e
+  data.tar.gz: fb7e3d0a535522e98ed3c7a0180f1ac35ca5057a29dfdb3429b07cd896375672c0c94e114d92809325680f599ca39d8dee2f7fc3a658a73fabd744cf4a987946

data/CHANGELOG.md

@@ -7,6 +7,19 @@ 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`.

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.20.0'
+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

@@ -376,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/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
@@ -1152,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
@@ -1171,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.

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
@@ -341,15 +400,19 @@ module ClaudeAgentSDK
       # Head fallback covers short sessions where the title entry may not be in tail.
       # Each candidate passes through presence so a blank value (e.g. a
       # trailing title-clearing entry) falls through instead of short-circuiting.
-      custom_title = presence(extract_json_string_field(tail, 'customTitle', last: true)) ||
-                     presence(extract_json_string_field(head, 'customTitle', last: true)) ||
-                     presence(extract_json_string_field(tail, 'aiTitle', last: true)) ||
-                     presence(extract_json_string_field(head, 'aiTitle', last: true))
+      # 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 ||
-                presence(extract_json_string_field(tail, 'lastPrompt', last: true)) ||
-                presence(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?
 

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/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -555,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
@@ -909,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
@@ -918,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
@@ -997,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
 

metadata

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