docs(cli-backends): document ownsNativeCompaction opt-out contract

anagnorisis2peripeteia · obviyus · commit 5e52a9b513aa · 2026-06-02T14:39:35.000+05:30
diff --git a/docs/gateway/cli-backends.md b/docs/gateway/cli-backends.md
@@ -372,6 +372,35 @@ its own control markers and channel delivery.
 For CLIs that emit Claude Code stream-json compatible JSONL, set
 `jsonlDialect: "claude-stream-json"` on that backend's config.
 
+## Native compaction ownership
+
+Some CLI backends run an agent that compacts its **own** transcript, so OpenClaw must
+not run its safeguard summarizer against them - doing so fights the backend's own
+compaction and can hard-fail the turn. **Codex** (its app-server owns automatic
+compaction) and **Claude Code** (`claude-cli`) both work this way, and both **opt out
+of OpenClaw compaction**:
+
+- **Codex** routes to its native-harness compaction endpoint (matched by the session's
+  `agentHarnessId`).
+- **`claude-cli`** has no harness endpoint - Claude Code compacts internally - so it
+  declares `ownsNativeCompaction: true`, and OpenClaw returns a no-op from the
+  compaction path.
+
+Either way OpenClaw **defers and never compacts these sessions.** Because the backend
+owns compaction, the old stopgap of setting `contextTokens: 1_000_000` purely to keep
+OpenClaw's safeguard from firing on a claude-cli session is **no longer needed** - the
+opt-out replaces it.
+
+```typescript
+api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });
+```
+
+Only declare `ownsNativeCompaction` for a backend that genuinely owns its compaction: it
+must reliably bound its own transcript as it nears its context window and persist a
+resumable session (e.g. `--resume` / `--session-id`); otherwise a deferred session can
+stay over budget. (A session whose `agentHarnessId` matches the provider still routes to
+the harness endpoint - the no-op applies only when there is no harness endpoint.)
+
 ## Bundle MCP overlays
 
 CLI backends do **not** receive OpenClaw tool calls directly, but a backend can
diff --git a/docs/plugins/cli-backend-plugins.md b/docs/plugins/cli-backend-plugins.md
@@ -208,10 +208,30 @@ only for behavior that really belongs to the backend.
 | `authEpochMode`                    | Decide how auth changes invalidate stored CLI sessions |
 | `nativeToolMode`                   | Declare whether the CLI has always-on native tools     |
 | `bundleMcp` / `bundleMcpMode`      | Opt into OpenClaw's loopback MCP tool bridge           |
+| `ownsNativeCompaction`             | Backend owns its own compaction - OpenClaw defers      |
 
 Keep these hooks provider-owned. Do not add CLI-specific branches to core when a
 backend hook can express the behavior.
 
+### `ownsNativeCompaction`: opting out of OpenClaw compaction
+
+If your backend runs an agent that compacts its **own** transcript, set
+`ownsNativeCompaction: true` so OpenClaw's safeguard summarizer never runs against its
+sessions - the CLI compaction lifecycle returns a no-op and the turn proceeds. This is
+the **same opt-out Codex uses** (its app-server owns automatic compaction); `claude-cli`
+declares it because Claude Code compacts internally with no harness endpoint. It also
+removes any need to inflate `contextTokens` just to keep the safeguard from firing.
+
+**Only declare it when all of the following hold**, or a deferred over-budget session can
+stay over budget / go stale (OpenClaw no longer rescues it):
+
+- the backend reliably compacts or bounds its own transcript as it nears its window;
+- it persists a resumable session so the compacted state survives turns
+  (e.g. `--resume` / `--session-id`);
+- it is **not** a native-harness compaction session - a session whose `agentHarnessId`
+  matches the provider routes to the harness endpoint instead; this no-op applies only
+  when there is no harness endpoint.
+
 ## MCP tool bridge
 
 CLI backends do not receive OpenClaw tools by default. If the CLI can consume an
diff --git a/src/plugins/cli-backend.types.ts b/src/plugins/cli-backend.types.ts
@@ -84,9 +84,20 @@ export type CliBackendPlugin = {
   contextEngineHostCapabilities?: readonly ContextEngineHostCapability[];
   /**
    * When true, the backend manages its own transcript compaction lifecycle
-   * (e.g. Claude Code's internal auto-compaction). OpenClaw will skip its
-   * safeguard summarizer and return a no-op from the compaction path instead
-   * of fighting the backend's own compaction or hard-failing the turn.
+   * (e.g. Claude Code's internal auto-compaction). OpenClaw skips its safeguard
+   * summarizer and returns a no-op from the CLI compaction path instead of
+   * fighting the backend's own compaction or hard-failing the turn.
+   *
+   * Safety contract - only declare this when ALL of the following hold, or an
+   * over-budget session can stay over budget / go stale (OpenClaw no longer
+   * rescues it):
+   *  - the backend reliably compacts or bounds its own transcript as it nears
+   *    its context window;
+   *  - it persists a resumable session so the compacted state survives across
+   *    turns (e.g. `--resume` / `--session-id`);
+   *  - it is NOT a native-harness compaction session - a session whose
+   *    `agentHarnessId` matches the provider still routes to the harness
+   *    endpoint, so this no-op applies only when there is no harness endpoint.
    */
   ownsNativeCompaction?: boolean;
   /**
