Gate plugin usage instructions by model capability (#36792)

## What changed

- Add `include_plugin_usage_instructions` to model metadata, defaulting to false.
- Emit generic plugin guidance only when plugins are available and the selected model enables it.
- Enable the capability for interactive model presets while leaving `codex-auto-review` opted out.

GitOrigin-RevId: 67f5a97e978033f5f1d533956c0b9deeae610283

codex-rs/app-server/tests/common/models_cache.rs

@@ -43,6 +43,7 @@ fn preset_to_info(preset: &ModelPreset, priority: i32) -> ModelInfo {
             token_budget: None,
         }),
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

codex-rs/app-server/tests/suite/v2/selected_capability_stack.rs

@@ -246,9 +246,9 @@ async fn selected_capability_stack_tracks_environment_availability_and_resume()
     for request in &requests[1..4] {
         assert_selected_skill_is_injected(request, /*expected_count*/ 1);
         assert_selected_plugin_tools(request);
-        assert_plugin_guidance_count(request, /*expected_count*/ 1);
+        assert_plugin_guidance_count(request, /*expected_count*/ 0);
     }
-    assert_plugin_guidance_count(&requests[4], /*expected_count*/ 1);
+    assert_plugin_guidance_count(&requests[4], /*expected_count*/ 0);
     assert_selected_skill_is_injected(&requests[5], /*expected_count*/ 2);
     assert_selected_plugin_tools(&requests[5]);
     let output = requests[2].function_call_output(MCP_CALL_ID);
@@ -417,9 +417,9 @@ async fn selected_capabilities_become_available_between_samples_in_one_turn() ->
     assert_eq!(3, requests.len());
     assert_selected_skill_catalog_available(&requests[1]);
     assert_selected_plugin_tools(&requests[1]);
-    assert_plugin_guidance_count(&requests[1], /*expected_count*/ 1);
+    assert_plugin_guidance_count(&requests[1], /*expected_count*/ 0);
     assert_selected_plugin_tools(&requests[2]);
-    assert_plugin_guidance_count(&requests[2], /*expected_count*/ 1);
+    assert_plugin_guidance_count(&requests[2], /*expected_count*/ 0);
     let output = requests[2].function_call_output(MCP_CALL_ID);
     let output = output["output"]
         .as_str()

codex-rs/codex-api/tests/models_integration.rs

@@ -81,6 +81,7 @@ async fn models_client_hits_models_endpoint() {
             upgrade: None,
             model_messages: None,
             include_skills_usage_instructions: false,
+            include_plugin_usage_instructions: false,
             supports_reasoning_summary_parameter: true,
             default_reasoning_summary: ReasoningSummary::Auto,
             support_verbosity: false,

codex-rs/core/src/session/world_state.rs

@@ -184,8 +184,10 @@ impl Session {
                 false
             };
         world_state.add_section(AppsInstructionsState::new(apps_available));
+        let plugins_usage_instructions_available = step_context.mcp.plugins_available()
+            && turn_context.model_info.include_plugin_usage_instructions;
         world_state.add_section(PluginsInstructionsState::new(
-            step_context.mcp.plugins_available(),
+            plugins_usage_instructions_available,
         ));
         if turn_context
             .config

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

@@ -270,6 +270,7 @@ fn remote_model_with_auto_review_override(slug: &str, review_model: &str) -> Mod
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

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

@@ -99,6 +99,7 @@ fn test_model_info(
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,
@@ -962,6 +963,7 @@ async fn model_switch_to_smaller_model_updates_token_context_window() -> Result<
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

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

@@ -512,6 +512,7 @@ fn test_remote_model(slug: &str, priority: i32) -> ModelInfo {
             token_budget: None,
         }),
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

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

@@ -647,6 +647,7 @@ async fn remote_model_friendly_personality_instructions_with_feature() -> anyhow
             token_budget: None,
         }),
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,
@@ -767,6 +768,7 @@ async fn user_turn_personality_remote_model_template_includes_update_message() -
             token_budget: None,
         }),
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

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

@@ -537,6 +537,7 @@ async fn remote_models_remote_model_uses_unified_exec() -> Result<()> {
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,
@@ -798,6 +799,7 @@ async fn remote_models_apply_legacy_instructions() -> Result<()> {
             token_budget: None,
         }),
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,
@@ -1372,6 +1374,7 @@ fn test_remote_model_with_policy(
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

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

@@ -2261,6 +2261,7 @@ async fn stdio_image_responses_are_sanitized_for_text_only_model() -> anyhow::Re
                 upgrade: None,
                 model_messages: None,
                 include_skills_usage_instructions: false,
+                include_plugin_usage_instructions: false,
                 supports_reasoning_summary_parameter: true,
                 default_reasoning_summary: ReasoningSummary::Auto,
                 support_verbosity: false,

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

@@ -80,6 +80,7 @@ fn test_model_info(
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

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

@@ -1372,6 +1372,7 @@ async fn view_image_tool_returns_unsupported_message_for_text_only_model() -> an
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

codex-rs/models-manager/models.json

@@ -21,6 +21,7 @@
       "multi_agent_version": "v2",
       "use_responses_lite": true,
       "include_skills_usage_instructions": false,
+      "include_plugin_usage_instructions": true,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 272000,
@@ -134,6 +135,7 @@
       "multi_agent_version": "v2",
       "use_responses_lite": true,
       "include_skills_usage_instructions": false,
+      "include_plugin_usage_instructions": true,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 272000,
@@ -245,6 +247,7 @@
       "multi_agent_version": "v1",
       "use_responses_lite": true,
       "include_skills_usage_instructions": false,
+      "include_plugin_usage_instructions": true,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 272000,
@@ -352,6 +355,7 @@
       "multi_agent_version": null,
       "use_responses_lite": false,
       "include_skills_usage_instructions": true,
+      "include_plugin_usage_instructions": true,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 272000,
@@ -457,6 +461,7 @@
       "multi_agent_version": null,
       "use_responses_lite": false,
       "include_skills_usage_instructions": true,
+      "include_plugin_usage_instructions": true,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 1000000,
@@ -560,6 +565,7 @@
       "multi_agent_version": null,
       "use_responses_lite": false,
       "include_skills_usage_instructions": true,
+      "include_plugin_usage_instructions": true,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 272000,
@@ -658,6 +664,7 @@
       "multi_agent_version": null,
       "use_responses_lite": false,
       "include_skills_usage_instructions": true,
+      "include_plugin_usage_instructions": true,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 272000,
@@ -753,6 +760,7 @@
       "multi_agent_version": null,
       "use_responses_lite": false,
       "include_skills_usage_instructions": true,
+      "include_plugin_usage_instructions": false,
       "auto_review_model_override": null,
       "context_window": 272000,
       "max_context_window": 1000000,

codex-rs/models-manager/src/model_info.rs

@@ -154,6 +154,7 @@ pub fn model_info_from_slug(slug: &str) -> ModelInfo {
         upgrade: None,
         model_messages: Some(local_model_messages_for_slug(slug)),
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: ReasoningSummary::Auto,
         support_verbosity: false,

codex-rs/protocol/src/openai_models.rs

@@ -390,6 +390,8 @@ pub struct ModelInfo {
     pub model_messages: Option<ModelMessages>,
     #[serde(default)]
     pub include_skills_usage_instructions: bool,
+    #[serde(default)]
+    pub include_plugin_usage_instructions: bool,
     /// Whether the model accepts the Responses API `reasoning.summary` parameter.
     #[serde(default = "default_true", skip_serializing_if = "is_true")]
     pub supports_reasoning_summary_parameter: bool,
@@ -823,6 +825,7 @@ mod tests {
             upgrade: None,
             model_messages: spec,
             include_skills_usage_instructions: false,
+            include_plugin_usage_instructions: false,
             supports_reasoning_summary_parameter: true,
             default_reasoning_summary: ReasoningSummary::Auto,
             support_verbosity: false,
@@ -1414,6 +1417,7 @@ mod tests {
             vec![InputModality::Text, InputModality::Image]
         );
         assert!(!model.include_skills_usage_instructions);
+        assert!(!model.include_plugin_usage_instructions);
         assert!(model.supports_reasoning_summary_parameter);
         assert!(!model.supports_image_detail_original);
         assert_eq!(model.web_search_tool_type, WebSearchToolType::Text);

codex-rs/tools/src/tool_config_tests.rs

@@ -27,6 +27,7 @@ fn model_with_shell_type(shell_type: ConfigShellToolType) -> ModelInfo {
         upgrade: None,
         model_messages: None,
         include_skills_usage_instructions: false,
+        include_plugin_usage_instructions: false,
         supports_reasoning_summary_parameter: true,
         default_reasoning_summary: Default::default(),
         support_verbosity: false,