agy-auto — Antigravity Auto-Permission & Security Gate

Visão Geral

agy-auto é um hook PreToolUse e um sistema de segurança para o Google Antigravity CLI (agy) que suporta uma política de execução não supervisionada revisada sem depender de --dangerously-skip-permissions. Ele passa todas as chamadas de ferramenta pendentes por um portão de política de várias camadas: regras de negação determinísticas, permissão rápida determinística para operações com escopo de workspace e somente leitura, um classificador LLM como fallback (Gemini Flash Lite ou llama.cpp local) e aprovações de token com escopo de uso único e Autoridade Ambiente Zero.

Quando Usar Esta Skill

• Use ao executar o Antigravity CLI (agy) sem supervisão ou em loops de agente em segundo plano e você deseja permissões automatizadas de ferramentas sem expor arquivos de sistema ou credenciais.
• Use quando precisar de controles granulares e auditáveis sobre comandos de shell, modificações de arquivos e saída de rede durante fluxos de trabalho agy.
• Use ao configurar um ambiente seguro de programação em par com o Antigravity que reduz a exposição de chamadas de ferramentas dentro de um limite de workspace verificado.

Como Funciona

Passo 1: Revisar, Fixar e Instalar agy-auto

[!IMPORTANT] Como agy-auto é instalado como um hook PreToolUse ativo no caminho de avaliação de permissão, nunca clone um branch mutável diretamente em seu diretório de plugin ativo. Sempre clone para uma pasta de staging temporária, fixe uma tag de release imutável ou SHA de commit e inspecione o código-fonte antes de tornar o hook executável.

Opção A: Plugin Antigravity Nativo (Recomendado)

# 1. Clone into a temporary review directory and checkout an immutable release tag
git clone https://github.com/onkarbadve/agy-auto.git /tmp/agy-auto-review
cd /tmp/agy-auto-review
git checkout <verified-full-commit-sha>

# 2. Inspect hook.sh and engine/ files before deployment
less hook.sh
python3 -m unittest -v tests/test_engine.py

# 3. Once reviewed and verified, copy to the Antigravity plugin directory and set permissions
# Host activation requires explicit user approval, an existing-config backup,
# and a reviewed non-overwriting installation into the confirmed host path.

Somente se a combinação exata de CLI/hook for verificada como falha segura em hooks ausentes, falhos e adulterados, e o usuário aprovar explicitamente essa alteração de permissão do host, configure toolPermission: "always-proceed" em ~/.gemini/antigravity-cli/settings.json para que os hooks possam controlar as chamadas de ferramentas:

{
  "toolPermission": "always-proceed"
}

Opção B: Hook Global via Instalador

# 1. Clone to an isolated location and pin release
git clone https://github.com/onkarbadve/agy-auto.git ~/.local/share/agy-auto
cd ~/.local/share/agy-auto
git checkout <verified-full-commit-sha>

# 2. Review and run the installer
chmod +x hook.sh
./install.sh                  # registers hook in hooks.json, sets always-proceed, runs smoke tests

Passo 2: Camadas de Avaliação de Política

agy-auto avalia cada invocação de ferramenta através de camadas sequenciais (primeira correspondência vence):

1. Negação Rígida: Bloqueia imediatamente exclusões recursivas fora do workspace, leituras de credenciais (~/.ssh, .env, tokens de nuvem), reescritas de histórico git (push --force, rebase), publicação de pacotes, gravações de arquivos de sistema (/etc, shell rc) e adulteração do gate.
2. Permissão Rápida: Permite imediatamente comandos somente leitura analisados (cat, grep, git status) e gravações confinadas ao workspace sem invocar um LLM.
3. Classificador: Comandos ambíguos ou de área cinzenta caem para um classificador LLM (um modelo provedor configurado atualmente disponível (verifique preços e transmissão de contexto privado), ou um endpoint local llama.cpp / Ollama) que revisa a chamada pendente contra o contexto da conversa e falha de forma segura em caso de timeout.
4. Aprovação de Ação com Escopo: Se um comando for negado ou precisar de julgamento humano, o motor emite um token de ação de uso único de 6 caracteres vinculado estritamente a (tool, normalized_cmd, cwd). Você o aprova respondendo > agy-approve <token> no chat. Frases conversacionais como "sim" ou "prosseguir" são ignoradas para evitar vazamento de autoridade ambiente.

Antes da ativação, teste operações permitidas e negadas em fixtures descartáveis, incluindo escapadas de symlink/caminho, expansões de shell, requisições de rede, hook ausente, timeout do classificador e repetição de token. Uma passagem de teste unitário não é prova de que todo o acesso ao host é interceptado. Preserve um caminho de desativação/rollback verificado. Nenhum classificador de modelo é autoridade de merge ou política.

Exemplos

Exemplo 1: Aprovando um Comando Bloqueado

…