Source multi-agent instructions from the model catalog (#38619)

## What changed

- Add model-catalog messages for root and subagent roles, explicit delegation, and delegation hints.
- Resolve role instructions in config, catalog, then bundled-default order, while preserving empty values as an explicit way to suppress fallback text.
- Refresh catalog-provided role and mode instructions when the model changes, and give full-history forks the selected child model's subagent role without retaining the parent's role guidance.
- Keep existing config overrides and reasoning-effort behavior, including proactive delegation for ultra reasoning effort.

## Testing

- Cover message deserialization and preservation through model overrides.
- Cover precedence, empty overrides, model switches, resumed sessions, and full-history subagent forks.

GitOrigin-RevId: 4625cf7c6a5490176adddfaa0fb99100707daea9
This commit is contained in:
rhan-oai authored and copyberry committed 2026-08-14 18:26:20 +00:00
1 parent 14a6813fa8
commit 395723b238
30 files changed
+734 -231

No files matched your search

+91 -24
View File
@@ -1,7 +1,9 @@
use crate::config::edit::ConfigEdit;
use crate::config::edit::ConfigEditsBuilder;
use crate::config::edit::apply_blocking;
use crate::context::ContextualUserFragment;
use crate::plugins::plugins_manager_for_config;
use crate::session::multi_agents::resolve_usage_hints;
use assert_matches::assert_matches;
use codex_config::CONFIG_TOML_FILE;
use codex_config::ConfigLayerEntry;
@@ -87,6 +89,7 @@ use codex_protocol::models::BUILT_IN_PERMISSION_PROFILE_WORKSPACE;
use codex_protocol::models::ManagedFileSystemPermissions;
use codex_protocol::models::PermissionProfile;
use codex_protocol::models::SandboxEnforcement;
use codex_protocol::openai_models::MultiAgentRoleMessages;
use codex_protocol::permissions::FileSystemAccessMode;
use codex_protocol::permissions::FileSystemPath;
use codex_protocol::permissions::FileSystemSandboxEntry;
@@ -10991,17 +10994,29 @@ max_concurrent_threads_per_session = 17
let config = resolve_multi_agent_v2_config(&config_toml);
let concurrency_guidance = "There are 17 available concurrency slots, meaning that up to 17 agents can be active at once, including you.";
let expected_suffix = format!(
"{DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT}\n{DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT}\n\n{concurrency_guidance}"
);
assert!(
[
config.root_agent_usage_hint_text,
config.subagent_usage_hint_text,
]
.into_iter()
.all(|hint| hint.is_some_and(|hint| hint.contains(expected_suffix.as_str())))
assert!(config.wait_agent_enabled);
for wait_agent_enabled in [true, false] {
let mut config = config.clone();
config.wait_agent_enabled = wait_agent_enabled;
let usage_hints = resolve_usage_hints(&config, /*catalog*/ None);
for hint in [usage_hints.root, usage_hints.subagent] {
let hint = hint.expect("default usage hints should be present").body();
assert!(hint.contains(concurrency_guidance));
assert_eq!(
hint.contains("When calling `wait_agent`, prefer longer waits"),
wait_agent_enabled
);
}
}
let usage_hints = resolve_usage_hints(
&config,
Some(&MultiAgentRoleMessages {
root: Some(String::new()),
subagent: Some(String::new()),
}),
);
assert!(usage_hints.root.is_none() && usage_hints.subagent.is_none());
}
#[test]
@@ -11026,6 +11041,23 @@ expose_spawn_agent_model_overrides = true
config.subagent_usage_hint_text.as_deref(),
Some("Subagent guidance.")
);
let usage_hints = resolve_usage_hints(
&config,
Some(&MultiAgentRoleMessages {
root: Some("Catalog root base.".to_string()),
subagent: Some("Catalog subagent base.".to_string()),
}),
);
assert_eq!(
(
usage_hints.root.map(|hint| hint.body()),
usage_hints.subagent.map(|hint| hint.body()),
),
(
Some("Root guidance.".to_string()),
Some("Subagent guidance.".to_string()),
)
);
}
#[test]
@@ -11033,18 +11065,39 @@ fn multi_agent_v2_exposes_model_overrides_by_default() {
let config_toml =
toml::from_str(r#"[features.multi_agent_v2]"#).expect("multi-agent v2 config should parse");
let config = resolve_multi_agent_v2_config(&config_toml);
let mut config = resolve_multi_agent_v2_config(&config_toml);
assert!(config.expose_spawn_agent_model_overrides);
assert!(
[
config.root_agent_usage_hint_text,
config.subagent_usage_hint_text,
]
.into_iter()
.all(|hint| hint.is_some_and(|hint| {
hint.ends_with(DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT)
}))
);
let usage_hints = resolve_usage_hints(&config, /*catalog*/ None);
config.expose_spawn_agent_model_overrides = false;
let usage_hints_without_model_overrides = resolve_usage_hints(&config, /*catalog*/ None);
for (hint, hint_without_model_overrides) in [
(usage_hints.root, usage_hints_without_model_overrides.root),
(
usage_hints.subagent,
usage_hints_without_model_overrides.subagent,
),
] {
let hint = hint.expect("default usage hints should be present").body();
let hint_without_model_overrides = hint_without_model_overrides
.expect("default usage hints should be present without model overrides")
.body();
let model_override_guidance = hint
.strip_prefix(hint_without_model_overrides.as_str())
.expect("model-override guidance should extend the base usage hint");
for required_fragment in [
"Full-history forks",
"`fork_turns`",
"`model`",
"`reasoning_effort`",
] {
assert!(
model_override_guidance.contains(required_fragment),
"model-override guidance should contain {required_fragment}"
);
}
}
}
#[tokio::test]
@@ -11108,7 +11161,7 @@ subagent_developer_instructions = " \t "
}
#[tokio::test]
async fn multi_agent_v2_empty_usage_hint_overrides_clear_default_hints() -> std::io::Result<()> {
async fn multi_agent_v2_empty_usage_hint_overrides_are_preserved() -> std::io::Result<()> {
let codex_home = TempDir::new()?;
std::fs::write(
codex_home.path().join(CONFIG_TOML_FILE),
@@ -11125,8 +11178,22 @@ subagent_usage_hint_text = ""
.build()
.await?;
assert_eq!(config.multi_agent_v2.root_agent_usage_hint_text, None);
assert_eq!(config.multi_agent_v2.subagent_usage_hint_text, None);
let usage_hints = resolve_usage_hints(
&config.multi_agent_v2,
Some(&MultiAgentRoleMessages {
root: Some("catalog root".to_string()),
subagent: Some("catalog subagent".to_string()),
}),
);
assert_eq!(
(
config.multi_agent_v2.root_agent_usage_hint_text.as_deref(),
config.multi_agent_v2.subagent_usage_hint_text.as_deref(),
usage_hints.root,
usage_hints.subagent,
),
(Some(""), Some(""), None, None)
);
Ok(())
}
+8 -123
View File
@@ -213,69 +213,7 @@ pub(crate) const DEFAULT_MULTI_AGENT_V2_MAX_CONCURRENT_THREADS_PER_SESSION: usiz
pub(crate) const DEFAULT_MULTI_AGENT_V2_MIN_WAIT_TIMEOUT_MS: i64 = 10_000;
pub(crate) const DEFAULT_MULTI_AGENT_V2_MAX_WAIT_TIMEOUT_MS: i64 = 3600 * 1000;
pub(crate) const DEFAULT_MULTI_AGENT_V2_DEFAULT_WAIT_TIMEOUT_MS: i64 = 30_000;
const DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT: &str = r#"You are `/root`, the primary agent in a team of agents collaborating to fulfill the user's goals.
At the start of your turn, you are the active agent.
You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents.
All agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.
You can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task and trigger a turn, and `send_message` to pass a message to a running agent without triggering a turn.
Child agents can also spawn their own sub-agents.
You can decide how much context you want to propagate to your sub-agents with the `fork_turns` parameter.
You will receive messages in the analysis channel in the form:
```
Message Type: MESSAGE | FINAL_ANSWER
Task name: <recipient>
Sender: <author>
Payload:
<payload text>
```
They may be addressed as to=/root
"#;
const DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT: &str = r#"You are an agent in a team of agents collaborating to complete a task.
You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents. All agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.
You can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task and trigger a turn, and `send_message` to pass a message to a running agent.
Child agents can also spawn their own sub-agents.
When you provide a response in the final channel, that content is immediately delivered back to your parent agent.
You will receive messages in the analysis channel in the form:
```
Message Type: NEW_TASK | MESSAGE | FINAL_ANSWER
Task name: <recipient>
Sender: <author>
Payload:
<payload text>
```
You may also see them addressed as to=/root/..., which indicates your identity is /root/...
"#;
const DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT: &str = "Full-history forks (`fork_turns` omitted or `\"all\"`) inherit the parent model and reasoning effort and do not accept overrides. Only set `model` or `reasoning_effort` when explicitly requested by the user, applicable `AGENTS.md` instructions, or skill instructions; when doing so, set `fork_turns` to `\"none\"` or a positive integer string.";
const DEFAULT_MULTI_AGENT_V2_TOOL_NAMESPACE: &str = "collaboration";
const DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT: &str =
"When calling `wait_agent`, prefer longer waits (minutes) to avoid busy polling.";
const DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT: &str = r#"Note that collaboration tools cannot be called from inside `functions.exec`. Call `spawn_agent`, `send_message`, `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents` only as direct tool calls using the recipient shown in their tool definitions, such as `to=functions.collaboration.spawn_agent`, since they are intentionally absent from the `functions.exec` `tools.*` namespace. Available tools in `functions.exec` are explicitly described with a `tools` namespace in the developer message.
All agents share the same directory. In detail:
- All agents have access to the same container and filesystem as you.
- All agents use the same current working directory.
- As a result, edits made by one agent are immediately visible to all other agents.
"#;
fn default_multi_agent_v2_usage_hint_text(
usage_hint_text: &str,
max_concurrency: usize,
wait_agent_usage_hint_text: Option<&str>,
) -> String {
let wait_agent_usage_hint_text = match wait_agent_usage_hint_text {
Some(wait_agent_usage_hint_text) => format!("{wait_agent_usage_hint_text}\n\n"),
None => String::new(),
};
format!(
"{usage_hint_text}\n{DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT}\n{wait_agent_usage_hint_text}There are {max_concurrency} available concurrency slots, meaning that up to {max_concurrency} agents can be active at once, including you."
)
}
pub(crate) const HARD_MIN_MULTI_AGENT_V2_TIMEOUT_MS: i64 = 0;
pub(crate) const HARD_MAX_MULTI_AGENT_V2_TIMEOUT_MS: i64 =
@@ -1298,16 +1236,8 @@ impl MultiAgentV2Config {
max_wait_timeout_ms: DEFAULT_MULTI_AGENT_V2_MAX_WAIT_TIMEOUT_MS,
default_wait_timeout_ms: DEFAULT_MULTI_AGENT_V2_DEFAULT_WAIT_TIMEOUT_MS,
usage_hint_text: None,
root_agent_usage_hint_text: Some(default_multi_agent_v2_usage_hint_text(
DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT,
max_concurrent_threads_per_session,
Some(DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT),
)),
subagent_usage_hint_text: Some(default_multi_agent_v2_usage_hint_text(
DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT,
max_concurrent_threads_per_session,
Some(DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT),
)),
root_agent_usage_hint_text: None,
subagent_usage_hint_text: None,
subagent_developer_instructions: None,
multi_agent_mode_hint_text: None,
tool_namespace: Some(DEFAULT_MULTI_AGENT_V2_TOOL_NAMESPACE.to_string()),
@@ -2725,42 +2655,15 @@ fn resolve_multi_agent_v2_config(config_toml: &ConfigToml) -> MultiAgentV2Config
let expose_spawn_agent_model_overrides = base
.and_then(|config| config.expose_spawn_agent_model_overrides)
.unwrap_or(default.expose_spawn_agent_model_overrides);
let root_agent_usage_hint_text = base
.and_then(|config| config.root_agent_usage_hint_text.as_ref())
.cloned();
let subagent_usage_hint_text = base
.and_then(|config| config.subagent_usage_hint_text.as_ref())
.cloned();
let wait_agent_enabled = base
.and_then(|config| config.wait_agent_enabled)
.unwrap_or(default.wait_agent_enabled);
let default_wait_agent_usage_hint_text = if wait_agent_enabled {
Some(DEFAULT_MULTI_AGENT_V2_WAIT_AGENT_USAGE_HINT_TEXT)
} else {
None
};
let mut default_root_agent_usage_hint_text = Some(default_multi_agent_v2_usage_hint_text(
DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT,
max_concurrent_threads_per_session,
default_wait_agent_usage_hint_text,
));
let mut default_subagent_usage_hint_text = Some(default_multi_agent_v2_usage_hint_text(
DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT,
max_concurrent_threads_per_session,
default_wait_agent_usage_hint_text,
));
if expose_spawn_agent_model_overrides {
default_root_agent_usage_hint_text = Some(append_usage_hint_text(
default_root_agent_usage_hint_text.as_deref(),
DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT,
));
default_subagent_usage_hint_text = Some(append_usage_hint_text(
default_subagent_usage_hint_text.as_deref(),
DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT,
));
}
let root_agent_usage_hint_text = resolve_optional_prompt_text(
base.map(|config| &config.root_agent_usage_hint_text),
default_root_agent_usage_hint_text,
);
let subagent_usage_hint_text = resolve_optional_prompt_text(
base.map(|config| &config.subagent_usage_hint_text),
default_subagent_usage_hint_text,
);
let subagent_developer_instructions = base
.and_then(|config| config.subagent_developer_instructions.as_ref())
.map(|instructions| instructions.trim().to_string());
@@ -2941,24 +2844,6 @@ fn resolve_terminal_resize_reflow_config(config_toml: &ConfigToml) -> TerminalRe
}
}
fn resolve_optional_prompt_text(
configured: Option<&Option<String>>,
default: Option<String>,
) -> Option<String> {
match configured {
Some(Some(value)) if value.is_empty() => None,
Some(Some(value)) => Some(value.clone()),
Some(None) | None => default,
}
}
fn append_usage_hint_text(usage_hint_text: Option<&str>, additional_text: &str) -> String {
match usage_hint_text {
Some(usage_hint_text) => format!("{usage_hint_text}\n\n{additional_text}"),
None => additional_text.to_string(),
}
}
fn code_mode_toml_config(features: Option<&FeaturesToml>) -> Option<&CodeModeConfigToml> {
match features?.code_mode.as_ref()? {
FeatureToml::Enabled(_) => None,