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

O Claude Code usa regras de permissão com allow / ask / deny no settings.json para definir quais ferramentas, comandos, arquivos e domínios são permitidos sem confirmação, exigem aprovação ou são proibidos. Equipes podem compartilhá-las para rejeitar chamadas correspondentes e reduzir aprovações de tarefas comuns já revisadas. Elas não bloqueiam uniformemente outras formas de invocar o mesmo programa nem acessos por scripts.

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 utiliza um sistema de permissões em camadas. Tomando Manual como referência, leituras na área de trabalho normalmente não exigem confirmação, enquanto edições e execução de Bash normalmente exigem, com exceções como comandos integrados somente de leitura e regras allow. Sobre essa base, as regras especificam exceções individuais (fonte: “Configure permissions”, documentação oficial do Claude Code).

É fácil confundir regras com modos de permissão. Os modos definem a política geral de confirmação (default, acceptEdits, auto etc.); as regras especificam ferramentas e comandos individuais. Eles se complementam: os modos definem a base e as regras a modificam com instruções como “sempre permita isto” ou “negue esta chamada”.

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. Entre as regras comuns de configuração, a primeira correspondência decide, e a especificidade não muda a ordem. Um deny amplo Bash(aws *) bloqueia até um allow mais específico Bash(aws s3 ls). O ponto principal é que allow não pode anular um deny correspondente. A negação em caminhos relativos de Read/Edit é um recurso separado.

3. Sintaxe das regras (Tool(specifier))

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

As regras de MCP valem apenas para o servidor que elas nomeiam. A partir da v2.1.299 (14 de outubro de 2026), mcp__a não permite outros servidores chamados a__b ou a_. Para um servidor cujo nome contenha __ ou termine com _, escreva o nome normalizado completo seguido de __*, como em mcp__reports__v2__* (documentação oficial e histórico de alterações, verificado em 18 de outubro de 2026).

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 ou nega chamadas específicas; não bloqueia todas as vias para o mesmo programa
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Comandos compostos são avaliados por subcomando, e invólucros reconhecidos são removidos antes da avaliação. Porém, outras formas de invocar o mesmo programa nem sempre correspondem: Bash(git push *) não corresponde a git -C . push. Comandos integrados somente de leitura normalmente dispensam confirmação, mas restrições de leitura fora da área de trabalho e esperas pelo classificador de auto são condições separadas.

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

* /Users/... NÃO é absoluto — é relativo à âncora do arquivo de configuração (a raiz do projeto nas configurações do projeto). Nas configurações do usuário, Read(/secrets/**) aponta para ~/.claude/secrets/**; para uma regra que valha em todos os projetos, use // ou ~/. 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

Os valores das configurações são resolvidos pela hierarquia. Para regras de permissão, um deny correspondente é avaliado antes de allow. A tabela descreve a prioridade entre regras de arquivos de configuração e da CLI; não é uma garantia absoluta que também abranja mudanças de decisão por mods.

// .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). Mas auto e bypassPermissions não têm efeito nas configurações de projeto (.claude/settings.json, .claude/settings.local.json); coloque-os nas configurações de usuário ou gerenciadas. Para ler/editar fora do diretório de trabalho, adicione caminhos a additionalDirectories.

5. Receitas práticas

Comece por restringir allow a chamadas comuns revisadas e usar ask/deny nas chamadas que deseja limitar. Isso não controla automaticamente outras formas de realizar a mesma operação nem tudo o que ocorre dentro de um script permitido.

A correspondência de argumentos Bash não basta para impor restrições de URL. Mesmo uma política que negue curl/wget e use WebFetch deixa vias por caminhos absolutos, sh -c e outros programas. Regras de domínio do WebFetch controlam essa ferramenta, não todo o tráfego de Bash. Para impor destinos, combine controles como a lista de destinos permitidos do sandbox e gerencie separadamente ferramentas e novas tentativas fora do sandbox.

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.
• Deny de Read/Edit não impede acesso indireto. Aplica-se a ferramentas de arquivo integradas e a cat/head/sed, mas não a scripts Python ou Node que abrem arquivos por conta própria. Outra exceção são operações recursivas como grep -r pattern ., que não nomeiam o arquivo de destino. Restrições do sistema operacional se aplicam a processos dentro do sandbox; Read integrado, MCP e outras vias precisam de controles separados.
• 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 anulam regras. Um hook PreToolUse pode ampliar permissões, mas deny/ask são avaliados independentemente do resultado. Porém, tool.check de um mod pode substituir a decisão em uma etapa posterior. Pode aprovar ask e, em ambientes pessoais sem configurações gerenciadas, também deny. Em dispositivos gerenciados e Team/Enterprise, deny tem prioridade por padrão, embora configurações da organização possam mudar isso. É preciso decidir se você confia nos mods instalados.
• No modo automático, até um comando da sua lista allow pode passar pelo classificador. Ao entrar no modo automático, as regras allow amplas que permitem executar código arbitrário (Bash(*) irrestrito, interpretadores com curinga como Bash(python*), comandos run de gerenciadores de pacotes, regras Agent etc.) são retiradas e voltam quando você sai do modo; regras estreitas como Bash(npm test) continuam valendo. As regras só coincidem como estão escritas, então Bash(git push *) não coincide com git -C . push, e um comando sem regra correspondente é julgado pelo classificador. Escritas em caminhos protegidos também passam pelo classificador, mesmo com uma regra allow. Se uma ação legítima for bloqueada, dá para tentar de novo pelo Recently blocked (Recently denied antes da v2.1.314) em /permissions (veja modos de permissão). Também há issues no GitHub relatando comandos permitidos que foram bloqueados (por exemplo, #95996). Este item segue a documentação oficial (Choose a permission mode) em 9 de outubro de 2026.

* O comportamento segue a documentação oficial do Claude Code (Configure permissions / Settings files and precedence / Choose a permission mode), em 9 de outubro 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 (a primeira correspondência vence; a especificidade não importa). Entre regras de configuração, allow não pode anular um deny correspondente. Níveis: managed > CLI > local > project > user.
• 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.

Entenda a que cada regra corresponde e reduza apenas as aprovações que precisa reduzir. Combine regras com modos de permissão e hooks. Considere um sandbox quando precisar de restrições efetivas de arquivos ou rede. Distinga qual camada cobre cada via.

Se você quer investigar o estado atual e receber orientação sem alterar o código, consulte como usar Codex e Claude Code apenas para investigar. O guia inclui os passos no aplicativo, no IDE e na CLI, além de uma instrução para impedir que o agente passe à implementação.

FAQ

O alcance e as exceções das permissões e do isolamento foram novamente conferidos na documentação oficial original em 9 de outubro de 2026. Não foram alteradas configurações do dispositivo nem realizados testes de inicialização.