OSC 7501：プログラム状態プロトコル（Program Status Protocol）

OSC 7501 は、あらゆるプログラムがターミナルに対して**「現在何をしているか」**を知らせるための汎用的なプロトコルです。

プロトコルの概要と特徴

このプロトコルを活用することで、以下のような状態を細かく伝達可能です：

• アイドル（待機中）
• 作動中
• ユーザー入力を待機中（ブロックされている）
• 終了した
• 失敗した
  • 失敗の原因や理由まで詳細を伝えることが可能

動作例：Terraform の状態報告

Terraform が完了判定前にユーザー入力（承認）を待機している際、以下の形式で状態を伝達します。ターミナル側はこの情報に基づき、ポップアップ通知、受信トレイ表示、ステータスアイコンなど、様々な形でユーザーに可視化します。

ESC ] 7501 ; state=blocked:kind=permission:app=terraform:msg=QXBwbHkgMyB0byBhZGQsIDEgdG8gY2hhbmdlLCAwIHRvIGRlc3Ryb3k/ ESC \

プロトコルの設計思想

• 完全な汎用性: 特定の製品やプログラミング言語に依存しません。
• ターミナルネイティブ: ターミナル開発者が理解しやすい慣習的で整合性の取れた仕様です。
• 由来: 「Superlogical」と「Ghostty」の開発チームから生まれました。

課題の背景

長期間実行されるタスク（ビルド、デプロイ、データ処理、コーディングエージェントなど）は、以下のサイクルを繰り返します：

1. 自律的に処理を進める
2. ユーザーの入力を待つ
3. 完了する

この間、ユーザーはタスクの完了状況や**「協力が求められるタイミング」**を知りたいことが多いです。既存のアプローチには以下の限界があります：

• アクティブプロセス監視: フォアグラウンドプロセスの変化を監視するが、粒度が粗い。
• 出力待ち時間: 「静かな」状態が続く時間を待つ手法は信頼性が低い。
• 統合的な解決策の欠如: 進行状況、ブロック状態、完了、タスクツリーなどの情報を一元化して伝える仕組みが存在しませんでした。

「エージェント用受信トレイ」への焦点

AI エージェントや LLM を利用するケースでは、この課題が特に顕著です。現在は複数のエージェントを同時に動作させることが増えています（背景調査、問題監視、バグ修正など）。各エージェントは処理の一時停止、許可要求、完了報告を繰り返します。これらを管理するための新たなカテゴリとして**「エージェント用受信トレイ（agentic inbox）」**が注目されています。

既存のアプローチと限界

専用プロトコルが存在しないため、現状では以下の 2 つの方法で状態管理が行われています：

1. ヘuristics（推測手法）

画面内容やウィンドウタイトルを読み取り、既知のパターンに照合して状態を推測します。

• 代表例:

  Herdr

  • ウィンドウタイトルが点字（ブライトル）のスピンナー文字で始まる場合などに「作動中」と判定します。
  • 特定のツール（例：Claude Code）向けに個別の規則（TOML 形式）を定義・維持管理する必要があります。これでは統一的な解決策にはなりません。

2. ターミナル外 API

プログラムから直接状態を報告するソケット API（例：

Herdr

cmux notify

• 長所: プログラム自身の内部状態が最も正確です。
• 短所: 全てのプログラムが個別にツールと統合する必要があります。ローカルソケットは SSH やコンテナ環境から利用するには追加のブリッジングが必要で、汎用性に欠けます。

OSC 7501：プログラム状態プロトコル

OSC 7501 はターミナルネイティブな解決策として、プログラムが保有する PTY（擬似端末）を介して自身の状態を直接報告します。未知の OSC シーケンスも見逃すことなく安全に処理できる振る舞いが設計されています。

メッセージ構造

シーケンス本体は

:

必須キー:

state

プログラムの現在の状態を定義します：

• idle

  : 待機中。次のユーザー指示を待つ。

• working

  : 作動中。進行状況のパーセンテージなどを併記できる。

• done

  : 完了。結果が用意され、ユーザー確認待ちの状態。

• blocked

  : 継続にはユーザーアクションが必要。

  • kind

    : 原因を示す（許可不足、質問、認証など）。

  • msg

    : 理由を説明するメッセージ（base64 符号化）。

• error

  : 失敗し停止した状態。

任意キー

• app

  : 機械可読な安定したプログラム名（例：

  cargo

  ,

  claude-code

  など）。

• msg

  : 人間が読みやすい単一行テキスト（base64 符号化）。

階層的な ID の使用

複数のタスクを同時に実行している場合、階層的な ID を使用して複数の状態記録を報告できます。

• 例: ルートでデプロイ中でありつつ、特定リージョンのイメージプッシュが進行中であり、他リージョンがブロックされている状況など。
• ターミナル側がこの情報を決定し、状態が明確になったら古い記録は削除されます。

実装例：シェルスクリプト

PTY を通じた簡単な報告を POSIX sh で実装可能です。SDK、ソケット、環境変数、JSON は一切不要です。

status() {
  printf '\e]7501;state=%s:msg=%s\e\\' "$1" "$(printf '%s' "$2" | base64 | tr -d '\n')"
}

# 作動中の表示
status working "Syncing photos"
rsync -a ~/Photos backup:/photos && status done "Photos synced" || status error "rsync failed"

このアプローチは、特定の GUI 表現へのバイアスもなく、特定のワークロード（AI など）への偏りもないため、誰でも参加できる汎用的な基盤を提供します。仕様書には記録のライフサイクル、機能検出、terminfo 定義、サイズ制限、セキュリティなどの詳細が含まれています。

実装状況と今後の展開

既の実装例

• libghostty: プロトコルを実装済み。
• Rex: 別の実装が存在。
• 概念実証: Terraform、Claude Code、Codex、Homebrew 等でのプラグインやフォークによる実装が完了。
  • いずれの実装も十数行で収まります。

コミュニティへの呼びかけ

多数のターミナル・エミュレータ維持チームと協力し、仕様書のレビューを済ませました。

• ご意見やフィードバックをお持ちの場合は歓迎です。
• 実装を検討されている方からは、メール（フッターのリンク）による連絡をお待ちしています。
  • 登録いただいたツールリストへの掲載も可能です。

目標

画面やプロセスツリーを読むことでプログラムが何をしているかを推測する必要はなくなります。プログラムの内部状態は既にプログラム自身を知っていますので、それを分かりやすく伝える手段を与えることが重要です！