claude-agent-sdk 1.0.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,
@@ -81,21 +83,11 @@ module ClaudeAgentSDK
       self.include_hook_events = false
       self.strict_mcp_config = false
       self.forward_subagent_text = false
+      self.verbatim_prompts = false
 
       super(merge_with_defaults(attributes || {}))
 
-      # Non-nil defaults for options that need them.
-      self.env                 ||= {}
-      self.extra_args          ||= {}
-      self.mcp_servers         ||= {}
-      self.add_dirs            ||= []
-      self.observers           ||= []
-      self.allowed_tools       ||= []
-      self.disallowed_tools    ||= []
-      self.session_store_flush ||= 'batched'
-      # 0 is a valid (immediate) timeout, so only fill in the default for nil.
-      self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
-      self.callback_scheduling = :thread if callback_scheduling.nil?
+      fill_nil_defaults
     end
 
     def dup_with(**changes)
@@ -203,6 +195,58 @@ module ClaudeAgentSDK
       @forward_subagent_text = coerce_boolean(value)
     end
 
+    # Deliver every prompt to Claude as written.
+    #
+    # When true, every user message the SDK sends is marked `client_composed`:
+    # a String prompt to {ClaudeAgentSDK.query}, {Client#connect} or
+    # {Client#query}, and every message of a streamed (Enumerable) prompt to
+    # any of them. Claude Code then delivers the text exactly as given: no
+    # `@path` file-mention expansion and no slash-command dispatch. Use it when
+    # the prompt is assembled from content your end user did not type (earlier
+    # turns, tool output, third-party text), so an `@/absolute/path` inside it
+    # cannot make Claude Code read a local file. `tools: []`, `allowed_tools`
+    # and `disallowed_tools` do not stop that expansion: it happens before the
+    # model runs, without a tool call.
+    #
+    # While the option is on there is no per-message opt-out: a
+    # `client_composed` key on a streamed message Hash (either spelling) is
+    # overwritten. For per-turn control, leave the option off and set
+    # `client_composed: true` on individual streamed messages. The caller's
+    # Hashes are never mutated. A streamed JSONL String is parsed, marked and
+    # re-serialized; one that is not a single JSON object raises
+    # `ArgumentError` rather than being sent unmarked (on the background
+    # streaming paths that ends the stream with a warning, like any other
+    # stream error).
+    #
+    # On current Claude Code versions a turn delivered this way also skips the
+    # turn-start attachment pass as a whole: `@server:resource` MCP mentions
+    # are not expanded either, and the prompt goes without the context Claude
+    # Code normally attaches (nested `CLAUDE.md` and rules files, skill and
+    # tool listings, other per-turn reminders). The pass between tool calls is
+    # unaffected, so most of that context arrives after the turn's first tool
+    # call instead.
+    #
+    # Requires Claude Code 2.1.248 or later; older versions ignore the field,
+    # so prompts are still expanded there, and the SDK warns when it connects
+    # to one with this option on. Read once when the session starts. Not a
+    # CLI flag. Matches the Python SDK's `verbatim_prompts`.
+    #
+    # Assigning coerces to a Boolean; {#verbatim_prompts?} is the predicate
+    # form.
+    #
+    # @return [Boolean]
+    attr_reader :verbatim_prompts
+
+    # @return [Boolean] {#verbatim_prompts}, as a strict Boolean.
+    def verbatim_prompts?
+      !!verbatim_prompts
+    end
+
+    # @see #verbatim_prompts
+    def verbatim_prompts=(value)
+      @verbatim_prompts = coerce_boolean(value)
+    end
+
     # Request model-generated progress summaries for subagent (`local_agent`)
     # tasks. `true` *requests* generation: while the CLI has it enabled, a
     # subagent's {TaskProgressMessage#summary} **may** carry a one-line status.
@@ -288,16 +332,59 @@ module ClaudeAgentSDK
 
     private
 
+    # Non-nil defaults for options that need them.
+    def fill_nil_defaults
+      self.env                 ||= {}
+      self.extra_args          ||= {}
+      self.mcp_servers         ||= {}
+      self.add_dirs            ||= []
+      self.observers           ||= []
+      self.allowed_tools       ||= []
+      self.disallowed_tools    ||= []
+      self.session_store_flush ||= 'batched'
+      # 0 is a valid (immediate) timeout, so only fill in the default for nil.
+      self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
+      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.
@@ -346,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.0.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
@@ -749,7 +785,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
           forward_subagent_text: configured_options.forward_subagent_text?,
           agent_progress_summaries: configured_options.agent_progress_summaries,
           callback_scheduling: callback_scheduling,
-          callback_wrapper: callback_wrapper
+          callback_wrapper: callback_wrapper,
+          verbatim_prompts: configured_options.verbatim_prompts?,
+          run_end_ceiling_ms: Query.run_end_ceiling_ms(configured_options.env)
         )
 
         # Mirror transcripts to the session_store, if configured. Installed
@@ -782,7 +820,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             parent_tool_use_id: nil,
             session_id: ''
           }
-          transport.write("#{JSON.generate(message)}\n")
+          transport.write("#{Query.serialize_user_message(message, configured_options.verbatim_prompts?)}\n")
           # Background-spawn so messages stream to the user block while stdin
           # close waits (without timeout) for the first result; a synchronous
           # call would defer all delivery until the turn completes (mirrors
@@ -901,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
@@ -1041,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
@@ -1084,7 +1124,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             parent_tool_use_id: nil,
             session_id: session_id
           }
-          writeln(JSON.generate(message))
+          writeln(Query.serialize_user_message(message, @verbatim_prompts))
         elsif prompt.respond_to?(:each)
           # Inline iteration on the caller, Python client.py parity — NOT
           # Query#stream_input, whose ensure always ends input after
@@ -1312,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
@@ -1333,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
@@ -1394,6 +1444,10 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
       exclude_dynamic_sections = ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt)
       system_prompt_snapshot = ClaudeAgentSDK.extract_system_prompt_snapshot(configured_options.system_prompt)
 
+      # Captured once, so String and streamed prompts in one session are
+      # stamped alike (the Query stamps the streamed ones with this value).
+      @verbatim_prompts = configured_options.verbatim_prompts?
+
       # Create Query handler
       @query_handler = Query.new(
         transport: @transport,
@@ -1408,7 +1462,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
         forward_subagent_text: configured_options.forward_subagent_text?,
         agent_progress_summaries: configured_options.agent_progress_summaries,
         callback_scheduling: @callback_scheduling,
-        callback_wrapper: @callback_wrapper
+        callback_wrapper: @callback_wrapper,
+        verbatim_prompts: @verbatim_prompts,
+        run_end_ceiling_ms: Query.run_end_ceiling_ms(configured_options.env)
       )
 
       # Mirror transcripts to the session_store, if configured.
@@ -1450,7 +1506,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
     # key styles — an explicit nil is preserved, mirroring Python's
     # `"session_id" not in msg`). Strings pass through verbatim (Ruby
     # superset: Streaming.user_message emits pre-serialized JSONL; no
-    # parse-stamp-regenerate, which would block the reactor on huge frames).
+    # parse-stamp-regenerate, which would block the reactor on huge frames),
+    # except that verbatim_prompts must mark them `client_composed`, so with
+    # that option on they are parsed and re-serialized (Query.stamp_user_message).
     def stream_query_messages(prompt, session_id)
       prompt.each do |msg|
         case msg
@@ -1460,13 +1518,13 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
                                             scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
-          writeln(JSON.generate(msg))
+          writeln(Query.serialize_user_message(msg, @verbatim_prompts))
         when String
           if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
             ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
                                             scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
-          writeln(msg)
+          writeln(Query.serialize_user_message(msg, @verbatim_prompts))
         else
           # No to_s fallback — silently serializing arbitrary objects is the
           # exact inspect-garbage bug class this method exists to prevent.

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.