docs: note self-chat config docs update

- Add new section explaining self-chat mode for group control
- Document routing.allowFrom as the key setting for controlling metadata mentions
- Clarify difference between whatsapp.allowFrom (DM allowlist) and routing.allowFrom (self-chat mode)
- Explain metadata mentions vs text patterns in routing.groupChat
- Add example config for responding only to specific text triggers

When routing.allowFrom contains the bot's own number, WhatsApp native
@-mentions are ignored in groups, and only mentionPatterns trigger responses.
This prevents unwanted responses when users tap-to-mention the bot owner.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -7,7 +7,6 @@
 - Agent runtime: update pi-mono dependencies to 0.31.1 (agent-core split).
 - Dependencies: bump to latest compatible versions (TypeBox, grammY, Zod, Rolldown, oxlint-tsgolint).
 - Tests: cover read tool image metadata + text output.
-- Hooks: treat null transforms as handled skips (204) and let explicit mappings override presets (#117) — thanks @jverdi.
 
 ### Breaking
 - Skills config schema moved under `skills.*`:
@@ -54,7 +53,6 @@
 - Skills: add tmux-first coding-agent skill + `requires.anyBins` gate for multi-CLI setup (thanks @sreekaransrinath).
 
 ### Fixes
-- Gog calendar: format date ranges as RFC 3339 with timezone to satisfy Google Calendar API (thanks @jayhickey).
 - Chat UI: keep the chat scrolled to the latest message after switching sessions.
 - Auto-reply: stream completed reply blocks as soon as they finish (configurable default + break); skip empty tool-only blocks unless verbose.
 - Providers: make outbound text chunk limits configurable via `*.textChunkLimit` (defaults remain 4000/Discord 2000).
@@ -109,6 +107,7 @@
 - Cron: prevent `every` schedules without an anchor from firing in a tight loop (thanks @jamesgroat).
 - Docs: add manual OAuth setup for remote/headless deployments (#67) — thanks @wstock
 - Docs/agent tools: clarify that browser `wait` should be avoided by default and used only in exceptional cases.
+- Docs: clarify self-chat mode and group mention gating config (#111) — thanks @rafaelreis-r.
 - Browser tools: `upload` supports auto-click refs, direct `inputRef`/`element` file inputs, and emits input/change after `setFiles` so JS-heavy sites pick up attachments.
 - Browser tools: harden CDP readiness (HTTP + WS), retry CDP connects, and auto-restart the clawd browser when the socket handshake stalls.
 - Browser CLI: add `clawdis browser reset-profile` to move the clawd profile to Trash when it gets wedged.

docs/configuration.md

@@ -10,11 +10,11 @@ CLAWDIS reads an optional **JSON5** config from `~/.clawdis/clawdis.json` (comme
 
 If the file is missing, CLAWDIS uses safe-ish defaults (embedded Pi agent + per-sender sessions + workspace `~/clawd`). You usually only need a config to:
 - restrict who can trigger the bot (`whatsapp.allowFrom`, `telegram.allowFrom`, etc.)
-- tune group mention behavior (`whatsapp.groups`, `telegram.groups`, `imessage.groups`, `discord.guilds`)
+- control group mention behavior (`whatsapp.groups`, `telegram.groups`, `discord.guilds`, `routing.groupChat`)
 - customize message prefixes (`messages`)
-- set the agent’s workspace (`agent.workspace`)
+- set the agent's workspace (`agent.workspace`)
 - tune the embedded agent (`agent`) and session behavior (`session`)
-- set the agent’s identity (`identity`)
+- set the agent's identity (`identity`)
 
 ## Minimal config (recommended starting point)
 
@@ -25,6 +25,26 @@ If the file is missing, CLAWDIS uses safe-ish defaults (embedded Pi agent + per-
 }
 ```
 
+## Self-chat mode (recommended for group control)
+
+To prevent the bot from responding to WhatsApp @-mentions in groups (only respond to specific text triggers):
+
+```json5
+{
+  agent: { workspace: "~/clawd" },
+  whatsapp: {
+    // Allowlist is DMs only; including your own number enables self-chat mode.
+    allowFrom: ["+15555550123"],
+    groups: { "*": { requireMention: true } }
+  },
+  routing: {
+    groupChat: {
+      mentionPatterns: ["@clawd", "reisponde"]
+    }
+  }
+}
+```
+
 ## Common options
 
 ### `identity`
@@ -78,7 +98,8 @@ Metadata written by CLI wizards (`onboard`, `configure`, `doctor`, `update`).
 
 ### `whatsapp.allowFrom`
 
-Allowlist of E.164 phone numbers that may trigger WhatsApp auto-replies.
+Allowlist of E.164 phone numbers that may trigger WhatsApp auto-replies (DMs only).
+If empty, the default allowlist is your own WhatsApp number (self-chat mode).
 
 ```json5
 {
@@ -89,24 +110,13 @@ Allowlist of E.164 phone numbers that may trigger WhatsApp auto-replies.
 }
 ```
 
-### `whatsapp.groups`
-
-Per-group mention gating for WhatsApp groups. Default group config lives at `whatsapp.groups."*"`.
-
-```json5
-{
-  whatsapp: {
-    groups: {
-      "*": { requireMention: true },
-      "123@g.us": { requireMention: false } // group JID
-    }
-  }
-}
-```
-
 ### `routing.groupChat`
 
-Group mention patterns + history handling shared across surfaces (WhatsApp/iMessage/Telegram/Discord).
+Group messages default to **require mention** (either metadata mention or regex patterns). Applies to WhatsApp, Telegram, Discord, and iMessage group chats.
+
+**Mention types:**
+- **Metadata mentions**: Native platform @-mentions (e.g., WhatsApp tap-to-mention). Ignored in WhatsApp self-chat mode (see `whatsapp.allowFrom`).
+- **Text patterns**: Regex patterns defined in `mentionPatterns`. Always checked regardless of self-chat mode.
 
 ```json5
 {
@@ -118,8 +128,26 @@ Group mention patterns + history handling shared across surfaces (WhatsApp/iMess
   }
 }
 ```
+
 Mention gating defaults live per provider (`whatsapp.groups`, `telegram.groups`, `imessage.groups`, `discord.guilds`).
 
+To respond **only** to specific text triggers (ignoring native @-mentions):
+```json5
+{
+  whatsapp: {
+    // Include your own number to enable self-chat mode (ignore native @-mentions).
+    allowFrom: ["+15555550123"],
+    groups: { "*": { requireMention: true } }
+  },
+  routing: {
+    groupChat: {
+      // Only these text patterns will trigger responses
+      mentionPatterns: ["reisponde", "@clawd"]
+    }
+  }
+}
+```
+
 ### `routing.queue`
 
 Controls how inbound messages behave when an agent run is already active.
@@ -172,12 +200,7 @@ Set `telegram.enabled: false` to disable automatic startup.
   telegram: {
     enabled: true,
     botToken: "your-bot-token",
-    textChunkLimit: 4000,                  // optional outbound chunk size (chars)
-    replyToMode: "off",
-    groups: {
-      "*": { requireMention: true },
-      "123456789": { requireMention: false } // group chat id
-    },
+    requireMention: true,
     allowFrom: ["123456789"],
     mediaMaxMb: 5,
     proxy: "socks5://localhost:9050",
@@ -187,8 +210,6 @@ Set `telegram.enabled: false` to disable automatic startup.
   }
 }
 ```
-Mention gating precedence (most specific wins): `telegram.groups.<chatId>.requireMention` → `telegram.groups."*".requireMention` → default `true`.
-Reply threading is controlled via `telegram.replyToMode` (`off` | `first` | `all`) and reply tags in the model output.
 
 ### `discord` (bot transport)
 
@@ -199,10 +220,8 @@ Configure the Discord bot by setting the bot token and optional gating:
   discord: {
     enabled: true,
     token: "your-bot-token",
-    textChunkLimit: 2000,                   // optional outbound chunk size (chars)
     mediaMaxMb: 8,                          // clamp inbound media size
     enableReactions: true,                  // allow agent-triggered reactions
-    replyToMode: "off",                     // off | first | all
     slashCommand: {                         // user-installed app slash commands
       enabled: true,
       name: "clawd",
@@ -216,7 +235,6 @@ Configure the Discord bot by setting the bot token and optional gating:
       groupChannels: ["clawd-dm"]          // optional group DM allowlist
     },
     guilds: {
-      "*": { requireMention: true },       // default per-guild mention gating
       "123456789012345678": {               // guild id (preferred) or slug
         slug: "friends-of-clawd",
         requireMention: false,              // per-guild default
@@ -233,23 +251,7 @@ Configure the Discord bot by setting the bot token and optional gating:
 ```
 
 Clawdis starts Discord only when a `discord` config section exists. The token is resolved from `DISCORD_BOT_TOKEN` or `discord.token` (unless `discord.enabled` is `false`). Use `user:<id>` (DM) or `channel:<id>` (guild channel) when specifying delivery targets for cron/CLI commands.
-Reply threading is controlled via `discord.replyToMode` (`off` | `first` | `all`) and reply tags in the model output.
 Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged channel name (no leading `#`). Prefer guild ids as keys to avoid rename ambiguity.
-Use `discord.guilds."*"` for default per-guild settings.
-
-### `signal` (signal-cli JSON-RPC)
-
-Clawdis can send/receive Signal via `signal-cli` (daemon or existing HTTP URL).
-
-```json5
-{
-  signal: {
-    enabled: true,
-    textChunkLimit: 4000,                   // optional outbound chunk size (chars)
-    mediaMaxMb: 8
-  }
-}
-```
 
 ### `imessage` (imsg CLI)
 
@@ -261,12 +263,7 @@ Clawdis spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
     enabled: true,
     cliPath: "imsg",
     dbPath: "~/Library/Messages/chat.db",
-    textChunkLimit: 4000,                   // optional outbound chunk size (chars)
     allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
-    groups: {
-      "*": { requireMention: true },
-      "123": { requireMention: false } // chat_id for the group
-    },
     includeAttachments: false,
     mediaMaxMb: 16,
     service: "auto",
@@ -279,7 +276,6 @@ Notes:
 - Requires Full Disk Access to the Messages DB.
 - The first send will prompt for Messages automation permission.
 - Prefer `chat_id:<id>` targets. Use `imsg chats --limit 20` to list chats.
-- Group mention gating lives in `imessage.groups` (default at `imessage.groups."*"`).
 
 ### `agent.workspace`
 
@@ -296,7 +292,6 @@ Default: `~/clawd`.
 ### `messages`
 
 Controls inbound/outbound prefixes and timestamps.
-Outbound text chunking is configured per provider via `*.textChunkLimit` (e.g. `whatsapp.textChunkLimit`, `telegram.textChunkLimit`).
 
 ```json5
 {
@@ -351,8 +346,6 @@ Controls the embedded agent runtime (model/thinking/verbose/timeouts).
     },
     thinkingDefault: "low",
     verboseDefault: "off",
-    blockStreamingDefault: "on",
-    blockStreamingBreak: "text_end",
     timeoutSeconds: 600,
     mediaMaxMb: 5,
     heartbeat: {
@@ -377,14 +370,6 @@ deprecation fallback.
 Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 `ZAI_API_KEY` (or legacy `Z_AI_API_KEY`) in the environment.
 
-`agent.blockStreamingDefault` controls whether completed assistant blocks are
-sent immediately (default: `on`). Set to `off` to only deliver the final
-consolidated reply.
-
-`agent.blockStreamingBreak` controls what “block” means:
-- `text_end` (default): end of each assistant text content block (before tool calls)
-- `message_end`: end of the whole assistant message (may wait across tools)
-
 `agent.heartbeat` configures periodic heartbeat runs:
 - `every`: duration string (`ms`, `s`, `m`, `h`); default unit minutes. Omit or set
   `0m` to disable.
@@ -701,7 +686,6 @@ Endpoints:
 Mapping notes:
 - `match.path` matches the sub-path after `/hooks` (e.g. `/hooks/gmail` → `gmail`).
 - `match.source` matches a payload field (e.g. `{ source: "gmail" }`) so you can use a generic `/hooks/ingest` path.
-- `hooks.mappings` are evaluated before presets; first match wins.
 - Templates like `{{messages[0].subject}}` read from the payload.
 - `transform` can point to a JS/TS module that returns a hook action.
 

docs/webhook.md

@@ -89,7 +89,6 @@ code transforms.
 Mapping options (summary):
 - `hooks.presets: ["gmail"]` enables the built-in Gmail mapping.
 - `hooks.mappings` lets you define `match`, `action`, and templates in config.
-- `hooks.mappings` are evaluated before presets; first match wins.
 - `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
 - Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
 - TS transforms require a TS loader (e.g. `tsx`) or precompiled `.js` at runtime.

src/gateway/hooks-mapping.test.ts

@@ -74,61 +74,6 @@ describe("hooks mapping", () => {
     }
   });
 
-  it("treats null transform as a handled skip", async () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "clawdis-hooks-skip-"));
-    const modPath = path.join(dir, "transform.mjs");
-    fs.writeFileSync(modPath, "export default () => null;");
-
-    const mappings = resolveHookMappings({
-      transformsDir: dir,
-      mappings: [
-        {
-          match: { path: "skip" },
-          action: "agent",
-          transform: { module: "transform.mjs" },
-        },
-      ],
-    });
-
-    const result = await applyHookMappings(mappings, {
-      payload: {},
-      headers: {},
-      url: new URL("http://127.0.0.1:18789/hooks/skip"),
-      path: "skip",
-    });
-
-    expect(result?.ok).toBe(true);
-    if (result?.ok) {
-      expect(result.action).toBeNull();
-      expect("skipped" in result).toBe(true);
-    }
-  });
-
-  it("prefers explicit mappings over presets", async () => {
-    const mappings = resolveHookMappings({
-      presets: ["gmail"],
-      mappings: [
-        {
-          id: "override",
-          match: { path: "gmail" },
-          action: "agent",
-          messageTemplate: "Override subject: {{messages[0].subject}}",
-        },
-      ],
-    });
-    const result = await applyHookMappings(mappings, {
-      payload: { messages: [{ subject: "Hello" }] },
-      headers: {},
-      url: baseUrl,
-      path: "gmail",
-    });
-    expect(result?.ok).toBe(true);
-    if (result?.ok) {
-      expect(result.action.kind).toBe("agent");
-      expect(result.action.message).toBe("Override subject: Hello");
-    }
-  });
-
   it("rejects missing message", async () => {
     const mappings = resolveHookMappings({
       mappings: [{ match: { path: "noop" }, action: "agent" }],

src/gateway/hooks-mapping.ts

@@ -70,7 +70,6 @@ export type HookAction =
 
 export type HookMappingResult =
   | { ok: true; action: HookAction }
-  | { ok: true; action: null; skipped: true }
   | { ok: false; error: string };
 
 const hookPresetMappings: Record<string, HookMappingConfig[]> = {
@@ -114,11 +113,11 @@ export function resolveHookMappings(
 ): HookMappingResolved[] {
   const presets = hooks?.presets ?? [];
   const mappings: HookMappingConfig[] = [];
-  if (hooks?.mappings) mappings.push(...hooks.mappings);
   for (const preset of presets) {
     const presetMappings = hookPresetMappings[preset];
     if (presetMappings) mappings.push(...presetMappings);
   }
+  if (hooks?.mappings) mappings.push(...hooks.mappings);
   if (mappings.length === 0) return [];
 
   const configDir = path.dirname(CONFIG_PATH_CLAWDIS);
@@ -146,9 +145,7 @@ export async function applyHookMappings(
     if (mapping.transform) {
       const transform = await loadTransform(mapping.transform);
       override = await transform(ctx);
-      if (override === null) {
-        return { ok: true, action: null, skipped: true };
-      }
+      if (override === null) return null;
     }
 
     const merged = mergeAction(base.action, override, mapping.action);

src/gateway/server.ts

@@ -1706,11 +1706,6 @@ export async function startGatewayServer(
             sendJson(res, 400, { ok: false, error: mapped.error });
             return true;
           }
-          if (mapped.action === null) {
-            res.statusCode = 204;
-            res.end();
-            return true;
-          }
           if (mapped.action.kind === "wake") {
             dispatchWakeHook({
               text: mapped.action.text,