Capítulo 4: Hooks y Personalización

Los hooks permiten interceptar y automatizar acciones en Claude Code, desde validar herramientas hasta auto-aprobar permisos.

Objetivos del Capítulo

• Entender los tipos de hooks disponibles
• Crear hooks personalizados
• Configurar permisos avanzados con wildcards
• Automatizar flujos de trabajo con hooks

Tipos de Hooks

Claude Code soporta varios tipos de hooks:

Hook	Momento	Uso
PreToolUse	Antes de ejecutar herramienta	Validar, modificar, pedir confirmación
PostToolUse	Después de ejecutar herramienta	Logging, notificaciones
Stop	Cuando Claude termina	Cleanup, resumen
Notification	Eventos del sistema	Alertas, logging
PermissionRequest	Al pedir permisos	Auto-aprobar/denegar

Configurar Hooks

Comando /hooks

# Ver hooks configurados
/hooks

# Configurar hooks interactivamente
/hooks
# Navegar con flechas y seleccionar

Hooks en settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "match": "Bash(rm *)",
        "action": "deny",
        "message": "Comando de eliminación bloqueado"
      },
      {
        "match": "Write",
        "action": "ask"
      }
    ],
    "PostToolUse": [
      {
        "match": "Bash(git commit*)",
        "action": "log",
        "path": "./commits.log"
      }
    ],
    "Stop": [
      {
        "action": "prompt",
        "prompt": "Resume lo que hiciste"
      }
    ]
  }
}

PreToolUse Hooks

Interceptan herramientas antes de ejecutarse.

Acciones Disponibles

Acción	Descripción
allow	Permitir sin preguntar
deny	Bloquear ejecución
ask	Pedir confirmación
modify	Modificar input

Ejemplos de PreToolUse

{
  "hooks": {
    "PreToolUse": [
      {
        "match": "Bash(npm install*)",
        "action": "ask",
        "message": "¿Instalar dependencia?"
      },
      {
        "match": "Write(*.env*)",
        "action": "deny",
        "message": "No se puede escribir archivos .env"
      },
      {
        "match": "Bash(git push*)",
        "action": "ask"
      }
    ]
  }
}

Modificar Input

PreToolUse puede modificar el input de una herramienta:

{
  "hooks": {
    "PreToolUse": [
      {
        "match": "Bash(npm *)",
        "action": "modify",
        "updatedInput": {
          "command": "npm --prefer-offline ${originalCommand}"
        }
      }
    ]
  }
}

Hook con once: true

Para hooks que solo deben ejecutarse una vez:

{
  "hooks": {
    "PreToolUse": [
      {
        "match": "Bash(npm install)",
        "action": "ask",
        "message": "Primera instalación de dependencias",
        "once": true
      }
    ]
  }
}

PostToolUse Hooks

Se ejecutan después de que una herramienta termina.

Ejemplos de PostToolUse

{
  "hooks": {
    "PostToolUse": [
      {
        "match": "Write",
        "action": "log",
        "path": "./file-changes.log"
      },
      {
        "match": "Bash(git *)",
        "action": "notify"
      }
    ]
  }
}

tool_use_id

Desde v2.0.43, los hooks incluyen tool_use_id para identificación:

{
  "hooks": {
    "PostToolUse": [
      {
        "match": "*",
        "action": "custom",
        "handler": "./hooks/log-tool.js"
      }
    ]
  }
}

Stop Hooks

Se ejecutan cuando Claude termina una tarea.

Prompt-based Stop Hooks

{
  "hooks": {
    "Stop": [
      {
        "action": "prompt",
        "prompt": "Resume brevemente lo que hiciste"
      }
    ]
  }
}

Stop Hook con Modelo Específico

{
  "hooks": {
    "Stop": [
      {
        "action": "prompt",
        "prompt": "Genera un changelog de los cambios",
        "model": "haiku"
      }
    ]
  }
}

PermissionRequest Hook

Auto-aprueba o deniega permisos automáticamente.

{
  "hooks": {
    "PermissionRequest": [
      {
        "match": "Read(*)",
        "action": "allow"
      },
      {
        "match": "Write(*.test.*)",
        "action": "allow"
      },
      {
        "match": "Bash(npm test*)",
        "action": "allow"
      },
      {
        "match": "Bash(rm *)",
        "action": "deny"
      }
    ]
  }
}

Hooks en Skills y Agentes

Los skills y agentes pueden definir sus propios hooks:

---
name: safe-deploy
description: Deploy seguro con validaciones
hooks:
  PreToolUse:
    - match: Bash(npm run deploy)
      action: ask
      message: "¿Confirmas deploy a producción?"
  PostToolUse:
    - match: Bash(npm run deploy)
      action: notify
  Stop:
    - action: prompt
      prompt: "Genera reporte de deploy"
---

Permisos Avanzados

Wildcards en Permisos

Desde v2.1.0, puedes usar wildcards en permisos:

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(* install)",
      "Bash(git * main)",
      "mcp__github__*",
      "Read(*)",
      "Write(src/*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(* --force)",
      "Write(*.env*)"
    ]
  }
}

Patrones de Matching

Patrón	Descripción
*	Cualquier texto
Bash(npm *)	npm seguido de cualquier cosa
Bash(* install)	Cualquier cosa terminando en install
Write(src/*)	Escribir en src/
mcp__server__*	Todos los tools de un MCP server

Deshabilitar Agentes

{
  "disallowedTools": [
    "Task(Explore)",
    "Task(Plan)"
  ]
}

Hooks Personalizados (JavaScript)

Puedes crear hooks en JavaScript para lógica compleja:

// .claude/hooks/validate-commit.js
module.exports = {
  PreToolUse: async (context) => {
    if (context.tool === 'Bash' && context.input.includes('git commit')) {
      const message = context.input.match(/-m "(.+)"/)?.[1];

      if (!message || message.length < 10) {
        return {
          action: 'deny',
          message: 'El mensaje de commit debe tener al menos 10 caracteres'
        };
      }
    }
    return { action: 'allow' };
  }
};

Registrar Hook JavaScript

{
  "hooks": {
    "PreToolUse": [
      {
        "handler": "./.claude/hooks/validate-commit.js"
      }
    ]
  }
}

Notificaciones

Notification Hooks

{
  "hooks": {
    "Notification": [
      {
        "match": "error",
        "action": "alert"
      },
      {
        "match": "complete",
        "action": "sound"
      }
    ]
  }
}

Matcher Values

Los hooks de notificación soportan varios matchers:

Matcher	Descripción
error	Errores del sistema
complete	Tarea completada
permission	Solicitud de permiso
tool	Uso de herramienta

Debugging de Hooks

# Modo debug para ver hooks ejecutándose
claude --debug

# Ver hooks configurados
/hooks

# Buscar hooks por tool
/permissions
# Usa / para filtrar

Resumen

En este capítulo aprendiste:

• Los tipos de hooks disponibles
• Cómo configurar PreToolUse, PostToolUse y Stop hooks
• Permisos avanzados con wildcards
• Crear hooks personalizados en JavaScript
• Auto-aprobar permisos con PermissionRequest

Próximo Capítulo

En el siguiente capítulo exploraremos Claude in Chrome:

• Automatización del navegador
• Integración con la extensión
• Casos de uso prácticos

Siguiente: Capítulo 5 - Claude in Chrome →