AIコーディングCLIのHooks機能比較 — Gemini CLI・Claude Code・Codex CLI

AIコーディングCLI御三家（Gemini CLI、Claude Code、Codex CLI）のHooks機能を比較調査した。Googleが公式ブログでGemini CLIのHooks機能を紹介していたのがきっかけ。

調べてみると、3つのツールで設計思想がかなり違って興味深かった。

Hooksとは

AIコーディングCLIにおけるHooksは、エージェントのライフサイクル（ツール実行前後、セッション開始・終了など）に独自の処理を差し込む仕組み。Webフレームワークのミドルウェアに近い。

典型的なユースケース:

• ツール実行前にバリデーション（危険なコマンドをブロック）
• シークレットの漏洩防止（ファイル書き込み前にスキャン）
• ログ収集・トークンコスト最適化
• セッション開始時にプロジェクト固有のコンテキストを注入

Gemini CLI

2025年7月にGoogleが公式ブログで紹介。v0.26.0以降で利用可能。

設定

.gemini/settings.json に記述する。

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "secret-scanner",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/scan-secrets.sh",
            "description": "Scan for secrets before writing files"
          }
        ]
      }
    ]
  }
}

イベント一覧

イベント	タイミング
SessionStart	セッション開始時
SessionEnd	セッション終了時
BeforeAgent	エージェントターン開始前
AfterAgent	エージェントターン完了後
BeforeModel	LLMリクエスト送信前
AfterModel	LLMレスポンス受信後
BeforeToolSelection	ツール選択前
BeforeTool	ツール実行前
AfterTool	ツール実行後
Notification	通知発生時

10種類。特徴的なのはBeforeModelとBeforeToolSelection。LLMへのリクエスト自体に介入できるのはGemini CLIだけ。

通信プロトコル

• stdinでJSON入力を受け取り、stdoutでJSON出力を返す
• exit code 0で続行、exit code 2でブロック
• BeforeModelではモックレスポンスを返すことも可能（LLM呼び出しをスキップ）
• タイムアウトはデフォルト60秒、カスタマイズ可

設定の階層

プロジェクト → ユーザー → システムの3階層でマージされる。Extensions経由でHooksをバンドル配布できるのもGemini CLIならでは。

Claude Code

Claude Codeも同様のHooks機能を持つ。

設定

.claude/settings.json に記述する。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/validate-bash.py"
          }
        ]
      }
    ]
  }
}

イベント一覧

イベント	タイミング
SessionStart	セッション開始時
SessionEnd	セッション終了時
UserPromptSubmit	ユーザー入力送信時
PreToolUse	ツール実行前
PostToolUse	ツール実行後
PostToolUseFailure	ツール実行失敗時
PermissionRequest	権限リクエスト時
Notification	通知発生時
SubagentStart	サブエージェント開始時
SubagentStop	サブエージェント停止時
Stop	エージェント停止時
PreCompact	コンテキスト圧縮前

12種類で最多。SubagentStart/Stopはマルチエージェント構成を前提としたイベントで、他のツールにはない。

フックタイプ — 最大の差別化ポイント

Claude Codeのフックには3種類のtypeがある。

type	動作
command	シェルコマンドを実行（他ツールと同じ）
prompt	LLMにプロンプトを送って判断させる
agent	LLMエージェントを起動して処理を委任

promptとagentはClaude Code固有の機能。フックの判断ロジック自体をLLMに委任できる。たとえば「このBashコマンドは安全か？」をルールベースではなくLLMに判断させるといった使い方ができる。

柔軟性は高いが、LLM呼び出しが発生するのでコストとレイテンシのトレードオフがある。

設定の階層

ユーザー → プロジェクト → ローカルの3階層。

Codex CLI

OpenAIのCodex CLIには正式なHooksシステムが存在しない。GitHub Discussions（#2150）でコミュニティから要望は出ているが、未実装のまま。

唯一のフック的機能: notify

# ~/.codex/config.toml
notify = ["say", "Codex is done"]

エージェントがターンを完了したときに外部コマンドを実行する。通知専用で、ツール実行の前後に介入する機能はない。

代わりにどうしているか

Codex CLIはHooksの代わりに、宣言的な設定でツール実行を制御するアプローチを取っている。

Approval Policy（承認ポリシー）: ユーザーへの確認タイミングを4段階で制御。

ポリシー	動作
on-request	ネットワーク・ワークスペース外書き込み・未信頼コマンドで承認要求
untrusted	ファイル編集は自動、未知コマンドのみ承認要求
on-failure	コマンド失敗時のみ承認要求
never	承認プロンプト無効

Sandbox Mode: OS-levelのサンドボックスで物理的に制限する。

モード	制限
read-only	ファイル変更・コマンド実行を制限
workspace-write	ワークスペース内のみ編集可
danger-full-access	制限なし

macOSはSeatbelt、LinuxはLandlock+seccomp、WindowsはWSL sandboxと、OS固有の実装を使う。ここはかなりCodex CLIらしい設計。

Execution Policy: .rulesファイルでコマンドパターンマッチ。

prefix_rule(pattern="git status", decision="allow")
prefix_rule(pattern="rm -rf /", decision="forbidden")

allow（自動実行）、prompt（承認要求）、forbidden（ブロック）の3段階。複数ルール適用時は最も制限的なものが優先される。

比較表

項目	Gemini CLI	Claude Code	Codex CLI
Hooks有無	あり	あり	なし（notify のみ）
イベント数	10	12	—
ツール実行前介入	BeforeTool	PreToolUse	Execution Policy
ツール実行後介入	AfterTool	PostToolUse	—
LLM呼び出し前介入	BeforeModel	—	—
LLMによる判断	—	prompt/agent hook	—
サブエージェント対応	—	SubagentStart/Stop	—
サンドボックス	—	—	OS-level sandbox
matcher	正規表現	正規表現	prefix match
設定形式	JSON	JSON	TOML + Starlark風
通信方式	stdin/stdout JSON	stdin/stdout JSON	—
拡張配布	Extensions	—	—

設計思想の違い

3つのツールを並べると、設計思想の違いが見える。

Gemini CLIは最も低レイヤーまで介入できるアプローチ。BeforeModelでLLMリクエスト自体に介入したり、BeforeToolSelectionでツール選択をフィルタしたり、エージェントの内部動作に深く関与できる。Extensions経由でHooksをバンドル配布できるのもエコシステム指向。

Claude Codeはフックの判断ロジック自体をLLMに委任できる唯一のツール。ルールベースで書きにくい曖昧な判断（「このコマンドは安全か？」）をLLMに任せるという割り切り。SubagentStart/Stopのようにマルチエージェント構成を前提としたイベントがあるのも、Agent SDKとの統合を見据えた設計に見える。

Codex CLIはHooksを持たず、宣言的ポリシー + OSサンドボックスで制御する。任意スクリプトの介入を許可しない代わりに、OS-levelのサンドボックスで物理的にセキュリティを担保するという方向性。「コードで柔軟にカスタマイズしたい」より「安全にデフォルトを提供したい」という思想が強い。

どのアプローチが正解かは用途次第だが、個人的にはGemini CLIのBeforeModelが一番面白いと思った。LLMのリクエスト/レスポンスに直接介入できるのは、テスト・デバッグ・コスト最適化で活躍しそう。

参考

• Tailor Gemini CLI to your workflow with hooks | Google Developers Blog
• Claude Code Hooks | Anthropic Docs
• Codex CLI | OpenAI Docs
• Hook would be a great feature - Codex CLI Discussion #2150