claude-agent-sdk 1.1.0 → 1.2.0

data/lib/claude_agent_sdk/types/options.rb

@@ -18,8 +18,10 @@ module ClaudeAgentSDK
 
   # Claude Agent Options for configuring queries
   class ClaudeAgentOptions < Type
-    # `env` routinely carries credentials (ANTHROPIC_API_KEY, ...).
-    inspect_filtered :env
+    # `env` routinely carries credentials (ANTHROPIC_API_KEY, ...). So does
+    # `settings` (its own `env`, `apiKeyHelper`), as a Hash or a JSON String,
+    # and an `extra_args` value can be one.
+    inspect_filtered :env, :settings, :extra_args
 
     attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
                   :resume, :resume_session_at, :session_id, :max_turns, :disallowed_tools,
@@ -345,16 +347,44 @@ module ClaudeAgentSDK
       self.callback_scheduling = :thread if callback_scheduling.nil?
     end
 
+    # `mcp_servers` holds typed configs, which filter themselves, next to raw
+    # Hash configs carrying the same credentials: those are rendered by
+    # Type#inspect_mcp_server_config. Anything but a Hash (the JSON of a
+    # config as a String, or the path to one) is replaced outright, like a
+    # String `settings`.
+    def inspect_attributes
+      super.map { |name, value| [name, name == 'mcp_servers' ? inspect_mcp_servers(value) : value] }
+    end
+
+    def inspect_mcp_servers(servers)
+      return '[FILTERED]' unless servers.is_a?(Hash)
+
+      servers.to_h { |name, config| [name, config.is_a?(Hash) ? inspect_mcp_server_config(config) : config] }
+    rescue StandardError
+      '[FILTERED]'
+    end
+
     # Strict key validation: unlike other Type subclasses (which silently drop
     # unknown keys for forward-compat with newer CLI output), ClaudeAgentOptions
     # is a developer-facing config object — typos should fail loudly.
     def assign_attribute(name, value)
-      setter = :"#{normalize_name(name)}="
-      raise ArgumentError, "unknown ClaudeAgentOptions option: #{name.inspect}" unless respond_to?(setter)
+      setter = option_setter(normalize_name(name))
+      raise ArgumentError, "unknown ClaudeAgentOptions option: #{name.inspect}" unless setter
 
       public_send(setter, value)
     end
 
+    # The writer of the option with this normalized name, nil when the name
+    # is not an option. An option is a declared attribute, or a setter user
+    # code defined (on a subclass, a module it includes, or the object);
+    # respond_to? alone would also answer for '[]' (#[]=) and '=' (#==).
+    def option_setter(normalized)
+      setter = :"#{normalized}="
+      return unless respond_to?(setter)
+
+      setter if self.class.attribute?(normalized) || user_defined_method?(setter)
+    end
+
     # Merge caller-provided attributes with configured defaults.
     # Only keys the caller explicitly passed are treated as overrides;
     # method-signature defaults ([], {}, false) are NOT present unless the caller wrote them.
@@ -403,7 +433,7 @@ module ClaudeAgentSDK
     # reports the typo exactly as the developer wrote it.
     def option_key(name)
       normalized = normalize_name(name)
-      respond_to?(:"#{normalized}=") ? normalized.to_sym : name
+      option_setter(normalized) ? normalized.to_sym : name
     end
   end
 end

data/lib/claude_agent_sdk/types/permissions.rb

@@ -34,20 +34,21 @@ module ClaudeAgentSDK
       @rules = value&.map { |rule| rule.is_a?(Hash) ? PermissionRuleValue.new(rule) : rule }
     end
 
+    # The wire form. The CLI validates the updatedPermissions of a
+    # can_use_tool reply as one unit and drops the whole array when a single
+    # entry does not fit its schema, so two things it rejects are never
+    # written: a rule without content has no ruleContent key (the schema
+    # wants a String or no key, not null), and an update that has a type but
+    # no destination goes to 'session' — the narrowest one: it lasts for this
+    # run and writes no settings file (the default Python PR #1330 proposes).
     def to_h
       result = { type: @type }
-      result[:destination] = @destination if @destination
+      destination = @destination || ('session' unless @type.nil?)
+      result[:destination] = destination if destination
 
       case @type
       when 'addRules', 'replaceRules', 'removeRules'
-        if @rules
-          result[:rules] = @rules.map do |rule|
-            {
-              toolName: rule.tool_name,
-              ruleContent: rule.rule_content
-            }
-          end
-        end
+        result[:rules] = @rules.map { |rule| rule_to_h(rule) } if @rules
         result[:behavior] = @behavior if @behavior
       when 'setMode'
         result[:mode] = @mode if @mode
@@ -57,6 +58,14 @@ module ClaudeAgentSDK
 
       result
     end
+
+    private
+
+    def rule_to_h(rule)
+      wire_rule = { toolName: rule.tool_name }
+      wire_rule[:ruleContent] = rule.rule_content unless rule.rule_content.nil?
+      wire_rule
+    end
   end
 
   # Tool permission context delivered to `can_use_tool` callbacks.

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -79,7 +79,10 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
   end
 
   # Internal: normalize hook lists for the control protocol. An absent or
-  # disabled event must not become an empty registration in initialize.
+  # disabled event must not become an empty registration in initialize. An
+  # event written as a String under one key and as a Symbol under another
+  # ('PreToolUse' and :PreToolUse) is one event: its matcher lists are
+  # joined in the order they were written, never replaced.
   # @api private
   def self.convert_hooks_to_internal_format(hooks)
     return nil unless hooks
@@ -94,7 +97,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
         config[:timeout] = matcher.timeout if matcher.timeout
         entries << config
       end
-      internal_hooks[event.to_s] = entries unless entries.empty?
+      (internal_hooks[event.to_s] ||= []).concat(entries) unless entries.empty?
     end
     internal_hooks.empty? ? nil : internal_hooks
   end
@@ -139,7 +142,8 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
       eds = system_prompt.exclude_dynamic_sections
       return eds if [true, false].include?(eds)
     elsif system_prompt.is_a?(Hash)
-      type = system_prompt[:type] || system_prompt['type']
+      # The tag may be a Symbol (type: :preset), as CommandBuilder reads it.
+      type = (system_prompt[:type] || system_prompt['type']).to_s
       if type == 'preset'
         eds = system_prompt.fetch(:exclude_dynamic_sections) { system_prompt['exclude_dynamic_sections'] }
         return eds if [true, false].include?(eds)
@@ -160,7 +164,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
       snapshot = system_prompt.snapshot
       return snapshot if [true, false].include?(snapshot)
     when Hash
-      type = system_prompt[:type] || system_prompt['type']
+      type = (system_prompt[:type] || system_prompt['type']).to_s
       if %w[preset custom].include?(type)
         snapshot = system_prompt.fetch(:snapshot) { system_prompt['snapshot'] }
         return snapshot if [true, false].include?(snapshot)
@@ -173,14 +177,39 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
   # Each observer is invoked through FiberBoundary so that user code runs
   # on a plain thread (no Fiber scheduler) even when called from inside
   # the SDK's Async reactor — or in place when scheduling is :inline.
+  #
+  # What the observer raises, and what its callback_wrapper raises, is
+  # contained where it happens: inside the hop, on the execution context
+  # the observer runs on. The rescue must not sit around the hop, because
+  # the calling fiber WAITS there, and an exception raised into a waiting
+  # fiber is not the observer's — a caller's `task.with_timeout` /
+  # `Timeout.timeout` deadline is delivered exactly that way. Rescued out
+  # here, an expired deadline was swallowed as if the observer had failed,
+  # and the turn carried on. So the wrapper is composed inside the rescued
+  # body rather than handed to FiberBoundary.invoke, which would run it
+  # outside that rescue.
+  #
+  # Known residue with `scheduling: :inline` (and with no scheduler at all):
+  # the observer runs on the calling fiber itself, so a deadline that lands
+  # while the observer is suspended is raised inside the observer's own
+  # frames, cannot be told from the observer's own timeout, and is still
+  # swallowed here.
   # @api private
   def self.notify_observers(observers, method, *args, scheduling: :thread, wrapper: nil)
     observers.each do |obs|
-      FiberBoundary.invoke(scheduling: scheduling, wrapper: wrapper) { obs.send(method, *args) }
-    rescue StandardError, ScriptError
-      # ScriptError too: NotImplementedError < ScriptError (not
-      # StandardError), and a stubbed observer must never mask the original
-      # error being notified or abort connect/teardown cleanup.
+      FiberBoundary.invoke(scheduling: scheduling) do
+        invocation = proc { obs.send(method, *args) }
+        wrapper ? wrapper.call(invocation) : invocation.call
+      rescue StandardError, ScriptError
+        # ScriptError too: NotImplementedError < ScriptError (not
+        # StandardError), and a stubbed observer must never mask the original
+        # error being notified or abort connect/teardown cleanup.
+        nil
+      end
+    rescue ScriptError
+      # A ScriptError raised around the body rather than in it (the hop's own
+      # plumbing). No deadline is a ScriptError, so nothing a caller injects
+      # into the waiting fiber is caught here.
       nil
     end
   end
@@ -703,7 +732,14 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
       raise ArgumentError, 'transport must respond to #connect (see ClaudeAgentSDK::Transport)'
     end
 
-    Async(&FiberBoundary.capture_otel_context do # rubocop:disable Metrics/BlockLength -- the reactor task body of query()
+    # finished: false tells Async that a waiter handles this task's failure
+    # (the .wait at the end re-raises it), as Kernel#Sync does for its own
+    # task. Without it a task that fails before anyone waits for it — always
+    # the case outside a reactor, where Async runs the whole task before it
+    # returns — is also logged as "Task may have ended with unhandled
+    # exception", message and backtrace included, although the caller gets
+    # the same error raised and may well rescue it.
+    Async(finished: false, &FiberBoundary.capture_otel_context do # rubocop:disable Metrics/BlockLength -- the reactor task body of query()
       materialized = nil
       query_handler = nil
       begin
@@ -903,16 +939,13 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
   # The Client class always uses streaming mode for bidirectional communication.
   #
   # @example Basic usage
-  #   Async do
-  #     client = ClaudeAgentSDK::Client.new
-  #     client.connect  # No arguments needed - automatically uses streaming mode
-  #
+  #   # Client.open connects, yields the client and always disconnects,
+  #   # also when the block raises.
+  #   ClaudeAgentSDK::Client.open do |client|
   #     client.query("What is the capital of France?")
   #     client.receive_response do |msg|
   #       puts msg if msg.is_a?(ClaudeAgentSDK::AssistantMessage)
   #     end
-  #
-  #     client.disconnect
   #   end
   #
   # @example With hooks
@@ -1043,17 +1076,22 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
         # (The enumerator branch streams in the background and cannot raise
         # out of connect.) No on_close follows for pre-handshake failures
         # (disconnect gates it on @connected): the session never opened.
-        notify_error(e) if e.is_a?(StandardError) && !@connected
-        # Tear down the partial connect, but never let a cleanup failure (e.g. a
-        # custom transport whose #close raises) mask the original connect error.
-        # Rescue Exception (not StandardError) so reactor cancellation
-        # (Async::Stop < Exception) after materialize_resume set @materialized
-        # still runs disconnect -> @materialized.cleanup, never leaking the temp
-        # CLAUDE_CONFIG_DIR that holds the redacted .credentials.json copy.
         begin
-          disconnect
-        rescue StandardError => cleanup_error
-          warn "Claude SDK: cleanup after failed connect raised: #{cleanup_error.message}"
+          notify_error(e) if e.is_a?(StandardError) && !@connected
+        ensure
+          # Tear down the partial connect, but never let a cleanup failure (e.g. a
+          # custom transport whose #close raises) mask the original connect error.
+          # Rescue Exception (not StandardError) so reactor cancellation
+          # (Async::Stop < Exception) after materialize_resume set @materialized
+          # still runs disconnect -> @materialized.cleanup, never leaking the temp
+          # CLAUDE_CONFIG_DIR that holds the redacted .credentials.json copy.
+          # In an ensure: an exception raised into this fiber while it waits
+          # for the on_error observer (a caller's deadline) must not skip it.
+          begin
+            disconnect
+          rescue StandardError => cleanup_error
+            warn "Claude SDK: cleanup after failed connect raised: #{cleanup_error.message}"
+          end
         end
         raise
       end
@@ -1314,11 +1352,11 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
     # holds, in every scheduling mode, for a streaming-input enumerator that
     # calls disconnect: it is iterated on the reactor inside a task the close
     # stops, so it unwinds with Async::Stop once the teardown has completed.
+    #
+    # Interrupted while an observer's on_close runs — the caller's deadline
+    # expires, or its task is stopped — disconnect still completes the
+    # teardown, then lets the interruption propagate.
     def disconnect
-      if @connected
-        ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close,
-                                        scheduling: @callback_scheduling, wrapper: @callback_wrapper)
-      end
       # Tear down whatever exists — robust to a partial/failed connect, where
       # @connected is still false but a transport and/or materialized temp dir
       # were already created. #close on the query handler also closes the
@@ -1335,26 +1373,36 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
       # and the materialized-dir decision at the bottom needs to ask it.
       query_handler = @query_handler
       begin
-        @query_handler&.close
+        # Notified inside the begin: an exception raised into this fiber while
+        # it waits for an observer (a caller's deadline) propagates, and must
+        # not skip the teardown below.
+        if @connected
+          ClaudeAgentSDK.notify_observers(@resolved_observers || [], :on_close,
+                                          scheduling: @callback_scheduling, wrapper: @callback_wrapper)
+        end
       ensure
-        @query_handler = nil
         begin
-          @transport&.close
+          @query_handler&.close
         ensure
-          @transport = nil
-          @connected = false
-          # Remove the materialized resume temp dir AFTER the subprocess
-          # exited — unless the mirror dropped batches: the store copy is then
-          # incomplete and the temp dir holds the only copy of the dropped
-          # turns, so it is preserved (scrubbed of credentials) with a warning
-          # instead of deleted.
-          if @materialized
-            if query_handler&.mirror_batches_dropped?
-              @materialized.preserve_transcripts
-            else
-              @materialized.cleanup
+          @query_handler = nil
+          begin
+            @transport&.close
+          ensure
+            @transport = nil
+            @connected = false
+            # Remove the materialized resume temp dir AFTER the subprocess
+            # exited — unless the mirror dropped batches: the store copy is then
+            # incomplete and the temp dir holds the only copy of the dropped
+            # turns, so it is preserved (scrubbed of credentials) with a warning
+            # instead of deleted.
+            if @materialized
+              if query_handler&.mirror_batches_dropped?
+                @materialized.preserve_transcripts
+              else
+                @materialized.cleanup
+              end
+              @materialized = nil
             end
-            @materialized = nil
           end
         end
       end

data/lib/generators/claude_agent_sdk/install/templates/claude_agent_sdk.rb.tt

@@ -22,6 +22,12 @@ ClaudeAgentSDK.configure do |config|
     # whatever the process cwd. To run a binary from somewhere else instead:
     # cli_path: '/usr/local/bin/claude',
 
+    # Multi-user apps: turn off the CLI's auto-memory — kept per project
+    # directory, read by every session and written by claude_code-preset
+    # sessions, so one user's "remember ..." reaches all others (the value
+    # must stay '1'; '0' forces it on). See docs/rails.md ("Per-user isolation").
+    # env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' },
+
     # OpenTelemetry tracing (Langfuse, Honeycomb, ...). A factory lambda gives
     # every query/session its own observer — safe under Puma and job threads.
     # observers: [-> { ClaudeAgentSDK::Instrumentation::OTelObserver.new }],

data/sig/claude_agent_sdk/types/hooks.rbs

@@ -47,8 +47,9 @@ module ClaudeAgentSDK
                             | CwdChangedHookSpecificOutput
                             | FileChangedHookSpecificOutput
 
-  # What a hook callback returns: a Hash (snake_case or camelCase keys), a
-  # typed output, or nil (treated as {}).
+  # What a hook callback returns: a Hash (Symbol or String keys, snake_case
+  # or camelCase, also inside hook_specific_output), a typed output, or nil
+  # (treated as {}).
   type hook_output = Hash[Symbol | String, untyped] | SyncHookJSONOutput | AsyncHookJSONOutput | nil
 
   # A hook callback (HookMatcher#hooks entries). tool_use_id is nil for
@@ -520,7 +521,9 @@ module ClaudeAgentSDK
 
     attr_accessor reason: String?
 
-    # A typed output, or the equivalent Hash (camelCase wire keys, sent as-is).
+    # A typed output, or the equivalent Hash (snake_case or camelCase keys).
+    # #to_h returns a Hash as written; the SDK puts its keys in wire spelling
+    # when it sends the output.
     attr_accessor hook_specific_output: (hook_specific_output | Hash[Symbol | String, untyped])?
 
     def to_h: () -> Hash[Symbol, untyped]

data/sig/claude_agent_sdk/types/option_values.rbs

@@ -7,6 +7,16 @@ module ClaudeAgentSDK
   # the Hash form (String or camelCase keys, e.g. `klass.new(value.to_h)`)
   # is accepted too. An unknown key raises ArgumentError. Discriminators
   # (`type`) are fixed by the class and read-only.
+  #
+  # The keyword overload documents the accepted keys and their types; no
+  # type checker enforces it. `klass.new(typo: 1)` is also a Symbol-keyed
+  # Hash, which the second overload accepts whatever its keys and values, so
+  # Steep reports neither a misspelled keyword nor a wrong value type, and
+  # the runtime checker behind `rake rbs:test` never reports a constructor
+  # mismatch (it only checks the attribute setters the constructor calls).
+  # The enforcement is the ArgumentError the constructor raises at runtime
+  # for an unknown key. This holds for every constructor in sig/ that has
+  # both overloads.
 
   # Adaptive thinking: the model decides when and how much to think.
   class ThinkingConfigAdaptive < Type
@@ -81,15 +91,15 @@ module ClaudeAgentSDK
 
   # A local plugin directory (ClaudeAgentOptions#plugins entries).
   class SdkPluginConfig < Type
-    def initialize: (?path: String?) -> void
+    def initialize: (?path: (String | Pathname)?) -> void
                   | (Hash[Symbol | String, untyped]? attributes) -> void
 
-    attr_accessor path: String?
+    attr_accessor path: (String | Pathname)?
 
     # "local".
     attr_reader type: String
 
-    def to_h: () -> { type: String, path: String? }
+    def to_h: () -> { type: String, path: (String | Pathname)? }
   end
 
   class SandboxNetworkConfig < Type
@@ -138,6 +148,13 @@ module ClaudeAgentSDK
 
   # Sandbox settings for isolated command execution
   # (ClaudeAgentOptions#sandbox).
+  #
+  # network / filesystem take the typed config or a Hash. A Hash may spell
+  # the fields of the typed class in snake_case or in the CLI's camelCase,
+  # with Symbol or String keys; other keys are sent as written. A snake_case
+  # key is sent under the CLI's name only when its value has the shape the
+  # CLI accepts for it; otherwise it is sent as written, which the CLI
+  # ignores.
   class SandboxSettings < Type
     def initialize: (?enabled: bool?, ?fail_if_unavailable: bool?, ?auto_allow_bash_if_sandboxed: bool?, ?excluded_commands: Array[String]?, ?allow_unsandboxed_commands: bool?, ?network: (SandboxNetworkConfig | Hash[Symbol | String, untyped])?, ?filesystem: (SandboxFilesystemConfig | Hash[Symbol | String, untyped])?, ?ignore_violations: Hash[Symbol | String, Array[String]]?, ?enable_weaker_nested_sandbox: bool?, ?enable_weaker_network_isolation: bool?, ?ripgrep: Hash[Symbol | String, untyped]?) -> void
                   | (Hash[Symbol | String, untyped]? attributes) -> void
@@ -181,15 +198,15 @@ module ClaudeAgentSDK
 
   # A system prompt loaded from a file.
   class SystemPromptFile < Type
-    def initialize: (?path: String?) -> void
+    def initialize: (?path: (String | Pathname)?) -> void
                   | (Hash[Symbol | String, untyped]? attributes) -> void
 
-    attr_accessor path: String?
+    attr_accessor path: (String | Pathname)?
 
     # "file".
     attr_reader type: String
 
-    def to_h: () -> { type: String, path: String? }
+    def to_h: () -> { type: String, path: (String | Pathname)? }
   end
 
   # The Claude Code preset system prompt, optionally extended.

data/sig/claude_agent_sdk/types/options.rbs

@@ -48,7 +48,7 @@ module ClaudeAgentSDK
                       ?permission_prompt_tool_name: String?,
                       ?cwd: (String | Pathname)?,
                       ?cli_path: (String | Pathname)?,
-                      ?settings: (String | Hash[Symbol | String, untyped])?,
+                      ?settings: (String | Pathname | Hash[Symbol | String, untyped])?,
                       ?add_dirs: Array[String | Pathname]?,
                       ?env: Hash[String | Symbol, String?]?,
                       ?extra_args: Hash[String | Symbol, untyped]?,
@@ -68,7 +68,7 @@ module ClaudeAgentSDK
                       ?plugins: Array[SdkPluginConfig | Hash[Symbol | String, untyped]]?,
                       ?debug_stderr: (_Puts | String)?,
                       ?betas: Array[String]?,
-                      ?tools: (Array[String] | ToolsPreset | Hash[Symbol | String, untyped])?,
+                      ?tools: (Array[String] | ToolsPreset | Hash[Symbol | String, untyped] | String)?,
                       ?sandbox: (SandboxSettings | Hash[Symbol | String, untyped] | bool)?,
                       ?thinking: thinking_config?,
                       ?effort: (String | Symbol | Integer)?,
@@ -133,8 +133,9 @@ module ClaudeAgentSDK
 
     attr_accessor cli_path: (String | Pathname)?
 
-    # A settings JSON String, a path to a settings file, or a Hash.
-    attr_accessor settings: (String | Hash[Symbol | String, untyped])?
+    # A settings JSON String, a path to a settings file (a String or a
+    # Pathname), or a Hash.
+    attr_accessor settings: (String | Pathname | Hash[Symbol | String, untyped])?
 
     attr_accessor add_dirs: Array[String | Pathname]?
 
@@ -185,10 +186,13 @@ module ClaudeAgentSDK
     # Entries of SDK_BETAS.
     attr_accessor betas: Array[String]?
 
-    # The base tool set: tool names, or a preset.
-    attr_accessor tools: (Array[String] | ToolsPreset | Hash[Symbol | String, untyped])?
+    # The base tool set: tool names (an Array, or the CLI's comma-separated
+    # String such as "Read,Grep"), or a preset.
+    attr_accessor tools: (Array[String] | ToolsPreset | Hash[Symbol | String, untyped] | String)?
 
-    # true / false are forwarded as-is (a bare toggle).
+    # true / false are forwarded as-is (a bare toggle). A Hash may spell the
+    # fields of SandboxSettings, and of its network / filesystem, in
+    # snake_case or in the CLI's camelCase (see SandboxSettings).
     attr_accessor sandbox: (SandboxSettings | Hash[Symbol | String, untyped] | bool)?
 
     attr_accessor thinking: thinking_config?

data/sig/claude_agent_sdk/types/permissions.rbs

@@ -41,7 +41,8 @@ module ClaudeAgentSDK
 
     attr_accessor directories: Array[String]?
 
-    # One of PERMISSION_UPDATE_DESTINATIONS.
+    # One of PERMISSION_UPDATE_DESTINATIONS. When nil, #to_h sends "session"
+    # (unless type is nil too).
     attr_accessor destination: String?
 
     attr_reader rules: Array[PermissionRuleValue]?
@@ -49,7 +50,8 @@ module ClaudeAgentSDK
     # Hash entries (camelCase or snake_case keys) become PermissionRuleValue.
     def rules=: (Array[PermissionRuleValue | Hash[Symbol | String, untyped]]? value) -> Array[PermissionRuleValue | Hash[Symbol | String, untyped]]?
 
-    # The wire form (camelCase keys).
+    # The wire form (camelCase keys). A rule without content has no
+    # ruleContent key.
     def to_h: () -> Hash[Symbol, untyped]
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - ya-luotao
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -54,14 +54,14 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
@@ -118,6 +118,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
 - README.md
@@ -129,6 +130,7 @@ files:
 - docs/hooks-and-permissions.md
 - docs/mcp-servers.md
 - docs/observability.md
+- docs/options.md
 - docs/rails.md
 - docs/sessions.md
 - docs/subagents.md