claude-agent-sdk 0.16.5 → 0.16.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2fe7bf072c2a3b8448b23bf82c95e7f0a896b347bd43039145458b72e21f301
-  data.tar.gz: 1a58f5e31ef7a872aeaf75a3aada1c8e60a264d9ad5e93615b62c42d96179d99
+  metadata.gz: 9b2b002f964cd13c118fd417aa0ed253fe47f469d9c7ad75f3839f64177e7744
+  data.tar.gz: a253123d762a01fe8cbfc6f7a798d9ed310c56f8e8970393d2dd053d44c33b27
 SHA512:
-  metadata.gz: e76c6cfe62c7b01320edf7a3d659e44fce46921f764132da7ab0f8223bb1d5a4a2b4457f5406b7bc68a1dde91f7af29fd0d4ff565334ed2cae8ad120339bac83
-  data.tar.gz: 9e1920a7254f5e27dab4ae88cc5ba6d8ac7430a7ec32e8c9157d80c792a65bee8c258096f52ac20ce69d5bedfd1a629a2c8ef852341c9b03e4aaa631c491d912
+  metadata.gz: cc338d1a24133685314b1696fc698b709f16b79dd620bb002d5ba9106aea29ce8575894e0120e3885ebaeccc78432c42942d5b642d1695e77264008fb1eb9b6e
+  data.tar.gz: 4630953488a3ec83df9be0209cb2731ffd80efdb5b37b6051df11cda5735928a83c98a11db9f55c869e2108ec015e856b33f0f75a2dac2873f022fbbd68d3db2

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.7] - 2026-05-15
+
+### Added
+- `ClaudeAgentOptions#resume_session_at` — forwarded as `--resume-session-at <message-uuid>` to the CLI. When resuming a session, the conversation is truncated to include only messages up to and including the assistant message with the given UUID, enabling history rewriting / branched continuations from a specific turn. Raises `ArgumentError` from `CommandBuilder` if set without `resume` (matches the CLI's own validation but surfaces it synchronously in the caller's stack).
+- `examples/e2b_transport_example.rb` — working ~320-line custom transport that runs the Claude Code CLI inside an E2B Firecracker microVM via the `e2b` gem. Reuses `CommandBuilder` for argv parity with `SubprocessCLITransport` and demonstrates the 6-method `Transport` interface against a remote backend. README's Custom Transport section now includes an interface table, data-flow diagram, code sketch, and production-hardening checklist that link to the example.
+
+## [0.16.6] - 2026-04-29
+
+### Added
+- Type classes now accept hash construction with mixed key shapes — symbols or strings, snake_case or camelCase — and support bracket access (`obj[:field]`, `obj['field']`). `UserMessage.new({"sessionId" => "abc"})` works the same as `UserMessage.new(session_id: "abc")`. `Type.from_hash(nil)` and `Type.wrap(nil)` are nil-safe.
+- `ClaudeAgentOptions.new(nil)` is accepted and yields an options object populated with configured defaults.
+
+### Changed
+- Discriminator fields on type classes (`type` on `SystemPromptFile`/`McpStdioServerConfig`/etc., `behavior` on `PermissionResultAllow`/`Deny`, `hook_event_name` on every hook input/output) are now `attr_reader`-only, set authoritatively in `initialize`. They cannot be overwritten externally.
+- `ClaudeAgentOptions` continues to raise `ArgumentError` on unknown keys (constructor, `dup_with`, and `[]=`); other type subclasses silently drop unknown keys for forward-compatibility with newer CLI output.
+
+### Internal
+- Unified ~50 type classes (messages, hook inputs/outputs, MCP configs, system prompt configs, sandbox settings) under a shared `Type` base class. `lib/claude_agent_sdk/types.rb` shrank from 1510 to 588 lines; `MessageParser`'s system-message dispatch went from 215 lines to a 14-entry lookup table.
+
 ## [0.16.5] - 2026-04-24
 
 ### Added

data/README.md

@@ -108,7 +108,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.16.5'
+gem 'claude-agent-sdk', '~> 0.16.7'
 ```
 
 And then execute:
@@ -311,57 +311,112 @@ end.wait
 
 ### Custom Transport
 
-By default, `Client` uses `SubprocessCLITransport` to spawn the Claude Code CLI locally. You can provide a custom transport class to connect via other channels (e.g., E2B sandbox, remote SSH, WebSocket):
+By default, `Client` uses `SubprocessCLITransport` to spawn the Claude Code CLI locally. You can provide a custom transport class to connect via other channels (e.g., remote SSH, WebSocket, or a sandbox VM).
+
+A transport must implement six methods:
+
+| Method | Purpose |
+|---|---|
+| `connect` | Establish the connection / spawn the remote CLI |
+| `write(data)` | Send raw JSON-line bytes to stdin |
+| `read_messages { \|hash\| ... }` | Yield parsed JSON messages from stdout; block until the stream closes |
+| `end_input` | Signal EOF on stdin |
+| `close` | Terminate and clean up |
+| `ready?` | Report whether the transport can accept I/O |
+
+Then plug it into `Client` via `transport_class:` / `transport_args:`. All connect orchestration (option transforms, MCP extraction, hook conversion, Query lifecycle) is handled for you.
 
 ```ruby
-# Custom transport must implement the Transport interface:
-# connect, write, read_messages, end_input, close, ready?
-class E2BSandboxTransport < ClaudeAgentSDK::Transport
-  def initialize(options, sandbox:)
-    @options = options
-    @sandbox = sandbox
-  end
+client = ClaudeAgentSDK::Client.new(
+  options: options,
+  transport_class: MyTransport,
+  transport_args: { foo: 'bar' } # forwarded to MyTransport.new(options, **transport_args)
+)
+```
 
-  def connect
-    @sandbox.connect
-  end
+#### Reference: running `claude` inside an E2B sandbox
 
-  def write(data)
-    @sandbox.stdin_write(data)
-  end
+[`examples/e2b_transport_example.rb`](examples/e2b_transport_example.rb) is a working transport that runs the Claude Code CLI inside an [E2B](https://e2b.dev) Firecracker microVM instead of on your host. The wire protocol stays identical — only the I/O layer changes:
 
-  def read_messages(&block)
-    @sandbox.stdout_read_lines { |line| yield JSON.parse(line, symbolize_names: true) }
-  end
+```
+ClaudeAgentSDK::Client (host)
+    │  JSON-lines
+    ▼
+E2BCliTransport (host)
+    │  send_stdin / commands.run(background:) / CommandHandle#each
+    ▼
+E2B envd RPC (HTTP/2)
+    │
+    ▼
+/usr/local/bin/claude (in-VM subprocess)
+```
+
+The example reuses the SDK's `CommandBuilder` to produce the exact same argv that `SubprocessCLITransport` would build (including SDK MCP server `:instance` field stripping), shell-escapes it for E2B's `/bin/bash -l -c` execution path, and streams stdout/stderr back through `CommandHandle#each`.
+
+Sketch (full file is ~250 lines):
 
-  def end_input
-    @sandbox.close_stdin
+```ruby
+require 'claude_agent_sdk'
+require 'e2b'
+
+class E2BCliTransport < ClaudeAgentSDK::Transport
+  def initialize(options, sandbox:, cli_path: '/usr/local/bin/claude')
+    @options, @sandbox, @cli_path = options, sandbox, cli_path
   end
 
-  def close
-    @sandbox.disconnect
+  def connect
+    argv = ClaudeAgentSDK::CommandBuilder.new(@cli_path, @options).build
+    cmd = argv.map { |a| Shellwords.shellescape(a.to_s) }.join(' ')
+    @handle = @sandbox.commands.run(cmd, background: true, stdin: true,
+                                    cwd: @options.cwd&.to_s, envs: build_env)
+    @pid = @handle.pid
+    @ready = true
   end
 
-  def ready?
-    @sandbox.connected?
+  def write(data)         = @sandbox.commands.send_stdin(@pid, data)
+  def end_input           = @sandbox.commands.close_stdin(@pid)
+  def close               = @handle&.kill
+  def ready?              = @ready
+
+  def read_messages(&block)
+    buf = +''
+    @handle.each do |stdout, stderr, _pty|
+      next if stderr && !stderr.empty?
+      stdout.each_line do |line|
+        buf << line.strip
+        begin
+          yield JSON.parse(buf, symbolize_names: true)
+          buf.clear
+        rescue JSON::ParserError
+          # JSON line split across reads — keep buffering
+        end
+      end
+    end
+    @handle.wait # raises E2B::CommandExitError on non-zero exit
   end
 end
 
-# Use it with Client — all connect orchestration (option transforms,
-# MCP extraction, hook conversion, Query lifecycle) is handled for you
+# Use it
+sandbox = E2B::Sandbox.create(template: 'base', timeout: 600)
 Async do
   client = ClaudeAgentSDK::Client.new(
     options: options,
-    transport_class: E2BSandboxTransport,
-    transport_args: { sandbox: my_sandbox }
+    transport_class: E2BCliTransport,
+    transport_args: { sandbox: sandbox }
   )
   client.connect
-  client.query("Hello from the sandbox!")
+  client.query('Hello from the sandbox!')
   client.receive_response { |msg| puts msg }
   client.disconnect
+ensure
+  sandbox.kill
 end.wait
 ```
 
+**Why use a remote transport?** Untrusted code execution, multi-tenant agent runs that can't share a host, environments without local Node.js, or simply isolating filesystem/network blast radius. The Firecracker VM gives you a fresh `/home/user` per session and is killable without touching the host.
+
+**Production hardening** (intentionally omitted from the example for clarity): inactivity watchdog, keepalive heartbeat, stream reconnect on transient SSL/EOF errors, host env-var blocklist, MCP server filtering for sandbox compatibility. See the example file's header comments for what to add and why.
+
 ## Custom Tools (SDK MCP Servers)
 
 A **custom tool** is a Ruby proc/lambda that you can offer to Claude, for Claude to invoke as needed.
@@ -1053,6 +1108,24 @@ result = ClaudeAgentSDK.fork_session(
 
 > **Note:** Session mutations use append-only JSONL writes with `O_WRONLY | O_APPEND` (no `O_CREAT`) for TOCTOU safety. They are safe to call while the session is open in a CLI process. `fork_session` uses `O_CREAT | O_EXCL` to prevent race conditions.
 
+### Resuming at a Specific Message
+
+`resume_session_at` truncates the resumed conversation to messages up to **and including** the assistant message with the given UUID — useful for rewriting history from a known point or branching exploration without forking the session file. The flag rides on top of `resume`, so the original session ID is preserved; only the in-memory history loaded for the new turn is shortened.
+
+```ruby
+ClaudeAgentSDK.query(
+  prompt: 'Try a different approach',
+  options: ClaudeAgentSDK::ClaudeAgentOptions.new(
+    resume: '550e8400-e29b-41d4-a716-446655440000',
+    resume_session_at: 'assistant-message-uuid-from-history'
+  )
+) do |message|
+  # ...
+end
+```
+
+`resume_session_at` requires `resume`; the SDK raises `ArgumentError` from `CommandBuilder` when this constraint is violated, matching the underlying CLI's validation but surfacing it synchronously in the caller's stack.
+
 ## Observability (OpenTelemetry / Langfuse)
 
 The SDK includes a built-in **observer interface** and an **OpenTelemetry observer** for tracing agent sessions. Traces are emitted using standard `gen_ai.*` semantic conventions, compatible with Langfuse, Jaeger, Datadog, and any OTel backend.

data/lib/claude_agent_sdk/command_builder.rb

@@ -105,9 +105,23 @@ module ClaudeAgentSDK
     def append_session(cmd)
       cmd.push("--continue") if @options.continue_conversation
       cmd.push("--resume", @options.resume) if @options.resume
+      append_resume_session_at(cmd)
       cmd.push("--session-id", @options.session_id) if @options.session_id
     end
 
+    # `--resume-session-at <message-uuid>` truncates the resumed conversation
+    # to include messages up to and including the given assistant message UUID.
+    # The CLI rejects this flag without `--resume`; we raise early to surface
+    # the misconfiguration in the caller's stack rather than as a remote
+    # process exit.
+    def append_resume_session_at(cmd)
+      return unless @options.resume_session_at
+
+      raise ArgumentError, "resume_session_at requires resume to be set" unless @options.resume
+
+      cmd.push("--resume-session-at", @options.resume_session_at.to_s)
+    end
+
     def append_settings(cmd)
       return unless @options.settings || @options.sandbox
 

data/lib/claude_agent_sdk/message_parser.rb

@@ -78,214 +78,57 @@ module ClaudeAgentSDK
       )
     end
 
+    # Typed SystemMessage subclasses inherit from `Type` and accept the raw
+    # CLI hash directly — camelCase and snake_case keys are normalized by the
+    # base class, and the full hash is captured as `#data`.
+    SYSTEM_MESSAGE_CLASSES = {
+      'init' => InitMessage,
+      'compact_boundary' => CompactBoundaryMessage,
+      'status' => StatusMessage,
+      'api_retry' => APIRetryMessage,
+      'local_command_output' => LocalCommandOutputMessage,
+      'hook_started' => HookStartedMessage,
+      'hook_progress' => HookProgressMessage,
+      'hook_response' => HookResponseMessage,
+      'session_state_changed' => SessionStateChangedMessage,
+      'files_persisted' => FilesPersistedMessage,
+      'elicitation_complete' => ElicitationCompleteMessage,
+      'task_started' => TaskStartedMessage,
+      'task_progress' => TaskProgressMessage,
+      'task_notification' => TaskNotificationMessage
+    }.freeze
+
     def self.parse_system_message(data)
-      case data[:subtype]
-      when 'init'
-        InitMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          agents: data[:agents], api_key_source: data[:apiKeySource] || data[:api_key_source],
-          betas: data[:betas], claude_code_version: data[:claude_code_version],
-          cwd: data[:cwd], tools: data[:tools], mcp_servers: data[:mcp_servers],
-          model: data[:model], permission_mode: data[:permissionMode] || data[:permission_mode],
-          slash_commands: data[:slash_commands], output_style: data[:output_style],
-          skills: data[:skills], plugins: data[:plugins],
-          fast_mode_state: data[:fastModeState] || data[:fast_mode_state]
-        )
-      when 'compact_boundary'
-        raw_metadata = data[:compact_metadata]
-        CompactBoundaryMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          compact_metadata: CompactMetadata.from_hash(raw_metadata)
-        )
-      when 'status'
-        StatusMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          status: data[:status],
-          permission_mode: data[:permissionMode] || data[:permission_mode]
-        )
-      when 'api_retry'
-        APIRetryMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          attempt: data[:attempt], max_retries: data[:maxRetries] || data[:max_retries],
-          retry_delay_ms: data[:retryDelayMs] || data[:retry_delay_ms],
-          error_status: data[:errorStatus] || data[:error_status],
-          error: data[:error]
-        )
-      when 'local_command_output'
-        LocalCommandOutputMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          content: data[:content]
-        )
-      when 'hook_started'
-        HookStartedMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          hook_id: data[:hookId] || data[:hook_id],
-          hook_name: data[:hookName] || data[:hook_name],
-          hook_event: data[:hookEvent] || data[:hook_event]
-        )
-      when 'hook_progress'
-        HookProgressMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          hook_id: data[:hookId] || data[:hook_id],
-          hook_name: data[:hookName] || data[:hook_name],
-          hook_event: data[:hookEvent] || data[:hook_event],
-          stdout: data[:stdout], stderr: data[:stderr], output: data[:output]
-        )
-      when 'hook_response'
-        HookResponseMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          hook_id: data[:hookId] || data[:hook_id],
-          hook_name: data[:hookName] || data[:hook_name],
-          hook_event: data[:hookEvent] || data[:hook_event],
-          output: data[:output], stdout: data[:stdout], stderr: data[:stderr],
-          exit_code: data[:exitCode] || data[:exit_code],
-          outcome: data[:outcome]
-        )
-      when 'session_state_changed'
-        SessionStateChangedMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          state: data[:state]
-        )
-      when 'files_persisted'
-        FilesPersistedMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          files: data[:files], failed: data[:failed],
-          processed_at: data[:processedAt] || data[:processed_at]
-        )
-      when 'elicitation_complete'
-        ElicitationCompleteMessage.new(
-          subtype: data[:subtype], data: data,
-          uuid: data[:uuid], session_id: data[:session_id],
-          mcp_server_name: data[:mcpServerName] || data[:mcp_server_name],
-          elicitation_id: data[:elicitationId] || data[:elicitation_id]
-        )
-      when 'task_started'
-        TaskStartedMessage.new(
-          subtype: data[:subtype], data: data,
-          task_id: data[:task_id], description: data[:description],
-          uuid: data[:uuid], session_id: data[:session_id],
-          tool_use_id: data[:tool_use_id], task_type: data[:task_type],
-          workflow_name: data[:workflowName] || data[:workflow_name],
-          prompt: data[:prompt]
-        )
-      when 'task_progress'
-        TaskProgressMessage.new(
-          subtype: data[:subtype], data: data,
-          task_id: data[:task_id], description: data[:description],
-          usage: data[:usage], uuid: data[:uuid], session_id: data[:session_id],
-          tool_use_id: data[:tool_use_id], last_tool_name: data[:last_tool_name],
-          summary: data[:summary]
-        )
-      when 'task_notification'
-        TaskNotificationMessage.new(
-          subtype: data[:subtype], data: data,
-          task_id: data[:task_id], status: data[:status],
-          output_file: data[:output_file], summary: data[:summary],
-          uuid: data[:uuid], session_id: data[:session_id],
-          tool_use_id: data[:tool_use_id], usage: data[:usage]
-        )
-      else
-        SystemMessage.new(subtype: data[:subtype], data: data)
-      end
+      klass = SYSTEM_MESSAGE_CLASSES[data[:subtype]] || SystemMessage
+      klass.new(data)
     end
 
     def self.parse_result_message(data)
-      ResultMessage.new(
-        subtype: data[:subtype],
-        duration_ms: data[:duration_ms],
-        duration_api_ms: data[:duration_api_ms],
-        is_error: data[:is_error],
-        num_turns: data[:num_turns],
-        session_id: data[:session_id],
-        stop_reason: data[:stop_reason],
-        total_cost_usd: data[:total_cost_usd],
-        usage: data[:usage],
-        result: data[:result],
-        structured_output: data[:structured_output],
-        model_usage: data[:modelUsage] || data[:model_usage],
-        permission_denials: data[:permission_denials],
-        errors: data[:errors],
-        uuid: data[:uuid],
-        fast_mode_state: data[:fastModeState] || data[:fast_mode_state]
-      )
+      ResultMessage.new(data)
     end
 
     def self.parse_stream_event(data)
-      StreamEvent.new(
-        uuid: data[:uuid],
-        session_id: data[:session_id],
-        event: data[:event],
-        parent_tool_use_id: data[:parent_tool_use_id]
-      )
+      StreamEvent.new(data)
     end
 
     def self.parse_rate_limit_event(data)
-      info = data[:rate_limit_info] || {}
-      rate_limit_info = RateLimitInfo.new(
-        status: info[:status],
-        resets_at: info[:resetsAt],
-        rate_limit_type: info[:rateLimitType],
-        utilization: info[:utilization],
-        overage_status: info[:overageStatus],
-        overage_resets_at: info[:overageResetsAt],
-        overage_disabled_reason: info[:overageDisabledReason],
-        raw: info
-      )
-      RateLimitEvent.new(
-        rate_limit_info: rate_limit_info,
-        uuid: data[:uuid],
-        session_id: data[:session_id],
-        raw_data: data
-      )
+      RateLimitEvent.new(data.merge(raw_data: data))
     end
 
     def self.parse_tool_progress_message(data)
-      ToolProgressMessage.new(
-        uuid: data[:uuid],
-        session_id: data[:session_id],
-        tool_use_id: data[:toolUseId] || data[:tool_use_id],
-        tool_name: data[:toolName] || data[:tool_name],
-        parent_tool_use_id: data[:parentToolUseId] || data[:parent_tool_use_id],
-        elapsed_time_seconds: data[:elapsedTimeSeconds] || data[:elapsed_time_seconds],
-        task_id: data[:taskId] || data[:task_id]
-      )
+      ToolProgressMessage.new(data)
     end
 
     def self.parse_auth_status_message(data)
-      AuthStatusMessage.new(
-        uuid: data[:uuid],
-        session_id: data[:session_id],
-        is_authenticating: data[:isAuthenticating] || data[:is_authenticating],
-        output: data[:output],
-        error: data[:error]
-      )
+      AuthStatusMessage.new(data)
     end
 
     def self.parse_tool_use_summary_message(data)
-      ToolUseSummaryMessage.new(
-        uuid: data[:uuid],
-        session_id: data[:session_id],
-        summary: data[:summary],
-        preceding_tool_use_ids: data[:precedingToolUseIds] || data[:preceding_tool_use_ids]
-      )
+      ToolUseSummaryMessage.new(data)
     end
 
     def self.parse_prompt_suggestion_message(data)
-      PromptSuggestionMessage.new(
-        uuid: data[:uuid],
-        session_id: data[:session_id],
-        suggestion: data[:suggestion]
-      )
+      PromptSuggestionMessage.new(data)
     end
 
     # Accepts blocks with either symbol or string keys — live CLI messages