claude-agent-sdk 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6fe812f6bded72a1c1adfc9175c56eee2fa8efa4e32775fe5c442543cee43cb
-  data.tar.gz: 846346fa31dea76200b96846058ab3bb92727ab1f2463a1672e1ca0848c881cc
+  metadata.gz: 5207d9e2d85cd3a5b1c8a7f7267d74077dd8ed7c856361f7e8689401a5da0b4b
+  data.tar.gz: 644c33952692d891e3c46c8ad4d448e52ef06461b79bec66950b3fb24ab6d926
 SHA512:
-  metadata.gz: 1d057cc9e1b745c27f1b94c75193ba498f1eaac910409c916c4d1f64f0567bc21c62749bf019ac0c1b2fc99361c3e1f868b16b67a53c9fb0ad5e7e6b69b62ed0
-  data.tar.gz: 5dec34347fe3becfb005b9e1c0431c56b99f05383eaf17e6b9ac56379a2df0a7973972eeaa09b7e8ffd5c5ab318086753f6a39e19f841a3f0c98cded618f5fff
+  metadata.gz: 03ad7fab32ba205b5598c2237dd65a8a1b25786349da7f1c5815eb83ccc516206d89c1bbfaa9e7c2d0ccc2e5cf3256c8fda2cc92a7d3a48eb6a56c24d28678d8
+  data.tar.gz: 4b97b7f3cedb844e78a4d04c4d376f776f76c74e2822c6c6253a6aff8bececbfcce04a5c6a54b52d7348e5900987ea9f5179fe773aa763a06dc126a13b2942a6

data/CHANGELOG.md

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

data/docs/options.md

@@ -211,10 +211,21 @@ A plain script that does not trap INT is no worse off: Ctrl-C still raises `Inte
 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 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)).
 
-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.
+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.
 

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -376,14 +376,21 @@ module ClaudeAgentSDK
         # 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.
+        # 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
@@ -639,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)
@@ -670,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)
@@ -684,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
@@ -695,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
@@ -740,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
@@ -894,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
@@ -910,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

@@ -260,6 +260,13 @@ module ClaudeAgentSDK
     # {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

data/lib/claude_agent_sdk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - ya-luotao