Przejdź do głównej zawartości

Hooki 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.

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:

RyzykoZdarzenie cyklu życiaZadanie hookaNiezależne zabezpieczenie
Edycja plików generowanych, vendorowanych lub wyroczni testówPreToolUse (zapis plików)Zablokuj zapis i wskaż źródło do edycjiReguły deny w uprawnieniach + CODEOWNERS
Uruchomienie destrukcyjnej lub produkcyjnej komendyPreToolUse (powłoka)Zablokuj i przekaż komendę do wykonania człowiekowiSandbox OS, brak poświadczeń produkcyjnych, deploy z CI
Złamanie formatowania lub reguł linteraPostToolUse (zapis plików)Sformatuj po cichu (fail open), zwróć błędy lintera agentowiWymagana bramka lint w CI
Pozostawienie poświadczeń w drzewie roboczymStopBezwarunkowo blokuj zakończenie do usunięcia sekretuGit pre-commit + skanowanie sekretów w CI
Zgłoszenie „gotowe” mimo czerwonych typów lub testówStopUruchom zawężone kontrole raz; blokuj przy błędzie i przekaż sterowanie przez stop_hook_activeWymagany 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.

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.

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.

  1. 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ę kodem 2 przy braku jq lub file_path:

    .claude/hooks/protect-paths.sh
    #!/usr/bin/env bash
    set -uo pipefail
    block() { 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." ;;
    esac
    exit 0
  2. 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 kodem 2. Traktuj dopasowanie tekstu komendy wyłącznie jako łapacz pomyłek: sh -c lub zapisany skrypt ominą wyrażenie regularne, więc realną ochroną pozostaje brak poświadczeń produkcyjnych.

  3. 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 na stderr i zakończ kodem 2, aby agent naprawił go od razu, gdy zmiana jest w pamięci roboczej.

  4. 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 sprawdzaj stop_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 bash
    set -uo pipefail
    block() { 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; then
    block "Secret detected in uncommitted changes. Remove it and use environment variables."
    fi
    [ "$again" = "true" ] && exit 0
    if ! out=$(pnpm check:changed 2>&1); then
    block "Checks failed. Fix the root cause:\n$(printf '%s' "$out" | tail -n 40)"
    fi
    exit 0

    Ponieważ bramka stop skanuje niezacommitowane zmiany, zawsze łącz ją z hookiem Git pre-commit skanującym sekrety, gdy agent ma prawo tworzyć commity.

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ą.

.claude/settings.json
{
"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.

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):

scripts/test-hooks.sh
#!/usr/bin/env bash
set -euo pipefail
check() {
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: uruchom npx @wondelai/harness-audit --lang pl, aby zweryfikować Stanowisko 2 (Harness) — obecność hooków i zabezpieczenia stop_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.
  • Strażnik po cichu przestał działać. Literówka w ścieżce, brak chmod +x, brak jq lub przypadkowe exit 1 sprawiają, że CLI przepuszcza akcję. Uruchamiaj testy hooków w CI i pilnuj, by każdy wykrywalny błąd zwracał kod 2.
  • 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 kod 2 rezerwuj 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 --redact w skanerach sekretów i rotuj każde ujawnione poświadczenie.
  • Niezaufany PR uruchamia hooki atakującego w CI. Wczytanie .claude/settings.json albo .codex/hooks.json z 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).

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.

wcale bardzo

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.