Hook blokuje moje działania - jak zdiagnozować

Claude Code

Hook blokuje moje działania - jak zdiagnozować

W skrócie

Hooki w Claude Code, oficjalnym narzędziu CLI od Anthropic do programowania z AI, to komendy uruchamiane automatycznie w konkretnych momentach cyklu pracy - na przykład tuż przed wykonaniem narzędzia. Są świetne do wymuszania zasad (blokada niebezpiecznych poleceń, formatowanie po zapisie), ale gdy hook zacznie blokować coś, czego nie chciałeś, potrafi solidnie namieszać: agent raportuje, że akcja została zablokowana, a przyczyna nie jest oczywista. Pokażemy, jak namierzyć winowajcę i go poprawić.

Jak to wygląda w praktyce

Prosisz agenta o edycję pliku albo uruchomienie komendy, a on odpowiada, że operacja została zablokowana - często z krótkim komunikatem, który sam hook wypisał jako powód. Bywa gorzej: hook blokuje po cichu, a Ty widzisz tylko, że narzędzie "nie przeszło", bez sensownego wyjaśnienia. Charakterystyczne jest to, że nadanie uprawnień nie pomaga - akcja dalej nie przechodzi. To znak, że w grę wchodzi nie system uprawnień, lecz hook, który świadomie ją odrzuca.

Dlaczego Claude Code tak działa

Hook PreToolUse uruchamia się przed wykonaniem narzędzia i może zadecydować o jego losie. Jeżeli hook zakończy się kodem wyjścia 2, Claude Code blokuje wywołanie narzędzia - i to jest twarda blokada: nawet jawne zezwolenie w wyniku hooka jej nie nadpisze, bo kod 2 zawsze blokuje. Powód, który zobaczysz, pochodzi albo z decyzji zwróconej przez hook w formacie JSON, albo - gdy jej nie ma - ze standardowego wyjścia błędów hooka. Hooki definiuje się w plikach ustawień na kilku poziomach: ~/.claude/settings.json (wszystkie projekty), .claude/settings.json (projekt, wersjonowany) i .claude/settings.local.json (projekt, prywatny), a dodatkowo mogą je wnosić wtyczki. Dlatego blokujący hook potrafi pochodzić z miejsca, o którym zapomniałeś, na przykład ze współdzielonych ustawień projektu.

Jak to rozwiązać krok po kroku

1. Wpisz w Claude Code komendę /hooks. Otworzy się przegląd wszystkich skonfigurowanych hooków pogrupowanych po zdarzeniach, z warunkami dopasowania i - co kluczowe - z informacją, z którego pliku ustawień pochodzi każdy hook.
2. Znajdź hooki podpięte pod PreToolUse i sprawdź ich warunek dopasowania (matcher, np. Bash albo wzorzec komendy). To one mogą blokować, zanim narzędzie w ogóle się uruchomi.
3. Uruchom Claude Code z flagą --debug. W logach debugowania zobaczysz szczegóły wykonania hooków, w tym dlaczego dany hook zablokował akcję i pełne wyjście błędów. To najpewniejszy sposób, żeby wskazać konkretnego winowajcę zamiast zgadywać.
4. Otwórz plik ustawień wskazany przy hooku w /hooks i przeczytaj jego warunek. Bardzo częsta przyczyna to zbyt szeroki matcher - na przykład reguła, która miała łapać tylko rm -rf, a łapie każdą komendę powłoki.
5. Popraw warunek albo logikę hooka: zawęź matcher, dodaj wyjątek dla operacji, których nie chcesz blokować, albo w kodzie hooka zwróć kod wyjścia 0 dla przypadków, które mają przechodzić.
6. Jeśli hook jest cudzy albo pochodzi z wtyczki i chwilowo zawadza, tymczasowo usuń lub zakomentuj jego wpis w odpowiednim pliku ustawień, a przy następnym uruchomieniu potwierdź w /hooks, że już go nie ma na liście.

Jak sprawdzić, że zadziałało

Ponów operację, która wcześniej była blokowana - jeśli teraz przechodzi, hook przestał ją odrzucać. Dla pewności otwórz jeszcze raz /hooks i sprawdź, że poprawiony hook ma zawężony warunek albo że problematyczny wpis zniknął. Jeżeli chcesz mieć twardy dowód, uruchom sesję ponownie z --debug i wykonaj tę samą akcję: w logach zobaczysz, że hook uruchomił się i zakończył kodem 0 (przepuścił), zamiast kodem 2 (zablokował). Pamiętaj przy tym, że blokada niebezpiecznych komend to często celowe zabezpieczenie - poprawiaj warunek precyzyjnie, a nie wyłączaj ochrony w całości.

Wróć do listy: 100 najczęstszych problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5