chore: bump version to 0.2.3

install.sh now copies hooks-handlers/*.py and hooks.json into the live
cache dir after symlinking — ensures edits take effect in the running
session without a CC restart for hook scripts, and on next session start
for hooks.json changes.

Also manually synced 0.1.0 cache to unblock current session:
- post-tool-use.py: find_catalog + already-owned spawn guard
- user-prompt-submit.py: null buddymon_id fallback
- roster-stop.py: reads roster_output.txt (no recursive CLI call)
- hooks.json: roster-stop.py Stop hook entry

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "buddymon",
-  "description": "Collectible creatures discovered through coding — commit streaks, bug fights, and session challenges",
+  "description": "Collectible creatures discovered through coding \u2014 commit streaks, bug fights, and session challenges",
-  "version": "0.1.0",
+  "version": "0.2.3",
   "author": {
     "name": "CircuitForge LLC",
     "email": "hello@circuitforge.tech"

hooks-handlers/post-tool-use.py

@@ -20,9 +20,31 @@ import random
 from pathlib import Path
 from datetime import datetime
 
-PLUGIN_ROOT = os.environ.get("CLAUDE_PLUGIN_ROOT", str(Path(__file__).parent.parent))
 BUDDYMON_DIR = Path.home() / ".claude" / "buddymon"
-CATALOG_FILE = Path(PLUGIN_ROOT) / "lib" / "catalog.json"
+
+
+def find_catalog() -> dict:
+    """Load catalog from the first candidate path that exists.
+
+    Checks the user-local copy installed by install.sh first, so the
+    current catalog is always used regardless of which plugin cache version
+    CLAUDE_PLUGIN_ROOT points to.
+    """
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", str(Path(__file__).parent.parent))
+    candidates = [
+        # User-local copy: always matches the live dev/install version
+        BUDDYMON_DIR / "catalog.json",
+        Path(plugin_root) / "lib" / "catalog.json",
+        Path.home() / ".claude/plugins/cache/circuitforge/buddymon/0.1.1/lib/catalog.json",
+        Path.home() / ".claude/plugins/marketplaces/circuitforge/plugins/buddymon/lib/catalog.json",
+    ]
+    for p in candidates:
+        if p and p.exists():
+            try:
+                return json.loads(p.read_text())
+            except Exception:
+                continue
+    return {}
 
 # Each CC session gets its own state file keyed by process group ID.
 # All hooks within one session share the same PGRP, giving stable per-session state.
@@ -33,14 +55,13 @@ SESSION_FILE = BUDDYMON_DIR / "sessions" / f"{SESSION_KEY}.json"
 def get_session_state() -> dict:
     """Read the current session's state file, falling back to global active.json."""
     session = load_json(SESSION_FILE)
-    if not session:
+    # Fall back when file is missing OR when buddymon_id is null (e.g. pgrp mismatch
-        # No session file yet — inherit from global default
+    # between the CLI process that ran evolve/assign and this hook process).
+    if not session.get("buddymon_id"):
         global_active = load_json(BUDDYMON_DIR / "active.json")
-        session = {
+        session["buddymon_id"] = global_active.get("buddymon_id")
-            "buddymon_id": global_active.get("buddymon_id"),
+        session.setdefault("challenge", global_active.get("challenge"))
-            "challenge": global_active.get("challenge"),
+        session.setdefault("session_xp", 0)
-            "session_xp": 0,
-        }
     return session
 
 
@@ -250,7 +271,18 @@ def is_starter_chosen():
 
 
 def get_active_buddy_id():
-    return get_session_state().get("buddymon_id")
+    """Return the active buddy ID, skipping any caught monster that slipped in."""
+    bid = get_session_state().get("buddymon_id")
+    if not bid:
+        return None
+    # Validate: caught bug/mascot types are trophies, not assignable buddies.
+    # If one ended up in state (e.g. from a state corruption), fall back to active.json.
+    roster = load_json(BUDDYMON_DIR / "roster.json")
+    mon_type = roster.get("owned", {}).get(bid, {}).get("type", "")
+    if mon_type in ("caught_bug_monster",):
+        fallback = load_json(BUDDYMON_DIR / "active.json")
+        bid = fallback.get("buddymon_id", bid)
+    return bid
 
 
 def get_active_encounter():
@@ -521,7 +553,7 @@ def main():
         BUDDYMON_DIR.mkdir(parents=True, exist_ok=True)
         sys.exit(0)
 
-    catalog = load_json(CATALOG_FILE)
+    catalog = find_catalog()
     buddy_id = get_active_buddy_id()
 
     # Look up display name
@@ -570,6 +602,24 @@ def main():
 
         existing = get_active_encounter()
 
+        if existing:
+            # Already-owned shortcut: dismiss immediately, no XP, no wound cycle.
+            # No point fighting something already in the collection.
+            enc_id = existing.get("id", "")
+            roster_quick = load_json(BUDDYMON_DIR / "roster.json")
+            owned_quick = roster_quick.get("owned", {})
+            if (enc_id in owned_quick
+                    and owned_quick[enc_id].get("type") in ("caught_bug_monster", "caught_language_mascot")
+                    and not existing.get("catch_pending")):
+                enc_data = load_json(BUDDYMON_DIR / "encounters.json")
+                enc_data.setdefault("history", []).append({**existing, "outcome": "dismissed_owned"})
+                enc_data["active_encounter"] = None
+                save_json(BUDDYMON_DIR / "encounters.json", enc_data)
+                messages.append(
+                    f"\n🔁 **{existing.get('display', enc_id)}** — already in your collection. Dismissed."
+                )
+                existing = None  # skip further processing this run
+
         if existing:
             # On a clean Bash run (monster patterns gone), respect catch_pending,
             # wound a healthy monster, or auto-resolve a wounded one.
@@ -635,6 +685,16 @@ def main():
             target = monster or event
 
             if target and random.random() < 0.70:
+                # Skip spawn if this monster is already in the collection —
+                # no point announcing something the player already caught.
+                target_id = target.get("id", "")
+                _owned = load_json(BUDDYMON_DIR / "roster.json").get("owned", {})
+                already_owned = (target_id in _owned
+                                 and _owned[target_id].get("type")
+                                 in ("caught_bug_monster", "caught_language_mascot"))
+                if already_owned:
+                    pass  # silently skip
+                else:
                     if monster:
                         strength = compute_strength(monster, elapsed_minutes=0)
                     else:
@@ -674,11 +734,9 @@ def main():
             ext = os.path.splitext(file_path)[1].lower()
             lang = KNOWN_EXTENSIONS.get(ext)
             if lang:
-                # Session-level "first encounter" bonus — only announce if genuinely new
+                # Fire "new language" bonus only when affinity XP is genuinely zero.
-                # (zero affinity XP). Languages already in the roster just get quiet XP.
+                # Affinity XP in roster.json is the reliable persistent signal;
-                seen = get_languages_seen()
+                # session.json languages_seen was volatile and caused false positives.
-                if lang not in seen:
-                    add_language_seen(lang)
                 affinity = get_language_affinity(lang)
                 if affinity.get("xp", 0) == 0:
                     add_session_xp(15)

hooks-handlers/roster-stop.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""
+Buddymon Stop hook — roster re-emitter.
+
+Checks for roster_pending.txt written by `cli.py roster`.
+If present, runs the roster CLI and emits full output as additionalContext,
+guaranteeing the full roster is visible without Bash-tool truncation.
+"""
+import json
+import sys
+from pathlib import Path
+
+BUDDYMON_DIR   = Path.home() / ".claude" / "buddymon"
+PENDING_FLAG   = BUDDYMON_DIR / "roster_pending.txt"
+OUTPUT_FILE    = BUDDYMON_DIR / "roster_output.txt"
+
+
+def main():
+    try:
+        json.load(sys.stdin)
+    except Exception:
+        pass
+
+    if not PENDING_FLAG.exists():
+        sys.exit(0)
+
+    # Clear both files before reading — prevents a second Stop event from
+    # re-delivering the same roster if OUTPUT_FILE lingers.
+    PENDING_FLAG.unlink(missing_ok=True)
+
+    if not OUTPUT_FILE.exists():
+        sys.exit(0)
+
+    output = OUTPUT_FILE.read_text().strip()
+    OUTPUT_FILE.unlink(missing_ok=True)
+
+    if not output:
+        sys.exit(0)
+
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "Stop",
+            "additionalContext": output,
+        }
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

hooks-handlers/user-prompt-submit.py

@@ -23,7 +23,11 @@ SESSION_FILE = BUDDYMON_DIR / "sessions" / f"{SESSION_KEY}.json"
 def get_session_state() -> dict:
     try:
         with open(SESSION_FILE) as f:
-            return json.load(f)
+            data = json.load(f)
+        # Fall through when file exists but buddymon_id is null (pgrp mismatch).
+        if not data.get("buddymon_id"):
+            raise ValueError("null buddymon_id")
+        return data
     except Exception:
         global_active = {}
         try:

hooks/hooks.json

@@ -47,6 +47,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks-handlers/roster-stop.py",
+            "timeout": 10
+          }
+        ]
       }
     ]
   }

install.sh

@@ -287,6 +287,19 @@ PYEOF
     chmod +x "${BUDDYMON_DIR}/cli.py"
     ok "Installed cli.py → ${BUDDYMON_DIR}/cli.py"
 
+    cp "${REPO_DIR}/lib/catalog.json" "${BUDDYMON_DIR}/catalog.json"
+    ok "Installed catalog.json → ${BUDDYMON_DIR}/catalog.json"
+
+    # Sync hooks-handlers and hooks.json into the live cache so edits take effect
+    # without waiting for a CC plugin-cache refresh. CC re-reads hook scripts on
+    # every invocation but only reads hooks.json at session start.
+    if [[ -d "${CACHE_DIR}/hooks-handlers" ]]; then
+        cp "${REPO_DIR}/hooks-handlers/"*.py "${CACHE_DIR}/hooks-handlers/"
+        cp "${REPO_DIR}/hooks-handlers/"*.sh "${CACHE_DIR}/hooks-handlers/" 2>/dev/null || true
+        cp "${REPO_DIR}/hooks/hooks.json"    "${CACHE_DIR}/hooks/hooks.json"
+        ok "Synced hooks-handlers + hooks.json → ${CACHE_DIR}/"
+    fi
+
     # Install statusline into settings.json if not already configured
     python3 << PYEOF
 import json

lib/cli.py

@@ -26,8 +26,10 @@ def find_catalog() -> dict:
     pr = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
     candidates = [
         Path(pr) / "lib" / "catalog.json" if pr else None,
-        Path.home() / ".claude/plugins/cache/circuitforge/buddymon/0.1.0/lib/catalog.json",
+        # User-local copy updated by install.sh — checked before stale plugin cache
+        BUDDYMON_DIR / "catalog.json",
         Path.home() / ".claude/plugins/cache/circuitforge/buddymon/0.1.1/lib/catalog.json",
+        Path.home() / ".claude/plugins/cache/circuitforge/buddymon/0.1.0/lib/catalog.json",
         Path.home() / ".claude/plugins/marketplaces/circuitforge/plugins/buddymon/lib/catalog.json",
     ]
     for p in candidates:
@@ -412,89 +414,204 @@ def cmd_catch(args: list[str]):
             print(f"💨 {display} broke free! Weaken it further and try again. ({int(catch_rate * 100)}% catch rate)")
 
 
+def _evo_chain_label(bid: str, owned: dict, catalog: dict) -> str:
+    """Build a short evolution chain string: A → B → C with current marked."""
+    # Walk backwards to find root
+    root = bid
+    while True:
+        prev = owned.get(root, {}).get("evolved_from") or catalog.get("evolutions", {}).get(root, {}).get("evolves_from")
+        if not prev or prev not in owned:
+            break
+        root = prev
+    # Walk forward
+    chain = [root]
+    cur = root
+    while True:
+        nxt = owned.get(cur, {}).get("evolved_into")
+        if not nxt or nxt not in owned:
+            break
+        chain.append(nxt)
+        cur = nxt
+    if len(chain) < 2:
+        return ""
+    return " → ".join(
+        f"[{n}]" if n == bid else n
+        for n in chain
+    )
+
+
 def cmd_roster():
+    import io as _io
+    _buf = _io.StringIO()
+
+    def _p(*args, **kwargs):
+        """print() that writes to the buffer instead of stdout."""
+        kwargs.setdefault("file", _buf)
+        print(*args, **kwargs)
+
     roster = load(BUDDYMON_DIR / "roster.json")
     owned = roster.get("owned", {})
+    active_bid = get_buddy_id() or load(BUDDYMON_DIR / "active.json").get("buddymon_id")
 
     try:
         catalog = find_catalog()
     except Exception:
         catalog = {}
     mascot_catalog = catalog.get("language_mascots", {})
+    bug_catalog   = catalog.get("bug_monsters", {})
 
     core_buddymon  = {k: v for k, v in owned.items()
                       if v.get("type") not in ("caught_bug_monster", "caught_language_mascot")}
     mascots_owned  = {k: v for k, v in owned.items() if v.get("type") == "caught_language_mascot"}
-    caught = {k: v for k, v in owned.items() if v.get("type") == "caught_bug_monster"}
+    caught_bugs    = {k: v for k, v in owned.items() if v.get("type") == "caught_bug_monster"}
 
-    print("🐾 Your Buddymon")
+    total_owned    = len(core_buddymon) + len(mascots_owned) + len(caught_bugs)
-    print("─" * 44)
+    bug_total      = len(bug_catalog)
-    for bid, b in core_buddymon.items():
+    mascot_total   = len(mascot_catalog)
+
+    W = 52
+    owned_tag = f"{total_owned} owned"
+    pad = W - 10 - len(owned_tag)
+    _p("╔" + "═" * W + "╗")
+    _p(f"║  🐾 ROSTER{' ' * pad}{owned_tag}  ║")
+    _p("╚" + "═" * W + "╝")
+
+    # ── BUDDYMON ──────────────────────────────────────────────
+    _p()
+    _p("── BUDDYMON  ✓ levels via XP · assignable " + "─" * 8)
+    for bid, b in sorted(core_buddymon.items(),
+                         key=lambda x: -x[1].get("xp", 0)):
         lvl      = b.get("level", 1)
         total_xp = b.get("xp", 0)
         max_xp   = lvl * 100
-        xp_in_level = total_xp % max_xp if max_xp else 0
+        xp_in    = total_xp % max_xp if max_xp else 0
-        bar = xp_bar(xp_in_level, max_xp)
+        bar      = xp_bar(xp_in, max_xp, width=16)
         display  = b.get("display", bid)
         affinity = b.get("affinity", "")
-        evo_note = f"  → {b['evolved_into']}" if b.get("evolved_into") else ""
+        aff_tag  = f"  [{affinity}]" if affinity else ""
-        print(f"  {display}  Lv.{lvl}  {affinity}{evo_note}")
-        print(f"     XP: [{bar}] {xp_in_level}/{max_xp}")
 
+        active_tag = "  ← ACTIVE" if bid == active_bid else ""
+        chain      = _evo_chain_label(bid, owned, catalog)
+
+        cat_entry  = catalog.get("buddymon", {}).get(bid) or catalog.get("evolutions", {}).get(bid) or {}
+        evos       = cat_entry.get("evolutions", [])
+        next_evo   = next((e for e in evos if lvl < e.get("level", 999)), None)
+
+        _p()
+        _p(f"  {display}{aff_tag}{active_tag}")
+        _p(f"  {'Lv.' + str(lvl):<8}  XP: [{bar}] {xp_in}/{max_xp}")
+        if chain:
+            _p(f"  chain: {chain}")
+        if next_evo:
+            gap = next_evo["level"] - lvl
+            _p(f"  → evolves to {next_evo['into']} at Lv.{next_evo['level']}  ({gap} levels to go)")
+        elif b.get("evolved_into") and b["evolved_into"] in owned:
+            _p(f"  ✓ fully evolved")
+
+    # ── LANGUAGE MASCOTS ──────────────────────────────────────
+    _p()
+    _p("── LANGUAGE MASCOTS  ✓ levels via XP · assignable " + "─" * 1)
     if mascots_owned:
-        print()
+        for bid, b in sorted(mascots_owned.items(),
-        print("🦎 Language Mascots")
+                             key=lambda x: -x[1].get("xp", 0)):
-        print("─" * 44)
-        for bid, b in sorted(mascots_owned.items(), key=lambda x: x[1].get("caught_at", ""), reverse=True):
             display  = b.get("display", bid)
             lang     = b.get("language", "")
-            caught_at = b.get("caught_at", "")[:10]
             lvl      = b.get("level", 1)
+            total_xp = b.get("xp", 0)
+            max_xp   = lvl * 100
+            xp_in    = total_xp % max_xp if max_xp else 0
+            bar      = xp_bar(xp_in, max_xp, width=16)
             mc       = mascot_catalog.get(bid, {})
-            assignable = mc.get("assignable", False)
+            elem     = mc.get("element", "")
-            assign_note = "  ✓ assignable as buddy" if assignable else ""
+            elem_tag = f"  [{elem}]" if elem else ""
-            evo_chains = mc.get("evolutions", [])
+            evos     = mc.get("evolutions", [])
-            evo_note = f"  → evolves at Lv.{evo_chains[0]['level']}" if evo_chains else ""
+            next_evo = next((e for e in evos if lvl < e.get("level", 999)), None)
-            print(f"  {display}  [{lang}]  Lv.{lvl}{assign_note}{evo_note}")
+            active_tag = "  ← ACTIVE" if bid == active_bid else ""
-            print(f"     caught {caught_at}")
 
-    if caught:
+            _p()
-        print()
+            _p(f"  {display}  [{lang}]{elem_tag}{active_tag}")
-        print("🏆 Caught Bug Monsters")
+            _p(f"  {'Lv.' + str(lvl):<8}  XP: [{bar}] {xp_in}/{max_xp}")
-        print("─" * 44)
+            if next_evo:
-        for bid, b in sorted(caught.items(), key=lambda x: x[1].get("caught_at", ""), reverse=True):
+                _p(f"  → evolves to {next_evo['into']} at Lv.{next_evo['level']}")
-            display = b.get("display", bid)
+    else:
-            caught_at = b.get("caught_at", "")[:10]
+        _p(f"  (none yet — code in Python, JS, Rust… to encounter them)")
-            print(f"  {display}  — caught {caught_at}")
+        _p(f"  {mascot_total} species to discover across {len(set(m.get('rarity','') for m in mascot_catalog.values()))} rarity tiers")
 
+    # ── LANGUAGE AFFINITIES ───────────────────────────────────
     affinities = roster.get("language_affinities", {})
     if affinities:
-        print()
+        _p()
-        print("🗺️  Language Affinities")
+        _p("── LANGUAGE AFFINITIES  ◑ passive · levels via edits " + "─" * 0)
-        print("─" * 44)
         for lang, data in sorted(affinities.items(), key=lambda x: -x[1].get("xp", 0)):
             tier   = data.get("tier", "discovering")
             level  = data.get("level", 0)
             xp     = data.get("xp", 0)
             emoji  = TIER_EMOJI.get(tier, "🔭")
             elem   = LANGUAGE_ELEMENTS.get(lang, "")
-            elem_tag = f"  [{elem}]" if elem else ""
+            e_tag  = f"[{elem}]" if elem else ""
-            # Flag languages that have a spawnable mascot
             has_mascot = any(m.get("language") == lang for m in mascot_catalog.values())
-            mascot_tag = "  🦎" if has_mascot and level >= 1 else ""
+            m_tag  = " 🦎" if has_mascot else ""
-            print(f"  {emoji}  {lang:<12} {tier:<12} (Lv.{level}  · {xp} XP){elem_tag}{mascot_tag}")
+            _p(f"  {emoji}  {lang:<13} {tier:<12} Lv.{level:<3} · {xp:>5} XP  {e_tag}{m_tag}")
 
-    bug_total = len(catalog.get("bug_monsters", {}))
+    # ── BUG TROPHY CASE ───────────────────────────────────────
-    mascot_total = len(mascot_catalog)
+    _p()
-    missing_bugs = bug_total - len(caught)
+    caught_count = len(caught_bugs)
+    _p(f"── BUG TROPHY CASE  ✗ trophies only · no leveling  ({caught_count}/{bug_total}) " + "─" * 0)
+    if caught_bugs:
+        # Sort: notable (level>1 or has XP) first, then alpha
+        def bug_sort_key(item):
+            b = item[1]
+            notable = b.get("level", 1) > 1 or b.get("xp", 0) > 0
+            return (not notable, item[0])
+        items = sorted(caught_bugs.items(), key=bug_sort_key)
+        # Two-column grid — 28 chars per column; cap at COL so long names don't push
+        # the right column out of alignment.
+        COL = 28
+        for i in range(0, len(items), 2):
+            left_id, left  = items[i]
+            right_id, right = items[i + 1] if i + 1 < len(items) else (None, None)
+
+            def cell(bid, b):
+                if b is None:
+                    return ""
+                disp = b.get("display", bid)
+                lvl  = b.get("level", 1)
+                bc   = bug_catalog.get(bid, {})
+                weak = bc.get("weak_against", [])
+                elem = f"[{weak[0]}]" if weak else ""
+                lvl_tag = f" Lv.{lvl}" if lvl > 1 else ""
+                cell_str = f"{disp}{lvl_tag} {elem}".strip()
+                return cell_str[:COL].ljust(COL)
+
+            l = cell(left_id, left)
+            r = cell(right_id, right) if right else ""
+            _p(f"  {l}  {r}".rstrip())
+    else:
+        _p("  none yet")
+
+    # ── DISCOVERY FOOTER ──────────────────────────────────────
+    missing_bugs    = bug_total    - len(caught_bugs)
     missing_mascots = mascot_total - len(mascots_owned)
     if missing_bugs + missing_mascots > 0:
         parts = []
-        if missing_bugs > 0:
+        if missing_bugs    > 0: parts.append(f"{missing_bugs} bug monsters")
-            parts.append(f"{missing_bugs} bug monsters")
+        if missing_mascots > 0: parts.append(f"{missing_mascots} mascots")
-        if missing_mascots > 0:
+        _p(f"\n  ❓ ??? — {' and '.join(parts)} still to discover")
-            parts.append(f"{missing_mascots} language mascots")
+
-        print(f"\n❓ ??? — {' and '.join(parts)} still to discover...")
+    # Write roster output to a file for the Stop hook to deliver as additionalContext.
+    # The Stop hook reads roster_output.txt directly — it does NOT re-run this command,
+    # avoiding any recursive flag-write loop.
+    output_text = _buf.getvalue()
+    roster_output = BUDDYMON_DIR / "roster_output.txt"
+    roster_pending = BUDDYMON_DIR / "roster_pending.txt"
+    roster_output.write_text(output_text)
+    roster_pending.write_text("1")
+
+    # Print to stdout only when running interactively (direct terminal use).
+    # When called from a skill via Bash (piped), output is silent — the Stop
+    # hook delivers it as additionalContext instead.
+    if sys.stdout.isatty():
+        sys.stdout.write(output_text)
 
 
 def cmd_start(choice: str | None = None):