AIエージェントの必須検査をフック（hook）で止める｜Claude Code・Codex向け設計

AIエージェントに記事の公開といった仕事を任せると、URLの確認や承認の手続きが抜けることがあります。AIが「確認しました」と返した文章だけでは、実際にURLを開いたか、検査後に本文が変わっていないかを証明できません。

記事を非公開へ戻しても、公開中に読まれたり外部へ転載された内容までは回収できない場合があります。そのため、不十分な状態で送信される経路を公開前に止めます。

そこで、記事を送る直前などの決まったタイミングで確認処理を動かします。対象の公開処理が実行前フックを必ず通る構成なら、一つでも不合格のときに送信を止められます。

このように、AIの作業の節目をきっかけとして、利用者が登録した処理を実行する機能をフック（hook）と呼びます。

フックを使うには、AIが動いている環境へ利用者が処理を登録できなければなりません。そのため、今AIを動かしている場所がコマンドで操作する環境か、コード編集画面か、Web画面かによって、機能の利用可否が変わります。

たとえば、Claude Codeの公式フックリファレンスには、作業の節目へユーザー定義の処理を登録する方法が示されています。Codexの公式フックガイドでも、設定ファイルを使ってプロジェクト内にフックを置く仕組みが用意されています。

これらは2026年8月15日時点の公式資料に基づいています。同じCodexという名前であっても、使っている画面やバージョンによって利用できる機能は異なります。

一方、ChatGPT Webの公式案内などを2026年8月15日に本稿で確認した範囲では、この記事と同じユーザー定義フックの設定方法を確認できませんでした。ChatGPT Webを使う場合は、公開用スクリプトやCI（変更時に自動で検査する仕組み）など、チャットの外側に検査を置きます。

それでは、Claude CodeやCodexのようにフックを登録できる環境と、ChatGPT Webの通常チャットのように同じ設定を前提にできない環境を分けたうえで、必須検査をどう止めればよいでしょうか。

フック（hook）とは何か、どう書くか
AIに任せること、仕組みで止めること
止めるなら公開ボタンより前
公開前に確認する3つのこと
最後に人が見る場面
よくある質問
調査手法について

フック（hook）とは何か、どう書くか

AIが作業を進める途中には、ツールの実行前、ファイルの保存後、回答の終了前などの節目があります。製品によって使える節目と名称は異なります。フックは、対応する節目をきっかけとして、利用者が用意した検査や記録の処理を動かす仕組みです。

Claude Codeの公式リファレンスとCodexの公式フックガイドは、イベント情報を、項目名と値を組み合わせたJSON形式で処理へ渡す方法を説明しています。入力項目と応答形式は同一ではありません。

フックの設定は「いつ動くか」「どのツールを対象にするか」「どの処理を動かすか」の三要素で書きます。

Claude Codeの公式フックリファレンスに沿って、イベント、対象ツールを選ぶ条件であるmatcher、実行するhookを.claude/settings.jsonへ設定します。次は、WordPress投稿ツールの実行前に検査スクリプトを呼ぶ例です。matcherは実際の投稿ツール名へ置き換えてください。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^mcp__wordpress__publish_post$",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-before-publish.sh"
          }
        ]
      }
    ]
  }
}

Claude Codeの公式フックリファレンスによると、PreToolUse command hookは標準入力でイベントJSONを受け取ります。不合格の理由を標準エラー出力へ書き、終了コード2を返すと、対象ツールの実行を拒否できます。終了コード0はhookとして異議がないことを示しますが、通常の権限確認は残ります。

#!/usr/bin/env bash
set -u

input=$(cat)
tool_name=$(jq -r '.tool_name // ""' <<<"$input")

if ! python3 "$CLAUDE_PROJECT_DIR/scripts/verify-before-publish.py"; then
  echo "公開前検査が不合格です: $tool_name" >&2
  exit 2
fi

exit 0

Codexでは、設定を.codex/hooks.jsonまたは.codex/config.tomlへ置けます。次はTOML形式（設定を書くための記法）で、同じ投稿ツールを対象にする例です。

[[hooks.PreToolUse]]
matcher = "^mcp__wordpress__publish_post$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/check_before_publish.py"'
timeout = 30

check_before_publish.pyが不合格を検出した場合は、Codexの公式フックガイドに沿って、次のJSONを標準出力へ書きます。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "公開前検査が不合格です。"
  }
}

Codexのプロジェクト内command hook（コマンドを実行するフック）は、利用者が定義内容を確認して信頼した後に動きます。設定を変更した場合は再確認が必要です。Claude CodeとCodexでは入力項目や拒否の応答形式が異なるため、それぞれの現在の仕様に合わせます。

設定ファイルだけでは、検査内容は決まりません。検査プログラムには、承認記録の場所、照合する本文、合格条件、製品仕様に沿った拒否方法を定めます。

合格例に加えて、承認記録を外した不合格例も実行します。対象ツールが止まった記録を確認してから、公開経路へ組み込みます。

フックのイベントは、目的に合わせて選びます。公開や削除のように外部へ影響が生じる操作は、実行前イベントで検査します。一方、生成されたファイル形式の確認や実行記録の保存には、処理後のイベントを使えます。

処理後のイベントで不合格を見つけても、すでに外部へ送った内容までは回収できません。後続処理を止める場合は、その結果を必ず通るワークフローを別途設計します。

Codexの公式フックガイドでは、Web検索のようにホスト側で実行されるツール（hosted tool）は、CodexのローカルPreToolUseとPostToolUseの対象外とされています。ローカルツールのフックを有効にしても、すべての操作を観測できるわけではありません。

AIに「公開前に確認してください」と文章で伝える指示は、確認処理そのものではありません。自然文はAIへ方針や目的を伝えます。フックは、対応するイベントが起きたときに登録済みの処理を実行します。

二つの役割を分ければ、AIへの依頼文を検査の実行証拠として扱わずに済みます。

AIに任せること、仕組みで止めること

AIに作業を任せるときは、プロンプトで伝える方針と、プログラムで強制的に止める条件の役割を分けます。説明が読者に通じるか、ある例が誤解を生まないかといった文脈の判断は、AIに考えさせる仕事です。

一方で、公開用HTMLに不要なH1タグが混ざっていないか、本文が検査後に書き換わっていないか、送信前に承認トークンがあるかといった確認は、毎回同じ入力に対して同じ基準で合否を判定できます。こうした確認は、プログラムで条件を定めてフックなどの外部処理に任せます。

もし文脈の判断まで単純な文字列の検査へ押し込んでしまうと、本文を読まずに判定したように見せる事故を起こします。自然文のプロンプトは対象範囲や例外、検査が必要な理由を伝えるために残します。必ず走らせたい処理は、フックや、入力・出力・ツール呼び出しを検査して止めるガードレールとして定義します。

さらに、実行の観測、人の承認判断、システム上の実行権限も分けて考えます。実行ログやトレースは、どのツールや検査がどの順序で動いたかを観測する材料です。ログが存在しても、内容の合格までは示しません。

影響が大きい操作では、人が公開可否を判断します。認証情報や実行権限は、承認結果を確認するサービスアカウントなどが管理する場合もあります。自然文は方針、プログラムは機械的な停止、ログは観測、人は承認判断を担います。

調査の作業でも、この役割分担が役立ちます。最終レポートにURLが含まれているか、検索語と実行時刻が記録されているかは、プログラムの条件で機械的に検査できます。しかし、依頼に対して調査範囲が十分か、根拠の選び方が妥当かは、記録の意味を人が読まなければ判断できません。

Anthropicの評価例でも、主張が根拠で支えられているか、重要な事実を落としていないかを分けて評価しています。URLの数や検索回数だけをフックの合格条件にしてしまうと、記録の量と調査の妥当性を混同してしまいます。

問いの分解や対象言語の選び方、一次情報の探索、情報源の照合を記録します。その記録を機械的に確認する処理と、人が根拠を読んで判断する工程に分けます。

使う製品を選ぶ前には、こうした役割をどこに置くかを決めておきます。OpenAI Agents SDKのGuardrailsでも、入力、出力、ツールの境界を分けて確認する場所を定めています。

エージェント全体に一度だけ書いたルールで、すべてのツール呼び出しを確認できたと推測してはいけません。役割と境界を分類すると、処理を止めるタイミングを選べるようになります。

止めるなら公開ボタンより前

役割と境界を整理できたら、次は不合格のときにどう処理を止めるかを設計します。前節で整理したとおり、フックを動かすタイミングにはツールの実行前、実行後、作業終了直前があります。どこに検査を置くかは、失敗したときに何が起きると困るかを想像して選びます。

記事の公開や送信のように外部へ影響が生じる操作では、対象ツールを実行する前に検査します。Claude Codeの公式ガイドでも、副作用を避ける検査は実行前にブロックする構成が説明されています。

対象の公開処理がこの検査を必ず通るように接続すれば、不合格の本文を送信する経路を止められます。ただし、フックの対象外となる別経路がないことも確認します。

この「実行前に止める」という考え方は、フック以外の仕組みでも重要です。OpenAI Agents SDKのGuardrailsでは、入力に対する検査に並列モードとブロックモードの二つがあります。

並列モードはAIの作業と同時に始まるため処理が速いですが、検査で失敗が分かったときにはすでにツールが動いている可能性があります。公開のように副作用を避けたい場面では、入力検査が終わるまで最初のエージェントを開始しないblockingモードを検討します。

個々のツール呼び出しを止める場合は、その呼び出しの前後を検査するtool guardrailを使います。

一方で、実行後や作業終了直前のタイミングにも役割があります。実行後の検査は、すでに起きた公開を取り消せません。後続ワークフローが検査結果を受け取って制御する構成なら、保存したファイル形式を確認し、不合格のときに後続の作業を止められます。

作業終了直前のタイミングは、必要な記録やファイルがすべてそろっているかを確認するために使います。

このように、操作の取り返しがつかない場合は実行前、次の作業を制御する場合は実行後、成果物の漏れを防ぐ場合は終了直前と、目的によって検査を置く位置を使い分けます。位置が決まれば、不合格のときに後続の処理を止める仕組みを作ることができます。では、公開の操作を止める直前には、具体的にどのような記録を確認すればよいのでしょうか。

公開前に確認する3つのこと

公開の直前で処理を止める仕組みを作っても、どのような基準で何を確認したのかが分からなければ、検査が正しく行われたかを確かめられません。担当者が後から内容を追えるように、三つの重要な情報を一つの記録として残します。

一つ目は、検査した時点の本文と、これから公開する本文が全く同じであるという証明です。二つ目は、設定したすべての検査に合格しているという結果です。そして三つ目は、どの確認処理をいつ実行したかという履歴です。

本文が同じかどうかを確かめるためには、ファイル内容から計算する識別値であるSHAを使います。検査した対象ファイル、入力時のSHA、実行時刻、そして合否を表す終了コードを一つにまとめて記録します。

検査のあとに本文を編集するとSHAが変わるため、前の合格結果は使えません。記録されたSHAと現在のSHAを照らし合わせれば、合格したときと同じ本文かを再確認できます。

どのような順番で処理が動いたかも記録します。OpenAI Agents SDKのTracingは、モデル生成や関数ツール、エージェント間の引き継ぎ、検査処理、独自に記録するイベントなどを記録できます。

ただし、外部のフックや検査プログラムが自動でトレースへ入るとは限りません。トレース対象外の検査は、検査プログラム側で入力SHA、開始・終了、結果を別途記録します。

ただし、実行の記録があることと、品質の基準を満たしていることは別の問題です。実行記録で検査プログラムが動いた事実を確かめ、そのプログラムが正しく計算した結果によって合否を判定します。影響が大きい公開操作では、機械的な判定とは別に、人が公開可否を承認する手続きを置きます。承認する人と、API認証情報を保持して実行するシステムは同一である必要はありません。

最後に人が見る場面

自動検査と記録があっても、公開や外部送信、データ削除や決済のように失敗時の影響が大きい操作は、機械判定だけで進めるとは限りません。人が「この内容をいま出してよいか」を判断する工程を置きます。OpenAIの実務ガイドでも、高リスクまたは不可逆な操作を人の承認へ戻す考え方が示されています。

もし使っているAI製品にフックの機能がなくても、同じ仕組みは作れます。AIが行動を選ぶ場所の外側に処理を止める条件があればよいためです。たとえば、公開用スクリプトの先頭で検査結果を確かめる、CI（変更時に自動で検査する仕組み）を必須にする、ワークフローの途中で人の承認待ちにする、といった方法で代替できます。

AIへの自然文は方針を伝えるために使い、プログラムは検査の強制に使い、ログは事実の観測に使います。公開可否は人が判断し、実行権限は承認結果を確認するシステムが持つ場合があります。このように役割を分けると、AIに下書きや資料の整理を任せながら、未確認の公開経路を見つけて止めやすくなります。

よくある質問

Q1. プロンプトに「必ず確認」と書けばフックは不要ですか？

不要とは限りません。検査漏れが公開を止める条件なら、対象経路の外側に強制処理を置きます。漏れても人が後で直せる下書き段階なら、プロンプトだけで運用する選択もあります。

Q2. ChatGPTのWeb版でもこの記事のフックを使えますか？

同じ設定は前提にしません。WordPress API（記事を外部へ送る窓口）など、公開権限を持つ入口を一つに絞って検査を置きます。チャットが使う経路と人が使う経路の両方が、同じ入口を通るか試験してください。

Q3. フックに置いてよい検査は何ですか？

検査を置く前に、入力、判定式、不合格時に止める処理を一組で書けるか確認します。三つを固定できない項目は、フックで自動合否を決めず、人が判断する一覧へ残します。

Q4. 説明が読者に誤解を与えないかもフックで判定できますか？

最終判定はフックへ置きません。AIに誤解の恐れがある箇所と根拠を示させ、人が本文と根拠を読んで公開可否を決めます。文字数やリンク切れなど、意味を読まずに決められる補助検査だけをプログラムへ分けます。

Q5. 公開前の検査はどの境界へ置きますか？

WordPress APIなど、外部送信が始まる直前の呼び出しを対象にします。公開経路が複数ある場合は入口を一覧にし、どの入口でも不合格例が送信前に止まるかを試験します。

Q6. ログがあれば品質が合格したと判断できますか？

判断できません。ログには対象本文のSHAと検査時刻を残し、公開直前に同じ本文へ検査を再実行します。ログのSHAと現在のSHAが違う場合は、以前の合格結果を使いません。

Q7. フックがないAI製品ではどうしますか？

公開権限を持つ処理を一つのスクリプトやワークフローへ集約し、その入口で検査します。AIが別の経路から直接公開できない権限設計にすると、製品にフックがなくても停止条件を一か所へ置けます。

Q8. フックの設定はどこに書きますか？

全プロジェクトで使う検査は利用者側の設定へ、記事公開のように特定リポジトリだけで使う検査はプロジェクト側へ置きます。Codexでは公式フックガイドで読み込み場所と優先順を確認し、共有前に設定差分と実行コマンドをレビューします。

調査手法について

こちらの記事はグラフAIリサーチプラットフォームのSnorbeを使って作られています。Snorbeは研究開発・新規事業向けの調査テーマに応じた幅広い項目のオートリサーチや、ナレッジグラフの構築、構造化レポートの生成ができるAIリサーチツールです。

Screenshot

調査したいテーマを入力するだけで、AIが深堀りすべき観点や広げるべき調査項目をレコメンドしながら、自動でリサーチを進めます。収集した情報はナレッジグラフとして蓄積され、未調査領域（ホワイトスペース）を可視化しながら調査の網羅性を高めていけます。

また、観点マトリクスを30秒・構造化レポートを10分で自動生成する機能があり、出典付きのレポートをMarkdown/PDF形式でエクスポートできます。調査の元データも保存されるため、ファクトチェックや社内共有も容易です。

ご利用をご希望の方は、こちらよりお申し込みください。

また、グラフAIを活用した社内ナレッジ管理や、研究開発・新規事業のリサーチ支援、セルフホスト導入のご相談も受け付けています。お困りの方はお気軽にご連絡ください。

冨田到

市場調査やデスクリサーチの生成AIエージェントを作っています仲間探し中 / Founder of AI Desk Research Agent @deskrex , https://deskrex.ai