Resum ràpid: Claude Code hooks són scripts d'automatització que s'executen en punts específics del cicle de vida durant les sessions de codificació amb IA, permetent als desenvolupadors executar ordres personalitzades, validar accions, formatar codi, enviar notificacions i fer complir les regles del projecte. Aquests hooks s'integren amb el flux de treball de Claude mitjançant esdeveniments com SessionStart, PreToolUse i PostToolUse, donant suport a patrons d'execució basats en ordres, basats en HTTP i basats en prompts amb timeouts configurables i comportament de codi de sortida.
El sistema de hooks de Claude Code transforma l'assistent de codificació IA d'una eina útil a un entorn de desenvolupament totalment automatitzat. La majoria dels desenvolupadors no s'adonen de l'abast del control disponible a través dels hooks.
Això és el que passa: els hooks no només serveixen per executar scripts després de les edicions de fitxers. Proporcionen punts d'intercepció durant tot el procés de presa de decisions de Claude. Abans que executi una ordre. Després que una crida a una eina falli. Quan necessita permís. Fins i tot abans de processar prompts de l'usuari.
Aquesta guia cobreix tot el que proporciona la documentació oficial, a més de patrons pràctics que les discussions de la comunitat revelen que realment funcionen en entorns de producció.
Què fan realment els Claude Code Hooks
Segons la documentació oficial de Claude Code, els hooks són ordres de shell definides per l'usuari, punts finals HTTP o injeccions de prompt que s'executen en punts específics del cicle de vida de Claude Code. Reben entrada JSON estructurada via stdin i controlen el flux de treball mitjançant codis de sortida o respostes HTTP.
L'automatització va més enllà del que suggereixen la majoria de guies. Els hooks poden bloquejar completament l'execució d'eines, injectar context addicional al raonament de Claude, activar serveis externs i fer complir regles de validació que Claude ha de respectar.
Hi ha tres tipus principals de hooks:
- Hooks d'ordre: Scripts de shell que es comuniquen mitjançant stdout, stderr i codis de sortida
- Hooks HTTP: Punts finals remots que reben peticions POST i retornen respostes JSON
- Hooks de prompt: Instruccions dinàmiques injectades al context de Claude en esdeveniments específics
Cada tipus serveix per a diferents patrons d'automatització. Els hooks d'ordre gestionen la validació local i el format. Els hooks HTTP s'integren amb serveis externs i bases de dades. Els hooks de prompt modifiquen el comportament de Claude sense processos externs.
Sistema de Cicle de Vida i Esdeveniments de Hook
La documentació oficial defineix múltiples esdeveniments de hook (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification i altres) que s'activen durant el flux d'execució de Claude Code. Comprendre quan es dispara cada un determina quina automatització és possible.
| Esdeveniment | Quan es dispara | Pot bloquejar |
|---|---|---|
| SessionStart | Quan una sessió comença o es reprèn | No |
| UserPromptSubmit | Quan envieu un prompt, abans que Claude el processi | Sí |
| PreToolUse | Abans que s'executi una crida a eina | Sí |
| PermissionRequest | Quan apareix un diàleg de permís | Sí |
| PostToolUse | Després que una crida a eina tingui èxit | No |
| PostToolUseFailure | Després que una crida a eina falli | No |
| Notification | Quan Claude Code envia una notificació | No |
| SubmitMessage | Quan Claude envia un missatge a l'usuari | No |
| ContextCompaction | Quan la finestra de context s'aproxima als límits | No |
La capacitat de bloqueig és el més important. Els hooks PreToolUse poden prevenir operacions perilloses abans que s'executin. El codi de sortida 1 bloqueja l'acció. El codi de sortida 0 la permet. El codi de sortida 2 fa que Claude reconsideri.
Però espereu. Els hooks PostToolUse no poden desfer accions ja que l'eina ja s'ha executat. Aquesta limitació modela com s'estructura la lògica de validació. Les comprovacions crítiques pertanyen a PreToolUse. La neteja i el format pertanyen a PostToolUse.
Navega per els Avantatges d'Eines IA mentre Configures Claude Code
Si estàs treballant amb hooks de Claude Code, és possible que també estiguis escollint altres eines d'IA al teu voltant. Get AI Perks recopila crèdits per a startups i descomptes de programari per a eines d'IA i cloud en un sol lloc. La plataforma inclou més de 200 ofertes, amb condicions d'avantatge i guia de reclamació per a cadascuna.
Busques avantatges de Claude o d'altres eines IA?
Consulta Get AI Perks per:
- navegar per les ofertes de Claude i altres eines IA
- comparar les condicions dels avantatges abans d'aplicar-vos
- trobar descomptes per a startups a tota la vostra pila d'eines
👉 Visita Get AI Perks per explorar els avantatges de programari IA actuals.
Configuració i Estructura de Fitxers
Els hooks es defineixen al fitxer .claude/settings.json dins d'un projecte. L'esquema de configuració admet hooks globals i comparadors específics d'eines que filtren quan s'executen els hooks.
Estructura bàsica del hook d'ordre:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
La variable ${file} s'expandeix al camí del fitxer real de l'entrada de l'eina. Segons la documentació oficial, els hooks admeten aquestes expansions de variables en els camps de comanda i arguments.
Jerarquia d'Ubicació dels Hooks
Claude Code comprova diverses ubicacions per a les definicions de hooks, amb un ordre de precedència clar:
- A nivell de projecte: .claude/settings.json a l'espai de treball actual
- A nivell d'usuari: ~/.claude/settings.json per a totes les sessions
- Proporcionat per plugins: Hooks inclosos amb plugins instal·lats
Els hooks de projecte anul·len els hooks d'usuari per al mateix esdeveniment. Això permet regles de formatació específiques del projecte mantenint controladors de notificacions globals.
Patrons de Comparació per a l'Execució Selectiva
El sistema de comparació filtra els hooks a eines o condicions específiques. Sense comparadors, els hooks es disparen per a cada ocurrència del seu esdeveniment.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
El camp pathPattern accepta sintaxi glob. El camp toolName compara amb les eines integrades de Claude com edit_file, execute_command, read_file i create_directory.
Les discussions de la comunitat revelen que les combinacions de comparadors funcionen amb lògica AND. Tots els comparadors especificats han de coincidir perquè el hook s'executi.
Hooks d'Ordre: Integració de Scripts de Shell
Els hooks d'ordre executen ordres o scripts de shell amb entrada JSON estructurada. Representen el tipus de hook més comú per a l'automatització local.
La documentació oficial especifica que els hooks d'ordre reben JSON via stdin amb aquesta estructura:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Els scripts analitzen aquesta entrada per prendre decisions. Un hook de validació en Python podria semblar:#!/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(“No es poden editar fitxers protegits”, file=sys.stderr) sys.exit(1) sys.exit(0) |
El codi de sortida 0 permet l'operació. El codi de sortida 1 la bloqueja i mostra el missatge stderr a Claude. El codi de sortida 2 activa un comportament especial depenent de l'esdeveniment.
Comportament del Codi de Sortida 2
Segons la documentació oficial de referència dels hooks, el codi de sortida 2 té un significat específic de l'esdeveniment (PreToolUse: bloqueja i demana reconsideració; UserPromptSubmit: proporciona context sense bloquejar; PermissionRequest: bloqueja el permís):
- PreToolUse: Bloqueja l'eina i demana a Claude que reconsideri amb el missatge stderr com a context
- UserPromptSubmit: Proporciona la sortida stderr com a context addicional sense bloquejar
- PermissionRequest: Bloqueja la concessió del permís
Això crea un punt mig entre el bloqueig dur i la permissió. Claude rep retroalimentació sobre per què l'acció podria ser problemàtica i pot ajustar el seu enfocament.
Hooks d'Ordre Asíncrons
La bandera async: true executa els hooks en segon pla sense bloquejar el flux de treball de Claude. Això és important per a operacions lentes com notificacions de desplegament o recopilació de mètriques.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Quan es dispara un hook asíncron, Claude Code inicia el procés i continua immediatament. El camp timeout estableix el temps màxim d'execució en segons. Si no s'especifica, els hooks asíncrons utilitzen un timeout per defecte de 10 minuts.
Parlem clar: els hooks asíncrons no poden bloquejar operacions ja que s'executen després que Claude continuï. Funcionen per a registre, notificacions i neteja, no per a validació.
Hooks HTTP: Integració de Serveis Externs
Els hooks HTTP envien payloads JSON a punts finals remots i analitzen les respostes per controlar les decisions. Permeten la integració amb serveis de validació, bases de dades i eines de tercers.
Configuració bàsica del hook HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
L'estructura del payload coincideix amb la entrada del hook d'ordre però arriba com a cos HTTP POST. La resposta determina la propera acció de Claude.
Gestió de Respostes HTTP
Segons la documentació oficial, els hooks HTTP interpreten les respostes basant-se en el codi d'estat i el contingut del cos:
| Codi d'estat | Efecte | Font del Missatge |
|---|---|---|
| 200 | Permet l'operació | Cos de la resposta (opcional) |
| 400 | Bloqueja l'operació | Cos de la resposta mostrat a Claude |
| 500 | Error del hook, permet l'operació | Registrat però no mostrat a Claude |
| Altres | Permet l'operació | La fallada del hook no bloqueja el flux de treball |
El cos de la resposta pot incloure un camp de missatge que Claude veu com a context. Això permet que els serveis de validació expliquin per què una operació va ser bloquejada.
Interpola de Variables d'Entorn
Els hooks HTTP admeten la sintaxi ${VAR} a url, headers i altres camps de text. Les variables s'expandeixen des de l'entorn on s'executa Claude Code.
Segons la documentació oficial de MCP, l'expansió de variables d'entorn inclou una sintaxi de fallback per defecte: ${VAR:-default} s'expandeix a VAR si està definida, sinó utilitza el valor per defecte.
Restricció de seguretat: Segons el problema de GitHub #28044, els hooks HTTP només poden accedir a variables d'entorn explícitament llistades al camp de configuració allowedEnvVars. Això evita l'exposició accidental de credencials.
Hooks de Prompt: Injecció de Context
Els hooks de prompt injecten instruccions dinàmiques al context de Claude en esdeveniments específics. Modifiquen el comportament sense processos externs ni trucades a API.
| { “event”: “SessionStart”, “prompt”: “Estàs treballant en un projecte TypeScript. Utilitza sempre comprovacions estrictes de nuls i prefereix async/await sobre promeses.” } |
El text injectat esdevé part de les instruccions del sistema de Claude per a aquesta sessió. Els hooks de prompt també poden utilitzar variables de plantilla que s'expandeixen segons les dades de l'esdeveniment.
Generació Dinàmica de Prompt
Segons la documentació oficial, els hooks de prompt admeten camps d'ordre que generen prompts dinàmicament:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
L'ordre rep l'entrada JSON estàndard via stdin i emet el text del prompt a stdout. Això permet la generació d'instruccions sensibles al context basades en l'estat del projecte.
Hooks Basats en Agents
Els hooks d'agent especifiquen un subagent que gestiona l'esdeveniment en lloc d'una injecció de prompt directa. El subagent rep context sobre l'esdeveniment i pot realitzar un raonament multi-pas.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “La crida a una eina ha fallat. Analitza l'error i suggereix correccions.” } |
El subagent anomenat ha de ser definit a la configuració del projecte. Els hooks d'agent permeten una lògica de decisió complexa que la simple injecció de prompt no pot proporcionar.
Patrons Pràctics de Hooks
Les discussions de la comunitat i els exemples oficials revelen patrons d'automatització específics que funcionen de manera fiable en producció.
Format Automàtic del Codi Després de les Edicions
El patró més comú formula automàticament el codi després que Claude editi fitxers:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
La variable ${toolInput.path} s'expandeix al camí del fitxer editat. PostToolUse assegura que el format es realitza després d'edicions exitoses, però no bloqueja el flux de treball de Claude.
Bloquejar Modificacions de Fitxers Protegits
Els hooks PreToolUse apliquen regles de protecció de fitxers:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
L'script valida el camí de destinació contra patrons protegits i surt amb el codi 1 per bloquejar edicions prohibides.
Rebre Notificacions Quan Claude Necessita Entrada
Segons la guia oficial de flux de treball, els hooks de Notificació poden activar alertes d'escriptori o enviar missatges a serveis externs:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Això es dispara sempre que Claude Code envia una notificació, incloent quan espera entrada de l'usuari o després de la finalització d'una tasca.
Reinjectar Context Després de la Compactació
Els hooks de ContextCompaction restauren el context important quan la finestra de conversa s'omple:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
La sortida de l'ordre s'injecta de nou al context de Claude després que la compactació elimini els missatges antics. Això evita la pèrdua d'instruccions crítiques específiques del projecte.
Auditar Canvis de Configuració
Rastrejar quan Claude modifica fitxers de configuració:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
L'execució asíncrona evita bloquejar Claude mentre les operacions git es completen. Això crea un rastre d'auditoria de canvis de configuració sense posada en escena manual.
Sortida JSON i Control de Decisions
Els hooks d'ordre poden emetre JSON estructurat per proporcionar retroalimentació detallada més enllà de simples codis de sortida. Segons la referència oficial, la sortida JSON permet respostes de múltiples camps que Claude interpreta per a la presa de decisions.
| { “allowed”: false, “message”: “Aquest fitxer està protegit per la política de l'equip”, “suggestion”: “Creeu un nou fitxer a src/features/ en el seu lloc” } |
El camp allowed controla si l'operació procedeix. El missatge apareix a Claude com a context. El camp suggestion proporciona enfocaments alternatius.
Perquè els hooks emetin JSON, han de:
- Escriure JSON vàlid a stdout
- Sortir amb codi 0 (per permès) o 1 (per bloquejat)
- Incloure com a mínim el camp booleà allowed
Claude Code analitza el JSON i l'utilitza per millorar el bucle de retroalimentació. Els codis de sortida encara determinen la decisió principal, però el JSON proporciona un context més ric.
Referència de Camps d'Entrada dels Hooks
Tots els hooks reben un objecte JSON via stdin amb camps comuns més dades específiques de l'esdeveniment. Comprendre l'esquema complet permet una lògica de hook més sofisticada.
Camps d'Entrada Comuns
Cada hook rep aquests camps base:
- event: El nom de l'esdeveniment del hook (p. ex., "PreToolUse")
- sessionId: Identificador únic de la sessió de Claude actual
- turnId: Identificador del gir de conversa actual
- timestamp: Marca de temps ISO 8601 quan es va disparar l'esdeveniment
Camps d'Esdeveniments d'Eina
Els esdeveniments PreToolUse, PostToolUse i PostToolUseFailure inclouen:
- toolName: Nom de l'eina que s'està invocant (edit_file, execute_command, etc.)
- toolInput: Objecte que conté els paràmetres d'entrada de l'eina
- toolResponse: Dades de sortida de l'eina (només PostToolUse)
- error: Detalls de l'error incloent missatge i codi (només PostToolUseFailure)
L'estructura de toolInput varia segons l'eina. Per a edit_file conté path i content. Per a execute_command conté command i args.
Camps d'Esdeveniments de Permís
Els esdeveniments PermissionRequest inclouen:
- permissionType: Tipus de permís sol·licitat (file_write, command_execute, etc.)
- requestedAction: Acció específica que requereix permís
- resourcePath: Camí del fitxer o identificador de recurs afectat
Hooks d'Eina MCP
Segons la referència oficial dels hooks, els hooks poden comparar-se amb eines del Model Context Protocol (MCP) utilitzant el camp de comparació mcpTool. Això permet l'execució de hooks quan Claude utilitza eines externes proporcionades per servidors MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
El valor mcpTool compara amb el nom de l'eina en format nomServidor/nomEina. Això permet la lògica de validació per a consultes de bases de dades, trucades a API o altres operacions externes.
Les sol·licituds de funcions a GitHub indiquen un interès creixent en una integració MCP més profunda, incloent hooks que puguin inspeccionar notificacions de servidors MCP i respondre a esdeveniments externs.
Consideracions de Seguretat
Els hooks s'executen amb els mateixos permisos que Claude Code. Això crea implicacions de seguretat per a entorns multi-usuari i configuracions compartides.
Sandbox d'Execució d'Ordres
Segons el problema de GitHub #28044, els hooks HTTP passen per un proxy sandbox que restringeix l'accés a la xarxa i filtra les variables d'entorn. Els hooks d'ordre no tenen aquestes restriccions: s'executen amb accés complet a la shell.
La documentació recomana aquestes pràctiques:
- Mai emmagatzemar credencials en ordres de hooks
- Utilitzar variables d'entorn per a dades sensibles
- Validar tota l'entrada de les expansions ${...}
- Implementar límits de temps per a serveis externs
- Utilitzar hooks asíncrons per a operacions no crítiques per evitar bloquejos en fallades
Aïllament de l'Execució dels Hooks
Els hooks a nivell d'usuari a ~/.claude/settings.json s'apliquen a tots els projectes. Això crea riscos quan es treballa entre diferents límits de confiança. Els hooks a nivell de projecte anul·len els hooks d'usuari però no poden deshabilitar-los completament.
El menú /hooks a Claude Code mostra tots els hooks actius per a la sessió actual. Revisar aquesta llista abans de treballar en projectes sensibles ajuda a identificar possibles preocupacions de seguretat.
Depuració i Resolució de Problemes
Les fallades dels hooks no sempre són clares a la conversa de Claude. La documentació oficial proporciona diversos enfocaments de depuració.
Logs d'Execució dels Hooks
Claude Code registra l'execució dels hooks a la sortida de depuració de la sessió. Segons la guia de resolució de problemes, habilitar el registre de depuració revela:
- Quins hooks van coincidir per a cada esdeveniment
- L'entrada JSON enviada a cada hook
- Sortida stdout i stderr dels processos dels hooks
- Codi de sortida i temps d'execució
- Codis de resposta HTTP i cossos per a hooks HTTP
Habilita el registre de depuració establint CLAUDE_DEBUG=1 a l'entorn abans d'iniciar Claude Code.
Provar Hooks Independentment
Els hooks d'ordre es poden provar fora de Claude Code construint manualment l'entrada JSON:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Això valida la lògica del hook sense activar operacions reals de Claude. El codi de sortida i la sortida stdout/stderr han de coincidir amb el comportament esperat.
Fallades Comunes dels Hooks
Les discussions de la comunitat identifiquen aquests problemes freqüents:
- Errors de timeout: El timeout per defecte de 10 minuts és massa curt per a operacions lentes: augmenta-ho amb el camp timeout
- Fallades d'expansió de camí: Variables com ${file} no definides per a esdeveniments que no inclouen context de fitxer
- Errors de permís: Els scripts dels hooks no tenen permisos d'execució: executa chmod +x script.sh
- Errors d'anàlisi JSON: Sortida JSON malformada dels hooks: valida amb jq abans de retornar
- Indisponibilitat de variables d'entorn: Variables no propagades al procés del hook: comprova l'entorn de Claude Code
Implicacions de Rendiment dels Hooks
Els hooks síncrons bloquegen el flux de treball de Claude fins a la finalització. El timeout per defecte de 10 minuts evita bloquejos indefinits, però fins i tot retards curts s'acumulen entre múltiples operacions.
Els professionals informen que els hooks de validació simples tenen un impacte de rendiment negligible. Els hooks de formatació de fitxers causen un impacte de rendiment notable però acceptable. Les trucades a API externes poden crear fricció en el flux de treball. Les operacions de computació pesada es beneficien de l'execució asíncrona.
Agrupació de Hooks
Diversos hooks poden coincidir amb el mateix esdeveniment. Segons la documentació de referència, els hooks s'executen seqüencialment en ordre de definició. Si algun hook bloqueja l'operació, els hooks restants no s'executen.
Això és important per al rendiment. Cinc hooks síncrons a 200 ms cadascun afegeixen un segon per esdeveniment. Combinar validacions relacionades en un sol hook redueix l'overhead.
Patrons Avançats
Més enllà de l'automatització bàsica, els hooks permeten una personalització sofisticada del flux de treball.
Cadena de Hooks Amb Estat
Els hooks poden mantenir l'estat entre execucions utilitzant fitxers o bases de dades. Un hook PostToolUse podria registrar operacions exitoses que un hook PreToolUse valida posteriorment:
| #!/bin/bash # Registra les edicions exitoses echo “${toolInput.path}” >> .claude/edit-history.txt |
Un hook PreToolUse acompanyant podria comprovar aquest historial per prevenir operacions redundants o fer complir restriccions d'ordre.
Activació Condicional de Hooks
Les variables d'entorn controlen el comportament dels hooks en temps d'execució. Establir CLAUDE_SKIP_HOOKS=1 desactiva els hooks per a situacions d'emergència.
Els mateixos hooks poden comprovar les banderes d'entorn:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Aplica validació estricta exit 1 fi exit 0 |
Això permet un comportament de mode de desenvolupament vs. mode de producció sense canvis de configuració.
Validació en Múltiples Etapes
Els hooks PreToolUse poden implementar validació multi-nivell on el codi de sortida 2 permet a Claude continuar amb advertències:
- Fallades dures (sortida 1): Bloquejar operacions perilloses
- Advertències suaus (sortida 2): Alertar a Claude per reconsiderar
- Passar amb context (sortida 0 + JSON): Proporcionar informació addicional
Això crea un espectre de validació més matisat que un simple binari permet/denega.
Integració amb CI/CD
Segons la documentació oficial d'integració de plataformes, Claude Code s'executa en entorns CI/CD per a la revisió automàtica de codi i la triatge d'incidències. Els hooks amplien aquesta automatització.
Els fluxos de treball de GitHub Actions poden definir hooks que fan complir les polítiques de l'equip durant sessions automatitzades:
| – name: Executar Claude Code amb hooks estrictes env: STRICT_MODE: 1 run: | claude “Revisa aquest PR i suggereix millores” |
La bandera STRICT_MODE activa la lògica de validació condicional als scripts dels hooks. Això garanteix que les sessions automatitzades segueixin regles més rígides que el desenvolupament interactiu.
Generació de Rastre d'Auditoria
Els hooks PostToolUse en entorns CI creen registres d'auditoria detallats de totes les operacions de Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
El registre en segon pla no afecta el rendiment però proporciona un historial complet d'operacions per a complir normatives i depuració.
El Menú /hooks
Claude Code proporciona un comandament /hooks que mostra tots els hooks actius per a la sessió actual. Segons la documentació oficial, aquest menú mostra:
- Tipus d'esdeveniment del hook
- Patrons de comparació
- Ordre o punt final de la URL
- Si el hook s'executa en mode asíncron
- Font de configuració (projecte, usuari o plugin)
Seleccionar un hook mostra la seva configuració completa i permet deshabilitar-lo temporalment per a la sessió actual.
Deshabilitar o Eliminar Hooks
Els hooks es poden deshabilitar sense eliminar la configuració afegint "enabled": false a la definició del hook. Això preserva la configuració mentre impedeix l'execució.
Per eliminar permanentment un hook, esborra la seva entrada del fitxer settings.json corresponent. Els canvis entren en vigor en la propera reinici de sessió o quan s'executa /reload.
Hooks en Skills i Agents
Segons la documentació oficial, els hooks definits dins de les configuracions de skill o subagent s'apliquen només quan s'executa aquesta skill o agent. Això permet l'automatització especialitzada per a fluxos de treball específics.
Un subagent de depuració podria incloure hooks que registren totes les trucades a eines:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Aquests hooks només es disparen durant les sessions de l'agent de depuració, no durant l'operació normal de Claude Code.
Referenciar Scripts per Camí
Les ordres de hooks admeten tant camins relatius com absoluts. Els camins relatius es resolen des de laarrel del projecte on s'executa Claude Code.
Millors pràctiques de les discussions de la comunitat:
- Emmagatzemar scripts de hooks al directori .claude/hooks/
- Utilitzar noms descriptius: validate-typescript.sh no hook1.sh
- Fer els scripts executables: chmod +x .claude/hooks/*.sh
- Incloure una línia shebang: #!/usr/bin/env bash o #!/usr/bin/env python3
- Afegir gestió d'errors amb set -e en scripts bash
Capacitats Futura dels Hooks
Les sol·licituds de funcions a GitHub revelen millores plane jades i sol·licitades per als hooks:
- Hooks d'script en línia: Definir la lògica del hook directament a settings.json sense fitxers externs
- Integració d'eines MCP: Invocar eines de servidors MCP des de hooks en lloc d'ordres de shell
- Col·laboració multi-agent: Hooks que coordinen entre instàncies de Claude en diferents màquines
- Tipificació millorada: Definisions de tipus TypeScript per a esquemes d'entrada/sortida de hooks
Segons el problema de GitHub #4274, la sol·licitud de tipus de hook integrats (eina MCP, script en línia, trucada API) té com a objectiu simplificar la configuració i millorar l'experiència del desenvolupador.
Preguntes Freqüents
Els hooks poden prevenir que Claude executi ordres perilloses?
Sí. Els hooks PreToolUse poden bloquejar l'execució de qualsevol eina sortint amb el codi 1. Això inclou edicions de fitxers, execució d'ordres i trucades a eines MCP. El hook rep l'entrada completa de l'eina i pot validar contra qualsevol criteri abans de permetre l'operació.
Com depuro un hook que no funciona?
Habilita el registre de depuració amb CLAUDE_DEBUG=1 abans d'iniciar Claude Code. Comprova els logs de la sessió per obtenir detalls d'execució dels hooks incloent quins hooks van coincidir, l'entrada JSON enviada, la sortida stdout/stderr i els codis de sortida. Prova els hooks independentment enviant JSON de mostra a l'script del hook.
Els hooks funcionen amb totes les plataformes de Claude Code?
Els hooks funcionen a la CLI, l'aplicació d'escriptori i l'extensió VS Code. Segons la documentació oficial, els hooks s'executen on sigui que Claude Code s'executi amb accés al sistema de fitxers. Claude basat en navegador i les aplicacions mòbils no admeten hooks a causa de les restriccions de sandboxing.
Els hooks poden modificar les respostes o el comportament de Claude?
Els hooks de prompt injecten instruccions que influeixen en el comportament de Claude. Els hooks d'agent deleguen la gestió d'esdeveniments a subagents especialitzats. No obstant això, els hooks no poden modificar directament el text generat o el procés de raonament de Claude; funcionen proporcionant context i bloquejant operacions.
Quina és la diferència entre hooks asíncrons i síncrons?
Els hooks síncrons bloquegen el flux de treball de Claude fins a la finalització o el timeout. Els hooks asíncrons s'executen en segon pla sense bloquejar. Els hooks síncrons poden prevenir operacions mitjançant codis de sortida. Els hooks asíncrons no poden bloquejar ja que Claude continua abans que el hook es completi. Utilitza async per a registrar i notificacions, sync per a validació.
Com puc compartir hooks amb un equip?
Commit el fitxer .claude/settings.json al control de versions. Els hooks a nivell de projecte s'apliquen a tots els membres de l'equip que clonen el repositori. Per a polítiques a nivell d'organització, els equips poden mantenir un fitxer de configuració d'usuari compartit que els membres copien a ~/.claude/settings.json.
Els hooks HTTP poden trucar a API internes darrere de tallafocs?
Sí, si Claude Code s'executa en un entorn amb accés a la xarxa a aquestes API. Els hooks HTTP realitzen peticions POST estàndard des de la màquina que executa Claude Code. Els tallafocs corporatius i les VPN s'apliquen normalment. El proxy sandbox mencionat a la documentació controla l'exposició de variables d'entorn, no l'enrutament de xarxa.
Els hooks augmenten l'ús de tokens de Claude Code?
Els hooks de prompt injecten text al context de Claude, el qual consumeix tokens. Els hooks d'ordre i HTTP no afecten directament l'ús de tokens, però la seva sortida (missatges d'error, suggeriments) es converteix en part del context de la conversa. El codi de sortida 2 amb missatges explicatius afegeix més context que el codi de sortida 1 amb bloqueig simple.
Conclusió
Els hooks de Claude Code transformen l'assistent d'IA d'una eina potent a una plataforma de desenvolupament totalment automatitzada. El sistema d'esdeveniments proporciona punts d'intercepció durant tot el flux de treball de Claude, des de la inicialització de la sessió fins a la compactació del context.
Els hooks d'ordre gestionen la validació local i el format. Els hooks HTTP integren serveis externs i bases de dades. Els hooks de prompt modifiquen el comportament mitjançant la injecció de context. Junts, permeten patrons d'automatització que fan complir les polítiques d'equip, mantenen la qualitat del codi i s'integren amb la infraestructura de desenvolupament existent.
El sistema de comparació filtra els hooks a eines i patrons de fitxers específics. Els codis de sortida i la sortida JSON controlen el flux de decisions. L'execució asíncrona evita bloquejos en operacions lentes. L'esquema de configuració complet admet tot, des de la simple formatació automàtica fins a la complexa validació multi-etapa.
Comença amb hooks PostToolUse bàsics per a la formatació de codi. Afegeix validació PreToolUse a mesura que sorgeixen les polítiques. Experimenta amb hooks de prompt per a la modificació del comportament. Construeix integracions HTTP per a l'aplicació a nivell d'equip.
Consulta la documentació oficial de Claude Code per a la referència completa dels hooks i l'esquema de configuració actualitzat a mesura que s'enviïn noves capacitats.
