Antigravity MCP Bridge

Servidor MCP local para delegar tarefas de programação ao Google Antigravity por meio do CLI oficial agy. O Codex pode iniciar tarefas, acompanhar eventos, consultar resultados e cancelar processos. O projeto é independente e não é afiliado ao Google ou à OpenAI.

Codex -- MCP stdio --> bridge -- subprocesso --> agy oficial --> Antigravity
Codex <-- eventos e resultado estruturados <-- bridge <-- stdout/stderr

O bridge não acessa endpoints privados, cookies ou os armazenamentos de autenticação do CLI. Para candidatos a arquivos do projeto, o bridge realiza apenas inspeção local durante o preflight preventivo antes da cópia. A comunicação com o serviço é feita pelo próprio agy.

Requisitos

• Node.js 24 ou mais recente e npm. Esse requisito inicia o servidor; no Windows LPAC, ele não garante a compatibilidade de todos os subprocessos Node.

• Git 2.32 ou mais recente, disponível em uma entrada absoluta do PATH. Versões anteriores falham na admissão porque não oferecem o isolamento de configuração global exigido pelo bridge.

• Antigravity CLI oficial instalado e disponível no PATH (fonte primária de instalação). Você também pode definir AGY_PATH com o caminho absoluto do executável.

• Autenticação oficial concluída no agy. O CLI gerencia credenciais por meio dos mecanismos nativos do sistema operacional: Windows Credential Manager, macOS Keychain ou Linux Secret Service (via D-Bus). O bridge preserva diretórios de perfil e configuração, sessão de segurança, D-Bus, proxy, certificados, GEMINI_API_KEY e GOOGLE_GEMINI_BASE_URL. Variáveis de Google Application Default Credentials (ADC) e de ambientes corporativos (GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, GOOGLE_CLOUD_UNIVERSE_DOMAIN) são preservadas no ambiente por compatibilidade; o fluxo Enterprise não foi validado ponta a ponta. Consulte a documentação oficial do modo headless.

A descoberta (discover) do CLI executa --version e --help, exigindo exit code 0 em ambas as chamadas, saída não vazia e anúncio obrigatório das capacidades stream-json e --sandbox. Se o executável não for encontrado, a permissão for negada, a sondagem falhar ou o CLI não for compatível, o bridge emite os diagnósticos AGY_NOT_FOUND, AGY_PERMISSION_DENIED, AGY_PROBE_FAILED ou AGY_INCOMPATIBLE.

O bridge foi validado com agy 1.3.2 e @modelcontextprotocol/sdk 1.30.1. As tarefas delegadas exigem que o CLI anuncie --sandbox e stream-json; versões futuras podem exigir adaptação. No Windows, antigravity_test usa por padrão o executor local do bridge em AppContainer/LPAC; nos demais sistemas, usa o sandbox oficial do agy.

O Git local usa um ambiente próprio, com PATH restrito a diretórios fora do projeto e da cópia. Hooks, fsmonitor e configurações globais de execução ficam desativados; as regras de ignore são consultadas separadamente. Isso preserva a política de autenticação do agy. Quando o encerramento de um processo Git não pode ser comprovado após solicitação de término e janela delimitada de tolerância (pipes retidos), a operação falha com GIT_CLEANUP_UNVERIFIED, destruindo stdio e bloqueando a cópia com marcador no baseline privado para impedir reutilização, prévia, integração ou exclusão insegura de recursos potencialmente retidos, sem alegar falsamente limpeza comprovada.

Alterações textuais com bytes não-UTF-8 falham com UNSUPPORTED_PATCH_ENCODING, evitando corrupção na aplicação. Declare esses arquivos como binary no .gitattributes para obter patches binários do Git que preservem os bytes originais.

Related MCP server: Antigravity MCP Bridge

Versões disponíveis

Os exemplos de instalação selecionam a 0.9.0. Consulte a página do pacote no npm para conferir a versão distribuída.

A 0.9.0 inclui o Anti-AI Craft com as skills de código e segurança sempre carregadas e as demais sob demanda, redação de erros, frames, deltas, mensagens e estado antes da persistência, recusa de credenciais em entradas operacionais, confirmação do encerramento dos processos de cada execução, regras de delegação com restauração do fim de linha original nas prévias, sanitização única do estado salvo por versões anteriores e cancelamento efetivo de testes Windows recém-enfileirados.

A 0.8.0 acrescenta workflows no servidor, checkpoints, hooks de validação, memória privada, perfis completos, seleção de MCPs e ferramentas por tarefa, responsáveis e dependências, mensagens entre nós, espera conjunta, resultados JSON, artefatos com hashes e orçamento por consumo observado.

A 0.7.1 preserva entrega compacta, mensagens por sessão, skills selecionadas, execução simultânea e autorização prévia de integração, além das correções do Windows.

A 0.6.1 inclui executor Windows do bridge, permissões de sandbox controladas por ferramentas MCP e um runtime Node portátil opcional para LPAC. O runtime está publicado em um Release imutável; prepare-o explicitamente antes de usar o modo portátil.

A 0.5.1 inclui perfis, espera com progresso, transferência entre papéis, comparação de modelos e papéis personalizados. Ela amplia a margem de observação dos testes para suportar a preparação de cópias em runners mais lentos, preservando as verificações dos timeouts de execução.

Instalação

Servidor MCP via npm/npx

Para iniciar o servidor pelo pacote npm 0.9.0, configure seu cliente MCP com:

{
  "mcpServers": {
    "antigravity": {
      "command": "npx",
      "args": ["--yes", "antigravity-mcp-bridge@0.9.0"]
    }
  }
}

No Windows, clientes que exigem o nome completo do comando podem usar npx.cmd. O executável inicia o servidor em stdio; não é um comando interativo. O pacote contém o servidor compilado e os avisos das dependências incluídas. Node.js 24, Git e o agy autenticado continuam necessários. Para validar uma versão ainda não publicada, use npm run build:plugin, npm pack e o tarball local com npx --yes --package <caminho-do-tarball> antigravity-mcp-bridge.

Instalação pelo código-fonte

Os exemplos PowerShell usam npm.cmd, o lançador do npm para Windows, que funciona mesmo quando a política de execução bloqueia npm.ps1. Em outros shells, use npm.

git clone https://github.com/Zythenth/antigravity-mcp-bridge.git
cd antigravity-mcp-bridge
npm.cmd ci
npm.cmd run build:plugin
npm.cmd test

npm run build:plugin compila o servidor e gera plugin/server.mjs. Esse arquivo também acompanha o repositório para que o plugin possa ser instalado sem executar o build. npm start inicia o servidor MCP em stdio; a saída padrão fica reservada para JSON-RPC.

Runtime Node portátil no Windows LPAC

O servidor iniciado diretamente por npm usa o Node do sistema por padrão. O descritor distribuído com o plugin pede o modo portable, para que os testes Windows LPAC usem o runtime preparado no cache. Os modos são escolhidos somente na inicialização confiável do servidor com BRIDGE_WINDOWS_NODE_RUNTIME=system ou portable; entradas de ferramentas MCP não aceitam URL, hash nem caminho de cache.

No Windows, a inspeção do cache usa um helper nativo incluído no pacote, compilado com o .NET Framework já existente no sistema. O compilador também é necessário para consultar o estado do runtime portátil. Essa verificação lê os atributos e as marcas dos caminhos diretamente, sem iniciar PowerShell. O inspetor e a validação de caminhos de permissões aceitam as marcas IO_REPARSE_TAG_CLOUD a IO_REPARSE_TAG_CLOUD_F, usadas pelo OneDrive, e rejeitam junctions, links simbólicos e marcas desconhecidas em qualquer ancestral. Arquivos somente na nuvem precisam estar disponíveis para leitura. O cache continua separado do projeto. Compilação e inspeção compartilham um prazo de 15 segundos; os arquivos temporários do helper são removidos ao final.

Consulte o estado sem iniciar MCP, descobrir agy ou baixar arquivos:

node plugin/server.mjs --windows-runtime-status

No Windows x64, prepare explicitamente o runtime antes de usar o modo portátil:

node plugin/server.mjs --prepare-windows-runtime

Para preparar o runtime pelo pacote npm 0.9.0:

npx --yes antigravity-mcp-bridge@0.9.0 --prepare-windows-runtime

O status retorna JSON com requestedMode, supported, ready, buildId, nodeVersion, libuvVersion, sha256 e, quando necessário, error. Uma consulta sem suporte, sem cache ou com cache inválido continua sendo uma consulta bem-sucedida; uma falha de preparação retorna exit code 1. Preparação baixa somente os arquivos declarados do GitHub Release, confere tamanho e SHA-256 e instala o cache privado de forma atômica. Em caches situados em pastas sincronizadas (como OneDrive), toleram-se contagens extras ou transitórias de links (nlink) exclusivamente na leitura de assets com descritor confiável, tamanho e SHA-256 fixados, no staging da fonte do Node portátil com expectedSha256, e no lock de preparação do Node portátil (desde que device, inode e size permaneçam idênticos e o nonce/payload exato seja conferido, liberando com unlink apenas a entrada do próprio processo para preservar aliases). Hash, tamanho, identidade de arquivo, marcas reparse e layout de diretório permanecem estritamente obrigatórios; qualquer conteúdo alterado é recusado e aliases não são modificados. Destinos de runtime, executáveis genéricos e concessões de ACL continuam exigindo link único. O StateStore não oferece suporte genérico a armazenamento em nuvem. Inicialização, saúde e testes não baixam arquivos. Cache ausente no modo portátil exige --prepare-windows-runtime, sem voltar silenciosamente ao Node do sistema. Cache corrompido, alterado ou inseguro é recusado também pela preparação, que não o repara nem remove automaticamente. Antes de preparar novamente, uma pessoa deve inspecionar o caminho e remover manualmente somente o cache do build afetado; depois, executar --prepare-windows-runtime.

Mantenha o cache fora dos projetos. O bridge resolve os caminhos reais e recusa sobreposição em ambas as direções entre o projeto e BRIDGE_WINDOWS_NODE_CACHE_DIRECTORY, antes de consultar modelos, enfileirar a tarefa ou copiar arquivos. Essa regra também vale com includePaths e no modo system.

O runtime Node 24.21.0 LPAC1 para Windows x64 está publicado em um Release imutável, com ABI 137, libuv base 1.52.1 e apenas o PR 5181 aplicado. Ele não declara suporte geral a outras versões, arquiteturas ou plataformas. O cache instala somente node.exe, a LICENSE upstream e build.json; este último registra a fonte fixada, o patch, a ferramenta de compilação e a proveniência da execução. A seleção substitui somente o process.execPath conhecido desse runtime e o npm adjacente validado; executáveis Node ou npm personalizados permanecem selecionados como foram informados. A substituição portátil inicial de process.execPath e do npm adjacente exige Node 24 no host do servidor. O requisito geral Node >=24 permite iniciar o servidor, mas hosts Node 25/26 falham em testes elegíveis com PORTABLE_NODE_HOST_UNSUPPORTED. O cache persiste entre reinicializações normais do processo e do servidor, mas a persistência através de uma reinicialização física ainda não foi verificada.

Instalar como plugin do Codex

O repositório contém um catálogo em .agents/plugins/marketplace.json e o plugin em plugin/. Instale o catálogo e o plugin:

codex plugin marketplace add Zythenth/antigravity-mcp-bridge
codex plugin add antigravity@antigravity-mcp-bridge

Para atualizar, execute codex plugin marketplace upgrade antigravity-mcp-bridge e codex plugin add antigravity@antigravity-mcp-bridge. Abra uma nova conversa depois da instalação ou atualização. Peça, por exemplo: “Use $antigravity para implementar esta mudança e revisar o resultado.” A skill orienta a escolha de modelos, o acompanhamento da tarefa e a revisão final. Sessões já abertas não recarregam as ferramentas do plugin. Se o aplicativo não encontrar agy, configure AGY_PATH no ambiente em que o Codex é iniciado.

O guia oficial de plugins explica o formato do catálogo e outras opções de instalação.

Registrar somente o servidor MCP

Para usar o bridge sem a skill do plugin, compile o projeto e registre o servidor:

$server = (Resolve-Path .\dist\src\index.js).Path
codex mcp add antigravity -- node $server

Há também um exemplo de configuração TOML. Use uma forma de registro por vez para evitar ferramentas duplicadas.

Perfis de ferramentas

Defina BRIDGE_TOOL_PROFILE no ambiente do servidor e reinicie a conexão MCP:

O perfil é informado em antigravity_health.toolProfile. Ferramentas fora do perfil não são registradas e chamadas diretas são recusadas. query e review também recusam mode: "write"; omitir o modo seleciona leitura. Perfis reduzem o catálogo e restringem essas tarefas; o sandbox e a política de autorização da integração continuam necessários. Valores desconhecidos impedem a inicialização.

Espera com progresso

Prefira antigravity_wait com taskId, after e timeoutSeconds (1–60, padrão 30). Clientes que enviam _meta.progressToken recebem notificações notifications/progress com a sequência e o tipo de eventos reais, incluindo ferramentas, recibos de testes e conclusão. O número é um cursor de eventos, sem total ou porcentagem. Nenhum texto de arquivo, prompt ou saída do terminal é enviado nessas notificações.

A resposta inclui ready, timedOut, estado, uso de tokens e até 1.000 eventos. Continue com nextCursor; truncated informa eventos antigos perdidos. Timeout da espera e cancelamento da chamada MCP preservam a execução. Para parar a tarefa, use antigravity_cancel. Sem suporte a progresso, a resposta final continua disponível. A espera consulta também o estado persistido para observar tarefas de outro processo do bridge.

Transferência entre papéis

Use antigravity_context após uma tarefa concluída para inspecionar critérios, relatórios e treeSha256. Em seguida, chame antigravity_handoff com sourceTaskId, esse hash, role, prompt e, opcionalmente, model e decisions.

A nova tarefa recebe uma cópia independente dos arquivos atuais, incluindo alterações ainda não integradas. Mantém o baseline do projeto original, critérios, até oito relatórios de planejamento/revisão e a origem dos testes. Decisões são marcadas como relatos do cliente; relatórios e recibos mantêm sua origem e não autorizam integração. O pacote de contexto inteiro deve caber no limite do prompt; não há corte silencioso.

Planejamento → implementação → revisão pode mudar de papel e modelo sem reusar a conversa do papel anterior. O contexto é dado a conferir, não uma instrução de prioridade superior. Hashes são conferidos ao aceitar a tarefa e ao copiar, também quando ela aguardou na fila. A revisão verifica que sua cópia permaneceu intacta, incluindo arquivos ignorados. A cópia da implementação permanece disponível para testes, verificação e integração confirmada. Uma implementação iniciada a partir da revisão preserva o patch acumulado contra o original.

A cópia continua respeitando os ignores do projeto e limites de arquivos/bytes. Se a seleção mudar por novas regras de ignore, o handoff falha; inspecione o contexto novamente. Não inclua segredos em decisões. antigravity_resume conserva papel e cópia; antigravity_handoff cria outro papel em outra cópia e sessão.

Comparação entre modelos

Após antigravity_context, chame antigravity_compare com sourceTaskId, expectedContextSha256, prompt e models contendo 2 a 4 IDs distintos devolvidos por agy models. Cada modelo recebe uma cópia independente da mesma versão e executa uma revisão em leitura. A comparação consome a quota de cada tarefa; respeita MAX_CONCURRENT_TASKS, fila, retenção e limites de cópia. As cópias são preparadas antes de iniciar o grupo, evitando que revisores disputem a cópia de origem.

Guarde comparisonId e acompanhe cada taskId com antigravity_wait. antigravity_comparison reúne pareceres, erros, uso de tokens, modelos ausentes e os achados por arquivo/linha/citação. identical significa achados literalmente iguais; different, interpretações diferentes no mesmo trecho; not-reported-by-all, um trecho não relatado por todos. Ausência de achados não prova concordância nem correção.

complete exige todos os pareceres concluídos e suas cópias ainda correspondentes ao conteúdo comparado. contextStale sinaliza que a origem ou alguma cópia mudou, ficou indisponível ou não pôde ser conferida; confira contextMatches por parecer. Erros de início ficam em startErrors; falhas ou tarefas removidas não são ocultadas. O Codex deve conferir as fontes e sintetizar recomendações, divergências e limites de cada parecer. O agrupamento não faz votação semântica e não autoriza integração. As tarefas de comparação podem ser canceladas e descartadas individualmente.

Limites de interação e contagem prévia

antigravity_health.bridgeLimitations informa duas capacidades indisponíveis:

• interactiveReplies.available: false: o protocolo headless verificado recusa control_request e control_response. Mensagens de texto em novos turnos não respondem a solicitações pendentes de permissão. O bridge encerra o stdin após seu prompt; para continuar a conversa concluída, use antigravity_resume. Examine pedidos negados nos eventos e erros, sem contornar o sandbox. A confirmação MCP da integração continua sendo uma operação separada do bridge.

• preflightTokenCount.available: false, exactTokens: null: não há comando do agy verificado para contar tokens antes do envio. O uso informado pelo CLI é observado após execução. Tamanho em caracteres não é uma contagem exata de tokens nem um orçamento de quota. O bridge permanece no CLI oficial, sem API adicional, novas credenciais ou estimador apresentado como contagem exata.

Essas limitações não são resolvidas por manter o processo aberto ou inventar mensagens do protocolo. Um suporte futuro exige verificar a versão e o contrato oferecido pelo CLI antes de adicionar a operação.

Entrega ao agente principal

Use deliveryMode: "messages" em antigravity_run para receber perguntas públicas estruturadas, bloqueios e um trecho do resultado final. antigravity_wait devolve messages e cursores de mensagens, sem os eventos e notificações de progresso detalhados. Uma pergunta observada pode encerrar a espera antes do fim da tarefa. O principal lê resultados e diffs completos somente quando necessários, pelas ferramentas de leitura em partes.

Cada mensagem inclui origem, modelo informado, ID, sequência e data; cada texto tem no máximo 2.000 caracteres. Até 100 mensagens são retidas por tarefa e as páginas indicam perdas de mensagens antigas. O resultado final aponta para antigravity_read_result, com o hash correspondente. As mensagens do modelo continuam sendo relatos, sem comprovar testes nem autorizar integração.

Omitir a opção conserva events, com o histórico de eventos existente. antigravity_events continua disponível para uma consulta detalhada explícita. antigravity_set_delivery_mode muda a entrega de uma tarefa; reinicie o cursor em after: 0 após trocar de modo. Passe também cursorMode com o modo do cursor anterior: se o modo de entrega mudar, a espera reinicia em zero e informa cursorReset: true. A retomada herda a escolha, que não altera permissões ou papéis.

Execução simultânea

A instalação do plugin configura duas tarefas simultâneas; o servidor independente mantém uma por padrão. MAX_CONCURRENT_TASKS aceita 1 a 16. Retomadas da mesma cópia continuam sequenciais.

Mensagens para a sessão

Use antigravity_send_message({taskId, messageId, text}) para enviar até 2.000 caracteres; messageId é um UUID escolhido pelo cliente. Repetir o mesmo ID e texto retorna o recibo existente. Outro texto com o mesmo ID é recusado. Até 20 inputs ficam retidos por tarefa.

Se o turno estiver ativo, o recibo fica queued. Após sua conclusão, o bridge retoma a sessão oficial na mesma cópia e processa os inputs em sequência. sent indica aceitação do novo turno pelo bridge, sem provar que o modelo leu a mensagem. Falhas e cancelamento ficam explícitos; um envio interrompido sem evidência de aceitação não é repetido automaticamente.

Acompanhe continuationTaskId com um novo cursor em zero. continuationPending: true em antigravity_wait indica inputs aguardando despacho; o término do turno anterior não encerra toda a conversa. Retomadas preservam seleção, skills, papel, modo e critérios. Mensagens não concedem permissões nem aprovam integração; solicitações de controle do agy continuam indisponíveis.

Modos de aprovação e integração

O servidor MCP suporta modos de aprovação controlados pela variável BRIDGE_APPROVAL_MODE no ambiente do servidor. Quando a variável não estiver definida (unset), o modo padrão é auto. Os valores aceitos são estritamente auto ou ask; valores inválidos causam erro na inicialização.

• Modo automático (auto, padrão): antigravity_integrate autoriza automaticamente a integração de alterações quando o patch estiver verificado contra o hash atual, dispensando formulários interativos MCP de confirmação humana. Atualizações validadas da política de sandbox (antigravity_set_sandbox_policy) também são aplicadas automaticamente. Nenhuma confirmação manual extra é exigida do chamador em auto. O chamador pode propor concessões estreitas e verificadas necessárias à tarefa autorizada. Agentes delegados via agy (Gemini) NÃO escolhem, não autorizam nem proporcionam permissões. O modo automático não afrouxa os controles de segurança: tarefa de escrita concluída, hash SHA-256 da prévia, critérios de aceitação aprovados via antigravity_verify, revisão fundamentada nos arquivos reais, testes observados atuais sem falhas, source-lock, CAS e proteção estrita de caminhos (path-protection) continuam estritamente obrigatórios. Em antigravity_health, o servidor anuncia approvalMode: "auto", integrationApproval.mode: "auto" e integrationApproval.method: "automatic".

• Modo de confirmação estrita (ask): opt-in estrito onde antigravity_integrate exige SEMPRE confirmação humana interativa via formulário MCP (MCP form elicitation), assim como atualizações de teto de sandbox (antigravity_set_sandbox_policy). Não há bypass para raízes previamente configuradas no ambiente (BRIDGE_PREAUTHORIZED_INTEGRATION_ROOTS) ou raízes lembradas legadas (integration-approvals.json); no modo ask, a confirmação é sempre exigida. O checkbox de memorização ("Não pedir novamente neste projeto") foi removido do formulário. Em antigravity_health, o servidor anuncia approvalMode: "ask", integrationApproval.mode: "ask" e integrationApproval.method: "mcp-form-elicitation".

Para configurar o modo de forma persistente, defina BRIDGE_APPROVAL_MODE no ambiente privado de inicialização do servidor MCP (por exemplo, na configuração do cliente MCP ou nas variáveis de ambiente persistentes do sistema ou do usuário). Exemplos em PowerShell ($env:BRIDGE_APPROVAL_MODE = 'ask') afetam apenas o shell atual em execução. É necessário reiniciar a conexão MCP após alterar as variáveis de ambiente para que as modificações tenham efeito.

Nenhum modo introduz fallback automático para execução no host, nem altera as permissões do Codex ou do agy. A integração é realizada exclusivamente via MCP; autorizações não substituem verificações de critérios, testes e revisão técnica. Texto do Gemini, mensagens do chamador e argumentos de ferramentas não concedem autorização nem permissões de sandbox.

antigravity_health.integrationApproval.preauthorizedProjectCount informa a quantidade de raízes configuradas ou lembradas legadas; no modo ask, todas as integrações continuam exigindo confirmação humana independente desse total.

Anti-AI Craft incluído

O pacote traz um snapshot verificado do Anti-AI Craft com seis skills. Em toda tarefa nova, anti-ai-code e anti-ai-security são preparadas na cópia como skills permanentes e o Gemini é instruído a lê-las antes de trabalhar. anti-ai-design, anti-ai-design-flow, anti-ai-audit e anti-ai-remediate aparecem apenas como catálogo (nome, descrição e caminho, até 8 KiB); seus corpos, referências e imagens ficam fora do prompt e são lidos sob demanda, somente leitura, a partir de uma cópia privada por revisão em <estado>/anti-ai-craft/, adicionada ao CLI com --add-dir. Sob política de ferramentas, os hooks permitem apenas leitura nessa raiz. A seleção situacional é uma política desta integração: o Gemini escolhe pela pertinência da tarefa, sem exigir o nome literal da skill.

O snapshot é verificado contra o manifesto (tamanho e SHA-256 de cada arquivo) antes de cada tarefa nova; conteúdo ausente ou adulterado falha com CRAFT_SNAPSHOT_INVALID ou CRAFT_SNAPSHOT_MISSING, sem download automático, e a correção é reinstalar a versão do bridge. Retomadas e handoffs conservam o snapshot da sessão original. As permanentes contam no limite de oito pacotes e de 1 MiB das skills fornecidas; uma skill fornecida com o mesmo nome e conteúdo idêntico é deduplicada, e conteúdo diferente falha com SKILL_CONFLICT. Arquivos das skills não entram no patch.

BRIDGE_ANTI_AI_CRAFT=off desativa a política para todas as tarefas. BRIDGE_ANTI_AI_CRAFT_DIRECTORY aponta para outro snapshot com o mesmo formato, que também é verificado contra o próprio manifesto. Disponibilizar as skills não instala o MCP do Anti-AI Craft, Graphify, Python ou outras ferramentas que elas mencionem. As imagens da biblioteca visual mantêm as licenças de suas fontes; consulte THIRD_PARTY_NOTICES.md.

Skills fornecidas pelo cliente

O Codex ou outro cliente pode enviar skills selecionadas em antigravity_run.skills. No modo compacto, providedSkillSummaries contém apenas nome, hash e quantidade de arquivos. Cada pacote contém o texto de SKILL.md e, opcionalmente, recursos de texto com caminhos relativos à skill:

{
  "workingDirectory": "/caminho/absoluto/do/projeto",
  "prompt": "Use a skill review-style para revisar o projeto.",
  "mode": "read-only",
  "skills": [{
    "name": "review-style",
    "content": "---\nname: review-style\ndescription: Regras de revisão\n---\nLeia references/check.md antes de revisar.",
    "resources": [{ "path": "references/check.md", "content": "Confira os requisitos contra os arquivos reais." }]
  }]
}

O bridge prepara apenas os pacotes enviados em .agents/skills/<nome-em-minúsculas>/ dentro da cópia. Preserva o nome declarado e os bytes UTF-8, incluindo nomes como Presentations. Os metadados retornados contêm nomes, caminhos relativos e hashes; não repetem os textos das skills. Skills globais não são descobertas nem importadas automaticamente. O cliente deve selecionar e fornecer também os recursos necessários, mantendo arquivos privados e credenciais fora do envio.

Limites: 8 skills, 100 recursos por skill e 1 MiB de texto no total. Esses arquivos também contam nos limites de arquivos e bytes da cópia. Caminhos absolutos, travessia, nomes de dispositivos, aliases de caixa, links e colisões com pastas existentes na cópia são recusados. O preparo não executa os scripts fornecidos. Dependências de ferramentas precisam existir no agy; uma skill não concede novas permissões.

A retomada e o handoff conservam os pacotes originais e seus hashes. Não é possível fornecer skills novamente numa retomada, mesmo como lista vazia; use uma nova tarefa para outra seleção. Alterar, remover ou acrescentar recursos numa skill fornecida invalida a verificação. Os arquivos auxiliares não entram no patch do projeto original. Omitir skills preserva o uso de skills que já pertençam aos arquivos elegíveis do projeto.

Papéis personalizados

Defina BRIDGE_CUSTOM_ROLES como um array JSON no ambiente do servidor e reinicie a conexão. Exemplo PowerShell:

$env:BRIDGE_CUSTOM_ROLES = '[{"name":"security-review","baseRole":"reviewer","description":"Revisão de controles de acesso","instruction":"Examine os controles de acesso do escopo solicitado e cite evidências reais."}]'

antigravity_roles lista os nomes disponíveis, descrições, base e tamanho das instruções. Selecione o nome em role de antigravity_run ou antigravity_handoff; os schemas MCP anunciam os nomes configurados. Cada papel tem nome de até 32 caracteres em letras minúsculas, números e hífens, baseRole e instruções de até 8.000 caracteres. A descrição é opcional, até 500 caracteres. Há até 20 papéis; nomes duplicados, substituição dos três nomes nativos, bases desconhecidas ou instruções vazias impedem a inicialização.

As bases planner e reviewer conservam modo de leitura, contratos JSON e conferência de citações. implementer conserva o fluxo de escrita na cópia e as mesmas exigências de verificação e confirmação para integração. Instruções personalizadas não dão permissões extras e entram no limite total do prompt. A definição usada é salva com a tarefa; a retomada mantém instruções e base originais, mesmo após mudar a configuração. Para trocar de papel, crie uma nova tarefa ou faça handoff.

Grupos de tarefas e espera conjunta

O cliente cria um grupo com UUID estável, raiz Git, título e até 32 tarefas. Cada tarefa tem uma chave única, owner com um papel configurado, dependsOn e as opções de execução em task. Dependências desconhecidas, duplicadas, ciclos e definições maiores que 4 MiB são recusados. Há até 100 grupos retidos.

Exemplo de definition para antigravity_group_create:

{
  "workingDirectory": "<raiz-git-absoluta>",
  "title": "Inspeção sequencial",
  "jobs": [
    { "key": "inspect", "owner": "implementer", "dependsOn": [],
      "task": { "prompt": "Inspecione os arquivos selecionados.", "mode": "read-only",
        "acceptanceCriteria": [{ "id": "inspection", "description": "Inspeção fundamentada nos arquivos selecionados" }] } },
    { "key": "check", "owner": "implementer", "dependsOn": ["inspect"],
      "task": { "prompt": "Confira os requisitos da tarefa.", "mode": "read-only",
        "acceptanceCriteria": [{ "id": "requirements", "description": "Conferência fundamentada dos requisitos" }] } }
  ]
}

Repita o mesmo UUID e a mesma definição para consultar uma criação com resposta perdida; outra definição com esse UUID retorna GROUP_CONFLICT. O início exige o hash devolvido. O servidor admite um nó somente após todos os seus pré-requisitos terminarem com sucesso. Falha ou cancelamento bloqueiam os dependentes. Cada nó tem sua própria cópia; dependências controlam a ordem e não integram automaticamente alterações entre cópias.

Os grupos usam entrega messages. Cada nó aplica hooks da política nativa dentro da cópia, com as ferramentas de arquivo permitidas pelo teto humano e finish. MCPs entram por seleção da tarefa ou por um padrão explícito do perfil. A raiz do projeto precisa permanecer canônica e separada do estado privado do bridge. As esperas devolvem no máximo quatro mensagens no total, uma por tarefa, com nextCursor, oldestAvailable e truncated. Passe os cursores anteriores na próxima espera. hasMoreMessages e hasMore sinalizam mensagens ainda não lidas, inclusive quando ready já for verdadeiro. As respostas não incluem prompts, histórico de ferramentas ou resultados intermediários completos; use os leitores por partes quando precisar deles. Cancelar a espera preserva a execução.

Após reiniciar o servidor, resumeRequired informa a necessidade de retomada explícita. O coordenador recupera IDs já aceitos e não repete nós concluídos. Se uma admissão interrompida não tiver identidade verificável, retorna GROUP_ADMISSION_UNVERIFIED; não inicia outra execução silenciosamente. Alterar o perfil de um responsável pausa novas admissões com GROUP_PROFILE_CHANGED. Tarefas removidas pela retenção retornam erro, sem repetição.

O estado completed informa o término das execuções. Integração continua exigindo revisão, testes, verificação atual e hash por tarefa. Os registros de grupo ficam no estado privado até remoção local; descarte as cópias antes de apagar registros, conforme Privacidade.

Workflows e checkpoints

Acrescente workflow à definição do grupo:

{
  "finalNode": "check",
  "hooks": {
    "inspect": { "requireReview": true }
  },
  "fileSources": { "check": "inspect" }
}

O nó final precisa depender, direta ou indiretamente, de todos os outros nós. Cada etapa exige acceptanceCriteria. O servidor verifica as condições de arquivo antes de liberar dependentes. Critérios sem uma verificação automática exigem revisão com citações conferidas nos arquivos reais. requireReview exige essa revisão mesmo com verificações automáticas; requireTests exige evidência observada de execução, vinculada ao patch e à árvore atuais. Registros client-reported não satisfazem esse hook. Testes diretos exigem uma etapa de escrita baseada em implementer e um executor compatível; a falta dessa capacidade não autoriza execução no host.

Os resultados JSON e artefatos permanecem no estado privado. Etapas de implementação sem formato explícito usam {"summary":"..."}; formatos dos perfis e contratos de outros papéis são preservados. Os predecessores fornecem JSON validado e hashes ao próximo nó; a síntese final recebe os intermediários concluídos. O contexto tem até 64 KiB UTF-8. Excesso retorna WORKFLOW_CONTEXT_TOO_LARGE, sem truncamento silencioso ou estimativa de tokens.

fileSources escolhe uma dependência direta como base dos arquivos de uma etapa. O servidor confere seu checkpoint e cria outra cópia. Outros predecessores fornecem dados; não há mescla automática de arquivos. A seleção de arquivos e skills da base é preservada: omita includePaths e skills no destino. As regras existentes de transferência de memória continuam válidas; memory: [] permite não herdar snapshots.

Checkpoints guardam hashes da árvore, patch, resultado, artefatos e validação. Saídas com revisão ou testes pendentes são retidas e pausam o grupo. Depois da verificação, retome com antigravity_group_start e o mesmo hash de definição. O servidor revalida os dados e não repete a chamada já concluída. Alterações em arquivos ou resultados retornam WORKFLOW_CHECKPOINT_CHANGED; identidades perdidas não autorizam repetição. Novas mensagens não podem alterar uma etapa já checkpointada.

antigravity_group_wait mantém os intermediários fora da resposta, preservando perguntas, bloqueios e erros públicos. antigravity_workflow_result revalida os checkpoints e entrega somente a síntese pública final e uma referência com hash. Uma execução posterior com falha impede disponibilizar uma síntese como atualmente validada. Essas verificações cobrem as condições declaradas; a integração mantém seus próprios testes, revisão e confirmação ou autorização prévia.

Orçamento observado por grupo

Use "budget": {"maxTotalTokens": 100000} na definição. Sem esse campo, o comportamento existente é preservado. Com teto configurado, o grupo aguarda os contadores do turno atual antes de admitir outro. O controle inclui continuações, mensagens entre nós e reparos com modelo; retomadas contam a diferença da sessão e execuções locais sem modelo têm consumo conhecido zero.

O status informa observedTotalTokens, subtotal conhecido, tarefas sem medição, margem e estado do orçamento. Contadores ausentes ou identidades retidas perdidas bloqueiam novas chamadas com GROUP_USAGE_UNAVAILABLE; atingir o teto pausa com GROUP_BUDGET_EXCEEDED. O teto faz parte da definição imutável do grupo.

Esse controle impede novas admissões conforme consumo observado. Um turno já aceito pode ultrapassar o teto; o CLI não oferece previsão exata de tokens ou preço antecipado. Não há substituição de dados ausentes por estimativas.

Mensagens entre nós

O chamador seleciona rotas direcionadas em definition.peerRoutes, por exemplo [{"from":"inspect","to":"check"}]. Omissão ou [] nega envios. Não há direção inversa ou broadcast implícitos. Limites: 128 rotas, 20 mensagens por nó de origem durante o grupo e 100 por grupo.

O delegado recebe os destinos permitidos e emite uma resposta pública <antigravity-peer-message>{"messageId":"<uuid-estável>","toNode":"check","text":"descoberta"}</antigravity-peer-message>. O texto tem até 2.000 caracteres. O servidor verifica responsável, raiz de conversa, projeto e definição; a entrada chega ao destinatário como dados sem autorizar ferramentas ou integração.

A entrega aguarda a admissão do destinatário e o fim do turno ativo, usando a continuação oficial do CLI. Cada novo turno pode consumir quota. queued informa espera; sent informa aceitação da continuação, sem comprovar leitura pelo modelo. Dependências aguardam os turnos adicionais, e a espera conjunta acompanha o turno mais recente.

antigravity_peer_receipts recebe groupId, after e limit de 1 a 20. Os recibos trazem origem agy-reported, destinos, estado e SHA-256; corpos e IDs internos de transporte ficam fora da página. O cursor pagina um retrato: releia a página para conferir estados alterados. Resultados públicos do destinatário podem reproduzir dados recebidos e permanecem disponíveis pelos leitores normais.

Mesmo ID e conteúdo preservam a identidade. Conteúdo conflitante pausa com PEER_MESSAGE_CONFLICT; limites e truncamento pausam com PEER_LIMIT_EXCEEDED. Confirmação ambígua exige inspeção e retomada explícita, reutilizando o ID persistido. Rota negada ou destinatário encerrado produz falha sem outra sessão. O cancelamento alcança continuações ativas; grupos encerrados recusam novos turnos.

Em tarefas de implementação com política nativa e sem schema de saída explícito, o bridge oferece o formato JSON {"summary":"..."} para disponibilizar a chamada guardada finish. Schemas explícitos e contratos de outros papéis são preservados. Envelopes no campo público summary também são reconhecidos; isso não expõe raciocínio privado.

Memória privada por projeto e especialista

A memória fica no estado privado do servidor, separada pela raiz Git canônica e pelo identificador do especialista. Nenhum arquivo do projeto é importado automaticamente.

Exemplo de seleção em antigravity_run, depois de ler e conferir a memória:

{ "memory": [{ "specialist": "reviewer", "sha256": "<hash-atual-de-64-caracteres>" }] }

O chamador escolhe até oito entradas. O texto selecionado é enviado ao CLI como dados revisáveis, dentro do limite total do prompt; ele não concede permissões nem substitui as instruções da tarefa. Os retornos de tarefas incluem somente os metadados da memória, inclusive na entrega compacta. O conteúdo não é preparado como arquivo auxiliar nem integrado ao projeto.

memory também pode ser um padrão explícito de especialista. Uma lista vazia substitui esse padrão. A retomada conserva os snapshots originais, mesmo após substituir ou remover a memória armazenada; fornecer memory outra vez numa retomada é recusado. Handoffs herdam o snapshot por padrão e permitem uma seleção explícita diferente ou memory: [].

Os padrões globais são 100 entradas, 1 MiB de texto e 64 KiB por entrada, medidos em UTF-8. Escritas usam comparação de hash e lock entre processos; versões divergentes retornam MEMORY_CHANGED. Links, junções de armazenamento, arquivos corrompidos e hashes inconsistentes são recusados. Perfis query e review permitem somente listar e ler. Textos com formatos de credencial de alta confiança são recusados com INPUT_SECRET_DETECTED, assim como prompts e mensagens. Entradas antigas com esses valores são lidas redigidas e não podem ser selecionadas.

Remover uma entrada não apaga os snapshots já guardados nas tarefas retidas. O descarte da cópia também preserva esses registros. Consulte Privacidade para apagar o estado local; o bridge não oferece criptografia própria.

Controles por especialista e tarefa

Papéis personalizados aceitam defaults com model, effort, skills, includePaths, outputSchema, artifactPaths, deliveryMode, timeoutSeconds, allowedTools, mcpServers e memory. Argumentos explícitos substituem cada campo completo, sem mesclar listas; model: null mantém Auto. A retomada conserva o snapshot original. Schemas de resultado personalizados exigem base implementer; os outros papéis mantêm seus contratos próprios.

A pessoa usuária configura no ambiente do servidor:

• BRIDGE_ALLOWED_AGY_TOOLS: array JSON que limita as ferramentas nativas. Valores aceitos: view_file, write_to_file, replace_file_content, multi_replace_file_content e finish. A finalização permanece implícita. Um teto configurado é aplicado mesmo quando o chamador omite seletores.

• BRIDGE_MCP_CATALOG: até 20 servidores confiáveis, cada um com id, transporte e tools: [{name, readOnly}]. O transporte é command absoluto com args/env/cwd opcionais, ou serverUrl HTTPS/HTTP de loopback com headers opcionais. nativeServerName permite um alias nativo estável definido pela pessoa usuária.

No CLI com os nomes atuais, read_file corresponde à capacidade view_file, write_file a write_to_file e edit_file exige replace_file_content ou multi_replace_file_content. Esses nomes usam Path; os seletores acima permanecem compatíveis. O hook rejeita alvos ambíguos e aplica as mesmas verificações de caminho e modo somente leitura. O recibo registra o nome efetivamente chamado.

Consulte antigravity_get_agent_policy antes de escolher allowedTools e mcpServers: [{serverId, tools}] em antigravity_run ou antigravity_handoff. O catálogo público mostra apenas IDs, aliases, descrições e ferramentas; transportes e credenciais não entram no prompt nem na política devolvida. Listas vazias selecionam somente a finalização e nenhum MCP. Sem configuração global nem seletores, tarefas antigas conservam o comportamento anterior. Uma sessão antiga sem controles exige nova tarefa depois de configurar um teto global.

Os hooks nativos restringem arquivos à cópia, bloqueiam ferramentas não escolhidas e impedem alterações da configuração auxiliar. Leituras em .agents são limitadas aos arquivos de skills explicitamente fornecidos. Helpers são conferidos por hash e ficam fora dos patches. A finalização precisa de recibo novo vinculado à política e à conversa; uma finalização anterior não valida a retomada. O handoff cria seus próprios controles e recibos, conservando a seleção e reduzindo ferramentas incompatíveis com leitura.

O agy também exige uma autorização nativa mcp(alias/ferramenta) em suas configurações. O bridge não concede essa autorização nem altera configurações globais; a ausência aparece como AGY_MCP_PERMISSION_REQUIRED. Servidores stdio são programas confiáveis executados no host: os hooks controlam chamadas do modelo, sem isolar a implementação interna desses serviços.

No Windows, testes pelo executor LPAC continuam disponíveis. A configuração MCP auxiliar mantém uma DACL protegida e não recebe acesso do processo de teste. A seleção de ferramentas não concede terminal: o executor legado BRIDGE_TEST_EXECUTOR=agy recusa testes diretos de tarefas com essa política usando POLICY_TEST_EXECUTOR_UNAVAILABLE.

Ferramentas

Todas as ferramentas publicam outputSchema com campos e tipos de suas respostas estruturadas. O contrato contempla sucesso e error: { code, message }. O SDK confere os campos obrigatórios antes de entregar respostas de sucesso; clientes também podem validar o JSON recebido. Dados brutos do CLI continuam com tipo aberto porque seu formato pertence ao provedor. O contrato não transforma uma alegação do modelo em prova de execução.

antigravity_run recebe prompt, workingDirectory absoluto na raiz de um repositório Git e, opcionalmente, model, timeoutSeconds, mode e includePaths (arquivos ou pastas relativos à raiz). Sem includePaths, copia todos os arquivos rastreados e não rastreados que não correspondam a .gitignore, .git/info/exclude ou às outras regras de ignore do Git. O filtro também exclui arquivos rastreados que passaram a ser ignorados. includePaths apenas reduz essa seleção; não permite incluir arquivos ignorados. Links simbólicos e caminhos fora da raiz são recusados. Consulte antigravity_list_models antes de selecionar um modelo.

Política de sandbox dos testes

antigravity_get_sandbox_policy devolve a política global normalizada e seu sha256 para os testes Windows LPAC. Ela é o limite máximo para readRoots, writeRoots, network, childProcesses e maxOutputChars. A configuração inicial não concede raízes externas, desativa rede, permite processos filhos e limita a saída a 4.000 caracteres.

O agente que chama o MCP, seja o Codex ou outro cliente, escolhe em cada antigravity_test Windows sandbox: { readPaths, writePaths, network, childProcesses, maxOutputChars } dentro desse limite. O bridge recusa caminhos que ultrapassem as raízes aprovadas ou que coincidam com a origem, credenciais, armazenamento do bridge, temporários controlados, links, aliases ou outros caminhos protegidos. A seleção fica vinculada à evidência do teste e ao hash da política usado. No caminho legado agy, uma seleção explícita não é aceita; sem seleção, ele conserva o comportamento anterior.

Para ampliar ou reduzir o limite global, leia antes a política e chame antigravity_set_sandbox_policy com seu hash atual e a proposta. Em modo auto, propostas validadas de teto global de sandbox são aplicadas automaticamente sem exibir formulário; em modo ask, o cliente MCP deve apresentar o formulário interativo com comparação do hash anterior. A comparação e gravação evitam substituir uma política que mudou enquanto a proposta era avaliada. O agente que chama o MCP escolhe concessões estreitas e verificadas necessárias por teste dentro desses limites; o Gemini delegado via agy não pode escolher, autorizar nem alterar concessões. Alterações afetam testes novos e os que ainda estiverem na fila; elas não revogam promessas de permissões de trabalhos ativos nem realizam fallback ao host.

Por exemplo, um pedido de leitura e escrita deve usar raízes específicas verificadas, como "<raiz-de-leitura-aprovada>" e "<raiz-de-escrita-aprovada>"; não use um disco inteiro nem presuma caminhos do computador de outra pessoa. Em modo ask, confirme antes os limites no formulário; em auto, submeta a proposta validada e selecione subconjuntos estreitos dela para o teste.

Para revisão, diagnóstico ou segunda opinião, passe mode: "read-only". O bridge exige suporte a agy --mode plan, confere ao final que nenhum arquivo foi criado, modificado ou removido (inclusive arquivos novos ignorados pelo Git) e recusa integração dessas tarefas. Esse modo é uma restrição do CLI com verificação posterior, sem garantia de bloqueio físico de escrita. O padrão mode: "write" preserva o fluxo de implementação na cópia. Uma sessão retomada mantém seu modo original.

Fluxo típico:

1. Consulte antigravity_health para conferir CLI, perfil e modo de aprovação (approvalMode e integrationApproval). Use antigravity_list_models e antigravity_roles para selecionar IDs e papéis anunciados pelo servidor.

2. Liste os arquivos elegíveis com antigravity_list_project_files, selecione includePaths quando necessário e defina acceptanceCriteria cobrindo os requisitos antes de iniciar a implementação com antigravity_run. Guarde o taskId.

3. Acompanhe com antigravity_wait, preservando nextCursor e repetindo a espera quando ready for falso. timedOut encerra apenas a espera. Use antigravity_events para consultar os eventos detalhados.

4. Após o término, confira o status e os erros em antigravity_result com includeResult: false. Leia o resultado com antigravity_read_result e o patch com antigravity_preview (includePatch: false) e antigravity_read_patch. Se houver falha, confira a causa antes de retomar; completed não comprova os requisitos.

5. No Windows com o executor LPAC, consulte a política de sandbox e execute os testes pertinentes com antigravity_test, usando o hash da prévia e somente uma seleção já aprovada. Nos demais sistemas, ou com BRIDGE_TEST_EXECUTOR=agy, execute o teste sem seletor sandbox, pois a seleção explícita é recusada no caminho legado. A ferramenta devolve outro taskId: acompanhe e revise esse ID, confira a origem da evidência, exit codes e evidências desatualizadas e obtenha a prévia atual novamente. antigravity_record_test registra testes executados pelo cliente, como relatos; não substitui a evidência observada do executor.

6. Confira os arquivos reais contra cada critério e envie evidências de revisão a antigravity_verify com o hash atual. Com verificação aprovada e atual, confira também se os testes observados continuam válidos e chame antigravity_integrate na tarefa de implementação mais recente dessa cópia para aplicar segundo a política de autorização configurada. Alterações no patch, nas evidências ou nos arquivos afetados do original exigem nova conferência.

7. Informe o uso observado com antigravity_usage e, quando o trabalho puder ser removido, descarte a cópia com antigravity_discard.

Esse fluxo de implementação requer full ou implementation. Para planejamento, revisão ou comparação, use os papéis de leitura e os fluxos específicos acima. Uma revisão por handoff recebe outra cópia; ela não altera qual é a tarefa mais recente da cópia de implementação.

A aplicação final respeita o modo ativo configurado: em auto, antigravity_integrate aplica o patch verificado sem formulários; em ask, exige confirmação humana via formulário MCP (MCP form elicitation), mesmo para raízes lembradas ou configuradas legadas (o checkbox de memorização foi removido). antigravity_health informa approvalMode, integrationApproval.available e integrationApproval.mode. No modo ask, o formulário mostra origem, tarefa, hash, arquivos e contagens de linhas; só accept com confirm: true permite aplicar. Recusa, cancelamento, timeout ou falta de suporte preservam o original. O hash identifica o patch e a confirmação vem de uma resposta separada do cliente; nenhum argumento approved é aceito como autorização. Após a resposta, o bridge confere novamente hash e origem. A confirmação depende de um cliente confiável que apresente a decisão ao usuário.

Verificação dos resultados

Consumo de tokens

antigravity_status e antigravity_result incluem task.tokenUsage. antigravity_usage consolida as tarefas retidas e aceita filtros por taskId, sessionId e model. A resposta contém byTask, bySession, byModel e os contadores inputTokens, outputTokens, totalTokens, thinkingTokens e cacheReadTokens.

O resultado final do agy informa uso cumulativo da sessão. O bridge salva os contadores anteriores ao retomar e usa a diferença para a tarefa seguinte, inclusive quando o modelo muda. Assim, duas respostas cumulativas de 120 e 170 tokens representam 170 tokens na sessão e 50 na segunda tarefa. observedCumulative preserva o último total de sessão informado pelo CLI, separado do consumo das tarefas retidas.

Contadores ausentes, inválidos, reiniciados ou sem baseline conhecido ficam null; available, partial, source e warnings indicam a qualidade dos dados. Não há estimativa de tokens nem substituição silenciosa por zero. O consumo de tarefas falhas também é incluído quando o CLI devolve os contadores finais. Antes desse resultado, o total da tarefa pode estar indisponível. Tarefas antigas removidas pela retenção deixam de compor o consolidado local. Modelo null significa que não foi informado um ID; não se presume um modelo padrão.

Esses números são relatos do CLI, sem cálculo de cobrança ou acesso à quota global da conta. Cache e raciocínio são dimensões separadas e não devem ser somados novamente a totalTokens. A skill orienta o Codex a informar o consumo disponível ao concluir ou relatar falhas.

Papéis de trabalho

antigravity_run aceita os papéis nativos "implementer" (padrão), "planner" e "reviewer", além dos nomes personalizados anunciados por antigravity_roles. As bases de planejamento e revisão usam obrigatoriamente mode: "read-only" e agy --mode plan; selecionar escrita nesses papéis é recusado. A retomada mantém o papel e a definição originais.

Os papéis de consulta exigem suporte a agy --json-schema. O planejamento devolve summary, steps com arquivos e verificações observáveis, e unverified. A revisão devolve summary, reviewedFiles, findings e unverified; cada achado contém gravidade P0–P3, caminho, linha, citação literal, mensagem, impacto e sugestão.

O relatório validado aparece em task.report na resposta completa. Com resposta compacta, use antigravity_read_result para ler o structured_output original do CLI. Relatórios são identificados como agy-reported; na revisão, citationsChecked: true significa que arquivos e citações foram conferidos, sem atestar a interpretação ou provar ausência de defeitos. Formato inválido, arquivos inexistentes ou citações inventadas impedem a conclusão normal da tarefa. Uma resposta de planejamento não significa que suas etapas foram executadas.

Ler respostas grandes em partes

Use antigravity_preview com includePatch: false para obter arquivos, estatísticas, hash e patchLength sem enviar o diff inteiro. Depois chame antigravity_read_patch com expectedSha256 e, opcionalmente, um path devolvido na prévia. A seleção é feita pelo Git, incluindo arquivos binários e caminhos com espaços; não depende de interpretar cabeçalhos do patch. Qualquer alteração do patch completo invalida a leitura, mesmo quando você seleciona apenas um arquivo.

antigravity_result aceita includeResult: false para omitir o resultado bruto, o prompt, relatórios transferidos, instruções do papel e a lista completa de arquivos da cópia. Quando ready: true, consulte antigravity_read_result para ler o resultado serializado como JSON. Guarde contentSha256 e envie-o como expectedContentSha256 nas páginas seguintes para detectar mudanças.

Os leitores recebem offset (padrão 0) e limit (padrão 10.000, entre 2 e 50.000). Retornam text, nextOffset, hasMore, totalLength e contentSha256. Concatene text até hasMore: false; use sempre o nextOffset devolvido. Os offsets usam unidades UTF-16 e o leitor preserva caracteres representados por pares substitutos, como emojis. As opções antigas continuam devolvendo o conteúdo inteiro quando os campos de omissão não são usados.

Defina acceptanceCriteria antes de iniciar uma tarefa. Cada critério tem id, description e, opcionalmente, check com kind, path e text. As verificações disponíveis são file-exists, file-absent, file-contains e file-not-contains; as duas últimas exigem text. Critérios são preservados em retomadas e não podem ser substituídos depois da execução.

Após revisar o patch, chame antigravity_verify com o hash atual e reviews. Para cada critério, informe criterionId, verdict (passed, failed ou unverified), path, line, quote e explanation. O bridge lê os arquivos da cópia, executa as verificações e confere se a citação corresponde exatamente à linha indicada. Uma alegação do Gemini, um resultado SUCCESS ou um registro de teste do cliente não substitui essas evidências.

A integração exige todos os critérios aprovados e uma revisão atual. Critérios ausentes ou pendentes geram VERIFICATION_REQUIRED. Alterações no patch ou nos arquivos usados como evidência invalidam a verificação, inclusive alterações em arquivos ignorados que não aparecem no diff. O servidor verifica novamente após a confirmação humana. A prévia inclui verification e stale.

As verificações automáticas demonstram apenas as condições declaradas; a correção funcional mais ampla depende dos testes pertinentes e da revisão do Codex. O parecer permanece identificado como client-reported: conferir uma citação não demonstra que sua interpretação está correta. Esse fluxo aplica a distinção entre alegação e estado final e combina verificações determinísticas com revisão, conforme a orientação sobre avaliações de agentes.

Eventos, sessões e cancelamento

O bridge exige suporte aos formatos stream-json e a --sandbox, conferidos na descoberta do CLI. A versão verificada neste projeto é agy 1.3.2. Eventos estruturados chegam como NDJSON; diagnósticos de stderr permanecem separados. Linhas inválidas são expostas como stream.unparsed. O EventStore mantém um buffer limitado: truncated: true indica perda de eventos antigos. Registros de tarefas, sessões, eventos disponíveis, preferência de modelo e referências às cópias são persistidos por escrita atômica em ~/.antigravity-mcp-bridge (ou BRIDGE_STATE_DIRECTORY). O estado contém prompts e resultados: mantenha esse diretório privado, fora dos projetos versionados e de pastas compartilhadas.

Locks do estado privado conferem a identidade do arquivo e um token de posse antes da liberação. A recuperação de um proprietário confirmado como encerrado é serializada entre processos. Locks incompletos, arquivos substituídos e uma recuperação interrompida permanecem protegidos para inspeção local, com STATE_BUSY; a liberação repetida de um lock já encerrado é idempotente. O StateStore não possui suporte genérico a armazenamento em nuvem. Em ambientes sincronizados como OneDrive, a tolerância a variações na contagem de links (nlink) aplica-se exclusivamente à leitura de assets com descritor confiável, tamanho e SHA-256 fixados, ao staging da fonte do Node portátil com expectedSha256, e ao lock de preparação do Node portátil (preservando device, inode, tamanho e nonce/payload exato, com unlink apenas da entrada do próprio processo para preservar aliases). Hash, tamanho, identidade, marcas de reparse e layout continuam estritamente obrigatórios; conteúdo alterado é recusado e aliases não são modificados. Destinos de runtime, executáveis genéricos e concessões de ACL continuam exigindo link único.

Modelo padrão

Defina BRIDGE_DEFAULT_MODEL com um ID devolvido por agy models para o padrão inicial. antigravity_set_model grava a preferência no estado privado, compartilhada por servidores que usam o mesmo diretório. A prioridade é: model da tarefa, preferência salva, variável de ambiente e padrão do agy. A seleção é conferida contra a lista atual antes de executar; IDs indisponíveis causam MODEL_NOT_AVAILABLE.

Passe model: null para Auto: por tarefa, ignora os padrões do bridge; em antigravity_set_model, persiste o padrão do agy mesmo quando a variável está configurada. Omitir model preserva a preferência vigente. Para voltar ao padrão inicial do ambiente, pare o servidor e remova somente model-selection.json do diretório privado de estado.

antigravity_resume usa o conversation_id de uma tarefa concluída, inclusive após reinício, e reutiliza sua cópia isolada. Use antigravity_tasks para recuperar IDs e antigravity_sessions para consultar sessões persistidas. Execuções interrompidas não são repetidas automaticamente: recebem SERVER_RESTARTED quando o processo anterior já terminou. Se o PID registrado ainda estiver vivo, a cópia fica bloqueada com ORPHAN_PROCESS_RUNNING; o bridge não encerra processos recuperados apenas por PID. Tarefas de outro servidor ativo podem ser acompanhadas, mas devem ser canceladas no servidor que as iniciou. Locks locais impedem uso simultâneo da mesma cópia. O cancelamento encerra o subprocesso local; alterações parciais na cópia podem permanecer e devem ser revisadas.

Em cancelamentos e timeouts, a primeira intenção registrada prevalece (TASK_CANCELLED ou TASK_TIMEOUT), acionando o encerramento do processo e descendentes, sem garantia perfeita para processos que escapem do grupo de processos ou de permissões do sistema operacional. Diagnósticos estruturados diferenciam falhas de execução e ciclo de vida: AGY_NOT_FOUND (executável ausente), AGY_PERMISSION_DENIED (acesso negado ao binário), AGY_PROBE_FAILED (falha na sondagem inicial), AGY_INCOMPATIBLE (falta de suporte a stream-json ou --sandbox), CLI_INPUT_FAILED (falhas de stdin, EPIPE ou EOF prematuro), AGY_IO_FAILED (erros de I/O em streams) e AGY_PROCESS_FAILED (saída anômala do processo). Mensagens de erro de ferramentas externas podem conter segredos desconhecidos; o bridge aplica redaction a formas e padrões conhecidos de erro e suas operações não adicionam valores de credenciais aos logs nem passam tokens como argumentos, sem prometer ausência absoluta.

Ao fim de cada execução do CLI, inclusive com sucesso, o bridge observa novamente os processos pertencentes à execução e registra processCleanup. No Windows, a árvore é reconstruída por PID pai e horário de criação a partir do instante do spawn, o que exclui PIDs reutilizados; cada processo é encerrado e sua ausência é confirmada em até 3 s. Em POSIX, o grupo de processos próprio é encerrado e sua ausência é confirmada. Quando a confirmação falha, processCleanup.verified fica false e retomadas, testes, integrações e mensagens dessa cópia são recusados com PROCESS_CLEANUP_UNVERIFIED até uma nova observação confirmar o encerramento. Limite: no Windows, descendentes cujo processo intermediário já terminou não podem ser associados pelo PID pai e não entram na verificação.

Cópia, revisão e integração

Antes de chamar agy, o bridge cria uma cópia temporária dos arquivos elegíveis e mantém um baseline Git separado da cópia. O CLI recebe a cópia como diretório de trabalho e a opção --sandbox. O projeto original só muda por antigravity_integrate, depois da revisão do patch. O bridge não faz commit, merge nem push.

Antes de copiar, o bridge executa um preflight preventivo de segredos APÓS as exclusões do Git e a seleção por includePaths, e ANTES da cópia dos arquivos. O preflight bloqueia .env, .env.local e outras variantes .env.* (exceto .env.example, .env.sample, .env.template e .env.dist, que ainda passam por inspeção de conteúdo), .envrc, chaves privadas, keystores, autenticação conhecida e padrões de credenciais com alta confiança por conteúdo. Certificados, chaves públicas e fixtures sintéticas para testes permanecem permitidos. O evento copy.ready informa blockedFiles contendo apenas path e reason (SECRET_FILE, SECRET_CONTENT, SECRET_EXCLUSION, UNSAFE_PATH), nunca expondo o conteúdo do arquivo. O preflight não garante detectar segredos arbitrários em código, formatos desconhecidos ou dados criptografados.

Quando o CLI anuncia --add-dir e --new-project, o bridge declara a cópia como workspace e cria um projeto CLI separado na primeira execução. A retomada preserva o projeto da conversa. Essas opções não equivalem a uma comprovação de todas as fronteiras do sandbox; permissões negadas continuam sendo respeitadas.

O resultado informa copyDirectory e includedFiles. Cópias temporárias permanecem para revisão por 7 dias após a última tarefa finalizada. O servidor limpa cópias expiradas na inicialização e a cada minuto; antigravity_cleanup permite antecipar a verificação. Use antigravity_discard para remover imediatamente uma cópia pelo MCP. Tarefas retomadas compartilham a mesma cópia; todas perdem acesso após descarte. Cópias em uso são preservadas. A expulsão do último registro pelo limite de retenção também remove sua cópia. isolateWorktree: true é aceito apenas por compatibilidade e usa o mesmo fluxo de cópia; false é recusado.

antigravity_preview preserva files, patch e sha256 e acrescenta summary (totais A/M/D, linhas e arquivos binários), fileSummaries (inserções/remoções por caminho) e tests. Binários usam null nas contagens de linhas. Registros de antigravity_record_test têm source: "client-reported": são relatos cujo comando o bridge não executou. Registros capturados por antigravity_test indicam o executor que os observou. Cada registro leva hash, data, exit code e saída limitada pela seleção do teste; o padrão é 4.000 caracteres. Resultados antigos recebem stale: true quando a evidência já não corresponde aos arquivos atuais. Falhas são preservadas e devem ser apresentadas na revisão.

A cópia aceita até 10.000 arquivos e 256 MiB por padrão (MAX_COPY_FILES e MAX_COPY_BYTES), limites estritamente respeitados durante o scan preliminar e durante a cópia. A seleção é medida antes da criação e os bytes efetivamente copiados são conferidos novamente para detectar crescimento da origem. Qualquer mudança de identidade, tamanho ou hash falha a operação com SOURCE_CHANGED ou CONTEXT_CHANGED, e a criação da cópia (fork) não omite silenciosamente arquivos de baseline que venham a virar credencial. includePaths pode reduzir a seleção. Mais de 100 arquivos alterados gera CHANGE_LIMIT_EXCEEDED ao finalizar, revisar ou integrar. O original permanece intacto; reduza a tarefa ou ajuste os limites explicitamente no ambiente do servidor.

Executar testes sem Docker

Chame antigravity_test com taskId, expectedSha256 e command: { executable, args }. A ferramenta inicia uma continuação na mesma cópia e devolve outro taskId. Acompanhe esse ID pelos eventos e pelo resultado; revise e integre a tarefa mais recente. retries vale 0 por padrão e aceita até 3 tentativas de correção adicionais, solicitadas explicitamente. timeoutSeconds vale 600 por padrão.

Se uma tentativa local do Windows falhar na infraestrutura, uma chamada explícita de antigravity_test pode criar outra tentativa após a recuperação nativa das leases. O registro anterior permanece falho. Essa repetição exige a prévia e o hash atuais e é recusada enquanto houver execução ativa ou recuperação inconclusiva. Ela não habilita testes de sessões do CLI canceladas, expiradas ou com falhas de modelo.

A limpeza confere o caminho e a identidade dos temporários próprios. Um temporário comprovadamente ausente não invalida os demais resultados de limpeza; substituições ou links detectados impedem sua remoção. As verificações de Job, perfil, aliases e permissões continuam obrigatórias.

No Windows, o bridge cria um processo AppContainer/LPAC por execução e executa o comando diretamente nessa fronteira. O perfil, o SID e as ACLs de acesso são exclusivos da execução; as concessões exatas são removidas ao final. A limpeza e a recuperação de uma execução interrompida são verificadas em processos novos. Uma queda de energia não remove essas ACLs instantaneamente: a recuperação seguinte precisa concluí-la, e uma falha de limpeza impede que o teste seja considerado verificado e bloqueia novo uso daquela concessão.

O executor Windows não instala Docker nem pede elevação UAC. Ele exige o compilador .NET Framework já existente no Windows para criar o controlador. Cada execução é isolada em um perfil novo; a cobertura atual inclui recuperação de processo e nova execução, mas não afirma uma reinicialização física do computador.

Para expor os diretórios próprios da execução, o controlador cria aliases temporários em dois níveis para a cópia, o runtime preparado e o scratch: um nome DOS e uma letra entre D: e Z: para cada diretório. São necessárias três letras livres. O controlador confere a identidade e o destino de cada mapeamento antes, durante e depois do comando e os remove na limpeza, inclusive ao recuperar uma execução interrompida. Esses nomes DOS ficam visíveis apenas no contexto de logon atual; a reserva por letra é coordenada por logon e letra. Eles não concedem acesso à raiz do volume, não criam um mount persistente e não pedem UAC.

Fora do Windows, ou com BRIDGE_TEST_EXECUTOR=agy, o bridge mantém o caminho legado: agy --sandbox e run_command, com recibo vinculado à chamada exata. Não há fallback para executar diretamente no host. Em todos os casos, um comando não zero produz TEST_FAILED, mudanças nos arquivos durante/depois do comando produzem TEST_CHANGED_PATCH, e a evidência precisa continuar atual para integração.

No Windows, a evidência tem source: "windows-executor" e sandbox: "windows-lpac"; fora dele, tem source: "agy-tool" e sandbox: "agy-native-requested". A evidência inclui seleção de sandbox, hash da política, saída limitada e fingerprints antes/depois. A execução local conhecida registra zero tokens de modelo. Se uma correção pelo agy for solicitada após uma falha, seus contadores continuam sendo somente os devolvidos pelo CLI; campos ausentes permanecem null.

Saída ou texto do modelo, inclusive uma afirmação de que o comando passou, não é recibo de teste. Use somente a evidência observada pelo executor escolhido, com seu exit code e os campos de sandbox correspondentes.

No Windows, o bridge preenche PATHEXT ausente no subprocesso com .COM;.EXE;.BAT;.CMD, para que o PowerShell encontre os executáveis instalados. Valores definidos pelo cliente, inclusive um valor vazio, são preservados. O SDK pode omitir essa variável no ambiente herdado, fazendo node parecer ausente mesmo quando o arquivo está instalado. A correção vale para as sondagens e para todas as tarefas, sem configuração por projeto.

No Windows, use um .exe nativo ou npm/npm.cmd. Para npm, o bridge valida o launcher instalado, seu pacote e npm-cli.js, e chama o node.exe preparado com os argumentos literais. Lotes .cmd/.bat arbitrários e outros interpretadores não são suportados pelo executor. O staging rejeita caminhos remotos, dispositivos, streams alternativos e NUL; só o runtime validado é copiado sob limites de tamanho. Destinos de runtime, executáveis genéricos e concessões de ACL (grants) continuam exigindo link único; arquivos preparados pelo usuário não podem usar links; o cmd.exe interno deriva de um caminho fixo do Windows.

Para testes Node/npm e comandos git diretos no Windows, o executor prepara automaticamente o Git for Windows descoberto no PATH quando instalado, resolvendo launchers de cmd e bin para o binário nativo em ucrt64/bin ou mingw64/bin quando há um layout conhecido. Executáveis nativos e instalações standalone são preservados; layouts conhecidos sem binário válido ou com links inseguros são recusados. Copiam-se somente binários PE, DLLs e helpers públicos para um runtime isolado em modo somente leitura com links únicos no destino; arquivos de origem podem conter hardlinks na instalação original, mas ela não recebe ACLs nem concessões. O PATH preserva exclusivamente os diretórios do runtime preparado e o System32 exato; GIT_EXEC_PATH aponta para o diretório no alias do runtime, a configuração global aponta para arquivo ausente no scratch e definem-se GIT_CONFIG_NOSYSTEM=1 e GIT_TERMINAL_PROMPT=0. Entradas injetadas de GIT_CONFIG_COUNT, GIT_CONFIG_KEY_*, GIT_CONFIG_VALUE_* e GIT_CONFIG_PARAMETERS são removidas, e o ambiente do comando estabelece a confiança protegida de safe.directory restrita exclusivamente à lista exata dos depósitos verificados presentes na cópia no início da execução: reset vazio (VALUE_0=''), raiz do alias da cópia verificada (VALUE_1) e raízes dos depósitos descendentes com diretório .git verificado dentro da cópia (VALUE_2..N), sem wildcard * e sem confiar fora da cópia. Novos depósitos criados após a admissão continuam sujeitos às checagens normais do Git. Não há herança de .gitconfig, credenciais ou chaves, nem download de Git. A ausência de Git é opcional e não impede testes Node/npm sem Git, enquanto comandos que necessitam de Git falham se ele estiver ausente. Os limites de cópia permanecem obrigatórios (arquivos do Git contam para o teto), sem concessões extras para a pasta de instalação e sem fallback ao host ou ampliação de rede.

Novos repositórios temporários criados no sandbox usam o formato reftable via GIT_DEFAULT_REF_FORMAT=reftable definido somente no ambiente isolado quando o Git está preparado. O Git instalado deve suportar esse formato; a configuração não converte repositórios existentes nem altera o Git no host. O backend tradicional files e versões do Git sem suporte a reftable possuem limitação no LPAC ao consultar diretórios pais privados (sem alegação de suporte universal). A configuração não afrouxa as proteções de sistema de arquivos: diretórios pais privados continuam com acesso negado, sem novas concessões, sem UAC e sem fallback ao host.

Quando o Git está preparado, o controlador consulta a permissão do dispositivo Null do Windows. Se a regra padrão de LPAC já permite leitura e escrita, essa consulta não altera a ACL nem solicita WRITE_DAC. Caso o acesso esteja ausente e o token atual permita WRITE_DAC, o controlador registra uma concessão temporária somente para o SID exclusivo da execução. A limpeza verifica que o Job está vazio antes de remover acessos; uma recuperação inconclusiva mantém o lease e bloqueia a execução. A falta de permissão produz um diagnóstico sem solicitar elevação.

Compatibilidade de subprocessos Node no Windows LPAC

No Node 24.14.1 com libuv 1.51, child_process.spawnSync com pipes padrão de stdin/stdout/stderr cria endpoints globais \\?\pipe\uv\.... O LPAC recusa o CreateNamedPipe global com erro 5, enquanto endpoints equivalentes LOCAL\... abrem. A captura de stdout/stderr do processo pai está corrigida; no Node 24.14.1 do sistema, esse caso com pipes padrão ainda expira com exit code 124.

Testes de filhos com stdio: "inherit" e do ciclo real do npm passaram, mas não demonstram compatibilidade geral de subprocessos porque não exercitam os pipes capturados por padrão. Não substitua os pipes por stdio herdado para apresentar essa falha como resolvida.

O PR 5181 do libuv corrige os nomes de pipe para AppContainer e a correção entrou no libuv 1.53. O runtime portátil Node 24.21.0 LPAC1 para Windows x64, com libuv base 1.52.1 e somente esse PR aplicado, já está publicado em Release imutável e disponível para preparação explícita. Esse build passou pela regressão LPAC de spawnSync com pipes padrão capturados (1 teste) e pelos testes de isolamento e ciclo de vida (22 testes, sem falhas nem skips). A validação se aplica a esse build fixado.

network: true concede somente as capacidades Windows internetClient e privateNetworkClientServer, que permitem tráfego de Internet e LAN privada bidirecional. Não há capacidades arbitrárias, exceção para localhost, alteração de firewall nem acesso de rede quando a seleção não o permite. childProcesses e maxOutputChars também ficam limitados pela política aprovada.

Para testar com a conta real em um projeto descartável, execute npm run build e node tests/native-integration.mjs. Esse teste usa a conta do agy e verifica a captura de uma execução real; a suíte padrão usa o CLI simulado e não consome quota.

Configuração e segurança

Entradas e diretórios são validados. Configurações de ambiente devem ser registradas de modo persistente no ambiente privado de inicialização do servidor (atribuições de exemplo no PowerShell como $env:VAR = ... afetam somente o shell atual); reinicie a conexão MCP após qualquer alteração. Tarefas delegadas usam spawn sem shell e exigem --sandbox; não passam --dangerously-skip-permissions. Testes Windows usam o executor LPAC do bridge por padrão. Não inclua credenciais ou documentos privados nos prompts. Mantenha arquivos sensíveis fora da cópia por regras de ignore e selecione apenas os caminhos necessários com includePaths. Consulte a documentação do sandbox e do modo headless.

Padrões de exclusão e exceção de segredos

Os padrões em BRIDGE_SECRET_EXCLUSIONS são definidos como um array JSON de strings com caminhos relativos à raiz do projeto. Já BRIDGE_SECRET_EXCEPTIONS adota formato de objeto JSON versionado estrito: {"version": 2, "namePatterns": ["fixtures/.env.local"]}. Ambos suportam curingas glob: * (segmento individual), ? (um caractere) e ** (múltiplos diretórios), sem permitir travessia de diretório (..), caracteres NUL ou caminhos absolutos. Nomes sem barra correspondem ao nome base (basename) em qualquer diretório; **/ e /**/ correspondem a zero ou mais diretórios intermediários. A comparação é insensível a maiúsculas e minúsculas (case-insensitive). Arrays legados não vazios são rejeitados com diagnóstico de migração (sem expor valores sensíveis); a omissão ou um array vazio [] normaliza para política vazia {"version": 2, "namePatterns": []}.

Prefira exceções restritas a arquivos revisados e sem credenciais reais (como o exemplo sintético BRIDGE_SECRET_EXCEPTIONS='{"version": 2, "namePatterns": ["fixtures/.env.local"]}'), evitando padrões glob amplos. Na versão 2, a exceção pula apenas a checagem de nome de arquivo de credencial conhecida (isKnownCredentialFile / SECRET_FILE); todo o conteúdo permitido continua sendo inspecionado pelo scanner de segredos (detectSecretContent / SECRET_CONTENT) e nunca é ignorado por exceções de nome.

A ordem de precedência e segurança é estrita:

1. Regras de ignore do Git e verificações de caminhos inseguros (UNSAFE_PATH) SEMPRE vencem e têm prioridade máxima sobre qualquer exceção.

2. Deny explícito (BRIDGE_SECRET_EXCLUSIONS gerando SECRET_EXCLUSION) sempre vence qualquer exceção (BRIDGE_SECRET_EXCEPTIONS).

3. Exceção explícita v2 (BRIDGE_SECRET_EXCEPTIONS) pula unicamente o bloqueio padrão de nome de credencial (SECRET_FILE), mantendo integralmente a varredura e bloqueio por conteúdo (SECRET_CONTENT).

O preflight preventivo não garante a detecção de segredos arbitrários embutidos em código-fonte, formatos proprietários ou desconhecidos, dados criptografados ou arquivos ofuscados.

Barreiras de segurança em prévias, contexto e artefatos

A prévia inspeciona nomes e padrões de credenciais conhecidos antes de formar uma cópia dos bytes verificados para staging no Git privado, restaurando o índice privado com read-tree HEAD ao final. A leitura de patches por arquivo (readProjectPatch) extrai a fatia correspondente diretamente do patch revisado e verificado (preview.patch), vinculando-se estritamente ao mesmo hash SHA-256 e dispensando novas leituras inseguras do índice compartilhado ou da árvore de trabalho. Arquivos gerados ou modificados que violem a política falham com BLOCKED_FILE_DETECTED; alterações detectadas durante a preparação invalidam a operação. Restaurar o índice não remove objetos que já existiam no banco do Git.

Snapshots, fingerprints e bifurcações aplicam os ignores da origem e da cópia e a política de segredos. Arquivos gerados bloqueados são omitidos; um arquivo do baseline que se torne bloqueado causa CONTEXT_CHANGED. Skills fornecidas e políticas de execução conservam verificações próprias de integridade.

A coleta e a leitura de artefatos reaplicam a política de nomes, conteúdo e exclusões. Violações de segredo falham com BLOCKED_ARTIFACT_PATH. A leitura verifica os bytes contra o SHA-256 da inspeção e da referência, mantendo somente a janela solicitada em memória. Referências anteriores não dispensam os controles de caminho e política. Essas verificações cobrem os formatos reconhecidos pelo scanner e não garantem detectar segredos arbitrários nem eliminar toda corrida possível do filesystem.

Ambiente do subprocesso do CLI (cliEnvironment)

O subprocesso do CLI utiliza um ambiente estritamente filtrado por cliEnvironment em vez de herdar o ambiente do host indiscriminadamente. O bridge não registra valores de variáveis de ambiente nem passa tokens como argumentos. A variável BRIDGE_ALLOWED_ENV_VARS aceita um array JSON de nomes exatos adicionais para inclusão (opt-in), por exemplo BRIDGE_ALLOWED_ENV_VARS='["MY_TOOL_SETTING"]'. Por padrão, nenhuma injeção ou variável arbitrária é permitida; a inclusão de variáveis é estritamente opt-in e não é o comportamento padrão. A correspondência respeita as regras de plataforma (case-insensitive no Windows e exata/case-sensitive no Unix/Linux/macOS), preservando a deduplicação e PATHEXT.

Por motivos de segurança, variáveis de injeção de runtime e preload de bibliotecas (NODE_OPTIONS, NODE_PATH e os namespaces LD_* e DYLD_*) são estritamente proibidas para opt-in em BRIDGE_ALLOWED_ENV_VARS e chamadas diretas a cliEnvironment, inclusive com variações de maiúsculas/minúsculas ou espaços em branco em qualquer plataforma. Tentativas de opt-in dessas variáveis falham com erro estruturado nomeando a variável rejeitada, sem jamais ecoar seu valor. Opt-ins de variáveis legítimas não injetáveis, certificados como NODE_EXTRA_CA_CERTS e todos os defaults de sistema, perfil, keyring nativo, proxies, certificados corporativos e autenticação oficial Google / ADC continuam preservados. Demais credenciais de provedores e APIs de terceiros (como AWS, GitHub/GH, OpenAI e Stripe) e agentes locais (SSH_AUTH_SOCK, GPG_AGENT_INFO) continuam omitidos por padrão.

As variáveis padrão permitidas são agrupadas exatamente conforme definido no cliEnvironment:

• Resolução de sistema e executáveis: PATH, PATHEXT, SystemRoot, SystemDrive, ComSpec, WINDIR, SHELL, TERM, COLORTERM.

• Diretórios de usuário e perfil: HOME, USERPROFILE, APPDATA, LOCALAPPDATA, HOMEDRIVE, HOMEPATH, USER, LOGNAME, USERNAME.

• Diretórios temporários: TEMP, TMP, TMPDIR.

• Localidade, idioma e fuso horário: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, TZ.

• Diretórios base XDG e autenticação de sessão / keyring nativo: XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_CACHE_HOME, XDG_RUNTIME_DIR, XDG_DATA_DIRS, XDG_CONFIG_DIRS, DBUS_SESSION_BUS_ADDRESS, GNOME_KEYRING_CONTROL, GNOME_KEYRING_PID, SECURITYSESSIONID.

• Contexto de sessão remota SSH (sem credenciais): SSH_CONNECTION, SSH_CLIENT, SSH_TTY.

• Configurações de rede e proxy: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY, http_proxy, https_proxy, all_proxy, no_proxy.

• Certificados SSL/TLS (corporativos e raízes customizadas): SSL_CERT_FILE, SSL_CERT_DIR, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS.

• Autenticação oficial Google / Gemini e endpoints customizados: GEMINI_API_KEY, GOOGLE_GEMINI_BASE_URL, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, GOOGLE_CLOUD_UNIVERSE_DOMAIN.

• Ambiente Windows, arquitetura e contexto de domínio: OS, PROCESSOR_ARCHITECTURE, PROCESSOR_ARCHITEW6432, NUMBER_OF_PROCESSORS, ProgramData, ProgramFiles, ProgramFiles(x86), CommonProgramFiles, CommonProgramFiles(x86), USERDOMAIN, USERDNSDOMAIN, COMPUTERNAME.

Erros comuns e diagnósticos estruturados incluem AGY_NOT_FOUND, AGY_PERMISSION_DENIED, AGY_PROBE_FAILED, AGY_INCOMPATIBLE, CLI_INPUT_FAILED, AGY_IO_FAILED, AGY_PROCESS_FAILED, TASK_CANCELLED, TASK_TIMEOUT, AGY_AUTH_REQUIRED, MODEL_NOT_AVAILABLE, INVALID_WORKING_DIRECTORY e QUEUE_FULL. Se houver AGY_AUTH_REQUIRED, faça login no agy interativo. Se as ferramentas não aparecerem no Codex, confirme a instalação com codex plugin list --json e abra uma conversa nova.

Testes

npm.cmd run typecheck
npm.cmd run lint
npm.cmd test
npm.cmd run build:plugin
npm.cmd run test:package

npm test usa um mock do agy e não consome quota. npm run test:package também consulta o status do runtime pelo pacote empacotado; em plataformas fora do Windows ele deve informar supported: false sem preparar nada. A integração real é opcional: npm run test:integration cria um repositório descartável, executa uma tarefa pelo cliente MCP, confere que o original permanece intacto até a integração e remove o repositório. Esse teste simula a resposta de confirmação somente para seu projeto descartável; a confirmação humana da interface deve ser usada nos projetos reais. Execute-a apenas com agy autenticado e quando quiser usar a conta real.

Licença e políticas

O projeto usa a licença MIT. Consulte a política de segurança, a política de privacidade, o histórico de versões e os avisos das dependências distribuídas. npm run build:plugin atualiza o bundle e os avisos a partir das dependências efetivamente incluídas.