Los Hooks están diseñados para usuarios avanzados y equipos Enterprise que necesitan un control de grano fino sobre el comportamiento de Cascade. Requieren conocimientos básicos de scripting en shell.
- Registro y Analytics: Haz seguimiento de cada archivo leído, cambio de código, comando ejecutado, prompt de usuario o respuesta de Cascade para fines de cumplimiento y análisis de uso
- Controles de seguridad: Evita que Cascade acceda a archivos sensibles, ejecute comandos peligrosos o procese prompts que violen las políticas
- Aseguramiento de la calidad: Ejecuta linters, formatters o pruebas automáticamente después de modificaciones de código
- Flujos de trabajo personalizados: Integra con rastreadores de incidencias, sistemas de notificaciones o pipelines de despliegue
- Estandarización del equipo: Aplica estándares de codificación y mejores prácticas en toda tu organización
- Recibe contexto (detalles sobre la acción que se está realizando) en formato JSON por 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 comprobaciones de validación.
Los hooks se configuran en archivos JSON que pueden ubicarse en tres niveles diferentes. Cascade carga y fusiona los hooks de todas las ubicaciones, lo que ofrece a los equipos flexibilidad para distribuir y administrar las configuraciones de hooks.
Los hooks a nivel de sistema son ideales para definir políticas de toda la organización en máquinas de desarrollo compartidas. Por ejemplo, puedes usarlos para aplicar políticas de seguridad, requisitos de cumplimiento o flujos de trabajo obligatorios de revisión de código. Los equipos Enterprise también pueden configurar hooks desde el panel de control en la nube sin tener que gestionar archivos locales.
- macOS:
/Library/Application Support/Windsurf/hooks.json - Linux/WSL:
/etc/windsurf/hooks.json - Windows:
C:\ProgramData\Windsurf\hooks.json
- Windsurf IDE:
~/.codeium/windsurf/hooks.json - Plugin de JetBrains:
~/.codeium/hooks.json
- Ubicación:
.windsurf/hooks.jsonen la raíz de tu workspace
Los hooks de las tres ubicaciones se combinan. Si el mismo evento de hook está configurado en varias ubicaciones, todos los hooks se ejecutarán en este orden: sistema → usuario → workspace.
Acerca del parámetro
working_directory:- En workspaces con múltiples repositorios, el valor predeterminado es la raíz del repositorio en el que se está trabajando actualmente
- Las rutas relativas se resuelven desde la ubicación predeterminada (raíz del workspace o del repositorio)
- Se admiten rutas absolutas
- No se admite el uso de
~para la expansión del directorio personal
En los siguientes ejemplos, se omiten los campos comunes por brevedad. Hay doce tipos principales de eventos de hook:
Se activa antes de que Cascade lea un archivo de código. Puede bloquear la acción si el hook finaliza con el código 2.
Casos de uso: Restringir el acceso a archivos, registrar operaciones de lectura, verificar permisos
JSON de entrada:
file_path puede ser una ruta de directorio cuando Cascade lee un directorio de forma recursiva.
Se activa después de que Cascade lea correctamente un archivo de código.
Casos de uso: Registrar lecturas correctas, rastrear patrones de acceso a archivos
JSON de entrada:
file_path puede ser una ruta de directorio cuando Cascade lee un directorio de manera recursiva.
Se activa antes de que Cascade escriba o modifique un archivo de código. Esto puede bloquear la acción si el hook termina con el código 2.
Casos de uso: Evitar modificaciones en archivos protegidos, hacer copias de seguridad de archivos antes de aplicar cambios
Entrada JSON:
show_output no se aplica a este hook.
Se activa de forma asíncrona después de que Cascade completa una respuesta al mensaje de un usuario. Este hook recibe la respuesta completa de Cascade desde la última entrada del usuario.
Casos de uso: Registrar todas las respuestas de Cascade para fines de auditoría, analizar patrones de respuesta, enviar respuestas a sistemas externos para revisión de cumplimiento normativo
JSON de entrada:
response contiene el contenido en formato Markdown de la respuesta de Cascade desde la última entrada del usuario. Esto incluye respuestas del planificador, acciones de herramientas (lecturas y escrituras de archivos, comandos) y cualquier otro paso que haya realizado Cascade. También incluye información sobre qué reglas se activaron. Consulta el ejemplo Seguimiento de reglas activadas para ver cómo analizar el uso de reglas.
La opción de configuración show_output no se aplica a este hook.
Se activa de forma asíncrona después de que Cascade completa una respuesta al prompt de un usuario, similar a post_cascade_response. En lugar de proporcionar un resumen en markdown integrado, este hook escribe la transcripción completa de la conversación (desde el inicio de la conversación) 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 de Analytics
JSON de entrada:
transcript_path apunta a un archivo JSONL en ~/.windsurf/transcripts/{trajectory_id}.jsonl. Cada línea contiene un objeto JSON que representa un único paso en la conversación, con un campo type y otro status, además de datos específicos de ese paso. Por ejemplo:
0600. Windsurf limita automáticamente el directorio de transcripciones a 100 archivos, eliminando los más antiguos según la hora 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:
Se activa después de que se crea y configura un nuevo git worktree. El hook se ejecuta dentro del nuevo directorio del worktree.
Casos de uso: Copiar archivos
.env u otros archivos sin seguimiento al worktree, instalar dependencias, ejecutar scripts de configuración
Variables de entorno:
JSON de entrada:
Ten en cuenta que el usuario puede ver cualquier salida estándar y error estándar generados por los hooks en la interfaz de Cascade si
show_output es true.
Realiza un seguimiento de cada acción que Cascade lleva a cabo con fines de auditoría.
Configuración:
log_input.py):
block_read_access.py):
block_dangerous_commands.py):
block_bad_prompts.py):
log_cascade_response.py):
track_rules.py):
Always On- Reglas que siempre se incluyenModel Decision- Reglas cuyas descripciones se mostraron al modelo de IA para su aplicación condicionalManual- Reglas mencionadas explícitamente con @ en la entrada del usuarioGlobal- Reglas globales deglobal_rules.mdGlob- Reglas activadas por acceso a archivos que coinciden con patrones de tipo glob
Esto registra qué reglas fueron presentadas al modelo de IA o activadas por el acceso a archivos, pero no indica si el modelo de IA realmente siguió una regla. Las reglas que ya se han mostrado recientemente en la conversación se deduplican y puede que no vuelvan a aparecer hasta más adelante.
format_code.sh):
.windsurf/hooks.json):
hooks/setup_worktree.sh):
- Valide todas las entradas: Nunca confíe en el JSON de entrada sin validarlo, especialmente en lo referente a rutas de archivos y comandos.
- Use rutas absolutas: Utilice siempre rutas absolutas en la configuración de sus hooks para evitar ambigüedades.
- Proteja los datos sensibles: Evite registrar información sensible, como claves de API o credenciales.
- Revise los permisos: Asegúrese de que sus scripts de hooks tengan los permisos adecuados en el sistema de archivos.
- Audite antes del despliegue: Revise cada comando y script de hook antes de añadirlo a su configuración.
- Pruebe en aislamiento: Ejecute los hooks en un entorno de pruebas antes de habilitarlos en su máquina principal de desarrollo.
- Mantén los hooks rápidos: Los hooks lentos afectarán la capacidad de respuesta de Cascade. Procura tiempos de ejecución inferiores a 100 ms.
- Usa operaciones asíncronas: Para hooks no bloqueantes, considera enviar registros a una cola o base de datos de manera asíncrona.
- Filtra cuanto antes: Verifica el tipo de acción al inicio de tu script para evitar procesamiento innecesario.
- Valida siempre el JSON: Usa bloques try-catch para manejar entradas malformadas de forma adecuada.
- 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.
- Empieza con registros: Implementa primero un hook simple de logging 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.
- Verifica todas las rutas de código: Prueba tanto los casos de éxito como los de error en tus scripts.
- Cloud Dashboard - Configura los hooks mediante Team Settings en el panel de Windsurf
- System-Level Files - Implementa los hooks mediante MDM o herramientas de gestión de configuración
- Plan Enterprise
- Permiso
TEAM_SETTINGS_UPDATE
- Accede a Team Settings en el panel de Windsurf
- Busca la sección Cascade Hooks
- Introduce tu configuración de hooks en formato JSON
- Guarda los cambios
Cuando se combinan múltiples configuraciones de equipo, los hooks se agrupan por acción en lugar de sobrescribirse. Esto significa que los hooks de todas las configuraciones de equipo aplicables se ejecutarán conjuntamente.
hooks.json en estas ubicaciones específicas del sistema operativo:
macOS:
/usr/local/share/windsurf-hooks/ en sistemas Unix).
Los hooks a nivel del sistema tienen prioridad sobre los hooks del usuario y del workspace, y no pueden deshabilitarse por los usuarios finales sin permisos de root.
Los equipos de TI de Enterprise pueden desplegar hooks a nivel del sistema utilizando herramientas estándar:
Mobile Device Management (MDM)
- Jamf Pro (macOS) - Despliegue mediante perfiles de configuración o scripts
- Microsoft Intune (Windows/macOS) - Use scripts de PowerShell o despliegue de políticas
- Workspace ONE, Google Endpoint Management y otras soluciones MDM
- Ansible, Puppet, Chef, SaltStack - Use su automatización de infraestructura existente
- Scripts de despliegue personalizados - Scripts de shell, PowerShell o sus herramientas preferidas
Importante: Los hooks a nivel de sistema son gestionados íntegramente por tu equipo de TI o de seguridad. Windsurf no despliega ni administra archivos en rutas del sistema. Asegúrate de que tus equipos internos se encarguen del despliegue, las actualizaciones y el cumplimiento conforme a las políticas de tu organización.
- Integración con MCP: Obtén más información sobre el Model Context Protocol en Windsurf
- Workflows: Descubre cómo combinar hooks con Cascade Workflows
- Analytics: Realiza un seguimiento del uso de Cascade con Team Analytics