v1.2.0 - pluggable backends, approval mode, native sessions, Windows reliability, timeouts, tests

[jamubc]

Summary

First feature release after the 1.1.6 security patch. It hardens cross-platform execution, adds an opt-in safety control and native multi-turn sessions, a configurable default model, a setup doctor, and a real test suite — and it makes the CLI backend pluggable, preparing for the Gemini CLI retirement on 2026-06-18 (free/Pro/Ultra tiers) in favour of the Antigravity CLI (agy).

No default behaviour changes for existing users. Closes #49.

What's new

• Pluggable backends (src/backends/). The executor is now backend-agnostic. The Gemini CLI stays the default; set GEMINI_MCP_BACKEND=agy to use the experimental Antigravity CLI backend. agy print-mode is Flash-only, and because agy -p has an empty-stdout bug in 1.0.x we fall back to reading agy's transcript files — verified end-to-end locally.
• Configurable default model — GEMINI_MODEL pins the model used when a call doesn't pass one, so the assistant can't silently fall back to an older model (Hope to be able to specify the model in MCP json settings #49; also helps Please update default to gemini-3-pro-preview #51). GEMINI_FLASH_MODEL overrides the quota-fallback target. Precedence: per-call model arg → GEMINI_MODEL → Gemini CLI default.
• Setup doctor — npm run doctor (or the gemini-mcp-doctor bin / npx -p gemini-mcp-tool gemini-mcp-doctor) reports the active backend, detected gemini/agy installs (path + version), and your effective model/approval/timeout/env configuration with actionable hints. Self-contained, zero-dependency.
• Approval mode — approvalMode arg on ask-gemini/brainstorm (+ GEMINI_MCP_APPROVAL_MODE), forwarding gemini --approval-mode {default,auto_edit,yolo,plan}. Opt-in (see note below).
• Native multi-turn sessions — sessionId/resume forward gemini --session-id/--resume (agy --conversation/--continue); the requested session id is echoed back, using the CLI's own sessions rather than local transcript storage.
• Windows executable resolution — honours GEMINI_CLI_PATH, else resolves the real gemini shim via where (preferring .cmd/.exe/.bat), fixing "command not found" when the server doesn't inherit your shell PATH.
• Per-command timeout — hung calls are terminated (SIGTERM→SIGKILL on POSIX; taskkill /T on Windows), GEMINI_MCP_TIMEOUT_MS (default 30m, 0 disables).
• Help fix — calls gemini --help instead of -help (yargs mis-parsed it as -h -e -l -p).
• Version & DX — version read from package.json at runtime (was hardcoded, stale at 1.1.4); engines.node → >=18; prepare script for Git-checkout installs.
• Docs — README gains Environment Variables + Setup Doctor sections; the docs site documents every 1.2.0 env var, the model config, and the doctor.
• Test suite — node:test coverage for the @file guard, Windows quoting/resolution, approval-mode/model/session arg building, backend selection, and timeout parsing. tsconfig.build.json keeps tests type-checked but out of the published dist/.

Note: approval mode is opt-in, not defaulted to plan

Defaulting --approval-mode plan was considered but rejected. In headless -p mode plan turns Gemini into an autonomous planner — for a trivial prompt it ignored the question, started exploring the repo, and errored with Invalid stream: empty response or malformed tool call. Both no flag (today's behaviour) and --approval-mode default answer cleanly. So approval mode is left unset by default and a mode is only forwarded when the caller asks for one.

Testing

• npm run build (clean) · npm run lint (type-checks tests too) · npm test → 18 passing.
• Manual smoke against gemini (basic Q&A, --help), the agy backend, and npm run doctor (default + env-override + invalid-value paths).

Review feedback

All five findings from the gemini-code-assist and Copilot bot reviews were addressed in 4c9b9b3 (stdin EPIPE guard, Windows taskkill process-tree kill, .cmd/.exe/.bat resolver ordering, tsx loader feature-detect, and the session-id echo no longer emitting latest).

Related / out of scope

• Builds on feat(windows): stdin prompt passing + windowsHide (harvested from #27) #77 (Windows stdin/windowsHide) and feat: expose session ID in ask-gemini response and improve command ex… #50 (native session id). Complements the 1.1.6 security fixes (release: v1.1.6 — emergency CVE-2026-0755 security patch #76, fix(security): path-traversal guards for fetch-chunk and chunkCache (CWE-22) #72, Fix spawn EINVAL on Windows + Node 22+ for .cmd shims #69).
• Separate follow-ups: Modernise MCP stack, improve stability, and preserve Gemini CLI OAuth #65 (SDK modernization), Add performance optimizations and LRU caching #44 (LRU cache), feat: add MCP tool annotations to all 6 tools #46 (tool annotations), feat: Add Gemini compatibility mode #35 (schema-compat); --output-format stream-json real streaming; promoting the agy backend from experimental once agy -p stdout is fixed upstream.

[gemini-code-assist]

Code Review

This pull request upgrades the server to version 1.2.0, introducing pluggable backends (Gemini CLI and experimental Antigravity CLI), native multi-turn sessions, approval modes, a per-command timeout mechanism, and a comprehensive test suite. It also hardens Windows execution by passing complex prompts via stdin and resolving executable shims. Feedback was provided to prevent potential server crashes by handling stdin write errors, and to ensure that timed-out processes on Windows are fully terminated along with their child trees rather than leaving orphaned background processes.

[Copilot]

Pull request overview

This PR is a v1.2.0 feature release that refactors CLI execution to support pluggable backends (Gemini CLI + experimental Antigravity agy), adds opt-in approval modes and native multi-turn session flags, improves Windows reliability, introduces per-command timeouts, and adds a real node:test-based test suite.

Changes:

• Introduces a backend abstraction (src/backends/*) and routes executeGeminiCLI() through the selected backend (GEMINI_MCP_BACKEND).
• Adds approval/session CLI flag plumbing and Windows reliability improvements (stdin routing for complex prompts, executable resolution, windowsHide).
• Adds timeout management + a test runner and updates build/test packaging (new tsconfig.build.json, npm test runs real tests).

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tsconfig.build.json	Build-only tsconfig excluding tests/scripts from dist/.
src/utils/timeoutManager.ts	Adds env-driven per-command timeout parsing.
src/utils/timeoutManager.test.ts	Unit tests for timeout parsing behavior.
src/utils/geminiExecutor.ts	Refactors execution to a backend-driven model; stdin routing for complex prompts; adds options object.
src/utils/geminiExecutor.test.ts	Tests for @file containment guard.
src/utils/commandExecutor.ts	Adds Windows executable resolution, stdin support, ENOENT guidance, and per-command timeout kill logic.
src/utils/commandExecutor.test.ts	Tests for cmd quoting, resolution no-op off Windows, and ENOENT guidance text.
src/tools/simple-tools.ts	Uses CLI constants for echo and fixes Help tool to use --help.
src/tools/brainstorm.tool.ts	Adds approvalMode arg and forwards execution via new executeGeminiCLI options.
src/tools/ask-gemini.tool.ts	Adds approvalMode + session args; forwards via options object; appends session note.
src/index.ts	Reads server version from package.json at runtime.
src/constants.ts	Adds approval modes, env var names, and new CLI flags/commands.
src/backends/types.ts	Defines backend interface + run options.
src/backends/index.ts	Implements backend selection via GEMINI_MCP_BACKEND.
src/backends/index.test.ts	Tests backend selection logic.
src/backends/gemini.ts	Gemini backend implementation incl. approval/session args and Flash fallback on quota exhaustion.
src/backends/gemini.test.ts	Tests approval-mode resolution + arg building.
src/backends/agy.ts	Experimental Antigravity CLI backend with transcript-based output recovery.
src/backends/agy.test.ts	Tests agy arg mapping.
SECURITY-REPORT-2026-05-28.md	Adds security audit report document.
scripts/run-tests.mjs	Adds a test discovery + execution script for node:test with tsx.
package.json	Bumps version to 1.2.0; adds real tests, build config, prepare script; raises Node floor to >=18.
CHANGELOG.md	Documents 1.2.0 release notes and clarifies 1.1.6 entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.