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

## Why

Tool availability can change between calls. Conditioning discovery guidance on whether deferred tools are currently present changes the `exec` description when the catalog changes.

## What changed

Always include the configured discovery guidance in the Code Mode `exec` description, even when no deferred tools are present. The default guidance explains how to find tools in `ALL_TOOLS` and notes that availability can change between calls. Custom guidance and explicit empty overrides remain supported.

## Testing

Add regression coverage for stable guidance with empty and populated deferred tool catalogs in both Code Mode configurations, including custom and empty overrides. Update tool-description assertions and request snapshots.

GitOrigin-RevId: 086ea19a48e3c51ec8c429a619676a936d658721

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");

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"));
+}

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:

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:

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",

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

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

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

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

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

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

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

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

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:

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

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

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

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:

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

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:

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:

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:

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:

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>

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>

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

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

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

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),
             }))