Claude Code subagent、Agent Team 与后台 Session 区别：含 Worktree 与 resume

Technical2026-07-14

Claude Code 文档里到处是 agent。问题是：它们不是同一种东西。

有人说「我开了三个 agent」——可能是 Agent View 里三个后台 session；也可能是主对话里 spawn 的三个 subagent；还可能是实验性 Agent Team 里三个 teammate。混着说，排查问题会疯。

这篇文章把它们拆开，顺带讲 resume、消息和 worktree。官方入口：

版本很重要。Agent View 从 v2.1.139 起；subagent 默认后台是 v2.1.198；Agent Team 行为在 v2.1.178+ 改过一轮。先 claude --version。

先记一张对照表

	Subagent	Background session	Agent team teammate
是什么	主 session 内部的专职工人	完整 Claude Code 会话，挂在 supervisor 上	另一套完整 Claude 实例，由 lead 协调
上下文	自己的 window；结果摘要回主对话	完整独立对话	完整独立对话
互相通信	不能。只向调用方汇报	默认互不相干	能。共享 task list + 直接发消息
你怎么管	主对话里 @ / 自然语言 / Agent 工具	`claude agents`、peek、attach	lead 面板或 split pane
并行文件	默认同目录；可 `isolation: worktree`	写文件前常自动进 `.claude/worktrees/`	各自 session；冲突靠任务拆分
成本	相对低（摘要回流）	每个 session 独立吃 quota	明显更贵：每人一整份上下文
默认开吗	开（内置 Explore / Plan 等）	开（Agent View 是 research preview）	关。要 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`

一句话版：

Subagent：主对话的外包。读日志、搜代码、跑测试，脏输出别污染主上下文。
Background session：你自己的第二、第三、第 N 个 Claude，关掉终端也继续干活。
Agent team：一群能互聊、能抢任务的 Claude，lead 当项目经理。实验特性，贵，有坑。

Worktree 不是第四种 agent。它是文件系统隔离层：给并行写代码的人各分一套工作目录，避免互相覆盖。

Subagent：主 session 里的工人

Subagent 跑在当前 session 内部。自己的 context window、自己的 system prompt、可限制 tools 和 model。干完把摘要交回主 Claude。工人之间不聊天。

内置的几个：

Explore：只读搜代码，结果不塞爆主对话
Plan：plan mode 里做调研
General-purpose：又要读又要改的复杂活

自定义就是 Markdown + frontmatter，丢进：

项目：.claude/agents/
全局：~/.claude/agents/

---
name: code-reviewer
description: Reviews code for quality and best practices. Use after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. Be specific. Show current code and a better version.

调用方式：

Use the code-reviewer subagent on the auth changes

或 @ 点名。整 session 当某种 agent 跑：

claude --agent code-reviewer

前台 / 后台

前台：卡住主对话等结果；权限弹窗直接给你
后台：主对话继续聊；需要权限时弹到主 session（v2.1.186+）

v2.1.198 起默认偏后台。Claude 要立刻用结果时会前台跑。你也可以明说「后台跑」或 Ctrl+B 把当前任务打到后台。

彻底关掉后台任务：CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1。

注意：background subagent ≠ background session。前者是主 session 里的后台任务；后者是 Agent View 里一整行独立会话。Subagent 不会作为单独一行出现在 claude agents 列表里。

Resume subagent

每次默认是新实例、干净上下文。要接着干，让 Claude resume 那个 subagent——保留完整对话、工具调用和推理轨迹，从断点继续。

API 挂了导致 subagent 失败时（v2.1.199+），失败会如实回报，而不是把错误文本假装成「调研结论」。清掉限流后，重试或 resume。

嵌套 subagent 有深度上限（最多五层 subagent）；到顶就没有 Agent 工具了。Resume 不会改变它被 spawn 时的深度。

适合 / 不适合

适合：高噪音操作（测试输出、大规模搜索）、固定工种复用、限制只读权限。

不适合：需要和你频繁来回 refining 的实现；多阶段共享大量同一上下文——这时主对话更合适。需要工人之间辩论、抢任务 → 上 Agent Team，别硬叠 subagent。

Background session：真正「挂着跑」的 Claude

打开：

claude agents

这是 Agent View：一张表，所有后台 session。Working / Needs input / Completed 分组。关掉这个 TUI，session 还在跑——有独立 supervisor 进程养着它们，不绑你的终端。

怎么开一个

从 Agent View：底部输入任务，Enter。每条 prompt = 新 session，不是给旧的补一句。

从已有交互 session：

/bg
/background run the test suite and fix failures

或空 prompt 上按 ←（可关：leftArrowOpensAgents）。

从 shell：

claude --bg "investigate the flaky SettingsChangeDetector test"
claude --agent code-reviewer --bg "address review comments on PR 1234"
claude --bg --name "flaky-test-fix" "..."

会打印 short id 和管理命令：

backgrounded · 7c5dcf5d · flaky-test-fix
  claude agents
  claude attach 7c5dcf5d
  claude logs 7c5dcf5d
  claude stop 7c5dcf5d

纯跑 shell、不调模型：

claude --bg --exec 'pytest -x'
# 或在 agent view 输入：! pytest -x

消息：peek vs attach

操作	做什么
Space	Peek：最近输出 / 卡在哪问你什么；直接回复
Enter / →	Attach：完整交互 session
← 空 prompt	Detach 回列表（session 继续）
数字键 / Tab	多选问题选答案 / 填建议回复
`!cmd`	给该 session 塞一条 bash

从 shell：claude attach <id>、claude logs <id>。

Detatch 不会停 session。 要停：attach 后 /stop，或列表里 Ctrl+X，或 claude stop <id>。

双击 Ctrl+X 删除会连带拆掉 Claude 为它建的 worktree（含未提交改动）。要留的先 commit/push。你自己 git worktree add 开的目录不会被删。

Resume / 重启

进程挂了但会话还在：∙ 图标；peek/attach 会从断点续
机器睡眠：进程可恢复，supervisor 重连（别当无限保险）
关机：running session 会挂；用 claude respawn <id> 或 claude respawn --all 拉起，对话还在
删掉的 agent view 行：transcript 通常还在本地，claude --resume 仍可能找得到

Background session 不是「subagent 的 resume」。它是完整会话生命周期：background → attach → detach → stop → respawn。

自动 Worktree

后台 session 默认先在你的工作目录启动；写文件前会挪到 .claude/worktrees/ 下的隔离 worktree，避免几个后台活互相踩。

跳过隔离的情况：已经在 linked worktree 里、不是 git 仓库、写路径在仓库外。强制关掉：

{
  "worktree": {
    "bgIsolation": "none"
  }
}

v2.1.198+：隔离成功的后台 session 可以自己 commit、推自己的分支、开 draft PR——不会 push main/master，不会 force-push，不会 merge。行上会出现 #1234 之类 PR 标记。

后台 session 里再 spawn 的 subagent，默认继承 session 的 cwd（也就是那个 worktree）。要给 subagent 再套一层独立 worktree：isolation: worktree。

配额

每个后台 session 单独吃 subscription / API quota。Agent View 里开五个等于五个并行 Claude。钱包和 rate limit 自己算。

Agent Team：能互聊的一队 Claude

实验特性。默认关。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Lead = 你的主 session。Teammate = 各自完整 Claude 实例，独立上下文，通过共享 task list 和消息互相协调。你可以不经过 lead，直接跟某个 teammate 说话。

这是和 subagent 的硬差别：

Subagent:     主 ←—— 摘要 —— 工人A
              主 ←—— 摘要 —— 工人B
              A 和 B 互不认识

Agent team:   Lead
               ↕ task list / mailbox
              A ←——→ B ←——→ C

开法很土：打开开关后自然语言描述。

Spawn three teammates to explore this CLI design:
one on UX, one on architecture, one as devil's advocate.

面板里上下键选 teammate，Enter 进 transcript 直接说话。显示模式：teammateMode 的 in-process（默认）或 tmux/iTerm2 split panes。

消息与任务

Mailbox：teammate 之间按名字发消息；送达是自动的
Shared task list：pending / in progress / completed，可有依赖；可 lead 指派，也可自领（有文件锁防抢同一 task）
Idle 通知：干完会通知 lead；API error 也会（v2.1.198+）

Teammate 不继承 lead 的对话历史。CLAUDE.md、MCP、skills 会按正常 session 加载；任务细节必须写进 spawn prompt。

Subagent 定义可以复用到 teammate：spawn 时点名 agent type，会带上 tools / model，body 追加进 system prompt。但 skills / mcpServers frontmatter 在 teammate 路径上不生效——它们从项目/用户设置加载。

已知坑（官方自己写了）

in-process teammate 不能 /resume / /rewind 恢复；resume 后 lead 可能给幽灵 teammate 发消息
task 状态可能滞后，依赖链卡住要人工 nudge
关停慢：要等当前工具跑完
一 session 一队；不能嵌套 team；lead 不能转让
in-process teammate 的 subagent 只能前台；要后台 subagent 会报错（后台活不能活得比 lead 进程更久）
token 贵：每人一份完整上下文，线性涨

适合：多视角 review、竞争性假设 debug、边界清晰的模块并行。不适合：顺序活、同文件互改、省钱。

Worktree：防碰撞，不是 magician

Git worktree = 同一仓库另一套工作目录 + 分支。文件隔离靠这个，不靠模型自觉。

手动 / CLI

claude --worktree feature-auth
claude --worktree              # 自动起名
claude --worktree "#1234"      # 基于 PR

默认落在 .claude/worktrees/<name>/，分支 worktree-<name>。建议 gitignore 掉 .claude/worktrees/。

基线分支默认跟 origin/HEAD（干净 remote 视角）。要带着当前本地 HEAD 上的未推送状态：

{
  "worktree": {
    "baseRef": "head"
  }
}

.env 等 gitignored 文件默认不会进 worktree。根目录放 .worktreeinclude：

.env
.env.local
config/secrets.json

和 subagent / background 的关系

场景	Worktree 行为
`claude --worktree`	你显式开隔离 session
Background session 写文件	通常自动迁入 worktree（可关 bgIsolation）
Subagent `isolation: worktree`	临时 worktree；无改动自动清理
Agent team	不自动 magically 隔离文件；拆任务时别让两人改同一文件

Subagent 并行改代码却不设 isolation，等于多人写同一 checkout——覆盖是物理必然，不是运气差。

无改动、无新 commit 的 worktree 退出可自动清；有改动会问你。Background / subagent 建的、超过 cleanupPeriodDays 且干净的，也会被扫掉。你用 --worktree 手动建的不会被这轮清扫干掉。

消息模型（别混）

三种「发消息」不是一个通道：

你 ↔ 主 Claude / 你 attach 的 session
正常对话。
你 → background session（未 attach）
Agent View 的 peek 回复，或 attach 后输入。Session 不在列表里就看不见——先 /bg 或 --bg。
Agent team 内部
Lead ↔ teammate、teammate ↔ teammate。权限审批仍冒泡到 lead；teammate 不能替你点同意，也不能把被拒操作转包给别人绕过。

Subagent 没有 peer messaging。它只有：主 agent 派任务 → subagent 干活 → 结果回主 agent。你想「跟某个 subagent 继续聊」，路径是 resume 那个 subagent，不是给它发 team 邮件。

怎么选

主对话一个人干完
小改、要连续讨论、延迟敏感。

Subagent
噪音大、可摘要、工种固定、或要限制工具。调研 / 测日志 / 只读 review 首选。

Background session
好几件互不依赖的活，你不想盯着：修 flaky test、开 PR、改无关模块。用 Agent View 当仪表盘。

Agent team
需要辩论、交叉验证、共享任务板的复杂活。先接受贵和实验性。

Worktree
只要「并行写文件不互踩」，三个层级都能挂。Background 常常自动挂；subagent 要显式 isolation: worktree；你自己多终端并行就用 --worktree。

反模式：

用一堆无 isolation 的 subagent 并行改代码 → 文件战争
用 Agent Team 跑「跑一下测试」→ 用核打击蚊子
以为 background subagent 会出现在 claude agents → 不会
删 Agent View 行前不 push → worktree 里的活一起蒸发

实战：从 `claude agents` 到 draft PR

概念表背完没用。走一遍最短闭环：两件互不依赖的活，并行后台跑，最后各自（或你）开出 PR。

0. 前置

Claude Code ≥ 2.1.139（Agent View）；自动 commit/PR 行为看 ≥ 2.1.198
在一个 git 仓库里操作（非 git 没有默认 worktree 隔离）
权限模式按你平常习惯；后台 dispatch 默认吃该目录的 defaultMode，别一上来就 bypassPermissions 除非你清楚后果

1. 打开仪表盘

cd ~/projects/my-app
claude agents

底部是 dispatch 输入，上面是空表。关掉这个界面（Esc）session 不会停——supervisor 还在养。

2. 丢两条独立任务

分别回车，各起一行 session，例如：

Fix the flaky SettingsChangeDetector test. Run the failing test, fix root cause, keep changes minimal.

Add a draft PR description outline for the auth middleware refactor: list files touched and open questions. Do not change production behavior.

注意：Agent View 里每条 prompt = 新 session，不是给上一行补一句。要跟进某一行，用 Space peek 或 Enter attach。

也可以 shell 里直接后台起：

claude --bg --name "flaky-test" "Fix the flaky SettingsChangeDetector test..."
claude --bg --name "auth-notes" "Add a draft PR outline for auth middleware..."

3. 看它们有没有互踩

默认后台 session 写文件前会迁进 .claude/worktrees/。两行活各写各的目录和分支，主 checkout 不被当面改烂。

行上出现黄色 / Needs input：Space 打开 peek，回答问题或点权限
行上出现 #1234：这行已经挂上（或自己开了）PR
想盯完整 transcript：Enter attach；看完 ← 空 prompt detach，不要 /stop 除非真要杀

v2.1.198+ 且成功隔离的后台 session，可以自己 commit、推自己的分支、开 draft PR——不会推 main/master，不会 force-push，不会 merge。你在提示里写「不要开 PR」它会跳过。

4. 你介入的两种姿势

轻量：peek 里回一句「跑完测试再 commit」「用 conventional commits」。

重量：attach 进去当正常 Claude Code 用——改提示、/model、看 diff。完事 detach 回列表。

进程挂了但会话还在（∙ 图标）：attach 或 claude respawn <id> 从断点续，不是从零开。

5. 收口

你想要的结果	做法
合并	浏览器 / `gh` 审 draft PR，该改再 attach 那一行继续改
只要分支	peek 看 worktree 路径与分支名，本地 checkout 审
丢弃	确认没有要留的 commit 后，列表 `Ctrl+X` 两次删行（会拆掉 Claude 建的 worktree）

删行前未 push 的改动可能一起没。claude rm <id> 对有未提交改动的 worktree 会更保守（打印路径让你自己清）。

6. 同场景，另外两种原语怎么嵌

主对话里还要跑一轮测试、不想堵着：

Use a subagent to run the full test suite and report only failures with stack traces.

这是 subagent，不会出现在 claude agents 表里。后台跑的是主 session 内部任务，不是新的 background session。

两块代码要并行改、还在同一会话里协调：

Spawn two subagents with isolation worktree:
one fixes the flaky test, one drafts the auth notes.
Return each worktree branch name when done.

需要三路 review 互抬杠（贵）：

先开 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，再：

Spawn three teammates to review PR #N: security, performance, tests.
Debate, then one synthesis for me.

实战建议：先用 background session 把活并行做完 → 开 PR → 必要时再用 team 做 review。别一上来 team 写代码，token 和协调成本都不友好。

7. 这一趟你应该带走的体感

claude agents 管的是完整会话，不是 subagent 列表
并行安全主要靠 worktree，不是靠模型「注意一点」
消息：列表 peek / attach 对话 / team 私信 / resume subagent——四条路
收工看 PR 号或分支，不要看「模型说做完了」就信

其它最小命令（备忘）

claude agents                 # 仪表盘
claude attach <id>            # 进某 session
claude logs <id>              # 最近输出
claude stop <id>              # 停
claude respawn <id>           # 对话还在，进程拉起来
claude --worktree feature-x   # 自己开一个隔离终端会话

自定义 subagent 仍丢 .claude/agents/*.md；要默认后台 + 隔离：

---
name: feature-dev
isolation: worktree
background: true
---

收工

Claude Code 的 agent 叙事里，真正要分清的是生命周期边界：

Subagent 活在主 session 的委托关系里
Background session 活在 supervisor 的进程树里
Agent team 活在 lead + mailbox + task list 的协作协议里
Worktree 活在 git 工作目录层

Resume、消息、隔离，每一层语义不同。先问「我需要的是摘要回流、独立会话，还是工人互聊」，再选原语。选错了不是模型笨，是你把项目经理、外包和工位隔板当成了同一个按钮。