feat(session): add dmScope for multi-user DM isolation

Co-authored-by: Alphonse-arianee <Alphonse-arianee@users.noreply.github.com>

docs/cli/security.md

@@ -20,3 +20,4 @@ clawdbot security audit --deep
 clawdbot security audit --fix
 ```
 
+The audit warns when multiple DM senders share the main session and recommends `session.dmScope="per-channel-peer"` for shared inboxes.

docs/concepts/session.md

@@ -7,6 +7,11 @@ read_when:
 
 Clawdbot treats **one direct-chat session per agent** as primary. Direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`), while group/channel chats get their own keys. `session.mainKey` is honored.
 
+Use `session.dmScope` to control how **direct messages** are grouped:
+- `main` (default): all DMs share the main session for continuity.
+- `per-peer`: isolate by sender id across channels.
+- `per-channel-peer`: isolate by channel + sender (recommended for multi-user inboxes).
+
 ## Gateway is the source of truth
 All session state is **owned by the gateway** (the “master” Clawdbot). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
 
@@ -32,8 +37,11 @@ the workspace is writable. See [Memory](/concepts/memory) and
 [Compaction](/concepts/compaction).
 
 ## Mapping transports → session keys
-- Direct chats collapse to the per-agent primary key: `agent:<agentId>:<mainKey>`.
-  - Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.
+- Direct chats follow `session.dmScope` (default `main`).
+  - `main`: `agent:<agentId>:<mainKey>` (continuity across devices/channels).
+    - Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.
+  - `per-peer`: `agent:<agentId>:dm:<peerId>`.
+  - `per-channel-peer`: `agent:<agentId>:<channel>:dm:<peerId>`.
 - Group chats isolate state: `agent:<agentId>:<channel>:group:<id>` (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).
   - Telegram forum topics append `:topic:<threadId>` to the group id for isolation.
   - Legacy `group:<id>` keys are still recognized for migration.
@@ -77,6 +85,7 @@ Send these as standalone messages so they register.
 {
   session: {
     scope: "per-sender",      // keep group keys separate
+    dmScope: "main",          // DM continuity (set per-channel-peer for shared inboxes)
     idleMinutes: 120,
     resetTriggers: ["/new", "/reset"],
     store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",

docs/gateway/configuration.md

@@ -2261,6 +2261,7 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 {
   session: {
     scope: "per-sender",
+    dmScope: "main",
     idleMinutes: 60,
     resetTriggers: ["/new", "/reset"],
     // Default is already per-agent under ~/.clawdbot/agents/<agentId>/sessions/sessions.json
@@ -2285,6 +2286,10 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 Fields:
 - `mainKey`: direct-chat bucket key (default: `"main"`). Useful when you want to “rename” the primary DM thread without changing `agentId`.
   - Sandbox note: `agents.defaults.sandbox.mode: "non-main"` uses this key to detect the main session. Any session key that does not match `mainKey` (groups/channels) is sandboxed.
+- `dmScope`: how DM sessions are grouped (default: `"main"`).
+  - `main`: all DMs share the main session for continuity.
+  - `per-peer`: isolate DMs by sender id across channels.
+  - `per-channel-peer`: isolate DMs per channel + sender (recommended for multi-user inboxes).
 - `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).
 - `sendPolicy.default`: `allow` or `deny` fallback when no rule matches.
 - `sendPolicy.rules[]`: match by `channel`, `chatType` (`direct|group|room`), or `keyPrefix` (e.g. `cron:`). First deny wins; otherwise allow.

docs/gateway/security.md

@@ -123,6 +123,18 @@ clawdbot pairing approve <channel> <code>
 
 Details + files on disk: [Pairing](/start/pairing)
 
+## DM session isolation (multi-user mode)
+
+By default, Clawdbot routes **all DMs into the main session** so your assistant has continuity across devices and channels. If **multiple people** can DM the bot (open DMs or a multi-person allowlist), consider isolating DM sessions:
+
+```json5
+{
+  session: { dmScope: "per-channel-peer" }
+}
+```
+
+This prevents cross-user context leakage while keeping group chats isolated. See [Session Management](/concepts/session) and [Configuration](/gateway/configuration).
+
 ## Allowlists (DM + groups) — terminology
 
 Clawdbot has two separate “who can trigger me?” layers: