riffer 0.31.0 → 0.32.0

data/lib/riffer/skills/context.rb

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Skills context for an agent generation cycle.
-#
-# Coordinates skill discovery, activation, and prompt rendering.
-# Tracks activations with caching to avoid redundant backend reads.
-#
-# Built by the agent during +Agent.new+ and exposed to tools via
-# <tt>context.skills</tt> on the agent's +Riffer::Agent::Context+.
-#
-# See Riffer::Skills::Backend, Riffer::Skills::Frontmatter.
+# Skills context for an agent generation cycle — coordinates discovery,
+# activation, and prompt rendering, caching activations to avoid redundant
+# backend reads. Exposed to tools via <tt>context.skills</tt>.
 class Riffer::Skills::Context
   # @rbs @backend: Riffer::Skills::Backend
   # @rbs @activated: Hash[String, String]
@@ -23,13 +17,6 @@ class Riffer::Skills::Context
   # Optional callback invoked when a skill is first activated.
   attr_writer :on_activate #: (^(String) -> void)?
 
-  # Creates a new skills context for a generation cycle.
-  #
-  # [backend] the skills backend for reading skill bodies.
-  # [skills] skill catalog indexed by name.
-  # [adapter] the adapter used to render skill content. The adapter
-  #           carries the activation tool class via its initializer.
-  #
   #--
   #: (backend: Riffer::Skills::Backend, skills: Hash[String, Riffer::Skills::Frontmatter], adapter: Riffer::Skills::Adapter) -> void
   def initialize(backend:, skills:, adapter:)
@@ -61,10 +48,8 @@ class Riffer::Skills::Context
     @activated.key?(name)
   end
 
-  # Returns the complete skills section for the system prompt.
-  #
-  # Includes the catalog and any pre-activated skill bodies.
-  #
+  # Returns the complete skills section for the system prompt — the catalog plus
+  # any pre-activated skill bodies.
   #--
   #: () -> String
   def system_prompt

data/lib/riffer/skills/filesystem_backend.rb

@@ -1,23 +1,13 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Built-in backend that reads skills from the filesystem.
-#
-# Scans configured directories for immediate child directories containing
-# +SKILL.md+ files. Directory names must match the skill +name+ field.
-#
-#   backend = Riffer::Skills::FilesystemBackend.new(".skills", "~/.riffer/skills")
-#   backend.list_skills  # => [Riffer::Skills::Frontmatter, ...]
-#   backend.read_skill("code-review")  # => "Full skill instructions..."
-#
+# Built-in backend that reads skills from the filesystem. Scans configured
+# directories for immediate child directories containing +SKILL.md+; directory
+# names must match the skill +name+.
 class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
   # @rbs @paths: Array[String]
   # @rbs @skills_cache: Hash[String, String]?
 
-  # Creates a new FilesystemBackend.
-  #
-  # [paths] one or more directory paths to scan for skills.
-  #
   #--
   #: (*String) -> void
   def initialize(*paths)
@@ -25,12 +15,8 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
     @skills_cache = nil #: Hash[String, String]?
   end
 
-  # Returns frontmatter for all discovered skills.
-  #
-  # Scans each configured path for immediate child directories containing
-  # SKILL.md. When multiple paths contain a skill with the same name,
-  # first-path-wins.
-  #
+  # Returns frontmatter for all discovered skills; on a name collision across
+  # paths, first-path-wins.
   #--
   #: () -> Array[Riffer::Skills::Frontmatter]
   def list_skills
@@ -59,12 +45,8 @@ class Riffer::Skills::FilesystemBackend < Riffer::Skills::Backend
     frontmatters
   end
 
-  # Returns the full SKILL.md body (without frontmatter) for a skill.
-  #
-  # [name] the skill name to read.
-  #
-  # Raises Riffer::ArgumentError if skill not found.
-  #
+  # Returns the full SKILL.md body (without frontmatter) for a skill. Raises
+  # Riffer::ArgumentError if the skill is not found.
   #--
   #: (String) -> String
   def read_skill(name)

data/lib/riffer/skills/frontmatter.rb

@@ -3,13 +3,9 @@
 
 require "yaml"
 
-# Immutable value object holding parsed SKILL.md YAML frontmatter.
-#
-# Required fields per the Agent Skills spec: +name+ and +description+.
-# All unrecognized top-level frontmatter keys are merged into +metadata+.
-#
-#   frontmatter, body = Riffer::Skills::Frontmatter.parse(raw_content)
-#
+# Immutable value object holding parsed SKILL.md YAML frontmatter. Required
+# fields: +name+ and +description+; unrecognized top-level keys are merged into
+# +metadata+.
 class Riffer::Skills::Frontmatter
   NAME_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/ #: Regexp
   MAX_NAME_LENGTH = 64 #: Integer
@@ -21,18 +17,13 @@ class Riffer::Skills::Frontmatter
   # The skill description (1-1024 chars).
   attr_reader :description #: String
 
-  # Arbitrary key-value metadata from the spec's +metadata+ field
-  # and any unrecognized top-level frontmatter keys.
+  # Metadata from the spec's +metadata+ field plus any unrecognized top-level
+  # keys.
   attr_reader :metadata #: Hash[Symbol, untyped]
 
-  # Parses a raw SKILL.md string into a Frontmatter and body.
-  #
-  # Splits on YAML front matter delimiters (+---+). Unrecognized
-  # top-level keys become +metadata+. Available to custom backends
-  # so they don't need to reimplement parsing.
-  #
-  # Raises Riffer::ArgumentError if frontmatter is invalid.
-  #
+  # Parses a raw SKILL.md string into a +[Frontmatter, body]+ pair — public so
+  # custom backends needn't reimplement parsing. Raises Riffer::ArgumentError
+  # if the frontmatter is invalid.
   #--
   #: (String) -> [Riffer::Skills::Frontmatter, String]
   def self.parse(raw)
@@ -42,9 +33,7 @@ class Riffer::Skills::Frontmatter
   end
 
   # Parses only the frontmatter from a raw SKILL.md string, ignoring the body.
-  #
-  # Raises Riffer::ArgumentError if frontmatter is invalid.
-  #
+  # Raises Riffer::ArgumentError if the frontmatter is invalid.
   #--
   #: (String) -> Riffer::Skills::Frontmatter
   def self.parse_frontmatter(raw)
@@ -68,14 +57,7 @@ class Riffer::Skills::Frontmatter
   end
   private_class_method :split_frontmatter
 
-  # Creates a new Frontmatter.
-  #
-  # [name] the skill name (must match +[a-z0-9]([a-z0-9-]*[a-z0-9])?+, 1-64 chars).
-  # [description] the skill description (1-1024 chars).
-  # [metadata] optional metadata hash.
-  #
-  # Raises Riffer::ArgumentError if name or description is invalid.
-  #
+  # Raises Riffer::ArgumentError if +name+ or +description+ is invalid.
   #--
   #: (name: String, description: String, ?metadata: Hash[Symbol, untyped]) -> void
   def initialize(name:, description:, metadata: {})

data/lib/riffer/skills/markdown_adapter.rb

@@ -1,17 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Default Markdown skill adapter.
-#
-# Renders a skill catalog as Markdown for the system prompt.
-# Used by OpenAI, Amazon Bedrock, and other providers.
-#
-# See Riffer::Skills::XmlAdapter for the Anthropic/Claude variant.
+# Default skill adapter — renders a skill catalog as Markdown for the system
+# prompt.
 class Riffer::Skills::MarkdownAdapter < Riffer::Skills::Adapter
   # Renders a skill catalog as Markdown.
-  #
-  # [skills] array of Frontmatter objects to render.
-  #
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)

data/lib/riffer/skills/xml_adapter.rb

@@ -3,16 +3,10 @@
 
 require "cgi"
 
-# XML skill adapter, optimized for Anthropic/Claude.
-#
-# Renders a skill catalog as XML for the system prompt.
-#
-# See Riffer::Skills::MarkdownAdapter for the default variant.
+# Renders a skill catalog as XML for the system prompt, optimized for
+# Anthropic/Claude.
 class Riffer::Skills::XmlAdapter < Riffer::Skills::Adapter
   # Renders a skill catalog as XML.
-  #
-  # [skills] array of Frontmatter objects to render.
-  #
   #--
   #: (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog(skills)

data/lib/riffer/stream_events/base.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Base class for all streaming events in the Riffer framework.
-#
-# Subclasses must implement the +to_h+ method.
+# Base class for all streaming events. Subclasses must implement +to_h+.
 class Riffer::StreamEvents::Base
   # The message role (typically :assistant).
   attr_reader :role #: Symbol
@@ -15,9 +13,6 @@ class Riffer::StreamEvents::Base
   end
 
   # Converts the event to a hash.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/stream_events/guardrail_modification.rb

@@ -1,18 +1,11 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a guardrail modification event during streaming.
-#
-# Emitted when a guardrail transforms data during the streaming pipeline.
+# Emitted when a guardrail transforms data during streaming.
 class Riffer::StreamEvents::GuardrailModification < Riffer::StreamEvents::Base
   # The modification record.
   attr_reader :modification #: Riffer::Guardrails::Modification
 
-  # Creates a new guardrail modification stream event.
-  #
-  # [modification] the modification details.
-  # [role] the message role (defaults to :assistant).
-  #
   #--
   #: (Riffer::Guardrails::Modification, ?role: Symbol) -> void
   def initialize(modification, role: :assistant)

data/lib/riffer/stream_events/guardrail_tripwire.rb

@@ -1,18 +1,11 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a guardrail tripwire event during streaming.
-#
-# Emitted when a guardrail blocks execution during the streaming pipeline.
+# Emitted when a guardrail blocks execution during streaming.
 class Riffer::StreamEvents::GuardrailTripwire < Riffer::StreamEvents::Base
   # The tripwire containing block details.
   attr_reader :tripwire #: Riffer::Guardrails::Tripwire
 
-  # Creates a new tripwire stream event.
-  #
-  # [tripwire] the tripwire details.
-  # [role] the message role (defaults to :assistant).
-  #
   #--
   #: (Riffer::Guardrails::Tripwire, ?role: Symbol) -> void
   def initialize(tripwire, role: :assistant)

data/lib/riffer/stream_events/interrupt.rb

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an interrupt event during streaming.
-#
-# Emitted when a callback interrupts the agent loop via +throw :riffer_interrupt+.
+# Represents an interrupt during streaming, fired when a callback throws
+# +:riffer_interrupt+.
 class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   # The reason provided with the interrupt, if any.
   attr_reader :reason #: (String | Symbol)?
 
-  # Call ids of tool_use blocks that riffer filled with placeholder
-  # results when the interrupt fired. Populated only when
-  # +Riffer.config.experimental_history_healing+ is on.
+  # Call ids of tool_use blocks riffer filled with placeholder results when the
+  # interrupt fired (only when history healing is on).
   attr_reader :healed_tool_call_ids #: Array[String]
 
   #--
@@ -22,7 +20,6 @@ class Riffer::StreamEvents::Interrupt < Riffer::StreamEvents::Base
   end
 
   # Converts the event to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/stream_events/reasoning_delta.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents an incremental reasoning chunk during streaming.
-#
-# Emitted when the LLM produces reasoning/thinking content incrementally.
-# Only available with providers that support reasoning (e.g., OpenAI with reasoning option).
+# Represents an incremental reasoning chunk during streaming; only emitted by
+# providers that support reasoning (e.g. OpenAI with the reasoning option).
 class Riffer::StreamEvents::ReasoningDelta < Riffer::StreamEvents::Base
   # The incremental reasoning content.
   attr_reader :content #: String

data/lib/riffer/stream_events/reasoning_done.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents completion of reasoning during streaming.
-#
-# Emitted when the LLM has finished producing reasoning/thinking content.
-# Only available with providers that support reasoning (e.g., OpenAI with reasoning option).
+# Represents completed reasoning during streaming; only emitted by providers
+# that support reasoning (e.g. OpenAI with the reasoning option).
 class Riffer::StreamEvents::ReasoningDone < Riffer::StreamEvents::Base
   # The complete reasoning content.
   attr_reader :content #: String

data/lib/riffer/stream_events/skill_activation.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Emitted when a skill is activated during streaming.
-#
-# Fired by the +on_activate+ callback on Riffer::Skills::Context
-# when the LLM calls the skill activation tool.
+# Emitted when a skill is activated during streaming, via the +on_activate+
+# callback when the LLM calls the activation tool.
 class Riffer::StreamEvents::SkillActivation < Riffer::StreamEvents::Base
   # The activated skill name.
   attr_reader :name #: String

data/lib/riffer/stream_events/text_delta.rb

@@ -2,8 +2,6 @@
 # rbs_inline: enabled
 
 # Represents an incremental text chunk during streaming.
-#
-# Emitted when the LLM produces text content incrementally.
 class Riffer::StreamEvents::TextDelta < Riffer::StreamEvents::Base
   # The incremental text content.
   attr_reader :content #: String

data/lib/riffer/stream_events/text_done.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents completion of text generation during streaming.
-#
-# Emitted when the LLM has finished producing text content.
+# Represents completed text generation during streaming.
 class Riffer::StreamEvents::TextDone < Riffer::StreamEvents::Base
   # The complete text content.
   attr_reader :content #: String

data/lib/riffer/stream_events/token_usage_done.rb

@@ -1,14 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents completion of token usage tracking during streaming.
-#
-# Emitted when the LLM has finished and token usage data is available.
-#
-#   event.token_usage.input_tokens   # => 100
-#   event.token_usage.output_tokens  # => 50
-#   event.token_usage.total_tokens   # => 150
-#
+# Final token usage for the response, emitted when the LLM finishes.
 class Riffer::StreamEvents::TokenUsageDone < Riffer::StreamEvents::Base
   # The token usage data for this response.
   attr_reader :token_usage #: Riffer::Providers::TokenUsage

data/lib/riffer/stream_events/tool_call_delta.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::StreamEvents::ToolCallDelta represents an incremental tool call chunk during streaming.
-#
-# Emitted when the LLM is building a tool call, containing partial argument data.
+# Represents an incremental tool call chunk (partial argument data) during
+# streaming.
 class Riffer::StreamEvents::ToolCallDelta < Riffer::StreamEvents::Base
   # The tool call item identifier.
   attr_reader :item_id #: String

data/lib/riffer/stream_events/tool_call_done.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::StreamEvents::ToolCallDone represents a completed tool call during streaming.
-#
-# Emitted when the LLM has finished building a tool call with complete arguments.
+# Represents a completed tool call during streaming.
 class Riffer::StreamEvents::ToolCallDone < Riffer::StreamEvents::Base
   # The tool call item identifier.
   attr_reader :item_id #: String

data/lib/riffer/stream_events/web_search_done.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents the result of a web search during streaming.
-#
-# Emitted when the LLM has finished a server-side web search.
+# The result of a completed server-side web search during streaming.
 class Riffer::StreamEvents::WebSearchDone < Riffer::StreamEvents::Base
   # The search query used.
   attr_reader :query #: String

data/lib/riffer/stream_events/web_search_status.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a web search status notification during streaming.
-#
-# Emitted when the LLM performs a server-side web search and its status changes.
+# A web search status notification, emitted as a server-side web search
+# progresses.
 class Riffer::StreamEvents::WebSearchStatus < Riffer::StreamEvents::Base
   # The web search status ("in_progress", "searching", "completed", "open_page").
   attr_reader :status #: String

data/lib/riffer/stream_events.rb

@@ -1,15 +1,5 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Namespace for streaming event types in the Riffer framework.
-#
-# When streaming responses, these events are yielded to represent incremental updates:
-# - Riffer::StreamEvents::TextDelta - Incremental text content
-# - Riffer::StreamEvents::TextDone - Complete text content
-# - Riffer::StreamEvents::ToolCallDelta - Incremental tool call arguments
-# - Riffer::StreamEvents::ToolCallDone - Complete tool call
-# - Riffer::StreamEvents::ReasoningDelta - Incremental reasoning content
-# - Riffer::StreamEvents::ReasoningDone - Complete reasoning content
-# - Riffer::StreamEvents::SkillActivation - Skill activated during streaming
 module Riffer::StreamEvents
 end

data/lib/riffer/tool.rb

@@ -3,12 +3,8 @@
 
 require "timeout"
 
-# Riffer::Tool is the base class for all tools in the Riffer framework.
-#
-# Provides a DSL for defining tool description and parameters.
-# Subclasses must implement the +call+ method.
-#
-# See Riffer::Agent.
+# Base class for all tools in the Riffer framework. Subclasses must implement
+# the +call+ method.
 #
 #   class WeatherLookupTool < Riffer::Tool
 #     description "Provides current weather information for a specified city."
@@ -29,16 +25,13 @@ class Riffer::Tool
   kind :tool
 
   # Executes the tool with the given arguments.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  #
   #--
   #: (context: Riffer::Agent::Context?, **untyped) -> Riffer::Tools::Response
   def call(context:, **kwargs)
     raise NotImplementedError, "#{self.class} must implement #call"
   end
 
-  # Creates a text response. Shorthand for Riffer::Tools::Response.text.
+  # Creates a text response.
   #
   #--
   #: (untyped) -> Riffer::Tools::Response
@@ -46,7 +39,7 @@ class Riffer::Tool
     Riffer::Tools::Response.text(result)
   end
 
-  # Creates a JSON response. Shorthand for Riffer::Tools::Response.json.
+  # Creates a JSON response.
   #
   #--
   #: (untyped) -> Riffer::Tools::Response
@@ -54,7 +47,7 @@ class Riffer::Tool
     Riffer::Tools::Response.json(result)
   end
 
-  # Creates an error response. Shorthand for Riffer::Tools::Response.error.
+  # Creates an error response.
   #
   #--
   #: (String, ?type: Symbol) -> Riffer::Tools::Response
@@ -75,7 +68,7 @@ class Riffer::Tool
     validated_args = params_builder ? params_builder.validate(kwargs) : kwargs
 
     result = Timeout.timeout(self.class.timeout) do
-      call(context: context, **validated_args)
+      call(context: context, **validated_args) #: untyped
     end
 
     unless result.is_a?(Riffer::Tools::Response)

data/lib/riffer/tools/response.rb

@@ -3,10 +3,7 @@
 
 require "json"
 
-# Riffer::Tools::Response represents the result of a tool execution.
-#
-# All tools must return a Response object from their +call+ method.
-# Use +Response.success+ for successful results and +Response.error+ for failures.
+# Represents the result of a tool execution; every tool's +call+ must return one.
 #
 #   class MyTool < Riffer::Tool
 #     def call(context:, **kwargs)
@@ -22,8 +19,13 @@ class Riffer::Tools::Response
 
   VALID_FORMATS = %i[text json].freeze #: Array[Symbol]
 
+  # The response content.
   attr_reader :content #: String
+
+  # The error message, or +nil+ on success.
   attr_reader :error_message #: String?
+
+  # The error type, or +nil+ on success.
   attr_reader :error_type #: Symbol?
 
   # Creates a success response.
@@ -65,10 +67,12 @@ class Riffer::Tools::Response
     new(content: message, success: false, error_message: message, error_type: type)
   end
 
+  # Returns true if the tool execution succeeded.
   #--
   #: () -> bool
   def success? = @success
 
+  # Returns true if the tool execution failed.
   #--
   #: () -> bool
   def error? = !@success

data/lib/riffer/tools/runtime/fibers.rb

@@ -8,9 +8,6 @@
 #   end
 #
 class Riffer::Tools::Runtime::Fibers < Riffer::Tools::Runtime
-  # [max_concurrency] maximum number of tool calls to execute simultaneously.
-  #   When +nil+, all tool calls run as fibers without limit.
-  #
   #--
   #: (?max_concurrency: Integer?) -> void
   def initialize(max_concurrency: nil)

data/lib/riffer/tools/runtime/inline.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Executes tool calls sequentially in the current thread.
-#
-# This is the default tool runtime used when no runtime is configured.
-#
+# Executes tool calls sequentially in the current thread — the default runtime.
 class Riffer::Tools::Runtime::Inline < Riffer::Tools::Runtime
   #--
   #: () -> void

data/lib/riffer/tools/runtime/threaded.rb

@@ -10,8 +10,6 @@
 class Riffer::Tools::Runtime::Threaded < Riffer::Tools::Runtime
   DEFAULT_MAX_CONCURRENCY = 5 #: Integer
 
-  # [max_concurrency] maximum number of tool calls to execute simultaneously.
-  #
   #--
   #: (?max_concurrency: Integer) -> void
   def initialize(max_concurrency: DEFAULT_MAX_CONCURRENCY)

data/lib/riffer/tools/runtime.rb

@@ -3,25 +3,12 @@
 
 require "json"
 
-# Riffer::Tools::Runtime handles tool call execution for an agent.
-#
-# Composes with a Riffer::Runner for concurrency control and provides
-# +execute+ as the sole public entry point.
-#
-# Subclass and override +dispatch_tool_call+ to customize how individual
-# tool calls are dispatched (e.g., HTTP, gRPC).
-#
-#   runtime = Riffer::Tools::Runtime::Inline.new
-#   results = runtime.execute(tool_calls, tools: tools, context: context)
-#
+# Handles tool call execution for an agent, composing with a Riffer::Runner for
+# concurrency. Subclass and override +dispatch_tool_call+ to customize dispatch
+# (e.g. HTTP, gRPC).
 class Riffer::Tools::Runtime
   # @rbs @runner: Riffer::Runner
 
-  # [runner] the concurrency runner to use for batch execution.
-  #
-  # Subclasses must provide a runner; instantiating Riffer::Tools::Runtime directly
-  # raises +NotImplementedError+.
-  #
   #--
   #: (runner: Riffer::Runner) -> void
   def initialize(runner:)
@@ -30,15 +17,6 @@ class Riffer::Tools::Runtime
   end
 
   # Executes a batch of tool calls, returning <tt>[tool_call, response]</tt> pairs.
-  #
-  # [tool_calls] the tool calls to execute.
-  # [tools] the resolved tool classes.
-  # [context] the context hash.
-  # [assistant_message] the assistant message that produced these tool
-  #   calls, when known. Forwarded to +around_tool_call+ and
-  #   +dispatch_tool_call+ so subclasses can access it (e.g. for
-  #   instrumentation that needs the accompanying assistant text).
-  #
   #--
   #: (Array[Riffer::Messages::Assistant::ToolCall], tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Array[[Riffer::Messages::Assistant::ToolCall, Riffer::Tools::Response]]
   def execute(tool_calls, tools:, context:, assistant_message: nil)
@@ -50,10 +28,8 @@ class Riffer::Tools::Runtime
     end
   end
 
-  # Hook that wraps each tool call execution. Override in subclasses
-  # to customize. Must +yield+ to continue execution.
-  #
-  # The default implementation simply yields.
+  # Hook wrapping each tool call; override in subclasses to instrument or
+  # customize. Must +yield+ to continue.
   #
   #   class InstrumentedRuntime < Riffer::Tools::Runtime::Inline
   #     private
@@ -74,15 +50,6 @@ class Riffer::Tools::Runtime
 
   private
 
-  # Dispatches a single tool call. Override in subclasses to change
-  # how individual tools are invoked (e.g., HTTP, gRPC).
-  #
-  # [tool_call] the tool call to execute.
-  # [tools] the resolved tool classes.
-  # [context] the context hash.
-  # [assistant_message] the assistant message that produced this tool
-  #   call, when known.
-  #
   #--
   #: (Riffer::Messages::Assistant::ToolCall, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
   def dispatch_tool_call(tool_call, tools:, context:, assistant_message: nil)