›_ Codex Issues
Codex Issues / #17900

Clarify thread/read vs thread/resume semantics in integration docs

Open 💬 2 comments Opened Apr 15, 2026 by forsaken628
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

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 ↗

2 Comments

etraut-openai contributor · 4 months ago

Please refer to our official app server documentation here.

Herrtian · 3 months ago

I prepared a small app-server README clarification for this:

https://github.com/Herrtian/codex/tree/docs/thread-read-resume-subscription

The change keeps the existing API behavior unchanged and only tightens the docs language:

  • thread/resume is described as the call that subscribes the connection to live turn/item notifications for the resumed thread.
  • thread/read is described as a snapshot/read API for stored or loaded thread state, not as a live-event subscription.
  • the reconnect guidance points clients that need future turn/* and item/* notifications toward thread/resume.

Validation I ran:

git diff --check -- codex-rs/app-server/README.md

PR creation appears to be limited by the repo's invitation-only contribution policy, so I'm sharing the branch here instead of opening an unsolicited PR. If this lines up with the app-server docs direction, could a maintainer invite a PR or pick it up internally?