@rethunk/mcp-multi-root-git 2.2.0 → 2.3.1

package/AGENTS.md

@@ -16,25 +16,31 @@ 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/roots.ts`](src/server/roots.ts) | `requireGitAndRoots` — sole public export; session root resolution |
+| [`src/server/roots.ts`](src/server/roots.ts) | `requireGitAndRoots`, `requireSingleRepo` — shared tool preludes; session root resolution |
 | [`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` |
 | [`src/server/inventory.ts`](src/server/inventory.ts) | `InventoryEntryJson`, `validateRepoPath`, `makeSkipEntry`, `buildInventorySectionMarkdown`, `collectInventoryEntry` |
+| [`src/server/git-refs.ts`](src/server/git-refs.ts) | `isProtectedBranch`, `isSafeGitRefToken`, `isSafeGitRangeToken`, `isSafeGitAncestorRef`; `getCurrentBranch`, `resolveRef`, `isWorkingTreeClean`, `isFullyMergedInto`, `commitListBetween`; `listWorktrees`, `worktreeForBranch`; `conflictPaths` |
 | [`src/server/tools.ts`](src/server/tools.ts) | `registerRethunkGitTools` — dispatches to `register*` below |
 | [`src/server/git-status-tool.ts`](src/server/git-status-tool.ts) | `git_status` |
 | [`src/server/git-inventory-tool.ts`](src/server/git-inventory-tool.ts) | `git_inventory` |
 | [`src/server/git-parity-tool.ts`](src/server/git-parity-tool.ts) | `git_parity` |
 | [`src/server/list-presets-tool.ts`](src/server/list-presets-tool.ts) | `list_presets` |
-| [`src/server/git-log-tool.ts`](src/server/git-log-tool.ts) | `git_log` |
+| [`src/server/git-log-tool.ts`](src/server/git-log-tool.ts) | `git_log` — v3 JSON shape: `sha` (full), `workspaceRoot`, no `sha7`/`ageRelative`, optional `email` |
 | [`src/server/git-diff-summary-tool.ts`](src/server/git-diff-summary-tool.ts) | `git_diff_summary` — structured token-efficient diff viewer; read-only |
-| [`src/server/batch-commit-tool.ts`](src/server/batch-commit-tool.ts) | `batch_commit` — sequential multi-commit; mutating |
+| [`src/server/git-worktree-tool.ts`](src/server/git-worktree-tool.ts) | `git_worktree_list`, `git_worktree_add`, `git_worktree_remove` |
+| [`src/server/batch-commit-tool.ts`](src/server/batch-commit-tool.ts) | `batch_commit` — sequential multi-commit; mutating; exports `PushReport`, `runPushAfter` |
+| [`src/server/git-push-tool.ts`](src/server/git-push-tool.ts) | `git_push` — standalone push with optional upstream tracking |
+| [`src/server/git-merge-tool.ts`](src/server/git-merge-tool.ts) | `git_merge` — mutating |
+| [`src/server/git-cherry-pick-tool.ts`](src/server/git-cherry-pick-tool.ts) | `git_cherry_pick` — mutating |
+| [`src/server/git-reset-soft-tool.ts`](src/server/git-reset-soft-tool.ts) | `git_reset_soft` — soft-reset; mutating |
 | [`src/server/presets-resource.ts`](src/server/presets-resource.ts) | `rethunk-git://presets` resource |
 | [`src/repo-paths.ts`](src/repo-paths.ts) | `resolvePathForRepo`, `assertRelativePathUnderTop`, `isStrictlyUnderGitTop` |
 
 ## Changing contracts
 
 - **No banner paragraphs** in shipped docs. Use normal titles + cross-links.
-- **JSON format version** (currently `"2"`, 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.
+- **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.
 - **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). Install/client wiring → [docs/install.md](docs/install.md) only. `.cursor/rules/rethunk-git-mcp.mdc` → only when *MCP-vs-shell* guidance changes.
 
@@ -53,7 +59,3 @@ Dogfood from clone: [docs/install.md](docs/install.md) — *From source*.
 Repo ships `.cursor/` with alwaysApply rule [`.cursor/rules/rethunk-git-mcp.mdc`](.cursor/rules/rethunk-git-mcp.mdc) covering MCP-vs-shell usage. Rule does not re-link this file (already injected).
 
 User-level skills may mention README for discovery. Canonical refs: tools/JSON → [docs/mcp-tools.md](docs/mcp-tools.md); install → [docs/install.md](docs/install.md); presets → [HUMANS.md](HUMANS.md).
-
-## Commits
-
-Conventional Commits. Small themed commits. Why-focused messages. Stage + commit in one invocation per batch.

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 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.3.1] — 2026-04-21
+
+Documentation-only patch following the 2.3.0 release.
+
+### Documentation
+
+- **`README.md`** — one-liner description updated to include `git_log`, `git_push`, `git_worktree_*`, and `git_reset_soft`.
+- **`HUMANS.md`** — opening line corrected from "Read-only MCP git tools" to "MCP git tools" (mutating operations have been present since v2.2.0).
+- **`docs/mcp-tools.md`** — overview table expanded from 9 to 14 rows, adding all tools introduced in v2.3.0; **Read-only** / **Mutating** annotations added to every row consistently.
+
+## [2.3.0] — 2026-04-21
+
+Five new tools, a token-efficiency sweep, a targeted breaking change to the `git_log` JSON contract, and test coverage raised from 70% to 89%.
+
+### Added
+
+- **`git_push`** — push the current branch to its configured upstream. Accepts explicit `remote` / `branch` overrides and a `setUpstream: true` flag for first-push (`git push -u`). Refuses on detached HEAD; does not force-push.
+- **`git_worktree_list`** — list all git worktrees (`git worktree list --porcelain`); annotated `readOnlyHint: true`.
+- **`git_worktree_add`** — create a new linked worktree, creating the branch from `baseRef` if it does not yet exist. Refuses on protected branch names (`main`, `master`, `dev`, `release*`, `hotfix*`, …).
+- **`git_worktree_remove`** — remove a registered worktree; refuses to remove the main worktree. Optional `force: true` for dirty trees.
+- **`git_reset_soft`** — soft-reset the current branch to a ref (`HEAD~1`, `HEAD~N`, SHA, branch name). Preserves rewound changes in the staging index — the canonical way to re-split an already-committed chunk. Requires a clean working tree.
+
+### Changed — breaking (`git_log` JSON, `MCP_JSON_FORMAT_VERSION` → `"3"`)
+
+Consumers using `format: "json"` with `git_log` must update field names. All other tools are unaffected.
+
+- `sha7` removed — was always derivable as `sha.slice(0, 7)`.
+- `ageRelative` removed — was human-readable noise in machine output.
+- `workspace_root` renamed to `workspaceRoot` — consistent camelCase with all other fields.
+- `email` is now omitted when empty rather than always present.
+- Error code `not_a_git_repo` corrected to `not_a_git_repository` — consistent with all other tools.
+
+### Changed — non-breaking
+
+- **Token efficiency:** `readOnlyHint: true` added to `git_status`, `git_inventory`, `git_parity`, and `list_presets`. "See docs/mcp-tools.md" suffix dropped from all 9 tool descriptions; descriptions are now self-contained.
+- **`WorkspacePickSchema`** — `rootIndex` and `allWorkspaceRoots` parameters carry inline descriptions so LLMs can pick them without consulting external docs.
+- **`git_merge`** — protected-branch list in the description collapsed to a single canonical reference (was duplicated inline).
+
+### Internal
+
+- `requireSingleRepo` helper extracted to `roots.ts`; replaces copy-paste preludes across `batch_commit`, `git_diff_summary`, `git_merge`, `git_cherry_pick`, `git_push`, `git_reset_soft`, and all `git_worktree_*`.
+- `conflictPaths` extracted from `git-merge-tool.ts` to `git-refs.ts`; shared by `git_merge` and `git_cherry_pick`.
+- `inferRemoteFromUpstream` extracted to `git-refs.ts`; shared by `runPushAfter` (`batch_commit`) and `git_push`.
+- `isWorkingTreeClean` used consistently everywhere (was inlined in `git_reset_soft`).
+
+### Tests
+
+- Coverage: **88.6% lines / 92.8% functions** (up from 69.9% / 71.4%).
+- 262 tests across 15 files (up from 134 across 7 files).
+- New test files: `presets.test.ts`, `inventory.test.ts`, `git-utils.test.ts`, `json.test.ts`, `git-reset-soft-tool.test.ts`, `git-push-tool.test.ts`, `git-worktree-tool.test.ts`, `roots.test.ts`. `git-refs.test.ts` extended with `isSafeGitAncestorRef` cases.
+
+### Documentation
+
+- `docs/mcp-tools.md` — all new tools documented with parameter tables, JSON shapes, and error-code tables.
+- `AGENTS.md` — implementation map updated with all new and refactored modules.
+
 ## [2.2.0] — 2026-04-17
 
 Mutating git operations: merge, cherry-pick, and optional push-after for `batch_commit`.
@@ -41,6 +97,8 @@ Mutating git operations: merge, cherry-pick, and optional push-after for `batch_
 
 - Initial release: `git_status`, `git_inventory`, `git_parity`, `list_presets`.
 
+[2.3.1]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.3.1
+[2.3.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.3.0
 [2.2.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.2.0
 [2.1.0]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.1.0
 [2.0.1]: https://github.com/Rethunk-AI/mcp-multi-root-git/releases/tag/v2.0.1

package/HUMANS.md

@@ -1,6 +1,6 @@
 # @rethunk/mcp-multi-root-git — User guide
 
-Read-only MCP git tools for any workspace. **How the server is installed and wired to clients:** **[docs/install.md](docs/install.md)** only (do not restate that material here).
+MCP git tools for any workspace. **How the server is installed and wired to clients:** **[docs/install.md](docs/install.md)** only (do not restate that material here).
 
 ## Badges
 

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: read-only status, multi-root inventory, `HEAD` parity, presets, structured diff viewer, batch commit, merge, and cherry-pick. **Install and MCP client wiring:** **[docs/install.md](docs/install.md)** only — do not duplicate those steps elsewhere.
+**git** tools over MCP: read-only status, multi-root inventory, `HEAD` parity, presets, structured diff viewer, log, push, worktrees, soft-reset, batch commit, merge, and cherry-pick. **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,9 +1,9 @@
 import { z } from "zod";
 import { isStrictlyUnderGitTop, resolvePathForRepo } from "../repo-paths.js";
-import { gitTopLevel, spawnGitAsync } from "./git.js";
-import { getCurrentBranch } from "./git-refs.js";
+import { spawnGitAsync } from "./git.js";
+import { getCurrentBranch, inferRemoteFromUpstream } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
-import { requireGitAndRoots } from "./roots.js";
+import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
 const CommitEntrySchema = z.object({
     message: z.string().min(1).describe("Commit message."),
@@ -20,41 +20,26 @@ const PushModeSchema = z
  * After all commits succeed, push the current branch to its upstream.
  * Commits are already applied at this point — do NOT attempt rollback on push failure.
  */
-async function runPushAfter(gitTop) {
+export async function runPushAfter(gitTop) {
     const branch = await getCurrentBranch(gitTop);
     if (!branch) {
         return { ok: false, error: "push_detached_head" };
     }
-    // Verify upstream exists before attempting push (avoids side effects of auto-set-upstream).
-    const upstreamProbe = await spawnGitAsync(gitTop, [
-        "rev-parse",
-        "--abbrev-ref",
-        "--symbolic-full-name",
-        "@{u}",
-    ]);
-    if (!upstreamProbe.ok) {
-        return {
-            ok: false,
-            branch,
-            error: "push_no_upstream",
-            detail: (upstreamProbe.stderr || upstreamProbe.stdout).trim(),
-        };
+    const t = await inferRemoteFromUpstream(gitTop);
+    if (!t.ok) {
+        return { ok: false, branch, error: "push_no_upstream", detail: t.detail };
     }
-    const upstream = upstreamProbe.stdout.trim();
-    // Explicit remote + branch so a future push refspec change to the upstream does not surprise us.
-    const slash = upstream.indexOf("/");
-    const remote = slash > 0 ? upstream.slice(0, slash) : "origin";
-    const pushResult = await spawnGitAsync(gitTop, ["push", remote, branch]);
+    const pushResult = await spawnGitAsync(gitTop, ["push", t.remote, branch]);
     if (!pushResult.ok) {
         return {
             ok: false,
             branch,
-            upstream,
+            upstream: t.upstream,
             error: "push_failed",
             detail: (pushResult.stderr || pushResult.stdout).trim(),
         };
     }
-    return { ok: true, branch, upstream };
+    return { ok: true, branch, upstream: t.upstream };
 }
 export function registerBatchCommitTool(server) {
     server.addTool({
@@ -62,7 +47,7 @@ export function registerBatchCommitTool(server) {
         description: "Create multiple sequential git commits in a single call. " +
             "Each entry stages the listed files then commits with the given message. " +
             'Stops on first failure. Optional `push: "after"` pushes the current branch ' +
-            "to its upstream once all commits succeed. See docs/mcp-tools.md.",
+            "to its upstream once all commits succeed.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -77,17 +62,10 @@ export function registerBatchCommitTool(server) {
             push: PushModeSchema,
         }),
         execute: async (args) => {
-            const pre = requireGitAndRoots(server, args, undefined);
+            const pre = requireSingleRepo(server, args);
             if (!pre.ok)
                 return jsonRespond(pre.error);
-            const rootInput = pre.roots[0];
-            if (!rootInput) {
-                return jsonRespond({ error: "no_workspace_root" });
-            }
-            const gitTop = gitTopLevel(rootInput);
-            if (!gitTop) {
-                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
-            }
+            const gitTop = pre.gitTop;
             const results = [];
             for (let i = 0; i < args.commits.length; i++) {
                 const entry = args.commits[i];

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

@@ -1,21 +1,12 @@
 import { z } from "zod";
-import { gitTopLevel, spawnGitAsync } from "./git.js";
-import { commitListBetween, getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRangeToken, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
+import { spawnGitAsync } from "./git.js";
+import { commitListBetween, conflictPaths, getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRangeToken, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
-import { requireGitAndRoots } from "./roots.js";
+import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-async function conflictPaths(gitTop) {
-    const r = await spawnGitAsync(gitTop, ["diff", "--name-only", "--diff-filter=U"]);
-    if (!r.ok)
-        return [];
-    return r.stdout
-        .split("\n")
-        .map((l) => l.trim())
-        .filter((l) => l.length > 0);
-}
 async function cherryPickHead(gitTop) {
     const r = await spawnGitAsync(gitTop, ["rev-parse", "--verify", "--quiet", "CHERRY_PICK_HEAD"]);
     if (!r.ok)
@@ -106,7 +97,7 @@ export function registerGitCherryPickTool(server) {
             "`A..B` ranges, or branch names (expanded to `onto..<branch>`, oldest-first). " +
             "Commits already reachable from the destination are skipped. Refuses on dirty tree; " +
             "stops on the first conflict and reports paths. Optional flags auto-delete fully " +
-            "merged source branches and their worktrees, skipping protected names. See docs/mcp-tools.md.",
+            "merged source branches and their worktrees, skipping protected names.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -138,15 +129,10 @@ export function registerGitCherryPickTool(server) {
                 "(`git worktree remove`). Protected tails always skipped."),
         }),
         execute: async (args) => {
-            const pre = requireGitAndRoots(server, args, undefined);
+            const pre = requireSingleRepo(server, args);
             if (!pre.ok)
                 return jsonRespond(pre.error);
-            const rootInput = pre.roots[0];
-            if (!rootInput)
-                return jsonRespond({ error: "no_workspace_root" });
-            const gitTop = gitTopLevel(rootInput);
-            if (!gitTop)
-                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
+            const gitTop = pre.gitTop;
             // --- Resolve destination ---
             const startBranch = await getCurrentBranch(gitTop);
             const onto = args.onto?.trim() || startBranch;

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

@@ -1,8 +1,8 @@
 import { matchesGlob } from "node:path";
 import { z } from "zod";
-import { gitTopLevel, isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
+import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
-import { requireGitAndRoots } from "./roots.js";
+import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -156,7 +156,7 @@ export function registerGitDiffSummaryTool(server) {
         name: "git_diff_summary",
         description: "Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions, " +
             "truncated to configurable line limits, with noise files (lock files, dist, etc.) excluded by default. " +
-            "Use `range` to target staged, HEAD, or any revision range. See docs/mcp-tools.md.",
+            "Use `range` to target staged, HEAD, or any revision range.",
         annotations: {
             readOnlyHint: true,
         },
@@ -192,17 +192,10 @@ export function registerGitDiffSummaryTool(server) {
                 .describe("Glob patterns to exclude. Defaults to common noise: lock files, dist, vendor, etc."),
         }),
         execute: async (args) => {
-            // --- Standard prelude ---
-            const pre = requireGitAndRoots(server, args, undefined);
+            const pre = requireSingleRepo(server, args);
             if (!pre.ok)
                 return jsonRespond(pre.error);
-            const rootInput = pre.roots[0];
-            if (!rootInput)
-                return jsonRespond({ error: "no_workspace_root" });
-            const gitTop = gitTopLevel(rootInput);
-            if (!gitTop) {
-                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
-            }
+            const gitTop = pre.gitTop;
             // --- Build git diff args ---
             const diffArgsResult = buildDiffArgs(args.range);
             if (!diffArgsResult.ok) {

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

@@ -8,7 +8,10 @@ import { MAX_INVENTORY_ROOTS_DEFAULT, WorkspacePickSchema } from "./schemas.js";
 export function registerGitInventoryTool(server) {
     server.addTool({
         name: "git_inventory",
-        description: "Read-only status + ahead/behind per root. See docs/mcp-tools.md.",
+        description: "Read-only status + ahead/behind per root.",
+        annotations: {
+            readOnlyHint: true,
+        },
         parameters: WorkspacePickSchema.extend({
             nestedRoots: z.array(z.string()).optional(),
             preset: z.string().optional(),

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

@@ -14,12 +14,13 @@ const DEFAULT_SINCE = "7.days";
 // The format string itself is safe ASCII; git emits the byte.
 const FIELD_SEP_OUT = "\x01"; // what git outputs (SOH)
 const RECORD_SEP_OUT = "\x02"; // what git outputs (STX) — used as record-START marker
-// git log --pretty tformat: sha7, shaFull, subject, author, email, ISO date, relative date.
+// git log --pretty tformat: shaFull, subject, author, email, ISO date.
+// sha7 and ageRelative dropped in v3 (shaFull.slice(0,7) used for display; date is ISO).
 // %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).
-const PRETTY_FORMAT = "%x02%h%x01%H%x01%s%x01%aN%x01%aE%x01%aI%x01%ar%x01";
+const PRETTY_FORMAT = "%x02%H%x01%s%x01%aN%x01%aE%x01%aI%x01";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -101,18 +102,16 @@ async function runGitLog(opts) {
         const fieldsPart = newlineIdx >= 0 ? chunk.slice(0, newlineIdx) : chunk;
         const statPart = newlineIdx >= 0 ? chunk.slice(newlineIdx + 1) : "";
         const fields = fieldsPart.split(FIELD_SEP_OUT);
-        const [sha7, shaFull, subject, authorName, email, date, ageRelative] = fields;
-        if (!sha7 || !shaFull)
+        const [shaFull, subject, authorName, email, date] = fields;
+        if (!shaFull)
             continue;
         const stat = parseShortstat(statPart);
         const commit = {
-            sha7: sha7.trim(),
-            shaFull: shaFull.trim(),
+            sha: shaFull.trim(),
             subject: subject?.trim() ?? "",
             author: authorName?.trim() ?? "",
-            email: email?.trim() ?? "",
+            ...spreadDefined("email", email?.trim() || undefined),
             date: date?.trim() ?? "",
-            ageRelative: ageRelative?.trim() ?? "",
             ...spreadDefined("filesChanged", stat?.filesChanged),
             ...spreadDefined("insertions", stat?.insertions),
             ...spreadDefined("deletions", stat?.deletions),
@@ -123,7 +122,7 @@ async function runGitLog(opts) {
     const commits = truncated ? allCommits.slice(0, maxCommits) : allCommits;
     const omittedCount = truncated ? allCommits.length - maxCommits : 0;
     return {
-        workspace_root: top,
+        workspaceRoot: top,
         repo: basename(top),
         branch: resolvedBranch,
         commits,
@@ -137,14 +136,14 @@ async function runGitLog(opts) {
 function renderLogMarkdown(group, filterSummary) {
     const lines = [];
     lines.push(`### ${group.repo} (${group.branch})${filterSummary ? `  —  ${filterSummary}` : ""}`);
-    lines.push(`_root: ${group.workspace_root}_`);
+    lines.push(`_root: ${group.workspaceRoot}_`);
     lines.push("");
     if (group.commits.length === 0) {
         lines.push("_(no commits match)_");
     }
     else {
         for (const c of group.commits) {
-            lines.push(`- \`${c.sha7}\`  ${c.ageRelative}  ${c.subject}  —  ${c.author}`);
+            lines.push(`- \`${c.sha.slice(0, 7)}\`  ${c.date.slice(0, 10)}  ${c.subject}  —  ${c.author}`);
         }
     }
     if (group.truncated) {
@@ -160,8 +159,7 @@ export function registerGitLogTool(server) {
     server.addTool({
         name: "git_log",
         description: "Path-filtered, time-windowed read-only `git log` across one or more workspace roots. " +
-            "Returns structured commit history with author, date, subject, and optional diff stats. " +
-            "See docs/mcp-tools.md.",
+            "Returns structured commit history with author, date, subject, and optional diff stats.",
         annotations: {
             readOnlyHint: true,
         },
@@ -216,7 +214,7 @@ export function registerGitLogTool(server) {
             const results = await asyncPool(jobs, GIT_SUBPROCESS_PARALLELISM, async ({ rootInput }) => {
                 const top = gitTopLevel(rootInput);
                 if (!top) {
-                    return { _error: true, workspace_root: rootInput, error: "not_a_git_repo" };
+                    return { _error: true, workspaceRoot: rootInput, error: "not_a_git_repository" };
                 }
                 const r = await runGitLog({
                     top,
@@ -228,7 +226,7 @@ export function registerGitLogTool(server) {
                     branch: args.branch,
                 });
                 if ("error" in r) {
-                    return { _error: true, workspace_root: rootInput, error: r.error };
+                    return { _error: true, workspaceRoot: rootInput, error: r.error };
                 }
                 return { _error: false, ...r };
             });
@@ -245,8 +243,8 @@ export function registerGitLogTool(server) {
                 const groups = results.map((r) => {
                     if (r._error) {
                         return {
-                            workspace_root: r.workspace_root,
-                            repo: basename(r.workspace_root),
+                            workspaceRoot: r.workspaceRoot,
+                            repo: basename(r.workspaceRoot ?? ""),
                             branch: "",
                             commits: [],
                             ...spreadWhen(true, { error: r.error }),
@@ -264,7 +262,7 @@ export function registerGitLogTool(server) {
             const mdChunks = ["# Git log"];
             for (const r of results) {
                 if (r._error) {
-                    mdChunks.push(`### ${r.workspace_root}\n_error: ${r.error}_`);
+                    mdChunks.push(`### ${r.workspaceRoot}\n_error: ${r.error}_`);
                     continue;
                 }
                 const { _error: _e, ...group } = r;

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

@@ -1,8 +1,8 @@
 import { z } from "zod";
-import { gitTopLevel, spawnGitAsync } from "./git.js";
-import { getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
+import { spawnGitAsync } from "./git.js";
+import { conflictPaths, getCurrentBranch, isFullyMergedInto, isProtectedBranch, isSafeGitRefToken, isWorkingTreeClean, resolveRef, worktreeForBranch, } from "./git-refs.js";
 import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
-import { requireGitAndRoots } from "./roots.js";
+import { requireSingleRepo } from "./roots.js";
 import { WorkspacePickSchema } from "./schemas.js";
 // ---------------------------------------------------------------------------
 // Schemas
@@ -16,17 +16,8 @@ const StrategySchema = z
     "`rebase`: rebase source onto destination, then fast-forward (no merge-commit fallback). " +
     "`merge`: always create a merge commit (no fast-forward).");
 // ---------------------------------------------------------------------------
-// Conflict helpers
+// Abort helpers
 // ---------------------------------------------------------------------------
-async function conflictPaths(gitTop) {
-    const r = await spawnGitAsync(gitTop, ["diff", "--name-only", "--diff-filter=U"]);
-    if (!r.ok)
-        return [];
-    return r.stdout
-        .split("\n")
-        .map((l) => l.trim())
-        .filter((l) => l.length > 0);
-}
 async function abortMerge(gitTop) {
     await spawnGitAsync(gitTop, ["merge", "--abort"]);
 }
@@ -220,7 +211,7 @@ export function registerGitMergeTool(server) {
             "Refuses if the working tree is dirty. Stops on the first conflict and reports " +
             "the affected paths. Optional flags auto-delete merged branches and worktrees, " +
             "skipping protected names (main, master, dev, develop, stable, trunk, prod, " +
-            "production, release/*, hotfix/*). See docs/mcp-tools.md.",
+            "production, release/*, hotfix/*).",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -246,8 +237,7 @@ export function registerGitMergeTool(server) {
                 .optional()
                 .default(false)
                 .describe("After all sources merge cleanly, delete each source branch locally (`git branch -d`). " +
-                "Protected names (main, master, dev, develop, stable, trunk, prod, production, " +
-                "release/*, hotfix/*) are always skipped. Never affects remote branches."),
+                "Protected names always skipped. Never affects remote branches."),
             deleteMergedWorktrees: z
                 .boolean()
                 .optional()
@@ -256,15 +246,10 @@ export function registerGitMergeTool(server) {
                 "on a source branch (`git worktree remove`). Protected tails always skipped."),
         }),
         execute: async (args) => {
-            const pre = requireGitAndRoots(server, args, undefined);
+            const pre = requireSingleRepo(server, args);
             if (!pre.ok)
                 return jsonRespond(pre.error);
-            const rootInput = pre.roots[0];
-            if (!rootInput)
-                return jsonRespond({ error: "no_workspace_root" });
-            const gitTop = gitTopLevel(rootInput);
-            if (!gitTop)
-                return jsonRespond({ error: "not_a_git_repository", path: rootInput });
+            const gitTop = pre.gitTop;
             // --- Validate ref tokens early ---
             for (const s of args.sources) {
                 if (!isSafeGitRefToken(s)) {

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

@@ -8,7 +8,10 @@ import { WorkspacePickSchema } from "./schemas.js";
 export function registerGitParityTool(server) {
     server.addTool({
         name: "git_parity",
-        description: "Read-only HEAD parity for path pairs. See docs/mcp-tools.md.",
+        description: "Read-only HEAD parity for path pairs.",
+        annotations: {
+            readOnlyHint: true,
+        },
         parameters: WorkspacePickSchema.extend({
             pairs: z
                 .array(z.object({

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

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { isSafeGitUpstreamToken, spawnGitAsync } from "./git.js";
+import { getCurrentBranch, inferRemoteFromUpstream, isSafeGitRefToken } from "./git-refs.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+export function registerGitPushTool(server) {
+    server.addTool({
+        name: "git_push",
+        description: "Push the current branch to its configured upstream. " +
+            "Use `setUpstream: true` to set tracking (`-u`) when no upstream is configured yet. " +
+            "Refuses on detached HEAD. Does not force-push.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            remote: z
+                .string()
+                .optional()
+                .describe("Remote to push to. Defaults to the remote inferred from the current upstream tracking " +
+                "ref, or `origin` when `setUpstream` is true."),
+            branch: z
+                .string()
+                .optional()
+                .describe("Branch to push. Defaults to the currently checked-out branch. " +
+                "Rejected when HEAD is detached."),
+            setUpstream: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Set the upstream tracking reference (`git push -u`). " +
+                "Use when the branch has not been pushed yet. Remote defaults to `origin`."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // --- Resolve branch ---
+            const currentBranch = await getCurrentBranch(gitTop);
+            const branch = args.branch?.trim() || currentBranch;
+            if (!branch) {
+                return jsonRespond({ error: "push_detached_head" });
+            }
+            if (!isSafeGitRefToken(branch)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: branch });
+            }
+            // --- Resolve remote ---
+            let remote;
+            if (args.remote?.trim()) {
+                if (!isSafeGitUpstreamToken(args.remote.trim())) {
+                    return jsonRespond({ error: "unsafe_remote_token", remote: args.remote.trim() });
+                }
+                remote = args.remote.trim();
+            }
+            else if (args.setUpstream) {
+                // No explicit remote and we're setting upstream — default to origin.
+                remote = "origin";
+            }
+            else {
+                // Infer remote from existing upstream tracking ref.
+                const t = await inferRemoteFromUpstream(gitTop);
+                if (!t.ok) {
+                    return jsonRespond({
+                        error: "push_no_upstream",
+                        branch,
+                        detail: t.detail,
+                    });
+                }
+                remote = t.remote;
+            }
+            // --- Push ---
+            const pushArgs = ["push"];
+            if (args.setUpstream)
+                pushArgs.push("-u");
+            pushArgs.push(remote, branch);
+            const pushResult = await spawnGitAsync(gitTop, pushArgs);
+            if (!pushResult.ok) {
+                return jsonRespond({
+                    ok: false,
+                    branch,
+                    remote,
+                    error: "push_failed",
+                    detail: (pushResult.stderr || pushResult.stdout).trim(),
+                });
+            }
+            // Probe the upstream tracking ref now (may have been set by -u).
+            const upstreamProbe = await spawnGitAsync(gitTop, [
+                "rev-parse",
+                "--abbrev-ref",
+                "--symbolic-full-name",
+                "@{u}",
+            ]);
+            const upstream = upstreamProbe.ok ? upstreamProbe.stdout.trim() : `${remote}/${branch}`;
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: true,
+                    branch,
+                    remote,
+                    upstream,
+                    ...spreadDefined("setUpstream", args.setUpstream || undefined),
+                });
+            }
+            return `# Push\n✓ ${branch} → ${upstream}`;
+        },
+    });
+}