Explicit worktree creation
显式创建工作树
A Session that needs an isolated checkout otherwise has to coordinate Git commands with its own working directory. Changing a shell process directory does not update the Session's later tools or recorded context, and a linked worktree's Git administration directory can lie outside the Session's existing write grant.
English
Problem
A Session that needs an isolated checkout otherwise has to coordinate Git commands with its own working directory. Changing a shell process directory does not update the Session's later tools or recorded context, and a linked worktree's Git administration directory can lie outside the Session's existing write grant.
Decision
The experimental worktree runtime creates a new named branch and checkout from a pinned local commit, then enters its canonical directory through the shared working-directory service. The tool exposes create_worktree({ name?, from? }). These packages use ordinary explicit composition, with no additional runtime feature flag.
The source repository comes from the calling Session's current directory. Creation does not fetch or copy uncommitted files. The default pool is .agents/worktrees under the current checkout’s top-level directory, including when the caller is in a linked checkout. The process that creates a pool writes its self-ignoring .gitignore; existing directories and ignore files are preserved. Names must be new branches and unused checkout paths.
Git and directory creation use the mounted subprocess and sandbox providers without widening the calling Session's policy. Both destination and shared Git metadata writes must already be permitted. Successful creation changes only the current working directory; the Session identity and original sandbox root remain owned by their existing services.
Leaving uses the shared working-directory operation and retains the checkout and branch. Failed setup can retain partial artifacts and reports their location. The service does not own a checkout registry, cleanup schedule, branch merge policy, or task association database.
Alternatives considered
A separate worktree-exit tool. Leaving is the existing working-directory operation; another exit operation would needlessly couple directory changes to Git ownership or deletion.
Copy the dirty checkout into each new worktree. A pinned local commit gives the caller an explicit baseline without mixing staged, unstaged, untracked, and ignored state or inventing conflict rules.
Automatic subagent isolation. Agent Teams keeps its existing explicit coordination model. Creating a checkout is available as an operation rather than an implicit consequence of delegation.
Expand write grants during creation. A convenience operation cannot acquire authority over a shared Git administration directory merely because the destination is writable.
Consequences
The caller can continue one Session in a new checkout with a reconstructable directory change. Retention avoids deleting work on exit or a failed final publication, but callers must manage unused checkouts and branches themselves. Git and Node must be available in the filesystem provider's execution world. Submodule setup and dependency installation remain separate operations.
中文
Problem
需要隔离检出目录的 Session 原本必须自行协调 Git 命令与工作目录。改变 shell 进程目录不会更新 Session 后续工具或已记录的上下文，而且链接工作树的 Git 管理目录可能位于 Session 既有写权限范围之外。
Decision
实验性工作树运行时从固定的本地提交创建新的具名分支与检出目录，然后通过共享工作目录服务进入其规范路径。工具公开 create_worktree({ name?, from? })。这些包使用普通的显式组合，不添加额外运行时功能开关。
源仓库由调用 Session 的当前目录决定。创建操作不会获取远端提交或复制未提交文件。默认父目录是当前检出目录顶层路径下的 .agents/worktrees，调用方位于链接检出目录中时也一样。创建该目录的进程写入忽略自身的 .gitignore；已有目录与忽略文件保持不变。名称必须对应新分支与尚未使用的检出路径。
Git 与目录创建使用挂载的子进程及沙箱提供方，不扩大调用 Session 的策略。目标目录与共享 Git 元数据必须均已允许写入。成功创建只改变当前工作目录；Session 身份与原始沙箱根目录仍由已有服务拥有。
离开使用共享工作目录操作，保留检出目录与分支。初始化失败可能留下部分产物，并报告其位置。该服务不拥有工作树注册表、清理计划、分支合并策略或任务关联数据库。
Alternatives considered
单独提供工作树退出工具。 离开就是已有工作目录操作；另一个退出操作会无谓地将目录切换与 Git 所有权或删除耦合。
将未提交状态复制到每个新工作树。 固定本地提交为调用方提供显式基准，无需混合暂存、未暂存、未跟踪和被忽略的状态，也无需制定冲突规则。
自动隔离子代理。 Agent Teams保留已有的显式协调模型。创建检出目录是一项可调用操作，而不是委派的隐含结果。
创建时扩大写权限。 便捷操作不能仅因目标目录可写，就获得共享 Git 管理目录的权限。
Consequences
调用方可以在新的检出目录继续同一个 Session，且目录切换可重建。保留策略避免在离开或最后发布失败时删除工作，但调用方必须自行管理闲置检出目录与分支。Git 与 Node 必须存在于文件系统提供方的执行环境中。子模块配置与依赖安装仍是独立操作。