Skip to content

armgit / codex

Public Imported from GitHub
0

Lightweight coding agent that runs in your terminal

Rust

Keep Code Mode tool discovery guidance stable across catalog changes (#50562)

Ahmed Ibrahim58ca099b0302
diff --git a/codex-rs/code-mode-protocol/src/description.rs b/codex-rs/code-mode-protocol/src/description.rs
index 5ad727fee8..87c918055f 100644
--- a/codex-rs/code-mode-protocol/src/description.rs
+++ b/codex-rs/code-mode-protocol/src/description.rs
@@ -14,7 +14,9 @@ use crate::json_schema_types::render_json_schema_to_typescript_with_budget;
const MAX_JS_SAFE_INTEGER: u64 = (1_u64 << 53) - 1;
const DEFERRED_NESTED_TOOLS_GUIDANCE: &str = r#"Some deferred nested tools may be omitted from this description. They are still available on the global `tools` object and listed in `ALL_TOOLS`.
-To find one, filter `ALL_TOOLS` by `name` and `description`."#;
+To find one, filter `ALL_TOOLS` by `name` and `description`.
+
+Tool availability can change between calls."#;
const LEGACY_IMAGE_HELPER_DESCRIPTION: &str = r#"`image(imageUrlOrItem: string | { image_url: string; detail?: "auto" | "low" | "high" | "original" | null } | ImageContent, detail?: "auto" | "low" | "high" | "original" | null)`: Appends an image item. `image_url` should be a base64-encoded `data:` URL. To forward an MCP tool image, pass an individual `ImageContent` block from `result.content`, for example `image(result.content[0])`. MCP image blocks may request detail with `_meta: { "codex/imageDetail": "original" }`. When provided, the second `detail` argument overrides any detail embedded in the first argument."#;
const UNIFIED_IMAGE_HELPER_DESCRIPTION: &str = r#"`image(imageUrlOrItem: string | { image_url: string } | ImageContent)`: Appends an image item. `image_url` should be a base64-encoded `data:` URL. To forward an MCP tool image, pass an individual `ImageContent` block from `result.content`, for example `image(result.content[0])`."#;
const EXEC_DESCRIPTION_TEMPLATE: &str = r#"Run JavaScript code to orchestrate/compose tool calls
@@ -268,7 +270,7 @@ pub enum ImageDetailVisibility {
pub fn build_exec_tool_description(
enabled_tools: &[ToolDefinition],
- deferred_tools: &[ToolDefinition],
+ _deferred_tools: &[ToolDefinition],
namespace_descriptions: &BTreeMap<String, ToolNamespaceDescription>,
default_exec_yield_time_ms: u64,
code_mode_only: bool,
@@ -292,13 +294,11 @@ pub fn build_exec_tool_description(
if !description.is_empty() {
sections.push(description);
}
- if !deferred_tools.is_empty() {
- let guidance = messages
- .and_then(|messages| messages.deferred_nested_tools_guidance.as_deref())
- .unwrap_or(DEFERRED_NESTED_TOOLS_GUIDANCE);
- if !guidance.is_empty() {
- sections.push(guidance.to_string());
- }
+ let guidance = messages
+ .and_then(|messages| messages.deferred_nested_tools_guidance.as_deref())
+ .unwrap_or(DEFERRED_NESTED_TOOLS_GUIDANCE);
+ if !guidance.is_empty() {
+ sections.push(guidance.to_string());
}
if !code_mode_only {
return sections.join("\n\n");
diff --git a/codex-rs/code-mode-protocol/src/description_override_tests.rs b/codex-rs/code-mode-protocol/src/description_override_tests.rs
index a133e14bfc..57c8b9f0cb 100644
--- a/codex-rs/code-mode-protocol/src/description_override_tests.rs
+++ b/codex-rs/code-mode-protocol/src/description_override_tests.rs
@@ -46,7 +46,7 @@ fn exec_override_renders_only_known_literal_placeholders() {
assert_eq!(
description,
format!(
- " \nDefaults to 10000 ms. 4567 ms.\n{image_helper}\n{{{{ unknown }}}} {{{{default_exec_yield_time_ms}}}}\t "
+ " \nDefaults to 10000 ms. 4567 ms.\n{image_helper}\n{{{{ unknown }}}} {{{{default_exec_yield_time_ms}}}}\t \n\n{DEFERRED_NESTED_TOOLS_GUIDANCE}"
),
);
}
@@ -77,6 +77,7 @@ fn exec_override_preserves_empty_and_whitespace_only_text() {
),
[
description_override,
+ "No deferred tools; omit this.",
"Shared MCP Types:\n```ts\nNo MCP tools; omit this.\n```"
]
.into_iter()
@@ -208,3 +209,47 @@ fn mcp_types_stay_stable_when_a_deferred_tool_changes_its_output_schema() {
assert_eq!(before, render(&tool, preamble));
}
}
+
+#[test]
+fn nested_guidance_survives_catalog_changes_and_respects_overrides() {
+ let deferred_tools = [ToolDefinition {
+ name: "deferred_echo".to_string(),
+ tool_name: ToolName::plain("deferred_echo"),
+ description: "Echo a value.".to_string(),
+ kind: CodeModeToolKind::Function,
+ input_schema: None,
+ input_schema_max_bytes: None,
+ output_schema: None,
+ }];
+ let render = |tools: &[ToolDefinition], code_mode_only, guidance: Option<&str>| {
+ build_exec_tool_description(
+ &[],
+ tools,
+ &BTreeMap::new(),
+ crate::DEFAULT_EXEC_YIELD_TIME_MS,
+ code_mode_only,
+ ImageDetailVisibility::Visible,
+ Some(&CodeModeToolMessages {
+ exec: Some(ToolMessage {
+ description: Some(String::new()),
+ ..Default::default()
+ }),
+ deferred_nested_tools_guidance: guidance.map(str::to_string),
+ mcp_typescript_preamble: Some(String::new()),
+ ..Default::default()
+ }),
+ )
+ };
+ for code_mode_only in [false, true] {
+ for (guidance, expected) in [
+ (None, DEFERRED_NESTED_TOOLS_GUIDANCE),
+ (Some("Catalog discovery."), "Catalog discovery."),
+ (Some(""), ""),
+ ] {
+ let prompt = render(&[], code_mode_only, guidance);
+ assert_eq!(prompt, expected);
+ assert_eq!(prompt, render(&deferred_tools, code_mode_only, guidance));
+ }
+ }
+ assert!(DEFERRED_NESTED_TOOLS_GUIDANCE.contains("Tool availability can change between calls"));
+}
diff --git a/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_followup_review_request_layout.snap b/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_followup_review_request_layout.snap
index 8088415452..a759fc36ac 100644
--- a/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_followup_review_request_layout.snap
+++ b/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_followup_review_request_layout.snap
@@ -6,8 +6,8 @@ Scenario: Guardian follow-up review request layout
## Window 1
-- request 1 (request; Initial Guardian Review Request) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
diff --git a/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_review_request_layout.snap b/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_review_request_layout.snap
index 902bbccf36..3a624e4f67 100644
--- a/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_review_request_layout.snap
+++ b/codex-rs/core/src/guardian/snapshots/codex_core__guardian__tests__guardian_review_request_layout.snap
@@ -6,8 +6,8 @@ Scenario: Guardian review request layout
## Window 1
-- request 1 (request; Guardian Review Request) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
diff --git a/codex-rs/core/src/tools/spec_plan_tests.rs b/codex-rs/core/src/tools/spec_plan_tests.rs
index 1518558409..07a0bea574 100644
--- a/codex-rs/core/src/tools/spec_plan_tests.rs
+++ b/codex-rs/core/src/tools/spec_plan_tests.rs
@@ -2699,10 +2699,10 @@ async fn excluded_deferred_namespaces_do_not_enable_nested_tool_guidance() {
panic!("expected code mode exec tool");
};
assert!(
- !exec
- .description
+ exec.description
.contains("Some deferred nested tools may be omitted")
);
+ assert!(!exec.description.contains("excluded__lookup("));
plan.assert_registered_contains(&[
&ToolName::namespaced("excluded", "lookup").to_string(),
"tool_search",
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__app_tool_exposure_CodeModeOnly.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__app_tool_exposure_CodeModeOnly.snap
index 544533d9b4..890bc6a0ad 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__app_tool_exposure_CodeModeOnly.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__app_tool_exposure_CodeModeOnly.snap
@@ -16,8 +16,8 @@ Settings:
stream: true
text: {"verbosity":"low"}
tool_choice: "auto"
- tools (4; hash=8f44dd235bfe4473):
- - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=0fc6c2a32798a2ec
+ tools (4; hash=aa7c4090dac68d7b):
+ - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=9c848ebf633880a2
- function/wait: Waits on a yielded `exec` cell and returns new output or completion. - Use `wait` only after `exe...; args=[cell_id, max_tokens, terminate, yield_time_ms]; hash=6692d8f6c55be489
- 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
- web_search; hash=e214d4db1bc49e89
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_active_environment_selection.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_active_environment_selection.snap
index f4f407fa8b..795fc65bbb 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_active_environment_selection.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_active_environment_selection.snap
@@ -6,8 +6,8 @@ Scenario: Astra starts in one workspace, switches for the next step of the activ
## Window 1
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=34dffd584d55c8e8):
- - namespace/functions; hash=93657a45ae4a5a60
+00:additional_tools/developer (3; hash=6517f5ceb3554929):
+ - namespace/functions; hash=4261ffb241688b3d
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap
index 4aab76dad6..b9999f419a 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap
@@ -7,8 +7,8 @@ Scenario: Astra uses the catalog question schema to ask who a launch update is f
## Window 1
-- request 1 (request) --
-00:additional_tools/developer (3; hash=2351b38cd1e61302):
- - namespace/functions; hash=27bd0dde5ddb5182
+00:additional_tools/developer (3; hash=2b6cdd8f97e8814b):
+ - namespace/functions; hash=7e611b8ddd5621cf
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_code_mode_call_timing.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_code_mode_call_timing.snap
index 171359ee6f..cc57f4f811 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_code_mode_call_timing.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_code_mode_call_timing.snap
@@ -6,8 +6,8 @@ Scenario: Astra receives host and handler timings on completed and failed code-m
## Window 1
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=fe0dd2d6b97e53b8):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_disabled_executor_skills.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_disabled_executor_skills.snap
index eb648aceb6..12ae7112ba 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_disabled_executor_skills.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_disabled_executor_skills.snap
@@ -16,8 +16,8 @@ Settings:
text: {"verbosity":"low"}
tool_choice: "auto"
-- request 1 (request) --
-00:additional_tools/developer (3; hash=e22abab074c3c061):
- - namespace/functions; hash=fd198a707305c309
+00:additional_tools/developer (3; hash=91d402a1b9d55c34):
+ - namespace/functions; hash=7d26e086c1dbba28
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_interrupts_response.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_interrupts_response.snap
index 404e031244..548b77a10d 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_interrupts_response.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_interrupts_response.snap
@@ -6,8 +6,8 @@ Scenario: Astra receives new user input after its unfinished response is interru
## Window 1
-- request 1 (request) --
-00:additional_tools/developer (3; hash=fe0dd2d6b97e53b8):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_yields_code_mode_cell.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_yields_code_mode_cell.snap
index 7f411b3160..4574331821 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_yields_code_mode_cell.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_yields_code_mode_cell.snap
@@ -6,8 +6,8 @@ Scenario: Astra continues after new user input yields a running code cell, then
## Window 1
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=c42aa1aa511db58f):
- - namespace/functions; hash=b655cdad519813cb
+00:additional_tools/developer (3; hash=42b12a95deaea38e):
+ - namespace/functions; hash=13a36c9bc9ada856
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_kickoff_remote_compaction_windows.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_kickoff_remote_compaction_windows.snap
index bc51fa69ab..4509958edc 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_kickoff_remote_compaction_windows.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_kickoff_remote_compaction_windows.snap
@@ -16,8 +16,8 @@ Settings:
text: {"verbosity":"low"}
tool_choice: "auto"
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=fe0dd2d6b97e53b8):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
@@ -187,8 +187,8 @@ Settings:
## Window 2 (after request 3: input diverged at item 02)
Settings: same as window 1
-- request 4 (turn) --
-00:additional_tools/developer (3; hash=fe0dd2d6b97e53b8):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_plugin_refresh.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_plugin_refresh.snap
index 251499874f..878f9c13e3 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_plugin_refresh.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_plugin_refresh.snap
@@ -16,8 +16,8 @@ Settings:
text: {"verbosity":"low"}
tool_choice: "auto"
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=fe0dd2d6b97e53b8):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
@@ -106,99 +106,7 @@ Settings:
Wall time <DURATION> seconds
Output:
| []
-
-## Window 2 (after request 2: input diverged at item 00)
-Settings: same as window 1
-- request 3 (turn) --
-00:additional_tools/developer (3; hash=7810769c6e12d379):
- - namespace/functions; hash=8c17932a39355f2d
- - custom/exec
- - function/wait
- - function/request_user_input
- - function/request_user_input_async
- - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
- - function/sleep
- - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=b263e3c84ad07c37
- - function/followup_task
- - function/interrupt_agent
- - function/list_agents
- - function/send_message
- - function/spawn_agent
- - function/wait_agent
-01:message/developer:
- You are Codex, an agent based on GPT-6. You and the user share one workspace, and your job is to collabo...them until their intended goal is completely handled. [hash=efa50f074efa5803]
-
- # When to ask the user for permission
-
- Use your best judgement given task context for when you really need user permission, like a competent co...ork without ending the turn to clarify with the user. [hash=ca7367e658b51388]
-
- User authorization and preferences persist across turns. Do not request permission again when the user h... any guidelines provided in skills or external files. [hash=911f91c92c72882c]
-
- <OMITTED 155 LINES; ~4935 TOKENS; hash=5573869716192298>
-
- - Skill naming: If a plugin contributes skills, those skill entries are prefixed with plugin_name: in the Skills list.
- - MCP naming: Plugin-provided MCP tools keep standard MCP identifiers such as mcp__server__tool; use tool provenance to tell which plugin they come from.
- - Trigger rules: If the user explicitly names a plugin, prefer capabilities associated with that plugin for that turn.
- - Relationship to capabilities: Plugins are not invoked directly. Use their underlying skills, MCP tools, and app tools to help solve the task.
- - Relevance: Determine what a plugin can help with from explicit user mention or from the plugin-associa..., MCP tools, and apps exposed elsewhere in this turn. [hash=620459a4e7b590f0]
- - Missing/blocked: If the user requests a plugin that does not have relevant callable capabilities for t..., say so briefly and continue with the best fallback. [hash=746b0469a8f6cb3e]
-
-02:message/developer[2]:
- [01] <permissions instructions>
- Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is `danger-full-access`...ll commands are permitted. Network access is enabled. [hash=c134061cebb94a1b]
- Approval policy is currently never. Do not provide the `sandbox_permissions` for any reason, commands will be rejected.
- </permissions instructions>
- [02] <collaboration_mode># Collaboration Mode: Default
-
- You are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.
-
- Your active mode changes only when new developer instructions with a different `<collaboration_mode>...<...by themselves. Known mode names are Default and Plan. [hash=e75f6b12fc52d812]
-
- ## request_user_input availability
-
- Use the `request_user_input` tool only when it is listed in the available tools for this turn.
-
- Use the `request_user_input` tool only for optional questions where the answer would materially improve the quality of the work.
-
- If `request_user_input` returns no answers, continue with best judgment instead of asking again or treating the turn as blocked.
-
- Never use the `request_user_input` tool for permission requests or permission-related escalations.
- </collaboration_mode>
-03:message/developer:
- <multi_agent_role>You are `/root`, the primary agent in a team of agents collaborating to fulfill the user's goals.
-
- At the start of your turn, you are the active agent.
- You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents.
- All agents in the team, including the agents that you can assign tasks to, are equally intelligent and capable, and have access to the same set of tools.
-
- You can use `spawn_agent` to create a new agent, `followup_task` to give an existing agent a new task an...message to a running agent without triggering a turn. [hash=7d40ff8b58977202]
- `send_message` calls may be read by a human, so ensure they are legible. Always put proper spaces between words and/or numbers.
- <OMITTED 17 LINES; ~246 TOKENS; hash=780031e2df907944>
- - All agents use the same current working directory.
- - As a result, edits made by one agent are immediately visible to all other agents.
-
- When calling `wait_agent`, prefer longer waits (minutes) to avoid busy polling.
-
- There are 4 available concurrency slots, meaning that up to 4 agents can be active at once, including you.
-
- Full-history forks (`fork_turns` omitted or `"all"`) inherit the parent model and reasoning effort and d...ne"` or a positive integer string.</multi_agent_role> [hash=c7f52e90688299ce]
-04:message/developer:
- <multi_agent_mode>Any earlier instruction enabling proactive multi-agent delegation no longer applies. D...elegation, or parallel agent work.</multi_agent_mode> [hash=2b6e037067b4390c]
-05:message/user:
- <environment_context>
- <cwd><CWD></cwd>
- <shell><HOST_SHELL></shell>
- <current_date><CURRENT_DATE></current_date>
- <timezone><HOST_TIMEZONE></timezone>
- <filesystem><workspace_roots><root><WORKSPACE_ROOT 1></root></workspace_roots><permission_profile type...e="unrestricted" /></permission_profile></filesystem> [hash=0592734c170299c1]
- </environment_context>
-06:message/user:
- Check whether the Notes plugin echo tool is available.
-07:custom_tool_call/exec:text(ALL_TOOLS.filter(({ name }) => name === "mcp__notes__echo").map(({ name }) => name));
-08:custom_tool_call_output:Script completed
- Wall time <DURATION> seconds
- Output:
- | []
09:message/assistant:
The Notes tool is not installed yet.
10:message/developer:
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_settings_release_check_tool_shapes.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_settings_release_check_tool_shapes.snap
index 438f1efa3f..755867034a 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_settings_release_check_tool_shapes.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_settings_release_check_tool_shapes.snap
@@ -16,8 +16,8 @@ Settings:
text: {"verbosity":"low"}
tool_choice: "auto"
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=7810769c6e12d379):
- - namespace/functions; hash=8c17932a39355f2d
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__code_mode_mcp_schema_limits.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__code_mode_mcp_schema_limits.snap
index c34c97ef03..64226b9179 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__code_mode_mcp_schema_limits.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__code_mode_mcp_schema_limits.snap
@@ -16,8 +16,8 @@ Settings:
stream: true
text: {"verbosity":"low"}
tool_choice: "auto"
- tools (4; hash=ee397215c4055252):
- - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=485f26f17d4a2899
+ tools (4; hash=95b65d00fe586b7d):
+ - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=e02c9856c9cd8430
- function/wait: Waits on a yielded `exec` cell and returns new output or completion. - Use `wait` only after `exe...; args=[cell_id, max_tokens, terminate, yield_time_ms]; hash=6692d8f6c55be489
- 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
- web_search; hash=e214d4db1bc49e89
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__compaction__remote_slash_compact.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__compaction__remote_slash_compact.snap
index 5c4a6f6cf7..ab2bf0b330 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__compaction__remote_slash_compact.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__compaction__remote_slash_compact.snap
@@ -16,8 +16,8 @@ Settings:
text: {"verbosity":"low"}
tool_choice: "auto"
-- request 1 (turn; Before /compact) --
-00:additional_tools/developer (3; hash=fe0dd2d6b97e53b8):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
@@ -115,8 +115,8 @@ Settings: unavailable (items only)
## Window 3 (after request 3: input diverged at item 00)
Settings: same as window 1
-- request 4 (turn; First turn after /compact) --
-00:additional_tools/developer (3; hash=fe0dd2d6b97e53b8):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=2c5a5b48dbcfce9b):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_agent_messages__encrypted_parent_reply_survives_incremental_guardian_reviews.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_agent_messages__encrypted_parent_reply_survives_incremental_guardian_reviews.snap
index 195e2a0dfa..2df41fb92d 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_agent_messages__encrypted_parent_reply_survives_incremental_guardian_reviews.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_agent_messages__encrypted_parent_reply_survives_incremental_guardian_reviews.snap
@@ -20,8 +20,8 @@ Scenario: An encrypted parent reply is delivered as a native agent message. Both
## Window 2 (after request 2: input diverged at item 00, settings changed (instructions, model, parallel_tool_calls, prompt_cache_key, reasoning, text, tools))
-- request 3 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
@@ -106,8 +106,8 @@ Scenario: An encrypted parent reply is delivered as a native agent message. Both
## Window 4 (after request 4: input diverged at item 00, settings changed (instructions, model, parallel_tool_calls, prompt_cache_key, reasoning, text, tools))
-- request 5 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_checkpoint_migration.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_checkpoint_migration.snap
index e99600e31e..fcf9b869e4 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_checkpoint_migration.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_checkpoint_migration.snap
@@ -50,8 +50,8 @@ Settings: relative to window 1
reasoning: {"context":"all_turns","effort":"medium"}
tools: <removed>
-- request 4 (turn) --
-00:additional_tools/developer (1; hash=77ff9904ddb4aedd):
- - namespace/functions; hash=99a6a9ccd0de2a13
+00:additional_tools/developer (1; hash=1ea3c73f7e3c8b33):
+ - namespace/functions; hash=2a9848b19a516663
- custom/exec
- function/wait
- function/request_user_input
@@ -79,8 +79,8 @@ Settings: relative to window 2
reasoning: {"context":"all_turns","effort":"low"}
text: {"format":{"name":"codex_output_schema","schema":{"additionalProperties":false,"properties":{"outcome":{"enum":["allow","deny"],"type":"string"},"rationale":{"type":"string"},"risk_level":{"enum":["low","medium","high","critical"],"type":"string"},"user_authorization":{"enum":["unknown","low","medium","high"],"type":"string"}},"required":["outcome"],"type":"object"},"strict":false,"type":"json_schema"},"verbosity":"low"}
-- request 6 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
@@ -187,8 +187,8 @@ Settings: relative to window 2
## Window 4 (after request 6: input diverged at item 00)
Settings: same as window 2
-- request 7 (turn) --
-00:additional_tools/developer (1; hash=77ff9904ddb4aedd):
- - namespace/functions; hash=99a6a9ccd0de2a13
+00:additional_tools/developer (1; hash=1ea3c73f7e3c8b33):
+ - namespace/functions; hash=2a9848b19a516663
- custom/exec
- function/wait
- function/request_user_input
@@ -216,8 +216,8 @@ Settings: same as window 2
## Window 5 (after request 8: input diverged at item 04)
Settings: same as window 2
-- request 9 (turn) --
-00:additional_tools/developer (1; hash=77ff9904ddb4aedd):
- - namespace/functions; hash=99a6a9ccd0de2a13
+00:additional_tools/developer (1; hash=1ea3c73f7e3c8b33):
+ - namespace/functions; hash=2a9848b19a516663
- custom/exec
- function/wait
- function/request_user_input
@@ -242,8 +242,8 @@ Settings: same as window 2
## Window 6 (after request 9: input diverged at item 00)
Settings: same as window 3
-- request 10 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
@@ -340,8 +340,8 @@ Settings: same as window 3
## Window 7 (after request 10: input diverged at item 00)
Settings: same as window 2
-- request 11 (turn) --
-00:additional_tools/developer (1; hash=77ff9904ddb4aedd):
- - namespace/functions; hash=99a6a9ccd0de2a13
+00:additional_tools/developer (1; hash=1ea3c73f7e3c8b33):
+ - namespace/functions; hash=2a9848b19a516663
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_code_mode_messaging.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_code_mode_messaging.snap
index a20212700f..3ce9aab364 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_code_mode_messaging.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_code_mode_messaging.snap
@@ -83,8 +83,8 @@ Scenario: A root uses Code Mode to send a confirmation and receives a real user
## Window 3 (after request 6: input diverged at item 00, settings changed (instructions, model, parallel_tool_calls, prompt_cache_key, reasoning, text, tools))
-- request 7 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
@@ -153,8 +153,8 @@ Scenario: A root uses Code Mode to send a confirmation and receives a real user
## Window 4 (after request 7: input diverged at item 04, settings changed (prompt_cache_key))
-- request 8 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_extra_policy__extra_policy_reaches_guardian_review.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_extra_policy__extra_policy_reaches_guardian_review.snap
index eb972c9a47..830dbb5753 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_extra_policy__extra_policy_reaches_guardian_review.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_extra_policy__extra_policy_reaches_guardian_review.snap
@@ -84,8 +84,8 @@ Settings: relative to window 1
text: {"format":{"name":"codex_output_schema","schema":{"additionalProperties":false,"properties":{"outcome":{"enum":["allow","deny"],"type":"string"},"rationale":{"type":"string"},"risk_level":{"enum":["low","medium","high","critical"],"type":"string"},"user_authorization":{"enum":["unknown","low","medium","high"],"type":"string"}},"required":["outcome"],"type":"object"},"strict":false,"type":"json_schema"},"verbosity":"low"}
tools: <removed>
-- request 2 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_handoff__guardian_handoff_delegation.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_handoff__guardian_handoff_delegation.snap
index 4a3c509576..72166903bb 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_handoff__guardian_handoff_delegation.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_handoff__guardian_handoff_delegation.snap
@@ -7,8 +7,8 @@ Scenario: Complete Guardian request history: root delegates through alpha to lea
## Window 1
-- request 1 (turn) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_heartbeat__heartbeat_repetitions_keep_later_human_authorization.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_heartbeat__heartbeat_repetitions_keep_later_human_authorization.snap
index 66ebfcd8c0..c00eefad15 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_heartbeat__heartbeat_repetitions_keep_later_human_authorization.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__guardian_heartbeat__heartbeat_repetitions_keep_later_human_authorization.snap
@@ -56,8 +56,8 @@ Scenario: Three scheduled runs share one instruction body, a human overrides its
## Window 2 (after request 5: input diverged at item 00, settings changed (instructions, model, parallel_tool_calls, prompt_cache_key, reasoning, text, tools))
-- request 6 (request) --
-00:additional_tools/developer (1; hash=a8891bdc414756a2):
- - namespace/functions; hash=af55b81b2cec6cc2
+00:additional_tools/developer (1; hash=65a86311792f6c71):
+ - namespace/functions; hash=dcfbcf0da1c2d607
- custom/exec
- function/wait
01:message/developer:
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snap
index 4cac8fa44c..7af84a0d9b 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__incremental_tools__incremental_tools.snap
@@ -18,8 +18,8 @@ Settings:
-- request 1 (turn) --
00:message/developer:
<MODEL_INSTRUCTIONS>
-01:additional_tools/developer (2; hash=1e63b25da7155640):
- - namespace/functions; hash=cc6eebc2891d0fea
+01:additional_tools/developer (2; hash=49f981f03ae5c5ce):
+ - namespace/functions; hash=cc6e8cf0e5405f3a
- custom/exec
- function/wait
- function/exec_command
@@ -44,8 +44,8 @@ Settings: relative to window 1
-- request 3 (turn) --
00:message/developer:
<MODEL_INSTRUCTIONS>
-01:additional_tools/developer (2; hash=1e63b25da7155640):
- - namespace/functions; hash=cc6eebc2891d0fea
+01:additional_tools/developer (2; hash=49f981f03ae5c5ce):
+ - namespace/functions; hash=cc6e8cf0e5405f3a
- custom/exec
- function/wait
- function/exec_command
@@ -62,8 +62,8 @@ Settings: relative to window 1
Begin work.
05:message/user:
Continue with the same tools.
-06:additional_tools/developer (1; hash=458b87f50d4f6057):
- - namespace/functions; hash=3045d6c5c31286d9
+06:additional_tools/developer (1; hash=26cd263a29587cc7):
+ - namespace/functions; hash=771cad2ff250d2f3
- custom/exec
07:message/developer:
<MODEL_SWITCH>
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__indirect_namespace_prefixes__catalog_indirect_namespace_prefixes.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__indirect_namespace_prefixes__catalog_indirect_namespace_prefixes.snap
index 47b71fd5f9..7748fe08d1 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__indirect_namespace_prefixes__catalog_indirect_namespace_prefixes.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__indirect_namespace_prefixes__catalog_indirect_namespace_prefixes.snap
@@ -16,8 +16,8 @@ Settings:
stream: true
text: {"verbosity":"low"}
tool_choice: "auto"
- tools (4; hash=045ecf3b2d3b6af5):
- - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=e9cdd499ac568220
+ tools (4; hash=a9bf6ab2694395ea):
+ - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=046e4cb99a803db9
- function/wait: Waits on a yielded `exec` cell and returns new output or completion. - Use `wait` only after `exe...; args=[cell_id, max_tokens, terminate, yield_time_ms]; hash=6692d8f6c55be489
- 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
- web_search; hash=e214d4db1bc49e89
@@ -48,8 +48,8 @@ Settings:
## Window 2 (after request 2)
Settings: relative to window 1
model: "prefixes-cleared"
- tools (4; hash=dec6fdcb7bf3fec7):
- ~ custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=39e1eedcbc703718
+ tools (4; hash=5aa602f8d0ed5702):
+ ~ custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=b1c19da7942f5c47
-- request 3 (turn) --
00:message/developer:
<PERMISSIONS_INSTRUCTIONS>
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_resource_messages__mcp_resource_messages.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_resource_messages__mcp_resource_messages.snap
index 3a7c7f38e1..6c534ca389 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_resource_messages__mcp_resource_messages.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__mcp_resource_messages__mcp_resource_messages.snap
@@ -32,8 +32,8 @@ Settings:
stream: true
text: {"verbosity":"low"}
tool_choice: "auto"
- tools (7; hash=4a2648ce3a65d327):
- - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=50ea9b7f60e145b5
+ tools (7; hash=221a8b190f48eeef):
+ - custom/exec: Run JavaScript code to orchestrate/compose tool calls - Evaluates the provided JavaScript code in...; hash=9ad48dbb5eac1f9b
- function/wait: Waits on a yielded `exec` cell and returns new output or completion. - Use `wait` only after `exe...; args=[cell_id, max_tokens, terminate, yield_time_ms]; hash=6692d8f6c55be489
- 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/request_user_input_async: Ask the user one or more questions during ongoing work. Use this tool only to request missing inf...; args=[questions]; hash=d6d74f33db330162
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_catalog_parameters.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_catalog_parameters.snap
index fd13c44123..76ab79bd27 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_catalog_parameters.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_catalog_parameters.snap
@@ -16,8 +16,8 @@ Settings:
text: {"verbosity":"low"}
tool_choice: "auto"
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=2c396104084747ac):
- - namespace/functions; hash=3a795ca1f0e0f332
+00:additional_tools/developer (3; hash=cc5df79824bafc21):
+ - namespace/functions; hash=fada4a476a3754dd
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__skill_catalog_dedup__dedup_before_budgeting.snap b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__skill_catalog_dedup__dedup_before_budgeting.snap
index 9a9777b3e5..449e2a34b6 100644
--- a/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__skill_catalog_dedup__dedup_before_budgeting.snap
+++ b/codex-rs/core/tests/suite/snapshots/all__suite__scenarios__skill_catalog_dedup__dedup_before_budgeting.snap
@@ -16,8 +16,8 @@ Settings:
text: {"verbosity":"low"}
tool_choice: "auto"
-- request 1 (turn) --
-00:additional_tools/developer (3; hash=5551438133509eec):
- - namespace/functions; hash=c60996290e7ef438
+00:additional_tools/developer (3; hash=b6ebf543280ec271):
+ - namespace/functions; hash=bd9e182b4235cdc1
- custom/exec
- function/wait
- function/request_user_input
diff --git a/codex-rs/core/tests/suite/step_settings.rs b/codex-rs/core/tests/suite/step_settings.rs
index 5334a593b7..51440d4757 100644
--- a/codex-rs/core/tests/suite/step_settings.rs
+++ b/codex-rs/core/tests/suite/step_settings.rs
@@ -2436,7 +2436,7 @@ async fn tool_messages_follow_mid_turn_model_changes() -> Result<()> {
.collect::<serde_json::Map<String, Value>>(),
"channel_post_description": format!("post description for {model}."),
"channel_post_required": ["text"],
- "exec_description": format!("Exec description for {model}."),
+ "exec_description": format!("Exec description for {model}.\n\nSome deferred nested tools may be omitted from this description. They are still available on the global `tools` object and listed in `ALL_TOOLS`.\nTo find one, filter `ALL_TOOLS` by `name` and `description`.\n\nTool availability can change between calls."),
"wait_description": format!("Wait description for {model}."),
"wait_parameters": wait_parameters(model),
}))