Human Notify — 人間へのローカル通知
呼び出し元が通知の必要性・急ぐ理由・期限を判断し、本スキルが端末への表示と読み上げを担当する。 Claude Code / Codexのどちらでも同じCLIを使う。 リモート環境やGUIのない環境では手元の端末へ届くと見なさず、チャットと詳細参照先を残す。
| 経路 | 使う時 | 出方 | script |
|---|---|---|---|
| 止まった時の知らせ | ゴールの印を付けたセッションが、手を止めた・許可待ちになった | デスクトップのバナー(macOS、Linux) | scripts/waiting_notify.py |
| 急ぎの連絡 | 期限までの猶予が短い判断・作業、重大な問題 | repo名付きのダイアログと読み上げ(macOS) | scripts/human_notify.py |
同じ依頼を、複数の経路から重ねて送らない。
止まった時の知らせ
ゴールの印を付けたセッションが、手を止めて静かになった時、APIのエラーでターンが終わった時、許可待ちになった時に、案件名・状態・ゴール名をデスクトップへ知らせる。印の無いworktreeのセッションと、同じworktreeにいる別のセッション(レビューの実行など)では、何も知らせない。印を付けるのは、ゴールを進めるセッションである(autopilotの「知らせ」の節)。
python3 <skill-dir>/scripts/waiting_notify.py mark --cwd <worktree> --goal '<ゴール名>' --page '<ページの絶対パス>' [--state '<状態>'] [--delay <秒>]
python3 <skill-dir>/scripts/waiting_notify.py mark --cwd <worktree> --state '判断待ち'
python3 <skill-dir>/scripts/waiting_notify.py send --cwd <worktree> --message 'Q1:本番への反映の時刻を決めてください'
python3 <skill-dir>/scripts/waiting_notify.py clear --cwd <worktree>
mark --goal --page: 印を付ける。最初の1回は両方が要る。状態の既定は「進行中」。印はworktreeごとに1つで、${XDG_STATE_HOME:-~/.local/state}/human-notify/marks/に置かれる(リポジトリの中には何も書かない)。markを実行したセッションのIDを、ホストが渡す環境変数から記録し、そのセッションの停止だけを知らせる。引き継いだセッションはmark --goal --pageをやり直す。mark --state: 状態が変わるたびに呼ぶ。渡した項目だけが変わる。待っていた知らせは取り下げられるので、再開した時は最初に「進行中」へ戻す。「完了」にすると、完了を知らせた後に印が自動で消える(知らせに失敗した時は印を残し、次の停止でもう一度知らせる)。send: 作業を続けたまま、いますぐ知らせる。届けられなかった時は0以外で終わるので、チャットで伝える。clear: 完了にせずゴールを手放す時に、印を消す。以後は知らせない。--delay: 止まり方を宣言した時に待つ、静かな秒数(既定20)。
配線は要らない。 toolbox pluginが、ホストの Stop と PermissionRequest にこのscriptを登録する(hooks/hooks.json)。Claude Codeでは、APIのエラーでターンが終わった時の StopFailure も登録する(hooks/claude-code.json)。hookは印が無ければ何もせずに終わり、常駐するプロセスも無い。ホストごとに、一度だけ次を確かめる。
- Codex: 新しいhookは、人が確認して許可するまで実行されない。起動時に確認を求める表示が出たら、
/hooksで内容を見て許可する。 - sandboxで書込みを制限しているホスト: 状態の置き場(
~/.local/state/human-notify)を書込み許可に加える(Codexはsandbox_workspace_write.writable_roots、Claude Codeはpermissions.additionalDirectories)。許可が無いとmarkは失敗し、そのことを表示する。Codexの標準のsandboxは、リポジトリの外とGitディレクトリへの書込みを止める。
知らせる時機は次のとおり。
| 場面 | 知らせるまで |
|---|---|
| 止まり方を宣言した停止(状態が「進行中」以外) | 静かになって約20秒 |
| 宣言の無い停止(状態が「進行中」のまま) | 静かになって約2分。長いtool実行の最中かもしれないため、長く待つ |
| 許可待ち | すぐ |
| APIのエラーでターンが終わった(Claude Code) | すぐ |
- ターンの終わりは、まだ停止ではない。ホストが次のターンを自分で始めることがあるので、transcriptへの最後の書込みから静かさを測る。新しいターンの終わり、印の更新、印の消去のどれかがあれば、古い待ちは取り下げる。宣言の無いターンの終わりの直後に、印に触れないまま長いtoolを実行すると、transcriptが静かなので、止まったものとして知らせることがある。
- 届けた結果は
${XDG_STATE_HOME:-~/.local/state}/human-notify/waiting.logに、1イベント1行のJSONで残る。delivered(届けた)、superseded(新しいターンに取り下げられた)、cleared(印が消えた)、expired(45分待っても静かにならなかった)、error(OSの通知に失敗した)、skipped(使える通知手段が無い)、other-session(同じworktreeの別のセッションだったので知らせなかった)のどれかである。知らせが来ない時は、まずこの記録を見る。 - macOSではデスクトップのバナーで出る。scriptを実行するアプリ(
osascript)の通知を、システム設定で許可しておく。Linuxではnotify-sendを使う。どちらも無い環境では知らせず、skippedを残す。 deliveredはOSのコマンドが終わったことを表し、人が見た保証ではない。集中モードや通知の不許可では表示されない。届かない環境では、そのことを人に伝え、チャットでの報告に頼る。
バナーは見落とされうる。見落とすと損が大きい連絡は、次節の急ぎの連絡で届ける。
急ぎの連絡を使う場面
- 人間の判断・作業が必要で期限までの猶予が短い、重要な作業が回答待ちで止まった、重大な問題の即時連絡が必要なとき。
- ユーザーが通知を明示依頼したとき。
- 通常の進捗や回答記録はチャットだけ。承認待ちになっただけでは、ダイアログと読み上げを自動で鳴らさない。
依頼と推奨・期限を、ゴールのページなどの詳細参照先へ保存してからチャットにリンクを出し、通知する。詳細の正本を通知側に複製しない。 macOS GUIセッション向けのadapterを同梱する。
急ぎの連絡の初回設定
python3 <skill-dir>/scripts/human_notify.py devices
python3 <skill-dir>/scripts/human_notify.py configure --device-id <内蔵スピーカーのID>
一覧から出力先を選ぶ。初回はユーザーが意図した出力先を確認して設定し、実通知のテストで見える・聞こえることを確認する。 設定したデバイスの名前を実行時に照合し、番号変更に追随する。不在・同名複数なら音声だけ失敗とし、既定出力へ切り替えない。 ヘッドホンの接続状態やシステム全体の出力先・音量を変えない。 設定・保存場所・実機確認は macOS adapter を参照する。
急ぎの連絡の実行
python3 <skill-dir>/scripts/human_notify.py send \
--cwd <対象repoの作業ディレクトリ> \
--event 'goal:release:Q12' --revision '1' \
--message 'Q12:リリース判断をお願いします。期限:15:00 JST' \
--speech 'ゴールのページのQ12をご確認ください。' \
--detail <ゴールのページのパスまたはURL>
python3 <skill-dir>/scripts/human_notify.py status <返されたjobのID>
- repo名は画面タイトルと音声の先頭へ必ず付ける。 originからowner/repoを取得し、無ければmain repo名を使う。worktreeでも共通Gitディレクトリを識別に使う。
- 別repoで同名になる場合やrepo表示名を変える場合は
--repo-label owner/repoを明示する。Git repo以外は現在非対応。対象を推測して別repoから実行しない。 - 読み上げは「owner/repoの件です。ゴールのページのQ12をご確認ください。」。「急ぎの確認があります」は付けない。
--speechにrepo名を重ねない。 - eventは同じゴール・依頼で固定する。ゴールが複数あれば、ゴールの識別子も含める。revisionは期限・必要な判断が大きく変わったときだけ増やし、文面修正や再開では増やさない。
- repo・event・revisionが同じなら重複として省略する。自動再通知はしない。失敗後に再通知が必要なら失敗を確認し、明示的な再試行としてrevisionを変える。
- 入力はCLI引数として渡す。shell文字列へ未エスケープで連結しない。秘密や詳細本文を読み上げない。
結果と待機
send は別プロセスを起動して started とjob ID・PIDを返す。返されたjobを索引へ残し、独立した作業を続けてよい。
起動だけを成功とせず、後のtool境界で status を回収する。端末単位のlockでダイアログ・音声を直列化するので、別通知の後ろで待つ場合がある。
duplicate: 同じ依頼は起動済み。既存jobを確認する。completed: OSコマンドの実行終了。人間が聞いた・理解した保証ではない。partial-failure: 画面・音声の一方以上が失敗。各channelの結果を確認し、チャットで知らせる。pending-or-interrupted: 結果がまだ無い。待機中・実行中・中断のどれかで、成功と扱わない。PIDを照合し、同じ通知を無条件に再送しない。error: 設定・対応環境等の問題。チャットと依頼の正本を維持する。
ダイアログはOKまたは60秒で閉じる。OKは通知を閉じる操作で、承認・回答ではない。 回答は従来のチャット等から取得する。 表示と音声は独立して開始する。集中モード・出力音量・端末のスリープ・ホストによる子プロセス終了等で到達は保証できない。 どちらの経路も、常駐監視・エージェント再起動・定期再通知・外部サービスへの送信は行わない。