# フックについて GitHub Copilot

エージェントの実行中 GitHub Copilot キー ポイントでカスタム シェル コマンドを実行して、エージェントの動作を拡張およびカスタマイズします。

## フックとは何か

フックは、エージェント セッションの開始または終了、プロンプトの入力時、ツールの呼び出し時など、エージェントのワークフロー内の戦略的なポイントでカスタム シェル コマンドを実行する方法です。

フックは JSON 入力を介してエージェント アクションに関する詳細情報を受け取り、コンテキスト対応の自動化を可能にします。 たとえば、フックを使用して次のことができます。

* プログラムによってツールの実行を承認または拒否します。
* シークレット スキャンなどの組み込みのセキュリティ機能を使用して、資格情報の漏洩を防ぎます。
* コンプライアンスのためにカスタム検証規則と監査ログを実装します。

フックは以下で使用できます。

* **Copilot cloud agent** に GitHubする。
* **GitHub Copilot CLI** ターミナルで

json ファイルでフックを定義し、 `.github/hooks/*.json`のリポジトリに格納します。 これらは、 Copilot エージェントがリポジトリで使用されるたびに適用されます。
Copilot CLI では、 `~/.copilot/hooks/*.json`のホーム ディレクトリに格納する個人用フックもサポートされます。 これらは、 Copilot CLIを使用するたびに適用されます。

## フックの種類

次の種類のフックを使用できます。

* **sessionStart**: 新しいエージェント セッションが開始されたとき、または既存のセッションを再開するときに実行されます。 環境の初期化、監査のためのログ セッションの開始、プロジェクトの状態の検証、一時リソースの設定に使用できます。
* **sessionEnd**: エージェント セッションが完了または終了したときに実行されます。 一時的なリソースのクリーンアップ、セッション レポートとログの生成とアーカイブ、セッション完了に関する通知の送信に使用できます。
* **userPromptSubmitted**: ユーザーがエージェントにプロンプトを送信したときに実行されます。 監査と使用状況分析のユーザー要求をログに記録するために使用できます。
* **preToolUse**: エージェントが任意のツール ( `bash`、 `edit`、 `view`など) を使用する前に実行されます。 これは、 **ツールの実行を承認または拒否**できるため、最も強力なフックです。 このフックを使用して、危険なコマンドをブロックしたり、セキュリティ ポリシーとコーディング標準を適用したり、機密性の高い操作の承認を必要としたり、コンプライアンスのためにログ ツールを使用したりできます。
* **postToolUse**: ツールの実行が完了した後に実行されます (成功したか失敗したか)。 実行結果のログ記録、使用状況の統計の追跡、監査証跡の生成、パフォーマンス メトリックの監視、エラー アラートの送信に使用できます。
* **agentStop**: メイン エージェントがプロンプトへの応答を完了したときに実行されます。
* **subagentStop**: 親エージェントに結果を返す前に、サブエージェントが完了したときに実行されます。
* **errorOccurred**: エージェントの実行中にエラーが発生したときに実行されます。 デバッグのエラーのログ記録、通知の送信、エラー パターンの追跡、レポートの生成に使用できます。

ユース ケース、ベスト プラクティス、高度なパターンの例を含むフックの種類の完全なリファレンスについては、 [GitHub Copilotフックリファレンス](/ja/copilot/reference/hooks-reference) を参照してください。

## フック構成形式

特殊な JSON 形式を使用してフックを構成します。 JSON には、値が `version` の`1` フィールドと、フック定義の配列を含む`hooks` オブジェクトが含まれている必要があります。

```json copy
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}
```

フック オブジェクトには、次のキーを含めることができます。

| 財産                      | 必須                | Description                            |
| ----------------------- | ----------------- | -------------------------------------- |
| `type`                  | イエス               |                                        |
| `"command"` にする必要があります。 |                   |                                        |
| `bash`                  | はい (Unix システムの場合) | 実行する bash スクリプトへのパス                    |
| `powershell`            | はい (Windows)      | 実行する PowerShell スクリプトへのパス              |
| `cwd`                   | いいえ               | スクリプトの作業ディレクトリ (リポジトリ ルートに対する相対ディレクトリ) |
| `env`                   | いいえ               | 既存の環境とマージされる追加の環境変数                    |
| `timeoutSec`            | いいえ               | 最大実行時間 (秒単位) (既定値: 30)                 |

## フック構成ファイルの例

これは、リポジトリ内の `~/.github/hooks/project-hooks.json` に存在する構成ファイルの例です。

```json copy
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo \"Session started: $(date)\" >> logs/session.log",
        "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
        "cwd": ".",
        "timeoutSec": 10
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}
```

## パフォーマンスに関する考慮事項

フックは同期的に実行され、エージェントの実行をブロックします。 応答性の高いエクスペリエンスを確保するには、次の考慮事項に留意してください。

* **実行時間を最小限に抑える**: 可能な場合は、フックの実行時間を 5 秒以下にしてください。
* **ログ記録の最適化**: 同期 I/O ではなく、ファイルへの追加などの非同期ログを使用します。
* **バックグラウンド処理を使用**する: コストの高い操作の場合は、バックグラウンド処理を検討してください。
* **キャッシュ結果**: コストの高い計算を可能な限りキャッシュします。

## セキュリティに関する考慮事項

フックを使用するときにセキュリティが維持されるようにするには、次の点に注意してください。

* **フックによって処理される入力を常に検証してサニタイズします**。 信頼されていない入力によって、予期しない動作が発生する可能性があります。
* **コマンドを作成するときは、適切なシェル エスケープを使用します**。 これにより、コマンド インジェクションの脆弱性が回避されます。
* **トークンやパスワードなどの機密データをログに記録しないでください**。
* **フック スクリプトとログに適切なアクセス許可があることを確認**します。
* **外部ネットワーク呼び出しを行うフックには注意してください**。 これにより、待機時間、障害が発生したり、サード パーティにデータが公開されたりする可能性があります。
* **リソースの枯渇を防ぐために、適切なタイムアウトを設定します**。 実行時間の長いフックは、エージェントの実行をブロックし、パフォーマンスを低下させる可能性があります。

## 次のステップ

フックの作成を開始するには、次を参照してください。

* [フックを使用してエージェント ワークフローをカスタマイズする](/ja/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks) for Copilot cloud agent
* [GitHub Copilot CLI でフックを使用する](/ja/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) for GitHub Copilot CLI