Cascade Hooks

Cascade Hooks vă permit să executați comenzi shell personalizate în momente cheie din fluxul de lucru al Cascade. Această capabilitate puternică de extensibilitate vă permite să înregistrați operațiuni, să impuneți garde-fou, să rulați verificări de validare sau să vă integrați cu sisteme externe.

Hooks sunt concepute pentru utilizatori avansați și echipe Enterprise care au nevoie de control granular asupra comportamentului Cascade. Acestea necesită cunoștințe de bază de scripting în shell.

Ce puteți construi

Hook-urile deblochează o gamă largă de capabilități pentru automatizare și guvernanță:

Jurnalizare & Analytics: Monitorizați fiecare fișier citit, modificare de cod, comandă executată, prompt de utilizator sau răspuns Cascade, pentru conformitate și analiză a utilizării
Controale de securitate: Împiedicați Cascade să acceseze fișiere sensibile, să ruleze comenzi periculoase sau să proceseze prompturi care încalcă politicile
Asigurarea calității: Rulați automat linters, formatare sau teste după modificările de cod
Fluxuri de lucru personalizate: Integrați cu trackere de issue-uri, sisteme de notificare sau pipeline-uri de deployment
Standardizare la nivel de echipă: Aplicați standarde de cod și bune practici în întreaga organizație

Cum funcționează hook-urile

Hook-urile sunt comenzi de shell care rulează automat atunci când au loc acțiuni Cascade specifice. Fiecare hook:

Primește context (detalii despre acțiunea executată) prin JSON ca intrare standard
Execută scriptul dvs. – Python, Bash, Node.js sau orice executabil
Returnează un rezultat prin codul de ieșire și fluxurile de ieșire

Pentru pre-hook-uri (executate înaintea unei acțiuni), scriptul dvs. poate bloca acțiunea încheindu-se cu codul de ieșire 2. Acest lucru face ca pre-hook-urile să fie ideale pentru implementarea politicilor de securitate sau a verificărilor de validare.

Configurare

Hook‑urile se configurează în fișiere JSON care pot fi plasate la trei niveluri diferite. Cascade încarcă și combină hook‑urile din toate locațiile, oferind echipelor flexibilitate în modul în care distribuie și gestionează configurațiile de hook.

La nivel de sistem

Hook-urile la nivel de sistem sunt ideale pentru politici la nivelul întregii organizații, aplicate pe stații de lucru partajate. De exemplu, le puteți folosi pentru a impune politici de securitate, cerințe de conformitate sau fluxuri de lucru obligatorii pentru code review. Echipele Enterprise pot, de asemenea, să configureze hook-uri prin intermediul dashboard-ului din cloud, fără a fi nevoie să gestioneze fișiere locale.

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

La nivel de utilizator

Hookurile la nivel de utilizator sunt ideale pentru preferințe personale și fluxuri de lucru opționale.

Windsurf IDE: ~/.codeium/windsurf/hooks.json
JetBrains Plugin: ~/.codeium/hooks.json

La nivel de workspace

Hook-urile la nivel de workspace permit echipelor să versiuneze politici specifice proiectului alături de cod. Acestea pot include reguli personalizate de validare, integrări specifice proiectului sau fluxuri de lucru specifice echipei.

Locație: .windsurf/hooks.json în rădăcina workspace-ului

Hook-urile din toate cele trei locații sunt comasate. Dacă același eveniment de hook este configurat în mai multe locații, toate hook-urile se vor executa în această ordine: sistem → utilizator → workspace.

Structură de bază

Iată un exemplu al structurii de bază a configurației pentru 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
      }
    ]
  }
}

Opțiuni de configurare

Fiecare hook acceptă următorii parametri:

Parametru	Tip	Descriere
`command`	string	Comanda shell de executat. Poate fi orice executabil valid, cu argumente.
`show_output`	boolean	Dacă să fie afișată ieșirea stdout/stderr a hook‑ului în interfața Cascade vizibilă pentru utilizator. Util pentru depanare.
`working_directory`	string	Opțional. Directorul din care se execută comanda. Implicit, rădăcina workspace‑ului dvs.

Despre parametrul working_directory:

În workspace‑urile cu mai multe repo‑uri, valoarea implicită este rădăcina repo‑ului la care lucrați în prezent
Căile relative sunt rezolvate pornind de la locația implicită (rădăcina workspace‑ului sau a repo‑ului)
Căile absolute sunt acceptate
Utilizarea lui ~ pentru extinderea la directorul home nu este acceptată

Evenimente hook

Cascade oferă douăsprezece evenimente hook care acoperă cele mai importante acțiuni din fluxul de lucru al agentului.

Structura comună a inputului

Toate hook-urile primesc un obiect JSON cu următoarele câmpuri comune:

Câmp	Tip	Descriere
`agent_action_name`	string	Numele evenimentului hook-ului (de ex. „pre_read_code”, „post_write_code”)
`trajectory_id`	string	Identificator unic pentru conversația Cascade în ansamblu
`execution_id`	string	Identificator unic pentru o singură iterație a agentului
`timestamp`	string	Marcaj temporal ISO 8601 la momentul declanșării hook-ului
`tool_info`	object	Informații specifice evenimentului (variază în funcție de tipul de hook)

În exemplele de mai jos, câmpurile comune sunt omise pentru concizie. Există douăsprezece tipuri majore de evenimente de tip hook:

pre_read_code

Declanșat înainte ca Cascade să citească un fișier de cod. Acest lucru poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Restricționați accesul la fișiere, înregistrați operațiunile de citire, verificați permisiunile Input JSON:

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

Acest file_path poate fi o cale de director atunci când Cascade parcurge recursiv un director.

post_read_code

Declanșat după ce Cascade citește cu succes un fișier de cod. Cazuri de utilizare: Înregistrați citirile reușite, urmăriți tiparele de acces la fișiere Input JSON:

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

Acest file_path poate fi o cale de director atunci când Cascade parcurge recursiv un director.

pre_write_code

Declanșat înainte ca Cascade să scrie sau să modifice un fișier de cod. Poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Prevenirea modificărilor în fișiere protejate, realizarea de copii de rezervă înainte de schimbări 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

Declanșat după ce Cascade scrie sau modifică un fișier de cod. Cazuri de utilizare: Rulați linters, formatare sau teste; înregistrați modificările de cod Input JSON:

{
  "agent_action_name": "post_write_code",
  "tool_info": {
    "file_path": "/Users/yourname/project/file.py",
    "edits": [
      {
        "old_string": "import os",
        "new_string": "import os\nimport sys"
      }
    ]
  }
}

pre_run_command

Se declanșează înainte ca Cascade să execute o comandă în terminal. Poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Blocați comenzile periculoase, înregistrați toate execuțiile de comenzi, adăugați verificări de siguranță Input JSON:

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

post_run_command

Se declanșează după ce Cascade execută o comandă în terminal. Cazuri de utilizare: înregistrarea rezultatelor comenzii, declanșarea acțiunilor ulterioare Input JSON:

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

pre_mcp_tool_use

Declanșat înainte ca Cascade să utilizeze un instrument MCP (Model Context Protocol). Poate bloca acțiunea dacă hook-ul se încheie cu codul 2. Cazuri de utilizare: Înregistrarea utilizării MCP, restricționarea instrumentelor MCP care pot fi folosite Input JSON:

{
  "agent_action_name": "pre_mcp_tool_use",
  "tool_info": {
    "mcp_server_name": "github",
    "mcp_tool_arguments": {
      "owner": "code-owner",
      "repo": "my-cool-repo",
      "title": "Raport de eroare",
      "body": "Descrierea erorii aici"
    },
    "mcp_tool_name": "create_issue"
  }
}

post_mcp_tool_use

Declanșat după ce Cascade a apelat cu succes un instrument MCP. Cazuri de utilizare: Înregistrați operațiunile MCP, urmăriți utilizarea API-ului, vizualizați rezultatele MCP Input JSON:

{
  "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

Declanșat înainte ca Cascade să proceseze textul promptului unui utilizator. Acest hook poate bloca acțiunea dacă se încheie cu codul 2. Cazuri de utilizare: Înregistrarea în log a tuturor prompturilor utilizatorilor pentru auditare, blocarea prompturilor potențial dăunătoare sau care încalcă politicile Input JSON:

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

Opțiunea de configurare show_output nu se aplică acestui hook.

post_cascade_response

Declanșat asincron după ce Cascade finalizează un răspuns la promptul unui utilizator. Acest hook primește întregul răspuns Cascade de la ultima intrare a utilizatorului. Cazuri de utilizare: Înregistrați toate răspunsurile Cascade pentru audit, analizați tiparele de răspuns, trimiteți răspunsurile către sisteme externe pentru verificarea conformității Input JSON:

{
  "agent_action_name": "post_cascade_response",
  "tool_info": {
    "response": "### Răspuns Planificator\n\nVă voi ajuta să creați acel fișier.\n\n*Fișier creat `/path/to/file.py`*\n\n### Răspuns Planificator\n\nFișierul a fost creat cu succes."
  }
}

Câmpul response conține conținutul în format markdown al răspunsului generat de Cascade de la ultima intrare a utilizatorului. Acesta include răspunsurile planificatorului, acțiunile instrumentelor (citiri de fișiere, scrieri, comenzi) și orice alți pași pe care i-a efectuat Cascade. Include și informații despre regulile care au fost declanșate. Consultați exemplul Tracking Triggered Rules pentru a vedea cum să interpretați utilizarea regulilor. Opțiunea de configurare show_output nu se aplică acestui hook.

Conținutul response este derivat din date privind traiectoria și poate conține informații sensibile din codul sau conversațiile dvs. Tratați aceste date în conformitate cu politicile de securitate și confidențialitate ale organizației dvs.

post_cascade_response_with_transcript

Declanșat asincron după ce Cascade finalizează un răspuns la promptul unui utilizator, similar cu post_cascade_response. În loc să ofere un rezumat markdown direct în conversație, acest hook scrie transcrierea completă a conversației (începând de la debutul conversației) într-un fișier JSONL local și furnizează calea către fișier. Cazuri de utilizare: jurnalizare pentru audit și conformitate la nivel Enterprise, urmărirea contribuțiilor generate de AI, trimiterea transcrierilor către instrumente externe de observabilitate sau Analytics Input JSON:

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

transcript_path indică către un fișier JSONL la ~/.windsurf/transcripts/{trajectory_id}.jsonl. Fiecare linie este un obiect JSON care reprezintă un singur pas în conversație, cu câmpurile type și status, plus date specifice pasului. De exemplu:

{"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"}

Transcriptul include date detaliate, deținute de client, precum conținutul fișierelor, ieșiri ale comenzilor, argumente ale instrumentelor, rezultate de căutare și reguli care au fost aplicate. Vă rugăm să rețineți că structura exactă a fiecărui pas se poate schimba în versiunile viitoare, așa că este indicat să construiți orice componente care consumă hook-uri astfel încât să fie rezistente la schimbări. Fișierele de transcript sunt scrise cu permisiuni 0600. Windsurf limitează automat directorul de transcripturi la 100 de fișiere, ștergându-le pe cele mai vechi în funcție de timpul ultimei modificări. Opțiunea de configurare show_output nu se aplică acestui hook. Acest tabel arată principalele diferențe dintre hook-urile post_cascade_response și post_cascade_response_with_transcript:

	`post_cascade_response`	`post_cascade_response_with_transcript`
Sferă de date	Doar pașii de la ultima intrare a utilizatorului	Întreaga conversație de la început
Format	Rezumat în Markdown în `tool_info.response`	Fișier JSONL structurat la `tool_info.transcript_path`
Nivel de detaliu	Rezumat condensat, ușor de citit pentru oameni	Date detaliate, procesabile de mașini (conținut de fișiere, ieșiri de comenzi etc.)
Mod de livrare	Inline prin stdin JSON	Fișier pe disc (`~/.windsurf/transcripts/`)

Fișierele de transcript vor conține informații sensibile din codul dumneavoastră, inclusiv conținutul fișierelor, ieșiri de comenzi și istoricul conversațiilor. Gestionați aceste fișiere în conformitate cu politicile de securitate și confidențialitate ale organizației dumneavoastră.

post_setup_worktree

Declanșat după ce un nou git worktree este creat și configurat. Hook-ul este executat în noul director worktree. Cazuri de utilizare: Copiați fișierele .env sau alte fișiere neurmărite în worktree, instalați dependențele, rulați scripturi de configurare Variabile de mediu:

Variabilă	Descriere
`$ROOT_WORKSPACE_PATH`	Calea absolută către workspace-ul original. Utilizați-o pentru a accesa fișiere sau pentru a rula comenzi relativ la repository-ul original.

JSON de intrare:

{
  "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"
  }
}

Coduri de ieșire

Scripturile hook comunică rezultatele prin coduri de ieșire:

Cod de ieșire	Semnificație	Efect
`0`	Succes	Acțiunea continuă normal
`2`	Eroare care blochează	Agentul Cascade va vedea mesajul de eroare din stderr. Pentru pre-hook-uri, acest lucru blochează acțiunea.
Oricare altul	Eroare	Acțiunea continuă normal

Doar pre-hook-urile (pre_user_prompt, pre_read_code, pre_write_code, pre_run_command, pre_mcp_tool_use) pot bloca acțiunile folosind codul de ieșire 2. Post-hook-urile nu pot bloca, deoarece acțiunea a avut deja loc.

Țineți cont că utilizatorul poate vedea orice ieșire standard și eroare standard generate de hook în interfața Cascade dacă show_output este true.

Exemple de scenarii de utilizare

Înregistrarea tuturor acțiunilor Cascade

Monitorizați fiecare acțiune efectuată de Cascade în scopuri de 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"Eroare la procesarea JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Acest script adaugă fiecare apel al unui hook într-un fișier jurnal, creând un traseu de audit pentru toate acțiunile Cascade. Puteți transforma datele de intrare sau rula logică personalizată, după cum considerați potrivit.

Restricționarea accesului la fișiere

Împiedicați Cascade să citească fișiere din afara unui director specific. Config:

{
  "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():
    # 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_read_code":
            tool_info = data.get("tool_info", {})
            file_path = tool_info.get("file_path", "")
            
            if not file_path.startswith(ALLOWED_PREFIX):
                print(f"Acces refuzat: Cascade poate citi doar fișierele din {ALLOWED_PREFIX}", file=sys.stderr)
                sys.exit(2)  # Exit code 2 blocks the action
            
            print(f"Access granted: {file_path}", file=sys.stdout)

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

if __name__ == "__main__":
    main()

Când Cascade încearcă să citească un fișier din afara directorului permis, acest hook blochează operațiunea și afișează un mesaj de eroare.

Blocarea comenzilor periculoase

Împiedicați Cascade să execute comenzi potențial dăunătoare. Config:

{
  "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"Comandă blocată: '{dangerous_cmd}' nu este permisă din motive de securitate.", 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()

Acest hook scanează comenzile pentru tipare periculoase și le blochează înainte de execuție.

Blocarea prompturilor care încalcă politicile

Împiedicați utilizatorii să trimită prompturi care încalcă politicile organizației. Config:

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

Scriptul (block_bad_prompts.py):

#!/usr/bin/env python3

import sys
import json

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

def main():
    # Citește datele JSON din stdin
    input_data = sys.stdin.read()

    # Analizează JSON-ul
    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 blocat: Conține conținut interzis. Utilizatorul nu poate solicita agentului să efectueze acțiuni nepermise.", file=sys.stderr)
                    sys.exit(2)  # Codul de ieșire 2 blochează prompt-ul

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

if __name__ == "__main__":
    main()

Acest hook examinează prompturile utilizatorului înainte ca acestea să fie procesate și blochează orice prompt care conține tipare interzise. Atunci când un prompt este blocat, utilizatorul vede un mesaj de eroare în interfața Cascade.

Înregistrarea răspunsurilor Cascade

Urmăriți toate răspunsurile Cascade pentru audit de conformitate sau analiză. Config:

{
  "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():
    # Citește datele JSON din stdin
    input_data = sys.stdin.read()

    # Analizează JSON-ul
    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())

            # Înregistrează în fișier
            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"Error parsing JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Acest hook înregistrează fiecare răspuns Cascade într-un fișier, creând un istoric de audit al întregului conținut generat de AI. Puteți extinde acest comportament pentru a trimite date către sisteme externe de jurnale, baze de date sau platforme de conformitate.

Urmărirea regulilor declanșate

Urmăriți care reguli au fost aplicate în timpul interacțiunilor cu Cascade, pentru observabilitate și metrici. Configurație:

{
  "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:
    """
    Analizează regulile declanșate din răspunsul Cascade.
    Regulile apar ca: - (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()

Tipuri de reguli:

Always On - Reguli care sunt incluse întotdeauna
Model Decision - Reguli ale căror descrieri au fost afișate modelului AI pentru aplicare condiționată
Manual - Reguli menționate explicit cu @ în introducerea utilizatorului
Global - Reguli globale din global_rules.md
Glob - Reguli declanșate de accesarea fișierelor care se potrivesc cu șabloane glob

Aceasta urmărește ce reguli au fost prezentate modelului AI sau declanșate de accesarea fișierelor, dar nu indică dacă modelul AI a respectat efectiv o regulă. Regulile care au fost deja afișate recent în conversație sunt deduplicate și este posibil să nu mai apară din nou decât mai târziu.

Rularea formatarelor de cod după modificări

Formatați automat fișierele de cod după ce Cascade le actualizează. Config:

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

Script (format_code.sh):

#!/bin/bash

# Read JSON from stdin
input=$(cat)

# Extract file path using jq
file_path=$(echo "$input" | jq -r '.tool_info.file_path')

# Format based on file extension
if [[ "$file_path" == *.py ]]; then
    black "$file_path" 2>&1
    echo "Fișier Python formatat: $file_path"
elif [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
    prettier --write "$file_path" 2>&1
    echo "Formatted JS/TS file: $file_path"
elif [[ "$file_path" == *.go ]]; then
    gofmt -w "$file_path" 2>&1
    echo "Formatted Go file: $file_path"
fi

exit 0

Acest hook rulează automat formatorul adecvat în funcție de tipul fișierului, după fiecare modificare.

Configurarea worktree-urilor

Copiați fișierele de mediu și instalați dependențele la crearea unui nou worktree. Config (în .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

# Copiați fișierele de mediu din workspace-ul original
if [ -f "$ROOT_WORKSPACE_PATH/.env" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env" .env
    echo "Fișierul .env a fost copiat"
fi

if [ -f "$ROOT_WORKSPACE_PATH/.env.local" ]; then
    cp "$ROOT_WORKSPACE_PATH/.env.local" .env.local
    echo "Fișierul .env.local a fost copiat"
fi

# Instalați dependențele
if [ -f "package.json" ]; then
    npm install
    echo "Dependențele npm au fost instalate"
fi

exit 0

Acest hook se asigură că fiecare worktree are în mod automat configurată configurația de mediu necesară și dependențele instalate.

Recomandări de bune practici

Securitate

Utilizați Cascade Hooks pe propria răspundere: Hook‑urile execută automat comenzi de shell cu toate permisiunile contului dvs. de utilizator. Sunteți pe deplin responsabil(ă) pentru codul pe care îl configurați. Hook‑urile proiectate defectuos sau malițioase pot modifica fișiere, șterge date, expune credențiale sau compromite sistemul.

Validați toate intrările: Nu aveți niciodată încredere în JSON‑ul de intrare fără validare, mai ales în ceea ce privește căile de fișiere și comenzile.
Folosiți căi absolute: Utilizați întotdeauna căi absolute în configurațiile hook‑urilor pentru a evita ambiguitățile.
Protejați datele sensibile: Evitați înregistrarea (logging) informațiilor sensibile, precum chei API sau credențiale.
Revizuiți permisiunile: Asigurați-vă că scripturile hook au permisiuni adecvate în sistemul de fișiere.
Auditați înainte de implementare: Examinați fiecare comandă și script de hook înainte de a le adăuga în configurație.
Testați în izolare: Rulați hook‑urile într-un mediu de test înainte de a le activa pe stația dvs. principală de dezvoltare.

Considerații privind performanța

Păstrați hook-urile rapide: Hook-urile lente vor afecta capacitatea de răspuns a Cascade. Vizați timpi de execuție sub 100 ms.
Folosiți operațiuni asincrone: Pentru hook-uri neblocante, luați în considerare logarea într-o coadă sau într-o bază de date, asincron.
Filtrați cât mai devreme: Verificați tipul acțiunii la începutul scriptului pentru a evita procesarea inutilă.

Gestionarea erorilor

Validați întotdeauna JSON-ul: Folosiți blocuri try-catch pentru a gestiona elegant datele de intrare malformate.
Înregistrați corect erorile: Trimiteți erorile la stderr pentru a fi vizibile când show_output este activat.
Eșuați în siguranță: Dacă hook-ul dvs. întâmpină o eroare, evaluați dacă ar trebui să blocheze acțiunea sau să permită continuarea acesteia.

Testarea hook-urilor

Începeți cu jurnalizarea: Implementați mai întâi un hook simplu de jurnalizare pentru a înțelege fluxul de date.
Folosiți show_output: true: Activați afișarea rezultatelor în timpul dezvoltării pentru a vedea ce fac hook-urile.
Testați comportamentul de blocare: Verificați că valoarea de ieșire 2 (exit code 2) blochează corect acțiunile în pre-hooks.
Verificați toate ramurile de cod: Testați atât scenariile de reușită, cât și pe cele de eșec în scripturi.

Distribuție Enterprise

Organizațiile Enterprise trebuie să aplice politici de securitate, cerințe de conformitate și standarde de dezvoltare pe care utilizatorii individuali nu le pot evita. Cascade Hooks susține două metode de distribuție Enterprise:

Cloud Dashboard – Configurați hooks în Team Settings din dashboard-ul Windsurf
System-Level Files – Implementați hooks prin MDM sau instrumente de gestionare a configurațiilor

Ambele metode pot fi utilizate împreună — hooks din toate sursele sunt combinate și executate în ordine.

Configurarea dashboard-ului în cloud

Administratorii de echipă pot configura Cascade Hooks direct din dashboard-ul Windsurf. Cerințe:

Plan Enterprise
Permisiunea TEAM_SETTINGS_UPDATE

Pentru configurare:

Navigați la Team Settings în dashboard-ul Windsurf
Găsiți secțiunea Cascade Hooks
Introduceți configurația pentru hooks, în format JSON
Salvați modificările

Hook-urile configurate din dashboard sunt distribuite automat tuturor membrilor echipei și sunt încărcate la pornirea Windsurf. Hook-urile configurate în cloud sunt încărcate mai întâi, urmate de hook-urile la nivel de sistem, la nivel de utilizator și la nivel de workspace.

Atunci când mai multe configurații de echipă sunt îmbinate, hook-urile sunt combinate pentru fiecare acțiune, în loc să fie suprascrise. Aceasta înseamnă că hook-urile din toate configurațiile de echipă aplicabile vor rula împreună.

Implementare fișiere la nivel de sistem

Pentru organizațiile care preferă configurarea bazată pe fișiere sau care au nevoie ca hook-urile să funcționeze offline, implementați configurația obligatorie hooks.json în aceste locații specifice sistemului de operare: macOS:

/Library/Application Support/Windsurf/hooks.json

Linux/WSL:

/etc/windsurf/hooks.json

Windows:

C:\ProgramData\Windsurf\hooks.json

Plasați scripturile hook într-un director de sistem corespunzător (de ex. „/usr/local/share/windsurf-hooks/” pe sistemele Unix). Hook-urile la nivel de sistem au prioritate față de hook-urile de utilizator și de workspace și nu pot fi dezactivate de utilizatorii finali fără permisiuni de root.

MDM și gestionarea configurațiilor

Echipele IT Enterprise pot implementa hook‑uri la nivel de sistem folosind instrumente standard: Mobile Device Management (MDM)

Jamf Pro (macOS) - Implementare prin profiluri de configurare sau scripturi
Microsoft Intune (Windows/macOS) - Utilizați scripturi PowerShell sau implementarea prin politici
Workspace ONE, Google Endpoint Management și alte soluții MDM

Gestionarea configurațiilor

Ansible, Puppet, Chef, SaltStack - Utilizați automatizarea existentă a infrastructurii
Scripturi personalizate de implementare - Scripturi shell, PowerShell sau instrumentele preferate

Verificare și auditare

După implementare, verificați că hook-urile sunt instalate corect:

# Verify system hooks are present
ls -la /etc/windsurf/hooks.json  # Linux
ls -la "/Library/Application Support/Windsurf/hooks.json"  # macOS

# Testați execuția hook-ului (ar trebui să vedeți rezultatul hook-ului în Cascade)
# Have a developer trigger the relevant Cascade action

# Verify users cannot modify system hooks
sudo chown root:root /etc/windsurf/hooks.json
sudo chmod 644 /etc/windsurf/hooks.json

Important: Hook-urile la nivel de sistem sunt administrate în întregime de echipa dvs. IT sau de securitate. Windsurf nu distribuie și nu gestionează fișiere în locații la nivel de sistem. Asigurați-vă că echipele interne se ocupă de distribuire, actualizări și conformitate în acord cu politicile organizației dvs.

Hook-uri de workspace pentru proiecte de echipă

Pentru convenții specifice fiecărui proiect, echipele pot utiliza hook-uri la nivel de workspace în sistemul de control al versiunilor:

# Adăugați în repository-ul dvs.
.windsurf/
├── hooks.json
└── scripts/
    └── format-check.py

# Commit în git
git add .windsurf/
git commit -m "Adăugați hook-uri de workspace pentru formatarea codului"

Acest lucru permite echipelor să standardizeze practicile de dezvoltare. Păstrați politicile critice pentru securitate la nivel de cloud sau de sistem și evitați să introduceți informații sensibile în sistemul de control al versiunilor.

Resurse suplimentare

Integrare MCP: Aflați mai multe despre Model Context Protocol în Windsurf
Workflows: Descoperiți cum să combinați hooks cu Cascade Workflows
Analytics: Urmăriți utilizarea Cascade cu Analytics pentru echipă