Reject conflicting namespace descriptions in strict tool mode (#37053)

## What changed

- Treat different non-empty descriptions for the same tool namespace as a
  collision when `error_on_tool_collisions` is enabled, including deferred
  tools.
- Continue allowing multiple tools to share a namespace when their descriptions
  match or are empty.
- Preserve the first non-empty namespace description when strict collision
  checking is disabled.

## Testing

- Cover strict collisions across direct and deferred tools, valid shared
  namespaces, relaxed description merging, and failure before model sampling.

GitOrigin-RevId: 788a2ae0eccb64c97995af7a208d9abb79edf2d0
This commit is contained in:
rka-oai
2026-08-05 08:01:47 +00:00
committed by copyberry
parent ed2f985a26
commit 3171166881
3 changed files with 180 additions and 21 deletions
+25 -6
View File
@@ -349,12 +349,31 @@ pub(crate) fn finalize_tool_router(
let code_mode_tool_names = register_code_mode_executors(turn_context, &mut registry);
if turn_context.config.tool_registry.error_on_tool_collisions
&& let Some(tool_name) = registry.first_collision()
{
let namespace = tool_name.namespace.as_deref().unwrap_or("functions");
let name = format!("{namespace}.{}", tool_name.name);
return Err(CodexErrorDetails::ToolCollision(name).into());
if turn_context.config.tool_registry.error_on_tool_collisions {
if let Some(tool_name) = registry.first_collision() {
let namespace = tool_name.namespace.as_deref().unwrap_or("functions");
let name = format!("{namespace}.{}", tool_name.name);
return Err(CodexErrorDetails::ToolCollision(name).into());
}
let mut namespace_descriptions = BTreeMap::new();
for tool in registry.entries() {
let ToolSpec::Namespace(namespace) = tool.runtime.spec() else {
continue;
};
if namespace.description.trim().is_empty() {
continue;
}
match namespace_descriptions.entry(namespace.name) {
Entry::Vacant(entry) => {
entry.insert(namespace.description);
}
Entry::Occupied(entry) if entry.get() != &namespace.description => {
return Err(CodexErrorDetails::ToolCollision(entry.key().clone()).into());
}
Entry::Occupied(_) => {}
}
}
}
let model_visible_specs =
+102 -1
View File
@@ -1303,7 +1303,30 @@ async fn strict_tool_collisions_reject_external_and_synthetic_duplicates() {
),
];
for (expected_name, inputs, code_mode_enabled, search_enabled) in cases {
let namespace_cases = [
(ToolExposure::Direct, ToolExposure::Direct, false),
(ToolExposure::Direct, ToolExposure::Deferred, true),
(ToolExposure::Deferred, ToolExposure::Deferred, true),
(ToolExposure::Deferred, ToolExposure::Deferred, false),
]
.map(|(first_exposure, second_exposure, search_enabled)| {
(
"shared",
ToolPlanInputs {
tool_runtimes: vec![
mcp_runtime("first", "shared", "lookup", first_exposure),
mcp_runtime("second", "shared", "list", second_exposure),
],
..ToolPlanInputs::default()
},
false,
search_enabled,
)
});
for (expected_name, inputs, code_mode_enabled, search_enabled) in
cases.into_iter().chain(namespace_cases)
{
let (_session, mut turn) = make_session_and_context().await;
update_config(&mut turn, |config| {
config.tool_registry.error_on_tool_collisions = true;
@@ -1348,6 +1371,84 @@ async fn strict_tool_collisions_reject_external_and_synthetic_duplicates() {
}
}
#[tokio::test]
async fn strict_tool_collisions_allow_multiple_tools_in_one_namespace() {
let mut undocumented_tool = mcp_tool("shared", "shared", "undocumented");
undocumented_tool.namespace_description = None;
let plan = probe_with(
|turn| {
update_config(turn, |config| {
config.tool_registry.error_on_tool_collisions = true;
});
},
ToolPlanInputs {
tool_runtimes: vec![
RegisteredTool {
runtime: Arc::new(
McpHandler::new(undocumented_tool).expect("MCP tool spec should build"),
),
exposure: ToolExposure::Direct,
},
mcp_runtime("shared", "shared", "lookup", ToolExposure::Direct),
mcp_runtime("shared", "shared", "list", ToolExposure::Direct),
],
..ToolPlanInputs::default()
},
)
.await;
assert_eq!(
plan.namespace_function_names("shared"),
["list", "lookup", "undocumented"]
);
let ToolSpec::Namespace(namespace) = plan.visible_spec("shared") else {
panic!("expected the shared namespace to stay visible");
};
assert_eq!(namespace.description, "Tools from shared.");
}
#[tokio::test]
async fn relaxed_tool_collisions_preserve_first_nonempty_namespace_description() {
for (first_description, second_description, expected_description) in [
(
Some("First namespace description."),
Some("Second namespace description."),
"First namespace description.",
),
(
None,
Some("Second namespace description."),
"Second namespace description.",
),
] {
let runtime = |name, description: Option<&str>| {
let mut tool = mcp_tool("shared", "shared", name);
tool.namespace_description = description.map(str::to_string);
RegisteredTool {
runtime: Arc::new(McpHandler::new(tool).expect("MCP tool spec should build")),
exposure: ToolExposure::Direct,
}
};
let plan = probe_with(
|_| {},
ToolPlanInputs {
tool_runtimes: vec![
runtime("lookup", first_description),
runtime("list", second_description),
],
..ToolPlanInputs::default()
},
)
.await;
assert_eq!(plan.namespace_function_names("shared"), ["list", "lookup"]);
let ToolSpec::Namespace(namespace) = plan.visible_spec("shared") else {
panic!("expected the shared namespace to stay visible");
};
assert_eq!(namespace.description, expected_description);
}
}
#[tokio::test]
async fn strict_tool_collisions_allow_identical_names_in_different_namespaces() {
let plan = probe_with(
+53 -14
View File
@@ -12,6 +12,8 @@ use codex_core::config::Constrained;
use codex_core::sandboxing::SandboxPermissions;
use codex_features::Feature;
use codex_protocol::dynamic_tools::DynamicToolFunctionSpec;
use codex_protocol::dynamic_tools::DynamicToolNamespaceSpec;
use codex_protocol::dynamic_tools::DynamicToolNamespaceTool;
use codex_protocol::dynamic_tools::DynamicToolSpec;
use codex_protocol::models::PermissionProfile;
use codex_protocol::permissions::FileSystemAccessMode;
@@ -66,10 +68,14 @@ fn tool_names(body: &Value) -> Vec<String> {
.unwrap_or_default()
}
#[test_case(false; "normal sampling")]
#[test_case(true; "pre sampling compaction")]
#[test_case(false, false; "normal sampling")]
#[test_case(true, false; "pre sampling compaction")]
#[test_case(false, true; "namespace collision")]
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn strict_tool_collisions_fail_the_turn_before_sampling(pre_compact: bool) -> Result<()> {
async fn strict_tool_collisions_fail_the_turn_before_sampling(
pre_compact: bool,
namespace_collision: bool,
) -> Result<()> {
skip_if_no_network!(Ok(()));
let server = start_mock_server().await;
@@ -80,19 +86,47 @@ async fn strict_tool_collisions_fail_the_turn_before_sampling(pre_compact: bool)
}
});
let test = builder.build_with_auto_env(&server).await?;
let dynamic_tools = if namespace_collision {
[
("first", "First namespace description."),
("second", "Second namespace description."),
]
.into_iter()
.map(|(name, description)| {
DynamicToolSpec::Namespace(DynamicToolNamespaceSpec {
name: "shared".to_string(),
description: description.to_string(),
tools: vec![DynamicToolNamespaceTool::Function(
DynamicToolFunctionSpec {
name: name.to_string(),
description: format!("The {name} tool."),
input_schema: json!({
"type": "object",
"properties": {},
"additionalProperties": false,
}),
defer_loading: false,
},
)],
})
})
.collect()
} else {
vec![DynamicToolSpec::Function(DynamicToolFunctionSpec {
name: "update_plan".to_string(),
description: "Collides with the built-in planning tool.".to_string(),
input_schema: json!({
"type": "object",
"properties": {},
"additionalProperties": false,
}),
defer_loading: false,
})]
};
let thread = test
.thread_manager
.start_thread(StartThreadOptions {
dynamic_tools: vec![DynamicToolSpec::Function(DynamicToolFunctionSpec {
name: "update_plan".to_string(),
description: "Collides with the built-in planning tool.".to_string(),
input_schema: json!({
"type": "object",
"properties": {},
"additionalProperties": false,
}),
defer_loading: false,
})],
dynamic_tools,
..StartThreadOptions::new(test.config.clone())
})
.await?
@@ -116,7 +150,12 @@ async fn strict_tool_collisions_fail_the_turn_before_sampling(pre_compact: bool)
else {
unreachable!("event predicate guarantees an error");
};
assert_eq!(error.message, "duplicate tool: functions.update_plan");
let expected_collision = if namespace_collision {
"duplicate tool: shared"
} else {
"duplicate tool: functions.update_plan"
};
assert_eq!(error.message, expected_collision);
let EventMsg::TurnComplete(completed) =
wait_for_event(&thread, |event| matches!(event, EventMsg::TurnComplete(_))).await