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

> Configure headroom to protect recent Read tool outputs from compression. Learn how to set the protect_recent_reads_fraction field for optimal conversation history management.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-06

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) (lines 13-22):

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py) at line 64, the system automatically sets:

```python
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:

```python
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`](https://github.com/chopratejas/headroom/blob/main/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:

```python
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:

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

```

Load and apply these settings when starting the proxy:

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py) unless explicitly overridden.
- Configuration changes take effect in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.