/agy-native

name: agy-native
description: 'Run a supplied task in headless AGY (Antigravity, Gemini) and collect its result. Use when: AGY, Antigravity or Gemini is requested by name; never a fallback.'
practices: [team-topologies, design-by-contract]
hexagonal_role: driving-adapter
consumes: [explicit-packet]
produces: [agy-run-evidence]
context_rel:
- kind: separate-ways
  with: codex-exec
skill_api_version: 1
user-invocable: true
metadata:
  tier: cross-vendor
  dependencies: []
  capabilities: [dispatch_explicit_packet, provide_fresh_context]
  effects: [start_agy_session]
  canonical_status: canonical
  disposition: keep_optional_adapter
output_contract: AGY runtime evidence

AGY Native

Run a supplied packet in AGY (Antigravity) only when the caller explicitly selects that runtime. Scope the run to the supplied workspace and packet, return runtime evidence, and stop. It worked when the command passes an explicit `--print-timeout`, the posture is disclosed, and the result says whether the turn finished instead of reading exit 0 as proof.

Before launch

1. **Read the live surface.** The CLI changes faster than skill text. Re-checked on 2026-10-25 against AGY 1.4.7. Run `agy --help` for flags, `agy changelog` for behavior the help omits, and `agy models` for ids. That list includes Claude and GPT-OSS: a Gemini or cross-family run needs a `gemini-*` id. 2. **Absent means stop.** If `agy` is missing or its help cannot be read, report the absence and stop. Never fall back silently to Codex, Claude or any other runtime. A fallback the caller named, in advance or after that report, runs only after it, through [claude-exec](../claude-exec/SKILL.md) or [codex-exec](../codex-exec/SKILL.md) with its own bound, labelled "not an AGY result". Nothing routes work to AGY on its own either. 3. **Set an explicit bound.** Print mode (`agy -p` / `--print`) is the headless path, and it has no built-in limit: `--print-timeout` defaults to `0`, which waits until the turn completes. Pass `--print-timeout` from the caller's remaining deadline and hold the same bound outside the process. A run stopped at the bound is a timeout, not a result. 4. **Keep author and validator apart.** A validator is a new run in a new conversation, never `-c`/`--continue` or `--conversation <author-id>`, so its judgment stays fresh. Validators stay read-only and hand judgment to Validate; they never write the core verdict.

Permission posture (disclose it; never assume it)

Name the posture before launch: the flags plus the user and project `settings.json` permissions, which headless runs honor (disclose those or say not inspected). No flag makes file access read-only.

• No posture flag: workspace reads are granted; other actions needing approval

are denied and listed in the JSON `denied_actions`. With settings that allow no writes, this is the validator posture.

• `--sandbox` restricts terminal commands only. `--mode accept-edits` approves

edits and `--mode auto` edits and safe commands; `--mode plan` is not documented as read-only, and headless runs pass plan review on their own.

• `--dangerously-skip-permissions` approves every tool call. It and the

approving modes need declared effects and caller authorization covering that blast radius.

Before and after the run, take `git status --porcelain` and `git diff HEAD | shasum` in `$WORKSPACE`, and list the packet directory `$PKT` after; a validator's write is out of authority. These miss edits inside untracked or ignored files and under other `--add-dir` paths: report those unchecked.

Command

In an AgentOps source checkout, review runs use `REVIEWER=agy` (the id in `REVIEWER_MODEL`) with `codex_exec_guarded` from `scripts/lib/codex-exec.sh` (call shape in [codex-exec](../codex-exec/SKILL.md#run-it)). It adds echo, stall and output-cap handling. Its posture, to disclose, is `--sandbox --dangerously-skip-permissions` with `--add-dir` on its own private `mktemp -d` packet directory: every tool call is approved over the workspace and that directory, so it is not read-only. An installed skill lacks that library; use this block. The caller supplies `$MODEL`, `$POSTURE`, `DEADLINE_EPOCH` and absolute `$WORKSPACE`, `$PROMPT_FILE`, `$OUT` and `$ERR` paths, the last three outside `$WORKSPACE`. This block passes the packet by path, not inline: a short `-p` pointer plus `--add-dir` on the packet's own directory only, because a large inline prompt can be dropped while the run still looks scoped. That drop is an earlier-run observation, not in the 1.4.7 help or changelog. Would verify: a run with an inline `-p` prompt over ~100 KB that asks for a marker from its end.

TO=$(command -v timeout || command -v gtimeout) || { echo "no timeout: not launching" >&2; exit 2; }
[ -n "$MODEL" ] || { echo "MODEL unset: pick an id from agy models" >&2; exit 2; }
# DEADLINE_EPOCH: absolute Unix time fixed once by the caller; a later run gets what is left.
case "$DEADLINE_EPOCH" in ''|*[!0-9]*) echo "no deadline: not launching" >&2; exit 2;; esac
for p in "$WORKSPACE" "$PROMPT_FILE" "$OUT" "$ERR"; do case "$p" in /*) ;; *) echo "not absolute: '$p'" >&2; exit 2;; esac; done
remaining=$(( DEADLINE_EPOCH - $(date +%s) ))
pt=$(( remaining - 15 ))  # AGY's bound fires first; 0 would mean no limit
[ "$pt" -gt 0 ] || { echo "deadline too close; not launched" >&2; exit 124; }
PKT=$(mktemp -d) && cp "$PROMPT_FILE" "$PKT/packet.md" || exit 2  # not $TMPDIR itself
cd "$WORKSPACE" || exit 2
# POSTURE: Bash array of the flags chosen above; empty is the default posture.
set -o pipefail  # bash and zsh: $? is the failing stage, not head's
start=$(date +%s)
"$TO" -k 10 "$remaining" \
  agy --print-timeout "${pt}s" --model "$MODEL" --output-format json \
  "${POSTURE[@]}" --add-dir "$PKT" \
  -p "Read the task packet at $PKT/packet.md and do what it describes." \
  </dev/null 2>"$ERR" | head -c 10485760 >"$OUT"
rc=$?; elapsed=$(( $(date +%s) - star