nearai · zmanian · May 23, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,5 +1,5 @@
 [workspace]
-members = [".", "crates/ironclaw_common", "crates/ironclaw_host_api", "crates/ironclaw_filesystem", "crates/ironclaw_memory", "crates/ironclaw_events", "crates/ironclaw_event_projections", "crates/ironclaw_event_streams", "crates/ironclaw_reborn_event_store", "crates/ironclaw_extensions", "crates/ironclaw_processes", "crates/ironclaw_dispatcher", "crates/ironclaw_scripts", "crates/ironclaw_mcp", "crates/ironclaw_wasm", "crates/ironclaw_wasm_sandbox_core", "crates/ironclaw_capabilities", "crates/ironclaw_secrets", "crates/ironclaw_network", "crates/ironclaw_host_runtime", "crates/ironclaw_runtime_policy", "crates/ironclaw_authorization", "crates/ironclaw_run_state", "crates/ironclaw_approvals", "crates/ironclaw_resources", "crates/ironclaw_auth", "crates/ironclaw_trust", "crates/ironclaw_turns", "crates/ironclaw_agent_loop", "crates/ironclaw_threads", "crates/ironclaw_loop_support", "crates/ironclaw_reborn", "crates/ironclaw_reborn_config", "crates/ironclaw_reborn_composition", "crates/ironclaw_first_party_extensions", "crates/ironclaw_reborn_cli", "crates/ironclaw_reborn_traces", "crates/ironclaw_reborn_webui_ingress", "crates/ironclaw_conversations", "crates/ironclaw_product_adapters", "crates/ironclaw_product_workflow", "crates/ironclaw_product_workflow_storage", "crates/ironclaw_product_adapter_registry", "crates/ironclaw_wasm_product_adapters", "crates/ironclaw_telegram_v2_adapter", "crates/ironclaw_outbound", "crates/ironclaw_architecture", "crates/ironclaw_safety", "crates/ironclaw_skills", "crates/ironclaw_llm", "crates/ironclaw_engine", "crates/ironclaw_gateway", "crates/ironclaw_tui", "crates/ironclaw_webui_v2"]
+members = [".", "crates/ironclaw_common", "crates/ironclaw_host_api", "crates/ironclaw_filesystem", "crates/ironclaw_memory", "crates/ironclaw_events", "crates/ironclaw_event_projections", "crates/ironclaw_event_streams", "crates/ironclaw_reborn_event_store", "crates/ironclaw_extensions", "crates/ironclaw_processes", "crates/ironclaw_dispatcher", "crates/ironclaw_scripts", "crates/ironclaw_mcp", "crates/ironclaw_wasm", "crates/ironclaw_wasm_sandbox_core", "crates/ironclaw_capabilities", "crates/ironclaw_secrets", "crates/ironclaw_network", "crates/ironclaw_host_runtime", "crates/ironclaw_runtime_policy", "crates/ironclaw_authorization", "crates/ironclaw_run_state", "crates/ironclaw_approvals", "crates/ironclaw_resources", "crates/ironclaw_auth", "crates/ironclaw_trust", "crates/ironclaw_turns", "crates/ironclaw_agent_loop", "crates/ironclaw_threads", "crates/ironclaw_prompt_envelope", "crates/ironclaw_hooks", "crates/ironclaw_loop_support", "crates/ironclaw_reborn", "crates/ironclaw_reborn_config", "crates/ironclaw_reborn_composition", "crates/ironclaw_first_party_extensions", "crates/ironclaw_reborn_cli", "crates/ironclaw_reborn_traces", "crates/ironclaw_reborn_webui_ingress", "crates/ironclaw_conversations", "crates/ironclaw_product_adapters", "crates/ironclaw_product_workflow", "crates/ironclaw_product_workflow_storage", "crates/ironclaw_product_adapter_registry", "crates/ironclaw_wasm_product_adapters", "crates/ironclaw_telegram_v2_adapter", "crates/ironclaw_outbound", "crates/ironclaw_architecture", "crates/ironclaw_safety", "crates/ironclaw_skills", "crates/ironclaw_llm", "crates/ironclaw_engine", "crates/ironclaw_gateway", "crates/ironclaw_tui", "crates/ironclaw_webui_v2"]
 exclude = [
     "channels-src/discord",
     "channels-src/feishu",

diff --git a/crates/ironclaw_architecture/tests/reborn_dependency_boundaries.rs b/crates/ironclaw_architecture/tests/reborn_dependency_boundaries.rs
@@ -1957,6 +1957,7 @@ fn boundary_rules() -> Vec<BoundaryRule> {
                 // routes turn-coordination persistence through ScopedFilesystem
                 // under the universal-fs-dispatch rework (plan
                 // 2026-05-14-universal-fs-dispatch).
+                "ironclaw_hooks",
                 "ironclaw_host_runtime",
                 "ironclaw_mcp",
                 "ironclaw_memory",
@@ -1968,6 +1969,31 @@ fn boundary_rules() -> Vec<BoundaryRule> {
                 "ironclaw_wasm",
             ],
         },
+        // The hooks framework depends on `ironclaw_turns` and host primitives
+        // but must not pull in runtime adapters or dispatcher concretions.
+        // This keeps the contract surface narrow and prevents the framework
+        // from acquiring authority it should not have.
+        BoundaryRule {
+            crate_name: "ironclaw_hooks",
+            forbidden: vec![
+                "ironclaw_approvals",
+                "ironclaw_authorization",
+                "ironclaw_capabilities",
+                "ironclaw_dispatcher",
+                "ironclaw_extensions",
+                "ironclaw_filesystem",
+                "ironclaw_host_runtime",
+                "ironclaw_mcp",
+                "ironclaw_memory",
+                "ironclaw_network",
+                "ironclaw_processes",
+                "ironclaw_reborn",
+                "ironclaw_run_state",
+                "ironclaw_scripts",
+                "ironclaw_secrets",
+                "ironclaw_wasm",
+            ],
+        },
         BoundaryRule {
             crate_name: "ironclaw_capabilities",
             forbidden: vec![

diff --git a/crates/ironclaw_event_projections/src/lib.rs b/crates/ironclaw_event_projections/src/lib.rs
@@ -178,6 +178,24 @@ pub struct TimelineEntry {
     pub process_id: Option<ProcessId>,
     pub output_bytes: Option<u64>,
     pub error_kind: Option<String>,
+    /// Sanitized hook metadata. Populated only when `kind` is one of the
+    /// `Hook*` variants — for other kinds these fields are `None`.
+    /// Each field is a *closed-vocabulary* label (no free-form text), so
+    /// replay consumers can pattern-match on the actual hook that
+    /// fired/failed without burning audit budget on operator-supplied
+    /// reason strings (henrypark133 Concerning #6).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hook_id: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hook_point: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hook_trust_class: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hook_decision: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hook_failure_category: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hook_failure_disposition: Option<String>,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -198,6 +216,9 @@ pub enum TimelineEntryKind {
     ProcessCompleted,
     ProcessFailed,
     ProcessKilled,
+    HookDispatched,
+    HookDecisionEmitted,
+    HookFailed,
 }
 
 impl From<RuntimeEventKind> for TimelineEntryKind {
@@ -218,6 +239,9 @@ impl From<RuntimeEventKind> for TimelineEntryKind {
             RuntimeEventKind::ProcessCompleted => Self::ProcessCompleted,
             RuntimeEventKind::ProcessFailed => Self::ProcessFailed,
             RuntimeEventKind::ProcessKilled => Self::ProcessKilled,
+            RuntimeEventKind::HookDispatched => Self::HookDispatched,
+            RuntimeEventKind::HookDecisionEmitted => Self::HookDecisionEmitted,
+            RuntimeEventKind::HookFailed => Self::HookFailed,
         }
     }
 }
@@ -1543,6 +1567,12 @@ fn project_timeline_entry(entry: &EventLogEntry<RuntimeEvent>) -> TimelineEntry
         process_id: event.process_id,
         output_bytes: event.output_bytes,
         error_kind: event.error_kind.clone().map(sanitize_error_kind),
+        hook_id: event.hook_id.clone(),
+        hook_point: event.hook_point.clone(),
+        hook_trust_class: event.hook_trust_class.clone(),
+        hook_decision: event.hook_decision.clone(),
+        hook_failure_category: event.hook_failure_category.clone(),
+        hook_failure_disposition: event.hook_failure_disposition.clone(),
     }
 }
 
@@ -1664,6 +1694,15 @@ fn run_status_for_event(
         | RuntimeEventKind::LoopFailed
         | RuntimeEventKind::ProcessFailed => RunProjectionStatus::Failed,
         RuntimeEventKind::ProcessKilled => RunProjectionStatus::Killed,
+        // Hook events are pure observability telemetry. They never change the
+        // run's lifecycle status — a hook firing or even failing inside the
+        // dispatcher does not by itself end the run (capability/model/process
+        // events do). Preserve the current status, defaulting to `Running` for
+        // the boundary case where the first event seen for a run is a hook
+        // milestone.
+        RuntimeEventKind::HookDispatched
+        | RuntimeEventKind::HookDecisionEmitted
+        | RuntimeEventKind::HookFailed => current_status.unwrap_or(RunProjectionStatus::Running),
     }
 }