Agent SDK のフック｜道具の前後で止める・記録する

公開 2026-11-10更新 2026-11-10著者永上裕之仕事の自動化

#Claude Agent SDK #フック #PreToolUse #自動化 #セキュリティ

この記事の要点

フックは、AI が道具を使う前後や会話の節目で、自分のプログラムを動かす仕組み
道具を使う前（PreToolUse）なら、止める・書き換える・人に確認を回すができる。複数のフックでは「止める」が最優先
マッチャーは道具の名前にしか当たらない。ファイルの場所で絞るときは、フックの中で入力を確かめる

活用例：AI エージェントの操作をすべて記録して、あとから監査できるようにする

部署: 情報システム・内部監査
使うもの: Claude Agent SDK
AIに任せる: 資料の調査・ファイル作成などの作業
人が決める: 止める操作の一覧・記録の保存先と保存期間

AI エージェントを仕事に入れると、「この操作だけは絶対にさせたくない」「何をしたか全部残しておきたい」 という要望が必ず出てきます。権限の設定だけでは足りない細かい条件を、自分のプログラムで判断できるのが フック（hooks） です。

この記事では、公式ドキュメント「Intercept and control agent behavior with hooks」（2026年11月10日確認）にもとづいて、Claude Agent SDK のフックの仕組みと、仕事で使うときの組み方を整理します。SDK そのものの全体像は Claude Agent SDK とはで解説しています。

結論：フックは「道具の手前と後ろに立つ見張り役」

フックは、決まったタイミングで自分の関数を呼んでもらう仕組み です。AI が道具を使おうとした時、使い終わった時、会話が止まる時などに、SDK があなたの関数を呼び、返した答えに従って動きを変えます。

動く順番は次の5段階です。

出来事が起きる（例：道具を使う直前）
SDK が、その出来事に登録されたフックを集める
マッチャー（例："Write|Edit"）で、動かすフックを絞る
あなたの関数が、道具の名前や入力などを受け取る
関数が「許可・止める・書き換える・情報を足す」のどれかを返す

道具を使う手前と後ろに見張りの関門があり、危ない操作だけが止められる図（イメージ）

よく使う出来事は4つ

フックが動く出来事はたくさんありますが、仕事でまず使うのは次の4つ です。Python 版と TypeScript 版で使える出来事が違う点に注意します。

出来事	いつ動く	使いどころ
PreToolUse	道具を使う直前	危ないコマンドを止める・入力を書き換える
PostToolUse	道具を使った直後	変更したファイルを記録する・結果に情報を足す
Stop	作業が止まる時	途中の状態を保存する
Notification	状態のお知らせが出た時	許可待ちを Slack などに知らせる

会話の始まりと終わり（SessionStart・SessionEnd）は、TypeScript 版ではコードで登録できますが、Python 版ではコードのフックとしては使えません。 Python で使いたい時は、設定ファイルに書くシェルのフックにします。

道具の手前でできる4つの返事

PreToolUse のフックは、許可（allow）・止める（deny）・人に確認（ask）・あとに回す（defer）の4つを返せます。 止めるときは理由（permissionDecisionReason）を返すと、AI がその理由を読んでやり方を変えます。利用者に見せる一言（systemMessage）も別に返せます。

入力の書き換えもできます。たとえば、書き込み先の場所の前に決まったフォルダを付けて、作業用の場所の中にだけ書かせる、といった使い方です。

書き換えた入力（updatedInput）と「許可」を一緒に返すと、書き換えた内容でそのまま実行される
「確認」と一緒に返すと、書き換えた内容を人に見せて判断してもらえる
「あとに回す」と一緒に返すと、書き換えは捨てられる

複数のフックが違う答えを返したときは、止める＞あとに回す＞確認＞許可の順で強いほうが勝ちます。 フックは同時に動くので、順番に頼らず、1つずつ独立して判断する書き方にします。

つまずきやすい3つの落とし穴

1. マッチャーは道具の名前にしか当たらない

マッチャーで絞れるのは道具の名前だけ です。「この場所のファイルだけ止めたい」なら、フックの中で入力のファイルの場所を確かめます。また、"Write|Edit" で書き込みを見張っていても、AI がコマンド実行（Bash）でファイルを書けばフックは動きません。 コマンド経由も止めたいなら、サンドボックスの設定もあわせて使います。サンドボックスの考え方は Claude Code のサンドボックスで解説しています。

2. 見張りが落ちると、ふつうは素通りする

多くの出来事では、フックの関数がエラーで落ちても、操作はそのまま進みます。 見張りが壊れたら止めたい場合は、マッチャーに onFailure（Python では on_failure）を "block" と書きます（TypeScript 版 SDK 0.3.317 以降、Python 版 0.2.177 以降）。ただし Stop など一部の出来事では、この指定は効きません。

3. 時間切れにも決まった動きがある

フックには時間の上限があり、指定しなければ多くの出来事で600秒です。道具の手前のフックが時間切れになると、その道具の実行は止まります。 外部の確認に時間がかかるときは、timeout を長めに書きます。

仕事で使うときの組み方

最初は「止める」「記録する」の2本だけ作る のが続けやすい形です。

PreToolUse で、絶対に許さない操作（重要な設定ファイルへの書き込みなど）を止める
PostToolUse で、どの道具を何に使ったかを記録する。記録だけなら「待たない返事（async）」にすると、作業を遅くしない
許可待ちが長引く時のために、Notification で担当者に知らせる

権限の設定とフックは役割が違います。権限は「誰に何を許すか」の大枠、フックは「中身を見て判断する」細かい見張り です。権限の判定の順番は Agent SDK の権限設定で、Claude Code 本体のフックは Claude Code のフックで解説しています。

まとめ

フックは 道具の手前と後ろ、会話の節目で自分の関数を動かす 仕組み
道具の手前なら 止める・書き換える・確認に回す。複数のフックでは止めるが最優先
マッチャーは道具の名前だけ。場所で絞るのはフックの中で。壊れた時に止めたいなら onFailure を "block" に

出典

永上裕之

ユニコスクール株式会社代表取締役。AIエージェント専門のスクール＆コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。