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

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

@@ -11,12 +11,17 @@ MCP clients expose tools as `{serverName}_{toolName}`. With the server registere
 
 | Short id | Client id (server `rethunk-git`) | Purpose |
 |----------|-----------------------------------|---------|
-| `git_status` | `rethunk-git_git_status` | `git status --short -b` per MCP root and optional submodules (`includeSubmodules`); parallel submodule status. Args include `allWorkspaceRoots`, `rootIndex`, `workspaceRoot`, `format`. |
-| `git_inventory` | `rethunk-git_git_inventory` | Status + ahead/behind per path; default upstream each repo’s `@{u}`; pass **both** `remote` and `branch` for fixed tracking. `nestedRoots`, `preset`, `presetMerge`, `maxRoots`, `format`, plus workspace pick args. |
-| `git_parity` | `rethunk-git_git_parity` | Compare `git rev-parse HEAD` for path pairs. `pairs`, `preset`, `presetMerge`, `format`, plus workspace pick args. |
-| `list_presets` | `rethunk-git_list_presets` | List preset names/counts from `.rethunk/git-mcp-presets.json`; invalid JSON/schema surface as errors. Workspace pick + `format` only. |
-| `git_log` | `rethunk-git_git_log` | Path-filtered, time-windowed `git log` across one or more workspace roots. Returns commit history with author, date, subject, and shortstat. Args: `since`, `paths`, `grep`, `author`, `maxCommits`, `branch`, plus workspace pick args + `format`. |
+| `git_status` | `rethunk-git_git_status` | `git status --short -b` per MCP root and optional submodules (`includeSubmodules`); parallel submodule status. Args include `allWorkspaceRoots`, `rootIndex`, `workspaceRoot`, `format`. **Read-only.** |
+| `git_inventory` | `rethunk-git_git_inventory` | Status + ahead/behind per path; default upstream each repo’s `@{u}`; pass **both** `remote` and `branch` for fixed tracking. `nestedRoots`, `preset`, `presetMerge`, `maxRoots`, `format`, plus workspace pick args. **Read-only.** |
+| `git_parity` | `rethunk-git_git_parity` | Compare `git rev-parse HEAD` for path pairs. `pairs`, `preset`, `presetMerge`, `format`, plus workspace pick args. **Read-only.** |
+| `list_presets` | `rethunk-git_list_presets` | List preset names/counts from `.rethunk/git-mcp-presets.json`; invalid JSON/schema surface as errors. Workspace pick + `format` only. **Read-only.** |
+| `git_log` | `rethunk-git_git_log` | Path-filtered, time-windowed `git log` across one or more workspace roots. Returns commit history with author, date, subject, and shortstat. Args: `since`, `paths`, `grep`, `author`, `maxCommits`, `branch`, plus workspace pick args + `format`. **Read-only.** |
 | `git_diff_summary` | `rethunk-git_git_diff_summary` | Structured, token-efficient diff viewer. Returns per-file diffs with additions/deletions counts, truncated to configurable line limits, with lock files/dist/vendor excluded by default. Args: `range`, `fileFilter`, `maxLinesPerFile`, `maxFiles`, `excludePatterns`, plus workspace pick args + `format`. **Read-only.** |
+| `git_worktree_list` | `rethunk-git_git_worktree_list` | List all worktrees (`git worktree list --porcelain`). Workspace pick + `format`. **Read-only.** |
+| `git_push` | `rethunk-git_git_push` | Push the current branch to its upstream. Optional `remote`, `branch`, `setUpstream` (passes `-u`). Refuses on detached HEAD; never force-pushes. Workspace pick + `format`. **Mutating.** |
+| `git_worktree_add` | `rethunk-git_git_worktree_add` | Create a new linked worktree, creating the branch from `baseRef` if it does not yet exist. Refuses on protected branch names. Args: `path`, `branch`, `baseRef?`, plus workspace pick + `format`. **Mutating.** |
+| `git_worktree_remove` | `rethunk-git_git_worktree_remove` | Remove a registered worktree; refuses to remove the main worktree. Optional `force: true` for dirty trees. Args: `path`, `force?`, plus workspace pick + `format`. **Mutating.** |
+| `git_reset_soft` | `rethunk-git_git_reset_soft` | Soft-reset the current branch to a ref (`HEAD~N`, SHA, branch). Rewound changes land in the staging index; requires a clean working tree. Args: `ref`, plus workspace pick + `format`. **Mutating — not idempotent.** |
 | `batch_commit` | `rethunk-git_batch_commit` | 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 every commit lands. Args: `commits` (array of `{message, files}`), `push?`, plus workspace pick args + `format`. **Mutating — not idempotent.** |
 | `git_merge` | `rethunk-git_git_merge` | Merge one or more source branches into a destination. Default strategy `auto` cascades fast-forward → rebase → merge-commit per source, preferring linear history. Refuses on dirty tree; stops on first conflict with structured path report. Optional `deleteMergedBranches` / `deleteMergedWorktrees` cascade cleanup, always skipping protected names (main/master/dev/develop/stable/trunk/prod/production/release\*/hotfix\*). Args: `sources`, `into?`, `strategy?`, `message?`, cleanup flags + workspace pick + `format`. **Mutating.** |
 | `git_cherry_pick` | `rethunk-git_git_cherry_pick` | Play commits from one or more sources onto a destination. Sources may be SHAs, `A..B` ranges, or branch names (expanded to `onto..<branch>`, oldest-first). Uses `--empty=drop` so patch-equivalent re-applies add nothing. Refuses on dirty tree; stops on first conflict, aborting cleanly. Same cleanup flags as `git_merge` (branch-kind sources only, protected names skipped). Args: `sources`, `onto?`, cleanup flags + workspace pick + `format`. **Mutating.** |
@@ -25,9 +30,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 +73,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 +92,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 +344,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 |