Optional OSC 7501 (Program Status Protocol) reporting from Progress/Status/Live

[jdidion]

How would you improve Rich?

Add optional support for OSC 7501, the Program Status Protocol (spec linked below). Progress, Status and Live would report the program's state to the terminal through the pty:

• a Progress task with a known total: state=working:progress=<completed*100/total>
• Status (spinner) or an unknown total: state=working with no progress (the spec defines that as indeterminate)
• all tasks finished when the context exits normally: state=done; exiting with an exception: state=error
• multiple Progress tasks: child records, id=<task id> and title=<description>, with the root record for the overall state
• Prompt.ask / Confirm.ask waiting for input could report state=blocked:kind=question

It would be opt-in (a constructor flag or a Console option). It should only emit when the console is a real terminal, and only on state changes and integer-percent changes. app has to be repeated in every report, because each report replaces its record completely.

What problem does it solve for you?

I run long CLI jobs and coding agents in several terminal panes and walk away from them. Today the only way for a terminal, or a tool that watches many sessions, to know whether one of them finished, failed or is waiting on me is to guess from the window title or screen contents. Rich already knows the progress and prompt state, so it is the natural place to report it, and every Rich-based CLI would get it without per-application code.

Background

OSC 7501, the Program Status Protocol (revision 0.3, 2026-10-07, written by Mitchell Hashimoto) lets a program tell the terminal what it is doing through the pty it already has:

ESC ] 7501 ; state=working:app=mytool:progress=40:msg=<base64 UTF-8> ESC \

States are idle, working (optional progress 0-100), blocked (with kind=permission|question|auth), done, error, plus clear. Reports can address child records with hierarchical ids (id=build/test). Well-behaved terminals ignore unknown OSCs, and the spec says programs may send reports without feature detection, so emitting it is safe. The motivation is long-running work that the user walks away from: today terminals and multi-session "inbox" tools guess a program's state from window titles or screen contents (background post).

Details from the spec that matter for an implementation:

• Each report replaces its record completely, so app (and title) must be repeated in every report.
• msg and title are standard base64 of UTF-8 with no control characters; msg is capped at 2048 bytes decoded and the whole sequence at 4096 bytes.
• working and blocked records are dropped by the terminal on process exit or the next shell prompt; done and error survive, so a program should report one of those right before exiting.

Current adoption: libghostty (ghostty-org/ghostty#14560), Rex, and Pi. Open PRs or issues elsewhere include Charm's bubbletea#1841 and x#1004, rust-lang/cargo#17559, neovim/neovim#42276, microsoft/terminal#20777 and manaflow-ai/cmux#18397.