claude-agent-sdk 0.36.0 → 1.0.0

data/docs/types.md

@@ -1,6 +1,81 @@
 # Types Reference
 
-See [lib/claude_agent_sdk/types.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types.rb) for complete type definitions.
+See [lib/claude_agent_sdk/types/](https://github.com/ya-luotao/claude-agent-sdk-ruby/tree/main/lib/claude_agent_sdk/types) for complete type definitions (one file per area; `types.rb` loads them all).
+
+## Hash keys
+
+Where the SDK hands you a plain Hash rather than a typed object, its key form
+depends on where the data came from. One rule covers every case:
+
+| Source | Key form | Examples |
+|--------|----------|----------|
+| The CLI's live stream-JSON, passed through as-is | **Symbols**, spelled exactly as on the wire | `UserMessage#origin`, `ResultMessage#origin`, `AssistantMessage#usage`, `ResultMessage#usage`, `ResultMessage#model_usage`, `ResultMessage#structured_output`, `UserMessage#tool_use_result`, `SystemMessage#data`, hook `tool_input`, the `can_use_tool` `input`, SDK MCP tool and prompt `args`, `Client#mcp_status`, `Client#context_usage` |
+| Transcripts read from disk or a `SessionStore` | **Strings**, spelled as in the JSONL | `SessionMessage#message`, `get_subagent_metadata`, `SessionStore` keys and entries, `fold_session_summary` input and output |
+
+"As on the wire" means the SDK does not rewrite key names. Structures the CLI
+generates use camelCase (`origin[:fromSession]`, `model_usage` values'
+`:inputTokens` / `:costUSD`, `client.mcp_status[:mcpServers]`), while objects
+the CLI relays from the API keep their snake_case (`usage[:input_tokens]`).
+Nesting follows the same rule all the way down, including keys that are data
+rather than field names: `model_usage` is keyed by model-name Symbols
+(`result.model_usage.each { |model, u| puts "#{model}: $#{u[:costUSD]}" }`).
+
+The wrong key form reads as `nil` rather than raising, so look up the source
+before indexing: `tool_input['command']` on a hook input, or
+`meta[:toolUseId]` on subagent metadata, silently returns `nil`. The Python
+SDK uses String keys everywhere; do not port its lookups literally.
+
+The Symbol side of the rule relies on the transport parsing each line with
+`JSON.parse(line, symbolize_names: true)`. The built-in
+`SubprocessCLITransport` does; a [custom transport](client.md#custom-transport)
+must too.
+
+## Reading and writing attributes
+
+The SDK's typed objects (messages, content blocks, hook inputs and outputs,
+option objects: everything built on `ClaudeAgentSDK::Type`) accept the same
+attribute name in several spellings. These accessors are public API:
+
+```ruby
+msg.session_id          # the attr_accessor
+msg[:session_id]        # Symbol or String, snake_case or camelCase:
+msg['session_id']       #   all four read the same attribute
+msg[:sessionId]
+msg['sessionId']
+msg.sessionId           # camelCase reader (also answers respond_to?)
+```
+
+`#[]` returns `nil` for a name the type does not define, while a misspelled
+method call such as `msg.nope` raises `NoMethodError`. These accessors reach a type's
+**attributes** only; any other method (`to_h`, `freeze`, ...) counts as undefined —
+see [Attributes Only](#attributes-only).
+
+`#[]=` assigns through the attribute's setter, with the same name
+normalization, and returns the assigned value:
+
+```ruby
+msg[:result] = 'edited' # same as msg.result = 'edited'
+```
+
+- It **changes the object you received**. Messages are not frozen or copied
+  on delivery, so a change is visible to anything else holding the same
+  object (for example an observer that received it before your block did).
+  Copy first if you need the original.
+- A name the type does not define is ignored on the types the SDK parses from
+  CLI output. `ClaudeAgentOptions` raises `ArgumentError` for an unknown key (as
+  its constructor and `dup_with` do), and so do the value types you build and
+  pass in — see [Unknown Keys](#unknown-keys).
+- Discriminator fields (`type` on the MCP server and system-prompt configs,
+  `behavior` on `PermissionResultAllow` / `PermissionResultDeny`,
+  `hook_event_name` on hook inputs and outputs) are read-only, so
+  assigning them has no effect.
+
+Constructors accept the same spellings: `ResultMessage.new('sessionId' => 'abc')`
+is equivalent to `ResultMessage.new(session_id: 'abc')`.
+
+`SDKSessionInfo` and `SessionMessage` (returned by the session functions) are
+currently plain classes, not `Type`s: use their snake_case accessors
+(`info.session_id`); they have no `#[]`, `#[]=` or camelCase readers.
 
 ## Message Types
 
@@ -134,8 +209,9 @@ turn was cancelled via `Client#interrupt`. `nil` when the CLI did not report
 one (older CLIs, or a result that bypassed the query loop such as a local
 slash command).
 
-`model_usage` values are passed through verbatim from the CLI, so their keys
-are camelCase (the TypeScript/Python SDKs' `ModelUsage` shape): `inputTokens`,
+`model_usage` is passed through verbatim from the CLI (see [Hash keys](#hash-keys)):
+it is keyed by model-name Symbols (`:"claude-sonnet-4-5"`), and each value's
+keys are camelCase Symbols (the TypeScript/Python SDKs' `ModelUsage` shape): `inputTokens`,
 `outputTokens`, `cacheReadInputTokens`, `cacheCreationInputTokens`,
 `webSearchRequests`, `costUSD`, `contextWindow`, `maxOutputTokens`, plus
 optional `canonicalModel` (canonical id used for the pricing lookup, which can
@@ -287,7 +363,7 @@ end
 | `McpHttpServerConfig` | MCP server config for HTTP transport |
 | `SdkPluginConfig` | SDK plugin configuration |
 | `McpServerStatus` | Status of a single MCP server connection (with `.parse`) |
-| `McpStatusResponse` | Response from `get_mcp_status` containing all server statuses (with `.parse`) |
+| `McpStatusResponse` | Typed view of the `Client#mcp_status` / `#get_mcp_status` Hash: `McpStatusResponse.parse(client.mcp_status).mcp_servers` is an Array of `McpServerStatus`. The client itself returns the raw Hash (see [client.md](client.md#mcp-status-and-context-usage-return-hashes)) |
 | `McpServerInfo` | MCP server name and version |
 | `McpToolInfo` | MCP tool name, description, and annotations |
 | `McpToolAnnotations` | MCP tool annotation hints (`read_only`, `destructive`, `open_world`) |
@@ -302,6 +378,35 @@ end
 | `SystemPromptFile` | System prompt loaded from a file path |
 | `ToolsPreset` | Tools preset configuration for base tools selection |
 
+### Unknown Keys
+
+`ClaudeAgentOptions` and the value types you build and pass *in* raise `ArgumentError` on a key they do not define, naming the class, the key and the keys it accepts:
+
+```ruby
+ClaudeAgentSDK::HookMatcher.new(matchr: 'Bash', hooks: [check])
+# ArgumentError: ClaudeAgentSDK::HookMatcher: unknown attribute :matchr (known: hooks, matcher, timeout)
+```
+
+This covers `.new` and `#[]=` on:
+
+- option values: `AgentDefinition`, `SandboxSettings`, `SandboxNetworkConfig`, `SandboxFilesystemConfig`, `ThinkingConfigAdaptive` / `Enabled` / `Disabled`, `TaskBudget`, `SystemPromptPreset` / `Custom` / `File`, `ToolsPreset`, `SdkPluginConfig`, `McpStdioServerConfig`, `McpSSEServerConfig`, `McpHttpServerConfig`, `McpSdkServerConfig`
+- `HookMatcher` and hook outputs: `SyncHookJSONOutput`, `AsyncHookJSONOutput`, every `*HookSpecificOutput`
+- `PermissionResultAllow`, `PermissionResultDeny`, `PermissionUpdate`, `PermissionRuleValue`
+
+A nested value is checked as its own type: `PermissionUpdate.new(rules: [{ rule_contnt: 'x' }])` raises naming `PermissionRuleValue`.
+
+Accepted: Symbol or String keys, snake_case or camelCase spellings, and the fixed discriminator a type sets itself (`type`, `hook_event_name`, `behavior`), so on a type that defines its own `#to_h` (the MCP server configs, `SandboxSettings`, the system prompt types, the hook outputs, ...) `klass.new(value.to_h)` round-trips. Types the SDK parses from CLI output (messages, content blocks, hook inputs, `ToolPermissionContext`, the MCP status types) stay lenient, so a field added by a newer CLI is ignored rather than raising, and so does every construction through `.from_hash` or `.wrap`. Use those two for data you did not write yourself, such as a Hash deserialized from the CLI or from storage.
+
+(0.37 printed a one-time warning here and ignored the key; 1.0 raises. See [UPGRADING-1.0.md](../UPGRADING-1.0.md).)
+
+### Attributes Only
+
+`#[]`, `#[]=` 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.
+
+(Through 0.37 these accessors reached any public method, with a one-time warning in 0.37.)
+
 ## Constants
 
 | Constant | Description |

data/lib/claude_agent_sdk/cli_installer.rb

@@ -30,16 +30,22 @@ module ClaudeAgentSDK
   #   ClaudeAgentSDK::CLIInstaller.install_pinned
   # @example Pin a version of your own
   #   ClaudeAgentSDK::CLIInstaller.install(version: '2.1.220')
-  module CLIInstaller
+  module CLIInstaller # rubocop:disable Metrics/ModuleLength -- Http/Platform/Release/Metadata submodules in one file
+    # @api private
     BASE_URL = 'https://downloads.claude.ai/claude-code-releases'
     # Dist-tags resolved through a GET to BASE_URL/<tag>.
+    #
+    # @api private
     DIST_TAGS = %w[stable latest].freeze
     # Concrete version, optionally with a pre-release suffix (e.g. 2.1.220-rc1).
     # The suffix is restricted to the semver pre-release character set: every
     # accepted version is interpolated straight into a download URL, and a
     # laxer `\S+` would let "2.1.220-x/../2.1.221" traverse out of the release
     # path — silently installing something other than the pinned version.
+    #
+    # @api private
     VERSION_PATTERN = /\A\d+\.\d+\.\d+(-[A-Za-z0-9.-]+)?\z/
+    # @api private
     CHECKSUM_PATTERN = /\A[0-9a-f]{64}\z/
     # The CLI version this gem release is developed and tested against — the
     # Ruby equivalent of the Python SDK's bundled-CLI pin (_cli_version.py),
@@ -48,24 +54,35 @@ module ClaudeAgentSDK
     # .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.280'
+    # @api private
     BINARY_NAME = 'claude'
+    # @api private
     VERSION_FILE = 'VERSION'
+    # @api private
     LOCK_FILE = '.install.lock'
     # 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
     # tasks, bin/setup, test suites).
+    #
+    # @api private
     DEFAULT_DIR = File.join('vendor', 'claude')
     # Response caps. The dist-tag endpoints return a bare version string and
     # manifests are a few KB; anything larger is a misrouted response, not
     # something to buffer in memory. (The binary itself streams to disk.)
+    #
+    # @api private
     VERSION_RESPONSE_LIMIT = 1024
+    # @api private
     MANIFEST_RESPONSE_LIMIT = 5 * 1024 * 1024
+    # @api private
     METADATA_READ_LIMIT = 4096
 
     # Maps the running Ruby to a release-manifest platform key
     # (darwin-arm64, darwin-x64, linux-x64, linux-arm64, and the -musl
     # variants). Windows is not supported by this gem.
+    #
+    # @api private
     module Platform
       class << self
         def detect
@@ -123,6 +140,8 @@ module ClaudeAgentSDK
     # and chunked streaming for the binary. Knows nothing about releases; the
     # specs stub .fetch_text / .download_to wholesale so no HTTP stubbing
     # library is needed.
+    #
+    # @api private
     module Http
       MAX_REDIRECTS = 5
       OPEN_TIMEOUT_SECONDS = 10
@@ -155,7 +174,9 @@ module ClaudeAgentSDK
             File.open(path, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o600) do |file|
               response.read_body do |chunk|
                 written += chunk.bytesize
-                raise CLIInstallError, "Download from #{url} exceeds the expected #{max_bytes} bytes" if over?(written, max_bytes)
+                if over?(written, max_bytes)
+                  raise CLIInstallError, "Download from #{url} exceeds the expected #{max_bytes} bytes"
+                end
 
                 file.write(chunk)
               end
@@ -205,6 +226,8 @@ module ClaudeAgentSDK
 
     # Talks to the release service: dist-tag resolution, manifest lookup and
     # URL construction. Pure remote reads — no filesystem, no state.
+    #
+    # @api private
     module Release
       class << self
         # Local, network-free check of what the caller asked for. Returns the
@@ -239,7 +262,9 @@ module ClaudeAgentSDK
           end
 
           checksum = entry['checksum'].to_s.downcase
-          raise CLIInstallError, "#{url} has no valid sha256 checksum for #{platform}" unless checksum.match?(CHECKSUM_PATTERN)
+          unless checksum.match?(CHECKSUM_PATTERN)
+            raise CLIInstallError, "#{url} has no valid sha256 checksum for #{platform}"
+          end
 
           size = entry['size']
           { checksum: checksum, size: size.is_a?(Integer) && size.positive? ? size : nil }
@@ -277,6 +302,8 @@ module ClaudeAgentSDK
     # per line. Both platform and checksum must match before trusting a cached
     # binary offline: a cache copied between OS/CPU/libc targets is not usable.
     # Older one- or two-line files lack that proof and trigger a clean reinstall.
+    #
+    # @api private
     module Metadata
       class << self
         def read(dir)