claude-agent-sdk 0.36.0 → 0.37.0

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] }

data/lib/claude_agent_sdk/testing/session_store_conformance.rb

@@ -5,7 +5,7 @@ require_relative '../session_summary'
 
 module ClaudeAgentSDK
   # Test helpers shipped in the gem for third-party SessionStore adapter authors.
-  module Testing # rubocop:disable Metrics/ModuleLength
+  module Testing # rubocop:disable Metrics/ModuleLength -- the whole conformance suite in one module
     # Raised by run_session_store_conformance when a behavioral contract fails.
     class ConformanceError < StandardError; end
 
@@ -100,7 +100,7 @@ module ClaudeAgentSDK
 
     # -- Required: append + load -------------------------------------------
 
-    def check_append_and_load(fresh, has_list_sessions) # rubocop:disable Metrics/MethodLength
+    def check_append_and_load(fresh, has_list_sessions) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- linear assertion script
       # 1. append then load returns same entries in same order.
       store = fresh.call
       store.append(key, [entry('uuid' => 'b', 'n' => 1), entry('uuid' => 'a', 'n' => 2)])
@@ -165,7 +165,7 @@ module ClaudeAgentSDK
 
     # -- Optional: list_sessions -------------------------------------------
 
-    def check_list_sessions(fresh)
+    def check_list_sessions(fresh) # rubocop:disable Metrics/AbcSize -- linear assertion script
       # 7. list_sessions returns session_ids for project.
       store = fresh.call
       store.append({ 'project_key' => 'proj', 'session_id' => 'a' }, [entry('n' => 1)])
@@ -197,7 +197,7 @@ module ClaudeAgentSDK
 
     # -- Optional: list_session_summaries ----------------------------------
 
-    def check_list_session_summaries(fresh, has_list_sessions, has_delete) # rubocop:disable Metrics/MethodLength
+    def check_list_session_summaries(fresh, has_list_sessions, has_delete) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- linear assertion script
       # 14. persisted fold output round-trips through fold_session_summary.
       store = fresh.call
       summ_key = { 'project_key' => 'proj', 'session_id' => 'summ-sess' }
@@ -236,8 +236,10 @@ module ClaudeAgentSDK
       # Subagent appends must NOT affect the main session's summary.
       store.append(summ_key.merge('subpath' => 'subagents/agent-1'),
                    [entry('timestamp' => '2024-01-01T00:00:09.000Z', 'customTitle' => 'subagent')])
-      after_sub = summaries_by_id(store, 'proj', ['summ-sess'],
-                                  'list_session_summaries must still return one row per session after a subagent append')
+      after_sub = summaries_by_id(
+        store, 'proj', ['summ-sess'],
+        'list_session_summaries must still return one row per session after a subagent append'
+      )
       assert_eq(after_sub['summ-sess']['data'], summ['data'], 'subagent appends must not change the main summary')
       assert_eq(store.list_session_summaries('never-appended-project'), [], 'unknown project must list no summaries')
 
@@ -249,7 +251,7 @@ module ClaudeAgentSDK
 
     # -- Optional: delete --------------------------------------------------
 
-    def check_delete(fresh, has_list_subkeys, has_list_sessions) # rubocop:disable Metrics/MethodLength
+    def check_delete(fresh, has_list_subkeys, has_list_sessions) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- linear assertion script
       # 9. delete main then load returns nil (delete of never-written is a no-op).
       store = fresh.call
       store.delete('project_key' => 'proj', 'session_id' => 'never-written')
@@ -308,7 +310,7 @@ module ClaudeAgentSDK
 
     # -- Optional: list_subkeys --------------------------------------------
 
-    def check_list_subkeys(fresh)
+    def check_list_subkeys(fresh) # rubocop:disable Metrics/AbcSize -- linear assertion script
       # 12. list_subkeys returns subpaths (scoped to the session).
       store = fresh.call
       store.append(key, [entry('n' => 1)])
@@ -317,7 +319,8 @@ module ClaudeAgentSDK
       store.append({ 'project_key' => key['project_key'], 'session_id' => 'other-sess',
                      'subpath' => 'subagents/agent-x' }, [entry('n' => 1)])
       subkeys = store.list_subkeys(key)
-      assert_eq(subkeys.sort, ['subagents/agent-1', 'subagents/agent-2'], "list_subkeys must return this session's subpaths")
+      assert_eq(subkeys.sort, ['subagents/agent-1', 'subagents/agent-2'],
+                "list_subkeys must return this session's subpaths")
       assert(!subkeys.include?('subagents/agent-x'), "list_subkeys must not leak another session's subkeys")
 
       # 13. list_subkeys excludes the main transcript.
@@ -381,7 +384,8 @@ module ClaudeAgentSDK
       return if actual == expected
 
       raise ConformanceError,
-            "SessionStore conformance failed: #{message}\n  expected: #{expected.inspect}\n  actual:   #{actual.inspect}"
+            "SessionStore conformance failed: #{message}\n  " \
+            "expected: #{expected.inspect}\n  actual:   #{actual.inspect}"
     end
 
     private_class_method :check_callback_scheduling_declaration, :check_append_and_load, :check_list_sessions,

data/lib/claude_agent_sdk/transcript_mirror_batcher.rb

@@ -44,6 +44,8 @@ module ClaudeAgentSDK
   # may remain permanently HALF-applied in the store. The drop is surfaced
   # (MirrorErrorMessage, batches_dropped?); the local transcript remains the
   # source of truth.
+  #
+  # @api private
   class TranscriptMirrorBatcher
     # Eager-flush thresholds (exposed for tests).
     MAX_PENDING_ENTRIES = 500