Lightweight coding agent that runs in your terminal
Rust
Reuse MCP handlers across sampling steps (#37273)
jife1831db7c31e
diff --git a/codex-rs/core/src/mcp_tool_exposure.rs b/codex-rs/core/src/mcp_tool_exposure.rsindex 84d14ebcd3..43b490ecc2 100644--- a/codex-rs/core/src/mcp_tool_exposure.rs+++ b/codex-rs/core/src/mcp_tool_exposure.rs@@ -1,9 +1,14 @@+use std::collections::HashMap;use std::collections::HashSet;+use std::collections::hash_map::Entry;use std::sync::Arc;+use std::sync::Mutex;+use std::sync::Weak;use codex_connectors::AppToolPolicyEvaluator;use codex_connectors::AppToolPolicyInput;use codex_mcp::CODEX_APPS_MCP_SERVER_NAME;+use codex_mcp::McpBinding;use codex_mcp::ToolInfo as McpToolInfo;use codex_mcp::tool_is_model_visible;use codex_tools::ToolExposure;@@ -18,13 +23,62 @@ use crate::config::Config;use crate::tools::handlers::McpHandler;use crate::tools::registry::ToolRegistry;+#[derive(Default)]+pub(crate) struct McpHandlerCache {+ cached: Mutex<Option<CachedMcpHandlers>>,+}++struct CachedMcpHandlers {+ binding: Weak<McpBinding>,+ handlers: HashMap<ToolName, Arc<McpHandler>>,+}++impl McpHandlerCache {+ pub(crate) fn append_mcp_tools(+ &self,+ binding: &Arc<McpBinding>,+ config: &Config,+ apps_enabled: bool,+ mcp_server_catalog: &codex_mcp::ResolvedMcpCatalog,+ search_tool_enabled: bool,+ registry: &mut ToolRegistry,+ ) -> HashSet<ToolName> {+ let mut cached = self+ .cached+ .lock()+ .unwrap_or_else(std::sync::PoisonError::into_inner);+ if !cached+ .as_ref()+ .and_then(|cached| cached.binding.upgrade())+ .is_some_and(|cached_binding| Arc::ptr_eq(&cached_binding, binding))+ {+ *cached = None;+ }++ let cached = cached.get_or_insert_with(|| CachedMcpHandlers {+ binding: Arc::downgrade(binding),+ handlers: HashMap::new(),+ });+ append_mcp_tools(+ binding.tools(),+ config,+ apps_enabled,+ mcp_server_catalog,+ search_tool_enabled,+ &mut cached.handlers,+ registry,+ )+ }+}+#[instrument(level = "trace", skip_all)]-pub(crate) fn append_mcp_tools(+fn append_mcp_tools(all_mcp_tools: &[McpToolInfo],config: &Config,apps_enabled: bool,mcp_server_catalog: &codex_mcp::ResolvedMcpCatalog,search_tool_enabled: bool,+ handlers: &mut HashMap<ToolName, Arc<McpHandler>>,registry: &mut ToolRegistry,) -> HashSet<ToolName> {// Keep regular MCP tools first; Apps tools also require connector and policy checks.@@ -45,43 +99,48 @@ pub(crate) fn append_mcp_tools(let agent_plugin = mcp_server_catalog.server(&tool.server_name).is_some_and(|server| server.source().is_agent_plugin());- let handler = if agent_plugin {- McpHandler::new_agent_plugin(tool.clone())- } else {- McpHandler::new(tool.clone())- };- match handler {- Ok(handler) => {- let fits_agent_budget = if agent_plugin {- handler.model_spec_bytes().is_ok_and(|bytes| {- if bytes > MAX_AGENT_PLUGIN_MCP_SPEC_BYTES {- return false;- }- let next = agent_plugin_bytes.saturating_add(bytes);- if next <= MAX_AGENT_PLUGIN_MCP_TOTAL_BYTES {- agent_plugin_bytes = next;- true- } else {- false- }- })- } else {- true- };- let tool_exposure = if fits_agent_budget {- exposure+ let handler = match handlers.entry(tool_name.clone()) {+ Entry::Occupied(entry) => Arc::clone(entry.get()),+ Entry::Vacant(entry) => {+ let handler = if agent_plugin {+ McpHandler::new_agent_plugin(tool.clone())} else {- ToolExposure::Hidden+ McpHandler::new(tool.clone())};- if registry.register_external_with_exposure(Arc::new(handler), tool_exposure)- && fits_agent_budget- {- registered_tools.insert(tool_name);++ match handler {+ Ok(handler) => Arc::clone(entry.insert(Arc::new(handler))),+ Err(err) => {+ warn!("Skipping MCP tool `{tool_name}`: failed to build tool spec: {err}");+ continue;+ }}}- Err(err) => {- warn!("Skipping MCP tool `{tool_name}`: failed to build tool spec: {err}");- }+ };++ let fits_agent_budget = if agent_plugin {+ handler.model_spec_bytes().is_ok_and(|bytes| {+ if bytes > MAX_AGENT_PLUGIN_MCP_SPEC_BYTES {+ return false;+ }+ let next = agent_plugin_bytes.saturating_add(bytes);+ if next <= MAX_AGENT_PLUGIN_MCP_TOTAL_BYTES {+ agent_plugin_bytes = next;+ true+ } else {+ false+ }+ })+ } else {+ true+ };+ let tool_exposure = if fits_agent_budget {+ exposure+ } else {+ ToolExposure::Hidden+ };+ if registry.register_external_with_exposure(handler, tool_exposure) && fits_agent_budget {+ registered_tools.insert(tool_name);}}registered_toolsdiff --git a/codex-rs/core/src/mcp_tool_exposure_test.rs b/codex-rs/core/src/mcp_tool_exposure_test.rsindex 9f709f8dcb..c94be8ce55 100644--- a/codex-rs/core/src/mcp_tool_exposure_test.rs+++ b/codex-rs/core/src/mcp_tool_exposure_test.rs@@ -95,6 +95,7 @@ fn runtimes_by_name_with_catalog(mcp_server_catalog: &ResolvedMcpCatalog,search_tool_enabled: bool,) -> HashMap<ToolName, ToolExposure> {+ let mut handlers = HashMap::new();let mut registry = ToolRegistry::default();append_mcp_tools(tools,@@ -102,6 +103,7 @@ fn runtimes_by_name_with_catalog(apps_enabled,mcp_server_catalog,search_tool_enabled,+ &mut handlers,&mut registry,);registry@@ -220,6 +222,89 @@ async fn directly_exposes_effective_tool_sets_when_search_is_unavailable() {);}+#[tokio::test]+async fn cached_app_handlers_still_obey_current_apps_enablement_and_tool_policy() {+ let config = test_config().await;+ let codex_home = tempdir().expect("create restrictive config directory");+ std::fs::write(+ codex_home.path().join(CONFIG_TOML_FILE),+ "[apps.calendar]\ndefault_tools_enabled = false\n",+ )+ .expect("write restrictive app policy");+ let restricted_config = ConfigBuilder::without_managed_config_for_tests()+ .codex_home(codex_home.path().to_path_buf())+ .build()+ .await+ .expect("build restrictive app policy");+ let tools = [make_mcp_tool(+ CODEX_APPS_MCP_SERVER_NAME,+ "events/create",+ "mcp__codex_apps__calendar",+ "create",+ Some("calendar"),+ Some("Calendar"),+ )];+ let mut handlers = HashMap::new();+ let catalog = ResolvedMcpCatalog::default();+ let mut allowed_registry = ToolRegistry::default();+ let allowed = append_mcp_tools(+ &tools,+ &config,+ /*apps_enabled*/ true,+ &catalog,+ /*search_tool_enabled*/ false,+ &mut handlers,+ &mut allowed_registry,+ );+ let cached_handler = &allowed_registry+ .entries()+ .next()+ .expect("allowed app tool should be registered")+ .runtime;++ let mut disabled_registry = ToolRegistry::default();+ let disabled = append_mcp_tools(+ &tools,+ &config,+ /*apps_enabled*/ false,+ &catalog,+ /*search_tool_enabled*/ false,+ &mut handlers,+ &mut disabled_registry,+ );+ let mut restricted_registry = ToolRegistry::default();+ let restricted = append_mcp_tools(+ &tools,+ &restricted_config,+ /*apps_enabled*/ true,+ &catalog,+ /*search_tool_enabled*/ false,+ &mut handlers,+ &mut restricted_registry,+ );+ let mut restored_registry = ToolRegistry::default();+ let restored = append_mcp_tools(+ &tools,+ &config,+ /*apps_enabled*/ true,+ &catalog,+ /*search_tool_enabled*/ true,+ &mut handlers,+ &mut restored_registry,+ );+ let restored_handler = restored_registry+ .entries()+ .next()+ .expect("restored app tool should be registered");++ assert_eq!(allowed, HashSet::from([tools[0].canonical_tool_name()]));+ assert!(disabled.is_empty());+ assert!(restricted.is_empty());+ assert_eq!(restored, allowed);+ assert!(Arc::ptr_eq(cached_handler, &restored_handler.runtime));+ assert_eq!(restored_handler.exposure, ToolExposure::Deferred);+}+#[tokio::test]async fn excludes_tools_hidden_from_model_exposure() {let config = test_config().await;@@ -339,6 +424,7 @@ async fn app_tool_registration_uses_trusted_catalog_metadata_and_preserves_sourcsynthetic_app_tool.clone(),regular_tool.clone(),];+ let mut handlers = HashMap::new();let mut registry = ToolRegistry::default();append_mcp_tools(@@ -347,6 +433,7 @@ async fn app_tool_registration_uses_trusted_catalog_metadata_and_preserves_sourc/*apps_enabled*/ true,&ResolvedMcpCatalog::default(),/*search_tool_enabled*/ false,+ &mut handlers,&mut registry,);diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rsindex f69ff50476..4db2ba4dac 100644--- a/codex-rs/core/src/session/mod.rs+++ b/codex-rs/core/src/session/mod.rs@@ -3143,7 +3143,7 @@ impl Session {self.as_ref(),turn_context.as_ref(),&environments,- mcp.as_ref(),+ &mcp,&extension_data,prepared_recommendations,)diff --git a/codex-rs/core/src/session/session.rs b/codex-rs/core/src/session/session.rsindex 522055b7b2..ed99e8d01f 100644--- a/codex-rs/core/src/session/session.rs+++ b/codex-rs/core/src/session/session.rs@@ -1115,6 +1115,7 @@ impl Session {// Start with an empty connection set. The initialized set is// published after SessionConfigured so MCP events follow it.mcp_runtime,+ mcp_handler_cache: Default::default(),unified_exec_manager: UnifiedExecProcessManager::new(config.background_terminal_max_timeout,),diff --git a/codex-rs/core/src/session/tests.rs b/codex-rs/core/src/session/tests.rsindex 3a0ae6850a..8048bf525e 100644--- a/codex-rs/core/src/session/tests.rs+++ b/codex-rs/core/src/session/tests.rs@@ -5750,6 +5750,7 @@ pub(crate) async fn make_session_and_context() -> (Session, TurnContext) {.then(|| Arc::new(crate::state::ExecutedToolCallRecorder::default()));let services = SessionServices {mcp_runtime,+ mcp_handler_cache: Default::default(),unified_exec_manager: UnifiedExecProcessManager::new(config.background_terminal_max_timeout,),@@ -7968,6 +7969,7 @@ where.then(|| Arc::new(crate::state::ExecutedToolCallRecorder::default()));let services = SessionServices {mcp_runtime,+ mcp_handler_cache: Default::default(),unified_exec_manager: UnifiedExecProcessManager::new(config.background_terminal_max_timeout,),@@ -8183,6 +8185,18 @@ async fn refresh_mcp_servers_uses_latest_state_for_existing_turns() {.capture_step_context(next_turn, &CancellationToken::new()).await.expect("a fresh cancellation token cannot be cancelled");+ assert!(+ !Arc::ptr_eq(&old_step.mcp, &new_step.mcp),+ "publishing a new MCP runtime must invalidate cached bindings"+ );+ let refreshed_old_step = session+ .capture_step_context(Arc::clone(&turn_context), &CancellationToken::new())+ .await+ .expect("capture an existing turn after its MCP runtime is republished");+ assert!(+ Arc::ptr_eq(&new_step.mcp, &refreshed_old_step.mcp),+ "existing turns should reuse the newly published immutable MCP binding"+ );let rematerialized_old = session.mcp_runtime_for_step(&turn_context,@@ -8220,12 +8234,17 @@ async fn refresh_mcp_servers_uses_latest_state_for_existing_turns() {async fn refreshed_mcp_binding_captures_current_approval_authority() {let (session, old_turn) = make_session_and_context().await;let session = Arc::new(session);+ let old_turn = Arc::new(old_turn);let previous_policy = old_turn.approval_policy();assert_ne!(previous_policy, AskForApproval::Never);assert_eq!(old_turn.config.permissions.approval_policy.value(),previous_policy);+ let old_step = session+ .capture_step_context(Arc::clone(&old_turn), &CancellationToken::new())+ .await+ .expect("capture initial sampling step");session.update_settings(SessionSettingsUpdate {@@ -8244,6 +8263,18 @@ async fn refreshed_mcp_binding_captures_current_approval_authority() {.current_binding().await.expect("refreshed runtime should be available");+ assert!(+ !Arc::ptr_eq(&old_step.mcp, &binding),+ "changed approval authority must invalidate the cached MCP binding"+ );+ let refreshed_step = session+ .capture_step_context(Arc::clone(&old_turn), &CancellationToken::new())+ .await+ .expect("capture existing turn after its approval authority changes");+ assert!(+ Arc::ptr_eq(&binding, &refreshed_step.mcp),+ "existing turns must use the MCP binding with current approval authority"+ );let config = binding.config();assert_eq!((diff --git a/codex-rs/core/src/session/turn.rs b/codex-rs/core/src/session/turn.rsindex eb18e3b24f..5cb61ef7b7 100644--- a/codex-rs/core/src/session/turn.rs+++ b/codex-rs/core/src/session/turn.rs@@ -1475,7 +1475,7 @@ pub(crate) async fn built_tools(sess: &Session,turn_context: &TurnContext,environments: &TurnEnvironmentSnapshot,- mcp: &codex_mcp::McpBinding,+ mcp: &Arc<codex_mcp::McpBinding>,step_store: &ExtensionData,prepared_recommendations: PreparedToolRecommendations,) -> CodexResult<Arc<ToolRouter>> {diff --git a/codex-rs/core/src/state/service.rs b/codex-rs/core/src/state/service.rsindex dd17a076c1..1e3cb00bca 100644--- a/codex-rs/core/src/state/service.rs+++ b/codex-rs/core/src/state/service.rs@@ -14,6 +14,7 @@ use crate::environment_selection::ThreadEnvironments;use crate::exec_policy::ExecPolicyManager;use crate::guardian::GuardianRejectionCircuitBreaker;use crate::mcp::McpManager;+use crate::mcp_tool_exposure::McpHandlerCache;use crate::tools::ExecutedToolCallRecorder;use crate::tools::code_mode::CodeModeService;use crate::tools::handlers::ToolSearchHandlerCache;@@ -45,6 +46,8 @@ use tokio::sync::Mutex;pub(crate) struct SessionServices {/// The single owner of live MCP connections for this thread.pub(crate) mcp_runtime: Arc<McpRuntime>,+ /// Immutable MCP handlers scoped to this thread's current binding.+ pub(crate) mcp_handler_cache: McpHandlerCache,pub(crate) unified_exec_manager: UnifiedExecProcessManager,pub(crate) elicitations: ElicitationService,#[cfg_attr(not(unix), allow(dead_code))]diff --git a/codex-rs/core/src/tools/code_mode/execute_handler.rs b/codex-rs/core/src/tools/code_mode/execute_handler.rsindex e6ea6ff461..87d260be4e 100644--- a/codex-rs/core/src/tools/code_mode/execute_handler.rs+++ b/codex-rs/core/src/tools/code_mode/execute_handler.rs@@ -7,6 +7,7 @@ use crate::tools::registry::CoreToolRuntime;use crate::tools::registry::ToolExecutor;use codex_tools::ToolName;use codex_tools::ToolSpec;+use std::sync::Arc;use super::ExecContext;use super::PUBLIC_TOOL_NAME;@@ -14,13 +15,15 @@ use super::handle_runtime_response;use super::is_exec_tool_name;use super::telemetry::CodeModeToolCallGuard;+type CodeModeNestedTool = (Arc<ToolSpec>, Option<Arc<dyn CoreToolRuntime>>);+pub struct CodeModeExecuteHandler {spec: ToolSpec,- nested_tool_specs: Vec<ToolSpec>,+ nested_tool_specs: Vec<CodeModeNestedTool>,}impl CodeModeExecuteHandler {- pub(crate) fn new(spec: ToolSpec, nested_tool_specs: Vec<ToolSpec>) -> Self {+ pub(crate) fn new(spec: ToolSpec, nested_tool_specs: Vec<CodeModeNestedTool>) -> Self {Self {spec,nested_tool_specs,@@ -38,8 +41,26 @@ impl CodeModeExecuteHandler {let args =codex_code_mode::parse_exec_source(&code).map_err(FunctionCallError::RespondToModel)?;let exec = ExecContext { session, turn };- let enabled_tools =- codex_tools::collect_code_mode_tool_definitions(&self.nested_tool_specs);+ let mut enabled_tools = Vec::with_capacity(self.nested_tool_specs.len());+ for (spec, cached_runtime) in &self.nested_tool_specs {+ if let Some(cached_definitions) = cached_runtime+ .as_ref()+ .and_then(|runtime| runtime.cached_code_mode_definitions())+ {+ enabled_tools.extend_from_slice(cached_definitions);+ continue;+ }++ let definitions =+ codex_tools::collect_code_mode_tool_definitions(std::iter::once(spec.as_ref()));+ enabled_tools.extend(definitions.into_iter().map(|mut definition| {+ definition.input_schema = None;+ definition.output_schema = None;+ definition+ }));+ }+ enabled_tools.sort_by(|left, right| left.name.cmp(&right.name));+ enabled_tools.dedup_by(|left, right| left.name == right.name);let started_at = std::time::Instant::now();let started_cell = exec.sessiondiff --git a/codex-rs/core/src/tools/handlers/mcp.rs b/codex-rs/core/src/tools/handlers/mcp.rsindex 7a67372737..b6c9324022 100644--- a/codex-rs/core/src/tools/handlers/mcp.rs+++ b/codex-rs/core/src/tools/handlers/mcp.rs@@ -1,4 +1,5 @@use std::sync::Arc;+use std::sync::OnceLock;use std::time::Instant;use crate::function_tool::FunctionCallError;@@ -37,7 +38,8 @@ const MAX_MCP_NAMESPACE_DESCRIPTION_BYTES: usize = 512 * 1024;pub struct McpHandler {tool_info: ToolInfo,- spec: ToolSpec,+ spec: Arc<ToolSpec>,+ code_mode_tool_definitions: OnceLock<Vec<codex_code_mode::ToolDefinition>>,}impl McpHandler {@@ -66,8 +68,12 @@ impl McpHandler {.to_string()});}- let spec = create_tool_spec(&tool_info, agent_plugin)?;- Ok(Self { tool_info, spec })+ let spec = Arc::new(create_tool_spec(&tool_info, agent_plugin)?);+ Ok(Self {+ tool_info,+ spec,+ code_mode_tool_definitions: OnceLock::new(),+ })}pub(crate) fn model_spec_bytes(&self) -> Result<usize, serde_json::Error> {@@ -104,7 +110,7 @@ impl ToolExecutor<ToolInvocation> for McpHandler {}fn spec(&self) -> ToolSpec {- self.spec.clone()+ self.spec.as_ref().clone()}fn supports_parallel_tool_calls(&self) -> bool {@@ -197,6 +203,27 @@ impl McpHandler {}impl CoreToolRuntime for McpHandler {+ fn immutable_spec(&self) -> Option<&Arc<ToolSpec>> {+ Some(&self.spec)+ }++ fn cached_code_mode_definitions(&self) -> Option<&[codex_code_mode::ToolDefinition]> {+ Some(+ self.code_mode_tool_definitions+ .get_or_init(|| {+ let mut definitions = codex_tools::collect_code_mode_tool_definitions(+ std::iter::once(self.spec.as_ref()),+ );+ for definition in &mut definitions {+ definition.input_schema = None;+ definition.output_schema = None;+ }+ definitions+ })+ .as_slice(),+ )+ }+fn wait_until_ready<'a>(&'a self, session: &'a Arc<Session>) -> Option<BoxFuture<'a, ()>> {Some(Box::pin(async move {session@@ -536,6 +563,32 @@ mod tests {);}+ #[test]+ fn mcp_code_mode_definitions_are_cached_lazily() {+ let handler = McpHandler::new(tool_info("filesystem", "mcp__filesystem", "read_file"))+ .expect("MCP tool spec should build");++ assert!(handler.code_mode_tool_definitions.get().is_none());+ assert!(Arc::ptr_eq(+ handler+ .immutable_spec()+ .expect("MCP spec should be immutable"),+ &handler.spec,+ ));++ let first = handler+ .cached_code_mode_definitions()+ .expect("MCP definitions should be cached");+ assert_eq!(first.len(), 1);+ assert!(first[0].input_schema.is_none());+ assert!(first[0].output_schema.is_none());++ let second = handler+ .cached_code_mode_definitions()+ .expect("MCP definitions should be cached");+ assert!(std::ptr::eq(first, second));+ }+#[test]fn mcp_read_only_hint_supports_parallel_calls_without_server_opt_in() {let mut read_only_info = tool_info("foo", "mcp__foo__", "read");diff --git a/codex-rs/core/src/tools/registry.rs b/codex-rs/core/src/tools/registry.rsindex fd41dcb11c..b603512dd6 100644--- a/codex-rs/core/src/tools/registry.rs+++ b/codex-rs/core/src/tools/registry.rs@@ -51,6 +51,16 @@ pub use codex_tools::ToolExposure;/// Implementers provide the shared `ToolExecutor` behavior plus optional/// core-owned metadata for hooks, telemetry, tool search, and argument diffs.pub(crate) trait CoreToolRuntime: ToolExecutor<ToolInvocation> {+ /// Returns a shared spec when both the spec and search metadata are immutable.+ fn immutable_spec(&self) -> Option<&Arc<ToolSpec>> {+ None+ }++ /// Returns lazily cached Code Mode definitions owned by this runtime.+ fn cached_code_mode_definitions(&self) -> Option<&[codex_code_mode::ToolDefinition]> {+ None+ }+/// Returns a readiness wait for this exact tool before taking the execution gate.fn wait_until_ready<'a>(&'a self, _session: &'a Arc<Session>) -> Option<BoxFuture<'a, ()>> {None@@ -385,15 +395,22 @@ impl ToolRegistry {if !existing_description.trim().is_empty() {continue;}- let description = match tool.runtime.spec() {- ToolSpec::Namespace(namespace) => namespace.description,+ let owned_spec;+ let spec = if let Some(spec) = tool.runtime.immutable_spec() {+ spec.as_ref()+ } else {+ owned_spec = tool.runtime.spec();+ &owned_spec+ };+ let description = match spec {+ ToolSpec::Namespace(namespace) => namespace.description.as_str(),ToolSpec::Function(_)| ToolSpec::Freeform(_)| ToolSpec::ToolSearch { .. }- | ToolSpec::WebSearch { .. } => String::new(),+ | ToolSpec::WebSearch { .. } => "",};if !description.trim().is_empty() {- *existing_description = description;+ *existing_description = description.to_string();}}namespacesdiff --git a/codex-rs/core/src/tools/spec_plan.rs b/codex-rs/core/src/tools/spec_plan.rsindex 0e94988ec1..1b11729175 100644--- a/codex-rs/core/src/tools/spec_plan.rs+++ b/codex-rs/core/src/tools/spec_plan.rs@@ -2,7 +2,6 @@ use crate::agent::exceeds_thread_spawn_depth_limit;use crate::agent::next_thread_spawn_depth;use crate::environment_selection::TurnEnvironmentSnapshot;use crate::image_preparation::unified_image_budget_enabled;-use crate::mcp_tool_exposure::append_mcp_tools;use crate::session::session::Session;use crate::session::turn_context::TurnContext;use crate::tools::code_mode::default_exec_yield_time_override_ms;@@ -120,7 +119,7 @@ pub(crate) fn build_tool_router(session: &Session,turn_context: &TurnContext,environments: &TurnEnvironmentSnapshot,- mcp: &codex_mcp::McpBinding,+ mcp: &Arc<codex_mcp::McpBinding>,apps_enabled: bool,step_store: &ExtensionData,tool_suggest_candidates: Option<&crate::tools::router::ToolSuggestCandidates>,@@ -147,8 +146,8 @@ pub(crate) fn build_tool_router({Vec::new()} else {- let registered_mcp_tools = append_mcp_tools(- mcp.tools(),+ let registered_mcp_tools = session.services.mcp_handler_cache.append_mcp_tools(+ mcp,&turn_context.config,apps_enabled,&mcp.config().mcp_server_catalog,@@ -350,7 +349,14 @@ pub(crate) fn finalize_tool_router(let conflicting_tool_names = registry.entries().filter_map(|tool| {- let ToolSpec::Namespace(namespace) = tool.runtime.spec() else {+ let owned_spec;+ let spec = if let Some(spec) = tool.runtime.immutable_spec() {+ spec.as_ref()+ } else {+ owned_spec = tool.runtime.spec();+ &owned_spec+ };+ let ToolSpec::Namespace(namespace) = spec else {return None;};(namespace.name == tool_search_name.name).then(|| tool.runtime.tool_name())@@ -375,15 +381,22 @@ pub(crate) fn finalize_tool_router(let mut namespace_descriptions = BTreeMap::new();for tool in registry.entries() {- let ToolSpec::Namespace(namespace) = tool.runtime.spec() else {+ let owned_spec;+ let spec = if let Some(spec) = tool.runtime.immutable_spec() {+ spec.as_ref()+ } else {+ owned_spec = tool.runtime.spec();+ &owned_spec+ };+ let ToolSpec::Namespace(namespace) = spec else {continue;};if namespace.description.trim().is_empty() {continue;}- match namespace_descriptions.entry(namespace.name) {+ match namespace_descriptions.entry(namespace.name.clone()) {Entry::Vacant(entry) => {- entry.insert(namespace.description);+ entry.insert(namespace.description.clone());}Entry::Occupied(entry) if entry.get() != &namespace.description => {return Err(CodexErrorDetails::ToolCollision(entry.key().clone()).into());@@ -402,6 +415,15 @@ fn apply_direct_model_only_namespace_overrides(turn_context: &TurnContext,registry: &mut ToolRegistry,) {+ if turn_context+ .config+ .code_mode+ .direct_only_tool_namespaces+ .is_empty()+ {+ return;+ }+for tool in registry.entries_mut() {let configured = tool.runtime@@ -431,19 +453,24 @@ fn build_model_visible_specs() -> Vec<ToolSpec> {let mut specs = Vec::new();for tool in registry.entries() {- let tool_name = tool.runtime.tool_name();let exposure = tool.exposure;- if exposure.is_direct() && !is_hidden_by_code_mode_only(turn_context, &tool_name, exposure)- {- let spec = tool.runtime.spec();- specs.push(spec_for_model_request(- turn_context,- exposure,- &tool_name,- code_mode_tool_names,- spec,- ));+ if !exposure.is_direct() {+ continue;}++ let tool_name = tool.runtime.tool_name();+ if is_hidden_by_code_mode_only(turn_context, &tool_name, exposure) {+ continue;+ }++ let spec = tool.runtime.spec();+ specs.push(spec_for_model_request(+ turn_context,+ exposure,+ &tool_name,+ code_mode_tool_names,+ spec,+ ));}specs.extend(hosted_specs);@@ -653,6 +680,7 @@ fn register_code_mode_executors(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 mut included_deferred_mcp_output_schema = false;let deferred_tools_guidance_enabled = search_tool_enabled(turn_context);for tool in registry.entries() {let exposure = tool.exposure;@@ -665,9 +693,13 @@ fn register_code_mode_executors(continue;}- let spec = tool.runtime.spec();+ let immutable_spec = tool.runtime.immutable_spec();+ let cached_runtime = immutable_spec.map(|_| Arc::clone(&tool.runtime));+ let spec = immutable_spec+ .map(Arc::clone)+ .unwrap_or_else(|| Arc::new(tool.runtime.spec()));// Derive the name without serializing and augmenting every tool schema.- let code_mode_name = match &spec {+ let code_mode_name = match spec.as_ref() {ToolSpec::Function(_) | ToolSpec::Freeform(_) => {codex_tools::code_mode_name_for_tool_name(&tool_name)}@@ -698,13 +730,18 @@ fn register_code_mode_executors(}if exposure == ToolExposure::Deferred {- if deferred_tools_guidance_enabled {- deferred_exec_prompt_tool_specs.push(spec.clone());+ if deferred_tools_guidance_enabled+ && (cached_runtime.is_none() || !included_deferred_mcp_output_schema)+ {+ if cached_runtime.is_some() {+ included_deferred_mcp_output_schema = true;+ }+ deferred_exec_prompt_tool_specs.push(Arc::clone(&spec));}} else {- exec_prompt_tool_specs.push(spec.clone());+ exec_prompt_tool_specs.push(spec.as_ref().clone());}- code_mode_nested_tool_specs.push(spec);+ code_mode_nested_tool_specs.push((spec, cached_runtime));}if turn_context.model_info.use_responses_lite {@@ -716,10 +753,11 @@ fn register_code_mode_executors(let namespace_descriptions = code_mode_namespace_descriptions(&exec_prompt_tool_specs);let mut enabled_tools =collect_code_mode_exec_prompt_tool_definitions(exec_prompt_tool_specs.iter());+ let deferred_tools = collect_code_mode_exec_prompt_tool_definitions(+ deferred_exec_prompt_tool_specs.iter().map(Arc::as_ref),+ );enabled_tools.sort_by(|left, right| compare_code_mode_tools(left, right, &namespace_descriptions));- let deferred_tools =- collect_code_mode_exec_prompt_tool_definitions(deferred_exec_prompt_tool_specs.iter());let default_exec_yield_time_ms =default_exec_yield_time_override_ms(&turn_context.config.features).unwrap_or(codex_code_mode::DEFAULT_EXEC_YIELD_TIME_MS);diff --git a/codex-rs/core/tests/suite/code_mode.rs b/codex-rs/core/tests/suite/code_mode.rsindex 9e3ade1f61..d8b6fabbb3 100644--- a/codex-rs/core/tests/suite/code_mode.rs+++ b/codex-rs/core/tests/suite/code_mode.rs@@ -80,6 +80,8 @@ use std::fs;use std::io::Cursor;use std::path::Path;use std::sync::Arc;+use std::sync::atomic::AtomicUsize;+use std::sync::atomic::Ordering;use std::time::Duration;use std::time::Instant;use test_case::test_case;@@ -4175,7 +4177,10 @@ text(JSON.stringify({Ok(())}-struct NamespacedCustomTool;+struct NamespacedCustomTool {+ generation: usize,+ generations: Arc<AtomicUsize>,+}impl ToolContributor for NamespacedCustomTool {fn tools(@@ -4183,7 +4188,19 @@ impl ToolContributor for NamespacedCustomTool {_session_store: &ExtensionData,_thread_store: &ExtensionData,) -> Vec<Arc<dyn ToolExecutor<ToolCall>>> {- vec![Arc::new(Self)]+ Vec::new()+ }++ fn tools_for_step(+ &self,+ _session_store: &ExtensionData,+ _thread_store: &ExtensionData,+ _step_store: &ExtensionData,+ ) -> Vec<Arc<dyn ToolExecutor<ToolCall>>> {+ vec![Arc::new(Self {+ generation: self.generations.fetch_add(1, Ordering::Relaxed) + 1,+ generations: Arc::clone(&self.generations),+ })]}}@@ -4198,7 +4215,7 @@ impl ToolExecutor<ToolCall> for NamespacedCustomTool {description: "Editing tools.".to_string(),tools: vec![ResponsesApiNamespaceTool::Custom(FreeformTool {name: "apply_patch".to_string(),- description: "Apply a raw editor patch.".to_string(),+ description: format!("Apply a raw editor patch (step {}).", self.generation),defer_loading: None,format: FreeformToolFormat {r#type: "grammar".to_string(),@@ -4220,6 +4237,7 @@ impl ToolExecutor<ToolCall> for NamespacedCustomTool {"namespace": call.tool_name.namespace,"name": call.tool_name.name,"input": input,+ "generation": self.generation,}))) as Box<dyn ToolOutput>)})}@@ -4231,7 +4249,10 @@ async fn code_mode_exposes_and_dispatches_namespaced_custom_tools() -> Result<()let server = responses::start_mock_server().await;let mut extensions = ExtensionRegistryBuilder::<Config>::new();- extensions.tool_contributor(Arc::new(NamespacedCustomTool));+ extensions.tool_contributor(Arc::new(NamespacedCustomTool {+ generation: 0,+ generations: Arc::new(AtomicUsize::new(0)),+ }));let mut builder = test_codex().with_model("test-gpt-5.1-codex").with_extensions(Arc::new(extensions.build()))@@ -4283,8 +4304,11 @@ text(JSON.stringify({let declaration ="declare const tools: { editor__apply_patch(input: string): Promise<unknown>; };";- let description =- format!("Apply a raw editor patch.\n\nexec tool declaration:\n```ts\n{declaration}\n```");+ let description = |generation| {+ format!(+ "Apply a raw editor patch (step {generation}).\n\nexec tool declaration:\n```ts\n{declaration}\n```"+ )+ };let first_body = requests[0].body_json();let namespaced_custom_tool = namespace_child_tool(&first_body, "editor", "apply_patch").expect("namespaced custom tool should be included in the model request");@@ -4293,7 +4317,7 @@ text(JSON.stringify({&serde_json::json!({"type": "custom","name": "apply_patch",- "description": description,+ "description": description(1),"format": {"type": "grammar","syntax": "lark",@@ -4301,6 +4325,14 @@ text(JSON.stringify({},}));+ let second_body = requests[1].body_json();+ let second_description = description(2);+ assert_eq!(+ namespace_child_tool(&second_body, "editor", "apply_patch")+ .and_then(|tool| tool.get("description"))+ .and_then(Value::as_str),+ Some(second_description.as_str())+ );let (direct_output, direct_success) =custom_tool_output_body_and_success(&requests[1], "call-direct");@@ -4314,6 +4346,7 @@ text(JSON.stringify({"namespace": "editor","name": "apply_patch","input": "direct patch",+ "generation": 1,}));@@ -4327,11 +4360,12 @@ text(JSON.stringify({exec_output,serde_json::json!({"name": "editor__apply_patch",- "description": format!("Editing tools.\n\n{description}"),+ "description": format!("Editing tools.\n\n{second_description}"),"result": {"namespace": "editor","name": "apply_patch","input": "nested patch",+ "generation": 2,},}));diff --git a/codex-rs/core/tests/suite/mcp_tool_cache.rs b/codex-rs/core/tests/suite/mcp_tool_cache.rsindex 7d257d5714..8dd4863d9e 100644--- a/codex-rs/core/tests/suite/mcp_tool_cache.rs+++ b/codex-rs/core/tests/suite/mcp_tool_cache.rs@@ -222,8 +222,13 @@ async fn mcp_calls_stay_bound_to_each_thread() -> anyhow::Result<()> {wait_for_event(thread, |event| matches!(event, EventMsg::TurnComplete(_))).await;let request = call_response.single_request();assert!(request.tool_by_name(NAMESPACE, "echo").is_some());- let output = completion_response- .single_request()+ let completion_request = completion_response.single_request();+ assert_eq!(+ request.body_json()["tools"],+ completion_request.body_json()["tools"],+ "MCP tool schemas must remain unchanged across a same-turn continuation"+ );+ let output = completion_request.function_call_output_text(call_id).expect("MCP result should be returned to the model");assert!(output.contains(&process));@@ -502,6 +507,11 @@ async fn cached_mcp_startup_is_eager_for_root_and_lazy_for_subagents() -> anyhow.await?;let expected_error = format!("MCP tool `{SERVER_NAME}/cwd` is not available to the model");assert_eq!(cached_turn.await??, second_process);+ assert_definition(+ &cached_done_response,+ &format!("Use the tools from {second_process}."),+ &format!("Echo from {second_process}."),+ );let output = cached_done_response.single_request().function_call_output_text(app_only_call_id)