v0.6.1

Fixed

• Done-claim validation received empty or misleading diff evidence. stop-done-claim.sh summarized the work with git diff --stat HEAD~1, which produced nothing usable in four common cases: an unborn HEAD (the first commit not yet made), a root commit (no parent, so HEAD~1 errors out), a multi-commit task (only the most recent commit was shown, hiding the rest of the work), and uncommitted changes (HEAD~1 ignores the working tree entirely). In each case the gemini-validator was handed weak evidence to audit the "done" claim against. Fixed by adding build_diff_summary() to hooks/lib/common.sh: it shows staged work on an unborn HEAD, uncommitted changes against HEAD, and the whole branch since it forked from the default branch (detected as origin/main, main, or master), falling back to HEAD~1 and then the single commit when no fork point exists.

v0.6.0

Added

• Automatic design-review pass. Whenever a design/plan artifact is written (a *-design.md spec, a *-plan.md, or a file under a specs//plans/ directory) via a new PostToolUse(Write|Edit) hook, or when native plan mode exits, the plugin asks Claude to dispatch gemini-validator (VALIDATE_DESIGN) and gemini-challenger (CHALLENGE_DESIGN) over it. The pass is advisory (findings surface but never block), deduped by file content hash so cosmetic re-edits do not re-fire, exempt from the manual one-consult-per-turn cap (it is part of the uncounted hook channel), and silenced by the existing CLAUDE_PLUGIN_GEMINI_DISABLE_HOOKS / brainstorm.off kill switch. The artifact globs are overridable via CLAUDE_PLUGIN_GEMINI_DESIGN_GLOBS.

Changed

• Verdict handling is now per-dispatch advisory-or-blocking. subagent-verdict-handler.sh reads and consumes a per-agent "pending mode" marker written by the dispatching hook. A fail/block verdict blocks (exit 2) only when the marker is blocking (the default when no marker exists, which preserves the plan-validator and done-claim gates); the design-review pass writes advisory markers so its findings never halt the flow.
• Native plan-mode exit now also runs an advisory challenger alongside the existing blocking plan-validator (the validator gate is unchanged).

v0.5.1

Fixed

• Agents stalled "hunting for the tool name" in sessions with many MCP servers. When numerous MCP servers are connected, Claude Code switches MCP tools into deferred mode: the tool name is shown in a system reminder but its schema is not loaded, so a direct call fails until the caller materializes it via ToolSearch. The five agents told themselves to "use the gemini_search_grounded tool" but never mentioned ToolSearch, so a subagent in a heavy-MCP session could not find a directly-callable Gemini tool, burned its turn budget hunting for the name, and ended mid-investigation without emitting its JSON, after which the orchestrator fell back to plain web search. This was intermittent because a light session loads the tools directly and a capable model sometimes rediscovers ToolSearch unaided. Distinct from the v0.4.1 tools:-allowlist bug and from the stale-session case gemini-doctor covers. Fixed by adding a "Deferred tools (do this FIRST)" step to each agent's "Tool availability" section: call ToolSearch with a namespace-agnostic keyword query (e.g. gemini search grounded) to load the schema, then call the exact tool name returned; treat the tool as missing only after ToolSearch returns no match.

Changed

• gemini-consult skill documents the deferred-tool path and points to /gemini-plugin:gemini-doctor when an agent returns unavailable/unknown with a missing-tool error.
• tests/mcp-namespace.bats now asserts every agent documents the ToolSearch deferred-tool step using a keyword query (not a hardcoded mcp__ path).

v0.5.0 — gemini-doctor diagnostic command

Added

• /gemini-plugin:gemini-doctor command. A one-step self-diagnostic that distinguishes a real Gemini outage from a stale session. It runs four checks:

  1. API key configured (without printing it).
  2. MCP server reachable from the main agent: resolves the grounded-search tool under the plugin namespace (mcp__plugin_gemini-plugin_gemini__*) or the manual-install namespace (mcp__gemini__*), then calls it for real.
  3. Subagent grounding path: spawns gemini-researcher and confirms it actually sees a Gemini tool and grounds (the check that catches the most common failure).
  4. On-disk plugin version (what the next fresh session will load).

  When checks 1 and 2 pass but check 3 fails, the doctor reports STALE SESSION and tells you to restart Claude Code. This is the common cause of "grounding produced nothing" reports: the MCP server works, but a session started before a plugin update still has the outdated agent definitions loaded in memory.

Upgrade note: run /plugin and update gemini-plugin to v0.5.0, then start a fresh session so the new command and current agents load.

PR #18.

v0.4.1 — MCP namespace fix + fail-loud agents

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: mcp__plugin_gemini-plugin_gemini__*), but every agent's tools: allowlist named the bare un-prefixed form (mcp__gemini__*), 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.

Upgrade note: run /plugin and update gemini-plugin to v0.4.1 to pick up this fix; the old cached install will not have it.

PR #15.

v0.4.0 — gemini-reviewer agent + gemini-consult dispatch rule

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. Sonnet, maxTurns 10, returns structured JSON {verdict, strengths, issues, next_actions}. Advisory: changes_requested 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.

Changed

• gemini-reviewer added to the SubagentStop matcher so its transcript is read and persisted to plan-history.

PR #14.

v0.3.0 — fix subagent partial-response failures

Fixes user-reported failures where the gemini-validator subagent (and others) were returning partial responses without delivering the final JSON verdict. The verdict-handler hook then had nothing to parse and the validation was silently lost.

Root cause

Three combining factors: tight maxTurns budgets, under-spec'd models for structured-output workloads, and a system prompt that didn't structurally enforce the JSON-only final-turn rule.

Per-user direction: double maxTurns, bump model tier

Agent	Old model	New model	Old maxTurns	New maxTurns
gemini-validator	haiku	sonnet	3	6
gemini-challenger	sonnet	opus	4	8
gemini-researcher	haiku	sonnet	6	12
gemini-summarizer	sonnet	opus	2	4

System prompts now include explicit turn-budget plans reserving the final turn for JSON emission only.

Cost impact

Sonnet/Opus per call is ~4-5x Haiku/Sonnet. Combined with v0.2.0's brainstorm-on-by-default (researcher fires on every prompt), expect 5-10x higher Gemini-side cost per session vs v0.1.3.

Mitigation: /gemini-plugin:gemini-brainstorm-off reduces researcher invocations to keyword-matching prompts only.

How to update

/plugin marketplace update synthforge
/plugin install gemini-plugin@synthforge

Full changelog

https://github.com/azmym/gemini-plugin/blob/main/CHANGELOG.md#030---2026-05-28

v0.2.0 — brainstorming on by default

Per user request, this release makes Gemini grounding fire on every prompt by default rather than only on prompts matching the narrow keyword regex.

Behavior change

Before (v0.1.x): the grounding hook only fired when a prompt matched patterns like latest version of X or CVE-YYYY-NNN. Brainstorming mode was opt-in via a brainstorm.lock file.

After (v0.2.0): every prompt triggers a gemini-researcher consultation by default. To opt out and fall back to keyword-only grounding, run:

/gemini-plugin:gemini-brainstorm-off

To re-enable the default after opting out:

/gemini-plugin:gemini-brainstorm-on

Cost note

Per-prompt grounding catches stale-training-data answers but adds a Gemini call (Haiku, fast and cheap, but still real) to every prompt. Use /gemini-plugin:gemini-brainstorm-off if you want to control cost or reduce latency on chatty sessions.

Migration from v0.1.x

If you had brainstorm.lock set in v0.1.x, you can delete it (it's a no-op now). If you want LESS grounding than the new default, run /gemini-plugin:gemini-brainstorm-off once.

How to update

/plugin marketplace update synthforge
/plugin install gemini-plugin@synthforge

Full changelog

https://github.com/azmym/gemini-plugin/blob/main/CHANGELOG.md#020---2026-05-28

v0.1.3 — hook event/exit-code contract alignment

Hot-fix release for hook-event/exit-code mismatches found by an audit of every hook against the official Claude Code hooks documentation. The visible symptom in v0.1.2 was a wall-of-text "UserPromptSubmit operation blocked by hook" message on prompts containing common operational words (release, app, api, etc).

Root cause

Different hook events have different exit 2 semantics. We had used exit 2 + stderr everywhere. Five of seven hooks were wrong:

Hook	What exit 2 actually does	What we now use
UserPromptSubmit	Blocks prompt and erases it; stderr shown to user	exit 0 + JSON additionalContext
PreToolUse(Bash) (destructive)	Blocks tool; stderr to Claude	exit 0 + JSON permissionDecision: deny + additionalContext
PreToolUse(ExitPlanMode) (plan validation)	Blocks plan exit	exit 0 + JSON additionalContext (plan still reaches user; validator runs alongside)
PreCompact	Blocks compaction; stderr to user	exit 0 + JSON additionalContext (no longer blocks compaction)
Stop	Prevents stopping; stderr to Claude	exit 0 + JSON decision: block + reason + additionalContext

SessionStart was already correct from v0.1.2. SubagentStop keeps exit 2 + stderr because it is the documented correct pattern there.

Bonus fix: narrower keyword regex

The old user-prompt-grounding.sh regex matched bare \brelease\b, \bapp\b, \bapi\b. Operational prompts like:

release="mss-cart-service", app="mss-cart-service-app"

triggered the grounding hook unnecessarily. The new regex requires contextual phrases that strongly imply post-cutoff questions:

• latest|newest|current|recent (version|release|stable)
• version of X
• CVE-YYYY-NNN
• changelog for X
• deprecated in X
• breaking change in X
• security advisory

Other improvements

• All hooks now have trap ... ERR so any future failure writes a diagnostic to stderr instead of crashing silently with the cryptic "No stderr output" message
• POSIX ERE regex (no \d, no \s) for cross-platform compatibility (caught by Linux CI)
• 73 tests passing on Ubuntu and macOS (4 new regression tests)

How to update

/plugin marketplace update synthforge
/plugin install gemini-plugin@synthforge

The "blocked by hook" wall of text will stop appearing.

Full changelog

https://github.com/azmym/gemini-plugin/blob/main/CHANGELOG.md#013---2026-05-28

v0.1.2 — SessionStart hook hot-fix

Hot-fix release for the SessionStart:startup hook error: Failed with non-blocking status code: No stderr output error reported in real session startup. v0.1.1 was correct in isolation (all tests passed) but broke at the integration boundary when Claude Code spawned the hook.

Three combining bugs

1. set -u crash on ${CLAUDE_PLUGIN_DATA}. The session-start and verdict-handler hooks referenced this env var directly. When unset, set -u crashed the script with "unbound variable", non-zero exit, and no stderr.
2. Wrong exit-code convention for SessionStart. Per the Claude Code hooks docs, SessionStart does not honor exit 2 as a block signal. The supported way to inject context is exit 0 with the directive on stdout (where it becomes additionalContext for the session). Even on success, users saw a misleading "hook error" line.
3. No error trap. set -euo pipefail aborted on any internal failure with no message, producing the cryptic "No stderr output" error.

What's in this release

• New data_dir() helper in lib/common.sh that returns CLAUDE_PLUGIN_DATA when set, falling back to ~/.claude/plugins/data/gemini-plugin/. State now survives reboots and never lands in /tmp.
• session-start-risk-map.sh: switched from exit 2 + stderr to exit 0 + stdout. Added trap ... ERR so any future crash writes a diagnostic line instead of vanishing silently.
• subagent-verdict-handler.sh: same data_dir() migration and trap ... ERR.
• New regression test: session-start: does not crash when CLAUDE_PLUGIN_DATA is unset. Total: 70 tests, all passing on Ubuntu and macOS CI.

How to update

/plugin marketplace update synthforge
/plugin install gemini-plugin@synthforge

The error will stop appearing on session start.

Full changelog

https://github.com/azmym/gemini-plugin/blob/main/CHANGELOG.md#012---2026-05-28