claude-agent-sdk 1.2.0 → 1.3.0

data/lib/claude_agent_sdk/command_builder.rb

@@ -3,6 +3,7 @@
 require 'json'
 require_relative 'errors'
 require_relative 'types'
+require_relative 'option_forms'
 
 module ClaudeAgentSDK
   # Builds the CLI argv array from a ClaudeAgentOptions instance.
@@ -68,57 +69,34 @@ module ClaudeAgentSDK
 
     private
 
+    # What the option stands for, typed or as a Hash, is OptionForms' to say;
+    # a kind that is none of these (a preset without an append, a Hash the
+    # SDK does not recognize, ...) sends no prompt flag at all.
     def append_system_prompt(cmd)
-      case @options.system_prompt
-      when nil
+      prompt = OptionForms.system_prompt(@options.system_prompt)
+      case prompt.kind
+      when :empty
         # 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', path_string(@options.system_prompt.path))
-      when SystemPromptCustom
-        # The object form of a String prompt; snapshot travels on the
+      when :text
+        # A String, or its object form (custom); snapshot travels on the
         # initialize request, not as a CLI flag.
-        cmd.push('--system-prompt', custom_prompt_text(@options.system_prompt.prompt))
-      when SystemPromptPreset
+        cmd.push('--system-prompt', custom_prompt_text(prompt.value))
+      when :file
+        cmd.push('--system-prompt-file', path_string(prompt.value))
+      when :append
         # 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)
+        cmd.push('--append-system-prompt', prompt.value)
       end
     end
 
-    # The type tag of a Hash option, as a String: `type: :preset` is the
-    # natural Ruby spelling of `type: 'preset'`, and thinking and the MCP
-    # server configs already read it that way. A missing tag is '', which
-    # matches no branch, like any other tag the SDK does not know.
-    def hash_type(hash)
-      (hash[:type] || hash['type']).to_s
-    end
-
     # A path as the String the command line takes. A Pathname (anything that
     # answers #to_path) is converted; every other value is returned as it is.
     def path_string(path)
       path.respond_to?(:to_path) ? path.to_path : path
     end
 
-    def append_hash_system_prompt(cmd, prompt_hash)
-      case hash_type(prompt_hash)
-      when 'file'
-        prompt_path = prompt_hash[:path] || prompt_hash['path']
-        cmd.push('--system-prompt-file', path_string(prompt_path)) if prompt_path
-      when 'custom'
-        prompt = prompt_hash.fetch(:prompt) { prompt_hash['prompt'] }
-        cmd.push('--system-prompt', custom_prompt_text(prompt))
-      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
-
     # A custom prompt is always forwarded, even when empty (an empty String
     # suppresses the default Claude Code prompt, exactly like a nil
     # system_prompt). A missing prompt is rejected loudly rather than
@@ -338,7 +316,7 @@ module ClaudeAgentSDK
         # read from JSON spell that key as a String; left next to the Symbol
         # key below it would be written twice (json 3.x raises on that).
         settings_hash = settings_hash.reject { |key, _| key.to_s == 'sandbox' }
-        settings_hash[:sandbox] = sandbox_section(@options.sandbox)
+        settings_hash[:sandbox] = OptionForms.sandbox(@options.sandbox)
       end
 
       cmd.push('--settings', JSON.generate(settings_hash)) if !settings_is_path && !settings_hash.empty?
@@ -355,29 +333,10 @@ module ClaudeAgentSDK
       [{}, true]
     end
 
-    # The sandbox section as the CLI reads it. A Hash stands for the
-    # SandboxSettings with the same fields: the CLI only knows the camelCase
-    # keys that class writes, and it ignores the others without an error, so
-    # a Hash in Ruby spelling (deny_read, denied_domains) is renamed like the
-    # typed value would be (SandboxKeys). Booleans go out as they are.
-    def sandbox_section(sandbox)
-      case sandbox
-      when SandboxSettings then sandbox.to_h
-      when Hash then SandboxKeys.normalize(sandbox)
-      else sandbox
-      end
-    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
+      total = OptionForms.task_budget_total(@options.task_budget)
       cmd.push('--task-budget', total.to_s) if total
     end
 
@@ -389,16 +348,16 @@ module ClaudeAgentSDK
     # max_thinking_tokens fallback.
     def append_thinking(cmd)
       if @options.thinking
-        type, budget, display = thinking_fields(@options.thinking)
-        case type
+        thinking = OptionForms.thinking(@options.thinking)
+        case thinking.type
         when 'adaptive'
           cmd.push('--thinking', 'adaptive')
-          append_thinking_display(cmd, display)
+          append_thinking_display(cmd, thinking.display)
         when 'enabled'
-          raise ArgumentError, "thinking type 'enabled' requires budget_tokens" if budget.nil?
+          raise ArgumentError, "thinking type 'enabled' requires budget_tokens" if thinking.budget_tokens.nil?
 
-          cmd.push('--max-thinking-tokens', budget.to_s)
-          append_thinking_display(cmd, display)
+          cmd.push('--max-thinking-tokens', thinking.budget_tokens.to_s)
+          append_thinking_display(cmd, thinking.display)
         when 'disabled'
           cmd.push('--thinking', 'disabled')
         else
@@ -409,20 +368,6 @@ module ClaudeAgentSDK
       end
     end
 
-    # Explicit class dispatch — never respond_to? probes (Kernel#display
-    # exists on every object and PRINTS the receiver to $stdout).
-    def thinking_fields(thinking)
-      case thinking
-      when Hash
-        type = (thinking[:type] || thinking['type'])&.to_s
-        [type, thinking[:budget_tokens] || thinking['budget_tokens'], thinking[:display] || thinking['display']]
-      when ThinkingConfigAdaptive then [thinking.type, nil, thinking.display]
-      when ThinkingConfigEnabled then [thinking.type, thinking.budget_tokens, thinking.display]
-      when ThinkingConfigDisabled then [thinking.type, nil, nil]
-      else [nil, nil, nil] # falls into append_thinking's else -> ArgumentError
-      end
-    end
-
     # `--thinking-display` toggles between `"summarized"` (visible thinking
     # text) and `"omitted"` (empty thinking, signature only). Current models default
     # to `"omitted"`, so pass `display: "summarized"` to see reasoning.
@@ -448,28 +393,27 @@ module ClaudeAgentSDK
     def append_tools(cmd)
       return if @options.tools.nil?
 
-      case @options.tools
+      # The preset, typed or as a Hash, is OptionForms' to recognize; every
+      # other value comes back as it was given and is only encoded here.
+      tools = OptionForms.tools(@options.tools)
+      case tools
+      when OptionForms::DEFAULT_TOOLS
+        cmd.push('--tools', 'default')
       when Array
-        tools_value = @options.tools.empty? ? '' : @options.tools.join(',')
+        tools_value = tools.empty? ? '' : tools.join(',')
         cmd.push('--tools', tools_value)
       when String
         # The CLI's own syntax ("Read,Grep", "default", ""): passed as written.
-        cmd.push('--tools', @options.tools)
-      when ToolsPreset
-        cmd.push('--tools', 'default')
+        cmd.push('--tools', tools)
       when Hash
-        if hash_type(@options.tools) == 'preset'
-          cmd.push('--tools', 'default')
-        else
-          cmd.push('--tools', JSON.generate(@options.tools))
-        end
+        cmd.push('--tools', JSON.generate(tools))
       end
     end
 
     def append_output_format(cmd)
       return unless @options.output_format
 
-      schema = output_schema(@options.output_format)
+      schema = OptionForms.output_schema(@options.output_format)
       # A json_schema output_format with a nil/absent schema must skip the
       # flag — `--json-schema null` is rejected by the CLI (Python guards
       # `schema is not None`).
@@ -479,22 +423,6 @@ module ClaudeAgentSDK
       cmd.push('--json-schema', schema_json)
     end
 
-    # The schema of a { type: 'json_schema', schema: ... } output format; any
-    # other value is the schema itself. The tag may be a Symbol, and `schema`
-    # is read under the key style `type` was written in, or under the other
-    # one when that key is absent ({ 'type' => 'json_schema', schema: {...} }).
-    def output_schema(format)
-      return format unless format.is_a?(Hash)
-
-      if format[:type].to_s == 'json_schema'
-        format.fetch(:schema) { format['schema'] }
-      elsif format['type'].to_s == 'json_schema'
-        format.fetch('schema') { format[:schema] }
-      else
-        format
-      end
-    end
-
     def append_additional_dirs(cmd)
       (@options.add_dirs || []).each { |dir| cmd.push('--add-dir', dir.to_s) }
     end
@@ -502,25 +430,15 @@ module ClaudeAgentSDK
     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|
-          # Typed Mcp*ServerConfig objects serialize via their wire hash —
-          # without this they'd JSON-stringify as "#<...>" via to_s.
-          config = config.to_h if config.is_a?(Type)
-          # Same recognition rule as ClaudeAgentSDK.extract_sdk_mcp_servers:
-          # either key style (and a Symbol :sdk type). The live instance is
-          # never serialized — JSON.generate would raise on it or leak its
-          # #to_s onto the command line.
-          servers_for_cli[name] = if config.is_a?(Hash) && (config[:type] || config['type']).to_s == 'sdk'
-                                    config.except(:instance, 'instance')
-                                  else
-                                    config
-                                  end
-        end
-        cmd.push('--mcp-config', JSON.generate({ mcpServers: servers_for_cli })) unless servers_for_cli.empty?
+      # A Hash of servers comes back with typed configs as their wire Hashes
+      # and without the live instance of an SDK server, which is never
+      # serialized: JSON.generate would raise on it or leak its #to_s onto
+      # the command line. Any other value is a path or JSON text.
+      servers = OptionForms.mcp_servers(@options.mcp_servers)
+      if servers.is_a?(Hash)
+        cmd.push('--mcp-config', JSON.generate({ mcpServers: servers })) unless servers.empty?
       else
-        cmd.push('--mcp-config', @options.mcp_servers.to_s)
+        cmd.push('--mcp-config', servers.to_s)
       end
     end
 
@@ -539,17 +457,17 @@ module ClaudeAgentSDK
     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_path = plugin_config[:path] || plugin_config['path']
+      @options.plugins.each do |entry|
+        plugin = OptionForms.plugin(entry)
 
-        unless %w[local plugin].include?(hash_type(plugin_config))
-          plugin_type = plugin_config[:type] || plugin_config['type']
-          raise ArgumentError, "Unsupported plugin type: #{plugin_type.inspect}"
+        unless %w[local plugin].include?(plugin.type_tag)
+          # raw_type looks the type up again, as it was written; asked for
+          # only here, so an accepted plugin has its type read once.
+          raise ArgumentError, "Unsupported plugin type: #{plugin.raw_type.inspect}"
         end
-        next unless plugin_path
+        next unless plugin.path
 
-        cmd.push('--plugin-dir', path_string(plugin_path))
+        cmd.push('--plugin-dir', path_string(plugin.path))
       end
     end
 

data/lib/claude_agent_sdk/option_forms.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require_relative 'types'
+
+module ClaudeAgentSDK
+  # How the SDK reads a Hash that stands for an option value, behind one set
+  # of functions. Several options take a typed value "or the equivalent
+  # Hash"; each function here reads one such option in both forms and answers
+  # what its caller needs: a small frozen record (Prompt, Thinking, Plugin),
+  # a plain value, the value as it was given, or a new Hash made from it.
+  # Only the records are frozen, never a value the caller owns.
+  #
+  # The functions are stateless. They keep nothing, they do not change the
+  # value they are given, and they check nothing: a caller that raises on a
+  # bad value (CommandBuilder, for a custom prompt without text, an enabled
+  # thinking config without a budget, an unknown thinking or plugin type)
+  # still does so itself, from what a function answers. The one exception is
+  # .agent_definition, which builds a Hash through AgentDefinition.new, so a
+  # misspelled key raises there. Flag names, path conversion and JSON
+  # encoding stay with the caller as well.
+  #
+  # The readers were written one at a time, and each option kept the key rule
+  # its reader had. They are not one rule, on purpose: a Hash that carries
+  # both spellings of a key, or nil / false under one of them, reads as it
+  # always did. The rules are
+  #
+  #   truthy    hash[:key] || hash['key']: a nil or false Symbol key falls
+  #             back to the String key
+  #   presence  hash.fetch(:key) { hash['key'] }: a Symbol key that is there
+  #             is the one read, whatever it holds
+  #
+  # and HashForm, which holds the field lookups that used to sit in the
+  # consumers of these options, says for each key which of them applies.
+  # Two kinds of Hash are not read there but handed whole to the code that
+  # read them before, with rules of its own: a sandbox Hash to
+  # SandboxKeys.normalize (types/option_values.rb), by .sandbox, and an agent
+  # Hash to AgentDefinition.new and the Type attribute machinery, by
+  # .agent_definition. spec/unit/option_forms_characterization_spec.rb pins
+  # the rules at the command line and the initialize request; a change of
+  # rule is a change of behaviour, not a cleanup.
+  #
+  # @api private
+  module OptionForms
+    # What .system_prompt answers. +kind+ says what the command line gets:
+    #
+    #   :empty   --system-prompt ''             (the option is nil)
+    #   :none    no prompt flag at all          (see .system_prompt)
+    #   :text    --system-prompt value          (value is whatever the custom
+    #                                           form holds; the caller raises
+    #                                           unless it is a String)
+    #   :file    --system-prompt-file value
+    #   :append  --append-system-prompt value
+    class Prompt
+      attr_reader :kind, :value
+
+      def initialize(kind, value = nil)
+        @kind = kind
+        @value = value
+        freeze
+      end
+
+      # +kind+ when there is a value to send, no prompt flag otherwise: a
+      # preset activates the default Claude Code prompt by sending no
+      # --system-prompt, with its append text only when it has any, and a
+      # file Hash names a file only when it has a path.
+      def self.optional(kind, value)
+        value ? new(kind, value) : new(:none)
+      end
+    end
+
+    # What .thinking answers: the fields of a thinking config, typed or Hash.
+    # +type+ is nil for a value that is no thinking config.
+    class Thinking
+      attr_reader :type, :budget_tokens, :display
+
+      def initialize(type: nil, budget_tokens: nil, display: nil)
+        @type = type
+        @budget_tokens = budget_tokens
+        @display = display
+        freeze
+      end
+    end
+
+    # What .plugin answers. +type_tag+ is the type as a String, to compare.
+    class Plugin
+      attr_reader :type_tag, :path
+
+      def initialize(type_tag:, path:, config:)
+        @type_tag = type_tag
+        @path = path
+        @config = config
+        freeze
+      end
+
+      # The type as it was written, for the message of the caller that
+      # refuses the plugin. Read from the entry anew each time it is asked
+      # for, and not when the record is made: the reader this replaces looked
+      # the type up a second time for its message, and only once it had
+      # refused the plugin, which a Hash that computes its values can tell.
+      def raw_type
+        HashForm.plugin_type(@config)
+      end
+    end
+
+    # The direct field lookups on an option Hash that were moved out of its
+    # consumers (CommandBuilder, the root extractors, the transport's sandbox
+    # warning), each under the rule its option has always had (truthy or
+    # presence, see OptionForms). The functions of OptionForms tell the forms
+    # of an option apart by class and come here for the Hash one.
+    #
+    # This is not every read of an option Hash in the SDK. The fields of a
+    # sandbox Hash are read and renamed by SandboxKeys.normalize
+    # (types/option_values.rb), which OptionForms.sandbox delegates to; only
+    # the `enabled` of the warning predicate is looked up here. The
+    # attributes of an agent Hash are assigned by the strict
+    # AgentDefinition.new, through the Type machinery, which
+    # OptionForms.agent_definition delegates to.
+    module HashForm
+      # The type tag, as a String: `type: :preset` is the natural Ruby
+      # spelling of `type: 'preset'`. Truthy, so a nil Symbol-keyed tag falls
+      # back to the String-keyed one. A missing tag is '', which is no tag
+      # the SDK knows.
+      def self.tag(hash)
+        (hash[:type] || hash['type']).to_s
+      end
+
+      # system_prompt, by its tag: +path+ and +append+ are truthy, +prompt+
+      # is by presence (a Symbol key holding nil is the prompt, and the
+      # caller refuses it). Any other tag, or none, is no prompt flag.
+      def self.system_prompt(hash)
+        case tag(hash)
+        when 'file' then Prompt.optional(:file, hash[:path] || hash['path'])
+        when 'custom' then Prompt.new(:text, hash.fetch(:prompt) { hash['prompt'] })
+        when 'preset' then Prompt.optional(:append, hash[:append] || hash['append'])
+        else Prompt.new(:none)
+        end
+      end
+
+      # +snapshot+ of a preset or custom system prompt, by presence.
+      def self.snapshot(hash)
+        hash.fetch(:snapshot) { hash['snapshot'] } if %w[preset custom].include?(tag(hash))
+      end
+
+      # +exclude_dynamic_sections+ of a preset system prompt, by presence.
+      def self.exclude_dynamic_sections(hash)
+        hash.fetch(:exclude_dynamic_sections) { hash['exclude_dynamic_sections'] } if tag(hash) == 'preset'
+      end
+
+      # thinking: all three fields are truthy, so `budget_tokens: false` is
+      # no budget. The type stays nil when there is none; +display+ is not
+      # checked the way the typed classes check theirs.
+      def self.thinking(hash)
+        Thinking.new(type: (hash[:type] || hash['type'])&.to_s,
+                     budget_tokens: hash[:budget_tokens] || hash['budget_tokens'],
+                     display: hash[:display] || hash['display'])
+      end
+
+      # output_format: the Symbol-keyed tag is looked at before the
+      # String-keyed one, and +schema+ is read by presence under the key
+      # style the matching tag was written in, or under the other one when
+      # that key is absent ({ 'type' => 'json_schema', schema: {...} }). A
+      # Hash that is not tagged json_schema is the schema itself.
+      def self.output_schema(hash)
+        if hash[:type].to_s == 'json_schema'
+          hash.fetch(:schema) { hash['schema'] }
+        elsif hash['type'].to_s == 'json_schema'
+          hash.fetch('schema') { hash[:schema] }
+        else
+          hash
+        end
+      end
+
+      # task_budget: +total+ is truthy.
+      def self.total(hash)
+        hash[:total] || hash['total']
+      end
+
+      # One plugin: +path+ is truthy and read first, then the tag, once.
+      def self.plugin(hash)
+        path = hash[:path] || hash['path']
+        Plugin.new(type_tag: tag(hash), path: path, config: hash)
+      end
+
+      # The type of a plugin as it was written (truthy), for Plugin#raw_type.
+      def self.plugin_type(hash)
+        hash[:type] || hash['type']
+      end
+
+      # sandbox, for the warning alone (.sandbox_requested?): either key
+      # being true will do, whatever the other one holds.
+      def self.enabled?(hash)
+        hash[:enabled] == true || hash['enabled'] == true
+      end
+
+      # The live server of an sdk MCP server config, by presence.
+      def self.instance(hash)
+        hash.key?(:instance) ? hash[:instance] : hash['instance']
+      end
+    end
+    private_constant :HashForm
+
+    # What .tools answers for the preset. An object of its own rather than a
+    # Symbol: a caller can write `tools: :default`, which is none of the forms
+    # of the option and sends no flag.
+    #
+    # @api private
+    DEFAULT_TOOLS = Object.new.freeze
+
+    # The system prompt as the command line takes it (see Prompt).
+    #
+    # nil is the empty prompt, and it is the only value that is. No prompt
+    # flag at all, so that the CLI runs with its default prompt, is the answer
+    # for a preset without an append, a file Hash without a path, a Hash with
+    # an unknown tag or none, and a value that is none of the forms of the
+    # option. A typed SystemPromptFile is a file prompt whatever its path
+    # holds.
+    def self.system_prompt(value)
+      case value
+      when nil then Prompt.new(:empty)
+      when String then Prompt.new(:text, value)
+      when SystemPromptFile then Prompt.new(:file, value.path)
+      when SystemPromptCustom then Prompt.new(:text, value.prompt)
+      when SystemPromptPreset then Prompt.optional(:append, value.append)
+      when Hash then HashForm.system_prompt(value)
+      else Prompt.new(:none)
+      end
+    end
+
+    # The +snapshot+ of a preset or custom system prompt, for the initialize
+    # request: true, false, or nil when there is none to send. Only a genuine
+    # true or false is answered (`snapshot: false` is the value callers set).
+    # The prompt text is not looked at: a session over a transport that
+    # builds no command line still gets its snapshot through.
+    def self.system_prompt_snapshot(value)
+      case value
+      when SystemPromptPreset, SystemPromptCustom then boolean(value.snapshot)
+      when Hash then boolean(HashForm.snapshot(value))
+      end
+    end
+
+    # The +exclude_dynamic_sections+ of a preset system prompt, for the
+    # initialize request: true, false, or nil when there is none to send.
+    def self.exclude_dynamic_sections(value)
+      case value
+      when SystemPromptPreset then boolean(value.exclude_dynamic_sections)
+      when Hash then boolean(HashForm.exclude_dynamic_sections(value))
+      end
+    end
+
+    # The fields of a thinking config (see Thinking). The typed classes are
+    # told apart by class, never by respond_to?: Kernel#display exists on
+    # every object and prints the receiver to $stdout.
+    def self.thinking(value)
+      case value
+      when Hash then HashForm.thinking(value)
+      when ThinkingConfigAdaptive then Thinking.new(type: value.type, display: value.display)
+      when ThinkingConfigEnabled
+        Thinking.new(type: value.type, budget_tokens: value.budget_tokens, display: value.display)
+      when ThinkingConfigDisabled then Thinking.new(type: value.type)
+      else Thinking.new
+      end
+    end
+
+    # DEFAULT_TOOLS for the tools preset, typed or as a Hash tagged 'preset';
+    # any other value as it was given (an Array of names, the CLI's own
+    # String syntax, a Hash the caller sends as JSON text).
+    def self.tools(value)
+      case value
+      when ToolsPreset then DEFAULT_TOOLS
+      when Hash then HashForm.tag(value) == 'preset' ? DEFAULT_TOOLS : value
+      else value
+      end
+    end
+
+    # The schema of a { type: 'json_schema', schema: ... } output format; any
+    # other value is the schema itself. The value found is answered as it
+    # is, false included; only the caller leaves out nil.
+    def self.output_schema(value)
+      value.is_a?(Hash) ? HashForm.output_schema(value) : value
+    end
+
+    # The total of a task budget, or nil when there is none. Any value that
+    # is not a TaskBudget is read as a Hash, which is how one that is no
+    # budget at all still fails loudly.
+    def self.task_budget_total(value)
+      return unless value
+      return value.total if value.is_a?(TaskBudget)
+
+      HashForm.total(value)
+    end
+
+    # One entry of +plugins+ (see Plugin); a typed SdkPluginConfig is read
+    # through its #to_h, taken once. The caller refuses a type that is no
+    # plugin type, asking for Plugin#raw_type only then, and skips an entry
+    # without a path.
+    def self.plugin(value)
+      HashForm.plugin(value.is_a?(SdkPluginConfig) ? value.to_h : value)
+    end
+
+    # The sandbox section as the CLI reads it. A Hash stands for the
+    # SandboxSettings with the same fields: the CLI only knows the camelCase
+    # keys that class writes, and it ignores the others without an error, so
+    # a Hash in Ruby spelling (deny_read, denied_domains) is renamed like the
+    # typed value would be (SandboxKeys, which has key rules of its own).
+    # Every other value, booleans and nil included, is answered as it is.
+    def self.sandbox(value)
+      case value
+      when SandboxSettings then value.to_h
+      when Hash then SandboxKeys.normalize(value)
+      else value
+      end
+    end
+
+    # True when the option enables the sandbox: `true`, a SandboxSettings
+    # with +enabled+ true, or a Hash that says so under either key, which is
+    # not what .sandbox sends for a Hash carrying both. Deliberately a
+    # shallow read and nothing else: the transport asks from its stderr
+    # threads, where walking the Hash or calling a #to_h a user can override
+    # has no place.
+    def self.sandbox_requested?(value)
+      case value
+      when SandboxSettings then value.enabled == true
+      when Hash then HashForm.enabled?(value)
+      else value == true
+      end
+    end
+
+    # The MCP servers as the command line takes them. A Hash of servers is
+    # answered as a new Hash: a typed Mcp*ServerConfig as its wire Hash
+    # (as JSON it would otherwise read "#<...>"), and an sdk entry
+    # (.sdk_server?) without its +instance+, under either key: the live
+    # server is never serialized. Any other value (the path of a config
+    # file, JSON text) is answered as it was given.
+    def self.mcp_servers(value)
+      return value unless value.is_a?(Hash)
+
+      servers = {}
+      value.each do |name, config|
+        config = config.to_h if config.is_a?(Type)
+        servers[name] = sdk_server?(config) ? config.except(:instance, 'instance') : config
+      end
+      servers
+    end
+
+    # The live SDK MCP servers of an +mcp_servers+ Hash, by server name: the
+    # +instance+ of every sdk entry, typed or Hash. The entries are
+    # recognized exactly as .mcp_servers recognizes them, which strips the
+    # instance from the same ones. Empty for any other value.
+    def self.sdk_mcp_servers(value)
+      return {} unless value.is_a?(Hash)
+
+      servers = {}
+      value.each do |name, config|
+        config = config.to_h if config.is_a?(Type)
+        servers[name] = HashForm.instance(config) if sdk_server?(config)
+      end
+      servers
+    end
+
+    # One value of +agents+ as an AgentDefinition. A Hash stands for the
+    # AgentDefinition with the same attributes and is built through .new:
+    # the user wrote it, so a misspelled key raises as on the typed class.
+    def self.agent_definition(value)
+      value.is_a?(Hash) ? AgentDefinition.new(value) : value
+    end
+
+    # An MCP server config (a typed one already as its wire Hash) that is an
+    # in-process SDK server: a Hash tagged 'sdk'.
+    def self.sdk_server?(config)
+      config.is_a?(Hash) && HashForm.tag(config) == 'sdk'
+    end
+
+    def self.boolean(value)
+      value if [true, false].include?(value)
+    end
+
+    private_class_method :sdk_server?, :boolean
+  end
+end