@rethunk/mcp-multi-root-git 2.5.0 → 2.6.0

package/AGENTS.md

@@ -48,7 +48,7 @@ IDEs injecting this as context: do not re-link from rules.
 ## Changing contracts
 
 - **No banner paragraphs** in shipped docs. Use normal titles + cross-links.
-- **JSON format version** (currently `"3"`, discoverable via MCP `initialize`): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false. v3 changes in `git_log`: `sha7` → `sha` (full SHA), `workspace_root` → `workspaceRoot`, `ageRelative` removed, `email` omitted when empty.
+- **JSON format version** (currently `"3"`, exported as `MCP_JSON_FORMAT_VERSION` in `src/server.ts` and surfaced via the FastMCP `instructions` field — discoverable from the MCP `initialize` response): bump on incompatible JSON changes (renamed/nested/omitted fields). Document migration here + [docs/mcp-tools.md](docs/mcp-tools.md). v2 removed the `rethunkGitMcp` envelope; payloads are minified; optional fields omitted when empty/null/false. v3 changes in `git_log`: `sha7` → `sha` (full SHA), `workspace_root` → `workspaceRoot`, `ageRelative` removed, `email` omitted when empty.
 - **Preset file:** keep `presets.ts` Zod schemas aligned with [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json).
 - **Public tool surface:** rename/add → update [docs/mcp-tools.md](docs/mcp-tools.md) + [README.md](README.md) (if mentioned), then regenerate the shipped schema artifacts (`tool-parameters.schema.json`, `schemas/index.json`, `schemas/*.json`). Install/client wiring → [docs/install.md](docs/install.md) only.
 
@@ -66,7 +66,7 @@ Rules for LLMs operating in or against this repository.
 
 **End-user Git/MCP preference** (status/log/diff/commits): **`~/.claude/CLAUDE.md`** § **Git & GitHub** — same policy when dogfooding this server from a harness.
 
-**Mutating tools require workspace-root confirmation** — `git_fetch`, `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_reset_soft`, `git_tag`, and `git_stash_apply` operate only on roots confirmed by `requireGitAndRoots` / `requireSingleRepo`. Never pass caller-supplied absolute paths to mutating tools; use `workspaceRoot` or MCP roots.
+**Mutating tools use `workspaceRoot` as trusted operator input** — `git_fetch`, `batch_commit`, `git_push`, `git_merge`, `git_cherry_pick`, `git_reset_soft`, `git_tag`, and `git_stash_apply` operate on roots resolved via `requireGitAndRoots` / `requireSingleRepo`. Pass the target repo as `workspaceRoot` (trusted caller input) or via MCP roots. The `absoluteGitRoots` bulk multi-root parameter is not accepted by mutating tools — passing it is rejected.
 
 **`batch_commit` atomic staging — single call per logical change** — Do NOT attempt incremental staging across multiple `batch_commit` calls. Each call is self-contained: it stages all files in all entries, commits them sequentially, and the moment the call completes, all commits have landed. Include all related files (for all related commit entries) in a single `batch_commit` call. A call cannot be resumed or extended by a later call — each is an independent transaction. If entry N fails, entries before N remain committed; entries after N are skipped (not rolled back).
 
@@ -76,7 +76,7 @@ Rules for LLMs operating in or against this repository.
 
 **Never force-push** — `git_push` has no force-push mode by design. `git_merge` with `strategy: "ff-only"` will fail cleanly rather than force.
 
-**Contract bumps need documentation** — if a JSON output shape changes incompatibly, bump `MCP_JSON_FORMAT_VERSION` in `src/server.ts` and document the migration in both this file and [docs/mcp-tools.md](docs/mcp-tools.md).
+**Contract bumps need documentation** — if a JSON output shape changes incompatibly, bump the `MCP_JSON_FORMAT_VERSION` constant in `src/server.ts` (it is surfaced in the server `instructions` field and discoverable via MCP `initialize`) and document the migration in both this file and [docs/mcp-tools.md](docs/mcp-tools.md).
 
 **Path confinement** — any tool accepting file paths must use `resolvePathForRepo` / `assertRelativePathUnderTop` from [`src/repo-paths.ts`](src/repo-paths.ts) and include escaping-attempt tests.
 

package/CHANGELOG.md

@@ -2,7 +2,30 @@
 
 All notable changes to `@rethunk/mcp-multi-root-git` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com); the project uses [Semantic Versioning](https://semver.org).
 
-## [Unreleased]
+## [2.6.0] — 2026-05-22
+
+Security-hardening and correctness release surfaced by a full-repo critical review.
+
+### Security
+
+- **Argument-injection hardening** — `git_show`, `git_log`, and `git_fetch` passed caller-supplied ref/branch/remote values straight into git argv. A value beginning with `-` is parsed by git as an option (`--output=<path>` writes an arbitrary file; `--upload-pack=<cmd>` on fetch runs a command). These read tools now validate those tokens against the argv-safe subset before invoking git, returning `unsafe_ref_token`, `unsafe_remote_token`, or `path_escapes_repo` on rejection — the same gate already applied to the mutating tools.
+- **`isProtectedBranch` normalization** — input is now normalized (trim, strip leading `refs/heads/`, lowercase) before matching, so `refs/heads/main`, `Main`, and `MAIN` are all recognized as protected. Previously the exact-name set was case-sensitive and a `refs/heads/` prefix evaded it entirely.
+
+### Fixed
+
+- **`batch_commit` linked worktrees** — hunk-level staging wrote its scratch patch under `${gitTop}/.git/`, which fails with `ENOTDIR` in a linked worktree (where `.git` is a file). The scratch path is now resolved via `git rev-parse --absolute-git-dir`, correct for both normal repos and worktrees.
+- **`batch_commit` dry run** — preview cleanup ran an unconditional `git reset HEAD --` over every touched path, silently unstaging work the caller had staged before invoking. A pre-staged snapshot is now taken first; cleanup resets only paths the dry run itself staged.
+- **`git_stash_list` index** — `index` was taken from the loop counter, so a malformed entry dropped by the parse guard shifted every later index and `git_stash_apply` could target the wrong stash. The index is now parsed from the canonical `stash@{N}` ref.
+- **`git_diff_summary` rename parsing** — the new path of a rename whose path contained the substring ` b/` was mis-reported because the greedy `diff --git` header regex split at the wrong point; the authoritative `rename to` body line is now used.
+- **`.gitmodules` parser** — `parseGitSubmodulePaths` matched any `path =` line regardless of INI section and ignored comments; it now tracks `[submodule]` sections and strips `;`/`#` comments.
+- **`git_inventory` / `git_parity` v3 JSON** — `workspace_root` field corrected to `workspaceRoot` (camelCase), completing the v3 contract rename already applied to `git_log`.
+
+### Changed
+
+- **`git_tag` error codes renamed** — `tag_empty` → `empty_tag_name`, `tag_unsafe` → `unsafe_tag_token`, `ref_unsafe` → `unsafe_ref_token`; consistent with the server-wide naming convention.
+- **`git_diff` multi-root parameters removed** — `absoluteGitRoots` and `allWorkspaceRoots` are no longer accepted by `git_diff`; it is now a pure single-repo tool (identical posture to `git_show`). Use `workspaceRoot` or `rootIndex` to select the target repo. `git_diff_summary` keeps single-entry `absoluteGitRoots` and drops only `allWorkspaceRoots`.
+- **`MCP_JSON_FORMAT_VERSION` constant** — `"3"` is now an exported constant in `src/server.ts` and surfaced in the FastMCP `instructions` field, making the format version discoverable from the MCP `initialize` response.
+- **CI** — the 20 published per-tool `schemas/*.json` artifacts are now drift-checked on every PR via a new `schema:individual:check` step; previously only `tool-parameters.schema.json` was gated.
 
 ## [2.5.0] — 2026-05-15
 

package/dist/server/batch-commit-tool.js

@@ -162,8 +162,14 @@ async function stageFile(gitTop, filePath, lines) {
     if (!partialPatch) {
         return { ok: false, error: "No hunks found in line range" };
     }
-    // Write partial patch to temp file in the git repo and apply it to the index
-    const tempPatchFile = `${gitTop}/.git/.mcp-patch-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`;
+    // Resolve the real git dir (works for linked worktrees where .git is a file, not a dir)
+    const gitDirResult = await spawnGitAsync(gitTop, ["rev-parse", "--absolute-git-dir"]);
+    if (!gitDirResult.ok) {
+        return { ok: false, error: (gitDirResult.stderr || gitDirResult.stdout).trim() };
+    }
+    const gitDir = gitDirResult.stdout.trim();
+    // Write partial patch to temp file in the git dir and apply it to the index
+    const tempPatchFile = `${gitDir}/.mcp-patch-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`;
     const { writeFileSync, unlinkSync } = await import("node:fs");
     writeFileSync(tempPatchFile, partialPatch, "utf8");
     const applyResult = await spawnGitAsync(gitTop, ["apply", "--cached", tempPatchFile]);
@@ -239,6 +245,18 @@ export function registerBatchCommitTool(server) {
             const gitTop = pre.gitTop;
             const results = [];
             const stagedFilesForCleanup = new Set();
+            // Snapshot already-staged paths BEFORE the preview loop so dry-run cleanup
+            // doesn't unstage files the caller had staged before invoking.
+            let preStagedPaths = new Set();
+            if (args.dryRun) {
+                const snapResult = await spawnGitAsync(gitTop, ["diff", "--cached", "--name-only"]);
+                if (snapResult.ok) {
+                    preStagedPaths = new Set(snapResult.stdout
+                        .split("\n")
+                        .map((s) => s.trim())
+                        .filter(Boolean));
+                }
+            }
             for (let i = 0; i < args.commits.length; i++) {
                 const entry = args.commits[i];
                 if (!entry)
@@ -298,10 +316,13 @@ export function registerBatchCommitTool(server) {
                     });
                     break;
                 }
-                // Track staged files for cleanup in dry-run
+                // Track staged files for cleanup in dry-run, excluding paths that were
+                // already staged before this call (so pre-existing staged state survives).
                 if (args.dryRun) {
                     for (const path of filePaths) {
-                        stagedFilesForCleanup.add(path);
+                        if (!preStagedPaths.has(path)) {
+                            stagedFilesForCleanup.add(path);
+                        }
                     }
                 }
                 // --- Dry-run mode: collect preview and unstage ---

package/dist/server/git-diff-summary-tool.js

@@ -102,6 +102,12 @@ function extractFileInfo(header, body) {
         status = "renamed";
         const fromMatch = /^rename from (.+)$/m.exec(body);
         oldPath = fromMatch?.[1];
+        // Prefer the authoritative "rename to <path>" body line over the greedy
+        // header regex split, which mis-parses paths containing the literal " b/".
+        const toMatch = /^rename to (.+)$/m.exec(body);
+        if (toMatch?.[1]) {
+            bPath = toMatch[1];
+        }
     }
     const path = status === "deleted" ? aPath : bPath;
     return { path, oldPath, status };
@@ -178,7 +184,7 @@ export function registerGitDiffSummaryTool(server) {
         annotations: {
             readOnlyHint: true,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({ allWorkspaceRoots: true }).extend({
             range: z
                 .string()
                 .optional()

package/dist/server/git-diff-tool.js

@@ -61,7 +61,10 @@ export function registerGitDiffTool(server) {
         annotations: {
             readOnlyHint: true,
         },
-        parameters: WorkspacePickSchema.extend({
+        parameters: WorkspacePickSchema.omit({
+            absoluteGitRoots: true,
+            allWorkspaceRoots: true,
+        }).extend({
             base: z
                 .string()
                 .optional()

package/dist/server/git-fetch-tool.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { spawnGitAsync } from "./git.js";
+import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
 import { jsonRespond } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
@@ -78,6 +78,13 @@ export function registerGitFetchTool(server) {
             const branch = args.branch?.trim();
             const prune = args.prune === true;
             const tags = args.tags === true;
+            // Validate remote and branch to prevent argument injection.
+            if (!isSafeGitUpstreamToken(remote)) {
+                return jsonRespond({ error: "unsafe_remote_token", remote });
+            }
+            if (branch && !isSafeGitUpstreamToken(branch)) {
+                return jsonRespond({ error: "unsafe_ref_token", branch });
+            }
             // Build git fetch command
             const fetchArgs = ["fetch"];
             if (prune) {

package/dist/server/git-inventory-tool.js

@@ -57,7 +57,7 @@ export function registerGitInventoryTool(server) {
                     const err = { error: "not_a_git_repository", path: workspaceRoot };
                     if (args.format === "json") {
                         allJson.push({
-                            workspace_root: workspaceRoot,
+                            workspaceRoot: workspaceRoot,
                             ...(upstream.mode === "fixed" ? { upstream } : {}),
                             entries: [
                                 makeSkipEntry(workspaceRoot, workspaceRoot, upstream.mode, JSON.stringify(err)),
@@ -117,7 +117,7 @@ export function registerGitInventoryTool(server) {
                 }
                 if (args.format === "json") {
                     allJson.push({
-                        workspace_root: top,
+                        workspaceRoot: top,
                         ...spreadDefined("presetSchemaVersion", presetSchemaVersion),
                         ...spreadWhen(nestedRootsTruncated, {
                             nestedRootsTruncated: true,

package/dist/server/git-log-tool.js

@@ -1,6 +1,7 @@
 import { basename } from "node:path";
 import { z } from "zod";
 import { asyncPool, GIT_SUBPROCESS_PARALLELISM, gitTopLevel, spawnGitAsync } from "./git.js";
+import { isSafeGitAncestorRef } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
 import { requireGitAndRoots } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
@@ -231,6 +232,10 @@ export function registerGitLogTool(server) {
                     return jsonRespond({ error: "invalid_paths", path: p });
                 }
             }
+            // Validate branch — reject leading-dash and other injection attempts.
+            if (args.branch && !isSafeGitAncestorRef(args.branch)) {
+                return jsonRespond({ error: "unsafe_ref_token", branch: args.branch });
+            }
             const maxCommits = Math.min(args.maxCommits ?? DEFAULT_MAX_COMMITS, MAX_COMMITS_HARD_CAP);
             // Fan out across roots.
             const jobs = pre.roots.map((rootInput) => ({ rootInput }));

package/dist/server/git-parity-tool.js

@@ -37,7 +37,7 @@ export function registerGitParityTool(server) {
                     const err = jsonRespond(errPayload);
                     if (args.format === "json") {
                         results.push({
-                            workspace_root: workspaceRoot,
+                            workspaceRoot: workspaceRoot,
                             status: "MISMATCH",
                             pairs: [{ label: "—", leftPath: "", rightPath: "", match: false, error: err }],
                         });
@@ -114,7 +114,7 @@ export function registerGitParityTool(server) {
                     }
                 }
                 results.push({
-                    workspace_root: top,
+                    workspaceRoot: top,
                     ...spreadDefined("presetSchemaVersion", parityPresetSchemaVersion),
                     status: allOk ? "OK" : "MISMATCH",
                     pairs: pairResults,

package/dist/server/git-refs.js

@@ -25,17 +25,24 @@ const PROTECTED_EXACT = new Set([
     "trunk",
     "prod",
     "production",
-    "HEAD",
+    "head",
 ]);
 const PROTECTED_PATTERN = /^(release|hotfix)[-/].+$/i;
 /** True when a branch name is on the protected list and must not be auto-deleted. */
 export function isProtectedBranch(name) {
-    const t = name.trim();
-    if (t === "")
+    // Normalize: trim whitespace, strip leading refs/heads/ prefix, then lowercase.
+    const trimmed = name.trim();
+    if (trimmed === "")
         return true;
-    if (PROTECTED_EXACT.has(t))
+    const stripped = trimmed.startsWith("refs/heads/")
+        ? trimmed.slice("refs/heads/".length)
+        : trimmed;
+    const normalized = stripped.toLowerCase();
+    if (normalized === "")
         return true;
-    return PROTECTED_PATTERN.test(t);
+    if (PROTECTED_EXACT.has(normalized))
+        return true;
+    return PROTECTED_PATTERN.test(normalized);
 }
 // ---------------------------------------------------------------------------
 // Ref/branch name validation (argv-safe subset of git's ref-format rules)

package/dist/server/git-show-tool.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
+import { assertRelativePathUnderTop, resolvePathForRepo } from "../repo-paths.js";
 import { spawnGitAsync } from "./git.js";
+import { isSafeGitAncestorRef } from "./git-refs.js";
 import { jsonRespond } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
@@ -119,7 +121,10 @@ export function registerGitShowTool(server) {
             format: true,
         })
             .extend({
-            ref: z.string().describe("Commit reference (SHA, branch, tag, or any git rev-spec)."),
+            ref: z
+                .string()
+                .min(1)
+                .describe("Commit reference (SHA, branch, tag, or any git rev-spec)."),
             path: z
                 .string()
                 .optional()
@@ -130,6 +135,15 @@ export function registerGitShowTool(server) {
             if (!pre.ok)
                 return jsonRespond(pre.error);
             const top = pre.gitTop;
+            if (!isSafeGitAncestorRef(args.ref)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.ref });
+            }
+            if (args.path !== undefined) {
+                const resolved = resolvePathForRepo(args.path, top);
+                if (!assertRelativePathUnderTop(args.path, resolved, top)) {
+                    return jsonRespond({ error: "path_escapes_repo", path: args.path });
+                }
+            }
             const result = await runGitShow({
                 top,
                 ref: args.ref,

package/dist/server/git-stash-tool.js

@@ -39,21 +39,22 @@ export function registerGitStashListTool(server) {
                 .split("\n")
                 .map((l) => l.trim())
                 .filter((l) => l.length > 0);
-            for (let i = 0; i < lines.length; i++) {
-                const line = lines[i];
-                if (line) {
-                    const parts = line.split("|");
-                    // parts[0] = stash@{N}, last part = short SHA, middle = message (may contain "|")
-                    const sha = parts[parts.length - 1];
-                    const message = parts.slice(1, -1).join("|");
-                    if (parts.length >= 3 && message && sha) {
-                        stashes.push({
-                            index: i,
-                            message,
-                            sha,
-                        });
-                    }
+            for (const line of lines) {
+                const parts = line.split("|");
+                // parts[0] = stash@{N}, last part = short SHA, middle = message (may contain "|")
+                const sha = parts[parts.length - 1];
+                const message = parts.slice(1, -1).join("|");
+                // Parse the real stash index from the canonical stash@{N} ref in parts[0].
+                const indexMatch = parts[0] ? /stash@\{(\d+)\}/.exec(parts[0]) : null;
+                if (!indexMatch || parts.length < 3 || !message || !sha) {
+                    // Malformed line — skip without affecting index tracking.
+                    continue;
                 }
+                stashes.push({
+                    index: Number(indexMatch[1]),
+                    message,
+                    sha,
+                });
             }
             if (args.format === "json") {
                 return jsonRespond({ stashes });

package/dist/server/git-tag-tool.js

@@ -72,11 +72,11 @@ export function registerGitTagTool(server) {
             const gitTop = pre.gitTop;
             const tag = args.tag.trim();
             if (!tag) {
-                return jsonRespond({ error: "tag_empty" });
+                return jsonRespond({ error: "empty_tag_name" });
             }
             // Validate tag name: no shell metacharacters
             if (!isSafeGitUpstreamToken(tag)) {
-                return jsonRespond({ error: "tag_unsafe", tag });
+                return jsonRespond({ error: "unsafe_tag_token", tag });
             }
             // Handle deletion
             if (args.delete === true) {
@@ -99,7 +99,7 @@ export function registerGitTagTool(server) {
             // Determine the ref to tag (default HEAD)
             const ref = (args.ref ?? "HEAD").trim();
             if (!isSafeGitUpstreamToken(ref)) {
-                return jsonRespond({ error: "ref_unsafe", ref });
+                return jsonRespond({ error: "unsafe_ref_token", ref });
             }
             // Get the SHA of the ref to tag
             const sha = await getRefSha(gitTop, ref);

package/dist/server/git.js

@@ -94,10 +94,23 @@ export function parseGitSubmodulePaths(gitRoot) {
         return [];
     }
     const paths = [];
-    for (const line of text.split("\n")) {
-        const m = /^\s*path\s*=\s*(.+)\s*$/.exec(line);
+    let inSubmoduleSection = false;
+    for (const rawLine of text.split("\n")) {
+        // Strip inline and whole-line comments (; and #)
+        const commentIdx = rawLine.search(/\s*[;#]/);
+        const line = commentIdx >= 0 ? rawLine.slice(0, commentIdx) : rawLine;
+        // Track INI section header
+        const sectionMatch = /^\s*\[(.+)\]\s*$/.exec(line);
+        if (sectionMatch) {
+            inSubmoduleSection = /^submodule\s+"/.test(sectionMatch[1] ?? "");
+            continue;
+        }
+        // Only collect path = lines inside a [submodule "..."] section
+        if (!inSubmoduleSection)
+            continue;
+        const m = /^\s*path\s*=\s*(.+?)\s*$/.exec(line);
         if (m?.[1])
-            paths.push(m[1].trim());
+            paths.push(m[1]);
     }
     return paths;
 }

package/dist/server.js

@@ -2,9 +2,16 @@
 import { FastMCP } from "fastmcp";
 import { readMcpServerVersion } from "./server/json.js";
 import { registerRethunkGitTools } from "./server/tools.js";
+/**
+ * JSON payload contract version. Bump on incompatible JSON output changes
+ * (renamed/nested/omitted fields). Surfaced via the FastMCP `instructions`
+ * field below, so it is discoverable in the MCP `initialize` response.
+ */
+export const MCP_JSON_FORMAT_VERSION = "3";
 const server = new FastMCP({
     name: "rethunk-git",
     version: readMcpServerVersion(),
+    instructions: `rethunk-git MCP server. JSON payload contract: format version ${MCP_JSON_FORMAT_VERSION} (minified, no envelope; optional fields omitted when empty/null/false).`,
     roots: { enabled: true },
 });
 registerRethunkGitTools(server);

package/docs/mcp-tools.md

@@ -17,7 +17,7 @@ MCP clients expose tools as `{serverName}_{toolName}`. With the server registere
 | `list_presets` | `rethunk-git_list_presets` | List preset names/counts from `.rethunk/git-mcp-presets.json`; invalid JSON/schema surface as errors. Workspace pick + `format` only (includes `absoluteGitRoots`). **Read-only.** |
 | `git_log` | `rethunk-git_git_log` | Path-filtered, time-windowed `git log` across one or more workspace roots. Returns commit history with author, date, subject, and shortstat. Args: `since`, `paths`, `grep`, `author`, `maxCommits`, `branch`, plus workspace pick args (`absoluteGitRoots` for sibling clones) + `format` (`markdown`/`json`/`oneline`). **Read-only.** |
 | `git_diff_summary` | `rethunk-git_git_diff_summary` | Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions counts, truncated to configurable line limits, with lock files/dist/vendor excluded by default. Args: `range`, `fileFilter`, `maxLinesPerFile`, `maxFiles`, `excludePatterns`, plus workspace pick args (optional single-entry `absoluteGitRoots`) + `format`. **Read-only.** |
-| `git_diff` | `rethunk-git_git_diff` | Raw diff text for a single repo. Supports unstaged, staged, or `base..head` ranges, optionally scoped to one path. Args: `base?`, `head?`, `path?`, `staged?`, plus single-repo workspace pick + `format`. **Read-only.** |
+| `git_diff` | `rethunk-git_git_diff` | Raw diff text for a single repo. Supports unstaged, staged, or `base..head` ranges, optionally scoped to one path. Args: `workspaceRoot`, `rootIndex`, `format`, `base?`, `head?`, `path?`, `staged?`. No `absoluteGitRoots` or `allWorkspaceRoots`. **Read-only.** |
 | `git_show` | `rethunk-git_git_show` | Inspect one commit or ref. Returns commit message plus diff, or file content at `path` for that ref. Args: `ref`, `path?`, plus single-repo workspace pick + `format`. **Read-only.** |
 | `git_worktree_list` | `rethunk-git_git_worktree_list` | List all worktrees (`git worktree list --porcelain`). Workspace pick + `format`. **Read-only.** |
 | `git_stash_list` | `rethunk-git_git_stash_list` | List `git stash` entries for one repo. Args: single-repo workspace pick + `format`. **Read-only.** |
@@ -259,7 +259,7 @@ Path-escape and `rev-parse` failures are reported inline in `pairs[*].error`, no
 
 ## JSON responses
 
-Tool JSON bodies are minified and contain only the payload — no `rethunkGitMcp` envelope. Current `MCP_JSON_FORMAT_VERSION` is **`"3"`**; server + format version are discoverable via MCP `initialize`. Payload keys (`groups`, `inventories`, `parity`, `roots`) are stable within a given format version. Preset-related responses may include **`presetSchemaVersion`**.
+Tool JSON bodies are minified and contain only the payload — no `rethunkGitMcp` envelope. Current `MCP_JSON_FORMAT_VERSION` is **`"3"`** (exported constant in `src/server.ts`); the version string is surfaced in the FastMCP `instructions` field and is therefore discoverable via the MCP `initialize` response. Payload keys (`groups`, `inventories`, `parity`, `roots`) are stable within a given format version. Preset-related responses may include **`presetSchemaVersion`**.
 
 The package also ships **`tool-parameters.schema.json`**, generated from the registered Zod parameter schemas via `bun run schema:tools`, plus the published **`schemas/`** directory (`schemas/index.json` + one JSON Schema per tool) via `bun run schema:individual`. Connected MCP clients should still prefer live schema discovery from `initialize` / tool listing; the shipped artifacts are for offline inspection, drift checks, and code generation.
 
@@ -282,7 +282,7 @@ To keep responses compact, **optional fields are omitted when they would be empt
 
 - Error payloads carry an `error` code string and any structured context (e.g. `preset`, `presetFile`). The old free-text `message` field is **removed** for self-describing codes (`git_not_found`, `remote_branch_mismatch`, `invalid_remote_or_branch`, `no_pairs`, `preset_not_found` *missing* case). It is retained only where it carries parse output (the `invalid_json` preset branch).
 
-**When to bump `MCP_JSON_FORMAT_VERSION` or change payload shape:** [AGENTS.md](../AGENTS.md) — *Changing contracts*.
+**When to bump `MCP_JSON_FORMAT_VERSION` or change payload shape:** [AGENTS.md](../AGENTS.md) — *Changing contracts*. The constant lives in `src/server.ts` and is surfaced via the server `instructions` field (discoverable from the MCP `initialize` response).
 
 ### `git_log` — parameters
 
@@ -335,6 +335,7 @@ v2 field-omission rules still apply: `filesChanged`, `insertions`, `deletions` o
 | `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
 | `invalid_since` | The `since` string contains shell metacharacters and was rejected. |
 | `invalid_paths` | One of the `paths` entries contains shell metacharacters and was rejected. |
+| `unsafe_ref_token` | `branch` contains characters outside the argv-safe subset. |
 | `git_log_failed` | `git log` exited non-zero (e.g. unknown branch ref). |
 | `root_index_out_of_range` | `rootIndex` exceeds the number of MCP file roots. |
 | `absolute_git_roots_exclusive` | `absoluteGitRoots` was combined with `workspaceRoot`, `rootIndex`, or `allWorkspaceRoots: true`. |
@@ -416,7 +417,11 @@ The response contains one **`parity[]`** entry per resolved git toplevel. `absol
 | `head` | string | `HEAD` | Head ref for a revision diff. Used only when `base` is provided. |
 | `path` | string | — | Optional single file path to scope the diff. |
 | `staged` | boolean | `false` | When `true`, runs `git diff --staged`. Ignored when `base` is provided. |
-| `workspaceRoot`, `rootIndex`, `format` | — | Standard single-repo workspace pick + output format. |
+| `workspaceRoot` | string | — | Explicit root; highest priority. |
+| `rootIndex` | int | — | Pick one of several MCP roots (0-based). |
+| `format` | `"markdown"` \| `"json"` | `"markdown"` | Output format. |
+
+`git_diff` is a single-repo tool. It does not accept `absoluteGitRoots` or `allWorkspaceRoots`; use `workspaceRoot` or `rootIndex` to select the target repo.
 
 ### `git_diff` — JSON shape (`format: "json"`)
 
@@ -462,6 +467,8 @@ The response contains one **`parity[]`** entry per resolved git toplevel. `absol
 
 | Code | Meaning |
 |------|---------|
+| `unsafe_ref_token` | `ref` contains characters outside the argv-safe subset. |
+| `path_escapes_repo` | `path` resolves outside the git toplevel. |
 | `git_show_failed` | `git show` exited non-zero (e.g. unknown ref). |
 | `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
 
@@ -520,6 +527,8 @@ Fetch failures are reported as `ok: false` with the captured git output in `outp
 
 | Code | Meaning |
 |------|---------|
+| `unsafe_remote_token` | `remote` contains characters outside the argv-safe subset. |
+| `unsafe_ref_token` | `branch` contains characters outside the argv-safe subset. |
 | `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
 
 ---
@@ -792,9 +801,9 @@ For deletions, `type` is `"deleted"` and `sha` is an empty string.
 
 | Code | Meaning |
 |------|---------|
-| `tag_empty` | `tag` trimmed to an empty string. |
-| `tag_unsafe` | `tag` contains disallowed characters. |
-| `ref_unsafe` | `ref` contains disallowed characters. |
+| `empty_tag_name` | `tag` trimmed to an empty string. |
+| `unsafe_tag_token` | `tag` contains disallowed characters. |
+| `unsafe_ref_token` | `ref` contains disallowed characters. |
 | `ref_not_found` | `ref` did not resolve to a commit. |
 | `tag_create_failed` | `git tag` failed while creating the tag. |
 | `tag_delete_failed` | `git tag -d` failed. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,
@@ -37,6 +37,7 @@
     "schema:tools": "bun scripts/generate-tool-parameters-schema.ts",
     "schema:tools:check": "bun scripts/generate-tool-parameters-schema.ts --check",
     "schema:individual": "bun scripts/generate-individual-schemas.ts",
+    "schema:individual:check": "bun scripts/generate-individual-schemas.ts --check",
     "publish:preflight": "bun scripts/publish-preflight.ts",
     "test": "bun test src/",
     "test:coverage": "bun test src/ --coverage",
@@ -69,7 +70,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
-    "@types/node": "^25.8.0",
+    "@types/node": "^25.9.1",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3"
   },

package/schemas/git_diff.json

@@ -14,19 +14,6 @@
       "minimum": 0,
       "maximum": 9007199254740991
     },
-    "allWorkspaceRoots": {
-      "default": false,
-      "description": "Fan out across all MCP file roots.",
-      "type": "boolean"
-    },
-    "absoluteGitRoots": {
-      "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
-      "maxItems": 256,
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
     "format": {
       "default": "markdown",
       "type": "string",
@@ -54,7 +41,6 @@
     }
   },
   "required": [
-    "allWorkspaceRoots",
     "format",
     "staged"
   ],

package/schemas/git_diff_summary.json

@@ -14,11 +14,6 @@
       "minimum": 0,
       "maximum": 9007199254740991
     },
-    "allWorkspaceRoots": {
-      "default": false,
-      "description": "Fan out across all MCP file roots.",
-      "type": "boolean"
-    },
     "absoluteGitRoots": {
       "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
       "maxItems": 256,
@@ -66,7 +61,6 @@
     }
   },
   "required": [
-    "allWorkspaceRoots",
     "format",
     "maxLinesPerFile",
     "maxFiles"

package/schemas/git_show.json

@@ -24,6 +24,7 @@
     },
     "ref": {
       "type": "string",
+      "minLength": 1,
       "description": "Commit reference (SHA, branch, tag, or any git rev-spec)."
     },
     "path": {

package/tool-parameters.schema.json

@@ -326,11 +326,6 @@
           "minimum": 0,
           "maximum": 9007199254740991
         },
-        "allWorkspaceRoots": {
-          "default": false,
-          "description": "Fan out across all MCP file roots.",
-          "type": "boolean"
-        },
         "absoluteGitRoots": {
           "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
           "maxItems": 256,
@@ -378,7 +373,6 @@
         }
       },
       "required": [
-        "allWorkspaceRoots",
         "format",
         "maxLinesPerFile",
         "maxFiles"
@@ -399,19 +393,6 @@
           "minimum": 0,
           "maximum": 9007199254740991
         },
-        "allWorkspaceRoots": {
-          "default": false,
-          "description": "Fan out across all MCP file roots.",
-          "type": "boolean"
-        },
-        "absoluteGitRoots": {
-          "description": "Absolute paths to git repo roots. Use for many sibling clones under a non-git parent directory.",
-          "maxItems": 256,
-          "type": "array",
-          "items": {
-            "type": "string"
-          }
-        },
         "format": {
           "default": "markdown",
           "type": "string",
@@ -439,7 +420,6 @@
         }
       },
       "required": [
-        "allWorkspaceRoots",
         "format",
         "staged"
       ],
@@ -469,6 +449,7 @@
         },
         "ref": {
           "type": "string",
+          "minLength": 1,
           "description": "Commit reference (SHA, branch, tag, or any git rev-spec)."
         },
         "path": {