Como criar um hook no Claude Code para bloquear edições em .env e arquivos protegidos

Um hook no Claude Code é um comando de shell que a ferramenta executa em momentos fixos do seu ciclo de vida. Neste tutorial você vai criar um hook que impede o assistente de alterar arquivos sensíveis, como .env, package-lock.json e qualquer coisa dentro de .git/. O passo a passo segue o guia oficial de hooks da Anthropic.

O que é um hook e por que usar

Hooks dão controle determinístico: certas ações sempre acontecem, em vez de depender de o modelo decidir. Segundo a documentação, servem para impor regras do projeto, automatizar tarefas repetitivas e integrar o Claude Code ao que você já usa.

O hook deste tutorial roda antes de cada chamada às ferramentas Edit ou Write (evento PreToolUse). Se o arquivo de destino estiver na lista de proteção, o script encerra com código de saída 2, e o Claude Code bloqueia a edição. A mensagem escrita pelo script vai para o Claude como retorno, e ele pode ajustar o plano.

Pré-requisitos

• Claude Code instalado e funcionando em um projeto.
• O utilitário jq, usado para ler o JSON que o Claude Code envia ao hook. A documentação indica brew install jq no macOS e apt-get install jq no Debian e no Ubuntu.
• Um terminal com acesso à pasta raiz do projeto (Linux, macOS ou Windows com bash).

Passo 1: criar o script do hook

Na raiz do projeto, crie a pasta .claude/hooks e salve o arquivo .claude/hooks/protect-files.sh com este conteúdo, que é o exemplo da documentação oficial:

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

O que o script faz, linha a linha: lê o JSON da entrada padrão, extrai o caminho do arquivo com jq, troca barras invertidas do Windows por barras normais e compara o caminho com a lista PROTECTED_PATTERNS. Se houver correspondência, escreve o motivo na saída de erro e sai com código 2. Qualquer outro caso termina com código 0 e a edição segue normalmente.

Para proteger outros arquivos, acrescente padrões à lista, por exemplo "yarn.lock".

Passo 2: tornar o script executável

No macOS e no Linux, o script precisa de permissão de execução para o Claude Code conseguir rodá-lo:

chmod +x .claude/hooks/protect-files.sh

Passo 3: registrar o hook nas configurações

Abra ou crie o arquivo .claude/settings.json na raiz do projeto e adicione o hook PreToolUse:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

O campo matcher define a quais ferramentas o hook se aplica. Aqui, Edit|Write cobre as duas ferramentas de edição de arquivos. A variável $CLAUDE_PROJECT_DIR aponta para a raiz do projeto, o que permite usar o script de qualquer subpasta.

Se o seu settings.json já tiver uma chave hooks, não substitua o objeto inteiro. Adicione PreToolUse como irmã dos eventos existentes. Cada nome de evento é uma chave dentro do mesmo objeto hooks.

Passo 4: conferir se o hook foi carregado

Dentro do Claude Code, digite /hooks. A tela lista os hooks configurados, e o seu deve aparecer sob PreToolUse. Se não aparecer, revise o JSON, porque uma vírgula fora do lugar impede a leitura do arquivo.

Passo 5: testar

Peça ao Claude para adicionar um comentário ao arquivo .env do projeto. O resultado esperado, segundo a documentação, é que o Claude Code bloqueie a edição antes de ela acontecer e entregue ao modelo a mensagem que começa com Blocked:. O arquivo permanece intacto, e o assistente costuma explicar que não pôde editar e propor outro caminho.

Para um teste sem o modelo, simule a entrada do hook direto no terminal:

echo '{"tool_input":{"file_path":".env"}}' | .claude/hooks/protect-files.sh; echo "saída: $?"

O comando deve imprimir a mensagem de bloqueio e saída: 2. Com um arquivo comum, como src/app.js, o código de saída será 0.

Erros comuns

• O hook não roda: confirme que o script está executável (chmod +x) e que o caminho no command está certo.
• Erro de comando não encontrado para jq: instale o jq, pois o script depende dele.
• Bloqueia arquivos demais: o padrão .env casa com qualquer caminho que contenha esse texto, inclusive .env.example. Ajuste os padrões se isso for um problema.
• Chave hooks duplicada: em JSON, repetir a mesma chave faz a última valer. Reúna tudo em um único objeto.
• Mudou o settings e nada acontece: use /hooks para verificar o que foi carregado.

Um aviso sobre falhas do próprio hook

O changelog do Claude Code registra, na versão 2.1.295, de 8 de outubro de 2026, a opção onFailure: "block" para hooks de comando e HTTP: um hook que não consegue iniciar, estoura o tempo ou termina de forma inesperada passa a bloquear a ação. O guia não detalha esse campo no trecho usado aqui, então consulte a referência de hooks da documentação antes de aplicá-lo.

Resultado

Com o script, a permissão e o registro no settings.json, o Claude Code passa a recusar edições em .env, package-lock.json e .git/ em qualquer sessão deste projeto. Se commitar a pasta .claude no repositório, a regra vale para toda a equipe.