@senad-d/branchme 0.1.7 → 0.1.9

package/src/tools/branchme-tools.ts

@@ -1,32 +1,43 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
   BRANCH_STATUS_TOOL_NAME,
   CHANGE_BRANCH_TOOL_NAME,
   CREATE_BRANCH_TOOL_NAME,
+  CREATE_WORKTREE_TOOL_NAME,
   FETCH_BRANCH_TOOL_NAME,
+  GIT_INTEGRATION_SUMMARY_LIMIT_CHARS,
+  GIT_WORKTREE_SUMMARY_LIMIT_CHARS,
+  INTEGRATE_BRANCH_TOOL_NAME,
+  LIST_WORKTREES_TOOL_NAME,
   PULL_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
   REBASE_BRANCH_TOOL_NAME,
+  REMOVE_WORKTREE_TOOL_NAME,
 } from "../constants.ts";
 import {
   changeExistingLocalBranch,
   createLocalBranch,
+  createWorktree,
   fetchCurrentBranch,
   getGitRoot,
   getLocalBranchCommit,
   getPullRequestCommitSubjects,
   inferPullRequestBaseBranch,
+  listWorktrees,
   localBranchExists,
   pullCurrentBranch,
   pushCurrentBranch,
   rebaseCurrentBranch,
+  removeWorktree,
   requireCurrentBranch,
   validateBranchName,
   withRepositoryMutationQueue,
 } from "../git.ts";
 import { collectGitContext, formatGitContext } from "../git-context.ts";
+import { integrateBranch } from "../git-integration.ts";
 import {
   createGitHubPullRequest,
   ensureGitHubBranchExists,
@@ -39,16 +50,44 @@ import {
 } from "../github.ts";
 import type {
   ChangeBranchDetails,
+  CreateWorktreeDetails,
   GitContextDetails,
+  IntegrateBranchDetails,
+  ListWorktreesDetails,
   PullRequestDetails,
   PullRequestInput,
   PullRequestInputField,
   PullRequestToolDetails,
   PullRequestToolInput,
+  RemoveWorktreeDetails,
+  WorktreeEntry,
 } from "../types.ts";
 
 const EmptyParametersSchema = Type.Object({}, { additionalProperties: false });
 
+const BranchStatusParametersSchema = Type.Object(
+  {
+    ancestry: Type.Optional(
+      Type.Object(
+        {
+          sourceBranch: Type.String({ minLength: 1, description: "Exact existing local source branch to verify." }),
+          targetBranch: Type.String({ minLength: 1, description: "Exact existing local target branch to verify." }),
+        },
+        { additionalProperties: false },
+      ),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+const IntegrateBranchParametersSchema = Type.Object(
+  {
+    sourceBranch: Type.String({ minLength: 1, description: "Exact existing local source branch to integrate." }),
+    targetBranch: Type.String({ minLength: 1, description: "Exact existing local target branch already checked out in the clean control worktree." }),
+  },
+  { additionalProperties: false },
+);
+
 const CreateBranchParametersSchema = Type.Object(
   {
     branchName: Type.String({ minLength: 1, description: "Name of the new branch to create from current HEAD." }),
@@ -63,6 +102,24 @@ const ChangeBranchParametersSchema = Type.Object(
   { additionalProperties: false },
 );
 
+const CreateWorktreeParametersSchema = Type.Object(
+  {
+    worktreePath: Type.String({ minLength: 1, description: "Explicit absolute destination path for the linked worktree." }),
+    branchName: Type.String({ minLength: 1, description: "New or existing local branch name for the linked worktree." }),
+    branchMode: StringEnum(["new", "existing"] as const, {
+      description: "Whether create_worktree creates a new local branch from current HEAD or uses an existing local branch.",
+    }),
+  },
+  { additionalProperties: false },
+);
+
+const RemoveWorktreeParametersSchema = Type.Object(
+  {
+    worktreePath: Type.String({ minLength: 1, description: "Explicit absolute path of the linked worktree to remove." }),
+  },
+  { additionalProperties: false },
+);
+
 const PullRequestParametersSchema = Type.Object(
   {
     headBranch: Type.Optional(
@@ -100,6 +157,150 @@ export function formatPullRequest(details: PullRequestDetails, autofilledFields:
   return `Created pull request #${details.number} (${details.state}) for ${repositoryLabel(details.repository)}: ${details.url}.${autofill}`;
 }
 
+const WORKTREE_FORMAT_PATH_LIMIT_CHARS = 512;
+const WORKTREE_FORMAT_BRANCH_LIMIT_CHARS = 256;
+
+function truncateWorktreeFormatValue(value: string, limit: number): string {
+  if (value.length <= limit) return value;
+  let end = limit - 1;
+  const lastCodePoint = value.codePointAt(end - 1);
+  if (lastCodePoint !== undefined && lastCodePoint > 0xffff) end -= 1;
+  return `${value.slice(0, end)}…`;
+}
+
+function escapeWorktreeFormatControlCharacter(character: string): string {
+  const codePoint = character.codePointAt(0);
+  return codePoint === undefined ? "" : String.raw`\u${codePoint.toString(16).padStart(4, "0")}`;
+}
+
+function safeWorktreeFormatValue(value: string, limit: number): string {
+  const redacted = redactSecrets(value);
+  const escaped = redacted.replace(
+    /[\p{Cc}\p{Cf}\u2028\u2029]/gu,
+    escapeWorktreeFormatControlCharacter,
+  );
+  return truncateWorktreeFormatValue(escaped, limit);
+}
+
+function worktreeDisplayState(worktree: WorktreeEntry): string {
+  if (worktree.bare) return "bare";
+  if (worktree.detached) return "detached";
+  const branch = worktree.branch ?? "unknown";
+  return `branch ${safeWorktreeFormatValue(branch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS)}`;
+}
+
+function worktreeDisplayIndicators(worktree: WorktreeEntry): string[] {
+  const indicators: string[] = [];
+  if (worktree.main) indicators.push("main");
+  if (worktree.current) indicators.push("current");
+  if (worktree.locked) indicators.push("locked");
+  if (worktree.prunable) indicators.push("prunable");
+  return indicators;
+}
+
+function formatWorktreeEntry(worktree: WorktreeEntry): string {
+  const path = safeWorktreeFormatValue(worktree.path, WORKTREE_FORMAT_PATH_LIMIT_CHARS);
+  const head = worktree.head === null ? "none" : shortCommit(worktree.head);
+  const indicators = worktreeDisplayIndicators(worktree);
+  const indicatorText = indicators.length === 0 ? "" : ` | ${indicators.join(",")}`;
+  return `- ${path} | ${worktreeDisplayState(worktree)} | HEAD ${head}${indicatorText}`;
+}
+
+function worktreeOmissionLine(omitted: number): string {
+  return `${omitted} worktree entr${omitted === 1 ? "y" : "ies"} omitted.`;
+}
+
+export function formatListWorktrees(details: ListWorktreesDetails): string {
+  const repoRoot = safeWorktreeFormatValue(details.repoRoot, WORKTREE_FORMAT_PATH_LIMIT_CHARS);
+  const lines = [`Worktrees for ${repoRoot}:`];
+  let omitted = details.omitted;
+
+  for (const [index, worktree] of details.worktrees.entries()) {
+    const line = formatWorktreeEntry(worktree);
+    const remaining = details.worktrees.length - index - 1;
+    const candidateOmitted = details.omitted + remaining;
+    const candidate = [
+      ...lines,
+      line,
+      ...(candidateOmitted > 0 ? [worktreeOmissionLine(candidateOmitted)] : []),
+    ].join("\n");
+    if (candidate.length > GIT_WORKTREE_SUMMARY_LIMIT_CHARS) {
+      omitted += details.worktrees.length - index;
+      break;
+    }
+    lines.push(line);
+  }
+
+  if (omitted > 0) lines.push(worktreeOmissionLine(omitted));
+  return lines.join("\n");
+}
+
+export function formatCreateWorktree(details: CreateWorktreeDetails): string {
+  const cwd = safeWorktreeFormatValue(details.handoff.cwd, WORKTREE_FORMAT_PATH_LIMIT_CHARS);
+  const branch = safeWorktreeFormatValue(details.handoff.branch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  const mode = details.request.branchMode === "new" ? "new local branch" : "existing local branch";
+  return `Created linked worktree ${cwd} for ${mode} ${branch}. Verified its canonical path, local branch, HEAD ${shortCommit(details.handoff.head)}, clean working tree, and ready handoff.`;
+}
+
+export function formatRemoveWorktree(details: RemoveWorktreeDetails): string {
+  const path = safeWorktreeFormatValue(
+    details.verified.before.worktree.path,
+    WORKTREE_FORMAT_PATH_LIMIT_CHARS,
+  );
+  const branch = safeWorktreeFormatValue(details.handoff.branch, WORKTREE_FORMAT_BRANCH_LIMIT_CHARS);
+  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 {
+  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");
+}
+
+export function formatIntegrateBranch(details: IntegrateBranchDetails): string {
+  if (details.status === "conflict") 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);
+  const beforeTarget = shortCommit(details.verified.heads.before.targetHead);
+  const afterTarget = shortCommit(details.verified.heads.after.targetHead);
+  if (details.status === "already_integrated") {
+    return `integrate_branch verified ${source} was already integrated into ${target}; no merge ran and target HEAD remained ${afterTarget}.`;
+  }
+  if (details.status === "fast_forward") {
+    return `integrate_branch fast-forwarded ${target} from ${beforeTarget} to ${afterTarget}, integrating ${source}.`;
+  }
+  return `integrate_branch created and verified a merge commit ${afterTarget} on ${target} from previous target ${beforeTarget} and source ${source}.`;
+}
+
 const PULL_REQUEST_INPUT_FIELDS: PullRequestInputField[] = ["headBranch", "baseBranch", "title", "body", "draft"];
 
 interface ResolvedPullRequestBranches {
@@ -257,16 +458,18 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: BRANCH_STATUS_TOOL_NAME,
     label: "Branch Status",
-    description: "branch_status explicitly refreshes the current Git repository snapshot, including branch, working tree, unstaged changes, related pull request, and recent commits. branch_status is read-only and never mutates files, Git state, or GitHub state.",
-    promptSnippet: "branch_status: explicitly refresh current-repository branch, working tree, changes, related PR, and recent commits without mutation",
+    description: "branch_status explicitly refreshes the current Git repository snapshot and can optionally verify whether one captured local branch commit is an ancestor of another. branch_status is read-only and never mutates files, Git state, or GitHub state.",
+    promptSnippet: "branch_status: explicitly refresh current-repository Git state and optionally verify targeted local-branch ancestry without mutation",
     promptGuidelines: [
       "Use the automatic Git context for start-of-run questions; call branch_status only for an explicit refresh or after Git state changes during the current run.",
       "Use branch_status as a read-only refresh; branch_status never mutates files, Git state, or GitHub state.",
+      "Use targeted branch_status ancestry verification only after integrate_branch completes; do not issue branch_status in the same parallel tool batch as integrate_branch.",
     ],
-    parameters: EmptyParametersSchema,
-    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+    parameters: BranchStatusParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const details = await collectGitContext(pi, ctx, {
         signal,
+        ancestry: params.ancestry,
         env: options.env,
         fetchImpl: options.fetchImpl,
       });
@@ -390,6 +593,29 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
     },
   });
 
+  pi.registerTool({
+    name: INTEGRATE_BRANCH_TOOL_NAME,
+    label: "Integrate Branch",
+    description: "integrate_branch verifies and merges one exact existing local source branch into one exact existing local target branch from the current clean control worktree, returning an already-integrated, fast-forward, merge-commit, or automatically aborted conflict result. integrate_branch never fetches or pushes.",
+    promptSnippet: "integrate_branch: merge an exact local source branch into the checked-out clean local target with verified outcomes and automatic conflict abort",
+    promptGuidelines: [
+      "Use integrate_branch only when the user explicitly wants one exact existing local source branch integrated into one exact existing local target branch.",
+      "Before integrate_branch, require the current clean control worktree to already have targetBranch checked out; integrate_branch never switches branches, stashes, or discards changes.",
+      "Use integrate_branch only after local refs already contain the commits to integrate; integrate_branch never fetches or pushes.",
+      "Call integrate_branch by itself and wait for it to complete; never batch integrate_branch with other Git mutations.",
+      "After integrate_branch completes, run any targeted branch_status ancestry proof separately; never place integrate_branch and branch_status in the same parallel tool batch.",
+      "A conflict result from integrate_branch means the merge was automatically aborted and restoration was verified; semantic conflict analysis belongs to a separate delegated workflow, not integrate_branch.",
+    ],
+    parameters: IntegrateBranchParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await integrateBranch(pi, ctx, params, signal);
+      return {
+        content: [{ type: "text", text: formatIntegrateBranch(details) }],
+        details,
+      };
+    },
+  });
+
   pi.registerTool({
     name: PUSH_BRANCH_TOOL_NAME,
     label: "Push Branch",
@@ -464,4 +690,70 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       });
     },
   });
+
+  pi.registerTool({
+    name: LIST_WORKTREES_TOOL_NAME,
+    label: "List Worktrees",
+    description: "list_worktrees reads the current repository's bounded linked-worktree inventory without changing Git or filesystem state. list_worktrees accepts no parameters and reports paths, local branches or detached state, HEADs, and safety indicators.",
+    promptSnippet: "list_worktrees: explicitly inspect the bounded current-repository worktree inventory without mutation",
+    promptGuidelines: [
+      "Use list_worktrees when the user or task explicitly needs the current repository's worktree inventory; list_worktrees is read-only.",
+      "Use list_worktrees explicitly because automatic Git context remains focused on the active worktree and does not include worktree inventory.",
+    ],
+    parameters: EmptyParametersSchema,
+    async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+      const details = await listWorktrees(pi, ctx, signal);
+      return {
+        content: [{ type: "text", text: formatListWorktrees(details) }],
+        details,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: CREATE_WORKTREE_TOOL_NAME,
+    label: "Create Worktree",
+    description: "create_worktree creates and verifies one linked worktree at an explicit absolute worktreePath for either a new local branch from current HEAD or an existing unoccupied local branch. create_worktree returns exact lossless handoff identity fields and never infers paths, remotes, base refs, detached or orphan modes, or force behavior.",
+    promptSnippet: "create_worktree: create and verify a linked worktree at an explicit absolute path with a ready handoff cwd",
+    promptGuidelines: [
+      "Use create_worktree only when the user explicitly requests worktree creation and provides or approves the exact absolute worktreePath; create_worktree must never infer a filesystem path silently.",
+      "Use create_worktree with exactly worktreePath, branchName, and branchMode; create_worktree never accepts force, baseRef, remote, detach, orphan, move, prune, repair, lock, or unlock parameters.",
+      "Do not batch create_worktree with dependent worktree mutations; wait for create_worktree to complete and verify its ready exact handoff.cwd before passing that cwd to another agent or session.",
+    ],
+    parameters: CreateWorktreeParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await createWorktree(
+        pi,
+        ctx,
+        params.worktreePath,
+        params.branchName,
+        params.branchMode,
+        signal,
+      );
+      return {
+        content: [{ type: "text", text: formatCreateWorktree(details) }],
+        details,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: REMOVE_WORKTREE_TOOL_NAME,
+    label: "Remove Worktree",
+    description: "remove_worktree force-free removes one verified clean linked worktree at an explicit absolute worktreePath while retaining and returning its exact local branch identity. remove_worktree rejects main, current, dirty, detached, locked, prunable, missing, and foreign worktrees and never deletes branches.",
+    promptSnippet: "remove_worktree: force-free removal of an explicitly selected clean linked worktree while retaining its branch",
+    promptGuidelines: [
+      "Use remove_worktree only when the user explicitly requests worktree removal and provides or approves the exact absolute worktreePath; remove_worktree must never infer a filesystem path silently.",
+      "Use remove_worktree with exactly worktreePath; remove_worktree never accepts force, move, prune, repair, lock, unlock, branch deletion, remote, or refspec parameters.",
+      "Do not batch remove_worktree with dependent worktree mutations; wait for remove_worktree to complete and verify its non-ready handoff before continuing.",
+    ],
+    parameters: RemoveWorktreeParametersSchema,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const details = await removeWorktree(pi, ctx, params.worktreePath, signal);
+      return {
+        content: [{ type: "text", text: formatRemoveWorktree(details) }],
+        details,
+      };
+    },
+  });
 }

package/src/types.ts

@@ -20,6 +20,131 @@ export interface WorkingTreeDetails {
   untracked: number;
 }
 
+export interface BranchStatusAncestryQuery {
+  sourceBranch: string;
+  targetBranch: string;
+}
+
+export interface BranchStatusToolInput {
+  ancestry?: BranchStatusAncestryQuery;
+}
+
+export interface IntegrateBranchToolInput {
+  sourceBranch: string;
+  targetBranch: string;
+}
+
+export type CreateWorktreeMode = "new" | "existing";
+
+export type ListWorktreesToolInput = Record<string, never>;
+
+export interface CreateWorktreeToolInput {
+  worktreePath: string;
+  branchName: string;
+  branchMode: CreateWorktreeMode;
+}
+
+export interface RemoveWorktreeToolInput {
+  worktreePath: string;
+}
+
+export interface WorktreeEntry {
+  path: string;
+  head: string | null;
+  branch: string | null;
+  detached: boolean;
+  bare: boolean;
+  locked: boolean;
+  lockReason: string | null;
+  prunable: boolean;
+  pruneReason: string | null;
+  main: boolean;
+  current: boolean;
+}
+
+export interface VerifiedLinkedWorktreeEntry extends Omit<WorktreeEntry, "path" | "branch"> {
+  /** Exact machine-readable identity validated to require no BranchMe display transformation. */
+  path: string;
+  head: string;
+  /** Exact machine-readable identity validated to require no BranchMe display transformation. */
+  branch: string;
+  detached: false;
+  bare: false;
+  locked: false;
+  lockReason: null;
+  prunable: false;
+  pruneReason: null;
+  main: false;
+  current: false;
+}
+
+export interface ListWorktreesDetails {
+  action: "list_worktrees";
+  repoRoot: string;
+  worktrees: WorktreeEntry[];
+  omitted: number;
+}
+
+export interface ReadyWorktreeHandoffDetails {
+  cwd: string;
+  branch: string;
+  head: string;
+  ready: true;
+  summary: string;
+}
+
+export interface RetainedBranchHandoffDetails {
+  cwd: null;
+  branch: string;
+  head: string;
+  ready: false;
+  summary: string;
+}
+
+export type WorktreeHandoffDetails = ReadyWorktreeHandoffDetails | RetainedBranchHandoffDetails;
+
+export interface CreateWorktreeDetails {
+  action: "create_worktree";
+  repoRoot: string;
+  request: CreateWorktreeToolInput;
+  verified: {
+    before: {
+      sourcePath: string;
+      sourceBranch: string | null;
+      sourceDetached: boolean;
+      sourceHead: string;
+      canonicalWorktreePath: string;
+      branchExisted: boolean;
+      destinationRegistered: false;
+    };
+    after: {
+      worktreePresent: true;
+      worktree: VerifiedLinkedWorktreeEntry;
+      workingTree: WorkingTreeDetails;
+    };
+  };
+  handoff: ReadyWorktreeHandoffDetails;
+}
+
+export interface RemoveWorktreeDetails {
+  action: "remove_worktree";
+  repoRoot: string;
+  request: RemoveWorktreeToolInput;
+  verified: {
+    before: {
+      worktree: VerifiedLinkedWorktreeEntry;
+      workingTree: WorkingTreeDetails;
+    };
+    after: {
+      worktreePresent: false;
+      branchRetained: true;
+      branch: string;
+      head: string;
+    };
+  };
+  handoff: RetainedBranchHandoffDetails;
+}
+
 export interface GitFileChange {
   status: string;
   path: string;
@@ -54,6 +179,12 @@ export type RelatedPullRequest =
   | { status: "none" }
   | { status: "unavailable"; reason: string };
 
+export interface BranchAncestryDetails extends BranchStatusAncestryQuery {
+  sourceHead: string;
+  targetHead: string;
+  isAncestor: boolean;
+}
+
 export interface BranchStatusDetails {
   repoRoot: string;
   currentBranch: string | null;
@@ -62,6 +193,7 @@ export interface BranchStatusDetails {
   hasChanges: boolean;
   ahead: number | null;
   behind: number | null;
+  ancestry?: BranchAncestryDetails;
   warnings?: string[];
   githubRepository?: GitHubRepository;
 }
@@ -128,6 +260,100 @@ export interface PushBranchDetails {
   output: string;
 }
 
+export type IntegrateBranchStatus = "already_integrated" | "fast_forward" | "merge_commit" | "conflict";
+
+export interface IntegrateBranchHeads {
+  sourceHead: string;
+  targetHead: string;
+}
+
+export interface IntegrateBranchRepositoryVerification {
+  worktreeRoot: string;
+  canonicalCommonGitDirectory: string;
+  identityPreserved: true;
+}
+
+export interface IntegrateBranchControlWorktreeVerification {
+  targetBranch: string;
+  currentBranchPreserved: true;
+  cleanBefore: true;
+  cleanAfter: true;
+  operationStateAbsentBefore: true;
+  operationStateAbsentAfter: true;
+}
+
+export interface IntegrateBranchFinalAncestryProof {
+  sourceHead: string;
+  previousTargetHead: string;
+  targetHead: string;
+  sourceIsAncestorOfTarget: boolean;
+  previousTargetIsAncestorOfTarget: boolean;
+}
+
+export interface IntegrateBranchVerification {
+  repository: IntegrateBranchRepositoryVerification;
+  controlWorktree: IntegrateBranchControlWorktreeVerification;
+  heads: {
+    before: IntegrateBranchHeads;
+    after: IntegrateBranchHeads;
+  };
+  finalAncestry: IntegrateBranchFinalAncestryProof;
+}
+
+export interface IntegrateBranchDetailsBase {
+  action: "integrate_branch";
+  request: IntegrateBranchToolInput;
+  verified: IntegrateBranchVerification;
+}
+
+export interface IntegrateBranchAlreadyIntegratedDetails extends IntegrateBranchDetailsBase {
+  status: "already_integrated";
+  mergeExecuted: false;
+}
+
+export interface IntegrateBranchFastForwardDetails extends IntegrateBranchDetailsBase {
+  status: "fast_forward";
+  mergeExecuted: true;
+}
+
+export interface IntegrateBranchMergeCommitDetails extends IntegrateBranchDetailsBase {
+  status: "merge_commit";
+  mergeExecuted: true;
+}
+
+export interface IntegrateBranchConflictPathEntry {
+  /** Exact repository-relative identity; human-readable renderers must sanitize a separate display copy. */
+  path: string;
+}
+
+export interface IntegrateBranchConflictDetails extends IntegrateBranchDetailsBase {
+  status: "conflict";
+  mergeExecuted: true;
+  conflict: {
+    paths: IntegrateBranchConflictPathEntry[];
+    omitted: number;
+    abort: {
+      attempted: true;
+      succeeded: true;
+    };
+    restoration: {
+      verified: true;
+      repositoryIdentityPreserved: true;
+      controlWorktreeBranchPreserved: true;
+      sourceHeadPreserved: true;
+      targetHeadRestored: true;
+      operationStateCleared: true;
+      cleanControlWorktree: true;
+    };
+  };
+}
+
+export type IntegrateBranchDetails =
+  | IntegrateBranchAlreadyIntegratedDetails
+  | IntegrateBranchFastForwardDetails
+  | IntegrateBranchMergeCommitDetails
+  | IntegrateBranchConflictDetails;
+
 export interface PullRequestDetails {
   repository: GitHubRepository;
   number: number;