agent-doorbell

Agent Doorbell

メインのエージェントが停止したときや入力を必要としているときに、ユーザーの注意を促すランタイムフックを管理するには、このスキルを使用します。子エージェント、チームメイト、中間のタスク活動は通知しません。リマインダーはランタイムフックが担当します。

基本ルール

このスキルはフックマネージャーです。最新のユーザーリクエストで agent-doorbell が明示的に呼び出された場合、リクエストにアンインストール、削除、または無効化の指示がない限り、デフォルトのランタイムフックをインストールまたは更新します。エージェントが最終応答を送信しようとしているという理由だけで、このスキルを使用してはいけません。

フックがインストールされると、ランタイムは OS ネイティブのランナーを呼び出し、すぐに制御を返します。同じ停止イベントに対して、手動のドアベルヘルパーも実行してはいけません。

アクションの振り分け

ユーザーの意図	アクション
agent-doorbell、インストール、セットアップ、有効化、更新、リマインダーの自動化	フックをインストールまたは更新
アンインストール、削除、無効化、ドアベルフックをオフにする	フックをアンインストール
テスト、ドライラン、プレビュー	インストーラーを --dry-run 付きで実行
通常の最終応答、進捗報告の一時停止、内部チェックリストの手順	このスキルを実行しない

ユーザーがこのターンでツール、シェルコマンド、通知、または設定の変更を禁止している場合、フック設定を書き込んではいけません。セットアップを見送ったことを簡潔に説明します。

ランタイムのデフォルト設定

ランタイム	デフォルトのイベント	設定対象	備考
Claude Code	Elicitation、PermissionRequest、Stop、StopFailure、フィルター済みの Notification	~/.claude/settings.json	command、args、async: true、timeout、statusMessage を指定する、実行可能形式のコマンドフックを使用します。
Gemini CLI	AfterAgent	~/.gemini/settings.json	コマンド文字列、ミリ秒単位のタイムアウト、中立的な JSON 出力を使用します。
Codex	Stop	~/.codex/hooks.json	コマンド文字列と秒単位のタイムアウトを使用します。新しい定義は /hooks で確認してください。
Copilot CLI	agentStop	<COPILOT_HOME or ~/.copilot>/hooks/agent-doorbell.json	直接の exec、args、timeoutSec を指定するバージョン 1 のフラット形式のフックを使用します。プロジェクトスコープは .github/hooks/agent-doorbell.json です。
Cursor	stop	~/.cursor/hooks.json	バージョン 1 のフラット形式のフックを使用します。完了ステータスを読み取るには、明示的に --runner node を指定する必要があります。エラー時は failed を鳴らし、中断された実行では通知しません。
その他のエージェントランタイム	ランタイム固有の停止／終了／入力イベント	ランタイム固有のローカル設定	ランタイムに文書化されたライフサイクルフックがある場合に限り、設定してください。プラグインのみでの統合に関する制限については、ランタイムアダプターを参照してください。

オペレーティングシステム	デフォルトのフックランナー	備考
Windows	powershell.exe + scripts/hook-runner.ps1	同梱の WAV 再生とトレイ／デスクトップ通知には ring.ps1 を使用します。
macOS	/bin/sh + scripts/hook-runner.sh	同梱の WAV には afplay、通知には osascript を使用し、フォールバックとしてシステムビープを使用します。
Linux	/bin/sh + scripts/hook-runner.sh	同梱の WAV には paplay または aplay、利用可能な場合は notify-send を使用し、制御端末が利用可能な場合はフォールバックとして端末ベルを鳴らします。

共有 Claude 注意イベントには、子 agent_id を含まない有効な JSON オブジェクトが必要です。POSIX ランナーはこの確認に jq を使用します。jq がない場合、共有イベントは通知されませんが、完了リマインダーは引き続き利用できます。

イベントチャイム

同梱されている44.1 kHzのモノラルPCM WAVファイル5つは、doorbellプラグイン本来のソフトなチャイムのレシピを使用しており、各ファイルの長さは0.6秒未満です。ネイティブランナーはこれらのファイルを直接再生するため、フック実行時に合成ランタイムやプラグインサービスは必要ありません。

イベントまたは理由	チャイム
メインのStop、AfterAgent、CopilotのagentStop、Cursorのcompleted	done
子、チームメイト、中間タスクのイベント	無音
Elicitation、フィルタリングされた注意通知	needs-input
権限リクエスト	approval
ClaudeのStopFailure、Cursorのerror	failed
Cursorのaborted	無音
明示的なblocked理由	blocked
明示的なcancelled理由	無音

フックイベントによって音が決まり、ランナーが応答テキストから目標のブロックを推測することはありません。ランタイムアダプターの説明に従って、メインエージェントのイベントのみを登録し、共有される入力または権限のペイロードをエージェントの識別情報でフィルタリングしてください。子、チームメイト、タスクのライフサイクルイベントは、古いフックが引き続きランナーを呼び出す場合でも無音のままです。注意通知のマッチャーは、バックグラウンドエージェントや定型的な通知を除外します。Elicitationは外部からの入力リクエストを対象とし、アシスタントの応答に含まれるあらゆる質問を対象とするわけではありません。

Claudeの非同期フックは権限の決定を行えず、フックのタイムアウトを無視し、非対話型CLIの終了時に強制終了される場合があります。quietとnormalではシステム音量で1回再生され、loudでは2回再生されます。WAVの再生に失敗した場合は、システムサウンドが代わりに使用されます。プラグイン固有のセッション重複排除、クライアント間のルーティング、ウォーム状態のプレーヤープロセスにはプラグインホストが必要であり、このフックマネージャーの対象外です。

フックコマンドにはマシン固有の実行ファイルやスキルのパスが含まれるため、デフォルトではユーザーのローカル設定を優先してください。プロジェクトごとの動作をユーザーが求めた場合にのみ、プロジェクトのローカル設定を使用してください。

あらゆるエージェントランタイムに対応しようとしないでください。ライフサイクルフックが文書化されているランタイムのみをサポートしてください。文書化されたフックが存在しない場合は、このスキルでは信頼性の高い自動停止リマインダーをまだ利用できないと説明してください。

インストールのワークフロー

1. この SKILL.md を含むスキルディレクトリを特定します。
2. ランタイムを選択します。
   • リクエストで Claude Code に言及している場合、または現在の環境が Claude Code の場合は、claude を使用します。
   • リクエストで Gemini CLI に言及している場合は、gemini を使用します。
   • リクエストで Codex に言及している場合、または現在の環境が Codex の場合は、codex を使用します。
   • Copilot CLI には copilot を使用します。このアダプターはクラウドエージェントを設定しません。
   • cursor を使用するのは、ユーザーが Node ランナーを明示的に選択した場合のみです。ステータスペイロードの解析が必要です。
   • ランタイムが不明な場合は、誤った設定ファイルを書き込む代わりに、短い質問を 1 つしてください。
3. アクションを選択します。
   • ユーザーが agent-doorbell を明示的に呼び出した場合、デフォルトのアクションはインストール／更新です。
   • ユーザーが uninstall、remove、disable、または同等の表現を使った場合は、アンインストールします。
4. 同梱のインストーラーがある場合はそれを実行し、ない場合は以下のフック形式に従って対象の設定 JSON を直接編集します。

Claude Code のインストール：

.\scripts\install-hooks.ps1 -Runtime claude -Scope user

Claude Code のアンインストール：

.\scripts\install-hooks.ps1 -Action uninstall -Runtime claude -Scope user

Gemini CLI のインストール：

.\scripts\install-hooks.ps1 -Runtime gemini -Scope user

Gemini CLI のアンインストール：

.\scripts\install-hooks.ps1 -Action uninstall -Runtime gemini -Scope user

Codex のインストール／更新：

.\scripts\install-hooks.ps1 -Runtime codex -Scope user

Codex のアンインストール：

.\scripts\install-hooks.ps1 -Action uninstall -Runtime codex -Scope user

Node が使用可能な場合に macOS/Linux で役立つ、Node を使ったインストーラーの例：

node scripts/install-hooks.js --runtime claude --scope user
node scripts/install-hooks.js uninstall --runtime claude --scope user
node scripts/install-hooks.js --runtime gemini --scope user
node scripts/install-hooks.js --runtime codex --scope user
node scripts/install-hooks.js --runtime copilot --scope user
node scripts/install-hooks.js --runtime cursor --scope user --runner node

プロジェクトローカルの例：

node scripts/install-hooks.js --runtime claude --scope project-local --project-root .
node scripts/install-hooks.js --runtime gemini --scope project --project-root .
node scripts/install-hooks.js --runtime codex --scope project --project-root .

設定を書き込まずに変更内容をプレビューするには、--dry-run を使用します。

.\scripts\install-hooks.ps1 -Runtime claude -Scope user -DryRun

インストーラーは JSON の書き込みを支援するツールです。Claude、Gemini、Codex、Copilot のフックは、デフォルトで OS ネイティブのランナーを使用するため、停止時に Node や Python は必要ありません。Cursor では Node ランナーを明示的に選択する必要があります。PowerShell インストーラーは、残りの 4 つのアダプターに対応しています。Copilot の exec 形式は CLI 専用です。クラウドエージェント用にこのプロジェクトファイルを再利用しないでください。インストーラーは冪等です。置き換えを書き込む前に、既存の Agent Doorbell フックエントリーを削除します。statusMessage／name が Agent Doorbell のもの、または hook-runner.ps1、hook-runner.sh、hook-runner.js を参照するコマンドのみを削除します。また、古い Python ベースのフックを問題なく置き換えられるよう、従来の hook-runner.py エントリーも認識します。

ユーザーが Node ベースのフックを明示的に希望した場合のみ、--runner node を使用します。

node scripts/install-hooks.js --runtime claude --scope user --runner node

フック形式

Windows の Claude Code では、次の形式と同等のエントリーが書き込まれます。

{
  "hooks": {
    "Stop": [{"hooks": [{"type": "command", "command": "powershell.exe", "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "<skill-path>/scripts/hook-runner.ps1", "-Event", "Stop", "-Reason", "done", "-Mode", "both", "-Intensity", "normal", "-Output", "none"], "async": true, "timeout": 10, "statusMessage": "Agent Doorbell"}]}]
  }
}

macOS/Linux の Claude Code では、/bin/sh と scripts/hook-runner.sh が使用され、同じイベント／理由引数が渡されます。

macOS/Linux の Gemini CLI では、シェルで引用符処理したコマンド文字列を使って、次の形式と同等のエントリーが書き込まれます。

{
  "hooks": {
    "AfterAgent": [{"hooks": [{"name": "Agent Doorbell", "type": "command", "command": "/bin/sh <skill-path>/scripts/hook-runner.sh --event AfterAgent --reason done --mode both --intensity normal --output gemini", "timeout": 10000, "description": "Ring a non-blocking Agent Doorbell cue when the agent stops or needs attention."}]}]
  }
}

Windows の Gemini CLI では、代わりに powershell.exe ... hook-runner.ps1 ... -Output gemini のコマンド文字列が使用されます。

適用範囲

• エージェントが停止するという理由だけでフックをインストールしないでください。
• 通常の最終応答の代わりとして、手動でベルを鳴らさないでください。
• ユーザーがプロジェクトスコープを明示的に選択しない限り、共有可能なプロジェクト設定にマシン固有のパスを書き込まないでください。
• フックのサマリーに、シークレット、非公開の識別子、生ログ、大量の出力を含めないでください。
• ウィンドウを開いたり、フォーカスを奪ったり、サウンドをループ再生したりしないでください。
• 未対応のランタイムについては、正確に伝えてください。ライフサイクルフックが文書化されていない場合、このスキルでは信頼性の高い自動停止リマインダーをまだ利用できないと説明してください。
• ペイロード解析が不要なアダプターでは、OS ネイティブのランナーを使用してください。Cursor はユーザーが Node ランナーを選択してから設定し、ランタイム依存関係を黙って追加しないでください。

検証

テストコマンドと想定される動作については、検証を参照してください。アダプターの選択や変更にあたっては、イベントの対応状況、バージョン制約、その他のランタイムの制限について、ランタイムアダプターを確認してください。