@rethunk/mcp-multi-root-git 3.1.0 → 4.0.0

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

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
 import { z } from "zod";
+import { assertRelativePathUnderTop, resolvePathForRepo } from "../repo-paths.js";
 import { ERROR_CODES } from "./error-codes.js";
 import { asyncPool, GIT_SUBPROCESS_PARALLELISM, gitTopLevel, spawnGitAsync } from "./git.js";
 import { isSafeGitAncestorRef } from "./git-refs.js";
@@ -21,7 +22,7 @@ const RECORD_SEP_OUT = "\x02"; // what git outputs (STX) — used as record-STAR
 // %x02 is placed at the START of each record (tformat adds \n as terminator after each).
 // Splitting stdout on \x02 then gives empty-first-chunk + one chunk per commit,
 // each structured as:  <fields>\x01\n\n <shortstat text>\n
-// Fields are separated by %x01; the trailing \x01 before \n leaves one empty last field (ignored).
+// Fields are separated by %x01; the trailing %x01 before \n leaves one empty last field (ignored).
 const PRETTY_FORMAT = "%x02%H%x01%s%x01%aN%x01%aE%x01%aI%x01";
 // ---------------------------------------------------------------------------
 // Helpers
@@ -55,7 +56,7 @@ async function gitCurrentBranch(cwd, branchArg) {
  * Run git log for a single repo root and return structured data.
  */
 async function runGitLog(opts) {
-    const { top, since, paths, grep, author, maxCommits, branch } = opts;
+    const { top, since, paths, grep, author, maxCommits, branch, follow } = opts;
     // Resolve branch first (needed for output metadata).
     const resolvedBranch = await gitCurrentBranch(top, branch);
     // Fetch one extra commit to detect truncation.
@@ -68,6 +69,9 @@ async function runGitLog(opts) {
         String(fetchLimit),
         `--since=${since}`,
     ];
+    if (follow) {
+        logArgs.push("--follow");
+    }
     if (branch?.trim()) {
         logArgs.push(branch.trim());
     }
@@ -176,7 +180,8 @@ function renderLogMarkdown(group, filterSummary) {
 export function registerGitLogTool(server) {
     server.addTool({
         name: "git_log",
-        description: "Read-only `git log` across one or more roots. Returns author, date, subject, optional diff stats.",
+        description: "Read-only `git log` across one or more roots. Returns author, date, subject, optional diff stats. " +
+            "`follow: true` passes `--follow` for rename-aware history (requires exactly one `paths` entry).",
         annotations: {
             readOnlyHint: true,
         },
@@ -209,6 +214,11 @@ export function registerGitLogTool(server) {
                 .default(DEFAULT_MAX_COMMITS)
                 .describe(`Max commits per root (hard cap ${MAX_COMMITS_HARD_CAP}, default ${DEFAULT_MAX_COMMITS}).`),
             branch: z.string().optional().describe("Ref/branch to log from. Default: HEAD."),
+            follow: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Pass `git log --follow` for rename-aware history. Requires exactly one entry in `paths`."),
         }),
         execute: async (args) => {
             const pre = requireGitAndRoots(server, args, undefined);
@@ -227,12 +237,20 @@ export function registerGitLogTool(server) {
                     return jsonRespond({ error: ERROR_CODES.INVALID_PATHS, path: p });
                 }
             }
+            const follow = args.follow ?? false;
+            if (follow && rawPaths.length !== 1) {
+                return jsonRespond({
+                    error: ERROR_CODES.INVALID_PATHS,
+                    detail: "follow requires exactly one path",
+                    pathCount: rawPaths.length,
+                });
+            }
             // Validate branch — reject leading-dash and other injection attempts.
             if (args.branch && !isSafeGitAncestorRef(args.branch)) {
                 return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, branch: args.branch });
             }
             const maxCommits = Math.min(args.maxCommits ?? DEFAULT_MAX_COMMITS, MAX_COMMITS_HARD_CAP);
-            // Fan out across roots.
+            // Fan out across roots. Path confinement is per-root (each has its own toplevel).
             const jobs = pre.roots.map((rootInput) => ({ rootInput }));
             const results = await asyncPool(jobs, GIT_SUBPROCESS_PARALLELISM, async ({ rootInput }) => {
                 const top = gitTopLevel(rootInput);
@@ -243,6 +261,16 @@ export function registerGitLogTool(server) {
                         error: ERROR_CODES.NOT_A_GIT_REPOSITORY,
                     };
                 }
+                for (const p of rawPaths) {
+                    const resolved = resolvePathForRepo(p, top);
+                    if (!assertRelativePathUnderTop(p, resolved, top)) {
+                        return {
+                            _error: true,
+                            workspaceRoot: rootInput,
+                            error: ERROR_CODES.PATH_ESCAPES_REPO,
+                        };
+                    }
+                }
                 const r = await runGitLog({
                     top,
                     since: rawSince,
@@ -251,6 +279,7 @@ export function registerGitLogTool(server) {
                     author: args.author,
                     maxCommits,
                     branch: args.branch,
+                    follow,
                 });
                 if ("error" in r) {
                     return { _error: true, workspaceRoot: rootInput, error: r.error };
@@ -261,6 +290,8 @@ export function registerGitLogTool(server) {
             const filterParts = [`since: ${rawSince}`];
             if (rawPaths.length > 0)
                 filterParts.push(`paths: ${rawPaths.join(", ")}`);
+            if (follow)
+                filterParts.push("follow");
             if (args.grep)
                 filterParts.push(`grep: ${args.grep}`);
             if (args.author)

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

@@ -15,22 +15,39 @@ const StrategySchema = z
     .describe("`auto` (default): cascade fast-forward → rebase → merge-commit per source. " +
     "`ff-only`: only fast-forward, fail if diverged. " +
     "`rebase`: rebase source onto destination, then fast-forward (no merge-commit fallback). " +
-    "`merge`: always create a merge commit (no fast-forward).");
+    "`merge`: always create a merge commit (no fast-forward). " +
+    "Note: `auto`/`rebase` rewrite the source branch tip in place when rebasing (new SHAs).");
 // ---------------------------------------------------------------------------
 // Abort helpers
 // ---------------------------------------------------------------------------
-async function abortMerge(gitTop) {
-    await spawnGitAsync(gitTop, ["merge", "--abort"]);
+/** Result of `git merge --abort` — callers must check `ok` before claiming a clean abort. */
+export async function abortMerge(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["merge", "--abort"]);
+    if (r.ok)
+        return { ok: true };
+    const detail = (r.stderr || r.stdout).trim();
+    return detail === "" ? { ok: false } : { ok: false, detail };
 }
-async function abortRebase(gitTop) {
-    await spawnGitAsync(gitTop, ["rebase", "--abort"]);
+/** Result of `git rebase --abort` — callers must check `ok` before claiming a clean abort. */
+export async function abortRebase(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["rebase", "--abort"]);
+    if (r.ok)
+        return { ok: true };
+    const detail = (r.stderr || r.stdout).trim();
+    return detail === "" ? { ok: false } : { ok: false, detail };
+}
+async function mergeInProgress(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["rev-parse", "--verify", "--quiet", "MERGE_HEAD"]);
+    return r.ok;
 }
 // ---------------------------------------------------------------------------
 // Per-source merge logic
 // ---------------------------------------------------------------------------
 /**
  * Attempt to land `source` on `into`. Caller must ensure `into` is checked out.
- * On conflict the repo state is cleaned (merge/rebase aborted, HEAD restored to `into`).
+ * On conflict the repo is aborted when possible; if `--abort` itself fails the
+ * result carries `merge_abort_failed` / `rebase_abort_failed` and the tree may
+ * still be mid-merge/rebase.
  */
 async function mergeOneSource(gitTop, into, source, strategy, mergeMessage) {
     // --- Classify state via merge-base ---
@@ -79,6 +96,7 @@ async function mergeOneSource(gitTop, into, source, strategy, mergeMessage) {
         return mergeCommit(gitTop, source, mergeMessage, into);
     }
     // --- rebase or auto (diverged case) ---
+    // Warning: rebaseSourceOntoInto rewrites the source branch tip in place.
     const rebased = await rebaseSourceOntoInto(gitTop, into, source);
     if (rebased.ok) {
         // Rebase succeeded; FF destination up to the now-rebased source tip.
@@ -96,7 +114,21 @@ async function mergeOneSource(gitTop, into, source, strategy, mergeMessage) {
 async function fastForward(gitTop, source) {
     const r = await spawnGitAsync(gitTop, ["merge", "--ff-only", source]);
     if (!r.ok) {
-        await abortMerge(gitTop);
+        // ff-only refusal normally leaves no MERGE_HEAD — only abort when mid-merge.
+        if (await mergeInProgress(gitTop)) {
+            const abort = await abortMerge(gitTop);
+            if (!abort.ok) {
+                return {
+                    source,
+                    ok: false,
+                    outcome: "conflicts",
+                    conflictStage: "merge",
+                    conflictPaths: [],
+                    error: ERROR_CODES.MERGE_ABORT_FAILED,
+                    detail: abort.detail ?? (r.stderr || r.stdout).trim(),
+                };
+            }
+        }
         return {
             source,
             ok: false,
@@ -120,7 +152,18 @@ async function mergeCommit(gitTop, source, message, into) {
     const r = await spawnGitAsync(gitTop, ["merge", "--no-ff", "--no-edit", "-m", msg, source]);
     if (!r.ok) {
         const paths = await conflictPaths(gitTop);
-        await abortMerge(gitTop);
+        const abort = await abortMerge(gitTop);
+        if (!abort.ok) {
+            return {
+                source,
+                ok: false,
+                outcome: "conflicts",
+                conflictStage: "merge",
+                conflictPaths: paths,
+                error: ERROR_CODES.MERGE_ABORT_FAILED,
+                detail: abort.detail ?? (r.stderr || r.stdout).trim(),
+            };
+        }
         return {
             source,
             ok: false,
@@ -142,15 +185,27 @@ async function mergeCommit(gitTop, source, message, into) {
 /**
  * Rebase `source` onto `into`, then return to `into`.
  * On failure: abort rebase, check out `into` again, return structured conflict.
+ * Successful rebase rewrites the source branch tip (new SHAs).
  */
 async function rebaseSourceOntoInto(gitTop, into, source) {
     // `git rebase <upstream> <branch>` first switches to <branch>.
     const r = await spawnGitAsync(gitTop, ["rebase", into, source]);
     if (!r.ok) {
         const paths = await conflictPaths(gitTop);
-        await abortRebase(gitTop);
-        // Ensure we're back on `into` regardless of rebase state.
+        const abort = await abortRebase(gitTop);
+        // Ensure we're back on `into` regardless of rebase state (best-effort).
         await spawnGitAsync(gitTop, ["checkout", into]);
+        if (!abort.ok) {
+            return {
+                source,
+                ok: false,
+                outcome: "conflicts",
+                conflictStage: "rebase",
+                conflictPaths: paths,
+                error: ERROR_CODES.REBASE_ABORT_FAILED,
+                detail: abort.detail ?? (r.stderr || r.stdout).trim(),
+            };
+        }
         return {
             source,
             ok: false,
@@ -179,6 +234,9 @@ async function rebaseSourceOntoInto(gitTop, into, source) {
 async function maybeRemoveWorktree(gitTop, source, enabled) {
     if (!enabled)
         return undefined;
+    // Gate on the source branch name first (path basename may be an agent temp dir).
+    if (isProtectedBranch(source))
+        return undefined;
     const path = await worktreeForBranch(gitTop, source);
     if (!path)
         return undefined;
@@ -209,6 +267,7 @@ export function registerGitMergeTool(server) {
         name: "git_merge",
         description: "Merge one or more source branches into a destination. `auto` cascades " +
             "fast-forward → rebase → merge-commit, preferring linear history. " +
+            "`auto`/`rebase` rewrite the source branch tip in place when rebasing (new SHAs), not only the destination. " +
             "Refuses on dirty tree; stops on first conflict. Optional flags delete merged branches/worktrees " +
             "(protected names skipped: main, master, dev, develop, stable, trunk, prod, production, release/*, hotfix/*).",
         annotations: {
@@ -240,7 +299,7 @@ export function registerGitMergeTool(server) {
                 .boolean()
                 .optional()
                 .default(false)
-                .describe("Remove local worktrees on source branches after clean merge (`git worktree remove`). Protected tails skipped."),
+                .describe("Remove local worktrees on source branches after clean merge (`git worktree remove`). Protected source names and path tails skipped."),
         }),
         execute: async (args) => {
             const pre = requireSingleRepo(server, args);
@@ -330,7 +389,6 @@ export function registerGitMergeTool(server) {
                         }),
                         ...spreadWhen(r.branchDeleted === true, { branchDeleted: true }),
                         ...spreadDefined("worktreeRemoved", r.worktreeRemoved),
-                        ...spreadDefined("skipReason", r.skipReason),
                         ...spreadDefined("error", r.error),
                         ...spreadDefined("detail", r.detail),
                     })),

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

@@ -34,17 +34,26 @@ export function registerGitParityTool(server) {
             for (const workspaceRoot of pre.roots) {
                 const top = gitTopLevel(workspaceRoot);
                 if (!top) {
-                    const errPayload = { error: ERROR_CODES.NOT_A_GIT_REPOSITORY, path: workspaceRoot };
-                    const err = jsonRespond(errPayload);
+                    const errDesc = `not a git repository: ${workspaceRoot}`;
                     if (args.format === "json") {
                         results.push({
                             workspaceRoot: workspaceRoot,
                             status: "MISMATCH",
-                            pairs: [{ label: "—", leftPath: "", rightPath: "", match: false, error: err }],
+                            pairs: [{ label: "—", leftPath: "", rightPath: "", match: false, error: errDesc }],
                         });
                     }
                     else {
-                        mdParts.push(err);
+                        mdParts.push([
+                            "# Git HEAD parity",
+                            "",
+                            `status: MISMATCH`,
+                            "",
+                            `## — — error`,
+                            "```text",
+                            errDesc,
+                            "```",
+                            "",
+                        ].join("\n"));
                     }
                     continue;
                 }

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

@@ -45,7 +45,9 @@ export function registerGitPushTool(server) {
             if (!branch) {
                 return jsonRespond({ error: ERROR_CODES.PUSH_DETACHED_HEAD });
             }
-            if (!isSafeGitRefToken(branch)) {
+            // Reject leading `+` (git force-update refspec) even if the shared ref
+            // token helper still permits `+` mid-name — never force-push via argv.
+            if (!isSafeGitRefToken(branch) || branch.startsWith("+")) {
                 return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: branch });
             }
             // --- Resolve remote ---

package/dist/server/git-refs.js

@@ -51,13 +51,14 @@ export function isProtectedBranch(name) {
  * Conservative check for branch/ref names passed to git argv.
  * Rejects anything outside the ASCII subset `A-Z a-z 0-9 _ . / + -`,
  * sequences git itself rejects (`..`, `@{`, leading `-`, trailing `.lock`/`/`),
- * and pathological tokens.
+ * leading `+` (git force-refspec), and pathological tokens.
  */
 export function isSafeGitRefToken(s) {
     const t = s.trim();
     if (t.length === 0 || t.length > 256)
         return false;
-    if (t.startsWith("-"))
+    // Leading `-` is a git option; leading `+` is a force-update refspec.
+    if (t.startsWith("-") || t.startsWith("+"))
         return false;
     if (t.endsWith("/") || t.endsWith(".lock") || t.endsWith("."))
         return false;
@@ -70,32 +71,52 @@ export function isSafeGitRefToken(s) {
     return /^[A-Za-z0-9_./+-]+$/.test(t);
 }
 /**
- * Same as `isSafeGitRefToken` but also allows `~N` / `^N` ancestor notation used
- * by `git reset --soft HEAD~3`. Permits `~` and `^` suffix characters.
+ * Same as `isSafeGitCommitIsh` — trailing `~N` / `^N` ancestor notation used
+ * by `git reset --soft HEAD~3`, plus the full `isSafeGitRefToken` base guards
+ * (`..`, `.lock`, `//`, `@{`, leading `+/-`, etc.). Kept as a named export for
+ * call sites that only need ancestor-capable single refs (not ranges).
  */
 export function isSafeGitAncestorRef(s) {
+    return isSafeGitCommitIsh(s);
+}
+/**
+ * Same as `isSafeGitRefToken`, but also accepts a trailing run of ancestor
+ * operators (`~N` / `^N`, mixable and order-independent, e.g. `HEAD~3`,
+ * `main^2`, `v1.0.0~2^1`) as used by commit-ish arguments to `git diff`,
+ * `git blame`, and `git show`. The base name (everything before the first
+ * ancestor operator) must itself pass `isSafeGitRefToken` — so all of that
+ * function's guards (leading `-`/`+`, `..`, `.lock` suffix, `//`, `@{`,
+ * whitespace, `:`, etc.) still apply. Ancestor operators are only permitted
+ * as a trailing suffix run, not embedded mid-name (e.g. `a~b` is rejected).
+ */
+export function isSafeGitCommitIsh(s) {
     const t = s.trim();
     if (t.length === 0 || t.length > 256)
         return false;
-    if (t.startsWith("-"))
+    const suffixMatch = /(?:[~^][0-9]*)+$/.exec(t);
+    const base = suffixMatch ? t.slice(0, suffixMatch.index) : t;
+    if (base.length === 0)
         return false;
-    return /^[A-Za-z0-9_./+~^-]+$/.test(t);
+    return isSafeGitRefToken(base);
 }
 /**
  * Same as `isSafeGitRefToken` but also allows the `A..B` / `A...B` range forms
- * used by `git log` / `git cherry-pick`. Splits once and validates each side.
+ * used by `git log` / `git cherry-pick` / `git_diff_summary`. Splits once and
+ * validates each side (and the no-range single-ref fallthrough) with
+ * `isSafeGitCommitIsh`, so ancestor notation (`HEAD~3`, `main^2`) is accepted
+ * on either endpoint, e.g. `HEAD~3..HEAD` or `main...feature^2`.
  */
 export function isSafeGitRangeToken(s) {
     const t = s.trim();
     if (t.includes("...")) {
         const parts = t.split("...");
-        return parts.length === 2 && parts.every((p) => isSafeGitRefToken(p));
+        return parts.length === 2 && parts.every((p) => isSafeGitCommitIsh(p));
     }
     if (t.includes("..")) {
         const parts = t.split("..");
-        return parts.length === 2 && parts.every((p) => isSafeGitRefToken(p));
+        return parts.length === 2 && parts.every((p) => isSafeGitCommitIsh(p));
     }
-    return isSafeGitRefToken(t);
+    return isSafeGitCommitIsh(t);
 }
 // ---------------------------------------------------------------------------
 // Async helpers
@@ -218,11 +239,16 @@ export async function commitListBetween(cwd, excludeRef, includeRef) {
         .map((l) => l.trim())
         .filter((l) => l.length > 0);
 }
-/** Parse `git worktree list --porcelain` into structured entries. */
+/**
+ * Parse `git worktree list --porcelain` into structured entries.
+ * Returns `{ ok: false, detail }` when git fails — callers must not treat
+ * failure as an empty worktree list.
+ */
 export async function listWorktrees(cwd) {
     const r = await spawnGitAsync(cwd, ["worktree", "list", "--porcelain"]);
-    if (!r.ok)
-        return [];
+    if (!r.ok) {
+        return { ok: false, detail: (r.stderr || r.stdout).trim() || "git worktree list failed" };
+    }
     const out = [];
     let cur = {};
     for (const line of r.stdout.split("\n")) {
@@ -245,12 +271,17 @@ export async function listWorktrees(cwd) {
     }
     if (cur.path)
         out.push({ path: cur.path, branch: cur.branch ?? null, head: cur.head ?? null });
-    return out;
+    return { ok: true, worktrees: out };
 }
-/** Path of the worktree currently checked out on `branch`; `null` if none. */
+/**
+ * Path of the worktree currently checked out on `branch`; `null` if none
+ * or if listing worktrees failed (fail closed for destructive callers).
+ */
 export async function worktreeForBranch(cwd, branch) {
-    const trees = await listWorktrees(cwd);
-    const hit = trees.find((t) => t.branch === branch);
+    const listed = await listWorktrees(cwd);
+    if (!listed.ok)
+        return null;
+    const hit = listed.worktrees.find((t) => t.branch === branch);
     return hit?.path ?? null;
 }
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,160 @@
+import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
+import { spawnGitAsync } from "./git.js";
+import { conflictPaths, isSafeGitAncestorRef, isWorkingTreeClean } from "./git-refs.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** SHA of REVERT_HEAD (the commit currently mid-revert), or undefined once resolved/absent. */
+async function revertHead(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["rev-parse", "--verify", "--quiet", "REVERT_HEAD"]);
+    if (!r.ok)
+        return undefined;
+    const sha = r.stdout.trim();
+    return sha === "" ? undefined : sha;
+}
+/** Result of attempting `git revert --abort` — callers must check `ok` before claiming a clean abort. */
+export async function abortRevert(gitTop) {
+    const r = await spawnGitAsync(gitTop, ["revert", "--abort"]);
+    if (r.ok)
+        return { ok: true };
+    const detail = (r.stderr || r.stdout).trim();
+    return detail === "" ? { ok: false } : { ok: false, detail };
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitRevertTool(server) {
+    server.addTool({
+        name: "git_revert",
+        description: "`git revert`: creates new commit(s) that undo the changes introduced by one or more source " +
+            "commits. Unlike `git_reset_soft`, this never rewrites history — safe on shared/pushed branches. " +
+            "Refuses on a dirty tree. On conflict, aborts and returns the tree clean. `noCommit` stages the " +
+            "revert(s) without committing (working tree intentionally left staged in that case). `mainline` " +
+            "selects the parent to diff against when reverting a merge commit.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            sources: z
+                .array(z.string().min(1))
+                .min(1)
+                .max(20)
+                .describe("Commits to revert, applied in order: SHA, branch/tag name, or ancestor notation (`HEAD~1`)."),
+            noCommit: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Pass `--no-commit`: apply the revert(s) to the index/working tree without committing " +
+                "(changes are left staged instead)."),
+            mainline: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Parent number (`-m N`) to diff against — required when reverting a merge commit."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // --- Validate sources ---
+            for (const raw of args.sources) {
+                if (!isSafeGitAncestorRef(raw)) {
+                    return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, source: raw });
+                }
+            }
+            // --- Refuse dirty tree ---
+            if (!(await isWorkingTreeClean(gitTop))) {
+                return jsonRespond({
+                    error: ERROR_CODES.WORKING_TREE_DIRTY,
+                    detail: "git_revert requires a clean working tree. Commit or stash pending changes first.",
+                });
+            }
+            const preHeadProbe = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const preHead = preHeadProbe.ok ? preHeadProbe.stdout.trim() : "";
+            const revertArgs = ["revert"];
+            if (args.noCommit)
+                revertArgs.push("--no-commit");
+            if (args.mainline !== undefined)
+                revertArgs.push("-m", String(args.mainline));
+            revertArgs.push(...args.sources);
+            const r = await spawnGitAsync(gitTop, revertArgs);
+            if (!r.ok) {
+                const failedSha = await revertHead(gitTop);
+                const paths = await conflictPaths(gitTop);
+                const abortResult = await abortRevert(gitTop);
+                return jsonRespond({
+                    ok: false,
+                    aborted: abortResult.ok,
+                    ...spreadDefined("commit", failedSha),
+                    conflicts: paths,
+                    ...spreadDefined("detail", (r.stderr || r.stdout).trim() || undefined),
+                    ...spreadWhen(!abortResult.ok, {
+                        error: ERROR_CODES.REVERT_ABORT_FAILED,
+                        ...spreadDefined("abortDetail", abortResult.detail),
+                    }),
+                });
+            }
+            // --- No-commit: revert(s) staged, no new commits ---
+            if (args.noCommit) {
+                const stagedResult = await spawnGitAsync(gitTop, ["diff", "--cached", "--name-only"]);
+                const stagedFiles = stagedResult.ok
+                    ? stagedResult.stdout
+                        .split("\n")
+                        .map((l) => l.trim())
+                        .filter((l) => l.length > 0)
+                    : [];
+                if (args.format === "json") {
+                    return jsonRespond({
+                        ok: true,
+                        staged: true,
+                        sources: args.sources,
+                        stagedCount: stagedFiles.length,
+                    });
+                }
+                return [
+                    "# Revert (staged, not committed)",
+                    `${args.sources.length} source(s) → ${stagedFiles.length} file(s) staged`,
+                    ...args.sources.map((s) => `- ${s}`),
+                ].join("\n");
+            }
+            // --- Committed: one new commit per source, oldest-first ---
+            const newCommitsResult = await spawnGitAsync(gitTop, [
+                "rev-list",
+                "--reverse",
+                `${preHead}..HEAD`,
+            ]);
+            const newCommits = newCommitsResult.ok
+                ? newCommitsResult.stdout
+                    .split("\n")
+                    .map((l) => l.trim())
+                    .filter((l) => l.length > 0)
+                : [];
+            const reverted = [];
+            for (let i = 0; i < args.sources.length; i++) {
+                const source = args.sources[i];
+                const sha = newCommits[i];
+                if (source !== undefined && sha !== undefined)
+                    reverted.push({ source, sha });
+            }
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: true,
+                    reverted,
+                });
+            }
+            const lines = [`# Revert: ${reverted.length} commit(s)`, ""];
+            for (const item of reverted) {
+                lines.push(`- ${item.source} → ${item.sha.slice(0, 7)}`);
+            }
+            return lines.join("\n");
+        },
+    });
+}

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

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { assertRelativePathUnderTop, resolvePathForRepo } from "../repo-paths.js";
 import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
-import { isSafeGitAncestorRef } from "./git-refs.js";
+import { isSafeGitCommitIsh } from "./git-refs.js";
 import { jsonRespond } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
@@ -39,6 +39,7 @@ async function runGitShow(opts) {
     if (!r.ok) {
         return {
             error: ERROR_CODES.GIT_SHOW_FAILED,
+            detail: (r.stderr || r.stdout).trim(),
         };
     }
     // Parse the output. For a commit, git show outputs:
@@ -157,7 +158,10 @@ export function registerGitShowTool(server) {
             readOnlyHint: true,
         },
         parameters: WorkspacePickSchema.extend({
-            ref: z.string().min(1).describe("Commit reference (SHA, branch, tag, or any git rev-spec)."),
+            ref: z
+                .string()
+                .min(1)
+                .describe('Commit reference (SHA, branch, tag, or ancestor notation like "HEAD~3", "main^2").'),
             path: z
                 .string()
                 .optional()
@@ -176,7 +180,7 @@ export function registerGitShowTool(server) {
             if (!pre.ok)
                 return jsonRespond(pre.error);
             const top = pre.gitTop;
-            if (!isSafeGitAncestorRef(args.ref)) {
+            if (!isSafeGitCommitIsh(args.ref)) {
                 return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.ref });
             }
             if (args.path !== undefined) {