Claude Code / Codex / Cursor Agent Hooks の設定方法:PreToolUse 比較、最小スクリプトと fail-open の実測

Instructions、AGENTS.md、skills はモデルが無視できる提案にすぎない。hooks は harness が固定タイミングで実行する決定論的スクリプトだ。本記事では Claude Code、Codex、Cursor の PreToolUse(または同等イベント)について、設定パス・イベント名・exit 2 / deny・fail-open と fail-closed を比較し、Claude Code で実測済みの最小インターセプトスクリプトを示す。

9 分钟阅读
Claude Code / Codex / Cursor Agent Hooks の設定方法:PreToolUse 比較、最小スクリプトと fail-open の実測

まず結論から:

  • AGENTS.md / skills / システム指示は提案:モデルは読むが、忘れたり回避したりすることもある。
  • Hooks は harness が実行するスクリプト:ツール呼び出しの前後など固定タイミングで実行され、モデルがルールを「覚えているか」には依存しない。
  • 3 クライアントともツール呼び出しをインターセプトできる:Claude Code / Codex は PreToolUse、Cursor は preToolUse(またはより限定的な beforeShellExecution)を使う。インターセプト方法は exit code 2 か JSON の deny が一般的だ。
  • デフォルトは多くの場合 fail-open:スクリプトがクラッシュ・タイムアウト・0/2 以外で終了した場合、ツール呼び出しは多くの場合続行される。セキュリティポリシーには fail-closed を明示的に設定する必要がある(Claude Code:onFailure: "block";Cursor:failClosed: true)。Codex の公式ドキュメントによれば、hook 失敗時は hook failure と報告され、デフォルトで失敗をハードブロックとして扱わない。
  • Claude Code は実測済み:rm -rf /tmp/hooks-deny-me にマッチする Bash は PreToolUse にインターセプトされ(exit 2)、echo hooks-allow-ok は正常に通過した。Cursor はローカルのヘッドレス環境で同等の実測ができないため、設定は公式ドキュメントに基づいて整理しており、Cursor の実測は主張しない。

SwiftLee / Antoine van der Lee の 2026-11-02 記事 および @peterfriese による X でのシェア によれば:hooks はルールを AGENTS.md に書くよりはるかに信頼性が高い。以下では各社の公式ドキュメントを基準とし、第三者記事と不一致がある場合は公式を優先して出典を明記する。

関連背景:プラグインが黙って SessionStart hooks を追加することがある(Postman プラグインの確認と削除 を参照)。また AGENTS.md はディレクトリコンテキストによって意図せず上書きされることもある(Downloads ディレクトリハイジャック を参照)。Hooks は「Downloads でエージェントを開かない」という対策を代替するものではないが、markdown では強制できないハードルールを実行できる。MCP と権限境界については Codex Playwright MCP セキュリティガイド を、skills と hooks の役割分担については AI エージェントでの Skills の使い方 を参照。

1 分間比較表

項目Claude CodeCodexCursor
ユーザーレベル設定~/.claude/settings.json~/.codex/hooks.json または config.toml~/.cursor/hooks.json
プロジェクトレベル設定.claude/settings.json.codex/hooks.json または config.toml.cursor/hooks.json(ワークスペースの信頼が必要)
ツール呼び出し前PreToolUsePreToolUsepreToolUse;シェルコマンドには beforeShellExecution も使用可
ツール呼び出し後PostToolUsePostToolUsepostToolUse / afterFileEdit など
Shell ツール名(matcher)BashBashShell(beforeShellExecution ではコマンドテキストで直接マッチ)
インターセプトexit 2、または JSON permissionDecision: "deny"exit 2、または JSON permissionDecision: "deny" / 旧形式 decision: "block"exit 2、または JSON permission: "deny"
Hook 失敗デフォルト多くのイベントは続行(fail-open);onFailure: "block" で変更可hook failure と報告、失敗をハードブロックとして扱わない(公式 Hooks ページより)デフォルト fail-open;failClosed: true で変更可
信頼 / 審査ワークスペース信頼がプロジェクト hooks に影響非管理 hooks は /hooks で審査・trust が必要;--dangerously-bypass-hook-trust(1 回限り)も使用可プロジェクト hooks は信頼済みワークスペースのみ読み込み

公式ドキュメント:Claude Code Hooks · Codex Hooks · Cursor Hooks

なぜ AGENTS.md だけでは不十分か

SwiftLee の記事の経験によれば:xcodebuild の出力をフィルタリングするようグローバル指示に書いても、エージェントは依然として生ログをコンテキストに詰め込むことが多かった。指示テキストは prompt に入り、モデルが従うかどうかを決める。hook は harness レイヤーで実行されるため、モデルには「hook を実行するかどうか」を否決する権限がない。

役割分担の目安:

  1. 指示と設定 → AGENTS.md / skills(意図・スタイル・フローの説明)
  2. 毎回必ず成立すべきルール → hooks(危険なコマンドのブロック・ビルドコマンドの書き換え・監査・セッション終了時のログ記録)
  3. hooks を唯一の防衛線にしない → 一部のパスは hooks をスキップする(例:Codex のドキュメントによれば、write_stdin ポーリングで既に PreToolUse を通過したコマンドは再度 PreToolUse を実行しない)

最小スクリプト:危険な Bash を 1 つブロックする(fail-open)

以下のスクリプトは 3 クライアント共通で使用できる。stdin から JSON を読み込んでコマンドを取得し、マッチすればブロック、そうでなければ通過させる。解析失敗時は exit 0(fail-open)。~/.agents/hooks/block-rm-demo.sh のように実行可能ファイルとして保存する。

bash
#!/bin/bash
# fail-open: jq がないか JSON が不正 → exit 0、処理を止めない
input=$(cat || true)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // .command // empty' 2>/dev/null || true)

if [[ -z "$command" ]]; then
  exit 0
fi

if [[ "$command" == *"rm -rf /tmp/hooks-deny-me"* ]]; then
  # Cursor:cursor_version フィールドがある場合は JSON deny を使用(公式 Cursor Hooks + SwiftLee 記事の書き方に基づく)
  if printf '%s' "$input" | jq -e 'has("cursor_version")' >/dev/null 2>&1; then
    jq -n '{permission:"deny", agent_message:"Blocked by PreToolUse-style hook: refusing rm -rf /tmp/hooks-deny-me"}'
    exit 0
  fi
  # Claude Code / Codex:stderr + exit 2
  echo "Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me" >&2
  exit 2
fi

exit 0

chmod +x の後に設定に登録する。

Claude Code への登録

~/.claude/settings.json またはプロジェクトの .claude/settings.json に記述する:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm-demo.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

ユーザーレベルには絶対パスを使用できる。セキュリティポリシーの hook には "onFailure": "block" を追加することを推奨する(比較的新しいバージョンが必要。公式の説明は Hooks reference を参照)。スクリプトパスの誤記でポリシー全体が無効にならないようにするためだ。

Codex への登録

Claude Code と形式が近い。~/.codex/hooks.json またはプロジェクトの .codex/hooks.json に記述する:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/bash /absolute/path/to/block-rm-demo.sh",
            "timeout": 5,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

注意:Codex では非管理 hooks を CLI の /hooks で審査・trust する必要がある。プロジェクトレベルの hooks はプロジェクトの .codex/ が信頼済みであることも必要だ。1 回限りの自動化には公式ドキュメントの --dangerously-bypass-hook-trust が使える。[features] hooks = false でグローバルに無効化できる。

Cursor への登録

Cursor の hooks.json はよりフラットな構造で、version が必要だ:

json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "~/.agents/hooks/block-rm-demo.sh",
        "matcher": "Shell",
        "timeout": 5
      }
    ]
  }
}

プロジェクトレベルのパスはリポジトリルートからの相対パス(例:.cursor/hooks/block-rm-demo.sh)。セキュリティ上重要な hook には "failClosed": true を追加する。beforeShellExecution に変更してコマンドテキスト(例:rm\\s+-rf)に直接マッチさせることもできる。

実測:Claude Code PreToolUse(本サイト Key)

環境:Claude Code CLI 2.1.319、プロジェクト内の .claude/settings.json に上記の fail-open スクリプトを登録し、aicodewith 互換インターフェース経由で非インタラクティブ -p を実行。

  1. 通過パス:モデルに echo hooks-allow-ok の実行を要求 → hooks-allow-ok が出力され、約 8 秒。
  2. インターセプトパス:モデルに rm -rf /tmp/hooks-deny-me の実行を要求 → PreToolUse hook error が返され、コマンドは実行されず、約 9 秒。エラーの抜粋:
text
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
  1. ユニットレベル fail-open:stdin に不正な JSON を送信 → スクリプトが exit 0(後続処理をブロックしない)。

Cursor はローカルのヘッドレス環境で同等の実測ができないため、上表の Cursor 列は Cursor 公式 Hooks ドキュメント に基づく。Codex の設定形式は公式ドキュメントで確認済み。今回の統合実測は重複コストを避けるため Claude Code の 1 つのチェーンを選択した。

Codex を使用している場合は、同じスクリプトを PreToolUse + matcher Bash に登録し、まず /hooks で trust してから、マッチするコマンドとマッチしないコマンドをそれぞれ実行して動作を確認できる。

fail-open か fail-closed か

シナリオ推奨設定方法
便利系(ビルドログのフィルタリング、自動 format)fail-openデフォルトのまま;スクリプト内の解析失敗も exit 0
セキュリティ・コンプライアンス(削除禁止・外部送信禁止・キーファイル変更禁止)fail-closedClaude Code:onFailure: "block";Cursor:failClosed: true;「スクリプトを削除したときにツールがブロックされるか」も自分でテストすること
Codex 管理ポリシー企業の requirements.toml / managed hooks に従う公式の Managed hooks を参照;ローカルユーザー hook 失敗はデフォルトでハードブロックしない

SwiftLee の記事によれば:便利系 hook は fail-open にすべきで、壊れた hook で作業できなくならないようにする。危険な操作をブロックする hook だけ fail-closed にすべきだ。

設定時の注意点(3 クライアント共通)

  1. 読んでから有効化:リポジトリやプラグインが持ち込む hooks はローカルスクリプトであり、自分自身と同等の権限を持つ。Postman 系プラグインは過去に SessionStart hooks を自動インストールしていた。インストール前に何が登録されるか確認する。
  2. timeout は短く:エージェントは hook を待つ。ユーザーレベルの便利系 hook は 5 秒が一般的だ。
  3. Stop / stop の継続実行はループを制限:Cursor は stop / subagentStop に loop_limit(デフォルト 5)がある。「終了後にもう一言追加」が無限ループにならないよう注意。
  4. matcher 名を混同しない:Claude Code / Codex のシェルツール名は Bash;Cursor の汎用ツールマッチには Shell を使う。
  5. Hooks ≠ skills:skills は名前や説明で呼び出される能力パッケージ;hooks はイベント駆動で、誰も指定しなくても実行される。

aicodewith Key で Claude Code / Codex を実行する(任意)

hooks のテストは特定のモデルプロバイダーに依存しない。aicodewith 経由でモデルを利用する場合:

  • Claude Code:サイトのドキュメントに従って互換 Base URL と Key を設定する。
  • Codex:グローバルの ~/.codex/config.toml で experimental_bearer_token、name = "aicodewith"、base_url = "https://api.aicodewith.ai/chatgpt/v1" を設定する(/chatgpt/v1 であり、裸の /v1 ではないことに注意)。

API Key を作成する →

よくある質問

Hooks と AGENTS.md の違いは?

AGENTS.md はコンテキストに入り、モデルが無視できる。hooks は Claude Code / Codex / Cursor がライフサイクルイベントで直接実行する。意図は markdown に書き、ハードな制約は hook にする。

Exit code 2 と JSON deny はどちらを選ぶ?

どちらもブロックできる。Claude Code / Codex は stderr + exit 2 が一般的。構造化された理由が必要な場合や入力を書き換えたい場合は JSON(permissionDecision / updatedInput など)を使う。Cursor の permission hooks は stdout JSON の permission フィールドを優先する。exit 2 も deny と同等だ。

プロジェクトの hooks が実行されないのはなぜ?

確認事項:ワークスペース・プロジェクトが信頼済みか;Codex で /hooks trust が完了しているか;パスが正しいか(Cursor のプロジェクト hooks はリポジトリルートからの相対パス);matcher のツール名が正しいか;Claude Code では /hooks メニューで登録元を確認できる。

Hooks はセキュリティポリシーを完全に代替できるか?

できない。公式ドキュメントでも一部のパスは hook を通らないと認めている。プラグインや SessionStart スクリプト自体もリスク面になりえる。Hooks は決定論的な一層のガードレールであり、権限モデル・キー管理・ディレクトリ選択と組み合わせて使う必要がある。

Cursor の ask は preToolUse で信頼できるか?

Cursor の公式ドキュメントによれば:preToolUse の出力における "ask" は現時点では強制されない。操作をブロックするには "deny" または exit 2 を使うこと。beforeShellExecution などのイベントは allow / deny / ask をサポートしている。

まとめ

「モデルが覚えておくべき」ルールを「harness が毎回実行する」hooks に格上げする。まず PreToolUse / preToolUse の最小スクリプト 1 つから始めよう:matcher を Bash または Shell に合わせ、マッチしたら exit 2 / deny、デフォルトは fail-open、セキュリティ用途のみ fail-closed にする。Claude Code、Codex、Cursor の設定ファイルとイベント名は異なるが、イベント → matcher → スクリプト → 判定という流れは共通だ。

API Key を作成する → · モデルと接続ドキュメントを見る →

出典

相关文章

UI SDK とは何か、どう使うか?Vercel と shadcn が Agent 向けに出した振る舞いライブラリを、Claude Code / Codex / Cursor でインストールして実測する(0.1.0-beta.1)

UI SDK とは何か、どう使うか?Vercel と shadcn が Agent 向けに出した振る舞いライブラリを、Claude Code / Codex / Cursor でインストールして実測する(0.1.0-beta.1)

UI SDK は、Vercel が 2026 年 11 月 12 日に公開した Agent 向けの振る舞い(behaviors)ライブラリで、バージョンは 0.1.0-beta.1 です。振る舞いはフレームワーク非依存の @ui-sdk/core にあり、React、Vue、Svelte、Solid、Web Components のアダプターが描画します。公式ドキュメントに沿って「何か」「どう入れるか」「Claude Code / Codex / Cursor に skill をどう渡すか」を整理し、テスト機で実際に走ったコマンド、所要時間、出力を記録します。

AWS Emulator とは?インストール方法と、Claude Code / Codex でローカルに AWS アプリをテストする手順(1.0.322 で検証)

AWS Emulator とは?インストール方法と、Claude Code / Codex でローカルに AWS アプリをテストする手順(1.0.322 で検証)

AWS Emulator は AWS 公式のローカル AWS エミュレーターで、2026 年 11 月 11 日(米国時間)に一般提供(GA)が始まりました。追加のサービス料金はかからず、ソースは公開されており、AWS アカウントも不要で、200 以上のサービスをカバーします。本記事では Debian 13 上で 1.0.322 を検証し、インストールコマンド、AWS CLI をローカル endpoint に向けて S3 バケットと DynamoDB テーブルを作る手順、遭遇したエラー、Claude Code・Codex・Cursor にエミュレーター相手でコードを書かせてテストさせる方法をまとめます。

T3 Code とは?インストール方法、Claude Code・Codex との接続、サードパーティ API Key の設定とよくあるエラー(0.1.9 で検証)

T3 Code とは?インストール方法、Claude Code・Codex との接続、サードパーティ API Key の設定とよくあるエラー(0.1.9 で検証)

T3 Code は pingdotgg が公開しているオープンソースのコーディングエージェント用コンソールです。モデルは内蔵しておらず、マシンにインストール済みの Claude Code、Codex、Cursor などの CLI を操作します。Linux 上で T3 Code 0.1.9 を検証し、インストールコマンド、Claude Code と Codex を AICodeWith API Key につないで T3 Code から操作する設定、t3 thread コマンドで両方を動かした結果、実際に出たエラーと対処法をまとめました。