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): trim the wrap claude startup banner (#3900)

Sudhindra Desaiaba75cbf6d2f
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index a398a2f7f..001c5c230 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -96,6 +96,7 @@ from headroom.providers.claude import (
remote_control_applies_to_auth,
remote_control_gate_active,
remote_control_gate_message,
+ remote_control_gate_short_message,
remote_control_sibling_gate_note,
remove_vscode_claude_settings,
resolve_1m_model,
@@ -4728,8 +4729,7 @@ def _ensure_proxy_unlocked(
if code_graph and not running_config.get("code_graph"):
missing.append("code_graph")
if not missing:
- click.echo(f" Proxy already running on port {port}")
- click.echo(f" Dashboard: http://127.0.0.1:{port}/dashboard")
+ click.echo(_proxy_status_line("Proxy already running", port))
_warn_proxy_mode_mismatch(running_config)
return None, port
# Features mismatch or config unavailable — fall through to the
@@ -5008,8 +5008,7 @@ def _ensure_proxy_unlocked(
needs_restart = True
if not needs_restart and reuse_running:
- click.echo(f" Proxy already running on port {port}")
- click.echo(f" Dashboard: http://127.0.0.1:{port}/dashboard")
+ click.echo(_proxy_status_line("Proxy already running", port))
_warn_proxy_mode_mismatch(running_config)
return None, port
@@ -5056,8 +5055,7 @@ def _ensure_proxy_unlocked(
copilot_api_token_expires_at=copilot_api_token_expires_at,
),
)
- click.echo(f" Proxy ready on http://127.0.0.1:{actual_port}")
- click.echo(f" Dashboard: http://127.0.0.1:{actual_port}/dashboard")
+ click.echo(_proxy_status_line("Proxy ready", actual_port))
return proc, actual_port
except RuntimeError as e:
click.echo(f" Error: {e}")
@@ -5116,6 +5114,11 @@ def _proxy_start_lock(port: int) -> Any:
yield
+def _proxy_status_line(status: str, port: int) -> str:
+ """One banner line for the proxy, naming its host:port once (#3426)."""
+ return f" {status} — dashboard: http://127.0.0.1:{port}/dashboard"
+
+
@wraps(_ensure_proxy_unlocked)
def _ensure_proxy(
port: int,
@@ -6022,7 +6025,12 @@ def claude(
if remote_control_applies_to_auth(os.environ)
else None
)
- if remote_control_gate_active(proxy_url, os.environ, _cc_version):
+ _rc_gated = remote_control_gate_active(proxy_url, os.environ, _cc_version)
+ if _rc_gated and not verbose:
+ # Issue #3426: one actionable line by default; -v restores the
+ # full explanation (versions, sibling gates) below.
+ click.echo(" " + remote_control_gate_short_message(version=_cc_version))
+ elif _rc_gated:
click.echo(
" "
+ remote_control_gate_message(
@@ -6111,14 +6119,23 @@ def claude(
# Describe what the written value actually does: --tool-search
# false/0/no/off turns deferral OFF, and the banner must say so
# rather than repeat "kept on" (issue #1779 accuracy rule).
- _tool_search_state = (
- "on-demand tool loading kept on"
- if _tool_search_mode_is_active(_tool_search_value)
- else "on-demand tool loading DISABLED per your setting"
- )
- click.echo(
- f" {_TOOL_SEARCH_ENV}={_tool_search_value} ({_tool_search_state}; issue #746)"
- )
+ _tool_search_active = _tool_search_mode_is_active(_tool_search_value)
+ if verbose:
+ _tool_search_state = (
+ "on-demand tool loading kept on"
+ if _tool_search_active
+ else "on-demand tool loading DISABLED per your setting"
+ )
+ click.echo(
+ f" {_TOOL_SEARCH_ENV}={_tool_search_value} ({_tool_search_state}; issue #746)"
+ )
+ else:
+ # Issue #3426: state the outcome once; -v shows the env var and issue.
+ click.echo(
+ " On-demand tool loading: kept on (this session)"
+ if _tool_search_active
+ else " On-demand tool loading: off (this session)"
+ )
elif verbose:
click.echo(
f" {_TOOL_SEARCH_ENV}={env.get(_TOOL_SEARCH_ENV)} "
diff --git a/headroom/providers/claude/__init__.py b/headroom/providers/claude/__init__.py
index df4f338a4..af9cb0542 100644
--- a/headroom/providers/claude/__init__.py
+++ b/headroom/providers/claude/__init__.py
@@ -21,6 +21,7 @@ from .runtime import (
remote_control_applies_to_auth,
remote_control_gate_active,
remote_control_gate_message,
+ remote_control_gate_short_message,
remote_control_sibling_gate_note,
resolve_1m_model,
)
@@ -61,5 +62,6 @@ __all__ = [
"remote_control_applies_to_auth",
"remote_control_gate_active",
"remote_control_gate_message",
+ "remote_control_gate_short_message",
"remote_control_sibling_gate_note",
]
diff --git a/headroom/providers/claude/runtime.py b/headroom/providers/claude/runtime.py
index 7e4d8b4be..558170ea7 100644
--- a/headroom/providers/claude/runtime.py
+++ b/headroom/providers/claude/runtime.py
@@ -159,6 +159,24 @@ def remote_control_gate_message(source: str, *, version: tuple[int, int, int] |
)
+def remote_control_gate_short_message(*, version: tuple[int, int, int] | None = None) -> str:
+ """One-line Remote Control notice for the default ``wrap claude`` banner (#3426).
+
+ Same accuracy rule as :func:`remote_control_gate_message` (issue #1779):
+ with a known gated version state the disable as fact; with an unknown
+ version name the threshold rather than assert the user's build.
+ """
+ scope = (
+ ""
+ if version is not None and version >= REMOTE_CONTROL_GATED_MIN_VERSION
+ else f" on Claude Code {_version_str(REMOTE_CONTROL_GATED_MIN_VERSION)}+"
+ )
+ return (
+ f"{REMOTE_CONTROL_FEATURE} (/rc) is disabled{scope} while routed through "
+ "Headroom — run `claude` directly (no wrap) for sessions that need it."
+ )
+
+
def is_custom_anthropic_base_url(value: str | None) -> bool:
"""Return whether ANTHROPIC_BASE_URL is custom from Claude's Remote Control gate view.
diff --git a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
index 16c2f7172..7d7825e60 100644
--- a/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
+++ b/tests/test_cli/test_wrap_claude_vertex_proxy_env.py
@@ -129,7 +129,8 @@ def _invoke_wrap_claude(
def test_wrap_claude_plain_mode_warns_about_remote_control_gate(
runner: CliRunner, monkeypatch: pytest.MonkeyPatch
) -> None:
- captured, output = _invoke_wrap_claude(runner, monkeypatch, env={})
+ # -v restores the full #1779 explanation (#3426 made it opt-in).
+ captured, output = _invoke_wrap_claude(runner, monkeypatch, env={}, extra_args=("-v",))
assert captured["child_cmd"] == ["/usr/bin/claude"]
assert "Remote Control" in output
@@ -214,7 +215,7 @@ def test_wrap_claude_sibling_note_accurate_under_1m_and_tool_search_optouts(
runner,
monkeypatch,
env={},
- extra_args=("--1m", "--tool-search", "false"),
+ extra_args=("-v", "--1m", "--tool-search", "false"),
)
assert "already restored via --1m" in output
assert "restore with `headroom wrap claude --1m`" not in output
@@ -267,8 +268,8 @@ def test_wrap_claude_tool_search_banner_line_still_accurate_when_active(
runner: CliRunner, monkeypatch: pytest.MonkeyPatch
) -> None:
# Default session: deferral is on, and both the #746 banner line and the
- # RC sibling note say so.
- _captured, output = _invoke_wrap_claude(runner, monkeypatch, env={})
+ # RC sibling note say so (full wording under -v, #3426).
+ _captured, output = _invoke_wrap_claude(runner, monkeypatch, env={}, extra_args=("-v",))
assert "on-demand tool loading kept on" in output
assert "keeps it on for this session" in output
assert "DISABLED per your setting" not in output
@@ -289,7 +290,54 @@ def test_wrap_claude_foundry_persists_disabled_tool_search_for_workers(
assert captured["child_env"]["ENABLE_TOOL_SEARCH"] == "false"
assert captured["write_tool_search_value"] == "false"
- assert "on-demand tool loading DISABLED" in output
+ # Foundry's default turns deferral off without a --tool-search flag, so the
+ # compact line must not blame the user's setting (#3426).
+ assert "On-demand tool loading: off (this session)" in output
+ assert "kept on" not in output
+
+
+def test_wrap_claude_default_banner_is_compact(
+ runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ # Issue #3426: without -v the RC notice and the #746 line are one line each,
+ # and the long explanation / sibling note / env-var trailer are omitted.
+ _captured, output = _invoke_wrap_claude(runner, monkeypatch, env={})
+ assert (
+ "Remote Control (/rc) is disabled while routed through Headroom — run `claude` "
+ "directly (no wrap) for sessions that need it."
+ ) in output
+ assert "On-demand tool loading: kept on (this session)" in output
+ assert "Same base-URL gate" not in output
+ assert "ENABLE_TOOL_SEARCH=" not in output
+ assert "issue #746" not in output
+
+
+def test_wrap_claude_compact_tool_search_off_line(
+ runner: CliRunner, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _captured, output = _invoke_wrap_claude(
+ runner, monkeypatch, env={}, extra_args=("--tool-search", "false")
+ )
+ assert "On-demand tool loading: off (this session)" in output
+ assert "kept on" not in output
+
+
+def test_proxy_status_line_keeps_own_signature_and_names_port_once() -> None:
+ # The status helper must not inherit _ensure_proxy_unlocked's metadata via
+ # a stray @wraps; _ensure_proxy is the function that should carry it.
+ import inspect
+
+ assert wrap_mod._proxy_status_line.__name__ == "_proxy_status_line"
+ assert list(inspect.signature(wrap_mod._proxy_status_line).parameters) == [
+ "status",
+ "port",
+ ]
+ assert wrap_mod._ensure_proxy.__wrapped__ is wrap_mod._ensure_proxy_unlocked
+ assert "learn" in inspect.signature(wrap_mod._ensure_proxy).parameters
+
+ line = wrap_mod._proxy_status_line("Proxy ready", 8787)
+ assert line == " Proxy ready — dashboard: http://127.0.0.1:8787/dashboard"
+ assert line.count("127.0.0.1:8787") == 1
def test_wrap_claude_vertex_passes_custom_base_url_to_proxy_before_child_redirect(
diff --git a/tests/test_issue_1779_remote_control_gate.py b/tests/test_issue_1779_remote_control_gate.py
index a1ac9ab99..eedd948a1 100644
--- a/tests/test_issue_1779_remote_control_gate.py
+++ b/tests/test_issue_1779_remote_control_gate.py
@@ -27,6 +27,7 @@ from headroom.providers.claude.runtime import (
remote_control_applies_to_auth,
remote_control_gate_active,
remote_control_gate_message,
+ remote_control_gate_short_message,
remote_control_sibling_gate_note,
)
@@ -293,3 +294,22 @@ def test_sibling_note_does_not_advise_1m_already_passed() -> None:
)
def test_is_custom_anthropic_base_url_host_edges(value, expected) -> None:
assert is_custom_anthropic_base_url(value) is expected
+
+
+# ---------------------------------------------------------------------------
+# Compact banner line (#3426) keeps the #1779 accuracy rule
+# ---------------------------------------------------------------------------
+
+
+def test_short_message_known_gated_version_states_fact() -> None:
+ msg = remote_control_gate_short_message(version=_GATED)
+ assert msg == (
+ "Remote Control (/rc) is disabled while routed through Headroom — run `claude` "
+ "directly (no wrap) for sessions that need it."
+ )
+
+
+def test_short_message_unknown_version_states_threshold() -> None:
+ msg = remote_control_gate_short_message(version=None)
+ assert "is disabled on Claude Code 2.1.196+ while routed through Headroom" in msg
+ assert "may" not in msg