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(router): keep small shell results verbatim (#3590) (#4426)
ShiYuan Xiong4ee616453fce
diff --git a/docs/content/docs/proxy.mdx b/docs/content/docs/proxy.mdxindex 0b3f12b7c..e2912b79e 100644--- a/docs/content/docs/proxy.mdx+++ b/docs/content/docs/proxy.mdx@@ -320,6 +320,7 @@ Fine-grained control over what gets compressed and how hard. Most users pick a [| `--mode` / `HEADROOM_MODE` | `cache` | `cache` compresses only the newest delta (prefix-cache safe); `token` maximizes removal. || `--target-ratio` / `HEADROOM_TARGET_RATIO` | unset | Keep-ratio for ML text compression; lower = more aggressive (e.g. `0.10`). || `HEADROOM_MIN_TOKENS` | `500` | Minimum block size before a tool output is compressed. |+| `HEADROOM_SHELL_RESULT_MIN_CHARS` | `2000` | Shell tool results shorter than this many characters bypass lossy compression. For top-level text blocks, the threshold uses their combined text length. Byte-lossless folds such as search grouping may still apply. Applies to `bash`, `shell`, `local_shell`, and aliases such as `run_shell_command`/`execute_command`; set `0` to restore lossy compression. || `HEADROOM_COMPRESS_USER_MESSAGES` | profile | Compress text inside user-role messages. The `coding` profile turns this on; set `0` to keep user text verbatim under it. Anthropic `tool_result` blocks compress either way. No `--compress-user-messages` flag on `headroom proxy`; the direct module entry point (`python -m headroom.proxy.server`) does accept one. || `HEADROOM_COMPRESS_SYSTEM_MESSAGES` | unset | Compress system prompts. Off by default to keep the hottest cache prefix stable. || `HEADROOM_PROTECT_RECENT` | profile | Never compress the N most recent turns. |diff --git a/e2e/wrap/tools/README.md b/e2e/wrap/tools/README.mdindex 8a404f7ad..34ad5f4fc 100644--- a/e2e/wrap/tools/README.md+++ b/e2e/wrap/tools/README.md@@ -10,7 +10,8 @@ PATH. `npm ci` does not support global installs, so diagnostics must also use`npm list --prefix /opt/wrap-tools`.After editing a CLI version in `package.json`, regenerate the lockfile using-Node 22 and npm 11.16.0 on Linux:+Node 24.22.1+ within the Node 24 line and npm 11.16.0 on Linux (the pinned+OpenClaw version no longer supports Node 22):```shcd e2e/wrap/tools@@ -34,4 +35,11 @@ to make a build pass.These are existing test tools, not new product dependencies. Codex is maintainedby OpenAI; OpenClaw and its transitive dependencies retain their upstreammaintainers. Their install surface includes registry downloads, native optional-packages and lifecycle scripts, as before. Top-level CLI versions are unchanged.+packages and lifecycle scripts, as before. OpenClaw 2026.10.6 and its fixed+Undici override follow the upstream #4453 security repair.++The raw audit still reports npm 12.2.1's bundled ip-address and Undici copies.+`npm-audit-exceptions.json` records the upstream-approved E2E-only risk+acceptance, restricted to exact advisory/path/version combinations and expiring+on 2026-11-15. Security CI rejects other findings and expired or stale entries;+these exceptions are not a claim that the contained packages are patched.diff --git a/headroom/transforms/content_router.py b/headroom/transforms/content_router.pyindex d4ec4da6f..038fe1529 100644--- a/headroom/transforms/content_router.py+++ b/headroom/transforms/content_router.py@@ -2113,6 +2113,30 @@ def _is_small_mcp_result(tool_name: Any, text: Any) -> bool:)+def _shell_result_min_chars() -> int:+ """Below this many characters a shell tool result is never lossily compressed."""+ try:+ return max(0, int(os.environ.get("HEADROOM_SHELL_RESULT_MIN_CHARS", "2000")))+ except ValueError:+ return 2000+++def _is_small_shell_result(tool_name: Any, text: Any, bash_tool_names: frozenset[str]) -> bool:+ """True when ``text`` is a short shell result that must not be lossily compressed.++ A 200-token ``ls -la``, ``git status``, or JSON dump is cheap to keep and+ expensive to get wrong: lossy compression can leave a numbers-only blob+ that still looks structured, so the model treats it as data instead of+ retrying the command (issue #3590). Large build/test logs still take the+ lossy path. ``HEADROOM_SHELL_RESULT_MIN_CHARS=0`` restores the old+ behaviour.+ """+ if not isinstance(text, str) or not text:+ return False+ name = str(tool_name or "").lower()+ return name in bash_tool_names and len(text) < _shell_result_min_chars()++@dataclassclass ContentRouterConfig:"""Configuration for intelligent content routing.@@ -2317,8 +2341,22 @@ class ContentRouterConfig:# BUT a read-only *search* run through them (grep/rg/git grep) yields byte-# losslessly foldable output — folded instead of lossy-compressed. See# ``_bash_search_fold``. Config so new harness tool names / search programs- # can be added without code changes.- bash_tool_names: frozenset[str] = frozenset({"bash", "shell", "local_shell"})+ # can be added without code changes. The aliases mirror+ # ``headroom.learn._shared._TOOL_NAME_MAP`` so the same harnesses are+ # covered here.+ bash_tool_names: frozenset[str] = frozenset(+ {+ "bash",+ "shell",+ "local_shell",+ "run_shell_command",+ "execute_command",+ "exec_command",+ "terminal",+ "run_command",+ "run_terminal_command",+ }+ )bash_search_commands: frozenset[str] = frozenset({"grep", "egrep", "fgrep", "rg", "ripgrep", "ag", "ack"})@@ -2349,6 +2387,12 @@ class ContentRouterConfig:# Default False; the proxy enables it in token mode.search_group_by_file: bool = False+ def __post_init__(self) -> None:+ # Normalize once so the per-message shell check stays a set lookup.+ self.bash_tool_names = frozenset(+ name.lower() for name in self.bash_tool_names if isinstance(name, str)+ )+@dataclassclass _PerRequestRuntimeState:@@ -6311,6 +6355,7 @@ class ContentRouter(Transform):"ccr_retrieve": 0,"user_msg": 0,"small": 0,+ "shell_small_result": 0,"recent_code": 0,"analysis_ctx": 0,"ratio_too_high": 0,@@ -6600,6 +6645,36 @@ class ContentRouter(Transform):_diag[i] = "compressed:bash_lossless_search"continue+ # Small shell results stay verbatim (#3590). A short `ls`,+ # `git status`, or JSON dump is cheap to keep; lossy+ # compression can leave a numbers-only blob that still looks+ # structured, so the model treats it as data instead of+ # retrying. Large build/test logs still take the lossy path.+ if _is_small_shell_result(tool_name, content, self.config.bash_tool_names):+ result_slots[i] = message+ transforms_applied.append("router:shell_small_result_verbatim")+ route_counts["shell_small_result"] = (+ route_counts.get("shell_small_result", 0) + 1+ )+ if collect_diagnostics:+ _diag[i] = "protected:shell_small_result"+ continue++ # Legacy OpenAI `role:"function"` carries the tool name on the+ # message itself, not in a tool_call_id. Resolve it directly so the+ # small-shell floor also covers this wire shape (#3590 review).+ if role == "function":+ function_name = message.get("name", "")+ if _is_small_shell_result(function_name, content, self.config.bash_tool_names):+ result_slots[i] = message+ transforms_applied.append("router:shell_small_result_verbatim")+ route_counts["shell_small_result"] = (+ route_counts.get("shell_small_result", 0) + 1+ )+ if collect_diagnostics:+ _diag[i] = "protected:shell_small_result"+ continue+# Read protection (ROLE / SHAPE-AGNOSTIC). An observation produced by# a file read command (cat/sed/head/…) is passed VERBATIM so the agent# keeps exact bytes to patch — regardless of how THIS harness labels@@ -7569,6 +7644,21 @@ class ContentRouter(Transform):any_compressed = Falserole = message.get("role", "")+ # Top-level text blocks are fragments of one tool result. Measure the+ # whole result so splitting a large log cannot activate the small-result+ # floor for every fragment. Sum lengths without copying the payload.+ shell_result_chars = (+ sum(+ len(block["text"])+ for block in content_blocks+ if isinstance(block, dict)+ and block.get("type") == "text"+ and isinstance(block.get("text"), str)+ )+ if role in ("tool", "function")+ else 0+ )+# Role-based gate for `text` blocks. Tool/function roles are tool# outputs and compress freely; assistant defaults to skip (cache# safety) with explicit opt-in; unknown roles default to skip.@@ -7767,6 +7857,18 @@ class ContentRouter(Transform):any_compressed = Truecontinue+ # Small shell results stay verbatim (#3590), same contract as+ # the string-form path above. Build/test logs above the floor+ # still go through lossy compression.+ if _is_small_shell_result(tool_name, tool_text, self.config.bash_tool_names):+ new_blocks.append(block)+ transforms_applied.append("router:shell_small_result_verbatim")+ if route_counts is not None:+ route_counts["shell_small_result"] = (+ route_counts.get("shell_small_result", 0) + 1+ )+ continue+# Protection: failed tool calls / error outputs stay verbatim# (issue #847). `is_error` is Anthropic's explicit failure# flag and suffices alone; the indicator scan catches error@@ -7864,6 +7966,29 @@ class ContentRouter(Transform):if route_counts is not None:route_counts["ccr_retrieve"] = route_counts.get("ccr_retrieve", 0) + 1continue++ # A normalized tool/function message can carry its output+ # as top-level text blocks rather than a tool_result+ # wrapper. Apply the same small-shell floor here (#3590+ # review).+ _shell_name = (+ (tool_name_map or {}).get(_msg_tool_id, "")+ if role == "tool"+ else message.get("name", "")+ )+ if (+ _is_small_shell_result(+ _shell_name, block.get("text", ""), self.config.bash_tool_names+ )+ and shell_result_chars < _shell_result_min_chars()+ ):+ new_blocks.append(block)+ transforms_applied.append("router:shell_small_result_verbatim")+ if route_counts is not None:+ route_counts["shell_small_result"] = (+ route_counts.get("shell_small_result", 0) + 1+ )+ continuetext_content = block.get("text", "")if isinstance(text_content, str) and (len(text_content) > min_chars or self._has_lossless_fold(text_content)diff --git a/plugins/opencode/package.json b/plugins/opencode/package.jsonindex fcd6934b0..6dd950656 100644--- a/plugins/opencode/package.json+++ b/plugins/opencode/package.json@@ -47,8 +47,8 @@},"overrides": {"esbuild": "^0.28.1",- "zod": "^4.6.6",- "toml": "^5.0.1"+ "zod": "4.6.7",+ "toml": "5.0.1"},"license": "Apache-2.0"}diff --git a/plugins/opencode/src/dependency-compat.test.ts b/plugins/opencode/src/dependency-compat.test.tsnew file mode 100644index 000000000..b9ea0cc4e--- /dev/null+++ b/plugins/opencode/src/dependency-compat.test.ts@@ -0,0 +1,62 @@+import { tool } from "@opencode-ai/plugin";+import { Effect, FileSystem, Path } from "effect";+import { Primitive } from "effect/unstable/cli";+import { describe, expect, it } from "vitest";++function parseConfig(content: string): Promise<unknown> {+ const fs = FileSystem.makeNoop({+ exists: () => Effect.succeed(true),+ stat: () => Effect.succeed({ type: "File" } as FileSystem.File.Info),+ readFileString: () => Effect.succeed(content),+ });+ return Effect.runPromise(+ Primitive.fileParse({ format: "toml" }).parse("/headroom/config.toml").pipe(+ Effect.provideService(FileSystem.FileSystem, fs),+ Effect.provide(Path.layer),+ ),+ );+}++describe("patched OpenCode dependency compatibility", () => {+ it("builds and validates a tool with the upstream Zod schema interface", () => {+ const schema = tool.schema.object({+ hash: tool.schema.string().regex(/^[a-f0-9]{24}$/i),+ });+ const retrieve = tool({+ description: "Retrieve an original tool result",+ args: schema.shape,+ async execute(args) {+ return args.hash;+ },+ });+ expect(schema.parse({ hash: "a".repeat(24) })).toEqual({ hash: "a".repeat(24) });+ expect(schema.safeParse({ hash: "invalid" }).success).toBe(false);+ expect(retrieve.args.hash).toBe(schema.shape.hash);+ });++ it("parses typed TOML through Effect's actual file parser", async () => {+ const content = `+name = "headroom"+enabled = true+ports = [8787, 8788]+[proxy]+host = "127.0.0.1"+ratio = 0.5+[[models]]+name = "coding"+[[models]]+name = "review"+`;+ await expect(parseConfig(content)).resolves.toEqual({+ name: "headroom",+ enabled: true,+ ports: [8787, 8788],+ proxy: { host: "127.0.0.1", ratio: 0.5 },+ models: [{ name: "coding" }, { name: "review" }],+ });+ });++ it("keeps malformed TOML on Effect's parse-error channel", async () => {+ await expect(parseConfig("[unclosed")).rejects.toThrow("Failed to parse '.toml'");+ });+});diff --git a/pyproject.toml b/pyproject.tomlindex 1c598884c..dedddb344 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -54,7 +54,7 @@ dependencies = ["litellm>=1.96.2,<2.0","click>=8.3.3", # CLI framework; PYSEC-2026-2132 fix (command injection in click.edit())"rich>=13.0.0", # Rich terminal output- "opentelemetry-api>=1.24.0", # Safe no-op OTEL API for instrumentation+ "opentelemetry-api>=1.45.1", # CVE-2026-114603: bounded, linear-time tracestate parsing# AST-aware code slicing (CodeCompressor); binary wheel. 0.44.1 is excluded:# that PyPI release was a compromised supply-chain build shipping an# info-stealer `sg.exe` (Trojan:Win64/Lazy!MTB) alongside the real binary@@ -414,6 +414,8 @@ Changelog = "https://github.com/headroomlabs-ai/headroom/blob/main/CHANGELOG.md"# transitively; the floor pins below ensure uv resolves to patched versions.[tool.uv]constraint-dependencies = [+ # PYSEC-2026-4320 — remove distrusted root certificates from the CA bundle.+ "certifi>=2026.10.19",# GHSA-5239-wwwm-4pmq (Low) — transitive via rich; fix at 2.20.0"pygments>=2.20.0",# GHSA-4xgf-cpjx-pc3j (Medium) — transitive via mcp; fix at 2.14.2@@ -429,8 +431,11 @@ constraint-dependencies = ["lxml-html-clean>=0.4.5",# CVE-2026-5241 (High) — direct optional dep for proxy/ml/voice; fix at 5.5.0"transformers>=5.5.0",- # PYSEC-2026-3447 — transitive dependency; fix at 83.0.0- "setuptools>=83.0.0",+ # GHSA-xmj3-9gf7-h52w — Windows wheel namespace path traversal.+ "setuptools>=84.1.0",+ # CVE-2026-112940/112913/112907. The patched series requires Python 3.11;+ # Python 3.10 retains the legacy locked version; it is not remediated by this marker.+ "filelock>=4.2.1; python_version >= '3.11'",# PYSEC-2026-3545/3546/3547 — transitive HTTP/WebSocket parser fixes;# CVE-2026-111063/111064, GHSA-2g87-pp6c-29x5; fix at 3.14.4"aiohttp>=3.14.4",diff --git a/tests/test_content_router_shell_small_results.py b/tests/test_content_router_shell_small_results.pynew file mode 100644index 000000000..4ac629e32--- /dev/null+++ b/tests/test_content_router_shell_small_results.py@@ -0,0 +1,483 @@+"""Small shell results must stay verbatim through the lossy router path.++Issue #3590: ``headroom wrap claude`` with a low ``HEADROOM_MIN_TOKENS``+compressed a short ``ls -la`` result into a numbers-only blob. The output+still looked structured, so the model treated it as data instead of+retrying. File reads and searches are already protected; shell output is+deliberately compressible, but a small result is not worth the accuracy+cost. Large build/test logs must keep going through the lossy path.+"""++from __future__ import annotations++from collections.abc import Callable++import pytest++from headroom.config import TransformResult+from headroom.providers import OpenAIProvider+from headroom.tokenizer import Tokenizer+from headroom.transforms.content_router import (+ CompressionStrategy,+ ContentRouter,+ ContentRouterConfig,+ ContentType,+ RouterCompressionResult,+ RoutingDecision,+ _is_small_shell_result,+ _shell_result_min_chars,+)+++def _tokenizer() -> Tokenizer:+ provider = OpenAIProvider()+ return Tokenizer(provider.get_token_counter("gpt-4o"), "gpt-4o")+++def _lossy_result(original: str) -> RouterCompressionResult:+ """Stand-in for the ML compressor, including its CCR recovery marker."""+ return RouterCompressionResult(+ compressed="128 448 09:26 1760 09:28 11980 16767 2394 1262\n<<ccr:deadbeef>>",+ original=original,+ strategy_used=CompressionStrategy.KOMPRESS,+ strategy_chain=["kompress"],+ routing_log=[+ RoutingDecision(+ ContentType.PLAIN_TEXT,+ CompressionStrategy.KOMPRESS,+ original_tokens=400,+ compressed_tokens=12,+ )+ ],+ )+++def _fake_compress(content: str, **kwargs: object) -> RouterCompressionResult:+ return _lossy_result(content)+++def _conversation(+ tool_name: str, tool_output: str, *, list_form: bool = False+) -> list[dict[str, object]]:+ """A conversation old enough that the tool result is compressible."""+ tool_content: object = [{"type": "text", "text": tool_output}] if list_form else tool_output+ messages: list[dict[str, object]] = [+ {"role": "system", "content": "You are a coding agent."},+ {"role": "user", "content": "run the command"},+ {+ "role": "assistant",+ "content": [+ {+ "type": "tool_use",+ "id": "tool_1",+ "name": tool_name,+ "input": {"command": "ls -la"},+ }+ ],+ },+ {+ "role": "user",+ "content": [+ {+ "type": "tool_result",+ "tool_use_id": "tool_1",+ "content": tool_content,+ }+ ],+ },+ ]+ for i in range(10):+ messages.append({"role": "assistant", "content": f"step {i}"})+ messages.append({"role": "user", "content": f"continue {i}"})+ return messages+++def _route(tool_name: str, tool_output: str, *, list_form: bool = False) -> TransformResult:+ router = ContentRouter(ContentRouterConfig())+ router.compress = _fake_compress # type: ignore[assignment]+ return router.apply(+ _conversation(tool_name, tool_output, list_form=list_form),+ _tokenizer(),+ target_ratio=0.4,+ )+++def _openai_conversation(tool_name: str, tool_output: str) -> list[dict[str, object]]:+ messages: list[dict[str, object]] = [+ {"role": "system", "content": "You are a coding agent."},+ {"role": "user", "content": "run the command"},+ {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {"name": tool_name, "arguments": "{}"},+ }+ ],+ },+ {"role": "tool", "tool_call_id": "call_1", "content": tool_output},+ ]+ for i in range(10):+ messages.append({"role": "assistant", "content": f"step {i}"})+ messages.append({"role": "user", "content": f"continue {i}"})+ return messages+++def _route_openai(tool_name: str, tool_output: str) -> TransformResult:+ router = ContentRouter(ContentRouterConfig())+ router.compress = _fake_compress # type: ignore[assignment]+ return router.apply(+ _openai_conversation(tool_name, tool_output), _tokenizer(), target_ratio=0.4+ )+++def _tail(messages: list[dict[str, object]]) -> list[dict[str, object]]:+ for i in range(10):+ messages.append({"role": "assistant", "content": f"step {i}"})+ messages.append({"role": "user", "content": f"continue {i}"})+ return messages+++def _function_conversation(tool_name: str, tool_output: str) -> list[dict[str, object]]:+ """Legacy OpenAI shape: role:function with the tool name on the message."""+ messages: list[dict[str, object]] = [+ {"role": "system", "content": "You are a coding agent."},+ {"role": "user", "content": "run the command"},+ {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {"name": tool_name, "arguments": "{}"},+ }+ ],+ },+ {"role": "function", "name": tool_name, "content": tool_output},+ ]+ return _tail(messages)+++def _route_function(tool_name: str, tool_output: str) -> TransformResult:+ router = ContentRouter(ContentRouterConfig())+ router.compress = _fake_compress # type: ignore[assignment]+ return router.apply(+ _function_conversation(tool_name, tool_output), _tokenizer(), target_ratio=0.4+ )+++def _text_block_conversation(tool_name: str, tool_output: str) -> list[dict[str, object]]:+ """OpenAI shape: a tool message whose content is a list of text blocks."""+ messages: list[dict[str, object]] = [+ {"role": "system", "content": "You are a coding agent."},+ {"role": "user", "content": "run the command"},+ {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call_1",+ "type": "function",+ "function": {"name": tool_name, "arguments": "{}"},+ }+ ],+ },+ {+ "role": "tool",+ "tool_call_id": "call_1",+ "content": [{"type": "text", "text": tool_output}],+ },+ ]+ return _tail(messages)+++def _route_text_block(tool_name: str, tool_output: str) -> TransformResult:+ router = ContentRouter(ContentRouterConfig())+ router.compress = _fake_compress # type: ignore[assignment]+ return router.apply(+ _text_block_conversation(tool_name, tool_output), _tokenizer(), target_ratio=0.4+ )+++def _ls_output(rows: int = 18) -> str:+ files = "\n".join(+ f"-rw-r--r-- 1 user staff {1000 + i:>6} Oct 22 09:{i:02d} report_{i:02d}_final_v2.md"+ for i in range(rows)+ )+ return (+ "total 128\n"+ "drwxr-xr-x 12 user staff 384 Oct 22 09:26 .\n"+ "drwxr-xr-x 5 user staff 160 Oct 22 09:25 ..\n"+ f"{files}\n"+ )+++def _padded_output(length: int) -> str:+ """A shell-like payload of exactly ``length`` characters."""+ base = "line: some structured shell output\n"+ return (base * (length // len(base) + 1))[:length]+++def test_small_bash_tool_result_stays_verbatim() -> None:+ """A short shell result keeps its structure instead of becoming numbers."""+ output = _ls_output()+ assert len(output) < 2000++ result = _route("Bash", output)++ assert result.messages[3]["content"][0]["content"] == output+ assert "router:shell_small_result_verbatim" in result.transforms_applied+++def test_large_bash_tool_result_is_still_compressed() -> None:+ """The guard must not disable compression for large build/test logs."""+ output = _ls_output(rows=80)+ assert len(output) > 2000++ result = _route("Bash", output)++ assert result.messages[3]["content"][0]["content"] != output+ assert "router:tool_result:kompress" in result.transforms_applied+++def test_small_non_shell_tool_result_is_still_compressed() -> None:+ """The guard is scoped to shell tools, not every small tool result."""+ output = "a short reference payload\n" * 30++ result = _route("SomeOtherTool", output)++ assert result.messages[3]["content"][0]["content"] != output+ assert "router:tool_result:kompress" in result.transforms_applied+++def test_small_openai_tool_result_stays_verbatim() -> None:+ """The OpenAI role:tool shape carries the same guard as Anthropic blocks."""+ output = _ls_output()++ result = _route_openai("Bash", output)++ assert result.messages[3]["content"] == output+ assert "router:shell_small_result_verbatim" in result.transforms_applied+++def test_shell_result_min_chars_can_disable_the_guard(monkeypatch: pytest.MonkeyPatch) -> None:+ """The escape hatch restores the previous behaviour for operators."""+ monkeypatch.setenv("HEADROOM_SHELL_RESULT_MIN_CHARS", "0")+ output = _ls_output()++ result = _route("Bash", output)++ assert result.messages[3]["content"][0]["content"] != output+ assert "router:tool_result:kompress" in result.transforms_applied+++def test_invalid_shell_result_min_chars_falls_back(monkeypatch: pytest.MonkeyPatch) -> None:+ """A non-numeric override keeps the documented default instead of crashing."""+ monkeypatch.setenv("HEADROOM_SHELL_RESULT_MIN_CHARS", "junk")++ assert _shell_result_min_chars() == 2000+++def test_zero_shell_result_min_chars_is_legitimate(monkeypatch: pytest.MonkeyPatch) -> None:+ """Zero is a real value ("no floor"), not an invalid one."""+ monkeypatch.setenv("HEADROOM_SHELL_RESULT_MIN_CHARS", "0")++ assert _shell_result_min_chars() == 0+++def test_negative_shell_result_min_chars_disables_the_guard(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.setenv("HEADROOM_SHELL_RESULT_MIN_CHARS", "-1")+ assert _shell_result_min_chars() == 0+ result = _route("Bash", _ls_output())+ assert "router:shell_small_result_verbatim" not in result.transforms_applied++[email protected]("text", [None, 123, ""])+def test_empty_or_non_string_values_are_not_small_shell_results(text: object) -> None:+ assert not _is_small_shell_result("Bash", text, frozenset({"bash"}))+++def test_shell_result_floor_boundary_is_exclusive() -> None:+ """The floor is "shorter than", so exactly 2000 chars stays compressible."""+ at_floor = _padded_output(2000)+ below_floor = _padded_output(1999)++ at_result = _route("Bash", at_floor)+ below_result = _route("Bash", below_floor)++ assert at_result.messages[3]["content"][0]["content"] != at_floor+ assert below_result.messages[3]["content"][0]["content"] == below_floor+ assert "router:shell_small_result_verbatim" in below_result.transforms_applied+++ "tool_name",+ ["Bash", "shell", "local_shell", "run_shell_command", "execute_command"],+)+def test_recognized_shell_aliases_stay_verbatim(tool_name: str) -> None:+ """Harness aliases from the shared tool-name map get the same protection."""+ output = _ls_output()++ result = _route(tool_name, output)++ assert result.messages[3]["content"][0]["content"] == output+ assert "router:shell_small_result_verbatim" in result.transforms_applied+++def test_unrecognized_shell_like_name_is_still_compressed() -> None:+ """A similar-looking name outside the configured set is not protected."""+ output = _ls_output()++ result = _route("run_remote_shell", output)++ assert result.messages[3]["content"][0]["content"] != output+ assert "router:tool_result:kompress" in result.transforms_applied+++def test_small_list_form_tool_result_stays_verbatim() -> None:+ """The Anthropic list-form content wrapper is flattened and protected."""+ output = _ls_output()++ result = _route("Bash", output, list_form=True)++ assert result.messages[3]["content"][0]["content"] == [{"type": "text", "text": output}]+ assert "router:shell_small_result_verbatim" in result.transforms_applied+++def test_small_legacy_function_result_stays_verbatim() -> None:+ """Legacy role:function resolves the shell name from message["name"]."""+ output = _ls_output()++ result = _route_function("Bash", output)++ assert result.messages[3]["content"] == output+ assert "router:shell_small_result_verbatim" in result.transforms_applied+++def test_small_top_level_text_block_stays_verbatim() -> None:+ """A tool message normalized to top-level text blocks gets the guard."""+ output = _ls_output()++ result = _route_text_block("Bash", output)++ assert result.messages[3]["content"] == [{"type": "text", "text": output}]+ assert "router:shell_small_result_verbatim" in result.transforms_applied++[email protected]("role", ["tool", "function"])[email protected]("length", [1999, 2000, 2400])+def test_split_shell_result_uses_total_text_length(role: str, length: int) -> None:+ """The floor applies to the whole result, not each provider text fragment."""+ messages = _text_block_conversation("Bash", "")+ if role == "function":+ messages[3] = {"role": "function", "name": "Bash"}+ blocks = [+ {"type": "text", "text": _padded_output(length // 2)},+ {"type": "text", "text": _padded_output(length - length // 2)},+ ]+ messages[3]["content"] = blocks+ router = ContentRouter(ContentRouterConfig())+ router.compress = _fake_compress # type: ignore[assignment]++ result = router.apply(messages, _tokenizer(), target_ratio=0.4)++ assert (result.messages[3]["content"] == blocks) is (length < 2000)+ assert ("router:shell_small_result_verbatim" in result.transforms_applied) is (length < 2000)++[email protected]("route", [_route_openai, _route_function, _route_text_block])+def test_shell_floor_override_applies_to_wire_shapes(+ monkeypatch: pytest.MonkeyPatch, route: Callable[[str, str], TransformResult]+) -> None:+ """A positive override protects below the floor and compresses at it."""+ monkeypatch.setenv("HEADROOM_SHELL_RESULT_MIN_CHARS", "1000")+ below = route("Bash", _padded_output(999))+ at = route("Bash", _padded_output(1000))+ assert "router:shell_small_result_verbatim" in below.transforms_applied+ assert "router:shell_small_result_verbatim" not in at.transforms_applied+++def test_custom_shell_names_are_normalized_and_protected() -> None:+ """An operator's custom mixed-case shell name gets the same floor."""+ router = ContentRouter(ContentRouterConfig(bash_tool_names=frozenset({"MyShell"})))+ router.compress = _fake_compress # type: ignore[assignment]+ output = _ls_output()+ result = router.apply(_openai_conversation("mYsHeLl", output), _tokenizer(), target_ratio=0.4)+ assert result.messages[3]["content"] == output+ assert "router:shell_small_result_verbatim" in result.transforms_applied++[email protected]("route", [_route_openai, _route_function, _route_text_block])+def test_non_shell_results_remain_compressible_in_all_wire_shapes(+ route: Callable[[str, str], TransformResult],+) -> None:+ output = _ls_output()+ result = route("SomeOtherTool", output)+ assert "router:shell_small_result_verbatim" not in result.transforms_applied+ assert result.messages[3]["content"] not in (output, [{"type": "text", "text": output}])++[email protected]("route", [_route_openai, _route_function, _route_text_block])+def test_shell_floor_can_be_disabled_in_all_wire_shapes(+ monkeypatch: pytest.MonkeyPatch, route: Callable[[str, str], TransformResult]+) -> None:+ monkeypatch.setenv("HEADROOM_SHELL_RESULT_MIN_CHARS", "0")+ output = _ls_output()+ result = route("Bash", output)+ assert "router:shell_small_result_verbatim" not in result.transforms_applied+ assert result.messages[3]["content"] not in (output, [{"type": "text", "text": output}])++[email protected]("conversation", [_openai_conversation, _function_conversation])+def test_small_shell_result_diagnostics_explain_why_it_was_preserved(+ conversation: Callable[[str, str], list[dict[str, object]]],+) -> None:+ output = _ls_output()+ router = ContentRouter(ContentRouterConfig())+ router.compress = _fake_compress # type: ignore[assignment]+ result = router.apply(+ conversation("Bash", output), _tokenizer(), target_ratio=0.4, collect_diagnostics=True+ )+ decision = next(item for item in result.message_decisions if item.message_index == 3)+ assert decision.action == "protected:shell_small_result"+ assert decision.tokens_before == decision.tokens_after+ assert result.messages[3]["content"] == output++[email protected]("shape", ["anthropic", "tool", "function"])+def test_small_shell_blocks_without_optional_route_counters(shape: str) -> None:+ """Direct block callers can omit counters without losing the shell guard."""+ output = _ls_output()+ if shape == "anthropic":+ message = _conversation("Bash", output)[3]+ elif shape == "function":+ message = {+ "role": "function",+ "name": "Bash",+ "content": [{"type": "text", "text": output}],+ }+ else:+ message = _text_block_conversation("Bash", output)[3]+ transforms: list[str] = []+ router = ContentRouter(ContentRouterConfig())+ router.compress = _fake_compress # type: ignore[assignment]++ result = router._process_content_blocks(+ message=message,+ content_blocks=message["content"],+ context="",+ transforms_applied=transforms,+ excluded_tool_ids=set(),+ ccr_retrieve_tool_ids=set(),+ tool_name_map={"tool_1": "Bash", "call_1": "Bash"},+ route_counts=None,+ messages_from_end=20,+ )++ assert result is message+ assert transforms == ["router:shell_small_result_verbatim"]diff --git a/tests/test_websearch_tool_result_protection.py b/tests/test_websearch_tool_result_protection.pyindex a270b9a24..ec65dd56e 100644--- a/tests/test_websearch_tool_result_protection.py+++ b/tests/test_websearch_tool_result_protection.py@@ -2,6 +2,8 @@from __future__ import annotations+import pytest+from headroom.config import DEFAULT_EXCLUDE_TOOLSfrom headroom.proxy.server import HeadroomProxy, ProxyConfigfrom headroom.transforms.content_detector import ContentType@@ -159,7 +161,11 @@ def test_web_tool_results_skip_cross_turn_dedup() -> None:assert second["content"] == payload # type: ignore[index]-def test_bash_remains_compressible() -> None:[email protected]("repetitions, expected_calls", [(100, 0), (200, 1)])+def test_bash_compression_respects_small_result_floor(+ monkeypatch: pytest.MonkeyPatch, repetitions: int, expected_calls: int+) -> None:+ monkeypatch.setenv("HEADROOM_SHELL_RESULT_MIN_CHARS", "2000")router = _router()calls = 0@@ -177,8 +183,11 @@ def test_bash_remains_compressible() -> None:)router.compress = fake_compress # type: ignore[method-assign]- payload = "bash output " * 100+ payload = "bash output " * repetitionsresult = router.apply(_messages("Bash", payload), _Tokenizer())- assert calls == 1+ assert calls == expected_callsassert "router:excluded:tool" not in result.transforms_applied+ assert ("router:shell_small_result_verbatim" in result.transforms_applied) is (+ expected_calls == 0+ )diff --git a/uv.lock b/uv.lockindex 6c334667f..f6c1cb21e 100644--- a/uv.lock+++ b/uv.lock@@ -23,13 +23,15 @@ resolution-markers = [[manifest]constraints = [{ name = "aiohttp", specifier = ">=3.14.4" },+ { name = "certifi", specifier = ">=2026.10.19" },{ name = "cryptography", specifier = ">=50.0.0" },+ { name = "filelock", marker = "python_full_version >= '3.11'", specifier = ">=4.2.1" },{ name = "gitpython", specifier = ">=3.1.58" },{ name = "langsmith", specifier = ">=0.9.0" },{ name = "lxml-html-clean", specifier = ">=0.4.5" },{ name = "pydantic-settings", specifier = ">=2.14.2" },{ name = "pygments", specifier = ">=2.20.0" },- { name = "setuptools", specifier = ">=83.0.0" },+ { name = "setuptools", specifier = ">=84.1.0" },{ name = "transformers", specifier = ">=5.5.0" },]overrides = [{ name = "pillow", specifier = ">=13.0.0" }]@@ -1765,7 +1767,7 @@ requires-dist = [{ name = "openai", marker = "extra == 'proxy'", specifier = ">=2.14.0" },{ name = "openpyxl", marker = "extra == 'dev'", specifier = ">=3.1.0" },{ name = "openpyxl", marker = "extra == 'spreadsheet'", specifier = ">=3.1.0" },- { name = "opentelemetry-api", specifier = ">=1.24.0" },+ { name = "opentelemetry-api", specifier = ">=1.45.1" },{ name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'dev'", specifier = ">=1.24.0" },{ name = "opentelemetry-exporter-otlp-proto-http", marker = "extra == 'otel'", specifier = ">=1.24.0" },{ name = "opentelemetry-sdk", marker = "extra == 'dev'", specifier = ">=1.24.0" },