Supported read-only thread status stream for external tools (OpenDeck use case)

[!NOTE]
🤖 Codex responding on behalf of beastyrabbit

We are developing T3 Code Status for OpenDeck, an external plugin that displays running thread counts and highlights pending user input, approvals, and plan reviews on Stream Deck keys.

The plugin currently checks the local environment endpoint and reads T3 Code's local Chromium shell cache on a timer. A shorter interval would make question alerts more responsive, but it would also repeatedly read the cache when nothing has changed. We would prefer an authenticated status subscription.

Smallest useful scope

• An initial snapshot of current thread states.
• Updates when work starts or stops, input or approval requests appear or are resolved, or a plan needs review.
• Updates when threads leave the displayed set, and a way to recover the current state after reconnecting.
• Read-only access with the narrowest available permissions.

The OpenDeck integration would remain in our project. We only need status metadata for the display; we do not need to send prompts, answer approvals, read conversation bodies, or access workspace files.

Question about the existing interface

In v0.0.40, we found read-only pairing and orchestration.subscribeShell, including the pending-input and approval flags and sequence-based resume support. This looks close to what we need already.

Is read-only pairing plus orchestration.subscribeShell the recommended interface for an external status client? If so, could a minimal supported connection example or contract be documented, covering authentication, session expiry, reconnection, and compatibility expectations?

The current orchestration:read permission also allows file reads. A narrower status-only permission would fit this use case if one is planned. If a different event interface is preferred, guidance on that would also help.

We would be happy to use the existing WebSocket stream if it is intended for this purpose. This request could be addressed independently of a broader SDK or an embedded-plugin system.

Related discussions

• #6686: Local lifecycle hooks / notification integration covers similar events. Our display also needs the current state on connection and recovery after missed events.
• #6933: Outbound completion webhooks focuses on terminal events.
• #6977: Local app integration SDK and custom project surfaces includes a broader client SDK proposal.

I understand feature proposals normally belong in Ideas discussions. Please feel free to move this there or point us to an existing thread if that is the preferred place for this specific integration question.

Start by reviewing the existing read-only pairing and orchestration.subscribeShell interface, including its pending-input, approval, and sequence-resume behavior. Compare it with discussions #6686, #6933, and #6977. Done means the supported connection contract, authentication, session expiry, reconnection, and compatibility expectations are documented or the preferred interface is identified.