Claude Codeのフック：エージェントの動作を決定論的に制御する

フックの構成

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}

構成要素は、イベント、マッチャー（ツールイベントではツール名に適用する正規表現。省略するとすべてに一致）、および実行するコマンドです。コマンドは、イベントを記述したJSONオブジェクトを標準入力で受け取ります。ツールイベントでは、これに次が含まれます： tool_name と tool_input。上の例はこれを使って、直前に編集されたファイルを特定します。リポジトリで共有する場合は次に配置します： .claude/settings.json 。自分だけで使う場合は次に配置します： ~/.claude/settings.json 。または、次を実行して /hooks Claude Codeに書き込ませます。

イベント

• PreToolUse — ツールの実行前。次の操作が可能な唯一のイベントです： ブロック：終了コード2で呼び出しをキャンセルし、Claudeは標準エラー出力をその理由として読み取ります。
• PostToolUse — ツールの成功後。編集されたファイルに対してフォーマッター、リンター、型チェックを実行します。
• UserPromptSubmit — プロンプトの送信時。コンテキストを追加したり、プロンプトを拒否したりできます。
• Stop / SubagentStop — エージェント（またはサブエージェント）が終了しようとするとき。ここでの終了コード2は「まだ完了していない」を意味します。典型的な用途は、テストが失敗している間は終了を拒否することです。
• PreCompact — 次の処理の前： /compact。会話の全記録から必要な情報を保存します。
• SessionStart — セッションの開始時または再開時。環境を読み込み、リマインダーを表示します。
• Notification — Claude Codeがユーザーの対応を必要とするとき（許可の確認、待機中）。デスクトップ通知やSlack通知に接続します。

危険なコマンドのブロック

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

終了コード2が動作を決める規約です。ツール呼び出しは実行されず、フックが標準エラー出力に書き出した内容がClaudeへの説明になります。そのため、Claudeは同じ操作を再試行せず、別の方法を選べます。それ以外のゼロ以外の終了コードはログに記録されますが、ブロックはしません。

「テストが通るまで終了しない」

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

ヘッドレス実行では、次の上限設定と組み合わせてください： --max-turns 。修正不可能な失敗によって無限ループに陥るのを防げます。

フックとCLAUDE.mdと権限の比較

CLAUDE.mdはモデルが読む助言です。 /permissions は、確認なしに実行してよい操作の一覧です。フックはそれらに関係なく実行されるコードです。CLAUDE.mdはスタイルとコンテキストに、権限は許可と確認の境界に、フックは毎回確実に実施すべき処理に使います。たとえば、整形、シークレットのスキャン、テストによる実行制御、監査ログです。これらは組み合わせて機能します。権限によって次の実行が許可されても、 Bash(git *) PreToolUseフックは引き続き次をブロックします： git push --force.

フックとゲートウェイ

フックはローカルで実行され、APIには一切アクセスしないため、Claude Codeの接続先を次にしても動作は変わりません： ANTHROPIC_BASE_URL=https://aiprimetech.io。便利な組み合わせの例として、次のフックがあります： Stop 。自分のログから次の形式の使用量を表示します： /cost。これにより、従量課金のクレジットを使うチームは、各セッションの終了時にその料金を確認できます。

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

よくある質問

AI Prime Techは独立したAPIゲートウェイであり、Anthropicとの提携関係はなく、同社の推奨や支援も受けていません。「Claude」と「Claude Code」はAnthropicの商標です。ここで説明するClaude Codeの機能は、執筆時点のAnthropicの公開ドキュメントに基づいており、頻繁に変更されます。このページの料金とモデル一覧は、このゲートウェイの現在の設定から取得しています。