claude-agent-sdk 0.31.0 → 0.33.0

data/lib/claude_agent_sdk/query.rb

@@ -8,6 +8,7 @@ require 'async/condition'
 require 'securerandom'
 require_relative 'transport'
 require_relative 'errors'
+require_relative 'cancellation_signal'
 
 module ClaudeAgentSDK
   # Handles bidirectional control protocol on top of Transport
@@ -63,7 +64,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, forward_subagent_text: false,
+                   exclude_dynamic_sections: nil, system_prompt_snapshot: nil, skills: nil,
+                   forward_subagent_text: false, agent_progress_summaries: nil,
                    callback_scheduling: :thread, callback_wrapper: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
@@ -74,8 +76,10 @@ 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
+      @agent_progress_summaries = agent_progress_summaries
 
       # Control protocol state
       @pending_control_responses = {}
@@ -86,6 +90,7 @@ module ClaudeAgentSDK
       @request_counter = 0
       @request_counter_mutex = Mutex.new
       @inflight_control_request_tasks = {}
+      @callback_request_signals = {}
 
       # Message stream
       @message_queue = Async::Queue.new
@@ -189,12 +194,19 @@ 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
+      # Unset (nil) omits the key; true/false are forwarded verbatim. Not a live toggle: CLI
+      # 2.1.278 only acts on a truthy value, so false is schema-valid but
+      # equivalent to omitting the key.
+      request[:agentProgressSummaries] = @agent_progress_summaries unless @agent_progress_summaries.nil?
 
       response = send_control_request(request)
       @initialized = true
@@ -327,7 +339,11 @@ module ClaudeAgentSDK
             begin
               handle_control_request(message)
             ensure
-              @inflight_control_request_tasks.delete(request_id) if request_id
+              # Identity-guarded: if the CLI ever reused an in-flight request
+              # id, the later handler owns the slot and must stay cancellable.
+              if request_id && @inflight_control_request_tasks[request_id].equal?(Async::Task.current)
+                @inflight_control_request_tasks.delete(request_id)
+              end
             end
           end
           # A handler that never suspends (MCP metadata, unsupported-subtype
@@ -337,6 +353,7 @@ module ClaudeAgentSDK
           @inflight_control_request_tasks[request_id] = handler_task if request_id && !handler_task.finished?
         when 'control_cancel_request'
           request_id = message[:request_id] || message[:requestId]
+          @callback_request_signals[request_id]&.cancel
           task = request_id ? @inflight_control_request_tasks[request_id] : nil
           task&.stop
           next
@@ -414,6 +431,9 @@ module ClaudeAgentSDK
       # Put error in queue so iterators can handle it
       @message_queue.enqueue({ type: 'error', error: error })
     ensure
+      # A callback can no longer be answered after EOF, transport failure,
+      # or reactor cancellation. Wake cooperative worker-thread callbacks too.
+      @callback_request_signals.dup.each_value(&:cancel)
       # Catch entries from a turn that ended without a `result` (early EOF /
       # transport error) so they aren't dropped. The flush can suspend (lock
       # acquire / thread join), so Async::Stop delivered mid-flush would skip
@@ -535,9 +555,9 @@ module ClaudeAgentSDK
 
       case subtype
       when 'can_use_tool'
-        response_data = handle_permission_request(request_data)
+        response_data = handle_permission_request(request_data, request_id: request_id)
       when 'hook_callback'
-        response_data = handle_hook_callback(request_data)
+        response_data = handle_hook_callback(request_data, request_id: request_id)
       when 'mcp_message'
         response_data = handle_mcp_message(request_data)
       else
@@ -557,33 +577,34 @@ module ClaudeAgentSDK
       writeln(JSON.generate(success_response))
     rescue Async::Stop
       # Cancellation requested; respond with an error so the CLI can unblock.
-      cancelled_response = {
-        type: 'control_response',
-        response: {
-          subtype: 'error',
-          request_id: request_id,
-          requestId: request_id,
-          error: 'Cancelled'
-        }
-      }
-      writeln(JSON.generate(cancelled_response))
+      send_control_error(request_id, 'Cancelled')
     rescue StandardError => e
-      # Send error response
+      send_control_error(request_id, e.message)
+    end
+
+    def send_control_error(request_id, message)
       error_response = {
         type: 'control_response',
         response: {
           subtype: 'error',
           request_id: request_id,
           requestId: request_id,
-          error: e.message
+          error: message
         }
       }
       writeln(JSON.generate(error_response))
+    rescue CLIConnectionError
+      # EOF/close can invalidate a callback after the peer has gone away.
+      # Only this best-effort reply is discarded; read errors still reach
+      # the message queue through read_messages.
+      nil
     end
 
-    def handle_permission_request(request_data)
+    def handle_permission_request(request_data, request_id: nil)
       raise 'canUseTool callback is not provided' unless @can_use_tool
 
+      signal = CancellationSignal.new
+      @callback_request_signals[request_id] = signal if request_id
       original_input = request_data[:input]
 
       # Field order mirrors Python _internal/query.py's can_use_tool branch.
@@ -591,7 +612,8 @@ module ClaudeAgentSDK
       # malformed entry raises here, on the reactor, and becomes an error
       # control_response — same observable behavior as Python.
       context = ToolPermissionContext.new(
-        signal: nil,
+        signal: signal,
+        request_id: request_id,
         suggestions: (request_data[:permission_suggestions] || []).map { |s| PermissionUpdate.new(s) },
         tool_use_id: request_data[:tool_use_id],
         agent_id: request_data[:agent_id],
@@ -610,6 +632,9 @@ module ClaudeAgentSDK
       response = FiberBoundary.invoke(scheduling: @callback_scheduling, wrapper: @callback_wrapper) do
         @can_use_tool.call(request_data[:tool_name], request_data[:input], context)
       end
+      # A worker may return a decision after the read loop invalidated the
+      # request. Never turn that late decision into an allow response.
+      raise Async::Stop if signal.cancelled?
 
       # Convert PermissionResult to expected format
       case response
@@ -629,19 +654,27 @@ module ClaudeAgentSDK
       else
         raise "Tool permission callback must return PermissionResult, got #{response.class}"
       end
+      completed = true
+      result
+    ensure
+      signal&.cancel unless completed
+      untrack_callback_signal(request_id, signal)
     end
 
-    def handle_hook_callback(request_data)
+    def handle_hook_callback(request_data, request_id: nil)
       callback_id = request_data[:callback_id]
       callback = @hook_callbacks[callback_id]
       raise "No hook callback found for ID: #{callback_id}" unless callback
 
+      signal = CancellationSignal.new
+      @callback_request_signals[request_id] = signal if request_id
+
       # Parse input data into typed HookInput object
       input_data = request_data[:input] || {}
       hook_input = parse_hook_input(input_data)
 
       # Create typed HookContext
-      context = HookContext.new(signal: nil)
+      context = HookContext.new(signal: signal, request_id: request_id)
 
       # Hop off the Fiber scheduler before invoking user hook code (default
       # :thread mode). With a timeout, the Async-side with_timeout wraps the
@@ -689,8 +722,25 @@ module ClaudeAgentSDK
           end
       end
 
+      # A thread callback may finish after EOF/close invalidated its request.
+      raise Async::Stop if signal.cancelled?
+
       # Convert Ruby-safe field names to CLI-expected names
-      convert_hook_output_for_cli(hook_output)
+      result = convert_hook_output_for_cli(hook_output)
+      completed = true
+      result
+    ensure
+      signal&.cancel unless completed
+      untrack_callback_signal(request_id, signal)
+    end
+
+    # Identity-guarded for the same reason as the in-flight task map: a handler
+    # only untracks its own signal, never a later request that reused its id —
+    # otherwise EOF/close could no longer invalidate that later request.
+    def untrack_callback_signal(request_id, signal)
+      return unless request_id && @callback_request_signals[request_id].equal?(signal)
+
+      @callback_request_signals.delete(request_id)
     end
 
     def parse_hook_input(input_data)
@@ -749,6 +799,8 @@ module ClaudeAgentSDK
         StopHookInput.new(
           stop_hook_active: fetch.call(:stop_hook_active),
           last_assistant_message: fetch.call(:last_assistant_message),
+          background_tasks: fetch.call(:background_tasks),
+          session_crons: fetch.call(:session_crons),
           **base_args
         )
       when 'SubagentStop'
@@ -758,6 +810,8 @@ module ClaudeAgentSDK
           agent_transcript_path: fetch.call(:agent_transcript_path),
           agent_type: fetch.call(:agent_type),
           last_assistant_message: fetch.call(:last_assistant_message),
+          background_tasks: fetch.call(:background_tasks),
+          session_crons: fetch.call(:session_crons),
           **base_args
         )
       when 'Notification'
@@ -1263,6 +1317,21 @@ module ClaudeAgentSDK
                            })
     end
 
+    # Background in-flight foreground tasks (Bash commands and subagents) — the
+    # control-request equivalent of pressing Ctrl+B in the terminal.
+    # @param tool_use_id [String, nil] The spawning tool_use block's id (not a
+    #   task_id or agent_id). nil is the explicit all-tasks form: it backgrounds
+    #   every foreground task
+    # @return [Hash] Targeted: `{ backgrounded: true }`, or `{ backgrounded:
+    #   false }` — a definitive miss (no matching foreground task). All-tasks:
+    #   `{}`, which says nothing about whether any task existed
+    # @raise [ArgumentError] if tool_use_id is neither nil nor a non-empty String
+    def background_tasks(tool_use_id: nil)
+      request = { subtype: 'background_tasks' }
+      request[:tool_use_id] = background_selector(tool_use_id) unless tool_use_id.nil?
+      send_control_request(request)
+    end
+
     # Rewind files to a previous checkpoint (v0.1.15+)
     # Restores file state to what it was at the given user message
     # Requires enable_file_checkpointing to be true in options
@@ -1388,6 +1457,25 @@ module ClaudeAgentSDK
 
     private
 
+    # The selector actually sent for a targeted background_tasks request.
+    #
+    # The CLI normalizes "" to "background ALL foreground tasks", so a selector
+    # built from a missing id (`id.to_s`) would release every blocking call.
+    # Validate the value that goes on the wire, not the caller's object: a
+    # private plain-String copy cannot be emptied by another thread between this
+    # check and serialization (send_control_request can park on a mutex first),
+    # and a String subclass cannot answer `empty?` or `to_json` for it. Never
+    # normalize a bad selector to nil, and never strip — a whitespace-only id is
+    # still a targeted selector CLI-side, so stripping would widen the request.
+    def background_selector(tool_use_id)
+      selector = String.new(tool_use_id) if String === tool_use_id # rubocop:disable Style/CaseEquality
+      return selector unless selector.nil? || selector.empty?
+
+      raise ArgumentError,
+            "tool_use_id must be a non-empty String (got #{tool_use_id.inspect}); " \
+            'pass nil explicitly to background all foreground tasks'
+    end
+
     def close_now
       # First caller wins: a reactor-side close racing a watcher-served
       # foreign close (or a repeated disconnect) must not re-run teardown
@@ -1406,6 +1494,8 @@ module ClaudeAgentSDK
       return unless first_caller
 
       @closed = true
+      # Snapshot for the off-reactor fallback, like the response waiters below.
+      @callback_request_signals.dup.each_value(&:cancel)
       # Wake pending control-request waiters (same shape as the read-loop
       # rescue broadcast): close stops the read task with Async::Stop, which
       # bypasses that broadcast — a worker-thread caller parked in

data/lib/claude_agent_sdk/sessions.rb

@@ -596,6 +596,25 @@ module ClaudeAgentSDK
       collect_agent_files(subagents_dir).map(&:first)
     end
 
+    # Read the optional subagent metadata sidecar without reading its transcript.
+    # Uses the same project scoping and sorted first-match rule as the message
+    # reader. This is historical metadata, not a live status query.
+    # @return [Hash{String => Object}, nil] Original CLI fields, or nil if unavailable
+    def get_subagent_metadata(session_id:, agent_id:, directory: nil)
+      return nil unless session_id.match?(UUID_RE)
+      return nil if agent_id.nil? || agent_id.empty?
+
+      subagents_dir = resolve_subagents_dir(session_id, directory)
+      return nil if subagents_dir.nil?
+
+      _id, path = collect_agent_files(subagents_dir).find { |id, _path| id == agent_id }
+      return nil if path.nil?
+
+      read_agent_metadata_sidecar(path)
+    rescue SystemCallError
+      nil
+    end
+
     # Read a subagent's conversation messages from local disk (counterpart to
     # get_subagent_messages_from_store). First match in sorted walk order wins
     # when the same agent id exists at multiple depths (mirrors Python).
@@ -760,6 +779,24 @@ module ClaudeAgentSDK
       end
     end
 
+    # Store counterpart to get_subagent_metadata. The last agent_metadata entry
+    # wins, including when no conversation messages have been mirrored yet.
+    # The synthetic `type` marker is omitted; all other string-keyed fields
+    # remain unchanged. Adapter failures propagate, like other store readers.
+    # @return [Hash{String => Object}, nil]
+    def get_subagent_metadata_from_store(session_store:, session_id:, agent_id:, directory: nil)
+      return nil unless session_id.match?(UUID_RE)
+      return nil if agent_id.nil? || agent_id.empty?
+
+      project_key = project_key_for_directory(directory)
+      subpath = resolve_subagent_subpath(session_store, project_key, session_id, agent_id)
+      return nil if subpath.nil?
+
+      entries = session_store.load('project_key' => project_key, 'session_id' => session_id, 'subpath' => subpath)
+      metadata, = split_agent_metadata(entries || [])
+      metadata&.except('type')
+    end
+
     # Read a subagent's conversation messages from a SessionStore. Subagents may
     # live at subagents/agent-<id> or nested under
     # subagents/workflows/<runId>/agent-<id>; scans subkeys to resolve the path