1. Hook de segurança que sai com exit 1 não bloqueia nada
Depois de configurar o Claude Code em vários projetos, identifiquei que o hook de segurança que sai com exit 1 (1) não impede nada. O Claude Code apenas ignora o código de saída 2 (um erro) e utiliza o que o hook escreve no stderr (sobretudo mensagens de erro) para tomar decisões. Qualquer código de saída diferente de 2 é considerado um erro não bloqueante. Se o seu hook for um 'nunca rode isso', sair com exit 1 só avisa.
2. "Nunca leia o .env" no CLAUDE.md é pedido, não regra
A regra 'Nunca leia o .env' no CLAUDE.md é um contexto, não uma regra obrigatória. Ela não impede um script de ler o arquivo .env diretamente. Para bloquear o acesso ao .env, é necessário definir uma regra deny no arquivo .claude/settings.json, como 'Read(./.env)', por exemplo. Mesmo assim, um script que abra o arquivo .env continuará sendo possível.
3. Em claude -p não existe o diálogo de confiança da pasta
No modo não interativo, os hooks do projeto e os servidores do .mcp.json rodam sem perguntas. Antes de rodar o comando claude -p no repositório de um cliente, é importante verificar o .claude/settings.json, o .mcp.json e as skills. Se não houver um .mcp.json, ou se ele estiver configurado de forma diferente, o comando não funcionará corretamente. Para evitar isso, rode o comando com opções como --bare ou --setting-sources user.
4. Revisor "somente leitura" com Bash não é somente leitura
Criar um revisor com apenas leitura (Edit e Write removidos) no campo tools de um subagente faz com que o Claude Code remova essas ferramentas do subagente. No entanto, se o revisor mantiver o Bash, um comando de shell ainda pode alterar arquivos, e o subagente herdará o modo de permissão da sessão.
5. Hook de segurança: Referências e documentação
Para entender melhor as configurações de hooks, permissoes e subagentes, consulte as seguintes referências:
- Hooks: https://code.claude.com/docs/en/hooks
- Permissoes: https://code.claude.com/docs/en/permissions
- Subagentes: https://code.claude.com/docs/en/sub-agents
- Headless: https://code.claude.com/docs/en/headless
Complemento
Os pontos 1 e 2 apresentados aqui batem com a documentação. Para o hook que não consegue rodar (por exemplo, script inexistente ou timeout), a versão recente (2.1.295 ou mais nova) do Claude Code faz o falha do hook bloquear a ação. Para a regra Read(./.env) no deny, a documentação diz que ela também pega cat, head, tail e redirecionamento no Bash. O que escapa é o grep -r, que abre o arquivo por conta própria, e para esses, o sandbox é a solução.
Considerações finais
Manter o harness (configuração) é um desafio. Existem muitos detalhes que devem ser cuidados. Este post foi favoritado via extensão TABNEWS FAVORITOS. Se você está curioso sobre IA, dê uma olhada no meu livro: IA para Engenheiros.