Cascade Hooks

Les Cascade Hooks vous permettent d’exécuter des commandes shell personnalisées à des moments clés du workflow de Cascade. Cette puissante fonctionnalité d’extensibilité vous permet de consigner des opérations, d’appliquer des garde-fous, d’exécuter des contrôles de validation ou de vous intégrer à des systèmes externes.

Les Hooks sont conçus pour les utilisateurs avancés et les équipes Enterprise qui ont besoin d’un contrôle précis sur le comportement de Cascade. Ils nécessitent des connaissances de base en scripting shell.

Ce que vous pouvez créer

Les hooks ouvrent un large éventail de fonctions d’automatisation et de gouvernance :

Journalisation et Analytics : suivez chaque fichier lu, chaque modification de code, chaque commande exécutée, chaque invite utilisateur ou chaque réponse de Cascade pour la conformité et l’analyse de l’usage
Contrôles de sécurité : empêchez Cascade d’accéder à des fichiers sensibles, d’exécuter des commandes dangereuses ou de traiter des invites qui enfreignent les politiques
Assurance qualité : exécutez automatiquement des linters, des formateurs ou des tests après des modifications de code
Workflows personnalisés : intégrez-vous aux outils de suivi d’incidents, aux systèmes de notification ou aux pipelines de déploiement
Standardisation d’équipe : appliquez des normes de codage et des meilleures pratiques dans toute votre organisation

Fonctionnement des hooks

Les hooks sont des commandes de shell qui s’exécutent automatiquement lors d’actions Cascade spécifiques. Chaque hook :

Reçoit un contexte (des détails sur l’action en cours) au format JSON via l’entrée standard
Exécute votre script — Python, Bash, Node.js ou tout exécutable
Renvoie un résultat via le code de sortie et les flux de sortie

Pour les pré-hooks (exécutés avant une action), votre script peut bloquer l’action en se terminant avec le code de sortie 2. Les pré-hooks sont donc idéaux pour appliquer des politiques de sécurité ou effectuer des validations.

Configuration

Les hooks sont configurés dans des fichiers JSON pouvant être placés à trois niveaux différents. Cascade charge et fusionne les hooks à partir de tous ces emplacements, offrant aux équipes la flexibilité nécessaire pour distribuer et gérer les configurations de hooks.

Niveau système

Les hooks au niveau système sont idéaux pour des politiques à l’échelle de l’organisation, appliquées sur des machines de développement partagées. Par exemple, vous pouvez les utiliser pour appliquer des politiques de sécurité, des exigences de conformité ou des workflows de revue de code obligatoires. Les équipes Enterprise peuvent également configurer des hooks via le cloud dashboard sans avoir à gérer de fichiers locaux.

macOS : /Library/Application Support/Windsurf/hooks.json
Linux/WSL : /etc/windsurf/hooks.json
Windows : C:\ProgramData\Windsurf\hooks.json

Niveau utilisateur

Les hooks au niveau utilisateur sont parfaits pour des préférences personnelles et des workflows optionnels.

Emplacement : ~/.codeium/windsurf/hooks.json
Plugin JetBrains : ~/.codeium/hooks.json

Au niveau du workspace

Les hooks au niveau du workspace permettent aux équipes de versionner des politiques propres au projet aux côtés de leur code. Ils peuvent inclure des règles de validation personnalisées, des intégrations spécifiques au projet ou des workflows propres à l’équipe.

Emplacement : .windsurf/hooks.json à la racine de votre workspace

Les hooks provenant des trois emplacements sont fusionnés. Si le même événement de hook est configuré à plusieurs emplacements, tous les hooks s’exécuteront dans l’ordre : système → utilisateur → workspace.

Structure de base

Voici un exemple de la structure de base de la configuration des hooks :

{
  "hooks": {
    "pre_read_code": [
      {
        "command": "python3 /path/to/your/script.py",
        "show_output": true
      }
    ],
    "post_write_code": [
      {
        "command": "python3 /path/to/another/script.py",
        "show_output": true
      }
    ]
  }
}

Options de configuration

Chaque hook accepte les paramètres suivants :

Paramètre	Type	Description
`command`	string	La commande shell à exécuter. Peut être n’importe quel exécutable valide avec des arguments.
`show_output`	boolean	Indique s’il faut afficher la sortie stdout/stderr du hook dans l’interface Cascade visible par l’utilisateur. Utile pour le débogage.
`working_directory`	string	Facultatif. Le répertoire à partir duquel exécuter la commande. Par défaut, la racine de votre workspace.

À propos du paramètre working_directory :

Dans les workspaces comportant plusieurs dépôts, la valeur par défaut est la racine du dépôt actuellement en cours d’utilisation
Les chemins relatifs sont résolus à partir de l’emplacement par défaut (racine du workspace ou du dépôt)
Les chemins absolus sont pris en charge
L’utilisation de ~ pour développer le chemin vers le répertoire personnel n’est pas prise en charge

Événements de hooks

Cascade propose douze événements de hooks couvrant les actions les plus critiques du workflow de l’agent.

Structure d’entrée commune

Tous les hooks reçoivent un objet JSON avec les champs communs suivants :

Champ	Type	Description
`agent_action_name`	string	Nom de l’événement du hook (p. ex. « pre_read_code », « post_write_code »)
`trajectory_id`	string	Identifiant unique de l’ensemble de la conversation Cascade
`execution_id`	string	Identifiant unique du tour de l’agent
`timestamp`	string	Horodatage ISO 8601 au moment du déclenchement du hook
`tool_info`	object	Informations spécifiques à l’événement (varie selon le type de hook)

Dans les exemples suivants, les champs communs sont omis pour plus de concision. Il existe douze grands types d’événements de hook :

pre_read_code

Déclenché avant que Cascade ne lise un fichier de code. L’action peut être bloquée si le hook se termine avec le code 2. Cas d’usage : Restreindre l’accès aux fichiers, consigner les opérations de lecture, vérifier les autorisations JSON d’entrée :

{
  "agent_action_name": "pre_read_code",
  "tool_info": {
    "file_path": "/Users/yourname/project/file.py"
  }
}

Ce file_path peut être un chemin de répertoire lorsque Cascade parcourt un répertoire de façon récursive.

post_read_code

Déclenché après que Cascade a lu un fichier de code avec succès. Cas d’usage : consigner les lectures réussies, suivre les schémas d’accès aux fichiers JSON d’entrée :

{
  "agent_action_name": "post_read_code",
  "tool_info": {
    "file_path": "/Users/votrenom/projet/fichier.py"
  }
}

Ce file_path peut être un chemin de répertoire lorsque Cascade lit un répertoire de façon récursive.

pre_write_code

Déclenché avant que Cascade n’écrive ou ne modifie un fichier de code. Cela peut bloquer l’action si le hook se termine avec le code 2. Cas d’utilisation : Empêcher les modifications de fichiers protégés, sauvegarder les fichiers avant les changements Input JSON:

{
  "agent_action_name": "pre_write_code",
  "tool_info": {
    "file_path": "/Users/yourname/project/file.py",
    "edits": [
      {
        "old_string": "def old_function():\n    pass",
        "new_string": "def new_function():\n    return True"
      }
    ]
  }
}

post_write_code

Déclenché après que Cascade a écrit ou modifié un fichier de code. Cas d’utilisation : Exécuter des linters, des formateurs ou des tests ; consigner les modifications de code JSON d’entrée:

{
  "agent_action_name": "post_write_code",
  "tool_info": {
    "file_path": "/Users/nomutilisateur/projet/fichier.py",
    "edits": [
      {
        "old_string": "import os",
        "new_string": "import os\nimport sys"
      }
    ]
  }
}

pre_run_command

Déclenché avant que Cascade n’exécute une commande dans le terminal. L’action peut être bloquée si le hook se termine avec le code 2. Cas d’usage : Bloquer les commandes dangereuses, consigner toutes les exécutions de commandes, ajouter des contrôles de sécurité JSON d’entrée :

{
  "agent_action_name": "pre_run_command",
  "tool_info": {
    "command_line": "npm install package-name",
    "cwd": "/Users/yourname/project"
  }
}

post_run_command

Déclenché après l’exécution d’une commande de terminal par Cascade. Cas d’usage : journaliser les résultats de la commande, déclencher des actions ultérieures JSON d’entrée :

{
  "agent_action_name": "post_run_command",
  "tool_info": {
    "command_line": "npm install package-name",
    "cwd": "/Users/yourname/project"
  }
}

pre_mcp_tool_use

Déclenché avant que Cascade n’invoque un outil MCP (Model Context Protocol). L’action peut être bloquée si le hook se termine avec le code 2. Cas d’usage : consigner l’utilisation de MCP, restreindre les outils MCP autorisés JSON d’entrée :

{
  "agent_action_name": "pre_mcp_tool_use",
  "tool_info": {
    "mcp_server_name": "github",
    "mcp_tool_arguments": {
      "owner": "code-owner",
      "repo": "my-cool-repo",
      "title": "Signalement de bug",
      "body": "Description du bug ici"
    },
    "mcp_tool_name": "create_issue"
  }
}

post_mcp_tool_use

Déclenché après que Cascade a invoqué avec succès un outil MCP. Cas d’usage : consigner les opérations MCP, suivre l’utilisation de l’API, afficher les résultats MCP JSON d’entrée :

{
  "agent_action_name": "post_mcp_tool_use",
  "tool_info": {
    "mcp_result": "...",
    "mcp_server_name": "github",
    "mcp_tool_arguments": {
      "owner": "code-owner",
      "perPage": 1,
      "repo": "my-cool-repo",
      "sha": "main"
    },
    "mcp_tool_name": "list_commits"
  }
}

pre_user_prompt

Déclenché avant que Cascade ne traite le texte de la requête d’un utilisateur. Cela peut bloquer l’action si le hook se termine avec le code 2. Cas d’utilisation : Journaliser toutes les requêtes des utilisateurs à des fins d’audit, bloquer les requêtes potentiellement dangereuses ou non conformes aux règles JSON d’entrée :

{
  "agent_action_name": "pre_user_prompt",
  "tool_info": {
    "user_prompt": "can you run the echo hello command"
  }
}

L’option de configuration show_output ne s’applique pas à ce hook.

post_cascade_response

Déclenché de manière asynchrone après que Cascade a terminé de répondre à la requête d’un utilisateur. Ce hook reçoit l’intégralité de la réponse générée par Cascade depuis la dernière saisie de l’utilisateur. Cas d’utilisation : journaliser toutes les réponses de Cascade pour audit, analyser les schémas de réponse, envoyer les réponses à des systèmes externes pour examen de conformité JSON d’entrée :

{
  "agent_action_name": "post_cascade_response",
  "tool_info": {
    "response": "### Planner Response\n\nI'll help you create that file.\n\n*Created file `/path/to/file.py`*\n\n### Planner Response\n\nThe file has been created successfully."
  }
}

Le champ response contient le contenu au format Markdown de la réponse de Cascade depuis la dernière saisie de l’utilisateur. Cela inclut les réponses du planificateur, les actions d’outils (lectures et écritures de fichiers, commandes), ainsi que toute autre étape effectuée par Cascade. Il inclut également des informations sur les règles qui ont été déclenchées. Voir l’exemple Suivi des règles déclenchées pour savoir comment analyser l’utilisation des règles. L’option de configuration show_output ne s’applique pas à ce hook.

Le contenu de response est dérivé des données de trajectoire et peut contenir des informations sensibles provenant de votre base de code ou de vos conversations. Traitez ces données conformément aux politiques de sécurité et de confidentialité de votre organisation.

post_cascade_response_with_transcript

Déclenché de manière asynchrone après que Cascade a terminé une réponse à l’invite d’un utilisateur, similaire à post_cascade_response. Au lieu de fournir un résumé markdown intégré, ce hook écrit la transcription complète de la conversation (depuis le début de la conversation) dans un fichier JSONL local et fournit le chemin du fichier. Cas d’usage : journalisation d’audit et de conformité pour Enterprise, suivi des contributions générées par l’IA, envoi des transcriptions vers des outils externes d’observabilité ou d’Analytics JSON d’entrée :

{
  "agent_action_name": "post_cascade_response_with_transcript",
  "tool_info": {
    "transcript_path": "/Users/yourname/.windsurf/transcripts/{trajectory_id}.jsonl"
  }
}

Le transcript_path pointe vers un fichier JSONL situé à ~/.windsurf/transcripts/{trajectory_id}.jsonl. Chaque ligne est un objet JSON représentant une étape de la conversation, avec des champs type et status, ainsi que des données propres à cette étape. Par exemple :

{"status":"done","type":"user_input","user_input":{"rules_applied":{"always_on":["my-rule.md"]},"user_response":"create a hello world file"}}
{"planner_response":{"response":"I'll create a hello world file for you."},"status":"done","type":"planner_response"}
{"code_action":{"new_content":"print('hello world')\n","path":"/path/to/file.py"},"status":"done","type":"code_action"}
{"planner_response":{"response":"I created the file for you."},"status":"done","type":"planner_response"}

La transcription inclut des données détaillées, détenues par le client, telles que le contenu des fichiers, les sorties de commande, les arguments des outils, les résultats de recherche, ainsi que les règles qui ont été appliquées. Veuillez noter que la structure exacte de chaque étape peut changer dans de futures versions ; veillez donc à rendre tous les consommateurs de hooks résilients à ces évolutions. Les fichiers de transcription sont écrits avec les autorisations 0600. Windsurf limite automatiquement le répertoire de transcriptions à 100 fichiers, en supprimant les plus anciens selon leur date de modification. L’option de configuration show_output ne s’applique pas à ce hook. Ce tableau présente les différences clés entre les hooks post_cascade_response et post_cascade_response_with_transcript :

	`post_cascade_response`	`post_cascade_response_with_transcript`
Data scope	Uniquement les étapes depuis la dernière entrée utilisateur	L’ensemble de la conversation depuis le début
Format	Résumé en Markdown dans `tool_info.response`	Fichier JSONL structuré à l’emplacement `tool_info.transcript_path`
Detail level	Résumé condensé, lisible par un humain	Données détaillées, lisibles par une machine (contenu de fichiers, sorties de commande, etc.)
Delivery	En ligne via JSON sur stdin	Fichier sur disque (`~/.windsurf/transcripts/`)

Les fichiers de transcription contiendront des informations sensibles provenant de votre base de code, y compris le contenu des fichiers, les sorties de commande et l’historique des conversations. Traitez ces fichiers conformément aux politiques de sécurité et de confidentialité de votre organisation.

post_setup_worktree

Déclenché après la création et la configuration d’un nouveau git worktree. Le hook est exécuté dans le répertoire du nouveau worktree. Cas d’utilisation : Copier les fichiers .env ou d’autres fichiers non suivis dans le worktree, installer les dépendances, exécuter des scripts de configuration Variables d’environnement :

Variable	Description
`$ROOT_WORKSPACE_PATH`	Le chemin absolu vers le workspace d’origine. Utilisez-le pour accéder aux fichiers ou exécuter des commandes relativement au dépôt d’origine.

JSON d’entrée :

{
  "agent_action_name": "post_setup_worktree",
  "tool_info": {
    "worktree_path": "/Users/me/.windsurf/worktrees/my-repo/abmy-repo-c123",
    "root_workspace_path": "/Users/me/projects/my-repo"
  }
}

Codes de sortie

Vos scripts de hook communiquent leurs résultats via des codes de sortie :

Code de sortie	Signification	Effet
`0`	Réussite	L’action se poursuit normalement
`2`	Erreur bloquante	L’agent Cascade verra le message d’erreur sur stderr. Pour les pré-hooks, cela bloque l’action.
Tout autre	Erreur	L’action se poursuit normalement

Seuls les pré-hooks (pre_user_prompt, pre_read_code, pre_write_code, pre_run_command, pre_mcp_tool_use) peuvent bloquer des actions avec le code de sortie 2. Les post-hooks ne peuvent pas bloquer, puisque l’action a déjà eu lieu.

Gardez à l’esprit que l’utilisateur peut voir toute sortie standard et toute erreur standard générées par un hook dans l’interface Cascade si show_output est à true.

Exemples d’utilisations

Journalisation de toutes les actions Cascade

Enregistrez chaque action effectuée par Cascade à des fins d’audit. Config :

{
  "hooks": {
    "post_read_code": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ],
    "post_write_code": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ],
    "post_run_command": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ],
    "post_mcp_tool_use": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py",
        "show_output": true
      }
    ],
    "post_cascade_response": [
      {
        "command": "python3 /Users/yourname/hooks/log_input.py"
      }
    ]
  }
}

Script (log_input.py) :

#!/usr/bin/env python3

import sys
import json

def main():
    # Read the JSON data from stdin
    input_data = sys.stdin.read()
    
    # Parse the JSON
    try:
        data = json.loads(input_data)
        
        # Write formatted JSON to file
        with open("/Users/yourname/hooks/input.txt", "a") as f:
            f.write('\n' + '='*80 + '\n')
            f.write(json.dumps(data, indent=2, separators=(',', ': ')))
            f.write('\n')
    
        print(json.dumps(data, indent=2))
    except json.JSONDecodeError as e:
        print(f"Erreur lors de l'analyse du JSON : {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Ce script consigne chaque appel de hook dans un fichier journal, créant un historique d’audit de toutes les actions Cascade. Vous pouvez transformer les données d’entrée ou implémenter une logique personnalisée selon vos besoins.

Restriction de l’accès aux fichiers

Empêcher Cascade de lire des fichiers en dehors d’un répertoire spécifique. Configuration :

{
  "hooks": {
    "pre_read_code": [
      {
        "command": "python3 /Users/yourname/hooks/block_read_access.py",
        "show_output": true
      }
    ]
  }
}

Script (block_read_access.py) :

#!/usr/bin/env python3

import sys
import json

ALLOWED_PREFIX = "/Users/yourname/my-project/"

def main():
    # Lire les données JSON depuis stdin
    input_data = sys.stdin.read()

    # Analyser le JSON
    try:
        data = json.loads(input_data)

        if data.get("agent_action_name") == "pre_read_code":
            tool_info = data.get("tool_info", {})
            file_path = tool_info.get("file_path", "")
            
            if not file_path.startswith(ALLOWED_PREFIX):
                print(f"Accès refusé : Cascade ne peut lire que les fichiers sous {ALLOWED_PREFIX}", file=sys.stderr)
                sys.exit(2)  # Le code de sortie 2 bloque l'action
            
            print(f"Accès autorisé : {file_path}", file=sys.stdout)

    except json.JSONDecodeError as e:
        print(f"Erreur lors de l'analyse du JSON : {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Lorsque Cascade tente de lire un fichier en dehors du répertoire autorisé, ce hook bloque l’opération et affiche un message d’erreur.

Blocage des commandes dangereuses

Empêchez Cascade d’exécuter des commandes potentiellement dangereuses. Configuration :

{
  "hooks": {
    "pre_run_command": [
      {
        "command": "python3 /Users/yourname/hooks/block_dangerous_commands.py",
        "show_output": true
      }
    ]
  }
}

Script (block_dangerous_commands.py) :

#!/usr/bin/env python3

import sys
import json

DANGEROUS_COMMANDS = ["rm -rf", "sudo rm", "format", "del /f"]

def main():
    # Read the JSON data from stdin
    input_data = sys.stdin.read()

    # Parse the JSON
    try:
        data = json.loads(input_data)

        if data.get("agent_action_name") == "pre_run_command":
            tool_info = data.get("tool_info", {})
            command = tool_info.get("command_line", "")

            for dangerous_cmd in DANGEROUS_COMMANDS:
                if dangerous_cmd in command:
                    print(f"Commande bloquée : '{dangerous_cmd}' n'est pas autorisé pour des raisons de sécurité.", file=sys.stderr)
                    sys.exit(2)  # Exit code 2 blocks the command
            
            print(f"Command approved: {command}", file=sys.stdout)

    except json.JSONDecodeError as e:
        print(f"Error parsing JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Ce hook analyse les commandes à la recherche de schémas dangereux et les bloque avant leur exécution.

Blocage des prompts non conformes aux politiques

Empêchez les utilisateurs de soumettre des prompts qui enfreignent les politiques de l’organisation. Config :

{
  "hooks": {
    "pre_user_prompt": [
      {
        "command": "python3 /Users/yourname/hooks/block_bad_prompts.py"
      }
    ]
  }
}

Script (block_bad_prompts.py) :

#!/usr/bin/env python3

import sys
import json

BLOCKED_PATTERNS = [
    "something dangerous",
    "bypass security",
    "ignore previous instructions"
]

def main():
    # Lire les données JSON depuis stdin
    input_data = sys.stdin.read()

    # Parser le JSON
    try:
        data = json.loads(input_data)

        if data.get("agent_action_name") == "pre_user_prompt":
            tool_info = data.get("tool_info", {})
            user_prompt = tool_info.get("user_prompt", "").lower()

            for pattern in BLOCKED_PATTERNS:
                if pattern in user_prompt:
                    print(f"Prompt blocked: Contains prohibited content. The user cannot ask the agent to do bad things.", file=sys.stderr)
                    sys.exit(2)  # Le code de sortie 2 bloque le prompt

    except json.JSONDecodeError as e:
        print(f"Error parsing JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Ce hook analyse les prompts des utilisateurs avant leur traitement et bloque tous ceux qui contiennent des motifs interdits. Lorsqu’un prompt est bloqué, l’utilisateur voit s’afficher un message d’erreur dans l’interface de Cascade.

Journalisation des réponses de Cascade

Consignez toutes les réponses de Cascade pour les besoins d’audit de conformité ou d’Analytics. Configuration :

{
  "hooks": {
    "post_cascade_response": [
      {
        "command": "python3 /Users/yourname/hooks/log_cascade_response.py"
      }
    ]
  }
}

Script (log_cascade_response.py) :

#!/usr/bin/env python3

import sys
import json
from datetime import datetime

def main():
    # Lire les données JSON depuis stdin
    input_data = sys.stdin.read()

    # Analyser le JSON
    try:
        data = json.loads(input_data)

        if data.get("agent_action_name") == "post_cascade_response":
            tool_info = data.get("tool_info", {})
            cascade_response = tool_info.get("response", "")
            trajectory_id = data.get("trajectory_id", "unknown")
            timestamp = data.get("timestamp", datetime.now().isoformat())

            # Enregistrer dans un fichier
            with open("/Users/yourname/hooks/cascade_responses.log", "a") as f:
                f.write(f"\n{'='*80}\n")
                f.write(f"Timestamp: {timestamp}\n")
                f.write(f"Trajectory ID: {trajectory_id}\n")
                f.write(f"Response:\n{cascade_response}\n")

            print(f"Logged Cascade response for trajectory {trajectory_id}")

    except json.JSONDecodeError as e:
        print(f"Erreur lors de l'analyse du JSON : {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Ce hook enregistre chaque réponse de Cascade dans un fichier, créant une piste d’audit de l’ensemble du contenu généré par l’IA. Vous pouvez l’étendre pour envoyer des données vers des systèmes de logs externes, des bases de données ou des plateformes de conformité.

Suivi des règles déclenchées

Identifiez quelles règles ont été appliquées lors des interactions avec Cascade, à des fins d’observabilité et de mesure. Config :

{
  "hooks": {
    "post_cascade_response": [
      {
        "command": "python3 /Users/yourname/hooks/track_rules.py"
      }
    ]
  }
}

Script (track_rules.py) :

#!/usr/bin/env python3

import sys
import json
import re
from datetime import datetime

def extract_triggered_rules(response: str) -> dict:
    """
    Analyse les règles déclenchées à partir de la réponse Cascade.
    Les règles apparaissent sous la forme : - (Rule-Type) Triggered Rule: rule-filename.md
    """
    pattern = r"- \(([^)]+)\) Triggered Rule: (.+?)(?:\s*$)"
    rules = {}

    for match in re.finditer(pattern, response, re.MULTILINE):
        rule_type, rule_name = match.groups()
        if rule_type not in rules:
            rules[rule_type] = []
        rules[rule_type].append(rule_name)

    return rules

def main():
    input_data = sys.stdin.read()

    try:
        data = json.loads(input_data)

        if data.get("agent_action_name") == "post_cascade_response":
            response = data.get("tool_info", {}).get("response", "")
            trajectory_id = data.get("trajectory_id", "unknown")
            timestamp = data.get("timestamp", datetime.now().isoformat())

            rules = extract_triggered_rules(response)
            total_rules = sum(len(v) for v in rules.values())

            # Log to file
            with open("/Users/yourname/hooks/rules_usage.log", "a") as f:
                f.write(f"\n{'='*60}\n")
                f.write(f"Timestamp: {timestamp}\n")
                f.write(f"Trajectory: {trajectory_id}\n")
                f.write(f"Total rules triggered: {total_rules}\n")
                for rule_type, rule_list in rules.items():
                    if rule_list:
                        f.write(f"  {rule_type}: {', '.join(rule_list)}\n")

            print(f"Tracked {total_rules} triggered rules")

    except json.JSONDecodeError as e:
        print(f"Error parsing JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Types de règles :

Always On - Règles toujours actives
Model Decision - Règles dont les descriptions ont été présentées au modèle d’IA pour une application conditionnelle
Manual - Règles explicitement mentionnées avec @ dans la saisie utilisateur
Global - Règles globales provenant de global_rules.md
Glob - Règles déclenchées par l’accès à des fichiers correspondant à des motifs glob

Cela indique quelles règles ont été présentées au modèle d’IA ou déclenchées par l’accès aux fichiers, mais n’indique pas si le modèle d’IA a effectivement suivi une règle. Les règles déjà affichées récemment dans la conversation sont dédupliquées et peuvent ne pas réapparaître avant un certain temps.

Exécuter des formatteurs de code après modification

Formatez automatiquement les fichiers après que Cascade les a modifiés. Configuration :

{
  "hooks": {
    "post_write_code": [
      {
        "command": "bash /Users/yourname/hooks/format_code.sh",
        "show_output": false
      }
    ]
  }
}

Script (format_code.sh) :

#!/bin/bash

# Lire le JSON depuis stdin
input=$(cat)

# Extraire le chemin du fichier avec jq
file_path=$(echo "$input" | jq -r '.tool_info.file_path')

# Formater selon l'extension du fichier
if [[ "$file_path" == *.py ]]; then
    black "$file_path" 2>&1
    echo "Fichier Python formaté : $file_path"
elif [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
    prettier --write "$file_path" 2>&1
    echo "Fichier JS/TS formaté : $file_path"
elif [[ "$file_path" == *.go ]]; then
    gofmt -w "$file_path" 2>&1
    echo "Fichier Go formaté : $file_path"
fi

exit 0

Ce hook exécute automatiquement le formatteur adapté au type de fichier après chaque modification.

Mise en place des worktrees

Copiez les fichiers d’environnement et installez les dépendances lorsqu’un nouveau worktree est créé. Config (dans .windsurf/hooks.json) :

{
  "hooks": {
    "post_setup_worktree": [
      {
        "command": "bash $ROOT_WORKSPACE_PATH/hooks/setup_worktree.sh",
        "show_output": true
      }
    ]
  }
}

Script (hooks/setup_worktree.sh) :

#!/bin/bash

# Copier les fichiers d'environnement depuis le workspace d'origine
if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env" .env
    echo "Fichier .env copié"
fi

if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
    echo "Fichier .env.local copié"
fi

# Installer les dépendances
if [ -f "package.json" ]; then
    npm install
    echo "Dépendances npm installées"
fi

exit 0

Ce hook garantit que, pour chaque worktree, la configuration d’environnement et les dépendances nécessaires sont automatiquement installées.

Bonnes pratiques

Sécurité

Utilisez les hooks Cascade à vos risques et périls : les hooks exécutent automatiquement des commandes shell avec l’ensemble des permissions de votre compte utilisateur. Vous êtes entièrement responsable du code que vous configurez. Des hooks mal conçus ou malveillants peuvent modifier des fichiers, supprimer des données, exposer des secrets ou compromettre votre système.

Validez toutes les entrées : Ne faites jamais confiance au JSON d’entrée sans validation, en particulier pour les chemins de fichiers et les commandes.
Utilisez des chemins absolus : Utilisez toujours des chemins absolus dans vos configurations de hooks pour éviter toute ambiguïté.
Protégez les données sensibles : Évitez de journaliser des informations sensibles comme des clés d’API ou des identifiants.
Vérifiez les permissions : Assurez-vous que vos scripts de hook disposent des permissions appropriées sur le système de fichiers.
Auditez avant le déploiement : Passez en revue chaque commande et chaque script de hook avant de l’ajouter à votre configuration.
Testez en isolation : Exécutez les hooks dans un environnement de test avant de les activer sur votre machine de développement principale.

Considérations sur les performances

Gardez les hooks rapides : Des hooks lents dégraderont la réactivité de Cascade. Visez des temps d’exécution inférieurs à 100 ms.
Utilisez des opérations asynchrones : Pour des hooks non bloquants, envisagez de journaliser vers une file d’attente ou une base de données de façon asynchrone.
Filtrez dès le début : Vérifiez le type d’action au démarrage de votre script pour éviter tout traitement inutile.

Gestion des erreurs

Toujours valider le JSON : Utilisez des blocs try-catch pour gérer proprement les entrées malformées.
Journalisez correctement les erreurs : Écrivez-les sur stderr afin qu’elles soient visibles lorsque show_output est activé.
Échec sécurisé : Si votre hook rencontre une erreur, déterminez s’il doit bloquer l’action ou la laisser se poursuivre.

Tester vos hooks

Commencez par la journalisation : Implémentez d’abord un hook de journalisation simple pour comprendre le flux de données.
Utilisez show_output: true : Activez l’affichage de la sortie pendant le développement pour voir ce que font vos hooks.
Testez le comportement de blocage : Vérifiez que le code de sortie 2 bloque correctement les actions dans les pré-hooks.
Couvrez tous les chemins d’exécution : Testez les scénarios de réussite comme d’échec dans vos scripts.

Distribution Enterprise

Les organisations Enterprise doivent appliquer des politiques de sécurité, des exigences de conformité et des normes de développement que les utilisateurs individuels ne peuvent pas contourner. Cascade Hooks prend en charge deux méthodes de distribution Enterprise :

Cloud Dashboard - Configurez les hooks via les paramètres d’équipe dans le tableau de bord Windsurf
Fichiers au niveau du système - Déployez les hooks via des outils MDM ou de gestion de configuration

Les deux méthodes peuvent être utilisées ensemble : les hooks provenant de toutes les sources sont combinés et exécutés dans l’ordre.

Configuration du tableau de bord Cloud

Les administrateurs d’équipe peuvent configurer les Cascade Hooks directement depuis le tableau de bord Windsurf. Prérequis :

Offre Enterprise
Autorisation TEAM_SETTINGS_UPDATE

Pour configurer :

Accédez à Team Settings dans le tableau de bord Windsurf
Recherchez la section Cascade Hooks
Saisissez votre configuration de hooks au format JSON
Enregistrez vos modifications

Les hooks configurés via le tableau de bord sont automatiquement distribués à tous les membres de l’équipe et chargés au démarrage de Windsurf. Les hooks configurés dans le cloud sont chargés en premier, suivis des hooks au niveau système, utilisateur et workspace.

Lorsque plusieurs configurations d’équipe sont fusionnées, les hooks sont combinés par action plutôt que remplacés. Cela signifie que les hooks de toutes les configurations d’équipe applicables s’exécuteront ensemble.

Déploiement de fichiers au niveau du système

Pour les organisations qui préfèrent une configuration basée sur des fichiers ou qui ont besoin que les hooks fonctionnent hors ligne, déployez votre configuration obligatoire hooks.json aux emplacements spécifiques au système d’exploitation suivants : macOS :

/Library/Application Support/Windsurf/hooks.json

Linux/WSL :

/etc/windsurf/hooks.json

Windows :

C:\ProgramData\Windsurf\hooks.json

Placez vos scripts de hooks dans le répertoire système correspondant (par exemple, /usr/local/share/windsurf-hooks/ sur les systèmes Unix). Les hooks au niveau du système ont priorité sur les hooks utilisateur et de workspace et ne peuvent pas être désactivés par les utilisateurs finaux sans privilèges root.

MDM et gestion de configuration

Les équipes IT Enterprise peuvent déployer des hooks au niveau du système à l’aide d’outils standard : Mobile Device Management (MDM)

Jamf Pro (macOS) - Déployez via des profils de configuration ou des scripts
Microsoft Intune (Windows/macOS) - Utilisez des scripts PowerShell ou un déploiement de stratégies
Workspace ONE, Google Endpoint Management, et autres solutions MDM

Gestion de configuration

Ansible, Puppet, Chef, SaltStack - Utilisez votre automatisation d’infrastructure existante
Scripts de déploiement personnalisés - Scripts shell, PowerShell ou l’outil de votre choix

Vérification et audit

Après le déploiement, vérifiez que les hooks sont correctement installés :

# Vérifier la présence des hooks système
ls -la /etc/windsurf/hooks.json  # Linux
ls -la "/Library/Application Support/Windsurf/hooks.json"  # macOS

# Tester l'exécution des hooks (la sortie devrait apparaître dans Cascade)
# Demander à un développeur de déclencher l'action Cascade appropriée

# Vérifier que les utilisateurs ne peuvent pas modifier les hooks système
sudo chown root:root /etc/windsurf/hooks.json
sudo chmod 644 /etc/windsurf/hooks.json

Important : Les hooks système sont entièrement gérés par votre équipe informatique ou sécurité. Windsurf ne déploie ni ne gère de fichiers dans des emplacements système. Veillez à ce que vos équipes internes se chargent du déploiement, des mises à jour et de la conformité conformément aux politiques de votre organisation.

Hooks de workspace pour les projets d’équipe

Pour les conventions propres à un projet, les équipes peuvent utiliser des hooks au niveau du workspace dans le système de contrôle de version :

# Ajouter à votre dépôt
.windsurf/
├── hooks.json
└── scripts/
    └── format-check.py

# Valider dans git
git add .windsurf/
git commit -m "Ajouter des hooks de workspace pour le formatage du code"

Cela permet aux équipes d’uniformiser les pratiques de développement. Conservez les politiques critiques en matière de sécurité au niveau du cloud ou du système et évitez de valider des informations sensibles dans le système de contrôle de version.

Ressources supplémentaires

Intégration MCP : En savoir plus sur le Model Context Protocol dans Windsurf
Workflows : Découvrez comment combiner des hooks avec les workflows Cascade
Analytics : Suivez l’utilisation de Cascade avec les Analytics d’équipe

​Ce que vous pouvez créer

​Fonctionnement des hooks

​Configuration

​Niveau système

​Niveau utilisateur

​Au niveau du workspace

​Structure de base

​Options de configuration

​Événements de hooks

​Structure d’entrée commune

​pre_read_code

​post_read_code

​pre_write_code

​post_write_code

​pre_run_command

​post_run_command

​pre_mcp_tool_use

​post_mcp_tool_use

​pre_user_prompt

​post_cascade_response

​post_cascade_response_with_transcript

​post_setup_worktree

​Codes de sortie

​Exemples d’utilisations

​Journalisation de toutes les actions Cascade

​Restriction de l’accès aux fichiers

​Blocage des commandes dangereuses

​Blocage des prompts non conformes aux politiques

​Journalisation des réponses de Cascade

​Suivi des règles déclenchées

​Exécuter des formatteurs de code après modification

​Mise en place des worktrees

​Bonnes pratiques

​Sécurité

​Considérations sur les performances

​Gestion des erreurs

​Tester vos hooks

​Distribution Enterprise

​Configuration du tableau de bord Cloud

​Déploiement de fichiers au niveau du système

​MDM et gestion de configuration

​Vérification et audit

​Hooks de workspace pour les projets d’équipe

​Ressources supplémentaires

Ce que vous pouvez créer

Fonctionnement des hooks

Configuration

Niveau système

Niveau utilisateur

Au niveau du workspace

Structure de base

Options de configuration

Événements de hooks

Structure d’entrée commune

pre_read_code

post_read_code

pre_write_code

post_write_code

pre_run_command

post_run_command

pre_mcp_tool_use

post_mcp_tool_use

pre_user_prompt

post_cascade_response

post_cascade_response_with_transcript

post_setup_worktree

Codes de sortie

Exemples d’utilisations

Journalisation de toutes les actions Cascade

Restriction de l’accès aux fichiers

Blocage des commandes dangereuses

Blocage des prompts non conformes aux politiques

Journalisation des réponses de Cascade

Suivi des règles déclenchées

Exécuter des formatteurs de code après modification

Mise en place des worktrees

Bonnes pratiques

Sécurité

Considérations sur les performances

Gestion des erreurs

Tester vos hooks

Distribution Enterprise

Configuration du tableau de bord Cloud

Déploiement de fichiers au niveau du système

MDM et gestion de configuration

Vérification et audit

Hooks de workspace pour les projets d’équipe

Ressources supplémentaires