# AIエージェント 音声・スマホ・腕時計通知インストールかんたんキット

バージョン：2026-08-31  
対象環境：macOS  
用途：このファイルを、手元のファイルとターミナルを操作できる AI に渡し、AIエージェントの「タスク完了」「判断待ち」「失敗」通知の設定を手伝ってもらう。

---

## 利用者の方へ

1. このファイルを、信頼でき、かつこの Mac を操作できる AI に渡す。
2. 次のように伝える：「ファイルどおりに実行してください。まず検知と計画を行い、私の同意を得てから変更してください。」
3. AI は、あなたが使っているのが Claude Code、Codex、または他の AIエージェントか、およびこの Mac に既に通知設定があるかを先に調べる。
4. Pushover のキー、アカウントログイン、システムの権限、または不確かな既存設定に出会ったときは、あなた本人が操作する。

このかんたんキットは、あらゆる AIエージェントが手元のイベント通知に対応していることを保証しない。プラットフォームに正式な hook、イベント、または拡張の入口がない場合、AI はそこで止まって制限を説明しなければならず、代わりに定期ポーリングや常駐プログラムを自分で作ってはならない。

---

## 以下は AI に渡す作業説明

あなたは、プログラム設定に慣れていない macOS 利用者を手伝っている。任務は、信頼できる AIエージェントの進捗通知を作ることであり、利用者が画面を見続けなくても、正しいタイミングで次を受け取れるようにする：

- タスク全体が完了したこと、および何が完了したかが分かる。
- AIエージェントが人の承認、選択、または追加資料を必要としており、何を決めるべきかが分かる。
- 作業が本当に続行できないとき、どこで止まっているかが分かる。

通知の出力は、利用者の選択に応じて次を含んでよい：

- macOS のローカル音声。
- Pushover による iPhone への送信。
- Apple Watch が iPhone 通知のミラー表示または振動で知らせる。

### 最優先ルール

1. まず検知と計画を行い、利用者の明確な同意を得てから変更する。
2. 既存設定を上書きしたり削除したりしない。まず読み取り、衝突を説明し、そのうえで最小の変更にする。
3. 利用者に API token、パスワード、その他の秘密を会話へ貼るよう求めない。権限を制限したローカルのひな型だけを作り、そこで止まって利用者本人に記入してもらう。
4. ログイン、MFA、有料手続き、アカウント認可、システムのプライバシー権限、またはキー入力に出会ったら、直ちに止まって利用者へ戻す。
5. 通知 hook は知らせるだけであり、利用者の承認、拒否、回答の代わりになってはならない。
6. 各イベントの通報は最大1回。周期的に再再生する daemon、launchd ジョブ、または自動リトライのループを作ってはならない。
7. Pushover は常に通常優先度 `priority=0` を使う。確認されるまで繰り返し続ける緊急優先度を使ってはならない。
8. テストは必ず `TEST` と標示し、一度に有効化する出力先は1つだけにする。
9. 通知の重複、イベント意味の不明、またはタスク全体を安全に識別できない場合は、直ちに通知を無効化し、変更を止める。
10. 未検証のスマホ到達や Apple Watch の振動を成功と称してはならない。利用者が本人で確認しなければならない。

## 第1段階：検知のみ。変更しない

次の検査を完了し、結果を一般の利用者が分かる言い方で列挙する：

1. オペレーティングシステムが macOS であること、および現在使っている shell を確認する。
2. インストール済みの AIエージェントとバージョンを検知する。例：Claude Code、Codex、または利用者が指定したプラットフォーム。新しい AIエージェントを自分でインストールしない。
3. そのバージョンの現行公式ドキュメントを調べ、利用可能な完了、権限リクエスト、入力待ち、失敗イベントを確認する。記憶上のイベント名だけに頼らない。
4. 既存設定と hook を読むが、秘密の内容を表示してはならない。Claude Code のよくある場所は `~/.claude/settings.json` と `~/.claude/hooks/`；Codex のよくある場所は `~/.codex/config.toml`、`~/.codex/hooks.json`、`~/.codex/hooks/`。実際のパスは手元の環境と公式ドキュメントを正とする。
5. すでに音声、Pushover、通知スクリプト、背景プロセス、または同一イベントを同時に扱う複数の hook がないか確認する。
6. `/usr/bin/say`、Python 3、および必要なシステムコマンドが使えるか確認する。
7. 利用者がどの出力を必要とするか尋ねる：Mac 音声のみか、さらに Pushover、iPhone、Apple Watch もか。
8. 変更予定の各ファイル、用途、無効化の方法、テスト方法、および利用者が本人で完了すべき手順を説明する。

検知が終わったら止まり、利用者が計画に同意するのを待つ。同意なしに次の段階へ進んではならない。

## 第2段階：通知の骨格を作る

同意を得たら、プラットフォームの能力に従って実装する。固定パスの丸写しより、次の骨格を優先して守る：

```text
AIエージェントの正式イベント
├─ タスク全体の完了
├─ 人の判断が必要
└─ 本当に続行できない
          │
          ▼
プラットフォームイベント接続部：イベントを解析し、出所と作業内容を識別
          │
          ▼
安全コア：内容のマスク、単発ロック、頻度ヒューズ、無効化スイッチ
          │
          ├─ macOS 音声
          └─ Pushover → iPhone → Apple Watch
```

### イベントの意味

- 毎回の応答停止、ツール手順の終了、または段階的なメッセージを、そのまま「タスク全体の完了」と呼んではならない。
- Claude Code が `Stop` を使う場合は、明確なタスク全体の印、または他の信頼できるゲートを必ず付ける。印がないときは沈黙を保つ。
- Codex が `agent-turn-complete` を使う場合は、現行バージョンが主タスクの最終結果と段階的出力を確実に区別できることを確認しなければならない。
- 判断待ち通知は、プラットフォーム正式の権限リクエストまたは入力待ちイベントを優先する。例：現行バージョンのドキュメントにある `PermissionRequest`。イベント名は必ずその場で照合する。
- プラットフォームがイベントを確実に区別できない場合、安全な既定は通知しないことであり、利用者に制限を説明する。

### 通知の内容

各通知には出所と安全な要約を含める。例：

- `Claude のタスクが完了しました：ウェブサイト記事の下書きを完成しました。`
- `Codex はあなたの判断が必要です：指定の設定ファイルの変更を許可するか。`
- `Claude は続行できません：利用者から提供される入力データが不足しています。`

要約は次を守らなければならない：

- イベント内の公開説明を優先して使う。
- 長さを制限する。目安は 120 文字以内。
- API token、パスワード、Bearer token、完全なローカルパス、生のターミナルコマンド、その他の秘密になり得るものをマスクする。
- 安全な説明がないときは、ツールの種類だけを述べ、画面に戻って確認するよう利用者に求め、生の入力を読み上げたりプッシュしたりしてはならない。

### 単発と無効化の設計

- 各 hook は短命プロセスを1つだけ起動し、通知が終わったら直ちに終了する。
- アトミックな単発ロックを使う。例：SQLite の一意主キー、またはプラットフォームに適した一度きりのタスク印。
- さらに短時間の頻度ヒューズを加え、上流のイベント ID が変わったときに大量通知が出ないようにする。
- 複数ウィンドウの音声にはキューまたは排他ロックを使い、音が重ならないようにする。
- 分かりやすい有効化ファイルまたは無効化スイッチを作る。無効化中は、音声もプッシュも実行してはならない。
- ネットワーク失敗は手元に記録してよいが、Pushover を自動再送してはならない。

### Pushover と秘密

利用者が Pushover を選んだ場合：

1. ローカルの認証情報ひな型を作る。例：`~/.config/ai-agent-notify/pushover.env`。
2. ディレクトリ権限を `700`、認証情報ファイルを `600` にする。
3. そこで止まり、利用者本人に `PUSHOVER_TOKEN` と `PUSHOVER_USER` を記入してもらう。
4. 読み出さない、表示しない、記録しない、認証情報を repository に書き込まない。
5. 常に `priority=0` を使い、自動リトライしない。

## 第3段階：層ごとのテスト

次の順でテストし、各層が通ってから次の層へ進む：

1. **無効化テスト**：通知スイッチがオフのとき、すべてのイベントが沈黙を保つ。
2. **ドライランテスト**：手元のテスト記録だけを書き、音声を再生せず、ネットワークも呼ばない。
3. **単発ロックテスト**：同一の偽イベントを2回入れると、最初の1回だけが受理される。
4. **完了意味テスト**：段階的な応答は通知せず、タスク全体だけを1回通知する。
5. **判断待ちテスト**：同一リクエストは1回だけ通知し、内容は何を決めるべきかを説明でき、元の Agent は利用者の操作を待ち続ける。
6. **Mac 音声テスト**：`TEST` と標示した短い音声を1本だけ再生する。
7. **Pushover テスト**：利用者の同意を得てから、通常優先度で `TEST` と標示したメッセージを1通だけ送る。
8. **iPhone と Apple Watch テスト**：利用者本人に、通知権限、Watch App のミラー、集中モード、消音、装着とロック解除の状態を確認してもらい、届いたか・振動したかを報告してもらう。
9. **総スイッチテスト**：再度無効化し、背景プロセスが再生や送信を続けていないことを確認する。

どの一歩でも失敗したら、以降の出力は閉じたままにする。テストを通すために完了条件を緩めたり、重複排除を止めたり、リトライを増やしたりしてはならない。

## 完了時の報告形式

完了後、利用者へ次を提供する：

1. 対応済みの AIエージェントとイベント種類。
2. 変更または追加したファイルと用途。
3. 通知の無効化方法。
4. 通過したテスト、および誰が確認したか。
5. まだ検証していない部分、またはプラットフォームが非対応の部分。
6. 今後 AIエージェントをアップグレードしたあと、再テストが必要な項目。

タスク全体、判断待ち、単発ロック、無効化スイッチ、および利用者が選んだ出力先について、それぞれ対応する検証が完了して初めて、設定完了と言える。