fix badge priority, update CC docs

Author: sawka

docs/docs/claude-code.mdx

@@ -4,10 +4,16 @@ id: "claude-code"
 title: "Claude Code Integration"
 ---
 
-# Claude Code Tab Badges
+import { VersionBadge } from "@site/src/components/versionbadge";
+
+# Claude Code Tab Badges <VersionBadge version="v0.14.2" />
 
 When you run multiple Claude Code sessions in parallel — one per feature, one per repo, a few long-running tasks — it gets hard to know which tabs need your attention without clicking through each one. Wave's badge system solves this: hooks in Claude Code write a small visual indicator to the tab header whenever something important happens, so you can see at a glance which sessions are waiting, done, or in trouble.
 
+:::info
+tl;dr You can copy and paste this page directly into Claude Code and it will help you set everything up!
+:::
+
 ## How it works
 
 Claude Code supports [lifecycle hooks](https://code.claude.com/docs/en/hooks) — shell commands that run automatically at specific points in a session. Wave's `wsh badge` command sets or clears a visual indicator on the current block or tab. By wiring these together, you get ambient awareness across all your sessions without watching any of them.
@@ -38,6 +44,15 @@ Add the following to `~/.claude/settings.json`. If you already have a `hooks` ke
             "command": "wsh badge bell-exclamation --color '#e0b956' --priority 20 --beep"
           }
         ]
+      },
+      {
+        "matcher": "elicitation_dialog",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "wsh badge message-question --color '#e0b956' --priority 20 --beep"
+          }
+        ]
       }
     ],
     "Stop": [
@@ -49,43 +64,62 @@ Add the following to `~/.claude/settings.json`. If you already have a `hooks` ke
           }
         ]
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "wsh badge message-question --color '#e0b965' --priority 20 --beep"
+          }
+        ]
+      }
     ]
   }
 }
 ```
 
 That's it. Restart any running Claude Code sessions for the hooks to take effect.
 
+:::warning Known Issue
+There is a known issue in Claude Code where `Notification` hooks may be delayed by several seconds before firing. This delay is unrelated to Wave — it occurs in Claude Code itself. See [#5186](https://github.com/anthropics/claude-code/issues/5186) and [#19627](https://github.com/anthropics/claude-code/issues/19627) for details.
+:::
+
 ## What each hook does
 
-### Permission prompt — `circle-exclamation` gold, priority 20
+### Permission prompt — `bell-exclamation` gold, priority 20
 
 Claude Code occasionally needs your approval before it can continue — to run a command, write a file outside the project, or use a tool that requires explicit permission. When it hits one of these, it stops and waits. Without a signal, you might not notice for minutes.
 
 This hook fires on the `permission_prompt` notification type and sets a high-priority gold badge with an audible beep. Priority 20 means it beats any other badge on that tab, so a waiting session always surfaces above a finished one.
 
 When you click into the tab and approve or deny the request, the badge clears automatically.
 
-### Session complete — `circle-check` green, priority 10
+### Session complete — `check` green, priority 10
 
 When Claude Code finishes responding, this hook sets a green check badge. It's a low-key signal: glance at the tab bar, see which sessions are done, review their output in whatever order you like.
 
-The `stop_hook_active` guard in the command prevents the hook from firing recursively if you have other `Stop` hooks that keep Claude running.
+### AskUserQuestion — `message-question` gold, priority 20
+
+When Claude Code uses the `AskUserQuestion` tool, it's paused and waiting for you to respond before it can proceed. This `PreToolUse` hook fires just before that tool call and sets the same high-priority gold badge as the permission prompt.
+
+`PreToolUse` hooks can match any tool by name, so you can add badges for other tools as well — for example, to get a signal whenever Claude runs a shell command (`Bash`) or edits a file (`Edit`). Any tool name Claude Code supports can be used as a matcher.
 
 ## Choosing your own icons and colors
 
-Icon names are [Font Awesome](https://fontawesome.com/icons) icon names without the `fa-` prefix. Colors are any valid CSS color — named colors like `gold` and `green`, hex values like `#f59e0b`, or anything else CSS accepts.
+Icon names are [Font Awesome](https://fontawesome.com/icons) icon names without the `fa-` prefix. Colors are any valid CSS color — hex values, named colors, or anything else CSS accepts.
 
-Some alternatives to consider:
+Some icon and color ideas:
 
 | Situation | Icon | Color |
 |-----------|------|-------|
-| Permission needed | `circle-exclamation` | `gold` |
-| Session complete | `circle-check` | `green` |
-| Custom high-priority alert | `triangle-exclamation` | `red` |
-| Neutral / informational | `circle-info` | `steelblue` |
+| Custom high-priority alert | `triangle-exclamation` | `#FF453A` |
+| Blocked / waiting on input | `hourglass-half` | `#FF9500` |
+| Neutral / informational | `circle-info` | `#429DFF` |
+| Background task running | `spinner` | `#00FFDB` |
 
-To target a specific block or tab instead of the current one, add `-b <blockid>` or `-b tab`. See the [`wsh badge` reference](/reference/wsh-cmd/badge) for all available flags.
+See the [`wsh badge` reference](/reference/wsh-cmd/badge) for all available flags.
 
 ## Adjusting priorities
 

frontend/app/store/badge.ts

@@ -123,8 +123,7 @@ function getTabBadgeAtom(tabId: string, env?: TabBadgesEnv): Atom<Badge[]> {
     }
     const tabOref = WOS.makeORef("tab", tabId);
     const tabBadgeAtom = getBadgeAtom(tabOref);
-    const tabAtom =
-        env != null ? env.wos.getWaveObjectAtom<Tab>(tabOref) : WOS.getWaveObjectAtom<Tab>(tabOref);
+    const tabAtom = env != null ? env.wos.getWaveObjectAtom<Tab>(tabOref) : WOS.getWaveObjectAtom<Tab>(tabOref);
     rtn = atom((get) => {
         const tab = get(tabAtom);
         const blockIds = tab?.blockids ?? [];
@@ -213,7 +212,13 @@ function setupBadgesSubscription() {
                 }
                 return;
             }
-            globalStore.set(curAtom, data.clear ? null : (data.badge ?? null));
+            if (data.clear) {
+                globalStore.set(curAtom, null);
+            } else if (data.badge != null) {
+                const existing = globalStore.get(curAtom);
+                const candidates = existing != null ? [existing, data.badge] : [data.badge];
+                globalStore.set(curAtom, sortBadges(candidates)[0]);
+            }
         },
     });
 }

pkg/wcore/badge.go

@@ -94,8 +94,12 @@ func setBadge(oref waveobj.ORef, data baseds.BadgeEvent) {
 		delete(globalBadgeStore.transient, orefStr)
 		log.Printf("badge store: badge cleared: oref=%s\n", orefStr)
 	} else {
-		globalBadgeStore.transient[orefStr] = *data.Badge
-		log.Printf("badge store: badge set: oref=%s badge=%+v\n", orefStr, *data.Badge)
+		incoming := *data.Badge
+		existing, hasExisting := globalBadgeStore.transient[orefStr]
+		if !hasExisting || incoming.Priority > existing.Priority || (incoming.Priority == existing.Priority && incoming.BadgeId > existing.BadgeId) {
+			globalBadgeStore.transient[orefStr] = incoming
+			log.Printf("badge store: badge set: oref=%s badge=%+v\n", orefStr, incoming)
+		}
 	}
 }