Hooks executam comandos de shell em pontos fixos de uma sessão: depois que um arquivo é escrito, antes de uma ferramenta rodar, quando um turno termina. São a única parte da configuração que executa código sem pedir permissão toda vez, o que torna vantajoso caçar suas falhas silenciosas. Um matcher que nomeia uma ferramenta inexistente nunca dispara e nunca reclama. Um comando que procura um argumento recebe uma string vazia, porque o evento chega pela entrada padrão como JSON e não como argumentos. E só alguns eventos conseguem realmente impedir o que estava prestes a acontecer. Este criador cobre os três casos e diz quais eventos bloqueiam e quais apenas observam.
Recursos
Cada evento listado com o que o dispara
Matchers conferidos contra nomes reais, com diferença de maiúsculas detectada
Avisa quando há matcher num evento sem ferramenta
Avisa quando um comando busca argumentos que nunca vai receber
Diz quais eventos podem bloquear uma ação, e como
Padrões de matcher comuns como atalhos de um clique
Vários hooks agrupados corretamente por evento e matcher
Aponta um comando destrutivo antes que ele rode sem supervisão
Como usar Construtor de hooks
Escolha o evento em que quer agir
Acrescente um matcher se o evento for específico de ferramenta
Escreva o comando lendo a carga pela entrada padrão
Leia os avisos e junte a saída ao settings.json
Exemplo
Entrada
prettier --write "$1"
Saída
Warning: $1 will be empty — a hook is not given arguments
O evento chega como JSON por pipe; leia com jq.
Erros comuns e solução de problemas
O hook nunca roda. — Quase sempre o matcher. Nomes são capitalizados e diferenciam maiúsculas — Write, não write — e um nome inexistente não casa com nada, em silêncio.
O comando roda mas não recebe entrada. — A entrada do hook chega como JSON pela entrada padrão. Leia com algo como jq -r '.tool_input.file_path' em vez de esperar um argumento.
Meu hook não consegue impedir a chamada. — Só alguns eventos conseguem, e só saindo com status 2. Qualquer outra coisa é lida como “siga em frente”, e eventos como PostToolUse disparam depois do fato de qualquer jeito.
A sessão trava no meu hook. — Defina um tempo limite. Um hook que espera por algo — uma chamada de rede, um lock — segura a sessão inteira enquanto isso.
Perguntas frequentes
Que evento usar para um formatador?
PostToolUse com um matcher para as ferramentas de escrita, para rodar quando o arquivo já existe. Formatar antes de escrever não tem nada para formatar.
Como o hook recebe o evento?
Como JSON pela entrada padrão: o nome da ferramenta, a entrada dela e o contexto em volta. Nada chega como argumento de linha de comando, e por isso um comando escrito em torno de $1 não recebe nada.
Um hook pode impedir uma ferramenta de rodar?
Antes de ela rodar, sim: sair com status 2 bloqueia. Quais eventos permitem isso aparece conforme você escolhe, porque tentar bloquear a partir de um evento que dispara depois é um erro tão comum quanto confuso.
Hooks rodam sem perguntar?
Sim, esse é o ponto deles e a razão de ler qualquer hook com atenção antes de acrescentar. Um que apaga arquivos é apontado aqui, mas a regra geral é que tudo neste arquivo roda sem supervisão.
Posso ter vários hooks num evento?
Sim. Os que compartilham evento e matcher ficam agrupados na saída, que é o formato esperado pelo arquivo de configuração.