Support model-catalog overrides for Code Mode tool messages (#47118)

## What changed

- Add `tools.code_mode` catalog messages for `exec`, `wait`, deferred-tool guidance, and shared MCP TypeScript definitions.
- Render `{{ default_exec_yield_time_ms }}` and `{{ image_helper }}` in `exec` descriptions while preserving runtime tool declarations and the freeform grammar.
- Resolve `wait` descriptions and parameter schemas independently, falling back to bundled parameters for invalid or unsupported schemas.
- Use the active model's Code Mode messages, including after mid-turn model changes. Missing overrides retain bundled defaults; empty text overrides suppress the corresponding text.

## Testing

Add coverage for literal template substitution, runtime section preservation, independent `wait` overrides and fallback behavior, mid-turn model changes, and a yielded cell completing through `wait` with catalog messages.

GitOrigin-RevId: e542a0cd47a7138a414871192cee47790ed1214e
This commit is contained in:
rhan-oai
2026-09-21 22:49:17 +00:00
committed by copyberry
parent 3fd5160cd6
commit 5aa4939be4
19 changed files with 652 additions and 48 deletions
@@ -1,5 +1,6 @@
use codex_code_mode::ImageDetailVisibility;
use codex_code_mode::ToolDefinition as CodeModeToolDefinition;
use codex_protocol::openai_models::CodeModeToolMessages;
use codex_tools::FreeformTool;
use codex_tools::FreeformToolFormat;
use codex_tools::ToolSpec;
@@ -12,6 +13,7 @@ pub(crate) fn create_code_mode_tool(
default_exec_yield_time_ms: u64,
code_mode_only: bool,
image_detail_visibility: ImageDetailVisibility,
messages: Option<&CodeModeToolMessages>,
) -> ToolSpec {
const CODE_MODE_FREEFORM_GRAMMAR: &str = r#"
start: pragma_source | plain_source
@@ -32,6 +34,7 @@ SOURCE: /[\s\S]+/
default_exec_yield_time_ms,
code_mode_only,
image_detail_visibility,
messages,
),
defer_loading: None,
format: FreeformToolFormat {
@@ -67,6 +70,7 @@ mod tests {
codex_code_mode::DEFAULT_EXEC_YIELD_TIME_MS,
/*code_mode_only*/ true,
ImageDetailVisibility::Visible,
/*messages*/ None,
),
ToolSpec::Freeform(FreeformTool {
name: codex_code_mode::PUBLIC_TOOL_NAME.to_string(),
@@ -77,6 +81,7 @@ mod tests {
codex_code_mode::DEFAULT_EXEC_YIELD_TIME_MS,
/*code_mode_only*/ true,
ImageDetailVisibility::Visible,
/*messages*/ None,
),
defer_loading: None,
format: FreeformToolFormat {
@@ -20,7 +20,9 @@ use super::telemetry::CodeModeToolCallGuard;
use super::telemetry::trace_id;
use super::wait_spec::create_wait_tool;
pub struct CodeModeWaitHandler;
pub struct CodeModeWaitHandler {
spec: ToolSpec,
}
#[derive(Debug, Deserialize)]
struct ExecWaitArgs {
@@ -52,7 +54,7 @@ impl ToolExecutor<ToolInvocation> for CodeModeWaitHandler {
}
fn spec(&self) -> ToolSpec {
create_wait_tool()
self.spec.clone()
}
fn handle<'a>(&'a self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'a>
@@ -64,6 +66,15 @@ impl ToolExecutor<ToolInvocation> for CodeModeWaitHandler {
}
impl CodeModeWaitHandler {
pub(crate) fn new(
description_override: Option<&str>,
parameters_override: Option<&str>,
) -> Self {
Self {
spec: create_wait_tool(description_override, parameters_override),
}
}
// Default to interrupted if this future is dropped; telemetry::CodeModeToolCallGuard::finish
// overwrites this handler's captured span on explicit success or failure, including early errors.
#[tracing::instrument(
+33 -12
View File
@@ -3,7 +3,10 @@ use codex_tools::ResponsesApiTool;
use codex_tools::ToolSpec;
use std::collections::BTreeMap;
pub(crate) fn create_wait_tool() -> ToolSpec {
pub(crate) fn create_wait_tool(
description_override: Option<&str>,
parameters_override: Option<&str>,
) -> ToolSpec {
let properties = BTreeMap::from([
(
"cell_id".to_string(),
@@ -31,17 +34,35 @@ pub(crate) fn create_wait_tool() -> ToolSpec {
ToolSpec::Function(ResponsesApiTool {
name: codex_code_mode::WAIT_TOOL_NAME.to_string(),
description: format!(
"Waits on a yielded `{}` cell and returns new output or completion.\n{}",
codex_code_mode::PUBLIC_TOOL_NAME,
codex_code_mode::build_wait_tool_description().trim()
),
description: description_override.map(str::to_owned).unwrap_or_else(|| {
format!(
"Waits on a yielded `{}` cell and returns new output or completion.\n{}",
codex_code_mode::PUBLIC_TOOL_NAME,
codex_code_mode::build_wait_tool_description().trim()
)
}),
strict: false,
parameters: JsonSchema::object(
properties,
Some(vec!["cell_id".to_string()]),
Some(false.into()),
),
parameters: parameters_override
.and_then(
|parameters| match crate::tools::catalog_parameters::parse(parameters) {
Ok(parameters) => Some(parameters),
Err(reason) => {
tracing::warn!(
tool = codex_code_mode::WAIT_TOOL_NAME,
reason,
"Invalid catalog tool parameters; using bundled parameters"
);
None
}
},
)
.unwrap_or_else(|| {
JsonSchema::object(
properties,
Some(vec!["cell_id".to_string()]),
Some(false.into()),
)
}),
output_schema: None,
defer_loading: None,
})
@@ -55,7 +76,7 @@ mod tests {
#[test]
fn create_wait_tool_matches_expected_spec() {
assert_eq!(
create_wait_tool(),
create_wait_tool(/*description_override*/ None, /*parameters_override*/ None),
ToolSpec::Function(ResponsesApiTool {
name: codex_code_mode::WAIT_TOOL_NAME.to_string(),
description: format!(