fix: polish tts auto mode + tests (#1667) (thanks @sebslight)

## Problem

The clawdbot-gateway systemd service was crash-looping on Linux (Fedora 42,
aarch64) with the error:

    error: unknown command '/usr/bin/node-22'

After ~20 seconds of runtime, the gateway would exit with status 1/FAILURE
and systemd would restart it, repeating the cycle indefinitely (80+ restarts
observed).

## Root Cause Analysis

### Investigation Steps

1. Examined systemd service logs via `journalctl --user -u clawdbot-gateway.service`
2. Found the error appeared consistently after the service had been running
   for 20-30 seconds
3. Added debug logging to trace argv at parseAsync() call
4. Discovered that argv was being passed to Commander.js with the node binary
   and script paths still present: `["/usr/bin/node-22", "/path/to/entry.js", "gateway", "--port", "18789"]`
5. Traced the issue to the lazy subcommand registration logic in runCli()

### The Bug

The lazy-loading logic for subcommands was gated behind `hasHelpOrVersion(parseArgv)`:

```typescript
if (hasHelpOrVersion(parseArgv)) {
  const primary = getPrimaryCommand(parseArgv);
  if (primary) {
    const { registerSubCliByName } = await import("./program/register.subclis.js");
    await registerSubCliByName(program, primary);
  }
}
```

This meant that when running `clawdbot gateway --port 18789` (without --help
or --version), the `gateway` subcommand was never registered before
`program.parseAsync(parseArgv)` was called. Commander.js would then try to
parse the arguments without knowing about the gateway command, leading to
parse errors.

The error message "unknown command '/usr/bin/node-22'" appeared because
Commander was treating the first positional argument as a command name due to
argv not being properly stripped on non-Windows platforms in some code paths.

## The Fix

Remove the `hasHelpOrVersion()` gate and always register the primary
subcommand when one is detected:

```typescript
// Register the primary subcommand if one exists (for lazy-loading)
const primary = getPrimaryCommand(parseArgv);
if (primary) {
  const { registerSubCliByName } = await import("./program/register.subclis.js");
  await registerSubCliByName(program, primary);
}
```

This ensures that subcommands like `gateway` are properly registered before
parsing begins, regardless of what flags are present.

## Environment

- OS: Fedora 42 (Linux 6.15.9-201.fc42.aarch64)
- Arch: aarch64
- Node: /usr/bin/node-22 (symlink to node-22)
- Deployment: systemd user service
- Runtime: Gateway started via `clawdbot gateway --port 18789`

## Why This Should Be Merged

1. **Critical Bug**: The gateway service cannot run reliably on Linux without
   this fix, making it a blocking issue for production deployments via systemd.

2. **Affects All Non-Help Invocations**: Any direct subcommand invocation
   (gateway, channels, etc.) without --help/--version is broken.

3. **Simple & Safe Fix**: The change removes an unnecessary condition that was
   preventing lazy-loading from working correctly. Subcommands should always be
   registered when detected, not just for help/version requests.

4. **No Regression Risk**: The fix maintains the lazy-loading behavior (only
   loads the requested subcommand), just ensures it works in all cases instead
   of only help/version scenarios.

5. **Tested**: Verified that the gateway service now runs stably for extended
   periods (45+ seconds continuous runtime with no crashes) after applying this
   fix.

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -10,6 +10,7 @@ Docs: https://docs.clawd.bot
 
 ### Changes
 - TTS: add Edge TTS provider fallback, defaulting to keyless Edge with MP3 retry on format failures. (#1668) Thanks @steipete. https://docs.clawd.bot/tts
+- TTS: add auto mode enum (off/always/inbound/tagged) with per-session `/tts` override. (#1667) Thanks @sebslight. https://docs.clawd.bot/tts
 - Docs: expand FAQ (migration, scheduling, concurrency, model recommendations, OpenAI subscription auth, Pi sizing, hackable install, docs SSL workaround).
 - Docs: add verbose installer troubleshooting guidance.
 - Docs: update Fly.io guide notes.
@@ -21,15 +22,15 @@ Docs: https://docs.clawd.bot
 - BlueBubbles: keep part-index GUIDs in reply tags when short IDs are missing.
 - Web UI: hide internal `message_id` hints in chat bubbles.
 - Web UI: show Stop button during active runs, swap back to New session when idle. (#1664) Thanks @ndbroadbent.
-- Web UI: keep raw config edits from toggling channel save state; enable save/apply on raw changes only. (#1673) Thanks @Glucksberg.
 - Heartbeat: normalize target identifiers for consistent routing.
 - TUI: reload history after gateway reconnect to restore session state. (#1663)
 - Telegram: use wrapped fetch for long-polling on Node to normalize AbortSignal handling. (#1639)
+- Signal: repair reaction sends (group/UUID targets + CLI author flags). (#1651) Thanks @vilkasdev.
 - Exec: keep approvals for elevated ask unless full mode. (#1616) Thanks @ivancasco.
 - Agents: auto-compact on context overflow prompt errors before failing. (#1627) Thanks @rodrigouroz.
 - Agents: use the active auth profile for auto-compaction recovery.
 - Models: default missing custom provider fields so minimal configs are accepted.
-- Gateway: honor trusted proxy client IPs for local pairing + HTTP checks. (#1654) Thanks @ndbroadbent.
+- Gateway: skip Tailscale DNS probing when tailscale.mode is off. (#1671)
 - Gateway: reduce log noise for late invokes + remote node probes; debounce skills refresh. (#1607) Thanks @petter-b.
 - macOS: default direct-transport `ws://` URLs to port 18789; document `gateway.remote.transport`. (#1603) Thanks @ngutman.
 - Voice Call: return stream TwiML for outbound conversation calls on initial Twilio webhook. (#1634)

docs/channels/signal.md

@@ -105,8 +105,29 @@ Groups:
 - **Read receipts**: when `channels.signal.sendReadReceipts` is true, Clawdbot forwards read receipts for allowed DMs.
 - Signal-cli does not expose read receipts for groups.
 
+## Reactions (message tool)
+- Use `message action=react` with `channel=signal`.
+- Targets: sender E.164 or UUID (use `uuid:<id>` from pairing output; bare UUID works too).
+- `messageId` is the Signal timestamp for the message you’re reacting to.
+- Group reactions require `targetAuthor` or `targetAuthorUuid`.
+
+Examples:
+```
+message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥
+message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true
+message action=react channel=signal target=signal:group:<groupId> targetAuthor=uuid:<sender-uuid> messageId=1737630212345 emoji=✅
+```
+
+Config:
+- `channels.signal.actions.reactions`: enable/disable reaction actions (default true).
+- `channels.signal.reactionLevel`: `off | ack | minimal | extensive`.
+  - `off`/`ack` disables agent reactions (message tool `react` will error).
+  - `minimal`/`extensive` enables agent reactions and sets the guidance level.
+- Per-account overrides: `channels.signal.accounts.<id>.actions.reactions`, `channels.signal.accounts.<id>.reactionLevel`.
+
 ## Delivery targets (CLI/cron)
 - DMs: `signal:+15551234567` (or plain E.164).
+- UUID DMs: `uuid:<id>` (or bare UUID).
 - Groups: `signal:group:<groupId>`.
 - Usernames: `username:<name>` (if supported by your Signal account).
 

docs/cli/message.md

@@ -66,11 +66,12 @@ Name lookup:
   - Discord only: `--poll-duration-hours`, `--message`
 
 - `react`
-  - Channels: Discord/Google Chat/Slack/Telegram/WhatsApp
+  - Channels: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal
   - Required: `--message-id`, `--target`
-  - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`
+  - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
   - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
   - WhatsApp only: `--participant`, `--from-me`
+  - Signal group reactions: `--target-author` or `--target-author-uuid` required
 
 - `reactions`
   - Channels: Discord/Google Chat/Slack
@@ -213,6 +214,13 @@ clawdbot message react --channel slack \
   --target C123 --message-id 456 --emoji "✅"
 ```
 
+React in a Signal group:
+```
+clawdbot message react --channel signal \
+  --target signal:group:abc123 --message-id 1737630212345 \
+  --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
+```
+
 Send Telegram inline buttons:
 ```
 clawdbot message send --channel telegram --target @mychat --message "Choose:" \

docs/gateway/configuration.md

@@ -1502,7 +1502,7 @@ voice notes; other channels send MP3 audio.
 {
   messages: {
     tts: {
-      enabled: true,
+      auto: "always", // off | always | inbound | tagged
       mode: "final", // final | all (include tool/block replies)
       provider: "elevenlabs",
       summaryModel: "openai/gpt-4.1-mini",
@@ -1539,8 +1539,10 @@ voice notes; other channels send MP3 audio.
 ```
 
 Notes:
-- `messages.tts.enabled` can be overridden by local user prefs (see `/tts on`, `/tts off`).
-- `prefsPath` stores local overrides (enabled/provider/limit/summarize).
+- `messages.tts.auto` controls auto‑TTS (`off`, `always`, `inbound`, `tagged`).
+- `/tts off|always|inbound|tagged` sets the per‑session auto mode (overrides config).
+- `messages.tts.enabled` is legacy; doctor migrates it to `messages.tts.auto`.
+- `prefsPath` stores local overrides (provider/limit/summarize).
 - `maxTextLength` is a hard cap for TTS input; summaries are truncated to fit.
 - `summaryModel` overrides `agents.defaults.model.primary` for auto-summary.
   - Accepts `provider/model` or an alias from `agents.defaults.models`.

docs/help/faq.md

@@ -66,6 +66,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
   - [How does memory work?](#how-does-memory-work)
   - [Does semantic memory search require an OpenAI API key?](#does-semantic-memory-search-require-an-openai-api-key)
 - [Where things live on disk](#where-things-live-on-disk)
+  - [Is all data used with Clawdbot saved locally?](#is-all-data-used-with-clawdbot-saved-locally)
   - [Where does Clawdbot store its data?](#where-does-clawdbot-store-its-data)
   - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd--soulmd--usermd--memorymd-live)
   - [What’s the recommended backup strategy?](#whats-the-recommended-backup-strategy)
@@ -918,6 +919,20 @@ models — see [Memory](/concepts/memory) for the setup details.
 
 ## Where things live on disk
 
+### Is all data used with Clawdbot saved locally?
+
+No — **Clawdbot’s state is local**, but **external services still see what you send them**.
+
+- **Local by default:** sessions, memory files, config, and workspace live on the Gateway host
+  (`~/.clawdbot` + your workspace directory).
+- **Remote by necessity:** messages you send to model providers (Anthropic/OpenAI/etc.) go to
+  their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their
+  servers.
+- **You control the footprint:** using local models keeps prompts on your machine, but channel
+  traffic still goes through the channel’s servers.
+
+Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory).
+
 ### Where does Clawdbot store its data?
 
 Everything lives under `$CLAWDBOT_STATE_DIR` (default: `~/.clawdbot`):

docs/platforms/windows.md

@@ -7,7 +7,8 @@ read_when:
 # Windows (WSL2)
 
 Clawdbot on Windows is recommended **via WSL2** (Ubuntu recommended). The
-CLI + Gateway run inside Linux, which keeps the runtime consistent. Native
+CLI + Gateway run inside Linux, which keeps the runtime consistent and makes
+tooling far more compatible (Node/Bun/pnpm, Linux binaries, skills). Native
 Windows installs are untested and more problematic.
 
 Native Windows companion apps are planned.

docs/start/getting-started.md

@@ -45,7 +45,7 @@ run on host, set an explicit per-agent override:
   See [Web tools](/tools/web).
 
 macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
-Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested and more problematic. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows).
+Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows).
 
 ## 1) Install the CLI (recommended)
 

docs/tools/slash-commands.md

@@ -68,7 +68,7 @@ Text + native (when enabled):
 - `/config show|get|set|unset` (persist config to disk, owner-only; requires `commands.config: true`)
 - `/debug show|set|unset|reset` (runtime overrides, owner-only; requires `commands.debug: true`)
 - `/usage off|tokens|full|cost` (per-response usage footer or local cost summary)
-- `/tts on|off|status|provider|limit|summary|audio` (control TTS; see [/tts](/tts))
+- `/tts off|always|inbound|tagged|status|provider|limit|summary|audio` (control TTS; see [/tts](/tts))
   - Discord: native command is `/voice` (Discord reserves `/tts`); text `/tts` still works.
 - `/stop`
 - `/restart`

docs/tts.md

@@ -53,8 +53,8 @@ so that provider must also be authenticated if you enable summaries.
 
 ## Is it enabled by default?
 
-No. TTS is **disabled** by default. Enable it in config or with `/tts on`,
-which writes a local preference override.
+No. Auto‑TTS is **off** by default. Enable it in config with
+`messages.tts.auto` or per session with `/tts always` (alias: `/tts on`).
 
 Edge TTS **is** enabled by default once TTS is on, and is used automatically
 when no OpenAI or ElevenLabs API keys are available.
@@ -70,7 +70,7 @@ Full schema is in [Gateway configuration](/gateway/configuration).
 {
   messages: {
     tts: {
-      enabled: true,
+      auto: "always",
       provider: "elevenlabs"
     }
   }
@@ -83,7 +83,7 @@ Full schema is in [Gateway configuration](/gateway/configuration).
 {
   messages: {
     tts: {
-      enabled: true,
+      auto: "always",
       provider: "openai",
       summaryModel: "openai/gpt-4.1-mini",
       modelOverrides: {
@@ -121,7 +121,7 @@ Full schema is in [Gateway configuration](/gateway/configuration).
 {
   messages: {
     tts: {
-      enabled: true,
+      auto: "always",
       provider: "edge",
       edge: {
         enabled: true,
@@ -156,7 +156,7 @@ Full schema is in [Gateway configuration](/gateway/configuration).
 {
   messages: {
     tts: {
-      enabled: true,
+      auto: "always",
       maxTextLength: 4000,
       timeoutMs: 30000,
       prefsPath: "~/.clawdbot/settings/tts.json"
@@ -165,13 +165,25 @@ Full schema is in [Gateway configuration](/gateway/configuration).
 }
 ```
 
+### Only reply with audio after an inbound voice note
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "inbound"
+    }
+  }
+}
+```
+
 ### Disable auto-summary for long replies
 
 ```json5
 {
   messages: {
     tts: {
-      enabled: true
+      auto: "always"
     }
   }
 }
@@ -185,7 +197,10 @@ Then run:
 
 ### Notes on fields
 
-- `enabled`: master toggle (default `false`; local prefs can override).
+- `auto`: auto‑TTS mode (`off`, `always`, `inbound`, `tagged`).
+  - `inbound` only sends audio after an inbound voice note.
+  - `tagged` only sends audio when the reply includes `[[tts]]` tags.
+- `enabled`: legacy toggle (doctor migrates this to `auto`).
 - `mode`: `"final"` (default) or `"all"` (includes tool/block replies).
 - `provider`: `"elevenlabs"`, `"openai"`, or `"edge"` (fallback is automatic).
 - If `provider` is **unset**, Clawdbot prefers `openai` (if key), then `elevenlabs` (if key),
@@ -195,7 +210,7 @@ Then run:
 - `modelOverrides`: allow the model to emit TTS directives (on by default).
 - `maxTextLength`: hard cap for TTS input (chars). `/tts audio` fails if exceeded.
 - `timeoutMs`: request timeout (ms).
-- `prefsPath`: override the local prefs JSON path.
+- `prefsPath`: override the local prefs JSON path (provider/limit/summary).
 - `apiKey` values fall back to env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `OPENAI_API_KEY`).
 - `elevenlabs.baseUrl`: override ElevenLabs API base URL.
 - `elevenlabs.voiceSettings`:
@@ -218,6 +233,7 @@ Then run:
 ## Model-driven overrides (default on)
 
 By default, the model **can** emit TTS directives for a single reply.
+When `messages.tts.auto` is `tagged`, these directives are required to trigger audio.
 
 When enabled, the model can emit `[[tts:...]]` directives to override the voice
 for a single reply, plus an optional `[[tts:text]]...[[/tts:text]]` block to
@@ -338,8 +354,10 @@ Discord note: `/tts` is a built-in Discord command, so Clawdbot registers
 `/voice` as the native command there. Text `/tts ...` still works.
 
 ```
-/tts on
 /tts off
+/tts always
+/tts inbound
+/tts tagged
 /tts status
 /tts provider openai
 /tts limit 2000
@@ -350,6 +368,7 @@ Discord note: `/tts` is a built-in Discord command, so Clawdbot registers
 Notes:
 - Commands require an authorized sender (allowlist/owner rules still apply).
 - `commands.text` or native command registration must be enabled.
+- `off|always|inbound|tagged` are per‑session toggles (`/tts on` is an alias for `/tts always`).
 - `limit` and `summary` are stored in local prefs, not the main config.
 - `/tts audio` generates a one-off audio reply (does not toggle TTS on).
 

extensions/signal/src/channel.ts

@@ -18,12 +18,20 @@ import {
   setAccountEnabledInConfigSection,
   signalOnboardingAdapter,
   SignalConfigSchema,
+  type ChannelMessageActionAdapter,
   type ChannelPlugin,
   type ResolvedSignalAccount,
 } from "clawdbot/plugin-sdk";
 
 import { getSignalRuntime } from "./runtime.js";
 
+const signalMessageActions: ChannelMessageActionAdapter = {
+  listActions: (ctx) => getSignalRuntime().channel.signal.messageActions.listActions(ctx),
+  supportsAction: (ctx) => getSignalRuntime().channel.signal.messageActions.supportsAction?.(ctx),
+  handleAction: async (ctx) =>
+    await getSignalRuntime().channel.signal.messageActions.handleAction(ctx),
+};
+
 const meta = getChatChannelMeta("signal");
 
 export const signalPlugin: ChannelPlugin<ResolvedSignalAccount> = {
@@ -42,7 +50,9 @@ export const signalPlugin: ChannelPlugin<ResolvedSignalAccount> = {
   capabilities: {
     chatTypes: ["direct", "group"],
     media: true,
+    reactions: true,
   },
+  actions: signalMessageActions,
   streaming: {
     blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
   },
@@ -115,7 +125,7 @@ export const signalPlugin: ChannelPlugin<ResolvedSignalAccount> = {
     normalizeTarget: normalizeSignalMessagingTarget,
     targetResolver: {
       looksLikeId: looksLikeSignalTargetId,
-      hint: "<E.164|group:ID|signal:group:ID|signal:+E.164>",
+      hint: "<E.164|uuid:ID|group:ID|signal:group:ID|signal:+E.164>",
     },
   },
   setup: {

src/agents/models-config.skips-writing-models-json-no-env-token.test.ts

@@ -48,29 +48,19 @@ describe("models-config", () => {
       const previous = process.env.COPILOT_GITHUB_TOKEN;
       const previousGh = process.env.GH_TOKEN;
       const previousGithub = process.env.GITHUB_TOKEN;
-      const previousVenice = process.env.VENICE_API_KEY;
       const previousKimiCode = process.env.KIMICODE_API_KEY;
-      const previousKimiCodeAlt = process.env.KIMI_CODE_API_KEY;
       const previousMinimax = process.env.MINIMAX_API_KEY;
       const previousMoonshot = process.env.MOONSHOT_API_KEY;
       const previousSynthetic = process.env.SYNTHETIC_API_KEY;
-      const previousAwsAccessKey = process.env.AWS_ACCESS_KEY_ID;
-      const previousAwsSecretKey = process.env.AWS_SECRET_ACCESS_KEY;
-      const previousAwsProfile = process.env.AWS_PROFILE;
-      const previousAwsBearer = process.env.AWS_BEARER_TOKEN;
+      const previousVenice = process.env.VENICE_API_KEY;
       delete process.env.COPILOT_GITHUB_TOKEN;
       delete process.env.GH_TOKEN;
       delete process.env.GITHUB_TOKEN;
-      delete process.env.VENICE_API_KEY;
       delete process.env.KIMICODE_API_KEY;
-      delete process.env.KIMI_CODE_API_KEY;
       delete process.env.MINIMAX_API_KEY;
       delete process.env.MOONSHOT_API_KEY;
       delete process.env.SYNTHETIC_API_KEY;
-      delete process.env.AWS_ACCESS_KEY_ID;
-      delete process.env.AWS_SECRET_ACCESS_KEY;
-      delete process.env.AWS_PROFILE;
-      delete process.env.AWS_BEARER_TOKEN;
+      delete process.env.VENICE_API_KEY;
 
       try {
         vi.resetModules();
@@ -93,26 +83,16 @@ describe("models-config", () => {
         else process.env.GH_TOKEN = previousGh;
         if (previousGithub === undefined) delete process.env.GITHUB_TOKEN;
         else process.env.GITHUB_TOKEN = previousGithub;
-        if (previousVenice === undefined) delete process.env.VENICE_API_KEY;
-        else process.env.VENICE_API_KEY = previousVenice;
         if (previousKimiCode === undefined) delete process.env.KIMICODE_API_KEY;
         else process.env.KIMICODE_API_KEY = previousKimiCode;
-        if (previousKimiCodeAlt === undefined) delete process.env.KIMI_CODE_API_KEY;
-        else process.env.KIMI_CODE_API_KEY = previousKimiCodeAlt;
         if (previousMinimax === undefined) delete process.env.MINIMAX_API_KEY;
         else process.env.MINIMAX_API_KEY = previousMinimax;
         if (previousMoonshot === undefined) delete process.env.MOONSHOT_API_KEY;
         else process.env.MOONSHOT_API_KEY = previousMoonshot;
         if (previousSynthetic === undefined) delete process.env.SYNTHETIC_API_KEY;
         else process.env.SYNTHETIC_API_KEY = previousSynthetic;
-        if (previousAwsAccessKey === undefined) delete process.env.AWS_ACCESS_KEY_ID;
-        else process.env.AWS_ACCESS_KEY_ID = previousAwsAccessKey;
-        if (previousAwsSecretKey === undefined) delete process.env.AWS_SECRET_ACCESS_KEY;
-        else process.env.AWS_SECRET_ACCESS_KEY = previousAwsSecretKey;
-        if (previousAwsProfile === undefined) delete process.env.AWS_PROFILE;
-        else process.env.AWS_PROFILE = previousAwsProfile;
-        if (previousAwsBearer === undefined) delete process.env.AWS_BEARER_TOKEN;
-        else process.env.AWS_BEARER_TOKEN = previousAwsBearer;
+        if (previousVenice === undefined) delete process.env.VENICE_API_KEY;
+        else process.env.VENICE_API_KEY = previousVenice;
       }
     });
   });

src/agents/pi-embedded-runner/compact.ts

@@ -15,6 +15,8 @@ import { resolveChannelCapabilities } from "../../config/channel-capabilities.js
 import type { ClawdbotConfig } from "../../config/config.js";
 import { getMachineDisplayName } from "../../infra/machine-name.js";
 import { resolveTelegramInlineButtonsScope } from "../../telegram/inline-buttons.js";
+import { resolveTelegramReactionLevel } from "../../telegram/reaction-level.js";
+import { resolveSignalReactionLevel } from "../../signal/reaction-level.js";
 import { type enqueueCommand, enqueueCommandInLane } from "../../process/command-queue.js";
 import { normalizeMessageChannel } from "../../utils/message-channel.js";
 import { isSubagentSessionKey } from "../../routing/session-key.js";
@@ -255,6 +257,28 @@ export async function compactEmbeddedPiSessionDirect(
         }
       }
     }
+    const reactionGuidance =
+      runtimeChannel && params.config
+        ? (() => {
+            if (runtimeChannel === "telegram") {
+              const resolved = resolveTelegramReactionLevel({
+                cfg: params.config,
+                accountId: params.agentAccountId ?? undefined,
+              });
+              const level = resolved.agentReactionGuidance;
+              return level ? { level, channel: "Telegram" } : undefined;
+            }
+            if (runtimeChannel === "signal") {
+              const resolved = resolveSignalReactionLevel({
+                cfg: params.config,
+                accountId: params.agentAccountId ?? undefined,
+              });
+              const level = resolved.agentReactionGuidance;
+              return level ? { level, channel: "Signal" } : undefined;
+            }
+            return undefined;
+          })()
+        : undefined;
     // Resolve channel-specific message actions for system prompt
     const channelActions = runtimeChannel
       ? listChannelSupportedActions({
@@ -313,6 +337,7 @@ export async function compactEmbeddedPiSessionDirect(
       ttsHint,
       promptMode,
       runtimeInfo,
+      reactionGuidance,
       messageToolHints,
       sandboxInfo,
       tools,

src/agents/pi-embedded-runner/run/attempt.ts

@@ -15,6 +15,7 @@ import { resolveChannelCapabilities } from "../../../config/channel-capabilities
 import { getMachineDisplayName } from "../../../infra/machine-name.js";
 import { resolveTelegramInlineButtonsScope } from "../../../telegram/inline-buttons.js";
 import { resolveTelegramReactionLevel } from "../../../telegram/reaction-level.js";
+import { resolveSignalReactionLevel } from "../../../signal/reaction-level.js";
 import { normalizeMessageChannel } from "../../../utils/message-channel.js";
 import { isReasoningTagProvider } from "../../../utils/provider-utils.js";
 import { isSubagentSessionKey } from "../../../routing/session-key.js";
@@ -255,14 +256,25 @@ export async function runEmbeddedAttempt(
       }
     }
     const reactionGuidance =
-      runtimeChannel === "telegram" && params.config
+      runtimeChannel && params.config
         ? (() => {
-            const resolved = resolveTelegramReactionLevel({
-              cfg: params.config,
-              accountId: params.agentAccountId ?? undefined,
-            });
-            const level = resolved.agentReactionGuidance;
-            return level ? { level, channel: "Telegram" } : undefined;
+            if (runtimeChannel === "telegram") {
+              const resolved = resolveTelegramReactionLevel({
+                cfg: params.config,
+                accountId: params.agentAccountId ?? undefined,
+              });
+              const level = resolved.agentReactionGuidance;
+              return level ? { level, channel: "Telegram" } : undefined;
+            }
+            if (runtimeChannel === "signal") {
+              const resolved = resolveSignalReactionLevel({
+                cfg: params.config,
+                accountId: params.agentAccountId ?? undefined,
+              });
+              const level = resolved.agentReactionGuidance;
+              return level ? { level, channel: "Signal" } : undefined;
+            }
+            return undefined;
           })()
         : undefined;
     const { defaultAgentId, sessionAgentId } = resolveSessionAgentIds({

src/agents/tools/message-tool.ts

@@ -94,6 +94,9 @@ function buildReactionSchema() {
     messageId: Type.Optional(Type.String()),
     emoji: Type.Optional(Type.String()),
     remove: Type.Optional(Type.Boolean()),
+    targetAuthor: Type.Optional(Type.String()),
+    targetAuthorUuid: Type.Optional(Type.String()),
+    groupId: Type.Optional(Type.String()),
   };
 }
 

src/auto-reply/reply/commands-tts.ts

@@ -6,19 +6,20 @@ import {
   getTtsMaxLength,
   getTtsProvider,
   isSummarizationEnabled,
-  isTtsEnabled,
   isTtsProviderConfigured,
+  normalizeTtsAutoMode,
+  resolveTtsAutoMode,
   resolveTtsApiKey,
   resolveTtsConfig,
   resolveTtsPrefsPath,
   resolveTtsProviderOrder,
   setLastTtsAttempt,
   setSummarizationEnabled,
-  setTtsEnabled,
   setTtsMaxLength,
   setTtsProvider,
   textToSpeech,
 } from "../../tts/tts.js";
+import { updateSessionStore } from "../../config/sessions.js";
 
 type ParsedTtsCommand = {
   action: string;
@@ -39,9 +40,9 @@ function ttsUsage(): ReplyPayload {
   // Keep usage in one place so help/validation stays consistent.
   return {
     text:
-      "⚙️ Usage: /tts <on|off|status|provider|limit|summary|audio> [value]" +
+      "⚙️ Usage: /tts <off|always|inbound|tagged|status|provider|limit|summary|audio> [value]" +
       "\nExamples:\n" +
-      "/tts on\n" +
+      "/tts always\n" +
       "/tts provider openai\n" +
       "/tts provider edge\n" +
       "/tts limit 2000\n" +
@@ -71,14 +72,30 @@ export const handleTtsCommands: CommandHandler = async (params, allowTextCommand
     return { shouldContinue: false, reply: ttsUsage() };
   }
 
-  if (action === "on") {
-    setTtsEnabled(prefsPath, true);
-    return { shouldContinue: false, reply: { text: "🔊 TTS enabled." } };
-  }
-
-  if (action === "off") {
-    setTtsEnabled(prefsPath, false);
-    return { shouldContinue: false, reply: { text: "🔇 TTS disabled." } };
+  const requestedAuto = normalizeTtsAutoMode(
+    action === "on" ? "always" : action === "off" ? "off" : action,
+  );
+  if (requestedAuto) {
+    const entry = params.sessionEntry;
+    const sessionKey = params.sessionKey;
+    const store = params.sessionStore;
+    if (entry && store && sessionKey) {
+      entry.ttsAuto = requestedAuto;
+      entry.updatedAt = Date.now();
+      store[sessionKey] = entry;
+      if (params.storePath) {
+        await updateSessionStore(params.storePath, (store) => {
+          store[sessionKey] = entry;
+        });
+      }
+    }
+    const label = requestedAuto === "always" ? "enabled (always)" : requestedAuto;
+    return {
+      shouldContinue: false,
+      reply: {
+        text: requestedAuto === "off" ? "🔇 TTS disabled." : `🔊 TTS ${label}.`,
+      },
+    };
   }
 
   if (action === "audio") {
@@ -212,7 +229,9 @@ export const handleTtsCommands: CommandHandler = async (params, allowTextCommand
   }
 
   if (action === "status") {
-    const enabled = isTtsEnabled(config, prefsPath);
+    const sessionAuto = params.sessionEntry?.ttsAuto;
+    const autoMode = resolveTtsAutoMode({ config, prefsPath, sessionAuto });
+    const enabled = autoMode !== "off";
     const provider = getTtsProvider(config, prefsPath);
     const hasKey = isTtsProviderConfigured(config, provider);
     const providerStatus =
@@ -226,9 +245,10 @@ export const handleTtsCommands: CommandHandler = async (params, allowTextCommand
     const maxLength = getTtsMaxLength(prefsPath);
     const summarize = isSummarizationEnabled(prefsPath);
     const last = getLastTtsAttempt();
+    const autoLabel = sessionAuto ? `${autoMode} (session)` : autoMode;
     const lines = [
       "📊 TTS status",
-      `State: ${enabled ? "✅ enabled" : "❌ disabled"}`,
+      `Auto: ${enabled ? autoLabel : "off"}`,
       `Provider: ${provider} (${providerStatus})`,
       `Text limit: ${maxLength} chars`,
       `Auto-summary: ${summarize ? "on" : "off"}`,

src/auto-reply/reply/dispatch-from-config.ts

@@ -1,4 +1,6 @@
 import type { ClawdbotConfig } from "../../config/config.js";
+import { resolveSessionAgentId } from "../../agents/agent-scope.js";
+import { loadSessionStore, resolveStorePath } from "../../config/sessions.js";
 import { logVerbose } from "../../globals.js";
 import { isDiagnosticsEnabled } from "../../infra/diagnostic-events.js";
 import {
@@ -14,7 +16,55 @@ import { formatAbortReplyText, tryFastAbortFromMessage } from "./abort.js";
 import { shouldSkipDuplicateInbound } from "./inbound-dedupe.js";
 import type { ReplyDispatcher, ReplyDispatchKind } from "./reply-dispatcher.js";
 import { isRoutableChannel, routeReply } from "./route-reply.js";
-import { maybeApplyTtsToPayload } from "../../tts/tts.js";
+import { maybeApplyTtsToPayload, normalizeTtsAutoMode } from "../../tts/tts.js";
+
+const AUDIO_PLACEHOLDER_RE = /^<media:audio>(\s*\([^)]*\))?$/i;
+const AUDIO_HEADER_RE = /^\[Audio\b/i;
+
+const normalizeMediaType = (value: string): string => value.split(";")[0]?.trim().toLowerCase();
+
+const isInboundAudioContext = (ctx: FinalizedMsgContext): boolean => {
+  const rawTypes = [
+    typeof ctx.MediaType === "string" ? ctx.MediaType : undefined,
+    ...(Array.isArray(ctx.MediaTypes) ? ctx.MediaTypes : []),
+  ].filter(Boolean) as string[];
+  const types = rawTypes.map((type) => normalizeMediaType(type));
+  if (types.some((type) => type === "audio" || type.startsWith("audio/"))) return true;
+
+  const body =
+    typeof ctx.BodyForCommands === "string"
+      ? ctx.BodyForCommands
+      : typeof ctx.CommandBody === "string"
+        ? ctx.CommandBody
+        : typeof ctx.RawBody === "string"
+          ? ctx.RawBody
+          : typeof ctx.Body === "string"
+            ? ctx.Body
+            : "";
+  const trimmed = body.trim();
+  if (!trimmed) return false;
+  if (AUDIO_PLACEHOLDER_RE.test(trimmed)) return true;
+  return AUDIO_HEADER_RE.test(trimmed);
+};
+
+const resolveSessionTtsAuto = (
+  ctx: FinalizedMsgContext,
+  cfg: ClawdbotConfig,
+): string | undefined => {
+  const targetSessionKey =
+    ctx.CommandSource === "native" ? ctx.CommandTargetSessionKey?.trim() : undefined;
+  const sessionKey = (targetSessionKey ?? ctx.SessionKey)?.trim();
+  if (!sessionKey) return undefined;
+  const agentId = resolveSessionAgentId({ sessionKey, config: cfg });
+  const storePath = resolveStorePath(cfg.session?.store, { agentId });
+  try {
+    const store = loadSessionStore(storePath);
+    const entry = store[sessionKey.toLowerCase()] ?? store[sessionKey];
+    return normalizeTtsAutoMode(entry?.ttsAuto);
+  } catch {
+    return undefined;
+  }
+};
 
 export type DispatchFromConfigResult = {
   queuedFinal: boolean;
@@ -81,6 +131,8 @@ export async function dispatchReplyFromConfig(params: {
     return { queuedFinal: false, counts: dispatcher.getQueuedCounts() };
   }
 
+  const inboundAudio = isInboundAudioContext(ctx);
+  const sessionTtsAuto = resolveSessionTtsAuto(ctx, cfg);
   const hookRunner = getGlobalHookRunner();
   if (hookRunner?.hasHooks("message_received")) {
     const timestamp =
@@ -223,6 +275,8 @@ export async function dispatchReplyFromConfig(params: {
               cfg,
               channel: ttsChannel,
               kind: "tool",
+              inboundAudio,
+              ttsAuto: sessionTtsAuto,
             });
             if (shouldRouteToOriginating) {
               await sendPayloadAsync(ttsPayload);
@@ -239,6 +293,8 @@ export async function dispatchReplyFromConfig(params: {
               cfg,
               channel: ttsChannel,
               kind: "block",
+              inboundAudio,
+              ttsAuto: sessionTtsAuto,
             });
             if (shouldRouteToOriginating) {
               await sendPayloadAsync(ttsPayload, context?.abortSignal);
@@ -262,6 +318,8 @@ export async function dispatchReplyFromConfig(params: {
         cfg,
         channel: ttsChannel,
         kind: "final",
+        inboundAudio,
+        ttsAuto: sessionTtsAuto,
       });
       if (shouldRouteToOriginating && originatingChannel && originatingTo) {
         // Route final reply to originating channel.

src/auto-reply/reply/session.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { CURRENT_SESSION_VERSION, SessionManager } from "@mariozechner/pi-coding-agent";
 import { resolveSessionAgentId } from "../../agents/agent-scope.js";
 import type { ClawdbotConfig } from "../../config/config.js";
+import type { TtsAutoMode } from "../../config/types.tts.js";
 import {
   DEFAULT_RESET_TRIGGERS,
   deriveSessionMetaPatch,
@@ -128,6 +129,7 @@ export async function initSessionState(params: {
   let persistedThinking: string | undefined;
   let persistedVerbose: string | undefined;
   let persistedReasoning: string | undefined;
+  let persistedTtsAuto: TtsAutoMode | undefined;
   let persistedModelOverride: string | undefined;
   let persistedProviderOverride: string | undefined;
 
@@ -220,6 +222,7 @@ export async function initSessionState(params: {
     persistedThinking = entry.thinkingLevel;
     persistedVerbose = entry.verboseLevel;
     persistedReasoning = entry.reasoningLevel;
+    persistedTtsAuto = entry.ttsAuto;
     persistedModelOverride = entry.modelOverride;
     persistedProviderOverride = entry.providerOverride;
   } else {
@@ -258,6 +261,7 @@ export async function initSessionState(params: {
     thinkingLevel: persistedThinking ?? baseEntry?.thinkingLevel,
     verboseLevel: persistedVerbose ?? baseEntry?.verboseLevel,
     reasoningLevel: persistedReasoning ?? baseEntry?.reasoningLevel,
+    ttsAuto: persistedTtsAuto ?? baseEntry?.ttsAuto,
     responseUsage: baseEntry?.responseUsage,
     modelOverride: persistedModelOverride ?? baseEntry?.modelOverride,
     providerOverride: persistedProviderOverride ?? baseEntry?.providerOverride,

src/auto-reply/status.ts

@@ -17,7 +17,7 @@ import {
   getTtsMaxLength,
   getTtsProvider,
   isSummarizationEnabled,
-  isTtsEnabled,
+  resolveTtsAutoMode,
   resolveTtsConfig,
   resolveTtsPrefsPath,
 } from "../tts/tts.js";
@@ -252,15 +252,23 @@ const formatMediaUnderstandingLine = (decisions?: MediaUnderstandingDecision[])
   return `📎 Media: ${parts.join(" · ")}`;
 };
 
-const formatVoiceModeLine = (config?: ClawdbotConfig): string | null => {
+const formatVoiceModeLine = (
+  config?: ClawdbotConfig,
+  sessionEntry?: SessionEntry,
+): string | null => {
   if (!config) return null;
   const ttsConfig = resolveTtsConfig(config);
   const prefsPath = resolveTtsPrefsPath(ttsConfig);
-  if (!isTtsEnabled(ttsConfig, prefsPath)) return null;
+  const autoMode = resolveTtsAutoMode({
+    config: ttsConfig,
+    prefsPath,
+    sessionAuto: sessionEntry?.ttsAuto,
+  });
+  if (autoMode === "off") return null;
   const provider = getTtsProvider(ttsConfig, prefsPath);
   const maxLength = getTtsMaxLength(prefsPath);
   const summarize = isSummarizationEnabled(prefsPath) ? "on" : "off";
-  return `🔊 Voice: on · provider=${provider} · limit=${maxLength} · summary=${summarize}`;
+  return `🔊 Voice: ${autoMode} · provider=${provider} · limit=${maxLength} · summary=${summarize}`;
 };
 
 export function buildStatusMessage(args: StatusArgs): string {
@@ -398,7 +406,7 @@ export function buildStatusMessage(args: StatusArgs): string {
   const usageCostLine =
     usagePair && costLine ? `${usagePair} · ${costLine}` : (usagePair ?? costLine);
   const mediaLine = formatMediaUnderstandingLine(args.mediaDecisions);
-  const voiceLine = formatVoiceModeLine(args.config);
+  const voiceLine = formatVoiceModeLine(args.config, args.sessionEntry);
 
   return [
     versionLine,

src/channels/plugins/actions/signal.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ClawdbotConfig } from "../../../config/config.js";
+import { signalMessageActions } from "./signal.js";
+
+const sendReactionSignal = vi.fn(async () => ({ ok: true }));
+const removeReactionSignal = vi.fn(async () => ({ ok: true }));
+
+vi.mock("../../../signal/send-reactions.js", () => ({
+  sendReactionSignal: (...args: unknown[]) => sendReactionSignal(...args),
+  removeReactionSignal: (...args: unknown[]) => removeReactionSignal(...args),
+}));
+
+describe("signalMessageActions", () => {
+  it("returns no actions when no configured accounts exist", () => {
+    const cfg = {} as ClawdbotConfig;
+    expect(signalMessageActions.listActions({ cfg })).toEqual([]);
+  });
+
+  it("hides react when reactions are disabled", () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111", actions: { reactions: false } } },
+    } as ClawdbotConfig;
+    expect(signalMessageActions.listActions({ cfg })).toEqual(["send"]);
+  });
+
+  it("enables react when at least one account allows reactions", () => {
+    const cfg = {
+      channels: {
+        signal: {
+          actions: { reactions: false },
+          accounts: {
+            work: { account: "+15550001111", actions: { reactions: true } },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+    expect(signalMessageActions.listActions({ cfg })).toEqual(["send", "react"]);
+  });
+
+  it("skips send for plugin dispatch", () => {
+    expect(signalMessageActions.supportsAction?.({ action: "send" })).toBe(false);
+    expect(signalMessageActions.supportsAction?.({ action: "react" })).toBe(true);
+  });
+
+  it("blocks reactions when action gate is disabled", async () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111", actions: { reactions: false } } },
+    } as ClawdbotConfig;
+
+    await expect(
+      signalMessageActions.handleAction({
+        action: "react",
+        params: { to: "+15550001111", messageId: "123", emoji: "✅" },
+        cfg,
+        accountId: undefined,
+      }),
+    ).rejects.toThrow(/actions\.reactions/);
+  });
+
+  it("uses account-level actions when enabled", async () => {
+    sendReactionSignal.mockClear();
+    const cfg = {
+      channels: {
+        signal: {
+          actions: { reactions: false },
+          accounts: {
+            work: { account: "+15550001111", actions: { reactions: true } },
+          },
+        },
+      },
+    } as ClawdbotConfig;
+
+    await signalMessageActions.handleAction({
+      action: "react",
+      params: { to: "+15550001111", messageId: "123", emoji: "👍" },
+      cfg,
+      accountId: "work",
+    });
+
+    expect(sendReactionSignal).toHaveBeenCalledWith("+15550001111", 123, "👍", {
+      accountId: "work",
+    });
+  });
+
+  it("normalizes uuid recipients", async () => {
+    sendReactionSignal.mockClear();
+    const cfg = {
+      channels: { signal: { account: "+15550001111" } },
+    } as ClawdbotConfig;
+
+    await signalMessageActions.handleAction({
+      action: "react",
+      params: {
+        recipient: "uuid:123e4567-e89b-12d3-a456-426614174000",
+        messageId: "123",
+        emoji: "🔥",
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(sendReactionSignal).toHaveBeenCalledWith(
+      "123e4567-e89b-12d3-a456-426614174000",
+      123,
+      "🔥",
+      { accountId: undefined },
+    );
+  });
+
+  it("requires targetAuthor for group reactions", async () => {
+    const cfg = {
+      channels: { signal: { account: "+15550001111" } },
+    } as ClawdbotConfig;
+
+    await expect(
+      signalMessageActions.handleAction({
+        action: "react",
+        params: { to: "signal:group:group-id", messageId: "123", emoji: "✅" },
+        cfg,
+        accountId: undefined,
+      }),
+    ).rejects.toThrow(/targetAuthor/);
+  });
+
+  it("passes groupId and targetAuthor for group reactions", async () => {
+    sendReactionSignal.mockClear();
+    const cfg = {
+      channels: { signal: { account: "+15550001111" } },
+    } as ClawdbotConfig;
+
+    await signalMessageActions.handleAction({
+      action: "react",
+      params: {
+        to: "signal:group:group-id",
+        targetAuthor: "uuid:123e4567-e89b-12d3-a456-426614174000",
+        messageId: "123",
+        emoji: "✅",
+      },
+      cfg,
+      accountId: undefined,
+    });
+
+    expect(sendReactionSignal).toHaveBeenCalledWith("", 123, "✅", {
+      accountId: undefined,
+      groupId: "group-id",
+      targetAuthor: "uuid:123e4567-e89b-12d3-a456-426614174000",
+      targetAuthorUuid: undefined,
+    });
+  });
+});

src/channels/plugins/actions/signal.ts

@@ -0,0 +1,130 @@
+import { createActionGate, jsonResult, readStringParam } from "../../../agents/tools/common.js";
+import { listEnabledSignalAccounts, resolveSignalAccount } from "../../../signal/accounts.js";
+import { resolveSignalReactionLevel } from "../../../signal/reaction-level.js";
+import { sendReactionSignal, removeReactionSignal } from "../../../signal/send-reactions.js";
+import type { ChannelMessageActionAdapter, ChannelMessageActionName } from "../types.js";
+
+const providerId = "signal";
+const GROUP_PREFIX = "group:";
+
+function normalizeSignalReactionRecipient(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return trimmed;
+  const withoutSignal = trimmed.replace(/^signal:/i, "").trim();
+  if (!withoutSignal) return withoutSignal;
+  if (withoutSignal.toLowerCase().startsWith("uuid:")) {
+    return withoutSignal.slice("uuid:".length).trim();
+  }
+  return withoutSignal;
+}
+
+function resolveSignalReactionTarget(raw: string): { recipient?: string; groupId?: string } {
+  const trimmed = raw.trim();
+  if (!trimmed) return {};
+  const withoutSignal = trimmed.replace(/^signal:/i, "").trim();
+  if (!withoutSignal) return {};
+  if (withoutSignal.toLowerCase().startsWith(GROUP_PREFIX)) {
+    const groupId = withoutSignal.slice(GROUP_PREFIX.length).trim();
+    return groupId ? { groupId } : {};
+  }
+  return { recipient: normalizeSignalReactionRecipient(withoutSignal) };
+}
+
+export const signalMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const accounts = listEnabledSignalAccounts(cfg);
+    if (accounts.length === 0) return [];
+    const configuredAccounts = accounts.filter((account) => account.configured);
+    if (configuredAccounts.length === 0) return [];
+
+    const actions = new Set<ChannelMessageActionName>(["send"]);
+
+    const reactionsEnabled = configuredAccounts.some((account) =>
+      createActionGate(account.config.actions)("reactions"),
+    );
+    if (reactionsEnabled) {
+      actions.add("react");
+    }
+
+    return Array.from(actions);
+  },
+  supportsAction: ({ action }) => action !== "send",
+
+  handleAction: async ({ action, params, cfg, accountId }) => {
+    if (action === "send") {
+      throw new Error("Send should be handled by outbound, not actions handler.");
+    }
+
+    if (action === "react") {
+      // Check reaction level first
+      const reactionLevelInfo = resolveSignalReactionLevel({
+        cfg,
+        accountId: accountId ?? undefined,
+      });
+      if (!reactionLevelInfo.agentReactionsEnabled) {
+        throw new Error(
+          `Signal agent reactions disabled (reactionLevel="${reactionLevelInfo.level}"). ` +
+            `Set channels.signal.reactionLevel to "minimal" or "extensive" to enable.`,
+        );
+      }
+
+      // Also check the action gate for backward compatibility
+      const actionConfig = resolveSignalAccount({ cfg, accountId }).config.actions;
+      const isActionEnabled = createActionGate(actionConfig);
+      if (!isActionEnabled("reactions")) {
+        throw new Error("Signal reactions are disabled via actions.reactions.");
+      }
+
+      const recipientRaw =
+        readStringParam(params, "recipient") ??
+        readStringParam(params, "to", {
+          required: true,
+          label: "recipient (UUID, phone number, or group)",
+        });
+      const target = resolveSignalReactionTarget(recipientRaw);
+      if (!target.recipient && !target.groupId) {
+        throw new Error("recipient or group required");
+      }
+
+      const messageId = readStringParam(params, "messageId", {
+        required: true,
+        label: "messageId (timestamp)",
+      });
+      const targetAuthor = readStringParam(params, "targetAuthor");
+      const targetAuthorUuid = readStringParam(params, "targetAuthorUuid");
+      if (target.groupId && !targetAuthor && !targetAuthorUuid) {
+        throw new Error("targetAuthor or targetAuthorUuid required for group reactions.");
+      }
+
+      const emoji = readStringParam(params, "emoji", { allowEmpty: true });
+      const remove = typeof params.remove === "boolean" ? params.remove : undefined;
+
+      const timestamp = parseInt(messageId, 10);
+      if (!Number.isFinite(timestamp)) {
+        throw new Error(`Invalid messageId: ${messageId}. Expected numeric timestamp.`);
+      }
+
+      if (remove) {
+        if (!emoji) throw new Error("Emoji required to remove reaction.");
+        await removeReactionSignal(target.recipient ?? "", timestamp, emoji, {
+          accountId: accountId ?? undefined,
+          groupId: target.groupId,
+          targetAuthor,
+          targetAuthorUuid,
+        });
+        return jsonResult({ ok: true, removed: emoji });
+      }
+
+      if (!emoji) throw new Error("Emoji required to add reaction.");
+      await sendReactionSignal(target.recipient ?? "", timestamp, emoji, {
+        accountId: accountId ?? undefined,
+        groupId: target.groupId,
+        targetAuthor,
+        targetAuthorUuid,
+      });
+      return jsonResult({ ok: true, added: emoji });
+    }
+
+    throw new Error(`Action ${action} not supported for ${providerId}.`);
+  },
+};

src/channels/plugins/normalize/signal.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { looksLikeSignalTargetId, normalizeSignalMessagingTarget } from "./signal.js";
+
+describe("signal target normalization", () => {
+  it("normalizes uuid targets by stripping uuid:", () => {
+    expect(normalizeSignalMessagingTarget("uuid:123E4567-E89B-12D3-A456-426614174000")).toBe(
+      "123e4567-e89b-12d3-a456-426614174000",
+    );
+  });
+
+  it("normalizes signal:uuid targets", () => {
+    expect(normalizeSignalMessagingTarget("signal:uuid:123E4567-E89B-12D3-A456-426614174000")).toBe(
+      "123e4567-e89b-12d3-a456-426614174000",
+    );
+  });
+
+  it("accepts uuid prefixes for target detection", () => {
+    expect(looksLikeSignalTargetId("uuid:123e4567-e89b-12d3-a456-426614174000")).toBe(true);
+    expect(looksLikeSignalTargetId("signal:uuid:123e4567-e89b-12d3-a456-426614174000")).toBe(true);
+  });
+
+  it("accepts compact UUIDs for target detection", () => {
+    expect(looksLikeSignalTargetId("123e4567e89b12d3a456426614174000")).toBe(true);
+    expect(looksLikeSignalTargetId("uuid:123e4567e89b12d3a456426614174000")).toBe(true);
+  });
+
+  it("rejects invalid uuid prefixes", () => {
+    expect(looksLikeSignalTargetId("uuid:")).toBe(false);
+    expect(looksLikeSignalTargetId("uuid:not-a-uuid")).toBe(false);
+  });
+});

src/channels/plugins/normalize/signal.ts

@@ -19,12 +19,30 @@ export function normalizeSignalMessagingTarget(raw: string): string | undefined
     const id = normalized.slice("u:".length).trim();
     return id ? `username:${id}`.toLowerCase() : undefined;
   }
+  if (lower.startsWith("uuid:")) {
+    const id = normalized.slice("uuid:".length).trim();
+    return id ? id.toLowerCase() : undefined;
+  }
   return normalized.toLowerCase();
 }
 
+// UUID pattern for signal-cli recipient IDs
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const UUID_COMPACT_PATTERN = /^[0-9a-f]{32}$/i;
+
 export function looksLikeSignalTargetId(raw: string): boolean {
   const trimmed = raw.trim();
   if (!trimmed) return false;
   if (/^(signal:)?(group:|username:|u:)/i.test(trimmed)) return true;
+  if (/^(signal:)?uuid:/i.test(trimmed)) {
+    const stripped = trimmed
+      .replace(/^signal:/i, "")
+      .replace(/^uuid:/i, "")
+      .trim();
+    if (!stripped) return false;
+    return UUID_PATTERN.test(stripped) || UUID_COMPACT_PATTERN.test(stripped);
+  }
+  // Accept UUIDs (used by signal-cli for reactions)
+  if (UUID_PATTERN.test(trimmed) || UUID_COMPACT_PATTERN.test(trimmed)) return true;
   return /^\+?\d{3,}$/.test(trimmed);
 }

src/cli/program.smoke.test.ts

@@ -67,6 +67,28 @@ describe("cli program (smoke)", () => {
     expect(messageCommand).toHaveBeenCalled();
   });
 
+  it("runs message react with signal author fields", async () => {
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        "message",
+        "react",
+        "--channel",
+        "signal",
+        "--target",
+        "signal:group:abc123",
+        "--message-id",
+        "1737630212345",
+        "--emoji",
+        "✅",
+        "--target-author-uuid",
+        "123e4567-e89b-12d3-a456-426614174000",
+      ],
+      { from: "user" },
+    );
+    expect(messageCommand).toHaveBeenCalled();
+  });
+
   it("runs status command", async () => {
     const program = buildProgram();
     await program.parseAsync(["status"], { from: "user" });

src/cli/program/message/register.reactions.ts

@@ -13,6 +13,8 @@ export function registerMessageReactionsCommands(message: Command, helpers: Mess
     .option("--remove", "Remove reaction", false)
     .option("--participant <id>", "WhatsApp reaction participant")
     .option("--from-me", "WhatsApp reaction fromMe", false)
+    .option("--target-author <id>", "Signal reaction target author (uuid or phone)")
+    .option("--target-author-uuid <uuid>", "Signal reaction target author uuid")
     .action(async (opts) => {
       await helpers.runMessageAction("react", opts);
     });

src/cli/run-main.ts

@@ -11,7 +11,7 @@ import { assertSupportedRuntime } from "../infra/runtime-guard.js";
 import { formatUncaughtError } from "../infra/errors.js";
 import { installUnhandledRejectionHandler } from "../infra/unhandled-rejections.js";
 import { enableConsoleCapture } from "../logging.js";
-import { getPrimaryCommand, hasHelpOrVersion } from "./argv.js";
+import { getPrimaryCommand } from "./argv.js";
 import { tryRouteCli } from "./route.js";
 
 export function rewriteUpdateFlagArgv(argv: string[]): string[] {
@@ -50,12 +50,11 @@ export async function runCli(argv: string[] = process.argv) {
   });
 
   const parseArgv = rewriteUpdateFlagArgv(normalizedArgv);
-  if (hasHelpOrVersion(parseArgv)) {
-    const primary = getPrimaryCommand(parseArgv);
-    if (primary) {
-      const { registerSubCliByName } = await import("./program/register.subclis.js");
-      await registerSubCliByName(program, primary);
-    }
+  // Register the primary subcommand if one exists (for lazy-loading)
+  const primary = getPrimaryCommand(parseArgv);
+  if (primary) {
+    const { registerSubCliByName } = await import("./program/register.subclis.js");
+    await registerSubCliByName(program, primary);
   }
   await program.parseAsync(parseArgv);
 }

src/commands/onboard-auth.config-core.ts

@@ -353,9 +353,7 @@ export function applyVeniceProviderConfig(cfg: ClawdbotConfig): ClawdbotConfig {
   const veniceModels = VENICE_MODEL_CATALOG.map(buildVeniceModelDefinition);
   const mergedModels = [
     ...existingModels,
-    ...veniceModels.filter(
-      (model) => !existingModels.some((existing) => existing.id === model.id),
-    ),
+    ...veniceModels.filter((model) => !existingModels.some((existing) => existing.id === model.id)),
   ];
   const { apiKey: existingApiKey, ...existingProviderRest } = (existingProvider ?? {}) as Record<
     string,

src/commands/onboard-auth.ts

@@ -2,10 +2,7 @@ export {
   SYNTHETIC_DEFAULT_MODEL_ID,
   SYNTHETIC_DEFAULT_MODEL_REF,
 } from "../agents/synthetic-models.js";
-export {
-  VENICE_DEFAULT_MODEL_ID,
-  VENICE_DEFAULT_MODEL_REF,
-} from "../agents/venice-models.js";
+export { VENICE_DEFAULT_MODEL_ID, VENICE_DEFAULT_MODEL_REF } from "../agents/venice-models.js";
 export {
   applyAuthProfileConfig,
   applyKimiCodeConfig,

src/config/config.legacy-config-detection.accepts-imessage-dmpolicy.test.ts

@@ -138,6 +138,16 @@ describe("legacy config detection", () => {
     expect(res.config?.channels?.telegram?.groups?.["*"]?.requireMention).toBe(false);
     expect(res.config?.channels?.telegram?.requireMention).toBeUndefined();
   });
+  it("migrates messages.tts.enabled to messages.tts.auto", async () => {
+    vi.resetModules();
+    const { migrateLegacyConfig } = await import("./config.js");
+    const res = migrateLegacyConfig({
+      messages: { tts: { enabled: true } },
+    });
+    expect(res.changes).toContain("Moved messages.tts.enabled → messages.tts.auto (always).");
+    expect(res.config?.messages?.tts?.auto).toBe("always");
+    expect(res.config?.messages?.tts?.enabled).toBeUndefined();
+  });
   it("migrates legacy model config to agent.models + model lists", async () => {
     vi.resetModules();
     const { migrateLegacyConfig } = await import("./config.js");

src/config/legacy.migrations.part-3.ts

@@ -40,6 +40,26 @@ export const LEGACY_CONFIG_MIGRATIONS_PART_3: LegacyConfigMigration[] = [
       delete tools.bash;
     },
   },
+  {
+    id: "messages.tts.enabled->auto",
+    describe: "Move messages.tts.enabled to messages.tts.auto",
+    apply: (raw, changes) => {
+      const messages = getRecord(raw.messages);
+      const tts = getRecord(messages?.tts);
+      if (!tts) return;
+      if (tts.auto !== undefined) {
+        if ("enabled" in tts) {
+          delete tts.enabled;
+          changes.push("Removed messages.tts.enabled (messages.tts.auto already set).");
+        }
+        return;
+      }
+      if (typeof tts.enabled !== "boolean") return;
+      tts.auto = tts.enabled ? "always" : "off";
+      delete tts.enabled;
+      changes.push(`Moved messages.tts.enabled → messages.tts.auto (${String(tts.auto)}).`);
+    },
+  },
   {
     id: "agent.defaults-v2",
     describe: "Move agent config to agents.defaults and tools",

src/config/legacy.rules.ts

@@ -120,6 +120,10 @@ export const LEGACY_CONFIG_RULES: LegacyConfigRule[] = [
     message:
       "agent.imageModelFallbacks was replaced by agents.defaults.imageModel.fallbacks (auto-migrated on load).",
   },
+  {
+    path: ["messages", "tts", "enabled"],
+    message: "messages.tts.enabled was replaced by messages.tts.auto (auto-migrated on load).",
+  },
   {
     path: ["gateway", "token"],
     message: "gateway.token is ignored; use gateway.auth.token instead (auto-migrated on load).",

src/config/sessions/types.ts

@@ -4,6 +4,7 @@ import type { Skill } from "@mariozechner/pi-coding-agent";
 import type { NormalizedChatType } from "../../channels/chat-type.js";
 import type { ChannelId } from "../../channels/plugins/types.js";
 import type { DeliveryContext } from "../../utils/delivery-context.js";
+import type { TtsAutoMode } from "../types.tts.js";
 
 export type SessionScope = "per-sender" | "global";
 
@@ -42,6 +43,7 @@ export type SessionEntry = {
   verboseLevel?: string;
   reasoningLevel?: string;
   elevatedLevel?: string;
+  ttsAuto?: TtsAutoMode;
   execHost?: string;
   execSecurity?: string;
   execAsk?: string;

src/config/types.signal.ts

@@ -8,6 +8,7 @@ import type { ChannelHeartbeatVisibilityConfig } from "./types.channels.js";
 import type { DmConfig } from "./types.messages.js";
 
 export type SignalReactionNotificationMode = "off" | "own" | "all" | "allowlist";
+export type SignalReactionLevel = "off" | "ack" | "minimal" | "extensive";
 
 export type SignalAccountConfig = {
   /** Optional display name for this account (used in CLI/UI lists). */
@@ -64,6 +65,19 @@ export type SignalAccountConfig = {
   reactionNotifications?: SignalReactionNotificationMode;
   /** Allowlist for reaction notifications when mode is allowlist. */
   reactionAllowlist?: Array<string | number>;
+  /** Action toggles for message tool capabilities. */
+  actions?: {
+    /** Enable/disable sending reactions via message tool (default: true). */
+    reactions?: boolean;
+  };
+  /**
+   * Controls agent reaction behavior:
+   * - "off": No reactions
+   * - "ack": Only automatic ack reactions (👀 when processing)
+   * - "minimal": Agent can react sparingly (default)
+   * - "extensive": Agent can react liberally
+   */
+  reactionLevel?: SignalReactionLevel;
   /** Heartbeat visibility settings for this channel. */
   heartbeat?: ChannelHeartbeatVisibilityConfig;
 };

src/config/types.tts.ts

@@ -2,6 +2,8 @@ export type TtsProvider = "elevenlabs" | "openai" | "edge";
 
 export type TtsMode = "final" | "all";
 
+export type TtsAutoMode = "off" | "always" | "inbound" | "tagged";
+
 export type TtsModelOverrideConfig = {
   /** Enable model-provided overrides for TTS. */
   enabled?: boolean;
@@ -22,7 +24,9 @@ export type TtsModelOverrideConfig = {
 };
 
 export type TtsConfig = {
-  /** Enable auto-TTS (can be overridden by local prefs). */
+  /** Auto-TTS mode (preferred). */
+  auto?: TtsAutoMode;
+  /** Legacy: enable auto-TTS when `auto` is not set. */
   enabled?: boolean;
   /** Apply TTS to final replies only or to all replies (tool/block/final). */
   mode?: TtsMode;

src/config/zod-schema.core.ts

@@ -158,8 +158,10 @@ export const MarkdownConfigSchema = z
 
 export const TtsProviderSchema = z.enum(["elevenlabs", "openai", "edge"]);
 export const TtsModeSchema = z.enum(["final", "all"]);
+export const TtsAutoSchema = z.enum(["off", "always", "inbound", "tagged"]);
 export const TtsConfigSchema = z
   .object({
+    auto: TtsAutoSchema.optional(),
     enabled: z.boolean().optional(),
     mode: TtsModeSchema.optional(),
     provider: TtsProviderSchema.optional(),

src/config/zod-schema.providers-core.ts

@@ -499,6 +499,13 @@ export const SignalAccountSchemaBase = z
     mediaMaxMb: z.number().int().positive().optional(),
     reactionNotifications: z.enum(["off", "own", "all", "allowlist"]).optional(),
     reactionAllowlist: z.array(z.union([z.string(), z.number()])).optional(),
+    actions: z
+      .object({
+        reactions: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    reactionLevel: z.enum(["off", "ack", "minimal", "extensive"]).optional(),
     heartbeat: ChannelHeartbeatVisibilitySchema,
   })
   .strict();

src/discord/monitor/message-handler.process.ts

@@ -1,3 +1,4 @@
+import { ChannelType } from "@buape/carbon";
 import { resolveAckReaction, resolveHumanDelayConfig } from "../../agents/identity.js";
 import {
   removeAckReactionAfterReply,
@@ -129,6 +130,14 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
     senderDisplay && senderTag && senderDisplay !== senderTag
       ? `${senderDisplay} (${senderTag})`
       : (senderDisplay ?? senderTag ?? author.id);
+  const isForumParent =
+    threadParentType === ChannelType.GuildForum || threadParentType === ChannelType.GuildMedia;
+  const forumParentSlug =
+    isForumParent && threadParentName ? normalizeDiscordSlug(threadParentName) : "";
+  const threadChannelId = threadChannel?.id;
+  const isForumStarter =
+    Boolean(threadChannelId && isForumParent && forumParentSlug) && message.id === threadChannelId;
+  const forumContextLine = isForumStarter ? `[Forum parent: #${forumParentSlug}]` : null;
   const groupChannel = isGuildMessage && displayChannelSlug ? `#${displayChannelSlug}` : undefined;
   const groupSubject = isDirectMessage ? undefined : groupChannel;
   const channelDescription = channelInfo?.topic?.trim();
@@ -182,6 +191,9 @@ export async function processDiscordMessage(ctx: DiscordMessagePreflightContext)
   if (replyContext) {
     combinedBody = `[Replied message - for context]\n${replyContext}\n\n${combinedBody}`;
   }
+  if (forumContextLine) {
+    combinedBody = `${combinedBody}\n${forumContextLine}`;
+  }
 
   let threadStarterBody: string | undefined;
   let threadLabel: string | undefined;

src/gateway/server-discovery-runtime.ts

@@ -13,6 +13,7 @@ export async function startGatewayDiscovery(params: {
   gatewayTls?: { enabled: boolean; fingerprintSha256?: string };
   canvasPort?: number;
   wideAreaDiscoveryEnabled: boolean;
+  tailscaleMode: "off" | "serve" | "funnel";
   logDiscovery: { info: (msg: string) => void; warn: (msg: string) => void };
 }) {
   let bonjourStop: (() => Promise<void>) | null = null;
@@ -20,8 +21,11 @@ export async function startGatewayDiscovery(params: {
     process.env.CLAWDBOT_DISABLE_BONJOUR !== "1" &&
     process.env.NODE_ENV !== "test" &&
     !process.env.VITEST;
+  const tailscaleEnabled = params.tailscaleMode !== "off";
   const needsTailnetDns = bonjourEnabled || params.wideAreaDiscoveryEnabled;
-  const tailnetDns = needsTailnetDns ? await resolveTailnetDnsHint() : undefined;
+  const tailnetDns = needsTailnetDns
+    ? await resolveTailnetDnsHint({ enabled: tailscaleEnabled })
+    : undefined;
   const sshPortEnv = process.env.CLAWDBOT_SSH_PORT?.trim();
   const sshPortParsed = sshPortEnv ? Number.parseInt(sshPortEnv, 10) : NaN;
   const sshPort = Number.isFinite(sshPortParsed) && sshPortParsed > 0 ? sshPortParsed : undefined;

src/gateway/server-discovery.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+const getTailnetHostname = vi.hoisted(() => vi.fn());
+
+vi.mock("../infra/tailscale.js", () => ({ getTailnetHostname }));
+
+import { resolveTailnetDnsHint } from "./server-discovery.js";
+
+describe("resolveTailnetDnsHint", () => {
+  const prevTailnetDns = { value: undefined as string | undefined };
+
+  beforeEach(() => {
+    prevTailnetDns.value = process.env.CLAWDBOT_TAILNET_DNS;
+    delete process.env.CLAWDBOT_TAILNET_DNS;
+    getTailnetHostname.mockReset();
+  });
+
+  afterEach(() => {
+    if (prevTailnetDns.value === undefined) {
+      delete process.env.CLAWDBOT_TAILNET_DNS;
+    } else {
+      process.env.CLAWDBOT_TAILNET_DNS = prevTailnetDns.value;
+    }
+  });
+
+  test("returns env hint when disabled", async () => {
+    process.env.CLAWDBOT_TAILNET_DNS = "studio.tailnet.ts.net.";
+    const value = await resolveTailnetDnsHint({ enabled: false });
+    expect(value).toBe("studio.tailnet.ts.net");
+    expect(getTailnetHostname).not.toHaveBeenCalled();
+  });
+
+  test("skips tailscale lookup when disabled", async () => {
+    const value = await resolveTailnetDnsHint({ enabled: false });
+    expect(value).toBeUndefined();
+    expect(getTailnetHostname).not.toHaveBeenCalled();
+  });
+
+  test("uses tailscale lookup when enabled", async () => {
+    getTailnetHostname.mockResolvedValue("host.tailnet.ts.net");
+    const value = await resolveTailnetDnsHint({ enabled: true });
+    expect(value).toBe("host.tailnet.ts.net");
+    expect(getTailnetHostname).toHaveBeenCalledTimes(1);
+  });
+});

src/gateway/server-discovery.ts

@@ -55,11 +55,13 @@ export function resolveBonjourCliPath(opts: ResolveBonjourCliPathOptions = {}):
 export async function resolveTailnetDnsHint(opts?: {
   env?: NodeJS.ProcessEnv;
   exec?: typeof runExec;
+  enabled?: boolean;
 }): Promise<string | undefined> {
   const env = opts?.env ?? process.env;
   const envRaw = env.CLAWDBOT_TAILNET_DNS?.trim();
   const envValue = envRaw && envRaw.length > 0 ? envRaw.replace(/\.$/, "") : "";
   if (envValue) return envValue;
+  if (opts?.enabled === false) return undefined;
 
   const exec =
     opts?.exec ??

src/gateway/server-methods/tts.ts

@@ -5,6 +5,7 @@ import {
   getTtsProvider,
   isTtsEnabled,
   isTtsProviderConfigured,
+  resolveTtsAutoMode,
   resolveTtsApiKey,
   resolveTtsConfig,
   resolveTtsPrefsPath,
@@ -24,11 +25,13 @@ export const ttsHandlers: GatewayRequestHandlers = {
       const config = resolveTtsConfig(cfg);
       const prefsPath = resolveTtsPrefsPath(config);
       const provider = getTtsProvider(config, prefsPath);
+      const autoMode = resolveTtsAutoMode({ config, prefsPath });
       const fallbackProviders = resolveTtsProviderOrder(provider)
         .slice(1)
         .filter((candidate) => isTtsProviderConfigured(config, candidate));
       respond(true, {
         enabled: isTtsEnabled(config, prefsPath),
+        auto: autoMode,
         provider,
         fallbackProvider: fallbackProviders[0] ?? null,
         fallbackProviders,

src/gateway/server.impl.ts

@@ -339,6 +339,7 @@ export async function startGatewayServer(
       ? { enabled: true, fingerprintSha256: gatewayTls.fingerprintSha256 }
       : undefined,
     wideAreaDiscoveryEnabled: cfgAtStart.discovery?.wideArea?.enabled === true,
+    tailscaleMode,
     logDiscovery,
   });
   bonjourStop = discovery.bonjourStop;

src/plugins/runtime/index.ts

@@ -40,6 +40,7 @@ import { removeAckReactionAfterReply, shouldAckReaction } from "../../channels/a
 import { resolveCommandAuthorizedFromAuthorizers } from "../../channels/command-gating.js";
 import { recordInboundSession } from "../../channels/session.js";
 import { discordMessageActions } from "../../channels/plugins/actions/discord.js";
+import { signalMessageActions } from "../../channels/plugins/actions/signal.js";
 import { telegramMessageActions } from "../../channels/plugins/actions/telegram.js";
 import { createWhatsAppLoginTool } from "../../channels/plugins/agent-tools/whatsapp-login.js";
 import { monitorWebChannel } from "../../channels/web/index.js";
@@ -269,6 +270,7 @@ export function createPluginRuntime(): PluginRuntime {
         probeSignal,
         sendMessageSignal,
         monitorSignalProvider,
+        messageActions: signalMessageActions,
       },
       imessage: {
         monitorIMessageProvider,

src/plugins/runtime/types.ts

@@ -123,6 +123,8 @@ type TelegramMessageActions =
 type ProbeSignal = typeof import("../../signal/probe.js").probeSignal;
 type SendMessageSignal = typeof import("../../signal/send.js").sendMessageSignal;
 type MonitorSignalProvider = typeof import("../../signal/index.js").monitorSignalProvider;
+type SignalMessageActions =
+  typeof import("../../channels/plugins/actions/signal.js").signalMessageActions;
 type MonitorIMessageProvider = typeof import("../../imessage/monitor.js").monitorIMessageProvider;
 type ProbeIMessage = typeof import("../../imessage/probe.js").probeIMessage;
 type SendMessageIMessage = typeof import("../../imessage/send.js").sendMessageIMessage;
@@ -278,6 +280,7 @@ export type PluginRuntime = {
       probeSignal: ProbeSignal;
       sendMessageSignal: SendMessageSignal;
       monitorSignalProvider: MonitorSignalProvider;
+      messageActions: SignalMessageActions;
     };
     imessage: {
       monitorIMessageProvider: MonitorIMessageProvider;

src/signal/index.ts

@@ -1,3 +1,5 @@
 export { monitorSignalProvider } from "./monitor.js";
 export { probeSignal } from "./probe.js";
 export { sendMessageSignal } from "./send.js";
+export { sendReactionSignal, removeReactionSignal } from "./send-reactions.js";
+export { resolveSignalReactionLevel } from "./reaction-level.js";

src/signal/reaction-level.ts

@@ -0,0 +1,71 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import { resolveSignalAccount } from "./accounts.js";
+
+export type SignalReactionLevel = "off" | "ack" | "minimal" | "extensive";
+
+export type ResolvedSignalReactionLevel = {
+  level: SignalReactionLevel;
+  /** Whether ACK reactions (e.g., 👀 when processing) are enabled. */
+  ackEnabled: boolean;
+  /** Whether agent-controlled reactions are enabled. */
+  agentReactionsEnabled: boolean;
+  /** Guidance level for agent reactions (minimal = sparse, extensive = liberal). */
+  agentReactionGuidance?: "minimal" | "extensive";
+};
+
+/**
+ * Resolve the effective reaction level and its implications for Signal.
+ *
+ * Levels:
+ * - "off": No reactions at all
+ * - "ack": Only automatic ack reactions (👀 when processing), no agent reactions
+ * - "minimal": Agent can react, but sparingly (default)
+ * - "extensive": Agent can react liberally
+ */
+export function resolveSignalReactionLevel(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string;
+}): ResolvedSignalReactionLevel {
+  const account = resolveSignalAccount({
+    cfg: params.cfg,
+    accountId: params.accountId,
+  });
+  const level = (account.config.reactionLevel ?? "minimal") as SignalReactionLevel;
+
+  switch (level) {
+    case "off":
+      return {
+        level,
+        ackEnabled: false,
+        agentReactionsEnabled: false,
+      };
+    case "ack":
+      return {
+        level,
+        ackEnabled: true,
+        agentReactionsEnabled: false,
+      };
+    case "minimal":
+      return {
+        level,
+        ackEnabled: false,
+        agentReactionsEnabled: true,
+        agentReactionGuidance: "minimal",
+      };
+    case "extensive":
+      return {
+        level,
+        ackEnabled: false,
+        agentReactionsEnabled: true,
+        agentReactionGuidance: "extensive",
+      };
+    default:
+      // Fallback to minimal behavior
+      return {
+        level: "minimal",
+        ackEnabled: false,
+        agentReactionsEnabled: true,
+        agentReactionGuidance: "minimal",
+      };
+  }
+}

src/signal/send-reactions.test.ts

@@ -0,0 +1,69 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const rpcMock = vi.fn();
+const loadSendReactions = async () => await import("./send-reactions.js");
+
+vi.mock("../config/config.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../config/config.js")>();
+  return {
+    ...actual,
+    loadConfig: () => ({}),
+  };
+});
+
+vi.mock("./accounts.js", () => ({
+  resolveSignalAccount: () => ({
+    accountId: "default",
+    enabled: true,
+    baseUrl: "http://signal.local",
+    configured: true,
+    config: { account: "+15550001111" },
+  }),
+}));
+
+vi.mock("./client.js", () => ({
+  signalRpcRequest: (...args: unknown[]) => rpcMock(...args),
+}));
+
+describe("sendReactionSignal", () => {
+  beforeEach(() => {
+    rpcMock.mockReset().mockResolvedValue({ timestamp: 123 });
+    vi.resetModules();
+  });
+
+  it("uses recipients array and targetAuthor for uuid dms", async () => {
+    const { sendReactionSignal } = await loadSendReactions();
+    await sendReactionSignal("uuid:123e4567-e89b-12d3-a456-426614174000", 123, "🔥");
+
+    const params = rpcMock.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(rpcMock).toHaveBeenCalledWith("sendReaction", expect.any(Object), expect.any(Object));
+    expect(params.recipients).toEqual(["123e4567-e89b-12d3-a456-426614174000"]);
+    expect(params.groupIds).toBeUndefined();
+    expect(params.targetAuthor).toBe("123e4567-e89b-12d3-a456-426614174000");
+    expect(params).not.toHaveProperty("recipient");
+    expect(params).not.toHaveProperty("groupId");
+  });
+
+  it("uses groupIds array and maps targetAuthorUuid", async () => {
+    const { sendReactionSignal } = await loadSendReactions();
+    await sendReactionSignal("", 123, "✅", {
+      groupId: "group-id",
+      targetAuthorUuid: "uuid:123e4567-e89b-12d3-a456-426614174000",
+    });
+
+    const params = rpcMock.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(params.recipients).toBeUndefined();
+    expect(params.groupIds).toEqual(["group-id"]);
+    expect(params.targetAuthor).toBe("123e4567-e89b-12d3-a456-426614174000");
+  });
+
+  it("defaults targetAuthor to recipient for removals", async () => {
+    const { removeReactionSignal } = await loadSendReactions();
+    await removeReactionSignal("+15551230000", 456, "❌");
+
+    const params = rpcMock.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(params.recipients).toEqual(["+15551230000"]);
+    expect(params.targetAuthor).toBe("+15551230000");
+    expect(params.remove).toBe(true);
+  });
+});

src/signal/send-reactions.ts

@@ -0,0 +1,195 @@
+/**
+ * Signal reactions via signal-cli JSON-RPC API
+ */
+
+import { loadConfig } from "../config/config.js";
+import { resolveSignalAccount } from "./accounts.js";
+import { signalRpcRequest } from "./client.js";
+
+export type SignalReactionOpts = {
+  baseUrl?: string;
+  account?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  targetAuthor?: string;
+  targetAuthorUuid?: string;
+  groupId?: string;
+};
+
+export type SignalReactionResult = {
+  ok: boolean;
+  timestamp?: number;
+};
+
+function normalizeSignalId(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  return trimmed.replace(/^signal:/i, "").trim();
+}
+
+function normalizeSignalUuid(raw: string): string {
+  const trimmed = normalizeSignalId(raw);
+  if (!trimmed) return "";
+  if (trimmed.toLowerCase().startsWith("uuid:")) {
+    return trimmed.slice("uuid:".length).trim();
+  }
+  return trimmed;
+}
+
+function resolveTargetAuthorParams(params: {
+  targetAuthor?: string;
+  targetAuthorUuid?: string;
+  fallback?: string;
+}): { targetAuthor?: string } {
+  const candidates = [params.targetAuthor, params.targetAuthorUuid, params.fallback];
+  for (const candidate of candidates) {
+    const raw = candidate?.trim();
+    if (!raw) continue;
+    const normalized = normalizeSignalUuid(raw);
+    if (normalized) return { targetAuthor: normalized };
+  }
+  return {};
+}
+
+function resolveReactionRpcContext(
+  opts: SignalReactionOpts,
+  accountInfo?: ReturnType<typeof resolveSignalAccount>,
+) {
+  const hasBaseUrl = Boolean(opts.baseUrl?.trim());
+  const hasAccount = Boolean(opts.account?.trim());
+  const resolvedAccount =
+    accountInfo ||
+    (!hasBaseUrl || !hasAccount
+      ? resolveSignalAccount({
+          cfg: loadConfig(),
+          accountId: opts.accountId,
+        })
+      : undefined);
+  const baseUrl = opts.baseUrl?.trim() || resolvedAccount?.baseUrl;
+  if (!baseUrl) {
+    throw new Error("Signal base URL is required");
+  }
+  const account = opts.account?.trim() || resolvedAccount?.config.account?.trim();
+  return { baseUrl, account };
+}
+
+/**
+ * Send a Signal reaction to a message
+ * @param recipient - UUID or E.164 phone number of the message author
+ * @param targetTimestamp - Message ID (timestamp) to react to
+ * @param emoji - Emoji to react with
+ * @param opts - Optional account/connection overrides
+ */
+export async function sendReactionSignal(
+  recipient: string,
+  targetTimestamp: number,
+  emoji: string,
+  opts: SignalReactionOpts = {},
+): Promise<SignalReactionResult> {
+  const accountInfo = resolveSignalAccount({
+    cfg: loadConfig(),
+    accountId: opts.accountId,
+  });
+  const { baseUrl, account } = resolveReactionRpcContext(opts, accountInfo);
+
+  const normalizedRecipient = normalizeSignalUuid(recipient);
+  const groupId = opts.groupId?.trim();
+  if (!normalizedRecipient && !groupId) {
+    throw new Error("Recipient or groupId is required for Signal reaction");
+  }
+  if (!Number.isFinite(targetTimestamp) || targetTimestamp <= 0) {
+    throw new Error("Valid targetTimestamp is required for Signal reaction");
+  }
+  if (!emoji?.trim()) {
+    throw new Error("Emoji is required for Signal reaction");
+  }
+
+  const targetAuthorParams = resolveTargetAuthorParams({
+    targetAuthor: opts.targetAuthor,
+    targetAuthorUuid: opts.targetAuthorUuid,
+    fallback: normalizedRecipient,
+  });
+  if (groupId && !targetAuthorParams.targetAuthor) {
+    throw new Error("targetAuthor is required for group reactions");
+  }
+
+  const params: Record<string, unknown> = {
+    emoji: emoji.trim(),
+    targetTimestamp,
+    ...targetAuthorParams,
+  };
+  if (normalizedRecipient) params.recipients = [normalizedRecipient];
+  if (groupId) params.groupIds = [groupId];
+  if (account) params.account = account;
+
+  const result = await signalRpcRequest<{ timestamp?: number }>("sendReaction", params, {
+    baseUrl,
+    timeoutMs: opts.timeoutMs,
+  });
+
+  return {
+    ok: true,
+    timestamp: result?.timestamp,
+  };
+}
+
+/**
+ * Remove a Signal reaction from a message
+ * @param recipient - UUID or E.164 phone number of the message author
+ * @param targetTimestamp - Message ID (timestamp) to remove reaction from
+ * @param emoji - Emoji to remove
+ * @param opts - Optional account/connection overrides
+ */
+export async function removeReactionSignal(
+  recipient: string,
+  targetTimestamp: number,
+  emoji: string,
+  opts: SignalReactionOpts = {},
+): Promise<SignalReactionResult> {
+  const accountInfo = resolveSignalAccount({
+    cfg: loadConfig(),
+    accountId: opts.accountId,
+  });
+  const { baseUrl, account } = resolveReactionRpcContext(opts, accountInfo);
+
+  const normalizedRecipient = normalizeSignalUuid(recipient);
+  const groupId = opts.groupId?.trim();
+  if (!normalizedRecipient && !groupId) {
+    throw new Error("Recipient or groupId is required for Signal reaction removal");
+  }
+  if (!Number.isFinite(targetTimestamp) || targetTimestamp <= 0) {
+    throw new Error("Valid targetTimestamp is required for Signal reaction removal");
+  }
+  if (!emoji?.trim()) {
+    throw new Error("Emoji is required for Signal reaction removal");
+  }
+
+  const targetAuthorParams = resolveTargetAuthorParams({
+    targetAuthor: opts.targetAuthor,
+    targetAuthorUuid: opts.targetAuthorUuid,
+    fallback: normalizedRecipient,
+  });
+  if (groupId && !targetAuthorParams.targetAuthor) {
+    throw new Error("targetAuthor is required for group reaction removal");
+  }
+
+  const params: Record<string, unknown> = {
+    emoji: emoji.trim(),
+    targetTimestamp,
+    remove: true,
+    ...targetAuthorParams,
+  };
+  if (normalizedRecipient) params.recipients = [normalizedRecipient];
+  if (groupId) params.groupIds = [groupId];
+  if (account) params.account = account;
+
+  const result = await signalRpcRequest<{ timestamp?: number }>("sendReaction", params, {
+    baseUrl,
+    timeoutMs: opts.timeoutMs,
+  });
+
+  return {
+    ok: true,
+    timestamp: result?.timestamp,
+  };
+}

src/tts/tts.test.ts

@@ -4,7 +4,7 @@ import { completeSimple } from "@mariozechner/pi-ai";
 
 import { getApiKeyForModel } from "../agents/model-auth.js";
 import { resolveModel } from "../agents/pi-embedded-runner/model.js";
-import { _test, getTtsProvider, resolveTtsConfig } from "./tts.js";
+import * as tts from "./tts.js";
 
 vi.mock("@mariozechner/pi-ai", () => ({
   completeSimple: vi.fn(),
@@ -37,6 +37,8 @@ vi.mock("../agents/model-auth.js", () => ({
   requireApiKey: vi.fn((auth: { apiKey?: string }) => auth.apiKey ?? ""),
 }));
 
+const { _test, resolveTtsConfig, maybeApplyTtsToPayload, getTtsProvider } = tts;
+
 const {
   isValidVoiceId,
   isValidOpenAIVoice,
@@ -431,4 +433,129 @@ describe("tts", () => {
       );
     });
   });
+
+  describe("maybeApplyTtsToPayload", () => {
+    const baseCfg = {
+      agents: { defaults: { model: { primary: "openai/gpt-4o-mini" } } },
+      messages: {
+        tts: {
+          auto: "inbound",
+          provider: "openai",
+          openai: { apiKey: "test-key", model: "gpt-4o-mini-tts", voice: "alloy" },
+        },
+      },
+    };
+
+    it("skips auto-TTS when inbound audio gating is on and the message is not audio", async () => {
+      const prevPrefs = process.env.CLAWDBOT_TTS_PREFS;
+      process.env.CLAWDBOT_TTS_PREFS = `/tmp/tts-test-${Date.now()}.json`;
+      const originalFetch = globalThis.fetch;
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        arrayBuffer: async () => new ArrayBuffer(1),
+      }));
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const payload = { text: "Hello world" };
+      const result = await maybeApplyTtsToPayload({
+        payload,
+        cfg: baseCfg,
+        kind: "final",
+        inboundAudio: false,
+      });
+
+      expect(result).toBe(payload);
+      expect(fetchMock).not.toHaveBeenCalled();
+
+      globalThis.fetch = originalFetch;
+      process.env.CLAWDBOT_TTS_PREFS = prevPrefs;
+    });
+
+    it("attempts auto-TTS when inbound audio gating is on and the message is audio", async () => {
+      const prevPrefs = process.env.CLAWDBOT_TTS_PREFS;
+      process.env.CLAWDBOT_TTS_PREFS = `/tmp/tts-test-${Date.now()}.json`;
+      const originalFetch = globalThis.fetch;
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        arrayBuffer: async () => new ArrayBuffer(1),
+      }));
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const result = await maybeApplyTtsToPayload({
+        payload: { text: "Hello world" },
+        cfg: baseCfg,
+        kind: "final",
+        inboundAudio: true,
+      });
+
+      expect(result.mediaUrl).toBeDefined();
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      globalThis.fetch = originalFetch;
+      process.env.CLAWDBOT_TTS_PREFS = prevPrefs;
+    });
+
+    it("skips auto-TTS in tagged mode unless a tts tag is present", async () => {
+      const prevPrefs = process.env.CLAWDBOT_TTS_PREFS;
+      process.env.CLAWDBOT_TTS_PREFS = `/tmp/tts-test-${Date.now()}.json`;
+      const originalFetch = globalThis.fetch;
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        arrayBuffer: async () => new ArrayBuffer(1),
+      }));
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const cfg = {
+        ...baseCfg,
+        messages: {
+          ...baseCfg.messages,
+          tts: { ...baseCfg.messages.tts, auto: "tagged" },
+        },
+      };
+
+      const payload = { text: "Hello world" };
+      const result = await maybeApplyTtsToPayload({
+        payload,
+        cfg,
+        kind: "final",
+      });
+
+      expect(result).toBe(payload);
+      expect(fetchMock).not.toHaveBeenCalled();
+
+      globalThis.fetch = originalFetch;
+      process.env.CLAWDBOT_TTS_PREFS = prevPrefs;
+    });
+
+    it("runs auto-TTS in tagged mode when tags are present", async () => {
+      const prevPrefs = process.env.CLAWDBOT_TTS_PREFS;
+      process.env.CLAWDBOT_TTS_PREFS = `/tmp/tts-test-${Date.now()}.json`;
+      const originalFetch = globalThis.fetch;
+      const fetchMock = vi.fn(async () => ({
+        ok: true,
+        arrayBuffer: async () => new ArrayBuffer(1),
+      }));
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const cfg = {
+        ...baseCfg,
+        messages: {
+          ...baseCfg.messages,
+          tts: { ...baseCfg.messages.tts, auto: "tagged" },
+        },
+      };
+
+      const result = await maybeApplyTtsToPayload({
+        payload: { text: "[[tts:text]]Hello world[[/tts:text]]" },
+        cfg,
+        kind: "final",
+      });
+
+      expect(result.mediaUrl).toBeDefined();
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      globalThis.fetch = originalFetch;
+      process.env.CLAWDBOT_TTS_PREFS = prevPrefs;
+    });
+  });
 });

src/tts/tts.ts

@@ -20,6 +20,7 @@ import type { ChannelId } from "../channels/plugins/types.js";
 import type { ClawdbotConfig } from "../config/config.js";
 import type {
   TtsConfig,
+  TtsAutoMode,
   TtsMode,
   TtsProvider,
   TtsModelOverrideConfig,
@@ -75,8 +76,10 @@ const DEFAULT_OUTPUT = {
   voiceCompatible: false,
 };
 
+const TTS_AUTO_MODES = new Set<TtsAutoMode>(["off", "always", "inbound", "tagged"]);
+
 export type ResolvedTtsConfig = {
-  enabled: boolean;
+  auto: TtsAutoMode;
   mode: TtsMode;
   provider: TtsProvider;
   providerSource: "config" | "default";
@@ -123,6 +126,7 @@ export type ResolvedTtsConfig = {
 
 type TtsUserPrefs = {
   tts?: {
+    auto?: TtsAutoMode;
     enabled?: boolean;
     provider?: TtsProvider;
     maxLength?: number;
@@ -161,6 +165,7 @@ type TtsDirectiveOverrides = {
 type TtsDirectiveParseResult = {
   cleanedText: string;
   ttsText?: string;
+  hasDirective: boolean;
   overrides: TtsDirectiveOverrides;
   warnings: string[];
 };
@@ -187,6 +192,15 @@ type TtsStatusEntry = {
 
 let lastTtsAttempt: TtsStatusEntry | undefined;
 
+export function normalizeTtsAutoMode(value: unknown): TtsAutoMode | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  if (TTS_AUTO_MODES.has(normalized as TtsAutoMode)) {
+    return normalized as TtsAutoMode;
+  }
+  return undefined;
+}
+
 function resolveModelOverridePolicy(
   overrides: TtsModelOverrideConfig | undefined,
 ): ResolvedTtsModelOverrides {
@@ -220,8 +234,9 @@ export function resolveTtsConfig(cfg: ClawdbotConfig): ResolvedTtsConfig {
   const raw: TtsConfig = cfg.messages?.tts ?? {};
   const providerSource = raw.provider ? "config" : "default";
   const edgeOutputFormat = raw.edge?.outputFormat?.trim();
+  const auto = normalizeTtsAutoMode(raw.auto) ?? (raw.enabled ? "always" : "off");
   return {
-    enabled: raw.enabled ?? false,
+    auto,
     mode: raw.mode ?? "final",
     provider: raw.provider ?? "edge",
     providerSource,
@@ -279,17 +294,48 @@ export function resolveTtsPrefsPath(config: ResolvedTtsConfig): string {
   return path.join(CONFIG_DIR, "settings", "tts.json");
 }
 
+function resolveTtsAutoModeFromPrefs(prefs: TtsUserPrefs): TtsAutoMode | undefined {
+  const auto = normalizeTtsAutoMode(prefs.tts?.auto);
+  if (auto) return auto;
+  if (typeof prefs.tts?.enabled === "boolean") {
+    return prefs.tts.enabled ? "always" : "off";
+  }
+  return undefined;
+}
+
+export function resolveTtsAutoMode(params: {
+  config: ResolvedTtsConfig;
+  prefsPath: string;
+  sessionAuto?: string;
+}): TtsAutoMode {
+  const sessionAuto = normalizeTtsAutoMode(params.sessionAuto);
+  if (sessionAuto) return sessionAuto;
+  const prefsAuto = resolveTtsAutoModeFromPrefs(readPrefs(params.prefsPath));
+  if (prefsAuto) return prefsAuto;
+  return params.config.auto;
+}
+
 export function buildTtsSystemPromptHint(cfg: ClawdbotConfig): string | undefined {
   const config = resolveTtsConfig(cfg);
   const prefsPath = resolveTtsPrefsPath(config);
-  if (!isTtsEnabled(config, prefsPath)) return undefined;
+  const autoMode = resolveTtsAutoMode({ config, prefsPath });
+  if (autoMode === "off") return undefined;
   const maxLength = getTtsMaxLength(prefsPath);
   const summarize = isSummarizationEnabled(prefsPath) ? "on" : "off";
+  const autoHint =
+    autoMode === "inbound"
+      ? "Only use TTS when the user's last message includes audio/voice."
+      : autoMode === "tagged"
+        ? "Only use TTS when you include [[tts]] or [[tts:text]] tags."
+        : undefined;
   return [
     "Voice (TTS) is enabled.",
+    autoHint,
     `Keep spoken text ≤${maxLength} chars to avoid auto-summary (summary ${summarize}).`,
     "Use [[tts:...]] and optional [[tts:text]]...[[/tts:text]] to control voice/expressiveness.",
-  ].join("\n");
+  ]
+    .filter(Boolean)
+    .join("\n");
 }
 
 function readPrefs(prefsPath: string): TtsUserPrefs {
@@ -323,16 +369,25 @@ function updatePrefs(prefsPath: string, update: (prefs: TtsUserPrefs) => void):
   atomicWriteFileSync(prefsPath, JSON.stringify(prefs, null, 2));
 }
 
-export function isTtsEnabled(config: ResolvedTtsConfig, prefsPath: string): boolean {
-  const prefs = readPrefs(prefsPath);
-  if (prefs.tts?.enabled !== undefined) return prefs.tts.enabled === true;
-  return config.enabled;
+export function isTtsEnabled(
+  config: ResolvedTtsConfig,
+  prefsPath: string,
+  sessionAuto?: string,
+): boolean {
+  return resolveTtsAutoMode({ config, prefsPath, sessionAuto }) !== "off";
+}
+
+export function setTtsAutoMode(prefsPath: string, mode: TtsAutoMode): void {
+  updatePrefs(prefsPath, (prefs) => {
+    const next = { ...prefs.tts };
+    delete next.enabled;
+    next.auto = mode;
+    prefs.tts = next;
+  });
 }
 
 export function setTtsEnabled(prefsPath: string, enabled: boolean): void {
-  updatePrefs(prefsPath, (prefs) => {
-    prefs.tts = { ...prefs.tts, enabled };
-  });
+  setTtsAutoMode(prefsPath, enabled ? "always" : "off");
 }
 
 export function getTtsProvider(config: ResolvedTtsConfig, prefsPath: string): TtsProvider {
@@ -485,15 +540,17 @@ function parseTtsDirectives(
   policy: ResolvedTtsModelOverrides,
 ): TtsDirectiveParseResult {
   if (!policy.enabled) {
-    return { cleanedText: text, overrides: {}, warnings: [] };
+    return { cleanedText: text, overrides: {}, warnings: [], hasDirective: false };
   }
 
   const overrides: TtsDirectiveOverrides = {};
   const warnings: string[] = [];
   let cleanedText = text;
+  let hasDirective = false;
 
   const blockRegex = /\[\[tts:text\]\]([\s\S]*?)\[\[\/tts:text\]\]/gi;
   cleanedText = cleanedText.replace(blockRegex, (_match, inner: string) => {
+    hasDirective = true;
     if (policy.allowText && overrides.ttsText == null) {
       overrides.ttsText = inner.trim();
     }
@@ -502,6 +559,7 @@ function parseTtsDirectives(
 
   const directiveRegex = /\[\[tts:([^\]]+)\]\]/gi;
   cleanedText = cleanedText.replace(directiveRegex, (_match, body: string) => {
+    hasDirective = true;
     const tokens = body.split(/\s+/).filter(Boolean);
     for (const token of tokens) {
       const eqIndex = token.indexOf("=");
@@ -672,6 +730,7 @@ function parseTtsDirectives(
   return {
     cleanedText,
     ttsText: overrides.ttsText,
+    hasDirective,
     overrides,
     warnings,
   };
@@ -1156,13 +1215,17 @@ export async function maybeApplyTtsToPayload(params: {
   cfg: ClawdbotConfig;
   channel?: string;
   kind?: "tool" | "block" | "final";
+  inboundAudio?: boolean;
+  ttsAuto?: string;
 }): Promise<ReplyPayload> {
   const config = resolveTtsConfig(params.cfg);
   const prefsPath = resolveTtsPrefsPath(config);
-  if (!isTtsEnabled(config, prefsPath)) return params.payload;
-
-  const mode = config.mode ?? "final";
-  if (mode === "final" && params.kind && params.kind !== "final") return params.payload;
+  const autoMode = resolveTtsAutoMode({
+    config,
+    prefsPath,
+    sessionAuto: params.ttsAuto,
+  });
+  if (autoMode === "off") return params.payload;
 
   const text = params.payload.text ?? "";
   const directives = parseTtsDirectives(text, config.modelOverrides);
@@ -1183,6 +1246,12 @@ export async function maybeApplyTtsToPayload(params: {
           text: visibleText.length > 0 ? visibleText : undefined,
         };
 
+  if (autoMode === "tagged" && !directives.hasDirective) return nextPayload;
+  if (autoMode === "inbound" && params.inboundAudio !== true) return nextPayload;
+
+  const mode = config.mode ?? "final";
+  if (mode === "final" && params.kind && params.kind !== "final") return nextPayload;
+
   if (!ttsText.trim()) return nextPayload;
   if (params.payload.mediaUrl || (params.payload.mediaUrls?.length ?? 0) > 0) return nextPayload;
   if (text.includes("MEDIA:")) return nextPayload;
@@ -1197,7 +1266,7 @@ export async function maybeApplyTtsToPayload(params: {
       logVerbose(
         `TTS: skipping long text (${textForAudio.length} > ${maxLength}), summarization disabled.`,
       );
-      return params.payload;
+      return nextPayload;
     }
 
     try {
@@ -1219,7 +1288,7 @@ export async function maybeApplyTtsToPayload(params: {
     } catch (err) {
       const error = err as Error;
       logVerbose(`TTS: summarization failed: ${error.message}`);
-      return params.payload;
+      return nextPayload;
     }
   }
 

src/types/node-edge-tts.d.ts

@@ -0,0 +1,18 @@
+declare module "node-edge-tts" {
+  export type EdgeTTSOptions = {
+    voice?: string;
+    lang?: string;
+    outputFormat?: string;
+    saveSubtitles?: boolean;
+    proxy?: string;
+    rate?: string;
+    pitch?: string;
+    volume?: string;
+    timeout?: number;
+  };
+
+  export class EdgeTTS {
+    constructor(options?: EdgeTTSOptions);
+    ttsPromise(text: string, outputPath: string): Promise<void>;
+  }
+}

src/web/inbound.media.test.ts

@@ -127,9 +127,9 @@ describe("web inbound media saves with extension", () => {
     realSock.ev.emit("messages.upsert", upsert);
 
     // Allow a brief window for the async handler to fire on slower hosts.
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 50; i++) {
       if (onMessage.mock.calls.length > 0) break;
-      await new Promise((resolve) => setTimeout(resolve, 5));
+      await new Promise((resolve) => setTimeout(resolve, 10));
     }
 
     expect(onMessage).toHaveBeenCalledTimes(1);
@@ -178,9 +178,9 @@ describe("web inbound media saves with extension", () => {
 
     realSock.ev.emit("messages.upsert", upsert);
 
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 50; i++) {
       if (onMessage.mock.calls.length > 0) break;
-      await new Promise((resolve) => setTimeout(resolve, 5));
+      await new Promise((resolve) => setTimeout(resolve, 10));
     }
 
     expect(onMessage).toHaveBeenCalledTimes(1);
@@ -218,9 +218,9 @@ describe("web inbound media saves with extension", () => {
 
     realSock.ev.emit("messages.upsert", upsert);
 
-    for (let i = 0; i < 10; i++) {
+    for (let i = 0; i < 50; i++) {
       if (onMessage.mock.calls.length > 0) break;
-      await new Promise((resolve) => setTimeout(resolve, 5));
+      await new Promise((resolve) => setTimeout(resolve, 10));
     }
 
     expect(onMessage).toHaveBeenCalledTimes(1);

ui/src/ui/app-gateway.ts

@@ -134,10 +134,7 @@ export function connectGateway(host: GatewayHost) {
     },
     onClose: ({ code, reason }) => {
       host.connected = false;
-      // Code 1012 = Service Restart (expected during config saves, don't show as error)
-      if (code !== 1012) {
-        host.lastError = `disconnected (${code}): ${reason || "no reason"}`;
-      }
+      host.lastError = `disconnected (${code}): ${reason || "no reason"}`;
     },
     onEvent: (evt) => handleGatewayEvent(host, evt),
     onGap: ({ expected, received }) => {

ui/src/ui/views/config.ts

@@ -234,9 +234,8 @@ export function renderConfig(props: ConfigProps) {
   const hasChanges = props.formMode === "form" ? diff.length > 0 : hasRawChanges;
 
   // Save/apply buttons require actual changes to be enabled
-  // Note: formUnsafe warns about unsupported schema paths but shouldn't block saving
   const canSaveForm =
-    Boolean(props.formValue) && !props.loading;
+    Boolean(props.formValue) && !props.loading && !formUnsafe;
   const canSave =
     props.connected &&
     !props.saving &&