Hook nefunguje alebo prekáža

Hook je už nastavený, príkaz /hooks ho zobrazuje, no potom sa začnú diať zvláštne veci. Odošlete požiadavku, ale nový riadok sa neobjaví v requests.log. Alebo sa objaví dvakrát. Niekedy je to horšie: automatická akcia sa spustí po každej úprave a začne prekážať bežnej práci.

V takej situácii netreba znovu skladať celé nastavenie. Užitočnejšie je premeniť pozorovanie na malú overiteľnú úlohu: na čo má hook zareagovať, akú stopu má zanechať a aký prípad musí preskočiť. Potom Claude Code dokáže overiť konkrétne súbory a navrhnúť minimálnu opravu.

Kedy má hook zareagovať

V tomto článku rozoberáme príkazové hooks zo súborov nastavení. Pri takom hooku sú dôležité tri časti: udalosť, podmienka spustenia a obslužná rutina. Udalosť odpovedá na otázku "kedy sledovať", podmienka zužuje vhodné prípady, obslužná rutina vykonáva akciu.

Napríklad denník požiadaviek je naviazaný na UserPromptSubmit. Táto udalosť nastane, keď do relácie príde požiadavka, ešte pred jej spracovaním modelom. Najčastejšie je to vaša požiadavka, ale Claude Code ju spúšťa aj pri ťahoch, ktoré začína sám: ďalšie kolo /loop, hlásenie subagenta na pozadí. Nový riadok v denníku preto potvrdzuje len málo - hook dostal požiadavku a zapísal ju, nič viac. Či agent splnil úlohu správne, z tohto riadku nezistíte.

UserPromptSubmit nemá matcher. Ak denník potrebuje len niektoré požiadavky, vyberá ich sama obslužná rutina. Pri nástrojových udalostiach je situácia iná. Napríklad matcher Edit|Write vyberá nástroje a cesta k súboru sa overuje samostatne podľa údajov volania. Matcher s názvom nástroja neznamená "len súbory zo src".

Pred opravou si zapíšte dva krátke scenáre:

• potrebný: odoslať testovaciu požiadavku a vidieť jeden nový riadok v requests.log;
• nežiaduci: otvoriť súbor v bežnom editore bez toho, aby ste Claude Code poslali novú požiadavku, a overiť, že denník sa nezmenil. Pri denníku všetkých požiadaviek by aj druhý odoslaný prompt mal dať záznam; nebude to negatívna kontrola.

Toto sú kritériá overenia. Konkrétnu odpoveď Claude Code netreba vopred vymýšľať.

Záznam sa neobjavil

Začnite tam, kde sa pozorovanie rozchádza s očakávaním. Pri denníku je to chýbajúci nový riadok po testovacej požiadavke. Ďalej postupujte od nastavenia k akcii:

1. Zadajte /hooks v interaktívnej relácii Claude Code a overte, či je potrebný záznam načítaný. Toto menu otvárate vy; to, čo v ňom uvidíte, odovzdajte agentovi.
2. Overte udalosť. Denník požiadaviek by mal reagovať na UserPromptSubmit, zatiaľ čo akcia po zmene súboru sa zvyčajne viaže na nástrojovú udalosť.
3. Nájdite zdrojový súbor nastavenia. Môže ísť o používateľské, projektové alebo lokálne nastavenie; porovnávajte nielen názvy, ale aj celé príkazy. To, že rovnaká obslužná rutina je zapísaná hneď vo viacerých súboroch nastavení, samo osebe neznamená dve spustenia.
4. Overte príkaz obslužnej rutiny: či súbor existuje, či príkaz zodpovedá vášmu OS, či sa nerozbila cesta s medzerami.
5. Overte miesto výsledku. Relatívna cesta závisí od pracovného adresára procesu, takže obslužná rutina mohla zapísať súbor inam, ako ho hľadáte.

Hlavná cesta tu vedie cez agenta. Odovzdajte mu pozorovanie, výsledok kontroly /hooks a hranice úpravy:

Hook UserPromptSubmit je vidieť v /hooks, ale po testovacej požiadavke
sa v requests.log neobjavil nový riadok.

Nájdi zdrojové nastavenie a obslužnú rutinu. Over udalosť, cestu k príkazu,
pracovný adresár a vytvorenie priečinka pre denník. Ukáž príčinu
a urob minimálnu opravu. Ostatné hooks a nastavenia zachovaj.
Po oprave opíš potrebný a negatívny kontrolný scenár.

Napríklad agent zistil: obslužná rutina zapisuje do logs/requests.log, ale priečinok logs/ neexistuje a skript ho nevytvára. Minimálna oprava spočíva vo vytvorení tohto priečinka pred zápisom. Po nej overte práve logs/requests.log: jedna testovacia požiadavka by mala pridať jeden záznam. Toto je príklad možnej príčiny, nie diagnóza akéhokoľvek prázdneho denníka.

Ak je nastavenie v súbore, ale chýba v /hooks, príčina môže byť v syntaxi JSON, rozsahu nastavenia alebo v tom, že sa hooks teraz vôbec nespúšťajú: priečinok projektu nie je označený ako dôveryhodný, je zapnuté disableAllHooks alebo správca povolil len hooks z riadenej politiky. Hooks z rôznych súborov nastavení sa sčítavajú, nenahrádzajú jeden druhý. Ak je záznam načítaný, ale stopa chýba, pozornosť sa presúva na príkaz, vstupné dáta a cestu výstupu.

Zmysel rozcestia je jednoduchý: kým Claude Code nenačítal záznam, je predčasné riešiť fungovanie skriptu. Keď je záznam vidieť, konfigurácia sa už dostala do aplikácie a užitočnejšie je overovať spustenie obslužnej rutiny, vstupný JSON a miesto, kde má vzniknúť výsledok.

Obslužná rutina skončila chybou

Príkazový hook dostáva JSON cez štandardný vstup. Sú v ňom všeobecné polia udalosti a údaje konkrétnej udalosti. Pri UserPromptSubmit prichádza text požiadavky v poli prompt. Tento text treba čítať ako dáta. Nemožno ho spojiť so shellovým príkazom a vykonať: testovacia požiadavka môže obsahovať úvodzovky, konce riadkov a akýkoľvek bežný text.

Požiadajte Claude Code, aby zopakoval spustenie obslužnej rutiny na vymyslenom vstupe. V zadaní hneď uveďte dôležité prípady:

Over obslužnú rutinu hooku mimo relácie na vymyslenom JSON.
Potrebné prípady: bežný a viacriadkový prompt, cesta projektu s medzerami,
chýbajúci priečinok denníka a nesprávny vstup.

Nevykonávaj text promptu ako kód. Ukáž príkaz spustenia, návratový kód,
stderr a skutočnú zmenu testovacieho súboru. Nemeň pracovný denník.

Návratový kód pomáha pochopiť osud samotnej obslužnej rutiny, ale jeho zmysel závisí od udalosti. exit 0 hovorí, že príkaz hooku skončil bez chyby. To nepotvrdzuje výsledok celej úlohy. exit 2 môže zablokovať akciu pri udalostiach "pred", ale po vykonanom nástroji už jeho prácu nezruší. Preto jeden recept s exit 2 nemožno prenášať medzi udalosťami naslepo.

Ak je samostatné spustenie úspešné, ale hook v relácii stále mlčí, spustite Claude Code z priečinka projektu s príkazom claude --debug-file hook-debug.log a zopakujte jednu testovaciu požiadavku. Otvorte vzniknutý hook-debug.log a nájdite udalosť, zodpovedajúce hooks a návratový kód. Je to denník samotného Claude Code, oddelený od vášho requests.log. Po overení túto diagnostickú reláciu ukončite; na bežnú prácu spúšťajte Claude Code bez tohto prepínača. Bežný stdout väčšiny udalostí ide do debug logu a nemusí sa objaviť v transcripte. Výnimky závisia od udalosti, takže ľubovoľné diagnostické riadky v stdout môžu ovplyvniť kontext namiesto toho, aby sa stali praktickým logom.

Hook sa spúšťa navyše

Dva rovnaké riadky po jednej požiadavke môžu poukazovať na opakovanú registráciu: podobné, ale nie úplne rovnaké hooks ležia napríklad v používateľských a projektových nastaveniach. Ak je to doslova ten istý príkaz, len zopakovaný v rôznych súboroch, spustí sa aj tak iba raz. Kópie z pluginu alebo skillu sa počítajú samostatne, takže zdroj v menu je tiež dôležitý. Najprv odovzdajte agentovi výsledok /hooks a požiadajte ho, aby vypísal záznamy tejto udalosti vo všetkých dostupných súboroch nastavení. Ak je v nastaveniach všetko v poriadku, overte, či samotná obslužná rutina nezapisuje dvakrát za jedno spustenie. Mazať prvý nájdený riadok je predčasné.

Ďalšou častou príčinou je príliš široká podmienka. Predpokladajme, že hook má nechávať diagnostickú značku po zmene súborov v src/, ale reaguje na každé použitie Edit a Write. Tu sú potrebné dve úrovne výberu:

• matcher vyberá nástroje Edit a Write;
• samostatná podmienka overuje cestu z argumentov nástroja a preskakuje všetko mimo src/.

Jedna kontrola nenahrádza druhú. Matcher odfiltruje nevhodné nástroje, potom podmienka podľa argumentov ponechá len cesty zo src/. Diagnostická značka sa objaví, len keď obe kontroly dajú odpoveď "áno".

Fragment nastavenia môže vyzerať takto:

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      { "type": "command", "command": "python .claude/hooks/mark-source-edit.py" }
    ]
  }
]

Toto je prvok objektu hooks v existujúcom settings.json, nie úplný JSON dokument. Kontrola cesty má byť v obslužnej rutine; skript mark-source-edit.py je tu len ilustračný, jeho telo v článku nie je. Príkaz predpokladá dostupný python a spustenie z koreňa projektu. Agent má overiť interpreter, shell a cestu vo vašom nastavení; kopírovať príklad ako hotové pripojenie sa neodporúča.

Tento fragment sa dobre číta ako jedna veta:

Reťazec ukazuje len to, čo je zadané v nastavení. Rozhodnutie "ponechať značku alebo preskočiť súbor" robí až obslužná rutina po overení cesty. Preto prítomnosť matchera potvrdzuje výber nástroja, ale ešte nedokazuje správne filtrovanie src/.

V tejto tabuľke Edit a Write znamenajú nástroje Claude Code. Ručná zmena súboru v editore ich nespúšťa, a preto takýto matcher neoveruje. Pred každou akciou si poznačte koniec diagnostického súboru a potom porovnajte len nové záznamy.

Kým hranica nie je overená, nechajte akciu neškodnú: jedna značka o spustení, bez formátovania, blokovania alebo hromadnej úpravy súborov. Najprv sa uistite, že potrebný prípad prejde presne raz a nežiaduci neprejde.

Spustenie navyše vždy pridáva prácu. Pritom lokálny príkaz, ktorý len zapisuje súbor, sám osebe model nevolá. Hook typu prompt alebo agent funguje inak a model používa. Podrobný rozbor nákladov tu netreba, stačí tieto dva typy obslužných rutín nezamieňať.

Ako vypnúť reakciu

Ak hook práve teraz prekáža, nájdite jeho zdrojový záznam a z poľa danej udalosti odstráňte iba ten. Ostatné hooks nechajte na mieste. Toto je vypnutie budúcich spustení: nezruší už vykonaný príkaz, nevráti zmenené súbory a nevymaže riadky, ktoré sa už dostali do denníka.

Pred vymazaním si uložte kópiu vybraného záznamu, ak sa ho chystáte vrátiť. Po zmene znova otvorte /hooks a overte, že tento záznam už neexistuje. Ak menu stále zobrazuje staré nastavenie, ukončite reláciu a otvorte novú z toho istého projektu. Potom vykonajte kontrolnú akciu a porovnajte denník pred a po. Nové riadky od vypnutého hooku by sa nemali objaviť.

Na dočasné vypnutie všetkých hooks existuje nastavenie "disableAllHooks": true. Je to však hlavný vypínač, nie spôsob, ako vypnúť jeden záznam. Pri samotnom tomto nastavení priority súborov fungujú: "disableAllHooks": false v projektovom súbore prebije true z vašich používateľských nastavení. Okrem toho hooks zadané riadenou politikou organizácie sa nedajú vypnúť bežným používateľským alebo projektovým nastavením.

Ako zadať opravu Claude Code

Dobré zadanie obsahuje pozorovanie, očakávanú udalosť, konkrétne súbory a hranicu zmeny. To stačí na to, aby agent preskúmal nastavenie bez prepisovania celej automatizácie:

Vyrieš hook v tomto projekte.

Pozorovanie: po jednej testovacej požiadavke pribudnú v requests.log dva riadky.
/loop ani subagenti na pozadí v tejto relácii nie sú spustené.
Očakávanie: UserPromptSubmit má pridať presne jeden riadok.
Priložím výsledok /hooks. Over všetky dostupné zdroje nastavenia
a príkaz obslužnej rutiny.

Najprv pomenuj príčinu a súbory, ktoré treba zmeniť. Potom urob
minimálnu opravu, zachovaj ostatné hooks a ukáž diff.
Over potrebný aj negatívny prípad. Nakoniec ukáž,
ako vypnúť len túto reakciu.

Na konci by ste mali mať štyri jasné odpovede:

• ktorá udalosť hook spúšťa;
• ktorá podmienka preskakuje nežiaduce prípady;
• kde ležia zdrojové nastavenie a obslužná rutina;
• ako vypnúť presne túto reakciu bez zásahu do ostatných.

A celá kontrolná trasa: potrebná akcia zanechá jednu očakávanú stopu, nežiaduca nezanechá žiadnu, chyba obslužnej rutiny je vidieť v cielenej diagnostike, po vypnutí sa nová stopa už neobjaví. Je to celkom prízemné. Práve preto sa takýto hook udržiava ľahšie ako automatizácia, ktorá jednoducho "občas niečo robí".

Na overenie správania použite oficiálnu referenciu hooks a praktický návod: rozhranie sa mení spolu s Claude Code.

Správanie bolo porovnané s oficiálnou dokumentáciou 18. septembra 2026. Príklady ukazujú postup overenia; hotová obslužná rutina tu nie je. Príkaz a cesty si overte vo svojom OS a shelli.