# Używaj hooków jako deterministycznych guardraili

URL: https://developertoolkit.ai/pl/workflows/harness/agent-hooks/
Description: Warstwowe hooki w Claude Code, Codexie i Cursorze: chroń ścieżki, blokuj ryzykowne komendy, lintuj edycje i wymuszaj bramkę stop z ochroną przed pętlą.

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.

## 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

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](/pl/workflows/harness/permissions-and-sandboxing/).

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

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

   ```bash title=".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:

   ```bash title=".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.

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

**Claude Code**

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ą](/pl/org/managed-policy/).

```json title=".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](https://code.claude.com/docs) i [automatyzacja hooków w Claude Code](/pl/claude-code/automate/hooks-automation/).

**Codex**

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 bramce `Stop`.

Bieżące schematy zdarzeń i zaufania sprawdzaj w [dokumentacji OpenAI Codex](https://developers.openai.com/codex).

**Cursor**

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](https://cursor.com/docs).

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

```bash title="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](/pl/workflows/harness/harness-audit-guide/)).
- **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.

**Prompt do skopiowania: zaprojektuj hook fail-closed z testami**

```text
Read AGENTS.md and pick the highest-risk mechanical rule still enforced only in prose.
Design one fail-closed bash hook (event, matcher, JSON field) exiting 2 with an
actionable stderr message on policy violations and parse/dependency errors. Add
allow, deny, near-miss, and malformed-input fixtures. Do not register it yet.
```

## Kiedy hooki agentów zawodzą po cichu

- **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](/pl/org/agent-identity-and-secrets/)).

## 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](https://code.claude.com/docs), [OpenAI Codex](https://developers.openai.com/codex) i [Cursor](https://cursor.com/docs).

- [Uprawnienia i sandboksy](/pl/workflows/harness/permissions-and-sandboxing/) — Zbuduj granice sandboksa OS i kontroli sieci, które hooki jedynie uzupełniają.
- [Ochrona wyroczni](/pl/workflows/test/protect-the-oracle/) — Zablokuj testy akceptacyjne i workflowy CI przed osłabianiem przez agentów.
- [Polityka zarządzana](/pl/org/managed-policy/) — Wdrażaj nienadpisywalne hooki i zabezpieczenia w całej organizacji.
- [Automatyzacja hooków Claude Code](/pl/claude-code/automate/hooks-automation/) — Poznaj szczegółowe wzorce zdarzeń cyklu życia w Claude Code.
