claude-agent-sdk 0.16.7 → 0.16.9

data/docs/types.md

@@ -0,0 +1,187 @@
+# Types Reference
+
+See [lib/claude_agent_sdk/types.rb](../lib/claude_agent_sdk/types.rb) for complete type definitions.
+
+## Message Types
+
+```ruby
+# Union type of all possible messages
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage
+```
+
+### UserMessage
+
+User input message.
+
+```ruby
+class UserMessage
+  attr_accessor :content,            # String | Array<ContentBlock>
+                :uuid,               # String | nil - Unique ID for rewind support
+                :parent_tool_use_id, # String | nil
+                :tool_use_result     # Hash | nil - Tool result data when message is a tool response
+end
+```
+
+### AssistantMessage
+
+Assistant response message with content blocks.
+
+```ruby
+class AssistantMessage
+  attr_accessor :content,            # Array<ContentBlock>
+                :model,              # String
+                :parent_tool_use_id, # String | nil
+                :error,              # String | nil ('authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'unknown')
+                :usage               # Hash | nil - Token usage info from the API response
+end
+```
+
+### SystemMessage
+
+System message with metadata. Task lifecycle events are typed subclasses.
+
+```ruby
+class SystemMessage
+  attr_accessor :subtype,  # String ('init', 'task_started', 'task_progress', 'task_notification', etc.)
+                :data      # Hash
+end
+
+# Typed subclasses (all inherit from SystemMessage, so is_a?(SystemMessage) still works)
+class TaskStartedMessage < SystemMessage
+  attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type
+end
+
+class TaskProgressMessage < SystemMessage
+  attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name
+end
+
+class TaskNotificationMessage < SystemMessage
+  attr_accessor :task_id, :status, :output_file, :summary, :uuid, :session_id, :tool_use_id, :usage
+end
+```
+
+### ResultMessage
+
+Final result message with cost and usage information.
+
+```ruby
+class ResultMessage
+  attr_accessor :subtype,           # String
+                :duration_ms,       # Integer
+                :duration_api_ms,   # Integer
+                :is_error,          # Boolean
+                :num_turns,         # Integer
+                :session_id,        # String
+                :stop_reason,       # String | nil ('end_turn', 'max_tokens', 'stop_sequence')
+                :total_cost_usd,    # Float | nil
+                :usage,             # Hash | nil
+                :result,            # String | nil (final text result)
+                :structured_output  # Hash | nil (when using output_format)
+end
+```
+
+## Content Block Types
+
+```ruby
+# Union type of all content blocks
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | UnknownBlock
+```
+
+### TextBlock
+
+```ruby
+class TextBlock
+  attr_accessor :text  # String
+end
+```
+
+### ThinkingBlock
+
+For models with extended thinking capability.
+
+```ruby
+class ThinkingBlock
+  attr_accessor :thinking,  # String
+                :signature  # String
+end
+```
+
+### ToolUseBlock
+
+Tool use request block.
+
+```ruby
+class ToolUseBlock
+  attr_accessor :id,    # String
+                :name,  # String
+                :input  # Hash
+end
+```
+
+### ToolResultBlock
+
+Tool execution result block.
+
+```ruby
+class ToolResultBlock
+  attr_accessor :tool_use_id,  # String
+                :content,      # String | Array<Hash> | nil
+                :is_error      # Boolean | nil
+end
+```
+
+### UnknownBlock
+
+Generic content block for types the SDK doesn't explicitly handle (e.g., `document` for PDFs, `image` for inline images). Preserves the raw data for forward compatibility with newer CLI versions.
+
+```ruby
+class UnknownBlock
+  attr_accessor :type,  # String — the original block type (e.g., "document")
+                :data   # Hash — the full raw block hash
+end
+```
+
+## Configuration Types
+
+| Type | Description |
+|------|-------------|
+| `Configuration` | Global defaults via `ClaudeAgentSDK.configure` block |
+| `ClaudeAgentOptions` | Main configuration for queries and clients |
+| `HookMatcher` | Hook configuration with matcher pattern and timeout |
+| `PermissionResultAllow` | Permission callback result to allow tool use |
+| `PermissionResultDeny` | Permission callback result to deny tool use |
+| `AgentDefinition` | Agent definition with description, prompt, tools, model, skills, memory, mcp_servers |
+| `ThinkingConfigAdaptive` | Adaptive thinking mode (CLI dynamically adjusts budget) |
+| `ThinkingConfigEnabled` | Enabled thinking with explicit `budget_tokens` |
+| `ThinkingConfigDisabled` | Disabled thinking |
+| `SdkMcpTool` | SDK MCP tool definition with name, description, input_schema, handler, annotations |
+| `McpStdioServerConfig` | MCP server config for stdio transport |
+| `McpSSEServerConfig` | MCP server config for SSE transport |
+| `McpHttpServerConfig` | MCP server config for HTTP transport |
+| `SdkPluginConfig` | SDK plugin configuration |
+| `McpServerStatus` | Status of a single MCP server connection (with `.parse`) |
+| `McpStatusResponse` | Response from `get_mcp_status` containing all server statuses (with `.parse`) |
+| `McpServerInfo` | MCP server name and version |
+| `McpToolInfo` | MCP tool name, description, and annotations |
+| `McpToolAnnotations` | MCP tool annotation hints (`read_only`, `destructive`, `open_world`) |
+| `TaskUsage` | Typed usage data (`total_tokens`, `tool_uses`, `duration_ms`) with `from_hash` factory |
+| `SDKSessionInfo` | Session metadata from `list_sessions` |
+| `SessionMessage` | Single message from `get_session_messages` |
+| `SandboxSettings` | Sandbox settings for isolated command execution |
+| `SandboxNetworkConfig` | Network configuration for sandbox |
+| `SandboxIgnoreViolations` | Configure which sandbox violations to ignore |
+| `SystemPromptPreset` | System prompt preset configuration |
+| `ToolsPreset` | Tools preset configuration for base tools selection |
+
+## Constants
+
+| Constant | Description |
+|----------|-------------|
+| `SDK_BETAS` | Available beta features (e.g., `"context-1m-2025-08-07"`) |
+| `PERMISSION_MODES` | Available permission modes |
+| `SETTING_SOURCES` | Available setting sources |
+| `HOOK_EVENTS` | Available hook events |
+| `ASSISTANT_MESSAGE_ERRORS` | Possible error types in AssistantMessage |
+| `TASK_NOTIFICATION_STATUSES` | Task lifecycle notification statuses (`completed`, `failed`, `stopped`) |
+| `MCP_SERVER_CONNECTION_STATUSES` | MCP server connection states (`connected`, `failed`, `needs-auth`, `pending`, `disabled`) |
+| `EFFORT_LEVELS` | Effort levels (`low`, `medium`, `high`, `xhigh`, `max`) |

data/lib/claude_agent_sdk/command_builder.rb

@@ -103,6 +103,11 @@ module ClaudeAgentSDK
     end
 
     def append_session(cmd)
+      # `--continue` and `--resume <id>` are mutually exclusive session-restore
+      # modes. Passing both surfaces as a generic non-zero CLI exit, which is
+      # painful to debug at the caller; raise early in the SDK stack instead.
+      raise ArgumentError, "continue_conversation and resume are mutually exclusive" if @options.continue_conversation && @options.resume
+
       cmd.push("--continue") if @options.continue_conversation
       cmd.push("--resume", @options.resume) if @options.resume
       append_resume_session_at(cmd)

data/lib/claude_agent_sdk/message_parser.rb

@@ -153,6 +153,14 @@ module ClaudeAgentSDK
           content: get.call(:content),
           is_error: get.call(:is_error)
         )
+      when 'server_tool_use'
+        ServerToolUseBlock.new(id: get.call(:id), name: get.call(:name), input: get.call(:input))
+      when 'server_tool_result'
+        ServerToolResultBlock.new(
+          tool_use_id: get.call(:tool_use_id),
+          content: get.call(:content),
+          is_error: get.call(:is_error)
+        )
       else
         # Forward-compatible: preserve unrecognized content block types (e.g., "document", "image")
         # so newer CLI versions don't crash older SDK versions.

data/lib/claude_agent_sdk/query.rb

@@ -22,6 +22,10 @@ module ClaudeAgentSDK
 
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
+    # NOTE: CLAUDE_CODE_STREAM_CLOSE_TIMEOUT is defined by the CLI in
+    # MILLISECONDS (Python SDK uses `int(os.environ[...])/1000`); the SDK
+    # divides by 1000 to obtain seconds. The default below is *seconds*
+    # for direct use without env conversion (60 s = the CLI's 60000 ms).
     STREAM_CLOSE_TIMEOUT_ENV_VAR = 'CLAUDE_CODE_STREAM_CLOSE_TIMEOUT'
     DEFAULT_STREAM_CLOSE_TIMEOUT_SECONDS = 60.0
 
@@ -119,13 +123,31 @@ module ClaudeAgentSDK
       response
     end
 
-    # Start reading messages from transport
+    # Start reading messages from transport.
+    #
+    # Spawns `read_messages` as a direct child task of the current Async
+    # task and stores that child in `@task`. An earlier version wrapped
+    # `task.async { read_messages }` inside an outer `Async do ... end` and
+    # assigned the outer task to `@task`; the outer task completed almost
+    # immediately after spawning, so `close`'s `@task.stop` never reached
+    # the actual `read_messages` fiber and the read loop kept running
+    # until the transport raised. Now `@task.stop` stops the read loop.
+    #
+    # Must be called inside an Async{} block (matches `query()` which wraps
+    # its own internals in Async, and the documented `Client#connect`
+    # pattern). If invoked outside a reactor, raise a clear error rather
+    # than letting Async::Task.current raise an opaque "No async task
+    # available!" — earlier versions of this method *appeared* to work
+    # from synchronous callers but actually hung indefinitely because the
+    # outer Async{} root task waited for read_messages to finish, which
+    # never happens for a live Client.
     def start
       return if @task
 
-      @task = Async do |task|
-        task.async { read_messages }
-      end
+      parent = Async::Task.current?
+      raise CLIConnectionError, 'Query#start must be called inside an Async{} block (e.g. wrap Client#connect in Async{...})' unless parent
+
+      @task = parent.async { read_messages }
     end
 
     private
@@ -644,23 +666,30 @@ module ClaudeAgentSDK
 
       writeln(JSON.generate(control_request))
 
-      # Wait for response with timeout (default 1200s to handle slow CLI startup)
-      Async do |task|
-        task.with_timeout(timeout_seconds) do
+      # Wait for response with timeout. Use the current task's timeout so we
+      # stay in the caller's fiber (a nested `Async do ... end.wait` spawned a
+      # separate task and could leak the pending entries when an Async::Stop
+      # propagated through `.wait` before either the success-path or the
+      # timeout-path cleanup ran). Control requests must run inside an Async
+      # reactor — `Query#start` already enforces this precondition, so the
+      # cleanest place to surface the contract is the start hand-off; here we
+      # assume an active task is present.
+      begin
+        Async::Task.current.with_timeout(timeout_seconds) do
           condition.wait
         end
-
-        result = @pending_control_results.delete(request_id)
-        @pending_control_responses.delete(request_id)
-
+        result = @pending_control_results[request_id]
         raise result if result.is_a?(Exception)
 
-        result[:response] || {}
-      end.wait
-    rescue Async::TimeoutError
-      @pending_control_responses.delete(request_id)
-      @pending_control_results.delete(request_id)
-      raise ControlRequestTimeoutError, "Control request timeout: #{request[:subtype]}"
+        result&.[](:response) || {}
+      rescue Async::TimeoutError
+        raise ControlRequestTimeoutError, "Control request timeout: #{request[:subtype]}"
+      ensure
+        # Always evict the entries so a late control_response (after timeout)
+        # or an Async::Stop propagating through wait does not leak state.
+        @pending_control_responses.delete(request_id)
+        @pending_control_results.delete(request_id)
+      end
     end
 
     def handle_sdk_mcp_request(server_name, message)

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -111,8 +111,10 @@ module ClaudeAgentSDK
       resource = @resources.find { |r| r.uri == uri }
       raise "Resource '#{uri}' not found" unless resource
 
-      # Call the resource's reader
-      content = resource.reader.call
+      # Hop off the Fiber scheduler before invoking user code — same reason
+      # as `call_tool` above: reader blocks may touch Thread.current-keyed
+      # libraries (ActiveRecord, pg, ...) and must run on a plain thread.
+      content = FiberBoundary.invoke { resource.reader.call }
 
       # Ensure content has the expected format
       unless content.is_a?(Hash) && content[:contents]
@@ -142,8 +144,9 @@ module ClaudeAgentSDK
       prompt = @prompts.find { |p| p.name == name }
       raise "Prompt '#{name}' not found" unless prompt
 
-      # Call the prompt's generator
-      result = prompt.generator.call(arguments)
+      # Hop off the Fiber scheduler before invoking user code — same reason
+      # as `call_tool` above.
+      result = FiberBoundary.invoke { prompt.generator.call(arguments) }
 
       # Ensure result has the expected format
       unless result.is_a?(Hash) && result[:messages]
@@ -276,7 +279,9 @@ module ClaudeAgentSDK
             end
 
             def read
-              result = @resource_def.reader.call
+              # Hop off the Fiber scheduler before invoking user code so the
+              # async gem's scheduler is not visible to ActiveRecord / pg.
+              result = ClaudeAgentSDK::FiberBoundary.invoke { @resource_def.reader.call }
 
               # Convert to MCP format
               result[:contents].map do |content|
@@ -315,7 +320,8 @@ module ClaudeAgentSDK
             end
 
             def get(**args)
-              result = @prompt_def.generator.call(args)
+              # Hop off the Fiber scheduler before invoking user code (see read above).
+              result = ClaudeAgentSDK::FiberBoundary.invoke { @prompt_def.generator.call(args) }
 
               # Convert to MCP format
               {

data/lib/claude_agent_sdk/session_mutations.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'securerandom'
+require 'fileutils'
 require_relative 'sessions'
 
 module ClaudeAgentSDK
@@ -13,6 +14,13 @@ module ClaudeAgentSDK
   module SessionMutations # rubocop:disable Metrics/ModuleLength
     module_function
 
+    # Transcript entry types kept in fork output. Mirrors Python's
+    # `_TRANSCRIPT_TYPES`. Other types (custom-title, tag, aiTitle,
+    # permission-mode, etc.) carry session metadata and must not bleed
+    # into the fork's transcript body — they are reconstructed for the
+    # fork's own sessionId after the body is written.
+    TRANSCRIPT_TYPES = %w[user assistant attachment system progress].freeze
+
     # Rename a session by appending a custom-title entry.
     #
     # list_sessions reads the LAST custom-title from the file tail, so
@@ -83,6 +91,13 @@ module ClaudeAgentSDK
       rescue Errno::ENOENT
         raise Errno::ENOENT, "Session #{session_id} not found"
       end
+
+      # Subagent transcripts live in a sibling directory named after the
+      # session ID. Without removing it, the CLI would later pick up
+      # orphaned subagent state if the same session ID happened to be
+      # reused. Matches Python's `shutil.rmtree(path.parent / session_id)`.
+      subagent_dir = File.join(File.dirname(path), session_id)
+      FileUtils.rm_rf(subagent_dir) if File.directory?(subagent_dir)
     end
 
     # Fork a session into a new branch with fresh UUIDs.
@@ -111,7 +126,7 @@ module ClaudeAgentSDK
       file_size = File.size(file_path)
       raise ArgumentError, "Session #{session_id} has no messages to fork" if file_size.zero?
 
-      transcript, content_replacements = parse_fork_transcript(file_path)
+      transcript, content_replacements = parse_fork_transcript(file_path, session_id)
       transcript.reject! { |e| e['isSidechain'] }
       raise ArgumentError, "Session #{session_id} has no messages to fork" if transcript.empty?
 
@@ -140,12 +155,18 @@ module ClaudeAgentSDK
                            forked_session_id, session_id, now)
       end
 
-      # Append content-replacement entry if any
+      # Append content-replacement entry if any. The entry needs `uuid` and
+      # `timestamp` so a *second* fork of this forked session can re-ingest
+      # it — `parse_fork_transcript` gates content-replacement on the entry
+      # being a valid hash with a matching `sessionId`, and the CLI's own
+      # tools index entries by uuid. Matches Python's `_emit_fork_to_disk`.
       if content_replacements && !content_replacements.empty?
         lines << JSON.generate({
                                  'type' => 'content-replacement',
                                  'sessionId' => forked_session_id,
-                                 'replacements' => content_replacements
+                                 'replacements' => content_replacements,
+                                 'uuid' => SecureRandom.uuid,
+                                 'timestamp' => now
                                })
       end
 
@@ -156,7 +177,9 @@ module ClaudeAgentSDK
       lines << JSON.generate({
                                'type' => 'custom-title',
                                'sessionId' => forked_session_id,
-                               'customTitle' => fork_title
+                               'customTitle' => fork_title,
+                               'uuid' => SecureRandom.uuid,
+                               'timestamp' => now
                              })
 
       fork_path = File.join(project_dir, "#{forked_session_id}.jsonl")
@@ -229,9 +252,17 @@ module ClaudeAgentSDK
     # Parse a fork transcript by streaming the JSONL file line-by-line.
     # Opens in binary mode and scrubs invalid UTF-8 so stray non-UTF-8
     # bytes in tool results do not raise Encoding::InvalidByteSequenceError.
-    def parse_fork_transcript(file_path)
+    #
+    # Only `TRANSCRIPT_TYPES` entries with a string uuid are kept in the
+    # transcript body — `custom-title`, `tag`, `aiTitle`, `permission-mode`
+    # and other metadata entries are reconstructed for the new sessionId
+    # by the caller. `content-replacement` entries are collected across the
+    # entire file (one per compaction round) — concatenated rather than
+    # overwritten — and only kept if their `sessionId` matches the source.
+    # Matches Python's `_parse_fork_transcript` exactly.
+    def parse_fork_transcript(file_path, source_session_id = nil)
       transcript = []
-      content_replacements = nil
+      content_replacements = []
 
       File.foreach(file_path, mode: 'rb') do |line|
         line = line.force_encoding('UTF-8').scrub
@@ -240,13 +271,16 @@ module ClaudeAgentSDK
         rescue JSON::ParserError
           next
         end
-        next unless entry.is_a?(Hash) && entry['uuid']
-
-        if entry['type'] == 'content-replacement'
-          content_replacements = entry['replacements']
-          next
+        next unless entry.is_a?(Hash)
+
+        entry_type = entry['type']
+        if TRANSCRIPT_TYPES.include?(entry_type) && entry['uuid'].is_a?(String)
+          transcript << entry
+        elsif entry_type == 'content-replacement' &&
+              (source_session_id.nil? || entry['sessionId'] == source_session_id) &&
+              entry['replacements'].is_a?(Array)
+          content_replacements.concat(entry['replacements'])
         end
-        transcript << entry
       end
 
       [transcript, content_replacements]

data/lib/claude_agent_sdk/sessions.rb

@@ -472,16 +472,56 @@ module ClaudeAgentSDK
       by_id.values
     end
 
+    # Probe git for the worktree list with a hard 5-second cap. A stale
+    # git lock or hung network mount must not block the listing path
+    # forever. Stdlib `Timeout.timeout` raises across threads via
+    # `Thread#raise`, which corrupts the Async fiber-scheduler state when
+    # the caller is inside a reactor, so we drain stdout/stderr on side
+    # threads (so a full pipe buffer can't deadlock git) and SIGKILL the
+    # child if the deadline passes. Matches Python's
+    # `subprocess.run(..., timeout=5)`.
     def detect_worktrees(path)
-      output, _err, status = Open3.capture3('git', '-C', path, 'worktree', 'list', '--porcelain')
-      return [path] unless status.success?
+      stdin, stdout, stderr, wait_thr = Open3.popen3('git', '-C', path, 'worktree', 'list', '--porcelain')
+      stdin.close
+
+      # Drain stdout/stderr concurrently — without this, a repo with enough
+      # worktrees to overrun the 64 KB pipe buffer causes git to block on
+      # write, wait_thr never finishes, and we hit the 5-second watchdog
+      # and silently lose every worktree path.
+      stdout_buf = +''
+      stdout_reader = Thread.new { stdout_buf << stdout.read.to_s }
+      stderr_reader = Thread.new { stderr.read }
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5.0
+      until wait_thr.join(0.1)
+        next if Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+
+        begin
+          Process.kill('KILL', wait_thr.pid)
+        rescue Errno::ESRCH
+          # Already exited between the join check and the kill.
+        end
+        wait_thr.join
+        stdout_reader.join(0.5)
+        stderr_reader.join(0.5)
+        return [path]
+      end
+
+      stdout_reader.join
+      stderr_reader.join
+
+      return [path] unless wait_thr.value.success?
 
-      paths = output.lines.filter_map do |line|
+      paths = stdout_buf.lines.filter_map do |line|
         line.strip.delete_prefix('worktree ') if line.start_with?('worktree ')
       end
       paths.empty? ? [path] : paths
     rescue StandardError
       [path]
+    ensure
+      stdout_reader&.kill if stdout_reader&.alive?
+      stderr_reader&.kill if stderr_reader&.alive?
+      [stdout, stderr].each { |io| io&.close rescue nil } # rubocop:disable Style/RescueModifier
     end
 
     def find_session_file(session_id, directory)