[Bug] OpenClaw integration: before_prompt_build hook not triggered for external agents, auto-recall works only for Pi embedded runner

[Suidge]

Bug Description

OpenViking's auto-recall feature works correctly when using OpenClaw's Pi embedded agent, but does not trigger when using external agents (e.g., agent-qwen, agent-codex) via ACP protocol.

Steps to Reproduce

1. Configure OpenClaw with OpenViking context engine:

{
  "contextEngine": "openviking",
  "plugins": {
    "entries": {
      "openviking": {
        "enabled": true,
        "config": {
          "mode": "remote",
          "baseUrl": "http://127.0.0.1:1933",
          "autoRecall": true,
          "autoCapture": true,
          "recallLimit": 6,
          "recallScoreThreshold": 0.2
        }
      }
    }
  }
}

2. Start OpenClaw Gateway and OpenViking server (v0.2.13)

3. Use an external agent (e.g., agent-qwen) to chat

4. Observe OpenViking server logs

Expected Behavior

OpenViking should receive POST /api/v1/search/find requests when external agents process user messages, enabling memory recall for all agent types.

Actual Behavior

• auto-capture works: OpenViking receives POST /api/v1/sessions/.../commit requests
• auto-recall fails: No POST /api/v1/search/find requests are sent
• OpenClaw logs show openviking: registered context-engine (before_prompt_build=auto-recall, afterTurn=auto-capture) but the before_prompt_build hook is never triggered for external agents

Root Cause Analysis

Code Location: OpenClaw's before_prompt_build hook is only called in src/agents/pi-embedded-runner/run/attempt.prompt-helpers.ts

Problem:

1. The before_prompt_build hook runs exclusively in the Pi embedded agent's prompt building phase
2. External agents (agent-qwen, agent-codex, etc.) communicate via ACP protocol and bypass Pi's prompt construction
3. The Gateway does not trigger before_prompt_build when proxying requests to external agents
4. OpenViking's recall logic depends entirely on this hook

Evidence

Working (March 24, 2026)

2026-03-24T08:00:02.094+08:00 [gateway] openviking: injecting 6 memories (~185 tokens, budget=2000)

Broken (April 1, 2026 after restart)

# Only registration logs, no recall execution
openviking: registered context-engine (before_prompt_build=auto-recall, afterTurn=auto-capture)
# No "injecting memories" logs
# No POST /api/v1/search/find in OpenViking logs

OpenViking Server Logs (April 1)

# Only dashboard queries, no recall requests
GET /api/v1/observer/retrieval 200
POST /api/v1/sessions/.../commit 200  # capture works
# NO POST /api/v1/search/find  # recall missing!

Proposed Solutions

Option A: Gateway-level hook execution (Recommended)

Trigger before_prompt_build hook in the Gateway's agent request handler, before forwarding to external agents. This ensures recall works for all agent types uniformly.

Implementation approach:

1. Add before_prompt_build hook execution in Gateway's agent dispatch flow
2. Inject recalled memories into the messages/context sent to external agents
3. External agents receive enriched context without needing to understand OpenViking

Option B: ACP protocol extension

Extend ACP protocol to support context enrichment hooks, allowing plugins to inject context before agent execution.

Option C: External agent configuration

Document that auto-recall only works with Pi embedded runner, and provide guidance for configuring external agents to use Pi runtime.

Environment

• OpenClaw: 2026.3.28
• OpenViking: 0.2.13
• Python: 3.13.x
• OS: macOS 25.4.0 (arm64)
• Mode: remote (OpenViking server at http://127.0.0.1:1933)
• Agents affected: agent-qwen, agent-codex, and all external ACP agents
• Agents working: Pi embedded runner only

Impact

• Users cannot leverage OpenViking memory recall with popular external agents (Codex, Claude Code, etc.)
• Creates inconsistent behavior: capture works for all agents, but recall only works for Pi
• Limits OpenViking's utility in multi-agent deployments

Additional Context

This appears to be an architectural limitation rather than a bug in OpenViking itself. The OpenViking plugin correctly registers the before_prompt_build hook, but OpenClaw's Gateway does not invoke this hook for external agent requests.

Cross-posted to OpenClaw: https://github.com/openclaw/openclaw/issues/XXX