フックについて

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

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

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

Copilot エージェントは、リポジトリ内の JSON ファイルに格納されているフックをサポートしています .github/hooks/*.json。

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

Copilot コーディングエージェントは GitHub 上で
GitHub Copilot CLI（コマンドラインインターフェース）をターミナルに表示する

フックの種類

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

        **sessionStart**: 新しいエージェント セッションが開始されたとき、または既存のセッションを再開するときに実行されます。 環境の初期化、監査のためのログ セッションの開始、プロジェクトの状態の検証、一時リソースの設定に使用できます。

        **sessionEnd**: エージェント セッションが完了または終了したときに実行されます。 一時的なリソースのクリーンアップ、セッション レポートとログの生成とアーカイブ、セッション完了に関する通知の送信に使用できます。

        **userPromptSubmitted**: ユーザーがエージェントにプロンプトを送信したときに実行されます。 監査と使用状況分析のユーザー要求をログに記録するために使用できます。

        **preToolUse**: エージェントが任意のツール ( `bash`、 `edit`、 `view`など) を使用する前に実行されます。 これは、 **ツールの実行を承認または拒否**できるため、最も強力なフックです。 このフックを使用して、危険なコマンドをブロックしたり、セキュリティ ポリシーとコーディング標準を適用したり、機密性の高い操作の承認を必要としたり、コンプライアンスのためにログ ツールを使用したりできます。

        **postToolUse**: ツールの実行が完了した後に実行されます (成功したか失敗したか)。 実行結果のログ記録、使用状況の統計の追跡、監査証跡の生成、パフォーマンス メトリックの監視、エラー アラートの送信に使用できます。

        **errorOccurred**: エージェントの実行中にエラーが発生したときに実行されます。 デバッグのエラーのログ記録、通知の送信、エラー パターンの追跡、レポートの生成に使用できます。

ユースケース、ベストプラクティス、高度なパターンの例を含むフックの種類の完全なリファレンスについては、フックの構成を参照してください。

フック構成形式

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

JSON

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

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

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

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

フック構成ファイルの例

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

JSON

{
  "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
      }
    ]
  }
}

{
  "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 ではなく、ファイルへの追加などの非同期ログを使用します。

        **バックグラウンド処理を使用**する: コストの高い操作の場合は、バックグラウンド処理を検討してください。

        **キャッシュ結果**: コストの高い計算を可能な限りキャッシュします。

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

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

        **フックによって処理される入力を常に検証してサニタイズします**。 信頼されていない入力によって、予期しない動作が発生する可能性があります。

        **コマンドを作成するときは、適切なシェル エスケープを使用します**。 これにより、コマンド インジェクションの脆弱性が回避されます。

        **トークンやパスワードなどの機密データをログに記録しないでください**。

        **フック スクリプトとログに適切なアクセス許可があることを確認**します。

        **外部ネットワーク呼び出しを行うフックには注意してください**。 これにより、待機時間、障害が発生したり、サード パーティにデータが公開されたりする可能性があります。

        **リソースの枯渇を防ぐために、適切なタイムアウトを設定します**。 実行時間の長いフックは、エージェントの実行をブロックし、パフォーマンスを低下させる可能性があります。

次のステップ

フックの作成を開始するには、 GitHub Copilot エージェントを使ったフックの活用を参照してください。

フックについて

この機能を使用できるユーザーについて

この記事の内容