@mcuste/pi-herdr-worktree 0.1.0

package/dist/worktree.js

@@ -0,0 +1,47 @@
+import { normalize } from "node:path";
+import { runChecked } from "./process.js";
+function comparablePath(value) {
+    return normalize(value).replace(/\/+$/u, "");
+}
+/**
+ * Reads the worktrees Git itself knows about. Herdr reports what it did; this is the
+ * independent check that the repository really changed the same way.
+ *
+ * `-z` ends every record with a NUL, so a path that contains a newline cannot pretend to be
+ * another record. It needs Git 2.36 or newer.
+ */
+export async function readGitWorktrees(runner, cwd, signal) {
+    const result = await runChecked(runner, "git", ["worktree", "list", "--porcelain", "-z"], { cwd, signal }, "Unable to list the Git worktrees");
+    const entries = [];
+    let path;
+    let head = null;
+    let branch = null;
+    const flush = () => {
+        if (path) {
+            entries.push({ path: comparablePath(path), head, branch });
+        }
+        path = undefined;
+        head = null;
+        branch = null;
+    };
+    // An unrecognised record, such as `bare` or `locked`, is ignored rather than read as a path.
+    for (const record of result.stdout.split("\0")) {
+        if (record.startsWith("worktree ")) {
+            flush();
+            path = record.slice("worktree ".length);
+        }
+        else if (record.startsWith("HEAD ")) {
+            head = record.slice("HEAD ".length);
+        }
+        else if (record.startsWith("branch refs/heads/")) {
+            branch = record.slice("branch refs/heads/".length);
+        }
+    }
+    flush();
+    return entries;
+}
+export function findGitWorktree(entries, path) {
+    const wanted = comparablePath(path);
+    return entries.find((entry) => entry.path === wanted);
+}
+//# sourceMappingURL=worktree.js.map

package/dist/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAsB,UAAU,EAAE,MAAM,cAAc,CAAC;AAQ9D,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAqB,EACrB,GAAW,EACX,MAA+B;IAE/B,MAAM,MAAM,GAAG,MAAM,UAAU,CAC7B,MAAM,EACN,KAAK,EACL,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,CAAC,EACzC,EAAE,GAAG,EAAE,MAAM,EAAE,EACf,kCAAkC,CACnC,CAAC;IAEF,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,IAAI,IAAwB,CAAC;IAC7B,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,MAAM,GAAkB,IAAI,CAAC;IAEjC,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,GAAG,SAAS,CAAC;QACjB,IAAI,GAAG,IAAI,CAAC;QACZ,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC,CAAC;IAEF,6FAA6F;IAC7F,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,IAAI,MAAM,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACnC,KAAK,EAAE,CAAC;YACR,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;aAAM,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,MAAM,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;YACnD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IACD,KAAK,EAAE,CAAC;IACR,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,OAAoC,EACpC,IAAY;IAEZ,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;AACxD,CAAC"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@mcuste/pi-herdr-worktree",
+  "version": "0.1.0",
+  "description": "Herdr Git worktree workspaces as one safe, model-callable tool for the Pi and Oh My Pi coding agents",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "oh-my-pi",
+    "omp",
+    "extension",
+    "herdr",
+    "worktree",
+    "git-worktree",
+    "workspace",
+    "terminal-multiplexer"
+  ],
+  "license": "MIT",
+  "author": "mcuste",
+  "homepage": "https://github.com/mcuste/pi-herdr-worktree#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcuste/pi-herdr-worktree.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mcuste/pi-herdr-worktree/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.9",
+    "@types/node": "^26.2.0",
+    "knip": "6.32.2",
+    "publint": "0.3.23",
+    "typebox": "^1.3.15",
+    "typescript": "^7.0.2"
+  },
+  "knip": {
+    "entry": [
+      "test/**/*.test.mjs",
+      "test/**/*.e2e.mjs",
+      "scripts/*.mjs"
+    ],
+    "project": [
+      "src/**/*.ts",
+      "test/**/*.mjs",
+      "scripts/*.mjs"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "omp": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "pnpm quality && pnpm package:check && pnpm test && pnpm test:integration && pnpm deadcode && pnpm security",
+    "deadcode": "knip",
+    "fix": "biome check --write .",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "package:check": "pnpm build && publint",
+    "quality": "biome check .",
+    "release": "node scripts/release.mjs",
+    "security": "pnpm audit --audit-level high",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "test:integration": "pnpm build && node --test test/*.e2e.mjs"
+  }
+}

package/src/argument.ts

@@ -0,0 +1,183 @@
+import { isAbsolute, normalize } from "node:path";
+import {
+  CommandCancelledError,
+  type CommandResult,
+  type CommandRunner,
+  runChecked,
+} from "./process.js";
+
+export const MAX_BRANCH_NAME_LENGTH = 255;
+export const MAX_PATH_LENGTH = 4096;
+export const MAX_LABEL_LENGTH = 120;
+
+/** The bounds come from the pattern, so the schema advertises exactly what this accepts. */
+const WORKSPACE_ID = /^w[0-9A-Za-z]{1,16}$/u;
+export const MIN_WORKSPACE_ID_LENGTH = 2;
+export const MAX_WORKSPACE_ID_LENGTH = 17;
+
+declare const branchNameBrand: unique symbol;
+declare const revisionBrand: unique symbol;
+declare const commitIdBrand: unique symbol;
+declare const absolutePathBrand: unique symbol;
+declare const labelBrand: unique symbol;
+declare const workspaceIdBrand: unique symbol;
+
+/** The branch name `git check-ref-format --branch` printed, so shorthand is already expanded. */
+export type ParsedBranchName = string & { readonly [branchNameBrand]: true };
+
+/** A revision that `git rev-parse --verify` resolved to a commit. */
+export type ParsedRevision = string & { readonly [revisionBrand]: true };
+
+/** A full object id that `git rev-parse` printed. */
+type ParsedCommitId = string & { readonly [commitIdBrand]: true };
+
+export type ParsedAbsolutePath = string & { readonly [absolutePathBrand]: true };
+
+export type ParsedLabel = string & { readonly [labelBrand]: true };
+
+export type ParsedWorkspaceId = string & { readonly [workspaceIdBrand]: true };
+
+/**
+ * Every value that may become a command argument. A plain string is not a member, so unparsed
+ * text cannot reach a spawned command.
+ */
+export type ParsedArgumentValue =
+  | ParsedAbsolutePath
+  | ParsedBranchName
+  | ParsedLabel
+  | ParsedRevision
+  | ParsedWorkspaceId;
+
+/** A revision, together with the commit it pointed at when it was parsed. */
+export interface ParsedBase {
+  readonly revision: ParsedRevision;
+  readonly commit: ParsedCommitId;
+}
+
+/** Bidirectional marks make text display as other text, and a newline forges a line of output. */
+const UNSAFE_CHARACTERS = /[\p{Cc}\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/u;
+
+const COMMIT_ID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u;
+
+/**
+ * Rejects values that could turn into a command-line option, split an argument, or forge a line
+ * of output before Git or Herdr ever sees them.
+ */
+function hasSafeArgumentSyntax(value: unknown, maxLength: number): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= maxLength &&
+    value === value.trim() &&
+    !value.startsWith("-") &&
+    !UNSAFE_CHARACTERS.test(value)
+  );
+}
+
+/** The runtime re-check of what the parsed types already promise, for the gate before a spawn. */
+export function hasParsedArgumentSyntax(value: unknown): value is string {
+  return hasSafeArgumentSyntax(value, MAX_PATH_LENGTH);
+}
+
+export async function parseBranchName(
+  runner: CommandRunner,
+  value: unknown,
+  label: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<ParsedBranchName> {
+  if (!hasSafeArgumentSyntax(value, MAX_BRANCH_NAME_LENGTH)) {
+    throw new Error(`${label} is not a safe branch name: ${JSON.stringify(value)}.`);
+  }
+
+  let result: CommandResult;
+  try {
+    result = await runChecked(
+      runner,
+      "git",
+      ["check-ref-format", "--branch", value],
+      { cwd, signal },
+      `${label} is not a valid Git branch name`,
+    );
+  } catch (error) {
+    if (error instanceof CommandCancelledError) {
+      throw error;
+    }
+    throw new Error(`${label} is not a valid Git branch name: ${JSON.stringify(value)}.`, {
+      cause: error,
+    });
+  }
+
+  // `--branch` expands shorthand such as `@{-1}`, so only the printed name names the real branch.
+  const expanded = result.stdout.trim();
+  if (!hasSafeArgumentSyntax(expanded, MAX_BRANCH_NAME_LENGTH)) {
+    throw new Error(`${label} did not expand to a safe branch name: ${JSON.stringify(value)}.`);
+  }
+  return expanded as ParsedBranchName;
+}
+
+/** A base for a new worktree only has to resolve to a commit, so tags and SHAs are allowed. */
+export async function parseBase(
+  runner: CommandRunner,
+  value: unknown,
+  label: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+): Promise<ParsedBase> {
+  if (!hasSafeArgumentSyntax(value, MAX_BRANCH_NAME_LENGTH)) {
+    throw new Error(`${label} is not a safe Git revision: ${JSON.stringify(value)}.`);
+  }
+
+  let result: CommandResult;
+  try {
+    result = await runChecked(
+      runner,
+      "git",
+      ["rev-parse", "--verify", "--quiet", `${value}^{commit}`],
+      { cwd, signal },
+      `${label} does not resolve to a commit`,
+    );
+  } catch (error) {
+    if (error instanceof CommandCancelledError) {
+      throw error;
+    }
+    throw new Error(`${label} does not resolve to a commit: ${JSON.stringify(value)}.`, {
+      cause: error,
+    });
+  }
+
+  const commit = result.stdout.trim();
+  if (!COMMIT_ID.test(commit)) {
+    throw new Error(`${label} did not resolve to a commit id: ${JSON.stringify(value)}.`);
+  }
+  return { revision: value as ParsedRevision, commit: commit as ParsedCommitId };
+}
+
+export function parseAbsolutePath(value: unknown, label: string): ParsedAbsolutePath {
+  if (!hasSafeArgumentSyntax(value, MAX_PATH_LENGTH)) {
+    throw new Error(`${label} is not a safe path: ${JSON.stringify(value)}.`);
+  }
+  if (!isAbsolute(value)) {
+    throw new Error(`${label} must be an absolute path: ${JSON.stringify(value)}.`);
+  }
+  const normalized = normalize(value).replace(/\/+$/u, "");
+  if (!normalized || !isAbsolute(normalized)) {
+    throw new Error(`${label} does not normalise to an absolute path: ${JSON.stringify(value)}.`);
+  }
+  return normalized as ParsedAbsolutePath;
+}
+
+/** A label is display text, so it only has to stay a single argument on one line. */
+export function parseLabel(value: unknown, label: string): ParsedLabel {
+  if (!hasSafeArgumentSyntax(value, MAX_LABEL_LENGTH)) {
+    throw new Error(`${label} must be single-line text without leading options.`);
+  }
+  return value as ParsedLabel;
+}
+
+export function parseWorkspaceId(value: unknown, label: string): ParsedWorkspaceId {
+  if (!hasSafeArgumentSyntax(value, MAX_WORKSPACE_ID_LENGTH) || !WORKSPACE_ID.test(value)) {
+    throw new Error(`${label} is not a Herdr workspace id: ${JSON.stringify(value)}.`);
+  }
+  return value as ParsedWorkspaceId;
+}

package/src/capability.ts

@@ -0,0 +1,223 @@
+import { resolve } from "node:path";
+import { type ParsedAbsolutePath, parseAbsolutePath } from "./argument.js";
+import {
+  CommandCancelledError,
+  type CommandResult,
+  type CommandRunner,
+  runChecked,
+  runCommand,
+} from "./process.js";
+
+/** Herdr injects this into every managed pane. Without it there is no session to talk to. */
+const SESSION_MARKER = "HERDR_ENV";
+
+const MINIMUM_HERDR_VERSION = [0, 8, 2] as const;
+const CAPABILITY_MAX_AGE_MS = 10 * 60 * 1000;
+const UNAVAILABLE_RETRY_MS = 5 * 60 * 1000;
+
+export interface GitRepository {
+  readonly root: ParsedAbsolutePath;
+  readonly gitDir: ParsedAbsolutePath;
+}
+
+export interface HerdrCapability {
+  readonly repository: GitRepository;
+  readonly herdrVersion: string;
+  readonly cache: "memory" | "detected";
+}
+
+interface RememberedCapability {
+  readonly capability: Omit<HerdrCapability, "cache">;
+  readonly expiresAt: number;
+}
+
+export class HerdrUnavailableError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "HerdrUnavailableError";
+  }
+}
+
+function isAtLeast(installed: readonly number[], minimum: readonly number[]): boolean {
+  for (const [index, required] of minimum.entries()) {
+    const part = installed[index] ?? 0;
+    if (part !== required) {
+      return part > required;
+    }
+  }
+  return true;
+}
+
+function parseHerdrVersion(result: CommandResult): string {
+  const raw = result.stdout.trim() || result.stderr.trim();
+  const match = /^(?:herdr )?(\d+)\.(\d+)\.(\d+)/u.exec(raw);
+  if (!match) {
+    throw new HerdrUnavailableError(
+      `Unable to read the Herdr version from ${JSON.stringify(raw)}.`,
+    );
+  }
+  const parts = match.slice(1, 4).map(Number);
+  if (!isAtLeast(parts, MINIMUM_HERDR_VERSION)) {
+    throw new HerdrUnavailableError(
+      `Herdr ${MINIMUM_HERDR_VERSION.join(".")} or newer is required, but ${parts.join(".")} is installed.`,
+    );
+  }
+  return parts.join(".");
+}
+
+/**
+ * The capability is a property of the running session, not of the repository, so it is only
+ * held in memory. Nothing is written to the repository.
+ */
+export class HerdrCapabilityResolver {
+  readonly #runner: CommandRunner;
+  readonly #environment: Readonly<Record<string, string | undefined>>;
+  readonly #now: () => number;
+  readonly #memory = new Map<string, RememberedCapability>();
+  readonly #unavailable = new Map<string, number>();
+
+  constructor(
+    runner: CommandRunner = runCommand,
+    environment: Readonly<Record<string, string | undefined>> = process.env,
+    now: () => number = Date.now,
+  ) {
+    this.#runner = runner;
+    this.#environment = environment;
+    this.#now = now;
+  }
+
+  async ensure(cwd: string, signal?: AbortSignal): Promise<HerdrCapability> {
+    const lookupKey = resolve(cwd);
+    const remembered = this.#memory.get(lookupKey);
+    if (remembered && remembered.expiresAt > this.#now()) {
+      return { ...remembered.capability, cache: "memory" };
+    }
+    this.#memory.delete(lookupKey);
+
+    this.#assertManagedSession();
+    const repository = await this.#findRepository(cwd, signal);
+    const herdrVersion = await this.#detectHerdr(repository, signal);
+    const capability = { repository, herdrVersion };
+    this.#remember(lookupKey, capability);
+    return { ...capability, cache: "detected" };
+  }
+
+  /**
+   * Never throws, unlike `ensure`. A failed detection is cached for a short time, so a caller that
+   * runs on every agent start does not spawn `git` and `herdr` every turn.
+   */
+  async tryEnsure(cwd: string, signal?: AbortSignal): Promise<HerdrCapability | undefined> {
+    // The marker comes from the process environment, so the answer cannot change while it runs.
+    if (!this.#isManagedSession()) {
+      return undefined;
+    }
+
+    const lookupKey = resolve(cwd);
+    const retryAt = this.#unavailable.get(lookupKey);
+    if (retryAt !== undefined && retryAt > this.#now()) {
+      return undefined;
+    }
+    this.#unavailable.delete(lookupKey);
+
+    try {
+      return await this.ensure(cwd, signal);
+    } catch (error) {
+      if (error instanceof HerdrUnavailableError) {
+        this.#unavailable.set(lookupKey, this.#now() + UNAVAILABLE_RETRY_MS);
+      }
+      return undefined;
+    }
+  }
+
+  forget(cwd: string): void {
+    const lookupKey = resolve(cwd);
+    this.#unavailable.delete(lookupKey);
+    const remembered = this.#memory.get(lookupKey);
+    const repositoryRoot = resolve(remembered?.capability.repository.root ?? cwd);
+    for (const [key, entry] of this.#memory) {
+      if (key === lookupKey || resolve(entry.capability.repository.root) === repositoryRoot) {
+        this.#memory.delete(key);
+      }
+    }
+    this.#unavailable.delete(repositoryRoot);
+  }
+
+  #remember(lookupKey: string, capability: Omit<HerdrCapability, "cache">): void {
+    const remembered = { capability, expiresAt: this.#now() + CAPABILITY_MAX_AGE_MS };
+    this.#memory.set(lookupKey, remembered);
+    this.#memory.set(resolve(capability.repository.root), remembered);
+  }
+
+  #isManagedSession(): boolean {
+    return this.#environment[SESSION_MARKER] === "1";
+  }
+
+  #assertManagedSession(): void {
+    if (!this.#isManagedSession()) {
+      throw new HerdrUnavailableError(
+        `Herdr worktree tools only run inside a Herdr-managed pane, where ${SESSION_MARKER} is 1. Start the agent from a Herdr session and retry.`,
+      );
+    }
+  }
+
+  async #findRepository(cwd: string, signal: AbortSignal | undefined): Promise<GitRepository> {
+    let result: CommandResult;
+    try {
+      result = await runChecked(
+        this.#runner,
+        "git",
+        ["rev-parse", "--show-toplevel", "--absolute-git-dir"],
+        { cwd, signal },
+        "Unable to locate the Git repository",
+      );
+    } catch (error) {
+      if (error instanceof CommandCancelledError) {
+        throw error;
+      }
+      throw new HerdrUnavailableError(
+        "Herdr worktree actions require a Git work tree. Run the tool from inside a Git repository.",
+        { cause: error },
+      );
+    }
+
+    const lines = result.stdout.replace(/\r?\n$/u, "").split(/\r?\n/u);
+    if (lines.length !== 2) {
+      throw new HerdrUnavailableError(
+        "Git returned an invalid repository location; Herdr worktree actions cannot run reliably here.",
+      );
+    }
+    try {
+      return {
+        root: parseAbsolutePath(lines[0], "The repository root"),
+        gitDir: parseAbsolutePath(lines[1], "The Git directory"),
+      };
+    } catch (error) {
+      throw new HerdrUnavailableError(
+        "Git returned an invalid repository location; Herdr worktree actions cannot run reliably here.",
+        { cause: error },
+      );
+    }
+  }
+
+  async #detectHerdr(repository: GitRepository, signal: AbortSignal | undefined): Promise<string> {
+    let result: CommandResult;
+    try {
+      result = await runChecked(
+        this.#runner,
+        "herdr",
+        ["--version"],
+        { cwd: repository.root, signal },
+        "Unable to read the Herdr version",
+      );
+    } catch (error) {
+      if (error instanceof CommandCancelledError) {
+        throw error;
+      }
+      throw new HerdrUnavailableError(
+        "The Herdr CLI is unavailable. Install `herdr` and ensure it is on PATH.",
+        { cause: error },
+      );
+    }
+    return parseHerdrVersion(result);
+  }
+}

package/src/guidance.ts

@@ -0,0 +1,51 @@
+import type { HerdrCapabilityResolver } from "./capability.js";
+
+/**
+ * The tool loads on demand, so the model needs this note before it reaches for `herdr` or
+ * `git worktree` in bash.
+ */
+export const HERDR_PROMPT_NOTE =
+  "Use the herdr_worktree tool for Git worktrees, not herdr or git worktree in bash. Create a worktree when work needs its own checkout, for example parallel multi-agent work.";
+
+interface BeforeAgentStartEvent {
+  readonly systemPrompt?: unknown;
+}
+
+interface BeforeAgentStartContext {
+  readonly cwd?: string;
+  readonly signal?: AbortSignal;
+}
+
+interface BeforeAgentStartResult {
+  readonly systemPrompt: string;
+}
+
+export interface HerdrPromptApi {
+  on?(
+    event: "before_agent_start",
+    handler: (
+      event: BeforeAgentStartEvent,
+      context?: BeforeAgentStartContext,
+    ) => Promise<BeforeAgentStartResult | undefined>,
+  ): void;
+}
+
+export function registerHerdrGuidance(
+  pi: HerdrPromptApi,
+  capabilities: HerdrCapabilityResolver,
+): void {
+  pi.on?.("before_agent_start", async (event, context) => {
+    const systemPrompt = event?.systemPrompt;
+    // A host may chain several handlers, so the note must not be appended twice.
+    if (typeof systemPrompt !== "string" || systemPrompt.includes(HERDR_PROMPT_NOTE)) {
+      return undefined;
+    }
+
+    const capability = await capabilities.tryEnsure(context?.cwd ?? process.cwd(), context?.signal);
+    if (!capability) {
+      return undefined;
+    }
+
+    return { systemPrompt: `${systemPrompt}\n\n${HERDR_PROMPT_NOTE}` };
+  });
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+import { type HerdrExtensionApi, registerHerdrWorktreeTools } from "./tools.js";
+
+export default function piHerdrWorktree(pi: HerdrExtensionApi): void {
+  registerHerdrWorktreeTools(pi);
+}