From 9491ec9bdbba6e519d8d17bbc2c6e2919b334eee Mon Sep 17 00:00:00 2001
From: Keith the Silly Goose <keith@42bolton.macnet.nz>
Date: Wed, 28 Jan 2026 22:28:21 +1300
Subject: [PATCH] fix: make session-level mentions strict (ignore activation
 bypass)

- Session override 'mentions' now requires actual @mention
- Does not bypass via groupActivated state
- Added test case for strict behavior
- Updated docs to clarify distinction from global config
---
 docs/channels/whatsapp.md          |  4 +++-
 src/channels/ack-reactions.test.ts | 14 ++++++++++++++
 src/channels/ack-reactions.ts      |  3 ++-
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/channels/whatsapp.md b/docs/channels/whatsapp.md
index f55a903d5..92a35ff92 100644
--- a/docs/channels/whatsapp.md
+++ b/docs/channels/whatsapp.md
@@ -244,10 +244,12 @@ The global and per-account configurations can be overridden for specific session
 - `ackReaction`: `"always" | "mentions" | "never"`
   - `"always"`: Enables reactions (overrides global off/never).
   - `"never"`: Disables reactions (overrides global on/always/mentions).
-  - `"mentions"`: Enforces mention-only reactions.
+  - `"mentions"`: Enforces **strict** mention-only reactions (requires actual @mention, ignores group activation state).
   - Useful for disabling reactions in specific DMs (`"never"`) or forcing them in specific groups.
 
 > **Note:** Setting `"mentions"` on a DM session effectively disables reactions for that DM, since direct messages don't have @mentions. Use `"always"` or `"never"` for DMs.
+>
+> **Note:** Unlike the global `group: "mentions"` setting which respects group activation state, the session-level `"mentions"` override is strict and always requires an actual @mention.
 
 **Per-account override:**
 ```json
diff --git a/src/channels/ack-reactions.test.ts b/src/channels/ack-reactions.test.ts
index 7b6422571..b0cb70acb 100644
--- a/src/channels/ack-reactions.test.ts
+++ b/src/channels/ack-reactions.test.ts
@@ -281,6 +281,20 @@ describe("shouldAckReactionForWhatsApp", () => {
         sessionMode: "mentions", // Session override ON (if mentioned)
       }),
     ).toBe(true);
+
+    // Session: MENTIONS is strict - does NOT bypass via groupActivated
+    expect(
+      shouldAckReactionForWhatsApp({
+        emoji: "👀",
+        isDirect: false,
+        isGroup: true,
+        directEnabled: true,
+        groupMode: "always",
+        wasMentioned: false, // Not mentioned
+        groupActivated: true, // But group is activated
+        sessionMode: "mentions", // Explicit mentions = strict, no bypass
+      }),
+    ).toBe(false);
   });
 });
 
diff --git a/src/channels/ack-reactions.ts b/src/channels/ack-reactions.ts
index c6b9c6d48..00734c5e4 100644
--- a/src/channels/ack-reactions.ts
+++ b/src/channels/ack-reactions.ts
@@ -44,6 +44,7 @@ export function shouldAckReactionForWhatsApp(params: {
   if (params.sessionMode === "never") return false;
   if (params.sessionMode === "always") return true;
   if (params.sessionMode === "mentions") {
+    // Strict mention-only: explicit session override should not bypass via activation
     return shouldAckReaction({
       scope: "group-mentions",
       isDirect: params.isDirect,
@@ -52,7 +53,7 @@ export function shouldAckReactionForWhatsApp(params: {
       requireMention: true,
       canDetectMention: true,
       effectiveWasMentioned: params.wasMentioned,
-      shouldBypassMention: params.groupActivated,
+      // Note: intentionally not passing shouldBypassMention here
     });
   }