claude_agent 0.7.10 → 0.7.11

data/lib/claude_agent/event_handler.rb

@@ -3,7 +3,13 @@
 module ClaudeAgent
   # Dispatches typed events as messages flow through a conversation turn.
   #
-  # Register handlers for specific events instead of writing `case` statements
+  # Three event layers fire for every message:
+  #
+  # 1. **Catch-all** — +:message+ fires for every message
+  # 2. **Type-based** — +message.type+ fires (e.g. +:assistant+, +:stream_event+, +:status+)
+  # 3. **Decomposed** — convenience events for rich content types (+:text+, +:thinking+, etc.)
+  #
+  # Register handlers for specific events instead of writing +case+ statements
   # over raw message types. Use standalone or via {Client#on}.
   #
   # @example Standalone
@@ -14,6 +20,11 @@ module ClaudeAgent
   #
   #   client.receive_response.each { |msg| handler.handle(msg) }
   #
+  # @example Type-based events
+  #   handler.on_stream_event { |evt| handle_stream(evt) }
+  #   handler.on_tool_progress { |prog| update_spinner(prog) }
+  #   handler.on_status { |status| show_status(status) }
+  #
   # @example Via Client
   #   client.on_text { |text| print text }
   #   client.on_tool_use { |tool| puts tool.display_label }
@@ -25,13 +36,22 @@ module ClaudeAgent
   #     .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)
+    # Type-based events — one per message type, auto-dispatched from message.type
+    TYPE_EVENTS = %i[
+      user assistant system result stream_event compact_boundary
+      status tool_progress hook_response auth_status task_notification
+      hook_started hook_progress tool_use_summary task_started
+      task_progress rate_limit_event prompt_suggestion files_persisted
+    ].freeze
+
+    # Decomposed events — extracted content from rich message types
+    DECOMPOSED_EVENTS = %i[text thinking tool_use tool_result].freeze
+
+    # Meta events — catch-all
+    META_EVENTS = %i[message].freeze
+
+    # All known events
+    EVENTS = (META_EVENTS + TYPE_EVENTS + DECOMPOSED_EVENTS).freeze
 
     def initialize
       @handlers = Hash.new { |h, k| h[k] = [] }
@@ -40,7 +60,7 @@ module ClaudeAgent
 
     # Register a handler for an event
     #
-    # @param event [Symbol] Event name
+    # @param event [Symbol] Event name (any symbol, including future/unknown types)
     # @yield Event-specific arguments
     # @return [self]
     def on(event, &block)
@@ -49,53 +69,82 @@ module ClaudeAgent
     end
 
     # @!method on_message(&block)
-    #   Register a handler for every message
+    #   Register a handler for every message (catch-all)
     #   @yield [message] Any message object
     #   @return [self]
 
+    # @!method on_assistant(&block)
+    #   Register a handler for AssistantMessage
+    #   @yield [AssistantMessage] The assistant message
+    #   @return [self]
+
+    # @!method on_user(&block)
+    #   Register a handler for UserMessage
+    #   @yield [UserMessage] The user message
+    #   @return [self]
+
+    # @!method on_result(&block)
+    #   Register a handler for ResultMessage (end of turn)
+    #   @yield [ResultMessage] The result
+    #   @return [self]
+
+    # @!method on_stream_event(&block)
+    #   Register a handler for StreamEvent
+    #   @yield [StreamEvent] The stream event
+    #   @return [self]
+
+    # @!method on_status(&block)
+    #   Register a handler for StatusMessage
+    #   @yield [StatusMessage] The status message
+    #   @return [self]
+
+    # @!method on_tool_progress(&block)
+    #   Register a handler for ToolProgressMessage
+    #   @yield [ToolProgressMessage] The tool progress message
+    #   @return [self]
+
     # @!method on_text(&block)
-    #   Register a handler for assistant text content
+    #   Register a handler for assistant text content (decomposed)
     #   @yield [String] Text from the AssistantMessage
     #   @return [self]
 
     # @!method on_thinking(&block)
-    #   Register a handler for assistant thinking content
+    #   Register a handler for assistant thinking content (decomposed)
     #   @yield [String] Thinking from the AssistantMessage
     #   @return [self]
 
     # @!method on_tool_use(&block)
-    #   Register a handler for tool use requests
+    #   Register a handler for tool use requests (decomposed)
     #   @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
+    #   Register a handler for tool results, paired with the original request (decomposed)
     #   @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|
+    EVENTS.each do |event|
       define_method(:"on_#{event}") { |&block| on(event, &block) }
     end
 
     # Dispatch a message to registered handlers
     #
+    # Fires events in order:
+    # 1. +:message+ (catch-all)
+    # 2. +message.type+ (type-based, e.g. +:assistant+, +:stream_event+)
+    # 3. Decomposed events (+:text+, +:thinking+, +:tool_use+, +:tool_result+)
+    #
     # @param message [Message] Any SDK message
     # @return [void]
     def handle(message)
       emit(:message, message)
+      emit(message.type, message)
 
       case message
       when AssistantMessage
         handle_assistant(message)
       when UserMessage, UserMessageReplay
         handle_user(message)
-      when ResultMessage
-        emit(:result, message)
       end
     end
 

data/lib/claude_agent/hooks.rb

@@ -167,13 +167,13 @@ module ClaudeAgent
     required: [ :reason ]
 
   BaseHookInput.define_input "Stop",
-    optional: { stop_hook_active: false }
+    optional: { stop_hook_active: false, last_assistant_message: nil }
 
   BaseHookInput.define_input "SubagentStart",
     required: [ :agent_id, :agent_type ]
 
   BaseHookInput.define_input "SubagentStop",
-    optional: { stop_hook_active: false, agent_id: nil, agent_transcript_path: nil }
+    optional: { stop_hook_active: false, agent_id: nil, agent_transcript_path: nil, agent_type: nil, last_assistant_message: nil }
 
   BaseHookInput.define_input "PreCompact",
     required: [ :trigger ],

data/lib/claude_agent/live_tool_activity.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Mutable wrapper around a ToolUseBlock for real-time status tracking.
+  #
+  # Unlike {ToolActivity} (immutable, built after a turn completes),
+  # LiveToolActivity tracks status changes as they happen — running,
+  # done, or error — making it suitable for live UIs.
+  #
+  # @example
+  #   activity = LiveToolActivity.new(tool_use)
+  #   activity.running?  # => true
+  #   activity.elapsed   # => nil
+  #
+  #   activity.update_elapsed(2.5)
+  #   activity.elapsed   # => 2.5
+  #
+  #   activity.complete!(tool_result)
+  #   activity.done?     # => true
+  #   activity.elapsed   # => 2.5 (preserved from progress)
+  #
+  class LiveToolActivity
+    attr_reader :tool_use, :tool_result, :status, :started_at, :elapsed
+
+    # @param tool_use [ToolUseBlock, ServerToolUseBlock] The tool use block
+    def initialize(tool_use)
+      @tool_use = tool_use
+      @tool_result = nil
+      @status = :running
+      @started_at = Time.now
+      @elapsed = nil
+    end
+
+    # Tool use ID
+    # @return [String]
+    def id
+      tool_use.id
+    end
+
+    # Tool name
+    # @return [String]
+    def name
+      tool_use.name
+    end
+
+    # Tool input
+    # @return [Hash]
+    def input
+      tool_use.input
+    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
+
+    # Mark the tool as complete with its result.
+    #
+    # Transitions status to :done or :error based on the result.
+    # Calculates elapsed time from started_at if not already set by progress updates.
+    #
+    # @param result [ToolResultBlock, ServerToolResultBlock] The tool result
+    # @return [void]
+    def complete!(result)
+      @tool_result = result
+      @status = result.is_error ? :error : :done
+      @elapsed ||= Time.now - @started_at
+    end
+
+    # Update elapsed time from a ToolProgressMessage.
+    #
+    # @param seconds [Float] Elapsed time in seconds
+    # @return [void]
+    def update_elapsed(seconds)
+      @elapsed = seconds
+    end
+
+    # Whether the tool is currently running.
+    # @return [Boolean]
+    def running?
+      @status == :running
+    end
+
+    # Whether the tool completed successfully.
+    # @return [Boolean]
+    def done?
+      @status == :done
+    end
+
+    # Whether the tool completed with an error.
+    # @return [Boolean]
+    def error?
+      @status == :error
+    end
+
+    # Whether the tool execution is complete (done or error).
+    # @return [Boolean]
+    def complete?
+      @status == :done || @status == :error
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        id: id,
+        name: name,
+        status: @status,
+        elapsed: @elapsed,
+        started_at: @started_at
+      }
+    end
+
+    def inspect
+      parts = [ "#<#{self.class}" ]
+      parts << "id=#{id}"
+      parts << "name=#{name}"
+      parts << "status=#{@status}"
+      parts << "elapsed=#{@elapsed}s" if @elapsed
+      "#{parts.join(" ")}>"
+    end
+  end
+end

data/lib/claude_agent/message_parser.rb

@@ -254,7 +254,8 @@ module ClaudeAgent
       StatusMessage.new(
         uuid: raw[:uuid] || "",
         session_id: raw[:session_id] || "",
-        status: raw[:status]
+        status: raw[:status],
+        permission_mode: raw[:permission_mode]
       )
     end
 
@@ -265,7 +266,8 @@ module ClaudeAgent
         tool_use_id: raw[:tool_use_id] || "",
         tool_name: raw[:tool_name] || "",
         parent_tool_use_id: raw[:parent_tool_use_id],
-        elapsed_time_seconds: raw[:elapsed_time_seconds] || 0
+        elapsed_time_seconds: raw[:elapsed_time_seconds] || 0,
+        task_id: raw[:task_id]
       )
     end
 
@@ -295,13 +297,24 @@ module ClaudeAgent
     end
 
     def parse_task_notification_message(raw)
+      usage = raw[:usage]
+      parsed_usage = if usage
+        TaskUsage.new(
+          total_tokens: usage[:total_tokens] || 0,
+          tool_uses: usage[:tool_uses] || 0,
+          duration_ms: usage[:duration_ms] || 0
+        )
+      end
+
       TaskNotificationMessage.new(
         uuid: raw[:uuid] || "",
         session_id: raw[:session_id] || "",
         task_id: raw[:task_id] || "",
         status: raw[:status] || "unknown",
         output_file: raw[:output_file] || "",
-        summary: raw[:summary] || ""
+        summary: raw[:summary] || "",
+        tool_use_id: raw[:tool_use_id],
+        usage: parsed_usage
       )
     end
 

data/lib/claude_agent/messages.rb

@@ -288,7 +288,11 @@ module ClaudeAgent
   #     status: "compacting"
   #   )
   #
-  StatusMessage = Data.define(:uuid, :session_id, :status) do
+  StatusMessage = Data.define(:uuid, :session_id, :status, :permission_mode) do
+    def initialize(uuid:, session_id:, status:, permission_mode: nil)
+      super
+    end
+
     def type
       :status
     end
@@ -313,7 +317,8 @@ module ClaudeAgent
     :tool_use_id,
     :tool_name,
     :parent_tool_use_id,
-    :elapsed_time_seconds
+    :elapsed_time_seconds,
+    :task_id
   ) do
     def initialize(
       uuid:,
@@ -321,7 +326,8 @@ module ClaudeAgent
       tool_use_id:,
       tool_name:,
       elapsed_time_seconds:,
-      parent_tool_use_id: nil
+      parent_tool_use_id: nil,
+      task_id: nil
     )
       super
     end
@@ -469,7 +475,9 @@ module ClaudeAgent
     :task_id,
     :status,
     :output_file,
-    :summary
+    :summary,
+    :tool_use_id,
+    :usage
   ) do
     def initialize(
       uuid:,
@@ -477,7 +485,9 @@ module ClaudeAgent
       task_id:,
       status:,
       output_file:,
-      summary:
+      summary:,
+      tool_use_id: nil,
+      usage: nil
     )
       super
     end

data/lib/claude_agent/options.rb

@@ -39,9 +39,6 @@ module ClaudeAgent
       enable_file_checkpointing: false,
       persist_session: true,
       betas: [],
-      init: false,
-      init_only: false,
-      maintenance: false,
       prompt_suggestions: false,
       debug: false,
       debug_file: nil
@@ -60,12 +57,11 @@ module ClaudeAgent
       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
-      settings sandbox cwd add_dirs env user agent
+      sandbox cwd add_dirs env agent
       cli_path extra_args agents setting_sources plugins
       include_partial_messages output_format enable_file_checkpointing
       persist_session prompt_suggestions betas max_buffer_size stderr_callback
       abort_controller spawn_claude_code_process
-      init init_only maintenance
       debug debug_file
       logger
     ].freeze
@@ -93,10 +89,9 @@ module ClaudeAgent
         args.concat(conversation_args)
         args.concat(limits_args)
         args.concat(mcp_args)
-        args.concat(settings_args)
+        args.concat(sandbox_args)
         args.concat(environment_args)
         args.concat(output_args)
-        args.concat(setup_hook_args)
         args.concat(debug_args)
         args.concat(extra_cli_args)
       end
@@ -233,9 +228,8 @@ module ClaudeAgent
       end
     end
 
-    def settings_args
+    def sandbox_args
       [].tap do |args|
-        args.push("--settings", settings) if settings
         if sandbox
           args.push("--sandbox", JSON.generate(sandbox.to_h))
         end
@@ -244,7 +238,6 @@ module ClaudeAgent
 
     def environment_args
       [].tap do |args|
-        args.push("--user", user) if user
         args.push("--agent", agent) if agent
         add_dirs.each { |dir| args.push("--add-dir", dir.to_s) }
         args.push("--setting-sources", setting_sources.join(",")) if setting_sources&.any?
@@ -270,14 +263,6 @@ module ClaudeAgent
       end
     end
 
-    def setup_hook_args
-      [].tap do |args|
-        args.push("--init") if init
-        args.push("--init-only") if init_only
-        args.push("--maintenance") if maintenance
-      end
-    end
-
     def debug_args
       [].tap do |args|
         args.push("--debug") if debug
@@ -342,11 +327,6 @@ module ClaudeAgent
       if session_id && (continue_conversation || resume) && !fork_session
         raise ConfigurationError, "session_id cannot be used with continue or resume unless fork_session is also set"
       end
-
-      setup_options = [ init, init_only, maintenance ].count { |opt| opt }
-      if setup_options > 1
-        raise ConfigurationError, "Only one of init, init_only, or maintenance can be set at a time"
-      end
     end
   end
 end

data/lib/claude_agent/query.rb

@@ -2,48 +2,6 @@
 
 module ClaudeAgent
   class << self
-    # Run Setup hooks and exit
-    #
-    # This is a convenience method for running Setup hooks without starting
-    # a conversation. Useful for CI/CD pipelines or scripts that need to
-    # ensure setup is complete before proceeding.
-    #
-    # @param trigger [Symbol] The setup trigger (:init or :maintenance)
-    # @param options [Options, nil] Additional configuration options
-    # @return [Array<Message>] All messages received during setup
-    #
-    # @example Run init setup
-    #   messages = ClaudeAgent.run_setup
-    #   result = messages.last
-    #   puts "Setup completed" if result.success?
-    #
-    # @example Run init setup with custom options
-    #   options = ClaudeAgent::Options.new(cwd: "/my/project")
-    #   ClaudeAgent.run_setup(trigger: :init, options: options)
-    #
-    # @note The :maintenance trigger requires --maintenance flag which
-    #   continues into a conversation. For maintenance-only behavior,
-    #   use options with maintenance: true and handle accordingly.
-    #
-    def run_setup(trigger: :init, options: nil)
-      options ||= Options.new
-
-      case trigger
-      when :init
-        # Create new options with init_only set
-        setup_options = Options.new(**options_to_hash(options).merge(init_only: true))
-      when :maintenance
-        # Note: There's no --maintenance-only flag, so we use --maintenance
-        # which will continue into a conversation. The caller should handle this.
-        setup_options = Options.new(**options_to_hash(options).merge(maintenance: true))
-      else
-        raise ArgumentError, "Invalid trigger: #{trigger}. Must be :init or :maintenance"
-      end
-
-      # Run with an empty prompt - setup hooks run before the prompt is processed
-      query(prompt: "", options: setup_options).to_a
-    end
-
     # One-shot query to Claude Code CLI
     #
     # This is a simple, stateless interface for sending a single prompt
@@ -151,17 +109,5 @@ module ClaudeAgent
       events&.reset!
       turn
     end
-
-    private
-
-    # Convert an Options object to a hash for merging
-    # @param options [Options] The options object
-    # @return [Hash] Hash of option values
-    def options_to_hash(options)
-      Options::ATTRIBUTES.each_with_object({}) do |attr, hash|
-        value = options.send(attr)
-        hash[attr] = value unless value.nil?
-      end
-    end
   end
 end