[DOCS] Subagent docs missing 10-minute stall timeout and failure behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

"Run subagents in foreground or background" and related background-task status guidance

Current Documentation

The docs currently say:

Subagents can run in the foreground (blocking) or background (concurrent): Foreground subagents block the main conversation until complete. Permission prompts and clarifying questions (like AskUserQuestion) are passed through to you. Background subagents run concurrently while you continue working. Before launching, Claude Code prompts for any tool permissions the subagent will need, ensuring it has the necessary approvals upfront. Once running, the subagent inherits these permissions and auto-denies anything not pre-approved. If a background subagent needs to ask clarifying questions, that tool call fails but the subagent continues. If a background subagent fails due to missing permissions, you can start a new foreground subagent with the same task to retry with interactive prompts.

And the Desktop docs say:

The tasks pane shows the background work running inside the current session: subagents, background shell commands, and workflows. Open it from the Views menu or drag it into your layout. Click any entry to see its output in the subagent pane or stop it.

What's Wrong or Missing?

Changelog v2.1.113 says: "Subagents that stall mid-stream now fail with a clear error after 10 minutes instead of hanging silently."

That behavior is not documented on the subagents page or in the task-management surfaces those docs point users to. The current docs mention permission-related failures, but they do not explain:

A. Automatic stall timeout

Stalled subagents now have a 10-minute failure threshold instead of waiting indefinitely.

B. How the failure surfaces

Users are not told that the stalled subagent now transitions to a failed state with a clear error instead of appearing hung.

C. Troubleshooting expectations

Someone watching a stuck subagent or checking /tasks has no documentation telling them whether they should keep waiting, retry in the foreground, or expect an automatic failure.

Suggested Improvement

Add a short note in https://code.claude.com/docs/en/sub-agents under "Run subagents in foreground or background" that explains:

If a subagent stalls mid-stream, Claude Code now fails it with a clear error after 10 minutes instead of leaving it running indefinitely.

Also add a brief troubleshooting note that says where this failure appears (for example, in the task/subagent output view and failed task state) and that retrying in the foreground is the right next step when more visibility or interaction is needed.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/sub-agents | Foreground/background subagent behavior and current failure guidance |
| https://code.claude.com/docs/en/desktop | Tasks pane instructions for viewing subagent output/status |
| https://code.claude.com/docs/en/commands | /tasks command entry for managing background tasks |
| https://code.claude.com/docs/en/agent-sdk/typescript | SDKTaskNotificationMessage describes failed background-task status for subagents |

Total scope: 4 pages affected

Source: Changelog v2.1.113

Exact changelog entry: "Subagents that stall mid-stream now fail with a clear error after 10 minutes instead of hanging silently"