agy-auto — Antigravity Auto-Permission & Security Gate

Overview

agy-auto is a PreToolUse hook and security harness for Google Antigravity CLI (agy) that enables safe unattended execution without relying on --dangerously-skip-permissions. It passes every pending tool call through a multi-layered policy gate: deterministic hard-deny rules, deterministic fast-allow for workspace-scoped and read-only operations, an LLM classifier fallback (Gemini Flash Lite or local llama.cpp), and single-use scoped token approvals with Zero Ambient Authority.

When to Use This Skill

• Use when running Antigravity CLI (agy) unattended or in background agent loops and you want automated tool permissions without exposing system files or credentials.
• Use when you need granular, auditable controls over shell commands, file modifications, and network egress during agy workflows.
• Use when setting up a secure pair-programming environment with Antigravity that prevents prompt injection attacks from escaping the workspace.

How It Works

Step 1: Review, Pin, and Install agy-auto

[!IMPORTANT] Because agy-auto installs as an active PreToolUse hook on the permission evaluation path, never clone a mutable branch directly into your live plugin directory. Always clone to a temporary staging folder, pin an immutable release tag or commit SHA, and inspect the codebase before making the hook executable.

Option A: Native Antigravity Plugin (Recommended)

# 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 v0.2.0-alpha

# 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
mkdir -p ~/.gemini/config/plugins/agy-auto
cp -r . ~/.gemini/config/plugins/agy-auto/
chmod +x ~/.gemini/config/plugins/agy-auto/hook.sh

Ensure toolPermission: "always-proceed" is configured in ~/.gemini/antigravity-cli/settings.json so hooks can gate tool calls:

{
  "toolPermission": "always-proceed"
}

Option B: Global Hook via Installer

# 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 v0.2.0-alpha

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

Step 2: Policy Evaluation Layers

agy-auto evaluates each tool invocation through sequential layers (first match wins):

1. Hard Deny: Immediately blocks recursive deletes outside workspace, credential reads (~/.ssh, .env, cloud tokens), git history rewrites (push --force, rebase), package publishing, system file writes (/etc, shell rc), and gate tampering.
2. Fast Allow: Immediately permits parsed read-only commands (cat, grep, git status) and workspace-confined writes without invoking an LLM.
3. Classifier: Ambiguous or grey-area commands fall through to an LLM classifier (Google Gemini 3.5 Flash Lite free tier, or a local llama.cpp / Ollama endpoint) that reviews the pending call against conversation context and fail-closes on timeout.
4. Scoped Action Approval: If a command is denied or needs human judgment, the engine issues a single-use 6-character action token bound strictly to (tool, normalized_cmd, cwd). You approve it by replying > agy-approve <token> in chat. Conversational phrases like "yes" or "proceed" are ignored to prevent ambient authority leakage.

Examples

Example 1: Approving a Blocked Command

When an unclassified command is blocked, agy-auto outputs a token:

tool call denied by pre-tool hook: [agy-auto/classifier] needs human approval: pip install requests. Reply '> agy-approve a1b2c3' in chat to proceed.

To authorize this specific command for a single run, reply directly in the chat:

> agy-approve a1b2c3

Example 2: Configuring a Local Model Backend

To run agy-auto completely offline using llama.cpp or Ollama instead of cloud APIs, edit ~/.gemini/config/agy-auto/policy.toml:

[classifier]
endpoint = "http://127.0.0.1:8080/v1/chat/completions"
model = "qwen2.5-coder:7b"
timeout_s = 20

Example 3: Running Headless Invocations

When invoking agy in headless mode (-p), always pass --add-dir so agy-auto recognizes the workspace boundaries:

agy --add-dir . -p "Run test suite and fix failing cases"

Best Practices

• ✅ Always keep toolPermission: "always-proceed" enabled so the pre-tool hook can intercept and gate every tool call.
• ✅ Add custom repetitive dev tools (e.g. specialized compilers, formatters) to [fast_allow] in ~/.gemini/config/agy-auto/policy.toml for instant sub-millisecond execution.
• ✅ Pass --add-dir <path> when running headless commands (agy -p) to prevent false-positive path denials.
• ❌ Do not use --dangerously-skip-permissions; agy-auto provides safe autonomous execution without removing safety guardrails.
• ❌ Do not attempt conversational approval words ("approve", "proceed", "yes"); approvals strictly require the ephemeral action token.

Common Pitfalls

• Problem: Commands fail with path is outside the workspace when running agy -p. Solution: Headless agy does not infer workspace roots automatically. Pass --add-dir . (e.g. agy --add-dir . -p "...").
• Problem: Classifier fails closed with policy classifier unavailable (The read operation timed out). Solution: Increase timeout_s in ~/.gemini/config/agy-auto/policy.toml (especially when running local LLMs on integrated graphics), or verify your GEMINI_API_KEY.
• Problem: Changes to policy.toml or hook.sh are blocked by [agy-auto/hard_deny]. Solution: agy-auto enforces self-protection against agents tampering with the security gate. Edit policy files directly from your own shell.

Limitations

• agy-auto only intercepts actions performed via tool calls (e.g. run_command, write_to_file); it cannot restrict internal LLM network reasoning or Antigravity's own internal context-gathering file reads.
• Requires toolPermission: "always-proceed" in Antigravity settings to ensure the PreToolUse hook intercepts all tool invocations.
• Shell parsing is conservative: complex pipelines with computed variable expansions that cannot be statically resolved will fall through to the LLM classifier or require manual token approval.

Additional Resources

• agy-auto GitHub Repository
• Antigravity CLI Documentation