{"meta":{"title":"GitHub Copilot CLI でフックを使用する","intro":"エージェントの実行中 GitHub Copilot キー ポイントでカスタム シェル コマンドを使用して、エージェントの動作を拡張します。","product":"GitHub Copilot","breadcrumbs":[{"href":"/ja/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/ja/enterprise-cloud@latest/copilot/how-tos","title":"方法"},{"href":"/ja/enterprise-cloud@latest/copilot/how-tos/copilot-cli","title":"Copilot CLI"},{"href":"/ja/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot","title":"Copilot CLI のカスタマイズ"},{"href":"/ja/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-hooks","title":"フックを使用する"}],"documentType":"article"},"body":"# GitHub Copilot CLI でフックを使用する\n\nエージェントの実行中 GitHub Copilot キー ポイントでカスタム シェル コマンドを使用して、エージェントの動作を拡張します。\n\nフックを使用すると、エージェントの実行中にキー ポイントでカスタム シェル コマンドを実行することで、 GitHub Copilot エージェントの動作を拡張およびカスタマイズできます。 使用可能なフック トリガーの詳細など、フックの概念の概要については、 [フックについて GitHub Copilot](/ja/enterprise-cloud@latest/copilot/concepts/agents/hooks) を参照してください。\n\n## 前提条件\n\n**Windowsユーザーのみ:** この記事のフック例は、Windows、Linux、macOS で実行するように設計されています。 Windowsの場合、PowerShell を使用するため、PowerShell 7.0 以降をインストールして PATH にインストールする必要があります。 ターミナルで `pwsh --version` を実行することで、PowerShell のバージョンを確認できます。 PowerShell をインストールするには、`winget install Microsoft.PowerShell` を実行し、ターミナルを再起動します。\n\n## リポジトリ レベルのフックの作成\n\n1. リポジトリの`NAME.json` フォルダーに新しい`NAME` ファイル (`.github/hooks/`ファイルの目的を説明するファイル) を作成します。\n\n2. テキスト エディターで、次のフック テンプレートをコピーして貼り付けます。 使用する予定のないフックを `hooks` 配列から削除します。\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"sessionStart\": [...],\n \"sessionEnd\": [...],\n \"userPromptSubmitted\": [...],\n \"preToolUse\": [...],\n \"postToolUse\": [...],\n \"errorOccurred\": [...]\n }\n }\n ```\n\n3. `bash`キーと`powershell` キーでフック構文を構成するか、作成したスクリプト ファイルを直接参照します。\n\n > \\[!NOTE]\n > `bash` キー (Linux および macOS 用のスクリプトを含む) と `powershell` キー (Windows 用スクリプト用) の両方を含めて、3 つのオペレーティング システムすべてでフックを実行できるようにします。 Copilot は、ユーザーのオペレーティング システムに基づいて適切なキーを使用します。\n\n * 次の例では、 `sessionStart` フックを使用してセッションの開始日をログ ファイルに出力するスクリプトを実行します。\n\n ```json copy\n \"sessionStart\": [\n {\n \"type\": \"command\",\n \"bash\": \"echo \\\"Session started: $(date)\\\" >> logs/session.log\",\n \"powershell\": \"Add-Content -Path logs/session.log -Value \\\"Session started: $(Get-Date)\\\"\",\n \"cwd\": \".\",\n \"timeoutSec\": 10\n }\n ],\n ```\n\n * 次の例では、外部 `log-prompt` スクリプトを呼び出します。\n\n ```json copy\n \"userPromptSubmitted\": [\n {\n \"type\": \"command\",\n \"bash\": \"./scripts/log-prompt.sh\",\n \"powershell\": \"./scripts/log-prompt.ps1\",\n \"cwd\": \"scripts\",\n \"env\": {\n \"LOG_LEVEL\": \"INFO\"\n }\n }\n ],\n ```\n\n エージェント セッションからの入力 JSON とサンプル スクリプトの完全なリファレンスについては、 [GitHub Copilotフックリファレンス](/ja/enterprise-cloud@latest/copilot/reference/hooks-reference) を参照してください。\n\n4. ファイルをリポジトリにコミットし、既定のブランチにマージします。 これで、フックはエージェント セッション中に実行されます。\n\n## ユーザー レベルのフックの作成\n\nユーザー レベルのフックはリポジトリ レベルのフックと同じように構成されますが、フック ファイルはローカルのホーム ディレクトリの下に格納されます。\n\nmacOS と Windows の次の例では、CLI がプロンプトに応答し終わったときにサウンドを再生し、メッセージ ボックスを表示するフックを構成し、Copilot CLIを終了する方法を示します。 Linux 用フックは macOS の例に似ていますが、サウンドの再生やメッセージの表示には Linux ツールを使用します。\n\n### macOS のユーザー レベルの例\n\n1. `notification-hooks.json`で `~/.copilot/hooks/` という名前のファイルを作成します。\n\n > \\[!NOTE]\n > `COPILOT_HOME`が設定されている場合は、`$COPILOT_HOME/hooks/`でファイルを作成します。\n\n2. 次の JSON をコピーしてファイルに貼り付けます。\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"bash\": \"osascript -e 'do shell script \\\"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\\\"' -e 'display dialog \\\"Agent stopped.\\\" with title \\\"Hook-generated message\\\" buttons {\\\"OK\\\"} default button \\\"OK\\\"'\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"bash\": \"osascript -e 'do shell script \\\"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\\\"' -e 'display dialog \\\"Session ended.\\\" with title \\\"Hook-generated message\\\" buttons {\\\"OK\\\"} default button \\\"OK\\\"'\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. Copilot CLIを開始または再起動します。\n\n > \\[!NOTE]\n > フック構成の変更は、CLI の開始時に読み込まれます。\n\n4. プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージ ボックスが表示されることを確認します。\n\n5. これらのフックを削除するには、 `notification-hooks.json` ファイルを削除します。\n\n### Windowsのユーザー レベルの例\n\n1. `notification-hooks.json`で `%USERPROFILE%\\.copilot\\hooks\\` という名前のファイルを作成します。\n\n > \\[!NOTE]\n > `COPILOT_HOME`が設定されている場合は、`%COPILOT_HOME%\\hooks\\`でファイルを作成します。\n\n2. 次の JSON をコピーしてファイルに貼り付けます。\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. Copilot CLIを開始または再起動します。\n\n > \\[!NOTE]\n > フック構成の変更は、CLI の開始時に読み込まれます。\n\n4. プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージ ボックスが表示されることを確認します。\n\n5. これらのフックを削除するには、 `notification-hooks.json` ファイルを削除します。\n\n## トラブルシューティング\n\nフックを使用して問題が発生した場合は、次の表を使用してトラブルシューティングを行います。\n\n| 問題点 | アクション |\n| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| フックが実行されていない | | |\n| フックがタイムアウトする | |\n| 無効な JSON 出力 | |\n\n## デバッグ\n\n次のメソッドを使用してフックをデバッグできます。\n\n* スクリプトで**詳細ログを有効化**して、入力データを検査し、スクリプトの実行を追跡します。\n\n ```shell copy\n #!/bin/bash\n set -x # Enable bash debug mode\n INPUT=$(cat)\n echo \"DEBUG: Received input\" >&2\n echo \"$INPUT\" >&2\n # ... rest of script\n ```\n\n* **テストフックをローカルでテストするために、テスト入力をフックにパイプし**、その動作を検証します。\n\n ```shell copy\n # Create test input\n echo '{\"timestamp\":1704614400000,\"cwd\":\"/tmp\",\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"ls\\\"}\"}' | ./my-hook.sh\n\n # Check exit code\n echo $?\n\n # Validate output is valid JSON\n ./my-hook.sh | jq .\n ```\n\n## 詳細については、次を参照してください。\n\n* [GitHub Copilotフックリファレンス](/ja/enterprise-cloud@latest/copilot/reference/hooks-reference)\n* [クラウド エージェントGitHub Copilotについて](/ja/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [GITHUB COPILOT CLI について](/ja/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-copilot-cli)\n* [開発環境を構成する](/ja/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)"}