Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Centralize tool registration and protect host tools (#36127)

jif89a0eed93c9b
diff --git a/codex-rs/core/src/mcp_tool_exposure.rs b/codex-rs/core/src/mcp_tool_exposure.rs
index 1bbd028608..6c77604a31 100644
--- a/codex-rs/core/src/mcp_tool_exposure.rs
+++ b/codex-rs/core/src/mcp_tool_exposure.rs
@@ -17,93 +17,80 @@ use crate::tools::registry::CoreToolRuntime;
use crate::tools::registry::override_tool_exposure;
#[instrument(level = "trace", skip_all)]
-pub(crate) fn build_mcp_tool_runtimes(
- all_mcp_tools: &[McpToolInfo],
- connectors: Option<&[connectors::AppInfo]>,
- config: &Config,
+pub(crate) fn build_mcp_tool_runtimes<'a>(
+ all_mcp_tools: &'a [McpToolInfo],
+ connectors: Option<&'a [connectors::AppInfo]>,
+ config: &'a Config,
search_tool_enabled: bool,
-) -> Vec<Arc<dyn CoreToolRuntime>> {
- let mut exposed_tools = filter_non_codex_apps_mcp_tools_only(all_mcp_tools);
- if let Some(connectors) = connectors {
- exposed_tools.extend(filter_codex_apps_mcp_tools(
- all_mcp_tools,
- connectors,
- config,
- ));
- }
-
+) -> impl Iterator<Item = Arc<dyn CoreToolRuntime>> + 'a {
+ // Keep regular MCP tools first; Apps tools also require connector and policy checks.
+ let non_app_tools = filter_non_codex_apps_mcp_tools_only(all_mcp_tools);
+ let app_tools = connectors
+ .into_iter()
+ .flat_map(move |connectors| filter_codex_apps_mcp_tools(all_mcp_tools, connectors, config));
let exposure = if search_tool_enabled {
ToolExposure::Deferred
} else {
ToolExposure::Direct
};
- exposed_tools
- .into_iter()
- .filter_map(|tool| {
- let tool_name = tool.canonical_tool_name();
- match McpHandler::new(tool) {
- Ok(handler) => {
- let handler: Arc<dyn CoreToolRuntime> = Arc::new(handler);
- Some(override_tool_exposure(handler, exposure))
- }
- Err(err) => {
- warn!("Skipping MCP tool `{tool_name}`: failed to build tool spec: {err}");
- None
- }
+ non_app_tools.chain(app_tools).filter_map(move |tool| {
+ let tool_name = tool.canonical_tool_name();
+ match McpHandler::new(tool.clone()) {
+ Ok(handler) => {
+ let handler: Arc<dyn CoreToolRuntime> = Arc::new(handler);
+ Some(override_tool_exposure(handler, exposure))
}
- })
- .collect()
+ Err(err) => {
+ warn!("Skipping MCP tool `{tool_name}`: failed to build tool spec: {err}");
+ None
+ }
+ }
+ })
}
-fn filter_non_codex_apps_mcp_tools_only(mcp_tools: &[McpToolInfo]) -> Vec<McpToolInfo> {
- mcp_tools
- .iter()
- .filter(|tool| {
- tool.server_name != CODEX_APPS_MCP_SERVER_NAME && tool_is_model_visible(tool)
- })
- .cloned()
- .collect()
+fn filter_non_codex_apps_mcp_tools_only(
+ mcp_tools: &[McpToolInfo],
+) -> impl Iterator<Item = &McpToolInfo> + '_ {
+ mcp_tools.iter().filter(|tool| {
+ tool.server_name != CODEX_APPS_MCP_SERVER_NAME && tool_is_model_visible(tool)
+ })
}
-fn filter_codex_apps_mcp_tools(
- mcp_tools: &[McpToolInfo],
- connectors: &[connectors::AppInfo],
- config: &Config,
-) -> Vec<McpToolInfo> {
+fn filter_codex_apps_mcp_tools<'a>(
+ mcp_tools: &'a [McpToolInfo],
+ connectors: &'a [connectors::AppInfo],
+ config: &'a Config,
+) -> impl Iterator<Item = &'a McpToolInfo> + 'a {
let allowed: HashSet<&str> = connectors
.iter()
.map(|connector| connector.id.as_str())
.collect();
let app_tool_policy = AppToolPolicyEvaluator::new(&config.config_layer_stack);
- mcp_tools
- .iter()
- .filter(|tool| {
- if tool.server_name != CODEX_APPS_MCP_SERVER_NAME {
- return false;
- }
- if !tool_is_model_visible(tool) {
- return false;
- }
- let Some(connector_id) = tool.connector_id.as_deref() else {
- return false;
- };
- let annotations = tool.tool.annotations.as_ref();
- allowed.contains(connector_id)
- && app_tool_policy
- .policy(AppToolPolicyInput {
- connector_id: Some(connector_id),
- tool_name: &tool.tool.name,
- tool_title: tool.tool.title.as_deref(),
- destructive_hint: annotations
- .and_then(|annotations| annotations.destructive_hint),
- open_world_hint: annotations
- .and_then(|annotations| annotations.open_world_hint),
- })
- .enabled
- })
- .cloned()
- .collect()
+ mcp_tools.iter().filter(move |tool| {
+ if tool.server_name != CODEX_APPS_MCP_SERVER_NAME {
+ return false;
+ }
+ if !tool_is_model_visible(tool) {
+ return false;
+ }
+ let Some(connector_id) = tool.connector_id.as_deref() else {
+ return false;
+ };
+ let annotations = tool.tool.annotations.as_ref();
+ allowed.contains(connector_id)
+ && app_tool_policy
+ .policy(AppToolPolicyInput {
+ connector_id: Some(connector_id),
+ tool_name: &tool.tool.name,
+ tool_title: tool.tool.title.as_deref(),
+ destructive_hint: annotations
+ .and_then(|annotations| annotations.destructive_hint),
+ open_world_hint: annotations
+ .and_then(|annotations| annotations.open_world_hint),
+ })
+ .enabled
+ })
}
#[cfg(test)]
diff --git a/codex-rs/core/src/mcp_tool_exposure_test.rs b/codex-rs/core/src/mcp_tool_exposure_test.rs
index e66edcc95e..8a7a6b4230 100644
--- a/codex-rs/core/src/mcp_tool_exposure_test.rs
+++ b/codex-rs/core/src/mcp_tool_exposure_test.rs
@@ -90,9 +90,11 @@ fn expected_runtimes(
.collect()
}
-fn runtimes_by_name(runtimes: &[Arc<dyn CoreToolRuntime>]) -> HashMap<ToolName, ToolExposure> {
+fn runtimes_by_name(
+ runtimes: impl IntoIterator<Item = Arc<dyn CoreToolRuntime>>,
+) -> HashMap<ToolName, ToolExposure> {
runtimes
- .iter()
+ .into_iter()
.map(|runtime| (runtime.tool_name(), runtime.exposure()))
.collect()
}
@@ -117,7 +119,7 @@ async fn directly_exposes_effective_tool_sets_when_search_is_unavailable() {
);
assert_eq!(
- runtimes_by_name(&runtimes),
+ runtimes_by_name(runtimes),
expected_runtimes(&mcp_tools, ToolExposure::Direct)
);
}
@@ -194,7 +196,7 @@ async fn excludes_tools_hidden_from_model_exposure() {
);
assert_eq!(
- runtimes_by_name(&runtimes),
+ runtimes_by_name(runtimes),
expected_runtimes(&[visible_tool, visible_app_tool], ToolExposure::Direct)
);
}
@@ -236,15 +238,16 @@ enabled = true
);
let connectors = vec![make_connector("calendar", "Calendar")];
+ let mcp_tools = [enabled_tool.clone(), disabled_tool];
let runtimes = build_mcp_tool_runtimes(
- &[enabled_tool.clone(), disabled_tool],
+ &mcp_tools,
Some(connectors.as_slice()),
&config,
/*search_tool_enabled*/ false,
);
assert_eq!(
- runtimes_by_name(&runtimes),
+ runtimes_by_name(runtimes),
expected_runtimes(&[enabled_tool], ToolExposure::Direct)
);
}
@@ -259,7 +262,7 @@ async fn defers_effective_tool_sets_when_search_is_available() {
);
assert_eq!(
- runtimes_by_name(&runtimes),
+ runtimes_by_name(runtimes),
expected_runtimes(&mcp_tools, ToolExposure::Deferred)
);
}
@@ -295,7 +298,7 @@ async fn defers_apps_and_non_app_mcp_tools() {
);
assert_eq!(
- runtimes_by_name(&runtimes),
+ runtimes_by_name(runtimes),
expected_runtimes(&mcp_tools, ToolExposure::Deferred)
);
}
diff --git a/codex-rs/core/src/session/turn.rs b/codex-rs/core/src/session/turn.rs
index 947de8226f..1f16975fc8 100644
--- a/codex-rs/core/src/session/turn.rs
+++ b/codex-rs/core/src/session/turn.rs
@@ -28,7 +28,6 @@ use crate::injection::ToolMentionKind;
use crate::injection::app_id_from_path;
use crate::injection::tool_kind_for_path;
use crate::mcp_skill_dependencies::maybe_prompt_and_install_mcp_dependencies;
-use crate::mcp_tool_exposure::build_mcp_tool_runtimes;
use crate::mentions::build_connector_slug_counts;
use crate::mentions::build_skill_name_counts;
use crate::mentions::collect_explicit_app_ids;
@@ -60,10 +59,7 @@ use crate::tools::parallel::ToolCallRuntime;
use crate::tools::registry::ToolArgumentDiffConsumer;
use crate::tools::router::ToolSuggestCandidates;
use crate::tools::router::ToolSuggestPresentation;
-use crate::tools::spec_plan::append_source_tool_runtimes;
-use crate::tools::spec_plan::build_core_tool_runtimes;
-use crate::tools::spec_plan::extension_tool_executors;
-use crate::tools::spec_plan::search_tool_enabled;
+use crate::tools::spec_plan::build_tool_router;
use crate::tools::spec_plan::tool_suggest_enabled;
use crate::turn_diff_tracker::TurnDiffTracker;
use crate::turn_timing::record_turn_ttft_metric;
@@ -1549,35 +1545,14 @@ pub(crate) async fn built_tools(
.instrument(trace_span!("built_tools.load_discoverable_tools"))
.await
};
- let mcp_tool_runtimes = build_mcp_tool_runtimes(
- &all_mcp_tools,
- connectors.as_deref(),
- &turn_context.config,
- search_tool_enabled(turn_context),
- );
- let wait_for_environment_tool_config = sess
- .services
- .thread_extension_data
- .get::<crate::WaitForEnvironmentToolConfig>();
- let mut tool_runtimes = build_core_tool_runtimes(
+ let tool_router = Arc::new(build_tool_router(
+ sess,
turn_context,
environments,
mcp,
+ connectors.as_deref(),
+ step_store,
tool_suggest_candidates.as_ref(),
- wait_for_environment_tool_config.as_ref(),
- );
- let hosted_specs = append_source_tool_runtimes(
- turn_context,
- &mut tool_runtimes,
- mcp_tool_runtimes,
- extension_tool_executors(sess, step_store),
- &turn_context.dynamic_tools,
- );
- let tool_router = Arc::new(ToolRouter::from_tools(
- turn_context,
- tool_runtimes,
- hosted_specs,
- &sess.services.tool_search_handler_cache,
));
(all_mcp_tools, tool_router)
}
diff --git a/codex-rs/core/src/tools/registry.rs b/codex-rs/core/src/tools/registry.rs
index 37a165e53b..f5dddf0022 100644
--- a/codex-rs/core/src/tools/registry.rs
+++ b/codex-rs/core/src/tools/registry.rs
@@ -1,5 +1,4 @@
use std::collections::BTreeMap;
-use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering;
@@ -39,8 +38,9 @@ use codex_tools::ToolName;
use codex_tools::ToolSearchInfo;
use codex_tools::ToolSpec;
use futures::future::BoxFuture;
+use indexmap::IndexMap;
+use indexmap::map::Entry;
use serde_json::Value;
-use tracing::instrument;
pub(crate) type ToolTelemetryTags = Vec<(&'static str, String)>;
@@ -334,27 +334,87 @@ impl CoreToolRuntime for ExposureOverride {
}
}
+#[derive(Default)]
pub struct ToolRegistry {
- tools: HashMap<ToolName, Arc<dyn CoreToolRuntime>>,
+ tools: IndexMap<ToolName, Arc<dyn CoreToolRuntime>>,
}
impl ToolRegistry {
- fn new(tools: HashMap<ToolName, Arc<dyn CoreToolRuntime>>) -> Self {
- Self { tools }
+ #[cfg(test)]
+ pub(crate) fn from_tools(tools: impl IntoIterator<Item = Arc<dyn CoreToolRuntime>>) -> Self {
+ let mut registry = Self {
+ tools: IndexMap::new(),
+ };
+
+ for runtime in tools {
+ registry.register_trusted(runtime);
+ }
+
+ registry
}
- #[instrument(level = "trace", skip_all)]
- pub(crate) fn from_tools(tools: impl IntoIterator<Item = Arc<dyn CoreToolRuntime>>) -> Self {
- let mut tools_by_name = HashMap::new();
- for tool in tools {
- let name = tool.tool_name();
- if tools_by_name.contains_key(&name) {
- error_or_panic(format!("tool {name} already registered"));
- continue;
+ pub(crate) fn add<T>(&mut self, handler: T)
+ where
+ T: CoreToolRuntime + 'static,
+ {
+ self.register_trusted(Arc::new(handler));
+ }
+
+ pub(crate) fn add_with_exposure<T>(&mut self, handler: T, exposure: ToolExposure)
+ where
+ T: CoreToolRuntime + 'static,
+ {
+ self.register_trusted(override_tool_exposure(Arc::new(handler), exposure));
+ }
+
+ pub(crate) fn register_trusted(&mut self, runtime: Arc<dyn CoreToolRuntime>) {
+ match self.tools.entry(runtime.tool_name()) {
+ Entry::Vacant(entry) => {
+ entry.insert(runtime);
+ }
+ Entry::Occupied(entry) => {
+ let tool_name = entry.key();
+ error_or_panic(format!("tool {tool_name} already registered"));
}
- tools_by_name.insert(name, tool);
}
- Self::new(tools_by_name)
+ }
+
+ pub(crate) fn prepend_trusted(&mut self, runtime: Arc<dyn CoreToolRuntime>) {
+ let tool_name = runtime.tool_name();
+ if self.tools.contains_key(&tool_name) {
+ error_or_panic(format!("tool {tool_name} already registered"));
+ return;
+ }
+
+ self.tools.shift_insert(0, tool_name, runtime);
+ }
+
+ pub(crate) fn register_external(&mut self, runtime: Arc<dyn CoreToolRuntime>) -> bool {
+ match self.tools.entry(runtime.tool_name()) {
+ Entry::Vacant(entry) => {
+ entry.insert(runtime);
+ true
+ }
+ Entry::Occupied(entry) => {
+ tracing::warn!(
+ tool_name = %entry.key(),
+ "skipping duplicate external tool that is already registered"
+ );
+ false
+ }
+ }
+ }
+
+ pub(crate) fn remove(&mut self, tool_name: &ToolName) -> Option<Arc<dyn CoreToolRuntime>> {
+ self.tools.shift_remove(tool_name)
+ }
+
+ pub(crate) fn runtimes(&self) -> impl Iterator<Item = &Arc<dyn CoreToolRuntime>> {
+ self.tools.values()
+ }
+
+ pub(crate) fn runtimes_mut(&mut self) -> impl Iterator<Item = &mut Arc<dyn CoreToolRuntime>> {
+ self.tools.values_mut()
}
pub(crate) fn deferred_tool_namespaces(&self) -> BTreeMap<String, String> {
@@ -386,7 +446,7 @@ impl ToolRegistry {
#[cfg(test)]
pub(crate) fn empty_for_test() -> Self {
- Self::new(HashMap::new())
+ Self::from_tools(std::iter::empty())
}
#[cfg(test)]
@@ -394,8 +454,7 @@ impl ToolRegistry {
where
T: CoreToolRuntime + 'static,
{
- let name = handler.tool_name();
- Self::new(HashMap::from([(name, handler as Arc<dyn CoreToolRuntime>)]))
+ Self::from_tools([handler as Arc<dyn CoreToolRuntime>])
}
pub(crate) fn tool(&self, name: &ToolName) -> Option<Arc<dyn CoreToolRuntime>> {
diff --git a/codex-rs/core/src/tools/registry_tests.rs b/codex-rs/core/src/tools/registry_tests.rs
index eb60c67541..2e79693314 100644
--- a/codex-rs/core/src/tools/registry_tests.rs
+++ b/codex-rs/core/src/tools/registry_tests.rs
@@ -183,10 +183,8 @@ fn handler_looks_up_namespaced_aliases_explicitly() {
let namespaced_handler = Arc::new(TestHandler {
tool_name: namespaced_name.clone(),
}) as Arc<dyn CoreToolRuntime>;
- let registry = ToolRegistry::new(HashMap::from([
- (plain_name.clone(), Arc::clone(&plain_handler)),
- (namespaced_name.clone(), Arc::clone(&namespaced_handler)),
- ]));
+ let registry =
+ ToolRegistry::from_tools([Arc::clone(&plain_handler), Arc::clone(&namespaced_handler)]);
let plain = registry.tool(&plain_name);
let namespaced = registry.tool(&namespaced_name);
@@ -210,6 +208,32 @@ fn handler_looks_up_namespaced_aliases_explicitly() {
);
}
+#[test]
+fn registry_preserves_external_winners_and_trusted_synthetic_order() {
+ let handler = |tool_name| Arc::new(TestHandler { tool_name }) as Arc<dyn CoreToolRuntime>;
+ let [first_name, second_name, synthetic_name] =
+ ["first", "second", "synthetic"].map(codex_tools::ToolName::plain);
+ let first_handler = handler(first_name.clone());
+
+ let mut registry = ToolRegistry::from_tools([Arc::clone(&first_handler)]);
+ assert!(!registry.register_external(handler(first_name.clone())));
+ assert!(registry.register_external(handler(second_name.clone())));
+ registry.prepend_trusted(handler(synthetic_name.clone()));
+
+ assert_eq!(
+ registry
+ .runtimes()
+ .map(|runtime| runtime.tool_name())
+ .collect::<Vec<_>>(),
+ vec![synthetic_name, first_name.clone(), second_name],
+ );
+ assert!(
+ registry
+ .remove(&first_name)
+ .is_some_and(|handler| Arc::ptr_eq(&handler, &first_handler))
+ );
+}
+
#[tokio::test]
async fn readiness_selects_exact_tool_and_forwards_exposure_overrides() {
let (session, _turn) = crate::session::tests::make_session_and_context().await;
@@ -496,10 +520,7 @@ async fn dispatch_notifies_tool_lifecycle_contributors() -> anyhow::Result<()> {
tool_name: failing_tool.clone(),
result: LifecycleTestResult::Err,
}) as Arc<dyn CoreToolRuntime>;
- let registry = ToolRegistry::new(HashMap::from([
- (ok_tool.clone(), ok_handler),
- (failing_tool.clone(), failing_handler),
- ]));
+ let registry = ToolRegistry::from_tools([ok_handler, failing_handler]);
let session = Arc::new(session);
let turn = Arc::new(turn);
diff --git a/codex-rs/core/src/tools/router.rs b/codex-rs/core/src/tools/router.rs
index 8f63390b86..746a298790 100644
--- a/codex-rs/core/src/tools/router.rs
+++ b/codex-rs/core/src/tools/router.rs
@@ -1,16 +1,19 @@
use crate::function_tool::FunctionCallError;
use crate::session::session::Session;
use crate::session::step_context::StepContext;
+#[cfg(test)]
use crate::session::turn_context::TurnContext;
use crate::tools::context::SharedTurnDiffTracker;
use crate::tools::context::ToolInvocation;
use crate::tools::context::ToolPayload;
+#[cfg(test)]
use crate::tools::handlers::ToolSearchHandlerCache;
use crate::tools::registry::AnyToolResult;
use crate::tools::registry::CoreToolRuntime;
use crate::tools::registry::ToolArgumentDiffConsumer;
use crate::tools::registry::ToolRegistry;
-use crate::tools::spec_plan::build_tool_router;
+#[cfg(test)]
+use crate::tools::spec_plan::finalize_tool_router;
use codex_protocol::models::ResponseItem;
use codex_protocol::models::SearchToolCallParams;
use codex_tools::DiscoverableTool;
@@ -80,15 +83,16 @@ pub(crate) struct ToolSuggestCandidates {
}
impl ToolRouter {
+ #[cfg(test)]
pub(crate) fn from_tools(
turn_context: &TurnContext,
tool_runtimes: Vec<Arc<dyn CoreToolRuntime>>,
hosted_specs: Vec<ToolSpec>,
tool_search_handler_cache: &ToolSearchHandlerCache,
) -> Self {
- build_tool_router(
+ finalize_tool_router(
turn_context,
- tool_runtimes,
+ ToolRegistry::from_tools(tool_runtimes),
hosted_specs,
tool_search_handler_cache,
)
diff --git a/codex-rs/core/src/tools/router_tests.rs b/codex-rs/core/src/tools/router_tests.rs
index 78b79d526b..d40b5de1ff 100644
--- a/codex-rs/core/src/tools/router_tests.rs
+++ b/codex-rs/core/src/tools/router_tests.rs
@@ -129,7 +129,7 @@ fn extension_tool_test_registry() -> Arc<ExtensionRegistry<Config>> {
fn test_tool_router(
step_context: &StepContext,
mcp_tool_runtimes: Vec<Arc<dyn CoreToolRuntime>>,
- extension_tool_executors: Vec<Arc<dyn ToolExecutor<ExtensionToolCall>>>,
+ extension_tool_executors: impl IntoIterator<Item = Arc<dyn ToolExecutor<ExtensionToolCall>>>,
dynamic_tools: &[DynamicToolSpec],
) -> ToolRouter {
let mut tool_runtimes = build_core_tool_runtimes(
diff --git a/codex-rs/core/src/tools/spec_plan.rs b/codex-rs/core/src/tools/spec_plan.rs
index e0c616a6de..928a37bad1 100644
--- a/codex-rs/core/src/tools/spec_plan.rs
+++ b/codex-rs/core/src/tools/spec_plan.rs
@@ -1,6 +1,8 @@
use crate::agent::exceeds_thread_spawn_depth_limit;
use crate::agent::next_thread_spawn_depth;
+use crate::connectors::AppInfo;
use crate::environment_selection::TurnEnvironmentSnapshot;
+use crate::mcp_tool_exposure::build_mcp_tool_runtimes;
use crate::session::session::Session;
use crate::session::turn_context::TurnContext;
use crate::tools::code_mode::default_exec_yield_time_override_ms;
@@ -88,55 +90,13 @@ use codex_tools::shell_command_backend_for_features;
use codex_tools::shell_type_for_model_and_features;
use futures::future::BoxFuture;
use std::collections::BTreeMap;
-use std::collections::HashSet;
use std::sync::Arc;
use tracing::instrument;
-use tracing::warn;
const MULTI_AGENT_V2_NAMESPACE_DESCRIPTION: &str = "Tools for spawning and managing sub-agents.";
const IMAGE_GEN_NAMESPACE: &str = "image_gen";
const IMAGEGEN_TOOL_NAME: &str = "imagegen";
-type PlannedRuntime = Arc<dyn CoreToolRuntime>;
-
-#[derive(Default)]
-struct PlannedTools {
- runtimes: Vec<PlannedRuntime>,
- hosted_specs: Vec<ToolSpec>,
-}
-
-impl PlannedTools {
- fn add<T>(&mut self, handler: T)
- where
- T: CoreToolRuntime + 'static,
- {
- self.runtimes.push(Arc::new(handler));
- }
-
- fn add_arc(&mut self, handler: PlannedRuntime) {
- self.runtimes.push(handler);
- }
-
- fn add_with_exposure<T>(&mut self, handler: T, exposure: ToolExposure)
- where
- T: CoreToolRuntime + 'static,
- {
- self.runtimes
- .push(override_tool_exposure(Arc::new(handler), exposure));
- }
-
- fn add_dispatch_only<T>(&mut self, handler: T)
- where
- T: CoreToolRuntime + 'static,
- {
- self.add_with_exposure(handler, ToolExposure::Hidden);
- }
-
- fn runtimes(&self) -> &[PlannedRuntime] {
- &self.runtimes
- }
-}
-
#[derive(Clone, Copy)]
struct CoreToolPlanContext<'a> {
turn_context: &'a TurnContext,
@@ -148,6 +108,64 @@ struct CoreToolPlanContext<'a> {
wait_agent_timeouts: WaitAgentTimeoutOptions,
}
+#[instrument(level = "trace", skip_all)]
+pub(crate) fn build_tool_router(
+ session: &Session,
+ turn_context: &TurnContext,
+ environments: &TurnEnvironmentSnapshot,
+ mcp: &codex_mcp::McpBinding,
+ connectors: Option<&[AppInfo]>,
+ step_store: &ExtensionData,
+ tool_suggest_candidates: Option<&crate::tools::router::ToolSuggestCandidates>,
+) -> ToolRouter {
+ let default_agent_type_description =
+ crate::agent::role::spawn_tool_spec::build(&std::collections::BTreeMap::new());
+ let wait_for_environment_tool_config = session
+ .services
+ .thread_extension_data
+ .get::<crate::WaitForEnvironmentToolConfig>();
+ let context = CoreToolPlanContext {
+ turn_context,
+ environments,
+ mcp,
+ tool_suggest_candidates,
+ wait_for_environment_tool_config: wait_for_environment_tool_config.as_ref(),
+ default_agent_type_description: &default_agent_type_description,
+ wait_agent_timeouts: wait_agent_timeout_options(turn_context),
+ };
+ let mut registry = ToolRegistry::default();
+ add_core_tool_sources(&context, &mut registry);
+
+ let hosted_specs = if crate::guardian::is_guardian_reviewer_source(&turn_context.session_source)
+ {
+ Vec::new()
+ } else {
+ for runtime in build_mcp_tool_runtimes(
+ mcp.tools(),
+ connectors,
+ &turn_context.config,
+ search_tool_enabled(turn_context),
+ ) {
+ registry.register_external(runtime);
+ }
+ let standalone_web_search_tool = append_extension_tool_executors(
+ turn_context,
+ extension_tool_executors(session, step_store),
+ &mut registry,
+ );
+ append_dynamic_tool_runtimes(&turn_context.dynamic_tools, &mut registry);
+ hosted_model_tool_specs(turn_context, standalone_web_search_tool.as_slice())
+ };
+
+ finalize_tool_router(
+ turn_context,
+ registry,
+ hosted_specs,
+ &session.services.tool_search_handler_cache,
+ )
+}
+
+#[cfg(test)]
#[instrument(level = "trace", skip_all)]
pub(crate) fn build_core_tool_runtimes(
turn_context: &TurnContext,
@@ -167,74 +185,93 @@ pub(crate) fn build_core_tool_runtimes(
default_agent_type_description: &default_agent_type_description,
wait_agent_timeouts: wait_agent_timeout_options(turn_context),
};
- let mut planned_tools = PlannedTools::default();
- add_core_tool_sources(&context, &mut planned_tools);
- planned_tools.runtimes
+ let mut registry = ToolRegistry::default();
+ add_core_tool_sources(&context, &mut registry);
+ registry.runtimes().cloned().collect()
}
+#[cfg(test)]
#[instrument(level = "trace", skip_all)]
pub(crate) fn append_source_tool_runtimes(
turn_context: &TurnContext,
tool_runtimes: &mut Vec<Arc<dyn CoreToolRuntime>>,
mcp_tool_runtimes: Vec<Arc<dyn CoreToolRuntime>>,
- extension_tool_executors: Vec<Arc<dyn ToolExecutor<ExtensionToolCall>>>,
+ extension_tool_executors: impl IntoIterator<Item = Arc<dyn ToolExecutor<ExtensionToolCall>>>,
dynamic_tools: &[DynamicToolSpec],
) -> Vec<ToolSpec> {
if crate::guardian::is_guardian_reviewer_source(&turn_context.session_source) {
return Vec::new();
}
- let hosted_specs = hosted_model_tool_specs(turn_context, &extension_tool_executors);
- tool_runtimes.extend(mcp_tool_runtimes);
- append_extension_tool_executors(turn_context, &extension_tool_executors, tool_runtimes);
- append_dynamic_tool_runtimes(dynamic_tools, tool_runtimes);
- hosted_specs
+ let mut registry = ToolRegistry::from_tools(std::mem::take(tool_runtimes));
+ for runtime in mcp_tool_runtimes {
+ registry.register_external(runtime);
+ }
+ let standalone_web_search_tool =
+ append_extension_tool_executors(turn_context, extension_tool_executors, &mut registry);
+ append_dynamic_tool_runtimes(dynamic_tools, &mut registry);
+ tool_runtimes.extend(registry.runtimes().cloned());
+ hosted_model_tool_specs(turn_context, standalone_web_search_tool.as_slice())
}
#[instrument(level = "trace", skip_all)]
-pub(crate) fn extension_tool_executors(
- session: &Session,
- step_store: &ExtensionData,
-) -> Vec<Arc<dyn ToolExecutor<ExtensionToolCall>>> {
+pub(crate) fn extension_tool_executors<'a>(
+ session: &'a Session,
+ step_store: &'a ExtensionData,
+) -> impl Iterator<Item = Arc<dyn ToolExecutor<ExtensionToolCall>>> + 'a {
session
.services
.extensions
.tool_contributors()
.iter()
- .flat_map(|contributor| {
+ .flat_map(move |contributor| {
contributor.tools_for_step(
&session.services.session_extension_data,
&session.services.thread_extension_data,
step_store,
)
})
- .collect()
}
#[instrument(level = "trace", skip_all)]
-pub(crate) fn build_tool_router(
+pub(crate) fn finalize_tool_router(
turn_context: &TurnContext,
- tool_runtimes: Vec<Arc<dyn CoreToolRuntime>>,
+ mut registry: ToolRegistry,
hosted_specs: Vec<ToolSpec>,
tool_search_handler_cache: &ToolSearchHandlerCache,
) -> ToolRouter {
- let mut planned_tools = PlannedTools {
- runtimes: tool_runtimes,
- hosted_specs,
- };
- apply_direct_model_only_namespace_overrides(turn_context, &mut planned_tools);
- append_tool_search_executor(turn_context, &mut planned_tools, tool_search_handler_cache);
- prepend_code_mode_executors(turn_context, &mut planned_tools);
- let (model_visible_specs, registry) =
- build_model_visible_specs_and_registry(turn_context, planned_tools);
+ apply_direct_model_only_namespace_overrides(turn_context, &mut registry);
+ let code_mode_enabled = matches!(
+ effective_tool_mode(turn_context),
+ ToolMode::CodeMode | ToolMode::CodeModeOnly
+ );
+ if code_mode_enabled {
+ registry.remove(&ToolName::plain(codex_code_mode::PUBLIC_TOOL_NAME));
+ registry.remove(&ToolName::plain(codex_code_mode::WAIT_TOOL_NAME));
+ }
+ let tool_search_name = ToolName::plain(TOOL_SEARCH_TOOL_NAME);
+ if search_tool_enabled(turn_context)
+ && registry.runtimes().any(|runtime| {
+ runtime.tool_name() != tool_search_name
+ && runtime.exposure() == ToolExposure::Deferred
+ && runtime.search_info().is_some()
+ })
+ {
+ registry.remove(&tool_search_name);
+ append_tool_search_executor(turn_context, &mut registry, tool_search_handler_cache);
+ }
+
+ register_code_mode_executors(turn_context, &mut registry);
+
+ let model_visible_specs = build_model_visible_specs(turn_context, &registry, hosted_specs);
ToolRouter::from_parts(registry, model_visible_specs)
}
fn apply_direct_model_only_namespace_overrides(
turn_context: &TurnContext,
- planned_tools: &mut PlannedTools,
+ registry: &mut ToolRegistry,
) {
- for runtime in &mut planned_tools.runtimes {
+ for runtime in registry.runtimes_mut() {
let configured = runtime
.tool_name()
.namespace
@@ -253,21 +290,14 @@ fn apply_direct_model_only_namespace_overrides(
}
#[instrument(level = "trace", skip_all)]
-fn build_model_visible_specs_and_registry(
+fn build_model_visible_specs(
turn_context: &TurnContext,
- planned_tools: PlannedTools,
-) -> (Vec<ToolSpec>, ToolRegistry) {
- let PlannedTools {
- runtimes,
- hosted_specs,
- } = planned_tools;
+ registry: &ToolRegistry,
+ hosted_specs: Vec<ToolSpec>,
+) -> Vec<ToolSpec> {
let mut specs = Vec::new();
- let mut seen_tool_names = HashSet::new();
- for runtime in &runtimes {
+ for runtime in registry.runtimes() {
let tool_name = runtime.tool_name();
- if !seen_tool_names.insert(tool_name.clone()) {
- continue;
- }
let exposure = runtime.exposure();
if exposure.is_direct() && !is_hidden_by_code_mode_only(turn_context, &tool_name, exposure)
{
@@ -282,15 +312,12 @@ fn build_model_visible_specs_and_registry(
}
specs.extend(hosted_specs);
- let registry = ToolRegistry::from_tools(runtimes);
- let model_visible_specs = merge_into_namespaces(specs)
+ merge_into_namespaces(specs)
.into_iter()
.filter(|spec| {
namespace_tools_enabled(turn_context) || !matches!(spec, ToolSpec::Namespace(_))
})
- .collect();
-
- (model_visible_specs, registry)
+ .collect()
}
fn spec_for_model_request(
@@ -314,7 +341,7 @@ fn spec_for_model_request(
#[instrument(level = "trace", skip_all)]
fn hosted_model_tool_specs(
turn_context: &TurnContext,
- extension_tool_executors: &[Arc<dyn ToolExecutor<ExtensionToolCall>>],
+ registered_extension_tool_names: &[ToolName],
) -> Vec<ToolSpec> {
// Responses Lite accepts schemas for client-executed tools, not hosted Responses tools.
if turn_context.model_info.use_responses_lite
@@ -325,9 +352,7 @@ fn hosted_model_tool_specs(
let mut specs = Vec::new();
let standalone_web_search_available = standalone_web_search_enabled(turn_context)
- && extension_tool_executors
- .iter()
- .any(|executor| executor.tool_name() == ToolName::namespaced("web", "run"));
+ && registered_extension_tool_names.contains(&ToolName::namespaced("web", "run"));
// `Some(Cached/Live/Disabled)` are the options for mode when standalone search is unavailable
// and the provider supports hosted search. `None` prevents emitting a hosted search tool.
let web_search_mode = (!standalone_web_search_available
@@ -470,20 +495,17 @@ fn is_excluded_from_code_mode(turn_context: &TurnContext, tool_name: &ToolName)
})
}
-fn build_code_mode_executors(
- turn_context: &TurnContext,
- executors: &[Arc<dyn CoreToolRuntime>],
-) -> Vec<Arc<dyn CoreToolRuntime>> {
+fn register_code_mode_executors(turn_context: &TurnContext, registry: &mut ToolRegistry) {
let tool_mode = effective_tool_mode(turn_context);
if !matches!(tool_mode, ToolMode::CodeMode | ToolMode::CodeModeOnly) {
- return vec![];
+ return;
}
let mut code_mode_nested_tool_specs = Vec::new();
let mut exec_prompt_tool_specs = Vec::new();
let mut deferred_exec_prompt_tool_specs = Vec::new();
let deferred_tools_guidance_enabled = search_tool_enabled(turn_context);
- for executor in executors {
+ for executor in registry.runtimes() {
let exposure = executor.exposure();
if !exposure.is_available_in_code_mode() {
continue;
@@ -532,19 +554,19 @@ fn build_code_mode_executors(
default_exec_yield_time_override_ms(&turn_context.config.features)
.unwrap_or(codex_code_mode::DEFAULT_EXEC_YIELD_TIME_MS);
- vec![
- Arc::new(CodeModeExecuteHandler::new(
- create_code_mode_tool(
- &enabled_tools,
- &deferred_tools,
- &namespace_descriptions,
- default_exec_yield_time_ms,
- tool_mode == ToolMode::CodeModeOnly,
- ),
- code_mode_nested_tool_specs,
- )),
- Arc::new(CodeModeWaitHandler),
- ]
+ let execute_handler = CodeModeExecuteHandler::new(
+ create_code_mode_tool(
+ &enabled_tools,
+ &deferred_tools,
+ &namespace_descriptions,
+ default_exec_yield_time_ms,
+ tool_mode == ToolMode::CodeModeOnly,
+ ),
+ code_mode_nested_tool_specs,
+ );
+
+ registry.prepend_trusted(Arc::new(CodeModeWaitHandler));
+ registry.prepend_trusted(Arc::new(execute_handler));
}
#[instrument(level = "trace", skip_all, fields(tool_spec_count = specs.len()))]
@@ -617,7 +639,7 @@ fn code_mode_namespace_descriptions(
}
#[instrument(level = "trace", skip_all)]
-fn add_core_tool_sources(context: &CoreToolPlanContext<'_>, planned_tools: &mut PlannedTools) {
+fn add_core_tool_sources(context: &CoreToolPlanContext<'_>, registry: &mut ToolRegistry) {
// Guardian reviewers receive only `exec_command`, `write_stdin`, and `view_image`
// when an environment is available; all general tool sources stay excluded.
if crate::guardian::is_guardian_reviewer_source(&context.turn_context.session_source) {
@@ -625,7 +647,7 @@ fn add_core_tool_sources(context: &CoreToolPlanContext<'_>, planned_tools: &mut
let environment_mode = tool_environment_mode(context.environments);
if environment_mode.has_environment() {
let include_environment_id = matches!(environment_mode, ToolEnvironmentMode::Multiple);
- planned_tools.add(ExecCommandHandler::new(ExecCommandHandlerOptions {
+ registry.add(ExecCommandHandler::new(ExecCommandHandlerOptions {
allow_login_shell: turn_context.config.permissions.allow_login_shell,
exec_permission_approvals_enabled: false,
include_environment_id,
@@ -634,8 +656,8 @@ fn add_core_tool_sources(context: &CoreToolPlanContext<'_>, planned_tools: &mut
context.environments,
),
}));
- planned_tools.add(WriteStdinHandler);
- planned_tools.add(ViewImageHandler::new(ViewImageToolOptions {
+ registry.add(WriteStdinHandler);
+ registry.add(ViewImageHandler::new(ViewImageToolOptions {
can_request_original_image_detail: can_request_original_image_detail(
&turn_context.model_info,
),
@@ -645,10 +667,10 @@ fn add_core_tool_sources(context: &CoreToolPlanContext<'_>, planned_tools: &mut
return;
}
- add_shell_tools(context, planned_tools);
- add_mcp_resource_tools(context, planned_tools);
- add_core_utility_tools(context, planned_tools);
- add_collaboration_tools(context, planned_tools);
+ add_shell_tools(context, registry);
+ add_mcp_resource_tools(context, registry);
+ add_core_utility_tools(context, registry);
+ add_collaboration_tools(context, registry);
}
fn standalone_web_search_enabled(turn_context: &TurnContext) -> bool {
@@ -667,7 +689,7 @@ fn tool_environment_mode(environments: &TurnEnvironmentSnapshot) -> ToolEnvironm
}
#[instrument(level = "trace", skip_all)]
-fn add_shell_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut PlannedTools) {
+fn add_shell_tools(context: &CoreToolPlanContext<'_>, registry: &mut ToolRegistry) {
let turn_context = context.turn_context;
let features = turn_context.config.features.get();
let environment_mode = tool_environment_mode(context.environments);
@@ -686,7 +708,7 @@ fn add_shell_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut Planne
match shell_type_for_model_and_features(&turn_context.model_info, features) {
ConfigShellToolType::UnifiedExec => {
- planned_tools.add(ExecCommandHandler::new(ExecCommandHandlerOptions {
+ registry.add(ExecCommandHandler::new(ExecCommandHandlerOptions {
allow_login_shell,
exec_permission_approvals_enabled,
include_environment_id,
@@ -695,17 +717,20 @@ fn add_shell_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut Planne
context.environments,
),
}));
- planned_tools.add(WriteStdinHandler);
+ registry.add(WriteStdinHandler);
// Keep the legacy shell tool registered while unified exec is
// model-visible.
- planned_tools.add_dispatch_only(ShellCommandHandler::new(shell_command_options));
+ registry.add_with_exposure(
+ ShellCommandHandler::new(shell_command_options),
+ ToolExposure::Hidden,
+ );
}
ConfigShellToolType::Disabled => {}
ConfigShellToolType::Default
| ConfigShellToolType::Local
| ConfigShellToolType::ShellCommand => {
- planned_tools.add(ShellCommandHandler::new(shell_command_options));
+ registry.add(ShellCommandHandler::new(shell_command_options));
}
}
}
@@ -723,26 +748,26 @@ fn unified_exec_should_include_shell_parameter(
}
#[instrument(level = "trace", skip_all)]
-fn add_mcp_resource_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut PlannedTools) {
+fn add_mcp_resource_tools(context: &CoreToolPlanContext<'_>, registry: &mut ToolRegistry) {
if context.mcp.has_servers() {
- planned_tools.add(ListMcpResourcesHandler);
- planned_tools.add(ListMcpResourceTemplatesHandler);
- planned_tools.add(ReadMcpResourceHandler);
+ registry.add(ListMcpResourcesHandler);
+ registry.add(ListMcpResourceTemplatesHandler);
+ registry.add(ReadMcpResourceHandler);
}
}
#[instrument(level = "trace", skip_all)]
-fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut PlannedTools) {
+fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, registry: &mut ToolRegistry) {
let turn_context = context.turn_context;
let features = turn_context.config.features.get();
let environment_mode = tool_environment_mode(context.environments);
if turn_context.config.update_plan_enabled {
- planned_tools.add(PlanHandler);
+ registry.add(PlanHandler);
}
if features.enabled(Feature::DeferredExecutor) {
- planned_tools.add(
+ registry.add(
context
.wait_for_environment_tool_config
.map(Arc::as_ref)
@@ -754,7 +779,7 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut
}
if turn_context.config.experimental_request_user_input_enabled {
- planned_tools.add_with_exposure(
+ registry.add_with_exposure(
RequestUserInputHandler {
available_modes: request_user_input_available_modes(features),
},
@@ -763,23 +788,23 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut
}
if environment_mode.has_environment() && features.enabled(Feature::RequestPermissionsTool) {
- planned_tools.add(RequestPermissionsHandler);
+ registry.add(RequestPermissionsHandler);
}
if features.enabled(Feature::TokenBudget) {
- planned_tools.add_with_exposure(NewContextWindowHandler, ToolExposure::DirectModelOnly);
- planned_tools.add(GetContextRemainingHandler);
+ registry.add_with_exposure(NewContextWindowHandler, ToolExposure::DirectModelOnly);
+ registry.add(GetContextRemainingHandler);
}
if features.enabled(Feature::CurrentTimeReminder) {
- planned_tools.add(CurrentTimeHandler);
+ registry.add(CurrentTimeHandler);
if turn_context
.config
.current_time_reminder
.as_ref()
.is_some_and(|config| config.sleep_tool)
{
- planned_tools.add(SleepHandler);
+ registry.add(SleepHandler);
}
}
@@ -789,11 +814,11 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut
.filter(|candidates| !candidates.tools.is_empty())
{
if candidates.presentation == crate::tools::router::ToolSuggestPresentation::ListTool {
- planned_tools.add(ListAvailablePluginsToInstallHandler::new(
+ registry.add(ListAvailablePluginsToInstallHandler::new(
collect_request_plugin_install_entries(&candidates.tools),
));
}
- planned_tools.add(RequestPluginInstallHandler::new(
+ registry.add(RequestPluginInstallHandler::new(
candidates.tools.clone(),
candidates.presentation,
));
@@ -802,7 +827,7 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut
if environment_mode.has_environment() && turn_context.model_info.apply_patch_tool_type.is_some()
{
let include_environment_id = matches!(environment_mode, ToolEnvironmentMode::Multiple);
- planned_tools.add(ApplyPatchHandler::new(include_environment_id));
+ registry.add(ApplyPatchHandler::new(include_environment_id));
}
if turn_context
@@ -811,12 +836,12 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut
.iter()
.any(|tool| tool == "test_sync_tool")
{
- planned_tools.add(TestSyncHandler);
+ registry.add(TestSyncHandler);
}
if environment_mode.has_environment() {
let include_environment_id = matches!(environment_mode, ToolEnvironmentMode::Multiple);
- planned_tools.add(ViewImageHandler::new(ViewImageToolOptions {
+ registry.add(ViewImageHandler::new(ViewImageToolOptions {
can_request_original_image_detail: can_request_original_image_detail(
&turn_context.model_info,
),
@@ -826,7 +851,7 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut
}
#[instrument(level = "trace", skip_all)]
-fn add_collaboration_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mut PlannedTools) {
+fn add_collaboration_tools(context: &CoreToolPlanContext<'_>, registry: &mut ToolRegistry) {
let turn_context = context.turn_context;
if collab_tools_enabled(turn_context) {
if multi_agent_v2_enabled(turn_context) {
@@ -842,7 +867,7 @@ fn add_collaboration_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mu
agent_type_description(turn_context, context.default_agent_type_description);
let hide_spawn_agent_metadata =
turn_context.config.multi_agent_v2.hide_spawn_agent_metadata;
- planned_tools.add_arc(override_tool_exposure(
+ registry.register_trusted(override_tool_exposure(
multi_agent_v2_handler(
SpawnAgentHandlerV2::new(SpawnAgentToolOptions {
available_models: turn_context.available_models.clone(),
@@ -860,16 +885,16 @@ fn add_collaboration_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mu
),
exposure,
));
- planned_tools.add_arc(override_tool_exposure(
+ registry.register_trusted(override_tool_exposure(
multi_agent_v2_handler(SendMessageHandlerV2, tool_namespace),
exposure,
));
- planned_tools.add_arc(override_tool_exposure(
+ registry.register_trusted(override_tool_exposure(
multi_agent_v2_handler(FollowupTaskHandlerV2, tool_namespace),
exposure,
));
if turn_context.config.multi_agent_v2.wait_agent_enabled {
- planned_tools.add_arc(override_tool_exposure(
+ registry.register_trusted(override_tool_exposure(
multi_agent_v2_handler(
WaitAgentHandlerV2::new(context.wait_agent_timeouts),
tool_namespace,
@@ -877,11 +902,11 @@ fn add_collaboration_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mu
exposure,
));
}
- planned_tools.add_arc(override_tool_exposure(
+ registry.register_trusted(override_tool_exposure(
multi_agent_v2_handler(InterruptAgentHandler, tool_namespace),
exposure,
));
- planned_tools.add_arc(override_tool_exposure(
+ registry.register_trusted(override_tool_exposure(
multi_agent_v2_handler(ListAgentsHandlerV2, tool_namespace),
exposure,
));
@@ -893,7 +918,7 @@ fn add_collaboration_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mu
} else {
ToolExposure::Direct
};
- planned_tools.add_with_exposure(
+ registry.add_with_exposure(
SpawnAgentHandler::new(SpawnAgentToolOptions {
available_models: turn_context.available_models.clone(),
agent_type_description,
@@ -905,20 +930,17 @@ fn add_collaboration_tools(context: &CoreToolPlanContext<'_>, planned_tools: &mu
}),
exposure,
);
- planned_tools.add_with_exposure(SendInputHandler, exposure);
- planned_tools.add_with_exposure(ResumeAgentHandler, exposure);
- planned_tools
+ registry.add_with_exposure(SendInputHandler, exposure);
+ registry.add_with_exposure(ResumeAgentHandler, exposure);
+ registry
.add_with_exposure(WaitAgentHandler::new(context.wait_agent_timeouts), exposure);
- planned_tools.add_with_exposure(CloseAgentHandler, exposure);
+ registry.add_with_exposure(CloseAgentHandler, exposure);
}
}
}
#[instrument(level = "trace", skip_all, fields(dynamic_tool_count = dynamic_tools.len()))]
-fn append_dynamic_tool_runtimes(
- dynamic_tools: &[DynamicToolSpec],
- tool_runtimes: &mut Vec<Arc<dyn CoreToolRuntime>>,
-) {
+fn append_dynamic_tool_runtimes(dynamic_tools: &[DynamicToolSpec], registry: &mut ToolRegistry) {
for spec in dynamic_tools {
match spec {
DynamicToolSpec::Function(tool) => {
@@ -929,7 +951,7 @@ fn append_dynamic_tool_runtimes(
);
continue;
};
- tool_runtimes.push(Arc::new(handler));
+ registry.register_external(Arc::new(handler));
}
DynamicToolSpec::Namespace(namespace) => {
for tool in &namespace.tools {
@@ -943,7 +965,7 @@ fn append_dynamic_tool_runtimes(
);
continue;
};
- tool_runtimes.push(Arc::new(handler));
+ registry.register_external(Arc::new(handler));
}
}
}
@@ -953,23 +975,14 @@ fn append_dynamic_tool_runtimes(
#[instrument(level = "trace", skip_all)]
fn append_tool_search_executor(
turn_context: &TurnContext,
- planned_tools: &mut PlannedTools,
+ registry: &mut ToolRegistry,
tool_search_handler_cache: &ToolSearchHandlerCache,
) {
- if !search_tool_enabled(turn_context) {
- return;
- }
-
- let search_infos = planned_tools
+ let search_infos = registry
.runtimes()
- .iter()
.filter(|executor| executor.exposure() == ToolExposure::Deferred)
.filter_map(|executor| executor.search_info())
.collect::<Vec<_>>();
- if search_infos.is_empty() {
- return;
- }
-
let source_listing = if turn_context
.config
.features
@@ -979,50 +992,22 @@ fn append_tool_search_executor(
} else {
ToolSearchSourceListing::Include
};
- let handler: PlannedRuntime =
- tool_search_handler_cache.get_or_build(search_infos, source_listing);
- planned_tools.add_arc(handler);
-}
-
-fn prepend_code_mode_executors(turn_context: &TurnContext, planned_tools: &mut PlannedTools) {
- let code_mode_executors = build_code_mode_executors(turn_context, planned_tools.runtimes());
- planned_tools.runtimes.splice(0..0, code_mode_executors);
+ registry.register_trusted(tool_search_handler_cache.get_or_build(search_infos, source_listing));
}
fn append_extension_tool_executors(
turn_context: &TurnContext,
- executors: &[Arc<dyn ToolExecutor<ExtensionToolCall>>],
- tool_runtimes: &mut Vec<Arc<dyn CoreToolRuntime>>,
-) {
- if executors.is_empty() {
- return;
- }
-
- let mut reserved_tool_names = tool_runtimes
- .iter()
- .map(|executor| executor.tool_name())
- .collect::<HashSet<_>>();
- let tool_mode = effective_tool_mode(turn_context);
- if matches!(tool_mode, ToolMode::CodeMode | ToolMode::CodeModeOnly) {
- reserved_tool_names.insert(ToolName::plain(codex_code_mode::PUBLIC_TOOL_NAME));
- reserved_tool_names.insert(ToolName::plain(codex_code_mode::WAIT_TOOL_NAME));
- }
- if search_tool_enabled(turn_context)
- && tool_runtimes
- .iter()
- .any(|executor| executor.exposure() == ToolExposure::Deferred)
- {
- reserved_tool_names.insert(ToolName::plain(TOOL_SEARCH_TOOL_NAME));
- }
-
+ executors: impl IntoIterator<Item = Arc<dyn ToolExecutor<ExtensionToolCall>>>,
+ registry: &mut ToolRegistry,
+) -> Option<ToolName> {
let standalone_web_search_enabled = standalone_web_search_enabled(turn_context);
let web_search_mode_on = turn_context.config.web_search_mode.value() != WebSearchMode::Disabled;
+ let mut standalone_web_search_tool = None;
- for executor in executors.iter().cloned() {
+ for executor in executors {
let tool_name = executor.tool_name();
- if tool_name == ToolName::namespaced("web", "run")
- && (!standalone_web_search_enabled || !web_search_mode_on)
- {
+ let is_standalone_web_search = tool_name == ToolName::namespaced("web", "run");
+ if is_standalone_web_search && (!standalone_web_search_enabled || !web_search_mode_on) {
continue;
}
if tool_name == ToolName::namespaced(IMAGE_GEN_NAMESPACE, IMAGEGEN_TOOL_NAME)
@@ -1030,12 +1015,13 @@ fn append_extension_tool_executors(
{
continue;
}
- if !reserved_tool_names.insert(tool_name.clone()) {
- warn!("Skipping extension tool `{tool_name}`: tool already registered");
- continue;
+ let runtime = Arc::new(ExtensionToolAdapter::new(executor));
+ if registry.register_external(runtime) && is_standalone_web_search {
+ standalone_web_search_tool = Some(tool_name);
}
- tool_runtimes.push(Arc::new(ExtensionToolAdapter::new(executor)));
}
+
+ standalone_web_search_tool
}
fn multi_agent_v2_handler(
diff --git a/codex-rs/core/src/tools/spec_plan_tests.rs b/codex-rs/core/src/tools/spec_plan_tests.rs
index e1b3ab1ca9..cf958e5f56 100644
--- a/codex-rs/core/src/tools/spec_plan_tests.rs
+++ b/codex-rs/core/src/tools/spec_plan_tests.rs
@@ -1880,6 +1880,36 @@ async fn code_mode_only_can_expose_namespaced_multi_agent_v2_as_normal_tools() {
}
}
+#[tokio::test]
+async fn hosted_web_search_fallback_follows_winning_browser_runtime() {
+ let plan = probe_with(
+ |turn| {
+ set_feature(turn, Feature::StandaloneWebSearch, /*enabled*/ true);
+ set_web_search_mode(turn, WebSearchMode::Live);
+ },
+ ToolPlanInputs {
+ tool_runtimes: vec![mcp_runtime(
+ "browser_collision",
+ "web",
+ "run",
+ ToolExposure::Direct,
+ )],
+ extension_tool_executors: vec![Arc::new(TestNamespaceExtensionTool {
+ namespace: "web",
+ tool_name: "run",
+ })],
+ ..ToolPlanInputs::default()
+ },
+ )
+ .await;
+
+ let ToolSpec::Namespace(namespace) = plan.visible_spec("web") else {
+ panic!("expected the winning browser namespace");
+ };
+ assert_eq!(namespace.description, "Tools from browser_collision.");
+ plan.assert_visible_contains(&["web_search"]);
+}
+
#[tokio::test]
async fn hosted_web_search_and_standalone_image_generation_follow_runtime_gates() {
let image_generation_tool = Arc::new(TestNamespaceExtensionTool {
diff --git a/codex-rs/core/tests/suite/search_tool.rs b/codex-rs/core/tests/suite/search_tool.rs
index 69775b72ec..6a2e83f4db 100644
--- a/codex-rs/core/tests/suite/search_tool.rs
+++ b/codex-rs/core/tests/suite/search_tool.rs
@@ -987,13 +987,23 @@ async fn tool_search_returns_deferred_dynamic_tool_and_routes_follow_up_call() -
},
)],
});
+ let shadow_tool = DynamicToolSpec::Function(DynamicToolFunctionSpec {
+ name: TOOL_SEARCH_TOOL_NAME.to_string(),
+ description: "Client-provided tool that must not replace tool search.".to_string(),
+ input_schema: json!({
+ "type": "object",
+ "properties": {},
+ "additionalProperties": false,
+ }),
+ defer_loading: false,
+ });
let mut builder = test_codex().with_config(configure_search_capable_model);
- let base_test = builder.build(&server).await?;
+ let base_test = builder.build_with_auto_env(&server).await?;
let new_thread = base_test
.thread_manager
.start_thread(StartThreadOptions {
- dynamic_tools: vec![dynamic_tool],
+ dynamic_tools: vec![dynamic_tool, shadow_tool],
..StartThreadOptions::new(base_test.config.clone())
})
.await?;
@@ -1048,11 +1058,23 @@ async fn tool_search_returns_deferred_dynamic_tool_and_routes_follow_up_call() -
let first_request_body = requests[0].body_json();
let first_request_tools = tool_names(&first_request_body);
- assert!(
- first_request_tools
- .iter()
- .any(|name| name == TOOL_SEARCH_TOOL_NAME),
- "first request should advertise tool_search: {first_request_tools:?}"
+ let advertised_search_tool_types = first_request_body
+ .get("tools")
+ .and_then(Value::as_array)
+ .expect("first request should contain model tools")
+ .iter()
+ .filter(|tool| {
+ tool.get("name")
+ .or_else(|| tool.get("type"))
+ .and_then(Value::as_str)
+ == Some(TOOL_SEARCH_TOOL_NAME)
+ })
+ .map(|tool| tool.get("type").and_then(Value::as_str))
+ .collect::<Vec<_>>();
+ assert_eq!(
+ advertised_search_tool_types,
+ vec![Some(TOOL_SEARCH_TOOL_NAME)],
+ "first request should advertise exactly one host tool_search: {first_request_tools:?}"
);
assert!(
!first_request_tools.iter().any(|name| name == tool_name),