feat: Add granular notification control with per-channel toggles (#27) (#29)

Add per-channel notification control via /notification skill and VoiceGate
hook enhancement. Voice and desktop channels can be independently toggled
on/off through settings.json, with VoiceGate blocking all curl commands
when voice is disabled.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: virtualian

Releases/v3.0/.claude/hooks/VoiceGate.hook.ts

@@ -1,28 +1,31 @@
 #!/usr/bin/env bun
 /**
- * VoiceGate.hook.ts - Block Voice Curls from Subagents (PreToolUse)
+ * VoiceGate.hook.ts - Voice Notification Gate (PreToolUse)
  *
  * PURPOSE:
- * Prevents background agents / subagents from sending voice notifications.
- * Only the main terminal session (identified by having a kitty-sessions file)
- * is allowed to curl the voice server at localhost:8888.
+ * Controls voice notification delivery via two mechanisms:
+ * 1. Per-channel toggle: When notifications.voice is false in settings.json,
+ *    ALL voice curls are blocked — zero noise, zero execution.
+ * 2. Subagent blocking: When voice is enabled, only the main terminal session
+ *    can send voice curls. Subagents are silently blocked.
  *
  * ROOT CAUSE THIS FIXES:
- * Subagents inherit full PAI context (CLAUDE.md → SKILL.md → Algorithm),
- * which mandates voice curls at every phase. Without this gate, every
- * spawned agent triggers voice announcements — flooding the voice server.
+ * - Issue #27: No granular notification control — curls fire unconditionally
+ * - Subagent flooding: Spawned agents inherit Algorithm context and fire curls
  *
  * TRIGGER: PreToolUse (matcher: Bash)
  *
  * DECISION LOGIC:
  * 1. Command doesn't contain "localhost:8888" → PASS (not a voice curl)
- * 2. Command contains "localhost:8888" AND is main session → PASS
- * 3. Command contains "localhost:8888" AND is NOT main session → BLOCK
+ * 2. notifications.voice is false in settings.json → BLOCK (user disabled voice)
+ * 3. Command contains "localhost:8888" AND is main session → PASS
+ * 4. Command contains "localhost:8888" AND is NOT main session → BLOCK
  *
- * PERFORMANCE: <5ms. Fast-path exit for non-voice commands.
+ * PERFORMANCE: <5ms. Fast-path exit for non-voice commands. Settings read
+ * is synchronous file I/O but only triggered for voice curls (~7 per session).
  */
 
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
@@ -34,6 +37,27 @@ interface HookInput {
   session_id: string;
 }
 
+function isVoiceEnabled(): boolean {
+  // Read notifications.voice from settings.json
+  // Supports two formats:
+  //   Boolean: { "voice": true }
+  //   Object:  { "voice": { "enabled": true } }
+  // Default to true (voice enabled) if setting is missing or unreadable
+  const paiDir = process.env.PAI_DIR || join(homedir(), '.claude');
+  const settingsPath = join(paiDir, 'settings.json');
+  try {
+    if (!existsSync(settingsPath)) return true;
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    const voice = settings?.notifications?.voice;
+    if (voice === undefined || voice === null) return true; // Missing → enabled
+    if (typeof voice === 'boolean') return voice;           // Boolean format
+    if (typeof voice === 'object') return voice.enabled !== false; // Object format
+    return true; // Unknown format → default enabled
+  } catch {
+    return true; // Can't read settings → default to enabled
+  }
+}
+
 function isMainSession(sessionId: string): boolean {
   // Terminal detection: if we're in a recognized terminal, this is a main session.
   // Subagents spawned by Task tool don't inherit terminal environment variables,
@@ -83,7 +107,16 @@ async function main() {
     return;
   }
 
-  // It's a voice curl — check if main session
+  // It's a voice curl — check if voice notifications are enabled
+  if (!isVoiceEnabled()) {
+    console.log(JSON.stringify({
+      decision: "block",
+      reason: "Voice notifications are disabled (notifications.voice = false in settings.json). Use /notification voice on to re-enable."
+    }));
+    return;
+  }
+
+  // Voice is enabled — check if main session
   if (isMainSession(input.session_id)) {
     console.log(JSON.stringify({ continue: true }));
     return;

Releases/v3.0/.claude/settings.json

@@ -802,6 +802,12 @@
   },
   "max_tokens": 16000,
   "notifications": {
+    "voice": {
+      "enabled": true
+    },
+    "desktop": {
+      "enabled": true
+    },
     "ntfy": {
       "enabled": true,
       "topic": "${NTFY_TOPIC}",

Releases/v3.0/.claude/skills/Notification/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: Notification
+description: Per-channel notification control. USE WHEN notification, notifications, voice on, voice off, mute, unmute, notification status.
+---
+
+## Customization
+
+**Before executing, check for user customizations at:**
+`~/.claude/skills/PAI/USER/SKILLCUSTOMIZATIONS/Notification/`
+
+If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.
+
+---
+
+## Slash Command Interface
+
+This skill implements `/notification` with per-channel toggle control:
+
+```
+/notification voice on       # Enable voice (curl) notifications
+/notification voice off      # Disable voice notifications — suppresses ALL curl calls
+/notification desktop on     # Enable desktop notifications
+/notification desktop off    # Disable desktop notifications
+/notification status         # Show current notification channel states
+/notification all off        # Disable all notification channels
+/notification all on         # Enable all notification channels
+```
+
+---
+
+## Workflow Routing
+
+**When user requests toggling voice notifications:**
+Examples: "/notification voice on", "/notification voice off", "turn off voice", "mute voice", "unmute voice", "disable voice notifications", "enable voice", "silence the curls", "stop voice announcements"
+-> **Action:** Read `~/.claude/settings.json`, set `notifications.voice` to `true` or `false`, write back. Confirm the change.
+-> **Feedback:** "Voice notifications [enabled/disabled]. Phase announcement curls will [fire normally/be suppressed]."
+
+**When user requests toggling desktop notifications:**
+Examples: "/notification desktop on", "/notification desktop off", "turn off desktop", "mute desktop", "disable desktop notifications"
+-> **Action:** Read `~/.claude/settings.json`, set `notifications.desktop` to `true` or `false`, write back. Confirm the change.
+-> **Feedback:** "Desktop notifications [enabled/disabled]."
+
+**When user requests notification status:**
+Examples: "/notification status", "notification status", "what notifications are on", "show notification settings"
+-> **Action:** Read `~/.claude/settings.json` and display current state of all notification channels.
+-> **Output format:**
+```
+Notification Channel Status:
+  Voice:   [ON/OFF]  — Phase announcement curls
+  Desktop: [ON/OFF]  — Desktop alerts
+  ntfy:    [ON/OFF]  — Push notifications (mobile)
+  Discord: [ON/OFF]  — Discord webhook
+```
+
+**When user requests toggling all notifications:**
+Examples: "/notification all off", "/notification all on", "mute all", "unmute all", "silence everything", "turn on all notifications"
+-> **Action:** Read `~/.claude/settings.json`, set `notifications.voice` and `notifications.desktop` to the requested state, write back. Confirm the change.
+-> **Feedback:** "All notification channels [enabled/disabled]."
+
+---
+
+## Settings Location
+
+Notification state is stored in `~/.claude/settings.json` under the `notifications` key:
+
+```json
+{
+  "notifications": {
+    "voice": { "enabled": true },
+    "desktop": { "enabled": true },
+    "ntfy": { "enabled": true, ... },
+    "discord": { "enabled": true, ... },
+    ...
+  }
+}
+```
+
+- `voice.enabled` (boolean): Controls phase announcement curl commands. When `false`, VoiceGate.hook.ts blocks all curls to localhost:8888.
+- `desktop.enabled` (boolean): Controls desktop notification delivery.
+
+Both boolean format (`"voice": true`) and object format (`"voice": { "enabled": true }`) are supported for backwards compatibility.
+
+Settings persist across sessions automatically since they live in settings.json.
+
+---
+
+## Implementation Details
+
+### Voice Suppression Mechanism
+
+The voice toggle works through `VoiceGate.hook.ts` (PreToolUse hook on Bash):
+
+1. Algorithm emits a `curl -s -X POST http://localhost:8888/notify ...` command
+2. VoiceGate intercepts it before execution
+3. If `notifications.voice` is `false` in settings.json -> **BLOCK** (curl never executes)
+4. If `notifications.voice` is `true` (or missing) -> proceed to subagent check
+5. If main session -> **PASS** (curl executes)
+6. If subagent -> **BLOCK** (subagent curls always blocked)
+
+This means the Algorithm template's `[VERBATIM]` curl directives remain unchanged. The gating happens at infrastructure level, not prompt level.
+
+### Desktop Suppression
+
+Desktop notifications are sent via macOS `osascript` or notification hooks. When `notifications.desktop` is `false`, notification-sending code should check this setting before firing.
+
+---
+
+## When to Activate This Skill
+
+### Direct Notification Commands
+- "/notification voice on/off"
+- "/notification desktop on/off"
+- "/notification status"
+- "/notification all on/off"
+
+### Natural Language Triggers
+- "turn off voice notifications"
+- "mute the voice", "silence curls"
+- "stop announcing phases"
+- "enable voice", "unmute"
+- "what notification channels are on"
+- "show notification settings"
+- "disable all notifications"
+
+---
+
+## Related Documentation
+
+- **Notification System:** `~/.claude/skills/PAI/THENOTIFICATIONSYSTEM.md`
+- **VoiceGate Hook:** `~/.claude/hooks/VoiceGate.hook.ts`
+- **Settings:** `~/.claude/settings.json` → `notifications` section

Releases/v3.0/.claude/skills/PAI/THENOTIFICATIONSYSTEM.md

@@ -5,6 +5,51 @@
 This system provides:
 - Voice feedback when workflows start
 - Consistent user experience across all skills
+- **Per-channel notification control** via `/notification` skill
+
+---
+
+## Per-Channel Notification Control
+
+**Granular toggle control over notification channels.** Use the `/notification` skill:
+
+```
+/notification voice on       # Enable voice (curl) notifications
+/notification voice off      # Disable voice notifications — suppresses ALL curl calls
+/notification desktop on     # Enable desktop notifications
+/notification desktop off    # Disable desktop notifications
+/notification status         # Show current notification channel states
+/notification all off        # Disable all notification channels
+/notification all on         # Enable all notification channels
+```
+
+### Settings Persistence
+
+Notification state is stored in `settings.json`:
+
+```json
+{
+  "notifications": {
+    "voice": { "enabled": true },
+    "desktop": { "enabled": true }
+  }
+}
+```
+
+Both boolean (`"voice": false`) and object (`"voice": { "enabled": false }`) formats are supported.
+
+### Voice Curl Suppression
+
+When `notifications.voice` is `false`, the `VoiceGate.hook.ts` PreToolUse hook blocks ALL `curl` commands targeting `localhost:8888` before they execute. This means:
+
+- **Zero terminal noise** — no curl commands appear in output
+- **Zero execution** — the voice server is never contacted
+- **Zero changes to Algorithm template** — curls remain `[VERBATIM]` in the prompt; gating happens at hook level
+- **Background agents inherit the setting** — VoiceGate reads from `settings.json` which is shared across all sessions
+
+### Skill Reference
+
+Full documentation: `~/.claude/skills/Notification/SKILL.md`
 
 ---