[DOCS] Agent view attach/detach docs omit the WSL + Windows Terminal stale/garbled frame that was fixed in v2.1.169

Documentation Type

Other: Platform-specific known-issue / changelog-fix note missing from the user-facing page

Documentation Location

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

Section/Topic

The "Attach and detach" step in the Quick start (around the "Press ← on an empty prompt to detach and return to the table" line) and the "Limitations" section at the end of the page. Both are the right surfaces for the WSL + Windows Terminal caveat, and neither currently mentions the platform-specific render bug that was fixed in v2.1.169.

Current Documentation

The Quick start says:

## Quick start <Step title="Attach and detach"> Press Enter or → on a row to attach when you want the full conversation. The session takes over the terminal as a full interactive Claude Code session. Press ← on an empty prompt to detach and return to the table. </Step>

The Limitations section at the bottom of the page says:

## Limitations Agent view is in research preview with the following limitations: Rate limits apply: background sessions consume your subscription usage the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one. Sessions are local: background sessions run on your machine. They are preserved across sleep but stop if the machine shuts down. * Claude-created worktrees are deleted with the session in agent view: merge or push changes before deleting a session that edited files in its own worktree. claude rm keeps a worktree that has uncommitted changes; a worktree you created yourself is left in place.

The v2.1.169 release notes call out the fix specifically:

* Fixed agents view leaving a stale/garbled frame after navigating back from an agent on WSL in Windows Terminal

Neither the agent-view page nor the Limitations section cross-references that release note or mentions the WSL + Windows Terminal combination, so users who hit the same symptom (or who want to confirm they are on a version that includes the fix) have nothing to point at.

What's Wrong or Missing?

A. No mention of the WSL + Windows Terminal render-state bug in the "Attach and detach" step

The Quick-start step that teaches ← to navigate back from an attached agent is the exact interaction the v2.1.169 fix targets, but the page does not say "on WSL inside Windows Terminal, a stale/garbled frame could appear after pressing ← — fixed in v2.1.169" or anything equivalent. Users running Claude Code inside WSL via Windows Terminal have no warning, and post-fix users have no breadcrumb to confirm their symptom matches a known-and-fixed issue.

B. The "Limitations" section is missing a platform-specific caveats bullet

The Limitations list currently covers rate limits, local-only hosting, and worktree cleanup. It does not call out that the attach/detach loop has historically had renderer-edge issues on specific terminal/host combinations (Windows Terminal, WSL in Windows Terminal, CJK content) and that v2.1.169 resolves one of those. Other Windows-Terminal-specific fixes (stale-fragment scrolling in attached background sessions, ghost characters with CJK, full-screen strobing) appear in the changelog but are not surfaced on the user-facing page either, which leaves Windows-Terminal users guessing whether they are on a broken configuration or a known issue.

C. No version anchor for the fix

The v2.1.169 changelog entry is the only place the WSL + Windows Terminal stale-frame fix is recorded. The agent-view page does not pin the fix to a version, and the page does not currently say "requires Claude Code v2.1.139 or later" relative to WSL/Windows Terminal behavior, so users on older v2.1.x builds inside WSL cannot tell from the docs that they need to upgrade to clear the symptom.

Suggested Improvement

Option A: Minimum fix (recommended)

Add one bullet to the Limitations section calling out the platform-specific caveat and the version that resolves it, and one parenthetical in the Quick-start "Attach and detach" step.

In the Limitations section, after the existing three bullets, add:

* Renderer edges on Windows Terminal and WSL: the attach/detach loop has had platform-specific render bugs (stale or garbled frames after pressing ←, ghost characters with wide/CJK content, full-screen strobing in attached background sessions). Most of these are fixed as of v2.1.169; if you see them on an older build, upgrade with claude update or reinstall the native Windows installer.

In the Quick-start "Attach and detach" Step, expand the ← sentence to:

Press ← on an empty prompt to detach and return to the table. On WSL inside Windows Terminal, builds older than v2.1.169 could leave a stale/garbled frame in the table area after detaching; upgrade to v2.1.169 or later to clear it.

Option B: Comprehensive fix

In addition to Option A, add a short "Platform notes" subsection (between "Troubleshooting" and "Limitations") with a table of known attach/detach and background-session render issues keyed to the version that resolved each, e.g.:

### Platform notes Renderer behavior in agent view and attached background sessions depends on the host terminal. The following combinations have had documented issues that were fixed in specific releases: | Host | Symptom | Fixed in | |----------------------------------------------|----------------------------------------------------------------------|----------| | Windows Terminal, WSL inside Windows Terminal | Stale or garbled frame in the agent view table after detaching | v2.1.169 | | Windows Terminal | Stale fragments while scrolling in an attached background session | v2.1.150 | | Windows Terminal with CJK content | Ghost characters at the left edge when switching panes | v2.1.146 | | Windows Terminal | Full-screen strobing while Claude streams | v2.1.144 | | Windows Terminal and WSL | Right-click paste in claude agents failing | v2.1.146 |

This keeps the WSL + Windows Terminal story in one discoverable place and gives Windows-Terminal users a version-based upgrade path for each symptom.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-view | 60-61 | "Attach and detach" Quick-start step that documents pressing ← to return to the table |
| https://code.claude.com/docs/en/agent-view | 547-553 | "Limitations" section — missing a platform-specific caveat bullet |
| https://code.claude.com/docs/en/changelog | 26 | v2.1.169 entry that records the WSL + Windows Terminal stale-frame fix |
| https://code.claude.com/docs/en/terminal-config | 28 | Terminal support matrix that lists Windows Terminal as a supported host without calling out the WSL caveat |

Total scope: 4 pages touched (1 primary, 3 cross-references).

Version numbers where behavior differs: The stale/garbled frame after ← from an attached agent on WSL inside Windows Terminal is fixed in v2.1.169. Earlier v2.1.x builds inside that host combination are expected to still show the symptom.

Related changelog entries documenting the broader Windows-Terminal render story (for context, not as duplicate issue targets):

• v2.1.146: ghost characters at the left edge when switching panes in Agent View on Windows Terminal with CJK content
• v2.1.144: full-screen strobing in attached background sessions on Windows Terminal while Claude is streaming
• v2.1.150: stale-fragment rendering when scrolling in attached background sessions on Windows Terminal
• v2.1.146: right-click paste in claude agents on Windows Terminal and WSL

These adjacent fixes support the "platform notes" table in Option B above and confirm that Windows Terminal + WSL is a recurring render edge case worth surfacing on the agent-view page rather than only in the changelog.