Como um hook bloqueia uma ação?

No evento de antes de uma ferramenta, o hook lê o que o agente está prestes a fazer, avalia conforme a sua regra e, se for proibido, sinaliza o bloqueio. O Claude Code respeita o sinal e a ação não acontece. Como o hook roda sempre, o bloqueio é garantido.

Por que o bloqueio por hook é garantido?

Porque o hook é determinístico: sempre que o evento dispara, ele roda e impõe a regra, sem depender de o agente decidir obedecer. Diferente do CLAUDE.md, que sugere, o hook impõe. Por isso serve para regras críticas de segurança que precisam valer sempre, sem exceção.

Hooks substituem as regras de permissão?

Não. Eles se somam numa defesa em camadas. As regras de permissão bloqueiam por padrões simples; os hooks aplicam lógica programável garantida; a revisão humana julga o que passa. Juntas, formam uma malha difícil de furar. Para o crítico, ter mais de uma camada cobrindo é o mais seguro.

Um hook pode atrapalhar bloqueando demais?

Pode, se mal configurado. Como impõe de forma garantida, um filtro amplo demais ou uma verificação mal calibrada pode barrar ações legítimas. Se o Claude Code recusar coisas de forma estranha, cheque se um hook está pegando demais. A mira certa é bloquear o perigoso sem barrar o legítimo.

Módulo 12 - Hooks

Hooks que bloqueiam e a segurança garantida

7 min de leitura · por Cesar Gargiulo, revisado pela equipe ValorFinal e GuardiaSec · Atualizado em 13/07/2026

O que você vai aprender

Entender como um hook bloqueia uma ação.
Ver por que o bloqueio por hook é garantido.
Combinar hooks com regras de permissão.
Usar hooks para segurança crítica.

Impedir uma ação de forma garantida

O uso mais poderoso de um hook é bloquear. No evento de antes de uma ferramenta, o hook age com a ação ainda por vir, e ele pode fazer mais do que observar: pode dizer ao Claude Code para não executar aquela ação. Na prática, o hook lê o que o agente está prestes a fazer, avalia conforme a sua regra e, se for algo proibido, sinaliza o bloqueio. O Claude Code respeita esse sinal e a ação não acontece. Como o hook roda sempre que o evento dispara, esse bloqueio é garantido: não importa o que o agente decida, se a sua regra diz não, o hook impõe o não. É uma trava de verdade, não uma sugestão.

Compare com o que você viu antes. As regras de permissão, do módulo de segurança, já bloqueiam ferramentas e comandos, e são a sua primeira linha de defesa. O CLAUDE.md sugere, mas não garante. Os hooks adicionam uma camada com lógica própria: enquanto uma regra de permissão bloqueia por padrões simples, um hook pode aplicar qualquer verificação que você programar, por mais sofisticada. Ele pode, por exemplo, bloquear um comando só se ele atender a uma combinação específica de condições que uma regra simples não expressaria. Essa flexibilidade faz do hook a ferramenta certa para regras de bloqueio elaboradas, que vão além do que os padrões de permissão alcançam.

Diagrama mostrando o agente prestes a rodar um comando destrutivo, o hook de antes da ferramenta interceptando, avaliando a regra e sinalizando um bloqueio, com o Claude Code respeitando o sinal e a ação sendo impedida, tudo de forma garantida. — No evento de antes, o hook inspeciona a ação e pode bloqueá-la de forma garantida, sem depender do agente.

Hooks numa defesa em camadas

O poder dos hooks não substitui as outras defesas; ele se soma a elas numa defesa em profundidade. A ideia é ter várias camadas de proteção, para que, se uma falhar ou não cobrir um caso, outra pegue. No Claude Code, essas camadas são as regras de permissão, que bloqueiam por padrões; a revisão humana, que julga o que passa; e os hooks, que impõem regras programáveis de forma garantida. Juntas, elas formam uma malha de segurança difícil de furar. Para o que é realmente crítico, um comando que nunca pode rodar, um arquivo que nunca pode ser tocado, ter mais de uma camada cobrindo é o que dá tranquilidade de verdade.

Camadas que previnem

Regras de permissão: bloqueiam por padrões simples.
Hooks: bloqueiam por lógica programável, garantida.
Caminhos protegidos: defesas de fábrica.

Camada que julga

Revisão humana: o seu julgamento final.
Cobre o que as regras automáticas não pegam.
A responsabilidade que nenhuma automação remove.

🎮 Jogo da aula

Bloqueio por hook: verdade ou mito?

Para cada afirmação sobre hooks que bloqueiam, diga se é verdadeira ou falsa.

Um cuidado ao usar hooks para bloquear: como eles impõem regras de forma garantida, um hook mal configurado pode bloquear coisas que você não queria, atrapalhando o trabalho. Se o Claude Code começar a recusar ações legítimas de forma estranha, vale checar se um hook está pegando demais. Por isso a revisão cuidadosa da aula anterior é ainda mais importante em hooks de bloqueio: um filtro amplo demais ou uma verificação mal calibrada transforma uma proteção em obstáculo. O objetivo é bloquear exatamente o perigoso, sem barrar o legítimo, e acertar essa mira é o que separa um hook de segurança útil de um chato.

Quando usar hooks para segurança

Os hooks de bloqueio valem o esforço quando você tem uma regra de segurança crítica que precisa de garantia absoluta e que os padrões simples de permissão não expressam bem. Por exemplo: bloquear qualquer comando que combine certas condições específicas do seu ambiente, ou impedir alterações num tipo de arquivo sob circunstâncias particulares. Para regras simples, como bloquear uma ferramenta inteira, as regras de permissão já bastam e são mais fáceis. O hook entra quando a regra tem lógica, quando o sim ou não depende de olhar os detalhes e aplicar um critério que só um comando programável consegue. É a ferramenta certa para a segurança sob medida.

Com os hooks de bloqueio dominados, você tem a camada mais forte de garantia do Claude Code. A última aula do módulo mostra os hooks na prática, com exemplos além da segurança, como automatizar formatação e verificações, e reforça os cuidados para usá-los bem. Você vai sair sabendo transformar regras críticas em leis garantidas e tarefas repetitivas em automações confiáveis, com a consciência de que essa força pede responsabilidade. Os hooks fecham o conjunto de recursos que dão controle profundo sobre como o Claude Code se comporta, do sugerir ao garantir.

Teste rápido

Por que o bloqueio por hook é considerado garantido?

Perguntas frequentes

Como um hook bloqueia uma ação?: No evento de antes de uma ferramenta, o hook lê o que o agente está prestes a fazer, avalia conforme a sua regra e, se for proibido, sinaliza o bloqueio. O Claude Code respeita o sinal e a ação não acontece. Como o hook roda sempre, o bloqueio é garantido.
Por que o bloqueio por hook é garantido?: Porque o hook é determinístico: sempre que o evento dispara, ele roda e impõe a regra, sem depender de o agente decidir obedecer. Diferente do CLAUDE.md, que sugere, o hook impõe. Por isso serve para regras críticas de segurança que precisam valer sempre, sem exceção.
Hooks substituem as regras de permissão?: Não. Eles se somam numa defesa em camadas. As regras de permissão bloqueiam por padrões simples; os hooks aplicam lógica programável garantida; a revisão humana julga o que passa. Juntas, formam uma malha difícil de furar. Para o crítico, ter mais de uma camada cobrindo é o mais seguro.
Quando uso um hook em vez de uma regra de permissão?: Use a regra de permissão para bloqueios simples, como barrar uma ferramenta inteira. Use o hook quando o bloqueio tem lógica, quando o sim ou não depende de olhar os detalhes e aplicar um critério que um padrão simples não expressa. O hook é a segurança sob medida, mais poderosa e flexível.
Um hook pode atrapalhar bloqueando demais?: Pode, se mal configurado. Como impõe de forma garantida, um filtro amplo demais ou uma verificação mal calibrada pode barrar ações legítimas. Se o Claude Code recusar coisas de forma estranha, cheque se um hook está pegando demais. A mira certa é bloquear o perigoso sem barrar o legítimo.

Fontes

Seu progresso fica salvo neste aparelho. Assinantes sincronizam entre os aparelhos.

← Configurando um hook Concluir e avançar →