Los hooks están diseñados para usuarios avanzados y equipos empresariales que necesitan un control preciso sobre el comportamiento de Cascade. Requieren conocimientos básicos de scripting de shell.
Qué puedes crear
- Registro y analítica: Supervisa cada archivo leído, cambio de código, comando ejecutado, prompt de usuario o respuesta de Cascade para el cumplimiento normativo y el análisis de uso
- Controles de seguridad: Impide que Cascade acceda a archivos sensibles, ejecute comandos peligrosos o procese prompts que infrinjan las políticas
- Garantía de calidad: Ejecuta linters, formateadores o pruebas automáticamente tras modificar el código
- Flujos de trabajo personalizados: Integra sistemas de seguimiento de incidencias, sistemas de notificaciones o pipelines de despliegue
- Estandarización del equipo: Aplica estándares de codificación y prácticas recomendadas en toda tu organización
Cómo funcionan los Hooks
- Recibe contexto (detalles sobre la acción que se está realizando) en formato JSON a través de la entrada estándar
- Ejecuta tu script: Python, Bash, Node.js o cualquier ejecutable
- Devuelve un resultado mediante el código de salida y los flujos de salida
2. Esto hace que los pre-hooks sean ideales para implementar políticas de seguridad o validaciones.
Configuración
A nivel del sistema
- macOS:
/Library/Application Support/Windsurf/hooks.json - Linux/WSL:
/etc/windsurf/hooks.json - Windows:
C:\ProgramData\Windsurf\hooks.json
Nivel de usuario
- Devin Desktop IDE:
~/.codeium/windsurf/hooks.json - Plugin de JetBrains:
~/.codeium/hooks.json
A nivel del espacio de trabajo
- Ubicación:
.windsurf/hooks.jsonen la raíz de tu espacio de trabajo
Los hooks de las tres ubicaciones se combinan. Si el mismo evento de hook está configurado en múltiples ubicaciones, todos los hooks se ejecutarán en este orden: sistema → usuario → espacio de trabajo.
Estructura básica
pre_read_code especifica tanto un comando para macOS/Linux como un comando de PowerShell para Windows. El hook post_write_code solo especifica command, por lo que se ejecutará en macOS/Linux y, en Windows, usará PowerShell como alternativa.
Opciones de configuración
Comportamiento en distintas plataformas
command y powershell permiten definir comandos adecuados para cada plataforma en una sola configuración. Esto resulta útil para equipos con entornos mixtos de macOS/Linux y Windows.
Acerca del parámetro
working_directory:- En espacios de trabajo con varios repos, el valor predeterminado es la raíz del repo en el que se está trabajando en ese momento
- Las rutas relativas se resuelven desde la ubicación predeterminada (espacio de trabajo o raíz del repo)
- Se admiten rutas absolutas
- No se admite usar
~para expandir el directorio de inicio
Eventos de hook
Estructura de entrada común
En los siguientes ejemplos, los campos comunes se omiten por brevedad. Hay doce tipos principales de eventos de hook:
pre_read_code
file_path puede ser la ruta de un directorio cuando Cascade lee ese directorio de forma recursiva.
post_read_code
file_path puede ser la ruta de un directorio cuando Cascade lee un directorio de forma recursiva.
pre_write_code
post_write_code
pre_run_command
post_run_command
pre_mcp_tool_use
post_mcp_tool_use
pre_user_prompt
show_output no es aplicable a este hook.
post_cascade_response
response contiene el contenido en formato Markdown de la respuesta de Cascade desde la última entrada del usuario. Esto incluye respuestas del planner, acciones de las herramientas (lecturas y escrituras de archivos, comandos) y cualquier otro paso que haya realizado Cascade. También incluye información sobre qué Rules se activaron. Consulta el ejemplo Tracking Triggered Rules para ver cómo analizar el uso de Rules.
La opción de configuración show_output no se aplica a este hook.
post_cascade_response_with_transcript
post_cascade_response. En lugar de proporcionar un resumen en markdown directamente, este hook escribe la transcripción completa de la conversación (desde su inicio) en un archivo JSONL local y proporciona la ruta del archivo.
Casos de uso: registro de auditoría y cumplimiento de Enterprise, seguimiento de contribuciones generadas por IA, envío de transcripciones a herramientas externas de observabilidad o analítica
JSON de entrada:
transcript_path apunta a un archivo JSONL en ~/.windsurf/transcripts/{trajectory_id}.jsonl. Cada línea es un objeto JSON que representa un único paso de la conversación, con los campos type y status, además de datos específicos de ese paso. Por ejemplo:
0600. Devin Desktop limita automáticamente el directorio de transcripciones a 100 archivos y elimina los más antiguos según su fecha de modificación.
La opción de configuración show_output no se aplica a este hook.
Esta tabla muestra las diferencias clave entre los hooks post_cascade_response y post_cascade_response_with_transcript:
post_setup_worktree
.env u otros archivos sin seguimiento al worktree, instalar dependencias, ejecutar scripts de configuración
Variables de entorno:
JSON de entrada:
Códigos de salida
Ten en cuenta que el usuario puede ver cualquier salida estándar y error estándar generados por hooks en la interfaz de usuario de Cascade si
show_output es true.
Casos de uso de ejemplo
Registro de todas las acciones de Cascade
log_input.py):
Restringir el acceso a los archivos
block_read_access.py):
Bloqueo de comandos peligrosos
block_dangerous_commands.py):
Bloqueo de prompts que incumplen las políticas
block_bad_prompts.py):
Registro de respuestas de Cascade
log_cascade_response.py):
Seguimiento de las Rules activadas
track_rules.py):
Always On- Rules que siempre se incluyenModel Decision- Rules cuyas descripciones se mostraron al modelo para su aplicación condicionalManual- Rules mencionadas explícitamente con @ en la entrada del usuarioGlobal- Rules globales deglobal_rules.mdGlob- Rules activadas por accesos a archivos que coinciden con patrones glob
Esto indica qué Rules se presentaron al modelo o se activaron por acceso a archivos, pero no si el modelo realmente siguió una Rule. Las Rules que ya se mostraron recientemente en la conversación se deduplican y es posible que no vuelvan a aparecer hasta más adelante.
Ejecutar formateadores de código tras las ediciones
format_code.sh):
Configuración de worktrees
.windsurf/hooks.json):
hooks/setup_worktree.sh):
Buenas prácticas
Seguridad
- Valida todas las entradas: Nunca confíes en el JSON de entrada sin validarlo, especialmente en rutas de archivos y comandos.
- Usa rutas absolutas: Usa siempre rutas absolutas en la configuración de tus hooks para evitar ambigüedades.
- Protege los datos sensibles: Evita registrar información sensible, como claves de API o credenciales.
- Revisa los permisos: Asegúrate de que los scripts de tus hooks tengan los permisos adecuados en el sistema de archivos.
- Audita antes del despliegue: Revisa cada comando y script de hook antes de agregarlo a tu configuración.
- Prueba de forma aislada: Ejecuta los hooks en un entorno de prueba antes de habilitarlos en tu equipo principal de desarrollo.
Consideraciones de rendimiento
- Mantén los hooks rápidos: Los hooks lentos afectarán la capacidad de respuesta de Cascade. Procura que los tiempos de ejecución sean inferiores a 100 ms.
- Usa operaciones asíncronas: Para hooks no bloqueantes, considera registrar la información en una cola o base de datos de forma asíncrona.
- Filtra desde el principio: Comprueba el tipo de acción al inicio de tu script para evitar procesamiento innecesario.
Manejo de errores
- Valida siempre el JSON: Usa bloques
try-catchpara gestionar correctamente las entradas malformadas. - Registra los errores correctamente: Escribe los errores en
stderrpara que sean visibles cuandoshow_outputesté habilitado. - Falla de forma segura: Si tu hook encuentra un error, considera si debe bloquear la acción o permitir que continúe.
Cómo probar tus Hooks
- Empieza con el registro: Comienza implementando un hook de registro simple para comprender el flujo de datos.
- Usa
show_output: true: Habilita la salida durante el desarrollo para ver qué hacen tus hooks. - Prueba el comportamiento de bloqueo: Verifica que el código de salida 2 bloquee correctamente las acciones en los pre-hooks.
- Comprueba todos los caminos de ejecución: Prueba tanto los escenarios de éxito como los de error en tus scripts.
Distribución empresarial
- Panel en la nube - Configura los hooks desde Team Settings en el panel de Devin Desktop
- Archivos del sistema - Implementa hooks mediante MDM o herramientas de gestión de configuración
Configuración del panel en la nube
- plan Enterprise
- permiso
TEAM_SETTINGS_UPDATE
- Ve a Team Settings en el dashboard de Devin Desktop
- Busca la sección Cascade Hooks
- Introduce la configuración de los hooks en formato JSON
- Guarda tus cambios
Cuando se combinan varias configuraciones de equipo, los hooks se combinan por acción en lugar de sobrescribirse. Esto significa que los hooks de todas las configuraciones de equipo aplicables se ejecutarán en conjunto.
Despliegue de archivos en el sistema
hooks.json en estas ubicaciones específicas del sistema operativo:
macOS:
/usr/local/share/windsurf-hooks/ en sistemas Unix).
Los hooks de nivel de sistema tienen prioridad sobre los hooks de usuario y del espacio de trabajo, y los usuarios finales no pueden deshabilitarlos sin permisos de root.
MDM y gestión de la configuración
- Jamf Pro (macOS) - Despliegue mediante perfiles de configuración o scripts
- Microsoft Intune (Windows/macOS) - Usa scripts de PowerShell o implementaciones de políticas
- Workspace ONE, Google Endpoint Management y otras soluciones de MDM
- Ansible, Puppet, Chef, SaltStack - Usa tu automatización de infraestructura existente
- Scripts de despliegue personalizados - Scripts de shell, PowerShell o las herramientas que prefieras
Verificación y auditoría
Importante: Tu equipo de TI o de seguridad gestiona por completo los hooks a nivel de sistema. Devin Desktop no instala ni gestiona archivos en rutas del sistema. Asegúrate de que tus equipos internos se encarguen del despliegue, las actualizaciones y el cumplimiento de las políticas de tu organización.
Hooks del espacio de trabajo para proyectos de equipo
Recursos adicionales
- Integración de MCP: Obtén más información sobre Model Context Protocol en Devin Desktop
- Flujos de trabajo: Descubre cómo combinar hooks con los flujos de trabajo de Cascade
- Análisis: Supervisa el uso de Cascade con Análisis del equipo

