[Pitch] Como modelei o sistema de permissões do meu agente de IA (SAFE → YOLO): governança de confiança na prática

---

Transparência logo de cara: sou o autor do projeto que vou citar aqui, então isto é um [Pitch]. Mas o que eu quero compartilhar de verdade é uma decisão de engenharia: como desenhar um sistema de permissões para um agente de IA que mexe nos seus arquivos e roda comandos no seu terminal. O projeto é só o contexto; as ideias funcionam para qualquer agente.

O problema que eu não conseguia ignorar

Todo agente de coding hoje pede a mesma coisa: acesso ao seu disco e ao seu terminal. Aí você dá o comando, ele sai escrevendo arquivo, rodando bash, instalando dependência... e você fica olhando a tela torcendo pra nada quebrar.

Eu testei várias ferramentas e todas caíam num dos dois extremos:

1. Pergunta tudo, toda hora. Você vira um carimbador de "sim, pode continuar" e perde o fluxo.
2. Não pergunta nada. Roda solto, e quando você percebe, ele já refatorou metade do projeto.

Nenhum dos dois me servia. Eu queria uma terceira opção: o agente só tem a liberdade que eu dei a ele, naquele diretório, naquele momento — e eu posso aumentar ou diminuir essa liberdade com um comando.

A solução: 4 níveis de permissão × 3 tipos de ação

O modelo que implementei no Andromity (meu agente open source, MIT) é uma matriz simples:

Modo	Planos	Escrita em arquivos	Comandos no terminal
SAFE (padrão)	Aprovar cada um	Aprovar cada uma	Aprovar cada um
TRUST	Aprovar	Direto	Direto
FULL	Automático	Direto	Direto
YOLO	Automático	Silencioso	Silencioso

Três colunas porque "o agente pode mexer no meu código?" e "o agente pode rodar comandos?" são perguntas diferentes — e "ele precisa me mostrar o plano antes?" é uma terceira. Juntar tudo num interruptor único (on/off) é o que gera os dois extremos ruins do tópico anterior.

As decisões de design (a parte técnica de verdade)

1. Nada roda até a pasta ser confiável

Antes de qualquer modo de permissão, existe uma trava anterior: o diretório precisa ser marcado como confiável. É confiança por pasta, não global. A pasta do projeto do cliente que você abriu ontem por curiosidade? Continua trancada. Sua pasta de experimentos? Você confia e pronto.

Isso parece detalhe, mas resolve um problema real: agentes que herdam permissões amplas do ambiente. Aqui a permissão nasce no diretório de trabalho e morre com ele.

2. O padrão é o modo mais restritivo

SAFE é o default, sempre. Você começa aprovando tudo e sobe de nível conforme entende o comportamento do agente naquele projeto. É o princípio do menor privilégio aplicado a agentes: ninguém começa com a chave do cofre.

Na prática, meu fluxo diário é: SAFE numa pasta nova → TRUST quando o agente já entendeu a estrutura → FULL só em tarefas chatas e repetitivas → YOLO quase nunca, e só com /undo por perto.

3. YOLO é opt-in explícito, não acidente

Repare que o modo mais perigoso existe, mas você precisa digitá-lo de propósito. Isso é deliberado. Tem tarefa que realmente pede autonomia total — rodar a suíte de testes de madrugada e commitar o fix, por exemplo (o Andromity tem um agendador /cron embutido pra isso). Mas autonomia total tem que ser uma decisão consciente, não o resultado de você ter clicado "lembrar minha escolha" sem querer há três semanas.

4. Aprovação de plano ≠ aprovação de execução

No modo TRUST, você aprova o plano mas a execução é direta. Por quê? Porque revisar um plano ("vou criar 3 arquivos, editar 2, rodar os testes") custa 30 segundos de leitura. Revisar cada escrita de arquivo custa o seu fluxo inteiro. O plano é o ponto de alavancagem: é ali que um erro de entendimento aparece barato.

O modo de planejamento do Andromity inclusive trava antes de escrever qualquer linha: ele analisa o código, monta o passo a passo e espera você aprovar, pular ou editar cada etapa.

5. A rede de segurança: /undo sem tocar no git

Permissão nenhuma substitui um bom desfazer. O /undo reverte o último turno do agente — todas as mudanças de arquivo que ele fez — sem mexer no seu histórico do git. É o equivalente a dizer "volta tudo que você fez nos últimos 5 minutos". Isso muda a psicologia do uso: você experimenta mais porque o custo do erro caiu pra quase zero.

6. Sessões isoladas

Cada sessão tem seu próprio contexto, histórico e log de mudanças. Trocar de sessão (Ctrl+O) não mistura nada. Se um subagente em background fizer besteira, o /undo reverte só aquela sessão. Permissão também é sobre blast radius: quando algo dá errado, o estrago fica contido.

Quando usar cada modo (casos reais)

• SAFE — pasta de projeto que você abriu pela primeira vez; código de cliente; qualquer repo com dados sensíveis. É onde todo mundo deveria começar.
• TRUST — seu projeto pessoal que o agente já conhece; refatorações que você revisaria de qualquer jeito no diff.
• FULL — tarefas mecânicas: atualizar dependências, rodar linter em 40 arquivos, gerar testes boilerplate. Coisa que você aprovaria de olhos fechados mesmo.
• YOLO — jobs agendados de madrugada (/cron: "roda o pytest às 2h, corrige o que quebrou, commita"). Autonomia total, mas num horário em que você não está olhando — então o /waterfall (timeline ao vivo de tudo que o agente fez) vira seu relatório da manhã.

Como isso se compara

Vou ser honesto sobre o estado da arte, porque fingir que inventei tudo seria desonesto. Na tabela de comparação do README do projeto:

• Modelo de confiança por pasta: Andromity ✅ · Aider ❌ · Cursor ❌ · Claude Code ❌
• Níveis de permissão (SAFE → YOLO): Andromity ✅ · Aider ❌ · Cursor parcial · Claude Code ❌
• Cron embutido: só o Andromity tem (até onde eu sei)

O Cursor tem algo parecido com permissões parciais, e o Claude Code evoluiu bastante nessa área. A diferença de design que eu defendo: permissão por diretório como trava fundamental, não como configuração global.

O que eu aprendi construindo isso

Minha opinião sincera: a gente discute muito "qual modelo é mais inteligente" e pouco "quanto poder esse modelo deveria ter". Um agente mediano com permissões bem desenhadas me dá mais tranquilidade que um agente brilhante rodando solto no meu terminal. Confiança não é sobre o agente ser bom — é sobre eu poder dizer exatamente onde ele pode errar.

O projeto

Andromity é um agente de coding open source (MIT): extensão pro VS Code + CLI de terminal. Além da governança de permissões, tem /waterfall (timeline ao vivo da execução), modo de planejamento com aprovação, /cron (agendador embutido), 396+ modelos via BYOK (Claude, GPT-4o, Gemini, DeepSeek, Groq, OpenRouter) e Ollama 100% local e grátis. Chaves de API ficam criptografadas na sua máquina; seu código vai só pro provedor que você escolher.

Vou ser transparente sobre o tamanho: é um projeto pequeno, ~20 estrelas no GitHub, mantido por mim (sou dev indie, ~2 anos construindo plataformas web — POS, dashboards, marketplaces). Se a ideia das permissões por pasta fizer sentido pra você, feedback técnico honesto vale mais que estrela: o que você mudaria nesse modelo?

• 🌐 Site: https://andromity.agenticmarket.dev
• 💻 Repo: https://github.com/agenticmarket/andromity
• 📦 VS Code: code --install-extension agenticmarket.andromity-agent