stack/openclaw-feature-requests.md

OpenClaw Feature Requests

Filed: 2026-03-01 — for when we fork and contribute back

---

FR-001: Pre-Compaction State Snapshot

Problem: Mid-session compaction silently loses track of in-flight work — running worker PIDs, pending PRs, active deploys. Agents rely on having written state to HEARTBEAT.md beforehand, which fails under cognitive load.

Requested behavior: Before summarizing context, OpenClaw should:

1. Read workspace HEARTBEAT.md active state section
2. Inject a "pre-compaction snapshot" block into the compaction summary
3. Ensure any STATE: in-progress WAL entries survive verbatim into the new context

---

FR-002: WAL Append Tool / Hook

Problem: Agents updating HEARTBEAT.md requires a file write tool call — which can be skipped, fails silently, and is not atomic.

Requested behavior: A lightweight wal_append tool or pre-turn hook that:

1. Appends a timestamped entry to a persistent WAL file outside the summarizable context
2. Is called automatically before/after tool calls matching a configurable action pattern
3. Survives compaction independently of the context window

---

FR-003: Session State Persistence API

Problem: Active worker session IDs, pending merges, and deploy state live only in context. After compaction or a new session, there is no way to resume awareness of in-flight operations.

Requested behavior:

1. A key-value session state store (separate from context) that persists across compactions
2. Agents can state_set("audit_worker_pid", "3990263") and state_get("audit_worker_pid")
3. State visible in /status output and injected as a small block in every turn

---

FR-004: Mandatory Pre-Action Hooks (Convention Enforcement)

Problem: Completion gates (code review, WAL updates, scratchpads) are defined in AGENTS.md but nothing mechanically enforces them. Agents skip them under load.

Requested behavior:

1. A configurable pre_action_hooks in openclaw config
2. Hooks run before specific tool categories (e.g., exec with git merge, sessions_spawn)
3. Hook can require a WAL entry exists for the current task before proceeding
4. Violations logged and surfaced to the user

---

Implementation Notes (for when we fork)

• WAL file: ~/.openclaw/workspace/.wal (append-only, outside workspace injection)
• State store: could be SQLite in ~/.openclaw/state.db
• Pre-action hooks: defined in ~/.openclaw/config.yml under hooks:
• Compaction snapshot: modify compaction.ts to read active HEARTBEAT.md state before summarizing