azmym · azmym · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,8 +1,8 @@
 {
   "name": "gemini-plugin",
   "displayName": "Gemini Plugin",
-  "version": "0.3.0",
-  "description": "Wraps gemini-mcp into a Claude Code plugin so Gemini acts as a second opinion: validator/challenger/researcher/summarizer subagents, auto-trigger hooks, and 8 task-oriented skills.",
+  "version": "0.4.0",
+  "description": "Wraps gemini-mcp into a Claude Code plugin so Gemini acts as a second opinion: validator/challenger/researcher/summarizer/reviewer subagents, auto-trigger hooks, and 9 task-oriented skills.",
   "author": { "name": "azmym" },
   "homepage": "https://github.com/azmym/gemini-plugin",
   "repository": "https://github.com/azmym/gemini-plugin",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,17 @@ All notable changes to gemini-plugin are documented here. The format follows [Ke
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-29
+
+### Added
+
+- **`gemini-reviewer` agent (5th subagent).** A generalist third-reviewer for diffs and PRs, covering the cross-cutting concerns the other four agents do not own: security, threading correctness, library/version drift, doc accuracy, dead code, and complexity. Modeled on the `gemini-assistant` "code review" mode from the IPTV project setup. Sonnet, `maxTurns: 10`, returns structured JSON `{verdict, strengths, issues, next_actions}`. It is advisory: a `changes_requested` verdict surfaces inline but does not block, because the reviewer is dispatched manually rather than by a hook.
+- **`gemini-consult` dispatch-rule skill (9th skill).** Tells the main Claude when to consult Gemini, which of the five agents to route to, and enforces a one-consult-per-turn cap on manual dispatches (the always-on hooks are a separate, uncounted channel). Ports the disagreement protocol and "what you are NOT" scope guards from the IPTV `gemini-assistant` rule.
+
+### Changed
+
+- `gemini-reviewer` added to the `SubagentStop` matcher so its transcript is read and persisted to plan-history.
+
 ## [0.3.0] - 2026-05-28
 
 ### Changed

diff --git a/README.md b/README.md
@@ -76,15 +76,16 @@ The plugin auto-registers the `gemini` MCP server. No separate `claude mcp add`
 | You ask about a library version, CVE, or live API | Prompt grounding hook | Gemini searches the web and injects citations before Claude answers |
 | Claude is about to compact context | Pre-compact hook | Gemini summarizes decisions and unresolved debt so the next session starts with full context |
 | Claude says it is finished | Done-claim hook | Gemini validates output against your original ask; blocks if something was missed |
-| You want a second opinion right now | Slash command | Any of the four subagents on demand, for any artifact or question |
+| You want a second opinion right now | Slash command or consult rule | Any of the five subagents on demand, for any artifact or question |
+| You are finalizing a diff or PR | gemini-reviewer (manual consult) | A generalist review for security, threading, version drift, docs, dead code, and complexity |
 
 ## Architecture at a glance
 
 <p align="center">
   <img src="assets/infographic.png" alt="gemini-plugin architecture: three layers (hooks coordinate, subagents reason, MCP executes) connecting Claude Code to Gemini" width="900" />
 </p>
 
-Three layers do the work: **hooks** coordinate (read events, apply gates, emit directives), **subagents** reason (validator, challenger, researcher, summarizer with structured JSON verdicts), and the **gemini-mcp** server executes (calls Gemini, Imagen, Veo, and Lyria via Google AI Studio). For the full architecture write-up, see [docs/reference/architecture.md](docs/reference/architecture.md).
+Three layers do the work: **hooks** coordinate (read events, apply gates, emit directives), **subagents** reason (validator, challenger, researcher, summarizer, and reviewer with structured JSON verdicts), and the **gemini-mcp** server executes (calls Gemini, Imagen, Veo, and Lyria via Google AI Studio). For the full architecture write-up, see [docs/reference/architecture.md](docs/reference/architecture.md).
 
 ## Slash commands
 

diff --git a/agents/gemini-reviewer.md b/agents/gemini-reviewer.md
@@ -0,0 +1,108 @@
+---
+name: gemini-reviewer
+description: |
+  Use proactively when finalizing a diff or PR for a generalist third-reviewer
+  pass that the other agents do not cover: security, threading correctness,
+  library/version drift, doc accuracy, dead code, and complexity. NOT for
+  research (use gemini-researcher), claim validation (use gemini-validator),
+  or devil's-advocate brainstorming (use gemini-challenger). Returns structured
+  JSON {verdict, strengths, issues, next_actions}.
+tools:
+  - mcp__gemini__gemini_chat
+  - mcp__gemini__gemini_search_grounded
+  - Read
+  - Grep
+  - Glob
+  - Bash
+model: sonnet
+color: cyan
+maxTurns: 10
+skills:
+  - gemini-when-to-use
+---
+
+You are gemini-reviewer, a generalist third-reviewer powered by Google Gemini.
+Your role is to review a diff or PR for the cross-cutting concerns that the
+other four Gemini agents do not own: security, threading/concurrency
+correctness, library and API version drift, documentation accuracy, dead code,
+and unnecessary complexity.
+
+## Workflow
+
+You have 10 turns. Budget them:
+
+1. **Turn 1-2: Establish scope.** If the brief names BASE_SHA and HEAD_SHA, run
+   `git diff $BASE_SHA $HEAD_SHA --stat` then targeted `git show` /
+   `git diff $BASE_SHA $HEAD_SHA -- <path>` on the changed files. If the brief
+   names files or a path instead, Read those directly.
+2. **Turn 3-4: Read for context.** Use Read/Grep/Glob to pull in surrounding
+   code the diff depends on, so your review is grounded, not surface-level.
+3. **Turn 5-7: Call Gemini once.** Call mcp__gemini__gemini_chat with the diff
+   content and ask for a review focused ONLY on: security, threading
+   correctness, library/version drift, doc accuracy, dead code, complexity.
+4. **Turn 8 (optional): Verify a version fact.** If and only if a finding hinges
+   on a version-specific or post-cutoff fact, call
+   mcp__gemini__gemini_search_grounded ONCE to confirm it.
+5. **Turn 9: Synthesize.** Draft the JSON verdict.
+6. **Turn 10: Emit ONLY the JSON** (no other content in this turn).
+
+## What you are NOT
+
+- You are NOT gemini-validator. You do not validate a plan or a done-claim
+  against the original ask. If asked to do that, say so and defer.
+- You are NOT gemini-researcher. You do not perform open-ended research. A
+  single grounded lookup to confirm one version fact is the only exception.
+- You are NOT gemini-challenger. You do not argue alternatives or play devil's
+  advocate on architecture decisions. That is the challenger's job.
+- You are NOT a yes-machine. If Gemini's findings contradict the dispatching
+  Claude's draft, surface BOTH positions with their evidence. Do not silently
+  defer to either side.
+
+## Disagreement protocol
+
+If Gemini's review contradicts a claim or choice in the diff or the dispatching
+brief, record both positions in the verdict (one issue entry stating Gemini's
+position with its citation, the strengths or next_actions noting the author's
+rationale if known). Let the human decide. Tie-break toward the side with the
+more concrete, recent (post-2024) citation.
+
+## Cap
+
+At most ONE mcp__gemini__gemini_chat call and at most ONE
+mcp__gemini__gemini_search_grounded call per dispatch, unless the brief
+explicitly authorizes more. Latency and token cost matter.
+
+## Output Format
+
+**CRITICAL: Your FINAL turn must contain ONLY this JSON object, with no
+surrounding text, no code fences, no preamble, and no explanatory prose.**
+
+The verdict-handler hook parses your final assistant message with jq, so any
+non-JSON content breaks the contract and the verdict is silently discarded. Do
+not narrate your work in the last turn. Do not say "Here is the verdict:" before
+the JSON. Do not wrap it in ```json fences.
+
+    {
+      "verdict": "approved|changes_requested|unknown",
+      "strengths": [],
+      "issues": {
+        "critical": [],
+        "important": [],
+        "minor": []
+      },
+      "next_actions": []
+    }
+
+- **approved**: no critical or important issues; merge is safe.
+- **changes_requested**: at least one critical or important issue found.
+- **unknown**: insufficient diff/context to judge confidently.
+
+Each issue string SHOULD carry a `file:line` reference where applicable. All
+arrays may be empty. If verdict is approved, the critical and important arrays
+MUST be empty.
+
+## Failure-mode discipline
+
+If at turn 9 you do not have enough information for a confident verdict, emit
+verdict: "unknown" with a clear issues entry explaining what was missing. Never
+run out of turns mid-response. Partial responses are worse than unknown.
diff --git a/docs/index.md b/docs/index.md
@@ -13,8 +13,8 @@ A Claude Code plugin that turns Google Gemini into a second-opinion assistant la
 | [Configure hooks](how-to/configure-hooks.md) | Enable, disable, or customize the automatic triggers |
 | **Reference** | |
 | [Architecture](reference/architecture.md) | System architecture, data flow, and component diagram |
-| [Skills](reference/skills.md) | All 8 skills with descriptions and MCP tool mappings |
-| [Subagents](reference/subagents.md) | All 4 subagents with frontmatter, tools, and output schemas |
+| [Skills](reference/skills.md) | All 9 skills with descriptions and MCP tool mappings |
+| [Subagents](reference/subagents.md) | All 5 subagents with frontmatter, tools, and output schemas |
 | [Hooks](reference/hooks.md) | All 7 hooks with event types, gates, and exit behavior |
 | [Commands](reference/commands.md) | All 5 slash commands with usage examples |
 | **Explanation** | |
@@ -29,9 +29,10 @@ Plugin installs via marketplace
 ┌─────────────────────────────────────────────┐
 │ gemini-plugin                               │
 │                                             │
-│  8 skills    - when/how to use Gemini       │
-│  4 subagents - validator, challenger,       │
-│                researcher, summarizer       │
+│  9 skills    - when/how to use Gemini       │
+│  5 subagents - validator, challenger,       │
+│                researcher, summarizer,      │
+│                reviewer                     │
 │  7 hooks     - auto-trigger on key events   │
 │  5 commands  - manual slash invocation      │
 │  1 rule      - session-level guidance       │

diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md
@@ -8,7 +8,7 @@ This document describes the system architecture of gemini-plugin: how the compon
 graph TB
     subgraph "Claude Code Session"
         User[User] --> Claude[Main Claude Agent]
-        Claude --> Skills[8 Skills]
+        Claude --> Skills[9 Skills]
         Claude --> Commands[5 Slash Commands]
     end
 
@@ -26,13 +26,15 @@ graph TB
         Claude --> |Agent tool| Challenger[gemini-challenger]
         Claude --> |Agent tool| Researcher[gemini-researcher]
         Claude --> |Agent tool| Summarizer[gemini-summarizer]
+            Claude --> |Agent tool| Reviewer[gemini-reviewer]
     end
 
     subgraph "MCP (execution layer)"
         Validator --> MCP[gemini-mcp server]
         Challenger --> MCP
         Researcher --> MCP
         Summarizer --> MCP
+            Reviewer --> MCP
     end
 
     subgraph "Google AI Studio"
@@ -121,8 +123,8 @@ sequenceDiagram
 | Component | Count | Location | Purpose |
 |---|---|---|---|
 | Plugin manifest | 1 | `.claude-plugin/plugin.json` | Metadata, userConfig prompt, MCP server registration |
-| Skills | 8 | `skills/*/SKILL.md` | When/how to use Gemini capabilities |
-| Subagents | 4 | `agents/*.md` | Role-specific reasoning with structured output |
+| Skills | 9 | `skills/*/SKILL.md` | When/how to use Gemini capabilities |
+| Subagents | 5 | `agents/*.md` | Role-specific reasoning with structured output |
 | Commands | 5 | `commands/*.md` | User-invoked slash commands |
 | Hooks | 7 | `hooks/hooks.json` + `hooks/*.sh` | 6 triggers + 1 verdict handler |
 | Shared library | 2 | `hooks/lib/*.sh` | JSON helpers, gates, prompt builders |
@@ -166,7 +168,7 @@ The plugin manifest auto-registers the gemini MCP server on install:
 }
 ```
 
-All 4 subagents inherit this MCP connection from the parent session (plugin subagents cannot define their own `mcpServers` in frontmatter).
+All 5 subagents inherit this MCP connection from the parent session (plugin subagents cannot define their own `mcpServers` in frontmatter).
 
 ## State management
 
@@ -199,5 +201,6 @@ State is local, session-scoped, and disposable. Deleting the data directory rese
 | gemini-challenger | Opus | Hardest reasoning task (creative alternatives + objections); bumped from Sonnet in v0.3.0 |
 | gemini-researcher | Sonnet | Multi-source synthesis and citation discipline; bumped from Haiku in v0.3.0 |
 | gemini-summarizer | Opus | Large-input compression with structured output; bumped from Sonnet in v0.3.0 |
+| gemini-reviewer | Sonnet | Generalist diff/PR review; manual consult via the gemini-consult rule (added in v0.4.0) |
 
 All subagents call Gemini models via MCP (default: `gemini-3.5-flash` for chat/search, `gemini-3.1-pro-preview` for generate). The Claude model handles orchestration and JSON structuring; the Gemini model handles reasoning and web access. The Claude-side model bumps in v0.3.0 fixed a class of partial-response failures where validator and other agents were exiting before producing the final JSON verdict.
diff --git a/docs/reference/hooks.md b/docs/reference/hooks.md
@@ -124,11 +124,11 @@ Patterns that look destructive but pass through (intentional false-positive guar
 | Field | Value |
 |---|---|
 | Event | `SubagentStop` |
-| Matcher | `gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer` |
+| Matcher | `gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer|gemini-reviewer` |
 | Gate | Transcript must exist and contain parseable JSON verdict |
 | Blocking | Conditional: exit 2 if verdict=fail or verdict=block; exit 0 otherwise |
 
-**What it does:** Reads the subagent's transcript, extracts the final JSON verdict, applies the loop guard (identical verdict twice in a row is demoted to advisory), persists to plan-history.jsonl, and decides whether to block.
+**What it does:** Reads the subagent's transcript, extracts the final JSON verdict, applies the loop guard (identical verdict twice in a row is demoted to advisory), persists to plan-history.jsonl, and decides whether to block. gemini-reviewer's verdict (changes_requested) is advisory and does not trigger the exit-2 block path (only fail/block block).
 
 **Stdin JSON:** `{"agent_type": "gemini-validator", "transcript_path": "/path/to/transcript.jsonl"}`
 

diff --git a/docs/reference/skills.md b/docs/reference/skills.md
@@ -1,12 +1,13 @@
 # Skills Reference
 
-The plugin ships 8 task-oriented skills. Skills tell Claude WHEN to reach for Gemini and WHICH MCP tool to use. They load on-demand when Claude determines a match based on the description field.
+The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Gemini and WHICH MCP tool to use. They load on-demand when Claude determines a match based on the description field.
 
 ## Skill index
 
 | Skill | MCP tools | Auto-invoked? |
 |---|---|---|
 | [gemini-when-to-use](#gemini-when-to-use) | (none, decision guide) | Yes (broadest description) |
+| [gemini-consult](#gemini-consult) | (none, dispatch rule) | Yes (routes among the 5 agents) |
 | [gemini-chat-and-reason](#gemini-chat-and-reason) | `gemini_generate`, `gemini_chat` | Yes |
 | [gemini-research-grounded](#gemini-research-grounded) | `gemini_search_grounded`, `gemini_start_research`, `gemini_get_research_report` | Yes |
 | [gemini-file-analysis](#gemini-file-analysis) | `gemini_analyze_file` | Yes |
@@ -17,7 +18,7 @@ The plugin ships 8 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 
 ## gemini-when-to-use
 
-**Description:** Master router for the Gemini plugin. Covers cost discipline, anti-hallucination triggers, and the four subagent roles.
+**Description:** Master router for the Gemini plugin. Covers cost discipline, anti-hallucination triggers, and the five subagent roles.
 
 **Purpose:** Loaded first, before any other gemini-* skill. Tells Claude:
 - Which subagent to use for which situation
@@ -27,6 +28,14 @@ The plugin ships 8 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 
 **Invocation:** `/gemini-plugin:gemini-when-to-use` or auto-invoked when Claude is uncertain
 
+## gemini-consult
+
+**Description:** Dispatch rule for the five Gemini agents. Routes a consult to the right agent and enforces a one-consult-per-turn cap on manual dispatches.
+
+**Purpose:** Complements gemini-when-to-use. Where gemini-when-to-use routes among the seven capability skills (raw MCP calls), gemini-consult routes among the five subagents (researcher, validator, challenger, reviewer, summarizer) for structured second-opinion work, and holds the per-turn cap plus the disagreement protocol.
+
+**Invocation:** Auto-consulted when Claude is deciding whether and how to get a Gemini second opinion. No MCP tools (decision guide only).
+
 ## gemini-chat-and-reason
 
 **Description:** Get a second opinion from Gemini via text generation or multi-turn chat.

diff --git a/docs/reference/subagents.md b/docs/reference/subagents.md
@@ -1,6 +1,6 @@
 # Subagents Reference
 
-The plugin ships 4 specialized subagents. Each has a focused role, restricted tools, and a structured JSON output schema. They are spawned by Claude via the Agent tool (triggered by hooks or slash commands).
+The plugin ships 5 specialized subagents. Each has a focused role, restricted tools, and a structured JSON output schema. They are spawned by Claude via the Agent tool (triggered by hooks or slash commands).
 
 ## Subagent summary
 
@@ -10,6 +10,7 @@ The plugin ships 4 specialized subagents. Each has a focused role, restricted to
 | gemini-challenger | opus | high | 8 | (none) | red | false |
 | gemini-researcher | sonnet | medium | 12 | (none) | green | true |
 | gemini-summarizer | opus | high | 4 | project | purple | false |
+| gemini-reviewer | sonnet | medium | 10 | (none) | cyan | false |
 
 All subagents preload the `gemini-when-to-use` skill via the `skills:` frontmatter field.
 
@@ -153,6 +154,31 @@ Output schema:
 
 **Memory:** project-scoped. Accumulates knowledge about the codebase across sessions.
 
+## gemini-reviewer
+
+**Role:** Generalist third-reviewer for diffs/PRs: security, threading correctness, library/version drift, doc accuracy, dead code, complexity. Covers concerns the other four agents do not own.
+
+**Tools:**
+- `mcp__gemini__gemini_chat`
+- `mcp__gemini__gemini_search_grounded`
+- Read, Grep, Glob, Bash
+
+**Output schema:**
+
+```json
+{
+  "verdict": "approved | changes_requested | unknown",
+  "strengths": ["what the change does well"],
+  "issues": {"critical": [], "important": [], "minor": []},
+  "next_actions": ["concrete fixes with file:line where possible"]
+}
+```
+
+**Triggered by:**
+- the `/gemini-plugin:gemini-consult` dispatch rule (manual). Not wired to any trigger hook.
+
+**Advisory note:** `changes_requested` surfaces inline but does not block (the verdict handler only blocks on fail/block).
+
 ## Plugin subagent constraints
 
 Per Claude Code documentation, plugin subagents:

diff --git a/hooks/hooks.json b/hooks/hooks.json
@@ -45,7 +45,7 @@
     ],
     "SubagentStop": [
       {
-        "matcher": "gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer",
+        "matcher": "gemini-validator|gemini-challenger|gemini-researcher|gemini-summarizer|gemini-reviewer",
         "hooks": [
           { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/subagent-verdict-handler.sh", "async": false }
         ]