Hooks

Precedencia de permisos en PreToolUse

Hook dice "allow"
  + regla deny existe  → DENY (la regla gana)
  + regla ask existe   → Forzar diálogo de permiso
  + sin reglas         → ALLOW ✓

Hook dice "deny"       → DENY inmediato

Hook dice "ask"        → Forzar diálogo de permiso

Múltiples hooks: deny > ask > allow

Un hook allow NO anula reglas deny/ask de settings.json. Las reglas siempre ganan.

Async por configuración

{
  "type": "command",
  "command": "tarea-lenta.sh",
  "async": true
}

El hook se ejecuta en segundo plano. Claude continúa sin esperar.

Declaración async en tiempo de ejecución

El hook se declara async en tiempo de ejecución mediante su primera línea en stdout:

{"async": true, "asyncTimeout": 30}

El hook escribe en stdout:

{
  "prompt": "request-id-123",
  "message": "Elige el destino de deploy:",
  "options": [
    { "key": "staging",    "label": "Staging" },
    { "key": "production", "label": "Producción" }
  ]
}

Claude Code escribe de vuelta al stdin del hook:

{
  "prompt_response": "request-id-123",
  "selected": "staging"
}

Auto-formatear después de ediciones

// PostToolUse, matcher: "Write|Edit"
{
  "type": "command",
  "command": "prettier --write "$(cat | jq -r '.tool_input.file_path')"",
  "timeout": 10,
  "statusMessage": "Formateando..."
}

Bloquear comandos git peligrosos

// PreToolUse, matcher: "Bash", if: "Bash(git *)"
{
  "type": "command",
  "command": "CMD=$(cat|jq -r '.tool_input.command'); if echo "$CMD" | grep -qE 'force|reset --hard'; then echo 'Bloqueado' >&2; exit 2; fi"
}

Auto-aprobar permisos en CI

// PermissionRequest, matcher: "Bash"
{
  "type": "command",
  "command": "echo '{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}'"
}