Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

docs(proxy): document --protect-tool-results side effect on protect_recent_reads_fraction (#2054)

GUOHAO LIU8322677ddd8a
diff --git a/headroom/cli/proxy.py b/headroom/cli/proxy.py
index 5d0c8aeb5..0c60c5da4 100644
--- a/headroom/cli/proxy.py
+++ b/headroom/cli/proxy.py
@@ -285,6 +285,10 @@ def dashboard(port: int, no_open: bool) -> None:
help=(
"Comma-separated tool names whose results are never lossy-compressed, "
"merged with the built-in defaults (e.g. Bash,WebFetch). "
+ "In token mode, this also resets protect_recent_reads_fraction "
+ "from 0.3 (only recent ~30% of results protected) to 0.0 (all "
+ "results protected indefinitely), which prevents older Read/Glob/"
+ "Grep/Write/Edit tool results from being silently compressed. "
"Env: HEADROOM_PROTECT_TOOL_RESULTS."
),
)
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index e8d929bcd..275915947 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -761,6 +761,11 @@ class HeadroomProxy(
if is_token_mode(config.mode):
router_config.protect_recent_reads_fraction = 0.3
router_config.search_group_by_file = True
+ # Note: protect_tool_results runs AFTER token mode (ordering matters).
+ # It resets protect_recent_reads_fraction from 0.3→0.0, restoring
+ # full protection for ALL excluded-tool results regardless of age.
+ # This means naming any tool with --protect-tool-results also
+ # protects Read/Glob/Grep/Write/Edit results indefinitely.
if config.protect_tool_results:
router_config.protect_recent_reads_fraction = 0.0
# `--compress-user-messages` flips the router's default skip rule.