Regras de permissão do Claude Code e o settings.json

As regras de permissão do Claude Code permitem que você escreva entradas allow / ask / deny no settings.json para especificar, de forma granular, quais ferramentas, comandos, arquivos e domínios são executados sem perguntar, exigem confirmação a cada vez ou ficam proibidos. Elas podem ser compartilhadas com toda a equipe, então você bloqueia o que é perigoso com certeza enquanto deixa o trabalho seguro e rotineiro rodar sem interrupções.

Este guia cobre o que são as regras de permissão (e em que elas diferem dos modos de permissão), a prioridade entre allow/ask/deny, a sintaxe das regras, a hierarquia do settings.json e receitas práticas — tudo com base na especificação oficial.

1. O que são as regras de permissão (vs. modos)

O Claude Code usa um sistema de permissões em camadas. Leituras (visualização de arquivos, Grep, etc.) não precisam de aprovação; comandos Bash e edições de arquivo precisam — e, por cima desse patamar base, as regras permitem especificar exceções granulares (fonte: "Configure permissions", documentação oficial do Claude Code).

É fácil confundir regras com modos de permissão. Modos são o patamar amplo de "com que frequência ele pergunta" (default/acceptEdits/auto, etc.); regras são especificações por ferramenta e por comando. Eles trabalham juntos — o modo define o patamar base e as regras o sobrescrevem com "sempre permitir isto" ou "nunca permitir aquilo".

2. allow / ask / deny e a ordem de prioridade

Existem três tipos de regra. O comando /permissions lista e edita essas regras (e mostra de qual settings.json cada uma vem).

As regras são avaliadas na ordem deny → ask → allow. A primeira correspondência decide o resultado, e a especificidade da regra não altera essa ordem. Um deny amplo como Bash(aws *) vence um allow mais específico como Bash(aws s3 ls). A questão: um deny não pode carregar exceções de lista de permissão.

3. Sintaxe das regras (Tool(specifier))

O formato é Tool (tudo) ou Tool(specifier) (específico). Cada ferramenta tem seu próprio estilo de specifier.

Curingas do Bash podem aparecer em qualquer lugar. Bash(ls *) (espaço + *) corresponde a ls -la mas não a lsof (limite de palavra); Bash(ls*) (sem espaço) corresponde a ambos. Um :* ao final equivale a *.

// Permite comandos seguros, bloqueia git push
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Atenção aos comandos compostos. O Claude Code entende separadores como && || ; |, e cada subcomando precisa corresponder de forma independente. Bash(safe-cmd *) não permite safe-cmd && rm -rf .. Note que comandos somente leitura (ls/cat/grep/find/pwd, etc.) rodam sem pergunta em todos os modos, e wrappers como timeout/nice/nohup são removidos antes da correspondência.

Caminhos de Read/Edit seguem a semântica do gitignore com quatro âncoras:

※ /Users/... NÃO é absoluto — é relativo à raiz do projeto. Use //Users/... (barra dupla) para caminhos absolutos. Read(.env) equivale a Read(**/.env) e corresponde a todos os .env abaixo.

4. Hierarquia e prioridade do settings.json

As regras ficam no settings.json. Há vários arquivos, e os níveis mais altos são mais fortes. A regra-chave: um deny em qualquer nível sempre vence um allow em qualquer outro nível.

// .claude/settings.json (compartilhado pela equipe)
{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(npm run *)", "WebFetch(domain:docs.example.com)"],
    "deny": ["Read(.env)", "Read(**/secrets/**)", "Bash(git push *)"],
    "additionalDirectories": ["../shared-lib"]
  }
}

O modo de permissão padrão também é definido aqui, como defaultMode (detalhes dos modos). Para ler/editar fora do diretório de trabalho, adicione caminhos a additionalDirectories.

5. Receitas práticas

Combinações comuns. A forma básica: bloqueie o perigoso com certeza, permita a rotina segura para automatizá-la.

Restringir URLs por padrões de argumento do Bash é frágil (curl http://github.com/ * é facilmente burlado por -X GET ou expansão de variáveis). Em vez disso, bloqueie curl/wget e permita domínios específicos com WebFetch(domain:...). Para um controle mais rígido, valide as URLs em um hook PreToolUse.

6. Pegadinhas e confusões comuns

• O deny é aplicado pelo Claude Code, não pelo modelo. Escrever "não leia isto" no seu prompt ou no CLAUDE.md não o impedirá sem uma regra.
• O deny de Read/Edit não consegue impedir o acesso indireto. Ele se aplica às ferramentas de arquivo nativas e a cat/head/sed, mas não a um script Python ou Node que abre arquivos por conta própria. Para aplicação em nível de SO, use também sandboxing.
• Cuidado com executores de ambiente. devbox run *, npx e docker exec executam seus argumentos como um comando, então Bash(devbox run *) também permite devbox run rm -rf .. Escreva regras que incluam o comando interno.
• Hooks não sobrescrevem regras. Um hook PreToolUse pode estender permissões, mas deny/ask são avaliados independentemente do que o hook retorna (a regra de deny-primeiro não muda).

※ O comportamento segue a documentação oficial do Claude Code (Configure permissions / Settings), em junho de 2026. Ele pode mudar — consulte a documentação oficial para a versão mais recente.

Resumo

Três pontos essenciais sobre as regras de permissão do Claude Code.

• O que são: allow/ask/deny no settings.json para conceder/perguntar/proibir por ferramenta, comando, arquivo e domínio. Os modos definem o patamar base; as regras cuidam dos detalhes.
• Prioridade: deny → ask → allow (vence a primeira correspondência; a especificidade é irrelevante). Um deny em qualquer nível sempre vence. Níveis: gerenciado > CLI > local > projeto > usuário.
• Sintaxe: Tool(specifier). Bash usa curingas (espaço + * é um limite de palavra), Read/Edit usam caminhos no estilo gitignore, WebFetch usa domain:. Comandos compostos exigem que cada subcomando corresponda.

"Bloqueie o perigoso com certeza, automatize a rotina segura" é o coração do design de regras. Combine isso com os modos de permissão, os hooks e a configuração de esforço para rodar o Claude Code com segurança e fluidez.

FAQ