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

package/AGENTS.md

@@ -17,7 +17,7 @@ IDEs injecting this as context: do not re-link from rules.
 |------|---------|
 | [`src/server.ts`](src/server.ts) | `FastMCP` + `roots: { enabled: true }`; `readMcpServerVersion()`; `registerRethunkGitTools` |
 | [`src/server/json.ts`](src/server/json.ts) | `jsonRespond()` (minified, no envelope), `spreadWhen`, `spreadDefined` |
-| [`src/server/git.ts`](src/server/git.ts) | `gateGit`, `spawnGitAsync`, `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`, `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`, `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
+| [`src/server/git.ts`](src/server/git.ts) | `gateGit`, `spawnGitAsync` (optional `{ timeoutMs, signal }`), `asyncPool`, `GIT_SUBPROCESS_PARALLELISM`, `GIT_SUBPROCESS_TIMEOUT_MS`, `gitTopLevel`, `gitRevParseGitDir`, `gitRevParseHead`, `parseGitSubmodulePaths`, `hasGitMetadata`, `gitStatusSnapshotAsync`, `gitStatusShortBranchAsync`, `fetchAheadBehind`, `isSafeGitUpstreamToken` |
 | [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots`, `requireSingleRepo`, `resolveAbsoluteGitRootsList`, `GitRootPickArgs` — shared tool preludes; session root resolution; optional `absoluteGitRoots` bulk pick |
 | [`src/server/presets.ts`](src/server/presets.ts) | `PRESET_FILE_PATH`, `loadPresetsFromGitTop`, `presetLoadErrorPayload`, `applyPresetNestedRoots`, `applyPresetParityPairs`; Zod schemas must match [`git-mcp-presets.schema.json`](git-mcp-presets.schema.json) |
 | [`src/server/schemas.ts`](src/server/schemas.ts) | `WorkspacePickSchema`, `MAX_INVENTORY_ROOTS_DEFAULT`, **`MAX_ABSOLUTE_GIT_ROOTS`** (256), optional **`absoluteGitRoots`** on workspace pick |

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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).
 
+## [2.8.0] — 2026-05-29
+
+Feature release: three new read-only inspection tools (tool count 20 → 23). Additive — no JSON format-version bump.
+
+### Added
+
+- **`git_blame`** — line-by-line authorship for a file: commit SHA, author, ISO date, summary, and content per line. Blames at an optional `ref` and an optional `startLine`/`endLine` range (`-L`); path-confined like the other path tools (`path_escapes_repo`).
+- **`git_branch_list`** — list local branches with sha, current marker, and upstream; optional `includeRemotes` adds remote-tracking branches (symbolic `origin/HEAD` skipped). Returns `{ branches, remotes? }`.
+- **`git_reflog`** — show the reflog for a ref (default `HEAD`): recent HEAD movements with selector (`HEAD@{N}`), full SHA, and message; `maxEntries` cap (default 30, max 200).
+
+## [2.7.0] — 2026-05-29
+
+Feature release: deepens three read tools per recurring agent pain points (TODO.md) and hardens the git subprocess layer. All changes are additive — no JSON format-version bump.
+
+### Added
+
+- **`git_diff` — multi-path + context control** — new `paths: string[]` scopes the diff to multiple files (unioned with the legacy single `path`), and `unified: number` (0–100) sets the context-line width (`-U<n>`). Path confinement is now enforced on every path input, returning `path_escapes_repo` on escape.
+- **`git_show` — stat + multi-path modes** — new `stat: true` returns a `--stat` diffstat (commit message + per-file counts, no full patch), and `paths: string[]` filters the shown patch/stat to specific files, with the same path-confinement guarantees as single `path`.
+- **`git_fetch` — structured ref deltas** — emits `updated: [{ ref, oldSha, newSha, flag }]`, `created: [{ ref, newSha, flag }]`, and `pruned: [{ ref }]` parsed from `git fetch --porcelain` (git ≥ 2.41). On older git the option is detected as unsupported and the tool falls back to the legacy line parse; the string `updatedRefs` / `newRefs` fields are retained for back-compat in both modes.
+- **`GIT_SUBPROCESS_TIMEOUT_MS`** — `spawnGitAsync` now accepts an optional `{ timeoutMs, signal }` argument and applies a default timeout (120000 ms, configurable via the env var; `0` disables). A hung git operation against a dead remote no longer blocks the server indefinitely — the child is killed (SIGTERM) on expiry or `AbortSignal` abort, and the result resolves `ok: false` with `timedOut` / `aborted` flags. Existing callers are unchanged beyond gaining default timeout protection.
+
 ## [2.6.0] — 2026-05-22
 
 Security-hardening and correctness release surfaced by a full-repo critical review.

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/%40rethunk%2Fmcp-multi-root-git.svg)](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**git** tools over MCP: status, multi-root inventory, `HEAD` parity, presets, logs, structured and raw diff views, commit inspection, fetch, stash, tag, batch commit, push, merge, cherry-pick, worktrees, and soft-reset. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
+**git** tools over MCP: status, multi-root inventory, `HEAD` parity, presets, logs, structured and raw diff views, commit inspection, fetch, stash, tag, batch commit, push, merge, cherry-pick, worktrees, soft-reset, blame, branch listing, and reflog. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
 
 **Repository:** [github.com/Rethunk-AI/mcp-multi-root-git](https://github.com/Rethunk-AI/mcp-multi-root-git) · **npmjs (manual releases):** [`@rethunk/mcp-multi-root-git`](https://www.npmjs.com/package/@rethunk/mcp-multi-root-git) · **GitHub Packages (CI on each tag):** [`@rethunk-ai/mcp-multi-root-git`](https://github.com/Rethunk-AI/mcp-multi-root-git/packages) — see [docs/install.md](docs/install.md) and [HUMANS.md](HUMANS.md) Publishing.
 

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

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { z } from "zod";
 import { isStrictlyUnderGitTop, resolvePathForRepo } from "../repo-paths.js";
+import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { getCurrentBranch, inferRemoteFromUpstream } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
@@ -192,11 +193,11 @@ async function stageFile(gitTop, filePath, lines) {
 export async function runPushAfter(gitTop) {
     const branch = await getCurrentBranch(gitTop);
     if (!branch) {
-        return { ok: false, error: "push_detached_head" };
+        return { ok: false, error: ERROR_CODES.PUSH_DETACHED_HEAD };
     }
     const t = await inferRemoteFromUpstream(gitTop);
     if (!t.ok) {
-        return { ok: false, branch, error: "push_no_upstream", detail: t.detail };
+        return { ok: false, branch, error: ERROR_CODES.PUSH_NO_UPSTREAM, detail: t.detail };
     }
     const pushResult = await spawnGitAsync(gitTop, ["push", t.remote, branch]);
     if (!pushResult.ok) {
@@ -204,7 +205,7 @@ export async function runPushAfter(gitTop) {
             ok: false,
             branch,
             upstream: t.upstream,
-            error: "push_failed",
+            error: ERROR_CODES.PUSH_FAILED,
             detail: (pushResult.stderr || pushResult.stdout).trim(),
         };
     }
@@ -288,7 +289,7 @@ export function registerBatchCommitTool(server) {
                         ok: false,
                         message: entry.message,
                         files: filePaths,
-                        error: "path_escapes_repository",
+                        error: ERROR_CODES.PATH_ESCAPES_REPOSITORY,
                         detail: escapedPaths.join(", "),
                     });
                     break;
@@ -310,7 +311,7 @@ export function registerBatchCommitTool(server) {
                         ok: false,
                         message: entry.message,
                         files: filePaths,
-                        error: "stage_failed",
+                        error: ERROR_CODES.STAGE_FAILED,
                         detail: stagingError,
                         ...spreadDefined("output", stagingError || undefined),
                     });
@@ -349,7 +350,7 @@ export function registerBatchCommitTool(server) {
                         ok: false,
                         message: entry.message,
                         files: filePaths,
-                        error: "commit_failed",
+                        error: ERROR_CODES.COMMIT_FAILED,
                         detail: gitOutput,
                         ...spreadDefined("output", gitOutput || undefined),
                     });

package/dist/server/error-codes.js

@@ -0,0 +1,95 @@
+/**
+ * Centralised error-code registry.
+ *
+ * Every value here is the exact string that appears on the wire in JSON
+ * responses (the `error` field). Keys are SCREAMING_SNAKE equivalents so
+ * callers get autocomplete and typos become compile errors.
+ *
+ * Adding a new code: append one entry here, then use ERROR_CODES.YOUR_CODE at
+ * the call-site — do not introduce a new inline string literal.
+ */
+export const ERROR_CODES = {
+    // Git availability
+    GIT_NOT_FOUND: "git_not_found",
+    // Repository resolution
+    NOT_A_GIT_REPOSITORY: "not_a_git_repository",
+    NO_WORKSPACE_ROOT: "no_workspace_root",
+    ROOT_INDEX_OUT_OF_RANGE: "root_index_out_of_range",
+    // absoluteGitRoots validation
+    ABSOLUTE_GIT_ROOTS_EMPTY: "absolute_git_roots_empty",
+    ABSOLUTE_GIT_ROOTS_EXCLUSIVE: "absolute_git_roots_exclusive",
+    ABSOLUTE_GIT_ROOTS_NESTED_OR_PRESET_CONFLICT: "absolute_git_roots_nested_or_preset_conflict",
+    ABSOLUTE_GIT_ROOTS_PRESET_CONFLICT: "absolute_git_roots_preset_conflict",
+    ABSOLUTE_GIT_ROOTS_SINGLE_REPO_ONLY: "absolute_git_roots_single_repo_only",
+    ABSOLUTE_GIT_ROOTS_TOO_MANY: "absolute_git_roots_too_many",
+    INVALID_ABSOLUTE_GIT_ROOT: "invalid_absolute_git_root",
+    // Presets
+    PRESET_FILE_INVALID: "preset_file_invalid",
+    PRESET_NOT_FOUND: "preset_not_found",
+    // Input validation — tokens / refs / paths
+    EMPTY_TAG_NAME: "empty_tag_name",
+    INVALID_LINE_RANGE: "invalid_line_range",
+    INVALID_PATHS: "invalid_paths",
+    INVALID_REMOTE_OR_BRANCH: "invalid_remote_or_branch",
+    INVALID_SINCE: "invalid_since",
+    PATH_ESCAPES_REPO: "path_escapes_repo",
+    PATH_ESCAPES_REPOSITORY: "path_escapes_repository",
+    UNSAFE_RANGE_TOKEN: "unsafe_range_token",
+    UNSAFE_REF_TOKEN: "unsafe_ref_token",
+    UNSAFE_REMOTE_TOKEN: "unsafe_remote_token",
+    UNSAFE_TAG_TOKEN: "unsafe_tag_token",
+    // Branch / ref state
+    INTO_DETACHED_HEAD: "into_detached_head",
+    ONTO_DETACHED_HEAD: "onto_detached_head",
+    PROTECTED_BRANCH: "protected_branch",
+    WORKING_TREE_DIRTY: "working_tree_dirty",
+    // Branch list
+    BRANCH_LIST_FAILED: "branch_list_failed",
+    // Commit / stage
+    COMMIT_FAILED: "commit_failed",
+    STAGE_FAILED: "stage_failed",
+    // Diff
+    GIT_DIFF_FAILED: "git_diff_failed",
+    // Log
+    GIT_LOG_FAILED: "git_log_failed",
+    // Show
+    GIT_SHOW_FAILED: "git_show_failed",
+    // Blame
+    GIT_BLAME_FAILED: "git_blame_failed",
+    // Reflog
+    REFLOG_FAILED: "reflog_failed",
+    // Stash
+    STASH_LIST_FAILED: "stash_list_failed",
+    // Fetch
+    // (uses UNSAFE_REMOTE_TOKEN and UNSAFE_REF_TOKEN)
+    // Push
+    PUSH_DETACHED_HEAD: "push_detached_head",
+    PUSH_FAILED: "push_failed",
+    PUSH_NO_UPSTREAM: "push_no_upstream",
+    // Merge
+    CANNOT_FAST_FORWARD: "cannot_fast_forward",
+    DESTINATION_NOT_FOUND: "destination_not_found",
+    MERGE_BASE_FAILED: "merge_base_failed",
+    MERGE_CONFLICTS: "merge_conflicts",
+    MERGE_FAILED: "merge_failed",
+    REBASE_CONFLICTS: "rebase_conflicts",
+    SOURCE_NOT_FOUND: "source_not_found",
+    // Cherry-pick
+    CHECKOUT_FAILED: "checkout_failed",
+    RANGE_RESOLUTION_FAILED: "range_resolution_failed",
+    // Reset
+    RESET_FAILED: "reset_failed",
+    // Tag
+    REF_NOT_FOUND: "ref_not_found",
+    TAG_CREATE_FAILED: "tag_create_failed",
+    TAG_DELETE_FAILED: "tag_delete_failed",
+    TAG_VERIFICATION_FAILED: "tag_verification_failed",
+    // Worktree
+    CANNOT_REMOVE_MAIN_WORKTREE: "cannot_remove_main_worktree",
+    WORKTREE_ADD_FAILED: "worktree_add_failed",
+    WORKTREE_NOT_FOUND: "worktree_not_found",
+    WORKTREE_REMOVE_FAILED: "worktree_remove_failed",
+    // Inventory / parity
+    NO_PAIRS: "no_pairs",
+    REMOTE_BRANCH_MISMATCH: "remote_branch_mismatch",
+};

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

@@ -0,0 +1,227 @@
+import { z } from "zod";
+import { assertRelativePathUnderTop, resolvePathForRepo } from "../repo-paths.js";
+import { ERROR_CODES } from "./error-codes.js";
+import { spawnGitAsync } from "./git.js";
+import { isSafeGitRefToken } from "./git-refs.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+/**
+ * Convert a Unix epoch + timezone offset string (e.g. "+0200") to an ISO 8601 string.
+ * The tz offset is in the format ±HHMM as emitted by git blame --porcelain.
+ */
+function epochTzToIso(epoch, tz) {
+    // tz looks like "+0200" or "-0500"
+    const sign = tz.startsWith("-") ? -1 : 1;
+    const tzBody = tz.replace(/^[+-]/, "");
+    const tzHours = Number.parseInt(tzBody.slice(0, 2), 10);
+    const tzMins = Number.parseInt(tzBody.slice(2), 10);
+    const offsetMs = sign * (tzHours * 60 + tzMins) * 60 * 1000;
+    const localMs = epoch * 1000 + offsetMs;
+    const d = new Date(localMs);
+    const pad2 = (n) => String(n).padStart(2, "0");
+    const datePart = `${d.getUTCFullYear()}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())}`;
+    const timePart = `${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())}:${pad2(d.getUTCSeconds())}`;
+    const tzSign = sign >= 0 ? "+" : "-";
+    const tzStr = `${tzSign}${pad2(tzHours)}:${pad2(tzMins)}`;
+    return `${datePart}T${timePart}${tzStr}`;
+}
+/**
+ * Parse `git blame --porcelain` output into structured lines.
+ *
+ * Porcelain format per commit block:
+ *   <sha> <orig-line> <final-line> [<num-lines>]
+ *   author <name>
+ *   author-mail <email>
+ *   author-time <epoch>
+ *   author-tz <±HHMM>
+ *   committer ...
+ *   summary <msg>
+ *   ...
+ *   \t<line content>
+ *
+ * Key-value header lines only appear for the FIRST occurrence of a SHA.
+ * Subsequent blocks for the same SHA have only the header line + TAB line.
+ */
+function parsePorcelain(output) {
+    const lines = output.split("\n");
+    const metaCache = new Map();
+    const result = [];
+    let i = 0;
+    while (i < lines.length) {
+        const headerLine = lines[i];
+        if (headerLine === undefined || headerLine.trim() === "") {
+            i++;
+            continue;
+        }
+        // Header: "<sha40> <origLine> <finalLine> [numLines]"
+        const headerMatch = /^([0-9a-f]{40}) \d+ (\d+)/.exec(headerLine);
+        if (!headerMatch) {
+            i++;
+            continue;
+        }
+        const sha = headerMatch[1] ?? "";
+        const finalLine = Number.parseInt(headerMatch[2] ?? "0", 10);
+        i++;
+        // Collect key-value lines until the TAB-prefixed content line
+        let author = "";
+        let authorTime = 0;
+        let authorTz = "+0000";
+        let summary = "";
+        let content = "";
+        let foundContent = false;
+        while (i < lines.length) {
+            const l = lines[i];
+            if (l === undefined) {
+                i++;
+                break;
+            }
+            if (l.startsWith("\t")) {
+                content = l.slice(1);
+                foundContent = true;
+                i++;
+                break;
+            }
+            // Parse known key-value pairs
+            if (l.startsWith("author ") && !l.startsWith("author-")) {
+                author = l.slice("author ".length);
+            }
+            else if (l.startsWith("author-time ")) {
+                authorTime = Number.parseInt(l.slice("author-time ".length), 10);
+            }
+            else if (l.startsWith("author-tz ")) {
+                authorTz = l.slice("author-tz ".length).trim();
+            }
+            else if (l.startsWith("summary ")) {
+                summary = l.slice("summary ".length);
+            }
+            i++;
+        }
+        if (!foundContent)
+            continue;
+        // Merge with cache: first occurrence populates cache; subsequent occurrences read it.
+        const cached = metaCache.get(sha);
+        if (cached === undefined) {
+            // First occurrence — we collected the metadata
+            metaCache.set(sha, { author, authorTime, summary, authorTz });
+        }
+        else {
+            // Subsequent occurrence — restore from cache
+            author = cached.author;
+            authorTime = cached.authorTime;
+            authorTz = cached.authorTz;
+            summary = cached.summary;
+        }
+        const date = epochTzToIso(authorTime, authorTz);
+        result.push({
+            line: finalLine,
+            sha,
+            author,
+            date,
+            summary,
+            content,
+        });
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderBlameMarkdown(result) {
+    const header = result.ref !== undefined
+        ? `# git blame ${result.ref} -- ${result.path}`
+        : `# git blame ${result.path}`;
+    const rows = result.lines.map((l) => {
+        const sha7 = l.sha.slice(0, 7);
+        return `${sha7} (${l.author} ${l.date}) ${l.content}`;
+    });
+    return [`${header}`, "", "```", ...rows, "```"].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitBlameTool(server) {
+    server.addTool({
+        name: "git_blame",
+        description: "Annotate each line of a file with the commit SHA, author, date, and summary that last modified it. Optionally restrict to a commit-ish ref and/or a line range.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
+            .pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        })
+            .extend({
+            path: z.string().min(1).describe("Repo-relative path to the file to blame."),
+            ref: z.string().optional().describe("Optional commit-ish (SHA, branch, tag) to blame at."),
+            startLine: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("First line of the range to blame (1-based). Requires endLine."),
+            endLine: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Last line of the range to blame (1-based, inclusive). Requires startLine."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const top = pre.gitTop;
+            // Path confinement
+            const resolved = resolvePathForRepo(args.path, top);
+            if (!assertRelativePathUnderTop(args.path, resolved, top)) {
+                return jsonRespond({ error: ERROR_CODES.PATH_ESCAPES_REPO, path: args.path });
+            }
+            // Ref validation
+            if (args.ref !== undefined) {
+                if (!isSafeGitRefToken(args.ref)) {
+                    return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.ref });
+                }
+            }
+            // Line range validation
+            const startLine = args.startLine;
+            const endLine = args.endLine;
+            if (startLine !== undefined || endLine !== undefined) {
+                if (startLine === undefined || endLine === undefined) {
+                    return jsonRespond({ error: ERROR_CODES.INVALID_LINE_RANGE });
+                }
+                if (startLine > endLine) {
+                    return jsonRespond({ error: ERROR_CODES.INVALID_LINE_RANGE });
+                }
+            }
+            // Build git blame args
+            const blameArgs = ["blame", "--porcelain"];
+            if (args.ref !== undefined) {
+                blameArgs.push(args.ref);
+            }
+            if (startLine !== undefined && endLine !== undefined) {
+                blameArgs.push(`-L${startLine},${endLine}`);
+            }
+            blameArgs.push("--", args.path);
+            const r = await spawnGitAsync(top, blameArgs);
+            if (!r.ok) {
+                return jsonRespond({
+                    error: ERROR_CODES.GIT_BLAME_FAILED,
+                    detail: (r.stderr || r.stdout).trim(),
+                });
+            }
+            const blameLines = parsePorcelain(r.stdout);
+            const blameJson = {
+                ...spreadDefined("ref", args.ref),
+                path: args.path,
+                lines: blameLines,
+            };
+            if (args.format === "json") {
+                return jsonRespond(blameJson);
+            }
+            return renderBlameMarkdown(blameJson);
+        },
+    });
+}

package/dist/server/git-branch-list-tool.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
+import { spawnGitAsync } from "./git.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function runBranchList(opts) {
+    const { top, includeRemotes } = opts;
+    // Local branches: name, full SHA, upstream (may be empty), HEAD marker (* or space)
+    const localR = await spawnGitAsync(top, [
+        "for-each-ref",
+        "--format=%(refname:short)%00%(objectname)%00%(upstream:short)%00%(HEAD)",
+        "refs/heads",
+    ]);
+    if (!localR.ok) {
+        return {
+            error: ERROR_CODES.BRANCH_LIST_FAILED,
+            detail: (localR.stderr || localR.stdout).trim(),
+        };
+    }
+    const branches = [];
+    const localLines = (localR.stdout || "").split("\n").filter((l) => l.length > 0);
+    for (const line of localLines) {
+        const parts = line.split("\x00");
+        const name = parts[0] ?? "";
+        const sha = parts[1] ?? "";
+        const upstream = parts[2] ?? "";
+        const headMarker = parts[3] ?? "";
+        if (!name || !sha)
+            continue;
+        branches.push({
+            name,
+            sha,
+            current: headMarker === "*",
+            ...spreadDefined("upstream", upstream || undefined),
+        });
+    }
+    if (!includeRemotes) {
+        return { branches };
+    }
+    // Remote branches: name, full SHA — skip symbolic origin/HEAD refs
+    const remoteR = await spawnGitAsync(top, [
+        "for-each-ref",
+        "--format=%(refname:short)%00%(objectname)",
+        "refs/remotes",
+    ]);
+    if (!remoteR.ok) {
+        return {
+            error: ERROR_CODES.BRANCH_LIST_FAILED,
+            detail: (remoteR.stderr || remoteR.stdout).trim(),
+        };
+    }
+    const remotes = [];
+    const remoteLines = (remoteR.stdout || "").split("\n").filter((l) => l.length > 0);
+    for (const line of remoteLines) {
+        const parts = line.split("\x00");
+        const name = parts[0] ?? "";
+        const sha = parts[1] ?? "";
+        // Skip symbolic origin/HEAD
+        if (!name || !sha || name.endsWith("/HEAD"))
+            continue;
+        remotes.push({ name, sha });
+    }
+    return {
+        branches,
+        ...spreadWhen(remotes.length > 0, { remotes }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+function renderBranchListMarkdown(result) {
+    const lines = ["## Branches", ""];
+    if (result.branches.length === 0) {
+        lines.push("_(none)_");
+    }
+    else {
+        for (const b of result.branches) {
+            const prefix = b.current ? "* " : "  ";
+            const upstream = b.upstream ? ` → ${b.upstream}` : "";
+            lines.push(`${prefix}**${b.name}**${upstream}  (\`${b.sha}\`)`);
+        }
+    }
+    if (result.remotes && result.remotes.length > 0) {
+        lines.push("");
+        lines.push("## Remote branches");
+        lines.push("");
+        for (const r of result.remotes) {
+            lines.push(`- **${r.name}**  (\`${r.sha}\`)`);
+        }
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGitBranchListTool(server) {
+    server.addTool({
+        name: "git_branch_list",
+        description: "List local branches (and optionally remote-tracking branches) for a single git repository. " +
+            "Returns `{ branches: [{ name, sha, current, upstream? }], remotes?: [{ name, sha }] }`. " +
+            "The current branch is marked with `current: true`. Remote branches are included when `includeRemotes: true`.",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.omit({ absoluteGitRoots: true, allWorkspaceRoots: true })
+            .pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        })
+            .extend({
+            includeRemotes: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("When true, also return remote-tracking branches from refs/remotes (excluding symbolic origin/HEAD)."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            const result = await runBranchList({
+                top: gitTop,
+                includeRemotes: args.includeRemotes ?? false,
+            });
+            if ("error" in result) {
+                return jsonRespond(result);
+            }
+            if (args.format === "json") {
+                return jsonRespond(result);
+            }
+            return renderBranchListMarkdown(result);
+        },
+    });
+}

package/dist/server/git-cherry-pick-tool.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { spawnGitAsync } from "./git.js";
 import { commitListBetween, conflictPaths, getCurrentBranch, isContentEquivalentlyMergedInto, isFullyMergedInto, isProtectedBranch, isSafeGitRangeToken, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
@@ -30,12 +31,12 @@ async function branchExists(gitTop, name) {
 async function resolveSource(gitTop, onto, raw) {
     if (raw.includes("..")) {
         if (!isSafeGitRangeToken(raw)) {
-            return { error: "unsafe_ref_token", raw };
+            return { error: ERROR_CODES.UNSAFE_REF_TOKEN, raw };
         }
         const r = await spawnGitAsync(gitTop, ["rev-list", "--reverse", raw]);
         if (!r.ok) {
             return {
-                error: "range_resolution_failed",
+                error: ERROR_CODES.RANGE_RESOLUTION_FAILED,
                 detail: (r.stderr || r.stdout).trim(),
                 raw,
             };
@@ -47,18 +48,18 @@ async function resolveSource(gitTop, onto, raw) {
         return { raw, kind: "range", commits };
     }
     if (!isSafeGitRefToken(raw)) {
-        return { error: "unsafe_ref_token", raw };
+        return { error: ERROR_CODES.UNSAFE_REF_TOKEN, raw };
     }
     if (await branchExists(gitTop, raw)) {
         const commits = await commitListBetween(gitTop, onto, raw);
         if (commits === null) {
-            return { error: "range_resolution_failed", raw };
+            return { error: ERROR_CODES.RANGE_RESOLUTION_FAILED, raw };
         }
         return { raw, kind: "branch", commits };
     }
     const sha = await resolveRef(gitTop, raw);
     if (!sha) {
-        return { error: "source_not_found", raw };
+        return { error: ERROR_CODES.SOURCE_NOT_FOUND, raw };
     }
     return { raw, kind: "sha", commits: [sha] };
 }
@@ -149,26 +150,26 @@ export function registerGitCherryPickTool(server) {
             const startBranch = await getCurrentBranch(gitTop);
             const onto = args.onto?.trim() || startBranch;
             if (!onto)
-                return jsonRespond({ error: "onto_detached_head" });
+                return jsonRespond({ error: ERROR_CODES.ONTO_DETACHED_HEAD });
             if (args.onto !== undefined && !isSafeGitRefToken(args.onto)) {
-                return jsonRespond({ error: "unsafe_ref_token", ref: args.onto });
+                return jsonRespond({ error: ERROR_CODES.UNSAFE_REF_TOKEN, ref: args.onto });
             }
             // --- Refuse dirty tree ---
             if (!(await isWorkingTreeClean(gitTop))) {
-                return jsonRespond({ error: "working_tree_dirty" });
+                return jsonRespond({ error: ERROR_CODES.WORKING_TREE_DIRTY });
             }
             // --- Ensure destination is checked out ---
             if (onto !== startBranch) {
                 const co = await spawnGitAsync(gitTop, ["checkout", onto]);
                 if (!co.ok) {
                     return jsonRespond({
-                        error: "checkout_failed",
+                        error: ERROR_CODES.CHECKOUT_FAILED,
                         detail: (co.stderr || co.stdout).trim(),
                     });
                 }
             }
             if (!(await resolveRef(gitTop, onto))) {
-                return jsonRespond({ error: "destination_not_found", ref: onto });
+                return jsonRespond({ error: ERROR_CODES.DESTINATION_NOT_FOUND, ref: onto });
             }
             // --- Resolve each source ---
             const resolved = [];

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

@@ -1,5 +1,6 @@
 import { matchesGlob } from "node:path";
 import { z } from "zod";
+import { ERROR_CODES } from "./error-codes.js";
 import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
 import { requireSingleRepo } from "./roots.js";
@@ -230,7 +231,7 @@ export function registerGitDiffSummaryTool(server) {
             const statResult = await spawnGitAsync(gitTop, ["diff", "--numstat", ...diffArgs]);
             if (!statResult.ok) {
                 return jsonRespond({
-                    error: "git_diff_failed",
+                    error: ERROR_CODES.GIT_DIFF_FAILED,
                     detail: (statResult.stderr || statResult.stdout).trim(),
                 });
             }
@@ -239,7 +240,7 @@ export function registerGitDiffSummaryTool(server) {
             const diffResult = await spawnGitAsync(gitTop, ["diff", ...diffArgs]);
             if (!diffResult.ok) {
                 return jsonRespond({
-                    error: "git_diff_failed",
+                    error: ERROR_CODES.GIT_DIFF_FAILED,
                     detail: (diffResult.stderr || diffResult.stdout).trim(),
                 });
             }