docs(codex): document native compaction hooks

docs/concepts/compaction.md

@@ -113,6 +113,20 @@ the summary:
 /compact Focus on the API design decisions
 ```
 
+## Codex harness compaction
+
+When an embedded agent session uses the Codex app-server harness, Codex owns the
+native thread and native compaction operation. OpenClaw keeps a transcript mirror
+for channel history and future harness switching, but the canonical compacted
+thread stays in Codex.
+
+OpenClaw plugin hooks still expose `before_compaction` and `after_compaction`
+for the Codex harness from the app-server compaction item stream. Codex native
+`PreCompact` and `PostCompact` hooks, when supported by the installed Codex
+app-server, are separate Codex command hooks configured through Codex. They are
+useful for low-level Codex audit or policy, but they do not replace the
+OpenClaw plugin hook contract.
+
 ## Using a different model
 
 By default, compaction uses your agent's primary model. You can use a more

docs/plugins/codex-harness.md

@@ -530,11 +530,17 @@ thread unless Codex exposes that operation through app-server or native hook
 callbacks.
 
 When newer Codex app-server builds expose native compaction and model lifecycle
-hook events, OpenClaw should version-gate that protocol support and map the
-events into the existing OpenClaw hook contract where the semantics are honest.
-Until then, OpenClaw's `before_compaction`, `after_compaction`, `llm_input`, and
-`llm_output` events are adapter-level observations, not byte-for-byte captures
-of Codex's internal request or compaction payloads.
+hook events, OpenClaw version-gates that protocol support and maps events into
+the existing OpenClaw hook contract where the semantics are honest. The
+OpenClaw `before_compaction`, `after_compaction`, `llm_input`, and `llm_output`
+events remain adapter-level observations, not byte-for-byte captures of Codex's
+internal request or compaction payloads.
+
+Codex native `PreCompact` and `PostCompact` hooks are lower-level Codex command
+hooks. They run inside Codex around native thread compaction, using Codex hook
+configuration. OpenClaw's plugin hooks do not require a user or project
+`hooks.json`, and OpenClaw does not double-fire `before_compaction` or
+`after_compaction` just because native Codex compaction hooks are available.
 
 ## Tools, media, and compaction
 
@@ -558,6 +564,12 @@ records native compaction start and completion signals. It does not yet expose a
 human-readable compaction summary or an auditable list of which entries Codex
 kept after compaction.
 
+On Codex app-server builds with native compaction hook support, Codex can also
+run its own `PreCompact` and `PostCompact` command hooks around that native
+operation. Those hooks are useful for Codex-owned audit and policy. OpenClaw
+still treats the app-server compaction item stream as the source for OpenClaw
+plugin `before_compaction` and `after_compaction` events.
+
 Because Codex owns the canonical native thread, `tool_result_persist` does not
 currently rewrite Codex-native tool result records. It only applies when
 OpenClaw is writing an OpenClaw-owned session transcript tool result.