Clarify thread/read vs thread/resume semantics in integration docs
Open 💬 2 comments Opened Apr 15, 2026 by forsaken628
What is the type of issue?
Documentation is missing
What is the issue?
The integration-facing docs do not clearly explain the semantic difference between thread/read and thread/resume.
This makes it easy to assume that thread/read can be used to reattach a connection to an existing thread and continue receiving live turn
events. In practice, that is not the case.
Observed behavior:
thread/readreturns thread state / persisted historythread/readdoes not attach a live listener for future thread eventsthread/resumeis the operation that resumes an existing thread and subscribes the connection for subsequent updates
Because this distinction is not prominent in the docs, integrators may build reconnect flows that appear to lose turn/started, item/completed,
or turn/completed notifications.
Suggested documentation change:
- explicitly state that
thread/readis for state/history inspection only - explicitly state that
thread/readis not a subscription primitive - explicitly state that reconnecting to an existing thread's live event stream requires
thread/resume
Where did you find it?
codex-rs/docs/codex_mcp_interface.mdcodex-rs/app-server-client/README.mdcodex-rs/app-server-protocol/src/protocol/v2.rs
Relevant source comments that clarify the behavior today:
codex-rs/app-server/src/thread_state.rscodex-rs/tui/src/app.rs
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗