fix(wrap): trim the wrap claude startup banner (#3900)

## Description

Implements the three banner cleanups from #3426. Routing, tool-search
and Remote Control behavior are unchanged; this only changes what the
banner prints.

1. **`127.0.0.1:<port>` repetition.** The "Proxy ready/already running
on …" line and the `Dashboard:` line are now one line that names
host:port once: `Proxy ready — dashboard:
http://127.0.0.1:8787/dashboard`. This applies to all three
`_ensure_proxy` sites. `ANTHROPIC_BASE_URL=…` stays, since it's what the
session actually uses.
2. **Remote Control notice.** By default this is now one actionable
line. It keeps the #1779 accuracy rule: it states the disable as fact
for a detected gated version, and names the `2.1.196+` threshold when
the version is unknown. `-v` restores the full explanation and the
session-accurate #746/#1158 sibling note.
3. **On-demand tool loading line.** By default this prints `On-demand
tool loading: kept on (this session)` or `… off (this session)`. `-v`
restores `ENABLE_TOOL_SEARCH=… (…; issue #746)`. The compact "off"
wording doesn't say "per your setting", because Foundry turns deferral
off by default without any `--tool-search` flag.

Closes #3426

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/providers/claude/runtime.py`: new
`remote_control_gate_short_message(version=...)`, which follows the same
version-accuracy rule as `remote_control_gate_message`. It's exported
from `headroom.providers.claude`.
- `headroom/cli/wrap.py`: new `_proxy_status_line()` used at the three
proxy status sites. `wrap claude` prints the compact RC and tool-search
lines unless `-v`/`--verbose` is set, in which case it prints the
existing full lines unchanged.
- Tests: the existing full-wording assertions in
`test_wrap_claude_vertex_proxy_env.py` now run with `-v`. New tests
cover the compact default banner, the compact "off" line (including
Foundry's default-off), and both short-message version branches in
`test_issue_1779_remote_control_gate.py`. `doctor` still uses the full
message and is untouched.

## Testing

- [x] Unit tests pass (`pytest`), with one unrelated failure noted below
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`): not run successfully. My
local mypy stops on an unrelated numpy stub syntax error in this env
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest tests/test_cli tests/test_issue_1779_remote_control_gate.py tests/test_cli_doctor.py -q
FAILED tests/test_cli/test_wrap_sighup_proxy_leak.py::test_sighup_on_launch_tool_releases_the_proxy
1 failed, 1067 passed, 1 skipped in 21.45s
```

`test_sighup_on_launch_tool_releases_the_proxy` fails identically on
unmodified `main` in my environment (checked with the change stashed),
so it's unrelated.

## Real Behavior Proof

- Environment: macOS, Python 3.12, Claude Code 2.1.290, branch head
`f971660d`
- Exact command / steps: live launch against a real proxy (no mocks).
The proxy was started by `wrap` on a free port, and `--version` makes
the real Claude Code binary exit right after the banner:
  ```text
headroom wrap claude --port 8799 --no-mcp --code-memory none --
--version
headroom wrap claude -v --port 8799 --no-mcp --code-memory none --
--version
  ```
- Observed result: by default the banner shows one Remote Control line
and one tool-loading line, and the proxy status and dashboard share one
line. `-v` prints the previous full RC and tool-search wording
unchanged.

  Default (fresh proxy start):
  ```text
    Starting Headroom proxy on port 8799...
    Logs: ~/.headroom/logs/proxy-8799.log
    Proxy ready — dashboard: http://127.0.0.1:8799/dashboard

    Launching Claude Code (API routed through Headroom)...
    ANTHROPIC_BASE_URL=http://127.0.0.1:8799
Remote Control (/rc) is disabled while routed through Headroom — run
`claude` directly (no wrap) for sessions that need it.
    Extra args: --version
Telemetry: anonymous usage counters — never prompts, code, or file
paths. See: headroom telemetry --show | Off: HEADROOM_BEACON=off

    On-demand tool loading: kept on (this session)
  2.1.290 (Claude Code)
  ```
  With `-v` (reusing the running proxy):
  ```text
    Proxy already running — dashboard: http://127.0.0.1:8799/dashboard
    Skipping MCP retrieve tool (--no-mcp)
    Skipping Serena MCP (--code-memory none)

    Launching Claude Code (API routed through Headroom)...
    ANTHROPIC_BASE_URL=http://127.0.0.1:8799
Remote Control: Claude Code 2.1.290 disables the /remote-control (/rc)
command while ANTHROPIC_BASE_URL points at a custom endpoint (the
wrapped Claude session's ANTHROPIC_BASE_URL). Headroom cannot override
this client-side gate — run Claude without Headroom for sessions that
need Remote Control.
Same base-URL gate also affects on-demand tool loading (#746 — Headroom
keeps it on for this session) and the 1M context window (#1158 — restore
with `headroom wrap claude --1m`).
    Extra args: --version
Telemetry: anonymous usage counters — never prompts, code, or file
paths. See: headroom telemetry --show | Off: HEADROOM_BEACON=off

    ENABLE_TOOL_SEARCH=true (on-demand tool loading kept on; issue #746)
  2.1.290 (Claude Code)
  ```
- Not tested: a full interactive session. The launch exits at
`--version` once the banner prints.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: Only the banner text. No routing or
env changes.
- Kill switch / disable path: `-v` shows the previous full lines
- Unsafe override required: No
- Qualification impact: None
- Rollback path: revert this PR

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation: N/A, the
docs don't quote these banner lines
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md`

## Additional Notes

In the default mode, the `--1m` hint from the sibling note now only
appears under `-v`. If maintainers want that hint visible by default, a
short `(1M context: --1m)` suffix on the tool-loading line would be a
cheap way to keep it.


<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3900"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
Sudhindra Desai
2026-10-06 08:36:29 -05:00
committed by GitHub
co-authored by JD Davis
parent 855390d611
commit aba75cbf6d
5 changed files with 125 additions and 20 deletions
+32 -15
View File
@@ -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)} "
+2
View File
@@ -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",
]
+18
View File
@@ -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.
@@ -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(
@@ -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