claude-agent-sdk 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a678100ed5fdb6ba11e9895e534b4a87df8a2b8a57d0a0a459900d81d88bf593
-  data.tar.gz: 8bc65b4056f315abe23a3f1f9089402819137b2abb38cbd1d57afdcfe5366e42
+  metadata.gz: ecc2b309c23e9e07ce4d03aed2997d7f8c2b3fc8909f48601bfd3c1b0ca93152
+  data.tar.gz: f7c56c6cde059b2edf3b57e633ac49fa761074d633a9532f503ff2261b846795
 SHA512:
-  metadata.gz: b7ec8544374217a99458cc3557504777d5ac4e2a66cab706f9322f326f43220b312fc877388983961a688a1e3c55b3493bae1458c4a7ed71a7614bfe2e6bc0aa
-  data.tar.gz: b119e67d145088a4adbf832f611eaf5d7047c255a2037e5a76372f6ac319d8d6d7addaf4af062b58acbb12ba9acf17799027b89175c02498f65471320683533a
+  metadata.gz: 422bd92af76c1785ce33e3c50b7750d74c4dbdeb096445a0f441497be2e3f5f41a463cabd7f55374606fa236c524ae356e4a282cd75db9c7fde3fbbd4e8e07e2
+  data.tar.gz: 17b52f5f14f603cadb4fdc989b4236a5d75c4862f1ec8672014548288a67f886ede5695afce8078327d779331da87b82cc5fbfcc3fadee419037615ce7bc134b

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-30
+
+Syncs with Python SDK 0.2.162. Additive only: one new option and a fix to when `query()` closes stdin.
+
+### Added
+- **`ClaudeAgentOptions#verbatim_prompts`** (default `false`; Python SDK #1269). When `true`, every user message the SDK writes carries `client_composed: true`: String prompts and each message of a streamed prompt, through `query`, `Client#connect` and `Client#query`. Claude Code then delivers the text as written, with no `@path` file expansion and no slash-command dispatch. Use it when a prompt includes text your end user did not type. `tools: []` and `disallowed_tools` do not stop `@path` expansion, which reads the file before the model runs. While the option is on, a caller's `client_composed` key is overwritten, and caller Hashes are never mutated. A streamed JSONL String is parsed and re-serialized; one that is not a single JSON object raises `ArgumentError` rather than going out unmarked. `Client` reads the option once, at `connect`. On current CLIs such a turn also skips the turn-start attachment pass (nested `CLAUDE.md` and rules files, skill and tool listings). Requires Claude Code 2.1.248 or later; the SDK warns when it connects to an older CLI with the option on. See `docs/configuration.md`.
+- Development only, nothing ships in the gem: TLA+ models in `formal/tla/` of the two most concurrency-sensitive designs. `CLIInstaller.tla` covers `CLIInstaller.install`'s publish order, the in-lock dist-tag resolve and the stale-temp sweep. `ControlProtocol.tla` covers the outbound control-request waiter protocol in `Query`. `formal/tla/run.sh` model-checks both with TLC. It confirms that the shipped design passes and that each alternative the source comments reject, including the historical rename-then-record order, produces a counterexample.
+
+### Changed
+- `CLIInstaller::PINNED_CLI_VERSION` moves from 2.1.280 (the 1.0.0 pin) to **2.1.285**, the CLI the Python SDK 0.2.162 bundles. `CLIInstaller.install_pinned` installs it. It honors both `client_composed` (`verbatim_prompts`) and `CLAUDE_CODE_SDK_READS_SESSION_STATE` (the fix below).
+
+### Fixed
+- **`query()` with hooks, `can_use_tool` or SDK MCP servers no longer closes stdin while a follow-up turn is still owed** (Python SDK #1279, fixing Python issue #1190). A background subagent that finished just before the turn's result was already off the in-flight ledger, so stdin closed at that result, and the follow-up turn its completion triggered had every hook, permission and SDK MCP request fail with "Stream closed" (the model reported the tool as refused). The transport now sets `CLAUDE_CODE_SDK_READS_SESSION_STATE=1` unless `options.env` or the environment already names it (in any case; a `nil` value in `options.env` unsets it). The CLI then sends `session_state_changed` frames marked `sdk_host_only`, which the SDK drops from the message stream for `query()` and `Client` alike. `query()` keeps stdin open until the CLI reports `idle` after a result:
+  - The wait between turns is bounded by `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`, read from `options.env` and then the environment; the default is 10 minutes and `0` means no limit. The clock restarts at each result and at each `running`. A main-thread turn, the CLI reporting `requires_action`, a tracked background agent and a hook, permission or SDK MCP request the SDK is still answering each stop it.
+  - With an Enumerable prompt, each message written waits for its own run. Work the CLI takes up after the run ended reopens it.
+  - A CLI that sends no state (2.1.282 and earlier) gets the old behavior: stdin closes at the first result with no tracked task in flight.
+  - Background agents, bounded monitors and MCP tasks can now keep a one-shot run open, up to the ceiling. Background shells, persistent monitors and remote agents do not, because the CLI leaves them out of its `running` report.
+  - `SessionStateChangedMessage` reaches your code only if you set `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1` yourself; the SDK never sets it.
+  - A custom transport must pass `CLAUDE_CODE_SDK_READS_SESSION_STATE=1` to the CLI itself to get this behavior (see `docs/client.md`); the E2B example transport now does.
+
 ## [1.0.0] - 2026-09-23
 
 **1.0 is a stability commitment.** From here on the public API — everything documented in `docs/` plus the YARD docs without `@api private`, now also described by the RBS signatures in `sig/` — follows Semantic Versioning: no breaking changes within 1.x. Upgrading from 0.x? Read [UPGRADING-1.0.md](UPGRADING-1.0.md) and run your suite on 0.37 first.

data/docs/client.md

@@ -117,6 +117,17 @@ A transport must implement six methods:
 | `close` | Terminate and clean up |
 | `ready?` | Report whether the transport can accept I/O |
 
+**Environment your transport should give the CLI.** `SubprocessCLITransport`
+sets a few variables that a custom transport has to set itself. The one that
+changes SDK behavior is `CLAUDE_CODE_SDK_READS_SESSION_STATE=1`: with it, the
+CLI reports its session state, and a one-shot `query()` with hooks,
+`can_use_tool` or SDK MCP servers keeps stdin open until the CLI reports
+`idle`. That is what lets a follow-up turn woken by a background subagent get
+its control requests answered. Without it, `query()` closes stdin at the first
+result with no tracked task in flight, the pre-1.1 behavior. The state frames
+arrive marked `sdk_host_only`, and the SDK drops them from your message
+stream.
+
 Then plug it into `Client` via `transport_class:` / `transport_args:`. All connect orchestration (option transforms, MCP extraction, hook conversion, Query lifecycle) is handled for you.
 
 ```ruby

data/docs/configuration.md

@@ -245,6 +245,48 @@ options = ClaudeAgentSDK::ClaudeAgentOptions.new(
 
 See [examples/bare_mode_example.rb](https://github.com/ya-luotao/claude-agent-sdk-ruby/blob/main/examples/bare_mode_example.rb).
 
+## Verbatim Prompts
+
+Claude Code expands an `@/absolute/path` token anywhere in a user message into
+that file's contents, and dispatches a leading `/name` as a slash command. The
+expansion happens before the model runs and without a tool call, so `tools: []`,
+`allowed_tools` and `disallowed_tools` do not stop it. If your prompt includes
+text your end user did not type (earlier turns, tool output, third-party
+content), set `verbatim_prompts` so that text cannot make Claude Code read a
+local file:
+
+```ruby
+options = ClaudeAgentSDK::ClaudeAgentOptions.new(verbatim_prompts: true)
+ClaudeAgentSDK.query(prompt: text_that_may_contain_at_paths, options: options) { |message| ... }
+```
+
+Every user message the SDK writes is then marked `client_composed`, and Claude
+Code delivers it exactly as written. That covers String prompts and every
+message of a streamed prompt, through `ClaudeAgentSDK.query`, `Client#connect`
+and `Client#query`.
+
+- **No per-message opt-out.** A `client_composed` key on a streamed message
+  Hash is overwritten. For per-turn control, leave the option off and set
+  `client_composed: true` on individual streamed messages.
+- Your message Hashes are never mutated.
+- A streamed JSONL String is parsed, marked and re-serialized. One that is not
+  a single JSON object raises `ArgumentError` instead of going out unmarked
+  (on the background streaming paths the stream stops with a warning, like any
+  stream error).
+- `Client` reads the option once, at `connect`.
+- **It skips more than `@path` expansion.** On current Claude Code versions a
+  turn delivered this way skips the whole turn-start attachment pass:
+  `@server:resource` MCP mentions are not expanded, and the prompt goes without
+  the context Claude Code normally attaches (nested `CLAUDE.md` and rules files,
+  skill and tool listings, other per-turn reminders). The pass between tool
+  calls still runs, so most of that context arrives after the turn's first tool
+  call.
+- Requires Claude Code **2.1.248** or later. Older versions ignore the field
+  and still expand prompts; the SDK prints a warning when it connects to one
+  with the option on.
+
+Matches the Python SDK's `verbatim_prompts`.
+
 ## Forwarding Subagent Text
 
 By default only `tool_use` / `tool_result` blocks from subagents (spawned via

data/lib/claude_agent_sdk/cli_installer.rb

@@ -53,7 +53,7 @@ module ClaudeAgentSDK
     # Single source of truth: bumped here (and only here) by
     # .github/workflows/cli-pin-bump.yml or a Python-sync release, so a
     # Dependabot bump of the gem carries the CLI forward with it.
-    PINNED_CLI_VERSION = '2.1.280'
+    PINNED_CLI_VERSION = '2.1.285'
     # @api private
     BINARY_NAME = 'claude'
     # @api private

data/lib/claude_agent_sdk/query.rb

@@ -49,6 +49,93 @@ module ClaudeAgentSDK
     # status, or it will hang the query (see #track_task_lifecycle).
     DEFERRING_TASK_TYPES = %w[local_agent local_workflow].freeze
 
+    # The CLI's own wait for background work once stdin is closed; the SDK
+    # bounds its wait for the CLI's "idle" by the same value
+    # (#arm_run_end_ceiling, Python #1279).
+    RUN_END_CEILING_ENV_VAR = 'CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS'
+    DEFAULT_RUN_END_CEILING_MS = 600_000
+    # The longest ceiling honored (~24.8 days), as in the TypeScript and
+    # Python SDKs, whose timers cannot run longer.
+    MAX_RUN_END_CEILING_MS = (2**31) - 1
+    # Frame types that mark a main-thread turn under way (when they carry no
+    # parent_tool_use_id), and the states that do not re-arm the ceiling.
+    TURN_FRAME_TYPES = %w[assistant stream_event].freeze
+    NON_RUNNING_SESSION_STATES = %w[idle requires_action].freeze
+
+    # Read CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS from where the CLI gets it:
+    # +options_env+ (ClaudeAgentOptions#env) overrides the inherited
+    # environment, as it does for the subprocess, and a key present with a nil
+    # value is unset in the child, so the CLI falls back to its default. 0
+    # means no limit. Only plain non-negative integers are read; anything else
+    # falls back to the CLI's default of 10 minutes, including spellings the
+    # CLI itself also reads, such as 1e6 (as in the Python SDK).
+    def self.run_end_ceiling_ms(options_env)
+      env = (options_env || {}).transform_keys(&:to_s)
+      raw = env.key?(RUN_END_CEILING_ENV_VAR) ? env[RUN_END_CEILING_ENV_VAR] : ENV.fetch(RUN_END_CEILING_ENV_VAR, nil)
+      digits = raw.to_s.strip
+      digits.match?(/\A\d+\z/) ? Integer(digits, 10) : DEFAULT_RUN_END_CEILING_MS
+    end
+
+    # One run's end, set at most once (the Python SDK's per-run anyio.Event).
+    # A waiter holds the object it started waiting on, so a run that ends and
+    # is then reopened (#reopen_run swaps in a fresh RunEnd) still releases the
+    # waiters the ended run woke, while later waits wait for the new run.
+    # Reactor-only, like every caller.
+    class RunEnd
+      def initialize
+        @ended = false
+        @condition = Async::Condition.new
+      end
+
+      def ended?
+        @ended
+      end
+
+      def end!
+        return if @ended
+
+        @ended = true
+        @condition.signal
+      end
+
+      def wait
+        @condition.wait until @ended
+      end
+    end
+
+    # Apply ClaudeAgentOptions#verbatim_prompts to one outgoing user message
+    # (Python #1269's stamp_user_message). Off: returns +message+ unchanged.
+    # On: returns a new Hash with `client_composed: true`, dropping any
+    # caller-supplied value under either key spelling first (JSON.generate
+    # would otherwise emit the key twice). A pre-serialized JSONL String — a
+    # Ruby-only input shape — is parsed, marked and handed back as a Hash; one
+    # that is not a single JSON object raises ArgumentError, because sending it
+    # unmarked would silently defeat the option.
+    def self.stamp_user_message(message, verbatim_prompts)
+      return message unless verbatim_prompts
+
+      hash = message.is_a?(Hash) ? message : parse_streamed_message(message.to_s)
+      hash.reject { |key, _| key.to_s == 'client_composed' }.merge(client_composed: true)
+    end
+
+    # The serialized line for one outgoing user message, stamped per
+    # verbatim_prompts. Hashes are JSON-generated; other items pass through
+    # as their String form unless they must be stamped.
+    def self.serialize_user_message(message, verbatim_prompts)
+      stamped = stamp_user_message(message, verbatim_prompts)
+      stamped.is_a?(Hash) ? JSON.generate(stamped) : stamped.to_s
+    end
+
+    def self.parse_streamed_message(string)
+      parsed = JSON.parse(string)
+      return parsed if parsed.is_a?(Hash)
+
+      raise ArgumentError, "verbatim_prompts: a streamed message String must be one JSON object (got #{parsed.class})"
+    rescue JSON::ParserError => e
+      raise ArgumentError, "verbatim_prompts: a streamed message String must be one JSON object (#{e.message})"
+    end
+    private_class_method :parse_streamed_message
+
     # 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
@@ -74,7 +161,8 @@ module ClaudeAgentSDK
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil, # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- initializes every control-protocol concern in one place
                    exclude_dynamic_sections: nil, system_prompt_snapshot: nil, skills: nil,
                    forward_subagent_text: false, agent_progress_summaries: nil,
-                   callback_scheduling: :thread, callback_wrapper: nil)
+                   callback_scheduling: :thread, callback_wrapper: nil, verbatim_prompts: false,
+                   run_end_ceiling_ms: DEFAULT_RUN_END_CEILING_MS)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
@@ -88,6 +176,8 @@ module ClaudeAgentSDK
       @skills = skills
       @forward_subagent_text = forward_subagent_text
       @agent_progress_summaries = agent_progress_summaries
+      @verbatim_prompts = verbatim_prompts
+      @run_end_ceiling_ms = run_end_ceiling_ms
 
       # Control protocol state
       @pending_control_responses = {}
@@ -103,10 +193,30 @@ 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
+      # Ends when the run is over, so the stdin-closing waiter can wake; see
+      # #read_messages and @inflight_tasks below (Python #1088, #1190/#1279).
+      # Work the CLI takes up after the run ended swaps in a fresh one
+      # (#reopen_run).
+      @run_end = RunEnd.new
+      @result_received = false
+      # The CLI's latest session_state_changed state, or nil while it sends
+      # none (a CLI too old to honor CLAUDE_CODE_SDK_READS_SESSION_STATE). A
+      # CLI that reports state stays "running" while a background agent is
+      # live or its completion is still to be handled, and reports "idle" once
+      # no further turn is owed.
+      @session_state = nil
+      # Ends the run if no new turn starts within the ceiling after a result
+      # (#arm_run_end_ceiling). The generation tells a sleeper that woke after
+      # it was cleared or re-armed to stand down.
+      @run_end_ceiling_task = nil
+      @run_end_ceiling_generation = 0
+      # A main-thread turn is under way (its assistant/stream_event frames
+      # have started and its result has not arrived): the ceiling counts only
+      # the wait between turns, so it is not armed meanwhile.
+      @turn_in_progress = false
+      # Set once stdin is closed or the reader is gone: the run then stays
+      # ended, since nothing can wait on a reopened one.
+      @run_final = 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
@@ -119,7 +229,6 @@ module ClaudeAgentSDK
       # reported. Mirrors the TypeScript SDK's `lastErrorResultText`
       # (Query.ts), but keeps the whole payload rather than just the text.
       @last_error_result = nil
-      @first_result_condition = Async::Condition.new
       @task = nil
       @child_tasks = []
       @initialized = false
@@ -376,22 +485,26 @@ module ClaudeAgentSDK
         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 msg_type == 'system'
+            had_tasks_in_flight = !@inflight_tasks.empty?
+            track_task_lifecycle(message)
+            # The ceiling left the last tracked agent alone; the wait between
+            # turns starts over now that it settled.
+            rearm_run_end_ceiling_between_turns if had_tasks_in_flight && @inflight_tasks.empty?
+            if message[:subtype] == 'session_state_changed'
+              on_session_state(message[:state])
+              # Frames the CLI sent only because the transport asked for them
+              # (CLAUDE_CODE_SDK_READS_SESSION_STATE); the caller did not opt
+              # in, so they never reach the stream, observers or the parser.
+              next if message[:sdk_host_only] == true
+            end
+          end
 
-          if message[:type] == 'result'
+          if msg_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
-            # 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
+            on_result
             @last_error_result = message[:is_error] ? message : nil
           elsif !(msg_type == 'system' && message[:subtype] == 'session_state_changed')
             # Anything other than the post-turn session_state_changed marker
@@ -399,6 +512,14 @@ module ClaudeAgentSDK
             # crash, not the expected exit from a prior error result. Mirrors
             # the Python/TypeScript SDK reset logic.
             @last_error_result = nil
+            # A main-thread turn is under way, so the ceiling stops (it counts
+            # only the wait between turns, as the CLI's does) and the run
+            # reopens even if the ceiling ended it while no state changed.
+            if TURN_FRAME_TYPES.include?(msg_type) && message[:parent_tool_use_id].nil?
+              @turn_in_progress = true
+              reopen_run
+              clear_run_end_ceiling
+            end
           end
           # Regular SDK messages go to the queue
           @message_queue.enqueue(message)
@@ -447,10 +568,11 @@ module ClaudeAgentSDK
       begin
         flush_transcript_mirror
       ensure
-        unless @first_result_received
-          @first_result_received = true
-          @first_result_condition.signal
-        end
+        # Unblock the stdin-closing waiter so it doesn't stall on early exit;
+        # with the reader gone the run stays ended. Also stops a pending
+        # ceiling sleeper, which would otherwise keep the reactor alive.
+        @run_final = true
+        end_run
         # Always signal end of stream
         @message_queue.enqueue({ type: 'end' })
       end
@@ -500,6 +622,131 @@ module ClaudeAgentSDK
       end
     end
 
+    # A result ends a turn, not necessarily the run: a background agent that
+    # finished just before it still wakes the session for another turn, whose
+    # hook, permission and SDK MCP requests need stdin (Python #1190/#1279). A
+    # CLI that reports session state stays "running" while such a turn is
+    # owed, so wait for "idle" (some hosts send it just before the result).
+    # Without state events the result is all there is to go on.
+    def on_result
+      @result_received = true
+      @turn_in_progress = false
+      if @session_state.nil? || @session_state == 'idle' || !bidirectional_needs?
+        maybe_end_run
+      elsif @session_state != 'requires_action'
+        # While the SDK is still answering a request the ceiling waits for
+        # the "running" that follows.
+        arm_run_end_ceiling
+      end
+    end
+
+    # Track the CLI's session_state_changed state (Python #1279).
+    def on_session_state(state)
+      @session_state = state
+      if state == 'idle'
+        maybe_end_run if @result_received
+        return
+      end
+      # Work the CLI took up after the run ended (a finished background task
+      # woke it) reopens the run until the next "idle".
+      reopen_run
+      if state == 'requires_action'
+        # The host is answering a request; stdin must outlast it.
+        clear_run_end_ceiling
+      else
+        rearm_run_end_ceiling_between_turns
+      end
+    end
+
+    # End the run unless a tracked background task is still in flight: such
+    # a task may still need hook/SDK-MCP control responses over stdin
+    # (Python #1088), and its completion wakes the parent for a follow-up
+    # turn whose result (or "idle") ends the run then. A CLI that reports
+    # session state never reports "idle" with an agent still live, so this
+    # matters for CLIs that report "idle" at every turn end or not at all.
+    def maybe_end_run
+      end_run if @inflight_tasks.empty?
+    end
+
+    # The run is over: wake the stdin-closing waiter. Idempotent.
+    def end_run
+      clear_run_end_ceiling
+      @run_end.end!
+    end
+
+    # Reopen an ended run for work that started after it ended. A waiter the
+    # ended run already woke still closes stdin; this makes a later wait
+    # (stream_input's, once its prompts are all written) wait for the new
+    # work too. Once stdin is closed, or the reader is gone, the run stays
+    # ended.
+    def reopen_run
+      @run_end = RunEnd.new if @run_end.ended? && !@run_final
+    end
+
+    # End the run anyway once the ceiling passes with no new turn. The CLI's
+    # own background-wait ceiling only counts once stdin is closed, so without
+    # this, work that never finishes would hold "running", and stdin, open
+    # forever. It counts only the wait between turns: restarted at each result
+    # and whenever the CLI reports "running" again, cleared by main-thread
+    # turn activity and by "requires_action", never armed mid-turn.
+    #
+    # The sleeper is a child of the read task, NOT a #spawn_task entry: it is re-armed at every
+    # result and every "running", and @child_tasks never prunes. The read
+    # task's stop cascades to it, and every exit path clears it (#end_run in
+    # the read loop's ensure, #wait_for_result_and_end_input's ensure), so a
+    # pending sleeper can never keep the enclosing reactor alive.
+    def arm_run_end_ceiling
+      clear_run_end_ceiling
+      # A frame read while close is under way (the result branch flushes the
+      # mirror first) must not leave a sleeper behind either.
+      return if @run_end_ceiling_ms <= 0 || @run_end.ended? || @run_final || @closed ||
+                @turn_in_progress || !bidirectional_needs?
+
+      generation = @run_end_ceiling_generation
+      seconds = [@run_end_ceiling_ms, MAX_RUN_END_CEILING_MS].min / 1000.0
+      @run_end_ceiling_task = @task.async do
+        sleep seconds
+        end_run_at_ceiling(generation)
+      end
+    end
+
+    # Restart the ceiling if the run is between turns, past a result, with
+    # the CLI still reporting work ("running").
+    def rearm_run_end_ceiling_between_turns
+      return unless @result_received
+      return if @session_state.nil? || NON_RUNNING_SESSION_STATES.include?(@session_state)
+
+      arm_run_end_ceiling
+    end
+
+    def end_run_at_ceiling(generation)
+      # Cleared or re-armed while this sleeper was already waking up.
+      return unless generation == @run_end_ceiling_generation
+
+      # Detach before ending the run: #end_run clears the ceiling, and
+      # clearing it must not stop the task running this very method.
+      @run_end_ceiling_task = nil
+      # A tracked background agent still running may still need stdin for its
+      # hook, permission and SDK MCP requests (Python #1088), so it is not cut
+      # off; the ceiling starts over once it settles (#read_messages).
+      return unless @inflight_tasks.empty?
+
+      # A control request the SDK is still answering (a slow hook or SDK MCP
+      # tool) must be able to write its reply, so the clock starts over rather
+      # than closing stdin under it. Ruby-only guard: Python relies on the CLI
+      # reporting requires_action for every such request.
+      return arm_run_end_ceiling unless @inflight_control_request_tasks.empty?
+
+      end_run
+    end
+
+    def clear_run_end_ceiling
+      @run_end_ceiling_generation += 1
+      task = @run_end_ceiling_task
+      @run_end_ceiling_task = nil
+      task&.stop
+    end
+
     # Whether the CLI may still send control requests that need a reply.
     #
     # SDK MCP servers, hooks and the can_use_tool permission callback are all
@@ -1399,45 +1646,62 @@ module ClaudeAgentSDK
                            })
     end
 
-    # Wait for a run-ending result before closing stdin when hooks, SDK MCP
-    # servers or a can_use_tool callback 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). 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.
+    # Wait for the end of the run, when hooks, SDK MCP servers or a
+    # can_use_tool callback may still need to exchange control messages with
+    # the CLI, then close stdin. Their replies are all written to stdin, so it
+    # must stay open until the run ends: at the CLI's "idle" session state
+    # after a result, or, from a CLI that reports no session state, at the
+    # first result with no tracked tasks in flight. A result frame ends one
+    # turn, not necessarily the run: background tasks keep running past it,
+    # or have just finished and still wake the parent for a follow-up turn,
+    # and those turns need stdin for control responses (Python #1088, #1190).
+    #
+    # No timeout bounds a turn (closing stdin mid-turn silently broke
+    # hooks/MCP on turns longer than the old 60s bound; Python c3d96cb). The
+    # wait BETWEEN turns is bounded: if the CLI still reports "running"
+    # CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS (10 minutes by default, 0 for no
+    # limit) after a result with no new turn, the run ends anyway
+    # (#arm_run_end_ceiling). A turn under way, a request the SDK is still
+    # answering and a tracked background agent still in flight (Python #1088)
+    # stop that clock. The run is guaranteed to end: as above, or in
+    # read_messages' ensure when the process exits early.
     #
-    # Known limitation (same as Python's): the condition is one-shot and is
-    # not aware of prompt messages still queued CLI-side, so an Enumerator
-    # prompt yielding several user messages (several turns) releases the hold
-    # at the first turn boundary with no tracked tasks; control requests from
-    # later turns can then find stdin closed. Single-message and String
-    # prompts — the common one-shot shapes — are fully covered.
+    # Known limitation (same as Python's): from a CLI that reports no session
+    # state, a result for an earlier message of an Enumerator prompt still
+    # ends the run even when a later message is already queued CLI-side, so
+    # control requests from that later turn can find stdin closed.
+    # Single-message and String prompts are fully covered.
     def wait_for_result_and_end_input
-      @first_result_condition.wait if !@first_result_received && bidirectional_needs?
+      @run_end.wait if bidirectional_needs?
     ensure
+      @run_final = true
+      clear_run_end_ceiling
       @transport.end_input
     end
 
-    # Stream input messages to transport. NOTE: iteration runs on the
-    # reactor (the deliberate FiberBoundary carve-out — see
-    # fiber_boundary.rb): scheduler-aware blocking (Thread::Queue#pop,
-    # sleep, socket IO) parks only this task; CPU-bound or scheduler-opaque
-    # work in the enumerator must be moved to a producer Thread by the user.
+    # Stream input messages to transport, then close stdin once the run ends
+    # (#wait_for_result_and_end_input). Each message written owes a run of its
+    # own, so the wait is for the last message's run, not an earlier one's.
+    #
+    # NOTE: iteration runs on the reactor (the deliberate FiberBoundary
+    # carve-out — see fiber_boundary.rb): scheduler-aware blocking
+    # (Thread::Queue#pop, sleep, socket IO) parks only this task; CPU-bound or
+    # scheduler-opaque work in the enumerator must be moved to a producer
+    # Thread by the user.
     def stream_input(stream)
       wrote_message = false
       stream.each do |message|
         break if @closed
 
-        serialized = message.is_a?(Hash) ? JSON.generate(message) : message.to_s
-        writeln(serialized)
+        # Serialized first: a message verbatim_prompts cannot mark raises
+        # here, before the run is reopened for a message that never went out.
+        line = Query.serialize_user_message(message, @verbatim_prompts)
+        # This message owes a run of its own, result included: an earlier
+        # one having ended does not end it.
+        reopen_run
+        @result_received = false
+        clear_run_end_ceiling
+        writeln(line)
         wrote_message = true
       end
     rescue StandardError => e
@@ -1446,13 +1710,12 @@ module ClaudeAgentSDK
     ensure
       # Three teardown shapes:
       # - #close in progress (@closed, Async::Stop unwinding): do nothing —
-      #   the transport is about to be closed, and waiting on
-      #   @first_result_condition inside a stopping fiber could suspend
-      #   teardown. Mirrors Python, where cancellation skips this entirely.
+      #   the transport is about to be closed, and waiting on the run's end
+      #   inside a stopping fiber could suspend teardown. Mirrors Python,
+      #   where cancellation skips this entirely.
       # - A turn is in flight (some message reached the CLI): hold stdin
-      #   open until its first result so hooks/SDK MCP control replies can
-      #   still be written (no timeout — the result or process exit is
-      #   guaranteed to signal).
+      #   open until the run ends so hooks/SDK MCP control replies can still
+      #   be written (the run's end or process exit is guaranteed to signal).
       # - No complete message ever reached the CLI (empty stream, or the
       #   stream raised before the first write): no result can ever arrive,
       #   so waiting would park query() forever beside an idle CLI. Close
@@ -1462,6 +1725,7 @@ module ClaudeAgentSDK
         if wrote_message
           wait_for_result_and_end_input
         else
+          @run_final = true
           @transport.end_input
         end
       end

data/lib/claude_agent_sdk/subprocess_cli_transport.rb

@@ -16,6 +16,15 @@ module ClaudeAgentSDK
     DEFAULT_MAX_BUFFER_SIZE = 1024 * 1024 # 1MB buffer limit
     # @api private
     MINIMUM_CLAUDE_CODE_VERSION = '2.0.0'
+    # First Claude Code version that honors `client_composed` on user
+    # messages, which ClaudeAgentOptions#verbatim_prompts relies on.
+    # @api private
+    VERBATIM_PROMPTS_MINIMUM_CLAUDE_CODE_VERSION = '2.1.248'
+    # Asks the CLI for session_state_changed frames marked sdk_host_only,
+    # which Query reads to tell when the run is over and keeps out of the
+    # caller's stream. CLIs that predate it send no frames.
+    # @api private
+    SDK_READS_SESSION_STATE_ENV_VAR = 'CLAUDE_CODE_SDK_READS_SESSION_STATE'
     # @api private
     SKIP_VERSION_CHECK_ENV_VAR = 'CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK'
     # @api private
@@ -288,6 +297,15 @@ module ClaudeAgentSDK
       # under the caller's distributed trace (Python SDK #821 parity). No-op
       # when opentelemetry is not loaded or there is no active span.
       inject_otel_trace_context(process_env, custom_env)
+      # Query waits for the CLI's session_state_changed "idle" before closing
+      # stdin on a run that serves control requests (Python #1279). Ask for
+      # the frames it drops (sdk_host_only) unless the caller named the
+      # variable, in any case, in options.env (a nil value unsets it) or the
+      # inherited environment. CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS stays the
+      # caller's own opt-in to seeing the frames; the SDK never sets it.
+      unless process_env.keys.any? { |key| key.casecmp?(SDK_READS_SESSION_STATE_ENV_VAR) }
+        process_env[SDK_READS_SESSION_STATE_ENV_VAR] = '1'
+      end
       process_env['CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING'] = 'true' if @options.enable_file_checkpointing
       process_env['PWD'] = @cwd.to_s if @cwd
 
@@ -922,6 +940,13 @@ module ClaudeAgentSDK
                       'Some features may not work correctly.'
             warn warning
           end
+
+          verbatim_min_parts = VERBATIM_PROMPTS_MINIMUM_CLAUDE_CODE_VERSION.split('.').map(&:to_i)
+          if @options.verbatim_prompts? && (version_parts <=> verbatim_min_parts).negative?
+            warn "Warning: verbatim_prompts is enabled, but Claude Code version #{version} at #{@cli_path} " \
+                 'ignores it: prompts will still have @path mentions expanded and slash commands dispatched. ' \
+                 "Claude Code #{VERBATIM_PROMPTS_MINIMUM_CLAUDE_CODE_VERSION} or later is required."
+          end
         end
       rescue StandardError
         # Ignore version check errors — including Timeout::Error from the

data/lib/claude_agent_sdk/types/messages.rb

@@ -192,7 +192,13 @@ module ClaudeAgentSDK
                   :outcome # "success", "error", or "cancelled"
   end
 
-  # Session state changed system message
+  # Session state changed system message.
+  #
+  # Reaches your code only when you opt in with
+  # `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1` in ClaudeAgentOptions#env. The
+  # SDK also asks the CLI for these frames on its own behalf (to tell when a
+  # query() run is over), but those arrive marked `sdk_host_only` and are
+  # dropped before the message stream.
   class SessionStateChangedMessage < SystemMessage
     attr_accessor :uuid, :session_id,
                   :state # "idle", "running", or "requires_action"

data/lib/claude_agent_sdk/types/options.rb

@@ -81,21 +81,11 @@ module ClaudeAgentSDK
       self.include_hook_events = false
       self.strict_mcp_config = false
       self.forward_subagent_text = false
+      self.verbatim_prompts = false
 
       super(merge_with_defaults(attributes || {}))
 
-      # Non-nil defaults for options that need them.
-      self.env                 ||= {}
-      self.extra_args          ||= {}
-      self.mcp_servers         ||= {}
-      self.add_dirs            ||= []
-      self.observers           ||= []
-      self.allowed_tools       ||= []
-      self.disallowed_tools    ||= []
-      self.session_store_flush ||= 'batched'
-      # 0 is a valid (immediate) timeout, so only fill in the default for nil.
-      self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
-      self.callback_scheduling = :thread if callback_scheduling.nil?
+      fill_nil_defaults
     end
 
     def dup_with(**changes)
@@ -203,6 +193,58 @@ module ClaudeAgentSDK
       @forward_subagent_text = coerce_boolean(value)
     end
 
+    # Deliver every prompt to Claude as written.
+    #
+    # When true, every user message the SDK sends is marked `client_composed`:
+    # a String prompt to {ClaudeAgentSDK.query}, {Client#connect} or
+    # {Client#query}, and every message of a streamed (Enumerable) prompt to
+    # any of them. Claude Code then delivers the text exactly as given: no
+    # `@path` file-mention expansion and no slash-command dispatch. Use it when
+    # the prompt is assembled from content your end user did not type (earlier
+    # turns, tool output, third-party text), so an `@/absolute/path` inside it
+    # cannot make Claude Code read a local file. `tools: []`, `allowed_tools`
+    # and `disallowed_tools` do not stop that expansion: it happens before the
+    # model runs, without a tool call.
+    #
+    # While the option is on there is no per-message opt-out: a
+    # `client_composed` key on a streamed message Hash (either spelling) is
+    # overwritten. For per-turn control, leave the option off and set
+    # `client_composed: true` on individual streamed messages. The caller's
+    # Hashes are never mutated. A streamed JSONL String is parsed, marked and
+    # re-serialized; one that is not a single JSON object raises
+    # `ArgumentError` rather than being sent unmarked (on the background
+    # streaming paths that ends the stream with a warning, like any other
+    # stream error).
+    #
+    # On current Claude Code versions a turn delivered this way also skips the
+    # turn-start attachment pass as a whole: `@server:resource` MCP mentions
+    # are not expanded either, and the prompt goes without the context Claude
+    # Code normally attaches (nested `CLAUDE.md` and rules files, skill and
+    # tool listings, other per-turn reminders). The pass between tool calls is
+    # unaffected, so most of that context arrives after the turn's first tool
+    # call instead.
+    #
+    # Requires Claude Code 2.1.248 or later; older versions ignore the field,
+    # so prompts are still expanded there, and the SDK warns when it connects
+    # to one with this option on. Read once when the session starts. Not a
+    # CLI flag. Matches the Python SDK's `verbatim_prompts`.
+    #
+    # Assigning coerces to a Boolean; {#verbatim_prompts?} is the predicate
+    # form.
+    #
+    # @return [Boolean]
+    attr_reader :verbatim_prompts
+
+    # @return [Boolean] {#verbatim_prompts}, as a strict Boolean.
+    def verbatim_prompts?
+      !!verbatim_prompts
+    end
+
+    # @see #verbatim_prompts
+    def verbatim_prompts=(value)
+      @verbatim_prompts = 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.
@@ -288,6 +330,21 @@ module ClaudeAgentSDK
 
     private
 
+    # Non-nil defaults for options that need them.
+    def fill_nil_defaults
+      self.env                 ||= {}
+      self.extra_args          ||= {}
+      self.mcp_servers         ||= {}
+      self.add_dirs            ||= []
+      self.observers           ||= []
+      self.allowed_tools       ||= []
+      self.disallowed_tools    ||= []
+      self.session_store_flush ||= 'batched'
+      # 0 is a valid (immediate) timeout, so only fill in the default for nil.
+      self.load_timeout_ms = 60_000 if load_timeout_ms.nil?
+      self.callback_scheduling = :thread if callback_scheduling.nil?
+    end
+
     # Strict key validation: unlike other Type subclasses (which silently drop
     # unknown keys for forward-compat with newer CLI output), ClaudeAgentOptions
     # is a developer-facing config object — typos should fail loudly.

data/lib/claude_agent_sdk/version.rb

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

data/lib/claude_agent_sdk.rb

@@ -749,7 +749,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
           forward_subagent_text: configured_options.forward_subagent_text?,
           agent_progress_summaries: configured_options.agent_progress_summaries,
           callback_scheduling: callback_scheduling,
-          callback_wrapper: callback_wrapper
+          callback_wrapper: callback_wrapper,
+          verbatim_prompts: configured_options.verbatim_prompts?,
+          run_end_ceiling_ms: Query.run_end_ceiling_ms(configured_options.env)
         )
 
         # Mirror transcripts to the session_store, if configured. Installed
@@ -782,7 +784,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             parent_tool_use_id: nil,
             session_id: ''
           }
-          transport.write("#{JSON.generate(message)}\n")
+          transport.write("#{Query.serialize_user_message(message, configured_options.verbatim_prompts?)}\n")
           # Background-spawn so messages stream to the user block while stdin
           # close waits (without timeout) for the first result; a synchronous
           # call would defer all delivery until the turn completes (mirrors
@@ -1084,7 +1086,7 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             parent_tool_use_id: nil,
             session_id: session_id
           }
-          writeln(JSON.generate(message))
+          writeln(Query.serialize_user_message(message, @verbatim_prompts))
         elsif prompt.respond_to?(:each)
           # Inline iteration on the caller, Python client.py parity — NOT
           # Query#stream_input, whose ensure always ends input after
@@ -1394,6 +1396,10 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
       exclude_dynamic_sections = ClaudeAgentSDK.extract_exclude_dynamic_sections(configured_options.system_prompt)
       system_prompt_snapshot = ClaudeAgentSDK.extract_system_prompt_snapshot(configured_options.system_prompt)
 
+      # Captured once, so String and streamed prompts in one session are
+      # stamped alike (the Query stamps the streamed ones with this value).
+      @verbatim_prompts = configured_options.verbatim_prompts?
+
       # Create Query handler
       @query_handler = Query.new(
         transport: @transport,
@@ -1408,7 +1414,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
         forward_subagent_text: configured_options.forward_subagent_text?,
         agent_progress_summaries: configured_options.agent_progress_summaries,
         callback_scheduling: @callback_scheduling,
-        callback_wrapper: @callback_wrapper
+        callback_wrapper: @callback_wrapper,
+        verbatim_prompts: @verbatim_prompts,
+        run_end_ceiling_ms: Query.run_end_ceiling_ms(configured_options.env)
       )
 
       # Mirror transcripts to the session_store, if configured.
@@ -1450,7 +1458,9 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
     # key styles — an explicit nil is preserved, mirroring Python's
     # `"session_id" not in msg`). Strings pass through verbatim (Ruby
     # superset: Streaming.user_message emits pre-serialized JSONL; no
-    # parse-stamp-regenerate, which would block the reactor on huge frames).
+    # parse-stamp-regenerate, which would block the reactor on huge frames),
+    # except that verbatim_prompts must mark them `client_composed`, so with
+    # that option on they are parsed and re-serialized (Query.stamp_user_message).
     def stream_query_messages(prompt, session_id)
       prompt.each do |msg|
         case msg
@@ -1460,13 +1470,13 @@ module ClaudeAgentSDK # rubocop:disable Metrics/ModuleLength -- the public entry
             ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
                                             scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
-          writeln(JSON.generate(msg))
+          writeln(Query.serialize_user_message(msg, @verbatim_prompts))
         when String
           if (text = ClaudeAgentSDK.extract_user_prompt_text(msg))
             ClaudeAgentSDK.notify_observers(@resolved_observers, :on_user_prompt, text,
                                             scheduling: @callback_scheduling, wrapper: @callback_wrapper)
           end
-          writeln(msg)
+          writeln(Query.serialize_user_message(msg, @verbatim_prompts))
         else
           # No to_s fallback — silently serializing arbitrary objects is the
           # exact inspect-garbage bug class this method exists to prevent.

data/sig/claude_agent_sdk/types/options.rbs

@@ -85,6 +85,7 @@ module ClaudeAgentSDK
                       ?include_hook_events: bool?,
                       ?strict_mcp_config: bool?,
                       ?forward_subagent_text: bool?,
+                      ?verbatim_prompts: bool?,
                       ?agent_progress_summaries: bool?,
                       ?callback_scheduling: (:thread | :inline | "thread" | "inline")?,
                       ?callback_wrapper: _CallbackWrapper?
@@ -264,6 +265,14 @@ module ClaudeAgentSDK
 
     def forward_subagent_text?: () -> bool
 
+    # Mark every outgoing user message client_composed, so the CLI delivers
+    # it as written (false by default).
+    attr_reader verbatim_prompts: bool?
+
+    def verbatim_prompts=: (untyped value) -> bool?
+
+    def verbatim_prompts?: () -> bool
+
     # Request model-generated progress summaries for subagent tasks (nil:
     # unset, not sent).
     attr_reader agent_progress_summaries: bool?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - ya-luotao
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async