claude-agent-sdk 0.37.0 → 1.1.0

data/lib/claude_agent_sdk/types/attributes.rb

@@ -1,20 +1,12 @@
 # frozen_string_literal: true
 
-require_relative '../deprecation'
-
 module ClaudeAgentSDK
   # Attribute declarations and the rules #[], #[]=, .new and the camelCase
   # readers follow (issue #126). Loaded by base.rb right after Type itself,
   # before any subclass declares an attribute.
   class Type
-    # The 1.0 switch for attribute access, false through 0.x. When true:
-    # an unknown key on a strict type (see .strict_attributes) raises
-    # ArgumentError, and #[], #[]= and the camelCase readers reach declared
-    # attributes only. While false, both cases warn once per class and name.
-    ENFORCE_ATTRIBUTES = false
-
     LENIENT_KEY = :__claude_agent_sdk_lenient_attributes
-    private_constant :ENFORCE_ATTRIBUTES, :LENIENT_KEY
+    private_constant :LENIENT_KEY
 
     class << self
       # attr_accessor / attr_reader / attr_writer also declare the names as
@@ -108,9 +100,9 @@ module ClaudeAgentSDK
 
     # Declares a type the user constructs and passes IN (option values, hook
     # matchers and outputs, permission results and updates). Constructing
-    # one directly (.new or #[]=) with a key that is not an attribute warns
-    # once per class and key — a typo would otherwise be dropped silently —
-    # and raises ArgumentError from 1.0. A read-only attribute (the +type+,
+    # one directly (.new or #[]=) with a key that is not an attribute raises
+    # ArgumentError — a typo would otherwise be dropped silently (0.37 warned
+    # here; 1.0 raises). A read-only attribute (the +type+,
     # +hook_event_name+ or +behavior+ discriminator a type sets itself, which
     # its own #to_h emits) is accepted and ignored. Types the SDK parses from
     # CLI output stay lenient so a newer CLI's extra fields never break an
@@ -151,15 +143,14 @@ module ClaudeAgentSDK
           self.class.cache_attribute_reader(method_name, normalized.to_sym)
           return public_send(normalized, ...)
         end
-        return public_send(normalized, ...) if reachable?(normalized, method_name, :camel_case)
+        return public_send(normalized, ...) if user_defined_method?(normalized)
       end
       super
     end
 
     def respond_to_missing?(method_name, include_private = false)
       normalized = normalize_name(method_name)
-      (normalized != method_name.to_s && respond_to?(normalized) &&
-        (!ENFORCE_ATTRIBUTES || attribute_method?(normalized))) || super
+      (normalized != method_name.to_s && respond_to?(normalized) && attribute_method?(normalized)) || super
     end
 
     def assign_attributes(attributes)
@@ -184,12 +175,12 @@ module ClaudeAgentSDK
           self.class.cache_attribute_writer(name, setter)
           return public_send(setter, value)
         end
-        return public_send(setter, value) if reachable?(setter.to_s, name, :write)
+        return public_send(setter, value) if user_defined_method?(setter.to_s)
       end
       return unless self.class.strict_attributes? && !Thread.current[LENIENT_KEY] && !self.class.attribute?(normalized)
       return if respond_to?(normalized) && user_defined_method?(normalized)
 
-      unknown_attribute(name, normalized)
+      unknown_attribute(name)
     end
 
     def read_attribute(name)
@@ -202,7 +193,7 @@ module ClaudeAgentSDK
       if self.class.attribute_method?(getter)
         self.class.cache_attribute_reader(name, getter.to_sym)
         public_send(getter)
-      elsif reachable?(getter, name, :read)
+      elsif user_defined_method?(getter)
         public_send(getter)
       end
     end
@@ -234,38 +225,12 @@ module ClaudeAgentSDK
       !name.nil? && (name == 'ClaudeAgentSDK' || name.start_with?('ClaudeAgentSDK::'))
     end
 
-    # #[], #[]= (and so .new) or a camelCase call resolved to +method_name+, a
-    # public method. An attribute passes. Any other method (to_h, freeze, ...)
-    # passes with a warning once per class and name through 0.x, and is
-    # treated as undefined from 1.0.
-    def reachable?(method_name, name, access)
-      return true if attribute_method?(method_name)
-      return false if ENFORCE_ATTRIBUTES
-
-      class_name = self.class.name || self.class.inspect
-      message = case access
-                when :read then "#{class_name}#[]: #{name.inspect} is not an attribute; " \
-                                'Type#[] will only read attributes in 1.0'
-                when :write then "#{class_name}#[]=: #{name.inspect} is not an attribute; " \
-                                 'Type#[]= and .new will only write attributes in 1.0'
-                else "#{class_name}##{name}: #{method_name} is not an attribute; " \
-                     'camelCase methods will only reach attributes in 1.0'
-                end
-      Deprecation.warn_once_at_caller([:non_attribute, self.class, method_name], message)
-      true
-    end
-
-    def unknown_attribute(name, normalized)
+    # A key that is not an attribute, on a strict type: a typo the user
+    # would otherwise never see.
+    def unknown_attribute(name)
       klass = self.class
-      class_name = klass.name || klass.inspect
-      known = klass.attribute_names.join(', ')
-      raise ArgumentError, "#{class_name}: unknown attribute #{name.inspect} (known: #{known})" if ENFORCE_ATTRIBUTES
-
-      Deprecation.warn_once_at_caller(
-        [:unknown_attribute, klass, normalized],
-        "#{class_name}: unknown attribute #{name.inspect} ignored; " \
-        "this will raise ArgumentError in 1.0 (known: #{known})"
-      )
+      raise ArgumentError, "#{klass.name || klass.inspect}: unknown attribute #{name.inspect} " \
+                           "(known: #{klass.attribute_names.join(', ')})"
     end
   end
 end

data/lib/claude_agent_sdk/types/base.rb

@@ -158,6 +158,8 @@ module ClaudeAgentSDK
     # `seen` holds the Types/containers on the current rendering path (not
     # every one rendered so far), so a shared-but-acyclic value still renders
     # in full wherever it appears.
+    #
+    # @api private
     def inspect_with(depth, seen)
       return "#<#{inspect_class_name} …>" if depth > INSPECT_MAX_DEPTH || seen.key?(self)
 

data/lib/claude_agent_sdk/types/messages.rb

@@ -192,7 +192,13 @@ module ClaudeAgentSDK
                   :outcome # "success", "error", or "cancelled"
   end
 
-  # Session state changed system message
+  # Session state changed system message.
+  #
+  # Reaches your code only when you opt in with
+  # `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1` in ClaudeAgentOptions#env. The
+  # SDK also asks the CLI for these frames on its own behalf (to tell when a
+  # query() run is over), but those arrive marked `sdk_host_only` and are
+  # dropped before the message stream.
   class SessionStateChangedMessage < SystemMessage
     attr_accessor :uuid, :session_id,
                   :state # "idle", "running", or "requires_action"

data/lib/claude_agent_sdk/types/options.rb

@@ -81,21 +81,11 @@ module ClaudeAgentSDK
       self.include_hook_events = false
       self.strict_mcp_config = false
       self.forward_subagent_text = false
+      self.verbatim_prompts = false
 
       super(merge_with_defaults(attributes || {}))
 
-      # Non-nil defaults for options that need them.
-      self.env                 ||= {}
-      self.extra_args          ||= {}
-      self.mcp_servers         ||= {}
-      self.add_dirs            ||= []
-      self.observers           ||= []
-      self.allowed_tools       ||= []
-      self.disallowed_tools    ||= []
-      self.session_store_flush ||= 'batched'
-      # 0 is a valid (immediate) timeout, so only fill in the default for nil.
-      self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
-      self.callback_scheduling = :thread if callback_scheduling.nil?
+      fill_nil_defaults
     end
 
     def dup_with(**changes)
@@ -203,6 +193,58 @@ module ClaudeAgentSDK
       @forward_subagent_text = coerce_boolean(value)
     end
 
+    # Deliver every prompt to Claude as written.
+    #
+    # When true, every user message the SDK sends is marked `client_composed`:
+    # a String prompt to {ClaudeAgentSDK.query}, {Client#connect} or
+    # {Client#query}, and every message of a streamed (Enumerable) prompt to
+    # any of them. Claude Code then delivers the text exactly as given: no
+    # `@path` file-mention expansion and no slash-command dispatch. Use it when
+    # the prompt is assembled from content your end user did not type (earlier
+    # turns, tool output, third-party text), so an `@/absolute/path` inside it
+    # cannot make Claude Code read a local file. `tools: []`, `allowed_tools`
+    # and `disallowed_tools` do not stop that expansion: it happens before the
+    # model runs, without a tool call.
+    #
+    # While the option is on there is no per-message opt-out: a
+    # `client_composed` key on a streamed message Hash (either spelling) is
+    # overwritten. For per-turn control, leave the option off and set
+    # `client_composed: true` on individual streamed messages. The caller's
+    # Hashes are never mutated. A streamed JSONL String is parsed, marked and
+    # re-serialized; one that is not a single JSON object raises
+    # `ArgumentError` rather than being sent unmarked (on the background
+    # streaming paths that ends the stream with a warning, like any other
+    # stream error).
+    #
+    # On current Claude Code versions a turn delivered this way also skips the
+    # turn-start attachment pass as a whole: `@server:resource` MCP mentions
+    # are not expanded either, and the prompt goes without the context Claude
+    # Code normally attaches (nested `CLAUDE.md` and rules files, skill and
+    # tool listings, other per-turn reminders). The pass between tool calls is
+    # unaffected, so most of that context arrives after the turn's first tool
+    # call instead.
+    #
+    # Requires Claude Code 2.1.248 or later; older versions ignore the field,
+    # so prompts are still expanded there, and the SDK warns when it connects
+    # to one with this option on. Read once when the session starts. Not a
+    # CLI flag. Matches the Python SDK's `verbatim_prompts`.
+    #
+    # Assigning coerces to a Boolean; {#verbatim_prompts?} is the predicate
+    # form.
+    #
+    # @return [Boolean]
+    attr_reader :verbatim_prompts
+
+    # @return [Boolean] {#verbatim_prompts}, as a strict Boolean.
+    def verbatim_prompts?
+      !!verbatim_prompts
+    end
+
+    # @see #verbatim_prompts
+    def verbatim_prompts=(value)
+      @verbatim_prompts = coerce_boolean(value)
+    end
+
     # Request model-generated progress summaries for subagent (`local_agent`)
     # tasks. `true` *requests* generation: while the CLI has it enabled, a
     # subagent's {TaskProgressMessage#summary} **may** carry a one-line status.
@@ -288,6 +330,21 @@ module ClaudeAgentSDK
 
     private
 
+    # Non-nil defaults for options that need them.
+    def fill_nil_defaults
+      self.env                 ||= {}
+      self.extra_args          ||= {}
+      self.mcp_servers         ||= {}
+      self.add_dirs            ||= []
+      self.observers           ||= []
+      self.allowed_tools       ||= []
+      self.disallowed_tools    ||= []
+      self.session_store_flush ||= 'batched'
+      # 0 is a valid (immediate) timeout, so only fill in the default for nil.
+      self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
+      self.callback_scheduling = :thread if callback_scheduling.nil?
+    end
+
     # Strict key validation: unlike other Type subclasses (which silently drop
     # unknown keys for forward-compat with newer CLI output), ClaudeAgentOptions
     # is a developer-facing config object — typos should fail loudly.

data/lib/claude_agent_sdk/version.rb

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

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, ...)')
@@ -749,7 +749,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
           forward_subagent_text: configured_options.forward_subagent_text?,
           agent_progress_summaries: configured_options.agent_progress_summaries,
           callback_scheduling: callback_scheduling,
-          callback_wrapper: callback_wrapper
+          callback_wrapper: callback_wrapper,
+          verbatim_prompts: configured_options.verbatim_prompts?,
+          run_end_ceiling_ms: Query.run_end_ceiling_ms(configured_options.env)
         )
 
         # Mirror transcripts to the session_store, if configured. Installed
@@ -782,7 +784,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             parent_tool_use_id: nil,
             session_id: ''
           }
-          transport.write("#{JSON.generate(message)}\n")
+          transport.write("#{Query.serialize_user_message(message, configured_options.verbatim_prompts?)}\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
@@ -1084,7 +1086,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             parent_tool_use_id: nil,
             session_id: session_id
           }
-          writeln(JSON.generate(message))
+          writeln(Query.serialize_user_message(message, @verbatim_prompts))
         elsif prompt.respond_to?(:each)
           # Inline iteration on the caller, Python client.py parity — NOT
           # Query#stream_input, whose ensure always ends input after
@@ -1394,6 +1396,10 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
       exclude_dynamic_sections = ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt)
       system_prompt_snapshot = ClaudeAgentSDK.extract_system_prompt_snapshot(configured_options.system_prompt)
 
+      # Captured once, so String and streamed prompts in one session are
+      # stamped alike (the Query stamps the streamed ones with this value).
+      @verbatim_prompts = configured_options.verbatim_prompts?
+
       # Create Query handler
       @query_handler = Query.new(
         transport: @transport,
@@ -1408,7 +1414,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
         forward_subagent_text: configured_options.forward_subagent_text?,
         agent_progress_summaries: configured_options.agent_progress_summaries,
         callback_scheduling: @callback_scheduling,
-        callback_wrapper: @callback_wrapper
+        callback_wrapper: @callback_wrapper,
+        verbatim_prompts: @verbatim_prompts,
+        run_end_ceiling_ms: Query.run_end_ceiling_ms(configured_options.env)
       )
 
       # Mirror transcripts to the session_store, if configured.
@@ -1450,7 +1458,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
     # key styles — an explicit nil is preserved, mirroring Python's
     # `"session_id" not in msg`). Strings pass through verbatim (Ruby
     # superset: Streaming.user_message emits pre-serialized JSONL; no
-    # parse-stamp-regenerate, which would block the reactor on huge frames).
+    # parse-stamp-regenerate, which would block the reactor on huge frames),
+    # except that verbatim_prompts must mark them `client_composed`, so with
+    # that option on they are parsed and re-serialized (Query.stamp_user_message).
     def stream_query_messages(prompt, session_id)
       prompt.each do |msg|
         case msg
@@ -1460,13 +1470,13 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
                                             scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
-          writeln(JSON.generate(msg))
+          writeln(Query.serialize_user_message(msg, @verbatim_prompts))
         when String
           if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
             ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
                                             scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
-          writeln(msg)
+          writeln(Query.serialize_user_message(msg, @verbatim_prompts))
         else
           # No to_s fallback — silently serializing arbitrary objects is the
           # exact inspect-garbage bug class this method exists to prevent.

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