Hooks y Sistema de Permisos en Claude Code

Con gran poder viene gran responsabilidad • D3 Claude Code • 20% del examen CCA-F

Spider-sense y la tía May: control total del agente

Peter Parker no espera que el puño del Duende Verde le llegue a la cara para reaccionar. El spider-sense se activa ANTES. Le da una fracción de segundo de ventaja — puede esquivar, bloquear, o decidir que en este caso específico conviene recibir el golpe para proteger a alguien más.

Eso son los hooks de Claude Code: código que se ejecuta antes o después de que el agente use una herramienta. Interceptan la acción, la evalúan, y deciden si procede o no.

Y el sistema de permisos es la tía May. Peter tiene superpoderes, pero la tía May le marcó límites. No porque no confíe en él — sino porque entiende que el poder sin estructura crea consecuencias no deseadas. Claude Code puede acceder a tu filesystem, ejecutar comandos de shell, llamar APIs. El settings.json define exactamente qué puede hacer solo, qué necesita confirmación, y qué está absolutamente prohibido.

En este video combinamos las dos herramientas para construir un agente con poderes reales y controles reales. Un spider-sense que bloquea comandos peligrosos. Una tía May configurada con precisión de glob. Y un modo detective para cuando querés análisis sin acción.

Los 4 hooks: cuándo se ejecutan y qué pueden hacer

Un hook en Claude Code es un script externo — Python, bash, Node — que Claude Code invoca en momentos específicos del agentic loop. El script recibe el contexto de la acción por stdin (JSON) y devuelve su decisión por stdout (JSON).

El spider-sense es PreToolUse. Si Peter siente el golpe venir y decide esquivarlo, el golpe nunca llega. Eso es {"decision": "block"}. Si decide absorberlo, el golpe ocurre y después analiza. Eso es PostToolUse.

¿Qué recibe y devuelve un hook?

Cuando Claude Code va a ejecutar una herramienta, antes de hacerlo serializa la información a JSON y se la pasa por stdin a tu script. El script lee ese JSON, evalúa, y responde por stdout:

stdin JSON que recibe un hook PreToolUse

Y los campos que puede incluir el output del hook:

Configurar hooks en settings.json

Los hooks se registran en .claude/settings.json. La estructura tiene dos niveles: el tipo de hook, y dentro de cada tipo, una lista de matchers con los scripts a ejecutar:

.claude/settings.json — hooks configurados

Tres conceptos clave de la configuración:

El matcher es una expresión regular que filtra a qué herramientas aplica el hook. "Bash" aplica solo a llamadas de shell, "Write" solo a escritura de archivos, ".*" aplica a todo, "Bash|Write" aplica a ambas. Si no especificás matcher en Stop, aplica siempre.

Podés encadenar múltiples scripts para el mismo evento. Se ejecutan en orden. Si el primero bloquea, los siguientes no se ejecutan.

El tipo "command" es el único disponible actualmente — ejecuta un script externo. El script puede ser Python, bash, Node, o cualquier ejecutable en el sistema.

🎯 TRAMPA DE EXAMEN: El examen puede preguntar sobre el matcher. Recordá: es regex, no glob. "Bash" coincide exactamente con la tool Bash. "Bash|Write" coincide con Bash O Write. ".*" coincide con todo.

Sistema de permisos: la tía May del agente

El sistema de permisos controla qué herramientas puede usar Claude Code y con qué nivel de autonomía. Se configura en el mismo settings.json, en la sección permissions, con dos listas: allow y deny.

.claude/settings.json — permisos completos con glob patterns

Anatomía de los glob patterns: Bash(git ) permite cualquier comando git. Bash(git commit ) permite solo git commit. Write(.env) bloquea específicamente ese archivo. Write(/secrets/*) bloquea toda la carpeta. mcp__db__read_* permite solo las tools de lectura del MCP 'db'. La prioridad es siempre deny sobre allow cuando hay conflicto.

Architect mode: Peter en modo detective

Hay situaciones donde querés que Claude Code analice y planifique sin tocar nada. Para eso existe architect mode:

En architect mode Claude Code puede leer archivos y analizar el código, planificar cambios y explicar su razonamiento, hacer preguntas y pedir aclaraciones. Pero no puede escribir ni modificar archivos ni ejecutar comandos de shell.

Cuándo usarlo: revisiones de código antes de un refactor, auditorías de seguridad, planning de nuevas features. Peter analiza la escena del crimen sin tocar evidencia. Cuando el equipo aprueba el plan, salís de architect mode y ejecutás.

🎯 TRAMPA DE EXAMEN: El examen pregunta sobre architect mode como si fuera un permiso configurable. No lo es — es un flag de CLI (--mode architect). No se configura en settings.json.

Demo: spider_sense.py + audit_logger.py en acción

Acá está el hook PreToolUse completo — el spider-sense real. Lee el contexto de la tool por stdin, evalúa si es peligroso, y bloquea antes de que ocurra cualquier daño:

.claude/hooks/spider_sense.py — PreToolUse hook

print(json.dumps(result))

Y el hook PostToolUse que registra todo lo que el agente hace — sin bloquear, solo observando:

.claude/hooks/audit_logger.py — PostToolUse hook

Ahora el settings.json completo que une todo:

.claude/settings.json — configuración completa del proyecto

Y así se ve en la práctica cuando el spider-sense entra en acción:

Terminal — hook bloqueando en tiempo real

Resultado: rm -rf bloqueado por deny en permissions (primera capa). .env bloqueado por spider_sense.py (segunda capa). rm sin -rf sobre archivos no protegidos: aprobado y ejecutado. Cada acción registrada en .claude/audit.log por el PostToolUse hook. Peter no pierde sus poderes — solo opera dentro de los límites de la tía May.

Trampas de examen: lo que pregunta el CCA-F

🎯 TRAMPA DE EXAMEN: '¿Qué hook usarías para bloquear comandos sudo?' La respuesta es PreToolUse — es el ÚNICO que puede bloquear. Si decís PostToolUse, ya es tarde. Siempre PreToolUse para interceptar antes de la ejecución.

🎯 TRAMPA DE EXAMEN: '¿Qué pasa si un permiso aparece en allow Y en deny?' Deny siempre gana. La tía May tiene veto absoluto, sin importar lo que diga allow.

🎯 TRAMPA DE EXAMEN: '¿Cómo configurás architect mode?' No se configura en settings.json. Es un flag de CLI: claude --mode architect. El examen puede intentar confundirte con opciones de settings.

🎯 TRAMPA DE EXAMEN: '¿Qué recibe por stdin un hook PreToolUse?' Un JSON con hook_event_name, tool_name, tool_input (los argumentos de la herramienta), session_id, y transcript_path. No recibe el resultado — eso es PostToolUse.

🎯 TRAMPA DE EXAMEN: 'Tu agente debe revisar y planificar sin hacer cambios todavía. ¿Qué modo usás?' claude --mode architect. No es un hook ni un permiso — es el modo del agente.

🎯 TRAMPA DE EXAMEN: 'Si encadenás dos hooks PreToolUse y el primero bloquea, ¿qué pasa con el segundo?' No se ejecuta. Cuando un hook bloquea, la cadena se corta ahí.

Con gran poder viene gran responsabilidad

Uncle Ben tenía razón. Y no solo para Peter — para cualquier agente con acceso a herramientas reales.

Los hooks y el sistema de permisos no limitan la utilidad de Claude Code. La hacen sostenible. Un agente que puede hacer todo sin control no es más útil — es más riesgoso. El spider-sense y la tía May son lo que permiten darle al agente acceso real a tu entorno sin perder el control de lo que hace.

Resumen para el examen: 4 hooks (PreToolUse único que bloquea, los otros 3 observan). settings.json con permissions.allow + permissions.deny (deny siempre gana) + hooks con matcher regex. architect mode = claude --mode architect = solo lectura y planificación.

En M3V3 vemos cómo configurar y usar MCP servers desde Claude Code: cómo registrarlos en settings.json, cómo verificarlos con /mcp, y cómo el agente decide cuándo usarlos. El multi-verse de herramientas externas te espera.