diff --git a/codex-rs/core/src/agent/host/admission.rs b/codex-rs/core/src/agent/host/admission.rs
index f4c5b4f7c8..04f4e3e6a7 100644
--- a/codex-rs/core/src/agent/host/admission.rs
+++ b/codex-rs/core/src/agent/host/admission.rs
@@ -22,6 +22,8 @@ pub struct AgentTurnAdmissionRequest {
/// A submitted turn can be denied after its input was accepted. Core records that
/// input and reports the error through the ordinary turn lifecycle.
/// Hosts own remote retries, abandoned acquisitions and worker-loss recovery.
+/// Default hosted roles advertise `multi_agent_v2.max_concurrent_threads_per_session`.
+/// Hosts should set it to their admission limit or override the role text.
pub trait AgentTurnAdmission: Send + Sync {
fn admit_turn(
&self,
diff --git a/codex-rs/core/src/config/config_tests.rs b/codex-rs/core/src/config/config_tests.rs
index 5c8016b470..55dbe04646 100644
--- a/codex-rs/core/src/config/config_tests.rs
+++ b/codex-rs/core/src/config/config_tests.rs
@@ -13115,9 +13115,10 @@ expose_spawn_agent_model_overrides = true
}
#[test]
-fn multi_agent_v2_disabled_native_tools_omit_default_roles() {
+fn multi_agent_v2_disabled_native_tools_keep_only_concurrency() {
let mut config = resolve_multi_agent_v2_config(&ConfigToml::default());
config.disable_native_tools = true;
+ config.max_concurrent_threads_per_session = 17;
let mut messages = ResolvedModelMessages::bundled().multi_agent();
for catalog_override in [false, true] {
if catalog_override {
@@ -13127,7 +13128,13 @@ fn multi_agent_v2_disabled_native_tools_omit_default_roles() {
let usage_hints = resolve_usage_hints(
&config, messages, /*omit_update_plan_instructions*/ false,
);
- assert_eq!((usage_hints.root, usage_hints.subagent), (None, None));
+ let expected = Some(
+ crate::context::MultiAgentRoleInstructions::concurrency_only(
+ /*max_concurrency*/ 17,
+ ),
+ );
+ assert_eq!(usage_hints.root, expected);
+ assert_eq!(usage_hints.subagent, expected);
}
}
diff --git a/codex-rs/core/src/session/multi_agents.rs b/codex-rs/core/src/session/multi_agents.rs
index 29c9fcd1c2..616c5c3aaf 100644
--- a/codex-rs/core/src/session/multi_agents.rs
+++ b/codex-rs/core/src/session/multi_agents.rs
@@ -55,7 +55,9 @@ pub(crate) fn resolve_usage_hints(
return None;
}
if config.disable_native_tools {
- return None;
+ return Some(MultiAgentRoleInstructions::concurrency_only(
+ config.max_concurrent_threads_per_session,
+ ));
}
Some(MultiAgentRoleInstructions::Composed {
base: base.to_owned(),
diff --git a/codex-rs/core/tests/suite/scenarios.rs b/codex-rs/core/tests/suite/scenarios.rs
index 0939a500d8..8640cdbc3b 100644
--- a/codex-rs/core/tests/suite/scenarios.rs
+++ b/codex-rs/core/tests/suite/scenarios.rs
@@ -2445,7 +2445,7 @@ async fn multi_agent_catalog_parameters(
} else if disable_native_tools {
(
"multi_agent_native_tools_hidden",
- "Native tools and native usage guidance are unavailable.",
+ "The root receives the session concurrency limit with native tools hidden.",
)
} else {
(
diff --git a/codex-rs/core/tests/suite/scenarios_injected_agent_mail.rs b/codex-rs/core/tests/suite/scenarios_injected_agent_mail.rs
index 7f22668287..e2b7aa2bde 100644
--- a/codex-rs/core/tests/suite/scenarios_injected_agent_mail.rs
+++ b/codex-rs/core/tests/suite/scenarios_injected_agent_mail.rs
@@ -81,6 +81,7 @@ async fn injected_mail_respects_delivery_boundaries() -> anyhow::Result<()> {
.enable(Feature::MultiAgentV2)
.expect("use MAv2");
config.multi_agent_v2.disable_native_tools = true;
+ config.multi_agent_v2.root_agent_usage_hint_text = Some(String::new());
config.multi_agent_v2.multi_agent_mode_hint_text = Some(String::new());
config
.features
diff --git a/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs b/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs
index ed426b77cf..cb9769f900 100644
--- a/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs
+++ b/codex-rs/core/tests/suite/scenarios_reserved_spawn.rs
@@ -186,6 +186,7 @@ async fn prepared_child_instructions_preserve_native_inheritance(
config.developer_instructions = Some(PARENT_DEVELOPER.into());
config.multi_agent_v2.subagent_developer_instructions =
subagent_developer.map(str::to_owned);
+ config.multi_agent_v2.root_agent_usage_hint_text = Some(String::new());
config
.features
.enable(Feature::IncrementalTools)
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden.snap
index 2352361684..9c7558977d 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden.snap
@@ -2,7 +2,7 @@
source: core/tests/suite/scenarios.rs
expression: "context_snapshot::format_request_history_snapshot(description,\n&mock.requests(),\n&ContextSnapshotOptions::default().include_request_settings(),)"
---
-Scenario: Native tools and native usage guidance are unavailable.
+Scenario: The root receives the session concurrency limit with native tools hidden.
## Window 1
Settings:
@@ -48,12 +48,14 @@ Settings:
Approval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.
03:message/developer:
+ There are 4 available concurrency slots, meaning that up to 4 agents can be active at once, including you.
+04:message/developer:
Any earlier instruction enabling proactive multi-agent delegation no longer applies. Do not spawn sub-ag...k for sub-agents, delegation, or parallel agent work. [hash=6e1e1baf5a87faf5]
Before calling any multi-agent tool, read the full multi-agent skill using its listed package locator. S...context. If the read fails, make note of the blocker. [hash=104096cdd6a881da]
-04:message/user:
+05:message/user:
@@ -61,9 +63,9 @@ Settings:
<...e="unrestricted" /> [hash=d40b2f45cb028888]
-05:message/user:
+06:message/user:
Check which agents are working under /root before delegating more work.
-06:configuration_update:reasoning={"effort":"low"}
+07:configuration_update:reasoning={"effort":"low"}
-- request 2 (turn) --
-07:function_call/collaboration.list_agents:{"path_prefix":"/root"}
-08:function_call_output:unsupported call: collaborationlist_agents
+08:function_call/collaboration.list_agents:{"path_prefix":"/root"}
+09:function_call_output:unsupported call: collaborationlist_agents
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden_proactive.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden_proactive.snap
index 9f36a5d44e..5793911912 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden_proactive.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_native_tools_hidden_proactive.snap
@@ -48,6 +48,8 @@ Settings:
Approval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.
03:message/developer:
+ There are 4 available concurrency slots, meaning that up to 4 agents can be active at once, including you.
+04:message/developer:
Proactive multi-agent delegation is active. Any earlier developer instruction requiring an explicit user...message changes it. User requests override this hint. [hash=0917619915af4b51]
@@ -55,7 +57,7 @@ Settings:
Before calling any multi-agent tool, read the full multi-agent skill using its listed package locator. S...context. If the read fails, make note of the blocker. [hash=104096cdd6a881da]
-04:message/user:
+05:message/user:
@@ -63,9 +65,9 @@ Settings:
<...e="unrestricted" /> [hash=d40b2f45cb028888]
-05:message/user:
+06:message/user:
Check which agents are working under /root before delegating more work.
-06:configuration_update:reasoning={"effort":"xhigh"}
+07:configuration_update:reasoning={"effort":"xhigh"}
-- request 2 (turn) --
-07:function_call/collaboration.list_agents:{"path_prefix":"/root"}
-08:function_call_output:unsupported call: collaborationlist_agents
+08:function_call/collaboration.list_agents:{"path_prefix":"/root"}
+09:function_call_output:unsupported call: collaborationlist_agents
diff --git a/codex-rs/prompts/src/multi_agent_instructions.rs b/codex-rs/prompts/src/multi_agent_instructions.rs
index bf28cce32a..c4283271ee 100644
--- a/codex-rs/prompts/src/multi_agent_instructions.rs
+++ b/codex-rs/prompts/src/multi_agent_instructions.rs
@@ -21,7 +21,7 @@ All agents share the same directory. In detail:
/// Multi-agent role text and the captured capabilities used to render its context segment.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MultiAgentRoleInstructions {
- /// Complete configured role body.
+ /// Complete role body.
Configured(String),
/// Selected catalog or bundled text, composed with captured runtime guidance.
Composed {
@@ -36,6 +36,10 @@ pub enum MultiAgentRoleInstructions {
impl MultiAgentRoleInstructions {
/// Content classification shared by role producers and inherited-history filtering.
pub const KIND: &str = "multi_agent.role_instructions";
+
+ pub fn concurrency_only(max_concurrency: usize) -> Self {
+ Self::Configured(concurrency_guidance(max_concurrency))
+ }
}
impl ContextualUserFragment for MultiAgentRoleInstructions {
@@ -79,9 +83,8 @@ impl ContextualUserFragment for MultiAgentRoleInstructions {
String::new()
};
let shared = DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT;
- let mut text = format!(
- "{base}\n{shared}\n{wait_agent_guidance}There are {max_concurrency} available concurrency slots, meaning that up to {max_concurrency} agents can be active at once, including you."
- );
+ let concurrency = concurrency_guidance(*max_concurrency);
+ let mut text = format!("{base}\n{shared}\n{wait_agent_guidance}{concurrency}");
if *expose_model_overrides {
text.push_str("\n\n");
text.push_str(DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT);
@@ -92,6 +95,12 @@ impl ContextualUserFragment for MultiAgentRoleInstructions {
}
}
+fn concurrency_guidance(max_concurrency: usize) -> String {
+ format!(
+ "There are {max_concurrency} available concurrency slots, meaning that up to {max_concurrency} agents can be active at once, including you."
+ )
+}
+
#[cfg(test)]
#[path = "multi_agent_instructions_tests.rs"]
mod tests;