claude-agent-sdk 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0738568951864f8bf79353f7477f23356c0d04e60900ca346dab0bcc099dbe46'
-  data.tar.gz: 5136e71504b5078bb3e6fbcc38d34ee2151239be909d275f0972ef40a052a8ff
+  metadata.gz: 34802f2c21bd1cf77053b627b48032fa448a616d17379f0c788cee879d12d8ba
+  data.tar.gz: 8f44d432159c6fba9dc453a30702d7a215527a5a52ab9398082e3ef53b1bf037
 SHA512:
-  metadata.gz: 61d60a87a8202259abc051f7b642d79c3b2c49f1f53a44ad588a69669578d170415860a584ce8e487a81566b1fc51c86a76cb83b0f47f78bd051fdc07e20276e
-  data.tar.gz: f8a8b46e371a290885f33806fb3a67cf95494ed59003749c54ab68c33123d32f9d80ea3f576262201f08fefa5d14f0d4947edd2245c376a045fbdc10b5f79677
+  metadata.gz: 061a1e5c1bea501e9ced4a7a31a893e633b2b5e8f345ae0b28b94959ff2ec5ad2594fd7374be4eefe67bfbcc57d023d364960721f3a81c0f044ee26b57bb35db
+  data.tar.gz: 96be886af087aab90fddf8355d858f7e2cf7d31c122e30bee6554a56e20f2a45d970ba80f5026d214a5491beca588cae5c7c03028b49a41868ae0a7172562a04

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.24.0] - 2026-07-27
+
+Parity batch with the Python SDK v0.2.111–v0.2.128 (everything substantive in that span; the rest is bundled-CLI version bumps, which don't apply to this gem).
+
+### Fixed
+- **argv flag injection via `resume` / `session_id` / `resume_session_at`** (Python #1123): these values are now passed as single `=`-joined argv tokens (`--resume=<value>`). The CLI declares `--resume [value]` with an *optional* value, so in the old two-token form a dash-leading untrusted value (e.g. a session id taken from a request) was not bound to the flag and parsed as an independent CLI flag — letting it inject e.g. `--dangerously-skip-permissions`. `extra_args` values starting with `-` are likewise emitted in `--flag=value` form (Python #1127); other `extra_args` values keep the two-token form.
+- **Premature stdin close while background tasks are in flight** (Python #1103): a `result` frame ends one *turn*, not the run. The SDK no longer closes stdin on a result while `run_in_background` subagents (task types `local_agent`/`local_workflow`) are still running — previously their SDK-MCP tool calls failed with `"Stream closed"` and their PreToolUse hooks were silently bypassed (deny-gates stopped gating). In-flight tasks are tracked from `task_started` / `task_notification` / terminal `task_updated` lifecycle frames; stdin closes on the first result with none in flight. Background shells/teammates are deliberately not tracked (they may never reach a terminal status, which would withhold the close forever).
+- **Leaked CLI child when a cancellation interrupts `close`** (Python #1082): the graceful TERM→KILL escalation in `SubprocessCLITransport#close` suspends (task sleep, thread join), so `Async::Stop` delivered mid-close abandoned it and left a live `claude` child running until interpreter exit. `close` now guarantees termination from an `ensure` with no suspension points: synchronous SIGTERM immediately, then a plain background thread escalates to SIGKILL after a 2s grace period; on that path the child also deliberately stays in the `at_exit` registry as a second safety net, and the stdin/stdout/stderr pipes are closed best-effort (references cleared first, so even a failed close leaves them collectable) instead of leaking descriptors for the life of the transport object.
+
+### Added
+- `ResultMessage#terminal_reason` (Python #1142): why the query loop ended (`"completed"`, `"max_turns"`, `"aborted_streaming"`, …). `"aborted_streaming"` / `"aborted_tools"` mean the turn was cancelled via `Client#interrupt`. `nil` when the CLI does not report one (older CLIs, or a result that bypassed the query loop such as a local slash command).
+- **Advisory warning when `can_use_tool` is shadowed** (Python #1081): the callback is only consulted when the CLI's permission ladder lands on "ask", so `permission_mode: 'bypassPermissions'` or an `allowed_tools` entry that allows a whole tool (`'Read'`, `'Read()'`, `'Read(*)'` — including the bare `Skill` implied by `skills: 'all'`) silently turns a security callback into dead code. `query()` / `Client#connect` now warn to stderr, once per distinct message per process (`ClaudeAgentSDK::OptionWarnings.reset!` clears the dedupe for tests). Real specifiers (`'Bash(ls:*)'`) and malformed entries don't warn; never raises. The permission-callback docs/example no longer demonstrate the shadowed combination.
+- Documented the `ResultMessage#model_usage` per-model value shape (verbatim CLI camelCase keys, matching the TS/Python `ModelUsage` type), including the new optional `canonicalModel` and `provider` keys (Python #1143 — type-only upstream, so a doc change here).
+
 ## [0.23.0] - 2026-07-14
 
 ### Added

data/README.md

@@ -68,7 +68,7 @@ Add this line to your application's Gemfile:
 gem 'claude-agent-sdk', github: 'ya-luotao/claude-agent-sdk-ruby'
 
 # Or use a stable version from RubyGems
-gem 'claude-agent-sdk', '~> 0.23.0'
+gem 'claude-agent-sdk', '~> 0.24.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.

data/docs/hooks-and-permissions.md

@@ -95,7 +95,6 @@ Async do
   end
 
   options = ClaudeAgentSDK::ClaudeAgentOptions.new(
-    allowed_tools: ['Read', 'Write', 'Bash'],
     can_use_tool: permission_callback
   )
 
@@ -108,3 +107,25 @@ end.wait
 ```
 
 See [examples/permission_callback_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/permission_callback_example.rb).
+
+### Shadowing: when `can_use_tool` never runs
+
+`can_use_tool` is only consulted when the CLI's permission ladder lands on
+"ask". Anything that auto-approves a tool call earlier means the callback
+never fires for it — a security callback can silently become dead code:
+
+- `permission_mode: 'bypassPermissions'` auto-approves everything (except
+  explicit deny rules), fully shadowing the callback.
+- An `allowed_tools` entry that allows a whole tool — `'Write'`, `'Write()'`,
+  `'Write(*)'`, or the bare `Skill` implied by `skills: 'all'` — shadows the
+  callback for that tool. A real specifier like `'Bash(ls:*)'` only
+  auto-approves matching invocations.
+- Allow rules in settings files shadow the callback the same way, but are not
+  visible to the SDK at construction time.
+
+The SDK emits an advisory warning to stderr from `query()` / `Client#connect`
+when it can see the shadowing (once per distinct message per process). It
+never raises — shadowing can be intentional, e.g. a callback used solely for
+tools outside `allowed_tools`. To gate every tool call including
+auto-approved ones, use a `PreToolUse` hook instead (note that a `PreToolUse`
+hook returning an allow decision also skips this callback).

data/docs/types.md

@@ -74,20 +74,41 @@ Final result message with cost and usage information.
 
 ```ruby
 class ResultMessage
-  attr_accessor :subtype,           # String
-                :duration_ms,       # Integer
-                :duration_api_ms,   # Integer
-                :is_error,          # Boolean
-                :num_turns,         # Integer
-                :session_id,        # String
-                :stop_reason,       # String | nil ('end_turn', 'max_tokens', 'stop_sequence')
-                :total_cost_usd,    # Float | nil
-                :usage,             # Hash | nil
-                :result,            # String | nil (final text result)
-                :structured_output  # Hash | nil (when using output_format)
+  attr_accessor :subtype,            # String
+                :duration_ms,        # Integer
+                :duration_api_ms,    # Integer
+                :is_error,           # Boolean
+                :num_turns,          # Integer
+                :session_id,         # String
+                :stop_reason,        # String | nil ('end_turn', 'max_tokens', 'stop_sequence')
+                :total_cost_usd,     # Float | nil
+                :usage,              # Hash | nil
+                :result,             # String | nil (final text result)
+                :structured_output,  # Hash | nil (when using output_format)
+                :model_usage,        # Hash | nil — { model_name => usage Hash } (see below)
+                :permission_denials, # Array | nil
+                :errors,             # Array<String> | nil (present on error subtypes)
+                :uuid,               # String | nil
+                :fast_mode_state,    # String | nil ('off', 'cooldown', 'on')
+                :api_error_status,   # Integer | nil (HTTP status on api_error subtype)
+                :terminal_reason     # String | nil (see below)
 end
 ```
 
+`terminal_reason` says why the query loop ended (`"completed"`, `"max_turns"`,
+`"aborted_streaming"`, ...). `"aborted_streaming"` / `"aborted_tools"` mean the
+turn was cancelled via `Client#interrupt`. `nil` when the CLI did not report
+one (older CLIs, or a result that bypassed the query loop such as a local
+slash command).
+
+`model_usage` values are passed through verbatim from the CLI, so their keys
+are camelCase (the TypeScript/Python SDKs' `ModelUsage` shape): `inputTokens`,
+`outputTokens`, `cacheReadInputTokens`, `cacheCreationInputTokens`,
+`webSearchRequests`, `costUSD`, `contextWindow`, `maxOutputTokens`, plus
+optional `canonicalModel` (canonical id used for the pricing lookup, which can
+differ from the raw model-string key for provider-specific ids/aliases) and
+`provider` (`'firstParty'`, `'bedrock'`, `'vertex'`, ...).
+
 ## Content Block Types
 
 ```ruby

data/lib/claude_agent_sdk/command_builder.rb

@@ -142,9 +142,14 @@ module ClaudeAgentSDK
       raise ArgumentError, "continue_conversation and resume are mutually exclusive" if @options.continue_conversation && @options.resume
 
       cmd.push("--continue") if @options.continue_conversation
-      cmd.push("--resume", @options.resume) if @options.resume
+      # =-joined single tokens: the CLI declares `--resume [value]` with an
+      # OPTIONAL value, so in the two-token form a dash-leading value is not
+      # bound to the flag and parses as an independent CLI flag — letting an
+      # untrusted value (e.g. a session id from a request) inject arbitrary
+      # flags. The equals form always binds the value to its flag.
+      cmd.push("--resume=#{@options.resume}") if @options.resume
       append_resume_session_at(cmd)
-      cmd.push("--session-id", @options.session_id) if @options.session_id
+      cmd.push("--session-id=#{@options.session_id}") if @options.session_id
     end
 
     # `--resume-session-at <message-uuid>` truncates the resumed conversation
@@ -157,7 +162,9 @@ module ClaudeAgentSDK
 
       raise ArgumentError, "resume_session_at requires resume to be set" unless @options.resume
 
-      cmd.push("--resume-session-at", @options.resume_session_at.to_s)
+      # Equals form for the same reason as --resume above: never let a
+      # dash-leading value parse as a separate flag.
+      cmd.push("--resume-session-at=#{@options.resume_session_at}")
     end
 
     # Sandbox gating is `!nil?` throughout — Python's `sandbox is not None`.
@@ -373,6 +380,10 @@ module ClaudeAgentSDK
 
         if value.nil?
           cmd.push("--#{flag}")
+        elsif value.to_s.start_with?("-")
+          # A dash-leading value must bind via `=` or the CLI parses it as a
+          # separate flag — same injection class as --resume above.
+          cmd.push("--#{flag}=#{value}")
         else
           cmd.push("--#{flag}", value.to_s)
         end

data/lib/claude_agent_sdk/option_warnings.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module ClaudeAgentSDK
+  # Advisory warnings for option combinations that silently change behavior.
+  module OptionWarnings
+    @emitted = Set.new
+    @mutex = Mutex.new
+
+    class << self
+      # can_use_tool is only consulted when the CLI's permission ladder lands
+      # on "ask". Anything that auto-approves a tool call earlier in the
+      # ladder means the callback never runs — so a callback written for
+      # *security* purposes can silently be dead code (real callers have
+      # shipped path-jails that never fired because the same tools were
+      # listed bare in allowed_tools).
+      #
+      # Advisory only (never raises): shadowing can be intentional, e.g. a
+      # callback used solely for tools outside allowed_tools. Deliberately
+      # silent on permission_mode 'acceptEdits' (it only auto-approves in-cwd
+      # file edits, so warning would be a false positive for anyone gating
+      # Bash/network/MCP tools) and on real specifiers like "Bash(ls:*)"
+      # (they only shadow matching invocations, not the whole tool).
+      def warn_if_can_use_tool_shadowed(options)
+        return unless options.can_use_tool
+
+        message = can_use_tool_shadowed_message(options)
+        emit(message) if message
+      end
+
+      # Test hook: forget which messages were already emitted.
+      def reset!
+        @mutex.synchronize { @emitted.clear }
+      end
+
+      private
+
+      # Each distinct message is emitted once per process (mirrors Python's
+      # default UserWarning filter), so an app constructing a client per
+      # request does not repeat the same warning on every connect.
+      #
+      # Best-effort by design: this runs inside query()/Client#connect, and
+      # an advisory warning must never break an otherwise valid session — a
+      # daemonized process with a closed or broken $stderr would otherwise
+      # turn the warn into an IOError out of connect. The message stays in
+      # the dedupe set either way (retrying against a broken sink is
+      # pointless and would violate once-per-process).
+      def emit(message)
+        first = @mutex.synchronize { @emitted.add?(message) }
+        return unless first
+
+        begin
+          warn "Claude SDK: #{message}"
+        rescue StandardError
+          nil
+        end
+      end
+
+      def can_use_tool_shadowed_message(options)
+        # bypassPermissions shadows the callback for EVERY tool, so it takes
+        # precedence over naming individual allowed_tools entries.
+        if options.permission_mode == 'bypassPermissions'
+          return 'can_use_tool will not be invoked: permission_mode ' \
+                 "'bypassPermissions' auto-approves every tool call (except " \
+                 'explicit deny rules) before the callback is consulted. To ' \
+                 'gate every tool call, use a PreToolUse hook instead.'
+        end
+
+        shadowed = shadowed_tools(options)
+        return nil if shadowed.empty?
+
+        "can_use_tool will not be invoked for: #{shadowed.join(', ')}. " \
+          'An allowed_tools entry that allows a whole tool auto-approves it ' \
+          'before the callback is consulted. To gate every tool call, use a ' \
+          'PreToolUse hook; or narrow the entry so calls fall through to ' \
+          'can_use_tool. Allow rules from settings files can also shadow the ' \
+          'callback but are not visible here.'
+      end
+
+      # skills: 'all' makes the command builder append a bare "Skill" to the
+      # effective allowed_tools (CommandBuilder#skills_defaults), so it
+      # shadows the callback just like a hand-written entry; skills: [names]
+      # appends Skill(name) specifiers, which do not.
+      def shadowed_tools(options)
+        allowed_tools = options.allowed_tools || []
+        allowed_tools += ['Skill'] if options.skills == 'all' && !allowed_tools.include?('Skill')
+        allowed_tools.filter_map { |entry| whole_tool_allowed(entry) }.uniq
+      end
+
+      # Returns the tool an allowed_tools entry allows outright, else nil.
+      #
+      # Mirrors the CLI's rule parser (permissionRuleValueFromString): an
+      # entry allows a whole tool when it has no (...) specifier ("Read"),
+      # or when the specifier is empty or a lone wildcard ("Read()",
+      # "Read(*)") — the CLI collapses both to a tool-wide rule. A malformed
+      # entry ("Bash(ls:*" without the closing paren, "(*)") falls back to
+      # being read as a whole-string tool name by the CLI, which then
+      # matches nothing — so it shadows nothing and is ignored here.
+      def whole_tool_allowed(entry)
+        entry = entry.to_s
+        return nil if entry.strip.empty?
+
+        open_index = entry.index('(')
+        return entry if open_index.nil?
+        return nil if open_index.zero? || !entry.end_with?(')')
+
+        specifier = entry[(open_index + 1)...-1]
+        ['', '*'].include?(specifier) ? entry[0...open_index] : nil
+      end
+    end
+  end
+end

data/lib/claude_agent_sdk/query.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'set'
 require 'async'
 require 'async/queue'
 require 'async/condition'
@@ -23,6 +24,22 @@ module ClaudeAgentSDK
     CONTROL_REQUEST_TIMEOUT_ENV_VAR = 'CLAUDE_AGENT_SDK_CONTROL_REQUEST_TIMEOUT_SECONDS'
     DEFAULT_CONTROL_REQUEST_TIMEOUT_SECONDS = 1200.0
 
+    # Task types whose completion runs a follow-up turn, and which therefore
+    # may still need the control channel after the turn's result frame.
+    #
+    # Mirrors the set the CLI itself holds a result back for, which is
+    # narrower than its notion of "delegated agent work". The types left out
+    # are left out on purpose:
+    #   - background shells and monitors run indefinitely by design, so
+    #     deferring the close on one withholds it forever rather than briefly;
+    #   - teammates are long-lived too — their status stays running for their
+    #     whole lifetime, so they never settle the ledger;
+    #   - remote agents can be long-running monitors the CLI likewise refuses
+    #     to wait on.
+    # Anything added here must be a type that reliably reaches a terminal
+    # status, or it will hang the query (see #track_task_lifecycle).
+    DEFERRING_TASK_TYPES = %w[local_agent local_workflow].freeze
+
     # Waiter for control responses awaited OFF the reactor — i.e. a control
     # method called from inside a hook/can_use_tool/SDK-MCP callback, which
     # runs on a FiberBoundary worker thread (Python supports this reentrancy
@@ -68,7 +85,16 @@ module ClaudeAgentSDK
 
       # Message stream
       @message_queue = Async::Queue.new
+      # Set when a run-ending result arrives (a result frame with no tasks in
+      # flight) so the stdin-closing waiter can wake. Named for history — it
+      # once tracked the literal first result.
       @first_result_received = false
+      # Task IDs of started-but-not-finished deferring tasks. A result frame
+      # only ends one turn, not the run: a background task keeps running past
+      # it and still needs stdin for hook/SDK-MCP control responses (Python
+      # #1088/#1103), so a result that arrives while this set is non-empty
+      # must not close stdin.
+      @inflight_tasks = Set.new
       @last_error_result_text = nil
       @first_result_condition = Async::Condition.new
       @task = nil
@@ -307,11 +333,21 @@ module ClaudeAgentSDK
           @transcript_mirror_batcher&.enqueue(message[:filePath] || message[:file_path], message[:entries] || [])
           next
         else
+          # Track task lifecycle frames so results can tell "one turn ended"
+          # apart from "the run is done" (Python #1088/#1103).
+          track_task_lifecycle(message) if message[:type] == 'system'
+
           if message[:type] == 'result'
             # Flush the mirror before signaling/yielding the result so a
             # consumer observing the result sees an up-to-date store for the turn.
             flush_transcript_mirror
-            unless @first_result_received
+            # A result with tasks still in flight ends one turn, not the run:
+            # the tasks may still need hook/SDK-MCP control responses over
+            # stdin, and closing it now silently disables hooks and fails
+            # SDK-MCP calls with "Stream closed". Each deferring task's
+            # completion wakes the parent for a follow-up turn, so a later
+            # result arrives with no tasks in flight and closes stdin then.
+            if @inflight_tasks.empty? && !@first_result_received
               @first_result_received = true
               @first_result_condition.signal
             end
@@ -376,6 +412,50 @@ module ClaudeAgentSDK
       end
     end
 
+    # Track in-flight tasks from `system` task lifecycle frames.
+    #
+    # `task_started` marks a task in flight; `task_notification` or a
+    # `task_updated` patch with a terminal status clears it. Terminal
+    # completion can arrive as either frame (not every terminal task emits a
+    # notification), so both are handled; Set deletion keeps the pair
+    # idempotent.
+    #
+    # This is a mitigation, not a complete answer to Python #1088. An empty
+    # set means "nothing we know of is running", which is not the same as
+    # "the run is over": a task that settles *before* the turn's result frame
+    # leaves the set empty at that result, so stdin closes even though the
+    # completion may still wake the parent for a continuation turn. What this
+    # does fix is the common ordering, where the task outlives the turn that
+    # spawned it.
+    #
+    # Only delegated agent work is tracked (DEFERRING_TASK_TYPES). A
+    # background *shell* is also reported through these frames, but it may
+    # never reach a terminal status, and the CLI in stream-json mode only
+    # exits on stdin EOF — tracking one would withhold the close forever.
+    #
+    # `background_tasks_changed` is deliberately not consumed, in either
+    # direction: its payload is the live *background* set, while a subagent
+    # is registered in the foreground and only flips to backgrounded later
+    # without a second task_started, so narrowing against the snapshot would
+    # drop an agent that goes on to outlive its turn, and widening from it
+    # could admit an id no later frame ever clears (observer agents suppress
+    # both their start and terminal frames).
+    def track_task_lifecycle(message)
+      task_id = message[:task_id]
+      return if task_id.nil? || task_id.to_s.empty?
+
+      case message[:subtype]
+      when 'task_started'
+        @inflight_tasks.add(task_id) if DEFERRING_TASK_TYPES.include?(message[:task_type])
+      when 'task_notification'
+        @inflight_tasks.delete(task_id)
+      when 'task_updated'
+        patch = message[:patch]
+        status = patch.is_a?(Hash) ? patch[:status] : nil
+        @inflight_tasks.delete(task_id) if TERMINAL_TASK_STATUSES.include?(status)
+      end
+    end
+
     # Flush the transcript-mirror batcher, swallowing errors — a mirror failure
     # must never propagate into the read loop or its teardown.
     def flush_transcript_mirror
@@ -1104,15 +1184,19 @@ module ClaudeAgentSDK
                            })
     end
 
-    # Wait for the first result before closing stdin when hooks or SDK MCP
+    # Wait for a run-ending result before closing stdin when hooks or SDK MCP
     # servers may still need to exchange control messages with the CLI.
     # The control protocol requires stdin to stay open for the entire turn
     # (hook replies, can_use_tool replies and SDK MCP tool results are all
     # written to stdin), so no timeout is applied — closing stdin mid-turn
     # silently broke hooks/MCP on turns longer than the old 60s bound
-    # (mirrors Python SDK commit c3d96cb). The condition is guaranteed to be
-    # signaled: by the result branch in read_messages, or by its ensure block
-    # when the process exits early.
+    # (mirrors Python SDK commit c3d96cb). A result frame ends one turn, not
+    # necessarily the run: while background tasks are in flight the result
+    # branch withholds the signal (Python #1088/#1103), and each deferring
+    # task's completion wakes the parent for a follow-up turn that ends in
+    # another result. The condition is guaranteed to be signaled: by the
+    # result branch in read_messages once no tasks are in flight, or by its
+    # ensure block when the process exits early.
     def wait_for_result_and_end_input
       if !@first_result_received &&
          ((@sdk_mcp_servers && !@sdk_mcp_servers.empty?) || (@hooks && !@hooks.empty?))

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -328,6 +328,66 @@ module ClaudeAgentSDK
       @ready = false
       return unless @process
 
+      process = @process
+      process_teardown_complete = false
+      begin
+        teardown_process
+        process_teardown_complete = true
+      ensure
+        # The graceful escalation in teardown_process suspends (task sleep,
+        # thread join), so a cancellation (Async::Stop) delivered mid-close
+        # used to skip TERM/KILL entirely and leak a live CLI child until
+        # interpreter exit (the at_exit reaper fires only then, TERM only).
+        # Nothing here may suspend: a synchronous TERM plus a plain
+        # background thread for the KILL escalation. On this path the
+        # process deliberately STAYS in the at_exit registry as a second
+        # safety net; the normal path deregisters in teardown_process.
+        force_terminate_in_background(process) unless process_teardown_complete
+
+        # Snapshot-then-nil BEFORE the best-effort pipe close below: once the
+        # references are cleared, even a close that somehow failed leaves the
+        # IOs unreachable from this (still-referenced) transport, so GC can
+        # finalize them — "wait for GC" alone would never fire while the
+        # transport keeps pointing at them, and with @process nil a repeat
+        # #close returns immediately, so a cancelled close used to leak the
+        # pipe descriptors for the life of the object.
+        #
+        # @stdin is cleared WITHOUT its mutex (taking it could suspend
+        # mid-cancellation): the ivar swap is atomic, and #write takes its
+        # snapshot under the mutex, so a concurrent writer sees either nil
+        # (raises not-ready — @ready is already false) or the old IO, whose
+        # in-flight write then fails with IOError and is converted to
+        # CLIConnectionError — the documented shutdown behavior either way.
+        stdin_io = @stdin
+        stdout_io = @stdout
+        stderr_io = @stderr
+        @process = nil
+        @stdin = nil
+        @stdout = nil
+        @stderr = nil
+        @stderr_task = nil
+        @exit_error = nil
+
+        unless process_teardown_complete
+          # Cancellation can land before teardown_process reached the pipe
+          # closes. stdout/stderr are read ends (close never blocks); stdin's
+          # implicit flush is a no-op in practice because #write flushes
+          # after every write. Best-effort: an IO that is already closed or
+          # fails to close is left to GC, which the nil-ing above enables.
+          [stdin_io, stdout_io, stderr_io].each do |io|
+            io&.close
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+
+    # Pre-existing #close body: stop the stderr drain, close pipes, wait for
+    # graceful exit after stdin EOF, escalate TERM → KILL on timeout. Runs on
+    # the reactor and suspends at several points; #close's ensure covers the
+    # cancellation-abandoned case.
+    def teardown_process
       cleanup_errors = []
 
       # Kill stderr thread
@@ -404,12 +464,34 @@ module ClaudeAgentSDK
       end
 
       self.class.deregister_active_process(@process)
-      @process = nil
-      @stdout = nil
-      # @stdin already nilled under the mutex above.
-      @stderr = nil
-      @stderr_task = nil
-      @exit_error = nil
+    end
+
+    # Last-resort termination when #close was interrupted before the graceful
+    # escalation finished. Contains no suspension points, so it is safe
+    # 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.
+    def force_terminate_in_background(process, grace_seconds: 2)
+      return unless process&.alive?
+
+      pid = process.pid
+      begin
+        Process.kill('TERM', pid)
+      rescue StandardError
+        return # ESRCH: already gone; EPERM: not ours to signal
+      end
+
+      Thread.new do
+        sleep grace_seconds
+        begin
+          Process.kill('KILL', pid) if process.alive?
+        rescue StandardError
+          nil # died inside the grace window
+        end
+      end
     end
 
     # Wait for the spawned process to exit, up to +timeout_seconds+. Polls

data/lib/claude_agent_sdk/types.rb

@@ -409,15 +409,31 @@ module ClaudeAgentSDK
 
   # Result message with cost and usage information
   class ResultMessage < Type
+    # model_usage maps model name => per-model usage Hash, passed through
+    # verbatim from the CLI's modelUsage field, so its keys are camelCase
+    # (matches the TypeScript/Python SDKs' ModelUsage shape): inputTokens,
+    # outputTokens, cacheReadInputTokens, cacheCreationInputTokens,
+    # webSearchRequests, costUSD, contextWindow, maxOutputTokens, plus
+    # optional canonicalModel (canonical id used for the pricing lookup —
+    # may differ from the raw model-string key for provider-specific
+    # ids/aliases) and provider ('firstParty', 'bedrock', 'vertex', ...).
+    #
+    # terminal_reason says why the query loop ended ("completed",
+    # "max_turns", "aborted_streaming", ...). "aborted_streaming" /
+    # "aborted_tools" mean the turn was cancelled via Client#interrupt (an
+    # interrupt control request). nil when the CLI did not report one
+    # (older CLI versions, or a result that bypassed the query loop such
+    # as a local slash command).
     attr_accessor :subtype, :duration_ms, :duration_api_ms, :is_error,
                   :num_turns, :session_id, :stop_reason, :total_cost_usd, :usage,
                   :result, :structured_output,
-                  :model_usage,        # Hash of { model_name => usage_data }
+                  :model_usage,        # Hash of { model_name => usage_data }, see above
                   :permission_denials, # Array of { tool_name:, tool_use_id:, tool_input: }
                   :errors,             # Array of error strings (present on error subtypes)
                   :uuid,
                   :fast_mode_state,    # "off", "cooldown", or "on"
-                  :api_error_status    # Integer HTTP status (429, 500, 529) on api_error subtype (CLI 2.1.110+)
+                  :api_error_status,   # Integer HTTP status (429, 500, 529) on api_error subtype (CLI 2.1.110+)
+                  :terminal_reason     # why the query loop ended, see above
 
     attr_reader :deferred_tool_use     # DeferredToolUse, populated when a PreToolUse hook deferred
 

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -18,6 +18,7 @@ require_relative 'claude_agent_sdk/transcript_mirror_batcher'
 require_relative 'claude_agent_sdk/session_resume'
 require_relative 'claude_agent_sdk/session_mutations'
 require_relative 'claude_agent_sdk/fiber_boundary'
+require_relative 'claude_agent_sdk/option_warnings'
 require 'async'
 require 'securerandom'
 
@@ -411,6 +412,10 @@ module ClaudeAgentSDK
       configured_options = options.dup_with(permission_prompt_tool_name: 'stdio')
     end
 
+    # Advisory: warn if other options shadow the can_use_tool callback.
+    # After the ArgumentError validations so invalid configs raise, not warn.
+    OptionWarnings.warn_if_can_use_tool_shadowed(options)
+
     # Fail fast on invalid session_store combinations before spawning the CLI.
     SessionStores.validate_session_store_options(configured_options)
 
@@ -680,6 +685,10 @@ module ClaudeAgentSDK
         configured_options = @options.dup_with(permission_prompt_tool_name: 'stdio')
       end
 
+      # Advisory: warn if other options shadow the can_use_tool callback.
+      # After the ArgumentError validations so invalid configs raise, not warn.
+      OptionWarnings.warn_if_can_use_tool_shadowed(@options)
+
       # Fail fast on invalid session_store combinations before spawning the CLI.
       # Configuration validation is a usage error, like the ArgumentErrors
       # above — deliberately outside the on_error notify scope.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Community Contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-14 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -129,6 +129,7 @@ files:
 - lib/claude_agent_sdk/instrumentation/otel.rb
 - lib/claude_agent_sdk/message_parser.rb
 - lib/claude_agent_sdk/observer.rb
+- lib/claude_agent_sdk/option_warnings.rb
 - lib/claude_agent_sdk/query.rb
 - lib/claude_agent_sdk/sdk_mcp_server.rb
 - lib/claude_agent_sdk/session_mutations.rb