mirror of https://github.com/pchuan98/codex.git synced 2026-07-01 00:31:56 +08:00

Files

T

jif 5f4d06ef18 Encrypt multi-agent v2 message payloads (#26210 )

## 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`

5f4d06ef18 · 2026-06-05 10:25:57 +02:00

History

src

Encrypt multi-agent v2 message payloads (#26210 )

2026-06-05 10:25:57 +02:00

tests

Update rmcp to 1.7.0 (#24763 )

2026-05-27 14:52:06 -07:00

BUILD.bazel

[codex] Move tool specs into core handlers (#21416 )

2026-05-06 15:40:50 -07:00

Cargo.toml

chore: add JSON schema policy fixture coverage (#24152 )

2026-05-22 16:31:33 -07:00

README.md

Remove ToolsConfig from tool planning (#22835 )

2026-05-19 11:24:09 +02:00

README.md

codex-tools

codex-tools is the shared support crate for building, adapting, and executing model-visible tools outside codex-core.

Today this crate owns the host-facing tool models and helpers that no longer need to live in core/src/tools/spec.rs or core/src/client_common.rs:

aggregate host models such as ToolSpec, ConfiguredToolSpec, LoadableToolSpec, ResponsesApiNamespace, and ResponsesApiNamespaceTool
host discovery models used while assembling tool sets, including discoverable-tool models and request-plugin-install helpers
host adapters such as schema sanitization, MCP/dynamic conversion, code-mode augmentation, and image-detail normalization
shared executable-tool contracts such as ToolExecutor, ToolCall, and ToolOutput

That extraction is the first step in a longer migration. The goal is not to move all of core/src/tools into this crate in one shot. Instead, the plan is to peel off reusable pieces in reviewable increments while keeping compatibility-sensitive orchestration in codex-core until the surrounding boundaries are ready.

Vision

Over time, this crate should hold host-side tool machinery that is shared by multiple consumers, for example:

host-visible aggregate tool models
tool-set planning and discovery helpers
MCP and dynamic-tool adaptation into Responses API shapes
code-mode compatibility shims that do not depend on codex-core
other narrowly scoped host utilities that multiple crates need

The corresponding non-goals are just as important:

do not move codex-core orchestration here prematurely
do not pull Session / TurnContext / approval flow / runtime execution logic into this crate unless those dependencies have first been split into stable shared interfaces
do not turn this crate into a grab-bag for unrelated helper code

Migration approach

The expected migration shape is:

Keep extension-owned executable-tool authoring in codex-extension-api.
Move host-side planning/adaptation helpers here when they no longer need to stay coupled to codex-core.
Leave compatibility-sensitive adapters in codex-core while downstream call sites are updated.
Only extract higher-level host infrastructure after the crate boundaries are clear and independently testable.

Crate conventions

This crate should start with stricter structure than core/src/tools so it stays easy to grow:

src/lib.rs should remain exports-only.
Business logic should live in named module files such as foo.rs.
Unit tests for foo.rs should live in a sibling foo_tests.rs.
The implementation file should wire tests with:

#[cfg(test)]
#[path = "foo_tests.rs"]
mod tests;

If this crate starts accumulating code that needs runtime state from codex-core, that is a sign to revisit the extraction boundary before adding more here.