Configurando um hook

Onde a configuração vive

A configuração dos hooks vive nos arquivos de ajustes do Claude Code, os mesmos que guardam as regras de permissão que você viu no módulo de segurança. Isso significa que a lógica de escopo é a que você já conhece: um hook pode ser do projeto, compartilhado com o time pelo controle de versão, ou pessoal, valendo em todos os seus projetos. Um hook de projeto é ótimo para regras que toda a equipe deve seguir naquele código, como sempre formatar de um jeito; um hook pessoal, para automações suas. Colocar o hook no arquivo de ajustes certo segue a mesma decisão de sempre: quem deve ser coberto por esta regra automática?

A estrutura da configuração parece ter várias camadas à primeira vista, mas ela só diz três coisas. Primeiro, em qual evento o hook dispara, como antes de uma ferramenta. Segundo, um filtro que restringe para quais casos, como só para a ferramenta de rodar comandos, e não para todas. Terceiro, o comando que deve rodar. Se você ler qualquer configuração de hook com essas três perguntas na cabeça, em qual evento, para quais casos, qual comando, ela deixa de parecer complicada. As camadas existem justamente para organizar essas três respostas, permitindo, por exemplo, vários filtros e comandos diferentes para o mesmo evento.

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      { "type": "command", "command": "meu-verificador.sh" }
    ]
  }
]

A ideia de um hook: no evento antes de uma ferramenta, filtrando pela de rodar comandos, execute um script.

O hook recebe informações do que acontece

Um hook não roda às cegas: quando dispara, o Claude Code passa a ele informações sobre o que está acontecendo. Se é um evento de antes de uma ferramenta, o hook recebe qual ferramenta é e o que ela vai fazer, por exemplo, qual comando será rodado ou qual arquivo será editado. O comando do hook lê essas informações e decide como agir. É isso que permite hooks inteligentes: um hook de segurança lê o comando que o agente quer rodar, verifica se é perigoso e, se for, o bloqueia; um hook de formatação lê qual arquivo foi editado e roda o formatador naquele arquivo específico. As informações dão ao hook o contexto para agir com precisão.

Essas informações chegam ao hook num formato estruturado, que o comando lê da entrada, como se recebesse um bilhete com os detalhes do evento. Você não precisa se preocupar com o formato exato agora; o importante é entender que o hook tem acesso ao contexto do que está acontecendo. Isso é o que separa um hook útil de um genérico: em vez de rodar sempre a mesma coisa cegamente, ele pode olhar os detalhes, qual ferramenta, qual arquivo, qual comando, e agir de forma adequada a cada caso. Um bom hook usa essas informações para ser específico, poderoso e seguro, atuando só quando e como deve.

Assim como comandos e subagentes, você não precisa escrever a configuração do hook à mão. O jeito mais fácil é pedir ao Claude Code: descreva a regra que quer automatizar, algo como configure um hook que bloqueia comandos destrutivos antes de rodarem, e o agente monta a configuração e o script para você, no arquivo de ajustes certo. Depois, você revisa o que ele gerou, especialmente por ser um hook que roda automaticamente, e ajusta se preciso. É a mesma filosofia de sempre: você decide a intenção, o agente cuida da mecânica, e você revisa o resultado, com atenção redobrada por se tratar de automação que vai valer sozinha.

Revisar um hook com atenção redobrada

Há uma razão para revisar um hook com mais cuidado que um comando comum: ele vai rodar sozinho, muitas vezes, sem você olhar a cada vez. Um erro num pedido único você percebe e corrige na hora; um erro num hook se repete silenciosamente sempre que o evento acontece. Por isso, ao configurar um hook, teste-o e leia bem o que ele faz antes de confiar. Confirme que ele dispara no evento certo, filtra os casos certos e roda o comando certo. Um hook bem revisado é uma bênção, pois automatiza uma regra sem esforço; um hook mal revisado é uma dor de cabeça recorrente, porque o problema volta toda vez.

Com a configuração dominada, você sabe montar um hook: escolher o evento, filtrar os casos, ligar o comando e revisar com cuidado. A próxima aula aprofunda o uso mais poderoso dos hooks, o de bloquear ações, mostrando como um hook pode impedir algo perigoso de acontecer de forma garantida, e por que isso é uma camada de segurança que nenhuma sugestão oferece. É onde os hooks mostram todo o seu valor: transformar uma regra de segurança crítica numa lei que o agente simplesmente não consegue violar, por mais que tente.