[DOCS] [Agent teams] Teammate background-task lifetime across turns is undocumented

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-teams

Section/Topic

Talk to teammates directly, Context and communication, and the teammate lifecycle wording around when a teammate "finishes and stops".

Current Documentation

The agent teams docs currently say:

Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.

And later:

Idle notifications: when a teammate finishes and stops, they automatically notify the lead.

The generic background-task docs say:

When Claude Code runs a command in the background, it runs the command asynchronously and immediately returns a background task ID. Claude Code can respond to new prompts while the command continues executing in the background. * Background tasks are automatically cleaned up when Claude Code exits

What's Wrong or Missing?

Claude Code v2.1.183 includes this fix:

Fixed background tasks started by a teammate being killed when the teammate finishes a turn

That behavior is not documented in the agent teams guide.

A. No teammate-specific background-task lifecycle

The agent teams page says teammates are full Claude Code sessions, but it never states that a teammate can start background work and keep it alive after the teammate's foreground turn ends. That is a meaningful capability for long-running teammate workflows such as tests, builds, or research subagents.

B. "finishes and stops" is too coarse once background work exists

The current idle-notification wording collapses several states together. After the v2.1.183 fix, a teammate can finish its visible turn while background work is still running, so the docs should distinguish between:

1. the foreground turn ending
2. the teammate session still being alive because background work continues
3. the teammate session actually stopping

C. No guidance for inspecting or stopping teammate background work

The docs do not tell readers whether teammate-started background work is managed the same way as background work in a regular session, for example by re-entering the teammate session and checking /tasks. Without that guidance, it is hard to use or troubleshoot the fixed behavior intentionally.

Suggested Improvement

Add a short note to agent-teams.md, ideally near Talk to teammates directly or Context and communication, such as:

Teammates support the same background-task features as a regular Claude Code session. If a teammate backgrounds a shell command or subagent, that work stays attached to the teammate session after the foreground turn ends. The teammate should not be treated as fully stopped until that background work finishes or is explicitly stopped.

Also add a short operator note that explains how to inspect or stop that work, with a cross-reference to the background-task and /tasks guidance.

Finally, tighten the idle-notification wording so it distinguishes turn completion from actual session shutdown.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-teams | 155-158, 256-263 | Teammates are described as full sessions, and idle notifications are described, but there is no background-task lifecycle guidance for teammates |
| https://code.claude.com/docs/en/interactive-mode | 245-259 | Generic background-task lifecycle is documented here, but not connected back to teammate sessions |
| https://code.claude.com/docs/en/agents | 51-53 | /tasks is documented as the way to inspect background work in the current session, but the agent teams guide does not point readers to it |

Total scope: 3 pages affected

Version: Claude Code v2.1.183 fixes background tasks started by a teammate being killed when the teammate finishes a turn.