claude_agent 0.7.12 → 0.7.13

data/lib/claude_agent/event_handler.rb

@@ -42,6 +42,7 @@ module ClaudeAgent
       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
+      elicitation_complete local_command_output
     ].freeze
 
     # Decomposed events — extracted content from rich message types

data/lib/claude_agent/get_session_info.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Looks up a single session by ID and returns its metadata.
+  #
+  # Reuses ListSessions parsing logic to read session files from disk.
+  # Searches project directories for the session file by UUID.
+  #
+  # @example
+  #   info = ClaudeAgent.get_session_info("abc-123-...")
+  #   puts info.summary if info
+  #
+  module GetSessionInfo
+    module_function
+
+    # Look up a single session by ID.
+    #
+    # @param session_id [String] UUID of the session to look up
+    # @param dir [String, nil] Project directory to scope the search.
+    #   When nil, searches all projects.
+    # @return [SessionInfo, nil] Session metadata or nil if not found
+    def call(session_id, dir: nil)
+      unless SessionPaths::UUID_PATTERN.match?(session_id.to_s)
+        raise ArgumentError, "Invalid session_id: #{session_id}. Must be a valid UUID."
+      end
+
+      filename = "#{session_id}.jsonl"
+
+      if dir
+        find_in_directory(session_id, filename, dir)
+      else
+        find_in_all_projects(session_id, filename)
+      end
+    end
+
+    # --- Private Helpers ---
+
+    def find_in_directory(session_id, filename, dir)
+      resolved = SessionPaths.realpath(dir)
+      project_dir = SessionPaths.find_project_dir(resolved)
+
+      if project_dir
+        result = try_parse(project_dir, filename, session_id)
+        return result if result
+      end
+
+      # Check worktrees
+      worktrees = SessionPaths.git_worktrees(resolved)
+      worktrees.each do |wt|
+        wt_project_dir = SessionPaths.find_project_dir(wt)
+        next unless wt_project_dir
+
+        result = try_parse(wt_project_dir, filename, session_id)
+        return result if result
+      end
+
+      nil
+    end
+    private_class_method :find_in_directory
+
+    def find_in_all_projects(session_id, filename)
+      base = SessionPaths.projects_dir
+      return nil unless File.directory?(base)
+
+      Dir.entries(base).each do |entry|
+        next if entry.start_with?(".")
+        dir_path = File.join(base, entry)
+        next unless File.directory?(dir_path)
+
+        result = try_parse(dir_path, filename, session_id)
+        return result if result
+      end
+
+      nil
+    end
+    private_class_method :find_in_all_projects
+
+    def try_parse(project_dir, filename, session_id)
+      path = File.join(project_dir, filename)
+      return nil unless File.exist?(path)
+
+      ListSessions.send(:parse_session_file, path, session_id)
+    end
+    private_class_method :try_parse
+  end
+end

data/lib/claude_agent/hooks.rb

@@ -18,9 +18,12 @@ module ClaudeAgent
     Setup
     TeammateIdle
     TaskCompleted
+    Elicitation
+    ElicitationResult
     ConfigChange
     WorktreeCreate
     WorktreeRemove
+    InstructionsLoaded
   ].freeze
 
   # Matcher configuration for hooks
@@ -71,14 +74,16 @@ module ClaudeAgent
   # hook_event_name/base field inheritance.
   #
   class BaseHookInput
-    attr_reader :hook_event_name, :session_id, :transcript_path, :cwd, :permission_mode
+    attr_reader :hook_event_name, :session_id, :transcript_path, :cwd, :permission_mode, :agent_id, :agent_type
 
-    def initialize(hook_event_name:, session_id: nil, transcript_path: nil, cwd: nil, permission_mode: nil, **kwargs)
+    def initialize(hook_event_name:, session_id: nil, transcript_path: nil, cwd: nil, permission_mode: nil, agent_id: nil, agent_type: nil, **kwargs)
       @hook_event_name = hook_event_name
       @session_id = session_id
       @transcript_path = transcript_path
       @cwd = cwd
       @permission_mode = permission_mode
+      @agent_id = agent_id
+      @agent_type = agent_type
     end
 
     # Define a hook input subclass declaratively
@@ -196,6 +201,14 @@ module ClaudeAgent
     required: [ :task_id, :task_subject ],
     optional: { task_description: nil, teammate_name: nil, team_name: nil }
 
+  BaseHookInput.define_input "Elicitation",
+    required: [ :mcp_server_name, :message ],
+    optional: { mode: nil, url: nil, elicitation_id: nil, requested_schema: nil }
+
+  BaseHookInput.define_input "ElicitationResult",
+    required: [ :mcp_server_name, :action ],
+    optional: { elicitation_id: nil, mode: nil, content: nil }
+
   BaseHookInput.define_input "ConfigChange",
     required: [ :source ],
     optional: { file_path: nil },
@@ -206,4 +219,12 @@ module ClaudeAgent
 
   BaseHookInput.define_input "WorktreeRemove",
     required: [ :worktree_path ]
+
+  BaseHookInput.define_input "InstructionsLoaded",
+    required: [ :file_path, :memory_type, :load_reason ],
+    optional: { globs: nil, trigger_file_path: nil, parent_file_path: nil },
+    constants: {
+      MEMORY_TYPES: %w[User Project Local Managed].freeze,
+      LOAD_REASONS: %w[session_start nested_traversal path_glob_match include].freeze
+    }
 end

data/lib/claude_agent/list_sessions.rb

@@ -31,12 +31,14 @@ module ClaudeAgent
       # @param dir [String, nil] Directory to scope sessions to (with worktree support).
       #   When nil, returns sessions from all projects.
       # @param limit [Integer, nil] Maximum number of sessions to return.
+      # @param include_worktrees [Boolean] When dir is in a git repo, include sessions
+      #   from all git worktree paths. Defaults to true.
       # @return [Array<SessionInfo>] Sessions sorted by last_modified descending.
-      def call(dir: nil, limit: nil)
+      def call(dir: nil, limit: nil, offset: nil, include_worktrees: true)
         if dir
-          list_for_directory(dir, limit)
+          list_for_directory(dir, limit, offset: offset, include_worktrees: include_worktrees)
         else
-          list_all(limit)
+          list_all(limit, offset: offset)
         end
       end
 
@@ -243,6 +245,9 @@ module ClaudeAgent
         first_prompt = extract_first_prompt(head)
         git_branch = extract_last(tail, "gitBranch") || extract_first(head, "gitBranch")
         cwd = extract_first(head, "cwd")
+        tag = extract_last(tail, "tag")
+        timestamp_str = extract_first(head, "timestamp")
+        created_at = timestamp_str&.to_i
 
         # Build summary: customTitle > last summary > firstPrompt > "(session)"
         summary_from_file = extract_last(tail, "summary")
@@ -256,7 +261,9 @@ module ClaudeAgent
           custom_title: custom_title,
           first_prompt: first_prompt,
           git_branch: git_branch,
-          cwd: cwd
+          cwd: cwd,
+          tag: tag,
+          created_at: created_at
         )
       end
 
@@ -288,21 +295,22 @@ module ClaudeAgent
 
       # --- Listing Modes ---
 
-      # List sessions for a specific directory, including worktree siblings.
+      # List sessions for a specific directory, optionally including worktree siblings.
       # Matches TypeScript's bM function.
       #
       # @param dir [String]
       # @param limit [Integer, nil]
+      # @param include_worktrees [Boolean] Whether to include worktree sessions
       # @return [Array<SessionInfo>]
-      def list_for_directory(dir, limit)
+      def list_for_directory(dir, limit, offset: nil, include_worktrees: true)
         resolved = SessionPaths.realpath(dir)
-        worktrees = SessionPaths.git_worktrees(resolved)
+        worktrees = include_worktrees ? SessionPaths.git_worktrees(resolved) : []
 
-        # Simple case: not in a worktree (or single worktree)
+        # Simple case: not in a worktree (or single worktree) or worktrees disabled
         if worktrees.length <= 1
           project_dir = SessionPaths.find_project_dir(resolved)
           return [] unless project_dir
-          return sort_and_limit(scan_project_dir(project_dir), limit)
+          return sort_and_limit(scan_project_dir(project_dir), limit, offset: offset)
         end
 
         # Complex case: multiple worktrees - scan all related project directories
@@ -341,7 +349,7 @@ module ClaudeAgent
           end
         end
 
-        sort_and_limit(deduplicate(all_sessions), limit)
+        sort_and_limit(deduplicate(all_sessions), limit, offset: offset)
       end
 
       # List sessions from all project directories.
@@ -349,7 +357,7 @@ module ClaudeAgent
       #
       # @param limit [Integer, nil]
       # @return [Array<SessionInfo>]
-      def list_all(limit)
+      def list_all(limit, offset: nil)
         base = SessionPaths.projects_dir
         return [] unless File.directory?(base)
 
@@ -362,7 +370,7 @@ module ClaudeAgent
           all_sessions.concat(scan_project_dir(dir_path))
         end
 
-        sort_and_limit(deduplicate(all_sessions), limit)
+        sort_and_limit(deduplicate(all_sessions), limit, offset: offset)
       end
 
       # --- Helpers ---
@@ -389,8 +397,9 @@ module ClaudeAgent
       # @param sessions [Array<SessionInfo>]
       # @param limit [Integer, nil]
       # @return [Array<SessionInfo>]
-      def sort_and_limit(sessions, limit)
+      def sort_and_limit(sessions, limit, offset: nil)
         sorted = sessions.sort_by { |s| -s.last_modified }
+        sorted = sorted.drop(offset) if offset
         limit ? sorted.first(limit) : sorted
       end
     end

data/lib/claude_agent/message_parser.rb

@@ -83,7 +83,9 @@ module ClaudeAgent
     register "system:hook_progress",     :parse_hook_progress_message
     register "system:files_persisted",   :parse_files_persisted_event
     register "system:task_started",      :parse_task_started_message
-    register "system:task_progress",     :parse_task_progress_message
+    register "system:task_progress",            :parse_task_progress_message
+    register "system:elicitation_complete",    :parse_elicitation_complete_message
+    register "system:local_command_output",    :parse_local_command_output_message
 
     private
 
@@ -167,7 +169,8 @@ module ClaudeAgent
         errors: raw[:errors],
         permission_denials: permission_denials,
         model_usage: raw[:model_usage],
-        stop_reason: raw[:stop_reason]
+        stop_reason: raw[:stop_reason],
+        fast_mode_state: raw[:fast_mode_state]
       )
     end
 
@@ -368,7 +371,8 @@ module ClaudeAgent
         task_id: raw[:task_id] || "",
         tool_use_id: raw[:tool_use_id],
         description: raw[:description],
-        task_type: raw[:task_type]
+        task_type: raw[:task_type],
+        prompt: raw[:prompt]
       )
     end
 
@@ -380,7 +384,25 @@ module ClaudeAgent
         tool_use_id: raw[:tool_use_id],
         description: raw[:description] || "",
         usage: raw[:usage],
-        last_tool_name: raw[:last_tool_name]
+        last_tool_name: raw[:last_tool_name],
+        summary: raw[:summary]
+      )
+    end
+
+    def parse_elicitation_complete_message(raw)
+      ElicitationCompleteMessage.new(
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        mcp_server_name: raw[:mcp_server_name] || "",
+        elicitation_id: raw[:elicitation_id] || ""
+      )
+    end
+
+    def parse_local_command_output_message(raw)
+      LocalCommandOutputMessage.new(
+        uuid: raw[:uuid] || "",
+        session_id: raw[:session_id] || "",
+        content: raw[:content] || ""
       )
     end
 

data/lib/claude_agent/messages/conversation.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # User message sent to Claude
+  #
+  # @example
+  #   msg = UserMessage.new(content: "Hello!", uuid: "abc-123", session_id: "session-abc")
+  #
+  UserMessage = Data.define(:content, :uuid, :session_id, :parent_tool_use_id) do
+    def initialize(content:, uuid: nil, session_id: nil, parent_tool_use_id: nil)
+      super
+    end
+
+    def type
+      :user
+    end
+
+    # Get text content if content is a string
+    # @return [String, nil]
+    def text
+      content.is_a?(String) ? content : nil
+    end
+
+    # Check if this is a replayed message
+    # @return [Boolean]
+    def replay?
+      false
+    end
+  end
+
+  # User message replay (TypeScript SDK parity)
+  #
+  # Sent when resuming a session with existing conversation history.
+  # These messages represent replayed user messages from a previous session.
+  #
+  # @example
+  #   msg = UserMessageReplay.new(
+  #     content: "Hello!",
+  #     uuid: "abc-123",
+  #     session_id: "session-abc",
+  #     is_replay: true
+  #   )
+  #   msg.replay?  # => true
+  #
+  UserMessageReplay = Data.define(
+    :content,
+    :uuid,
+    :session_id,
+    :parent_tool_use_id,
+    :is_replay,
+    :is_synthetic,
+    :tool_use_result
+  ) do
+    def initialize(
+      content:,
+      uuid: nil,
+      session_id: nil,
+      parent_tool_use_id: nil,
+      is_replay: true,
+      is_synthetic: nil,
+      tool_use_result: nil
+    )
+      super
+    end
+
+    def type
+      :user
+    end
+
+    # Get text content if content is a string
+    # @return [String, nil]
+    def text
+      content.is_a?(String) ? content : nil
+    end
+
+    # Check if this is a replayed message
+    # @return [Boolean]
+    def replay?
+      is_replay == true
+    end
+
+    # Check if this is a synthetic message (system-generated)
+    # @return [Boolean]
+    def synthetic?
+      is_synthetic == true
+    end
+  end
+
+  # Assistant message from Claude
+  #
+  # @example
+  #   msg = AssistantMessage.new(
+  #     content: [TextBlock.new(text: "Hello!")],
+  #     model: "claude-sonnet-4-5-20250514",
+  #     uuid: "msg-123",
+  #     session_id: "session-abc"
+  #   )
+  #
+  AssistantMessage = Data.define(:content, :model, :uuid, :session_id, :error, :parent_tool_use_id) do
+    def initialize(content:, model:, uuid: nil, session_id: nil, error: nil, parent_tool_use_id: nil)
+      super
+    end
+
+    def type
+      :assistant
+    end
+
+    # Get all text content concatenated
+    # @return [String]
+    def text
+      content
+        .select { |block| block.is_a?(TextBlock) }
+        .map(&:text)
+        .join
+    end
+
+    # Get all thinking content concatenated
+    # @return [String]
+    def thinking
+      content
+        .select { |block| block.is_a?(ThinkingBlock) }
+        .map(&:thinking)
+        .join
+    end
+
+    # Get all tool use blocks
+    # @return [Array<ToolUseBlock>]
+    def tool_uses
+      content.select { |block| block.is_a?(ToolUseBlock) }
+    end
+
+    # Check if assistant wants to use a tool
+    # @return [Boolean]
+    def has_tool_use?
+      content.any? { |block| block.is_a?(ToolUseBlock) }
+    end
+  end
+end

data/lib/claude_agent/messages/generic.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # 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
+end

data/lib/claude_agent/messages/hook_lifecycle.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module ClaudeAgent
+  # Hook started message (TypeScript SDK parity)
+  #
+  # Sent when a hook execution starts.
+  #
+  # @example
+  #   msg = HookStartedMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     hook_id: "hook-456",
+  #     hook_name: "my-hook",
+  #     hook_event: "PreToolUse"
+  #   )
+  #
+  HookStartedMessage = Data.define(
+    :uuid,
+    :session_id,
+    :hook_id,
+    :hook_name,
+    :hook_event
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      hook_id:,
+      hook_name:,
+      hook_event:
+    )
+      super
+    end
+
+    def type
+      :hook_started
+    end
+  end
+
+  # Hook progress message (TypeScript SDK parity)
+  #
+  # Reports progress during hook execution.
+  #
+  # @example
+  #   msg = HookProgressMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     hook_id: "hook-456",
+  #     hook_name: "my-hook",
+  #     hook_event: "PreToolUse",
+  #     stdout: "Hook output so far...",
+  #     stderr: "",
+  #     output: "Combined output"
+  #   )
+  #
+  HookProgressMessage = Data.define(
+    :uuid,
+    :session_id,
+    :hook_id,
+    :hook_name,
+    :hook_event,
+    :stdout,
+    :stderr,
+    :output
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      hook_id:,
+      hook_name:,
+      hook_event:,
+      stdout: "",
+      stderr: "",
+      output: ""
+    )
+      super
+    end
+
+    def type
+      :hook_progress
+    end
+  end
+
+  # Hook response message (TypeScript SDK parity)
+  #
+  # Contains output from hook executions.
+  #
+  # @example
+  #   msg = HookResponseMessage.new(
+  #     uuid: "msg-123",
+  #     session_id: "session-abc",
+  #     hook_id: "hook-456",
+  #     hook_name: "my-hook",
+  #     hook_event: "PreToolUse",
+  #     stdout: "Hook output",
+  #     stderr: "",
+  #     output: "Combined output",
+  #     exit_code: 0,
+  #     outcome: "success"
+  #   )
+  #   msg.success?    # => true
+  #   msg.error?      # => false
+  #   msg.cancelled?  # => false
+  #
+  # Outcome values:
+  # - "success" - Hook completed successfully
+  # - "error" - Hook encountered an error
+  # - "cancelled" - Hook was cancelled
+  #
+  HookResponseMessage = Data.define(
+    :uuid,
+    :session_id,
+    :hook_id,
+    :hook_name,
+    :hook_event,
+    :stdout,
+    :stderr,
+    :output,
+    :exit_code,
+    :outcome
+  ) do
+    def initialize(
+      uuid:,
+      session_id:,
+      hook_id: nil,
+      hook_name:,
+      hook_event:,
+      stdout: "",
+      stderr: "",
+      output: "",
+      exit_code: nil,
+      outcome: nil
+    )
+      super
+    end
+
+    def type
+      :hook_response
+    end
+
+    # Check if hook completed successfully
+    # @return [Boolean]
+    def success?
+      outcome == "success"
+    end
+
+    # Check if hook encountered an error
+    # @return [Boolean]
+    def error?
+      outcome == "error"
+    end
+
+    # Check if hook was cancelled
+    # @return [Boolean]
+    def cancelled?
+      outcome == "cancelled"
+    end
+  end
+end