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.

fix(wrap): make RTK opt-in (off by default) across wrap subcommands (#2344)

Tejas Chopra44136ed0427e
diff --git a/e2e/wrap/run.py b/e2e/wrap/run.py
index 32332e65d..c779b7042 100644
--- a/e2e/wrap/run.py
+++ b/e2e/wrap/run.py
@@ -953,6 +953,9 @@ def main() -> None:
"PATH": f"{shim_dir}{os.pathsep}{base_env['PATH']}",
"HEADROOM_E2E_LOG_DIR": str(log_dir),
"OPENAI_TARGET_API_URL": "http://127.0.0.1:19001/v1",
+ # RTK is opt-in (off by default). These wrap smoke tests assert
+ # RTK-instruction injection, so exercise the RTK-on path.
+ "HEADROOM_RTK": "1",
}
)
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 9dc110447..4afea9af9 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -647,8 +647,42 @@ def _start_proxy(
stdio_log_file.close()
+def _rtk_opt_in() -> bool:
+ """Whether RTK CLI-command filtering was explicitly enabled.
+
+ RTK is opt-in (off by default): turn it on with ``--rtk`` (which sets
+ ``HEADROOM_RTK=1``) or by exporting ``HEADROOM_RTK=1``. ``--no-rtk`` remains
+ accepted as a deprecated no-op.
+ """
+ return os.environ.get("HEADROOM_RTK", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _rtk_flag_callback(ctx: Any, param: Any, value: bool) -> bool:
+ """Click eager callback: ``--rtk`` sets HEADROOM_RTK so the central RTK gate
+ (:func:`_rtk_opt_in`) sees the opt-in without threading a param through every
+ wrap subcommand."""
+ if value:
+ os.environ["HEADROOM_RTK"] = "1"
+ return value
+
+
+# Shared opt-in flag applied to every ``wrap`` subcommand. ``expose_value=False``
+# so no subcommand signature changes; it works purely through HEADROOM_RTK.
+_rtk_option = click.option(
+ "--rtk",
+ is_flag=True,
+ default=False,
+ expose_value=False,
+ is_eager=True,
+ callback=_rtk_flag_callback,
+ help="Enable RTK CLI-command filtering (opt-in; off by default). Also enabled by HEADROOM_RTK=1.",
+)
+
+
def _setup_rtk(verbose: bool = False) -> Path | None:
"""Ensure rtk is installed and hooks are registered."""
+ if not _rtk_opt_in():
+ return None
from headroom.rtk import get_rtk_path
from headroom.rtk.installer import ensure_rtk, register_claude_hooks
@@ -2123,6 +2157,8 @@ def _snapshot_codex_config_if_unwrapped(config_file: Path, backup_file: Path) ->
def _ensure_rtk_binary(verbose: bool = False) -> Path | None:
"""Ensure rtk binary is installed (download if needed). No hook registration."""
+ if not _rtk_opt_in():
+ return None
from headroom.rtk import get_rtk_path
from headroom.rtk.installer import ensure_rtk
@@ -2693,6 +2729,8 @@ def _inject_rtk_instructions(file_path: Path, verbose: bool = False) -> bool:
Idempotent — skips if marker already present. Appends to existing content.
Returns True if instructions were written.
"""
+ if not _rtk_opt_in():
+ return False
if file_path.exists():
existing = _read_text(file_path)
if _RTK_MARKER in existing:
@@ -4396,6 +4434,7 @@ def wrap_selfheal(marker: str | None) -> None:
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
# no "-p" short alias here: claude's own -p/--print must fall through to CLAUDE_ARGS
"--port",
@@ -4523,7 +4562,12 @@ def claude(
headroom wrap claude --no-serena # Never register the Serena backup
headroom wrap claude --1m # Preserve the 1M context window
"""
- setup_context_tool = context_tool and not no_rtk
+ # RTK/context-tool is opt-in (off by default): --context-tool (legacy) and
+ # --rtk both enable it. Mirror --context-tool into HEADROOM_RTK so the central
+ # RTK gate (_rtk_opt_in) fires for the legacy flag too.
+ if context_tool:
+ os.environ["HEADROOM_RTK"] = "1"
+ setup_context_tool = (context_tool or _rtk_opt_in()) and not no_rtk
if prepare_only:
if setup_context_tool:
if _selected_context_tool() == _CONTEXT_TOOL_LEAN_CTX:
@@ -4936,6 +4980,7 @@ def unwrap_claude(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -5459,6 +5504,7 @@ def _run_codex_wrap(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -5577,6 +5623,7 @@ def codex(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -5681,6 +5728,7 @@ def aider(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option("--port", "-p", default=8787, type=int, help="Proxy port (default: 8787)")
@click.option(
"--no-context-tool",
@@ -5783,6 +5831,7 @@ def openclaude(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -5862,6 +5911,7 @@ def vibe(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -5949,6 +5999,7 @@ def kimi(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6092,6 +6143,7 @@ def grok(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6198,6 +6250,7 @@ def cursor(
@wrap.command("grok-build", context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6294,6 +6347,7 @@ def grok_build(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6396,6 +6450,7 @@ def cline(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6491,6 +6546,7 @@ def zcode(
@wrap.command("continue", context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6615,6 +6671,7 @@ def continue_dev(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6740,6 +6797,7 @@ def goose(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -6883,6 +6941,7 @@ def openhands(
@wrap.command("openclaw")
+@_rtk_option
@click.option(
"--plugin-path",
type=click.Path(path_type=Path, file_okay=False, dir_okay=True),
@@ -7124,6 +7183,7 @@ def openclaw(
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
@@ -7648,6 +7708,7 @@ def unwrap_codex(port: int, no_stop_proxy: bool) -> None:
@wrap.command(context_settings={"ignore_unknown_options": True})
+@_rtk_option
@click.option(
"--port", "-p", default=8787, type=click.IntRange(1, 65535), help="Proxy port (default: 8787)"
)
diff --git a/tests/test_cli/test_wrap_bridge.py b/tests/test_cli/test_wrap_bridge.py
index a3e21c91b..40e1ef0d1 100644
--- a/tests/test_cli/test_wrap_bridge.py
+++ b/tests/test_cli/test_wrap_bridge.py
@@ -164,6 +164,7 @@ def test_wrap_codex_prepare_only_accepts_no_context_tool_alias(monkeypatch, tmp_
def test_wrap_aider_prepare_only_injects_conventions(monkeypatch, tmp_path: Path) -> None:
_set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_RTK", "1") # RTK is opt-in; exercise the RTK-on path
runner = CliRunner()
with runner.isolated_filesystem(temp_dir=str(tmp_path)):
@@ -180,6 +181,7 @@ def test_wrap_cursor_prepare_only_registers_native_hook(monkeypatch, tmp_path: P
# GH #756: when rtk's own `--agent cursor` hook registers successfully,
# headroom must not also inject RTK_INSTRUCTIONS_BLOCK into .cursorrules.
_set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_RTK", "1") # RTK is opt-in; exercise the RTK-on path
runner = CliRunner()
# headroom trusts the on-disk hook, not rtk's exit code, so simulate rtk
@@ -206,6 +208,7 @@ def test_wrap_cursor_prepare_only_falls_back_to_cursorrules_when_hook_fails(
monkeypatch, tmp_path: Path
) -> None:
_set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_RTK", "1") # RTK is opt-in; exercise the RTK-on path
runner = CliRunner()
with runner.isolated_filesystem(temp_dir=str(tmp_path)):
diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.py
index 439c68f8b..0c86fd278 100644
--- a/tests/test_cli/test_wrap_codex.py
+++ b/tests/test_cli/test_wrap_codex.py
@@ -470,6 +470,7 @@ class TestInjectAndRestoreRoundTrip:
"""`wrap codex` injects the rtk block into the Codex global AGENTS.md;
`unwrap codex` must take it back out (regression for #1421)."""
_set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_RTK", "1")
codex_home = tmp_path / ".codex"
codex_home.mkdir()
agents = codex_home / "AGENTS.md"
@@ -487,6 +488,7 @@ class TestInjectAndRestoreRoundTrip:
"""Only the marker-fenced rtk block is removed; the user's own AGENTS.md
prose survives the unwrap."""
_set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_RTK", "1")
codex_home = tmp_path / ".codex"
codex_home.mkdir()
agents = codex_home / "AGENTS.md"
@@ -1275,6 +1277,7 @@ def test_wrap_codex_injects_rtk_globally_without_changing_project_agents(
runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
_set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_RTK", "1")
project_dir = tmp_path / "project"
project_dir.mkdir()
project_agents = project_dir / "AGENTS.md"
@@ -1308,6 +1311,7 @@ def test_wrap_codex_launch_injects_rtk_globally_without_changing_project_agents(
runner: CliRunner, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
_set_test_home(monkeypatch, tmp_path)
+ monkeypatch.setenv("HEADROOM_RTK", "1")
project_dir = tmp_path / "project"
project_dir.mkdir()
project_agents = project_dir / "AGENTS.md"
diff --git a/tests/test_cli/test_wrap_copilot.py b/tests/test_cli/test_wrap_copilot.py
index 033d37d73..2da75d95e 100644
--- a/tests/test_cli/test_wrap_copilot.py
+++ b/tests/test_cli/test_wrap_copilot.py
@@ -21,6 +21,12 @@ def _expected_project_prefix() -> str:
return f"/p/{quote(Path.cwd().name, safe='')}"
[email protected](autouse=True)
+def _enable_rtk(monkeypatch: pytest.MonkeyPatch) -> None:
+ # RTK is opt-in (off by default); these tests exercise the RTK-on injection path.
+ monkeypatch.setenv("HEADROOM_RTK", "1")
+
+
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
diff --git a/tests/test_cli/test_wrap_encoding.py b/tests/test_cli/test_wrap_encoding.py
index 6aa531c84..da0794294 100644
--- a/tests/test_cli/test_wrap_encoding.py
+++ b/tests/test_cli/test_wrap_encoding.py
@@ -31,7 +31,11 @@ _EXISTING = "Be in “happy places” — really.\n".encode() + b"legacy \x9d by
@pytest.mark.parametrize("inject, marker", INJECTORS)
-def test_inject_appends_into_file_with_non_ascii_and_stray_byte(inject, marker, tmp_path: Path):
+def test_inject_appends_into_file_with_non_ascii_and_stray_byte(
+ inject, marker, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ if marker == _RTK_MARKER:
+ monkeypatch.setenv("HEADROOM_RTK", "1")
target = tmp_path / "AGENTS.md"
target.write_bytes(_EXISTING)
@@ -45,7 +49,11 @@ def test_inject_appends_into_file_with_non_ascii_and_stray_byte(inject, marker,
@pytest.mark.parametrize("inject, marker", INJECTORS)
-def test_inject_creates_file_when_absent(inject, marker, tmp_path: Path):
+def test_inject_creates_file_when_absent(
+ inject, marker, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+ if marker == _RTK_MARKER:
+ monkeypatch.setenv("HEADROOM_RTK", "1")
target = tmp_path / "nested" / "AGENTS.md"
assert inject(target) is True
@@ -53,7 +61,9 @@ def test_inject_creates_file_when_absent(inject, marker, tmp_path: Path):
@pytest.mark.parametrize("inject, marker", INJECTORS)
-def test_inject_is_idempotent(inject, marker, tmp_path: Path):
+def test_inject_is_idempotent(inject, marker, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+ if marker == _RTK_MARKER:
+ monkeypatch.setenv("HEADROOM_RTK", "1")
target = tmp_path / "AGENTS.md"
target.write_bytes(_EXISTING)
diff --git a/tests/test_cli/test_wrap_hintfile_agents.py b/tests/test_cli/test_wrap_hintfile_agents.py
index d04025d0a..31e5c13c5 100644
--- a/tests/test_cli/test_wrap_hintfile_agents.py
+++ b/tests/test_cli/test_wrap_hintfile_agents.py
@@ -31,6 +31,12 @@ HINTFILE_AGENTS = [
]
[email protected](autouse=True)
+def _enable_rtk(monkeypatch: pytest.MonkeyPatch) -> None:
+ # RTK is opt-in (off by default); these tests exercise the RTK-on injection path.
+ monkeypatch.setenv("HEADROOM_RTK", "1")
+
+
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
diff --git a/tests/test_cli/test_wrap_omp.py b/tests/test_cli/test_wrap_omp.py
index 47064db02..8c0f56f4a 100644
--- a/tests/test_cli/test_wrap_omp.py
+++ b/tests/test_cli/test_wrap_omp.py
@@ -241,6 +241,7 @@ def test_wrap_omp_rtk_injects_into_cwd_agents_md(
runner: CliRunner, omp_home: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setenv("HEADROOM_CONTEXT_TOOL", "rtk")
+ monkeypatch.setenv("HEADROOM_RTK", "1")
with (
patch("headroom.cli.wrap.shutil.which", return_value="omp"),
patch("headroom.cli.wrap._launch_tool"),
@@ -260,8 +261,9 @@ def test_wrap_omp_rtk_injects_into_cwd_agents_md(
def test_unwrap_omp_restored_and_cleans_agents_md(
- runner: CliRunner, omp_home: Path, tmp_path: Path
+ runner: CliRunner, omp_home: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
+ monkeypatch.setenv("HEADROOM_RTK", "1")
original = "providers:\n anthropic:\n apiKey: sk-user-secret\n"
omp_home.write_bytes(original.encode("utf-8"))
inject_models_override(8787, "proj")
diff --git a/tests/test_cli/test_wrap_openclaude.py b/tests/test_cli/test_wrap_openclaude.py
index 6234fcba6..dd0054a60 100644
--- a/tests/test_cli/test_wrap_openclaude.py
+++ b/tests/test_cli/test_wrap_openclaude.py
@@ -24,6 +24,12 @@ def _expected_project_prefix() -> str:
return f"/p/{quote(Path.cwd().name, safe='')}"
[email protected](autouse=True)
+def _enable_rtk(monkeypatch: pytest.MonkeyPatch) -> None:
+ # RTK is opt-in (off by default); these tests exercise the RTK-on injection path.
+ monkeypatch.setenv("HEADROOM_RTK", "1")
+
+
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
diff --git a/tests/test_cli/test_wrap_opencode.py b/tests/test_cli/test_wrap_opencode.py
index b74a7d936..6eaf8d550 100644
--- a/tests/test_cli/test_wrap_opencode.py
+++ b/tests/test_cli/test_wrap_opencode.py
@@ -13,6 +13,12 @@ from headroom.cli import wrap as wrap_mod
from headroom.cli.main import main
[email protected](autouse=True)
+def _enable_rtk(monkeypatch: pytest.MonkeyPatch) -> None:
+ # RTK is opt-in (off by default); these tests exercise the RTK-on injection path.
+ monkeypatch.setenv("HEADROOM_RTK", "1")
+
+
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
diff --git a/tests/test_cli/test_wrap_zcode.py b/tests/test_cli/test_wrap_zcode.py
index 17b7a18ad..5e642df83 100644
--- a/tests/test_cli/test_wrap_zcode.py
+++ b/tests/test_cli/test_wrap_zcode.py
@@ -18,6 +18,12 @@ from headroom.cli import wrap as wrap_mod
from headroom.cli.main import main
[email protected](autouse=True)
+def _enable_rtk(monkeypatch: pytest.MonkeyPatch) -> None:
+ # RTK is opt-in (off by default); these tests exercise the RTK-on injection path.
+ monkeypatch.setenv("HEADROOM_RTK", "1")
+
+
@pytest.fixture
def runner() -> CliRunner:
return CliRunner()
diff --git a/tests/test_wrap_rtk_opt_in.py b/tests/test_wrap_rtk_opt_in.py
new file mode 100644
index 000000000..ada618abb
--- /dev/null
+++ b/tests/test_wrap_rtk_opt_in.py
@@ -0,0 +1,47 @@
+"""RTK is opt-in (off by default): enabled only via --rtk / HEADROOM_RTK=1.
+
+Regression for the RTK-default flip: the three RTK entry points must no-op
+unless explicitly opted in, and every wrap subcommand must expose --rtk.
+"""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from headroom.cli import wrap
+
+
+def _no_rtk_env() -> dict[str, str]:
+ env = dict(os.environ)
+ env.pop("HEADROOM_RTK", None)
+ return env
+
+
+def test_rtk_opt_in_off_by_default() -> None:
+ with patch.dict(os.environ, _no_rtk_env(), clear=True):
+ assert wrap._rtk_opt_in() is False
+
+
+def test_rtk_opt_in_on_via_env() -> None:
+ for val in ("1", "true", "yes", "on"):
+ with patch.dict(os.environ, {"HEADROOM_RTK": val}):
+ assert wrap._rtk_opt_in() is True
+
+
+def test_rtk_entry_points_noop_when_not_opted_in(tmp_path) -> None:
+ agents = tmp_path / "AGENTS.md"
+ with patch.dict(os.environ, _no_rtk_env(), clear=True):
+ assert wrap._setup_rtk() is None
+ assert wrap._ensure_rtk_binary() is None
+ assert wrap._inject_rtk_instructions(agents) is False
+ assert not agents.exists() # nothing written when RTK is off
+
+
+def test_rtk_flag_present_on_subcommands() -> None:
+ runner = CliRunner()
+ for tool in ("claude", "codex", "copilot", "aider", "continue"):
+ out = runner.invoke(wrap.wrap, [tool, "--help"]).output
+ assert "--rtk" in out, f"--rtk missing from `wrap {tool} --help`"