Problem

Codex CLI runtime (src/middleware/runtimes/codex.ts) has a --image flag for image input that was previously broken in --json output mode due to upstream bug codex#5773.

Upstream status

Blocked on openai/codex#5773.

Unblocked. openai/codex#5891 fixed the race condition causing codex exec --json --image to hang. Merged Oct 28, 2025.

Current state

• Uses exec --json --color never for invocation
• --image <path> flag exists and works in --json mode (upstream fix landed)
• mediaCapabilities still declares acceptsInbound: [] (workaround for the now-fixed bug)

Implementation

• Update mediaCapabilities: acceptsInbound: ["image/"]
• In buildArgs(), for each image MediaAttachment with filePath, append --image <path>
• Codex CLI accepts --image directly as file paths (no base64/stdin envelope needed, unlike Claude)
• Audio/video remain unsupported: emitsOutbound: false

readonly mediaCapabilities = {
  acceptsInbound: ["image/"],
  emitsOutbound: false,
} as const;

Codex --image flag details

• Long: --image, Short: -i
• Accepts file paths, repeatable or comma-delimited
• Works on exec subcommand; verify behavior on exec resume

Considerations

• Media attachments arrive with filePath populated (from media-resolver.ts)
• partitionMedia() in channel-bridge.ts already filters by capabilities
• Temp file lifecycle managed by the bridge (cleaned up after invocation)
• Session resume: verify if exec resume supports --image — may need to skip images on resume since Codex propagates conversation context internally

Tests

Unit tests (src/middleware/runtimes/codex.test.ts)

• mediaCapabilities reports acceptsInbound: ["image/"]
• buildArgs() with image media passes --image <path> flags
• buildArgs() with multiple images passes multiple --image flags
• buildArgs() without media does not include --image
• buildArgs() filters non-image media (no --image for audio/video)

Live smoke test (src/middleware/__smoke__/codex.live.test.ts)

• Send image, verify Codex describes content

Depends on

• feat(middleware): add multimodal media attachments to AgentRuntime contract #385 — AgentRuntime multimodal contract (merged)

Related

• feat(runtimes): implement multimodal I/O for each CLI runtime #386 — per-runtime multimodal (parent tracking issue)
• research(auth+media): auth profiles and media understanding architecture #376 — auth/media restructuring