[DOCS] Statusline docs omit footer-hint (e.g. "esc to interrupt") interaction with a custom status line, and voice-dictation page describes the pre-v2.1.169 behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

1. https://code.claude.com/docs/en/statusline — the "How status lines work" section and the "Troubleshooting" section. The page does not describe how a custom status line interacts with built-in footer hints such as "esc to interrupt" while Claude is processing.
2. https://code.claude.com/docs/en/voice-dictation — the "Enable voice dictation" / "Hold to record" lead-in paragraph, which still states the pre-fix rule that voice-dictation hints are suppressed when a custom status line is configured.

Current Documentation

The v2.1.169 changelog entry to which this issue is tied:

"Fixed footer hints (e.g. \"esc to interrupt\") not showing for users with a custom statusline"

Current statusline.md ("How status lines work" → "What your script can output" area, and the "Troubleshooting" section) describes when the status line runs and what it can output, but never describes the relationship between a custom status line and Claude Code's built-in footer hints. The only UI-hiding note on the page is:

"The status line runs locally and does not consume API tokens. It temporarily hides during certain UI interactions, including autocomplete suggestions, the help menu, and permission prompts."

Current voice-dictation.md (line 56, "Enable voice dictation" lead-in) explicitly says the dictation hint is hidden when a custom status line is configured:

"While voice dictation is enabled, the input footer shows a hold Space to speak hint when the prompt is empty. The hint reflects your current voice:pushToTalk binding and updates if you [rebind the dictation key](#rebind-the-dictation-key). The hint text is the same in both modes, and it does not appear if you have a custom status line configured."

That statement is the pre-v2.1.169 behavior the v2.1.169 fix targets (a broader class of footer hints that includes the "hold Space to speak" hint and the "esc to interrupt" hint).

What's Wrong or Missing?

A. The statusline page never explains footer-hint coexistence

The statusline docs explain the data flow, the JSON fields, the available options, and detailed troubleshooting, but they never mention that a custom status line shares its bottom row with built-in footer hints such as "esc to interrupt" while Claude is processing, "hold Space to speak" while voice dictation is enabled, and the various context-low / MCP-error transient indicators described in the "Notifications share the status line row" troubleshooting item. The v2.1.169 fix demonstrates that this coexistence is part of the contract for a custom status line, so the page should call it out (and should mention the v2.1.169 fix in a "version" note or under "Troubleshooting").

B. The voice-dictation page describes pre-v2.1.169 behavior

voice-dictation.md line 56 still says the hold Space to speak hint "does not appear if you have a custom status line configured." The v2.1.169 fix generalized the rule for the "esc to interrupt" hint and the same fix unblocks the voice-dictation hint. After the fix, the dictation hint should appear even with a custom status line, so the parenthetical is now incorrect.

C. The "Troubleshooting" section does not list this case

The statusline troubleshooting list includes "Status line not appearing", "Status line shows -- or empty values", "Context percentage shows unexpected values", "OSC 8 links not clickable", "Display glitches with escape sequences", "Workspace trust required", "Script errors or hangs", and "Notifications share the status line row", but it does not call out the "esc to interrupt" / footer-hint visibility rule that v2.1.169 just changed. A user on an older build who hides their statusline and relies on the footer for keyboard hints has no documentation entry to look at.

Suggested Improvement

A. Add a "Coexistence with built-in footer hints" subsection to the statusline page

In https://code.claude.com/docs/en/statusline under "How status lines work" (or as a new "UI coexistence" subsection), add a paragraph such as:

"Your custom status line shares the bottom of the interface with Claude Code's built-in footer hints, such as the esc to interrupt hint shown while Claude is processing and the hold Space to speak hint shown when voice dictation is enabled. As of v2.1.169 these hints appear in addition to your status line output. On narrow terminals the hints may truncate your status line, as noted in Notifications share the status line row below."

B. Update the voice-dictation paragraph

In https://code.claude.com/docs/en/voice-dictation line 56, change:

"The hint text is the same in both modes, and it does not appear if you have a custom status line configured."

to:

"The hint text is the same in both modes, and it appears in addition to your custom status line output as of v2.1.169. On narrow terminals the hint may truncate your status line output."

C. Add a troubleshooting entry

Under "Troubleshooting" in statusline.md, add:

"esc to interrupt (or other) footer hint is missing with a custom status line Footer hints such as esc to interrupt, hold Space to speak, and the context-low / MCP-error transient notifications are rendered alongside your status line output as of v2.1.169. On older builds, a custom status line suppressed the esc to interrupt hint; upgrade to v2.1.169 or later to see it again. On narrow terminals the hint may truncate your status line output. Shorten your status line output or raise padding to keep both visible."

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/statusline | 9, 131–151, 1083–1087 | Statusline page describes how the script runs but does not document the coexistence with built-in footer hints, and the "Troubleshooting" section does not cover the v2.1.169 footer-hint fix |
| https://code.claude.com/docs/en/voice-dictation | 56 | Paragraph still states the dictation hint is hidden when a custom status line is configured, which is the pre-v2.1.169 behavior the v2.1.169 changelog entry generalizes |
| https://code.claude.com/docs/en/changelog | 23 | The v2.1.169 changelog entry itself is fine; the gap is that the entry has no companion "see also" pointer into the statusline and voice-dictation docs |

Total scope: 2 documentation pages need updates to reflect the v2.1.169 footer-hint fix, plus 1 cross-reference in the statusline page.

Cross-references:

• https://code.claude.com/docs/en/keybindings documents the app:interrupt (Ctrl+C) and the Footer action context, but does not mention the esc to interrupt hint row that v2.1.169 now shows alongside a custom status line; the same coexistence paragraph could be referenced from there as well.
• https://code.claude.com/docs/en/interactive-mode line 39 documents Esc → "Interrupt Claude" but does not mention the on-screen hint or its interaction with a custom status line.

Version reference: The v2.1.169 changelog entry is the source of the behavior change. The fix was labeled as restoring the esc to interrupt hint specifically; the same fix unblocks the broader class of footer hints (including the voice-dictation hold Space to speak hint) that share the bottom row with a custom status line.