AIコーディングエージェント 2026.05.31 更新: 2026.06.01

Codex Hooksで止める前に決めること

3行まとめ

VisualHooksで分ける5つの場面実行前、承認、実行後、入力、終了を分けます。

Pre

tool前確認。

Permission

承認文脈。

Post

結果確認。

Prompt

入力補助。

Stop

終了条件。

hooksは何でも止める場所ではなく、軽い補助から始めます。

Codex Hooksは、tool実行前、承認依頼、実行後、prompt送信前、終了時に追加処理を入れる仕組みです。
最初からblockを増やすのではなく、PostToolUseで結果を要約し、PreToolUseやPermissionRequestでは軽い警告から始めます。
hook commandは信頼対象です。matcher、timeout、stdout JSON、exit code、team reviewを決めてから共有します。

この記事では、OpenAI公式のHooks、Rules、Permissions、AGENTS.md、Advanced Configuration、Skills docsを確認し、2026年6月1日時点の情報として整理しています。hook event、対応handler、入出力の扱いは更新され得るため、導入時には最新docsと手元のCodex設定を確認してください。

この記事でわかること

Visual導入前の判断hooksを入れる前に決めることです。

Scope

どのeventか。

Trust

commandを信頼。

Timeout

待ち時間。

Output

返すJSON。

hookはCodexの作業経路に入るため、軽さと信頼性が重要です。

Codex Hooksで何を自動化し、何を止めないほうがよいか
PreToolUseとPermissionRequestを軽く保つ理由
PostToolUseでBash結果やtest結果をレビューする方法
UserPromptSubmitで入力補助やblockを扱う考え方
StopとSubagentStopで終了条件を見る使いどころ
matcher、timeout、stdout JSON、exit codeの注意点
チーム導入初週に見るべき失敗条件

Hooksは強力です。Codexがtoolを使う前後や、prompt送信前、session終了時にcommandを走らせられます。うまく使えば、危険なcommandの警告、test失敗の要約、未検証の検出、社内ルールの補助ができます。

ただし、hooksを「全部止める場所」として使うと、作業が重くなります。実行前hookが遅い、毎回長い追加文脈を足す、blockが多すぎる、hook command自体が信用できない、という状態になると、Codexの通常作業が進まなくなります。

Codex設定全体の置き場所は、公開済み記事のCodex設定を増やす前に決めることでも整理しています。この記事では、その中でもHooksだけを扱います。

前提知識

Visual公式docsで見る範囲仕様確認に使う情報です。

項目	内容	見方
Hooks		eventsとI/O。
Rules		command制御。
Permissions		approval。
AGENTS.md		作業指示。
Skills		手順化。

hookの仕様や対応eventは導入時に再確認します。

OpenAI公式のHooks docsでは、Codex Hooksが特定eventでcommand hookを実行し、stdinへJSON objectを渡し、stdoutやexit codeで結果を返す仕組みとして説明されています。2026年6月1日時点のdocsでは、実行されるhandlerはcommand typeが中心で、promptやagent handlerはparsedされてもskipされる扱いが説明されています。

Hooks docsでは、PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、UserPromptSubmit、SubagentStart、SubagentStop、Stop、SessionStartなどのeventが扱われています。複数fileにmatching hookがある場合は複数実行され、同じeventの複数command hookは並行して起動される点にも注意が必要です。

公式情報で確認する範囲

確認先	見ること
Hooks	event、matcher、stdin JSON、stdout JSON、exit code、timeout
Rules	command単位で止める設定
Permissions	approval requestとpermission mode
AGENTS.md	repoの作業指示
Advanced Configuration	configとproject設定
Skills	繰り返し手順の固定

注意点

hook commandは、Codexの作業経路に入ります。特にnon-managed command hooksは、実行前にreviewされ、信頼できることを確認する必要があります。teamで使うなら、hook script自体をcode review対象にします。

また、hookはsecurity境界のすべてを置き換えるものではありません。危険commandの拒否はrulesやpermissions、network policy、branch protection、人間reviewも組み合わせます。

まずhookで止めるものを分ける

Visualhook設計の順番何を見るかを先に分けます。

1Detect
条件を見る。
2Warn
文脈を足す。
3Block
止める。
4Review
結果を見る。

止めるhookを増やす前に、警告だけで足りるかを見ます。

Hooksを入れる前に、何をしたいのかを4つへ分けます。

目的	例	最初の実装
Detect	commandやpromptの条件を見る	警告だけ
Warn	追加文脈を返す	`systemMessage`やcontext
Block	実行やpromptを止める	条件を狭くする
Review	実行結果を見る	PostToolUseで要約

最初からblockを多くしないほうがよいです。まず観測し、警告し、効果があるものだけblockへ進めます。

実行前に見る

実行前に見るべきものは、軽い条件です。tool名、commandの文字列、対象path、permission requestの文脈などです。ここで長いlintやtestを走らせると、通常作業のたびに重くなります。

実行前hookの良い使い方

使い方	理由
deploy commandに警告	本番影響を見落としにくい
secret pathの読み取りを警告	誤操作を早く止める
`git push`を確認対象にする	外部状態が変わる
migration commandをaskへ寄せる	data影響が大きい

このあたりはRules docsの考え方とも重なります。Rulesで止めるべきものと、hookで補助するものを分けます。

実行後に見る

実行後に見るものは、Bash output、exit code、test結果、lint結果、diffの変化です。実行前より情報が多いため、PostToolUseのほうが要約や次の行動提示に向いています。

たとえば、npm testが落ちたときに、失敗test名、最初のerror、再実行すべきcommandを短く返すhookです。Codexが長いlogをそのまま読むより、次の一手が見えやすくなります。

PreToolUseとPermissionRequestは軽くする

Visual実行前の使いどころtool call前の補助です。

項目	内容	見方
PreToolUse		tool名と入力を見る。
Permission		承認依頼を見る。
Matcher		対象を絞る。
Fast		重い処理を避ける。

実行前hookが重いと、通常作業の体感が悪くなります。

PreToolUseはtool call前のhookです。PermissionRequestは承認依頼に関わるeventです。どちらも、作業が進む前に入るため、重くしすぎないことが大事です。

tool call前の確認

PreToolUseでは、matcherで対象toolを絞ります。Hooks docsでは、Bash、apply_patch、MCP tool名のようなmatcher例が示されています。すべてのtoolにhookを入れるより、Bashやwrite系など、影響が出やすいtoolに絞ります。

対象	hookで見ること
Bash	command、cwd、危険語
apply_patch	対象file、変更範囲
MCP tool	read/write、外部service
Web/browser	外部送信やログイン状態

PreToolUseで避けること

PreToolUseで避けたいのは、重い処理と広すぎる判定です。

避けること	理由
毎回test suiteを走らせる	tool実行前に重すぎる
すべてのBashをblock	通常確認も止まる
長いstdoutを返す	Codexの文脈を汚す
外部APIへ毎回問い合わせる	遅く、壊れやすい

実行前hookは、短く、速く、対象を絞ります。

approval requestの文脈

PermissionRequestでは、承認を求めるときに追加文脈を返す設計ができます。たとえば「このcommandはdeployに見える」「このpathはsecretに近い」「このoperationはbranch外へ影響する」といった警告です。

ここでも、hookは判断材料を足すものとして扱います。最終的に許可するかは、approval policyや人間判断に残します。

Codexに外部通信や広い権限を持たせる設計は、公開済み記事のCodexにインターネットアクセスを許可する前にも参考になります。PermissionRequest hookは、その判断を助ける補助線です。

PostToolUseで結果をレビューする

Visual実行後に見るもの結果を見て追加文脈を返します。

Bash

出力とexit。

Test

失敗要約。

Diff

影響範囲。

Signal

次の行動。

重い判断は実行前より実行後に寄せると扱いやすくなります。

PostToolUseは、tool実行後に結果を見られるhookです。実行後なので、command outputやtool resultを見て、次の行動につながる要約を返しやすくなります。

Bash outputを見る

Hooks docsの例でも、PostToolUseでBash outputをreviewするcommand hookが示されています。実務では、testやlintの結果を要約する用途が扱いやすいです。

command	hookで返すと便利な情報
test	失敗test、最初のerror、再実行command
lint	rule名、対象file、修正の方向
typecheck	型errorの集約
build	失敗stage、missing dependency

出力は短くします。長いlogをそのまま返すと、Codexの次の判断が鈍ります。

lint/test結果を要約する

test失敗を要約するhookでは、次のように分けます。

項目	例
status	failed / passed / skipped
target	package名、test file
first error	最初のerrorだけ
next action	再実行、対象file確認、rollback

この構造にすると、Codexが「何を直すべきか」を見失いにくくなります。AIコーディングのbenchmarkやtest repairを設計する話は、公開済み記事のAI Coding Benchmark Kitの作り方ともつながります。

UserPromptSubmitで入力を補助する

Visual入力前に足す文脈promptを送る前の補助です。

Context

追加情報。

Block

確認を求める。

Policy

社内観点。

Light

短く返す。

prompt補助は便利ですが、毎回長い追加文脈を足さないようにします。

UserPromptSubmitは、ユーザーpromptが送信される前に動くeventです。Hooks docsでは、このeventでmatcherは使われず、promptを含むinputが渡され、plain textやJSONで追加developer contextを返せることが説明されています。条件によってpromptをblockする方法も示されています。

追加developer context

UserPromptSubmitで便利なのは、追加文脈です。たとえば、promptが「本番に出して」だけなら「deploy前に対象branchとrollbackを確認する」といったdeveloper contextを足せます。

prompt傾向	追加する文脈
曖昧な実装依頼	変更範囲と完了条件を確認
本番影響	rollbackと承認を確認
secret関連	表示せずscopeを確認
大きなrefactor	先に差分案を出す

ただし、毎回長いcontextを足さないようにします。追加文脈が多すぎると、元の依頼が埋もれます。

blockの扱い

UserPromptSubmitでは、条件によってblockできます。たとえば、明らかにsecret表示を求めるpromptや、未確認の本番操作を求めるpromptです。

blockする前の基準

blockは強い操作なので、基準を狭くします。

block候補	理由
secret値の表示	一度出ると回収が難しい
本番deployの直接依頼	承認とrollbackが必要
destructive commandの即実行	復旧不能リスク
外部送信の曖昧な依頼	送信先とdata確認が必要

迷うものはblockではなく、追加contextや確認要求にします。

StopとSubagentStopで終了条件を見る

Visual終わり際の確認完了前に見ることです。

項目	内容	見方
Stop		最終状態。
SubagentStop		分担結果。
Continue		続行判断。
Reason		止めた理由。

終了時hookは、未検証や未完了を見落としにくくするために使います。

StopとSubagentStopは、作業の終わり際に効くhookです。完了報告の前に、未検証、未完了、追加確認が必要な点を拾う用途に向きます。

継続すべき作業

Stop hookでは、終わる前に次のような条件を見ます。

条件	返す文脈
test未実行	未検証として明記
diff未確認	変更fileを確認
TODO残り	完了条件を満たすか確認
publish未確認	公開URLやnoindexを確認

Hooks docsでは、Common output fieldsとしてcontinueやstopReason、systemMessageが説明されています。ただしeventごとに対応fieldが違うため、Stopで使える形とPreToolUseで使える形を混同しないようにします。

subagentの結果確認

SubagentStopは、subagentを使うworkflowで便利です。分担結果を受け取り、足りない証跡や矛盾を拾う補助にできます。

たとえば、1つのsubagentが公式docsを確認し、別のsubagentが実装差分を確認した場合、SubagentStopで「source URLが足りない」「test結果がない」「結論だけで根拠がない」といった警告を返す用途です。

SubagentsやSkillsとの分担は、公開済み記事のCodexのSkills・Plugins・Subagents・MCPをチームで使う前にでも整理しています。

導入初週の進め方

Visual1週間の導入順軽いhookから始めます。

1日目
PostToolUseで要約。
2日目
PreToolUseで警告。
3日目
Permission文脈。
5日目
Prompt補助。
7日目
Stop確認。

最初からblockを増やさず、観測と警告で効果を見ます。

Hooksは、最初の1週間で小さく入れるのがよいです。いきなりblockを大量に入れると、どのhookが作業を止めているか分からなくなります。

日	やること	見ること
1日目	PostToolUseでtest結果を要約	出力が短く役に立つか
2日目	PreToolUseで危険commandを警告	誤検知が多すぎないか
3日目	PermissionRequestで承認文脈を足す	人間判断が楽になるか
4日目	UserPromptSubmitで曖昧依頼を補助	長すぎないか
5日目	Stopで未検証を拾う	完了報告が正確になるか
7日目	block条件を最小限追加	本当に止めるべきものだけか

最初に見るべきなのは、hookの数ではありません。通常作業の邪魔をせず、危険な操作や未検証を減らせているかです。

継続判断の基準

次の4つを満たすhookだけ残します。

判断	継続条件
軽さ	通常作業の体感を悪くしない
信頼	hook scriptがreviewされている
精度	誤検知が少ない
保守	event、matcher、timeoutが明確

満たさないhookは、削るか、warningだけに戻します。hooksは増やすより、効く場所に少なく置くほうが強いです。

FAQ

Visualよくある迷いhooks導入で詰まりやすい点です。

Block?

慎重に使う。

Timeout?

短く保つ。

Matcher?

対象を絞る。

Trust?

commandをreview。

hookは強力ですが、通常作業を止めすぎないことが大事です。

Hooksはrulesの代わりになりますか

代わりではありません。rulesはcommand制御、hooksはevent時の追加処理です。危険commandを止めるならrulesやpermissionsも使い、hooksは文脈追加や結果レビューに寄せると扱いやすくなります。

最初にどのeventから使うべきですか

PostToolUseから始めるのが無難です。実行後の結果を要約するだけなら、通常作業を止めにくく、効果も見やすいからです。

blockはいつ使いますか

secret表示、本番操作、破壊的削除、外部送信のように、誤実行時の影響が大きいものに限定します。迷うものはblockではなくwarningや追加contextにします。

hook commandはrepoに置くべきですか

チームで共有するならrepo管理が向いています。ただし、hook script自体をreview対象にし、誰が更新するかを決めます。個人用の実験hookをいきなり共有しないほうが安全です。

timeoutはどれくらいにしますか

用途次第ですが、実行前hookは短く保ちます。Hooks docsではtimeoutの扱いが説明されています。重い処理はPreToolUseではなくPostToolUseや明示的なactionへ寄せます。

参照した主な情報源

https://developers.openai.com/codex/hooks
https://developers.openai.com/codex/rules
https://developers.openai.com/codex/permissions
https://developers.openai.com/codex/guides/agents-md
https://developers.openai.com/codex/config-advanced
https://developers.openai.com/codex/config/skills

更新履歴

Visual確認と更新の記録公式情報は更新されます。

2026年6月1日
OpenAI公式Codex docsを確認して初版を作成しました。

導入時には最新のHooks docsと手元の設定を確認してください。

2026年6月1日: OpenAI公式Codex docsを確認し、Hooksを実行前確認、承認文脈、実行後レビュー、入力補助、終了条件に分ける記事として初版を作成しました。