claude-agent-sdk 0.32.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
@@ -64,7 +65,8 @@ module ClaudeAgentSDK
 
     def initialize(transport:, is_streaming_mode:, can_use_tool: nil, hooks: nil, sdk_mcp_servers: nil, agents: nil,
                    exclude_dynamic_sections: nil, system_prompt_snapshot: nil, skills: nil,
-                   forward_subagent_text: false, callback_scheduling: :thread, callback_wrapper: nil)
+                   forward_subagent_text: false, agent_progress_summaries: nil,
+                   callback_scheduling: :thread, callback_wrapper: nil)
       @transport = transport
       @is_streaming_mode = is_streaming_mode
       @can_use_tool = can_use_tool
@@ -77,6 +79,7 @@ module ClaudeAgentSDK
       @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 = {}
@@ -87,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
@@ -199,6 +203,10 @@ module ClaudeAgentSDK
       # 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
@@ -331,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
@@ -341,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
@@ -418,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
@@ -539,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
@@ -561,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.
@@ -595,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],
@@ -614,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
@@ -633,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
@@ -693,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)
@@ -753,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'
@@ -762,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'
@@ -1267,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
@@ -1392,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
@@ -1410,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

data/lib/claude_agent_sdk/types.rb

@@ -421,12 +421,51 @@ module ClaudeAgentSDK
   # Task started system message (subagent/background task started)
   class TaskStartedMessage < SystemMessage
     attr_accessor :task_id, :description, :uuid, :session_id, :tool_use_id, :task_type,
-                  :workflow_name, :prompt
+                  :workflow_name, :prompt,
+                  :subagent_type # Subagent type, for Task/Agent tool subagents; nil otherwise
+
+    # Whether the task was registered in the background (`true`) or in the
+    # foreground with the spawning tool call blocking on it (`false`). `nil`
+    # means the CLI did not say (the field is optional, and only set for
+    # `local_agent` and `local_bash` tasks) — so test `== false`, never
+    # falsiness, to detect a foreground/blocking task. A resumed subagent is
+    # always registered in the background. A later move to the background does
+    # not re-emit task_started; it arrives as {TaskUpdatedMessage#is_backgrounded}.
+    #
+    # @return [Boolean, nil]
+    attr_accessor :is_backgrounded
+
+    # Nesting depth of a spawned subagent (`local_agent`) task: 1 for a
+    # top-level spawn, N+1 when spawned from inside a depth-N agent. `nil` on
+    # other task types and on CLIs that do not report it.
+    #
+    # @return [Integer, nil]
+    attr_accessor :spawn_depth
+
+    # Display flags, passed through for the host to act on — the SDK never
+    # filters frames or computes activity from them. Both are optional
+    # Booleans: `nil` when absent, an explicit `false` preserved.
+    #
+    # - `skip_transcript`: an ambient/housekeeping task. Hide it from the
+    #   inline transcript; it may still appear in a tasks panel.
+    # - `ambient`: true for tasks that are not activity — every
+    #   `skip_transcript` task, plus every live-update watcher (requested or
+    #   auto-started). Exclude these from activity indicators.
+    #
+    # @return [Boolean, nil]
+    attr_accessor :skip_transcript, :ambient
   end
 
-  # Task progress system message (periodic update from a running task)
+  # Task progress system message (periodic update from a running task).
+  #
+  # `summary` is an optional one-line status for the task's row — `nil` on any
+  # frame that lacks one. For a `local_agent` task it is the model-generated
+  # progress summary, which the CLI produces only while generation is enabled
+  # (see {ClaudeAgentOptions#agent_progress_summaries}); for a backgrounded
+  # `mcp_task` it is the MCP server's own status message and needs no option.
   class TaskProgressMessage < SystemMessage
-    attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name, :summary
+    attr_accessor :task_id, :description, :usage, :uuid, :session_id, :tool_use_id, :last_tool_name, :summary,
+                  :subagent_type # Subagent type, for Task/Agent tool subagents; nil otherwise
   end
 
   # Task notification system message (task completed/failed/stopped).
@@ -437,6 +476,42 @@ module ClaudeAgentSDK
   # should clear them on a terminal status from *either* message.
   class TaskNotificationMessage < SystemMessage
     attr_accessor :task_id, :status, :output_file, :summary, :uuid, :session_id, :tool_use_id, :usage
+
+    # Machine-readable cause, set only when the task did not end through an
+    # ordinary completion, failure, or stop. The one known value is
+    # `'worker_restart'` (the worker process restarted and the resumed process
+    # found the task orphaned; always with status `'stopped'`). Documentation,
+    # not validation: newer CLIs may add values.
+    #
+    # @return [String, nil]
+    attr_accessor :reason
+
+    # For a backgrounded MCP task (`task_type: 'mcp_task'`) that completed: the
+    # `resource_link` content blocks of its final result — the files it
+    # returned by reference. A backgrounded task's tool_result is placeholder
+    # text, so this is where a host learns which files the call produced; join
+    # to the originating call via `tool_use_id`. `nil` when the result had
+    # none or the task is any other type.
+    #
+    # Passed through from the CLI untouched, so each element is a Hash whose
+    # keys are **Symbols with the wire spelling preserved**: `:uri` and `:name`
+    # (Strings, always present), and optionally `:title`, `:description`,
+    # `:mimeType` (camelCase — a `:mime_type` lookup returns nil), `:size` (a
+    # Number, not necessarily an Integer), `:annotations` (a Hash of arbitrary
+    # values). Elements carry no `type: 'resource_link'` discriminator. The CLI
+    # describes its own output as at most 50 links / 64 KiB serialized; that is
+    # a producer-side note, and the SDK neither enforces nor truncates.
+    #
+    # @return [Array<Hash{Symbol => Object}>, nil]
+    attr_accessor :resource_links
+
+    # Display flags with the same meaning as on {TaskStartedMessage}:
+    # `skip_transcript` (hide from the inline transcript) and `ambient` (not
+    # activity — exclude from activity indicators). Optional Booleans: `nil`
+    # when absent, an explicit `false` preserved. The SDK does not act on them.
+    #
+    # @return [Boolean, nil]
+    attr_accessor :skip_transcript, :ambient
   end
 
   # Task updated system message (background task lifecycle state change).
@@ -455,18 +530,105 @@ module ClaudeAgentSDK
   # or absent patch falls back to {}; and `task_id` defaults to "" (never nil,
   # matching the Python SDK) so consumers can rely on it always being a String.
   # The full patch is preserved on `#patch` for callers that need more than the
-  # status.
+  # derived readers.
+  #
+  # A patch carries only the fields that changed, so every derived reader is
+  # `nil` when its field is absent. That matters most for `is_backgrounded`:
+  # `true` means the task just moved to the background (e.g. after
+  # {Client#background_tasks}), while `nil` means "this patch does not mention
+  # it" — not "foreground". Merge patches into your own task map rather than
+  # reading any single one as the task's full state.
   class TaskUpdatedMessage < SystemMessage
-    attr_accessor :task_id, :patch, :status, :uuid, :session_id
+    attr_accessor :task_id, :patch, :status, :uuid, :session_id,
+                  :description,     # patch[:description] — String, nil when unchanged
+                  :error,           # patch[:error] — String, nil when unchanged
+                  :end_time,        # patch[:end_time] — Integer (epoch ms), nil when unchanged
+                  :total_paused_ms, # patch[:total_paused_ms] — Integer, nil when unchanged
+                  :is_backgrounded  # patch[:is_backgrounded] — true/false, nil when unchanged
 
     def initialize(attributes = {})
       super
       @task_id ||= ''
       @patch = {} unless @patch.is_a?(Hash)
-      @status = @patch[:status]
+      @status = patch_value(:status)
+      @description = patch_value(:description)
+      @error = patch_value(:error)
+      @end_time = patch_value(:end_time)
+      @total_paused_ms = patch_value(:total_paused_ms)
+      @is_backgrounded = patch_value(:is_backgrounded)
+    end
+
+    private
+
+    # The parser always hands over a symbol-keyed patch; a hand-built message
+    # may use string keys. `fetch` with a block (not `||`) keeps an explicit
+    # `false` from falling through to the string-key lookup's nil.
+    def patch_value(key)
+      @patch.fetch(key) { @patch[key.to_s] }
     end
   end
 
+  # Background tasks changed system message: the full set of live background
+  # tasks, emitted whenever membership changes (start, completion, kill, a
+  # foreground agent being backgrounded) or an entry's `ambient` flag flips.
+  #
+  # A **level** signal with **REPLACE semantics** — `tasks` is every live
+  # background task after the change, so swap your set for each payload rather
+  # than pairing task_started / task_notification edges; a missed edge then
+  # cannot wedge a stale "running" indicator. Per the CLI's contract:
+  #
+  # - Ordering relative to the edge frames for the same transition is
+  #   unspecified, and the payload carries ids only — do not correlate it
+  #   with the edge stream.
+  # - The level is per-process: nothing is emitted at startup, so reset to the
+  #   empty set whenever the session's CLI process (re)starts.
+  # - `tasks: []` is an authoritative empty snapshot for that process, not a
+  #   missing value.
+  # - A repeated `initialize` on an already-running process is answered with a
+  #   snapshot of the current set (even an empty one) right behind its success
+  #   response; older CLIs send nothing there. This SDK initializes once per
+  #   connection, so that only matters to custom transports that reconnect.
+  # - It covers *background* tasks only. A foreground subagent (the spawning
+  #   tool call still blocking) is not listed until it is backgrounded.
+  #
+  # `tasks` is passed through untouched: an Array of symbol-keyed Hashes
+  # `{ task_id:, task_type:, description:, ambient: }`. `:ambient` is optional;
+  # true marks tasks that are not activity (housekeeping, live-update
+  # watchers), which hosts should exclude from activity indicators.
+  #
+  # The SDK itself deliberately does not consume this frame for its own
+  # stdin-close bookkeeping; it is typed purely for consumers.
+  class BackgroundTasksChangedMessage < SystemMessage
+    attr_accessor :tasks, :uuid, :session_id
+  end
+
+  # Permission denied system message: a tool call was auto-denied without an
+  # interactive permission prompt (auto-mode classifier, dontAsk mode,
+  # headless-agent auto-deny, a deny rule, or — with no can_use_tool callback —
+  # an "ask" decision that nobody can answer). The "ask" path with a callback
+  # surfaces through can_use_tool instead.
+  #
+  # **Best-effort advisory, not a complete denial feed**:
+  # {ResultMessage#permission_denials} is the authoritative record. In rare
+  # races a booked denial has no frame, or a frame has no booked denial — so do
+  # not derive counts or permission state from this stream. Not covered at all:
+  # PreToolUse hook denies, deny-rule overrides of a hook's allow/ask decision,
+  # Read/Edit/Write calls refused by a path-scoped deny rule (all resolve before
+  # the permission check), and the MCP `--permission-prompt-tool` surface.
+  #
+  # `agent_id` is a subagent id for host-side routing; it is NOT a permission
+  # `request_id`, and this message is not a pending permission request.
+  # `decision_reason_type` is an open String (the values below are examples,
+  # not an enum). The CLI's `decision_reason_code` is marked internal and is
+  # left to `#data` with no stability promise.
+  class PermissionDeniedMessage < SystemMessage
+    attr_accessor :uuid, :session_id, :tool_name, :tool_use_id,
+                  :agent_id,             # Subagent ID when the denied call originated inside a subagent; nil otherwise
+                  :decision_reason_type, # Open String, e.g. "classifier", "asyncAgent", "mode", "rule"; nil when not reported
+                  :decision_reason,      # Human-readable reason from the deciding component; nil when not reported
+                  :message               # The rejection message returned to the model in the tool_result
+  end
+
   # Result message with cost and usage information
   class ResultMessage < Type
     # model_usage maps model name => per-model usage Hash, passed through
@@ -742,8 +904,10 @@ module ClaudeAgentSDK
   # `decision_reason`) so the SDK consumer can render the same prompt UI
   # the CLI would have shown. Older fields (`signal`, `suggestions`,
   # `tool_use_id`, `agent_id`) remain unchanged.
+  # `signal` is a CancellationSignal on dispatched callbacks; `request_id`
+  # identifies this permission request (distinct from the tool invocation).
   class ToolPermissionContext < Type
-    attr_accessor :signal, :suggestions, :tool_use_id, :agent_id,
+    attr_accessor :signal, :request_id, :suggestions, :tool_use_id, :agent_id,
                   :title, :display_name, :description,
                   :blocked_path, :decision_reason
 
@@ -786,9 +950,10 @@ module ClaudeAgentSDK
     end
   end
 
-  # Hook context passed to hook callbacks
+  # Hook context passed to hook callbacks. Dispatched hooks receive the control
+  # request ID and a CancellationSignal (including on HookMatcher timeout).
   class HookContext < Type
-    attr_accessor :signal
+    attr_accessor :signal, :request_id
   end
 
   # Base hook input with common fields
@@ -828,8 +993,11 @@ module ClaudeAgentSDK
   end
 
   # Stop hook input
+  # Snapshot arrays are passed through unchanged. nil means unavailable;
+  # [] means the CLI provided an empty snapshot. They cover the parent
+  # session's background work, NOT all foreground and background agents.
   class StopHookInput < BaseHookInput
-    attr_accessor :stop_hook_active, :last_assistant_message
+    attr_accessor :stop_hook_active, :last_assistant_message, :background_tasks, :session_crons
 
     def initialize(attributes = {})
       super
@@ -841,7 +1009,7 @@ module ClaudeAgentSDK
   # SubagentStop hook input
   class SubagentStopHookInput < BaseHookInput
     attr_accessor :stop_hook_active, :agent_id, :agent_transcript_path, :agent_type,
-                  :last_assistant_message
+                  :last_assistant_message, :background_tasks, :session_crons
 
     def initialize(attributes = {})
       super
@@ -1888,6 +2056,34 @@ module ClaudeAgentSDK
       @forward_subagent_text = 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.
+    # `summary` stays optional on the wire even then — not every progress
+    # frame has one — so read it nil-safely. `false` / `nil` do not enable
+    # generation; they do not promise that `summary` is absent (a process that
+    # already enabled summaries keeps them, and a backgrounded `mcp_task`
+    # reports its own status there regardless of this option). Matches the
+    # CLI's `agentProgressSummaries` initialize field.
+    #
+    # Defaults to `nil` (unset): the key is omitted from the `initialize`
+    # control request. `true` and `false` are forwarded verbatim. This is an
+    # enable switch, not a live toggle: CLI 2.1.278 only acts on a truthy
+    # value, so `false` is schema-valid but equivalent to leaving the option
+    # unset — it does not switch summaries off on a process that already
+    # enabled them. Both {ClaudeAgentSDK.query} and {Client} run the control
+    # protocol, so the option applies to either entry point.
+    #
+    # Assigning coerces to a Boolean and keeps `nil` as `nil`.
+    #
+    # @return [Boolean, nil]
+    attr_reader :agent_progress_summaries
+
+    # @see #agent_progress_summaries
+    def agent_progress_summaries=(value)
+      @agent_progress_summaries = coerce_boolean(value)
+    end
+
     CALLBACK_SCHEDULING_MODES = %i[thread inline].freeze
 
     # Where user callbacks (hooks, can_use_tool, SDK MCP handlers, message
@@ -1952,6 +2148,12 @@ module ClaudeAgentSDK
     # Merge caller-provided attributes with configured defaults.
     # Only keys the caller explicitly passed are treated as overrides;
     # method-signature defaults ([], {}, false) are NOT present unless the caller wrote them.
+    #
+    # Both sides are keyed by the option they name, not by their literal
+    # spelling: Type accepts symbol/string and snake_case/camelCase names, so a
+    # caller's `'permissionMode' => nil` must still inherit a configured
+    # `permission_mode:` (and a Hash must still merge into it) rather than
+    # riding along as a second entry that overwrites the default on assignment.
     def merge_with_defaults(attributes)
       return attributes unless defined?(ClaudeAgentSDK) && ClaudeAgentSDK.respond_to?(:default_options)
 
@@ -1962,8 +2164,10 @@ module ClaudeAgentSDK
       # duped so per-instance mutation (options.allowed_tools << 'Bash')
       # can never corrupt the global defaults; non-container leaves
       # (Strings, Procs, SdkMcpServer instances) intentionally keep identity.
-      result = deep_dup_containers(defaults)
+      result = {}
+      defaults.each { |key, value| result[option_key(key)] = deep_dup_containers(value) }
       attributes.each do |key, value|
+        key = option_key(key)
         default_val = result[key]
         result[key] = if value.nil?
                         default_val # nil means "no preference" — keep the configured default
@@ -1976,6 +2180,14 @@ module ClaudeAgentSDK
       result
     end
 
+    # The canonical Symbol for a known option, whatever its spelling. An
+    # unknown name is returned untouched so assign_attribute's strict check
+    # reports the typo exactly as the developer wrote it.
+    def option_key(name)
+      normalized = normalize_name(name)
+      respond_to?(:"#{normalized}=") ? normalized.to_sym : name
+    end
+
     # Recurse ONLY into Hash/Array; leaves keep object identity (observer
     # factories, callbacks, SDK MCP server instances must not be duped).
     # Rebuild via dup.clear (never Hash#to_h / Array#map) to preserve

data/lib/claude_agent_sdk/version.rb

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