Skip to content

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.

fix(wrap): remove rtk instructions from Codex AGENTS.md on unwrap (#1604)

Abhay Singhc9d717c13c7a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c2bdb938c..52e26d0ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -72,6 +72,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Bug Fixes
+* **wrap/codex:** `headroom unwrap codex` now removes the Headroom rtk instruction block from the Codex global `AGENTS.md`. `wrap codex` injects it there, but unwrap only restored `config.toml` and MCP state, so a plain `codex` launch kept following the "prefix shell commands with `rtk`" guidance and failed once the managed rtk binary was off PATH. Unwrap now strips the marker-fenced block (preserving the rest of the file), mirroring `unwrap copilot` ([#1421](https://github.com/headroomlabs-ai/headroom/issues/1421)).
* **proxy/auth:** classify real Anthropic OAuth tokens correctly. `classify_auth_mode` matched OAuth on the `sk-ant-oat-` prefix, but real access tokens are `sk-ant-oat01-...` (a version number, no dash after `oat`), so every real subscription/OAuth token fell through to the `sk-` branch and was tagged `PAYG` — enabling aggressive lossy compression, auto `cache_control`, and `prompt_cache_key` injection on subscription-bound requests the classifier is meant to route to the passthrough-prefer path. The prefix is now the dash-less `sk-ant-oat` (still matches the legacy dashed shape). The existing parity tests only passed because they used a synthetic `sk-ant-oat-01-` fixture; a regression test now covers the real `sk-ant-oat01-` format.
* **install:** stop leaking a file descriptor on every `headroom install start`. `start_detached_agent()` opened the agent log file and handed it to `subprocess.Popen` but never closed the parent's copy, so each call leaked one fd (and pinned the log file open against rotation). The parent now closes its copy in a `try/finally` once the child has inherited it — the close also runs if `Popen` raises ([#1554](https://github.com/headroomlabs-ai/headroom/issues/1554)).
* **proxy:** include the system prompt, tools, and the response-shaping request fields in the SemanticCache key. `_compute_key` hashed only `{model, messages}`, so two non-streaming requests with identical messages but a different top-level `system` prompt, tool set, sampling config, or output-shaping field collided on one key and the second caller was served the first's cached response — generated under different request semantics, in the default config (`cache_enabled` defaults on). The key now folds the request fields that shape generation — `temperature`/`top_p`/`top_k`/`max_tokens`/`stop`, plus OpenAI `tool_choice`/`response_format`/`parallel_tool_calls`/`seed`/`presence_penalty`/`frequency_penalty`/`logit_bias`/`n`/`logprobs`/`top_logprobs`/`reasoning_effort`/`verbosity`/`modalities` and Anthropic `thinking`/`tool_choice`/`output_config` — canonicalizing `system`/`tools` so a moved `cache_control` breakpoint does not fragment it, and the handlers snapshot the fields once at the cache read and reuse them at write so a body mutated by the pipeline cannot diverge the key. Non-streaming path only.
diff --git a/headroom/cli/wrap.py b/headroom/cli/wrap.py
index 1f22f2ff3..53d051ed3 100644
--- a/headroom/cli/wrap.py
+++ b/headroom/cli/wrap.py
@@ -5842,6 +5842,16 @@ def unwrap_codex(port: int, no_stop_proxy: bool) -> None:
elif serena_status == "failed":
click.echo(" Serena MCP server matched Headroom ledger but could not be removed.")
+ # `wrap codex` injects the marker-fenced rtk guidance into the Codex global
+ # AGENTS.md (`_codex_home_dir() / "AGENTS.md"`); that block is durable state
+ # the config restore above does not touch. Without removing it, a plain
+ # `codex` launch keeps following Headroom's "prefix shell commands with rtk"
+ # instruction and fails when the managed rtk binary is off PATH. Mirror what
+ # unwrap_copilot already does. Best-effort and unconditional, like the MCP
+ # cleanup above.
+ if _remove_rtk_instructions(_codex_home_dir() / "AGENTS.md"):
+ click.echo(" Removed Headroom rtk instructions from Codex AGENTS.md.")
+
if status in {"restored", "cleaned", "removed"}:
# Hand the threads back to the native-provider menu so the full history
# stays visible once Codex no longer routes through Headroom. Best-effort.
diff --git a/tests/test_cli/test_wrap_codex.py b/tests/test_cli/test_wrap_codex.py
index 7af6597f4..d3a5500b5 100644
--- a/tests/test_cli/test_wrap_codex.py
+++ b/tests/test_cli/test_wrap_codex.py
@@ -459,6 +459,53 @@ class TestInjectAndRestoreRoundTrip:
assert status == "restored"
assert config_file.read_text(encoding="utf-8") == malformed
+ def test_unwrap_removes_rtk_block_from_global_agents(
+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+ ) -> None:
+ """`wrap codex` injects the rtk block into the Codex global AGENTS.md;
+ `unwrap codex` must take it back out (regression for #1421)."""
+ _set_test_home(monkeypatch, tmp_path)
+ codex_home = tmp_path / ".codex"
+ codex_home.mkdir()
+ agents = codex_home / "AGENTS.md"
+ wrap_mod._inject_rtk_instructions(agents)
+ assert wrap_mod._RTK_MARKER in agents.read_text(encoding="utf-8")
+
+ wrap_mod.unwrap_codex.callback(port=8787, no_stop_proxy=True)
+
+ remaining = agents.read_text(encoding="utf-8") if agents.exists() else ""
+ assert wrap_mod._RTK_MARKER not in remaining
+
+ def test_unwrap_preserves_user_content_in_global_agents(
+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+ ) -> None:
+ """Only the marker-fenced rtk block is removed; the user's own AGENTS.md
+ prose survives the unwrap."""
+ _set_test_home(monkeypatch, tmp_path)
+ codex_home = tmp_path / ".codex"
+ codex_home.mkdir()
+ agents = codex_home / "AGENTS.md"
+ agents.write_text("# My project rules\n\nAlways write tests.\n", encoding="utf-8")
+ wrap_mod._inject_rtk_instructions(agents)
+ assert wrap_mod._RTK_MARKER in agents.read_text(encoding="utf-8")
+
+ wrap_mod.unwrap_codex.callback(port=8787, no_stop_proxy=True)
+
+ remaining = agents.read_text(encoding="utf-8")
+ assert wrap_mod._RTK_MARKER not in remaining
+ assert "# My project rules" in remaining
+ assert "Always write tests." in remaining
+
+ def test_unwrap_is_safe_when_no_global_agents(
+ self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+ ) -> None:
+ """No Codex AGENTS.md → unwrap is a clean no-op, not a crash."""
+ _set_test_home(monkeypatch, tmp_path)
+
+ wrap_mod.unwrap_codex.callback(port=8787, no_stop_proxy=True)
+
+ assert not (tmp_path / ".codex" / "AGENTS.md").exists()
+
# ---------------------------------------------------------------------------
# Thread retag: wrap pulls native threads into the headroom menu, unwrap hands