Permissões do Claude Code: regras allow, deny e ask, explicadas
Um passo a passo quadro a quadro de como o Claude Code pede permissão: as três opções do prompt, as regras allow salvas no settings.local.json, a ordem de avaliação com deny primeiro, os modos de permissão e as receitas que fazem o dia a dia de código e a CI perguntarem menos — com a documentação oficial preenchendo cada lacuna que o vídeo deixa.
Permissões do Claude Code em 60 segundos
- O Claude Code pergunta antes de Bash, Edit, WebFetch e Write; Read, Glob, Grep e LS rodam sem perguntar.
- “Yes, and don't ask again” salva uma regra como Bash(git add:*) no .claude/settings.local.json — seu caderno de regras pessoal, excluído do git, daquele repositório.
- As regras são avaliadas deny → ask → allow: um deny de qualquer arquivo de settings vence, e nenhuma regra allow consegue abrir exceção nele.
- Os modos dosam a confiança: acceptEdits (alt+m) para trabalho cheio de edições, plan para reconhecimento somente leitura, bypassPermissions para CI via --permission-mode — e os valores defaultMode auto e bypassPermissions só têm efeito vindos de settings user ou managed.
Claude Code Tutorial #4 - Tools & Permissions
Canal:The Net Ninja4:55
Permission Modes Head to Head
Canal:ttywood6:20
Permissions — Claude Code documentation
Docs:code.claude.com
Settings files — Claude Code documentation
Docs:code.claude.com
Cada frame vem da gravação do Net Ninja, uma captura de tela limpa, sem câmera nem overlays. O episódio do ttywood que compara os modos de permissão frente a frente serviu de contraprova para as seções de modos e receitas, mas não contribuiu com frames — os dele têm legendas queimadas. Sintaxe de regras, ordem de avaliação, comportamento dos modos e precedência de arquivos de settings estão verificados contra as duas páginas de documentação oficiais.
Vídeos © The Net Ninja e ttywood, apenas linkados. Documentação © Anthropic. Capturas de tela são referenciadas neste guia para fins de comentário.
Configurar as permissões do Claude Code, passo a passo
O que o Claude Code pergunta antes de agir
- 1
Veja quais ferramentas disparam um prompt de permissão
O Claude Code escolhe as próprias ferramentas — Read para abrir arquivos, Edit para alterá-los, Bash para comandos de shell. A documentação de settings da Anthropic dedica a cada uma uma coluna Permission Required: Bash, Edit, WebFetch e Write param e perguntam, enquanto Read, Glob, Grep e LS simplesmente rodam. Você nunca digita nomes de ferramentas; o ponto é saber de antemão quais ações vão pausar por você.
A documentação de settings do Claude Code lista cada ferramenta nativa com o veredito em Permission Required.Ver em 1:05 - 2
Peça uma edição e veja ele ler primeiro
No vídeo, o pedido é propositalmente pequeno: adicionar uma variável --highlight amarelo-pastel ao src/app/globals.css. O Claude Code lê o arquivo primeiro — Read nunca pede permissão — e só para quando vai alterá-lo. Essa divisão é todo o modelo de permissões em miniatura: olhar é de graça, mexer pergunta.
O pedido da variável highlight digitado na entrada do Claude Code no VS Code.Ver em 1:45 - 3
Leia as três opções antes de responder
Todo prompt de edição oferece três respostas. 1. Yes aprova só esta edição. 2. Yes, and don't ask again this session aprova o resto das edições da sessão (alt+m na build mostrada). 3. No, and tell Claude what to do differently (esc) rejeita a mudança e deixa você tomar o rumbo. A opção 3 não é um fracasso — é assim que você corrige a rota antes do código pousar.
O prompt de edição do globals.css com as três opções de permissão visíveis.Ver em 2:17
Diga sim uma vez: salve uma regra allow
- 4
Espere um prompt por edição, não por tarefa
A aprovação não se estende à próxima mudança. A demo precisou de três Yes para três edições separadas do mesmo arquivo, e a mudança seguinte perguntou de novo. Aprovar-tudo-na-hora funciona, mas escala mal além de uma tarefa de duas linhas — é exatamente por isso que existem as regras allow e os modos.
Uma segunda edição do globals.css perguntando de novo logo depois da primeira aprovada.Ver em 2:32 - 5
Comandos de Bash perguntam separadamente
Comandos de shell têm o próprio portão. Quando a demo pede ao Claude fazer um commit, o Bash(git add src/app/globals.css) fica em estado Waiting até você responder. Um sim para um comando não é sim para o próximo — o git commit que vem depois pergunta por conta própria.
O comando git add esperando aprovação enquanto a saída anterior do git rola acima.Ver em 3:16 - 6
Deixe o “don't ask again” escrever a regra por você
Escolher Yes, and don't ask again para os comandos git add faz duas coisas ao mesmo tempo: destrava o comando atual e salva uma regra. O arquivo criado é o .claude/settings.local.json na raiz do repositório, com um objeto permissions e um array allow — aqui "Bash(git add:*)" — além de arrays deny e ask vazios. Todo git add futuro neste projeto roda sem perguntar.
settings.local.json criado sob .claude com a regra allow Bash(git add:*) salva.Ver em 3:40 - 7
Edite as regras à mão quando o diálogo não dá conta
O array allow é JSON puro, então você mesmo pode acrescentar regras. Use uma string exata para um único comando — Bash(npm run test) — e um :* no final para tudo que começa igual — Bash(npm run test:*). A documentação confirma que :* é o atalho do curinga final. Mantenha o arquivo pessoal: o Claude Code exclui o settings.local.json do git automaticamente, e o vídeo diz o mesmo — é para o seu fluxo de trabalho, não para o repositório.
A regra salva selecionada dentro de permissions.allow durante a edição manual do arquivo.Ver em 4:22
Regule a delegação com os modos
- 8
Mude para accept edits nos períodos cheios de edições
alt+m (shift+tab gira os modos nas builds atuais) vira a insígnia da sessão para accept edits on. As edições de arquivos passam a acontecer sem prompts, e a documentação acrescenta que comandos comuns de sistema de arquivos — mkdir, touch, mv, cp — também são autoaceitos. A regalia vale só pela sessão: sessão nova, volta o prompt por edição, até você optar de novo.
A insígnia accept edits on enquanto os comandos git permitidos encerram o commit.Ver em 4:35 - 9
Conheça a escada completa de modos antes de subi-la
Os modos definem a postura padrão de uma sessão. default pergunta no primeiro uso de cada ferramenta; plan é exploração somente leitura que não edita nada; acceptEdits autoaceita edições de arquivos; dontAsk nega automaticamente tudo o que perguntaria; auto aprova chamadas de ferramentas com checagens de segurança em segundo plano; bypassPermissions pula os prompts, exceto para o pequeno conjunto de ações que nenhum modo pode autoaprovar. Escolha um por sessão com --permission-mode, ou torne-o permanente com permissions.defaultMode.
- 10
Coloque o defaultMode no arquivo certo
A documentação de settings é direta: os valores defaultMode auto e bypassPermissions não têm efeito vindos de settings de projeto ou locais — coloque-os nos settings user (~/.claude/settings.json) ou managed, ou passe --permission-mode para uma única sessão. A precedência vai managed → CLI --settings → .claude/settings.local.json → .claude/settings.json → user, e um deny em qualquer nível vence todo allow abaixo dele.
Receitas de copiar e colar para projetos reais
- 11
Receita: permita os testes, tranque a destruição
No .claude/settings.json compartilhado com o time, permita o ciclo de testes com "Bash(npm run test:*)" e isole as partes perigosas com "Bash(rm -rf *)" e "Read(./.env)" para que segredos nunca fiquem legíveis. A pesquisa na web crava a mesma trilha: "WebFetch(domain:example.com)" para um domínio, "WebFetch(domain:*.example.com)" para um subdomínio inteiro. Como o deny é avaliado primeiro, nenhuma regra allow consegue abrir exceção nele.
- 12
Receita: pule prompts na CI com segurança
Execuções não interativas pedem uma postura deliberada, não acidental: passe --permission-mode bypassPermissions no job de CI, ou defina o defaultMode em settings user ou managed — um arquivo de projeto não pode concedê-lo. Para blindar a proteção, defina permissions.disableBypassPermissionsMode como "disable" nos managed settings e audite qualquer máquina com /permissions, que lista cada regra ativa e o arquivo de onde vem.
deny → ask → allow: como as regras são avaliadas de verdade
A documentação de permissões diz sem cerimônia: as regras são avaliadas na ordem — deny, depois ask, depois allow — a primeira correspondência decide, e a especificidade de uma regra nunca muda essa ordem. Uma regra allow não consegue abrir exceção numa deny, por mais precisa que seja.
O deny também é global entre arquivos. Se os settings user permitem um comando e os de projeto o negam, o deny vence, porque regras deny de qualquer escopo são avaliadas antes das allow — e um deny dos managed settings não pode ser sobreposto nem por flags de linha de comando. Negar um nome de ferramenta puro como "Bash" vai além ainda: a documentação diz que isso remove a ferramenta do contexto do Claude por completo.
Consequência prática: entregue suas regras de segurança — deny rm, deny leitura de .env, deny force-push — no .claude/settings.json do projeto, que viaja com o repositório, e trate as listas allow como conveniências que se empilham por cima. Listas allow se mesmam entre escopos em vez de se sobrescrever, então o seu settings.local.json pessoal pode somar permissões sem enfraquecer os vetos de ninguém.
Três receitas que valem a pena roubar
Cada receita nomeia o arquivo onde entra. Uma constante vale para todas: o deny vence em todo lugar, sempre.
Testes livres, com rm e .env trancados
No .claude/settings.json: "permissions.allow": ["Bash(npm run test:*)"] (troque por "Bash(npx vitest:*)" ou "Bash(uv run pytest:*)" conforme sua stack), "permissions.deny": ["Bash(rm -rf *)", "Read(./.env)"]. Testes e seus callbacks rodam sem as mãos; exclusões destrutivas e leituras de segredos são bloqueadas antes de a avaliação chegar à sua lista allow.
Prenda a pesquisa nos domínios em que confia
Para trabalho com muita documentação: "WebFetch(domain:developer.mozilla.org)" e "WebFetch(domain:claude.com)" no allow, ou "WebFetch(domain:*.example.com)" para cobrir um subdomínio inteiro. Negar a ferramenta pura "WebFetch" desliga a leitura da web por completo — útil para execuções reproduzíveis que precisam se manter no contexto local.
CI headless sem fugir do controle
Faça o job de CI passar --permission-mode bypassPermissions, ou defina "permissions.defaultMode": "bypassPermissions" em settings user ou managed — settings de projeto e locais não podem concedê-lo. Para proibir o modo de vez, "permissions.disableBypassPermissionsMode": "disable" nos managed settings trava todo repositório e toda flag. Mesmo assim, o bypassPermissions continua bloqueando a lista curta de ações que nenhum modo pode autoaprovar.
A regra não funciona? Cheque estas quatro coisas
A maioria dos relatos “minha regra allow está sendo ignorada” se resume a em qual arquivo a regra caiu e qual arquivo vence.
- 1Regra certa, arquivo errado. Aprovações de sessão caem no .claude/settings.local.json; regras de time pertencem ao .claude/settings.json; regras de máquina, ao ~/.claude/settings.json. Rode /permissions — ele lista cada regra ativa e o arquivo de settings de onde vem.
- 2Um arquivo acima nega. Valores sobrescrevem para baixo, mas um deny de qualquer nível é avaliado antes do allow, então um allow no nível user nunca salva um deny no nível projeto — e os managed settings vencem tudo, inclusive flags de linha de comando.
- 3A regra allow espera confiança. Regras deny e ask valem na hora, mas regras allow de um arquivo de projeto commitado só entram em vigor depois de você confiar na pasta do workspace — um portão deliberado para repositórios clonados.
- 4Modo no arquivo errado. Valores defaultMode auto e bypassPermissions são ignorados em settings de projeto e locais (a documentação nota que isso mudou na v2.1.257 — antes, o bypassPermissions valia a partir de qualquer arquivo). Mova para settings user ou managed, ou use --permission-mode para uma única sessão.