Hooks do Cascade (Beta)

Os Hooks do Cascade permitem executar comandos de shell personalizados em pontos-chave do fluxo de trabalho do Cascade. Esse poderoso recurso de extensibilidade possibilita registrar operações, aplicar controles (guardrails), executar verificações de validação ou integrar-se a sistemas externos.

Versão Beta: Os Hooks do Cascade estão em beta e em desenvolvimento ativo. Funcionalidades e APIs podem mudar. Entre em contato com o Windsurf Support para enviar feedback ou relatar bugs.

Os Hooks foram projetados para usuários avançados e equipes Enterprise que precisam de controle granular sobre o comportamento do Cascade. Eles exigem conhecimento básico de shell scripting.

O que você pode construir

Hooks desbloqueiam uma ampla gama de recursos de automação e governança:

Registro e Analytics: Acompanhe cada arquivo lido, alteração de código ou comando executado pelo Cascade para fins de conformidade e análise de uso
Controles de segurança: Impessa o Cascade de acessar arquivos sensíveis ou executar comandos perigosos
Garantia de qualidade: Execute linters, formatadores ou testes automaticamente após modificações no código
Fluxos de trabalho personalizados: Integre com rastreadores de issues, sistemas de notificação ou pipelines de deploy
Padronização da equipe: Faça cumprir padrões de codificação e melhores práticas em toda a organização

Como os Hooks Funcionam

Hooks são comandos de shell que são executados automaticamente quando ações específicas do Cascade ocorrem. Cada hook:

Recebe contexto (detalhes sobre a ação em execução) via JSON na entrada padrão
Executa seu script — Python, Bash, Node.js ou qualquer executável
Retorna um resultado por meio de código de saída e fluxos de saída

Para pré-hooks (executados antes de uma ação), seu script pode bloquear a ação encerrando com o código de saída 2. Isso torna os pré-hooks ideais para implementar políticas de segurança ou validações.

Configuração

Os hooks são configurados em arquivos JSON que podem ser colocados em três níveis diferentes. O Cascade carrega e combina os hooks de todos os locais, dando às equipes flexibilidade para distribuir e gerenciar as configurações de hooks.

Nível do sistema

Hooks em nível de sistema são ideais para políticas organizacionais aplicadas em máquinas de desenvolvimento compartilhadas. Por exemplo, você pode usá-los para impor políticas de segurança, requisitos de conformidade ou fluxos de trabalho obrigatórios de revisão de código.

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

Nível do usuário

Hooks no nível do usuário são ideais para preferências pessoais e fluxos de trabalho opcionais.

Local: ~/.codeium/windsurf/hooks.json

Nível de workspace

Hooks no nível de workspace permitem que as equipes versionem políticas específicas do projeto junto com o código. Eles podem incluir regras de validação personalizadas, integrações específicas do projeto ou fluxos de trabalho específicos da equipe.

Local: .windsurf/hooks.json na raiz do seu workspace

Hooks de todas as três origens são mesclados. Se o mesmo evento de hook estiver configurado em várias origens, todos os hooks serão executados na seguinte ordem: sistema → usuário → workspace.

Estrutura básica

Veja um exemplo da estrutura básica da configuração de 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ções de configuração

Cada hook aceita os seguintes parâmetros:

Parâmetro	Tipo	Descrição
`command`	string	O comando de shell a ser executado. Pode ser qualquer executável válido com argumentos.
`show_output`	boolean	Define se a saída stdout/stderr do hook será exibida na interface do Cascade voltada ao usuário. Útil para depuração.
`working_directory`	string	Opcional. O diretório a partir do qual o comando será executado. Por padrão, é a raiz do seu workspace.

Eventos de Hook

O Cascade oferece oito eventos de hook que abrangem as ações mais críticas no fluxo de trabalho do agente.

Estrutura comum de entrada

Todos os hooks recebem um objeto JSON com os seguintes campos comuns:

Campo	Tipo	Descrição
`agent_action_name`	string	Nome do evento do hook (por exemplo, “pre_read_code”, “post_write_code”)
`trajectory_id`	string	Identificador exclusivo da conversa geral do Cascade
`execution_id`	string	Identificador exclusivo da única interação do agente
`timestamp`	string	Carimbo de data/hora em formato ISO 8601 no momento em que o hook foi acionado
`tool_info`	object	Informações específicas do evento (variam conforme o tipo de hook)

Nos exemplos a seguir, os campos comuns são omitidos para brevidade. Existem oito tipos principais de eventos de hook:

pre_read_code

Acionado antes de o Cascade ler um arquivo de código. Isso pode bloquear a ação se o hook terminar com o código 2. Casos de uso: Restringir acesso a arquivos, registrar operações de leitura, verificar permissões JSON de entrada:

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

Este file_path pode ser um caminho de diretório quando o Cascade lê uma pasta de forma recursiva.

post_read_code

Acionado após o Cascade ler um arquivo de código com sucesso. Casos de uso: Registrar leituras bem-sucedidas, acompanhar padrões de acesso a arquivos JSON de entrada:

{
  "agent_action_name": "post_read_code",
  "tool_info": {
    "file_path": "/Users/seunome/projeto/arquivo.py"
  }
}

Este file_path pode ser um caminho de diretório quando o Cascade lê um diretório de forma recursiva.

pre_write_code

Acionado antes de o Cascade escrever ou modificar um arquivo de código. Pode bloquear a ação se o hook encerrar com o código 2. Casos de uso: Impedir modificações em arquivos protegidos, fazer backup dos arquivos antes de alterações JSON de entrada:

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

Acionado depois que o Cascade escreve ou modifica um arquivo de código. Casos de uso: Executar linters, formatadores ou testes; registrar alterações no código JSON de entrada:

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

Acionado antes de o Cascade executar um comando no terminal. A ação pode ser bloqueada se o hook terminar com o código 2. Casos de uso: bloquear comandos perigosos, registrar todas as execuções de comandos, adicionar verificações de segurança JSON de entrada:

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

post_run_command

Disparado após o Cascade executar um comando no terminal. Casos de uso: Registrar resultados do comando, disparar ações subsequentes JSON de entrada:

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

pre_mcp_tool_use

Acionado antes de o Cascade invocar uma ferramenta MCP (Model Context Protocol). Isso pode bloquear a ação se o hook terminar com o código 2. Casos de uso: Registrar o uso de MCP, restringir quais ferramentas MCP podem ser usadas JSON de entrada:

{
  "agent_action_name": "pre_mcp_tool_use",
  "tool_info": {
    "mcp_server_name": "github",
    "mcp_tool_arguments": {
      "owner": "code-owner",
      "repo": "my-cool-repo",
      "title": "Relatório de bug",
      "body": "Descrição do bug"
    },
    "mcp_tool_name": "create_issue"
  }
}

post_mcp_tool_use

Acionado depois que o Cascade invoca com sucesso uma ferramenta MCP. Casos de uso: Registrar operações do MCP, acompanhar uso de API, visualizar resultados do MCP JSON de entrada:

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

Códigos de saída

Seus scripts de hook comunicam resultados por meio de códigos de saída:

Código de saída	Significado	Efeito
`0`	Sucesso	A ação prossegue normalmente
`2`	Erro bloqueador	O agente Cascade verá a mensagem de erro do stderr. Em pré-hooks, isso bloqueia a ação.
Qualquer outro	Erro	A ação prossegue normalmente

Apenas pré-hooks (pre_read_code, pre_write_code, pre_run_command, pre_mcp_tool_use) podem bloquear ações usando o código de saída 2. Pós-hooks não podem bloquear, pois a ação já ocorreu.

Lembre-se de que o usuário pode ver qualquer saída padrão e erro padrão gerados pelos hooks na interface do Cascade se show_output for true.

Exemplos de casos de uso

Registro de todas as ações do Cascade

Acompanhe cada ação que o Cascade executa para fins de auditoria. Config (~/.codeium/windsurf/hooks.json):

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

Script (log_input.py):

#!/usr/bin/env python3

import sys
import json

def main():
    # Lê os dados JSON da entrada padrão
    input_data = sys.stdin.read()
    
    # Faz o parse do JSON
    try:
        data = json.loads(input_data)
        
        # Grava o JSON formatado no arquivo
        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"Erro ao fazer parse do JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Este script anexa cada acionamento de hook a um arquivo de log, criando um registro de auditoria de todas as ações do Cascade. Você pode transformar os dados de entrada ou executar lógica personalizada conforme achar necessário.

Restringir acesso a arquivos

Impeça o Cascade de ler arquivos fora de um diretório específico. Config (~/.codeium/windsurf/hooks.json):

{
  "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():
    # Lê os dados JSON da entrada padrão
    input_data = sys.stdin.read()

    # Faz o parse do 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"Acesso negado: o Cascade só pode ler arquivos em {ALLOWED_PREFIX}", file=sys.stderr)
                sys.exit(2)  # O código de saída 2 bloqueia a ação
            
            print(f"Acesso concedido: {file_path}", file=sys.stdout)

    except json.JSONDecodeError as e:
        print(f"Erro ao fazer parse do JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Quando o Cascade tenta ler um arquivo fora do diretório permitido, este hook bloqueia a operação e exibe uma mensagem de erro.

Bloqueando comandos perigosos

Impeça o Cascade de executar comandos potencialmente perigosos. Config (~/.codeium/windsurf/hooks.json):

{
  "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():
    # Lê os dados JSON da entrada padrão
    input_data = sys.stdin.read()

    # Faz o parse do 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"Comando bloqueado: '{dangerous_cmd}' não é permitido por motivos de segurança.", file=sys.stderr)
                    sys.exit(2)  # Código de saída 2 bloqueia o comando
            
            print(f"Comando aprovado: {command}", file=sys.stdout)

    except json.JSONDecodeError as e:
        print(f"Erro ao fazer parse do JSON: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

Este hook verifica os Commands em busca de padrões perigosos e os bloqueia antes da execução.

Executando formatadores de código após edições

Formate arquivos de código automaticamente depois que o Cascade os modificar. Configuração (~/.codeium/windsurf/hooks.json):

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

Script (format_code.sh):

#!/bin/bash

# Lê JSON da entrada padrão
input=$(cat)

# Extrai o caminho do arquivo usando jq
file_path=$(echo "$input" | jq -r '.tool_info.file_path')

# Formata com base na extensão do arquivo
if [[ "$file_path" == *.py ]]; then
    black "$file_path" 2>&1
    echo "Arquivo Python formatado: $file_path"
elif [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
    prettier --write "$file_path" 2>&1
    echo "Arquivo JS/TS formatado: $file_path"
elif [[ "$file_path" == *.go ]]; then
    gofmt -w "$file_path" 2>&1
    echo "Arquivo Go formatado: $file_path"
fi

exit 0

Este hook executa automaticamente o formatador adequado com base no tipo de arquivo após cada edição.

Boas práticas

Segurança

Use Cascade Hooks por sua conta e risco: Hooks executam comandos de shell automaticamente com todas as permissões da sua conta de usuário. Você é totalmente responsável pelo código que configurar. Hooks mal projetados ou maliciosos podem modificar arquivos, excluir dados, expor credenciais ou comprometer seu sistema.

Valide todas as entradas: Nunca confie no JSON de entrada sem validação, especialmente para caminhos de arquivo e comandos.
Use caminhos absolutos: Sempre use caminhos absolutos nas configurações de hooks para evitar ambiguidades.
Proteja dados sensíveis: Evite registrar informações sensíveis, como chaves de API ou credenciais.
Revise as permissões: Certifique-se de que seus scripts de hooks tenham permissões adequadas no sistema de arquivos.
Audite antes da implantação: Revise cada comando e script de hooks antes de adicioná-los à sua configuração.
Teste em isolamento: Execute hooks em um ambiente de teste antes de habilitá-los na sua máquina principal de desenvolvimento.

Considerações de desempenho

Mantenha os hooks rápidos: Hooks lentos afetarão a responsividade do Cascade. Mire em tempos de execução abaixo de 100 ms.
Use operações assíncronas: Para hooks não bloqueantes, considere registrar em uma fila ou em um banco de dados de forma assíncrona.
Filtre o quanto antes: Verifique o tipo de ação no início do script para evitar processamento desnecessário.

Tratamento de erros

Sempre valide o JSON: Use blocos try-catch para tratar entradas malformadas de forma adequada.
Registre os erros corretamente: Escreva os erros em stderr para que fiquem visíveis quando show_output estiver ativado.
Falhe com segurança: Se o seu hook encontrar um erro, avalie se ele deve bloquear a ação ou permitir que ela continue.

Testando seus hooks

Comece registrando logs: Implemente um hook simples de logging para entender o fluxo de dados.
Use show_output: true: Ative a exibição de saída durante o desenvolvimento para ver o que seus hooks estão fazendo.
Teste o comportamento de bloqueio: Verifique se o código de saída 2 bloqueia corretamente as ações em pre-hooks.
Verifique todos os caminhos de código: Teste cenários de sucesso e de falha nos seus scripts.

Distribuição Enterprise

Organizações Enterprise precisam aplicar políticas de segurança, requisitos de conformidade e padrões de desenvolvimento que usuários individuais não podem contornar. O Cascade Hooks dá suporte a isso por meio de configuração em nível do sistema, que tem precedência e não pode ser desativada por usuários finais sem permissões de root. Implante sua configuração obrigatória hooks.json nestes locais específicos do sistema operacional: macOS:

/Library/Application Support/Windsurf/hooks.json

Linux/WSL:

/etc/windsurf/hooks.json

Windows:

C:\ProgramData\Windsurf\hooks.json

Coloque seus scripts de hook em um diretório de sistema correspondente (por exemplo, /usr/local/share/windsurf-hooks/ em sistemas Unix).

Métodos de Implantação

As equipes de TI do Enterprise podem implantar hooks em nível de sistema usando ferramentas e fluxos de trabalho padrão: Gerenciamento de Dispositivos Móveis (MDM)

Jamf Pro (macOS) - Implante por meio de perfis de configuração ou scripts
Microsoft Intune (Windows/macOS) - Use scripts do PowerShell ou implantação por políticas
Workspace ONE, Google Endpoint Management e outras soluções de MDM

Gerenciamento de Configuração

Ansible, Puppet, Chef, SaltStack - Use sua automação de infraestrutura existente
Scripts de implantação personalizados - Scripts de shell, PowerShell ou suas ferramentas preferidas

Verificação e auditoria

Após a implantação, confirme que os hooks estão instalados corretamente e não podem ser contornados:

# Verificar se os hooks do sistema estão presentes
ls -la /etc/windsurf/hooks.json  # Linux
ls -la "/Library/Application Support/Windsurf/hooks.json"  # macOS

# Testar a execução do hook (a saída do hook deve aparecer no Cascade)
# Solicite que um desenvolvedor acione a ação relevante do Cascade

# Verificar se os usuários não podem modificar os hooks do sistema
sudo chown root:root /etc/windsurf/hooks.json
sudo chmod 644 /etc/windsurf/hooks.json

Importante: Hooks em nível de sistema são totalmente gerenciados pela sua equipe de TI ou segurança. O Windsurf não implanta nem gerencia arquivos em caminhos de sistema. Certifique-se de que suas equipes internas cuidem da implantação, das atualizações e da conformidade de acordo com as políticas da sua organização.

Hooks de workspace para projetos em equipe

Para convenções específicas de projeto, as equipes podem usar hooks no nível do workspace no controle de versão:

# Adicione ao seu repositório
.windsurf/
├── hooks.json
└── scripts/
    └── format-check.py

# Faça commit no git
git add .windsurf/
git commit -m "Adiciona hooks de workspace para formatação de código"

Isso permite que as equipes padronizem as práticas de desenvolvimento. Certifique-se de manter as políticas críticas de segurança no nível do sistema e de não registrar nenhuma informação sensível no controle de versão.

Recursos adicionais

Integração MCP: Saiba mais sobre o Model Context Protocol no Windsurf
Workflows: Descubra como combinar hooks com os Workflows do Cascade
Analytics: Acompanhe o uso do Cascade com o Analytics da Equipe

Editor

Cascade

Contas

Consciência de contexto

Resolução de problemas

Segurança

​O que você pode construir

​Como os Hooks Funcionam

​Configuração

​Nível do sistema

​Nível do usuário

​Nível de workspace

​Estrutura básica

​Opções de configuração

​Eventos de Hook

​Estrutura comum de entrada

​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

​Códigos de saída

​Exemplos de casos de uso

​Registro de todas as ações do Cascade

​Restringir acesso a arquivos

​Bloqueando comandos perigosos

​Executando formatadores de código após edições

​Boas práticas

​Segurança

​Considerações de desempenho

​Tratamento de erros

​Testando seus hooks

​Distribuição Enterprise

​Métodos de Implantação

​Verificação e auditoria

​Hooks de workspace para projetos em equipe

​Recursos adicionais

O que você pode construir

Como os Hooks Funcionam

Configuração

Nível do sistema

Nível do usuário

Nível de workspace

Estrutura básica

Opções de configuração

Eventos de Hook

Estrutura comum de entrada

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

Códigos de saída

Exemplos de casos de uso

Registro de todas as ações do Cascade

Restringir acesso a arquivos

Bloqueando comandos perigosos

Executando formatadores de código após edições

Boas práticas

Segurança

Considerações de desempenho

Tratamento de erros

Testando seus hooks

Distribuição Enterprise

Métodos de Implantação

Verificação e auditoria

Hooks de workspace para projetos em equipe

Recursos adicionais