claude_agent 0.7.10 → 0.7.11

data/lib/claude_agent/tool_activity_tracker.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Enumerable collection of {LiveToolActivity} entries with auto-wiring.
+  #
+  # Attaches to an {EventHandler} or {Client} and automatically tracks
+  # tool lifecycle events (:tool_use, :tool_result, :tool_progress),
+  # maintaining a live view of active and completed tools.
+  #
+  # @example Specific callbacks
+  #   tracker = ToolActivityTracker.attach(client)
+  #   tracker.on_start    { |entry| puts "▸ #{entry.display_label}" }
+  #   tracker.on_progress { |entry| puts "  #{entry.elapsed&.round(1)}s..." }
+  #   tracker.on_complete { |entry| puts "✓ #{entry.display_label}" }
+  #
+  # @example Catch-all callback
+  #   tracker.on_change { |event, entry| log(event, entry.id) }
+  #
+  # @example Poll running tools
+  #   tracker.running.each { |t| render_spinner(t) }
+  #   tracker.done.each { |t| render_checkmark(t) }
+  #
+  class ToolActivityTracker
+    include Enumerable
+
+    # Create a tracker and wire it to an EventHandler or Client.
+    #
+    # @param target [EventHandler, Client] The event source to wire into
+    # @return [ToolActivityTracker]
+    def self.attach(target)
+      tracker = new
+      handler = target.is_a?(EventHandler) ? target : target.event_handler
+      tracker.send(:wire, handler)
+      tracker
+    end
+
+    def initialize
+      @entries = []
+      @index = {}
+      @callbacks = {}
+    end
+
+    # Register a callback for when a tool starts running.
+    #
+    # @yield [entry] Called when a tool use is detected
+    # @yieldparam entry [LiveToolActivity] The new entry
+    # @return [self]
+    def on_start(&block)
+      @callbacks[:started] = block
+      self
+    end
+
+    # Register a callback for when a tool completes (success or error).
+    #
+    # @yield [entry] Called when a tool result is received
+    # @yieldparam entry [LiveToolActivity] The completed entry
+    # @return [self]
+    def on_complete(&block)
+      @callbacks[:completed] = block
+      self
+    end
+
+    # Register a callback for tool progress updates.
+    #
+    # @yield [entry] Called when elapsed time is updated
+    # @yieldparam entry [LiveToolActivity] The updated entry
+    # @return [self]
+    def on_progress(&block)
+      @callbacks[:progress] = block
+      self
+    end
+
+    # Register a catch-all callback for any state change.
+    #
+    # Fires with :started, :completed, or :progress and the affected entry.
+    # Fires in addition to specific callbacks (on_start, on_complete, on_progress).
+    #
+    # @yield [event, entry] Called on each state change
+    # @yieldparam event [Symbol] :started, :completed, or :progress
+    # @yieldparam entry [LiveToolActivity] The affected entry
+    # @return [self]
+    def on_change(&block)
+      @callbacks[:change] = block
+      self
+    end
+
+    # @yield [LiveToolActivity]
+    # @return [Enumerator<LiveToolActivity>]
+    def each(&block)
+      @entries.each(&block)
+    end
+
+    # Number of tracked activities.
+    # @return [Integer]
+    def size
+      @entries.size
+    end
+
+    # Whether there are no tracked activities.
+    # @return [Boolean]
+    def empty?
+      @entries.empty?
+    end
+
+    # Look up a LiveToolActivity by tool use ID.
+    #
+    # @param id [String] Tool use ID
+    # @return [LiveToolActivity, nil]
+    def find_by_id(id)
+      @index[id]
+    end
+
+    alias_method :[], :find_by_id
+
+    # All currently running activities.
+    # @return [Array<LiveToolActivity>]
+    def running
+      @entries.select(&:running?)
+    end
+
+    # All completed (success) activities.
+    # @return [Array<LiveToolActivity>]
+    def done
+      @entries.select(&:done?)
+    end
+
+    # All errored activities.
+    # @return [Array<LiveToolActivity>]
+    def errored
+      @entries.select(&:error?)
+    end
+
+    # Clear all tracked state. Call between turns.
+    # @return [void]
+    def reset!
+      @entries.clear
+      @index.clear
+    end
+
+    private
+
+    def wire(handler)
+      handler.on(:tool_use) { |tool_use| handle_tool_use(tool_use) }
+      handler.on(:tool_result) { |tool_result, _tool_use| handle_tool_result(tool_result) }
+      handler.on(:tool_progress) { |message| handle_tool_progress(message) }
+    end
+
+    def emit(event, entry)
+      @callbacks[event]&.call(entry)
+      @callbacks[:change]&.call(event, entry)
+    end
+
+    def handle_tool_use(tool_use)
+      entry = LiveToolActivity.new(tool_use)
+      @entries << entry
+      @index[tool_use.id] = entry
+      emit(:started, entry)
+    end
+
+    def handle_tool_result(tool_result)
+      entry = @index[tool_result.tool_use_id]
+      return unless entry
+
+      entry.complete!(tool_result)
+      emit(:completed, entry)
+    end
+
+    def handle_tool_progress(message)
+      entry = @index[message.tool_use_id]
+      return unless entry
+
+      entry.update_elapsed(message.elapsed_time_seconds)
+      emit(:progress, entry)
+    end
+  end
+end

data/lib/claude_agent/types.rb

@@ -15,7 +15,7 @@ module ClaudeAgent
 
   # API key source types (TypeScript SDK parity)
   # Indicates where the API key was sourced from
-  API_KEY_SOURCES = %w[user project org temporary].freeze
+  API_KEY_SOURCES = %w[user project org temporary oauth].freeze
 
   # Tools preset configuration (TypeScript SDK parity)
   #
@@ -52,8 +52,8 @@ module ClaudeAgent
   #   model.value        # => "claude-3-opus"
   #   model.display_name # => "Claude 3 Opus"
   #
-  ModelInfo = Data.define(:value, :display_name, :description) do
-    def initialize(value:, display_name: nil, description: nil)
+  ModelInfo = Data.define(:value, :display_name, :description, :supports_effort, :supported_effort_levels, :supports_adaptive_thinking) do
+    def initialize(value:, display_name: nil, description: nil, supports_effort: nil, supported_effort_levels: nil, supports_adaptive_thinking: nil)
       super
     end
   end
@@ -64,8 +64,19 @@ module ClaudeAgent
   # @example
   #   status = McpServerStatus.new(name: "filesystem", status: "connected", server_info: {name: "fs", version: "1.0"})
   #
-  McpServerStatus = Data.define(:name, :status, :server_info) do
-    def initialize(name:, status:, server_info: nil)
+  McpServerStatus = Data.define(:name, :status, :server_info, :error, :config, :scope, :tools) do
+    def initialize(name:, status:, server_info: nil, error: nil, config: nil, scope: nil, tools: nil)
+      super
+    end
+  end
+
+  # Task usage statistics for TaskNotificationMessage (TypeScript SDK parity)
+  #
+  # @example
+  #   usage = TaskUsage.new(total_tokens: 5000, tool_uses: 3, duration_ms: 2500)
+  #
+  TaskUsage = Data.define(:total_tokens, :tool_uses, :duration_ms) do
+    def initialize(total_tokens: 0, tool_uses: 0, duration_ms: 0)
       super
     end
   end

data/lib/claude_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgent
-  VERSION = "0.7.10"
+  VERSION = "0.7.11"
 end

data/lib/claude_agent.rb

@@ -27,6 +27,8 @@ require_relative "claude_agent/cumulative_usage"
 require_relative "claude_agent/event_handler"
 require_relative "claude_agent/turn_result"
 require_relative "claude_agent/tool_activity"
+require_relative "claude_agent/live_tool_activity"
+require_relative "claude_agent/tool_activity_tracker"
 require_relative "claude_agent/query"
 require_relative "claude_agent/client"
 require_relative "claude_agent/conversation"

data/sig/claude_agent.rbs

@@ -128,16 +128,31 @@ module ClaudeAgent
     attr_reader value: String
     attr_reader display_name: String?
     attr_reader description: String?
+    attr_reader supports_effort: bool?
+    attr_reader supported_effort_levels: Array[String]?
+    attr_reader supports_adaptive_thinking: bool?
 
-    def initialize: (value: String, ?display_name: String?, ?description: String?) -> void
+    def initialize: (value: String, ?display_name: String?, ?description: String?, ?supports_effort: bool?, ?supported_effort_levels: Array[String]?, ?supports_adaptive_thinking: bool?) -> void
   end
 
   class McpServerStatus
     attr_reader name: String
     attr_reader status: String
     attr_reader server_info: Hash[String, untyped]?
+    attr_reader error: String?
+    attr_reader config: Hash[String, untyped]?
+    attr_reader scope: String?
+    attr_reader tools: Array[Hash[String, untyped]]?
+
+    def initialize: (name: String, status: String, ?server_info: Hash[String, untyped]?, ?error: String?, ?config: Hash[String, untyped]?, ?scope: String?, ?tools: Array[Hash[String, untyped]]?) -> void
+  end
 
-    def initialize: (name: String, status: String, ?server_info: Hash[String, untyped]?) -> void
+  class TaskUsage
+    attr_reader total_tokens: Integer
+    attr_reader tool_uses: Integer
+    attr_reader duration_ms: Integer
+
+    def initialize: (?total_tokens: Integer, ?tool_uses: Integer, ?duration_ms: Integer) -> void
   end
 
   class AccountInfo
@@ -357,15 +372,13 @@ module ClaudeAgent
     # Hooks
     attr_accessor hooks: Hash[String, Array[HookMatcher]]?
 
-    # Settings & sandbox
-    attr_accessor settings: String?
+    # Sandbox
     attr_accessor sandbox: SandboxSettings?
 
     # Environment
     attr_accessor cwd: String?
     attr_accessor add_dirs: Array[String]
     attr_accessor env: Hash[String, String]
-    attr_accessor user: String?
     attr_accessor agent: String?
 
     # CLI configuration
@@ -636,8 +649,9 @@ module ClaudeAgent
     attr_reader uuid: String
     attr_reader session_id: String
     attr_reader status: String
+    attr_reader permission_mode: String?
 
-    def initialize: (uuid: String, session_id: String, status: String) -> void
+    def initialize: (uuid: String, session_id: String, status: String, ?permission_mode: String?) -> void
     def type: () -> :status
   end
 
@@ -649,8 +663,9 @@ module ClaudeAgent
     attr_reader tool_name: String
     attr_reader parent_tool_use_id: String?
     attr_reader elapsed_time_seconds: Float
+    attr_reader task_id: String?
 
-    def initialize: (uuid: String, session_id: String, tool_use_id: String, tool_name: String, elapsed_time_seconds: Float, ?parent_tool_use_id: String?) -> void
+    def initialize: (uuid: String, session_id: String, tool_use_id: String, tool_name: String, elapsed_time_seconds: Float, ?parent_tool_use_id: String?, ?task_id: String?) -> void
     def type: () -> :tool_progress
   end
 
@@ -694,8 +709,10 @@ module ClaudeAgent
     attr_reader status: String
     attr_reader output_file: String
     attr_reader summary: String
+    attr_reader tool_use_id: String?
+    attr_reader usage: TaskUsage?
 
-    def initialize: (uuid: String, session_id: String, task_id: String, status: String, output_file: String, summary: String) -> void
+    def initialize: (uuid: String, session_id: String, task_id: String, status: String, output_file: String, summary: String, ?tool_use_id: String?, ?usage: TaskUsage?) -> void
     def type: () -> :task_notification
     def completed?: () -> bool
     def failed?: () -> bool
@@ -897,8 +914,9 @@ module ClaudeAgent
 
   class StopInput < BaseHookInput
     attr_reader stop_hook_active: bool
+    attr_reader last_assistant_message: String?
 
-    def initialize: (?stop_hook_active: bool, **untyped) -> void
+    def initialize: (?stop_hook_active: bool, ?last_assistant_message: String?, **untyped) -> void
   end
 
   class SubagentStartInput < BaseHookInput
@@ -912,8 +930,10 @@ module ClaudeAgent
     attr_reader stop_hook_active: bool
     attr_reader agent_id: String?
     attr_reader agent_transcript_path: String?
+    attr_reader agent_type: String?
+    attr_reader last_assistant_message: String?
 
-    def initialize: (?stop_hook_active: bool, ?agent_id: String?, ?agent_transcript_path: String?, **untyped) -> void
+    def initialize: (?stop_hook_active: bool, ?agent_id: String?, ?agent_transcript_path: String?, ?agent_type: String?, ?last_assistant_message: String?, **untyped) -> void
   end
 
   class PreCompactInput < BaseHookInput
@@ -1132,14 +1152,44 @@ module ClaudeAgent
 
   # Event handler for dispatching typed events from message streams
   class EventHandler
+    TYPE_EVENTS: Array[Symbol]
+    DECOMPOSED_EVENTS: Array[Symbol]
+    META_EVENTS: Array[Symbol]
+    EVENTS: Array[Symbol]
+
     def initialize: () -> void
     def on: (Symbol event) { (*untyped) -> void } -> self
+
+    # Meta events
     def on_message: () { (message) -> void } -> self
+
+    # Type-based events
+    def on_user: () { (UserMessage | UserMessageReplay) -> void } -> self
+    def on_assistant: () { (AssistantMessage) -> void } -> self
+    def on_system: () { (SystemMessage) -> void } -> self
+    def on_result: () { (ResultMessage) -> void } -> self
+    def on_stream_event: () { (StreamEvent) -> void } -> self
+    def on_compact_boundary: () { (CompactBoundaryMessage) -> void } -> self
+    def on_status: () { (StatusMessage) -> void } -> self
+    def on_tool_progress: () { (ToolProgressMessage) -> void } -> self
+    def on_hook_response: () { (HookResponseMessage) -> void } -> self
+    def on_auth_status: () { (AuthStatusMessage) -> void } -> self
+    def on_task_notification: () { (TaskNotificationMessage) -> void } -> self
+    def on_hook_started: () { (HookStartedMessage) -> void } -> self
+    def on_hook_progress: () { (HookProgressMessage) -> void } -> self
+    def on_tool_use_summary: () { (ToolUseSummaryMessage) -> void } -> self
+    def on_task_started: () { (TaskStartedMessage) -> void } -> self
+    def on_task_progress: () { (TaskProgressMessage) -> void } -> self
+    def on_rate_limit_event: () { (RateLimitEvent) -> void } -> self
+    def on_prompt_suggestion: () { (PromptSuggestionMessage) -> void } -> self
+    def on_files_persisted: () { (FilesPersistedEvent) -> void } -> self
+
+    # Decomposed events
     def on_text: () { (String) -> void } -> self
     def on_thinking: () { (String) -> void } -> self
     def on_tool_use: () { (ToolUseBlock | ServerToolUseBlock) -> void } -> self
     def on_tool_result: () { (ToolResultBlock | ServerToolResultBlock, (ToolUseBlock | ServerToolUseBlock)?) -> void } -> self
-    def on_result: () { (ResultMessage) -> void } -> self
+
     def handle: (message) -> void
     def reset!: () -> void
     def has_handlers?: () -> bool
@@ -1164,14 +1214,64 @@ module ClaudeAgent
     def duration: () -> Float?
   end
 
+  # Mutable wrapper around a ToolUseBlock for real-time status tracking
+  class LiveToolActivity
+    attr_reader tool_use: ToolUseBlock | ServerToolUseBlock
+    attr_reader tool_result: ToolResultBlock | ServerToolResultBlock | nil
+    attr_reader status: Symbol
+    attr_reader started_at: Time
+    attr_reader elapsed: Float?
+
+    def initialize: (ToolUseBlock | ServerToolUseBlock tool_use) -> void
+    def id: () -> String
+    def name: () -> String
+    def input: () -> Hash[Symbol | String, untyped]
+    def display_label: () -> String
+    def summary: (?max: Integer) -> String
+    def file_path: () -> String?
+    def complete!: (ToolResultBlock | ServerToolResultBlock result) -> void
+    def update_elapsed: (Float seconds) -> void
+    def running?: () -> bool
+    def done?: () -> bool
+    def error?: () -> bool
+    def complete?: () -> bool
+    def to_h: () -> Hash[Symbol, untyped]
+    def inspect: () -> String
+  end
+
+  # Enumerable collection of LiveToolActivity entries with auto-wiring
+  class ToolActivityTracker
+    include Enumerable[LiveToolActivity]
+
+    def self.attach: (EventHandler | Client target) -> ToolActivityTracker
+
+    def initialize: () -> void
+    def on_start: () { (LiveToolActivity) -> void } -> self
+    def on_complete: () { (LiveToolActivity) -> void } -> self
+    def on_progress: () { (LiveToolActivity) -> void } -> self
+    def on_change: () { (Symbol, LiveToolActivity) -> void } -> self
+    def each: () { (LiveToolActivity) -> void } -> void
+            | () -> Enumerator[LiveToolActivity, void]
+    def size: () -> Integer
+    def empty?: () -> bool
+    def find_by_id: (String id) -> LiveToolActivity?
+    def []: (String id) -> LiveToolActivity?
+    def running: () -> Array[LiveToolActivity]
+    def done: () -> Array[LiveToolActivity]
+    def errored: () -> Array[LiveToolActivity]
+    def reset!: () -> void
+  end
+
   # High-level conversation interface managing the full lifecycle
   class Conversation
     CONVERSATION_KEYS: Array[Symbol]
+    CALLBACK_ALIASES: Hash[Symbol, Symbol]
 
     attr_reader turns: Array[TurnResult]
     attr_reader messages: Array[message]
     attr_reader tool_activity: Array[ToolActivity]
     attr_reader client: Client
+    attr_reader tool_tracker: ToolActivityTracker?
 
     def self.open: (**untyped) { (Conversation) -> void } -> void
     def self.resume: (String session_id, **untyped) -> Conversation
@@ -1245,12 +1345,37 @@ module ClaudeAgent
     def send_message: (String | Array[content_block] content, ?session_id: String, ?uuid: String?) -> void
     alias query send_message
     def on: (Symbol event) { (*untyped) -> void } -> self
+
+    # Meta events
     def on_message: () { (message) -> void } -> self
+
+    # Type-based events
+    def on_user: () { (UserMessage | UserMessageReplay) -> void } -> self
+    def on_assistant: () { (AssistantMessage) -> void } -> self
+    def on_system: () { (SystemMessage) -> void } -> self
+    def on_result: () { (ResultMessage) -> void } -> self
+    def on_stream_event: () { (StreamEvent) -> void } -> self
+    def on_compact_boundary: () { (CompactBoundaryMessage) -> void } -> self
+    def on_status: () { (StatusMessage) -> void } -> self
+    def on_tool_progress: () { (ToolProgressMessage) -> void } -> self
+    def on_hook_response: () { (HookResponseMessage) -> void } -> self
+    def on_auth_status: () { (AuthStatusMessage) -> void } -> self
+    def on_task_notification: () { (TaskNotificationMessage) -> void } -> self
+    def on_hook_started: () { (HookStartedMessage) -> void } -> self
+    def on_hook_progress: () { (HookProgressMessage) -> void } -> self
+    def on_tool_use_summary: () { (ToolUseSummaryMessage) -> void } -> self
+    def on_task_started: () { (TaskStartedMessage) -> void } -> self
+    def on_task_progress: () { (TaskProgressMessage) -> void } -> self
+    def on_rate_limit_event: () { (RateLimitEvent) -> void } -> self
+    def on_prompt_suggestion: () { (PromptSuggestionMessage) -> void } -> self
+    def on_files_persisted: () { (FilesPersistedEvent) -> void } -> self
+
+    # Decomposed events
     def on_text: () { (String) -> void } -> self
     def on_thinking: () { (String) -> void } -> self
     def on_tool_use: () { (ToolUseBlock | ServerToolUseBlock) -> void } -> self
     def on_tool_result: () { (ToolResultBlock | ServerToolResultBlock, (ToolUseBlock | ServerToolUseBlock)?) -> void } -> self
-    def on_result: () { (ResultMessage) -> void } -> self
+
     def receive_messages: () { (message) -> void } -> void
                         | () -> Enumerator[message, void]
     def receive_response: () { (message) -> void } -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.7.10
+  version: 0.7.11
 platform: ruby
 authors:
 - Thomas Carr
@@ -62,6 +62,7 @@ files:
 - lib/claude_agent/get_session_messages.rb
 - lib/claude_agent/hooks.rb
 - lib/claude_agent/list_sessions.rb
+- lib/claude_agent/live_tool_activity.rb
 - lib/claude_agent/logging.rb
 - lib/claude_agent/mcp/server.rb
 - lib/claude_agent/mcp/tool.rb
@@ -78,6 +79,7 @@ files:
 - lib/claude_agent/session_paths.rb
 - lib/claude_agent/spawn.rb
 - lib/claude_agent/tool_activity.rb
+- lib/claude_agent/tool_activity_tracker.rb
 - lib/claude_agent/transport/base.rb
 - lib/claude_agent/transport/subprocess.rb
 - lib/claude_agent/turn_result.rb