claude-agent-sdk 0.2.1 → 0.4.0

data/lib/claude_agent_sdk/types.rb

@@ -1,6 +1,28 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
+  # Type constants for permission modes
+  PERMISSION_MODES = %w[default acceptEdits plan bypassPermissions].freeze
+
+  # Type constants for setting sources
+  SETTING_SOURCES = %w[user project local].freeze
+
+  # Type constants for permission update destinations
+  PERMISSION_UPDATE_DESTINATIONS = %w[userSettings projectSettings localSettings session].freeze
+
+  # Type constants for permission behaviors
+  PERMISSION_BEHAVIORS = %w[allow deny ask].freeze
+
+  # Type constants for hook events
+  HOOK_EVENTS = %w[PreToolUse PostToolUse UserPromptSubmit Stop SubagentStop PreCompact].freeze
+
+  # Type constants for assistant message errors
+  ASSISTANT_MESSAGE_ERRORS = %w[authentication_failed billing_error rate_limit invalid_request server_error unknown].freeze
+
+  # Type constants for SDK beta features
+  # Available beta features that can be enabled via the betas option
+  SDK_BETAS = %w[context-1m-2025-08-07].freeze
+
   # Content Blocks
 
   # Text content block
@@ -48,22 +70,24 @@ module ClaudeAgentSDK
 
   # User message
   class UserMessage
-    attr_accessor :content, :parent_tool_use_id
+    attr_accessor :content, :uuid, :parent_tool_use_id
 
-    def initialize(content:, parent_tool_use_id: nil)
+    def initialize(content:, uuid: nil, parent_tool_use_id: nil)
       @content = content
+      @uuid = uuid # Unique identifier for rewind support
       @parent_tool_use_id = parent_tool_use_id
     end
   end
 
   # Assistant message with content blocks
   class AssistantMessage
-    attr_accessor :content, :model, :parent_tool_use_id
+    attr_accessor :content, :model, :parent_tool_use_id, :error
 
-    def initialize(content:, model:, parent_tool_use_id: nil)
+    def initialize(content:, model:, parent_tool_use_id: nil, error: nil)
       @content = content
       @model = model
       @parent_tool_use_id = parent_tool_use_id
+      @error = error # One of: authentication_failed, billing_error, rate_limit, invalid_request, server_error, unknown
     end
   end
 
@@ -80,10 +104,10 @@ module ClaudeAgentSDK
   # Result message with cost and usage information
   class ResultMessage
     attr_accessor :subtype, :duration_ms, :duration_api_ms, :is_error,
-                  :num_turns, :session_id, :total_cost_usd, :usage, :result
+                  :num_turns, :session_id, :total_cost_usd, :usage, :result, :structured_output
 
     def initialize(subtype:, duration_ms:, duration_api_ms:, is_error:,
-                   num_turns:, session_id:, total_cost_usd: nil, usage: nil, result: nil)
+                   num_turns:, session_id:, total_cost_usd: nil, usage: nil, result: nil, structured_output: nil)
       @subtype = subtype
       @duration_ms = duration_ms
       @duration_api_ms = duration_api_ms
@@ -93,6 +117,7 @@ module ClaudeAgentSDK
       @total_cost_usd = total_cost_usd
       @usage = usage
       @result = result
+      @structured_output = structured_output # Structured output when output_format is specified
     end
   end
 
@@ -201,11 +226,215 @@ module ClaudeAgentSDK
 
   # Hook matcher configuration
   class HookMatcher
-    attr_accessor :matcher, :hooks
+    attr_accessor :matcher, :hooks, :timeout
 
-    def initialize(matcher: nil, hooks: [])
+    def initialize(matcher: nil, hooks: [], timeout: nil)
       @matcher = matcher
       @hooks = hooks
+      @timeout = timeout # Timeout in seconds for hook execution
+    end
+  end
+
+  # Hook context passed to hook callbacks
+  class HookContext
+    attr_accessor :signal
+
+    def initialize(signal: nil)
+      @signal = signal
+    end
+  end
+
+  # Base hook input with common fields
+  class BaseHookInput
+    attr_accessor :session_id, :transcript_path, :cwd, :permission_mode
+
+    def initialize(session_id: nil, transcript_path: nil, cwd: nil, permission_mode: nil)
+      @session_id = session_id
+      @transcript_path = transcript_path
+      @cwd = cwd
+      @permission_mode = permission_mode
+    end
+  end
+
+  # PreToolUse hook input
+  class PreToolUseHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :tool_name, :tool_input
+
+    def initialize(hook_event_name: 'PreToolUse', tool_name: nil, tool_input: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @tool_name = tool_name
+      @tool_input = tool_input
+    end
+  end
+
+  # PostToolUse hook input
+  class PostToolUseHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :tool_name, :tool_input, :tool_response
+
+    def initialize(hook_event_name: 'PostToolUse', tool_name: nil, tool_input: nil, tool_response: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @tool_response = tool_response
+    end
+  end
+
+  # UserPromptSubmit hook input
+  class UserPromptSubmitHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :prompt
+
+    def initialize(hook_event_name: 'UserPromptSubmit', prompt: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @prompt = prompt
+    end
+  end
+
+  # Stop hook input
+  class StopHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :stop_hook_active
+
+    def initialize(hook_event_name: 'Stop', stop_hook_active: false, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @stop_hook_active = stop_hook_active
+    end
+  end
+
+  # SubagentStop hook input
+  class SubagentStopHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :stop_hook_active
+
+    def initialize(hook_event_name: 'SubagentStop', stop_hook_active: false, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @stop_hook_active = stop_hook_active
+    end
+  end
+
+  # PreCompact hook input
+  class PreCompactHookInput < BaseHookInput
+    attr_accessor :hook_event_name, :trigger, :custom_instructions
+
+    def initialize(hook_event_name: 'PreCompact', trigger: nil, custom_instructions: nil, **base_args)
+      super(**base_args)
+      @hook_event_name = hook_event_name
+      @trigger = trigger
+      @custom_instructions = custom_instructions
+    end
+  end
+
+  # PreToolUse hook specific output
+  class PreToolUseHookSpecificOutput
+    attr_accessor :hook_event_name, :permission_decision, :permission_decision_reason, :updated_input
+
+    def initialize(permission_decision: nil, permission_decision_reason: nil, updated_input: nil)
+      @hook_event_name = 'PreToolUse'
+      @permission_decision = permission_decision # 'allow', 'deny', or 'ask'
+      @permission_decision_reason = permission_decision_reason
+      @updated_input = updated_input
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:permissionDecision] = @permission_decision if @permission_decision
+      result[:permissionDecisionReason] = @permission_decision_reason if @permission_decision_reason
+      result[:updatedInput] = @updated_input if @updated_input
+      result
+    end
+  end
+
+  # PostToolUse hook specific output
+  class PostToolUseHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'PostToolUse'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # UserPromptSubmit hook specific output
+  class UserPromptSubmitHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'UserPromptSubmit'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # SessionStart hook specific output
+  class SessionStartHookSpecificOutput
+    attr_accessor :hook_event_name, :additional_context
+
+    def initialize(additional_context: nil)
+      @hook_event_name = 'SessionStart'
+      @additional_context = additional_context
+    end
+
+    def to_h
+      result = { hookEventName: @hook_event_name }
+      result[:additionalContext] = @additional_context if @additional_context
+      result
+    end
+  end
+
+  # Async hook JSON output
+  class AsyncHookJSONOutput
+    attr_accessor :async, :async_timeout
+
+    def initialize(async: true, async_timeout: nil)
+      @async = async
+      @async_timeout = async_timeout
+    end
+
+    def to_h
+      result = { async: @async }
+      result[:asyncTimeout] = @async_timeout if @async_timeout
+      result
+    end
+  end
+
+  # Sync hook JSON output
+  class SyncHookJSONOutput
+    attr_accessor :continue, :suppress_output, :stop_reason, :decision,
+                  :system_message, :reason, :hook_specific_output
+
+    def initialize(continue: true, suppress_output: false, stop_reason: nil, decision: nil,
+                   system_message: nil, reason: nil, hook_specific_output: nil)
+      @continue = continue
+      @suppress_output = suppress_output
+      @stop_reason = stop_reason
+      @decision = decision
+      @system_message = system_message
+      @reason = reason
+      @hook_specific_output = hook_specific_output
+    end
+
+    def to_h
+      result = { continue: @continue }
+      result[:suppressOutput] = @suppress_output if @suppress_output
+      result[:stopReason] = @stop_reason if @stop_reason
+      result[:decision] = @decision if @decision
+      result[:systemMessage] = @system_message if @system_message
+      result[:reason] = @reason if @reason
+      result[:hookSpecificOutput] = @hook_specific_output.to_h if @hook_specific_output
+      result
     end
   end
 
@@ -274,6 +503,139 @@ module ClaudeAgentSDK
     end
   end
 
+  # SDK Plugin configuration
+  class SdkPluginConfig
+    attr_accessor :type, :path
+
+    def initialize(path:)
+      @type = 'plugin'
+      @path = path
+    end
+
+    def to_h
+      { type: @type, path: @path }
+    end
+  end
+
+  # Sandbox network configuration
+  class SandboxNetworkConfig
+    attr_accessor :allow_unix_sockets, :allow_all_unix_sockets, :allow_local_binding,
+                  :http_proxy_port, :socks_proxy_port
+
+    def initialize(
+      allow_unix_sockets: nil,
+      allow_all_unix_sockets: nil,
+      allow_local_binding: nil,
+      http_proxy_port: nil,
+      socks_proxy_port: nil
+    )
+      @allow_unix_sockets = allow_unix_sockets
+      @allow_all_unix_sockets = allow_all_unix_sockets
+      @allow_local_binding = allow_local_binding
+      @http_proxy_port = http_proxy_port
+      @socks_proxy_port = socks_proxy_port
+    end
+
+    def to_h
+      result = {}
+      result[:allowUnixSockets] = @allow_unix_sockets unless @allow_unix_sockets.nil?
+      result[:allowAllUnixSockets] = @allow_all_unix_sockets unless @allow_all_unix_sockets.nil?
+      result[:allowLocalBinding] = @allow_local_binding unless @allow_local_binding.nil?
+      result[:httpProxyPort] = @http_proxy_port if @http_proxy_port
+      result[:socksProxyPort] = @socks_proxy_port if @socks_proxy_port
+      result
+    end
+  end
+
+  # Sandbox ignore violations configuration
+  class SandboxIgnoreViolations
+    attr_accessor :file, :network
+
+    def initialize(file: nil, network: nil)
+      @file = file # Array of file paths to ignore
+      @network = network # Array of network patterns to ignore
+    end
+
+    def to_h
+      result = {}
+      result[:file] = @file if @file
+      result[:network] = @network if @network
+      result
+    end
+  end
+
+  # Sandbox settings for isolated command execution
+  class SandboxSettings
+    attr_accessor :enabled, :auto_allow_bash_if_sandboxed, :excluded_commands,
+                  :allow_unsandboxed_commands, :network, :ignore_violations,
+                  :enable_weaker_nested_sandbox
+
+    def initialize(
+      enabled: nil,
+      auto_allow_bash_if_sandboxed: nil,
+      excluded_commands: nil,
+      allow_unsandboxed_commands: nil,
+      network: nil,
+      ignore_violations: nil,
+      enable_weaker_nested_sandbox: nil
+    )
+      @enabled = enabled
+      @auto_allow_bash_if_sandboxed = auto_allow_bash_if_sandboxed
+      @excluded_commands = excluded_commands # Array of commands to exclude
+      @allow_unsandboxed_commands = allow_unsandboxed_commands
+      @network = network # SandboxNetworkConfig instance
+      @ignore_violations = ignore_violations # SandboxIgnoreViolations instance
+      @enable_weaker_nested_sandbox = enable_weaker_nested_sandbox
+    end
+
+    def to_h
+      result = {}
+      result[:enabled] = @enabled unless @enabled.nil?
+      result[:autoAllowBashIfSandboxed] = @auto_allow_bash_if_sandboxed unless @auto_allow_bash_if_sandboxed.nil?
+      result[:excludedCommands] = @excluded_commands if @excluded_commands
+      result[:allowUnsandboxedCommands] = @allow_unsandboxed_commands unless @allow_unsandboxed_commands.nil?
+      if @network
+        result[:network] = @network.is_a?(SandboxNetworkConfig) ? @network.to_h : @network
+      end
+      if @ignore_violations
+        result[:ignoreViolations] = @ignore_violations.is_a?(SandboxIgnoreViolations) ? @ignore_violations.to_h : @ignore_violations
+      end
+      result[:enableWeakerNestedSandbox] = @enable_weaker_nested_sandbox unless @enable_weaker_nested_sandbox.nil?
+      result
+    end
+  end
+
+  # System prompt preset configuration
+  class SystemPromptPreset
+    attr_accessor :type, :preset, :append
+
+    def initialize(preset:, append: nil)
+      @type = 'preset'
+      @preset = preset
+      @append = append
+    end
+
+    def to_h
+      result = { type: @type, preset: @preset }
+      result[:append] = @append if @append
+      result
+    end
+  end
+
+  # Tools preset configuration
+  class ToolsPreset
+    attr_accessor :type, :preset
+
+    def initialize(preset:)
+      @type = 'preset'
+      @preset = preset
+    end
+
+    def to_h
+      { type: @type, preset: @preset }
+    end
+  end
+
   # Claude Agent Options for configuring queries
   class ClaudeAgentOptions
     attr_accessor :allowed_tools, :system_prompt, :mcp_servers, :permission_mode,
@@ -281,7 +643,10 @@ module ClaudeAgentSDK
                   :model, :permission_prompt_tool_name, :cwd, :cli_path, :settings,
                   :add_dirs, :env, :extra_args, :max_buffer_size, :stderr,
                   :can_use_tool, :hooks, :user, :include_partial_messages,
-                  :fork_session, :agents, :setting_sources
+                  :fork_session, :agents, :setting_sources,
+                  :output_format, :max_budget_usd, :max_thinking_tokens,
+                  :fallback_model, :plugins, :debug_stderr,
+                  :betas, :tools, :sandbox, :enable_file_checkpointing, :append_allowed_tools
 
     def initialize(
       allowed_tools: [],
@@ -308,7 +673,18 @@ module ClaudeAgentSDK
       include_partial_messages: false,
       fork_session: false,
       agents: nil,
-      setting_sources: nil
+      setting_sources: nil,
+      output_format: nil,
+      max_budget_usd: nil,
+      max_thinking_tokens: nil,
+      fallback_model: nil,
+      plugins: nil,
+      debug_stderr: nil,
+      betas: nil,
+      tools: nil,
+      sandbox: nil,
+      enable_file_checkpointing: false,
+      append_allowed_tools: nil
     )
       @allowed_tools = allowed_tools
       @system_prompt = system_prompt
@@ -335,6 +711,17 @@ module ClaudeAgentSDK
       @fork_session = fork_session
       @agents = agents
       @setting_sources = setting_sources
+      @output_format = output_format # JSON schema for structured output
+      @max_budget_usd = max_budget_usd # Spending cap in dollars
+      @max_thinking_tokens = max_thinking_tokens # Extended thinking token budget
+      @fallback_model = fallback_model # Backup model if primary unavailable
+      @plugins = plugins # Array of SdkPluginConfig
+      @debug_stderr = debug_stderr # Debug output file object/path
+      @betas = betas # Array of beta feature strings (e.g., ["context-1m-2025-08-07"])
+      @tools = tools # Base tools selection: Array, empty array [], or ToolsPreset
+      @sandbox = sandbox # SandboxSettings instance for isolated command execution
+      @enable_file_checkpointing = enable_file_checkpointing # Enable file checkpointing for rewind support
+      @append_allowed_tools = append_allowed_tools # Array of tools to append to allowed_tools
     end
 
     def dup_with(**changes)

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.2.1'
+  VERSION = '0.4.0'
 end

data/lib/claude_agent_sdk.rb

@@ -244,6 +244,15 @@ module ClaudeAgentSDK
       @query_handler.set_model(model)
     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)
+      raise CLIConnectionError, 'Not connected. Call connect() first' unless @connected
+      @query_handler.rewind_files(user_message_uuid)
+    end
+
     # Get server initialization info
     # @return [Hash, nil] Server info or nil
     def server_info

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2025-10-17 00:00:00.000000000 Z
+date: 2026-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async