Escrevendo Regras Hookify

Visão Geral

O ECC avalia regras Hookify locais do projeto com seu runtime Node integrado. Nenhuma instalação separada de plugin Hookify ou Python é necessária quando os hooks do ECC estão habilitados.

Regras Hookify são arquivos markdown com frontmatter YAML que definem padrões a serem observados e mensagens a serem exibidas quando esses padrões correspondem. As regras são armazenadas em arquivos .claude/hookify.{rule-name}.local.md.

Formato do Arquivo de Regra

Estrutura Básica

---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---

Message to show Claude when this rule triggers.
Can include markdown formatting, warnings, suggestions, etc.

Campos do Frontmatter

Formato Avançado (Múltiplas Condições)

---
name: warn-env-api-keys
enabled: true
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.env$
  - field: new_text
    operator: contains
    pattern: API_KEY
---

You're adding an API key to a .env file. Ensure this file is in .gitignore!

Campos de condição por evento:

• bash: command
• file: file_path, new_text, old_text, content
• prompt: user_prompt

Operadores: regex_match, contains, equals, not_contains, starts_with, ends_with

Todas as condições devem corresponder para que a regra seja acionada.

Guia de Tipo de Evento

Eventos bash

Corresponde a padrões de comando Bash:

• Comandos perigosos: rm\s+-rf, dd\s+if=, mkfs
• Escalação de privilégios: sudo\s+, su\s+
• Problemas de permissão: chmod\s+777

Eventos file

Corresponde a operações de Edição/Escrita/MultiEdição:

• Código de depuração: console\.log\(, debugger
• Riscos de segurança: eval\(, innerHTML\s*=
• Arquivos sensíveis: \.env$, credentials, \.pem$

Eventos stop

Verificações de conclusão e lembretes. O padrão .* corresponde sempre.

Eventos prompt

Corresponde ao conteúdo do prompt do usuário para aplicação do fluxo de trabalho.

Dicas para Escrever Padrões

Noções Básicas de Regex

• Caracteres especiais de escape: . a \., ( a \(
• \s espaço em branco, \d dígito, \w caractere de palavra
• + um ou mais, * zero ou mais, ? opcional
• | operador OU

Armadilhas Comuns

• Muito amplo: log corresponde a "login", "dialog" — use console\.log\(
• Muito específico: rm -rf /tmp — use rm\s+-rf
• Escapamento YAML: Use padrões sem aspas; strings entre aspas precisam de \\s

Teste

python3 -c "import re; print(re.search(r'your_pattern', 'test text'))"

Evite quantificadores aninhados como (a+)+. O runtime rejeita padrões com formas comuns de backtracking catastrófico porque as regras são executadas sincronamente no caminho do hook, e cada avaliação de regex tem um tempo limite rígido de 25 ms. Regras locais inválidas, com links simbólicos ou de tamanho excessivo falham abertas e emitem um diagnóstico sem desabilitar outras regras Hookify.

Regras locais rastreadas pelo Git são desabilitadas por padrão. Defina ECC_HOOKIFY_ALLOW_TRACKED=1 somente após revisar esses arquivos; regras comuns ignoradas pelo Git criadas localmente permanecem ativas sem essa substituição.

Comportamento do Runtime

• warn injeta a mensagem como contexto adicional específico do evento e não bloqueia.
• block nega chamadas Bash, PowerShell, Write, Edit ou MultiEdit correspondentes antes da execução.
• Em eventos prompt, post-tool e stop, block usa a decisão de bloqueio estruturada do Claude Code.
• Regras stop pulam eventos recursivos stop_hook_active para evitar loops de continuação infinitos.

Organização de Arquivos

• Localização: diretório .claude/ na raiz do projeto
• Nomeação: .claude/hookify.{descriptive-name}.local.md
• Gitignore: Adicione .claude/*.local.md a .gitignore

Comandos

• /hookify [description] - Cria novas regras (analisa automaticamente a conversa se não houver argumentos)
• /hookify-list - Visualiza todas as regras em formato de tabela
• /hookify-configure - Alterna regras interativamente
• /hookify-help - Documentação completa

Referência Rápida

Regra mínima viável:

---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
Warning message here