claude-agent-sdk 0.19.0 → 0.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbcc1484868ae2ed502513727fd7df53192fc0177eed594433ad7c0332b3287a
-  data.tar.gz: b052d3f7993aa1f4d5a2b4fc3bdb01f7cf974f939c67e82a7bac173cb0b65a8f
+  metadata.gz: fc9c6b243b2a7ac982141db36c55d510d9a08cb18caeffb5dd2d9ed59fefc42d
+  data.tar.gz: 7ce8124f1cebd923857fda75532caa8332a89d930564ff9c474e847e57fcb1d8
 SHA512:
-  metadata.gz: b50d94d3879214f2bed9c42e4fe20a989c84e5de26a36a907c1b1093dc344a66a6b37e53a3d60a997f92ce84b4795871d55da32056a235a70617e4dd0cf85552
-  data.tar.gz: 7899caf95b4c5da6e5f4e004ae57456e19e18b6d2be35469e88bd14f1333be4d3053fa8138dd037616c9a15ce2a9985164d065bbdb0026af90b759b31646cddb
+  metadata.gz: 7c548159588586dd908b4a51173bdf89abac417ceab753d8eb8b313095463770dbf5fc44e7af9c90dce26df651f11ae5b25eca28d755a17e2c5b68984eff1ccb
+  data.tar.gz: 0a46ae5342425411af912c98ab5f96607bdf4d8ec76f027a7388b5519c3dc7d425a79e03a4b82c7317e9f983dcd232c7375d91f23feb33ecb758289f57dcce3b

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.19.1'
 ```
 
 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

@@ -306,6 +306,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/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

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/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

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -23,13 +23,43 @@ 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
 
   # Safely call a method on each observer, suppressing any errors.
@@ -391,12 +421,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
@@ -903,12 +928,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 = 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.19.1
 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