# second-opinion

Runs external LLM code reviews (OpenAI Codex or Google Antigravity CLI) on uncommitted changes, branch diffs, or specific commits. Use when the user asks for a second opinion, external review, codex review, gemini review, antigravity review, or mentions /second-opinion.

- **Kind:** skill
- **Source:** https://github.com/trailofbits/skills
- **Page:** https://forefy.com/skills/811e1d74-2164-4b20-9b43-5f3f3ec9807d
- **API (JSON + files):** https://forefy.com/api/asr/811e1d74-2164-4b20-9b43-5f3f3ec9807d

---

## SKILL.md

---
name: second-opinion
description: "Runs external LLM code reviews (OpenAI Codex or Google Antigravity CLI) on uncommitted changes, branch diffs, or specific commits. Use when the user asks for a second opinion, external review, codex review, gemini review, antigravity review, or mentions /second-opinion."
allowed-tools: Bash Read Glob Grep AskUserQuestion
---

# Second Opinion

Shell out to external LLM CLIs for an independent code review powered by
a separate model. Supports OpenAI Codex CLI (`codex`) and Google
Antigravity CLI (`agy`).

## When to Use

- Getting a second opinion on code changes from a different model
- Reviewing branch diffs before opening a PR
- Checking uncommitted work for issues before committing
- Running a focused review (security, performance, error handling)
- Comparing review output from multiple models

## When NOT to Use

- Neither Codex CLI nor Antigravity CLI is installed
- No API key or subscription configured for either tool
- Reviewing non-code files (documentation, config)
- You want Claude's own review (just ask Claude directly)

## Gemini CLI Is End-of-Life

As of 2026-06-18, `gemini` (Gemini CLI) stopped serving Google AI Pro,
Ultra, and free-tier individual accounts. Those accounts now get
`UNSUPPORTED_CLIENT` on every request, pointing at
<https://antigravity.google>. The replacement is **Antigravity CLI**,
binary `agy`.

Default to `agy`. Only fall back to `gemini` when the user has a Gemini
Code Assist Standard/Enterprise license or a paid Gemini API key
(`GEMINI_API_KEY`) — those still work. See
[references/gemini-invocation.md](references/gemini-invocation.md) for
that legacy path.

## Quick Reference

```
# Codex (headless exec with structured JSON output)
codex exec -c model='"gpt-5.6-sol"' -c model_reasoning_effort='"xhigh"' \
  --sandbox read-only --ephemeral \
  --output-schema codex-review-schema.json \
  -o "$output_file" - < "$prompt_file"

# Antigravity (headless print mode — prompt must be an ARGUMENT, not stdin)
git diff HEAD > /tmp/review-diff.txt
agy --model gemini-3.1-pro-high --output-format text \
  --disable-slash-commands -p="$(cat /tmp/review-prompt.txt)"
```

## Invocation

### 1. Gather context interactively

Use `AskUserQuestion` to collect review parameters in one shot.
Adapt the questions based on what the user already provided
in their invocation (skip questions they already answered).

Combine all applicable questions into a single `AskUserQuestion`
call (max 4 questions).

**Question 1 — Tool** (skip if user already specified):

```
header: "Review tool"
question: "Which tool should run the review?"
options:
  - "Both Codex and Antigravity (Recommended)" → run both in parallel
  - "Codex only"                               → codex exec
  - "Antigravity only"                         → agy print mode
```

If the user says "gemini", treat it as Antigravity unless they
explicitly have a paid Code Assist / API-key setup.

**Question 2 — Scope** (skip if user already specified):

```
header: "Review scope"
question: "What should be reviewed?"
options:
  - "Uncommitted changes" → git diff HEAD + untracked files
  - "Branch diff vs main" → git diff <branch>...HEAD (auto-detect default branch)
  - "Specific commit"     → git diff <sha>~1..<sha> (follow up for SHA)
```

**Question 3 — Project context** (skip if neither CLAUDE.md nor AGENTS.md exists):

Check for CLAUDE.md first, then AGENTS.md in the repo root.
Only show this question if at least one exists.

```
header: "Project context"
question: "Include project conventions file so the review
  checks against your standards?"
options:
  - "Yes, include it"
  - "No, standard review"
```

**Question 4 — Review focus** (always ask):

```
header: "Review focus"
question: "Any specific focus areas for the review?"
options:
  - "General review"    → no custom prompt
  - "Security & auth"   → security-focused prompt
  - "Performance"       → performance-focused prompt
  - "Error handling"    → error handling-focused prompt
```

### 2. Run the tool directly

Do not pre-check tool availability. Run the selected tool
immediately. If the command fails with "command not found" or
an extension is missing, report the install command from the
Error Handling table below and skip that tool (if "Both" was
selected, run only the available one).

`agy` installs to `~/.local/bin`, which is not always on PATH.
Prefix the call with `export PATH="$HOME/.local/bin:$PATH"` before
concluding it is missing.

## Diff Preview

After collecting answers, show the diff stats:

```bash
# For uncommitted (tracked + untracked):
git diff --stat HEAD
git ls-files --others --exclude-standard

# For branch diff:
git diff --stat <branch>...HEAD

# For specific commit:
git diff --stat <sha>~1..<sha>
```

If the diff is empty, stop and tell the user.

If the diff is very large (>2000 lines changed), warn the user
and ask whether to proceed or narrow the scope.

## Auto-detect Default Branch

For branch diff scope, detect the default branch name:

```bash
git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
  | sed 's@^refs/remotes/origin/@@' || echo main
```

## Codex Invocation

See [references/codex-invocation.md](references/codex-invocation.md)
for full details on command syntax, prompt assembly, and the
structured output schema.

Summary:
- Uses `codex exec` (not `codex exec review`) for headless operation.
  `codex exec review` has native `--uncommitted` / `--base` /
  `--commit` scope flags, but they are mutually exclusive with a
  custom `[PROMPT]`, so it cannot carry project context or focus
  instructions. Keep the manual prompt-assembly approach.
- Model: `gpt-5.6-sol`, reasoning: `xhigh`
- Uses OpenAI's published code review prompt (fine-tuned into the model)
- Diff is generated manually and piped via stdin with the prompt
- `--output-schema` produces structured JSON findings
- `-o` captures only the final message (no thinking/exec noise)
- All three scopes (uncommitted, branch, commit) support project
  context and focus instructions (no limitations)
- Falls back to `gpt-5.6`, then `gpt-5.4`, on auth errors
- Output is clean JSON — parse and present findings by priority
- Set `timeout: 600000` on the Bash call

## Antigravity Invocation

See [references/antigravity-invocation.md](references/antigravity-invocation.md)
for full details on flags, scope mapping, and model selection.

Summary:
- Model: `gemini-3.1-pro-high` (effort is baked into the model slug)
- **The prompt must be a command-line argument, not stdin.** `agy`
  print mode does not read prompts from stdin unless
  `--input-format stream-json` is used. Assemble the prompt into a
  file, then pass `-p="$(cat "$prompt_file")"`.
- **Use `-p=<value>` with an equals sign.** Bare `-p` swallows the
  next flag as its prompt value and silently discards the real one.
- Add `--disable-slash-commands` so a line in the untrusted diff cannot
  be expanded as a slash command
- Do NOT pass `--mode plan`. It intermittently returns a "plan artifact
  / click Proceed" stub instead of the review. Omit `--mode` entirely
- Do NOT pass `--dangerously-skip-permissions`; it is unnecessary for
  a text-only diff review and will be blocked in restricted environments
- Prefer `--output-format text`. `--json-schema` is advisory, not
  enforced: it emits schema-shaped JSON nested inside a `response`
  string, duplicates the payload, and ran ~3x slower in testing
- Set `timeout: 600000` on the Bash call

**Scope mapping for `git diff`** (Antigravity has no built-in scope flags):

| Scope | Diff command |
|-------|-------------|
| Uncommitted | `git diff HEAD` + untracked (see codex-invocation.md) |
| Branch diff | `git diff <branch>...HEAD` |
| Specific commit | `git diff <sha>~1..<sha>` |

## Running Both

When the user picks "Both" (the default):

1. Run Codex and Antigravity in parallel — issue both Bash tool
   calls in a single response. Both commands are read-only
   (they review diffs via external APIs) so there is no
   shared state or git lock contention.
2. Collect both results, then present with clear headers:

```
## Codex Review (gpt-5.6-sol)
<codex output>

## Antigravity Review (gemini-3.1-pro-high)
<agy output>
```

Summarize where the two reviews agree and differ.

## Error Handling

| Error | Action |
|-------|--------|
| `codex: command not found` | Tell user: `npm i -g @openai/codex` |
| `agy: command not found` | Retry with `export PATH="$HOME/.local/bin:$PATH"`. Still missing → tell user to install Antigravity from <https://antigravity.google> |
| `agy` error: `-p took "--model" as its prompt` | Use `-p=<value>` form and move other flags before it |
| `agy` error: `empty prompt` | The prompt was piped on stdin. Pass it as an argument instead |
| `gemini` error: `UNSUPPORTED_CLIENT` / "migrate to the Antigravity suite" | Gemini CLI is EOL for individual tiers. Switch to `agy` |
| Model auth error (Codex) | Retry with `gpt-5.6`, then `gpt-5.4` |
| Empty diff | Tell user there are no changes to review |
| Timeout | Inform user and suggest narrowing the diff scope |
| Tool partially unavailable | Run only the available tool, note the skip |

## Examples

**Both tools (default):**
```
User: /second-opinion
Claude: [asks 4 questions: tool, scope, context, focus]
User: picks "Both", "Branch diff", "Yes include CLAUDE.md", "Security"
Claude: [detects default branch = main]
Claude: [shows diff --stat: 6 files, +103 -15]
Claude: [assembles prompt with review instructions + CLAUDE.md + security focus + diff]
Claude: [runs codex exec and agy in parallel]
Claude: [reads codex output file, parses structured findings]
Claude: [presents both reviews, highlights agreements/differences]
```

**Codex only with inline args:**
```
User: /second-opinion check uncommitted changes for bugs
Claude: [scope known: uncommitted, focus known: custom]
Claude: [asks 2 questions: tool, project context]
User: picks "Codex only", "No context"
Claude: [shows diff --stat: 3 files, +45 -10]
Claude: [writes prompt file with review instructions + diff]
Claude: [runs codex exec, reads structured JSON output]
Claude: [presents findings by priority with file:line refs]
```

**Antigravity only:**
```
User: /second-opinion
Claude: [asks 4 questions]
User: picks "Antigravity only", "Uncommitted", "No", "General"
Claude: [shows diff --stat: 2 files, +20 -5]
Claude: [writes prompt file, runs agy --model gemini-3.1-pro-high -p="$(cat prompt.txt)"]
Claude: [presents review]
```

**Large diff warning:**
```
User: /second-opinion
Claude: [asks questions] → user picks "Both", "Uncommitted", "General"
Claude: [shows diff --stat: 45 files, +3200 -890]
Claude: "Large diff (3200+ lines). Proceed, or narrow the scope?"
User: "proceed"
Claude: [runs both reviews]
```

## agents

```

```

## agents/openai.yaml

```yaml
interface:
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"
```

## assets

```

```

## assets/trail-of-bits-mark.svg

```

```

## references

```

```

## references/antigravity-invocation.md

# Antigravity CLI (`agy`) Invocation

Antigravity CLI replaced Gemini CLI for individual Google accounts on
2026-06-18. Binary is `agy`. Verified against `agy` 1.1.21.

## Default Configuration

- Model: `gemini-3.1-pro-high`
- Output: `--output-format text`
- Add `--disable-slash-commands` — the prompt embeds an untrusted diff,
  and without this a line in the diff that looks like `/something` can
  be expanded as a slash command

## PATH

`agy` installs to `~/.local/bin`, which is often absent from a
non-interactive shell's PATH. Always prefix:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

## Models

`agy models` lists what the account can reach. As of testing:

```
gemini-3.7-flash-high / -medium / -low
gemini-3.6-flash-high / -medium / -low
gemini-3.5-flash-high / -medium / -low
gemini-3.1-pro-high
gemini-3.1-pro-low
claude-sonnet-4-6
claude-opus-4-6-thinking
gpt-oss-120b-medium
```

Reasoning effort is part of the model slug — there is no separate
effort flag to set for these (though `--effort low|medium|high` exists
for models that take it). Use `gemini-3.1-pro-high` for code review:
it is the strongest Gemini option exposed.

Do not select `claude-*` slugs for a second opinion — the point is a
different model family from Claude.

## Key Flags

| Flag | Purpose |
|------|---------|
| `-p=<prompt>` / `--print=<prompt>` | Non-interactive (headless) mode |
| `--model <slug>` | Model selection |
| `--mode plan` | Plan mode — **do not use for reviews**, see below |
| `--disable-slash-commands` | Stop diff text from being read as slash commands |
| `--output-format text\|json\|stream-json` | Output shape |
| `--json-schema <file>` | Advisory structured output (see caveat) |
| `--sandbox` | Terminal restrictions |
| `--dangerously-skip-permissions` | Auto-approve tools — **do not use** |

## Two Gotchas That Will Break the Call

### 1. The prompt must be an argument, not stdin

Unlike `codex exec -`, `agy` print mode does **not** read the prompt
from stdin (only `--input-format stream-json` consumes stdin, as
NDJSON). Piping a diff into `agy -p` fails with:

```
Error: Error: empty prompt. Usage: agy --print "your prompt here"
```

Assemble the prompt into a file, then pass its contents:

```bash
agy --model gemini-3.1-pro-high --output-format text \
  --disable-slash-commands -p="$(cat "$prompt_file")"
```

### 2. Use `-p=<value>`, never bare `-p`

Bare `-p` consumes the next token as its prompt value. `agy -p --model x`
takes `--model` as the prompt and discards the real one:

```
Error: -p took "--model" as its prompt, so the intended prompt was left
as an argument and ignored.
```

Always use the `=` form and put other flags before it.

## Prompt Assembly

Same structure as the Codex path. Write to `$prompt_file`:

```
You are reviewing a proposed code change made by another engineer.
Flag only actionable issues introduced by this diff, citing the affected
file and line range. Prioritize correctness, security, performance, and
maintainability over nits. After the findings, give an overall
correctness verdict and a confidence score.
Review the diff text only.

<If project context was requested>
Project conventions and standards:
---
<full contents of CLAUDE.md or AGENTS.md>
---

<If focus area was selected>
Focus: <focus area instructions>

Diff to review:
---
<git diff output for the selected scope>
---
```

## Scope-to-Diff Mapping

`agy` has no built-in scope flags. Map the user's choice:

| Scope | Diff command |
|-------|-------------|
| Uncommitted | `git diff HEAD` + untracked files (see codex-invocation.md) |
| Branch diff | `git diff <branch>...HEAD` |
| Specific commit | `git diff <sha>~1..<sha>` |

**For uncommitted scope, use `git diff HEAD`, not bare `git diff`** —
bare `git diff` misses staged changes. Include untracked files too.

## Do Not Use `--mode plan`

`--mode plan` makes `agy` treat the review as a planning task. It
intermittently writes its findings into a plan artifact and returns
only a stub asking for approval that will never come:

```
I have created an implementation plan artifact containing my proposed
code review findings.
Please review the artifact and click "Proceed" if you agree...
```

The same command printed a full review on one run and this stub on the
next, so it is not safely reproducible. Omit `--mode` entirely — plain
print mode does not request tool approvals for a text-only diff review.

## Full Command

```bash
export PATH="$HOME/.local/bin:$PATH"
agy --model gemini-3.1-pro-high \
    --output-format text \
    --disable-slash-commands \
    -p="$(cat "$prompt_file")" \
  > "$output_file" 2>"$stderr_log"
```

Typical wall time for a small diff: 19–34s. Set `timeout: 600000`.

## Structured Output: Prefer Text

`--json-schema <file>` with `--output-format json` runs, but the schema
is advisory, not enforced. Observed with the Codex review schema:

- The findings JSON arrives as an **escaped string** inside a
  `response` field of the outer envelope, requiring a double parse
- `code_location` came back as a string (`"app.py:3-4"`) in one block
  and an object in another, contradicting the schema
- `confidence_score` came back as `100` where the schema says 0–1
- `overall_correctness` came back as `"Needs Work"`, not one of the
  schema's enum values
- The payload was emitted twice in the same response
- Took ~68s versus ~24s for the text path

Use `--output-format text` and present `agy`'s prose review as-is.
Keep the structured-JSON path for Codex only.

## Do Not Pass `--dangerously-skip-permissions`

A text-only diff review needs no tool approvals, and the flag is
blocked outright in permission-restricted environments. Leave it off.

## Extensions / Security Scanning

Antigravity CLI does not carry over the Gemini CLI `code-review` or
`gemini-cli-security` extensions, and has no `/security:scan-deps`
equivalent. For dependency scanning, use a dedicated tool
(`osv-scanner`, `npm audit`, `pip-audit`) rather than routing it
through `agy`.

`agy plugin list` shows what is installed if the user has added
plugins; there is no bundled review plugin to rely on.

## Error Handling

| Error | Action |
|-------|--------|
| `agy: command not found` | Add `~/.local/bin` to PATH; else install from <https://antigravity.google> |
| `-p took "--model" as its prompt` | Use `-p=<value>`, flags before it |
| `empty prompt` | Prompt was on stdin; pass as argument |
| Permission denied on `--dangerously-skip-permissions` | Drop the flag; plain print mode needs no approvals |
| Output is a "plan artifact / click Proceed" stub | `--mode plan` was passed. Remove it |
| Timeout | Inform user, suggest scoping down the diff |

## references/codex-invocation.md

# Codex CLI Invocation

## Default Configuration

- Model: `gpt-5.6-sol`
- Reasoning effort: `xhigh`

Verified against `codex-cli` 0.149.1. The `gpt-5.6` family exposes
`gpt-5.6`, `gpt-5.6-sol`, `gpt-5.6-luna`, `gpt-5.6-terra`, and
`gpt-5.6-pro`. `sol` is the general-purpose choice and the one the
Codex CLI's own default config selected on the machine this was
verified on.

Valid `model_reasoning_effort` values are now `none`, `minimal`, `low`,
`medium`, `high`, `xhigh`, `max`, `ultra`. `xhigh` is the right default
for review — `max`/`ultra` cost substantially more wall time for
marginal gain on a diff-sized input.

## Why Not `codex exec review`

`codex exec review` now has native scope flags (`--uncommitted`,
`--base <BRANCH>`, `--commit <SHA>`) and supports `--output-schema`,
`-o`, and `--ephemeral`. It looks like a simplification, but those
scope flags are **mutually exclusive with the `[PROMPT]` argument**:

```
error: the argument '--uncommitted' cannot be used with '[PROMPT]'
```

That makes it impossible to inject project conventions (CLAUDE.md /
AGENTS.md) or a focus area alongside a scope flag. Keep the manual
`codex exec` prompt-assembly approach below, which supports context
and focus for all three scopes.

## Approach

Use `codex exec` in headless mode with the published code review
prompt, structured JSON output, and `-o` (`--output-last-message`)
to capture only the final review. This avoids the verbose
`[thinking]` and `[exec]` blocks that `codex review` dumps to
stdout.

## Review Prompt

Use this prompt verbatim — it is from OpenAI's [Build Code Review
with the Codex SDK](https://developers.openai.com/cookbook/examples/codex/build_code_review_with_codex_sdk)
cookbook, and GPT-5.4 and later (including the 5.6 family)
received specific training on it:

```
You are acting as a reviewer for a proposed code change made by another engineer.
Focus on issues that impact correctness, performance, security, maintainability, or developer experience.
Flag only actionable issues introduced by the pull request.
When you flag an issue, provide a short, direct explanation and cite the affected file and line range.
Prioritize severe issues and avoid nit-level comments unless they block understanding of the diff.
After listing findings, produce an overall correctness verdict ("patch is correct" or "patch is incorrect") with a concise justification and a confidence score between 0 and 1.
Ensure that file citations and line numbers are exactly correct using the tools available; if they are incorrect your comments will be rejected.
```

## Prompt Assembly

Create temp files for the prompt and output:

```bash
prompt_file="$(mktemp)"
output_file="$(mktemp)"
stderr_log="$(mktemp)"
```

Write the prompt file with these sections in order:

```
<review prompt from above>

<If project context was requested>
Project conventions and standards:
---
<full contents of CLAUDE.md or AGENTS.md>
---

<If focus area was selected or custom text provided>
Focus: <focus area instructions>

Diff to review:
---
<git diff output for the selected scope>
---
```

### Generating the diff

| Scope | Command |
|-------|---------|
| Uncommitted (tracked) | `git diff HEAD` |
| Uncommitted (untracked) | `git ls-files --others --exclude-standard` — for each file, append `git diff --no-index /dev/null <file>` |
| Branch diff | `git diff <branch>...HEAD` |
| Specific commit | `git diff <sha>~1..<sha>` |

**Uncommitted scope must include untracked files.** `git diff HEAD`
alone only shows changes to tracked files. New files that haven't
been staged would be silently excluded. Generate the full diff:

```bash
{
  git diff HEAD
  git ls-files --others --exclude-standard | while IFS= read -r f; do
    git diff --no-index /dev/null "$f" 2>/dev/null || true
  done
}
```

## Base Command

```bash
codex exec \
  -c model='"gpt-5.6-sol"' \
  -c model_reasoning_effort='"xhigh"' \
  --sandbox read-only \
  --ephemeral \
  --output-schema {baseDir}/references/codex-review-schema.json \
  -o "$output_file" \
  - < "$prompt_file" \
  > /dev/null 2>"$stderr_log"
```

Then read `$output_file` with the Read tool. If empty or missing,
read `$stderr_log` to diagnose the failure.

## Output Format

The output is structured JSON matching `codex-review-schema.json`:

```json
{
  "findings": [
    {
      "title": "Short description (max 80 chars)",
      "body": "Detailed explanation",
      "confidence_score": 0.95,
      "priority": 1,
      "code_location": {
        "file_path": "src/main.rs",
        "line_range": { "start": 42, "end": 48 }
      }
    }
  ],
  "overall_correctness": "patch is correct",
  "overall_explanation": "Summary of the review",
  "overall_confidence_score": 0.9
}
```

Priority levels: 0 = informational, 1 = low, 2 = medium, 3 = high.

### Presenting Results

Parse the JSON and present findings grouped by priority (highest
first). For each finding, show:

- **Title** with file:line reference
- **Body** explanation
- **Confidence** as a percentage

End with the overall verdict and confidence.

If the output file is empty or missing, read `$stderr_log` to
diagnose the failure.

## Model Fallback

If `gpt-5.6-sol` fails with an auth error (e.g., "not supported
when using Codex with a ChatGPT account"), retry in order:
`gpt-5.6`, then `gpt-5.4`. Log the fallback for the user.

`gpt-5.6-pro` is deliberately not in the fallback chain: it is a
higher-tier, slower model, so it is a poor automatic substitute for an
auth failure. Untested here — reach for it only on explicit request.

## Error Handling

| Error | Action |
|-------|--------|
| `codex: command not found` | Tell user: `npm i -g @openai/codex` |
| Model auth error | Retry with `gpt-5.6`, then `gpt-5.4` |
| Timeout | Suggest narrowing the diff scope |
| `EPERM` / sandbox errors | Expected — `codex exec` runs sandboxed. Ignore these. |
| Empty/missing output file | Read `$stderr_log` to diagnose the failure |

## references/codex-review-schema.json

```json
{
  "type": "object",
  "properties": {
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 80
          },
          "body": {
            "type": "string",
            "minLength": 1
          },
          "confidence_score": {
            "type": ["number", "null"],
            "minimum": 0,
            "maximum": 1
          },
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "code_location": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "file_path": {
                    "type": "string"
                  },
                  "line_range": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "start": {
                            "type": "integer"
                          },
                          "end": {
                            "type": "integer"
                          }
                        },
                        "required": ["start", "end"],
                        "additionalProperties": false
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": ["file_path", "line_range"],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": ["title", "body", "confidence_score", "priority", "code_location"],
        "additionalProperties": false
      }
    },
    "overall_correctness": {
      "type": "string"
    },
    "overall_explanation": {
      "type": ["string", "null"]
    },
    "overall_confidence_score": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": ["findings", "overall_correctness", "overall_explanation", "overall_confidence_score"],
  "additionalProperties": false
}
```

## references/gemini-invocation.md

# Gemini CLI Invocation (Legacy — Paid Tiers Only)

> **Gemini CLI is end-of-life for individual accounts.** On 2026-06-18
> Google stopped serving Gemini CLI requests for AI Pro, Ultra, and
> free-tier individual accounts. Those accounts now fail with:
>
> ```
> reasonCode: 'UNSUPPORTED_CLIENT'
> reasonMessage: 'This client is no longer supported for Gemini Code
>   Assist for individuals. To continue using Gemini, please migrate to
>   the Antigravity suite of products: https://antigravity.google'
> ```
>
> This is the shutdown, not a broken install. Reinstalling, clearing
> `~/.gemini`, or signing in with a different personal Google account
> will not fix it.
>
> **Use [antigravity-invocation.md](antigravity-invocation.md) instead.**

## Who Can Still Use This Path

Only these keep working:

- Organizations with **Gemini Code Assist Standard or Enterprise**
  licenses
- Accounts using a **paid Gemini API key** via `GEMINI_API_KEY`
  (AI Studio / Vertex), which bypasses Code Assist tier gating
  entirely
- **Vertex AI** via `GOOGLE_GENAI_USE_VERTEXAI=true`

Check before using this path:

```bash
env | grep -q GEMINI_API_KEY && echo "api-key auth available"
```

If auth is `oauth-personal` (see `~/.gemini/settings.json`) and the
account is an individual tier, this path will fail. Go to Antigravity.

## Default Configuration

- Model: `gemini-3.1-pro-preview`
- Extensions: `code-review`, `gemini-cli-security`

## Key Flags

| Flag | Purpose |
|------|---------|
| `-p <prompt>` | Non-interactive (headless) mode; reads stdin too |
| `--yolo` / `-y` | Auto-approve all tool calls |
| `-m <model>` | Model selection |
| `-e <ext>` | Load specific extension(s) |
| `--skip-trust` | Trust the workspace for this session — **required in headless runs** |

### Trusted-folder gotcha

`--yolo` is **silently downgraded** in an untrusted directory:

```
YOLO mode is enabled. All tool calls will be automatically approved.
Approval mode overridden to "default" because the current folder is not trusted.
Gemini CLI is not running in a trusted directory. To proceed, either use
`--skip-trust`, set the `GEMINI_CLI_TRUST_WORKSPACE=true` environment
variable, or trust this directory in interactive mode.
```

Any headless invocation must add `--skip-trust` (or export
`GEMINI_CLI_TRUST_WORKSPACE=true`), or the extension-driven paths will
stall waiting for approvals that can never arrive.

## Scope-to-Diff Mapping

| Scope | Diff command |
|-------|-------------|
| Uncommitted | `git diff HEAD` (captures both staged and unstaged) |
| Branch diff | `git diff <branch>...HEAD` |
| Specific commit | `git diff <sha>~1..<sha>` |

**Important:** For uncommitted scope, use `git diff HEAD` not bare
`git diff`. Bare `git diff` misses staged changes.

## Code Review (General, Performance, Error Handling)

For uncommitted changes, the `/code-review` extension automatically
picks up the working tree diff:

```bash
gemini -p "/code-review" \
  --yolo \
  --skip-trust \
  -e code-review \
  -m gemini-3.1-pro-preview
```

For branch diffs or specific commits, pipe the diff with a prompt
header (avoids heredocs — diffs contain `$` and backticks that break
shell expansion):

```bash
git diff <branch>...HEAD > /tmp/review-diff.txt
{ printf '%s\n\n' 'Review this diff for code quality issues. <focus prompt>'; \
  cat /tmp/review-diff.txt; } \
  | gemini -p - -m gemini-3.1-pro-preview --yolo --skip-trust
```

## Security Review

`/security:analyze` is interactive-only, so use headless mode with a
security-focused prompt instead:

```bash
git diff HEAD > /tmp/review-diff.txt
{ printf '%s\n\n' 'Analyze this diff for security vulnerabilities, including injection, auth bypass, data exposure, and input validation issues. Report each finding with severity, location, and remediation.'; \
  cat /tmp/review-diff.txt; } \
  | gemini -p - -e gemini-cli-security -m gemini-3.1-pro-preview --yolo --skip-trust
```

Only run the supply chain scan if the diff touches dependency manifests:

```bash
git diff --name-only <scope> \
  | grep -qiE '(package\.json|package-lock|yarn\.lock|pnpm-lock|Gemfile|\.gemspec|requirements\.txt|setup\.py|setup\.cfg|pyproject\.toml|poetry\.lock|uv\.lock|Cargo\.toml|Cargo\.lock|go\.mod|go\.sum|composer\.json|composer\.lock|Pipfile)' \
  && gemini -p "/security:scan-deps" \
       --yolo \
       --skip-trust \
       -e gemini-cli-security \
       -m gemini-3.1-pro-preview
```

The scan analyzes the entire project's dependency tree regardless of
diff scope, so it adds significant time for no value when dependencies
were not touched.

## Adding Project Context

```bash
git diff HEAD > /tmp/review-diff.txt
{ printf 'Project conventions:\n---\n'; \
  cat CLAUDE.md; \
  printf '\n---\n\n%s\n\n' '<review instructions and focus>'; \
  cat /tmp/review-diff.txt; } \
  | gemini -p - -m gemini-3.1-pro-preview --yolo --skip-trust
```

## Error Handling

| Error | Action |
|-------|--------|
| `UNSUPPORTED_CLIENT` / "migrate to the Antigravity suite" | Individual tier is shut off. Switch to `agy` |
| `gemini: command not found` | Tell user: `npm i -g @google/gemini-cli` |
| `not running in a trusted directory` | Add `--skip-trust` |
| Extension missing | Tell user: `gemini extensions install <github-url>` |
| `-e security` silently ignored | Use `-e gemini-cli-security` (the actual installed name) |
| Timeout | Inform user, suggest scoping down the diff |

## Extension Install Commands

```bash
gemini extensions install https://github.com/gemini-cli-extensions/code-review
gemini extensions install https://github.com/gemini-cli-extensions/security
```

The security extension installs as `gemini-cli-security` (not
`security`). Always use `-e gemini-cli-security` when loading it.