claude_agent 0.7.7 → 0.7.9

data/lib/claude_agent/cumulative_usage.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Tracks cumulative usage statistics across multiple conversation turns
+  #
+  # Token counts are summed across all turns. Cost and turn count reflect
+  # the session-cumulative values from the most recent result (the CLI
+  # already accumulates these across the session).
+  #
+  # @example Via Client
+  #   ClaudeAgent::Client.open do |client|
+  #     client.send_message("Hello")
+  #     client.receive_response.each { |m| }
+  #
+  #     client.send_message("Follow up")
+  #     client.receive_response.each { |m| }
+  #
+  #     usage = client.cumulative_usage
+  #     puts "Tokens: #{usage.input_tokens} in / #{usage.output_tokens} out"
+  #     puts "Cost: $#{usage.total_cost_usd}"
+  #     puts "Turns: #{usage.num_turns}"
+  #   end
+  #
+  # @example Standalone
+  #   tracker = ClaudeAgent::CumulativeUsage.new
+  #   messages.each { |msg| tracker.track(msg) }
+  #   puts tracker.to_h
+  #
+  class CumulativeUsage
+    attr_reader :input_tokens, :output_tokens,
+                :cache_read_input_tokens, :cache_creation_input_tokens,
+                :total_cost_usd, :num_turns,
+                :duration_ms, :duration_api_ms
+
+    def initialize
+      @mutex = Mutex.new
+      @input_tokens = 0
+      @output_tokens = 0
+      @cache_read_input_tokens = 0
+      @cache_creation_input_tokens = 0
+      @total_cost_usd = 0.0
+      @num_turns = 0
+      @duration_ms = 0
+      @duration_api_ms = 0
+    end
+
+    # Update cumulative usage from a message
+    #
+    # Only processes {ResultMessage} instances; other message types are ignored.
+    #
+    # @param message [Object] Any message object
+    # @return [void]
+    def track(message)
+      return unless message.is_a?(ResultMessage)
+
+      @mutex.synchronize do
+        if message.usage
+          @input_tokens += message.usage[:input_tokens].to_i
+          @output_tokens += message.usage[:output_tokens].to_i
+          @cache_read_input_tokens += message.usage[:cache_read_input_tokens].to_i
+          @cache_creation_input_tokens += message.usage[:cache_creation_input_tokens].to_i
+        end
+
+        # Cost and turn count are session-cumulative from the CLI
+        @total_cost_usd = message.total_cost_usd if message.total_cost_usd
+        @num_turns = message.num_turns if message.num_turns
+
+        # Durations are per-turn, sum them
+        @duration_ms += message.duration_ms.to_i
+        @duration_api_ms += message.duration_api_ms.to_i
+      end
+    end
+
+    # Reset all counters to zero
+    #
+    # @return [void]
+    def reset!
+      @mutex.synchronize do
+        @input_tokens = 0
+        @output_tokens = 0
+        @cache_read_input_tokens = 0
+        @cache_creation_input_tokens = 0
+        @total_cost_usd = 0.0
+        @num_turns = 0
+        @duration_ms = 0
+        @duration_api_ms = 0
+      end
+    end
+
+    # @return [Hash] All tracked fields as a hash
+    def to_h
+      @mutex.synchronize do
+        {
+          input_tokens: @input_tokens,
+          output_tokens: @output_tokens,
+          cache_read_input_tokens: @cache_read_input_tokens,
+          cache_creation_input_tokens: @cache_creation_input_tokens,
+          total_cost_usd: @total_cost_usd,
+          num_turns: @num_turns,
+          duration_ms: @duration_ms,
+          duration_api_ms: @duration_api_ms
+        }
+      end
+    end
+  end
+end

data/lib/claude_agent/event_handler.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Dispatches typed events as messages flow through a conversation turn.
+  #
+  # Register handlers for specific events instead of writing `case` statements
+  # over raw message types. Use standalone or via {Client#on}.
+  #
+  # @example Standalone
+  #   handler = ClaudeAgent::EventHandler.new
+  #   handler.on_text { |text| print text }
+  #   handler.on_tool_use { |tool| puts "Using: #{tool.display_label}" }
+  #   handler.on_result { |result| puts "Cost: $#{result.total_cost_usd}" }
+  #
+  #   client.receive_response.each { |msg| handler.handle(msg) }
+  #
+  # @example Via Client
+  #   client.on_text { |text| print text }
+  #   client.on_tool_use { |tool| puts tool.display_label }
+  #   turn = client.send_and_receive("Fix the bug")
+  #
+  # @example Chaining
+  #   handler = ClaudeAgent::EventHandler.new
+  #     .on_text { |text| print text }
+  #     .on_result { |r| puts "\nDone!" }
+  #
+  class EventHandler
+    # Events:
+    #   :message      — every message (catch-all)
+    #   :text         — AssistantMessage text content
+    #   :thinking     — AssistantMessage thinking content
+    #   :tool_use     — ToolUseBlock or ServerToolUseBlock
+    #   :tool_result  — ToolResultBlock or ServerToolResultBlock, paired with original tool_use
+    #   :result       — ResultMessage (end of turn)
+
+    def initialize
+      @handlers = Hash.new { |h, k| h[k] = [] }
+      @pending_tool_uses = {}
+    end
+
+    # Register a handler for an event
+    #
+    # @param event [Symbol] Event name
+    # @yield Event-specific arguments
+    # @return [self]
+    def on(event, &block)
+      @handlers[event] << block
+      self
+    end
+
+    # @!method on_message(&block)
+    #   Register a handler for every message
+    #   @yield [message] Any message object
+    #   @return [self]
+
+    # @!method on_text(&block)
+    #   Register a handler for assistant text content
+    #   @yield [String] Text from the AssistantMessage
+    #   @return [self]
+
+    # @!method on_thinking(&block)
+    #   Register a handler for assistant thinking content
+    #   @yield [String] Thinking from the AssistantMessage
+    #   @return [self]
+
+    # @!method on_tool_use(&block)
+    #   Register a handler for tool use requests
+    #   @yield [ToolUseBlock, ServerToolUseBlock] The tool use block
+    #   @return [self]
+
+    # @!method on_tool_result(&block)
+    #   Register a handler for tool results, paired with the original request
+    #   @yield [ToolResultBlock, ToolUseBlock|nil] Result block and matched tool use
+    #   @return [self]
+
+    # @!method on_result(&block)
+    #   Register a handler for the final ResultMessage
+    #   @yield [ResultMessage] The result
+    #   @return [self]
+
+    %i[message text thinking tool_use tool_result result].each do |event|
+      define_method(:"on_#{event}") { |&block| on(event, &block) }
+    end
+
+    # Dispatch a message to registered handlers
+    #
+    # @param message [Message] Any SDK message
+    # @return [void]
+    def handle(message)
+      emit(:message, message)
+
+      case message
+      when AssistantMessage
+        handle_assistant(message)
+      when UserMessage, UserMessageReplay
+        handle_user(message)
+      when ResultMessage
+        emit(:result, message)
+      end
+    end
+
+    # Clear turn-level tracking state (pending tool uses)
+    #
+    # Called automatically between turns when used via Client.
+    # Call manually when reusing a standalone handler across turns.
+    #
+    # @return [void]
+    def reset!
+      @pending_tool_uses.clear
+    end
+
+    # Whether any handlers have been registered
+    # @return [Boolean]
+    def has_handlers?
+      @handlers.any? { |_, v| v.any? }
+    end
+
+    private
+
+    def handle_assistant(message)
+      text = message.text
+      emit(:text, text) unless text.empty?
+
+      thinking = message.thinking
+      emit(:thinking, thinking) unless thinking.empty?
+
+      message.content.each do |block|
+        case block
+        when ToolUseBlock, ServerToolUseBlock
+          @pending_tool_uses[block.id] = block
+          emit(:tool_use, block)
+        end
+      end
+    end
+
+    def handle_user(message)
+      return unless message.content.is_a?(Array)
+
+      message.content.each do |block|
+        case block
+        when ToolResultBlock, ServerToolResultBlock
+          tool_use = @pending_tool_uses.delete(block.tool_use_id)
+          emit(:tool_result, block, tool_use)
+        end
+      end
+    end
+
+    def emit(event, *args)
+      @handlers[event].each { |handler| handler.call(*args) }
+    end
+  end
+end

data/lib/claude_agent/hooks.rb

@@ -19,6 +19,8 @@ module ClaudeAgent
     TeammateIdle
     TaskCompleted
     ConfigChange
+    WorktreeCreate
+    WorktreeRemove
   ].freeze
 
   # Matcher configuration for hooks
@@ -64,6 +66,10 @@ module ClaudeAgent
 
   # Base class for hook input types (TypeScript SDK parity)
   #
+  # Subclasses are generated declaratively via {.define_input}, which creates
+  # a class with attr_readers, a keyword-argument initializer, and automatic
+  # hook_event_name/base field inheritance.
+  #
   class BaseHookInput
     attr_reader :hook_event_name, :session_id, :transcript_path, :cwd, :permission_mode
 
@@ -74,255 +80,130 @@ module ClaudeAgent
       @cwd = cwd
       @permission_mode = permission_mode
     end
-  end
-
-  # Input for PreToolUse hook
-  #
-  class PreToolUseInput < BaseHookInput
-    attr_reader :tool_name, :tool_input, :tool_use_id
-
-    def initialize(tool_name:, tool_input:, tool_use_id: nil, **kwargs)
-      super(hook_event_name: "PreToolUse", **kwargs)
-      @tool_name = tool_name
-      @tool_input = tool_input
-      @tool_use_id = tool_use_id
-    end
-  end
-
-  # Input for PostToolUse hook
-  #
-  class PostToolUseInput < BaseHookInput
-    attr_reader :tool_name, :tool_input, :tool_response, :tool_use_id
-
-    def initialize(tool_name:, tool_input:, tool_response:, tool_use_id: nil, **kwargs)
-      super(hook_event_name: "PostToolUse", **kwargs)
-      @tool_name = tool_name
-      @tool_input = tool_input
-      @tool_response = tool_response
-      @tool_use_id = tool_use_id
-    end
-  end
-
-  # Input for PostToolUseFailure hook (TypeScript SDK parity)
-  #
-  class PostToolUseFailureInput < BaseHookInput
-    attr_reader :tool_name, :tool_input, :tool_use_id, :error, :is_interrupt
-
-    def initialize(tool_name:, tool_input:, error:, tool_use_id: nil, is_interrupt: nil, **kwargs)
-      super(hook_event_name: "PostToolUseFailure", **kwargs)
-      @tool_name = tool_name
-      @tool_input = tool_input
-      @tool_use_id = tool_use_id
-      @error = error
-      @is_interrupt = is_interrupt
-    end
-  end
-
-  # Input for Notification hook (TypeScript SDK parity)
-  #
-  class NotificationInput < BaseHookInput
-    attr_reader :message, :title, :notification_type
-
-    def initialize(message:, title: nil, notification_type: nil, **kwargs)
-      super(hook_event_name: "Notification", **kwargs)
-      @message = message
-      @title = title
-      @notification_type = notification_type
-    end
-  end
-
-  # Input for UserPromptSubmit hook
-  #
-  class UserPromptSubmitInput < BaseHookInput
-    attr_reader :prompt
-
-    def initialize(prompt:, **kwargs)
-      super(hook_event_name: "UserPromptSubmit", **kwargs)
-      @prompt = prompt
-    end
-  end
-
-  # Input for SessionStart hook (TypeScript SDK parity)
-  #
-  class SessionStartInput < BaseHookInput
-    attr_reader :source, :agent_type, :model
-
-    # @param source [String] One of: "startup", "resume", "clear", "compact"
-    # @param agent_type [String, nil] Type of agent if running in subagent context
-    # @param model [String, nil] Model being used for this session
-    def initialize(source:, agent_type: nil, model: nil, **kwargs)
-      super(hook_event_name: "SessionStart", **kwargs)
-      @source = source
-      @agent_type = agent_type
-      @model = model
-    end
-  end
 
-  # Input for SessionEnd hook (TypeScript SDK parity)
-  #
-  class SessionEndInput < BaseHookInput
-    attr_reader :reason
-
-    def initialize(reason:, **kwargs)
-      super(hook_event_name: "SessionEnd", **kwargs)
-      @reason = reason
-    end
-  end
+    # Define a hook input subclass declaratively
+    #
+    # Generates a complete input class with attr_readers, a keyword-argument
+    # initializer, and automatic hook_event_name forwarding. The generated class
+    # is registered as ClaudeAgent::{event_name}Input.
+    #
+    # @param event_name [String] Hook event name (e.g., "PreToolUse")
+    # @param required [Array<Symbol>] Required keyword arguments
+    # @param optional [Hash<Symbol, Object>] Optional keyword arguments with defaults
+    # @param constants [Hash<Symbol, Object>] Constants to define on the class
+    # @param block [Proc] Optional block for additional instance methods
+    # @return [Class] The generated subclass
+    #
+    # @example Simple declaration
+    #   BaseHookInput.define_input "PreToolUse",
+    #     required: [:tool_name, :tool_input],
+    #     optional: { tool_use_id: nil }
+    #
+    # @example With custom behavior
+    #   BaseHookInput.define_input "Setup",
+    #     required: [:trigger] do
+    #       def init? = trigger == "init"
+    #       def maintenance? = trigger == "maintenance"
+    #     end
+    #
+    def self.define_input(event_name, required: [], optional: {}, constants: {}, &block)
+      klass = Class.new(self)
+      all_fields = required + optional.keys
+      klass.attr_reader(*all_fields)
+
+      # Build keyword argument signature
+      params = required.map { |f| "#{f}:" }
+      params += optional.map { |f, default| "#{f}: #{default.inspect}" }
+      params << "**kwargs"
+
+      # Build instance variable assignments
+      assignments = all_fields.map { |f| "@#{f} = #{f}" }.join("\n      ")
+
+      klass.class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def initialize(#{params.join(", ")})
+          super(hook_event_name: "#{event_name}", **kwargs)
+          #{assignments}
+        end
+      RUBY
 
-  # Input for Stop hook
-  #
-  class StopInput < BaseHookInput
-    attr_reader :stop_hook_active
+      constants.each { |name, value| klass.const_set(name, value) }
+      klass.class_eval(&block) if block
 
-    def initialize(stop_hook_active: false, **kwargs)
-      super(hook_event_name: "Stop", **kwargs)
-      @stop_hook_active = stop_hook_active
+      ClaudeAgent.const_set("#{event_name}Input", klass)
     end
   end
 
-  # Input for SubagentStart hook (TypeScript SDK parity)
+  # --- Hook Input Declarations ---
   #
-  class SubagentStartInput < BaseHookInput
-    attr_reader :agent_id, :agent_type
+  # Each declaration generates a complete input class with:
+  # - attr_readers for all fields
+  # - initialize with required/optional keyword arguments
+  # - Automatic hook_event_name and base field inheritance
 
-    def initialize(agent_id:, agent_type:, **kwargs)
-      super(hook_event_name: "SubagentStart", **kwargs)
-      @agent_id = agent_id
-      @agent_type = agent_type
-    end
-  end
+  BaseHookInput.define_input "PreToolUse",
+    required: [ :tool_name, :tool_input ],
+    optional: { tool_use_id: nil }
 
-  # Input for SubagentStop hook
-  #
-  class SubagentStopInput < BaseHookInput
-    attr_reader :stop_hook_active, :agent_id, :agent_transcript_path
+  BaseHookInput.define_input "PostToolUse",
+    required: [ :tool_name, :tool_input, :tool_response ],
+    optional: { tool_use_id: nil }
 
-    def initialize(stop_hook_active: false, agent_id: nil, agent_transcript_path: nil, **kwargs)
-      super(hook_event_name: "SubagentStop", **kwargs)
-      @stop_hook_active = stop_hook_active
-      @agent_id = agent_id
-      @agent_transcript_path = agent_transcript_path
-    end
-  end
+  BaseHookInput.define_input "PostToolUseFailure",
+    required: [ :tool_name, :tool_input, :error ],
+    optional: { tool_use_id: nil, is_interrupt: nil }
 
-  # Input for PreCompact hook
-  #
-  class PreCompactInput < BaseHookInput
-    attr_reader :trigger, :custom_instructions
+  BaseHookInput.define_input "Notification",
+    required: [ :message ],
+    optional: { title: nil, notification_type: nil }
 
-    # @param trigger [String] One of: "manual", "auto"
-    # @param custom_instructions [String, nil] Custom instructions for compaction
-    def initialize(trigger:, custom_instructions: nil, **kwargs)
-      super(hook_event_name: "PreCompact", **kwargs)
-      @trigger = trigger
-      @custom_instructions = custom_instructions
-    end
-  end
+  BaseHookInput.define_input "UserPromptSubmit",
+    required: [ :prompt ]
 
-  # Input for PermissionRequest hook (TypeScript SDK parity)
-  #
-  class PermissionRequestInput < BaseHookInput
-    attr_reader :tool_name, :tool_input, :permission_suggestions
+  BaseHookInput.define_input "SessionStart",
+    required: [ :source ],
+    optional: { agent_type: nil, model: nil }
 
-    def initialize(tool_name:, tool_input:, permission_suggestions: nil, **kwargs)
-      super(hook_event_name: "PermissionRequest", **kwargs)
-      @tool_name = tool_name
-      @tool_input = tool_input
-      @permission_suggestions = permission_suggestions
-    end
-  end
+  BaseHookInput.define_input "SessionEnd",
+    required: [ :reason ]
 
-  # Input for Setup hook (TypeScript SDK parity)
-  #
-  # Triggered during initial setup or maintenance operations.
-  #
-  # @example
-  #   input = SetupInput.new(trigger: "init", session_id: "abc-123")
-  #   input.trigger  # => "init"
-  #   input.init?    # => true
-  #
-  class SetupInput < BaseHookInput
-    attr_reader :trigger
+  BaseHookInput.define_input "Stop",
+    optional: { stop_hook_active: false }
 
-    # @param trigger [String] One of: "init", "maintenance"
-    def initialize(trigger:, **kwargs)
-      super(hook_event_name: "Setup", **kwargs)
-      @trigger = trigger
-    end
+  BaseHookInput.define_input "SubagentStart",
+    required: [ :agent_id, :agent_type ]
 
-    # Check if this is an init trigger
-    # @return [Boolean]
-    def init?
-      trigger == "init"
-    end
+  BaseHookInput.define_input "SubagentStop",
+    optional: { stop_hook_active: false, agent_id: nil, agent_transcript_path: nil }
 
-    # Check if this is a maintenance trigger
-    # @return [Boolean]
-    def maintenance?
-      trigger == "maintenance"
-    end
-  end
+  BaseHookInput.define_input "PreCompact",
+    required: [ :trigger ],
+    optional: { custom_instructions: nil }
 
-  # Input for TeammateIdle hook (TypeScript SDK v0.2.33 parity)
-  #
-  # Fired when a teammate becomes idle.
-  #
-  class TeammateIdleInput < BaseHookInput
-    attr_reader :teammate_name, :team_name
+  BaseHookInput.define_input "PermissionRequest",
+    required: [ :tool_name, :tool_input ],
+    optional: { permission_suggestions: nil }
 
-    # @param teammate_name [String] Name of the idle teammate
-    # @param team_name [String] Name of the team
-    def initialize(teammate_name:, team_name:, **kwargs)
-      super(hook_event_name: "TeammateIdle", **kwargs)
-      @teammate_name = teammate_name
-      @team_name = team_name
+  BaseHookInput.define_input "Setup",
+    required: [ :trigger ] do
+      def init? = trigger == "init"
+      def maintenance? = trigger == "maintenance"
     end
-  end
 
-  # Input for ConfigChange hook (TypeScript SDK v0.2.49 parity)
-  #
-  # Fired when a configuration file changes.
-  #
-  # @example
-  #   input = ConfigChangeInput.new(
-  #     source: "user_settings",
-  #     file_path: "~/.claude/settings.json",
-  #     session_id: "sess-123"
-  #   )
-  #
-  class ConfigChangeInput < BaseHookInput
-    attr_reader :source, :file_path
+  BaseHookInput.define_input "TeammateIdle",
+    required: [ :teammate_name, :team_name ]
 
-    SOURCES = %w[user_settings project_settings local_settings policy_settings skills].freeze
+  BaseHookInput.define_input "TaskCompleted",
+    required: [ :task_id, :task_subject ],
+    optional: { task_description: nil, teammate_name: nil, team_name: nil }
 
-    # @param source [String] One of SOURCES
-    # @param file_path [String, nil] Path to the changed file
-    def initialize(source:, file_path: nil, **kwargs)
-      super(hook_event_name: "ConfigChange", **kwargs)
-      @source = source
-      @file_path = file_path
-    end
-  end
+  BaseHookInput.define_input "ConfigChange",
+    required: [ :source ],
+    optional: { file_path: nil },
+    constants: { SOURCES: %w[user_settings project_settings local_settings policy_settings skills].freeze }
 
-  # Input for TaskCompleted hook (TypeScript SDK v0.2.33 parity)
-  #
-  # Fired when a task completes.
-  #
-  class TaskCompletedInput < BaseHookInput
-    attr_reader :task_id, :task_subject, :task_description, :teammate_name, :team_name
+  BaseHookInput.define_input "WorktreeCreate",
+    required: [ :name ]
 
-    # @param task_id [String] ID of the completed task
-    # @param task_subject [String] Subject of the completed task
-    # @param task_description [String, nil] Description of the completed task
-    # @param teammate_name [String, nil] Name of the teammate that completed the task
-    # @param team_name [String, nil] Name of the team
-    def initialize(task_id:, task_subject:, task_description: nil, teammate_name: nil, team_name: nil, **kwargs)
-      super(hook_event_name: "TaskCompleted", **kwargs)
-      @task_id = task_id
-      @task_subject = task_subject
-      @task_description = task_description
-      @teammate_name = teammate_name
-      @team_name = team_name
-    end
-  end
+  BaseHookInput.define_input "WorktreeRemove",
+    required: [ :worktree_path ]
 end