Glosario de Claude Code
Hooks
Los hooks son comandos o endpoints definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code.
También llamado: claude code hooks, PreToolUse, PostToolUse, hook events
Los hooks son comandos de shell, endpoints HTTP o prompts de LLM definidos por el usuario que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code. La distinción clave es que, si bien las instrucciones de CLAUDE.md son contextuales y pueden ser ignoradas, los hooks son código que se ejecuta independientemente de las decisiones de Claude. Si una acción debe ocurrir en un punto fijo —antes de cada commit, después de cada edición de archivo— debe implementarse como un hook.
Los nombres de eventos verificados incluyen: SessionStart, SessionEnd, Setup, UserPromptSubmit, UserPromptExpansion, Stop, StopFailure, PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDenied, PreCompact, PostCompact, Notification, SubagentStart, SubagentStop, InstructionsLoaded y FileChanged.
La configuración sigue una estructura de tres niveles: seleccionar un evento de hook, agregar un grupo matcher para filtrar cuándo se dispara (por ejemplo, 'Bash'), y definir handlers. Los handlers pueden ser de tipo command, http, mcp_tool, prompt o agent. Las ubicaciones de configuración verificadas incluyen ~/.claude/settings.json (global), .claude/settings.json (específico del proyecto), .claude/settings.local.json (específico del proyecto y gitignored), el hooks/hooks.json de un plugin, y el frontmatter de skills o agentes (con alcance a la duración activa del componente).
La semántica del código de salida es crítica: un código de salida de 0 significa éxito, permitiendo a Claude Code analizar la salida JSON para decisiones posteriores. Un código de salida de 2 indica un error de bloqueo, impidiendo la llamada a la herramienta y mostrando stderr a Claude. Otros códigos de salida distintos de cero se tratan como errores no bloqueantes.
Crucialmente, un hook PreToolUse puede devolver una permissionDecision de deny para evitar que se ejecute una llamada a herramienta. Esto proporciona un mecanismo potente para aplicar restricciones o validar condiciones antes de que se tomen las acciones. Para gestionar hooks, la skill Hooks Management puede traducir lenguaje natural a configuraciones validadas, y la skill Debug Hooks ofrece un flujo de trabajo para solucionar problemas.