フックとは？AIエージェントの決まった時点で、必ず処理を実行する仕組み

確認日：2026年10月7日

AIエージェントに「ファイルを書き換えたら、必ず整形ツールをかけて」と伝えても、たまに忘れることがあります。指示を読んで動くかどうかは、モデルの判断に任されているからです。そこで使うのがフックで、AIエージェントの決まった時点に、利用者が用意した処理を必ず実行させられます。

本記事では、AIエージェントの開発元の公式ドキュメントをもとに、フックの仕組みと操作を止める流れ、使うときの注意を解説しましょう。

フックとは

フックは、AIエージェントが動く途中の決まった時点に登録しておく、利用者のプログラムです。シェルのコマンドやスクリプトで書くのが一般的で、「ツールを実行する前」「ツールを実行した後」「応答を終えたとき」のような時点が来ると、AIエージェントがそのプログラムを実行します。

フックを実行するのは、モデルではありません。モデルの外側で動くハーネスです。Claude Codeのドキュメントは、LLMが実行を選ぶのに頼らず、決まった処理を必ず起こせる点をフックの利点に挙げていました。

指示ファイルとの違い

毎回読ませる指示ファイル（AGENTS.mdなど）にも、「書き換えたら整形する」と書けます。それでもフックを使うのは、守られ方が違うからです。

指示ファイル（AGENTS.md）とスキルはモデルに読ませる文章で、守るかどうかはモデルの判断になる。フックと権限はハーネスがモデルの外で実行・判定するため、モデルが忘れたりだまされたりしても働くことを示す図

指示ファイルはモデルに読ませる文章なので、モデルが忘れたり、別の指示と取り違えたりすれば守られません。フックは、決めた時点が来ればハーネスが実行します。モデルが何を考えていても関係ありません。

使い分けの目安は、「判断が要るか」です。状況に応じて変えてよいことは指示ファイルやスキルに書き、例外なく毎回行うことはフックにします。

フックを登録できる時点

フックを登録できる時点は製品によって違いますが、主なものは共通しています。

フックを登録できる時点の例。セッションの開始、利用者の入力の送信、ツールの実行前、ツールの実行後、応答の終わりで、ツールの実行前の時点だけは操作を止められる

たとえば、セッションの開始時に作業の決まりを読み込ませたり、ファイルを書き換えた後に整形ツールを実行したりできます。応答を終えたときに、デスクトップへ通知を出してもよいでしょう。

なかでも大事なのが、ツールを実行する前の時点です。ここに登録したフックは、これから行う操作の内容を見て、実行を止められます。

操作を止める流れ

ツールを実行する前のフックで、危ない操作を止める流れを見てみましょう。

ツールを実行する前のフックの流れ。モデルがツールの実行を求めると、ハーネスはフックのスクリプトに操作の内容をJSONで渡す。スクリプトが止めると答えたら、ハーネスはツールを実行せず、理由をモデルに返す

モデルがツールの実行を求めると、ハーネスは実行する前に、操作の内容をJSONにしてフックのスクリプトへ渡します。たとえば、これから実行するコマンドの文字列や、書き換えるファイルの場所です。スクリプトはその内容を確かめ、終了コードで答えを返します。

Claude CodeとCodexでは、終了コードの意味がそろっていました。0なら「問題なし」で、操作はそのまま次へ進みます。2なら「止める」で、スクリプトが出力した文が理由としてモデルに伝わる仕組みです。モデルは理由を読んで、別のやり方を考えるでしょう。

たとえば、秘密の値を書いた .env ファイルを書き換えようとしたら止める、データベースの表を消すコマンドを止める、といった使い方ができます。

使うときの注意

フックは、利用者の権限でそのままプログラムを実行するものです。便利な反面、注意しておきたい点が3つあります。

1つ目は、他人が用意したフックの扱いです。リポジトリに含まれる設定ファイルにフックが書かれていれば、そのリポジトリで作業するだけで、書いた人のプログラムが自分のパソコンで動きます。Codexは、管理者が配ったもの以外のフックについて、実行する前に利用者の確認を求める作りにしていました。中身を読まずに有効にしないようにしましょう。

2つ目は、同じ時点に複数のフックがあるときの動きです。Claude Codeのドキュメントによると、当てはまるフックはすべて並行して実行されます。1つのフックが操作を止めても、ほかのフックの処理は止まりません。記録を書くフックなら、止められた操作も記録に残るわけです。

3つ目に、フックは万能ではありません。コマンドの文字列を調べて止める方法は、書き方を変えたコマンドを見逃すことがあります。ファイルやネットワークへの接続を確実に制限したいときは、権限の設定やサンドボックスと組み合わせてください。

製品での使われ方

ここでは、Claude CodeとCodexを例に挙げます。

Claude Codeでのフックの書き場所は、設定ファイル（settings.json）の hooks です。プロジェクトの .claude/settings.json に書けば、そのリポジトリで作業する人の全員に同じフックが働きます。登録できる時点は、ツールの実行前（PreToolUse）や実行後（PostToolUse）、入力の送信（UserPromptSubmit）などです。ツールの名前で、対象を絞ることもできます。

Codexでは、hooks.json か、設定ファイル config.toml の [hooks] に書く仕組みです。登録できる時点の名前はClaude Codeとほぼ同じですが、初期設定ではフック自体が無効になっています。使うときは、設定で機能を有効にしてください。