[DOCS] Attached background sessions ignored `CLAUDE_CODE_DISABLE_MOUSE` and `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` opt-outs before v2.1.203

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/fullscreen

Section/Topic

• The "Mouse handling" / native-selection paragraphs (around lines 184-194) that introduce CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS.
• The trailing "Background sessions opened from agent view or claude attach" paragraph (line 204) that lists which TUI controls and environment variables apply to attached background sessions.
• The matching CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS rows in the env-vars reference.
• The "Version history" table at the bottom of agent-view.md, which is missing a v2.1.203 row.

Current Documentation

From fullscreen.md, the closing paragraph of the "Mouse handling" / native-selection section:

Background sessions opened from agent view or claude attach always use fullscreen rendering. The attaching terminal enters the alternate screen buffer to show the session, and the classic renderer has no scrollback or mouse handling there, so the tui setting and CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN don't apply to them.

The same page introduces the opt-outs a few lines earlier without any background-session qualifier:

If you rely on native selection all the time, set CLAUDE_CODE_DISABLE_MOUSE=1 to opt out of mouse capture while keeping the flicker-free rendering and flat memory:

To keep wheel scrolling but turn off click, drag, and hover handling, set CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1 instead. Requires Claude Code v2.1.195 or later. CLAUDE_CODE_DISABLE_MOUSE takes precedence when both variables are set.

The env-vars reference rows are similarly generic about where the variables apply:

CLAUDE_CODE_DISABLE_MOUSE — Set to 1 to disable mouse tracking in fullscreen rendering. Keyboard scrolling with PgUp and PgDn still works. Use this to keep your terminal's native copy-on-select behavior CLAUDE_CODE_DISABLE_MOUSE_CLICKS — {/ min-version: 2.1.195 /}Set to 1 to disable click, drag, and hover handling in fullscreen rendering while keeping mouse-wheel scrolling. Use this when you want wheel scroll to work inside Claude Code but don't want clicks to position the cursor, expand tool output, or open links. CLAUDE_CODE_DISABLE_MOUSE takes precedence when both are set. Requires Claude Code v2.1.195 or later

The agent-view.md version history table ends at v2.1.202 and has no row for v2.1.203.

What's Wrong or Missing?

A. The "Background sessions … always use fullscreen rendering" sentence hides the v2.1.203 fix

The v2.1.203 changelog says:

Fixed attached background sessions ignoring CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS opt-outs

Before v2.1.203, attached background sessions (whether entered via claude agents → Enter on a row, or claude attach <id>) silently bypassed both mouse-opt-out variables, even though the rest of the fullscreen docs treat them as standard opt-outs. The closing paragraph of the "Mouse handling" section on fullscreen.md is the natural place where a reader learns that an environment variable is or is not honored for attached sessions. It names tui and CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN explicitly but says nothing about CLAUDE_CODE_DISABLE_MOUSE or CLAUDE_CODE_DISABLE_MOUSE_CLICKS, so:

• A user reading only the env-vars row sees a generic "in fullscreen rendering" description and reasonably expects both variables to work everywhere fullscreen rendering is on.
• A user reading the closing "Background sessions" paragraph sees CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN mentioned by name as a variable that does not apply to attached sessions, but no parallel note for the two mouse-opt-out variables. The natural inference is that those two variables do apply, but in practice they did not.

After v2.1.203 the inference is finally correct, but the docs never say so.

B. The env-vars rows do not document the attached-session contract

Both rows describe the variables in terms of "fullscreen rendering" without distinguishing between foreground fullscreen and the attached-session fullscreen buffer. The CLAUDE_CODE_DISABLE_MOUSE row predates attached background sessions and never received a v2.1.203 note. The CLAUDE_CODE_DISABLE_MOUSE_CLICKS row only carries a {/* min-version: 2.1.195 */} marker for the variable's introduction; nothing on it tells the reader that attached background sessions were ignoring it until v2.1.203.

A user who relies on these variables to keep terminal-native mouse behavior in their main session has no way to learn from the docs that, until v2.1.203, the same export had no effect when they later opened claude agents and attached to a session.

C. agent-view.md "Version history" table is missing a v2.1.203 row

The "Version history" table at the bottom of agent-view.md is the per-page summary of agent-view-related changes. It currently lists v2.1.202 (last) and v2.1.200 / v2.1.199 / v2.1.198 below it. The mouse-opt-out fix is a behavior change that lands in the same surface (attached background sessions rendering) and so should have a v2.1.203 row, in the same {/* min-version: 2.1.203 */} format used by the rest of the table. Without it, a reader who looks only at the version history table will not see that attached sessions now honor the mouse-opt-out variables.

Suggested Improvement

On https://code.claude.com/docs/en/fullscreen — extend the closing "Background sessions" paragraph so that the two mouse-opt-out variables are explicitly listed as applying to attached sessions, in the same shape as the existing CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN note:

Before:

Background sessions opened from agent view or claude attach always use fullscreen rendering. The attaching terminal enters the alternate screen buffer to show the session, and the classic renderer has no scrollback or mouse handling there, so the tui setting and CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN don't apply to them.

After:

Background sessions opened from agent view or claude attach always use fullscreen rendering. The attaching terminal enters the alternate screen buffer to show the session, and the classic renderer has no scrollback or mouse handling there, so the tui setting and CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN don't apply to them. {/ min-version: 2.1.203 /}As of v2.1.203, CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS are honored by attached sessions, so the same export you use in your normal terminal keeps terminal-native selection and click behavior when you attach to a background session.

On https://code.claude.com/docs/en/env-vars — add a {/* min-version: 2.1.203 */} note to both rows stating that the variable now applies to attached background sessions:

Before (on the CLAUDE_CODE_DISABLE_MOUSE row):

Set to 1 to disable mouse tracking in fullscreen rendering. Keyboard scrolling with PgUp and PgDn still works. Use this to keep your terminal's native copy-on-select behavior

After:

{/ min-version: 2.1.203 /}Set to 1 to disable mouse tracking in fullscreen rendering, including in attached background sessions. Keyboard scrolling with PgUp and PgDn still works. Use this to keep your terminal's native copy-on-select behavior

And similarly append "including in attached background sessions" to the CLAUDE_CODE_DISABLE_MOUSE_CLICKS row, keeping its existing v2.1.195 marker.

On https://code.claude.com/docs/en/agent-view — add a row to the "Version history" table above v2.1.202:

Before (top of the version-history table):

| v2.1.202 | {/ min-version: 2.1.202 /}A name set with /rename or Ctrl+R on a background session persists when the supervisor stops and restarts its process, instead of reverting to the name the session was dispatched with. |

After (new row above v2.1.202):

| v2.1.203 | {/ min-version: 2.1.203 /}Attached background sessions opened from agent view or claude attach honor CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS, so the same exports you use in your normal terminal keep terminal-native mouse and click behavior when you attach. |

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/fullscreen | 184-194 | "Mouse handling" / native-selection paragraphs introducing CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS |
| https://code.claude.com/docs/en/fullscreen | 204 | Closing paragraph that lists which TUI controls and environment variables apply to attached background sessions |
| https://code.claude.com/docs/en/env-vars | 187-188 | CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS rows in the env-vars reference |
| https://code.claude.com/docs/en/agent-view | 654-656 | "Version history" table at the bottom of the page, missing a v2.1.203 row |

Total scope: 3 pages affected (fullscreen, env-vars, agent-view).

The changelog entry the docs should reflect is:

Fixed attached background sessions ignoring CLAUDE_CODE_DISABLE_MOUSE and CLAUDE_CODE_DISABLE_MOUSE_CLICKS opt-outs

The two variables were introduced in v2.0.0 (CLAUDE_CODE_DISABLE_MOUSE) and v2.1.195 (CLAUDE_CODE_DISABLE_MOUSE_CLICKS). Attached-background-session rendering exists since agent view shipped, so the silent-bypass window has been open since each variable's introduction; v2.1.203 closes it for both.