Add global subagent nickname pool fallback

This commit is contained in:
Nick Baumann
2026-03-18 17:34:26 -07:00
parent 580f32ad2a
commit 8b873c0ba8
6 changed files with 289 additions and 0 deletions
+7
View File
@@ -53,6 +53,13 @@
"format": "uint",
"minimum": 1.0,
"type": "integer"
},
"nickname_pool": {
"description": "Global fallback nickname candidates for spawned agent threads.\n\nExample: ```toml [agents] nickname_pool = [\"Scout\", \"Builder\", \"Reviewer\"] ```",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
+4
View File
@@ -54,6 +54,10 @@ fn agent_nickname_candidates(
return candidates;
}
if !config.agent_nickname_pool.is_empty() {
return config.agent_nickname_pool.clone();
}
default_agent_nickname_list()
.into_iter()
.map(ToOwned::to_owned)
+88
View File
@@ -961,6 +961,94 @@ async fn spawn_thread_subagent_uses_role_specific_nickname_candidates() {
assert_eq!(agent_nickname, Some("Atlas".to_string()));
}
#[tokio::test]
async fn spawn_thread_subagent_uses_global_nickname_pool_when_role_has_no_candidates() {
let mut harness = AgentControlHarness::new().await;
harness.config.agent_nickname_pool = vec!["Scout".to_string()];
harness.config.agent_roles.insert(
"researcher".to_string(),
AgentRoleConfig {
description: Some("Research role".to_string()),
config_file: None,
nickname_candidates: None,
},
);
let (parent_thread_id, _parent_thread) = harness.start_thread().await;
let child_thread_id = harness
.control
.spawn_agent(
harness.config.clone(),
text_input("hello child"),
Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn {
parent_thread_id,
depth: 1,
agent_nickname: None,
agent_role: Some("researcher".to_string()),
})),
)
.await
.expect("child spawn should succeed");
let child_thread = harness
.manager
.get_thread(child_thread_id)
.await
.expect("child thread should be registered");
let snapshot = child_thread.config_snapshot().await;
let SessionSource::SubAgent(SubAgentSource::ThreadSpawn { agent_nickname, .. }) =
snapshot.session_source
else {
panic!("expected thread-spawn sub-agent source");
};
assert_eq!(agent_nickname, Some("Scout".to_string()));
}
#[tokio::test]
async fn spawn_thread_subagent_prefers_role_candidates_over_global_nickname_pool() {
let mut harness = AgentControlHarness::new().await;
harness.config.agent_nickname_pool = vec!["Scout".to_string()];
harness.config.agent_roles.insert(
"researcher".to_string(),
AgentRoleConfig {
description: Some("Research role".to_string()),
config_file: None,
nickname_candidates: Some(vec!["Atlas".to_string()]),
},
);
let (parent_thread_id, _parent_thread) = harness.start_thread().await;
let child_thread_id = harness
.control
.spawn_agent(
harness.config.clone(),
text_input("hello child"),
Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn {
parent_thread_id,
depth: 1,
agent_nickname: None,
agent_role: Some("researcher".to_string()),
})),
)
.await
.expect("child spawn should succeed");
let child_thread = harness
.manager
.get_thread(child_thread_id)
.await
.expect("child thread should be registered");
let snapshot = child_thread.config_snapshot().await;
let SessionSource::SubAgent(SubAgentSource::ThreadSpawn { agent_nickname, .. }) =
snapshot.session_source
else {
panic!("expected thread-spawn sub-agent source");
};
assert_eq!(agent_nickname, Some("Atlas".to_string()));
}
#[tokio::test]
async fn resume_thread_subagent_restores_stored_nickname_and_role() {
let (home, mut config) = test_config().await;
+41
View File
@@ -441,6 +441,47 @@ fn normalize_agent_role_nickname_candidates(
Ok(Some(normalized_candidates))
}
pub(crate) fn normalize_agent_nickname_pool(
field_label: &str,
nickname_pool: Option<&[String]>,
) -> std::io::Result<Option<Vec<String>>> {
let Some(nickname_pool) = nickname_pool else {
return Ok(None);
};
let mut normalized_candidates = Vec::with_capacity(nickname_pool.len());
let mut seen_candidates = BTreeSet::new();
for nickname in nickname_pool {
let normalized_nickname = nickname.trim();
if normalized_nickname.is_empty() {
continue;
}
if !normalized_nickname
.chars()
.all(|c| c.is_ascii_alphanumeric() || matches!(c, ' ' | '-' | '_'))
{
return Err(std::io::Error::new(
std::io::ErrorKind::InvalidInput,
format!(
"{field_label} may only contain ASCII letters, digits, spaces, hyphens, and underscores"
),
));
}
if seen_candidates.insert(normalized_nickname.to_owned()) {
normalized_candidates.push(normalized_nickname.to_owned());
}
}
if normalized_candidates.is_empty() {
Ok(None)
} else {
Ok(Some(normalized_candidates))
}
}
fn discover_agent_roles_in_dir(
agents_dir: &Path,
declared_role_files: &BTreeSet<PathBuf>,
+129
View File
@@ -107,6 +107,23 @@ persistence = "none"
history_no_persistence_cfg.history
);
let agents_with_nickname_pool = r#"
[agents]
nickname_pool = ["Scout", "Builder", "Reviewer"]
"#;
let agents_with_nickname_pool_cfg = toml::from_str::<ConfigToml>(agents_with_nickname_pool)
.expect("TOML deserialization should succeed");
assert_eq!(
agents_with_nickname_pool_cfg
.agents
.and_then(|agents| agents.nickname_pool),
Some(vec![
"Scout".to_string(),
"Builder".to_string(),
"Reviewer".to_string()
])
);
let memories = r#"
[memories]
no_memories_if_mcp_or_web_search = true
@@ -1579,6 +1596,109 @@ profile = "project"
Ok(())
}
#[tokio::test]
async fn user_agents_nickname_pool_is_used_without_project_override() -> std::io::Result<()> {
let codex_home = TempDir::new()?;
let workspace = TempDir::new()?;
let workspace_key = workspace.path().to_string_lossy().replace('\\', "\\\\");
std::fs::write(
codex_home.path().join(CONFIG_TOML_FILE),
format!(
r#"
[agents]
nickname_pool = [" Scout ", "", "Builder", "Scout", " ", "Reviewer"]
[projects."{workspace_key}"]
trust_level = "trusted"
"#,
),
)?;
let config = ConfigBuilder::default()
.codex_home(codex_home.path().to_path_buf())
.fallback_cwd(Some(workspace.path().to_path_buf()))
.build()
.await?;
assert_eq!(
config.agent_nickname_pool,
vec![
"Scout".to_string(),
"Builder".to_string(),
"Reviewer".to_string()
]
);
Ok(())
}
#[tokio::test]
async fn project_agents_nickname_pool_overrides_user_pool() -> std::io::Result<()> {
let codex_home = TempDir::new()?;
let workspace = TempDir::new()?;
let workspace_key = workspace.path().to_string_lossy().replace('\\', "\\\\");
std::fs::write(
codex_home.path().join(CONFIG_TOML_FILE),
format!(
r#"
[agents]
nickname_pool = ["Scout", "Builder"]
[projects."{workspace_key}"]
trust_level = "trusted"
"#,
),
)?;
let project_config_dir = workspace.path().join(".codex");
std::fs::create_dir_all(&project_config_dir)?;
std::fs::write(
project_config_dir.join(CONFIG_TOML_FILE),
r#"
[agents]
nickname_pool = ["Reviewer"]
"#,
)?;
let config = ConfigBuilder::default()
.codex_home(codex_home.path().to_path_buf())
.fallback_cwd(Some(workspace.path().to_path_buf()))
.build()
.await?;
assert_eq!(config.agent_nickname_pool, vec!["Reviewer".to_string()]);
Ok(())
}
#[tokio::test]
async fn empty_agents_nickname_pool_preserves_default_behavior() -> std::io::Result<()> {
let codex_home = TempDir::new()?;
let workspace = TempDir::new()?;
let workspace_key = workspace.path().to_string_lossy().replace('\\', "\\\\");
std::fs::write(
codex_home.path().join(CONFIG_TOML_FILE),
format!(
r#"
[agents]
nickname_pool = ["", " "]
[projects."{workspace_key}"]
trust_level = "trusted"
"#,
),
)?;
let config = ConfigBuilder::default()
.codex_home(codex_home.path().to_path_buf())
.fallback_cwd(Some(workspace.path().to_path_buf()))
.build()
.await?;
assert!(config.agent_nickname_pool.is_empty());
Ok(())
}
#[test]
fn profile_sandbox_mode_overrides_base() -> std::io::Result<()> {
let codex_home = TempDir::new()?;
@@ -3064,6 +3184,7 @@ fn load_config_rejects_missing_agent_role_config_file() -> std::io::Result<()> {
max_threads: None,
max_depth: None,
job_max_runtime_seconds: None,
nickname_pool: None,
roles: BTreeMap::from([(
"researcher".to_string(),
AgentRoleToml {
@@ -3929,6 +4050,7 @@ fn load_config_normalizes_agent_role_nickname_candidates() -> std::io::Result<()
max_threads: None,
max_depth: None,
job_max_runtime_seconds: None,
nickname_pool: None,
roles: BTreeMap::from([(
"researcher".to_string(),
AgentRoleToml {
@@ -3970,6 +4092,7 @@ fn load_config_rejects_empty_agent_role_nickname_candidates() -> std::io::Result
max_threads: None,
max_depth: None,
job_max_runtime_seconds: None,
nickname_pool: None,
roles: BTreeMap::from([(
"researcher".to_string(),
AgentRoleToml {
@@ -4005,6 +4128,7 @@ fn load_config_rejects_duplicate_agent_role_nickname_candidates() -> std::io::Re
max_threads: None,
max_depth: None,
job_max_runtime_seconds: None,
nickname_pool: None,
roles: BTreeMap::from([(
"researcher".to_string(),
AgentRoleToml {
@@ -4040,6 +4164,7 @@ fn load_config_rejects_unsafe_agent_role_nickname_candidates() -> std::io::Resul
max_threads: None,
max_depth: None,
job_max_runtime_seconds: None,
nickname_pool: None,
roles: BTreeMap::from([(
"researcher".to_string(),
AgentRoleToml {
@@ -4284,6 +4409,7 @@ fn test_precedence_fixture_with_o3_profile() -> std::io::Result<()> {
tool_output_token_limit: None,
agent_max_threads: DEFAULT_AGENT_MAX_THREADS,
agent_max_depth: DEFAULT_AGENT_MAX_DEPTH,
agent_nickname_pool: Vec::new(),
agent_roles: BTreeMap::new(),
memories: MemoriesConfig::default(),
agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS,
@@ -4425,6 +4551,7 @@ fn test_precedence_fixture_with_gpt3_profile() -> std::io::Result<()> {
tool_output_token_limit: None,
agent_max_threads: DEFAULT_AGENT_MAX_THREADS,
agent_max_depth: DEFAULT_AGENT_MAX_DEPTH,
agent_nickname_pool: Vec::new(),
agent_roles: BTreeMap::new(),
memories: MemoriesConfig::default(),
agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS,
@@ -4564,6 +4691,7 @@ fn test_precedence_fixture_with_zdr_profile() -> std::io::Result<()> {
tool_output_token_limit: None,
agent_max_threads: DEFAULT_AGENT_MAX_THREADS,
agent_max_depth: DEFAULT_AGENT_MAX_DEPTH,
agent_nickname_pool: Vec::new(),
agent_roles: BTreeMap::new(),
memories: MemoriesConfig::default(),
agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS,
@@ -4689,6 +4817,7 @@ fn test_precedence_fixture_with_gpt5_profile() -> std::io::Result<()> {
tool_output_token_limit: None,
agent_max_threads: DEFAULT_AGENT_MAX_THREADS,
agent_max_depth: DEFAULT_AGENT_MAX_DEPTH,
agent_nickname_pool: Vec::new(),
agent_roles: BTreeMap::new(),
memories: MemoriesConfig::default(),
agent_job_max_runtime_seconds: DEFAULT_AGENT_JOB_MAX_RUNTIME_SECONDS,
+20
View File
@@ -417,6 +417,9 @@ pub struct Config {
/// Maximum nesting depth allowed for spawned agent threads.
pub agent_max_depth: i32,
/// Global fallback nickname candidates for spawned agent threads.
pub agent_nickname_pool: Vec<String>,
/// User-defined role declarations keyed by role name.
pub agent_roles: BTreeMap<String, AgentRoleConfig>,
@@ -1666,6 +1669,15 @@ pub struct AgentsToml {
#[schemars(range(min = 1))]
pub job_max_runtime_seconds: Option<u64>,
/// Global fallback nickname candidates for spawned agent threads.
///
/// Example:
/// ```toml
/// [agents]
/// nickname_pool = ["Scout", "Builder", "Reviewer"]
/// ```
pub nickname_pool: Option<Vec<String>>,
/// User-defined role declarations keyed by role name.
///
/// Example:
@@ -2442,6 +2454,13 @@ impl Config {
"agents.job_max_runtime_seconds must fit within a 64-bit signed integer",
));
}
let agent_nickname_pool = agent_roles::normalize_agent_nickname_pool(
"agents.nickname_pool",
cfg.agents
.as_ref()
.and_then(|agents| agents.nickname_pool.as_deref()),
)?
.unwrap_or_default();
let background_terminal_max_timeout = cfg
.background_terminal_max_timeout
.unwrap_or(DEFAULT_MAX_BACKGROUND_TERMINAL_TIMEOUT_MS)
@@ -2707,6 +2726,7 @@ impl Config {
tool_output_token_limit: cfg.tool_output_token_limit,
agent_max_threads,
agent_max_depth,
agent_nickname_pool,
agent_roles,
memories: cfg.memories.unwrap_or_default().into(),
agent_job_max_runtime_seconds,