feat(hud): cache savings badge (Wave 2-C)

Claude API's prompt caching discounts cache_read_input_tokens by
90%. This module quantifies that saving so the HUD can surface
"💰$4.56 saved" as a badge appended to the cost segment.

New lib/hud_cache_savings.py:
- compute_cache_savings(cache_read_tokens, model_id) -> float
  Pure arithmetic helper with defensive coercion for malformed input.
- format_cache_savings(stdin_data) -> str
  End-to-end renderer that reads Claude Code stdin, extracts
  cache_read_input_tokens and model.id, returns "💰$N.NN saved"
  or "" below the $0.01 noise floor.
- Known model families: haiku ($0.80/M), sonnet ($3/M), opus ($15/M).
  Unknown models fall back to sonnet-tier pricing (conservative).

26 new tests in test_hud_cache_savings.py cover:
- All 3 model families + unknown + empty
- Case-insensitive matching
- Zero / negative / non-numeric / numeric-string inputs
- Empty stdin / missing context_window / missing current_usage
- Below $0.01 noise floor
- display_name fallback when model.id is absent
- Two-decimal formatting

Part of #1464 (Wave 0 statusbar refactor)

Author: JeremyDev87

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

@@ -1,14 +1,119 @@
-"""Cache-savings badge for CodingBuddy statusLine (#1326).
+"""Cache savings calculator for CodingBuddy statusLine (#1326, Wave 2-C).
 
-Wave 0 skeleton — reserved for **Wave 2-C**.
+Claude API's prompt caching charges ``cache_read_input_tokens`` at
+10% of the base input price — a 90% discount. This module quantifies
+that discount so the HUD can surface "how much you saved by caching"
+as a badge like ``"💰$4.56 saved"`` appended to the cost segment.
 
-Planned contents (Wave 2-C owner fills):
-    * ``compute_cache_savings(cost_breakdown: dict) -> float`` — USD
-      avoided by cache hits
-    * ``format_cache_savings_badge(savings_usd: float) -> str``
+Primary entry points:
 
-Source of truth for the computation is the stdin ``cost`` payload
-(cached-input vs non-cached-input token counts combined with
-``MODEL_PRICING`` — both already available in ``codingbuddy-hud``).
-This module will be the single import target for Wave 3 assembly.
+- :func:`compute_cache_savings` — pure arithmetic helper (tokens +
+  model_id → dollars saved).
+- :func:`format_cache_savings` — end-to-end renderer that reads
+  Claude Code stdin, extracts the relevant fields, and returns the
+  formatted badge string (or ``""`` when there is nothing to show).
 """
+from __future__ import annotations
+
+from typing import Any, Dict
+
+# Money glyph — U+1F4B0 money bag emoji
+_MONEY_GLYPH: str = "\U0001f4b0"  # 💰
+
+# cache_read tokens cost 10% of the input price, so the per-token
+# savings equals 90% of the input price.
+_CACHE_DISCOUNT: float = 0.90
+
+# Minimum dollar savings required to show the badge. Hides noise
+# below one cent so the status bar does not flicker on tiny reads.
+_MIN_DISPLAY_USD: float = 0.01
+
+# Baseline input prices in USD per million tokens. Mirrors the
+# ``MODEL_PRICING`` table in ``codingbuddy-hud.py``.
+_INPUT_PRICE_PER_M: Dict[str, float] = {
+    "haiku": 0.80,
+    "sonnet": 3.00,
+    "opus": 15.00,
+}
+
+# Sonnet as the safe default when the model family cannot be
+# identified. Avoids over-claiming savings on unknown tiers.
+_DEFAULT_INPUT_PRICE_PER_M: float = 3.00
+
+
+def _input_price_per_million(model_id: str) -> float:
+    """Return the baseline input price (USD per million tokens).
+
+    Case-insensitive substring match against the known family keys.
+    Falls back to the sonnet tier when no key matches.
+    """
+    if not model_id:
+        return _DEFAULT_INPUT_PRICE_PER_M
+    lowered = model_id.lower()
+    for key, price in _INPUT_PRICE_PER_M.items():
+        if key in lowered:
+            return price
+    return _DEFAULT_INPUT_PRICE_PER_M
+
+
+def compute_cache_savings(
+    cache_read_tokens: Any,
+    model_id: str,
+) -> float:
+    """Return the dollar amount saved by cache reads.
+
+    Formula::
+
+        savings = cache_read_tokens * (input_price / 1_000_000) * 0.90
+
+    Defensive coercion: negative or non-numeric inputs return
+    ``0.0`` so callers never render a "saved -$0.12" surprise when
+    upstream payloads are malformed.
+    """
+    try:
+        tokens = int(cache_read_tokens)
+    except (TypeError, ValueError):
+        return 0.0
+    if tokens <= 0:
+        return 0.0
+    price = _input_price_per_million(model_id)
+    return (tokens / 1_000_000.0) * price * _CACHE_DISCOUNT
+
+
+def format_cache_savings(stdin_data: Dict[str, Any]) -> str:
+    """Render the cache savings badge from a stdin payload.
+
+    Output format:
+
+        ``💰$4.56 saved``
+
+    Returns an empty string when any of the following hold:
+
+    * ``stdin_data`` is empty or has no ``context_window``
+    * ``current_usage`` is missing
+    * ``cache_read_input_tokens`` is zero, absent, or negative
+    * Computed savings < ``$0.01`` (noise floor)
+
+    Model identification is sourced from ``stdin_data.model.id``
+    (or ``display_name`` fallback). Unknown models default to the
+    sonnet-tier input price so the display still shows a
+    conservative estimate.
+    """
+    if not stdin_data:
+        return ""
+
+    ctx = stdin_data.get("context_window") or {}
+    usage = ctx.get("current_usage") or {}
+    cache_read = usage.get("cache_read_input_tokens", 0) or 0
+
+    if not cache_read or (isinstance(cache_read, (int, float)) and cache_read <= 0):
+        return ""
+
+    model_info = stdin_data.get("model") or {}
+    model_id = model_info.get("id") or model_info.get("display_name") or ""
+
+    savings = compute_cache_savings(cache_read, model_id)
+    if savings < _MIN_DISPLAY_USD:
+        return ""
+
+    return f"{_MONEY_GLYPH}${savings:.2f} saved"

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

@@ -1,4 +1,4 @@
-"""Skeleton sanity for hud_cache_savings — Wave 2-C placeholder (#1463)."""
+"""Behavior tests for hud_cache_savings (Wave 2-C / #1326)."""
 import os
 import sys
 
@@ -9,7 +9,202 @@
     if _p not in sys.path:
         sys.path.insert(0, _p)
 
+import hud_cache_savings  # noqa: E402
 
-def test_module_loads():
-    """Contract: hud_cache_savings must be importable. Wave 2-C will add real assertions."""
-    import hud_cache_savings  # noqa: F401
+_MONEY = "\U0001f4b0"  # 💰
+
+
+# --------------------------- _input_price_per_million ----------------------
+
+
+def test_input_price_haiku():
+    assert hud_cache_savings._input_price_per_million("claude-haiku-4-5") == 0.80
+
+
+def test_input_price_sonnet():
+    assert hud_cache_savings._input_price_per_million("claude-sonnet-4-6") == 3.00
+
+
+def test_input_price_opus():
+    assert hud_cache_savings._input_price_per_million("claude-opus-4-6") == 15.00
+
+
+def test_input_price_unknown_defaults_to_sonnet():
+    assert hud_cache_savings._input_price_per_million("gpt-4") == 3.00
+
+
+def test_input_price_empty_defaults():
+    assert hud_cache_savings._input_price_per_million("") == 3.00
+
+
+def test_input_price_case_insensitive():
+    assert hud_cache_savings._input_price_per_million("CLAUDE-OPUS-4") == 15.00
+
+
+# --------------------------- compute_cache_savings ------------------------
+
+
+def test_compute_zero_tokens_returns_zero():
+    assert hud_cache_savings.compute_cache_savings(0, "opus") == 0.0
+
+
+def test_compute_negative_tokens_returns_zero():
+    assert hud_cache_savings.compute_cache_savings(-100, "opus") == 0.0
+
+
+def test_compute_non_numeric_returns_zero():
+    assert hud_cache_savings.compute_cache_savings("abc", "opus") == 0.0
+    assert hud_cache_savings.compute_cache_savings(None, "opus") == 0.0
+
+
+def test_compute_opus_savings():
+    """1M cache_read tokens on opus → 1M * $15/M * 0.9 = $13.50 saved."""
+    result = hud_cache_savings.compute_cache_savings(1_000_000, "claude-opus")
+    assert abs(result - 13.50) < 0.001
+
+
+def test_compute_sonnet_savings():
+    """1M cache_read tokens on sonnet → 1M * $3/M * 0.9 = $2.70 saved."""
+    result = hud_cache_savings.compute_cache_savings(1_000_000, "claude-sonnet")
+    assert abs(result - 2.70) < 0.001
+
+
+def test_compute_haiku_savings():
+    """1M cache_read tokens on haiku → 1M * $0.80/M * 0.9 = $0.72 saved."""
+    result = hud_cache_savings.compute_cache_savings(1_000_000, "claude-haiku")
+    assert abs(result - 0.72) < 0.001
+
+
+def test_compute_scales_linearly():
+    """Double the tokens → double the savings."""
+    a = hud_cache_savings.compute_cache_savings(100_000, "opus")
+    b = hud_cache_savings.compute_cache_savings(200_000, "opus")
+    assert abs(b - 2 * a) < 0.001
+
+
+def test_compute_numeric_string_accepted():
+    """Numeric string coerced via int()."""
+    result = hud_cache_savings.compute_cache_savings("500000", "sonnet")
+    assert result > 0
+
+
+# --------------------------- format_cache_savings -------------------------
+
+
+def test_format_empty_stdin_returns_empty():
+    assert hud_cache_savings.format_cache_savings({}) == ""
+
+
+def test_format_no_context_window_returns_empty():
+    assert hud_cache_savings.format_cache_savings({"cost": {}}) == ""
+
+
+def test_format_no_current_usage_returns_empty():
+    stdin = {"context_window": {}}
+    assert hud_cache_savings.format_cache_savings(stdin) == ""
+
+
+def test_format_zero_cache_read_returns_empty():
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": 0}
+        }
+    }
+    assert hud_cache_savings.format_cache_savings(stdin) == ""
+
+
+def test_format_missing_cache_read_returns_empty():
+    stdin = {
+        "context_window": {
+            "current_usage": {"input_tokens": 1000}
+        }
+    }
+    assert hud_cache_savings.format_cache_savings(stdin) == ""
+
+
+def test_format_below_one_cent_returns_empty():
+    """Tiny savings (< $0.01) are hidden to avoid flicker."""
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": 100}
+        },
+        "model": {"id": "claude-sonnet"},
+    }
+    # 100 tokens * $3/M * 0.9 = $0.00027 → below threshold
+    result = hud_cache_savings.format_cache_savings(stdin)
+    assert result == ""
+
+
+def test_format_meaningful_savings_opus():
+    """500K cache_read tokens on opus → $6.75 saved."""
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": 500_000}
+        },
+        "model": {"id": "claude-opus-4-6"},
+    }
+    result = hud_cache_savings.format_cache_savings(stdin)
+    assert result.startswith(_MONEY)
+    assert "6.75" in result
+    assert "saved" in result
+
+
+def test_format_uses_display_name_fallback():
+    """When model.id is empty, fall back to display_name for pricing."""
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": 1_000_000}
+        },
+        "model": {"display_name": "Opus 4.6"},
+    }
+    result = hud_cache_savings.format_cache_savings(stdin)
+    assert "13.50" in result
+
+
+def test_format_unknown_model_uses_sonnet_default():
+    """Unknown model → sonnet-tier pricing ($2.70 per 1M tokens)."""
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": 1_000_000}
+        },
+        "model": {"id": "some-unknown"},
+    }
+    result = hud_cache_savings.format_cache_savings(stdin)
+    assert "2.70" in result
+
+
+def test_format_uses_money_glyph():
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": 1_000_000}
+        },
+        "model": {"id": "opus"},
+    }
+    result = hud_cache_savings.format_cache_savings(stdin)
+    assert result.startswith(_MONEY)
+
+
+def test_format_two_decimal_places():
+    """Output always has 2 decimal places."""
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": 100_000}
+        },
+        "model": {"id": "opus"},
+    }
+    result = hud_cache_savings.format_cache_savings(stdin)
+    # Should look like "💰$1.35 saved"
+    import re
+
+    assert re.search(r"\$\d+\.\d{2} saved", result)
+
+
+def test_format_negative_tokens_returns_empty():
+    """Malformed payload with negative cache_read is silently skipped."""
+    stdin = {
+        "context_window": {
+            "current_usage": {"cache_read_input_tokens": -500}
+        },
+        "model": {"id": "opus"},
+    }
+    assert hud_cache_savings.format_cache_savings(stdin) == ""