Rezumat rapid: Hook-urile Claude Code sunt scripturi de automatizare care se execută în puncte specifice ale ciclului de viață în timpul sesiunilor de codare AI, permițând dezvoltatorilor să ruleze comenzi personalizate, să valideze acțiuni, să formateze codul, să trimită notificări și să impună regulile proiectului. Aceste hook-uri se integrează cu fluxul de lucru al lui Claude prin evenimente precum SessionStart, PreToolUse și PostToolUse, suportând modele de execuție bazate pe comenzi, bazate pe HTTP și bazate pe prompt, cu timpi de expirare configurabili și comportament al codului de ieșire.
Sistemul de hook-uri al Claude Code transformă asistentul de codare AI dintr-un instrument util într-un mediu de dezvoltare complet automatizat. Majoritatea dezvoltatorilor nu realizează gradul de control disponibil prin hook-uri.
Aici intervine problema—hook-urile nu vizează doar rularea scripturilor după modificările fișierelor. Acestea oferă puncte de interceptare pe parcursul întregului proces de luare a deciziilor al lui Claude. Înainte ca acesta să execute o comandă. După ce un apel de instrument eșuează. Când are nevoie de permisiune. Chiar și înainte de procesarea prompturilor utilizatorului.
Acest ghid acoperă tot ce oferă documentația oficială, plus modele practice care discuțiile din comunitate relevă că funcționează în medii de producție.
Ce fac de fapt hook-urile Claude Code
Conform documentației oficiale Claude Code, hook-urile sunt comenzi shell definite de utilizator, endpoint-uri HTTP sau injecții de prompt care se execută în puncte specifice ale ciclului de viață al Claude Code. Acestea primesc intrări JSON structurate prin stdin și controlează fluxul de lucru prin coduri de ieșire sau răspunsuri HTTP.
Automatizarea este mai profundă decât sugerează majoritatea ghidurilor. Hook-urile pot bloca complet execuția instrumentelor, pot injecta context suplimentar în raționamentul lui Claude, pot declanșa servicii externe și pot impune reguli de validare pe care Claude trebuie să le respecte.
Există trei tipuri principale de hook-uri:
- Hook-uri de comandă: Scripturi shell care comunică prin stdout, stderr și coduri de ieșire
- Hook-uri HTTP: Endpoint-uri la distanță care primesc cereri POST și returnează răspunsuri JSON
- Hook-uri de prompt: Instrucțiuni dinamice injectate în contextul lui Claude la evenimente specifice
Fiecare tip servește diferite modele de automatizare. Hook-urile de comandă gestionează validarea și formatarea locală. Hook-urile HTTP se integrează cu servicii externe și baze de date. Hook-urile de prompt modifică comportamentul lui Claude fără procese externe.
Ciclu de viață al hook-urilor și sistemul de evenimente
Documentația oficială definește multiple evenimente de hook (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification și altele) care se declanșează pe parcursul fluxului de execuție al Claude Code. Înțelegerea momentului în care se declanșează fiecare determină ce automatizare devine posibilă.
| Eveniment | Când se declanșează | Poate bloca |
|---|---|---|
| SessionStart | Când o sesiune începe sau se reia | Nu |
| UserPromptSubmit | Când trimiteți un prompt, înainte ca Claude să-l proceseze | Da |
| PreToolUse | Înainte ca un apel de instrument să se execute | Da |
| PermissionRequest | Când apare o fereastră de dialog pentru permisiune | Da |
| PostToolUse | După ce un apel de instrument reușește | Nu |
| PostToolUseFailure | După ce un apel de instrument eșuează | Nu |
| Notification | Când Claude Code trimite o notificare | Nu |
| SubmitMessage | Când Claude trimite un mesaj utilizatorului | Nu |
| ContextCompaction | Când fereastra de context se apropie de limite | Nu |
Capacitatea de blocare este cea mai importantă. Hook-urile PreToolUse pot preveni operațiuni periculoase înainte ca acestea să fie executate. Codul de ieșire 1 blochează acțiunea. Codul de ieșire 0 permite aceasta. Codul de ieșire 2 îl determină pe Claude să reconsidere.
Dar stați. Hook-urile PostToolUse nu pot anula acțiuni, deoarece instrumentul a fost deja executat. Această limitare modelează modul în care sunt structurate regulile de validare. Verificările critice aparțin PreToolUse. Curățarea și formatarea aparțin PostToolUse.
Răsfoiți oferte AI Tool Perks în timp ce configurați Claude Code
Dacă lucrați cu hook-uri Claude Code, este posibil să alegeți și alte instrumente AI în fluxul dvs. de lucru. Get AI Perks colectează credite de startup și reduceri software pentru instrumente AI și cloud într-un singur loc. Platforma include peste 200 de oferte, cu condiții de ofertă și ghid de revendicare pentru fiecare.
Căutați oferte pentru Claude sau alte instrumente AI?
Verificați Get AI Perks pentru:
- răsfoiți oferte pentru Claude și alte instrumente AI
- comparați condițiile de ofertă înainte de a aplica
- găsiți reduceri de startup pe întregul stivă de instrumente
👉 Vizitați Get AI Perks pentru a explora ofertele actuale de software AI.
Configurare și structura fișierelor
Hook-urile sunt definite în fișierul .claude/settings.json din cadrul unui proiect. Schema de configurare suportă hook-uri globale și potriviri specifice instrumentelor care filtrează când se execută hook-urile.
Structură de bază a hook-ului de comandă:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Variabila ${file} se extinde la calea fișierului real din intrarea instrumentului. Conform documentației oficiale, hook-urile suportă aceste extinderi de variabile în câmpurile command și args.
Ierarhia locațiilor hook-urilor
Claude Code verifică multiple locații pentru definiții de hook-uri, cu o ordine clară de precedență:
- La nivel de proiect: .claude/settings.json în spațiul de lucru curent
- La nivel de utilizator: ~/.claude/settings.json pentru toate sesiunile
- Furnizate de plugin: Hook-uri împachetate cu plugin-uri instalate
Hook-urile de proiect suprascriu hook-urile utilizatorului pentru același eveniment. Aceasta permite reguli de formatare specifice proiectului, menținând în același timp gestionari globali de notificări.
Modele de potrivire pentru execuție selectivă
Sistemul de potrivire filtrează hook-urile la instrumente sau condiții specifice. Fără potriviri, hook-urile se declanșează pentru fiecare apariție a evenimentului lor.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Câmpul pathPattern acceptă sintaxă glob. Câmpul toolName se potrivește cu instrumentele încorporate ale lui Claude, cum ar fi edit_file, execute_command, read_file și create_directory.
Discuțiile din comunitate relevă că combinațiile de potriviri funcționează cu logica ȘI. Toate potrivirile specificate trebuie să se potrivească pentru ca hook-ul să se execute.
Hook-uri de comandă: Integrare cu scripturi shell
Hook-urile de comandă execută comenzi sau scripturi shell cu intrări JSON structurate. Acestea reprezintă cel mai comun tip de hook pentru automatizarea locală.
Documentația oficială specifică faptul că hook-urile de comandă primesc JSON prin stdin cu această structură:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Scripturile analizează această intrare pentru a lua decizii. Un hook de validare Python ar putea arăta astfel:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Codul de ieșire 0 permite operațiunea. Codul de ieșire 1 o blochează și afișează mesajul stderr lui Claude. Codul de ieșire 2 declanșează un comportament special, în funcție de eveniment.
Comportamentul codului de ieșire 2
Conform documentației oficiale de referință a hook-urilor, codul de ieșire 2 are o semnificație specifică evenimentului (PreToolUse: blochează și solicită reconsiderare; UserPromptSubmit: oferă context fără a bloca; PermissionRequest: blochează permisiunea):
- PreToolUse: Blochează instrumentul și îl determină pe Claude să reconsidere, utilizând mesajul stderr ca și context
- UserPromptSubmit: Oferă ieșirea stderr ca context suplimentar fără a bloca
- PermissionRequest: Blochează acordarea permisiunii
Aceasta creează un mijloc de mijloc între blocarea completă și permitere. Claude primește feedback cu privire la motivul pentru care acțiunea ar putea fi problematică și își poate ajusta abordarea.
Hook-uri de comandă asincrone
Flag-ul async: true rulează hook-urile în fundal, fără a bloca fluxul de lucru al lui Claude. Acest lucru este important pentru operațiuni lente, cum ar fi notificările de implementare sau colectarea metricilor.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Când se declanșează un hook async, Claude Code pornește procesul și continuă imediat. Câmpul timeout stabilește timpul maxim de execuție în secunde. Dacă nu este specificat, hook-urile async folosesc un timeout implicit de 10 minute.
Sincer vorbind: hook-urile async nu pot bloca operațiuni, deoarece rulează după ce Claude a continuat. Ele funcționează pentru înregistrare, notificări și curățare - nu pentru validare.
Hook-uri HTTP: Integrare cu servicii externe
Hook-urile HTTP trimit payload-uri JSON către endpoint-uri la distanță și analizează răspunsurile pentru controlul deciziilor. Acestea permit integrarea cu servicii de validare, baze de date și instrumente terțe.
Configurare de bază a hook-ului HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Structura payload-ului corespunde intrării hook-ului de comandă, dar ajunge ca corp al cererii HTTP POST. Răspunsul determină următoarea acțiune a lui Claude.
Gestionarea răspunsurilor HTTP
Conform documentației oficiale, hook-urile HTTP interpretează răspunsurile în funcție de codul de stare și conținutul corpului:
| Cod de stare | Efect | Sursa mesajului |
|---|---|---|
| 200 | Permite operațiunea | Corp de răspuns (opțional) |
| 400 | Blochează operațiunea | Corp de răspuns afișat lui Claude |
| 500 | Eroare hook, permite operațiunea | Înregistrată, dar nu afișată lui Claude |
| Altele | Permite operațiunea | Eșecul hook-ului nu blochează fluxul de lucru |
Corpul răspunsului poate include un câmp message pe care Claude îl vede ca context. Acest lucru permite serviciilor de validare să explice de ce o operațiune a fost blocată.
Interpolarea variabilelor de mediu
Hook-urile HTTP suportă sintaxa ${VAR} în url, headers și alte câmpuri de tip șir. Variabilele se extind din mediul în care rulează Claude Code.
Conform documentației oficiale MCP, extinderea variabilelor de mediu include o sintaxă implicită de fallback: ${VAR:-default} se extinde la VAR dacă este setată, altfel folosește valoarea implicită.
Restricție de securitate: Conform issue-ului GitHub #28044, hook-urile HTTP pot accesa doar variabile de mediu listate explicit în câmpul de configurare allowedEnvVars. Aceasta previne expunerea accidentală a credențialelor.
Hook-uri de prompt: Inserare context
Hook-urile de prompt injectează instrucțiuni dinamice în contextul lui Claude la evenimente specifice. Acestea modifică comportamentul fără procese externe sau apeluri API.
| { “event”: “SessionStart”, “prompt”: “You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises.” } |
Textul injectat devine parte din instrucțiunile sistemului lui Claude pentru acea sesiune. Hook-urile de prompt pot folosi, de asemenea, variabile șablon care se extind pe baza datelor evenimentului.
Generare dinamică de prompt
Conform documentației oficiale, hook-urile de prompt suportă câmpuri de comandă care generează prompturi dinamice:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Comanda primește intrarea JSON standard prin stdin și generează textul promptului către stdout. Aceasta permite generarea de instrucțiuni conștiente de context, bazate pe starea proiectului.
Hook-uri bazate pe agenți
Hook-urile de agent specifică un subagent care gestionează evenimentul, în loc de injecție directă de prompt. Subagentul primește context despre eveniment și poate efectua raționament în mai mulți pași.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “A tool call failed. Analyze the error and suggest fixes.” } |
Subagentul numit trebuie să fie definit în configurația proiectului. Hook-urile de agent permit logică complexă de decizie, pe care injecția simplă de prompt nu o poate oferi.
Modele practice de hook-uri
Discuțiile din comunitate și exemplele oficiale relevă modele de automatizare specifice care funcționează fiabil în producție.
Formatare automată a codului după modificări
Cel mai comun model formatează codul automat după ce Claude modifică fișierele:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Variabila ${toolInput.path} se extinde la calea fișierului modificat. PostToolUse asigură că formatarea are loc după modificări reușite, dar nu blochează fluxul de lucru al lui Claude.
Blocarea modificărilor fișierelor protejate
Hook-urile PreToolUse impun reguli de protecție a fișierelor:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Scriptul validează calea țintă împotriva modelelor protejate și iese cu codul 1 pentru a bloca modificările interzise.
Fiți notificat când Claude necesită intrare
Conform ghidului oficial de flux de lucru, hook-urile de notificare pot declanșa alerte desktop sau pot trimite mesaje către servicii externe:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Acest lucru se declanșează ori de câte ori Claude Code trimite o notificare, inclusiv atunci când așteaptă intrarea utilizatorului sau după finalizarea unei sarcini.
Re-injectați contextul după compactare
Hook-urile ContextCompaction restaurează contextul important atunci când fereastra conversației se umple:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Ieșirea comenzii este injectată înapoi în contextul lui Claude după ce compactarea elimină mesajele mai vechi. Aceasta previne pierderea instrucțiunilor critice specifice proiectului.
Auditați modificările de configurare
Urmăriți când Claude modifică fișierele de configurare:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Execuția asincronă previne blocarea lui Claude în timp ce operațiunile git se finalizează. Aceasta creează o pistă de audit a modificărilor de configurare fără intervenție manuală.
Ieșire JSON și controlul deciziilor
Hook-urile de comandă pot genera JSON structurat pentru a oferi feedback detaliat dincolo de simpla coduri de ieșire. Conform referinței oficiale, ieșirea JSON permite răspunsuri cu mai multe câmpuri pe care Claude le interpretează pentru luarea deciziilor.
| { “allowed”: false, “message”: “This file is protected by team policy”, “suggestion”: “Create a new file in src/features/ instead” } |
Câmpul allowed controlează dacă operațiunea continuă. Mesajul apare lui Claude ca și context. Câmpul suggestion oferă abordări alternative.
Pentru ca hook-urile să genereze JSON, acestea trebuie:
- Să scrie un JSON valid în stdout
- Să iasă cu codul 0 (pentru permis) sau 1 (pentru blocat)
- Să includă cel puțin câmpul boolean allowed
Claude Code analizează JSON-ul și îl folosește pentru a îmbunătăți bucla de feedback. Codurile de ieșire determină în continuare decizia principală, dar JSON-ul oferă un context mai bogat.
Referință câmpuri de intrare hook
Toate hook-urile primesc un obiect JSON prin stdin cu câmpuri comune plus date specifice evenimentului. Înțelegerea schemei complete permite o logică mai sofisticată a hook-urilor.
Câmpuri de intrare comune
Fiecare hook primește aceste câmpuri de bază:
- event: Numele evenimentului hook (ex: "PreToolUse")
- sessionId: Identificator unic pentru sesiunea curentă Claude
- turnId: Identificator pentru tura curentă de conversație
- timestamp: Marcaj temporal ISO 8601 când s-a declanșat evenimentul
Câmpuri pentru evenimente instrument
Evenimentele PreToolUse, PostToolUse și PostToolUseFailure includ:
- toolName: Numele instrumentului invocat (edit_file, execute_command, etc.)
- toolInput: Obiect care conține parametrii de intrare ai instrumentului
- toolResponse: Date de ieșire ale instrumentului (doar PostToolUse)
- error: Detalii ale erorii, inclusiv mesajul și codul (doar PostToolUseFailure)
Structura toolInput variază în funcție de instrument. Pentru edit_file, conține path și content. Pentru execute_command, conține command și args.
Câmpuri pentru evenimente de permisiune
Evenimentele PermissionRequest includ:
- permissionType: Tipul de permisiune solicitată (file_write, command_execute, etc.)
- requestedAction: Acțiunea specifică care necesită permisiune
- resourcePath: Calea fișierului sau identificatorul resursei afectate
Hook-uri MCP Tool
Conform referinței oficiale a hook-urilor, hook-urile se pot potrivi cu instrumente de Protocol de Context al Modelului (MCP) folosind câmpul matcher mcpTool. Aceasta permite execuția hook-urilor atunci când Claude utilizează instrumente externe furnizate de servere MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Valoarea mcpTool se potrivește cu numele instrumentului în formatul server-name/tool-name. Aceasta permite logica de validare pentru interogări de baze de date, apeluri API sau alte operațiuni externe.
Cererile de funcționalități GitHub indică un interes crescut pentru integrarea mai profundă a MCP, inclusiv hook-uri care pot inspecta notificările serverului MCP și pot răspunde la evenimente externe.
Considerații de securitate
Hook-urile se execută cu aceleași permisiuni ca și Claude Code în sine. Aceasta creează implicații de securitate pentru mediile multi-utilizator și configurațiile partajate.
Sandbox pentru execuția comenzilor
Conform issue-ului GitHub #28044, hook-urile HTTP sunt rutate printr-un proxy sandbox care restricționează accesul la rețea și filtrează variabilele de mediu. Hook-urile de comandă nu au astfel de restricții—se execută cu acces complet la shell.
Documentația recomandă aceste practici:
- Nu stocați niciodată credențiale în comenzile hook
- Utilizați variabile de mediu pentru date sensibile
- Validați toate intrările din expansiunile ${…}
- Implementați limite de timp pentru servicii externe
- Utilizați hook-uri async pentru operațiuni non-critice pentru a preveni blocarea în caz de eșec
Izolarea execuției hook-urilor
Hook-urile la nivel de utilizator din ~/.claude/settings.json se aplică tuturor proiectelor. Aceasta creează riscuri atunci când se lucrează în granițe de încredere diferite. Hook-urile la nivel de proiect suprascriu hook-urile utilizatorului, dar nu le pot dezactiva complet.
Meniul /hooks din Claude Code afișează toate hook-urile active pentru sesiunea curentă. Revizuirea acestei liste înainte de a lucra la proiecte sensibile ajută la identificarea potențialelor probleme de securitate.
Depanare și soluționare probleme
Eșecurile hook-urilor nu apar întotdeauna clar în conversația lui Claude. Documentația oficială oferă mai multe abordări de depanare.
Jurnale de execuție a hook-urilor
Claude Code înregistrează execuția hook-urilor în ieșirea de depanare a sesiunii. Conform ghidului de soluționare a problemelor, activarea jurnalizării de depanare dezvăluie:
- Ce hook-uri s-au potrivit pentru fiecare eveniment
- Intrarea JSON trimisă fiecărui hook
- Ieșirea stdout și stderr din procesele hook
- Coduri de ieșire și timp de execuție
- Coduri de stare HTTP și corpuri pentru hook-urile HTTP
Activați jurnalizarea de depanare setând CLAUDE_DEBUG=1 în mediu înainte de a porni Claude Code.
Testarea hook-urilor independent
Hook-urile de comandă pot fi testate în afara Claude Code prin construirea manuală a intrării JSON:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Acest lucru validează logica hook-ului fără a declanșa operațiuni reale ale lui Claude. Codul de ieșire și ieșirea stdout/stderr ar trebui să corespundă comportamentului așteptat.
Eșecuri comune ale hook-urilor
Discuțiile din comunitate identifică aceste probleme frecvente:
- Erori de timeout: Timeout-ul implicit de 10 minute este prea scurt pentru operațiuni lente—creșteți-l cu câmpul timeout
- Eșecuri de extindere a căii: Variabile precum ${file} nu sunt definite pentru evenimente care nu includ contextul fișierului
- Erori de permisiune: Scripturile hook nu au permisiuni de execuție—rulați chmod +x script.sh
- Erori de analiză JSON: Ieșire JSON incorectă de la hook-uri—validați cu jq înainte de a returna
- Indisponibilitatea variabilelor de mediu: Variabilele nu sunt propagate către procesul hook—verificați mediul Claude Code
Implicații de performanță ale hook-urilor
Hook-urile sincrone blochează fluxul de lucru al lui Claude până la finalizare. Timeout-ul implicit de 10 minute previne blocajele nedeterminate, dar chiar și întârzierile scurte se acumulează în operațiuni multiple.
Practicienii raportează că hook-urile simple de validare au un impact neglijabil asupra performanței. Hook-urile de formatare a fișierelor cauzează un impact perceptibil, dar acceptabil asupra performanței. Apelurile către API-uri externe pot crea fricțiuni în fluxul de lucru. Operațiunile computaționale intensive beneficiază de execuția asincronă.
Batching hook-uri
Multiple hook-uri se pot potrivi aceluiași eveniment. Conform documentației de referință, hook-urile se execută secvențial în ordinea definiției. Dacă orice hook blochează operațiunea, hook-urile rămase nu se execută.
Acest lucru este important pentru performanță. Cinci hook-uri sincrone la 200 ms fiecare adaugă o secundă per eveniment. Combinarea validărilor conexe într-un singur hook reduce supraîncărcarea.
Modele avansate
Dincolo de automatizarea de bază, hook-urile permit personalizarea sofisticată a fluxului de lucru.
Lanțuri de hook-uri cu stare
Hook-urile pot menține starea între execuții utilizând fișiere sau baze de date. Un hook PostToolUse ar putea înregistra operațiuni reușite pe care un hook PreToolUse le validează ulterior:
| #!/bin/bash # Record successful edits echo “${toolInput.path}” >> .claude/edit-history.txt |
Un hook PreToolUse însoțitor ar putea verifica acest istoric pentru a preveni operațiuni redundante sau pentru a impune constrângeri de ordine.
Activare condiționată a hook-urilor
Variabilele de mediu controlează comportamentul hook-urilor la rulare. Setarea CLAUDE_SKIP_HOOKS=1 dezactivează hook-urile pentru situații de urgență.
Hook-urile însele pot verifica flag-uri de mediu:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Apply strict validation exit 1 fi exit 0 |
Aceasta permite comportament de mod de dezvoltare versus mod de producție fără modificări de configurare.
Validare în mai mulți pași
Hook-urile PreToolUse pot implementa validare în mai multe niveluri, unde codul de ieșire 2 îi permite lui Claude să continue cu avertismente:
- Eșecuri complete (cod 1): Blochează operațiuni periculoase
- Avertismente ușoare (cod 2): Avertizează Claude să reconsidere
- Trece cu context (cod 0 + JSON): Oferă informații suplimentare
Aceasta creează un spectru de validare mai nuanțat decât binarul permitere/refuzare.
Integrare cu CI/CD
Conform documentației oficiale de integrare a platformei, Claude Code rulează în medii CI/CD pentru revizuirea automată a codului și triajul problemelor. Hook-urile extind această automatizare.
Fluxurile de lucru GitHub Actions pot defini hook-uri care impun politici de echipă în timpul sesiunilor automate:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
Flag-ul STRICT_MODE activează logica de validare condiționată în scripturile hook. Aceasta asigură că sesiunile automate respectă reguli mai rigide decât dezvoltarea interactivă.
Generare audit trail
Hook-urile PostToolUse în medii CI creează jurnale de audit detaliate ale tuturor operațiunilor Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Înregistrarea în fundal nu afectează performanța, dar oferă un istoric complet al operațiunilor pentru conformitate și depanare.
Meniul /hooks
Claude Code oferă o comandă /hooks care afișează toate hook-urile active pentru sesiunea curentă. Conform documentației oficiale, acest meniu afișează:
- Tipul evenimentului hook
- Modele de potrivire
- Comanda sau endpoint-ul URL
- Dacă hook-ul rulează async
- Sursa de configurare (proiect, utilizator sau plugin)
Selectarea unui hook afișează configurația sa completă și permite dezactivarea temporară pentru sesiunea curentă.
Dezactivați sau eliminați hook-uri
Hook-urile pot fi dezactivate fără a elimina configurația adăugând "enabled": false la definiția hook-ului. Aceasta păstrează configurația, dar previne execuția.
Pentru a elimina permanent un hook, ștergeți intrarea sa din fișierul settings.json corespunzător. Modificările intră în vigoare la următoarea repornire a sesiunii sau când rulați /reload.
Hook-uri în Skills și Agenți
Conform documentației oficiale, hook-urile definite în configurațiile de skill sau subagent se aplică doar atunci când acel skill sau agent se execută. Aceasta permite automatizare specializată pentru fluxuri de lucru specifice.
Un subagent de depanare ar putea include hook-uri care înregistrează toate apelurile instrumentelor:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Aceste hook-uri se declanșează doar în timpul sesiunilor agentului de depanare, nu în timpul operațiunii normale a Claude Code.
Referențierea scripturilor după cale
Comenzile hook suportă căi relative și absolute. Căile relative se rezolvă de la rădăcina proiectului unde rulează Claude Code.
Cele mai bune practici din discuțiile comunității:
- Stocați scripturile hook în directorul .claude/hooks/
- Folosiți nume descriptive: validate-typescript.sh nu hook1.sh
- Faceți scripturile executabile: chmod +x .claude/hooks/*.sh
- Includeți linia shebang: #!/usr/bin/env bash sau #!/usr/bin/env python3
- Adăugați gestionarea erorilor cu set -e în scripturile bash
Capacități viitoare ale hook-urilor
Cererile de funcționalități GitHub dezvăluie îmbunătățiri planificate și solicitate ale hook-urilor:
- Hook-uri de script inline: Definiți logica hook direct în settings.json fără fișiere externe
- Integrare instrumente MCP: Invocați instrumente server MCP din hook-uri în loc de comenzi shell
- Colaborare multi-agent: Hook-uri care coordonează între instanțe Claude pe mașini diferite
- Tipărire îmbunătățită: Definiții de tipuri TypeScript pentru schemele de intrare/ieșire ale hook-urilor
Conform issue-ului GitHub #4274, cererea pentru tipuri de hook integrate (instrument MCP, script inline, apel API) vizează simplificarea configurării și îmbunătățirea experienței dezvoltatorului.
Întrebări frecvente
Pot hook-urile să împiedice Claude să execute comenzi periculoase?
Da. Hook-urile PreToolUse pot bloca orice execuție de instrument prin ieșirea cu codul 1. Aceasta include modificări de fișiere, execuții de comenzi și apeluri de instrumente MCP. Hook-ul primește intrarea completă a instrumentului și poate valida împotriva oricărui criteriu înainte de a permite operațiunea.
Cum depanez un hook care nu funcționează?
Activați jurnalizarea de depanare cu CLAUDE_DEBUG=1 înainte de a porni Claude Code. Verificați jurnalele sesiunii pentru detalii de execuție a hook-urilor, inclusiv ce hook-uri s-au potrivit, intrarea JSON trimisă, ieșirea stdout/stderr și codurile de ieșire. Testați hook-urile independent prin trimiterea JSON-ului de probă către scriptul hook.
Hook-urile funcționează cu toate platformele Claude Code?
Hook-urile funcționează în CLI, aplicația desktop și extensia VS Code. Conform documentației oficiale, hook-urile se execută oriunde rulează Claude Code cu acces la sistemul de fișiere. Claude bazat pe browser și aplicațiile mobile nu suportă hook-uri din cauza constrângerilor de sandbox.
Pot hook-urile să modifice răspunsurile sau comportamentul lui Claude?
Hook-urile de prompt injectează instrucțiuni care influențează comportamentul lui Claude. Hook-urile de agent deleagă gestionarea evenimentelor către subagenți specializați. Cu toate acestea, hook-urile nu pot modifica direct textul generat sau procesul de raționament al lui Claude—acestea funcționează prin furnizarea de context și blocarea operațiunilor.
Care este diferența dintre hook-urile async și sync?
Hook-urile sincrone blochează fluxul de lucru al lui Claude până la finalizare sau expirarea timpului. Hook-urile asincrone rulează în fundal fără a bloca. Hook-urile sync pot preveni operațiuni prin coduri de ieșire. Hook-urile async nu pot bloca, deoarece Claude continuă înainte ca hook-ul să se finalizeze. Folosiți async pentru înregistrare și notificări, sync pentru validare.
Cum partajez hook-uri cu o echipă?
Salvați fișierul .claude/settings.json în controlul versiunilor. Hook-urile la nivel de proiect se aplică tuturor membrilor echipei care clonează depozitul. Pentru politici la nivel de organizație, echipele pot menține un fișier de setări partajat la nivel de utilizator pe care membrii îl copiază în ~/.claude/settings.json.
Pot hook-urile HTTP să apeleze API-uri interne din spatele firewall-urilor?
Da, dacă Claude Code rulează într-un mediu cu acces la rețea la acele API-uri. Hook-urile HTTP fac cereri POST standard de pe mașina care rulează Claude Code. Firewall-urile corporative și VPN-urile se aplică normal. Proxy-ul sandbox menționat în documentație controlează expunerea variabilelor de mediu, nu rutarea rețelei.
Hook-urile măresc utilizarea token-urilor Claude Code?
Hook-urile de prompt injectează text în contextul lui Claude, ceea ce consumă token-uri. Hook-urile de comandă și HTTP nu afectează direct utilizarea token-urilor, dar ieșirea lor (mesaje de eroare, sugestii) devine parte din contextul conversației. Codul de ieșire 2 cu mesaje explicative adaugă mai mult context decât codul de ieșire 1 cu blocare simplă.
Concluzie
Hook-urile Claude Code transformă asistentul AI dintr-un instrument puternic într-o platformă de dezvoltare complet automatizată. Sistemul de evenimente oferă puncte de interceptare pe parcursul fluxului de lucru al lui Claude—de la inițializarea sesiunii până la compactarea contextului.
Hook-urile de comandă gestionează validarea și formatarea locală. Hook-urile HTTP integrează servicii și baze de date externe. Hook-urile de prompt modifică comportamentul prin injectare de context. Împreună, acestea permit modele de automatizare care impun politici de echipă, mențin calitatea codului și se integrează cu infrastructura de dezvoltare existentă.
Sistemul de potrivire filtrează hook-urile la instrumente și modele de fișiere specifice. Codurile de ieșire și ieșirea JSON controlează fluxul decizional. Execuția asincronă previne blocarea operațiunilor lente. Schema completă de configurare suportă totul, de la formatare automată simplă la validare complexă în mai mulți pași.
Începeți cu hook-uri simple PostToolUse pentru formatarea codului. Adăugați validare PreToolUse pe măsură ce apar politici. Experimentați cu hook-uri de prompt pentru modificarea comportamentului. Creați integrări HTTP pentru aplicare la nivel de echipă.
Verificați documentația oficială Claude Code pentru referința completă a hook-urilor și schema de configurare actualizată pe măsură ce apar noi funcționalități.
