core: bundle settings diff updates into one dev/user envelope (#12417)

## Summary
- bundle contextual prompt injection into at most one developer message
plus one contextual user message in both:
  - per-turn settings updates
  - initial context insertion
- preserve `<model_switch>` across compaction by rebuilding it through
canonical initial-context injection, instead of relying on
strip/reattach hacks
- centralize contextual user fragment detection in one shared definition
table and reuse it for parsing/compaction logic
- keep `AGENTS.md` in its natural serialized format:
  - `# AGENTS.md instructions for {dirname}`
  - `<INSTRUCTIONS>...</INSTRUCTIONS>`
- simplify related tests/helpers and accept the expected snapshot/layout
updates from bundled multi-part messages

## Why
The goal is to converge toward a simpler, more intentional prompt shape
where contextual updates are consistently represented as one developer
envelope plus one contextual user envelope, while keeping parsing and
compaction behavior aligned with that representation.

## Notable details
- the temporary `SettingsUpdateEnvelope` wrapper was removed; these
paths now return `Vec<ResponseItem>` directly
- local/remote compaction no longer rely on model-switch strip/restore
helpers
- contextual user detection is now driven by shared fragment definitions
instead of ad hoc matcher assembly
- AGENTS/user instructions are still the same logical context; only the
synthetic `<user_instructions>` wrapper was replaced by the natural
AGENTS text format

## Testing
- `just fmt`
- `cargo test -p codex-app-server
codex_message_processor::tests::extract_conversation_summary_prefers_plain_user_messages
-- --exact`
- `cargo test -p codex-core
compact::tests::collect_user_messages_filters_session_prefix_entries
--lib -- --exact`
- `cargo test -p codex-core --test all
'suite::compact::snapshot_request_shape_pre_turn_compaction_strips_incoming_model_switch'
-- --exact`
- `cargo test -p codex-core --test all
'suite::compact_remote::snapshot_request_shape_remote_pre_turn_compaction_strips_incoming_model_switch'
-- --exact`
- `cargo test -p codex-core --test all
'suite::client::includes_apps_guidance_as_developer_message_when_enabled'
-- --exact`
- `cargo test -p codex-core --test all
'suite::client::includes_developer_instructions_message_in_request' --
--exact`
- `cargo test -p codex-core --test all
'suite::client::includes_user_instructions_message_in_request' --
--exact`
- `cargo test -p codex-core --test all
'suite::client::resume_includes_initial_messages_and_sends_prior_items'
-- --exact`
- `cargo test -p codex-core --test all
'suite::review::review_input_isolated_from_parent_history' -- --exact`
- `cargo test -p codex-exec --test all
'suite::resume::exec_resume_last_respects_cwd_filter_and_all_flag' --
--exact`
- `cargo test -p core_test_support
context_snapshot::tests::full_text_mode_preserves_unredacted_text --
--exact`

## Notes
- I also ran several targeted `compact`, `compact_remote`,
`prompt_caching`, `model_visible_layout`, and `event_mapping` tests
while iterating on prompt-shape changes.
- I have not claimed a clean full-workspace `cargo test` from this
environment because local sandbox/resource conditions have previously
produced unrelated failures in large workspace runs.

codex-rs/core/src/context_manager/history.rs

@@ -1,14 +1,11 @@
 use crate::codex::TurnContext;
 use crate::context_manager::normalize;
-use crate::instructions::SkillInstructions;
-use crate::instructions::UserInstructions;
-use crate::session_prefix::is_session_prefix;
+use crate::event_mapping::is_contextual_user_message_content;
 use crate::truncate::TruncationPolicy;
 use crate::truncate::approx_token_count;
 use crate::truncate::approx_tokens_from_byte_count_i64;
 use crate::truncate::truncate_function_output_items_with_policy;
 use crate::truncate::truncate_text;
-use crate::user_shell_command::is_user_shell_command_text;
 use codex_protocol::models::BaseInstructions;
 use codex_protocol::models::ContentItem;
 use codex_protocol::models::FunctionCallOutputBody;
@@ -554,33 +551,7 @@ pub(crate) fn is_user_turn_boundary(item: &ResponseItem) -> bool {
         return false;
     };
 
-    if role != "user" {
-        return false;
-    }
-
-    if UserInstructions::is_user_instructions(content)
-        || SkillInstructions::is_skill_instructions(content)
-    {
-        return false;
-    }
-
-    for content_item in content {
-        match content_item {
-            ContentItem::InputText { text } => {
-                if is_session_prefix(text) || is_user_shell_command_text(text) {
-                    return false;
-                }
-            }
-            ContentItem::OutputText { text } => {
-                if is_session_prefix(text) {
-                    return false;
-                }
-            }
-            ContentItem::InputImage { .. } => {}
-        }
-    }
-
-    true
+    role == "user" && !is_contextual_user_message_content(content)
 }
 
 fn user_message_positions(items: &[ResponseItem]) -> Vec<usize> {

codex-rs/core/src/context_manager/history_tests.rs

@@ -563,7 +563,6 @@ fn drop_last_n_user_turns_preserves_prefix() {
 fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
     let items = vec![
         user_input_text_msg("<environment_context>ctx</environment_context>"),
-        user_input_text_msg("<user_instructions>do the thing</user_instructions>"),
         user_input_text_msg(
             "# AGENTS.md instructions for test_directory\n\n<INSTRUCTIONS>\ntest_text\n</INSTRUCTIONS>",
         ),
@@ -586,7 +585,6 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
 
     let expected_prefix_and_first_turn = vec![
         user_input_text_msg("<environment_context>ctx</environment_context>"),
-        user_input_text_msg("<user_instructions>do the thing</user_instructions>"),
         user_input_text_msg(
             "# AGENTS.md instructions for test_directory\n\n<INSTRUCTIONS>\ntest_text\n</INSTRUCTIONS>",
         ),
@@ -608,7 +606,6 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
 
     let expected_prefix_only = vec![
         user_input_text_msg("<environment_context>ctx</environment_context>"),
-        user_input_text_msg("<user_instructions>do the thing</user_instructions>"),
         user_input_text_msg(
             "# AGENTS.md instructions for test_directory\n\n<INSTRUCTIONS>\ntest_text\n</INSTRUCTIONS>",
         ),
@@ -623,7 +620,6 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
 
     let mut history = create_history_with_items(vec![
         user_input_text_msg("<environment_context>ctx</environment_context>"),
-        user_input_text_msg("<user_instructions>do the thing</user_instructions>"),
         user_input_text_msg(
             "# AGENTS.md instructions for test_directory\n\n<INSTRUCTIONS>\ntest_text\n</INSTRUCTIONS>",
         ),
@@ -644,7 +640,6 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
 
     let mut history = create_history_with_items(vec![
         user_input_text_msg("<environment_context>ctx</environment_context>"),
-        user_input_text_msg("<user_instructions>do the thing</user_instructions>"),
         user_input_text_msg(
             "# AGENTS.md instructions for test_directory\n\n<INSTRUCTIONS>\ntest_text\n</INSTRUCTIONS>",
         ),

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

@@ -4,6 +4,7 @@ use crate::features::Feature;
 use crate::shell::Shell;
 use codex_execpolicy::Policy;
 use codex_protocol::config_types::Personality;
+use codex_protocol::models::ContentItem;
 use codex_protocol::models::DeveloperInstructions;
 use codex_protocol::models::ResponseItem;
 use codex_protocol::openai_models::ModelInfo;
@@ -30,7 +31,7 @@ fn build_permissions_update_item(
     previous: Option<&TurnContextItem>,
     next: &TurnContext,
     exec_policy: &Policy,
-) -> Option<ResponseItem> {
+) -> Option<DeveloperInstructions> {
     let prev = previous?;
     if prev.sandbox_policy == *next.sandbox_policy.get()
         && prev.approval_policy == next.approval_policy.value()
@@ -38,27 +39,26 @@ fn build_permissions_update_item(
         return None;
     }
 
-    Some(
-        DeveloperInstructions::from_policy(
-            next.sandbox_policy.get(),
-            next.approval_policy.value(),
-            exec_policy,
-            &next.cwd,
-            next.features.enabled(Feature::RequestPermissions),
-        )
-        .into(),
-    )
+    Some(DeveloperInstructions::from_policy(
+        next.sandbox_policy.get(),
+        next.approval_policy.value(),
+        exec_policy,
+        &next.cwd,
+        next.features.enabled(Feature::RequestPermissions),
+    ))
 }
 
 fn build_collaboration_mode_update_item(
     previous: Option<&TurnContextItem>,
     next: &TurnContext,
-) -> Option<ResponseItem> {
+) -> Option<DeveloperInstructions> {
     let prev = previous?;
     if prev.collaboration_mode.as_ref() != Some(&next.collaboration_mode) {
         // If the next mode has empty developer instructions, this returns None and we emit no
         // update, so prior collaboration instructions remain in the prompt history.
-        Some(DeveloperInstructions::from_collaboration_mode(&next.collaboration_mode)?.into())
+        Some(DeveloperInstructions::from_collaboration_mode(
+            &next.collaboration_mode,
+        )?)
     } else {
         None
     }
@@ -68,7 +68,7 @@ fn build_personality_update_item(
     previous: Option<&TurnContextItem>,
     next: &TurnContext,
     personality_feature_enabled: bool,
-) -> Option<ResponseItem> {
+) -> Option<DeveloperInstructions> {
     if !personality_feature_enabled {
         return None;
     }
@@ -82,8 +82,7 @@ fn build_personality_update_item(
     {
         let model_info = &next.model_info;
         let personality_message = personality_message_for(model_info, personality);
-        personality_message
-            .map(|message| DeveloperInstructions::personality_spec_message(message).into())
+        personality_message.map(DeveloperInstructions::personality_spec_message)
     } else {
         None
     }
@@ -103,7 +102,7 @@ pub(crate) fn personality_message_for(
 pub(crate) fn build_model_instructions_update_item(
     previous_user_turn_model: Option<&str>,
     next: &TurnContext,
-) -> Option<ResponseItem> {
+) -> Option<DeveloperInstructions> {
     let previous_model = previous_user_turn_model?;
     if previous_model == next.model_info.slug {
         return None;
@@ -114,7 +113,36 @@ pub(crate) fn build_model_instructions_update_item(
         return None;
     }
 
-    Some(DeveloperInstructions::model_switch_message(model_instructions).into())
+    Some(DeveloperInstructions::model_switch_message(
+        model_instructions,
+    ))
+}
+
+pub(crate) fn build_developer_update_item(text_sections: Vec<String>) -> Option<ResponseItem> {
+    build_text_message("developer", text_sections)
+}
+
+pub(crate) fn build_contextual_user_message(text_sections: Vec<String>) -> Option<ResponseItem> {
+    build_text_message("user", text_sections)
+}
+
+fn build_text_message(role: &str, text_sections: Vec<String>) -> Option<ResponseItem> {
+    if text_sections.is_empty() {
+        return None;
+    }
+
+    let content = text_sections
+        .into_iter()
+        .map(|text| ContentItem::InputText { text })
+        .collect();
+
+    Some(ResponseItem::Message {
+        id: None,
+        role: role.to_string(),
+        content,
+        end_turn: None,
+        phase: None,
+    })
 }
 
 pub(crate) fn build_settings_update_items(
@@ -125,29 +153,26 @@ pub(crate) fn build_settings_update_items(
     exec_policy: &Policy,
     personality_feature_enabled: bool,
 ) -> Vec<ResponseItem> {
-    let mut update_items = Vec::new();
+    let contextual_user_message = build_environment_update_item(previous, next, shell);
+    let developer_update_sections = [
+        // Keep model-switch instructions first so model-specific guidance is read before
+        // any other context diffs on this turn.
+        build_model_instructions_update_item(previous_user_turn_model, next),
+        build_permissions_update_item(previous, next, exec_policy),
+        build_collaboration_mode_update_item(previous, next),
+        build_personality_update_item(previous, next, personality_feature_enabled),
+    ]
+    .into_iter()
+    .flatten()
+    .map(DeveloperInstructions::into_text)
+    .collect();
 
-    // Keep model-switch instructions first so model-specific guidance is read before
-    // any other context diffs on this turn.
-    if let Some(model_instructions_item) =
-        build_model_instructions_update_item(previous_user_turn_model, next)
-    {
-        update_items.push(model_instructions_item);
+    let mut items = Vec::with_capacity(2);
+    if let Some(developer_message) = build_developer_update_item(developer_update_sections) {
+        items.push(developer_message);
     }
-    if let Some(env_item) = build_environment_update_item(previous, next, shell) {
-        update_items.push(env_item);
+    if let Some(contextual_user_message) = contextual_user_message {
+        items.push(contextual_user_message);
     }
-    if let Some(permissions_item) = build_permissions_update_item(previous, next, exec_policy) {
-        update_items.push(permissions_item);
-    }
-    if let Some(collaboration_mode_item) = build_collaboration_mode_update_item(previous, next) {
-        update_items.push(collaboration_mode_item);
-    }
-    if let Some(personality_item) =
-        build_personality_update_item(previous, next, personality_feature_enabled)
-    {
-        update_items.push(personality_item);
-    }
-
-    update_items
+    items
 }