feat(sag-notify)!: skill-driven notifications, greeting-style messages

duyet · duyetbot · duyet · commit 134153fab3aa · 2026-06-02T22:38:27.000+07:00
Replace auto-firing Notification/Stop hooks with a skill-driven model: Claude
runs the notifier itself (bin/speak.sh) right before it asks a question and once
at the end of a substantive turn, so the spoken line reflects what it did/needs.

- New default templates: "Hi, this is Claude. Project &lt;name&gt; needs you/is done. &lt;body&gt;"
  (en + vi presets), with empty-body collapse in sag_render.
- Add bin/speak.sh (agent CLI: `needs-you`/`done` + body) reusing lib.sh; move
  hooks/lib.sh -&gt; bin/lib.sh; remove hooks.json, notify.sh, summary.sh.
- Drop now-unused summary_file config key (body is passed as a CLI arg).
- Rewrite sag-voice SKILL.md with the proactive protocol; refresh README,
  setup/config/test commands; marketplace type hook -&gt; skill.

BREAKING CHANGE: notifications no longer fire from hooks; enable the sag-voice
skill so Claude speaks proactively.

Co-Authored-By: duyetbot &lt;duyetbot@users.noreply.github.com&gt;
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -87,7 +87,7 @@
     {
       "name": "sag-notify",
       "source": "./sag-notify",
-      "description": "Spoken voice notifications via sag (ElevenLabs TTS). Speaks a short alert when Claude needs you and a per-turn summary when work finishes, naming the project. Auto-injected hooks; configurable voice, language, and templates."
+      "description": "Spoken voice notifications via sag (ElevenLabs TTS). Skill-driven: Claude speaks a short alert just before it asks you something and a one-line summary when work finishes, naming the project. Configurable voice, language, and templates."
     }
   ]
 }
diff --git a/marketplace.json b/marketplace.json
@@ -150,9 +150,9 @@
     {
       "name": "sag-notify",
       "id": "sag-notify@duyet-claude-plugins",
-      "description": "Spoken voice notifications via sag (ElevenLabs TTS): a short alert when Claude needs you and a per-turn summary when work finishes, naming the project. Configurable voice, language, and templates.",
-      "version": "1.0.0",
-      "type": "hook",
+      "description": "Spoken voice notifications via sag (ElevenLabs TTS): skill-driven, Claude speaks a short alert just before it asks you something and a one-line summary when work finishes, naming the project. Configurable voice, language, and templates.",
+      "version": "2.0.0",
+      "type": "skill",
       "category": "ui"
     }
   ],
diff --git a/sag-notify/.claude-plugin/plugin.json b/sag-notify/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "sag-notify",
-  "version": "1.1.0",
-  "description": "Spoken voice notifications via sag (ElevenLabs TTS). Speaks a short alert when Claude needs you, and a per-turn summary when work finishes — naming the project. Auto-injected hooks; configurable voice, multi-language presets, and message templates.",
+  "version": "2.0.0",
+  "description": "Spoken voice notifications via sag (ElevenLabs TTS). Skill-driven: Claude speaks a short alert just before it asks you something, and a one-line summary when work finishes — naming the project. Configurable voice, multi-language presets, and message templates.",
   "author": {
     "name": "duyet"
   }
diff --git a/sag-notify/README.md b/sag-notify/README.md
@@ -2,36 +2,38 @@
 
 Spoken voice notifications for Claude Code via [`sag`](https://github.com/steipete/sag) (ElevenLabs TTS).
 
-- **Needs you** → when Claude waits for permission/input, it speaks a short alert naming the project.
-- **Turn done** → when Claude finishes substantive work, it speaks a one-line summary you author.
+- **Needs you** → just before Claude asks you a question, it speaks a short alert naming the project.
+- **Turn done** → when Claude finishes substantive work, it speaks a one-line summary of what it did.
 
-Both are driven by **auto-injected hooks** — once the plugin is enabled, every session gets them, no per-session setup.
+Both are **skill-driven**: Claude runs `sag` itself at the right moment (via the bundled `bin/speak.sh`), so the spoken line reflects what it actually did or needs. There are no auto-firing hooks — the **sag-voice** skill teaches Claude when and how to speak.
 
 ## Requirements
 
 The `sag` CLI must be installed and authenticated. Install with `brew install steipete/tap/sag` and set `ELEVENLABS_API_KEY`. Full guide: [skills/sag-voice/references/sag-cli.md](skills/sag-voice/references/sag-cli.md).
 
 ## How it works
 
-| Event | Hook | Behavior |
-|-------|------|----------|
-| `Notification` | `hooks/notify.sh` | Speaks the notification template, naming the project, in the configured language. (The harness message is English, so it is replaced by the template.) |
-| `Stop` | `hooks/summary.sh` | Reads the body Claude wrote to `summary_file`, speaks it via the summary template, deletes the file. **Silent when no file exists**, so trivial turns are quiet. |
+Claude calls one helper at two moments:
 
-To make Claude speak a summary, it writes a short body to `~/.claude/.sag-summary` during a substantive turn. The hook adds the `This is <name>, reporting from project <name>:` framing automatically.
+| Moment | Command | Speaks (default) |
+|--------|---------|------------------|
+| Right before asking you (e.g. before `AskUserQuestion`) | `bin/speak.sh needs-you "<reason>"` | `Hi, this is Claude. Project <name> needs you. <reason>` |
+| End of a substantive turn | `bin/speak.sh done "<summary>"` | `Hi, this is Claude. Project <name> is done. <summary>` |
+
+`bin/speak.sh` reads your config, names the project from `$PWD`, renders the configured template, and speaks in the background. It exits silently when `sag`/`jq`/the API key are missing or the plugin is disabled, so it never blocks a turn. Trivial turns stay quiet because Claude simply doesn't call it.
 
 ## Setup
 
 1. Install + authenticate `sag` (see Requirements).
-2. Enable the plugin (it ships `hooks/hooks.json`).
+2. Enable the plugin and the **sag-voice** skill.
 3. Run `/sag-notify:setup` — checks `sag`/`jq`, resolves the API key, picks a voice, writes config, and tests audio.
 4. Or just rely on defaults: Brian voice, English templates, key from the `ELEVENLABS_API_KEY` environment variable.
 
 `ELEVENLABS_API_KEY` must be resolvable — from the environment, or from an optional key file you point `key_file` at in your user config.
 
 ## Configuration
 
-User config at `~/.config/sag-notify/config.json` overrides [`config.default.json`](config.default.json). See the **sag-voice** skill or run `/sag-notify:config`. Key settings: `enabled`, `events.{notification,summary}`, `voice_id`, `model_id`, `self_name`, `language`, `key_file`, `summary_file`, `error_log`, `max_chars`, `templates.{notification,summary}`, `languages.<lang>.{notification,summary}`.
+User config at `~/.config/sag-notify/config.json` overrides [`config.default.json`](config.default.json). See the **sag-voice** skill or run `/sag-notify:config`. Key settings: `enabled`, `events.{notification,summary}`, `voice_id`, `model_id`, `self_name`, `language`, `key_file`, `error_log`, `max_chars`, `templates.{notification,summary}`, `languages.<lang>.{notification,summary}`.
 
 ### Languages
 
@@ -49,8 +51,8 @@ jq '.language = "vi"' ~/.config/sag-notify/config.json > /tmp/c && mv /tmp/c ~/.
 
 - `/sag-notify:setup` — guided first-time setup + audio test
 - `/sag-notify:config` — change voice, language, templates, toggles
-- `/sag-notify:test` — fire both hooks and check `~/.claude/.sag-error.log`
+- `/sag-notify:test` — fire both notification lines and check `~/.claude/.sag-error.log`
 
 ## Troubleshooting
 
-Silent? Check `~/.claude/.sag-error.log` (the hooks log stderr there, never `/dev/null`). A `402` means a paid voice; switch to a premade one. Verify real audio in the **foreground** — the hooks background the call so their exit code can't tell you if sound played.
+Silent? Check `~/.claude/.sag-error.log` (errors are logged there, never `/dev/null`). A `402` means a paid voice; switch to a premade one. Verify real audio in the **foreground** — `bin/speak.sh` backgrounds the call so its exit code can't tell you if sound played.
diff --git a/sag-notify/bin/lib.sh b/sag-notify/bin/lib.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Shared helpers for the sag-notify hooks. Sourced by notify.sh and summary.sh.
+# Shared helpers for sag-notify. Sourced by bin/speak.sh (the agent-driven CLI).
 # Config precedence: user config (~/.config/sag-notify/config.json) → plugin default.
 
 # Plugin root: prefer the env Claude Code sets; fall back to this file's parent dir.
@@ -66,10 +66,14 @@ sag_speak() {
 }
 
 # sag_render <template> <name> <project> [body] — substitute {name}/{project}/{body}.
+# Collapses a dangling " {body}" to nothing when no body is given, and trims any
+# leftover double spaces / trailing space so empty-body lines read cleanly.
 sag_render() {
   local out="$1"
   out=${out//\{name\}/$2}
   out=${out//\{project\}/$3}
   out=${out//\{body\}/${4:-}}
+  out=${out//  / }      # collapse double spaces left by an empty {body}
+  out=${out% }          # drop a single trailing space
   printf '%s' "$out"
 }
diff --git a/sag-notify/bin/speak.sh b/sag-notify/bin/speak.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Agent-driven voice notification via sag. The sag-voice skill instructs Claude to
+# run this itself — right before it asks you a question, and once at the end of a
+# substantive turn — instead of relying on auto-firing hooks.
+#
+#   speak.sh needs-you "I have two questions before continuing."
+#   speak.sh done      "Refactored the hooks into a skill; build is green."
+#
+# Resolves config from ~/.config/sag-notify/config.json (falls back to the plugin
+# default), renders the configured template, names the current project from $PWD,
+# and speaks in the background. Exits 0 silently on any missing prerequisite so it
+# never blocks a turn.
+set -uo pipefail
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+kind="${1:-done}"
+body="${2:-}"
+
+command -v sag >/dev/null 2>&1 || exit 0
+command -v jq  >/dev/null 2>&1 || exit 0
+[ "$(cfg '.enabled' 'true')" = "true" ] || exit 0
+sag_resolve_key || exit 0
+
+# Map the friendly verb to a template kind + the toggle that gates it.
+case "$kind" in
+  notify|notification|needs-you|needsyou|input|ask) tkind=notification; event=notification ;;
+  done|summary|finished|complete)                    tkind=summary;      event=summary ;;
+  *)                                                 tkind=summary;      event=summary ;;
+esac
+[ "$(cfg ".events.$event" 'true')" = "true" ] || exit 0
+
+name=$(cfg '.self_name' 'Claude')
+project=$(sag_project "$PWD")
+maxlen=$(cfg '.max_chars' '280')
+body=${body:0:$maxlen}
+tmpl=$(sag_template "$tkind")
+
+sag_speak "$(sag_render "$tmpl" "$name" "$project" "$body")"
+exit 0
diff --git a/sag-notify/commands/config.md b/sag-notify/commands/config.md
@@ -24,7 +24,7 @@ Common changes:
 - **Length cap**: `.max_chars = 200`.
 - **Key file**: `.key_file = "~/path/to/keyfile"` (sourced if `ELEVENLABS_API_KEY` is unset).
 
-After changing the voice or templates, verify in the FOREGROUND (hooks background the call):
+After changing the voice or templates, verify in the FOREGROUND (`bin/speak.sh` backgrounds the call):
 ```
 ! V=$(jq -r .voice_id ~/.config/sag-notify/config.json); M=$(jq -r .model_id ~/.config/sag-notify/config.json); sag speak --model-id "$M" --voice-id "$V" "test" 2>&1 | grep -iE "failed|402" || echo OK
 ```
diff --git a/sag-notify/commands/setup.md b/sag-notify/commands/setup.md
@@ -8,7 +8,7 @@ Walk the user through setup, doing the work for them where possible:
 
 1. **Check `sag` and `jq`** are installed: `command -v sag jq`. If `sag` is missing, point them at the install guide [skills/sag-voice/references/sag-cli.md](../skills/sag-voice/references/sag-cli.md) (`brew install steipete/tap/sag`) and stop.
 
-2. **Resolve the API key.** Check `ELEVENLABS_API_KEY` in the environment. If absent, instruct the user to add it themselves (do NOT ask them to paste the secret in chat). Recommend their shell env file so non-interactive hook shells inherit it:
+2. **Resolve the API key.** Check `ELEVENLABS_API_KEY` in the environment. If absent, instruct the user to add it themselves (do NOT ask them to paste the secret in chat). Recommend their shell env file so non-interactive shells (where `bin/speak.sh` runs) inherit it:
    ```
    ! echo "export ELEVENLABS_API_KEY='your-key'" >> ~/.zshenv
    ```
@@ -26,4 +26,4 @@ Walk the user through setup, doing the work for them where possible:
    ```
    Empty/`OK` = success. A 402 means the voice needs a paid plan — go back to step 4.
 
-7. Confirm the hooks are active and explain that summaries only speak when Claude writes a body to the configured `summary_file`.
+7. Confirm the **sag-voice** skill is enabled and explain the model: Claude itself runs `${CLAUDE_PLUGIN_ROOT}/bin/speak.sh` — `needs-you` right before it asks a question, and `done` once at the end of a substantive turn. There are no auto-firing hooks, so trivial turns stay silent.
diff --git a/sag-notify/commands/test.md b/sag-notify/commands/test.md
@@ -1,27 +1,27 @@
 # /sag-notify:test
 
-Speak a test line through the current configuration to confirm audio works.
+Speak both notification lines through the current configuration to confirm audio works.
 
 ## Action Required
 
-Run both hook paths the same way Claude Code would, then check the error log.
+Fire the helper the same way Claude does during a turn, then check the error log.
 
 1. Resolve config values:
    ```
    ! CFG=~/.config/sag-notify/config.json; [ -f "$CFG" ] || CFG="${CLAUDE_PLUGIN_ROOT}/config.default.json"; jq . "$CFG"
    ```
 
-2. **Notification path** — fire the hook with a sample cwd so it names a project:
+2. **Needs-you line** — names the current project:
    ```
-   ! echo '{"cwd":"/path/to/demo-project"}' | "${CLAUDE_PLUGIN_ROOT}/hooks/notify.sh"; echo exit=$?
+   ! "${CLAUDE_PLUGIN_ROOT}/bin/speak.sh" needs-you "this is an audio test."; echo exit=$?
    ```
 
-3. **Summary path** — prime a body, then fire the Stop hook (use the configured language for the body):
+3. **Done line** — the end-of-turn summary:
    ```
-   ! printf 'this is an audio test.' > ~/.claude/.sag-summary; echo '{"cwd":"/path/to/demo-project"}' | "${CLAUDE_PLUGIN_ROOT}/hooks/summary.sh"; echo exit=$?
+   ! "${CLAUDE_PLUGIN_ROOT}/bin/speak.sh" done "this is an audio test."; echo exit=$?
    ```
 
-4. **Check for silent failures** (the hooks background the call, so a clean exit ≠ sound):
+4. **Check for silent failures** (the helper backgrounds the call, so a clean exit ≠ sound):
    ```
    ! sleep 6; [ -s ~/.claude/.sag-error.log ] && cat ~/.claude/.sag-error.log || echo "(no errors — audio played)"
    ```
diff --git a/sag-notify/config.default.json b/sag-notify/config.default.json
@@ -9,7 +9,6 @@
   "self_name": "Claude",
   "language": "en",
   "key_file": "",
-  "summary_file": "~/.claude/.sag-summary",
   "error_log": "~/.claude/.sag-error.log",
   "max_chars": 280,
   "templates": {
@@ -18,12 +17,12 @@
   },
   "languages": {
     "en": {
-      "notification": "This is {name}. I'm working on project {project} and could use your input.",
-      "summary": "This is {name}, reporting from project {project}: {body}"
+      "notification": "Hi, this is {name}. Project {project} needs you. {body}",
+      "summary": "Hi, this is {name}. Project {project} is done. {body}"
     },
     "vi": {
-      "notification": "Đây là {name}. Mình đang làm ở project {project}, cần bạn xem qua một chút.",
-      "summary": "Đây là {name}, báo cáo từ project {project}: {body}"
+      "notification": "Chào, mình là {name}. Project {project} cần bạn xem qua. {body}",
+      "summary": "Chào, mình là {name}. Project {project} đã xong. {body}"
     }
   }
 }
diff --git a/sag-notify/hooks/hooks.json b/sag-notify/hooks/hooks.json
diff --git a/sag-notify/hooks/notify.sh b/sag-notify/hooks/notify.sh
diff --git a/sag-notify/hooks/summary.sh b/sag-notify/hooks/summary.sh
diff --git a/sag-notify/skills/sag-voice/SKILL.md b/sag-notify/skills/sag-voice/SKILL.md

Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@`
`87`	`87`	`{`
`88`	`88`	`"name": "sag-notify",`
`89`	`89`	`"source": "./sag-notify",`
`90`		`- "description": "Spoken voice notifications via sag (ElevenLabs TTS). Speaks a short alert when Claude needs you and a per-turn summary when work finishes, naming the project. Auto-injected hooks; configurable voice, language, and templates."`
	`90`	`+ "description": "Spoken voice notifications via sag (ElevenLabs TTS). Skill-driven: Claude speaks a short alert just before it asks you something and a one-line summary when work finishes, naming the project. Configurable voice, language, and templates."`
`91`	`91`	`}`
`92`	`92`	`]`
`93`	`93`	`}`
Original file line number	Diff line number	Diff line change
`@@ -150,9 +150,9 @@`
`150`	`150`	`{`
`151`	`151`	`"name": "sag-notify",`
`152`	`152`	`"id": "sag-notify@duyet-claude-plugins",`
`153`		`- "description": "Spoken voice notifications via sag (ElevenLabs TTS): a short alert when Claude needs you and a per-turn summary when work finishes, naming the project. Configurable voice, language, and templates.",`
`154`		`- "version": "1.0.0",`
`155`		`- "type": "hook",`
	`153`	`+ "description": "Spoken voice notifications via sag (ElevenLabs TTS): skill-driven, Claude speaks a short alert just before it asks you something and a one-line summary when work finishes, naming the project. Configurable voice, language, and templates.",`
	`154`	`+ "version": "2.0.0",`
	`155`	`+ "type": "skill",`
`156`	`156`	`"category": "ui"`
`157`	`157`	`}`
`158`	`158`	`],`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "sag-notify",`
`3`		`- "version": "1.1.0",`
`4`		`- "description": "Spoken voice notifications via sag (ElevenLabs TTS). Speaks a short alert when Claude needs you, and a per-turn summary when work finishes — naming the project. Auto-injected hooks; configurable voice, multi-language presets, and message templates.",`
	`3`	`+ "version": "2.0.0",`
	`4`	`+ "description": "Spoken voice notifications via sag (ElevenLabs TTS). Skill-driven: Claude speaks a short alert just before it asks you something, and a one-line summary when work finishes — naming the project. Configurable voice, multi-language presets, and message templates.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "duyet"`
`7`	`7`	`}`