@senad-d/branchme 0.1.6 → 0.1.8

package/src/github.ts

@@ -10,6 +10,7 @@ import {
   GITHUB_USER_AGENT,
   GIT_CONTEXT_VALUE_LIMIT_CHARS,
   MAX_SUMMARY_OUTPUT_CHARS,
+  PULL_REQUEST_AUTOFILL_ENV_NAME,
 } from "./constants.ts";
 import {
   getCurrentBranch,
@@ -27,6 +28,9 @@ import type {
 } from "./types.ts";
 
 type TokenEnvironmentKey = "GITHUB_TOKEN" | "GH_TOKEN";
+type PullRequestAutofillEnvironmentKey = typeof PULL_REQUEST_AUTOFILL_ENV_NAME;
+type SupportedDotEnvKey = TokenEnvironmentKey | PullRequestAutofillEnvironmentKey;
+type DotEnvReadPurpose = "GitHub token fallback" | "pull request autofill configuration";
 
 export type TokenResolutionSource = TokenEnvironmentKey | `${TokenEnvironmentKey} (.env)`;
 
@@ -149,8 +153,8 @@ function resolveProcessToken(env: NodeJS.ProcessEnv): TokenResolution | null {
   return null;
 }
 
-function isTokenEnvironmentKey(value: string): value is TokenEnvironmentKey {
-  return value === "GITHUB_TOKEN" || value === "GH_TOKEN";
+function isSupportedDotEnvKey(value: string): value is SupportedDotEnvKey {
+  return value === "GITHUB_TOKEN" || value === "GH_TOKEN" || value === PULL_REQUEST_AUTOFILL_ENV_NAME;
 }
 
 function decodeDoubleQuotedDotEnvValue(value: string): string {
@@ -182,23 +186,46 @@ function stripDotEnvInlineComment(value: string): string {
   return value;
 }
 
+function closingDotEnvQuoteIndex(value: string, quote: "\"" | "'"): number {
+  let escaped = false;
+  for (let index = 1; index < value.length; index += 1) {
+    const character = value.charAt(index);
+    if (quote === "\"" && character === "\\" && !escaped) {
+      escaped = true;
+      continue;
+    }
+    if (character === quote && !escaped) return index;
+    escaped = false;
+  }
+  return -1;
+}
+
+function parseQuotedDotEnvValue(value: string): string | null {
+  const quote = value.charAt(0);
+  if (quote !== "\"" && quote !== "'") return null;
+
+  const closingIndex = closingDotEnvQuoteIndex(value, quote);
+  if (closingIndex === -1) return null;
+
+  const remainder = value.slice(closingIndex + 1).trim();
+  if (remainder && !remainder.startsWith("#")) return null;
+
+  const quotedValue = value.slice(1, closingIndex);
+  return quote === "\"" ? decodeDoubleQuotedDotEnvValue(quotedValue).trim() : quotedValue.trim();
+}
+
 function parseDotEnvValue(rawValue: string): string {
   const value = rawValue.trim();
   if (!value) return "";
 
-  if (value.startsWith("\"") && value.endsWith("\"")) {
-    return decodeDoubleQuotedDotEnvValue(value.slice(1, -1)).trim();
-  }
-
-  if (value.startsWith("'") && value.endsWith("'")) {
-    return value.slice(1, -1).trim();
-  }
+  const quotedValue = parseQuotedDotEnvValue(value);
+  if (quotedValue !== null) return quotedValue;
 
   return stripDotEnvInlineComment(value).trim();
 }
 
-function parseDotEnvTokens(contents: string): Partial<Record<TokenEnvironmentKey, string>> {
-  const tokens: Partial<Record<TokenEnvironmentKey, string>> = {};
+function parseDotEnvValues(contents: string): Partial<Record<SupportedDotEnvKey, string>> {
+  const values: Partial<Record<SupportedDotEnvKey, string>> = {};
 
   for (const line of contents.split(/\r?\n/u)) {
     const trimmed = line.trim();
@@ -209,12 +236,12 @@ function parseDotEnvTokens(contents: string): Partial<Record<TokenEnvironmentKey
     if (separatorIndex === -1) continue;
 
     const key = assignment.slice(0, separatorIndex).trim();
-    if (!isTokenEnvironmentKey(key)) continue;
+    if (!isSupportedDotEnvKey(key)) continue;
 
-    tokens[key] = parseDotEnvValue(assignment.slice(separatorIndex + 1).trimStart());
+    values[key] = parseDotEnvValue(assignment.slice(separatorIndex + 1).trimStart());
   }
 
-  return tokens;
+  return values;
 }
 
 const MAX_DOTENV_BYTES = 64 * 1024;
@@ -223,55 +250,77 @@ function isMissingFileError(error: unknown): boolean {
   return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
 }
 
-function throwIfAborted(signal: AbortSignal | undefined): void {
-  if (signal?.aborted) throw new Error("GitHub token .env fallback was aborted.");
+function throwIfAborted(signal: AbortSignal | undefined, purpose: DotEnvReadPurpose): void {
+  if (signal?.aborted) throw new Error(`${purpose} .env read was aborted.`);
 }
 
 function errorMessage(error: unknown): string {
   return redactSecrets(error instanceof Error ? error.message : String(error));
 }
 
-async function readDotEnvTokens(
+async function readDotEnvValues(
   cwd: string | undefined,
   signal?: AbortSignal,
-): Promise<Partial<Record<TokenEnvironmentKey, string>>> {
+  purpose: DotEnvReadPurpose = "GitHub token fallback",
+): Promise<Partial<Record<SupportedDotEnvKey, string>>> {
   if (!cwd) return {};
 
   const envPath = join(cwd, ".env");
-  throwIfAborted(signal);
+  throwIfAborted(signal, purpose);
 
   let stats: Awaited<ReturnType<typeof lstat>>;
   try {
     stats = await lstat(envPath);
   } catch (error) {
     if (isMissingFileError(error)) return {};
-    throw new Error(`Unable to inspect .env file for GitHub token fallback: ${errorMessage(error)}`);
+    throw new Error(`Unable to inspect .env file for ${purpose}: ${errorMessage(error)}`);
   }
 
   if (!stats.isFile()) {
-    throw new Error("Unable to read .env file for GitHub token fallback: .env must be a small regular file.");
+    throw new Error(`Unable to read .env file for ${purpose}: .env must be a small regular file.`);
   }
   if (stats.size > MAX_DOTENV_BYTES) {
     throw new Error(
-      `Unable to read .env file for GitHub token fallback: .env is too large (${stats.size} bytes; limit ${MAX_DOTENV_BYTES} bytes).`,
+      `Unable to read .env file for ${purpose}: .env is too large (${stats.size} bytes; limit ${MAX_DOTENV_BYTES} bytes).`,
     );
   }
 
-  throwIfAborted(signal);
+  throwIfAborted(signal, purpose);
 
   let contents: string;
   try {
     contents = await readFile(envPath, { encoding: "utf8", signal });
   } catch (error) {
     if (isMissingFileError(error)) return {};
-    throw new Error(`Unable to read .env file for GitHub token fallback: ${errorMessage(error)}`);
+    throw new Error(`Unable to read .env file for ${purpose}: ${errorMessage(error)}`);
   }
 
   if (Buffer.byteLength(contents, "utf8") > MAX_DOTENV_BYTES) {
-    throw new Error(`Unable to read .env file for GitHub token fallback: .env exceeded the ${MAX_DOTENV_BYTES} byte limit.`);
+    throw new Error(`Unable to read .env file for ${purpose}: .env exceeded the ${MAX_DOTENV_BYTES} byte limit.`);
   }
 
-  return parseDotEnvTokens(contents);
+  return parseDotEnvValues(contents);
+}
+
+function parsePullRequestAutofillValue(value: string): boolean {
+  const normalized = value.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  throw new Error(
+    `${PULL_REQUEST_AUTOFILL_ENV_NAME} must be one of true, false, 1, 0, yes, no, on, or off.`,
+  );
+}
+
+export async function resolvePullRequestAutofill(
+  env: NodeJS.ProcessEnv = process.env,
+  options: TokenResolutionOptions = {},
+): Promise<boolean> {
+  const processValue = env[PULL_REQUEST_AUTOFILL_ENV_NAME];
+  if (processValue !== undefined) return parsePullRequestAutofillValue(processValue);
+
+  const dotEnvValues = await readDotEnvValues(options.cwd, options.signal, "pull request autofill configuration");
+  const dotEnvValue = dotEnvValues[PULL_REQUEST_AUTOFILL_ENV_NAME];
+  return dotEnvValue === undefined ? false : parsePullRequestAutofillValue(dotEnvValue);
 }
 
 export async function resolveGitHubToken(
@@ -281,7 +330,7 @@ export async function resolveGitHubToken(
   const processToken = resolveProcessToken(env);
   if (processToken) return processToken;
 
-  const dotEnvTokens = await readDotEnvTokens(options.cwd, options.signal);
+  const dotEnvTokens = await readDotEnvValues(options.cwd, options.signal);
   const githubToken = dotEnvTokens.GITHUB_TOKEN?.trim();
   if (githubToken) return { token: githubToken, source: "GITHUB_TOKEN (.env)" };
 

package/src/tools/branchme-tools.ts

@@ -1,25 +1,36 @@
+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_WORKTREE_SUMMARY_LIMIT_CHARS,
+  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";
@@ -31,9 +42,22 @@ import {
   repositoryLabel,
   resolveGitHubRepository,
   resolveGitHubToken,
+  resolvePullRequestAutofill,
   validatePullRequestBranchRef,
 } from "../github.ts";
-import type { ChangeBranchDetails, GitContextDetails, PullRequestDetails } from "../types.ts";
+import type {
+  ChangeBranchDetails,
+  CreateWorktreeDetails,
+  GitContextDetails,
+  ListWorktreesDetails,
+  PullRequestDetails,
+  PullRequestInput,
+  PullRequestInputField,
+  PullRequestToolDetails,
+  PullRequestToolInput,
+  RemoveWorktreeDetails,
+  WorktreeEntry,
+} from "../types.ts";
 
 const EmptyParametersSchema = Type.Object({}, { additionalProperties: false });
 
@@ -51,13 +75,37 @@ 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.String({ minLength: 1, description: "Existing local branch containing the pull request changes." }),
-    baseBranch: Type.String({ minLength: 1, description: "Existing local target branch for the pull request." }),
-    title: Type.String({ minLength: 1, description: "Pull request title." }),
-    body: Type.String({ description: "Pull request body. Pass an empty string only when intentionally blank." }),
-    draft: Type.Boolean({ description: "Whether to create the pull request as a draft." }),
+    headBranch: Type.Optional(
+      Type.String({ minLength: 1, description: "Existing local branch containing the pull request changes. May be omitted in PR autofill mode." }),
+    ),
+    baseBranch: Type.Optional(
+      Type.String({ minLength: 1, description: "Existing local target branch for the pull request. May be omitted in PR autofill mode." }),
+    ),
+    title: Type.Optional(Type.String({ minLength: 1, description: "Pull request title. May be omitted in PR autofill mode." })),
+    body: Type.Optional(
+      Type.String({ description: "Pull request body. Pass an empty string only when intentionally blank; may be omitted in PR autofill mode." }),
+    ),
+    draft: Type.Optional(Type.Boolean({ description: "Whether to create the pull request as a draft. Defaults to false in PR autofill mode." })),
   },
   { additionalProperties: false },
 );
@@ -77,8 +125,156 @@ export function formatChangeBranch(details: ChangeBranchDetails): string {
   return `Changed branch from ${previous} to ${details.currentBranch}.`;
 }
 
-export function formatPullRequest(details: PullRequestDetails): string {
-  return `Created pull request #${details.number} (${details.state}) for ${repositoryLabel(details.repository)}: ${details.url}`;
+export function formatPullRequest(details: PullRequestDetails, autofilledFields: PullRequestInputField[] = []): string {
+  const autofill = autofilledFields.length > 0 ? ` Autofilled fields: ${autofilledFields.join(", ")}.` : "";
+  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.`;
+}
+
+const PULL_REQUEST_INPUT_FIELDS: PullRequestInputField[] = ["headBranch", "baseBranch", "title", "body", "draft"];
+
+interface ResolvedPullRequestBranches {
+  headBranch: string;
+  baseBranch: string;
+  autofilledFields: PullRequestInputField[];
+}
+
+interface ResolvedPullRequestInput {
+  input: PullRequestInput;
+  autofilledFields: PullRequestInputField[];
+}
+
+function missingPullRequestInputFields(params: PullRequestToolInput): PullRequestInputField[] {
+  return PULL_REQUEST_INPUT_FIELDS.filter((field) => params[field] === undefined);
+}
+
+function generatedPullRequestTitle(
+  headBranch: string,
+  commitSubjects: string[],
+  tokens: readonly string[],
+): string {
+  if (commitSubjects[0]) return commitSubjects[0];
+
+  const branchSegment = headBranch.split("/").at(-1) ?? headBranch;
+  const words = redactSecrets(branchSegment, tokens).replace(/[-_]+/gu, " ").trim();
+  if (!words) return "Update project";
+  return `${words.charAt(0).toUpperCase()}${words.slice(1)}`;
+}
+
+function escapePullRequestMarkdownText(value: string): string {
+  return value.replace(/[!-/:-@[-`{-~]/gu, String.raw`\$&`);
+}
+
+function generatedPullRequestBody(commitSubjects: string[]): string {
+  if (commitSubjects.length === 0) return "";
+  const bullets = commitSubjects.map((subject) => `- ${escapePullRequestMarkdownText(subject)}`);
+  return ["## Summary", "", ...bullets, "", "_Generated by BranchMe from commit subjects._"].join("\n");
+}
+
+async function requirePullRequestAutofill(
+  missingFields: PullRequestInputField[],
+  env: NodeJS.ProcessEnv | undefined,
+  repoRoot: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (missingFields.length === 0) return;
+  if (await resolvePullRequestAutofill(env, { cwd: repoRoot, signal })) return;
+  throw new Error(
+    `Missing pull_request fields: ${missingFields.join(", ")}. Provide them explicitly or set BRANCHME_PR_AUTOFILL=true in the process environment or repository .env file.`,
+  );
 }
 
 async function validateLocalPullRequestBranchName(
@@ -109,6 +305,60 @@ async function requireExistingValidatedLocalPullRequestBranch(
   throw new Error(`${field} local branch '${redactSecrets(branchName)}' does not exist.`);
 }
 
+async function resolvePullRequestBranches(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: { cwd: string },
+  params: PullRequestToolInput,
+  env: NodeJS.ProcessEnv | undefined,
+  signal?: AbortSignal,
+): Promise<ResolvedPullRequestBranches> {
+  const autofilledFields = missingPullRequestInputFields(params);
+  await requirePullRequestAutofill(autofilledFields, env, ctx.cwd, signal);
+
+  const headBranch = params.headBranch ?? await requireCurrentBranch(pi, ctx, signal);
+  const baseBranch = params.baseBranch ?? await inferPullRequestBaseBranch(pi, ctx, headBranch, signal);
+  if (headBranch === baseBranch) throw new Error("headBranch and baseBranch must be different branches.");
+
+  await validateLocalPullRequestBranchName(pi, ctx, headBranch, "headBranch", signal);
+  await validateLocalPullRequestBranchName(pi, ctx, baseBranch, "baseBranch", signal);
+  await requireExistingValidatedLocalPullRequestBranch(pi, ctx, headBranch, "headBranch", signal);
+  await requireExistingValidatedLocalPullRequestBranch(pi, ctx, baseBranch, "baseBranch", signal);
+
+  return { headBranch, baseBranch, autofilledFields };
+}
+
+async function resolvePullRequestInput(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: { cwd: string },
+  params: PullRequestToolInput,
+  branches: ResolvedPullRequestBranches,
+  tokens: readonly string[],
+  signal?: AbortSignal,
+): Promise<ResolvedPullRequestInput> {
+  const needsCommitSubjects = params.title === undefined || params.body === undefined;
+  const commitSubjects = needsCommitSubjects
+    ? await getPullRequestCommitSubjects(
+      pi,
+      ctx,
+      branches.headBranch,
+      branches.baseBranch,
+      signal,
+      tokens,
+    )
+    : [];
+
+  return {
+    input: {
+      headBranch: branches.headBranch,
+      baseBranch: branches.baseBranch,
+      title: params.title ?? generatedPullRequestTitle(branches.headBranch, commitSubjects, tokens),
+      body: params.body ?? generatedPullRequestBody(commitSubjects),
+      draft: params.draft ?? false,
+    },
+    autofilledFields: branches.autofilledFields,
+  };
+}
+
 function shortCommit(commit: string): string {
   return commit.slice(0, 12);
 }
@@ -288,10 +538,12 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: PULL_REQUEST_TOOL_NAME,
     label: "Pull Request",
-    description: "pull_request creates a GitHub pull request in the resolved current repository. pull_request requires headBranch and baseBranch to exist as safe local branch names, requires headBranch to match the GitHub-visible branch commit, and requires baseBranch to be visible on GitHub. Owner-prefixed refs, owner, and repo are never accepted as inputs.",
-    promptSnippet: "pull_request: create a GitHub pull request in the current repository with all PR fields explicit",
+    description: "pull_request creates a GitHub pull request in the resolved current repository. PR fields are optional only when BRANCHME_PR_AUTOFILL=true; pull_request then infers branches, derives title/body from commit subjects, and defaults draft to false. Branches must exist locally and on GitHub, and headBranch must match the GitHub-visible commit. Owner-prefixed refs, owner, and repo are never accepted as inputs.",
+    promptSnippet: "pull_request: create a GitHub pull request with explicit fields or optional configured PR field autofill",
     promptGuidelines: [
-      "Use pull_request only when the user provides explicit headBranch, baseBranch, title, body, and draft values.",
+      "Use pull_request only when the user explicitly asks to create a pull request; pull_request must not create one merely because a branch was pushed.",
+      "When automatic Git context reports pull request field autofill disabled, use pull_request only with explicit headBranch, baseBranch, title, body, and draft values.",
+      "When automatic Git context reports pull request field autofill enabled, pull_request may omit fields the user did not provide; prefer the user's explicit values whenever present.",
       "Use pull_request only with existing local branches for headBranch and baseBranch; headBranch must match the GitHub-visible branch commit.",
       "Do not call push_branch and pull_request in the same tool batch; call pull_request only after push_branch has completed.",
       "Use pull_request only for the resolved current repository; pull_request never accepts owner, repo, or owner-prefixed branch refs.",
@@ -303,30 +555,31 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       const rootCtx = { cwd: repoRoot };
 
       return withRepositoryMutationQueue(repoRoot, async () => {
-        await validateLocalPullRequestBranchName(pi, rootCtx, params.headBranch, "headBranch", signal);
-        await validateLocalPullRequestBranchName(pi, rootCtx, params.baseBranch, "baseBranch", signal);
-        await requireExistingValidatedLocalPullRequestBranch(pi, rootCtx, params.headBranch, "headBranch", signal);
-        await requireExistingValidatedLocalPullRequestBranch(pi, rootCtx, params.baseBranch, "baseBranch", signal);
+        const branches = await resolvePullRequestBranches(pi, rootCtx, params, options.env, signal);
         const repository = await resolveGitHubRepository(pi, rootCtx, signal, options.env);
         const token = (await resolveGitHubToken(options.env, { cwd: repoRoot, signal })).token;
 
         try {
-          const headBranch = await ensureGitHubBranchExists(repository, params.headBranch, "headBranch", token, {
+          const resolved = await resolvePullRequestInput(pi, rootCtx, params, branches, [token], signal);
+          const headBranch = await ensureGitHubBranchExists(repository, resolved.input.headBranch, "headBranch", token, {
             fetchImpl: options.fetchImpl,
             signal,
           });
-          await requireGitHubHeadMatchesLocalBranch(pi, rootCtx, params.headBranch, headBranch.commitSha, signal);
-          await ensureGitHubBranchExists(repository, params.baseBranch, "baseBranch", token, {
+          await requireGitHubHeadMatchesLocalBranch(pi, rootCtx, resolved.input.headBranch, headBranch.commitSha, signal);
+          await ensureGitHubBranchExists(repository, resolved.input.baseBranch, "baseBranch", token, {
             fetchImpl: options.fetchImpl,
             signal,
           });
-          const details = await createGitHubPullRequest(repository, params, token, {
+          const details = await createGitHubPullRequest(repository, resolved.input, token, {
             fetchImpl: options.fetchImpl,
             signal,
           });
+          const toolDetails: PullRequestToolDetails = resolved.autofilledFields.length > 0
+            ? { ...details, autofilledFields: resolved.autofilledFields }
+            : details;
           return {
-            content: [{ type: "text", text: formatPullRequest(details) }],
-            details,
+            content: [{ type: "text", text: formatPullRequest(details, resolved.autofilledFields) }],
+            details: toolDetails,
           };
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
@@ -335,4 +588,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,
+      };
+    },
+  });
 }