riffer 0.41.0 → 0.43.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd309de6be56bd5fbe778bbf277b9125dd63d4ce7b360c3e5e85554a944cb81d
-  data.tar.gz: 965daf888849a0386b2826af572fd95d0a7fb8a4ac6f9f91788acb0254705f8e
+  metadata.gz: bed1103d2399d8532635b4041d4a24b8264f160b58a3110436ed67a14380fd56
+  data.tar.gz: acdaa65506e0c4887d388663be686bc02ccf668c26db281148efcec9f5772d6b
 SHA512:
-  metadata.gz: deedbd28b2c79faceea167422fb69147cb2453d7e06df48c46c2eb1e601068de7b9018026675a973f6de6036373d324d5120fc43269e863dd43ce39b88ee7ea4
-  data.tar.gz: 2007cc98bd5955ae2db4776e72551d546038deea60be3e397a5838e028cd2901465f2fe9c00d944b18e4ce9508599bcd7603ad61e0e75efaa8264793461cf283
+  metadata.gz: 0733aa1731a7206195862e6bfd59936b80cc3219fa913a6afce577a8de9d8f4510ca59316a6bb27c6a778706b6d231ce61cd74ebd9d63f32d2a695453b2bd5ae
+  data.tar.gz: da09bd24389e52f79c7cbe3dd977c5ada7bc9f0a923f2d09d2331245b4ca1fd079f9f688da0ab8b36eac6b1a260bd627831dc0c344ae93422f5a006c929a11e3

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.43.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.43.0](https://github.com/janeapp/riffer/compare/riffer/v0.42.0...riffer/v0.43.0) (2026-08-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* call_with_validation no longer raises Riffer::ValidationError / Riffer::TimeoutError / Riffer::Error — it always returns a Riffer::Tools::Response. Riffer::TimeoutError has been removed; delete any `rescue Riffer::TimeoutError` and check `response.error_type` instead. Custom runtimes overriding dispatch_tool_call no longer inherit rescues from the base class.
+
+### Features
+
+* tools are the error boundary — call_with_validation never raises ([#412](https://github.com/janeapp/riffer/issues/412)) ([b6db9b6](https://github.com/janeapp/riffer/commit/b6db9b6ab2885d170cbba52c7a571c63b83d892e))
+
+## [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/AGENT_LOOP.md

@@ -15,13 +15,15 @@ When an agent receives a response with tool calls:
 
 ## Error Handling
 
-Tool execution errors are captured and sent back to the LLM:
+Tool execution errors never abort the loop — each is captured and sent back to the LLM as a tool result:
 
 - `unknown_tool` - Tool not found in registered tools
-- `validation_error` - Arguments failed validation
-- `execution_error` - Tool raised an exception
+- `validation_error` - Arguments failed validation or were malformed JSON
+- `timeout_error` - Tool exceeded its configured timeout
+- `execution_error` - Tool returned an error or raised `Riffer::ToolExecutionError`
+- `unhandled_error` - Tool raised an unanticipated exception
 
-The LLM can use this information to retry or respond appropriately.
+The LLM can use this information to retry or respond appropriately. See [Error Handling](TOOL_ADVANCED.md#error-handling) for details.
 
 ## Ways the Agent Loop Can Stop
 

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`:
@@ -252,7 +269,7 @@ error("Service unavailable", type: :service_error)
 error("Rate limit exceeded", type: :rate_limit)
 ```
 
-If no type is specified, it defaults to `:execution_error`.
+If no type is specified, it defaults to `:execution_error`. Riffer reserves `:unhandled_error` for unrescued exceptions — don't set it yourself.
 
 ### Using Riffer::Tools::Response Directly
 
@@ -280,4 +297,7 @@ error_response.success?       # => false
 error_response.error?         # => true
 error_response.error_message  # => "failed"
 error_response.error_type     # => :not_found
+error_response.exception      # => nil
 ```
+
+`exception` holds the rescued exception on the `:unhandled_error` responses Riffer builds. It never appears in serialized output, so it is not visible to the LLM.

data/docs/TOOL_ADVANCED.md

@@ -16,7 +16,7 @@ class SlowExternalApiTool < Riffer::Tool
 end
 ```
 
-When a tool times out, the error is reported to the LLM with error type `:timeout_error`, allowing it to respond appropriately (e.g., suggest retrying or using a different approach).
+When a tool times out, the LLM receives an error response with type `:timeout_error` and can respond appropriately (e.g., suggest retrying or using a different approach). The timeout raises `Riffer::TimeoutError` inside `call`, so a tool can rescue it to release resources before it propagates.
 
 ## Validation
 
@@ -26,7 +26,7 @@ Arguments are automatically validated before `call` is invoked:
 - Types must match the schema
 - Enum values must be in the allowed list
 
-Validation errors are captured and sent back to the LLM as tool results with error type `:validation_error`.
+Validation errors are captured and sent back to the LLM as tool results with error type `:validation_error`, as is malformed or non-object JSON in the provider's tool-call arguments.
 
 ## JSON Schema Generation
 
@@ -95,7 +95,20 @@ rescue => e
 end
 ```
 
-Unhandled `RuntimeError` exceptions are caught by Riffer and converted to error responses with type `:execution_error`. For expected execution errors, raise `Riffer::ToolExecutionError` — these are also caught and returned to the LLM. Programming bugs (`NoMethodError`, `NameError`, `TypeError`, etc.) propagate to the caller. It's recommended to handle expected errors explicitly for better error messages.
+A tool never raises into the agent loop — every `StandardError` raised during a tool call becomes an error response:
+
+| Failure                      | Error type          | Response content                                     |
+| ---------------------------- | ------------------- | ---------------------------------------------------- |
+| Invalid arguments            | `:validation_error` | the validation message                               |
+| Timeout                      | `:timeout_error`    | `Tool execution timed out after N seconds`           |
+| `Riffer::ToolExecutionError` | `:execution_error`  | the exception message                                |
+| Any other `StandardError`    | `:unhandled_error`  | `Error executing tool: <ExceptionClass>: <message>` |
+
+An `:unhandled_error` response also carries the rescued exception on `response.exception` — never serialized, so it stays out of the message history — and its `execute_tool` span records the exception with an `ERROR` status (see [Tracing](TRACING.md)).
+
+`NotImplementedError` is not rescued: an unimplemented `#call` raises out of the run.
+
+For expected failures, return `error(...)` or raise `Riffer::ToolExecutionError` — both give the LLM a clean message rather than an `:unhandled_error`.
 
 The LLM receives the error message and can decide how to respond (retry, apologize, ask for different input, etc.).
 
@@ -222,14 +235,14 @@ class HttpToolRuntime < Riffer::Tools::Runtime
       arguments: tool_call.arguments
     })
     Riffer::Tools::Response.text(response.body)
-  rescue Riffer::ToolExecutionError => e
-    Riffer::Tools::Response.error(e.message, type: :execution_error)
-  rescue RuntimeError => e
-    Riffer::Tools::Response.error("Error executing tool: #{e.message}", type: :execution_error)
+  rescue HttpClient::Error => e
+    Riffer::Tools::Response.error("Tool service unavailable: #{e.message}", type: :execution_error)
   end
 end
 ```
 
+Anything that escapes `dispatch_tool_call` propagates out of the run — rescue whatever your transport can raise and return an error response. The base class handles only an unknown tool name and malformed argument JSON.
+
 ### Around-Call Hook
 
 Each tool call is wrapped by the `around_tool_call` method, which yields by default. Override it in a subclass to add instrumentation, logging, or other cross-cutting concerns:

data/docs/TRACING.md

@@ -168,12 +168,13 @@ Usage on this span is the run total, aggregated across every step. See [Token us
 | `gen_ai.tool.call.arguments` | string | When `capture_messages` is on (see [capture](#message-content-capture)) |
 | `gen_ai.tool.call.result`    | string | When `capture_messages` is on                                           |
 
-A tool failure comes in two shapes, distinguished by span status:
+A tool failure comes in three shapes, distinguished by span status:
 
-- **Handled error** — the tool returned an error response. `error.type` carries the category and the **span status stays unset** (the run continues). The framework's categories are `unknown_tool`, `validation_error`, `timeout_error`, and `execution_error`; a custom tool may set its own via `Riffer::Tools::Response.error(type:)`.
-- **Unhandled exception** — the dispatch raised. `error.type` is the exception class name and the **span status is `ERROR`**, with the exception recorded.
+- **Handled error** — the tool call produced a deliberate error response, from the tool itself or from the runtime (an unknown tool, malformed arguments). `error.type` carries the category and the **span status stays unset** (the run continues). The framework's categories are `unknown_tool`, `validation_error`, `timeout_error`, and `execution_error`; a custom tool may set its own via `Riffer::Tools::Response.error(type:)`.
+- **Unhandled error** — the tool raised an unanticipated `StandardError`. `error.type` is `unhandled_error`, the **span status is `ERROR`**, and the exception is recorded on the span. The run continues — the LLM receives the error response.
+- **Host code raising** around the tool call (an `around_tool_call` hook, a tracing callback) propagates out of the run. `error.type` is the exception class name and the span status is `ERROR`.
 
-This status convention is the same on `chat` and `invoke_agent`: an unhandled exception sets `error.type` to the class name and marks the span `ERROR`; everything else leaves the status unset.
+This status convention is the same on `chat` and `invoke_agent`: an unhandled exception marks the span `ERROR` with the exception recorded; a handled outcome leaves the status unset.
 
 ## `execute_guardrail {name}` — the guardrail span
 

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/messages/tool.rb

@@ -12,7 +12,8 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
   # The error message if the tool execution failed.
   attr_reader :error #: String?
 
-  # The type of error (:unknown_tool, :validation_error, :execution_error, :timeout_error).
+  # The type of error (:unknown_tool, :validation_error, :execution_error,
+  # :timeout_error, :unhandled_error).
   attr_reader :error_type #: Symbol?
 
   #--

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.