Lightweight coding agent that runs in your terminal
Rust
Honor tool-description-first ordering in Code Mode (#51704)
swastik-oai0a2a64e94200
diff --git a/codex-rs/core/src/tools/code_mode/execute_handler.rs b/codex-rs/core/src/tools/code_mode/execute_handler.rsindex 75733b9dfa..25661c6c35 100644--- a/codex-rs/core/src/tools/code_mode/execute_handler.rs+++ b/codex-rs/core/src/tools/code_mode/execute_handler.rs@@ -4,6 +4,7 @@ use crate::tools::context::ToolPayload;use crate::tools::context::boxed_tool_output;use crate::tools::registry::CoreToolRuntime;use crate::tools::registry::ToolExecutor;+use codex_features::Feature;use codex_prompts::ResolvedModelMessages;use codex_tools::IndirectNamespacePrefixes;use codex_tools::ToolName;@@ -55,12 +56,18 @@ impl CodeModeExecuteHandler {.config.code_mode.tool_input_schema_max_bytes;+ let tool_description_first = step_context+ .turn+ .config+ .features+ .enabled(Feature::CodeModeToolDescriptionFirst);let mut enabled_tools = Vec::with_capacity(self.nested_tool_specs.len());for (spec, cached_runtime) in &self.nested_tool_specs {let definitions = prepare_code_mode_tool_definitions(cached_runtime.as_deref(),|| Cow::Borrowed(spec.as_ref()),code_mode_input_schema_max_bytes,+ tool_description_first,);match definitions {Cow::Borrowed(definitions) => enabled_tools.extend_from_slice(definitions),diff --git a/codex-rs/core/src/tools/code_mode/tool_definitions.rs b/codex-rs/core/src/tools/code_mode/tool_definitions.rsindex 84b262319a..568f6dabd6 100644--- a/codex-rs/core/src/tools/code_mode/tool_definitions.rs+++ b/codex-rs/core/src/tools/code_mode/tool_definitions.rs@@ -1,5 +1,6 @@//! Prepares nested tool definitions for execution and search.//! Cached definitions stay borrowed; rendered schemas are dropped after augmentation.+//! Description order follows the session-static feature setting.use crate::tools::registry::CoreToolRuntime;use codex_code_mode::ToolDefinition;@@ -10,10 +11,12 @@ pub(crate) fn prepare_code_mode_tool_definitions<'a>(runtime: Option<&'a dyn CoreToolRuntime>,spec: impl FnOnce() -> Cow<'a, ToolSpec>,code_mode_input_schema_max_bytes: Option<usize>,+ tool_description_first: bool,) -> Cow<'a, [ToolDefinition]> {- if let Some(definitions) = runtime- .and_then(|runtime| runtime.cached_code_mode_definitions(code_mode_input_schema_max_bytes))- {+ if let Some(definitions) = runtime.and_then(|runtime| {+ runtime+ .cached_code_mode_definitions(code_mode_input_schema_max_bytes, tool_description_first)+ }) {return Cow::Borrowed(definitions);}@@ -21,6 +24,7 @@ pub(crate) fn prepare_code_mode_tool_definitions<'a>(let mut definitions = codex_tools::collect_code_mode_tool_definitions(std::iter::once(spec.as_ref()),code_mode_input_schema_max_bytes,+ tool_description_first,);for definition in &mut definitions {definition.input_schema = None;diff --git a/codex-rs/core/src/tools/handlers/mcp.rs b/codex-rs/core/src/tools/handlers/mcp.rsindex 4cce55018f..e165a53ab2 100644--- a/codex-rs/core/src/tools/handlers/mcp.rs+++ b/codex-rs/core/src/tools/handlers/mcp.rs@@ -51,7 +51,8 @@ const MAX_MCP_NAMESPACE_DESCRIPTION_BYTES: usize = 512 * 1024;pub struct McpHandler {tool_info: ToolInfo,spec: Arc<ToolSpec>,- code_mode_tool_definitions: OnceLock<(Option<usize>, Vec<codex_code_mode::ToolDefinition>)>,+ code_mode_tool_definitions:+ OnceLock<(Option<usize>, bool, Vec<codex_code_mode::ToolDefinition>)>,}impl McpHandler {@@ -284,20 +285,29 @@ impl CoreToolRuntime for McpHandler {fn cached_code_mode_definitions(&self,code_mode_input_schema_max_bytes: Option<usize>,+ tool_description_first: bool,) -> Option<&[codex_code_mode::ToolDefinition]> {- let (cached_budget, definitions) = 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()),- code_mode_input_schema_max_bytes,- );- for definition in &mut definitions {- definition.input_schema = None;- definition.output_schema = None;- }- (code_mode_input_schema_max_bytes, definitions)- });- // A config change must not reuse descriptions rendered under the previous budget.- (*cached_budget == code_mode_input_schema_max_bytes).then_some(definitions.as_slice())+ let (cached_budget, cached_tool_description_first, definitions) =+ 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()),+ code_mode_input_schema_max_bytes,+ tool_description_first,+ );+ for definition in &mut definitions {+ definition.input_schema = None;+ definition.output_schema = None;+ }+ (+ code_mode_input_schema_max_bytes,+ tool_description_first,+ definitions,+ )+ });+ // Reuse definitions only when both rendering inputs match.+ (*cached_budget == code_mode_input_schema_max_bytes+ && *cached_tool_description_first == tool_description_first)+ .then_some(definitions.as_slice())}fn wait_until_ready<'a>(&'a self, session: &'a Arc<Session>) -> Option<BoxFuture<'a, ()>> {@@ -833,17 +843,36 @@ mod tests {));let first = handler- .cached_code_mode_definitions(/*code_mode_input_schema_max_bytes*/ None)+ .cached_code_mode_definitions(+ /*code_mode_input_schema_max_bytes*/ None,+ /*tool_description_first*/ false,+ ).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());+ assert!(+ handler+ .cached_code_mode_definitions(+ /*code_mode_input_schema_max_bytes*/ None,+ /*tool_description_first*/ true,+ )+ .is_none()+ );+let second = handler- .cached_code_mode_definitions(/*code_mode_input_schema_max_bytes*/ None)+ .cached_code_mode_definitions(+ /*code_mode_input_schema_max_bytes*/ None,+ /*tool_description_first*/ false,+ ).expect("MCP definitions should be cached");assert!(std::ptr::eq(first, second));- assert!(handler.cached_code_mode_definitions(Some(32_000)).is_none());+ assert!(+ handler+ .cached_code_mode_definitions(Some(32_000), /*tool_description_first*/ false)+ .is_none()+ );}#[test]diff --git a/codex-rs/core/src/tools/handlers/tool_search.rs b/codex-rs/core/src/tools/handlers/tool_search.rsindex 570b6610a2..6fe3c7dfe7 100644--- a/codex-rs/core/src/tools/handlers/tool_search.rs+++ b/codex-rs/core/src/tools/handlers/tool_search.rs@@ -15,6 +15,7 @@ use bm25::Embedder;use bm25::EmbedderBuilder;use bm25::Language;use bm25::Scorer;+use codex_features::Feature;use codex_prompts::ResolvedModelMessages;use codex_tools::IndirectNamespacePrefixes;use codex_tools::JsonToolOutput;@@ -259,6 +260,11 @@ impl ToolSearchHandler {.config.code_mode.tool_input_schema_max_bytes,+ step_context+ .turn+ .config+ .features+ .enabled(Feature::CodeModeToolDescriptionFirst),&indirect_prefixes,);return Ok(boxed_tool_output(JsonToolOutput::new(serde_json::json!({@@ -286,6 +292,7 @@ impl ToolSearchHandler {limit: usize,router: &ToolRouter,code_mode_input_schema_max_bytes: Option<usize>,+ tool_description_first: bool,indirect_prefixes: &IndirectNamespacePrefixes<'_>,) -> Vec<CodeModeSearchResult> {let mut tools = Vec::new();@@ -313,6 +320,7 @@ impl ToolSearchHandler {Some(runtime.as_ref()),|| Cow::Owned(runtime.spec()),code_mode_input_schema_max_bytes,+ tool_description_first,);let Some(definition) = definitions.iter().find(|definition| {definition.tool_name.clone().with_default_namespace() == candidate_namediff --git a/codex-rs/core/src/tools/registry.rs b/codex-rs/core/src/tools/registry.rsindex ad51f77d73..da679ce292 100644--- a/codex-rs/core/src/tools/registry.rs+++ b/codex-rs/core/src/tools/registry.rs@@ -72,9 +72,11 @@ pub(crate) trait CoreToolRuntime: ToolExecutor<ToolInvocation> {/// Returns lazily cached, augmented Code Mode definitions owned by this runtime./// Input and output schemas must be cleared after rendering their declarations.+ /// Return None when the requested rendering inputs differ from the cached inputs.fn cached_code_mode_definitions(&self,_code_mode_input_schema_max_bytes: Option<usize>,+ _tool_description_first: bool,) -> Option<&[codex_code_mode::ToolDefinition]> {None}diff --git a/codex-rs/core/tests/suite/code_mode.rs b/codex-rs/core/tests/suite/code_mode.rsindex 3452a3939e..2b82def2b0 100644--- a/codex-rs/core/tests/suite/code_mode.rs+++ b/codex-rs/core/tests/suite/code_mode.rs@@ -3611,12 +3611,15 @@ async fn code_mode_complete_call_survives_unrelated_truncation() -> Result<()> {}#[tokio::test(flavor = "multi_thread", worker_threads = 2)]-#[test_case(false, None; "control")]-#[test_case(true, None; "ranked_search")]-#[test_case(true, Some(30_000); "ranked_search_expanded_schema")]+#[test_case(false, None, false; "control")]+#[test_case(true, None, false; "ranked_search")]+#[test_case(true, Some(30_000), false; "ranked_search_expanded_schema")]+#[test_case(false, None, true; "tool_description_first")]+#[test_case(true, None, true; "ranked_search_tool_description_first")]async fn code_mode_only_searches_and_calls_deferred_app_tools(ranked_search: bool,schema_max_bytes: Option<usize>,+ tool_description_first: bool,) -> Result<()> {skip_if_no_network!(Ok(()));@@ -3675,6 +3678,7 @@ if (!tool) {hasDeclaration: tool.description.includes("mcp__codex_apps__calendar_timezone_option_99(args:"),hasSchemaDescription: tool.description.includes("schema_budget_marker"),hasNamespacePrefix: tool.description.startsWith("Calendar search context.\n\n"),+ descriptionPrefix: tool.description.split("\n\nexec tool declaration:")[0],matchesCatalog: tool.description === ALL_TOOLS.find(({ name }) => name === tool.name)?.description,isError: Boolean(result.isError),text: result.content?.[0]?.text ?? "",@@ -3735,6 +3739,13 @@ if (!tool) {.enable(Feature::CodeModeOnly).expect("test config should allow feature update");config.code_mode.tool_input_schema_max_bytes = schema_max_bytes;+ config+ .features+ .set_enabled(+ Feature::CodeModeToolDescriptionFirst,+ tool_description_first,+ )+ .expect("test config should allow description order update");if ranked_search {config.features@@ -3822,6 +3833,11 @@ if (!tool) {"hasDeclaration": true,"hasSchemaDescription": schema_max_bytes.is_some(),"hasNamespacePrefix": true,+ "descriptionPrefix": if tool_description_first {+ "Calendar search context.\n\nRead timezone option 99.\n\nPlan events and manage your calendar."+ } else {+ "Calendar search context.\n\nPlan events and manage your calendar.\n\nRead timezone option 99."+ },"matchesCatalog": true,"isError": false,"text": "called calendar_timezone_option_99 for at with ",diff --git a/codex-rs/tools/src/code_mode.rs b/codex-rs/tools/src/code_mode.rsindex 8194387921..cc0b5326e4 100644--- a/codex-rs/tools/src/code_mode.rs+++ b/codex-rs/tools/src/code_mode.rs@@ -90,6 +90,7 @@ pub fn tool_spec_to_code_mode_tool_definition(spec: &ToolSpec) -> Option<CodeModpub fn collect_code_mode_tool_definitions<'a>(specs: impl IntoIterator<Item = &'a ToolSpec>,code_mode_input_schema_max_bytes: Option<usize>,+ tool_description_first: bool,) -> Vec<CodeModeToolDefinition> {let mut tool_definitions = specs.into_iter()@@ -100,8 +101,11 @@ pub fn collect_code_mode_tool_definitions<'a>(let namespace_description = namespace.description.trim();if !namespace_description.is_empty() {for definition in &mut definitions {- definition.description =- format!("{namespace_description}\n\n{}", definition.description);+ definition.description = if tool_description_first {+ format!("{}\n\n{namespace_description}", definition.description)+ } else {+ format!("{namespace_description}\n\n{}", definition.description)+ };}}}diff --git a/codex-rs/tools/src/code_mode_tests.rs b/codex-rs/tools/src/code_mode_tests.rsindex 0486372a5c..9ee63c93da 100644--- a/codex-rs/tools/src/code_mode_tests.rs+++ b/codex-rs/tools/src/code_mode_tests.rs@@ -58,10 +58,12 @@ fn code_mode_materializes_mcp_output_schemas() {super::collect_code_mode_tool_definitions([&ToolSpec::Function(parsed)],/*code_mode_input_schema_max_bytes*/ None,+ /*tool_description_first*/ false,),super::collect_code_mode_tool_definitions([&ToolSpec::Function(eager)],/*code_mode_input_schema_max_bytes*/ None,+ /*tool_description_first*/ false,),);}