claude_agent 0.7.12 → 0.7.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22706a6a24af11c5f24404ee12add5ff617a6c293e5869c5437d295f6314c9dd
-  data.tar.gz: e55b7eaba0ede01618c88971992651c5f4d09253333b31abf6ff52fb52098464
+  metadata.gz: 6b6188550282e29001c6bf2996842b5c11cd013de37aeeded995c982cef67399
+  data.tar.gz: 33e7d2e6b000d5f085093f236fd531c136e3711be170c3af4c11715fbdedda77
 SHA512:
-  metadata.gz: 325f9c1e944e5eaaa51f7a5ae1029e1bf93016ce8abcfd9983185771830b9be2d560093a1c42d70dd1a9755b1c501dbad2f4e46e873dc3b7c424677c3280d5e4
-  data.tar.gz: 9bddde78dec0a0dd251cc9fc77c6379b9206469e18ce4310d6e444b231e4f65ce137235d89422778e2a2bd09b258254801479ea98ea3092bdef7b0c855fccafc
+  metadata.gz: b5ec2de8caa5ef32681e671645dd6d6540d58f86221c3d99186cc7ab7e9a076b892fe41c16e2472b94399c296439b5ceba72f573eb0b218b8b2ff507661d162f
+  data.tar.gz: c00a1312f295f1f15949cac076155750b2259f5412cfb0cbe6acffa8bcb789927887bb58ebacdc94fd92fa492851f985b975a14bb31abe68b78e23ce4fda8c5d

data/.claude/rules/testing.md

@@ -7,12 +7,14 @@ SDK-specific testing guidance. For general patterns (base classes, mocking, stru
 ```bash
 bundle exec rake test                                    # Unit tests only
 bundle exec rake test_integration                        # Integration tests (requires CLI v2.0.0+)
+bundle exec rake test_smoke                              # Smoke tests against local LLM (e.g. Ollama)
 bundle exec rake test_all                                # All tests
 bundle exec ruby -Itest test/claude_agent/test_foo.rb   # Single file
 
 # Binstubs
 bin/test                                                 # Unit tests only
 bin/test-integration                                     # Integration tests
+bin/test-smoke                                           # Smoke tests (Ollama)
 bin/test-all                                             # All tests
 ```
 
@@ -22,6 +24,7 @@ bin/test-all                                             # All tests
 test/
 ├── test_helper.rb              # Central setup, requires, base class
 ├── integration_helper.rb       # Base class for integration tests
+├── smoke_helper.rb             # Base class for smoke tests (Ollama)
 ├── support/                    # Shared mocks, test transports, helpers
 │   └── mock_transport.rb
 ├── claude_agent/               # Unit tests (mirrors lib/claude_agent/)
@@ -29,10 +32,15 @@ test/
 │   ├── test_options.rb
 │   └── mcp/
 │       └── test_tool.rb
-├── integration/                # Integration tests (require Claude CLI)
-│   ├── test_query.rb
-│   ├── test_client.rb
-│   └── ...
+├── integration/                # Scenario tests (require Claude CLI)
+│   ├── test_query_scenarios.rb
+│   ├── test_client_scenarios.rb
+│   ├── test_conversation_scenarios.rb
+│   ├── test_session_scenarios.rb
+│   ├── test_permissions_and_tools_scenarios.rb
+│   └── test_transport.rb
+├── smoke/                      # Smoke tests (local LLM via Ollama)
+│   └── test_basic.rb
 └── fixtures/                   # JSON fixtures for parser tests
     ├── assistant_message.json
     └── tool_use_response.json
@@ -225,19 +233,27 @@ end
 
 ## Integration Tests
 
+Integration tests are **scenario tests** that consolidate multiple assertions per CLI process spawn. Each test exercises a complete workflow rather than testing a single field.
+
 Integration tests live in `test/integration/` and inherit from `IntegrationTestCase`:
 
 ```ruby
-# test/integration/test_query.rb
+# test/integration/test_query_scenarios.rb
 require_relative "../integration_helper"
 
-class TestIntegrationQuery < IntegrationTestCase
-  test "real query returns result" do
-    messages = ClaudeAgent.query(prompt: "Say hello", options: test_options).to_a
-    result = messages.find { |m| m.is_a?(ClaudeAgent::ResultMessage) }
+class TestIntegrationQueryScenarios < IntegrationTestCase
+  test "query lifecycle: messages, fields, and content" do
+    messages = ClaudeAgent.query(prompt: "Reply with exactly: HELLO", options: test_options).to_a
 
+    # Assert system, assistant, and result messages in one spawn
+    system_msg = messages.find { |m| m.is_a?(ClaudeAgent::SystemMessage) }
+    assert_not_nil system_msg
+    assert_equal "init", system_msg.subtype
+
+    result = messages.find { |m| m.is_a?(ClaudeAgent::ResultMessage) }
     assert_not_nil result
-    assert result.success?
+    assert_equal false, result.is_error
+    assert_not_nil result.session_id
   end
 end
 ```
@@ -247,6 +263,31 @@ The `IntegrationTestCase` base class:
 - Skips if Claude CLI is not installed
 - Provides `test_options` helper with sensible defaults
 
+## Smoke Tests
+
+Smoke tests run the same core paths against a local LLM (e.g. Ollama) for fast feedback without Anthropic API costs.
+
+Smoke tests live in `test/smoke/` and inherit from `SmokeTestCase`:
+
+```ruby
+# test/smoke/test_basic.rb
+require_relative "../smoke_helper"
+
+class TestSmokeBasic < SmokeTestCase
+  test "basic query returns result" do
+    messages = ClaudeAgent.query(prompt: "Reply with exactly: PING", options: test_options).to_a
+    result = messages.find { |m| m.is_a?(ClaudeAgent::ResultMessage) }
+    assert_not_nil result
+  end
+end
+```
+
+The `SmokeTestCase` base class:
+- Extends `IntegrationTestCase` (requires CLI + INTEGRATION=true)
+- Skips unless `SMOKE=true` is set (automatic with `rake test_smoke`)
+- Checks Ollama availability before running
+- `rake test_smoke` auto-sets `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`, and `ANTHROPIC_AUTH_TOKEN`
+
 ## What to Test
 
 | Component      | Focus Areas                                 |

data/.claude/settings.json

@@ -30,6 +30,7 @@
       "Bash(bin/setup:*)",
       "Bash(bin/test:*)",
       "Bash(bin/test-integration:*)",
+      "Bash(bin/test-smoke:*)",
       "Bash(bin/test-all:*)",
       "Bash(bin/update-reference-sdks:*)",
       "WebFetch(domain:docs.anthropic.com)",

data/ARCHITECTURE.md

@@ -0,0 +1,237 @@
+# TypeScript SDK Architecture: Data Flow
+
+How data flows through the `@anthropic-ai/claude-agent-sdk`. Not about specific classes — about **concepts**, what they wrap, and where data lives.
+
+## The Big Picture
+
+The SDK is a **process bridge**. It spawns the Claude Code CLI as a subprocess and communicates over JSON Lines via stdin/stdout. Everything flows through this pipe.
+
+```mermaid
+graph TB
+    subgraph "SDK Process (your app)"
+        USER["Your Code"]
+        Q["query() / SDKSession"]
+        OPT["Options"]
+        CP["Control Protocol"]
+        HOOKS["Hook Callbacks"]
+        MCP_SDK["SDK MCP Servers"]
+        PERM["canUseTool Callback"]
+    end
+
+    subgraph "CLI Subprocess"
+        CLI["Claude Code CLI"]
+        CLAUDE_API["Claude API"]
+        MCP_EXT["External MCP Servers"]
+        TOOLS["Built-in Tools\n(Bash, Read, Edit...)"]
+    end
+
+    USER -->|"prompt + options"| Q
+    Q -->|"builds CLI args + env"| OPT
+    OPT -->|"spawns process"| CLI
+    Q <-->|"JSON Lines\nstdin/stdout"| CP
+    CP <-->|"control_request/\ncontrol_response"| CLI
+    CLI <-->|"API calls"| CLAUDE_API
+    CLI <-->|"stdio/SSE/HTTP"| MCP_EXT
+    CLI -->|"executes"| TOOLS
+    CP -->|"routes"| HOOKS
+    CP -->|"routes"| MCP_SDK
+    CP -->|"routes"| PERM
+```
+
+## Two Message Channels on One Pipe
+
+All messages flow through one stdin/stdout pipe, but the Control Protocol splits them into two logical channels:
+
+```mermaid
+graph LR
+    subgraph "stdout from CLI"
+        RAW["Raw JSON Lines"]
+    end
+
+    RAW -->|"type: control_request\ntype: control_response"| CTRL["Control Channel\n(handled in-process)"]
+    RAW -->|"type: assistant\ntype: result\ntype: system\ntype: user\n..."| SDK_Q["SDK Channel\n(queued for your code)"]
+
+    CTRL -->|"can_use_tool"| PERM["Permission Callback"]
+    CTRL -->|"hook_callback"| HOOK["Hook Callbacks"]
+    CTRL -->|"mcp_message"| MCP["SDK MCP Server"]
+    CTRL -->|"elicitation"| ELICIT["Elicitation Callback"]
+
+    SDK_Q --> PARSE["Message Parser"]
+    PARSE --> TYPED["Typed SDK Messages\n(SDKMessage union)"]
+```
+
+## Data Flow: A Complete Turn
+
+```mermaid
+sequenceDiagram
+    participant App as Your Code
+    participant Q as query()
+    participant CP as Control Protocol
+    participant T as Transport (stdin/stdout)
+    participant CLI as Claude Code CLI
+    participant API as Claude API
+
+    Note over Q,T: 1. SETUP
+    App->>Q: query({ prompt, options })
+    Q->>T: spawn("claude", [...args])
+    T->>CLI: process starts
+    Q->>CP: start(streaming: true)
+    CP->>T: write: {type: "control_request",\nrequest: {subtype: "initialize",\nhooks, sdkMcpServers, agents...}}
+    CLI-->>T: {type: "control_response",\nresponse: {commands, models, account...}}
+    CP-->>Q: initialized
+
+    Note over Q,T: 2. SEND PROMPT
+    CP->>T: write: {type: "user",\nmessage: {role: "user", content: "..."}}
+
+    Note over CLI,API: 3. CLI PROCESSES
+    CLI->>API: messages.create(...)
+    API-->>CLI: streaming response
+
+    Note over Q,T: 4. PERMISSION CHECK (if tool use)
+    CLI-->>T: {type: "control_request",\nrequest: {subtype: "can_use_tool",\ntool_name: "Bash"...}}
+    CP->>App: canUseTool("Bash", input, options)
+    App-->>CP: {behavior: "allow"}
+    CP->>T: write: {type: "control_response",\nresponse: {behavior: "allow"}}
+
+    Note over Q,T: 5. STREAM RESULTS
+    CLI-->>T: {type: "assistant",\nmessage: {content: [...]}}
+    T-->>CP: routes to SDK queue
+    CP-->>Q: SDKAssistantMessage
+    Q-->>App: yield message
+
+    CLI-->>T: {type: "result",\nsubtype: "success", result: "...", usage: {...}}
+    T-->>CP: routes to SDK queue
+    CP-->>Q: SDKResultMessage
+    Q-->>App: yield message (iteration ends)
+```
+
+## What Wraps CLI Data vs. What's an SDK Abstraction
+
+### SDK Abstractions
+
+Invented by the SDK — not in the CLI's JSON protocol.
+
+| Concept                | What it does                                                                                                            |
+|------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| `query()`              | Entry point. Returns `AsyncGenerator<SDKMessage>`. Spawns process, runs handshake, sends prompt, yields typed messages. |
+| `SDKSession`           | V2 multi-turn session interface. `.send()` / `.stream()` / `.close()`.                                                  |
+| `Options`              | Converts user config into CLI args + env vars. The SDK's configuration surface.                                         |
+| Control Protocol       | Routes messages between two channels. Manages request/response matching with IDs.                                       |
+| `canUseTool`           | Permission callback. CLI sends a control request, SDK routes it to your function.                                       |
+| `HookCallback`         | In-process hook execution. CLI sends hook input, SDK calls your function, returns result.                               |
+| `createSdkMcpServer()` | Hosts an MCP server in your process. CLI routes MCP messages to it via control protocol.                                |
+| `onElicitation`        | User input callback for MCP OAuth flows.                                                                                |
+| Query methods          | `.interrupt()`, `.setModel()`, `.rewindFiles()`, `.setMcpServers()` — all send control requests.                        |
+| `listSessions()`       | Reads the CLI's session JSONL files from disk. No subprocess involved.                                                  |
+| `getSessionMessages()` | Parses the CLI's transcript format from disk.                                                                           |
+
+### CLI Protocol Wrappers
+
+Direct 1:1 mapping of JSON the CLI sends/receives. The SDK adds TypeScript types but doesn't transform the data.
+
+| Type                                   | CLI JSON it wraps                                                                                            |
+|----------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| `SDKAssistantMessage`                  | `{type: "assistant", message: BetaMessage}`                                                                  |
+| `SDKUserMessage`                       | `{type: "user", message: MessageParam}`                                                                      |
+| `SDKResultMessage`                     | `{type: "result", subtype: "success"\|"error_*"}`                                                            |
+| `SDKSystemMessage`                     | `{type: "system", subtype: "init"}`                                                                          |
+| `SDKStatusMessage`                     | `{type: "system", subtype: "status"}`                                                                        |
+| `SDKPartialAssistantMessage`           | `{type: "stream_event", event: ...}`                                                                         |
+| `SDKHookStarted/Progress/Response`     | Hook lifecycle messages                                                                                      |
+| `SDKTaskStarted/Progress/Notification` | Subagent task messages                                                                                       |
+| `SDKToolProgressMessage`               | Tool execution progress                                                                                      |
+| `SDKRateLimitEvent`                    | Rate limit state changes                                                                                     |
+| `SDKCompactBoundaryMessage`            | Context compaction markers                                                                                   |
+| `SDKFilesPersistedEvent`               | File checkpoint events                                                                                       |
+| `SDKElicitationCompleteMessage`        | MCP elicitation completion                                                                                   |
+| `SDKPromptSuggestionMessage`           | Predicted next prompt                                                                                        |
+| Control request/response types         | `initialize`, `can_use_tool`, `hook_callback`, `mcp_message`, `interrupt`, `set_model`, `rewind_files`, etc. |
+
+### Configuration Wrappers
+
+SDK types that map to CLI flags, env vars, or config JSON.
+
+| SDK Type               | Maps to                                      |
+|------------------------|----------------------------------------------|
+| `PermissionMode`       | `--permission-mode` flag                     |
+| `McpStdioServerConfig` | MCP server config JSON                       |
+| `AgentDefinition`      | `--agents` JSON config                       |
+| `SandboxSettings`      | `--sandbox-settings` JSON                    |
+| `OutputFormat`         | `--output-format` config                     |
+| `ThinkingConfig`       | `--thinking` / `--max-thinking-tokens`       |
+| `SystemPrompt`         | `--system-prompt` / `--append-system-prompt` |
+| `SettingSource`        | `--settings-sources` flag                    |
+
+### Pass-through Types
+
+Types from upstream protocols that flow through untouched. The SDK re-exports them for convenience.
+
+| Type                        | Source                                        |
+|-----------------------------|-----------------------------------------------|
+| `BetaMessage`               | `@anthropic-ai/sdk` (Anthropic API response)  |
+| `BetaUsage`                 | `@anthropic-ai/sdk` (token counts from API)   |
+| `MessageParam`              | `@anthropic-ai/sdk` (API input format)        |
+| `BetaRawMessageStreamEvent` | `@anthropic-ai/sdk` (streaming chunks)        |
+| `JSONRPCMessage`            | `@modelcontextprotocol/sdk` (MCP wire format) |
+| `CallToolResult`            | `@modelcontextprotocol/sdk` (MCP tool output) |
+| `ElicitResult`              | `@modelcontextprotocol/sdk` (MCP user input)  |
+
+## The Three Layers
+
+```mermaid
+graph TB
+    subgraph L3["Layer 3: SDK Abstractions"]
+        direction LR
+        query["query()"]
+        session["SDKSession"]
+        opts["Options builder"]
+        ctrl["Control Protocol"]
+        callbacks["Callbacks\n(canUseTool, hooks,\nonElicitation)"]
+        session_mgmt["Session Management\n(listSessions,\ngetSessionMessages)"]
+    end
+
+    subgraph L2["Layer 2: CLI Protocol Types"]
+        direction LR
+        msgs["SDKMessage union\n(21+ message types)"]
+        ctrl_req["Control Requests\n(initialize, can_use_tool,\nhook_callback, ...)"]
+        ctrl_resp["Control Responses"]
+    end
+
+    subgraph L1["Layer 1: Pass-through Types"]
+        direction LR
+        beta["BetaMessage\n(Anthropic API)"]
+        usage["BetaUsage\n(Anthropic API)"]
+        msgparam["MessageParam\n(Anthropic API)"]
+        jsonrpc["JSONRPCMessage\n(MCP protocol)"]
+        content["Content Blocks\n(text, tool_use, thinking)"]
+    end
+
+    L3 --> L2
+    L2 --> L1
+
+    style L3 fill:#e1f5fe
+    style L2 fill:#fff3e0
+    style L1 fill:#f3e5f5
+```
+
+**Layer 1 (Pass-through):** Types from the Anthropic API and MCP protocol. The CLI's `SDKAssistantMessage.message` is literally a `BetaMessage` from the API. The SDK doesn't interpret content blocks — they're whatever the API returned.
+
+**Layer 2 (CLI Protocol):** The JSON shapes the CLI sends/receives over JSON Lines. The SDK defines TypeScript types for them but doesn't transform the data. It's a typed window into what the CLI emits.
+
+**Layer 3 (SDK Abstractions):** Things the SDK invents. `query()` is not a CLI concept — it's an ergonomic wrapper that spawns a process, runs the control protocol handshake, sends the prompt, and yields typed messages. The Control Protocol's routing logic is an SDK concept. The CLI just sends a control request and blocks until it gets a response.
+
+## Key Insight: The SDK is Thin Where It Matters
+
+The SDK deliberately avoids re-interpreting CLI data. It doesn't parse content blocks into rich objects, doesn't build conversation trees, doesn't accumulate state. It's a **typed streaming bridge**:
+
+```
+Your prompt --> Options --> CLI args --> subprocess --> JSON Lines --> typed messages --> your code
+                                            ^                              |
+                                            +-- control requests <---------+
+                                                (permissions, hooks, MCP)
+```
+
+The "intelligence" lives in three places:
+1. **The CLI** — runs Claude, manages tools, handles the API
+2. **The Control Protocol** — routes bidirectional requests between CLI and your callbacks
+3. **Your code** — decides permissions, handles hooks, processes messages

data/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.14] - 2026-03-14
+
+### Fixed
+- Replace busy-wait polling (`Queue#pop(true)` + `sleep 0.01`) in `ControlProtocol::Messaging#each_message` with blocking `Queue#pop` and `:done` sentinel, eliminating CPU waste and up-to-10ms per-message latency
+- Fix `Conversation#partition_kwargs` misrouting `on_elicitation` (and any future `on_*` Options attributes) as event callbacks instead of forwarding to Options; now uses explicit allowlist derived from `EventHandler::EVENTS`
+- Remove global `ENV["CLAUDE_CODE_ENTRYPOINT"]` mutation from `Client#connect` and `ClaudeAgent.query`; the subprocess already receives this via `Options#to_env`
+- Log stderr callback errors instead of silently swallowing them in `Transport::Subprocess`
+
+## [0.7.13] - 2026-03-14
+
+### Added
+- Ollama smoke test profile (`rake test_smoke`, `bin/test-smoke`) for fast local testing against local LLMs
+- `SmokeTestCase` base class with Ollama availability check and configurable `SMOKE_MODEL` env var
+
+### Changed
+- Restructured integration test suite: removed 92 misplaced unit tests, consolidated 52 CLI tests into 16 scenario tests across 5 files
+- Integration tests now use scenario-based structure (`test_*_scenarios.rb`) that exercises multiple assertions per CLI process spawn
+- Split `content_blocks.rb` (352 lines) into `content_blocks/` directory with 8 focused files + barrel file
+- Split `types.rb` (300 lines) into `types/` directory with 5 domain-grouped files + barrel file
+- Split `messages.rb` (908 lines) into `messages/` directory with 8 semantic-domain files + barrel file
+- Extracted `control_protocol.rb` (1,010 lines) into 5 mixin modules (`Primitives`, `Lifecycle`, `Messaging`, `Commands`, `RequestHandling`) + shell class
+- Extracted `Client::Commands` mixin from `client.rb` (545 lines) for CLI command delegations
+- Extracted `Options::Serializer` mixin from `options.rb` (344 lines) for CLI arg/env serialization
+- Split `session.rb` into `v2_session.rb` (V2 Session API) and `session.rb` (historical finder)
+- Split monolithic test files to mirror lib/ directory structure (`test/claude_agent/{messages,content_blocks,types,control_protocol}/`)
+- Added RBS module declarations for `ControlProtocol`, `Client`, and `Options` mixins
+
+### Added
+- `AgentInfo` type with `name`, `description`, and `model` fields (TypeScript SDK v0.2.63 parity)
+- `supported_agents` control request on `ControlProtocol` and `Client` for querying available subagents (TypeScript SDK v0.2.63 parity)
+- `agents` field on `InitializationResult` returning `AgentInfo[]`
+- `fast_mode_state` field on `ResultMessage` (TypeScript SDK v0.2.63 parity)
+- `ElicitationCompleteMessage` for MCP elicitation completion events (TypeScript SDK v0.2.63 parity)
+- `LocalCommandOutputMessage` for local command output events (TypeScript SDK v0.2.63 parity)
+- `on_elicitation` option for handling MCP elicitation requests via callback (TypeScript SDK v0.2.63 parity)
+- `Elicitation` and `ElicitationResult` hook events with input types (TypeScript SDK v0.2.63 parity)
+- Elicitation control protocol handling with callback support and default decline behavior
+- `on_elicitation_complete` and `on_local_command_output` event handler methods
+- `tag` and `created_at` fields on `SessionInfo` (TypeScript SDK v0.2.75 parity)
+- `supports_auto_mode` field on `ModelInfo` (TypeScript SDK v0.2.75 parity)
+- `offset` parameter on `list_sessions` for pagination (TypeScript SDK v0.2.75 parity)
+- `rename_session(session_id, title)` for renaming session files (TypeScript SDK v0.2.74 parity)
+- `tag_session(session_id, tag)` for tagging sessions with Unicode sanitization (TypeScript SDK v0.2.75 parity)
+- `get_session_info(session_id)` for single-session lookup by UUID (TypeScript SDK v0.2.75 parity)
+- `agent_progress_summaries` option for periodic AI-generated progress summaries (TypeScript SDK v0.2.72 parity)
+- `prompt` field on `TaskStartedMessage` (TypeScript SDK v0.2.75 parity)
+- `summary` field on `TaskProgressMessage` for AI-generated progress summaries (TypeScript SDK v0.2.72 parity)
+- `fast_mode_state` field on `InitializationResult` (TypeScript SDK v0.2.75 parity)
+- RBS signatures for all new types, fields, and methods
+
+### Removed
+- `get_settings` from SPEC.md — not in TypeScript SDK public API (`sdk.d.ts`)
+
 ## [0.7.12] - 2026-02-27
 
 ### Added

data/CLAUDE.md

@@ -17,6 +17,7 @@ bin/setup                          # Install dependencies
 bundle exec rake                   # Run unit tests + rbs + rubocop (default)
 bundle exec rake test              # Unit tests only
 bundle exec rake test_integration  # Integration tests (requires CLI v2.0.0+)
+bundle exec rake test_smoke        # Smoke tests against local LLM (e.g. Ollama)
 bundle exec rake test_all          # All tests (requires CLI v2.0.0+)
 bundle exec rake rbs               # Validate RBS signatures
 bundle exec rake rbs:parse         # RBS syntax check only (faster)
@@ -28,6 +29,7 @@ bin/console                        # IRB with gem loaded
 bin/test                           # Unit tests only
 bin/test-integration               # Integration tests
 bin/test-all                       # All tests
+bin/test-smoke                     # Smoke tests (Ollama)
 bin/rbs-validate                   # Validate RBS signatures
 bin/release VERSION                # Release gem (e.g., bin/release 1.2.0)
 ```

data/README.md

@@ -501,6 +501,7 @@ result.error?          # Convenience method
 result.errors          # Array of error messages (if any)
 result.permission_denials  # Array of SDKPermissionDenial (if any)
 result.stop_reason     # Why the model stopped generating (e.g. "end_turn", "tool_use")
+result.fast_mode_state # Fast mode status (if applicable)
 ```
 
 ### UserMessageReplay
@@ -690,6 +691,27 @@ Suggested follow-up prompts (requires `prompt_suggestions: true`):
 suggestion.suggestion  # The suggested prompt text
 ```
 
+### ElicitationCompleteMessage
+
+MCP elicitation completion:
+
+```ruby
+elicitation.uuid             # Message UUID
+elicitation.session_id       # Session identifier
+elicitation.mcp_server_name  # MCP server that requested elicitation
+elicitation.elicitation_id   # Elicitation identifier
+```
+
+### LocalCommandOutputMessage
+
+Local command output:
+
+```ruby
+output.uuid        # Message UUID
+output.session_id  # Session identifier
+output.content     # Command output content
+```
+
 ### GenericMessage
 
 Wraps unknown/future message types instead of raising errors:
@@ -1084,6 +1106,27 @@ update = ClaudeAgent::PermissionUpdate.new(
 )
 ```
 
+## MCP Elicitation
+
+Handle MCP server elicitation requests (e.g. OAuth flows, form input):
+
+```ruby
+options = ClaudeAgent::Options.new(
+  on_elicitation: ->(request, signal:) {
+    # request contains: server_name, message, mode, url, elicitation_id, requested_schema
+    case request[:mode]
+    when "oauth"
+      # Handle OAuth flow
+      { action: "accept", content: { token: "..." } }
+    else
+      { action: "decline" }
+    end
+  }
+)
+```
+
+Without `on_elicitation`, all elicitation requests are declined by default.
+
 ## Error Handling
 
 The SDK provides specific error types:
@@ -1213,6 +1256,7 @@ client.cumulative_usage      # CumulativeUsage with totals across all turns
 # Query capabilities
 client.supported_commands.each { |cmd| puts "#{cmd.name}: #{cmd.description}" }
 client.supported_models.each { |model| puts "#{model.value}: #{model.display_name}" }
+client.supported_agents.each { |agent| puts "#{agent.name}: #{agent.description}" }
 client.mcp_server_status.each { |s| puts "#{s.name}: #{s.status}" }
 puts client.account_info.email
 
@@ -1391,7 +1435,7 @@ 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 (immutable, post-turn)            |
+| `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                              |
@@ -1400,6 +1444,7 @@ session = ClaudeAgent.unstable_v2_create_session(options)
 | `EventHandler`           | Typed event callback registry                                                    |
 | `SlashCommand`           | Available slash commands (name, description, argument_hint)                      |
 | `ModelInfo`              | Available models (value, display_name, description)                              |
+| `AgentInfo`              | Available agents (name, description, model)                                      |
 | `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)                    |

data/Rakefile

@@ -35,6 +35,23 @@ task :test_integration do
   Rake::Task[:_integration].invoke
 end
 
+# Internal task for running smoke tests
+Minitest::TestTask.create(:_smoke) do |t|
+  t.test_globs = [ "test/smoke/**/test_*.rb" ]
+  t.warning = false
+end
+
+# Smoke tests - wrapper that sets INTEGRATION + SMOKE + Ollama defaults
+desc "Run smoke tests against local LLM (e.g. Ollama)"
+task :test_smoke do
+  ENV["INTEGRATION"] = "true"
+  ENV["SMOKE"] = "true"
+  ENV["ANTHROPIC_BASE_URL"] ||= "http://localhost:11434"
+  ENV["ANTHROPIC_API_KEY"] ||= "ollama"
+  ENV["ANTHROPIC_AUTH_TOKEN"] ||= "ollama"
+  Rake::Task[:_smoke].invoke
+end
+
 require "rubocop/rake_task"
 
 RuboCop::RakeTask.new