«Por favor, altera apenas os rascunhos» é uma instrução de trabalho sensata. Mas ainda não é um ponto de controlo técnico. Um hook pode aplicar uma regra recorrente no ponto em que uma ação específica foi preparada. Isto transforma um pedido genérico numa decisão verificável sobre uma chamada de ferramenta concreta.
A referência do Claude Code descreve, entre outros eventos, o PreToolUse: ocorre depois de os parâmetros da ferramenta terem sido criados e antes de a chamada ser processada. O hook pode devolver uma decisão. Os exemplos seguintes explicam um esboço nosso; não foi instalada nem executada qualquer configuração de hook para eles.
Que informação está disponível no ponto de decisão?
O nosso projeto de aprendizagem contém uma pasta de rascunhos e, ao lado, um ficheiro de referência. O agente só deve editar rascunhos. Uma regra sensata olha, por isso, para o destino concreto de uma ação de escrita. Não decide se todo o conteúdo da conversa é fiável.
A interface fornece o nome da ferramenta e a entrada. Para um pedido de ficheiro adequado, o destino pode ser determinado a partir deles. Uma ferramenta desconhecida ou uma entrada incompreensível deve desencadear um estado próprio. Um erro silencioso no programa de verificação não pode parecer um caminho verificado com sucesso.
Uma decisão é um valor de retorno estruturado
Um valor de recusa ilustrativo na estrutura documentada do PreToolUse tem este aspeto. O motivo é redação nossa; descreve a regra local, não uma avaliação geral do utilizador.
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "The target file is outside the drafts area."
}
}Este excerto é o valor de retorno, não um programa de verificação completo. Não contém nem o registo do hook nem a leitura e verificação da entrada. É precisamente esta separação que ajuda: a regra, a avaliação técnica e a saída da interface podem ser analisadas de forma independente.
Pertencer a um caminho é mais do que um prefixo coincidente
Uma mera comparação de cadeias de caracteres pode confundir pastas vizinhas com nomes semelhantes. Por isso, a tua própria regra deve trabalhar com caminhos resolvidos de forma inequívoca e verificar se o destino pertence efetivamente à pasta raiz pretendida. Separadores diferentes e ligações têm de ser tidos em conta no ambiente utilizado.
own rule logic, schematic:
Input fully readable? Otherwise check status unknown.
Tool belongs to the write path being handled? Otherwise not checked.
Resolve target and permitted root unambiguously.
Target really inside the root? Otherwise deny.
Assess only the specific call being handled.Este esboço não sugere, deliberadamente, uma proteção completa. Em particular, programas externos que alteram eles próprios outros ficheiros exigem uma consideração diferente da de um único campo de ficheiro. Um ficheiro inicial permitido ainda não diz nada sobre as ações subsequentes que um script executa.
Quatro testes tornam o alcance visível
Num projeto descartável, cria um ficheiro permitido, uma referência protegida e uma pasta vizinha com um nome semelhante. Acrescenta uma entrada inválida. Para cada caso, anota antecipadamente que decisão é esperada. Depois, observa tanto o valor de retorno como a execução real.
Testa também uma falha do próprio programa de verificação. O comportamento em caso de falha depende do evento e da configuração e, por isso, faz parte da aceitação. A ausência de uma mensagem não é prova de que a regra foi verificada com sucesso.
Para cada teste, anota também se o hook chegou sequer a ser alcançado. Uma ação que siga outro percurso pode contornar a regra sem que a verificação interna de caminhos tenha funcionado incorretamente.
Um hook não é uma estrutura de proteção completa
O PreToolUse diz respeito a chamadas de ferramentas. O contexto pode entrar na sessão por outras vias; a referência atual descreve explicitamente limites a este respeito. Por isso, um hook não substitui nem as permissões nem o controlo do ambiente, e não é uma salvaguarda geral contra a injeção de prompts.
Começa com uma única regra local e documenta as vias que ela abrange e não abrange. O ganho técnico está num ponto de controlo compreensível. Se este ponto de controlo está corretamente configurado na tua versão, só um ensaio real com as interfaces adequadas o pode mostrar.
Fontes e estado da documentação: 25 de outubro de 2026.
