claude-agent-sdk 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db31632430bb28dc8f07903bfc8634a8c437da9dc988f2237606948ecc71f7e0
-  data.tar.gz: e7574810137063aef37a0a78fb9d855645a0a479ba0b909b63a491f0ea7060f6
+  metadata.gz: acfb2780cc551ed4ff8cd1d96286636dd2d8d24b1ca3d34b93eadf15d1bbf49c
+  data.tar.gz: b3857039975c72fbf730e261831783db37efd00706bf30b2863b2feeceb58b3a
 SHA512:
-  metadata.gz: e394102a18bace179f7745b2b10cc721393ff25e8dcbc75f9492e6822aa6a80afa1455eb168b6567857cbf10a7d1d2e96e7293e43b043ad69ac2b41f95a3eb99
-  data.tar.gz: 03b94423b5d2369eb974e9cf82b2523e36aea4a09d05181e86528da11b3432d8685256705989210941b644333b5f9d3173b2efa0fd3b5f1b74e5e5aea3705bc6
+  metadata.gz: fa211da2013526662038143ed0cc7e04639a1821e5de8fdd7a6cc305f4d30fe495dd7b827796fd6e85e98612c61df2335120cbd2938a74736b1d31840719cf0f
+  data.tar.gz: 1bf84df24c779a99dbeeea776e00e53dc131bb2aca21a3bb2658ea7c3a972222bbfb0abef7d0ef48ec402490bd992074b82d7f806b8c3a98eb616f9d76421d20

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-02-07
+
+### Added
+- **Default configuration:** `ClaudeAgentSDK.configure` block for setting default options that merge with every `ClaudeAgentOptions` instance, ideal for Rails initializers (PR #8)
+- `ClaudeAgentSDK.reset_configuration` for resetting defaults (useful in tests)
+- Deep merge for `env` and `mcp_servers` hashes; provided values override configured defaults
+- `OPTION_DEFAULTS` constant on `ClaudeAgentOptions` for introspectable non-nil defaults
+
+### Changed
+- `ClaudeAgentOptions#initialize` now uses `**kwargs` internally to correctly distinguish caller-provided values from method signature defaults
+
 ## [0.4.2] - 2026-02-07
 
 ### Fixed

data/README.md

@@ -38,7 +38,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.4.0'
+gem 'claude-agent-sdk', '~> 0.5.0'
 ```
 
 And then execute:

data/lib/claude_agent_sdk/configuration.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ClaudeAgentSDK
+  # Configuration class for setting default options
+  #
+  # Use this to set default options that will be merged with every request.
+  # This is especially useful in Rails applications where you want to
+  # configure defaults once during initialization.
+  #
+  # @example In a Rails initializer (config/initializers/claude_agent_sdk.rb)
+  #   ClaudeAgentSDK.configure do |config|
+  #     config.default_options = {
+  #       env: {
+  #         'ANTHROPIC_API_KEY' => ENV['ANTHROPIC_API_KEY'],
+  #         'CUSTOM_VAR' => 'value'
+  #       },
+  #       permission_mode: 'bypassPermissions',
+  #       model: 'sonnet'
+  #     }
+  #   end
+  #
+  # @example Then use ClaudeAgentSDK without repeating options
+  #   # env and other defaults will be automatically applied
+  #   ClaudeAgentSDK.query(prompt: "Hello!")
+  #
+  #   # You can still override defaults when needed
+  #   ClaudeAgentSDK.query(
+  #     prompt: "Hello!",
+  #     options: ClaudeAgentOptions.new(model: 'opus')  # overrides default
+  #   )
+  class Configuration
+    attr_accessor :default_options
+
+    def initialize
+      @default_options = {}
+    end
+  end
+
+  class << self
+    # Configure the SDK with default options
+    #
+    # @yield [Configuration] The configuration object
+    #
+    # @example Set default env and other options
+    #   ClaudeAgentSDK.configure do |config|
+    #     config.default_options = {
+    #       env: { 'API_KEY' => 'xxx' },
+    #       permission_mode: 'bypassPermissions'
+    #     }
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Get the configuration object
+    #
+    # @return [Configuration] The current configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset configuration to defaults (useful for testing)
+    def reset_configuration
+      @configuration = Configuration.new
+    end
+
+    # Get merged default options for use with ClaudeAgentOptions
+    #
+    # @return [Hash] Default options hash
+    def default_options
+      configuration.default_options || {}
+    end
+  end
+end

data/lib/claude_agent_sdk/types.rb

@@ -784,87 +784,62 @@ module ClaudeAgentSDK
                   :fallback_model, :plugins, :debug_stderr,
                   :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools
 
-    def initialize(
-      allowed_tools: [],
-      system_prompt: nil,
-      mcp_servers: {},
-      permission_mode: nil,
-      continue_conversation: false,
-      resume: nil,
-      max_turns: nil,
-      disallowed_tools: [],
-      model: nil,
-      permission_prompt_tool_name: nil,
-      cwd: nil,
-      cli_path: nil,
-      settings: nil,
-      add_dirs: [],
-      env: {},
-      extra_args: {},
-      max_buffer_size: nil,
-      stderr: nil,
-      can_use_tool: nil,
-      hooks: nil,
-      user: nil,
-      include_partial_messages: false,
-      fork_session: false,
-      agents: nil,
-      setting_sources: nil,
-      output_format: nil,
-      max_budget_usd: nil,
-      max_thinking_tokens: nil,
-      fallback_model: nil,
-      plugins: nil,
-      debug_stderr: nil,
-      betas: nil,
-      tools: nil,
-      sandbox: nil,
-      enable_file_checkpointing: false,
-      append_allowed_tools: nil
-    )
-      @allowed_tools = allowed_tools
-      @system_prompt = system_prompt
-      @mcp_servers = mcp_servers
-      @permission_mode = permission_mode
-      @continue_conversation = continue_conversation
-      @resume = resume
-      @max_turns = max_turns
-      @disallowed_tools = disallowed_tools
-      @model = model
-      @permission_prompt_tool_name = permission_prompt_tool_name
-      @cwd = cwd
-      @cli_path = cli_path
-      @settings = settings
-      @add_dirs = add_dirs
-      @env = env
-      @extra_args = extra_args
-      @max_buffer_size = max_buffer_size
-      @stderr = stderr
-      @can_use_tool = can_use_tool
-      @hooks = hooks
-      @user = user
-      @include_partial_messages = include_partial_messages
-      @fork_session = fork_session
-      @agents = agents
-      @setting_sources = setting_sources
-      @output_format = output_format # JSON schema for structured output
-      @max_budget_usd = max_budget_usd # Spending cap in dollars
-      @max_thinking_tokens = max_thinking_tokens # Extended thinking token budget
-      @fallback_model = fallback_model # Backup model if primary unavailable
-      @plugins = plugins # Array of SdkPluginConfig
-      @debug_stderr = debug_stderr # Debug output file object/path
-      @betas = betas # Array of beta feature strings (e.g., ["context-1m-2025-08-07"])
-      @tools = tools # Base tools selection: Array, empty array [], or ToolsPreset
-      @sandbox = sandbox # SandboxSettings instance for isolated command execution
-      @enable_file_checkpointing = enable_file_checkpointing # Enable file checkpointing for rewind support
-      @append_allowed_tools = append_allowed_tools # Array of tools to append to allowed_tools
+    # Non-nil defaults for options that need them.
+    # Keys absent from here default to nil.
+    OPTION_DEFAULTS = {
+      allowed_tools: [], disallowed_tools: [], add_dirs: [],
+      mcp_servers: {}, env: {}, extra_args: {},
+      continue_conversation: false, include_partial_messages: false,
+      fork_session: false, enable_file_checkpointing: false
+    }.freeze
+
+    # Valid option names derived from attr_accessor declarations.
+    VALID_OPTIONS = instance_methods.grep(/=\z/).map { |m| m.to_s.chomp('=').to_sym }.freeze
+
+    # Using **kwargs lets us distinguish "caller passed allowed_tools: []"
+    # from "caller omitted allowed_tools" — critical for correct merge with
+    # configured defaults.
+    def initialize(**kwargs)
+      unknown = kwargs.keys - VALID_OPTIONS
+      raise ArgumentError, "unknown keyword#{'s' if unknown.size > 1}: #{unknown.join(', ')}" if unknown.any?
+
+      merged = merge_with_defaults(kwargs)
+      OPTION_DEFAULTS.merge(merged).each do |key, value|
+        instance_variable_set(:"@#{key}", value)
+      end
     end
 
     def dup_with(**changes)
       new_options = self.dup
-      changes.each { |key, value| new_options.send("#{key}=", value) }
+      changes.each { |key, value| new_options.send(:"#{key}=", value) }
       new_options
     end
+
+    private
+
+    # Merge caller-provided kwargs with configured defaults.
+    # Only keys the caller explicitly passed are treated as overrides;
+    # method-signature defaults ([], {}, false) are NOT in kwargs unless the caller wrote them.
+    def merge_with_defaults(kwargs)
+      return OPTION_DEFAULTS.merge(kwargs) unless defined?(ClaudeAgentSDK) && ClaudeAgentSDK.respond_to?(:default_options)
+
+      defaults = ClaudeAgentSDK.default_options
+      return OPTION_DEFAULTS.merge(kwargs) unless defaults.any?
+
+      # Start from configured defaults (deep dup hashes to prevent mutation)
+      result = defaults.transform_values { |v| v.is_a?(Hash) ? v.dup : v }
+      kwargs.each do |key, value|
+        default_val = result[key]
+        result[key] = if value.nil?
+                        default_val # nil means "no preference" — keep the configured default
+                      elsif default_val.is_a?(Hash) && value.is_a?(Hash)
+                        default_val.merge(value)
+                      else
+                        value
+                      end
+      end
+      OPTION_DEFAULTS.merge(result)
+    end
   end
 
   # SDK MCP Tool definition

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -2,6 +2,7 @@
 
 require_relative 'claude_agent_sdk/version'
 require_relative 'claude_agent_sdk/errors'
+require_relative 'claude_agent_sdk/configuration'
 require_relative 'claude_agent_sdk/types'
 require_relative 'claude_agent_sdk/transport'
 require_relative 'claude_agent_sdk/subprocess_cli_transport'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Community Contributors
@@ -104,6 +104,7 @@ files:
 - LICENSE
 - README.md
 - lib/claude_agent_sdk.rb
+- lib/claude_agent_sdk/configuration.rb
 - lib/claude_agent_sdk/errors.rb
 - lib/claude_agent_sdk/message_parser.rb
 - lib/claude_agent_sdk/query.rb