Add codex_hook_run analytics event

codex-rs/analytics/src/analytics_client_tests.rs

@@ -4,6 +4,7 @@ use crate::events::CodexAppMentionedEventRequest;
 use crate::events::CodexAppServerClientMetadata;
 use crate::events::CodexAppUsedEventRequest;
 use crate::events::CodexCompactionEventRequest;
+use crate::events::CodexHookRunEventRequest;
 use crate::events::CodexPluginEventRequest;
 use crate::events::CodexPluginUsedEventRequest;
 use crate::events::CodexRuntimeMetadata;
@@ -12,6 +13,7 @@ use crate::events::ThreadInitializedEvent;
 use crate::events::ThreadInitializedEventParams;
 use crate::events::TrackEventRequest;
 use crate::events::codex_app_metadata;
+use crate::events::codex_hook_run_metadata;
 use crate::events::codex_plugin_metadata;
 use crate::events::codex_plugin_used_metadata;
 use crate::events::subagent_thread_started_event_request;
@@ -21,13 +23,16 @@ use crate::facts::AppInvocation;
 use crate::facts::AppMentionedInput;
 use crate::facts::AppUsedInput;
 use crate::facts::CodexCompactionEvent;
+use crate::facts::CodexHookSource;
 use crate::facts::CompactionImplementation;
 use crate::facts::CompactionPhase;
 use crate::facts::CompactionReason;
 use crate::facts::CompactionStatus;
 use crate::facts::CompactionStrategy;
 use crate::facts::CompactionTrigger;
 use crate::facts::CustomAnalyticsFact;
+use crate::facts::HookRunFact;
+use crate::facts::HookRunInput;
 use crate::facts::InputError;
 use crate::facts::InvocationType;
 use crate::facts::PluginState;
@@ -81,6 +86,8 @@ use codex_plugin::PluginTelemetryMetadata;
 use codex_protocol::config_types::ApprovalsReviewer;
 use codex_protocol::config_types::ModeKind;
 use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookRunStatus;
 use codex_protocol::protocol::SandboxPolicy;
 use codex_protocol::protocol::SessionSource;
 use codex_protocol::protocol::SubAgentSource;
@@ -1282,6 +1289,109 @@ fn plugin_management_event_serializes_expected_shape() {
     );
 }
 
+#[test]
+fn hook_run_event_serializes_expected_shape() {
+    let tracking = TrackEventsContext {
+        model_slug: "gpt-5".to_string(),
+        thread_id: "thread-3".to_string(),
+        turn_id: "turn-3".to_string(),
+    };
+    let event = TrackEventRequest::HookRun(CodexHookRunEventRequest {
+        event_type: "codex_hook_run",
+        event_params: codex_hook_run_metadata(
+            &tracking,
+            HookRunFact {
+                event_name: HookEventName::PreToolUse,
+                hook_source: CodexHookSource::User,
+                status: HookRunStatus::Completed,
+            },
+        ),
+    });
+
+    let payload = serde_json::to_value(&event).expect("serialize hook run event");
+
+    assert_eq!(
+        payload,
+        json!({
+            "event_type": "codex_hook_run",
+            "event_params": {
+                "thread_id": "thread-3",
+                "turn_id": "turn-3",
+                "model_slug": "gpt-5",
+                "hook_name": "PreToolUse",
+                "hook_source": "user",
+                "status": "completed"
+            }
+        })
+    );
+}
+
+#[test]
+fn hook_run_metadata_maps_sources_and_statuses() {
+    let tracking = TrackEventsContext {
+        model_slug: "gpt-5".to_string(),
+        thread_id: "thread-1".to_string(),
+        turn_id: "turn-1".to_string(),
+    };
+
+    let system = serde_json::to_value(codex_hook_run_metadata(
+        &tracking,
+        HookRunFact {
+            event_name: HookEventName::SessionStart,
+            hook_source: CodexHookSource::System,
+            status: HookRunStatus::Completed,
+        },
+    ))
+    .expect("serialize system hook");
+    let project = serde_json::to_value(codex_hook_run_metadata(
+        &tracking,
+        HookRunFact {
+            event_name: HookEventName::Stop,
+            hook_source: CodexHookSource::Project,
+            status: HookRunStatus::Blocked,
+        },
+    ))
+    .expect("serialize project hook");
+    let unknown = serde_json::to_value(codex_hook_run_metadata(
+        &tracking,
+        HookRunFact {
+            event_name: HookEventName::UserPromptSubmit,
+            hook_source: CodexHookSource::Unknown,
+            status: HookRunStatus::Failed,
+        },
+    ))
+    .expect("serialize unknown hook");
+
+    assert_eq!(system["hook_source"], "system");
+    assert_eq!(system["status"], "completed");
+    assert_eq!(project["hook_source"], "project");
+    assert_eq!(project["status"], "blocked");
+    assert_eq!(unknown["hook_source"], "unknown");
+    assert_eq!(unknown["status"], "failed");
+}
+
+#[test]
+fn hook_run_metadata_maps_stopped_status() {
+    let tracking = TrackEventsContext {
+        model_slug: "gpt-5".to_string(),
+        thread_id: "thread-1".to_string(),
+        turn_id: "turn-1".to_string(),
+    };
+
+    let stopped = serde_json::to_value(codex_hook_run_metadata(
+        &tracking,
+        HookRunFact {
+            event_name: HookEventName::Stop,
+            hook_source: CodexHookSource::User,
+            status: HookRunStatus::Stopped,
+        },
+    ))
+    .expect("serialize stopped hook");
+
+    assert_eq!(stopped["hook_source"], "user");
+    assert_eq!(stopped["status"], "stopped");
+}
+
 #[test]
 fn plugin_used_dedupe_is_keyed_by_turn_and_plugin() {
     let (sender, _receiver) = mpsc::channel(1);
@@ -1359,6 +1469,37 @@ async fn reducer_ingests_skill_invoked_fact() {
     );
 }
 
+#[tokio::test]
+async fn reducer_ingests_hook_run_fact() {
+    let mut reducer = AnalyticsReducer::default();
+    let mut events = Vec::new();
+
+    reducer
+        .ingest(
+            AnalyticsFact::Custom(CustomAnalyticsFact::HookRun(HookRunInput {
+                tracking: TrackEventsContext {
+                    model_slug: "gpt-5".to_string(),
+                    thread_id: "thread-1".to_string(),
+                    turn_id: "turn-1".to_string(),
+                },
+                hook: HookRunFact {
+                    event_name: HookEventName::PostToolUse,
+                    hook_source: CodexHookSource::Unknown,
+                    status: HookRunStatus::Failed,
+                },
+            })),
+            &mut events,
+        )
+        .await;
+
+    let payload = serde_json::to_value(&events).expect("serialize events");
+    assert_eq!(payload.as_array().expect("events array").len(), 1);
+    assert_eq!(payload[0]["event_type"], "codex_hook_run");
+    assert_eq!(payload[0]["event_params"]["hook_name"], "PostToolUse");
+    assert_eq!(payload[0]["event_params"]["hook_source"], "unknown");
+    assert_eq!(payload[0]["event_params"]["status"], "failed");
+}
+
 #[tokio::test]
 async fn reducer_ingests_app_and_plugin_facts() {
     let mut reducer = AnalyticsReducer::default();

codex-rs/analytics/src/client.rs

@@ -9,6 +9,8 @@ use crate::facts::AppInvocation;
 use crate::facts::AppMentionedInput;
 use crate::facts::AppUsedInput;
 use crate::facts::CustomAnalyticsFact;
+use crate::facts::HookRunFact;
+use crate::facts::HookRunInput;
 use crate::facts::PluginState;
 use crate::facts::PluginStateChangedInput;
 use crate::facts::SkillInvocation;
@@ -191,6 +193,12 @@ impl AnalyticsEventsClient {
         )));
     }
 
+    pub fn track_hook_run(&self, tracking: TrackEventsContext, hook: HookRunFact) {
+        self.record_fact(AnalyticsFact::Custom(CustomAnalyticsFact::HookRun(
+            HookRunInput { tracking, hook },
+        )));
+    }
+
     pub fn track_plugin_used(&self, tracking: TrackEventsContext, plugin: PluginTelemetryMetadata) {
         if !self.queue.should_enqueue_plugin_used(&tracking, &plugin) {
             return;

codex-rs/analytics/src/events.rs

@@ -1,5 +1,7 @@
 use crate::facts::AppInvocation;
 use crate::facts::CodexCompactionEvent;
+use crate::facts::CodexHookSource;
+use crate::facts::HookRunFact;
 use crate::facts::InvocationType;
 use crate::facts::PluginState;
 use crate::facts::SubAgentThreadStartedInput;
@@ -15,6 +17,7 @@ use codex_plugin::PluginTelemetryMetadata;
 use codex_protocol::approvals::NetworkApprovalProtocol;
 use codex_protocol::models::PermissionProfile;
 use codex_protocol::models::SandboxPermissions;
+use codex_protocol::protocol::HookRunStatus;
 use codex_protocol::protocol::SubAgentSource;
 use serde::Serialize;
 
@@ -39,6 +42,7 @@ pub(crate) enum TrackEventRequest {
     GuardianReview(Box<GuardianReviewEventRequest>),
     AppMentioned(CodexAppMentionedEventRequest),
     AppUsed(CodexAppUsedEventRequest),
+    HookRun(CodexHookRunEventRequest),
     Compaction(Box<CodexCompactionEventRequest>),
     TurnEvent(Box<CodexTurnEventRequest>),
     TurnSteer(CodexTurnSteerEventRequest),
@@ -300,6 +304,22 @@ pub(crate) struct CodexAppUsedEventRequest {
     pub(crate) event_params: CodexAppMetadata,
 }
 
+#[derive(Serialize)]
+pub(crate) struct CodexHookRunMetadata {
+    pub(crate) thread_id: Option<String>,
+    pub(crate) turn_id: Option<String>,
+    pub(crate) model_slug: Option<String>,
+    pub(crate) hook_name: Option<String>,
+    pub(crate) hook_source: Option<CodexHookSource>,
+    pub(crate) status: Option<HookRunStatus>,
+}
+
+#[derive(Serialize)]
+pub(crate) struct CodexHookRunEventRequest {
+    pub(crate) event_type: &'static str,
+    pub(crate) event_params: CodexHookRunMetadata,
+}
+
 #[derive(Serialize)]
 pub(crate) struct CodexCompactionEventParams {
     pub(crate) thread_id: String,
@@ -529,6 +549,20 @@ pub(crate) fn codex_plugin_used_metadata(
     }
 }
 
+pub(crate) fn codex_hook_run_metadata(
+    tracking: &TrackEventsContext,
+    hook: HookRunFact,
+) -> CodexHookRunMetadata {
+    CodexHookRunMetadata {
+        thread_id: Some(tracking.thread_id.clone()),
+        turn_id: Some(tracking.turn_id.clone()),
+        model_slug: Some(tracking.model_slug.clone()),
+        hook_name: Some(hook.event_name.analytics_name().to_owned()),
+        hook_source: Some(hook.hook_source),
+        status: Some(analytics_hook_status(hook.status)),
+    }
+}
+
 pub(crate) fn current_runtime_metadata() -> CodexRuntimeMetadata {
     let os_info = os_info::get();
     CodexRuntimeMetadata {
@@ -586,3 +620,11 @@ pub(crate) fn subagent_parent_thread_id(subagent_source: &SubAgentSource) -> Opt
         _ => None,
     }
 }
+
+fn analytics_hook_status(status: HookRunStatus) -> HookRunStatus {
+    match status {
+        // Running is unexpected here and normalized defensively.
+        HookRunStatus::Running => HookRunStatus::Failed,
+        other => other,
+    }
+}

codex-rs/analytics/src/facts.rs

@@ -15,6 +15,8 @@ use codex_protocol::config_types::ReasoningSummary;
 use codex_protocol::config_types::ServiceTier;
 use codex_protocol::openai_models::ReasoningEffort;
 use codex_protocol::protocol::AskForApproval;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookRunStatus;
 use codex_protocol::protocol::SandboxPolicy;
 use codex_protocol::protocol::SessionSource;
 use codex_protocol::protocol::SkillScope;
@@ -241,6 +243,15 @@ pub enum CompactionStatus {
     Interrupted,
 }
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CodexHookSource {
+    System,
+    User,
+    Project,
+    Unknown,
+}
+
 #[derive(Clone)]
 pub struct CodexCompactionEvent {
     pub thread_id: String,
@@ -298,6 +309,7 @@ pub(crate) enum CustomAnalyticsFact {
     SkillInvoked(SkillInvokedInput),
     AppMentioned(AppMentionedInput),
     AppUsed(AppUsedInput),
+    HookRun(HookRunInput),
     PluginUsed(PluginUsedInput),
     PluginStateChanged(PluginStateChangedInput),
 }
@@ -317,6 +329,17 @@ pub(crate) struct AppUsedInput {
     pub app: AppInvocation,
 }
 
+pub(crate) struct HookRunInput {
+    pub tracking: TrackEventsContext,
+    pub hook: HookRunFact,
+}
+
+pub struct HookRunFact {
+    pub event_name: HookEventName,
+    pub hook_source: CodexHookSource,
+    pub status: HookRunStatus,
+}
+
 pub(crate) struct PluginUsedInput {
     pub tracking: TrackEventsContext,
     pub plugin: PluginTelemetryMetadata,

codex-rs/analytics/src/lib.rs

@@ -22,13 +22,15 @@ pub use events::GuardianReviewedAction;
 pub use facts::AnalyticsJsonRpcError;
 pub use facts::AppInvocation;
 pub use facts::CodexCompactionEvent;
+pub use facts::CodexHookSource;
 pub use facts::CodexTurnSteerEvent;
 pub use facts::CompactionImplementation;
 pub use facts::CompactionPhase;
 pub use facts::CompactionReason;
 pub use facts::CompactionStatus;
 pub use facts::CompactionStrategy;
 pub use facts::CompactionTrigger;
+pub use facts::HookRunFact;
 pub use facts::InputError;
 pub use facts::InvocationType;
 pub use facts::SkillInvocation;