doctor: Enforce Codex project-hook discovery policy

Prevent structurally current Codex project registrations from appearing healthy when the effective managed-only policy excludes project hooks. Probe Codex's composed policy once per doctor invocation, classify blocked and unknown policy separately from trust, reuse the result across registrations and reports, and keep repairs limited to structural drift.

Plan: codex-cli-integration.md — T22 (follow-up correctness fix #3)

Co-authored-by: SCE <sce@crocoder.dev>

Author: davidabram

cli/src/services/codex_hook_policy.rs

@@ -1,5 +1,19 @@
-//! Read-only diagnosis of Codex's own hook-trust bookkeeping for SCE-owned
-//! `.codex/hooks.json` registrations.
+//! Read-only diagnosis of Codex's own per-handler hook-*trust* bookkeeping
+//! (enabled / `trusted_hash`) for SCE-owned `.codex/hooks.json`
+//! registrations.
+//!
+//! This is deliberately only one of two independent dimensions Codex
+//! requires before it will actually execute a project hook handler. This
+//! module answers "given an eligible hook *source*, has this handler been
+//! enabled and durably trusted?" — it says nothing about whether Codex
+//! considers the *source* (SCE's project `.codex/hooks.json`) eligible at
+//! all. That second dimension is effective hook-discovery *policy*
+//! (`allow_managed_hooks_only`), owned entirely by `codex_hook_policy`. A
+//! project registration is only executable when both are satisfied:
+//! structurally current, policy-eligible, *and* trusted. See
+//! `codex_hook_policy`'s module documentation for why policy cannot be
+//! determined by reading any file this module could read, and for the
+//! upstream discovery-policy source references.
 //!
 //! Mirrors current upstream `openai/codex` (commit
 //! `8e649e3afa5cdddfb09a1b85a090b94775045d9b`):
@@ -45,8 +59,13 @@ const EVENTS_SUPPORTING_ADDITIONAL_CONTEXT: [&str; 4] = [
 /// project-owned (non-managed) handlers in `.codex/hooks.json`.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub(crate) enum TrustReadiness {
-    /// Enabled and `trusted_hash` matches the handler's current hash: Codex
-    /// will execute this handler.
+    /// Enabled and `trusted_hash` matches the handler's current hash: this
+    /// handler is durably trusted. This alone does **not** mean Codex will
+    /// execute it — `Trusted` says nothing about whether Codex's
+    /// hook-discovery policy considers this project handler's *source*
+    /// eligible at all (see `codex_hook_policy`). The accurate reading is
+    /// "the current non-managed handler is enabled and durably trusted,
+    /// assuming Codex policy permits this hook source."
     Trusted,
     /// Enabled but no `trusted_hash` is recorded for this handler yet.
     Untrusted,
@@ -208,7 +227,7 @@ fn state_key(
 /// [<one normalized handler>]}` shape, canonicalize (recursively sort object
 /// keys, matching `fingerprint::canonical_json`), and SHA-256 the compact
 /// JSON encoding.
-fn hash_command_handler(
+pub(crate) fn hash_command_handler(
     event: &str,
     matcher: Option<&str>,
     handler: &Value,

cli/src/services/codex_hook_trust.rs

@@ -5,6 +5,7 @@ use std::process::Command;
 use anyhow::{Context, Result};
 
 use crate::app::{ContextWithRepoRoot, HasRepoRoot};
+use crate::services::codex_hook_policy;
 use crate::services::default_paths::{resolve_sce_default_locations, resolve_state_data_root};
 use crate::services::lifecycle::{
     lifecycle_providers, FixOutcome, HealthCategory, HealthFixability, HealthProblem,
@@ -52,6 +53,13 @@ struct DoctorDependencies<'a> {
     resolve_state_root: &'a dyn Fn() -> Result<PathBuf>,
     resolve_global_config_path: &'a dyn Fn() -> Result<PathBuf>,
     validate_config_file: &'a dyn Fn(&Path) -> Result<()>,
+    /// Probes Codex's effective hook-discovery policy
+    /// (`allow_managed_hooks_only`). Invoked exactly once per doctor
+    /// invocation (see `execute_doctor_with_lifecycle_providers`) and reused
+    /// for every Codex integration inspection within that invocation —
+    /// initial report, `--fix`, and final report alike — never once per
+    /// registration.
+    probe_codex_hook_policy: &'a dyn Fn() -> codex_hook_policy::CodexHookPolicyReadiness,
 }
 
 struct DoctorExecution {
@@ -98,6 +106,7 @@ fn execute_doctor_with_context(
                 Ok(resolve_sce_default_locations()?.global_config_file())
             },
             validate_config_file: &crate::services::config::validate_config_file,
+            probe_codex_hook_policy: &codex_hook_policy::probe_default,
         },
     )
 }
@@ -108,6 +117,11 @@ fn execute_doctor_with_lifecycle_providers(
     context: &impl HasRepoRoot,
     dependencies: &DoctorDependencies<'_>,
 ) -> DoctorExecution {
+    // Probed exactly once per doctor invocation, then reused for every
+    // Codex integration inspection below (initial report, `--fix`, and final
+    // report alike) instead of once per registration or once per report.
+    let policy_readiness = (dependencies.probe_codex_hook_policy)();
+
     let providers = lifecycle_providers(true);
     let initial_problems = diagnose_lifecycle_providers(context, &providers);
     let initial_doctor_problems = initial_problems
@@ -119,6 +133,7 @@ fn execute_doctor_with_lifecycle_providers(
         repository_root,
         dependencies,
         initial_doctor_problems,
+        &policy_readiness,
     );
 
     if request.mode != DoctorMode::Fix {
@@ -129,7 +144,10 @@ fn execute_doctor_with_lifecycle_providers(
     }
 
     let mut fix_results = fix_lifecycle_providers(context, &providers, &initial_problems);
-    fix_results.extend(repair_merge_target_configs(repository_root));
+    fix_results.extend(repair_merge_target_configs(
+        repository_root,
+        &policy_readiness,
+    ));
     let final_problems = diagnose_lifecycle_providers(context, &providers);
     let final_doctor_problems = final_problems
         .into_iter()
@@ -140,6 +158,7 @@ fn execute_doctor_with_lifecycle_providers(
         repository_root,
         dependencies,
         final_doctor_problems,
+        &policy_readiness,
     );
     fix_results.extend(build_manual_fix_results(&final_report));
 
@@ -335,6 +354,12 @@ fn doctor_problem_kind(kind: HealthProblemKind) -> ProblemKind {
         HealthProblemKind::CodexHookRegistrationNotTrusted => {
             ProblemKind::CodexHookRegistrationNotTrusted
         }
+        HealthProblemKind::CodexHookRegistrationPolicyBlocked => {
+            ProblemKind::CodexHookRegistrationPolicyBlocked
+        }
+        HealthProblemKind::CodexHookRegistrationPolicyUnknown => {
+            ProblemKind::CodexHookRegistrationPolicyUnknown
+        }
         HealthProblemKind::AgentTraceDbConnectionFailed => {
             ProblemKind::AgentTraceDbConnectionFailed
         }
@@ -403,6 +428,12 @@ fn health_problem_kind(kind: ProblemKind) -> HealthProblemKind {
         ProblemKind::CodexHookRegistrationNotTrusted => {
             HealthProblemKind::CodexHookRegistrationNotTrusted
         }
+        ProblemKind::CodexHookRegistrationPolicyBlocked => {
+            HealthProblemKind::CodexHookRegistrationPolicyBlocked
+        }
+        ProblemKind::CodexHookRegistrationPolicyUnknown => {
+            HealthProblemKind::CodexHookRegistrationPolicyUnknown
+        }
         ProblemKind::AgentTraceDbConnectionFailed => {
             HealthProblemKind::AgentTraceDbConnectionFailed
         }

cli/src/services/doctor/inspect.rs

@@ -436,8 +436,10 @@ fn integration_group_status(
                 | IntegrationContentState::Mismatch
                 | IntegrationContentState::Stale
                 | IntegrationContentState::Malformed(_)
-                | IntegrationContentState::ReadFailed(_) => DoctorDisplayStatus::Fail,
-                IntegrationContentState::NotTrusted(_) => DoctorDisplayStatus::Warn,
+                | IntegrationContentState::ReadFailed(_)
+                | IntegrationContentState::PolicyBlocked(_) => DoctorDisplayStatus::Fail,
+                IntegrationContentState::NotTrusted(_)
+                | IntegrationContentState::PolicyUnknown(_) => DoctorDisplayStatus::Warn,
             })
         });
     let problem_status = report
@@ -606,6 +608,16 @@ fn render_display_detail(lines: &mut Vec<String>, detail: &DoctorDisplayDetail,
             lines.push(format!("{prefix}Path: {}", path.display()));
             lines.push(format!("{prefix}Not yet executable by Codex: {reason}"));
         }
+        DoctorDisplayDetail::PolicyBlocked { path, reason } => {
+            lines.push(format!("{prefix}Path: {}", path.display()));
+            lines.push(format!("{prefix}Blocked by Codex policy: {reason}"));
+        }
+        DoctorDisplayDetail::PolicyUnknown { path, reason } => {
+            lines.push(format!("{prefix}Path: {}", path.display()));
+            lines.push(format!(
+                "{prefix}Codex hook-discovery policy could not be determined: {reason}"
+            ));
+        }
         DoctorDisplayDetail::Problem {
             summary,
             remediation,

cli/src/services/doctor/mod.rs

@@ -226,6 +226,18 @@ pub(super) enum IntegrationContentState {
     /// Carries a short machine-readable reason (`"untrusted"`, `"modified"`,
     /// `"disabled"`, or `"unknown"`).
     NotTrusted(String),
+    /// The registration is structurally current, but Codex's effective
+    /// hook-discovery policy (`allow_managed_hooks_only = true`) discards
+    /// every project-owned hook source, so Codex will never even consider
+    /// this handler — independent of, and checked before, trust readiness.
+    /// Carries a human-readable explanation.
+    PolicyBlocked(String),
+    /// Whether Codex's effective hook-discovery policy allows project hooks
+    /// could not be determined (no Codex executable, probe failure, timeout,
+    /// malformed response, etc.). Never treated as healthy: AC28 requires
+    /// proof Codex will actually execute the registration, and an unknown
+    /// policy is not proof. Carries a human-readable reason.
+    PolicyUnknown(String),
 }
 
 #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
@@ -271,6 +283,14 @@ pub(super) enum DoctorDisplayDetail {
         path: PathBuf,
         reason: String,
     },
+    PolicyBlocked {
+        path: PathBuf,
+        reason: String,
+    },
+    PolicyUnknown {
+        path: PathBuf,
+        reason: String,
+    },
     Problem {
         summary: String,
         remediation: String,
@@ -398,6 +418,20 @@ impl IntegrationChildHealth {
                     reason: reason.clone(),
                 }),
             ),
+            IntegrationContentState::PolicyBlocked(reason) => (
+                DoctorDisplayStatus::Fail,
+                Some(DoctorDisplayDetail::PolicyBlocked {
+                    path: self.path.clone(),
+                    reason: reason.clone(),
+                }),
+            ),
+            IntegrationContentState::PolicyUnknown(reason) => (
+                DoctorDisplayStatus::Warn,
+                Some(DoctorDisplayDetail::PolicyUnknown {
+                    path: self.path.clone(),
+                    reason: reason.clone(),
+                }),
+            ),
         };
         DoctorDisplayNode::asset(self.relative_path.clone(), status, detail)
     }
@@ -457,6 +491,8 @@ pub(crate) enum ProblemKind {
     CodexAssetReadFailed,
     CodexHookRegistrationMalformed,
     CodexHookRegistrationNotTrusted,
+    CodexHookRegistrationPolicyBlocked,
+    CodexHookRegistrationPolicyUnknown,
     AgentTraceDbConnectionFailed,
     AgentTraceDbSchemaNotReady,
 }

cli/src/services/doctor/render.rs

@@ -67,6 +67,8 @@ pub enum HealthProblemKind {
     CodexAssetReadFailed,
     CodexHookRegistrationMalformed,
     CodexHookRegistrationNotTrusted,
+    CodexHookRegistrationPolicyBlocked,
+    CodexHookRegistrationPolicyUnknown,
     AgentTraceDbConnectionFailed,
     AgentTraceDbSchemaNotReady,
 }

cli/src/services/doctor/types.rs

@@ -15,6 +15,7 @@ pub mod bash_policy;
 pub mod capabilities;
 pub mod checkout;
 pub(crate) mod codex_hook_config;
+pub(crate) mod codex_hook_policy;
 pub(crate) mod codex_hook_trust;
 pub mod command_registry;
 pub mod completion;