Clarify V2 spawn model override guidance for context catalogs (#49786)

## What changed

When the model catalog is provided in context and model overrides are exposed, tell V2 `spawn_agent` callers to inherit the current model unless the user explicitly asks for a different model. Include this guidance even when spawn metadata is hidden.

## Testing

Extend tool-description tests to cover hidden metadata with both inline and context catalogs, and update request-level assertions for V1 and V2 model override guidance.

GitOrigin-RevId: b70b0f09b0b5987a0eccba578196b8ef7cee4baf

codex-rs/core/src/tools/handlers/multi_agents_spec.rs

@@ -15,6 +15,7 @@ pub const MULTI_AGENT_V1_NAMESPACE: &str = "multi_agent_v1";
 const MULTI_AGENT_V1_NAMESPACE_DESCRIPTION: &str = "Tools for spawning and managing sub-agents.";
 
 const SPAWN_AGENT_INHERITED_MODEL_GUIDANCE: &str = "Spawned agents inherit your current model by default. Omit `model` to use that preferred default; set `model` only when an explicit override is needed.";
+const SPAWN_AGENT_INHERITED_MODEL_GUIDANCE_V2: &str = "Spawned agents inherit your current model by default. Do not set the `model` field unless the user explicitly asks for a different model.";
 const SPAWN_AGENT_MODEL_CATALOG_GUIDANCE: &str =
     "Pick model overrides from the latest <model_catalog> listing.";
 const SPAWN_AGENT_TYPE_OVERRIDE_DESCRIPTION_V1: &str = "Agent type override for the new agent. Omit to inherit the parent agent type with a full-history fork; otherwise, `default` is used.";
@@ -113,9 +114,14 @@ pub fn create_spawn_agent_tool_v2(
         .then(|| {
             spawn_agent_models_description(&options.available_models, options.multi_agent_version)
         });
-    let inherited_model_guidance = (options.expose_spawn_agent_model_overrides
-        && !options.hide_agent_type_model_reasoning)
-        .then_some(SPAWN_AGENT_INHERITED_MODEL_GUIDANCE);
+    let inherited_model_guidance = if options.model_catalog_in_context {
+        options
+            .expose_spawn_agent_model_overrides
+            .then_some(SPAWN_AGENT_INHERITED_MODEL_GUIDANCE_V2)
+    } else {
+        (options.expose_spawn_agent_model_overrides && !options.hide_agent_type_model_reasoning)
+            .then_some(SPAWN_AGENT_INHERITED_MODEL_GUIDANCE)
+    };
     let mut properties = spawn_agent_common_properties_v2(&options.agent_type_description);
     if !options.expose_agent_type {
         properties.remove("agent_type");

codex-rs/core/src/tools/handlers/multi_agents_spec_tests.rs

@@ -163,14 +163,18 @@ fn spawn_agent_tool_v1_keeps_legacy_fork_context_field() {
     assert!(!properties.contains_key("service_tier"));
 }
 
-#[test]
-fn spawn_agent_tool_keeps_model_controls_when_spawn_metadata_is_hidden() {
+#[test_case::test_case(false; "inline_catalog")]
+#[test_case::test_case(true; "context_catalog")]
+fn spawn_agent_tool_keeps_model_controls_when_spawn_metadata_is_hidden(
+    model_catalog_in_context: bool,
+) {
     let tool = create_spawn_agent_tool_v2(
         SpawnAgentToolOptions {
             agent_type_description: "role help".to_string(),
             expose_agent_type: false,
             hide_agent_type_model_reasoning: true,
             expose_spawn_agent_model_overrides: true,
+            model_catalog_in_context,
             usage_hint_text: None,
             ..Default::default()
         },
@@ -195,6 +199,10 @@ fn spawn_agent_tool_keeps_model_controls_when_spawn_metadata_is_hidden() {
     assert!(properties.contains_key("reasoning_effort"));
     assert!(!properties.contains_key("service_tier"));
     assert!(!description.contains(SPAWN_AGENT_INHERITED_MODEL_GUIDANCE));
+    assert_eq!(
+        description.contains(SPAWN_AGENT_INHERITED_MODEL_GUIDANCE_V2),
+        model_catalog_in_context
+    );
 }
 
 #[test]

codex-rs/core/tests/suite/spawn_agent_description.rs

@@ -282,20 +282,24 @@ pub(super) async fn model_catalog_refresh_requests(
         description.contains("- `visible-model`: Fast and capable"),
         !model_catalog_in_context
     );
+    let expected_inherited_model_guidance = if multi_agent_version == MultiAgentVersion::V2
+        && model_catalog_in_context
+    {
+        "Spawned agents inherit your current model by default. Do not set the `model` field unless the user explicitly asks for a different model."
+    } else {
+        "Spawned agents inherit your current model by default. Omit `model` to use that preferred default; set `model` only when an explicit override is needed."
+    };
     assert!(
-        description.contains(
-            "Spawned agents inherit your current model by default. Omit `model` to use that preferred default; set `model` only when an explicit override is needed."
-        ),
+        description.contains(expected_inherited_model_guidance),
         "expected inherited-model guidance in spawn_agent description: {description:?}"
     );
-    if multi_agent_version == MultiAgentVersion::V1 {
-        assert!(
+    assert_eq!(
         description.contains(
             "Do not set the `model` field unless the user explicitly asks for a different model."
         ),
+        multi_agent_version == MultiAgentVersion::V1 || model_catalog_in_context,
         "expected model override usage guidance in spawn_agent description: {description:?}"
     );
-    }
     assert!(
         listing.contains("Reasoning efforts: low, medium (default), high."),
         "expected default reasoning effort in model catalog: {catalog:?}"