メインコンテンツへスキップ
一部のツール呼び出しは、盲目的に許可するには重大すぎ、完全に禁止するには有用すぎ ます — 本番データベースへの書き込み、電信送金、実データに対する *.delete。それらには ループに人を入れたい：呼び出しを保留し、人間に見せ、それから yes のときのみ進めます。 それがまさに pending_approval 判定が行うことです。 このページはヒューマンインザループのエージェント承認フローをエンドツーエンドで カバーします：保留された呼び出しがどう表面化するか、レビュアーがコンソールまたは webhook からどう解決するか、そしてエージェントが承認された呼び出しをどう再送信するか。 判定がルール文法のどこに位置するかについては ファイアウォールルールを；その周りのポリシーモデルに ついてはファイアウォールの概要を参照してください。

​
1. 保留された呼び出しがどう見えるか

ルールが pending_approval に解決すると、エンジンは承認レコードをエンキューし、 呼び出しはツールに到達しません。リレーは error.code firewall_approval_pending の HTTP 400 を返します；エージェントがポーリングする承認 id は人間可読の error.message で運ばれます： 
{
  "error": {
    "code": "firewall_approval_pending",
    "message": "tool \"db.write\" held for approval (…) — resolve approval 507f1f77bcf86cd799439011 and retry with header X-OrcaRouter-Firewall-Approval"
  }
}
構造化された error.metadata（存在する場合）は判定の理由詳細 — reason_code、 factors、risk_score — を運び、承認 id ではありません。id をメッセージからパース するか、下記の SDK ヘルパーから取得します。 保留は即時です — リクエストをブロックするインラインのロングポールはありません。 エージェントは id を返してもらい、呼び出しはサーバー側で pending 状態にパークされ、 解決は帯域外で行われます。
保留された呼び出しは判定 pending_approval のファイアウォールイベントとして記録される ため、events ログで deny イベントのすぐ隣で フィルタ可能です — 何が保留されたか、そして承認レコードを介して何が解決されたかを 常に見られます。

​
2. 具体例 1 つ

本番接続への任意の書き込みを人間のために保留するルールを作成します： 
{
  "label": "hold prod db writes",
  "tool_name_glob": "db.write",
  "verdict": "pending_approval",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.connection\",\"op\":\"eq\",\"value\":\"prod\"}]}"
}
ここでライフサイクル：
1

エージェントがツールを呼ぶ

エージェントが prod に対して db.write を発行します。ルールがマッチし、エンジンが 呼び出しを保留し、リレーが approval_id を持つ 400 firewall_approval_pending を 返します。
2

人間（またはシステム）がレビューする

レビュアーが承認を解決します — コンソールで、または署名付き webhook コールバック 経由で（§3 を参照）。
3

エージェントが解決までポーリングする

エージェントは状態が pending でなくなるまで承認 id をポーリングします （§4 を参照）。
4

エージェントが承認ヘッダーで再送信する

approved で、エージェントは全く同じ呼び出しを一度、単回使用の X-OrcaRouter-Firewall-Approval ヘッダーを運んで再発行します。エンジンは承認を クレームし、その 1 つの呼び出しを通します。

​
3. 承認を解決する

pending 承認を approved または rejected に変える方法は 2 つあります。両方とも 最初の決定が勝つ保証を共有します — 着地する最初の解決がアトミックに適用され、 後の解決（または重複）は 200 を返す冪等の no-op です。
Approvals タブは保留中の保留を最古順にリストし、それぞれにツール名と、ポリシーと 発火したルール句を名指しする「Held because…」行が付きます。（生の呼び出し引数は 承認レコードに保存されません — ツール名、来歴、args ハッシュのみ — そのため レビュアーはツールとマッチした句から決定します。）レビュアーは次のように 1 つを 解決します：
PATCH /api/workspace/firewall/approvals/:id

{ "decision": "approved", "reason": "verified change ticket #4821" }
decision は approved または rejected でなければなりません。このルートは UserAuth（レビュアーのコンソールセッション）であり Developer+ にゲート されています — レビュアーのアイデンティティが認可なので、共有シークレットは 関与しません。解決はワークスペース監査ログに書き込まれます。
承認を外部システム（Slack 承認、チケットワークフロー）に配線するには、ワークスペースの 承認 webhook シークレットを設定し、それから決定を POST して返します：
POST /api/v1/firewall/approvals/:id/callback

{ "decision": "approved", "reason": "auto-approved by change-control bot" }
コールバックは HMAC-SHA256 で認証されます：X-Orca-Signature: sha256=<hex> ヘッダーを、ワークスペースの承認 webhook シークレットでキー付けされた <approval_id>\n<raw_body> の HMAC に設定します。id は署名された素材の一部なので、 キャプチャされた署名を別の承認に対してリプレイできません。設定されたシークレットが なければ、コールバック駆動の解決は拒否されます — 代わりにコンソールの PATCH 経由で 解決します。
承認 webhook の拒否パスを設定することは、無人実行のための安全なデフォルトです： 人間が保留を解決しなければ、呼び出しは単にパークされたままになり、エージェントは ポーリングを続けます。保留された呼び出しが決してサイレントに allow になることは ありません。

​
4. ポーリングしてから再送信する

エージェント側はポーリングループに続いて 1 回の再送信です。 ファイアウォールゲートウェイスコープのトークンで承認状態をポーリングします： 
GET /api/v1/firewall/approvals/:id
このルートはファイアウォールゲートウェイスコープのトークン（/evaluate と MCP ゲートウェイに使われるのと同じ専用ゲートウェイキー）を 必要とします；通常のリレーキーは 403 を受け取ります。承認ドキュメントを返します — state が pending ではなく approved または rejected になるまで待ちます。 クロスワークスペースまたは未知の id は 404 を返し、別のテナントにそれが存在することを 決して開示しません。 状態が approved になったら再送信します：同じツール呼び出しを、単回使用の ヘッダーに承認 id を運んで再発行します： 
X-OrcaRouter-Firewall-Approval: 507f1f77bcf86cd799439011
エンジンは承認をアトミックにクレームします — 単回使用。それを運ぶ最初の再送信は その 1 回限り通されます；同じヘッダーのリプレイは承認がすでに消費されたことを見つけ、 許可されるのではなく再び保留されます。rejected 承認は決してクレーム可能では ないため、エージェントは拒否を終端の deny として扱い、別のパスを選ぶべきです。
OrcaRouter MCP SDK の HITL ヘルパーはこのポーリングしてから再送信するループをあなたの ために実行します：evaluate が pending_approval を返すと、 GET /api/v1/firewall/approvals/:id をポーリングし、承認で承認ヘッダーとともに再送信 します — あなたはルールを作成しレビュアーを配置するだけです。

​
5. 状態とロール概観

状態意味エージェントのアクション
pending保留、決定待ちポーリングを続ける
approvedレビュアーが yes と言ったヘッダーとともに一度再送信
rejectedレビュアーが no と言ったdeny として扱う
アクションルート認証 · ロール
キューをリストGET /api/workspace/firewall/approvalsUserAuth · Developer+
解決PATCH /api/workspace/firewall/approvals/:idUserAuth · Developer+
Webhook コールバックPOST /api/v1/firewall/approvals/:id/callbackHMAC 署名付き
状態をポーリングGET /api/v1/firewall/approvals/:idゲートウェイトークン

​
6. 承認がどこに収まるか

pending_approval 判定はファイアウォール判定の ひとつです — ポリシー内の他のすべてと合成されます。知っておく価値のある 2 つの相互 作用：
  • スキル隔離が保留にエスカレートする。 保留されたツール呼び出しが 隔離されたスキルによって所有されている場合、deny 未満のものは自動的に pending_approval にエスカレートされます — 隔離と承認は 2 つの 方向から見た同じレビューゲートです。
  • シャドウモードがそれを平坦化する。 シャドウモードでは、pending_approval 判定は audit に格下げされ [shadow] would … としてログされるため、保留が実トラフィックを ゲートし始める前に、それがどのくらいの頻度で発火するであろうかを測定できます。
これは危険なツール呼び出しと 過剰なエージェンシーのための正しいコントロール です — 「人間に尋ねる」という判定が allow と deny の両方に勝るケースです。

​
次に進む場所

判定

6 つすべてのファイアウォール判定とデフォルト判定。

ゲートウェイキー

承認のポーリングに使うファイアウォールゲートウェイトークンを発行。

シャドウモード

保留が実トラフィックをゲートする前に測定。

ルールリファレンス

pending_approval 判定を生成するルールを作成。