claude-agent-sdk 0.37.0 → 1.0.0

data/lib/claude_agent_sdk.rb

@@ -541,27 +541,27 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
     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, ...)')
@@ -569,14 +569,14 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
                                              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, ...)')
@@ -584,7 +584,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
                                               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)
@@ -593,28 +593,28 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
                                               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, ...)')

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

data/sig/claude_agent_sdk/session_store.rbs

@@ -0,0 +1,105 @@
+module ClaudeAgentSDK
+  # Values of ClaudeAgentOptions#session_store_flush.
+  SESSION_STORE_FLUSH_MODES: Array[String]
+
+  # A SessionStore key. String keys: 'project_key' and 'session_id' always;
+  # 'subpath' (e.g. "subagents/agent-<id>") only for a subagent transcript.
+  type session_key = Hash[String, String?]
+
+  # A session summary as built by ClaudeAgentSDK.fold_session_summary:
+  # { 'session_id' => String, 'mtime' => Integer, 'data' => Hash[String, untyped] }.
+  type session_summary = Hash[String, untyped]
+
+  # The duck type ClaudeAgentOptions#session_store and the session functions'
+  # session_store: accept. Only #append and #load are required; an adapter
+  # need not subclass SessionStore. Keys and entries cross this boundary as
+  # String-keyed Hashes (docs/types.md#hash-keys).
+  #
+  # The SDK also probes (SessionStore.implements?) for these OPTIONAL methods
+  # and uses them when present — they cannot be expressed as optional
+  # interface members, so they are listed here:
+  #
+  #   def list_sessions: (String project_key) -> Array[{ 'session_id' => String, 'mtime' => Integer }]
+  #   def list_session_summaries: (String project_key) -> Array[session_summary]
+  #   def delete: (session_key key) -> void        # a main key cascades to its subkeys
+  #   def list_subkeys: (session_key key) -> Array[String]
+  #   def callback_scheduling: () -> (:thread | :inline)   # :inline = fiber-native adapter
+  #
+  # ClaudeAgentSDK::Testing.run_session_store_conformance checks an adapter
+  # against the behavioral contracts.
+  interface _SessionStore
+    # Mirrors a batch of transcript entries. Must be thread-safe per key and
+    # should dedupe by entry['uuid'].
+    def append: (session_key key, Array[transcript_hash] entries) -> void
+
+    # The full transcript for key, or nil when it was never written.
+    def load: (session_key key) -> Array[transcript_hash]?
+  end
+
+  # Optional base class for adapters. Its methods raise NotImplementedError,
+  # which marks an optional method as absent (see .implements?).
+  class SessionStore
+    # True when store overrides method rather than inheriting the
+    # NotImplementedError default (works for duck-typed adapters too).
+    def self.implements?: (untyped store, Symbol | String method) -> bool
+
+    def append: (session_key key, Array[transcript_hash] entries) -> void
+
+    def load: (session_key key) -> Array[transcript_hash]?
+
+    def list_sessions: (String project_key) -> Array[Hash[String, String | Integer]]
+
+    def list_session_summaries: (String project_key) -> Array[session_summary]
+
+    def delete: (session_key key) -> void
+
+    def list_subkeys: (session_key key) -> Array[String]
+  end
+
+  # In-memory SessionStore for tests and development; data is lost on exit.
+  # Implements every optional method.
+  class InMemorySessionStore < SessionStore
+    def initialize: () -> void
+
+    def append: (session_key key, Array[transcript_hash]? entries) -> void
+
+    def load: (session_key key) -> Array[transcript_hash]?
+
+    def list_sessions: (String project_key) -> Array[Hash[String, String | Integer]]
+
+    def list_session_summaries: (String project_key) -> Array[session_summary]
+
+    def delete: (session_key key) -> void
+
+    def list_subkeys: (session_key key) -> Array[String]
+
+    # Test helper: all entries for key ([] when absent).
+    def get_entries: (session_key key) -> Array[transcript_hash]
+
+    # Test helper: number of stored main transcripts.
+    def size: () -> Integer
+
+    # Test helper: removes everything.
+    def clear: () -> void
+  end
+
+  # Test helpers shipped for third-party SessionStore adapter authors.
+  module Testing
+    # Raised by run_session_store_conformance on the first violated contract.
+    class ConformanceError < StandardError
+    end
+
+    # The optional SessionStore methods skip_optional: accepts.
+    OPTIONAL_METHODS: Array[String]
+
+    # Asserts the SessionStore behavioral contracts against a fresh store
+    # from make_store (called once per contract). Raises ConformanceError on
+    # a violation; returns nil otherwise.
+    def self.run_session_store_conformance: (_StoreFactory make_store, ?skip_optional: Array[String | Symbol], ?check_uuid_dedupe: bool) -> nil
+
+    # Returns a fresh store per call.
+    interface _StoreFactory
+      def call: () -> _SessionStore
+    end
+  end
+end

data/sig/claude_agent_sdk/streaming.rbs

@@ -0,0 +1,15 @@
+module ClaudeAgentSDK
+  # Builders for streaming input: a prompt that is an Enumerator of JSONL
+  # user messages.
+  module Streaming
+    # One JSON-encoded user message, newline-terminated. content is a String
+    # or an Array of content-block Hashes.
+    def self.user_message: (String | Array[Hash[Symbol | String, untyped]] content, ?session_id: String, ?parent_tool_use_id: String?) -> String
+
+    def self.from_array: (_Each[String | Array[Hash[Symbol | String, untyped]]] messages, ?session_id: String) -> Enumerator[String, void]
+
+    # The block receives an Enumerator::Yielder; each value it yields becomes
+    # one user message.
+    def self.from_block: (?session_id: String) { (Enumerator::Yielder yielder) -> void } -> Enumerator[String, void]
+  end
+end

data/sig/claude_agent_sdk/transport.rbs

@@ -0,0 +1,98 @@
+module ClaudeAgentSDK
+  # What `query(transport:)` and Client need from a transport. A custom
+  # transport may subclass Transport or be any object with these methods.
+  # read_messages must yield each stdout line parsed with
+  # `JSON.parse(line, symbolize_names: true)` (see docs/types.md#hash-keys).
+  # #close must be idempotent. (Transport#ready? is part of the abstract
+  # class but the SDK never calls it, so it is not required here.)
+  interface _Transport
+    def connect: () -> void
+
+    def write: (String data) -> void
+
+    def read_messages: () { (wire_hash message) -> void } -> void
+
+    def close: () -> void
+
+    def end_input: () -> void
+  end
+
+  # Client's transport_class: Client calls
+  # `transport_class.new(options, **transport_args)`.
+  interface _TransportClass
+    def new: (ClaudeAgentOptions options, **untyped transport_args) -> _Transport
+  end
+
+  # Abstract base for custom transports: every method raises
+  # NotImplementedError until overridden.
+  class Transport
+    def connect: () -> void
+
+    def write: (String data) -> void
+
+    def read_messages: () { (wire_hash message) -> void } -> void
+                     | () -> Enumerator[wire_hash, void]
+
+    def close: () -> void
+
+    def ready?: () -> bool
+
+    def end_input: () -> void
+  end
+
+  # The default transport: spawns the `claude` CLI and speaks stream-JSON
+  # over its stdin/stdout.
+  class SubprocessCLITransport < Transport
+    # The legacy two-argument form `new(prompt, options)` ignores prompt.
+    def initialize: (ClaudeAgentOptions options) -> void
+                  | (untyped prompt, ClaudeAgentOptions options) -> void
+
+    def connect: () -> void
+
+    def write: (String data) -> void
+
+    def read_messages: () { (wire_hash message) -> void } -> void
+                     | () -> Enumerator[wire_hash, void]
+
+    def close: () -> void
+
+    def ready?: () -> bool
+
+    def end_input: () -> void
+  end
+
+  # Builds the CLI argv SubprocessCLITransport would spawn (for custom
+  # transports that run the CLI elsewhere; see docs/client.md).
+  class CommandBuilder
+    def initialize: (String cli_path, ClaudeAgentOptions options) -> void
+
+    def build: () -> Array[String]
+  end
+
+  # Downloads a pinned Claude Code CLI into vendor/claude (Docker/CI deploys).
+  # Every failure raises CLIInstallError.
+  module CLIInstaller
+    # The CLI version this gem release is tested against.
+    PINNED_CLI_VERSION: String
+
+    # The directory vendor/claude resolves against (nil: the cwd at call
+    # time). An absolute, frozen path once set.
+    def self.root: () -> String?
+
+    def self.root=: ((String | Pathname)? path) -> (String | Pathname)?
+
+    # Absolute path of the default install directory.
+    def self.default_dir: () -> String
+
+    # Installs the CLI ('stable', 'latest' or a concrete version) and returns
+    # the absolute path of the binary. Idempotent and safe to run
+    # concurrently.
+    def self.install: (?version: String, ?dir: (String | Pathname)?) -> String
+
+    # Installs PINNED_CLI_VERSION.
+    def self.install_pinned: (?dir: (String | Pathname)?) -> String
+
+    # Path of an already-installed binary, or nil.
+    def self.installed_path: (?dir: (String | Pathname)?) -> String?
+  end
+end

data/sig/claude_agent_sdk/types/base.rbs

@@ -0,0 +1,39 @@
+module ClaudeAgentSDK
+  # Base class of the SDK's value types (messages, content blocks, hook
+  # inputs/outputs, option values).
+  #
+  # Attribute names are accepted in several spellings — Symbol or String,
+  # snake_case or camelCase — by .new, #[] and #[]=, which reach attributes
+  # only. The camelCase readers (`msg.sessionId`) are public API too but are
+  # resolved dynamically (method_missing), so they have no static signature
+  # here: prefer the snake_case readers, or #[], in typed code.
+  class Type
+    # Returns object unchanged when it already is an instance, nil for nil,
+    # and otherwise builds one (leniently: unknown keys never raise).
+    def self.wrap: (untyped object) -> instance?
+
+    # Builds an instance from a Hash (leniently); nil for anything else.
+    def self.from_hash: (untyped hash) -> instance?
+
+    # attributes: a Hash of attribute name => value (the keyword form
+    # `Klass.new(name: value)` passes the same Hash). On a user-constructed
+    # (strict) type an unknown key raises ArgumentError; types parsed from
+    # CLI output ignore it.
+    def initialize: (?Hash[Symbol | String, untyped]? attributes) -> void
+
+    # Reads an attribute; nil for a name that is not an attribute.
+    def []: (Symbol | String name) -> untyped
+
+    # Writes an attribute through its setter; returns value. A name that is
+    # not an attribute is ignored, or raises ArgumentError on a strict type.
+    def []=: (Symbol | String name, untyped value) -> untyped
+
+    # The wire (CLI) form; types that are sent to the CLI override this.
+    def to_h: () -> Hash[Symbol, untyped]
+
+    # Bounded, credential-filtered, human-oriented rendering.
+    def inspect: () -> String
+
+    def to_s: () -> String
+  end
+end

data/sig/claude_agent_sdk/types/content_blocks.rbs

@@ -0,0 +1,79 @@
+module ClaudeAgentSDK
+  # A raw Hash inside a content block: Symbol keys on live messages, String
+  # keys on blocks parsed from a transcript (SessionMessage#content_blocks).
+  type block_hash = wire_hash | transcript_hash
+
+  # A content block of a UserMessage / AssistantMessage / SessionMessage.
+  type content_block = TextBlock
+                     | ThinkingBlock
+                     | ToolUseBlock
+                     | ToolResultBlock
+                     | ServerToolUseBlock
+                     | ServerToolResultBlock
+                     | UnknownBlock
+
+  class TextBlock < Type
+    attr_accessor text: String?
+
+    def to_s: () -> String
+  end
+
+  class ThinkingBlock < Type
+    attr_accessor thinking: String?
+
+    attr_accessor signature: String?
+  end
+
+  class ToolUseBlock < Type
+    attr_accessor id: String?
+
+    attr_accessor name: String?
+
+    attr_accessor input: block_hash?
+  end
+
+  class ToolResultBlock < Type
+    attr_accessor tool_use_id: String?
+
+    # A String, or an Array of content-block Hashes.
+    attr_accessor content: (String | Array[block_hash])?
+
+    attr_accessor is_error: bool?
+  end
+
+  # A server-side tool call (advisor, web_search, code_execution, ...).
+  class ServerToolUseBlock < Type
+    attr_accessor id: String?
+
+    attr_accessor name: String?
+
+    attr_accessor input: block_hash?
+  end
+
+  # The result of a server-side tool call. content is passed through from
+  # the API as-is and its shape depends on the tool.
+  class ServerToolResultBlock < Type
+    attr_accessor tool_use_id: String?
+
+    attr_accessor content: untyped
+
+    attr_accessor is_error: bool?
+  end
+
+  # A block type this SDK version does not model ("document", "image", ...):
+  # type is the original block type, data the raw block.
+  class UnknownBlock < Type
+    attr_accessor type: String?
+
+    attr_accessor data: block_hash?
+  end
+
+  # A tool call a PreToolUse hook deferred (ResultMessage#deferred_tool_use).
+  class DeferredToolUse < Type
+    attr_accessor id: String?
+
+    attr_accessor name: String?
+
+    attr_accessor input: block_hash?
+  end
+end