@memtensor/memos-cloud-openclaw-plugin 0.1.15 → 0.1.16-beta.0

package/README.md

@@ -5,7 +5,7 @@ Official plugin maintained by MemTensor.
 A minimal OpenClaw lifecycle plugin that **recalls** memories from MemOS Cloud before each run and **adds** new messages to MemOS Cloud after each run.
 
 ## Features
-- **Recall**: `before_agent_start` → `/search/memory`
+- **Recall**: `before_prompt_build` (`before_agent_start` on older OpenClaw hosts) → `/search/memory`
 - **Add**: `agent_end` → `/add/message`
 - **Config UI**: starting the gateway also starts a local plugin config page for editing `plugins.entries.memos-cloud-openclaw-plugin.config`
 - Uses **Token** auth (`Authorization: Token <MEMOS_API_KEY>`)
@@ -164,7 +164,7 @@ In `plugins.entries.memos-cloud-openclaw-plugin.config`:
 ```
 
 ## How it Works
-- **Recall** (`before_agent_start`)
+- **Recall** (`before_prompt_build`; falls back to `before_agent_start` on older OpenClaw hosts)
   - Builds a `/search/memory` request using `user_id`, `query` (= prompt + optional prefix), and optional filters.
   - Default **global recall**: when `recallGlobal=true`, it does **not** pass `conversation_id`.
   - Optional second-pass filtering: if `recallFilterEnabled=true`, candidates are sent to your configured model and only returned `keep` items are injected.

package/README_ZH.md

@@ -7,7 +7,7 @@
 - **添加记忆**：在每轮对话结束后把消息写回 MemOS Cloud
 
 ## 功能
-- **Recall**：`before_agent_start` → `/search/memory`
+- **Recall**：`before_prompt_build`（旧版 OpenClaw 回退到 `before_agent_start`）→ `/search/memory`
 - **Add**：`agent_end` → `/add/message`
 - **Config UI**：启动 gateway 时同时启动本地插件配置页面，用来编辑 `plugins.entries.memos-cloud-openclaw-plugin.config`
 - 使用 **Token** 认证（`Authorization: Token <MEMOS_API_KEY>`）
@@ -164,7 +164,7 @@ MEMOS_API_KEY=YOUR_TOKEN
 ```
 
 ## 工作原理
-### 1) 召回（before_agent_start）
+### 1) 召回（新版 OpenClaw 使用 `before_prompt_build`；旧版回退到 `before_agent_start`）
 - 组装 `/search/memory` 请求
   - `user_id`、`query`（= prompt + 可选前缀）
   - 默认**全局召回**：`recallGlobal=true` 时不传 `conversation_id`

package/clawdbot.plugin.json

@@ -2,7 +2,7 @@
   "id": "memos-cloud-openclaw-plugin",
   "name": "MemOS Cloud OpenClaw Plugin",
   "description": "MemOS Cloud recall + add memory via lifecycle hooks",
-  "version": "0.1.15",
+  "version": "0.1.16-beta.0",
   "kind": "lifecycle",
   "main": "./index.js",
   "activation": {

package/index.js

@@ -27,6 +27,22 @@ const API_KEY_HELP_URL = "https://memos-dashboard.openmem.net/cn/apikeys/";
 const ENV_FILE_SEARCH_HINTS = ["~/.openclaw/.env", "~/.moltbot/.env", "~/.clawdbot/.env"];
 const MEMOS_SOURCE = "openclaw";
 
+// Heartbeat prompts are always injected at the very beginning of the user
+// content by the host (OpenClaw). Anchoring at start prevents false positives
+// when a legitimate user message happens to mention these phrases.
+const HEARTBEAT_PROMPT_PATTERN =
+  /^\s*(?:Read HEARTBEAT\.md if it exists\b|\[OpenClaw heartbeat poll\])/i;
+const SYSTEM_COMMAND_PATTERN = /^\/(?:new|reset|stop|status|help|dock_|undock)\b/i;
+
+function isHeartbeatPrompt(text) {
+  return typeof text === "string" && HEARTBEAT_PROMPT_PATTERN.test(text);
+}
+
+function isSystemCommandPrompt(text) {
+  if (typeof text !== "string") return false;
+  return SYSTEM_COMMAND_PATTERN.test(text.trimStart());
+}
+
 function warnMissingApiKey(log, context) {
   const heading = "[memos-cloud] Missing MEMOS_API_KEY (Token auth)";
   const header = `${heading}${context ? `; ${context} skipped` : ""}. Configure it with:`;
@@ -178,48 +194,222 @@ export function buildAddMessagePayload(cfg, messages, ctx) {
   return payload;
 }
 
-function pickLastTurnMessages(messages, cfg) {
-  const lastUserIndex = messages
-    .map((m, idx) => ({ m, idx }))
-    .filter(({ m }) => m?.role === "user")
-    .map(({ idx }) => idx)
-    .pop();
-
-  if (lastUserIndex === undefined) return [];
-
-  const slice = messages.slice(lastUserIndex);
-  const results = [];
-
-  for (const msg of slice) {
-    if (!msg || !msg.role) continue;
-    if (msg.role === "user") {
-      const content = stripOpenClawInjectedPrefix(extractText(msg.content));
-      if (content) results.push({ role: "user", content: truncate(content, cfg.maxMessageChars) });
-      continue;
+function convertAssistantMessage(msg, cfg) {
+  const contentArr = Array.isArray(msg.content)
+    ? msg.content
+    : msg.content
+      ? [{ type: "text", text: String(msg.content) }]
+      : [];
+
+  const textContent = contentArr
+    .filter((c) => c?.type === "text")
+    .map((c) => c.text || "")
+    .filter(Boolean)
+    .join("\n");
+
+  const toolCallItems = contentArr.filter((c) => c?.type === "toolCall");
+
+  const result = { role: "assistant" };
+
+  if (textContent) {
+    result.content = truncate(textContent, cfg.maxMessageChars);
+  }
+
+  if (cfg.includeToolMemory && toolCallItems.length > 0) {
+    result.tool_calls = toolCallItems.map((tc) => ({
+      id: tc.id,
+      type: "function",
+      function: {
+        name: tc.name,
+        arguments: typeof tc.arguments === "string" ? tc.arguments : JSON.stringify(tc.arguments ?? {}),
+      },
+    }));
+  }
+
+  if (!result.content && !result.tool_calls) return null;
+  return result;
+}
+
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
+
+// 把单个附件值（URL / data URI / 裸 base64）统一描述成可读 text：
+// - http(s):// / 其它协议 URL：[<kind>: <url>]
+// - data:<mediaType>;base64,...：[<kind> (<mediaType> base64, ~<size> chars)]
+// - 其它（视为裸 base64）：[<kind> (base64, ~<size> chars)]
+function describeAttachment(kind, value) {
+  const dataMatch = /^data:([^;,]+)/i.exec(value);
+  if (dataMatch) {
+    return `[${kind} (${dataMatch[1] || kind} base64, ~${value.length} chars)]`;
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+    return `[${kind}: ${value}]`;
+  }
+  return `[${kind} (base64, ~${value.length} chars)]`;
+}
+
+// MemOS 是文本记忆服务，召回路径上图片/文件 block 几乎只有文本价值。
+// 这里把所有 block 一律归一成 [{type:"text", text}]，但**保留 URL 文字本身**：
+// - text block：透传文本（按 cfg.maxMessageChars 截头）
+// - URL 形态：输出 "[image: <url>]" / "[file: <url>]"，URL 作为可检索文字保留
+// - data URI / base64 形态：输出 "[image (<media_type> base64, ~<size> chars)]" 元数据描述，永不 inline base64
+// - 未识别 type：含 url 字段则 "[<type>: <url>]"，否则 JSON.stringify 兜底
+function normalizeToolResultContent(content, cfg) {
+  const blocks = [];
+
+  const pushText = (raw) => {
+    const text = truncate(String(raw ?? ""), cfg.maxMessageChars);
+    if (text) blocks.push({ type: "text", text });
+  };
+
+  // 解析所有协议下的 image 类 block，提取出统一的"附件值"再交给 describeAttachment 描述。
+  // 覆盖：
+  //   {type:"image_url", image_url:{url}} / {image_url:"<str>"} / 顶层 url   （OpenAI 风格）
+  //   {type:"image", data, media_type} / {type:"image", source:{data, media_type}} （Claude 风格）
+  //   {type:"image", url}                                                        （少见）
+  const tryPushImageBlock = (block) => {
+    const claudeData =
+      (block.source && typeof block.source === "object" && block.source.data) || block.data || "";
+    if (claudeData) {
+      const mediaType =
+        (block.source && typeof block.source === "object" && block.source.media_type) ||
+        block.media_type ||
+        block.mimeType ||
+        "image";
+      pushText(describeAttachment("image", `data:${mediaType};base64,${String(claudeData)}`));
+      return true;
     }
-    if (msg.role === "assistant" && cfg.includeAssistant) {
-      const content = extractText(msg.content);
-      if (content) results.push({ role: "assistant", content: truncate(content, cfg.maxMessageChars) });
+    const url =
+      (block.image_url && typeof block.image_url === "object" && block.image_url.url) ||
+      (typeof block.image_url === "string" ? block.image_url : "") ||
+      block.url ||
+      "";
+    if (!url) return false;
+    pushText(describeAttachment("image", String(url)));
+    return true;
+  };
+
+  // MemOS schema 标准 file block：{type:"file", file:{file_data}}，兼容顶层 file_data。
+  const tryPushFileBlock = (block) => {
+    const fileData =
+      (block.file && typeof block.file === "object" && block.file.file_data) ||
+      block.file_data ||
+      "";
+    if (!fileData) return false;
+    pushText(describeAttachment("file", String(fileData)));
+    return true;
+  };
+
+  const tryPushTypedBlock = (block) => {
+    if (!block || typeof block !== "object") return false;
+    if (block.type === "text") {
+      pushText(block.text);
+      return true;
     }
+    if (block.type === "image_url" || block.type === "image") return tryPushImageBlock(block);
+    if (block.type === "file") return tryPushFileBlock(block);
+    return false;
+  };
+
+  // 未识别 type：有 url 字段则给可读占位，否则整体 stringify。
+  const fallbackSerialize = (block) => {
+    if (
+      block &&
+      typeof block === "object" &&
+      typeof block.type === "string" &&
+      typeof block.url === "string" &&
+      block.url
+    ) {
+      pushText(`[${block.type}: ${block.url}]`);
+      return;
+    }
+    const serialized = safeStringify(block);
+    if (serialized) pushText(serialized);
+  };
+
+  if (content == null || content === "") return blocks;
+
+  if (typeof content === "string") {
+    pushText(content);
+    return blocks;
   }
 
-  return results;
-}
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block == null) continue;
+      if (typeof block === "string") {
+        pushText(block);
+        continue;
+      }
+      if (typeof block !== "object") continue;
+      if (tryPushTypedBlock(block)) continue;
+      fallbackSerialize(block);
+    }
+    return blocks;
+  }
 
-function pickFullSessionMessages(messages, cfg) {
-  const results = [];
-  for (const msg of messages) {
-    if (!msg || !msg.role) continue;
-    if (msg.role === "user") {
-      const content = stripOpenClawInjectedPrefix(extractText(msg.content));
-      if (content) results.push({ role: "user", content: truncate(content, cfg.maxMessageChars) });
+  if (typeof content === "object") {
+    if (!tryPushTypedBlock(content)) {
+      fallbackSerialize(content);
     }
-    if (msg.role === "assistant" && cfg.includeAssistant) {
-      const content = extractText(msg.content);
-      if (content) results.push({ role: "assistant", content: truncate(content, cfg.maxMessageChars) });
+    return blocks;
+  }
+
+  return blocks;
+}
+
+function convertToolResultMessage(msg, cfg) {
+  const toolCallId = msg.toolCallId || msg.tool_call_id;
+  if (!toolCallId) return null;
+  const blocks = normalizeToolResultContent(msg.content, cfg);
+  if (blocks.length === 0) return null;
+  return {
+    role: "tool",
+    tool_call_id: toolCallId,
+    content: blocks,
+  };
+}
+
+// 把 OpenClaw 的单条原始消息转成 MemOS /add/message 接受的形态。
+// 三类 role 分发：user / assistant / toolResult，其它 role（system/...）直接丢弃返 null。
+function convertSessionMessage(msg, cfg) {
+  if (!msg || !msg.role) return null;
+  if (msg.role === "user") {
+    const content = stripOpenClawInjectedPrefix(extractText(msg.content));
+    if (!content) return null;
+    return { role: "user", content: truncate(content, cfg.maxMessageChars) };
+  }
+  if (msg.role === "assistant" && cfg.includeAssistant) {
+    return convertAssistantMessage(msg, cfg);
+  }
+  if (msg.role === "toolResult" && cfg.includeToolMemory) {
+    return convertToolResultMessage(msg, cfg);
+  }
+  return null;
+}
+
+function pickLastTurnMessages(messages, cfg) {
+  let lastUserIndex = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]?.role === "user") {
+      lastUserIndex = i;
+      break;
     }
   }
-  return results;
+  if (lastUserIndex < 0) return [];
+  return messages
+    .slice(lastUserIndex)
+    .map((m) => convertSessionMessage(m, cfg))
+    .filter(Boolean);
+}
+
+function pickFullSessionMessages(messages, cfg) {
+  return messages.map((m) => convertSessionMessage(m, cfg)).filter(Boolean);
 }
 
 function truncate(text, maxLen) {
@@ -447,6 +637,9 @@ export default {
     // Start 12-hour background update interval
     startUpdateChecker(log);
 
+    // Detect the host CLI version once so every hook registration branch can reference it.
+    const hostVersion = detectHostVersion();
+
     // Side effects below are only meaningful when the host CLI was actually
     // launched to run the gateway (`openclaw gateway run|start|restart`).
     // Other entry points (e.g. `plugins install`, `security audit`) also
@@ -458,11 +651,8 @@ export default {
     //     misleading "probe timed out" warning before the process exits.
     // Gate them all in one place so the policy is explicit and discoverable.
     if (isGatewayRuntimeStartup()) {
-      // Detect the host CLI version once so every branch below can reference it.
       // `allowConversationAccess` hook policy was introduced in 2026.4.23;
       // older hosts do not understand the field and don't need it patched in.
-      const hostVersion = detectHostVersion();
-
       const HOOK_POLICY_MIN_VERSION = "2026.4.23";
       const needsHookPolicy =
         hostVersion === null ||
@@ -529,7 +719,17 @@ export default {
       );
     }
 
-    api.on("before_agent_start", async (event, ctx) => {
+    const runRecall = async (event, ctx) => {
+      // Skip system events: heartbeat, /new, /reset, and other commands
+      const prompt = event?.prompt || "";
+      const isHeartbeat = isHeartbeatPrompt(prompt);
+      const isSystemCommand = isSystemCommandPrompt(prompt);
+
+      if (isHeartbeat || isSystemCommand) {
+        log.info?.(`[memos-cloud] recall skipped: system event detected (heartbeat=${isHeartbeat}, command=${isSystemCommand}, prompt="${prompt.substring(0, 50)}...")`);
+        return;
+      }
+
       if (!isAgentAllowed(cfg, ctx)) {
         log.info?.(`[memos-cloud] recall skipped: agent "${ctx?.agentId}" not in allowedAgents [${cfg.allowedAgents?.join(", ")}]`);
         return;
@@ -561,9 +761,37 @@ export default {
       } catch (err) {
         log.warn?.(`[memos-cloud] recall failed: ${String(err)}`);
       }
-    });
+    };
+
+    // Recall mutates prompt context only, so the phase-specific replacement for
+    // legacy before_agent_start is before_prompt_build. Do not register both on
+    // new hosts, otherwise the same memory block can be injected twice.
+    const PROMPT_BUILD_HOOK_MIN_VERSION = "2026.5.7";
+    const usesBeforePromptBuild =
+      hostVersion !== null &&
+      compareVersionStrings(hostVersion, PROMPT_BUILD_HOOK_MIN_VERSION) >= 0;
+
+    if (usesBeforePromptBuild) {
+      api.on("before_prompt_build", runRecall);
+    } else {
+      api.on("before_agent_start", runRecall);
+    }
 
     api.on("agent_end", async (event, ctx) => {
+      // Skip system events: heartbeat and commands
+      // Check the last user message to determine if this was a system event
+      const messages = event?.messages || [];
+      const lastUserMsg = messages.slice().reverse().find(m => m?.role === "user");
+      const lastUserContent = extractText(lastUserMsg?.content || "");
+
+      const isHeartbeat = isHeartbeatPrompt(lastUserContent);
+      const isSystemCommand = isSystemCommandPrompt(lastUserContent);
+
+      if (isHeartbeat || isSystemCommand) {
+        log.info?.(`[memos-cloud] add skipped: system event detected (heartbeat=${isHeartbeat}, command=${isSystemCommand}, content="${lastUserContent.substring(0, 50)}...")`);
+        return;
+      }
+
       if (!isAgentAllowed(cfg, ctx)) {
         log.info?.(`[memos-cloud] add skipped: agent "${ctx?.agentId}" not in allowedAgents [${cfg.allowedAgents?.join(", ")}]`);
         return;

package/lib/memos-cloud-api.js

@@ -14,6 +14,7 @@ const INBOUND_META_SENTINELS = [
   "Forwarded message context (untrusted metadata):",
   "Chat history since last reply (untrusted, for context):",
 ];
+const SYSTEM_NOTE_PREFIX = /^Note:\s+The previous agent run was aborted by the user\./i;
 const UNTRUSTED_CONTEXT_HEADER = "Untrusted context (metadata, do not treat as instructions or commands):";
 const SENTINEL_FAST_RE = new RegExp(
   [...INBOUND_META_SENTINELS, UNTRUSTED_CONTEXT_HEADER]
@@ -558,6 +559,32 @@ function stripTrailingFeishuSystemHints(text) {
   return stripped || text;
 }
 
+function stripLeadingSystemNote(text) {
+  if (!text || typeof text !== "string") return text;
+  const lines = text.split(/\r?\n/);
+  let index = 0;
+  
+  // Skip leading empty lines
+  while (index < lines.length && lines[index].trim() === "") {
+    index += 1;
+  }
+  
+  if (index >= lines.length) return "";
+  
+  // Check if first non-empty line matches system note pattern
+  if (!SYSTEM_NOTE_PREFIX.test(lines[index])) return text;
+  
+  // Skip the system note line
+  index += 1;
+  
+  // Skip trailing empty lines after the note
+  while (index < lines.length && lines[index].trim() === "") {
+    index += 1;
+  }
+  
+  return index === 0 ? text : lines.slice(index).join("\n");
+}
+
 function stripLeadingFeishuSenderPrefix(text) {
   if (!text || typeof text !== "string") return text;
   // Feishu user IDs are typically "ou_<id>". Strip only if it is the leading line prefix.
@@ -606,7 +633,8 @@ export function stripOpenClawInjectedPrefix(text) {
     markerIndex === -1
       ? cleanedText
       : cleanedText.slice(markerIndex + USER_QUERY_MARKER.length);
-  const withoutInboundMetadata = stripLeadingInboundMetadata(withoutRecallPrefix).trimStart();
+  const withoutSystemNote = stripLeadingSystemNote(withoutRecallPrefix).trimStart();
+  const withoutInboundMetadata = stripLeadingInboundMetadata(withoutSystemNote).trimStart();
   const withoutMessageIdHints = stripLeadingMessageIdHints(withoutInboundMetadata).trimStart();
   const withoutEnvelope = stripLeadingEnvelope(withoutMessageIdHints).trimStart();
   const withoutTrailingSystemHints = stripTrailingFeishuSystemHints(withoutEnvelope).trimStart();
@@ -675,13 +703,12 @@ function wrapCodeBlock(lines, options = {}) {
 function buildMemorySections(data, options = {}) {
   const memoryList = data?.memory_detail_list ?? [];
   const preferenceList = data?.preference_detail_list ?? [];
+  const toolMemoryList = data?.tool_memory_detail_list ?? [];
+
+  const threshold = options.relativity ?? 0;
 
   const memoryLines = memoryList
-    .filter((item) => {
-      const score = item?.relativity ?? 1;
-      const threshold = options.relativity ?? 0;
-      return score > threshold;
-    })
+    .filter((item) => (item?.relativity ?? 1) > threshold)
     .map((item) => {
       const text = item?.memory_value || item?.memory_key || "";
       return formatMemoryLine(item, text, options);
@@ -689,18 +716,22 @@ function buildMemorySections(data, options = {}) {
     .filter(Boolean);
 
   const preferenceLines = preferenceList
-    .filter((item) => {
-      const score = item?.relativity ?? 1;
-      const threshold = options.relativity ?? 0;
-      return score > threshold;
-    })
+    .filter((item) => (item?.relativity ?? 1) > threshold)
     .map((item) => {
       const text = item?.preference || "";
       return formatPreferenceLine(item, text, options);
     })
     .filter(Boolean);
 
-  return { memoryLines, preferenceLines };
+  const toolMemoryLines = toolMemoryList
+    .filter((item) => (item?.relativity ?? 1) > threshold)
+    .map((item) => {
+      const text = item?.tool_value || "";
+      return formatMemoryLine(item, text, options);
+    })
+    .filter(Boolean);
+
+  return { memoryLines, preferenceLines, toolMemoryLines };
 }
 
 const STATIC_RECALL_SYSTEM_PROMPT = [
@@ -752,8 +783,8 @@ const STATIC_RECALL_SYSTEM_PROMPT = [
 ].join("\n");
 
 function buildMemoryPrependBlock(data, options = {}) {
-  const { memoryLines, preferenceLines } = buildMemorySections(data, options);
-  const hasContent = memoryLines.length > 0 || preferenceLines.length > 0;
+  const { memoryLines, preferenceLines, toolMemoryLines } = buildMemorySections(data, options);
+  const hasContent = memoryLines.length > 0 || preferenceLines.length > 0 || toolMemoryLines.length > 0;
   if (!hasContent) return "";
 
   const memoriesBlock = [
@@ -761,6 +792,9 @@ function buildMemoryPrependBlock(data, options = {}) {
     "  <facts>",
     ...memoryLines,
     "  </facts>",
+    "  <tool_memories>",
+    ...toolMemoryLines,
+    "  </tool_memories>",
     "  <preferences>",
     ...preferenceLines,
     "  </preferences>",

package/moltbot.plugin.json

@@ -2,7 +2,7 @@
   "id": "memos-cloud-openclaw-plugin",
   "name": "MemOS Cloud OpenClaw Plugin",
   "description": "MemOS Cloud recall + add memory via lifecycle hooks",
-  "version": "0.1.15",
+  "version": "0.1.16-beta.0",
   "kind": "lifecycle",
   "main": "./index.js",
   "activation": {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memos-cloud-openclaw-plugin",
   "name": "MemOS Cloud OpenClaw Plugin",
   "description": "MemOS Cloud recall + add memory via lifecycle hooks",
-  "version": "0.1.15",
+  "version": "0.1.16-beta.0",
   "kind": "lifecycle",
   "main": "./index.js",
   "activation": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memtensor/memos-cloud-openclaw-plugin",
-  "version": "0.1.15",
+  "version": "0.1.16-beta.0",
   "description": "OpenClaw lifecycle plugin for MemOS Cloud (add + recall memory)",
   "scripts": {
     "sync-version": "node scripts/sync-version.js",

package/test/recall-hook-registration.test.mjs

@@ -0,0 +1,56 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import plugin from "../index.js";
+
+const createApi = (hostVersion) => {
+  const registeredHooks = [];
+  const originalArgv1 = process.argv[1];
+  process.argv[1] = `C:\\Users\\lee\\AppData\\Local\\pnpm\\global\\5\\.pnpm\\openclaw@${hostVersion}\\node_modules\\openclaw\\openclaw.mjs`;
+
+  const api = {
+    config: { hooks: { internal: { enabled: false } } },
+    logger: {},
+    pluginConfig: {
+      apiKey: "mpg-test",
+      recallEnabled: false,
+      addEnabled: false,
+    },
+    on: (hookName, handler) => {
+      registeredHooks.push({ hookName, handler });
+    },
+    registerHook: () => {},
+  };
+
+  return {
+    api,
+    registeredHooks,
+    restore: () => {
+      process.argv[1] = originalArgv1;
+    },
+  };
+};
+
+test("registers before_prompt_build on OpenClaw hosts that support the phase-specific hook", () => {
+  const { api, registeredHooks, restore } = createApi("2026.5.7");
+  try {
+    plugin.register(api);
+  } finally {
+    restore();
+  }
+
+  assert.ok(registeredHooks.some((hook) => hook.hookName === "before_prompt_build"));
+  assert.ok(!registeredHooks.some((hook) => hook.hookName === "before_agent_start"));
+});
+
+test("falls back to before_agent_start on older OpenClaw hosts", () => {
+  const { api, registeredHooks, restore } = createApi("2026.4.26");
+  try {
+    plugin.register(api);
+  } finally {
+    restore();
+  }
+
+  assert.ok(registeredHooks.some((hook) => hook.hookName === "before_agent_start"));
+  assert.ok(!registeredHooks.some((hook) => hook.hookName === "before_prompt_build"));
+});