---
name: antigravity-cli-runtime
description: Internal helper contract for calling the agy-companion runtime from Claude Code
user-invocable: false
---

# Antigravity Runtime

Use this skill only inside the `antigravity:antigravity-rescue` subagent.

Primary helper:
- `node "${CLAUDE_PLUGIN_ROOT}/scripts/agy-companion.mjs" task "<raw arguments>"`

Execution rules:
- The rescue subagent is a forwarder, not an orchestrator. Its only job is to invoke `task` once and return that stdout unchanged.
- Prefer the helper over hand-rolled `agy` strings, direct CLI calls, or any other Bash activity.
- Do not call `setup`, `status`, `result`, or `cancel` from `antigravity:antigravity-rescue`.
- Use `task` for every rescue request, including diagnosis, planning, research, and explicit fix requests.
- You may use the `gemini-prompting` skill to rewrite the user's request into a tighter Antigravity prompt before the single `task` call.
- That prompt drafting is the only Claude-side work allowed. Do not inspect the repo, solve the task yourself, or add independent analysis outside the forwarded prompt text.

Command selection:
- Use exactly one `task` invocation per rescue handoff.
- If the forwarded request includes `--background`, forward it as `--background` to the helper.
- If the forwarded request includes `--wait`, treat that as a hint to NOT use `--background` (foreground). Strip `--wait` from the task text.
- If the forwarded request includes `--resume`, strip that token from the task text and add `--resume` to the helper invocation. This becomes `--continue` for the agy CLI.
- If the forwarded request includes `--fresh`, strip that token and do not add `--resume`.
- If the forwarded request includes `--sandbox`, pass `--sandbox` through to the helper (it enables agy's sandbox mode with terminal restrictions).
- If the forwarded request includes `--add-dir <path>`, pass `--add-dir <path>` through to the helper (it adds a workspace directory).
- If the forwarded request includes `--timeout <value>`, pass it through (format: `10m` or `300s`). Default foreground timeout is 10 minutes; background is 30 minutes.

Bash invocation pattern:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/agy-companion.mjs" task [--background] [--resume] [--sandbox] [--add-dir <p>] [--timeout 10m] "<the user task text>"
```

Safety rules:
- Always quote the prompt text to preserve spaces and special characters.
- Preserve the user's task text as-is apart from stripping routing flags.
- Do not inspect the repository, read files, grep, monitor progress, poll status, fetch results, cancel jobs, summarize output, or do any follow-up work of your own.
- Return the stdout of the `task` command exactly as-is.
- If the Bash call fails or Antigravity cannot be invoked, return nothing.

Headless authorization:
- Under the hood, the helper invokes `agy --print --dangerously-skip-permissions --print-timeout <T>`.
- `--dangerously-skip-permissions` auto-approves all tool permission requests (necessary for headless work).
- `--print` runs a single prompt non-interactively and prints the response.
- This is the safe, documented headless mode of agy (per `agy --help`).