Modos

O que é um modo

Um modo é uma propriedade de um espaço, armazenada como uma coluna na linha do espaço. Toda conversa dentro de um espaço o compartilha, incluindo as threads — uma thread herda o modo do seu espaço como qualquer outra conversa. Por isso, o mesmo agente pode estar em modos diferentes em espaços diferentes ao mesmo tempo, e trocar o modo de um espaço muda o que acontece no próximo turno sem tocar no agente.

Há exatamente quatro: chat, review, plan, orchestrate. O próprio enum não carrega nenhuma política. Tudo o que um modo garante é declarado uma única vez, em um perfil de capacidades, de onde cada camada de aplicação projeta:

Superfície de ferramentas — quais ferramentas existem nesse modo, expressas como um nível máximo de aprovação, uma lista de permissões, uma lista de negações e um conjunto de classes de efeito recusadas.
Verbo de saída obrigatório — o que a execução precisa chamar para ter entregado algo.
Classes de efeito negadas — o que os guardrails de ação recusam de plano.
Postura da worktree — se é possível escrever na worktree. Isso é aplicado removendo da superfície as ferramentas que mutam, e é o que faz a regra valer em qualquer host. Quando o host tem um sandbox do sistema operacional, essa mesma postura também define as regras de escrita do sistema de arquivos — um modo somente leitura monta a worktree como somente leitura —, mas essa é uma segunda cópia da garantia, não a que faz o trabalho.
Bloco de prompt do sistema — um preâmbulo de capacidades gerado a partir da lista de ferramentas realmente materializada, além de orientações escritas à mão.

Cada camada de aplicação projeta a partir desse único perfil, de modo que a superfície de ferramentas, os guardrails, a postura da worktree e o prompt não podem divergir.

Os quatro modos

Chat — exibido como “Agent”

É o modo padrão e o único sem restrições adicionais: a superfície de ferramentas completa até o nível de execução, uma worktree em que se pode escrever, nenhuma classe de efeito negada e nenhum contrato de conclusão. Use-o para implementação, correção de bugs, perguntas sobre a base de código e qualquer coisa pontual.

Preste atenção no rótulo: no composer, o modo é exibido como “Agent”, e não como “Chat”.

Plano — somente leitura, um único entregável

O modo plano torna a worktree somente leitura e remove por completo as ferramentas de escrita da superfície, então a restrição é estrutural, e não apenas instruída. O agente lê, pesquisa e investiga, e entrega exatamente uma coisa: uma chamada submit_plan que carrega um grafo de dependências tipado — um objetivo mais nós com chaves, títulos, descrições e as chaves dos nós de que cada um depende.

O plano aparece como uma linha compacta na conversa e abre o Plan Studio em uma aba ao lado dela. Aprová-lo compila o grafo em uma orquestração, executa o trabalho gerado e devolve o espaço de criação ao modo agente.

Se uma execução em modo plano terminar sem nunca chamar submit_plan, o loop primeiro injeta um lembrete dizendo que o plano não existe até que essa chamada dê certo. O lembrete autoriza explicitamente uma saída honesta do tipo “aqui não é necessário nenhum plano”, porque o modo plano é uma configuração do espaço e uma pergunta comum feita dentro dele não deveria forçar um plano falso.

Há uma segunda saída, separada: exit_plan_mode. Ela é um portão de aprovação rígido, não um verbo de saída — um agente que a chama em vez de submit_plan não entregou nada. A primeira chamada abre uma aprovação durável plan_exit e retorna pending, e o espaço continua somente leitura; chamadas repetidas continuam em pending em vez de abrir um segundo portão. Só depois que a aprovação é concedida é que uma chamada seguinte alterna o espaço para chat. Uma rejeição permite que o agente abra uma nova solicitação com um plano revisado.

Para sair do modo plano você mesmo, alterne o seletor de modo do composer (ou use Shift+Tab). exit_plan_mode é decidido com a ferramenta MCP decide_approval. As linhas de “aprovação de agente” da Caixa de entrada são outra coisa: prompts de confirmação por turno de um agente em execução.

Revisão — somente leitura, sem contrato

O modo de revisão serve para revisar PR. Ele torna a worktree somente leitura, limita a superfície de ferramentas para abaixo do nível de execução e aplica uma lista de permissões curada de ferramentas de revisão, tickets e comunicação. Um espaço aberto para uma pull request é criado automaticamente no modo de revisão.

A saída do agente são achados estruturados — nós de revisão — e, quando uma revisão é finalizada, um veredito. Um nó carrega um tipo (bug, suggestion, recommendation, question ou ticket), uma prioridade de P0 (bloqueia o lançamento) a P3 (desejável), uma confiança autoavaliada, uma âncora opcional (arquivo mais um intervalo de linhas; as notas de todo o repositório não têm nenhuma) e um status de ciclo de vida que passa de open para consensusReady quando um par — nunca o autor — o confirma. Um achado cuja prioridade ou confiança esteja ausente ou fora do intervalo é descartado na fronteira de leitura, em vez de poluir o veredito.

O veredito é ship, hold ou block, e os resultados por eixo incorporados a ele só podem torná-lo mais severo: um eixo com portão que falhou força block, e um eixo com portão que não pôde ser executado força pelo menos hold. A ausência de evidências nunca deixa um portão verde.

Diferentemente de plano e orquestração, a revisão não tem contrato de conclusão. Os achados se acumulam por meio de add_review_node e são publicados por finalize_review, e ambas podem legitimamente ser chamadas zero vezes — um agente de pipeline em execução no modo de revisão pode estar ali para concluir um ticket.

Orquestração — somente leitura, propõe uma equipe

O modo de orquestração transforma um objetivo em um plano de toda a equipe. Como o modo plano, ele é somente leitura e não pode escrever arquivos; além da superfície de pesquisa, ele tem um único verbo privilegiado, propose_orchestration, que emite uma proposta estruturada: funções, uma árvore de subtickets, uma etapa de síntese e um orçamento. O prompt nomeia apenas as ferramentas que estão na superfície, então o modelo não gasta turnos narrando contratações ou trabalho de tickets que não pode invocar.

Nada da proposta é executado até você aprová-la. Na aprovação, um materializador determinista contrata os agentes, cria os tickets e um projeto e executa um pipeline gerado. A aprovação é exclusiva do operador: não há ferramenta MCP para isso, então um agente pode propor, mas nunca aprovar o próprio plano. As repropostas iniciadas por um agente são limitadas por um intervalo de espera de dois minutos, então replanejamentos consecutivos são recusados e recebem a instrução de agrupar. Consulte Orquestração.

Duas regras que vale conhecer

O próprio verbo de saída de um modo nunca pode ser negado. submit_plan e propose_orchestration são fixados na superfície de ferramentas e pré-aprovados, passando por cima tanto do filtro de ferramentas quanto do portão de aprovação e dos guardrails de ação, de modo que o dial de autonomia por espaço não pode silenciar o entregável de um modo. A ask_user do harness está fixada pelo mesmo motivo: é assim que uma execução chega ao operador, então colocar um portão nela bloquearia uma execução que precisa perguntar algo. Ela é de nível de leitura, então todo modo somente leitura a mantém, e está isenta do wrapper de aprovação — um prompt na frente de outro prompt falha fechado quando não há nenhum aprovador conectado, o que negaria ao agente o próprio ato de perguntar.

Modos somente leitura não negam acesso à rede nem a segredos. As classes de efeito que revisão, plano e orquestração recusam são as que mudam o mundo: exclusão de arquivos, gravações fora da worktree, commits, pushes, criação e publicação de PR, gravações de sincronização com fornecedores, instalação de pacotes, criação de processos, mutação do espaço de trabalho e controle de recintos. A saída de rede e o acesso a segredos ficam nos valores padrão de propósito — a pesquisa é justamente o objetivo de um modo somente leitura.

Escolher e trocar de modo

O seletor de modo do composer oferece três opções: Agent (chat), Plan e Orchestrate. review não é selecionável pelo usuário — ele é definido pelo sistema quando um espaço de revisão de PR é criado e pelas etapas de pipeline.

Um nó de pipeline que abre um espaço pode fixar o modo dessa sala com uma chave extras['mode'] (chat, review ou plan). A chave exige correspondência exata: qualquer outra grafia — incluindo orchestrate — é ignorada em silêncio e a sala recebe o padrão do corpo (review no corpo de criação de espaço). Uma etapa de agente entra em uma sala que não criou e não redefine as permissões dela.

A resolução em si é simples. O dispatcher lê a coluna mode do espaço; um despacho sem espaço — uma execução pontual, uma invocação da CLI ou um id de espaço de outro espaço de trabalho, que simplesmente não está no arquivo de banco de dados deste espaço de trabalho — é resolvido como chat. Trocar o modo tem efeito a partir do próximo turno.

Onde a garantia de fato se sustenta

A superfície de ferramentas de um modo é construída e aplicada pelo harness integrado. Ele é o único transporte capaz de tornar uma ferramenta invisível em vez de apenas negá-la, de colocar um portão em cada chamada antes de ela rodar e de observar um contrato de conclusão.

No transporte do Claude Code, um modo diferente de chat é passado como --permission-mode plan. O Claude respeita isso por convenção; as próprias ferramentas de leitura, escrita e edição dele rodam sem serem vistas, e os comandos de shell dele só são verificados por um hook que lê a linha de comando. Para esse transporte, o modo é orientação, não uma fronteira do Control Center — consulte O modelo de agentes.

As listas de permissões restringem as ferramentas de nível de escrita e acima. O nível de leitura do harness integrado ainda alcança ferramentas que nenhuma lista nomeia; no Claude Code, uma ferramenta omitida pela lista de permissões é recusada independentemente de o servidor tê-la ou não.

Conceitos relacionados

Ciclo de vida do despacho de agentes: onde o modo é resolvido e projetado
O modelo de agentes: quais transportes podem aplicar um modo
Barreiras: a política de classes de efeito em que a predefinição de um modo desemboca
Orquestração: o que uma proposta de orquestração aprovada faz
Usar o modo plano: o passo a passo prático