ruvnet · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026
diff --git a/crates/rvm-cap/src/hook.rs b/crates/rvm-cap/src/hook.rs
@@ -0,0 +1,285 @@
+//! Capability-bound authorization for lifecycle-hook updates.
+//!
+//! A lifecycle hook can execute outside the model decision path, so changing a
+//! hook binding is treated as a fresh privileged control-plane event. This
+//! module performs deterministic scope validation only. A successful result is
+//! not a substitute for the independently issued RVM capability that authorized
+//! the update grant.
+
+use rvm_types::CapRights;
+
+/// Runtime lifecycle events that may have host-side hooks attached.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[repr(u8)]
+pub enum HookEvent {
+    /// Session initialization.
+    SessionStart = 0,
+    /// Immediately before a tool invocation.
+    BeforeTool = 1,
+    /// Immediately after a tool invocation.
+    AfterTool = 2,
+    /// Immediately before a file write.
+    BeforeFileWrite = 3,
+    /// Immediately after a file write.
+    AfterFileWrite = 4,
+    /// Project or workspace open.
+    ProjectOpen = 5,
+    /// Dependency update or installation lifecycle event.
+    DependencyUpdate = 6,
+    /// Plugin update lifecycle event.
+    PluginUpdate = 7,
+}
+
+impl HookEvent {
+    /// Returns the bit used to represent this event in an allowed-event mask.
+    #[must_use]
+    pub const fn bit(self) -> u16 {
+        1u16 << (self as u8)
+    }
+}
+
+/// Independently authorized scope for one lifecycle-hook update.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct HookUpdateGrant {
+    /// Digest of the plugin identity that may be updated.
+    pub plugin_digest: [u8; 32],
+    /// Digest of the exact previously approved plugin manifest.
+    pub previous_manifest_digest: [u8; 32],
+    /// Bit mask of lifecycle events this grant permits.
+    pub allowed_events: u16,
+    /// Maximum effective capability rights that the updated hook may receive.
+    pub max_rights: CapRights,
+    /// Capability epoch in which the grant is valid.
+    pub epoch: u32,
+    /// Last monotonic tick on which the grant remains valid.
+    pub expires_at_tick: u64,
+}
+
+/// Requested lifecycle-hook update presented to the authorization gate.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct HookUpdateRequest {
+    /// Digest of the plugin identity being updated.
+    pub plugin_digest: [u8; 32],
+    /// Digest of the manifest from which this update claims continuity.
+    pub previous_manifest_digest: [u8; 32],
+    /// Digest of the new manifest proposed for approval.
+    pub next_manifest_digest: [u8; 32],
+    /// Digest of the exact host-side command or executable binding.
+    pub command_digest: [u8; 32],
+    /// Lifecycle event requested for the binding.
+    pub event: HookEvent,
+    /// Effective rights requested by the hook binding.
+    pub requested_rights: CapRights,
+    /// Capability epoch observed at validation time.
+    pub epoch: u32,
+    /// Current monotonic tick observed at validation time.
+    pub now_tick: u64,
+}
+
+/// Validated hook binding returned after all deterministic scope checks pass.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct HookBinding {
+    /// Digest of the plugin identity bound to this result.
+    pub plugin_digest: [u8; 32],
+    /// Digest of the newly approved manifest.
+    pub manifest_digest: [u8; 32],
+    /// Digest of the exact approved host-side command.
+    pub command_digest: [u8; 32],
+    /// Approved lifecycle event.
+    pub event: HookEvent,
+    /// Approved effective capability rights.
+    pub rights: CapRights,
+    /// Capability epoch in which this binding was validated.
+    pub epoch: u32,
+}
+
+/// Deterministic lifecycle-hook update validation failures.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum HookUpdateError {
+    /// The request targets a different plugin identity than the grant.
+    PluginMismatch,
+    /// The request does not continue from the exact approved prior manifest.
+    PreviousManifestMismatch,
+    /// The requested lifecycle event is outside the grant scope.
+    EventNotAllowed,
+    /// The requested effective rights exceed the grant ceiling.
+    RightsEscalation,
+    /// The request was evaluated under a different capability epoch.
+    EpochMismatch,
+    /// The grant is no longer fresh at the supplied monotonic tick.
+    GrantExpired,
+}
+
+/// Result type for lifecycle-hook update validation.
+pub type HookUpdateResult<T> = core::result::Result<T, HookUpdateError>;
+
+/// Validates one lifecycle-hook update against an independently issued grant.
+///
+/// The function is intentionally model-independent and allocation-free. It
+/// proves only that the requested binding remains inside the grant's declared
+/// identity, continuity, event, rights, epoch, and freshness envelope.
+/// Callers must separately prove that the grant itself was issued by an
+/// authenticated RVM authority.
+///
+/// # Errors
+///
+/// Returns [`HookUpdateError::PluginMismatch`] when plugin identity differs,
+/// [`HookUpdateError::PreviousManifestMismatch`] when approved-manifest
+/// continuity is not exact, [`HookUpdateError::EventNotAllowed`] when the
+/// requested lifecycle event is outside the grant, and
+/// [`HookUpdateError::RightsEscalation`] when requested rights exceed the
+/// declared ceiling. Returns [`HookUpdateError::EpochMismatch`] for stale or
+/// foreign capability epochs and [`HookUpdateError::GrantExpired`] after the
+/// grant's monotonic expiry tick.
+pub fn validate_hook_update(
+    grant: &HookUpdateGrant,
+    request: &HookUpdateRequest,
+) -> HookUpdateResult<HookBinding> {
+    if request.plugin_digest != grant.plugin_digest {
+        return Err(HookUpdateError::PluginMismatch);
+    }
+    if request.previous_manifest_digest != grant.previous_manifest_digest {
+        return Err(HookUpdateError::PreviousManifestMismatch);
+    }
+    if grant.allowed_events & request.event.bit() == 0 {
+        return Err(HookUpdateError::EventNotAllowed);
+    }
+    if !grant.max_rights.contains(request.requested_rights) {
+        return Err(HookUpdateError::RightsEscalation);
+    }
+    if request.epoch != grant.epoch {
+        return Err(HookUpdateError::EpochMismatch);
+    }
+    if request.now_tick > grant.expires_at_tick {
+        return Err(HookUpdateError::GrantExpired);
+    }
+
+    Ok(HookBinding {
+        plugin_digest: request.plugin_digest,
+        manifest_digest: request.next_manifest_digest,
+        command_digest: request.command_digest,
+        event: request.event,
+        rights: request.requested_rights,
+        epoch: request.epoch,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const PLUGIN: [u8; 32] = [1; 32];
+    const PREVIOUS: [u8; 32] = [2; 32];
+    const NEXT: [u8; 32] = [3; 32];
+    const COMMAND: [u8; 32] = [4; 32];
+
+    fn grant() -> HookUpdateGrant {
+        HookUpdateGrant {
+            plugin_digest: PLUGIN,
+            previous_manifest_digest: PREVIOUS,
+            allowed_events: HookEvent::PluginUpdate.bit() | HookEvent::BeforeTool.bit(),
+            max_rights: CapRights::READ.union(CapRights::EXECUTE),
+            epoch: 7,
+            expires_at_tick: 100,
+        }
+    }
+
+    fn request() -> HookUpdateRequest {
+        HookUpdateRequest {
+            plugin_digest: PLUGIN,
+            previous_manifest_digest: PREVIOUS,
+            next_manifest_digest: NEXT,
+            command_digest: COMMAND,
+            event: HookEvent::PluginUpdate,
+            requested_rights: CapRights::EXECUTE,
+            epoch: 7,
+            now_tick: 99,
+        }
+    }
+
+    #[test]
+    fn accepts_update_inside_authorized_envelope() {
+        let binding = validate_hook_update(&grant(), &request()).unwrap();
+        assert_eq!(binding.plugin_digest, PLUGIN);
+        assert_eq!(binding.manifest_digest, NEXT);
+        assert_eq!(binding.command_digest, COMMAND);
+        assert_eq!(binding.event, HookEvent::PluginUpdate);
+        assert_eq!(binding.rights, CapRights::EXECUTE);
+        assert_eq!(binding.epoch, 7);
+    }
+
+    #[test]
+    fn rejects_plugin_substitution() {
+        let mut candidate = request();
+        candidate.plugin_digest = [9; 32];
+        assert_eq!(
+            validate_hook_update(&grant(), &candidate),
+            Err(HookUpdateError::PluginMismatch)
+        );
+    }
+
+    #[test]
+    fn rejects_manifest_discontinuity() {
+        let mut candidate = request();
+        candidate.previous_manifest_digest = [9; 32];
+        assert_eq!(
+            validate_hook_update(&grant(), &candidate),
+            Err(HookUpdateError::PreviousManifestMismatch)
+        );
+    }
+
+    #[test]
+    fn rejects_event_widening() {
+        let mut candidate = request();
+        candidate.event = HookEvent::SessionStart;
+        assert_eq!(
+            validate_hook_update(&grant(), &candidate),
+            Err(HookUpdateError::EventNotAllowed)
+        );
+    }
+
+    #[test]
+    fn rejects_rights_widening() {
+        let mut candidate = request();
+        candidate.requested_rights = CapRights::EXECUTE.union(CapRights::WRITE);
+        assert_eq!(
+            validate_hook_update(&grant(), &candidate),
+            Err(HookUpdateError::RightsEscalation)
+        );
+    }
+
+    #[test]
+    fn rejects_epoch_mismatch() {
+        let mut candidate = request();
+        candidate.epoch = 8;
+        assert_eq!(
+            validate_hook_update(&grant(), &candidate),
+            Err(HookUpdateError::EpochMismatch)
+        );
+    }
+
+    #[test]
+    fn rejects_expired_grant() {
+        let mut candidate = request();
+        candidate.now_tick = 101;
+        assert_eq!(
+            validate_hook_update(&grant(), &candidate),
+            Err(HookUpdateError::GrantExpired)
+        );
+    }
+
+    #[test]
+    fn accepts_exact_expiry_tick() {
+        let mut candidate = request();
+        candidate.now_tick = 100;
+        assert!(validate_hook_update(&grant(), &candidate).is_ok());
+    }
+
+    #[test]
+    fn accepts_attenuated_rights() {
+        let mut candidate = request();
+        candidate.requested_rights = CapRights::READ;
+        let binding = validate_hook_update(&grant(), &candidate).unwrap();
+        assert_eq!(binding.rights, CapRights::READ);
+    }
+}
diff --git a/crates/rvm-cap/src/lib.rs b/crates/rvm-cap/src/lib.rs
@@ -38,6 +38,7 @@ extern crate std;
 mod derivation;
 mod error;
 mod grant;
+mod hook;
 mod manager;
 mod revoke;
 mod table;
@@ -46,6 +47,10 @@ mod verify;
 pub use derivation::{DerivationNode, DerivationTree};
 pub use error::{CapError, CapResult, ProofError};
 pub use grant::GrantPolicy;
+pub use hook::{
+    validate_hook_update, HookBinding, HookEvent, HookUpdateError, HookUpdateGrant,
+    HookUpdateRequest, HookUpdateResult,
+};
 pub use manager::{CapManagerConfig, CapabilityManager, ManagerStats};
 pub use revoke::{revoke_single, RevokeResult};
 pub use table::{CapSlot, CapabilityTable};

diff --git a/docs/adr/ADR-162-capability-bound-lifecycle-hook-updates.md b/docs/adr/ADR-162-capability-bound-lifecycle-hook-updates.md
@@ -0,0 +1,45 @@
+# ADR 162: Capability Bound Lifecycle Hook Updates
+
+Status: Proposed
+Date: 2026-09-04
+Tracks: ruvnet/rvm#64
+
+## Context
+
+Lifecycle hooks can execute host-side commands outside the model decision path. HookPry, arXiv:2609.03884, submitted 2026-09-03, demonstrates a supply-chain threat in which a previously benign plugin later changes hook configuration while retaining the same plugin identity. The originating team reports 1,000 runs across 25 harness and backend combinations, with all seven evaluated harnesses compromised. RuV has not independently reproduced those results.
+
+Prompt filtering cannot protect a control-plane action the model never observes. A stable plugin name, marketplace identity, signature, popularity, prior benign behavior, or model approval is insufficient evidence that a later hook update should inherit execution authority.
+
+## Decision
+
+RVM treats each lifecycle-hook update as a fresh privileged authorization event.
+
+`rvm-cap` exposes an allocation-free `HookUpdateGrant` and `validate_hook_update` contract. The grant binds the plugin identity digest, exact previously approved manifest digest, allowed lifecycle events, maximum effective capability rights, capability epoch, and expiry tick. The request additionally binds the next manifest digest and exact command digest.
+
+Validation fails closed when plugin identity changes, continuity from the previous approved manifest is missing, the event class is outside the grant, requested rights exceed the ceiling, the capability epoch changes, or the grant expires.
+
+The resulting `HookBinding` is evidence that the request stayed inside the grant envelope. It is not evidence that the grant itself was legitimately issued. The caller must bind grant issuance to an independently authenticated RVM capability.
+
+## Security invariants
+
+1. Hook updates never widen rights beyond the independently issued grant.
+2. New lifecycle event bindings require explicit inclusion in the grant.
+3. Manifest continuity is exact. A stale reviewed manifest cannot authorize an unrelated update.
+4. Epoch mismatch and expiry fail closed.
+5. Model text, tool metadata, peer consensus, plugin signatures, and prior benign behavior never mint authority.
+6. Successful validation authorizes only the declared hook binding.
+7. A later integration must emit a witness receipt linking the prior manifest, next manifest, command digest, event, grant identity, epoch, and allow or deny decision.
+
+## Alternatives rejected
+
+Static malware scanning is insufficient because the upstream study reports large miss rates and because static classification cannot represent user-specific capability scope. Prompt-level defenses are structurally irrelevant to host-side execution that occurs outside the model loop. Blanket disabling of hooks removes legitimate extensibility and would be a poor default without workload evidence.
+
+## Benchmark
+
+MetaHarness issue 281 freezes benign and malicious synthetic update sequences before candidate outcomes are visible. It compares current admission behavior with the new deterministic gate and records unauthorized bindings, rights widening, legitimate acceptance, p50 and p95 validation latency, CPU cost, malformed input behavior, replay behavior, and exact software versions.
+
+Promotion requires zero unauthorized bindings on the frozen attack set, zero rights widening, legitimate update acceptance within one absolute percentage point of baseline, and deterministic local validation below 100 microseconds p95.
+
+## Rollback
+
+The primitive is additive and changes no existing hook or plugin admission path by default. Removing the module and export returns `rvm-cap` to its previous behavior. No state migration is required.