Gemini Cli Runtime

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

# Gemini Companion Runtime Contract

## Invocation

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/gemini-companion.mjs" task [flags] -- <prompt>
```

Everything after `--` (or the first non-flag positional) is the task text sent to Gemini.

## Flags

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--write` | boolean | false | Enable Gemini to make file changes (sets `--approval-mode auto_edit`) |
| `--model <name>` | string | `auto-gemini-3` | Model override — see model reference below |
| `--thinking-budget <n>` | integer | (unset) | Thinking token budget for the model |
| `--approval-mode <mode>` | string | `default` | One of: `default`, `auto_edit`, `yolo`, `plan` |
| `--resume-last` | boolean | false | Resume the most recent task thread in this repository |
| `--background` | boolean | false | Run as a detached background job |
| `--wait` | boolean | true | Run in the foreground (default) |
| `--cwd <path>` | string | `$CLAUDE_PROJECT_DIR` | Working directory override |
| `--json` | boolean | false | Emit structured JSON instead of rendered markdown |

## Model Reference

The default model is **`auto-gemini-3`**, which routes to the best available Gemini 3.x model.

### Auto-routing aliases (recommended)

| Alias | Routes to |
|-------|-----------|
| `auto-gemini-3` | Gemini 3.1 or 3 (best available) — **default** |
| `auto-gemini-2.5` | Gemini 2.5 (stable, production) |
| `pro` | `gemini-3.1-pro-preview` (highest capability) |
| `flash` | `gemini-3-flash-preview` (speed-optimised) |
| `flash-lite` | `gemini-3.1-flash-lite-preview` (fastest) |

### Concrete model IDs (pin to specific preview)

| Model ID | Generation |
|----------|-----------|
| `gemini-3.1-pro-preview` | Gemini 3.1 |
| `gemini-3.1-flash-lite-preview` | Gemini 3.1 |
| `gemini-3-pro-preview` | Gemini 3 |
| `gemini-3-flash-preview` | Gemini 3 |
| `gemini-2.5-pro` | Gemini 2.5 |
| `gemini-2.5-flash` | Gemini 2.5 |
| `gemini-2.5-flash-lite` | Gemini 2.5 |

Unlisted model IDs are forwarded as-is to Gemini CLI.

## Safety Rules

- Exactly one Bash call per rescue invocation.
- Never chain additional tool calls after the companion returns.
- Never inspect, modify, or second-guess Gemini's output.
- If the companion exits non-zero, return nothing — do not fabricate a response.
- Do not include `--thinking-budget`, `--model`, `--resume-last`, `--background`, or `--wait` in the task text itself. They are runtime controls.

## Output

- `stdout`: Rendered markdown (default) or JSON (`--json`).
- `stderr`: Progress updates during execution.
- Exit code 0 = success, non-zero = failure.

## Job Health Labels

`/gemini:status` reports a conservative `Health` label for each active job.
Interpret each label as follows when deciding what to do next:

| Label | Interpretation | Recommend to the user |
|-------|----------------|-----------------------|
| `active` | Gemini emitted progress recently. | Wait for completion; do not cancel. |
| `quiet` | Heartbeat is recent but no new progress. | Re-check `/gemini:status` shortly. |
| `possibly_stalled` | No recent heartbeat or progress. | Re-check `/gemini:status`, fetch `/gemini:result`, or retry if the job does not recover. |
| `rate_limited` | Explicit quota or 429-class diagnostic. | Wait, switch models (`--model flash` / `--model auto-gemini-2.5`), or cancel with `/gemini:cancel`. |
| `auth_required` | Explicit auth/credential diagnostic. | Point the user to `/gemini:setup` to re-authenticate before retrying. |
| `broker_unhealthy` | The ACP broker reported busy/disconnected. | Re-check status shortly; a restart may be needed if it persists. |
| `worker_missing` | Worker PID is no longer alive. | Fetch `/gemini:result`; retry if the output is incomplete. |
| `failed` | Worker or Gemini ended with an error. | Fetch `/gemini:result` for the diagnostic and retry only after understanding it. |
| `completed` | Gemini finished successfully. | Fetch `/gemini:result` and present output; do not retry. |
| `cancelled` | Job was cancelled by user or system. | Fetch `/gemini:result` for final diagnostics; consider retrying if needed. |

Never claim a job is dead or useless based on `quiet` or `possibly_stalled`
alone. Those labels mean "check again", not "give up".