claude-agent-sdk 0.16.4 → 0.16.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98b00605830d86d1dc5e632ef9887574b255d2ace8fdc815451a53983ca0ea2e
-  data.tar.gz: d28cb3256fa5944f966e21afa753d082559a6d537d527dfc2abb5aaa962a450b
+  metadata.gz: 5e77eea013fead986f47ff000864ddb9e52a3408186cf09bf3bb8d5214edec28
+  data.tar.gz: 49f94edca00072ec403cb26eb79165979d8684e655336bce6ca53f3c1a31eb81
 SHA512:
-  metadata.gz: 807595177836563a86f0dc72a3a70b297860d07f76d19c90d70f97dafae7a1bdd69a52583a8c005172148f6742b59fbd80e78f79a3d10c47ad33ba24d7ade89c
-  data.tar.gz: af94cf3bbd037da6b1a7998a41438f10227d731657c2050e4a0f1d57551e682d4dd9dcfef9d98c67f6ead150472804468093cc226622392b8b3ecdb25cae4d18
+  metadata.gz: '08544dd09bb2d8c1127364517e1cc3527aaa0321d8c2d957550f078c5ce1d20796f5622f987ddd9f128377cad697d314a63a31031cd8eeb2e823bbfef282ee17'
+  data.tar.gz: e7149a4d3d9546631449d71878a6480d3d8758c2d990b3836cdc1dde65e93d09a8d19658c781c4f2cf5655bcb3c910dac84bc7d0076f635af4957f78a2e91fe9

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- `display:` option on `ThinkingConfigAdaptive` and `ThinkingConfigEnabled`, forwarded to the CLI as `--thinking-display <summarized|omitted>`. Opus 4.7 defaults thinking display to `"omitted"` (empty `thinking` field, signature only), so pass `ThinkingConfigAdaptive.new(display: "summarized")` to receive plaintext summarized thinking text. Invalid values raise `ArgumentError` at construction. See [adaptive thinking docs](https://docs.claude.com/en/docs/build-with-claude/adaptive-thinking).
+
+### Internal
+- Extracted private `writeln`/`write` helpers in `Client` and `Query` to consolidate the `@transport.write(json + "\n")` pattern across five call sites. Pure refactor; same bytes on the wire.
+
 ## [0.16.4] - 2026-04-23
 
 ### Fixed

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.4'
+gem 'claude-agent-sdk', '~> 0.16.6'
 ```
 
 And then execute:

data/lib/claude_agent_sdk/command_builder.rb

@@ -158,8 +158,10 @@ module ClaudeAgentSDK
         case @options.thinking
         when ThinkingConfigAdaptive
           cmd.push("--thinking", "adaptive")
+          append_thinking_display(cmd, @options.thinking.display)
         when ThinkingConfigEnabled
           cmd.push("--max-thinking-tokens", @options.thinking.budget_tokens.to_s)
+          append_thinking_display(cmd, @options.thinking.display)
         when ThinkingConfigDisabled
           cmd.push("--thinking", "disabled")
         end
@@ -168,6 +170,15 @@ module ClaudeAgentSDK
       end
     end
 
+    # `--thinking-display` toggles between `"summarized"` (visible thinking
+    # text) and `"omitted"` (empty thinking, signature only). Opus 4.7 defaults
+    # to `"omitted"`, so pass `display: "summarized"` to see reasoning.
+    def append_thinking_display(cmd, display)
+      return if display.nil?
+
+      cmd.push("--thinking-display", display.to_s)
+    end
+
     # The set of supported levels is model-dependent; the CLI falls back to
     # the highest supported level at or below the one requested
     # (e.g. `xhigh` → `high` on Opus 4.6).

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

data/lib/claude_agent_sdk/query.rb

@@ -261,7 +261,7 @@ module ClaudeAgentSDK
           response: response_data
         }
       }
-      @transport.write(JSON.generate(success_response) + "\n")
+      writeln(JSON.generate(success_response))
     rescue Async::Stop
       # Cancellation requested; respond with an error so the CLI can unblock.
       cancelled_response = {
@@ -273,7 +273,7 @@ module ClaudeAgentSDK
           error: 'Cancelled'
         }
       }
-      @transport.write(JSON.generate(cancelled_response) + "\n")
+      writeln(JSON.generate(cancelled_response))
     rescue StandardError => e
       # Send error response
       error_response = {
@@ -285,7 +285,7 @@ module ClaudeAgentSDK
           error: e.message
         }
       }
-      @transport.write(JSON.generate(error_response) + "\n")
+      writeln(JSON.generate(error_response))
     end
 
     def handle_permission_request(request_data)
@@ -642,7 +642,7 @@ module ClaudeAgentSDK
         request: request
       }
 
-      @transport.write(JSON.generate(control_request) + "\n")
+      writeln(JSON.generate(control_request))
 
       # Wait for response with timeout (default 1200s to handle slow CLI startup)
       Async do |task|
@@ -913,13 +913,8 @@ module ClaudeAgentSDK
     def stream_input(stream)
       stream.each do |message|
         break if @closed
-        serialized = if message.is_a?(Hash)
-                       JSON.generate(message) + "\n"
-                     else
-                       message.to_s
-                     end
-        serialized += "\n" unless serialized.end_with?("\n")
-        @transport.write(serialized)
+        serialized = message.is_a?(Hash) ? JSON.generate(message) : message.to_s
+        writeln(serialized)
       end
     rescue StandardError => e
       # Log error but don't raise
@@ -928,6 +923,14 @@ module ClaudeAgentSDK
       wait_for_result_and_end_input
     end
 
+    def writeln(string)
+      write string.end_with?("\n") ? string : "#{string}\n"
+    end
+
+    def write(string)
+      @transport.write(string)
+    end
+
     # Receive SDK messages (not control messages)
     def receive_messages(&block)
       return enum_for(:receive_messages) unless block