Release v0.28.0

0.28.0 (2026-06-29)

Features

• add --disable-kompress-fallback to restore legacy PASSTHROUGH fallback (#1185) (f309244)
• add first-class OpenCode support (wrap, learn, mcp install) (#559) (91cd210)
• add HEADROOM_KEEPALIVE_EXPIRY to keep upstream connections warm (#1124) (85786b3)
• azure-foundry: derive upstream URL from ANTHROPIC_FOUNDRY_RESOURCE (#1138) (e5031b0)
• cache: attribute prompt-cache misses to TTL lapse vs prefix change (#1313) (#1343) (4658721)
• code: add Perl support to code-aware compressor (#1125) (f39858c)
• headroom wrap opencode / unwrap opencode CLI (#1105) (b4571cc)
• learn: weight loops in Headroom Learn + RTK-loop eval (#1160) (14e8dc4)
• learn: write per-project learnings to CLAUDE.local.md by default (#1115) (ced75e4)
• proxy: add request timeout config (#738) (c0745d4)
• proxy: pilot hardening — inbound auth, security headers, audit log, air-gap switch (#1537) (546ab55)
• proxy: support glob patterns in exclude_tools (#870) (#1259) (a2159c0)
• read-maturation: activity-based hold-back Read maturation (Mechanism B) (#1068) (723b80c)
• savings: durable savings ledger + headroom savings command (#1127) (978ffa0)
• wrap: add --1m to preserve the 1M context window on wrap claude (#1158) (#1351) (b50d9c1)
• wrap: make tokensave the primary coding-task compressor, Serena the backup (#1230) (dca9853)

Bug Fixes

• agent-evals: Phase 0 — coding-agent accuracy A/B framework (#1037) (84f9871)
• agno: tolerate streaming tool-call SDK objects in parser (#1312) (#1336) (5986c22)
• bedrock: add boto3 1.41 + CRT for aws login credentials (#1486) (4db3bc9)
• bump codebase-memory-mcp to v0.8.1 (#1284) (530318b)
• ccr: make headroom_retrieve a hash-only full-content lookup (#1532) (c2fc4d3)
• ccr: propagate --no-ccr-marker flag to all compressors (#1022) (#1197) (0c9b42a)
• ccr: skip Anthropic marker emission when tool injection is deferred (#1273) (2cae13d)
• ci: extend gitleaks allowlist to cover test fixtures + verified examples (#1539) (d2565a6)
• ci: guarantee model present in test shards to end cache-miss flakiness (#1399) (2e29c72)
• ci: normalize Windows CRLF line endings in PR governance script (#1012) (5194388)
• cli: add explicit UTF-8 encoding to file I/O in wrap commands (#1126) (#1164) (a0cb798)
• cli: fall back gracefully when embedding-server sidecar is absent (#1206) (38f1404)
• cli: harden all CLI surfaces + fix docs accuracy (#1491) (bd76235)
• cli: wire --http2/--no-http2 (HEADROOM_HTTP2) into proxy command (#1373) (e06b616)
• cli: wire --rpm/--tpm and HEADROOM_RPM/HEADROOM_TPM to the Click proxy command (#1375) (8aab8f2)
• code: slice tree-sitter byte offsets as UTF-8 (#1332) (8238402)
• code: validate Python compressed syntax (#1302) (cbd361d)
• code: verify a real parse in tree-sitter availability check (#1231) (#1299) (5e0bb69)
• codex: retag threads on init so Codex Desktop history stays visible (#961) (#1349) (e6bbc40)
• codex: stop pinning Codex memory MCP to one project db (#1269) (ad7993b)
• dashboard: include RTK stats in the historical tab (#1324) (35939c3)
• deps: remediate dependency CVEs and publish SBOM (#1509) (5771a80)
• docker: persist session history across container revisions (#1118) (5912d65)
• gemini: offload compression to the executor (#1382) (615848e)
• gemini: resolve Google model capabilities through ModelRegistry (#1276) (17ecad9)
• install: guard install_agent_ensure against duplicate runtime spawns (#1301) (8da0b4e)
• install: repair macOS launchd restart/start lifecycle (#1290) (da1a397)
• install: stop duplicating ENTRYPOINT in persistent-docker runtime command (#833) (#1348) (feedead)
• io: use UTF-8 with locale fallback and preserve line endings on config/text I/O (#1498) (1baa04e)
• kompress: hard override keeps must-keep tokens regardless of model score (#1400) (42612c8)
• langchain: disable streaming on wrapped model during ainvoke() (#1287) (3590046)
• mcp: register managed installs with a resolvable headroom command (#1386) (22def93)
• mcp: report correct savings_percent in headroom_compress (#1106) (f216e43)
• opencode: write local MCP config (#1381) (6c83790)
• packaging: move hnswlib to optional [vector] extra so [all] needs no C++ toolchain (#1499) (80fa086)
• patch rtk hook script to use absolute path after register_claude_hooks (#571) (b618d2d)
• perf: surface RTK/CLI context-tool savings in perf and the session card (#1433) (9362747)
• proxy: add --protect-tool-results to prevent lossy compression of exact-output Bash results (#1374) (51d4bcf)
• proxy: add an Anthropic buffered read-timeout override (#1331) (3be2526)
• proxy: add versionless Vertex AI routes for Claude Code compatibility (#1321) (bb3e040)
• proxy: bind before eager preload so a hung compressor load can't block startup (#1500) (d5ac07f)
• proxy: build SSL contexts for custom CA bundles (#1134) (561ba17)
• proxy: forward request-id headers on the streaming path (#1100) (#1258) (3d59df7)
• proxy: gate CCR retrieve/compress endpoints to loopback (#1338) (acafb2d)
• proxy: honor force_kompress routing profile (#996) (b4682d6)
• proxy: keep large compression results on the critical path (#296) (#1352) (90734b6)
• proxy: offload /v1/compress to the compression executor to stop blocking the loop (#1501) (27e010e)
• proxy: preserve Responses memory continuations with store=false (#1103) (cdfeeac)
• proxy: queue mid-turn user messages on non-Bedrock streaming path (#1377) (b09f027)
• proxy: register interceptor in explicit transforms list when HEADROOM_INTERCEPT_ENABLED (#1376) (55c700c)
• proxy: report real input tokens on streaming message_start (#1132) (#1305) (70cc96a)
• proxy: retry upstream 429 with Retry-After on both forwarders (#1329) (90bee89)
• proxy: retry upstream 529 overloaded like 429 on both forwarders (#1495) (547b15d)
• proxy: stop re-compressing headroom_retrieve output and emitting unredeemable markers (#1323) (43494ff)
• proxy: strip Codex lite header from OpenAI WebSockets (#1543) (5d3803a)
• read-lifecycle: persist STALE Read originals in the CCR store (#1488) (9157173)
• recover persistent proxy feature checks and reject non-Copilot exchange URL (#1465) (16c638b)
• remove agents.md (#1540) (a7d3360)
• respect COPILOT_PROVIDER_TYPE env var when provider_type is auto (#549) (24cf256)
• restore token-mode compression on frozen prefixes (#1489) (8e0dadf)
• router: degrade to pure-Python detection on native panic (#1123) (#1260) (a00fb67)
• rtk: stop hook registration timing out on a forked daemon (#1314) (9758817)
• smart-crusher: honor enable_ccr_marker on the opaque-blob path (#1130) (27d6f8e)
• subscription: only reset 5h contribution on real rollover, not API jitter (#1255) (8d6c175)
• subscription: run transcript token scan off the event loop (#1263) (f03021f)
• surface output reduction without a restart, and explain $0.00 savings on Python 3.14 (#1296) (c30ec4c)
• tests: reset whole headroom logger subtree so caplog stays deterministic (#1117) (fda4670)
• tls: add HEADROOM_TLS_STRICT=0 toggle for corporate SSL inspection (#1308) (#1341) (52068dd)
• tokenizers: price CJK/Kana/Hangul at ~1 token per char in EstimatingTokenCounter (#1093) (a35fe86)
• transforms: gate tool string output from lossy compression (#1307) (#1387) (c6c921a)
• websocket: harden responses websocket origin handling (#1481) (c632023)
• windows: pin UTF-8 encoding on text-mode subprocess calls (#1311) (d633e81)
• wrap: add Copilot unwrap command (#1251) (b4fde0c)
• wrap: isolate proxy stdio from proxy.log on Windows (#1191) (959ab0d)
• wrap: keep agent savings opt-in (#1294) (b829ceb)
• wrap: show the dashboard URL when the proxy is already running (#1313) (b0146c4)

Performance Improvements

• compression: take large cold-start contexts off the synchronous kompress path (#1171) (#1298) (6c68ff4)