feat(context-mode): make OpenClaw capability reporting truthful

.gitignore

@@ -18,5 +18,6 @@ AGENTS.md
 context-mode-guidance-*/
 .claude/worktrees/
 .claude-worktrees/
+.worktrees/
 .vibetree/
 .cw/

README.md

@@ -418,6 +418,13 @@ context-mode runs as a native [OpenClaw](https://github.com/openclaw) gateway pl
 
 **Verify:** The plugin registers 8 hooks via [`api.on()`](https://docs.openclaw.ai/tools/plugin) (lifecycle) and [`api.registerHook()`](https://docs.openclaw.ai/tools/plugin) (commands). Type `ctx stats` to confirm tools are loaded.
 
+> **OpenClaw support is capability-aware.** After installation, verify the current session with `ctx-stats` or `ctx-doctor`.
+> - `full` means DB-backed persistence was observed for this session.
+> - `degraded` means relevant hooks fired, but persistence is not yet proven.
+> - `unsupported` means no reliable capture path is proven yet.
+>
+> Do not treat installation success by itself as proof that token savings are active.
+
 **Routing:** Automatic. All tool interception, session tracking, and compaction recovery hooks activate automatically — no manual hook configuration or routing file needed.
 
 > **Minimum version:** OpenClaw >2026.1.29 — this includes the `api.on()` lifecycle fix from [PR #9761](https://github.com/openclaw/openclaw/pull/9761). On older versions, lifecycle hooks silently fail. The adapter falls back to DB snapshot reconstruction (less precise but preserves critical state).
@@ -877,7 +884,7 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `searc
 
 **KiloCode** — Partial. Shares the same plugin architecture as OpenCode via the OpenCodeAdapter. The TypeScript plugin captures PostToolUse events via `tool.execute.after`, but SessionStart availability depends on KiloCode's implementation. Events are stored but may not be automatically restored after compaction.
 
-**OpenClaw / Pi Agent** — High coverage. All tool lifecycle hooks (`after_tool_call`, `before_compaction`, `session_start`) fire via the native gateway plugin. User decisions aren't captured but file edits, git ops, errors, and tasks are fully tracked. Falls back to DB snapshot reconstruction if compaction hooks fail on older gateway versions. See [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md).
+**OpenClaw / Pi Agent** — Capability-aware. `full` means DB-backed persistence was observed for the current session. `degraded` means relevant hooks were observed but persistence is not proven. `unsupported` means no reliable capture path is proven. Installation success alone is not proof that token savings are active. See [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md).
 
 **Codex CLI** — MCP active, hooks ready. Hook scripts (PreToolUse, PostToolUse, SessionStart) are implemented and tested but Codex CLI doesn't dispatch them yet (Stage::UnderDevelopment). MCP tools work. Track: [openai/codex#16685](https://github.com/openai/codex/issues/16685).
 
@@ -910,7 +917,7 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `searc
 >
 > **KiloCode** shares the same TypeScript plugin architecture as OpenCode via the OpenCodeAdapter, with platform-specific configuration paths (`kilo.json` instead of `opencode.json`, `~/.config/kilo/` instead of `~/.config/opencode/`). Hook capabilities depend on KiloCode's implementation of the plugin interface.
 >
-> **OpenClaw** runs context-mode as a native gateway plugin targeting Pi Agent sessions. Hooks register via `api.on()` (tool/lifecycle) and `api.registerHook()` (commands). All tool interception and compaction hooks are supported. See [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md).
+> **OpenClaw** runs context-mode as a native gateway plugin targeting Pi Agent sessions. Hooks register via `api.on()` (tool/lifecycle) and `api.registerHook()` (commands). Hook coverage is high, but session status remains capability-aware (`full`/`degraded`/`unsupported`) based on observed runtime evidence, not default assumptions. See [`docs/adapters/openclaw.md`](docs/adapters/openclaw.md).
 >
 > **Codex CLI** hooks are implemented but dispatch is not yet active (`codex_hooks` is `Stage::UnderDevelopment`). MCP tools work. Hook scripts are ready and will activate once Codex enables dispatch ([openai/codex#16685](https://github.com/openai/codex/issues/16685)). PreToolUse supports `permissionDecision: "deny"` only — `additionalContext` is not supported in PreToolUse (context injection works via PostToolUse and SessionStart instead; the codex formatter handles this automatically). See the Codex install section for setup. **Antigravity** and **Zed** do not support hooks. They rely solely on manually-copied routing instruction files (`AGENTS.md` / `GEMINI.md`) for enforcement (~60% compliance). See each platform's install section for copy instructions. Antigravity and Zed are auto-detected via MCP protocol handshake — no manual platform configuration needed.
 >

docs/adapters/openclaw.md

@@ -10,8 +10,21 @@ The context-mode adapter hooks into Pi Agent sessions specifically, intercepting
 
 ### Supported Configurations
 
-- **Pi Agent sessions** with coding tools (Read/Write/Edit/Bash) — fully supported.
-- **Custom agents** with coding tools — may work but are untested. The adapter relies on tool names matching Pi Agent's conventions.
+- **Pi Agent sessions** with coding tools (Read/Write/Edit/Bash) — capability-aware support. A session is reported as `full` only after DB-backed persistence is observed for that session.
+- **Direct `agent:main:main` sessions** — fail-closed. They are not expected to be `full` unless runtime evidence proves a working capture path. Until then, they may report `degraded` or `unsupported`. Do not assume token savings are active from installation alone.
+- **Custom agents** with coding tools — unproven. Treat support as `unsupported` until `ctx-stats` or `ctx-doctor` reports stronger evidence.
+
+## Capability Reporting
+
+Use `ctx-stats` or `ctx-doctor` and read these fields literally:
+
+- `Capability`
+- `reason_code`
+- `evidence_level`
+- `Active capture path`
+- `Token savings active`
+
+`Token savings active: yes` is reserved for sessions where DB-backed persistence has been observed for the current session.
 
 ## Installation