プログラムステータスのためのターミナルプロトコル (OSC 7501)

プログラムステータスのためのターミナルプロトコル (OSC 7501) October 6, 2026 新しいターミナルエスケープシーケンス、プログラムステータスプロトコル（OSC 7501）の仕様を記述しました。これにより、あらゆるプログラムがターミナルに対して、自身が何をしているか（アイドル、作業中、ユーザー待ち、完了、または失敗）とその理由を伝えることができます。例えば、Terraformがユーザー入力を待ってブロックされている状態を、「Apply 3 to add, 1 to change, 0 to destroy?」（3つ追加、1つ変更、0つ破棄を適用？）というメッセージと共に示す方法を以下に示します（base64エンコード済み）。ターミナル（またはTerraformを実行している他のツール）は、この情報を通知、受信トレイ、ステータスアイコンなど、適切だと感じる方法で表示できます。 ESC ] 7501 ; state=blocked:kind=permission:app=terraform:msg=QXBwbHkgMyB0byBhZGQsIDEgdG8gY2hhbmdlLCAwIHRvIGRlc3Ryb3k/ ESC \ この記事では、なぜこのプロトコルが必要だと考えるのか、既存のアプローチ（特にコーディングエージェントにとって）がなぜ不十分なのか、そしてプロトコルがどのように機能するのかを説明します。これは完全に汎用的で、ターミナルネイティブな仕様とプロトコルです。SuperlogicalとGhosttyでの作業から生まれましたが、仕様には製品固有の機能や言語はありません。あらゆるターミナル開発者にとって馴染みのある、idiomaticでよく形成された仕様として設計されています。 問題 ターミナルでは、ビルド、デプロイ、パッケージアップグレード、データ処理、そして今日ますます増えているコーディングエージェントなど、長時間実行される作業が一般的です。これらのプログラムは、自身の作業、ユーザー待ち、完了の間で交互に状態が変わります。その間、ユーザーは通常、別の作業に移り、作業が完了したり、ユーザーの介入が必要になったりしたときに知りたいと思っています。この問題の側面は、数十年前から様々な方法で解決されてきました。例えば、一部のターミナルはアクティブなフォアグラウンドプロセスを監視し、それが変更されたときに通知する機能を持っています。あるいは、様々な定義で「静寂」（出力がない状態）の一定期間を待ちます。仕様には、既存のシーケンスがなぜ不十分なのかも記載されています。最終的に、進捗、ブロック、完了、タスクツリーを伝える、一貫性があり、インタラクションに依存しない、汎用的な解決策が存在しないと感じました。また、既存のシーケンスを組み合わせて堅牢に実現することも不可能でした。 「エージェントインボックス」の特定 AI、LLMなどに関心がない場合は、このセクションをスキップしてください。この問題は汎用的であり、AIを持ち出さなくても説得力のある形で適用できます。AIに関しては特に厄介なので、ここで言及しますが、もしそれらに興味がない場合はスキップしてください。現在、様々な理由で多くの長時間実行エージェントを実行することがますます一般的になっています。バックグラウンドリサーチ、問題監視、バグ修正、大規模機能開発などです。それぞれがしばらく作業し、許可を求めたり、質問したり、完了したことを報告したりするために停止します。これにより、私が単にエージェントインボックスと呼ぶ新しいツールのカテゴリが出現しました。これは、実行中のすべてのエージェントを単一のビューで表示し、どれが作業中で、どれが完了し、どれがあなたを待っているかを示します。Herdr、cmux、Agent Deckは、数百ある例のうちのいくつかです。専用のプロトコルがない場合、エージェントステータス問題は2つの方法で解決されます。ヒューリスティックと非ターミナルAPIです。 ヒューリスティック 最初のアプローチは、画面やウィンドウタイトルを読み取り、既知のパターンと照合して推測することです。Herdrはその良い例です。なぜなら、それはこの作業をうまくこなし、それをオープンに文書化しているからです。その検出マニフェストは、エージェントをアイドル、作業中、またはブロック済みとして分類するTOMLルールです。以下は、Claude Codeの16のルールの最初のものです。 [[rules]] id = "osc_title_working" state = "working" priority = 1100 region = "osc_title" visible_working = true # Braille covers <= 2.1.227; half-circles are the 2.1.228 busy spinner. regex = ['^[\\x{2800}-\\x{28FF}\\x{25D0}-\\x{25D3}] '] Claude Codeは、ウィンドウタイトルが点字スピナー文字、またはバージョン2.1.228以降では半円スピナー文字で始まる場合に「作業中」と見なされます。そのファイルの履歴を見ると、Claude Codeだけで3ヶ月間に10回の変更がありました。これはHerdrを批判するものではありません。そのメンテナーは、利用可能なツールで最善を尽くしています。しかし、これは統一されたプロトコルが持つ利点をよく示しています。 非ターミナルAPI 2番目のアプローチは、プログラムがエージェントインボックス固有のアウトオブバンドAPI（HerdrのソケットAPIやcmux notifyなど）を通じて自身の状態を報告することです。これは、状態を知っているプログラム自身がそれを報告するため、ヒューリスティックよりもいくつかの点で優れています。しかし、すべてのプログラムがすべてのインボックスと個別に統合する必要があり、ローカルソケットはSSH経由やコンテナ内では追加のブリッジなしでは機能しません。ptyはこれらのすべてで機能します。 プログラムステータスプロトコル OSC 7501は、この問題に対するターミナルネイティブな回答です。プログラムは、常に持っているptyを介して、どこにでも安全に送信できる形式（適切に動作するターミナルは未知のOSCを無視します）を使用して、自身の状態を直接報告します。シーケンスの本体は、:で区切られたkey=valueペアのリストです。唯一必須のキーはstateで、以下のいずれかです。 stateMeaning idle 待機状態、ユーザーの次の指示を待っている。 working 実行中。進捗率を含む場合がある。 done 完了。結果が準備できており、ユーザーはまだ見ていない。 error 失敗して停止した。 オプションのキーには、cargoやclaude-codeのような安定した機械可読プログラム名であるapp、およびbase64でエンコードされた単一の人間可読行であるmsgが含まれます。同時に複数のタスクを実行するプログラムは、階層的なIDを使用して複数のレコードを報告できます。デプロイツールはルートで作業中であり、us-eastは40%でイメージをプッシュしており、eu-westは本番環境へのデプロイ承認を待ってブロックされている可能性があります。これらすべてが同時に真であり、ターミナルが表示方法を決定します。クリア状態はレコードを削除します。 以下は、rsyncをラップしてこのプロトコルに参加するためのシェルスクリプトの完全な統合例です。 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" 通常のPOSIX shでスクリプト化するのは非常に簡単です。SDK、ソケット、環境変数、JSONは不要です。特定のGUIプレゼンテーションへのバイアスはありません。特定のワークロード（AIなど）へのバイアスもありません。誰でも参加できる、機能の上に構築するための、よく形成された汎用的な基盤です。完全な仕様には、レコードのライフタイム、機能検出、terminfo、サイズ制限、セキュリティが含まれます。短いです。すべて手書きで書きました。ぜひ読んでください。 実装する 長年ターミナルエミュレータをメンテナンスしてきた経験に基づいて、この仕様を作成しました。アプリケーション開発者が発行しやすく、ターミナルエミュレータが消費・解析しやすいように書かれています。すでにこのプロトコルを2回実装しました。libghosttyに1つの実装があり、Rexにも並列実装があります。また、Terraform、Claude Code、Codex、Homebrewでは、プラグインまたはフォークを通じて概念実証として実装しました。いずれの場合も、実装は十数行に過ぎませんでした。多くの人気のあるターミナルプログラムやエミュレータのメンテナーと連絡を取り、仕様のレビューと形成に協力してもらいました。しかし、さらにフィードバックがあれば、喜んでお聞きします。仕様を実装した場合は、メール（フッターのメールアイコン）で知らせてください。実装ツールのリストに追加します。ありがとうございます。 プログラムが画面やプロセスツリーを読み取って何をしているかを推測するのをやめましょう。プログラムはすでにそれを知っています。それを私たちに伝える方法を与えましょう！ October 6, 2026