Hooks イベントリファレンス

Claude Code のフックシステムは 30 個のイベントタイプ、5 種類のフックタイプ、イベント別マッチャー、スマート動作 をサポートします。フックはエージェンティックハーネスで唯一「必ず実行される」ことが保証される決定論的 (deterministic) な制御ポイントです — プロンプトは無視されうるが、フックは無視されません。

フックの基本概念と設定方法は Hooks ガイド を参照してください。このページはイベントの全リファレンスです。

利用可能なフックタイプは 5 種類です。

MoAI-ADK フックは単純なイベント処理を超えて知的な動作を行います。

読み取り専用ツール (Read, Grep, Glob) の権限が拒否されると、フックが自動的にリトライをトリガーします。これはバックグラウンドエージェントで権限プロンプトが表示されない問題を緩和します。

エージェント停止失敗時にエラータイプに応じて差別化された応答を提供します。長時間実行セッションでの安定性を保証します。

コンテキスト圧縮後に重要なセッションメモ (進行状態、SPEC 参照) を自動的に復元します。コンテキスト圧縮はトークンを節約する代わりに情報を失う取引ですが、このフックがその損失から核心情報を守ります。

サブエージェント開始時に必要なコンテキスト (プロジェクトルール、MX タグ、進行状態) を自動注入します。

マッチャーを使うと特定の条件でのみフックが実行されるようフィルタリングできます。すべてのイベントにフックを掛けるとその分だけ実行コストが増えるので、マッチャーで範囲を絞るのが基本です。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": { "toolName": "Bash" },
      "hooks": [{
        "type": "command",
        "command": "echo 'Bash tool detected'",
        "timeout": 5
      }]
    }]
  }
}

CwdChanged と FileChanged フックを通じて環境変数を継続的に管理できます。

# .claude/hooks/moai/handle-cwd-changed.sh
# CLAUDE_ENV_FILE を通じて環境変数を永続化
echo "MOAI_PROJECT_DIR=$(pwd)" >> "$CLAUDE_ENV_FILE"

これによりセッション間で環境変数を維持し、ディレクトリ変更時に自動的に環境を再設定できます。

• Hooks ガイド — フックの基本概念と設定方法
• settings.json ガイド — settings.json 全リファレンス
• CLI リファレンス — moai hook コマンド詳細