claude-agent-sdk 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54ece5b925722a884cb054583cd1d54307736c8491fa9452dfb46bd3b522bd9c
-  data.tar.gz: fc048c6247dc93e82be75ab1ce0a04bcf616409998c4c89ac8fb4defc1e83ae4
+  metadata.gz: 5207d9e2d85cd3a5b1c8a7f7267d74077dd8ed7c856361f7e8689401a5da0b4b
+  data.tar.gz: 644c33952692d891e3c46c8ad4d448e52ef06461b79bec66950b3fb24ab6d926
 SHA512:
-  metadata.gz: 0bbd41108e645d575b0bc2603de574e4f727eb40a4cd9feabf111c11708196c0947ba7d492b870edfc7dbc7812e7166279aeecc3e6dc8bef7fa530baadfe694b
-  data.tar.gz: 676ef6b0dd2f168f73fd820fd33528729b02d96656140a7b340ade9a7548495354341949a84ede20a737a3ea2ce62bc0fe11adbb26225af3911661b7a72afdf1
+  metadata.gz: 03ad7fab32ba205b5598c2237dd65a8a1b25786349da7f1c5815eb83ccc516206d89c1bbfaa9e7c2d0ccc2e5cf3256c8fda2cc92a7d3a48eb6a56c24d28678d8
+  data.tar.gz: 4b97b7f3cedb844e78a4d04c4d376f776f76c74e2822c6c6253a6aff8bececbfcce04a5c6a54b52d7348e5900987ea9f5179fe773aa763a06dc126a13b2942a6

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.1] - 2026-10-25
+
+### Changed
+- **`process_group: true`: a SIGKILL the SDK sends the CLI also goes to the CLI's process group.** A wedged CLI that the SDK had to kill could not stop its own children, so one still in its group that ignores stdin EOF (a stdio MCP server, for instance) kept running after the session; before `process_group` it would at least have got the terminal's Ctrl-C. The group SIGKILL goes out just before the SIGKILL of the CLI itself, whenever the SDK sends one (a normal teardown after its grace periods and SIGTERM, a cancelled teardown after its short grace, or a CLI that closed stdout and hung), and adds no delay. SIGTERM, including the one sent at interpreter exit, still goes to the CLI process only, so the CLI's own cleanup of its children still runs; a CLI that exits on SIGTERM or on its own gets no group signal, and processes that left its group are not reached. Only sessions with `process_group: true` on Unix are affected. This narrows what 1.4.0 documented ("the SDK still signals the CLI process, not its group"). See [`docs/options.md`](docs/options.md#process_group).
+
+## [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,59 @@ 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 only, not its group. Best effort: it does not wait for the turn, and sends no SIGKILL.
+- 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)).
+
+SIGTERM still goes to the CLI process only, so the CLI can stop the processes it started in its own order (it does so for stdio MCP servers). Whenever the SDK sends the CLI SIGKILL, that SIGKILL also goes to the CLI's process group, so processes still in that group die with the CLI instead of outliving it: a CLI that has to be killed cannot stop them itself, and with the option on they no longer get the terminal's SIGINT either. The group SIGKILL follows the SDK's own SIGKILL decisions and adds no delay of its own. The SDK sends the CLI SIGKILL when it is still running:
+
+- on a normal teardown (disconnect, the end of a `Client.open` block or a `query()` call): after stdin EOF, a grace period, SIGTERM and a second grace period;
+- when that teardown is itself cancelled before it got there (`Async::Stop`, a task timeout): SIGTERM at once, then SIGKILL after a short grace, with no grace for stdin EOF first;
+- when the CLI has closed its stdout but kept running: after a grace period of its own, SIGTERM and a second grace period.
+
+What it does not do:
+
+- When the CLI exits on its own, or on SIGTERM, before a SIGKILL is due, the SDK sends its group nothing. Its children are the CLI's to stop; one that ignores the CLI's request is not chased.
+- A process that moved to another process group is not reached.
+- The SDK does not wait for or reap the processes the group SIGKILL reaches: they are the CLI's children, not the SDK's.
+- On Windows nothing changes: the SDK signals the CLI process only.
+
+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,8 +373,24 @@ 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. SIGTERM still goes to the
+        # pid only; a SIGKILL also goes to the group (#kill_process_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)
+        # Recorded from the spawn options themselves, on every spawn: only a
+        # process this line started with pgroup: true leads a group of its
+        # own (pgid == its pid). Kept by identity, so a KILL site asks about
+        # the waiter it holds, never the options, which can change after
+        # spawn. Not cleared by #close: a read loop still waiting on the
+        # same waiter must get the same answer.
+        @group_leader = opts[:pgroup] ? @process : nil
         # The CLI emits UTF-8 regardless of the parent locale. popen3 pipes
         # default to Encoding.default_external (US-ASCII under LANG=C/LC_ALL=C
         # — minimal Docker images, systemd, CI), which makes String#strip on
@@ -630,7 +646,14 @@ module ClaudeAgentSDK
         rescue Timeout::Error
           # SIGTERM didn't work — force kill
           begin
-            Process.kill('KILL', @process.pid)
+            kill_process_group(@process.pid) if group_leader?(@process)
+            begin
+              Process.kill('KILL', @process.pid)
+            rescue Errno::ESRCH
+              # Already reaped: the group KILL just above reaches the CLI
+              # too, and its waiter can finish before this signal. Still
+              # wait for that waiter below, as the other KILL sites do.
+            end
             @process.value
           rescue StandardError => e
             raise if e.is_a?(Async::TimeoutError)
@@ -661,9 +684,12 @@ module ClaudeAgentSDK
     # inside an ensure during fiber cancellation: synchronous SIGTERM now,
     # then a plain (non-reactor) thread escalates to SIGKILL after a grace
     # period. Open3's Process::Waiter thread keeps reaping, so no zombie is
-    # left either way. The alive? guard also makes the delayed KILL
-    # pid-reuse-safe: while the waiter thread reports alive (not yet reaped),
-    # the pid cannot have been recycled.
+    # left either way. The alive? guard before the delayed KILL is best
+    # effort: it narrows the window in which the pid could have been reaped
+    # and recycled, but does not close it — the waiter reports alive for a
+    # moment after its OS wait has reaped the child, and the child can be
+    # reaped between the check and the signal. The group KILL shares the
+    # pid KILL's check and instant, and so its window.
     #
     # @api private
     def force_terminate_in_background(process, grace_seconds: 2)
@@ -675,6 +701,8 @@ module ClaudeAgentSDK
       end
 
       pid = process.pid
+      # Captured now, on the caller's thread, for the KILL thread below.
+      kill_group = group_leader?(process)
       begin
         Process.kill('TERM', pid)
       rescue Errno::ESRCH
@@ -686,7 +714,10 @@ module ClaudeAgentSDK
       Thread.new do
         unless process.join(grace_seconds)
           begin
-            Process.kill('KILL', pid) if process.alive?
+            if process.alive?
+              kill_process_group(pid) if kill_group
+              Process.kill('KILL', pid)
+            end
           rescue Errno::ESRCH
             # Still wait for the waiter when exit raced the signal.
           end
@@ -731,6 +762,31 @@ module ClaudeAgentSDK
       false
     end
 
+    # Whether +process+ is the waiter #connect spawned with pgroup: true,
+    # i.e. the leader of a process group of its own, with the pid as pgid.
+    #
+    # @api private
+    def group_leader?(process)
+      !process.nil? && @group_leader.equal?(process)
+    end
+
+    # SIGKILL to the process group the CLI was spawned to lead, sent just
+    # before every SIGKILL of the CLI itself (process_group: true only), so
+    # its children still in that group die with it instead of outliving a
+    # CLI that never got to stop them. SIGTERM stays on the pid: the CLI
+    # stops its children itself on TERM, in its own order. Group first, so
+    # the still-running CLI keeps the group id in use at the signal. Best
+    # effort, and it proves nothing about the CLI: the group can be empty
+    # (ESRCH) or still hold other members after the CLI left it, so the pid
+    # KILL that follows, its waits and its error handling stay as they are.
+    #
+    # @api private
+    def kill_process_group(pgid)
+      Process.kill('KILL', -pgid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
     def write(data)
       raise CLIConnectionError, 'Cannot write to terminated process' if @process && !@process.alive?
       raise CLIConnectionError, "Cannot write to process that exited with error: #{@exit_error}" if @exit_error
@@ -885,6 +941,7 @@ module ClaudeAgentSDK
       # double-wait). Both are non-fatal — the message loop just exits.
       # Snapshot: a concurrent close() nils @process mid-wait.
       process = @process
+      kill_group = group_leader?(process)
       returncode = nil
       termsig = nil
       forced_exit = false
@@ -901,6 +958,7 @@ module ClaudeAgentSDK
           begin
             Process.kill('TERM', process.pid)
             unless process_exited_within?(process, EOF_TERM_GRACE_SECONDS)
+              kill_process_group(process.pid) if kill_group
               Process.kill('KILL', process.pid)
               # Even KILL can't reap a child stuck in uninterruptible kernel
               # I/O; bound this last wait too rather than block on #value.

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,47 @@ 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.
+    #
+    # Teardown still sends SIGTERM to the CLI process only, so the CLI can
+    # stop its own children in order. Whenever the SDK has to SIGKILL the
+    # CLI (it is still running after the teardown's graces and SIGTERM, or a
+    # cancelled teardown's short grace), that SIGKILL also goes to the CLI's
+    # process group, so processes still in it die with the CLI instead of
+    # outliving it. Unix only; see docs/options.md for the limits.
+    #
+    # 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.1'
 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.1
 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