［開発者向け］Gemini CLIの「フック」機能でエージェント動作をカスタマイズ可能に

2026-01-29

はじめに

　Googleが2026年1月28日、開発者向けブログで「Gemini CLI」の新機能「フック(hooks)」を発表しました。フックを活用することで、AIエージェントのライフサイクルの特定の時点で独自のスクリプトを実行し、セキュリティポリシーの適用やコンテキスト追加など、開発ワークフローに合わせたカスタマイズが可能になります。本稿では、フックの仕組み、実用例、ベストプラクティスについて解説します。

参考記事

タイトル: Tailor Gemini CLI to your workflow with hooks
著者: Edi Palencia (Software Engineer), Jack Wotherspoon (Developer Advocate), Abhi Patel (Software Engineer)
発行元: Google Developers Blog
発行日: 2026年1月28日
URL: https://developers.googleblog.com/tailor-gemini-cli-to-your-workflow-with-hooks/

要点

Gemini CLI v0.26.0以降で「フック」機能が標準搭載され、エージェントループの特定時点で独自スクリプトを実行できるようになった
フックを使うことで、コンテキスト追加、操作の検証、セキュリティポリシー適用、ログ記録、通知など多様なカスタマイズが可能である
BeforeToolフックを活用した自動シークレットスキャンなど、実用的なセキュリティ対策が実装できる
Gemini CLI拡張機能でもフックがサポートされ、「Ralph loop」のような継続的な反復処理を実現する拡張が登場している
フックは同期的に実行されるため、処理速度の最適化と適切なマッチャー設定が重要である

詳細解説

フックとは何か

　Googleによれば、フックとは「Gemini CLIがライフサイクルの特定の時点で実行するスクリプトまたはプログラム」です。これは、AIアシスタントのための「ミドルウェア」のような役割を果たし、エージェントループ内で同期的に独自のロジックを追加できます。

　フックが提供する主な機能は以下の通りです:

コンテキスト追加: 最近のgitコミット、Jiraチケット、ローカルドキュメントなど、関連情報をモデルがリクエストを処理する前に注入できます
操作の検証: 危険な可能性のある操作を実行前にレビューし、ブロックできます
ポリシー適用: 組織全体のセキュリティとコンプライアンス要件を自動的に実装できます
ログと最適化: ツール使用状況を追跡し、モデルの精度向上とトークンコスト削減のためにツール選択を動的に調整できます
通知: Gemini CLIがアイドル状態、入力待ち、またはツール確認が必要な時に更新を受け取れます

　フックを設定すると、イベントが発生した際にCLIはフックの完了を待ってから続行するため、独自ロジックが常に尊重されます。これは従来のCI/CDパイプラインにおけるフックと同様の概念で、特定の処理段階で開発者が介入できる仕組みと考えられます。

実用例:自動シークレットスキャン

　Googleが提示した最も実用的な例の一つが、BeforeToolフックを使用したセキュリティセーフティネットの構築です。この仕組みにより、AIが誤ってAPIキーやパスワードなどの機密データをコードベースに書き込むことを防げます。

　実装は、シェルスクリプトによるフック(.gemini/hooks/block-secrets.sh)と、設定ファイル(.gemini/settings.json)の組み合わせで行われます。スクリプトは標準入力からフック入力を読み取り、jqを使用して書き込まれる内容を抽出し、一般的なシークレットパターン(api_key、password、secretなど)を正規表現でチェックします。

※.gemini/hooks/block-secrets.sh

#!/usr/bin/env bash
# Read hook input from stdin
input=$(cat)

# Extract content being written using jq
content=$(echo "$input" | jq -r '.tool_input.content // .tool_input.new_string // ""')

# Check for common secret patterns
if echo "$content" | grep -qE 'api[_-]?key|password|secret|AKIA[0-9A-Z]{16}'; then
  # Return structured denial to the agent
  cat <<EOF
{
  "decision": "deny",
  "reason": "Security Policy: Potential secret detected in content.",
  "systemMessage": "Security scanner blocked operation"
}
EOF
  exit 0
fi

# Allow the operation
echo '{"decision": "allow"}'
exit 0

　※.gemini/settings.json

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "secret-scanner",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/block-secrets.sh",
            "description": "Prevent committing secrets"
          }
        ]
      }
    ]
  }
}

　シークレットが検出された場合、スクリプトは構造化された拒否応答をエージェントに返します。この応答には、決定(deny)、理由(セキュリティポリシー違反)、システムメッセージが含まれます。問題がない場合は、allow決定を返して操作を許可します。

　設定ファイルでは、BeforeToolイベントに対してwrite_fileまたはreplaceツールにマッチするマッチャーを設定し、このフックを適用します。これにより、Gemini CLIがファイルの書き込みや編集を試みるたびに、フックスクリプトが内容を事前に検証し、シークレットが検出された場合は操作をブロックし、エージェントに明確な説明を提供して自己修正を促します。

　この仕組みは、開発現場で頻繁に発生する「うっかり機密情報をコミット」という事故を、AIエージェントのレベルで防止できる点で実用的と考えられます。

フックのベストプラクティス

　Googleは、フックがワークフローを強化しつつ速度を低下させないための重要なガイドラインを提示しています:

高速化を維持: フックは同期的に実行されるため、スクリプトの遅延はエージェントの応答遅延に直結します。高コストなタスクには並列処理とキャッシングを使用することが推奨されます
特定のマッチャーを使用: すべてのツールに対してフックを実行するのではなく、matcher プロパティ(例:”matcher”: “write_file|replace”)を使用して関連イベントに実行を制限します
セキュリティ第一: フックはユーザー権限で実行されるため、プロジェクトレベルのフックを有効にする前に、必ずソースをレビューすることが重要です
ツールの活用: /hooksコマンドを使用して、すべてのフックとそのステータスを表示できます

　これらのガイドラインは、フックの柔軟性と引き換えに生じる可能性のあるパフォーマンス低下やセキュリティリスクを最小化するための実践的なアドバイスと言えます。

Gemini CLI拡張機能でのフック活用

　フックの機能は、ローカル設定に限定されていません。Gemini CLI拡張機能もフックを完全サポートしており、拡張機能の作者は拡張内に直接フックをバンドルできます。これにより、ユーザーは単一のコマンドでフックをインストールでき、手動設定が不要になります。

　実例として、Googleは「Ralph loop」テクニックを実装したRalph拡張を紹介しています。この拡張はAfterAgentフックを活用し、エージェントの完了シグナルをインターセプトして、継続的な反復ループに強制します。

　この仕組みにより、Gemini CLIは難しいタスクに対して粘り強く取り組み続け、長時間のセッションで頻繁に発生するコンテキストの劣化を防ぐために、試行の合間に自動的にコンテキストをリフレッシュします。これは、Gemini CLIを反応的なアシスタントから、仕事が完了するまで止まらない、自律的なワーカーに変換すると説明されています。

　また、より厳格な反復的ソフトウェア開発ライフサイクルプロセスに従う、Gemini CLIチームメンバーによる「Ralph loop」の進化版拡張も紹介されています。これらの拡張は、フックがエージェントの動作パターンそのものを根本的に変更できる可能性を示していると考えられます。

利用開始方法

　フックはGemini CLI v0.26.0以降でデフォルトで有効になっています。最新バージョンへの更新は、npm install -g @google/gemini-cli@latestコマンドで実行できます。

　Googleは、フックの詳細と実装を学ぶための公式ドキュメントとして、以下のリソースを提供しています:

フックの概要: コアコンセプトとイベントの概要
最初のフック作成: 包括的な実装例
フック技術リファレンス: すべてのイベントタイプの詳細な入出力スキーマ
ベストプラクティスとセキュリティ: パフォーマンス最適化と脅威軽減戦略

　フィードバックはGitHubリポジトリやソーシャルメディアで受け付けられており、最新情報はGemini CLIのX(旧Twitter)アカウントで確認できます。

まとめ

　Gemini CLIのフック機能は、AIエージェントの動作をソースコード変更なしでカスタマイズできる強力な仕組みです。セキュリティスキャンから継続的な反復処理まで、開発ワークフローに合わせた多様な活用が可能になります。フックのパフォーマンス最適化とセキュリティ配慮を適切に行うことで、より安全で効率的な開発環境が実現できると思います。