「承認機能あり」の検収を控えている方へ

エージェントに書き込み操作を任せる開発が進んでいて、「重要操作は人間が承認する」という要件の検収を控えている方、あるいはその実装を任されている方に向けて書いています。

先に事故のかたちを言います。承認を実装したのに、呼ばれない。機能が壊れているのではありません。権限の評価順序という仕様どおりに動いた結果、承認ゲートの手前で操作が許可されるのです。この記事はClaude Agent SDKを例に、その仕組みと防ぎ方を説明します。考え方は他の基盤でも同じです。

事故のかたち: コールバックが呼ばれない

Claude Agent SDKには、エージェントがツールを使おうとした瞬間に呼ばれる承認コールバック（canUseTool）があります。ツール名と入力を受け取り、許可か拒否を返す。ここに「書き込み系は人間の確認画面を出す」という処理を書けば、承認ゲートの完成に見えます。

ところが公式ドキュメントは、太字の警告でこう述べています。自動承認されたツールはコールバックに到達しない。許可ルールに載せたツールや、編集を自動許可するモードで通った操作は、コールバックを素通りして実行されます。

つまり「Readは安全だから許可リストに入れよう」という自然な設定が、そのツールに関する限り、あなたの書いた承認処理を無効にします。SDK自身がこの危うさを知っており、TypeScript版は該当する構成を検知すると、コールバックが影に入っている旨の警告（CLAUDE_SDK_CAN_USE_TOOL_SHADOWED）を一度だけ出します。警告を監視していなければ、静かな素通りです。

権限は6段階の順番で評価されます

素通りの正体は、評価の順序です。エージェントがツールを使おうとすると、SDKは次の順で判定します。

順 段階 働き
1 フック 最初に実行される自作コード。ここでの拒否は全モードで有効
2 拒否ルール 一致した操作を遮断。全許可モードでも効く
3 確認ルール 一致した操作をコールバックへ回す。全許可モードでも効く
4 許可モード モードに応じて自動承認。編集自動許可・全許可など
5 許可ルール 許可リストに一致すれば承認
6 承認コールバック ここまでで決まらなかった操作だけが到達する

読み方のポイントは2つです。第一に、コールバックは最後の受け皿であって関所ではありません。4と5で承認された操作は6に来ません。第二に、確認ルール（3）は許可モード（4）より先に評価されるため、「この操作だけは必ず人間に聞く」を確実にやりたければ、コールバック側ではなく3以前の段階に書く必要があります。

なお許可モードは6種類あります。標準・確認の代わりに拒否・編集の自動許可・全許可・計画モード・自動判定です。無人運用では「確認の代わりに拒否」を既定にすると、想定外の操作が黙って実行される代わりに黙って失敗する、安全側の縮退になります。

全操作を確実に検査するならフックです

では「すべての操作を例外なく自前の検査に通したい」ときはどうするか。公式ドキュメントの答えは明確で、コールバックではなく最初に走るフック（PreToolUse）に書くことです。フックは評価の1段目にあり、全許可モードでも実行され、拒否できます。

役割分担で覚えるのが実用的です。

「人間の承認」という1つの要件が、実装では4つの置き場所に分かれます。要件定義の一文をどこに置いたかを言えない実装は、素通りを疑ってください。

出回っている解説の順序は誤っていました

この評価順序について、付記しておくべきことがあります。今回の調査中に確認した比較解説では、評価順序が公式ドキュメントと食い違っていました。許可ルールが確認ルールより先に評価される、という逆の順序で説明されていたのです。

逆順で理解すると、設計が反転します。「許可リストで通した操作は、確認ルールでは捕まえられない」と誤解し、必ず確認したい操作を捕まえるつもりの設定が、実際には別の意味を持ちます。承認まわりは、まさにこうした細部が安全性そのものです。一次情報と二次情報の読み分けで書いたとおり、実装前に公式ドキュメントの該当ページを直接確認してください。

検収で確認する4点

承認ゲートの検収チェック

  • 許可リストと承認対象の突合表を出してもらう: 自動承認される操作の一覧と、承認を要する操作の一覧を並べ、重なりがないことを確認します。重なった操作は素通りします
  • 素通り警告の監視有無を確認する: コールバックが影に入る構成をSDKが警告します。この警告をログで拾う運用になっているかを聞きます
  • 「必ず人間に聞く操作」がどの段階に実装されているかを聞く: コールバック頼みなら要注意です。確認ルールかフックに置かれているのが正解です
  • 無人運用時の縮退を実演してもらう: 承認者が不在のとき、対象の操作が「実行される」のではなく「拒否される」ことを、実際に動かして確認します

受入テストの項目書に、この4行をそのまま追加できます

現場メモ

評価順序の誤解は、動作確認では見つかりにくいのが厄介です。デモで試す操作はたいてい許可リストの外にあり、コールバックが毎回呼ばれるので、承認は機能しているように見えます。素通りするのは、許可リストに入った操作だけ。つまり「よく使うから許可に足しておいた」操作から順に、ゲートが消えていきます。私たちは検収で、承認の画面ではなく許可リストの側から先に見ます。

発注側にとっての意味

「人間の承認を挟む」という要件は、書くのは1行、実装は6段階です。権限を最小に絞る原則はエージェントに任せる前に権限をコードで絞るに、データアクセスの統制は権限をコードで絞る実装の公開例に、承認をどの操作に置くかの業務側の設計は組み込みの責任分担に書きました。この記事はその実装層です。

承認設計のレビューや、既に動いているエージェントの素通り検査を依頼したい場合は、お問い合わせからご相談ください。許可リストと承認対象の突合表を作るところから入ります。