Isolate work in a worktree

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. Do not execute git worktree add: that only makes a directory, and later calls still use this session unless you pass work_dir / path. Use worktree(action="new").

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.