refactor(core): simplify model-visible context plumbing

Fix stale DeveloperInstructions test usage, deduplicate model/realtime update text logic, add typed no-turn fragment injection, migrate plugin explicit-injection messages off the DeveloperInstructions alias, and streamline initial-context developer fragment assembly.

Co-authored-by: Codex <noreply@openai.com>

Author: charley-oai

codex-rs/core/src/agent/control.rs

@@ -7,8 +7,8 @@ use crate::error::CodexErr;
 use crate::error::Result as CodexResult;
 use crate::find_thread_path_by_id_str;
 use crate::rollout::RolloutRecorder;
+use crate::session_prefix::SubagentNotification;
 use crate::session_prefix::format_subagent_context_line;
-use crate::session_prefix::format_subagent_notification_message;
 use crate::shell_snapshot::ShellSnapshot;
 use crate::state_db;
 use crate::thread_manager::ThreadManagerState;
@@ -456,11 +456,12 @@ impl AgentControl {
             let Ok(parent_thread) = state.get_thread(parent_thread_id).await else {
                 return;
             };
+            let child_thread_id_string = child_thread_id.to_string();
             parent_thread
-                .inject_message_without_turn(
-                    MessageRole::Developer,
-                    format_subagent_notification_message(&child_thread_id.to_string(), &status),
-                )
+                .inject_model_visible_fragment_without_turn(SubagentNotification::new(
+                    &child_thread_id_string,
+                    &status,
+                ))
                 .await;
         });
     }

codex-rs/core/src/codex.rs

@@ -3218,50 +3218,54 @@ impl Session {
         if let Some(developer_instructions) = turn_context.developer_instructions.as_deref() {
             developer_envelope.push(CustomDeveloperInstructions::new(developer_instructions));
         }
-        if turn_context.features.enabled(Feature::MemoryTool)
+        let memory_prompt = if turn_context.features.enabled(Feature::MemoryTool)
             && turn_context.config.memories.use_memories
-            && let Some(memory_prompt) =
-                build_memory_tool_developer_instructions(&turn_context.config.codex_home).await
         {
-            developer_envelope.push(DeveloperTextFragment::new(memory_prompt));
-        }
-        if let Some(collab_instructions) = developer_collaboration_mode_text(&collaboration_mode) {
-            developer_envelope.push(DeveloperTextFragment::new(collab_instructions));
-        }
-        if let Some(realtime_update) = crate::context_manager::updates::build_realtime_update_item(
-            reference_context_item.as_ref(),
-            previous_turn_settings.as_ref(),
-            turn_context,
-        ) {
-            developer_envelope.push(DeveloperTextFragment::new(realtime_update));
-        }
-        if self.features.enabled(Feature::Personality)
-            && let Some(personality) = turn_context.personality
-        {
-            let model_info = turn_context.model_info.clone();
-            let has_baked_personality = model_info.supports_personality()
-                && base_instructions == model_info.get_model_instructions(Some(personality));
-            if !has_baked_personality
-                && let Some(personality_message) =
-                    crate::context_manager::updates::personality_message_for(
-                        &model_info,
-                        personality,
+            build_memory_tool_developer_instructions(&turn_context.config.codex_home).await
+        } else {
+            None
+        };
+        let personality_message = if self.features.enabled(Feature::Personality) {
+            turn_context.personality.and_then(|personality| {
+                let model_info = turn_context.model_info.clone();
+                let has_baked_personality = model_info.supports_personality()
+                    && base_instructions == model_info.get_model_instructions(Some(personality));
+                if has_baked_personality {
+                    return None;
+                }
+                crate::context_manager::updates::personality_message_for(&model_info, personality)
+                    .map(developer_personality_spec_text)
+            })
+        } else {
+            None
+        };
+        for developer_text in [
+            memory_prompt,
+            developer_collaboration_mode_text(&collaboration_mode),
+            crate::context_manager::updates::build_realtime_update_item(
+                reference_context_item.as_ref(),
+                previous_turn_settings.as_ref(),
+                turn_context,
+            ),
+            personality_message,
+            turn_context
+                .features
+                .enabled(Feature::Apps)
+                .then(render_apps_section),
+            turn_context
+                .features
+                .enabled(Feature::CodexGitCommit)
+                .then(|| {
+                    commit_message_trailer_instruction(
+                        turn_context.config.commit_attribution.as_deref(),
                     )
-            {
-                developer_envelope.push(DeveloperTextFragment::new(
-                    developer_personality_spec_text(personality_message),
-                ));
-            }
-        }
-        if turn_context.features.enabled(Feature::Apps) {
-            developer_envelope.push(DeveloperTextFragment::new(render_apps_section()));
-        }
-        if turn_context.features.enabled(Feature::CodexGitCommit)
-            && let Some(commit_message_instruction) = commit_message_trailer_instruction(
-                turn_context.config.commit_attribution.as_deref(),
-            )
+                })
+                .flatten(),
+        ]
+        .into_iter()
+        .flatten()
         {
-            developer_envelope.push(DeveloperTextFragment::new(commit_message_instruction));
+            developer_envelope.push(DeveloperTextFragment::new(developer_text));
         }
         if let Some(user_instructions) =
             <AgentsMdInstructions as TurnContextDiffFragment>::from_turn_context(

codex-rs/core/src/codex_tests.rs

@@ -10,6 +10,8 @@ use crate::config_loader::Sourced;
 use crate::exec::ExecToolCallOutput;
 use crate::function_tool::FunctionCallError;
 use crate::mcp_connection_manager::ToolInfo;
+use crate::model_visible_context::DeveloperTextFragment;
+use crate::model_visible_context::ModelVisibleContextFragment;
 use crate::models_manager::model_info;
 use crate::shell::default_user_shell;
 use crate::tools::format_exec_output_str;
@@ -52,6 +54,7 @@ use codex_protocol::models::BaseInstructions;
 use codex_protocol::models::ContentItem;
 use codex_protocol::models::ResponseInputItem;
 use codex_protocol::models::ResponseItem;
+use codex_protocol::models::developer_personality_spec_text;
 use codex_protocol::openai_models::ModelsResponse;
 use codex_protocol::protocol::ConversationAudioParams;
 use codex_protocol::protocol::RealtimeAudioFrame;
@@ -3625,7 +3628,8 @@ async fn sample_rollout(
             .as_ref()
             .and_then(|m| m.get_personality_message(Some(p)).filter(|s| !s.is_empty()))
     {
-        let msg = DeveloperInstructions::personality_spec_message(personality_message).into();
+        let msg = DeveloperTextFragment::new(developer_personality_spec_text(personality_message))
+            .into_message();
         let insert_at = initial_context
             .iter()
             .position(|m| matches!(m, ResponseItem::Message { role, .. } if role == "developer"))

codex-rs/core/src/codex_thread.rs

@@ -5,6 +5,7 @@ use crate::config::ConstraintResult;
 use crate::error::Result as CodexResult;
 use crate::features::Feature;
 use crate::file_watcher::WatchRegistration;
+use crate::model_visible_context::ModelVisibleContextFragment;
 use crate::protocol::Event;
 use crate::protocol::Op;
 use crate::protocol::Submission;
@@ -102,16 +103,27 @@ impl CodexThread {
         self.codex.session.total_token_usage().await
     }
 
+    pub(crate) async fn inject_model_visible_fragment_without_turn(
+        &self,
+        fragment: impl ModelVisibleContextFragment,
+    ) {
+        self.inject_response_input_item_without_turn(fragment.into_response_input_item())
+            .await;
+    }
+
     pub(crate) async fn inject_message_without_turn(&self, role: MessageRole, message: String) {
-        let pending_item = ResponseInputItem::Message {
+        self.inject_response_input_item_without_turn(ResponseInputItem::Message {
             role: role.to_string(),
             content: vec![ContentItem::InputText { text: message }],
-        };
-        let pending_items = vec![pending_item];
+        })
+        .await;
+    }
+
+    async fn inject_response_input_item_without_turn(&self, pending_item: ResponseInputItem) {
         let Err(items_without_active_turn) = self
             .codex
             .session
-            .inject_response_items(pending_items)
+            .inject_response_items(vec![pending_item])
             .await
         else {
             return;

codex-rs/core/src/context_manager/updates/developer_update_fragments.rs

@@ -23,6 +23,40 @@ use codex_protocol::models::developer_realtime_start_text;
 use codex_protocol::openai_models::ModelInfo;
 use codex_protocol::protocol::TurnContextItem;
 
+fn model_instructions_update_text(
+    previous_model: Option<&str>,
+    turn_context: &TurnContext,
+) -> Option<String> {
+    if previous_model == Some(turn_context.model_info.slug.as_str()) {
+        return None;
+    }
+
+    let model_instructions = turn_context
+        .model_info
+        .get_model_instructions(turn_context.personality);
+    if model_instructions.is_empty() {
+        return None;
+    }
+
+    Some(developer_model_switch_text(model_instructions))
+}
+
+fn realtime_update_text(
+    previous_realtime_active: Option<bool>,
+    current_realtime_active: bool,
+    previous_turn_settings: Option<&PreviousTurnSettings>,
+) -> Option<String> {
+    match (previous_realtime_active, current_realtime_active) {
+        (Some(true), false) => Some(developer_realtime_end_text("inactive")),
+        (Some(false), true) | (None, true) => Some(developer_realtime_start_text()),
+        (Some(true), true) | (Some(false), false) => None,
+        (None, false) => previous_turn_settings
+            .and_then(|settings| settings.realtime_active)
+            .filter(|realtime_active| *realtime_active)
+            .map(|_| developer_realtime_end_text("inactive")),
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Settings-update fragments for the developer envelope
 // ---------------------------------------------------------------------------
@@ -140,42 +174,25 @@ impl TurnContextDiffFragment for RealtimeUpdateFragment {
         turn_context: &TurnContext,
         params: &TurnContextDiffParams<'_>,
     ) -> Option<Self> {
-        if turn_context.realtime_active {
-            return Some(Self {
-                text: developer_realtime_start_text(),
-            });
-        }
-
-        params
-            .previous_turn_settings
-            .and_then(|settings| settings.realtime_active)
-            .filter(|realtime_active| *realtime_active)
-            .map(|_| Self {
-                text: developer_realtime_end_text("inactive"),
-            })
+        realtime_update_text(
+            None,
+            turn_context.realtime_active,
+            params.previous_turn_settings,
+        )
+        .map(|text| Self { text })
     }
 
     fn diff_from_turn_context_item(
         previous: &TurnContextItem,
         turn_context: &TurnContext,
         params: &TurnContextDiffParams<'_>,
     ) -> Option<Self> {
-        match (previous.realtime_active, turn_context.realtime_active) {
-            (Some(true), false) => Some(Self {
-                text: developer_realtime_end_text("inactive"),
-            }),
-            (Some(false), true) | (None, true) => Some(Self {
-                text: developer_realtime_start_text(),
-            }),
-            (Some(true), true) | (Some(false), false) => None,
-            (None, false) => params
-                .previous_turn_settings
-                .and_then(|settings| settings.realtime_active)
-                .filter(|realtime_active| *realtime_active)
-                .map(|_| Self {
-                    text: developer_realtime_end_text("inactive"),
-                }),
-        }
+        realtime_update_text(
+            previous.realtime_active,
+            turn_context.realtime_active,
+            params.previous_turn_settings,
+        )
+        .map(|text| Self { text })
     }
 }
 
@@ -250,42 +267,22 @@ impl TurnContextDiffFragment for ModelInstructionsUpdateFragment {
         turn_context: &TurnContext,
         params: &TurnContextDiffParams<'_>,
     ) -> Option<Self> {
-        let previous_turn_settings = params.previous_turn_settings?;
-        if previous_turn_settings.model == turn_context.model_info.slug {
-            return None;
-        }
-
-        let model_instructions = turn_context
-            .model_info
-            .get_model_instructions(turn_context.personality);
-        if model_instructions.is_empty() {
-            return None;
-        }
-
-        Some(Self {
-            text: developer_model_switch_text(model_instructions),
-        })
+        model_instructions_update_text(
+            params
+                .previous_turn_settings
+                .map(|settings| settings.model.as_str()),
+            turn_context,
+        )
+        .map(|text| Self { text })
     }
 
     fn diff_from_turn_context_item(
         previous: &TurnContextItem,
         turn_context: &TurnContext,
         _params: &TurnContextDiffParams<'_>,
     ) -> Option<Self> {
-        if previous.model == turn_context.model_info.slug {
-            return None;
-        }
-
-        let model_instructions = turn_context
-            .model_info
-            .get_model_instructions(turn_context.personality);
-        if model_instructions.is_empty() {
-            return None;
-        }
-
-        Some(Self {
-            text: developer_model_switch_text(model_instructions),
-        })
+        model_instructions_update_text(Some(previous.model.as_str()), turn_context)
+            .map(|text| Self { text })
     }
 }
 
@@ -359,36 +356,20 @@ pub(crate) fn build_model_instructions_update_item(
     previous_turn_settings: Option<&PreviousTurnSettings>,
     turn_context: &TurnContext,
 ) -> Option<String> {
-    let previous_turn_settings = previous_turn_settings?;
-    if previous_turn_settings.model == turn_context.model_info.slug {
-        return None;
-    }
-
-    let model_instructions = turn_context
-        .model_info
-        .get_model_instructions(turn_context.personality);
-    if model_instructions.is_empty() {
-        return None;
-    }
-
-    Some(developer_model_switch_text(model_instructions))
+    model_instructions_update_text(
+        previous_turn_settings.map(|settings| settings.model.as_str()),
+        turn_context,
+    )
 }
 
 pub(crate) fn build_realtime_update_item(
     previous: Option<&TurnContextItem>,
     previous_turn_settings: Option<&PreviousTurnSettings>,
     turn_context: &TurnContext,
 ) -> Option<String> {
-    match (
+    realtime_update_text(
         previous.and_then(|item| item.realtime_active),
         turn_context.realtime_active,
-    ) {
-        (Some(true), false) => Some(developer_realtime_end_text("inactive")),
-        (Some(false), true) | (None, true) => Some(developer_realtime_start_text()),
-        (Some(true), true) | (Some(false), false) => None,
-        (None, false) => previous_turn_settings
-            .and_then(|settings| settings.realtime_active)
-            .filter(|realtime_active| *realtime_active)
-            .map(|_| developer_realtime_end_text("inactive")),
-    }
+        previous_turn_settings,
+    )
 }

codex-rs/core/src/model_visible_context.rs

@@ -125,6 +125,13 @@ pub(crate) trait ModelVisibleContextFragment {
     {
         model_visible_message::<Self::Role>(self.render_text())
     }
+
+    fn into_response_input_item(self) -> ResponseInputItem
+    where
+        Self: Sized,
+    {
+        model_visible_response_input_item::<Self::Role>(self.render_text())
+    }
 }
 
 pub(crate) struct DeveloperTextFragment {