mcp_authorization 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '058c192ec678d3ceb11d6ae5fed31c1025156a83d40cf12f7458054f50935682'
-  data.tar.gz: 00aee0863c22ead686543f40e8658a3a019711db84c8554c28bcac287bc51253
+  metadata.gz: b01924de48adcd82456518091bcfb6309908158c118fe0865e600417a70be766
+  data.tar.gz: 59ec07c72ae70fd00a77ff4e935b0c9feb03b5344e080b3d83aecfecf799390c
 SHA512:
-  metadata.gz: aeeb0fa5ab4074654132516b58e0b649aa3eaf3012b3703e98cb9d519c440f39f5bc080bde6947f802a8169073dc03dc1ee2cdf6ffc91b77f520182c7741a143
-  data.tar.gz: 89d8566f176bb0c6cb53cc84ca933adb01e858df69caa320d9d480759b7479efd814f6392c25fe61ecfef891c6246b7fbc0c6a349ba9c6892a01f1370c9f6255
+  metadata.gz: b603364bfb0c0aa3174e714f321b99c11394c938ccffd930aed01c950af91e60ab224a91565feafa3d1ee600a3327ec2c4c6d5d3420f69baf6f2e8b0ace25f02
+  data.tar.gz: a090369d9fe2da4276327b72ac3cf59f9e1626148c980093b42d6d3f85f0486bf496d3a9b6b5a906b1cec5d02e1d53b6b5e920c26c3d604c504655b522305cb5

data/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to this gem are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.9.0]
+
+Top-level params outside the caller's input schema are rejected instead of
+silently dropped. Behavior change on by default — opt out with
+`config.reject_unknown_input_keys = false`.
+
+### Changed
+- **`RbsSchemaCompiler.filter_input` raises `McpAuthorization::UnknownInputKeysError`** when the params carry a top-level key that is not in the caller's compiled input schema. Previously every such key was dropped by the closed-by-default projection, so a `tools/call` with an invented filter (`list_applicants(stage_id:, data: { booked_meeting: "true" }, limit: 100)`) returned `success: true` with the *unfiltered* page — and the calling agent moved every applicant on it, reporting the filter as applied. The same projection let a non-admin's `force: true` through as a silent no-op the agent then reported as done. The caller's schema is now the contract: a key the tool never declared and a key gated behind a predicate this caller fails are both outside it and are both rejected. The handler never runs, so a gated field is still never applied for a caller who lacks it. The error's `unknown_keys` / `accepted_keys` and its message name the offending keys and the params in this caller's schema — nothing `tools/list` did not already show that caller. Keys nested inside a declared object param are still projected silently; this release covers the top level only.
+- **The message is written for the model that reads it.** It states that nothing was executed, lists the accepted params, and tells the caller not to re-run the call without the rejected parameter (the result would be unfiltered) and not to approximate it with another one. A message that said "retry with accepted parameters" would have reproduced the incident.
+- **Materialized tools return the rejection in-band.** `Tool.materialize_for`'s `call` rescues `UnknownInputKeysError` and returns `MCP::Tool::Response.new([...], error: true)` with the text `<tool_name>: <message>`, rather than the SDK wrapping it as a JSON-RPC `-32603` that names the facade instead of the tool. Facade dispatch reaches the target's materialized `call`, so a facade caller — which only ever saw `arguments: object` — gets the same in-band error naming the inner tool. The non-materialized `Tool.call` lets the error propagate.
+- **Facade dispatch rejects keys beside `tool_name` and `arguments`.** The facade schema declares only those two, and dispatch read only `arguments`, so `{ tool_name:, arguments:, data: {...}, limit: 100 }` ran the target unfiltered and returned success. The facade now answers in-band naming itself. Its guidance differs from a tool's on purpose: a flattened parameter is supported and merely misplaced, so the caller is told to re-send it inside `arguments`, not to give up on it. `reject_unknown_input_keys = false` restores the old behavior here too.
+- **A facade `arguments` that is not an object is rejected instead of dropped.** `coerce_arguments` returned `{}` for an array, a scalar, a raw JSON blob of either, or `nil`, so the target ran with no arguments at all and the unfiltered default came back as a success — the same shape as the incident above, on the same surface.
+- **An `arguments.server_context` can no longer replace the request's context.** Dispatch splatted the caller's arguments *after* the `server_context:` keyword, and a later duplicate keyword wins in Ruby, so a caller-supplied `server_context` key bound the context used to compile the schema. Every predicate then ran against that object and fell open, admitting `@requires`/`@feature`-gated fields. The keyword is now passed last. Present since facades shipped in 0.7.0; direct (non-facade) calls were never affected, since the SDK passes `server_context:` last.
+- **An unroutable `tool_name` and a malformed `arguments` JSON blob come back in-band** with the facade's name and the list of tools the caller may use, instead of raising out of band.
+
+### Added
+- **`config.reject_unknown_input_keys`** (default `true`). `false` restores the 0.8 drop-everything behavior for both unknown and gated keys.
+- **`config.ignored_input_keys`** (default `[]`). Names the envelope keys a host's client attaches to every call — a UI annotation, not a tool parameter — which are dropped rather than rejected. Applied wherever a key is checked against a schema: beside `tool_name` and `arguments` on a facade call, and at the top level of any tool's params. A client that annotates every call reaches a flat domain directly, where there is no facade to exempt it, so one setting covers both surfaces.
+
+### Migration notes
+- **Check what your client puts beside `tool_name` and `arguments` before upgrading.** A client that annotates every facade call with an envelope key had it silently ignored through 0.8 and now has every call rejected. Name the key in `config.ignored_input_keys`, or declare it on the tools. Measuring the model's tool calls is not enough to find these: a host's own envelope is added by code, so it rides beside `arguments` where a survey of invented parameter names cannot see it, and a call the host makes on its own behalf may never appear in the conversation log at all. Read the client's source.
+- **Migrating a tool onto this gem is now a contract change.** A tool that used to be served by a hand-rolled endpoint, where an unknown key fell into a permit list and vanished, starts rejecting whatever its caller adds. When that caller is code rather than a model there is nobody to read the error and retry, so the key has to be declared or ignored in the same change that migrates the tool.
+- `reject_unknown_input_keys = false` does not cover the non-object `arguments` rejection: `arguments` is `required` in the facade schema, so an array, scalar or `nil` is rejected whatever the flag says. A host that leaves the MCP SDK's `validate_tool_call_arguments` on never reaches it, because the SDK rejects first.
+- A host that overrides `materialize_for` (or calls `filter_input` directly) must `rescue McpAuthorization::UnknownInputKeysError` and build its own error response. Until it does, the rejection still happens, but what the caller receives depends on the MCP SDK version — an in-band `Internal error calling tool <name>` response on some, a JSON-RPC internal error on others — and the host's exception reporter fires on every model typo.
+- Any client or test that relied on a top-level extra key being ignored — invented or gated — now sees an error. That reliance was the bug this release removes. A client that sends the full field set regardless of the caller's permissions must send only the fields in that caller's `tools/list` schema.
+
+## [0.8.0]
+
+A supported seam for tool classes the host generates at runtime instead of
+defining in a file under `tool_paths`. Additive and opt-in — a host that sets
+no producers behaves exactly as before. (#35)
+
+### Added
+- **`config.tool_producers`** — an array of callables that register generated tool classes. Invoked by `ToolRegistry.ensure_tools_loaded!` on the first read of a registry that has not finished loading, immediately after the `tool_paths` eager-load, and again after every `reset!`. Defaults to `[]`.
+
+  Registering generated tools previously had no supported hook, so hosts improvised one from a Rails boot callback — and both available callbacks are traps. Registering *before* the gem's own load tripped `ensure_tools_loaded!`'s old `return if @registered_tools&.any?` guard and silently suppressed every file-defined tool, leaving a near-empty `tools/list` in any environment that doesn't eager-load. Registering from `config.to_prepare` runs host code during `:run_prepare_callbacks`, which precedes `:eager_load!` and the railtie `after_initialize` that copies `config.i18n` onto `I18n` — so application code loaded there sees an empty `I18n.load_path`, and any class resolving a translation in its class body freezes `"Translation missing: …"` into its validators and option lists permanently, with the failures landing nowhere near MCP. Running producers from a registry read makes both unreachable by construction rather than by documentation.
+
+- **Boot-time registry population when the host eager-loads.** The Engine reads the registry from `after_initialize` when `config.eager_load` is on, so a malformed tool — or a producer that raises — fails the deploy rather than the first `tools/list`. Development and test stay lazy. `after_initialize` specifically: it is the earliest phase where the framework is guaranteed to be fully configured, `I18n` included.
+
+### Changed
+- **Loading completion is tracked separately from registry contents.** `ensure_tools_loaded!` previously short-circuited on `return if @registered_tools&.any?`, and `registered_tools` only triggered a load while the array was empty. That conflated "the registry has entries" with "loading finished", which is wrong as soon as loading can fail partway: `eager_load_tool_paths!` registers the file-defined tools *first*, so by the time a producer raises the array is already non-empty — as it also is when a producer registers 40 tools and raises on the 41st. Every later read then no-op'd, so a bad producer failed loudly exactly once and silently forever after, leaving a permanently incomplete surface and contradicting the documented "exceptions propagate" contract. A dedicated `@tools_loaded` flag, set only after every producer returns, replaces both guards; a raising producer is now retried on every read until it is fixed. Re-running is safe — `register` dedupes by identity and `eager_load_dir` is a no-op on an already-loaded directory.
+
+  Two consequences worth naming. A host that calls `register` directly before the first read no longer suppresses the `tool_paths` load — the silent-erasure hazard producers exist to remove is now unreachable from that direction too. And `reset!` clears the flag, so a reload still reloads.
+
+### Fixed
+- **`ensure_tools_loaded!` no longer raises on a partially-loaded Rails.** The autoloader pass guarded on the bare `Rails` constant and then called `Rails.root` / `Rails.autoloaders`. A process where `Rails` is defined but incomplete (or an unrelated module of that name) satisfied `defined?` and raised `NoMethodError`, taking `registered_tools` down with it — including for a host whose tools all come from producers and need no autoloader at all. It now probes for the methods it actually calls, matching the `defined?(Rails) && Rails.respond_to?(:env)` idiom already used in `Diagnostics`.
+
+### Internal
+- `ensure_tools_loaded!` is reentrant: a producer may read the registry (to inspect what is already registered, say) without recursing forever. The reentrancy guard is cleared in an `ensure`, so a raising producer does not wedge every later read.
+- The `tool_paths` eager-load moved into a private `eager_load_tool_paths!`, leaving `ensure_tools_loaded!` as the ordering contract it documents.
+
 ## [0.7.1]
 
 Follow-ups from the 0.7.0 review (onboardiq/mcp_authorization#31).

data/README.md

@@ -1,4 +1,5 @@
 # mcp_authorization
+[read it](https://fountain.engineering/mcp_authorization/)
 
 Rails engine for serving MCP tools with per-request schema discrimination compiled from RBS type annotations.
 
@@ -6,6 +7,10 @@ Add it to your Gemfile and your Rails app speaks [MCP](https://modelcontextproto
 
 > Looking for task-oriented "how do I X?" recipes rather than reference? See the **[Cookbook](COOKBOOK.md)**.
 
+<!-- site:skip -->
+> Prefer these docs as a browsable site, one section per page? **<https://fountain.engineering/mcp_authorization>** — built from these same files by [`site/collect.rb`](site/collect.rb).
+<!-- site:endskip -->
+
 ## Three layers of authorization
 
 The gem gives you three independent controls over what each user sees:
@@ -13,7 +18,7 @@ The gem gives you three independent controls over what each user sees:
 | Layer | Mechanism | Effect |
 |---|---|---|
 | **Tool visibility** | `authorization :manage_workflows` (RBAC) or `gate :feature, :sms` (any predicate) on the tool class | Tool hidden entirely from users who fail any check |
-| **Input fields** | `@requires(:backward_routing)` or `@feature(:sms)` on a param in `#:` annotation | Field excluded from the input schema *and* stripped from inbound params at call time |
+| **Input fields** | `@requires(:backward_routing)` or `@feature(:sms)` on a param in `#:` annotation | Field excluded from the input schema; a top-level one sent anyway is rejected at call time, a nested one is stripped |
 | **Output variants** | `@requires(:backward_routing)` or `@feature(:sms)` on a variant in `@rbs type output` | Variant excluded from the `oneOf` *and* fields projected out of the handler's return value before it crosses the wire |
 
 Tool-level `authorization :perm` is RBAC (calls `current_user.can?`). Tool-level `gate :predicate, :value` and the field-level annotations are generic — any predicate name works, as long as the server context implements `{predicate}?(value)`. See [Generic predicate tags](#generic-predicate-tags) below.
@@ -22,7 +27,13 @@ Tool-level `authorization :perm` is RBAC (calls `current_user.can?`). Tool-level
 
 `@requires` is a security boundary, not a hint. At tool-call time the gem:
 
-- **Filters inbound params** against the user's compiled input schema. Gated fields, and any keys not declared in the schema at all, are dropped before the handler's `#call` is invoked. A handler that takes `force:` gated behind `@requires(:admin)` will see `force: false` (its default) for non-admins even if the MCP client sends `force: true` in the raw JSON-RPC payload.
+- **Rejects inbound params outside the caller's compiled input schema.** The schema the caller received from `tools/list` is the contract. A top-level key outside it — one the tool never declared, or one gated behind a predicate this caller fails — does not exist from the caller's point of view. Such a key used to be dropped silently, which returned a success-shaped result that ignored part of the request: an LLM that never saw the per-tool schema (e.g. behind a [facade](#tool-grouping-facades)) invented a filter, got the *unfiltered* page back as `success: true`, and acted on it; a non-admin sending `force: true` was told the flag was applied. So `filter_input` raises `McpAuthorization::UnknownInputKeysError` and the materialized tool returns it as an in-band tool error (`isError: true`). The text is written for a model that will read it as a tool result:
+
+  ```
+  list_applicants: Unknown parameters: data, limit. Nothing was executed. Accepted parameters: funnel_id, page, per_page, query, stage_id. If your task depends on a rejected parameter (for example filtering by it), do not re-run this call without it: the result would be unfiltered. Do not substitute another parameter to approximate it. Use a tool that supports it, or tell the user it is not possible.
+  ```
+
+  Both lists come from the caller's own schema, so the message reveals nothing `tools/list` did not already show that caller. The handler never runs, so a gated field is still never applied for a caller who lacks it — the boundary holds, it just stops being silent. A facade call is checked twice: a key beside `tool_name` and `arguments` is rejected by the facade, which tells the caller to re-send it inside `arguments` (a flattened parameter is supported, just misplaced), and a key inside `arguments` by the target tool, which tells it not to re-run without the parameter. Name a client's envelope key in `config.ignored_input_keys` to have it dropped instead, on both surfaces. Keys nested inside a declared object param are still projected silently. With `strict_schema` on, the compiled root carries `additionalProperties: false`, so an MCP SDK that validates arguments (`validate_tool_call_arguments`, on by default in the `mcp` gem) rejects the call with its own generic message before this one is produced; turn that validation off on the server if the model must read the guidance. Set `config.reject_unknown_input_keys = false` to restore the pre-0.9 drop-everything behavior. A host that overrides `materialize_for` or calls `filter_input` directly must rescue `UnknownInputKeysError` itself; unrescued it surfaces as a JSON-RPC internal error carrying the same message. The non-materialized `Tool.call` lets it propagate.
 - **Projects the handler's return value** onto the user's compiled output schema. A variant hidden by `@requires` has its shape unavailable, so if the handler erroneously emits that variant's extra fields, they are stripped before serialization. A handler bug or refactor accident cannot leak admin-only fields to a non-admin.
 
 This means handler authors don't have to remember to re-check `can?` at every branch -- the schema *is* the boundary. `can?` inside `#call` is still useful for logic that changes behavior (not just field visibility), but it is no longer load-bearing for security.
@@ -66,9 +77,24 @@ end
 | `mount_path` | `"/mcp"` | URL prefix for MCP endpoints |
 | `default_domain` | `"default"` | Domain when no `:domain` segment in path |
 | `tool_paths` | `["app/mcp"]` | Directories where tool classes live (relative to Rails.root) |
+| `tool_producers` | `[]` | Callables that register tool classes built at runtime — see [Generated tools](#generated-tools) |
 | `shared_type_paths` | `["sig/shared"]` | Directories where shared `.rbs` type files live |
 | `context_builder` | *required* | `(request) -> context` |
 | `cli_context_builder` | `nil` | `(domain:, role:) -> context` for rake tasks |
+| `strict_schema` | `false` | Emit stricter compiled schemas |
+| `reject_unknown_input_keys` | `true` | Reject a `tools/call` carrying a top-level param outside the caller's compiled input schema (undeclared, or gated behind a predicate the caller fails) instead of silently dropping it — see [Enforcement, not just shaping](#enforcement-not-just-shaping) |
+| `ignored_input_keys` | `[]` | Envelope keys a client attaches to every call, dropped rather than rejected — beside `tool_name`/`arguments` on a facade, and at the top level on any tool |
+| `tools_list_cache` | `nil` | `:memory`, `:redis`, or any object responding to `get`/`set` — see [Caching `tools/list`](#caching-toolslist) |
+| `tools_list_cache_ttl` | `3600` | Per-entry TTL in seconds |
+| `tools_list_cache_redis` | `nil` | Explicit Redis client for the `:redis` store |
+| `tools_list_cache_redis_url` | `nil` | Explicit Redis URL; falls back to `ENV["REDIS_URL"]`, then `Redis.new` |
+
+Two configuration **methods** (not attributes) turn a domain into grouped facades — see [Tool grouping](#tool-grouping-facades):
+
+| Method | Purpose |
+|---|---|
+| `facet_domain :domain, group_by: :category, ...` | Present this domain as one facade tool per category. Optional `schema_strategy:`, `uncategorized:`, `facade_suffix:`. |
+| `categories { summary :key, "text" }` | Declare one summary line per group, used as each facade description's lead. |
 
 ## The contract
 
@@ -293,6 +319,7 @@ class MyTool < McpAuthorization::Tool
   gate :feature, :order_tracking  # any predicate: hidden unless server_context.feature?(:order_tracking)
   gate :tier, :enterprise         # multiple gates AND together
   tags "recruiting", "operations" # which domains this tool appears in
+  category :orders                # group this tool belongs to in a faceted domain
   read_only!                      # MCP annotation hints
   dynamic_contract MyService      # handler class
 end
@@ -304,6 +331,7 @@ end
 | `authorization :sym` | Tool-level RBAC visibility gate. Convenience alias for `gate :requires, :sym` — routes through the generic gate pipeline and falls back to `current_user.can?(:sym)` when the server context lacks a `requires?` method. Omit for public tools. |
 | `gate :predicate, :value` | Tool-level generic predicate gate. Calls `server_context.{predicate}?(value)`. Repeat for AND. Fail-open when the predicate method is missing (warning logged in dev). |
 | `tags "domain1", ...` | Domain(s) this tool appears under. Defaults to `["default"]`. |
+| `category :name` | Group this tool belongs to when its domain is faceted (see [Tool grouping](#tool-grouping-facades)). Ignored in flat domains. Optional `summary:` kwarg supplies the group summary for single-tool groups. |
 | `dynamic_contract HandlerClass` | Handler providing description, schemas, and execution |
 | `read_only!` | Annotation: tool only reads data |
 | `not_destructive!` | Annotation: tool does not destroy data |
@@ -316,6 +344,47 @@ end
 
 Tools self-register when loaded. Put them anywhere under `tool_paths` (default: `app/mcp/`).
 
+### Generated tools
+
+Some tools aren't worth writing by hand — one per controller action, one per row in a config table, one per endpoint in a family. For those, register a **producer**: a callable that mints the classes and registers them.
+
+```ruby
+McpAuthorization.configure do |config|
+  config.tool_producers << -> { MyApp::GeneratedTools.register_all! }
+end
+```
+
+Producers run from `ToolRegistry.ensure_tools_loaded!` — on the first read of an empty registry, immediately after `tool_paths` is eager-loaded, and again after every reload. Two properties follow from that, and both matter:
+
+- **Don't register from a Rails boot callback instead.** Generating tools usually means loading the code they derive from, and from `config.to_prepare` that happens during `:run_prepare_callbacks` — before `:eager_load!`, and before railties copy `config.i18n` onto `I18n`. Application code loaded that early sees an empty `I18n.load_path`, so any class resolving a translation in its class body freezes `"Translation missing: …"` into its validators and option lists for the life of the process. A producer sidesteps the ordering question entirely.
+- **Don't register before the registry loads its own tools.** Historically `ensure_tools_loaded!` skipped the `tool_paths` pass once the registry was non-empty, so registering first made every file-defined tool silently disappear from `tools/list`. Producers run *after* that pass, and completion is now tracked separately from "the registry has entries", so the ordering is not yours to get right.
+
+A producer must be **idempotent**. `register` dedupes by object identity, not by `tool_name`, so minting a fresh class on every call registers a second tool under the same name and leaves `find_tool` resolving an arbitrary one. Reuse the class while its inputs are unchanged. Exceptions propagate — a malformed generated tool fails the read rather than vanishing.
+
+When the host eager-loads (production), the engine reads the registry at `after_initialize`, so a producer that raises fails the deploy instead of the first `tools/list`. Development and test stay lazy.
+
+### Introspecting a tool class
+
+Every declaration is readable back off the class, which is what the registry, the facade builder, and the cache digest use:
+
+| Reader | Returns |
+|---|---|
+| `_permission` | The symbol passed to `authorization` |
+| `_gates` | `[{ name:, value: }, ...]` for every declared gate |
+| `_tags` | Declared domains |
+| `_category` | Declared category symbol, or `nil` |
+| `_category_summary` | Summary passed to `category(summary:)`, or `nil` |
+| `_contract_handler` | The handler class |
+
+`ToolRegistry` is the entry point for turning those declarations into MCP tools:
+
+| Registry method | Purpose |
+|---|---|
+| `tool_classes_for(domain:, server_context:)` | Every permitted tool in a domain (the `tools/list` path) |
+| `tool_class_for(domain:, name:, server_context:)` | One named tool, or `nil` (the `tools/call` path) |
+| `facades_for(domain:, server_context:)` | Facades for a faceted domain |
+| `facade_for(domain:, name:, server_context:)` | One facade by name |
+
 ## Contract validation
 
 If a handler is missing required methods or schema definitions, the gem raises an `ArgumentError` on first request with a full diagnostic:
@@ -384,6 +453,19 @@ McpAuthorization.configure do |config|
 end
 ```
 
+Grouping is opt-in and per-domain: a domain with no `facet_domain` behaves
+exactly as before, and `category` is inert there. `facet_domain` takes:
+
+| Option | Default | Description |
+|---|---|---|
+| `group_by:` | *required* | Grouping key. Only `:category` today; anything else raises `ArgumentError`. |
+| `schema_strategy:` | `:vendor_extension` | Where per-tool argument schemas go — `:vendor_extension` or `:lazy` (below). |
+| `uncategorized:` | `:fallback` | `:fallback` collects tools with no `category` into an `uncategorized` group; `:error` raises instead. |
+| `facade_suffix:` | `"tools"` | Token appended to a category to form the facade name (`orders_tools`). |
+
+For a group that holds a single tool, `category :orders, summary: "..."` saves a
+trip to the central registry. When both are declared, `config.categories` wins.
+
 `tools/list` for the domain then returns one facade per group the caller has
 at least one permitted tool in (`orders_tools`, `billing_tools`), each
 describing its tools with RBAC-filtered one-liners. Calling a facade names the
@@ -394,10 +476,40 @@ inner tool and its arguments:
   "arguments": { "tool_name": "update_order", "arguments": { "id": "o_1" } } }
 ```
 
-Dispatch resolves the real tool through its normal call path — authorization,
-gating, and schema filtering apply exactly as if the tool had been called
-directly, and JSON-string argument blobs are coerced against the *target*
-tool's schema.
+### Facade shape
+
+| Part | Value |
+|---|---|
+| Name | `"#{category}_#{facade_suffix}"` — default suffix `tools`, so `orders_tools` |
+| Description | Group summary, then one line per tool the caller may invoke: `- tool_name — first line of that tool's description for this caller` |
+| `inputSchema` | Flat object: `tool_name` (string enum of permitted tool names) + `arguments` (object). Both required. |
+| `_meta` | Under `:vendor_extension`, key `"tool-input-schemas"` — a map of tool name to that caller's compiled input schema |
+
+### Facade dispatch
+
+Dispatch resolves the real tool through its normal call path — there is no
+second code path, and therefore no second place for authorization to be wrong:
+
+1. **Advertised-set check.** `tool_name` must be in the set advertised to *this*
+   caller, else `ArgumentError` listing the valid names.
+2. **Re-resolution.** The tool is re-fetched via `ToolRegistry.tool_class_for`,
+   which re-runs `permitted?` — so a stale advertised set cached by a client
+   cannot get a caller into a tool they've lost access to. Failure raises
+   `NotAuthorizedError`.
+3. **Argument coercion.** MCP clients frequently serialize nested objects as JSON
+   strings, and the facade's generic `arguments: object` contract cannot know
+   which fields are structured. The `arguments` blob itself, and any top-level
+   value whose type in the *target's* compiled schema is `object` or `array`, are
+   JSON-parsed. Invalid JSON raises `ArgumentError` naming the field.
+4. **Delegation.** The target's materialized `call` runs, applying `filter_input`
+   and `filter_output` exactly as in a direct call.
+
+Direct tool names still resolve on `tools/call`, so a client that learned a
+real tool name before the domain was faceted keeps working.
+
+A `tools/call` build skips the `_meta` per-tool schema map (`for_dispatch: true`)
+— nothing on the call path reads it, and building it would recompile every tool
+in the group on every call.
 
 The facade `inputSchema` is always a flat object (a `tool_name` enum plus a
 permissive `arguments` object). It has to be: an LLM tool `input_schema` must
@@ -417,13 +529,31 @@ therefore only chooses where the per-tool schemas go:
 
 Uncategorized tools land in an `uncategorized` facade by default; pass
 `uncategorized: :error` to fail fast instead. Groups with zero permitted tools
-are hidden entirely, so a facade never advertises an empty `enum`.
+are hidden entirely, so a facade never advertises an empty `enum`. A facade
+name that collides with a real registered tool in the domain raises
+`FacadeBuilder::FacadeNameCollisionError` rather than shadowing that tool.
 
 Facade names are `#{category}_tools` by default. Override the suffix per domain
 with `facade_suffix:` — e.g. `config.facet_domain :admin, group_by: :category,
 facade_suffix: "hire"` exposes `orders_hire`, `billing_hire`. The suffix must be
 a lowercase identifier fragment (`[a-z0-9_]`) so the derived name stays a valid
-MCP tool name. See `docs/designs/tool-grouping-facades.md` for the full design.
+MCP tool name. See [the design doc](docs/designs/tool-grouping-facades.md) for
+the full rationale.
+
+Facet configuration participates in the [`tools/list` cache](#caching-toolslist)
+digest — each tool's `category`, every `facet_domain` setting, and every group
+summary — so toggling grouping or rewording a summary invalidates cached
+listings the same way a gate change does.
+
+### Facade errors
+
+| Error | Raised when |
+|---|---|
+| `FacadeBuilder::UncategorizedToolError` | A tool has no `category` in a domain faceted with `uncategorized: :error` |
+| `FacadeBuilder::FacadeNameCollisionError` | A derived facade name collides with a registered tool in the domain |
+| `ArgumentError` (config) | Invalid `group_by:`, `schema_strategy:`, `uncategorized:`, or `facade_suffix:` |
+| `ArgumentError` (dispatch) | `tool_name` not advertised, or a string argument that isn't valid JSON |
+| `NotAuthorizedError` | Re-resolution found the caller isn't permitted after all |
 
 ## RBS type syntax
 
@@ -458,6 +588,16 @@ The `@rbs type` comments compile to JSON Schema:
 # @rbs type input = { id: String, status: status }
 ```
 
+Every handler must declare `@rbs type output`. It may be a single record, a reference, or a union:
+
+```ruby
+# @rbs type output = { id: String }        # inline record
+# @rbs type output = applicant             # reference
+# @rbs type output = success | error       # union
+```
+
+When a type appears more than once in a compiled schema, it is hoisted into `$defs` and referenced with `$ref` rather than inlined repeatedly. This is automatic — nothing to declare.
+
 ### Constraint and annotation tags
 
 Tag any field in a `#:` annotation or `@rbs type` record to add JSON Schema constraints. Tags are written as `@tag(value)` after the type:
@@ -557,6 +697,17 @@ end
 
 The `@min` / `@max` tags are type-aware: on strings they emit `minLength`/`maxLength`, on numbers `minimum`/`maximum`, and on arrays `minItems`/`maxItems`.
 
+### Where tags may appear
+
+| Position | Effect |
+|---|---|
+| On a param in `#:` | Constrains or gates that input field |
+| On a field in an `@rbs type` record | Constrains or gates that output field |
+| On a member of an `@rbs type` union | Gates that whole output variant |
+| On an inline literal union member | Gates that individual member |
+
+A tag trailing a whole inline literal union applies to the **field**, not to the last member — the compiler distinguishes the two by whether any non-final member carries a tag.
+
 ### Multiline `#:` annotations
 
 The `#:` annotation above `def call` supports multiple lines. Each line starts with `#:`:
@@ -611,6 +762,70 @@ MCP clients can narrow on `success: const true` vs `success: const false` -- the
 
 Source files are parsed once at boot and cached in memory. Only `@requires` filtering runs per request (hash lookups and `can?` calls). In development, caches are cleared automatically on file change via the Rails reloader.
 
+Per-request work is also scoped to what the incoming JSON-RPC method actually needs, since per-tool schema compilation is the dominant cost of an MCP request:
+
+| Method | Tools materialized |
+|---|---|
+| `tools/list` | Every permitted tool in the domain |
+| `tools/call` | Only the invoked tool |
+| `initialize`, `notifications/initialized`, `ping`, GET stream probe | None |
+| Unrecognized shape (e.g. a batch with no top-level `method`) | Full domain, so routing stays correct |
+
+In a 140-tool domain that took a `tools/call` from ~2.6s to under 100ms and `notifications/initialized` from ~2s to ~1ms, with no change to `tools/list` output. What remains is the listing itself — which is cacheable (below) and, for very large domains, [groupable](#tool-grouping-facades).
+
+## Caching `tools/list`
+
+`tools/list` must materialize a per-user schema for every tool in a domain. That cost can be cached. Default is no caching, so nothing changes unless you opt in:
+
+```ruby
+McpAuthorization.configure do |c|
+  c.tools_list_cache = :redis          # or :memory, or any object responding to get/set
+  c.tools_list_cache_ttl = 3600        # seconds (default)
+end
+```
+
+| Store | Behavior |
+|---|---|
+| `:memory` | Process-local, bounded LRU with per-entry TTL |
+| `:redis` | Shared across processes, JSON values, per-entry TTL |
+| custom object | Anything responding to `get`/`set` |
+| *(unset)* | `NullStore` — no caching |
+
+The Redis connection resolves from an explicit client (`tools_list_cache_redis`), then `tools_list_cache_redis_url`, then `ENV["REDIS_URL"]`, then a bare `Redis.new` — i.e. it defaults to the host's Rails redis config with no extra wiring. `redis` is an optional dependency, required lazily only when the Redis store is used.
+
+### The key is a decision vector, not an identity
+
+```
+H(domain + tool_defs_digest + vocab_fingerprint + decision_vector)
+```
+
+The **decision vector** is the result of every gating decision the domain's compilation consults — `@requires` / `@feature` / `@tier` / custom predicates, tool-level `gate` and `authorization`, and `current_user.can?` / `default_for`. It never includes user or account identity.
+
+Two contexts that answer all of those identically produce identical schemas by construction, so they share an entry. Flip one feature flag and the vector — and the key — change, so an admin in a flag-on account never receives a flag-off account's tools. The `tool_defs_digest` (each tool's gates plus handler source, plus facet configuration) changes on deploy, auto-invalidating stale entries; the TTL bounds out-of-band staleness, such as a permission changed directly in the database.
+
+### Two ways to supply the vector
+
+**Automatic.** On the first (cold) compile the gem wraps the context in a `Cache::Recorder`, learns the domain's predicate vocabulary, then replays that vocabulary against the live context on later requests.
+
+**Explicit.** If the server context responds to `mcp_cache_fingerprint`, its return value is used verbatim as the decision component and the recorder is skipped:
+
+```ruby
+class ServerContext
+  def mcp_cache_fingerprint
+    [current_user.role, account.enabled_features.sort, account.plan_tier]
+  end
+end
+```
+
+Explicit wins when present. Reach for it when gating depends on something the recorder cannot observe, or when you would rather own the invalidation contract than infer it.
+
+### Operational notes
+
+- **Cache outages fail open** — a `get`/`set` error is logged and behaves as a miss, never breaking `tools/list`.
+- **Only successful listings are cached.** Error and unexpected responses render but are not stored.
+- **A hit still rebuilds the envelope** — the cached `result` is re-wrapped with the live JSON-RPC id.
+- **Development reloads clear it** (the reloader calls `Cache.reset!`), so an edited annotation shows up immediately.
+
 ## Development
 
 ### Live reload

data/lib/mcp_authorization/configuration.rb

@@ -50,6 +50,27 @@ module McpAuthorization
     #: Array[String]
     attr_accessor :tool_paths
 
+    # Callables that register tool classes the host generates at runtime,
+    # rather than defining in a file under +tool_paths+.
+    #
+    #   config.tool_producers << -> { MyApp::GeneratedTools.register_all! }
+    #
+    # Invoked by +ToolRegistry.ensure_tools_loaded!+ after the +tool_paths+
+    # eager-load, on the first read of an empty registry. Because a producer
+    # runs from a registry read rather than a Rails boot callback, it cannot
+    # execute before the framework is fully configured — see
+    # +ToolRegistry.ensure_tools_loaded!+ for why that matters.
+    #
+    # A producer must be idempotent: +register+ dedupes by object identity,
+    # not by +tool_name+, so minting a fresh class on every call registers a
+    # second tool under the same name and leaves +find_tool+ resolving an
+    # arbitrary one. Reuse the class while its inputs are unchanged.
+    #
+    # Exceptions propagate — a malformed generated tool fails the read rather
+    # than silently vanishing from the surface.
+    #: Array[^() -> void]
+    attr_accessor :tool_producers
+
     # Directories (relative to +Rails.root+) where shared +.rbs+ type
     # files live. Used by RbsSchemaCompiler to resolve +# @rbs import+.
     #: Array[String]
@@ -79,6 +100,25 @@ module McpAuthorization
     #: bool
     attr_accessor :strict_schema
 
+    # When true (the default), a +tools/call+ whose params carry a top-level
+    # key outside the caller's compiled input schema is rejected with
+    # +McpAuthorization::UnknownInputKeysError+ instead of having the key
+    # silently dropped. A field gated by a predicate this caller fails is
+    # outside that schema and is rejected the same way — the caller's
+    # schema is the contract. Set to false to restore the pre-0.9
+    # drop-everything behavior.
+    #: bool
+    attr_accessor :reject_unknown_input_keys
+
+    # Keys a host's client attaches to every call as an envelope — a UI
+    # annotation, not a tool parameter — which are dropped rather than
+    # rejected. Empty by default. Applied wherever a key is checked against a
+    # schema: beside +tool_name+ and +arguments+ on a facade call, and at the
+    # top level of any tool's params, so the same envelope is exempt on a
+    # facade and on a flat domain alike.
+    #: Array[String]
+    attr_accessor :ignored_input_keys
+
     # Cache for the +tools/list+ response. Opt-in; defaults to no caching.
     # Accepts:
     #   nil / false  — no caching (default)
@@ -151,12 +191,15 @@ module McpAuthorization
       @server_name = "mcp-authorization"
       @server_version = "1.0.0"
       @tool_paths = %w[app/mcp]
+      @tool_producers = []
       @shared_type_paths = %w[sig/shared]
       @default_domain = "default"
       @mount_path = "/mcp"
       @context_builder = nil
       @cli_context_builder = nil
       @strict_schema = false
+      @reject_unknown_input_keys = true
+      @ignored_input_keys = []
       @tools_list_cache = nil
       @tools_list_cache_ttl = 3600
       @tools_list_cache_redis = nil

data/lib/mcp_authorization/engine.rb

@@ -50,6 +50,23 @@ module McpAuthorization
       end
     end
 
+    # Populate the registry at boot when the host eager-loads (production), so
+    # a malformed tool — or a +tool_producers+ callable that raises — fails the
+    # deploy instead of the first +tools/list+.
+    #
+    # +after_initialize+ specifically: this read may load a large part of the
+    # host application, and it is the earliest phase where the framework is
+    # guaranteed to be fully configured — notably +I18n+, which railties only
+    # wire up in this same phase. Rails cannot have loaded this Engine before
+    # its own railties, so this block is always registered after theirs, and
+    # load hooks run in registration order.
+    #
+    # Development and test stay lazy: nothing loads until something reads the
+    # registry.
+    config.after_initialize do |app|
+      McpAuthorization::ToolRegistry.registered_tools if app.config.eager_load
+    end
+
     # Prepend MCP routes into the host app's router. Uses +prepend+ so the
     # MCP endpoint is available before any catch-all routes the host may
     # define. Supports both domain-scoped and bare paths.

data/lib/mcp_authorization/facade_builder.rb

@@ -25,9 +25,19 @@ module McpAuthorization
     # registered tool name. Renaming the category is the fix.
     class FacadeNameCollisionError < StandardError; end
 
+    # A facade call the caller can fix from the error alone: an unroutable
+    # +tool_name+, a malformed +arguments+, or a key beside the two the
+    # facade declares. Returned in-band so the message reaches the model.
+    # Raised only before dispatch reaches the target, so it never relabels a
+    # target's own error with the facade's name.
+    class FacadeCallError < ArgumentError; end
+
     # Fallback group for uncategorized tools (default mode).
     FALLBACK_CATEGORY = :uncategorized #: Symbol
 
+    # The only two keys a facade's inputSchema declares.
+    FACADE_KEYS = %w[arguments tool_name].freeze #: Array[String]
+
     class << self
       # All facades for a domain, one per non-empty group the caller has at
       # least one permitted tool in. Empty groups produce no facade — which
@@ -153,6 +163,9 @@ module McpAuthorization
 
           define_singleton_method(:call) do |server_context: nil, **params|
             builder.send(:dispatch, domain, advertised, params, server_context || ctx)
+          rescue McpAuthorization::FacadeBuilder::FacadeCallError => e
+            # Raised before the target runs, so the facade's name is the right label.
+            MCP::Tool::Response.new([{ type: "text", text: "#{name}: #{e.message}" }], error: true)
           end
         end
       end
@@ -235,10 +248,12 @@ module McpAuthorization
       #    the same code path as a direct call.
       #: (String, Set[String], Hash[Symbol, untyped], untyped) -> untyped
       def dispatch(domain, advertised, params, server_context)
+        reject_unknown_facade_keys!(params)
         tool_name = (params[:tool_name] || params["tool_name"]).to_s
         unless advertised.include?(tool_name)
-          raise ArgumentError,
-            "unknown tool_name #{tool_name.inspect}; expected one of #{advertised.to_a.sort.inspect}"
+          raise FacadeCallError,
+            "unknown tool_name #{tool_name.inspect}. Nothing was executed. " \
+            "Available tools: #{advertised.to_a.sort.join(", ")}."
         end
 
         candidates = McpAuthorization::ToolRegistry.tools_by_domain[domain] || []
@@ -249,7 +264,46 @@ module McpAuthorization
         raise McpAuthorization::Tool::NotAuthorizedError unless original && target
 
         arguments = coerce_arguments(original, params[:arguments] || params["arguments"], server_context)
-        target.call(server_context: server_context, **arguments)
+        reject_reserved_argument_keys!(arguments)
+        # server_context last: a later duplicate keyword wins in Ruby, so an
+        # `arguments.server_context` cannot replace the request's own context.
+        target.call(**arguments, server_context: server_context)
+      end
+
+      # The facade schema declares only tool_name and arguments; a sibling key
+      # is outside every caller's contract and was silently ignored, the same
+      # gap filter_input closes for the target tool. The guidance differs from
+      # the target's: a flattened parameter is supported, it is just in the
+      # wrong place, so the caller is told to nest it rather than to give up.
+      # +config.ignored_input_keys+ names host envelope keys to drop instead.
+      #: (Hash[Symbol, untyped]) -> void
+      def reject_unknown_facade_keys!(params)
+        return unless McpAuthorization.config.reject_unknown_input_keys
+
+        ignored = McpAuthorization.config.ignored_input_keys.map(&:to_s)
+        unknown = params.keys.map(&:to_s) - FACADE_KEYS - ignored
+        return if unknown.empty?
+
+        list = unknown.join(", ")
+        raise FacadeCallError,
+          "Unknown parameter#{"s" if unknown.size > 1}: #{list}. Nothing was executed. " \
+          "This tool accepts only tool_name and arguments; a tool's own parameters go " \
+          "inside arguments. Re-send with #{list} inside arguments if the tool declares " \
+          "#{unknown.size > 1 ? "them" : "it"}, and omit #{unknown.size > 1 ? "them" : "it"} otherwise."
+      end
+
+      # +server_context+ binds the target's own keyword, so it can never be a
+      # tool parameter and +filter_input+ never sees it. Rejecting it keeps the
+      # release's guarantee — no key outside the schema is quietly ignored —
+      # and makes the caller's intent visible rather than silently discarded.
+      #: (Hash[Symbol, untyped]) -> void
+      def reject_reserved_argument_keys!(arguments)
+        return unless McpAuthorization.config.reject_unknown_input_keys
+        return unless arguments.key?(:server_context)
+
+        raise FacadeCallError,
+          "server_context is not a tool parameter and cannot be supplied by a caller. " \
+          "Nothing was executed. Remove it from arguments and re-send."
       end
 
       # Coerce a facade's +arguments+ blob against the target tool's
@@ -257,12 +311,19 @@ module McpAuthorization
       # objects as JSON strings; the facade's own contract only knows
       # `arguments: object`, so string blobs are parsed here — both the
       # blob itself and any top-level value whose target type is an object
-      # or array. Unknown / permission-gated fields are then stripped by
-      # the target's filter_input as in a direct call.
+      # or array. Keys outside the target's schema are then rejected by the
+      # target's filter_input as in a direct call.
       #: (singleton(McpAuthorization::Tool), untyped, untyped) -> Hash[Symbol, untyped]
       def coerce_arguments(tool_class, raw, server_context)
         parsed = raw.is_a?(String) ? parse_json_blob(raw, "arguments") : raw
-        return {} unless parsed.is_a?(Hash)
+        # An empty hash here used to mean "call the target with no arguments",
+        # so a caller that sent an array, a scalar or nil got the unfiltered
+        # default result reported as a success.
+        unless parsed.is_a?(Hash)
+          raise FacadeCallError,
+            "arguments must be an object mapping parameter names to values; got " \
+            "#{parsed.nil? ? "null" : parsed.class.name.downcase}. Nothing was executed."
+        end
 
         schema = tool_class.dynamic_input_schema(server_context: server_context)
         properties = schema.is_a?(Hash) ? (schema[:properties] || schema["properties"] || {}) : {}
@@ -282,7 +343,8 @@ module McpAuthorization
       def parse_json_blob(string, field)
         JSON.parse(string)
       rescue JSON::ParserError => e
-        raise ArgumentError, "#{field} was sent as a string but is not valid JSON: #{e.message}"
+        raise FacadeCallError,
+          "#{field} was sent as a string but is not valid JSON: #{e.message}. Nothing was executed."
       end
     end
   end

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -42,6 +42,31 @@ require "rbs/parser_aux"
 require_relative "diagnostics"
 
 module McpAuthorization
+  # Raised by +RbsSchemaCompiler.filter_input+ when the caller sent a
+  # top-level param outside its compiled input schema. +unknown_keys+ are
+  # the offending names; +accepted_keys+ are the names in the caller's
+  # schema. The message is written for an LLM that will read it as a tool
+  # result: it must not suggest re-running without the parameter, because
+  # for a filter that means acting on an unfiltered result.
+  class UnknownInputKeysError < ArgumentError
+    attr_reader :unknown_keys, :accepted_keys
+
+    #: (Array[String], Array[String]) -> void
+    def initialize(unknown_keys, accepted_keys)
+      @unknown_keys = unknown_keys
+      @accepted_keys = accepted_keys
+      accepted = accepted_keys.empty? ? "none" : accepted_keys.join(", ")
+      super(
+        "Unknown parameter#{"s" if unknown_keys.size > 1}: #{unknown_keys.join(", ")}. " \
+        "Nothing was executed. Accepted parameters: #{accepted}. " \
+        "If your task depends on a rejected parameter (for example filtering by it), " \
+        "do not re-run this call without it: the result would be unfiltered. " \
+        "Do not substitute another parameter to approximate it. " \
+        "Use a tool that supports it, or tell the user it is not possible."
+      )
+    end
+  end
+
   # Compiles RBS-style type annotations in Ruby source files into JSON Schema,
   # with per-request filtering based on +@requires+ permission tags.
   #
@@ -127,10 +152,16 @@ module McpAuthorization
 
       # Filter incoming params against the user's compiled input schema.
       #
-      # Any key that is not in the schema for this user is dropped — including
-      # +@requires+-gated fields the user lacks permission for, and any
-      # unknown fields not declared in the schema. This is the runtime
-      # enforcement counterpart to the input-shaping that +compile_input+ did.
+      # This is the runtime enforcement counterpart to the input-shaping
+      # that +compile_input+ did. The caller's schema is the contract: a
+      # top-level key outside it — whether the tool never declared it or
+      # declared it behind a predicate this caller fails — does not exist
+      # from the caller's point of view. Such a key used to be dropped
+      # silently, which returned a successful-looking result that ignored
+      # part of the request (an invented filter, a gated flag). By default
+      # it now raises +UnknownInputKeysError+; see
+      # +config.reject_unknown_input_keys+. Keys nested inside a declared
+      # object param are still projected silently.
       #
       # @param handler_class [Class]
       # @param params [Hash] Params as received from the MCP client.
@@ -141,9 +172,27 @@ module McpAuthorization
         return params unless params.is_a?(Hash)
         schema = compile_input_for_filter(handler_class, server_context: server_context)
         return params unless schema
+        reject_unknown_input_keys!(params, schema) if McpAuthorization.config.reject_unknown_input_keys
         project_against_schema(params, schema, defs_from(schema))
       end
 
+      # Raise when +params+ carries a top-level key outside +schema+'s
+      # properties. Both the unknown and the accepted names come from the
+      # caller's own schema, so the message reveals nothing +tools/list+ did
+      # not already show this caller. A host's envelope key named in
+      # +config.ignored_input_keys+ is dropped here as it is on a facade: a
+      # client that annotates every call reaches a flat domain directly, where
+      # there is no facade to exempt it.
+      #: (Hash[untyped, untyped], Hash[Symbol, untyped]) -> void
+      def reject_unknown_input_keys!(params, schema)
+        accepted = (schema[:properties] || {}).keys.map(&:to_s)
+        ignored = McpAuthorization.config.ignored_input_keys.map(&:to_s)
+        unknown = params.keys.map(&:to_s) - accepted - ignored
+        return if unknown.empty?
+
+        raise UnknownInputKeysError.new(unknown, accepted.sort)
+      end
+
       # Filter the handler's return value against the user's compiled output
       # schema. Any field/variant not visible to this user is stripped from
       # the result.

data/lib/mcp_authorization/tool.rb

@@ -215,9 +215,10 @@ module McpAuthorization
       # Create an anonymous MCP::Tool subclass with this user's schemas baked in.
       #
       # The materialized +call+ enforces the compiled schema at runtime:
-      # input params are stripped of unknown or permission-gated fields
-      # before reaching the handler, and the handler's return value is
-      # projected onto the user's output schema before being serialized.
+      # a top-level param outside the caller's input schema is rejected
+      # in-band (+UnknownInputKeysError+ → +isError: true+) before the
+      # handler runs, and the handler's return value is projected onto the
+      # user's output schema before being serialized.
       #: (untyped) -> Class?
       def materialize_for(server_context)
         defn = to_mcp_definition(server_context: server_context)
@@ -236,9 +237,16 @@ module McpAuthorization
 
           define_singleton_method(:call) do |server_context: nil, **params|
             effective_ctx = server_context || ctx
-            filtered_params = McpAuthorization::RbsSchemaCompiler.filter_input(
-              handler, params, server_context: effective_ctx
-            )
+            begin
+              filtered_params = McpAuthorization::RbsSchemaCompiler.filter_input(
+                handler, params, server_context: effective_ctx
+              )
+            rescue McpAuthorization::UnknownInputKeysError => e
+              # In-band tool error (isError: true), not a JSON-RPC failure, so the
+              # model reads the guidance. tool_name, not defn[:name]: a host may
+              # rename the materialized class, and the caller knows the new name.
+              next MCP::Tool::Response.new([{ type: "text", text: "#{tool_name}: #{e.message}" }], error: true)
+            end
             raw = handler.new(server_context: effective_ctx).call(**symbolize.call(filtered_params))
             result = McpAuthorization::RbsSchemaCompiler.filter_output(
               handler, raw, server_context: effective_ctx

data/lib/mcp_authorization/tool_registry.rb

@@ -24,22 +24,65 @@ module McpAuthorization
       end
 
       # All registered tool classes. Triggers eager loading on first access.
+      #
+      # Gated on "loading finished", not on "the array has entries" — see
+      # +ensure_tools_loaded!+ for why those must not be conflated.
       #: () -> Array[singleton(McpAuthorization::Tool)]
       def registered_tools
         tools = (@registered_tools ||= [])
-        ensure_tools_loaded! if tools.empty?
+        ensure_tools_loaded! unless @tools_loaded
         tools
       end
 
-      # Force-loads tool directories so tool classes self-register.
+      # Force-loads tool directories so tool classes self-register, then runs
+      # +config.tool_producers+ for tools the host generates at runtime.
+      #
+      # Deliberately lazy, and the ordering here is the contract:
+      #
+      # * *Producers run last*, inside this method, so a host cannot register a
+      #   generated tool ahead of the +tool_paths+ eager-load and suppress it.
+      #
+      # * *Producers run on a registry read, never from a boot callback.*
+      #   Generating tool classes means loading the code they derive from,
+      #   which in a Rails app pulls in a large share of the application. Doing
+      #   that from +config.to_prepare+ runs it during +:run_prepare_callbacks+,
+      #   which precedes +:eager_load!+ and +:finisher_hook+ — and +config.i18n+
+      #   is only copied onto +I18n+ from a railtie-level +after_initialize+.
+      #   Application code loaded that early sees an empty +I18n.load_path+, so
+      #   any class resolving a translation in its class body freezes
+      #   "Translation missing: ..." into validators and option lists
+      #   permanently. Deferring to first read sidesteps the whole ordering
+      #   question rather than asking each host to solve it.
+      #
+      # * *Producers re-run after +reset!+.* The Engine resets the registry on
+      #   every code reload; the next read repopulates it, producers included.
+      #
+      # +@tools_loaded+ tracks completion, and is set only after every producer
+      # has returned. It deliberately does NOT reuse "is +@registered_tools+
+      # non-empty?" as the signal, because a non-empty registry does not mean
+      # loading succeeded: +eager_load_tool_paths!+ registers the file-defined
+      # tools first, so by the time a producer raises the array is already
+      # populated — as it also is when a producer registers 40 tools and raises
+      # on the 41st. Guarding on that would make the failure loud exactly once
+      # and silent forever after, leaving a permanently incomplete surface. The
+      # contract is the opposite: a producer that raises fails *every* read until
+      # it is fixed. Re-running is safe — +register+ dedupes by identity and
+      # +eager_load_dir+ is a no-op on an already-loaded directory.
+      #
+      # The reentrancy guard lets a producer call back into the registry (to
+      # inspect what is already registered, say) without recursing forever.
       #: () -> void
       def ensure_tools_loaded!
-        return if @registered_tools&.any?
-        return unless defined?(Rails)
+        return if @tools_loaded
+        return if @loading_tools
 
-        McpAuthorization.config.tool_paths.each do |path|
-          full_path = Rails.root.join(path)
-          Rails.autoloaders.main.eager_load_dir(full_path) if File.directory?(full_path)
+        @loading_tools = true
+        begin
+          eager_load_tool_paths!
+          McpAuthorization.config.tool_producers.each(&:call)
+          @tools_loaded = true
+        ensure
+          @loading_tools = false
         end
       end
 
@@ -115,9 +158,30 @@ module McpAuthorization
       end
 
       # Clear the registry. Called by the Engine's reloader on code change.
+      # The next read reloads +tool_paths+ and re-runs +tool_producers+.
       #: () -> void
       def reset!
         @registered_tools = []
+        @loading_tools = false
+        @tools_loaded = false
+      end
+
+      private
+
+      # Probes for the methods actually called rather than the bare constant,
+      # matching Diagnostics' `defined?(Rails) && Rails.respond_to?(:env)`.
+      # A partially-loaded Rails (or an unrelated `Rails` module in a non-Rails
+      # process) satisfies `defined?` and then raises NoMethodError on `.root`,
+      # which would take `registered_tools` down with it — including for a host
+      # whose tools all come from `tool_producers` and need no autoloader.
+      #: () -> void
+      def eager_load_tool_paths!
+        return unless defined?(Rails) && Rails.respond_to?(:root) && Rails.respond_to?(:autoloaders)
+
+        McpAuthorization.config.tool_paths.each do |path|
+          full_path = Rails.root.join(path)
+          Rails.autoloaders.main.eager_load_dir(full_path) if File.directory?(full_path)
+        end
       end
     end
   end

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.7.1"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.9.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -128,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Rails engine for MCP tools with per-request schema discrimination