@xyagent/cli 0.0.1

package/src-ext/openclaw-plugin/index.cjs

@@ -0,0 +1,1919 @@
+// Agentlink OpenClaw hooks plugin.
+//
+// Uses api.on() (typed hook registration) to capture tool call, subagent and
+// agent_end lifecycle events, then POSTs them as **unified Agent Protocol
+// envelopes** to relay /v1/agents/threads/<thread_id>/events.
+//
+// (Pre-2026-05 this plugin posted to the legacy /v1/gateways/<gw>/chat-events
+//  endpoint, which has been retired server-side; see PLUGIN_ACTIVE_RUNS.md.)
+//
+// Loaded by OpenClaw via `openclaw plugins install --link <plugin-dir>` which
+// is wrapped by `agentlink pair` / `agentlink setup` / `ensureAgentlinkHooksPlugin`.
+//
+// Credential source: ~/.agentlink/config.json (written by `agentlink pair`).
+//
+// Verbose dump: set `agentlinkHooksVerbose: true` in the same config file
+// to dump every hook event to OpenClaw log. Auto-expires after 24h
+// (set `agentlinkHooksVerboseUntil: <unix-ms>` to override).
+//
+// Hardening (vs. the first cut):
+//   • fetch() has a 5s AbortController timeout — no more dangling promises.
+//   • Failed POSTs are throttled to ≤1 warn / 60s — silent before, blind ops.
+//   • Large payloads are truncated to ~256KB — server LimitReader is 2MB.
+//   • This plugin always uses OpenClaw credentials (relayGatewayId / Token)
+//     regardless of state.runtimeKind: it loads inside the OpenClaw daemon,
+//     so hooks only fire when OpenClaw is the active runtime — sending to
+//     hermes credentials would be incorrect.
+//   • Per-callId serial queue keeps before/after order under network jitter.
+//   • Verbose dumps redact obvious secrets (Bearer ..., sk-..., AKIA*).
+//   • On 401 we re-read config.json once (token may have been rotated by
+//     `agentlink pair` while OpenClaw is still up); reset retry guard on success.
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+
+// Auto-generated by scripts/build-openclaw-plugin.mjs. Wrapped in try/catch so a
+// missing build artifact degrades gracefully instead of crashing the daemon.
+let envelopeBuilder = null;
+let envelopeBuilderLoadError = null;
+try {
+  envelopeBuilder = require("./envelope-builder.cjs");
+} catch (err) {
+  envelopeBuilderLoadError = err;
+}
+
+// todoTranslatorUtils.cjs is generated alongside envelope-builder.cjs by the
+// same build script. Required for update_plan → todo_list block translation.
+// Degrades gracefully: if the artifact is missing, update_plan falls through
+// to the normal tool_use path (no crash).
+let todoUtils = null;
+try {
+  todoUtils = require("./todoTranslatorUtils.cjs");
+} catch {
+  // Build artifact missing — update_plan will transparently fall through.
+}
+
+// relay-defaults is copied alongside envelope-builder by the same build script
+// (was previously a forbidden cross-dir require("../../src-shared/...")).
+let DEFAULT_RELAY_URL = "";
+try {
+  ({ defaultRelayUrl: DEFAULT_RELAY_URL } = require("./relay-defaults.json"));
+} catch {
+  // Plugin will warn at register() time if defaults are missing.
+}
+const FETCH_TIMEOUT_MS = 5000;
+const PAYLOAD_TRUNCATE_BYTES = 256 * 1024;     // 256 KB per payload
+const WARN_THROTTLE_MS = 60_000;                // ≤ 1 warn / minute
+const VERBOSE_DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const SECRET_PATTERNS = [
+  /Bearer\s+[A-Za-z0-9._\-]+/g,
+  /\bsk-[A-Za-z0-9_-]{16,}/g,
+  /\bAKIA[0-9A-Z]{12,}/g,
+  /\b[A-Za-z0-9]{20,}\.[A-Za-z0-9]{20,}\.[A-Za-z0-9_-]{20,}/g, // JWT-shaped
+];
+
+function configPath() {
+  return path.join(os.homedir(), ".agentlink", "config.json");
+}
+
+function readAgentlinkState() {
+  try {
+    return JSON.parse(fs.readFileSync(configPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function pickGatewayCreds(state) {
+  // Always OpenClaw credentials — this plugin only sees events that fire
+  // inside the OpenClaw daemon, regardless of which runtime the user picked
+  // for their App-side conversation.
+  return {
+    gatewayId: String(state?.relayGatewayId || "").trim(),
+    gatewayToken: String(state?.relayGatewayToken || "").trim(),
+  };
+}
+
+function resolveRelayUrl(state) {
+  const fromState = typeof state?.relayUrl === "string" ? state.relayUrl.trim() : "";
+  return fromState || DEFAULT_RELAY_URL;
+}
+
+function isVerboseEnabled(state) {
+  if (state?.agentlinkHooksVerbose !== true) return false;
+  // Optional explicit expiry; default to 24h after the bridge process started
+  // (effectively turning off after a daemon restart > 24h with the flag still
+  // on but never refreshed). The conservative choice: respect the flag while
+  // process is up — users debugging want it sticky during their session.
+  const until = Number(state?.agentlinkHooksVerboseUntil);
+  if (Number.isFinite(until) && until > 0) {
+    return Date.now() < until;
+  }
+  return true;
+}
+
+function redactSecrets(text) {
+  let out = text;
+  for (const re of SECRET_PATTERNS) {
+    out = out.replace(re, "[REDACTED]");
+  }
+  return out;
+}
+
+// Truncate any field whose JSON-encoded form exceeds the byte budget.
+// Preserves shape: replaces big string with prefix + tag, big object with
+// {_truncated, _size, _preview}.
+function truncatePayload(value, budget = PAYLOAD_TRUNCATE_BYTES) {
+  try {
+    const encoded = JSON.stringify(value);
+    if (encoded == null || Buffer.byteLength(encoded, "utf8") <= budget) {
+      return value;
+    }
+    const preview = encoded.slice(0, Math.max(1024, Math.floor(budget / 4)));
+    return {
+      _truncated: true,
+      _originalSize: Buffer.byteLength(encoded, "utf8"),
+      _preview: preview,
+    };
+  } catch {
+    return { _truncated: true, _serializeFailed: true };
+  }
+}
+
+function hostHash() {
+  try {
+    return crypto.createHash("sha256")
+      .update(os.hostname() + ":" + os.userInfo().username)
+      .digest("hex").slice(0, 12);
+  } catch {
+    return "";
+  }
+}
+
+// ── Auto-attach: 扫 assistant 文本里的本机路径 → 调 agentlink_attach_file ──
+//
+// 跑在 OpenClaw daemon 进程，从 ~/.agentlink/tools-server.json 读 bridge 起的
+// tools server URL+auth，POST /tools/call 走 attach_file 工具。bridge 没在跑
+// (discovery 缺失) → 安静跳过，等 bridge 起来后下一轮自然生效。
+//
+// dedup: 模块级 Map<absPath, mtimeMs>; mtime 变了重传 (自然支持 agent 改文件)。
+//
+// 与 ESM 侧 bridgeAttachAutoScanner.mjs 的正则保持一致 (人工同步)。
+const AUTO_ATTACH_PATH_REGEX =
+  /(?<![A-Za-z0-9_.+\-/~])(?:file:\/\/)?(?:~|\/)(?:\/?[A-Za-z0-9_.+\-]+)+/g;
+
+const _autoAttachDedup = new Map(); // absPath → mtimeMs
+const _autoAttachDiscoveryPath = path.join(os.homedir(), ".agentlink", "tools-server.json");
+
+function extractLocalPathsFromText(text) {
+  const out = new Set();
+  if (!text || typeof text !== "string") return out;
+  AUTO_ATTACH_PATH_REGEX.lastIndex = 0;
+  let m;
+  while ((m = AUTO_ATTACH_PATH_REGEX.exec(text)) !== null) {
+    let raw = m[0];
+    if (raw.startsWith("file://")) raw = raw.slice(7);
+    while (raw.length > 1 && /[.,;:!?)\]}"'<>\/]$/.test(raw)) raw = raw.slice(0, -1);
+    if (!raw || raw === "~") continue;
+    const lastSlash = raw.lastIndexOf("/");
+    const basename = lastSlash >= 0 ? raw.slice(lastSlash + 1) : raw;
+    if (!basename.includes(".") || basename === "." || basename === "..") continue;
+    if (raw.startsWith("~/")) raw = path.join(os.homedir(), raw.slice(2));
+    if (!raw.startsWith("/")) continue;
+    try { out.add(path.resolve(raw)); } catch { /* swallow */ }
+  }
+  return out;
+}
+
+function readAutoAttachDiscoverySync() {
+  try {
+    const raw = fs.readFileSync(_autoAttachDiscoveryPath, "utf8");
+    const doc = JSON.parse(raw);
+    if (typeof doc?.url === "string" && typeof doc?.auth === "string") return doc;
+  } catch { /* missing or malformed → null */ }
+  return null;
+}
+
+// fire-and-forget；caller 永远 void this。所有 path err 内部吞掉只 log。
+async function autoAttachScanAndDispatch(assistantText, { log, warnThrottled }) {
+  const candidates = extractLocalPathsFromText(assistantText);
+  if (candidates.size === 0) return;
+  log.info(`auto-attach.scan.matched count=${candidates.size} paths=${JSON.stringify([...candidates])}`);
+  const disc = readAutoAttachDiscoverySync();
+  if (!disc) {
+    log.info(`auto-attach.skip: tools-server discovery missing (bridge not running?) candidates=${[...candidates].join(",")}`);
+    return;
+  }
+  for (const rawAbsPath of candidates) {
+    let absPath = rawAbsPath;
+    let st;
+    try {
+      st = fs.statSync(absPath);
+    } catch (err) {
+      if (err && err.code === "ENOENT") {
+        // ★ workspace fallback: agent 经常把路径写错(`~/hello.txt`)而实际文件
+        // 在 `~/.openclaw/workspace/hello.txt`。这里取 basename 去 workspace
+        // 目录里找,命中就用真实路径继续。这对 agent 行为容错很关键。
+        const resolved = resolveInOpenClawWorkspace(absPath);
+        if (resolved) {
+          try {
+            st = fs.statSync(resolved);
+            absPath = resolved;
+            log.info(`auto-attach.workspace_fallback hit path=${rawAbsPath} resolved=${resolved}`);
+          } catch {
+            log.info(`auto-attach.skip.not_found path=${rawAbsPath} (workspace fallback also missing: ${resolved})`);
+            continue;
+          }
+        } else {
+          log.info(`auto-attach.skip.not_found path=${rawAbsPath}`);
+          continue;
+        }
+      } else {
+        log.info(`auto-attach.skip.stat_failed path=${absPath} err=${err?.code || err?.message}`);
+        continue;
+      }
+    }
+    if (!st.isFile()) {
+      log.info(`auto-attach.skip.not_file path=${absPath}`);
+      continue;
+    }
+    const prev = _autoAttachDedup.get(absPath);
+    if (prev === st.mtimeMs) {
+      log.info(`auto-attach.skip.unchanged path=${absPath} mtimeMs=${st.mtimeMs}`);
+      continue;
+    }
+    _autoAttachDedup.set(absPath, st.mtimeMs);
+    log.info(`auto-attach.start path=${absPath} size=${st.size}`);
+
+    // ── 预测式 sidecar 写入 ─────────────────────────────────────────
+    // 真正 PUT 完成前, 用 prefix cache + 本地 sha256 算 publicUrl, 立刻写
+    // sidecar。这样 App 第一次 fetch workspace file 时就有 publicUrl,
+    // 即便上传还在进行中。如果 PUT 还没完, App fetch COS URL 拿到 404,
+    // App 端 loadText 会 fallback 到 inline content/loadWorkspaceFile。
+    // 上传完成后, real publicUrl 会再次覆写 sidecar(同一对象 URL,无害)。
+    try {
+      const prefix = readCosPrefixCacheSync();
+      if (prefix) {
+        const buf = fs.readFileSync(absPath);
+        const sha256 = crypto.createHash("sha256").update(buf).digest("hex");
+        const ext = inferExtForCos(absPath);
+        const predictedUrl = `${prefix}/${sha256}${ext ? "." + ext : ""}`;
+        writeWorkspaceAttachSidecar({
+          absPath,
+          publicUrl: predictedUrl,
+          sha256,
+          mtimeMs: st.mtimeMs,
+          size: st.size,
+        });
+        log.info(`auto-attach.sidecar.predicted path=${absPath} url=${predictedUrl}`);
+      } else {
+        log.debug(`auto-attach.sidecar.predict.skip: no prefix cache yet (waiting for first upload)`);
+      }
+    } catch (err) {
+      log.warn(`auto-attach.sidecar.predict.failed path=${absPath} err=${err?.message || err}`);
+    }
+
+    let res, body;
+    const ctl = new AbortController();
+    const tid = setTimeout(() => ctl.abort(), 30_000);
+    try {
+      res = await fetch(`${disc.url.replace(/\/+$/, "")}/tools/call`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${disc.auth}`,
+        },
+        body: JSON.stringify({
+          name: "agentlink_attach_file",
+          arguments: { path: absPath, reason: "auto-scan" },
+        }),
+        signal: ctl.signal,
+      });
+      body = await res.json();
+    } catch (err) {
+      _autoAttachDedup.delete(absPath); // 允许下次重试
+      warnThrottled(`auto-attach.fetch.threw path=${absPath} err=${err?.message || err}`);
+      continue;
+    } finally {
+      clearTimeout(tid);
+    }
+    // ⚠ 注意:此处用**完整** text parse JSON,不能 slice。result 字符串通常
+    // 250+ 字符(URL 130 + sha256 64 + 其它),slice(200) 会在 url 中间截断
+    // 导致 JSON.parse 抛 "Unterminated string"。log 那条另用 truncated summary。
+    const resultText = String(body?.content?.[0]?.text || "");
+    const logSummary = resultText.slice(0, 400);
+    if (body?.isError) {
+      _autoAttachDedup.delete(absPath); // 工具拒了 → 允许重试 (e.g. denylist 后续改)
+      log.warn(`auto-attach.failed path=${absPath} reason=${logSummary}`);
+    } else {
+      log.info(`auto-attach.ok path=${absPath} result=${logSummary}`);
+      // 把 publicUrl / sha256 / mtime 写到 sidecar 文件让 server 端能 inject
+      // 进 workspace file DTO。sidecar 位于同目录 .agentlink-cos/<basename>.json,
+      // 命中后 App 拿到的 ChatWorkspaceFileMeta 就会带 publicUrl, preview 走 COS。
+      try {
+        const parsed = JSON.parse(resultText);
+        if (parsed?.ok && parsed?.url) {
+          writeWorkspaceAttachSidecar({
+            absPath,
+            publicUrl: String(parsed.url),
+            sha256: String(parsed.sha256 || ""),
+            mtimeMs: st.mtimeMs,
+            size: st.size,
+          });
+        }
+      } catch (err) {
+        log.warn(`auto-attach.sidecar.failed path=${absPath} err=${err?.message || err} raw=${resultText.slice(0, 120)}`);
+      }
+    }
+  }
+}
+
+// 读 cosUploadClient 学习并 cache 的 publicUrl prefix(到 userID 一级,不含
+// trailing /)。plugin 拿它本地拼 sha256+ext 预测 publicUrl,在真传完成前就把
+// sidecar 写好。CJS 不能 import ESM,直接读 ESM 那边的 cache 文件即可——格式
+// 一致(见 cosUploadClient.mjs writeCosPrefixCache)。
+const COS_PREFIX_CACHE_PATH = path.join(os.homedir(), ".agentlink", "cos-prefix-cache.json");
+
+// Workspace fallback: agent 经常把绝对路径写错(典型场景 `~/hello.txt` 但实
+// 际文件在 `~/.openclaw/workspace/hello.txt`)。当 regex 抓到的 path
+// fs.stat 抛 ENOENT 时, 用 basename 去 OpenClaw workspace 目录里再找一次。
+// workspace 目录: OPENCLAW_HOME/workspace (默认 ~/.openclaw/workspace)。
+//
+// 返回的是 workspace 内的真实绝对路径(如果同 basename 存在), 否则 null。
+function resolveInOpenClawWorkspace(rawPath) {
+  try {
+    const base = path.basename(rawPath);
+    if (!base || base === "." || base === ".." || base.includes("/")) return null;
+    const openclawHome = (process.env.OPENCLAW_HOME || path.join(os.homedir(), ".openclaw")).trim();
+    if (!openclawHome) return null;
+    const candidate = path.join(openclawHome, "workspace", base);
+    // 防 path traversal:确保 candidate 真在 workspace 子树里
+    const workspaceRoot = path.join(openclawHome, "workspace");
+    const resolved = path.resolve(candidate);
+    if (!resolved.startsWith(workspaceRoot + path.sep) && resolved !== workspaceRoot) {
+      return null;
+    }
+    return resolved;
+  } catch { return null; }
+}
+
+function readCosPrefixCacheSync() {
+  try {
+    const raw = fs.readFileSync(COS_PREFIX_CACHE_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    const p = typeof parsed?.prefix === "string" ? parsed.prefix.trim() : "";
+    if (!p || !/^https?:\/\//.test(p)) return null;
+    return p.replace(/\/+$/, "");
+  } catch { return null; }
+}
+
+// 跟 cosUploadClient.mjs / EXT_TO_MIME 对应的扩展名探测(简化版)。无扩展返回
+// 空串,与 server buildSHA256ObjectKey 行为对齐(无 ext = leaf 不带点)。
+function inferExtForCos(absPath) {
+  const base = path.basename(absPath);
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0 || dot === base.length - 1) return "";
+  return base.slice(dot + 1).toLowerCase();
+}
+
+// 把 attach 结果写到 sidecar JSON 文件: <dir>/.agentlink-cos/<basename>.json。
+// server (go_relay) 在 fetchAgentWorkspaceFile 时读这个文件,把 publicUrl 注入 DTO。
+// 同步写,失败只 swallow——丢一次 sidecar = 这次 App 不走 COS, 下次自然重试。
+function writeWorkspaceAttachSidecar({ absPath, publicUrl, sha256, mtimeMs, size }) {
+  const dir = path.dirname(absPath);
+  const base = path.basename(absPath);
+  const sidecarDir = path.join(dir, ".agentlink-cos");
+  const sidecarPath = path.join(sidecarDir, base + ".json");
+  try {
+    fs.mkdirSync(sidecarDir, { recursive: true });
+    fs.writeFileSync(
+      sidecarPath,
+      JSON.stringify({ publicUrl, sha256, mtimeMs, size, ts: Date.now() }),
+      { mode: 0o600 },
+    );
+  } catch {
+    // best-effort; 下次 attach 再写
+  }
+}
+
+// Bridge-managed run-context lookup. CLI bridge writes
+// `~/.agentlink/active-runs/<runId>.json` at dispatch entry; plugin reads it
+// on every hook so it can POST envelopes to the matching thread_id.
+//
+// Fallback by key: OpenClaw exposes the original session key (often the
+// unified thread_id) under both `ctx.sessionKey` and `ctx.runId` for
+// different dispatch flows; we try matching files for both keys before
+// giving up.
+//
+// Any failure (missing file, parse error, expired) returns null silently —
+// the caller drops that hook with no log spam.
+function loadRunContextFile(key) {
+  if (!key) return null;
+  try {
+    const dir = path.join(os.homedir(), ".agentlink", "active-runs");
+    const file = path.join(dir, `${key}.json`);
+    const raw = fs.readFileSync(file, "utf8");
+    const ctx = JSON.parse(raw);
+    if (typeof ctx?.expires_at === "number" && ctx.expires_at < Date.now()) {
+      return null;
+    }
+    if (!ctx?.thread_id) return null;
+    return ctx;
+  } catch {
+    return null;
+  }
+}
+
+// Resolve the unified thread_id + run_id + relay_url for the current hook ctx.
+//
+// CLI bridge writes `~/.agentlink/active-runs/<key>.json` under **two** keys
+// — thread_id AND run_id — pointing to the same JSON body. The OpenClaw
+// dispatch enqueue sets `SessionKey = run_id` on the relay request, so
+// `ctx.sessionKey` in plugin hooks is `run_<ULID>` (NOT thread_id), but
+// some dispatch flows may set sessionKey to thread_id directly. We try
+// each candidate from ctx in priority order and the first hit wins.
+//
+// Returns { thread_id, run_id, relay_url, isFallback } or null.
+//
+// isFallback:true 表示 active-runs/<key>.json 已经不存在（bridge 把那一轮
+// dispatch cleanup 了），但能从某个 ctx 字段里还原出 thr_<ULID> thread_id。
+// 这往往意味着这次 hook fire 是 OpenClaw daemon 在主 dispatch 结束后**自发**
+// 触发的（subagent 完成后 daemon 内部投递 task-completion user message + 自起
+// 新一轮 LLM 调用，daemon UI 通过 WS 收到，但 bridge 那条 /v1/responses
+// SSE 已 EOF 不再监听）。调用方应据此把这一轮 reply 也补发到 relay。
+//
+// ctx.sessionKey 在 daemon 自发轮里有两种已知形态:
+//   1. 主链路: 干净 "thr_01KRK..." (ULID 全大写)
+//   2. 自发轮: "agent:main:thr_01krk..." (带 agent 前缀,且 daemon **小写化**了 ULID)
+// 必须同时支持两种:从字符串里**抽取** thr_<26 chars> 子串、并按 active-runs/
+// 文件实际命名 (server-issued ULID 原样,即大写) 还原。
+const THREAD_ID_PATTERN = /thr_[0-9A-Za-z]{26}/;
+function extractThreadId(s) {
+  if (!s) return "";
+  const m = THREAD_ID_PATTERN.exec(s);
+  return m ? m[0] : "";
+}
+// thread_id 在 server-issued 时是 "thr_" 小写前缀 + 26 字符 Crockford Base32
+// **大写** ULID。daemon 在某些场景 (例如 ctx.sessionKey = "agent:main:thr_xxx")
+// 把整个串小写化,需要还原 ULID 部分到大写而保持前缀小写。
+function canonicalThreadId(threadId) {
+  if (!threadId) return "";
+  if (threadId.startsWith("thr_")) return "thr_" + threadId.slice(4).toUpperCase();
+  if (threadId.startsWith("THR_")) return "thr_" + threadId.slice(4).toUpperCase();
+  return threadId;
+}
+// active-runs 文件名是 server-issued ULID 原样 (Crockford Base32,全大写);
+// daemon 给 plugin 的 ctx.sessionKey 里 thr_ 子串可能被小写化,这里两种大小写
+// 都试一遍,谁命中就用谁。
+function loadRunContextByThreadId(threadId) {
+  if (!threadId) return null;
+  return loadRunContextFile(threadId)
+    || loadRunContextFile(canonicalThreadId(threadId))
+    || loadRunContextFile(threadId.toLowerCase());
+}
+
+function resolveHookContext(ctx, fallbackRelayUrl) {
+  const candidates = [
+    String(ctx?.sessionKey || "").trim(),
+    String(ctx?.runId || "").trim(),
+    String(ctx?.sessionId || "").trim(),
+  ].filter(Boolean);
+
+  // 第一遍:把任意 candidate 当 key 直接试 — 主链路 ctx.sessionKey 就是
+  // 干净 thr_xxx 时这条命中。
+  for (const key of candidates) {
+    const file = loadRunContextFile(key);
+    if (file && file.thread_id) {
+      return {
+        thread_id: file.thread_id,
+        run_id: file.run_id || ctx?.runId || "",
+        relay_url: file.relay_url || fallbackRelayUrl,
+        isFallback: false,
+      };
+    }
+  }
+  // 第二遍:从任意 candidate 里抽出 thr_<ULID> 子串再试 — 兼容 daemon 自发轮
+  // ctx.sessionKey = "agent:main:thr_xxx" 这种带前缀形态。命中 file 表示
+  // dispatch 还没 cleanup,仍走主链路。
+  for (const key of candidates) {
+    const tid = extractThreadId(key);
+    if (!tid) continue;
+    const file = loadRunContextByThreadId(tid);
+    if (file && file.thread_id) {
+      return {
+        thread_id: file.thread_id,
+        run_id: file.run_id || ctx?.runId || "",
+        relay_url: file.relay_url || fallbackRelayUrl,
+        isFallback: false,
+      };
+    }
+  }
+  // 第三遍 (fallback): file 都不在了,但能从 candidate 里抽到 thr_<ULID> 子串
+  // → 这就是「daemon 自发轮」信号,caller 应把这一轮 reply 也补发到 relay。
+  // thread_id 用大写形式 (与 server-issued ULID 一致;daemon 内部小写只是输出
+  // 习惯),否则 server 校验 envelope.thread_id 会失败。
+  for (const key of candidates) {
+    const tid = extractThreadId(key);
+    if (tid) {
+      return {
+        thread_id: canonicalThreadId(tid),
+        run_id: ctx?.runId || "",
+        relay_url: fallbackRelayUrl,
+        isFallback: true,
+      };
+    }
+  }
+  return null;
+}
+
+// Deterministic child run_id derivation: subagent_spawning + subagent_ended
+// for the same childSessionKey must produce the same run_id so the server-side
+// ingester groups them under one logical sub-run.
+//
+// Server schema requires `run_<26 Crockford Base32 chars>` (envelope.schema
+// `run_id` pattern `^run_[0-9A-HJKMNP-TV-Z]{26}$`). We seed the encoding with
+// sha1 of the childSessionKey to keep determinism, then transcode the top
+// 16 bytes into 26 Crockford chars (same algorithm as src-shared
+// envelope_builder.mjs `newBlockId`). Excluded letters: I L O U.
+const _CROCKFORD_CHARS = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+function deriveSubRunId(childSessionKey) {
+  if (!childSessionKey) return null;
+  const hashBytes = crypto.createHash("sha1").update(String(childSessionKey)).digest();
+  // Pack first 16 bytes (128 bits) into a BigInt then pull 5-bit groups
+  // from the MSB; 128/5 = 25.6 → 26 chars (top 2 bits zero).
+  let n = BigInt(0);
+  for (let i = 0; i < 16; i++) n = (n << BigInt(8)) | BigInt(hashBytes[i]);
+  const chars = new Array(26);
+  for (let i = 25; i >= 0; i--) {
+    chars[i] = _CROCKFORD_CHARS[Number(n & BigInt(31))];
+    n >>= BigInt(5);
+  }
+  return "run_" + chars.join("");
+}
+
+function register(api) {
+  // Plugin runs inside OpenClaw daemon — any console.* writes pollute the
+  // host's structured log stream. Always use api.logger. When api.logger is
+  // unavailable (should be impossible per OpenClaw contract but defensive)
+  // silently drop log entries; track a counter and write **one** stderr line
+  // at beforeExit so we don't lose all diagnostic signal.
+  let suppressedLogs = 0;
+  function logInfo(m) { if (api.logger?.info) api.logger.info(`[agentlink-hooks] ${m}`); else suppressedLogs += 1; }
+  function logWarn(m) { if (api.logger?.warn) api.logger.warn(`[agentlink-hooks] ${m}`); else suppressedLogs += 1; }
+  function logDebug(m) { if (api.logger?.debug) api.logger.debug(`[agentlink-hooks] ${m}`); }
+  process.on("beforeExit", () => {
+    if (suppressedLogs > 0) {
+      try { process.stderr.write(`[agentlink-hooks] ${suppressedLogs} logs suppressed: api.logger unavailable\n`); } catch {}
+    }
+  });
+  const log = { info: logInfo, warn: logWarn, debug: logDebug };
+
+  if (envelopeBuilderLoadError || !envelopeBuilder) {
+    log.warn(
+      `envelope-builder missing — run \`npm run build:plugin\`. ` +
+      `Tool events disabled. ${envelopeBuilderLoadError ? envelopeBuilderLoadError.message : ""}`,
+    );
+    return;
+  }
+
+  if (typeof api.on !== "function") {
+    log.warn("api.on unavailable — typed hooks not registered. Tool events disabled.");
+    return;
+  }
+
+  // Defense-in-depth env probe (debug-only; OpenClaw daemon may legitimately
+  // configure its own global dispatcher — we just record it for later forensics).
+  log.debug(
+    `env probe: undiciDispatcher=${!!globalThis[Symbol.for("undici.globalDispatcher.1")]} pid=${process.pid}`,
+  );
+
+  // ── Mutable runtime state (re-readable on 401) ─────────────────────────────
+
+  let state = readAgentlinkState();
+  let relayUrl = resolveRelayUrl(state);
+  let { gatewayId, gatewayToken } = pickGatewayCreds(state);
+  let verbose = isVerboseEnabled(state);
+  const HOST = hostHash();
+
+  function reloadConfig(reason) {
+    try {
+      const nextState = readAgentlinkState();
+      const nextCreds = pickGatewayCreds(nextState);
+      const nextRelay = resolveRelayUrl(nextState);
+      const changed =
+        nextCreds.gatewayId !== gatewayId
+        || nextCreds.gatewayToken !== gatewayToken
+        || nextRelay !== relayUrl;
+      if (changed) {
+        log.info(`reloaded creds (${reason}): relay=${nextRelay} gateway=${nextCreds.gatewayId.slice(0, 8)}…`);
+      }
+      state = nextState;
+      gatewayId = nextCreds.gatewayId;
+      gatewayToken = nextCreds.gatewayToken;
+      relayUrl = nextRelay;
+      verbose = isVerboseEnabled(state);
+      return changed;
+    } catch {
+      return false;
+    }
+  }
+
+  if (!gatewayId || !gatewayToken) {
+    log.warn("missing relay credentials — tool events disabled. Run `agentlink pair` to configure.");
+    return;
+  }
+
+  log.info(`registered. relay=${relayUrl} gateway=${gatewayId.slice(0, 8)}… host=${HOST} verbose=${verbose}`);
+
+  // ── Throttled warning so we surface failure without spamming the log ─────
+
+  let lastWarnAt = 0;
+  let warnsSuppressed = 0;
+  function warnThrottled(msg) {
+    const now = Date.now();
+    if (now - lastWarnAt < WARN_THROTTLE_MS) {
+      warnsSuppressed += 1;
+      return;
+    }
+    if (warnsSuppressed > 0) {
+      log.warn(`(${warnsSuppressed} similar warning(s) suppressed) ${msg}`);
+      warnsSuppressed = 0;
+    } else {
+      log.warn(msg);
+    }
+    lastWarnAt = now;
+  }
+
+  // ── POST queue (per-callId serial; cross-callId concurrent) ───────────────
+  // Guarantees that a single tool's started → completed envelopes arrive in
+  // order even if HTTP latency varies. Different toolCallIds run concurrently.
+
+  const queues = new Map();          // callId → Promise<void>
+  let credReloadInflight = false;    // single-flight guard for 401 retry
+
+  async function postOnce(url, body) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+    try {
+      return await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-agent-bridge-token": gatewayToken,
+        },
+        body,
+        signal: ctrl.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // Enrich plugin-produced envelope with dispatch-context required fields
+  // (thread_id / role / source). Mirrors bridge's enrichEnvelope in
+  // bin/agentlink — the server envelope schema requires these at the top
+  // level for every event. role/source are inferred by type.
+  function enrichEnvelope(env, threadId) {
+    const type = String(env?.type || "");
+    const isSystem = type === "heartbeat" || type === "error";
+    return {
+      thread_id: threadId,
+      role: isSystem ? "system" : "assistant",
+      source: isSystem ? "relay" : "runtime",
+      ...env,
+    };
+  }
+
+  // ── bridge-auto-tunnel hook chain (CJS → ESM dynamic import) ──────────────
+  // Plugin 与 bridge 是两条互不相交的 envelope POST 通道:
+  //   - bridge (bin/agentlink): dispatch SSE → translate → POST
+  //   - plugin (本文件):       daemon hook  → POST (尤其是 autonomous follow-up
+  //                            自发轮,bridge 的 SSE 这条路压根收不到内容)
+  // 之前 auto-tunnel URL 改写只挂在 bridge 那条链上,plugin 这条直接 POST 给
+  // relay → App 永远看到原 localhost URL。这里把 autoTunnelGateway 也接入
+  // plugin postEnvelopes,与 bridge 共享同一份 detect/start tunnel/replace 逻辑。
+  //
+  // 失败语义:any error → pass-through (envelopes 原样 POST),不阻断主链路。
+  let _autoTunnelHooksMod = null;
+  let _autoTunnelHooksTried = false;
+  async function _ensureAutoTunnelHooks(effectiveRelay) {
+    if (_autoTunnelHooksMod) return _autoTunnelHooksMod;
+    if (_autoTunnelHooksTried) return _autoTunnelHooksMod;
+    _autoTunnelHooksTried = true;
+    try {
+      const path = require("node:path");
+      const { pathToFileURL } = require("node:url");
+      // 本文件在 npm_cli/src-ext/openclaw-plugin/index.cjs
+      // autoTunnelWiring / bridgeHooks 在 npm_cli/src-ext/core/
+      const wiringPath = path.resolve(__dirname, "..", "core", "autoTunnelWiring.mjs");
+      const hooksPath  = path.resolve(__dirname, "..", "core", "bridgeHooks.mjs");
+      const { installAutoTunnel } = await import(pathToFileURL(wiringPath).href);
+      installAutoTunnel({ relayUrl: effectiveRelay, log: null });
+      _autoTunnelHooksMod = await import(pathToFileURL(hooksPath).href);
+    } catch (err) {
+      warnThrottled(`auto-tunnel hooks load failed (pass-through): ${err?.message || err}`);
+    }
+    return _autoTunnelHooksMod;
+  }
+
+  // POST a batch of unified envelopes to /v1/agents/threads/<tid>/events.
+  // hookCtx is the ctx object OpenClaw hands to typed hook handlers; we
+  // resolve thread_id + relay_url from it via resolveHookContext().
+  // Silently drops the batch if thread_id is not resolvable.
+  async function postEnvelopes(hookCtx, envelopes) {
+    if (!Array.isArray(envelopes) || envelopes.length === 0) return;
+    const rc = resolveHookContext(hookCtx, relayUrl);
+    if (!rc || !rc.thread_id) {
+      // No way to know which thread these envelopes belong to — drop silently.
+      return;
+    }
+    const effectiveRelay = rc.relay_url || relayUrl;
+
+    // bridge-auto-tunnel: 把 envelope 内 content_block.completed 的 loopback URL
+    // 改写为公网 tunnel URL。失败 pass-through。
+    let processedEnvelopes = envelopes;
+    try {
+      const hooks = await _ensureAutoTunnelHooks(effectiveRelay);
+      if (hooks && typeof hooks.applyOutgoingHooks === "function") {
+        const out = await hooks.applyOutgoingHooks(envelopes, {
+          thread_id: rc.thread_id,
+        });
+        if (Array.isArray(out) && out.length > 0) {
+          processedEnvelopes = out;
+        }
+      }
+    } catch (err) {
+      warnThrottled(`auto-tunnel hook chain failed (pass-through): ${err?.message || err}`);
+    }
+
+    const url = `${effectiveRelay.replace(/\/+$/, "")}/v1/agents/threads/${encodeURIComponent(rc.thread_id)}/events`;
+    const enriched = processedEnvelopes.map((env) => enrichEnvelope(env, rc.thread_id));
+    const body = JSON.stringify({ events: enriched });
+
+    try {
+      const resp = await postOnce(url, body);
+      if (resp.ok) return;
+
+      // 401 = token rejected entirely. 404 = token valid but resolves to a
+      // bridge_user_id that doesn't own this thread — happens when CLI
+      // re-paired (new gateway/token) between plugin's last config load and
+      // this POST. Both signals trigger a one-shot config reload + retry.
+      if ((resp.status === 401 || resp.status === 404) && !credReloadInflight) {
+        credReloadInflight = true;
+        try {
+          const changed = reloadConfig(`${resp.status} from relay`);
+          if (changed) {
+            // Re-resolve thread_id too: the active-runs file might have been
+            // rewritten by bridge under a new key after re-pair.
+            const rc2 = resolveHookContext(hookCtx, relayUrl);
+            const newThreadId = rc2?.thread_id || rc.thread_id;
+            const newRelay = rc2?.relay_url || effectiveRelay;
+            const newUrl = `${newRelay.replace(/\/+$/, "")}/v1/agents/threads/${encodeURIComponent(newThreadId)}/events`;
+            // Re-enrich envelopes (already auto-tunnel-rewritten) with the
+            // new thread_id (if changed).
+            const reEnriched = JSON.stringify({
+              events: processedEnvelopes.map((env) => enrichEnvelope(env, newThreadId)),
+            });
+            const retry = await postOnce(newUrl, reEnriched);
+            if (retry.ok) return;
+            warnThrottled(`relay POST /events ${retry.status} after creds reload — token may have been reset; run \`agentlink pair\` again`);
+            return;
+          }
+        } finally { credReloadInflight = false; }
+        warnThrottled(`relay POST /events ${resp.status} — token rejected or thread ownership mismatch. Run \`agentlink pair <code>\` to reconfigure.`);
+      } else if (resp.status === 207) {
+        // partial accept: log the first rejection but don't retry
+        try {
+          const decoded = await resp.json();
+          const rejected = Array.isArray(decoded?.rejected) ? decoded.rejected : [];
+          if (rejected.length > 0) {
+            const first = rejected[0] || {};
+            warnThrottled(`relay POST /events 207 partial: ${rejected.length} rejected; first code=${first.code || "?"}`);
+          }
+        } catch {
+          warnThrottled(`relay POST /events 207 partial (response not JSON)`);
+        }
+      } else if (resp.status === 401 || resp.status === 404) {
+        // Another reload+retry is already in flight from a concurrent hook;
+        // attempting another would race / risk infinite recursion. Log
+        // generically so user knows this isn't a fresh failure mode.
+        warnThrottled(`relay POST /events ${resp.status} — auth/ownership; reload already inflight, this batch dropped`);
+      } else {
+        warnThrottled(`relay POST /events ${resp.status} — server rejected (${envelopes.length} envelope(s))`);
+      }
+    } catch (err) {
+      const msg = err && err.name === "AbortError"
+        ? `relay POST /events timed out after ${FETCH_TIMEOUT_MS}ms (relay=${effectiveRelay})`
+        : `relay POST /events failed: ${err && err.message ? err.message : String(err)}`;
+      warnThrottled(msg);
+    }
+  }
+
+  function enqueuePost(callId, hookCtx, envelopes) {
+    const key = String(callId || `_run_${hookCtx?.runId || "anon"}`);
+    const prev = queues.get(key) || Promise.resolve();
+    const next = prev.then(
+      () => postEnvelopes(hookCtx, envelopes),
+      () => postEnvelopes(hookCtx, envelopes),
+    );
+    queues.set(key, next);
+    next.finally(() => {
+      if (queues.get(key) === next) queues.delete(key);
+    });
+    return next;
+  }
+
+  function safeOn(hookName, handler) {
+    api.on(hookName, (event, ctx) => {
+      try { handler(event, ctx); } catch (err) {
+        warnThrottled(`hook ${hookName} threw: ${err && err.message ? err.message : String(err)}`);
+      }
+    });
+  }
+
+  function dump(name, event, ctx) {
+    if (!verbose) return;
+    try {
+      const evJson = redactSecrets(JSON.stringify(event));
+      const ctxJson = redactSecrets(JSON.stringify(ctx));
+      // Cap dump length so a single hook can't write a 10MB log line.
+      const cap = 16 * 1024;
+      const ev = evJson.length > cap ? evJson.slice(0, cap) + `…(+${evJson.length - cap}B)` : evJson;
+      const c  = ctxJson.length > cap ? ctxJson.slice(0, cap) + `…(+${ctxJson.length - cap}B)` : ctxJson;
+      log.info(`hook=${name} event=${ev} ctx=${c}`);
+    } catch {
+      // event/ctx may contain circular refs; ignore
+    }
+  }
+
+  // ── Method A2: subagent_ref lifecycle state ─────────────────────────────
+  // Three Maps implement the after_tool_call-driven topology for subagent_ref
+  // envelope emission. All maps are scoped to this register() invocation and
+  // do NOT leak outside (they share lifetime with the plugin registration).
+  //
+  // pendingSessionsSpawnByRun: FIFO queue mapping parentRunId -> callId[]
+  //   before_tool_call(sessions_spawn) enqueues; after_tool_call dequeues.
+  //   Used to verify FIFO ordering between buffer and result events.
+  //
+  // pendingToolUseBufferByCallId: tool_use envelope buffer, key=callId, value=envelope[]
+  //   before_tool_call(sessions_spawn) stores the tool_use envelope here instead
+  //   of immediately posting. after_tool_call flushes it AFTER subagent_ref.started
+  //   + run.started, so relay sees the SDK signal (subagent_ref) before tool_use.
+  //
+  // subagentRefByChildKey: subagent_ref state table, key=childSessionKey
+  //   Written by after_tool_call(sessions_spawn) when childKey is extracted.
+  //   Read + deleted by agent_end(isFallback=true) to emit subagent_ref.completed.
+  //   Purged for a parentRunId when that parent's agent_end(A) fires.
+
+  /** FIFO queue: runId -> callId[] */
+  const pendingSessionsSpawnByRun = new Map();
+
+  /** Buffer: callId -> RawEnvelope[] */
+  const pendingToolUseBufferByCallId = new Map();
+
+  /** State table: childSessionKey -> { refBlockId, callId, parentRunId, agent, subRunId } */
+  const subagentRefByChildKey = new Map();
+
+  // ── per-run content_block.index counter ────────────────────────────────
+  // Unified envelope spec uses an optional per-run monotonic block index.
+  // Plugin owns its own counter; server tolerates the index being absent
+  // (set on best-effort basis).
+  const blockIndexes = new Map(); // runId → number
+  function nextBlockIndex(runId) {
+    const cur = blockIndexes.get(runId) || 0;
+    blockIndexes.set(runId, cur + 1);
+    return cur;
+  }
+  function dropBlockIndex(runId) { blockIndexes.delete(runId); }
+
+  // ── toolCallId → blk_<ULID> mapping ────────────────────────────────────
+  // Server schema enforces block.id to be exactly `blk_<26 Crockford chars>`.
+  // OpenClaw's `toolCallId` is `call_<hex>` (different prefix + length), so
+  // we generate a fresh blk_ id at before_tool_call and reuse it at
+  // after_tool_call (both tool_use completion and the paired tool_result
+  // block need a stable, schema-valid id).
+  //
+  // Two-level memory: `toolCallBlockIds` per call_id + `runToolCalls` reverse
+  // index `runId → Set<callId>` so that if after_tool_call never fires (rare
+  // — daemon crash mid-tool, partial outage), agent_end can drain the whole
+  // run's stale entries at turn end. Without the reverse index, entries
+  // accumulate forever in long-lived daemons.
+  const toolCallBlockIds = new Map(); // toolCallId → { useBlkId, resultBlkId }
+  const runToolCalls = new Map();     // runId → Set<callId>
+  function getOrCreateToolBlockIds(callId) {
+    if (!callId) {
+      // No toolCallId from OpenClaw: still generate ids so envelopes pass
+      // schema, but pair will be transient (started + completed map by their
+      // own callIds in the queue, not by toolCallId map).
+      return { useBlkId: envelopeBuilder._newBlockId?.() || undefined, resultBlkId: undefined, transient: true };
+    }
+    let entry = toolCallBlockIds.get(callId);
+    if (!entry) {
+      // Generate blk_ ids via the same shape buildBlockStarted would use
+      // when block.id is absent — but we need to know the id eagerly so
+      // we can pass it to all 3 envelopes for this tool call.
+      // Call buildBlockStarted with no block.id and read it back.
+      const probe = envelopeBuilder.buildBlockStarted("_", { type: "tool_use" });
+      const probeResult = envelopeBuilder.buildBlockStarted("_", { type: "tool_result" });
+      entry = {
+        useBlkId: probe.payload.block.id,
+        resultBlkId: probeResult.payload.block.id,
+      };
+      toolCallBlockIds.set(callId, entry);
+    }
+    return entry;
+  }
+  function dropToolBlockIds(callId) { if (callId) toolCallBlockIds.delete(callId); }
+  function trackToolCallForRun(runId, callId) {
+    if (!runId || !callId) return;
+    let set = runToolCalls.get(runId);
+    if (!set) { set = new Set(); runToolCalls.set(runId, set); }
+    set.add(callId);
+  }
+  function dropAllToolCallsForRun(runId) {
+    const set = runToolCalls.get(runId);
+    if (!set) return;
+    for (const cid of set) toolCallBlockIds.delete(cid);
+    runToolCalls.delete(runId);
+  }
+
+  // ── Tool-call lifecycle → tool_use + tool_result content blocks ────────
+  // before_tool_call event: { toolName, params, runId?, toolCallId? }
+  // after_tool_call event:  { ..., result?, error?, durationMs? }
+  // ctx: { agentId?, sessionKey?, sessionId?, runId?, toolName, toolCallId? }
+
+  safeOn("before_tool_call", (event, ctx) => {
+    dump("before_tool_call", event, ctx);
+    const rc = resolveHookContext(ctx, relayUrl);
+    if (!rc) return;
+    const runId = rc.run_id || ctx?.runId || event?.runId || "";
+    if (!runId) return;
+    const callId = ctx?.toolCallId || event?.toolCallId || "";
+    const toolName = event?.toolName || ctx?.toolName || "";
+
+    // ── update_plan intercept: emit todo_list block instead of tool_use ────
+    // OpenClaw calls update_plan as a native tool call; we suppress the
+    // tool_use / tool_result pair and replace it with a single todo_list block
+    // (started + completed emitted together in before_tool_call). after_tool_call
+    // also returns early so the tool_use_completed + tool_result are never sent.
+    if (toolName === "update_plan" && todoUtils) {
+      const rawPlan = event?.params?.plan;
+      const items = todoUtils.buildTodoItems(Array.isArray(rawPlan) ? rawPlan : []);
+      const idx = nextBlockIndex(runId);
+      const todoBlock = {
+        type: "todo_list",
+        status: "in_progress",
+        items,
+      };
+      const todoStarted = envelopeBuilder.buildBlockStarted(runId, todoBlock, idx);
+      const blockId = todoStarted.payload.block.id;
+      const todoCompleted = envelopeBuilder.buildBlockCompleted(
+        runId,
+        { id: blockId, type: "todo_list", status: "completed", items },
+        idx,
+      );
+      enqueuePost(callId, ctx, [todoStarted, todoCompleted]);
+      trackToolCallForRun(runId, callId);
+      return;
+    }
+
+    const input = truncatePayload(event?.params ?? null);
+    const idx = nextBlockIndex(runId);
+    const { useBlkId } = getOrCreateToolBlockIds(callId);
+    trackToolCallForRun(runId, callId); // for GC at agent_end
+    // tool_use block fields are flat on the block per blocks/tool_use.schema.json
+    // (no nested `body`). The OpenClaw call_xxx id goes into tool_call_id.
+    const env = envelopeBuilder.buildBlockStarted(
+      runId,
+      {
+        id: useBlkId,
+        type: "tool_use",
+        status: "in_progress",
+        tool_call_id: callId || "",
+        tool_name: toolName,
+        input: (input && typeof input === "object" && !Array.isArray(input)) ? input : {},
+        input_complete: false,
+      },
+      idx,
+    );
+
+    // Method A2: sessions_spawn tool_use goes into buffer instead of immediate POST.
+    // We need to flush it AFTER subagent_ref.started + run.started in after_tool_call,
+    // so relay's scanSDKSignals sees the SDK signal (subagent_ref) before synthStarted.
+    if (toolName === "sessions_spawn") {
+      // Buffer the tool_use envelope
+      const buf = pendingToolUseBufferByCallId.get(callId) || [];
+      buf.push(env);
+      pendingToolUseBufferByCallId.set(callId, buf);
+      // FIFO enqueue: parentRunId -> callId[]
+      const q = pendingSessionsSpawnByRun.get(runId) || [];
+      q.push(callId);
+      pendingSessionsSpawnByRun.set(runId, q);
+      // Do NOT enqueuePost — return early
+      return;
+    }
+
+    enqueuePost(callId, ctx, [env]);
+  });
+
+  safeOn("after_tool_call", (event, ctx) => {
+    dump("after_tool_call", event, ctx);
+    const rc = resolveHookContext(ctx, relayUrl);
+    if (!rc) return;
+    const runId = rc.run_id || ctx?.runId || event?.runId || "";
+    if (!runId) return;
+    const callId = ctx?.toolCallId || event?.toolCallId || "";
+    const toolName = event?.toolName || ctx?.toolName || "";
+
+    // ── update_plan intercept: todo_list block was already fully emitted in
+    // before_tool_call (started + completed). Skip tool_use_completed + tool_result.
+    if (toolName === "update_plan" && todoUtils) {
+      dropToolBlockIds(callId);
+      return;
+    }
+
+    const errorText = typeof event?.error === "string" ? event.error.trim() : "";
+    const isError = errorText !== "";
+    const duration =
+      typeof event?.durationMs === "number" ? event.durationMs : null;
+
+    const { useBlkId, resultBlkId } = getOrCreateToolBlockIds(callId);
+
+    // Reserve two consecutive per-run indexes upfront so:
+    //   - toolUseCompleted reuses the same index as the prior toolUseStarted
+    //     (close out the block at its original slot)
+    //   - toolResultStarted + toolResultCompleted share a fresh slot
+    // (We can't reuse the started's exact index without remembering it from
+    //  before_tool_call; using nextBlockIndex here gives monotonic order
+    //  which is sufficient for App-side delta replay.)
+    const useCompletedIdx = nextBlockIndex(runId);
+    const resultIdx = nextBlockIndex(runId);
+
+    // tool_use block: flat fields per blocks/tool_use.schema.json.
+    const paramsInput = truncatePayload(event?.params ?? null);
+    const toolUseCompleted = envelopeBuilder.buildBlockCompleted(
+      runId,
+      {
+        id: useBlkId,
+        type: "tool_use",
+        status: isError ? "failed" : "completed",
+        tool_call_id: callId || "",
+        tool_name: toolName,
+        input: (paramsInput && typeof paramsInput === "object" && !Array.isArray(paramsInput)) ? paramsInput : {},
+        input_complete: true,
+      },
+      useCompletedIdx,
+    );
+
+    // Helper: every block inside tool_result.output must satisfy
+    // block.schema.json `required: ["id", "type", "status"]` — including text
+    // children. We build them by calling buildBlockStarted to auto-fill
+    // schema-required fields (id, status, format, text), then strip the
+    // envelope wrapper to get back just the block object.
+    function newOutputTextBlock(text) {
+      const env = envelopeBuilder.buildBlockStarted("_unused", {
+        type: "text",
+        format: "plain",
+        text: String(text == null ? "" : text),
+        status: "completed",
+      });
+      return env.payload.block;
+    }
+    function normalizeOutputBlock(b) {
+      if (!b || typeof b !== "object") return null;
+      // OpenClaw text shape → schema-valid text block
+      if (b.type === "text" && typeof b.text === "string") {
+        return newOutputTextBlock(truncatePayload(b.text, PAYLOAD_TRUNCATE_BYTES));
+      }
+      // Other types: fill missing required fields if possible
+      const out = { ...b };
+      if (!out.id) {
+        const probe = envelopeBuilder.buildBlockStarted("_unused", { type: out.type || "text" });
+        out.id = probe.payload.block.id;
+      }
+      if (!out.status) out.status = "completed";
+      return out;
+    }
+
+    // tool_result.output is an **array of nested blocks** per
+    // blocks/tool_result.schema.json. We always wrap the OpenClaw result
+    // (which is typically already `{content:[{type:"text",text:"..."}]}` or a
+    // raw object) into one or more text blocks. summary captures duration
+    // when available so it's discoverable client-side.
+    const rawResult = event?.result;
+    let outputBlocks;
+    if (Array.isArray(rawResult?.content)) {
+      outputBlocks = rawResult.content.map(normalizeOutputBlock).filter(Boolean);
+    } else if (typeof rawResult === "string") {
+      outputBlocks = [newOutputTextBlock(truncatePayload(rawResult, PAYLOAD_TRUNCATE_BYTES))];
+    } else if (rawResult != null) {
+      outputBlocks = [newOutputTextBlock(JSON.stringify(truncatePayload(rawResult)))];
+    } else if (isError) {
+      outputBlocks = [newOutputTextBlock(errorText || "tool error")];
+    } else {
+      outputBlocks = [];
+    }
+
+    const toolResultStarted = envelopeBuilder.buildBlockStarted(
+      runId,
+      {
+        id: resultBlkId,
+        type: "tool_result",
+        status: "in_progress",
+        tool_call_id: callId || "",
+        is_error: isError,
+        output: outputBlocks,
+        summary: typeof duration === "number" ? `duration=${duration}ms` : undefined,
+      },
+      resultIdx,
+    );
+    const toolResultCompleted = envelopeBuilder.buildBlockCompleted(
+      runId,
+      {
+        id: resultBlkId,
+        type: "tool_result",
+        status: isError ? "failed" : "completed",
+        tool_call_id: callId || "",
+        is_error: isError,
+        output: outputBlocks,
+        summary: typeof duration === "number" ? `duration=${duration}ms` : undefined,
+      },
+      resultIdx,
+    );
+
+    // Method A2: sessions_spawn after_tool_call — emit subagent_ref.started + run.started
+    // BEFORE flushing the buffered tool_use, so relay's scanSDKSignals writes
+    // sdkMode before synthStarted sees the tool_use block.
+    if (toolName === "sessions_spawn") {
+      // Extract childSessionKey: try multiple shapes
+      //   1. 顶层字段（极少；如果 OpenClaw 升级把 result 摊平到顶层）
+      //   2. result.content[0].text 内嵌 JSON（典型 OpenClaw sessions_spawn 形态）
+      //   3. result.output[0].text 内嵌 JSON（少数 OpenClaw 版本的旧形态）
+      //   4. result 本身就是 JSON 字符串
+      function parseEmbeddedJSON(text) {
+        if (!text) return null;
+        try { return JSON.parse(text); } catch { return null; }
+      }
+      let childKey = "";
+      if (typeof rawResult?.childSessionKey === "string") {
+        childKey = rawResult.childSessionKey;
+      } else if (Array.isArray(rawResult?.content) && rawResult.content[0]?.text) {
+        const parsed = parseEmbeddedJSON(rawResult.content[0].text);
+        if (parsed?.childSessionKey) childKey = parsed.childSessionKey;
+      } else if (Array.isArray(rawResult?.output) && rawResult.output[0]?.text) {
+        const parsed = parseEmbeddedJSON(rawResult.output[0].text);
+        if (parsed?.childSessionKey) childKey = parsed.childSessionKey;
+      } else if (typeof rawResult === "string") {
+        const parsed = parseEmbeddedJSON(rawResult);
+        if (parsed?.childSessionKey) childKey = parsed.childSessionKey;
+      }
+
+      // Dequeue FIFO (align before_tool_call callId with after_tool_call callId)
+      const fifoQ = pendingSessionsSpawnByRun.get(runId) || [];
+      fifoQ.shift(); // pop the head (should correspond to this callId)
+      if (fifoQ.length === 0) {
+        pendingSessionsSpawnByRun.delete(runId);
+      } else {
+        pendingSessionsSpawnByRun.set(runId, fifoQ);
+      }
+
+      if (!childKey) {
+        // Fallback: childKey not extractable. Flush buffer and let relay synth handle it.
+        // Log result shape hint for debugging without dumping full content (may be sensitive).
+        const shapeHint = (() => {
+          if (rawResult == null) return "null";
+          if (typeof rawResult === "string") return "string(len=" + rawResult.length + ")";
+          if (Array.isArray(rawResult)) return "array";
+          if (typeof rawResult === "object") {
+            return "object(keys=" + Object.keys(rawResult).slice(0, 6).join(",") + ")";
+          }
+          return typeof rawResult;
+        })();
+        log.warn(
+          "[agentlink-hooks] after_tool_call(sessions_spawn): cannot extract childSessionKey " +
+          "from result, callId=" + callId + " runId=" + runId + " resultShape=" + shapeHint +
+          ", falling back to relay synth",
+        );
+        // Flush buffered tool_use
+        const fallbackBuf = pendingToolUseBufferByCallId.get(callId) || [];
+        pendingToolUseBufferByCallId.delete(callId);
+        if (fallbackBuf.length > 0) {
+          enqueuePost(callId, ctx, fallbackBuf);
+        }
+        // Then tool_use completed + tool_result (normal path)
+        enqueuePost(callId, ctx, [toolUseCompleted, toolResultStarted, toolResultCompleted]);
+        dropToolBlockIds(callId);
+        return;
+      }
+
+      // Core path: childKey extracted. Emit in strict order using a single
+      // enqueuePost call so all envelopes share one serial queue slot:
+      // ① subagent_ref.started  ② run.started  ③ buffer flush  ④ tool_result
+      // This guarantees relay sees the SDK signal (subagent_ref.started) first.
+      const subRunId = deriveSubRunId(childKey);
+      const parentRunId = runId;
+
+      // ① subagent_ref.started
+      const refStarted = envelopeBuilder.buildBlockStarted(
+        parentRunId,
+        {
+          type: "subagent_ref",
+          child_run_id: subRunId,
+          spawn_tool_use_id: callId,
+          agent: "",  // openclaw after_tool_call has no agentId in result
+          summary: "",
+        },
+      );
+      const refBlockId = refStarted.payload.block.id;
+
+      // ② run.started for the child sub-run
+      const runStarted = envelopeBuilder.buildRunStarted(subRunId, {
+        spawnToolUseId: callId,
+        model: "",
+        options: { mode: rawResult?.mode || "" },
+      });
+      runStarted.parent_run_id = parentRunId;
+      stampChildSessionKey(runStarted, childKey);
+
+      // ③ buffered tool_use (from before_tool_call)
+      const buf = pendingToolUseBufferByCallId.get(callId) || [];
+      pendingToolUseBufferByCallId.delete(callId);
+
+      // ④ tool_result (all in one batch, in order)
+      const orderedBatch = [
+        refStarted,
+        runStarted,
+        ...buf,
+        toolUseCompleted,
+        toolResultStarted,
+        toolResultCompleted,
+      ];
+      enqueuePost(callId, ctx, orderedBatch);
+      dropToolBlockIds(callId);
+
+      // Write to state table for agent_end(isFallback=true) to consume
+      subagentRefByChildKey.set(childKey, {
+        refBlockId,
+        callId,
+        parentRunId,
+        agent: "",
+        subRunId,
+      });
+      return;
+    }
+
+    enqueuePost(callId, ctx, [toolUseCompleted, toolResultStarted, toolResultCompleted]);
+    dropToolBlockIds(callId); // free per-call state after completion
+  });
+
+  // ── Subagent lifecycle ──────────────────────────────────────────────────
+  // subagent_spawning event:
+  //   { childSessionKey, agentId, label?, mode, requester?, threadRequested }
+  // subagent_ended event:
+  //   { targetSessionKey, targetKind, reason, outcome?, error?, runId?, endedAt? }
+  // ctx: { runId?, childSessionKey?, requesterSessionKey? }
+
+  // Helper: stamp the daemon-side OpenClaw childSessionKey onto envelope
+  // extensions so server-side subagent_synth can correlate child run.{started,
+  // completed,failed} back to the parent's subagent_ref block by key (the
+  // unified subRunId is derived locally via sha1(childKey) and not visible to
+  // server, but childKey itself appears in both sessions_spawn's tool_result
+  // output AND the hook event — so it's the only stable join key across the
+  // parent's tool_result and the child's terminal envelope).
+  function stampChildSessionKey(env, childKey) {
+    if (!childKey) return env;
+    const ext = (env.extensions && typeof env.extensions === "object") ? env.extensions : {};
+    const oc = (ext.openclaw && typeof ext.openclaw === "object") ? ext.openclaw : {};
+    env.extensions = {
+      ...ext,
+      openclaw: { ...oc, child_session_key: childKey },
+    };
+    return env;
+  }
+
+  // DEAD CODE (2026-05-17): subagent_spawning hook does NOT fire in current
+  // OpenClaw daemon version. This was verified via e2e DEBUG log — OpenClaw
+  // executes sessions_spawn via before_tool_call / after_tool_call instead.
+  // This handler was the intended core of the original plan B design.
+  // Kept for reference — remove or re-activate if OpenClaw upstream revives
+  // this hook in a future daemon version.
+  safeOn("subagent_spawning", (event, ctx) => {
+    dump("subagent_spawning", event, ctx);
+    const rc = resolveHookContext(ctx, relayUrl);
+    if (!rc) return;
+    const parentRunId = rc.run_id || ctx?.runId || "";
+    if (!parentRunId) return;
+    const childKey = event?.childSessionKey || ctx?.childSessionKey || "";
+    const subRunId = deriveSubRunId(childKey);
+    if (!subRunId) return;
+    // buildRunStarted does not natively set parent_run_id; we splice it in.
+    const env = envelopeBuilder.buildRunStarted(subRunId, {
+      model: "",
+      options: {
+        agent_id: event?.agentId || "",
+        label: event?.label || "",
+        mode: event?.mode || "",
+      },
+    });
+    env.parent_run_id = parentRunId;
+    stampChildSessionKey(env, childKey);
+    enqueuePost(childKey || subRunId, ctx, [env]);
+  });
+
+  // DEAD CODE (2026-05-17): subagent_ended hook does NOT fire in current
+  // OpenClaw daemon version (same reason as subagent_spawning above).
+  // Subagent completion is signaled via agent_end(isFallback=true) instead.
+  // Kept for reference — remove or re-activate if OpenClaw upstream revives
+  // this hook in a future daemon version.
+  safeOn("subagent_ended", (event, ctx) => {
+    dump("subagent_ended", event, ctx);
+    const rc = resolveHookContext(ctx, relayUrl);
+    if (!rc) return;
+    const parentRunId = rc.run_id || ctx?.runId || event?.runId || "";
+    if (!parentRunId) return;
+    const childKey = event?.targetSessionKey || ctx?.childSessionKey || "";
+    const subRunId = deriveSubRunId(childKey);
+    if (!subRunId) return;
+    const outcome = typeof event?.outcome === "string" ? event.outcome : "";
+    const isError = outcome !== "" && outcome !== "ok";
+    const errorText = typeof event?.error === "string" ? event.error.trim() : "";
+
+    let env;
+    if (isError) {
+      env = envelopeBuilder.buildRunFailed(
+        subRunId,
+        outcome || "runtime",
+        errorText || outcome || "subagent ended with non-ok outcome",
+      );
+    } else {
+      const stopReason =
+        outcome === "ok" ? "end_turn" : outcome || "end_turn";
+      env = envelopeBuilder.buildRunCompleted(subRunId, stopReason);
+    }
+    env.parent_run_id = parentRunId;
+    stampChildSessionKey(env, childKey);
+    enqueuePost(childKey || subRunId, ctx, [env]);
+  });
+
+  // ── before_agent_reply ────────────────────────────────────────────────
+  // OpenClaw 2026.3.x treats this name as an unknown typed hook and never
+  // fires it. Even if a future OpenClaw revives it, the server SSE adapter
+  // already emits run.started from response.started, so plugin emitting
+  // another run.started here would be redundant. We register a no-op handler
+  // purely for verbose-dump visibility if/when the hook resurfaces.
+
+  safeOn("before_agent_reply", (event, ctx) => {
+    dump("before_agent_reply", event, ctx);
+    // Intentionally no envelope: redundant with server-side SSE adapter.
+    // Remove this handler entirely once we confirm OpenClaw upstream has
+    // permanently retired the `before_agent_reply` hook name (the typed
+    // hook 已被标 unknown, see openclaw plugins inspect Diagnostics).
+    log.debug("before_agent_reply: no-op (server SSE adapter covers this)");
+  });
+
+  // ── agent_end → run.completed / run.failed (+ autonomous follow-up replay) ──
+  // event: { messages, success, error?, durationMs? }
+  //
+  // 两种 fire 模式（用 rc.isFallback 区分）:
+  //
+  //   A. isFallback=false — bridge dispatch 那轮主回复结束:
+  //      bridge 自己已经在 /v1/responses SSE 把 text content_blocks + 收尾
+  //      run.completed 发给 relay,plugin **不应**再重复发文本（会双倍
+  //      content_block），只需发 run.completed 作为 hook coverage。
+  //
+  //   B. isFallback=true — daemon 在原 dispatch 关闭 SSE 后**自发**起的
+  //      follow-up 轮（典型场景: subagent 完成后 daemon 内部投递 task-
+  //      completion user_message 给主 agent + 自动跑新一轮 LLM 调用）:
+  //      bridge 没在听,relay 永远收不到这一轮 reply → App 永远停在
+  //      "已启动子任务,稍等..." 那条。plugin 在这一刻是 daemon 进程里**
+  //      唯一**能看见这次 reply 的代码,必须把它补发出去。
+  //
+  //      由于 daemon native runId 是 resp_<uuid>,server schema 只接
+  //      run_<26 Crockford>,这里用 deriveSubRunId(stable seed) 生成一个
+  //      合规且**确定性**的 follow-up run_id（同一 ctx 多次 fire 不会双发）。
+  //      不挂 parent_run_id（这不是 subagent 而是 thread 顶层 follow-up）,
+  //      但带 extensions.openclaw.autonomous_followup 标记便于 server / App
+  //      区分这是 daemon 自发产物。
+
+  function extractAssistantText(messages) {
+    if (!Array.isArray(messages)) return "";
+    let combined = "";
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const m = messages[i];
+      if (!m || m.role !== "assistant") continue;
+      const content = m.content;
+      if (typeof content === "string") {
+        combined = content;
+        break;
+      }
+      if (Array.isArray(content)) {
+        const parts = [];
+        for (const c of content) {
+          if (!c || typeof c !== "object") continue;
+          // 跳过 thinking/toolCall 等;只拿 user-facing 文本
+          if (c.type === "text" && typeof c.text === "string") parts.push(c.text);
+          else if (c.type === "markdown" && typeof c.markdown === "string") parts.push(c.markdown);
+        }
+        combined = parts.join("");
+        break;
+      }
+    }
+    return combined;
+  }
+
+  function deriveAutonomousFollowupRunId(threadId, daemonRunId) {
+    // 同 thread + 同 daemon run 派生同 unified run_id（确定性,防重）;
+    // 不同 daemon run（例如同 thread 内多次 follow-up）派生不同 unified run_id。
+    const seed = `autonomous-followup:${threadId}:${daemonRunId || "anon"}`;
+    return deriveSubRunId(seed);
+  }
+
+  // OpenClaw daemon 用 `announce:v1:...` 命名 autonomous follow-up turn 的
+  // run_id（subagent 完成事件回灌主 agent 后内部触发的新一轮 LLM 调用）。
+  // 这种轮的 ctx.runId 不是 resp_<uuid> 也不是 unified run_<ULID>,是
+  // `announce:v1:agent:<name>:subagent:<uuid>:<parent-resp-id>` 这种合成 id。
+  // 当 ctx.runId 以 `announce:` 开头时,**无论 active-runs file 在不在**,
+  // 这一轮必然是 bridge dispatch 没在监听的自发轮 — bridge dispatch 只接
+  // **首轮** /v1/responses SSE,后续 daemon 自发产物通过 daemon-UI 自己的 WS
+  // chat.history channel 推,不在 bridge 通道里。
+  function isDaemonAutonomousTurn(ctx) {
+    const rid = String(ctx?.runId || "").trim();
+    // 只认 announce: 前缀。**不要**再用 "sessionKey 形如 agent:main:thr_xxx"
+    // 兜底：主轮（bridge dispatch 的那一轮）的 ctx.sessionKey 同样是
+    // `agent:main:thr_xxx`，旧的 sessionKey 启发式会把主轮误判成 autonomous，
+    // 于是 agent_end 走 path B 把已经流式发过的文本又补发一遍 → App 每条
+    // 回复显示两条相同消息。真正的 daemon 自发轮由 announce: 前缀（subagent）
+    // 或 isFallback=true（active-runs 文件已不在 = bridge 没在处理）识别，
+    // 不需要 sessionKey 启发式。
+    return rid.startsWith("announce:");
+  }
+
+  safeOn("agent_end", (event, ctx) => {
+    dump("agent_end", event, ctx);
+
+    // 自动 attach: 扫这一轮 assistant 文本里的本机文件路径 → 走 agentlink_attach_file
+    // 上传 COS。fire-and-forget,所有错误内部吞掉,不影响下面 run.completed 发送。
+    // path A / B 都需要扫(两条路上都有完整 assistant 文本)。
+    try {
+      const assistantText = extractAssistantText(event?.messages);
+      if (assistantText) {
+        void autoAttachScanAndDispatch(assistantText, { log, warnThrottled });
+      }
+    } catch (err) {
+      log.warn(`auto-attach.agent_end.threw: ${err?.message || err}`);
+    }
+
+    const rc = resolveHookContext(ctx, relayUrl);
+    if (!rc) return;
+
+    const ok = event?.success === true;
+
+    // ── A. 主链路 fire — 走原行为,只发 run.completed ──────────────────
+    // 即使 active-runs file 还在 (bridge dispatch SSE 没 EOF),只要 ctx 表明
+    // 这是 daemon 自发的 announce turn,就走 fallback 而不是 A —— bridge
+    // 那条 SSE 通道根本收不到这一轮的内容,不补发就丢。
+    //
+    // 补充判定（Bug fix: 主轮双发问题）：
+    // bridge SSE EOF 后会 cleanup active-runs 文件，但 daemon 的 agent_end
+    // hook 在那之后才触发 → 文件已删 → isFallback=true。此时若 ctx.runId 是
+    // 原生 "resp_<uuid>" 格式，说明这是 bridge 曾 dispatch 过的主轮（daemon
+    // 原生 run id 与 bridge 下发的 unified run_<ULID> 一一对应，主轮的
+    // ctx.runId 从不是 announce: 或其他合成格式）。bridge 已通过 SSE 把所有
+    // content_blocks 发给 relay，plugin 不应再重发文本，否则 App 会看到两条
+    // 完全相同的 assistant 消息。
+    // 判据依据：active-runs 文件写入时存的 run_id 是 unified run_<ULID>，
+    // 而 daemon 内部给 ctx.runId 赋的是原生 resp_<uuid>。两者格式不同，可
+    // 可靠区分。真正需要 plugin 补发的自发轮：
+    //   - B1 (subagent announce): ctx.runId 以 "announce:" 开头 → isDaemonAutonomousTurn=true
+    //   - B2 (cron/系统自发等): ctx.runId 既不是 resp_ 也不是 announce:
+    //     → isBridgeDispatchedMainRun=false → 走 B2 路径正确补发
+    // isBridgeDispatchedMainRun: bridge SSE EOF 后 active-runs 文件已删，
+    // 但 ctx.runId 仍是 daemon 原生 "resp_<uuid>" → 这是主轮，bridge 已全量
+    // 发过内容，plugin 直接跳过，不发任何 envelope（尤其不走 B2 补发路径）。
+    const isBridgeDispatchedMainRun =
+      rc.isFallback && String(ctx?.runId || "").startsWith("resp_");
+    if (isBridgeDispatchedMainRun) {
+      log.info(
+        `agent_end: skip main-run (bridge already streamed): ` +
+        `thread=${rc.thread_id} daemon_run=${ctx?.runId}`,
+      );
+      return;
+    }
+    const autonomous = isDaemonAutonomousTurn(ctx);
+    if (!rc.isFallback && !autonomous) {
+      const runId = rc.run_id || ctx?.runId || "";
+      if (!runId) return;
+      let env;
+      if (ok) {
+        env = envelopeBuilder.buildRunCompleted(runId, "end_turn");
+      } else {
+        const message =
+          (typeof event?.error === "string" && event.error.trim()) || "agent failed";
+        env = envelopeBuilder.buildRunFailed(runId, "runtime", message);
+      }
+      enqueuePost(null, ctx, [env]);
+      dropBlockIndex(runId);
+      // Method A2 Task 6 (修订 2026-05-17): 仅清理 FIFO + buffer。
+      // **不要**清 subagentRefByChildKey ——
+      // OpenClaw 的实际行为是：主 run 结束 (path A) 后子 agent 仍在跑，
+      // 之后子 agent 完成时 daemon 自起 follow-up 触发 path B (isFallback=true)，
+      // path B 需要查 subagentRefByChildKey 把 subagent_ref.completed 发出。
+      // path A 在这里清就把 state 提前抹掉了，导致 path B "no subagentRef state" warn。
+      // subagentRefByChildKey 的清理由 path B 末尾 line ~1256 完成；若 path B 永远
+      // 不来（子 agent crash），state 泄漏一直到 daemon 重启——可接受的损失。
+      pendingSessionsSpawnByRun.delete(runId);
+      const staleCallIds = runToolCalls.get(runId);
+      if (staleCallIds) {
+        for (const cid of staleCallIds) {
+          pendingToolUseBufferByCallId.delete(cid);
+        }
+      }
+      dropAllToolCallsForRun(runId);
+      return;
+    }
+
+    // ── B. daemon 自发 follow-up ─────────────────────────────────────────
+    // OpenClaw 在 subagent announce 完成后,把 subagent 的输出当作一条 user 内部消息
+    // 投回 parent session,parent 跑一轮 announce-LLM-call 把结果"以助手口吻"转给用户。
+    // 这一轮的 agent_end:
+    //   ctx.runId    = "announce:v1:agent:main:subagent:<childKey-uuid>:<daemonRunId>"
+    //   ctx.sessionKey = "agent:main:<lowercase-thr_xxx>"
+    //   event.messages[last assistant].content = subagent 实际答复(被 parent 转述)
+    //
+    // 协议视角:这段文本既是 parent 的"最终自然语言答复"(parent 第二轮 LLM 调用的输出),
+    // 也是用户看见的"subagent 最终结果"。validator 主视图基于单 rootRunId 锁单棵 run tree,
+    // 没办法把派生的孤儿 followup top-level run 渲染进主流。所以采取双发策略:
+    //   - text 作为 content_block 追加到 **parent run**:主流显示自然语言答复("计算结果:33")
+    //   - text 同样作为 content_block 挂到 **child sub-run**:点 subagent_ref 进详情看完整结果
+    //   - subagent_ref.completed.summary 同段 text:父流 subagent_ref 卡片内联预览
+    // parent run 此时通常已经 run.completed (yield 后 parent 主流的 LLM 调用结束),aggregator
+    // 容忍 run.completed 后继续追加 content_block,UI 会把它渲染到 parent run 的 blocks 末尾。
+    const daemonRun = String(ctx?.runId || "");
+    // daemon_run format: "announce:v1:agent:main:subagent:<childKey-uuid>:<daemonRunId>"
+    // childKey = "agent:main:subagent:<uuid>" (has colons), daemonRunId = UUID (no colons)
+    const announceMatch = /^announce:v1:agent:main:subagent:(.+):([^:]+)$/.exec(daemonRun);
+    const childKeyFromDaemonRun = announceMatch ? ("agent:main:subagent:" + announceMatch[1]) : "";
+
+    const refState = childKeyFromDaemonRun ? subagentRefByChildKey.get(childKeyFromDaemonRun) : undefined;
+
+    // 提取 announce-轮 assistant 文本(= subagent 最终答复,被 parent 转述)
+    const announceText = extractAssistantText(event?.messages);
+
+    if (childKeyFromDaemonRun && refState) {
+      // ── B1. subagent announce 命中:文本同时挂 parent + child,parent 内联预览 summary ──
+      const status = ok ? "completed" : "failed";
+      const stopReason = ok ? "end_turn" : "error";
+      log.info(
+        `agent_end subagent-announce: thread=${rc.thread_id} ` +
+        `daemon_run=${daemonRun} childKey=${childKeyFromDaemonRun} ` +
+        `subRunId=${refState.subRunId} text_len=${announceText.length} ok=${ok}`,
+      );
+
+      const envs = [];
+
+      // ① text content_block on PARENT run — 主流可见的"最终自然语言答复"
+      if (announceText) {
+        const parentIdx = nextBlockIndex(refState.parentRunId);
+        const parentStarted = envelopeBuilder.buildBlockStarted(
+          refState.parentRunId,
+          { type: "text", format: "markdown", text: "" },
+          parentIdx,
+        );
+        const parentBlockId = parentStarted.payload.block.id;
+        envs.push(parentStarted);
+
+        // buildBlockDelta 签名是 (runId, blockId, delta, index) —— 不要塞多余的
+        // "text" 位置参数，否则 delta 变成字面量 {text_append:"text"}、index 变成对象。
+        envs.push(envelopeBuilder.buildBlockDelta(
+          refState.parentRunId,
+          parentBlockId,
+          { text_append: announceText },
+          parentIdx,
+        ));
+
+        envs.push(envelopeBuilder.buildBlockCompleted(
+          refState.parentRunId,
+          { id: parentBlockId, type: "text", format: "markdown", text: announceText, status: "completed" },
+          parentIdx,
+        ));
+      }
+
+      // ② text content_block on CHILD sub-run — subagent_ref 详情页可见
+      // child 所有 envelope 必须挂 parent_run_id + child_session_key,与
+      // after_tool_call 里 buildRunStarted 时挂的字段一致。
+      if (announceText) {
+        const childIdx = nextBlockIndex(refState.subRunId);
+        const childStarted = envelopeBuilder.buildBlockStarted(
+          refState.subRunId,
+          { type: "text", format: "markdown", text: "" },
+          childIdx,
+        );
+        childStarted.parent_run_id = refState.parentRunId;
+        stampChildSessionKey(childStarted, childKeyFromDaemonRun);
+        const childBlockId = childStarted.payload.block.id;
+        envs.push(childStarted);
+
+        const childDelta = envelopeBuilder.buildBlockDelta(
+          refState.subRunId,
+          childBlockId,
+          { text_append: announceText },
+          childIdx,
+        );
+        childDelta.parent_run_id = refState.parentRunId;
+        stampChildSessionKey(childDelta, childKeyFromDaemonRun);
+        envs.push(childDelta);
+
+        const childCompleted = envelopeBuilder.buildBlockCompleted(
+          refState.subRunId,
+          { id: childBlockId, type: "text", format: "markdown", text: announceText, status: "completed" },
+          childIdx,
+        );
+        childCompleted.parent_run_id = refState.parentRunId;
+        stampChildSessionKey(childCompleted, childKeyFromDaemonRun);
+        envs.push(childCompleted);
+      }
+
+      // ③ subagent_ref.completed on parent run,summary 填入 text 作内联预览
+      const refCompleted = envelopeBuilder.buildBlockCompleted(
+        refState.parentRunId,
+        {
+          id: refState.refBlockId,
+          type: "subagent_ref",
+          child_run_id: refState.subRunId,
+          spawn_tool_use_id: refState.callId,
+          agent: refState.agent,
+          status,
+          stop_reason: stopReason,
+          summary: announceText,
+        },
+      );
+      envs.push(refCompleted);
+
+      // ④ child run.completed / run.failed
+      let runTerminal;
+      if (ok) {
+        runTerminal = envelopeBuilder.buildRunCompleted(refState.subRunId, "end_turn");
+      } else {
+        const errMsg =
+          (typeof event?.error === "string" && event.error.trim()) || "subagent failed";
+        runTerminal = envelopeBuilder.buildRunFailed(refState.subRunId, "runtime", errMsg);
+      }
+      runTerminal.parent_run_id = refState.parentRunId;
+      stampChildSessionKey(runTerminal, childKeyFromDaemonRun);
+      envs.push(runTerminal);
+
+      enqueuePost(refState.subRunId, ctx, envs);
+      subagentRefByChildKey.delete(childKeyFromDaemonRun);
+      dropBlockIndex(refState.subRunId);
+      return;
+    }
+
+    // ── B2. 非 subagent 的自发轮 fallback(announceMatch 没命中,或 refState 缺失)──
+    // 例如 cron / 系统自发投递 / 子轮但 refState 已被清。沿用原 followup top-level run。
+    // 注意:这条路径是 best-effort 兜底,验证场景里基本不应该走到。
+    log.warn(
+      `agent_end fallback (non-subagent autonomous): thread=${rc.thread_id} ` +
+      `daemon_run=${daemonRun} (no refState for childKey=${childKeyFromDaemonRun || "<none>"})`,
+    );
+
+    const followupRunId = deriveAutonomousFollowupRunId(rc.thread_id, daemonRun);
+    if (!followupRunId) return;
+    const envs = [];
+    const runStarted = envelopeBuilder.buildRunStarted(followupRunId, {
+      model: "",
+      options: {
+        autonomous_followup: true,
+        daemon_run_id: daemonRun,
+      },
+    });
+    runStarted.extensions = {
+      ...(runStarted.extensions || {}),
+      openclaw: {
+        ...(runStarted.extensions?.openclaw || {}),
+        autonomous_followup: true,
+      },
+    };
+    envs.push(runStarted);
+
+    if (announceText) {
+      const idx = nextBlockIndex(followupRunId);
+      const started = envelopeBuilder.buildBlockStarted(
+        followupRunId,
+        { type: "text", format: "markdown", text: "" },
+        idx,
+      );
+      const blockId = started.payload.block.id;
+      envs.push(started);
+      envs.push(
+        envelopeBuilder.buildBlockDelta(
+          followupRunId,
+          blockId,
+          { text_append: announceText },
+          idx,
+        ),
+      );
+      envs.push(
+        envelopeBuilder.buildBlockCompleted(
+          followupRunId,
+          { id: blockId, type: "text", format: "markdown", text: announceText, status: "completed" },
+          idx,
+        ),
+      );
+    }
+
+    if (ok) {
+      envs.push(envelopeBuilder.buildRunCompleted(followupRunId, "end_turn"));
+    } else {
+      const message =
+        (typeof event?.error === "string" && event.error.trim()) || "agent failed";
+      envs.push(envelopeBuilder.buildRunFailed(followupRunId, "runtime", message));
+    }
+
+    enqueuePost(null, ctx, envs);
+    dropBlockIndex(followupRunId);
+  });
+
+  // ── 2d: agentlink_attach_file / change_title / notify_user tool injection ──
+  // OpenClaw 不支持 MCP server 配置(2026.3.13 没有 `openclaw mcp` 子命令),
+  // 所以 agentlink 工具通过 plugin 注入。流程:
+  //   1) 读 ~/.agentlink/tools-server.json discovery 文件;不存在 → bridge 没跑,
+  //      log info 后跳过(等下次 plugin reload 或 mtime poll)
+  //   2) HTTP GET (实际是 POST {}) /tools/list 拿 agentlink tools registry
+  //   3) 对每个 tool 探测 api.tools.register 是否存在:
+  //      - 不存在 → log warn "unsupported on this OpenClaw version", 不注册
+  //      - 存在 → 注册一个 forwarder: agent call → POST /tools/call → 拿 result
+  //   4) 30s 轮询 discovery 文件 mtime, 变化(bridge 重启分配新端口)就刷新
+  //
+  // 失败任意一步都不让 plugin 整体失败 —— hook 转发是原生职责, tool injection
+  // 是新增功能。
+  tryInjectAgentlinkTools({ api, log, warnThrottled }).catch((err) => {
+    log.warn(`agentlink tool injection failed: ${err?.message || err}`);
+  });
+}
+
+/**
+ * 探测 OpenClaw plugin API 是否支持 tool 注册,支持就把 agentlinkToolsServer
+ * 暴露的工具批量注册过去。
+ *
+ * 设计要点:
+ *   - discovery 文件缺失 → 不报错,只 log info(bridge 没跑是合法状态)
+ *   - api.tools.register 缺失 → 一次性 warn,后续 plugin 启动若 API 出现可自愈
+ *   - 注册成功后启动 30s mtime poller, bridge 重启换端口时自动重新拉取 tools
+ */
+async function tryInjectAgentlinkTools({ api, log, warnThrottled }) {
+  const fs = require("node:fs");
+  const fsP = require("node:fs/promises");
+  const path = require("node:path");
+  const os = require("node:os");
+
+  const DISCOVERY_PATH = path.join(os.homedir(), ".agentlink", "tools-server.json");
+
+  if (typeof api.tools?.register !== "function") {
+    log.warn(
+      `tool injection unsupported on this OpenClaw version ` +
+      `(api.tools.register is undefined). agentlink_* tools won't be available to ` +
+      `OpenClaw LLM. Continuing with hook-only behavior.`,
+    );
+    return;
+  }
+
+  async function readDiscovery() {
+    try {
+      const raw = await fsP.readFile(DISCOVERY_PATH, "utf8");
+      const doc = JSON.parse(raw);
+      if (typeof doc?.url === "string" && typeof doc?.auth === "string") {
+        return doc;
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        log.warn(`discovery file read failed: ${err.message}`);
+      }
+    }
+    return null;
+  }
+
+  async function fetchToolsList(disc) {
+    const res = await fetch(`${disc.url.replace(/\/+$/, "")}/tools/list`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${disc.auth}`,
+      },
+      body: "{}",
+    });
+    if (!res.ok) {
+      throw new Error(`tools/list HTTP ${res.status}`);
+    }
+    const body = await res.json();
+    return Array.isArray(body?.tools) ? body.tools : [];
+  }
+
+  function makeHandler(toolName, disc) {
+    return async (args) => {
+      const res = await fetch(`${disc.url.replace(/\/+$/, "")}/tools/call`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${disc.auth}`,
+        },
+        body: JSON.stringify({ name: toolName, arguments: args || {} }),
+      });
+      const body = await res.json();
+      // body 已经是 MCP tools/call 标准 result shape: { content, isError? }
+      return body;
+    };
+  }
+
+  /** 当前已注册的 tool name 集合,刷新时与新 list 做 diff 决定 register/unregister。 */
+  let registeredNames = new Set();
+  let lastDiscPid = null;
+
+  async function refresh() {
+    const disc = await readDiscovery();
+    if (!disc) {
+      // bridge 没在跑, 不动现有注册(等下次 poll)
+      return;
+    }
+    // PID 变化 → bridge 重启过, 强制重新注册
+    const pidChanged = disc.pid !== lastDiscPid;
+    lastDiscPid = disc.pid;
+
+    let tools;
+    try {
+      tools = await fetchToolsList(disc);
+    } catch (err) {
+      log.warn(`tools/list fetch failed: ${err.message}`);
+      return;
+    }
+    const newNames = new Set(tools.map((t) => t.name));
+
+    // unregister 旧的(已不在 list 里或 PID 变了 = bridge 重启需要全部重新注册)
+    if (pidChanged && typeof api.tools.unregister === "function") {
+      for (const name of registeredNames) {
+        try { api.tools.unregister(name); } catch { /* swallow */ }
+      }
+      registeredNames = new Set();
+    } else if (typeof api.tools.unregister === "function") {
+      for (const name of registeredNames) {
+        if (!newNames.has(name)) {
+          try { api.tools.unregister(name); } catch { /* swallow */ }
+          registeredNames.delete(name);
+        }
+      }
+    }
+
+    // register 新的(同名重复注册若 API 不接受会 throw, 用 try/catch 兜底)
+    for (const tool of tools) {
+      if (registeredNames.has(tool.name)) continue;
+      try {
+        api.tools.register(
+          {
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+          },
+          makeHandler(tool.name, disc),
+        );
+        registeredNames.add(tool.name);
+        log.info(`registered agentlink tool: ${tool.name}`);
+      } catch (err) {
+        warnThrottled(`tool register failed for ${tool.name}: ${err.message}`);
+      }
+    }
+  }
+
+  // 首次注册
+  await refresh();
+
+  // 30s mtime poller, 检测 bridge 重启或 tools list 变化
+  let prevMtime = 0;
+  try {
+    prevMtime = fs.statSync(DISCOVERY_PATH).mtimeMs;
+  } catch { /* discovery 不存在 = 0 */ }
+
+  const pollInterval = setInterval(async () => {
+    let curMtime = 0;
+    try { curMtime = fs.statSync(DISCOVERY_PATH).mtimeMs; }
+    catch { /* discovery gone, treat as 0 */ }
+    if (curMtime !== prevMtime) {
+      prevMtime = curMtime;
+      await refresh().catch((err) => log.warn(`refresh threw: ${err.message}`));
+    }
+  }, 30_000);
+  pollInterval.unref?.();
+
+  // plugin shutdown 时清掉 poller(若 OpenClaw 提供 beforeExit / unload 钩子)
+  process.on("beforeExit", () => clearInterval(pollInterval));
+}
+
+module.exports = {
+  id: "agentlink-hooks",
+  name: "Agentlink Hooks",
+  description: "Captures OpenClaw tool-call, subagent and agent_end lifecycle events and forwards them to the Agentlink relay as unified Agent Protocol envelopes (tool_use / tool_result / run.completed / run.failed).",
+  register,
+};