Permissões do Claude Code

Problema: Claude Code pedindo permissão a cada edição de arquivo e cada comando mata o seu ritmo e desperdiça tempo.

Solução Rápida: Pressione Shift+Tab para alternar entre modos de permissão na hora:

# Press Shift+Tab to cycle:
normal → auto-accept edits → plan mode → normal

Você pode rebinder isso se Shift+Tab conflitar com o seu terminal. Agora você controla o fluxo sem tocar em um arquivo de configuração. Combine o modo com a tarefa e o ciclo de interrupções para.

Todos os Modos de Permissão

Claude Code vem com cinco modos de permissão, cada um feito para um tipo diferente de trabalho. Três modos principais alternam via Shift+Tab, e mais dois ficam na configuração.

Modo Normal (`default`)

O modo normal solicita confirmação antes de qualquer operação potencialmente perigosa. Você vê diálogos de confirmação para:

Edições e alterações de arquivos
Execução de comandos no terminal
Operações de sistema
Mudanças de diretório

Segurança acima de velocidade. Use para:

Código de produção
Bases de código que você não conhece bem
Aprender novas técnicas
Operações de alto risco

Modo Auto-Accept (`acceptEdits`)

O modo auto-accept remove os prompts de permissão para edições de arquivos pelo resto da sessão. Claude executa operações aprovadas diretamente.

Ative pressionando Shift+Tab até a interface mostrar "auto-accept edit on".

Melhor para:

Sessões grandes de refatoração
Trabalhar em um plano bem definido
Trabalho de pesquisa e documentação
Edições repetitivas em muitos arquivos

Modo Plan (`plan`)

O modo plan trava Claude em operações somente leitura. Claude pode analisar livremente, mas nada no disco muda.

Perfeito para:

Exploração inicial de uma base de código
Análise de arquitetura
Planejamento de features complexas
Sessões de code review

O modo Don't Ask nega automaticamente qualquer uso de ferramenta a menos que a ferramenta já esteja pré-aprovada via /permissions ou uma regra permissions.allow. Sem prompts. Qualquer coisa fora da lista de permissões é negada silenciosamente.

Melhor para:

Pipelines CI/CD sem humanos por perto para confirmar
Ambientes restritos com um conjunto conhecido de operações permitidas
Rodar Claude contra uma política de permissões estrita e pré-construída

Modo Bypass Permissions (`bypassPermissions`)

O modo bypass ignora toda verificação de permissão. Claude executa qualquer ferramenta sem solicitar.

# CLI flag equivalent:
claude --dangerously-skip-permissions

Ative isso apenas dentro de ambientes completamente isolados como contêineres, VMs ou runners CI efêmeros onde Claude não pode causar danos duradouros. O ponto do modo é automação em lugares onde o próprio ambiente é a fronteira de segurança.

Aviso: Admins podem desativar esse modo completamente definindo disableBypassPermissionsMode como "disable" nas configurações gerenciadas. Se a sua organização bloquear, nem a configuração nem a flag CLI funcionarão.

Definindo um Modo Padrão Persistente

Em vez de alternar modos toda sessão, fixe o seu padrão preferido no settings.json:

{
  "defaultMode": "acceptEdits"
}

Valores válidos: default, acceptEdits, plan, dontAsk, bypassPermissions. A preferência persiste entre sessões para que você sempre comece onde quer.

Gerenciando Permissões com /permissions

Em vez de editar arquivos JSON manualmente, o comando embutido /permissions abre uma visualização interativa:

# Launch the interactive permissions UI
/permissions

A partir daí você pode:

Ver quais ferramentas estão atualmente permitidas e negadas
Conceder acesso a ferramentas ou padrões específicos
Bloquear ferramentas que você quer fora dos limites
Ver de qual arquivo de configurações cada regra vem
Fazer mudanças sem reiniciar Claude Code

Sintaxe de Regras de Permissão

As regras seguem o formato Tool ou Tool(specifier). Elas ficam no objeto permissions do seu settings.json:

{
  "permissions": {
    "allow": ["Bash(npm run *)"],
    "deny": ["Bash(rm *)"],
    "ask": ["Bash(git push *)"]
  }
}

Três tipos de regras controlam o comportamento:

Regras Allow deixam Claude rodar a ferramenta sem perguntar
Regras Ask solicitam confirmação a cada uso
Regras Deny bloqueiam a ferramenta completamente

As regras são avaliadas em ordem: deny primeiro, depois ask, depois allow. A primeira regra correspondente vence, então um deny sempre supera um allow.

Combinando Todos os Usos de uma Ferramenta

Use apenas o nome da ferramenta para cobrir todas as invocações:

Regra	Efeito
`Bash`	Combina todos os comandos Bash
`WebFetch`	Combina todas as requisições web fetch
`Read`	Combina todas as leituras de arquivo
`Edit`	Combina todas as edições de arquivo

Bash(*) é o mesmo que Bash e combina todos os comandos Bash.

Padrões Wildcard do Bash

Regras Bash aceitam padrões glob com *. Wildcards podem aparecer em qualquer lugar na regra:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": ["Bash(git push *)"]
  }
}

Semântica de limite de palavra: o espaço antes de * importa. Bash(ls *) combina ls -la mas não lsof. Bash(ls*) combina os dois.

Consciência de operadores shell: Claude Code entende operadores shell. Uma regra como Bash(safe-cmd *) não vai combinar safe-cmd && malicious-cmd. Isso impede exploração por comandos encadeados.

Aviso: Padrões Bash que tentam restringir argumentos de comandos são frágeis. Uma regra como Bash(curl http://github.com/ *) pretende limitar curl a URLs do GitHub, mas não vai detectar variações (opções antes da URL, protocolos diferentes, expansão de variáveis). Para filtragem real de URL, bloqueie ferramentas de rede Bash e use WebFetch com regras de domínio.

Padrões de Read e Edit

Regras Read e Edit usam padrões de caminho no estilo gitignore, quatro tipos:

Padrão	Significado	Exemplo
`//path`	Caminho absoluto da raiz do sistema de arquivos	`Read(//Users/alice/secrets/**)`
`~/path`	Caminho a partir do diretório home	`Read(~/Documents/*.pdf)`
`/path`	Relativo ao arquivo de configurações	`Edit(/src/*/.ts)`
`path` ou `./path`	Relativo ao diretório atual	`Read(*.env)`

Importante: um padrão como /Users/alice/file não é um caminho absoluto. Ele é resolvido em relação ao seu arquivo de configurações. Use //Users/alice/file para um caminho absoluto verdadeiro.

Em padrões gitignore, * combina arquivos em um único diretório enquanto ** combina recursivamente. Para permitir acesso a todos os arquivos, remova os parênteses completamente: Read, Edit ou Write.

Regras de Domínio WebFetch

Controle de quais domínios Claude pode buscar:

{
  "permissions": {
    "allow": ["WebFetch(domain:docs.anthropic.com)"],
    "deny": ["WebFetch(domain:internal.company.com)"]
  }
}

Padrões de Ferramentas MCP

Controle o acesso ao servidor MCP no nível do servidor ou da ferramenta:

Regra	Efeito
`mcp__puppeteer`	Combina qualquer ferramenta do servidor puppeteer
`mcp__puppeteer__*`	O mesmo que acima (sintaxe wildcard)
`mcp__puppeteer__puppeteer_navigate`	Combina apenas a ferramenta navigate especificamente

Regras de Task (Subagente)

Controle quais subagentes Claude pode criar usando Task(AgentName):

{
  "permissions": {
    "deny": ["Task(Explore)"]
  }
}

Os nomes dos agentes incluem Explore, Plan e Verify. A flag CLI --disallowedTools também pode desativar agentes específicos na inicialização.

Estendendo Permissões com Hooks

Hooks PreToolUse rodam antes do sistema de permissões e podem aprovar, negar ou reescrever chamadas de ferramentas em tempo de execução. Isso dá controle programático além das regras estáticas.

Como Permissões Funcionam com Sandboxing

Permissões e sandboxing se acumulam como duas camadas de segurança complementares (defesa em profundidade):

Permissões controlam quais ferramentas Claude pode usar e quais arquivos ou domínios pode tocar. Aplicam-se a todas as ferramentas (Bash, Read, Edit, WebFetch, MCP e o resto).
Sandboxing adiciona aplicação no nível do OS por cima, limitando o que os comandos Bash podem alcançar no sistema de arquivos e rede. Aplica-se apenas a comandos Bash e seus processos filhos.

Use os dois juntos para a postura mais forte:

Regras de negação de permissão impedem Claude de tentar acessar recursos restritos
Restrições de sandbox mantêm comandos Bash dentro de limites definidos, mesmo quando uma injeção de prompt ignora a tomada de decisão do Claude
Restrições de sistema de arquivos no sandbox usam regras de negação Read e Edit (não configuração de sandbox separada)
Restrições de rede misturam regras de permissão WebFetch com a lista allowedDomains do sandbox

Ative o sandboxing com o comando /sandbox. No macOS funciona imediatamente usando Seatbelt. No Linux e WSL2, instale bubblewrap e socat primeiro.

Configurações de Permissão Gerenciadas

Para organizações que precisam de controle central, admins podem distribuir arquivos de configurações gerenciadas que usuários e projetos não podem sobrescrever:

Configuração	Efeito
`allowManagedPermissionRulesOnly`	Quando `true`, apenas regras de permissão das configurações gerenciadas se aplicam. Regras de usuário e projeto são ignoradas.
`disableBypassPermissionsMode`	Defina como `"disable"` para bloquear o modo `bypassPermissions` e a flag CLI `--dangerously-skip-permissions`.

Locais dos arquivos de configurações gerenciadas:

macOS: /Library/Application Support/ClaudeCode/managed-settings.json
Linux/WSL: /etc/claude-code/managed-settings.json
Windows: C:\Program Files\ClaudeCode\managed-settings.json

Esses são caminhos de todo o sistema (não diretórios home do usuário) e precisam de privilégios de admin. Usam o mesmo formato que arquivos de configurações normais mas têm a maior precedência na hierarquia de configurações.

Estratégias por Cenário de Desenvolvimento

Desenvolvimento Inicial (Use Modo Normal)

Começando um novo projeto ou explorando código desconhecido:

Mantenha todas as permissões manuais
Revise cada mudança sugerida
Observe como Claude aborda o problema
Construa confiança nas decisões da IA

Desenvolvimento Ativo (Use Auto-Accept)

Dentro de uma sessão intensa de coding:

Ative auto-accept para tipos de arquivo confiáveis
Permita comandos comuns (npm, git status)
Mantenha prompts para operações de sistema
Aproveite um fluxo de trabalho sem interrupções

Code Review (Use Modo Plan)

Quando você está analisando uma base de código existente:

Mude para o modo plan para segurança
Deixe Claude explorar sem tocar em arquivos
Produza análise e recomendações
Mude de modo apenas quando estiver pronto para implementar

Armadilhas Comuns de Permissão

Excesso de permissões: evite o modo bypassPermissions a menos que esteja dentro de um contêiner ou VM completamente isolado. O modo dontAsk com regras de allow explícitas é a opção mais segura de "mãos livres".

Falta de permissões: clicar em "Allow" pela centésima vez derrota o propósito. Use /permissions para pré-aprovar operações repetitivas, ou mude para acceptEdits durante o desenvolvimento ativo.

Confusão de Modo: verifique o seu modo atual antes de começar o trabalho. O indicador fica na interface. Defina defaultMode no settings.json se sempre quiser o mesmo modo de início.

Permissões Abrangentes: não permita todos os comandos Bash. Use padrões específicos como Bash(npm run *) para manter o escopo restrito. E lembre: regras deny sempre superam regras allow.

Padrões de Argumento Frágeis: não dependa de regras Bash para restringir argumentos de comandos (como fixar curl a certas URLs). Use regras de domínio WebFetch para filtragem real de URL.

O Que Vem a Seguir

Cinco modos de permissão para cinco tipos de trabalho. default para segurança, acceptEdits para produtividade, plan para exploração, dontAsk para automação e bypassPermissions para ambientes isolados. Escolha o modo que se encaixa na tarefa e adicione sandboxing por cima para defesa em profundidade.

Leituras relacionadas:

Automatize chamadas de permissão com hooks e o Permission Hook
Keybindings personalizados para alternância mais rápida de modo
Feedback loops para iteração mais rápida
Fluxos de trabalho Todo para rastreamento de tarefas
Integração git para controle de versão
Noções básicas de configuração para settings.json e configuração mais profunda