claude-agent-sdk 0.35.0 → 0.37.0

data/lib/claude_agent_sdk.rb

@@ -20,6 +20,7 @@ require_relative 'claude_agent_sdk/session_resume'
 require_relative 'claude_agent_sdk/session_mutations'
 require_relative 'claude_agent_sdk/fiber_boundary'
 require_relative 'claude_agent_sdk/option_warnings'
+require_relative 'claude_agent_sdk/deprecation'
 # Rails apps only: Bundler.require runs after `require 'rails'`, so the
 # Railtie (rake tasks; the generator lives under lib/generators) is picked up
 # there and nowhere else.
@@ -28,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
@@ -40,6 +43,7 @@ module ClaudeAgentSDK
   # skipped — most commonly a Class passed instead of an instance, which
   # previously produced silent zero instrumentation (every notify raised
   # NoMethodError, swallowed by notify_observers' error containment).
+  # @api private
   def self.resolve_observers(observers)
     Array(observers).filter_map do |obs|
       resolved = obs.respond_to?(:call) ? obs.call : obs
@@ -60,6 +64,7 @@ module ClaudeAgentSDK
   # configs may use String or Symbol keys (and a Symbol :sdk type) — the
   # recognition rule must match CommandBuilder#append_mcp_servers, which
   # strips the instance from exactly these entries.
+  # @api private
   def self.extract_sdk_mcp_servers(mcp_servers)
     return {} unless mcp_servers.is_a?(Hash)
 
@@ -75,6 +80,7 @@ module ClaudeAgentSDK
 
   # Internal: normalize hook lists for the control protocol. An absent or
   # disabled event must not become an empty registration in initialize.
+  # @api private
   def self.convert_hooks_to_internal_format(hooks)
     return nil unless hooks
 
@@ -108,11 +114,14 @@ module ClaudeAgentSDK
   # guarantees for can_use_tool — the permission round-trip works. The old
   # "requires streaming mode" ArgumentError was a needless restriction
   # (Python #1204).
+  # @api private
   def self.configure_can_use_tool(options)
     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.
@@ -124,6 +133,7 @@ module ClaudeAgentSDK
   # Internal: pull exclude_dynamic_sections out of a preset system prompt for
   # the initialize request (older CLIs ignore unknown initialize fields).
   # Shared by Client#connect and the one-shot query() path.
+  # @api private
   def self.extract_exclude_dynamic_sections(system_prompt)
     if system_prompt.is_a?(SystemPromptPreset)
       eds = system_prompt.exclude_dynamic_sections
@@ -143,6 +153,7 @@ module ClaudeAgentSDK
   # String or file prompt has no snapshot, and only a genuine true/false is
   # forwarded — `snapshot: false` is the primary use case, so the Hash lookup
   # must not collapse it to nil. Shared by Client#connect and query().
+  # @api private
   def self.extract_system_prompt_snapshot(system_prompt)
     case system_prompt
     when SystemPromptPreset, SystemPromptCustom
@@ -162,6 +173,7 @@ module ClaudeAgentSDK
   # Each observer is invoked through FiberBoundary so that user code runs
   # on a plain thread (no Fiber scheduler) even when called from inside
   # the SDK's Async reactor — or in place when scheduling is :inline.
+  # @api private
   def self.notify_observers(observers, method, *args, scheduling: :thread, wrapper: nil)
     observers.each do |obs|
       FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) { obs.send(method, *args) }
@@ -188,8 +200,8 @@ module ClaudeAgentSDK
   #
   # @example Inside an inline-mode tool handler
   #   ClaudeAgentSDK.offload { blocking_db_call }
-  def self.offload(&block)
-    FiberBoundary.invoke(&block)
+  def self.offload(&)
+    FiberBoundary.invoke(&)
   end
 
   # Guards the once-per-process flag below: two sessions connecting
@@ -202,6 +214,7 @@ module ClaudeAgentSDK
   # almost certainly violates inline mode's fiber-isolation precondition
   # (solid_queue fiber workers require isolation_level = :fiber).
   # defined? probing only; the SDK never loads ActiveSupport itself.
+  # @api private
   def self.check_inline_isolation(scheduling)
     return unless scheduling == :inline
     return unless defined?(ActiveSupport::IsolatedExecutionState)
@@ -224,6 +237,7 @@ module ClaudeAgentSDK
   # when there is none (non-user messages, tool_result-only content, …).
   # Only Hash and JSON-string items are inspected; arbitrary objects written
   # via to_s are never notified.
+  # @api private
   def self.extract_user_prompt_text(message)
     data = case message
            when Hash then message
@@ -254,6 +268,7 @@ module ClaudeAgentSDK
   # when there is no extractable text — on_user_prompt('') would latch
   # OTelObserver's first-prompt buffer while never setting the attribute,
   # permanently suppressing later real prompts.
+  # @api private
   def self.prompt_text_from_content(content)
     case content
     when String
@@ -273,6 +288,7 @@ module ClaudeAgentSDK
   # Wrap a streaming-input enumerable so observers get on_user_prompt for
   # each user message before it is written to stdin. Identity when no
   # observers are configured.
+  # @api private
   def self.observing_prompt_stream(prompt, observers, scheduling: :thread, wrapper: nil)
     return prompt if observers.empty?
 
@@ -287,6 +303,7 @@ module ClaudeAgentSDK
 
   # Look up a value in a hash that may use symbol or string keys in camelCase or snake_case.
   # Returns the first non-nil value found, preserving false as a meaningful value.
+  # @api private
   def self.flexible_fetch(hash, camel_key, snake_key)
     val = hash[camel_key.to_sym]
     val = hash[camel_key.to_s] if val.nil?
@@ -295,93 +312,211 @@ module ClaudeAgentSDK
     val
   end
 
-  # List sessions for a directory (or all sessions)
-  # @param directory [String, nil] Working directory to list sessions for
+  # ---- Session browsing & mutation ----
+  #
+  # One function per operation. By default each reads or writes the local-disk
+  # transcripts under CLAUDE_CONFIG_DIR; pass +session_store:+ to operate on a
+  # SessionStore instead. The two paths differ in a few documented ways:
+  #
+  # - +directory: nil+ searches every project directory on disk, but means the
+  #   current working directory with a store (a SessionStore is keyed by
+  #   project_key and cannot enumerate projects — parity with the Python SDK).
+  # - +include_worktrees:+ filters only on disk (list_sessions); with a
+  #   +session_store:+, anything but the default +true+ raises ArgumentError.
+
+  # List sessions for a directory (or all sessions), newest first.
+  # @param directory [String, nil] Working directory to list sessions for. On
+  #   disk, nil lists every project; with a session_store, nil means the
+  #   current working directory.
   # @param limit [Integer, nil] Maximum number of sessions to return
   # @param offset [Integer] Number of sessions to skip (for pagination)
-  # @param include_worktrees [Boolean] Whether to include git worktree sessions
+  # @param include_worktrees [Boolean] Disk only: also list the project's git
+  #   worktree sessions. A store has no worktrees, so with a session_store only
+  #   the default true is accepted; false or nil raises ArgumentError (the
+  #   store path cannot apply the filter the caller asked for).
+  # @param session_store [SessionStore, nil] List from this store instead of
+  #   local disk. Uses the store's list_session_summaries when implemented,
+  #   else list_sessions + one load per listed session.
   # @return [Array<SDKSessionInfo>] Sessions sorted by last_modified descending
-  def self.list_sessions(directory: nil, limit: nil, offset: 0, include_worktrees: true)
+  # @raise [ArgumentError] if include_worktrees is not true with a session_store,
+  #   or the store implements neither list_session_summaries nor list_sessions
+  def self.list_sessions(directory: nil, limit: nil, offset: 0, include_worktrees: true, session_store: nil)
+    unless session_store.nil?
+      unless include_worktrees == true
+        raise ArgumentError, "include_worktrees: #{include_worktrees.inspect} applies only to local-disk " \
+                             'listing; a session_store is keyed by project and has no worktrees to exclude'
+      end
+
+      return Sessions.list_sessions_from_store(session_store: session_store, directory: directory,
+                                               limit: limit, offset: offset)
+    end
+
     Sessions.list_sessions(directory: directory, limit: limit, offset: offset, include_worktrees: include_worktrees)
   end
 
   # Read metadata for a single session by ID (no full directory scan)
   # @param session_id [String] UUID of the session to look up
-  # @param directory [String, nil] Project directory path
-  # @return [SDKSessionInfo, nil] Session info, or nil if not found
-  def self.get_session_info(session_id:, directory: nil)
+  # @param directory [String, nil] Project directory path. On disk, nil
+  #   searches every project; with a session_store, nil means the current
+  #   working directory.
+  # @param session_store [SessionStore, nil] Read from this store instead of local disk
+  # @return [SDKSessionInfo, nil] Session info, or nil if not found / sidechain / no summary
+  def self.get_session_info(session_id:, directory: nil, session_store: nil)
+    unless session_store.nil?
+      return Sessions.get_session_info_from_store(session_store: session_store, session_id: session_id,
+                                                  directory: directory)
+    end
+
     Sessions.get_session_info(session_id: session_id, directory: directory)
   end
 
   # Get messages from a session transcript
   # @param session_id [String] The session UUID
-  # @param directory [String, nil] Working directory to search in
+  # @param directory [String, nil] Working directory to search in. On disk,
+  #   nil searches every project; with a session_store, nil means the current
+  #   working directory.
   # @param limit [Integer, nil] Maximum number of messages
   # @param offset [Integer] Number of messages to skip
+  # @param session_store [SessionStore, nil] Read from this store instead of local disk
   # @return [Array<SessionMessage>] Ordered messages from the session
-  def self.get_session_messages(session_id:, directory: nil, limit: nil, offset: 0)
+  def self.get_session_messages(session_id:, directory: nil, limit: nil, offset: 0, session_store: nil)
+    unless session_store.nil?
+      return Sessions.get_session_messages_from_store(session_store: session_store, session_id: session_id,
+                                                      directory: directory, limit: limit, offset: offset)
+    end
+
     Sessions.get_session_messages(session_id: session_id, directory: directory, limit: limit, offset: offset)
   end
 
-  # List subagent IDs recorded for a session on local disk
+  # List subagent IDs recorded for a session
   # @param session_id [String] The session UUID
-  # @param directory [String, nil] Working directory to search in
+  # @param directory [String, nil] Working directory to search in. On disk,
+  #   nil searches every project; with a session_store, nil means the current
+  #   working directory.
+  # @param session_store [SessionStore, nil] Read from this store instead of
+  #   local disk (the store must implement list_subkeys)
   # @return [Array<String>] Subagent IDs
-  def self.list_subagents(session_id:, directory: nil)
+  # @raise [ArgumentError] if the session_store does not implement list_subkeys
+  def self.list_subagents(session_id:, directory: nil, session_store: nil)
+    unless session_store.nil?
+      return Sessions.list_subagents_from_store(session_store: session_store, session_id: session_id,
+                                                directory: directory)
+    end
+
     Sessions.list_subagents(session_id: session_id, directory: directory)
   end
 
-  # Read a subagent's optional metadata (not live status) from local disk.
+  # Read a subagent's optional metadata (not live status). With a
+  # session_store, the last agent_metadata entry wins and its synthetic type
+  # marker is omitted.
   # @param session_id [String] The parent session UUID
   # @param agent_id [String] The subagent ID, without the agent- prefix
-  # @param directory [String, nil] Project directory to search in
+  # @param directory [String, nil] Project directory to search in. On disk,
+  #   nil searches every project; with a session_store, nil means the current
+  #   working directory.
+  # @param session_store [SessionStore, nil] Read from this store instead of local disk
   # @return [Hash{String => Object}, nil] CLI metadata, or nil if unavailable
-  def self.get_subagent_metadata(session_id:, agent_id:, directory: nil)
+  def self.get_subagent_metadata(session_id:, agent_id:, directory: nil, session_store: nil)
+    unless session_store.nil?
+      return Sessions.get_subagent_metadata_from_store(session_store: session_store, session_id: session_id,
+                                                       agent_id: agent_id, directory: directory)
+    end
+
     Sessions.get_subagent_metadata(session_id: session_id, agent_id: agent_id, directory: directory)
   end
 
-  # Read a subagent's conversation messages from local disk
+  # Read a subagent's conversation messages
   # @param session_id [String] The session UUID
   # @param agent_id [String] The subagent ID (without the agent- prefix)
-  # @param directory [String, nil] Working directory to search in
+  # @param directory [String, nil] Working directory to search in. On disk,
+  #   nil searches every project; with a session_store, nil means the current
+  #   working directory.
   # @param limit [Integer, nil] Maximum number of messages
   # @param offset [Integer] Number of messages to skip
+  # @param session_store [SessionStore, nil] Read from this store instead of local disk
   # @return [Array<SessionMessage>] Ordered messages from the subagent
-  def self.get_subagent_messages(session_id:, agent_id:, directory: nil, limit: nil, offset: 0)
+  def self.get_subagent_messages(session_id:, agent_id:, directory: nil, limit: nil, offset: 0, session_store: nil)
+    unless session_store.nil?
+      return Sessions.get_subagent_messages_from_store(session_store: session_store, session_id: session_id,
+                                                       agent_id: agent_id, directory: directory,
+                                                       limit: limit, offset: offset)
+    end
+
     Sessions.get_subagent_messages(session_id: session_id, agent_id: agent_id,
                                    directory: directory, limit: limit, offset: offset)
   end
 
-  # Rename a session by appending a custom-title entry
+  # Rename a session by appending a custom-title entry. With a session_store
+  # the entry is appended via SessionStore#append and carries a fresh uuid +
+  # timestamp (so uuid-deduping adapters treat it correctly).
   # @param session_id [String] UUID of the session to rename
   # @param title [String] New session title
-  # @param directory [String, nil] Project directory path
-  def self.rename_session(session_id:, title:, directory: nil)
+  # @param directory [String, nil] Project directory path (nil = cwd with a session_store)
+  # @param session_store [SessionStore, nil] Rename in this store instead of on local disk
+  # @raise [ArgumentError] if session_id is invalid or title is empty
+  # @raise [Errno::ENOENT] if the session is not found (nothing is written)
+  def self.rename_session(session_id:, title:, directory: nil, session_store: nil)
+    unless session_store.nil?
+      return SessionMutations.rename_session_via_store(session_store: session_store, session_id: session_id,
+                                                       title: title, directory: directory)
+    end
+
     SessionMutations.rename_session(session_id: session_id, title: title, directory: directory)
   end
 
   # Tag a session. Pass nil to clear the tag.
   # @param session_id [String] UUID of the session to tag
   # @param tag [String, nil] Tag string, or nil to clear
-  # @param directory [String, nil] Project directory path
-  def self.tag_session(session_id:, tag:, directory: nil)
+  # @param directory [String, nil] Project directory path (nil = cwd with a session_store)
+  # @param session_store [SessionStore, nil] Tag in this store instead of on local disk
+  # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
+  # @raise [Errno::ENOENT] if the session is not found (nothing is written)
+  def self.tag_session(session_id:, tag:, directory: nil, session_store: nil)
+    unless session_store.nil?
+      return SessionMutations.tag_session_via_store(session_store: session_store, session_id: session_id,
+                                                    tag: tag, directory: directory)
+    end
+
     SessionMutations.tag_session(session_id: session_id, tag: tag, directory: directory)
   end
 
-  # Delete a session by removing its JSONL file (hard delete).
+  # Delete a session (hard delete). On disk, removes its JSONL file and
+  # subagent directory, raising Errno::ENOENT if the session is not found.
+  # With a session_store, calls SessionStore#delete — a no-op when the store
+  # does not implement #delete (WORM/append-only backends); whether subagent
+  # subkeys are removed too depends on the store's cascade semantics.
   # @param session_id [String] UUID of the session to delete
-  # @param directory [String, nil] Project directory path
-  def self.delete_session(session_id:, directory: nil)
+  # @param directory [String, nil] Project directory path (nil = cwd with a session_store)
+  # @param session_store [SessionStore, nil] Delete from this store instead of local disk
+  # @raise [ArgumentError] if session_id is invalid
+  # @raise [Errno::ENOENT] on disk, if the session file cannot be found
+  def self.delete_session(session_id:, directory: nil, session_store: nil)
+    unless session_store.nil?
+      return SessionMutations.delete_session_via_store(session_store: session_store, session_id: session_id,
+                                                       directory: directory)
+    end
+
     SessionMutations.delete_session(session_id: session_id, directory: directory)
   end
 
-  # Fork a session into a new branch with fresh UUIDs.
+  # Fork a session into a new branch with fresh UUIDs. With a session_store
+  # the fork transform runs over the store's entries and the fork is appended
+  # to the same store.
   # @param session_id [String] UUID of the session to fork
-  # @param directory [String, nil] Project directory path
+  # @param directory [String, nil] Project directory path (nil = cwd with a session_store)
   # @param up_to_message_id [String, nil] Truncate the fork at this message UUID
   # @param title [String, nil] Custom title for the fork
+  # @param session_store [SessionStore, nil] Fork within this store instead of on local disk
   # @return [ForkSessionResult] Result containing the new session ID
-  def self.fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil)
+  # @raise [ArgumentError] if session_id/up_to_message_id is invalid or there are no messages
+  # @raise [Errno::ENOENT] if the source session is not found
+  def self.fork_session(session_id:, directory: nil, up_to_message_id: nil, title: nil, session_store: nil)
+    unless session_store.nil?
+      return SessionMutations.fork_session_via_store(session_store: session_store, session_id: session_id,
+                                                     directory: directory, up_to_message_id: up_to_message_id,
+                                                     title: title)
+    end
+
     SessionMutations.fork_session(session_id: session_id, directory: directory,
                                   up_to_message_id: up_to_message_id, title: title)
   end
@@ -406,81 +541,83 @@ module ClaudeAgentSDK
     SessionSummary.fold_session_summary(prev, key, entries)
   end
 
-  # List sessions from a SessionStore (store-backed counterpart to list_sessions).
-  # @param session_store [SessionStore] the store to read from
+  # ---- Deprecated store twins (removed in 1.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.
   # @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
 
-  # Read metadata for a single session from a SessionStore.
+  # @deprecated Use {.get_session_info} with +session_store:+. Removed in 1.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
 
-  # Read a session's conversation messages from a SessionStore.
+  # @deprecated Use {.get_session_messages} with +session_store:+. Removed in 1.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, ...)')
     Sessions.get_session_messages_from_store(session_store: session_store, session_id: session_id,
                                              directory: directory, limit: limit, offset: offset)
   end
 
-  # List subagent IDs for a session from a SessionStore (requires list_subkeys).
+  # @deprecated Use {.list_subagents} with +session_store:+. Removed in 1.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
 
-  # Read the latest subagent metadata from a SessionStore, without its synthetic type marker.
+  # @deprecated Use {.get_subagent_metadata} with +session_store:+. Removed in 1.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, ...)')
     Sessions.get_subagent_metadata_from_store(session_store: session_store, session_id: session_id,
                                               agent_id: agent_id, directory: directory)
   end
 
-  # Read a subagent's conversation messages from a SessionStore.
+  # @deprecated Use {.get_subagent_messages} with +session_store:+. Removed in 1.0.
   # @return [Array<SessionMessage>]
   def self.get_subagent_messages_from_store(session_store:, session_id:, agent_id:, directory: nil, limit: nil,
                                             offset: 0)
+    Deprecation.warn_once(:get_subagent_messages_from_store, 'get_subagent_messages(session_store: store, ...)')
     Sessions.get_subagent_messages_from_store(session_store: session_store, session_id: session_id,
                                               agent_id: agent_id, directory: directory, limit: limit, offset: offset)
   end
 
-  # Rename a session in a SessionStore (store-backed counterpart to
-  # rename_session). Appends a custom-title entry carrying a fresh uuid +
-  # timestamp via SessionStore#append.
-  # @raise [ArgumentError] if session_id is invalid or title is empty
-  # @raise [Errno::ENOENT] if the session is not found in the store (nothing is appended)
+  # @deprecated Use {.rename_session} with +session_store:+. Removed in 1.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
 
-  # Tag a session in a SessionStore (store-backed counterpart to tag_session).
-  # Pass nil to clear the tag.
-  # @raise [ArgumentError] if session_id is invalid or tag is empty after sanitization
-  # @raise [Errno::ENOENT] if the session is not found in the store (nothing is appended)
+  # @deprecated Use {.tag_session} with +session_store:+. Removed in 1.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
 
-  # Delete a session from a SessionStore (store-backed counterpart to
-  # delete_session). No-op when the store does not implement #delete
-  # (WORM/append-only backends).
-  # @raise [ArgumentError] if session_id is invalid
+  # @deprecated Use {.delete_session} with +session_store:+. Removed in 1.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
 
-  # Fork a session in a SessionStore into a new branch with fresh UUIDs
-  # (store-backed counterpart to fork_session).
-  # @return [ForkSessionResult] result containing the new session ID
-  # @raise [ArgumentError] if session_id/up_to_message_id is invalid or there are no messages
-  # @raise [Errno::ENOENT] if the source session is not found in the store
+  # @deprecated Use {.fork_session} with +session_store:+. Removed in 1.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, ...)')
     SessionMutations.fork_session_via_store(session_store: session_store, session_id: session_id,
                                             directory: directory, up_to_message_id: up_to_message_id, title: title)
   end
@@ -488,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,
@@ -531,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
 
@@ -557,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
@@ -572,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
@@ -636,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
@@ -647,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
 
@@ -702,6 +849,51 @@ module ClaudeAgentSDK
     end).wait
   end
 
+  # Run a query to completion and return its final ResultMessage.
+  #
+  # The one-call form of {.query} for when you want the answer rather than
+  # the stream: +ask(prompt).result+ is the final text, and the returned
+  # ResultMessage also carries cost, usage, duration, session_id and
+  # structured_output. It is {.query} underneath — same prompt types, same
+  # options, same errors — and it consumes the whole stream before
+  # returning. With an Enumerable prompt that produces several turns, the
+  # last ResultMessage is returned.
+  #
+  # An error result is returned like any other (check #is_error / #subtype);
+  # when the CLI then exits non-zero, {.query} raises ResultError, which
+  # propagates from here unchanged.
+  #
+  # @param prompt [String, Enumerable] The prompt, as for {.query}
+  # @param options [ClaudeAgentOptions, nil] Optional configuration
+  # @param transport [Transport, nil] Optional transport, as for {.query}
+  # @yield [Message] Optionally, every message as it arrives (including the
+  #   final ResultMessage), so you can stream progress and still get the
+  #   result back. Runs where {.query}'s block runs. The block observes the
+  #   stream; it cannot end it early — use {.query} for that.
+  # @return [ResultMessage]
+  # @raise [CLIConnectionError] if the stream ends without a ResultMessage
+  #
+  # @example
+  #   puts ClaudeAgentSDK.ask('What is 2 + 2?').result
+  #
+  # @example Stream progress, keep the result
+  #   result = ClaudeAgentSDK.ask('Refactor lib/foo.rb', options: options) do |message|
+  #     puts message.text if message.is_a?(ClaudeAgentSDK::AssistantMessage)
+  #   end
+  #   puts result   # => [result: success, 3 turns, 12.4s, $0.0421]
+  def self.ask(prompt, options: nil, transport: nil, &block)
+    result = nil
+    query(prompt: prompt, options: options, transport: transport) do |message|
+      result = message if message.is_a?(ResultMessage)
+      block&.call(message)
+    end
+    # The same class Query raises to a caller still waiting on the stream
+    # when it ends ("Control stream ended").
+    raise CLIConnectionError, 'Claude Code ended the conversation without a result message' unless result
+
+    result
+  end
+
   # Client for bidirectional, interactive conversations with Claude Code
   #
   # This client provides full control over the conversation flow with support
@@ -738,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
@@ -805,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)
@@ -871,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)
@@ -961,6 +1162,7 @@ module ClaudeAgentSDK
     # Send interrupt signal
     def interrupt
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       @query_handler.interrupt
     end
 
@@ -968,20 +1170,34 @@ 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
 
+    # Ruby-style spelling of #set_permission_mode: `client.permission_mode = 'plan'`.
+    # Delegates (rather than aliasing) so an override of #set_permission_mode applies to both.
+    def permission_mode=(mode)
+      set_permission_mode(mode)
+    end
+
     # Change the AI model during conversation
     # @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
 
+    # Ruby-style spelling of #set_model: `client.model = 'claude-opus-5'`.
+    def model=(model)
+      set_model(model)
+    end
+
     # Reconnect a failed MCP server
     # @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
 
@@ -990,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
 
@@ -997,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
 
@@ -1022,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
 
@@ -1031,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.
@@ -1046,20 +1266,35 @@ 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
 
+    # Ruby-style spelling of #get_context_usage.
+    # @return [Hash] Context usage response
+    def context_usage
+      get_context_usage
+    end
+
     # Get current MCP server connection status (only works with streaming mode)
     # @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
 
+    # Ruby-style spelling of #get_mcp_status.
+    # @return [Hash] MCP status information, including mcpServers list
+    def mcp_status
+      get_mcp_status
+    end
+
     # Get server initialization info including available commands and output styles
     # @return [Hash] Server info
     def get_server_info
       raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+
       server_info
     end
 
@@ -1142,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)