[DOCS] Agent teams docs omit the new API-error "failed" reporting and stuck-teammate wake behavior added in v2.1.198

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

• The "Teammates stopping on errors" subsection, which is the closest existing surface for this behavior
• The "Limitations" section, particularly the "Task status can lag" bullet, which is the closest surface for the wake-on-message fix

Current Documentation

The "Teammates stopping on errors" subsection currently reads:

Teammates may stop after encountering errors instead of recovering. Check their output by selecting the teammate in the agent panel and pressing Enter in in-process mode, or by clicking the pane in split mode, then either: Give them additional instructions directly Spawn a replacement teammate to continue the work

The "Limitations" section says:

* Task status can lag: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.

What's Wrong or Missing?

The release notes for v2.1.198 describe two related fixes:

Fixed agent teams: a teammate that dies on an API error now reports "failed" to the lead, and messaging a stuck teammate wakes it to retry immediately

Neither the failure-reporting behavior nor the wake-on-message behavior is in the docs. The closest related content ("Teammates may stop after encountering errors...") describes the old, less specific behavior and gives no recovery path besides manually giving instructions or spawning a replacement. The "Limitations" bullet about stuck tasks still describes the workaround the new behavior replaces (telling the lead to nudge the teammate).

Suggested Improvement

Extend "Teammates stopping on errors" to describe the new reporting and recovery behavior:

Before:

Teammates may stop after encountering errors instead of recovering. Check their output by selecting the teammate in the agent panel and pressing Enter in in-process mode, or by clicking the pane in split mode, then either: Give them additional instructions directly Spawn a replacement teammate to continue the work

After:

Teammates may stop after encountering errors instead of recovering. As of v2.1.198, a teammate that fails on an API error reports its state as "failed" to the lead, and sending any message to a stuck teammate wakes it to retry immediately, so you usually do not need to spawn a replacement. Check the teammate's output by selecting it in the agent panel and pressing Enter in in-process mode, or by clicking the pane in split mode. From there you can: Give it additional instructions directly, which resumes it if it is stuck Spawn a replacement teammate to take over the work

Update the "Task status can lag" bullet in "Limitations" so it notes that sending a message to the teammate now wakes it, removing the "tell the lead to nudge the teammate" workaround:

Before:

* Task status can lag: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.

After:

* Task status can lag: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually. As of v2.1.198, sending a message to the stuck teammate also wakes it to retry, so a manual nudge from the lead is no longer the only recovery path.

Impact

Medium - Makes feature difficult to understand

Additional Context

Related v2.1.198 change:

Fixed agent teams: a teammate that dies on an API error now reports "failed" to the lead, and messaging a stuck teammate wakes it to retry immediately

The agent-teams limitations page is the only existing surface in the docs where this behavior would naturally live; no other documentation page currently explains it.

Affected Pages:

| Page | Context |
|---|---|
| https://code.claude.com/docs/en/agent-teams | "Teammates stopping on errors" subsection and "Limitations" bullet about stuck tasks |