claude-agent-sdk 0.2.1 → 0.4.0

data/lib/claude_agent_sdk/message_parser.rb

@@ -32,6 +32,7 @@ module ClaudeAgentSDK
 
     def self.parse_user_message(data)
       parent_tool_use_id = data[:parent_tool_use_id]
+      uuid = data[:uuid] # UUID for rewind support
       message_data = data[:message]
       raise MessageParseError.new("Missing message field in user message", data: data) unless message_data
 
@@ -40,9 +41,9 @@ module ClaudeAgentSDK
 
       if content.is_a?(Array)
         content_blocks = content.map { |block| parse_content_block(block) }
-        UserMessage.new(content: content_blocks, parent_tool_use_id: parent_tool_use_id)
+        UserMessage.new(content: content_blocks, uuid: uuid, parent_tool_use_id: parent_tool_use_id)
       else
-        UserMessage.new(content: content, parent_tool_use_id: parent_tool_use_id)
+        UserMessage.new(content: content, uuid: uuid, parent_tool_use_id: parent_tool_use_id)
       end
     end
 
@@ -54,7 +55,8 @@ module ClaudeAgentSDK
       AssistantMessage.new(
         content: content_blocks,
         model: data.dig(:message, :model),
-        parent_tool_use_id: data[:parent_tool_use_id]
+        parent_tool_use_id: data[:parent_tool_use_id],
+        error: data[:error] # authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
       )
     end
 
@@ -75,7 +77,8 @@ module ClaudeAgentSDK
         session_id: data[:session_id],
         total_cost_usd: data[:total_cost_usd],
         usage: data[:usage],
-        result: data[:result]
+        result: data[:result],
+        structured_output: data[:structured_output] # Structured output when output_format is specified
       )
     end
 

data/lib/claude_agent_sdk/query.rb

@@ -217,16 +217,73 @@ module ClaudeAgentSDK
       callback = @hook_callbacks[callback_id]
       raise "No hook callback found for ID: #{callback_id}" unless callback
 
+      # Parse input data into typed HookInput object
+      input_data = request_data[:input] || {}
+      hook_input = parse_hook_input(input_data)
+
+      # Create typed HookContext
+      context = HookContext.new(signal: nil)
+
       hook_output = callback.call(
-        request_data[:input],
+        hook_input,
         request_data[:tool_use_id],
-        { signal: nil }
+        context
       )
 
       # Convert Ruby-safe field names to CLI-expected names
       convert_hook_output_for_cli(hook_output)
     end
 
+    def parse_hook_input(input_data)
+      event_name = input_data[:hook_event_name] || input_data['hook_event_name']
+      base_args = {
+        session_id: input_data[:session_id],
+        transcript_path: input_data[:transcript_path],
+        cwd: input_data[:cwd],
+        permission_mode: input_data[:permission_mode]
+      }
+
+      case event_name
+      when 'PreToolUse'
+        PreToolUseHookInput.new(
+          tool_name: input_data[:tool_name],
+          tool_input: input_data[:tool_input],
+          **base_args
+        )
+      when 'PostToolUse'
+        PostToolUseHookInput.new(
+          tool_name: input_data[:tool_name],
+          tool_input: input_data[:tool_input],
+          tool_response: input_data[:tool_response],
+          **base_args
+        )
+      when 'UserPromptSubmit'
+        UserPromptSubmitHookInput.new(
+          prompt: input_data[:prompt],
+          **base_args
+        )
+      when 'Stop'
+        StopHookInput.new(
+          stop_hook_active: input_data[:stop_hook_active],
+          **base_args
+        )
+      when 'SubagentStop'
+        SubagentStopHookInput.new(
+          stop_hook_active: input_data[:stop_hook_active],
+          **base_args
+        )
+      when 'PreCompact'
+        PreCompactHookInput.new(
+          trigger: input_data[:trigger],
+          custom_instructions: input_data[:custom_instructions],
+          **base_args
+        )
+      else
+        # Return base input for unknown event types
+        BaseHookInput.new(**base_args)
+      end
+    end
+
     def handle_mcp_message(request_data)
       server_name = request_data[:server_name]
       mcp_message = request_data[:message]
@@ -238,6 +295,13 @@ module ClaudeAgentSDK
     end
 
     def convert_hook_output_for_cli(hook_output)
+      # Handle typed output objects
+      if hook_output.respond_to?(:to_h) && !hook_output.is_a?(Hash)
+        return hook_output.to_h
+      end
+
+      return {} unless hook_output.is_a?(Hash)
+
       # Convert Ruby hash with symbol keys to CLI format
       # Handle special keywords that might be Ruby-safe versions
       converted = {}
@@ -245,9 +309,21 @@ module ClaudeAgentSDK
         converted_key = case key
                         when :async_, 'async_' then 'async'
                         when :continue_, 'continue_' then 'continue'
-                        else key.to_s.gsub('_', '')
+                        when :hook_specific_output then 'hookSpecificOutput'
+                        when :suppress_output then 'suppressOutput'
+                        when :stop_reason then 'stopReason'
+                        when :system_message then 'systemMessage'
+                        when :async_timeout then 'asyncTimeout'
+                        else key.to_s
                         end
-        converted[converted_key] = value
+
+        # Recursively convert nested objects
+        converted_value = if value.respond_to?(:to_h) && !value.is_a?(Hash)
+                            value.to_h
+                          else
+                            value
+                          end
+        converted[converted_key] = converted_value
       end
       converted
     end
@@ -475,6 +551,17 @@ module ClaudeAgentSDK
                            })
     end
 
+    # Rewind files to a previous checkpoint (v0.1.15+)
+    # Restores file state to what it was at the given user message
+    # Requires enable_file_checkpointing to be true in options
+    # @param user_message_uuid [String] The UUID of the UserMessage to rewind to
+    def rewind_files(user_message_uuid)
+      send_control_request({
+                             subtype: 'rewind_files',
+                             userMessageUuid: user_message_uuid
+                           })
+    end
+
     # Stream input messages to transport
     def stream_input(stream)
       stream.each do |message|

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -75,11 +75,97 @@ module ClaudeAgentSDK
       cmd.concat(['--max-turns', @options.max_turns.to_s]) if @options.max_turns
       cmd.concat(['--disallowedTools', @options.disallowed_tools.join(',')]) unless @options.disallowed_tools.empty?
       cmd.concat(['--model', @options.model]) if @options.model
+      cmd.concat(['--fallback-model', @options.fallback_model]) if @options.fallback_model
       cmd.concat(['--permission-prompt-tool', @options.permission_prompt_tool_name]) if @options.permission_prompt_tool_name
       cmd.concat(['--permission-mode', @options.permission_mode]) if @options.permission_mode
       cmd << '--continue' if @options.continue_conversation
       cmd.concat(['--resume', @options.resume]) if @options.resume
-      cmd.concat(['--settings', @options.settings]) if @options.settings
+
+      # Settings handling with sandbox merge
+      # Sandbox settings are merged into the main settings JSON
+      if @options.settings || @options.sandbox
+        settings_hash = {}
+        settings_is_path = false
+
+        # Parse existing settings if provided
+        if @options.settings
+          if @options.settings.is_a?(String)
+            begin
+              settings_hash = JSON.parse(@options.settings)
+            rescue JSON::ParserError
+              # If not valid JSON, treat as file path and pass as-is
+              settings_is_path = true
+              cmd.concat(['--settings', @options.settings])
+              if @options.sandbox
+                warn "Warning: Cannot merge sandbox settings when settings is a file path. " \
+                     "Sandbox settings will be ignored. Use a Hash or JSON string for settings " \
+                     "to enable sandbox merging."
+              end
+            end
+          elsif @options.settings.is_a?(Hash)
+            settings_hash = @options.settings.dup
+          end
+        end
+
+        # Merge sandbox settings if provided (only when settings is not a file path)
+        if !settings_is_path && @options.sandbox
+          sandbox_hash = if @options.sandbox.is_a?(SandboxSettings)
+                           @options.sandbox.to_h
+                         else
+                           @options.sandbox
+                         end
+          settings_hash[:sandbox] = sandbox_hash unless sandbox_hash.empty?
+        end
+
+        # Output merged settings (only when settings is not a file path)
+        if !settings_is_path && !settings_hash.empty?
+          cmd.concat(['--settings', JSON.generate(settings_hash)])
+        end
+      end
+
+      # Budget limit option
+      cmd.concat(['--max-budget-usd', @options.max_budget_usd.to_s]) if @options.max_budget_usd
+      # Note: max_thinking_tokens is stored in options but not yet supported by Claude CLI
+
+      # Betas option for enabling experimental features
+      if @options.betas && !@options.betas.empty?
+        cmd.concat(['--betas', @options.betas.join(',')])
+      end
+
+      # Tools option for base tools selection
+      if @options.tools
+        if @options.tools.is_a?(Array)
+          cmd.concat(['--tools', @options.tools.join(',')])
+        elsif @options.tools.is_a?(ToolsPreset)
+          cmd.concat(['--tools', JSON.generate(@options.tools.to_h)])
+        elsif @options.tools.is_a?(Hash)
+          cmd.concat(['--tools', JSON.generate(@options.tools)])
+        end
+      end
+
+      # Append allowed tools option
+      if @options.append_allowed_tools && !@options.append_allowed_tools.empty?
+        cmd.concat(['--append-allowed-tools', @options.append_allowed_tools.join(',')])
+      end
+
+      # File checkpointing for rewind support
+      cmd << '--enable-file-checkpointing' if @options.enable_file_checkpointing
+
+      # JSON schema for structured output
+      # Accepts either:
+      # 1. Direct schema: { type: 'object', properties: {...} }
+      # 2. Wrapped format: { type: 'json_schema', schema: {...} }
+      if @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_json = schema.is_a?(String) ? schema : JSON.generate(schema)
+        cmd.concat(['--json-schema', schema_json])
+      end
 
       # Add directories
       @options.add_dirs.each do |dir|
@@ -121,6 +207,14 @@ module ClaudeAgentSDK
         cmd.concat(['--agents', JSON.generate(agents_dict)])
       end
 
+      # Plugins
+      if @options.plugins && !@options.plugins.empty?
+        plugins_config = @options.plugins.map do |plugin|
+          plugin.is_a?(SdkPluginConfig) ? plugin.to_h : plugin
+        end
+        cmd.concat(['--plugins', JSON.generate(plugins_config)])
+      end
+
       # Setting sources
       sources_value = @options.setting_sources ? @options.setting_sources.join(',') : ''
       cmd.concat(['--setting-sources', sources_value])
@@ -159,7 +253,7 @@ module ClaudeAgentSDK
       process_env['PWD'] = @cwd.to_s if @cwd
 
       # Determine stderr handling
-      should_pipe_stderr = @options.stderr || @options.extra_args.key?('debug-to-stderr')
+      should_pipe_stderr = @options.stderr || @options.debug_stderr || @options.extra_args.key?('debug-to-stderr')
 
       begin
         # Start process using Open3
@@ -205,7 +299,17 @@ module ClaudeAgentSDK
         line_str = line.chomp
         next if line_str.empty?
 
+        # Call stderr callback if provided
         @options.stderr&.call(line_str)
+
+        # Write to debug_stderr file/IO if provided
+        if @options.debug_stderr
+          if @options.debug_stderr.respond_to?(:puts)
+            @options.debug_stderr.puts(line_str)
+          elsif @options.debug_stderr.is_a?(String)
+            File.open(@options.debug_stderr, 'a') { |f| f.puts(line_str) }
+          end
+        end
       end
     rescue StandardError
       # Ignore errors during stderr reading