Headroom: the tool path, measured; provider path documented as blocked

docs/PLAN-INTERFACE.md

@@ -664,6 +664,34 @@ To use it, one of these is needed:
 
 The provider entry was removed so no agent can be pointed at a failing endpoint by accident.
 
+### The path that does work: headroom as a tool
+
+The `headroom-bridge` extension in `~/.agents/extensions` does something different from a
+provider: it gives a Pi agent two tools, `compress_for_agent` and `check_headroom`. The first
+calls headroom's compression endpoint; the second reports whether the service is up. That is the
+integration that fits: headroom shortens text an agent is about to pass on, rather than standing
+between the agent and its model.
+
+Measured directly, without the extension:
+
+```
+POST http://192.168.20.13:8787/v1/compress  {"model": …, "messages":[…]}   → 200
+{tokens_before: 4009, tokens_after: 4009, tokens_saved: 0, compression_ratio: 1.0,
+ transforms_applied: ["router:protected:user_message"]}
+```
+
+So the endpoint works and reports its effect honestly; a single long user message is protected
+from compression, which is why it saved nothing in that test. To give one agent the tool:
+
+1. `~/.agents/extensions/headroom-bridge` needs the `headroom-ai` npm package resolvable by Pi;
+   it is **not** installed in `~/.pi/agent/npm`, so the extension will fail to import until it is.
+2. Give the extension to one agent with the extensions picker in `Agents>agents` — `space` writes a
+   wrapper and points that agent's command at it.
+3. Then that agent, and no other, has the compression tool.
+
+That is the honest position: compression is available as a tool, blocked on one npm package, and
+it is per agent because the wrapper is per agent.
+
 ## Mouse-1, measured
 
 The person supplied `docs/MOUSE-1-NOTES.md`, written from measurements on 2026-11-08/09. The