# Operations reference

The extension registers one tool, `herdr_worktree`. Its parameters are a closed union: the
`operation` field picks a variant, and each variant accepts only its own fields. Unknown
operations, unknown fields, and missing fields are rejected before any command runs.

Every command runs with the repository root as its working directory, and every operation that
opens a workspace passes `--no-focus` unless `focus` is `true`.

## `list`

No fields. Runs `herdr worktree list --cwd <repository root>`.

Reports every worktree of the current repository: its checkout path, its branch, the Herdr
workspace holding it, and whether it is the main checkout or a linked worktree. Read-only. Oh My Pi
treats it as a `read` operation and allows it to run concurrently with other reads.

## `create`

| Field | Type | Required |
| --- | --- | --- |
| `branch` | New branch name | yes |
| `base` | Commit, branch, or tag the branch starts from | no |
| `path` | Absolute path for the checkout | no |
| `label` | Single-line workspace label | no |
| `focus` | Move the user's view to the new workspace | no, defaults to `false` |

Runs `herdr worktree create` with each value as a separate argument. Without `path`, Herdr places
the checkout under its own worktree directory. With `path`, the caller chose where to write, so Oh
My Pi prompts the user first.

Before running, the tool reads the Git worktree list and refuses a `branch` that is already checked
out in a worktree, or a `path` that is already a worktree of this repository. A `path` must also sit
outside every worktree of the repository and outside its Git directory, and must not exist yet or
must be an empty directory. The tool may run from a linked worktree, so the check covers every
registered checkout and not only the one it was called from.

After running, it requires that Herdr reported a `worktree_created` result, on the requested branch
and at the requested path, marked as a linked worktree, and that Git lists that path as a worktree
with that branch checked out. When `base` was given, the new checkout must sit at the commit that
`base` pointed at while it was parsed, so a ref that moved in between is reported instead of
accepted.

## `open`

| Field | Type | Required |
| --- | --- | --- |
| `path` | Absolute path of an existing checkout | exactly one of `path` or `branch` |
| `branch` | Branch of an existing worktree | exactly one of `path` or `branch` |
| `label` | Single-line workspace label | no |
| `focus` | Move the user's view to the workspace | no, defaults to `false` |

Runs `herdr worktree open`. Passing both `path` and `branch`, or neither, is rejected.

After running, it requires that Herdr reported a `worktree_opened` result matching the requested
path or branch, and that Git lists that path as a worktree. A worktree that already had a workspace
is reported as already open.

## `remove`

| Field | Type | Required |
| --- | --- | --- |
| `workspace_id` | Herdr workspace id, such as `wG` | yes |
| `force` | Remove the checkout even with uncommitted changes | no, defaults to `false` |

Runs `herdr worktree remove --workspace <id>`, adding `--force` only when asked.

Before running, the tool lists the repository's worktrees and requires that `workspace_id` holds a
linked worktree of this repository. It refuses the main checkout and the repository it is running
in. It then asks the user to confirm, and stops if they decline.

After running, it requires that Herdr removed the workspace and path it was asked about, and that
Git no longer lists that path as a worktree.

## Limits

- Branch names: 1 to 255 characters, cannot start with `-`, resolved by
  `git check-ref-format --branch`. The name Git prints is the one used, so shorthand such as
  `@{-1}` becomes the branch it stands for before any check runs.
- A `base` must resolve to a commit, checked with `git rev-parse --verify <base>^{commit}`. The
  commit it resolved to is kept for the check after the create.
- Paths: absolute, 1 to 4096 characters, normalised, cannot start with `-`.
- Labels: 1 to 120 characters, cannot start with `-`.
- Workspace ids: `w` followed by 1 to 16 letters or digits.
- Control characters, bidirectional marks, and untrimmed values are rejected everywhere. A newline
  would let a value forge a line of Git's output.

## Excluded commands

| Command group | Why it is not exposed |
| --- | --- |
| `herdr workspace`, `herdr tab`, `herdr pane`, `herdr agent` | Terminal layout and agent control |
| `herdr session`, `herdr server`, `herdr update` | Can stop the user's session and its processes |
| `herdr config`, `herdr channel`, `herdr integration` | Change the installation, not the repository |

The model handles these through the normal Herdr workflow, with whatever approval the user
requires.