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(init): set ENABLE_TOOL_SEARCH=true so Claude Code keeps deferring tools (#746) (#995)
Eyal Mizrachi500ec2b7faeb
diff --git a/headroom/cli/init.py b/headroom/cli/init.pyindex 037b6754d..8abc98b12 100644--- a/headroom/cli/init.py+++ b/headroom/cli/init.py@@ -38,6 +38,7 @@ from headroom.install.runtime import ()from headroom.install.state import load_manifest, save_manifestfrom headroom.install.supervisors import start_supervisor+from headroom.providers.claude import TOOL_SEARCH_DEFAULT, TOOL_SEARCH_ENVfrom headroom.providers.codex.install import codex_uses_chatgpt_authfrom .main import main@@ -161,6 +162,12 @@ def _ensure_claude_hooks(path: Path, profile: str, port: int) -> None:payload = _json_file(path)env_map = dict(payload.get("env") or {}) if isinstance(payload.get("env"), dict) else {}env_map["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{port}"+ # GH #746: with a custom ANTHROPIC_BASE_URL and ENABLE_TOOL_SEARCH unset,+ # Claude Code stops deferring MCP/system tool schemas and materializes them+ # all into its context window — overflowing it (breaks sub-agent spawns,+ # forces constant compaction). Keep deferral on; respect a user-set value.+ # Shares the TOOL_SEARCH_* constants with `wrap` and `install`.+ env_map.setdefault(TOOL_SEARCH_ENV, TOOL_SEARCH_DEFAULT)payload["env"] = env_maphooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.pyindex aafc34575..9113afae6 100644--- a/headroom/cli/wrap.py+++ b/headroom/cli/wrap.py@@ -50,7 +50,13 @@ from headroom.copilot_auth import (resolve_subscription_bearer_token_details,)from headroom.providers.aider import build_launch_env as _build_aider_launch_env-from headroom.providers.claude import proxy_base_url as _claude_proxy_base_url+from headroom.providers.claude import (+ TOOL_SEARCH_DEFAULT,+ TOOL_SEARCH_ENV,+)+from headroom.providers.claude import (+ proxy_base_url as _claude_proxy_base_url,+)from headroom.providers.codex import build_launch_env as _build_codex_launch_envfrom headroom.providers.codex.install import codex_uses_chatgpt_authfrom headroom.providers.codex.threads import retag_to_headroom, retag_to_native@@ -121,9 +127,10 @@ _WRAP_PROXY_TIMEOUT_ML_MODULES = ("torch", "sentence_transformers", "spacy")# when we launch Claude Code keeps deferral on. Default to "true" — defer the# MCP/system tools for maximum context savings, matching native first-party# behaviour (core built-ins like Read/Edit/Bash are never deferred by Claude-# Code, so the agent loop is unaffected).-_TOOL_SEARCH_ENV = "ENABLE_TOOL_SEARCH"-_TOOL_SEARCH_DEFAULT = "true"+# Code, so the agent loop is unaffected). The key/default are shared with+# `init` and `install` via the Claude provider package to prevent drift.+_TOOL_SEARCH_ENV = TOOL_SEARCH_ENV+_TOOL_SEARCH_DEFAULT = TOOL_SEARCH_DEFAULT_AGENT_SAVINGS_WRAP_AGENTS = {"claude", "codex", "cursor"}_DEFAULT_AGENT_SAVINGS_PROFILE = "agent-90"@@ -2519,7 +2526,7 @@ def _marker_pid_reused(marker: Path, pid: int) -> bool:return Falsesrc = rec.get("start_src")recorded = rec.get("start_time")- if not isinstance(src, str) or not isinstance(recorded, (int, float)):+ if not isinstance(src, str) or not isinstance(recorded, int | float):return False # legacy / identity-less marker — can't tellident = _proc_identity(pid)if ident is None or ident[0] != src:diff --git a/headroom/providers/claude/__init__.py b/headroom/providers/claude/__init__.pyindex 0ea0c7e39..cdff9c83c 100644--- a/headroom/providers/claude/__init__.py+++ b/headroom/providers/claude/__init__.py@@ -1,5 +1,15 @@"""Claude-specific provider helpers."""-from .runtime import DEFAULT_API_URL, proxy_base_url+from .runtime import (+ DEFAULT_API_URL,+ TOOL_SEARCH_DEFAULT,+ TOOL_SEARCH_ENV,+ proxy_base_url,+)-__all__ = ["DEFAULT_API_URL", "proxy_base_url"]+__all__ = [+ "DEFAULT_API_URL",+ "TOOL_SEARCH_DEFAULT",+ "TOOL_SEARCH_ENV",+ "proxy_base_url",+]diff --git a/headroom/providers/claude/install.py b/headroom/providers/claude/install.pyindex 30b6928c2..fcce25c4d 100644--- a/headroom/providers/claude/install.py+++ b/headroom/providers/claude/install.py@@ -8,13 +8,23 @@ from pathlib import Pathfrom headroom.install.models import ConfigScope, DeploymentManifest, ManagedMutation, ToolTargetfrom headroom.install.paths import claude_settings_path-from .runtime import proxy_base_url+from .runtime import TOOL_SEARCH_DEFAULT, TOOL_SEARCH_ENV, proxy_base_urldef build_install_env(*, port: int, backend: str) -> dict[str, str]:"""Build the persistent install environment for Claude."""del backend- return {"ANTHROPIC_BASE_URL": proxy_base_url(port)}+ # TOOL_SEARCH_ENV keeps Claude Code deferring MCP/system tool schemas behind+ # the server-side Tool Search Tool when pointed at the proxy's custom+ # ANTHROPIC_BASE_URL; without it Claude Code materializes every schema into+ # its context window (GH #746) — breaking sub-agents and forcing compaction.+ # The install env is headroom-managed and reverted on uninstall, so it is+ # authoritative — unlike `init`, it always writes the default rather than+ # deferring to a pre-existing user value.+ return {+ "ANTHROPIC_BASE_URL": proxy_base_url(port),+ TOOL_SEARCH_ENV: TOOL_SEARCH_DEFAULT,+ }def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None:diff --git a/headroom/providers/claude/runtime.py b/headroom/providers/claude/runtime.pyindex 0039bcb98..45b65781c 100644--- a/headroom/providers/claude/runtime.py+++ b/headroom/providers/claude/runtime.py@@ -4,6 +4,14 @@ from __future__ import annotationsDEFAULT_API_URL = "https://api.anthropic.com"+# GH #746: Claude Code stops deferring MCP/system tool schemas (materializing+# every one into its context window) when ANTHROPIC_BASE_URL is a custom host+# and ENABLE_TOOL_SEARCH is unset. Every place that points Claude Code at the+# proxy must keep deferral on, so the env key and its default live here as the+# single source of truth shared by `wrap`, `init`, and `install`.+TOOL_SEARCH_ENV = "ENABLE_TOOL_SEARCH"+TOOL_SEARCH_DEFAULT = "true"+def proxy_base_url(port: int) -> str:"""Return the local proxy base URL used by Claude integrations."""diff --git a/tests/test_cli/test_init_cli.py b/tests/test_cli/test_init_cli.pyindex 9df842824..f94d293fd 100644--- a/tests/test_cli/test_init_cli.py+++ b/tests/test_cli/test_init_cli.py@@ -424,7 +424,11 @@ def test_ensure_claude_hooks_rewrites_existing_entries(monkeypatch, tmp_path: Painit_cli._ensure_claude_hooks(settings_path, "init-local-demo", 9001)payload = json.loads(settings_path.read_text(encoding="utf-8"))- assert payload["env"] == {"KEEP": "1", "ANTHROPIC_BASE_URL": "http://127.0.0.1:9001"}+ assert payload["env"] == {+ "KEEP": "1",+ "ANTHROPIC_BASE_URL": "http://127.0.0.1:9001",+ "ENABLE_TOOL_SEARCH": "true",+ }session_entries = payload["hooks"]["SessionStart"]assert session_entries[0] == "not-a-dict"assert session_entries[1] == {"hooks": "not-a-list"}diff --git a/tests/test_cli/test_init_enable_tool_search.py b/tests/test_cli/test_init_enable_tool_search.pynew file mode 100644index 000000000..de65e56ed--- /dev/null+++ b/tests/test_cli/test_init_enable_tool_search.py@@ -0,0 +1,42 @@+"""`headroom init claude` must set ENABLE_TOOL_SEARCH (GH #746).++Claude Code disables on-demand tool loading when ANTHROPIC_BASE_URL is a custom+host and ENABLE_TOOL_SEARCH is unset, materializing all MCP/system tool schemas+into the context window — which breaks sub-agent spawns and forces compaction.+`headroom wrap claude` already sets it; `init` (and the persistent install) must+too, otherwise init-wired users silently get eager tools.+"""++from __future__ import annotations++import json+from pathlib import Path++from headroom.cli import init as init_cli+from headroom.providers.claude import install as claude_install+++def test_ensure_claude_hooks_sets_enable_tool_search(tmp_path: Path) -> None:+ settings = tmp_path / "settings.json"+ init_cli._ensure_claude_hooks(settings, profile="init-user", port=8787)++ env = json.loads(settings.read_text(encoding="utf-8"))["env"]+ assert env["ANTHROPIC_BASE_URL"] == "http://127.0.0.1:8787"+ assert env["ENABLE_TOOL_SEARCH"] == "true"+++def test_ensure_claude_hooks_respects_user_tool_search_value(tmp_path: Path) -> None:+ settings = tmp_path / "settings.json"+ settings.write_text(+ json.dumps({"env": {"ENABLE_TOOL_SEARCH": "auto"}}) + "\n", encoding="utf-8"+ )+ init_cli._ensure_claude_hooks(settings, profile="init-user", port=8787)++ env = json.loads(settings.read_text(encoding="utf-8"))["env"]+ assert env["ENABLE_TOOL_SEARCH"] == "auto" # setdefault preserves the user's choice+++def test_build_install_env_includes_enable_tool_search() -> None:+ env = claude_install.build_install_env(port=8787, backend="anthropic")+ assert env["ENABLE_TOOL_SEARCH"] == "true"+ assert env["ANTHROPIC_BASE_URL"].endswith(":8787")diff --git a/tests/test_install/test_providers.py b/tests/test_install/test_providers.pyindex a4182a29d..f02da01c5 100644--- a/tests/test_install/test_providers.py+++ b/tests/test_install/test_providers.py@@ -382,7 +382,10 @@ def test_claude_build_install_env_returns_proxy_base_url() -> None:env = build_claude_install_env(port=5566, backend="ignored")# Assert- assert env == {"ANTHROPIC_BASE_URL": "http://127.0.0.1:5566"}+ assert env == {+ "ANTHROPIC_BASE_URL": "http://127.0.0.1:5566",+ "ENABLE_TOOL_SEARCH": "true",+ }def test_copilot_build_install_env_uses_provider_type_specific_proxy_urls() -> None: