hooks / overview · 約 8 分

hooks のライフサイクル

公式 12 イベントと、command / mcp_tool だけが走ることを把握します。

学習目標

hooks は hooks.json または config.toml の [hooks] です。場所は ~/.codex/hooks.json、~/.codex/config.toml、<repo>/.codex/hooks.json、<repo>/.codex/config.toml です。 ^{[codex-hooks]}

前提

プロジェクトが trusted であること。初回は起動時の trust を承認し、ファイル変更後は起動し直します。--ignore-user-config は学習の常用にしません。他社製品の hook JSON を流用しません。

なぜ必要か

AGENTS.md はお願いです。hooks はツール実行の直前に機械的に割り込めます。

実行場所

実機。browser では JSON を公式入力例で単体実行する練習ができます。それは Codex 本体からの呼び出しではありません。

公式のイベントは次の 12 です。SessionStart、SessionEnd、SubagentStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SubagentStop、Stop、Interrupt。 ^{[codex-hooks]}

ハンドラは command と mcp_tool です。prompt と agent はパースされますが skip されます。 ^{[codex-hooks]}

複数ソースは置換ではなく全部実行します。同一レイヤに JSON と TOML があるとマージして警告します。 ^{[codex-config-ref]}

notify は hooks ではありません。

成功結果

.codex/hooks.json に PreToolUse と Stop があります。

失敗対処

Claude Code のイベント名を混ぜないでください。この章は公式 hooks ページだけを一次出典にします。