@mcuste/pi-herdr-worktree 0.1.0

package/src/tools.ts

@@ -0,0 +1,952 @@
+import type { Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute, relative } from "node:path";
+import { type Static, type TSchema, Type } from "typebox";
+import {
+  hasParsedArgumentSyntax,
+  MAX_BRANCH_NAME_LENGTH,
+  MAX_LABEL_LENGTH,
+  MAX_PATH_LENGTH,
+  MAX_WORKSPACE_ID_LENGTH,
+  MIN_WORKSPACE_ID_LENGTH,
+  type ParsedAbsolutePath,
+  type ParsedArgumentValue,
+  type ParsedBase,
+  type ParsedBranchName,
+  type ParsedLabel,
+  type ParsedRevision,
+  type ParsedWorkspaceId,
+  parseAbsolutePath,
+  parseBase,
+  parseBranchName,
+  parseLabel,
+  parseWorkspaceId,
+} from "./argument.js";
+import {
+  type GitRepository,
+  type HerdrCapability,
+  HerdrCapabilityResolver,
+  HerdrUnavailableError,
+} from "./capability.js";
+import { type HerdrPromptApi, registerHerdrGuidance } from "./guidance.js";
+import {
+  CommandCancelledError,
+  CommandInvocationError,
+  type CommandResult,
+  type CommandRunner,
+  runCommand,
+} from "./process.js";
+import {
+  parseEnvelope,
+  parseWorktreeList,
+  parseWorktreeOpened,
+  parseWorktreeRemoved,
+  type WorktreeInfo,
+  type WorktreeListResult,
+  type WorktreeOpenedResult,
+  type WorktreeRemovedResult,
+} from "./response.js";
+import { findGitWorktree, type GitWorktreeEntry, readGitWorktrees } from "./worktree.js";
+
+const BranchName = Type.String({
+  minLength: 1,
+  maxLength: MAX_BRANCH_NAME_LENGTH,
+  description: "Exact branch name. Leading options are rejected.",
+});
+
+const CheckoutPath = Type.String({
+  minLength: 1,
+  maxLength: MAX_PATH_LENGTH,
+  description: "Absolute path of the worktree checkout.",
+});
+
+const WorkspaceLabel = Type.String({
+  minLength: 1,
+  maxLength: MAX_LABEL_LENGTH,
+  description: "Single-line label shown for the workspace in the Herdr sidebar.",
+});
+
+const Focus = Type.Boolean({
+  description: "Move the user's view to the new workspace. Defaults to false.",
+});
+
+const HerdrWorktreeParameters = Type.Union([
+  Type.Object({ operation: Type.Literal("list") }, { additionalProperties: false }),
+  Type.Object(
+    {
+      operation: Type.Literal("create"),
+      branch: BranchName,
+      base: Type.Optional(
+        Type.String({
+          minLength: 1,
+          maxLength: MAX_BRANCH_NAME_LENGTH,
+          description: "Existing commit, branch, or tag the new branch starts from.",
+        }),
+      ),
+      path: Type.Optional(CheckoutPath),
+      label: Type.Optional(WorkspaceLabel),
+      focus: Type.Optional(Focus),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      operation: Type.Literal("open"),
+      path: Type.Optional(CheckoutPath),
+      branch: Type.Optional(BranchName),
+      label: Type.Optional(WorkspaceLabel),
+      focus: Type.Optional(Focus),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      operation: Type.Literal("remove"),
+      workspace_id: Type.String({
+        minLength: MIN_WORKSPACE_ID_LENGTH,
+        maxLength: MAX_WORKSPACE_ID_LENGTH,
+        description: "Herdr workspace id of the worktree workspace to remove, such as `wG`.",
+      }),
+      force: Type.Optional(
+        Type.Boolean({
+          description: "Remove the checkout even when it holds uncommitted changes.",
+        }),
+      ),
+    },
+    { additionalProperties: false },
+  ),
+]);
+
+type HerdrWorktreeParameters = Static<typeof HerdrWorktreeParameters>;
+type HerdrWorktreeOperation = HerdrWorktreeParameters["operation"];
+
+/** The fields one operation accepts, typed against the schema so the two cannot drift. */
+type FieldsOf<TOperation extends HerdrWorktreeOperation> = keyof Extract<
+  HerdrWorktreeParameters,
+  { operation: TOperation }
+> &
+  string;
+
+interface RequestSchema<TOperation extends HerdrWorktreeOperation> {
+  readonly required: readonly FieldsOf<TOperation>[];
+  readonly optional: readonly FieldsOf<TOperation>[];
+}
+
+export const OPERATION_FIELDS: { readonly [K in HerdrWorktreeOperation]: RequestSchema<K> } = {
+  list: { required: ["operation"], optional: [] },
+  create: { required: ["operation", "branch"], optional: ["base", "path", "label", "focus"] },
+  open: { required: ["operation"], optional: ["path", "branch", "label", "focus"] },
+  remove: { required: ["operation", "workspace_id"], optional: ["force"] },
+};
+
+type ParsedOperation =
+  | { readonly operation: "list" }
+  | {
+      readonly operation: "create";
+      readonly branch: ParsedBranchName;
+      readonly base: ParsedBase | undefined;
+      readonly path: ParsedAbsolutePath | undefined;
+      readonly label: ParsedLabel | undefined;
+      readonly focus: boolean;
+    }
+  | {
+      readonly operation: "open";
+      readonly path: ParsedAbsolutePath | undefined;
+      readonly branch: ParsedBranchName | undefined;
+      readonly label: ParsedLabel | undefined;
+      readonly focus: boolean;
+    }
+  | {
+      readonly operation: "remove";
+      readonly workspaceId: ParsedWorkspaceId;
+      readonly force: boolean;
+    };
+
+/** The only `herdr` subcommand this extension is allowed to spawn. */
+const HERDR_SUBCOMMAND = "worktree";
+
+type HerdrAction = "list" | "create" | "open" | "remove";
+
+type HerdrSwitch = "--focus" | "--no-focus" | "--force";
+
+/** An option and its value, so a value can only travel under the option it was parsed for. */
+type HerdrOption =
+  | { readonly name: "--cwd"; readonly value: ParsedAbsolutePath }
+  | { readonly name: "--branch"; readonly value: ParsedBranchName }
+  | { readonly name: "--base"; readonly value: ParsedRevision }
+  | { readonly name: "--path"; readonly value: ParsedAbsolutePath }
+  | { readonly name: "--label"; readonly value: ParsedLabel }
+  | { readonly name: "--workspace"; readonly value: ParsedWorkspaceId };
+
+interface HerdrCommand {
+  readonly action: HerdrAction;
+  readonly options: readonly HerdrOption[];
+  readonly switches: readonly HerdrSwitch[];
+}
+
+const ALLOWED_OPTIONS: Record<HerdrAction, readonly HerdrOption["name"][]> = {
+  list: ["--cwd"],
+  create: ["--cwd", "--branch", "--base", "--path", "--label"],
+  open: ["--cwd", "--branch", "--path", "--label"],
+  remove: ["--workspace"],
+};
+
+const ALLOWED_SWITCHES: Record<HerdrAction, readonly HerdrSwitch[]> = {
+  list: [],
+  create: ["--focus", "--no-focus"],
+  open: ["--focus", "--no-focus"],
+  remove: ["--force"],
+};
+
+interface TextContent {
+  readonly type: "text";
+  readonly text: string;
+}
+
+interface ToolResult<TDetails> {
+  readonly content: readonly TextContent[];
+  readonly details: TDetails;
+}
+
+interface ToolContext {
+  readonly cwd: string;
+  readonly ui?: {
+    confirm(title: string, message: string): Promise<boolean>;
+  };
+}
+
+type ToolTier = "read" | "write" | "exec";
+
+type ToolApprovalDecision =
+  | ToolTier
+  | {
+      readonly tier: ToolTier;
+      readonly reason?: string;
+      readonly policy?: "allow" | "deny" | "prompt";
+    };
+
+interface ToolDefinition<TParameters extends TSchema, TDetails> {
+  readonly name: string;
+  readonly label: string;
+  readonly description: string;
+  readonly parameters: TParameters;
+  readonly approval: ToolApprovalDecision | ((args: unknown) => ToolApprovalDecision);
+  readonly loadMode: "essential" | "discoverable";
+  readonly concurrency?:
+    | "shared"
+    | "exclusive"
+    | ((args: Partial<Static<TParameters>>) => "shared" | "exclusive");
+  readonly executionMode?: "sequential" | "parallel";
+  readonly formatApprovalDetails?: (args: unknown) => string | readonly string[] | undefined;
+  execute(
+    toolCallId: string,
+    parameters: Static<TParameters>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    context: ToolContext,
+  ): Promise<ToolResult<TDetails>>;
+}
+
+export interface HerdrExtensionApi extends HerdrPromptApi {
+  registerTool<TParameters extends TSchema, TDetails>(
+    definition: ToolDefinition<TParameters, TDetails>,
+  ): void;
+}
+
+export interface HerdrExtensionDependencies {
+  readonly runner?: CommandRunner;
+  readonly capabilities?: HerdrCapabilityResolver;
+}
+
+interface CommandDetails {
+  readonly executable: string;
+  readonly args: readonly string[];
+  readonly exitCode: number;
+}
+
+interface CapabilityDetails {
+  readonly repositoryRoot: string;
+  readonly herdrVersion: string;
+  readonly cache: HerdrCapability["cache"];
+}
+
+interface ListDetails {
+  readonly operation: "list";
+  readonly capability: CapabilityDetails;
+  readonly command: CommandDetails;
+  readonly result: WorktreeListResult;
+}
+
+interface OpenDetails {
+  readonly operation: "create" | "open";
+  readonly capability: CapabilityDetails;
+  readonly command: CommandDetails;
+  readonly result: WorktreeOpenedResult;
+}
+
+interface RemoveDetails {
+  readonly operation: "remove";
+  readonly capability: CapabilityDetails;
+  readonly command: CommandDetails;
+  readonly result: WorktreeRemovedResult;
+}
+
+type HerdrWorktreeToolDetails = ListDetails | OpenDetails | RemoveDetails;
+
+const repositoryQueues = new Map<string, Promise<void>>();
+
+async function withRepositoryLock<T>(
+  repositoryRoot: ParsedAbsolutePath,
+  signal: AbortSignal | undefined,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const predecessor = repositoryQueues.get(repositoryRoot) ?? Promise.resolve();
+  const { promise: releasePromise, resolve: release } = Promise.withResolvers<void>();
+  const queueTail = predecessor.then(() => releasePromise);
+  repositoryQueues.set(repositoryRoot, queueTail);
+
+  await predecessor;
+  try {
+    if (signal?.aborted) {
+      throw new CommandCancelledError("Herdr worktree operation");
+    }
+    return await operation();
+  } finally {
+    release();
+    if (repositoryQueues.get(repositoryRoot) === queueTail) {
+      repositoryQueues.delete(repositoryRoot);
+    }
+  }
+}
+
+function capabilityDetails(capability: HerdrCapability): CapabilityDetails {
+  return {
+    repositoryRoot: capability.repository.root,
+    herdrVersion: capability.herdrVersion,
+    cache: capability.cache,
+  };
+}
+
+function commandDetails(result: CommandResult): CommandDetails {
+  return { executable: result.command, args: result.args, exitCode: result.exitCode };
+}
+
+function parseOperationFrom(args: unknown): HerdrWorktreeOperation | undefined {
+  if (!args || typeof args !== "object") {
+    return undefined;
+  }
+  switch (Reflect.get(args, "operation")) {
+    case "list":
+      return "list";
+    case "create":
+      return "create";
+    case "open":
+      return "open";
+    case "remove":
+      return "remove";
+    default:
+      return undefined;
+  }
+}
+
+/** The fields an operation declares, with values that are not parsed yet. */
+type RequestFields<TOperation extends HerdrWorktreeOperation> = Readonly<
+  Record<FieldsOf<TOperation>, unknown>
+>;
+
+function parseRequestFields<TOperation extends HerdrWorktreeOperation>(
+  parameters: unknown,
+  operation: TOperation,
+  fields: RequestSchema<TOperation>,
+): RequestFields<TOperation> {
+  if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) {
+    throw new Error(`Operation ${operation} requires an object request.`);
+  }
+  const entries = Object.entries(parameters);
+  const present = entries.map(([field]) => field);
+  const allowed: readonly string[] = [...fields.required, ...fields.optional];
+  const unexpected = present.filter((field) => !allowed.includes(field));
+  if (unexpected.length > 0) {
+    throw new Error(
+      `Operation ${operation} does not accept ${unexpected.join(", ")}. Allowed fields: ${allowed.join(", ")}.`,
+    );
+  }
+  const missing = fields.required.filter((field) => !present.includes(field));
+  if (missing.length > 0) {
+    throw new Error(`Operation ${operation} requires ${missing.join(", ")}.`);
+  }
+  // A null prototype, so an absent field cannot resolve to an inherited value.
+  return Object.assign(
+    Object.create(null) as Record<string, unknown>,
+    Object.fromEntries(entries),
+  ) as RequestFields<TOperation>;
+}
+
+function parseFlag(raw: unknown, label: string): boolean {
+  if (raw === undefined || typeof raw === "boolean") {
+    return raw === true;
+  }
+  throw new Error(`${label} must be a boolean.`);
+}
+
+function optional<T>(raw: unknown, parse: (raw: unknown) => T): T | undefined {
+  return raw === undefined ? undefined : parse(raw);
+}
+
+async function optionalAsync<T>(
+  raw: unknown,
+  parse: (raw: unknown) => Promise<T>,
+): Promise<T | undefined> {
+  return raw === undefined ? undefined : await parse(raw);
+}
+
+async function parseOperation(
+  parameters: unknown,
+  runner: CommandRunner,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<ParsedOperation> {
+  const operation = parseOperationFrom(parameters);
+  if (!operation) {
+    throw new Error("Unknown Herdr worktree operation.");
+  }
+
+  switch (operation) {
+    case "list":
+      parseRequestFields(parameters, operation, OPERATION_FIELDS[operation]);
+      return { operation };
+    case "create": {
+      const fields = parseRequestFields(parameters, operation, OPERATION_FIELDS[operation]);
+      return {
+        operation,
+        branch: await parseBranchName(runner, fields.branch, "branch", cwd, signal),
+        base: await optionalAsync(fields.base, (raw) =>
+          parseBase(runner, raw, "base", cwd, signal),
+        ),
+        path: optional(fields.path, (raw) => parseAbsolutePath(raw, "path")),
+        label: optional(fields.label, (raw) => parseLabel(raw, "label")),
+        focus: parseFlag(fields.focus, "focus"),
+      };
+    }
+    case "open": {
+      const fields = parseRequestFields(parameters, operation, OPERATION_FIELDS[operation]);
+      const path = optional(fields.path, (raw) => parseAbsolutePath(raw, "path"));
+      const branch = await optionalAsync(fields.branch, (raw) =>
+        parseBranchName(runner, raw, "branch", cwd, signal),
+      );
+      if ((path === undefined) === (branch === undefined)) {
+        throw new Error("Operation open requires exactly one of path or branch.");
+      }
+      return {
+        operation,
+        path,
+        branch,
+        label: optional(fields.label, (raw) => parseLabel(raw, "label")),
+        focus: parseFlag(fields.focus, "focus"),
+      };
+    }
+    case "remove": {
+      const fields = parseRequestFields(parameters, operation, OPERATION_FIELDS[operation]);
+      return {
+        operation,
+        workspaceId: parseWorkspaceId(fields.workspace_id, "workspace_id"),
+        force: parseFlag(fields.force, "force"),
+      };
+    }
+  }
+}
+
+function approvalFor(args: unknown): ToolApprovalDecision {
+  const operation = parseOperationFrom(args);
+  if (operation === "list") {
+    return "read";
+  }
+  if (operation === "remove") {
+    return {
+      tier: "exec",
+      policy: "prompt",
+      reason: "Removing a worktree deletes its checkout and closes its Herdr workspace.",
+    };
+  }
+  // A caller-chosen path writes wherever it names, so the user decides. Otherwise Herdr picks.
+  if (operation === "create" && args && typeof args === "object") {
+    if (Reflect.get(args, "path") !== undefined) {
+      return {
+        tier: "exec",
+        policy: "prompt",
+        reason: "Creating a worktree at an explicit path writes to a directory the caller chose.",
+      };
+    }
+  }
+  if (operation) {
+    return "exec";
+  }
+  return { tier: "exec", policy: "deny", reason: "Unknown Herdr worktree operation." };
+}
+
+function concurrencyFor(args: Partial<HerdrWorktreeParameters>): "shared" | "exclusive" {
+  return parseOperationFrom(args) === "list" ? "shared" : "exclusive";
+}
+
+const APPROVAL_VALUE_MAX_LENGTH = 200;
+
+/**
+ * The approval prompt is built before the request is parsed, so it shows raw text. A value must
+ * stay on one line, or it could forge the lines around it.
+ */
+function approvalValue(raw: unknown): string {
+  const text = typeof raw === "string" ? raw : (JSON.stringify(raw) ?? String(raw));
+  const singleLine = text.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, " ").trim();
+  return singleLine.length > APPROVAL_VALUE_MAX_LENGTH
+    ? `${singleLine.slice(0, APPROVAL_VALUE_MAX_LENGTH)}...`
+    : singleLine;
+}
+
+function approvalDetails(args: unknown): readonly string[] | undefined {
+  const operation = parseOperationFrom(args);
+  if (!operation || !args || typeof args !== "object") {
+    return undefined;
+  }
+  const lines = [`Operation: ${operation}`];
+  for (const field of ["branch", "base", "path", "label", "workspace_id"]) {
+    const raw = Reflect.get(args, field);
+    if (raw !== undefined) {
+      lines.push(`${field}: ${approvalValue(raw)}`);
+    }
+  }
+  if (Reflect.get(args, "force") === true) {
+    lines.push("force: discards uncommitted changes in the checkout");
+  }
+  return lines;
+}
+
+/**
+ * Last line of defence before spawning `herdr`, kept although the types already make most of it
+ * impossible. Herdr does not accept `--flag=value`, so every value travels as its own argument.
+ */
+function buildHerdrArguments(command: HerdrCommand): readonly string[] {
+  if (!Object.hasOwn(ALLOWED_OPTIONS, command.action)) {
+    throw new Error(
+      `Refusing to run an unknown Herdr worktree action: ${JSON.stringify(command.action)}.`,
+    );
+  }
+  const allowedOptions = ALLOWED_OPTIONS[command.action];
+  const allowedSwitches = ALLOWED_SWITCHES[command.action];
+  const args: string[] = [HERDR_SUBCOMMAND, command.action];
+  const used = new Set<string>();
+
+  for (const option of command.options) {
+    if (!allowedOptions.includes(option.name)) {
+      throw new Error(`Refusing to pass ${option.name} to ${command.action}.`);
+    }
+    if (used.has(option.name)) {
+      throw new Error(`Refusing to pass ${option.name} twice.`);
+    }
+    const value: ParsedArgumentValue = option.value;
+    if (!hasParsedArgumentSyntax(value)) {
+      throw new Error(`Refusing to pass ${option.name} without a safe value.`);
+    }
+    used.add(option.name);
+    args.push(option.name, value);
+  }
+
+  for (const flag of command.switches) {
+    if (!allowedSwitches.includes(flag)) {
+      throw new Error(`Refusing to pass ${flag} to ${command.action}.`);
+    }
+    if (used.has(flag)) {
+      throw new Error(`Refusing to pass ${flag} twice.`);
+    }
+    used.add(flag);
+    args.push(flag);
+  }
+  if (used.has("--focus") && used.has("--no-focus")) {
+    throw new Error("Refusing to pass both --focus and --no-focus.");
+  }
+  return args;
+}
+
+async function runHerdr(
+  runner: CommandRunner,
+  capabilities: HerdrCapabilityResolver,
+  capability: HerdrCapability,
+  command: HerdrCommand,
+  signal: AbortSignal | undefined,
+): Promise<{ result: CommandResult; payload: Record<string, unknown> }> {
+  const args = buildHerdrArguments(command);
+  let result: CommandResult;
+  try {
+    result = await runner("herdr", args, { cwd: capability.repository.root, signal });
+  } catch (error) {
+    if (error instanceof CommandInvocationError) {
+      capabilities.forget(capability.repository.root);
+      throw new HerdrUnavailableError(
+        "The Herdr session was detected, but the `herdr` executable could not be started.",
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+
+  // Exit 2 is a CLI syntax error: the argument vocabulary above and the installed CLI
+  // disagree, which is a bug here rather than a rejected request.
+  if (result.exitCode === 2) {
+    capabilities.forget(capability.repository.root);
+    throw new HerdrUnavailableError(
+      `The installed Herdr CLI rejected the argument list: ${[result.stderr, result.stdout]
+        .map((text) => text.trim())
+        .filter(Boolean)
+        .join("\n")}`,
+    );
+  }
+  return { result, payload: parseEnvelope(result) };
+}
+
+function describeWorktree(worktree: WorktreeInfo): string {
+  const branch = worktree.branch ?? "detached HEAD";
+  const workspace = worktree.openWorkspaceId ? ` in workspace ${worktree.openWorkspaceId}` : "";
+  const flags = [
+    worktree.isLinkedWorktree ? "linked" : "main checkout",
+    worktree.isPrunable ? "prunable" : undefined,
+    worktree.isBare ? "bare" : undefined,
+  ].filter(Boolean);
+  return `${worktree.path} [${branch}]${workspace} (${flags.join(", ")})`;
+}
+
+function textResult<TDetails>(text: string, details: TDetails): ToolResult<TDetails> {
+  return { content: [{ type: "text", text }], details };
+}
+
+async function assertGitWorktreeRegistered(
+  runner: CommandRunner,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  path: string,
+  branch: string | null,
+  label: string,
+): Promise<GitWorktreeEntry> {
+  const entries = await readGitWorktrees(runner, cwd, signal);
+  const entry = findGitWorktree(entries, path);
+  if (!entry) {
+    throw new Error(`Git does not list ${JSON.stringify(path)} as a worktree of this repository.`);
+  }
+  if (branch !== null && entry.branch !== branch) {
+    throw new Error(
+      `${label} reports branch ${JSON.stringify(branch)}, but Git has ${JSON.stringify(entry.branch)} checked out there.`,
+    );
+  }
+  return entry;
+}
+
+function isInside(directory: string, path: string): boolean {
+  const offset = relative(directory, path);
+  return offset === "" || (!offset.startsWith("..") && !isAbsolute(offset));
+}
+
+/**
+ * Git refuses to overwrite files too, but only after Herdr made the workspace for it. The tool may
+ * run from a linked worktree, where the main checkout is not the root Git reported, so every
+ * registered checkout is checked and not only that root.
+ */
+async function assertCheckoutPathAvailable(
+  path: ParsedAbsolutePath,
+  repository: GitRepository,
+  existing: readonly GitWorktreeEntry[],
+): Promise<void> {
+  const directories: readonly (readonly [string, string])[] = [
+    [repository.root, "repository"],
+    [repository.gitDir, "Git directory"],
+    ...existing.map((entry) => [entry.path, "worktree"] as const),
+  ];
+  for (const [directory, label] of directories) {
+    if (isInside(directory, path)) {
+      throw new Error(
+        `path ${JSON.stringify(path)} is inside the ${label} at ${JSON.stringify(directory)}. Create the worktree outside it.`,
+      );
+    }
+  }
+
+  let target: Stats;
+  try {
+    target = await stat(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw new Error(`Unable to inspect path ${JSON.stringify(path)}.`, { cause: error });
+  }
+  if (!target.isDirectory()) {
+    throw new Error(`path ${JSON.stringify(path)} already exists and is not a directory.`);
+  }
+  if ((await readdir(path)).length > 0) {
+    throw new Error(`path ${JSON.stringify(path)} already exists and is not empty.`);
+  }
+}
+
+function focusSwitch(focus: boolean): HerdrSwitch {
+  return focus ? "--focus" : "--no-focus";
+}
+
+function listCommand(root: ParsedAbsolutePath): HerdrCommand {
+  return { action: "list", options: [{ name: "--cwd", value: root }], switches: [] };
+}
+
+export function registerHerdrWorktreeTools(
+  pi: HerdrExtensionApi,
+  dependencies: HerdrExtensionDependencies = {},
+): void {
+  const runner = dependencies.runner ?? runCommand;
+  const capabilities = dependencies.capabilities ?? new HerdrCapabilityResolver(runner);
+
+  registerHerdrGuidance(pi, capabilities);
+
+  pi.registerTool<typeof HerdrWorktreeParameters, HerdrWorktreeToolDetails>({
+    name: "herdr_worktree",
+    label: "Herdr worktree",
+    description:
+      "List, create, open, and remove Herdr Git worktree workspaces for the current repository, with checked arguments and verified results.",
+    parameters: HerdrWorktreeParameters,
+    approval: approvalFor,
+    formatApprovalDetails: approvalDetails,
+    loadMode: "discoverable",
+    concurrency: concurrencyFor,
+    executionMode: "sequential",
+    async execute(_toolCallId, parameters, signal, _onUpdate, context) {
+      const capability = await capabilities.ensure(context.cwd, signal);
+      const root = capability.repository.root;
+      const operation = await parseOperation(parameters, runner, root, signal);
+
+      switch (operation.operation) {
+        case "list": {
+          const { result, payload } = await runHerdr(
+            runner,
+            capabilities,
+            capability,
+            listCommand(root),
+            signal,
+          );
+          const list = parseWorktreeList(payload);
+          const lines = list.worktrees.map((worktree) => `- ${describeWorktree(worktree)}`);
+          const body = lines.length > 0 ? lines.join("\n") : "No worktrees are registered.";
+          return textResult(`${list.source.repoName} (${list.source.repoRoot})\n${body}`, {
+            operation: "list",
+            capability: capabilityDetails(capability),
+            command: commandDetails(result),
+            result: list,
+          });
+        }
+        case "create":
+          return withRepositoryLock(root, signal, async () => {
+            const existing = await readGitWorktrees(runner, root, signal);
+            if (existing.some((entry) => entry.branch === operation.branch)) {
+              throw new Error(
+                `Branch ${JSON.stringify(operation.branch)} is already checked out in a worktree of this repository. Open it instead of creating it.`,
+              );
+            }
+            if (operation.path && findGitWorktree(existing, operation.path)) {
+              throw new Error(
+                `${JSON.stringify(operation.path)} is already a worktree of this repository.`,
+              );
+            }
+            if (operation.path) {
+              await assertCheckoutPathAvailable(operation.path, capability.repository, existing);
+            }
+
+            const options: HerdrOption[] = [
+              { name: "--cwd", value: root },
+              { name: "--branch", value: operation.branch },
+            ];
+            if (operation.base) {
+              options.push({ name: "--base", value: operation.base.revision });
+            }
+            if (operation.path) {
+              options.push({ name: "--path", value: operation.path });
+            }
+            if (operation.label) {
+              options.push({ name: "--label", value: operation.label });
+            }
+
+            const { result, payload } = await runHerdr(
+              runner,
+              capabilities,
+              capability,
+              { action: "create", options, switches: [focusSwitch(operation.focus)] },
+              signal,
+            );
+            const created = parseWorktreeOpened(payload);
+            if (created.type !== "worktree_created") {
+              throw new Error(
+                `Herdr answered a create request with ${JSON.stringify(created.type)}.`,
+              );
+            }
+            if (created.worktree.branch !== operation.branch) {
+              throw new Error(
+                `Herdr created the worktree on branch ${JSON.stringify(created.worktree.branch)} instead of ${JSON.stringify(operation.branch)}.`,
+              );
+            }
+            if (!created.worktree.isLinkedWorktree) {
+              throw new Error("Herdr reported the main checkout instead of a new linked worktree.");
+            }
+            if (operation.path && created.worktree.path !== operation.path) {
+              throw new Error(
+                `Herdr created the worktree at ${JSON.stringify(created.worktree.path)} instead of ${JSON.stringify(operation.path)}.`,
+              );
+            }
+            const entry = await assertGitWorktreeRegistered(
+              runner,
+              root,
+              signal,
+              created.worktree.path,
+              created.worktree.branch,
+              "Herdr",
+            );
+            // A ref can move between the parse and the create, so the commit is checked again.
+            if (operation.base && entry.head !== operation.base.commit) {
+              throw new Error(
+                `base ${JSON.stringify(operation.base.revision)} was at ${operation.base.commit}, but the new worktree is at ${JSON.stringify(entry.head)}.`,
+              );
+            }
+            return textResult(
+              `Created ${describeWorktree(created.worktree)}\nWorkspace ${created.workspaceId}, tab ${created.tabId}, pane ${created.rootPaneId}`,
+              {
+                operation: "create",
+                capability: capabilityDetails(capability),
+                command: commandDetails(result),
+                result: created,
+              },
+            );
+          });
+        case "open":
+          return withRepositoryLock(root, signal, async () => {
+            const options: HerdrOption[] = [{ name: "--cwd", value: root }];
+            if (operation.path) {
+              options.push({ name: "--path", value: operation.path });
+            }
+            if (operation.branch) {
+              options.push({ name: "--branch", value: operation.branch });
+            }
+            if (operation.label) {
+              options.push({ name: "--label", value: operation.label });
+            }
+
+            const { result, payload } = await runHerdr(
+              runner,
+              capabilities,
+              capability,
+              { action: "open", options, switches: [focusSwitch(operation.focus)] },
+              signal,
+            );
+            const opened = parseWorktreeOpened(payload);
+            if (opened.type !== "worktree_opened") {
+              throw new Error(
+                `Herdr answered an open request with ${JSON.stringify(opened.type)}.`,
+              );
+            }
+            if (operation.branch && opened.worktree.branch !== operation.branch) {
+              throw new Error(
+                `Herdr opened branch ${JSON.stringify(opened.worktree.branch)} instead of ${JSON.stringify(operation.branch)}.`,
+              );
+            }
+            if (operation.path && opened.worktree.path !== operation.path) {
+              throw new Error(
+                `Herdr opened ${JSON.stringify(opened.worktree.path)} instead of ${JSON.stringify(operation.path)}.`,
+              );
+            }
+            await assertGitWorktreeRegistered(
+              runner,
+              root,
+              signal,
+              opened.worktree.path,
+              opened.worktree.branch,
+              "Herdr",
+            );
+            const prefix = opened.alreadyOpen ? "Already open:" : "Opened";
+            return textResult(
+              `${prefix} ${describeWorktree(opened.worktree)}\nWorkspace ${opened.workspaceId}, tab ${opened.tabId}, pane ${opened.rootPaneId}`,
+              {
+                operation: "open",
+                capability: capabilityDetails(capability),
+                command: commandDetails(result),
+                result: opened,
+              },
+            );
+          });
+        case "remove":
+          return withRepositoryLock(root, signal, async () => {
+            const { payload: listPayload } = await runHerdr(
+              runner,
+              capabilities,
+              capability,
+              listCommand(root),
+              signal,
+            );
+            const list = parseWorktreeList(listPayload);
+            const target = list.worktrees.find(
+              (worktree) => worktree.openWorkspaceId === operation.workspaceId,
+            );
+            if (!target) {
+              throw new Error(
+                `Workspace ${JSON.stringify(operation.workspaceId)} does not hold a worktree of ${JSON.stringify(list.source.repoRoot)}.`,
+              );
+            }
+            if (!target.isLinkedWorktree) {
+              throw new Error(
+                `Workspace ${JSON.stringify(operation.workspaceId)} holds the main checkout at ${JSON.stringify(target.path)}, which cannot be removed.`,
+              );
+            }
+            if (target.path === capability.repository.root) {
+              throw new Error("remove cannot remove the repository the tool is running in.");
+            }
+
+            const confirmed = await context.ui?.confirm(
+              `Remove Herdr worktree ${target.path}?`,
+              operation.force
+                ? "This deletes the checkout even if it holds uncommitted changes, and closes its Herdr workspace."
+                : "This deletes the checkout and closes its Herdr workspace.",
+            );
+            if (!confirmed) {
+              throw new Error("Removing a worktree requires explicit user confirmation.");
+            }
+
+            const { result, payload } = await runHerdr(
+              runner,
+              capabilities,
+              capability,
+              {
+                action: "remove",
+                options: [{ name: "--workspace", value: operation.workspaceId }],
+                switches: operation.force ? ["--force"] : [],
+              },
+              signal,
+            );
+            const removed = parseWorktreeRemoved(payload);
+            if (removed.workspaceId !== operation.workspaceId) {
+              throw new Error(
+                `Herdr removed workspace ${JSON.stringify(removed.workspaceId)} instead of ${JSON.stringify(operation.workspaceId)}.`,
+              );
+            }
+            if (removed.path !== target.path) {
+              throw new Error(
+                `Herdr removed ${JSON.stringify(removed.path)} instead of ${JSON.stringify(target.path)}.`,
+              );
+            }
+            const remaining = await readGitWorktrees(runner, root, signal);
+            if (findGitWorktree(remaining, removed.path)) {
+              throw new Error(
+                `Herdr reported ${JSON.stringify(removed.path)} removed, but Git still lists it as a worktree.`,
+              );
+            }
+            return textResult(
+              `Removed ${removed.path} and closed workspace ${removed.workspaceId}${removed.forced ? " (forced)" : ""}.`,
+              {
+                operation: "remove",
+                capability: capabilityDetails(capability),
+                command: commandDetails(result),
+                result: removed,
+              },
+            );
+          });
+      }
+    },
+  });
+}