Allow model catalogs to set initial collaboration guidance (#62896)

## Why

Model catalogs could provide guidance for Plan and for Default after Plan,
but had no field for the turns before the first Plan turn.

## What changed

Add optional `collaboration_modes.initial` guidance. Codex uses it in
Default before the first Plan turn when the field is nonempty and no
caller-supplied instructions take precedence.

## Testing

Add a request snapshot test that covers initial guidance on a new thread,
retains it after resume, and verifies the switch to Plan guidance and then
to Default guidance when leaving Plan.

GitOrigin-RevId: bb9e83aeb60af54fc2ee1bf9ce5acbb8a354ffb8
This commit is contained in:
Dylan Hurd
2026-11-21 04:18:31 +00:00
committed by copyberry
parent 4739e94260
commit e3a398d3e4
9 changed files with 108 additions and 6 deletions
@@ -33,11 +33,6 @@ impl CollaborationModeState {
custom_model_catalog: bool,
) -> Self {
let bundled = ResolvedModelMessages::bundled().collaboration_modes();
let catalog_instructions = match mode {
None => None,
Some(ModeKind::Default) => messages.default.catalog_override(),
Some(ModeKind::Plan) => messages.plan.catalog_override(),
};
// Before Plan, preserve custom caller text only when it would win over the catalog.
let supplied = settings.developer_instructions.as_deref().filter(|text| {
!text.is_empty()
@@ -45,6 +40,12 @@ impl CollaborationModeState {
|| (messages.default.catalog_override().is_none()
&& *text != bundled.default.text()))
});
let catalog_instructions = match mode {
None if supplied.is_none() => messages.initial.filter(|text| !text.is_empty()),
None => None,
Some(ModeKind::Default) => messages.default.catalog_override(),
Some(ModeKind::Plan) => messages.plan.catalog_override(),
};
let instructions = catalog_instructions.or(supplied).map(str::to_string);
let instructions = instructions.map(|instructions| {
if update_plan_enabled {
@@ -93,6 +93,7 @@ fn catalog_collaboration_messages_select_mode_variant() {
let mut model = model_info_from_slug("test-model");
model.model_messages = Some(ModelMessages {
collaboration_modes: Some(CollaborationModeMessages {
initial: None,
default: Some(default.to_string()),
plan: Some(plan.to_string()),
}),
@@ -90,6 +90,7 @@ fn model_with_collaboration_messages(
guardian_v2: None,
});
model_messages.collaboration_modes = Some(CollaborationModeMessages {
initial: None,
default: default.map(str::to_string),
plan: plan.map(str::to_string),
});
@@ -3,12 +3,71 @@
use super::*;
use codex_models_manager::manager::RefreshStrategy;
use codex_models_manager::model_info::model_info_from_slug;
use codex_protocol::config_types::ModeKind;
use codex_protocol::openai_models::ApplyPatchToolType;
use codex_protocol::openai_models::CollaborationModeMessages;
use codex_protocol::openai_models::ModelVisibility;
use codex_protocol::openai_models::ModelsResponse;
use core_test_support::responses;
use pretty_assertions::assert_eq;
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn initial_collaboration_guidance_survives_resume_until_plan() -> Result<()> {
skip_if_no_network!(Ok(()));
let server = start_mock_server().await;
let builder = || {
test_codex()
.with_model("gpt-5.5")
.with_config(|config| {
configure_scenario_catalog(config);
config.include_environment_context = false;
config.include_permissions_instructions = false;
})
.with_model_info_override("gpt-5.5", |model| {
let messages = model.model_messages.get_or_insert_default();
messages.instructions_template = Some("Help with the migration.".into());
messages.collaboration_modes = Some(CollaborationModeMessages {
initial: Some("Work directly on the user's request.".into()),
plan: Some("Prepare a plan before editing.".into()),
default: Some("Resume implementation.".into()),
});
})
};
let mock = mount_sse_sequence(
&server,
(1..=4)
.map(|i| sse(vec![ev_completed(&format!("response-{i}"))]))
.collect(),
)
.await;
let test = builder().build_with_auto_env(&server).await?;
test.submit_text_turn("Inspect the migration.").await?;
let resumed = builder().restart_with_auto_env(&server, &test).await?;
for (mode, prompt) in [
(ModeKind::Default, "Check the rollback path too."),
(ModeKind::Plan, "Plan the migration."),
(ModeKind::Default, "Implement the plan."),
] {
let mut collaboration_mode = resumed.codex.config_snapshot().await.collaboration_mode;
collaboration_mode.mode = mode;
resumed
.codex
.update_thread_settings(ThreadSettingsOverrides {
collaboration_mode: Some(collaboration_mode),
..Default::default()
})
.await?;
resumed.submit_text_turn(prompt).await?;
}
insta::assert_snapshot!(context_snapshot::format_request_history_snapshot(
"A catalog supplies initial guidance. After a restart, the client selects Default, enters Plan, and returns to Default.",
&mock.requests(),
&ContextSnapshotOptions::default(),
));
Ok(())
}
/// Originator routing supplies the actual turn's instructions and tools without changing legacy callers.
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn originator_catalogs_control_turn_instructions_and_tools() -> Result<()> {
@@ -0,0 +1,31 @@
---
source: core/tests/suite/scenarios_model_instructions.rs
expression: "context_snapshot::format_request_history_snapshot(\"A catalog supplies initial guidance. After a restart, the client selects Default, enters Plan, and returns to Default.\",\n&mock.requests(), &ContextSnapshotOptions::default(),)"
---
Scenario: A catalog supplies initial guidance. After a restart, the client selects Default, enters Plan, and returns to Default.
## Window 1
-- request 1 (turn) --
00:message/developer:
Help with the migration.
01:message/developer[2]:
[01] <collaboration_mode>Work directly on the user's request.</collaboration_mode>
[02] <tools>
Deferred tool namespaces:
- multi_agent_v1: Tools for spawning and managing sub-agents.
</tools>
02:message/user:
Inspect the migration.
-- request 2 (turn) --
03:message/user:
Check the rollback path too.
-- request 3 (turn) --
04:message/developer:
<collaboration_mode>Prepare a plan before editing.</collaboration_mode>
05:message/user:
Plan the migration.
-- request 4 (turn) --
06:message/developer:
<collaboration_mode>Resume implementation.</collaboration_mode>
07:message/user:
Implement the plan.
@@ -1087,6 +1087,7 @@ async fn active_model_switch_updates_core_context_from_captured_settings(
let messages = model.model_messages.as_mut().expect("model messages");
messages.instructions_template = Some(format!("Instructions for {slug}."));
messages.collaboration_modes = Some(CollaborationModeMessages {
initial: None,
default: None,
plan: Some(format!("Plan collaboration for {slug}.")),
});
@@ -45,6 +45,7 @@ fn base_instruction_override_is_literal_and_preserves_catalog_messages() {
..Default::default()
};
let collaboration_modes = CollaborationModeMessages {
initial: Some("initial instructions".to_string()),
default: Some("default instructions".to_string()),
plan: Some("plan instructions".to_string()),
};
@@ -1,5 +1,5 @@
//! Resolves collaboration catalog text and bundled presets while retaining their source.
//! Runtime consumers use catalog overrides first, then the selected mode's settings.
//! Initial guidance is catalog-only. Selected modes fall back to their settings.
use super::ResolvedMessage;
use codex_collaboration_mode_templates::DEFAULT;
@@ -8,6 +8,7 @@ use codex_protocol::openai_models::CollaborationModeMessages;
#[derive(Debug, Clone, Copy)]
pub struct ResolvedCollaborationModeMessages<'a> {
pub initial: Option<&'a str>,
pub default: ResolvedMessage<'a>,
pub plan: ResolvedMessage<'a>,
}
@@ -15,6 +16,7 @@ pub struct ResolvedCollaborationModeMessages<'a> {
impl<'a> ResolvedCollaborationModeMessages<'a> {
pub(crate) fn new(messages: Option<&'a CollaborationModeMessages>) -> Self {
Self {
initial: messages.and_then(|m| m.initial.as_deref()),
default: ResolvedMessage::new(messages.and_then(|m| m.default.as_deref()), DEFAULT),
plan: ResolvedMessage::new(messages.and_then(|m| m.plan.as_deref()), PLAN),
}
+5
View File
@@ -874,6 +874,9 @@ pub struct GranularApprovalMessages {
#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]
pub struct CollaborationModeMessages {
/// Optional guidance for Default before the first Plan turn.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub initial: Option<String>,
pub default: Option<String>,
pub plan: Option<String>,
}
@@ -1628,6 +1631,7 @@ mod tests {
ModelMessages {
instructions_template: Some("legacy catalog instructions".to_string()),
collaboration_modes: Some(CollaborationModeMessages {
initial: None,
default: Some(String::new()),
plan: None,
}),
@@ -1819,6 +1823,7 @@ mod tests {
..Default::default()
}),
collaboration_modes: Some(CollaborationModeMessages {
initial: Some("initial collaboration".to_string()),
default: Some("default collaboration".to_string()),
plan: Some("plan collaboration".to_string()),
}),