claude_agent 0.7.12 → 0.7.13

data/lib/claude_agent/control_protocol/primitives.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  class ControlProtocol
+    # Low-level protocol primitives: sending/receiving control messages,
+    # writing to transport, request ID generation, and initialization.
+    module Primitives
+      private
+
+      # Send a control request and wait for response
+      # @param subtype [String] Request subtype
+      # @param kwargs [Hash] Additional request data
+      # @param timeout [Integer] Timeout in seconds
+      # @return [Hash] Response data
+      # @raise [AbortError] If abort signal is triggered
+      def send_control_request(subtype:, timeout: DEFAULT_TIMEOUT, **kwargs)
+        # Check abort signal before sending
+        @abort_signal&.check!
+
+        request_id = generate_request_id
+        logger.debug("protocol") { "Sending control request: #{subtype} (#{request_id})" }
+
+        request = {
+          type: "control_request",
+          request_id: request_id,
+          request: { subtype: subtype, **kwargs }
+        }
+
+        @mutex.synchronize do
+          @pending_requests[request_id] = true
+        end
+
+        write_message(request)
+
+        # Wait for response
+        response = nil
+        @mutex.synchronize do
+          deadline = Time.now + timeout
+          until @pending_results.key?(request_id)
+            # Check abort signal during wait (outside mutex for thread safety)
+            if @abort_signal&.aborted?
+              @pending_requests.delete(request_id)
+              raise AbortError, @abort_signal.reason
+            end
+
+            remaining = deadline - Time.now
+            if remaining <= 0
+              @pending_requests.delete(request_id)
+              raise TimeoutError.new("Control request timed out", request_id: request_id, timeout_seconds: timeout)
+            end
+            @condition.wait(@mutex, [ remaining, 0.1 ].min) # Wake up periodically to check abort
+          end
+          response = @pending_results.delete(request_id)
+          @pending_requests.delete(request_id)
+        end
+
+        if response["subtype"] == "error"
+          logger.error("protocol") { "Control request failed: #{subtype} - #{response["error"]}" }
+          raise Error, response["error"] || "Unknown error"
+        end
+
+        response["response"] || response
+      end
+
+      # Send a control response
+      # @param request_id [String] Request ID to respond to
+      # @param data [Hash] Response data
+      def send_control_response(request_id, data)
+        response = {
+          type: "control_response",
+          response: {
+            subtype: data[:error] ? "error" : "success",
+            request_id: request_id
+          }
+        }
+
+        if data[:error]
+          response[:response][:error] = data[:error]
+        else
+          response[:response][:response] = data
+        end
+
+        write_message(response)
+      end
+
+      # Handle control response from CLI
+      # @param raw [Hash] Raw control response
+      def handle_control_response(raw)
+        response = raw["response"] || {}
+        request_id = response["request_id"]
+
+        @mutex.synchronize do
+          if @pending_requests.key?(request_id)
+            @pending_results[request_id] = response
+            @condition.broadcast
+          end
+        end
+      end
+
+      # Write a message to the transport
+      # @param message [Hash] Message to write
+      def write_message(message)
+        json = JSON.generate(message)
+        @transport.write(json)
+      end
+
+      # Generate a unique request ID
+      # @return [String]
+      def generate_request_id
+        @mutex.synchronize do
+          @request_counter += 1
+          "#{REQUEST_ID_PREFIX}_#{@request_counter}_#{SecureRandom.hex(4)}"
+        end
+      end
+
+      # Send initialization request
+      # @return [Hash] Server info
+      def send_initialize
+        hooks_config = build_hooks_config
+
+        request = { subtype: "initialize" }
+        request[:hooks] = hooks_config if hooks_config
+        request[:promptSuggestions] = true if options.prompt_suggestions
+        request[:sdkMcpServers] = sdk_mcp_server_names if options.has_sdk_mcp_servers?
+        request[:toolConfig] = options.tool_config if options.tool_config
+        request[:agentProgressSummaries] = true if options.agent_progress_summaries
+
+        send_control_request(**request)
+      end
+
+      # Build hooks configuration for initialization
+      # @return [Hash, nil]
+      def build_hooks_config
+        return nil unless options.has_hooks?
+
+        config = {}
+
+        options.hooks.each do |event, matchers|
+          config[event] = matchers.map.with_index do |matcher, idx|
+            callback_ids = matcher.callbacks.map.with_index do |callback, cidx|
+              callback_id = "hook_#{event}_#{idx}_#{cidx}"
+              @hook_callbacks[callback_id] = callback
+              callback_id
+            end
+
+            entry = {
+              matcher: matcher.matcher,
+              hookCallbackIds: callback_ids
+            }
+            entry[:timeout] = matcher.timeout if matcher.timeout
+            entry
+          end
+        end
+
+        config
+      end
+
+      # Extract SDK MCP server names from options
+      # @return [Array<String>]
+      def sdk_mcp_server_names
+        options.mcp_servers
+          .select { |_, v| v.is_a?(Hash) && v[:type] == "sdk" }
+          .keys
+          .map(&:to_s)
+      end
+    end
+  end
+end

data/lib/claude_agent/control_protocol/request_handling.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  class ControlProtocol
+    # Handles incoming control requests from the CLI: permission checks,
+    # hook callbacks, MCP message routing, and elicitation.
+    module RequestHandling
+      private
+
+      # Handle incoming control request from CLI
+      # @param raw [Hash] Raw control request
+      def handle_control_request(raw)
+        request = raw["request"] || {}
+        request_id = raw["request_id"]
+        subtype = request["subtype"]
+
+        response = case subtype
+        when "can_use_tool"
+          handle_can_use_tool(request)
+        when "hook_callback"
+          handle_hook_callback(request)
+        when "mcp_message"
+          handle_mcp_message(request)
+        when "elicitation"
+          handle_elicitation(request)
+        else
+          { error: "Unknown control request subtype: #{subtype}" }
+        end
+
+        send_control_response(request_id, response)
+      rescue => e
+        send_control_response(request_id, { error: e.message })
+      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)
+        tool_name = request["tool_name"]
+        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"],
+          signal: @abort_signal,
+          request: perm_request
+        )
+
+        # 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]}" }
+
+        if normalized[:behavior] == "allow" && !normalized.key?(:updatedInput)
+          normalized[:updatedInput] = input
+        end
+
+        normalized
+      end
+
+      # Handle hook callback request
+      # @param request [Hash] Request data
+      # @return [Hash] Response
+      def handle_hook_callback(request)
+        callback_id = request["callback_id"]
+        input = (request["input"] || {}).deep_symbolize_keys
+        tool_use_id = request["tool_use_id"]
+
+        callback = @hook_callbacks[callback_id]
+        unless callback
+          logger.debug("protocol") { "Hook callback not found: #{callback_id}" }
+          return {}
+        end
+        logger.debug("protocol") { "Hook callback: #{callback_id}" }
+
+        context = { tool_use_id: tool_use_id }
+        result = callback.call(input, context)
+
+        # Normalize result - convert Ruby field names to CLI field names
+        normalize_hook_response(result || {})
+      end
+
+      # Handle MCP message routing
+      # @param request [Hash] Request data
+      # @return [Hash] Response
+      def handle_mcp_message(request)
+        server_name = request["server_name"]
+        message = request["message"]
+        logger.debug("protocol") { "MCP message for #{server_name}: #{message["method"]}" }
+
+        # Find SDK MCP server
+        server_config = options.mcp_servers[server_name]
+        return { error: "Unknown MCP server: #{server_name}" } unless server_config
+        return { error: "Not an SDK MCP server" } unless server_config[:type] == "sdk"
+
+        server_instance = server_config[:instance]
+        return { error: "No server instance" } unless server_instance
+
+        # Route message to server
+        mcp_response = server_instance.handle_message(message)
+        { mcp_response: mcp_response }
+      end
+
+      # Handle elicitation request from CLI (TypeScript SDK v0.2.63 parity)
+      # @param request [Hash] Request data
+      # @return [Hash] Response
+      def handle_elicitation(request)
+        elicitation_request = {
+          server_name: request["mcp_server_name"],
+          message: request["message"],
+          mode: request["mode"],
+          url: request["url"],
+          elicitation_id: request["elicitation_id"],
+          requested_schema: request["requested_schema"]
+        }
+
+        if options.on_elicitation
+          result = options.on_elicitation.call(elicitation_request, signal: @abort_signal)
+          return normalize_elicitation_result(result)
+        end
+
+        # Default: decline
+        { action: "decline" }
+      end
+
+      # Normalize an elicitation result for the CLI response
+      # @param result [Hash, nil] The result from the callback
+      # @return [Hash] Normalized response
+      def normalize_elicitation_result(result)
+        return { action: "decline" } unless result
+
+        result = result.to_h if result.respond_to?(:to_h) && !result.is_a?(Hash)
+        {
+          action: result[:action] || result["action"] || "decline",
+          content: result[:content] || result["content"]
+        }.compact
+      end
+
+      # Normalize hook response for CLI
+      # @param result [Hash] Raw result from callback
+      # @return [Hash] Normalized response
+      def normalize_hook_response(result)
+        result = result.to_h
+
+        response = HOOK_RESPONSE_KEYS.each_with_object({}) do |(ruby_key, json_key), acc|
+          acc[json_key] = result[ruby_key] if result.key?(ruby_key)
+        end
+
+        if result[:hook_specific_output]
+          response["hookSpecificOutput"] = normalize_hook_specific_output(result[:hook_specific_output])
+        end
+
+        response
+      end
+
+      # Normalize hookSpecificOutput nested fields to camelCase
+      # @param hso [Hash] Hook-specific output
+      # @return [Hash] Normalized output
+      def normalize_hook_specific_output(hso)
+        hso.each_with_object({}) do |(key, value), normalized|
+          camel_key = key.to_s.camelize(:lower)
+          normalized[camel_key] = value
+        end
+      end
+    end
+  end
+end