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/read returns thread state / persisted history
  • thread/read does not attach a live listener for future thread events
  • thread/resume is 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/read is for state/history inspection only
  • explicitly state that thread/read is 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.md
  • codex-rs/app-server-client/README.md
  • codex-rs/app-server-protocol/src/protocol/v2.rs

Relevant source comments that clarify the behavior today:

  • codex-rs/app-server/src/thread_state.rs
  • codex-rs/tui/src/app.rs

View original on GitHub ↗

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