claude-agent-sdk 1.0.0 → 1.2.0

data/lib/claude_agent_sdk/transport.rb

@@ -1,42 +1,58 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  # Abstract transport for Claude communication
+  # Abstract base class for transports: the channel between the SDK and a
+  # Claude Code CLI process.
   #
-  # WARNING: This internal API is exposed for custom transport implementations
-  # (e.g., remote Claude Code connections). The Claude Code team may change or
-  # remove this abstract class in any future release. Custom implementations
-  # must be updated to match interface changes.
+  # Public API, covered by this gem's SemVer promise like the rest of the
+  # documented surface. {SubprocessCLITransport}, the default, spawns the CLI
+  # locally. To run the CLI somewhere else (a container, an SSH host, a
+  # sandbox VM), subclass this class, or write any object with the same
+  # methods, and pass it to {Client#initialize} as `transport_class:` or to
+  # {ClaudeAgentSDK.query} / {ClaudeAgentSDK.ask} as `transport:`. See
+  # docs/client.md, "Custom Transport".
+  #
+  # The SDK calls five methods: {#connect}, {#write}, {#read_messages},
+  # {#end_input} and {#close}. It never calls {#ready?}, so that one is
+  # optional. Every method here raises NotImplementedError until a subclass
+  # overrides it.
   class Transport
-    # Connect the transport and prepare for communication
+    # Establish the connection (spawn or reach the CLI) and prepare for IO.
     def connect
       raise NotImplementedError, 'Subclasses must implement #connect'
     end
 
-    # Write raw data to the transport
+    # Write raw data to the CLI's stdin.
     # @param data [String] Raw string data to write (typically JSON + newline)
     def write(data)
       raise NotImplementedError, 'Subclasses must implement #write'
     end
 
-    # Read and parse messages from the transport
-    # @return [Enumerator] Async enumerator of parsed JSON messages
+    # Read the CLI's stdout and yield each line as a parsed message, blocking
+    # until the stream ends. Parse each line with
+    # `JSON.parse(line, symbolize_names: true)`: the SDK reads Symbol keys.
+    # The SDK always passes a block.
+    # @yield [Hash{Symbol => Object}] Each parsed message
     def read_messages
       raise NotImplementedError, 'Subclasses must implement #read_messages'
     end
 
-    # Close the transport connection and clean up resources
+    # Terminate the CLI and clean up resources. Must be idempotent: the SDK
+    # can call it more than once, and calls it after a failed {#connect} too.
     def close
       raise NotImplementedError, 'Subclasses must implement #close'
     end
 
-    # Check if transport is ready for communication
+    # Check if transport is ready for communication. Optional: the SDK never
+    # calls it.
     # @return [Boolean] True if transport is ready to send/receive messages
     def ready?
       raise NotImplementedError, 'Subclasses must implement #ready?'
     end
 
-    # End the input stream (close stdin for process transports)
+    # End the input stream (close stdin for process transports). The SDK
+    # calls it when a one-shot query's run is over and when a streamed prompt
+    # is exhausted.
     def end_input
       raise NotImplementedError, 'Subclasses must implement #end_input'
     end

data/lib/claude_agent_sdk/types/attributes.rb

@@ -184,6 +184,10 @@ module ClaudeAgentSDK
     end
 
     def read_attribute(name)
+      # A writer's name (`session_id=`) is not readable. Checked before the
+      # cache, which also holds the camelCase writers method_missing resolved.
+      return if writer_name?(name)
+
       reader = self.class.cached_attribute_reader(name)
       return public_send(reader) if reader
 
@@ -198,6 +202,11 @@ module ClaudeAgentSDK
       end
     end
 
+    def writer_name?(name)
+      name = name.to_s unless name.is_a?(Symbol) || name.is_a?(String)
+      name.end_with?('=')
+    end
+
     # Whether a normalized reader, writer or predicate name belongs to an
     # attribute: a declared one (`session_id`, `session_id=`,
     # `fork_session?`), or a method user code defined on its own subclass, a

data/lib/claude_agent_sdk/types/base.rb

@@ -122,8 +122,19 @@ module ClaudeAgentSDK
     # dumps every ivar recursively — those (SDK MCP server instances, store
     # adapters, observers) show as `#<ClassName>`. For display only: nothing
     # sent to the CLI goes through #inspect or #to_s (wire output uses #to_h).
+    #
+    # Attributes that carry credentials print as `[FILTERED]` (a Hash keeps
+    # its keys): `env`, `settings` and `extra_args` of ClaudeAgentOptions,
+    # and `env`, `args` and `headers` of the MCP server configs. An MCP
+    # server `url` prints its scheme and host only, and a Hash server config
+    # (in `mcp_servers`, or echoed by the CLI in McpServerStatus#config) is
+    # filtered like a typed one. `mcp_servers` given as a String prints as
+    # `[FILTERED]`.
+    #
+    # It does not raise: a value that fails while it is rendered shows as
+    # `#<ClassName>` (`#<?>` when even its class cannot be asked).
     def inspect
-      inspect_with(0, {}.compare_by_identity)
+      inspect_bounded(self, 0, {}.compare_by_identity)
     end
 
     # Object#to_s ignores instance variables, so `puts message` would print
@@ -134,9 +145,10 @@ module ClaudeAgentSDK
       inspect
     end
 
-    # Declares attributes that carry credentials (env vars, auth headers).
-    # Objects get logged, so #inspect shows them filtered; #to_h and
-    # everything sent to the CLI are unaffected. Inherited by subclasses.
+    # Declares attributes that carry credentials (env vars, auth headers,
+    # settings, extra CLI arguments, an MCP server's args). Objects get
+    # logged, so #inspect shows them filtered; #to_h and everything sent to
+    # the CLI are unaffected. Inherited by subclasses.
     #
     # @api private
     def self.inspect_filtered(*names)
@@ -182,7 +194,7 @@ module ClaudeAgentSDK
       filtered = self.class.inspect_filtered_attributes
       instance_variables.filter_map do |ivar|
         value = instance_variable_get(ivar)
-        next if value.nil?
+        next if nil.equal?(value) # not value.nil?: a BasicObject has no such method
 
         name = ivar.to_s.delete_prefix('@')
         [name, filtered.include?(name) ? inspect_filter(value) : value]
@@ -191,15 +203,65 @@ module ClaudeAgentSDK
 
     # A credential-bearing Hash keeps its keys (useful when debugging which
     # variables are set) with every value replaced; anything else is replaced
-    # outright. Builds a new Hash; the object itself is never touched.
+    # outright, and so is a value that fails while it is asked for its keys.
+    # Builds a new Hash; the object itself is never touched.
     def inspect_filter(value)
       value.respond_to?(:each_key) ? value.each_key.to_h { |key| [key, '[FILTERED]'] } : '[FILTERED]'
+    rescue StandardError
+      '[FILTERED]'
+    end
+
+    INSPECT_URL_ORIGIN = %r{
+      \A(https?|wss?)://                 # scheme
+      (?:[^/?\#\\]*@)?                   # userinfo, up to the last @ before the path
+      (\[[0-9a-f:.]+\]|[[:alnum:]._-]+)  # host: an IPv6 literal or a name
+      (:\d{1,5})?                        # port
+      (?=[/?\#]|\z)                      # then the path, the query, the fragment or the end
+    }ix
+    private_constant :INSPECT_URL_ORIGIN
+
+    # A URL can carry a credential in its userinfo, path, query or fragment,
+    # so only where it points is shown: `https://mcp.example.com/[FILTERED]`
+    # (scheme, host and port). Anything else is replaced outright: a value
+    # that is not a String, another scheme, a host or port with a character
+    # that does not belong there.
+    def inspect_filter_url(value)
+      origin = value.is_a?(String) && INSPECT_URL_ORIGIN.match(value)
+      origin ? "#{origin[1]}://#{origin[2]}#{origin[3]}/[FILTERED]" : '[FILTERED]'
+    rescue StandardError
+      '[FILTERED]'
+    end
+
+    # Keys of a raw Hash MCP server config whose values #inspect shows as they are.
+    INSPECT_MCP_CONFIG_KEYS = %w[type command name instance].freeze
+    private_constant :INSPECT_MCP_CONFIG_KEYS
+
+    # An MCP server config held as a raw Hash (in ClaudeAgentOptions#mcp_servers,
+    # or echoed by the CLI in McpServerStatus#config) carries the same
+    # credentials as a typed one: env, headers, args, a token in the url. It
+    # keeps its keys and shows what identifies the server: its type, its
+    # command (or the SDK server's name and instance) and the scheme and host
+    # of its url. Every other value is filtered here rather than left to the
+    # nesting limit of #inspect.
+    def inspect_mcp_server_config(config)
+      config.to_h do |key, value|
+        name = key.to_s
+        next [key, value] if INSPECT_MCP_CONFIG_KEYS.include?(name)
+
+        [key, name == 'url' ? inspect_filter_url(value) : '[FILTERED]']
+      end
     end
 
     def inspect_class_name
       self.class.name || self.class.inspect
     end
 
+    # Printing must never raise (it runs inside loggers and `puts`). The
+    # value's own methods run here (a String subclass's #length, a Hash
+    # subclass's #size, a Type subclass's #inspect_attributes), so a value
+    # that fails while it is rendered becomes a placeholder and the rest of
+    # the object still prints. Only StandardError is rescued: Interrupt,
+    # SystemExit and the like pass through.
     def inspect_bounded(value, depth, seen)
       case value
       when Type then value.inspect_with(depth, seen)
@@ -212,6 +274,16 @@ module ClaudeAgentSDK
       when Proc, Method, UnboundMethod then inspect_callable(value)
       else inspect_leaf(value)
       end
+    rescue StandardError
+      inspect_placeholder(value)
+    end
+
+    # `#<ClassName>` for a value that could not be rendered; a BasicObject
+    # cannot even be asked for its class.
+    def inspect_placeholder(value)
+      inspect_truncated_text("#<#{value.class}>")
+    rescue StandardError
+      '#<?>'
     end
 
     def inspect_container(value, open, close, depth, seen, &)
@@ -231,7 +303,10 @@ module ClaudeAgentSDK
     # Rendered by hand rather than via Hash#inspect, whose format differs
     # between Ruby 3.3 (`{:a=>1}`) and 3.4 (`{a: 1}`).
     def inspect_hash_key(key, depth, seen)
-      return "#{key.name}: " if key.is_a?(Symbol) && key.inspect.match?(/\A:\w+[?!]?\z/)
+      case key # not key.is_a?: a BasicObject key has no such method
+      when Symbol
+        return "#{key.name}: " if key.inspect.match?(/\A:\w+[?!]?\z/)
+      end
 
       "#{inspect_bounded(key, depth, seen)} => "
     end
@@ -265,19 +340,14 @@ module ClaudeAgentSDK
       "#{rendered[0, INSPECT_MAX_STRING]}…(+#{rendered.length - INSPECT_MAX_STRING} chars)"
     end
 
-    # Printing must never raise (it runs inside loggers and `puts`), so an
-    # object whose #inspect raises, or a BasicObject without one, falls back
-    # to a placeholder.
+    # An object whose #inspect raises, or a BasicObject without one, falls
+    # back to a placeholder.
     def inspect_leaf(value)
       return "#<#{value.class}>" if kernel_inspect_only?(value)
 
       inspect_truncated_text(value.inspect)
     rescue StandardError
-      begin
-        "#<#{value.class}>"
-      rescue StandardError
-        '#<?>'
-      end
+      inspect_placeholder(value)
     end
 
     def kernel_inspect_only?(value)

data/lib/claude_agent_sdk/types/hooks.rb

@@ -637,4 +637,77 @@ module ClaudeAgentSDK
       result
     end
   end
+
+  # The spellings a hook callback's return value may use for a field of the
+  # typed output classes above, mapped to the key the CLI reads. A Hash a
+  # callback returns stands for the typed output with the same fields: its
+  # keys may be Symbols or Strings, the attribute names (snake_case) or what
+  # #to_h emits (camelCase), at the top level and inside hook_specific_output.
+  #
+  # Only names that differ from their wire key are listed. A key that is not
+  # listed is sent as written, so a field of a newer CLI that the typed
+  # classes do not model still gets through, in the CLI's own spelling.
+  # spec/unit/hook_output_normalization_spec.rb walks every typed output
+  # class and fails when an attribute and these tables disagree.
+  #
+  # @api private
+  module HookOutputKeys
+    # SyncHookJSONOutput and AsyncHookJSONOutput attributes, plus the
+    # Ruby-safe spellings of the two keywords.
+    TOP_LEVEL = {
+      'continue_' => 'continue',
+      'async_' => 'async',
+      'suppress_output' => 'suppressOutput',
+      'stop_reason' => 'stopReason',
+      'system_message' => 'systemMessage',
+      'hook_specific_output' => 'hookSpecificOutput',
+      'async_timeout' => 'asyncTimeout'
+    }.freeze
+
+    # Attributes of the *HookSpecificOutput classes.
+    HOOK_SPECIFIC = {
+      'hook_event_name' => 'hookEventName',
+      'permission_decision' => 'permissionDecision',
+      'permission_decision_reason' => 'permissionDecisionReason',
+      'updated_input' => 'updatedInput',
+      'additional_context' => 'additionalContext',
+      'updated_tool_output' => 'updatedToolOutput',
+      'updated_mcp_tool_output' => 'updatedMCPToolOutput',
+      'watch_paths' => 'watchPaths'
+    }.freeze
+
+    # The hook output Hash as the CLI reads it: String keys in wire
+    # spelling, at the top level and one level down, inside
+    # hookSpecificOutput. Values are never rewritten: updatedInput and the
+    # tool outputs are the tool's own payloads, and a PermissionRequest
+    # decision goes out as the caller wrote it.
+    def self.normalize(output)
+      normalized = rename(output, TOP_LEVEL)
+      specific = normalized['hookSpecificOutput']
+      normalized['hookSpecificOutput'] = rename(specific, HOOK_SPECIFIC) if specific.is_a?(Hash)
+      normalized
+    end
+
+    # Every key ends up as one String, so a Symbol and a String spelling the
+    # same field cannot both reach JSON.generate (json 3.x raises on that;
+    # 2.x emits the key twice). When a Hash carries both spellings of one
+    # field the wire spelling wins, whichever comes first; between two keys
+    # in the same spelling the later one does.
+    def self.rename(hash, table)
+      renamed = {}
+      wire_spelled = {}
+      hash.each do |key, value|
+        name = key.to_s
+        wire = table.fetch(name, name)
+        if wire == name
+          wire_spelled[wire] = true
+        elsif wire_spelled.key?(wire)
+          next
+        end
+        renamed[wire] = value
+      end
+      renamed
+    end
+    private_class_method :rename
+  end
 end

data/lib/claude_agent_sdk/types/mcp.rb

@@ -109,6 +109,25 @@ module ClaudeAgentSDK
         config
       end
     end
+
+    private
+
+    # The CLI echoes a server's config back with its credentials (headers, a
+    # token in the url, args). A Hash config prints like a raw Hash config in
+    # ClaudeAgentOptions#mcp_servers; the typed proxy and SDK configs print
+    # as they are.
+    def inspect_attributes
+      super.map { |name, value| [name, name == 'config' ? inspect_config(value) : value] }
+    end
+
+    def inspect_config(config)
+      case config # not config.is_a?: a BasicObject has no such method
+      when Hash then inspect_mcp_server_config(config)
+      else config
+      end
+    rescue StandardError
+      '[FILTERED]'
+    end
   end
 
   # Response from get_mcp_status containing all server statuses
@@ -138,7 +157,8 @@ module ClaudeAgentSDK
     attr_accessor :command, :args, :env
     attr_reader :type
 
-    inspect_filtered :env
+    # `args` carries flags such as `--api-key <key>`.
+    inspect_filtered :env, :args
 
     def initialize(attributes = {})
       super
@@ -173,6 +193,14 @@ module ClaudeAgentSDK
       result[:headers] = @headers if @headers
       result
     end
+
+    private
+
+    # The url can carry a token (userinfo, path or query): #inspect shows
+    # its scheme and host.
+    def inspect_attributes
+      super.map { |name, value| [name, name == 'url' ? inspect_filter_url(value) : value] }
+    end
   end
 
   class McpHttpServerConfig < Type
@@ -195,6 +223,14 @@ module ClaudeAgentSDK
       result[:headers] = @headers if @headers
       result
     end
+
+    private
+
+    # The url can carry a token (userinfo, path or query): #inspect shows
+    # its scheme and host.
+    def inspect_attributes
+      super.map { |name, value| [name, name == 'url' ? inspect_filter_url(value) : value] }
+    end
   end
 
   class McpSdkServerConfig < Type

data/lib/claude_agent_sdk/types/messages.rb

@@ -192,7 +192,13 @@ module ClaudeAgentSDK
                   :outcome # "success", "error", or "cancelled"
   end
 
-  # Session state changed system message
+  # Session state changed system message.
+  #
+  # Reaches your code only when you opt in with
+  # `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1` in ClaudeAgentOptions#env. The
+  # SDK also asks the CLI for these frames on its own behalf (to tell when a
+  # query() run is over), but those arrive marked `sdk_host_only` and are
+  # dropped before the message stream.
   class SessionStateChangedMessage < SystemMessage
     attr_accessor :uuid, :session_id,
                   :state # "idle", "running", or "requires_action"

data/lib/claude_agent_sdk/types/option_values.rb

@@ -158,7 +158,19 @@ module ClaudeAgentSDK
     end
   end
 
-  # Sandbox settings for isolated command execution
+  # Sandbox settings for isolated command execution.
+  #
+  # +network+ and +filesystem+ take a SandboxNetworkConfig /
+  # SandboxFilesystemConfig or a Hash. A Hash may spell the fields of those
+  # classes as their attributes (+denied_domains+) or as the CLI does
+  # (+deniedDomains+), with Symbol or String keys; any other key is sent as
+  # written. The same holds for a Hash given as +sandbox:+ in place of a
+  # SandboxSettings.
+  #
+  # A snake_case key in such a Hash is sent under the CLI's name only when
+  # its value has the shape the CLI accepts there (an Array of Strings for
+  # +denied_domains+, +true+ or +false+ for +allow_local_binding+, ...).
+  # With any other value it is sent as written, and the CLI ignores it.
   class SandboxSettings < Type
     include Type::OptionValue
 
@@ -169,15 +181,15 @@ module ClaudeAgentSDK
                   :ignore_violations, :enable_weaker_nested_sandbox,
                   :enable_weaker_network_isolation, :ripgrep
 
-    def to_h # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- one optional key per sandbox field
+    def to_h
       result = {}
       result[:enabled] = @enabled unless @enabled.nil?
       result[:failIfUnavailable] = @fail_if_unavailable unless @fail_if_unavailable.nil?
       result[:autoAllowBashIfSandboxed] = @auto_allow_bash_if_sandboxed unless @auto_allow_bash_if_sandboxed.nil?
       result[:excludedCommands] = @excluded_commands if @excluded_commands
       result[:allowUnsandboxedCommands] = @allow_unsandboxed_commands unless @allow_unsandboxed_commands.nil?
-      result[:network] = @network.is_a?(SandboxNetworkConfig) ? @network.to_h : @network if @network
-      result[:filesystem] = @filesystem.is_a?(SandboxFilesystemConfig) ? @filesystem.to_h : @filesystem if @filesystem
+      result[:network] = SandboxKeys.network(@network) if @network
+      result[:filesystem] = SandboxKeys.filesystem(@filesystem) if @filesystem
       result[:ignoreViolations] = @ignore_violations if @ignore_violations
       result[:enableWeakerNestedSandbox] = @enable_weaker_nested_sandbox unless @enable_weaker_nested_sandbox.nil?
       unless @enable_weaker_network_isolation.nil?
@@ -188,6 +200,176 @@ module ClaudeAgentSDK
     end
   end
 
+  # The spellings a sandbox Hash may use for a field of the three sandbox
+  # classes above, mapped to the key their #to_h emits, which is the key the
+  # CLI reads. A Hash given as the +sandbox:+ option, or as the network /
+  # filesystem of a SandboxSettings, stands for the typed value with the same
+  # fields: its keys may be Symbols or Strings, the attribute names
+  # (snake_case) or the wire keys (camelCase).
+  #
+  # Every attribute is listed, also the ones whose name is their wire key. A
+  # key that is not listed is sent as written, so a field of the CLI that the
+  # typed classes do not model (allowAppleEvents, network.strictAllowlist,
+  # filesystem.disabled, ...) still gets through, in the CLI's own spelling.
+  # spec/unit/sandbox_hash_keys_spec.rb walks the attributes of the three
+  # classes and fails when one of them and these tables disagree.
+  #
+  # @api private
+  module SandboxKeys
+    # SandboxSettings attribute => wire key.
+    TOP_LEVEL = {
+      'enabled' => :enabled,
+      'fail_if_unavailable' => :failIfUnavailable,
+      'auto_allow_bash_if_sandboxed' => :autoAllowBashIfSandboxed,
+      'excluded_commands' => :excludedCommands,
+      'allow_unsandboxed_commands' => :allowUnsandboxedCommands,
+      'network' => :network,
+      'filesystem' => :filesystem,
+      'ignore_violations' => :ignoreViolations,
+      'enable_weaker_nested_sandbox' => :enableWeakerNestedSandbox,
+      'enable_weaker_network_isolation' => :enableWeakerNetworkIsolation,
+      'ripgrep' => :ripgrep
+    }.freeze
+
+    # SandboxNetworkConfig attribute => wire key.
+    NETWORK = {
+      'allowed_domains' => :allowedDomains,
+      'denied_domains' => :deniedDomains,
+      'allow_managed_domains_only' => :allowManagedDomainsOnly,
+      'allow_unix_sockets' => :allowUnixSockets,
+      'allow_all_unix_sockets' => :allowAllUnixSockets,
+      'allow_local_binding' => :allowLocalBinding,
+      'allow_mach_lookup' => :allowMachLookup,
+      'http_proxy_port' => :httpProxyPort,
+      'socks_proxy_port' => :socksProxyPort
+    }.freeze
+
+    # SandboxFilesystemConfig attribute => wire key.
+    FILESYSTEM = {
+      'allow_write' => :allowWrite,
+      'deny_write' => :denyWrite,
+      'deny_read' => :denyRead,
+      'allow_read' => :allowRead,
+      'allow_managed_read_paths_only' => :allowManagedReadPathsOnly
+    }.freeze
+
+    # Wire key => the kind of value CLI 2.1.287's sandbox schema accepts
+    # under it, for every wire key an attribute spells differently (read from
+    # the schema in the CLI binary and checked against the running CLI):
+    #
+    #   :boolean        true or false
+    #   :strings        an Array of Strings
+    #   :mach_services  an Array of Strings; a "*" only as the last character
+    #   :port           an Integer from 0 to 65535
+    #   :string_lists   a Hash whose values are Arrays of Strings
+    #
+    # One value outside its kind makes the CLI discard the whole --settings
+    # value, the sandbox and the permissions next to it. It lists the error
+    # in its get_settings response only, so the SDK is not told. A key in
+    # snake_case is one the CLI does not know and ignores, so it is renamed
+    # only when its value is of the kind listed here (see #rename). A kind
+    # that is too strict leaves a key without effect, as it was before the
+    # renaming existed; one that is too loose can cost a session its sandbox.
+    #
+    # :port is the strict side of what the CLI does. It takes any number it
+    # can read as a port, but an Integer too large for that (2**1024 and up,
+    # say 10**400) reaches it as a non-finite value and fails its schema.
+    SHAPES = {
+      boolean: %i[failIfUnavailable autoAllowBashIfSandboxed allowUnsandboxedCommands enableWeakerNestedSandbox
+                  enableWeakerNetworkIsolation allowManagedDomainsOnly allowAllUnixSockets allowLocalBinding
+                  allowManagedReadPathsOnly],
+      strings: %i[excludedCommands allowedDomains deniedDomains allowUnixSockets
+                  allowWrite denyWrite denyRead allowRead],
+      mach_services: %i[allowMachLookup],
+      port: %i[httpProxyPort socksProxyPort],
+      string_lists: %i[ignoreViolations]
+    }.flat_map { |kind, wire_keys| wire_keys.map { |wire| [wire, kind] } }.to_h.freeze
+
+    # A Hash +sandbox:+ as the CLI reads it: its known keys under their wire
+    # keys, at the top level and inside its network / filesystem, which may
+    # each be a Hash or the typed config. Other values are not rewritten:
+    # ignore_violations and ripgrep hold structures of the CLI's own.
+    def self.normalize(sandbox)
+      normalized = rename(sandbox, TOP_LEVEL)
+      normalized[:network] = network(normalized[:network]) if normalized.key?(:network)
+      normalized[:filesystem] = filesystem(normalized[:filesystem]) if normalized.key?(:filesystem)
+      normalized
+    end
+
+    # A network section as the CLI reads it: the typed config's #to_h, or a
+    # Hash with its known keys renamed. Any other value is returned as it is.
+    def self.network(section)
+      case section
+      when SandboxNetworkConfig then section.to_h
+      when Hash then rename(section, NETWORK)
+      else section
+      end
+    end
+
+    # A filesystem section as the CLI reads it (see .network).
+    def self.filesystem(section)
+      case section
+      when SandboxFilesystemConfig then section.to_h
+      when Hash then rename(section, FILESYSTEM)
+      else section
+      end
+    end
+
+    # A known key ends up as the one Symbol #to_h emits, so the spellings of
+    # a field (attribute name or wire key, Symbol or String) cannot reach
+    # JSON.generate side by side: json 3.x raises on a key given as a Symbol
+    # and as a String, 2.x writes it twice. When a Hash carries both
+    # spellings of a field the wire spelling wins, whichever comes first;
+    # between two keys in the same spelling the later one does.
+    #
+    # A known key holding nil is left out, as #to_h leaves out a nil
+    # attribute. The CLI rejects null under every one of these keys, and
+    # when it does it drops the whole --settings value, sandbox included.
+    #
+    # A key in snake_case is renamed only when the CLI accepts its value
+    # under the wire key (SHAPES). Otherwise it is sent as written, which
+    # the CLI ignores, as it ignored every snake_case key before: renaming
+    # must not be what makes the CLI drop the settings. A key the caller
+    # wrote in wire spelling is not looked at; it goes out as it always did.
+    def self.rename(hash, table)
+      renamed = {}
+      wire_spelled = {}
+      hash.each do |key, value|
+        name = key.to_s
+        wire = table[name] || table.each_value.find { |candidate| candidate.name == name }
+        next if wire && value.nil?
+
+        if wire && wire.name == name
+          wire_spelled[wire] = true
+          renamed[wire] = value
+        elsif wire && well_shaped?(wire, value)
+          renamed[wire] = value unless wire_spelled.key?(wire)
+        else
+          renamed[key] = value
+        end
+      end
+      renamed
+    end
+
+    # Whether the CLI accepts +value+ under +wire+. A key without a kind is
+    # answered false, the side that cannot cost the sandbox.
+    def self.well_shaped?(wire, value)
+      case SHAPES[wire]
+      when :boolean then [true, false].include?(value)
+      when :strings then strings?(value)
+      when :mach_services then strings?(value) && value.none? { |name| name.delete_suffix('*').include?('*') }
+      when :port then value.is_a?(Integer) && value.between?(0, 65_535)
+      when :string_lists then value.is_a?(Hash) && value.each_value.all? { |list| strings?(list) }
+      else false
+      end
+    end
+
+    def self.strings?(value)
+      value.is_a?(Array) && value.all?(String)
+    end
+    private_class_method :rename, :well_shaped?, :strings?
+  end
+
   # API-side task budget in tokens.
   # When set, the model is made aware of its remaining token budget so it can
   # pace tool use and wrap up before the limit.