Permissões do Claude Code: como desenhar autonomia sem abrir a produção

English summary: A practical framework for using Claude Code permissions, settings, allow/deny rules, hooks, human approval, and verification to give agents useful autonomy without granting production-level access by default.

Published: August 2026
Reading time: 19 min
Keywords: Claude Code, permissions, settings.json, hooks, least privilege, human approval, agent security, production safety

TL;DR

• Separe leitura, escrita e side effects.
• Modele permissões como política executável e revisável.
• Mantenha produção atrás de aprovação humana e evidência.

Exemplo concreto: uma alteração em código local pode ser automática; um deploy precisa de escopo e aprovação explícitos.

O comando que mais assusta num agent não é rm -rf. É o que parece inofensivo: uma correção de configuração, um kubectl apply, uma migração “pequena”, um git push para a branch errada. Quase nunca há uma intenção maliciosa. Há contexto incompleto, uma suposição errada e uma ferramenta com poder demais.

Claude Code acelera trabalho porque pode ler, editar e executar. Essa mesma capacidade torna permissões um problema de arquitetura, não uma preferência de interface. Se a segurança depende de o modelo sempre interpretar corretamente uma frase como “não mexa em produção”, o sistema já começou frágil.

A tese deste artigo é simples: autonomia útil nasce de permissões pequenas, efeitos reversíveis, gates humanos explícitos e evidência de verificação — não de desligar confirmações. O objetivo não é fazer o Claude Code trabalhar com medo. É tornar seguro deixar que ele trabalhe rápido onde o risco é baixo, e impossível ou deliberadamente lento onde o risco é alto.

As páginas de permissões, configurações e hooks do Claude Code são a fonte primária para a sintaxe discutida aqui; como modos e campos podem mudar entre releases, confira a documentação e a versão instalada antes de promover este desenho para um ambiente real. As referências foram verificadas para esta edição em agosto de 2026.

O que permissões são — e o que não são

Permissão é a decisão operacional sobre quais tools podem ser usadas, contra quais alvos e sob quais condições. Em Claude Code, isso inclui leitura de arquivos, escrita, comandos de shell e tools externas, inclusive MCP. Regras podem permitir, pedir confirmação ou negar chamadas específicas; o sistema avalia deny, depois ask, depois allow, portanto uma negação correspondente prevalece sobre uma permissão mais ampla (Configure permissions).

Isso não é o mesmo que instrução. Um CLAUDE.md dizendo “nunca faça deploy” é contexto valioso, mas continua sendo texto que o modelo precisa interpretar. Uma regra deny e um hook PreToolUse são controles executáveis. Eles reduzem o poder efetivo da tool antes que uma ação ocorra.

Também não é o mesmo que identidade. Uma credencial AWS com AdministratorAccess, um token GitHub com escopo amplo ou uma conexão de banco com escrita transforma qualquer erro de permissão local em incidente externo. O Claude Code decide se tenta uma tool; o provedor remoto ainda precisa conceder o menor conjunto possível de privilégios. As duas camadas são necessárias.

Por fim, não é uma justificativa para usar um agent em qualquer processo. Um workflow fixo — CI que executa testes e publica um artefato assinado — costuma ser melhor para passos previsíveis e repetitivos. Claude Code é mais útil quando precisa investigar, navegar contexto e propor mudanças. Quanto maior a liberdade de decidir a sequência, mais importante se torna limitar o raio de ação.

Uma forma prática de separar as responsabilidades é esta:

Se uma dessas linhas estiver vazia, as outras não compensam completamente. Um hook não salva uma credencial administrativa fora do seu escopo. Uma aprovação humana não é boa auditoria se ninguém consegue explicar o que foi aprovado. E testes verdes não tornam aceitável um comando executado no cluster errado.

As quatro falhas que abrem produção por acidente

Antes de desenhar a solução, vale reconhecer os quatro atalhos que mais aparecem em repositórios reais.

1. Tratar modo de permissão como política de segurança

Os modos do Claude Code definem a experiência de aprovação: default, acceptEdits, plan, auto, dontAsk e bypassPermissions têm comportamentos diferentes documentados pela Anthropic. Eles são úteis, mas não substituem uma política. plan reduz execução enquanto se explora o problema; acceptEdits remove atrito para alterações locais; dontAsk só permite o que já foi pré-aprovado. Nenhum deles, isoladamente, define o que uma organização considera operação crítica.

O caso mais perigoso é tratar bypassPermissions como atalho de produtividade. A documentação diz que ele pula prompts de permissão e recomenda uso apenas em ambientes isolados, como containers ou VMs. Mesmo que alguns comandos extremos acionem um circuito de proteção, isso não é uma fronteira de produção. Um diretório de trabalho com tokens, acesso a rede e credenciais montadas não vira seguro só porque está dentro de um container.

Use um modo para reduzir fricção em uma classe de trabalho; use regras, identidade e ambiente para definir a política. Em particular, a configuração de uma repository não deve ter o poder de ligar automaticamente uma experiência mais permissiva para todo desenvolvedor. Consulte a precedência documentada de configurações antes de depender de defaultMode em um escopo compartilhado.

2. Uma allowlist ampla que vira “pode executar tudo”

Bash(*) parece simples até você lembrar que shell é uma linguagem de composição: redirecionamentos, pipes, scripts chamados por scripts, variáveis e ferramentas remotas. Uma permissão ampla não é só “rodar comandos de desenvolvimento”; ela pode alcançar publicação de pacote, push, infraestrutura ou dados dependendo da máquina e das credenciais disponíveis.

O erro costuma vir de pensar em nomes de binários em vez de efeitos. git pode ser leitura de histórico ou pode publicar um branch. npm pode rodar lint ou executar um postinstall inesperado. kubectl pode listar pods ou aplicar uma mudança irreversível. A regra deve nomear o menor comando útil e, quando possível, restringir argumentos e contexto.

Também evite permitir segredos por conveniência. A própria documentação recomenda permissions.deny para impedir descoberta e leitura de .env, arquivos de credenciais e diretórios secretos. Isso reduz exposição acidental no contexto do modelo, mas não substitui secret management: o segredo idealmente nem está disponível na sessão que não precisa dele (Claude Code settings).

3. Usar hook como enfeite depois do efeito

Um PostToolUse que registra “deploy executado” é útil para observabilidade, mas não bloqueia o deploy: o efeito já aconteceu. Para prevenir um ato, o lugar relevante é antes da tool, tipicamente PreToolUse. Um comando de hook pode bloquear uma ação com saída 2; alternativamente, um hook pode retornar JSON estruturado para permitir, negar ou pedir confirmação, conforme o evento suporta (Hooks reference).

Isso cria uma consequência de design: hooks também têm superfície de ataque e de falha. Se um hook escreve logs, envia HTTP ou chama outro script, esses efeitos ocorrem mesmo quando outro hook decide negar a tool. A documentação alerta que hooks correspondentes são executados antes de os resultados serem combinados. Portanto, hooks que auditam precisam ser seguros para repetir e não devem produzir efeitos que você não aceitaria numa tentativa bloqueada.

4. Confirmação humana vaga e tarde demais

“Pergunte antes de algo perigoso” é uma regra mal definida. Quem responde? O que conta como perigoso? O humano vê o ambiente, o diff, a query e o blast radius, ou recebe uma caixa de diálogo genérica? Uma aprovação sem pacote de decisão vira um reflexo de clicar em “permitir”.

Approval humano funciona quando é um gate de mudança, não uma cerimônia. Defina um dono do serviço, o ambiente, o plano de reversão, a evidência de teste e a janela de impacto. Para operações de escrita em produção, o agente deve preparar o pacote e parar; o executor humano ou um pipeline com identidade controlada realiza a última ação.

O harness de segurança do Claude Code

Pensar em Claude Code como um harness ajuda a não concentrar toda a segurança em uma configuração. O harness junta contexto, tools, permissões, ambiente, verificação e observabilidade. Permissões são só uma camada, mas são a que transforma intenção em capacidade operacional.

Contexto: instruções deixam o comportamento legível

Use CLAUDE.md para declarar a fronteira do trabalho: ambientes permitidos, comandos de validação, donos de serviços e casos que exigem escalonamento. Ele não deve conter tokens, regras gigantes ou listas de exceções que só uma pessoa entende. O objetivo é diminuir ambiguidade antes de uma tool ser escolhida.

Exemplo de contrato curto:

# Operating agreement

- Este workspace é de desenvolvimento; produção é somente leitura.
- Alterações em `services/payments/**` exigem `pnpm test payments` e revisão do time Payments.
- Nunca aplique migrações, publique pacotes ou faça deploy a partir desta sessão.
- Para incidentes, colete evidência, proponha o plano e pare antes de qualquer escrita externa.

O contrato faz duas coisas: orienta o raciocínio e estabelece o momento de parar. Mas as linhas que realmente precisam resistir a erro devem reaparecer como regras ou hooks.

Tools e ambiente: reduza o que existe, não só o que é permitido

Least privilege fica mais forte quando o processo nem enxerga ferramentas e credenciais desnecessárias. Prefira:

• container ou VM efêmera para tarefas de alto risco;
• volume de trabalho sem diretórios de chaves montados;
• variáveis de ambiente mínimas;
• perfis cloud separados por ambiente;
• credenciais curtas e read-only para investigação;
• banco de produção acessível por uma réplica ou API de leitura, não por uma URL de escrita.

Esse desenho muda a pergunta de “o modelo vai obedecer?” para “qual é o pior efeito possível se ele errar?”. A segunda pergunta é verificável. E é nela que threat modeling começa a ser útil.

Permissões: escolha um default conservador e regras explícitas

No dia a dia, uma combinação comum é explorar em plan, editar localmente após revisão de plano e pré-aprovar apenas comandos de validação previsíveis. Para automação não interativa, dontAsk com allowlist pequena é mais defensável do que aceitar qualquer prompt automaticamente: uma tool fora da lista falha em vez de abrir uma nova superfície sem revisão.

As regras têm escopo e precedência. Configurações de usuário podem servir preferências locais; .claude/settings.json é compartilhável no projeto; .claude/settings.local.json deve conter experimentos ou escolhas pessoais e normalmente não entra no Git. Organizações com exigências fortes precisam de política gerenciada e identidade externa; não delegue controles mandatórios a um arquivo que o próprio repositório pode alterar. Veja a hierarquia em Settings.

Hooks: imponha invariantes objetivos

Hooks são apropriados para regras que podem ser avaliadas em dados da chamada da tool: bloquear um contexto de cluster, impedir git push, exigir que um arquivo de mudança exista ou registrar um identificador de aprovação. Eles não são bons para decidir se uma mudança “parece segura”; isso pede dono humano e contexto do negócio.

Para PreToolUse, a decisão de hook tem precedência restritiva entre hooks (deny vence ask, que vence allow). Porém regras deny e ask continuam sendo avaliadas mesmo que o hook tente permitir algo. Esse detalhe é excelente: mantenha proibições absolutas em regras e use hooks para política contextual ou logging.

Verificação e observabilidade: prove antes, durante e depois

Uma alteração local deve terminar com teste, typecheck, lint, diff revisto e uma declaração honesta do que não foi verificado. Uma mudança que toca um sistema externo exige também um registro de mudança, identidade do aprovador e sinais pós-ação. Para Claude Code, telemetria baseada em OpenTelemetry pode correlacionar decisões de tool com o tool_use_id exposto a hooks, quando habilitada e adequada à política de privacidade da empresa (Monitoring).

Não registre prompt integral, segredos, conteúdo de clientes ou comandos sensíveis apenas porque “é auditoria”. Auditoria boa é minimizada, retida pelo tempo necessário e acessível a quem precisa investigar.