claude-agent-sdk 0.36.0 → 1.0.0

data/lib/claude_agent_sdk/session_resume.rb

@@ -17,6 +17,8 @@ module ClaudeAgentSDK
   # +config_dir+ is a temp directory laid out like ~/.claude/ — point the
   # subprocess at it via CLAUDE_CONFIG_DIR. +resume_session_id+ is passed as
   # --resume. Call #cleanup after the subprocess exits to remove the temp dir.
+  #
+  # @api private
   class MaterializedResume
     attr_reader :config_dir, :resume_session_id
 
@@ -40,7 +42,7 @@ module ClaudeAgentSDK
       ['.credentials.json', '.claude.json', 'settings.json', 'cowork_settings.json'].each do |name|
         FileUtils.rm_f(File.join(@config_dir, name))
       end
-      warn "Claude SDK: transcript mirror dropped batches; the session store copy is incomplete. " \
+      warn 'Claude SDK: transcript mirror dropped batches; the session store copy is incomplete. ' \
            "Preserving the session transcript under #{File.join(@config_dir, 'projects')} instead of " \
            'deleting it — import it into your session store, then remove the directory.'
     rescue StandardError => e
@@ -55,7 +57,9 @@ module ClaudeAgentSDK
   # store. The CLI only resumes from a local file. This module loads the session
   # from the store, writes it to a temp dir laid out like ~/.claude/, and returns
   # the path so the caller can point the subprocess at it via CLAUDE_CONFIG_DIR.
-  module SessionResume # rubocop:disable Metrics/ModuleLength
+  #
+  # @api private
+  module SessionResume # rubocop:disable Metrics/ModuleLength -- resume materialization and its helpers
     # User settings files seeded into the temp config dir. cowork_settings.json
     # is the alternate filename the CLI reads in cowork-plugins mode.
     SEEDED_SETTINGS_FILES = ['settings.json', 'cowork_settings.json'].freeze
@@ -115,8 +119,9 @@ module ClaudeAgentSDK
     # Returns a MaterializedResume, or nil when no materialization is needed
     # (no store, no resume/continue, store has no entries, or the resolved
     # session id is not a valid UUID) — the caller then falls through to the
-    # normal spawn path. Raises RuntimeError if a store call fails or times out.
-    def materialize_resume_session(options)
+    # normal spawn path. Raises SessionStoreError (#cause: the adapter's own
+    # exception or the timeout) if a store call fails or times out.
+    def materialize_resume_session(options) # rubocop:disable Metrics/AbcSize -- materialization sequence kept in order
       store = options.session_store
       return nil if store.nil?
       return nil if options.resume.nil? && !options.continue_conversation
@@ -155,7 +160,9 @@ module ClaudeAgentSDK
         # so it can authenticate. Missing files are fine (API-key auth, etc.).
         copy_auth_files(tmp_base, options.env)
 
-        materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper) if SessionStore.implements?(store, :list_subkeys)
+        if SessionStore.implements?(store, :list_subkeys)
+          materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper)
+        end
       rescue Exception # rubocop:disable Lint/RescueException
         # Any failure after mkdtemp leaves tmp_base (which may already hold a
         # .credentials.json copy) on disk with no path for the caller to clean
@@ -172,7 +179,7 @@ module ClaudeAgentSDK
 
     # Load entries for session_id; return [session_id, entries] or nil if empty.
     # Callers pass the result through encode_candidate before writing.
-    def load_candidate(store, project_key, session_id, timeout_s, scheduling, wrapper)
+    def load_candidate(store, project_key, session_id, timeout_s, scheduling, wrapper) # rubocop:disable Metrics/ParameterLists -- store-call context (timeout, scheduling, wrapper) threaded explicitly
       entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id}", scheduling, wrapper) do
         store.load('project_key' => project_key, 'session_id' => session_id)
       end
@@ -185,7 +192,7 @@ module ClaudeAgentSDK
     # transcripts are mirrored as ordinary top-level keys and often have the
     # highest mtime, so walk newest->oldest and skip them so --continue resumes
     # the user's conversation, not a subagent's.
-    def resolve_continue_candidate(store, project_key, timeout_s, scheduling, wrapper)
+    def resolve_continue_candidate(store, project_key, timeout_s, scheduling, wrapper) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- newest-first walk with sidechain and validity skips
       sessions = with_timeout(timeout_s, 'SessionStore#list_sessions', scheduling, wrapper) do
         store.list_sessions(project_key)
       end
@@ -284,7 +291,12 @@ module ClaudeAgentSDK
     end
 
     # Run a store call (user code) on a plain thread bounded by timeout_s,
-    # re-raising failures/timeouts as RuntimeError with context. The thread hop
+    # re-raising failures/timeouts as SessionStoreError with context, the
+    # original as #cause (Ruby sets it: the raise is inside the rescue). Every
+    # StandardError is wrapped, the adapter's own RuntimeError included, so
+    # `rescue ClaudeSDKError` catches every materialization failure (0.x let
+    # a RuntimeError through unwrapped and raised the rest as bare
+    # RuntimeErrors, mirroring Python). The thread hop
     # (the default for FiberBoundary with a timeout) both keeps the async
     # scheduler out of the user's store code AND enforces load_timeout_ms
     # unconditionally — including when materialization runs outside an Async
@@ -299,11 +311,11 @@ module ClaudeAgentSDK
     def with_timeout(timeout_s, what, scheduling = :thread, wrapper = nil, &)
       FiberBoundary.invoke(timeout: timeout_s, scheduling: scheduling, wrapper: wrapper, &)
     rescue FiberBoundary::JoinTimeout
-      raise "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
-    rescue RuntimeError
+      raise SessionStoreError, "#{what} timed out after #{(timeout_s * 1000).to_i}ms during resume materialization"
+    rescue SessionStoreError
       raise
     rescue StandardError => e
-      raise "#{what} failed during resume materialization: #{e}"
+      raise SessionStoreError, "#{what} failed during resume materialization: #{e.class}: #{e.message}"
     end
 
     # Write pre-encoded JSON lines (see encode_jsonl_lines), one per line,
@@ -337,7 +349,7 @@ module ClaudeAgentSDK
     # missing files: they cannot exist, and raising here aborted every
     # store-backed resume on a HOME-less host — even API-key auth, which
     # needs none of them.
-    def copy_auth_files(tmp_base, opt_env)
+    def copy_auth_files(tmp_base, opt_env) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- each auth source is optional and copied independently
       caller_config_dir = env_value(opt_env, 'CLAUDE_CONFIG_DIR')
       home = caller_config_dir ? nil : Sessions.home_dir(opt_env)
       source_config_dir = caller_config_dir || (home && File.join(home, '.claude'))
@@ -361,7 +373,9 @@ module ClaudeAgentSDK
       write_redacted_credentials(creds_json, File.join(tmp_base, '.credentials.json'))
 
       claude_json_dir = caller_config_dir || home
-      copy_if_present(File.join(claude_json_dir, '.claude.json'), File.join(tmp_base, '.claude.json')) if claude_json_dir
+      if claude_json_dir
+        copy_if_present(File.join(claude_json_dir, '.claude.json'), File.join(tmp_base, '.claude.json'))
+      end
 
       # User settings carry apiKeyHelper (a fourth auth mechanism alongside
       # .credentials.json / Keychain / env vars) plus the user's env, hooks and
@@ -584,7 +598,7 @@ module ClaudeAgentSDK
     end
 
     # Load and write all subagent transcripts/metadata under session_id.
-    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper)
+    def materialize_subkeys(store, project_dir, project_key, session_id, timeout_s, scheduling, wrapper) # rubocop:disable Metrics/ParameterLists -- store-call context (timeout, scheduling, wrapper) threaded explicitly
       session_dir = File.join(project_dir, session_id)
       subkeys = with_timeout(timeout_s, "SessionStore#list_subkeys for session #{session_id}", scheduling, wrapper) do
         store.list_subkeys('project_key' => project_key, 'session_id' => session_id)
@@ -598,7 +612,8 @@ module ClaudeAgentSDK
           next
         end
 
-        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}", scheduling, wrapper) do
+        sub_entries = with_timeout(timeout_s, "SessionStore#load for session #{session_id} subpath #{subpath}",
+                                   scheduling, wrapper) do
           store.load('project_key' => project_key, 'session_id' => session_id, 'subpath' => subpath)
         end
         next if sub_entries.nil? || sub_entries.empty?
@@ -634,7 +649,7 @@ module ClaudeAgentSDK
     def encode_agent_metadata(meta_content, subpath)
       JSON.generate(meta_content)
     rescue JSON::JSONError => e
-      warn "Claude SDK: [SessionStore] resume: skipping unserializable agent metadata " \
+      warn 'Claude SDK: [SessionStore] resume: skipping unserializable agent metadata ' \
            "for subpath #{subpath} (#{e.class}: #{e.message})"
       nil
     end

data/lib/claude_agent_sdk/session_store.rb

@@ -56,8 +56,8 @@ module ClaudeAgentSDK
   # mode) and a cancelled append may remain permanently half-applied in the
   # store. The drop is surfaced (MirrorErrorMessage, batches_dropped?) and
   # the local transcript remains the source of truth; the
-  # dedupe-by-entry-uuid recommendation above stays advisory. The method is deliberately NOT defined here: the SDK probes
-  # `respond_to?(:callback_scheduling)` (see
+  # dedupe-by-entry-uuid recommendation above stays advisory. The method is
+  # deliberately NOT defined here: the SDK probes `respond_to?(:callback_scheduling)` (see
   # SessionStores.store_callback_scheduling), so pure duck-typed adapters
   # stay minimal, and an app can opt a third-party fiber-native adapter in
   # via a singleton method (`def store.callback_scheduling = :inline`).
@@ -290,6 +290,8 @@ module ClaudeAgentSDK
   end
 
   # Internal SessionStore support functions (path mapping, option validation).
+  #
+  # @api private
   module SessionStores
     STORE_CALLBACK_SCHEDULING_MODES = %i[thread inline].freeze
 
@@ -349,7 +351,9 @@ module ClaudeAgentSDK
       second = parts[1]
 
       # Main transcript: <project_key>/<session_id>.jsonl
-      return { 'project_key' => project_key, 'session_id' => second.delete_suffix('.jsonl') } if parts.length == 2 && second.end_with?('.jsonl')
+      if parts.length == 2 && second.end_with?('.jsonl')
+        return { 'project_key' => project_key, 'session_id' => second.delete_suffix('.jsonl') }
+      end
 
       # Subagent transcript: <project_key>/<session_id>/subagents/.../agent-<id>.jsonl
       if parts.length >= 4

data/lib/claude_agent_sdk/session_summary.rb

@@ -16,6 +16,8 @@ module ClaudeAgentSDK
   # (string keys from JSON), and the summary's opaque +data+ dict is persisted
   # verbatim by adapters — string keys survive a JSON round-trip (Postgres
   # JSONB, Redis) losslessly, whereas symbol keys would not.
+  #
+  # @api private
   module SessionSummary
     # JSONL entry keys -> summary data keys for last-wins string fields. Each
     # appended entry overwrites the previous value when present.
@@ -49,7 +51,7 @@ module ClaudeAgentSDK
     # @param key [Hash] the SessionKey (string keys)
     # @param entries [Array<Hash>] newly appended transcript entries
     # @return [Hash] the updated summary entry ({ 'session_id', 'mtime', 'data' })
-    def fold_session_summary(prev, key, entries)
+    def fold_session_summary(prev, key, entries) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- incremental fold over every summary field
       summary = if prev
                   { 'session_id' => prev['session_id'], 'mtime' => prev['mtime'], 'data' => prev['data'].dup }
                 else
@@ -147,7 +149,7 @@ module ClaudeAgentSDK
     # deliberately match the disk extractor (not Python's per-char replace) so
     # the Ruby store path and disk path produce identical first_prompt values
     # for the same transcript.
-    def fold_first_prompt(data, entry)
+    def fold_first_prompt(data, entry) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- must match the disk first-prompt extractor rule for rule
       return if data['first_prompt_locked']
       return unless entry['type'] == 'user'
       return if entry['isMeta'] == true || entry['isCompactSummary'] == true

data/lib/claude_agent_sdk/sessions.rb

@@ -83,7 +83,9 @@ module ClaudeAgentSDK
   end
 
   # Session browsing functions
-  module Sessions # rubocop:disable Metrics/ModuleLength
+  #
+  # @api private
+  module Sessions # rubocop:disable Metrics/ModuleLength -- session listing/reading functions share private helpers
     LITE_READ_BUF_SIZE = 65_536
     MAX_SANITIZED_LENGTH = 200
 
@@ -435,7 +437,7 @@ module ClaudeAgentSDK
     end
 
     # Extract the first meaningful user prompt from the head of a JSONL file
-    def extract_first_prompt_from_head(head)
+    def extract_first_prompt_from_head(head) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- first-prompt skip rules, matched by the store fold
       command_fallback = nil
 
       head.each_line do |line|
@@ -547,7 +549,7 @@ module ClaudeAgentSDK
       [head, tail]
     end
 
-    def build_session_info(file_path, head, tail, stat, project_path)
+    def build_session_info(file_path, head, tail, stat, project_path) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- one optional field per SDKSessionInfo attribute
       # User-set title (customTitle) wins over AI-generated title (aiTitle).
       # Consult the head only when the tail has no occurrence of that field.
       # Normalize blanks AFTER choosing the latest occurrence: an explicit
@@ -998,7 +1000,7 @@ module ClaudeAgentSDK
     # NotImplementedError (caller falls back to the slow path). Sessions missing
     # a sidecar or whose sidecar is stale (summary.mtime < the session's current
     # mtime) are routed through gap-fill so the fold is recomputed from source.
-    def list_sessions_via_summaries(store, project_key, project_path, limit, offset)
+    def list_sessions_via_summaries(store, project_key, project_path, limit, offset) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- fast path plus stale/missing-sidecar gap-fill
       begin
         # Array(): a non-conformant store returning nil (e.g. a NULL JSONB read)
         # degrades to gap-fill instead of crashing on nil.each, matching the
@@ -1046,7 +1048,7 @@ module ClaudeAgentSDK
     # leaves a short page; loads stay bounded to ~offset + limit + (the dropped
     # placeholders encountered before the page fills), preserving the fast
     # path's "don't load every session" intent.
-    def paginate_resolving_gaps(store, project_key, project_path, slots, limit, offset)
+    def paginate_resolving_gaps(store, project_key, project_path, slots, limit, offset) # rubocop:disable Metrics/ParameterLists -- pagination state threaded explicitly
       offset = 0 unless offset&.positive?
       results = []
       skipped = 0
@@ -1399,7 +1401,7 @@ module ClaudeAgentSDK
     # threads (so a full pipe buffer can't deadlock git) and SIGKILL the
     # child if the deadline passes. Matches Python's
     # `subprocess.run(..., timeout=5)`.
-    def detect_worktrees(path)
+    def detect_worktrees(path) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- bounded git subprocess: drained pipes, deadline kill
       stdin, stdout, stderr, wait_thr = Open3.popen3('git', '-C', path, 'worktree', 'list', '--porcelain')
       stdin.close
 

data/lib/claude_agent_sdk/streaming.rb

@@ -21,7 +21,7 @@ module ClaudeAgentSDK
         parent_tool_use_id: parent_tool_use_id,
         session_id: session_id
       }
-      JSON.generate(message) + "\n"
+      "#{JSON.generate(message)}\n"
     end
 
     # Create an Enumerator from an array of messages

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -11,17 +11,26 @@ require_relative 'cli_installer'
 
 module ClaudeAgentSDK
   # Subprocess transport using Claude Code CLI
-  class SubprocessCLITransport < Transport
+  class SubprocessCLITransport < Transport # rubocop:disable Metrics/ClassLength -- subprocess lifecycle: discovery, spawn, IO, teardown
+    # @api private
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
+    # @api private
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
+    # @api private
     SKIP_VERSION_CHECK_ENV_VAR = 'CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK'
+    # @api private
     CLI_PATH_ENV_VAR = 'CLAUDE_CLI_PATH'
+    # @api private
     VERSION_CHECK_TIMEOUT_SECONDS = 2 # mirrors Python's anyio.fail_after(2)
+    # @api private
     RECENT_STDERR_LINES_LIMIT = 20
     # After stdout EOF the child has closed (or lost) its last stdout handle,
     # so it is normally already exiting; a CLI still running this long
     # afterwards is wedged and gets the same TERM -> KILL ladder as #close.
+    #
+    # @api private
     EOF_EXIT_GRACE_SECONDS = 5
+    # @api private
     EOF_TERM_GRACE_SECONDS = 2
 
     # Track live CLI subprocesses so we can terminate them when the parent Ruby
@@ -39,27 +48,36 @@ module ClaudeAgentSDK
     # `self.class.register_active_process` would otherwise reach a nil mutex and
     # raise mid-#connect, orphaning the just-spawned child. The base-class
     # at_exit handler must be able to see every subprocess, a subclass's too.
+    #
+    # @api private
     ACTIVE_PROCESSES = Set.new
+    # @api private
     ACTIVE_PROCESSES_MUTEX = Mutex.new
 
     class << self
       # Public readers (the test suite uses `described_class.active_processes`);
       # they return the shared constants so subclasses observe the same objects.
+      #
+      # @api private
       def active_processes
         ACTIVE_PROCESSES
       end
 
+      # @api private
       def active_processes_mutex
         ACTIVE_PROCESSES_MUTEX
       end
 
       # +wait_thr+ is the Process::Waiter returned by Open3.popen3.
+      #
+      # @api private
       def register_active_process(wait_thr)
         return unless wait_thr
 
         active_processes_mutex.synchronize { active_processes.add(wait_thr) }
       end
 
+      # @api private
       def deregister_active_process(wait_thr)
         return unless wait_thr
 
@@ -79,6 +97,8 @@ module ClaudeAgentSDK
       # raises (e.g. ThreadError if reached from a trap context, or a
       # concurrent-modification error from the unlocked read), honoring the
       # "never interrupt interpreter shutdown" contract.
+      #
+      # @api private
       def kill_active_processes
         active_processes.to_a.each do |wait_thr|
           next unless wait_thr.alive?
@@ -94,6 +114,7 @@ module ClaudeAgentSDK
     end
 
     def initialize(options_or_prompt = nil, options = nil)
+      super() # Transport defines no state today; keep the chain intact if it ever does
       # Support both new single-arg form and legacy two-arg form
       @options = options.nil? ? options_or_prompt : options
       @cli_path = @options.cli_path || find_cli
@@ -134,7 +155,9 @@ module ClaudeAgentSDK
     #      whatever version happens to be installed globally on the host.
     #   3. `which claude`.
     #   4. Well-known install locations.
-    def find_cli
+    #
+    # @api private
+    def find_cli # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- ordered discovery probes (env, vendored, PATH, known locations)
       env_path = ENV.fetch(CLI_PATH_ENV_VAR, nil).to_s
       unless env_path.empty?
         # Absolutize against the CURRENT working directory, which is where the
@@ -188,18 +211,17 @@ module ClaudeAgentSDK
         return path if File.file?(path) && File.executable?(path)
       end
 
-      raise CLINotFoundError.new(
-        "Claude Code not found. Install with:\n" \
-        "  npm install -g @anthropic-ai/claude-code\n" \
-        "\nIf already installed locally, try:\n" \
-        '  export PATH="$HOME/node_modules/.bin:$PATH"' \
-        "\n\nOr provide the path via ClaudeAgentOptions:\n" \
-        "  ClaudeAgentOptions.new(cli_path: '/path/to/claude')" \
-        "\n\nFor hermetic deploys (Docker/CI), vendor a pinned CLI into the project:\n" \
-        "  ClaudeAgentSDK::CLIInstaller.install_pinned  # installs #{CLIInstaller::PINNED_CLI_VERSION}" \
-        "\n\nOr point the SDK at an existing binary:\n" \
-        "  export #{CLI_PATH_ENV_VAR}=/path/to/claude"
-      )
+      raise CLINotFoundError,
+            "Claude Code not found. Install with:\n  " \
+            "npm install -g @anthropic-ai/claude-code\n" \
+            "\nIf already installed locally, try:\n  " \
+            'export PATH="$HOME/node_modules/.bin:$PATH"' \
+            "\n\nOr provide the path via ClaudeAgentOptions:\n  " \
+            "ClaudeAgentOptions.new(cli_path: '/path/to/claude')" \
+            "\n\nFor hermetic deploys (Docker/CI), vendor a pinned CLI into the project:\n  " \
+            "ClaudeAgentSDK::CLIInstaller.install_pinned  # installs #{CLIInstaller::PINNED_CLI_VERSION}" \
+            "\n\nOr point the SDK at an existing binary:\n  " \
+            "export #{CLI_PATH_ENV_VAR}=/path/to/claude"
     end
 
     # Inject W3C trace context (TRACEPARENT/TRACESTATE, plus BAGGAGE) into the
@@ -209,6 +231,8 @@ module ClaudeAgentSDK
     # group. Gate on the carrier's traceparent key (the W3C propagator writes
     # it only for a valid span context) so a baggage-only carrier or a noop
     # propagator preserves inherited env.
+    #
+    # @api private
     def inject_otel_trace_context(process_env, custom_env)
       return unless defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:propagation)
 
@@ -233,11 +257,12 @@ module ClaudeAgentSDK
       # Exception). ScriptError too: NotImplementedError < ScriptError.
     end
 
+    # @api private
     def build_command
       CommandBuilder.new(@cli_path, @options).build
     end
 
-    def connect
+    def connect # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- spawn sequence kept in order
       return if @process
 
       check_claude_version
@@ -246,7 +271,7 @@ module ClaudeAgentSDK
 
       # Build environment
       # Convert symbol keys to strings for spawn compatibility
-      custom_env = @options.env.transform_keys { |k| k.to_s }
+      custom_env = @options.env.transform_keys(&:to_s)
       # Explicitly unset CLAUDECODE to prevent "nested session" detection when the SDK
       # launches Claude Code from within an existing Claude Code terminal.
       # NOTE: Must set to nil (not just omit the key) — Ruby's spawn only overlays
@@ -312,7 +337,7 @@ module ClaudeAgentSDK
 
         # Always keep stdin open — streaming mode uses it for the control protocol
         @ready = true
-      rescue Errno::ENOENT => e
+      rescue Errno::ENOENT
         # Check if error is from cwd or CLI
         if @cwd && !File.directory?(@cwd.to_s)
           error = CLIConnectionError.new("Working directory does not exist: #{@cwd}")
@@ -332,6 +357,7 @@ module ClaudeAgentSDK
       end
     end
 
+    # @api private
     def handle_stderr
       return unless @stderr
 
@@ -375,6 +401,7 @@ module ClaudeAgentSDK
       # Stream-level error (pipe closed mid-read); the loop naturally ends here.
     end
 
+    # @api private
     def drain_stderr_with_accumulation
       return unless @stderr
 
@@ -387,7 +414,7 @@ module ClaudeAgentSDK
       end
     end
 
-    def close
+    def close # rubocop:disable Metrics/MethodLength -- teardown ordering is load-bearing
       @ready = false
       return unless @process
 
@@ -465,7 +492,9 @@ module ClaudeAgentSDK
     # graceful exit after stdin EOF, escalate TERM → KILL on timeout. Runs on
     # the reactor and suspends at several points; #close's ensure covers the
     # cancellation-abandoned case.
-    def teardown_process
+    #
+    # @api private
+    def teardown_process # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- TERM/KILL escalation and reaping; ordering is load-bearing
       cleanup_errors = []
 
       # Kill stderr thread
@@ -543,9 +572,7 @@ module ClaudeAgentSDK
       end
 
       # Log any cleanup errors (non-fatal)
-      if cleanup_errors.any?
-        warn "Claude SDK: Cleanup warnings: #{cleanup_errors.join(', ')}"
-      end
+      warn "Claude SDK: Cleanup warnings: #{cleanup_errors.join(', ')}" if cleanup_errors.any?
 
       self.class.deregister_active_process(@process)
     end
@@ -558,6 +585,8 @@ module ClaudeAgentSDK
     # left either way. The alive? guard also makes the delayed KILL
     # pid-reuse-safe: while the waiter thread reports alive (not yet reaped),
     # the pid cannot have been recycled.
+    #
+    # @api private
     def force_terminate_in_background(process, grace_seconds: 2)
       return unless process
 
@@ -576,20 +605,18 @@ module ClaudeAgentSDK
       end
 
       Thread.new do
-        begin
-          unless process.join(grace_seconds)
-            begin
-              Process.kill('KILL', pid) if process.alive?
-            rescue Errno::ESRCH
-              # Still wait for the waiter when exit raced the signal.
-            end
-            process.join(grace_seconds)
+        unless process.join(grace_seconds)
+          begin
+            Process.kill('KILL', pid) if process.alive?
+          rescue Errno::ESRCH
+            # Still wait for the waiter when exit raced the signal.
           end
-        rescue StandardError
-          nil # best-effort; retain ownership if termination/reaping failed
-        ensure
-          self.class.deregister_active_process(process) unless process.alive?
+          process.join(grace_seconds)
         end
+      rescue StandardError
+        nil # best-effort; retain ownership if termination/reaping failed
+      ensure
+        self.class.deregister_active_process(process) unless process.alive?
       end
     end
 
@@ -598,6 +625,8 @@ module ClaudeAgentSDK
     # across threads via Thread#raise and corrupts Async fiber-scheduler state
     # (close is always called inside an Async task). Yields to the current
     # Async task when one is active so the reactor keeps running.
+    #
+    # @api private
     def wait_process_with_timeout(timeout_seconds, process = @process)
       deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds
       task = defined?(Async::Task) ? Async::Task.current? : nil
@@ -613,6 +642,8 @@ module ClaudeAgentSDK
     # Process::Waiter#join(timeout): under a Fiber scheduler Ruby 3.2's
     # Thread#join ignores its timeout and never returns for a live thread
     # (probed on 3.2.0; 3.3/3.4 honor it).
+    #
+    # @api private
     def process_exited_within?(process, seconds)
       wait_process_with_timeout(seconds, process)
       true
@@ -621,7 +652,7 @@ module ClaudeAgentSDK
     end
 
     def write(data)
-      raise CLIConnectionError, "Cannot write to terminated process" if @process && !@process.alive?
+      raise CLIConnectionError, 'Cannot write to terminated process' if @process && !@process.alive?
       raise CLIConnectionError, "Cannot write to process that exited with error: #{@exit_error}" if @exit_error
 
       # Snapshot @stdin under the lock so close() nilling it concurrently is
@@ -688,7 +719,7 @@ module ClaudeAgentSDK
       # Ignore
     end
 
-    def read_messages(&)
+    def read_messages(&) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- concurrency-sensitive read loop; kept whole on purpose
       return enum_for(:read_messages) unless block_given?
 
       raise CLIConnectionError, 'Not connected' unless @process && @stdout
@@ -747,7 +778,7 @@ module ClaudeAgentSDK
             buffer_length = json_buffer.bytesize
             json_buffer = ''
             raise CLIJSONDecodeError.new(
-              "JSON message exceeded maximum buffer size",
+              'JSON message exceeded maximum buffer size',
               StandardError.new("Buffer size #{buffer_length} exceeds limit #{@max_buffer_size}")
             )
           end
@@ -865,6 +896,7 @@ module ClaudeAgentSDK
       )
     end
 
+    # @api private
     def check_claude_version
       # Mirrors Python's os.environ.get truthiness: any non-empty value skips,
       # including '0'/'false'/' '; unset or empty string runs the check.
@@ -877,7 +909,7 @@ module ClaudeAgentSDK
         # stdout chunk): this searches anywhere in stdout+stderr, so leading
         # noise (a shim's own version line) could be mistaken for the CLI
         # version. Pre-existing shape; the check is best-effort only.
-        if match = output.match(/([0-9]+\.[0-9]+\.[0-9]+)/)
+        if (match = output.match(/([0-9]+\.[0-9]+\.[0-9]+)/))
           version = match[1]
           version_parts = version.split('.').map(&:to_i)
           min_parts = MINIMUM_CLAUDE_CODE_VERSION.split('.').map(&:to_i)
@@ -887,7 +919,7 @@ module ClaudeAgentSDK
           if (version_parts <=> min_parts).negative?
             warning = "Warning: Claude Code version #{version} at #{@cli_path} is unsupported in the Agent SDK. " \
                       "Minimum required version is #{MINIMUM_CLAUDE_CODE_VERSION}. " \
-                      "Some features may not work correctly."
+                      'Some features may not work correctly.'
             warn warning
           end
         end
@@ -914,7 +946,7 @@ module ClaudeAgentSDK
     # read both pipes to EOF (pre-existing capture3 shape), so the deadline
     # also bounds CLI exit. ensure always reaps the probe (mirrors Python's
     # finally: terminate(); wait()).
-    def capture_cli_version_output
+    def capture_cli_version_output # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- bounded subprocess probe: drained pipes, reaping
       stdin, stdout, stderr, wait_thr = Open3.popen3(@cli_path.to_s, '-v')
       stdin.close
       drainer = Thread.new { [stdout.read, stderr.read] }