claude-agent-sdk 1.1.0 → 1.2.1

data/lib/claude_agent_sdk/command_builder.rb

@@ -3,6 +3,7 @@
 require 'json'
 require_relative 'errors'
 require_relative 'types'
+require_relative 'option_forms'
 
 module ClaudeAgentSDK
   # Builds the CLI argv array from a ClaudeAgentOptions instance.
@@ -68,42 +69,32 @@ module ClaudeAgentSDK
 
     private
 
+    # What the option stands for, typed or as a Hash, is OptionForms' to say;
+    # a kind that is none of these (a preset without an append, a Hash the
+    # SDK does not recognize, ...) sends no prompt flag at all.
     def append_system_prompt(cmd)
-      case @options.system_prompt
-      when nil
+      prompt = OptionForms.system_prompt(@options.system_prompt)
+      case prompt.kind
+      when :empty
         # When nil, pass empty string to ensure predictable behavior without default Claude Code system prompt
         cmd.push('--system-prompt', '')
-      when String
-        cmd.push('--system-prompt', @options.system_prompt)
-      when SystemPromptFile
-        cmd.push('--system-prompt-file', @options.system_prompt.path)
-      when SystemPromptCustom
-        # The object form of a String prompt; snapshot travels on the
+      when :text
+        # A String, or its object form (custom); snapshot travels on the
         # initialize request, not as a CLI flag.
-        cmd.push('--system-prompt', custom_prompt_text(@options.system_prompt.prompt))
-      when SystemPromptPreset
+        cmd.push('--system-prompt', custom_prompt_text(prompt.value))
+      when :file
+        cmd.push('--system-prompt-file', path_string(prompt.value))
+      when :append
         # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
         # Only --append-system-prompt is passed if append text is provided
-        cmd.push('--append-system-prompt', @options.system_prompt.append) if @options.system_prompt.append
-      when Hash
-        append_hash_system_prompt(cmd, @options.system_prompt)
+        cmd.push('--append-system-prompt', prompt.value)
       end
     end
 
-    def append_hash_system_prompt(cmd, prompt_hash)
-      prompt_type = prompt_hash[:type] || prompt_hash['type']
-      case prompt_type
-      when 'file'
-        prompt_path = prompt_hash[:path] || prompt_hash['path']
-        cmd.push('--system-prompt-file', prompt_path) if prompt_path
-      when 'custom'
-        prompt = prompt_hash.fetch(:prompt) { prompt_hash['prompt'] }
-        cmd.push('--system-prompt', custom_prompt_text(prompt))
-      when 'preset'
-        append = prompt_hash[:append] || prompt_hash['append']
-        # Preset activates the default Claude Code system prompt by not passing --system-prompt ""
-        cmd.push('--append-system-prompt', append) if append
-      end
+    # A path as the String the command line takes. A Pathname (anything that
+    # answers #to_path) is converted; every other value is returned as it is.
+    def path_string(path)
+      path.respond_to?(:to_path) ? path.to_path : path
     end
 
     # A custom prompt is always forwarded, even when empty (an empty String
@@ -129,8 +120,12 @@ module ClaudeAgentSDK
     # Each listed name is validated before being formatted into a rule (see
     # #validate_skill_name). Both SDKs reject non-list, non-'all' shapes
     # loudly; this raises ArgumentError where Python raises TypeError.
+    #
+    # allowed_tools, like disallowed_tools, add_dirs and extra_args below, is
+    # nil when it was set to nil after construction (the readers are signed
+    # nilable); each use site reads nil as the constructor's default.
     def skills_defaults
-      allowed_tools = @options.allowed_tools.dup
+      allowed_tools = (@options.allowed_tools || []).dup
       setting_sources = @options.setting_sources&.dup
       skills = @options.skills
       return [allowed_tools, setting_sources] if skills.nil?
@@ -210,7 +205,8 @@ module ClaudeAgentSDK
     end
 
     def append_disallowed_tools(cmd)
-      cmd.push('--disallowedTools', @options.disallowed_tools.join(',')) unless @options.disallowed_tools.empty?
+      disallowed_tools = @options.disallowed_tools || []
+      cmd.push('--disallowedTools', disallowed_tools.join(',')) unless disallowed_tools.empty?
     end
 
     def append_max_turns(cmd)
@@ -301,16 +297,14 @@ module ClaudeAgentSDK
       settings_is_path = false
 
       if @options.settings
-        if @options.settings.is_a?(String)
+        if @options.settings.respond_to?(:to_path)
+          # A Pathname names a settings file; it is never tried as inline JSON.
+          settings_hash, settings_is_path = settings_file(cmd, @options.settings.to_path)
+        elsif @options.settings.is_a?(String)
           begin
             settings_hash = JSON.parse(@options.settings)
           rescue JSON::ParserError
-            if @options.sandbox.nil? # rubocop:disable Metrics/BlockNesting -- settings-is-a-path fallback inside the JSON parse rescue
-              settings_is_path = true
-              cmd.push('--settings', @options.settings)
-            else
-              settings_hash = load_settings_file(@options.settings)
-            end
+            settings_hash, settings_is_path = settings_file(cmd, @options.settings)
           end
         elsif @options.settings.is_a?(Hash)
           settings_hash = @options.settings.dup
@@ -318,22 +312,31 @@ module ClaudeAgentSDK
       end
 
       if !settings_is_path && !@options.sandbox.nil?
-        settings_hash[:sandbox] = @options.sandbox.is_a?(SandboxSettings) ? @options.sandbox.to_h : @options.sandbox
+        # The option replaces any sandbox section the settings carry. Settings
+        # read from JSON spell that key as a String; left next to the Symbol
+        # key below it would be written twice (json 3.x raises on that).
+        settings_hash = settings_hash.reject { |key, _| key.to_s == 'sandbox' }
+        settings_hash[:sandbox] = OptionForms.sandbox(@options.sandbox)
       end
 
       cmd.push('--settings', JSON.generate(settings_hash)) if !settings_is_path && !settings_hash.empty?
     end
 
+    # --settings for a settings file, as [settings_hash, settings_is_path].
+    # Without a sandbox option the path itself is passed and the CLI reads
+    # the file. With one, the file is read here, so that the option can be
+    # folded into its content.
+    def settings_file(cmd, path)
+      return [load_settings_file(path), false] unless @options.sandbox.nil?
+
+      cmd.push('--settings', path)
+      [{}, true]
+    end
+
     def append_budget(cmd)
       cmd.push('--max-budget-usd', @options.max_budget_usd.to_s) if @options.max_budget_usd
 
-      return unless @options.task_budget
-
-      total = if @options.task_budget.is_a?(TaskBudget)
-                @options.task_budget.total
-              else
-                @options.task_budget[:total] || @options.task_budget['total']
-              end
+      total = OptionForms.task_budget_total(@options.task_budget)
       cmd.push('--task-budget', total.to_s) if total
     end
 
@@ -345,16 +348,16 @@ module ClaudeAgentSDK
     # max_thinking_tokens fallback.
     def append_thinking(cmd)
       if @options.thinking
-        type, budget, display = thinking_fields(@options.thinking)
-        case type
+        thinking = OptionForms.thinking(@options.thinking)
+        case thinking.type
         when 'adaptive'
           cmd.push('--thinking', 'adaptive')
-          append_thinking_display(cmd, display)
+          append_thinking_display(cmd, thinking.display)
         when 'enabled'
-          raise ArgumentError, "thinking type 'enabled' requires budget_tokens" if budget.nil?
+          raise ArgumentError, "thinking type 'enabled' requires budget_tokens" if thinking.budget_tokens.nil?
 
-          cmd.push('--max-thinking-tokens', budget.to_s)
-          append_thinking_display(cmd, display)
+          cmd.push('--max-thinking-tokens', thinking.budget_tokens.to_s)
+          append_thinking_display(cmd, thinking.display)
         when 'disabled'
           cmd.push('--thinking', 'disabled')
         else
@@ -365,20 +368,6 @@ module ClaudeAgentSDK
       end
     end
 
-    # Explicit class dispatch — never respond_to? probes (Kernel#display
-    # exists on every object and PRINTS the receiver to $stdout).
-    def thinking_fields(thinking)
-      case thinking
-      when Hash
-        type = (thinking[:type] || thinking['type'])&.to_s
-        [type, thinking[:budget_tokens] || thinking['budget_tokens'], thinking[:display] || thinking['display']]
-      when ThinkingConfigAdaptive then [thinking.type, nil, thinking.display]
-      when ThinkingConfigEnabled then [thinking.type, thinking.budget_tokens, thinking.display]
-      when ThinkingConfigDisabled then [thinking.type, nil, nil]
-      else [nil, nil, nil] # falls into append_thinking's else -> ArgumentError
-      end
-    end
-
     # `--thinking-display` toggles between `"summarized"` (visible thinking
     # text) and `"omitted"` (empty thinking, signature only). Current models default
     # to `"omitted"`, so pass `display: "summarized"` to see reasoning.
@@ -404,31 +393,27 @@ module ClaudeAgentSDK
     def append_tools(cmd)
       return if @options.tools.nil?
 
-      case @options.tools
+      # The preset, typed or as a Hash, is OptionForms' to recognize; every
+      # other value comes back as it was given and is only encoded here.
+      tools = OptionForms.tools(@options.tools)
+      case tools
+      when OptionForms::DEFAULT_TOOLS
+        cmd.push('--tools', 'default')
       when Array
-        tools_value = @options.tools.empty? ? '' : @options.tools.join(',')
+        tools_value = tools.empty? ? '' : tools.join(',')
         cmd.push('--tools', tools_value)
-      when ToolsPreset
-        cmd.push('--tools', 'default')
+      when String
+        # The CLI's own syntax ("Read,Grep", "default", ""): passed as written.
+        cmd.push('--tools', tools)
       when Hash
-        if (@options.tools[:type] || @options.tools['type']) == 'preset'
-          cmd.push('--tools', 'default')
-        else
-          cmd.push('--tools', JSON.generate(@options.tools))
-        end
+        cmd.push('--tools', JSON.generate(tools))
       end
     end
 
     def append_output_format(cmd)
       return unless @options.output_format
 
-      schema = if @options.output_format.is_a?(Hash) && @options.output_format[:type] == 'json_schema'
-                 @options.output_format[:schema]
-               elsif @options.output_format.is_a?(Hash) && @options.output_format['type'] == 'json_schema'
-                 @options.output_format['schema']
-               else
-                 @options.output_format
-               end
+      schema = OptionForms.output_schema(@options.output_format)
       # A json_schema output_format with a nil/absent schema must skip the
       # flag — `--json-schema null` is rejected by the CLI (Python guards
       # `schema is not None`).
@@ -439,31 +424,21 @@ module ClaudeAgentSDK
     end
 
     def append_additional_dirs(cmd)
-      @options.add_dirs.each { |dir| cmd.push('--add-dir', dir.to_s) }
+      (@options.add_dirs || []).each { |dir| cmd.push('--add-dir', dir.to_s) }
     end
 
     def append_mcp_servers(cmd)
       return unless @options.mcp_servers && !@options.mcp_servers.empty?
 
-      if @options.mcp_servers.is_a?(Hash)
-        servers_for_cli = {}
-        @options.mcp_servers.each do |name, config|
-          # Typed Mcp*ServerConfig objects serialize via their wire hash —
-          # without this they'd JSON-stringify as "#<...>" via to_s.
-          config = config.to_h if config.is_a?(Type)
-          # Same recognition rule as ClaudeAgentSDK.extract_sdk_mcp_servers:
-          # either key style (and a Symbol :sdk type). The live instance is
-          # never serialized — JSON.generate would raise on it or leak its
-          # #to_s onto the command line.
-          servers_for_cli[name] = if config.is_a?(Hash) && (config[:type] || config['type']).to_s == 'sdk'
-                                    config.except(:instance, 'instance')
-                                  else
-                                    config
-                                  end
-        end
-        cmd.push('--mcp-config', JSON.generate({ mcpServers: servers_for_cli })) unless servers_for_cli.empty?
+      # A Hash of servers comes back with typed configs as their wire Hashes
+      # and without the live instance of an SDK server, which is never
+      # serialized: JSON.generate would raise on it or leak its #to_s onto
+      # the command line. Any other value is a path or JSON text.
+      servers = OptionForms.mcp_servers(@options.mcp_servers)
+      if servers.is_a?(Hash)
+        cmd.push('--mcp-config', JSON.generate({ mcpServers: servers })) unless servers.empty?
       else
-        cmd.push('--mcp-config', @options.mcp_servers.to_s)
+        cmd.push('--mcp-config', servers.to_s)
       end
     end
 
@@ -482,17 +457,17 @@ module ClaudeAgentSDK
     def append_plugins(cmd)
       return unless @options.plugins && !@options.plugins.empty?
 
-      @options.plugins.each do |plugin|
-        plugin_config = plugin.is_a?(SdkPluginConfig) ? plugin.to_h : plugin
-        plugin_type = plugin_config[:type] || plugin_config['type']
-        plugin_path = plugin_config[:path] || plugin_config['path']
+      @options.plugins.each do |entry|
+        plugin = OptionForms.plugin(entry)
 
-        unless %w[local plugin].include?(plugin_type)
-          raise ArgumentError, "Unsupported plugin type: #{plugin_type.inspect}"
+        unless %w[local plugin].include?(plugin.type_tag)
+          # raw_type looks the type up again, as it was written; asked for
+          # only here, so an accepted plugin has its type read once.
+          raise ArgumentError, "Unsupported plugin type: #{plugin.raw_type.inspect}"
         end
-        next unless plugin_path
+        next unless plugin.path
 
-        cmd.push('--plugin-dir', plugin_path)
+        cmd.push('--plugin-dir', path_string(plugin.path))
       end
     end
 
@@ -503,7 +478,7 @@ module ClaudeAgentSDK
     end
 
     def append_extra_args(cmd)
-      @options.extra_args.each do |flag, value|
+      (@options.extra_args || {}).each do |flag, value|
         unless EXTRA_ARG_FLAG_REGEXP.match?(flag)
           raise ArgumentError, "Invalid extra_args flag name: #{flag.inspect} (expected lowercase kebab-case)"
         end

data/lib/claude_agent_sdk/fiber_boundary.rb

@@ -135,6 +135,23 @@ module ClaudeAgentSDK
       end
     end
 
+    # What a failing user callback raises — a hook, can_use_tool, an SDK MCP
+    # tool / resource / prompt handler, or the callback_wrapper around one.
+    # The Ruby spelling of Python's `except Exception`: NotImplementedError
+    # and LoadError (both ScriptError), SystemStackError and SecurityError
+    # are not StandardErrors, so `rescue StandardError` lets them through.
+    # The control request then goes unanswered and its handler task ends
+    # with an exception Async treats as fatal for the whole reactor. Rescue
+    # `*FiberBoundary::CALLBACK_FAILURES` wherever a callback's failure is
+    # turned into the answer the CLI is waiting for.
+    #
+    # An explicit list, not `rescue Exception`: cancellation (Async::Stop,
+    # InlineCancellation) and process exits (SystemExit, SignalException —
+    # see .invoke_callback) must keep propagating. NoMemoryError stays out
+    # as well: building the answer would most likely fail again.
+    # @api private
+    CALLBACK_FAILURES = [StandardError, ScriptError, SystemStackError, SecurityError].freeze
+
     # Carries a SystemExit / SignalException (Interrupt included) raised by
     # a user callback out of the FiberBoundary hop — see .invoke_callback.
     # A StandardError so the hop ends normally: a :thread worker that died
@@ -335,9 +352,35 @@ module ClaudeAgentSDK
         Thread.current.report_on_exception = false
         work.call
       end
-      return thread.value if timeout.nil?
-      raise JoinTimeout, "timed out after #{timeout}s" unless thread.join(timeout)
+      await_worker(thread, timeout)
+    end
+
+    # Wait for the worker thread of one hop and return its value (or re-raise
+    # what it raised); with +timeout+, raise JoinTimeout once that many
+    # seconds have passed.
+    #
+    # Only "the thread has finished" or "the deadline has really passed" ends
+    # the wait. Under a fiber scheduler Thread#join parks the fiber, and MRI
+    # reports ANY wakeup that finds the thread alive as a timeout: join
+    # returns nil, and Thread#value returns nil with it. The wakeup need not
+    # belong to this join — one queued by an earlier hop's thread stays behind
+    # when an exception (Async::Stop, a deadline) is raised into the fiber
+    # before it is consumed, and resumes this hop instead. Trusting a single
+    # join then returned nil while the callback was still running, or raised
+    # JoinTimeout with no time passed.
+    # @api private
+    def await_worker(thread, timeout)
+      if timeout.nil?
+        nil until thread.join
+        return thread.value
+      end
 
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      until thread.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max)
+        next if Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+
+        raise JoinTimeout, "timed out after #{timeout}s"
+      end
       thread.value
     end
 

data/lib/claude_agent_sdk/instrumentation/otel.rb

@@ -7,8 +7,10 @@ module ClaudeAgentSDK
   module Instrumentation
     # OpenTelemetry observer that emits spans for Claude Agent SDK messages.
     #
-    # Uses standard gen_ai.* semantic conventions recognized by Langfuse, Datadog,
-    # Jaeger, and other OTel-compatible backends.
+    # Span attributes follow the Langfuse and OpenInference conventions, plus a
+    # subset of the OTel gen_ai.* attributes. docs/observability.md lists every
+    # attribute and says where they differ from the OTel GenAI semantic
+    # conventions.
     #
     # Requires the `opentelemetry-api` gem at runtime. Users must configure
     # `opentelemetry-sdk` and an exporter (e.g., `opentelemetry-exporter-otlp`)
@@ -49,10 +51,12 @@ module ClaudeAgentSDK
         @default_attributes = default_attributes
         @root_span = nil
         @root_context = nil
+        @trace_started = false # an InitMessage opened a trace since this observer was created or last closed
         @tool_spans = {} # tool_use_id => span
         @first_user_input = nil # first user prompt of the current trace
         @pending_prompt = nil # prompt that belongs to the NEXT trace (see on_user_prompt)
         @last_assistant_text = nil # capture last assistant text for trace output
+        @usage_reported_message_ids = Set.new # API responses whose usage a generation span of this trace carries
         @cost_session_id = nil
         @last_total_cost_usd = nil
       end
@@ -99,16 +103,25 @@ module ClaudeAgentSDK
         end
       end
 
-      # Recording-only by design: a Client session can survive an error (the
-      # user may rescue one bad message and keep receiving), so finishing here
-      # would orphan later spans and break the next turn. Finish ownership
-      # stays with end_trace/on_close; start_trace also finishes any dangling
-      # span from a previous trace as the never-disconnected backstop.
+      # With a trace open this is recording-only by design: a Client session
+      # can survive an error (the user may rescue one bad message and keep
+      # receiving), so finishing here would orphan later spans and break the
+      # next turn. Finish ownership stays with end_trace/on_close; start_trace
+      # also finishes any dangling span from a previous trace as the
+      # never-disconnected backstop.
+      #
+      # With no trace open, an error that arrives before the session's first
+      # InitMessage gets a session span of its own (record_failed_start). Once
+      # a trace has run, an error between traces stays unrecorded: the usual
+      # one is the ResultError query() raises when the CLI exits non-zero
+      # after an error result, and the trace that just ended already reports
+      # that failure.
       def on_error(error)
-        return unless @root_span
-
-        @root_span.record_exception(error)
-        @root_span.status = OpenTelemetry::Trace::Status.error(error.message)
+        if @root_span
+          record_error(@root_span, error)
+        elsif !@trace_started
+          record_failed_start(error)
+        end
       end
 
       def on_close
@@ -120,11 +133,12 @@ module ClaudeAgentSDK
         @pending_prompt = nil
         @cost_session_id = nil
         @last_total_cost_usd = nil
+        @trace_started = false
       end
 
       private
 
-      def start_trace(message) # rubocop:disable Metrics/AbcSize -- flat mapping of init-message fields to root span attributes
+      def start_trace(message)
         # A new init without an intervening ResultMessage (e.g. /clear or an
         # interrupted turn) supersedes the current trace; finish it so it is
         # exported instead of leaking as a never-ended span, and reset the
@@ -141,21 +155,9 @@ module ClaudeAgentSDK
         # because it came first chronologically.
         @first_user_input = @pending_prompt if @pending_prompt
         @pending_prompt = nil
+        @trace_started = true
 
-        attrs = {
-          # gen_ai semantic conventions (recognized by Langfuse, Datadog, etc.)
-          'gen_ai.system' => 'anthropic',
-          'gen_ai.request.model' => message.model,
-          # OpenInference conventions (recognized by Langfuse, Arize)
-          'openinference.span.kind' => 'AGENT',
-          'llm.model_name' => message.model,
-          'input.mime_type' => 'text/plain',
-          'output.mime_type' => 'text/plain',
-          # Langfuse: 'agent' type triggers the trace flow diagram (DAG graph)
-          'langfuse.observation.type' => 'agent',
-          # Session tracking
-          'session.id' => message.session_id
-        }.merge(@default_attributes)
+        attrs = session_span_attrs(model: message.model, session_id: message.session_id)
 
         if message.respond_to?(:claude_code_version) && message.claude_code_version
           attrs['claude_code.version'] = message.claude_code_version
@@ -174,6 +176,50 @@ module ClaudeAgentSDK
         @root_span.set_attribute('input.value', truncate(@first_user_input))
       end
 
+      # The attributes every session span starts with. The model and the
+      # session id come from the InitMessage, so the span of a session that
+      # failed before sending one (record_failed_start) has neither.
+      def session_span_attrs(model: nil, session_id: nil)
+        {
+          # gen_ai semantic conventions (recognized by Langfuse, Datadog, etc.)
+          'gen_ai.system' => 'anthropic',
+          'gen_ai.request.model' => model,
+          # OpenInference conventions (recognized by Langfuse, Arize)
+          'openinference.span.kind' => 'AGENT',
+          'llm.model_name' => model,
+          'input.mime_type' => 'text/plain',
+          'output.mime_type' => 'text/plain',
+          # Langfuse: 'agent' type triggers the trace flow diagram (DAG graph)
+          'langfuse.observation.type' => 'agent',
+          # Session tracking
+          'session.id' => session_id
+        }.merge(@default_attributes)
+      end
+
+      # A session that fails before its first InitMessage (the CLI cannot be
+      # found or started, initialize fails or times out, the process dies
+      # before its first frame) has no trace to record the error on, so the
+      # error gets a session span of its own, with the prompt if one was sent.
+      #
+      # The span is finished here and never becomes @root_span. query() does
+      # call on_close next, but a Client#connect that fails before the
+      # handshake never does, and an unfinished span is never exported; with
+      # no root span set, a later on_close has nothing to finish a second
+      # time. The buffers are reset so that the failed session's prompt cannot
+      # label the next trace of a reused observer.
+      def record_failed_start(error)
+        span = @tracer.start_span('claude_agent.session', attributes: compact_attrs(session_span_attrs))
+        span.set_attribute('input.value', truncate(@first_user_input)) if @first_user_input
+        record_error(span, error)
+        span.finish
+        reset_session_buffers
+      end
+
+      def record_error(span, error)
+        span.record_exception(error)
+        span.status = OpenTelemetry::Trace::Status.error(error.message)
+      end
+
       def handle_assistant(message)
         return unless @root_context
 
@@ -203,7 +249,7 @@ module ClaudeAgentSDK
           'gen_ai.completion' => truncate(combined_text),
           # OpenInference: Langfuse maps output.value to the Preview Output field
           'output.value' => truncate(combined_text)
-        }.merge(usage_token_attrs(message.usage || {}))
+        }.merge(generation_usage_attrs(message))
 
         OpenTelemetry::Context.with_current(@root_context) do
           span = @tracer.start_span('claude_agent.generation', attributes: compact_attrs(attrs))
@@ -343,10 +389,12 @@ module ClaudeAgentSDK
 
       # Clear per-trace buffers so a reused observer instance (sequential
       # query() calls or multi-turn Client sessions) does not stamp stale
-      # input/output onto later traces.
+      # input/output onto later traces, and so the message ids remembered by
+      # generation_usage_attrs never outlive their trace.
       def reset_session_buffers
         @first_user_input = nil
         @last_assistant_text = nil
+        @usage_reported_message_ids.clear
       end
 
       def record_retry_event(message)
@@ -397,6 +445,20 @@ module ClaudeAgentSDK
         }
       end
 
+      # gen_ai.usage.* attributes for one generation span. The CLI sends one
+      # assistant frame per content block, and every frame of an API response
+      # repeats that response's message id and usage snapshot, so putting the
+      # snapshot on every span counted the response's input, cache-read and
+      # cache-creation tokens once per block. Only the first span of a message
+      # id carries it. A message without an id cannot be grouped and keeps its
+      # usage; a frame without usage does not use up its id.
+      def generation_usage_attrs(message)
+        attrs = compact_attrs(usage_token_attrs(message.usage || {}))
+        return attrs if attrs.empty? || message.message_id.nil?
+
+        @usage_reported_message_ids.add?(message.message_id) ? attrs : {}
+      end
+
       # Usage hashes arrive symbol-keyed from the live CLI (symbolize_names:
       # true) and string-keyed from session transcripts.
       def usage_value(usage, key)