git:20261022.0ffc108 to git:20261025.a376884

68 added, 52 removed. Audit A to A.

---

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.

## Before launch

- 1. **Read the live surface.** Run `agy --help` for flags and defaults and

- `agy models` for the current model set. The CLI changes faster than skill

- text. **Wrapper drift** is a run built from remembered syntax that silently

- changed: it looks scoped and is not.

+ 1. **Read the live surface.** The CLI changes faster than skill text; the facts

+ here are from 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 substitute needs a new caller selection. Nothing routes

- work to AGY on its own either. The repository reviewer library rates AGY a

- routine-tier, degraded-fallback reviewer; that rating applies only when a

- caller opts in, and it is not an automatic route.

+ 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 (AGY 1.2.14). 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. **Name the posture** (below) and confirm the packet's declared effects and

- the caller's authorization cover it.

- 5. **Keep author and validator apart.** A validator is a new run in a new

- conversation, never `-c`/`--continue` or `--conversation <author-id>`. A

- session that reviews its own work forfeits the fresh judgment that makes a

- validator's evidence usable. Validators stay read-only and hand judgment to

+ 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)

- Flags choose the posture. Name the one used:

+ 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: AGY prompts for each tool permission. A headless run has no

- one to answer, so a prompt can stall it until the bound.

- - `--dangerously-skip-permissions`: auto-approves every tool call. Use it only

- when the declared effects and the caller's authorization cover that blast

- radius.

- - `--sandbox`: restricts the session's terminal access.

- - `--mode` (`plan`, `accept-edits`): changes the execution mode; confirm its

- current meaning in `agy --help`.

+ - 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.

+ Take `git status --porcelain` in `$WORKSPACE` before and after; a validator's

+ write is out of authority.

## Command

- Every `agy` flag below appears in `agy --help` for AGY 1.3.1; recheck before use.

- `DEADLINE_EPOCH` is an absolute Unix time the caller fixes once and reuses for

- every run in its scope, so a second run gets what is left rather than a new

- bound. `POSTURE` is a Bash array of the posture flags chosen above, for example

- `POSTURE=(--sandbox)`; an empty array means AGY asks for each tool.

- `PROMPT_FILE` is an absolute path. The packet goes by path, not inline: a short

- `-p` pointer plus `--add-dir`, as `scripts/lib/codex-exec.sh` does, because a

- large inline prompt can be dropped while the run still looks scoped.

+ 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 and runs

+ `--sandbox --dangerously-skip-permissions`, a posture to disclose. An

+ installed skill lacks that library; use this block.

+ The packet goes 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.

```bash

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.

remaining=$(( DEADLINE_EPOCH - $(date +%s) ))

- [ "$remaining" -gt 0 ] || { echo "deadline passed; not launched" >&2; exit 124; }

+ 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

"$TO" -k 10 "$remaining" \

- agy --print-timeout "${remaining}s" --model "$MODEL" --output-format json \

- "${POSTURE[@]}" --add-dir "$(dirname "$PROMPT_FILE")" \

- -p "Read the task packet at $PROMPT_FILE and do what it describes." >"$OUT" 2>"$ERR"

- rc=$? # 124, or 137 after the 10 s grace: the outer bound stopped the run

+ 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=$?

```

- `--print-timeout` takes a duration with a unit, such as `300s`. Add flags before

- `-p` so none lands after the prompt text. AGY's help does not say which status

- it returns when its own print timeout fires, so a run that ends at the bound is

- a timeout unless its output shows a finished turn.

+ Put every flag before `-p`. `--print-timeout` needs a unit such as `300s`; a

+ bare number or an unknown flag exits 2. If the host shell tool's cap is under

+ `remaining` plus 10 s, handle it as [claude-exec](../claude-exec/SKILL.md#run) does.

+ **Did it finish?** Exit 0 is not proof: an expired `--print-timeout` returns

+ partial output, exits 0 and warns on stderr, so that run timed out. Exit 3

+ with an `AGY_ERROR:` line is a model or agent error; other non-zero is a

+ failed run; 124, or 137 after the grace, is the outer bound. Output repeating

+ the packet or pointer is an echo. No JSON field is documented for a finished

+ turn: judge by the expected artifact and the `git status` diff, else say

+ unknown. An `$OUT` of exactly 10 MiB was cut; its status is the closed pipe.

## Return

```text

- command: exact argv (prompt by reference)

- posture: permission, sandbox and mode flags used

- model: requested model; observed model if AGY reported one, else unknown

- conversation: id AGY reported, else unknown

- bound: --print-timeout value and the outer deadline

- outcome: exit status | timed out | not run (reason)

- artifacts: captured output and changed-file paths

+ command: exact argv (prompt by reference)

+ posture: flags used; settings permissions, or "settings not inspected"

+ model: requested id; observed model if AGY reported one, else unknown

+ conversation: id AGY reported, else unknown

+ bound: --print-timeout value and the outer deadline

+ outcome: exit status; finished | timed out (which bound) | echo | unknown | not run

+ denied_actions: list from the JSON output, else none reported

+ artifacts: output path, bytes, truncated yes|no; changed-file paths

```

- AGY plugin, memory, permission, retry and session state are runtime facts; they

- never become AgentOps phase, queue or completion state. Installation, plugin

- mutation and recurring scheduling need separate explicit authorization.

+ Installation, plugin mutation and recurring scheduling need separate explicit

+ authorization.