agents-hooks

Claude Code Hooks + Codex Notifications

フックの動作が主な関心事である場合に、このスキルを使用します。Claude のライフサイクルフック、実行時の事前チェック、ガードレール、非同期検証、worktree のライフサイクルチェック、サブエージェントの連携、または Codex の通知コールバックが該当します。

ここでは Claude と Codex は同等ではありません。Claude には、広範で安定したフックシステムがあります。Codex には 2 つの仕組みがあります。長期間安定している通知機能（notify + tui.notifications）と、リリースごとにイベント、ハンドラーの種類、信頼ルールが変わり、イベントが確実に発火しないことがあるライフサイクルフックシステム（hooks.json。詳しくはdevelopers.openai.com/codex/hooksを参照）です。どちらのイベントセットも拡張されていくため、件数を鵜呑みにせず、各ランタイムのフックリファレンスで最新の一覧を確認してください。このスキルでは、Codex のフックに関する情報を references/hook-templates.md §Codex の参照手順として管理しています。確実に動作させる必要があるものには notify を優先し、依存する前に、使用するランタイムで Codex のフックが発火することを確認してください。

クイックリファレンス

必要なこと	イベント／方法
ツール実行前のポリシーやガードレールを適用する	PreToolUse コマンドフック
セッション開始時にランタイムをすばやくチェックする	SessionStart または Setup
Claude が見る前にユーザープロンプトに対応する	UserPromptSubmit
編集後にチェックを実行する（ブロックしない）	PostToolUse（非同期／バックグラウンド）
ツールの失敗を個別に検知する	PostToolUseFailure
並列ツール呼び出しの一連の処理後にチェックする	PostToolBatch
サブエージェントにコンテキストを注入する、または連携する	SubagentStart／SubagentStop
ユーザーに表示される内容を変換する（トランスクリプトは変更しない）	MessageDisplay
コンパクション前に簡潔で永続的な状態を保存する	PreCompact
コンパクション完了後に対応する	PostCompact
worktree のセットアップと削除を処理する	WorktreeCreate／WorktreeRemove
cd または監視対象ファイルの変更に対応する	CwdChanged／FileChanged
エージェントチームがアイドル状態になるのを防ぐ	TeammateIdle
ターン終了時の API エラーを処理する	StopFailure
プラグインのフックを安全に再読み込みする	クリアしてから登録するアトミックな入れ替え
Codex のコールバック動作を追加する	外部プログラムの notify と tui.notifications
予算、反復回数の上限、停滞、キルスイッチを適用する	references/budget-and-loop-hooks.md

このスキルを使用する場合

次のタスクでは、このスキルを使用してください。

• Claude のフック自動化を構築する
• コマンドのガードレールや承認ロジックを追加する
• 検証フックや監査フックを組み込む
• フックのスコープ内でリポジトリの健全性を管理する
• Codex の通知またはコールバックプログラムを設定する

主な関心事が次の場合は、別の場所を参照してください。

必要なこと	代わりに使用
永続的なプロジェクトメモリまたはコンパクションの内容	../agents-memory/SKILL.md
MCP の設計またはサーバー統合	../agents-mcp/SKILL.md
サブエージェントの設計または委任の境界	../agents-subagents/SKILL.md
マルチエージェントのオーケストレーション	../agents-swarm-orchestration/SKILL.md
コーディングエージェントの権限モードと承認の振り分け	../ai-coding-agents-safety-envelope/SKILL.md

機能の境界

機能	Claude Code	Codex
幅広いライフサイクルフック	はい（安定しています。最新のイベント一覧を確認してください）	はい。hooks.json を使用します（イベントの種類は少なく、信頼性に課題があります。マッチャー一覧を確認してください）
コマンドまたは判断の制御	はい	はい（PreToolUse で拒否、Stop／SubagentStop でブロックして続行）。実行されるハンドラーの種類と、解析されるもののスキップされる種類を確認してください
対応イベントでのペイロード変更	はい（updatedInput、updatedToolOutput）	ご利用のバージョンで PreToolUse が updatedInput を受け付けるか確認してください
外部コールバックプログラム	はい	notify（信頼性あり）＋ hooks.json フック（まず検証してください。信頼性の確認で、変更されたフックが通知なくスキップされる場合があります）
最適な用途	ポリシー、検証、衛生管理	信頼性あり：notify による通知／ログ記録。実験的：hooks.json によるライフサイクル自動化

典型的なシナリオ

実際の状況を、それを解決する最小限のイベントとレシピに対応付けています。一致する行のうち、最も範囲の狭いものを選んでください。

シナリオ	イベント	ハンドラー	レシピ
rm -rf、git push --force、git add . の実行前にブロックする	PreToolUse（マッチャー Bash）	command	references/hook-templates.md、パターン §8／§11
エージェントを遅くすることなく、編集のたびに自動フォーマットとスモークチェックを実行する	PostToolUse（マッチャー Edit|Write、async: true）	command	パターン §1
ハード拒否ではなく、本番環境や破壊的なツールに承認を必須にする	PreToolUse → permissionDecision: ask、PermissionRequest	command	パターン §8
セッション開始時にリポジトリの状態（ブランチ、タスク ID、主要なコマンド）を注入する	SessionStart／Setup	command	references/runtime-preflight-hooks.md、パターン §6
コンテキスト圧縮後も重要な状態を保持する	PreCompact（チェックポイント）＋ SessionStart（復元）	command	hook-templates.md、パターン §5
並列ツールの実行後、次のモデル呼び出しを制御する	PostToolBatch	command／agent	hook-templates.md、パターン §1
サブエージェントにコンテキストを渡し、報告前に出力を検証する	SubagentStart（注入）＋ SubagentStop（ブロック）	command	hook-templates.md、SKILL.md §サブエージェントの連携
エージェントチームが早まってアイドル状態になるのを防ぐ	TeammateIdle	command	クイックリファレンス
ワークツリーごとのセットアップ／ティアダウン（キャッシュ、環境ファイル、インデックス）	WorktreeCreate／WorktreeRemove	command	hook-templates.md、パターン §7
監査イベントを即座に外部サーバー上の SIEM／Webhook に送る	PostToolUse／Notification	http	パターン §2
構文的な判定ではなく、「受け入れ基準を満たしているか」という意味的なゲートを設ける	Stop／SubagentStop	agent	パターン §3
自律的なループにトークン数／反復回数／停滞の予算またはキルスイッチを適用する	Stop／PostToolBatch／UserPromptSubmit	command	references/budget-and-loop-hooks.md
フック／承認／サンドボックスポリシー自体の編集を監査する	ConfigChange	command	hook-templates.md、パターン §4
ディレクトリが変わったときに .envrc／ローカル設定を再読み込みする	CwdChanged／FileChanged	command	パターン §6
セッションをまたいで、どのスキルが実際に呼び出されるかを測定する	PreToolUse（マッチャー Skill）＋ UserPromptExpansion（/skillname パス）	command	パターン §15
デスクトップ通知／「処理完了」をローカルプロセスに引き渡す（Codex）	notify ＋ tui.notifications	外部プログラム	パターン §12

ワークフロー

1. 対象が Claude のフック、Codex の通知、または混在したセットアップのどれかを確認します。
2. 要件を満たす最小限のイベント範囲を選択します。
3. 適用には、決定論的なコマンドフックを優先します。
4. 同期フックは高速に保ち、負荷の高い処理は非同期またはバックグラウンドの経路に移します。
5. 最終的な案内の前に、現在のドキュメントに照らしてイベントのサポート状況とペイロードの前提を検証します。
6. 正確なランタイム、イベント、ハンドラーの種類について、タイムアウトとエラー時の動作を明示します。現在の Claude Code では、明示的な PreToolUse の拒否または終了コード 2 によりツール呼び出しがブロックされます。一方、command、http、または mcp_tool ハンドラーがタイムアウトすると、呼び出しは通常の権限評価に戻ります。Agent SDK のコールバックがタイムアウトした場合は、呼び出しがブロックされます。ハンドラーの失敗時にも必ず閉じた状態を保つポリシーでは、ランタイムがサポートする command または http フックに "onFailure": "block" を設定します。それ以外の場合は、別の拒否ルールを追加するか、実行基盤で適用します。タイムアウト、不正な出力、重複配信は、正常系とは分けてテストしてください。

検証とインストールのチェックリスト

# 1. Lint every hook script before deployment
shellcheck ~/.claude/hooks/*.sh

# 2. Dry-run a hook by piping a sample payload
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | bash ~/.claude/hooks/preflight-guard.sh

# 3. Confirm hook files are executable
chmod +x ~/.claude/hooks/*.sh

# 4. Check audit log after a test session
cat /tmp/claude-hook-audit.log

# 5. Disable all hooks for emergency bypass
# Set "disableAllHooks": true in ~/.claude/settings.json

イベント範囲（Claude Code）

出典：code.claude.com/docs/en/hooks。以下の表では、イベントを目的別にまとめています。これは一覧ではなく、全体像を示すものです。リリース間に新しいイベントが追加されるため、イベントを接続する前に、リファレンスのイベント表で確認し、ブロック可否の列を読んでください。

表全体に当てはまるルールは2つあります。

• コンテキスト専用イベントではブロックできません。 SessionStart、SubagentStart、およびリファレンスで「ブロック不可」とされているイベントでは、終了コード 2 を返しても、フックエラーの通知として stderr がユーザーに表示されるだけで、Claude には伝わりません。モデルに伝える必要がある内容は、終了コード 0 で hookSpecificOutput.additionalContext として送信してください。
• ブロック可能な停止フックにはループガードが必要です。 Stop と SubagentStop のペイロードには stop_hook_active が含まれています。この値が true の場合はブロックせず、終了コード 0 を返してください。フックのリファレンスには、停止フックの連続継続回数の上限と、その上限を引き上げる環境変数が記載されています。独自の上限が必要なゲートでは、ランタイムの上限に頼らず、セッション単位のキーを持つ状態ファイルで回数をカウントしてください。

セッションのライフサイクル

イベント	発生するタイミング	ブロック可能か
SessionStart	セッションの開始時または再開時	いいえ（コンテキスト専用。上記のルールを参照）
Setup	claude --init-only、または -p モードでの --init / --maintenance の実行時。CI やスクリプト向けの1回限りの準備（マッチャーは init / maintenance）	いいえ
SessionEnd	セッションの終了時	いいえ（短いデフォルトのタイムアウトで実行されます。ここにクリーンアップ処理を追加する前に、デフォルト値、最大値、上書き用の環境変数を確認してください）

ターンごとのイベント

イベント	発生するタイミング	ブロック可能か
UserPromptSubmit	ユーザーがプロンプトを送信した後、Claude がそれを受け取る前	はい
UserPromptExpansion	ユーザーが入力したコマンドがプロンプトに展開されるとき	はい
Stop	Claude が応答を完了したとき	はい（stop_hook_active を確認してください）
StopFailure	API エラーによりターンが終了したとき	いいえ
MessageDisplay	アシスタントのテキストが表示されたとき（表示のみ。トランスクリプトは変更しません）	いいえ
PreModelSwitch	セッションがモデルを切り替える前	はい
PostModelSwitch	モデルの切り替えが完了した後	いいえ（コンテキスト専用）

ツールの実行

イベント	発生するタイミング	ブロック可能か
PreToolUse	あらゆるツール呼び出しの前	はい
PermissionRequest	権限ダイアログが表示されたとき	hookSpecificOutput.decision のみで可能。終了コード 2 は無視されます
PermissionDenied	オートモードの分類器によってツールが拒否されたとき	いいえ
PostToolUse	ツール呼び出しが成功した後	いいえ
PostToolUseFailure	ツール呼び出しが失敗した後	いいえ
PostToolBatch	並列ツール呼び出しのバッチ全体が完了した後	はい
Elicitation	MCP サーバーがユーザー入力を要求したとき	はい
ElicitationResult	ユーザーが MCP による入力要求に応答したとき	はい

サブエージェント／チーム

イベント	発生するタイミング	ブロック可能？
SubagentStart	サブエージェントが起動したとき	いいえ（hookSpecificOutput.additionalContext を介してコンテキストのみ）
SubagentStop	サブエージェントが終了したとき	はい（stop_hook_active を確認し、transcript_path ではなく agent_transcript_path を読み取ります）
TeammateIdle	エージェントチームのチームメイトがアイドル状態になる直前	はい

タスク

イベント	発生するタイミング	ブロック可能？
TaskCreated	TaskCreate を介してタスクが作成されるとき	はい
TaskCompleted	タスクが完了としてマークされるとき	はい

設定／ファイルシステム

イベント	発生するタイミング	ブロック可能？
ConfigChange	セッション中に設定ファイルが変更されたとき	はい（policy_settings を除く）
InstructionsLoaded	指示ファイルが読み込まれたとき（CLAUDE.md、インクルード、glob／パスの一致、コンパクト化時）	いいえ（可観測性のため。終了コードは無視されます）
CwdChanged	作業ディレクトリが変更されたとき（cd）	いいえ
DirectoryAdded	セッションのワークスペースにディレクトリが追加されたとき	いいえ
FileChanged	監視対象のファイルがディスク上で変更されたとき	いいえ
WorktreeCreate	ワークツリーが作成されるとき	はい（ゼロ以外の終了コードの場合）。ペイロードから要求された name を読み取ります
WorktreeRemove	ワークツリーが削除されるとき	ゲートとして使用する前に、リファレンスのブロック可否の列を確認してください

コンパクト化／表示

イベント	発生するタイミング	ブロック可能？
PreCompact	コンテキストのコンパクト化前	はい
PostCompact	コンパクト化の完了後	いいえ
Notification	Claude Code が通知を送信したとき	いいえ

フック設定スニペット

最小限の settings.json 設定（~/.claude/settings.json または .claude/settings.json にコピーします）：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/preflight-guard.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/post-audit.sh",
            "async": true
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/pre-compact-state.sh"
          }
        ]
      }
    ]
  }
}

マッチャールール：空文字列または "*" はすべてに一致します。| で区切られた語句は完全一致のリストです（例："Edit|Write"）。その他の文字を含む文字列は JavaScript の正規表現です（例："mcp__memory__.*"）。

フックの種類：command（シェルスクリプト）、http（URL に POST）、mcp_tool（MCP サーバーのツールを呼び出す）、prompt（単一ターンの LLM）、agent（サブエージェントを起動。実験的）。

終了コード：0 = 成功。stdout を JSON として解析します。2 = 強制ブロック。stderr が Claude に渡されます。その他のゼロ以外の値 = ブロックしないエラーとしてログに記録されます。

ペイロードの変更（hookSpecificOutput を含む JSON で終了コード 0）：PreToolUse は permissionDecision に allow／deny／ask／defer を設定できます。PostToolUse は updatedToolOutput でツールの結果を置き換えられます。MessageDisplay は displayContent で画面上のテキストを書き換えられます（画面上のみ。トランスクリプトと Claude の表示内容は変更されません）。出力では、必ず発火したイベントを hookEventName に設定してください。

Exec 形式とシェル形式：シェルを介さず、クロスプラットフォームでの使用に対応するには "args": [...] を追加します。args を省略すると、パイプや && を使用する sh -c が使われます。

すべてのフックを無効化：緊急時にバイパスするには、設定で "disableAllHooks": true を設定します。

フックの種類を選ぶ

種類	レイテンシ	失敗モード	使用する場面
command	通常は最も低レイテンシ。実測してください	スクリプトのバグ、誤った終了コード、バイナリの欠落	決定的なチェック。デフォルトの選択肢です
http	ネットワークの往復	エンドポイント停止、タイムアウト、ローカルのフォールバックなし	監査情報をただちに外部へ送信する必要がある場合（SIEM、Webhook）
mcp_tool	サーバーによって異なります	サーバー未接続、ツールスキーマの不整合	ポリシーがすでに接続済みの MCP サーバー上にある場合
prompt	LLM 呼び出しが 1 回追加されます	非決定性、モデルに依存するトークンコスト	単一ターンの意味的な判断で十分な場合（ツールの使用は不要）
agent（実験的）	通常はレイテンシと使用量が増加します。実測してください	ホットパスで使用した場合のコスト／レイテンシの増加	複数ステップの意味的な検証（例：「受け入れ基準を満たしたか」）

より単純な種類ではチェックを表現できない場合に限り、このリストを下に進んでください。コストについて述べる前に、実測したレイテンシと使用量を比較してください。実際のコマンドとエージェントの選択については、references/hook-patterns.md §3 を参照してください。

実行モデルと優先順位

• 逐次ではなく並列です。 同じイベントに一致する登録済みフックが複数ある場合、Claude Code はすべてを並列で実行します。あるフックの出力が別のフックから見えるとは想定しないでください。また、優先順位を決めるために登録順に頼らないでください。同一の command フックはコマンド文字列と args の組み合わせで重複排除され、同一の http フックは URL で重複排除されます。意図は同じでもわずかに異なるフック（フラグが異なるもの）は重複排除されず、二重に実行されます。
• 競合する判断では制限の厳しい方が優先されます。 現在の Claude Code は deny を defer、ask、allow より優先して解決します。それでも、意見が異なる重複したフックは避けてください。有効なルールを見直せるようにマッチャーを絞り込み、単一のフックだけに頼らず、統合された設定をテストしてください。
• 設定の優先順位（code.claude.com/docs/en/settings に基づきます。フックのスコープが重要な場合は、そちらで再確認してください）：管理対象（組織）ポリシー > CLI フラグ > プロジェクトの .claude/settings.local.json > プロジェクトの .claude/settings.json > ユーザーの ~/.claude/settings.json。これは、このスキルの以前のバージョンで .claude/settings.local.json を最後に置いていた点を修正するものです。実際には、プロジェクト設定とユーザー設定の両方を上書きし、その逆ではありません。これら4つ以外にも、フックを含むスコープが2つあります。プラグインの hooks/hooks.json（プラグインが有効な間は常に有効）と、スキル／エージェントのフロントマター（スキルのフックはスキルが呼び出されるとセッション終了まで登録されたままになり、サブエージェントのフックは実行中のみ登録されます）です。すべてのスコープのフックは、互いを上書きするのではなく、統合されて一緒に実行されます。つまり、広いスコープのフックが狭いスコープのフックを暗黙に置き換えることはありません。そのため、この優先順位は主に disableAllHooks と単一値の設定が競合する場合に適用され、特定のフックが実行されるかどうかを決めるものではありません。
• allowManagedHooksOnly：エンタープライズ管理者は、管理対象設定でこの項目を設定し、管理対象の enabledPlugins によって強制的に有効化されたプラグインに付属するものを除いて、すべてのユーザー／プロジェクト／プラグインのフックをブロックできます。管理環境で登録したフックが突然実行されなくなった場合は、フックスクリプトをデバッグする前に、まずこれを確認してください。
• シェル条件を使わずにフックのスコープを絞り込む方法：ツールイベントフック（PreToolUse など）では if フィールドを指定できます。これは "if": "Bash(git *)" のような権限ルール文字列で、matcher だけでは表現できない条件でハンドラーの実行対象を絞り込みます。スクリプト内で同じロジックを重複させるより、こちらを優先してください。

推奨パターン

Claude

• ランタイムの事前チェックには SessionStart または Setup を使用します。
• Claude が処理する前にプロンプトを横取りまたは補足するには UserPromptSubmit を使用します。
• 対象を絞った許可、拒否、確認のガードレールには PreToolUse を使用します。
• フォーマットとスモークテストには PostToolUse を、失敗に特化した処理には PostToolUseFailure を使用します。
• 並列ツールの実行後、次のモデル呼び出しを制御するには PostToolBatch を使用します。
• 起動したサブエージェントにコンテキストを注入するには SubagentStart を、その出力を検証するには SubagentStop を使用します。
• 簡潔な状態情報を再注入するには PreCompact を、圧縮後の状況を確認するには PostCompact を使用します。
• ディレクトリ変更時に .envrc やローカル設定を再読み込みするには CwdChanged を使用します。
• フックポリシーの編集を監査するには ConfigChange を使用します。
• ワークツリーを適切な状態に保つには WorktreeCreate と WorktreeRemove を使用します。
• リロード時はプラグインのフックを一括でクリアして再登録し、古いハンドラーと新しいハンドラーが同時に残らないようにします。

サブエージェントの調整

SubagentStart で起動したサブエージェントにコンテキストを注入し、SubagentStop でその出力を検証します。

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/subagent-context.sh"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/subagent-validate.sh"
          }
        ]
      }
    ]
  }
}

SubagentStart は標準出力をそのまま注入しません。コンテキストは、JSON 出力の hookSpecificOutput.additionalContext を通じてのみサブエージェントに渡されます。systemMessage はトップレベルのフィールドで、ユーザーに表示されます。SubagentStop はサブエージェントが応答を返すのをブロックできます（終了コード 0 と decision: "block" を指定します）。まず stop_hook_active を確認し、サブエージェントのトランスクリプトである agent_transcript_path を読み取ってください。

Codex

• 外部コールバックには、長期にわたって安定し、信頼性の高い notify を使用します
• ターミナルでの通知ポリシーには tui.notifications を使用します
• ライフサイクルの自動化には、references/hook-templates.md §Codex の参照手順（イベント、ハンドラーの種類、非同期処理、updatedInput、管理ポリシーと信頼性の確認、発火に関する未修正のバグ）を実行したうえで、hooks.json を使用します。対象のランタイムで発火することを確認してください。信頼性が重要な場合は、notify に切り替えてください。
• セッション終了時のキャプチャに Stop を代用する前に、Codex のマッチャーテーブルでセッション終了イベントを確認してください。Stop はターンごとに発火する場合があるため、セッションごとに1回だけ実行する必要がある場合は重複を排除してください。
• Codex のリファレンスで確認していないイベントについて、Claude と同等のライフサイクルがあると想定しないでください

コミュニティのレシピ

知っておく価値のあるサードパーティ製フックです。コミュニティ提供のものとして扱い、本番セッションにインストールする前に、提供元を確認し、コードをレビューしてください。

• monitoring/context-timeline（aitmpl.com、Daniel San 経由、2026-04-26 スレッド）— claude-code-templates npm パッケージを通じて配布されています。npx claude-code-templates@latest として実行しないでください。変動する @latest は、レジストリがその時点で提供するものを、ユーザーの権限で実行します。公開済みのバージョンを1つレビューして正確に固定する（npx claude-code-templates@<reviewed-version> --hook monitoring/context-timeline）か、内容を読んだうえでフックスクリプトを .claude/hooks/ にベンダーとして取り込んでください。メインエージェントのコンテキストウィンドウと、並行して実行されているすべてのサブエージェントのライブタイムラインを表示します。これには、各サブエージェントが完了時に返すコンテキストも含まれます。複数ワーカーへのファンアウトやフォークされたサブエージェントのデバッグに役立ちます（フォークモードでオプトインが必要かどうかは、バージョンや利用環境によって異なります。§「Forking Parent Context Into Subagents」は../agents-subagents/SKILL.mdを参照してください）。これは可観測性のためのものであり、ポリシーを適用するものではありません。また、シークレットを扱うセッションに追加する前に、フックのソースを監査してください。

セキュリティルール

• 標準入力の JSON は信頼できない入力として扱ってください
• 使用前にフィールドを検証してください
• ファイル名の正規表現より、正規化されたパスのチェックを優先してください
• シェル変数をクォートし、eval を避けてください
• ログやコミット対象の設定ファイルにシークレットを含めないでください
• ブロッキングフックは対象を絞り、監査可能な状態に保ってください
• 複雑なシェルフックには ShellCheck を実行してください

既知の落とし穴

• Claude のライフサイクルイベントと Codex の通知サーフェスを互換性のあるものとして扱うこと。 解決策：フックを設定する前に、上記の「機能境界」表を確認してください。Codex には notify／tui.notifications と hooks.json のライフサイクルシステムという、別々のサーフェスが 2 つあり、どちらも Claude のイベントセットとは一致しません。Codex のマッチャー表を確認し、デプロイ前に実際のランタイムでテストしてください。

• 常時有効なフックに、時間のかかるネットワーク呼び出し、大規模なテストスイート、リポジトリ全体のスキャンを組み込むこと。 解決策：独自のランタイムでフックのレイテンシを測定し（公式の予算は公開されていません）、ループを目に見えて停止させる処理は、ドキュメントに記載された async: true の経路に移してください。単独のバックグラウンドジョブ（&）では、出力の配信とタイムアウト処理が失われます。同期フックは、高速で対象を絞ったチェックに限定してください。

• レビュー可能な差分や監査証跡を残さず、フック内でファイルや設定を変更すること。 解決策：通常の Git 追跡対象ファイルの経路を通して変更を書き込んでください。すべての変更を追記専用の監査ファイル（例：/tmp/claude-hook-audit.log）に記録してください。動作する例については、references/scenario-preflight-chain.md を参照してください。

• プラグインのフックを非アトミックに再読み込みし、新しいハンドラーと並行して古いハンドラーを有効なままにすること。 解決策：まずすべてのハンドラーを解除してから、新しいセットを登録してください。古いハンドラーを削除する前に、新しいハンドラーを追加してはいけません。登録手順が中断される可能性がある場合は、ロックファイルまたはアトミックスワップ（一時パスに書き込んでから mv）を使用してください。

• 正規化や境界チェックをせずに、ペイロードの形式、cwd、パスの値を信頼すること。 解決策：ペイロード内のパスは、使用する前に必ず realpath -m（または同等のもの）で正規化してください。処理を行う前に、解決されたパスが想定されるルート内にあることを検証してください。フックの種類にかかわらず、標準入力の JSON は信頼できない入力として扱ってください。

• 同じイベント上の 2 つのフックが順番に実行されると想定すること。 解決策：Claude Code は一致するすべてのフックを並列に実行し、Execution Model に示されている制限の厳しい優先順位（まず deny。独自の判定セットを持つイベントについては、正確な順序をフックのリファレンスで確認してください）に基づいて、競合する判定を解決します。それでも、同じイベント上のフックがめったに食い違わないよう、マッチャーの対象を絞ってください。調整よりも、レビュー済みの統合設定のほうが把握しやすくなります。

• stop_hook_active を確認せずに、ブロックする Stop または SubagentStop ゲートを書くこと。 解決策：stop_hook_active が true の場合は、0 で終了してください。このガードがないと、ランタイムのブロック上限に達して停止するまで、持続的な失敗条件によって追加ターンが強制されます。

• リファレンスに記載された名前ではなく、想定した名前でペイロードフィールドを読み取ること。 解決策：ドキュメントに記載されたフィールド名を使ってドライラン用ペイロードを作成し、ガードがブロックすべき入力をテストしてください。キーが間違っていると空の値として読み取られるため、ガードは何も出力せず 0 で終了し、合格したように見えます。テンプレートについては、scripts/test_hook_templates.py がこのテストを行います。

• 開発環境では正常に動作していたフックが、スクリプト自体に問題がないように見えるのに、いつの間にか実行されなくなること。 解決策：スクリプトをデバッグする前に、設定の優先順位と allowManagedHooksOnly を確認してください。組織レベルの管理ポリシーによって、ユーザー／プロジェクト／プラグインのフックがすべて抑制され、フックの故障と同じように見える場合があります。

アンチパターン

• すべてのフックで重い同期テストスイートを実行する
• Codex のイベント互換性について、ドキュメントにない前提を置く
• 正規表現だけでパスを検証する
• ペイロードや環境変数を、伏せ字処理なしでそのままログに記録する
• レビューできない危険な書き換えを、通知せずに行う

ナビゲーション

リソース

• references/hook-templates.md
• references/hook-patterns.md
• references/hook-security.md
• references/runtime-preflight-hooks.md
• references/scenario-preflight-chain.md — PreToolUse + PostToolUse + PreCompact を組み合わせた、エンドツーエンドで実行可能なシナリオ
• references/budget-and-loop-hooks.md — 自律ループ、トリガーによる実行、常時稼働ボット向けの予算、反復回数の上限、停滞、キルスイッチのフック
• assets/template-preflight-runtime-hook.sh
• scripts/test_hook_templates.py — 各テンプレートをドキュメント形式のペイロードに対して実行します。テンプレートを編集した後に実行してください
• data/sources.json

関連スキル

• ../agents-subagents/SKILL.md
• ../agents-mcp/SKILL.md
• ../agents-memory/SKILL.md
• ../agents-skills/SKILL.md
• ../agents-swarm-orchestration/SKILL.md
• ../ai-coding-agents-safety-envelope/SKILL.md
• ../ops-devops-platform/SKILL.md

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替として使う場合に限り、learnings.md を使用してください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶しておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを 1 つ learnings.md に追記してください。SKILL.md 自体は変更しないでください。