Worktree

Isolate this session

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.

Do not create one with execute (git worktree add, cd). That only adds a directory; this session's file tools stay in the old checkout. Call the worktree tool — it moves process cwd, sandbox, peer record and the status bar together. The transcript stays where it already was.

When

• list_agents shows another session in this directory (dirty files, same branch) and you are about to edit.
• The user or a peer names a task checkout ("切到 gateway-peers").
• A change should not land on the shared working tree.

Not this: a read-only task subagent (it does not write). A second CLI the human should watch is multi-agent — start that process with --worktree or its own -c.

How

Name the task, not yourself. Reused while the task is in progress; gone after merge. The tool schema lists the actions; do not invent paths.

• worktree(action="use", name="<task>") — create or reuse, then move here
• worktree(action="status") — where you are, every worktree of this repo
• worktree(action="merge") — land on local main, delete the checkout, return
• worktree(action="remove") — drop one with no unique work

The human's surfaces: agentica --worktree <task> at start (see agentica --help), /worktree mid-session. You cannot type slash commands; use the tool. Tell the user which slash to type when they want to drive.