Mcp(fix[safety]): Name the tier a gated tool needs

Calling a tool above the server's `LIBTMUX_SAFETY` tier reported
`Unknown tool: 'kill_pane'` — the server denying that its own gated
tool exists. An agent told a tool is absent reports the capability as
missing instead of naming the setting that enables it.

Two gates were intended and only one worked. FastMCP's native
`disable()` enforces the tier; `SafetyMiddleware` was meant to explain
it. `get_tool()` answers `None` for a disabled tool, so the guard
reading `if tool and not allowed` never ran for precisely the tools it
was written for, and dispatch raised `NotFoundError` instead. Off-tier
names now resolve against `_list_tools()`, which retains disabled tools
with their tags.

The batch wrappers carried the same defect through a second call path:
`_get_allowed_tool_tier` also read `get_tool` and raised "Unknown tool"
on `None`, so a gated tool and a misspelled one produced byte-identical
rows. It hands the operation on instead of duplicating the lookup —
nested calls already run with `run_middleware=True`, so one source of
truth decides which of the two it is.

The message also hardcoded `LIBTMUX_SAFETY=destructive` for every
denial, so a readonly server answered a `send_keys` call by advising the
strongest tier — telling a user to grant `kill_server` rights in order
to type into a pane. Denials now name the required tier and the tier in
force.

Restores an audit property the middleware ordering is built around: a
tier denial must raise inside `SafetyMiddleware` so `AuditMiddleware`,
sitting outside it, records it as a denial. While the denial never
fired, blocked calls were audited as unknown-tool errors.

`on_call_tool` now fails closed with no FastMCP context. It previously
fell through to the tool, which is fail-open in a gate whose top tier
includes `kill_server`, and was masked only because the native gate made
the dispatch fail anyway.

The existing suite documented the dead path rather than testing it, so
921 passing tests never called a gated tool end to end. Adds that
coverage per tier and through the batch wrapper, plus a contract test
pinning the private `_list_tools()` behavior the explanation depends on.

Author: tony

CHANGES

@@ -6,6 +6,55 @@
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### A gated tool now says which tier it needs
+
+Calling a tool above the server's `LIBTMUX_SAFETY` tier reported
+`Unknown tool: 'kill_pane'` — the server denying that its own gated tool
+exists. An agent told a tool is absent reports the capability as missing
+rather than naming the setting that enables it.
+
+Off-tier calls now name both the tier the tool requires and the tier in
+force:
+
+```
+Tool 'kill_pane' requires safety level 'destructive', but this server is
+running at 'mutating'. Restart it with LIBTMUX_SAFETY=destructive to
+enable it.
+```
+
+The message previously hardcoded `LIBTMUX_SAFETY=destructive` for every
+denial, so a `readonly` server answered a `send_keys` call by advising
+the strongest tier — telling a user to grant `kill_server` rights in
+order to type into a pane. The tier named is now the one the tool
+actually needs.
+
+Two gates were always intended here, and only one of them worked.
+FastMCP's native `disable()` enforces the tier; `SafetyMiddleware` was
+meant to explain it. Because `get_tool()` answers `None` for a disabled
+tool, the middleware's `if tool and not allowed` guard never ran for the
+tools it was written for. Off-tier names now resolve against the full
+registry, which retains disabled tools and their tags.
+
+Denials also reach the audit log as denials again. The server's
+middleware ordering is built so that a tier denial raises inside
+`SafetyMiddleware` and is recorded by `AuditMiddleware` outside it;
+while the denial never fired, a blocked call was audited as an
+unknown-tool error instead.
+
+The batch wrappers carried the same defect through a second call path:
+`_get_allowed_tool_tier` also read `get_tool` and raised "Unknown tool"
+on `None`, so a gated tool and a misspelled one produced byte-identical
+rows. It now hands the operation on instead of duplicating the lookup —
+the nested call runs through the middleware, which names the tier for a
+gated tool while a real typo still gets FastMCP's own error.
+
+`SafetyMiddleware.on_call_tool` additionally fails closed when no
+FastMCP context is present. It previously fell through to the tool,
+which was fail-open in a gate whose top tier includes `kill_server`, and
+was masked only because the native gate made the dispatch fail anyway.
+
 ### Documentation
 
 #### opencode joins the install picker

src/libtmux_mcp/middleware.py

@@ -51,25 +51,53 @@
     ExpectedToolError,
 )
 
+logger = logging.getLogger(__name__)
+
 _TIER_LEVELS: dict[str, int] = {
     TAG_READONLY: 0,
     TAG_MUTATING: 1,
     TAG_DESTRUCTIVE: 2,
 }
 
+#: Reverse of :data:`_TIER_LEVELS`, so a middleware configured with an
+#: unrecognized tier can still *name* the tier it fell back to.
+_LEVEL_TIERS: dict[int, str] = {level: tier for tier, level in _TIER_LEVELS.items()}
+
+
+def _highest_tier(tags: t.Collection[str]) -> str | None:
+    """Return the highest safety tier named in *tags*, or None if untagged."""
+    found = [tier for tier in _TIER_LEVELS if tier in tags]
+    if not found:
+        return None
+    return max(found, key=lambda tier: _TIER_LEVELS[tier])
+
 
 class SafetyMiddleware(Middleware):
-    """Gate tools by safety tier.
+    """Explain tier denials that ``_enable_allowed_tools`` enforces.
+
+    FastMCP's native ``disable()`` is the enforcement gate and holds
+    even for a call that skips the middleware chain. It also makes
+    ``get_tool()`` answer **None**, so FastMCP reports an off-tier call
+    as ``Unknown tool`` -- the server denying its own gated tool exists.
+    This gate names the required tier instead, resolving such names
+    against :meth:`_tier_snapshot` (the registry keeps disabled tools).
+
+    Denials must raise *here* so :class:`AuditMiddleware`, which sits
+    outside, records them as denials rather than unknown-tool errors.
 
     Parameters
     ----------
     max_tier : str
-        Maximum allowed tier. One of ``TAG_READONLY``, ``TAG_MUTATING``,
-        or ``TAG_DESTRUCTIVE``.
+        Maximum allowed tier. Unrecognized values fall back to
+        ``TAG_READONLY``.
     """
 
     def __init__(self, max_tier: str = TAG_MUTATING) -> None:
         self.max_level = _TIER_LEVELS.get(max_tier, 0)
+        #: Normalized tier name, so a denial reports where the server
+        #: stands rather than echoing an unrecognized env value back.
+        self.max_tier = _LEVEL_TIERS[self.max_level]
+        self._tier_by_tool: dict[str, str] | None = None
 
     def _is_allowed(self, tags: set[str]) -> bool:
         """Return True if the tool's tags fall within the allowed tier.
@@ -84,6 +112,55 @@ def _is_allowed(self, tags: set[str]) -> bool:
                     return False
         return found_tier
 
+    def _denial_message(self, tool_name: str, required_tier: str | None) -> str:
+        """Name the required tier and the active one.
+
+        The message this replaced hardcoded ``destructive`` for every
+        denial, so a readonly server answered ``send_keys`` by advising
+        kill_server rights in order to type into a pane.
+        """
+        if required_tier is None:
+            return (
+                f"Tool {tool_name!r} declares no safety tier and is blocked. "
+                "This is a bug in the server, not a configuration problem; "
+                "please report it."
+            )
+        return (
+            f"Tool {tool_name!r} requires safety level {required_tier!r}, but "
+            f"this server is running at {self.max_tier!r}. Restart it with "
+            f"LIBTMUX_SAFETY={required_tier} to enable it."
+        )
+
+    async def _tier_snapshot(self, fastmcp: t.Any) -> dict[str, str]:
+        """Map every registered tool name to its tier, disabled included.
+
+        Built once. ``_list_tools()`` is FastMCP-private, so a failure
+        degrades to an empty map: the call then falls through to the
+        stock ``NotFoundError``, losing the explanation but nothing
+        else. ``tests/test_server.py`` pins the behavior so a fastmcp
+        bump fails in CI rather than silently reverting this gate.
+        """
+        if self._tier_by_tool is not None:
+            return self._tier_by_tool
+
+        snapshot: dict[str, str] = {}
+        try:
+            registered = await fastmcp._list_tools()
+        except Exception:
+            logger.warning(
+                "safety tier snapshot unavailable; off-tier calls will "
+                "report 'unknown tool'",
+                exc_info=True,
+            )
+        else:
+            for tool in registered:
+                tier = _highest_tier(tool.tags)
+                if tier is not None:
+                    snapshot[tool.name] = tier
+
+        self._tier_by_tool = snapshot
+        return snapshot
+
     async def on_list_tools(
         self,
         context: MiddlewareContext,
@@ -98,16 +175,36 @@ async def on_call_tool(
         context: MiddlewareContext,
         call_next: t.Any,
     ) -> t.Any:
-        """Block execution of tools above the safety tier."""
-        if context.fastmcp_context:
-            tool = await context.fastmcp_context.fastmcp.get_tool(context.message.name)
-            if tool and not self._is_allowed(tool.tags):
-                msg = (
-                    f"Tool '{context.message.name}' is not available at the "
-                    f"current safety level. Set LIBTMUX_SAFETY=destructive "
-                    f"to enable destructive tools."
+        """Block execution of tools above the safety tier.
+
+        Fail-closed except for a name the registry has never heard of,
+        which is a typo and deserves FastMCP's own ``NotFoundError``.
+        """
+        tool_name = context.message.name
+
+        if context.fastmcp_context is None:
+            # No registry to consult: deny, since the top tier includes
+            # kill_server.
+            msg = (
+                f"Tool {tool_name!r} was called without a FastMCP context, so "
+                "its safety tier cannot be verified. Call it through MCP."
+            )
+            raise ExpectedToolError(msg)
+
+        fastmcp = context.fastmcp_context.fastmcp
+
+        tool = await fastmcp.get_tool(tool_name)
+        if tool is not None:
+            if not self._is_allowed(tool.tags):
+                raise ExpectedToolError(
+                    self._denial_message(tool_name, _highest_tier(tool.tags))
                 )
-                raise ExpectedToolError(msg)
+            return await call_next(context)
+
+        # Invisible to ``get_tool``: gated by tier, or nonexistent.
+        gated_tier = (await self._tier_snapshot(fastmcp)).get(tool_name)
+        if gated_tier is not None:
+            raise ExpectedToolError(self._denial_message(tool_name, gated_tier))
         return await call_next(context)
 
 

src/libtmux_mcp/server.py

@@ -436,8 +436,11 @@ def _enable_allowed_tools() -> None:
     if _mcp_visibility_configured:
         return
 
-    # Use FastMCP's native visibility system as primary gate,
-    # with the SafetyMiddleware as a secondary layer for clear error messages.
+    # This is the ENFORCEMENT gate: it holds even for a call that skips
+    # the middleware chain (``call_tool`` accepts
+    # ``run_middleware=False``). ``SafetyMiddleware`` is the
+    # EXPLANATION gate -- disabling makes ``get_tool`` answer None, so
+    # FastMCP would otherwise report a gated tool as ``Unknown tool``.
     allowed_tags = {TAG_READONLY}
     if _safety_level in {TAG_MUTATING, TAG_DESTRUCTIVE}:
         allowed_tags.add(TAG_MUTATING)

src/libtmux_mcp/tools/batch_tools.py

@@ -125,8 +125,14 @@ async def _get_allowed_tool_tier(
 
     tool = await fastmcp.get_tool(operation.tool)
     if tool is None:
-        msg = f"Unknown tool: {operation.tool!r}"
-        raise ExpectedToolError(msg)
+        # None means nonexistent OR disabled by tier, so raising
+        # "Unknown tool" here denied that a gated tool exists. Hand it
+        # on instead: the nested call runs with ``run_middleware=True``,
+        # letting ``SafetyMiddleware`` name the tier and FastMCP still
+        # raise ``NotFoundError`` for a typo. Nothing is skipped --
+        # visibility follows tier tags, so an invisible tool is
+        # off-tier by construction and is denied before these checks.
+        return
 
     # ``max_tier`` is a CEILING, so a readonly tool is reachable through
     # every batch wrapper, not only the readonly one. The batch loop is