reeve 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 225a220bbfd6168a26fdf67a816c8a580ca57ba996f97c7d1c9317755252d497
-  data.tar.gz: a5633fe99dedbc03796c82abf560eca68187fa783e5a9ceef1fb764b9a47d351
+  metadata.gz: 67bc82ca855e0385d021e54477cbcfcef697a1134d3c93e4fc073fea2ff3b748
+  data.tar.gz: 0c11093e604b6a056a23bec7ebd419620d4dd1780f93ff7e30fc8a08bdbd92d3
 SHA512:
-  metadata.gz: c9bccface22cb54d935720a927dd5aff7c61582403f6d0aeada860be4f178d110d4ac94801a84d6a15993c0abad8a6b14ee0c1058311809ddf5575ddb57d1741
-  data.tar.gz: e43b1e0a1fb8900a45cb998997b45152ab726b21961c2b86ea5dea0cc0adb3e0f9e015cf7aed8cdcd6e39aa28d7e9c827ff85d11653b8aa5fab769844b1cdecb
+  metadata.gz: 0524a6cd7376dc9cc8b7f2611d4a0a6a8b1fa81b6b5ff59ab662d3e5f5f313b4f47e7ad5b2d52d272da8bab1f1c19042ae937300beb382f57804f2fc72b77d3e
+  data.tar.gz: 4ead6c668edcde8b543c1e4ead9817e08015ecbf42adfbc34d44c5fa31426206284efb3ffdd88dad4cd983033be7708e256ac9cc2e5eb4758a6fc92f2ac14a19

data/CHANGELOG.md

@@ -4,6 +4,150 @@ All notable changes are recorded here. This project follows [Semantic
 Versioning](https://semver.org), with one rule specific to what it does — see
 [Versioning policy](#versioning-policy).
 
+## [0.5.0] - 2026-10-01
+
+Reeve protects the tools routed through it, and only those. A server that registers its
+tools as names and handler blocks can send some through `Reeve.invoke` and run the rest
+directly — and the direct ones are not unguarded, they are invisible: no denial, no scope,
+no ledger row, and nothing that says so. The compliance suite could not see them either,
+because it walks tools reeve was told about. A green run certified the subset reeve
+happened to know, and read exactly like a green run over the whole endpoint.
+
+**The audit-entry contract is unchanged at `2`, so no migration is required.** One new
+`rule` value, `unbound_tool`, can appear — only for a host that dispatches through an
+inventory.
+
+Behaviour changes worth reading before upgrading:
+
+- Both compliance suites have one more check, `EndpointCoverage`. Until `config.inventory`
+  is set it is **skipped** — pending in RSpec, a skip in Minitest — with a message saying
+  the endpoint was not verified. Nothing that passed before fails.
+- A `Report` now counts and prints skipped results (`8 checks, 7 passed, 0 failed, 1
+  skipped`, followed by `SKIP EndpointCoverage` and its reason). `passed?` is unchanged: a
+  skip is not a failure.
+- A multi-line check message is now indented as one block under its `FAIL` heading.
+
+**On Rails 7.0, keep `json` below 3.0.** json 3.0 dropped the `quirks_mode:` keyword that
+ActiveSupport 7.0 still passes to `JSON.generate`, so the ledger cannot serialize a row.
+Under the default `audit_failure_mode = :fail`, reeve fails closed: every invocation raises
+`Reeve::AuditWriteError` rather than running unrecorded — nothing goes unaudited, and
+nothing runs. Under `:warn`, every call runs and none is recorded. The defect is ActiveSupport's, not
+reeve's, and no reeve version works around it; pin `gem "json", "< 3"` until the
+application is on a Rails that supports json 3. Reeve's own CI pins it on the Ruby 3.0
+job for the same reason.
+
+### Added
+
+- **`Reeve::Inventory`** — the host's registered tool names, which of them route through
+  reeve and to which class, and which are exempt and why. Every part takes a value or a
+  callable, so a Rails initializer can declare it without autoloading application
+  constants. No MCP library involved: a list of names is the whole protocol.
+
+  - `#report` classifies every registered name as protected and guarded, routed but
+    unguarded, bypassing reeve, or exempted — plus anything the inventory names that the
+    server does not register, which is usually a rename that left the real name unbound.
+    The output names tools, classes and exemption reasons, never an argument, a principal
+    or a record, so it is safe in a CI log.
+  - `#verify!` raises `Reeve::IncompleteInventoryError`, carrying the report, unless every
+    registered name is guarded or exempt. For boot, a deploy step, or CI.
+  - `#dispatch(name, ...) { handler }` is the dispatch boundary. A routed name runs through
+    `Reeve.invoke`, with the handler block as the body; an exempt name runs as written; any
+    other name is treated as a tool with no guard — refused with the new `unbound_tool`
+    rule under `unguarded_tools = :deny`, or run unscoped with `guard: "none"` under
+    `:allow_with_warning` — and recorded either way. A host that dispatches through it
+    cannot have a tool that bypasses reeve.
+  - An exemption needs a non-empty reason, and is listed in every report, complete or not.
+
+- **`config.inventory`**, and **`Checks::EndpointCoverage`**, which compares a compliance
+  run against it. Passes only when the inventory is complete and the run covered all of
+  it; fails when the run claimed the whole endpoint and a registered tool bypasses reeve
+  or reaches it unguarded; skipped when no inventory is declared, or when
+  `compliance_tools` or `tools:` narrowed the run, naming what was left out. The
+  incremental path stays open, and a subset can no longer pass for the endpoint.
+
+- **Skipped results.** `Testing::Result.skipped`, `Result#skipped?`, `Report#skips` and
+  `Report#skipped?`. Only `EndpointCoverage` produces one.
+
+### Changed
+
+- The compliance suites' default population includes every class the inventory routes to.
+  A registry of blocks has no reason to `include Reeve::Guard` anywhere, so a routed class
+  with no guard would otherwise never reach `GuardDeclared`.
+
+## [0.4.0] - 2026-09-03
+
+Everything here came out of a second application integrating the gem — one that had put a
+handful of its MCP tools behind reeve and was about to guard its write tools next. Two
+defects surfaced from reviewing that work, and both were failures of the same kind: the
+gem reporting a guarantee it had not actually established.
+
+**The audit-entry contract is unchanged at `2`, so no migration is required.**
+
+Behaviour changes worth reading before upgrading:
+
+- A denied invocation now rolls the tool's work back. A guarded tool that writes and is
+  then refused used to leave the write behind.
+- A guarded tool that raises after writing now has that write rolled back too.
+- The compliance suite now reports tools that never declared a guard, so a suite that
+  passed before may legitimately fail now. That is the fix, not a regression — set
+  `config.compliance_tools` to what you have certified so far.
+
+### Fixed
+
+- **The compliance suite can see a tool that has no guard.** It walked the guard registry,
+  which holds one entry per `guard_with` — so every subject it checked had a guard by
+  construction, and `GuardDeclared`, the check whose whole job is naming tools that lack
+  one, could not fail. An application with three guarded tools and one that was forgotten
+  reported `4 checks, 4 passed`. The gem's own quickstart demonstrated this: it ships a
+  deliberately unguarded tool and then asserted that the compliance run passed.
+
+  Tools are now recorded when they include `Reeve::Guard`, declared or not — through
+  inheritance too, so an adapter that includes the DSL into a base class once (fast-mcp)
+  no longer hides every tool built on it. `Reeve.registry.unguarded_tool_classes` is the
+  worklist. A base class that carries the DSL for its subclasses declares itself with
+  `reeve_abstract!` rather than being guessed at: inferring "anything with a subclass is a
+  base" would silently drop a real tool from the run the moment someone subclassed it.
+
+  **Reeve can only see tools that reached it.** An MCP server dispatching tools reeve was
+  never told about is still invisible to it — pass `tools:` to certify the real inventory.
+
+- **A denied invocation no longer leaves the host's data changed.** The envelope
+  authorizes before the tool runs, with the model class as the subject because no record
+  exists yet, and scopes the return value afterwards. A write tool lives between those two
+  points: it fetched a record, changed it, and only then was refused. The caller saw
+  `out_of_scope_record`, the ledger recorded a denial — and the row in the database had
+  already been rewritten by a principal who could not see it. A `deny` that follows a
+  committed write is not a partial guarantee, it is a false statement in the artifact the
+  ledger exists to be.
+
+  The tool body now runs in a transaction and a scope denial rolls it back. `requires_new`
+  makes it a savepoint, so a transaction the host opened around the invocation is left
+  alone — the rollback reaches the tool's work and stops there. Measured overhead is at or
+  below noise on a read-only call.
+
+  Two consequences worth knowing:
+
+  - A tool that **writes and then raises** now has that write rolled back too. It was
+    already recorded as `tool_error`; the data now matches what the ledger said.
+  - A host with no ActiveRecord, or with the library loaded but no connection, keeps the
+    previous behaviour — there is nothing to roll back, and neither should be made to fail.
+
+### Added
+
+- **`config.compliance_tools`** — which tools the suite certifies, as an array or a
+  callable, defaulting to every tool reeve knows about. A retrofit is the normal state of
+  an application adopting this, and now that unguarded tools are reported, one that has
+  guarded three of thirty has a red build it cannot honestly turn green. A build expected
+  to be red is a build nobody reads. Narrowing the list states what has been certified —
+  a claim that can go green and stay green as the list grows.
+
+- **`authorize!(record)`** inside a tool body — asks the declared policy about one record
+  and returns it, raising `DeniedError` if the policy says no. For the part of a tool a
+  rollback cannot reach: a sent email, a webhook, a written file. A denial raised this way
+  carries the policy's own rule into the ledger rather than being filed as `tool_error`,
+  and names no record, so a refusal and a record that does not exist still read the same
+  (FR-006).
+
 ## [0.3.0] - 2026-08-17
 
 Three of the limitations 0.1.0 shipped knowingly are now closed, and the audit-entry
@@ -268,4 +412,4 @@ is for:
 - Adding a nullable ledger column is minor and leaves the audit-entry contract version
   alone. Removing or renaming a column, or changing what a value means, is major and bumps
   it.
-- The audit-entry contract version is `1`.
+- The audit-entry contract version is `2`.

data/README.md

@@ -7,7 +7,7 @@ A Ruby gem that makes it safe for a Rails application to expose MCP tools to AI
 declarative per-record authorization, an append-only audit ledger, and a testing kit that
 proves both hold.
 
-> **Status: 0.3.0.** Read the known limitations in
+> **Status: 0.5.0.** Read the known limitations in
 > [CHANGELOG.md](CHANGELOG.md) before adopting it — particularly the one about a
 > transaction wrapped around an invocation, if your application wraps requests in one.
 
@@ -119,6 +119,42 @@ end
 Reaching for `Invoice.sum(:cents)` there is denied with `unscoped_derived_result`. The
 guarantee is structural, not a matter of remembering.
 
+## Tools that write
+
+A denial means nothing happened. Authorization runs before the tool, but with the model
+class as its subject — for an index-style check there is no record yet — so the per-record
+answer only arrives once the tool has returned something to scope. A write tool sits
+between those two points:
+
+```ruby
+def call(id:, number:)
+  invoice = Invoice.find(id)        # unscoped fetch
+  invoice.update!(number: number)   # ...then a write
+  invoice
+end
+```
+
+The tool body runs in a transaction, and a scope denial rolls it back. Someone else's
+record is refused *and* unchanged, and the ledger's `deny` is a true statement about the
+database. A transaction the host opened around the invocation is untouched — the rollback
+reaches the tool's work and stops there.
+
+What a rollback cannot reach is anything that was never in the transaction. A tool that
+sends an email, calls a webhook or writes a file before it knows whether it is allowed to
+must ask first:
+
+```ruby
+def call(id:, to:)
+  invoice = authorize!(Invoice.find(id))   # raises DeniedError if the policy says no
+  InvoiceMailer.reminder(invoice, to).deliver_now
+  invoice
+end
+```
+
+`authorize!` asks the declared policy about one record and returns it, so it reads inline.
+The denial carries the policy's own rule into the ledger, and names no record — a refusal
+and a record that does not exist have to read the same.
+
 ## Every call leaves a trace
 
 One append-only row per invocation, allowed or denied, naming the agent, the principal, the
@@ -191,7 +227,27 @@ abort report.to_s unless report.passed?
 ```
 
 `alice` and `bob` are two fixture principals with disjoint records — that disjointness is
-what makes a shared record identifier proof of a leak. As a Rails rake task:
+what makes a shared record identifier proof of a leak.
+
+**The suite walks every tool that included `Reeve::Guard`, not only the ones that declared
+a guard.** A tool that forgot `guard_with` is the one worth finding, and it is absent from
+the guard registry by definition — so a run that only inspected guarded tools reported
+all-green on precisely the application that had a problem.
+
+Mid-retrofit that means a red build, which is honest but unreadable if it stays red for
+weeks. Say what you have certified so far, and grow the list:
+
+```ruby
+config.compliance_tools = -> { [InvoiceSearchTool, InvoiceShowTool] }
+```
+
+Reeve can only see tools that reached it. If your MCP server dispatches tools Reeve has
+never been told about — a custom controller with its own registry — declare the server's
+real inventory ([below](#every-tool-the-endpoint-dispatches)), or the run certifies the
+subset Reeve happens to know. Until you do, the suite says so: `EndpointCoverage` is
+reported as skipped, never as passed.
+
+As a Rails rake task:
 
 ```ruby
 # lib/tasks/reeve.rake
@@ -322,6 +378,91 @@ Reeve::Checks.run_all(
 That is the whole integration: one call site, your auth untouched, and the same three
 guarantees the fast-mcp adapter gets.
 
+## Every tool the endpoint dispatches
+
+Reeve protects the tools routed through it, and only those. A server that registers tools
+as names and handler blocks can send some through `Reeve.invoke` and run the rest directly
+— and the direct ones are not unguarded, they are invisible: no denial, no scope, no ledger
+row, and nothing that says so. Deny-by-default cannot deny a call it never sees.
+
+`Reeve::Inventory` makes the server's own list of names the thing that gets checked:
+
+```ruby
+# config/initializers/reeve.rb
+McpInventory = Reeve::Inventory.new(
+  registered: -> { McpServer.tool_names },
+  routed: -> { { "search_invoices" => InvoiceSearchTool, "get_invoice" => InvoiceShowTool } },
+  exemptions: { "healthcheck" => { reason: "returns no application data" } }
+)
+
+Reeve.configure { |config| config.inventory = McpInventory }
+```
+
+Each part takes a value or a callable. Callables are read when asked, so the initializer
+neither autoloads application constants nor runs before the server has registered its
+tools.
+
+```text
+reeve inventory: 4 registered
+  2 protected and guarded
+  0 routed through reeve but unguarded
+  1 bypasses reeve
+  1 exempted
+coverage: incomplete
+
+BYPASS export_invoices
+  registered with the server but neither routed through reeve nor exempted — route it to
+  a guarded tool, or exempt it with a reason
+
+EXEMPT healthcheck
+  returns no application data
+```
+
+The report names tools, classes and exemption reasons — never an argument, a principal or
+a record — so it is safe to print in CI. An exemption without a reason is refused, and one
+with a reason is listed every time, complete or not.
+
+**Fail boot or CI on a gap:**
+
+```ruby
+McpInventory.verify!   # raises Reeve::IncompleteInventoryError, carrying the report
+```
+
+**Dispatch through it, and a bypass stops being possible:**
+
+```ruby
+def call_tool
+  name = params.dig(:params, :name)
+  arguments = params.dig(:params, :arguments).to_h.symbolize_keys
+
+  result = McpInventory.dispatch(name, arguments: arguments,
+                                       agent: { id: request.headers["X-MCP-Client"] }) do
+    McpServer.handlers.fetch(name).call(arguments)
+  end
+
+  render json: { jsonrpc: "2.0", id: params[:id], result: serialize(result) }
+rescue Reeve::DeniedError => e
+  render json: { jsonrpc: "2.0", id: params[:id],
+                 error: { code: -32_003, message: e.message } }
+end
+```
+
+- A **routed** name runs through `Reeve.invoke` under its class's guard, with the handler
+  block as the body. A registry of blocks needs one guarded class per tool to name its
+  policy, and nothing else — the block still does the work, and what it returns is scoped.
+  Handlers dispatched this way should not call `Reeve.invoke` themselves.
+- An **exempt** name runs the block as written.
+- **Any other name** is a tool with no guard, and `unguarded_tools` decides: refused with
+  `unbound_tool` under `:deny`, the default; run unscoped and recorded with `guard: "none"`
+  under `:allow_with_warning`. Recorded either way, so a name the inventory missed lands on
+  the same ledger worklist as an unguarded class.
+
+**In the compliance suite,** `EndpointCoverage` compares the run against the inventory. It
+passes only when every registered tool is guarded or exempt and the run covered all of
+them. It fails when the run claimed the whole endpoint and something bypasses Reeve. A run
+narrowed by `compliance_tools` is reported as a subset — skipped, naming what it left out —
+so a retrofit stays green without passing for complete coverage.
+
 Policies are plain objects unless you want Pundit (`authorize` and `scope`, two methods).
 The ledger is an ActiveRecord table unless you supply your own recorder. Records are
 ActiveRecord unless they are not — a plain object with an `id` works.

data/lib/reeve/authorization/guard.rb

@@ -16,10 +16,22 @@ module Reeve
   module Guard
     def self.included(base)
       base.extend(ClassMethods)
+      Reeve.registry.note(base)
     end
 
     # Class-level DSL. See contracts/tool-dsl.md.
     module ClassMethods
+      # Declares this class a base rather than a tool: it carries the DSL so its
+      # subclasses have it, and the compliance suite should not ask whether it is guarded.
+      #
+      #   class ApplicationTool
+      #     include Reeve::Guard
+      #     reeve_abstract!
+      #   end
+      def reeve_abstract!
+        Reeve.registry.mark_abstract(self)
+      end
+
       # Declares which policy governs this tool. Absence is not neutral: a tool with no
       # declaration is denied by the envelope (FR-002, FR-004).
       def guard_with(policy, action: nil)
@@ -59,8 +71,16 @@ module Reeve
 
       # A subclass of a guarded tool is itself guarded, and is registered under its own
       # name so the envelope — which only ever has a name — can find it.
+      #
+      # The note comes first and unconditionally, because a subclass of an *unguarded*
+      # base is the case worth catching: subclasses acquire the DSL without ever running
+      # `included`, so without this every fast-mcp tool would be invisible to the
+      # compliance suite — that adapter includes Guard into `FastMcp::Tool` once and lets
+      # inheritance do the rest.
       def inherited(subclass)
         super
+        Reeve.registry.note(subclass)
+
         declaration = reeve_guard
         # An anonymous subclass has no name to be looked up by; it still inherits the
         # declaration through the ancestry walk in Registry#for_class.
@@ -93,5 +113,38 @@ module Reeve
 
       Authorization::Scoper.scoped_relation(state, model_or_relation)
     end
+
+    # Asks the declared policy about one record, before the tool acts on it. Returns the
+    # record so it reads inline; raises +DeniedError+ if the policy says no.
+    #
+    #   def call(id:, to:)
+    #     invoice = authorize!(Invoice.find(id))
+    #     InvoiceMailer.reminder(invoice, to).deliver_now
+    #     invoice
+    #   end
+    #
+    # The envelope authorizes before the tool runs and scopes what it returns, and between
+    # those two points a tool can do things neither of them can reach. A rolled-back write
+    # leaves no trace; a sent email does. `scoped(...)` is the answer when a tool can work
+    # from a relation; this is the answer when it cannot — when the tool holds one record
+    # and is about to do something to the world with it.
+    #
+    # The denial carries the policy's own rule, so the ledger names what refused rather
+    # than reporting the tool as broken. It names no record: an out-of-scope record and a
+    # record that does not exist have to be indistinguishable (FR-006), and a tool that
+    # reached this line has already fetched the record it must not talk about.
+    def authorize!(record)
+      state = Authorization::Current.state
+      raise Error, "authorize!(...) may only be called inside a guarded invocation" if state.nil?
+
+      decision = state.adapter.authorize(
+        principal: state.context.principal, policy: state.declaration.policy,
+        action: state.declaration.action, record: record
+      )
+      return record if decision.allowed?
+
+      raise DeniedError.from(decision, tool_name: state.context.tool_name,
+                                       principal_id: state.context.principal_id)
+    end
   end
 end

data/lib/reeve/authorization/registry.rb

@@ -13,10 +13,49 @@ module Reeve
 
       def initialize
         @declarations = {}
+        @known = {}     # every class that included Guard, declared or not
+        @abstract = {}  # bases others inherit from; not tools themselves
         @name_index = nil # invalidated on every add; see #name_index
         @mutex = Mutex.new
       end
 
+      # A class that included the DSL. Recorded whether or not it goes on to declare
+      # anything, because a tool that forgot `guard_with` is precisely the one worth
+      # finding, and it is absent from `@declarations` by definition.
+      def note(tool_class)
+        @mutex.synchronize { @known[tool_class] = true }
+        tool_class
+      end
+
+      # A base others inherit from — `FastMcp::Tool`, or a host's own `ApplicationTool`.
+      # It acquires the DSL so its subclasses have it, and it is not itself a tool, so
+      # asking whether it declared a guard is a question with no useful answer.
+      #
+      # Explicit rather than inferred. The obvious heuristic — "a class something else
+      # inherits from is a base" — silently drops a real tool from the compliance run the
+      # moment someone subclasses it, and a check that quietly stops checking is the
+      # failure mode this whole file exists to prevent.
+      def mark_abstract(tool_class)
+        @mutex.synchronize { @abstract[tool_class] = true }
+        tool_class
+      end
+
+      def abstract?(tool_class)
+        @abstract.key?(tool_class)
+      end
+
+      # Every tool reeve knows about: the ones that declared a guard and the ones that
+      # only included the DSL. This is what the compliance suite walks, so that "all
+      # checks passed" cannot mean "we only looked at the tools that were already safe".
+      def tool_classes
+        (@known.keys | @declarations.keys).reject { |klass| abstract?(klass) }
+      end
+
+      # The worklist.
+      def unguarded_tool_classes
+        tool_classes.reject { |klass| @declarations.key?(klass) }
+      end
+
       # The DSL's `guard_with`. Declaring twice on one class is a mistake worth naming;
       # `add` is the quiet path used by `redact` and by inheritance, which refine an
       # existing declaration rather than compete with it.
@@ -74,6 +113,8 @@ module Reeve
       def remove(tool_class)
         @mutex.synchronize do
           @declarations.delete(tool_class)
+          @known.delete(tool_class)
+          @abstract.delete(tool_class)
           @name_index = nil
         end
       end
@@ -81,6 +122,8 @@ module Reeve
       def reset!
         @mutex.synchronize do
           @declarations = {}
+          @known = {}
+          @abstract = {}
           @name_index = nil
         end
       end

data/lib/reeve/authorization.rb

@@ -42,7 +42,7 @@ module Reeve
           registry: registry,
           authorizer: Authorization::Authorizer.new,
           scoper: Authorization::Scoper.new,
-          config: configuration_for(principal)
+          config: config.with_principal(principal)
         ) { body ? body.call : run(tool, arguments) }
       end
     end
@@ -62,15 +62,5 @@ module Reeve
 
       Authorization::Declaration.new(tool_class: klass, policy: nil, action: :index).tool_name
     end
-
-    # An explicitly supplied principal is just a resolver that returns it. Routing it
-    # through the same resolution step rather than around it keeps one answer to "where
-    # did this principal come from" — the envelope still resolves, records and denies
-    # identically, and a nil passed in still denies with `no_principal`.
-    def configuration_for(principal)
-      return config if principal == :unset
-
-      config.dup.tap { |scoped| scoped.principal_resolver = ->(_context) { principal } }
-    end
   end
 end

data/lib/reeve/configuration.rb

@@ -24,7 +24,7 @@ module Reeve
     SETTINGS = %i[
       principal_resolver unguarded_tools audit_failure_mode redact_arguments
       max_recorded_ids policy_adapter default_action audit_recorder logger
-      compliance_principals
+      compliance_principals compliance_tools inventory
     ].freeze
 
     attr_reader(*SETTINGS)
@@ -40,11 +40,57 @@ module Reeve
       @audit_recorder     = nil
       @logger             = nil
       @compliance_principals = nil
+      @compliance_tools = nil
+      @inventory = nil
+    end
+
+    # The host's whole tool inventory (Reeve::Inventory). Optional. Setting it is what lets
+    # the compliance suite say whether it covered the endpoint or only the tools reeve
+    # happened to be told about.
+    def inventory=(inventory)
+      unless inventory.nil? || inventory.is_a?(Inventory)
+        raise ArgumentError, "inventory must be a Reeve::Inventory, got #{inventory.inspect}"
+      end
+
+      @inventory = inventory
+    end
+
+    # This configuration with the principal fixed for one invocation.
+    #
+    # An explicitly supplied principal is just a resolver that returns it. Routing it
+    # through the same resolution step rather than around it keeps one answer to "where
+    # did this principal come from" — the envelope still resolves, records and denies
+    # identically, and a nil passed in still denies with `no_principal`.
+    def with_principal(principal)
+      return self if principal == :unset
+
+      dup.tap { |scoped| scoped.principal_resolver = ->(_context) { principal } }
     end
 
     # Two fixture principals with disjoint records — the only host setup the compliance
     # suite needs (contracts/testing-kit.md). A callable rather than a value, because in a
     # Rails test suite the fixtures do not exist yet when the helper is loaded.
+    # Which tools the compliance suite certifies. Defaults to every tool reeve knows
+    # about, which is the answer a finished application wants.
+    #
+    # A host part-way through a retrofit needs the other answer. Once the suite reports
+    # unguarded tools — which is the whole point of it — an application with thirty tools
+    # and three guarded ones has a red build it cannot honestly turn green, and a red
+    # build that is expected to be red stops being read. Narrowing the list says "these
+    # are the ones I have certified", which is a claim that can go green and then stay
+    # green as the list grows.
+    #
+    #   config.compliance_tools = -> { [InvoiceSearchTool, InvoiceShowTool] }
+    def compliance_tools=(tools)
+      unless tools.nil? || tools.respond_to?(:call) || tools.is_a?(Array)
+        raise ArgumentError,
+              "compliance_tools must be an Array or a callable returning one, " \
+              "got #{tools.inspect}"
+      end
+
+      @compliance_tools = tools
+    end
+
     def compliance_principals=(principals)
       unless principals.nil? || principals.respond_to?(:call) || principals.is_a?(Array)
         raise ArgumentError,

data/lib/reeve/decision.rb

@@ -18,6 +18,10 @@ module Reeve
     # ledger records it as a deny — the trace of a call that blew up is the one most
     # worth having (R5).
     TOOL_ERROR              = "tool_error"
+    # A name dispatched through an Inventory that neither routes it through reeve nor
+    # exempts it. Not `no_guard_declared`: there may be no class to declare one on, and
+    # the fix is in the inventory.
+    UNBOUND_TOOL            = "unbound_tool"
 
     # The one reserved *allow* rule: a tool with no guard, permitted because the host
     # opted into :allow_with_warning. Kept out of RESERVED_RULES, which names deny paths.
@@ -33,7 +37,8 @@ module Reeve
       UNSCOPED_DERIVED_RESULT,
       OUT_OF_SCOPE_RECORD,
       AUDIT_WRITE_FAILED,
-      TOOL_ERROR
+      TOOL_ERROR,
+      UNBOUND_TOOL
     ].freeze
 
     OUTCOMES = %i[allow deny].freeze

data/lib/reeve/errors.rb

@@ -57,6 +57,19 @@ module Reeve
     end
   end
 
+  # Raised by Inventory#verify! when a registered tool is not protected: routed through
+  # reeve with no guard, not routed at all, or declared in the inventory but not registered
+  # with the server. The message is the whole report — tool names, classes and exemption
+  # reasons, never an argument, a principal or a record.
+  class IncompleteInventoryError < Error
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      super(report.to_s)
+    end
+  end
+
   # Raised when the ledger write fails and audit_failure_mode is :fail (FR-012).
   #
   # It carries a rule like any other denial, because the failure is not recorded anywhere

data/lib/reeve/integrations/fast_mcp/tool_extension.rb

@@ -37,7 +37,11 @@ module Reeve
       # Idempotent: requiring "reeve/fast_mcp" twice must not stack two envelopes around
       # the same call.
       def install!(tool_base = ::FastMcp::Tool)
-        tool_base.include(Reeve::Guard) unless tool_base.include?(Reeve::Guard)
+        unless tool_base.include?(Reeve::Guard)
+          tool_base.include(Reeve::Guard)
+          # FastMcp::Tool carries the DSL for its subclasses; it is not itself a tool.
+          tool_base.reeve_abstract!
+        end
 
         unless tool_base.singleton_class.include?(Inheritance)
           tool_base.singleton_class.prepend(Inheritance)