claude-agent-sdk 0.30.0 → 0.32.0

data/lib/claude_agent_sdk/query.rb

@@ -63,7 +63,8 @@ module ClaudeAgentSDK
     end
 
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil,
-                   exclude_dynamic_sections: nil, skills: nil, callback_scheduling: :thread, callback_wrapper: nil)
+                   exclude_dynamic_sections: nil, system_prompt_snapshot: nil, skills: nil,
+                   forward_subagent_text: false, callback_scheduling: :thread, callback_wrapper: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
@@ -73,7 +74,9 @@ module ClaudeAgentSDK
       @callback_wrapper = callback_wrapper
       @agents = agents
       @exclude_dynamic_sections = exclude_dynamic_sections
+      @system_prompt_snapshot = system_prompt_snapshot
       @skills = skills
+      @forward_subagent_text = forward_subagent_text
 
       # Control protocol state
       @pending_control_responses = {}
@@ -97,7 +100,12 @@ module ClaudeAgentSDK
       # #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
+      # Set to the result payload when the most recent message is a result
+      # with is_error=true. Used to replace the generic "exit code 1"
+      # ProcessError with a ResultError carrying what the CLI already
+      # 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 = []
@@ -182,9 +190,15 @@ module ClaudeAgentSDK
         agents: agents_dict
       }
       request[:excludeDynamicSections] = @exclude_dynamic_sections unless @exclude_dynamic_sections.nil?
+      # false is meaningful (rebuild the prompt every request), so send it
+      # explicitly; only nil (unset) is omitted.
+      request[:systemPromptSnapshot] = @system_prompt_snapshot unless @system_prompt_snapshot.nil?
       # 'all' and omitted are equivalent at the wire level (no filter), so
       # only send the field when it's an explicit list (mirrors Python).
       request[:skills] = @skills if @skills.is_a?(Array)
+      # Off is the CLI default, so only send the field when enabled — an
+      # older CLI then never sees an unknown key on the common path.
+      request[:forwardSubagentText] = true if @forward_subagent_text
 
       response = send_control_request(request)
       @initialized = true
@@ -355,45 +369,52 @@ module ClaudeAgentSDK
               @first_result_condition.signal
             end
             if message[:is_error]
-              errors = (message[:errors] || []).join('; ')
-              @last_error_result_text = errors.empty? ? (message[:subtype] || 'unknown error').to_s : errors
+              @last_error_result = message
             else
-              @last_error_result_text = nil
+              @last_error_result = nil
             end
           elsif !(msg_type == 'system' && message[:subtype] == 'session_state_changed')
             # Anything other than the post-turn session_state_changed marker
             # means the conversation moved on; a ProcessError now is a fresh
             # crash, not the expected exit from a prior error result. Mirrors
             # the Python/TypeScript SDK reset logic.
-            @last_error_result_text = nil
+            @last_error_result = nil
           end
           # Regular SDK messages go to the queue
           @message_queue.enqueue(message)
         end
       end
     rescue StandardError => e
-      # Unblock pending control requests (e.g., initialize) so callers don't
-      # hang until timeout. INVARIANT: store the result before signaling —
-      # senders check the slot before waiting (level-trigger).
-      @pending_control_responses.dup.each do |request_id, condition|
-        @pending_control_results[request_id] ||= e
-        condition.signal
-      end
-
       # When the CLI emits a result with is_error=true (e.g. error_max_turns,
-      # error_during_execution, a StructuredOutput error) it then exits
-      # non-zero on purpose, for shell-script consumers. The trailing
-      # ProcessError carries no information beyond "exit code 1" — replace it
-      # with the structured error the CLI already reported so the exception is
-      # actionable. Mirrors the Python SDK (_read_messages) and the TypeScript
-      # SDK (Query.ts readMessages).
-      error = if e.is_a?(ProcessError) && @last_error_result_text
-                ProcessError.new("Claude Code returned an error result: #{@last_error_result_text}",
-                                 exit_code: e.exit_code, stderr: e.stderr)
+      # error_during_execution, an API failure, a StructuredOutput error) it
+      # then exits non-zero on purpose, for shell-script consumers. The
+      # trailing ProcessError carries no information beyond "exit code 1" —
+      # replace it with a ResultError carrying what the CLI already reported
+      # so the exception is actionable *and* typed. Mirrors the Python SDK
+      # (_read_messages) and the TypeScript SDK (Query.ts readMessages).
+      error = if e.is_a?(ProcessError) && @last_error_result
+                ResultError.new("Claude Code returned an error result: #{ResultError.error_text(@last_error_result)}",
+                                data: @last_error_result, exit_code: e.exit_code, stderr: e.stderr,
+                                original_error: e)
               else
                 e
               end
 
+      # Unblock pending control requests (e.g., initialize) so callers don't
+      # hang until timeout. Computed AFTER the replacement above so they get
+      # the same enriched error the message stream does: a refused resume (a
+      # nonexistent session, a failed --resume-drops-turn guard) is reported
+      # by the CLI as an error result followed by exit 1 *before* it answers
+      # the SDK's `initialize`, so signaling the raw `e` here handed that
+      # in-flight request "Command failed with exit code 1" and discarded the
+      # real reason (Python #1198).
+      # INVARIANT: store the result before signaling — senders check the slot
+      # before waiting (level-trigger).
+      @pending_control_responses.dup.each do |request_id, condition|
+        @pending_control_results[request_id] ||= error
+        condition.signal
+      end
+
       # Put error in queue so iterators can handle it
       @message_queue.enqueue({ type: 'error', error: error })
     ensure
@@ -459,6 +480,24 @@ module ClaudeAgentSDK
       end
     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
+    # served over the control protocol: the CLI writes a control_request to
+    # stdout and blocks until the SDK writes the matching control_response to
+    # stdin. Closing stdin while any of these is configured makes every later
+    # request fail CLI-side with "Stream closed". Mirrors the TypeScript
+    # SDK's hasBidirectionalNeeds, de-prefixed per Ruby naming (Python #1204).
+    #
+    # can_use_tool is tested for truthiness, not for nil: ClaudeAgentSDK
+    # .configure_can_use_tool treats a falsey callback as "no callback"
+    # (`can_use_tool: enabled ? cb : false` is a real config shape), and the
+    # two must agree — otherwise `false` would skip the stdio routing while
+    # still holding stdin open for a reply that can never be asked for.
+    def bidirectional_needs?
+      !@sdk_mcp_servers.empty? || !@hooks.empty? || !!@can_use_tool
+    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
@@ -1239,8 +1278,9 @@ module ClaudeAgentSDK
                            })
     end
 
-    # 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.
+    # 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
@@ -1252,11 +1292,15 @@ module ClaudeAgentSDK
     # 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.
+    #
+    # 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.
     def wait_for_result_and_end_input
-      if !@first_result_received &&
-         ((@sdk_mcp_servers && !@sdk_mcp_servers.empty?) || (@hooks && !@hooks.empty?))
-        @first_result_condition.wait
-      end
+      @first_result_condition.wait if !@first_result_received && bidirectional_needs?
     ensure
       @transport.end_input
     end

data/lib/claude_agent_sdk/session_resume.rb

@@ -5,6 +5,7 @@ require 'fileutils'
 require 'tmpdir'
 require 'open3'
 require 'rbconfig'
+require 'securerandom'
 require_relative 'fiber_boundary'
 require_relative 'sessions'
 require_relative 'session_store'
@@ -36,7 +37,7 @@ module ClaudeAgentSDK
     # copies, and tell the user where the data is so they can import it into
     # the store manually. Never raises.
     def preserve_transcripts
-      ['.credentials.json', '.claude.json'].each do |name|
+      ['.credentials.json', '.claude.json', 'settings.json', 'cowork_settings.json'].each do |name|
         FileUtils.rm_f(File.join(@config_dir, name))
       end
       warn "Claude SDK: transcript mirror dropped batches; the session store copy is incomplete. " \
@@ -55,6 +56,18 @@ module ClaudeAgentSDK
   # from the store, writes it to a temp dir laid out like ~/.claude/, and returns
   # the path so the caller can point the subprocess at it via CLAUDE_CONFIG_DIR.
   module SessionResume # rubocop:disable Metrics/ModuleLength
+    # User settings files seeded into the temp config dir. cowork_settings.json
+    # is the alternate filename the CLI reads in cowork-plugins mode.
+    SEEDED_SETTINGS_FILES = ['settings.json', 'cowork_settings.json'].freeze
+
+    # User-settings keys that only misbehave under the redirected
+    # CLAUDE_CONFIG_DIR: plugin declarations reconcile against the
+    # always-empty tmp_base/plugins cache and would network-install each
+    # declared marketplace on every resume.
+    RESUME_SETTINGS_STRIPPED_KEYS = %w[enabledPlugins extraKnownMarketplaces].freeze
+
+    UTF8_BOM = "\xEF\xBB\xBF".b.freeze
+
     KEYCHAIN_SERVICE_NAME = 'Claude Code-credentials'
     KEYCHAIN_TIMEOUT_SECONDS = 5
 
@@ -269,13 +282,24 @@ module ClaudeAgentSDK
       chmod_owner_only(path)
     end
 
-    # Copy .credentials.json (refreshToken redacted) and .claude.json from the
-    # caller's effective config locations so the resumed subprocess can auth.
+    # Seed tmp_base with the caller's auth and user config so the resumed
+    # subprocess can authenticate: .credentials.json (refreshToken redacted),
+    # .claude.json, and user settings.json / cowork_settings.json (plugin
+    # declarations stripped).
+    #
+    # Source resolution mirrors the CLI: .credentials.json, settings.json and
+    # cowork_settings.json live under the config dir (default ~/.claude/), while
+    # .claude.json lives at $CLAUDE_CONFIG_DIR/.claude.json when set, else
+    # ~/.claude.json (NOT ~/.claude/.claude.json).
     def copy_auth_files(tmp_base, opt_env)
       caller_config_dir = env_value(opt_env, 'CLAUDE_CONFIG_DIR')
       source_config_dir = caller_config_dir || File.join(Dir.home, '.claude')
 
-      creds_json = read_file_if_present(File.join(source_config_dir, '.credentials.json'))
+      # read_if_present returns raw bytes; the credentials path parses and
+      # re-serializes JSON, so hand it a UTF-8-tagged string (invalid bytes
+      # simply fail to parse and get written through, as before).
+      creds_bytes = read_if_present(File.join(source_config_dir, '.credentials.json'))
+      creds_json = creds_bytes&.dup&.force_encoding(Encoding::UTF_8)
 
       # macOS default keeps OAuth tokens in the Keychain, not a file. Redirecting
       # CLAUDE_CONFIG_DIR changes the Keychain service suffix so the subprocess's
@@ -291,6 +315,115 @@ module ClaudeAgentSDK
 
       claude_json_src = caller_config_dir ? File.join(caller_config_dir, '.claude.json') : File.join(Dir.home, '.claude.json')
       copy_if_present(claude_json_src, File.join(tmp_base, '.claude.json'))
+
+      # User settings carry apiKeyHelper (a fourth auth mechanism alongside
+      # .credentials.json / Keychain / env vars) plus the user's env, hooks and
+      # permissions. Without them the resumed subprocess sees no user settings
+      # at all, and an apiKeyHelper-only host fails with "Not logged in".
+      # cowork_settings.json is the alternate filename the CLI reads in
+      # cowork-plugins mode. Both pass through strip_settings_for_resume so
+      # plugin declarations don't reconcile against the empty tmp_base cache.
+      transform = ->(content) { strip_settings_for_resume(content) }
+      SEEDED_SETTINGS_FILES.each do |name|
+        copy_if_present(File.join(source_config_dir, name), File.join(tmp_base, name), transform)
+      end
+    end
+
+    # Drop settings keys that only misbehave under the redirected config dir:
+    # RESUME_SETTINGS_STRIPPED_KEYS (plugin declarations, which reconcile
+    # against the always-empty tmp_base plugin cache and would network-install
+    # every declared marketplace on each resume) and env.CLAUDE_CONFIG_DIR
+    # (which would point the subprocess's config reads away from tmp_base).
+    # Content that doesn't parse as a JSON object is returned untouched so the
+    # subprocess sees exactly what the CLI would have read.
+    def strip_settings_for_resume(content)
+      parsed, restore = parse_settings_bytes(content)
+      return content unless parsed.is_a?(Hash)
+
+      stripped = false
+      RESUME_SETTINGS_STRIPPED_KEYS.each do |key|
+        next unless parsed.key?(key)
+
+        parsed.delete(key)
+        stripped = true
+      end
+      env_block = parsed['env']
+      if env_block.is_a?(Hash) && env_block.key?('CLAUDE_CONFIG_DIR')
+        env_block.delete('CLAUDE_CONFIG_DIR')
+        stripped = true
+      end
+      return content unless stripped
+
+      begin
+        out = JSON.generate(parsed)
+      rescue JSON::GeneratorError
+        # A spec-valid overflow like 1e999 parses to Infinity, and JSON.generate
+        # refuses to emit the bare token the CLI would reject anyway. Fall back
+        # to the original bytes rather than writing something unusable.
+        return content
+      end
+      restore ? restore.call(out) : out
+    end
+
+    # Parse settings bytes tolerating a UTF-8 BOM (PowerShell writes
+    # settings.json with one, and JSON.parse rejects it). Returns
+    # [parsed, restore] where +restore+ is nil, or a callable that must be
+    # applied to the re-serialized output (see mask_surrogate_escapes).
+    # Returns [nil, nil] when the bytes aren't valid UTF-8 or aren't valid JSON.
+    def parse_settings_bytes(content)
+      body = content.b
+      body = body.byteslice(3..) || +'' if body.start_with?(UTF8_BOM)
+      text = body.dup.force_encoding(Encoding::UTF_8)
+      return [nil, nil] unless text.valid_encoding?
+
+      parsed = begin
+        JSON.parse(text)
+      rescue JSON::ParserError
+        nil
+      end
+      return [parsed, nil] unless parsed.nil?
+
+      # Ruby's JSON parser rejects lone surrogate escapes ("\ud800") that
+      # Python's accepts, with no option to relax it. Passing the file through
+      # unstripped over one would leave enabledPlugins in place and let the
+      # resumed CLI keep network-installing every declared marketplace — the
+      # exact behavior this seeding exists to prevent. Retry with the surrogate
+      # escapes masked out, restoring them verbatim after re-serialization.
+      masked, restore = mask_surrogate_escapes(text)
+      return [nil, nil] if masked.nil?
+
+      begin
+        [JSON.parse(masked), restore]
+      rescue JSON::ParserError
+        [nil, nil]
+      end
+    end
+
+    # Replace every \uD800-\uDFFF escape with an opaque ASCII token so the
+    # document parses, and return [masked_text, restore] where +restore+ maps
+    # the tokens in generated output back to the original escape text
+    # byte-for-byte. Returns [nil, nil] when there is nothing to mask (the
+    # parse failure was something else) or the token could collide.
+    def mask_surrogate_escapes(text)
+      token_prefix = "CASDKSURROGATE#{SecureRandom.hex(8)}"
+      return [nil, nil] if text.include?(token_prefix)
+
+      escapes = []
+      masked = text.gsub(/\\+u[0-9a-fA-F]{4}/) do |match|
+        slashes = match[/\A\\+/]
+        # An even run is escaped backslashes followed by literal "uXXXX" text,
+        # not an escape sequence.
+        next match if slashes.length.even?
+
+        escape = "\\#{match[slashes.length..]}"
+        next match unless escape[2..].to_i(16).between?(0xD800, 0xDFFF)
+
+        escapes << escape
+        "#{slashes[0...-1]}#{token_prefix}#{escapes.length - 1}Z"
+      end
+      return [nil, nil] if escapes.empty?
+
+      [masked, ->(out) { out.gsub(/#{Regexp.escape(token_prefix)}(\d+)Z/) { escapes[::Regexp.last_match(1).to_i] } }]
     end
 
     # Write creds_json with claudeAiOauth.refreshToken removed. The resumed
@@ -298,24 +431,48 @@ module ClaudeAgentSDK
     # single-use refresh token would be consumed and the new tokens written
     # somewhere the parent never reads — revoking the parent's creds. Stripping
     # refreshToken short-circuits the subprocess's refresh check.
+    #
+    # Content that isn't JSON at all is written through unchanged: the
+    # subprocess then reads exactly what the CLI would have read (and fails on
+    # it the same way). Note this branch is narrower than "unreadable content" —
+    # JSON.parse accepts illegal UTF-8 bytes inside an otherwise well-formed
+    # document, so redaction can instead fail at re-serialization time; see
+    # below for why that case writes nothing rather than writing through.
     def write_redacted_credentials(creds_json, dst)
-      return if creds_json.nil?
+      out = redacted_credentials(creds_json)
+      return if out.nil?
 
-      out = creds_json
-      begin
-        data = JSON.parse(creds_json)
-        oauth = data.is_a?(Hash) ? data['claudeAiOauth'] : nil
-        if oauth.is_a?(Hash) && oauth.key?('refreshToken')
-          oauth.delete('refreshToken')
-          out = JSON.generate(data)
-        end
-      rescue JSON::ParserError
-        # Unparseable — write through; the subprocess will fail to parse it too.
-      end
       File.write(dst, out)
       chmod_owner_only(dst)
     end
 
+    # The redaction itself: returns the bytes to write, or nil to write no
+    # credentials file at all.
+    def redacted_credentials(creds_json)
+      return nil if creds_json.nil?
+
+      data = JSON.parse(creds_json)
+      oauth = data.is_a?(Hash) ? data['claudeAiOauth'] : nil
+      return creds_json unless oauth.is_a?(Hash) && oauth.key?('refreshToken')
+
+      oauth.delete('refreshToken')
+      begin
+        JSON.generate(data)
+      rescue JSON::GeneratorError => e
+        # The redaction succeeded but the result can't be re-emitted (illegal
+        # UTF-8 elsewhere in the file). Writing the original bytes through
+        # would put the un-redacted refreshToken back into the temp dir, so
+        # seed no credentials file instead — and don't abort the resume over
+        # it either, matching every other seed file's policy. A resume that
+        # falls back to another auth mechanism beats one that lets the
+        # subprocess burn the parent's single-use refresh token.
+        warn "Claude SDK: [SessionStore] resume: cannot redact credentials (#{e.message}); seeding none"
+        nil
+      end
+    rescue JSON::ParserError
+      creds_json
+    end
+
     # Read OAuth credentials JSON from the macOS Keychain (default service name).
     # Best-effort — returns nil on any error or non-macOS platforms.
     def read_keychain_credentials
@@ -404,16 +561,17 @@ module ClaudeAgentSDK
     # Partition entries into transcript vs agent_metadata and write the
     # <subpath>.jsonl transcript and, if present, the <subpath>.meta.json sidecar.
     def write_subagent_files(session_dir, subpath, entries)
-      metadata, transcript = entries.partition { |e| e.is_a?(Hash) && e['type'] == 'agent_metadata' }
+      # Last metadata entry wins (see Sessions.split_agent_metadata).
+      metadata, transcript = Sessions.split_agent_metadata(entries)
       sub_file = File.join(session_dir, "#{subpath}.jsonl")
 
       write_jsonl(sub_file, transcript) unless transcript.empty?
 
-      return if metadata.empty?
+      return if metadata.nil?
 
-      # Last metadata entry wins; strip the synthetic type field.
-      meta_content = metadata.last.except('type')
-      meta_file = "#{sub_file.delete_suffix('.jsonl')}.meta.json"
+      # Strip the synthetic type field.
+      meta_content = metadata.except('type')
+      meta_file = Sessions.agent_metadata_sidecar_path(sub_file)
       FileUtils.mkdir_p(File.dirname(meta_file))
       File.write(meta_file, JSON.generate(meta_content))
       chmod_owner_only(meta_file)
@@ -466,9 +624,26 @@ module ClaudeAgentSDK
       FileUtils.rm_rf(path)
     end
 
-    def read_file_if_present(path)
-      File.read(path)
-    rescue SystemCallError
+    # Read a regular file's bytes, or return nil.
+    #
+    # A missing source is skipped silently. Any other reason it can't be read
+    # (EACCES, a directory or FIFO where a file was expected, ...) is logged and
+    # skipped: these files are best-effort enrichment of the temp config dir, so
+    # an unreadable one must not abort — or, for a FIFO, hang — the resume. The
+    # ftype check happens on the stat, before any open: opening a FIFO blocks
+    # forever, so it must never be opened in the first place.
+    def read_if_present(path)
+      ftype = File.stat(path).ftype
+      unless ftype == 'file'
+        warn "Claude SDK: [SessionStore] resume: skipping #{path} (not a regular file: #{ftype})"
+        return nil
+      end
+
+      File.binread(path)
+    rescue Errno::ENOENT
+      nil
+    rescue SystemCallError => e
+      warn "Claude SDK: [SessionStore] resume: skipping #{path} (#{e.message})"
       nil
     end
 
@@ -482,15 +657,28 @@ module ClaudeAgentSDK
       nil
     end
 
-    # Copy src to dst (locked to 0600) when src exists; no-op otherwise. The
-    # only caller copies .claude.json, which can hold MCP-header secrets and
-    # customApiKeyResponses, so it gets the same owner-only mode as the other
+    # Copy src to dst (locked to 0600) when src exists, through an optional
+    # transform; no-op otherwise. Callers copy .claude.json and the user
+    # settings files, which can hold MCP-header secrets, customApiKeyResponses
+    # and apiKeyHelper env, so they get the same owner-only mode as the other
     # materialized files rather than inheriting the source's (often 0644) mode.
-    def copy_if_present(src, dst)
-      FileUtils.copy_file(src, dst)
-      chmod_owner_only(dst)
-    rescue SystemCallError
-      nil
+    # See read_if_present for the skip policy.
+    def copy_if_present(src, dst, transform = nil)
+      content = read_if_present(src)
+      return if content.nil?
+
+      begin
+        File.binwrite(dst, transform ? transform.call(content) : content)
+        chmod_owner_only(dst)
+      rescue SystemCallError => e
+        # Don't leave a truncated dst behind for the subprocess to misparse.
+        begin
+          FileUtils.rm_f(dst)
+        rescue SystemCallError
+          nil
+        end
+        warn "Claude SDK: [SessionStore] resume: skipping #{src} (#{e.message})"
+      end
     end
 
     # Resolve the value the CHILD process will see for env var +name+. Presence
@@ -513,6 +701,8 @@ module ClaudeAgentSDK
     private_class_method :load_candidate, :resolve_continue_candidate, :sortable_mtime, :with_timeout, :write_jsonl,
                          :copy_auth_files, :write_redacted_credentials, :read_keychain_credentials,
                          :capture_with_timeout, :materialize_subkeys, :write_subagent_files,
-                         :resolve_dir, :read_file_if_present, :chmod_owner_only, :copy_if_present, :env_value
+                         :resolve_dir, :read_if_present, :chmod_owner_only, :copy_if_present, :env_value,
+                         :strip_settings_for_resume, :parse_settings_bytes, :mask_surrogate_escapes,
+                         :redacted_credentials
   end
 end