claude-agent-sdk 0.16.7 → 0.16.8

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -30,6 +30,12 @@ module ClaudeAgentSDK
       @stderr_task = nil
       @recent_stderr = []
       @recent_stderr_mutex = Mutex.new
+      # Serializes stdin access across the reactor fiber (transport writes
+      # from inside Async) and user-callback threads spawned via FiberBoundary
+      # (tool handlers / hooks calling Client#query). Without this lock,
+      # close can nil @stdin between write's readiness check and the actual
+      # @stdin.write call, producing NoMethodError on nil.
+      @stdin_mutex = Mutex.new
     end
 
     def find_cli
@@ -148,20 +154,33 @@ module ClaudeAgentSDK
 
         record_bounded_stderr(line_str)
 
-        # Call stderr callback if provided
-        @options.stderr&.call(line_str)
+        # Per-line isolation: a callback that raises (e.g. user's logger
+        # transiently failing) must not poison the rest of the stderr stream.
+        # Without this, the first exception terminates the each_line loop and
+        # the SDK silently stops capturing stderr for the lifetime of the
+        # process. Matches Python SDK v0.2.82 (PR #932).
+        begin
+          @options.stderr&.call(line_str)
+        rescue StandardError
+          # Drop the callback error; the line is already in the recent-stderr
+          # ring buffer, which is what ProcessError surfaces on non-zero exit.
+        end
 
-        # Write to debug_stderr file/IO if provided
-        if @options.debug_stderr
-          if @options.debug_stderr.respond_to?(:puts)
-            @options.debug_stderr.puts(line_str)
-          elsif @options.debug_stderr.is_a?(String)
-            File.open(@options.debug_stderr, 'a') { |f| f.puts(line_str) }
+        # Write to debug_stderr file/IO if provided, also isolated.
+        begin
+          if @options.debug_stderr
+            if @options.debug_stderr.respond_to?(:puts)
+              @options.debug_stderr.puts(line_str)
+            elsif @options.debug_stderr.is_a?(String)
+              File.open(@options.debug_stderr, 'a') { |f| f.puts(line_str) }
+            end
           end
+        rescue StandardError
+          # Drop debug_stderr write errors so they never interrupt the loop.
         end
       end
     rescue StandardError
-      # Ignore errors during stderr reading
+      # Stream-level error (pipe closed mid-read); the loop naturally ends here.
     end
 
     def drain_stderr_with_accumulation
@@ -191,13 +210,18 @@ module ClaudeAgentSDK
         end
       end
 
-      # Close streams
-      begin
-        @stdin&.close
-      rescue IOError
-        # Already closed, ignore
-      rescue StandardError => e
-        cleanup_errors << "stdin: #{e.message}"
+      # Close stdin under the same lock that guards write — otherwise a
+      # concurrent writer (callbacks running on FiberBoundary threads) can
+      # see @stdin nilled mid-write and hit NoMethodError on nil.
+      @stdin_mutex.synchronize do
+        begin
+          @stdin&.close
+        rescue IOError
+          # Already closed, ignore
+        rescue StandardError => e
+          cleanup_errors << "stdin: #{e.message}"
+        end
+        @stdin = nil
       end
 
       begin
@@ -251,7 +275,7 @@ module ClaudeAgentSDK
 
       @process = nil
       @stdout = nil
-      @stdin = nil
+      # @stdin already nilled under the mutex above.
       @stderr = nil
       @stderr_task = nil
       @exit_error = nil
@@ -274,13 +298,28 @@ module ClaudeAgentSDK
     end
 
     def write(data)
-      raise CLIConnectionError, 'ProcessTransport is not ready for writing' unless @ready && @stdin
       raise CLIConnectionError, "Cannot write to terminated process" if @process && !@process.alive?
       raise CLIConnectionError, "Cannot write to process that exited with error: #{@exit_error}" if @exit_error
 
+      # Snapshot @stdin under the lock so close() nilling it concurrently is
+      # safe, but do the actual blocking IO *outside* the lock. Holding the
+      # mutex across @stdin.write would let a full pipe buffer block the
+      # writer indefinitely and block close() (which also needs the lock)
+      # from killing the subprocess — a hang on disconnect.
+      #
+      # If close() runs while we are inside the IO call, it will close the
+      # underlying stream and Ruby raises IOError("stream closed in another
+      # thread") inside @stdin.write — the rescue below converts that into a
+      # standard CLIConnectionError so callers see a clean shutdown error.
+      stdin = @stdin_mutex.synchronize do
+        raise CLIConnectionError, 'ProcessTransport is not ready for writing' unless @ready && @stdin
+
+        @stdin
+      end
+
       begin
-        @stdin.write(data)
-        @stdin.flush
+        stdin.write(data)
+        stdin.flush
       rescue StandardError => e
         @ready = false
         @exit_error = CLIConnectionError.new("Failed to write to process stdin: #{e}")
@@ -317,6 +356,14 @@ module ClaudeAgentSDK
             json_line = json_line.strip
             next if json_line.empty?
 
+            # When no partial JSON is buffered, the next line must start with
+            # `{` to be a valid stream-json message. Stray stderr-like text
+            # (e.g., debug warnings the CLI occasionally writes to stdout)
+            # would otherwise be appended into json_buffer, poisoning every
+            # subsequent parse until the buffer overflows. Matches the Python
+            # SDK's `if not json_buffer and not json_line.startswith("{")` guard.
+            next if json_buffer.empty? && !json_line.start_with?('{')
+
             json_buffer += json_line
 
             if json_buffer.bytesize > @max_buffer_size
@@ -344,9 +391,17 @@ module ClaudeAgentSDK
         # Client disconnected
       end
 
-      # Check process completion
-      status = @process.value
-      returncode = status.exitstatus
+      # Check process completion. @process may already be nil (close() ran
+      # concurrently and reset it) or already waited on (Errno::ECHILD on
+      # double-wait). Both are non-fatal — the message loop just exits.
+      returncode = nil
+      begin
+        status = @process&.value
+        returncode = status&.exitstatus
+      rescue Errno::ECHILD
+        # Process was already reaped (e.g., by close()); no exit status to surface.
+        returncode = nil
+      end
 
       if returncode && returncode != 0
         # Wait briefly for stderr thread to finish draining

data/lib/claude_agent_sdk/types.rb

@@ -180,12 +180,32 @@ module ClaudeAgentSDK
     attr_accessor :tool_use_id, :content, :is_error
   end
 
+  # Server-side tool use (CLI's built-in tools that execute server-side
+  # rather than as MCP tools — advisor, web_search, code_execution, etc.).
+  # Mirrors Python's `ServerToolUseBlock`.
+  class ServerToolUseBlock < Type
+    attr_accessor :id, :name, :input
+  end
+
+  # Result of a server-side tool execution. Mirrors Python's
+  # `ServerToolResultBlock`.
+  class ServerToolResultBlock < Type
+    attr_accessor :tool_use_id, :content, :is_error
+  end
+
   # Generic content block for types the SDK doesn't explicitly handle (e.g., "document", "image").
   # Preserves the raw hash data for forward compatibility with newer CLI versions.
   class UnknownBlock < Type
     attr_accessor :type, :data
   end
 
+  # Deferred tool use, emitted on `ResultMessage` when a PreToolUse hook
+  # returned `permissionDecision: "defer"`. The session can be resumed later
+  # to execute the deferred call. Mirrors Python's `DeferredToolUse`.
+  class DeferredToolUse < Type
+    attr_accessor :id, :name, :input
+  end
+
   # Message Types
 
   # User message
@@ -343,7 +363,14 @@ module ClaudeAgentSDK
                   :permission_denials, # Array of { tool_name:, tool_use_id:, tool_input: }
                   :errors,             # Array of error strings (present on error subtypes)
                   :uuid,
-                  :fast_mode_state     # "off", "cooldown", or "on"
+                  :fast_mode_state,    # "off", "cooldown", or "on"
+                  :api_error_status    # Integer HTTP status (429, 500, 529) on api_error subtype (CLI 2.1.110+)
+
+    attr_reader :deferred_tool_use     # DeferredToolUse, populated when a PreToolUse hook deferred
+
+    def deferred_tool_use=(value)
+      @deferred_tool_use = value.is_a?(Hash) ? DeferredToolUse.from_hash(value) : value
+    end
   end
 
   # Stream event for partial message updates
@@ -518,9 +545,16 @@ module ClaudeAgentSDK
     end
   end
 
-  # Tool permission context
+  # Tool permission context delivered to `can_use_tool` callbacks.
+  # CLI 2.1.110+ began populating the four pre-formatted display fields
+  # (`title`, `display_name`, `description`, `blocked_path`,
+  # `decision_reason`) so the SDK consumer can render the same prompt UI
+  # the CLI would have shown. Older fields (`signal`, `suggestions`,
+  # `tool_use_id`, `agent_id`) remain unchanged.
   class ToolPermissionContext < Type
-    attr_accessor :signal, :suggestions, :tool_use_id, :agent_id
+    attr_accessor :signal, :suggestions, :tool_use_id, :agent_id,
+                  :title, :display_name, :description,
+                  :blocked_path, :decision_reason
 
     def initialize(attributes = {})
       super
@@ -885,9 +919,15 @@ module ClaudeAgentSDK
     end
   end
 
-  # PostToolUse hook specific output
+  # PostToolUse hook specific output.
+  #
+  # `updated_tool_output` (CLI 2.1.110+) replaces the tool's output entirely
+  # — works for any tool, MCP or built-in. `updated_mcp_tool_output` is the
+  # legacy MCP-only field that pre-dates the unified one; the CLI still
+  # honors it, so both are emitted when set. Mirrors Python's
+  # `PostToolUseHookSpecificOutput`.
   class PostToolUseHookSpecificOutput < Type
-    attr_accessor :additional_context, :updated_mcp_tool_output
+    attr_accessor :additional_context, :updated_mcp_tool_output, :updated_tool_output
     attr_reader :hook_event_name
 
     def initialize(attributes = {})
@@ -898,6 +938,7 @@ module ClaudeAgentSDK
     def to_h
       result = { hookEventName: @hook_event_name }
       result[:additionalContext] = @additional_context if @additional_context
+      result[:updatedToolOutput] = @updated_tool_output unless @updated_tool_output.nil?
       result[:updatedMCPToolOutput] = @updated_mcp_tool_output if @updated_mcp_tool_output
       result
     end

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.16.7
+  version: 0.16.8
 platform: ruby
 authors:
 - Community Contributors
@@ -104,6 +104,15 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/client.md
+- docs/configuration.md
+- docs/errors.md
+- docs/hooks-and-permissions.md
+- docs/mcp-servers.md
+- docs/observability.md
+- docs/rails.md
+- docs/sessions.md
+- docs/types.md
 - lib/claude_agent_sdk.rb
 - lib/claude_agent_sdk/command_builder.rb
 - lib/claude_agent_sdk/configuration.rb