Przejdź do głównej treści
Niektóre wywołania narzędzi są zbyt brzemienne w skutki, by zezwalać na nie ślepo, i zbyt użyteczne, by zakazać ich wprost — zapis do produkcyjnej bazy danych, przelew, *.delete na prawdziwych danych. Dla tych chcesz człowieka w pętli: wstrzymaj wywołanie, pozwól człowiekowi spojrzeć, potem przejdź dalej tylko na tak. To dokładnie to, co robi werdykt pending_approval. Ta strona omawia przepływ zatwierdzania akcji agenta z człowiekiem w pętli od początku do końca: jak ujawnia się wstrzymane wywołanie, jak recenzent rozstrzyga je z konsoli lub webhooka oraz jak agent ponownie wysyła zatwierdzone wywołanie. Gdzie werdykt siedzi w gramatyce reguł, zobacz Reguły Firewall; dla modelu polityki wokół niego zobacz Przegląd Firewall.

​
1. Jak wygląda wstrzymane wywołanie

Gdy reguła rozwiązuje się do pending_approval, silnik kolejkuje rekord zatwierdzenia, a wywołanie nie dociera do narzędzia. Relay zwraca HTTP 400 z error.code firewall_approval_pending; id zatwierdzenia, na którym agent będzie odpytywał, jest niesione w czytelnym dla człowieka 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"
  }
}
Ustrukturyzowane error.metadata (gdy obecne) niesie szczegół powodu werdyktu — reason_code, factors, risk_score — nie id zatwierdzenia. Wyparsuj id z komunikatu lub pobierz je z pomocnika SDK poniżej. Wstrzymanie jest natychmiastowe — nie ma inline długiego odpytywania blokującego twoje żądanie. Agent dostaje id z powrotem, wywołanie jest zaparkowane po stronie serwera w stanie pending, a rozstrzygnięcie odbywa się poza pasmem.
Wstrzymane wywołanie jest rejestrowane jako zdarzenie firewalla z werdyktem pending_approval, więc jest filtrowalne w logu zdarzeń tuż obok zdarzeń deny — zawsze widzisz, co było wstrzymane i, przez rekord zatwierdzenia, co zostało rozstrzygnięte.

​
2. Jeden konkretny przykład

Napisz regułę, która wstrzymuje dla człowieka każdy zapis do produkcyjnego połączenia: 
{
  "label": "hold prod db writes",
  "tool_name_glob": "db.write",
  "verdict": "pending_approval",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.connection\",\"op\":\"eq\",\"value\":\"prod\"}]}"
}
Teraz cykl życia:
1

Agent wywołuje narzędzie

Agent wystawia db.write wobec prod. Reguła dopasowuje, silnik wstrzymuje wywołanie, a relay zwraca 400 firewall_approval_pending z approval_id.
2

Człowiek (lub twój system) recenzuje

Recenzent rozstrzyga zatwierdzenie — w konsoli lub przez podpisany webhook callback (zobacz §3).
3

Agent odpytuje, aż rozstrzygnięte

Agent odpytuje id zatwierdzenia, aż jego stan nie jest już pending (zobacz §4).
4

Agent ponownie wysyła z nagłówkiem zatwierdzenia

Na approved agent ponownie wystawia dokładnie to samo wywołanie raz, niosąc jednorazowy nagłówek X-OrcaRouter-Firewall-Approval. Silnik zgłasza zatwierdzenie i przepuszcza to jedno wywołanie.

​
3. Rozstrzyganie zatwierdzenia

Są dwa sposoby, by zamienić zatwierdzenie pending w approved lub rejected. Oba dzielą gwarancję wygrywa-pierwsza-decyzja — pierwsze rozstrzygnięcie, które wyląduje, jest stosowane atomowo, a każde późniejsze rozstrzygnięcie (lub duplikat) to idempotentny no-op zwracający 200.
Zakładka Approvals wymienia wstrzymane oczekiwania od najstarszych, każde z nazwą narzędzia i linią „Wstrzymane, ponieważ…” nazywającą politykę i klauzulę reguły, która odpaliła. (Surowe argumenty wywołania nie są przechowywane na rekordzie zatwierdzenia — tylko nazwa narzędzia, proweniencja i hash argumentów — więc recenzent decyduje z narzędzia plus dopasowanej klauzuli.) Recenzent rozstrzyga jedno przez:
PATCH /api/workspace/firewall/approvals/:id

{ "decision": "approved", "reason": "verified change ticket #4821" }
decision musi być approved lub rejected. Ta trasa to UserAuth (sesja konsoli recenzenta) i bramkowana do Developer+ — tożsamość twojego recenzenta jest autoryzacją, więc nie ma w grze współdzielonego sekretu. Rozstrzygnięcia są zapisywane do logu audytu przestrzeni roboczej.
Aby okablować zatwierdzenia w zewnętrzny system (zatwierdzenie Slack, przepływ ticketowy), skonfiguruj sekret webhooka zatwierdzeń dla przestrzeni roboczej, potem wyślij POST z decyzją z powrotem:
POST /api/v1/firewall/approvals/:id/callback

{ "decision": "approved", "reason": "auto-approved by change-control bot" }
Callback jest uwierzytelniany przez HMAC-SHA256: ustaw nagłówek X-Orca-Signature: sha256=<hex> na HMAC z <approval_id>\n<raw_body> kluczowany sekretem webhooka zatwierdzeń twojej przestrzeni roboczej. Id jest częścią podpisanego materiału, więc przechwycony podpis nie może być odtworzony wobec innego zatwierdzenia. Bez skonfigurowanego sekretu rozstrzygnięcie napędzane callbackiem jest odrzucane — rozstrzygnij przez PATCH konsoli zamiast tego.
Skonfigurowanie ścieżki odrzucenia webhooka zatwierdzeń to bezpieczna wartość domyślna dla nienadzorowanych uruchomień: jeśli żaden człowiek nie rozstrzygnie wstrzymania, wywołanie po prostu pozostaje zaparkowane, a agent dalej odpytuje. Wstrzymane wywołanie nigdy po cichu nie staje się allow.

​
4. Odpytuj, potem wyślij ponownie

Strona agenta to pętla odpytywania, po której następuje jedno ponowne wysłanie. Odpytuj stan zatwierdzenia tokenem w zakresie firewall-gateway: 
GET /api/v1/firewall/approvals/:id
Ta trasa wymaga tokenu z zakresem firewall-gateway (ten sam dedykowany klucz gateway używany dla /evaluate i bramy MCP); zwykły klucz relay dostaje 403. Zwraca dokument zatwierdzenia — czekaj, aż state to approved lub rejected, a nie pending. Id z innej przestrzeni roboczej lub nieznane zwraca 404, nigdy nie ujawniając innemu najemcy, że istnieje. Wyślij ponownie, gdy stan to approved: ponownie wystaw to samo wywołanie narzędzia, niosąc id zatwierdzenia w jednorazowym nagłówku: 
X-OrcaRouter-Firewall-Approval: 507f1f77bcf86cd799439011
Silnik atomowo zgłasza zatwierdzenie — jednorazowe. Pierwsze ponowne wysłanie niosące je jest przepuszczane ten jeden raz; odtworzenie tego samego nagłówka zastaje zatwierdzenie już skonsumowane i jest wstrzymane ponownie, nie dozwolone. Zatwierdzenie rejected nigdy nie jest zgłaszalne, więc agent powinien traktować odrzucenie jako terminalne deny i wybrać inną ścieżkę.
Pomocnik HITL SDK MCP OrcaRouter uruchamia tę pętlę odpytaj-potem-wyślij- ponownie za ciebie: gdy evaluate zwraca pending_approval, odpytuje GET /api/v1/firewall/approvals/:id i ponownie wysyła z nagłówkiem zatwierdzenia po zatwierdzeniu — ty tylko piszesz regułę i obsadzasz recenzenta.

​
5. Stany i role w skrócie

StanZnaczenieAkcja agenta
pendingWstrzymane, oczekuje na decyzjęOdpytuj dalej
approvedRecenzent powiedział takWyślij ponownie raz z nagłówkiem
rejectedRecenzent powiedział nieTraktuj jako deny
AkcjaTrasaAuth · rola
Lista kolejkiGET /api/workspace/firewall/approvalsUserAuth · Developer+
RozstrzygnijPATCH /api/workspace/firewall/approvals/:idUserAuth · Developer+
Webhook callbackPOST /api/v1/firewall/approvals/:id/callbackPodpisany HMAC
Odpytaj stanGET /api/v1/firewall/approvals/:idToken gateway

​
6. Gdzie pasują zatwierdzenia

Werdykt pending_approval to jeden z werdyktów firewalla — komponuje się ze wszystkim innym w polityce. Dwie interakcje warte poznania:
  • Kwarantanna skilla eskaluje do wstrzymania. Jeśli wstrzymane wywołanie narzędzia jest własnością skilla poddanego kwarantannie, wszystko poniżej deny jest eskalowane do pending_approval automatycznie — kwarantanna i zatwierdzenia to ta sama brama przeglądu z dwóch kierunków.
  • Tryb cienia ją spłaszcza. W trybie cienia werdykt pending_approval jest degradowany do audit i logowany jako [shadow] would …, więc możesz zmierzyć, jak często wstrzymanie by odpaliło, zanim zacznie bramkować prawdziwy ruch.
To właściwa kontrola dla niebezpiecznych wywołań narzędzi i nadmiernej sprawczości — przypadków, gdzie werdykt „zapytaj człowieka” bije zarówno allow, jak i deny.

​
Dokąd dalej

Werdykty

Wszystkie sześć werdyktów firewalla i werdykt domyślny.

Klucze gateway

Wybij token firewall-gateway używany do odpytywania zatwierdzeń.

Tryb cienia

Zmierz wstrzymanie, zanim zacznie bramkować prawdziwy ruch.

Referencja reguł

Napisz regułę, która produkuje werdykt pending_approval.