claude_agent 0.7.7 → 0.7.9

data/lib/claude_agent/content_blocks.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module ClaudeAgent
   # Text content block
   #
@@ -37,6 +39,7 @@ module ClaudeAgent
   #
   # @example
   #   block = ToolUseBlock.new(id: "tool_123", name: "Read", input: {file_path: "/tmp/file"})
+  #   block.input[:file_path] # => "/tmp/file"
   #   block.name # => "Read"
   #
   ToolUseBlock = Data.define(:id, :name, :input) do
@@ -47,6 +50,118 @@ module ClaudeAgent
     def to_h
       { type: "tool_use", id: id, name: name, input: input }
     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 for the tool call.
+    # @return [String]
+    def display_label
+      case name
+      when "Read", "Write", "Edit", "NotebookEdit"
+        path = file_path
+        path ? "#{name} #{shorten_path(path)}" : name
+      when "Bash"
+        cmd = input[:command]
+        cmd ? "Bash: #{truncate(cmd, 50)}" : "Bash"
+      when "Grep"
+        pattern = input[:pattern]
+        pattern ? "Grep: #{pattern}" : "Grep"
+      when "Glob"
+        pattern = input[:pattern]
+        pattern ? "Glob: #{pattern}" : "Glob"
+      when "WebFetch"
+        host = extract_host(input[:url])
+        host ? "WebFetch: #{host}" : "WebFetch"
+      when "WebSearch"
+        query = input[:query]
+        query ? "WebSearch: #{truncate(query, 50)}" : "WebSearch"
+      when "Task"
+        desc = input[:description]
+        desc ? "Task: #{truncate(desc, 50)}" : "Task"
+      else
+        name
+      end
+    end
+
+    # Detailed summary of the tool call, truncated to max chars.
+    # @param max [Integer] maximum length before truncation
+    # @return [String]
+    def summary(max: 60)
+      text = case name
+      when "Read"
+        path = file_path
+        path ? "Read: #{path}" : "Read"
+      when "Write"
+        path = file_path
+        if path
+          size = content_size(input[:content])
+          "Write: #{path} (#{size})"
+        else
+          "Write"
+        end
+      when "Edit"
+        path = file_path
+        if path
+          old = input[:old_string]
+          lines = old ? old.count("\n") + 1 : 0
+          "Edit: #{path} replacing #{lines} line(s)"
+        else
+          "Edit"
+        end
+      when "Bash"
+        cmd = input[:command]
+        cmd ? "Bash: #{cmd}" : "Bash"
+      when "Grep"
+        pattern = input[:pattern]
+        path = input[:path]
+        glob = input[:glob]
+        parts = [ "Grep: #{pattern}" ]
+        parts << "in #{path}" if path
+        parts << "(#{glob})" if glob
+        parts.join(" ")
+      when "NotebookEdit"
+        path = file_path
+        path ? "NotebookEdit: #{path}" : "NotebookEdit"
+      else
+        "#{name}: #{input.inspect}"
+      end
+
+      truncate(text, max)
+    end
+
+    private
+
+    def shorten_path(path)
+      parts = path.to_s.split("/")
+      parts.length > 2 ? parts.last(2).join("/") : path.to_s
+    end
+
+    def truncate(str, max)
+      return str if str.length <= max
+      "#{str[0, max]}..."
+    end
+
+    def extract_host(url)
+      return nil if url.nil?
+      URI.parse(url.to_s).host
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def content_size(content)
+      return "empty" if content.nil? || content.empty?
+      lines = content.count("\n") + 1
+      lines == 1 ? "1 line" : "#{lines} lines"
+    end
   end
 
   # Tool result block
@@ -81,6 +196,39 @@ module ClaudeAgent
     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
 
   # Server tool result block
@@ -110,11 +258,14 @@ module ClaudeAgent
   #   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
@@ -124,25 +275,25 @@ module ClaudeAgent
     # Get the media type if available
     # @return [String, nil]
     def media_type
-      source.is_a?(Hash) ? (source[:media_type] || source["media_type"]) : nil
+      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] || source["data"]) : nil
+      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] || source["url"]) : nil
+      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] || source["type"]) : nil
+      source.is_a?(Hash) ? source[:type] : nil
     end
 
     def to_h
@@ -150,6 +301,42 @@ module ClaudeAgent
     end
   end
 
+  # 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
+
   # All content block types
   CONTENT_BLOCK_TYPES = [
     TextBlock,
@@ -158,6 +345,7 @@ module ClaudeAgent
     ToolResultBlock,
     ServerToolUseBlock,
     ServerToolResultBlock,
-    ImageContentBlock
+    ImageContentBlock,
+    GenericBlock
   ].freeze
 end

data/lib/claude_agent/control_protocol.rb

@@ -24,6 +24,7 @@ module ClaudeAgent
     REQUEST_ID_PREFIX = "req"
 
     attr_reader :transport, :options, :server_info
+    attr_accessor :permission_queue
 
     # @param transport [Transport::Base] Transport for communication
     # @param options [Options] Configuration options
@@ -95,6 +96,9 @@ module ClaudeAgent
     def abort!
       @running = false
 
+      # Drain permission queue so reader thread unblocks
+      @permission_queue&.drain!(reason: "Operation aborted")
+
       # Fail all pending requests
       @mutex.synchronize do
         @pending_requests.each_key do |request_id|
@@ -443,6 +447,30 @@ module ClaudeAgent
       send_control_request(subtype: "mcp_toggle", serverName: 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
+    #   protocol.mcp_authenticate("my-remote-server")
+    #
+    def mcp_authenticate(server_name)
+      send_control_request(subtype: "mcp_authenticate", serverName: 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
+    #   protocol.mcp_clear_auth("my-remote-server")
+    #
+    def mcp_clear_auth(server_name)
+      send_control_request(subtype: "mcp_clear_auth", serverName: server_name)
+    end
+
     # Stop a running background task (TypeScript SDK parity)
     #
     # Sends a stop signal to a running task. A task_notification message
@@ -458,6 +486,20 @@ module ClaudeAgent
       send_control_request(subtype: "stop_task", task_id: 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
+    #   protocol.apply_flag_settings({ "model" => "claude-sonnet-4-5-20250514" })
+    #
+    def apply_flag_settings(settings)
+      send_control_request(subtype: "apply_flag_settings", settings: settings)
+    end
+
     # Dynamically set MCP servers for this session (TypeScript SDK parity)
     #
     # This replaces the current set of dynamically-added MCP servers.
@@ -588,27 +630,85 @@ module ClaudeAgent
     end
 
     # Handle can_use_tool permission request
+    #
+    # Supports three modes:
+    # 1. Synchronous callback — can_use_tool is set, returns result directly
+    # 2. Queue-based — permission_queue is set, enqueues and waits for resolution
+    # 3. Default allow — neither is set
+    #
+    # In hybrid mode (callback + queue), the callback can call
+    # context.request.defer! to enqueue the request instead of
+    # returning a synchronous answer.
+    #
     # @param request [Hash] Request data
     # @return [Hash] Response
     def handle_can_use_tool(request)
-      unless options.can_use_tool
-        logger.info("protocol") { "Permission decision for #{request["tool_name"]}: allow (no callback)" }
-        return { behavior: "allow" }
-      end
-
       tool_name = request["tool_name"]
-      input = request["input"] || {}
-      context = {
+      input = (request["input"] || {}).deep_symbolize_keys
+
+      # Build PermissionRequest for queue/hybrid modes
+      perm_request = PermissionRequest.new(
+        tool_name: tool_name,
+        input: input,
+        context: nil, # set below after ToolPermissionContext is built
+        request_id: request["tool_use_id"] || SecureRandom.hex(8)
+      )
+
+      context = ToolPermissionContext.new(
         permission_suggestions: request["permission_suggestions"],
         blocked_path: request["blocked_path"],
         decision_reason: request["decision_reason"],
         tool_use_id: request["tool_use_id"],
         agent_id: request["agent_id"],
-        description: request["description"]
-      }
+        description: request["description"],
+        signal: @abort_signal,
+        request: perm_request
+      )
 
-      result = options.can_use_tool.call(tool_name, input, context)
+      # Back-fill context on the request (circular, but both are needed)
+      perm_request.instance_variable_set(:@context, context)
+
+      # Mode 1: Synchronous callback
+      if options.can_use_tool
+        result = options.can_use_tool.call(tool_name, input, context)
+
+        # Check if the callback deferred to the queue
+        if perm_request.deferred?
+          return enqueue_and_wait(perm_request, tool_name, input)
+        end
 
+        return normalize_permission_result(result, tool_name, input)
+      end
+
+      # Mode 2: Queue-based
+      if @permission_queue
+        return enqueue_and_wait(perm_request, tool_name, input)
+      end
+
+      # Mode 3: Default allow
+      logger.info("protocol") { "Permission decision for #{tool_name}: allow (no callback)" }
+      { behavior: "allow" }
+    end
+
+    # Enqueue a permission request and block until resolved
+    # @param perm_request [PermissionRequest] The request to enqueue
+    # @param tool_name [String] Tool name (for logging)
+    # @param input [Hash] Original tool input
+    # @return [Hash] Normalized response
+    def enqueue_and_wait(perm_request, tool_name, input)
+      logger.info("protocol") { "Permission request queued for #{tool_name}" }
+      @permission_queue.push(perm_request)
+
+      result = perm_request.wait(timeout: DEFAULT_TIMEOUT)
+      normalize_permission_result(result, tool_name, input)
+    end
+
+    # Normalize a permission result for the CLI response
+    # @param result [PermissionResultAllow, PermissionResultDeny, Hash] The result
+    # @param tool_name [String] Tool name (for logging)
+    # @param input [Hash] Original tool input
+    # @return [Hash] Normalized response
+    def normalize_permission_result(result, tool_name, input)
       normalized = result.to_h
       logger.info("protocol") { "Permission decision for #{tool_name}: #{normalized[:behavior]}" }
 
@@ -624,7 +724,7 @@ module ClaudeAgent
     # @return [Hash] Response
     def handle_hook_callback(request)
       callback_id = request["callback_id"]
-      input = request["input"] || {}
+      input = (request["input"] || {}).deep_symbolize_keys
       tool_use_id = request["tool_use_id"]
 
       callback = @hook_callbacks[callback_id]

data/lib/claude_agent/conversation.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # High-level conversation interface managing the full lifecycle.
+  #
+  # Wraps {Client} and composes {TurnResult}, {EventHandler},
+  # {CumulativeUsage}, and {PermissionQueue} into a single stateful
+  # object. Auto-connects on first {#say}, tracks multi-turn history,
+  # and builds a unified tool activity timeline.
+  #
+  # @example Basic
+  #   conversation = ClaudeAgent::Conversation.new(
+  #     model: "claude-sonnet-4-5-20250514",
+  #     on_stream: ->(text) { print text }
+  #   )
+  #   turn = conversation.say("Fix the bug in auth.rb")
+  #   puts turn.text
+  #   conversation.close
+  #
+  # @example Block form
+  #   ClaudeAgent::Conversation.open(permission_mode: "default") do |c|
+  #     c.say("Help me write a function")
+  #     c.say("Now add tests")
+  #     puts "Total cost: $#{c.total_cost}"
+  #   end
+  #
+  # @example Resume a previous session
+  #   conversation = ClaudeAgent::Conversation.resume("session-abc")
+  #   conversation.say("Continue where we left off")
+  #
+  class Conversation
+    # Keys consumed by Conversation; everything else forwards to Options
+    CONVERSATION_KEYS = %i[
+      on_text on_stream on_tool_use on_tool_result
+      on_thinking on_result on_message on_permission
+      client options
+    ].freeze
+
+    attr_reader :turns, :messages, :tool_activity, :client
+
+    # Open a conversation with automatic cleanup.
+    #
+    # @yield [Conversation] The conversation
+    # @return [Object] Result of block
+    def self.open(**kwargs)
+      conversation = new(**kwargs)
+      begin
+        yield conversation
+      ensure
+        conversation.close
+      end
+    end
+
+    # Resume a previous conversation by session ID.
+    #
+    # @param session_id [String] Session ID to resume
+    # @return [Conversation]
+    def self.resume(session_id, **kwargs)
+      new(resume: session_id, **kwargs)
+    end
+
+    # Create a new conversation.
+    #
+    # Accepts all {Options} keyword arguments plus conversation-level
+    # callbacks:
+    #
+    # @param on_text [Proc] Handler for streaming text
+    # @param on_stream [Proc] Alias for on_text
+    # @param on_tool_use [Proc] Handler for tool use events
+    # @param on_tool_result [Proc] Handler for tool result events
+    # @param on_thinking [Proc] Handler for thinking events
+    # @param on_result [Proc] Handler for result events
+    # @param on_message [Proc] Handler for all messages
+    # @param on_permission [Symbol, Proc] :queue (default) or a callable for can_use_tool
+    # @param client [Client] Pre-built client (for testing)
+    # @param options [Options] Pre-built options object
+    #
+    def initialize(**kwargs)
+      conversation_kwargs = kwargs.slice(*CONVERSATION_KEYS)
+      options_kwargs = kwargs.except(*CONVERSATION_KEYS)
+
+      @options = conversation_kwargs[:options] || build_options(options_kwargs, conversation_kwargs)
+      @client = conversation_kwargs[:client] || Client.new(options: @options)
+
+      @turns = []
+      @messages = []
+      @tool_activity = []
+      @tool_use_timestamps = {}
+      @tool_result_timestamps = {}
+      @connected = false
+      @closed = false
+
+      register_callbacks(conversation_kwargs)
+      register_timing_hooks
+    end
+
+    # Send a message and receive the complete turn result.
+    #
+    # Auto-connects on first call. Appends to conversation history.
+    #
+    # @param prompt [String, Array] The message content
+    # @yield [Message] Each message as it streams in (optional)
+    # @return [TurnResult] The completed turn
+    def say(prompt, &block)
+      ensure_connected!
+
+      logger.debug("conversation") { "Turn #{@turns.size}: sending message" }
+
+      turn = @client.send_and_receive(prompt) do |message|
+        @messages << message
+        block&.call(message)
+      end
+
+      @turns << turn
+      build_tool_activities(turn, @turns.size - 1)
+
+      logger.info("conversation") { "Turn #{@turns.size - 1} complete (#{turn.tool_uses.size} tools, cost=$#{total_cost})" }
+
+      turn
+    end
+
+    # Total cost across all turns.
+    # @return [Float]
+    def total_cost
+      @client.cumulative_usage.total_cost_usd
+    end
+
+    # Session ID from the most recent turn.
+    # @return [String, nil]
+    def session_id
+      @turns.last&.session_id
+    end
+
+    # Cumulative usage stats.
+    # @return [CumulativeUsage]
+    def usage
+      @client.cumulative_usage
+    end
+
+    # Non-blocking poll for the next pending permission request.
+    # @return [PermissionRequest, nil]
+    def pending_permission
+      @client.pending_permission
+    end
+
+    # Whether any permission requests are pending.
+    # @return [Boolean]
+    def pending_permissions?
+      @client.pending_permissions?
+    end
+
+    # Close the conversation and disconnect the client.
+    # @return [void]
+    def close
+      return if @closed
+      logger.info("conversation") { "Closing (#{@turns.size} turns, cost=$#{total_cost})" }
+      @client.disconnect if @connected
+      @connected = false
+      @closed = true
+    end
+
+    # Whether the conversation is open (client connected).
+    # @return [Boolean]
+    def open?
+      @connected && !@closed
+    end
+
+    # Whether the conversation has been closed.
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    def inspect
+      parts = [ "#<#{self.class}" ]
+      parts << "turns=#{@turns.size}"
+      parts << "messages=#{@messages.size}"
+      parts << "tools=#{@tool_activity.size}" unless @tool_activity.empty?
+      parts << "cost=$#{total_cost}" if total_cost > 0
+      parts << "session=#{session_id}" if session_id
+      parts << (
+        if closed?
+          "closed"
+        else
+          open? ? "open" : "pending"
+        end)
+      "#{parts.join(" ")}>"
+    end
+
+    private
+
+    def build_options(options_kwargs, conversation_kwargs)
+      permission = conversation_kwargs[:on_permission]
+
+      if permission.respond_to?(:call)
+        options_kwargs[:can_use_tool] = permission
+      elsif permission == :queue || permission.nil?
+        options_kwargs[:permission_queue] = true unless options_kwargs.key?(:can_use_tool)
+      end
+
+      Options.new(**options_kwargs)
+    end
+
+    def register_callbacks(kwargs)
+      mapping = {
+        on_text: :text, on_stream: :text, on_thinking: :thinking,
+        on_tool_use: :tool_use, on_tool_result: :tool_result,
+        on_result: :result, on_message: :message
+      }
+
+      mapping.each do |key, event|
+        callback = kwargs[key]
+        @client.on(event, &callback) if callback
+      end
+    end
+
+    def register_timing_hooks
+      @client.on(:tool_use) { |tool| @tool_use_timestamps[tool.id] = Time.now }
+      @client.on(:tool_result) { |result, _| @tool_result_timestamps[result.tool_use_id] = Time.now }
+    end
+
+    def build_tool_activities(turn, turn_index)
+      turn.tool_executions.each do |exec|
+        tool_id = exec[:tool_use].id
+        @tool_activity << ToolActivity.new(
+          tool_use: exec[:tool_use],
+          tool_result: exec[:tool_result],
+          turn_index: turn_index,
+          started_at: @tool_use_timestamps.delete(tool_id),
+          completed_at: @tool_result_timestamps.delete(tool_id)
+        )
+      end
+    end
+
+    def logger
+      @options.effective_logger
+    end
+
+    def ensure_connected!
+      raise Error, "Conversation is closed" if @closed
+      return if @connected
+
+      logger.info("conversation") { "Auto-connecting" }
+      @client.connect
+      @connected = true
+    end
+  end
+end