まず結論から:
- 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 Code | Codex | Cursor |
|---|---|---|---|
| ユーザーレベル設定 | ~/.claude/settings.json | ~/.codex/hooks.json または config.toml | ~/.cursor/hooks.json |
| プロジェクトレベル設定 | .claude/settings.json | .codex/hooks.json または config.toml | .cursor/hooks.json(ワークスペースの信頼が必要) |
| ツール呼び出し前 | PreToolUse | PreToolUse | preToolUse;シェルコマンドには beforeShellExecution も使用可 |
| ツール呼び出し後 | PostToolUse | PostToolUse | postToolUse / afterFileEdit など |
| Shell ツール名(matcher) | Bash | Bash | Shell(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 を実行するかどうか」を否決する権限がない。
役割分担の目安:
- 指示と設定 → AGENTS.md / skills(意図・スタイル・フローの説明)
- 毎回必ず成立すべきルール → hooks(危険なコマンドのブロック・ビルドコマンドの書き換え・監査・セッション終了時のログ記録)
- hooks を唯一の防衛線にしない → 一部のパスは hooks をスキップする(例:Codex のドキュメントによれば、
write_stdinポーリングで既に PreToolUse を通過したコマンドは再度 PreToolUse を実行しない)
最小スクリプト:危険な Bash を 1 つブロックする(fail-open)
以下のスクリプトは 3 クライアント共通で使用できる。stdin から JSON を読み込んでコマンドを取得し、マッチすればブロック、そうでなければ通過させる。解析失敗時は exit 0(fail-open)。~/.agents/hooks/block-rm-demo.sh のように実行可能ファイルとして保存する。
#!/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 に記述する:
{
"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 に記述する:
{
"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 が必要だ:
{
"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 を実行。
- 通過パス:モデルに
echo hooks-allow-okの実行を要求 →hooks-allow-okが出力され、約 8 秒。 - インターセプトパス:モデルに
rm -rf /tmp/hooks-deny-meの実行を要求 → PreToolUse hook error が返され、コマンドは実行されず、約 9 秒。エラーの抜粋:
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
- ユニットレベル 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-closed | Claude Code:onFailure: "block";Cursor:failClosed: true;「スクリプトを削除したときにツールがブロックされるか」も自分でテストすること |
| Codex 管理ポリシー | 企業の requirements.toml / managed hooks に従う | 公式の Managed hooks を参照;ローカルユーザー hook 失敗はデフォルトでハードブロックしない |
SwiftLee の記事によれば:便利系 hook は fail-open にすべきで、壊れた hook で作業できなくならないようにする。危険な操作をブロックする hook だけ fail-closed にすべきだ。
設定時の注意点(3 クライアント共通)
- 読んでから有効化:リポジトリやプラグインが持ち込む hooks はローカルスクリプトであり、自分自身と同等の権限を持つ。Postman 系プラグインは過去に SessionStart hooks を自動インストールしていた。インストール前に何が登録されるか確認する。
- timeout は短く:エージェントは hook を待つ。ユーザーレベルの便利系 hook は 5 秒が一般的だ。
- Stop / stop の継続実行はループを制限:Cursor は
stop/subagentStopにloop_limit(デフォルト 5)がある。「終了後にもう一言追加」が無限ループにならないよう注意。 - matcher 名を混同しない:Claude Code / Codex のシェルツール名は
Bash;Cursor の汎用ツールマッチにはShellを使う。 - 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ではないことに注意)。
よくある質問
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 を作成する → · モデルと接続ドキュメントを見る →



