claude-agent-sdk 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54ece5b925722a884cb054583cd1d54307736c8491fa9452dfb46bd3b522bd9c
-  data.tar.gz: fc048c6247dc93e82be75ab1ce0a04bcf616409998c4c89ac8fb4defc1e83ae4
+  metadata.gz: a6fe812f6bded72a1c1adfc9175c56eee2fa8efa4e32775fe5c442543cee43cb
+  data.tar.gz: 846346fa31dea76200b96846058ab3bb92727ab1f2463a1672e1ca0848c881cc
 SHA512:
-  metadata.gz: 0bbd41108e645d575b0bc2603de574e4f727eb40a4cd9feabf111c11708196c0947ba7d492b870edfc7dbc7812e7166279aeecc3e6dc8bef7fa530baadfe694b
-  data.tar.gz: 676ef6b0dd2f168f73fd820fd33528729b02d96656140a7b340ade9a7548495354341949a84ede20a737a3ea2ce62bc0fe11adbb26225af3911661b7a72afdf1
+  metadata.gz: 1d057cc9e1b745c27f1b94c75193ba498f1eaac910409c916c4d1f64f0567bc21c62749bf019ac0c1b2fc99361c3e1f868b16b67a53c9fb0ad5e7e6b69b62ed0
+  data.tar.gz: 5dec34347fe3becfb005b9e1c0431c56b99f05383eaf17e6b9ac56379a2df0a7973972eeaa09b7e8ffd5c5ab318086753f6a39e19f841a3f0c98cded618f5fff

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-10-25
+
+### Added
+- **`ClaudeAgentOptions#process_group`** starts the CLI process in a process group of its own (issue #175). In a terminal, Ctrl-C signals the whole foreground process group, so the CLI used to get the SIGINT along with your process and end the turn on its own before your code could decide what to do. With `process_group: true` the terminal's Ctrl-C no longer reaches the CLI, and your process owns it: call `Client#interrupt` or `disconnect` from ordinary code (not from inside the signal trap, where Ruby raises `ThreadError`). Off by default, so nothing changes unless you set it. Sends nothing to the CLI; uses `pgroup: true` on Unix and `new_pgroup: true` on Windows, where it is untested. Teardown is unchanged: the SDK still signals the CLI process, not its group. Ruby only: the Python SDK's equivalent (PR #617) is unmerged as of 2026-10-25. [`docs/options.md`](docs/options.md#process_group) covers the trap pattern, when the CLI stops, and the background-group caveat for tools that read the terminal.
+
+### Changed
+- README: the Claude Code overview link (it led to a "Page not found" page) and the built-in tools link now point at `code.claude.com`. "Rails in a minute" is a section of its own after the Quick Start, and its job turns off auto-memory (`CLAUDE_CODE_DISABLE_AUTO_MEMORY`) as the Rails guide's does. The hooks example defines the two callbacks it passes, the custom-tool example runs a prompt, and the Examples table lists `subagent_status_example.rb`. What a session without credentials, or with a rejected key, returns is now described in a new "Authentication Failures" section of `docs/errors.md`.
+
 ## [1.3.0] - 2026-10-12
 
 ### Added

data/README.md

@@ -8,12 +8,10 @@
 [![Docs](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://rubydoc.info/gems/claude-agent-sdk)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/LICENSE)
 
-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.
+A Ruby SDK for the [Claude Code](https://code.claude.com/docs/en/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.
 
 > **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.
 
-> **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.
-
 ## Highlights
 
 - **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`).
@@ -36,6 +34,8 @@ gem 'claude-agent-sdk', '~> 1.0'
 
 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'`.
 
+> **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.
+
 **Prerequisites**
 
 - Ruby 3.2 or newer
@@ -57,31 +57,7 @@ The SDK holds no credentials of its own. The `claude` process it starts authenti
 - `CLAUDE_CODE_OAUTH_TOKEN`, a long-lived token for a Claude subscription (`claude setup-token` creates one), set the same way
 - a login the CLI has already stored for the user your process runs as (`claude auth login`)
 
-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.
-
-### Rails in a minute
-
-```bash
-bundle add claude-agent-sdk
-bin/rails generate claude_agent_sdk:install   # config/initializers/claude_agent_sdk.rb + .gitignore entry
-bin/rails claude_agent_sdk:install_cli        # the tested CLI into vendor/claude (also a Docker build step)
-```
-
-```ruby
-# app/jobs/summarize_ticket_job.rb
-class SummarizeTicketJob < ApplicationJob
-  def perform(ticket)
-    options = ClaudeAgentSDK::ClaudeAgentOptions.new(tools: [], max_turns: 1)
-    prompt = "Summarize this support ticket in two sentences:\n\n#{ticket.body}"
-
-    ClaudeAgentSDK.query(prompt: prompt, options: options) do |message|
-      ticket.update!(summary: message.result) if message.is_a?(ClaudeAgentSDK::ResultMessage)
-    end
-  end
-end
-```
-
-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.
+A machine with none of them, such as a fresh container or a CI runner, does not fail at startup: the first prompt fails instead, as a `ResultError` from `query()` and `ask` and as a `ResultMessage` with `is_error` set on a `Client`. [Authentication Failures](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/errors.md#authentication-failures) describes what arrives, for missing credentials and for a rejected key.
 
 ## Quick Start
 
@@ -176,6 +152,8 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
   mcp_servers: { tools: server },
   allowed_tools: ['mcp__tools__greet']
 )
+
+puts ClaudeAgentSDK.ask('Greet Alice with the greet tool', options: options).result
 ```
 
 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.
@@ -185,14 +163,58 @@ A String return is sent to Claude as a single text block. Return a Hash instead
 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.
 
 ```ruby
+# A PreToolUse hook: refuse any Bash command that contains `rm -rf`.
+block_rm_rf = lambda do |input, _tool_use_id, _context|
+  next {} unless input.tool_input[:command].to_s.include?('rm -rf')
+
+  { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny',
+                          permissionDecisionReason: 'rm -rf is not allowed' } }
+end
+
+# A permission callback: asked before a tool call that no rule already allows.
+protect_env_files = lambda do |tool_name, input, _context|
+  if tool_name == 'Write' && input[:file_path].to_s.end_with?('.env')
+    ClaudeAgentSDK::PermissionResultDeny.new(message: '.env files are off limits')
+  else
+    ClaudeAgentSDK::PermissionResultAllow.new
+  end
+end
+
 options = ClaudeAgentSDK::ClaudeAgentOptions.new(
-  hooks: { 'PreToolUse' => [ClaudeAgentSDK::HookMatcher.new(matcher: 'Bash', hooks: [my_hook])] },
-  can_use_tool: my_permission_callback
+  hooks: { 'PreToolUse' => [ClaudeAgentSDK::HookMatcher.new(matcher: 'Bash', hooks: [block_rm_rf])] },
+  can_use_tool: protect_env_files
 )
 ```
 
 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.
 
+## Rails in a minute
+
+```bash
+bundle add claude-agent-sdk
+bin/rails generate claude_agent_sdk:install   # config/initializers/claude_agent_sdk.rb + .gitignore entry
+bin/rails claude_agent_sdk:install_cli        # the tested CLI into vendor/claude (also a Docker build step)
+```
+
+```ruby
+# app/jobs/summarize_ticket_job.rb
+class SummarizeTicketJob < ApplicationJob
+  def perform(ticket)
+    options = ClaudeAgentSDK::ClaudeAgentOptions.new(
+      tools: [], max_turns: 1,                            # text only, no built-in tools
+      env: { 'CLAUDE_CODE_DISABLE_AUTO_MEMORY' => '1' }   # keeps one user's "remember…" out of the next user's session
+    )
+    prompt = "Summarize this support ticket in two sentences:\n\n#{ticket.body}"
+
+    ClaudeAgentSDK.query(prompt: prompt, options: options) do |message|
+      ticket.update!(summary: message.result) if message.is_a?(ClaudeAgentSDK::ResultMessage)
+    end
+  end
+end
+```
+
+The block runs on a plain thread, so ActiveRecord calls inside it are safe. It is a thread of its own, though: the job's `Current` attributes, time zone, log tags and database role or shard are not set there (see [Request state does not follow into callbacks](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/rails.md#request-state-does-not-follow-into-callbacks)). [docs/rails.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/rails.md) continues with multi-turn sessions, ActionCable streaming, per-user isolation, and fiber workers.
+
 ## Documentation
 
 | Topic | Guide |
@@ -210,7 +232,7 @@ See [docs/hooks-and-permissions.md](https://github.com/rubycatco/claude-agent-sd
 | 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) |
 | Error handling, exception hierarchy, timeouts | [docs/errors.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/docs/errors.md) |
 
-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).
+API reference: [rubydoc.info/gems/claude-agent-sdk](https://rubydoc.info/gems/claude-agent-sdk). Available built-in tools: [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
 
 ## Examples
 
@@ -219,7 +241,7 @@ Runnable scripts live in [`examples/`](https://github.com/rubycatco/claude-agent
 | Area | Examples |
 |------|----------|
 | 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) |
-| 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) |
+| Sessions, subagents and output | [session_resumption](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/session_resumption_example.rb) · [subagent_status](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/examples/subagent_status_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) |
 | 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) |
 | 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) |
 | 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) |
@@ -238,7 +260,7 @@ All three SDKs drive the same CLI over the same protocol, so capabilities line u
 | Hooks (all 33 events) | ✅ | 10 typed, the rest by name | ✅ |
 | Permission callbacks | ✅ | ✅ | ✅ |
 | Structured output | ✅ | ✅ | ✅ |
-| All 28 message types | ✅ | partial | ✅ |
+| Typed classes for every message type | ✅ | partial | ✅ |
 | [Sandbox](https://github.com/anthropic-experimental/sandbox-runtime) settings | ✅ | partial | ✅ |
 | Bare mode (`--bare`) | ✅ | via `extra_args` | ✅ |
 | File checkpointing & rewind | ✅ | ✅ | ✅ |
@@ -249,7 +271,7 @@ All three SDKs drive the same CLI over the same protocol, so capabilities line u
 | Custom transport (pluggable I/O) | — | ✅ | ✅ |
 | Rails integration | — | — | ✅ |
 
-Types are plain Ruby classes with `attr_accessor` and keyword arguments, mirroring the field names of the TypeScript Zod schemas and Python dataclasses; there is no runtime type checking.
+Types are plain Ruby classes with `attr_accessor` and keyword arguments, mirroring the field names of the TypeScript Zod schemas and Python dataclasses; there is no runtime type checking. The gem ships RBS signatures for its public API in `sig/`, which Steep and other RBS tools pick up through `rbs collection`.
 
 ## Claude Code plugin
 
@@ -272,7 +294,7 @@ RUN_INTEGRATION=1 bundle exec rspec  # also run the real-CLI integration suite (
 BUNDLE_GEMFILE=gemfiles/rails_8.gemfile bundle exec rspec --options spec/rails/.rspec  # Rails integration specs
 ```
 
-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.
+CI runs the suite and RuboCop on Ruby 3.2 through 4.0, the Rails specs on Rails 7.1 and 8, and both RBS tasks. See [CONTRIBUTING.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/CONTRIBUTING.md) for the development setup and the CI matrix, and [spec/README.md](https://github.com/rubycatco/claude-agent-sdk-ruby/blob/main/spec/README.md) for the test layout.
 
 ## Contributing
 

data/docs/client.md

@@ -64,6 +64,8 @@ ClaudeAgentSDK::Client.open do |client|
 end
 ```
 
+To handle Ctrl-C yourself in a terminal app (call `interrupt`, ask, or ignore it) rather than have it stop the CLI too, see [`process_group`](options.md#process_group).
+
 The Ruby-style names above sit next to the Python SDK's spellings, and both work, so code ported from the Python docs runs unchanged:
 
 | Ruby style | Python-parity name |

data/docs/errors.md

@@ -87,6 +87,32 @@ initial handshake that was still in flight when the CLI exited. Match on
 `Resume rejected by --resume-drops-turn:` in the message and treat it as
 deterministic: clear the fork target and resume plainly rather than retrying.
 
+## Authentication Failures
+
+The SDK holds no credentials; the CLI authenticates itself (see the README's
+[Authentication](../README.md#authentication)). Neither of the two ways that
+can fail is reported when the session starts.
+
+**No credentials at all** (a fresh container, a CI runner). 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.** It ends the same way, with
+`api_error_status` 401, but only after the CLI has retried: ten
+`APIRetryMessage`s over about three minutes when tested. Watch for them rather
+than waiting for the error:
+
+```ruby
+ClaudeAgentSDK.query(prompt: "Hello") do |message|
+  next unless message.is_a?(ClaudeAgentSDK::APIRetryMessage)
+
+  warn "API retry #{message.attempt}/#{message.max_retries}: HTTP #{message.error_status} (#{message.error})"
+end
+```
+
 ## Errors from Client Control Methods
 
 `Client#interrupt`, `#set_model`, `#set_permission_mode`, `#rewind_files`, `#reconnect_mcp_server`, `#toggle_mcp_server`, `#stop_task` and the other control methods (the Ruby-style `model=` and `permission_mode=` included) send a request to the CLI and wait for its answer. They can fail in three ways:

data/docs/options.md

@@ -170,6 +170,7 @@ Guides: [Vendoring the CLI](cli-installer.md), [Custom Transport](client.md#cust
 | `cwd` | `String \| Pathname` | `nil` | The working directory of the CLI process (and its `PWD`) |
 | `env` | `Hash[String \| Symbol, String?]` | `{}` | Merged over the environment the CLI process inherits. A `nil` value unsets the variable |
 | `user` | `String \| Integer` | `nil` | The user the CLI process runs as (name or uid; Unix, and the SDK process needs the privilege to switch) |
+| `process_group` | `bool` | `false`; explicit `nil` stays `nil` | Nothing (SDK only): the CLI process starts in a process group of its own, out of reach of the terminal's Ctrl-C. See [`process_group`](#process_group) |
 | `extra_args` | `Hash[String \| Symbol, untyped]` | `{}` | `--<flag> <value>` per pair, `--<flag>` for a `nil` value. See [`extra_args`](#extra_args) |
 | `stderr` | `_StderrCallback` | `nil` | Nothing (SDK only): called with each line the CLI writes to stderr |
 | `debug_stderr` | `_Puts \| String` | `nil` | Nothing (SDK only): an IO-like object (`puts`) or a file path that receives each CLI stderr line |
@@ -177,6 +178,48 @@ Guides: [Vendoring the CLI](cli-installer.md), [Custom Transport](client.md#cust
 
 These options describe the process the SDK starts itself. A [custom transport](client.md#custom-transport) starts the CLI its own way and decides what to do with them.
 
+### `process_group`
+
+In a terminal, Ctrl-C sends SIGINT to every process of the foreground process group. The CLI is in your process's group, so it gets the signal at the same moment your process does and ends the turn on its own, before your code can decide what to do: interrupt and keep the partial reply, ask whether to stop, or ignore the keypress. With `process_group: true` the CLI process the SDK starts for the session begins in a process group of its own, and the terminal's SIGINT no longer reaches it, nor the processes it starts that stay in its group (Bash tool commands, stdio MCP servers). The short `claude -v` version check that runs before it stays in your group.
+
+It applies to `query()` and `Client` alike, on the default transport. A [custom transport](client.md#custom-transport) starts the CLI its own way. A transport subclass whose `#build_command` wraps the CLI in another program (`docker exec`, `ssh`) puts that local program in a group of its own; the option does not set the process group of a CLI on the far side. The Python SDK has no equivalent; the TypeScript SDK leaves it to a custom `spawnClaudeCodeProcess`.
+
+Your process now owns Ctrl-C. To stop a turn, call `Client#interrupt`, or `Client#disconnect` to end the session; a one-shot `query()` has no handle to interrupt. Neither may be called inside a signal trap: they take a mutex, and Ruby raises `ThreadError` (`can't be called from trap context`). Let the trap only record the signal, and make the call from ordinary code:
+
+```ruby
+interrupts = Thread::Queue.new
+previous = trap('INT') { interrupts << :int } # nothing else in here: no SDK calls
+begin
+  options = ClaudeAgentSDK::ClaudeAgentOptions.new(process_group: true)
+  ClaudeAgentSDK::Client.open(options: options) do |client|
+    watcher = Thread.new do
+      client.interrupt if interrupts.pop # on this thread, outside the trap
+    end
+    client.query('Refactor the parser')
+    client.receive_response { |message| puts message }
+  ensure
+    interrupts << nil # ends the watcher; the queue stays open for the trap
+    watcher&.join
+  end
+ensure
+  trap('INT', previous) # Ctrl-C behaves as before once the session is over
+end
+```
+
+A plain script that does not trap INT is no worse off: Ctrl-C still raises `Interrupt` in your process, and the SDK's teardown stops the CLI as it does on any other exception.
+
+When the CLI process stops:
+
+- On `Client#disconnect`, or at the end of a `Client.open` block or a `query()` call, the usual teardown runs: the SDK closes the CLI's stdin, gives it a grace period to finish, then sends SIGTERM and finally SIGKILL.
+- When the interpreter exits normally without a disconnect, an `at_exit` handler sends SIGTERM to the CLI process. Best effort: it does not wait for the turn.
+- When your process dies abruptly (`exit!`, SIGKILL), the SDK cleans up nothing. The CLI sees its stdin close, which normally lets it wind down; how soon is up to the CLI and its background work (see [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](#claude_code_print_bg_wait_ceiling_ms)).
+
+In every case the SDK signals the CLI process only, not its group. The processes the CLI starts are its own to stop, and with the option on they no longer get the terminal's SIGINT either.
+
+The CLI's group is a background group of the terminal. A process in it that reads from the controlling terminal (a tool command that prompts on the tty) is stopped with SIGTTIN, and so is the rest of the group, the CLI included when the tool shares its group. Whether writing to the terminal stops it too depends on the terminal's TOSTOP setting. The SDK's own traffic with the CLI goes through pipes and is unaffected.
+
+On Windows the option starts the CLI with `new_pgroup: true` (`CREATE_NEW_PROCESS_GROUP`), which also turns Ctrl-C off for the CLI process. It has not been exercised on Windows.
+
 ### `extra_args`
 
 The way to pass a CLI flag the SDK has no option for. A key is the flag's name without the leading dashes; the value follows it, and `nil` means a flag without a value:

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -373,6 +373,15 @@ module ClaudeAgentSDK
         # On Windows spawn raises for :uid, wrapped below into
         # CLIConnectionError — fail-loud instead of the old silent ignore.
         opts = { chdir: @cwd&.to_s, uid: @options.user }.compact
+        # process_group: the terminal's Ctrl-C signals the whole foreground
+        # process group, so a CLI left in ours ends the turn on its own
+        # before the host can choose to interrupt, ask, or ignore it. Its own
+        # group keeps that decision with the host. Teardown still signals
+        # the pid, not the group. Windows has no :pgroup; :new_pgroup
+        # (CREATE_NEW_PROCESS_GROUP) is its equivalent, and Unix rejects it.
+        # Absent unless set, like :uid. The `-v` probe is short-lived and
+        # bounded, and stays in our group.
+        opts[Gem.win_platform? ? :new_pgroup : :pgroup] = true if @options.process_group?
 
         @stdin, @stdout, @stderr, @process = Open3.popen3(process_env, *cmd, opts)
         # The CLI emits UTF-8 regardless of the parent locale. popen3 pipes

data/lib/claude_agent_sdk/types/options.rb

@@ -84,6 +84,7 @@ module ClaudeAgentSDK
       self.strict_mcp_config = false
       self.forward_subagent_text = false
       self.verbatim_prompts = false
+      self.process_group = false
 
       super(merge_with_defaults(attributes || {}))
 
@@ -247,6 +248,40 @@ module ClaudeAgentSDK
       @verbatim_prompts = coerce_boolean(value)
     end
 
+    # Start the CLI process in a process group of its own. Defaults to
+    # `false`.
+    #
+    # In a terminal, Ctrl-C sends SIGINT to the whole foreground process
+    # group, and the CLI is in your process's group unless this is set: it
+    # ends the turn on its own at the same moment your process sees the
+    # signal, before you can decide what to do about it. When true, the
+    # terminal's SIGINT no longer reaches the CLI (nor the processes it
+    # starts in its own group), and stopping a turn is up to you:
+    # {Client#interrupt} or {Client#disconnect}, called from ordinary code,
+    # never from inside a signal trap.
+    #
+    # Applies to the CLI process the default transport starts for the
+    # session (`pgroup: true` on Unix, `new_pgroup: true` on Windows), not to
+    # the short `claude -v` version probe. SDK only: nothing is sent to the
+    # CLI. Ruby only: the Python SDK has no equivalent, and the TypeScript
+    # SDK leaves it to a custom `spawnClaudeCodeProcess`.
+    #
+    # Assigning coerces to a Boolean; {#process_group?} is the predicate
+    # form.
+    #
+    # @return [Boolean]
+    attr_reader :process_group
+
+    # @return [Boolean] {#process_group}, as a strict Boolean.
+    def process_group?
+      !!process_group
+    end
+
+    # @see #process_group
+    def process_group=(value)
+      @process_group = coerce_boolean(value)
+    end
+
     # Request model-generated progress summaries for subagent (`local_agent`)
     # tasks. `true` *requests* generation: while the CLI has it enabled, a
     # subagent's {TaskProgressMessage#summary} **may** carry a one-line status.

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 end

data/sig/claude_agent_sdk/types/options.rbs

@@ -57,6 +57,7 @@ module ClaudeAgentSDK
                       ?can_use_tool: _CanUseTool?,
                       ?hooks: Hash[String | Symbol, Array[HookMatcher]?]?,
                       ?user: (String | Integer)?,
+                      ?process_group: bool?,
                       ?agents: Hash[String | Symbol, AgentDefinition | Hash[Symbol | String, untyped]]?,
                       ?setting_sources: Array[String]?,
                       ?skills: (String | Array[String])?,
@@ -158,6 +159,14 @@ module ClaudeAgentSDK
     # User (name or uid) to run the CLI process as.
     attr_accessor user: (String | Integer)?
 
+    # Start the CLI process in a process group of its own, so the terminal's
+    # Ctrl-C does not reach it (false by default).
+    attr_reader process_group: bool?
+
+    def process_group=: (untyped value) -> bool?
+
+    def process_group?: () -> bool
+
     attr_accessor agents: Hash[String | Symbol, AgentDefinition | Hash[Symbol | String, untyped]]?
 
     # Entries of SETTING_SOURCES.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - ya-luotao
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async