Support custom session ID for new threads via ThreadStartParams
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
SessionConfiguredevent, 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::newuses provided ID) - Validation at both CLI (fail-fast) and protocol level (defense-in-depth)
--session-idflag oncodexandcodex 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.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗