fix: document false-positive update banner and add update-checker plugin (#18047)

[SebTardif]

Summary

Addresses #18047 — the "Update available!" banner fires for Homebrew and WinGet users even when no update is available, because Claude Code checks the npm registry regardless of installation method.

This affects users across macOS, Windows, and Linux/WSL (see also #33155, #41947, #44773, #46550, #47900).

Changes

1. README.md — Known Issues section

• Root cause explanation (npm registry vs package-manager version lag)
• Per-platform verification commands (brew info, winget list, npm outdated)
• DISABLE_AUTOUPDATER=1 workaround with both temporary and persistent examples (bash + PowerShell)
• Note that the banner auto-resolves once registries catch up

2. plugins/update-checker — new SessionStart hook plugin

A lightweight plugin that detects the actual installation method and checks the correct package source:

Method	Detection	Version source
Homebrew	brew info --cask claude-code	Homebrew cask formula
WinGet	winget show	WinGet manifest
npm	npm view	npm registry

At session start it injects accurate update context, e.g.:

Update check (homebrew): Claude Code 2.1.73 is the latest version available via homebrew. If you see an "Update available" banner it is a false positive caused by the npm registry being ahead of your package manager.

Testing

• Script syntax validated (bash -n)
• Tested on WSL with both Homebrew and WinGet accessible — correctly prioritizes Homebrew
• Version comparison verified for equal, newer, and older version cases
• All JSON files validated

Related issues

• [BUG] Update available text displays even when fully updated #18047 (original)
• Update notification always shown for winget installations due to npm version check #33155, [BUG] "Update available" banner shows when already on the latest version #41947, [Bug] Update notification appears when no update is available #44773, [BUG] False "Update available!" prompt persists after updating on Windows (winget release lag) #46550, [Bug] WinGet update notification shows before package is available in repository #47900 (duplicates across platforms)
• Feature request: Allow customization of update reminder notification #46220 (feature request: customizable notification)
• Misleading 'Update available' message for Homebrew users #49590 (closed — confirms npm-vs-brew root cause)