claude_agent 0.7.10 → 0.7.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1029f92c20c52b0d86d2942e3bb681fe0b0810ee14e5c848dc3f918a60969bb
-  data.tar.gz: 13b11ee08fd011a9787a404b389c0c1290619eeec15abd4d7bde3885235daf61
+  metadata.gz: 965fad355090a487a22e76e097ed84aa7426fe4db396a28e0165e6ceaa09b1e2
+  data.tar.gz: fe03eeffb6dfa608c5a40bc55d1b04b31f30bd0ec5d8a50322b2dc7bf127bdea
 SHA512:
-  metadata.gz: c7a0c0d980c96d6ebb4875916b15a7a9c49d6e6f657021722b54794951c9cb5cabad0589b4a7120210390aa0a9b27d4238e902bf6d26e141489a667bac8c9efa
-  data.tar.gz: 72e41cc15471827325a75f67de90bef61fe0b42ebedd36dd5b88a6c942d5fcba51caafbb83005a6eea560baa2be73b4b38bc765026c58f287e1d802c61e09c57
+  metadata.gz: b7353c7235415c842e29ba73c315f10ba52d6731324d0e326ecfe56f321272246a6877f07fd2e451007b3ac9252c007f312da15650c77f8ef4c99d06a1e907d1
+  data.tar.gz: ece71bf88dddd47d40da3dd13e660c8e39eba12484daaf1fa0b87731ff130b8b6ddfcb215e352d2f34c587eb55998a9d1669bbe88363a2587e342190c5b80c0e

data/CHANGELOG.md

@@ -7,6 +7,31 @@ 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

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
@@ -1349,7 +1390,9 @@ session = ClaudeAgent.unstable_v2_create_session(options)
 | Type                     | Purpose                                                                          |
 |--------------------------|----------------------------------------------------------------------------------|
 | `TurnResult`             | Complete agent turn with text, tools, usage, and status accessors                |
-| `ToolActivity`           | Tool use/result pair with turn index and timing                                  |
+| `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                                 |

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.61 (npm package)
+- TypeScript SDK: v0.2.62 (npm package)
 - Python SDK: v0.1.44 from GitHub (commit 7297bdc)
 - Ruby SDK: This repository
 
-**Last Updated:** 2026-02-26
+**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                 |
@@ -651,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          |
 
@@ -747,25 +810,28 @@ 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.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: CLI parity update (no new SDK-facing features)
+- 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)
@@ -773,8 +839,9 @@ Public API surface for SDK clients.
 - 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.61
+- 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
 

data/lib/claude_agent/control_protocol.rb

@@ -352,7 +352,10 @@ module ClaudeAgent
         ModelInfo.new(
           value: model["value"],
           display_name: model["displayName"],
-          description: model["description"]
+          description: model["description"],
+          supports_effort: model["supportsEffort"],
+          supported_effort_levels: model["supportedEffortLevels"],
+          supports_adaptive_thinking: model["supportsAdaptiveThinking"]
         )
       end
 
@@ -384,7 +387,10 @@ module ClaudeAgent
         ModelInfo.new(
           value: model["value"],
           display_name: model["displayName"],
-          description: model["description"]
+          description: model["description"],
+          supports_effort: model["supportsEffort"],
+          supported_effort_levels: model["supportedEffortLevels"],
+          supports_adaptive_thinking: model["supportsAdaptiveThinking"]
         )
       end
     end
@@ -397,7 +403,11 @@ module ClaudeAgent
         McpServerStatus.new(
           name: server["name"],
           status: server["status"],
-          server_info: server["serverInfo"]
+          server_info: server["serverInfo"],
+          error: server["error"],
+          config: server["config"],
+          scope: server["scope"],
+          tools: server["tools"]
         )
       end
     end

data/lib/claude_agent/conversation.rb

@@ -29,14 +29,13 @@ module ClaudeAgent
   #   conversation.say("Continue where we left off")
   #
   class Conversation
-    # Keys consumed by Conversation; everything else forwards to Options
-    CONVERSATION_KEYS = %i[
-      on_text on_stream on_tool_use on_tool_result
-      on_thinking on_result on_message on_permission
-      client options
-    ].freeze
+    # Keys consumed directly by Conversation; everything else is a callback or forwarded to Options
+    CONVERSATION_KEYS = %i[client options on_permission track_tools].freeze
 
-    attr_reader :turns, :messages, :tool_activity, :client
+    # Callback aliases (alternative names mapping to canonical events)
+    CALLBACK_ALIASES = { on_stream: :text }.freeze
+
+    attr_reader :turns, :messages, :tool_activity, :client, :tool_tracker
 
     # Open a conversation with automatic cleanup.
     #
@@ -62,7 +61,8 @@ module ClaudeAgent
     # Create a new conversation.
     #
     # Accepts all {Options} keyword arguments plus conversation-level
-    # callbacks:
+    # callbacks. Any +on_*+ keyword is registered as an event callback
+    # (see {EventHandler::EVENTS} for available events).
     #
     # @param on_text [Proc] Handler for streaming text
     # @param on_stream [Proc] Alias for on_text
@@ -71,13 +71,15 @@ module ClaudeAgent
     # @param on_thinking [Proc] Handler for thinking events
     # @param on_result [Proc] Handler for result events
     # @param on_message [Proc] Handler for all messages
+    # @param on_stream_event [Proc] Handler for stream events
+    # @param on_status [Proc] Handler for status messages
+    # @param on_tool_progress [Proc] Handler for tool progress messages
     # @param on_permission [Symbol, Proc] :queue (default) or a callable for can_use_tool
     # @param client [Client] Pre-built client (for testing)
     # @param options [Options] Pre-built options object
     #
     def initialize(**kwargs)
-      conversation_kwargs = kwargs.slice(*CONVERSATION_KEYS)
-      options_kwargs = kwargs.except(*CONVERSATION_KEYS)
+      callbacks, conversation_kwargs, options_kwargs = partition_kwargs(kwargs)
 
       @options = conversation_kwargs[:options] || build_options(options_kwargs, conversation_kwargs)
       @client = conversation_kwargs[:client] || Client.new(options: @options)
@@ -89,8 +91,9 @@ module ClaudeAgent
       @tool_result_timestamps = {}
       @connected = false
       @closed = false
+      @tool_tracker = conversation_kwargs[:track_tools] ? ToolActivityTracker.attach(@client) : nil
 
-      register_callbacks(conversation_kwargs)
+      register_callbacks(callbacks)
       register_timing_hooks
     end
 
@@ -113,6 +116,7 @@ module ClaudeAgent
 
       @turns << turn
       build_tool_activities(turn, @turns.size - 1)
+      @tool_tracker&.reset!
 
       logger.info("conversation") { "Turn #{@turns.size - 1} complete (#{turn.tool_uses.size} tools, cost=$#{total_cost})" }
 
@@ -189,6 +193,24 @@ module ClaudeAgent
 
     private
 
+    def partition_kwargs(kwargs)
+      callbacks = {}
+      conversation_kwargs = {}
+      options_kwargs = {}
+
+      kwargs.each do |key, value|
+        if CONVERSATION_KEYS.include?(key)
+          conversation_kwargs[key] = value
+        elsif key.to_s.start_with?("on_")
+          callbacks[key] = value
+        else
+          options_kwargs[key] = value
+        end
+      end
+
+      [ callbacks, conversation_kwargs, options_kwargs ]
+    end
+
     def build_options(options_kwargs, conversation_kwargs)
       permission = conversation_kwargs[:on_permission]
 
@@ -201,16 +223,12 @@ module ClaudeAgent
       Options.new(**options_kwargs)
     end
 
-    def register_callbacks(kwargs)
-      mapping = {
-        on_text: :text, on_stream: :text, on_thinking: :thinking,
-        on_tool_use: :tool_use, on_tool_result: :tool_result,
-        on_result: :result, on_message: :message
-      }
+    def register_callbacks(callbacks)
+      callbacks.each do |key, callback|
+        next unless callback
 
-      mapping.each do |key, event|
-        callback = kwargs[key]
-        @client.on(event, &callback) if callback
+        event = CALLBACK_ALIASES[key] || key.to_s.delete_prefix("on_").to_sym
+        @client.on(event, &callback)
       end
     end