claude_agent 0.7.9 → 0.7.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90d9094d4e4428fc7dfc1e452759403a92f2e4badf5d1ac5f2f90e950c511255
-  data.tar.gz: fd2a8407c794aa672a4b03a774a6573dac3682bc09b8fe666170b90f5bd9f79a
+  metadata.gz: 965fad355090a487a22e76e097ed84aa7426fe4db396a28e0165e6ceaa09b1e2
+  data.tar.gz: fe03eeffb6dfa608c5a40bc55d1b04b31f30bd0ec5d8a50322b2dc7bf127bdea
 SHA512:
-  metadata.gz: ce7d705ebe01a38ad1ac86a8caeaabd700831e200e73f134c9adef507b6f7b695effece63ae902849ee408714c3ae576930012dbbefe2b05da403d0de8549317
-  data.tar.gz: 7f06c5b0b5ed5ad798442672ad8ca969a0fdefc414a4c273e86911df0e171d24d5a378b9a88117bd3c60092a6affb5219d06cc58dd0107245643b571e2236440
+  metadata.gz: b7353c7235415c842e29ba73c315f10ba52d6731324d0e326ecfe56f321272246a6877f07fd2e451007b3ac9252c007f312da15650c77f8ef4c99d06a1e907d1
+  data.tar.gz: ece71bf88dddd47d40da3dd13e660c8e39eba12484daaf1fa0b87731ff130b8b6ddfcb215e352d2f34c587eb55998a9d1669bbe88363a2587e342190c5b80c0e

data/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.11] - 2026-02-27
+
+### Added
+- `LiveToolActivity` — mutable, real-time tool status tracker (`:running` → `:done`/`:error`) with elapsed time and delegation to `ToolUseBlock`
+- `ToolActivityTracker` — `Enumerable` collection that auto-wires to `EventHandler` or `Client` via `.attach`, with `on_start`/`on_complete`/`on_progress` callbacks, `on_change` catch-all, `running`/`done`/`errored` filtered views, and `reset!`
+- `Conversation` accepts `track_tools: true` to opt into live tool tracking via `tool_tracker` accessor
+- Convention-based event dispatch — every message type now auto-fires a dedicated event based on `message.type` (e.g. `:assistant`, `:stream_event`, `:status`, `:tool_progress`)
+- `EventHandler::EVENTS`, `TYPE_EVENTS`, `DECOMPOSED_EVENTS`, `META_EVENTS` constants enumerating all known events
+- `on_assistant`, `on_user`, `on_stream_event`, `on_status`, `on_tool_progress`, `on_hook_response`, `on_auth_status`, `on_task_notification`, `on_hook_started`, `on_hook_progress`, `on_tool_use_summary`, `on_task_started`, `on_task_progress`, `on_rate_limit_event`, `on_prompt_suggestion`, `on_files_persisted` convenience methods on `EventHandler` and `Client`
+- `Conversation` now accepts any `on_*` keyword argument as a callback (pattern-based, no longer limited to a hardcoded list)
+- `GenericMessage` fires its dynamic type symbol, so `on(:fancy_new_type)` works for future/unknown CLI message types
+- `TaskNotificationMessage#tool_use_id` and `#usage` fields with new `TaskUsage` type (TypeScript SDK parity)
+- `ToolProgressMessage#task_id` field (TypeScript SDK parity)
+- `StatusMessage#permission_mode` field (TypeScript SDK parity)
+- `ModelInfo#supports_effort`, `#supported_effort_levels`, `#supports_adaptive_thinking` fields (TypeScript SDK parity)
+- `McpServerStatus#error`, `#config`, `#scope`, `#tools` fields (TypeScript SDK parity)
+- `StopInput#last_assistant_message` hook field (TypeScript SDK parity)
+- `SubagentStopInput#agent_type` and `#last_assistant_message` hook fields (TypeScript SDK parity)
+- `'oauth'` source in `API_KEY_SOURCES` constant (TypeScript SDK parity)
+- RBS signatures for all new fields
+
+### Changed
+- `EventHandler#handle` now fires three layers per message: `:message` (catch-all) → `message.type` (type-based) → decomposed (`:text`, `:thinking`, `:tool_use`, `:tool_result`)
+- `Conversation::CONVERSATION_KEYS` now contains only infrastructure keys (`client`, `options`, `on_permission`); callback detection is pattern-based via `on_*` prefix
+
+## [0.7.10] - 2026-02-26
+
+### Added
+- `Session.find(id, dir:)` — find a past session by UUID, returns `Session` or `nil`
+- `Session.all` — list all past sessions as `Session` objects
+- `Session.where(dir:, limit:)` — query sessions with optional directory and limit filters
+- `Session#messages` — returns a chainable, `Enumerable` `SessionMessageRelation` for reading transcript messages
+- `SessionMessageRelation#where(limit:, offset:)` — paginate messages with immutable chaining
+- `ClaudeAgent.get_session_messages(session_id, dir:, limit:, offset:)` — read session transcripts from disk (TypeScript SDK v0.2.59 parity)
+- `SessionMessage` type — message from a session transcript with `type`, `uuid`, `session_id`, `message`
+- `SessionPaths` module — shared path infrastructure for session discovery (extracted from `ListSessions`)
+
+### Changed
+- Renamed `Session` (V2 multi-turn API) to `V2Session` to free the `Session` name for the finder API
+- `unstable_v2_create_session`, `unstable_v2_resume_session`, and `unstable_v2_prompt` now return `V2Session`
+
 ## [0.7.9] - 2026-02-25
 
 ### Added

data/README.md

@@ -93,26 +93,6 @@ ClaudeAgent::Client.open do |client|
 end
 ```
 
-### Run Setup Hooks
-
-Run Setup hooks without starting a conversation (useful for CI/CD pipelines):
-
-```ruby
-require "claude_agent"
-
-# Run init Setup hooks (default)
-messages = ClaudeAgent.run_setup
-result = messages.last
-puts "Setup completed" if result.success?
-
-# Run init Setup hooks with custom options
-options = ClaudeAgent::Options.new(cwd: "/my/project")
-ClaudeAgent.run_setup(trigger: :init, options: options)
-
-# Run maintenance Setup hooks
-ClaudeAgent.run_setup(trigger: :maintenance)
-```
-
 ## Conversation API
 
 The `Conversation` class manages the full lifecycle: auto-connects on first message, tracks multi-turn history, accumulates usage, and builds a unified tool activity timeline.
@@ -162,17 +142,20 @@ conversation.close
 
 ### Callbacks
 
-Register callbacks for real-time event handling:
+Register callbacks for real-time event handling. Any `on_*` keyword is accepted — see [Event Handlers](#event-handlers) for the full list.
 
 ```ruby
 conversation = ClaudeAgent.conversation(
-  on_text:        ->(text)    { print text },
-  on_stream:      ->(text)    { print text },          # Alias for on_text
-  on_thinking:    ->(thought) { puts "Thinking: #{thought}" },
-  on_tool_use:    ->(tool)    { puts "Tool: #{tool.display_label}" },
-  on_tool_result: ->(result)  { puts "Result: #{result.content&.slice(0, 80)}" },
-  on_result:      ->(result)  { puts "Done! Cost: $#{result.total_cost_usd}" },
-  on_message:     ->(msg)     { log(msg) }             # Catch-all
+  on_text:           ->(text)    { print text },
+  on_stream:         ->(text)    { print text },          # Alias for on_text
+  on_thinking:       ->(thought) { puts "Thinking: #{thought}" },
+  on_tool_use:       ->(tool)    { puts "Tool: #{tool.display_label}" },
+  on_tool_result:    ->(result)  { puts "Result: #{result.content&.slice(0, 80)}" },
+  on_result:         ->(result)  { puts "Done! Cost: $#{result.total_cost_usd}" },
+  on_message:        ->(msg)     { log(msg) },            # Catch-all
+  on_stream_event:   ->(evt)     { handle_stream(evt) },  # Type-based
+  on_status:         ->(status)  { show_status(status) },
+  on_tool_progress:  ->(prog)    { update_spinner(prog) }
 )
 ```
 
@@ -192,12 +175,49 @@ ClaudeAgent::Conversation.open(permission_mode: "acceptEdits") do |c|
 end
 ```
 
+### Live Tool Tracking
+
+Track tool status in real time for live UIs. Unlike `tool_activity` (built after a turn), `LiveToolActivity` updates as tools run:
+
+```ruby
+# Conversation level — opt in with track_tools: true
+ClaudeAgent::Conversation.open(
+  permission_mode: "acceptEdits",
+  track_tools: true
+) do |c|
+  c.tool_tracker.on_start    { |entry| puts "▸ #{entry.display_label}" }
+  c.tool_tracker.on_progress { |entry| puts "  #{entry.elapsed&.round(1)}s..." }
+  c.tool_tracker.on_complete { |entry| puts "✓ #{entry.display_label}" }
+
+  c.say("Fix the bug in auth.rb")
+  # Tracker resets between turns automatically
+end
+
+# Client level — attach directly
+tracker = ClaudeAgent::ToolActivityTracker.attach(client)
+tracker.on_start    { |entry| show_spinner(entry) }
+tracker.on_complete { |entry| hide_spinner(entry) }
+
+# Standalone — attach to any EventHandler
+tracker = ClaudeAgent::ToolActivityTracker.attach(event_handler)
+
+# Catch-all callback (receives event symbol + entry)
+tracker.on_change { |event, entry| log(event, entry.id) }
+
+# Query running/completed tools at any point
+tracker.running   # => [LiveToolActivity, ...]
+tracker.done      # => [LiveToolActivity, ...]
+tracker.errored   # => [LiveToolActivity, ...]
+tracker["toolu_01ABC"] # => LiveToolActivity (O(1) lookup by tool use ID)
+```
+
 ### Conversation Accessors
 
 ```ruby
 conversation.turns             # Array of TurnResult objects
 conversation.messages          # All messages across all turns
 conversation.tool_activity     # Array of ToolActivity objects
+conversation.tool_tracker      # ToolActivityTracker (when track_tools: true)
 conversation.total_cost        # Total cost in USD
 conversation.session_id        # Session ID from most recent turn
 conversation.usage             # CumulativeUsage stats
@@ -390,15 +410,27 @@ turn.content_blocks      # All content blocks across assistant messages
 
 Register typed callbacks instead of writing `case` statements. Works with `Client`, `Conversation`, or standalone.
 
+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`, `:tool_progress`)
+3. **Decomposed** — convenience events for rich content (`:text`, `:thinking`, `:tool_use`, `:tool_result`)
+
 ### Via Client
 
 ```ruby
 ClaudeAgent::Client.open do |client|
+  # Decomposed events (extracted content)
   client.on_text { |text| print text }
   client.on_tool_use { |tool| puts "\nUsing: #{tool.display_label}" }
   client.on_tool_result { |result, tool_use| puts "Done: #{tool_use&.name}" }
   client.on_result { |result| puts "\nCost: $#{result.total_cost_usd}" }
 
+  # Type-based events (full message object)
+  client.on_stream_event { |evt| handle_stream(evt) }
+  client.on_status { |status| show_status(status) }
+  client.on_tool_progress { |prog| update_spinner(prog) }
+
   client.send_and_receive("Fix the bug in auth.rb")
 end
 ```
@@ -424,6 +456,10 @@ handler.on(:tool_result) { |result, tool_use| puts "Result for #{tool_use&.name}
 handler.on(:result) { |result| puts "Cost: $#{result.total_cost_usd}" }
 handler.on(:message) { |msg| log(msg) }  # Catch-all
 
+# Type-based events work with on() too
+handler.on(:stream_event) { |evt| handle_stream(evt) }
+handler.on(:status) { |status| show_status(status) }
+
 # Dispatch manually
 client.receive_response.each { |msg| handler.handle(msg) }
 handler.reset!  # Clear turn state between turns
@@ -1133,6 +1169,11 @@ client.on_tool_result { |result, tool_use| puts "Done: #{tool_use&.name}" }
 client.on_thinking { |thought| puts thought }
 client.on_result { |result| puts "Cost: $#{result.total_cost_usd}" }
 client.on_message { |msg| log(msg) }
+# Type-based events for all message types
+client.on_assistant { |msg| handle_assistant(msg) }
+client.on_stream_event { |evt| handle_stream(evt) }
+client.on_status { |status| show_status(status) }
+client.on_tool_progress { |prog| update_spinner(prog) }
 
 # Control methods
 client.interrupt                              # Cancel current operation
@@ -1180,14 +1221,20 @@ client.disconnect
 
 ## Session Discovery
 
-List past Claude Code sessions from disk without spawning a CLI subprocess:
+Find and inspect past Claude Code sessions from disk without spawning a CLI subprocess.
+
+### Session.find / Session.all
 
 ```ruby
-# All sessions (most recent first)
-sessions = ClaudeAgent.list_sessions
+# Find a specific session by ID
+session = ClaudeAgent::Session.find("abc-123-def")
+session = ClaudeAgent::Session.find("abc-123-def", dir: "/my/project")
 
-# Scoped to a project directory (includes git worktree siblings)
-sessions = ClaudeAgent.list_sessions(dir: "/path/to/project", limit: 10)
+# List all sessions (most recent first)
+sessions = ClaudeAgent::Session.all
+
+# Filter by directory, limit results
+sessions = ClaudeAgent::Session.where(dir: "/path/to/project", limit: 10)
 
 sessions.each do |s|
   puts "#{s.summary} (#{s.git_branch || 'no branch'})"
@@ -1197,7 +1244,27 @@ sessions.each do |s|
 end
 ```
 
-Each session is a `SessionInfo` with these fields:
+### Reading Messages
+
+`Session#messages` returns a chainable, `Enumerable` relation:
+
+```ruby
+session = ClaudeAgent::Session.find("abc-123-def")
+
+# All messages
+session.messages.each { |m| puts "#{m.type}: #{m.uuid}" }
+
+# Paginated
+session.messages.where(limit: 10).map(&:uuid)
+session.messages.where(offset: 5, limit: 10).to_a
+
+# Enumerable methods work
+session.messages.first
+session.messages.count
+session.messages.select { |m| m.type == "assistant" }
+```
+
+### Session Fields
 
 | Field            | Type            | Description                                      |
 |------------------|-----------------|--------------------------------------------------|
@@ -1210,11 +1277,24 @@ Each session is a `SessionInfo` with these fields:
 | `git_branch`     | `String\|nil`   | Git branch the session was on                    |
 | `cwd`            | `String\|nil`   | Working directory of the session                 |
 
+### Functional API
+
+The lower-level functional API is also available:
+
+```ruby
+# List sessions (returns SessionInfo objects)
+infos = ClaudeAgent.list_sessions(dir: "/path/to/project", limit: 10)
+
+# Read messages directly
+messages = ClaudeAgent.get_session_messages("abc-123-def", limit: 10, offset: 5)
+```
+
+### Resume a Past Session
+
 Use with `Conversation.resume` to pick up where you left off:
 
 ```ruby
-sessions = ClaudeAgent.list_sessions(dir: Dir.pwd, limit: 5)
-session = sessions.first
+session = ClaudeAgent::Session.where(dir: Dir.pwd, limit: 5).first
 
 conversation = ClaudeAgent.resume_conversation(session.session_id)
 turn = conversation.say("Continue where we left off")
@@ -1307,23 +1387,28 @@ session = ClaudeAgent.unstable_v2_create_session(options)
 
 ### Return Types
 
-| Type                  | Purpose                                                                          |
-|-----------------------|----------------------------------------------------------------------------------|
-| `TurnResult`          | Complete agent turn with text, tools, usage, and status accessors                |
-| `ToolActivity`        | Tool use/result pair with turn index and timing                                  |
-| `CumulativeUsage`     | Running totals of tokens, cost, turns, and duration                              |
-| `PermissionRequest`   | Deferred permission promise resolvable from any thread                           |
-| `PermissionQueue`     | Thread-safe queue of pending permission requests                                 |
-| `EventHandler`        | Typed event callback registry                                                    |
-| `SlashCommand`        | Available slash commands (name, description, argument_hint)                      |
-| `ModelInfo`           | Available models (value, display_name, description)                              |
-| `McpServerStatus`     | MCP server status (name, status, server_info)                                    |
-| `AccountInfo`         | Account information (email, organization, subscription_type)                     |
-| `ModelUsage`          | Per-model usage stats (input_tokens, output_tokens, cost_usd)                    |
-| `McpSetServersResult` | Result of set_mcp_servers (added, removed, errors)                               |
-| `RewindFilesResult`   | Result of rewind_files (can_rewind, error, files_changed, insertions, deletions) |
-| `SessionInfo`         | Session metadata from `list_sessions` (session_id, summary, git_branch, cwd)     |
-| `SDKPermissionDenial` | Permission denial info (tool_name, tool_use_id, tool_input)                      |
+| Type                     | Purpose                                                                          |
+|--------------------------|----------------------------------------------------------------------------------|
+| `TurnResult`             | Complete agent turn with text, tools, usage, and status accessors                |
+| `ToolActivity`           | Tool use/result pair with turn index and timing (immutable, post-turn)            |
+| `LiveToolActivity`       | Mutable real-time tool status (running/done/error) with elapsed time             |
+| `ToolActivityTracker`    | Enumerable collection of `LiveToolActivity` with auto-wiring and `on_change`     |
+| `CumulativeUsage`        | Running totals of tokens, cost, turns, and duration                              |
+| `PermissionRequest`      | Deferred permission promise resolvable from any thread                           |
+| `PermissionQueue`        | Thread-safe queue of pending permission requests                                 |
+| `EventHandler`           | Typed event callback registry                                                    |
+| `SlashCommand`           | Available slash commands (name, description, argument_hint)                      |
+| `ModelInfo`              | Available models (value, display_name, description)                              |
+| `McpServerStatus`        | MCP server status (name, status, server_info)                                    |
+| `AccountInfo`            | Account information (email, organization, subscription_type)                     |
+| `ModelUsage`             | Per-model usage stats (input_tokens, output_tokens, cost_usd)                    |
+| `McpSetServersResult`    | Result of set_mcp_servers (added, removed, errors)                               |
+| `RewindFilesResult`      | Result of rewind_files (can_rewind, error, files_changed, insertions, deletions) |
+| `Session`                | Session finder with `.find`, `.all`, `#messages` (wraps SessionInfo)             |
+| `SessionMessageRelation` | Chainable, Enumerable query object for session messages                          |
+| `SessionInfo`            | Session metadata from `list_sessions` (session_id, summary, git_branch, cwd)     |
+| `SessionMessage`         | Message from a session transcript (type, uuid, session_id, message)              |
+| `SDKPermissionDenial`    | Permission denial info (tool_name, tool_use_id, tool_input)                      |
 
 ## Logging
 

data/SPEC.md

@@ -3,11 +3,11 @@
 This document provides a comprehensive specification of the Claude Agent SDK, comparing feature parity across the official TypeScript and Python SDKs with this Ruby implementation.
 
 **Reference Versions:**
-- TypeScript SDK: v0.2.56 (npm package)
-- Python SDK: v0.1.43 from GitHub (commit 9d758dd)
+- TypeScript SDK: v0.2.62 (npm package)
+- Python SDK: v0.1.44 from GitHub (commit 7297bdc)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-02-25
+**Last Updated:** 2026-02-27
 
 ---
 
@@ -68,7 +68,6 @@ Configuration options for SDK queries and clients.
 | `additionalDirectories`           |     ✅      |   ✅    |  ✅   | Extra allowed directories                                    |
 | `env`                             |     ✅      |   ✅    |  ✅   | Environment variables                                        |
 | `sandbox`                         |     ✅      |   ✅    |  ✅   | Sandbox settings                                             |
-| `settings`                        |     ✅      |   ✅    |  ✅   | Settings file path or JSON string (e.g., plansDirectory)     |
 | `settingSources`                  |     ✅      |   ✅    |  ✅   | Which settings to load                                       |
 | `plugins`                         |     ✅      |   ✅    |  ✅   | Plugin configurations                                        |
 | `betas`                           |     ✅      |   ✅    |  ✅   | Beta features (e.g., context-1m-2025-08-07)                  |
@@ -79,10 +78,6 @@ Configuration options for SDK queries and clients.
 | `executable`                      |     ✅      |  N/A   | N/A  | JS runtime (node/bun/deno) - JS-specific                     |
 | `executableArgs`                  |     ✅      |  N/A   | N/A  | JS runtime args - JS-specific                                |
 | `extraArgs`                       |     ✅      |   ✅    |  ✅   | Extra CLI arguments                                          |
-| `user`                            |     ✅      |   ✅    |  ✅   | User identifier (V2 Session API)                             |
-| `init`                            |     ✅      |   ❌    |  ✅   | Run Setup hooks (init trigger), then continue (hidden CLI)   |
-| `initOnly`                        |     ✅      |   ❌    |  ✅   | Run Setup hooks (init trigger), then exit (hidden CLI)       |
-| `maintenance`                     |     ✅      |   ❌    |  ✅   | Run Setup hooks (maintenance trigger), continue (hidden CLI) |
 | `promptSuggestions`               |     ✅      |   ❌    |  ✅   | Enable prompt suggestion after each turn (v0.2.47)           |
 | `debug`                           |     ✅      |   ❌    |  ✅   | Enable verbose debug logging                                 |
 | `debugFile`                       |     ✅      |   ❌    |  ✅   | Write debug logs to specific file path                       |
@@ -148,6 +143,34 @@ Messages exchanged between SDK and CLI.
 | `error_max_budget_usd`                |     ✅      |   ✅    |  ✅   | Budget exceeded                    |
 | `error_max_structured_output_retries` |     ✅      |   ❌    |  ✅   | Structured output retries exceeded |
 
+#### TaskNotificationMessage
+
+| Field         | TypeScript | Python | Ruby | Notes                       |
+|---------------|:----------:|:------:|:----:|-----------------------------|
+| `task_id`     |     ✅      |   ❌    |  ✅   | Task identifier             |
+| `tool_use_id` |     ✅      |   ❌    |  ✅   | Correlating tool call ID    |
+| `status`      |     ✅      |   ❌    |  ✅   | completed/failed/stopped    |
+| `output_file` |     ✅      |   ❌    |  ✅   | Path to task output         |
+| `summary`     |     ✅      |   ❌    |  ✅   | Task summary                |
+| `usage`       |     ✅      |   ❌    |  ✅   | Tokens/tool counts/duration |
+
+#### ToolProgressMessage
+
+| Field                  | TypeScript | Python | Ruby | Notes                   |
+|------------------------|:----------:|:------:|:----:|-------------------------|
+| `tool_use_id`          |     ✅      |   ❌    |  ✅   | Tool use ID             |
+| `tool_name`            |     ✅      |   ❌    |  ✅   | Tool name               |
+| `parent_tool_use_id`   |     ✅      |   ❌    |  ✅   | Parent tool use ID      |
+| `elapsed_time_seconds` |     ✅      |   ❌    |  ✅   | Elapsed time            |
+| `task_id`              |     ✅      |   ❌    |  ✅   | Associated task ID      |
+
+#### StatusMessage
+
+| Field            | TypeScript | Python | Ruby | Notes                   |
+|------------------|:----------:|:------:|:----:|-------------------------|
+| `status`         |     ✅      |   ❌    |  ✅   | Current status          |
+| `permissionMode` |     ✅      |   ❌    |  ✅   | Current permission mode |
+
 #### HookResponseMessage Fields
 
 | Field        | TypeScript | Python | Ruby | Notes                                    |
@@ -252,6 +275,29 @@ Bidirectional control protocol for SDK-CLI communication.
 | `McpSetServersResult`  |     ✅      |   ❌    |  ✅   | Set servers result     |
 | `RewindFilesResult`    |     ✅      |   ✅    |  ✅   | Rewind result          |
 
+#### ModelInfo Fields
+
+| Field                      | TypeScript | Python | Ruby | Notes                           |
+|----------------------------|:----------:|:------:|:----:|---------------------------------|
+| `value`                    |     ✅      |   ❌    |  ✅   | Model identifier                |
+| `displayName`              |     ✅      |   ❌    |  ✅   | Human-readable name             |
+| `description`              |     ✅      |   ❌    |  ✅   | Model description               |
+| `supportsEffort`           |     ✅      |   ❌    |  ✅   | Whether model supports effort   |
+| `supportedEffortLevels`    |     ✅      |   ❌    |  ✅   | Available effort levels         |
+| `supportsAdaptiveThinking` |     ✅      |   ❌    |  ✅   | Whether adaptive thinking works |
+
+#### McpServerStatus Fields
+
+| Field        | TypeScript | Python | Ruby | Notes                              |
+|--------------|:----------:|:------:|:----:|------------------------------------|
+| `name`       |     ✅      |   ✅    |  ✅   | Server name                        |
+| `status`     |     ✅      |   ✅    |  ✅   | Connection status                  |
+| `serverInfo` |     ✅      |   ❌    |  ✅   | Server name/version                |
+| `error`      |     ✅      |   ❌    |  ✅   | Error message (when failed)        |
+| `config`     |     ✅      |   ❌    |  ✅   | Server configuration               |
+| `scope`      |     ✅      |   ❌    |  ✅   | Config scope (project, user, etc.) |
+| `tools`      |     ✅      |   ❌    |  ✅   | Tools with annotations             |
+
 ---
 
 ## 5. Hooks
@@ -304,6 +350,23 @@ Event hooks for intercepting and modifying SDK behavior.
 | `WorktreeCreateHookInput`     |     ✅      |   ❌    |  ✅   |
 | `WorktreeRemoveHookInput`     |     ✅      |   ❌    |  ✅   |
 
+#### StopHookInput Fields
+
+| Field                    | TypeScript | Python | Ruby | Notes                                  |
+|--------------------------|:----------:|:------:|:----:|----------------------------------------|
+| `stop_hook_active`       |     ✅      |   ✅    |  ✅   | Whether stop hook is active            |
+| `last_assistant_message` |     ✅      |   ❌    |  ✅   | Last assistant message text (v0.2.51+) |
+
+#### SubagentStopHookInput Fields
+
+| Field                    | TypeScript | Python | Ruby | Notes                                  |
+|--------------------------|:----------:|:------:|:----:|----------------------------------------|
+| `stop_hook_active`       |     ✅      |   ✅    |  ✅   | Whether stop hook is active            |
+| `agent_id`               |     ✅      |   ✅    |  ✅   | Subagent identifier                    |
+| `agent_transcript_path`  |     ✅      |   ✅    |  ✅   | Path to agent transcript               |
+| `agent_type`             |     ✅      |   ✅    |  ✅   | Agent type                             |
+| `last_assistant_message` |     ✅      |   ❌    |  ✅   | Last assistant message text (v0.2.51+) |
+
 ### Hook Output Types
 
 | Output Field         | TypeScript | Python | Ruby | Notes                 |
@@ -524,9 +587,35 @@ Session management and resumption.
 
 ### Session Discovery
 
-| Feature          | TypeScript | Python | Ruby | Notes                                      |
-|------------------|:----------:|:------:|:----:|--------------------------------------------|
-| `listSessions()` |     ✅      |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+| Feature                | TypeScript | Python | Ruby | Notes                                            |
+|------------------------|:----------:|:------:|:----:|--------------------------------------------------|
+| `listSessions()`       |     ✅      |   ❌    |  ✅   | List past sessions with metadata (v0.2.53)       |
+| `getSessionMessages()` |     ✅      |   ❌    |  ✅   | Read session transcript messages (v0.2.59)       |
+
+#### ListSessionsOptions
+
+| Field   | TypeScript | Python | Ruby | Notes                                     |
+|---------|:----------:|:------:|:----:|-------------------------------------------|
+| `dir`   |     ✅      |   ❌    |  ✅   | Project directory (includes worktrees)    |
+| `limit` |     ✅      |   ❌    |  ✅   | Maximum number of sessions to return      |
+
+#### GetSessionMessagesOptions
+
+| Field    | TypeScript | Python | Ruby | Notes                                        |
+|----------|:----------:|:------:|:----:|----------------------------------------------|
+| `dir`    |     ✅      |   ❌    |  ✅   | Project directory to find session in         |
+| `limit`  |     ✅      |   ❌    |  ✅   | Maximum number of messages to return         |
+| `offset` |     ✅      |   ❌    |  ✅   | Number of messages to skip from the start    |
+
+#### SessionMessage Fields
+
+| Field                | TypeScript | Python | Ruby | Notes                            |
+|----------------------|:----------:|:------:|:----:|----------------------------------|
+| `type`               |     ✅      |   ❌    |  ✅   | 'user' or 'assistant'            |
+| `uuid`               |     ✅      |   ❌    |  ✅   | Message UUID                     |
+| `session_id`         |     ✅      |   ❌    |  ✅   | Session ID                       |
+| `message`            |     ✅      |   ❌    |  ✅   | Raw message content              |
+| `parent_tool_use_id` |     ✅      |   ❌    |  ✅   | Parent tool use ID (always null) |
 
 #### SDKSessionInfo Fields
 
@@ -625,7 +714,7 @@ Error types and hierarchy.
 | `CLIConnectionError` |     ❌      |   ✅    |  ✅   | Connection failed              |
 | `ProcessError`       |     ❌      |   ✅    |  ✅   | CLI process failed             |
 | `JSONDecodeError`    |     ❌      |   ✅    |  ✅   | JSON parsing failed            |
-| `MessageParseError`  |     ❌      |   ❌    |  ✅   | Message parsing failed         |
+| `MessageParseError`  |     ❌      |   ✅    |  ✅   | Message parsing failed         |
 | `TimeoutError`       |     ❌      |   ❌    |  ✅   | Control request timeout        |
 | `ConfigurationError` |     ❌      |   ❌    |  ✅   | Invalid configuration          |
 
@@ -649,9 +738,10 @@ Public API surface for SDK clients.
 
 ### Standalone Functions
 
-| Feature          |    TypeScript    | Python | Ruby | Notes                                      |
-|------------------|:----------------:|:------:|:----:|--------------------------------------------|
-| `listSessions()` | ✅ `listSessions` |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+| Feature                | TypeScript | Python | Ruby | Notes                                      |
+|------------------------|:----------:|:------:|:----:|--------------------------------------------|
+| `listSessions()`       |     ✅      |   ❌    |  ✅   | List past sessions with metadata (v0.2.53) |
+| `getSessionMessages()` |     ✅      |   ❌    |  ✅   | Read session transcript (v0.2.59)          |
 
 ### Query Interface
 
@@ -720,32 +810,38 @@ Public API surface for SDK clients.
 - Source is bundled/minified, but `sdk.d.ts` provides complete type definitions
 - Includes unstable V2 session API
 - `executable`/`executableArgs` are JS-specific (`node`/`bun`/`deno`)
+- Does NOT have `settings`, `user`, `init`/`initOnly`/`maintenance` as typed Options (use `extraArgs` or `settingSources`)
+- `ApiKeySource` includes `'oauth'`
 - v0.2.45: Added `TaskStartedMessage`, `RateLimitEvent` message types
 - v0.2.47: Added `promptSuggestions` option and `PromptSuggestionMessage`
 - v0.2.49: Added `ConfigChange` hook event, `SandboxFilesystemConfig`, ModelInfo capability fields
 - v0.2.50: Added `WorktreeCreate`/`WorktreeRemove` hook events, `apply_flag_settings` control request
-- v0.2.51: Added `TaskProgressMessage` for real-time background agent progress reporting
+- v0.2.51: Added `TaskProgressMessage`, `StopHookInput.last_assistant_message`, `SubagentStopHookInput.last_assistant_message`
 - v0.2.52: Added `mcp_authenticate`/`mcp_clear_auth` control requests for MCP server authentication
 - v0.2.53: Added `listSessions()` for discovering and listing past sessions with `SDKSessionInfo` metadata
-- v0.2.54 – v0.2.56: CLI parity updates (no new SDK-facing features)
+- v0.2.54 – v0.2.58: CLI parity updates (no new SDK-facing features)
+- v0.2.59: Added `getSessionMessages()` for reading session transcript history with pagination (limit/offset)
+- v0.2.61 – v0.2.62: CLI parity updates (no new SDK-facing features)
 
 ### Python SDK
 - Full source available with `Transport` abstract class
 - Partial control protocol: query and client support interrupt, setPermissionMode, setModel, rewindFiles, mcpStatus
-- Has `CLINotFoundError`, `CLIConnectionError`, `ProcessError`, `CLIJSONDecodeError` error types
+- Has `CLINotFoundError`, `CLIConnectionError`, `ProcessError`, `CLIJSONDecodeError`, `MessageParseError` error types
 - Missing hooks: SessionStart, SessionEnd, Setup, TeammateIdle, TaskCompleted, ConfigChange, WorktreeCreate, WorktreeRemove
 - Missing permission modes: `dontAsk`
 - Missing options: `allowDangerouslySkipPermissions`, `persistSession`, `resumeSessionAt`, `sessionId`, `strictMcpConfig`, `init`/`initOnly`/`maintenance`, `debug`/`debugFile`, `promptSuggestions`
 - `ToolPermissionContext` missing `blockedPath`, `decisionReason`, `toolUseID`, `agentID`, `description`
+- Has `agent_type` field in `SubagentStopHookInput`
 - Has SDK MCP server support with `tool()` helper and annotations
 - Added `thinking` config and `effort` option in v0.1.36
 - Handles `rate_limit_event` and unknown message types gracefully (v0.1.40)
 - Client has `get_server_info()` for accessing the initialization result (v0.1.31+)
-- v0.1.42 – v0.1.43: CLI parity updates (no new SDK-facing features)
+- v0.1.42 – v0.1.44: CLI parity updates (no new SDK-facing features; latest commit bumps bundled CLI to v2.1.61)
 
 ### Ruby SDK (This Repository)
-- Feature parity with TypeScript SDK v0.2.56
+- Feature parity with TypeScript SDK v0.2.62
 - Ruby-idiomatic patterns (Data.define, snake_case)
 - Complete control protocol, hook, and V2 Session API support
 - Dedicated Client class for multi-turn conversations
 - `executable`/`executableArgs` marked N/A (JS runtime options)
+- Has `settings`, `init`/`initOnly`/`maintenance`, `user` options (not typed in TS SDK)

data/lib/claude_agent/client.rb

@@ -159,50 +159,28 @@ module ClaudeAgent
     # Handlers persist across turns and fire automatically during
     # {#receive_turn} and {#send_and_receive}.
     #
-    # @param event [Symbol] Event name (:message, :text, :thinking, :tool_use, :tool_result, :result)
+    # See {EventHandler} for the full event hierarchy:
+    # - +:message+ — catch-all for every message
+    # - Type-based — +:assistant+, +:stream_event+, +:status+, etc.
+    # - Decomposed — +:text+, +:thinking+, +:tool_use+, +:tool_result+
+    #
+    # @param event [Symbol] Event name (see {EventHandler::EVENTS})
     # @yield Event-specific arguments
     # @return [self]
     #
     # @example
     #   client.on(:text) { |text| print text }
     #   client.on(:tool_use) { |tool| show_spinner(tool) }
+    #   client.on(:stream_event) { |evt| handle_stream(evt) }
     #
     def on(event, &block)
       @event_handler.on(event, &block)
       self
     end
 
-    # @!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]
-
-    # @!method on_message(&block)
-    #   Register a handler for every message (catch-all)
-    #   @yield [message] Any message object
-    #   @return [self]
-
-    %i[message text thinking tool_use tool_result result].each do |event|
+    # Generates on_* convenience methods for all known events.
+    # See {EventHandler::EVENTS} for the complete list.
+    EventHandler::EVENTS.each do |event|
       define_method(:"on_#{event}") { |&block| on(event, &block) }
     end