claude_agent 0.1.0

data/lib/claude_agent/options.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeAgent
+  # Permission modes for tool execution (TypeScript SDK parity)
+  PERMISSION_MODES = %w[default acceptEdits plan bypassPermissions delegate dontAsk].freeze
+
+  # Configuration options for ClaudeAgent queries and clients
+  #
+  # @example Basic usage
+  #   options = ClaudeAgent::Options.new(
+  #     model: "claude-sonnet-4-5-20250514",
+  #     max_turns: 10
+  #   )
+  #
+  # @example With tools and permissions
+  #   options = ClaudeAgent::Options.new(
+  #     tools: ["Read", "Write", "Bash"],
+  #     permission_mode: "acceptEdits",
+  #     can_use_tool: ->(name, input, context) { { behavior: "allow" } }
+  #   )
+  #
+  class Options
+    # Default values for options that have non-nil defaults
+    DEFAULTS = {
+      allowed_tools: [],
+      disallowed_tools: [],
+      allow_dangerously_skip_permissions: false,
+      continue_conversation: false,
+      fork_session: false,
+      strict_mcp_config: false,
+      mcp_servers: {},
+      add_dirs: [],
+      env: {},
+      extra_args: {},
+      plugins: [],
+      include_partial_messages: false,
+      enable_file_checkpointing: false,
+      persist_session: true,
+      betas: []
+    }.freeze
+
+    # All configurable attributes
+    ATTRIBUTES = %i[
+      tools allowed_tools disallowed_tools
+      system_prompt append_system_prompt
+      model fallback_model
+      permission_mode permission_prompt_tool_name can_use_tool allow_dangerously_skip_permissions
+      continue_conversation resume fork_session resume_session_at
+      max_turns max_budget_usd max_thinking_tokens
+      strict_mcp_config mcp_servers hooks
+      settings sandbox cwd add_dirs env user
+      cli_path extra_args agents setting_sources plugins
+      include_partial_messages output_format enable_file_checkpointing
+      persist_session betas max_buffer_size stderr_callback
+      abort_controller spawn_claude_code_process
+    ].freeze
+
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize(**kwargs)
+      merged = DEFAULTS.merge(kwargs)
+      ATTRIBUTES.each do |attr|
+        instance_variable_set(:"@#{attr}", merged[attr])
+      end
+      validate!
+    end
+
+    # Build CLI arguments from options
+    # @return [Array<String>] CLI arguments
+    def to_cli_args
+      [].tap do |args|
+        args.concat(system_prompt_args)
+        args.concat(model_args)
+        args.concat(tools_args)
+        args.concat(permission_args)
+        args.concat(conversation_args)
+        args.concat(limits_args)
+        args.concat(mcp_args)
+        args.concat(settings_args)
+        args.concat(environment_args)
+        args.concat(output_args)
+        args.concat(extra_cli_args)
+      end
+    end
+
+    # Build environment variables for CLI process
+    # @return [Hash] Environment variables
+    def to_env
+      env.dup.tap do |process_env|
+        process_env["CLAUDE_CODE_ENTRYPOINT"] = "sdk-rb"
+        process_env["CLAUDE_AGENT_SDK_VERSION"] = ClaudeAgent::VERSION
+        process_env["CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING"] = "true" if enable_file_checkpointing
+        process_env["PWD"] = cwd.to_s if cwd
+      end
+    end
+
+    # Check if SDK MCP servers are configured
+    # @return [Boolean]
+    def has_sdk_mcp_servers?
+      return false unless mcp_servers.is_a?(Hash)
+
+      mcp_servers.any? { |_, v| v.is_a?(Hash) && v[:type] == "sdk" }
+    end
+
+    # Check if hooks are configured
+    # @return [Boolean]
+    def has_hooks?
+      hooks.is_a?(Hash) && hooks.any?
+    end
+
+    # Get the abort signal from the controller
+    # @return [AbortSignal, nil]
+    def abort_signal
+      abort_controller&.signal
+    end
+
+    private
+
+    # --- CLI Argument Builders ---
+
+    def system_prompt_args
+      [].tap do |args|
+        if system_prompt
+          case system_prompt
+          when String then args.push("--system-prompt", system_prompt)
+          when Hash then args.push("--system-prompt", JSON.generate(system_prompt))
+          end
+        end
+        args.push("--append-system-prompt", append_system_prompt) if append_system_prompt
+      end
+    end
+
+    def model_args
+      [].tap do |args|
+        args.push("--model", model) if model
+        args.push("--fallback-model", fallback_model) if fallback_model
+      end
+    end
+
+    def tools_args
+      [].tap do |args|
+        if tools
+          case tools
+          when Array then args.push("--tools", tools.join(","))
+          when ToolsPreset then args.push("--tools", JSON.generate(tools.to_h))
+          when Hash then args.push("--tools", JSON.generate(tools))
+          else args.push("--tools", tools.to_s)
+          end
+        end
+        args.push("--allowedTools", allowed_tools.join(",")) if allowed_tools.any?
+        args.push("--disallowedTools", disallowed_tools.join(",")) if disallowed_tools.any?
+      end
+    end
+
+    def permission_args
+      [].tap do |args|
+        args.push("--permission-mode", permission_mode) if permission_mode
+        args.push("--permission-prompt-tool", permission_prompt_tool_name) if permission_prompt_tool_name
+        args.push("--dangerously-skip-permissions") if allow_dangerously_skip_permissions
+      end
+    end
+
+    def conversation_args
+      [].tap do |args|
+        args.push("--continue") if continue_conversation
+        args.push("--resume", resume) if resume
+        args.push("--fork-session") if fork_session
+        args.push("--resume-session-at", resume_session_at) if resume_session_at
+      end
+    end
+
+    def limits_args
+      [].tap do |args|
+        args.push("--max-turns", max_turns.to_s) if max_turns
+        args.push("--max-budget-usd", max_budget_usd.to_s) if max_budget_usd
+        args.push("--max-thinking-tokens", max_thinking_tokens.to_s) if max_thinking_tokens
+        args.push("--strict-mcp-config") if strict_mcp_config
+      end
+    end
+
+    def mcp_args
+      [].tap do |args|
+        if mcp_servers.is_a?(Hash) && mcp_servers.any?
+          external_servers = mcp_servers.reject { |_, v| v.is_a?(Hash) && v[:type] == "sdk" }
+          args.push("--mcp-config", JSON.generate(external_servers)) if external_servers.any?
+        elsif mcp_servers.is_a?(String)
+          args.push("--mcp-config", mcp_servers)
+        end
+      end
+    end
+
+    def settings_args
+      [].tap do |args|
+        args.push("--settings", settings) if settings
+        if sandbox
+          sandbox_json = sandbox.respond_to?(:to_h) ? sandbox.to_h : sandbox
+          args.push("--sandbox", JSON.generate(sandbox_json))
+        end
+      end
+    end
+
+    def environment_args
+      [].tap do |args|
+        args.push("--user", user) if user
+        add_dirs.each { |dir| args.push("--add-dir", dir.to_s) }
+        args.push("--setting-sources", setting_sources.join(",")) if setting_sources&.any?
+        plugins.each do |plugin|
+          dir = plugin.is_a?(Hash) ? plugin[:dir] : plugin
+          args.push("--plugin-dir", dir.to_s)
+        end
+        args.push("--betas", betas.join(",")) if betas.any?
+      end
+    end
+
+    def output_args
+      [].tap do |args|
+        args.push("--enable-file-checkpointing") if enable_file_checkpointing
+        args.push("--no-persist-session") if persist_session == false
+        args.push("--json-schema", JSON.generate(output_format)) if output_format
+        args.push("--include-partial-messages") if include_partial_messages
+        if agents
+          agents_hash = agents.transform_values { |a| a.respond_to?(:to_h) ? a.to_h : a }
+          args.push("--agents", JSON.generate(agents_hash))
+        end
+      end
+    end
+
+    def extra_cli_args
+      [].tap do |args|
+        extra_args.each do |key, value|
+          flag = key.to_s.start_with?("--") ? key.to_s : "--#{key}"
+          value.nil? ? args.push(flag) : args.push(flag, value.to_s)
+        end
+      end
+    end
+
+    # --- Validation ---
+
+    def validate!
+      if permission_mode && !PERMISSION_MODES.include?(permission_mode)
+        raise ConfigurationError, "Invalid permission_mode: #{permission_mode}. Must be one of: #{PERMISSION_MODES.join(", ")}"
+      end
+
+      if permission_mode == "bypassPermissions" && !allow_dangerously_skip_permissions
+        raise ConfigurationError,
+              "Must set allow_dangerously_skip_permissions: true to use bypassPermissions mode"
+      end
+
+      if can_use_tool && !can_use_tool.respond_to?(:call)
+        raise ConfigurationError, "can_use_tool must be callable (Proc, Lambda, or object responding to #call)"
+      end
+
+      if max_turns && (!max_turns.is_a?(Integer) || max_turns < 1)
+        raise ConfigurationError, "max_turns must be a positive integer"
+      end
+
+      if max_budget_usd && (!max_budget_usd.is_a?(Numeric) || max_budget_usd <= 0)
+        raise ConfigurationError, "max_budget_usd must be a positive number"
+      end
+    end
+  end
+end

data/lib/claude_agent/permissions.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Result of a permission check (allow)
+  #
+  # @example Allow with modified input
+  #   PermissionResultAllow.new(
+  #     updated_input: input.merge("safe" => true)
+  #   )
+  #
+  PermissionResultAllow = Data.define(:updated_input, :updated_permissions) do
+    def initialize(updated_input: nil, updated_permissions: nil)
+      super
+    end
+
+    def behavior
+      "allow"
+    end
+
+    def to_h
+      h = { behavior: "allow" }
+      h[:updatedInput] = updated_input if updated_input
+      h[:updatedPermissions] = updated_permissions&.map { |p| p.respond_to?(:to_h) ? p.to_h : p } if updated_permissions
+      h
+    end
+  end
+
+  # Result of a permission check (deny)
+  #
+  # @example Deny with message
+  #   PermissionResultDeny.new(
+  #     message: "Operation not allowed",
+  #     interrupt: true
+  #   )
+  #
+  PermissionResultDeny = Data.define(:message, :interrupt) do
+    def initialize(message: "", interrupt: false)
+      super
+    end
+
+    def behavior
+      "deny"
+    end
+
+    def to_h
+      { behavior: "deny", message: message, interrupt: interrupt }
+    end
+  end
+
+  # Valid permission update types
+  PERMISSION_UPDATE_TYPES = %w[
+    addRules
+    replaceRules
+    removeRules
+    setMode
+    addDirectories
+    removeDirectories
+  ].freeze
+
+  # Permission update request
+  #
+  # @example Add rules
+  #   PermissionUpdate.new(
+  #     type: "addRules",
+  #     rules: [{tool_name: "Read", behavior: "allow"}]
+  #   )
+  #
+  PermissionUpdate = Data.define(
+    :type,
+    :rules,
+    :behavior,
+    :mode,
+    :directories,
+    :destination
+  ) do
+    def initialize(
+      type:,
+      rules: nil,
+      behavior: nil,
+      mode: nil,
+      directories: nil,
+      destination: nil
+    )
+      super
+    end
+
+    def to_h
+      h = { type: type }
+      h[:rules] = rules.map { |r| normalize_rule(r) } if rules
+      h[:behavior] = behavior if behavior
+      h[:mode] = mode if mode
+      h[:directories] = directories if directories
+      h[:destination] = destination if destination
+      h
+    end
+
+    private
+
+    def normalize_rule(rule)
+      return rule unless rule.is_a?(Hash)
+
+      # Convert snake_case to camelCase
+      # Note: behavior is NOT part of PermissionRuleValue per TypeScript SDK
+      {
+        toolName: rule[:tool_name] || rule[:toolName],
+        ruleContent: rule[:rule_content] || rule[:ruleContent]
+      }.compact
+    end
+  end
+
+  # Permission rule value (TypeScript SDK parity)
+  # Note: behavior is on PermissionUpdate, not on individual rules
+  #
+  PermissionRuleValue = Data.define(:tool_name, :rule_content) do
+    def initialize(tool_name: nil, rule_content: nil)
+      super
+    end
+
+    def to_h
+      {
+        toolName: tool_name,
+        ruleContent: rule_content
+      }.compact
+    end
+  end
+
+  # Valid permission update destinations (TypeScript SDK parity)
+  PERMISSION_UPDATE_DESTINATIONS = %w[
+    userSettings
+    projectSettings
+    localSettings
+    session
+    cliArg
+  ].freeze
+
+  # Context provided to can_use_tool callbacks (TypeScript SDK parity)
+  #
+  # @example
+  #   context = ToolPermissionContext.new(
+  #     permission_suggestions: [update1, update2],
+  #     blocked_path: "/etc/passwd",
+  #     decision_reason: "Path outside allowed directories",
+  #     tool_use_id: "tool_123",
+  #     agent_id: "agent_456"
+  #   )
+  #
+  ToolPermissionContext = Data.define(
+    :permission_suggestions,
+    :blocked_path,
+    :decision_reason,
+    :tool_use_id,
+    :agent_id
+  ) do
+    def initialize(
+      permission_suggestions: nil,
+      blocked_path: nil,
+      decision_reason: nil,
+      tool_use_id: nil,
+      agent_id: nil
+    )
+      super
+    end
+  end
+end

data/lib/claude_agent/query.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  class << self
+    # One-shot query to Claude Code CLI
+    #
+    # This is a simple, stateless interface for sending a single prompt
+    # and receiving all responses. For interactive conversations, use
+    # {ClaudeAgent::Client} instead.
+    #
+    # @param prompt [String] The prompt to send to Claude
+    # @param options [Options, nil] Configuration options
+    # @param transport [Transport::Base, nil] Custom transport (default: Subprocess)
+    # @return [Enumerator<Message>] Enumerator yielding Message objects
+    #
+    # @example Basic usage
+    #   ClaudeAgent.query(prompt: "What is 2+2?").each do |message|
+    #     case message
+    #     when ClaudeAgent::AssistantMessage
+    #       puts message.text
+    #     when ClaudeAgent::ResultMessage
+    #       puts "Cost: $#{message.total_cost_usd}"
+    #     end
+    #   end
+    #
+    # @example Collect all messages
+    #   messages = ClaudeAgent.query(prompt: "Hello").to_a
+    #   result = messages.last
+    #   puts "Completed in #{result.duration_ms}ms"
+    #
+    # @example With custom options
+    #   options = ClaudeAgent::Options.new(
+    #     model: "claude-sonnet-4-5-20250514",
+    #     max_turns: 5,
+    #     permission_mode: "acceptEdits"
+    #   )
+    #   ClaudeAgent.query(prompt: "Fix the bug", options: options).each { |m| puts m }
+    #
+    def query(prompt:, options: nil, transport: nil)
+      options ||= Options.new
+      transport ||= Transport::Subprocess.new(options: options)
+
+      Enumerator.new do |yielder|
+        # Set entrypoint environment variable
+        ENV["CLAUDE_CODE_ENTRYPOINT"] = "sdk-rb"
+
+        # Determine mode based on hooks/MCP servers
+        streaming = options.has_hooks? || options.has_sdk_mcp_servers?
+
+        if streaming
+          # Use streaming mode with control protocol
+          protocol = ControlProtocol.new(transport: transport, options: options)
+          begin
+            # Register abort handler if abort controller is provided
+            if options.abort_signal
+              options.abort_signal.on_abort do
+                protocol.abort! rescue nil
+              end
+            end
+
+            protocol.start(streaming: true)
+            protocol.send_user_message(prompt)
+            transport.end_input unless options.has_hooks? || options.has_sdk_mcp_servers?
+
+            protocol.each_message do |message|
+              yielder << message
+              break if message.is_a?(ResultMessage)
+            end
+          ensure
+            protocol.stop
+          end
+        else
+          # Simple mode - just send prompt and read responses
+          parser = MessageParser.new
+          begin
+            transport.connect(streaming: false, prompt: prompt)
+
+            transport.read_messages do |raw|
+              message = parser.parse(raw)
+              yielder << message
+              break if message.is_a?(ResultMessage)
+            end
+          ensure
+            transport.close
+          end
+        end
+      end
+    end
+  end
+end

data/lib/claude_agent/sandbox_settings.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Network-specific configuration for sandbox mode (TypeScript SDK parity)
+  #
+  # @example
+  #   network = SandboxNetworkConfig.new(
+  #     allow_local_binding: true,
+  #     allow_unix_sockets: ["/var/run/docker.sock"],
+  #     allowed_domains: ["api.example.com"]
+  #   )
+  #
+  SandboxNetworkConfig = Data.define(
+    :allowed_domains,
+    :allow_local_binding,
+    :allow_unix_sockets,
+    :allow_all_unix_sockets,
+    :http_proxy_port,
+    :socks_proxy_port
+  ) do
+    def initialize(
+      allowed_domains: [],
+      allow_local_binding: false,
+      allow_unix_sockets: [],
+      allow_all_unix_sockets: false,
+      http_proxy_port: nil,
+      socks_proxy_port: nil
+    )
+      super
+    end
+
+    def to_h
+      result = {}
+      result[:allowedDomains] = allowed_domains unless allowed_domains.empty?
+      result[:allowLocalBinding] = allow_local_binding if allow_local_binding
+      result[:allowUnixSockets] = allow_unix_sockets unless allow_unix_sockets.empty?
+      result[:allowAllUnixSockets] = allow_all_unix_sockets if allow_all_unix_sockets
+      result[:httpProxyPort] = http_proxy_port if http_proxy_port
+      result[:socksProxyPort] = socks_proxy_port if socks_proxy_port
+      result
+    end
+  end
+
+  # Configuration for ignoring specific sandbox violations (TypeScript SDK parity)
+  #
+  # @example
+  #   ignore = SandboxIgnoreViolations.new(
+  #     file: ["/tmp/*"],
+  #     network: ["localhost:*"]
+  #   )
+  #
+  SandboxIgnoreViolations = Data.define(:file, :network) do
+    def initialize(file: [], network: [])
+      super
+    end
+
+    def to_h
+      result = {}
+      result[:file] = file unless file.empty?
+      result[:network] = network unless network.empty?
+      result
+    end
+  end
+
+  # Custom ripgrep configuration for sandbox mode (TypeScript SDK parity)
+  #
+  # @example
+  #   ripgrep = SandboxRipgrepConfig.new(
+  #     command: "/usr/local/bin/rg",
+  #     args: ["--hidden"]
+  #   )
+  #
+  SandboxRipgrepConfig = Data.define(:command, :args) do
+    def initialize(command:, args: nil)
+      super
+    end
+
+    def to_h
+      result = { command: command }
+      result[:args] = args if args
+      result
+    end
+  end
+
+  # Sandbox configuration for command execution (TypeScript SDK parity)
+  #
+  # @example Basic sandbox
+  #   sandbox = SandboxSettings.new(enabled: true)
+  #
+  # @example With network config
+  #   sandbox = SandboxSettings.new(
+  #     enabled: true,
+  #     auto_allow_bash_if_sandboxed: true,
+  #     excluded_commands: ["docker"],
+  #     network: SandboxNetworkConfig.new(allow_local_binding: true)
+  #   )
+  #
+  # @example With custom ripgrep
+  #   sandbox = SandboxSettings.new(
+  #     enabled: true,
+  #     ripgrep: SandboxRipgrepConfig.new(command: "/usr/local/bin/rg")
+  #   )
+  #
+  SandboxSettings = Data.define(
+    :enabled,
+    :auto_allow_bash_if_sandboxed,
+    :excluded_commands,
+    :allow_unsandboxed_commands,
+    :network,
+    :ignore_violations,
+    :enable_weaker_nested_sandbox,
+    :ripgrep
+  ) do
+    def initialize(
+      enabled: false,
+      auto_allow_bash_if_sandboxed: false,
+      excluded_commands: [],
+      allow_unsandboxed_commands: false,
+      network: nil,
+      ignore_violations: nil,
+      enable_weaker_nested_sandbox: false,
+      ripgrep: nil
+    )
+      super
+    end
+
+    def to_h
+      result = { enabled: enabled }
+      result[:autoAllowBashIfSandboxed] = auto_allow_bash_if_sandboxed if auto_allow_bash_if_sandboxed
+      result[:excludedCommands] = excluded_commands unless excluded_commands.empty?
+      result[:allowUnsandboxedCommands] = allow_unsandboxed_commands if allow_unsandboxed_commands
+      result[:network] = network.to_h if network && !network.to_h.empty?
+      result[:ignoreViolations] = ignore_violations.to_h if ignore_violations && !ignore_violations.to_h.empty?
+      result[:enableWeakerNestedSandbox] = enable_weaker_nested_sandbox if enable_weaker_nested_sandbox
+      result[:ripgrep] = ripgrep.to_h if ripgrep
+      result
+    end
+  end
+end