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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(wrap): keep Claude context-tool setup explicit (#1999)
Rod Boevf536aa0801af
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2726bb43e..c1541f99a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -35,6 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0* **cache/semantic:** key entries by the full-context hash, not the trailing query text. `SemanticCache.put` stored each response under `sha256(query)[:16]` where `query` is only the last user message, and the exact-match branch of `get` returned the slot without checking the stored entry's `messages_hash`. Two requests that share a trailing message ("continue", "yes", "run the tests") but differ in earlier context therefore collided on one slot — the second overwrote the first, and the first's hash then resolved to the second's cached response (wrong data served). Entries are now keyed by `messages_hash` when present, and `get` verifies `entry.messages_hash` before returning.* **proxy/openai:** stop PRE_SEND from reintroducing `tools: []` after the direct #728 fix. The OpenAI request handler now mirrors the existing `tools or _original_tools is not None` body-write guard during PRE_SEND write-back, so providers that reject empty tool arrays no longer see a tools field when the client omitted it, while explicit client `tools: []` remains preserved ([#1983](https://github.com/headroomlabs-ai/headroom/issues/1983)).* **proxy/openai:** keep the exact Responses function name `terminal` resident during OpenAI tool-search deferral so cache-mode optimization stops forwarding `terminal.terminal` and triggering the reserved-namespace 400 on Codex Responses ([#1946](https://github.com/headroomlabs-ai/headroom/issues/1946)).+* **wrap:** `headroom wrap claude` no longer installs RTK or lean-ctx by default. Claude context-tool setup is now explicit via `--context-tool`, `--no-context-tool` remains accepted, and other wrap commands keep their current defaults ([#1915](https://github.com/headroomlabs-ai/headroom/issues/1915)).* **proxy/openai:** thread the savings-profile kwargs into the live `/v1/chat/completions` compression path. The chat handler called `openai_pipeline.apply()` without `proxy_pipeline_kwargs(config)`, so `HEADROOM_SAVINGS_PROFILE=agent-90` (and the individual `compress_user_messages`/`target_ratio`/`min_tokens_to_compress`/... knobs) were silently dropped — OpenAI-compatible clients like OpenCode kept protecting user messages and missed the configured profile. Both the token-mode and non-token chat branches now pass the profile kwargs, matching `handlers/anthropic.py` and the dedicated OpenAI compress endpoint ([#1534](https://github.com/headroomlabs-ai/headroom/issues/1534)).* **proxy:** forward Codex Desktop `/v1/responses` posts byte-faithfully so they stop returning upstream `400 {"detail":"Bad Request"}`. `handle_openai_responses` decoded the inbound body to inspect it but always re-serialized a canonical body on the way out, and it never stripped the inbound `content-encoding` header — so a `content-encoding: zstd` Codex Desktop request was forwarded as already-decoded JSON still advertising `zstd`, and the upstream ChatGPT Codex endpoint rejected it. The handler now keeps the original decoded bytes and forwards them verbatim whenever nothing (compression or memory injection) mutated the request, and drops the stale `content-encoding` header, mirroring the byte-faithful passthrough the chat and Anthropic paths already use ([#1542](https://github.com/headroomlabs-ai/headroom/issues/1542)).* **wrap/codex:** `headroom unwrap codex` now removes the Headroom rtk instruction block from the Codex global `AGENTS.md`. `wrap codex` injects it there, but unwrap only restored `config.toml` and MCP state, so a plain `codex` launch kept following the "prefix shell commands with `rtk`" guidance and failed once the managed rtk binary was off PATH. Unwrap now strips the marker-fenced block (preserving the rest of the file), mirroring `unwrap copilot` ([#1421](https://github.com/headroomlabs-ai/headroom/issues/1421)).diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex fd89f0c75..f7506e3f8 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -3755,6 +3755,12 @@ def unwrap() -> None:is_flag=True,help="Skip CLI context-tool setup",)+ "--context-tool",+ "context_tool",+ is_flag=True,+ help="Enable CLI context-tool setup",+)@click.option("--no-mcp",is_flag=True,@@ -3824,6 +3830,7 @@ def unwrap() -> None:def claude(port: int,no_rtk: bool,+ context_tool: bool,no_mcp: bool,no_tokensave: bool,serena: bool,@@ -3855,13 +3862,15 @@ def claude(headroom wrap claude # tokensave code graph (primary)headroom wrap claude --no-tokensave # Skip tokensave; fall back to Serenaheadroom wrap claude --serena # Also register the Serena backup+ headroom wrap claude --context-tool # Enable CLI context-tool setupheadroom wrap claude --no-context-tool # Skip CLI context-tool setupheadroom wrap claude --no-mcp # Skip MCP retrieve tool registrationheadroom wrap claude --no-serena # Never register the Serena backupheadroom wrap claude --1m # Preserve the 1M context window"""+ setup_context_tool = context_tool and not no_rtkif prepare_only:- if not no_rtk:+ if setup_context_tool:if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:_setup_lean_ctx_agent("claude", verbose=verbose)else:@@ -3984,7 +3993,7 @@ def claude(port_holder[0] = actual_port_push_runtime_env(actual_port, no_proxy)- if not no_rtk:+ if setup_context_tool:if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:click.echo(" Setting up lean-ctx...")_setup_lean_ctx_agent("claude", verbose=verbose)diff --git a/tests/test_cli/test_wrap_bridge.py b/tests/test_cli/test_wrap_bridge.pyindex 00542037e..c160ae3e0 100644--- a/tests/test_cli/test_wrap_bridge.py+++ b/tests/test_cli/test_wrap_bridge.py@@ -32,7 +32,7 @@ def test_wrap_claude_prepare_only_skips_host_binary_lookup() -> None:with patch("headroom.cli.wrap._prepare_wrap_rtk") as prepare_rtk:with patch("headroom.cli.wrap.shutil.which") as which_mock:- result = runner.invoke(main, ["wrap", "claude", "--prepare-only"])+ result = runner.invoke(main, ["wrap", "claude", "--prepare-only", "--context-tool"])assert result.exit_code == 0, result.outputprepare_rtk.assert_called_once()@@ -48,7 +48,7 @@ def test_wrap_claude_prepare_only_uses_lean_ctx_when_configured(monkeypatch) ->"headroom.cli.wrap._setup_lean_ctx_agent",return_value=Path("lean-ctx"),) as setup:- result = runner.invoke(main, ["wrap", "claude", "--prepare-only"])+ result = runner.invoke(main, ["wrap", "claude", "--prepare-only", "--context-tool"])assert result.exit_code == 0, result.outputprepare_rtk.assert_not_called()diff --git a/tests/test_cli/test_wrap_helpers.py b/tests/test_cli/test_wrap_helpers.pyindex 2173d9d42..68de4d098 100644--- a/tests/test_cli/test_wrap_helpers.py+++ b/tests/test_cli/test_wrap_helpers.py@@ -19,6 +19,7 @@ import subprocessimport sysfrom pathlib import Pathfrom typing import Any+from unittest.mock import patchimport clickimport pytest@@ -26,6 +27,7 @@ from click.testing import CliRunnerfrom headroom import paths as paths_modfrom headroom.cli import wrap as wrap_mod+from headroom.cli.main import main# ---------------------------------------------------------------------------# _print_wrap_banner — centering math + box drawing.@@ -104,6 +106,72 @@ def test_print_wrap_banner_title_is_centered_or_near_centered() -> None:# ---------------------------------------------------------------------------+def test_claude_context_tool_is_opt_in_for_prepare_only(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Claude skips context-tool setup unless the positive flag is passed."""+ monkeypatch.delenv("HEADROOM_CONTEXT_TOOL", raising=False)+ runner = CliRunner()++ with patch.object(wrap_mod, "_prepare_wrap_rtk") as prepare_rtk:+ default = runner.invoke(main, ["wrap", "claude", "--prepare-only"])+ opt_in = runner.invoke(main, ["wrap", "claude", "--prepare-only", "--context-tool"])++ assert default.exit_code == 0, default.output+ assert opt_in.exit_code == 0, opt_in.output+ assert prepare_rtk.call_count == 1+++def test_claude_context_tool_opt_in_preserves_lean_ctx_selection(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The positive flag enables the configured lean-ctx installer."""+ monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")+ runner = CliRunner()++ with patch.object(wrap_mod, "_setup_lean_ctx_agent") as setup_lean_ctx:+ result = runner.invoke(main, ["wrap", "claude", "--prepare-only", "--context-tool"])++ assert result.exit_code == 0, result.output+ setup_lean_ctx.assert_called_once_with("claude", verbose=False)+++def test_claude_no_context_tool_wins_over_context_tool(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """The legacy opt-out remains authoritative when both flags are supplied."""+ runner = CliRunner()++ with patch.object(wrap_mod, "_prepare_wrap_rtk") as prepare_rtk:+ result = runner.invoke(+ main,+ ["wrap", "claude", "--prepare-only", "--context-tool", "--no-context-tool"],+ )++ assert result.exit_code == 0, result.output+ prepare_rtk.assert_not_called()+++def test_non_claude_context_tool_setup_remains_default(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ """Copilot still sets up RTK without a new positive opt-in flag."""+ monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-test-dummy")++ with (+ patch.object(wrap_mod.shutil, "which", return_value="copilot"),+ patch.object(wrap_mod, "_ensure_rtk_binary", return_value=Path("/tmp/rtk")) as ensure_rtk,+ patch.object(wrap_mod, "_launch_tool"),+ ):+ result = CliRunner().invoke(+ main,+ ["wrap", "copilot", "--no-proxy", "--", "--model", "claude-sonnet-4-20250514"],+ )++ assert result.exit_code == 0, result.output+ ensure_rtk.assert_called_once_with(verbose=False)++def test_setup_context_tool_lean_ctx_calls_lean_ctx_setup(monkeypatch: pytest.MonkeyPatch) -> None:"""When HEADROOM_CONTEXT_TOOL=lean-ctx, helper calls _setup_lean_ctx_agent."""monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "lean-ctx")