claude_agent 0.7.12 → 0.7.13

data/lib/claude_agent/client/commands.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  class Client
+    # CLI command delegations to the ControlProtocol.
+    #
+    # These methods provide the Client-level interface to control commands:
+    # permission/model changes, MCP management, task control, and query methods.
+    # Each enforces connection state before delegating to the protocol.
+    module Commands
+      # Change the permission mode
+      #
+      # @param mode [String] New permission mode
+      # @return [Hash] Response
+      def set_permission_mode(mode)
+        require_connection!
+
+        @protocol.set_permission_mode(mode)
+      end
+
+      # Change the model
+      #
+      # @param model [String, nil] New model name (nil to use default)
+      # @return [Hash] Response
+      def set_model(model)
+        require_connection!
+
+        @protocol.set_model(model)
+      end
+
+      # Rewind files to the state at a specific user message
+      #
+      # @param user_message_id [String] UUID of the user message to rewind to
+      # @param dry_run [Boolean] If true, preview changes without modifying files
+      # @return [RewindFilesResult] Result with rewind information
+      def rewind_files(user_message_id, dry_run: false)
+        require_connection!
+
+        @protocol.rewind_files(user_message_id, dry_run: dry_run)
+      end
+
+      # Set maximum thinking tokens (TypeScript SDK parity)
+      #
+      # @param tokens [Integer, nil] Max thinking tokens (nil to reset)
+      # @return [Hash] Response
+      def set_max_thinking_tokens(tokens)
+        require_connection!
+
+        @protocol.set_max_thinking_tokens(tokens)
+      end
+
+      # Get available slash commands (TypeScript SDK parity)
+      #
+      # @return [Array<SlashCommand>]
+      def supported_commands
+        require_connection!
+
+        @protocol.supported_commands
+      end
+
+      # Get available models (TypeScript SDK parity)
+      #
+      # @return [Array<ModelInfo>]
+      def supported_models
+        require_connection!
+
+        @protocol.supported_models
+      end
+
+      # Get available agents (TypeScript SDK v0.2.63 parity)
+      #
+      # @return [Array<AgentInfo>]
+      def supported_agents
+        require_connection!
+
+        @protocol.supported_agents
+      end
+
+      # Get MCP server status (TypeScript SDK parity)
+      #
+      # @return [Array<McpServerStatus>]
+      def mcp_server_status
+        require_connection!
+
+        @protocol.mcp_server_status
+      end
+
+      # Get account information (TypeScript SDK parity)
+      #
+      # @return [AccountInfo]
+      def account_info
+        require_connection!
+
+        @protocol.account_info
+      end
+
+      # Get full initialization result (TypeScript SDK parity)
+      #
+      # @return [InitializationResult]
+      def initialization_result
+        require_connection!
+
+        @protocol.initialization_result
+      end
+
+      # Stop a running background task (TypeScript SDK parity)
+      #
+      # Sends a stop signal to a running task. A task_notification message
+      # with status 'stopped' will be emitted when the task stops.
+      #
+      # @param task_id [String] The task ID from task_notification events
+      # @return [void]
+      #
+      # @example
+      #   client.stop_task("task-123")
+      #
+      def stop_task(task_id)
+        require_connection!
+
+        @protocol.stop_task(task_id)
+      end
+
+      # Apply flag settings (TypeScript SDK v0.2.50 parity)
+      #
+      # Merges the provided settings into the flag settings layer.
+      #
+      # @param settings [Hash] Settings to merge into the flag layer
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   client.apply_flag_settings({ "model" => "claude-sonnet-4-5-20250514" })
+      #
+      def apply_flag_settings(settings)
+        require_connection!
+
+        @protocol.apply_flag_settings(settings)
+      end
+
+      # Dynamically set MCP servers for this session (TypeScript SDK parity)
+      #
+      # This replaces the current set of dynamically-added MCP servers.
+      # Servers that are removed will be disconnected, and new servers will be connected.
+      #
+      # @param servers [Hash] Map of server name to configuration
+      # @return [McpSetServersResult] Result with added, removed, and errors
+      #
+      # @example
+      #   result = client.set_mcp_servers({
+      #     "my-server" => { type: "stdio", command: "node", args: ["server.js"] }
+      #   })
+      #   puts "Added: #{result.added}"
+      #   puts "Removed: #{result.removed}"
+      #
+      def set_mcp_servers(servers)
+        require_connection!
+
+        @protocol.set_mcp_servers(servers)
+      end
+
+      # Reconnect to an MCP server (TypeScript SDK parity)
+      #
+      # Attempts to reconnect to a disconnected or errored MCP server.
+      #
+      # @param server_name [String] Name of the MCP server to reconnect
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   client.mcp_reconnect("my-server")
+      #
+      def mcp_reconnect(server_name)
+        require_connection!
+
+        @protocol.mcp_reconnect(server_name)
+      end
+
+      # Enable or disable an MCP server (TypeScript SDK parity)
+      #
+      # Toggles an MCP server on or off without removing its configuration.
+      #
+      # @param server_name [String] Name of the MCP server to toggle
+      # @param enabled [Boolean] Whether to enable (true) or disable (false) the server
+      # @return [Hash] Response from the CLI
+      #
+      # @example Enable a server
+      #   client.mcp_toggle("my-server", enabled: true)
+      #
+      # @example Disable a server
+      #   client.mcp_toggle("my-server", enabled: false)
+      #
+      def mcp_toggle(server_name, enabled:)
+        require_connection!
+
+        @protocol.mcp_toggle(server_name, enabled: enabled)
+      end
+
+      # Initiate OAuth authentication for an MCP server (TypeScript SDK v0.2.52 parity)
+      #
+      # @param server_name [String] Name of the MCP server to authenticate
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   client.mcp_authenticate("my-remote-server")
+      #
+      def mcp_authenticate(server_name)
+        require_connection!
+
+        @protocol.mcp_authenticate(server_name)
+      end
+
+      # Clear stored auth credentials for an MCP server (TypeScript SDK v0.2.52 parity)
+      #
+      # @param server_name [String] Name of the MCP server to clear auth for
+      # @return [Hash] Response from the CLI
+      #
+      # @example
+      #   client.mcp_clear_auth("my-remote-server")
+      #
+      def mcp_clear_auth(server_name)
+        require_connection!
+
+        @protocol.mcp_clear_auth(server_name)
+      end
+    end
+  end
+end

data/lib/claude_agent/client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "client/commands"
+
 module ClaudeAgent
   # Interactive, bidirectional client for Claude Code CLI
   #
@@ -32,6 +34,8 @@ module ClaudeAgent
   #   end
   #
   class Client
+    include Commands
+
     attr_reader :options, :transport, :server_info, :cumulative_usage, :event_handler, :permission_queue
 
     # Open a client with automatic cleanup
@@ -295,210 +299,6 @@ module ClaudeAgent
       @protocol&.abort!
     end
 
-    # Change the permission mode
-    #
-    # @param mode [String] New permission mode
-    # @return [Hash] Response
-    def set_permission_mode(mode)
-      require_connection!
-
-      @protocol.set_permission_mode(mode)
-    end
-
-    # Change the model
-    #
-    # @param model [String, nil] New model name (nil to use default)
-    # @return [Hash] Response
-    def set_model(model)
-      require_connection!
-
-      @protocol.set_model(model)
-    end
-
-    # Rewind files to the state at a specific user message
-    #
-    # @param user_message_id [String] UUID of the user message to rewind to
-    # @param dry_run [Boolean] If true, preview changes without modifying files
-    # @return [RewindFilesResult] Result with rewind information
-    def rewind_files(user_message_id, dry_run: false)
-      require_connection!
-
-      @protocol.rewind_files(user_message_id, dry_run: dry_run)
-    end
-
-    # Set maximum thinking tokens (TypeScript SDK parity)
-    #
-    # @param tokens [Integer, nil] Max thinking tokens (nil to reset)
-    # @return [Hash] Response
-    def set_max_thinking_tokens(tokens)
-      require_connection!
-
-      @protocol.set_max_thinking_tokens(tokens)
-    end
-
-    # Get available slash commands (TypeScript SDK parity)
-    #
-    # @return [Array<SlashCommand>]
-    def supported_commands
-      require_connection!
-
-      @protocol.supported_commands
-    end
-
-    # Get available models (TypeScript SDK parity)
-    #
-    # @return [Array<ModelInfo>]
-    def supported_models
-      require_connection!
-
-      @protocol.supported_models
-    end
-
-    # Get MCP server status (TypeScript SDK parity)
-    #
-    # @return [Array<McpServerStatus>]
-    def mcp_server_status
-      require_connection!
-
-      @protocol.mcp_server_status
-    end
-
-    # Get account information (TypeScript SDK parity)
-    #
-    # @return [AccountInfo]
-    def account_info
-      require_connection!
-
-      @protocol.account_info
-    end
-
-    # Get full initialization result (TypeScript SDK parity)
-    #
-    # @return [InitializationResult]
-    def initialization_result
-      require_connection!
-
-      @protocol.initialization_result
-    end
-
-    # Stop a running background task (TypeScript SDK parity)
-    #
-    # Sends a stop signal to a running task. A task_notification message
-    # with status 'stopped' will be emitted when the task stops.
-    #
-    # @param task_id [String] The task ID from task_notification events
-    # @return [void]
-    #
-    # @example
-    #   client.stop_task("task-123")
-    #
-    def stop_task(task_id)
-      require_connection!
-
-      @protocol.stop_task(task_id)
-    end
-
-    # Apply flag settings (TypeScript SDK v0.2.50 parity)
-    #
-    # Merges the provided settings into the flag settings layer.
-    #
-    # @param settings [Hash] Settings to merge into the flag layer
-    # @return [Hash] Response from the CLI
-    #
-    # @example
-    #   client.apply_flag_settings({ "model" => "claude-sonnet-4-5-20250514" })
-    #
-    def apply_flag_settings(settings)
-      require_connection!
-
-      @protocol.apply_flag_settings(settings)
-    end
-
-    # Dynamically set MCP servers for this session (TypeScript SDK parity)
-    #
-    # This replaces the current set of dynamically-added MCP servers.
-    # Servers that are removed will be disconnected, and new servers will be connected.
-    #
-    # @param servers [Hash] Map of server name to configuration
-    # @return [McpSetServersResult] Result with added, removed, and errors
-    #
-    # @example
-    #   result = client.set_mcp_servers({
-    #     "my-server" => { type: "stdio", command: "node", args: ["server.js"] }
-    #   })
-    #   puts "Added: #{result.added}"
-    #   puts "Removed: #{result.removed}"
-    #
-    def set_mcp_servers(servers)
-      require_connection!
-
-      @protocol.set_mcp_servers(servers)
-    end
-
-    # Reconnect to an MCP server (TypeScript SDK parity)
-    #
-    # Attempts to reconnect to a disconnected or errored MCP server.
-    #
-    # @param server_name [String] Name of the MCP server to reconnect
-    # @return [Hash] Response from the CLI
-    #
-    # @example
-    #   client.mcp_reconnect("my-server")
-    #
-    def mcp_reconnect(server_name)
-      require_connection!
-
-      @protocol.mcp_reconnect(server_name)
-    end
-
-    # Enable or disable an MCP server (TypeScript SDK parity)
-    #
-    # Toggles an MCP server on or off without removing its configuration.
-    #
-    # @param server_name [String] Name of the MCP server to toggle
-    # @param enabled [Boolean] Whether to enable (true) or disable (false) the server
-    # @return [Hash] Response from the CLI
-    #
-    # @example Enable a server
-    #   client.mcp_toggle("my-server", enabled: true)
-    #
-    # @example Disable a server
-    #   client.mcp_toggle("my-server", enabled: false)
-    #
-    def mcp_toggle(server_name, enabled:)
-      require_connection!
-
-      @protocol.mcp_toggle(server_name, enabled: enabled)
-    end
-
-    # Initiate OAuth authentication for an MCP server (TypeScript SDK v0.2.52 parity)
-    #
-    # @param server_name [String] Name of the MCP server to authenticate
-    # @return [Hash] Response from the CLI
-    #
-    # @example
-    #   client.mcp_authenticate("my-remote-server")
-    #
-    def mcp_authenticate(server_name)
-      require_connection!
-
-      @protocol.mcp_authenticate(server_name)
-    end
-
-    # Clear stored auth credentials for an MCP server (TypeScript SDK v0.2.52 parity)
-    #
-    # @param server_name [String] Name of the MCP server to clear auth for
-    # @return [Hash] Response from the CLI
-    #
-    # @example
-    #   client.mcp_clear_auth("my-remote-server")
-    #
-    def mcp_clear_auth(server_name)
-      require_connection!
-
-      @protocol.mcp_clear_auth(server_name)
-    end
-
     # Non-blocking poll for the next pending permission request.
     #
     # Returns the next {PermissionRequest} from the queue, or nil if

data/lib/claude_agent/content_blocks/generic_block.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Generic content block for unknown/future block types
+  #
+  # Wraps unrecognized content block types so they can be inspected
+  # without losing type information. Supports dynamic field access via
+  # `[]` and `method_missing`.
+  #
+  # @example
+  #   block = GenericBlock.new(block_type: "citation", raw: { text: "ref", url: "https://example.com" })
+  #   block.type     # => :citation
+  #   block[:text]   # => "ref"
+  #   block.url      # => "https://example.com"
+  #   block.to_h     # => { text: "ref", url: "https://example.com" }
+  #
+  GenericBlock = Data.define(:block_type, :raw) do
+    def type
+      block_type&.to_sym || :unknown
+    end
+
+    def to_h
+      raw
+    end
+
+    def [](key)
+      raw[key]
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      raw.key?(name) || super
+    end
+
+    def method_missing(name, *args)
+      return raw[name] if args.empty? && raw.key?(name)
+      super
+    end
+  end
+end

data/lib/claude_agent/content_blocks/image_content_block.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Image content block (TypeScript SDK parity)
+  #
+  # Supports both base64-encoded image data and URL sources.
+  #
+  # @example Base64 image
+  #   block = ImageContentBlock.new(
+  #     source: { type: "base64", media_type: "image/png", data: "..." }
+  #   )
+  #   block.source_type  # => "base64"
+  #   block.media_type   # => "image/png"
+  #
+  # @example URL image
+  #   block = ImageContentBlock.new(
+  #     source: { type: "url", url: "https://example.com/image.png" }
+  #   )
+  #   block.url  # => "https://example.com/image.png"
+  #
+  ImageContentBlock = Data.define(:source) do
+    def type
+      :image
+    end
+
+    # Get the media type if available
+    # @return [String, nil]
+    def media_type
+      source.is_a?(Hash) ? source[:media_type] : nil
+    end
+
+    # Get the base64 data if available
+    # @return [String, nil]
+    def data
+      source.is_a?(Hash) ? source[:data] : nil
+    end
+
+    # Get the URL if this is a URL-sourced image
+    # @return [String, nil]
+    def url
+      source.is_a?(Hash) ? source[:url] : nil
+    end
+
+    # Get the source type (base64 or url)
+    # @return [String, nil]
+    def source_type
+      source.is_a?(Hash) ? source[:type] : nil
+    end
+
+    def to_h
+      { type: "image", source: source }
+    end
+  end
+end

data/lib/claude_agent/content_blocks/server_tool_result_block.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Server tool result block
+  #
+  ServerToolResultBlock = Data.define(:tool_use_id, :content, :is_error, :server_name) do
+    def initialize(tool_use_id:, server_name:, content: nil, is_error: nil)
+      super
+    end
+
+    def type
+      :server_tool_result
+    end
+
+    def to_h
+      h = { type: "server_tool_result", tool_use_id: tool_use_id, server_name: server_name }
+      h[:content] = content unless content.nil?
+      h[:is_error] = is_error unless is_error.nil?
+      h
+    end
+  end
+end

data/lib/claude_agent/content_blocks/server_tool_use_block.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Server tool use block (for MCP servers)
+  #
+  ServerToolUseBlock = Data.define(:id, :name, :input, :server_name) do
+    def type
+      :server_tool_use
+    end
+
+    def to_h
+      { type: "server_tool_use", id: id, name: name, input: input, server_name: server_name }
+    end
+
+    # Returns the file path for file-based tools, nil otherwise.
+    # @return [String, nil]
+    def file_path
+      case name
+      when "Read", "Write", "Edit"
+        input[:file_path]
+      when "NotebookEdit"
+        input[:notebook_path]
+      end
+    end
+
+    # One-line human-readable label with server context.
+    # @return [String]
+    def display_label
+      server_name ? "#{server_name}/#{name}" : name
+    end
+
+    # Detailed summary with server context, truncated to max chars.
+    # @param max [Integer] maximum length before truncation
+    # @return [String]
+    def summary(max: 60)
+      label = display_label
+      text = "#{label}: #{input.inspect}"
+      truncate(text, max)
+    end
+
+    private
+
+    def truncate(str, max)
+      return str if str.length <= max
+      "#{str[0, max]}..."
+    end
+  end
+end

data/lib/claude_agent/content_blocks/text_block.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Text content block
+  #
+  # @example
+  #   block = TextBlock.new(text: "Hello, world!")
+  #   block.text # => "Hello, world!"
+  #
+  TextBlock = Data.define(:text) do
+    def type
+      :text
+    end
+
+    def to_h
+      { type: "text", text: text }
+    end
+  end
+end

data/lib/claude_agent/content_blocks/thinking_block.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Extended thinking content block
+  #
+  # @example
+  #   block = ThinkingBlock.new(thinking: "Let me consider...", signature: "abc123")
+  #   block.thinking # => "Let me consider..."
+  #
+  ThinkingBlock = Data.define(:thinking, :signature) do
+    def type
+      :thinking
+    end
+
+    def to_h
+      { type: "thinking", thinking: thinking, signature: signature }
+    end
+  end
+end

data/lib/claude_agent/content_blocks/tool_result_block.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Tool result block
+  #
+  # @example
+  #   block = ToolResultBlock.new(tool_use_id: "tool_123", content: "file contents", is_error: false)
+  #
+  ToolResultBlock = Data.define(:tool_use_id, :content, :is_error) do
+    def initialize(tool_use_id:, content: nil, is_error: nil)
+      super
+    end
+
+    def type
+      :tool_result
+    end
+
+    def to_h
+      h = { type: "tool_result", tool_use_id: tool_use_id }
+      h[:content] = content unless content.nil?
+      h[:is_error] = is_error unless is_error.nil?
+      h
+    end
+  end
+end