Używaj hooków jako deterministycznych guardraili
ENHooki agentów to deterministyczne skrypty uruchamiane przez Claude Code, Codexa i Cursora w stałych punktach cyklu życia niezależnie od decyzji modelu. Programiści oraz tech leadzi układają cztery warstwy hooków — ochronę ścieżek, strażnika komend, lint po edycji i bramkę zakończenia — aby egzekwować mechaniczne niezmienniki, o których model zapomina w długim kontekście.
Twój AGENTS.md zabrania edycji src/generated/ i nakazuje uruchomienie testów przed zakończeniem pracy. Przez tydzień agent stosuje się do obu zasad, aż podczas długiego refaktoringu edytuje wygenerowanego klienta, melduje „gotowe” i zostawia w diffie nieprzechodzący test oraz wpisany na sztywno klucz API. Instrukcje w kontekście doradzają; hooki wykonują się zawsze.
Które kontrole należą do hooka?
Dział zatytułowany „Które kontrole należą do hooka?”Hook zwraca koszt utrzymania wtedy, gdy reguła jest mechaniczna, szybka do sprawdzenia i kosztowna w razie pominięcia. Umieszczaj każde zabezpieczenie przy najwcześniejszym zdarzeniu zdolnym zatrzymać albo naprawić błąd i zawsze dubluj je w CI:
| Ryzyko | Zdarzenie cyklu życia | Zadanie hooka | Niezależne zabezpieczenie |
|---|---|---|---|
| Edycja plików generowanych, vendorowanych lub wyroczni testów | PreToolUse (zapis plików) | Zablokuj zapis i wskaż źródło do edycji | Reguły deny w uprawnieniach + CODEOWNERS |
| Uruchomienie destrukcyjnej lub produkcyjnej komendy | PreToolUse (powłoka) | Zablokuj i przekaż komendę do wykonania człowiekowi | Sandbox OS, brak poświadczeń produkcyjnych, deploy z CI |
| Złamanie formatowania lub reguł lintera | PostToolUse (zapis plików) | Sformatuj po cichu (fail open), zwróć błędy lintera agentowi | Wymagana bramka lint w CI |
| Pozostawienie poświadczeń w drzewie roboczym | Stop | Bezwarunkowo blokuj zakończenie do usunięcia sekretu | Git pre-commit + skanowanie sekretów w CI |
| Zgłoszenie „gotowe” mimo czerwonych typów lub testów | Stop | Uruchom zawężone kontrole raz; blokuj przy błędzie i przekaż sterowanie przez stop_hook_active | Wymagany zestaw kontroli CI |
Oddzielaj naprawę od bezpieczeństwa. Awaria formatera powinna przepuszczać pracę (fail open), bo CI wyłapie styl później. Awaria strażnika ścieżek lub skanera sekretów musi blokować (fail closed), bo pominięta blokada może zniszczyć dane albo ujawnić klucz.
Kontrakt kodu wyjścia i domyślny tryb fail-open
Dział zatytułowany „Kontrakt kodu wyjścia i domyślny tryb fail-open”W hookach Claude Code i Codexa obowiązuje prosty kontrakt: kod 0 pozwala na kontynuację, natomiast kod 2 blokuje akcję (lub przedłuża turę na zdarzeniu Stop) i przekazuje stderr do modelu jako informację zwrotną. Kluczowy szczegół: zwykły błąd (exit 1), brak skryptu, brak narzędzia jq albo timeout działają w CLI w trybie fail-open, więc chroniona operacja przechodzi bez blokady.
Każdy hook bezpieczeństwa musi samodzielnie wyłapywać wykrywalne błędy i kończyć się kodem 2. Ponieważ timeout nadal przepuszcza akcję, twardą granicę utrzymuj zawsze w uprawnieniach i sandboksach.
Zbuduj cztery warstwowe skrypty hooków
Dział zatytułowany „Zbuduj cztery warstwowe skrypty hooków”Trzymaj logikę hooków w krótkich, wykonywalnych skryptach zacommitowanych w repozytorium (chmod +x), aby każdy programista i każda sesja uruchamiały te same kontrole.
-
Chroń ścieżki przed edycją (
PreToolUse). Odczytaj docelową ścieżkę z wejściowego JSON-a i odrzuć zapis do plików generowanych, vendorowanych, sekretów lub zablokowanych testów. Normalizuj separatory i zamykaj się kodem2przy brakujqlubfile_path:.claude/hooks/protect-paths.sh #!/usr/bin/env bashset -uo pipefailblock() { printf 'protect-paths: %s\n' "$1" >&2; exit 2; }command -v jq >/dev/null 2>&1 || block "jq missing; cannot verify file path."path=$(jq -er '.tool_input.file_path // empty' 2>/dev/null) || block "missing file_path."path=${path//\\//}case "$path" in*/src/generated/*|*/vendor/*|*/.env|*/.env.*)block "$path is protected. Edit the source schema or ask a human." ;;esacexit 0 -
Blokuj komendy produkcyjne i destrukcyjne (
PreToolUse). Sprawdzaj wywołania powłoki pod kątem ryzykownych wzorców (terraform apply, force push, zdalne mutacje--remote) i blokuj kodem2. Traktuj dopasowanie tekstu komendy wyłącznie jako łapacz pomyłek:sh -club zapisany skrypt ominą wyrażenie regularne, więc realną ochroną pozostaje brak poświadczeń produkcyjnych. -
Formatuj i lintuj edycje (
PostToolUse). Uruchom formatter w trybie fail-open (|| true) na zmienionym pliku, a potem szybki linter. Gdy linter zgłosi błąd, wyślij skrócony wynik nastderri zakończ kodem2, aby agent naprawił go od razu, gdy zmiana jest w pamięci roboczej. -
Wymuś bramkę stop z ochroną przed pętlą (
Stop). Skanuj niezacommitowane zmiany i nowe pliki pod kątem sekretów bezwarunkowo. Dla typów i zawężonych testów sprawdzajstop_hook_active, aby nienaprawialny błąd środowiska zablokował zakończenie raz i oddał sprawę człowiekowi zamiast kręcić się w kółko:.agent-hooks/stop-gate.sh #!/usr/bin/env bashset -uo pipefailblock() { printf 'stop-gate: %s\n' "$1" >&2; exit 2; }again=$(jq -r '.stop_hook_active // false' 2>/dev/null || echo false)root=$(git rev-parse --show-toplevel 2>/dev/null) || block "not inside a Git repo."cd "$root" || block "cannot enter repository root."command -v gitleaks >/dev/null 2>&1 || block "gitleaks missing; cannot scan diff."if ! { git diff HEAD 2>/dev/null; git ls-files -z --others --exclude-standard | xargs -0 -r cat; } \| gitleaks stdin --redact --no-banner >/dev/null 2>&1; thenblock "Secret detected in uncommitted changes. Remove it and use environment variables."fi[ "$again" = "true" ] && exit 0if ! out=$(pnpm check:changed 2>&1); thenblock "Checks failed. Fix the root cause:\n$(printf '%s' "$out" | tail -n 40)"fiexit 0Ponieważ bramka stop skanuje niezacommitowane zmiany, zawsze łącz ją z hookiem Git
pre-commitskanującym sekrety, gdy agent ma prawo tworzyć commity.
Podepnij hooki w Claude Code, Codexie i Cursorze
Dział zatytułowany „Podepnij hooki w Claude Code, Codexie i Cursorze”Współdziel skrypty tam, gdzie kształt danych wejściowych jest identyczny, a rejestrację zapisuj według schematu każdego narzędzia:
Rejestruj hooki projektu w .claude/settings.json ze zmienną ${CLAUDE_PROJECT_DIR}, aby ścieżki działały z każdego podkatalogu. Obowiązkowe kontrole firmowe wdrażaj jako managed hooks przez politykę zarządzaną.
{ "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-paths.sh", "timeout": 10 }] }, { "matcher": "Bash", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.agent-hooks/guard-commands.sh", "timeout": 10 }] } ], "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/post-edit-lint.sh", "timeout": 60 }] } ], "Stop": [ { "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.agent-hooks/stop-gate.sh", "timeout": 300 }] } ] }}Aktywne hooki i logi wywołań sprawdzisz narzędziami diagnostycznymi Claude Code; szczegóły podają dokumentacja hooków Claude Code i automatyzacja hooków w Claude Code.
Rejestruj hooki projektu w .codex/hooks.json lub config.toml. Zwróć uwagę na dwie istotne różnice względem Claude Code:
- Jawne zaufanie: hooki projektu pozostają nieaktywne, dopóki nie przejrzysz ich i nie oznaczysz jako zaufanych (i wymagają ponownego zaufania po zmianach), chyba że wdrożono je jako hooki zarządzane.
- Edycje oparte na patchach: Codex modyfikuje pliki przez payload patcha zamiast pojedynczego pola
file_path, więc dopasuj strażnika ścieżek do nagłówków patcha, a lint uruchamiaj w bramceStop.
Bieżące schematy zdarzeń i zaufania sprawdzaj w dokumentacji OpenAI Codex.
Cursor obsługuje hooki JSON przez stdio, które obserwują, blokują lub modyfikują akcje agenta obok reguł projektu i bramek CI. Wszystkie krytyczne niezmienniki (skanowanie sekretów, sprawdzenie chronionych ścieżek, typy, lint, testy) utrzymuj jako wymagane checki CI i hooki Git pre-commit, a hooki Cursora dopinaj według bieżącego schematu w dokumentacji Cursora.
Zweryfikuj każdy hook przypadkami testowymi zamiast zaufania
Dział zatytułowany „Zweryfikuj każdy hook przypadkami testowymi zamiast zaufania”Nieprzetestowany hook to pobożne życzenie. Zacommituj skrypt testowy uruchamiany w CI, który podaje próbki JSON wprost na wejście każdego blokującego hooka (allow, deny, near-miss allow i malformed input z kodem 2):
#!/usr/bin/env bashset -euo pipefailcheck() { local want=$1 script=$2 payload=$3 got=0 printf '%s' "$payload" | "$script" >/dev/null 2>&1 || got=$? [ "$got" -eq "$want" ] || { echo "FAIL $script: wanted $want, got $got"; exit 1; }}check 0 .claude/hooks/protect-paths.sh '{"tool_input":{"file_path":"/repo/src/app.ts"}}'check 2 .claude/hooks/protect-paths.sh '{"tool_input":{"file_path":"/repo/src/generated/api.ts"}}'check 0 .claude/hooks/protect-paths.sh '{"tool_input":{"file_path":"/repo/src/generator/api.ts"}}'check 2 .claude/hooks/protect-paths.sh 'malformed-json'Połącz testy fixture z trzema dodatkowymi sprawdzeniami:
@wondelai/harness-audit: uruchomnpx @wondelai/harness-audit --lang pl, aby zweryfikować Stanowisko 2 (Harness) — obecność hooków i zabezpieczeniastop_hook_active(przewodnik po harness-audit).- Test żywej rejestracji: na gałęzi roboczej potwierdź, że CLI wywołuje zarejestrowany hook i zwraca twój komunikat.
- Przegląd
CODEOWNERS: chroń skrypty i pliki ustawień przeglądem właścicieli kodu, bo hooki działają z uprawnieniami programisty i runnera CI.
Kiedy hooki agentów zawodzą po cichu
Dział zatytułowany „Kiedy hooki agentów zawodzą po cichu”- Strażnik po cichu przestał działać. Literówka w ścieżce, brak
chmod +x, brakjqlub przypadkoweexit 1sprawiają, że CLI przepuszcza akcję. Uruchamiaj testy hooków w CI i pilnuj, by każdy wykrywalny błąd zwracał kod2. - Bramka stop zamyka agenta w pętli. Testy padają z powodu niedostępnej usługi, której agent nie naprawi. Sprawdzaj
stop_hook_active, aby testy i lint blokowały raz, a bezwarunkowo blokuj wyłącznie sekrety. - Awaria formatera paraliżuje każdą edycję. Nigdy nie kończ kodem
2, gdy wywraca się formatter; kroki naprawcze działają w trybie fail-open, a kod2rezerwuj dla realnych błędów lintera i polityk. - Hook wypisuje wykryty sekret. Logowanie znalezionych wartości lub pełnych komend trafia do transkryptów i logów CI. Wypisuj wyłącznie nazwę reguły i pliku, używaj
--redactw skanerach sekretów i rotuj każde ujawnione poświadczenie. - Niezaufany PR uruchamia hooki atakującego w CI. Wczytanie
.claude/settings.jsonalbo.codex/hooks.jsonz forka w uprzywilejowanym zadaniu CI oddaje sekrety skryptom kontrybutora. Izoluj niezaufany kod i wyłączaj projektowe ustawienia oraz hooki w jobach posiadających sekrety (tożsamość agentów i sekrety).
Oficjalna dokumentacja i kolejne kroki
Dział zatytułowany „Oficjalna dokumentacja i kolejne kroki”Aktualne nazwy zdarzeń, schematy payloadów JSON i reguły hooków zarządzanych sprawdzaj w dokumentacji dostawców: Claude Code, OpenAI Codex i Cursor.
Czy ten artykuł Ci pomógł?
Jedno kliknięcie, bez logowania.
Co z tym zrobisz?
Jak się czytało?
Co przeszkadzało? Możesz zaznaczyć kilka
Twoja rola?
Dzięki. Czytam każdą odpowiedź. Michał Jaskólski
Pomógł Ci ten artykuł?
Każde to jedno kliknięcie. Zamknij, kiedy chcesz.
bez logowania
Najczęstsze pytania
Jakie są cztery warstwy deterministycznych hooków agenta?
Deterministyczny guardrail łączy cztery warstwy w pętli agenta: blokadę edycji chronionych ścieżek, blokadę ryzykownych komend produkcyjnych, formatowanie i lint edycji oraz odmowę zakończenia tury przy sekretach lub nieprzechodzących kontrolach.
Dlaczego hook Stop musi sprawdzać pole stop_hook_active?
Gdy hook Stop blokuje zakończenie, agent kontynuuje pracę i ponownie wyzwala hook. Sprawdzenie stop_hook_active zapobiega nieskończonej pętli, gdy testy padają z przyczyny poza kontrolą agenta.