ガイド

あらゆる AI コーディングエージェントの hook：Claude Code、Cursor、Gemini CLI、GitHub Copilot、Kiro、Factory Droid（2026）

各 AI コーディングエージェントで hook はどこに置き、hook はどうやってコマンドをブロックしますか？

Claude Code は .claude/settings.json の hooks ブロック、Gemini CLI は .gemini/settings.json の hooks ブロックを読み込みます。Cursor は .cursor/hooks.json、Factory Droid は .factory/hooks.json、GitHub Copilot は .github/hooks/*.json、Kiro は .kiro/hooks/ 内の任意の JSON ファイルを読み込みます。どれもイベントを JSON として stdin 経由でスクリプトに渡します。ツール呼び出しをブロックするには、Claude Code、Cursor、Gemini CLI、Factory Droid、Kiro CLI では終了コード 2 で終了するか、deny の判定を JSON で出力します（Copilot は permissionDecision、Cursor は permission を使います）。

このページは英語版ガイドの翻訳です。コマンド、設定キー、コードは原文のままです。内容に差異がある場合は英語版が優先されます。 英語版を読む → · 他の言語: 简体中文 · 한국어 · Español · Português (Brasil)

設定の変更をいち早くチェック

これらのツールの設定、フラグ、権限ルールが変わったときに、週 1 回メール（英語）でお知らせします。内容は公式ドキュメントで確認済みです。

クイックアンサー：hook ファイルの場所

  • Claude Code：.claude/settings.json（プロジェクト）または ~/.claude/settings.json（ユーザー）の hooks キー。/hooks で設定内容を確認できます。
  • Cursor：.cursor/hooks.json（プロジェクト）または ~/.cursor/hooks.json（ユーザー）で、"version": 1 を指定します。Enterprise と Team の hook はその両方より上位です。
  • Gemini CLI：.gemini/settings.json（プロジェクト）、~/.gemini/settings.json（ユーザー）、または /etc/gemini-cli/settings.json（システム）の hooks キー。
  • GitHub Copilot：cloud agent と Copilot CLI には .github/hooks/*.json、CLI ではさらに ~/.copilot/hooks/。"version": 1。
  • Kiro：.kiro/hooks/（ワークスペース）または ~/.kiro/hooks/（グローバル、CLI V3）内の任意の .json ファイルで、"version": "v1" を指定します。
  • Factory Droid：.factory/hooks.json（プロジェクト）または ~/.factory/hooks.json（ユーザー）。/hooks で hook マネージャーが開きます。

hook がツール呼び出しをブロックする仕組み

  • Claude Code：PreToolUse hook が 2 で終了するとアクションがブロックされ、stderr の内容が理由として返されます。
  • Cursor：2 で終了するか、{"permission": "deny"} を出力します。それ以外の非ゼロコードは、hook で failClosed: true を設定しない限り fail open（許可）になります。
  • Gemini CLI：0 で終了して {"decision": "deny", "reason": "..."} を出力する（推奨）か、stderr に理由を書いて 2 で終了します。その他のコードは警告のみです。
  • GitHub Copilot：preToolUse hook で {"permissionDecision": "deny", "permissionDecisionReason": "..."} を出力します。何もしなければ呼び出しは許可されます。
  • Kiro：CLI では、2 で終了すると PreToolUse がブロックされます。IDE では、非ゼロで終了すると Pre Tool Use hook がブロックします。
  • Factory Droid：PreToolUse で 2 で終了するとツール呼び出しがブロックされます。その他の非ゼロコードはログに記録され、Droid は処理を続けます。

考え方は同じ、イベント名は異なる

  • ツール実行前：PreToolUse（Claude Code、Kiro、Factory Droid）、preToolUse と beforeShellExecution（Cursor）、BeforeTool（Gemini CLI）、preToolUse（Copilot）。
  • ツール実行後：PostToolUse（Claude Code、Kiro、Factory Droid）、postToolUse と afterFileEdit（Cursor）、AfterTool（Gemini CLI）、postToolUse（Copilot）。
  • セッション開始：SessionStart（Claude Code、Kiro、Factory Droid、Gemini CLI）、sessionStart（Cursor、Copilot）。
  • エージェント終了：Stop（Kiro、Factory Droid）、stop（Cursor）、agentStop（Copilot）。
  • prompt 送信時：UserPromptSubmit（Kiro、Factory Droid）、beforeSubmitPrompt（Cursor）、userPromptSubmitted（Copilot）。

同じ hook を 4 つの構文で

Claude Code：.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Cursor：.cursor/hooks.json

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/block-risky.sh",
        "matcher": "rm -rf|curl|wget"
      }
    ]
  }
}

Gemini CLI：.gemini/settings.json

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Kiro：.kiro/hooks/guard-shell.json

{
  "version": "v1",
  "hooks": [
    {
      "name": "Guard shell commands",
      "trigger": "PreToolUse",
      "matcher": "shell",
      "action": {
        "type": "command",
        "command": "./scripts/guard.sh"
      }
    }
  ]
}

注意点

  • Gemini CLI の stdout には最終的な JSON だけを出力する必要があります。無効な JSON は allow として扱われます。
  • Gemini CLI は、名前やコマンドが変更されたプロジェクト hook を実行する前に警告します（例：git pull の後）。
  • Copilot は toolArgs を JSON 文字列として渡すため、2 回パースします。cloud agent は "ask" の判定を "deny" として扱い、hook はデフォルトブランチからのみ読み込みます。
  • Cursor のプロジェクト hook はプロジェクトルートから、ユーザー hook は ~/.cursor/ から実行されるため、スクリプトの相対パスが異なります。
  • Kiro の agent prompt アクションは新しいエージェントループを開始し、クレジットを消費します。シェルコマンドアクションは消費しません。
  • Factory Droid の matcher は大文字小文字を区別する正規表現です。Execute 呼び出しをコマンドのテキストで絞り込むには commandRegex を使います。

エージェント別の完全な hook ガイド

出典

このガイドで確認した公式ドキュメント（英語）です。 英語版の確認日: 2026-10-18

Claude Code: Automate actions with hooksCursor: HooksGemini CLI: HooksGemini CLI: Hooks referenceGitHub Docs: Hooks referenceGitHub Docs: Use hooks with Copilot CLIKiro Docs: HooksFactory: Hooks

その他の日本語ガイド