claude-agent-sdk 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0738568951864f8bf79353f7477f23356c0d04e60900ca346dab0bcc099dbe46'
-  data.tar.gz: 5136e71504b5078bb3e6fbcc38d34ee2151239be909d275f0972ef40a052a8ff
+  metadata.gz: 48fe05a71686f61555d5985ac8fe92e5d08b1ac530f1c2e2bb071f4d6b0fdb81
+  data.tar.gz: 669eedb9627e578e893e3e214271c172a0169d07fd9f60493c5c2d47c5540acb
 SHA512:
-  metadata.gz: 61d60a87a8202259abc051f7b642d79c3b2c49f1f53a44ad588a69669578d170415860a584ce8e487a81566b1fc51c86a76cb83b0f47f78bd051fdc07e20276e
-  data.tar.gz: f8a8b46e371a290885f33806fb3a67cf95494ed59003749c54ab68c33123d32f9d80ea3f576262201f08fefa5d14f0d4947edd2245c376a045fbdc10b5f79677
+  metadata.gz: 7efcdba28fd54e81ddbf4b24ae01e14fde11c9c111f39241f65901eb23453d938e4e1be0fee3493fc034f0e81f0ec8373664d68a061d029b280e01f2a7ed4ad0
+  data.tar.gz: 2fb7a50378cb0bd44408b2d31737bd4fc1ec51162473e1417dcd1be58c851b5e369c9de9313edfa48425a5e36d058ccade91cf47bf5681251eeb9fa3c2a89031

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-07-31
+
+### Added
+- **Opt-in fiber-native callback execution: `callback_scheduling: :inline`** (#47). By default the SDK hops every user callback (message blocks, hooks, permission callbacks, SDK MCP handlers, observers) to a plain thread so thread-keyed libraries (ActiveRecord, pg, …) never see the async gem's Fiber scheduler. Hosts that are fiber-isolated end to end — e.g. solid_queue fiber workers (`fibers: N`) with `ActiveSupport::IsolatedExecutionState.isolation_level = :fiber` — can now pass `ClaudeAgentOptions.new(callback_scheduling: :inline)` (or set it globally via `ClaudeAgentSDK.configure`) to run callbacks in place on the reactor fiber: `Fiber.scheduler` is live inside callbacks, no per-call threads exist to strand AR connections, and the session can live directly on the job fiber. This matches the Python SDK's execution model (async callbacks run natively on the event loop). Default behavior is unchanged. In `:inline` mode hook timeouts become cooperative cancellations (the hook is interrupted at its next suspension point and its `ensure` blocks run) instead of hard thread abandonment; `SessionStore` adapter calls intentionally stay on threads so a wedged adapter can never stall the reactor. The SDK warns once when `:inline` is enabled under `isolation_level == :thread`. See "Fiber workers (solid_queue)" in docs/rails.md.
+- `ClaudeAgentSDK.offload { }` — public escape hatch for `:inline` hosts: runs a heavy piece of a callback on a plain thread instead of the reactor fiber. Shields the reactor from scheduler-opaque blocking that releases the GVL (native DB drivers, file/socket I/O); turns pure-Ruby CPU work into GVL time-slicing instead of a hard stall. A C extension that holds the GVL for the whole computation still freezes the process — move such work to a subprocess. No-op outside a reactor.
+
+## [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.25.0'
 ```
 
 Then `bundle install`, or install directly: `gem install claude-agent-sdk`.
@@ -210,7 +210,7 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 | Structured output, thinking config, budget, fallback model, advisor model, beta features, sandbox, bare mode, file checkpointing | [docs/configuration.md](docs/configuration.md) |
 | Session listing, reading, renaming, tagging, deleting, forking, resume-at-message | [docs/sessions.md](docs/sessions.md) |
 | OpenTelemetry tracing, Langfuse setup, custom observers | [docs/observability.md](docs/observability.md) |
-| Rails integration (fiber safety, ActionCable, sessions, jobs, HTTP MCP, observability initializer) | [docs/rails.md](docs/rails.md) |
+| Rails integration (fiber safety, solid_queue fiber workers / `callback_scheduling: :inline`, ActionCable, sessions, jobs, HTTP MCP, observability initializer) | [docs/rails.md](docs/rails.md) |
 | Message, content block, and configuration type reference | [docs/types.md](docs/types.md) |
 | Error handling, exception hierarchy, timeout configuration | [docs/errors.md](docs/errors.md) |
 

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/rails.md

@@ -6,7 +6,7 @@ The SDK integrates well with Rails applications. Below are the common patterns.
 
 The SDK depends on [`async`](https://github.com/socketry/async), which installs a Fiber scheduler that multiplexes fibers onto a single OS thread and intercepts IO so blocking calls yield to siblings. Most mature Ruby libraries are thread-safe but not fiber-safe — they key state (checked-out DB connections, per-thread caches, request stores) on `Thread.current`. When the scheduler interleaves two fibers on one thread, those fibers share the same state slot, and interleaved IO on a shared connection silently corrupts wire protocols. This affects every DB driver keyed by thread (`pg`, `mysql2`, `sqlite3`), ActiveRecord's connection pool, and HTTP/cache clients pooled per thread.
 
-You do **not** need to think about this. The SDK hops to a plain thread at every user-callback boundary — message blocks given to `query` / `Client`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so your code runs with no Fiber scheduler active and inherits the ordinary thread-keyed assumptions every Rails / Sidekiq / Kamal app already makes:
+You do **not** need to think about this. By default (`callback_scheduling: :thread`; see the fiber-workers section below for the opt-in alternative) the SDK hops to a plain thread at every user-callback boundary — message blocks given to `query` / `Client`, SDK MCP tool handlers, hooks, permission callbacks, and observer methods — so your code runs with no Fiber scheduler active and inherits the ordinary thread-keyed assumptions every Rails / Sidekiq / Kamal app already makes:
 
 ```ruby
 tool = ClaudeAgentSDK.create_tool('lookup_user', 'Look up a user', { id: Integer }) do |args|
@@ -21,6 +21,51 @@ end
 
 The trade-off: because callbacks run on a plain thread rather than inside an `Async::Task`, fiber-specific primitives aren't available to them — `Async::Task.current` will raise "No async task available". If a callback wants cooperative concurrency it should open its own `Async { }` block. In practice, callbacks typically do some Ruby work, call external services, and return — so this rarely matters. If you wrap your own call site in an outer `Async { }` block, the scheduler is visible to your code again; you've opted in, and whatever fiber-safety rules your app uses apply there.
 
+## Fiber workers (solid_queue) and `callback_scheduling: :inline`
+
+[solid_queue 728](https://github.com/rails/solid_queue/pull/728) added a fiber-based worker mode: workers configured with `fibers: N` run claimed jobs as fibers on one async reactor thread — built for exactly the long-lived, I/O-bound "LLM streaming" jobs this SDK produces. It requires the app to be fiber-isolated end to end:
+
+```ruby
+# config/application.rb
+ActiveSupport::IsolatedExecutionState.isolation_level = :fiber
+```
+
+On Rails 7.2+, ActiveRecord releases connections between queries under fiber isolation, so fiber counts can far exceed the pool size (e.g. 50 fibers on 25 connections).
+
+In such a host the default thread hop works *against* you: every callback is ejected from the reactor onto a fresh bare thread, where `Fiber.scheduler` is `nil` (reactor APIs like `Async::Task#stop` / `Async::Notification` are unusable), and an implicitly checked-out AR connection dies with the throwaway thread (stranded until the reaper reclaims it). For these hosts the SDK offers opt-in inline scheduling:
+
+```ruby
+# config/initializers/claude_agent_sdk.rb — process-wide, matching
+# isolation_level's process-wide nature. Only set this in processes that run
+# fiber workers; or pass it per-session via ClaudeAgentOptions instead.
+ClaudeAgentSDK.configure do |config|
+  config.default_options = { callback_scheduling: :inline }
+end
+```
+
+With `:inline`, every user callback — message blocks, hooks, permission callbacks, SDK MCP handlers, observers — runs in place on the reactor fiber of the job. This is the same execution model as the Python SDK (async callbacks run natively on the event loop). Concretely:
+
+- `Fiber.scheduler` is live inside callbacks; reactor primitives work directly. DB access goes through the Rails 7.2+ fiber-aware pool under the same assumptions as the rest of your fiber-worker jobs.
+- No per-call threads exist, so nothing can strand an AR connection.
+- The whole SDK session can live directly on the job fiber — no bridge threads. `Client#connect` already requires an Async context, and the transport's pipe I/O is scheduler-aware.
+- Hook timeouts become **cooperative**: a timed-out inline hook is cancelled at its next suspension point (its `ensure` blocks run), instead of being abandoned on a worker thread. A CPU-stuck hook cannot be timed out.
+- The CLI's cancellation of an in-flight callback (e.g. permission prompt superseded) can now actually interrupt it at a suspension point.
+
+The one real risk: **scheduler-opaque blocking stalls the whole reactor.** CPU-bound work or a GVL-holding C extension inside an inline callback blocks every job on that worker, not just yours. Blocking that releases the GVL and pure-Ruby CPU work can be moved onto a thread explicitly:
+
+```ruby
+tool = ClaudeAgentSDK.create_tool('lookup', 'Query legacy DB', { id: String }) do |args|
+  row = ClaudeAgentSDK.offload { legacy_client.fetch(args[:id]) }  # plain thread
+  { content: [{ type: 'text', text: row.to_json }] }
+end
+```
+
+`ClaudeAgentSDK.offload` is a no-op outside a reactor, so it's safe to call unconditionally. Be precise about what it protects, though: it fully shields the reactor from blocking calls that *release* the GVL (native DB drivers, file/socket I/O the scheduler can't see), and it turns pure-Ruby CPU work from a hard stall into GVL time-slicing (added latency for sibling jobs, not starvation). A C extension that **holds** the GVL for the whole computation still freezes the process — `offload` cannot help there; run that work in a subprocess.
+
+Preconditions, spelled out: `:inline` is only correct when the process satisfies the same requirements as solid_queue's fiber workers — `isolation_level = :fiber`, Rails 7.2+ for AR, and no thread-keyed libraries used inside callbacks without a fiber-aware wrapper. The SDK warns once if it detects `:inline` under `isolation_level == :thread`. Everything else (Puma request threads, threaded Sidekiq/solid_queue workers) should stay on the default `callback_scheduling: :thread`.
+
+Note that `SessionStore` adapter calls (`#append` / `#load`) intentionally stay on threads even in `:inline` mode — their timeouts are hard bounds (`Thread#join`) so a wedged store adapter can never stall the reactor.
+
 ## ActionCable Streaming
 
 Stream Claude responses to the frontend in real-time:

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/fiber_boundary.rb

@@ -24,6 +24,26 @@ module ClaudeAgentSDK
   #
   # No-op when no scheduler is active, so it's cheap to use unconditionally.
   #
+  # OPT-IN INLINE MODE: hosts that are already fiber-isolated (e.g. Rails
+  # apps with `IsolatedExecutionState.isolation_level = :fiber` running
+  # solid_queue fiber workers) can pass `scheduling: :inline` to run
+  # callbacks in place on the reactor fiber instead of hopping. This is the
+  # same code path as the no-scheduler case — semantically the already-
+  # shipped synchronous path, and Python SDK parity (async callbacks run
+  # natively on the event loop there). The mode is plumbed per-call from
+  # `ClaudeAgentOptions#callback_scheduling` — never a thread-local (the
+  # reactor thread is shared by many fibers, so a set/reset window across
+  # suspension points would leak across sessions). The one path a call
+  # argument cannot cross (SDK-MCP dispatch through the mcp gem) carries
+  # it via a scoped, invalidatable fiber-storage entry instead — see
+  # SCHEDULING_KEY / SchedulingScope below.
+  #
+  # A `timeout:` always forces the thread hop regardless of scheduling —
+  # `Thread#join(timeout)` is a hard bound that can abandon a wedged call,
+  # which cooperative `with_timeout` cancellation cannot guarantee. The
+  # store-adapter call sites (TranscriptMirrorBatcher, SessionResume) rely
+  # on this to never stall the reactor on a wedged adapter.
+  #
   # The thread hop severs `break`/`return`/`next` from the surrounding method,
   # so SDK loops yielding user callbacks must keep loop control outside the
   # invoked block (see `Client#receive_response`); user-initiated `break` is
@@ -44,6 +64,57 @@ module ClaudeAgentSDK
     # in-flight call may still complete).
     class JoinTimeout < StandardError; end
 
+    # Cancellation injected into INLINE user callbacks by timeout
+    # enforcement (hook timeouts under scheduling: :inline) — user code
+    # should let it propagate. Deliberately
+    # NOT a StandardError: the exception is raised inside user code at a
+    # suspension point, and a callback's ordinary `rescue StandardError`
+    # must not be able to swallow the cancellation and convert an expired
+    # hook into a success (Async::TimeoutError is a StandardError, so it
+    # cannot be injected directly). The SDK translates it back to
+    # Async::TimeoutError once control returns from user code.
+    # @api private
+    class InlineCancellation < Exception; end # rubocop:disable Lint/InheritException
+
+    # Fiber-storage key carrying the dispatching session's callback
+    # scheduling mode across the SDK-MCP dispatch path (Query ->
+    # MCP::Server -> dynamic tool class). Fiber storage is per-fiber, so
+    # concurrent sessions with different modes sharing one SdkMcpServer
+    # instance cannot cross-contaminate — unlike mutating the shared
+    # server (last-writer-wins, persists past close) or a thread-local
+    # (the reactor thread is shared by many fibers).
+    # @api private
+    SCHEDULING_KEY = :claude_agent_sdk_callback_scheduling
+
+    # The value stored under SCHEDULING_KEY: a
+    # closable carrier rather than a bare symbol. Fiber-storage inheritance
+    # copies the storage HASH but shares value REFERENCES, so every fiber
+    # (and thread) created during a dispatch inherits this same object.
+    # Restoring the dispatching fiber's own slot is therefore not enough —
+    # a child task spawned inside a handler that outlives the dispatch
+    # would keep reading the stale mode forever. Closing the scope in the
+    # dispatch's ensure invalidates it for ALL inheritors at once; readers
+    # fall back to the server's own default. Benign race on close vs. a
+    # concurrent reader: either value is a defensible mode for a call that
+    # straddles the dispatch boundary.
+    # @api private
+    class SchedulingScope
+      attr_reader :mode
+
+      def initialize(mode)
+        @mode = mode
+        @active = true
+      end
+
+      def active?
+        @active
+      end
+
+      def close
+        @active = false
+      end
+    end
+
     # Sentinel returned by .invoke_iteration when the user block attempted `break`.
     class Break
       attr_reader :value
@@ -59,10 +130,15 @@ module ClaudeAgentSDK
     # Returns the block's value. Exceptions propagate to the caller.
     #
     # With +timeout+ (seconds) the thread hop happens unconditionally — even
-    # without a scheduler — so the bound is enforced in plain synchronous code
-    # too; JoinTimeout is raised when it expires.
-    def invoke(timeout: nil, &block)
-      return block.call if timeout.nil? && !Fiber.scheduler
+    # without a scheduler or with `scheduling: :inline` — so the bound is
+    # enforced in plain synchronous code too; JoinTimeout is raised when it
+    # expires.
+    #
+    # With `scheduling: :inline` (and no timeout) the block runs in place on
+    # the current fiber, scheduler or not. The caller opts in via
+    # `ClaudeAgentOptions#callback_scheduling`.
+    def invoke(timeout: nil, scheduling: :thread, &block)
+      return block.call if timeout.nil? && (scheduling == :inline || !Fiber.scheduler)
 
       thread = Thread.new(&block)
       thread.report_on_exception = false
@@ -77,10 +153,10 @@ module ClaudeAgentSDK
     # LocalJumpError(reason: :break) on the worker thread; translate it into
     # a Break sentinel so the SDK loop can break on the calling fiber.
     # Returns Break when the user broke, nil when the block completed.
-    # Without a scheduler the block runs in place and `break` unwinds
-    # natively, never reaching the translation.
-    def invoke_iteration(block, *args)
-      invoke do
+    # Without a scheduler (or with `scheduling: :inline`) the block runs in
+    # place and `break` unwinds natively, never reaching the translation.
+    def invoke_iteration(block, *args, scheduling: :thread)
+      invoke(scheduling: scheduling) do
         block.call(*args)
         nil
       rescue LocalJumpError => e

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