@mcuste/pi-herdr-worktree 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcuste
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# pi-herdr-worktree
+
+[![CI](https://github.com/mcuste/pi-herdr-worktree/actions/workflows/ci.yml/badge.svg)](https://github.com/mcuste/pi-herdr-worktree/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@mcuste/pi-herdr-worktree)](https://www.npmjs.com/package/@mcuste/pi-herdr-worktree)
+
+An extension for the [Pi](https://github.com/earendil-works/pi) and
+[Oh My Pi](https://github.com/can1357/oh-my-pi) terminal coding agents. It gives the model one
+`herdr_worktree` tool that runs a fixed set of [Herdr](https://herdr.dev) Git worktree operations,
+instead of letting it type `herdr` commands into a shell.
+
+If any of those names are new to you:
+
+- **Herdr** is a terminal workspace manager for coding agents. It can back a workspace with a Git
+  worktree, so a branch gets its own checkout, its own tabs, and its own panes.
+- **Pi** and **Oh My Pi** are terminal coding agents. An **extension** is an npm package they load
+  at startup to add tools the model can call.
+
+## Why
+
+An agent with shell access can already run `herdr`, but a shell gives it a free-form command
+string. Herdr's CLI does not accept `--flag=value`, so every value is a separate argument, and a
+value that starts with `-` silently becomes a flag. A wrong `--workspace` deletes the wrong
+checkout, `--force` throws away uncommitted work, and `--focus` moves the user's view away from
+what they were doing.
+
+This extension replaces that with a closed set of operations. Each one accepts only its own typed
+fields, builds a fixed argument array, checks the repository before running, and verifies the
+result against Git afterwards. There is no shell string anywhere.
+
+## Requirements
+
+- Node.js 22 or newer
+- Git 2.36 or newer
+- Herdr 0.8.2 or newer, and an agent running inside a Herdr-managed pane
+
+The extension loads anywhere. Outside a Herdr pane, outside a Git work tree, or without the
+`herdr` CLI, a tool call fails with an explanatory error rather than running an unsupported
+command.
+
+## Install
+
+Pi:
+
+```bash
+pi install npm:@mcuste/pi-herdr-worktree
+```
+
+Oh My Pi:
+
+```bash
+omp plugin install @mcuste/pi-herdr-worktree
+```
+
+Or through the Oh My Pi marketplace:
+
+```text
+/marketplace add mcuste/pi-herdr-worktree
+/marketplace install pi-herdr-worktree@pi-herdr-worktree
+```
+
+From a local checkout:
+
+```bash
+pnpm install
+pi install /absolute/path/to/pi-herdr-worktree
+omp plugin link /absolute/path/to/pi-herdr-worktree
+```
+
+## What the tool does
+
+One tool named `herdr_worktree`, selected by an `operation` field:
+
+| Operation | Runs | Purpose |
+| --- | --- | --- |
+| `list` | `herdr worktree list` | Read every worktree of the current repository |
+| `create` | `herdr worktree create` | Add a worktree on a new branch and open it as a workspace |
+| `open` | `herdr worktree open` | Open an existing worktree as a workspace |
+| `remove` | `herdr worktree remove` | Delete a worktree checkout and close its workspace |
+
+`list` is read-only. The other three change the repository and the session, and Oh My Pi asks for
+execute approval; `remove` always prompts, and so does a `create` that names its own `path`. Full
+per-operation fields and guarantees are in [docs/operations.md](docs/operations.md).
+
+## System prompt note
+
+The tool loads on demand, so its description is not in the base prompt. The model can reach for
+`herdr` or `git worktree` in a shell before it sees the tool, so the extension appends one note to
+the system prompt at the start of each turn:
+
+> 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.
+
+The note is added once per prompt, only where detection succeeds, and only in a host that offers
+the `before_agent_start` event. A host without that event still gets the tool.
+
+Detection reads `HERDR_ENV` first. That variable belongs to the process, so outside Herdr the
+extension starts no child process at all. Inside a Herdr pane, detection also finds the Git
+repository and reads the `herdr` version, then caches the result in memory for ten minutes. A
+failed detection is cached for five minutes, so a directory that is not a Git work tree does not
+run `git` and `herdr` on every turn.
+
+## What is deliberately missing
+
+- **Workspace, tab, pane, and agent control** (`herdr workspace`, `herdr tab`, `herdr pane`,
+  `herdr agent`) is a separate concern. This extension only manages worktree-backed workspaces.
+- **Session and server control** (`herdr session`, `herdr server`, `herdr update`) can stop the
+  user's session and every process in it.
+- **`herdr worktree remove` without a verified target.** The tool always lists the repository's
+  worktrees first and refuses a workspace that does not hold a linked worktree of it.
+
+For anything else, the model works through the normal Herdr workflow with the user in the loop.
+
+## Safety
+
+Every operation checks the repository before and after it runs: a new worktree must be registered
+by Git on the requested branch, an opened worktree must be the one that was asked for, and a
+removed checkout must be gone from `git worktree list`. A failed check is reported as an uncertain
+result rather than retried.
+
+Arguments are never concatenated into a shell command. Herdr does not accept `--flag=value`, so
+every value travels as its own argument and is rejected before spawning if it starts with `-`. Each
+value also carries the option it was parsed for, so a label cannot arrive as a branch. See
+[docs/safety.md](docs/safety.md).
+
+Focus defaults to off. The tool passes `--no-focus` unless the caller explicitly asks to move the
+user's view.
+
+## Documentation
+
+- [Operations reference](docs/operations.md)
+- [Safety model](docs/safety.md)
+- [Development and release](docs/development.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE)

package/dist/argument.d.ts

@@ -0,0 +1,54 @@
+import { type CommandRunner } from "./process.js";
+export declare const MAX_BRANCH_NAME_LENGTH = 255;
+export declare const MAX_PATH_LENGTH = 4096;
+export declare const MAX_LABEL_LENGTH = 120;
+export declare const MIN_WORKSPACE_ID_LENGTH = 2;
+export declare 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;
+}
+/** The runtime re-check of what the parsed types already promise, for the gate before a spawn. */
+export declare function hasParsedArgumentSyntax(value: unknown): value is string;
+export declare function parseBranchName(runner: CommandRunner, value: unknown, label: string, cwd: string, signal: AbortSignal | undefined): Promise<ParsedBranchName>;
+/** A base for a new worktree only has to resolve to a commit, so tags and SHAs are allowed. */
+export declare function parseBase(runner: CommandRunner, value: unknown, label: string, cwd: string, signal: AbortSignal | undefined): Promise<ParsedBase>;
+export declare function parseAbsolutePath(value: unknown, label: string): ParsedAbsolutePath;
+/** A label is display text, so it only has to stay a single argument on one line. */
+export declare function parseLabel(value: unknown, label: string): ParsedLabel;
+export declare function parseWorkspaceId(value: unknown, label: string): ParsedWorkspaceId;
+export {};
+//# sourceMappingURL=argument.d.ts.map

package/dist/argument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument.d.ts","sourceRoot":"","sources":["../src/argument.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,cAAc,CAAC;AAEtB,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAIpC,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,OAAO,CAAC,MAAM,eAAe,EAAE,OAAO,MAAM,CAAC;AAC7C,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAC3C,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAC3C,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAC;AAC/C,OAAO,CAAC,MAAM,UAAU,EAAE,OAAO,MAAM,CAAC;AACxC,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE7E,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEzE,qDAAqD;AACrD,KAAK,cAAc,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEjF,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,gBAAgB,GAChB,WAAW,GACX,cAAc,GACd,iBAAiB,CAAC;AAEtB,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAsBD,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEvE;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CA6B3B;AAED,+FAA+F;AAC/F,wBAAsB,SAAS,CAC7B,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,UAAU,CAAC,CA4BrB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAYnF;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAKrE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAKjF"}

package/dist/argument.js

@@ -0,0 +1,101 @@
+import { isAbsolute, normalize } from "node:path";
+import { CommandCancelledError, 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;
+/** 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, maxLength) {
+    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) {
+    return hasSafeArgumentSyntax(value, MAX_PATH_LENGTH);
+}
+export async function parseBranchName(runner, value, label, cwd, signal) {
+    if (!hasSafeArgumentSyntax(value, MAX_BRANCH_NAME_LENGTH)) {
+        throw new Error(`${label} is not a safe branch name: ${JSON.stringify(value)}.`);
+    }
+    let result;
+    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;
+}
+/** A base for a new worktree only has to resolve to a commit, so tags and SHAs are allowed. */
+export async function parseBase(runner, value, label, cwd, signal) {
+    if (!hasSafeArgumentSyntax(value, MAX_BRANCH_NAME_LENGTH)) {
+        throw new Error(`${label} is not a safe Git revision: ${JSON.stringify(value)}.`);
+    }
+    let result;
+    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, commit: commit };
+}
+export function parseAbsolutePath(value, label) {
+    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;
+}
+/** A label is display text, so it only has to stay a single argument on one line. */
+export function parseLabel(value, label) {
+    if (!hasSafeArgumentSyntax(value, MAX_LABEL_LENGTH)) {
+        throw new Error(`${label} must be single-line text without leading options.`);
+    }
+    return value;
+}
+export function parseWorkspaceId(value, label) {
+    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;
+}
+//# sourceMappingURL=argument.js.map

package/dist/argument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument.js","sourceRoot":"","sources":["../src/argument.ts"],"names":[],"mappings":"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"}

package/dist/capability.d.ts

@@ -0,0 +1,30 @@
+import { type ParsedAbsolutePath } from "./argument.js";
+import { type CommandRunner } from "./process.js";
+export interface GitRepository {
+    readonly root: ParsedAbsolutePath;
+    readonly gitDir: ParsedAbsolutePath;
+}
+export interface HerdrCapability {
+    readonly repository: GitRepository;
+    readonly herdrVersion: string;
+    readonly cache: "memory" | "detected";
+}
+export declare class HerdrUnavailableError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * 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 declare class HerdrCapabilityResolver {
+    #private;
+    constructor(runner?: CommandRunner, environment?: Readonly<Record<string, string | undefined>>, now?: () => number);
+    ensure(cwd: string, signal?: AbortSignal): Promise<HerdrCapability>;
+    /**
+     * 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.
+     */
+    tryEnsure(cwd: string, signal?: AbortSignal): Promise<HerdrCapability | undefined>;
+    forget(cwd: string): void;
+}
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,kBAAkB,EAAqB,MAAM,eAAe,CAAC;AAC3E,OAAO,EAGL,KAAK,aAAa,EAGnB,MAAM,cAAc,CAAC;AAStB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CAAC;CACvC;AAOD,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAGlD;CACF;AA6BD;;;GAGG;AACH,qBAAa,uBAAuB;;IAOlC,YACE,MAAM,GAAE,aAA0B,EAClC,WAAW,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,EACvE,GAAG,GAAE,MAAM,MAAiB,EAK7B;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAcxE;IAED;;;OAGG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAqBvF;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAWxB;CAgFF"}

package/dist/capability.js

@@ -0,0 +1,154 @@
+import { resolve } from "node:path";
+import { parseAbsolutePath } from "./argument.js";
+import { CommandCancelledError, 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];
+const CAPABILITY_MAX_AGE_MS = 10 * 60 * 1000;
+const UNAVAILABLE_RETRY_MS = 5 * 60 * 1000;
+export class HerdrUnavailableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "HerdrUnavailableError";
+    }
+}
+function isAtLeast(installed, minimum) {
+    for (const [index, required] of minimum.entries()) {
+        const part = installed[index] ?? 0;
+        if (part !== required) {
+            return part > required;
+        }
+    }
+    return true;
+}
+function parseHerdrVersion(result) {
+    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 {
+    #runner;
+    #environment;
+    #now;
+    #memory = new Map();
+    #unavailable = new Map();
+    constructor(runner = runCommand, environment = process.env, now = Date.now) {
+        this.#runner = runner;
+        this.#environment = environment;
+        this.#now = now;
+    }
+    async ensure(cwd, signal) {
+        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, signal) {
+        // 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) {
+        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, capability) {
+        const remembered = { capability, expiresAt: this.#now() + CAPABILITY_MAX_AGE_MS };
+        this.#memory.set(lookupKey, remembered);
+        this.#memory.set(resolve(capability.repository.root), remembered);
+    }
+    #isManagedSession() {
+        return this.#environment[SESSION_MARKER] === "1";
+    }
+    #assertManagedSession() {
+        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, signal) {
+        let result;
+        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, signal) {
+        let result;
+        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);
+    }
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"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"}

package/dist/guidance.d.ts

@@ -0,0 +1,22 @@
+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 declare 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 declare function registerHerdrGuidance(pi: HerdrPromptApi, capabilities: HerdrCapabilityResolver): void;
+export {};
+//# sourceMappingURL=guidance.d.ts.map

package/dist/guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.d.ts","sourceRoot":"","sources":["../src/guidance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,iBAAiB,iLACkJ,CAAC;AAEjL,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,CACD,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,CACP,KAAK,EAAE,qBAAqB,EAC5B,OAAO,CAAC,EAAE,uBAAuB,KAC9B,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,GAC/C,IAAI,CAAC;CACT;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,cAAc,EAClB,YAAY,EAAE,uBAAuB,GACpC,IAAI,CAeN"}

package/dist/guidance.js

@@ -0,0 +1,20 @@
+/**
+ * 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.";
+export function registerHerdrGuidance(pi, capabilities) {
+    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}` };
+    });
+}
+//# sourceMappingURL=guidance.js.map

package/dist/guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.js","sourceRoot":"","sources":["../src/guidance.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAC5B,8KAA8K,CAAC;AAyBjL,MAAM,UAAU,qBAAqB,CACnC,EAAkB,EAClB,YAAqC;IAErC,EAAE,CAAC,EAAE,EAAE,CAAC,oBAAoB,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACrD,MAAM,YAAY,GAAG,KAAK,EAAE,YAAY,CAAC;QACzC,6EAA6E;QAC7E,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACjF,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,UAAU,GAAG,MAAM,YAAY,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAChG,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,OAAO,iBAAiB,EAAE,EAAE,CAAC;IACrE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type HerdrExtensionApi } from "./tools.js";
+export default function piHerdrWorktree(pi: HerdrExtensionApi): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAA8B,MAAM,YAAY,CAAC;AAEhF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAEnE"}

package/dist/index.js

@@ -0,0 +1,5 @@
+import { registerHerdrWorktreeTools } from "./tools.js";
+export default function piHerdrWorktree(pi) {
+    registerHerdrWorktreeTools(pi);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAEhF,MAAM,CAAC,OAAO,UAAU,eAAe,CAAC,EAAqB;IAC3D,0BAA0B,CAAC,EAAE,CAAC,CAAC;AACjC,CAAC"}

package/dist/process.d.ts

@@ -0,0 +1,33 @@
+export interface CommandResult {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface RunCommandOptions {
+    readonly cwd: string;
+    readonly signal?: AbortSignal | undefined;
+    readonly maxOutputBytes?: number | undefined;
+}
+export type CommandRunner = (command: string, args: readonly string[], options: RunCommandOptions) => Promise<CommandResult>;
+export declare class CommandInvocationError extends Error {
+    readonly command: string;
+    readonly code: string | undefined;
+    constructor(command: string, message: string, code: string | undefined, options?: ErrorOptions);
+}
+export declare class CommandCancelledError extends Error {
+    constructor(command: string);
+}
+/**
+ * Node kills the child once its output passes `maxBuffer`. That is a size limit, not a
+ * broken executable, so it gets its own type instead of looking like a failed spawn.
+ */
+export declare class CommandOutputLimitError extends Error {
+    readonly command: string;
+    readonly maxOutputBytes: number;
+    constructor(command: string, maxOutputBytes: number, options?: ErrorOptions);
+}
+export declare const runCommand: CommandRunner;
+export declare function runChecked(runner: CommandRunner, command: string, args: readonly string[], options: RunCommandOptions, failureContext: string): Promise<CommandResult>;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,aAAa,CAAC,CAAC;AAY5B,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAElC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,EAK7F;CACF;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,YAAY,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAO1E;CACF;AAED,eAAO,MAAM,UAAU,EAAE,aAmDxB,CAAC;AAEF,wBAAsB,UAAU,CAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,iBAAiB,EAC1B,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,aAAa,CAAC,CAOxB"}