Zum Hauptinhalt springen
Wenn eine Firewall-Regel das pending_approval-Verdikt zurückgibt, wird der Tool-Call des Agenten zurückgehalten statt dispatcht — er wartet nun auf einen Menschen. Diese Seite ist für den Prüfer: wie man Agent-Tool-Call-Holds aus der Konsole genehmigt (oder ablehnt), was die Queue Ihnen zeigt und wie OrcaRouter zwei Prüfer davon abhält, auf derselben Entscheidung zu kollidieren. Es ist die Auflösungshälfte von Human-in-the-Loop. Dafür, warum ein Aufruf zurückgehalten wird und wie der zurückgehaltene Agent danach erneut einreicht, siehe Verdikte und die tiefere Freigaben-Referenz. Um aus Ihrem eigenen System statt aus der Konsole aufzulösen, siehe Freigabe-Webhooks.

​
1. Der Held-Call-Lebenszyklus aus Sicht eines Prüfers

Ein zurückgehaltener Aufruf ist eine kurze Out-of-band-Schleife. Ihre Aufgabe ist der mittlere Schritt:
1

Der Aufruf wird zurückgehalten

Eine Regel löst zu pending_approval auf. Das Relay gibt HTTP 400 mit Code firewall_approval_pending und einer Approval-ID zurück; der Aufruf erreicht das Tool nie. Der Agent beginnt, auf dieser ID zu pollen.
2

Sie lösen es auf

Sie öffnen die Approvals-Queue, lesen, warum der Aufruf zurückgehalten wurde, und genehmigen oder lehnen ihn ab — der Fokus dieser Seite.
3

Der Agent fährt fort (oder stoppt)

Bei Genehmigung reicht der Agent den ursprünglichen Aufruf mit einem einmal nutzbaren X-OrcaRouter-Firewall-Approval-Header erneut ein, und das Gateway lässt ihn dieses eine Mal durch. Bei Ablehnung bleibt der Aufruf blockiert.
Einen Hold aufzulösen ist auf Developer+ gegated — dasselbe Gate wie der Firewall-Events-Feed. Niedrigere Rollen können Firewall-Policy, Einstellungen und Discovered Tools lesen, aber nur Developer-und-höher-Rollen können die Approval-Queue auflisten oder einen zurückgehaltenen Tool-Call genehmigen/ablehnen. Siehe Rollen und Scope.

​
2. Die ausstehende Queue auflisten

Der Approvals-Tab liest GET /api/workspace/firewall/approvals. Ohne Filter gibt er die pending-Queue zurück, älteste zuerst — sodass der am-längsten-wartende Aufruf oben sitzt und Sie den Backlog der Reihe nach abarbeiten. 
GET /api/workspace/firewall/approvals?state=pending
state ist der eine Filter, der zählt. Die Werte bilden den Lebenszyklus der Freigabe ab:
stateZurückgegebene Freigaben
pending (Default)Zurückgehalten, auf eine Entscheidung wartend — Ihre Arbeits-Queue.
approvedBereits durchgelassen.
rejectedBereits blockiert.
Dies ist eine Konsolen-Route auf Ihrer Session — konfigurieren und prüfen Sie sie vom Dashboard aus, nicht mit einem sk-orca-…-Relay-Key. Relay-Keys sind für /v1/*-Modellaufrufe; das Firewall-Management läuft unter Ihrem Konsolen-Login.

​
3. Lesen, warum der Aufruf zurückgehalten wurde

Jede Zeile trägt die Entscheidungs-Inputs, die ein Prüfer braucht — den Tool-Namen (tool_name), einen Argument-Fingerabdruck (args_hash, das SHA-256 der kanonisierten Aufruf-Argumente — die rohen Argument-Werte werden nicht in der Freigabe gespeichert), die Request-ID und eine Klartext-Provenienzzeile, die die Policy, die Regel und die Klausel benennt, die feuerte:
Die benannte Policy, zu der die gematchte Regel gehört, workspace-bezogen aufgelöst, sodass eine veraltete ID nie den Policy-Namen eines anderen Tenants zutage fördern kann.
Das Label der Regel und ein einzeiliger „Warum”-Deskriptor — z. B. command contains rm -rf oder tool matches "http_fetch" für eine reine Glob-Regel. Das rendert die „Held because…”-Zeile in der Queue.
true, wenn die gematchte Regel am oder nach der Erstellung dieser Freigabe bearbeitet wurde. Das Live-Label und die Klausel werden dann unterdrückt (sie spiegeln möglicherweise nicht mehr, was den Aufruf tatsächlich zurückhielt), und die Queue zeigt stattdessen einen „rule since changed”-Hinweis statt veralteter Provenienz. Der Tool-Name und die Argumente — die echten Entscheidungs-Inputs — werden immer gezeigt.
rule_changed ist ein bewusstes Ehrlichkeitssignal, kein Fehler. Wenn jemand die Firewall-Regel bearbeitet, während ein Aufruf in der Queue sitzt, würde OrcaRouter lieber einen möglicherweise-falschen Grund verbergen, als Ihnen Provenienz zu zeigen, die nicht mehr passt. Entscheiden Sie in diesem Fall anhand des Tool-Namens und des Policy-Namens (weiterhin gezeigt).

​
4. Genehmigen oder ablehnen

Das Auflösen sendet PATCH /api/workspace/firewall/approvals/:id mit einer decision von approved oder rejected und einem optionalen reason. Die Konsole tut dies für Sie, wenn Sie den Button klicken; die Form ist: 
PATCH /api/workspace/firewall/approvals/507f1f77bcf86cd799439011
Content-Type: application/json

{ "decision": "approved", "reason": "verified target host with the on-call" }
  • approved → der zurückgehaltene Aufruf darf fortfahren. Das nächste erneute Einreichen des Agenten, das den einmal nutzbaren Approval-Header trägt, wird einmal durchgelassen.
  • rejected → der Aufruf bleibt blockiert. Der Agent sieht die Ablehnung und kann einen anderen Pfad wählen, den Nutzer fragen oder anhalten.
decision wird gegen die geschlossene {approved, rejected}-Menge validiert — alles andere wird abgelehnt. Der reason wird mit der Entscheidung aufgezeichnet und in das Firewall-Audit-Log geschrieben, neben dem Akteur, dem Tool-Namen und der Request-ID.
Jede Auflösung schreibt eine Workspace-Audit-Zeile, die benennt, wer entschied, die Entscheidung und den Grund. Konsolen-Auflösungen zeichnen den menschlichen Akteur auf; Webhook-Auflösungen zeichnen einen System-Akteur auf. Auflösungs-Provenienz wird nie stillschweigend verworfen.

​
5. First-Writer-wins: kein Doppel-Auflösen

Eine ausstehende Freigabe kann verrennt werden — zwei Prüfer in der Konsole, oder ein Konsolen-Klick und ein Webhook-Callback, die zusammen eintreffen. OrcaRouter löst dies mit einer einzelnen First-Writer-wins-Regel:
  • Die Entscheidung ist ein atomares bedingtes Update, das nur feuert, solange die Freigabe noch pending ist. Der erste Schreiber gewinnt und wendet die Entscheidung an.
  • Jeder spätere Schreiber beobachtet „bereits aufgelöst” und wird als idempotenter No-op behandelt — er bekommt HTTP 200 mit dem bereits-aufgelösten Dokument, keinen Fehler.
Die Antwort sagt Ihnen, auf welcher Seite Sie waren: 
{
  "resolved": false,
  "already_resolved": true,
  "approval": { "state": "approved", "decision": "approved", "...": "..." }
}
resolved: true bedeutet, dass Ihr Aufruf die Entscheidung anwandte; already_resolved: true bedeutet, dass jemand (oder ein Webhook) zuerst dort war und Sie sein Ergebnis sehen. So oder so versöhnt sich die Queue zu einem konsistenten Zustand.
Weil die Auflösung idempotent ist, kann ein wackeliges Netzwerk oder ein Doppelklick einen Hold nicht beschädigen oder eine Entscheidung umkehren. Das erste Genehmigen/Ablehnen ist das einzige, das zählt; alles danach liest nur das Ergebnis zurück.

​
6. Ein konkreter Durchgang durch die Queue

Ein Workspace mit balancierter Autonomie hält den shell.exec-Aufruf eines Agenten zurück, weil eine Regel command contains rm -rf gematcht hat. Als Prüfer:
  1. Öffnen Sie Approvals — das zurückgehaltene shell.exec sitzt oben auf der ältesten-zuerst-pending-Liste.
  2. Lesen Sie die Zeile: Tool shell.exec, der args_hash-Fingerabdruck, Request-ID und die „Held because… command contains rm -rf”-Zeile (gerendert aus der Klausel der gematchten Regel). Kein rule_changed-Flag, also ist die Provenienz aktuell.
  3. Das Ziel ist ein Scratch-Verzeichnis, also genehmigen Sie mit einem Grund.
  4. Ihr PATCH gibt resolved: true zurück; das nächste Polling des Agenten sieht approved, reicht mit seinem einmal nutzbaren Header erneut ein, und der Befehl läuft genau einmal.
Hätte ein Teamkollege ihn eine Sekunde früher genehmigt, hätte Ihr Klick already_resolved: true mit dessen Entscheidung zurückgegeben — kein Schaden, kein Doppellauf.

​
Wohin als Nächstes

Freigaben-Referenz

Die vollständige HITL-Schleife: zurückhalten, pollen, erneut einreichen und der einmal nutzbare Header.

Freigabe-Webhooks

Holds aus Ihrem eigenen System mit einem HMAC-signierten Callback auflösen.

Verdikte

Wo pending_approval unter den sechs Firewall-Verdikten sitzt.

Events-Log

Das Downstream-Ergebnis eines aufgelösten Aufrufs im Feed bestätigen.
Für die Risiken, die diese Holds abfangen sollen, siehe Gefährliche Tool-Calls und Übermäßige Handlungsmacht.