riffer 0.41.0 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd309de6be56bd5fbe778bbf277b9125dd63d4ce7b360c3e5e85554a944cb81d
-  data.tar.gz: 965daf888849a0386b2826af572fd95d0a7fb8a4ac6f9f91788acb0254705f8e
+  metadata.gz: eabed1a1a6844787d92f31be0a72e210117005c19b4dd5e021a905121f83e8e1
+  data.tar.gz: 4cc6b6bde7e4b474d7ca6fb2672a3e115d4584b096f1de5d967a2b1a751f49ba
 SHA512:
-  metadata.gz: deedbd28b2c79faceea167422fb69147cb2453d7e06df48c46c2eb1e601068de7b9018026675a973f6de6036373d324d5120fc43269e863dd43ce39b88ee7ea4
-  data.tar.gz: 2007cc98bd5955ae2db4776e72551d546038deea60be3e397a5838e028cd2901465f2fe9c00d944b18e4ce9508599bcd7603ad61e0e75efaa8264793461cf283
+  metadata.gz: 220febe23864053fa767e3eecc6850dc0c25ebdcb363a86d5daa58cd317c5500d08f2b50f499f133a77d7b4cf5182485c6faf0ddf36550099b22b7dd203af0c6
+  data.tar.gz: d231a4b0dc8c0468f4cba1abf9e3ace390852efc4b6adf5c23229c6729d4ad71fb0afdd5ae5b50540a188b79ec519ef58f95972357fb9854398570d0de058781

data/{AGENTS.md → .claude/CLAUDE.md}

@@ -10,14 +10,6 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)
 - **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/CONFIGURATION.md`, `docs/MESSAGES.md`). Adding a NEW page under `docs/` also requires a `docs-site/manifest.yml` entry — the site build fails without one. RDoc ≠ user docs.
 
-## Topic Guides
-
-- [Architecture](.agents/architecture.md) - Core components and project structure
-- [Testing](.agents/testing.md) - Minitest spec DSL and VCR cassettes
-- [Code Style](.agents/code-style.md) - RuboCop, comment, and RDoc conventions
-- [Providers](.agents/providers.md) - Adding new LLM provider adapters
-- [RBS Inline](.agents/rbs-inline.md) - Type annotations with rbs-inline
-
 ## Commands
 
 All wrappers `exec bundle exec …` under the hood.

data/.claude/rules/comments.md

@@ -0,0 +1,13 @@
+---
+paths: ["**/*.rb", "**/*.rake", "**/Gemfile"]
+---
+
+# Comments
+
+A comment exists to explain a **why** when the code itself cannot — never a **how**, and never a restatement of what the code already says. This bar governs all prose, from inline comments to docstrings.
+
+- **Internal and private code** — everything in an application, plus a library's non-exported internals — is self-documenting via clear names and strong types. A comment survives only when it explains something a competent reader cannot recover from the code alone: a non-local constraint, an external-system quirk, a deliberate non-obvious tradeoff. A description of _what_ the code does, or a why that's evident from reading it, gets cut.
+- **A published library's public surface** gets one verb-first sentence per exported symbol ("Serializes the definition to JSON."). An optional second sentence is reserved strictly for a why — a non-obvious constraint or rationale — never a second sentence of how. Needing more than one sentence to say _what_ it does is a smell the symbol does too much.
+- **Types are not prose's job.** Parameters, return values, and field types live in the type system (TypeScript types, rbs-inline `#:` annotations) — never restated in comments that duplicate them.
+- **Markers.** `TODO` / `FIXME` / `HACK` are tracked work and stay; `NOTE` / `REVIEW` meet the same why-bar as any other comment.
+- **No history.** A comment describes the present, never how the code got there — no "was X, now Y", no story of the bug that revealed a constraint. State a still-true constraint in the present tense ("the API returns null for empty results — guard").

data/{.agents → .claude/rules}/rbs-inline.md

@@ -1,128 +1,52 @@
+---
+paths: ["lib/**/*.rb", "sig/**/*"]
+---
+
 # RBS Inline
 
 Type annotations are added directly in Ruby source files using [rbs-inline](https://github.com/soutaro/rbs-inline).
 
-## Magic Comment
-
-rbs-inline only processes a file when `rbs_inline: enabled` is present on line 2. It ships as part of the required header on every `lib/**/*.rb` file — see [Required Header](code-style.md#required-header).
+## Required Header
 
-## Annotation Syntax
+Every `lib/**/*.rb` file starts with the two-line header `# frozen_string_literal: true` + `# rbs_inline: enabled` — rbs-inline silently skips any file missing the magic comment on line 2.
 
-The **`#:`** prefix is used — standalone lines above methods (type signatures) or inline on the same line (attributes, constants).
+## Annotation Conventions
 
-### Method Parameters and Return Types
+The **`#:`** prefix is used — standalone lines above methods (RBS method signatures) or inline on the same line (attributes, constants).
 
-Use a single `#:` line above the method with the RBS method signature:
+`# @rbs` is used **only** for ivar declarations; everything else uses `#:`. The `#:` shorthand on an assignment is a Steep _assertion_ — it types the expression but does **not declare the ivar**. To declare an ivar's type, use a `# @rbs` comment inside the class body:
 
 ```ruby
-#: (String, Integer) -> bool
-def valid?(name, age)
-```
+class Riffer::Agent::Session
+  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]   # instance ivar
+end
 
-#### Parameter Mapping
+module Riffer
+  # @rbs self.@config: Riffer::Config?                          # class/module-level ivar
+end
+```
 
-| Ruby param                   | RBS signature            |
-| ---------------------------- | ------------------------ |
-| `def foo(x)`                 | `(Type)`                 |
-| `def foo(x = nil)`           | `(?Type?)`               |
-| `def foo(x = val)`           | `(?Type)`                |
-| `def foo(x:)`                | `(x: Type)`              |
-| `def foo(x: nil)`            | `(?x: Type?)`            |
-| `def foo(x: val)`            | `(?x: Type)`             |
-| `def foo(*args)`             | `(*untyped)`             |
-| `def foo(**kwargs)`          | `(**untyped)`            |
-| `def foo(&block)` (required) | `() { (Type) -> void }`  |
-| `def foo(&block)` (optional) | `() ?{ (Type) -> void }` |
-| `def foo(...)`               | `(*untyped, **untyped)`  |
+## RDoc Conventions
 
-#### Examples
+**The `#--` stop directive.** Place `#--` on the line immediately before a **standalone** `#:` type annotation. Without it, RDoc treats `#:` as a label-list marker and corrupts the preceding description into a `<pre>` block. Inline `#:` on the same line as code (attributes, constants) does not need it.
 
 ```ruby
-# No parameters
-#: () -> String
-def name
-
-# Positional parameters
-#: (String, Integer) -> bool
-def valid?(name, age)
-
-# Optional positional parameter
-#: (?String?) -> String
-def self.identifier(value = nil)
-
-# Required keyword parameters
-#: (input: String, output: String) -> Riffer::Evals::Result
-def evaluate(input:, output:)
-
-# Mixed keyword parameters (required + optional)
-#: (input: String, output: String, ?context: Hash[Symbol, untyped]?) -> Riffer::Evals::Result
-def evaluate(input:, output:, context: nil)
-
-# Positional + keyword parameters
-#: (String, ?context: Hash[Symbol, untyped]?) -> String
-def generate(prompt, context: nil)
-
-# Splat/double-splat
-#: (**untyped) -> void
-def initialize(**options)
-
-# Forward arguments
-#: (*untyped, **untyped) -> String
-def self.generate(...)
-
-# Block parameter (required)
-#: () { (Riffer::Messages::Base) -> void } -> self
-def on_message(&block)
+# Serializes the agent definition to a transferable JSON payload.
+#--
+#: (Riffer::Agent) -> String
+def serialize(agent)
 
-# Block parameter (optional)
-#: () ?{ (Riffer::Config) -> void } -> void
-def configure(&block)
-```
-
-### Attributes
-
-```ruby
+# The agent's display name.
 attr_reader :name #: String
-attr_reader :items #: Array[String]
 ```
 
-### Constants
-
-```ruby
-VERSION = "1.0.0" #: String
-DEFAULTS = {}.freeze #: Hash[Symbol, untyped]
-```
-
-### Instance variables
-
-The `#:` shorthand on an assignment is a Steep _assertion_ — it types the expression but does
-**not declare the ivar**. To declare an ivar's type, use a `# @rbs` comment inside the class
-body. `# @rbs` is used **only** for ivar declarations in this codebase; everything else uses
-`#:`.
+**Raises.** Document a raise **only when it's part of the caller's contract** — something a caller should reasonably anticipate and handle. Skip programmer-error guards and "should never happen" assertions. When the raise condition merely restates the declared `#:` type, phrase it by intent ("Raises Riffer::ArgumentError on an invalid value") rather than re-listing the type union.
 
-```ruby
-class Riffer::Agent::Session
-  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]   # instance ivar
-end
-
-module Riffer
-  # @rbs self.@config: Riffer::Config?                          # class/module-level ivar
-end
-```
+**Examples.** Include an example only when a **consumer is likely to use the thing themselves** — a public entry point they construct, subclass, or call. Keep them sparing and write them as indented code blocks (2 extra spaces of indent). Usage walkthroughs belong in `docs/`.
 
-## Common Type Patterns
+**Inline code formatting.** Use `+word+` for single-word inline code; for multi-word expressions (spaces, colons, brackets) use `<tt>multi word expression</tt>`.
 
-| Pattern                   | Meaning                     |
-| ------------------------- | --------------------------- |
-| `String?`                 | Optional (String or nil)    |
-| `(String \| Integer)`     | Union type                  |
-| `Array[String]`           | Typed array                 |
-| `Hash[Symbol, untyped]`   | Typed hash                  |
-| `^(String) -> void`       | Block/proc type             |
-| `singleton(Riffer::Tool)` | Class object (not instance) |
-| `bool`                    | Boolean (true or false)     |
-| `untyped`                 | Any type                    |
-| `void`                    | No meaningful return        |
+**Internal APIs.** Mark with `# :nodoc:` to exclude from generated documentation.
 
 ## Optional-dependency types (consumer-safe signatures)
 
@@ -155,7 +79,7 @@ end
 ### Where stubs and stdlib deps live
 
 - `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client).
-- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Instance variables"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (the narrowed `client`).
+- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Annotation Conventions"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (the narrowed `client`).
 - `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
 
 ## Workflow

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.41.0"
+  ".": "0.42.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.42.0](https://github.com/janeapp/riffer/compare/riffer/v0.41.0...riffer/v0.42.0) (2026-08-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* duplicate identifiers among named direct subclasses of Riffer::Tool or Riffer::Agent now raise Riffer::DuplicateIdentifierError on lookup. Agent.find/.all (and the new Tool.find/.all) cover named direct subclasses only - anonymous classes are excluded even with an explicit identifier. Riffer::Helpers::ClassNameConverter is removed; use Riffer::Helpers::Identifier.derive (the separator: keyword is dropped).
+
+### Features
+
+* one identifier registry pattern for tools and agents ([#406](https://github.com/janeapp/riffer/issues/406)) ([72fa7d6](https://github.com/janeapp/riffer/commit/72fa7d6377f903e4a88f9f5ec0e27e51b46dc293))
+
 ## [0.41.0](https://github.com/janeapp/riffer/compare/riffer/v0.40.0...riffer/v0.41.0) (2026-08-14)
 
 

data/docs/AGENTS.md

@@ -306,6 +306,27 @@ agent.generate('Hello')
 
 When `config:` is supplied, the class-level configuration is ignored for that instance.
 
+## Looking Up Agents
+
+Look up an agent by identifier with `Riffer::Agent.find`, or list every agent with `Riffer::Agent.all`:
+
+```ruby
+class SupportAgent < Riffer::Agent
+  model 'openai/gpt-5-mini'
+end
+
+Riffer::Agent.find('support_agent')   # => SupportAgent
+Riffer::Agent.find(:support_agent)    # symbols work too
+Riffer::Agent.find('missing')         # => nil
+Riffer::Agent.all                     # => [SupportAgent, ...]
+```
+
+Only **named direct subclasses** are found:
+
+- Grandchildren are not visible to a grandparent's `find` or `all`. If your app defines an intermediate base class (`class ApplicationAgent < Riffer::Agent`), call `find`/`all` on the intermediate class to look up its subclasses.
+- Anonymous classes (`Class.new(Riffer::Agent)`) are never findable, even when they set an explicit `identifier`.
+- Two subclasses sharing an identifier raise `Riffer::DuplicateIdentifierError` at the first lookup.
+
 ## Per-Call Tags
 
 `#generate` and `#stream` accept an optional `tags:` hash — a flat map of attribution labels scoped to that single call (for cost/usage attribution, filtering audit logs, slicing telemetry). It is **per-call only**.
@@ -348,10 +369,10 @@ Riffer does not validate tag count, key/value length, or charset — it forwards
 
 ## Expand Your Agent
 
-| Goal                          | Feature           | Guide                                                                |
-| ----------------------------- | ----------------- | -------------------------------------------------------------------- |
+| Goal                          | Feature           | Guide                                                             |
+| ----------------------------- | ----------------- | ----------------------------------------------------------------- |
 | Call APIs or run functions    | Tools             | [Tools](TOOLS.md)                                                 |
-| Return structured JSON        | Structured Output | [structured_output](#structured_output)                              |
+| Return structured JSON        | Structured Output | [structured_output](#structured_output)                           |
 | Validate or filter content    | Guardrails        | [Guardrails](GUARDRAILS.md)                                       |
 | Measure output quality        | Evals             | [Evals](EVALS.md)                                                 |
 | Add packaged capabilities     | Skills            | [Skills](SKILLS.md)                                               |

data/docs/AGENT_LIFECYCLE.md

@@ -347,7 +347,7 @@ See [Messages — Structured Output on Messages](MESSAGES.md#structured-output-o
 
 ### find
 
-Find an agent class by identifier:
+Find an agent class by identifier (named direct subclasses only — see [Agents — Looking Up Agents](AGENTS.md#looking-up-agents)):
 
 ```ruby
 agent_class = Riffer::Agent.find('my_agent')
@@ -356,7 +356,7 @@ agent = agent_class.new
 
 ### all
 
-List all agent subclasses:
+List all registered agent subclasses (named direct subclasses only):
 
 ```ruby
 Riffer::Agent.all.each do |agent_class|

data/docs/TOOLS.md

@@ -108,7 +108,7 @@ Options:
 | `String`                   | `string`         |
 | `Integer`                  | `integer`        |
 | `Float`                    | `number`         |
-| `Riffer::Params::Boolean`          | `boolean`        |
+| `Riffer::Params::Boolean`  | `boolean`        |
 | `TrueClass` / `FalseClass` | `boolean`        |
 | `Array`                    | `array`          |
 | `Hash`                     | `object`         |
@@ -143,6 +143,23 @@ class CreateOrderTool < Riffer::Tool
 end
 ```
 
+## Looking Up Tools
+
+Look up a tool by identifier with `Riffer::Tool.find`, or list every tool with `Riffer::Tool.all`:
+
+```ruby
+Riffer::Tool.find('kb_search')   # => SearchTool
+Riffer::Tool.find(:kb_search)    # symbols work too
+Riffer::Tool.find('missing')     # => nil
+Riffer::Tool.all                 # => [SearchTool, ...]
+```
+
+Only **named direct subclasses** are found:
+
+- Grandchildren are not visible to a grandparent's `find` or `all`. If your app defines an intermediate base class (`class ApplicationTool < Riffer::Tool`), call `find`/`all` on the intermediate class to look up its subclasses.
+- Anonymous classes (`Class.new(Riffer::Tool)`) are never findable, even when they set an explicit `identifier`.
+- Two subclasses sharing an identifier raise `Riffer::DuplicateIdentifierError` at the first lookup.
+
 ## The call Method
 
 Every tool must implement the `call` method and return a `Riffer::Tools::Response`:

data/lib/riffer/agent/run.rb

@@ -465,10 +465,8 @@ module Riffer::Agent::Run
     tripwire = response.tripwire
     return unless tripwire
 
-    class_name = tripwire.guardrail.name
-    if class_name
-      span.set_attribute("riffer.tripwire.guardrail", Riffer::Helpers::ClassNameConverter.convert(class_name))
-    end
+    identifier = Riffer::Helpers::Identifier.for(tripwire.guardrail)
+    span.set_attribute("riffer.tripwire.guardrail", identifier) unless identifier.empty?
     span.set_attribute("riffer.tripwire.reason", tripwire.reason)
     span.set_attribute("riffer.tripwire.phase", tripwire.phase.to_s)
   end

data/lib/riffer/agent.rb

@@ -15,6 +15,8 @@ require "json"
 #   agent.generate('Hello!')
 #
 class Riffer::Agent
+  extend Riffer::Registrable
+
   # @rbs self.@config: Riffer::Agent::Config?
 
   INTERRUPT_MAX_STEPS = :max_steps #: Symbol
@@ -31,7 +33,7 @@ class Riffer::Agent
   #--
   #: (?String?) -> String
   def self.identifier(value = nil)
-    value.nil? ? (config.identifier || Riffer::Helpers::ClassNameConverter.convert(name)) : (config.identifier = value)
+    value.nil? ? (config.identifier || Riffer::Helpers::Identifier.for(self)) : (config.identifier = value)
   end
 
   # Gets or sets the model string (e.g., "openai/gpt-4o").
@@ -144,22 +146,6 @@ class Riffer::Agent
     config.skills_config
   end
 
-  # Finds an agent class by identifier.
-  #
-  #--
-  #: (String) -> singleton(Riffer::Agent)?
-  def self.find(identifier)
-    all.find { |agent_class| agent_class.identifier == identifier.to_s }
-  end
-
-  # Returns all agent subclasses.
-  #
-  #--
-  #: () -> Array[singleton(Riffer::Agent)]
-  def self.all
-    subclasses #: Array[singleton(Riffer::Agent)]
-  end
-
   # Generates a response using a new agent instance.
   #--
   #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response

data/lib/riffer/guardrail.rb

@@ -36,7 +36,7 @@ class Riffer::Guardrail
   #--
   #: () -> String
   def name
-    Riffer::Helpers::ClassNameConverter.convert(self.class.name)
+    Riffer::Helpers::Identifier.for(self.class)
   end
 
   protected

data/lib/riffer/helpers/identifier.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Helper module for deriving snake_case identifiers from class names.
+module Riffer::Helpers::Identifier
+  extend self
+
+  # Derives a snake_case identifier from a class name string.
+  #
+  #--
+  #: (String?) -> String
+  def derive(class_name)
+    class_name.
+      to_s.
+      gsub("::", "/").
+      gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').
+      gsub(/([a-z\d])([A-Z])/, '\1_\2').
+      downcase
+  end
+
+  # Derives and memoizes the identifier for a class or module. Anonymous
+  # classes return "" without caching, so a class named later still derives its
+  # real identifier — a guard that must travel with the cache, so callers never
+  # memoize their own.
+  #
+  #--
+  #: (Module) -> String
+  def for(klass)
+    cached = klass.instance_variable_get(:@derived_identifier) #: String?
+    return cached if cached
+
+    # Tool classes shadow Module#name with the identifier DSL, so the real
+    # class-path name must come from Module's own implementation.
+    real_name = Module.instance_method(:name).bind_call(klass) #: String?
+    return "" if real_name.nil?
+
+    derived = derive(real_name)
+    klass.instance_variable_set(:@derived_identifier, derived)
+    derived
+  end
+end

data/lib/riffer/providers/anthropic.rb

@@ -292,6 +292,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_input_json_event(event, state:, yielder:)
+    # server_tool_use (web_search) input streams through the raw-event path
+    # (handle_raw_content_block_delta) and must not surface as tool-call deltas.
+    return if state[:web_search_json]
+
     state[:tool_call] = { id: nil, name: nil, arguments: +"" } if state[:tool_call].nil?
     state[:tool_call][:arguments] << event.partial_json
     yielder << Riffer::StreamEvents::ToolCallDelta.new(

data/lib/riffer/providers/base.rb

@@ -11,6 +11,7 @@ class Riffer::Providers::Base
   # @rbs @current_tools: Array[singleton(Riffer::Tool)]
   # @rbs @current_model: String?
   # @rbs @client: untyped
+  # @rbs self.@semconv_provider_name: String?
 
   WIRE_SEPARATOR = "__" #: String
 
@@ -30,9 +31,11 @@ class Riffer::Providers::Base
   #: () -> String
   def self.semconv_provider_name
     class_name = name
+    # Anonymous classes stay uncached: a class assigned to a constant
+    # later must pick up its real name, not a frozen "unknown".
     return "unknown" unless class_name
 
-    Riffer::Helpers::ClassNameConverter.convert(class_name.split("::").last.to_s)
+    @semconv_provider_name ||= Riffer::Helpers::Identifier.derive(class_name.split("::").last)
   end
 
   # Generates text using the provider.

data/lib/riffer/registrable.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Registry of a class's named direct subclasses, keyed by identifier. Extend it
+# onto a base class to look up subclasses in constant time via +find+ and +all+.
+#
+#   class Riffer::Tool
+#     extend Riffer::Registrable
+#   end
+#
+#   Riffer::Tool.find("weather_tool") # => WeatherTool
+#
+# @rbs module-self Class
+module Riffer::Registrable
+  # @rbs @identifier_registry: Hash[String, Class]?
+
+  # Finds a registered subclass by identifier, or +nil+ when none matches.
+  # Only *named direct* subclasses are registered: grandchildren are not
+  # visible to a grandparent's +find+ (call +find+ on their direct parent
+  # instead), anonymous classes are never registered, and duplicate identifiers
+  # raise Riffer::DuplicateIdentifierError at first lookup.
+  #
+  #--
+  #: (String | Symbol) -> Class?
+  def find(identifier)
+    identifier_registry[identifier.to_s]
+  end
+
+  # Returns all registered subclasses. Only *named direct* subclasses are
+  # registered: grandchildren are not included (call +all+ on their direct
+  # parent instead), anonymous classes are never registered, and duplicate
+  # identifiers raise Riffer::DuplicateIdentifierError at first lookup.
+  #
+  #--
+  #: () -> Array[Class]
+  def all
+    identifier_registry.values
+  end
+
+  private
+
+  # Ruby invokes +inherited+ with +self+ bound to the direct superclass — the
+  # only registry the new subclass joins — so busting self's memo is exactly
+  # sufficient.
+  #--
+  #: (Class) -> void
+  def inherited(subclass)
+    super
+    @identifier_registry = nil
+  end
+
+  #--
+  #: () -> Hash[String, Class]
+  def identifier_registry
+    @identifier_registry ||= build_identifier_registry
+  end
+
+  #--
+  #: () -> Hash[String, Class]
+  def build_identifier_registry
+    registry = {} #: Hash[String, Class]
+    subclasses.each_with_object(registry) do |subclass, acc|
+      # Anonymous classes are skipped even with an explicit identifier — the
+      # MCP factory and serializer shells synthesize short-lived anonymous
+      # classes whose registration would flake with GC timing.
+      next if Riffer::Helpers::Identifier.for(subclass).empty?
+
+      candidate = subclass #: untyped
+      key = candidate.identifier.to_s
+      next if key.strip.empty?
+
+      existing = acc[key]
+      if existing
+        raise Riffer::DuplicateIdentifierError,
+              "Duplicate identifier #{key.inspect} for #{existing} and #{subclass}"
+      end
+
+      acc[key] = subclass
+    end.freeze
+  end
+end

data/lib/riffer/tool.rb

@@ -21,6 +21,7 @@ require "timeout"
 #
 class Riffer::Tool
   extend Riffer::Tools::Toolable
+  extend Riffer::Registrable
 
   kind :tool
 

data/lib/riffer/tools/toolable.rb

@@ -15,6 +15,7 @@
 #     end
 #   end
 #
+# @rbs module-self Module
 module Riffer::Tools::Toolable
   # @rbs self.@extenders: Array[Module]?
   # @rbs @description: String?
@@ -57,9 +58,7 @@ module Riffer::Tools::Toolable
   #--
   #: (?String?) -> String
   def identifier(value = nil)
-    if value.nil?
-      return @identifier || Riffer::Helpers::ClassNameConverter.convert(Module.instance_method(:name).bind_call(self))
-    end
+    return @identifier || Riffer::Helpers::Identifier.for(self) if value.nil?
 
     @identifier = value.to_s
   end

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.41.0" #: String
+  VERSION = "0.42.0" #: String
 end

data/lib/riffer.rb

@@ -32,6 +32,9 @@ module Riffer
   # Raised when a tool encounters an expected execution error.
   class ToolExecutionError < Error; end
 
+  # Raised when two registered subclasses share the same identifier.
+  class DuplicateIdentifierError < Error; end
+
   # Returns the Riffer configuration.
   #
   #--

data/sig/generated/riffer/agent.rbs

@@ -11,6 +11,8 @@
 #   agent = MyAgent.new
 #   agent.generate('Hello!')
 class Riffer::Agent
+  extend Riffer::Registrable
+
   self.@config: Riffer::Agent::Config?
 
   INTERRUPT_MAX_STEPS: Symbol
@@ -104,18 +106,6 @@ class Riffer::Agent
   # : () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
   def self.skills: () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
 
-  # Finds an agent class by identifier.
-  #
-  # --
-  # : (String) -> singleton(Riffer::Agent)?
-  def self.find: (String) -> singleton(Riffer::Agent)?
-
-  # Returns all agent subclasses.
-  #
-  # --
-  # : () -> Array[singleton(Riffer::Agent)]
-  def self.all: () -> Array[singleton(Riffer::Agent)]
-
   # Generates a response using a new agent instance.
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response

data/sig/generated/riffer/helpers/identifier.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/helpers/identifier.rb with RBS::Inline
+
+# Helper module for deriving snake_case identifiers from class names.
+module Riffer::Helpers::Identifier
+  # Derives a snake_case identifier from a class name string.
+  #
+  # --
+  # : (String?) -> String
+  def derive: (String?) -> String
+
+  # Derives and memoizes the identifier for a class or module. Anonymous
+  # classes return "" without caching, so a class named later still derives its
+  # real identifier — a guard that must travel with the cache, so callers never
+  # memoize their own.
+  #
+  # --
+  # : (Module) -> String
+  def for: (Module) -> String
+end

data/sig/generated/riffer/providers/base.rbs

@@ -5,6 +5,8 @@
 # +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
 # class orchestrates them.
 class Riffer::Providers::Base
+  self.@semconv_provider_name: String?
+
   @client: untyped
 
   @current_model: String?