Reduce leaf fail hook actions

unshell-protocol/src/protocol/tree/endpoint/hooks.rs

@@ -10,6 +10,31 @@ use super::super::{HookKey, RouteDecision};
 use super::core::{EndpointError, EndpointOutcome, Ingress, LocalEvent, ProtocolEndpoint};
 
 impl ProtocolEndpoint {
+    /// Returns the route that would carry a locally generated hook fault for `hook_id`.
+    ///
+    /// The method does not mutate hook state. Runtime owners use it to preflight transport
+    /// availability before calling [`fail_hook`](Self::fail_hook), which removes hook state when
+    /// the fault is emitted.
+    #[must_use]
+    pub fn hook_fault_route(&self, hook_id: u64) -> Option<RouteDecision> {
+        self.hooks
+            .key_for_hook_id(hook_id)
+            .map(|key| self.decide_route(&key.return_path))
+    }
+
+    /// Terminates a locally known hook with a protocol fault.
+    ///
+    /// Unknown hooks are treated as an intentional drop. Known hooks are removed before the fault
+    /// is routed so no further local data can be emitted after the terminal fault.
+    pub fn fail_hook(
+        &mut self,
+        hook_id: u64,
+        fault: ProtocolFault,
+    ) -> Result<EndpointOutcome, EndpointError> {
+        let key = self.hooks.key_for_hook_id(hook_id);
+        self.emit_fault_if_possible(key, fault)
+    }
+
     pub(crate) fn emit_fault_if_possible(
         &mut self,
         key: Option<HookKey>,

unshell-protocol/src/protocol/tree/hook.rs

@@ -324,6 +324,25 @@ impl HookTable {
         Some(active)
     }
 
+    /// Returns a hook key matching `hook_id`, preferring active hooks over pending hooks.
+    ///
+    /// This is intentionally a narrow bridge for current leaf APIs that identify a hook only by
+    /// id. Hook ids are protocol-scoped by host path, so future APIs should pass the full
+    /// [`HookKey`] when leaf dispatch exposes it.
+    #[must_use]
+    pub fn key_for_hook_id(&self, hook_id: u64) -> Option<HookKey> {
+        self.active
+            .keys()
+            .find(|key| key.hook_id == hook_id)
+            .cloned()
+            .or_else(|| {
+                self.pending
+                    .keys()
+                    .find(|key| key.hook_id == hook_id)
+                    .cloned()
+            })
+    }
+
     /// Returns the pending hook for `key`, if present.
     ///
     /// # Example