claude_agent 0.7.12 → 0.7.13

data/lib/claude_agent/options/serializer.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeAgent
+  class Options
+    # Converts Options into CLI arguments and environment variables.
+    #
+    # Separated from Options to keep configuration concerns (what to store)
+    # distinct from serialization concerns (how to render for the CLI).
+    module Serializer
+      # 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(sandbox_args)
+          args.concat(environment_args)
+          args.concat(output_args)
+          args.concat(debug_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
+
+      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
+          args.push("--session-id", session_id) if session_id
+        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.concat(thinking_args)
+          args.push("--max-thinking-tokens", max_thinking_tokens.to_s) if !thinking && max_thinking_tokens
+          args.push("--effort", effort) if effort
+          args.push("--strict-mcp-config") if strict_mcp_config
+        end
+      end
+
+      def thinking_args
+        return [] unless thinking.is_a?(Hash)
+
+        type = thinking[:type] || thinking["type"]
+        case type
+        when "disabled"
+          [ "--max-thinking-tokens", "0" ]
+        when "enabled"
+          budget = thinking[:budgetTokens] || thinking[:budget_tokens] ||
+                   thinking["budgetTokens"] || thinking["budget_tokens"]
+          budget ? [ "--max-thinking-tokens", budget.to_s ] : []
+        else # "adaptive" or unrecognized — omit flag, let CLI use default
+          []
+        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 sandbox_args
+        [].tap do |args|
+          if sandbox
+            args.push("--sandbox", JSON.generate(sandbox.to_h))
+          end
+        end
+      end
+
+      def environment_args
+        [].tap do |args|
+          args.push("--agent", agent) if agent
+          add_dirs.each { |dir| args.push("--add-dir", dir.to_s) }
+          args.push("--setting-sources", setting_sources.join(",")) if setting_sources&.any?
+          if settings
+            case settings
+            when String then args.push("--settings", settings)
+            when Hash then args.push("--settings", JSON.generate(settings))
+            end
+          end
+          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
+          args.push("--prompt-suggestions") if prompt_suggestions
+          if agents
+            agents_hash = agents.transform_values(&:to_h)
+            args.push("--agents", JSON.generate(agents_hash))
+          end
+        end
+      end
+
+      def debug_args
+        [].tap do |args|
+          args.push("--debug") if debug
+          args.push("--debug-file", debug_file) if debug_file
+        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
+    end
+  end
+end

data/lib/claude_agent/options.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "json"
+require_relative "options/serializer"
 
 module ClaudeAgent
   # Permission modes for tool execution (TypeScript SDK parity)
@@ -22,6 +22,8 @@ module ClaudeAgent
   #   )
   #
   class Options
+    include Serializer
+
     # Default values for options that have non-nil defaults
     DEFAULTS = {
       allowed_tools: [],
@@ -52,17 +54,19 @@ module ClaudeAgent
       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
+      permission_mode permission_prompt_tool_name can_use_tool on_elicitation allow_dangerously_skip_permissions
       permission_queue
       continue_conversation resume fork_session resume_session_at session_id
       max_turns max_budget_usd thinking effort max_thinking_tokens
       strict_mcp_config mcp_servers hooks
       sandbox cwd add_dirs env agent
-      cli_path extra_args agents setting_sources plugins
+      cli_path extra_args agents setting_sources settings plugins
       include_partial_messages output_format enable_file_checkpointing
       persist_session prompt_suggestions betas max_buffer_size stderr_callback
       abort_controller spawn_claude_code_process
       debug debug_file
+      tool_config
+      agent_progress_summaries
       logger
     ].freeze
 
@@ -78,36 +82,6 @@ module ClaudeAgent
       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(sandbox_args)
-        args.concat(environment_args)
-        args.concat(output_args)
-        args.concat(debug_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?
@@ -136,149 +110,6 @@ module ClaudeAgent
 
     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
-        args.push("--session-id", session_id) if session_id
-      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.concat(thinking_args)
-        args.push("--max-thinking-tokens", max_thinking_tokens.to_s) if !thinking && max_thinking_tokens
-        args.push("--effort", effort) if effort
-        args.push("--strict-mcp-config") if strict_mcp_config
-      end
-    end
-
-    def thinking_args
-      return [] unless thinking.is_a?(Hash)
-
-      type = thinking[:type] || thinking["type"]
-      case type
-      when "disabled"
-        [ "--max-thinking-tokens", "0" ]
-      when "enabled"
-        budget = thinking[:budgetTokens] || thinking[:budget_tokens] ||
-                 thinking["budgetTokens"] || thinking["budget_tokens"]
-        budget ? [ "--max-thinking-tokens", budget.to_s ] : []
-      else # "adaptive" or unrecognized — omit flag, let CLI use default
-        []
-      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 sandbox_args
-      [].tap do |args|
-        if sandbox
-          args.push("--sandbox", JSON.generate(sandbox.to_h))
-        end
-      end
-    end
-
-    def environment_args
-      [].tap do |args|
-        args.push("--agent", agent) if agent
-        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
-        args.push("--prompt-suggestions") if prompt_suggestions
-        if agents
-          agents_hash = agents.transform_values(&:to_h)
-          args.push("--agents", JSON.generate(agents_hash))
-        end
-      end
-    end
-
-    def debug_args
-      [].tap do |args|
-        args.push("--debug") if debug
-        args.push("--debug-file", debug_file) if debug_file
-      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!
@@ -295,6 +126,10 @@ module ClaudeAgent
         raise ConfigurationError, "can_use_tool must be callable (Proc, Lambda, or object responding to #call)"
       end
 
+      if on_elicitation && !on_elicitation.respond_to?(:call)
+        raise ConfigurationError, "on_elicitation must be callable (Proc, Lambda, or object responding to #call)"
+      end
+
       # Auto-set permission_prompt_tool_name to "stdio" when can_use_tool or
       # permission_queue is configured, so the CLI routes permission prompts
       # through the control protocol instead of interactive terminal prompts

data/lib/claude_agent/sandbox_settings.rb

@@ -135,6 +135,7 @@ module ClaudeAgent
     :network,
     :ignore_violations,
     :enable_weaker_nested_sandbox,
+    :enable_weaker_network_isolation,
     :ripgrep,
     :filesystem
   ) do
@@ -146,6 +147,7 @@ module ClaudeAgent
       network: nil,
       ignore_violations: nil,
       enable_weaker_nested_sandbox: false,
+      enable_weaker_network_isolation: false,
       ripgrep: nil,
       filesystem: nil
     )
@@ -160,6 +162,7 @@ module ClaudeAgent
       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[:enableWeakerNetworkIsolation] = enable_weaker_network_isolation if enable_weaker_network_isolation
       result[:ripgrep] = ripgrep.to_h if ripgrep
       result[:filesystem] = filesystem.to_h if filesystem && !filesystem.to_h.empty?
       result

data/lib/claude_agent/session.rb

@@ -1,210 +1,6 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  # V2 Session options (subset of full Options)
-  # V2 API - UNSTABLE
-  # @alpha
-  #
-  # @example
-  #   options = SessionOptions.new(
-  #     model: "claude-sonnet-4-5-20250929",
-  #     permission_mode: "acceptEdits"
-  #   )
-  #
-  SessionOptions = Data.define(
-    :model,
-    :path_to_claude_code_executable,
-    :env,
-    :allowed_tools,
-    :disallowed_tools,
-    :can_use_tool,
-    :hooks,
-    :permission_mode
-  ) do
-    def initialize(
-      model:,
-      path_to_claude_code_executable: nil,
-      env: nil,
-      allowed_tools: nil,
-      disallowed_tools: nil,
-      can_use_tool: nil,
-      hooks: nil,
-      permission_mode: nil
-    )
-      super
-    end
-  end
-
-  # V2 API - UNSTABLE
-  # Multi-turn session interface for persistent conversations.
-  #
-  # This provides a simpler interface than the full Client class,
-  # matching the TypeScript SDK's SDKSession interface.
-  #
-  # @alpha
-  #
-  # @example Create a session and send messages
-  #   session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
-  #   session.send("Hello!")
-  #   session.stream.each { |msg| puts msg.inspect }
-  #   session.close
-  #
-  class V2Session
-    attr_reader :session_id, :options
-
-    def initialize(options)
-      @options = options.is_a?(SessionOptions) ? options : SessionOptions.new(**options)
-      @client = nil
-      @session_id = nil
-      @closed = false
-    end
-
-    # Send a message to the agent
-    #
-    # @param message [String, UserMessage] The message to send
-    # @return [void]
-    def send(message)
-      ensure_connected!
-      content = message.is_a?(String) ? message : message
-      @client.send_message(content)
-    end
-
-    # Stream messages from the agent
-    #
-    # @return [Enumerator<message>] An enumerator of messages
-    # @yield [message] Each message received from the agent
-    def stream(&block)
-      ensure_connected!
-      if block_given?
-        @client.receive_response(&block)
-      else
-        @client.receive_response
-      end
-    end
-
-    # Close the session
-    #
-    # @return [void]
-    def close
-      return if @closed
-      @client&.disconnect
-      @closed = true
-    end
-
-    # Check if session is closed
-    #
-    # @return [Boolean]
-    def closed?
-      @closed
-    end
-
-    private
-
-    def ensure_connected!
-      raise AbortError, "Session is closed" if @closed
-      return if @client&.connected?
-
-      @client = Client.new(options: build_client_options)
-      @client.connect
-      update_session_id
-    end
-
-    def build_client_options
-      Options.new(
-        model: @options.model,
-        cli_path: @options.path_to_claude_code_executable,
-        env: @options.env,
-        allowed_tools: @options.allowed_tools,
-        disallowed_tools: @options.disallowed_tools,
-        can_use_tool: @options.can_use_tool,
-        hooks: @options.hooks,
-        permission_mode: @options.permission_mode
-      )
-    end
-
-    def update_session_id
-      # Session ID is typically extracted from the first system message
-      # but since we don't have it immediately, we leave it nil until available
-      @session_id = @client.server_info&.dig("session_id")
-    end
-  end
-
-  class << self
-    # V2 API - UNSTABLE
-    # Create a persistent session for multi-turn conversations.
-    #
-    # @param options [Hash, SessionOptions] Session configuration
-    # @return [Session] A new session instance
-    # @alpha
-    #
-    # @example
-    #   session = ClaudeAgent.unstable_v2_create_session(model: "claude-sonnet-4-5-20250929")
-    #
-    def unstable_v2_create_session(options)
-      V2Session.new(options)
-    end
-
-    # V2 API - UNSTABLE
-    # Resume an existing session by ID.
-    #
-    # @param session_id [String] The session ID to resume
-    # @param options [Hash, SessionOptions] Session configuration
-    # @return [Session] A session configured to resume the specified session
-    # @alpha
-    #
-    # @example
-    #   session = ClaudeAgent.unstable_v2_resume_session("session-abc123", model: "claude-sonnet-4-5-20250929")
-    #
-    def unstable_v2_resume_session(session_id, options)
-      # For resumption, we need to pass the resume option through
-      # Since SessionOptions doesn't have resume, we handle it in the Client options
-      session = V2Session.new(options)
-      session.instance_variable_set(:@resume_session_id, session_id)
-
-      # Override build_client_options to include resume
-      session.define_singleton_method(:build_client_options) do
-        Options.new(
-          model: @options.model,
-          cli_path: @options.path_to_claude_code_executable,
-          env: @options.env,
-          allowed_tools: @options.allowed_tools,
-          disallowed_tools: @options.disallowed_tools,
-          can_use_tool: @options.can_use_tool,
-          hooks: @options.hooks,
-          permission_mode: @options.permission_mode,
-          resume: @resume_session_id
-        )
-      end
-
-      session
-    end
-
-    # V2 API - UNSTABLE
-    # One-shot convenience function for single prompts.
-    #
-    # @param message [String] The prompt message
-    # @param options [Hash, SessionOptions] Session configuration
-    # @return [ResultMessage] The result of the query
-    # @alpha
-    #
-    # @example
-    #   result = ClaudeAgent.unstable_v2_prompt("What files are here?", model: "claude-sonnet-4-5-20250929")
-    #
-    def unstable_v2_prompt(message, options)
-      session = unstable_v2_create_session(options)
-      begin
-        session.send(message)
-        result = nil
-        session.stream.each do |msg|
-          result = msg if msg.is_a?(ResultMessage)
-        end
-        result
-      ensure
-        session.close
-      end
-    end
-  end
-
   # Historical session finder with Rails-like API.
   #
   # Wraps SessionInfo with a rich interface for finding sessions