Como escolher o modo de permissão do Claude Code

O(a) senhor(a) pede para adicionar um banner, mas o agente também sugere atualizar um módulo antigo. É útil ver esse plano antes das alterações e remover o que não foi pedido. Para isso, importam tanto uma solicitação clara quanto o modo de trabalho escolhido.

O modo de permissão define como as ações do Claude Code são autorizadas: o que pode ser feito na hora, o que exige uma confirmação e o que será bloqueado. Configurações e permissões já concedidas também afetam ações específicas. O modo, por si só, não verifica a qualidade da solução.

Vamos conhecer os modos usando como exemplo uma sessão local do Claude Code no terminal.

Pedido e permissão

É fácil confundir duas coisas que parecem semelhantes, mas funcionam de maneiras diferentes.

A primeira é o que o(a) senhor(a) escreve na solicitação: uma seção com exceções, a frase "mostre o plano primeiro, não altere nada", uma lista de arquivos que não devem ser tocados. São limites da tarefa: eles explicam o que precisa ser feito e influenciam bastante o que o agente vai propor. Mas são apenas texto e não afetam as permissões técnicas.

A segunda é o modo de permissão, também chamado de permission mode. É uma configuração da sessão. É possível escrever "não altere nada" e trabalhar em um modo que aplica as alterações automaticamente. O agente deve respeitar o pedido, mas a frase, por si só, não bloqueia tecnicamente as alterações.

Há uma exceção, mas ela é parcial. No modo auto, um classificador lê a conversa e interpreta "não faça push" ou "espere minha revisão" como um sinal para bloquear essas ações. Mas isso não é uma regra nas configurações: se a mensagem com a proibição for descartada durante a compactação do contexto, a proibição também desaparece. Para estabelecer um limite rígido, use as configurações, não uma frase.

Dos modos mais seguros aos mais arriscados

É mais fácil entender os modos como uma escala do que como uma lista. No topo, o agente quase não age sem a sua confirmação; na base, não pergunta nada. São cinco níveis e mais um modo que fica fora dessa escala.

O ponto principal é quantas ações são executadas sem a sua resposta. Esse número aumenta de cima para baixo, e o custo de um erro também. No topo, o(a) senhor(a) gasta tempo confirmando ações; na base, só descobre depois que uma alteração deu errado.

Um resumo de cada modo:

• plan - o agente explora o projeto e propõe alterações antes de implementá-las; enquanto isso, as alterações no código-fonte ficam bloqueadas. Há uma exceção: se a sessão foi iniciada com bypassPermissions permitido, no terminal o planejamento não bloqueia mais as alterações; o agente apenas recebe a instrução de não modificar nada. Use esse modo quando quiser uma análise do código, não mudanças nele. Se auto estiver disponível, o classificador também verifica os comandos de exploração, então pode haver até menos confirmações do que em default. Ele fica mais alto na escala porque não altera o código-fonte. Quando o plano fica pronto, o Claude Code pergunta como continuar: aprová-lo e mudar para auto, aprová-lo mantendo a confirmação manual das alterações ou continuar planejando.
• default, geralmente exibido como Manual na tela - pede confirmação antes de alterações, comandos e acessos à rede. A leitura do projeto e as permissões já concedidas não exigem confirmação, então não é preciso aprovar cada ação de novo. Às vezes, a confirmação é pedida até para um comando que parece inofensivo. Não é excesso de cautela: find com a opção -exec executa qualquer comando, enquanto -delete remove o que foi encontrado. Por isso, comandos nessas formas não passam sem a sua resposta.
• acceptEdits, exibido como "accept edits" na tela - aplica sozinho as alterações nos arquivos da pasta de trabalho e executa alguns comandos de arquivo, inclusive rm e mv. É uma forma de ganhar velocidade em arquivos conhecidos, que o(a) senhor(a) vai revisar depois de qualquer maneira.
• auto - faz quase tudo por conta própria. A leitura e as alterações na pasta de trabalho acontecem imediatamente; um modelo separado, o classificador, verifica comandos e acessos à rede. Ele bloqueia alguns deles, como veremos adiante.
• bypassPermissions, também ativado pela opção --dangerously-skip-permissions - quase nunca pede confirmação. Só permanecem as regras explícitas nas configurações (proibições e "sempre perguntar") e algumas proteções do sistema. Também é conhecido como YOLO, e o nome faz jus ao modo.

O sexto modo, dontAsk, aparece separado no diagrama. E há um motivo: os níveis diferem pela quantidade de ações que passam sem a sua resposta; quanto mais abaixo, mais o agente pode fazer. O dontAsk funciona de outra forma: também não pergunta, mas, em vez de concordar, recusa. É executado o que nem no modo normal exige uma pergunta (leitura de arquivos na pasta de trabalho, comandos seguros somente de leitura), mais o que foi permitido previamente. Tudo o que exigiria uma pergunta é rejeitado sem perguntar. A sessão simplesmente não espera uma resposta. Esse modo serve quando não há ninguém para responder, em cenários automatizados e ambientes fechados. No trabalho normal diante do teclado, o(a) senhor(a) não precisa dele.

Para trocar de modo, não basta pedir no chat: é preciso fazer isso manualmente. No terminal, use Shift+Tab para percorrer os modos em ciclo ou o comando /plan para entrar no modo de planejamento. Também é possível definir o modo ao iniciar:

claude --permission-mode plan

O comando é digitado no terminal, dentro da pasta do projeto; /plan é usado em uma sessão já aberta. No editor, o seletor tem outra aparência e fica abaixo do campo de entrada, mas o indicador do modo atual é a referência em qualquer interface.

Há duas ressalvas importantes para não superestimar essa escala. O planejamento não é um backup: não cria um ponto de restauração nem desfaz o que já foi feito; apenas mostra o plano antes que ele vire alterações. E nenhum nível muda os limites da tarefa: eles continuam sendo os que o(a) senhor(a) descreveu.

Quando o auto atrapalha em vez de ajudar

Vale ajustar uma expectativa sobre o modo auto desde o início. Como o modo se chama "automático", pode parecer que tudo será executado. Não é bem assim: o classificador existe justamente para interromper algumas ações.

Por padrão, ele bloqueia, entre outras coisas, deploys em produção e migrações, o envio de dados para endereços externos, push forçado, exclusões em massa em armazenamento na nuvem, concessão de permissões, download e execução de código da rede e remoção irreversível de arquivos que já existiam antes do início da sessão. A lógica é simples: são ações que o(a) senhor(a) não consegue desfazer por conta própria.

O que acontece depois depende da quantidade de bloqueios. Uma ação bloqueada aparece na lista de itens recusados recentemente (/permissions, aba Recently denied) e pode ser executada novamente com confirmação manual. Enquanto isso, o Claude recebe a recusa e tenta outro caminho. Se o classificador bloquear três ações seguidas ou vinte durante uma sessão, o modo é pausado e o Claude Code volta a pedir confirmação como de costume. Depois da sua confirmação, o modo auto é ativado novamente. Os limites são fixos e não podem ser configurados.

Assim dá para perceber quando o modo começa a atrapalhar. Se há apenas um comando questionável na tarefa, auto funciona como esperado: o(a) senhor(a) o autoriza manualmente e segue em frente. Mas, se a tarefa é justamente composta por esses comandos - preparar um ambiente, executar migrações, trabalhar com uma infraestrutura de terceiros -, o resultado fica estranho. O(a) senhor(a) acaba confirmando quase cada etapa manualmente, só que com voltas desnecessárias: o agente encontra um bloqueio, procura outra maneira, e o modo ora é pausado, ora é reativado.

Nesse momento, é mais simples subir na escala por conta própria. Até qual nível depende do que está atrapalhando:

• default - a opção mais direta. Cada alteração e comando pede autorização, sem gerar recusas. É mais lento, mas o(a) senhor(a) acompanha cada etapa;
• acceptEdits - use quando as alterações nos arquivos são aceitáveis e os únicos comandos questionáveis são, por exemplo, os de deploy ou migração. Mas atenção: esse modo executa rm e mv na pasta de trabalho sem perguntar; no modo auto, o classificador bloqueava a remoção de arquivos existentes.

Isso não é contornar um bloqueio, e vale não confundir as coisas. O(a) senhor(a) não desativa a verificação; assume a responsabilidade por ela. Mesmo em bypassPermissions, a remoção de caminhos do sistema, como a raiz do disco ou a pasta pessoal, não é executada sem confirmação. Nesse modo e no auto, o Claude Code vai perguntar ao(à) senhor(a), e no terminal há uns dois minutos para responder. Onde não há como perguntar, o auto rejeita o comando, e o dontAsk sempre o rejeita. A ideia é outra: evitar uma etapa extra quando o(a) senhor(a) já pretendia confirmar tudo manualmente.

O segundo motivo para subir de nível não tem relação com bloqueios. O classificador decide se uma ação é arriscada, mas não se o trabalho está seguindo na direção certa. Se o agente altera a mesma coisa pela terceira vez e o resultado continua errado, no modo auto ele simplesmente fará uma quarta tentativa, também sem perguntar. Os desenvolvedores do Claude Code recomendam não insistir nesse momento: volte ao plan, alinhe o plano de novo e só então continue. O mesmo vale no início. Se o(a) senhor(a) entende a tarefa por completo, pode entregá-la logo a um modo mais livre. Se ainda não tem certeza do que deve sair, comece com plan.

O que muda no trabalho

No dia a dia, tudo se resume a quatro hábitos.

1. conferir o indicador no início do trabalho. Ele mostra o modo; as permissões já concedidas também importam para cada ação;
2. comparar o plano proposto com os limites da tarefa antes de executá-lo. Um item desnecessário pode ser removido com algumas palavras, e esse é o ajuste mais barato possível;
3. ler o texto da opção usada para aprovar o plano: ele informa em qual modo a sessão continuará depois de sair de plan;
4. verificar o resultado depois da execução. Nenhum modo garante que a tarefa foi resolvida corretamente; essa verificação cabe ao(à) senhor(a).

O modo de permissão responde à pergunta "o que pode ser feito sem mim?", não a "isso foi feito corretamente?". Qualquer que seja a escolha, a segunda pergunta continua sendo sua.