claude-agent-sdk 0.19.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbcc1484868ae2ed502513727fd7df53192fc0177eed594433ad7c0332b3287a
-  data.tar.gz: b052d3f7993aa1f4d5a2b4fc3bdb01f7cf974f939c67e82a7bac173cb0b65a8f
+  metadata.gz: 35da7de1ea5624dce1116d0c031a6141549e1d554434f3636cf47f5bcc81ca70
+  data.tar.gz: f9093848753fc2b583aed232d30013c8f328e36c6a958dc44f7d30c6ff319ae8
 SHA512:
-  metadata.gz: b50d94d3879214f2bed9c42e4fe20a989c84e5de26a36a907c1b1093dc344a66a6b37e53a3d60a997f92ce84b4795871d55da32056a235a70617e4dd0cf85552
-  data.tar.gz: 7899caf95b4c5da6e5f4e004ae57456e19e18b6d2be35469e88bd14f1333be4d3053fa8138dd037616c9a15ce2a9985164d065bbdb0026af90b759b31646cddb
+  metadata.gz: f73779c80dfced4d4600384853900a68d658db1dcb9a73813949c49bced1593641a8b68085d83d6127178a533cb5a6daf2d045ffdaac4f526fc8d21f24db3636
+  data.tar.gz: 8e1022e4c20937b7464f46636636d2d9c6c160dfce9937617d1b56c5fae1c0abce401e6d9795fe4b566d2c59ba6e628c6c8dbf6e090278743eeac54a9a8a8489

data/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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).
+
+### Added
+- `lib/claude-agent-sdk.rb` require shim: `Bundler.require` now loads the SDK in default Rails/Bundler apps. Previously Bundler tried `claude-agent-sdk` and `claude/agent/sdk`, silently swallowed both LoadErrors, and left `ClaudeAgentSDK` undefined until a confusing `NameError` at first use.
+
+### Fixed
+- `require 'claude_agent_sdk/instrumentation'` now loads the SDK core, so the documented Rails observability initializer (and `OTelObserver`'s own `@example`) works as the only require.
+- Typed `McpStdioServerConfig` / `McpSSEServerConfig` / `McpHttpServerConfig` / `McpSdkServerConfig` objects passed directly in `mcp_servers` (without `.to_h`) now serialize to their wire hash instead of a `#<...>` string the CLI cannot parse — and `McpSdkServerConfig` instances now actually register their in-process server, so its tools connect.
+- `create_tool` with a Symbol name produced a tool that was advertised in `tools/list` but failed every invocation with 'Tool not found'; names are now coerced to String.
+- One stdout line carrying invalid UTF-8 bytes no longer aborts the whole message stream (which dropped all buffered valid frames, including a trailing `result`); the bad line is scrubbed, matching the version-probe path.
+- `fork_session` no longer hangs forever on a transcript with a `parentUuid` cycle among progress entries.
+- `fork_session` / `delete_session` no longer stop at a 0-byte transcript stub: they fall through to the worktree project dir holding the real transcript, mirroring the read path. A session whose *only* copy is a 0-byte stub now raises `Errno::ENOENT`, consistent with the read paths that already hide it.
+- Long-lived `Client`s using SDK MCP servers no longer leak one finished internal task per synchronously-handled control request (MCP metadata requests, unsupported subtypes).
+- An observer implementing none of the observer interface — most commonly a Class passed instead of an instance (`observers: [OTelObserver]`) — is now warned about and skipped instead of producing silent zero instrumentation.
+
+### Changed
+- The gem packages git-tracked files only (previously a working-tree glob, which shipped stray untracked files under `lib/`/`docs/` in locally built gems). `gem build` from a tree with tracked-but-deleted files now fails fast instead of silently packaging whatever was on disk.
+
 ## [0.19.0] - 2026-06-29
 
 ### Added

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.0'
+gem 'claude-agent-sdk', '~> 0.20.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/lib/claude-agent-sdk.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Bundler autorequire shim. The gem is named `claude-agent-sdk`, so
+# `Bundler.require` tries `require 'claude-agent-sdk'` and then
+# `require 'claude/agent/sdk'` — and silently swallows both LoadErrors when
+# neither file exists, leaving the SDK unloaded in default Rails/Bundler
+# apps. This file makes the gem-named require resolve to the real entry point.
+require_relative 'claude_agent_sdk'

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
@@ -306,6 +315,9 @@ module ClaudeAgentSDK
       if @options.mcp_servers.is_a?(Hash)
         servers_for_cli = {}
         @options.mcp_servers.each do |name, config|
+          # Typed Mcp*ServerConfig objects serialize via their wire hash —
+          # without this they'd JSON-stringify as "#<...>" via to_s.
+          config = config.to_h if config.is_a?(Type)
           servers_for_cli[name] = if config.is_a?(Hash) && config[:type] == "sdk"
                                     config.except(:instance)
                                   else

data/lib/claude_agent_sdk/instrumentation.rb

@@ -3,4 +3,10 @@
 # Instrumentation adapters for ClaudeAgentSDK.
 # Each adapter lazy-requires its external gem, so loading this file has zero cost
 # unless you instantiate a specific observer.
+#
+# This entry point is documented as a standalone require (docs/rails.md's
+# initializer, OTelObserver's @example), so it must load the SDK core too —
+# otherwise ClaudeAgentSDK exists (observer.rb reopens the module) but has
+# no .configure/.query/ClaudeAgentOptions.
+require_relative '../claude_agent_sdk'
 require_relative 'instrumentation/otel'

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

@@ -256,7 +256,11 @@ module ClaudeAgentSDK
               @inflight_control_request_tasks.delete(request_id) if request_id
             end
           end
-          @inflight_control_request_tasks[request_id] = handler_task if request_id
+          # A handler that never suspends (MCP metadata, unsupported-subtype
+          # error path) already ran to completion inside the async{} above —
+          # its ensure-delete fired before this insert, so registering it here
+          # would leak a finished task in the map forever.
+          @inflight_control_request_tasks[request_id] = handler_task if request_id && !handler_task.finished?
         when 'control_cancel_request'
           request_id = message[:request_id] || message[:requestId]
           task = request_id ? @inflight_control_request_tasks[request_id] : nil
@@ -1135,7 +1139,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'

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -470,6 +470,11 @@ module ClaudeAgentSDK
       resolved_meta = { 'anthropic/maxResultSizeChars' => max_chars } if max_chars
     end
 
+    # tools/call arrives from the CLI with the name as a JSON String; the mcp
+    # gem keys its lookup on the value stored here, so a Symbol name would be
+    # advertised in tools/list yet miss on every invocation ('Tool not found').
+    name = name.to_s if name.is_a?(Symbol)
+
     SdkMcpTool.new(
       name: name,
       description: description,

data/lib/claude_agent_sdk/session_mutations.rb

@@ -280,11 +280,17 @@ module ClaudeAgentSDK
       nil
     end
 
+    # 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) project dir. Mirrors the read path
+    # (Sessions.stat_candidate) and the append path (try_append).
     def try_project_dir(file_name, project_dir)
       return nil unless project_dir
 
       candidate = File.join(project_dir, file_name)
-      File.exist?(candidate) ? [candidate, project_dir] : nil
+      File.size(candidate).positive? ? [candidate, project_dir] : nil
+    rescue SystemCallError
+      nil
     end
 
     def find_in_all_projects(file_name)
@@ -295,8 +301,8 @@ module ClaudeAgentSDK
         pd = File.join(projects_dir, child)
         next unless File.directory?(pd)
 
-        candidate = File.join(pd, file_name)
-        return [candidate, pd] if File.exist?(candidate)
+        result = try_project_dir(file_name, pd)
+        return result if result
       end
       nil
     end
@@ -523,9 +529,13 @@ module ClaudeAgentSDK
       JSON.generate(forked)
     end
 
-    # Walk up parentUuid chain skipping progress entries.
+    # Walk up parentUuid chain skipping progress entries. The visited set
+    # guards against parentUuid cycles among progress entries (corrupt
+    # transcripts) like every other chain walker — an unguarded walk spun
+    # forever and hung both fork paths.
     def resolve_parent_uuid(parent_id, by_uuid, uuid_mapping)
-      while parent_id
+      visited = Set.new
+      while parent_id && visited.add?(parent_id)
         parent = by_uuid[parent_id]
         break unless parent
         return uuid_mapping[parent_id] if parent['type'] != 'progress'

data/lib/claude_agent_sdk/session_resume.rb

@@ -151,7 +151,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 +166,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 +452,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

@@ -236,6 +236,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 +260,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 +283,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 +339,17 @@ 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.
+      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))
       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_json_string_field(tail, 'lastPrompt', last: true)) ||
+                presence(extract_json_string_field(tail, 'summary', last: true)) ||
                 first_prompt
       return nil if summary.nil? || summary.strip.empty?
 
@@ -1235,7 +1265,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

@@ -494,6 +494,13 @@ module ClaudeAgentSDK
         # 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|
+          # stdout is UTF-8-tagged but the CLI can emit invalid bytes (echoed
+          # binary/latin-1 output). strip/lstrip below raise on invalid
+          # encoding, which would abort the whole stream and drop buffered
+          # valid frames — scrub the one bad line instead (the version-probe
+          # path guards the same way).
+          line = line.scrub unless line.valid_encoding?
+
           # 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
@@ -549,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
@@ -564,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)
 
@@ -572,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/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.0'
+  VERSION = '0.20.0'
 end

data/lib/claude_agent_sdk.rb

@@ -23,13 +23,60 @@ require 'securerandom'
 
 # Claude Agent SDK for Ruby
 module ClaudeAgentSDK
+  # The duck-typed observer surface probed by resolve_observers — implementing
+  # any one of these counts as an observer (see Observer's no-op defaults).
+  OBSERVER_INTERFACE = %i[on_user_prompt on_message on_error on_close].freeze
+
   # Resolve observers array: callables (Proc/lambda) are invoked to produce
   # a fresh instance per query/session (thread-safe); plain objects are used as-is.
   # Array() guards against nil (e.g., when observers: nil is passed explicitly).
+  # Anything implementing none of the observer methods is warned about and
+  # skipped — most commonly a Class passed instead of an instance, which
+  # previously produced silent zero instrumentation (every notify raised
+  # NoMethodError, swallowed by notify_observers' error containment).
   def self.resolve_observers(observers)
-    Array(observers).map do |obs|
-      obs.respond_to?(:call) ? obs.call : obs
+    Array(observers).filter_map do |obs|
+      resolved = obs.respond_to?(:call) ? obs.call : obs
+      if OBSERVER_INTERFACE.none? { |m| resolved.respond_to?(m) }
+        label = resolved.is_a?(Module) ? resolved : resolved.class
+        hint = resolved.is_a?(Module) ? " — pass an instance (#{resolved}.new) or a factory lambda" : ''
+        warn "ClaudeAgentSDK: ignoring observer #{label}: it implements none of #{OBSERVER_INTERFACE.join('/')}#{hint}"
+        next nil
+      end
+      resolved
+    end
+  end
+
+  # Internal: pull live SDK MCP server instances out of an mcp_servers Hash.
+  # Accepts both raw Hash configs and typed Mcp*ServerConfig objects — a
+  # McpSdkServerConfig passed without .to_h previously failed the Hash-only
+  # guard, so its in-process server was silently never registered.
+  def self.extract_sdk_mcp_servers(mcp_servers)
+    return {} unless mcp_servers.is_a?(Hash)
+
+    servers = {}
+    mcp_servers.each do |name, config|
+      config = config.to_h if config.is_a?(Type)
+      servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
     end
+    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.
@@ -341,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
@@ -391,12 +445,7 @@ module ClaudeAgentSDK
         transport.connect
 
         # Extract SDK MCP servers
-        sdk_mcp_servers = {}
-        if configured_options.mcp_servers.is_a?(Hash)
-          configured_options.mcp_servers.each do |name, config|
-            sdk_mcp_servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
-          end
-        end
+        sdk_mcp_servers = extract_sdk_mcp_servers(configured_options.mcp_servers)
 
         hooks = nil
         if configured_options.hooks
@@ -426,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
         )
 
@@ -903,19 +953,14 @@ module ClaudeAgentSDK
       @transport.connect
 
       # Extract SDK MCP servers
-      sdk_mcp_servers = {}
-      if configured_options.mcp_servers.is_a?(Hash)
-        configured_options.mcp_servers.each do |name, config|
-          sdk_mcp_servers[name] = config[:instance] if config.is_a?(Hash) && config[:type] == 'sdk'
-        end
-      end
+      sdk_mcp_servers = ClaudeAgentSDK.extract_sdk_mcp_servers(configured_options.mcp_servers)
 
       # Convert hooks to internal format
       hooks = convert_hooks_to_internal_format(configured_options.hooks) if configured_options.hooks
 
       # 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(
@@ -1038,20 +1083,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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -119,6 +119,7 @@ files:
 - docs/rails.md
 - docs/sessions.md
 - docs/types.md
+- lib/claude-agent-sdk.rb
 - lib/claude_agent_sdk.rb
 - lib/claude_agent_sdk/command_builder.rb
 - lib/claude_agent_sdk/configuration.rb