claude-agent-sdk 1.1.0 → 1.2.0

data/docs/types.md

@@ -82,9 +82,24 @@ currently plain classes, not `Type`s: use their snake_case accessors
 ```ruby
 # Union type of all possible messages
 Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage |
-          StreamEvent | RateLimitEvent | ConversationResetMessage
+          StreamEvent | RateLimitEvent | ConversationResetMessage |
+          ToolProgressMessage | AuthStatusMessage | ToolUseSummaryMessage |
+          PromptSuggestionMessage
 ```
 
+This is everything the block of `query()`, `ask`, `Client#receive_messages` and
+`Client#receive_response` can receive. `SystemMessage` stands for its typed
+subclasses as well (`InitMessage`, `TaskStartedMessage`, ...; see
+[System and progress messages](#system-and-progress-messages)): each of them
+`is_a?(SystemMessage)`. The other ten classes share nothing but the SDK's
+`Type` base class.
+
+A message type this SDK version does not know is skipped before it reaches
+your block, and a `system` message with an unknown `subtype` arrives as a plain
+`SystemMessage` (`subtype` and `data` set). Give a `case` over messages an
+`else` that ignores the rest: a later gem release can add a class to this
+list.
+
 ### UserMessage
 
 User input message.
@@ -108,11 +123,20 @@ class AssistantMessage
   attr_accessor :content,            # Array<ContentBlock>
                 :model,              # String
                 :parent_tool_use_id, # String | nil
-                :error,              # String | nil ('authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'unknown')
-                :usage               # Hash | nil - Token usage info from the API response
+                :error,              # String | nil - see ASSISTANT_MESSAGE_ERRORS below
+                :usage,              # Hash | nil - Token usage info from the API response
+                :message_id,         # String | nil - the API message id
+                :stop_reason,        # String | nil
+                :session_id,         # String | nil
+                :uuid                # String | nil - UUID of this message in the transcript
 end
 ```
 
+`error` is passed through from the CLI. The values this SDK version knows are
+in `ASSISTANT_MESSAGE_ERRORS`: `authentication_failed`, `billing_error`,
+`rate_limit`, `invalid_request`, `server_error`, `max_output_tokens`,
+`unknown`. A newer CLI can send others.
+
 ### SystemMessage
 
 System message with metadata. Task lifecycle events are typed subclasses.
@@ -120,7 +144,7 @@ System message with metadata. Task lifecycle events are typed subclasses.
 ```ruby
 class SystemMessage
   attr_accessor :subtype,  # String ('init', 'task_started', 'task_progress', 'task_notification', 'task_updated', etc.)
-                :data      # Hash
+                :data      # Hash - the frame's own `data` value when that is neither nil nor false, otherwise the whole frame (see below)
 end
 
 # Typed subclasses (all inherit from SystemMessage, so is_a?(SystemMessage) still works)
@@ -175,6 +199,40 @@ end
 
 See [subagent capabilities](subagents.md) for the contracts behind these fields.
 
+### System and progress messages
+
+The remaining typed messages. An attribute the CLI did not send reads `nil`,
+with two exceptions on `RateLimitEvent`: `rate_limit_info` is then an empty
+`RateLimitInfo`, and `RateLimitEvent#data` is always the whole event as a
+Symbol-keyed Hash. The first twelve are `SystemMessage` subclasses (wire
+`type` is `system`), so they also have `subtype` and `data`. Their `data` is
+the whole frame as a Symbol-keyed Hash, unless the frame carries a `data`
+value of its own that is neither `nil` nor `false`: then `data` is that
+value, and the frame is not kept. A frame whose `data` is `nil` or `false`
+reads like one without the key: `data` is the whole frame. The last six are
+message types of their own.
+
+| Class | Wire type | Attributes | Notes |
+|-------|-----------|------------|-------|
+| `InitMessage` | `system` / `init` | `uuid`, `session_id`, `model`, `cwd`, `tools`, `mcp_servers`, `agents`, `skills`, `plugins`, `slash_commands`, `permission_mode`, `claude_code_version`, `api_key_source`, `betas`, `output_style`, `fast_mode_state` | Start of every turn, with the session as the CLI sees it (so a multi-query `Client` session receives one per query) |
+| `CompactBoundaryMessage` | `system` / `compact_boundary` | `uuid`, `session_id`, `compact_metadata` (a `CompactMetadata`: `pre_tokens`, `post_tokens`, `trigger`, `preserved_segment`, `custom_instructions`) | Context compaction completed |
+| `StatusMessage` | `system` / `status` | `uuid`, `session_id`, `status`, `permission_mode` | Compacting status, permission mode changes |
+| `APIRetryMessage` | `system` / `api_retry` | `uuid`, `session_id`, `attempt`, `max_retries`, `retry_delay_ms`, `error_status`, `error` | The CLI is retrying an API request |
+| `LocalCommandOutputMessage` | `system` / `local_command_output` | `uuid`, `session_id`, `content` | Output of a local command |
+| `HookStartedMessage` | `system` / `hook_started` | `uuid`, `session_id`, `hook_id`, `hook_name`, `hook_event` | Hook lifecycle; `include_hook_events: true` asks the CLI for all of these |
+| `HookProgressMessage` | `system` / `hook_progress` | the `HookStartedMessage` attributes, `stdout`, `stderr`, `output` | |
+| `HookResponseMessage` | `system` / `hook_response` | the `HookProgressMessage` attributes, `exit_code`, `outcome` (`'success'`, `'error'`, `'cancelled'`) | |
+| `SessionStateChangedMessage` | `system` / `session_state_changed` | `uuid`, `session_id`, `state` (`'idle'`, `'running'`, `'requires_action'`) | Reaches your block only with `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1` in `env` |
+| `FilesPersistedMessage` | `system` / `files_persisted` | `uuid`, `session_id`, `files`, `failed`, `processed_at` | |
+| `ElicitationCompleteMessage` | `system` / `elicitation_complete` | `uuid`, `session_id`, `mcp_server_name`, `elicitation_id` | |
+| `MirrorErrorMessage` | `system` / `mirror_error` | `uuid`, `session_id`, `error`, `key` | Produced by the SDK, not the CLI: a `session_store` mirror batch was dropped (see [Sessions](sessions.md#mirroring-to-a-sessionstore)) |
+| `ToolProgressMessage` | `tool_progress` | `uuid`, `session_id`, `tool_use_id`, `tool_name`, `parent_tool_use_id`, `elapsed_time_seconds`, `task_id` | Progress of a running tool call |
+| `ToolUseSummaryMessage` | `tool_use_summary` | `uuid`, `session_id`, `summary`, `preceding_tool_use_ids` | |
+| `AuthStatusMessage` | `auth_status` | `uuid`, `session_id`, `is_authenticating`, `output`, `error` | |
+| `PromptSuggestionMessage` | `prompt_suggestion` | `uuid`, `session_id`, `suggestion` | |
+| `StreamEvent` | `stream_event` | `uuid`, `session_id`, `event` (the raw API stream event, Symbol keys), `parent_tool_use_id` | Partial message chunks; only with `include_partial_messages: true` |
+| `RateLimitEvent` | `rate_limit_event` | `uuid`, `session_id`, `rate_limit_info` (a `RateLimitInfo`: `status`, `resets_at`, `rate_limit_type`, `utilization`, `overage_status`, `overage_resets_at`, `overage_disabled_reason`, `raw`), `data` (the whole event) | Rate limit information changed |
+
 ### ResultMessage
 
 Final result message with cost and usage information.
@@ -199,10 +257,16 @@ class ResultMessage
                 :fast_mode_state,    # String | nil ('off', 'cooldown', 'on')
                 :api_error_status,   # Integer | nil (HTTP status on api_error subtype)
                 :terminal_reason,    # String | nil (see below)
-                :origin              # Hash | nil - origin of the triggering user message (see below)
+                :origin,             # Hash | nil - origin of the triggering user message (see below)
+                :deferred_tool_use   # DeferredToolUse | nil (see below)
 end
 ```
 
+`deferred_tool_use` is set when a `PreToolUse` hook answered a tool call with
+`permissionDecision: 'defer'`: a `DeferredToolUse` with the `id`, `name` and
+`input` of the call that was put off. The session can be resumed later to run
+the deferred call.
+
 `terminal_reason` says why the query loop ended (`"completed"`, `"max_turns"`,
 `"aborted_streaming"`, ...). `"aborted_streaming"` / `"aborted_tools"` mean the
 turn was cancelled via `Client#interrupt`. `nil` when the CLI did not report
@@ -287,7 +351,8 @@ cached session title). Read the new session id from the next message.
 
 ```ruby
 # Union type of all content blocks
-ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | UnknownBlock
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock |
+               ServerToolUseBlock | ServerToolResultBlock | UnknownBlock
 ```
 
 ### TextBlock
@@ -333,6 +398,30 @@ class ToolResultBlock
 end
 ```
 
+### ServerToolUseBlock and ServerToolResultBlock
+
+`ServerToolUseBlock` is a call to a tool that runs server-side (wire type
+`server_tool_use`), and `ServerToolResultBlock` is the advisor tool's result
+(wire type `advisor_tool_result`). An
+[advisor](configuration.md#advisor-model) consultation shows up as a
+`ServerToolUseBlock` named `'advisor'` and a `ServerToolResultBlock`. Any
+other block type, a different server-side result included, arrives as an
+`UnknownBlock`.
+
+```ruby
+class ServerToolUseBlock
+  attr_accessor :id,    # String
+                :name,  # String ('advisor', ...)
+                :input  # Hash
+end
+
+class ServerToolResultBlock
+  attr_accessor :tool_use_id,  # String
+                :content,      # the result payload, as the CLI sent it
+                :is_error      # Boolean | nil
+end
+```
+
 ### UnknownBlock
 
 Generic content block for types the SDK doesn't explicitly handle (e.g., `document` for PDFs, `image` for inline images). Preserves the raw data for forward compatibility with newer CLI versions.
@@ -349,7 +438,7 @@ end
 | Type | Description |
 |------|-------------|
 | `Configuration` | Global defaults via `ClaudeAgentSDK.configure` block |
-| `ClaudeAgentOptions` | Main configuration for queries and clients |
+| `ClaudeAgentOptions` | Main configuration for queries and clients. Every option is listed in the [options reference](options.md) |
 | `HookMatcher` | Hook configuration with matcher pattern and timeout |
 | `PermissionResultAllow` | Permission callback result to allow tool use |
 | `PermissionResultDeny` | Permission callback result to deny tool use |
@@ -368,11 +457,11 @@ end
 | `McpToolInfo` | MCP tool name, description, and annotations |
 | `McpToolAnnotations` | MCP tool annotation hints (`read_only`, `destructive`, `open_world`) |
 | `TaskUsage` | Typed usage data (`total_tokens`, `tool_uses`, `duration_ms`) with `from_hash` factory |
-| `SDKSessionInfo` | Session metadata from `list_sessions` |
+| `SDKSessionInfo` | Session metadata from `list_sessions` and `get_session_info` |
 | `SessionMessage` | Single message from `get_session_messages` |
-| `SandboxSettings` | Sandbox settings for isolated command execution |
+| `SandboxSettings` | Sandbox settings for isolated command execution. `ignore_violations` (which violations to ignore) is a plain Hash |
 | `SandboxNetworkConfig` | Network configuration for sandbox |
-| `SandboxIgnoreViolations` | Configure which sandbox violations to ignore |
+| `SandboxFilesystemConfig` | Filesystem configuration for sandbox (`allow_write`, `deny_write`, `deny_read`, `allow_read`, `allow_managed_read_paths_only`) |
 | `SystemPromptPreset` | System prompt preset configuration (`preset`, `append`, `exclude_dynamic_sections`, `snapshot`) |
 | `SystemPromptCustom` | Custom system prompt configuration — the object form of a String prompt, so `snapshot` can be set alongside it |
 | `SystemPromptFile` | System prompt loaded from a file path |
@@ -403,7 +492,7 @@ Accepted: Symbol or String keys, snake_case or camelCase spellings, and the fixe
 
 `#[]`, `#[]=` and the camelCase readers (`msg[:session_id]`, `msg['sessionId']`, `msg.sessionId`) are public API for a type's **attributes**: the fields it declares, plus predicates such as `options.forkSession?`. Methods your own code adds to a subclass (an `attr_accessor`, a hand-written reader or setter, a mixin's accessors, a singleton method) count as attributes too.
 
-A name that is not an attribute behaves like an undefined one: `#[]` returns `nil`, `#[]=` ignores it (on the strict types above it raises `ArgumentError`), a camelCase call raises `NoMethodError`, and `respond_to?` answers `false`. So `msg[:to_h]` is `nil`, `msg['freeze']` does not freeze the message, and `msg.toH` raises; call the method directly instead (`msg.to_h`). `UserMessage#text` and `AssistantMessage#text` are convenience methods, not attributes.
+A name that is not an attribute behaves like an undefined one: `#[]` returns `nil`, `#[]=` ignores it (on the strict types above it raises `ArgumentError`), a camelCase call raises `NoMethodError`, and `respond_to?` answers `false`. So `msg[:to_h]` is `nil`, `msg['freeze']` does not freeze the message, and `msg.toH` raises; call the method directly instead (`msg.to_h`). `#[]` only reads: a writer's name, as in `msg['session_id=']`, is `nil` too. `UserMessage#text` and `AssistantMessage#text` are convenience methods, not attributes.
 
 (Through 0.37 these accessors reached any public method, with a one-time warning in 0.37.)
 

data/lib/claude_agent_sdk/cli_installer.rb

@@ -53,13 +53,18 @@ module ClaudeAgentSDK
     # Single source of truth: bumped here (and only here) by
     # .github/workflows/cli-pin-bump.yml or a Python-sync release, so a
     # Dependabot bump of the gem carries the CLI forward with it.
-    PINNED_CLI_VERSION = '2.1.285'
+    PINNED_CLI_VERSION = '2.1.288'
     # @api private
     BINARY_NAME = 'claude'
     # @api private
     VERSION_FILE = 'VERSION'
     # @api private
     LOCK_FILE = '.install.lock'
+    # How often a waiting installer retries the install lock. See
+    # .with_install_lock for why it polls instead of blocking in flock.
+    #
+    # @api private
+    LOCK_POLL_SECONDS = 0.05
     # Relative to .root (Dir.pwd when unset), resolved at CALL time by
     # .default_dir — an absolute constant would freeze the working directory
     # as of require time, which is wrong for anything that chdirs (Rake
@@ -168,6 +173,11 @@ module ClaudeAgentSDK
         # +max_bytes+ (the manifest's declared size, when it has one) aborts a
         # response that runs long instead of filling the disk before the
         # checksum gets a chance to reject it.
+        #
+        # The file is fsynced before it is closed: the caller renames it into
+        # place, and a rename only orders metadata. Without the sync, a power
+        # loss shortly after an install could leave the published name
+        # pointing at an empty or partial file.
         def download_to(url, path, max_bytes: nil)
           with_response(url) do |response|
             written = 0
@@ -180,6 +190,7 @@ module ClaudeAgentSDK
 
                 file.write(chunk)
               end
+              file.fsync
             end
           end
           path
@@ -195,9 +206,9 @@ module ClaudeAgentSDK
           uri = url.is_a?(URI::Generic) ? url : URI(url.to_s)
           raise CLIInstallError, "Refusing to fetch non-HTTPS URL: #{uri}" unless uri.is_a?(URI::HTTPS)
 
-          Net::HTTP.start(uri.host, uri.port, use_ssl: true,
-                                              open_timeout: OPEN_TIMEOUT_SECONDS,
-                                              read_timeout: READ_TIMEOUT_SECONDS) do |http|
+          Net::HTTP.start(uri.host, uri.port, *proxy_args(uri), use_ssl: true,
+                                                                open_timeout: OPEN_TIMEOUT_SECONDS,
+                                                                read_timeout: READ_TIMEOUT_SECONDS) do |http|
             http.request(Net::HTTP::Get.new(uri)) do |response|
               # Branch on the status BEFORE touching the body: a redirect or an
               # error page must never be streamed into the target file.
@@ -213,6 +224,35 @@ module ClaudeAgentSDK
           raise CLIInstallError, "Failed to fetch #{url}: #{e.class}: #{e.message}"
         end
 
+        # The proxy arguments for Net::HTTP.start: address, port, user,
+        # password — or none.
+        #
+        # Left to itself, Net::HTTP looks its proxy up as if for an http://
+        # URL: it reads http_proxy even though this connection is TLS. An
+        # environment that exports only HTTPS_PROXY (what curl, RubyGems and
+        # the CLI itself read for an https URL) was therefore bypassed.
+        # URI#find_proxy on the https URL reads https_proxy / HTTPS_PROXY and
+        # applies no_proxy / NO_PROXY; the proxy it names is passed
+        # explicitly, its credentials percent-decoded the way Net::HTTP
+        # decodes the ones it finds itself.
+        #
+        # No arguments means "as before": Net::HTTP's own lookup (http_proxy)
+        # stays in charge. That is the answer when the variable is unset or
+        # no_proxy excludes the host, and also when its value is nothing
+        # Net::HTTP can use as an HTTP proxy — no scheme, socks5://, https://,
+        # not a URL at all. Such a value was ignored before and still is,
+        # rather than turning a download that works directly into a failure.
+        # ALL_PROXY is not consulted.
+        def proxy_args(uri)
+          proxy = uri.find_proxy
+          return [] unless proxy.instance_of?(URI::HTTP) && !proxy.hostname.to_s.empty?
+
+          credentials = [proxy.user, proxy.password].map { |part| part && URI.decode_www_form_component(part) }
+          [proxy.hostname, proxy.port, *credentials]
+        rescue URI::InvalidURIError
+          []
+        end
+
         def follow_redirect(uri, response, redirects_left, &)
           raise CLIInstallError, "Too many redirects while fetching #{uri}" if redirects_left <= 0
 
@@ -322,11 +362,14 @@ module ClaudeAgentSDK
         # Atomic: an unpredictable temp name opened O_EXCL, then renamed over
         # the old file. Without this a reader could observe a half-written
         # VERSION, or (worse) the previous version paired with a new binary.
+        # Fsynced before the rename, so that after a power loss VERSION is
+        # the old file or the new one, not an empty one.
         def write(dir, version, checksum, platform)
           tmp = File.join(dir, "#{VERSION_FILE}.#{SecureRandom.hex(8)}.tmp")
           begin
             File.open(tmp, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
               file.write("#{version}\n#{checksum}\n#{platform}\n")
+              file.fsync
             end
             File.rename(tmp, File.join(dir, VERSION_FILE))
           ensure
@@ -376,7 +419,7 @@ module ClaudeAgentSDK
       # +version+ is 'stable', 'latest', or a concrete version like '2.1.220'.
       #
       # Idempotent and safe to run concurrently: an exclusive lock on
-      # dir/.install.lock covers the whole check-download-place-record
+      # dir/.install.lock covers the whole check-download-record-place
       # sequence, so parallel boots (Docker layers, `foreman start`, CI matrix
       # jobs sharing a cache) never race each other into a partially written
       # binary — the loser of the race observes a finished install.
@@ -386,6 +429,12 @@ module ClaudeAgentSDK
       # touches the network: repeat boots must work offline (with a pinned
       # version — a dist-tag has to be re-resolved to be resolved at all).
       #
+      # That shortcut also holds in a directory this process cannot write (an
+      # image built as root and run as another user, a read-only root
+      # filesystem): a concrete version that is already installed and intact
+      # is returned. Anything that would need a write — a dist-tag, another
+      # version, a damaged binary — raises there.
+      #
       # An upgrade never destroys a working install: see #publish.
       def install(version: 'stable', dir: nil)
         dir = File.expand_path(dir || default_dir)
@@ -396,7 +445,19 @@ module ClaudeAgentSDK
         requested = Release.validate_version(version)
         binary = File.join(dir, BINARY_NAME)
         FileUtils.mkdir_p(dir)
-        with_install_lock(dir) do
+        begin
+          lock = open_lock_file(dir)
+        rescue Errno::EACCES, Errno::EROFS, Errno::EPERM
+          # The lock file cannot be opened for writing, so nothing can be
+          # installed here — and nothing has to be when the requested version
+          # already is (see .installed_without_lock?). This rescue covers
+          # OPENING the lock file and nothing else: a permission error raised
+          # inside the critical section must keep failing the install.
+          raise unless installed_without_lock?(dir, requested)
+
+          return binary
+        end
+        with_install_lock(lock) do
           sweep_stale_temp_files(dir)
           resolved = Release.resolve_version(requested)
           platform = Platform.detect
@@ -410,8 +471,11 @@ module ClaudeAgentSDK
       rescue SystemCallError, IOError => e
         # Filesystem failures (EACCES on the install dir, ENOSPC mid-download,
         # a read-only mount) reach callers as CLIInstallError like every other
-        # install failure; `cause` keeps the original for debugging.
-        raise CLIInstallError, "Failed to install the Claude Code CLI into #{dir}: #{e.class}: #{e.message}"
+        # install failure; `cause` keeps the original for debugging. +dir+ is
+        # still nil when resolving the default directory is what failed (the
+        # working directory was deleted): name it by its relative path then.
+        raise CLIInstallError,
+              "Failed to install the Claude Code CLI into #{dir || DEFAULT_DIR}: #{e.class}: #{e.message}"
       end
 
       # Install PINNED_CLI_VERSION — the version this gem release was tested
@@ -441,20 +505,50 @@ module ClaudeAgentSDK
       private
 
       # Cross-process mutual exclusion for the whole install. flock is
-      # advisory and per open file description, so concurrent threads in one
-      # process contend here exactly like separate processes do.
-      def with_install_lock(dir)
+      # advisory and per open file description, so concurrent threads — and
+      # concurrent fibers — in one process contend here exactly like separate
+      # processes do.
+      #
+      # The lock is polled (LOCK_NB + sleep), never taken with a blocking
+      # LOCK_EX. File#flock has no Fiber-scheduler hook, so a blocking call
+      # parks the whole reactor THREAD; when the holder is another fiber of
+      # that reactor, waiting inside the critical section for the network, it
+      # is never resumed and neither install returns. Kernel#sleep yields to
+      # a scheduler and is an ordinary sleep on a plain thread. Mutual
+      # exclusion is the same either way; like flock itself, the order in
+      # which waiters get the lock is unspecified.
+      #
+      # +lock+ is the open lock file (see .open_lock_file); it is closed here.
+      def with_install_lock(lock)
+        sleep(LOCK_POLL_SECONDS) until lock.flock(File::LOCK_EX | File::LOCK_NB)
+        begin
+          yield
+        ensure
+          lock.flock(File::LOCK_UN)
+        end
+      ensure
+        lock.close
+      end
+
+      # Opened read-write and created when missing. Kept apart from
+      # .with_install_lock so that .install can tell a lock file that cannot
+      # be opened from a failure inside the critical section.
+      def open_lock_file(dir)
         flags = File::RDWR | File::CREAT
         # Never follow a symlink planted at the lock path.
         flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
-        File.open(File.join(dir, LOCK_FILE), flags, 0o644) do |lock|
-          lock.flock(File::LOCK_EX)
-          begin
-            yield
-          ensure
-            lock.flock(File::LOCK_UN)
-          end
-        end
+        File.open(File.join(dir, LOCK_FILE), flags, 0o644)
+      end
+
+      # Whether .install can answer +requested+ without the install lock: it
+      # has to be a concrete version — a dist-tag must be resolved and may
+      # have to be published, which needs the lock — whose binary is in place
+      # and re-hashes to the checksum recorded for it. This is the lock-free
+      # read .installed_path already documents (#publish only ever renames a
+      # complete, verified binary into place) plus the re-hash, and it writes
+      # nothing.
+      def installed_without_lock?(dir, requested)
+        !DIST_TAGS.include?(requested) && installed?(dir, requested, Platform.detect)
       end
 
       # Remove temp files abandoned by an earlier install that died before its
@@ -503,17 +597,38 @@ module ClaudeAgentSDK
       # (The reverse order — rename then record — briefly published a binary
       # nothing vouched for, and a metadata failure then had to delete the
       # freshly renamed file, taking the previous working install with it.)
+      #
+      # Across a power loss, a rename only orders metadata. So the downloaded
+      # bytes (Http.download_to), the binary's executable mode (after its
+      # chmod, #fetch_verified) and the VERSION bytes (Metadata.write) are
+      # fsynced before their renames: each name then holds a complete file,
+      # the old one or the new one, never an empty, partial or
+      # non-executable one. The
+      # directory is synced after the rename so that an install that returned
+      # is still there afterwards; that sync is best-effort and cannot fail
+      # the install, which keeps the rename the last step that can.
       def publish(dir, binary, version, platform, entry)
         tmp = "#{binary}.download.#{SecureRandom.hex(8)}"
         begin
           fetch_verified(version, platform, entry, tmp)
           Metadata.write(dir, version, entry[:checksum], platform)
           File.rename(tmp, binary)
+          sync_directory(dir)
         ensure
           FileUtils.rm_f(tmp)
         end
       end
 
+      # Makes the renames in +dir+ durable (VERSION's and the binary's).
+      # Best-effort by necessity: it runs after the rename, where nothing may
+      # fail the install, and not every platform or filesystem can fsync a
+      # directory — some refuse to open one, others answer EINVAL or EBADF.
+      def sync_directory(dir)
+        File.open(dir, File::RDONLY, &:fsync)
+      rescue SystemCallError, IOError, NotImplementedError
+        nil
+      end
+
       # Download to an unpredictable sibling temp name (same filesystem, so the
       # rename is atomic; O_EXCL, so a pre-planted path or symlink cannot be
       # written through), bounded by the manifest's declared size, then verify
@@ -526,6 +641,12 @@ module ClaudeAgentSDK
         raise CLIInstallError, "Checksum mismatch for #{url}: expected #{expected}, got #{actual}" if actual != expected
 
         File.chmod(0o755, tmp)
+        # The mode is metadata of the file itself: the data fsync in
+        # Http.download_to came before it, and the directory sync after the
+        # rename does not cover it. Without this sync a power loss could bring
+        # the published binary back without its executable bit, and
+        # installed_path would skip it.
+        File.open(tmp, File::RDONLY, &:fsync)
       end
     end
   end

data/lib/claude_agent_sdk/command_builder.rb

@@ -76,7 +76,7 @@ module ClaudeAgentSDK
       when String
         cmd.push('--system-prompt', @options.system_prompt)
       when SystemPromptFile
-        cmd.push('--system-prompt-file', @options.system_prompt.path)
+        cmd.push('--system-prompt-file', path_string(@options.system_prompt.path))
       when SystemPromptCustom
         # The object form of a String prompt; snapshot travels on the
         # initialize request, not as a CLI flag.
@@ -90,12 +90,25 @@ module ClaudeAgentSDK
       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)
-      prompt_type = prompt_hash[:type] || prompt_hash['type']
-      case prompt_type
+      case hash_type(prompt_hash)
       when 'file'
         prompt_path = prompt_hash[:path] || prompt_hash['path']
-        cmd.push('--system-prompt-file', prompt_path) if prompt_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))
@@ -129,8 +142,12 @@ module ClaudeAgentSDK
     # Each listed name is validated before being formatted into a rule (see
     # #validate_skill_name). Both SDKs reject non-list, non-'all' shapes
     # loudly; this raises ArgumentError where Python raises TypeError.
+    #
+    # allowed_tools, like disallowed_tools, add_dirs and extra_args below, is
+    # nil when it was set to nil after construction (the readers are signed
+    # nilable); each use site reads nil as the constructor's default.
     def skills_defaults
-      allowed_tools = @options.allowed_tools.dup
+      allowed_tools = (@options.allowed_tools || []).dup
       setting_sources = @options.setting_sources&.dup
       skills = @options.skills
       return [allowed_tools, setting_sources] if skills.nil?
@@ -210,7 +227,8 @@ module ClaudeAgentSDK
     end
 
     def append_disallowed_tools(cmd)
-      cmd.push('--disallowedTools', @options.disallowed_tools.join(',')) unless @options.disallowed_tools.empty?
+      disallowed_tools = @options.disallowed_tools || []
+      cmd.push('--disallowedTools', disallowed_tools.join(',')) unless disallowed_tools.empty?
     end
 
     def append_max_turns(cmd)
@@ -301,16 +319,14 @@ module ClaudeAgentSDK
       settings_is_path = false
 
       if @options.settings
-        if @options.settings.is_a?(String)
+        if @options.settings.respond_to?(:to_path)
+          # A Pathname names a settings file; it is never tried as inline JSON.
+          settings_hash, settings_is_path = settings_file(cmd, @options.settings.to_path)
+        elsif @options.settings.is_a?(String)
           begin
             settings_hash = JSON.parse(@options.settings)
           rescue JSON::ParserError
-            if @options.sandbox.nil? # rubocop:disable Metrics/BlockNesting -- settings-is-a-path fallback inside the JSON parse rescue
-              settings_is_path = true
-              cmd.push('--settings', @options.settings)
-            else
-              settings_hash = load_settings_file(@options.settings)
-            end
+            settings_hash, settings_is_path = settings_file(cmd, @options.settings)
           end
         elsif @options.settings.is_a?(Hash)
           settings_hash = @options.settings.dup
@@ -318,12 +334,40 @@ module ClaudeAgentSDK
       end
 
       if !settings_is_path && !@options.sandbox.nil?
-        settings_hash[:sandbox] = @options.sandbox.is_a?(SandboxSettings) ? @options.sandbox.to_h : @options.sandbox
+        # The option replaces any sandbox section the settings carry. Settings
+        # 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)
       end
 
       cmd.push('--settings', JSON.generate(settings_hash)) if !settings_is_path && !settings_hash.empty?
     end
 
+    # --settings for a settings file, as [settings_hash, settings_is_path].
+    # Without a sandbox option the path itself is passed and the CLI reads
+    # the file. With one, the file is read here, so that the option can be
+    # folded into its content.
+    def settings_file(cmd, path)
+      return [load_settings_file(path), false] unless @options.sandbox.nil?
+
+      cmd.push('--settings', path)
+      [{}, 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
 
@@ -408,10 +452,13 @@ module ClaudeAgentSDK
       when Array
         tools_value = @options.tools.empty? ? '' : @options.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')
       when Hash
-        if (@options.tools[:type] || @options.tools['type']) == 'preset'
+        if hash_type(@options.tools) == 'preset'
           cmd.push('--tools', 'default')
         else
           cmd.push('--tools', JSON.generate(@options.tools))
@@ -422,13 +469,7 @@ module ClaudeAgentSDK
     def append_output_format(cmd)
       return unless @options.output_format
 
-      schema = if @options.output_format.is_a?(Hash) && @options.output_format[:type] == 'json_schema'
-                 @options.output_format[:schema]
-               elsif @options.output_format.is_a?(Hash) && @options.output_format['type'] == 'json_schema'
-                 @options.output_format['schema']
-               else
-                 @options.output_format
-               end
+      schema = 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`).
@@ -438,8 +479,24 @@ 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) }
+      (@options.add_dirs || []).each { |dir| cmd.push('--add-dir', dir.to_s) }
     end
 
     def append_mcp_servers(cmd)
@@ -484,15 +541,15 @@ module ClaudeAgentSDK
 
       @options.plugins.each do |plugin|
         plugin_config = plugin.is_a?(SdkPluginConfig) ? plugin.to_h : plugin
-        plugin_type = plugin_config[:type] || plugin_config['type']
         plugin_path = plugin_config[:path] || plugin_config['path']
 
-        unless %w[local plugin].include?(plugin_type)
+        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}"
         end
         next unless plugin_path
 
-        cmd.push('--plugin-dir', plugin_path)
+        cmd.push('--plugin-dir', path_string(plugin_path))
       end
     end
 
@@ -503,7 +560,7 @@ module ClaudeAgentSDK
     end
 
     def append_extra_args(cmd)
-      @options.extra_args.each do |flag, value|
+      (@options.extra_args || {}).each do |flag, value|
         unless EXTRA_ARG_FLAG_REGEXP.match?(flag)
           raise ArgumentError, "Invalid extra_args flag name: #{flag.inspect} (expected lowercase kebab-case)"
         end