feat(multi-agent): allow portable plaintext messages

Author: jingx8885

codex-rs/core/config.schema.json

@@ -1768,6 +1768,10 @@
         "enabled": {
           "type": "boolean"
         },
+        "encrypt_inter_agent_messages": {
+          "description": "Encrypt inter-agent message fields using the OpenAI Responses extension. Disable this for providers that only implement the portable Responses schema. When disabled without an explicit tool namespace, the client uses `agents`.",
+          "type": "boolean"
+        },
         "expose_spawn_agent_model_overrides": {
           "description": "Exposes `model` and `reasoning_effort` on the multi-agent v2 spawn tool and adds corresponding guidance to root and subagent usage hints.",
           "type": "boolean"

codex-rs/core/src/client.rs

@@ -80,6 +80,7 @@ use codex_protocol::config_types::ReasoningSummary as ReasoningSummaryConfig;
 use codex_protocol::config_types::Verbosity as VerbosityConfig;
 use codex_protocol::models::ContentItem;
 use codex_protocol::models::ResponseItem;
+use codex_protocol::models::plaintext_agent_message_content;
 use codex_protocol::openai_models::ModelInfo;
 use codex_protocol::openai_models::ReasoningEffort as ReasoningEffortConfig;
 use codex_protocol::protocol::InternalSessionSource;
@@ -835,6 +836,23 @@ impl ModelClient {
             input
                 .iter_mut()
                 .for_each(ResponseItem::clear_internal_chat_message_metadata_passthrough);
+            input = input
+                .into_iter()
+                .map(|item| {
+                    if let ResponseItem::AgentMessage { content, .. } = &item
+                        && let Some(text) = plaintext_agent_message_content(content)
+                    {
+                        return ResponseItem::Message {
+                            id: None,
+                            role: "user".to_string(),
+                            content: vec![ContentItem::InputText { text }],
+                            phase: None,
+                            internal_chat_message_metadata_passthrough: None,
+                        };
+                    }
+                    item
+                })
+                .collect();
         }
         let tools = create_tools_json_for_responses_api(&prompt.tools)?;
         let (instructions, tools) = if model_info.use_responses_lite {

codex-rs/core/src/config/config_tests.rs

@@ -10603,6 +10603,7 @@ tool_namespace = "agents"
 hide_spawn_agent_metadata = true
 expose_spawn_agent_model_overrides = false
 non_code_mode_only = true
+encrypt_inter_agent_messages = false
 
 [agents]
 max_concurrent_threads_per_session = 9
@@ -10650,6 +10651,7 @@ max_concurrent_threads_per_session = 9
     assert!(config.multi_agent_v2.hide_spawn_agent_metadata);
     assert!(!config.multi_agent_v2.expose_spawn_agent_model_overrides);
     assert!(config.multi_agent_v2.non_code_mode_only);
+    assert!(!config.multi_agent_v2.encrypt_inter_agent_messages);
 
     Ok(())
 }
@@ -10674,6 +10676,7 @@ enabled = true
         config.multi_agent_v2,
         resolve_multi_agent_v2_config(&ConfigToml::default())
     );
+    assert!(config.multi_agent_v2.encrypt_inter_agent_messages);
     assert_eq!(
         (
             config.agent_max_threads,
@@ -10685,6 +10688,32 @@ enabled = true
     Ok(())
 }
 
+#[tokio::test]
+async fn multi_agent_v2_plaintext_defaults_to_non_reserved_tool_namespace() -> std::io::Result<()> {
+    let codex_home = TempDir::new()?;
+    std::fs::write(
+        codex_home.path().join(CONFIG_TOML_FILE),
+        r#"[features.multi_agent_v2]
+enabled = true
+encrypt_inter_agent_messages = false
+"#,
+    )?;
+
+    let config = ConfigBuilder::without_managed_config_for_tests()
+        .codex_home(codex_home.path().to_path_buf())
+        .fallback_cwd(Some(codex_home.path().to_path_buf()))
+        .build()
+        .await?;
+
+    assert_eq!(
+        config.multi_agent_v2.tool_namespace.as_deref(),
+        Some("agents")
+    );
+    assert!(!config.multi_agent_v2.encrypt_inter_agent_messages);
+
+    Ok(())
+}
+
 #[test]
 fn multi_agent_v2_default_usage_hints_use_configured_thread_cap() {
     let config_toml = toml::from_str(

codex-rs/core/src/config/mod.rs

@@ -250,6 +250,7 @@ You may also see them addressed as to=/root/..., which indicates your identity i
 "#;
 const DEFAULT_MULTI_AGENT_V2_MODEL_OVERRIDE_USAGE_HINT_TEXT: &str = "Full-history forks (`fork_turns` omitted or `\"all\"`) inherit the parent model and reasoning effort and do not accept overrides. Only set `model` or `reasoning_effort` when explicitly requested by the user, applicable `AGENTS.md` instructions, or skill instructions; when doing so, set `fork_turns` to `\"none\"` or a positive integer string.";
 const DEFAULT_MULTI_AGENT_V2_TOOL_NAMESPACE: &str = "collaboration";
+const DEFAULT_MULTI_AGENT_V2_PLAINTEXT_TOOL_NAMESPACE: &str = "agents";
 const DEFAULT_MULTI_AGENT_V2_SHARED_USAGE_HINT_TEXT: &str = r#"Note that collaboration tools cannot be called from inside `functions.exec`. Call `spawn_agent`, `send_message`, `followup_task`, `wait_agent`, `interrupt_agent`, and `list_agents` only as direct tool calls using the recipient shown in their tool definitions, such as `to=functions.collaboration.spawn_agent`, since they are intentionally absent from the `functions.exec` `tools.*` namespace. Available tools in `functions.exec` are explicitly described with a `tools` namespace in the developer message.
 
 All agents share the same directory. In detail:
@@ -1178,6 +1179,7 @@ pub struct MultiAgentV2Config {
     pub hide_spawn_agent_metadata: bool,
     pub expose_spawn_agent_model_overrides: bool,
     pub non_code_mode_only: bool,
+    pub encrypt_inter_agent_messages: bool,
 }
 
 impl MultiAgentV2Config {
@@ -1201,6 +1203,7 @@ impl MultiAgentV2Config {
             hide_spawn_agent_metadata: true,
             expose_spawn_agent_model_overrides: true,
             non_code_mode_only: true,
+            encrypt_inter_agent_messages: true,
         }
     }
 }
@@ -2592,13 +2595,20 @@ fn resolve_multi_agent_v2_config(config_toml: &ConfigToml) -> MultiAgentV2Config
         .and_then(|config| config.multi_agent_mode_hint_text.as_ref())
         .cloned()
         .or(default.multi_agent_mode_hint_text);
+    let non_code_mode_only = base
+        .and_then(|config| config.non_code_mode_only)
+        .unwrap_or(default.non_code_mode_only);
+    let encrypt_inter_agent_messages = base
+        .and_then(|config| config.encrypt_inter_agent_messages)
+        .unwrap_or(default.encrypt_inter_agent_messages);
     let tool_namespace = base
         .and_then(|config| config.tool_namespace.as_ref())
         .cloned()
+        .or_else(|| {
+            (!encrypt_inter_agent_messages)
+                .then(|| DEFAULT_MULTI_AGENT_V2_PLAINTEXT_TOOL_NAMESPACE.to_string())
+        })
         .or(default.tool_namespace);
-    let non_code_mode_only = base
-        .and_then(|config| config.non_code_mode_only)
-        .unwrap_or(default.non_code_mode_only);
 
     MultiAgentV2Config {
         max_concurrent_threads_per_session,
@@ -2613,6 +2623,7 @@ fn resolve_multi_agent_v2_config(config_toml: &ConfigToml) -> MultiAgentV2Config
         hide_spawn_agent_metadata,
         expose_spawn_agent_model_overrides,
         non_code_mode_only,
+        encrypt_inter_agent_messages,
     }
 }
 

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

@@ -31,6 +31,23 @@ pub struct SpawnAgentToolOptions {
     pub expose_spawn_agent_model_overrides: bool,
     pub multi_agent_version: MultiAgentVersion,
     pub usage_hint_text: Option<String>,
+    pub message_format: InterAgentMessageFormat,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum InterAgentMessageFormat {
+    Encrypted,
+    Plaintext,
+}
+
+impl InterAgentMessageFormat {
+    pub fn from_encryption_enabled(enabled: bool) -> Self {
+        if enabled {
+            Self::Encrypted
+        } else {
+            Self::Plaintext
+        }
+    }
 }
 
 impl Default for SpawnAgentToolOptions {
@@ -43,6 +60,7 @@ impl Default for SpawnAgentToolOptions {
             expose_spawn_agent_model_overrides: false,
             multi_agent_version: MultiAgentVersion::Disabled,
             usage_hint_text: None,
+            message_format: InterAgentMessageFormat::Encrypted,
         }
     }
 }
@@ -106,7 +124,8 @@ pub fn create_spawn_agent_tool_v2(options: SpawnAgentToolOptions) -> ToolSpec {
     let inherited_model_guidance = (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);
+    let mut properties =
+        spawn_agent_common_properties_v2(&options.agent_type_description, options.message_format);
     if !options.expose_agent_type {
         properties.remove("agent_type");
     }
@@ -183,7 +202,7 @@ pub fn create_send_input_tool_v1() -> ToolSpec {
     })
 }
 
-pub fn create_send_message_tool() -> ToolSpec {
+pub fn create_send_message_tool(message_format: InterAgentMessageFormat) -> ToolSpec {
     let properties = BTreeMap::from([
         (
             "target".to_string(),
@@ -193,10 +212,10 @@ pub fn create_send_message_tool() -> ToolSpec {
         ),
         (
             "message".to_string(),
-            JsonSchema::string(Some(
-                "Message text to queue on the target agent.".to_string(),
-            ))
-            .with_encrypted(),
+            inter_agent_message_schema(
+                "Message text to queue on the target agent.",
+                message_format,
+            ),
         ),
     ]);
 
@@ -215,7 +234,7 @@ pub fn create_send_message_tool() -> ToolSpec {
     })
 }
 
-pub fn create_followup_task_tool() -> ToolSpec {
+pub fn create_followup_task_tool(message_format: InterAgentMessageFormat) -> ToolSpec {
     let properties = BTreeMap::from([
         (
             "target".to_string(),
@@ -226,10 +245,7 @@ pub fn create_followup_task_tool() -> ToolSpec {
         ),
         (
             "message".to_string(),
-            JsonSchema::string(Some(
-                "Message text to send to the target agent.".to_string(),
-            ))
-            .with_encrypted(),
+            inter_agent_message_schema("Message text to send to the target agent.", message_format),
         ),
     ]);
 
@@ -628,14 +644,28 @@ fn spawn_agent_common_properties_v1(agent_type_description: &str) -> BTreeMap<St
     ])
 }
 
-fn spawn_agent_common_properties_v2(agent_type_description: &str) -> BTreeMap<String, JsonSchema> {
+fn inter_agent_message_schema(
+    description: &str,
+    message_format: InterAgentMessageFormat,
+) -> JsonSchema {
+    let schema = JsonSchema::string(Some(description.to_string()));
+    match message_format {
+        InterAgentMessageFormat::Encrypted => schema.with_encrypted(),
+        InterAgentMessageFormat::Plaintext => schema,
+    }
+}
+
+fn spawn_agent_common_properties_v2(
+    agent_type_description: &str,
+    message_format: InterAgentMessageFormat,
+) -> BTreeMap<String, JsonSchema> {
     BTreeMap::from([
         (
             "message".to_string(),
-            JsonSchema::string(Some(
-                "Initial plain-text task for the new agent.".to_string(),
-            ))
-            .with_encrypted(),
+            inter_agent_message_schema(
+                "Initial plain-text task for the new agent.",
+                message_format,
+            ),
         ),
         (
             "agent_type".to_string(),

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

@@ -53,6 +53,7 @@ fn spawn_agent_tool_v2_requires_task_name_and_lists_visible_models() {
         expose_spawn_agent_model_overrides: true,
         multi_agent_version: MultiAgentVersion::V2,
         usage_hint_text: None,
+        message_format: InterAgentMessageFormat::Encrypted,
     });
 
     let ToolSpec::Function(ResponsesApiTool {
@@ -134,6 +135,7 @@ fn spawn_agent_tool_v1_keeps_legacy_fork_context_field() {
         expose_spawn_agent_model_overrides: true,
         multi_agent_version: MultiAgentVersion::V1,
         usage_hint_text: None,
+        message_format: InterAgentMessageFormat::Encrypted,
     });
 
     let ToolSpec::Namespace(namespace) = tool else {
@@ -199,6 +201,7 @@ fn spawn_agent_tool_caps_visible_model_summaries() {
         expose_spawn_agent_model_overrides: true,
         multi_agent_version: MultiAgentVersion::V2,
         usage_hint_text: None,
+        message_format: InterAgentMessageFormat::Encrypted,
     });
 
     let ToolSpec::Function(ResponsesApiTool { description, .. }) = tool else {
@@ -245,6 +248,7 @@ fn spawn_agent_tool_keeps_model_controls_when_spawn_metadata_is_hidden() {
         expose_spawn_agent_model_overrides: true,
         multi_agent_version: MultiAgentVersion::V2,
         usage_hint_text: None,
+        message_format: InterAgentMessageFormat::Encrypted,
     });
 
     let ToolSpec::Function(ResponsesApiTool {
@@ -278,6 +282,7 @@ fn spawn_agent_tool_hides_model_controls_without_override_exposure() {
         expose_spawn_agent_model_overrides: false,
         multi_agent_version: MultiAgentVersion::V2,
         usage_hint_text: None,
+        message_format: InterAgentMessageFormat::Encrypted,
     });
 
     let ToolSpec::Function(ResponsesApiTool {
@@ -306,7 +311,7 @@ fn send_message_tool_requires_message_and_has_no_output_schema() {
         parameters,
         output_schema,
         ..
-    }) = create_send_message_tool()
+    }) = create_send_message_tool(InterAgentMessageFormat::Encrypted)
     else {
         panic!("send_message should be a function tool");
     };
@@ -341,6 +346,21 @@ fn send_message_tool_requires_message_and_has_no_output_schema() {
     assert_eq!(output_schema, None);
 }
 
+#[test]
+fn send_message_tool_can_expose_portable_plaintext_schema() {
+    let ToolSpec::Function(ResponsesApiTool { parameters, .. }) =
+        create_send_message_tool(InterAgentMessageFormat::Plaintext)
+    else {
+        panic!("send_message should be a function tool");
+    };
+    let message = parameters
+        .properties
+        .as_ref()
+        .and_then(|properties| properties.get("message"))
+        .expect("send_message should define message");
+    assert_eq!(message.encrypted, None);
+}
+
 #[test]
 fn followup_task_tool_requires_message_and_has_no_output_schema() {
     let ToolSpec::Function(ResponsesApiTool {
@@ -349,7 +369,7 @@ fn followup_task_tool_requires_message_and_has_no_output_schema() {
         parameters,
         output_schema,
         ..
-    }) = create_followup_task_tool()
+    }) = create_followup_task_tool(InterAgentMessageFormat::Encrypted)
     else {
         panic!("followup_task should be a function tool");
     };