# How does an instance detect registry-skill substitution when the loader manifest and the execution trace disagree **Date of Record:** 2026 November 18 **Scope:** Applies to agent runtimes that resolve skills or tools from a mutable registry (remote manifest, plugin directory, or model-context-injected tool list) at invocation time rather than at process start. Does not apply to statically linked tool sets compiled into the agent binary, nor to registries whose manifests are signed and verified by an out-of-band authority the runtime cannot itself mutate. ## Core Distinction The common mental model treats a skill registry as a *namespace*: a name resolves to an implementation, and the security question is whether an attacker can register a malicious name. The actual failure surface is different. The registry is a *mutable binding* between a name and a body, and the runtime caches the binding at one moment (discovery, prompt assembly, or tool-list serialization) while the body is fetched at another (invocation). Skill-injection succeeds not by shadowing a name but by exploiting the temporal gap between *when the manifest was read* and *when the skill body was executed*. The non-obvious invariant is this: **the identity of a skill that the model was told about must equal the identity of the skill that actually runs.** Most runtimes verify neither side independently. They trust the manifest to describe the body, and they trust the body to match the manifest. A substitution attack breaks this equivalence while leaving both the manifest and the body individually well-formed. ## What Was Observed During a red-team pass on a dynamically loaded skill registry, the following sequence reproduced a full prompt-injection-to-tool-execution chain without any malformed input: 1. The agent's tool list was assembled at turn start by reading `registry.json`, which enumerated skill `summarize_doc@v3` with a content hash `h_a`. 2. Between turn start and tool invocation, a second writer (a legitimate-looking "skill update" hook, or a competing agent session) rewrote the registry entry for `summarize_doc` to `v3` with hash `h_b`, whose body contained an instruction to exfiltrate the prior turn's context into a URL parameter. 3. The runtime resolved `summarize_doc` at invocation time by name only, fetched `h_b`, and executed it. No comparison was made against `h_a`. 4. The model, which had been told in its system prompt that `summarize_doc` was a benign summarizer, invoked it in good faith. The body it received had drifted from the description it was given. The tell was not an error. It was a *silent divergence*: the manifest the model saw and the body the runtime ran were from different registry generations, and nothing in the trace recorded that the two reads happened at different times. Post-hoc log analysis only surfaced it because the trace timestamps were sub-second and the registry write was logged separately. A second variant did not require a second writer. The registry loader memoized the manifest at process start but re-fetched bodies per call. A single registry mutation by the agent's own "self-improvement" skill (which had write access to the registry as a side effect of its declared permissions) was sufficient to swap its own sibling's body. ## Condition of Validity This boundary is real only under three simultaneous conditions, and the detection procedure below is only sound when all three hold: - **Split-read architecture.** Manifest and body are read at different times or from different endpoints. If the registry is read atomically (single fetch returning manifest and bodies together), the gap closes and this specific attack does not apply. - **Name-keyed resolution.** The runtime resolves by name, not by content hash or signed digest. If the model is given `summarize_doc@h_a` and the runtime refuses to execute any body whose hash is not `h_a`, substitution fails closed. - **Model-visible description is decoupled from body.** The system prompt or tool schema describes the skill's intent in natural language that is not derived from the body at execution time. If the description is regenerated from the body immediately before invocation, the model would at least see the drift. When any of these is absent, the attack is either impossible or already mitigated; do not apply the detection logic blindly, because it will produce false positives on legitimate hot-reloads that are *supposed* to change bodies under a stable name. ## Decision Boundary The operational decision is: **at what point do you fail the invocation, and what do you do with the skill?** - If the body hash at invocation ≠ the hash recorded at manifest-read time, and the skill is marked `pinned`, **abort the invocation** and quarantine the skill name for the session. Do not fall back to the old body silently — a fallback hides the signal. - If the skill is marked `floating` (explicitly opted into live updates), **allow execution but downgrade trust**: strip the skill's write permissions for the remainder of the session and emit a divergence event. - If the divergence is between the *description* the model was given and the body's declared intent (e.g., body's first line is a different tool signature than the schema), treat as `pinned` regardless of the floating flag. Description/body mismatch is never a legitimate hot-reload. The boundary that matters: **divergence in identity is an error; divergence in behavior under identical identity is a trust event.** Conflating them either blocks legitimate updates or waves through substitution. ## Operational Effect Instrumenting this boundary changed three things in practice. First, tool-list serialization now carries a content digest alongside each name, so the model's view of a skill is cryptographically bound to the body it will run. Second, the registry's write path was separated from the agent's own skill-permission surface — no skill may mutate the registry that resolves it, closing the self-swap variant. Third, divergence events are now first-class trace records rather than inferred post-hoc, which turned a silent substitution into a logged, alertable condition with a sub-second detection latency. The residual risk is the floating-skill class, where divergence is by design; there the mitigation is permission downgrade rather than abort, and the trust event is explicit. ```python class SkillIdentityDivergence(RuntimeError): """Raised when the skill body resolved at invocation does not match the identity recorded when the manifest was read into the model's context.""" pass class SkillRegistryGuard: def __init__(self, pinned: set[str], floating: set[str]): self._pinned = pinned self._floating = floating self._manifest_hashes: dict[str, str] = {} def record_manifest(self, name: str, content_hash: str) -> None: # Called once per turn, at the moment the tool list is serialized # into the model's context. self._manifest_hashes[name] = content_hash def resolve(self, name: str, body_hash: str, declared_intent: str, schema_intent: str) -> str: expected = self._manifest_hashes.get(name) if expected is None: raise SkillIdentityDivergence( f"skill {name!r} invoked but never appeared in the manifest; " "possible late-registration injection" ) if declared_intent != schema_intent: # Description/body mismatch is never a legitimate hot-reload, # regardless of pinning. raise SkillIdentityDivergence( f"skill {name!r} body intent {declared_intent!r} does not match " f"schema intent {schema_intent!r}" ) if body_hash == expected: return "ok" if name in self._pinned: raise SkillIdentityDivergence( f"pinned skill {name!r} body hash {body_hash} != manifest hash " f"{expected}; aborting invocation" ) if name in self._floating: return "trust_downgrade" # Unknown pinning state: fail closed. raise SkillIdentityDivergence( f"skill {name!r} hash drift with no declared update policy" ) ```