codex: keep test developer instructions at config root (#16976)

codex-rs/app-server/tests/common/rollout.rs

@@ -84,6 +84,7 @@ pub fn create_fake_rollout_with_source(
         agent_role: None,
         model_provider: model_provider.map(str::to_string),
         base_instructions: None,
+        developer_instructions: None,
         dynamic_tools: None,
         memory_mode: None,
     };
@@ -167,6 +168,7 @@ pub fn create_fake_rollout_with_text_elements(
         agent_role: None,
         model_provider: model_provider.map(str::to_string),
         base_instructions: None,
+        developer_instructions: None,
         dynamic_tools: None,
         memory_mode: None,
     };

codex-rs/app-server/tests/suite/v2/thread_fork.rs

@@ -200,6 +200,16 @@ async fn thread_fork_honors_explicit_null_thread_instructions() -> Result<()> {
 
     let codex_home = TempDir::new()?;
     create_config_toml(codex_home.path(), &server.uri())?;
+    let config_path = codex_home.path().join("config.toml");
+    let mut config_toml = std::fs::read_to_string(&config_path)?;
+    let first_table_index = config_toml
+        .find("\n[")
+        .expect("test config must include a table header");
+    config_toml.insert_str(
+        first_table_index,
+        "\ndeveloper_instructions = \"Config developer instructions sentinel\"\n",
+    );
+    std::fs::write(config_path, config_toml)?;
 
     let conversation_id = create_fake_rollout(
         codex_home.path(),
@@ -323,6 +333,13 @@ async fn thread_fork_honors_explicit_null_thread_instructions() -> Result<()> {
             "unexpected instructions field in payload: {payload:?}"
         );
         let developer_texts = request.message_input_texts("developer");
+        assert_eq!(
+            developer_texts
+                .iter()
+                .any(|text| { text.contains("Config developer instructions sentinel") }),
+            expect_instructions,
+            "unexpected config developer instruction presence: {developer_texts:?}"
+        );
         assert!(
             developer_texts.iter().all(|text| !text.is_empty()),
             "did not expect empty developer instruction messages: {developer_texts:?}"

codex-rs/app-server/tests/suite/v2/thread_resume.rs

@@ -377,6 +377,7 @@ stream_max_retries = 0
         agent_role: None,
         model_provider: Some("mock_provider".to_string()),
         base_instructions: None,
+        developer_instructions: None,
         dynamic_tools: None,
         memory_mode: None,
     };

codex-rs/app-server/tests/suite/v2/turn_start.rs

@@ -166,6 +166,16 @@ async fn turn_start_honors_explicit_null_thread_instructions() -> Result<()> {
 
     let codex_home = TempDir::new()?;
     create_config_toml(codex_home.path(), &server.uri(), "never", &BTreeMap::new())?;
+    let config_path = codex_home.path().join("config.toml");
+    let mut config_toml = std::fs::read_to_string(&config_path)?;
+    let first_table_index = config_toml
+        .find("\n[")
+        .expect("test config must include a table header");
+    config_toml.insert_str(
+        first_table_index,
+        "\ndeveloper_instructions = \"Config developer instructions sentinel\"\n",
+    );
+    std::fs::write(config_path, config_toml)?;
 
     let mut mcp = McpProcess::new(codex_home.path()).await?;
     timeout(DEFAULT_READ_TIMEOUT, mcp.initialize()).await??;
@@ -240,6 +250,13 @@ async fn turn_start_honors_explicit_null_thread_instructions() -> Result<()> {
             "unexpected instructions field in payload: {payload:?}"
         );
         let developer_texts = request.message_input_texts("developer");
+        assert_eq!(
+            developer_texts
+                .iter()
+                .any(|text| { text.contains("Config developer instructions sentinel") }),
+            expect_instructions,
+            "unexpected config developer instruction presence: {developer_texts:?}"
+        );
         assert!(
             developer_texts.iter().all(|text| !text.is_empty()),
             "did not expect empty developer instruction messages: {developer_texts:?}"

codex-rs/core/src/codex.rs

@@ -618,6 +618,14 @@ impl Codex {
             dynamic_tools
         };
 
+        let developer_instructions_override = config
+            .developer_instructions_override
+            .clone()
+            .or_else(|| conversation_history.get_developer_instructions());
+        let developer_instructions = developer_instructions_override
+            .clone()
+            .unwrap_or_else(|| config.developer_instructions.clone());
+
         // TODO (aibrahim): Consolidate config.model and config.model_reasoning_effort into config.collaboration_mode
         // to avoid extracting these fields separately and constructing CollaborationMode here.
         let collaboration_mode = CollaborationMode {
@@ -633,7 +641,8 @@ impl Codex {
             collaboration_mode,
             model_reasoning_summary: config.model_reasoning_summary,
             service_tier: config.service_tier,
-            developer_instructions: config.developer_instructions.clone(),
+            developer_instructions,
+            developer_instructions_override,
             user_instructions,
             personality: config.personality,
             base_instructions,
@@ -1103,6 +1112,10 @@ pub(crate) struct SessionConfiguration {
     /// Developer instructions that supplement the base instructions.
     developer_instructions: Option<String>,
 
+    /// Explicit developer instructions override, preserving `null` as distinct
+    /// from a missing override.
+    developer_instructions_override: Option<Option<String>>,
+
     /// Model instructions that are appended to the base instructions.
     user_instructions: Option<String>,
 
@@ -1553,6 +1566,9 @@ impl Session {
                             .base_instructions
                             .clone()
                             .map(|text| BaseInstructions { text }),
+                        session_configuration
+                            .developer_instructions_override
+                            .clone(),
                         session_configuration.dynamic_tools.clone(),
                         if session_configuration.persist_extended_history {
                             EventPersistenceMode::Extended

codex-rs/core/src/codex_tests.rs

@@ -1853,6 +1853,7 @@ async fn set_rate_limits_retains_previous_credits() {
         collaboration_mode,
         model_reasoning_summary: config.model_reasoning_summary,
         developer_instructions: config.developer_instructions.clone(),
+        developer_instructions_override: config.developer_instructions_override.clone(),
         user_instructions: config.user_instructions.clone(),
         service_tier: None,
         personality: config.personality,
@@ -1955,6 +1956,7 @@ async fn set_rate_limits_updates_plan_type_when_present() {
         collaboration_mode,
         model_reasoning_summary: config.model_reasoning_summary,
         developer_instructions: config.developer_instructions.clone(),
+        developer_instructions_override: config.developer_instructions_override.clone(),
         user_instructions: config.user_instructions.clone(),
         service_tier: None,
         personality: config.personality,
@@ -2227,6 +2229,7 @@ async fn attach_rollout_recorder(session: &Arc<Session>) -> PathBuf {
             /*forked_from_id*/ None,
             SessionSource::Exec,
             Some(BaseInstructions::default()),
+            /*developer_instructions*/ None,
             Vec::new(),
             EventPersistenceMode::Limited,
         ),
@@ -2304,6 +2307,7 @@ pub(crate) async fn make_session_configuration_for_tests() -> SessionConfigurati
         collaboration_mode,
         model_reasoning_summary: config.model_reasoning_summary,
         developer_instructions: config.developer_instructions.clone(),
+        developer_instructions_override: config.developer_instructions_override.clone(),
         user_instructions: config.user_instructions.clone(),
         service_tier: None,
         personality: config.personality,
@@ -2570,6 +2574,7 @@ async fn session_new_fails_when_zsh_fork_enabled_without_zsh_path() {
         collaboration_mode,
         model_reasoning_summary: config.model_reasoning_summary,
         developer_instructions: config.developer_instructions.clone(),
+        developer_instructions_override: config.developer_instructions_override.clone(),
         user_instructions: config.user_instructions.clone(),
         service_tier: None,
         personality: config.personality,
@@ -2673,6 +2678,7 @@ pub(crate) async fn make_session_and_context() -> (Session, TurnContext) {
         collaboration_mode,
         model_reasoning_summary: config.model_reasoning_summary,
         developer_instructions: config.developer_instructions.clone(),
+        developer_instructions_override: config.developer_instructions_override.clone(),
         user_instructions: config.user_instructions.clone(),
         service_tier: None,
         personality: config.personality,
@@ -3513,6 +3519,7 @@ pub(crate) async fn make_session_and_context_with_dynamic_tools_and_rx(
         collaboration_mode,
         model_reasoning_summary: config.model_reasoning_summary,
         developer_instructions: config.developer_instructions.clone(),
+        developer_instructions_override: config.developer_instructions_override.clone(),
         user_instructions: config.user_instructions.clone(),
         service_tier: None,
         personality: config.personality,
@@ -4089,13 +4096,18 @@ async fn handle_output_item_done_records_image_save_history_message() {
     let image_output_dir = image_output_path
         .parent()
         .expect("generated image path should have a parent");
-    let image_message: ResponseItem = DeveloperInstructions::new(format!(
-        "Generated images are saved to {} as {} by default.\nIf you need to use a generated image at another path, copy it and leave the original in place unless the user explicitly asks you to delete it.",
+    let save_message: ResponseItem = DeveloperInstructions::new(format!(
+        "Generated images are saved to {} as {} by default.",
         image_output_dir.display(),
         image_output_path.display(),
     ))
     .into();
-    assert_eq!(history.raw_items(), &[image_message, item]);
+    let copy_message: ResponseItem = DeveloperInstructions::new(
+        "If you need to use a generated image at another path, copy it and leave the original in place unless the user explicitly asks you to delete it."
+            .to_string(),
+    )
+    .into();
+    assert_eq!(history.raw_items(), &[save_message, copy_message, item]);
     assert_eq!(
         std::fs::read(&expected_saved_path).expect("saved file"),
         b"foo"
@@ -4264,6 +4276,7 @@ async fn record_context_updates_and_set_reference_context_item_persists_baseline
             /*forked_from_id*/ None,
             SessionSource::Exec,
             Some(BaseInstructions::default()),
+            /*developer_instructions*/ None,
             Vec::new(),
             EventPersistenceMode::Limited,
         ),
@@ -4361,6 +4374,7 @@ async fn record_context_updates_and_set_reference_context_item_persists_full_rei
             /*forked_from_id*/ None,
             SessionSource::Exec,
             Some(BaseInstructions::default()),
+            /*developer_instructions*/ None,
             Vec::new(),
             EventPersistenceMode::Limited,
         ),

codex-rs/core/src/config/config_tests.rs

@@ -4506,6 +4506,7 @@ fn test_precedence_fixture_with_o3_profile() -> std::io::Result<()> {
             experimental_realtime_ws_startup_context: None,
             base_instructions: None,
             developer_instructions: None,
+            developer_instructions_override: None,
             guardian_developer_instructions: None,
             include_permissions_instructions: true,
             include_apps_instructions: true,
@@ -4651,6 +4652,7 @@ fn test_precedence_fixture_with_gpt3_profile() -> std::io::Result<()> {
         experimental_realtime_ws_startup_context: None,
         base_instructions: None,
         developer_instructions: None,
+        developer_instructions_override: None,
         guardian_developer_instructions: None,
         include_permissions_instructions: true,
         include_apps_instructions: true,
@@ -4794,6 +4796,7 @@ fn test_precedence_fixture_with_zdr_profile() -> std::io::Result<()> {
         experimental_realtime_ws_startup_context: None,
         base_instructions: None,
         developer_instructions: None,
+        developer_instructions_override: None,
         guardian_developer_instructions: None,
         include_permissions_instructions: true,
         include_apps_instructions: true,
@@ -4923,6 +4926,7 @@ fn test_precedence_fixture_with_gpt5_profile() -> std::io::Result<()> {
         experimental_realtime_ws_startup_context: None,
         base_instructions: None,
         developer_instructions: None,
+        developer_instructions_override: None,
         guardian_developer_instructions: None,
         include_permissions_instructions: true,
         include_apps_instructions: true,

codex-rs/core/src/config/mod.rs

@@ -248,6 +248,10 @@ pub struct Config {
     /// Developer instructions override injected as a separate message.
     pub developer_instructions: Option<String>,
 
+    /// Explicit developer instructions override, preserving `null` as distinct
+    /// from a missing override.
+    pub developer_instructions_override: Option<Option<String>>,
+
     /// Guardian-specific developer instructions override from requirements.toml.
     pub guardian_developer_instructions: Option<String>,
 
@@ -1761,6 +1765,7 @@ impl Config {
         let file_base_instructions =
             Self::try_read_non_empty_file(model_instructions_path, "model instructions file")?;
         let base_instructions = base_instructions.or_else(|| file_base_instructions.map(Some));
+        let developer_instructions_override = developer_instructions.clone();
         let developer_instructions =
             developer_instructions.unwrap_or_else(|| cfg.developer_instructions.clone());
         let include_permissions_instructions = config_profile
@@ -1945,6 +1950,7 @@ impl Config {
             base_instructions,
             personality,
             developer_instructions,
+            developer_instructions_override,
             compact_prompt,
             commit_attribution,
             include_permissions_instructions,

codex-rs/core/src/personality_migration_tests.rs

@@ -43,6 +43,7 @@ async fn write_session_with_user_event(codex_home: &Path) -> io::Result<()> {
             agent_role: None,
             model_provider: None,
             base_instructions: None,
+            developer_instructions: None,
             dynamic_tools: None,
             memory_mode: None,
         },

codex-rs/core/src/stream_events_utils.rs

@@ -379,12 +379,17 @@ pub(crate) async fn handle_non_tool_response_item(
                             .parent()
                             .unwrap_or(turn_context.config.codex_home.as_path());
                         let message: ResponseItem = DeveloperInstructions::new(format!(
-                            "Generated images are saved to {} as {} by default.\nIf you need to use a generated image at another path, copy it and leave the original in place unless the user explicitly asks you to delete it.",
+                            "Generated images are saved to {} as {} by default.",
                             image_output_dir.display(),
                             image_output_path.display(),
                         ))
                         .into();
-                        sess.record_conversation_items(turn_context, &[message])
+                        let copy_message: ResponseItem = DeveloperInstructions::new(
+                            "If you need to use a generated image at another path, copy it and leave the original in place unless the user explicitly asks you to delete it."
+                                .to_string(),
+                        )
+                        .into();
+                        sess.record_conversation_items(turn_context, &[message, copy_message])
                             .await;
                     }
                     Err(err) => {

codex-rs/core/tests/common/test_codex.rs

@@ -49,8 +49,8 @@ use crate::responses::WebSocketTestServer;
 use crate::responses::output_value_to_text;
 use crate::responses::start_mock_server;
 use crate::streaming_sse::StreamingSseServer;
+use crate::wait_for_event;
 use crate::wait_for_event_match;
-use crate::wait_for_event_with_timeout;
 use wiremock::Match;
 use wiremock::matchers::path_regex;
 
@@ -767,14 +767,10 @@ impl TestCodex {
             _ => None,
         })
         .await;
-        wait_for_event_with_timeout(
-            &self.codex,
-            |event| match event {
-                EventMsg::TurnComplete(event) => event.turn_id == turn_id,
-                _ => false,
-            },
-            Duration::from_secs(60),
-        )
+        wait_for_event(&self.codex, |event| match event {
+            EventMsg::TurnComplete(event) => event.turn_id == turn_id,
+            _ => false,
+        })
         .await;
         Ok(())
     }

codex-rs/core/tests/suite/personality_migration.rs

@@ -71,6 +71,7 @@ async fn write_rollout_with_user_event(dir: &Path, thread_id: ThreadId) -> io::R
             agent_role: None,
             model_provider: None,
             base_instructions: None,
+            developer_instructions: None,
             dynamic_tools: None,
             memory_mode: None,
         },
@@ -116,6 +117,7 @@ async fn write_rollout_with_meta_only(dir: &Path, thread_id: ThreadId) -> io::Re
             agent_role: None,
             model_provider: None,
             base_instructions: None,
+            developer_instructions: None,
             dynamic_tools: None,
             memory_mode: None,
         },

codex-rs/core/tests/suite/rollout_list_find.rs

@@ -174,6 +174,7 @@ async fn find_locates_rollout_file_written_by_recorder() -> std::io::Result<()>
             /*forked_from_id*/ None,
             SessionSource::Exec,
             Some(BaseInstructions::default()),
+            /*developer_instructions*/ None,
             Vec::new(),
             EventPersistenceMode::Limited,
         ),

codex-rs/core/tests/suite/sqlite_state.rs

@@ -146,6 +146,7 @@ async fn backfill_scans_existing_rollouts() -> Result<()> {
                     agent_role: None,
                     model_provider: None,
                     base_instructions: None,
+                    developer_instructions: None,
                     dynamic_tools: Some(dynamic_tools_for_hook),
                     memory_mode: None,
                 },

codex-rs/protocol/src/protocol.rs

@@ -2351,6 +2351,26 @@ impl InitialHistory {
         }
     }
 
+    pub fn get_developer_instructions(&self) -> Option<Option<String>> {
+        match self {
+            InitialHistory::New => None,
+            InitialHistory::Resumed(resumed) => {
+                resumed.history.iter().find_map(|item| match item {
+                    RolloutItem::SessionMeta(meta_line) => {
+                        meta_line.meta.developer_instructions.clone()
+                    }
+                    _ => None,
+                })
+            }
+            InitialHistory::Forked(items) => items.iter().find_map(|item| match item {
+                RolloutItem::SessionMeta(meta_line) => {
+                    meta_line.meta.developer_instructions.clone()
+                }
+                _ => None,
+            }),
+        }
+    }
+
     pub fn get_dynamic_tools(&self) -> Option<Vec<DynamicToolSpec>> {
         match self {
             InitialHistory::New => None,
@@ -2549,6 +2569,13 @@ pub struct SessionMeta {
         skip_serializing_if = "Option::is_none"
     )]
     pub base_instructions: Option<Option<BaseInstructions>>,
+    #[serde(
+        default,
+        deserialize_with = "deserialize_double_option",
+        serialize_with = "serialize_double_option",
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub developer_instructions: Option<Option<String>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub dynamic_tools: Option<Vec<DynamicToolSpec>>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -2570,6 +2597,7 @@ impl Default for SessionMeta {
             agent_path: None,
             model_provider: None,
             base_instructions: None,
+            developer_instructions: None,
             dynamic_tools: None,
             memory_mode: None,
         }

codex-rs/rollout/src/metadata_tests.rs

@@ -56,6 +56,7 @@ async fn extract_metadata_from_rollout_uses_session_meta() {
         agent_role: None,
         model_provider: Some("openai".to_string()),
         base_instructions: None,
+        developer_instructions: None,
         dynamic_tools: None,
         memory_mode: None,
     };
@@ -107,6 +108,7 @@ async fn extract_metadata_from_rollout_returns_latest_memory_mode() {
         agent_role: None,
         model_provider: Some("openai".to_string()),
         base_instructions: None,
+        developer_instructions: None,
         dynamic_tools: None,
         memory_mode: None,
     };
@@ -369,6 +371,7 @@ fn write_rollout_in_sessions_with_cwd(
         agent_role: None,
         model_provider: Some("test-provider".to_string()),
         base_instructions: None,
+        developer_instructions: None,
         dynamic_tools: None,
         memory_mode: None,
     };

codex-rs/rollout/src/recorder.rs

@@ -82,6 +82,7 @@ pub enum RolloutRecorderParams {
         forked_from_id: Option<ThreadId>,
         source: SessionSource,
         base_instructions: Option<BaseInstructions>,
+        developer_instructions: Option<Option<String>>,
         dynamic_tools: Vec<DynamicToolSpec>,
         event_persistence_mode: EventPersistenceMode,
     },
@@ -111,6 +112,7 @@ impl RolloutRecorderParams {
         forked_from_id: Option<ThreadId>,
         source: SessionSource,
         base_instructions: Option<BaseInstructions>,
+        developer_instructions: Option<Option<String>>,
         dynamic_tools: Vec<DynamicToolSpec>,
         event_persistence_mode: EventPersistenceMode,
     ) -> Self {
@@ -119,6 +121,7 @@ impl RolloutRecorderParams {
             forked_from_id,
             source,
             base_instructions,
+            developer_instructions,
             dynamic_tools,
             event_persistence_mode,
         }
@@ -380,6 +383,7 @@ impl RolloutRecorder {
                     forked_from_id,
                     source,
                     base_instructions,
+                    developer_instructions,
                     dynamic_tools,
                     event_persistence_mode,
                 } => {
@@ -409,6 +413,7 @@ impl RolloutRecorder {
                         source,
                         model_provider: Some(config.model_provider_id().to_string()),
                         base_instructions: Some(base_instructions),
+                        developer_instructions,
                         dynamic_tools: if dynamic_tools.is_empty() {
                             None
                         } else {

codex-rs/rollout/src/recorder_tests.rs

@@ -74,6 +74,7 @@ async fn recorder_materializes_only_after_explicit_persist() -> std::io::Result<
             /*forked_from_id*/ None,
             SessionSource::Exec,
             Some(BaseInstructions::default()),
+            /*developer_instructions*/ None,
             Vec::new(),
             EventPersistenceMode::Limited,
         ),
@@ -167,6 +168,7 @@ async fn metadata_irrelevant_events_touch_state_db_updated_at() -> std::io::Resu
             /*forked_from_id*/ None,
             SessionSource::Cli,
             Some(BaseInstructions::default()),
+            /*developer_instructions*/ None,
             Vec::new(),
             EventPersistenceMode::Limited,
         ),

codex-rs/rollout/src/tests.rs

@@ -1140,6 +1140,7 @@ async fn test_updated_at_uses_file_mtime() -> Result<()> {
                 agent_role: None,
                 model_provider: Some("test-provider".into()),
                 base_instructions: None,
+                developer_instructions: None,
                 dynamic_tools: None,
                 memory_mode: None,
             },

codex-rs/state/src/extract.rs

@@ -257,6 +257,7 @@ mod tests {
                     agent_role: None,
                     model_provider: Some("openai".to_string()),
                     base_instructions: None,
+                    developer_instructions: None,
                     dynamic_tools: None,
                     memory_mode: None,
                 },
@@ -384,6 +385,7 @@ mod tests {
                     agent_role: None,
                     model_provider: Some("openai".to_string()),
                     base_instructions: None,
+                    developer_instructions: None,
                     dynamic_tools: None,
                     memory_mode: None,
                 },

codex-rs/state/src/runtime/threads.rs

@@ -1030,6 +1030,7 @@ mod tests {
                 agent_role: None,
                 model_provider: None,
                 base_instructions: None,
+                developer_instructions: None,
                 dynamic_tools: None,
                 memory_mode: Some("polluted".to_string()),
             },
@@ -1088,6 +1089,7 @@ mod tests {
                 agent_role: None,
                 model_provider: None,
                 base_instructions: None,
+                developer_instructions: None,
                 dynamic_tools: None,
                 memory_mode: None,
             },