ヒューマン・イン・ザ・ループ承認ワークフロー
escalate_on_deny は承認リクエストを発行しません拒否は発動します。 escalate_on_deny: true のタグが付いたルールは、記述されたとおりに拒否します。一致したルール自身の policy_id、effect: "deny"、reason_code: "RULE_MATCH" が返されます。
英語の原文 -- 翻訳は技術レビュー待ちです
You are protected.
英語の原文 -- 翻訳は技術レビュー待ちです
The escalation does not. The tag is accepted by the policy schema and
carried into the policy bundle, and no enforcer acts on it: no approval request
is raised, no approver is notified, and decision.requires_approval stays
false.
このタグに対応するために decision.requires_approval で分岐するコードは、実行されることがありません。（別の仕組みである LLM 関数ポリシーの require_approval は、このフィールドを設定します。escalate_on_deny はそれに接続されていません。）追跡: #2391。
現時点で承認をリクエストするには、明示的に呼び出してください。 client.request_approval(decision) が、実際の承認リクエストを POST します。タグがこれを代わりに呼び出すことはありません。承認コールバックを参照してください。#2363 のとおり、承認者向けの /approvals ページは本番環境ではゲートされているため、リクエストは API 経由で解決します。
これは、公開済みの Python SDK（controlzero 1.13.14）と、公開済みの Node SDK（@controlzero/sdk 1.13.6）のどちらにも当てはまります。
対応モード: Hosted Hybrid Local 利用可能なプラン: Teams（Free と Solo は閲覧のみ可能で、有効化はできません。別の承認者が必要です） ステータス: BETA SDK: 1.6.0+（バリデーターへの追加は 1.5.8）
承認リクエストの経路は、ホスト型（SaaS）プランを含むすべてのデプロイメントで動作します。ポリシーがリクエストを発行し、SDK は一時停止します。管理者が Settings -> Approvals で、スコープ（組 織、プロジェクト、API キー）ごとにこのフローをオンにします。この機能は BETA で、デフォルトではオフです。
承認者向けのページには、まだアクセスできません。承認の受信トレイとリクエスト詳細のルートは、出荷済みのどのデプロイメントでもダッシュボードにリダイレクトされ、通知のディープリンクも同じパスを指しているため、現時点では承認者が UI からリクエストを解決することはできません。
英語の原文 -- 翻訳は技術レビュー待ちです
A request nobody resolves runs to its deadline and the SDK raises HITLTimeoutError with a synthesized deny, so the original deny stands.
エンドツーエンドのガイドについては、承認を設定するを参照してください。
ポリシーエンジンがツール呼び出しを拒否したとき、ユーザーに現在できるのは、拒否メッセージを読む、ポリシーを編集する、再デプロイするという選択肢だけです。手間が大きく、お客様は摩擦を避けるためにポリシーを緩めてしまい、ガバナンスが損なわれます。承認は、スコープごとのトグルがオンで、コードが承認を求めた場合に、拒否の瞬間をリクエストの瞬間に変えます。
仕組み
- 厳格なポリシーを作成する。 レビュー対象にしたい
denyルールを書きます。 - エージェントがルールに該当する。 呼び出しは拒否されます。コードは、その拒否が人間に見てもらうべきものだと判断し、
client.request_approval(decision)を呼び出して、承認リクエストをバックエンドに POST します。この手順は明示的に行うもので、ポリシーのタグが代わりに実行することはありません。 - 承認者に通知される。 アプリ内のベルとメール（セッションが切れている場合はマジックリンク付き）で通知されます。
- 承認者が次のいずれかを選ぶ。 拒否 / 1回のみ承認 / 24時間、7日、30日間承認 / 無期限に承認。
- SDK が再開する。 エージェントは呼び出しを続行するか（許可の経路）、拒否を尊重します（拒否の経路）。
英語の原文 -- 翻訳は技術レビュー待ちです
Every approval is auditable: who approved, when, why, what grant was created or what policy diff was applied.
判定の種類
承認者は、次のいずれかを選びます。
| 判定の種類 | 動作 | ストレージ |
|---|---|---|
approved_once | Single call only; auto-revoke after first use OR 5 minutes | hitl_grants row, args_hash-bound |
approved_timed | 24時間、7日、30日、またはカスタム（最大90日） | hitl_grants の行、expires_at に紐付け |
approved_forever_grant | 無期限。/grants 管理ページから取り消せます | hitl_grants の行、expires_at IS NULL |
approved_forever | ポリシーの編集: deny の上に allow ルールを挿入します | ポリシーのバージョンが上がり、ルールに created_by_hitl メタデータが付きます |
デフォルトは approved_once です。管理者は、パターンが見えてきたらスコープを段階的に広げます。
「この承認を誰が使えるか」の選択
付与を伴うすべての判定で、承認者はプリンシパルのスコープを選びます。
- <requestor_email> のみ（ツールと期限付きの付与のデフォルト）
- プロジェクト X を使うすべてのユーザー
- マシン Y 上のすべてのユーザー
- キー Z を使うすべてのユーザー
- カスタム条件（管理者がルールを手動で編集）
シークレットの場合、approved_forever であってもデフォルトはユーザースコープです。プロジェクト全体に対する長期のシークレット付与は、ボールトを損ないます。シークレットの承認を参照してください。
ID のレイヤー
承認フローでは、どの人間がリクエストを引き起こしたかを把握する必要があります。API キーはマシンの認証情報であり、共有されることがあります。SDK では、インストール時に controlzero install --email <email> が必要で、そのメールアドレスは、すべてのバックエンド呼び出しで X-CZ-Requestor-Email ヘッダーとして送信されます。
これは、共有 API キー（プロジェクトキー、CI キー）で最も重要になります。脅威モデルとフォレンジックのストーリーについては、マルチユーザーキーを参照してください。
承認が「そうではない」もの
- 適切なポリシー作成の代わりではありません。 承認は、拒否によってお客様がルールを緩めざるを得なくなる場合の、逃げ道です。
英語の原文 -- 翻訳は技術レビュー待ちです
- Not silent. Every approval is in the audit log. The
/approvalspage is the canonical surface for security review.
英語の原文 -- 翻訳は技術レビュー待ちです
- Not unlimited. Custom grant duration is capped at 365 days (default cap 90 days, configurable per scope).
- Free / Solo プランには適用されません。 どちらのプランもユーザーは1人で、形だけの自己承認ではガバナンスにならないためです。利用するには Teams にアップグレードしてください。
関連情報
- シークレットの承認。認証情報の読み取りに対する承認
- マルチユーザーキー。共有 API キーの ID
- SDK:
request_approval+wait。SDK の API - 承認の設定とカスケード。スコープごとのオン/オフのトグル
- E1701 承認のタイムアウト
- E1707 ID が必要
- E1500 スコープで承認が無効