# Human Notify

> 人間への連絡を手元の端末へ届ける。急ぎの連絡はrepo名付きの画面表示と音声で、ゴールを進めるセッションが止まった時と許可待ちになった時はデスクトップ通知で知らせる。「Macに通知して」「スピーカーで呼んで」「急ぎの依頼を通知して」を正のトリガーとし、急ぎの連絡時に使う。ゴールを受け入れまで進める管理にはautopilotを使う。通常の進捗報告には使わない。

- Skill: `masashifukuzawa/human-notify` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add masashifukuzawa/human-notify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masashifukuzawa/human-notify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MasashiFukuzawa (https://skillmd.com/u/masashifukuzawa)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/masashifukuzawa/human-notify

---

# Human Notify — 人間へのローカル通知

呼び出し元が通知の必要性・急ぐ理由・期限を判断し、本スキルが端末への表示と読み上げを担当する。
Claude Code / Codexのどちらでも同じCLIを使う。
リモート環境やGUIのない環境では手元の端末へ届くと見なさず、チャットと詳細参照先を残す。

| 経路 | 使う時 | 出方 | script |
|---|---|---|---|
| 止まった時の知らせ | ゴールの印を付けたセッションが、手を止めた・許可待ちになった | デスクトップのバナー（macOS、Linux） | `scripts/waiting_notify.py` |
| 急ぎの連絡 | 期限までの猶予が短い判断・作業、重大な問題 | repo名付きのダイアログと読み上げ（macOS） | `scripts/human_notify.py` |

同じ依頼を、複数の経路から重ねて送らない。

## 止まった時の知らせ

ゴールの印を付けたセッションが、手を止めて静かになった時、APIのエラーでターンが終わった時、許可待ちになった時に、案件名・状態・ゴール名をデスクトップへ知らせる。印の無いworktreeのセッションと、同じworktreeにいる別のセッション（レビューの実行など）では、何も知らせない。印を付けるのは、ゴールを進めるセッションである（autopilotの「知らせ」の節）。

```bash
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を同梱する。

## 急ぎの連絡の初回設定

```bash
python3 <skill-dir>/scripts/human_notify.py devices
python3 <skill-dir>/scripts/human_notify.py configure --device-id <内蔵スピーカーのID>
```

一覧から出力先を選ぶ。初回はユーザーが意図した出力先を確認して設定し、実通知のテストで見える・聞こえることを確認する。
設定したデバイスの名前を実行時に照合し、番号変更に追随する。不在・同名複数なら音声だけ失敗とし、既定出力へ切り替えない。
ヘッドホンの接続状態やシステム全体の出力先・音量を変えない。
設定・保存場所・実機確認は [macOS adapter](references/macos.md) を参照する。

## 急ぎの連絡の実行

```bash
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は通知を閉じる操作で、承認・回答ではない。** 回答は従来のチャット等から取得する。
表示と音声は独立して開始する。集中モード・出力音量・端末のスリープ・ホストによる子プロセス終了等で到達は保証できない。
どちらの経路も、常駐監視・エージェント再起動・定期再通知・外部サービスへの送信は行わない。

