Lightweight coding agent that runs in your terminal
Rust
Apply model catalog overrides to history, notes, and context tools (#56313)
rhan-oaie103bbc06f2f
diff --git a/codex-rs/Cargo.lock b/codex-rs/Cargo.lockindex bfc383e4d7..6bf43c6b6a 100644--- a/codex-rs/Cargo.lock+++ b/codex-rs/Cargo.lock@@ -3683,6 +3683,7 @@ dependencies = ["codex-utils-output-truncation","core_test_support","http 1.4.0",+ "insta","pretty_assertions","serde_json","tempfile",@@ -4910,6 +4911,7 @@ dependencies = ["serde","serde_json","thiserror 2.0.18",+ "tracing","urlencoding",]diff --git a/codex-rs/core/src/session/mod.rs b/codex-rs/core/src/session/mod.rsindex afe840d5ad..1824f43aad 100644--- a/codex-rs/core/src/session/mod.rs+++ b/codex-rs/core/src/session/mod.rs@@ -104,6 +104,7 @@ use codex_otel::auth_storage::AuthStorageOriginator;use codex_otel::current_span_trace_id;use codex_otel::current_span_w3c_trace_context;use codex_otel::set_parent_from_w3c_trace_context;+use codex_prompts::ResolvedModelMessages;use codex_prompts::render_model_instructions;use codex_protocol::ResponseUsageMetadata;use codex_protocol::SessionId;@@ -4064,6 +4065,13 @@ impl Session {{extension_data.insert(messages.clone());}+ let model_messages = ResolvedModelMessages::from_model(&settings.model_info);+ if let Some(messages) = model_messages.history() {+ extension_data.insert(messages.clone());+ }+ if let Some(messages) = model_messages.notes() {+ extension_data.insert(messages.clone());+ }let (mcp, prepared_recommendations) = tokio::join!(// MCP refresh can be large; keep it off the sampling request's stack.Box::pin(self.mcp_runtime_for_step(diff --git a/codex-rs/core/src/tools/catalog_parameters.rs b/codex-rs/core/src/tools/catalog_parameters.rsdeleted file mode 100644index 9c36c70abe..0000000000--- a/codex-rs/core/src/tools/catalog_parameters.rs+++ /dev/null@@ -1,14 +0,0 @@-//! Parses catalog parameter overrides using the harness's supported JSON Schema subset.-//! Rejected schemas leave fallback and transport-specific requirements to the tool owner.--use codex_tools::JsonSchema;-use serde_json::Value;--pub(super) fn parse(parameters: &str) -> Result<JsonSchema, &'static str> {- let parameters: Value =- serde_json::from_str(parameters).map_err(|_| "schema is not valid JSON")?;- if !parameters.is_object() || parameters["type"] != "object" {- return Err("schema must declare an object type");- }- serde_json::from_value(parameters).map_err(|_| "schema uses unsupported JSON Schema structures")-}diff --git a/codex-rs/core/src/tools/code_mode/wait_spec.rs b/codex-rs/core/src/tools/code_mode/wait_spec.rsindex 01b713e515..b1ec01f177 100644--- a/codex-rs/core/src/tools/code_mode/wait_spec.rs+++ b/codex-rs/core/src/tools/code_mode/wait_spec.rs@@ -44,7 +44,7 @@ pub(crate) fn create_wait_tool(strict: false,parameters: parameters_override.and_then(- |parameters| match crate::tools::catalog_parameters::parse(parameters) {+ |parameters| match codex_tools::parse_catalog_tool_parameters(parameters) {Ok(parameters) => Some(parameters),Err(reason) => {tracing::warn!(diff --git a/codex-rs/core/src/tools/handlers/get_context_remaining.rs b/codex-rs/core/src/tools/handlers/get_context_remaining.rsindex 4ef46b2a70..cdde397204 100644--- a/codex-rs/core/src/tools/handlers/get_context_remaining.rs+++ b/codex-rs/core/src/tools/handlers/get_context_remaining.rs@@ -6,11 +6,11 @@ use crate::tools::context::ToolOutput;use crate::tools::context::ToolPayload;use crate::tools::context::boxed_tool_output;use crate::tools::handlers::get_context_remaining_spec::GET_CONTEXT_REMAINING_TOOL_NAME;-use crate::tools::handlers::get_context_remaining_spec::create_get_context_remaining_tool;use crate::tools::registry::CoreToolRuntime;use crate::tools::registry::ToolExecutor;use codex_protocol::models::ContentItem;use codex_protocol::models::ResponseInputItem;+use codex_protocol::openai_models::ToolMessage;use codex_tools::ToolName;use codex_tools::ToolSpec;use serde_json::Value as JsonValue;@@ -57,7 +57,17 @@ impl ToolOutput for GetContextRemainingOutput {}}-pub struct GetContextRemainingHandler;+pub struct GetContextRemainingHandler {+ spec: ToolSpec,+}++impl GetContextRemainingHandler {+ pub(crate) fn new(messages: Option<&ToolMessage>) -> Self {+ Self {+ spec: super::get_context_remaining_spec::create_get_context_remaining_tool(messages),+ }+ }+}impl ToolExecutor<ToolInvocation> for GetContextRemainingHandler {fn tool_name(&self) -> ToolName {@@ -69,7 +79,7 @@ impl ToolExecutor<ToolInvocation> for GetContextRemainingHandler {}fn spec(&self) -> ToolSpec {- create_get_context_remaining_tool()+ self.spec.clone()}fn handle<'a>(&'a self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'a>diff --git a/codex-rs/core/src/tools/handlers/get_context_remaining_spec.rs b/codex-rs/core/src/tools/handlers/get_context_remaining_spec.rsindex 102dfbd138..de63217574 100644--- a/codex-rs/core/src/tools/handlers/get_context_remaining_spec.rs+++ b/codex-rs/core/src/tools/handlers/get_context_remaining_spec.rs@@ -1,21 +1,24 @@+use codex_protocol::openai_models::ToolMessage;use codex_tools::JsonSchema;use codex_tools::ResponsesApiTool;use codex_tools::ToolSpec;+use codex_tools::with_catalog_tool_message;use serde_json::Value;use serde_json::json;use std::collections::BTreeMap;pub(crate) const GET_CONTEXT_REMAINING_TOOL_NAME: &str = "get_context_remaining";-pub fn create_get_context_remaining_tool() -> ToolSpec {- ToolSpec::Function(ResponsesApiTool {+pub fn create_get_context_remaining_tool(messages: Option<&ToolMessage>) -> ToolSpec {+ let tool = ResponsesApiTool {name: GET_CONTEXT_REMAINING_TOOL_NAME.to_string(),description: "Get the remaining tokens in the current context window.".to_string(),strict: false,defer_loading: None,parameters: JsonSchema::object(BTreeMap::new(), /*required*/ None, Some(false.into())),output_schema: Some(get_context_remaining_output_schema().into()),- })+ };+ ToolSpec::Function(with_catalog_tool_message(tool, messages))}fn get_context_remaining_output_schema() -> Value {diff --git a/codex-rs/core/src/tools/handlers/mcp_resource_spec.rs b/codex-rs/core/src/tools/handlers/mcp_resource_spec.rsindex 4c6d41f06b..86b550fbbd 100644--- a/codex-rs/core/src/tools/handlers/mcp_resource_spec.rs+++ b/codex-rs/core/src/tools/handlers/mcp_resource_spec.rs@@ -2,6 +2,7 @@ use codex_protocol::openai_models::ToolMessage;use codex_tools::JsonSchema;use codex_tools::ResponsesApiTool;use codex_tools::ToolSpec;+use codex_tools::with_catalog_tool_message;use std::collections::BTreeMap;pub fn create_list_mcp_resources_tool(messages: Option<&ToolMessage>) -> ToolSpec {@@ -29,7 +30,7 @@ pub fn create_list_mcp_resources_tool(messages: Option<&ToolMessage>) -> ToolSpeparameters: JsonSchema::object(properties, /*required*/ None, Some(false.into())),output_schema: None,};- with_model_messages(tool, messages)+ ToolSpec::Function(with_catalog_tool_message(tool, messages))}pub fn create_list_mcp_resource_templates_tool(messages: Option<&ToolMessage>) -> ToolSpec {@@ -58,7 +59,7 @@ pub fn create_list_mcp_resource_templates_tool(messages: Option<&ToolMessage>) -parameters: JsonSchema::object(properties, /*required*/ None, Some(false.into())),output_schema: None,};- with_model_messages(tool, messages)+ ToolSpec::Function(with_catalog_tool_message(tool, messages))}pub fn create_read_mcp_resource_tool(messages: Option<&ToolMessage>) -> ToolSpec {@@ -93,26 +94,7 @@ pub fn create_read_mcp_resource_tool(messages: Option<&ToolMessage>) -> ToolSpec),output_schema: None,};- with_model_messages(tool, messages)-}--fn with_model_messages(mut tool: ResponsesApiTool, messages: Option<&ToolMessage>) -> ToolSpec {- if let Some(messages) = messages {- if let Some(description) = &messages.description {- tool.description.clone_from(description);- }- if let Some(parameters) = &messages.parameters {- match crate::tools::catalog_parameters::parse(parameters) {- Ok(parameters) => tool.parameters = parameters,- Err(reason) => tracing::warn!(- tool = %tool.name,- reason,- "Invalid catalog tool parameters; using bundled parameters"- ),- }- }- }- ToolSpec::Function(tool)+ ToolSpec::Function(with_catalog_tool_message(tool, messages))}#[cfg(test)]diff --git a/codex-rs/core/src/tools/handlers/mcp_resource_spec_tests.rs b/codex-rs/core/src/tools/handlers/mcp_resource_spec_tests.rsindex ec6839e4e8..638e0173b5 100644--- a/codex-rs/core/src/tools/handlers/mcp_resource_spec_tests.rs+++ b/codex-rs/core/src/tools/handlers/mcp_resource_spec_tests.rs@@ -94,42 +94,3 @@ fn read_mcp_resource_tool_matches_expected_spec() {}));}--#[test]-fn catalog_fields_override_independently_and_invalid_parameters_fall_back() {- let parameters = r#"{"type":"object","properties":{"server":{"type":"string","description":"Catalog server guidance."}},"additionalProperties":false}"#;- for create_tool in [- create_list_mcp_resources_tool,- create_list_mcp_resource_templates_tool,- create_read_mcp_resource_tool,- ] {- for (description, schema, valid_schema) in [- (None, None, false),- (Some(""), None, false),- (None, Some(parameters), true),- (- Some(" Catalog {{literal}} guidance.\n"),- Some(parameters),- true,- ),- (Some("Catalog guidance."), Some("invalid JSON"), false),- (None, Some(r#"{"type":"string"}"#), false),- ] {- let messages = ToolMessage {- description: description.map(str::to_owned),- parameters: schema.map(str::to_owned),- };- let mut expected = create_tool(/*messages*/ None);- let ToolSpec::Function(tool) = &mut expected else {- panic!("expected a function tool");- };- if let Some(description) = description {- tool.description = description.to_owned();- }- if valid_schema {- tool.parameters = serde_json::from_str(parameters).unwrap();- }- assert_eq!(create_tool(Some(&messages)), expected);- }- }-}diff --git a/codex-rs/core/src/tools/handlers/new_context_window.rs b/codex-rs/core/src/tools/handlers/new_context_window.rsindex 4b11300b54..227aad0b58 100644--- a/codex-rs/core/src/tools/handlers/new_context_window.rs+++ b/codex-rs/core/src/tools/handlers/new_context_window.rs@@ -5,16 +5,26 @@ use crate::tools::context::ToolInvocation;use crate::tools::context::ToolPayload;use crate::tools::context::boxed_tool_output;use crate::tools::handlers::new_context_window_spec::NEW_CONTEXT_WINDOW_TOOL_NAME;-use crate::tools::handlers::new_context_window_spec::create_new_context_window_tool;use crate::tools::registry::CoreToolRuntime;use crate::tools::registry::ToolExecutor;+use codex_protocol::openai_models::ToolMessage;use codex_tools::ToolName;use codex_tools::ToolSpec;pub(crate) const NEW_CONTEXT_WINDOW_MESSAGE: &str ="A new context window will start without summarizing conversation history.";-pub struct NewContextWindowHandler;+pub struct NewContextWindowHandler {+ spec: ToolSpec,+}++impl NewContextWindowHandler {+ pub(crate) fn new(messages: Option<&ToolMessage>) -> Self {+ Self {+ spec: super::new_context_window_spec::create_new_context_window_tool(messages),+ }+ }+}impl ToolExecutor<ToolInvocation> for NewContextWindowHandler {fn tool_name(&self) -> ToolName {@@ -22,7 +32,7 @@ impl ToolExecutor<ToolInvocation> for NewContextWindowHandler {}fn spec(&self) -> ToolSpec {- create_new_context_window_tool()+ self.spec.clone()}fn handle<'a>(&'a self, invocation: ToolInvocation) -> codex_tools::ToolExecutorFuture<'a>diff --git a/codex-rs/core/src/tools/handlers/new_context_window_spec.rs b/codex-rs/core/src/tools/handlers/new_context_window_spec.rsindex d2bde1f137..c5ac4bc88a 100644--- a/codex-rs/core/src/tools/handlers/new_context_window_spec.rs+++ b/codex-rs/core/src/tools/handlers/new_context_window_spec.rs@@ -1,17 +1,20 @@+use codex_protocol::openai_models::ToolMessage;use codex_tools::JsonSchema;use codex_tools::ResponsesApiTool;use codex_tools::ToolSpec;+use codex_tools::with_catalog_tool_message;use std::collections::BTreeMap;pub(crate) const NEW_CONTEXT_WINDOW_TOOL_NAME: &str = "new_context";-pub fn create_new_context_window_tool() -> ToolSpec {- ToolSpec::Function(ResponsesApiTool {+pub fn create_new_context_window_tool(messages: Option<&ToolMessage>) -> ToolSpec {+ let tool = ResponsesApiTool {name: NEW_CONTEXT_WINDOW_TOOL_NAME.to_string(),description: "Start a new context window. Does not clear, reset, or otherwise affect environment state.".to_string(),strict: false,defer_loading: None,parameters: JsonSchema::object(BTreeMap::new(), /*required*/ None, Some(false.into())),output_schema: None,- })+ };+ ToolSpec::Function(with_catalog_tool_message(tool, messages))}diff --git a/codex-rs/core/src/tools/handlers/request_user_input_async.rs b/codex-rs/core/src/tools/handlers/request_user_input_async.rsindex da153dcd59..a98d43ebb9 100644--- a/codex-rs/core/src/tools/handlers/request_user_input_async.rs+++ b/codex-rs/core/src/tools/handlers/request_user_input_async.rs@@ -66,7 +66,7 @@ impl ToolExecutor<ToolInvocation> for RequestUserInputAsyncHandler {/*additional_properties*/ Some(false.into()),);if let Some(parameters_override) = &self.parameters {- match crate::tools::catalog_parameters::parse(parameters_override) {+ match codex_tools::parse_catalog_tool_parameters(parameters_override) {Ok(schema) => parameters = schema,Err(reason) => tracing::warn!(tool = TOOL_NAME,diff --git a/codex-rs/core/src/tools/mod.rs b/codex-rs/core/src/tools/mod.rsindex 8f4041420c..73473f41d1 100644--- a/codex-rs/core/src/tools/mod.rs+++ b/codex-rs/core/src/tools/mod.rs@@ -1,6 +1,5 @@mod approvals;pub(crate) mod call_trace;-mod catalog_parameters;pub(crate) mod code_mode;pub(crate) mod context;mod control_tool_analytics;diff --git a/codex-rs/core/src/tools/multi_agent_tool.rs b/codex-rs/core/src/tools/multi_agent_tool.rsindex 0e44fd92b2..2b271af752 100644--- a/codex-rs/core/src/tools/multi_agent_tool.rs+++ b/codex-rs/core/src/tools/multi_agent_tool.rs@@ -25,7 +25,7 @@ pub(super) fn multi_agent_v2_handler(parameters_override: Option<&str>,) -> Arc<dyn CoreToolRuntime> {let parameters_override = parameters_override.map(|parameters| -> Result<JsonSchema, &str> {- let mut parameters = super::catalog_parameters::parse(parameters)?;+ let mut parameters = codex_tools::parse_catalog_tool_parameters(parameters)?;if let ToolSpec::Function(tool) = handler.spec()&& let Some(properties) = tool.parameters.properties{diff --git a/codex-rs/core/src/tools/spec_plan.rs b/codex-rs/core/src/tools/spec_plan.rsindex 24b60f3ff2..192deff7e1 100644--- a/codex-rs/core/src/tools/spec_plan.rs+++ b/codex-rs/core/src/tools/spec_plan.rs@@ -652,7 +652,11 @@ fn build_model_visible_specs(}specs.extend(hosted_specs);- merge_into_namespaces(specs)+ let mcp_namespaces = registry+ .mcp_namespaces()+ .map(|(_, namespace)| namespace)+ .collect();+ merge_into_namespaces(specs, &mcp_namespaces)}fn spec_for_model_request(@@ -1101,7 +1105,7 @@ fn register_code_mode_executors(}#[instrument(level = "trace", skip_all, fields(tool_spec_count = specs.len()))]-fn merge_into_namespaces(specs: Vec<ToolSpec>) -> Vec<ToolSpec> {+fn merge_into_namespaces(specs: Vec<ToolSpec>, mcp_namespaces: &HashSet<&str>) -> Vec<ToolSpec> {let mut merged_specs = Vec::with_capacity(specs.len());let mut namespace_indices = BTreeMap::<String, usize>::new();for spec in specs {@@ -1144,7 +1148,10 @@ fn merge_into_namespaces(specs: Vec<ToolSpec>) -> Vec<ToolSpec> {left_name.cmp(right_name)});- if namespace.description.trim().is_empty() {+ // Native tools resolve their own defaults, including intentional empty descriptions.+ if namespace.description.trim().is_empty()+ && mcp_namespaces.contains(namespace.name.as_str())+ {namespace.description = default_namespace_description(&namespace.name);}}@@ -1358,8 +1365,17 @@ fn add_core_utility_tools(context: &CoreToolPlanContext<'_>, registry: &mut Tool}if features.enabled(Feature::TokenBudget) {- registry.add_with_exposure(NewContextWindowHandler, ToolExposure::DirectModelOnly);- registry.add(GetContextRemainingHandler);+ let model_messages = ResolvedModelMessages::from_model(context.model_info);+ let messages = model_messages.context_management();+ registry.add_with_exposure(+ NewContextWindowHandler::new(+ messages.and_then(|messages| messages.new_context.as_ref()),+ ),+ ToolExposure::DirectModelOnly,+ );+ registry.add(GetContextRemainingHandler::new(+ messages.and_then(|messages| messages.get_context_remaining.as_ref()),+ ));}let current_time_reminder_enabled = features.enabled(Feature::CurrentTimeReminder);diff --git a/codex-rs/core/src/tools/spec_plan_tests.rs b/codex-rs/core/src/tools/spec_plan_tests.rsindex 1a8a066187..1ecd9f77f1 100644--- a/codex-rs/core/src/tools/spec_plan_tests.rs+++ b/codex-rs/core/src/tools/spec_plan_tests.rs@@ -2060,6 +2060,8 @@ async fn relaxed_tool_collisions_preserve_first_nonempty_namespace_description()Some("Second namespace description."),"Second namespace description.",),+ (None, None, "Tools in the shared namespace."),+ (Some(""), Some(" \t\n"), "Tools in the shared namespace."),] {let runtime = |name, description: Option<&str>| {let mut tool = mcp_tool("shared", "shared", name);diff --git a/codex-rs/core/tests/suite/scenarios.rs b/codex-rs/core/tests/suite/scenarios.rsindex 51e89ca463..bd71eddee7 100644--- a/codex-rs/core/tests/suite/scenarios.rs+++ b/codex-rs/core/tests/suite/scenarios.rs@@ -110,6 +110,9 @@ mod incremental_tools_resume;#[path = "scenarios_model_instructions.rs"]mod model_instructions;+#[path = "scenarios_context_management_tools.rs"]+mod context_management_tools;+#[path = "scenarios_code_mode_settled_helpers_tests.rs"]mod code_mode_settled_helpers;diff --git a/codex-rs/core/tests/suite/scenarios_context_management_tools.rs b/codex-rs/core/tests/suite/scenarios_context_management_tools.rsnew file mode 100644index 0000000000..5402d5df38--- /dev/null+++ b/codex-rs/core/tests/suite/scenarios_context_management_tools.rs@@ -0,0 +1,94 @@+//! Outgoing context-tool definitions follow the captured acting model.++use super::*;+use codex_protocol::openai_models::ContextManagementToolMessages;+use codex_protocol::openai_models::ModelInfo;+use pretty_assertions::assert_eq;++fn configure_tools(model: &mut ModelInfo, description: &str) {+ let message = ToolMessage {+ description: Some(description.to_string()),+ parameters: Some(r#"{"type":"object","properties":{},"additionalProperties":false,"description":"Catalog arguments."}"#.to_string()),+ };+ model+ .model_messages+ .get_or_insert_default()+ .tools+ .get_or_insert_default()+ .context_management = Some(ContextManagementToolMessages {+ new_context: Some(message.clone()),+ get_context_remaining: Some(message),+ });+}++#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn catalog_context_tool_definitions_follow_captured_models() -> Result<()> {+ skip_if_no_network!(Ok(()));+ let server = start_mock_server().await;+ let mock = mount_sse_sequence(+ &server,+ vec![+ sse(vec![ev_completed("first")]),+ sse(vec![ev_completed("second")]),+ ],+ )+ .await;+ let test = test_codex()+ .with_model_info_override("gpt-5.4", |model| {+ model.use_responses_lite = false;+ model.tool_mode = Some(ToolMode::Direct);+ configure_tools(model, "Catalog context guidance.");+ })+ .with_config(|config| {+ config+ .features+ .enable(Feature::TokenBudget)+ .expect("enable token budget");+ let catalog = config.model_catalog.as_mut().expect("model catalog");+ let mut updated = catalog+ .models+ .iter()+ .find(|model| model.slug == "gpt-5.4")+ .unwrap()+ .clone();+ updated.slug = "context-tools-updated".to_string();+ configure_tools(&mut updated, "");+ catalog.models.push(updated);+ })+ .build_with_auto_env(&server)+ .await?;+ test.submit_text_turn("Begin work.").await?;+ core_test_support::submit_thread_settings(+ &test.codex,+ codex_protocol::protocol::ThreadSettingsOverrides {+ model: Some("context-tools-updated".to_string()),+ ..Default::default()+ },+ )+ .await?;+ test.submit_text_turn("Continue with updated tools.")+ .await?;+ let requests = mock.requests();+ assert_eq!(requests.len(), 2);+ for (request, description) in requests.iter().zip(["Catalog context guidance.", ""]) {+ let body = request.body_json();+ for name in ["new_context", "get_context_remaining"] {+ let tool = body["tools"]+ .as_array()+ .unwrap()+ .iter()+ .find(|tool| tool["name"] == name)+ .unwrap();+ assert_eq!(tool["description"], description);+ assert_eq!(tool["parameters"]["description"], "Catalog arguments.");+ }+ }+ insta::assert_snapshot!(context_snapshot::format_request_history_snapshot(+ "Context tool descriptions and parameters use the captured model; selecting a model with explicit empty descriptions preserves empty text and prior history.",+ &requests,+ &ContextSnapshotOptions::default()+ .rewrite_known_segments()+ .include_request_settings(),+ ));+ Ok(())+}diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__context_management_tools__catalog_context_tool_definitions_follow_captured_models.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__context_management_tools__catalog_context_tool_definitions_follow_captured_models.snapnew file mode 100644index 0000000000..2985ef461d--- /dev/null+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__context_management_tools__catalog_context_tool_definitions_follow_captured_models.snap@@ -0,0 +1,72 @@+---+source: core/tests/suite/scenarios_context_management_tools.rs+expression: "context_snapshot::format_request_history_snapshot(\"Context tool descriptions and parameters use the captured model; selecting a model with explicit empty descriptions preserves empty text and prior history.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"+---+Scenario: Context tool descriptions and parameters use the captured model; selecting a model with explicit empty descriptions preserves empty text and prior history.++## Window 1+Settings:+ include: ["reasoning.encrypted_content"]+ model: "gpt-5.4"+ parallel_tool_calls: true+ prompt_cache_key: "<PROMPT_CACHE_KEY 1>"+ reasoning: {"effort":"medium"}+ store: false+ stream: true+ text: {"verbosity":"low"}+ tool_choice: "auto"+ tools (9; hash=2f5d124739fef213):+ - function/exec_command: Runs a command in a PTY, returning output or a session ID for ongoing interaction.; args=[cmd, justification, login, max_output_tokens, prefix_rule, sandbox_permissions, shell, tty, workdir, yield_time_ms]; hash=c04108e51a8548c5+ - function/write_stdin: Writes characters to an existing unified exec session and returns recent output.; args=[chars, max_output_tokens, session_id, yield_time_ms]; hash=7fb62d8a3e2df4e2+ - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6+ - function/new_context: Catalog context guidance.; args=[]; hash=8d300f346fb11d84+ - function/get_context_remaining: Catalog context guidance.; args=[]; hash=802b1cf4a796b439+ - custom/apply_patch: The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the pat...; hash=dea9f12b0111a4ba+ - function/view_image: View a local image file from the filesystem when visual inspection is needed. Use this for images...; args=[detail, path]; hash=3b766d5bdec5d50e+ - tool_search: # Tool discovery Searches over deferred tool metadata with BM25 and exposes matching tools for t...; args=[limit, query]; hash=400cd6ac61d524a9+ - web_search; hash=f103e327c6870a46+-- request 1 (turn) --+00:message/developer:+ <MODEL_INSTRUCTIONS>+01:message/developer:+ <PERMISSIONS_INSTRUCTIONS>+02:message/developer[3]:+ [01] <context_window>+ [02]+ Agent name: /root+ First context window id: <UUID 1>+ Current context window id: <UUID 1>++ [03] </context_window>+03:message/user:+ <ENVIRONMENT_CONTEXT>+04:message/user:+ Begin work.++## Window 2 (after request 1)+Settings: relative to window 1+ model: "context-tools-updated"+ tools (9; hash=bc76e2d214a3ede5):+ ~ function/new_context; args=[]; hash=b9263827b0adbb78+ ~ function/get_context_remaining; args=[]; hash=3e96d66806c56bdd+-- request 2 (turn) --+00:message/developer:+ <MODEL_INSTRUCTIONS>+01:message/developer:+ <PERMISSIONS_INSTRUCTIONS>+02:message/developer[3]:+ [01] <context_window>+ [02]+ Agent name: /root+ First context window id: <UUID 1>+ Current context window id: <UUID 1>++ [03] </context_window>+03:message/user:+ <ENVIRONMENT_CONTEXT>+04:message/user:+ Begin work.+05:message/developer:+ <MODEL_SWITCH>+06:message/user:+ Continue with updated tools.diff --git a/codex-rs/ext/history-notes/Cargo.toml b/codex-rs/ext/history-notes/Cargo.tomlindex df2f272945..11e93ea96b 100644--- a/codex-rs/ext/history-notes/Cargo.toml+++ b/codex-rs/ext/history-notes/Cargo.toml@@ -30,6 +30,7 @@ serde_json = { workspace = true }codex-config = { workspace = true }codex-model-provider-info = { workspace = true }core_test_support = { workspace = true }+insta = { workspace = true }pretty_assertions = { workspace = true }tempfile = { workspace = true }tokio = { workspace = true, features = ["macros", "rt"] }diff --git a/codex-rs/ext/history-notes/src/extension.rs b/codex-rs/ext/history-notes/src/extension.rsindex ff425ec8fa..8af60180d4 100644--- a/codex-rs/ext/history-notes/src/extension.rs+++ b/codex-rs/ext/history-notes/src/extension.rs@@ -20,6 +20,8 @@ use codex_extension_api::ToolExecutor;use codex_login::AuthManager;use codex_model_provider::create_model_provider;use codex_protocol::AgentPath;+use codex_protocol::openai_models::HistoryToolMessages;+use codex_protocol::openai_models::NotesToolMessages;use codex_utils_output_truncation::TruncationPolicy;use serde_json::json;@@ -160,6 +162,39 @@ impl ToolContributor for HistoryNotesExtension {&self,session_store: &ExtensionData,thread_store: &ExtensionData,+ ) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {+ self.tools_with_messages(+ session_store,+ thread_store,+ /*history_messages*/ None,+ /*notes_messages*/ None,+ )+ }++ fn tools_for_step(+ &self,+ session_store: &ExtensionData,+ thread_store: &ExtensionData,+ step_store: &ExtensionData,+ ) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {+ let history_messages = step_store.get::<HistoryToolMessages>();+ let notes_messages = step_store.get::<NotesToolMessages>();+ self.tools_with_messages(+ session_store,+ thread_store,+ history_messages.as_deref(),+ notes_messages.as_deref(),+ )+ }+}++impl HistoryNotesExtension {+ fn tools_with_messages(+ &self,+ session_store: &ExtensionData,+ thread_store: &ExtensionData,+ history_messages: Option<&HistoryToolMessages>,+ notes_messages: Option<&NotesToolMessages>,) -> Vec<Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>> {let Some(config) = thread_store.get::<HistoryNotesExtensionConfig>() else {return Vec::new();@@ -176,6 +211,8 @@ impl ToolContributor for HistoryNotesExtension {config.backend.clone(),session_store.level_id().to_string(),identity.agent_name.clone(),+ history_messages,+ notes_messages,)) as Arc<dyn for<'call> ToolExecutor<ToolCall<'call>>>}).collect()diff --git a/codex-rs/ext/history-notes/src/tools.rs b/codex-rs/ext/history-notes/src/tools.rsindex 114ee2ece8..17773befb1 100644--- a/codex-rs/ext/history-notes/src/tools.rs+++ b/codex-rs/ext/history-notes/src/tools.rs@@ -13,10 +13,13 @@ use codex_protocol::models::FunctionCallOutputContentItem;use codex_protocol::models::FunctionCallOutputPayload;use codex_protocol::models::ImageReference;use codex_protocol::models::ResponseInputItem;+use codex_protocol::openai_models::HistoryToolMessages;+use codex_protocol::openai_models::NotesToolMessages;use codex_tools::JsonToolOutput;use codex_tools::ResponsesApiNamespace;use codex_tools::ResponsesApiNamespaceTool;use codex_tools::ToolExposure;+use codex_tools::with_catalog_tool_message;use serde_json::Value;use serde_json::json;@@ -235,6 +238,60 @@ impl HistoryNotesAction {}),}}++ fn spec(+ self,+ history_messages: Option<&HistoryToolMessages>,+ notes_messages: Option<&NotesToolMessages>,+ ) -> ToolSpec {+ let (namespace_description, tool_message) = match self {+ Self::HistoryListWindows => history_messages+ .map(|messages| (&messages.namespace_description, &messages.list_windows)),+ Self::HistoryListItems => history_messages+ .map(|messages| (&messages.namespace_description, &messages.list_items)),+ Self::HistoryReadItem => history_messages+ .map(|messages| (&messages.namespace_description, &messages.read_item)),+ Self::HistorySearchContents => history_messages+ .map(|messages| (&messages.namespace_description, &messages.search_contents)),+ Self::NotesListFilesByPrefix => notes_messages.map(|messages| {+ (+ &messages.namespace_description,+ &messages.list_files_by_prefix,+ )+ }),+ Self::NotesReadFile => notes_messages+ .map(|messages| (&messages.namespace_description, &messages.read_file)),+ Self::NotesSearchContents => notes_messages+ .map(|messages| (&messages.namespace_description, &messages.search_contents)),+ Self::NotesAppendToFile => notes_messages+ .map(|messages| (&messages.namespace_description, &messages.append_to_file)),+ Self::NotesWriteFile => notes_messages+ .map(|messages| (&messages.namespace_description, &messages.write_file)),+ }+ .map_or((None, None), |(namespace_description, tool_message)| {+ (namespace_description.as_deref(), tool_message.as_ref())+ });+ let tool = with_catalog_tool_message(+ ResponsesApiTool {+ name: self.name().to_string(),+ description: self.description().to_string(),+ strict: false,+ parameters: parse_tool_input_schema(&self.parameters()).unwrap_or_else(|error| {+ panic!("History tool input schema should parse: {error}")+ }),+ output_schema: None,+ defer_loading: None,+ },+ tool_message,+ );+ ToolSpec::Namespace(ResponsesApiNamespace {+ name: self.namespace().to_string(),+ description: namespace_description+ .unwrap_or(self.namespace_description())+ .to_string(),+ tools: vec![ResponsesApiNamespaceTool::Function(tool)],+ })+ }}pub(crate) struct HistoryNotesTool {@@ -242,6 +299,7 @@ pub(crate) struct HistoryNotesTool {backend: HistoryNotesBackend,session_id: String,current_agent_name: String,+ spec: ToolSpec,}impl HistoryNotesTool {@@ -250,12 +308,15 @@ impl HistoryNotesTool {backend: HistoryNotesBackend,session_id: String,current_agent_name: String,+ history_messages: Option<&HistoryToolMessages>,+ notes_messages: Option<&NotesToolMessages>,) -> Self {Self {action,backend,session_id,current_agent_name,+ spec: action.spec(history_messages, notes_messages),}}@@ -292,20 +353,7 @@ impl<'call> ToolExecutor<ToolCall<'call>> for HistoryNotesTool {}fn spec(&self) -> ToolSpec {- ToolSpec::Namespace(ResponsesApiNamespace {- name: self.action.namespace().to_string(),- description: self.action.namespace_description().to_string(),- tools: vec![ResponsesApiNamespaceTool::Function(ResponsesApiTool {- name: self.action.name().to_string(),- description: self.action.description().to_string(),- strict: false,- parameters: parse_tool_input_schema(&self.action.parameters()).unwrap_or_else(- |error| panic!("History tool input schema should parse: {error}"),- ),- output_schema: None,- defer_loading: None,- })],- })+ self.spec.clone()}fn exposure(&self) -> ToolExposure {diff --git a/codex-rs/ext/history-notes/src/tools_tests.rs b/codex-rs/ext/history-notes/src/tools_tests.rsindex 9ec63f6621..55d021ba3b 100644--- a/codex-rs/ext/history-notes/src/tools_tests.rs+++ b/codex-rs/ext/history-notes/src/tools_tests.rs@@ -153,3 +153,29 @@ fn rejects_malformed_attachments_instead_of_silently_dropping_them() {assert_eq!(message, "History backend returned invalid image content.");}}++#[test]+fn sparse_catalog_messages_preserve_defaults_and_explicit_empty_descriptions() {+ let action = super::HistoryNotesAction::NotesReadFile;+ let mut expected = action.spec(/*history_messages*/ None, /*notes_messages*/ None);+ let codex_tools::ToolSpec::Namespace(namespace) = &mut expected else {+ panic!("expected namespace");+ };+ namespace.description.clear();+ let codex_tools::ResponsesApiNamespaceTool::Function(tool) = &mut namespace.tools[0] else {+ panic!("expected function");+ };+ tool.description.clear();+ let messages = codex_protocol::openai_models::NotesToolMessages {+ namespace_description: Some(String::new()),+ read_file: Some(codex_protocol::openai_models::ToolMessage {+ description: Some(String::new()),+ parameters: Some(String::new()),+ }),+ ..Default::default()+ };+ assert_eq!(+ action.spec(/*history_messages*/ None, Some(&messages)),+ expected+ );+}diff --git a/codex-rs/ext/history-notes/tests/history_notes_extension.rs b/codex-rs/ext/history-notes/tests/history_notes_extension.rsindex 143eabe01f..e5db8b2ad2 100644--- a/codex-rs/ext/history-notes/tests/history_notes_extension.rs+++ b/codex-rs/ext/history-notes/tests/history_notes_extension.rs@@ -29,6 +29,8 @@ use codex_protocol::AgentPath;use codex_protocol::ThreadId;use codex_protocol::models::FunctionCallOutputContentItem;use codex_protocol::models::ResponseInputItem;+use codex_protocol::openai_models::NotesToolMessages;+use codex_protocol::openai_models::ToolMessage;use codex_protocol::protocol::SessionSource;use codex_protocol::protocol::SubAgentSource;use codex_protocol::protocol::TruncationPolicy;@@ -136,6 +138,37 @@ async fn installed_extension_exposes_and_invokes_history_notes_tools() -> TestRe]);+ // Existing executors retain the catalog snapshot selected for their step.+ let step_store = ExtensionData::new("step-1");+ let mut messages = NotesToolMessages {+ read_file: Some(ToolMessage {+ description: Some("Catalog read instructions".to_string()),+ ..Default::default()+ }),+ ..Default::default()+ };+ step_store.insert(messages.clone());+ let catalog_tools =+ registry.tool_contributors()[0].tools_for_step(&session_store, &thread_store, &step_store);+ let captured_tool = catalog_tools+ .iter()+ .find(|tool| tool.tool_name() == ToolName::namespaced("notes", "read_file"))+ .expect("notes.read_file should be exposed");+ let captured_spec = captured_tool.spec();+ messages.read_file.as_mut().expect("read_file").description = Some(String::new());+ step_store.insert(messages);+ let next_tools =+ registry.tool_contributors()[0].tools_for_step(&session_store, &thread_store, &step_store);+ assert_ne!(+ next_tools+ .iter()+ .find(|tool| tool.tool_name() == ToolName::namespaced("notes", "read_file"))+ .expect("notes.read_file should be exposed")+ .spec(),+ captured_spec+ );+ assert_eq!(captured_tool.spec(), captured_spec);+let read_file = tools.iter().find(|tool| tool.tool_name() == ToolName::namespaced("notes", "read_file"))diff --git a/codex-rs/ext/history-notes/tests/image_model_input.rs b/codex-rs/ext/history-notes/tests/image_model_input.rsindex be78b52a47..1f3105450b 100644--- a/codex-rs/ext/history-notes/tests/image_model_input.rs+++ b/codex-rs/ext/history-notes/tests/image_model_input.rs@@ -1,5 +1,6 @@-//! Verify history attachments survive native preparation into the next model request.+//! Verify captured catalog definitions and history attachments reach outgoing model requests.+use std::collections::BTreeMap;use std::sync::Arc;use codex_core::config::Config;@@ -9,6 +10,8 @@ use codex_history_notes_extension::install;use codex_login::AuthHeaders;use codex_login::AuthManager;use codex_login::CodexAuth;+use core_test_support::context_snapshot;+use core_test_support::context_snapshot::ContextSnapshotOptions;use core_test_support::responses;use core_test_support::test_codex::test_codex;use http::HeaderMap;@@ -22,6 +25,25 @@ use wiremock::matchers::path;const PNG: &str ="iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=";+const NATIVE_TOOLS: [(&str, &str, &[&str]); 2] = [+ (+ "history",+ "",+ &["list_windows", "list_items", "read_item", "search_contents"],+ ),+ (+ "notes",+ " ",+ &[+ "list_files_by_prefix",+ "read_file",+ "search_contents",+ "append_to_file",+ "write_file",+ ],+ ),+];+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]async fn history_images_reach_the_next_model_request() -> Result<(), Box<dyn std::error::Error>> {let server = responses::start_mock_server().await;@@ -62,10 +84,27 @@ async fn history_images_reach_the_next_model_request() -> Result<(), Box<dyn std&mut extensions,AuthManager::from_auth_for_testing(auth.clone()),);+ let parameters = json!({+ "type": "object", "description": "Catalog read parameters",+ "properties": {"window_id": {"type": "string"}, "item_id": {"type": "string"}},+ "required": ["window_id", "item_id"]+ });+ let catalog_parameters = parameters.clone();let test = test_codex().with_auth(auth)- .with_model_info_override("gpt-5.5", |model_info| {+ .with_model_info_override("gpt-5.5", move |model_info| {model_info.supports_experimental_context = true;+ let mut messages = json!({});+ for (namespace, description, names) in NATIVE_TOOLS {+ messages[namespace] = json!({"namespace_description": description});+ for name in names {+ messages[namespace][*name] =+ json!({"description": format!("Catalog {namespace}.{name}")});+ }+ }+ messages["history"]["read_item"]["parameters"] = json!(catalog_parameters.to_string());+ model_info.model_messages.get_or_insert_default().tools =+ Some(serde_json::from_value(messages).expect("native catalog messages"));}).with_extensions(Arc::new(extensions.build())).with_config(|config| {@@ -81,6 +120,41 @@ async fn history_images_reach_the_next_model_request() -> Result<(), Box<dyn std.await?;let requests = requests.requests();assert_eq!(requests.len(), 2);+ for request in &requests {+ let body = request.body_json();+ for (name, description, tool_names) in NATIVE_TOOLS {+ let namespace = body["tools"]+ .as_array()+ .expect("tools")+ .iter()+ .find(|tool| tool["name"] == name)+ .expect("native namespace");+ assert_eq!(namespace["description"], description);+ let tools = namespace["tools"].as_array().expect("namespace tools");+ assert_eq!(+ tools+ .iter()+ .map(|tool| (+ tool["name"].as_str().unwrap(),+ tool["description"].as_str().unwrap().to_string(),+ ))+ .collect::<BTreeMap<_, _>>(),+ tool_names+ .iter()+ .map(|tool| (*tool, format!("Catalog {name}.{tool}")))+ .collect(),+ );+ if name == "history" {+ assert_eq!(+ tools+ .iter()+ .find(|tool| tool["name"] == "read_item")+ .unwrap()["parameters"],+ parameters+ );+ }+ }+ }assert_eq!(requests[1].function_call_output("read-history")["output"],json!([@@ -90,5 +164,12 @@ async fn history_images_reach_the_next_model_request() -> Result<(), Box<dyn std{"type": "input_image", "image_url": format!("data:image/png;base64,{PNG}"), "detail": "auto"}]));+ insta::assert_snapshot!(context_snapshot::format_request_history_snapshot(+ "History/Notes catalog definitions preserve empty and whitespace namespace descriptions, and history images reach the next model request.",+ &requests,+ &ContextSnapshotOptions::default()+ .rewrite_known_segments()+ .include_request_settings(),+ ));Ok(())}diff --git a/codex-rs/ext/history-notes/tests/snapshots/image_model_input__history_images_reach_the_next_model_request.snap b/codex-rs/ext/history-notes/tests/snapshots/image_model_input__history_images_reach_the_next_model_request.snapnew file mode 100644index 0000000000..12bd58d554--- /dev/null+++ b/codex-rs/ext/history-notes/tests/snapshots/image_model_input__history_images_reach_the_next_model_request.snap@@ -0,0 +1,48 @@+---+source: ext/history-notes/tests/image_model_input.rs+expression: "context_snapshot::format_request_history_snapshot(\"History/Notes catalog definitions preserve empty and whitespace namespace descriptions, and history images reach the next model request.\",\n&requests,\n&ContextSnapshotOptions::default().rewrite_known_segments().include_request_settings(),)"+---+Scenario: History/Notes catalog definitions preserve empty and whitespace namespace descriptions, and history images reach the next model request.++## Window 1+Settings:+ include: ["reasoning.encrypted_content"]+ model: "gpt-5.5"+ parallel_tool_calls: true+ prompt_cache_key: "<PROMPT_CACHE_KEY 1>"+ reasoning: {"effort":"medium"}+ store: false+ stream: true+ text: {"verbosity":"low"}+ tool_choice: "auto"+ tools (9; hash=33554259377e0d47):+ - function/exec_command: Runs a command in a PTY, returning output or a session ID for ongoing interaction.; args=[cmd, justification, login, max_output_tokens, prefix_rule, sandbox_permissions, shell, tty, workdir, yield_time_ms]; hash=c04108e51a8548c5+ - function/write_stdin: Writes characters to an existing unified exec session and returns recent output.; args=[chars, max_output_tokens, session_id, yield_time_ms]; hash=7fb62d8a3e2df4e2+ - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6+ - custom/apply_patch: The `apply_patch` tool can be used to edit files. This is a FREEFORM tool, so do not wrap the pat...; hash=dea9f12b0111a4ba+ - function/view_image: View a local image file from the filesystem when visual inspection is needed. Use this for images...; args=[detail, path]; hash=3b766d5bdec5d50e+ - namespace/history; hash=48578cec2ffd3727+ - function/list_items+ - function/list_windows+ - function/read_item+ - function/search_contents+ - namespace/notes: ; hash=1984d9e2f2d6c4f0+ - function/append_to_file+ - function/list_files_by_prefix+ - function/read_file+ - function/search_contents+ - function/write_file+ - tool_search: # Tool discovery Searches over deferred tool metadata with BM25 and exposes matching tools for t...; args=[limit, query]; hash=400cd6ac61d524a9+ - web_search; hash=f103e327c6870a46+-- request 1 (turn) --+00:message/developer:+ <MODEL_INSTRUCTIONS>+01:message/developer:+ <PERMISSIONS_INSTRUCTIONS>+02:message/user:+ <ENVIRONMENT_CONTEXT>+03:message/user:+ Read the image from history.+-- request 2 (turn) --+04:function_call/history.read_item:{"item_id":"item","window_id":"window"}+05:function_call_output:<encrypted_content> | <input_image> | <input_image> | <input_image>diff --git a/codex-rs/prompts/src/model_messages.rs b/codex-rs/prompts/src/model_messages.rsindex 26d3266e16..c3f7e43c3f 100644--- a/codex-rs/prompts/src/model_messages.rs+++ b/codex-rs/prompts/src/model_messages.rs@@ -144,6 +144,27 @@ impl<'a> ResolvedModelMessages<'a> {})}+ /// Selects native history definitions; missing fields delegate to the tool owner.+ pub fn history(self) -> Option<&'a codex_protocol::openai_models::HistoryToolMessages> {+ self.catalog_messages?.tools.as_ref()?.history.as_ref()+ }++ /// Selects native notes definitions; missing fields delegate to the tool owner.+ pub fn notes(self) -> Option<&'a codex_protocol::openai_models::NotesToolMessages> {+ self.catalog_messages?.tools.as_ref()?.notes.as_ref()+ }++ /// Selects context-window control definitions independently of runtime tool names.+ pub fn context_management(+ self,+ ) -> Option<&'a codex_protocol::openai_models::ContextManagementToolMessages> {+ self.catalog_messages?+ .tools+ .as_ref()?+ .context_management+ .as_ref()+ }+/// Resolves optional confirmation policies, leaving missing values to actor defaults.pub fn confirmation_policies(&self) -> Option<&'a ConfirmationPolicies> {self.catalog_messagesdiff --git a/codex-rs/protocol/src/openai_models.rs b/codex-rs/protocol/src/openai_models.rsindex 797c3f881b..0b3a3d0e86 100644--- a/codex-rs/protocol/src/openai_models.rs+++ b/codex-rs/protocol/src/openai_models.rs@@ -35,6 +35,11 @@ use crate::protocol::MultiAgentVersion;mod access_programs;mod incremental_tools;pub use incremental_tools::IncrementalToolMessages;+#[path = "openai_models/memento_v2.rs"]+mod memento_v2;+pub use memento_v2::ContextManagementToolMessages;+pub use memento_v2::HistoryToolMessages;+pub use memento_v2::NotesToolMessages;#[path = "openai_models/guardian.rs"]mod guardian;pub use guardian::GuardianModelPolicy;@@ -585,6 +590,15 @@ pub struct ConfirmationPolicies {/// Model-owned tool messages and description prefixes.#[derive(Debug, Default, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]pub struct ToolMessages {+ /// Native Memento V2 history tool definitions, independent of runtime namespace aliases.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub history: Option<HistoryToolMessages>,+ /// Native Memento V2 notes tool definitions.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub notes: Option<NotesToolMessages>,+ /// Memento V2 context-window control tool definitions.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub context_management: Option<ContextManagementToolMessages>,/// Optional wording for incremental catalog notices.#[serde(default, skip_serializing_if = "Option::is_none")]pub incremental_tools: Option<IncrementalToolMessages>,@@ -634,7 +648,8 @@ pub struct ToolMessage {#[serde(default, skip_serializing_if = "Option::is_none")]pub description: Option<String>,/// Complete JSON Schema encoded as a string. Consumed by Multi-Agent V2 tools, Code Mode wait,- /// request_user_input_async (the send_user_message_async catalog key), and MCP resource helpers.+ /// request_user_input_async (the send_user_message_async catalog key), MCP resource helpers,+ /// and Memento V2 tools./// Uses the harness's supported schema subset; unrecognized keywords are ignored./// Missing, null, invalid or unsupported structures, or a root without `type: "object"`/// retains the harness parameters. Schema semantics must remain API-compatible.diff --git a/codex-rs/protocol/src/openai_models/memento_v2.rs b/codex-rs/protocol/src/openai_models/memento_v2.rsnew file mode 100644index 0000000000..0c803e91a9--- /dev/null+++ b/codex-rs/protocol/src/openai_models/memento_v2.rs@@ -0,0 +1,52 @@+//! Sparse Memento V2 tool definitions. Runtime data remains with consumers.++use super::ToolMessage;+use schemars::JsonSchema;+use serde::Deserialize;+use serde::Serialize;+use ts_rs::TS;++/// Model-owned history namespace and public tool definitions.+#[derive(Debug, Default, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]+pub struct HistoryToolMessages {+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub namespace_description: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub list_windows: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub list_items: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub read_item: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub search_contents: Option<ToolMessage>,+}++/// Model-owned notes namespace and public tool definitions.+#[derive(Debug, Default, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]+pub struct NotesToolMessages {+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub namespace_description: Option<String>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub list_files_by_prefix: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub read_file: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub search_contents: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub append_to_file: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub write_file: Option<ToolMessage>,+}++/// Model-owned context-window control tool definitions.+#[derive(Debug, Default, Serialize, Deserialize, Clone, PartialEq, Eq, TS, JsonSchema)]+pub struct ContextManagementToolMessages {+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub new_context: Option<ToolMessage>,+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub get_context_remaining: Option<ToolMessage>,+}++#[cfg(test)]+#[path = "memento_v2_tests.rs"]+mod tests;diff --git a/codex-rs/protocol/src/openai_models/memento_v2_tests.rs b/codex-rs/protocol/src/openai_models/memento_v2_tests.rsnew file mode 100644index 0000000000..aab2a77ba9--- /dev/null+++ b/codex-rs/protocol/src/openai_models/memento_v2_tests.rs@@ -0,0 +1,18 @@+use crate::openai_models::ModelMessages;+use pretty_assertions::assert_eq;+use serde_json::json;++#[test]+fn memento_catalog_round_trip_preserves_sparse_tools_and_explicit_empty() {+ for tools in [+ json!({}),+ json!({+ "history": {"namespace_description": "", "read_item": {"description": "", "parameters": "not JSON"}},+ "notes": {"read_file": {"parameters": "{}"}},+ "context_management": {"new_context": {"description": "catalog"}}+ }),+ ] {+ let messages: ModelMessages = serde_json::from_value(json!({"tools": tools})).unwrap();+ assert_eq!(serde_json::to_value(messages.tools).unwrap(), tools);+ }+}diff --git a/codex-rs/tools/Cargo.toml b/codex-rs/tools/Cargo.tomlindex b943f38be2..aa378ff33d 100644--- a/codex-rs/tools/Cargo.toml+++ b/codex-rs/tools/Cargo.toml@@ -29,6 +29,7 @@ rmcp = { workspace = true, default-features = false, features = [serde = { workspace = true, features = ["derive"] }serde_json = { workspace = true, features = ["raw_value"] }thiserror = { workspace = true }+tracing = { workspace = true }urlencoding = { workspace = true }[dev-dependencies]diff --git a/codex-rs/tools/src/catalog_tool_message.rs b/codex-rs/tools/src/catalog_tool_message.rsnew file mode 100644index 0000000000..492f8f5c98--- /dev/null+++ b/codex-rs/tools/src/catalog_tool_message.rs@@ -0,0 +1,49 @@+//! Applies sparse catalog overrides while preserving bundled tool transport requirements.+//! Invalid parameters retain the bundled schema; other tool fields remain harness-owned.++use crate::ResponsesApiTool;+use crate::parse_catalog_tool_parameters;+use codex_protocol::openai_models::ToolMessage;++/// Apply catalog descriptions and parameters without changing the tool's identity or transport.+pub fn with_catalog_tool_message(+ mut tool: ResponsesApiTool,+ messages: Option<&ToolMessage>,+) -> ResponsesApiTool {+ let Some(messages) = messages else {+ return tool;+ };+ if let Some(description) = &messages.description {+ tool.description.clone_from(description);+ }+ if let Some(parameters) = &messages.parameters {+ let parameters = parse_catalog_tool_parameters(parameters).and_then(|mut parameters| {+ if let Some(properties) = &tool.parameters.properties {+ for (name, bundled_property) in properties.iter() {+ if bundled_property.encrypted == Some(true) {+ let property = parameters+ .properties+ .as_mut()+ .and_then(|properties| properties.get_mut(name))+ .ok_or("schema omits an encrypted parameter")?;+ property.encrypted = Some(true);+ }+ }+ }+ Ok(parameters)+ });+ match parameters {+ Ok(parameters) => tool.parameters = parameters,+ Err(reason) => tracing::warn!(+ tool = %tool.name,+ reason,+ "Invalid catalog tool parameters; using bundled parameters"+ ),+ }+ }+ tool+}++#[cfg(test)]+#[path = "catalog_tool_message_tests.rs"]+mod tests;diff --git a/codex-rs/tools/src/catalog_tool_message_tests.rs b/codex-rs/tools/src/catalog_tool_message_tests.rsnew file mode 100644index 0000000000..5c6278a64a--- /dev/null+++ b/codex-rs/tools/src/catalog_tool_message_tests.rs@@ -0,0 +1,85 @@+use super::*;+use crate::JsonSchema;+use pretty_assertions::assert_eq;+use serde_json::json;++#[test]+fn catalog_overrides_preserve_tool_fields_and_encryption_with_independent_fallbacks() {+ let bundled = ResponsesApiTool {+ name: "example".to_string(),+ description: "Bundled guidance.".to_string(),+ strict: true,+ defer_loading: Some(true),+ parameters: serde_json::from_value(json!({+ "type": "object",+ "properties": {+ "text": {"type": "string", "encrypted": true},+ "title": {"type": "string", "encrypted": true},+ "path": {"type": "string"}+ }+ }))+ .unwrap(),+ output_schema: Some(json!({"type": "string"}).into()),+ };+ assert_eq!(+ with_catalog_tool_message(bundled.clone(), /*messages*/ None),+ bundled,+ );++ let mut catalog = json!({+ "type": "object",+ "properties": {+ "text": {"type": "string", "description": "Catalog guidance.", "encrypted": false},+ "title": {"type": "string"},+ "path": {"type": "string"}+ }+ });+ let parameters = catalog.to_string();+ catalog["properties"]["text"]["encrypted"] = json!(true);+ catalog["properties"]["title"]["encrypted"] = json!(true);+ let expected_parameters: JsonSchema = serde_json::from_value(catalog).unwrap();++ for (description, schema, expected_schema) in [+ (None, None, None),+ (Some(""), None, None),+ (None, Some(parameters.as_str()), Some(&expected_parameters)),+ (+ Some(" Catalog {{literal}} guidance.\n"),+ Some(parameters.as_str()),+ Some(&expected_parameters),+ ),+ (Some("Catalog guidance."), Some("invalid JSON"), None),+ (None, Some(r#"{"type":"string"}"#), None),+ (+ None,+ Some(r#"{"type":"object","properties":{"text":{"type":"unsupported"}}}"#),+ None,+ ),+ (+ Some(""),+ Some(r#"{"type":"object","properties":{"title":{"type":"string"}}}"#),+ None,+ ),+ (+ Some("Catalog guidance."),+ Some(r#"{"type":"object","properties":{"text":{"type":"string"}}}"#),+ None,+ ),+ ] {+ let messages = ToolMessage {+ description: description.map(str::to_owned),+ parameters: schema.map(str::to_owned),+ };+ let mut expected = bundled.clone();+ if let Some(description) = description {+ expected.description = description.to_owned();+ }+ if let Some(parameters) = expected_schema {+ expected.parameters = parameters.clone();+ }+ assert_eq!(+ with_catalog_tool_message(bundled.clone(), Some(&messages)),+ expected,+ );+ }+}diff --git a/codex-rs/tools/src/json_schema.rs b/codex-rs/tools/src/json_schema.rsindex 0d70b1712d..d4e6990fc6 100644--- a/codex-rs/tools/src/json_schema.rs+++ b/codex-rs/tools/src/json_schema.rs@@ -1,4 +1,4 @@-//! Normalize tool schemas and prune unreachable definitions before applying the size policy.+//! Parse catalog overrides and normalize external tool schemas with their size policy.mod compaction;mod traversal;@@ -22,6 +22,17 @@ const DEFINITION_TABLE_KEYS: [&str; 2] = ["$defs", "definitions"];const SCHEMA_CHILD_KEYS: [&str; 4] = ["items", "anyOf", "oneOf", "allOf"];const COMPOSITION_SCHEMA_KEYS: [&str; 3] = ["anyOf", "oneOf", "allOf"];+/// Parse catalog parameters without normalization or compaction.+/// Consumers own fallback and transport-specific requirements.+pub fn parse_catalog_tool_parameters(parameters: &str) -> Result<JsonSchema, &'static str> {+ let parameters: JsonValue =+ serde_json::from_str(parameters).map_err(|_| "schema is not valid JSON")?;+ if !parameters.is_object() || parameters["type"] != "object" {+ return Err("schema must declare an object type");+ }+ serde_json::from_value(parameters).map_err(|_| "schema uses unsupported JSON Schema structures")+}+/// Parse the tool `input_schema` or return an error for invalid schema.pub fn parse_tool_input_schema(input_schema: &JsonValue) -> Result<JsonSchema, serde_json::Error> {parse_tool_input_schema_with_max_bytes(input_schema, DEFAULT_COMPACT_TOOL_SCHEMA_BYTES)diff --git a/codex-rs/tools/src/json_schema_tests.rs b/codex-rs/tools/src/json_schema_tests.rsindex 768ae2deee..b6321afb16 100644--- a/codex-rs/tools/src/json_schema_tests.rs+++ b/codex-rs/tools/src/json_schema_tests.rs@@ -2,11 +2,39 @@ use super::AdditionalProperties;use super::JsonSchema;use super::JsonSchemaPrimitiveType;use super::JsonSchemaType;+use super::parse_catalog_tool_parameters;use super::parse_tool_input_schema;use super::parse_tool_input_schema_without_compaction;use pretty_assertions::assert_eq;use std::collections::BTreeMap;+#[test]+fn catalog_parameters_preserve_schema_without_normalization() {+ let parameters = serde_json::json!({+ "type": "object",+ "properties": {"paths": {"type": "array"}},+ "$defs": {"unused": {"type": "string"}}+ });+ let parsed = parse_catalog_tool_parameters(¶meters.to_string()).expect("catalog schema");+ assert_eq!(serde_json::to_value(parsed).unwrap(), parameters);+}++#[test]+fn catalog_parameters_reject_invalid_shapes() {+ for (parameters, reason) in [+ ("", "schema is not valid JSON"),+ ("null", "schema must declare an object type"),+ ("{}", "schema must declare an object type"),+ (r#"{"type":"array"}"#, "schema must declare an object type"),+ (+ r#"{"type":"object","properties":{"text":{"type":"unsupported"}}}"#,+ "schema uses unsupported JSON Schema structures",+ ),+ ] {+ assert_eq!(parse_catalog_tool_parameters(parameters), Err(reason));+ }+}+// Tests in this section exercise normalization transforms that mutate badly// formed JSON for consumption by the Responses API.diff --git a/codex-rs/tools/src/lib.rs b/codex-rs/tools/src/lib.rsindex a89697a2e9..86616597af 100644--- a/codex-rs/tools/src/lib.rs+++ b/codex-rs/tools/src/lib.rs@@ -1,6 +1,7 @@//! Shared tool definitions and Responses API tool primitives that can live//! outside `codex-core`.+mod catalog_tool_message;mod code_mode;mod dynamic_tool;mod function_call_error;@@ -23,6 +24,7 @@ mod tool_payload;mod tool_search;mod tool_spec;+pub use catalog_tool_message::with_catalog_tool_message;pub use code_mode::augment_tool_spec_for_code_mode;pub use code_mode::code_mode_name_for_tool_name;pub use code_mode::collect_code_mode_exec_prompt_tool_definitions;@@ -41,6 +43,7 @@ pub use json_schema::AdditionalProperties;pub use json_schema::JsonSchema;pub use json_schema::JsonSchemaPrimitiveType;pub use json_schema::JsonSchemaType;+pub use json_schema::parse_catalog_tool_parameters;pub use json_schema::parse_tool_input_schema;pub use json_schema::parse_tool_input_schema_without_compaction;pub use mcp_tool::mcp_call_tool_result_output_schema;