v2.0 to v2.1

---

name: worktree

description: >-

Isolate parallel work in a git worktree of the current repository

(worktree tool: status / new / merge / remove). Use when another live

session is dirty in the same directory (list_agents), when two agents would

fight over index.lock, or when starting a parallel task checkout.

metadata:

---

# Isolate work in a worktree

Several sessions in one checkout overwrite each other and contend for git's

index. A worktree is one directory + one branch per *task*, sharing the

repository.

This session does **not** move. `worktree(action="new")` returns a path.

Pass that path as `work_dir` on `read_file` / `write_file` / `apply_patch` /

`execute`. On `glob` / `grep`, pass it as `path`. Omit those arguments and

the call stays in this session's directory.

Do not `cd` and expect later calls to follow — each call is independent.

## When

- `list_agents` shows another session in this directory (dirty files, same

branch) and you are about to edit.

- A change should not land on the shared working tree.

Not this: a read-only `task` subagent (it does not write). A second CLI

that should start already inside a tree is `agentica --worktree <task>`.

## How

Name the *task*, not yourself. Reused while the checkout is healthy; gone

after merge. A registration that is no longer a checkout is refused — remove

it first, or pick another name. The tool does not delete leftover files to

make room.

- `worktree(action="new", name="<task>")` — create or reuse; returns the path

- `worktree(action="status")` — every worktree of this repo

- `worktree(action="merge", name="<task>")` — land on local main (conflicts

stay in that worktree, then fast-forward on main), delete the checkout

- `worktree(action="remove", name="<task>")` — drop a `wt/*` checkout git

will allow (dirty is refused; an unmerged branch is left in place)

`new(name="main")` is refused: `main` is the repository root, not a task.

For a chunk of work big enough for its own process, `delegate(task=...,

work_dir=<path>)` already takes the same path.

If a directory goes missing, `status` labels it `(directory gone)` or

`(not a checkout)`. Say so; do not rebuild it by destroying what sits there.

`remove` the name, then `new` if you still want it.