Support custom session ID for new threads via ThreadStartParams

Resolved 💬 2 comments Opened Mar 25, 2026 by debuglebowski Closed May 10, 2026

Problem

External tools that embed Codex (e.g. desktop apps spawning codex or using the app-server protocol) need to correlate their own session identifiers with Codex thread IDs. Currently, ThreadId is always auto-generated via UUID::now_v7() in Session::new, with no way for callers to influence it.

This forces external tools to either:

  • Wait for SessionConfigured event, then retroactively map the generated ID
  • Maintain a separate mapping layer between their IDs and Codex's

Both approaches add complexity and race conditions, especially when multiple sessions start concurrently.

Proposed solution

Add an optional session_id: Option<String> field to ThreadStartParams. When provided, the given UUID is used as the thread's ThreadId instead of auto-generating one. When omitted, behavior is unchanged.

The field is validated as a valid UUID at the protocol level, returning INVALID_REQUEST_ERROR_CODE on failure.

Additionally, a --session-id <UUID> CLI flag on both codex and codex exec for the same purpose.

Why this is safe

ThreadId is purely client-side — it's sent to the OpenAI API only as correlation headers (session_id, x-client-request-id). The API does not validate, assign, or return these. No server-side behavior changes.

Implementation status

I have a complete implementation ready with:

  • Protocol field on ThreadStartParams + schema regeneration
  • Core threading through the spawn chain (Session::new uses provided ID)
  • Validation at both CLI (fail-fast) and protocol level (defense-in-depth)
  • --session-id flag on codex and codex exec
  • 8 tests: 4 unit (ThreadId parsing) + 4 integration (valid/invalid/empty/omitted via McpProcess)
  • Clean cargo build, cargo clippy, cargo fmt, cargo test

Happy to submit a PR if the team is open to this.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗