chore: Loosening claudesay reply limits, update README with multi-turn tag handling documentation and reformat design spec for consistency.

TimJJTing · TimJJTing · commit 476af6d17bd1 · 2026-04-24T21:58:25.000+08:00
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "claudesay",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Renders Claude replies as ASCII character speech bubbles",
   "author": {
     "name": "TimJJTing"
diff --git a/README.md b/README.md
@@ -328,10 +328,39 @@ Buddy was a Tamagotchi-style virtual pet — a companion you hatch and tend to.
 - The raw `<claudesay>` tag appears in the terminal scrollback before the bubble renders (Claude streams it before the Stop hook fires).
 - Figures do not render in CI, `--print` mode, or non-interactive SSH sessions.
 - Per-turn reminder adds ~20 tokens per turn.
+- **Stop-hook bubble reflects only the final assistant text block of a turn.** The Stop hook reads `.last_assistant_message` and grabs the last `<claudesay>` tag in it (`hooks/scripts/stop.sh`, `tail -1`). If Claude emits multiple conversational text messages in one turn (text → tool → text → tool → text), only the tag in the last block renders.
 
-## Compatibility
+  **Why we stop here:** the injected protocol (`hooks/scripts/session-start.sh`) instructs Claude to emit a single tag *at the very end*, with room for ~120 chars / 1-2 sentences in first person covering the whole turn. One well-written bubble usually describes the turn in full, making multi-bubble rendering redundant for the intended use case.
 
-Stacks naturally with the [caveman plugin](https://github.com/JuliusBrussee/caveman). Caveman compresses the main response; claudesay bubbles the separately-written tag. No conflict. `caveman-lite` recommended as a complementary install.
+  **If you want to render a bubble per mid-turn text block**, parse `transcript_path` (available on Stop hook input JSON). The transcript is JSONL, one message per line. Assistant entries look like:
+
+  ```json
+  {"type":"assistant","message":{"role":"assistant","content":[
+    {"type":"thinking", "...": "..."},
+    {"type":"text","text":"<claudesay mood=\"...\">...</claudesay>"},
+    {"type":"tool_use", "...": "..."}
+  ]}}
+  ```
+
+  A turn spans **multiple** assistant entries (one per LLM call, split by tool boundaries). Each has its own `.message.content` array of blocks — `thinking`, `text`, `tool_use`. Steps:
+
+  1. Walk JSONL backwards from EOF.
+  2. Stop at the most recent `type:"user"` entry whose content is not a `tool_result` — that marks the start of the current turn.
+  3. For each assistant entry after that boundary, extract `.message.content[] | select(.type=="text") | .text`.
+  4. Run the existing `<claudesay>` regex over each block; render matches sequentially, or combine into one multi-line bubble.
+
+  Sketch (`jq`):
+
+  ```bash
+  jq -r '
+    select(.type=="assistant")
+    | .message.content[]?
+    | select(.type=="text")
+    | .text
+  ' "$TRANSCRIPT_PATH"
+  ```
+
+  Add guards for missing/malformed/large transcripts. The protocol would also need updating to permit (and describe) mid-turn tags. Not shipped — contributions welcome.
 
 ## Development
 
diff --git a/docs/superpowers/specs/2026-04-17-claude-say-design.md b/docs/superpowers/specs/2026-04-17-claude-say-design.md
@@ -1,4 +1,5 @@
 # claudesay Design Spec
+
 _2026-04-17_
 
 ## Overview
@@ -66,10 +67,46 @@ Plugin hooks.json uses a flat format keyed directly by event name — no outer w
 
 ```json
 {
-  "SessionStart":     [{ "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh" }] }],
-  "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/prompt-submit.sh" }] }],
-  "PreToolUse":       [{ "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-tool-use.sh" }] }],
-  "Stop":             [{ "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop.sh" }] }]
+  "SessionStart": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/session-start.sh"
+        }
+      ]
+    }
+  ],
+  "UserPromptSubmit": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/prompt-submit.sh"
+        }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pre-tool-use.sh"
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop.sh"
+        }
+      ]
+    }
+  ]
 }
 ```
 
@@ -130,6 +167,7 @@ echo '{"systemMessage": "<claudesay-protocol>\nWhen giving a conversational repl
 ```
 
 `prompt-submit.sh` outputs a compact `systemMessage` reminder with every user turn so Claude never drifts:
+
 ```bash
 echo '{"systemMessage": "[claudesay: end chatty reply with <claudesay mood=\"X\">summary</claudesay>]"}'
 ```
@@ -177,45 +215,46 @@ fi
 
 ### Mood Expressions
 
-| Mood      | Face       | When used                        |
-|-----------|------------|----------------------------------|
-| happy-a   | `( ^ᵕ^  )` | Normal success (variant A)       |
-| happy-b   | `( ᵕ‿ᵕ  )` | Normal success (variant B)       |
-| excited   | `( ^▽^  )` | Big win                          |
-| excited-b | `( ≧▽≦  )` | Very excited                     |
-| thinking  | `( ._.  )` | In progress / uncertain          |
-| focused   | `( -.-  )` | Running a tool                   |
-| upset     | `( >_<  )` | Warning or partial failure       |
-| error     | `( x_x  )` | Actual error                     |
+| Mood      | Face       | When used                  |
+| --------- | ---------- | -------------------------- |
+| happy-a   | `( ^ᵕ^  )` | Normal success (variant A) |
+| happy-b   | `( ᵕ‿ᵕ  )` | Normal success (variant B) |
+| excited   | `( ^▽^  )` | Big win                    |
+| excited-b | `( ≧▽≦  )` | Very excited               |
+| thinking  | `( ._.  )` | In progress / uncertain    |
+| focused   | `( -.-  )` | Running a tool             |
+| upset     | `( >_<  )` | Warning or partial failure |
+| error     | `( x_x  )` | Actual error               |
 
 Positive moods rotate between variants on each render to avoid repetition.
 
 ### Tool Props (PreToolUse)
 
 Each tool entry has a `side` field (`left`/`right`) controlling which hand holds the prop. "Reaching out" tools (searching, reading, fetching) use the left hand; "doing" tools (editing, running, spawning) use the right.
 
-| Tool(s)              | Prop          | Mood     | Side  |
-|----------------------|---------------|----------|-------|
-| Edit, Write          | 🔧 wrench     | focused  | left  |
-| Bash                 | 🪄 magic wand | focused  | right |
-| Grep, Glob           | 🔍 magnifier  | thinking | left  |
-| Read                 | 📖 book       | thinking | left  |
-| WebFetch, WebSearch  | 📡 antenna    | thinking | right |
-| Agent (spawn)        | 🤖 buddy      | excited  | right |
-| TodoWrite            | 📋 clipboard  | focused  | left  |
-| default              | (none)        | focused  | —     |
+| Tool(s)             | Prop          | Mood     | Side  |
+| ------------------- | ------------- | -------- | ----- |
+| Edit, Write         | 🔧 wrench     | focused  | left  |
+| Bash                | 🪄 magic wand | focused  | right |
+| Grep, Glob          | 🔍 magnifier  | thinking | left  |
+| Read                | 📖 book       | thinking | left  |
+| WebFetch, WebSearch | 📡 antenna    | thinking | right |
+| Agent (spawn)       | 🤖 buddy      | excited  | right |
+| TodoWrite           | 📋 clipboard  | focused  | left  |
+| default             | (none)        | focused  | —     |
 
 ### Rendered Output Examples
 
 **Chat reply (Stop hook):**
+
 ```
 ...Claude's full response above...
 <claudesay mood="excited">All 3 tests pass now!</claudesay>
 
  ╭────────────────────────────────╮
  │   All 3 tests pass now!        │
  ╰────╮───────────────────────────╯
-      │                 
+      │
     /\__/\
    ( ≧▽≦  )
   m( ,,,, )m
@@ -224,6 +263,7 @@ Each tool entry has a `side` field (`left`/`right`) controlling which hand holds
 ```
 
 **Tool state (PreToolUse), prop on right (Edit):**
+
 ```
  ╭─────────────────────────────────╮
  │   Edit → src/utils.py           │
@@ -237,6 +277,7 @@ Each tool entry has a `side` field (`left`/`right`) controlling which hand holds
 ```
 
 **Tool state (PreToolUse), prop on left (Read):**
+
 ```
  ╭─────────────────────────────────╮
  │   Read → src/utils.py           │
@@ -275,20 +316,14 @@ CHAR_BOTTOM="    ||   ||\`~~>\n   (_)  (_)" # the rest of the character, can hav
 
 ## Edge Cases
 
-| Scenario | Behaviour |
-|---|---|
-| Claude omits `<claudesay>` tag | stop.sh exits silently — no duplicate output |
-| Multiple tags in one response | Take the last one |
-| Tool input path > 50 chars | Truncate with `…` |
-| Message > 45 chars wide | Wrap to multiple bubble lines |
-| Custom character missing a mood | Fall back to default character expression |
-| Custom character missing `CHAR_HAND_LEFT` or `CHAR_HAND_RIGHT` | Fall back to `m` for each |
-| Tool entry has no `side` or side is `—` | No prop shown, both hands rendered normally |
-| `jq` not installed | `/claudesay on` preflight check detects this and prints install instructions; hooks exit 0 silently if somehow reached |
-| Flag absent | All hooks exit at line 2 — zero overhead |
-
----
-
-## Caveman Compatibility
-
-`claudesay` stacks naturally with the caveman plugin. Caveman compresses the main response body; `claudesay` bubbles the separately-written summary tag. No conflict. README recommends `caveman-lite` as a complementary install.
+| Scenario                                                       | Behaviour                                                                                                              |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Claude omits `<claudesay>` tag                                 | stop.sh exits silently — no duplicate output                                                                           |
+| Multiple tags in one response                                  | Take the last one                                                                                                      |
+| Tool input path > 50 chars                                     | Truncate with `…`                                                                                                      |
+| Message > 45 chars wide                                        | Wrap to multiple bubble lines                                                                                          |
+| Custom character missing a mood                                | Fall back to default character expression                                                                              |
+| Custom character missing `CHAR_HAND_LEFT` or `CHAR_HAND_RIGHT` | Fall back to `m` for each                                                                                              |
+| Tool entry has no `side` or side is `—`                        | No prop shown, both hands rendered normally                                                                            |
+| `jq` not installed                                             | `/claudesay on` preflight check detects this and prints install instructions; hooks exit 0 silently if somehow reached |
+| Flag absent                                                    | All hooks exit at line 2 — zero overhead                                                                               |
diff --git a/hooks/scripts/session-start.sh b/hooks/scripts/session-start.sh
@@ -6,7 +6,7 @@ FLAG="${CLAUDE_PROJECT_DIR}/.claude/.claudesay-active"
 
 PROTOCOL='<claudesay-protocol>
 When giving a conversational reply, append this tag at the very end:
-<claudesay mood="MOOD">Brief 1-line summary of what you did or said</claudesay>
+<claudesay mood="MOOD">First-person summary of what I just did or said</claudesay>
 
 Available moods: happy, excited, thinking, focused, upset, error
 - happy / excited → success outcomes (rotate between them for variety)
@@ -16,9 +16,13 @@ Available moods: happy, excited, thinking, focused, upset, error
 - error           → actual failure
 
 Rules:
-- Keep message under 60 chars
-- Do NOT add the tag to: pure code blocks, diffs, long technical output, tool-only responses
-- Only chatty, conversational replies get a bubble
+- Up to ~120 chars. Bubble wraps at 45/line, so 1-2 short sentences.
+- First-person voice ("I fixed the flaky test and re-ran CI", not "Fixed the flaky test").
+  The character speaks AS the agent.
+- Cover the whole turn, not just the last sentence — if multiple things happened,
+  mention them briefly ("I read the hooks and drafted a plan.").
+- Do NOT add the tag to: pure code blocks, diffs, long technical output, tool-only responses.
+- Only chatty, conversational replies get a bubble.
 </claudesay-protocol>'
 
 printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":%s}}\n' \

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "claudesay",`
`3`		`- "version": "2.1.0",`
	`3`	`+ "version": "2.2.0",`
`4`	`4`	`"description": "Renders Claude replies as ASCII character speech bubbles",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "TimJJTing"`