claude-agent-sdk 0.16.1 → 0.16.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 784f87932778dac72fe69ebbe3236e62a7df31f9671b52150fae392aa3d57f05
-  data.tar.gz: cd743d1cabb8bd151457f0a4b18be725f25b5de684ba2430df8a76037900dd98
+  metadata.gz: b2c37eb821ab8e4fe91cc69b4d0d683b364617b321d74e642f330c7c560850dd
+  data.tar.gz: 62c00c3973e9bfabda1ebf5f95b4ce4ca79bd6dc4c36e8f0bcf0038ede7c588f
 SHA512:
-  metadata.gz: 68b582ef69fec09c0487d6d5600c76ac5d5a8420264f2b151cc7f52f95c7fb975339d6afa9fe519d4e75b48781c4f6132446fb03b2e9995decc3088ccd66c0f1
-  data.tar.gz: d119aaba15cb76997ceb58abbc43176a82df9ad4b697089a6b26ffbe342fb50ea10173890dddb03d5dc13397989abb774b617f140b1f92b3fdb0a8d16e3298d2
+  metadata.gz: af171dc45b39c86eee1dacd829f062e230b3369225ef394df0df43b9a05d2ecec087a6566dd00cb7a4a01d1af1f3a5677f08f9ae04ecaa9c46d9490c75acaf46
+  data.tar.gz: f96ce5a7ee822ef161a541e29fa6677fb28c77c5e316965aa15477a782e087a60b15ea706665488e09f102356f91fa43491be82f526910c2d4afa4f08b3256fd

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.3] - 2026-04-23
+
+### Changed
+- Internal: extracted `SubprocessCLITransport#record_bounded_stderr` helper to deduplicate the recent-stderr ring-buffer append/trim logic shared by `handle_stderr` and `drain_stderr_with_accumulation`, and replaced the inlined `20` cap with a named `RECENT_STDERR_LINES_LIMIT` constant. No public behavior change.
+
+## [0.16.2] - 2026-04-23
+
+### Changed
+- Extracted `ClaudeAgentSDK::CommandBuilder` from `SubprocessCLITransport`. CLI argv assembly now lives in its own class and can be exercised in isolation — `CommandBuilder.new(cli_path, options).build` returns the argv array without booting a transport. No public behavior change; `SubprocessCLITransport#build_command` still works and now delegates to `CommandBuilder`.
+
 ## [0.16.1] - 2026-04-21
 
 ### Fixed

data/README.md

@@ -108,7 +108,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.16.1'
+gem 'claude-agent-sdk', '~> 0.16.3'
 ```
 
 And then execute:

data/lib/claude_agent_sdk/command_builder.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+require_relative "types"
+
+module ClaudeAgentSDK
+  # Builds the CLI argv array from a ClaudeAgentOptions instance.
+  class CommandBuilder
+    EXTRA_ARG_FLAG_REGEXP = /\A[a-z0-9][a-z0-9-]*\z/
+
+    def initialize(cli_path, options)
+      @cli_path = cli_path
+      @options = options
+    end
+
+    def build
+      cmd = [@cli_path, "--output-format", "stream-json", "--verbose"]
+
+      append_system_prompt(cmd)
+      append_tools(cmd)
+      append_allowed_tools(cmd)
+      append_disallowed_tools(cmd)
+      append_max_turns(cmd)
+      append_model(cmd)
+      append_permission(cmd)
+      append_session(cmd)
+      append_settings(cmd)
+      append_budget(cmd)
+      append_thinking(cmd)
+      append_effort(cmd)
+      append_betas(cmd)
+      append_append_allowed_tools(cmd)
+      append_output_format(cmd)
+      append_additional_dirs(cmd)
+      append_mcp_servers(cmd)
+      append_boolean_flags(cmd)
+      append_plugins(cmd)
+      append_setting_sources(cmd)
+      append_extra_args(cmd)
+
+      # Always use streaming mode for bidirectional control protocol.
+      # Prompts and agents are sent via stdin (initialize + user messages),
+      # which avoids OS ARG_MAX limits for large prompts and agent configurations.
+      cmd.push("--input-format", "stream-json")
+
+      cmd
+    end
+
+    private
+
+    def append_system_prompt(cmd)
+      case @options.system_prompt
+      when nil
+        # When nil, pass empty string to ensure predictable behavior without default Claude Code system prompt
+        cmd.push("--system-prompt", "")
+      when String
+        cmd.push("--system-prompt", @options.system_prompt)
+      when SystemPromptFile
+        cmd.push("--system-prompt-file", @options.system_prompt.path)
+      when SystemPromptPreset
+        # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
+        # Only --append-system-prompt is passed if append text is provided
+        cmd.push("--append-system-prompt", @options.system_prompt.append) if @options.system_prompt.append
+      when Hash
+        append_hash_system_prompt(cmd, @options.system_prompt)
+      end
+    end
+
+    def append_hash_system_prompt(cmd, prompt_hash)
+      prompt_type = prompt_hash[:type] || prompt_hash["type"]
+      case prompt_type
+      when "file"
+        prompt_path = prompt_hash[:path] || prompt_hash["path"]
+        cmd.push("--system-prompt-file", prompt_path) if prompt_path
+      when "preset"
+        append = prompt_hash[:append] || prompt_hash["append"]
+        # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
+        cmd.push("--append-system-prompt", append) if append
+      end
+    end
+
+    def append_allowed_tools(cmd)
+      cmd.push("--allowedTools", @options.allowed_tools.join(",")) unless @options.allowed_tools.empty?
+    end
+
+    def append_disallowed_tools(cmd)
+      cmd.push("--disallowedTools", @options.disallowed_tools.join(",")) unless @options.disallowed_tools.empty?
+    end
+
+    def append_max_turns(cmd)
+      cmd.push("--max-turns", @options.max_turns.to_s) if @options.max_turns
+    end
+
+    def append_model(cmd)
+      cmd.push("--model", @options.model) if @options.model
+      cmd.push("--fallback-model", @options.fallback_model) if @options.fallback_model
+    end
+
+    def append_permission(cmd)
+      cmd.push("--permission-prompt-tool", @options.permission_prompt_tool_name) if @options.permission_prompt_tool_name
+      cmd.push("--permission-mode", @options.permission_mode) if @options.permission_mode
+    end
+
+    def append_session(cmd)
+      cmd.push("--continue") if @options.continue_conversation
+      cmd.push("--resume", @options.resume) if @options.resume
+      cmd.push("--session-id", @options.session_id) if @options.session_id
+    end
+
+    def append_settings(cmd)
+      return unless @options.settings || @options.sandbox
+
+      settings_hash = {}
+      settings_is_path = false
+
+      if @options.settings
+        if @options.settings.is_a?(String)
+          begin
+            settings_hash = JSON.parse(@options.settings)
+          rescue JSON::ParserError
+            if @options.sandbox
+              settings_hash = load_settings_file(@options.settings)
+            else
+              settings_is_path = true
+              cmd.push("--settings", @options.settings)
+            end
+          end
+        elsif @options.settings.is_a?(Hash)
+          settings_hash = @options.settings.dup
+        end
+      end
+
+      if !settings_is_path && @options.sandbox
+        sandbox_hash = @options.sandbox.is_a?(SandboxSettings) ? @options.sandbox.to_h : @options.sandbox
+        settings_hash[:sandbox] = sandbox_hash unless sandbox_hash.empty?
+      end
+
+      cmd.push("--settings", JSON.generate(settings_hash)) if !settings_is_path && !settings_hash.empty?
+    end
+
+    def append_budget(cmd)
+      cmd.push("--max-budget-usd", @options.max_budget_usd.to_s) if @options.max_budget_usd
+
+      return unless @options.task_budget
+
+      total = if @options.task_budget.is_a?(TaskBudget)
+                @options.task_budget.total
+              else
+                @options.task_budget[:total] || @options.task_budget["total"]
+              end
+      cmd.push("--task-budget", total.to_s) if total
+    end
+
+    # Thinking configuration takes precedence over deprecated max_thinking_tokens
+    def append_thinking(cmd)
+      if @options.thinking
+        case @options.thinking
+        when ThinkingConfigAdaptive
+          cmd.push("--thinking", "adaptive")
+        when ThinkingConfigEnabled
+          cmd.push("--max-thinking-tokens", @options.thinking.budget_tokens.to_s)
+        when ThinkingConfigDisabled
+          cmd.push("--thinking", "disabled")
+        end
+      elsif @options.max_thinking_tokens
+        cmd.push("--max-thinking-tokens", @options.max_thinking_tokens.to_s)
+      end
+    end
+
+    # The set of supported levels is model-dependent; the CLI falls back to
+    # the highest supported level at or below the one requested
+    # (e.g. `xhigh` → `high` on Opus 4.6).
+    def append_effort(cmd)
+      cmd.push("--effort", @options.effort.to_s) if @options.effort
+    end
+
+    def append_betas(cmd)
+      return unless @options.betas && !@options.betas.empty?
+
+      cmd.push("--betas", @options.betas.join(","))
+    end
+
+    def append_tools(cmd)
+      return if @options.tools.nil?
+
+      case @options.tools
+      when Array
+        tools_value = @options.tools.empty? ? "" : @options.tools.join(",")
+        cmd.push("--tools", tools_value)
+      when ToolsPreset
+        cmd.push("--tools", "default")
+      when Hash
+        if (@options.tools[:type] || @options.tools["type"]) == "preset"
+          cmd.push("--tools", "default")
+        else
+          cmd.push("--tools", JSON.generate(@options.tools))
+        end
+      end
+    end
+
+    def append_append_allowed_tools(cmd)
+      return unless @options.append_allowed_tools && !@options.append_allowed_tools.empty?
+
+      cmd.push("--append-allowed-tools", @options.append_allowed_tools.join(","))
+    end
+
+    def append_output_format(cmd)
+      return unless @options.output_format
+
+      schema = if @options.output_format.is_a?(Hash) && @options.output_format[:type] == "json_schema"
+                 @options.output_format[:schema]
+               elsif @options.output_format.is_a?(Hash) && @options.output_format["type"] == "json_schema"
+                 @options.output_format["schema"]
+               else
+                 @options.output_format
+               end
+      schema_json = schema.is_a?(String) ? schema : JSON.generate(schema)
+      cmd.push("--json-schema", schema_json)
+    end
+
+    def append_additional_dirs(cmd)
+      @options.add_dirs.each { |dir| cmd.push("--add-dir", dir.to_s) }
+    end
+
+    def append_mcp_servers(cmd)
+      return unless @options.mcp_servers && !@options.mcp_servers.empty?
+
+      if @options.mcp_servers.is_a?(Hash)
+        servers_for_cli = {}
+        @options.mcp_servers.each do |name, config|
+          servers_for_cli[name] = if config.is_a?(Hash) && config[:type] == "sdk"
+                                    config.except(:instance)
+                                  else
+                                    config
+                                  end
+        end
+        cmd.push("--mcp-config", JSON.generate({ mcpServers: servers_for_cli })) unless servers_for_cli.empty?
+      else
+        cmd.push("--mcp-config", @options.mcp_servers.to_s)
+      end
+    end
+
+    # NOTE: agents are sent via the initialize control request (not CLI args)
+    # to avoid OS ARG_MAX limits with large agent configurations.
+    def append_boolean_flags(cmd)
+      cmd.push("--include-partial-messages") if @options.include_partial_messages
+      cmd.push("--fork-session") if @options.fork_session
+      cmd.push("--bare") if @options.bare
+    end
+
+    def append_plugins(cmd)
+      return unless @options.plugins && !@options.plugins.empty?
+
+      @options.plugins.each do |plugin|
+        plugin_config = plugin.is_a?(SdkPluginConfig) ? plugin.to_h : plugin
+        plugin_type = plugin_config[:type] || plugin_config["type"]
+        plugin_path = plugin_config[:path] || plugin_config["path"]
+
+        raise ArgumentError, "Unsupported plugin type: #{plugin_type.inspect}" unless %w[local plugin].include?(plugin_type)
+        next unless plugin_path
+
+        cmd.push("--plugin-dir", plugin_path)
+      end
+    end
+
+    def append_setting_sources(cmd)
+      return unless @options.setting_sources
+
+      cmd.push("--setting-sources", @options.setting_sources.join(","))
+    end
+
+    def append_extra_args(cmd)
+      @options.extra_args.each do |flag, value|
+        raise ArgumentError, "Invalid extra_args flag name: #{flag.inspect} (expected lowercase kebab-case)" unless EXTRA_ARG_FLAG_REGEXP.match?(flag)
+
+        if value.nil?
+          cmd.push("--#{flag}")
+        else
+          cmd.push("--#{flag}", value.to_s)
+        end
+      end
+    end
+
+    def load_settings_file(path)
+      raise CLIConnectionError, "Settings file not found: #{path}" unless File.file?(path)
+
+      JSON.parse(File.read(path))
+    end
+  end
+end

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -6,13 +6,14 @@ require 'timeout'
 require_relative 'transport'
 require_relative 'errors'
 require_relative 'version'
+require_relative 'command_builder'
 
 module ClaudeAgentSDK
   # Subprocess transport using Claude Code CLI
   class SubprocessCLITransport < Transport
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
-    EXTRA_ARG_FLAG_RE = /\A[a-z0-9][a-z0-9-]*\z/
+    RECENT_STDERR_LINES_LIMIT = 20
 
     def initialize(options_or_prompt = nil, options = nil)
       # Support both new single-arg form and legacy two-arg form
@@ -67,126 +68,7 @@ module ClaudeAgentSDK
     end
 
     def build_command
-      cmd = [@cli_path, '--output-format', 'stream-json', '--verbose']
-
-      # System prompt handling
-      # When nil, pass empty string to ensure predictable behavior without default Claude Code system prompt
-      if @options.system_prompt.nil?
-        cmd.concat(['--system-prompt', ''])
-      elsif @options.system_prompt.is_a?(String)
-        cmd.concat(['--system-prompt', @options.system_prompt])
-      elsif @options.system_prompt.is_a?(SystemPromptFile)
-        cmd.concat(['--system-prompt-file', @options.system_prompt.path])
-      elsif @options.system_prompt.is_a?(SystemPromptPreset)
-        # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
-        # Only --append-system-prompt is passed if append text is provided
-        cmd.concat(['--append-system-prompt', @options.system_prompt.append]) if @options.system_prompt.append
-      elsif @options.system_prompt.is_a?(Hash)
-        prompt_type = @options.system_prompt[:type] || @options.system_prompt['type']
-        if prompt_type == 'file'
-          prompt_path = @options.system_prompt[:path] || @options.system_prompt['path']
-          cmd.concat(['--system-prompt-file', prompt_path]) if prompt_path
-        elsif prompt_type == 'preset'
-          append = @options.system_prompt[:append] || @options.system_prompt['append']
-          # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
-          cmd.concat(['--append-system-prompt', append]) if append
-        end
-      end
-
-      cmd.concat(['--allowedTools', @options.allowed_tools.join(',')]) unless @options.allowed_tools.empty?
-      cmd.concat(['--max-turns', @options.max_turns.to_s]) if @options.max_turns
-      cmd.concat(['--disallowedTools', @options.disallowed_tools.join(',')]) unless @options.disallowed_tools.empty?
-      cmd.concat(['--model', @options.model]) if @options.model
-      cmd.concat(['--fallback-model', @options.fallback_model]) if @options.fallback_model
-      cmd.concat(['--permission-prompt-tool', @options.permission_prompt_tool_name]) if @options.permission_prompt_tool_name
-      cmd.concat(['--permission-mode', @options.permission_mode]) if @options.permission_mode
-      cmd << '--continue' if @options.continue_conversation
-      cmd.concat(['--resume', @options.resume]) if @options.resume
-      cmd.concat(['--session-id', @options.session_id]) if @options.session_id
-
-      # Settings handling with sandbox merge
-      build_settings_args(cmd)
-
-      # Budget limit option
-      cmd.concat(['--max-budget-usd', @options.max_budget_usd.to_s]) if @options.max_budget_usd
-
-      # Task budget (API-side token budget)
-      if @options.task_budget
-        total = if @options.task_budget.is_a?(TaskBudget)
-                  @options.task_budget.total
-                else
-                  @options.task_budget[:total] || @options.task_budget['total']
-                end
-        cmd.concat(['--task-budget', total.to_s]) if total
-      end
-
-      # Thinking configuration (takes precedence over deprecated max_thinking_tokens)
-      build_thinking_args(cmd)
-
-      # Effort level — see ClaudeAgentSDK::EFFORT_LEVELS. The set of supported
-      # levels is model-dependent; the CLI falls back to the highest supported
-      # level at or below the one requested (e.g. `xhigh` → `high` on Opus 4.6).
-      cmd.concat(['--effort', @options.effort.to_s]) if @options.effort
-
-      # Betas option for enabling experimental features
-      if @options.betas && !@options.betas.empty?
-        cmd.concat(['--betas', @options.betas.join(',')])
-      end
-
-      # Tools option for base tools selection
-      build_tools_args(cmd)
-
-      # Append allowed tools option
-      if @options.append_allowed_tools && !@options.append_allowed_tools.empty?
-        cmd.concat(['--append-allowed-tools', @options.append_allowed_tools.join(',')])
-      end
-
-      # JSON schema for structured output
-      build_output_format_args(cmd)
-
-      # Add directories
-      @options.add_dirs.each do |dir|
-        cmd.concat(['--add-dir', dir.to_s])
-      end
-
-      # MCP servers
-      build_mcp_servers_args(cmd)
-
-      cmd << '--include-partial-messages' if @options.include_partial_messages
-      cmd << '--fork-session' if @options.fork_session
-      cmd << '--bare' if @options.bare
-
-      # Note: agents are now sent via the initialize control request (not CLI args)
-      # to avoid OS ARG_MAX limits with large agent configurations.
-
-      # Plugins
-      build_plugins_args(cmd)
-
-      # Setting sources
-      if @options.setting_sources
-        cmd.concat(['--setting-sources', @options.setting_sources.join(',')])
-      end
-
-      # Extra args
-      @options.extra_args.each do |flag, value|
-        flag_str = flag.to_s
-        unless EXTRA_ARG_FLAG_RE.match?(flag_str)
-          raise ArgumentError, "Invalid extra_args flag name: #{flag.inspect} (expected lowercase kebab-case)"
-        end
-
-        if value.nil?
-          cmd << "--#{flag_str}"
-        else
-          cmd.concat(["--#{flag_str}", value.to_s])
-        end
-      end
-
-      # Always use streaming mode for bidirectional control protocol.
-      # Prompts and agents are sent via stdin (initialize + user messages),
-      # which avoids OS ARG_MAX limits for large prompts and agent configurations.
-      cmd.concat(['--input-format', 'stream-json'])
-
-      cmd
+      CommandBuilder.new(@cli_path, @options).build
     end
 
     def connect
@@ -264,11 +146,7 @@ module ClaudeAgentSDK
         line_str = line.chomp
         next if line_str.empty?
 
-        # Accumulate recent lines for inclusion in ProcessError
-        @recent_stderr_mutex.synchronize do
-          @recent_stderr << line_str
-          @recent_stderr.shift if @recent_stderr.size > 20
-        end
+        record_bounded_stderr(line_str)
 
         # Call stderr callback if provided
         @options.stderr&.call(line_str)
@@ -293,10 +171,7 @@ module ClaudeAgentSDK
         line_str = line.chomp
         next if line_str.empty?
 
-        @recent_stderr_mutex.synchronize do
-          @recent_stderr << line_str
-          @recent_stderr.shift if @recent_stderr.size > 20
-        end
+        record_bounded_stderr(line_str)
       end
     end
 
@@ -401,7 +276,6 @@ module ClaudeAgentSDK
     def write(data)
       raise CLIConnectionError, 'ProcessTransport is not ready for writing' unless @ready && @stdin
       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
 
       begin
@@ -517,119 +391,13 @@ module ClaudeAgentSDK
 
     private
 
-    def build_settings_args(cmd)
-      return unless @options.settings || @options.sandbox
-
-      settings_hash = {}
-      settings_is_path = false
-
-      if @options.settings
-        if @options.settings.is_a?(String)
-          begin
-            settings_hash = JSON.parse(@options.settings)
-          rescue JSON::ParserError
-            if @options.sandbox
-              settings_hash = load_settings_file(@options.settings)
-            else
-              settings_is_path = true
-              cmd.concat(['--settings', @options.settings])
-            end
-          end
-        elsif @options.settings.is_a?(Hash)
-          settings_hash = @options.settings.dup
-        end
-      end
-
-      if !settings_is_path && @options.sandbox
-        sandbox_hash = @options.sandbox.is_a?(SandboxSettings) ? @options.sandbox.to_h : @options.sandbox
-        settings_hash[:sandbox] = sandbox_hash unless sandbox_hash.empty?
-      end
-
-      cmd.concat(['--settings', JSON.generate(settings_hash)]) if !settings_is_path && !settings_hash.empty?
-    end
-
-    def build_tools_args(cmd)
-      return if @options.tools.nil?
-
-      if @options.tools.is_a?(Array)
-        tools_value = @options.tools.empty? ? '' : @options.tools.join(',')
-        cmd.concat(['--tools', tools_value])
-      elsif @options.tools.is_a?(ToolsPreset)
-        cmd.concat(['--tools', 'default'])
-      elsif @options.tools.is_a?(Hash)
-        if (@options.tools[:type] || @options.tools['type']) == 'preset'
-          cmd.concat(['--tools', 'default'])
-        else
-          cmd.concat(['--tools', JSON.generate(@options.tools)])
-        end
-      end
-    end
-
-    def build_output_format_args(cmd)
-      return unless @options.output_format
-
-      schema = if @options.output_format.is_a?(Hash) && @options.output_format[:type] == 'json_schema'
-                 @options.output_format[:schema]
-               elsif @options.output_format.is_a?(Hash) && @options.output_format['type'] == 'json_schema'
-                 @options.output_format['schema']
-               else
-                 @options.output_format
-               end
-      schema_json = schema.is_a?(String) ? schema : JSON.generate(schema)
-      cmd.concat(['--json-schema', schema_json])
-    end
-
-    def build_mcp_servers_args(cmd)
-      return unless @options.mcp_servers && !@options.mcp_servers.empty?
-
-      if @options.mcp_servers.is_a?(Hash)
-        servers_for_cli = {}
-        @options.mcp_servers.each do |name, config|
-          servers_for_cli[name] = if config.is_a?(Hash) && config[:type] == 'sdk'
-                                    config.reject { |k, _| k == :instance }
-                                  else
-                                    config
-                                  end
-        end
-        cmd.concat(['--mcp-config', JSON.generate({ mcpServers: servers_for_cli })]) unless servers_for_cli.empty?
-      else
-        cmd.concat(['--mcp-config', @options.mcp_servers.to_s])
-      end
-    end
-
-    def build_plugins_args(cmd)
-      return unless @options.plugins && !@options.plugins.empty?
-
-      @options.plugins.each do |plugin|
-        plugin_config = plugin.is_a?(SdkPluginConfig) ? plugin.to_h : plugin
-        plugin_type = plugin_config[:type] || plugin_config['type']
-        plugin_path = plugin_config[:path] || plugin_config['path']
-
-        raise ArgumentError, "Unsupported plugin type: #{plugin_type.inspect}" unless %w[local plugin].include?(plugin_type)
-        next unless plugin_path
-
-        cmd.concat(['--plugin-dir', plugin_path])
-      end
-    end
-
-    def load_settings_file(path)
-      raise CLIConnectionError, "Settings file not found: #{path}" unless File.file?(path)
-
-      JSON.parse(File.read(path))
-    end
-
-    def build_thinking_args(cmd)
-      if @options.thinking
-        case @options.thinking
-        when ThinkingConfigAdaptive
-          cmd.concat(['--thinking', 'adaptive'])
-        when ThinkingConfigEnabled
-          cmd.concat(['--max-thinking-tokens', @options.thinking.budget_tokens.to_s])
-        when ThinkingConfigDisabled
-          cmd.concat(['--thinking', 'disabled'])
-        end
-      elsif @options.max_thinking_tokens
-        cmd.concat(['--max-thinking-tokens', @options.max_thinking_tokens.to_s])
+    # Append a stderr line to the recent-stderr ring, dropping the oldest
+    # entry once the buffer exceeds RECENT_STDERR_LINES_LIMIT. Used to surface the
+    # last few lines in ProcessError when the CLI exits non-zero.
+    def record_bounded_stderr(line)
+      @recent_stderr_mutex.synchronize do
+        @recent_stderr << line
+        @recent_stderr.shift if @recent_stderr.size > RECENT_STDERR_LINES_LIMIT
       end
     end
   end

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.16.3
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -104,6 +104,7 @@ files:
 - LICENSE
 - README.md
 - lib/claude_agent_sdk.rb
+- lib/claude_agent_sdk/command_builder.rb
 - lib/claude_agent_sdk/configuration.rb
 - lib/claude_agent_sdk/errors.rb
 - lib/claude_agent_sdk/fiber_boundary.rb