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

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,52 @@
 
 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.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 +87,7 @@ Mutating git operations: merge, cherry-pick, and optional push-after for `batch_
 
 - Initial release: `git_status`, `git_inventory`, `git_parity`, `list_presets`.
 
+[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/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}`;
+        },
+    });
+}

package/dist/server/git-refs.js

@@ -1,5 +1,18 @@
 import { spawnGitAsync } from "./git.js";
 // ---------------------------------------------------------------------------
+// Merge conflict helpers (shared between git_merge and git_cherry_pick)
+// ---------------------------------------------------------------------------
+/** Paths with unresolved merge conflicts (`--diff-filter=U`). */
+export 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);
+}
+// ---------------------------------------------------------------------------
 // Protected branch names — never auto-delete, never cascade destructive ops onto
 // ---------------------------------------------------------------------------
 const PROTECTED_EXACT = new Set([
@@ -48,6 +61,18 @@ export function isSafeGitRefToken(s) {
         return false;
     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.
+ */
+export function isSafeGitAncestorRef(s) {
+    const t = s.trim();
+    if (t.length === 0 || t.length > 256)
+        return false;
+    if (t.startsWith("-"))
+        return false;
+    return /^[A-Za-z0-9_./+~^-]+$/.test(t);
+}
 /**
  * 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.
@@ -149,3 +174,19 @@ export async function worktreeForBranch(cwd, branch) {
     const hit = trees.find((t) => t.branch === branch);
     return hit?.path ?? null;
 }
+// ---------------------------------------------------------------------------
+// Push helpers
+// ---------------------------------------------------------------------------
+/**
+ * Probe `@{u}` and extract the remote name from the tracking ref.
+ * Returns an error payload when no upstream is configured.
+ */
+export async function inferRemoteFromUpstream(cwd) {
+    const r = await spawnGitAsync(cwd, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    if (!r.ok)
+        return { ok: false, detail: (r.stderr || r.stdout).trim() };
+    const upstream = r.stdout.trim();
+    const slash = upstream.indexOf("/");
+    const remote = slash > 0 ? upstream.slice(0, slash) : "origin";
+    return { ok: true, remote, upstream };
+}

package/dist/server/git-reset-soft-tool.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { spawnGitAsync } from "./git.js";
+import { isSafeGitAncestorRef, isWorkingTreeClean } from "./git-refs.js";
+import { jsonRespond, spreadDefined } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+export function registerGitResetSoftTool(server) {
+    server.addTool({
+        name: "git_reset_soft",
+        description: "Soft-reset the current branch to a reference (`git reset --soft <ref>`). " +
+            "Moves the branch pointer back while keeping all changes from the rewound commits " +
+            "in the staging index — use this to re-split an already-committed chunk. " +
+            "Refuses when the working tree has any uncommitted or unstaged changes (run on a clean tree).",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            ref: z
+                .string()
+                .min(1)
+                .describe("Commit to reset to. Accepts ancestor notation (`HEAD~1`, `HEAD~3`), " +
+                "branch names, or full SHAs."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // Validate ref — allow ancestor notation (~N, ^N).
+            if (!isSafeGitAncestorRef(args.ref)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.ref });
+            }
+            // Refuse when the working tree is dirty (unstaged or untracked changes).
+            if (!(await isWorkingTreeClean(gitTop))) {
+                return jsonRespond({
+                    error: "working_tree_dirty",
+                    detail: "git_reset_soft requires a clean working tree. " +
+                        "Commit or stash pending changes first.",
+                });
+            }
+            // Probe HEAD before reset for the response.
+            const preSha = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const beforeSha = preSha.ok ? preSha.stdout.trim() : undefined;
+            // Run the reset.
+            const r = await spawnGitAsync(gitTop, ["reset", "--soft", args.ref]);
+            if (!r.ok) {
+                return jsonRespond({
+                    error: "reset_failed",
+                    detail: (r.stderr || r.stdout).trim(),
+                });
+            }
+            // Probe HEAD after reset.
+            const postSha = await spawnGitAsync(gitTop, ["rev-parse", "HEAD"]);
+            const afterSha = postSha.ok ? postSha.stdout.trim() : undefined;
+            // Count staged changes after reset.
+            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,
+                    ref: args.ref,
+                    ...spreadDefined("beforeSha", beforeSha),
+                    ...spreadDefined("afterSha", afterSha),
+                    stagedCount: stagedFiles.length,
+                });
+            }
+            const beforeShort = beforeSha?.slice(0, 7) ?? "?";
+            const afterShort = afterSha?.slice(0, 7) ?? "?";
+            return [
+                "# Reset (soft)",
+                `✓ ${beforeShort} → ${afterShort}  (${stagedFiles.length} file(s) staged)`,
+            ].join("\n");
+        },
+    });
+}

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

@@ -8,7 +8,10 @@ import { WorkspacePickSchema } from "./schemas.js";
 export function registerGitStatusTool(server) {
     server.addTool({
         name: "git_status",
-        description: "Read-only `git status --short -b` per root + submodules. See docs/mcp-tools.md.",
+        description: "Read-only `git status --short -b` per root + submodules.",
+        annotations: {
+            readOnlyHint: true,
+        },
         parameters: WorkspacePickSchema.extend({
             includeSubmodules: z.boolean().optional().default(true),
         }),

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

@@ -0,0 +1,188 @@
+import { resolve } from "node:path";
+import { z } from "zod";
+import { spawnGitAsync } from "./git.js";
+import { isProtectedBranch, isSafeGitRefToken, listWorktrees, } from "./git-refs.js";
+import { jsonRespond, spreadDefined, spreadWhen } from "./json.js";
+import { requireSingleRepo } from "./roots.js";
+import { WorkspacePickSchema } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// git_worktree_list
+// ---------------------------------------------------------------------------
+export function registerGitWorktreeListTool(server) {
+    server.addTool({
+        name: "git_worktree_list",
+        description: "List all git worktrees for the repository (`git worktree list --porcelain`).",
+        annotations: {
+            readOnlyHint: true,
+        },
+        parameters: WorkspacePickSchema.pick({
+            workspaceRoot: true,
+            rootIndex: true,
+            format: true,
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            const trees = await listWorktrees(gitTop);
+            if (args.format === "json") {
+                return jsonRespond({ worktrees: trees });
+            }
+            if (trees.length === 0) {
+                return "# Worktrees\n_(none)_";
+            }
+            const lines = ["# Worktrees", ""];
+            for (const t of trees) {
+                const branchPart = t.branch ?? "(detached)";
+                const headPart = t.head ? ` @ ${t.head.slice(0, 7)}` : "";
+                lines.push(`- \`${t.path}\`  ${branchPart}${headPart}`);
+            }
+            return lines.join("\n");
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// git_worktree_add
+// ---------------------------------------------------------------------------
+export function registerGitWorktreeAddTool(server) {
+    server.addTool({
+        name: "git_worktree_add",
+        description: "Add a new git worktree. If `branch` does not exist it is created from `baseRef` " +
+            "(defaults to HEAD). Refuses to create on a protected branch name.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            path: z
+                .string()
+                .min(1)
+                .describe("Filesystem path for the new worktree. Relative paths are resolved from the git toplevel."),
+            branch: z
+                .string()
+                .min(1)
+                .describe("Branch to check out in the new worktree. Created from `baseRef` if absent."),
+            baseRef: z
+                .string()
+                .optional()
+                .describe("Commit-ish to base the new branch on when it does not yet exist. Default: HEAD."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // Validate branch
+            if (!isSafeGitRefToken(args.branch)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.branch });
+            }
+            if (isProtectedBranch(args.branch)) {
+                return jsonRespond({ error: "protected_branch", branch: args.branch });
+            }
+            if (args.baseRef !== undefined && !isSafeGitRefToken(args.baseRef)) {
+                return jsonRespond({ error: "unsafe_ref_token", ref: args.baseRef });
+            }
+            // Resolve path
+            const wtPath = resolve(gitTop, args.path);
+            // Check if branch already exists
+            const branchCheck = await spawnGitAsync(gitTop, [
+                "show-ref",
+                "--verify",
+                "--quiet",
+                `refs/heads/${args.branch}`,
+            ]);
+            const branchExists = branchCheck.ok;
+            let gitArgs;
+            if (branchExists) {
+                gitArgs = ["worktree", "add", wtPath, args.branch];
+            }
+            else {
+                gitArgs = ["worktree", "add", "-b", args.branch, wtPath];
+                if (args.baseRef)
+                    gitArgs.push(args.baseRef);
+            }
+            const r = await spawnGitAsync(gitTop, gitArgs);
+            if (!r.ok) {
+                return jsonRespond({
+                    ok: false,
+                    error: "worktree_add_failed",
+                    detail: (r.stderr || r.stdout).trim(),
+                });
+            }
+            if (args.format === "json") {
+                return jsonRespond({
+                    ok: true,
+                    path: wtPath,
+                    branch: args.branch,
+                    created: !branchExists,
+                    ...spreadDefined("baseRef", !branchExists ? (args.baseRef ?? "HEAD") : undefined),
+                });
+            }
+            const createdNote = branchExists ? "" : ` (new branch from ${args.baseRef ?? "HEAD"})`;
+            return `# Worktree added\n✓ ${wtPath}  →  ${args.branch}${createdNote}`;
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// git_worktree_remove
+// ---------------------------------------------------------------------------
+export function registerGitWorktreeRemoveTool(server) {
+    server.addTool({
+        name: "git_worktree_remove",
+        description: "Remove a git worktree (`git worktree remove`). " +
+            "Pass `force: true` to remove a worktree with uncommitted changes. " +
+            "Refuses to remove the main worktree.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+        },
+        parameters: WorkspacePickSchema.extend({
+            path: z
+                .string()
+                .min(1)
+                .describe("Path of the worktree to remove. Must not be the main worktree."),
+            force: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Pass `--force` to allow removal of worktrees with uncommitted changes."),
+        }),
+        execute: async (args) => {
+            const pre = requireSingleRepo(server, args);
+            if (!pre.ok)
+                return jsonRespond(pre.error);
+            const { gitTop } = pre;
+            // Refuse to remove the main worktree
+            const wtPath = resolve(gitTop, args.path);
+            if (wtPath === gitTop) {
+                return jsonRespond({ error: "cannot_remove_main_worktree", path: wtPath });
+            }
+            // Verify it exists in the worktree list
+            const trees = await listWorktrees(gitTop);
+            const isRegistered = trees.some((t) => t.path === wtPath || t.path === args.path);
+            if (!isRegistered) {
+                return jsonRespond({ error: "worktree_not_found", path: args.path });
+            }
+            const removeArgs = ["worktree", "remove", wtPath];
+            if (args.force)
+                removeArgs.push("--force");
+            const r = await spawnGitAsync(gitTop, removeArgs);
+            if (!r.ok) {
+                return jsonRespond({
+                    ok: false,
+                    error: "worktree_remove_failed",
+                    detail: (r.stderr || r.stdout).trim(),
+                    ...spreadWhen((r.stderr || r.stdout).includes("contains modified") ||
+                        (r.stderr || r.stdout).includes("is not empty"), { hint: "Pass force: true to remove a worktree with uncommitted changes." }),
+                });
+            }
+            if (args.format === "json") {
+                return jsonRespond({ ok: true, path: wtPath });
+            }
+            return `# Worktree removed\n✓ ${wtPath}`;
+        },
+    });
+}

package/dist/server/list-presets-tool.js

@@ -7,7 +7,10 @@ import { WorkspacePickSchema } from "./schemas.js";
 export function registerListPresetsTool(server) {
     server.addTool({
         name: "list_presets",
-        description: "List presets from .rethunk/git-mcp-presets.json. See docs/mcp-tools.md.",
+        description: "List presets from .rethunk/git-mcp-presets.json.",
+        annotations: {
+            readOnlyHint: true,
+        },
         parameters: WorkspacePickSchema.pick({
             workspaceRoot: true,
             rootIndex: true,

package/dist/server/roots.js

@@ -118,3 +118,20 @@ export function requireGitAndRoots(server, args, presetName) {
     }
     return { ok: true, roots: rootsRes.roots };
 }
+/**
+ * Convenience wrapper for single-repo tools: gate git, resolve roots, pick the first
+ * root, and resolve its git toplevel. Returns `{ ok: true, gitTop }` or a structured
+ * error payload ready for `jsonRespond`.
+ */
+export function requireSingleRepo(server, args, presetName = undefined) {
+    const pre = requireGitAndRoots(server, args, presetName);
+    if (!pre.ok)
+        return pre;
+    const rootInput = pre.roots[0];
+    if (!rootInput)
+        return { ok: false, error: { error: "no_workspace_root" } };
+    const top = gitTopLevel(rootInput);
+    if (!top)
+        return { ok: false, error: { error: "not_a_git_repository", path: rootInput } };
+    return { ok: true, gitTop: top };
+}

package/dist/server/schemas.js

@@ -3,8 +3,17 @@ import { MAX_INVENTORY_ROOTS_DEFAULT } from "./inventory.js";
 const FormatSchema = z.enum(["markdown", "json"]).optional().default("markdown");
 export const WorkspacePickSchema = z.object({
     workspaceRoot: z.string().optional().describe("Highest-priority override."),
-    rootIndex: z.number().int().min(0).optional(),
-    allWorkspaceRoots: z.boolean().optional().default(false),
+    rootIndex: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("0-based index into the MCP file roots list; ignored when workspaceRoot is set."),
+    allWorkspaceRoots: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Fan out across all MCP file roots."),
     format: FormatSchema,
 });
 export { MAX_INVENTORY_ROOTS_DEFAULT };

package/dist/server/test-harness.js

@@ -16,6 +16,9 @@
  *   const result = await tool({ workspaceRoot: dir, commits: [...] });
  *   // result is string (markdown) or JSON-parseable string
  */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 // Stub context — no tool currently uses context
 const STUB_CONTEXT = {
     log: {
@@ -28,6 +31,30 @@ const STUB_CONTEXT = {
     session: undefined,
 };
 // ---------------------------------------------------------------------------
+// Tmp-dir lifecycle — prevents accumulating thousands of leaked test dirs.
+// Each test file must register the hook itself:
+//   afterEach(cleanupTmpPaths);
+// Module-scope afterEach(...) would only register once (first-importer wins)
+// because the module is cached across test files in the same bun test run.
+// ---------------------------------------------------------------------------
+const tmpPaths = [];
+export function mkTmpDir(prefix) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    tmpPaths.push(dir);
+    return dir;
+}
+export function trackTmpPath(path) {
+    tmpPaths.push(path);
+    return path;
+}
+export function cleanupTmpPaths() {
+    while (tmpPaths.length > 0) {
+        const p = tmpPaths.pop();
+        if (p)
+            rmSync(p, { recursive: true, force: true });
+    }
+}
+// ---------------------------------------------------------------------------
 // Fake server
 // ---------------------------------------------------------------------------
 function makeFakeServer() {

package/dist/server/tools.js

@@ -5,18 +5,29 @@ import { registerGitInventoryTool } from "./git-inventory-tool.js";
 import { registerGitLogTool } from "./git-log-tool.js";
 import { registerGitMergeTool } from "./git-merge-tool.js";
 import { registerGitParityTool } from "./git-parity-tool.js";
+import { registerGitPushTool } from "./git-push-tool.js";
+import { registerGitResetSoftTool } from "./git-reset-soft-tool.js";
 import { registerGitStatusTool } from "./git-status-tool.js";
+import { registerGitWorktreeAddTool, registerGitWorktreeListTool, registerGitWorktreeRemoveTool, } from "./git-worktree-tool.js";
 import { registerListPresetsTool } from "./list-presets-tool.js";
 import { registerPresetsResource } from "./presets-resource.js";
 export function registerRethunkGitTools(server) {
+    // Read-only tools
     registerGitStatusTool(server);
     registerGitInventoryTool(server);
     registerGitParityTool(server);
     registerListPresetsTool(server);
-    registerBatchCommitTool(server);
-    registerGitDiffSummaryTool(server);
     registerGitLogTool(server);
+    registerGitDiffSummaryTool(server);
+    registerGitWorktreeListTool(server);
+    // Mutating tools
+    registerBatchCommitTool(server);
+    registerGitPushTool(server);
     registerGitMergeTool(server);
     registerGitCherryPickTool(server);
+    registerGitResetSoftTool(server);
+    registerGitWorktreeAddTool(server);
+    registerGitWorktreeRemoveTool(server);
+    // Resources
     registerPresetsResource(server);
 }

package/docs/mcp-tools.md

@@ -25,9 +25,9 @@ Pass **`format: "json"`** on any tool for structured JSON instead of markdown (d
 
 ## JSON responses
 
-Tool JSON bodies are minified and contain only the payload — no `rethunkGitMcp` envelope. Current `MCP_JSON_FORMAT_VERSION` is **`"2"`**; server + format version are discoverable via MCP `initialize`. Payload keys (`groups`, `inventories`, `parity`, `roots`) are stable within a given format version. Preset-related responses may include **`presetSchemaVersion`**.
+Tool JSON bodies are minified and contain only the payload — no `rethunkGitMcp` envelope. Current `MCP_JSON_FORMAT_VERSION` is **`"3"`**; server + format version are discoverable via MCP `initialize`. Payload keys (`groups`, `inventories`, `parity`, `roots`) are stable within a given format version. Preset-related responses may include **`presetSchemaVersion`**.
 
-### v2 field omission (consumer contract)
+### v2/v3 field omission (consumer contract)
 
 To keep responses compact, **optional fields are omitted when they would be empty, `null`, or `false`** — they are not emitted as `null`. Consumers must test for *presence*, not compare to `null`.
 
@@ -68,17 +68,15 @@ To keep responses compact, **optional fields are omitted when they would be empt
 ```json
 {
   "groups": [{
-    "workspace_root": "/abs/path",
+    "workspaceRoot": "/abs/path",
     "repo": "my-repo",
     "branch": "main",
     "commits": [{
-      "sha7": "a1bf184",
-      "shaFull": "a1bf184c3d...",
+      "sha": "a1bf184c3d…",
       "subject": "feat(satcom): upgrade to PROTOCOL_VERSION 4",
       "author": "Damon Blais",
       "email": "damon@example.com",
       "date": "2026-04-12T18:32:01-07:00",
-      "ageRelative": "42m ago",
       "filesChanged": 4,
       "insertions": 16,
       "deletions": 5
@@ -89,14 +87,16 @@ To keep responses compact, **optional fields are omitted when they would be empt
 }
 ```
 
-v2 field-omission rules: `filesChanged`, `insertions`, `deletions` are omitted when zero/absent (new file with no shortstat). `truncated` and `omittedCount` are omitted when `false`/`0`. A group emits `error` instead of `commits` when git fails for that root.
+v3 changes from v2: `sha7` removed (use `sha.slice(0,7)` for display); `ageRelative` removed (use `date` — ISO 8601); `email` omitted when empty; `workspace_root` renamed to `workspaceRoot` (camelCase consistency).
+
+v2 field-omission rules still apply: `filesChanged`, `insertions`, `deletions` omitted when zero/absent. `truncated` and `omittedCount` omitted when `false`/`0`. A group emits `error` instead of `commits` when git fails for that root.
 
 ### `git_log` — error codes
 
 | Code | Meaning |
 |------|---------|
 | `git_not_found` | `git` binary not on `PATH`. |
-| `not_a_git_repo` | The resolved workspace root is not inside a git repository. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
 | `invalid_since` | The `since` string contains shell metacharacters and was rejected. |
 | `invalid_paths` | One of the `paths` entries contains shell metacharacters and was rejected. |
 | `git_log_failed` | `git log` exited non-zero (e.g. unknown branch ref). |
@@ -339,6 +339,110 @@ Repo state is cleaned (`git cherry-pick --abort`) before returning — no partia
 
 ---
 
+### `git_push` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `remote` | string | Remote to push to. Defaults to the remote inferred from the upstream tracking ref, or `origin` when `setUpstream` is true. |
+| `branch` | string | Branch to push. Defaults to the currently checked-out branch. Rejected on detached HEAD. |
+| `setUpstream` | boolean | Default `false`. Pass `-u` to set the upstream tracking ref; remote defaults to `origin`. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard workspace pick + output format. |
+
+### `git_push` — JSON shape (`format: "json"`)
+
+```json
+{ "ok": true, "branch": "feature/x", "remote": "origin", "upstream": "origin/feature/x" }
+```
+
+### `git_push` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `push_detached_head` | HEAD is detached; no branch name to push. |
+| `push_no_upstream` | Branch has no configured upstream and `setUpstream` was not requested. |
+| `push_failed` | `git push` exited non-zero. `detail` carries stderr. |
+| `unsafe_ref_token` | `branch` value contains characters outside the safe token set. |
+| `unsafe_remote_token` | `remote` value contains disallowed characters. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
+### `git_reset_soft` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `ref` | string | Target commit: `HEAD~N`, branch name, or full/short SHA. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard workspace pick + output format. |
+
+### `git_reset_soft` — JSON shape (`format: "json"`)
+
+```json
+{ "ok": true, "ref": "HEAD~2", "beforeSha": "a1b2c3d…", "afterSha": "f9e8d7c…", "stagedCount": 5 }
+```
+
+### `git_reset_soft` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `unsafe_ref_token` | `ref` contains characters outside the ancestor-safe token set. |
+| `working_tree_dirty` | Working tree has uncommitted/unstaged changes; clean up before resetting. |
+| `status_failed` | `git status` failed unexpectedly. |
+| `reset_failed` | `git reset --soft` failed (e.g. ref does not exist). |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
+### `git_worktree_list` — JSON shape (`format: "json"`)
+
+```json
+{ "worktrees": [{ "path": "/abs/path", "branch": "feature/x", "head": "a1b2c3d…" }] }
+```
+
+`branch` is `null` for detached-HEAD worktrees.
+
+### `git_worktree_add` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `path` | string | Filesystem path for the new worktree. Relative paths are resolved from the git toplevel. |
+| `branch` | string | Branch to check out. Created from `baseRef` if it does not already exist. |
+| `baseRef` | string | Commit-ish for branch creation. Default: `HEAD`. Ignored when `branch` already exists. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard workspace pick + output format. |
+
+### `git_worktree_add` — JSON shape (`format: "json"`)
+
+```json
+{ "ok": true, "path": "/abs/worktree", "branch": "feature/x", "created": true, "baseRef": "main" }
+```
+
+### `git_worktree_add` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `unsafe_ref_token` | `branch` or `baseRef` contains disallowed characters. |
+| `protected_branch` | `branch` is on the protected names list. |
+| `worktree_add_failed` | `git worktree add` exited non-zero. `detail` carries stderr. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+### `git_worktree_remove` — parameters
+
+| Parameter | Type | Notes |
+|-----------|------|-------|
+| `path` | string | Path of the worktree to remove. |
+| `force` | boolean | Default `false`. Pass `--force` to allow removal with uncommitted changes. |
+| `workspaceRoot`, `rootIndex`, `format` | — | Standard workspace pick + output format. |
+
+### `git_worktree_remove` — error codes
+
+| Code | Meaning |
+|------|---------|
+| `cannot_remove_main_worktree` | `path` resolves to the main (non-linked) worktree. |
+| `worktree_not_found` | `path` is not registered as a worktree in this repo. |
+| `worktree_remove_failed` | `git worktree remove` failed. Pass `force: true` if there are uncommitted changes. |
+| `not_a_git_repository` | The resolved workspace root is not inside a git repository. |
+
+---
+
 ## Resource
 
 | URI | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/mcp-multi-root-git",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "MCP stdio server: multi-root git status, inventory, and HEAD parity checks. Generic tools usable by any workspace.",
   "type": "module",
   "private": false,