worktree · diff
v1.0 to v2.0
29 added, 35 removed. Audit A to A.
---
name: worktree
description: >-
- Isolate this CLI session in its own git worktree of the current repository
- (worktree tool: status / use / main / merge / remove). Use when another live
+ 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, when starting a parallel task checkout, or when asked
- to switch into a named worktree.
+ fight over index.lock, or when starting a parallel task checkout.
metadata:
- version: "1.0"
+ version: "2.0"
---
- # Isolate this session
+ # 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.
- 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.
+ 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.
- - 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`.
+ 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 task is in progress; gone after
- merge. The tool schema lists the actions; do not invent paths.
+ 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="use", name="<task>")` — create or reuse, then move here
- - `worktree(action="status")` — where you are, every worktree of this repo
- - `worktree(action="main")` — return to the main checkout; the worktree stays
- - `worktree(action="merge")` — land on local main (conflicts stay in this
- worktree, then fast-forward on main), delete the checkout, return
- - `worktree(action="remove")` — drop a `wt/*` checkout git will allow (dirty
- or someone else's lock is refused; an unmerged branch is left in place)
+ - `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)
- Not `use(name="main")` when you mean "take me back to the main checkout":
- `use` reads its name as a *task*, so that creates a second checkout on a
- `wt/main` branch instead. `main` is the way to leave one unfinished. `merge`
- and `remove` dispose of the worktree. A `cd` is not it: that moves the shell
- only, not the file tools.
+ `new(name="main")` is refused: `main` is the repository root, not a task.
- Do not delete a worktree with `execute` (`git worktree remove`, `rm -rf`) while
- you are standing in it: your working directory disappears under you and every
- later command fails on it, absolute paths included. The tool's `remove` and
- `merge` move the session out before deleting, which is the reason to use them.
+ For a chunk of work big enough for its own process, `delegate(task=...,
+ work_dir=<path>)` already takes the same path.
- 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.
+ 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.