How to Configure Protection for Recent Read Tool Outputs from Compression in Headroom

Set the protect_recent_reads_fraction field in ContentRouterConfig to a float between 0.0 and 1.0 to control the fraction of recent conversation history containing Read-tool outputs that remains uncompressed.

Headroom’s content-router pipeline protects the output of Read-type tools—such as search results, logs, and diffs—from aggressive compression. The protect_recent_reads_fraction configuration option in the ContentRouterConfig dataclass, defined in headroom/transforms/content_router.py, governs how much of your recent conversation history stays uncompressed. This guide explains the available configuration options and how to implement them using the Python SDK or proxy server settings.

Understanding the Read Protection Mechanism

When Headroom processes conversation history, it calculates a protection window to determine which messages containing Read-tool outputs are safe to compress. The router computes this window adaptively using the logic found in headroom/transforms/content_router.py (lines 13-22):

read_protection_window = max(
    4,  # always keep at least four recent messages

    int(num_messages * self.config.protect_recent_reads_fraction),
)

Messages older than this window are eligible for compression, even if they originate from tools listed in DEFAULT_EXCLUDE_TOOLS. Messages inside the window retain their original content regardless of compression pressure.

Configuration Options and Defaults

The protection behavior is controlled through three related fields in the ContentRouterConfig dataclass:

• protect_recent_reads_fraction (float, default: 0.0): The fraction of the total message window to leave uncompressed. A value of 0.0 applies historic "exclude-tool" behavior that protects all recent reads, while 1.0 would allow compression of all Read-tool outputs.
• protect_recent_code (int, default: 4): The number of most-recent messages whose code blocks remain uncompressed regardless of other settings.
• protect_analysis_context (bool, default: True): When enabled, code blocks are preserved if the user’s last message contains analysis-type keywords.

In token-mode specifically, the proxy preset overrides the default fraction. As implemented in headroom/proxy/server.py at line 64, the system automatically sets:

if is_token_mode(config.mode):
    router_config.protect_recent_reads_fraction = 0.3

This ensures approximately 30% of the newest messages remain untouched when operating in token-reduction mode.

Setting the Protection Fraction

Programmatic Configuration via Python SDK

Instantiate ContentRouterConfig and pass it to ProxyConfig when initializing the Headroom client:

from headroom.transforms import ContentRouterConfig
from headroom.proxy import ProxyConfig

router_cfg = ContentRouterConfig(
    protect_recent_reads_fraction=0.2,  # Protect ~20% of recent messages

    protect_recent_code=0,              # Disable code-block protection

    protect_analysis_context=False,
)

proxy_cfg = ProxyConfig(
    mode="token",
    content_router=router_cfg,
)

client = HeadroomClient(proxy_config=proxy_cfg, ...)

Proxy Server Defaults

The proxy server constructs ContentRouterConfig internally during initialization. To adjust the fraction server-wide, modify the hard-coded preset in headroom/proxy/server.py before starting the proxy, or supply a custom configuration object through the application initialization logic.

Runtime Overrides

For dynamic adjustments on a running handler, access the router configuration directly:

from headroom.proxy.handlers.openai import OpenAIHandler

# Assuming `handler` is an OpenAIHandler instance

handler.router_config.protect_recent_reads_fraction = 0.5

Custom Proxy Deployment Example

Create a JSON configuration file to load custom router settings:

{
  "protect_recent_reads_fraction": 0.1,
  "protect_recent_code": 0,
  "protect_analysis_context": false
}

Load and apply these settings when starting the proxy:

import json
from headroom.transforms import ContentRouterConfig
from headroom.proxy import ProxyServer, ProxyConfig

with open("router.json") as f:
    cfg_dict = json.load(f)

router_cfg = ContentRouterConfig(**cfg_dict)
proxy_cfg = ProxyConfig(mode="token", content_router=router_cfg)

server = ProxyServer(proxy_cfg)
server.run()

Summary

• The protect_recent_reads_fraction field in ContentRouterConfig controls what percentage of recent Read-tool outputs remain uncompressed.
• The protection window is calculated as max(4, int(num_messages * fraction)), ensuring at least four recent messages are always preserved.
• Token-mode automatically sets this fraction to 0.3 (30%) in headroom/proxy/server.py unless explicitly overridden.
• Configuration changes take effect in headroom/transforms/content_router.py (lines 13-22 and 80-85) and can be set programmatically or via custom proxy initialization.

Frequently Asked Questions

What is the difference between protect_recent_reads_fraction and protect_recent_code?

The protect_recent_reads_fraction safeguards the output of Read-type tools (search, log, diff) based on a sliding percentage of the conversation length, while protect_recent_code protects a fixed integer count of messages containing code blocks. The former scales with conversation size; the latter provides a constant buffer regardless of history length.

Why does the protection window use a minimum of 4 messages?

The max(4, ...) floor in the calculation, implemented in headroom/transforms/content_router.py, ensures that even with very small fractions or short conversations, at least four recent messages remain readable. This prevents the compression algorithm from eliminating critical context in brief exchanges.

How do I disable Read tool output protection entirely?

Set protect_recent_reads_fraction to 1.0. This forces the calculated protection window to exceed the number of messages in any practical conversation, making all Read-tool outputs eligible for compression according to standard routing rules.

Does the fraction setting apply in all Headroom modes?

No. While the configuration option exists in all modes, the token-mode specifically injects a default value of 0.3 at headroom/proxy/server.py line 64. To use a custom fraction in token-mode, you must explicitly construct and pass a ContentRouterConfig instance with your desired value.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}