Defer built-in Default mode instructions until after Plan mode (#62857)

## Why

Threads that stay in Default mode carry a collaboration-mode prompt even
though they have no Plan mode instructions to supersede.

## What changed

Omit bundled and model-catalog Default mode instructions until a thread
uses Plan mode. Emit Plan mode instructions on entry and Default mode
instructions when switching back. Preserve eligible caller-provided
instructions and carry the active mode through compaction and resume.

## Testing

Cover prompt contents before, during, and after Plan mode in core and
app-server tests, including compaction and resume in the core tests.

GitOrigin-RevId: b734767da15be53c4eccae71994e46eba63a9ecc
This commit is contained in:
Dylan Hurd
2026-11-20 23:12:16 +00:00
committed by copyberry
parent 548dd628df
commit 941e1dcade
61 changed files with 530 additions and 1064 deletions
@@ -7,8 +7,8 @@ use crate::context::ContextualUserFragment;
use codex_prompts::ResolvedCollaborationModeMessages;
use codex_prompts::ResolvedModelMessages;
use codex_prompts::without_update_plan_instructions;
use codex_protocol::config_types::CollaborationMode;
use codex_protocol::config_types::ModeKind;
use codex_protocol::config_types::Settings;
use codex_protocol::models::ContentItem;
use codex_protocol::models::ContentItemKind;
use codex_protocol::models::input_text;
@@ -26,24 +26,26 @@ pub(crate) struct CollaborationModeState {
impl CollaborationModeState {
pub(crate) fn from_collaboration_mode(
collaboration_mode: &CollaborationMode,
mode: Option<ModeKind>,
settings: &Settings,
messages: ResolvedCollaborationModeMessages<'_>,
update_plan_enabled: bool,
custom_model_catalog: bool,
) -> Self {
let catalog_instructions = match collaboration_mode.mode {
ModeKind::Default => messages.default,
ModeKind::Plan => messages.plan,
}
.catalog_override();
let instructions = catalog_instructions.map(str::to_string).or_else(|| {
collaboration_mode
.settings
.developer_instructions
.clone()
.filter(|instructions| !instructions.is_empty())
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()
&& (mode.is_some()
|| (messages.default.catalog_override().is_none()
&& *text != bundled.default.text()))
});
let instructions = catalog_instructions.or(supplied).map(str::to_string);
let instructions = instructions.map(|instructions| {
if update_plan_enabled {
return instructions;
@@ -55,7 +57,6 @@ impl CollaborationModeState {
// preset or custom text. Compare whole strings against bundled presets
// only to recognize built-in text whose disabled update_plan guidance
// we can strip; custom instructions stay unchanged.
let bundled = ResolvedModelMessages::bundled().collaboration_modes();
instructions == bundled.default.text() || instructions == bundled.plan.text()
}
};
@@ -70,8 +71,8 @@ impl CollaborationModeState {
instructions: instructions.clone().unwrap_or_default(),
};
let snapshot = CollaborationModeSnapshot::Current {
mode: collaboration_mode.mode,
model: collaboration_mode.settings.model.clone(),
mode: mode.unwrap_or(ModeKind::Default),
model: settings.model.clone(),
instructions: Some(WorldStateHash::from_fragment(&fragment)),
};
Self {
@@ -48,7 +48,8 @@ fn instruction_updates_are_applied_once_in_retained_history() {
for instructions in [Some("old instructions"), Some("new instructions"), None] {
let mut world_state = WorldState::default();
world_state.add_section(CollaborationModeState::from_collaboration_mode(
&collaboration_mode(ModeKind::Default, instructions),
Some(ModeKind::Default),
&settings(instructions),
ResolvedModelMessages::bundled().collaboration_modes(),
/*update_plan_enabled*/ true,
/*custom_model_catalog*/ false,
@@ -101,7 +102,8 @@ fn catalog_collaboration_messages_select_mode_variant() {
for (mode, expected) in [(ModeKind::Default, default), (ModeKind::Plan, plan)] {
let state = CollaborationModeState::from_collaboration_mode(
&collaboration_mode(mode, Some("legacy instructions")),
Some(mode),
&settings(Some("legacy instructions")),
messages,
/*update_plan_enabled*/ true,
/*custom_model_catalog*/ false,
@@ -119,7 +121,8 @@ fn empty_catalog_collaboration_message_suppresses_legacy_instructions() {
..ResolvedModelMessages::bundled().collaboration_modes()
};
let state = CollaborationModeState::from_collaboration_mode(
&collaboration_mode(ModeKind::Plan, Some("legacy plan instructions")),
Some(ModeKind::Plan),
&settings(Some("legacy plan instructions")),
messages,
/*update_plan_enabled*/ true,
/*custom_model_catalog*/ false,
@@ -144,7 +147,8 @@ fn missing_catalog_collaboration_message_uses_legacy_instructions() {
};
for instructions in [Some("legacy plan instructions"), Some(""), None] {
let state = CollaborationModeState::from_collaboration_mode(
&collaboration_mode(ModeKind::Plan, instructions),
Some(ModeKind::Plan),
&settings(instructions),
messages,
/*update_plan_enabled*/ true,
/*custom_model_catalog*/ false,
@@ -168,7 +172,8 @@ fn legacy_collaboration_mode_snapshots_refresh_catalog_messages_once() {
..ResolvedModelMessages::bundled().collaboration_modes()
};
let state = CollaborationModeState::from_collaboration_mode(
&collaboration_mode(ModeKind::Default, Some("stale legacy instructions")),
Some(ModeKind::Default),
&settings(Some("stale legacy instructions")),
messages,
/*update_plan_enabled*/ true,
/*custom_model_catalog*/ false,
@@ -200,20 +205,18 @@ fn legacy_collaboration_mode_snapshots_refresh_catalog_messages_once() {
}
}
fn collaboration_mode(mode: ModeKind, instructions: Option<&str>) -> CollaborationMode {
CollaborationMode {
mode,
settings: Settings {
model: "test-model".to_string(),
reasoning_effort: None,
developer_instructions: instructions.map(str::to_string),
},
fn settings(instructions: Option<&str>) -> Settings {
Settings {
model: "test-model".to_string(),
reasoning_effort: None,
developer_instructions: instructions.map(str::to_string),
}
}
fn collaboration_mode_state(mode: ModeKind, instructions: &str) -> CollaborationModeState {
CollaborationModeState::from_collaboration_mode(
&collaboration_mode(mode, Some(instructions)),
Some(mode),
&settings(Some(instructions)),
ResolvedModelMessages::bundled().collaboration_modes(),
/*update_plan_enabled*/ true,
/*custom_model_catalog*/ false,
+5 -1
View File
@@ -584,7 +584,11 @@ impl ContextManager {
}
pub(crate) fn reference_context_item(&self) -> Option<TurnContextItem> {
self.reference_context_item.clone()
self.reference_context_item_ref().cloned()
}
pub(crate) fn reference_context_item_ref(&self) -> Option<&TurnContextItem> {
self.reference_context_item.as_ref()
}
pub(crate) fn render_step_world_state(
+8 -3
View File
@@ -4430,15 +4430,19 @@ impl Session {
// Read the step's model and record its environments together so an update cannot split them.
// Match apply_turn_settings and activate_turn_environments: active_turn before state.
// Wait for executor startup below, after releasing both locks.
let (mut settings, environments, inherited_environments) = {
let (mut settings, active_collaboration_mode, environments, inherited_environments) = {
let _active = self
.active_turn
.lock()
.or_cancel(cancellation_token)
.await?;
let _state = self.state.lock().or_cancel(cancellation_token).await?;
let state = self.state.lock().or_cancel(cancellation_token).await?;
let settings = turn_context.next_step_settings.load_full();
let active_collaboration_mode =
settings.active_collaboration_mode(state.history.reference_context_item_ref());
(
turn_context.next_step_settings.load_full(),
settings,
active_collaboration_mode,
self.services.turn_environments.snapshot(),
self.features
.enabled(Feature::SubagentThreadEnvironments)
@@ -4706,6 +4710,7 @@ impl Session {
}
let (executor_hook_sources, mcp, tool_router, extension_data) = prepared_tools??;
Ok(Arc::new(StepContext {
active_collaboration_mode,
sampled_through_sequence: None,
serving_assessment: None,
guardian_probe: None,
+7 -1
View File
@@ -19,6 +19,7 @@ use codex_model_provider_info::AMAZON_BEDROCK_RUNTIME_PROVIDER_ID;
use codex_model_provider_info::GCP_PROVIDER_ID;
use codex_otel::SessionTelemetry;
use codex_plugin::ExecutorPluginHookSource;
use codex_protocol::config_types::ModeKind;
use codex_protocol::items::ModelInvocationContext;
use codex_protocol::protocol::TurnContextItem;
use tokio_util::sync::CancellationToken;
@@ -41,6 +42,8 @@ pub(crate) struct StepContext {
pub(crate) realtime: RealtimeConversationSnapshot,
/// One immutable settings version captured before request preparation.
pub(crate) settings: Arc<ResolvedStepSettings>,
/// None until the first Plan turn. Carried into replacement context during compaction.
pub(crate) active_collaboration_mode: Option<ModeKind>,
/// Frozen turn preferences resolved against this step's captured model.
pub(crate) token_budget: Option<TokenBudgetConfig>,
/// Telemetry context tagged with this sampling request's model.
@@ -102,7 +105,10 @@ impl StepContext {
/// Persist the context captured for this request, even after a live update.
pub(crate) fn to_turn_context_item(&self) -> TurnContextItem {
let mut item = self.turn.to_turn_context_item();
let mut item = self.turn.context_item_with_mode(
self.active_collaboration_mode
.map(|_| self.settings.effective_collaboration_mode()),
);
item.realtime_active = Some(self.realtime.active);
item
}
@@ -11,6 +11,7 @@ use codex_otel::SessionTelemetry;
use codex_protocol::RequestCountry;
use codex_protocol::config_types::ApprovalsReviewer;
use codex_protocol::config_types::CollaborationMode;
use codex_protocol::config_types::ModeKind;
use codex_protocol::config_types::Personality;
use codex_protocol::config_types::ReasoningSummary;
use codex_protocol::config_types::SERVICE_TIER_DEFAULT_REQUEST_VALUE;
@@ -18,6 +19,7 @@ use codex_protocol::config_types::ServiceTier;
use codex_protocol::openai_models::CatalogModel;
use codex_protocol::openai_models::ReasoningEffort;
use codex_protocol::protocol::AskForApproval;
use codex_protocol::protocol::TurnContextItem;
use std::sync::Arc;
/// Model and execution settings selected for an individual model step within
@@ -94,6 +96,15 @@ impl ResolvedStepSettings {
.cloned()
}
pub(super) fn active_collaboration_mode(
&self,
previous: Option<&TurnContextItem>,
) -> Option<ModeKind> {
let mode = self.selected.collaboration_mode.mode;
(mode == ModeKind::Plan || previous.is_some_and(|item| item.collaboration_mode.is_some()))
.then_some(mode)
}
pub(crate) fn effective_collaboration_mode(&self) -> CollaborationMode {
let mut collaboration_mode = self.selected.collaboration_mode.clone();
collaboration_mode.settings.model = self.model_info.slug.clone();
+11
View File
@@ -299,6 +299,7 @@ impl StepContext {
});
settings.service_tier = turn.config.service_tier.clone();
Arc::new(Self {
active_collaboration_mode: settings.active_collaboration_mode(/*previous*/ None),
sampled_through_sequence: None,
turn_cancellation: tokio_util::sync::CancellationToken::new(),
preempt: turn
@@ -13479,3 +13480,13 @@ async fn rejected_mcp_refresh_then_corrected_user_config_blocks_ordinary_replace
"rejection must not permit same-name ordinary-auth replacement in this session"
);
}
impl TurnContext {
pub(crate) fn to_turn_context_item(&self) -> TurnContextItem {
self.context_item_with_mode(
self.initial_settings
.active_collaboration_mode(/*previous*/ None)
.map(|_| self.collaboration_mode()),
)
}
}
+5 -2
View File
@@ -938,7 +938,10 @@ impl TurnContext {
}
}
pub(crate) fn to_turn_context_item(&self) -> TurnContextItem {
pub(super) fn context_item_with_mode(
&self,
collaboration_mode: Option<CollaborationMode>,
) -> TurnContextItem {
#[allow(deprecated)]
let cwd = self.cwd.clone();
TurnContextItem {
@@ -959,7 +962,7 @@ impl TurnContext {
),
model: self.model_info().slug.clone(),
comp_hash: self.model_info().comp_hash.clone(),
collaboration_mode: Some(self.collaboration_mode()),
collaboration_mode,
multi_agent_version: Some(self.multi_agent_version),
realtime_active: Some(self.realtime_active),
cyber_access_program: self.cyber_access_program,
+2 -1
View File
@@ -342,7 +342,8 @@ impl Session {
}
if turn_context.config.include_collaboration_mode_instructions {
world_state.add_section(CollaborationModeState::from_collaboration_mode(
&settings.effective_collaboration_mode(),
step_context.active_collaboration_mode,
&settings.effective_collaboration_mode().settings,
model_messages.collaboration_modes(),
turn_context.config.update_plan_enabled,
turn_context.config.model_catalog.is_some(),