​

Hooks e automatização

​

O que são hooks

• rejeitar entradas de ferramentas inseguras antes da execução;
• executar verificações locais depois de chamadas de ferramentas selecionadas;
• acrescentar contexto limitado quando uma sessão ou prompt começa;
• registar sinais de auditoria locais sem expor segredos;
• notificar outro processo local quando ocorre um evento do ciclo de vida.

​

Eventos suportados

​

Localizações dos hooks

• .compass/hooks/ no projeto;
• ~/.compass/hooks/ para hooks pessoais.

.compass/hooks/PreToolUse.yaml
.compass/hooks/PreToolUse/protect-env.yaml
.compass/hooks/UserPromptSubmit/context.md

​

Frontmatter

---
description: Run a local policy check before file-writing tools
enabled: true
tools:
  - write_file
  - edit_file
timeout: 10000
---
node .compass\hook-scripts\check-write-policy.mjs

• description — objetivo legível para pessoas;
• enabled — define false para ignorar o hook;
• tools — padrões glob de nomes de ferramentas para PreToolUse e PostToolUse;
• timeout — tempo limite do processo, em milissegundos.

​

Exemplo portátil de PreToolUse

#!/usr/bin/env node

let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => { input += chunk; });
process.stdin.on('end', () => {
  let event;
  try {
    event = JSON.parse(input);
  } catch {
    console.error('Invalid hook input; blocking by project policy.');
    process.exit(1);
  }

  if (!event || typeof event !== 'object' || Array.isArray(event)) {
    console.error('Invalid hook event; blocking by project policy.');
    process.exit(1);
  }

  const path = String(event.tool_input?.path ?? '');
  if ((event.tool_name === 'write_file' || event.tool_name === 'edit_file') && /(^|[\\/])\.env$/i.test(path)) {
    console.error('Writing .env files is blocked by project policy.');
    process.exit(1);
  }

  process.exit(0);
});

​

Entrada do hook

• session_id;
• transcript_path;
• cwd;
• hook_event_name.

​

Estado de saída e resultado

• o código de saída 0 permite que o processamento continue;
• um código de saída diferente de zero bloqueia a chamada da ferramenta;
• o erro padrão e, em seguida, a saída padrão são usados como explicação do bloqueio quando disponíveis.

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Apply the repository's checked-in release policy."
  }
}

​

Ativar ou desativar hooks

nova config set hooks.enabled true
nova config set hooks.enabled false

​

Recomendações de desenho

1. Usa NOVA.md para orientação e hooks para aplicação. Um hook só é adequado quando é necessária uma verificação determinística do ciclo de vida.
2. Falha de forma fechada apenas para verificações de elevada confiança. Um hook PreToolUse com falsos positivos pode bloquear trabalho legítimo.
3. Mantém os hooks rápidos. Operações de rede longas tornam cada chamada de ferramenta mais lenta e menos fiável.
4. Não imprimas segredos. A saída do hook pode ficar visível em diagnósticos ou contexto injetado.
5. Não dupliques aprovações da Nova. Os hooks podem adicionar restrições específicas da organização, mas não devem enfraquecer nem contornar o gestor de aprovações.
6. Testa scripts fora da Nova primeiro. Fornece JSON representativo através da entrada padrão e confirma os códigos de saída no sistema operativo de destino.
7. Revê hooks do projeto após atualizar alterações. São políticas executáveis, não documentação passiva.

​

Resolução de problemas

• Confirma o diretório e a grafia exata do evento.
• Confirma que a extensão é suportada ou que um ficheiro sem extensão começa com um shebang.
• Verifica que o interpretador configurado existe na máquina atual.
• Mantém caminhos válidos para a shell de destino; corpos .yaml, .yml e .md usam a shell da plataforma.
• Confirma que o padrão tools do hook corresponde ao nome da ferramenta em runtime.
• Reproduz o script com JSON de teste capturado e inspeciona o código de saída.
• Reduz trabalho lento ou aumenta timeout apenas dentro do limite da Nova.
• Executa nova doctor para verificar se os hooks foram desativados pela configuração.

​

Recapitulação

​

Prática segura