@senad-d/branchme 0.3.2 → 0.3.4

package/src/git.ts

@@ -1,8 +1,9 @@
-import { lstat, realpath, stat } from "node:fs/promises";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
 import { withFileMutationQueue, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   GIT_BRANCH_ENTRY_LIMIT,
+  GIT_BRANCH_PATTERN_LIMIT,
   GIT_BRANCH_RAW_OUTPUT_LIMIT_BYTES,
   GIT_CONTEXT_CHANGE_LIMIT,
   GIT_CONTEXT_RECENT_COMMIT_LIMIT,
@@ -42,6 +43,7 @@ import type {
   GitFileChangeSummary,
   InitRepositoryDetails,
   ListBranchesDetails,
+  ListBranchesToolInput,
   ListWorktreesDetails,
   PullBranchDetails,
   PushBranchDetails,
@@ -629,7 +631,7 @@ function truncateWorktreeValue(value: string, limit: number): string {
   return `${value.slice(0, end)}…`;
 }
 
-function safeWorktreeValue(value: string, limit: number): string {
+export function safeWorktreeValue(value: string, limit: number): string {
   const redacted = redactSecrets(value);
   const escaped = redacted.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, escapeGitContextControlCharacter);
   return truncateWorktreeValue(escaped, limit);
@@ -1273,19 +1275,81 @@ export function parseBranchRefs(output: string): Pick<ListBranchesDetails, "bran
   return { branches, omitted: records.length - branches.length };
 }
 
+function validateBranchFilters(filters: ListBranchesToolInput): void {
+  if (filters.kind !== undefined && filters.kind !== "local" && filters.kind !== "remote-tracking") {
+    throw new TypeError("list_branches kind must be 'local' or 'remote-tracking'.");
+  }
+  if (filters.patterns === undefined) return;
+  if (!Array.isArray(filters.patterns) || filters.patterns.length === 0 || filters.patterns.length > GIT_BRANCH_PATTERN_LIMIT) {
+    throw new TypeError(`list_branches patterns must contain 1 to ${GIT_BRANCH_PATTERN_LIMIT} strings.`);
+  }
+  for (const pattern of filters.patterns) {
+    if (typeof pattern !== "string" || !pattern.trim() || pattern.length > GIT_CONTEXT_VALUE_LIMIT_CHARS ||
+        /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(pattern) || pattern.startsWith("-")) {
+      throw new TypeError("list_branches patterns must be nonblank, bounded strings without leading '-' or control characters.");
+    }
+  }
+}
+
+async function readBranchScope(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  patterns: string[],
+  signal: AbortSignal | undefined,
+  kind: string,
+): Promise<string> {
+  const result = await runGit(pi, ctx, [
+    "branch", "--list", "--no-color", "--no-column", "--sort=refname",
+    // Detached/rebasing pseudo-branches are not refs; render them as empty lines.
+    `--format=%(if:equals=refs)%(refname:rstrip=-1)%(then)${GIT_BRANCH_FORMAT}%(end)`,
+    ...(kind === "remote-tracking" ? ["--remotes"] : []), "--", ...patterns,
+  ], { signal });
+  return result.stdout;
+}
+
+async function readFilteredBranchRefs(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  filters: ListBranchesToolInput,
+  signal?: AbortSignal,
+): Promise<string> {
+  const kinds = filters.kind === undefined ? ["local", "remote-tracking"] : [filters.kind];
+  if (filters.patterns === undefined) {
+    const prefixes = kinds.map((kind) => kind === "local" ? "refs/heads/" : "refs/remotes/");
+    const result = await runGit(pi, ctx, [
+      "for-each-ref", "--sort=refname", `--format=${GIT_BRANCH_FORMAT}`, ...prefixes,
+    ], { signal });
+    return result.stdout;
+  }
+
+  // Git applies branch-list glob semantics before the raw-output and entry limits.
+  // Separate scopes keep remote names as origin/topic, not remotes/origin/topic.
+  const outputs = await Promise.all(kinds.map(readBranchScope.bind(undefined, pi, ctx, filters.patterns, signal)));
+  let output = "";
+  for (const scopeOutput of outputs) {
+    if (Buffer.byteLength(output, "utf8") + Buffer.byteLength(scopeOutput, "utf8") > GIT_BRANCH_RAW_OUTPUT_LIMIT_BYTES) {
+      throw new TypeError("Unable to parse branches: ref output exceeded the safety limit.");
+    }
+    for (const record of scopeOutput.split("\n")) {
+      if (record !== "") output += `${record}\n`;
+    }
+  }
+  return output;
+}
+
 export async function listBranches(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
   signal?: AbortSignal,
+  filters: ListBranchesToolInput = {},
 ): Promise<ListBranchesDetails> {
+  validateBranchFilters(filters);
   const repoRoot = await getGitRoot(pi, ctx, signal);
   const rootCtx = { cwd: repoRoot };
-  const result = await runGit(pi, rootCtx, [
-    "for-each-ref", "--sort=refname", `--format=${GIT_BRANCH_FORMAT}`, "refs/heads/", "refs/remotes/",
-  ], { signal });
-  const parsed = parseBranchRefs(result.stdout);
+  const output = await readFilteredBranchRefs(pi, rootCtx, filters, signal);
+  const parsed = parseBranchRefs(output);
   const inventory = await collectWorktreeInventory(pi, rootCtx, signal);
-  const rawRecords = result.stdout.split("\n");
+  const rawRecords = output.split("\n");
   for (const [index, branch] of parsed.branches.entries()) {
     if (branch.kind !== "local") continue;
     const rawName = rawRecords[index].split(NUL_SEPARATOR, 1)[0].slice("refs/heads/".length);
@@ -2402,6 +2466,33 @@ async function getVerifiedRefCommit(
   return commit;
 }
 
+export async function getMergeHeadCommit(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  signal?: AbortSignal,
+): Promise<string> {
+  const result = await runGit(pi, ctx, ["rev-parse", "--path-format=absolute", "--git-path", "MERGE_HEAD"], {
+    signal, timeout: GIT_STATUS_TIMEOUT_MS,
+  });
+  const path = stripSingleLineTerminator(result.stdout);
+  if (!isAbsolute(path) || /[\p{Cc}\p{Cf}\u2028\u2029]/u.test(path)) {
+    throw new Error("Unable to inspect MERGE_HEAD: Git returned an invalid state path.");
+  }
+  const metadata = await lstat(path);
+  if (!metadata.isFile() || metadata.size > 65) {
+    throw new Error("MERGE_HEAD must contain exactly one commit; multi-head merges are not supported.");
+  }
+  const contents = await readFile(path, { encoding: "utf8", signal });
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})\n?$/iu.test(contents)) {
+    throw new Error("MERGE_HEAD must contain exactly one valid commit identity.");
+  }
+  const commit = await getVerifiedRefCommit(pi, ctx, "MERGE_HEAD", "MERGE_HEAD", signal);
+  if (commit.toLowerCase() !== contents.trimEnd().toLowerCase()) {
+    throw new Error("MERGE_HEAD changed during inspection; inspect the merge before retrying.");
+  }
+  return commit;
+}
+
 export async function getLocalBranchCommit(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,

package/src/tools/branchme-tools.ts

@@ -8,8 +8,10 @@ import {
   CREATE_BRANCH_TOOL_NAME,
   CREATE_WORKTREE_TOOL_NAME,
   FETCH_BRANCH_TOOL_NAME,
+  FETCH_REMOTE_TOOL_NAME,
+  GIT_BRANCH_PATTERN_LIMIT,
   GIT_BRANCH_SUMMARY_LIMIT_CHARS,
-  GIT_INTEGRATION_SUMMARY_LIMIT_CHARS,
+  GIT_CONTEXT_VALUE_LIMIT_CHARS,
   GIT_RETIREMENT_SUMMARY_LIMIT_CHARS,
   GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
   INIT_REPOSITORY_TOOL_NAME,
@@ -47,7 +49,8 @@ import {
   withRepositoryMutationQueue,
 } from "../git.ts";
 import { collectGitContext, formatGitContext } from "../git-context.ts";
-import { integrateBranch } from "../git-integration.ts";
+import { fetchRemote } from "../git-discovery.ts";
+import { formatConflictPathList, integrateBranch } from "../git-integration.ts";
 import { retireBranch } from "../git-retirement.ts";
 import { formatLandBranch, landBranch } from "../git-landing.ts";
 import {
@@ -78,6 +81,28 @@ import type {
 
 const EmptyParametersSchema = Type.Object({}, { additionalProperties: false });
 
+const ListBranchesParametersSchema = Type.Object(
+  {
+    kind: Type.Optional(StringEnum(["local", "remote-tracking"] as const, {
+      description: "Limit discovery to local or remote-tracking branches; omit for both.",
+    })),
+    patterns: Type.Optional(Type.Array(Type.String({
+      minLength: 1,
+      maxLength: GIT_CONTEXT_VALUE_LIMIT_CHARS,
+      description: "Git branch-list glob on branch names, including remote prefix (for example origin/feat/23-*).",
+    }), { minItems: 1, maxItems: GIT_BRANCH_PATTERN_LIMIT, description: "Match any of these patterns before output limits; omit to list all selected branches." })),
+  },
+  { additionalProperties: false },
+);
+
+const FetchRemoteParametersSchema = Type.Object(
+  {
+    remote: Type.Optional(Type.String({ minLength: 1, description: "Configured remote name; defaults to origin." })),
+    prune: Type.Optional(Type.Boolean({ description: "Delete stale cached branch refs only for this remote; defaults to false. Never deletes local branches or tags." })),
+  },
+  { additionalProperties: false },
+);
+
 const InitRepositoryParametersSchema = Type.Object(
   {
     initialBranch: Type.Optional(Type.String({
@@ -328,42 +353,17 @@ export function formatRemoveWorktree(details: RemoveWorktreeDetails): string {
   return `Removed linked worktree directory ${path}. Verified it is no longer registered and retained local branch ${branch} at HEAD ${shortCommit(details.handoff.head)}; the removed cwd is not ready for handoff.`;
 }
 
-function integrationConflictOmissionLine(omitted: number): string {
-  return `${omitted} conflict path${omitted === 1 ? "" : "s"} omitted.`;
-}
-
-function formatIntegrationConflict(details: Extract<IntegrateBranchDetails, { status: "conflict" }>): string {
+function formatIntegrationConflict(details: Extract<IntegrateBranchDetails, { status: "conflict" | "conflict_kept" }>): string {
   const source = safeWorktreeFormatValue(details.request.sourceBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
   const target = safeWorktreeFormatValue(details.request.targetBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
-  const lines = [
-    `integrate_branch found conflicts while integrating ${source} into ${target}; the merge was automatically aborted and exact restoration was verified at target HEAD ${shortCommit(details.verified.heads.after.targetHead)}.`,
-    "Conflict paths:",
-  ];
-  let omitted = details.conflict.omitted;
-
-  for (const [index, entry] of details.conflict.paths.entries()) {
-    const path = safeWorktreeFormatValue(entry.path, WORKTREE_FORMAT_PATH_LIMIT_CHARS);
-    const line = `- ${path}`;
-    const remaining = details.conflict.paths.length - index - 1;
-    const candidateOmitted = details.conflict.omitted + remaining;
-    const candidate = [
-      ...lines,
-      line,
-      ...(candidateOmitted > 0 ? [integrationConflictOmissionLine(candidateOmitted)] : []),
-    ].join("\n");
-    if (candidate.length > GIT_INTEGRATION_SUMMARY_LIMIT_CHARS) {
-      omitted += details.conflict.paths.length - index;
-      break;
-    }
-    lines.push(line);
-  }
-
-  if (omitted > 0) lines.push(integrationConflictOmissionLine(omitted));
-  return lines.join("\n");
+  const header = details.status === "conflict"
+    ? `integrate_branch found conflicts while integrating ${source} into ${target}; the merge was automatically aborted and exact restoration was verified at target HEAD ${shortCommit(details.verified.heads.after.targetHead)}.`
+    : `integrate_branch found conflicts while integrating ${source} into ${target}; the merge was kept in progress at target HEAD ${shortCommit(details.heads.targetHead)} and must be finished with conclude_merge.`;
+  return formatConflictPathList(header, details.conflict);
 }
 
 export function formatIntegrateBranch(details: IntegrateBranchDetails): string {
-  if (details.status === "conflict") return formatIntegrationConflict(details);
+  if (details.status === "conflict" || details.status === "conflict_kept") return formatIntegrationConflict(details);
 
   const source = safeWorktreeFormatValue(details.request.sourceBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
   const target = safeWorktreeFormatValue(details.request.targetBranch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
@@ -548,15 +548,16 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: LIST_BRANCHES_TOOL_NAME,
     label: "List Branches",
-    description: "list_branches reads up to 200 local and remote-tracking branches, including commits, upstream counts, symbolic refs, and worktree occupancy. Read-only; cached remote refs are not fetched. Text is bounded to 4000 characters.",
+    description: "list_branches reads up to 200 local and remote-tracking branches, including commits, upstream counts, symbolic refs, and worktree occupancy. Optional kind and Git branch-list patterns filter before limits. Read-only; cached remote refs are not fetched. Text is bounded to 4000 characters.",
     promptSnippet: "list_branches: discover local and cached remote-tracking branches without mutation",
     promptGuidelines: [
       "Use list_branches to discover names and worktree occupancy before branch operations; it never fetches or mutates Git state.",
       "Treat list_branches names and paths as display metadata; redacted or truncated values are not executable identities.",
+      "Use list_branches with kind: 'remote-tracking' and patterns such as ['origin/feat/23', 'origin/feat/23-*'] for issue branch discovery; wait for fetch_remote to complete first when fresh remote refs are needed.",
     ],
-    parameters: EmptyParametersSchema,
-    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
-      const details = await listBranches(pi, ctx, signal);
+    parameters: ListBranchesParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await listBranches(pi, ctx, signal, params);
       const lines = details.branches.map((branch) =>
         `${branch.current ? "*" : "-"} ${JSON.stringify(branch.name)} (${branch.kind}) ${shortCommit(branch.head)}; upstream ${JSON.stringify(branch.upstream)}; ahead ${branch.ahead ?? "?"}, behind ${branch.behind ?? "?"}; worktrees ${JSON.stringify(branch.worktreePaths)}`);
       const text = [`Branches: ${details.branches.length}; omitted: ${details.omitted}.`, ...lines].join("\n");
@@ -696,6 +697,27 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  pi.registerTool({
+    name: FETCH_REMOTE_TOOL_NAME,
+    label: "Fetch Remote",
+    description: "fetch_remote refreshes all branch refs for one configured remote (default origin). Optional prune deletes only that remote's stale cached branch refs; default false. Uses an internal atomic heads-to-remote-tracking refspec, ignores configured refmaps, and disables tags, tag pruning, and submodules. Requires the files ref backend and non-overlapping remote namespaces; refuses unsafe symbolic destinations. Preserves safe remote HEAD aliases by excluding the remote branch named HEAD. Never changes local branches, checkout, upstream configuration, or working-tree files.",
+    promptSnippet: "fetch_remote: refresh a configured remote's branch cache with optional remote-tracking-only pruning",
+    promptGuidelines: [
+      "Use fetch_remote when fresh discovery of unknown remote branch names is needed; fetch_branch remains the narrow tool for a known branch.",
+      "Use fetch_remote with prune: true only when stale cached branch deletion is intended; it never deletes local branches, tags, or branches on the server.",
+      "Call fetch_remote by itself and wait for it to complete before list_branches, track_branch, or other dependent Git operations; do not batch Git mutations.",
+      "fetch_remote accepts only a configured remote name and optional prune boolean; never pass URLs, refspecs, force, tags, or checkout controls.",
+    ],
+    parameters: FetchRemoteParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await fetchRemote(pi, ctx, params.remote ?? "origin", params.prune ?? false, signal);
+      return {
+        content: [{ type: "text", text: `Fetched branch cache for remote ${details.remote}${details.prune ? " and pruned its stale remote-tracking branch refs" : " without pruning"}. No local branches or tags changed.` }],
+        details,
+      };
+    },
+  });
+
   pi.registerTool({
     name: PULL_BRANCH_TOOL_NAME,
     label: "Pull Branch",

package/src/tools/workflow-tools.ts

@@ -1,11 +1,57 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { PULL_REQUEST_STATUS_TOOL_NAME, TRACK_BRANCH_TOOL_NAME, UPDATE_FROM_BASE_TOOL_NAME } from "../constants.ts";
-import { getGitRoot, requireCurrentBranch } from "../git.ts";
+import {
+  CONCLUDE_MERGE_TOOL_NAME, GIT_CONTEXT_VALUE_LIMIT_CHARS, PULL_REQUEST_STATUS_TOOL_NAME, TRACK_BRANCH_TOOL_NAME,
+  UPDATE_FROM_BASE_TOOL_NAME,
+} from "../constants.ts";
+import { getGitRoot, requireCurrentBranch, safeWorktreeValue } from "../git.ts";
+import { concludeMerge, formatConflictPathList } from "../git-integration.ts";
 import { findGitHubPullRequest, getGitHubPullRequest, resolveGitHubRepository, resolveGitHubToken } from "../github.ts";
-import type { PullRequestStatusDetails } from "../types.ts";
+import type { ConcludeMergeDetails, PullRequestStatusDetails } from "../types.ts";
 import type { BranchMeToolOptions } from "./branchme-tools.ts";
-import { trackBranch, updateFromBase } from "../git-workflow.ts";
+import { trackBranch, updateFromBase, type UpdateFromBaseDetails } from "../git-workflow.ts";
+
+function shortCommit(commit: string): string {
+  return commit.slice(0, 12);
+}
+
+function branchLabel(branch: string): string {
+  return safeWorktreeValue(branch, GIT_CONTEXT_VALUE_LIMIT_CHARS);
+}
+
+export function formatUpdateFromBase(details: UpdateFromBaseDetails): string {
+  const { integration } = details;
+  const source = branchLabel(integration.request.sourceBranch);
+  const target = branchLabel(integration.request.targetBranch);
+  if (integration.status === "conflict") {
+    return formatConflictPathList(
+      `update_from_base: conflict. Merging ${source} into ${target} conflicted; the merge was automatically aborted and restoration was verified at HEAD ${shortCommit(integration.verified.heads.after.targetHead)}. Rerun with keepConflicts: true to keep the conflicted merge in progress for resolution.`,
+      integration.conflict,
+    );
+  }
+  if (integration.status === "conflict_kept") {
+    return formatConflictPathList(
+      `update_from_base: conflict_kept. Merging ${source} (${shortCommit(integration.heads.sourceHead)}) into ${target} conflicted; the merge is in progress with MERGE_HEAD set and HEAD unchanged at ${shortCommit(integration.heads.targetHead)}. Remove the conflict markers in the listed paths, then run conclude_merge with action "conclude" to commit the merge or action "abort" to restore the branch.`,
+      integration.conflict,
+    );
+  }
+  return `update_from_base: ${integration.status}. Base integration verified without rewriting published history.`;
+}
+
+export function formatConcludeMerge(details: ConcludeMergeDetails): string {
+  const branch = branchLabel(details.branch);
+  if (details.status === "aborted") {
+    return `conclude_merge: aborted. git merge --abort restored ${branch} to HEAD ${shortCommit(details.head)}; MERGE_HEAD ${shortCommit(details.mergeHead)} is cleared, no Git operation is in progress, and the working tree is clean.`;
+  }
+  const count = details.resolvedPaths.length;
+  return formatConflictPathList(
+    `conclude_merge: concluded. Committed merge ${shortCommit(details.heads.after)} on ${branch} with parents ${shortCommit(details.parents.first)} (previous HEAD) and ${shortCommit(details.parents.second)} (MERGE_HEAD); MERGE_HEAD is cleared and both parents were verified. Only the ${count} resolved path${count === 1 ? "" : "s"} listed below ${count === 1 ? "was" : "were"} staged during this call; other working-tree changes remain unstaged. The commit includes all previously staged entries.`,
+    { paths: details.resolvedPaths, omitted: 0 },
+    "Resolved paths:",
+    "resolved path",
+  );
+}
 
 function formatPullRequestStatus(pullRequest: PullRequestStatusDetails | null): string {
   if (!pullRequest) return "No matching pull request found.";
@@ -47,20 +93,43 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",
-    description: "update_from_base fetches one remote base and merges its captured commit into the clean current feature branch with verified no-op, fast-forward, merge-commit, or automatically aborted conflict results. Never rebases, pushes, stashes, or changes upstream configuration.",
-    promptSnippet: "update_from_base: merge a fresh remote base into the current feature without rewriting published history",
+    description: "update_from_base fetches one remote base and merges its captured commit into the clean current feature branch with verified no-op, fast-forward, merge-commit, or conflict results. A conflict is automatically aborted with restoration verified unless keepConflicts is true, which leaves the conflicted merge in progress for conclude_merge. Never rebases, pushes, stashes, or changes upstream configuration.",
+    promptSnippet: "update_from_base: merge a fresh remote base into the current feature without rewriting published history; keepConflicts keeps a conflicted merge in progress",
     promptGuidelines: [
       "Use update_from_base only when asked to update the current feature branch from an explicit baseBranch; remote defaults to origin.",
-      "Run update_from_base by itself. It fetches the base and uses the fixed normal-merge policy; conflicts are automatically aborted with restoration verified.",
-      "update_from_base preserves published history and upstream configuration; committing conflict-resolution changes belongs to a separate workflow.",
+      "Run update_from_base by itself. It fetches the base and uses the fixed normal-merge policy; by default conflicts are automatically aborted with restoration verified and the conflict paths are listed.",
+      "Pass keepConflicts: true to update_from_base only when a file-editing step will resolve the listed paths; the result conflict_kept leaves MERGE_HEAD set, and conclude_merge must then conclude or abort it before any other Git mutation.",
+      "update_from_base preserves published history and upstream configuration; it never resolves conflict content itself.",
     ],
     parameters: Type.Object({
       baseBranch: Type.String({ minLength: 1, description: "Exact base branch on the remote, for example main." }),
       remote: Type.Optional(Type.String({ minLength: 1, description: "Configured remote; defaults to origin." })),
+      keepConflicts: Type.Optional(Type.Boolean({ description: "When true, a conflicted merge is left in progress (MERGE_HEAD set, conflicted paths unmerged) for conclude_merge instead of being aborted; defaults to false." })),
     }, { additionalProperties: false }),
     async execute(_id, params, signal, _update, ctx) {
       const details = await updateFromBase(pi, ctx, params, signal);
-      return { content: [{ type: "text", text: `update_from_base: ${details.status}. ${details.status === "conflict" ? "Merge aborted and restoration verified; inspect conflict paths in details." : "Base integration verified without rewriting published history."}` }], details };
+      return { content: [{ type: "text", text: formatUpdateFromBase(details) }], details };
+    },
+  });
+  pi.registerTool({
+    name: CONCLUDE_MERGE_TOOL_NAME,
+    label: "Conclude Merge",
+    description: "conclude_merge finishes or abandons the in-progress merge on the current checkout, normally one kept by update_from_base with keepConflicts: true. action \"conclude\" checks unmerged working-tree paths and staged blobs for default/custom-sized conflict marker lines, stages exactly the unmerged paths, checks the candidate index again, and commits the full index with Git's prepared merge message, then verifies the two-parent result; action \"abort\" runs git merge --abort and verifies restoration. conclude_merge never stages other changes, accepts no commit message, and never pushes.",
+    promptSnippet: "conclude_merge: commit or abort the kept in-progress merge after conflict markers are removed",
+    promptGuidelines: [
+      "Use conclude_merge only after update_from_base reported conflict_kept, or when a single-head merge is otherwise in progress on the current checkout; run conclude_merge by itself. Multi-head merges are refused before mutation.",
+      "Before conclude_merge with action conclude, a file-editing step must remove every <<<<<<<, |||||||, =======, and >>>>>>> marker line from the listed paths; conclude_merge refuses and names the paths that still contain markers.",
+      "conclude_merge with action conclude stages only the currently unmerged paths and uses Git's prepared merge message; unrelated unstaged edits stay unstaged and are not part of the merge commit. Git commits the entire index, including previously staged entries: do not stage unrelated edits during the merge.",
+      "conclude_merge with action abort restores the branch with git merge --abort and verifies a clean idle checkout; conclude_merge refuses when no merge is in progress.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(["conclude", "abort"] as const, {
+        description: "conclude stages the resolved formerly unmerged paths and commits the merge; abort runs git merge --abort and verifies restoration.",
+      }),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      const details = await concludeMerge(pi, ctx, params, signal);
+      return { content: [{ type: "text", text: formatConcludeMerge(details) }], details };
     },
   });
   pi.registerTool({

package/src/types.ts

@@ -29,7 +29,25 @@ export interface BranchStatusToolInput {
   ancestry?: BranchStatusAncestryQuery;
 }
 
-export type ListBranchesToolInput = Record<string, never>;
+export interface ListBranchesToolInput {
+  kind?: "local" | "remote-tracking";
+  /** Git branch-list glob patterns on names, including the remote prefix for remote-tracking refs. */
+  patterns?: string[];
+}
+
+export interface FetchRemoteToolInput {
+  remote?: string;
+  prune?: boolean;
+}
+
+export interface FetchRemoteDetails {
+  action: "fetch_remote";
+  repoRoot: string;
+  remote: string;
+  prune: boolean;
+  refspec: string;
+  output: string;
+}
 
 export interface BranchEntry {
   name: string;
@@ -318,7 +336,7 @@ export interface PushBranchDetails {
   output: string;
 }
 
-export type IntegrateBranchStatus = "already_integrated" | "fast_forward" | "merge_commit" | "conflict";
+export type IntegrateBranchStatus = "already_integrated" | "fast_forward" | "merge_commit" | "conflict" | "conflict_kept";
 
 export interface IntegrateBranchHeads {
   sourceHead: string;
@@ -406,11 +424,72 @@ export interface IntegrateBranchConflictDetails extends IntegrateBranchDetailsBa
   };
 }
 
+/** A conflicted merge deliberately left in progress (update_from_base keepConflicts); conclude_merge finishes or abandons it. */
+export interface IntegrateBranchConflictKeptDetails {
+  action: "integrate_branch";
+  status: "conflict_kept";
+  mergeExecuted: true;
+  request: IntegrateBranchToolInput;
+  /** targetHead is the unchanged HEAD; sourceHead is the commit recorded in MERGE_HEAD. */
+  heads: IntegrateBranchHeads;
+  conflict: {
+    paths: IntegrateBranchConflictPathEntry[];
+    omitted: number;
+    kept: true;
+    mergeInProgress: true;
+  };
+}
+
 export type IntegrateBranchDetails =
   | IntegrateBranchAlreadyIntegratedDetails
   | IntegrateBranchFastForwardDetails
   | IntegrateBranchMergeCommitDetails
-  | IntegrateBranchConflictDetails;
+  | IntegrateBranchConflictDetails
+  | IntegrateBranchConflictKeptDetails;
+
+export type ConcludeMergeAction = "conclude" | "abort";
+
+export interface ConcludeMergeToolInput {
+  action: ConcludeMergeAction;
+}
+
+export interface ConcludeMergeConcludedDetails {
+  action: "conclude_merge";
+  status: "concluded";
+  request: ConcludeMergeToolInput;
+  repoRoot: string;
+  branch: string;
+  heads: {
+    before: string;
+    after: string;
+  };
+  parents: {
+    first: string;
+    second: string;
+  };
+  mergeHead: string;
+  /** Exactly the formerly unmerged paths that were staged for the merge commit. */
+  resolvedPaths: IntegrateBranchConflictPathEntry[];
+}
+
+export interface ConcludeMergeAbortedDetails {
+  action: "conclude_merge";
+  status: "aborted";
+  request: ConcludeMergeToolInput;
+  repoRoot: string;
+  branch: string;
+  head: string;
+  mergeHead: string;
+  restoration: {
+    verified: true;
+    headRestored: true;
+    branchPreserved: true;
+    operationStateCleared: true;
+    cleanWorktree: true;
+  };
+}
+
+export type ConcludeMergeDetails = ConcludeMergeConcludedDetails | ConcludeMergeAbortedDetails;
 
 export type RetireBranchMode = "merged" | "forced_unmerged";