Claude Code EnterWorktree 工具详解：从隔离工作区创建到进入与退出全流程

导读

EnterWorktree 是 Claude Code 中用于创建独立 git worktree 并将会话切换到其中的专用工具，它只在用户或项目指令（CLAUDE.md / memory）明确要求 "worktree" 时才被启用，避免自动会话意外闯入隔离工作区。本文基于本仓库（claude-code-system-prompts，Claude Code 各版本系统提示词的完整镜像）中的 EnterWorktree 工具说明，并结合 ExitWorktree、后台会话隔离指引等配套文档，系统讲解该工具的触发条件、行为规则、worktree.baseRef 配置、name/path 双参数语义，以及它与 Agent 子代理隔离、后台作业持久化之间的协作机制，帮助你完整掌握 Claude Code 的 worktree 隔离工作流。

---

一、工具定位：只在“显式要求”时启用

EnterWorktree 的工具说明开篇就划定了严格的激活边界（见 tool-description-enterworktree.md）：

Use this tool ONLY when explicitly instructed to work in a worktree — either by the user directly, or by project instructions (CLAUDE.md / memory).

即：只有在用户直接说出 “worktree”，或 CLAUDE.md / memory 等项目指令明确指示本任务应在 worktree 中完成时，Claude Code 才会调用它。从该仓库的 CHANGELOG 记录可以印证这一收紧过程：Tool Description: EnterWorktree - Added explicit "When NOT to Use" section; narrowed activation to only when user explicitly says "worktree"; no longer triggers for general isolation or branch requests（见 CHANGELOG.md），也就是说工具早期曾因“一般性隔离需求”被触发，后来被明确收窄。

何时使用（When to Use）

• 用户明确说出 “worktree” 关键词，例如 "start a worktree"、"work in a worktree"、"create a worktree"、"use a worktree"；
• CLAUDE.md 或 memory 指令要求当前任务在 worktree 中执行。

何时不使用（When NOT to Use）

• 用户只是要求创建分支、切换分支或在另一个分支上工作 —— 此时应使用普通 git 命令，而非本工具；
• 用户要求修复 bug 或开发功能 —— 除非用户或项目指令明确要求 worktree，否则走常规 git 工作流；
• 只要 “worktree” 一词没有被用户或 CLAUDE.md / memory 提及，就绝不调用本工具。

这条“显式触发”原则与 Agent 工具的隔离参数形成互补：Agent 工具支持 isolation: "worktree" 让子代理自动在临时 worktree 中运行（见 tool-description-agent-usage-notes.md），而 EnterWorktree 面向的是“会话本身”被移入 worktree 的场景。

---

二、前置要求（Requirements）

使用 EnterWorktree 创建新 worktree 需要满足二选一的前提：

1. 当前必须位于一个 git 仓库中；或者
2. 在 settings.json 中配置了 WorktreeCreate / WorktreeRemove 钩子，从而支持非 git 仓库的 VCS 无关隔离。

此外还有一个状态约束：当会话已经处于某个 worktree 中时，不能再通过 name 创建新的 worktree；但允许通过 path 切换到另一个已存在的 worktree（详见下文“进入已存在的 worktree”）。

从 CHANGELOG 可以看到该工具的演进历史印证了这两点：Tool Description: EnterWorktree - Generalized from git-only to support VCS-agnostic isolation via WorktreeCreate/WorktreeRemove hooks; requirements now allow non-git repos with hooks configured，以及 WorktreeCreate / WorktreeRemove 也被列入可用 hook 事件清单（见 CHANGELOG.md）。这说明仓库外场景（例如非 git 管理的目录）通过自定义 hook 同样可以获得隔离能力。

---

三、核心行为：在 .claude/worktrees/ 中创建隔离工作区

3.1 git 仓库内的行为

在 git 仓库中，EnterWorktree 会：

1. 在 .claude/worktrees/ 目录下创建一个新的 git worktree；
2. 为它新建一个独立分支；
3. 将当前会话的工作目录切换到新 worktree。

新分支的基底（base ref）由 worktree.baseRef 设置决定，这是本工具最重要的配置项：

取值	默认	行为
fresh	✅ 默认	从 origin/<default-branch>（远端默认分支）切出新分支，与本地当前 HEAD 无关，得到“干净的基线”
head	—	从当前本地 HEAD 切出新分支，继承本地尚未推送的提交

也就是说，默认的 fresh 模式让每个隔离工作区都从远端最新默认分支出发，避免把本地未提交/未推送的改动带入隔离环境；而 head 模式则适合需要基于当前本地工作继续开发的场景。CHANGELOG 中 Tool Description: EnterWorktree — Documents the worktree.baseRef setting for new worktrees, including the default fresh behavior from origin/<default-branch> and the head option from current local HEAD（见 CHANGELOG.md）正是对这一设置的记录。

3.2 非 git 仓库的行为

如果不在 git 仓库中，工具会委托给 WorktreeCreate / WorktreeRemove 钩子完成 VCS 无关的隔离，即隔离能力由用户自定义的 hook 实现，工具本身不直接操作 git。

3.3 会话退出时的清理

• 会话进行中可以通过 ExitWorktree 主动离开 worktree（保留或删除）；
• 如果退出会话时仍停留在 worktree 中，Claude Code 会提示用户选择保留（keep）或删除（remove）。

---

四、参数详解：name 与 path 互斥

EnterWorktree 只有两个参数，且二者互斥：

参数	可选性	语义
name	可选	为新 worktree 指定名称；如果 name 和 path 都未提供，则自动生成随机名称
path	可选	直接进入一个已存在的 worktree，而不是新建；必须属于当前仓库，或在首次从启动目录进入时属于嵌套在当前仓库内的子仓库

使用 path 进入已存在 worktree 的典型场景是：用户（或会话）先用 git worktree add 手动创建了 worktree，然后希望 Claude Code 的会话切换进去工作。

4.1 进入既有 worktree 的校验规则

• 首次从启动目录（launch directory）进入时：目标路径必须出现在 git worktree list 输出中，且属于其所属仓库 —— 即当前仓库，或在多仓库工作区中嵌套于当前仓库内部的子仓库；两者皆未登记的路径会被拒绝。
• 后续切换 / 已处于 worktree 中时：目标必须是同一仓库下 .claude/worktrees/ 中的 worktree。
• 已固定在启动目录的 Agent（子代理隔离或显式 cwd）：同样支持 path 切换，但该切换只影响该 Agent 自身，不影响父会话。
• 从 worktree 切换出去后，之前访问过的 worktree 不再可写；如需返回，需再次用 path 调用 EnterWorktree。

4.2 与 ExitWorktree 的边界

通过 path 进入的既有 worktree，ExitWorktree 不会删除它（ExitWorktree 只管理本会话由 EnterWorktree 创建的 worktree，见 tool-description-exitworktree.md）；此时应使用 action: "keep" 返回原始目录。

---

五、配套工具 ExitWorktree：保留或删除

EnterWorktree 的说明明确指向了配套工具 ExitWorktree，用于在会话中途离开 worktree。它的关键规则如下：

• 作用域极窄：只操作本会话中由 EnterWorktree 创建的 worktree；绝不触碰：
  • 用户手动用 git worktree add 创建的 worktree；
  • 之前会话（即便也是 EnterWorktree 创建的）留下的 worktree；
  • 从未调用过 EnterWorktree 时的当前目录。
• 会话外调用是 no-op：如果在非 EnterWorktree 会话中调用，它仅报告“无活动 worktree 会话”且不改变任何文件系统状态。

参数与行为

• action（必填）："keep"（保留 worktree 目录与分支在磁盘上，适合稍后继续或保留改动）或 "remove"（删除目录与分支，适合工作已完成或放弃时干净退出）。
• discard_changes（可选，默认 false）：仅在 action: "remove" 时有意义。若 worktree 中存在未提交文件或不在原分支上的提交，工具会拒绝删除，除非显式传入 true。若工具返回列出改动的错误，应先与用户确认，再以 discard_changes: true 重试。
• 退出后：将会话工作目录恢复到 EnterWorktree 之前的位置，并清除依赖 CWD 的缓存（system prompt 分节、memory 文件、plans 目录），使会话状态与原始目录一致。
• 若退出时存在附着于 worktree 的 tmux 会话：remove 时会被终止，keep 时保持运行（并返回其名称以便重新附着）。
• 退出后可以再次调用 EnterWorktree 创建全新的 worktree。

---

六、生态协作：worktree 隔离在后台会话、子代理与 workflow 中的应用

EnterWorktree 不是孤立存在的工具，它被本仓库多份系统提示词作为隔离机制反复引用，理解这些协作场景有助于判断何时需要它。

6.1 后台会话：改代码前先隔离

后台工作区隔离指引 规定：后台会话在任何代码改动之前都应调用 EnterWorktree，将工作与其它并行任务以及用户的正式工作副本隔离开，除非当前 cwd 已经在 .claude/worktrees/ 下（此时已处于隔离状态）。这一规则是强制性的：在共享检出目录中的文件编辑会被拒绝，直到隔离完成 —— 因此应在第一次编辑之前调用 EnterWorktree，而不是在被拒绝之后再调用。只读、搜索或回答问题的工作则跳过隔离；若 EnterWorktree 失败，则原地继续。

6.2 子代理写入被阻塞时的处置

子代理写入被阻塞提示 展示了隔离的“强制”细节：当子代理的父后台会话尚未隔离时，对共享检出目录的写入会被拦截。处置方式有三：

1. 以 isolation: "worktree" 重新派生子代理；
2. 让父会话先调用 EnterWorktree 再派生子代理；
3. 用 git worktree add 为任务手动创建链接 worktree，在 worktree 内部路径中编辑（worktree 内的路径会被接受）。

该提示还给出了关闭守卫的配置方法：在当前仓库的 .claude/settings.json 中设置 "worktree": {"bgIsolation": "none"}。

6.3 后台会话的持久化：提交、推送与草稿 PR

后台会话 worktree 持久化指引 说明：如果你在进入的 worktree 中做了代码改动，完成前应提交（无需询问），且仓库配置有 remote 时应推送——因为 worktree 可能随会话一起被删除，已提交并推送的工作才能存活。此规则的前提是用户没有在任务、CLAUDE.md 或 memory 中保留 git 操作权；若任务需要，还可打开草稿 PR。反之，若本作业未自行进入 worktree、或正处于用户自己的工作副本中，则提交或切换分支前必须询问。

6.4 Workflow 子代理：自动清理与保留

Workflow 隔离 worktree 提示 告知 workflow 子代理：它正运行在一个独立的 git worktree（即仓库的独立工作副本）中，其改动不影响主工作目录或其他 Agent；若未做任何改动，worktree 会被自动清理；若产生了改动，则会保留供审查。

6.5 Fork 会话：绝不进入原会话的 worktree

Fork 会话 worktree 隔离指引 规定：从某会话 fork 出的后台对话绝不能编辑、运行命令或进入原会话仍在使用中的链接 worktree；在隔离启用时，应先用自己的 EnterWorktree 创建新 worktree，若任务建立在原会话成果之上，应基于原 worktree 分支创建新分支（而非检出该分支，因为它仍被原 worktree 占用）。

6.6 批处理命令与并行 Agent

/batch 斜杠命令 要求计划获批后，为每个工作单元派生的后台 Agent 全部使用 isolation: "worktree" 与 run_in_background: true，并在单条消息中并行启动，以避免并行编辑相互覆盖。Agent 工具的 usage notes 也确认：使用 isolation: "worktree" 时，若 Agent 未做改动，worktree 会自动清理；否则路径与分支会随结果一并返回（见 tool-description-agent-usage-notes.md）。

6.7 共享 stash 的安全注意

由于 git stash 栈在主检出与所有 worktree 之间共享，其它会话可能并发 push/pop（见 共享 git stash 安全）。在多 worktree 隔离环境中，禁止裸用 git stash / git stash pop（可能弹出其它会话的改动）；优先用临时 WIP 提交暂存工作；若必须 stash，应使用 git stash push -u -m "<unique-tag>"，立即用 git stash list --format='%H %gs' 记录条目 SHA，用 git stash apply <sha> 恢复（而非 pop），之后按标签重新定位 stash@{n} 再 drop。

---

七、与状态栏、安全审计的联动

• 状态栏配置中，当工作目录位于链接 worktree 中时，workspace schema 会提供 git_worktree 字段（报告 worktree 名称），早期版本还包含 worktree 对象（name、path、branch、original cwd、original branch 等字段），便于在 UI 中直观呈现当前隔离状态（见 agent-prompt-status-line-setup.md 及 CHANGELOG.md 相关条目）。
• 安全审计方面，.claude/worktrees/<name>/ 下的文件被当作普通项目文件处理，不构成自我修改（Self-Modification）风险，除非其中包含受保护配置（见 CHANGELOG.md 中 Security monitor 相关条目）。

---

八、实践决策速查

场景	正确做法
用户说 “start a worktree”	调用 EnterWorktree（可带 name）
用户仅要求切换分支	用 git 命令，不调用本工具
用户先 git worktree add 建好工作区，要求进入	调用 EnterWorktree 并传 path（须在 git worktree list 中登记）
会话中途要离开 worktree	调用 ExitWorktree，action 选 keep 或 remove
离开时 worktree 有未提交改动	ExitWorktree 会拒绝 remove，须先确认再传 discard_changes: true
后台会话要改代码	先调用 EnterWorktree 隔离，改完提交、推送（用户未保留 git 控制权时）
并行派生子代理编辑同一仓库	全部使用 isolation: "worktree" + run_in_background: true 并行启动
需要基于本地未推送提交建 worktree	配置 worktree.baseRef: "head"；默认 fresh 从远端默认分支出发

---

结语

EnterWorktree 是 Claude Code 隔离工作流的关键入口：它以“显式请求”为唯一触发条件，在 .claude/worktrees/ 下按 worktree.baseRef（默认 fresh）创建独立分支，并通过 name/path 两个互斥参数分别覆盖“新建隔离区”与“进入既有工作区”两类场景，再与 ExitWorktree、后台会话持久化、子代理写入守卫、共享 stash 安全等一系列配套机制协同，构成一套完整的并行隔离与清理闭环。掌握本工具的使用边界与参数语义，即可在 Claude Code 中安全地并行开发、隔离试验，而不污染主工作副本。