CodexのHooksとは — 「毎回必ず走る」処理を差し込む仕組みと、hooks.jsonの設定方法

Hooksとは — 実行ループの決まった場所に処理を差し込む

Hooksとは、Codexのエージェント実行ループの特定タイミングに、自分のスクリプトを差し込む仕組みです。コマンドを実行する前後、ツールを使うとき、タスクが完了したときなど、あらかじめ決められた地点で自動処理を走らせられます。

たとえばこんなことができます。危ないコマンドが実行されそうになったら止める。作業が終わるたびにログを1行残す。応答が完了したら通知を鳴らす。いずれも「毎回やってほしいが、毎回頼むのは現実的でない」たぐいの処理です。

差し込めるタイミングは3種類

フックを差し込めるタイミングを起動イベントと呼びます。イベント名は設定ファイルにそのまま書く項目なので、英語のまま覚えてしまうのが早いです。大きく分けると次の3種類になります。

実務でよく使うのは、この中の3つに絞られます。危ない操作を止めたいなら PreToolUse、作業の記録を残したいなら PostToolUse か Stop、セッションの立ち上げ時に決まった準備をしたいなら SessionStart です。まずはこの3つだけ頭に入れておけば十分です。

SessionEnd に注意点が1つあります。これはメインのセッションが終わるときだけ動き、サブエージェントの終了では実行されません。サブエージェント側の終了を捉えたいときは SubagentStop を使います。

書き先はhooks.json — 自分専用とプロジェクトの2か所

フックの書き先は、hooks.json という専用ファイルです。config.toml の [hooks] 欄に書く方法もありますが、同じ場所に両方書くと起動時に警告が出ます。hooks.json に統一するのがおすすめです。

置き場所は、サブエージェントと同じ2か所です。どの案件でも動かしたいフックは自分専用の場所へ、その案件だけのフックはプロジェクト側へ置きます。

~/.codex/hooks.json              ← 自分専用：どのプロジェクトでも動く

my-project/
└── .codex/hooks.json            ← プロジェクト専用：この案件の作業で動く

設定は自分で書かない — 「いつ」と「何を」を伝えるだけ

ここが本記事でいちばんお伝えしたいところです。フックの設定ファイルは、自分で書く必要がありません。「いつ」と「何を走らせるか」の2つを日本語で伝えれば、Codexが設定ファイルとスクリプトの両方を作ってくれます。

フックを設定したいです。

いつ：Bashコマンドを実行する直前
何を：実行しようとしているコマンドをスクリプトで確認して、危ないものは止める

~/.codex/hooks.json と、必要なスクリプトを作ってください。
どのイベントを使ったかと、動作の確かめ方も教えてください。

こう伝えると、次のような hooks.json が出力されます。これが「Bashコマンドの実行直前に、自分のチェックスクリプトを走らせる」という設定の完成形です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/check_bash.py",
            "statusMessage": "コマンドの安全を確認中",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

中身を丸暗記する必要はありませんが、どこが何を表しているかを知っておくと、あとから自分で直せます。上の例に出てくる項目は5つだけです。

この5つが分かれば、イベント名を差し替えれば別のタイミングに、command を差し替えれば別の処理に変えられます。ゼロから書くのではなく、作ってもらったものを土台に必要なところだけ直していく——これがいちばん早い進め方です。

Skills・Subagentsとの決定的な違い — AIの判断が入らない

フックには、呼び出す操作がありません。一度設定してしまえば、そのイベントが起きたときに必ずスクリプトが走ります。頼む必要もなく、逆に「今回はやらないで」と頼んでも止まりません。

ここがSkills・Subagentsとの決定的な違いです。スキルやサブエージェントは「使うかどうか」をAIが判断するため、使われないことがあります。フックにはその判断が入りません。

だからこそ、Hooksに入れるべきなのは「やってほしい」ことではなく「忘れては困る」ことです。作業ログの記録、作ったファイルの体裁を揃える処理、終了時の通知——このあたりが向いています。逆に「状況によっては不要」な処理を入れると、毎回走って邪魔になります。

「ついでに何かする」だけでなく「進めていいか判定する」側にも使える

もう一つ知っておきたいのが、スクリプトの結果で作業そのものを止められることです。たとえば PreToolUse で危ういコマンドを検知したときに、その実行をブロックできます。

これは統制の観点で大きな意味を持ちます。「このコマンドは実行しないでください」とAGENTS.mdに書くのは、あくまでAIへのお願いです。守られる確率は高くても、100%ではありません。一方でHooksによるブロックは、AIの判断を通らないシステム側の関門です。社内ルールのうち、破られたら困るものだけをHooksに移す——この切り分けが実務では効いてきます。

最初の1本は「記録」から始める

いきなりブロック系のフックから入ると、正常な作業まで止まってしまい、原因の切り分けに時間を取られます。当社が導入支援でおすすめしているのは、まず何も止めない「記録」のフックを1本作ることです。

1. 1まず記録だけのフックを作る — 応答が完了したタイミング（Stop）で、日時と作業内容を1行ファイルに追記するだけのフックを入れる
2. 21日使って、意図どおり走っているか確認する — ログが増えていれば、イベント名と設定は正しい
3. 3そのうえで、止めたい操作を1つだけブロック対象にする — 記録で仕組みが動くと確認できてから、判定を足す

順番を逆にしないことがポイントです。「設定が間違っている」のか「判定ロジックが厳しすぎる」のかを切り分けられる状態を先に作っておけば、あとの調整がずっと楽になります。

組織でHooksを使うなら — 「守らせたいこと」の棚卸しから

組織で使う場合、技術的な設定より先に決めるべきことがあります。それは社内ルールのうち、どれをAIの判断に委ねず強制するかです。ここを決めずにフックを増やすと、現場では「なぜか止まる」「なぜか毎回何かが走る」という状態になり、かえって使われなくなります。

実務では、次の順で棚卸しすると整理しやすくなります。（1）破られたら事故になるルール（顧客情報を含むファイルを外部へ出さない、本番環境に触らない、など）はHooksへ。（2）守ってほしいが例外もあるルール（表記の統一、報告の形式など）はAGENTS.mdへ。（3）特定の業務でだけ守るルールはSkillsへ。この3層に振り分けるだけで、どこに何を書くかで迷わなくなります。

当社のCodex研修・導入伴走支援では、貴社の実業務を題材に、この振り分け自体をワークとして一緒に行っています。ツールの設定方法を教えて終わりではなく、「何を強制し、何を任せるか」という運用設計まで含めて伴走するのが当社のスタイルです。