feat(hud): smart context bar visualization (Wave 2-E)

Replaces the plain "Ctx:42%" text with a compact visual progress
bar so users can see context-window usage at a glance:

  [████░░░░░░] 42%        (safe, low usage)
  [███████░░░] 73%        (approaching danger)
  [█████████▓] 92%⚠       (critical — full bar + warning glyph)

Two visual signals distinguish the danger zones:
1. Dark glyph (▓) replaces the trailing full block at the danger
   threshold (85%) so "almost full" looks different from "full".
2. ⚠ suffix appended at the warning threshold (80%) — survives
   monochrome / greyscale renders.

New lib/hud_context_bar.py:
- CONTEXT_BAR_WIDTH = 10 cells (~10% resolution per cell)
- CONTEXT_BAR_THRESHOLDS = (80, 85, 95)  # warning, danger, critical
- _clamp_percentage(pct): defensive float coercion with [0, 100] clamp
- render_context_bar(used_pct, *, width): core renderer
- format_context_bar_segment(stdin_data): Claude Code stdin extractor

29 new tests cover:
- Basic shape (0/50/100 pct)
- Rounding (banker's round-half-to-even for 5/15/95)
- Warning/danger threshold boundaries (inclusive)
- Clamping (negative, >100, None, non-numeric, numeric string)
- Custom width (20, 0, 1)
- Segment extractor (empty, missing context_window, missing
  used_percentage, normal render, zero)
- Constants (width, threshold ordering)

158/158 pass.

Part of #1464 (Wave 0 statusbar refactor)

Author: JeremyDev87

packages/claude-code-plugin/hooks/lib/hud_context_bar.py

@@ -1,15 +1,136 @@
-"""Smart context bar visualization for CodingBuddy statusLine (#1326).
+"""Smart context bar visualization for CodingBuddy statusLine (#1326, Wave 2-E).
 
-Wave 0 skeleton — reserved for **Wave 2-E**.
+Renders the context-window usage percentage as a compact visual
+progress bar so users can see at a glance how close they are to
+overflow:
 
-Planned contents (Wave 2-E owner fills):
-    * ``CONTEXT_BAR_WIDTH: int`` — segment count
-    * ``CONTEXT_BAR_THRESHOLDS: tuple[float, float, float]`` — warning
-      / danger / critical cut-offs
-    * ``render_context_bar(used_tokens: int, total_tokens: int) -> str``
+    ``[████░░░░░░] 42%``         (safe — low usage)
+    ``[███████░░░] 73%``         (warning — approaching the danger zone)
+    ``[█████████▓] 92%⚠``        (critical — near exhaustion)
 
-Wave 2-E will render the bar from the ``context`` payload already
-parsed in ``codingbuddy-hud``. This file is a reserved import target
-so Wave 3 integration can depend on ``hud_context_bar`` without
-creating the module mid-merge.
+Primary entry point: :func:`render_context_bar`.
+
+The bar width is :data:`CONTEXT_BAR_WIDTH` (10 cells by default),
+chosen to keep the status line compact while still providing
+meaningful resolution (each cell represents ~10% of the budget).
+
+Thresholds (:data:`CONTEXT_BAR_THRESHOLDS`) drive two visual
+signals:
+
+1. A dark-shade glyph (``▓``) replaces the trailing full block when
+   usage crosses the *danger* threshold — so the last cell pulses
+   visually even when the bar looks otherwise full.
+2. A ``⚠`` suffix is appended when usage crosses the *warning*
+   threshold — a distinct text marker that survives greyscale /
+   monochrome renders.
 """
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+# ------------------------------------------------------------------------
+# Constants
+# ------------------------------------------------------------------------
+
+#: Number of cells in the rendered bar. 10 gives ~10% resolution per cell.
+CONTEXT_BAR_WIDTH: int = 10
+
+#: (warning, danger, critical) thresholds as percentages.
+#:
+#: * ``warning``  (80) — append a ``⚠`` suffix
+#: * ``danger``   (85) — replace the trailing full block with ``▓``
+#: * ``critical`` (95) — both signals always active
+CONTEXT_BAR_THRESHOLDS: Tuple[float, float, float] = (80.0, 85.0, 95.0)
+
+# Block-drawing glyphs
+_FULL = "\u2588"   # █
+_EMPTY = "\u2591"  # ░
+_DARK = "\u2593"   # ▓
+
+# Warning suffix
+_WARN = "\u26a0"  # ⚠
+
+
+def _clamp_percentage(pct: Any) -> float:
+    """Coerce an arbitrary value to a percentage in ``[0.0, 100.0]``.
+
+    Non-numeric inputs return ``0.0``. Values above 100 are capped
+    at 100; values below 0 are floored at 0.
+    """
+    try:
+        value = float(pct)
+    except (TypeError, ValueError):
+        return 0.0
+    if value < 0.0:
+        return 0.0
+    if value > 100.0:
+        return 100.0
+    return value
+
+
+def render_context_bar(
+    used_pct: Any,
+    *,
+    width: int = CONTEXT_BAR_WIDTH,
+) -> str:
+    """Render a context-bar string from a usage percentage.
+
+    Output format:
+
+        ``[<bar>] <N>%[⚠]``
+
+    The bar contains ``width`` cells; each cell represents
+    ``100 / width`` percent. The number of filled cells is
+    ``round(used_pct / 100 * width)``. When usage crosses the
+    danger threshold, the last full block becomes ``▓`` to make
+    the "full" state visually distinct from a true max. When usage
+    crosses the warning threshold, a trailing ``⚠`` is appended.
+
+    Args:
+        used_pct: Context-window usage percentage (0-100).
+            Accepts ``int``/``float``/numeric string. Non-numeric
+            input renders as ``0%``.
+        width: Override the bar cell count (tests / layout tuning).
+
+    Returns an empty string when ``width <= 0``.
+    """
+    if width <= 0:
+        return ""
+
+    pct = _clamp_percentage(used_pct)
+    warning, danger, _critical = CONTEXT_BAR_THRESHOLDS
+
+    # Number of filled cells (rounded for UX — 5% fills half a cell).
+    filled = int(round(pct / 100.0 * width))
+    if filled < 0:
+        filled = 0
+    if filled > width:
+        filled = width
+
+    # Build the bar
+    bar_cells = [_FULL] * filled + [_EMPTY] * (width - filled)
+
+    # Danger glyph replaces the trailing full block
+    if pct >= danger and filled > 0:
+        bar_cells[filled - 1] = _DARK
+
+    bar = "".join(bar_cells)
+    suffix = _WARN if pct >= warning else ""
+    return f"[{bar}] {pct:.0f}%{suffix}"
+
+
+def format_context_bar_segment(stdin_data: Dict[str, Any]) -> str:
+    """Render the context bar from a Claude Code stdin payload.
+
+    Extracts ``context_window.used_percentage`` and forwards to
+    :func:`render_context_bar`. Returns an empty string when the
+    field is absent — callers can append the result conditionally
+    without surrounding logic.
+    """
+    if not stdin_data:
+        return ""
+    ctx = stdin_data.get("context_window") or {}
+    pct = ctx.get("used_percentage")
+    if pct is None:
+        return ""
+    return render_context_bar(pct)

packages/claude-code-plugin/tests/test_hud_context_bar.py

@@ -1,4 +1,4 @@
-"""Skeleton sanity for hud_context_bar — Wave 2-E placeholder (#1463)."""
+"""Behavior tests for hud_context_bar (Wave 2-E / #1326)."""
 import os
 import sys
 
@@ -9,7 +9,205 @@
     if _p not in sys.path:
         sys.path.insert(0, _p)
 
+import hud_context_bar  # noqa: E402
 
-def test_module_loads():
-    """Contract: hud_context_bar must be importable. Wave 2-E will add real assertions."""
-    import hud_context_bar  # noqa: F401
+_FULL = "\u2588"
+_EMPTY = "\u2591"
+_DARK = "\u2593"
+_WARN = "\u26a0"
+
+
+# --------------------------- render_context_bar: basic shape --------------
+
+
+def test_zero_percent_all_empty():
+    result = hud_context_bar.render_context_bar(0)
+    assert _FULL not in result
+    assert _EMPTY * hud_context_bar.CONTEXT_BAR_WIDTH in result
+    assert "0%" in result
+
+
+def test_fifty_percent_half_filled():
+    result = hud_context_bar.render_context_bar(50)
+    # 50% of 10 cells = 5 filled
+    assert _FULL * 5 in result
+    assert _EMPTY * 5 in result
+    assert "50%" in result
+
+
+def test_hundred_percent_all_filled():
+    """100% shows the full bar but also danger glyph + warning suffix."""
+    result = hud_context_bar.render_context_bar(100)
+    # Danger glyph replaces last cell
+    assert _DARK in result
+    # And warning suffix
+    assert _WARN in result
+    assert "100%" in result
+
+
+# --------------------------- shape: format --------------------------------
+
+
+def test_output_has_bracket_wrapper():
+    result = hud_context_bar.render_context_bar(42)
+    assert result.startswith("[")
+    assert "] " in result
+
+
+def test_output_shows_percent_symbol():
+    result = hud_context_bar.render_context_bar(42)
+    assert "42%" in result
+
+
+# --------------------------- rounding -------------------------------------
+
+
+def test_rounding_nearest_5pct_fills_half_cell():
+    """5% rounds up to 1 filled cell (round-half-to-even)."""
+    result = hud_context_bar.render_context_bar(5)
+    # filled = round(5/100 * 10) = round(0.5) = 0 (banker's rounding)
+    # So 0 full cells expected.
+    assert _FULL not in result
+
+
+def test_rounding_15pct_fills_2_cells():
+    """15% → 1.5 → rounds to 2 (banker's rounding to even)."""
+    result = hud_context_bar.render_context_bar(15)
+    assert _FULL * 2 in result
+
+
+def test_rounding_95pct_fills_10_with_danger():
+    result = hud_context_bar.render_context_bar(95)
+    # filled = round(9.5) = 10 (banker's) → full bar with danger glyph
+    assert result.count(_FULL) + result.count(_DARK) == 10
+    assert _DARK in result
+    assert _WARN in result
+
+
+# --------------------------- warning / danger thresholds ------------------
+
+
+def test_below_warning_no_suffix():
+    result = hud_context_bar.render_context_bar(50)
+    assert _WARN not in result
+
+
+def test_at_warning_threshold_adds_suffix():
+    """80% is the warning threshold (inclusive)."""
+    result = hud_context_bar.render_context_bar(80)
+    assert _WARN in result
+
+
+def test_above_warning_has_suffix():
+    result = hud_context_bar.render_context_bar(85)
+    assert _WARN in result
+
+
+def test_below_danger_no_dark_glyph():
+    result = hud_context_bar.render_context_bar(80)
+    # 80 is warning but below danger (85) → no dark glyph
+    assert _DARK not in result
+
+
+def test_at_danger_threshold_has_dark_glyph():
+    """85% is the danger threshold (inclusive)."""
+    result = hud_context_bar.render_context_bar(85)
+    assert _DARK in result
+
+
+def test_above_danger_has_dark_glyph():
+    result = hud_context_bar.render_context_bar(92)
+    assert _DARK in result
+
+
+# --------------------------- clamping -------------------------------------
+
+
+def test_negative_clamped_to_zero():
+    result = hud_context_bar.render_context_bar(-50)
+    assert "0%" in result
+    assert _FULL not in result
+
+
+def test_above_100_clamped_to_100():
+    result = hud_context_bar.render_context_bar(150)
+    assert "100%" in result
+
+
+def test_non_numeric_treated_as_zero():
+    result = hud_context_bar.render_context_bar("abc")
+    assert "0%" in result
+
+
+def test_none_treated_as_zero():
+    result = hud_context_bar.render_context_bar(None)
+    assert "0%" in result
+
+
+def test_numeric_string_accepted():
+    result = hud_context_bar.render_context_bar("42")
+    assert "42%" in result
+
+
+# --------------------------- custom width ---------------------------------
+
+
+def test_custom_width_20():
+    result = hud_context_bar.render_context_bar(50, width=20)
+    # 50% of 20 = 10 filled
+    assert _FULL * 10 in result
+
+
+def test_width_zero_returns_empty():
+    assert hud_context_bar.render_context_bar(50, width=0) == ""
+
+
+def test_width_one_minimal_bar():
+    """Width 1 is a degenerate but valid case."""
+    result = hud_context_bar.render_context_bar(100, width=1)
+    assert "[" in result
+    assert "]" in result
+    assert "100%" in result
+
+
+# --------------------------- format_context_bar_segment -------------------
+
+
+def test_segment_empty_stdin():
+    assert hud_context_bar.format_context_bar_segment({}) == ""
+
+
+def test_segment_no_context_window():
+    assert hud_context_bar.format_context_bar_segment({"cost": {}}) == ""
+
+
+def test_segment_missing_used_percentage():
+    stdin = {"context_window": {"total_tokens": 1000}}
+    assert hud_context_bar.format_context_bar_segment(stdin) == ""
+
+
+def test_segment_normal_render():
+    stdin = {"context_window": {"used_percentage": 42}}
+    result = hud_context_bar.format_context_bar_segment(stdin)
+    assert "42%" in result
+    assert "[" in result
+
+
+def test_segment_zero_renders():
+    """Zero percent still renders (not same as missing)."""
+    stdin = {"context_window": {"used_percentage": 0}}
+    result = hud_context_bar.format_context_bar_segment(stdin)
+    assert "0%" in result
+
+
+# --------------------------- constants ------------------------------------
+
+
+def test_context_bar_width_default():
+    assert hud_context_bar.CONTEXT_BAR_WIDTH == 10
+
+
+def test_thresholds_ordered():
+    """warning ≤ danger ≤ critical."""
+    w, d, c = hud_context_bar.CONTEXT_BAR_THRESHOLDS
+    assert w <= d <= c