claude-agent-sdk 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +95 -71
  3. data/README.md +40 -40
  4. data/UPGRADING-1.0.md +1 -1
  5. data/docs/client.md +1 -1
  6. data/docs/configuration.md +6 -6
  7. data/docs/errors.md +2 -2
  8. data/docs/hooks-and-permissions.md +36 -7
  9. data/docs/mcp-servers.md +1 -1
  10. data/docs/observability.md +1 -1
  11. data/docs/rails.md +5 -5
  12. data/docs/sessions.md +1 -1
  13. data/docs/subagents.md +1 -1
  14. data/docs/types.md +2 -2
  15. data/lib/claude_agent_sdk/cli_installer.rb +1 -1
  16. data/lib/claude_agent_sdk/command_builder.rb +48 -130
  17. data/lib/claude_agent_sdk/option_forms.rb +379 -0
  18. data/lib/claude_agent_sdk/query/run_lifecycle.rb +373 -0
  19. data/lib/claude_agent_sdk/query.rb +95 -516
  20. data/lib/claude_agent_sdk/session_assembly.rb +311 -0
  21. data/lib/claude_agent_sdk/session_resume.rb +4 -4
  22. data/lib/claude_agent_sdk/subprocess_cli_transport.rb +10 -9
  23. data/lib/claude_agent_sdk/types/hooks.rb +378 -243
  24. data/lib/claude_agent_sdk/types/messages.rb +14 -3
  25. data/lib/claude_agent_sdk/version.rb +1 -1
  26. data/lib/claude_agent_sdk.rb +163 -406
  27. data/lib/generators/claude_agent_sdk/install/install_generator.rb +1 -1
  28. data/lib/generators/claude_agent_sdk/install/templates/claude_agent_sdk.rb.tt +1 -1
  29. data/sig/claude_agent_sdk/types/hooks.rbs +286 -3
  30. data/sig/claude_agent_sdk/types/messages.rbs +15 -0
  31. metadata +9 -6
data/README.md CHANGED
@@ -1,22 +1,22 @@
1
- ![Claude Agent SDK for Ruby — a ruby connecting code to terminal, tools, and messages](https://raw.githubusercontent.com/ya-luotao/claude-agent-sdk-ruby/main/assets/readme-banner.webp)
1
+ ![Claude Agent SDK for Ruby — a ruby connecting code to terminal, tools, and messages](https://raw.githubusercontent.com/rubycatco/claude-agent-sdk-ruby/main/assets/readme-banner.webp)
2
2
 
3
3
  # Claude Agent SDK for Ruby
4
4
 
5
5
  [![Gem Version](https://img.shields.io/gem/v/claude-agent-sdk)](https://rubygems.org/gems/claude-agent-sdk)
6
- [![CI](https://github.com/ya-luotao/claude-agent-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/ya-luotao/claude-agent-sdk-ruby/actions/workflows/ci.yml)
6
+ [![CI](https://github.com/rubycatco/claude-agent-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/rubycatco/claude-agent-sdk-ruby/actions/workflows/ci.yml)
7
7
  [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D)](https://www.ruby-lang.org/)
8
8
  [![Docs](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://rubydoc.info/gems/claude-agent-sdk)
9
- [![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/LICENSE)
9
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/LICENSE)
10
10
 
11
11
  A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-overview) agent runtime, built for running agents in production Ruby and Rails apps. It has the same capabilities as the official [TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript) and [Python](https://github.com/anthropics/claude-agent-sdk-python) SDKs, plus what a Rails deploy needs around them: a generator and CLI-vendoring rake task, callbacks that are safe to touch ActiveRecord from, a pinned CLI binary, built-in OpenTelemetry tracing, and transcript mirroring to your own storage.
12
12
 
13
- > **Unofficial and community-maintained.** This project is not affiliated with or supported by Anthropic. It tracks the official SDKs release by release; see the [CHANGELOG](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CHANGELOG.md) for the currently synced version.
13
+ > **Unofficial and community-maintained.** This project is not affiliated with or supported by Anthropic. It tracks the official SDKs release by release; see the [CHANGELOG](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/CHANGELOG.md) for the currently synced version.
14
14
 
15
- > **Upgrading from 0.x?** 1.0 raises on unknown keys, limits `#[]` to attributes and adds `SessionStoreError`. [UPGRADING-1.0.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/UPGRADING-1.0.md) has the checklist.
15
+ > **Upgrading from 0.x?** 1.0 raises on unknown keys, limits `#[]` to attributes and adds `SessionStoreError`. [UPGRADING-1.0.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/UPGRADING-1.0.md) has the checklist.
16
16
 
17
17
  ## Highlights
18
18
 
19
- - **Rails integration.** `bin/rails generate claude_agent_sdk:install` writes the initializer and `bin/rails claude_agent_sdk:install_cli` vendors the CLI; [docs/rails.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/rails.md) covers jobs, ActionCable streaming, session resumption, and solid_queue fiber workers (`callback_scheduling: :inline`).
19
+ - **Rails integration.** `bin/rails generate claude_agent_sdk:install` writes the initializer and `bin/rails claude_agent_sdk:install_cli` vendors the CLI; [docs/rails.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/rails.md) covers jobs, ActionCable streaming, session resumption, and solid_queue fiber workers (`callback_scheduling: :inline`).
20
20
  - **Callbacks that are safe around ActiveRecord.** Tool handlers, hooks, permission callbacks, and message blocks run on a plain thread by default, outside the SDK's fiber scheduler, so thread-keyed libraries (ActiveRecord, `pg`, per-thread caches) behave as they do everywhere else in your app. `ClaudeAgentSDK::Railtie.callback_wrapper` runs them in the Rails executor so connections go back to the pool, without deadlocking development code reloading.
21
21
  - **Hermetic deploys.** `CLIInstaller` vendors a checksum-verified CLI binary, pinned to the version each gem release is tested with, so production never depends on a global `npm install`.
22
22
  - **Built-in OpenTelemetry observer** with Langfuse support; no third-party instrumentation library required.
@@ -24,7 +24,7 @@ A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-ove
24
24
  - **Same wire protocol as the official SDKs.** Spawns the `claude` CLI as a subprocess and speaks stream-JSON over stdin/stdout, so every feature of the runtime is available: sessions, subagents, sandboxing, structured output, file checkpointing and rewind.
25
25
  - **`query()` for one-shot calls, `Client` for bidirectional sessions** with interrupts, mid-session model switching, and streaming input from any `Enumerator`.
26
26
  - **In-process custom tools.** Define tools as Ruby blocks; they run inside your process with direct access to your app state (SDK MCP servers), with JSON-Schema-validated arguments.
27
- - **All 27 hook events and permission callbacks** with typed inputs, so you can gate, audit, or rewrite every tool call.
27
+ - **All 33 hook events and permission callbacks** with typed inputs, so you can gate, audit, or rewrite every tool call.
28
28
  - **Pluggable transport** to run the CLI somewhere else (an E2B microVM, a container, over SSH).
29
29
 
30
30
  ## Installation
@@ -34,7 +34,7 @@ A Ruby SDK for the [Claude Code](https://docs.claude.com/en/docs/claude-code-ove
34
34
  gem 'claude-agent-sdk', '~> 1.0'
35
35
  ```
36
36
 
37
- Then `bundle install`, or install directly with `gem install claude-agent-sdk`. To track unreleased changes, point the Gemfile at GitHub: `gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'`.
37
+ Then `bundle install`, or install directly with `gem install claude-agent-sdk`. To track unreleased changes, point the Gemfile at GitHub: `gem 'claude-agent-sdk', github: 'rubycatco/claude-agent-sdk-ruby'`.
38
38
 
39
39
  **Prerequisites**
40
40
 
@@ -47,7 +47,7 @@ Then `bundle install`, or install directly with `gem install claude-agent-sdk`.
47
47
  ClaudeAgentSDK::CLIInstaller.install_pinned # => "/app/vendor/claude/claude"
48
48
  ```
49
49
 
50
- `install_pinned` installs `CLIInstaller::PINNED_CLI_VERSION`, so upgrading the gem carries the CLI forward with it; `CLIInstaller.install(version: 'x.y.z')` pins a version of your own. The vendored binary is found ahead of `PATH`, installs are idempotent and concurrency-safe, and a failed upgrade never breaks a working install. See [docs/cli-installer.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/cli-installer.md) for the full behaviour, supported platforms, and the CLI discovery order.
50
+ `install_pinned` installs `CLIInstaller::PINNED_CLI_VERSION`, so upgrading the gem carries the CLI forward with it; `CLIInstaller.install(version: 'x.y.z')` pins a version of your own. The vendored binary is found ahead of `PATH`, installs are idempotent and concurrency-safe, and a failed upgrade never breaks a working install. See [docs/cli-installer.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/cli-installer.md) for the full behaviour, supported platforms, and the CLI discovery order.
51
51
 
52
52
  ### Authentication
53
53
 
@@ -57,7 +57,7 @@ The SDK holds no credentials of its own. The `claude` process it starts authenti
57
57
  - `CLAUDE_CODE_OAUTH_TOKEN`, a long-lived token for a Claude subscription (`claude setup-token` creates one), set the same way
58
58
  - a login the CLI has already stored for the user your process runs as (`claude auth login`)
59
59
 
60
- A machine with none of them, such as a fresh container or a CI runner, does not fail at startup. The first prompt comes back as an `AssistantMessage` whose `error` is `'authentication_failed'` (its text is "Not logged in · Please run /login", a command an SDK host cannot run), followed by a `ResultMessage` with `is_error` set. `query()` and `ask` then raise `ResultError` with `terminal_reason == 'api_error'`; a `Client` session stays open, so check the result's `is_error` there. A key or token the API rejects ends the same way, with `api_error_status` 401, but only after the CLI has retried: watch for `APIRetryMessage` (ten of them over about three minutes when tested) rather than waiting for the error. [docs/errors.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/errors.md) shows how to handle both.
60
+ A machine with none of them, such as a fresh container or a CI runner, does not fail at startup. The first prompt comes back as an `AssistantMessage` whose `error` is `'authentication_failed'` (its text is "Not logged in · Please run /login", a command an SDK host cannot run), followed by a `ResultMessage` with `is_error` set. `query()` and `ask` then raise `ResultError` with `terminal_reason == 'api_error'`; a `Client` session stays open, so check the result's `is_error` there. A key or token the API rejects ends the same way, with `api_error_status` 401, but only after the CLI has retried: watch for `APIRetryMessage` (ten of them over about three minutes when tested) rather than waiting for the error. [docs/errors.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/errors.md) shows how to handle both.
61
61
 
62
62
  ### Rails in a minute
63
63
 
@@ -81,7 +81,7 @@ class SummarizeTicketJob < ApplicationJob
81
81
  end
82
82
  ```
83
83
 
84
- The block runs on a plain thread, so ActiveRecord calls inside it just work. [docs/rails.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/rails.md) continues with multi-turn sessions, ActionCable streaming, and fiber workers.
84
+ The block runs on a plain thread, so ActiveRecord calls inside it just work. [docs/rails.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/rails.md) continues with multi-turn sessions, ActionCable streaming, and fiber workers.
85
85
 
86
86
  ## Quick Start
87
87
 
@@ -100,7 +100,7 @@ end
100
100
  puts result
101
101
  ```
102
102
 
103
- It raises the same errors as `query()` (see [docs/errors.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/errors.md)), plus `CLIConnectionError` if the stream ends without a result.
103
+ It raises the same errors as `query()` (see [docs/errors.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/errors.md)), plus `CLIConnectionError` if the stream ends without a result.
104
104
 
105
105
  ### `query()` — one-shot and streaming
106
106
 
@@ -159,7 +159,7 @@ ensure
159
159
  end
160
160
  ```
161
161
 
162
- See [docs/client.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/client.md) for `interrupt`, mid-session model and permission switching, MCP status, and custom transports.
162
+ See [docs/client.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/client.md) for `interrupt`, mid-session model and permission switching, MCP status, and custom transports.
163
163
 
164
164
  ### Custom tools (SDK MCP servers)
165
165
 
@@ -178,11 +178,11 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
178
178
  )
179
179
  ```
180
180
 
181
- A String return is sent to Claude as a single text block. Return a Hash instead (`{ content: [...], is_error: true }`) to flag an error, attach `structured_content:`, or send several content blocks or images. Arguments are validated against the tool's JSON Schema before your handler runs, and handler exceptions are reported back to the model in-band so it can self-correct. See [docs/mcp-servers.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/mcp-servers.md) for resources, prompts, mixed SDK + external servers, and schema details.
181
+ A String return is sent to Claude as a single text block. Return a Hash instead (`{ content: [...], is_error: true }`) to flag an error, attach `structured_content:`, or send several content blocks or images. Arguments are validated against the tool's JSON Schema before your handler runs, and handler exceptions are reported back to the model in-band so it can self-correct. See [docs/mcp-servers.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/mcp-servers.md) for resources, prompts, mixed SDK + external servers, and schema details.
182
182
 
183
183
  ### Hooks and permission callbacks
184
184
 
185
- Hooks run your Ruby code at any of the 27 lifecycle events (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`, …) with typed inputs. Permission callbacks decide programmatically whether a tool call may proceed.
185
+ Hooks run your Ruby code at any of the 33 lifecycle events (`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`, …) with typed inputs. Permission callbacks decide programmatically whether a tool call may proceed.
186
186
 
187
187
  ```ruby
188
188
  options = ClaudeAgentSDK::ClaudeAgentOptions.new(
@@ -191,39 +191,39 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
191
191
  )
192
192
  ```
193
193
 
194
- See [docs/hooks-and-permissions.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/hooks-and-permissions.md) for the full event list and worked examples.
194
+ See [docs/hooks-and-permissions.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/hooks-and-permissions.md) for the full event list and worked examples.
195
195
 
196
196
  ## Documentation
197
197
 
198
198
  | Topic | Guide |
199
199
  |-------|-------|
200
- | `Client` advanced features and custom transports | [docs/client.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/client.md) |
201
- | SDK MCP servers: tools, resources, prompts, schema compatibility | [docs/mcp-servers.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/mcp-servers.md) |
202
- | All hook events, typed inputs, permission callbacks | [docs/hooks-and-permissions.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/hooks-and-permissions.md) |
203
- | Structured output, thinking, budget, fallback and advisor models, sandbox, bare mode, session isolation, checkpointing | [docs/configuration.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/configuration.md) |
204
- | Every `ClaudeAgentOptions` attribute: type, default, and the CLI flag or protocol field it becomes; environment variables | [docs/options.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/options.md) |
205
- | Session listing, reading, renaming, tagging, forking, resume-at-message | [docs/sessions.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/sessions.md) |
206
- | Subagent capabilities, event contracts, and minimal example | [docs/subagents.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/subagents.md) |
207
- | OpenTelemetry tracing, Langfuse, custom observers | [docs/observability.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/observability.md) |
208
- | Rails: generator, `install_cli` task, callback wrapper, fiber safety, solid_queue fiber workers, ActionCable, jobs | [docs/rails.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/rails.md) |
209
- | Vendoring a pinned CLI binary and CLI discovery order | [docs/cli-installer.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/cli-installer.md) |
210
- | Hash-key rule, attribute access, and the message, content block, and configuration type reference | [docs/types.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/types.md) |
211
- | Error handling, exception hierarchy, timeouts | [docs/errors.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/errors.md) |
200
+ | `Client` advanced features and custom transports | [docs/client.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/client.md) |
201
+ | SDK MCP servers: tools, resources, prompts, schema compatibility | [docs/mcp-servers.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/mcp-servers.md) |
202
+ | All hook events, typed inputs, permission callbacks | [docs/hooks-and-permissions.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/hooks-and-permissions.md) |
203
+ | Structured output, thinking, budget, fallback and advisor models, sandbox, bare mode, session isolation, checkpointing | [docs/configuration.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/configuration.md) |
204
+ | Every `ClaudeAgentOptions` attribute: type, default, and the CLI flag or protocol field it becomes; environment variables | [docs/options.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/options.md) |
205
+ | Session listing, reading, renaming, tagging, forking, resume-at-message | [docs/sessions.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/sessions.md) |
206
+ | Subagent capabilities, event contracts, and minimal example | [docs/subagents.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/subagents.md) |
207
+ | OpenTelemetry tracing, Langfuse, custom observers | [docs/observability.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/observability.md) |
208
+ | Rails: generator, `install_cli` task, callback wrapper, fiber safety, solid_queue fiber workers, ActionCable, jobs | [docs/rails.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/rails.md) |
209
+ | Vendoring a pinned CLI binary and CLI discovery order | [docs/cli-installer.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/cli-installer.md) |
210
+ | Hash-key rule, attribute access, and the message, content block, and configuration type reference | [docs/types.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/types.md) |
211
+ | Error handling, exception hierarchy, timeouts | [docs/errors.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/errors.md) |
212
212
 
213
213
  API reference: [rubydoc.info/gems/claude-agent-sdk](https://rubydoc.info/gems/claude-agent-sdk). Available built-in tools: [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude).
214
214
 
215
215
  ## Examples
216
216
 
217
- Runnable scripts live in [`examples/`](https://github.com/ya-luotao/claude-agent-sdk-ruby/tree/main/examples).
217
+ Runnable scripts live in [`examples/`](https://github.com/rubycatco/claude-agent-sdk-ruby/tree/main/examples).
218
218
 
219
219
  | Area | Examples |
220
220
  |------|----------|
221
- | Getting started | [quick_start](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/quick_start.rb) · [client](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/client_example.rb) · [streaming_input](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/streaming_input_example.rb) · [message_types](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/message_types_example.rb) · [error_handling](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/error_handling_example.rb) |
222
- | Sessions and output | [session_resumption](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb) · [structured_output](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb) · [extended_thinking](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/extended_thinking_example.rb) · [session_stores/](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md) |
223
- | Tools and MCP | [mcp_calculator](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_calculator.rb) · [mcp_resources_prompts](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_resources_prompts_example.rb) · [http_mcp_server](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/http_mcp_server_example.rb) |
224
- | Hooks and permissions | [hooks](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb) · [advanced_hooks](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb) · [lifecycle_hooks](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb) · [permission_callback](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb) |
225
- | Models and limits | [budget_control](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/budget_control_example.rb) · [fallback_model](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb) · [advisor](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advisor_example.rb) · [bare_mode](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb) · [sandbox](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/sandbox_example.rb) |
226
- | Rails, observability, transports | [rails_actioncable](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_actioncable_example.rb) · [rails_background_job](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_background_job_example.rb) · [otel_langfuse](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/otel_langfuse_example.rb) · [e2b_transport](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/e2b_transport_example.rb) |
221
+ | Getting started | [quick_start](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/quick_start.rb) · [client](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/client_example.rb) · [streaming_input](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/streaming_input_example.rb) · [message_types](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/message_types_example.rb) · [error_handling](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/error_handling_example.rb) |
222
+ | Sessions and output | [session_resumption](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb) · [structured_output](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb) · [extended_thinking](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/extended_thinking_example.rb) · [session_stores/](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md) |
223
+ | Tools and MCP | [mcp_calculator](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/mcp_calculator.rb) · [mcp_resources_prompts](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/mcp_resources_prompts_example.rb) · [http_mcp_server](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/http_mcp_server_example.rb) |
224
+ | Hooks and permissions | [hooks](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb) · [advanced_hooks](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb) · [lifecycle_hooks](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb) · [permission_callback](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb) |
225
+ | Models and limits | [budget_control](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/budget_control_example.rb) · [fallback_model](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb) · [advisor](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/advisor_example.rb) · [bare_mode](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb) · [sandbox](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/sandbox_example.rb) |
226
+ | Rails, observability, transports | [rails_actioncable](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/rails_actioncable_example.rb) · [rails_background_job](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/rails_background_job_example.rb) · [otel_langfuse](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/otel_langfuse_example.rb) · [e2b_transport](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/e2b_transport_example.rb) |
227
227
 
228
228
  ## Comparison with the official SDKs
229
229
 
@@ -235,7 +235,7 @@ All three SDKs drive the same CLI over the same protocol, so capabilities line u
235
235
  | Bidirectional `Client` | ✅ | ✅ | ✅ |
236
236
  | Streaming input | `AsyncIterable` | `AsyncIterable` | `Enumerator` |
237
237
  | Custom tools (SDK MCP servers) | `tool()` | `@tool` decorator | `create_tool` block |
238
- | Hooks (all 27 events) | ✅ | 10 typed, the rest by name | ✅ |
238
+ | Hooks (all 33 events) | ✅ | 10 typed, the rest by name | ✅ |
239
239
  | Permission callbacks | ✅ | ✅ | ✅ |
240
240
  | Structured output | ✅ | ✅ | ✅ |
241
241
  | All 28 message types | ✅ | partial | ✅ |
@@ -256,7 +256,7 @@ Types are plain Ruby classes with `attr_accessor` and keyword arguments, mirrori
256
256
  This repository is also a Claude Code plugin marketplace. The bundled skill teaches Claude Code the gem's APIs and patterns:
257
257
 
258
258
  ```bash
259
- /plugin marketplace add ya-luotao/claude-agent-sdk-ruby
259
+ /plugin marketplace add rubycatco/claude-agent-sdk-ruby
260
260
  /plugin install claude-agent-ruby@claude-agent-sdk-ruby
261
261
  ```
262
262
 
@@ -272,12 +272,12 @@ RUN_INTEGRATION=1 bundle exec rspec # also run the real-CLI integration suite (
272
272
  BUNDLE_GEMFILE=gemfiles/rails_8.gemfile bundle exec rspec --options spec/rails/.rspec # Rails integration specs
273
273
  ```
274
274
 
275
- CI runs the suite and RuboCop on Ruby 3.2, 3.3, 3.4 and 4.0 on Linux, the suite on macOS, and the Rails specs against Rails 7.1 and 8, validates the RBS signatures and runs the suite under RBS runtime type checking. Weekly, and on PRs that touch the installer, the transport, `Query` or the message parser, it runs a keyless smoke test against the pinned CLI, and the integration suite as well when the repository has an API key. The gem ships RBS signatures for its public API in `sig/`, which Steep and other RBS tools pick up through `rbs collection`. See [CONTRIBUTING.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md) for the development setup and [spec/README.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/spec/README.md) for the test layout.
275
+ CI runs the suite and RuboCop on Ruby 3.2, 3.3, 3.4 and 4.0 on Linux, the suite on macOS, and the Rails specs against Rails 7.1 and 8, validates the RBS signatures and runs the suite under RBS runtime type checking. Weekly, and on PRs that touch the installer, the transport, `Query` or the message parser, it runs a keyless smoke test against the pinned CLI, and the integration suite as well when the repository has an API key. The gem ships RBS signatures for its public API in `sig/`, which Steep and other RBS tools pick up through `rbs collection`. See [CONTRIBUTING.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md) for the development setup and [spec/README.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/spec/README.md) for the test layout.
276
276
 
277
277
  ## Contributing
278
278
 
279
- Bug reports and pull requests are welcome on [GitHub](https://github.com/ya-luotao/claude-agent-sdk-ruby/issues). Please include a failing spec with bug reports where possible, and keep pull requests focused on one change; [CONTRIBUTING.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md) has the details. Report security vulnerabilities privately, as described in [SECURITY.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/SECURITY.md). Releases follow [Semantic Versioning](https://semver.org/) and are recorded in the [CHANGELOG](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CHANGELOG.md).
279
+ Bug reports and pull requests are welcome on [GitHub](https://github.com/rubycatco/claude-agent-sdk-ruby/issues). Please include a failing spec with bug reports where possible, and keep pull requests focused on one change; [CONTRIBUTING.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md) has the details. Report security vulnerabilities privately, as described in [SECURITY.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/SECURITY.md). Releases follow [Semantic Versioning](https://semver.org/) and are recorded in the [CHANGELOG](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/CHANGELOG.md).
280
280
 
281
281
  ## License
282
282
 
283
- Released under the [MIT License](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/LICENSE).
283
+ Released under the [MIT License](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/LICENSE).
data/UPGRADING-1.0.md CHANGED
@@ -114,7 +114,7 @@ No breaking changes within 1.x to the public API: everything documented in
114
114
  YARD docs that is not tagged `@api private`. `@api private` objects (`Query`,
115
115
  `MessageParser`, `FiberBoundary`, the `Sessions*` modules, ...) stay callable
116
116
  but can change in any release. See
117
- [CONTRIBUTING.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md#what-is-public-api).
117
+ [CONTRIBUTING.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md#what-is-public-api).
118
118
 
119
119
  A removal is first deprecated in a minor release with a one-time warning that
120
120
  names the replacement, and happens in the next major.
data/docs/client.md CHANGED
@@ -158,7 +158,7 @@ Resuming from a `session_store` is not available over a custom transport, throug
158
158
 
159
159
  ### Reference: running `claude` inside an E2B sandbox
160
160
 
161
- [`examples/e2b_transport_example.rb`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/e2b_transport_example.rb) is a working transport that runs the Claude Code CLI inside an [E2B](https://e2b.dev) Firecracker microVM instead of on your host. The wire protocol stays identical — only the I/O layer changes:
161
+ [`examples/e2b_transport_example.rb`](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/e2b_transport_example.rb) is a working transport that runs the Claude Code CLI inside an [E2B](https://e2b.dev) Firecracker microVM instead of on your host. The wire protocol stays identical — only the I/O layer changes:
162
162
 
163
163
  ```
164
164
  ClaudeAgentSDK::Client (host)
data/docs/configuration.md CHANGED
@@ -37,7 +37,7 @@ end
37
37
 
38
38
  In the `output_format` Hash, `type` may be a String or a Symbol (`type: :json_schema`), and the keys Symbols or Strings.
39
39
 
40
- See [examples/structured_output_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb).
40
+ See [examples/structured_output_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/structured_output_example.rb).
41
41
 
42
42
  ## Thinking Configuration
43
43
 
@@ -117,7 +117,7 @@ ClaudeAgentSDK.query(prompt: "Explain recursion", options: options) do |message|
117
117
  end
118
118
  ```
119
119
 
120
- See [examples/budget_control_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/budget_control_example.rb).
120
+ See [examples/budget_control_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/budget_control_example.rb).
121
121
 
122
122
  ## Fallback Model
123
123
 
@@ -128,7 +128,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
128
128
  )
129
129
  ```
130
130
 
131
- See [examples/fallback_model_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb).
131
+ See [examples/fallback_model_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/fallback_model_example.rb).
132
132
 
133
133
  ## Advisor Model
134
134
 
@@ -162,7 +162,7 @@ Notes:
162
162
  - `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1` (settable via `options.env`) disables
163
163
  the advisor tool entirely; a configured `advisor_model` is then ignored.
164
164
 
165
- See [examples/advisor_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advisor_example.rb) and the
165
+ See [examples/advisor_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/advisor_example.rb) and the
166
166
  [advisor documentation](https://code.claude.com/docs/en/advisor).
167
167
 
168
168
  ## Beta Features
@@ -260,7 +260,7 @@ sandbox = ClaudeAgentSDK::SandboxSettings.new(enabled: true, fail_if_unavailable
260
260
 
261
261
  Without it, the sign is the CLI's warning on stderr ("Sandbox disabled: ... Commands will run WITHOUT sandboxing. Network and filesystem restrictions will NOT be enforced."), and stderr reaches your code only through the `stderr` (or `debug_stderr`) option. This is the CLI's own description of its behavior: the fallback has not been reproduced in this SDK's testing, where the sandbox was always available.
262
262
 
263
- See [examples/sandbox_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/sandbox_example.rb).
263
+ See [examples/sandbox_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/sandbox_example.rb).
264
264
 
265
265
  When the `sandbox:` option enabled the sandbox and the CLI reports `Sandbox disabled: …` on its stderr, the SDK repeats that line as a Ruby warning prefixed `[claude-agent-sdk]`, once per session, whether or not you set `stderr:`.
266
266
 
@@ -293,7 +293,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
293
293
 
294
294
  **What still works:** skills (via `/skill-name`), explicit `--add-dir` CLAUDE.md, `--settings`, `--mcp-config`, `--agents`, `--plugin-dir`, API key from `ANTHROPIC_API_KEY` env var.
295
295
 
296
- See [examples/bare_mode_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb).
296
+ See [examples/bare_mode_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb).
297
297
 
298
298
  ## Verbatim Prompts
299
299
 
data/docs/errors.md CHANGED
@@ -18,7 +18,7 @@ ClaudeAgentSDK.query(prompt: "Hello") do |message|
18
18
  end
19
19
  ```
20
20
 
21
- See [examples/error_handling_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/error_handling_example.rb).
21
+ See [examples/error_handling_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/error_handling_example.rb).
22
22
 
23
23
  ## Exception Handling
24
24
 
@@ -196,4 +196,4 @@ end
196
196
  | `CLIJSONDecodeError` | JSON parsing issues — including stdout ending mid-frame (a truncated final message; `line` holds the partial frame) |
197
197
  | `MessageParseError` | Message parsing issues |
198
198
 
199
- See [lib/claude_agent_sdk/errors.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/errors.rb) for all error types.
199
+ See [lib/claude_agent_sdk/errors.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/errors.rb) for all error types.
data/docs/hooks-and-permissions.md CHANGED
@@ -6,12 +6,14 @@ A **hook** is a Ruby proc/lambda that the Claude Code *application* (*not* Claud
6
6
 
7
7
  ### Supported Events
8
8
 
9
- All hook input objects include common fields like `session_id`, `transcript_path`, `cwd`, and `permission_mode`.
9
+ All hook input objects include the common fields `session_id`, `transcript_path`, `cwd`, `permission_mode`, `prompt_id` (the UUID of the prompt being processed, also the `prompt.id` of the CLI's OpenTelemetry events) and `effort` (the turn's reasoning effort, e.g. `{ level: "high" }`, on models that support it), plus `raw_input`: the payload exactly as the CLI sent it, Symbol keys included. A field the CLI sends that this SDK version has no reader for is still in `raw_input`.
10
10
 
11
11
  - `PreToolUse` → `PreToolUseHookInput` (`tool_name`, `tool_input`, `tool_use_id`)
12
- - `PostToolUse` → `PostToolUseHookInput` (`tool_name`, `tool_input`, `tool_response`, `tool_use_id`)
13
- - `PostToolUseFailure` → `PostToolUseFailureHookInput` (`tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`)
14
- - `UserPromptSubmit` → `UserPromptSubmitHookInput` (`prompt`)
12
+ - `PostToolUse` → `PostToolUseHookInput` (`tool_name`, `tool_input`, `tool_response`, `tool_use_id`, `duration_ms`)
13
+ - `PostToolUseFailure` → `PostToolUseFailureHookInput` (`tool_name`, `tool_input`, `tool_use_id`, `error`, `is_interrupt`, `duration_ms`)
14
+ - `PostToolBatch` → `PostToolBatchHookInput` (`tool_calls`)
15
+ - `UserPromptSubmit` → `UserPromptSubmitHookInput` (`prompt`, `session_title`, `source`)
16
+ - `UserPromptExpansion` → `UserPromptExpansionHookInput` (`expansion_type`, `command_name`, `command_args`, `command_source`, `prompt`)
15
17
  - `Stop` → `StopHookInput` (`stop_hook_active`, `last_assistant_message`, `background_tasks`, `session_crons`)
16
18
  - `SubagentStop` → `SubagentStopHookInput` (`stop_hook_active`, `agent_id`, `agent_transcript_path`, `agent_type`, `last_assistant_message`, `background_tasks`, `session_crons`)
17
19
  - `PreCompact` → `PreCompactHookInput` (`trigger`, `custom_instructions`)
@@ -21,7 +23,7 @@ All hook input objects include common fields like `session_id`, `transcript_path
21
23
 
22
24
  `tool_input` (and the `input` a [permission callback](#permission-callbacks) receives) is the CLI's Hash passed through unchanged, so its keys are Symbols spelled as on the wire: `tool_input[:command]`, `input[:file_path]`. See [Hash keys](types.md#hash-keys).
23
25
 
24
- All 27 hook events have typed input classes. See [`ClaudeAgentSDK::HOOK_EVENTS`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types/hooks.rb) and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
26
+ All 33 hook events have typed input classes (an event this SDK version does not know arrives as an `UnknownHookInput`, with its payload in `raw_input`). See [`ClaudeAgentSDK::HOOK_EVENTS`](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/lib/claude_agent_sdk/types/hooks.rb) and [examples/lifecycle_hooks_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
25
27
 
26
28
  `background_tasks` and `session_crons` are optional arrays of raw CLI hashes.
27
29
  `nil` means the CLI did not provide a snapshot; `[]` means it provided an empty
@@ -76,7 +78,7 @@ Async do
76
78
  end.wait
77
79
  ```
78
80
 
79
- See [examples/hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb), [examples/advanced_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb), and [examples/lifecycle_hooks_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
81
+ See [examples/hooks_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/hooks_example.rb), [examples/advanced_hooks_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/advanced_hooks_example.rb), and [examples/lifecycle_hooks_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/lifecycle_hooks_example.rb).
80
82
 
81
83
  ### Hook output
82
84
 
@@ -97,6 +99,33 @@ A callback returns a typed output (`AsyncHookJSONOutput`, or `SyncHookJSONOutput
97
99
  - The keys inside `updated_input`, `updated_tool_output`, `updated_mcp_tool_output` and a `PermissionRequest` `decision` are not renamed: those are the tool's own payloads (for `decision`, the CLI's), so spell them as the tool or the CLI does.
98
100
  - If one Hash spells the same field both ways, the CLI's spelling is the one sent (`permissionDecision` over `permission_decision`, `continue` over `continue_`).
99
101
 
102
+ The typed `hook_specific_output` classes, and the fields each one sends (a field left `nil` is not sent):
103
+
104
+ | Class | Fields |
105
+ |-------|--------|
106
+ | `PreToolUseHookSpecificOutput` | `permission_decision`, `permission_decision_reason`, `updated_input`, `additional_context` |
107
+ | `PostToolUseHookSpecificOutput` | `additional_context`, `updated_tool_output`, `updated_mcp_tool_output` |
108
+ | `PostToolUseFailureHookSpecificOutput` | `additional_context` |
109
+ | `PostToolBatchHookSpecificOutput` | `additional_context` |
110
+ | `UserPromptSubmitHookSpecificOutput` | `additional_context`, `session_title`, `suppress_original_prompt` |
111
+ | `UserPromptExpansionHookSpecificOutput` | `additional_context`, `suppress_original_prompt` |
112
+ | `SessionStartHookSpecificOutput` | `additional_context`, `initial_user_message`, `session_title`, `watch_paths`, `reload_skills` |
113
+ | `SetupHookSpecificOutput` | `additional_context` |
114
+ | `NotificationHookSpecificOutput` | `additional_context` |
115
+ | `SubagentStartHookSpecificOutput` | `additional_context` |
116
+ | `StopHookSpecificOutput` | `additional_context` (feedback the model acts on; the conversation continues) |
117
+ | `SubagentStopHookSpecificOutput` | `additional_context` (the same, for the subagent) |
118
+ | `PermissionRequestHookSpecificOutput` | `decision` |
119
+ | `PermissionDeniedHookSpecificOutput` | `retry` |
120
+ | `PreModelSwitchHookSpecificOutput` | `permission_decision` (`"allow"` / `"deny"`), `permission_decision_reason` |
121
+ | `PostModelSwitchHookSpecificOutput` | `additional_context` |
122
+ | `ElicitationHookSpecificOutput` | `action` (`"accept"` / `"decline"` / `"cancel"`), `content` |
123
+ | `ElicitationResultHookSpecificOutput` | `action`, `content` |
124
+ | `CwdChangedHookSpecificOutput` | `watch_paths` |
125
+ | `FileChangedHookSpecificOutput` | `watch_paths` |
126
+ | `WorktreeCreateHookSpecificOutput` | `worktree_path` |
127
+ | `MessageDisplayHookSpecificOutput` | `display_content` (changes the screen only, not the stored message) |
128
+
100
129
  ### Hook cancellation
101
130
 
102
131
  Dispatched hooks receive `HookContext#request_id` and `HookContext#signal`, using
@@ -148,7 +177,7 @@ Async do
148
177
  end.wait
149
178
  ```
150
179
 
151
- See [examples/permission_callback_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb).
180
+ See [examples/permission_callback_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb).
152
181
 
153
182
  ### Permission request cancellation
154
183
 
data/docs/mcp-servers.md CHANGED
@@ -222,4 +222,4 @@ are covered here too. For
222
222
  naming the exception class, and then the exception propagates as Ruby normally
223
223
  would.
224
224
 
225
- See [examples/mcp_calculator.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_calculator.rb) and [examples/mcp_resources_prompts_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/mcp_resources_prompts_example.rb) for complete examples.
225
+ See [examples/mcp_calculator.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/mcp_calculator.rb) and [examples/mcp_resources_prompts_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/mcp_resources_prompts_example.rb) for complete examples.
data/docs/observability.md CHANGED
@@ -204,4 +204,4 @@ end
204
204
  options = ClaudeAgentSDK::ClaudeAgentOptions.new(observers: [MyObserver.new])
205
205
  ```
206
206
 
207
- See [examples/otel_langfuse_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/otel_langfuse_example.rb) for a complete multi-tool example.
207
+ See [examples/otel_langfuse_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/otel_langfuse_example.rb) for a complete multi-tool example.
data/docs/rails.md CHANGED
@@ -356,7 +356,7 @@ end
356
356
 
357
357
  Preconditions, spelled out: `:inline` is only correct when the process satisfies the same requirements as solid_queue's fiber workers — `isolation_level = :fiber`, Rails 7.2+ for AR, and no thread-keyed libraries used inside callbacks without a fiber-aware wrapper. The SDK warns once if it detects `:inline` under `isolation_level == :thread`. Everything else (Puma request threads, threaded Sidekiq/solid_queue workers) should stay on the default `callback_scheduling: :thread`.
358
358
 
359
- Note that `SessionStore` adapter calls (`#append` / `#load`) stay on threads by default even in `:inline` mode — their timeouts are hard bounds (`Thread#join`) so a wedged store adapter can never stall the reactor. The exception is an adapter that declares itself fiber-native via an optional `callback_scheduling` method returning `:inline` (see "Fiber-native adapters" in [docs/sessions.md](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/docs/sessions.md)); its calls then run on the reactor under a cooperative timeout. In both cases a configured `callback_wrapper` composes around the adapter call inside the bound.
359
+ Note that `SessionStore` adapter calls (`#append` / `#load`) stay on threads by default even in `:inline` mode — their timeouts are hard bounds (`Thread#join`) so a wedged store adapter can never stall the reactor. The exception is an adapter that declares itself fiber-native via an optional `callback_scheduling` method returning `:inline` (see "Fiber-native adapters" in [docs/sessions.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/sessions.md)); its calls then run on the reactor under a cooperative timeout. In both cases a configured `callback_wrapper` composes around the adapter call inside the bound.
360
360
 
361
361
  ## ActionCable Streaming
362
362
 
@@ -541,7 +541,7 @@ end
541
541
  Then every `ClaudeAgentSDK.query` and `Client` session automatically gets traced — no per-call wiring needed. The lambda factory ensures each request gets its own observer with isolated span state, safe for concurrent Puma/Sidekiq workers.
542
542
 
543
543
  See:
544
- - [examples/rails_actioncable_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_actioncable_example.rb)
545
- - [examples/rails_background_job_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/rails_background_job_example.rb)
546
- - [examples/session_resumption_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb)
547
- - [examples/http_mcp_server_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/http_mcp_server_example.rb)
544
+ - [examples/rails_actioncable_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/rails_actioncable_example.rb)
545
+ - [examples/rails_background_job_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/rails_background_job_example.rb)
546
+ - [examples/session_resumption_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb)
547
+ - [examples/http_mcp_server_example.rb](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/http_mcp_server_example.rb)
data/docs/sessions.md CHANGED
@@ -398,7 +398,7 @@ end
398
398
  `InMemorySessionStore#append` is a working reference.
399
399
 
400
400
  Copy-in reference adapters for **S3, Redis, and Postgres** live in
401
- [`examples/session_stores/`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md), each with a
401
+ [`examples/session_stores/`](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/session_stores/README.md), each with a
402
402
  production checklist.
403
403
 
404
404
  #### Fiber-native adapters
data/docs/subagents.md CHANGED
@@ -158,7 +158,7 @@ See [hook fields and permission cancellation](hooks-and-permissions.md).
158
158
 
159
159
  ## Minimal example
160
160
 
161
- [`examples/subagent_status_example.rb`](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/subagent_status_example.rb)
161
+ [`examples/subagent_status_example.rb`](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/subagent_status_example.rb)
162
162
  defines a tool-free reviewer, registers lifecycle hooks, reads metadata, and
163
163
  prints task events and forwarded child text without building a status model:
164
164
 
data/docs/types.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Types Reference
2
2
 
3
- See [lib/claude_agent_sdk/types/](https://github.com/ya-luotao/claude-agent-sdk-ruby/tree/main/lib/claude_agent_sdk/types) for complete type definitions (one file per area; `types.rb` loads them all).
3
+ See [lib/claude_agent_sdk/types/](https://github.com/rubycatco/claude-agent-sdk-ruby/tree/main/lib/claude_agent_sdk/types) for complete type definitions (one file per area; `types.rb` loads them all).
4
4
 
5
5
  ## Hash keys
6
6
 
@@ -214,7 +214,7 @@ message types of their own.
214
214
 
215
215
  | Class | Wire type | Attributes | Notes |
216
216
  |-------|-----------|------------|-------|
217
- | `InitMessage` | `system` / `init` | `uuid`, `session_id`, `model`, `cwd`, `tools`, `mcp_servers`, `agents`, `skills`, `plugins`, `slash_commands`, `permission_mode`, `claude_code_version`, `api_key_source`, `betas`, `output_style`, `fast_mode_state` | Start of every turn, with the session as the CLI sees it (so a multi-query `Client` session receives one per query) |
217
+ | `InitMessage` | `system` / `init` | `uuid`, `session_id`, `model`, `cwd`, `tools`, `mcp_servers`, `agents`, `skills`, `plugins`, `plugin_errors`, `slash_commands`, `terminal_slash_commands`, `permission_mode`, `claude_code_version`, `api_key_source`, `betas`, `output_style`, `fast_mode_state`, `fast_mode_disabled_reason`, `capabilities` (protocol features such as `"interrupt_receipt_v1"`: test it instead of `claude_code_version`) | Start of every turn, with the session as the CLI sees it (so a multi-query `Client` session receives one per query) |
218
218
  | `CompactBoundaryMessage` | `system` / `compact_boundary` | `uuid`, `session_id`, `compact_metadata` (a `CompactMetadata`: `pre_tokens`, `post_tokens`, `trigger`, `preserved_segment`, `custom_instructions`) | Context compaction completed |
219
219
  | `StatusMessage` | `system` / `status` | `uuid`, `session_id`, `status`, `permission_mode` | Compacting status, permission mode changes |
220
220
  | `APIRetryMessage` | `system` / `api_retry` | `uuid`, `session_id`, `attempt`, `max_retries`, `retry_delay_ms`, `error_status`, `error` | The CLI is retrying an API request |
data/lib/claude_agent_sdk/cli_installer.rb CHANGED
@@ -53,7 +53,7 @@ module ClaudeAgentSDK
53
53
  # Single source of truth: bumped here (and only here) by
54
54
  # .github/workflows/cli-pin-bump.yml or a Python-sync release, so a
55
55
  # Dependabot bump of the gem carries the CLI forward with it.
56
- PINNED_CLI_VERSION = '2.1.288'
56
+ PINNED_CLI_VERSION = '2.1.295'
57
57
  # @api private
58
58
  BINARY_NAME = 'claude'
59
59
  # @api private