Hook, který nefunguje nebo překáží

Hook je už nastavený, příkaz /hooks ho ukazuje, a pak začne něco divného. Odešlete požadavek, ale nový řádek se v requests.log neobjeví. Nebo se objeví dvakrát. Někdy hůř: automatická akce se spustí po jakékoli úpravě a začne překážet běžné práci.

V takové situaci není potřeba znovu skládat celé nastavení. Užitečnější je proměnit pozorování v malý ověřitelný úkol: co má hook spustit, jakou stopu má zanechat a jaký případ musí přeskočit. Pak Claude Code může ověřit konkrétní soubory a navrhnout minimální opravu.

Kdy má hook zareagovat

V tomto článku rozebíráme příkazové hooks ze souborů nastavení. U takového hooku jsou důležité tři části: událost, podmínka spuštění a obslužná rutina. Událost odpovídá na otázku "kdy se dívat", podmínka zužuje vhodné případy, obslužná rutina provede akci.

Například deník požadavků je navázaný na UserPromptSubmit. Tato událost nastane, když do relace přijde požadavek, ještě před jeho zpracováním modelem. Nejčastěji je to váš požadavek, ale Claude Code ji spouští i u kroků, které zahajuje sám: další kolo /loop, hlášení subagenta na pozadí. Nový řádek v deníku proto potvrzuje jen málo - hook dostal požadavek a zapsal ho, nic víc. Jestli agent úkol vykonal správně, z tohoto řádku nepoznáte.

Událost UserPromptSubmit nemá matcher. Pokud deník potřebuje jen některé požadavky, vybírá je sama obslužná rutina. U událostí nástrojů je to jinak. Například matcher Edit|Write vybírá nástroje, cesta k souboru se kontroluje zvlášť podle dat volání. Matcher s názvem nástroje neznamená "jen soubory ze src".

Před opravou si zapište dva krátké scénáře:

• potřebný: odeslat testovací požadavek a vidět jeden nový řádek v requests.log;
• zbytečný: otevřít soubor v běžném editoru, bez odeslání nového požadavku do Claude Code, a ověřit, že se deník nezměnil. U deníku všech požadavků musí i druhý odeslaný prompt dát záznam; nebude to negativní kontrola.

Tohle jsou kritéria ověření. Konkrétní odpověď Claude Code si předem vymýšlet nemusíte.

Záznam se neobjevil

Začněte v místě, kde se pozorování liší od očekávání. U deníku je to chybějící nový řádek po testovacím požadavku. Dál postupujte od nastavení k akci:

1. Zadejte /hooks v interaktivní relaci Claude Code a ověřte, zda je potřebný záznam načtený. Toto menu otevíráte vy; co v něm uvidíte, předejte agentovi.
2. Ověřte událost. Deník požadavků má reagovat na UserPromptSubmit, zatímco akce po změně souboru se obvykle váže na událost nástroje.
3. Najděte zdrojový soubor nastavení. Může jít o uživatelské, projektové nebo lokální nastavení; srovnávejte nejen názvy, ale i celé příkazy. Stejná obslužná rutina nalezená hned ve více souborech nastavení sama o sobě neznamená dvě spuštění.
4. Zkontrolujte příkaz obslužné rutiny: existuje soubor, hodí se příkaz pro váš OS, nerozbila se cesta s mezerami.
5. Zkontrolujte místo výsledku. Relativní cesta závisí na pracovním adresáři procesu, takže obslužná rutina mohla zapsat soubor jinam, než kde ho hledáte.

Hlavní cesta tady vede přes agenta. Předejte mu pozorování, výsledek kontroly /hooks a hranice úpravy:

Hook UserPromptSubmit je vidět v /hooks, ale po testovacím požadavku
se v requests.log neobjeví nový řádek.

Najdi zdrojové nastavení a obslužnou rutinu. Zkontroluj událost, cestu k příkazu,
pracovní adresář a vytvoření složky pro deník. Ukaž příčinu
a proveď minimální opravu. Ostatní hooks a nastavení zachovej.
Po opravě popiš potřebný i negativní kontrolní scénář.

Agent například zjistil: obslužná rutina zapisuje do logs/requests.log, ale složka logs/ neexistuje a skript ji nevytváří. Minimální oprava spočívá ve vytvoření této složky před zápisem. Po ní zkontrolujte přesně logs/requests.log: jeden testovací požadavek by měl přidat jeden záznam. Toto je příklad možné příčiny, ne diagnóza pro jakýkoli prázdný deník.

Pokud je nastavení v souboru, ale chybí v /hooks, příčina může být v syntaxi JSON, rozsahu nastavení nebo v tom, že se hooks teď vůbec nespouštějí: složka projektu není označená jako důvěryhodná, je zapnuté disableAllHooks nebo správce povolil jen hooks ze spravované politiky. Hooks z různých souborů nastavení se sčítají, nenahrazují jeden druhý. Pokud je záznam načtený, ale stopa chybí, pozornost se přesouvá k příkazu, vstupním datům a cestě výstupu.

Smysl rozcestí je jednoduchý: dokud Claude Code nenačetl záznam, je brzy řešit práci skriptu. Když je záznam vidět, konfigurace se už dostala do aplikace a je užitečnější kontrolovat spuštění obslužné rutiny, vstupní JSON a místo, kde se má objevit výsledek.

Obslužná rutina skončila chybou

Příkazový hook dostává JSON přes standardní vstup. Jsou v něm obecná pole události a data konkrétní události. U UserPromptSubmit přichází text požadavku v poli prompt. Tento text je potřeba číst jako data. Nelze ho slepit se shellovým příkazem a spustit: testovací požadavek může obsahovat uvozovky, konce řádků a jakýkoli běžný text.

Požádejte Claude Code, aby reprodukoval spuštění obslužné rutiny na vymyšleném vstupu. V požadavku rovnou uveďte důležité případy:

Ověř obslužnou rutinu hooku odděleně od relace na vymyšleném JSON.
Potřebné případy: běžný a víceřádkový prompt, cesta projektu s mezerami,
chybějící složka deníku a neplatný vstup.

Nespouštěj text promptu jako kód. Ukaž příkaz spuštění, návratový kód,
stderr a skutečnou změnu testovacího souboru. Neměň pracovní deník.

Návratový kód pomáhá pochopit, co se stalo se samotnou obslužnou rutinou, ale jeho význam závisí na události. exit 0 říká, že příkaz hooku skončil bez chyby. To nepotvrzuje výsledek celého úkolu. exit 2 může zablokovat akci u událostí "před", zatímco po provedeném nástroji už jeho práci nezruší. Proto jeden recept s exit 2 nelze slepě přenášet mezi událostmi.

Pokud je samostatné spuštění úspěšné, ale v relaci hook stále mlčí, spusťte Claude Code ze složky projektu s příkazem claude --debug-file hook-debug.log a zopakujte jeden testovací požadavek. Otevřete vzniklý hook-debug.log a najděte událost, odpovídající hooks a návratový kód. Je to log samotného Claude Code, oddělený od vašeho requests.log. Po kontrole tuto diagnostickou relaci ukončete; pro běžnou práci spouštějte Claude Code bez tohoto přepínače. Běžný stdout většiny událostí jde do debug logu a nemusí se objevit v transcriptu. Výjimky závisí na události, takže libovolné diagnostické řádky ve stdout mohou ovlivnit kontext místo toho, aby se staly praktickým logem.

Hook se spouští navíc

Dva stejné řádky po jednom požadavku mohou znamenat opakovanou registraci: podobné, ale ne úplně stejné hooks leží například v uživatelských a projektových nastaveních. Pokud jde doslova o stejný příkaz, jen zopakovaný v různých souborech, spustí se stejně jen jednou. Kopie z pluginu nebo skillu se počítají zvlášť, takže zdroj v menu je taky důležitý. Nejdřív předejte agentovi výsledek /hooks a požádejte ho, aby vyjmenoval záznamy této události ve všech dostupných souborech nastavení. Pokud je nastavení v pořádku, zkontrolujte, jestli sama obslužná rutina nezapisuje dvakrát za jedno spuštění. Mazat hned první nalezený řádek je předčasné.

Další častou příčinou je příliš široká podmínka. Řekněme, že hook má nechávat diagnostickou značku po změně souborů v src/, ale reaguje na každé použití Edit a Write. Tady jsou potřeba dvě úrovně výběru:

• matcher vybírá nástroje Edit a Write;
• samostatná podmínka kontroluje cestu z argumentů nástroje a přeskočí vše mimo src/.

Jedna kontrola nenahrazuje druhou. Matcher odfiltruje nevhodné nástroje, pak podmínka podle argumentů ponechá jen cesty ze src/. Diagnostická značka se objeví, jen když obě kontroly dají odpověď "ano".

Fragment nastavení může vypadat takto:

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

Toto je prvek objektu hooks v existujícím settings.json, ne kompletní JSON dokument. Kontrola cesty má být v obslužné rutině; skript mark-source-edit.py je tu smyšlený, jeho tělo v článku není. Příkaz předpokládá dostupný python a spuštění z kořene projektu. Agent má ověřit interpret, shell a cestu ve vašem nastavení; kopírovat příklad jako hotové připojení se nedoporučuje.

Tento fragment se dobře čte jako jedna věta:

Řetězec ukazuje jen to, co je zadáno v nastavení. Rozhodnutí "nechat značku, nebo soubor přeskočit" dělá až obslužná rutina po kontrole cesty. Přítomnost matcheru proto potvrzuje výběr nástroje, ale ještě nedokazuje správné filtrování src/.

V této tabulce Edit a Write znamenají nástroje Claude Code. Ruční změna souboru v editoru je nevyvolá, a proto takový matcher neotestuje. Před každou akcí si poznamenejte konec diagnostického souboru a pak srovnejte jen nové záznamy.

Dokud hranice není ověřená, nechte akci neškodnou: jedna značka o spuštění, bez formátování, blokování nebo hromadné úpravy souborů. Nejdřív se ujistěte, že potřebný případ projde přesně jednou a zbytečný neprojde vůbec.

Zbytečné spuštění navíc vždy přidává práci. Přitom lokální příkaz, který jen zapisuje soubor, sám o sobě model nepoužívá. Hook typu prompt nebo agent funguje jinak a model používá. Podrobný rozbor nákladů tu není potřeba, stačí tyto dva typy obslužných rutin nesplést.

Jak reakci vypnout

Pokud hook právě teď překáží, najděte jeho zdrojový záznam a z pole dané události smažte jen jeho. Ostatní hooks nechte na místě. Toto je vypnutí budoucích spuštění: nezruší už provedený příkaz, nevrátí změněné soubory a nesmaže řádky, které se už dostaly do deníku.

Před smazáním si uložte kopii vybraného záznamu, pokud ho plánujete vrátit zpět. Po úpravě znovu otevřete /hooks a ověřte, že tento záznam už tam není. Pokud menu ještě ukazuje staré nastavení, ukončete relaci a otevřete novou ze stejného projektu. Pak proveďte kontrolní akci a srovnejte deník před a po. Nové řádky od vypnutého hooku by se objevit neměly.

Pro dočasné vypnutí všech hooks existuje nastavení "disableAllHooks": true. Je to ale hlavní vypínač, ne způsob, jak vypnout jeden záznam. U samotného tohoto nastavení priority souborů fungují: "disableAllHooks": false v projektovém souboru přebije true z vašeho uživatelského nastavení. Kromě toho hooks zadané spravovanou politikou organizace nelze vypnout běžným uživatelským ani projektovým nastavením.

Jak svěřit opravu Claude Code

Dobré zadání obsahuje pozorování, očekávanou událost, konkrétní soubory a hranici úpravy. To stačí, aby agent prozkoumal nastavení, aniž by přepisoval celou automatizaci:

Vyřeš problém s hookem v tomto projektu.

Pozorování: po jednom testovacím požadavku dostane requests.log dva řádky.
/loop ani subagenti na pozadí v této relaci nejsou spuštěné.
Očekávání: UserPromptSubmit má přidat přesně jeden řádek.
Přiložím výsledek /hooks. Zkontroluj všechny dostupné zdroje nastavení
a příkaz obslužné rutiny.

Nejdřív pojmenuj příčinu a soubory, které je potřeba změnit. Pak proveď
minimální opravu, zachovej ostatní hooks a ukaž diff.
Ověř potřebný i negativní případ. Nakonec ukaž,
jak vypnout jen tuto reakci.

Na konci byste měli mít čtyři jasné odpovědi:

• jaká událost hook spouští;
• jaká podmínka přeskočí zbytečné případy;
• kde leží zdrojové nastavení a obslužná rutina;
• jak vypnout právě tuto reakci, aniž byste zasáhli ostatní.

A celá kontrolní trasa: potřebná akce zanechá jednu očekávanou stopu, zbytečná nezanechá žádnou, chyba obslužné rutiny je vidět v cílené diagnostice, po vypnutí se nová stopa už neobjeví. Je to celkem přízemní. Právě proto se takový hook udržuje snadněji než automatizace, která prostě "občas něco dělá".

Pro ověření chování použijte oficiální referenci hooks a praktického průvodce: rozhraní se mění spolu s Claude Code.

Chování ověřeno podle oficiální dokumentace 18. září 2026. Příklady ukazují postup ověřování; hotová obslužná rutina tu není. Příkaz a cesty si ověřte ve svém OS a shellu.