claude-agent-sdk 0.36.0 → 1.0.0

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -29,9 +29,11 @@ require 'async'
 require 'securerandom'
 
 # Claude Agent SDK for Ruby
-module ClaudeAgentSDK
+module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry points (query, ask, sessions API) live on the root module
   # The duck-typed observer surface probed by resolve_observers — implementing
   # any one of these counts as an observer (see Observer's no-op defaults).
+  #
+  # @api private
   OBSERVER_INTERFACE = %i[on_user_prompt on_message on_error on_close].freeze
 
   # Resolve observers array: callables (Proc/lambda) are invoked to produce
@@ -117,7 +119,9 @@ module ClaudeAgentSDK
     return options unless options.can_use_tool
 
     # can_use_tool and permission_prompt_tool_name are mutually exclusive
-    raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name' if options.permission_prompt_tool_name
+    if options.permission_prompt_tool_name
+      raise ArgumentError, 'can_use_tool callback cannot be used with permission_prompt_tool_name'
+    end
 
     # Advisory: warn if other options shadow the callback. After the
     # ArgumentError above so invalid configs raise, not warn.
@@ -537,27 +541,27 @@ module ClaudeAgentSDK
     SessionSummary.fold_session_summary(prev, key, entries)
   end
 
-  # ---- Deprecated store twins (removed in 1.0) ----
+  # ---- Deprecated store twins (removed in 2.0) ----
   #
   # Each forwards to the same implementation as before — not to the merged
   # function, so a nil session_store keeps failing as it always did instead
   # of silently reading local disk — after one warning per method per process.
 
-  # @deprecated Use {.list_sessions} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.list_sessions} with +session_store:+. Removed in 2.0.
   # @return [Array<SDKSessionInfo>] sorted by last_modified descending
   def self.list_sessions_from_store(session_store:, directory: nil, limit: nil, offset: 0)
     Deprecation.warn_once(:list_sessions_from_store, 'list_sessions(session_store: store)')
     Sessions.list_sessions_from_store(session_store: session_store, directory: directory, limit: limit, offset: offset)
   end
 
-  # @deprecated Use {.get_session_info} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.get_session_info} with +session_store:+. Removed in 2.0.
   # @return [SDKSessionInfo, nil]
   def self.get_session_info_from_store(session_store:, session_id:, directory: nil)
     Deprecation.warn_once(:get_session_info_from_store, 'get_session_info(session_store: store, ...)')
     Sessions.get_session_info_from_store(session_store: session_store, session_id: session_id, directory: directory)
   end
 
-  # @deprecated Use {.get_session_messages} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.get_session_messages} with +session_store:+. Removed in 2.0.
   # @return [Array<SessionMessage>]
   def self.get_session_messages_from_store(session_store:, session_id:, directory: nil, limit: nil, offset: 0)
     Deprecation.warn_once(:get_session_messages_from_store, 'get_session_messages(session_store: store, ...)')
@@ -565,14 +569,14 @@ module ClaudeAgentSDK
                                              directory: directory, limit: limit, offset: offset)
   end
 
-  # @deprecated Use {.list_subagents} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.list_subagents} with +session_store:+. Removed in 2.0.
   # @return [Array<String>]
   def self.list_subagents_from_store(session_store:, session_id:, directory: nil)
     Deprecation.warn_once(:list_subagents_from_store, 'list_subagents(session_store: store, ...)')
     Sessions.list_subagents_from_store(session_store: session_store, session_id: session_id, directory: directory)
   end
 
-  # @deprecated Use {.get_subagent_metadata} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.get_subagent_metadata} with +session_store:+. Removed in 2.0.
   # @return [Hash{String => Object}, nil]
   def self.get_subagent_metadata_from_store(session_store:, session_id:, agent_id:, directory: nil)
     Deprecation.warn_once(:get_subagent_metadata_from_store, 'get_subagent_metadata(session_store: store, ...)')
@@ -580,7 +584,7 @@ module ClaudeAgentSDK
                                               agent_id: agent_id, directory: directory)
   end
 
-  # @deprecated Use {.get_subagent_messages} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.get_subagent_messages} with +session_store:+. Removed in 2.0.
   # @return [Array<SessionMessage>]
   def self.get_subagent_messages_from_store(session_store:, session_id:, agent_id:, directory: nil, limit: nil,
                                             offset: 0)
@@ -589,28 +593,28 @@ module ClaudeAgentSDK
                                               agent_id: agent_id, directory: directory, limit: limit, offset: offset)
   end
 
-  # @deprecated Use {.rename_session} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.rename_session} with +session_store:+. Removed in 2.0.
   def self.rename_session_via_store(session_store:, session_id:, title:, directory: nil)
     Deprecation.warn_once(:rename_session_via_store, 'rename_session(session_store: store, ...)')
     SessionMutations.rename_session_via_store(session_store: session_store, session_id: session_id,
                                               title: title, directory: directory)
   end
 
-  # @deprecated Use {.tag_session} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.tag_session} with +session_store:+. Removed in 2.0.
   def self.tag_session_via_store(session_store:, session_id:, tag:, directory: nil)
     Deprecation.warn_once(:tag_session_via_store, 'tag_session(session_store: store, ...)')
     SessionMutations.tag_session_via_store(session_store: session_store, session_id: session_id,
                                            tag: tag, directory: directory)
   end
 
-  # @deprecated Use {.delete_session} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.delete_session} with +session_store:+. Removed in 2.0.
   def self.delete_session_via_store(session_store:, session_id:, directory: nil)
     Deprecation.warn_once(:delete_session_via_store, 'delete_session(session_store: store, ...)')
     SessionMutations.delete_session_via_store(session_store: session_store, session_id: session_id,
                                               directory: directory)
   end
 
-  # @deprecated Use {.fork_session} with +session_store:+. Removed in 1.0.
+  # @deprecated Use {.fork_session} with +session_store:+. Removed in 2.0.
   # @return [ForkSessionResult]
   def self.fork_session_via_store(session_store:, session_id:, directory: nil, up_to_message_id: nil, title: nil)
     Deprecation.warn_once(:fork_session_via_store, 'fork_session(session_store: store, ...)')
@@ -621,6 +625,7 @@ module ClaudeAgentSDK
   # Replay a local on-disk session transcript into a SessionStore (migration /
   # gap-backfill). Keys under the on-disk project dir so the imported session is
   # resumable via session_store + resume from the original cwd.
+  # @param batch_size [Integer] entries per SessionStore#append call (default 500)
   # @raise [ArgumentError] if session_id is not a valid UUID
   # @raise [Errno::ENOENT] if the session JSONL cannot be found
   def self.import_session_to_store(session_id:, session_store:, directory: nil, include_subagents: true,
@@ -664,13 +669,17 @@ module ClaudeAgentSDK
   #   ClaudeAgentSDK.query(prompt: messages) do |message|
   #     puts message
   #   end
-  def self.query(prompt:, options: nil, transport: nil, &block)
+  def self.query(prompt:, options: nil, transport: nil, &block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- one-shot lifecycle (validate, resume, connect, stream, teardown) kept linear
     # 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)
+    if prompt.is_a?(Hash)
+      raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)'
+    end
+    unless prompt.is_a?(String) || prompt.respond_to?(:each)
+      raise ArgumentError, "prompt must be a String or respond to #each (got #{prompt.class})"
+    end
 
     return enum_for(:query, prompt: prompt, options: options, transport: transport) unless block
 
@@ -690,9 +699,11 @@ module ClaudeAgentSDK
     callback_wrapper = configured_options.callback_wrapper
     ClaudeAgentSDK.check_inline_isolation(callback_scheduling)
 
-    raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)' if transport && !transport.respond_to?(:connect)
+    if transport && !transport.respond_to?(:connect)
+      raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)'
+    end
 
-    Async(&FiberBoundary.capture_otel_context do
+    Async(&FiberBoundary.capture_otel_context do # rubocop:disable Metrics/BlockLength -- the reactor task body of query()
       materialized = nil
       query_handler = nil
       begin
@@ -705,7 +716,9 @@ module ClaudeAgentSDK
           # env/--resume only apply to the CLI subprocess (Python parity:
           # client.py skips materialization when a transport is supplied).
           materialized = SessionResume.materialize_resume_session(configured_options)
-          configured_options = SessionResume.apply_materialized_options(configured_options, materialized) if materialized
+          if materialized
+            configured_options = SessionResume.apply_materialized_options(configured_options, materialized)
+          end
 
           # Always use streaming mode with control protocol (matches Python
           # SDK). This sends agents via initialize request instead of CLI
@@ -769,7 +782,7 @@ module ClaudeAgentSDK
             parent_tool_use_id: nil,
             session_id: ''
           }
-          transport.write(JSON.generate(message) + "\n")
+          transport.write("#{JSON.generate(message)}\n")
           # Background-spawn so messages stream to the user block while stdin
           # close waits (without timeout) for the first result; a synchronous
           # call would defer all delivery until the turn completes (mirrors
@@ -780,8 +793,9 @@ module ClaudeAgentSDK
           # here kept the root reactor alive forever when the read loop died
           # while the user enumerator was still blocked (matches Python's
           # query.spawn_task(query.stream_input(prompt))).
-          observed_prompt = ClaudeAgentSDK.observing_prompt_stream(prompt, resolved_observers,
-                                                                   scheduling: callback_scheduling, wrapper: callback_wrapper)
+          observed_prompt = ClaudeAgentSDK.observing_prompt_stream(
+            prompt, resolved_observers, scheduling: callback_scheduling, wrapper: callback_wrapper
+          )
           query_handler.spawn_task { query_handler.stream_input(observed_prompt) }
         end
 
@@ -916,7 +930,10 @@ module ClaudeAgentSDK
   #     }
   #   )
   #   client = ClaudeAgentSDK::Client.new(options: options)
-  class Client
+  class Client # rubocop:disable Metrics/ClassLength -- public session API: lifecycle, control methods and their Ruby aliases
+    # The session's control-protocol handler (nil until #connect).
+    #
+    # @api private
     attr_reader :query_handler
 
     # @param options [ClaudeAgentOptions, nil] Configuration options
@@ -983,8 +1000,12 @@ module ClaudeAgentSDK
     def connect(prompt = nil)
       return if @connected
 
-      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, an Enumerator, or nil (got #{prompt.class})" unless prompt.nil? || prompt.is_a?(String) || prompt.respond_to?(:each)
+      if prompt.is_a?(Hash)
+        raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)'
+      end
+      unless prompt.nil? || prompt.is_a?(String) || prompt.respond_to?(:each)
+        raise ArgumentError, "prompt must be a String, an Enumerator, or nil (got #{prompt.class})"
+      end
 
       # Validate and configure permission settings
       configured_options = ClaudeAgentSDK.configure_can_use_tool(@options)
@@ -1049,7 +1070,9 @@ module ClaudeAgentSDK
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
       # A bare Hash responds to #each and would silently iterate [key, value]
       # pairs (Python's async-for over a dict raises TypeError).
-      raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)' if prompt.is_a?(Hash)
+      if prompt.is_a?(Hash)
+        raise ArgumentError, 'prompt must be a String or an Enumerable of message Hashes/JSONL Strings (got Hash)'
+      end
 
       begin
         if prompt.is_a?(String)
@@ -1139,6 +1162,7 @@ module ClaudeAgentSDK
     # Send interrupt signal
     def interrupt
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.interrupt
     end
 
@@ -1146,6 +1170,7 @@ module ClaudeAgentSDK
     # @param mode [String] Permission mode ('default', 'acceptEdits', 'bypassPermissions')
     def set_permission_mode(mode)
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.set_permission_mode(mode)
     end
 
@@ -1159,6 +1184,7 @@ module ClaudeAgentSDK
     # @param model [String, nil] Model name or nil for default
     def set_model(model)
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.set_model(model)
     end
 
@@ -1171,6 +1197,7 @@ module ClaudeAgentSDK
     # @param server_name [String] Name of the MCP server to reconnect
     def reconnect_mcp_server(server_name)
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.reconnect_mcp_server(server_name)
     end
 
@@ -1179,6 +1206,7 @@ module ClaudeAgentSDK
     # @param enabled [Boolean] Whether to enable or disable
     def toggle_mcp_server(server_name, enabled)
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.toggle_mcp_server(server_name, enabled)
     end
 
@@ -1186,6 +1214,7 @@ module ClaudeAgentSDK
     # @param task_id [String] The ID of the task to stop
     def stop_task(task_id)
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.stop_task(task_id)
     end
 
@@ -1211,6 +1240,7 @@ module ClaudeAgentSDK
     # @raise [ArgumentError] if tool_use_id is neither nil nor a non-empty String
     def background_tasks(tool_use_id: nil)
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.background_tasks(tool_use_id: tool_use_id)
     end
 
@@ -1220,13 +1250,14 @@ module ClaudeAgentSDK
     # @param user_message_uuid [String] The UUID of the UserMessage to rewind to
     def rewind_files(user_message_uuid)
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.rewind_files(user_message_uuid)
     end
 
     # Get server initialization info
     # @return [Hash, nil] Server info or nil
     def server_info
-      @query_handler&.instance_variable_get(:@initialization_result)
+      @query_handler&.initialization_result
     end
 
     # Get a breakdown of current context window usage by category.
@@ -1235,6 +1266,7 @@ module ClaudeAgentSDK
     # @return [Hash] Context usage response
     def get_context_usage
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.get_context_usage
     end
 
@@ -1248,6 +1280,7 @@ module ClaudeAgentSDK
     # @return [Hash] MCP status information, including mcpServers list
     def get_mcp_status
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.get_mcp_status
     end
 
@@ -1261,6 +1294,7 @@ module ClaudeAgentSDK
     # @return [Hash] Server info
     def get_server_info
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       server_info
     end
 
@@ -1343,7 +1377,7 @@ module ClaudeAgentSDK
     end
 
     # The connect body, wrapped by #connect so a failure triggers cleanup.
-    def connect_inner(configured_options, prompt)
+    def connect_inner(configured_options, prompt) # rubocop:disable Metrics/MethodLength -- connect sequence kept in order; #connect wraps it for cleanup
       # Client always uses streaming mode; keep stdin open for bidirectional
       # communication. Observers were already resolved by #connect.
       @transport = @transport_class.new(configured_options, **@transport_args)

data/sig/claude_agent_sdk/cancellation_signal.rbs

@@ -0,0 +1,14 @@
+module ClaudeAgentSDK
+  # Delivered as ToolPermissionContext#signal and HookContext#signal. It is
+  # cancelled when the CLI cancels the request (or the session closes), so a
+  # long-running callback can stop early.
+  class CancellationSignal
+    def initialize: () -> void
+
+    def cancelled?: () -> bool
+
+    # Blocks until cancelled or until timeout seconds pass; returns
+    # #cancelled?.
+    def wait: (?timeout: (Integer | Float)?) -> bool
+  end
+end

data/sig/claude_agent_sdk/configuration.rbs

@@ -0,0 +1,14 @@
+module ClaudeAgentSDK
+  # Global defaults set via ClaudeAgentSDK.configure, merged under every
+  # ClaudeAgentOptions (per-call options win).
+  class Configuration
+    # A frozen snapshot of the configured defaults ({} when unset). Keys are
+    # ClaudeAgentOptions option names.
+    attr_reader default_options: Hash[Symbol | String, untyped]
+
+    def initialize: () -> void
+
+    # Stores a deep-frozen copy; nil resets to {}.
+    def default_options=: (Hash[Symbol | String, untyped]? value) -> Hash[Symbol | String, untyped]?
+  end
+end

data/sig/claude_agent_sdk/errors.rbs

@@ -0,0 +1,86 @@
+module ClaudeAgentSDK
+  # Base exception for all Claude SDK errors.
+  class ClaudeSDKError < StandardError
+  end
+
+  # Raised when unable to connect to Claude Code (also: "Not connected").
+  class CLIConnectionError < ClaudeSDKError
+  end
+
+  # Raised when the control protocol does not respond in time.
+  class ControlRequestTimeoutError < CLIConnectionError
+  end
+
+  # Raised when Claude Code is not found or not installed.
+  class CLINotFoundError < CLIConnectionError
+    def initialize: (?String message, ?cli_path: (String | Pathname)?) -> void
+  end
+
+  # Raised when CLIInstaller cannot install the CLI binary.
+  class CLIInstallError < ClaudeSDKError
+  end
+
+  # Raised by the local-disk session APIs when the Claude config directory
+  # cannot be located.
+  class ConfigDirError < ClaudeSDKError
+  end
+
+  # Raised by Client#connect, ClaudeAgentSDK.query and .ask when resuming
+  # from ClaudeAgentOptions#session_store fails (a store call raised or
+  # exceeded load_timeout_ms). #cause holds the adapter's own exception.
+  class SessionStoreError < ClaudeSDKError
+  end
+
+  # Raised when the CLI process fails.
+  class ProcessError < ClaudeSDKError
+    attr_reader exit_code: Integer?
+
+    attr_reader stderr: String?
+
+    def initialize: (String message, ?exit_code: Integer?, ?stderr: String?) -> void
+  end
+
+  # Raised when the CLI exits non-zero after an error result. Every
+  # structured field is type-narrowed (nil unless the payload held the
+  # documented type); #data holds the payload as the CLI sent it.
+  class ResultError < ProcessError
+    attr_reader subtype: String?
+
+    attr_reader errors: Array[String]
+
+    attr_reader result: String?
+
+    attr_reader api_error_status: Integer?
+
+    attr_reader terminal_reason: String?
+
+    attr_reader session_id: String?
+
+    attr_reader data: Hash[Symbol | String, untyped]
+
+    attr_reader original_error: ProcessError?
+
+    # The exception text a `result` payload produces (any payload is
+    # accepted; a non-Hash reads as empty).
+    def self.error_text: (untyped data) -> String
+
+    def initialize: (String message, ?data: untyped, ?exit_code: Integer?, ?stderr: String?, ?original_error: ProcessError?) -> void
+  end
+
+  # Raised when a stdout line from the CLI is not valid JSON.
+  class CLIJSONDecodeError < ClaudeSDKError
+    attr_reader line: String
+
+    attr_reader original_error: Exception
+
+    def initialize: (String line, Exception original_error) -> void
+  end
+
+  # Raised when a CLI message cannot be parsed into a typed message.
+  class MessageParseError < ClaudeSDKError
+    # The offending payload, as received.
+    attr_reader data: untyped
+
+    def initialize: (String message, ?data: untyped) -> void
+  end
+end

data/sig/claude_agent_sdk/observer.rbs

@@ -0,0 +1,42 @@
+module ClaudeAgentSDK
+  # Base module for message observers (ClaudeAgentOptions#observers): include
+  # it and override the callbacks you need; each defaults to a no-op.
+  # Observer errors are rescued and never reach the pipeline.
+  module Observer
+    def on_user_prompt: (String prompt) -> void
+
+    def on_message: (message message) -> void
+
+    def on_error: (StandardError error) -> void
+
+    def on_close: () -> void
+  end
+
+  # Loaded by `require 'claude_agent_sdk/instrumentation'` (needs the
+  # opentelemetry-api gem).
+  module Instrumentation
+    # Emits OpenTelemetry spans (gen_ai.* + OpenInference conventions) for a
+    # session.
+    class OTelObserver
+      include Observer
+
+      TRACER_NAME: String
+
+      MAX_ATTRIBUTE_LENGTH: Integer
+
+      # default_attributes are added to every span. Attribute names usually
+      # contain dots, so they are commonly given as String keys
+      # (`new('user.id' => 'u1')`).
+      def initialize: (?tracer_name: String, **untyped default_attributes) -> void
+                    | (Hash[String | Symbol, untyped] default_attributes) -> void
+
+      def on_user_prompt: (String prompt) -> void
+
+      def on_message: (message message) -> void
+
+      def on_error: (StandardError error) -> void
+
+      def on_close: () -> void
+    end
+  end
+end

data/sig/claude_agent_sdk/railtie.rbs

@@ -0,0 +1,10 @@
+module ClaudeAgentSDK
+  # Rails integration (lib/claude_agent_sdk/railtie.rb), loaded only when
+  # Rails::Railtie is defined. Declared without its Rails::Railtie superclass
+  # so these signatures validate without Rails' own.
+  class Railtie
+    # A callback_wrapper that runs SDK callbacks in the Rails executor,
+    # deadlock-free under development code reloading.
+    def self.callback_wrapper: () -> _CallbackWrapper
+  end
+end

data/sig/claude_agent_sdk/sdk_mcp_server.rbs

@@ -0,0 +1,76 @@
+module ClaudeAgentSDK
+  # What an SDK MCP tool handler returns: a String (sent as one text block),
+  # or a Hash with a :content Array of MCP content blocks plus optional
+  # :is_error / :structured_content.
+  type tool_result = String | Hash[Symbol | String, untyped]
+
+  # An SDK MCP tool handler (the block given to ClaudeAgentSDK.create_tool).
+  # args is the tools/call arguments Hash (wire_hash).
+  interface _ToolHandler
+    def call: (wire_hash args) -> tool_result
+  end
+
+  # An SDK MCP resource reader: returns a Hash with a :contents Array.
+  interface _ResourceReader
+    def call: () -> Hash[Symbol | String, untyped]
+  end
+
+  # An SDK MCP prompt generator: returns a Hash with a :messages Array.
+  interface _PromptGenerator
+    def call: (Hash[Symbol | String, untyped] args) -> Hash[Symbol | String, untyped]
+  end
+
+  # An in-process MCP server (built by ClaudeAgentSDK.create_sdk_mcp_server).
+  # The list_*/call_*/read_*/get_* methods invoke it directly, outside a
+  # session.
+  class SdkMcpServer
+    attr_reader name: String
+
+    attr_reader version: String
+
+    attr_reader tools: Array[SdkMcpTool]
+
+    attr_reader resources: Array[SdkMcpResource]
+
+    attr_reader prompts: Array[SdkMcpPrompt]
+
+    # The underlying server object from the `mcp` gem (MCP::Server); not
+    # typed here so the signatures don't depend on that gem's.
+    attr_reader mcp_server: untyped
+
+    # Where handlers run on DIRECT invocations (a session dispatch uses the
+    # session's own mode). Defaults to :thread.
+    attr_reader callback_scheduling: :thread | :inline
+
+    # Wrapper for DIRECT invocations (a session dispatch uses the session's).
+    attr_reader callback_wrapper: _CallbackWrapper?
+
+    # A String is coerced to a Symbol; anything but :thread / :inline raises
+    # ArgumentError.
+    def callback_scheduling=: (:thread | :inline | "thread" | "inline" value) -> (:thread | :inline | "thread" | "inline")
+
+    # Raises ArgumentError unless value is callable or nil.
+    def callback_wrapper=: (_CallbackWrapper? value) -> _CallbackWrapper?
+
+    def initialize: (name: String, ?version: String, ?tools: Array[SdkMcpTool], ?resources: Array[SdkMcpResource], ?prompts: Array[SdkMcpPrompt]) -> void
+
+    # Tool definitions: { name:, description:, inputSchema:, annotations:?, _meta:? }.
+    def list_tools: () -> Array[Hash[Symbol, untyped]]
+
+    # Runs the tool's handler. Failures come back in-band with isError: true
+    # (a String handler result is wrapped into a text block).
+    def call_tool: (String name, Hash[Symbol | String, untyped] arguments) -> Hash[Symbol | String, untyped]
+
+    def list_resources: () -> Array[Hash[Symbol, untyped]]
+
+    # Raises when the resource does not exist or its reader returns no
+    # :contents.
+    def read_resource: (String uri) -> Hash[Symbol | String, untyped]
+
+    def list_prompts: () -> Array[Hash[Symbol, untyped]]
+
+    # Raises when the prompt does not exist or its generator returns no
+    # :messages.
+    def get_prompt: (String name, ?Hash[Symbol | String, untyped] arguments) -> Hash[Symbol | String, untyped]
+  end
+end