claude_agent 0.7.7 → 0.7.9

data/lib/claude_agent/messages.rb

@@ -241,7 +241,7 @@ module ClaudeAgent
     # Get the event type from the raw event
     # @return [String, nil]
     def event_type
-      event["type"]
+      event[:type]
     end
   end
 
@@ -267,13 +267,13 @@ module ClaudeAgent
     # Get the compaction trigger type
     # @return [String] "manual" or "auto"
     def trigger
-      compact_metadata[:trigger] || compact_metadata["trigger"]
+      compact_metadata[:trigger]
     end
 
     # Get the token count before compaction
     # @return [Integer, nil]
     def pre_tokens
-      compact_metadata[:pre_tokens] || compact_metadata["pre_tokens"]
+      compact_metadata[:pre_tokens]
     end
   end
 
@@ -654,6 +654,41 @@ module ClaudeAgent
     end
   end
 
+  # Task progress message (TypeScript SDK v0.2.51 parity)
+  #
+  # Reports progress during background task (subagent) execution.
+  # Contains usage information and description of what the task is doing.
+  #
+  # @example
+  #   msg = TaskProgressMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     task_id: "task-456",
+  #     description: "Searching codebase for patterns",
+  #     usage: { total_tokens: 5000, tool_uses: 3, duration_ms: 2500 }
+  #   )
+  #
+  TaskProgressMessage = Data.define(
+    :uuid, :session_id, :task_id, :tool_use_id,
+    :description, :usage, :last_tool_name
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      task_id:,
+      description:,
+      usage: nil,
+      tool_use_id: nil,
+      last_tool_name: nil
+    )
+      super
+    end
+
+    def type
+      :task_progress
+    end
+  end
+
   # Rate limit event (TypeScript SDK v0.2.45 parity)
   #
   # Reports rate limit status and utilization information.
@@ -663,12 +698,12 @@ module ClaudeAgent
   #     uuid: "msg-123",
   #     session_id: "session-abc",
   #     rate_limit_info: {
-  #       "status" => "allowed_warning",
-  #       "resetsAt" => 1700000000,
-  #       "rateLimitType" => "five_hour",
-  #       "utilization" => 0.85,
-  #       "isUsingOverage" => false,
-  #       "overageStatus" => "available"
+  #       status: "allowed_warning",
+  #       resetsAt: 1700000000,
+  #       rateLimitType: "five_hour",
+  #       utilization: 0.85,
+  #       isUsingOverage: false,
+  #       overageStatus: "available"
   #     }
   #   )
   #   msg.status  # => "allowed_warning"
@@ -685,7 +720,7 @@ module ClaudeAgent
     # Get the rate limit status
     # @return [String, nil]
     def status
-      rate_limit_info["status"] || rate_limit_info[:status]
+      rate_limit_info[:status]
     end
   end
 
@@ -719,11 +754,11 @@ module ClaudeAgent
   #   msg = FilesPersistedEvent.new(
   #     uuid: "msg-123",
   #     session_id: "session-abc",
-  #     files: [{ "filename" => "test.rb", "file_id" => "file-456" }],
+  #     files: [{ filename: "test.rb", file_id: "file-456" }],
   #     failed: [],
   #     processed_at: "2026-01-30T12:00:00Z"
   #   )
-  #   msg.files.first["filename"]  # => "test.rb"
+  #   msg.files.first[:filename]  # => "test.rb"
   #
   FilesPersistedEvent = Data.define(
     :uuid,
@@ -747,6 +782,42 @@ module ClaudeAgent
     end
   end
 
+  # Generic message for unknown/future protocol types
+  #
+  # Wraps unrecognized top-level message types so they can be inspected
+  # without crashing the application. Supports dynamic field access via
+  # `[]` and `method_missing`.
+  #
+  # @example
+  #   msg = GenericMessage.new(message_type: "fancy_new", raw: { data: "hello" })
+  #   msg.type       # => :fancy_new
+  #   msg[:data]     # => "hello"
+  #   msg.data       # => "hello"
+  #   msg.to_h       # => { data: "hello" }
+  #
+  GenericMessage = Data.define(:message_type, :raw) do
+    def type
+      message_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 message types
   MESSAGE_TYPES = [
     UserMessage,
@@ -766,7 +837,9 @@ module ClaudeAgent
     ToolUseSummaryMessage,
     FilesPersistedEvent,
     TaskStartedMessage,
+    TaskProgressMessage,
     RateLimitEvent,
-    PromptSuggestionMessage
+    PromptSuggestionMessage,
+    GenericMessage
   ].freeze
 end

data/lib/claude_agent/options.rb

@@ -56,6 +56,7 @@ module ClaudeAgent
       system_prompt append_system_prompt
       model fallback_model
       permission_mode permission_prompt_tool_name can_use_tool 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
@@ -309,10 +310,10 @@ module ClaudeAgent
         raise ConfigurationError, "can_use_tool must be callable (Proc, Lambda, or object responding to #call)"
       end
 
-      # Auto-set permission_prompt_tool_name to "stdio" when can_use_tool is configured
-      # (Python/TypeScript SDK parity) so the CLI routes permission prompts through the
-      # control protocol instead of interactive terminal prompts
-      if can_use_tool && !permission_prompt_tool_name
+      # 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
+      if (can_use_tool || permission_queue) && !permission_prompt_tool_name
         @permission_prompt_tool_name = "stdio"
       end
 

data/lib/claude_agent/permission_queue.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Thread-safe queue of pending permission requests.
+  #
+  # Provides both blocking and non-blocking access to permission
+  # requests that need resolution from the main thread.
+  #
+  # @example Non-blocking poll in a UI timer
+  #   while request = client.permission_queue.poll
+  #     show_dialog(request)
+  #   end
+  #
+  # @example Blocking wait
+  #   request = client.permission_queue.pop  # blocks until available
+  #   request.allow!
+  #
+  class PermissionQueue
+    def initialize
+      @queue = Queue.new
+    end
+
+    # Non-blocking poll for the next pending request.
+    #
+    # @return [PermissionRequest, nil] The next request, or nil if empty
+    def poll
+      @queue.pop(true)
+    rescue ThreadError
+      nil
+    end
+
+    # Blocking pop — waits for a request to arrive.
+    #
+    # @param timeout [Numeric, nil] Maximum seconds to wait (nil = wait forever)
+    # @return [PermissionRequest, nil] The request, or nil if timed out
+    def pop(timeout: nil)
+      if timeout
+        deadline = Time.now + timeout
+        loop do
+          request = poll
+          return request if request
+          remaining = deadline - Time.now
+          return nil if remaining <= 0
+          sleep([ remaining, 0.05 ].min)
+        end
+      else
+        @queue.pop
+      end
+    end
+
+    # Check if there are pending requests.
+    # @return [Boolean]
+    def empty?
+      @queue.empty?
+    end
+
+    # Number of pending requests.
+    # @return [Integer]
+    def size
+      @queue.size
+    end
+
+    # @api private
+    # Push a request onto the queue (called by ControlProtocol).
+    #
+    # @param request [PermissionRequest]
+    # @return [void]
+    def push(request)
+      @queue.push(request)
+    end
+
+    # Deny all pending requests and drain the queue.
+    #
+    # Used during abort/disconnect to unblock the reader thread.
+    #
+    # @param reason [String] Denial reason for all pending requests
+    # @return [Array<PermissionRequest>] The drained requests
+    def drain!(reason: "Operation aborted")
+      requests = []
+      while (request = poll)
+        request.deny!(message: reason) unless request.resolved?
+        requests << request
+      end
+      requests
+    end
+  end
+end

data/lib/claude_agent/permission_request.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # A deferred permission request that can be resolved from any thread.
+  #
+  # When the control protocol receives a can_use_tool request and
+  # queue-based permissions are enabled, it creates a PermissionRequest
+  # and enqueues it. The main/UI thread resolves it by calling
+  # {#allow!} or {#deny!}, which unblocks the reader thread.
+  #
+  # @example Resolving from a UI thread
+  #   request = client.pending_permission
+  #   puts "Tool: #{request.tool_name}, Input: #{request.input}"
+  #   request.allow!
+  #
+  # @example Denying with a reason
+  #   request.deny!(message: "Not allowed in production")
+  #
+  # @example Hybrid mode — defer from a can_use_tool callback
+  #   can_use_tool: ->(name, input, context) {
+  #     if name == "Read"
+  #       ClaudeAgent::PermissionResultAllow.new  # auto-allow reads
+  #     else
+  #       context.request.defer!  # defer writes/bash to the UI
+  #     end
+  #   }
+  #
+  class PermissionRequest
+    attr_reader :tool_name, :input, :context, :request_id, :created_at
+
+    def initialize(tool_name:, input:, context:, request_id:)
+      @tool_name = tool_name
+      @input = input
+      @context = context
+      @request_id = request_id
+      @created_at = Time.now
+
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @resolved = false
+      @deferred = false
+      @result = nil
+    end
+
+    # Allow the tool to execute.
+    #
+    # @param updated_input [Hash, nil] Modified input to send to the tool
+    # @param updated_permissions [Array<PermissionUpdate>, nil] Permission rule updates
+    # @return [void]
+    # @raise [Error] If already resolved
+    def allow!(updated_input: nil, updated_permissions: nil)
+      resolve!(PermissionResultAllow.new(
+        updated_input: updated_input,
+        updated_permissions: updated_permissions,
+        tool_use_id: context&.tool_use_id
+      ))
+    end
+
+    # Deny the tool execution.
+    #
+    # @param message [String] Reason for denial
+    # @param interrupt [Boolean] Whether to interrupt the agent
+    # @return [void]
+    # @raise [Error] If already resolved
+    def deny!(message: "", interrupt: false)
+      resolve!(PermissionResultDeny.new(
+        message: message,
+        interrupt: interrupt,
+        tool_use_id: context&.tool_use_id
+      ))
+    end
+
+    # Mark this request as deferred (enqueue instead of resolving synchronously).
+    #
+    # Called from within a can_use_tool callback to signal that the
+    # callback will not return an answer. The protocol will enqueue
+    # the request and wait for {#allow!} or {#deny!} from another thread.
+    #
+    # @return [self]
+    def defer!
+      @mutex.synchronize { @deferred = true }
+      self
+    end
+
+    # Check if this request was deferred by a callback.
+    # @return [Boolean]
+    def deferred?
+      @mutex.synchronize { @deferred }
+    end
+
+    # Check if this request has been resolved.
+    # @return [Boolean]
+    def resolved?
+      @mutex.synchronize { @resolved }
+    end
+
+    # Check if this request is still pending.
+    # @return [Boolean]
+    def pending?
+      !resolved?
+    end
+
+    # Get the result (nil if not yet resolved).
+    # @return [PermissionResultAllow, PermissionResultDeny, nil]
+    def result
+      @mutex.synchronize { @result }
+    end
+
+    # @api private
+    # Block until resolved (called by ControlProtocol reader thread).
+    #
+    # @param timeout [Numeric, nil] Timeout in seconds
+    # @return [PermissionResultAllow, PermissionResultDeny]
+    # @raise [TimeoutError] If timeout expires before resolution
+    def wait(timeout: nil)
+      @mutex.synchronize do
+        unless @resolved
+          deadline = timeout ? Time.now + timeout : nil
+          until @resolved
+            remaining = deadline ? deadline - Time.now : nil
+            if remaining && remaining <= 0
+              raise TimeoutError.new(
+                "Permission request timed out",
+                request_id: request_id,
+                timeout_seconds: timeout
+              )
+            end
+            @condition.wait(@mutex, remaining ? [ remaining, 0.5 ].min : 0.5)
+          end
+        end
+        @result
+      end
+    end
+
+    def inspect
+      status = resolved? ? "resolved(#{@result&.behavior})" : "pending"
+      "#<#{self.class} tool=#{tool_name} status=#{status} age=#{(Time.now - created_at).round(1)}s>"
+    end
+
+    private
+
+    def resolve!(result)
+      @mutex.synchronize do
+        raise Error, "Permission request already resolved" if @resolved
+        @result = result
+        @resolved = true
+        @condition.broadcast
+      end
+    end
+  end
+end

data/lib/claude_agent/permissions.rb

@@ -157,7 +157,8 @@ module ClaudeAgent
     :tool_use_id,
     :agent_id,
     :signal,
-    :description
+    :description,
+    :request
   ) do
     def initialize(
       permission_suggestions: nil,
@@ -166,7 +167,8 @@ module ClaudeAgent
       tool_use_id: nil,
       agent_id: nil,
       signal: nil,
-      description: nil
+      description: nil,
+      request: nil
     )
       super
     end

data/lib/claude_agent/query.rb

@@ -118,6 +118,40 @@ module ClaudeAgent
       end
     end
 
+    # One-shot query that returns a TurnResult
+    #
+    # Like {query}, but accumulates all messages into a {TurnResult}
+    # for convenient access to text, tool use, usage, and more.
+    #
+    # @param prompt [String] The prompt to send to Claude
+    # @param options [Options, nil] Configuration options
+    # @param transport [Transport::Base, nil] Custom transport
+    # @param events [EventHandler, nil] Event handler for dispatching events
+    # @yield [Message] Each message as it arrives (optional)
+    # @return [TurnResult] The completed turn
+    #
+    # @example Simple
+    #   turn = ClaudeAgent.query_turn(prompt: "What is 2+2?")
+    #   puts turn.text
+    #   puts "Cost: $#{turn.cost}"
+    #
+    # @example With events
+    #   events = ClaudeAgent::EventHandler.new
+    #     .on_text { |text| print text }
+    #     .on_result { |r| puts "\nCost: $#{r.total_cost_usd}" }
+    #   turn = ClaudeAgent.query_turn(prompt: "Explain Ruby", events: events)
+    #
+    def query_turn(prompt:, options: nil, transport: nil, events: nil)
+      turn = TurnResult.new
+      query(prompt: prompt, options: options, transport: transport).each do |message|
+        turn << message
+        events&.handle(message)
+        yield message if block_given?
+      end
+      events&.reset!
+      turn
+    end
+
     private
 
     # Convert an Options object to a hash for merging

data/lib/claude_agent/tool_activity.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # A single tool execution in the conversation timeline.
+  #
+  # Pairs a ToolUseBlock with its ToolResultBlock and adds context
+  # about which turn it occurred in and when.
+  #
+  # @example
+  #   conversation.tool_activity.each do |activity|
+  #     puts activity.display_label
+  #     puts "  Turn: #{activity.turn_index}"
+  #     puts "  Duration: #{activity.duration}s" if activity.duration
+  #     puts "  Error!" if activity.error?
+  #   end
+  #
+  ToolActivity = Data.define(
+    :tool_use,
+    :tool_result,
+    :turn_index,
+    :started_at,
+    :completed_at
+  ) do
+    def initialize(tool_use:, tool_result: nil, turn_index:, started_at: nil, completed_at: nil)
+      super
+    end
+
+    # Tool name
+    # @return [String]
+    def name
+      tool_use.name
+    end
+
+    # Human-readable label (delegates to ToolUseBlock#display_label)
+    # @return [String]
+    def display_label
+      tool_use.display_label
+    end
+
+    # Detailed summary (delegates to ToolUseBlock#summary)
+    # @param max [Integer] Maximum length
+    # @return [String]
+    def summary(max: 60)
+      tool_use.summary(max: max)
+    end
+
+    # File path if this is a file-based tool
+    # @return [String, nil]
+    def file_path
+      tool_use.file_path
+    end
+
+    # Tool use ID
+    # @return [String]
+    def id
+      tool_use.id
+    end
+
+    # Whether the tool produced an error result
+    # @return [Boolean]
+    def error?
+      tool_result&.is_error == true
+    end
+
+    # Whether the tool execution is complete (has a result)
+    # @return [Boolean]
+    def complete?
+      !tool_result.nil?
+    end
+
+    # Duration in seconds (nil if timing not available)
+    # @return [Float, nil]
+    def duration
+      return nil unless started_at && completed_at
+      completed_at - started_at
+    end
+  end
+end