Tag all multi-agent role instructions consistently (#62842)

## Why

Only catalog role instructions carried the `<multi_agent_role>` tag,
so the same guidance appeared in different formats depending on its source.

## What changed

Render bundled, catalog, and configured root and subagent guidance as
`multi_agent.role_instructions` developer messages. Wrap the guidance in
`<multi_agent_role>` tags and preserve configured text that's already tagged.
Match untagged parent guidance by its body when filtering forked history.

## Testing

Update prompt and session assertions for tagged role instructions, and keep
the cold-resume test exercising a rollout with legacy untagged guidance.

GitOrigin-RevId: 60c55b5d7227811b92bd1bf125f1cd3a965720fd
This commit is contained in:
rhan-oai
2026-11-20 21:42:17 +00:00
committed by copyberry
parent 5bee962f5e
commit 2b5111917c
30 changed files with 91 additions and 686 deletions
+1 -4
View File
@@ -3285,10 +3285,8 @@ async fn spawn_agent_can_fork_parent_thread_history_with_sanitized_items() {
.expect("parent shutdown should submit");
}
#[test_case::test_case(true; "marked catalog hints")]
#[test_case::test_case(false; "unmarked bundled hints")]
#[tokio::test]
async fn spawn_agent_fork_strips_parent_usage_hints_from_compacted_history(marked: bool) {
async fn spawn_agent_fork_strips_parent_usage_hints_from_compacted_history() {
let harness = AgentControlHarness::new().await;
let mut parent_config = harness.config.clone();
let _ = parent_config.features.enable(Feature::MultiAgentV2);
@@ -3318,7 +3316,6 @@ async fn spawn_agent_fork_strips_parent_usage_hints_from_compacted_history(marke
let parent_spawn_call_id = "spawn-call-compacted-usage-hints".to_string();
let catalog_role = |base: &str| MultiAgentRoleInstructions::Composed {
base: base.to_string(),
marked,
omit_update_plan_instructions: false,
max_concurrency: 2,
wait_agent_enabled: false,
+1 -1
View File
@@ -424,7 +424,7 @@ pub(super) async fn prepare_forked_history(
[parent_usage_hints.root, parent_usage_hints.subagent]
.into_iter()
.flatten()
.map(|instructions| instructions.render().into_text().unwrap_or_default())
.map(|instructions| instructions.body().into_text().unwrap_or_default())
.collect()
} else {
Vec::new()
@@ -3,7 +3,7 @@ use codex_protocol::models::ContentItem;
use codex_protocol::models::ContentItemKind;
use codex_protocol::models::input_text;
/// Configured multi-agent instructions emitted as a standalone developer message.
/// Developer note introducing a child after its inherited conversation prefix.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct MultiAgentUsageHint {
text: String,
@@ -102,7 +102,6 @@ fn unchanged_mode_is_reemitted_after_usage_hint_migration() {
fn catalog_role_updates_remain_separate_from_active_mode() {
let catalog_role = |base: &str| MultiAgentRoleInstructions::Composed {
base: base.to_string(),
marked: true,
omit_update_plan_instructions: false,
max_concurrency: 2,
wait_agent_enabled: false,
@@ -5,7 +5,6 @@ use super::WorldStateSection;
use super::WorldStateUpdate;
use crate::context::ContextualUserFragment;
use crate::context::MultiAgentRoleInstructions;
use crate::context::MultiAgentUsageHint;
use codex_protocol::models::ContentItemMetadata;
use codex_protocol::models::ContentItemNamespace;
@@ -52,18 +51,9 @@ impl WorldStateSection for MultiAgentUsageHintState {
}
PreviousSectionState::Unknown => None,
PreviousSectionState::Known(_) | PreviousSectionState::Absent => {
if self.instructions.markers().0.is_empty() {
Some(Box::new(
MultiAgentUsageHint::new(
&self.instructions.body().into_text().unwrap_or_default(),
)
.with_metadata(ContentItemMetadata::tool(self.namespace.clone())),
))
} else {
Some(Box::new(self.instructions.clone().with_metadata(
ContentItemMetadata::tool(self.namespace.clone()),
)))
}
Some(Box::new(self.instructions.clone().with_metadata(
ContentItemMetadata::tool(self.namespace.clone()),
)))
}
};
(
@@ -59,7 +59,6 @@ pub(crate) fn resolve_usage_hints(
}
Some(MultiAgentRoleInstructions::Composed {
base: base.to_owned(),
marked: message.catalog_override().is_some(),
omit_update_plan_instructions,
max_concurrency: config.max_concurrent_threads_per_session,
wait_agent_enabled: config.wait_agent_enabled,
+19 -46
View File
@@ -10854,6 +10854,17 @@ async fn build_initial_context_omits_prompt_fragments_without_extension_state()
);
}
fn multi_agent_role_messages(items: &[ResponseItem]) -> Vec<Vec<&str>> {
developer_message_texts(items)
.into_iter()
.filter(|message| {
message
.iter()
.any(|text| MultiAgentRoleInstructions::matches_text(text))
})
.collect()
}
#[tokio::test]
async fn build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_message() {
let (session, turn_context) =
@@ -10861,18 +10872,9 @@ async fn build_initial_context_adds_multi_agent_v2_root_usage_hint_as_developer_
let initial_context = build_initial_context(&session, &turn_context).await;
let developer_messages = developer_message_texts(&initial_context);
assert!(
developer_messages
.iter()
.any(|message| message.as_slice() == ["Root guidance."]),
"expected standalone root usage hint developer message, got {developer_messages:?}"
);
assert!(
!developer_messages
.iter()
.any(|message| message.as_slice() == ["Subagent guidance."]),
"did not expect subagent usage hint for root thread, got {developer_messages:?}"
assert_eq!(
multi_agent_role_messages(&initial_context),
[["<multi_agent_role>Root guidance.</multi_agent_role>"]]
);
}
@@ -10912,17 +10914,9 @@ async fn build_initial_context_adds_multi_agent_v2_subagent_usage_hint_as_develo
.contains("<context_window>\nAgent name: /root/worker\n")),
"expected subagent context window to include its canonical name, got {developer_messages:?}"
);
assert!(
developer_messages
.iter()
.any(|message| message.as_slice() == ["Subagent guidance."]),
"expected standalone subagent usage hint developer message, got {developer_messages:?}"
);
assert!(
!developer_messages
.iter()
.any(|message| message.as_slice() == ["Root guidance."]),
"did not expect root usage hint for subagent thread, got {developer_messages:?}"
assert_eq!(
multi_agent_role_messages(&initial_context),
[["<multi_agent_role>Subagent guidance.</multi_agent_role>"]]
);
}
@@ -10933,16 +10927,7 @@ async fn build_initial_context_omits_multi_agent_v2_usage_hints_when_feature_dis
let initial_context = build_initial_context(&session, &turn_context).await;
let developer_messages = developer_message_texts(&initial_context);
assert!(
!developer_messages.iter().any(|message| {
matches!(
message.as_slice(),
["Root guidance."] | ["Subagent guidance."]
)
}),
"did not expect multi-agent v2 usage hint developer messages, got {developer_messages:?}"
);
assert!(multi_agent_role_messages(&initial_context).is_empty());
}
#[tokio::test]
@@ -10960,19 +10945,7 @@ async fn build_initial_context_omits_multi_agent_v2_usage_hints_when_hint_is_emp
let initial_context = build_initial_context(&session, &turn_context).await;
let developer_messages = developer_message_texts(&initial_context);
assert!(
!developer_messages.iter().any(|message| {
matches!(
message.as_slice(),
["Root guidance."] | ["Subagent guidance."]
) || message.iter().any(|text| {
text.contains("You are `/root`, the primary agent")
|| text.contains("You are an agent in a team of agents")
})
}),
"did not expect multi-agent v2 usage hint developer messages, got {developer_messages:?}"
);
assert!(multi_agent_role_messages(&initial_context).is_empty());
}
#[tokio::test]