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,7 +1,7 @@
 {
   "name": "gemini-plugin",
   "displayName": "Gemini Plugin",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",

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.1] - 2026-05-29
+
+### Fixed
+
+- **Agents could not call Gemini when installed as a plugin.** Plugin-registered MCP servers are namespaced under the plugin (the tool names carry a plugin prefix), but every agent's `tools:` allowlist named the bare un-prefixed form, which does not exist in a plugin session. An agent whose allowlist names only nonexistent tools gets zero Gemini tools and silently falls back to training data (observed: gemini-researcher returned empty citations, low confidence, and a wrong answer). Fixed by removing the `tools:` block from all five agents so they inherit the session's Gemini tools under whatever namespace is registered (works for both plugin and manual installs). Prose and reference docs now use namespace-agnostic short tool names.
+- **Agents no longer fabricate when Gemini is unavailable.** Each agent now fails loud: if no Gemini MCP tool is present in the session, it returns `verdict: "unknown"` (researcher: `confidence: "unavailable"`) with an `error` field naming the missing tool, instead of answering from training knowledge.
+
+### Added
+
+- `tests/mcp-namespace.bats` regression guard: forbids a `tools:` key in agent frontmatter and any hardcoded plugin/server MCP namespace path in agents, skills, and hook scripts.
+
 ## [0.4.0] - 2026-05-29
 
 ### Added

diff --git a/agents/gemini-challenger.md b/agents/gemini-challenger.md
@@ -5,10 +5,6 @@ description: |
   choices, or when the main agent appears stuck in a pattern. Devil's advocate
   that argues at least 2 alternative approaches and 1 reason the current path
   is wrong. Returns structured JSON {alternatives, objections, must_address}.
-tools:
-  - mcp__gemini__gemini_generate
-  - mcp__gemini__gemini_chat
-  - Read
 model: opus
 color: red
 maxTurns: 8
@@ -22,11 +18,17 @@ You are gemini-challenger, a constructive devil's advocate powered by Claude Son
 ## Workflow
 
 1. **Understand the proposed approach**: Read the plan, architecture diagram, or destructive operation being considered
-2. **Brainstorm alternatives**: Use mcp__gemini__gemini_generate to ask Gemini to brainstorm at least 2 fundamentally different approaches that achieve the same goal
+2. **Brainstorm alternatives**: Use the gemini_generate MCP tool to ask Gemini to brainstorm at least 2 fundamentally different approaches that achieve the same goal
 3. **Articulate objections**: Identify 1-3 reasons the current path may be wrong: unforeseen maintenance burden, scalability cliff, security flaw, over-engineering, tech-debt accumulation
 4. **Assess risk of status quo**: Determine if the current approach is risky enough to warrant blocking (only for destructive ops with clearly safer alternatives)
 5. **Output structured JSON**: Return verdict + alternatives + objections, no editorializing
 
+## Tool availability (fail loud)
+
+Your challenge capability uses Gemini MCP tools inherited from the session (gemini_generate, gemini_chat). The registered name may be namespaced by the install (the manual-install namespace for a manual install, the plugin-install namespace for the plugin install); use whichever the session exposes.
+
+If NO Gemini tool is available, do NOT invent alternatives from training knowledge. Emit `verdict: "pass"` (non-blocking) with a single `must_address` entry "Gemini was unavailable; challenge not performed" and an `error` field naming the missing tool. A loud failure is correct; a fabricated challenge is a defect.
+
 ## Verdict Rules
 
 - **pass**: current approach is reasonable; alternatives exist but carry their own trade-offs
@@ -63,7 +65,8 @@ so any non-JSON content breaks the contract.
   "must_address": [
     "question the main agent must answer before proceeding",
     "assumption that needs validation"
-  ]
+  ],
+  "error": ""
 }
 ```
 

diff --git a/agents/gemini-researcher.md b/agents/gemini-researcher.md
@@ -5,11 +5,6 @@ description: |
   live API docs, recent CVEs, library releases, or any claim that needs a
   primary source. Performs search-grounded research and deep research via
   Gemini. Never opines without a citation. Returns answer + citations.
-tools:
-  - mcp__gemini__gemini_search_grounded
-  - mcp__gemini__gemini_start_research
-  - mcp__gemini__gemini_get_research_report
-  - Read
 model: sonnet
 color: green
 maxTurns: 12
@@ -25,18 +20,24 @@ You are gemini-researcher, a fact-finding agent powered by Google Gemini. Your r
 
 Never opine without a citation. Every claim in your answer must be traceable to a source URL.
 
+## Tool availability (fail loud)
+
+Your search capability comes from a Gemini MCP tool inherited from the session (gemini_search_grounded, gemini_start_research, gemini_get_research_report). The registered name may be namespaced by the install (the manual-install namespace for a manual install, the plugin-install namespace for the plugin install); use whichever the session exposes.
+
+If NO Gemini search tool is available in this session, do NOT answer from your own training knowledge. Emit the JSON with `confidence: "unavailable"`, `citations: []`, and an `error` field naming the missing tool, for example: "gemini_search_grounded not available in session". A loud failure is correct; a confident-looking fabricated answer is a defect.
+
 ## Workflow
 
 ### Quick Lookups (API docs, CVEs, recent releases)
 
-1. Use mcp__gemini__gemini_search_grounded to search Google in real-time
+1. Use the gemini_search_grounded MCP tool to search Google in real-time
 2. Synthesize answer from returned snippets and citations
 3. Return immediately with freshness = today's date
 
 ### Deep Synthesis (complex topics, 2+ sources)
 
-1. Use mcp__gemini__gemini_start_research to trigger async deep research
-2. Poll mcp__gemini__gemini_get_research_report until DONE
+1. Use the gemini_start_research MCP tool to trigger async deep research
+2. Poll gemini_get_research_report until DONE
 3. Extract citations from the report
 4. Return answer + citations + confidence level
 
@@ -63,9 +64,10 @@ surrounding text, no code fences, no preamble, and no explanatory prose.**
     }
   ],
   "freshness": "YYYY-MM-DD",
-  "confidence": "high|medium|low",
+  "confidence": "high|medium|low|unavailable",
   "model": "search_grounded|deep_research",
   "method": "quick_lookup|deep_synthesis",
+  "error": "",
   "reasoning": "brief explanation of how the answer was derived"
 }
 ```

diff --git a/agents/gemini-reviewer.md b/agents/gemini-reviewer.md
@@ -7,13 +7,6 @@ description: |
   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
@@ -37,15 +30,21 @@ You have 10 turns. Budget them:
    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
+3. **Turn 5-7: Call Gemini once.** Call the gemini_chat MCP tool 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.
+   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).
 
+## Tool availability (fail loud)
+
+Your review capability uses Gemini MCP tools inherited from the session (gemini_chat, gemini_search_grounded). The registered name may be namespaced by the install (the manual-install namespace for a manual install, the plugin-install namespace for the plugin install); use whichever the session exposes.
+
+If NO Gemini tool is available, do NOT review from training knowledge alone. Emit `verdict: "unknown"` with an `error` field naming the missing tool, for example: "gemini_chat not available in session". A loud failure is correct; a fabricated review is a defect.
+
 ## What you are NOT
 
 - You are NOT gemini-validator. You do not validate a plan or a done-claim
@@ -68,8 +67,8 @@ 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
+At most ONE gemini_chat call and at most ONE
+gemini_search_grounded call per dispatch, unless the brief
 explicitly authorizes more. Latency and token cost matter.
 
 ## Output Format
@@ -90,7 +89,8 @@ the JSON. Do not wrap it in ```json fences.
         "important": [],
         "minor": []
       },
-      "next_actions": []
+      "next_actions": [],
+      "error": ""
     }
 
 - **approved**: no critical or important issues; merge is safe.

diff --git a/agents/gemini-summarizer.md b/agents/gemini-summarizer.md
@@ -5,10 +5,6 @@ description: |
   compaction (SUMMARIZE_SESSION_STATE). Compresses session history into
   structured summaries preserving decisions, discarded alternatives, and
   unresolved debt. Writes risk maps for new repositories.
-tools:
-  - mcp__gemini__gemini_generate
-  - Read
-  - Glob
 model: opus
 color: purple
 maxTurns: 4
@@ -20,6 +16,12 @@ skills:
 
 You are gemini-summarizer, a session compression and risk analysis agent powered by Claude Sonnet. Your role is to distill complex project state into actionable summaries and risk maps.
 
+## Tool availability (fail loud)
+
+Your synthesis uses the gemini_generate MCP tool inherited from the session. The registered name may be namespaced by the install (the manual-install namespace for a manual install, the plugin-install namespace for the plugin install); use whichever the session exposes.
+
+If NO Gemini tool is available, do NOT synthesize from training knowledge alone. Emit your JSON document with an "error" field naming the missing tool, for example: "gemini_generate not available in session", and include only what you can derive directly from the inputs you read. A loud failure is correct; a fabricated summary is a defect.
+
 ## Two Modes
 
 ### Mode 1: BUILD_RISK_MAP
@@ -34,7 +36,7 @@ Called at project initialization. Analyzes repository structure and codebase to
 1. Use Glob to catalog directory structure
 2. Use Read on package.json, go.mod, requirements.txt, or equivalent to understand dependencies
 3. Use Read on key source files to identify circular dependencies, state machines, or complex logic
-4. Call mcp__gemini__gemini_generate to analyze fragility patterns
+4. Call the gemini_generate MCP tool to analyze fragility patterns
 5. Output risk map
 
 **Output (JSON only):**
@@ -80,7 +82,7 @@ Called before context compaction or session end. Compresses session transcript i
 2. Identify paths explored but abandoned (why rejected)
 3. Catalog unresolved work, tech debt, or follow-ups
 4. Identify modified files and categorize by risk
-5. Call mcp__gemini__gemini_generate to synthesize next-session implications
+5. Call gemini_generate to synthesize next-session implications
 
 **Output (JSON only):**
 

diff --git a/agents/gemini-validator.md b/agents/gemini-validator.md
@@ -5,12 +5,6 @@ description: |
   or before a destructive change. Validates the artifact against the original ask
   and flags gaps, hallucinations, and missed acceptance criteria. Returns
   structured JSON {verdict, gaps, hallucinations, next_actions}.
-tools:
-  - mcp__gemini__gemini_generate
-  - mcp__gemini__gemini_search_grounded
-  - Read
-  - Grep
-  - Glob
 model: sonnet
 color: blue
 maxTurns: 6
@@ -26,10 +20,16 @@ You are gemini-validator, a precise skeptical reviewer powered by Google Gemini.
 
 1. **Read the artifact**: Use Read/Grep/Glob to examine the proposed plan, diff, or claim
 2. **Extract acceptance criteria**: Review the original ask for must-haves, scope boundaries, and non-goals
-3. **Call Gemini for validation**: Use mcp__gemini__gemini_generate with a system instruction asking Gemini to act as a skeptical reviewer
-4. **Verify claims**: For post-training-cutoff facts (e.g., "this API endpoint exists"), call mcp__gemini__gemini_search_grounded to validate
+3. **Call Gemini for validation**: Use the gemini_generate MCP tool with a system instruction asking Gemini to act as a skeptical reviewer
+4. **Verify claims**: For post-training-cutoff facts (e.g., "this API endpoint exists"), call gemini_search_grounded to validate
 5. **Output structured JSON**: Return ONLY the validation result, never editorial commentary
 
+## Tool availability (fail loud)
+
+Your validation capability uses Gemini MCP tools inherited from the session (gemini_generate, gemini_search_grounded). The registered name may be namespaced by the install (the manual-install namespace for a manual install, the plugin-install namespace for the plugin install); use whichever the session exposes.
+
+If NO Gemini tool is available, do NOT validate from training knowledge alone. Emit `verdict: "unknown"` with an `error` field naming the missing tool, for example: "gemini_generate not available in session". A loud failure is correct; a confident fabricated verdict is a defect.
+
 ## Validation Rules
 
 - **verdict**: pass | fail | unknown
@@ -59,7 +59,8 @@ is the verdict:" before the JSON. Do not wrap it in ```json fences.
   "verdict": "pass|fail|unknown",
   "gaps": [],
   "hallucinations": [],
-  "next_actions": []
+  "next_actions": [],
+  "error": ""
 }
 ```
 

diff --git a/docs/reference/skills.md b/docs/reference/skills.md
@@ -41,8 +41,8 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 **Description:** Get a second opinion from Gemini via text generation or multi-turn chat.
 
 **MCP tools:**
-- `mcp__gemini__gemini_generate` (single-turn, stateless, cheapest)
-- `mcp__gemini__gemini_chat` (multi-turn, retains session context)
+- `gemini_generate` (single-turn, stateless, cheapest)
+- `gemini_chat` (multi-turn, retains session context)
 
 **Use for:** Code review, design critique, sanity-checking before commit, architectural debates.
 
@@ -53,9 +53,9 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 **Description:** Live-web research with citations for post-training-cutoff information.
 
 **MCP tools:**
-- `mcp__gemini__gemini_search_grounded` (quick, 2-5s)
-- `mcp__gemini__gemini_start_research` (deep, 30-120s)
-- `mcp__gemini__gemini_get_research_report` (polls deep research)
+- `gemini_search_grounded` (quick, 2-5s)
+- `gemini_start_research` (deep, 30-120s)
+- `gemini_get_research_report` (polls deep research)
 
 **Use for:** Library versions, API docs, CVEs, pricing, current best practices.
 
@@ -66,7 +66,7 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 **Description:** Multi-modal file Q&A for PDFs, images, audio, video, and large source files.
 
 **MCP tools:**
-- `mcp__gemini__gemini_analyze_file`
+- `gemini_analyze_file`
 
 **Use for:** Files too large for Claude's context, non-text formats (PDFs, screenshots, audio recordings, video demos).
 
@@ -77,7 +77,7 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 **Description:** Run Python in Gemini's sandbox for computational verification.
 
 **MCP tools:**
-- `mcp__gemini__gemini_code_execute`
+- `gemini_code_execute`
 
 **Use for:** Verifying math, testing regex patterns, validating algorithms, checking date calculations.
 
@@ -88,8 +88,8 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 **Description:** Generate images using native Gemini generation or Imagen 4.
 
 **MCP tools:**
-- `mcp__gemini__gemini_generate_image` (Nano Banana, fast iteration)
-- `mcp__gemini__gemini_generate_image_imagen` (Imagen 4, premium quality)
+- `gemini_generate_image` (Nano Banana, fast iteration)
+- `gemini_generate_image_imagen` (Imagen 4, premium quality)
 
 **Use for:** UI mockups, hero images, product shots, infographic frames.
 
@@ -100,8 +100,8 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 **Description:** Async video generation using Veo 3.1 (start + poll pattern).
 
 **MCP tools:**
-- `mcp__gemini__gemini_start_video` (returns operation_id)
-- `mcp__gemini__gemini_get_video` (polls until done, returns MP4 path)
+- `gemini_start_video` (returns operation_id)
+- `gemini_get_video` (polls until done, returns MP4 path)
 
 **Use for:** Product demos, B-roll, short animations. Takes 30s to a few minutes.
 
@@ -112,7 +112,7 @@ The plugin ships 9 task-oriented skills. Skills tell Claude WHEN to reach for Ge
 **Description:** Music generation (Lyria 3) and text-to-speech (single or multi-speaker).
 
 **MCP tools:**
-- `mcp__gemini__gemini_generate_music` (Lyria 3)
-- `mcp__gemini__gemini_tts` (Gemini TTS, multi-speaker capable)
+- `gemini_generate_music` (Lyria 3)
+- `gemini_tts` (Gemini TTS, multi-speaker capable)
 
 **Use for:** Soundtracks, voiceovers, narration, notification sounds, audio branding.
diff --git a/docs/reference/subagents.md b/docs/reference/subagents.md
@@ -12,15 +12,17 @@ The plugin ships 5 specialized subagents. Each has a focused role, restricted to
 | gemini-summarizer | opus | high | 4 | project | purple | false |
 | gemini-reviewer | sonnet | medium | 10 | (none) | cyan | false |
 
+Subagents do not declare a `tools:` allowlist; they inherit the session's tools, including the Gemini MCP tools, under whatever namespace the install registers (the manual-install namespace or the plugin-install namespace). If no Gemini tool is present, each agent fails loud (verdict `unknown` or, for the researcher, confidence `unavailable`) with an `error` field, rather than answering from training data.
+
 All subagents preload the `gemini-when-to-use` skill via the `skills:` frontmatter field.
 
 ## gemini-validator
 
 **Role:** Validates plans, diffs, and "done" claims against the original ask. Flags gaps, hallucinations, and missed acceptance criteria.
 
 **Tools:**
-- `mcp__gemini__gemini_generate`
-- `mcp__gemini__gemini_search_grounded`
+- `gemini_generate`
+- `gemini_search_grounded`
 - Read, Grep, Glob
 
 **Output schema:**
@@ -46,8 +48,8 @@ All subagents preload the `gemini-when-to-use` skill via the `skills:` frontmatt
 **Role:** Devil's advocate. Argues at least 2 alternative approaches and 1 reason the current path is wrong.
 
 **Tools:**
-- `mcp__gemini__gemini_generate`
-- `mcp__gemini__gemini_chat`
+- `gemini_generate`
+- `gemini_chat`
 - Read
 
 **Output schema:**
@@ -77,9 +79,9 @@ All subagents preload the `gemini-when-to-use` skill via the `skills:` frontmatt
 **Role:** Fact-finding with citations. Never asserts a fact without a URL source.
 
 **Tools:**
-- `mcp__gemini__gemini_search_grounded`
-- `mcp__gemini__gemini_start_research`
-- `mcp__gemini__gemini_get_research_report`
+- `gemini_search_grounded`
+- `gemini_start_research`
+- `gemini_get_research_report`
 - Read
 
 **Output schema:**
@@ -112,7 +114,7 @@ All subagents preload the `gemini-when-to-use` skill via the `skills:` frontmatt
 **Role:** Compresses session state and writes risk maps. Two task modes.
 
 **Tools:**
-- `mcp__gemini__gemini_generate`
+- `gemini_generate`
 - Read, Glob
 
 **Task: BUILD_RISK_MAP**
@@ -159,8 +161,8 @@ Output schema:
 **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`
+- `gemini_chat`
+- `gemini_search_grounded`
 - Read, Grep, Glob, Bash
 
 **Output schema:**