Hooks

Gli hook sono comandi shell, endpoint HTTP o prompt LLM definiti dall'utente che vengono eseguiti automaticamente in punti specifici del ciclo di vita di Claude Code. La distinzione chiave è che mentre le istruzioni CLAUDE.md sono contestuali e potrebbero essere ignorate, gli hook sono codice che viene eseguito indipendentemente dalle decisioni di Claude. Se un'azione deve avvenire in un punto fisso — prima di ogni commit, dopo ogni modifica di file — dovrebbe essere implementata come hook.

I nomi degli eventi verificati includono: SessionStart, SessionEnd, Setup, UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied, PreCompact, PostCompact, Notification, SubagentStart, SubagentStop, InstructionsLoaded, e FileChanged.

La configurazione segue una struttura a tre livelli: seleziona un evento hook, aggiungi un gruppo matcher per filtrare quando si attiva (es. 'Bash'), e definisci gli handlers. Gli handler possono essere di tipo command, http, mcp_tool, prompt, o agent. Le posizioni di configurazione verificate includono ~/.claude/settings.json (globale), .claude/settings.json (specifico del progetto), .claude/settings.local.json (specifico del progetto e ignorato da git), hooks/hooks.json di un plugin, e il frontmatter di skill o agent (con ambito alla durata attiva del componente).

La semantica del codice di uscita è critica: un codice di uscita di 0 significa successo, consentendo a Claude Code di analizzare l'output JSON per decisioni successive. Un codice di uscita di 2 indica un errore bloccante, impedendo la chiamata dello strumento e mostrando stderr a Claude. Altri codici di uscita non nulli sono trattati come errori non bloccanti.

Fondamentalmente, un hook PreToolUse può restituire una permissionDecision di deny per impedire l'esecuzione di una chiamata allo strumento. Questo fornisce un potente meccanismo per far rispettare vincoli o validare condizioni prima che vengano intraprese azioni. Per la gestione degli hook, la skill Hooks Management può tradurre il linguaggio naturale in configurazioni validate, e la skill Debug Hooks offre un flusso di lavoro per la risoluzione dei problemi.