claude_agent 0.7.8 → 0.7.10

data/sig/claude_agent.rbs

@@ -30,6 +30,20 @@ module ClaudeAgent
     ?transport: Transport::Base?
   ) -> Enumerator[message, void]
 
+  # One-shot query returning a TurnResult
+  def self.query_turn: (
+    prompt: String,
+    ?options: Options?,
+    ?transport: Transport::Base?,
+    ?events: EventHandler?
+  ) -> TurnResult
+                     | (
+    prompt: String,
+    ?options: Options?,
+    ?transport: Transport::Base?,
+    ?events: EventHandler?
+  ) { (message) -> void } -> TurnResult
+
   # Error classes
   class Error < StandardError
   end
@@ -187,6 +201,31 @@ module ClaudeAgent
     def initialize: (can_rewind: bool, ?error: String?, ?files_changed: Array[String]?, ?insertions: Integer?, ?deletions: Integer?) -> void
   end
 
+  # Session metadata returned by list_sessions (TypeScript SDK parity: SDKSessionInfo)
+  class SessionInfo
+    attr_reader session_id: String
+    attr_reader summary: String
+    attr_reader last_modified: Integer
+    attr_reader file_size: Integer
+    attr_reader custom_title: String?
+    attr_reader first_prompt: String?
+    attr_reader git_branch: String?
+    attr_reader cwd: String?
+
+    def initialize: (session_id: String, summary: String, last_modified: Integer, file_size: Integer, ?custom_title: String?, ?first_prompt: String?, ?git_branch: String?, ?cwd: String?) -> void
+  end
+
+  # Session transcript message returned by get_session_messages (TypeScript SDK v0.2.59 parity)
+  class SessionMessage
+    attr_reader type: String
+    attr_reader uuid: String
+    attr_reader session_id: String
+    attr_reader message: untyped
+    attr_reader parent_tool_use_id: nil
+
+    def initialize: (type: String, uuid: String, session_id: String, message: untyped, ?parent_tool_use_id: nil) -> void
+  end
+
   # Agent definition for custom subagents (TypeScript SDK parity)
   class AgentDefinition
     attr_reader description: String
@@ -292,6 +331,7 @@ module ClaudeAgent
     attr_accessor permission_prompt_tool_name: String?
     attr_accessor can_use_tool: (^(String, Hash[String, untyped], untyped) -> permission_result)?
     attr_accessor allow_dangerously_skip_permissions: bool
+    attr_accessor permission_queue: bool?
 
     # Conversation flow
     attr_accessor continue_conversation: bool
@@ -398,6 +438,9 @@ module ClaudeAgent
     def initialize: (id: String, name: String, input: Hash[String, untyped]) -> void
     def type: () -> :tool_use
     def to_h: () -> Hash[Symbol, untyped]
+    def file_path: () -> String?
+    def display_label: () -> String
+    def summary: (?max: Integer) -> String
   end
 
   class ToolResultBlock
@@ -419,6 +462,9 @@ module ClaudeAgent
     def initialize: (id: String, name: String, input: Hash[String, untyped], server_name: String) -> void
     def type: () -> :server_tool_use
     def to_h: () -> Hash[Symbol, untyped]
+    def file_path: () -> String?
+    def display_label: () -> String
+    def summary: (?max: Integer) -> String
   end
 
   class ServerToolResultBlock
@@ -444,12 +490,32 @@ module ClaudeAgent
     def to_h: () -> Hash[Symbol, untyped]
   end
 
-  type content_block = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | ServerToolUseBlock | ServerToolResultBlock | ImageContentBlock
+  class GenericBlock
+    attr_reader block_type: String?
+    attr_reader raw: Hash[Symbol, untyped]
+
+    def initialize: (block_type: String?, raw: Hash[Symbol, untyped]) -> void
+    def type: () -> Symbol
+    def to_h: () -> Hash[Symbol, untyped]
+    def []: (Symbol key) -> untyped
+  end
+
+  type content_block = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | ServerToolUseBlock | ServerToolResultBlock | ImageContentBlock | GenericBlock
 
   CONTENT_BLOCK_TYPES: Array[Class]
 
+  class GenericMessage
+    attr_reader message_type: String?
+    attr_reader raw: Hash[Symbol, untyped]
+
+    def initialize: (message_type: String?, raw: Hash[Symbol, untyped]) -> void
+    def type: () -> Symbol
+    def to_h: () -> Hash[Symbol, untyped]
+    def []: (Symbol key) -> untyped
+  end
+
   # Message types
-  type message = UserMessage | UserMessageReplay | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | CompactBoundaryMessage | StatusMessage | ToolProgressMessage | HookResponseMessage | AuthStatusMessage | TaskNotificationMessage | HookStartedMessage | HookProgressMessage | ToolUseSummaryMessage | FilesPersistedEvent | TaskStartedMessage | RateLimitEvent | PromptSuggestionMessage
+  type message = UserMessage | UserMessageReplay | AssistantMessage | SystemMessage | ResultMessage | StreamEvent | CompactBoundaryMessage | StatusMessage | ToolProgressMessage | HookResponseMessage | AuthStatusMessage | TaskNotificationMessage | HookStartedMessage | HookProgressMessage | ToolUseSummaryMessage | FilesPersistedEvent | TaskStartedMessage | TaskProgressMessage | RateLimitEvent | PromptSuggestionMessage | GenericMessage
 
   MESSAGE_TYPES: Array[Class]
 
@@ -699,6 +765,20 @@ module ClaudeAgent
     def type: () -> :task_started
   end
 
+  # Task progress message (TypeScript SDK v0.2.51 parity)
+  class TaskProgressMessage
+    attr_reader uuid: String
+    attr_reader session_id: String
+    attr_reader task_id: String
+    attr_reader tool_use_id: String?
+    attr_reader description: String
+    attr_reader usage: Hash[String, untyped]?
+    attr_reader last_tool_name: String?
+
+    def initialize: (uuid: String, session_id: String, task_id: String, description: String, ?usage: Hash[String, untyped]?, ?tool_use_id: String?, ?last_tool_name: String?) -> void
+    def type: () -> :task_progress
+  end
+
   # Rate limit event (TypeScript SDK v0.2.45 parity)
   class RateLimitEvent
     attr_reader rate_limit_info: Hash[String, untyped]
@@ -723,7 +803,10 @@ module ClaudeAgent
   # Message parser
   class MessageParser
     def initialize: (?logger: Logger?) -> void
-    def parse: (Hash[String, untyped] raw) -> message
+    def parse: (Hash[untyped, untyped] raw) -> message
+
+    def self.registry: () -> Hash[String, Symbol]
+    def self.register: (String key, Symbol method_name) -> void
   end
 
   # Hook types
@@ -752,6 +835,9 @@ module ClaudeAgent
     attr_reader permission_mode: String?
 
     def initialize: (hook_event_name: String, ?session_id: String?, ?transcript_path: String?, ?cwd: String?, ?permission_mode: String?, **untyped) -> void
+
+    def self.define_input: (String event_name, ?required: Array[Symbol], ?optional: Hash[Symbol, untyped], ?constants: Hash[Symbol, untyped]) -> Class
+                         | (String event_name, ?required: Array[Symbol], ?optional: Hash[Symbol, untyped], ?constants: Hash[Symbol, untyped]) { () -> void } -> Class
   end
 
   class PreToolUseInput < BaseHookInput
@@ -945,15 +1031,210 @@ module ClaudeAgent
     attr_reader agent_id: String?
     attr_reader signal: AbortSignal?
     attr_reader description: String?
+    attr_reader request: PermissionRequest?
+
+    def initialize: (?permission_suggestions: untyped, ?blocked_path: String?, ?decision_reason: String?, ?tool_use_id: String?, ?agent_id: String?, ?signal: AbortSignal?, ?description: String?, ?request: PermissionRequest?) -> void
+  end
+
+  # Deferred permission request resolved from any thread
+  class PermissionRequest
+    attr_reader tool_name: String
+    attr_reader input: Hash[Symbol, untyped]
+    attr_reader context: ToolPermissionContext?
+    attr_reader request_id: String
+    attr_reader created_at: Time
+
+    def initialize: (tool_name: String, input: Hash[Symbol, untyped], context: ToolPermissionContext?, request_id: String) -> void
+    def allow!: (?updated_input: Hash[Symbol, untyped]?, ?updated_permissions: Array[PermissionUpdate]?) -> void
+    def deny!: (?message: String, ?interrupt: bool) -> void
+    def defer!: () -> self
+    def deferred?: () -> bool
+    def resolved?: () -> bool
+    def pending?: () -> bool
+    def result: () -> permission_result?
+    def wait: (?timeout: Numeric?) -> permission_result
+    def inspect: () -> String
+  end
+
+  # Thread-safe queue of pending permission requests
+  class PermissionQueue
+    def initialize: () -> void
+    def poll: () -> PermissionRequest?
+    def pop: (?timeout: Numeric?) -> PermissionRequest?
+    def empty?: () -> bool
+    def size: () -> Integer
+    def push: (PermissionRequest request) -> void
+    def drain!: (?reason: String) -> Array[PermissionRequest]
+  end
+
+  # Cumulative usage tracking across conversation turns
+  class CumulativeUsage
+    attr_reader input_tokens: Integer
+    attr_reader output_tokens: Integer
+    attr_reader cache_read_input_tokens: Integer
+    attr_reader cache_creation_input_tokens: Integer
+    attr_reader total_cost_usd: Float
+    attr_reader num_turns: Integer
+    attr_reader duration_ms: Integer
+    attr_reader duration_api_ms: Integer
+
+    def initialize: () -> void
+    def track: (untyped message) -> void
+    def reset!: () -> void
+    def to_h: () -> Hash[Symbol, Integer | Float]
+  end
+
+  # Represents a complete agent turn
+  class TurnResult
+    attr_reader messages: Array[message]
+
+    def initialize: () -> void
+    def <<: (message) -> self
+    def result: () -> ResultMessage?
+    def complete?: () -> bool
+
+    # Text & thinking
+    def text: () -> String
+    def thinking: () -> String
+
+    # Tool use
+    def tool_uses: () -> Array[ToolUseBlock | ServerToolUseBlock]
+    def tool_results: () -> Array[ToolResultBlock | ServerToolResultBlock]
+    def tool_executions: () -> Array[Hash[Symbol, ToolUseBlock | ServerToolUseBlock | ToolResultBlock | ServerToolResultBlock | nil]]
+
+    # Result accessors
+    def usage: () -> Hash[Symbol, Integer]?
+    def cost: () -> Float?
+    def duration_ms: () -> Integer?
+    def duration_api_ms: () -> Integer?
+    def session_id: () -> String?
+    def num_turns: () -> Integer?
+    def stop_reason: () -> String?
+    def model: () -> String?
+    def model_usage: () -> Hash[String, untyped]?
+    def structured_output: () -> untyped
+    def permission_denials: () -> Array[SDKPermissionDenial]
+    def errors: () -> Array[String]
+
+    # Status
+    def success?: () -> bool
+    def error?: () -> bool
+    def subtype: () -> String?
+
+    # Filtered message access
+    def assistant_messages: () -> Array[AssistantMessage]
+    def user_messages: () -> Array[UserMessage | UserMessageReplay]
+    def stream_events: () -> Array[StreamEvent]
+    def content_blocks: () -> Array[content_block]
+
+    def inspect: () -> String
+  end
+
+  # Event handler for dispatching typed events from message streams
+  class EventHandler
+    def initialize: () -> void
+    def on: (Symbol event) { (*untyped) -> void } -> self
+    def on_message: () { (message) -> void } -> self
+    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
+  end
+
+  # A single tool execution in the conversation timeline
+  class ToolActivity
+    attr_reader tool_use: ToolUseBlock | ServerToolUseBlock
+    attr_reader tool_result: ToolResultBlock | ServerToolResultBlock | nil
+    attr_reader turn_index: Integer
+    attr_reader started_at: Time?
+    attr_reader completed_at: Time?
+
+    def initialize: (tool_use: ToolUseBlock | ServerToolUseBlock, ?tool_result: ToolResultBlock | ServerToolResultBlock | nil, turn_index: Integer, ?started_at: Time?, ?completed_at: Time?) -> void
+    def name: () -> String
+    def display_label: () -> String
+    def summary: (?max: Integer) -> String
+    def file_path: () -> String?
+    def id: () -> String
+    def error?: () -> bool
+    def complete?: () -> bool
+    def duration: () -> Float?
+  end
+
+  # High-level conversation interface managing the full lifecycle
+  class Conversation
+    CONVERSATION_KEYS: Array[Symbol]
+
+    attr_reader turns: Array[TurnResult]
+    attr_reader messages: Array[message]
+    attr_reader tool_activity: Array[ToolActivity]
+    attr_reader client: Client
+
+    def self.open: (**untyped) { (Conversation) -> void } -> void
+    def self.resume: (String session_id, **untyped) -> Conversation
+
+    def initialize: (**untyped) -> void
+    def say: (String | Array[content_block] prompt) -> TurnResult
+           | (String | Array[content_block] prompt) { (message) -> void } -> TurnResult
+    def total_cost: () -> Float
+    def session_id: () -> String?
+    def usage: () -> CumulativeUsage
+    def pending_permission: () -> PermissionRequest?
+    def pending_permissions?: () -> bool
+    def close: () -> void
+    def open?: () -> bool
+    def closed?: () -> bool
+    def inspect: () -> String
+  end
+
+  # Session discovery
+  def self.list_sessions: (?dir: String?, ?limit: Integer?) -> Array[SessionInfo]
+  def self.get_session_messages: (String session_id, ?dir: String?, ?limit: Integer?, ?offset: Integer?) -> Array[SessionMessage]
+
+  # Shared session path infrastructure
+  module SessionPaths
+    MAX_SLUG_LENGTH: Integer
+    UUID_PATTERN: Regexp
+
+    def self.config_dir: () -> String
+    def self.projects_dir: () -> String
+    def self.project_dir_for: (String path) -> String
+    def self.encode_project_dir: (String path) -> String
+    def self.java_string_hash: (String str) -> String
+    def self.find_project_dir: (String path) -> String?
+    def self.realpath: (String path) -> String
+    def self.git_worktrees: (String dir) -> Array[String]
+  end
 
-    def initialize: (?permission_suggestions: untyped, ?blocked_path: String?, ?decision_reason: String?, ?tool_use_id: String?, ?agent_id: String?, ?signal: AbortSignal?, ?description: String?) -> void
+  # ListSessions module
+  module ListSessions
+    BUFFER_SIZE: Integer
+
+    def self.call: (?dir: String?, ?limit: Integer?) -> Array[SessionInfo]
+  end
+
+  # GetSessionMessages module (TypeScript SDK v0.2.59 parity)
+  module GetSessionMessages
+    PARSEABLE_TYPES: Array[String]
+
+    def self.call: (String session_id, ?dir: String?, ?limit: Integer?, ?offset: Integer?) -> Array[SessionMessage]
   end
 
+  # Convenience methods
+  def self.conversation: (**untyped) -> Conversation
+  def self.resume_conversation: (String session_id, **untyped) -> Conversation
+
   # Client
   class Client
     attr_reader options: Options
     attr_reader transport: Transport::Base
     attr_reader server_info: Hash[String, untyped]?
+    attr_reader cumulative_usage: CumulativeUsage
+    attr_reader event_handler: EventHandler
+    attr_reader permission_queue: PermissionQueue
 
     def self.open: (?options: Options?, ?transport: Transport::Base?, ?prompt: String?) { (Client) -> void } -> void
 
@@ -963,10 +1244,21 @@ module ClaudeAgent
     def connected?: () -> bool
     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
+    def on_message: () { (message) -> void } -> self
+    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
                         | () -> Enumerator[message, void]
+    def receive_turn: () -> TurnResult
+                    | () { (message) -> void } -> TurnResult
+    def send_and_receive: (String | Array[content_block] content, ?session_id: String, ?uuid: String?) -> TurnResult
+                        | (String | Array[content_block] content, ?session_id: String, ?uuid: String?) { (message) -> void } -> TurnResult
     def stream_input: (Enumerable[String | Hash[String, untyped] | UserMessage] stream, ?session_id: String) -> void
                     | (Enumerable[String | Hash[String, untyped] | UserMessage] stream, ?session_id: String) { (message) -> void } -> void
     def interrupt: () -> void
@@ -978,6 +1270,8 @@ module ClaudeAgent
     def set_mcp_servers: (Hash[String, untyped] servers) -> McpSetServersResult
     def mcp_reconnect: (String server_name) -> Hash[String, untyped]
     def mcp_toggle: (String server_name, enabled: bool) -> Hash[String, untyped]
+    def mcp_authenticate: (String server_name) -> Hash[String, untyped]
+    def mcp_clear_auth: (String server_name) -> Hash[String, untyped]
     def stop_task: (String task_id) -> Hash[String, untyped]
     def apply_flag_settings: (Hash[String, untyped] settings) -> Hash[String, untyped]
     def supported_commands: () -> Array[SlashCommand]
@@ -985,6 +1279,8 @@ module ClaudeAgent
     def mcp_server_status: () -> Array[McpServerStatus]
     def account_info: () -> AccountInfo
     def initialization_result: () -> InitializationResult
+    def pending_permission: () -> PermissionRequest?
+    def pending_permissions?: () -> bool
   end
 
   # Control protocol
@@ -996,6 +1292,7 @@ module ClaudeAgent
     attr_reader transport: Transport::Base
     attr_reader options: Options
     attr_reader server_info: Hash[String, untyped]?
+    attr_accessor permission_queue: PermissionQueue?
 
     def initialize: (transport: Transport::Base, ?options: Options?) -> void
     def start: (?streaming: bool, ?prompt: String?) -> Hash[String, untyped]?
@@ -1016,6 +1313,8 @@ module ClaudeAgent
     def set_mcp_servers: (Hash[String, untyped] servers) -> McpSetServersResult
     def mcp_reconnect: (String server_name) -> Hash[String, untyped]
     def mcp_toggle: (String server_name, enabled: bool) -> Hash[String, untyped]
+    def mcp_authenticate: (String server_name) -> Hash[String, untyped]
+    def mcp_clear_auth: (String server_name) -> Hash[String, untyped]
     def stop_task: (String task_id) -> Hash[String, untyped]
     def apply_flag_settings: (Hash[String, untyped] settings) -> Hash[String, untyped]
     def supported_commands: () -> Array[SlashCommand]
@@ -1156,7 +1455,7 @@ module ClaudeAgent
   end
 
   # V2 Session interface for multi-turn conversations
-  class Session
+  class V2Session
     attr_reader session_id: String?
     attr_reader options: SessionOptions
 
@@ -1169,7 +1468,37 @@ module ClaudeAgent
   end
 
   # V2 API module-level methods
-  def self.unstable_v2_create_session: (Hash[Symbol, untyped] | SessionOptions options) -> Session
-  def self.unstable_v2_resume_session: (String session_id, Hash[Symbol, untyped] | SessionOptions options) -> Session
+  def self.unstable_v2_create_session: (Hash[Symbol, untyped] | SessionOptions options) -> V2Session
+  def self.unstable_v2_resume_session: (String session_id, Hash[Symbol, untyped] | SessionOptions options) -> V2Session
   def self.unstable_v2_prompt: (String message, Hash[Symbol, untyped] | SessionOptions options) -> ResultMessage
+
+  # Chainable, lazy query object for session transcript messages
+  class SessionMessageRelation
+    include Enumerable[SessionMessage]
+
+    def initialize: (String session_id, ?dir: String?, ?limit: Integer?, ?offset: Integer?) -> void
+    def where: (?limit: Integer?, ?offset: Integer?) -> SessionMessageRelation
+    def each: () { (SessionMessage) -> void } -> void
+            | () -> Enumerator[SessionMessage, void]
+    def to_a: () -> Array[SessionMessage]
+  end
+
+  # Historical session finder with Rails-like API
+  class Session
+    attr_reader session_id: String
+    attr_reader summary: String
+    attr_reader last_modified: Integer
+    attr_reader file_size: Integer
+    attr_reader custom_title: String?
+    attr_reader first_prompt: String?
+    attr_reader git_branch: String?
+    attr_reader cwd: String?
+
+    def initialize: (SessionInfo session_info) -> void
+    def messages: () -> SessionMessageRelation
+
+    def self.find: (String session_id, ?dir: String?) -> Session?
+    def self.all: () -> Array[Session]
+    def self.where: (?dir: String?, ?limit: Integer?) -> Array[Session]
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_agent
 version: !ruby/object:Gem::Version
-  version: 0.7.8
+  version: 0.7.10
 platform: ruby
 authors:
 - Thomas Carr
@@ -55,21 +55,32 @@ files:
 - lib/claude_agent/client.rb
 - lib/claude_agent/content_blocks.rb
 - lib/claude_agent/control_protocol.rb
+- lib/claude_agent/conversation.rb
+- lib/claude_agent/cumulative_usage.rb
 - lib/claude_agent/errors.rb
+- lib/claude_agent/event_handler.rb
+- lib/claude_agent/get_session_messages.rb
 - lib/claude_agent/hooks.rb
+- lib/claude_agent/list_sessions.rb
 - lib/claude_agent/logging.rb
 - lib/claude_agent/mcp/server.rb
 - lib/claude_agent/mcp/tool.rb
 - lib/claude_agent/message_parser.rb
 - lib/claude_agent/messages.rb
 - lib/claude_agent/options.rb
+- lib/claude_agent/permission_queue.rb
+- lib/claude_agent/permission_request.rb
 - lib/claude_agent/permissions.rb
 - lib/claude_agent/query.rb
 - lib/claude_agent/sandbox_settings.rb
 - lib/claude_agent/session.rb
+- lib/claude_agent/session_message_relation.rb
+- lib/claude_agent/session_paths.rb
 - lib/claude_agent/spawn.rb
+- lib/claude_agent/tool_activity.rb
 - lib/claude_agent/transport/base.rb
 - lib/claude_agent/transport/subprocess.rb
+- lib/claude_agent/turn_result.rb
 - lib/claude_agent/types.rb
 - lib/claude_agent/version.rb
 - sig/claude_agent.rbs