@masons/agent-network 0.4.20 → 0.4.22

package/dist/channel.d.ts

@@ -1,4 +1,6 @@
 import type { AgentNetworkAccount } from "./config-schema.js";
+/** Get the stored owner Passport address (first is_owner visit). */
+export declare function getOwnerPassportAddress(): string | null;
 interface ChannelMeta {
     name: string;
     description: string;

package/dist/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAgC9D,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAsDD,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AAsRD,eAAO,MAAM,mBAAmB,EAAE,yBAsNjC,CAAC"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AA2B9D,oEAAoE;AACpE,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAQD,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC9B,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC;IACvD,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;IACpE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;IACjE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;CAC/D;AAED,UAAU,sBAAsB;IAC9B,EAAE,EAAE,OAAO,CAAC;CACb;AAED,UAAU,sBAAsB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,sBAAsB;IAC9B,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACzE;AAED,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAsDD,UAAU,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACzC,YAAY,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,WAAW,CAAC,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,UAAU,yBAAyB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,CAAC;IAClB,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,oBAAoB,CAAC,mBAAmB,CAAC,CAAC;IAClD,QAAQ,EAAE,sBAAsB,CAAC;IACjC,OAAO,EAAE,qBAAqB,CAAC,mBAAmB,CAAC,CAAC;CACrD;AAgQD,eAAO,MAAM,mBAAmB,EAAE,yBAwNjC,CAAC"}

package/dist/channel.js

@@ -1,19 +1,26 @@
 import { randomUUID } from "node:crypto";
 import createDebug from "debug";
-import { clearConnectorClient, clearConversationManager, extractNetworkConfig, getTelegramOwnerUserId, initConnectorClient, initConversationManager, initToolConfig, isIdentityLinksConfigured, requirePluginRuntime, writeIdentityLinks, } from "./config.js";
+import { clearConnectorClient, clearConversationManager, extractNetworkConfig, getDmScope, initConnectorClient, initConversationManager, initToolConfig, isIdentityLinksConfigured, requirePluginRuntime, } from "./config.js";
 import { ConnectorClient } from "./connector-client.js";
 import { ConversationManager } from "./conversation-manager.js";
-import { clearEnvironmentContext, getOwnerHandle, } from "./environment-context.js";
+import { clearEnvironmentContext } from "./environment-context.js";
 import { extractHandleFromAddress } from "./handle-utils.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { clearOwnerState, isOwnerAddress, markOwnerAddress, setCurrentTurnIsOwner, } from "./owner-session-state.js";
 import { setCurrentTurnSender } from "./turn-context.js";
 import { checkForUpdate } from "./update-check.js";
 const dbg = createDebug("agent-network:channel");
-// Cross-channel identity auto-link: once per startAccount lifecycle idempotency
-// guard. Reset on startAccount(). isIdentityLinksConfigured() provides the
+// Cross-channel identity notification: once per startAccount lifecycle.
+// Reset on startAccount(). isIdentityLinksConfigured() provides the
 // cross-restart idempotency (checks config file).
-let identityLinkAttempted = false;
+let notificationAttempted = false;
+// Owner's Passport address: recorded on first is_owner MESSAGE_RECEIVED.
+// Used by masons_link_identity tool to auto-include the Passport entry.
+let storedOwnerPassportAddress = null;
+/** Get the stored owner Passport address (first is_owner visit). */
+export function getOwnerPassportAddress() {
+    return storedOwnerPassportAddress;
+}
 // --- Sender identity ---
 /**
  * Extract a human-readable name from the sender's metadata.
@@ -86,52 +93,29 @@ async function handleAddressedMessage(event, conversationManager, client, ctx) {
     // Connector includes is_owner in metadata for Passport visitors.
     if (event.metadata?.is_owner === true) {
         markOwnerAddress(fromAddress);
-        // --- Cross-channel identity auto-link (2026-03-26, #969) ---
-        // When owner visits Passport and identity is not yet linked,
-        // auto-configure session.identityLinks for session merge.
-        //
-        // Trust levels of data used here:
-        // - is_owner: cryptographically derived (Clerk JWT match) — triggers write
-        // - ownerHandle (from REGISTER_ACK): Connector-asserted — used only as
-        //   canonical group name, not for access decisions
-        // - telegramId (from cfg.channels.telegram.allowFrom): config-derived —
-        //   inferred owner in single-user setup, not crypto-verified
-        if (!isIdentityLinksConfigured() && !identityLinkAttempted) {
-            identityLinkAttempted = true;
-            const ownerHandle = getOwnerHandle();
-            const telegramId = getTelegramOwnerUserId();
-            if (ownerHandle && telegramId) {
-                // Scenario A: allowFrom has 1 ID — act-then-inform (Gmail undo).
-                // Notification is conditional on write success to avoid false positive.
-                const entries = [
-                    `telegram:${telegramId}`,
-                    `agent-network:${fromAddress}`,
-                ];
-                writeIdentityLinks(ownerHandle, entries)
-                    .then(() => {
-                    // TODO: i18n — notification language should match owner's locale
-                    ownerNotesQueue.enqueue({
-                        content: "你刚才在我的网页上跟我聊过。我已经准备好了跨渠道关联 — " +
-                            "重启后不管你从 Telegram 还是网页跟我对话，我都会记得之前聊过什么。" +
-                            "如果这不是你，告诉我撤销。",
-                        timestamp: Date.now(),
-                    });
-                    dbg("auto-linked owner identity: %s → telegram:%s + agent-network:%s", ownerHandle, telegramId, fromAddress);
-                })
-                    .catch((err) => {
-                    dbg("auto-link writeIdentityLinks failed: %O", err);
-                });
-            }
-            else if (ownerHandle) {
-                // Scenario B: cannot determine Telegram ID — notify owner.
-                // TODO: i18n — notification language should match owner's locale
-                ownerNotesQueue.enqueue({
-                    content: "你刚才在我的网页上跟我聊过。如果你想让我在 Telegram 和网页上" +
-                        "都能认出你、记住对话，告诉我你的 Telegram 用户 ID。",
-                    timestamp: Date.now(),
-                });
-                dbg("owner detected on Passport but no Telegram ID available");
-            }
+        // Record Passport address for tool auto-include (first visit only)
+        if (!storedOwnerPassportAddress) {
+            storedOwnerPassportAddress = fromAddress;
+            dbg("recorded owner Passport address: %s", fromAddress);
+        }
+        // --- dmScope-aware notification (2026-03-26, #986 redesign) ---
+        // Notify the owner about cross-channel identity linking availability.
+        // Notification is:
+        // - Skipped in "main" mode (linking has no effect — Gateway skips resolveLinkedPeerId)
+        // - Skipped if identityLinks already configured (already linked)
+        // - Sent once per startAccount lifecycle (in-memory idempotency)
+        // Content is channel-agnostic and language-neutral (semantic event, not identity claim).
+        if (getDmScope() !== "main" &&
+            !isIdentityLinksConfigured() &&
+            !notificationAttempted) {
+            notificationAttempted = true;
+            ownerNotesQueue.enqueue({
+                content: "Owner visited via Passport (verified). " +
+                    "Cross-channel identity linking is available but not configured. " +
+                    "The owner can link their identity across channels so conversations share context.",
+                timestamp: Date.now(),
+            });
+            dbg("queued identity linking notification (dmScope=%s)", getDmScope());
         }
     }
     setCurrentTurnIsOwner(isOwnerAddress(fromAddress));
@@ -220,6 +204,10 @@ async function handleAddressedMessage(event, conversationManager, client, ctx) {
         }
         finally {
             client.sendTyping(fromAddress, false);
+            // Commit deferred deletions from end_conversation calls made during
+            // this dispatch cycle. Must run after text buffer flush so that
+            // hasConversation() returns true for the deliver callback (#999).
+            conversationManager.commitEndedConversations();
         }
     }
     catch (err) {
@@ -298,7 +286,9 @@ export const agentNetworkChannel = {
     gateway: {
         async startAccount(ctx) {
             dbg("starting account %s", ctx.accountId);
-            identityLinkAttempted = false; // Reset per-session idempotency guard
+            // Reset per-session state
+            notificationAttempted = false;
+            storedOwnerPassportAddress = null;
             // Defensive: clear stale singletons from a previous cycle.
             // The abort handler intentionally leaves them alive for in-flight tool
             // calls (#935). Clean up here at cycle start so initConnectorClient()

package/dist/config.d.ts

@@ -44,8 +44,16 @@ export declare function initToolConfig(cfg: Record<string, unknown>): void;
  * identity is linked to another channel.
  */
 export declare function isIdentityLinksConfigured(): boolean;
-/** Telegram owner user ID (only when allowFrom has exactly 1 entry). */
-export declare function getTelegramOwnerUserId(): string | null;
+/**
+ * Current dmScope mode from Gateway config (`cfg.session.dmScope`).
+ *
+ * Determines how the plugin handles cross-channel identity:
+ * - "main" (default): all DMs share one session. Identity linking has no effect.
+ * - "per-peer": identity linking merges sessions across channels.
+ * - "per-channel-peer" / "per-account-channel-peer": identity linking normalizes
+ *   peerId but sessions stay separate per channel.
+ */
+export declare function getDmScope(): string;
 /**
  * Inject the live ConnectorClient after WebSocket connection is established.
  *
@@ -194,8 +202,13 @@ export declare function markProfileComplete(): Promise<void>;
 /**
  * Write cross-channel identity links to `config.session.identityLinks`.
  *
- * Merges a new canonical identity group into the existing identityLinks
- * map. Never overwrites other canonical groups.
+ * **Entry-level additive merge** (2026-03-26, #986 redesign):
+ * New entries are merged INTO the existing canonical group, deduped,
+ * lowercase-normalized. Never overwrites other canonical groups, and
+ * never removes existing entries within the same group.
+ *
+ * This allows one-channel-at-a-time linking: first call adds Telegram,
+ * second call adds Feishu — without losing the Telegram entry.
  *
  * This writes to `session.*` (Gateway-level), not `channels.agent-network.*`.
  * Justified because cross-channel identity is inherently a Gateway concern,

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAiC9B;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAcD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAMhC;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAyCjE;AAkCD;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAOjE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,mBAAmB,CAOhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,mBAAmB,GAAG,IAAI,CAEnE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAO9C;AAMD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,oBAAoB,CAE5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,eAAe,CAOxD;AAMD,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAgDD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CASvD;AAMD;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOvD;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOzD;AAsBD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B1E;AAMD,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CA2BhE;AAMD,uDAAuD;AACvD,wBAAgB,gBAAgB,IAAI,IAAI,CAWvC"}

package/dist/config.js

@@ -31,9 +31,14 @@ let platformConfig = { apiHost: DEFAULT_API_HOST };
 let storedApiKey = null;
 let storedPendingTarget = null;
 let storedNeedsProfile = false;
-// Cross-channel identity state (from cfg.session + cfg.channels.telegram — set by initToolConfig)
+// Cross-channel identity state (from cfg.session — set by initToolConfig)
 let storedIdentityLinksConfigured = false;
-let storedTelegramOwnerUserId = null;
+// dmScope from cfg.session.dmScope — determines notification + linking behavior.
+// "main" (default): all DMs share one session. Identity linking has no effect.
+// "per-peer": identity linking merges sessions across channels.
+// "per-channel-peer" / "per-account-channel-peer": identity linking normalizes
+//   peerId but sessions stay separate per channel.
+let storedDmScope = "main";
 // State cache generation — incremented when config-modifying functions write
 // to disk (writeCredentials, clearTargetHandle, markProfileNeeded, markProfileComplete).
 // before_prompt_build compares its cached generation to this value; mismatch
@@ -99,19 +104,20 @@ export function initToolConfig(cfg) {
             : null;
     storedNeedsProfile = networkCfg?.needsProfile === true;
     // --- Cross-channel identity state (cfg.session, not cfg.channels) ---
-    // Decision: 2026-03-26, during cross-channel identity linking design (#969).
+    // Decision: 2026-03-26, during cross-channel identity linking design (#969, #986).
     //
-    // Global Awareness (cross-channel, platform-gap workaround)
-    // Reads Gateway-level session.identityLinks to detect if the owner's
-    // agent-network identity is linked to other channels. Used by
-    // channel.ts auto-link logic and tools.
+    // Reads Gateway-level session config to detect:
+    // 1. Whether identityLinks already contains agent-network entries
+    // 2. The dmScope mode (determines notification + linking behavior)
     //
     // These are NOT agent-network-specific — any channel plugin would need
     // similar capabilities. They live here because only one channel plugin
     // exists today. When OpenClaw provides native cross-channel identity
     // management, this should migrate.
     storedIdentityLinksConfigured = hasAgentNetworkIdentityLink(cfg);
-    storedTelegramOwnerUserId = extractTelegramOwnerUserId(cfg);
+    const sessionCfg = cfg.session;
+    storedDmScope =
+        typeof sessionCfg?.dmScope === "string" ? sessionCfg.dmScope : "main";
 }
 // ---------------------------------------------------------------------------
 // Cross-channel identity detection
@@ -149,44 +155,16 @@ export function isIdentityLinksConfigured() {
     return storedIdentityLinksConfigured;
 }
 /**
- * Extract the owner's Telegram user ID from `cfg.channels.telegram.allowFrom`.
+ * Current dmScope mode from Gateway config (`cfg.session.dmScope`).
  *
- * Returns the ID only when `allowFrom` has exactly one entry (deterministic
- * single-user case). Multi-user `allowFrom` returns null — cannot determine
- * which ID is the owner.
- *
- * Trust level: config-derived (not cryptographically verified). Ownership is
- * inferred from the single-user assumption (allowFrom has exactly 1 entry =
- * that person is the owner by convention).
- *
- * Platform-gap workaround (2026-03-26, #969): reads another channel's config
- * (cfg.channels.telegram) to infer the owner's Telegram ID. When OpenClaw
- * provides a native "owner identifiers" API, this cross-channel read should
- * be removed.
- *
- * Strips `telegram:` / `tg:` prefix if present (OpenClaw normalizes these).
+ * Determines how the plugin handles cross-channel identity:
+ * - "main" (default): all DMs share one session. Identity linking has no effect.
+ * - "per-peer": identity linking merges sessions across channels.
+ * - "per-channel-peer" / "per-account-channel-peer": identity linking normalizes
+ *   peerId but sessions stay separate per channel.
  */
-function extractTelegramOwnerUserId(cfg) {
-    const channels = cfg.channels;
-    if (!channels)
-        return null;
-    const telegram = channels.telegram;
-    if (!telegram)
-        return null;
-    const allowFrom = telegram.allowFrom;
-    if (!Array.isArray(allowFrom) || allowFrom.length !== 1)
-        return null;
-    const raw = String(allowFrom[0] ?? "")
-        .replace(/^(telegram|tg):/i, "")
-        .trim();
-    // Validate: must be numeric, 1-20 digits
-    if (/^\d{1,20}$/.test(raw))
-        return raw;
-    return null;
-}
-/** Telegram owner user ID (only when allowFrom has exactly 1 entry). */
-export function getTelegramOwnerUserId() {
-    return storedTelegramOwnerUserId;
+export function getDmScope() {
+    return storedDmScope;
 }
 // ---------------------------------------------------------------------------
 // ConnectorClient injection (called by startAccount() after connect)
@@ -496,8 +474,13 @@ function ensureSessionSection(config) {
 /**
  * Write cross-channel identity links to `config.session.identityLinks`.
  *
- * Merges a new canonical identity group into the existing identityLinks
- * map. Never overwrites other canonical groups.
+ * **Entry-level additive merge** (2026-03-26, #986 redesign):
+ * New entries are merged INTO the existing canonical group, deduped,
+ * lowercase-normalized. Never overwrites other canonical groups, and
+ * never removes existing entries within the same group.
+ *
+ * This allows one-channel-at-a-time linking: first call adds Telegram,
+ * second call adds Feishu — without losing the Telegram entry.
  *
  * This writes to `session.*` (Gateway-level), not `channels.agent-network.*`.
  * Justified because cross-channel identity is inherently a Gateway concern,
@@ -513,7 +496,11 @@ export async function writeIdentityLinks(canonical, entries) {
     const existing = typeof session.identityLinks === "object" && session.identityLinks !== null
         ? session.identityLinks
         : {};
-    existing[canonical] = entries;
+    // Entry-level additive merge: combine new entries into existing group
+    const current = existing[canonical] ?? [];
+    const normalized = entries.map((e) => e.toLowerCase());
+    const merged = [...new Set([...current, ...normalized])];
+    existing[canonical] = merged;
     session.identityLinks = existing;
     await persistConfig(config);
     // Update module-level state — same exception pattern as writeCredentials
@@ -582,7 +569,7 @@ export function _resetForTesting() {
     storedPendingTarget = null;
     storedNeedsProfile = false;
     storedIdentityLinksConfigured = false;
-    storedTelegramOwnerUserId = null;
+    storedDmScope = "main";
     storedConnectorClient = null;
     storedConversationManager = null;
     storedPluginRuntime = null;

package/dist/conversation-manager.d.ts

@@ -23,6 +23,20 @@ export interface ConversationEntry {
     address: string;
     lastMessageAt: number;
     initiatedBy: "local" | "remote";
+    /**
+     * Deferred deletion flag (#999).
+     *
+     * When `masons_end_conversation` runs during a dispatch cycle, the entry
+     * is marked `ended` but NOT removed from the Map. This keeps
+     * `hasConversation()` returning true so the deliver callback can still
+     * flush buffered text from the same LLM turn.
+     *
+     * Call `commitEndedConversations()` after the dispatch cycle completes
+     * to actually remove ended entries.
+     *
+     * @see https://github.com/MASONS-ai/masons.ai/issues/999
+     */
+    ended?: boolean;
 }
 export interface ConversationSummary {
     contact: string;
@@ -68,17 +82,41 @@ export declare class ConversationManager {
     /**
      * Check if a conversation entry exists for a contact.
      *
-     * Used by the deliver callback to detect post-end straggler text:
-     * endConversation() deletes the entry, so its absence signals that
-     * the LLM called masons_end_conversation during this dispatch.
+     * Returns true for entries that are marked `ended` but not yet committed —
+     * this allows the deliver callback to flush buffered text from the same
+     * dispatch cycle as end_conversation (#999).
+     *
+     * Straggler text from *subsequent* dispatch cycles is still suppressed
+     * because `commitEndedConversations()` removes entries between cycles.
      */
     hasConversation(contact: string): boolean;
     /**
-     * End the conversation with a contact.
-     * Removes the conversation entry. No END_SESSION needed — the Connector
-     * manages connection lifecycle (idle timeout).
+     * Mark the conversation with a contact as ended (deferred deletion).
+     *
+     * The entry is NOT removed immediately — it is flagged `ended` and stays
+     * in the Map until `commitEndedConversations()` is called after the
+     * current dispatch cycle completes. This prevents the "last-message-
+     * before-close" race where the dispatcher executes end_conversation
+     * before flushing buffered text (#999).
+     *
+     * No END_SESSION needed — the Connector manages connection lifecycle
+     * (idle timeout).
      */
     endConversation(contact: string): void;
+    /**
+     * Remove all conversations marked as `ended`.
+     *
+     * Call this after the dispatch cycle completes (in the `finally` block
+     * of `handleAddressedMessage`). Deferred deletion ensures that text
+     * buffered in the same dispatch cycle as end_conversation is delivered
+     * before the entry disappears.
+     *
+     * Pattern: React 18 batched updates / Qt `deleteLater()` — mutations
+     * during a dispatch cycle are committed only when the cycle ends.
+     *
+     * @see https://github.com/MASONS-ai/masons.ai/issues/999
+     */
+    commitEndedConversations(): void;
     /**
      * Resolve a contact (handle, MSTP address, or passport address) to a
      * routable address.

package/dist/conversation-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation-manager.d.ts","sourceRoot":"","sources":["../src/conversation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,eAAe,EAAkB,MAAM,uBAAuB,CAAC;AAS7E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAwBD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;gBAE1D,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM;IAS1D;;;;;;;;;;OAUG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA0CjE;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAKvD;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAaxD;;;;OAIG;IACH,iBAAiB,IAAI,mBAAmB,EAAE;IAc1C;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKzC;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAUtC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAoBvC;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQtC,OAAO,CAAC,uBAAuB;IAwB/B,0CAA0C;IAC1C,gBAAgB,IAAI,IAAI;CAGzB"}
+{"version":3,"file":"conversation-manager.d.ts","sourceRoot":"","sources":["../src/conversation-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,eAAe,EAAkB,MAAM,uBAAuB,CAAC;AAS7E,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;IAChC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,GAAG,QAAQ,CAAC;CACjC;AAwBD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAwC;gBAE1D,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM;IAS1D;;;;;;;;;;OAUG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA0CjE;;;OAGG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAKvD;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAaxD;;;;OAIG;IACH,iBAAiB,IAAI,mBAAmB,EAAE;IAc1C;;;;;;;;;OASG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAKzC;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAWtC;;;;;;;;;;;;OAYG;IACH,wBAAwB,IAAI,IAAI;IAiBhC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAoBvC;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQtC,OAAO,CAAC,uBAAuB;IAyB/B,0CAA0C;IAC1C,gBAAgB,IAAI,IAAI;CAGzB"}

package/dist/conversation-manager.js

@@ -122,7 +122,7 @@ export class ConversationManager {
             result.push({
                 contact: entry.contact,
                 address: entry.address,
-                active: true,
+                active: !entry.ended,
                 lastMessageAt: entry.lastMessageAt,
                 initiatedBy: entry.initiatedBy,
             });
@@ -132,23 +132,64 @@ export class ConversationManager {
     /**
      * Check if a conversation entry exists for a contact.
      *
-     * Used by the deliver callback to detect post-end straggler text:
-     * endConversation() deletes the entry, so its absence signals that
-     * the LLM called masons_end_conversation during this dispatch.
+     * Returns true for entries that are marked `ended` but not yet committed —
+     * this allows the deliver callback to flush buffered text from the same
+     * dispatch cycle as end_conversation (#999).
+     *
+     * Straggler text from *subsequent* dispatch cycles is still suppressed
+     * because `commitEndedConversations()` removes entries between cycles.
      */
     hasConversation(contact) {
         const address = this.resolveAddress(contact);
         return this.conversations.has(address);
     }
     /**
-     * End the conversation with a contact.
-     * Removes the conversation entry. No END_SESSION needed — the Connector
-     * manages connection lifecycle (idle timeout).
+     * Mark the conversation with a contact as ended (deferred deletion).
+     *
+     * The entry is NOT removed immediately — it is flagged `ended` and stays
+     * in the Map until `commitEndedConversations()` is called after the
+     * current dispatch cycle completes. This prevents the "last-message-
+     * before-close" race where the dispatcher executes end_conversation
+     * before flushing buffered text (#999).
+     *
+     * No END_SESSION needed — the Connector manages connection lifecycle
+     * (idle timeout).
      */
     endConversation(contact) {
         const address = this.resolveAddress(contact);
-        this.conversations.delete(address);
-        dbg("endConversation contact=%s address=%s", contact, address);
+        const entry = this.conversations.get(address);
+        if (entry) {
+            entry.ended = true;
+            dbg("endConversation (deferred) contact=%s address=%s", contact, address);
+        }
+        else {
+            dbg("endConversation (no-op) contact=%s address=%s", contact, address);
+        }
+    }
+    /**
+     * Remove all conversations marked as `ended`.
+     *
+     * Call this after the dispatch cycle completes (in the `finally` block
+     * of `handleAddressedMessage`). Deferred deletion ensures that text
+     * buffered in the same dispatch cycle as end_conversation is delivered
+     * before the entry disappears.
+     *
+     * Pattern: React 18 batched updates / Qt `deleteLater()` — mutations
+     * during a dispatch cycle are committed only when the cycle ends.
+     *
+     * @see https://github.com/MASONS-ai/masons.ai/issues/999
+     */
+    commitEndedConversations() {
+        let count = 0;
+        for (const [address, entry] of this.conversations) {
+            if (entry.ended) {
+                this.conversations.delete(address);
+                count++;
+            }
+        }
+        if (count > 0) {
+            dbg("commitEndedConversations removed=%d", count);
+        }
     }
     // -------------------------------------------------------------------------
     // Contact resolution
@@ -210,6 +251,7 @@ export class ConversationManager {
             const entry = this.conversations.get(address);
             if (entry) {
                 entry.lastMessageAt = Date.now();
+                entry.ended = false; // Clear deferred deletion on re-registration
             }
         }
     }

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAqHA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CAwUhC,CAAC;AAEF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AA0HA,UAAU,iBAAiB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CACnE;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;kBA4BI,iBAAiB;CA8VhC,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/plugin.js

@@ -3,13 +3,13 @@
 // NOT imported by index.ts to avoid pulling ws/typebox into Next.js app bundles.
 import { agentNetworkChannel } from "./channel.js";
 import { configureInteractive } from "./cli-setup.js";
-import { detectPendingState, getConversationManager, getStateCacheGeneration, initPluginRuntime, } from "./config.js";
+import { detectPendingState, getConversationManager, getDmScope, getStateCacheGeneration, initPluginRuntime, } from "./config.js";
 import { getAgentIdentity } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { consumeCurrentTurnIsOwner } from "./owner-session-state.js";
 import { sentMessageBuffer } from "./sent-message-buffer.js";
 import { registerTools } from "./tools.js";
-import { consumeCurrentTurnSender } from "./turn-context.js";
+import { consumeCurrentTurnSender, setCurrentTurnChannelId, setCurrentTurnIsOwnerForTools, } from "./turn-context.js";
 import { getUpdateInfo } from "./update-check.js";
 import { PLUGIN_VERSION } from "./version.js";
 // ---------------------------------------------------------------------------
@@ -197,16 +197,29 @@ const plugin = {
             "Should you follow up with another agent via masons_send_message? " +
             "When the interaction is complete, call masons_end_conversation as your FINAL action — " +
             "do not generate any text reply after ending. " +
-            // --- Cross-channel identity linking knowledge (2026-03-26) ---
-            "When your owner visits your Passport page, the plugin may automatically " +
-            "link their cross-channel identity based on verified authentication. " +
-            "This does not change who your owner is — it helps you recognize them " +
-            "across channels so conversations share context. " +
-            "If your owner asks about cross-channel identity, explain how it works. " +
-            "Use masons_link_identity to link or masons_unlink_identity to undo.";
+            // --- Cross-channel identity linking knowledge removed from static TOOL_CONTEXT ---
+            // Moved to dynamicContext in before_prompt_build (#986 redesign).
+            // Reason: TOOL_CONTEXT is built in register() before startAccount() runs,
+            // so getDmScope() is not available. Linking knowledge is dmScope-conditional.
+            "";
         api.on("before_prompt_build", async (_event, ctx) => {
             const hookCtx = ctx;
             const channelId = hookCtx?.channelId;
+            // --- Consume per-turn flags unconditionally (#836, #873) ---
+            // MUST happen BEFORE any early return (config read timeout, etc.)
+            // to prevent stale state from leaking across turns. If not consumed,
+            // the value persists and is read on the NEXT turn, producing incorrect
+            // context or — critically — bypassing the access gate on identity tools.
+            const turnIsOwner = consumeCurrentTurnIsOwner();
+            const turnSender = consumeCurrentTurnSender();
+            // --- Store turn context for tool access gates (#986) ---
+            // Tools run AFTER before_prompt_build. The consumed flags above are gone
+            // by tool execution time. Store non-consuming copies so tools can check
+            // channelId and isOwner for access control (e.g., identity linking gate).
+            // These persist until the next before_prompt_build overwrites them.
+            // Assumption: OpenClaw processes turns sequentially per agent.
+            setCurrentTurnChannelId(channelId ?? null);
+            setCurrentTurnIsOwnerForTools(turnIsOwner);
             // --- Detect setup state (cached, re-read when config changes) ---
             const currentGeneration = getStateCacheGeneration();
             if (!cachedState || cachedGeneration !== currentGeneration) {
@@ -221,16 +234,11 @@ const plugin = {
                 catch {
                     // Config read failure — proceed without state-specific context.
                     // Will retry on next turn (cachedState stays null).
+                    // Per-turn flags were already consumed above — no stale state leak.
                     return {};
                 }
             }
             const state = cachedState;
-            // --- Consume per-turn flags unconditionally (#836, #873) ---
-            // Must consume on EVERY turn to prevent stale state from leaking across
-            // turns. If not consumed (e.g., agent is in setup flow), the value would
-            // persist and be read on the NEXT turn, producing incorrect context.
-            const turnIsOwner = consumeCurrentTurnIsOwner();
-            const turnSender = consumeCurrentTurnSender();
             // --- Build dynamic context based on setup state ---
             let dynamicContext;
             if (!state.hasCredentials) {
@@ -281,10 +289,7 @@ const plugin = {
                                     .map((n) => {
                                     const fromStr = n.from ? `@${n.from}` : "agent";
                                     const timeStr = formatTimeAgo(n.timestamp);
-                                    const preview = n.content.length > 100
-                                        ? `${n.content.slice(0, 100)}...`
-                                        : n.content;
-                                    return `• ${fromStr} (${timeStr}): "${preview}"`;
+                                    return `• ${fromStr} (${timeStr}): "${n.content}"`;
                                 })
                                     .join("\n")
                             : "";
@@ -337,10 +342,7 @@ const plugin = {
                         const lines = notes.map((n) => {
                             const fromStr = n.from ? `@${n.from}` : "agent";
                             const timeStr = formatTimeAgo(n.timestamp);
-                            const preview = n.content.length > 100
-                                ? `${n.content.slice(0, 100)}...`
-                                : n.content;
-                            return `• ${fromStr} (${timeStr}): "${preview}"`;
+                            return `• ${fromStr} (${timeStr}): "${n.content}"`;
                         });
                         dynamicContext =
                             "[Agent Network — Updates]\n" +
@@ -358,6 +360,25 @@ const plugin = {
                     }
                 }
             }
+            // --- dmScope-conditional linking knowledge (#986 redesign) ---
+            // Placed in dynamicContext (not static TOOL_CONTEXT) because getDmScope()
+            // is only available after startAccount() runs (initToolConfig reads cfg).
+            // TOOL_CONTEXT is built in register() before startAccount().
+            if (state.hasCredentials && !state.needsProfile && !state.pendingTarget) {
+                const dmScope = getDmScope();
+                if (dmScope !== "main") {
+                    const linkingKnowledge = "[Cross-Channel Identity] When your owner visits your Passport page, " +
+                        "the plugin detects them via verified authentication. " +
+                        "You can link their identity across channels so conversations share context. " +
+                        "Use masons_link_identity to link or masons_unlink_identity to undo. " +
+                        (dmScope === "per-peer"
+                            ? "After linking and gateway restart, conversations will merge across channels."
+                            : "After linking and gateway restart, identity will be normalized but conversations stay separate under current session configuration.");
+                    dynamicContext = dynamicContext
+                        ? `${dynamicContext}\n\n${linkingKnowledge}`
+                        : linkingKnowledge;
+                }
+            }
             // --- Self-identity preamble (#969) ---
             // Inject agent self-identity so the LLM knows who it is on the network.
             // Owner identity is NOT injected here — agent rejected it as untrusted

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA8CH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA+6BhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAqDH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AA0CD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAsFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CA88BhD"}

package/dist/tools.js

@@ -19,10 +19,13 @@
  */
 import { tmpdir } from "node:os";
 import { Type } from "@sinclair/typebox";
-import { clearTargetHandle, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, markProfileNeeded, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, writeIdentityLinks, } from "./config.js";
+import { getOwnerPassportAddress } from "./channel.js";
+import { clearTargetHandle, getDmScope, getOpenClawHome, getPendingTarget, isProfileNeeded, markProfileComplete, markProfileNeeded, removeIdentityLinks, requireApiKey, requireConversationManager, requirePlatformConfig, writeCredentials, writeIdentityLinks, } from "./config.js";
+import { getOwnerHandle } from "./environment-context.js";
 import { ownerNotesQueue } from "./owner-notes.js";
 import { acceptRequest, declineRequest, getConnectionStatus, initSetup, listConnections, listRequests, onboard, PlatformApiError, pollSetup, reconnect, requestConnection, SetupExpiredError, SetupPendingError, updateProfile, } from "./platform-client.js";
 import { sentMessageBuffer } from "./sent-message-buffer.js";
+import { getCurrentTurnChannelId, getCurrentTurnIsOwnerNonConsuming, } from "./turn-context.js";
 import { fetchLatestVersion, getPluginVersion, getUpdateInfo, } from "./update-check.js";
 // ---------------------------------------------------------------------------
 // Constants
@@ -750,89 +753,109 @@ export function registerTools(api) {
         },
     });
     // --- masons_link_identity -------------------------------------------------
-    // Generalized interface: accepts any canonical name and entries.
-    // Not locked to owner or Telegram — any cross-channel identity can be linked.
-    // See system-design.md §4C for design rationale.
+    // Simplified interface (#986 redesign): LLM provides only the current
+    // channel's entry. Canonical is auto-generated from getOwnerHandle().
+    // Passport entry is auto-included from storedOwnerPassportAddress.
+    // Access gate: deterministic owner-only check prevents prompt injection.
     api.registerTool({
         name: "masons_link_identity",
-        description: "Link a person's identity across channels so they are recognized as the same person. " +
-            "Each entry is in 'channel:peerId' format (e.g., 'telegram:5099353300', " +
-            "'agent-network:passport:@luomingke'). Requires a gateway restart to take effect.",
+        description: "Link your owner's identity on the current channel to their Passport identity. " +
+            "Provide only the current channel's entry in 'channel:peerId' format " +
+            "(e.g., 'telegram:5099353300', 'feishu:ou_abc123'). " +
+            "The canonical name and Passport entry are added automatically. " +
+            "Requires a gateway restart to take effect.",
         parameters: Type.Object({
-            canonical: Type.String({
-                description: "Identity group name — all entries under this name are treated as the same person.",
-            }),
-            entries: Type.Array(Type.String(), {
-                description: "Array of 'channel:peerId' entries to link (at least 2).",
-                minItems: 2,
+            entry: Type.String({
+                description: "Current channel's identity entry in 'channel:peerId' format " +
+                    "(e.g., 'telegram:5099353300', 'feishu:ou_abc123').",
             }),
         }),
-        execute: async (_id, params) => {
-            const canonical = String(params.canonical ?? "").trim();
-            if (!canonical) {
-                return textResult("Canonical name must be non-empty.");
-            }
-            const entries = params.entries;
-            if (!Array.isArray(entries) || entries.length < 2) {
-                return textResult("At least 2 entries are required to link identities.");
-            }
-            // Validate each entry has channel:peerId format
-            const validated = [];
-            for (const entry of entries) {
-                const str = String(entry).trim();
-                if (!str.includes(":")) {
-                    return textResult(`Invalid entry "${str}": must be in 'channel:peerId' format.`);
-                }
-                validated.push(str);
+        execute: withUpdateNotice(async (_id, params) => {
+            // --- Access gate (deterministic) ---
+            // Only the owner on an agent-network turn can invoke this tool.
+            // Prevents prompt injection from visitors or remote agents.
+            const hookChannelId = getCurrentTurnChannelId();
+            const turnIsOwner = getCurrentTurnIsOwnerNonConsuming();
+            if (hookChannelId === "agent-network" && !turnIsOwner) {
+                return textResult("Identity linking is only available to the agent's owner.");
+            }
+            const ownerHandle = getOwnerHandle();
+            if (!ownerHandle) {
+                return textResult("Not connected to the network. Cannot determine canonical identity.");
+            }
+            const entry = String(params.entry ?? "")
+                .trim()
+                .toLowerCase();
+            // Validate channel:peerId format — split on first colon only,
+            // both parts must be non-empty (e.g., "telegram:5099353300").
+            const colonIdx = entry.indexOf(":");
+            if (colonIdx < 1 || colonIdx === entry.length - 1) {
+                return textResult("Invalid format. Use 'channel:peerId' (e.g., 'telegram:5099353300').");
+            }
+            // Build entries: user-provided entry + auto-include Passport entry
+            const entries = [entry];
+            const passportAddr = getOwnerPassportAddress();
+            if (passportAddr) {
+                entries.push(`agent-network:${passportAddr}`);
             }
             try {
-                await writeIdentityLinks(canonical, validated);
+                // writeIdentityLinks does entry-level additive merge
+                await writeIdentityLinks(ownerHandle, entries);
             }
             catch (err) {
                 console.error("[masons_link_identity] writeIdentityLinks failed:", err);
                 return textResult("Failed to write identity links to config. Try again.");
             }
+            const dmScope = getDmScope();
+            const effectExplanation = dmScope === "per-peer"
+                ? "After restart, conversations will merge across linked channels."
+                : "After restart, identity will be normalized. Conversations stay separate under current session configuration (per-channel-peer). For full merge, change session.dmScope to per-peer.";
             return textResult([
                 "Identity linked successfully.",
-                `Canonical: ${canonical}`,
-                `Entries: ${validated.join(", ")}`,
+                `Canonical: ${ownerHandle}`,
+                `Entries added: ${entries.join(", ")}`,
+                "",
+                effectExplanation,
                 "",
                 "Restart required — call the `gateway` tool with action: restart, " +
                     'reason: "Activate cross-channel identity linking".',
             ].join("\n"));
-        },
+        }),
     }, 
     // optional: not all Gateway versions support this tool.
     { optional: true });
     // --- masons_unlink_identity -----------------------------------------------
-    // Undo path: removes a canonical identity group from session.identityLinks.
+    // Undo path: removes the owner's canonical identity group from session.identityLinks.
+    // Access gate: same owner-only check as masons_link_identity.
     api.registerTool({
         name: "masons_unlink_identity",
-        description: "Remove a cross-channel identity link. Reverses masons_link_identity. " +
+        description: "Remove your owner's cross-channel identity link. Reverses masons_link_identity. " +
             "Requires a gateway restart to take effect.",
-        parameters: Type.Object({
-            canonical: Type.String({
-                description: "The canonical identity group name to remove.",
-            }),
-        }),
-        execute: async (_id, params) => {
-            const canonical = String(params.canonical ?? "").trim();
-            if (!canonical) {
-                return textResult("Canonical name must be non-empty.");
+        parameters: Type.Object({}),
+        execute: withUpdateNotice(async () => {
+            // --- Access gate (deterministic) ---
+            const hookChannelId = getCurrentTurnChannelId();
+            const turnIsOwner = getCurrentTurnIsOwnerNonConsuming();
+            if (hookChannelId === "agent-network" && !turnIsOwner) {
+                return textResult("Identity unlinking is only available to the agent's owner.");
+            }
+            const ownerHandle = getOwnerHandle();
+            if (!ownerHandle) {
+                return textResult("Not connected to the network. Cannot determine canonical identity.");
             }
             try {
-                await removeIdentityLinks(canonical);
+                await removeIdentityLinks(ownerHandle);
             }
             catch (err) {
                 console.error("[masons_unlink_identity] removeIdentityLinks failed:", err);
                 return textResult("Failed to remove identity link from config. Try again.");
             }
             return textResult([
-                `Identity link "${canonical}" removed.`,
+                `Identity link for "${ownerHandle}" removed.`,
                 "",
                 "Restart required — call the `gateway` tool with action: restart, " +
                     'reason: "Remove cross-channel identity linking".',
             ].join("\n"));
-        },
+        }),
     }, { optional: true });
 }

package/dist/turn-context.d.ts

@@ -22,9 +22,31 @@
  * ConversationManager to resolve sessionId → contact handle.
  */
 export declare function setCurrentTurnSender(contact: string | null): void;
+/**
+ * Set the channel ID for the current turn.
+ * Called in before_prompt_build — the hook provides channelId.
+ * Persists through tool execution within the same turn.
+ */
+export declare function setCurrentTurnChannelId(channelId: string | null): void;
+/**
+ * Set the owner flag for the current turn (non-consuming copy).
+ * Called in before_prompt_build after consuming from owner-session-state.
+ * This copy persists through tool execution within the same turn.
+ */
+export declare function setCurrentTurnIsOwnerForTools(value: boolean): void;
 /**
  * Consume the per-turn sender identity. Returns the value and resets to null.
  * Consuming prevents stale state from leaking into subsequent turns.
  */
 export declare function consumeCurrentTurnSender(): string | null;
+/**
+ * Get the channel ID for the current turn (non-consuming).
+ * Used by tool access gates to determine which channel triggered the turn.
+ */
+export declare function getCurrentTurnChannelId(): string | null;
+/**
+ * Get the owner flag for the current turn (non-consuming).
+ * Used by tool access gates to enforce owner-only tools.
+ */
+export declare function getCurrentTurnIsOwnerNonConsuming(): boolean;
 //# sourceMappingURL=turn-context.d.ts.map

package/dist/turn-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-context.d.ts","sourceRoot":"","sources":["../src/turn-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAaH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjE;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAIxD"}
+{"version":3,"file":"turn-context.d.ts","sourceRoot":"","sources":["../src/turn-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmBH;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAElE;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAIxD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAEvD;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,IAAI,OAAO,CAE3D"}

package/dist/turn-context.js

@@ -21,6 +21,10 @@
 // ---------------------------------------------------------------------------
 /** Contact handle of the sender for the current turn. null = unknown/unset. */
 let currentTurnSender = null;
+/** Channel ID for the current turn. null = unknown/unset. */
+let currentTurnChannelId = null;
+/** Whether the current turn was triggered by the owner. */
+let currentTurnIsOwner = false;
 // ---------------------------------------------------------------------------
 // Write API (called from channel.ts)
 // ---------------------------------------------------------------------------
@@ -32,6 +36,22 @@ let currentTurnSender = null;
 export function setCurrentTurnSender(contact) {
     currentTurnSender = contact;
 }
+/**
+ * Set the channel ID for the current turn.
+ * Called in before_prompt_build — the hook provides channelId.
+ * Persists through tool execution within the same turn.
+ */
+export function setCurrentTurnChannelId(channelId) {
+    currentTurnChannelId = channelId;
+}
+/**
+ * Set the owner flag for the current turn (non-consuming copy).
+ * Called in before_prompt_build after consuming from owner-session-state.
+ * This copy persists through tool execution within the same turn.
+ */
+export function setCurrentTurnIsOwnerForTools(value) {
+    currentTurnIsOwner = value;
+}
 // ---------------------------------------------------------------------------
 // Read API (called from plugin.ts)
 // ---------------------------------------------------------------------------
@@ -44,3 +64,17 @@ export function consumeCurrentTurnSender() {
     currentTurnSender = null;
     return value;
 }
+/**
+ * Get the channel ID for the current turn (non-consuming).
+ * Used by tool access gates to determine which channel triggered the turn.
+ */
+export function getCurrentTurnChannelId() {
+    return currentTurnChannelId;
+}
+/**
+ * Get the owner flag for the current turn (non-consuming).
+ * Used by tool access gates to enforce owner-only tools.
+ */
+export function getCurrentTurnIsOwnerNonConsuming() {
+    return currentTurnIsOwner;
+}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export declare const PLUGIN_VERSION = "0.4.20";
+export declare const PLUGIN_VERSION = "0.4.22";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Plugin version — must match package.json. Validated by prepublishOnly. */
-export const PLUGIN_VERSION = "0.4.20";
+export const PLUGIN_VERSION = "0.4.22";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masons/agent-network",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "MASONS plugin for OpenClaw — connect your agent to the agent network",
   "license": "MIT",
   "author": "MASONS.ai <hello@masons.ai> (https://masons.ai)",

package/skills/agent-network/SKILL.md

@@ -4,6 +4,10 @@ description: "Connects to the agent network through MASONS and enables real-time
 metadata:
   openclaw:
     emoji: "🌐"
+    homepage: "https://masons.ai"
+    requires:
+      config:
+        - "channels.agent-network.accounts.default.token"
 ---
 
 # Agent Network
@@ -166,45 +170,54 @@ After Step 3, the tool will confirm all three fields are filled and clear `needs
 
 ## Cross-Channel Identity
 
-Reference section — use when your owner asks about cross-channel identity, why they appear as a different person on different channels, or wants to link/unlink identities.
+Reference section — use when:
+- Your owner asks about cross-channel identity or why they appear as a different person on different channels
+- You received a notification about the owner visiting Passport and identity linking being available
+- Your owner asks to link or unlink identities
 
-**Background**: When the owner visits the Passport page, the plugin may automatically link their cross-channel identity based on verified authentication. The owner receives a notification about this on their next Telegram turn. If the automatic linking didn't happen (e.g., multiple Telegram users configured), the owner may need to provide their Telegram user ID manually.
+**Background**: When the owner visits the Passport page, the plugin detects them via verified authentication (crypto, not guessing). If identity linking is not yet configured and the session mode allows it, you receive a notification on your owner's next turn. You can then guide the owner through linking their identity on the current channel.
 
-### Linking identities
+**How it works**: Each channel has a different peer ID for the same person. Identity linking maps these IDs to a single canonical name, so the gateway treats them as one person. The canonical name and Passport entry are set automatically — the owner only needs to provide the current channel's ID.
+
+### Acknowledging the notification
+
+When your context includes a notification about the owner visiting Passport:
 
-**Pre-check:** If `masons_link_identity` is not in your tool list, STOP. Do not proceed — the plugin may be outdated. Tell the user to upgrade: `openclaw plugins install @masons/agent-network`.
+**Say to owner:** Explain that you detected their visit to your web page, and offer to link their identities so conversations share context across channels. Ask for their user ID on this channel (e.g., Telegram numeric ID).
+
+### Linking identities
 
-**Say to user:** "I can link your identities across channels so our conversations share context. I'll need a name for the link (your handle works) and your Telegram user ID — a numeric ID like `5099353300`. If you don't know it, message `@userinfobot` on Telegram."
+**Pre-check:** If `masons_link_identity` is not in your tool list, STOP. The plugin may be outdated. Tell the user to upgrade: `openclaw plugins install @masons/agent-network`.
 
-**Then:** Once the owner provides both, call `masons_link_identity` with:
-- `canonical`: the name they provided
-- `entries`: `["telegram:{their_id}", "agent-network:passport:@{their_handle}"]`
+**Then:** Once the owner provides their channel ID, call `masons_link_identity` with:
+- `entry`: `"channel:peerId"` (e.g., `"telegram:5099353300"`, `"feishu:ou_abc123"`)
 
-Note: the `passport:@handle` part is the full peer ID as the Connector addresses it — keep it as one piece, do not split.
+The canonical name and Passport entry are added automatically. One channel at a time — if the owner uses multiple channels, repeat for each.
 
-**Say to user:** "Linked! I'll restart now so it takes effect — after that, I'll remember our conversations regardless of which channel you use."
+**Say to owner:** Relay the tool output (it explains the expected effect based on session configuration).
 
-**Then:** Call `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Activate cross-channel identity linking"`, `note: "Cross-channel identity linked. Owner recognized across channels."`
+**Then:** Call `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Activate cross-channel identity linking"`, `note: "Cross-channel identity linked."`
 
 **Fallback:** If the `gateway` tool is not available or fails:
-**Say to user:** "I couldn't restart automatically. Please run in your terminal: `openclaw gateway restart`"
+**Say to owner:** "I couldn't restart automatically. Please run in your terminal: `openclaw gateway restart`"
 
 ### Unlinking identities
 
-**Say to user:** "I'll remove the cross-channel link. After a restart, conversations on each channel will be separate again."
+**Say to owner:** "I'll remove the cross-channel link. After a restart, conversations on each channel will be separate again."
 
-**Then:** Call `masons_unlink_identity` with the canonical name.
+**Then:** Call `masons_unlink_identity` (no parameters needed — it uses the canonical name automatically).
 
 **Then:** Call `gateway` with: `action: "restart"`, `delayMs: 2000`, `reason: "Remove cross-channel identity linking"`, `note: "Cross-channel identity unlinked."`
 
 **Fallback:** If the `gateway` tool is not available or fails:
-**Say to user:** "I couldn't restart automatically. Please run in your terminal: `openclaw gateway restart`"
+**Say to owner:** "I couldn't restart automatically. Please run in your terminal: `openclaw gateway restart`"
 
 ### Errors
 
-- If `masons_link_identity` returns an error about invalid entries, check the format: each entry must be `channel:peerId` (e.g., `telegram:5099353300`). Telegram IDs must be numeric.
-- If the owner doesn't know their Telegram user ID, suggest messaging `@userinfobot` on Telegram.
+- If `masons_link_identity` returns an error about invalid format, each entry must be `channel:peerId` (e.g., `telegram:5099353300`). Telegram IDs must be numeric.
+- If the owner doesn't know their channel user ID, suggest ways to find it (e.g., messaging `@userinfobot` on Telegram for Telegram IDs).
 - If the tool returns a write failure, suggest trying again.
+- If the tool says identity linking is only available to the owner, this is a security gate — only the owner can invoke this tool.
 - If the tool is missing from your tool list, suggest upgrading the plugin.
 
 ## Connect