feat: deprecation warning (#5825)

<img width="955" height="311" alt="Screenshot 2025-10-28 at 14 26 25"
src="https://github.com/user-attachments/assets/99729b3d-3bc9-4503-aab3-8dc919220ab4"
/>

codex-rs/core/src/codex.rs

@@ -78,6 +78,7 @@ use crate::protocol::AgentReasoningSectionBreakEvent;
 use crate::protocol::ApplyPatchApprovalRequestEvent;
 use crate::protocol::AskForApproval;
 use crate::protocol::BackgroundEventEvent;
+use crate::protocol::DeprecationNoticeEvent;
 use crate::protocol::ErrorEvent;
 use crate::protocol::Event;
 use crate::protocol::EventMsg;
@@ -454,7 +455,7 @@ impl Session {
         };
 
         // Error messages to dispatch after SessionConfigured is sent.
-        let mut post_session_configured_error_events = Vec::<Event>::new();
+        let mut post_session_configured_events = Vec::<Event>::new();
 
         // Kick off independent async setup tasks in parallel to reduce startup latency.
         //
@@ -502,7 +503,7 @@ impl Session {
             Err(e) => {
                 let message = format!("Failed to create MCP connection manager: {e:#}");
                 error!("{message}");
-                post_session_configured_error_events.push(Event {
+                post_session_configured_events.push(Event {
                     id: INITIAL_SUBMIT_ID.to_owned(),
                     msg: EventMsg::Error(ErrorEvent { message }),
                 });
@@ -516,7 +517,7 @@ impl Session {
                 let auth_entry = auth_statuses.get(&server_name);
                 let display_message = mcp_init_error_display(&server_name, auth_entry, &err);
                 warn!("MCP client for `{server_name}` failed to start: {err:#}");
-                post_session_configured_error_events.push(Event {
+                post_session_configured_events.push(Event {
                     id: INITIAL_SUBMIT_ID.to_owned(),
                     msg: EventMsg::Error(ErrorEvent {
                         message: display_message,
@@ -525,6 +526,22 @@ impl Session {
             }
         }
 
+        for (alias, feature) in session_configuration.features.legacy_feature_usages() {
+            let canonical = feature.key();
+            let summary = format!("`{alias}` is deprecated. Use `{canonical}` instead.");
+            let details = if alias == canonical {
+                None
+            } else {
+                Some(format!(
+                    "You can either enable it using the CLI with `--enable {canonical}` or through the config.toml file with `[features].{canonical}`"
+                ))
+            };
+            post_session_configured_events.push(Event {
+                id: INITIAL_SUBMIT_ID.to_owned(),
+                msg: EventMsg::DeprecationNotice(DeprecationNoticeEvent { summary, details }),
+            });
+        }
+
         let otel_event_manager = OtelEventManager::new(
             conversation_id,
             config.model.as_str(),
@@ -589,7 +606,7 @@ impl Session {
                 rollout_path,
             }),
         })
-        .chain(post_session_configured_error_events.into_iter());
+        .chain(post_session_configured_events.into_iter());
         for event in events {
             sess.send_event_raw(event).await;
         }
@@ -1076,9 +1093,6 @@ impl Session {
         }
     }
 
-    /// Helper that emits a BackgroundEvent with the given message. This keeps
-    /// the call‑sites terse so adding more diagnostics does not clutter the
-    /// core agent logic.
     pub(crate) async fn notify_background_event(
         &self,
         turn_context: &TurnContext,

codex-rs/core/src/features.rs

@@ -66,10 +66,17 @@ impl Feature {
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+pub struct LegacyFeatureUsage {
+    pub alias: String,
+    pub feature: Feature,
+}
+
 /// Holds the effective set of enabled features.
 #[derive(Debug, Clone, Default, PartialEq)]
 pub struct Features {
     enabled: BTreeSet<Feature>,
+    legacy_usages: BTreeSet<LegacyFeatureUsage>,
 }
 
 #[derive(Debug, Clone, Default)]
@@ -101,7 +108,10 @@ impl Features {
                 set.insert(spec.id);
             }
         }
-        Self { enabled: set }
+        Self {
+            enabled: set,
+            legacy_usages: BTreeSet::new(),
+        }
     }
 
     pub fn enabled(&self, f: Feature) -> bool {
@@ -116,11 +126,34 @@ impl Features {
         self.enabled.remove(&f);
     }
 
+    pub fn record_legacy_usage_force(&mut self, alias: &str, feature: Feature) {
+        self.legacy_usages.insert(LegacyFeatureUsage {
+            alias: alias.to_string(),
+            feature,
+        });
+    }
+
+    pub fn record_legacy_usage(&mut self, alias: &str, feature: Feature) {
+        if alias == feature.key() {
+            return;
+        }
+        self.record_legacy_usage_force(alias, feature);
+    }
+
+    pub fn legacy_feature_usages(&self) -> impl Iterator<Item = (&str, Feature)> + '_ {
+        self.legacy_usages
+            .iter()
+            .map(|usage| (usage.alias.as_str(), usage.feature))
+    }
+
     /// Apply a table of key -> bool toggles (e.g. from TOML).
     pub fn apply_map(&mut self, m: &BTreeMap<String, bool>) {
         for (k, v) in m {
             match feature_for_key(k) {
                 Some(feat) => {
+                    if k != feat.key() {
+                        self.record_legacy_usage(k.as_str(), feat);
+                    }
                     if *v {
                         self.enable(feat);
                     } else {

codex-rs/core/src/features/legacy.rs

@@ -134,6 +134,7 @@ fn set_if_some(
     if let Some(enabled) = maybe_value {
         set_feature(features, feature, enabled);
         log_alias(alias_key, feature);
+        features.record_legacy_usage_force(alias_key, feature);
     }
 }
 

codex-rs/core/src/rollout/policy.rs

@@ -75,6 +75,7 @@ pub(crate) fn should_persist_event_msg(ev: &EventMsg) -> bool {
         | EventMsg::PlanUpdate(_)
         | EventMsg::ShutdownComplete
         | EventMsg::ViewImageToolCall(_)
+        | EventMsg::DeprecationNotice(_)
         | EventMsg::ItemStarted(_)
         | EventMsg::ItemCompleted(_) => false,
     }