Você dá a um agente de código uma tarefa pequena: corrigir um teste que está falhando. Vinte minutos depois, ele reescreveu três arquivos que não tinham nada a ver, rodou uma migração de banco contra qualquer DATABASE_URL que encontrou no seu shell e fez force-push para um branch que outra pessoa estava usando. Nada no prompt pedia nada disso. O agente tinha o controle total da máquina, então usou o controle total da máquina.
Permissões são a forma de decidir, antecipadamente, o que um agente pode tocar. Uma permissão de agente de código é uma regra que define quais arquivos, comandos, credenciais e repositórios um determinado agente pode acessar durante uma execução, e onde uma pessoa precisa intervir. Se você acertar, um agente que sair do script falha com segurança dentro de uma caixa que você delimitou. Se errar, uma única execução problemática chega à produção.
Este artigo percorre o modelo de permissões camada por camada, dá nome ao modo de falha em cada etapa e termina com uma checklist que você pode aplicar hoje mesmo. Ele usa o Sharkly para tornar cada camada concreta, porque o papel do Sharkly é ficar acima dos seus agentes de código e manter esse escopo em um só lugar. Você já tem agentes de código. O Sharkly os transforma em um time, e um time precisa de regras sobre quem pode fazer o quê.
As três camadas onde vivem as permissões de um agente
As permissões de um agente de código não são uma única configuração. Elas vivem em três lugares, e uma brecha em qualquer uma delas anula as outras duas.
- O runtime decide quais ferramentas o agente pode chamar: ler um arquivo, editar um arquivo, executar um comando de shell, acessar a rede. É o Claude Code, o Codex, o Gemini CLI ou qualquer agente que execute o trabalho.
- A máquina decide o que essas ferramentas podem alcançar: quais diretórios, quais credenciais, quais variáveis de ambiente, qual rede. Um Computer no Sharkly “fornece o sistema operacional, os arquivos, as credenciais, o acesso à rede e as ferramentas de que um Agente precisa”, então a máquina é o raio de impacto real.
- A tarefa decide a fronteira da intenção: a qual repositório esta execução está limitada, quais status o agente pode definir e o ponto em que uma pessoa aceita o resultado.
Vale dizer uma fronteira com todas as letras: uma permissão não é um portão de aprovação. Uma permissão é o que o agente pode fazer. Um portão de aprovação é onde uma pessoa decide. Você precisa dos dois. Permissões restritas sem nenhum portão significam que ninguém confere o resultado. Um portão com permissões frouxas significa que o estrago já está feito quando alguém olhar.
Etapa 1: limite o escopo das ferramentas do runtime
Comece por onde o agente age. A maioria dos agentes de código traz um sistema de permissões: uma lista de permissões e uma lista de bloqueios de ferramentas, além de uma confirmação antes que qualquer coisa destrutiva seja executada. O Claude Code, por exemplo, permite autorizar ou bloquear ferramentas específicas e pede confirmação antes de rodar comandos de shell; os nomes exatos das configurações variam conforme o runtime e mudam com frequência, então leia a documentação atual do seu agente em vez de usar um trecho que você encontrou no ano passado.
O padrão seguro é ser generoso nas leituras e econômico nas escritas. Deixe o agente ler o repositório, rodar testes, fazer typecheck e build sem pedir nada. Coloque edições de arquivos e comandos de shell atrás de uma confirmação ou de uma lista de permissões explícita.
O modo de falha tem nome, e é aquele a que todo mundo recorre quando o prazo aperta: o modo de pular tudo de forma indiscriminada. Todo runtime tem uma flag que desliga todas as confirmações, e ela é prática em uma sessão supervisionada. O perigo é deixá-la ligada em uma execução sem supervisão. Um agente que nunca precisa pedir nada, trabalhando a partir de um plano que se revelou errado, vai apagar alegremente aquilo que ele entendeu mal. Use o aceite automático quando estiver olhando. Desligue-o quando você se afastar.
Etapa 2: limite o escopo da máquina e das credenciais
A lista de ferramentas do runtime não vale nada se a máquina entregar tudo ao agente. Um agente autorizado a rodar comandos de shell na sua máquina do dia a dia consegue ler todas as chaves SSH, todos os .env e todas as credenciais que o seu próprio login alcança. O modo de falha é silencioso: nada parece errado até um agente usar uma chave de produção que ele nunca deveria ter visto.
Dois movimentos reduzem o raio de impacto. Primeiro, rode os agentes em um ambiente com escopo definido, em vez de no notebook onde você guarda seus segredos de verdade. O Sharkly registra um Computer com um token de instalação de uso único, que tem vida curta e só pode ser usado uma vez, e a documentação é direta: não coloque esse token em uma imagem reutilizável, script, Task ou comentário. Seja o Computer um contêiner, um servidor ou uma máquina reserva, o alcance do agente é o alcance daquele ambiente, não o seu. Se você quer agentes trabalhando enquanto está offline, rode-os em um Computer remoto em vez de no seu notebook aberto.
Segundo, entregue apenas o que uma execução precisa. O ambiente de uma execução do Sharkly é montado a partir de configuração explícita: repositórios anexados, variáveis de ambiente, bindings de segredos e um diretório de trabalho. Anexe repositórios a um Agente quando ele precisar de um escopo de código mais restrito que o padrão do Space, para que um Agente de frontend nunca faça checkout do serviço de billing. Mantenha cada execução em seu próprio worktree isolado, que é a diferença entre uma edição ruim ficar em um único checkout e dois agentes corromperem a mesma árvore de trabalho. A regra da casa vale para todo campo: preencha apenas a configuração que o produto pede e nunca cole senhas ou tokens em campos não relacionados ou em comandos de inicialização.
Etapa 3: limite o escopo da tarefa e deixe o merge para uma pessoa
A última camada é a intenção. Mesmo um agente corretamente isolado em sandbox e com credenciais restritas pode fazer o trabalho errado: marcar a própria tarefa como concluída, enviar uma alteração pela metade para um branch compartilhado ou decidir que um PR está pronto para merge.
É aqui que entra o contrato entre humano e agente. Agentes pesquisam, executam, testam e reportam. Pessoas definem a direção, concedem autoridade e aceitam o resultado. A automação para onde o julgamento do time é necessário. Um agente deve poder abrir um PR em rascunho e anexar a saída dos seus testes; não deve aprovar esse PR nem fazer merge dele no seu branch protegido. A proteção de branch no host e a revisão humana na tarefa são os dois cadeados que mantêm essa linha intacta.
No Sharkly, a própria tarefa carrega esse limite. Um Workflow do tipo Task restringe quais status um Agente pode selecionar, de modo que um Agente não pode mover silenciosamente o trabalho para um estado de “Concluído” ou “Lançado” que pertence a uma pessoa. Quando um Agente precisa de uma decisão, ele deixa a Task aguardando revisão humana ou resposta humana, e isso aparece na Inbox para a pessoa responsável aceitar, solicitar alterações ou reatribuir. Execução, bloqueios, resultados e a revisão retornam todos para a mesma Task, em vez de se espalharem por cinco terminais.
É também aqui que a configuração faça-você-mesmo para de escalar. Um agente, um repositório, um engenheiro cuidadoso: você consegue manter todo o modelo de permissões na cabeça. Adicione um segundo e um terceiro agente, mais repositórios e um colega de time, e “o que cada agente pode fazer aqui” se torna uma pergunta que ninguém consegue responder de memória. Um quadro de tarefas transforma essas regras em configuração compartilhada e inspecionável: quem atribuiu o trabalho, qual escopo a execução tinha, quais evidências voltaram e quem aceitou. Essa é a camada de gestão acima dos seus agentes de código. Você pode construí-la à mão com worktrees, credenciais com escopo restrito e proteção de branch, ou rodar seus agentes de código atuais pelo Sharkly e gerenciar as permissões, as tarefas e a revisão em um só lugar.
A checklist de permissões que você pode aplicar hoje
Percorra esta lista para cada agente que você deixa tocar um repositório de verdade:
- Runtime: leituras e testes liberados sem confirmação; edições e comandos de shell com portão; modo de pular tudo desligado em execuções sem supervisão.
- Máquina: o agente roda em um Computer com escopo definido, não na sua máquina do dia a dia; tokens de instalação e de acesso de uso único e nunca commitados.
- Credenciais: apenas as variáveis de ambiente e os bindings de segredos que esta execução precisa, nada colado em campos não relacionados.
- Escopo de repositório: o agente está anexado aos repositórios que seu trabalho exige, não a todos os repositórios do Space.
- Isolamento: cada execução tem seu próprio worktree, para que uma alteração ruim não possa corromper um checkout compartilhado.
- Escopo de tarefa: o agente pode definir status de trabalho, mas não pode mover uma tarefa para um estado de aceito ou lançado que pertence a uma pessoa.
- O merge: proteção de branch mais revisão humana com evidências no nível da tarefa ficam entre o PR do agente e a main.
Se alguma linha estiver frouxa, aperte-a antes da próxima execução, não depois do incidente que vai te ensinar por que ela importava.
Perguntas frequentes
Qual é a diferença entre permissões de agente de código e portões de aprovação? As permissões definem o que um agente é tecnicamente capaz de fazer: quais arquivos, comandos e credenciais ele pode alcançar. Um portão de aprovação é o ponto em que uma pessoa decide se aceita o que o agente fez. Você precisa dos dois, porque permissões restritas ainda deixam trabalho que um humano deveria validar, e portões de aprovação não ajudam se o agente já tinha permissão para causar dano.
Um agente de código deveria poder fazer merge dos próprios PRs? Não, não por padrão. Deixe o agente abrir um PR em rascunho e anexar a saída da sua verificação, e então deixe o merge para uma pessoa ou uma revisão obrigatória. A lógica é o contrato entre humano e agente: agentes executam e reportam, pessoas aceitam e lançam. Isso vale até para fluxos de trabalho com humano no loop, em que o agente faz a maior parte do trabalho.
É seguro rodar um agente com todas as confirmações de permissão desligadas? Só enquanto você estiver olhando. Os modos de aceite automático são úteis em uma sessão supervisionada, em que você consegue interromper um passo errado. Para execuções sem supervisão ou durante a noite, mantenha as confirmações ou uma lista de permissões ativas, e coloque o agente em uma máquina com escopo definido para que um erro fique contido.
