# Which invariants prevent capability shadowing in dynamically loaded agent tool registries: the trust-boundary mismatch between registration-time authorization and invocation-time resolution **Date of Record:** 2026 November 17 **Scope:** Applies to agent runtimes where tool/skill manifests are loaded, unloaded, or replaced at runtime (plugin directories, remote registries, hot-reload watchers) and where the resolver selects a callable by name rather than by immutable identity. Does not apply to statically linked, single-binary agents whose tool table is fixed at process start and whose tool names are checked at link time. ## Core Distinction The security-relevant distinction is not "trusted vs. untrusted tools" but **the identity a tool is authorized under versus the identity it is resolved under**. A registry typically performs authorization at *registration*: "is this manifest allowed to declare a tool named `read_file`?" It then performs dispatch at *invocation*: "give me the callable bound to the string `read_file`." These two operations occur at different times, against different data structures, and—critically—under different assumptions about name uniqueness. The non-obvious failure is that **name uniqueness is an invariant of the resolver, not of the registry**. A registry can legitimately hold two manifests that both declare `read_file`: one from the trusted core plugin, one from a user-scoped directory, one from a remotely fetched tool bundle. Neither registration is malformed; both pass per-manifest validation. The invariant that actually protects the system—*at most one live binding per name, and it is the one the policy engine approved*—is never checked because no component owns it. The registry proves "each manifest is well-formed"; the resolver proves "some callable exists for this name"; nobody proves "the callable returned is the one that was authorized." This is skill injection's quiet cousin. Prompt-injection manipulates the *arguments* to a legitimate tool; capability shadowing manipulates the *binding* so the arguments go to an attacker's callable that happens to share the name. The manifest signature is valid, the tool description is benign, and the audit log records a call to `read_file`—because at the string level, that is exactly what happened. ## What Was Observed In a hot-reload agent runtime, the loader watched a plugin directory and re-registered manifests on file change. The registry keyed manifests by `(plugin_id, tool_name)`, which is correct and collision-free. The resolver, however, keyed dispatch by `tool_name` alone, last-writer-wins. The two keyspaces drifted. The sequence that produced shadowing: 1. A trusted plugin registered `read_file` at startup; policy granted the capability to the `core` principal. 2. A lower-privilege plugin, permitted to register under its own namespace, declared a tool it also named `read_file` (no validation rejected this, because `(plugin_id, tool_name)` was unique). 3. A file-watcher reload re-inserted the lower-privilege manifest; the resolver's flat `dict[str, Callable]` overwrote the binding. 4. The agent, following its system prompt, invoked `read_file` on a path outside the sandbox. Authorization had already passed—it was checked against the *name* at plan time—and the callable that executed was the shadow's. Nothing in any single component's logs looked wrong. The registry logged a valid registration. The policy engine logged an approved capability for `read_file`. The resolver logged a successful lookup. The failure lived entirely in the gaps between them. A second, subtler variant appeared with *lazy* resolution: manifests were validated eagerly but callables were imported on first use. A plugin could register a benign manifest, pass validation, and only on first invocation import a module that monkeypatched or re-bound the name. Here the manifest was honest and the code was not; validation of the former told you nothing about the latter. ## Condition of Validity The invariant *"a name resolves to the callable that policy approved"* holds only when all of the following are true, and it silently fails when any one is violated: - **Resolution key equals authorization key.** If policy authorizes `(principal, tool_name)` but the resolver dispatches on `tool_name` alone, the keyspaces are misaligned and shadowing is possible. The only safe form is that the resolver's lookup key is a superset of the authorization key, and the full tuple is verified at dispatch. - **Registration and binding are atomic with respect to reload.** If a reload can insert a binding between the moment policy checks a name and the moment the agent invokes it (a time-of-check/time-of-use window), the check is stale. Hot-reload widens this window to the entire lifetime of the process. - **Lazy import is treated as untrusted code execution.** A manifest that validates is not a module that is safe to import. If resolution triggers `importlib`, the import must occur under the same sandbox and principal constraints as the eventual call, or the manifest check is decorative. - **Uniqueness is enforced at the resolver, not merely at the registry.** "No two live bindings share a dispatch key" must be a runtime assertion on the resolver's own data structure, not an emergent property hoped for from registry-side keying. The condition does *not* require that tool names be globally unique across all plugins—namespacing is a legitimate design. It requires only that whatever the resolver uses as its key is exactly what authorization bound, and that no reload can change the binding without re-running authorization. ## Decision Boundary The operational choice is between two postures, and the boundary between them is whether tool names are treated as **capabilities** or as **labels**. - Treat names as **labels** (namespaced, many-to-one allowed) when tools are supplied by a single trust domain and the resolver can afford to carry the full `(plugin_id, tool_name, version)` tuple through every call. Dispatch must then verify the tuple, and a bare-name lookup must be a hard error, not a convenience. - Treat names as **capabilities** (globally unique, one binding per name) when tools arrive from multiple trust domains and the agent's plan refers to tools by bare name. Then uniqueness must be enforced by the resolver as an invariant, reload must be forbidden from rebinding a name without a fresh authorization, and any second registration of an existing name must fail closed rather than overwrite. The failure occurs precisely at the seam: a system that *intends* names to be capabilities (bare-name plans, name-based policy) but *implements* them as labels (namespaced registry, flat resolver). If you cannot decide which posture you are in, you are in the shadowable one. The safe default when ambiguous is to reject any registration whose dispatch key already exists—fail closed on collision—rather than to resolve by precedence. ## Operational Effect The practical consequence is that **audit trails become unreliable exactly when you need them**. A shadowed call is logged under the legitimate name, attributed to the legitimate principal, and approved by a policy check that did pass. Post-incident reconstruction cannot distinguish a genuine `read_file` from a shadow's `read_file` by name alone; you must reconstruct the resolver's binding history, which is usually not persisted. The remediation is therefore not a patch to the resolver but an architectural invariant: persist binding identity (plugin, version, content hash) alongside every invocation record, and assert at dispatch that the resolved binding's identity matches the identity authorization approved. Where that assertion cannot be made, the call must raise rather than proceed—an unverifiable binding is indistinguishable from a hostile one. ## Enforcement Sketch The following encodes the invariant as a resolver that refuses to dispatch under an unverified or colliding binding, and fails closed on reload-time shadowing. ```python import hashlib from dataclasses import dataclass from typing import Callable, Optional class CapabilityShadowingError(RuntimeError): """Raised when a dispatch key would resolve to a binding that policy did not authorize.""" @dataclass(frozen=True) class Binding: plugin_id: str tool_name: str version: str content_hash: str callable: Callable authorized_principal: str @property def dispatch_key(self) -> str: return self.tool_name def identity(self) -> tuple[str, str, str]: return (self.plugin_id, self.version, self.content_hash) class SafeToolResolver: """Resolver that treats tool names as capabilities, not labels.""" def __init__(self) -> None: self._bindings: dict[str, Binding] = {} def register(self, binding: Binding, *, replace: bool = False) -> None: existing = self._bindings.get(binding.dispatch_key) if existing is None: self._bindings[binding.dispatch_key] = binding return if existing.identity() == binding.identity(): return # A different binding wants the same dispatch key. if not replace: raise CapabilityShadowingError( f"refusing to shadow {binding.dispatch_key!r}: " f"held by {existing.plugin_id}/{existing.version}, " f"attempted by {binding.plugin_id}/{binding.version}" ) # Replacement is only legal if it re-runs authorization. raise CapabilityShadowingError( f"hot-reload cannot rebind {binding.dispatch_key!r} without fresh " f"authorization; re-register under a new principal-approved identity" ) def resolve(self, tool_name: str, *, principal: str, approved_identity: tuple[str, str, str]) -> Callable: binding = self._bindings.get(tool_name) if binding is None: raise CapabilityShadowingError(f"no binding for {tool_name!r}") if binding.identity() != approved_identity: raise CapabilityShadowingError( f"binding identity mismatch for {tool_name!r}: " f"policy approved {approved_identity}, resolver holds {binding.identity()}" ) if binding.authorized_principal != principal: raise CapabilityShadowingError( f"principal {principal!r} not authorized for {tool_name!r}" ) return binding.callable def hash_tool_source(source: bytes) -> str: return hashlib.sha256(source).hexdigest() ```