agent/codex
2
0
Fork 0
mirror of https://github.com/pchuan98/codex.git synced 2026-07-01 00:31:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Encrypt multi-agent v2 message payloads (#26210)

Browse Source 
## Why

Multi-agent v2 currently routes agent instructions through normal tool
arguments and inter-agent context. That means the parent model can emit
plaintext task text, Codex can persist it in history/rollouts, and the
recipient can receive it as ordinary assistant-message JSON.

This changes the v2 path so agent instructions stay encrypted between
model calls: Responses encrypts the `message` argument returned by the
model, Codex forwards only that ciphertext, and Responses decrypts it
internally for the recipient model.

## What changed

- Mark the v2 `message` parameter as encrypted for `spawn_agent`,
`send_message`, and `followup_task`.
- Treat multi-agent v2 tool `message` values as ciphertext
unconditionally.
- Store v2 inter-agent task text in
`InterAgentCommunication.encrypted_content` with empty plaintext
`content`.
- Convert encrypted inter-agent communications into the Responses
`agent_message` input item before sending the child request.
- Preserve `agent_message` items across history, rollout, compaction,
telemetry, and app-server schema paths.
- Leave multi-agent v1 unchanged.

## Message shape

The model still calls the v2 tools with a `message` argument, but that
value is now ciphertext:

```json
{
  "name": "spawn_agent",
  "arguments": {
    "task_name": "worker",
    "message": "<ciphertext>"
  }
}
```

Codex stores the task as encrypted inter-agent communication:

```json
{
  "author": "/root",
  "recipient": "/root/worker",
  "content": "",
  "encrypted_content": "<ciphertext>",
  "trigger_turn": true
}
```

When Codex builds the recipient request, it forwards the ciphertext
using the new Responses input item:

```json
{
  "type": "agent_message",
  "author": "/root",
  "recipient": "/root/worker",
  "content": [
    {
      "type": "encrypted_content",
      "encrypted_content": "<ciphertext>"
    }
  ]
}
```

Responses decrypts that item internally for the recipient model.

## Context impact

- Parent context no longer carries plaintext v2 agent task instructions
from these tool arguments.
- Codex rollout/history stores ciphertext for v2 agent instructions.
- Recipient requests receive an `agent_message` item instead of
assistant commentary JSON for encrypted task delivery.
- Plaintext completion/status notifications are still plaintext because
they are Codex-generated status messages, not encrypted model tool
arguments.

## Validation

- `just test -p codex-tools`
- `just test -p codex-protocol`
- `just test -p codex-rollout`
- `just test -p codex-rollout-trace`
- `just test -p codex-otel`
- `just write-app-server-schema`
This commit is contained in:
jif
2026-06-05 10:25:57 +02:00
committed by GitHub
parent 6a6a5f925e
commit 5f4d06ef18
34 changed files with 674 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
codex-rs/core/src/agent/control.rs
+32 -7
View File
@@ -109,7 +109,8 @@ fn keep_forked_rollout_item(item: &RolloutItem, preserve_reference_context_item:
_ => false,
},
RolloutItem::ResponseItem(
ResponseItem::Reasoning { .. }
ResponseItem::AgentMessage { .. }
| ResponseItem::Reasoning { .. }
| ResponseItem::LocalShellCall { .. }
| ResponseItem::FunctionCall { .. }
| ResponseItem::ToolSearchCall { .. }
@@ -715,7 +716,12 @@ impl AgentControl {
agent_id: ThreadId,
initial_operation: Op,
) -> CodexResult<String> {
let last_task_message = render_input_preview(&initial_operation);
let last_task_message = match &initial_operation {
Op::InterAgentCommunication { communication } => {
last_task_message_from_communication(communication)
}
_ => non_empty_task_message(render_input_preview(&initial_operation)),
};
let state = self.upgrade()?;
let result = self
.handle_thread_request_result(
@@ -725,8 +731,12 @@ impl AgentControl {
)
.await;
if result.is_ok() {
self.state
.update_last_task_message(agent_id, last_task_message);
match last_task_message {
Some(last_task_message) => self
.state
.update_last_task_message(agent_id, last_task_message),
None => self.state.clear_last_task_message(agent_id),
}
}
result
}
@@ -736,7 +746,7 @@ impl AgentControl {
agent_id: ThreadId,
communication: InterAgentCommunication,
) -> CodexResult<String> {
let last_task_message = communication.content.clone();
let last_task_message = last_task_message_from_communication(&communication);
let state = self.upgrade()?;
let result = self
.handle_thread_request_result(
@@ -748,8 +758,12 @@ impl AgentControl {
)
.await;
if result.is_ok() {
self.state
.update_last_task_message(agent_id, last_task_message);
match last_task_message {
Some(last_task_message) => self
.state
.update_last_task_message(agent_id, last_task_message),
None => self.state.clear_last_task_message(agent_id),
}
}
result
}
@@ -1329,6 +1343,17 @@ pub(crate) fn render_input_preview(initial_operation: &Op) -> String {
}
}
fn last_task_message_from_communication(communication: &InterAgentCommunication) -> Option<String> {
if communication.encrypted_content.is_some() {
return None;
}
non_empty_task_message(communication.content.clone())
}
fn non_empty_task_message(message: String) -> Option<String> {
(!message.is_empty()).then_some(message)
}
fn thread_spawn_depth(session_source: &SessionSource) -> Option<i32> {
match session_source {
SessionSource::SubAgent(SubAgentSource::ThreadSpawn { depth, .. }) => Some(*depth),
codex-rs/core/src/agent/control_tests.rs
+56
View File
@@ -527,6 +527,62 @@ async fn send_inter_agent_communication_without_turn_queues_message_without_trig
));
}
#[tokio::test]
async fn encrypted_inter_agent_communication_clears_existing_last_task_message() {
let harness = AgentControlHarness::new().await;
let (parent_thread_id, _) = harness.start_thread().await;
let agent_path = AgentPath::try_from("/root/worker").expect("agent path");
let spawned_agent = harness
.control
.spawn_agent_with_metadata(
harness.config.clone(),
text_input("old plaintext task"),
Some(SessionSource::SubAgent(SubAgentSource::ThreadSpawn {
parent_thread_id,
depth: 1,
agent_path: Some(agent_path.clone()),
agent_nickname: None,
agent_role: None,
})),
SpawnAgentOptions {
parent_thread_id: Some(parent_thread_id),
..Default::default()
},
)
.await
.expect("spawn_agent should succeed");
assert_eq!(
harness
.control
.state
.agent_metadata_for_thread(spawned_agent.thread_id)
.and_then(|metadata| metadata.last_task_message),
Some("old plaintext task".to_string())
);
let communication = InterAgentCommunication::new_encrypted(
AgentPath::root(),
agent_path,
Vec::new(),
"encrypted-task".to_string(),
/*trigger_turn*/ true,
);
harness
.control
.send_inter_agent_communication(spawned_agent.thread_id, communication)
.await
.expect("send_inter_agent_communication should succeed");
assert_eq!(
harness
.control
.state
.agent_metadata_for_thread(spawned_agent.thread_id)
.and_then(|metadata| metadata.last_task_message),
None
);
}
#[tokio::test]
async fn spawn_agent_creates_thread_and_sends_prompt() {
let harness = AgentControlHarness::new().await;
codex-rs/core/src/agent/registry.rs
+14
View File
@@ -180,6 +180,20 @@ impl AgentRegistry {
}
}
pub(crate) fn clear_last_task_message(&self, thread_id: ThreadId) {
let mut active_agents = self
.active_agents
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if let Some(metadata) = active_agents
.agent_tree
.values_mut()
.find(|metadata| metadata.agent_id == Some(thread_id))
{
metadata.last_task_message = None;
}
}
fn register_spawned_thread(&self, agent_metadata: AgentMetadata) {
let Some(thread_id) = agent_metadata.agent_id else {
return;
codex-rs/core/src/client_common.rs
+17 -1
View File
@@ -3,6 +3,7 @@ use codex_config::types::Personality;
use codex_protocol::error::Result;
use codex_protocol::models::BaseInstructions;
use codex_protocol::models::ResponseItem;
use codex_protocol::protocol::InterAgentCommunication;
use codex_tools::ToolSpec;
use futures::Stream;
use serde_json::Value;
@@ -53,7 +54,22 @@ impl Default for Prompt {
impl Prompt {
pub(crate) fn get_formatted_input(&self) -> Vec<ResponseItem> {
self.input.clone()
self.input
.iter()
.cloned()
.map(|item| {
let ResponseItem::Message { role, content, .. } = &item else {
return item;
};
if role != "assistant" {
return item;
}
InterAgentCommunication::from_message_content(content)
.filter(|communication| communication.encrypted_content.is_some())
.map(|communication| communication.to_model_input_item())
.unwrap_or(item)
})
.collect()
}
}
codex-rs/core/src/compact_remote.rs
+1
View File
@@ -348,6 +348,7 @@ pub(crate) fn should_keep_compacted_history_item(item: &ResponseItem) -> bool {
}
ResponseItem::Message { role, .. } if role == "assistant" => true,
ResponseItem::Message { .. } => false,
ResponseItem::AgentMessage { .. } => true,
ResponseItem::Compaction { .. } | ResponseItem::ContextCompaction { .. } => true,
ResponseItem::CompactionTrigger => false,
ResponseItem::Reasoning { .. }
codex-rs/core/src/context_manager/history.rs
+7 -1
View File
@@ -386,6 +386,7 @@ impl ContextManager {
output: truncate_function_output_payload(output, policy_with_serialization_budget),
},
ResponseItem::Message { .. }
| ResponseItem::AgentMessage { .. }
| ResponseItem::Reasoning { .. }
| ResponseItem::LocalShellCall { .. }
| ResponseItem::FunctionCall { .. }
@@ -474,7 +475,8 @@ pub(crate) fn truncate_function_output_payload(
fn is_api_message(message: &ResponseItem) -> bool {
match message {
ResponseItem::Message { role, .. } => role.as_str() != "system",
ResponseItem::FunctionCallOutput { .. }
ResponseItem::AgentMessage { .. }
| ResponseItem::FunctionCallOutput { .. }
| ResponseItem::FunctionCall { .. }
| ResponseItem::ToolSearchCall { .. }
| ResponseItem::ToolSearchOutput { .. }
@@ -720,11 +722,15 @@ fn is_model_generated_item(item: &ResponseItem) -> bool {
ResponseItem::FunctionCallOutput { .. }
| ResponseItem::ToolSearchOutput { .. }
| ResponseItem::CustomToolCallOutput { .. }
| ResponseItem::AgentMessage { .. }
| ResponseItem::Other => false,
}
}
pub(crate) fn is_user_turn_boundary(item: &ResponseItem) -> bool {
if matches!(item, ResponseItem::AgentMessage { .. }) {
return true;
}
let ResponseItem::Message { role, content, .. } = item else {
return false;
};
codex-rs/core/src/session/turn.rs
+1
View File
@@ -1924,6 +1924,7 @@ async fn try_run_sampling_request(
role == "assistant" && matches!(phase, Some(MessagePhase::Commentary))
}
ResponseItem::Reasoning { .. } => true,
ResponseItem::AgentMessage { .. } => false,
ResponseItem::LocalShellCall { .. }
| ResponseItem::FunctionCall { .. }
| ResponseItem::ToolSearchCall { .. }
codex-rs/core/src/tools/handlers/multi_agents_spec.rs
+8 -3
View File
@@ -167,7 +167,8 @@ 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(),
),
]);
@@ -199,7 +200,8 @@ 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(),
),
]);
@@ -595,7 +597,10 @@ fn spawn_agent_common_properties_v2(agent_type_description: &str) -> BTreeMap<St
BTreeMap::from([
(
"message".to_string(),
JsonSchema::string(Some("Initial plain-text task for the new agent.".to_string())),
JsonSchema::string(Some(
"Initial plain-text task for the new agent.".to_string(),
))
.with_encrypted(),
),
(
"agent_type".to_string(),
codex-rs/core/src/tools/handlers/multi_agents_spec_tests.rs
+24
View File
@@ -81,6 +81,12 @@ fn spawn_agent_tool_v2_requires_task_name_and_lists_visible_models() {
assert!(!description.contains("hidden-model"));
assert!(properties.contains_key("task_name"));
assert!(properties.contains_key("message"));
assert_eq!(
properties
.get("message")
.and_then(|schema| schema.encrypted),
Some(true)
);
assert!(properties.contains_key("fork_turns"));
assert!(!properties.contains_key("items"));
assert!(!properties.contains_key("fork_context"));
@@ -141,6 +147,12 @@ fn spawn_agent_tool_v1_keeps_legacy_fork_context_field() {
assert!(properties.contains_key("fork_context"));
assert!(!properties.contains_key("fork_turns"));
assert_eq!(
properties
.get("message")
.and_then(|schema| schema.encrypted),
None
);
assert_eq!(
properties
.get("model")
@@ -259,6 +271,12 @@ fn send_message_tool_requires_message_and_has_no_output_schema() {
.expect("send_message should use object params");
assert!(properties.contains_key("target"));
assert!(properties.contains_key("message"));
assert_eq!(
properties
.get("message")
.and_then(|schema| schema.encrypted),
Some(true)
);
assert!(!properties.contains_key("interrupt"));
assert!(!properties.contains_key("items"));
assert_eq!(
@@ -296,6 +314,12 @@ fn followup_task_tool_requires_message_and_has_no_output_schema() {
.expect("followup_task should use object params");
assert!(properties.contains_key("target"));
assert!(properties.contains_key("message"));
assert_eq!(
properties
.get("message")
.and_then(|schema| schema.encrypted),
Some(true)
);
assert!(!properties.contains_key("items"));
assert_eq!(
parameters.required.as_ref(),
codex-rs/core/src/tools/handlers/multi_agents_tests.rs
+13 -12
View File
@@ -1152,7 +1152,7 @@ async fn multi_agent_v2_spawn_returns_path_and_send_message_accepts_relative_pat
turn.clone(),
"spawn_agent",
function_payload(json!({
"message": "inspect this repo",
"message": "encrypted-spawn-message",
"task_name": "test_process"
})),
))
@@ -1188,7 +1188,8 @@ async fn multi_agent_v2_spawn_returns_path_and_send_message_accepts_relative_pat
if communication.author == AgentPath::root()
&& communication.recipient.as_str() == "/root/test_process"
&& communication.other_recipients.is_empty()
&& communication.content == "inspect this repo"
&& communication.content.is_empty()
&& communication.encrypted_content.as_deref() == Some("encrypted-spawn-message")
&& communication.trigger_turn
)
}));
@@ -1200,7 +1201,7 @@ async fn multi_agent_v2_spawn_returns_path_and_send_message_accepts_relative_pat
"send_message",
function_payload(json!({
"target": "test_process",
"message": "continue"
"message": "encrypted-send-message"
})),
))
.await
@@ -1214,7 +1215,8 @@ async fn multi_agent_v2_spawn_returns_path_and_send_message_accepts_relative_pat
if communication.author == AgentPath::root()
&& communication.recipient.as_str() == "/root/test_process"
&& communication.other_recipients.is_empty()
&& communication.content == "continue"
&& communication.content.is_empty()
&& communication.encrypted_content.as_deref() == Some("encrypted-send-message")
&& !communication.trigger_turn
)
}));
@@ -1396,7 +1398,7 @@ async fn multi_agent_v2_send_message_accepts_root_target_from_child() {
"send_message",
function_payload(json!({
"target": "/root",
"message": "done"
"message": "encrypted-done"
})),
))
.await
@@ -1410,7 +1412,8 @@ async fn multi_agent_v2_send_message_accepts_root_target_from_child() {
if communication.author == child_path
&& communication.recipient == AgentPath::root()
&& communication.other_recipients.is_empty()
&& communication.content == "done"
&& communication.content.is_empty()
&& communication.encrypted_content.as_deref() == Some("encrypted-done")
&& !communication.trigger_turn
)
}));
@@ -1500,7 +1503,7 @@ async fn multi_agent_v2_followup_task_rejects_root_target_from_child() {
}
#[tokio::test]
async fn multi_agent_v2_list_agents_returns_completed_status_and_last_task_message() {
async fn multi_agent_v2_list_agents_returns_completed_status_without_encrypted_spawn_preview() {
let (mut session, mut turn) = make_session_and_context().await;
let manager = thread_manager();
let root = manager
@@ -1586,10 +1589,7 @@ async fn multi_agent_v2_list_agents_returns_completed_status_and_last_task_messa
.find(|agent| agent.agent_name == "/root/worker")
.expect("worker agent should be listed");
assert_eq!(worker.agent_status, json!({"completed": "done"}));
assert_eq!(
worker.last_task_message.as_deref(),
Some("inspect this repo")
);
assert_eq!(worker.last_task_message, None);
assert_eq!(success, Some(true));
}
@@ -1868,7 +1868,8 @@ async fn multi_agent_v2_send_message_rejects_interrupt_parameter() {
if communication.author == AgentPath::root()
&& communication.recipient.as_str() == "/root/worker"
&& communication.other_recipients.is_empty()
&& communication.content == "continue"
&& communication.content.is_empty()
&& communication.encrypted_content.as_deref() == Some("continue")
&& !communication.trigger_turn
)));
}
codex-rs/core/src/tools/handlers/multi_agents_v2.rs
+15
View File
@@ -22,6 +22,7 @@ use codex_protocol::protocol::CollabCloseBeginEvent;
use codex_protocol::protocol::CollabCloseEndEvent;
use codex_protocol::protocol::CollabWaitingBeginEvent;
use codex_protocol::protocol::CollabWaitingEndEvent;
use codex_protocol::protocol::InterAgentCommunication;
use codex_protocol::user_input::UserInput;
use codex_tools::ToolName;
use serde::Deserialize;
@@ -42,3 +43,17 @@ mod message_tool;
mod send_message;
mod spawn;
pub(crate) mod wait;
pub(super) fn communication_from_tool_message(
author: AgentPath,
recipient: AgentPath,
message: String,
) -> InterAgentCommunication {
InterAgentCommunication::new_encrypted(
author,
recipient,
Vec::new(),
message,
/*trigger_turn*/ true,
)
}
codex-rs/core/src/tools/handlers/multi_agents_v2/message_tool.rs
+9 -12
View File
@@ -1,4 +1,4 @@
//! Shared argument parsing and dispatch for the v2 text-only agent messaging tools.
//! Shared argument parsing and dispatch for the v2 agent messaging tools.
//!
//! `send_message` and `followup_task` share the same submission path and differ only in whether the
//! resulting `InterAgentCommunication` should wake the target immediately.
@@ -55,20 +55,21 @@ fn message_content(message: String) -> Result<String, FunctionCallError> {
Ok(message)
}
/// Handles the shared MultiAgentV2 plain-text message flow for both `send_message` and `followup_task`.
/// Handles the shared MultiAgentV2 message flow for both `send_message` and `followup_task`.
pub(crate) async fn handle_message_string_tool(
invocation: ToolInvocation,
mode: MessageDeliveryMode,
target: String,
message: String,
) -> Result<FunctionToolOutput, FunctionCallError> {
let prompt = message_content(message)?;
let message = message_content(message)?;
let ToolInvocation {
session,
turn,
call_id,
..
} = invocation;
let prompt = String::new();
let receiver_thread_id = resolve_agent_target(&session, &turn, &target).await?;
let receiver_agent = session
.services
@@ -101,15 +102,11 @@ pub(crate) async fn handle_message_string_tool(
let receiver_agent_path = receiver_agent.agent_path.clone().ok_or_else(|| {
FunctionCallError::RespondToModel("target agent is missing an agent_path".to_string())
})?;
let communication = InterAgentCommunication::new(
turn.session_source
.get_agent_path()
.unwrap_or_else(AgentPath::root),
receiver_agent_path,
Vec::new(),
prompt.clone(),
/*trigger_turn*/ true,
);
let author = turn
.session_source
.get_agent_path()
.unwrap_or_else(AgentPath::root);
let communication = communication_from_tool_message(author, receiver_agent_path, message);
let result = session
.services
.agent_control
codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs
+8 -14
View File
@@ -1,7 +1,6 @@
use super::*;
use crate::agent::control::SpawnAgentForkMode;
use crate::agent::control::SpawnAgentOptions;
use crate::agent::control::render_input_preview;
use crate::agent::next_thread_spawn_depth;
use crate::agent::role::DEFAULT_ROLE_NAME;
use crate::agent::role::apply_role_to_config;
@@ -9,7 +8,6 @@ use crate::tools::handlers::multi_agents_spec::SpawnAgentToolOptions;
use crate::tools::handlers::multi_agents_spec::create_spawn_agent_tool_v2;
use crate::turn_timing::now_unix_timestamp_ms;
use codex_protocol::AgentPath;
use codex_protocol::protocol::InterAgentCommunication;
use codex_protocol::protocol::Op;
use codex_tools::ToolSpec;
@@ -61,8 +59,9 @@ async fn handle_spawn_agent(
.map(str::trim)
.filter(|role| !role.is_empty());
let message = args.message.clone();
let initial_operation = parse_collab_input(Some(args.message), /*items*/ None)?;
let prompt = render_input_preview(&initial_operation);
let prompt = String::new();
let session_source = turn.session_source.clone();
let child_depth = next_thread_spawn_depth(&session_source);
@@ -129,17 +128,12 @@ async fn handle_spawn_agent(
.iter()
.all(|item| matches!(item, UserInput::Text { .. })) =>
{
Op::InterAgentCommunication {
communication: InterAgentCommunication::new(
turn.session_source
.get_agent_path()
.unwrap_or_else(AgentPath::root),
recipient,
Vec::new(),
prompt.clone(),
/*trigger_turn*/ true,
),
}
let author = turn
.session_source
.get_agent_path()
.unwrap_or_else(AgentPath::root);
let communication = communication_from_tool_message(author, recipient, message);
Op::InterAgentCommunication { communication }
}
(_, initial_operation) => initial_operation,
},
codex-rs/core/src/tools/spec_plan_tests.rs
+24
View File
@@ -1047,6 +1047,30 @@ async fn multi_agent_feature_selects_one_agent_tool_family() {
);
}
#[tokio::test]
async fn multi_agent_v2_message_schemas_are_encrypted() {
let plan = probe(|turn| {
set_feature(turn, Feature::MultiAgentV2, /*enabled*/ true);
})
.await;
for tool_name in ["spawn_agent", "send_message", "followup_task"] {
let ToolSpec::Function(tool) = plan.visible_spec(tool_name) else {
panic!("expected {tool_name} function spec");
};
let properties = tool
.parameters
.properties
.as_ref()
.expect("tool should use object params");
assert_eq!(
properties
.get("message")
.and_then(|schema| schema.encrypted),
Some(true)
);
}
}
#[tokio::test]
async fn tool_mode_selector_overrides_feature_flags() {
let direct = probe(|turn| {
codex-rs/core/src/turn_timing.rs
+1
View File
@@ -177,6 +177,7 @@ fn response_item_records_turn_ttft(item: &ResponseItem) -> bool {
})
})
}
ResponseItem::AgentMessage { .. } => false,
ResponseItem::LocalShellCall { .. }
| ResponseItem::FunctionCall { .. }
| ResponseItem::CustomToolCall { .. }