As regras de permissão no Claude Code são aplicadas pelo runtime do agente, não pelo modelo em si. Essa distinção importa mais do que parece. Instruções no seu prompt ou CLAUDE.md moldam o que Claude tenta fazer, mas não mudam o que Claude Code realmente permite, como deixa claro a documentação oficial de permissões. Para conceder ou revogar acesso você usa /permissions, os arquivos de configuração descritos abaixo, um modo de permissão ou um hook PreToolUse. Este post percorre cada camada: escolher um modo, entender precedência, escrever um arquivo de política funcional, testá-lo e saber onde o sistema inteiro não consegue ajudá-lo.
Escolha um Modo de Permissão
O modo que você escolhe define a linha de base para tudo mais. Há cinco.
Manual interrompe Claude Code antes da maioria das edições de arquivo, comandos shell e chamadas de rede. Você confirma cada uma. Lento, mas nada surpreende você.
Auto entrega aprovação a um modelo classificador que revisa ações em seu nome. Nos planos Pro, Max e Team este é o modo inicial integrado, conforme a documentação de modos de permissão. O classificador tem suas próprias regras sobre quais ações ele revisa e quais pula, então auto não é o mesmo que "aprovar tudo".
Accept Edits aprova automaticamente operações de arquivo mas ainda solicita comandos shell. Um meio termo razoável para trabalho solo em um codebase que você é dono e entende.
Plan bloqueia edições de arquivo e escritas shell completamente. Claude pode ler, raciocinar e produzir um plano, mas não pode agir. Bom para revisões em estágio inicial quando você quer ver a abordagem antes de qualquer coisa mudar.
dontAsk nega automaticamente qualquer ferramenta que não esteja em sua lista de permissão explícita. Sem prompt, apenas uma negação silenciosa. Este é o modo certo para pipelines CI/CD onde ninguém está observando.
bypassPermissions pula todas as verificações. Claude executa o que quiser. Útil em ambientes descartáveis isolados; não é algo para rodar contra um repo de produção.
Para fixar o modo inicial no VS Code, defina claudeCode.initialPermissionMode nas configurações do usuário para default, manual, acceptEdits, plan ou bypassPermissions. Nota: a configuração não aceita auto. Para começar em Auto, deixe não definido e escolha uma vez no indicador de modo; a extensão lembra essa escolha para conversas subsequentes.
Para sessões de terminal, defina permissions.defaultMode em ~/.claude/settings.json ou em configurações gerenciadas. Esse valor se aplica nos planos Pro, Max e Team quando a busca de feature-flag está disponível.
Um caso extremo que vale a pena conhecer: se sua organização definiu uma ferramenta de conector claude.ai como ask, as regras de permissão para essa ferramenta não entram em vigor nem em modos auto ou bypassPermissions. Claude Code solicita a cada chamada. Em modo dontAsk, nega a chamada em vez de solicitar.
Como Precedência de Regras e Configurações Funciona
Cinco camadas, avaliadas de cima para baixo. Uma camada superior vence.
- Configurações gerenciadas (
managed-settings.json): implantadas por TI, não substituíveis. Se sua organização bloqueia SSH aqui, é final. - Configurações locais (
.claude/settings.local.json): por máquina, gitignored por padrão. Substituições pessoais ou sensíveis de segurança ficam aqui. - Configurações do projeto (
.claude/settings.json): commitadas no repositório. Compartilhadas com todo o time para esse projeto. - Configurações do usuário (
~/.claude/settings.json): padrões globais, aplicados a cada projeto a menos que uma camada superior as sobrescreva. - Sinalizadores de sessão:
--dangerously-skip-permissionse argumentos de tempo de execução similares.
A documentação de configuração admin adiciona dois controles de bloqueio que valem a pena conhecer: allowManagedPermissionRulesOnly (torna as configurações gerenciadas a única fonte de regras de permissão, ignorando arquivos de usuário e projeto) e permissions.disableBypassPermissionsMode (remove a opção de bypass inteiramente). Se você está rodando uma agência com contratados tocando repos de clientes, essas duas configurações juntas te dão um teto duro que nenhum desenvolvedor pode desfazer silenciosamente.
Cada camada aceita três tipos de regra: allow, deny e ask. Dentro de uma camada, deny vence allow. Shell-pattern matching é suportado (por exemplo Bash(git *)), mas seja preciso: um padrão que parece inexpugnável em testes frequentemente tem brechas quando strings de comando reais diferem do que você esperava.
Uma coisa que os docs sinalizam explicitamente: negar WebFetch bloqueia a ferramenta fetch do Claude, mas se Bash é permitido, curl e wget ainda podem acessar qualquer URL. Sandboxing (via /sandbox) fecha essa brecha com uma allowlist de domínio aplicada no nível do SO. Permissões e sandboxing cobrem camadas diferentes e você geralmente quer ambas para qualquer coisa séria.
Um Exemplo de Política de Repositório de Cliente
Aqui está um .claude/settings.json ilustrativo para um projeto de cliente onde o time pode rodar builds e ler o banco de dados mas não deve tocar em scripts de deployment ou secrets. Essa é uma estrutura representativa, não uma política de produção para copiar e colar.
{
"permissions": {
"defaultMode": "auto",
"allow": [
"Bash(npm run build)",
"Bash(npm run test*)",
"Bash(git log*)",
"Bash(git diff*)",
"Bash(git status)",
"Read(**)"
],
"deny": [
"Bash(rm -rf*)",
"Bash(git push*)",
"Bash(kubectl*)",
"Edit(.env*)",
"Edit(deploy/**)"
]
}
}
Junto a isso, um ~/.claude/settings.json na máquina de cada desenvolvedor cuida da confiança global pessoal, como permitir curl para uso geral. Credenciais sensíveis ou caminhos específicos da máquina vão em .claude/settings.local.json, que git não vai committar.
Do lado do CLAUDE.md, onde você define convenções e contexto do projeto em vez de regras de execução, o guia de agência para CLAUDE.md cobre o workflow de autoria em detalhe.
Teste a Política com Comandos Realistas
Coloque a política em um repositório descartável (um git init vazio em um diretório temporário funciona bem), depois rode um punhado de comandos que exercitem as três categorias de regra. O objetivo é ver quais solicitam aprovação, quais executam silenciosamente e quais são negadas sem um prompt.
Uma sequência de teste representativa:
npm run build(deve auto-aprovar, está na lista de permitidos)git diff HEAD~1(deve auto-aprovar)git push origin main(deve ser negado)rm -rf node_modules(deve ser negado)- Editar um arquivo dentro de
deploy/(deve ser negado) - Editar
src/index.js(nenhuma regra deny, nenhum allow explícito: comportamento depende do modo) - Uma chamada
curlpara uma URL externa (testa como regras de allow deBashe sandbox interagem)
Observe especificamente o caso 6. Em modo auto o classificador o analisa. Em modo dontAsk é negado silenciosamente porque não está na lista de permitidos. Essa diferença vai surpreender desenvolvedores que testam em um modo e deployam em outro.
Se você está adicionando automação no nível de evento em cima disso (rodando linters em salvamentos de arquivo, disparando notificações em chamadas de ferramenta específicas), isso é uma preocupação de hooks em vez de permissões. O guia de hooks cobre PreToolUse e PostToolUse completamente.
Para equipes que precisam de execuções autônomas ou integração CI, considere usar o setup da agência Claude Code para acertar a linha de base de configuração desde o início.
Configurações Gerenciadas e Trabalhos Autônomos
Quando nenhuma pessoa está presente para clicar em "aprovar", o modelo de permissões tem de ser totalmente pré-declarado. Isso aponta para o modo dontAsk com uma lista de permissão explícita nas configurações gerenciadas.
A documentação de setup do admin fornece permissions.defaultMode como a chave gerenciada para isso. Defina como dontAsk, depois enumere exatamente o que o trabalho precisa em permissions.allow. Qualquer coisa não listada é negada silenciosamente. Isso é o que você quer em um pipeline.
Algumas coisas que a documentação oficial destaca para cenários de equipes de agentes (onde uma sessão líder gera colegas):
- Os colegas começam com as configurações de permissão do líder. Se o líder executa com
--dangerously-skip-permissions, todos os colegas também o fazem. - Você pode alterar modos individuais de colega após a geração, mas não no momento da geração.
- Os prompts de permissão do colega aparecem na sessão do líder. Aprovações de plano são a exceção projetada: o líder as concede sem um prompt separado.
Managed Agents (o serviço de orquestração em nível de plataforma) está atualmente em beta conforme a visão geral de Managed Agents. Não projete pipelines de produção em torno de recursos beta sem um fallback.
Para a flag permissions.disableAutoMode: configurá-la remove o modo automático como uma opção para desenvolvedores nessa organização. Útil quando você quer que todas as sessões permaneçam em um modo onde um humano ou uma lista de permissão explícita está tomando cada decisão, em vez de um classificador.
O Que as Permissões Não Podem Garantir
Resposta honesta: bastante coisa.
Regras de negação com padrão shell não são um limite de segurança. Elas fazem matching contra a string de comando que Claude Code constrói, mas uma injeção de prompt suficientemente criativa ou uma reformulação inteligente de um comando shell pode produzir strings que seus padrões não pegam. A documentação de permissões é explícita: regras de negação e sandboxing cobrem camadas diferentes. Você precisa de ambos, e mesmo assim você está reduzindo risco, não eliminando-o.
O modo bypassPermissions não torna o código permitido inofensivo. Se Claude executa código que contém um bug ou faz algo inesperado, pular verificações de permissão significa que não havia um gate entre "Claude decidiu fazer" e "aconteceu".
Permissões também não avaliam o que está dentro do código que Claude escreve ou executa. Uma dependência que instala, um script que executa, o conteúdo de um arquivo que cria: nada disso é inspecionado pelo sistema de permissões. Essa é uma preocupação separada, mais próxima de higiene de cadeia de suprimentos do que de política de runtime.
E o modelo em si não é a camada de enforcement. Você pode escrever instruções CLAUDE.md que dizem "nunca toque em segredos de produção". Essas instruções moldam a intenção de Claude. Elas não impedem que uma regra de permissão mal configurada deixe isso acontecer mesmo assim. O runtime é a camada de enforcement. Os arquivos de configuração são como você configura o runtime. Trate-os assim.
FAQ
As configurações de permissão sincronizam automaticamente entre máquinas?
Não. As configurações do usuário (~/.claude/settings.json) são locais para cada máquina. As configurações do projeto (.claude/settings.json) sincronizam via git. As configurações gerenciadas são distribuídas pela sua infraestrutura de TI. Não há sincronização integrada para arquivos de nível de usuário; cada desenvolvedor precisa configurar a sua própria.
Os desenvolvedores podem sobrescrever configurações gerenciadas?
Apenas dentro dos limites que as configurações gerenciadas permitem. Se allowManagedPermissionRulesOnly estiver definida, as regras de permissão de usuário e projeto são ignoradas inteiramente. Sem esse flag, configurações de usuário e projeto podem adicionar regras de permissão, mas não podem sobrescrever uma negação gerenciada.
O que acontece com os prompts de permissão em ambientes headless ou CI?
No modo dontAsk, qualquer coisa que não esteja na lista de permissão é negada silenciosamente. Nenhum prompt aparece porque não há terminal para mostrar um. É por design. No modo auto em um ambiente headless, o classificador ainda executa, mas se não conseguir resolver um prompt (sem TTY), o comportamento depende da configuração do runner. Use dontAsk com uma lista de permissão explícita para trabalhos autônomos.
O modo de permissão se aplica às ferramentas MCP da mesma forma que se aplica às ferramentas integradas?
Principalmente, mas com diferenças. Ferramentas MCP buscadas diretamente pelo Claude Code aparecem como mcp__claude_ai_<server>__<tool>. Regras de permissão e negação podem direcioná-las por esse nome. Ferramentas de conectores que sua organização configurou para sempre perguntar sempre solicitam, independentemente do modo, com exceção do modo dontAsk, onde são negadas.
É seguro fazer commit de `.claude/settings.json` em um repositório público?
O arquivo em si é apenas JSON com nomes e padrões de ferramentas, sem segredos. Mas uma lista de permissão pública diz a qualquer pessoa que leia seu repositório exatamente quais operações o Claude Code executará sem avisar. Para projetos open-source, provavelmente está tudo bem. Para qualquer coisa proprietária, revise o que você está fazendo commit. Segredos e chaves de API nunca devem aparecer em nenhum arquivo de configuração; eles pertencem a variáveis de ambiente fora da configuração do Claude Code.
A coisa mais importante a se lembrar: regras de negação e sandbox resolvem problemas diferentes, e nenhuma delas substitui a outra. Configure ambas se estiver executando Claude Code em qualquer ambiente onde o custo de um erro é real.