hail-hydra-cc 2.0.3 → 2.0.4

package/README.md

@@ -56,18 +56,21 @@ npx hail-hydra-cc --help         # Show help
 │   ├── hydra-coder.md
 │   ├── hydra-analyst.md
 │   └── hydra-sentinel.md
-├── commands/hydra/              # 7 slash commands
+├── commands/hydra/              # 8 slash commands
 │   ├── help.md                  # /hydra:help
 │   ├── status.md                # /hydra:status
 │   ├── update.md                # /hydra:update
 │   ├── config.md                # /hydra:config
 │   ├── guard.md                 # /hydra:guard
 │   ├── quiet.md                 # /hydra:quiet
-│   └── verbose.md               # /hydra:verbose
-├── hooks/                       # 3 lifecycle hooks
+│   ├── verbose.md               # /hydra:verbose
+│   └── report.md                # /hydra:report
+├── hooks/                       # 4 lifecycle hooks
 │   ├── hydra-check-update.js    # SessionStart — version check
 │   ├── hydra-statusline.js      # StatusLine — status bar
-│   └── hydra-auto-guard.js      # PostToolUse — file tracker
+│   ├── hydra-auto-guard.js      # PostToolUse — file tracker
+│   ├── hydra-notify.js          # Notification — task completion sound
+│   └── hydra-task-complete.wav  # Notification sound file
 └── skills/hydra/                # Skill (Claude Code discoverable via /skills)
     ├── SKILL.md                 # Orchestrator instructions
     ├── VERSION                  # Installed version

package/files/SKILL.md

@@ -14,6 +14,49 @@ description: >
 > *"Cut off one head, two more shall take its place."*
 > Except here — every head is doing your work faster and cheaper.
 
+## ⛔ MANDATORY PROTOCOLS — NEVER SKIP
+
+These protocols are NON-NEGOTIABLE. Skipping them is a framework violation.
+
+### Protocol 1: Sentinel Scan After Code Changes
+
+When ANY agent returns output containing `⚠️ HYDRA_SENTINEL_REQUIRED`, you
+MUST — before doing ANYTHING else, before presenting results to the user,
+before running any other agents — dispatch hydra-sentinel-scan with the
+files and changes listed in the trigger block.
+
+**This is blocking.** The user does NOT see the code changes until sentinel
+completes. If you present code changes to the user without running sentinel
+first, you have violated the framework's core safety guarantee.
+
+Sequence:
+1. Receive agent output containing ⚠️ HYDRA_SENTINEL_REQUIRED
+2. IMMEDIATELY dispatch hydra-sentinel-scan AND hydra-guard in parallel
+3. WAIT for both to complete
+4. If sentinel-scan finds issues → dispatch hydra-sentinel (deep analysis)
+5. WAIT for deep analysis
+6. THEN — and ONLY then — present results to the user
+
+If the agent output contains `✅ HYDRA_NO_CODE_CHANGES`, skip sentinel. Present
+results immediately.
+
+### Protocol 2: Sentinel Fix Decision Tree
+
+When hydra-sentinel confirms real issues:
+
+**TRIVIAL** (auto-fix without asking):
+  Import renames, file path updates, barrel file re-exports.
+  → Dispatch hydra-coder to fix. Re-run sentinel-scan to verify.
+  → Tell user: "Sentinel caught [issue]. Auto-fixed."
+
+**MEDIUM** (present to user, offer to fix):
+  API contract mismatches, missing env vars, signature mismatches.
+  → Show the sentinel report. Ask: "Want me to fix these?"
+
+**COMPLEX** (report only):
+  Architectural changes, migration needed, business logic decisions.
+  → Show the report. Let user decide.
+
 ## Why Hydra Exists
 
 Autoregressive LLM inference is memory-bandwidth bound — the time per token scales with model
@@ -505,6 +548,10 @@ When manual verification is required, match depth to risk:
 
 ## Sentinel Protocol — Integration Integrity
 
+> **REMINDER:** If you see `⚠️ HYDRA_SENTINEL_REQUIRED` in any agent's output
+> and you skip sentinel, you are violating the framework's core protocol.
+> See "⛔ MANDATORY PROTOCOLS" at the top of this document.
+
 After EVERY code change made by hydra-coder or hydra-analyst (or yourself),
 you MUST run the sentinel pipeline BEFORE presenting results to the user.
 
@@ -703,6 +750,19 @@ Note: Savings calculated against Opus 4.6 pricing ($5/$25 per MTok) as of Februa
   "Re-executing [task] directly — [agent]'s output was insufficient because [reason]"
 - **If accepted as-is**, no inline comment needed — the dispatch log covers it
 
+### Sentinel Status in Dispatch Log
+
+The dispatch log MUST show sentinel status for every task involving code changes:
+
+| Step | Agent | Task | Verdict |
+|------|-------|------|---------|
+| 1 | hydra-coder (Sonnet 4.6) | Fixed auth bug | ✅ Accepted |
+| 2 | hydra-sentinel-scan (Haiku) | Integration sweep | ✅ Clean |
+| 3 | hydra-guard (Haiku 4.5) | Security scan | ✅ Clean |
+
+If sentinel-scan is missing from the dispatch log after a code change,
+something went wrong. This is your self-check.
+
 ### Controlling the Dispatch Log
 
 - **Default**: ON — always shown when 2+ agents were used
@@ -887,6 +947,21 @@ Track these mentally to calibrate:
 If rejection rate > 20%, you're too aggressive — shift borderline tasks up one tier.
 If rejection rate < 5%, you're too conservative — delegate more.
 
+## Task Completion Notification
+
+After completing a user's task (the final response you present to the user),
+run this command as the LAST action:
+```bash
+node ~/.claude/hooks/hydra-notify.js < /dev/null
+```
+
+This plays a short notification sound so the user knows you're done —
+especially useful when they've tabbed away while waiting.
+
+Do this for SUBSTANTIAL tasks only (tasks that took more than ~10 seconds).
+Do NOT play it for quick conversational responses, acknowledgments, or
+follow-up questions.
+
 ## Reference Material
 
 - `references/routing-guide.md` — Mandatory delegation examples, decision flowchart

package/files/commands/hydra/help.md

@@ -17,6 +17,7 @@ COMMANDS
   /hydra:guard     Run security scan on files (usage: /hydra:guard src/auth.py)
   /hydra:quiet     Suppress dispatch logs for this session
   /hydra:verbose   Enable verbose dispatch logs with timing
+  /hydra:report    Report a bug, request a feature, or share feedback
 
 AGENTS
   🟢 hydra-scout    (Haiku 4.5)   — Explore codebase, find files, map structure

package/files/commands/hydra/quiet.md

@@ -12,3 +12,5 @@ Respond with:
 "🐉 Quiet mode enabled. Dispatch logs suppressed for this session. Use /hydra:verbose to re-enable."
 
 Continue operating Hydra normally (delegation, verification, auto-guard) — just don't show the dispatch log table.
+
+Also suppress the task completion notification sound for this session.

package/files/commands/hydra/report.md

@@ -0,0 +1,112 @@
+---
+description: Report a bug, request a feature, or share feedback about Hydra
+allowed-tools: Bash
+---
+
+# Hydra Report
+
+Walk the user through submitting a bug report, feature request, or general feedback for the Hydra framework. Follow these steps interactively:
+
+## Step 1 — Ask report type
+
+Ask the user:
+
+```
+🐉 What would you like to report?
+
+  1. 🐛 Bug Report — something is broken or not working as expected
+  2. ✨ Feature Request — an idea for a new feature or improvement
+  3. 💬 General Feedback — anything else you'd like to share
+
+Enter 1, 2, or 3:
+```
+
+Wait for their response. Map:
+- 1 → label: `bug`, template: Bug Report
+- 2 → label: `enhancement`, template: Feature Request
+- 3 → label: `feedback`, template: General Feedback
+
+## Step 2 — Collect description
+
+Ask the user to describe the issue or idea:
+
+```
+Describe the [bug/feature/feedback] in a few sentences:
+```
+
+For bugs, also ask:
+```
+Steps to reproduce (if applicable):
+```
+
+## Step 3 — Collect system info (optional)
+
+Ask: "Include system info in the report? (recommended for bugs) [Y/n]"
+
+If yes, gather:
+```bash
+# Hydra version
+cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "not found"
+```
+```bash
+# OS info
+node -e "console.log(process.platform + ' ' + process.arch + ' ' + require('os').release())"
+```
+```bash
+# Agent count
+ls ~/.claude/agents/hydra-*.md 2>/dev/null | wc -l
+```
+
+Format as a "System Info" section in the report.
+
+## Step 4 — Submit via GitHub CLI or fallback
+
+Check if `gh` CLI is available:
+```bash
+gh --version 2>/dev/null
+```
+
+### If `gh` is installed, check auth:
+```bash
+gh auth status 2>/dev/null
+```
+
+### If authenticated → create issue directly:
+```bash
+gh issue create \
+  --repo AR6420/Hail_Hydra \
+  --title "<concise title based on description>" \
+  --label "<bug|enhancement|feedback>" \
+  --body "<formatted report body>"
+```
+
+Show the resulting issue URL to the user.
+
+### If `gh` is installed but NOT authenticated:
+
+Tell the user:
+```
+GitHub CLI is installed but not authenticated.
+Run this in your terminal to authenticate:
+
+  gh auth login
+
+Then try /hydra:report again.
+```
+
+### If `gh` is NOT installed → browser fallback:
+
+Construct a pre-filled GitHub issue URL and show it to the user:
+
+```
+GitHub CLI not found. You can submit your report via browser:
+
+  https://github.com/AR6420/Hail_Hydra/issues/new?template=<template>&title=<encoded-title>&labels=<label>&body=<encoded-body>
+
+Or install GitHub CLI: https://cli.github.com
+```
+
+Map template filenames:
+- bug → `bug_report.md`
+- enhancement → `feature_request.md`
+- feedback → `feedback.md`

package/files/commands/hydra/update.md

@@ -1,35 +1,78 @@
----
-description: Update the Hydra framework to the latest version from npm
-allowed-tools: Bash
----
-
-# Hydra Update
-
-Run the following steps to update Hydra to the latest version:
-
-1. First, check the current installed version:
-```bash
-   cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "VERSION file not found"
-```
-
-2. Check the latest available version on npm:
-```bash
-   npm view hail-hydra-cc version 2>/dev/null || echo "Package not found on npm"
-```
-
-3. If an update is available (versions differ), run the installer:
-```bash
-   npx hail-hydra-cc@latest --global
-```
-
-4. After installation completes, verify the new version:
-```bash
-   cat ~/.claude/skills/hydra/VERSION
-```
-
-5. Report to the user:
-   - If updated: "🐉 Hydra updated from [old] → [new]. All heads refreshed."
-   - If already current: "🐉 Hydra is already at the latest version ([version])."
-   - If error: Show the error and suggest running `npx hail-hydra-cc@latest --global` manually in their terminal.
-
-**Important**: After updating, the user should restart Claude Code to reload the updated agent files, commands, and hooks.
+---
+description: Update the Hydra framework to the latest version from npm
+allowed-tools: Bash, Read
+---
+
+# Hydra Update
+
+Run the following steps to update Hydra to the latest version:
+
+## Step 1 — Check versions
+
+```bash
+cat ~/.claude/skills/hydra/VERSION 2>/dev/null || echo "VERSION file not found"
+```
+```bash
+npm view hail-hydra-cc version 2>/dev/null || echo "Package not found on npm"
+```
+
+If the installed version matches the latest npm version, tell the user:
+"🐉 Hydra is already at the latest version ([version])."
+and stop here.
+
+## Step 2 — Show changelog preview
+
+Fetch the CHANGELOG from GitHub:
+```bash
+curl -sL "https://raw.githubusercontent.com/AR6420/Hail_Hydra/main/CHANGELOG.md"
+```
+
+Parse the changelog to extract entries between the installed version and the latest version. Display a formatted "What's New" section:
+
+```
+🐉 Hydra Update Available: [installed] → [latest]
+═══════════════════════════════════════════════════
+
+📋 What's New:
+[changelog entries for versions between installed and latest]
+```
+
+If the changelog fetch fails, skip the preview and continue with the update.
+
+## Step 3 — Show safety note
+
+Display:
+```
+⚠️  What gets replaced:
+   • Agent definitions (agents/*.md)
+   • SKILL.md, references, commands, hooks
+   • VERSION file
+
+✅ What's preserved:
+   • Your hydra.config.md settings
+   • Agent memory directories (memory/)
+   • CLAUDE.md orchestrator notes
+   • settings.json hook registrations (re-registered automatically)
+```
+
+## Step 4 — Ask for confirmation
+
+Ask the user: "Proceed with update? [Y/n]"
+
+If they decline, respond: "🐉 Update cancelled." and stop.
+
+## Step 5 — Run the update
+
+```bash
+npx hail-hydra-cc@latest --global
+```
+
+## Step 6 — Verify
+
+```bash
+cat ~/.claude/skills/hydra/VERSION
+```
+
+Report to the user:
+- If updated: "🐉 Hydra updated from [old] → [new]. All heads refreshed. Restart Claude Code to load the new files."
+- If error: Show the error and suggest running `npx hail-hydra-cc@latest --global` manually in their terminal.

package/files/commands/hydra/verbose.md

@@ -25,3 +25,5 @@ Total delegation time: 17.4s | Waves: 2
 
 Respond with:
 "🐉 Verbose mode enabled. Dispatch logs will include timing details. Use /hydra:quiet to suppress."
+
+Re-enable the task completion notification sound.

package/files/hooks/hydra-notify.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hydra Task Completion Notification
+ *
+ * Plays a short notification sound when Claude Code finishes a task.
+ * Cross-platform: macOS (afplay), Windows (PowerShell), Linux (paplay/aplay).
+ *
+ * Called by Claude Code's Notification hook — stdin receives JSON from
+ * the hook system, which we drain and discard to prevent EPIPE errors.
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// Drain stdin to prevent EPIPE when Claude Code pipes hook data
+process.stdin.resume();
+process.stdin.on('data', () => {});
+process.stdin.on('end', () => {});
+
+const wavFile = path.join(os.homedir(), '.claude', 'hooks', 'hydra-task-complete.wav');
+
+// Bail silently if the sound file is missing
+if (!fs.existsSync(wavFile)) {
+  process.exit(0);
+}
+
+const platform = process.platform;
+
+try {
+  let child;
+
+  if (platform === 'darwin') {
+    // macOS
+    child = spawn('afplay', [wavFile], {
+      detached: true,
+      stdio: 'ignore',
+    });
+  } else if (platform === 'win32') {
+    // Windows — use PowerShell to play the .wav
+    child = spawn('powershell', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `(New-Object Media.SoundPlayer '${wavFile.replace(/'/g, "''")}').PlaySync()`,
+    ], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+  } else {
+    // Linux — try paplay (PulseAudio) first, fall back to aplay (ALSA)
+    const paplay = spawn('paplay', [wavFile], {
+      detached: true,
+      stdio: 'ignore',
+    });
+
+    paplay.on('error', () => {
+      // paplay not available, try aplay
+      const aplay = spawn('aplay', [wavFile], {
+        detached: true,
+        stdio: 'ignore',
+      });
+      aplay.unref();
+      aplay.on('error', () => {}); // silently ignore if neither works
+    });
+
+    paplay.unref();
+    process.exit(0);
+  }
+
+  if (child) {
+    child.unref();
+  }
+} catch {
+  // Silently ignore errors — notification sound is non-critical
+}
+
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hail-hydra-cc",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Multi-headed speculative execution framework for Claude Code",
   "bin": {
     "hail-hydra-cc": "bin/cli.js"

package/src/display.js

@@ -42,8 +42,8 @@ function showInstallComplete(statusLineConfigured = true) {
   console.log(chalk.cyan.bold('  \uD83D\uDC09 Hail Hydra! Framework deployed and ready.'));
   console.log(chalk.gray('  ' + '\u2500'.repeat(45)));
   console.log(chalk.green(`    \u2714 9 agents installed`));
-  console.log(chalk.green(`    \u2714 7 slash commands installed`));
-  console.log(chalk.green(`    \u2714 3 hooks registered`));
+  console.log(chalk.green(`    \u2714 8 slash commands installed`));
+  console.log(chalk.green(`    \u2714 4 hooks registered`));
   if (statusLineConfigured) {
     console.log(chalk.green(`    \u2714 StatusLine configured`));
   } else {
@@ -141,7 +141,7 @@ function showStatusTable(globalStatus, localStatus) {
   // Global hooks (always ~/.claude/hooks/)
   console.log();
   console.log(chalk.bold('  Global Hooks (~/.claude/hooks/)'));
-  const hookKeys = ['hydra-check-update', 'hydra-statusline', 'hydra-auto-guard'];
+  const hookKeys = ['hydra-check-update', 'hydra-statusline', 'hydra-auto-guard', 'hydra-notify'];
   for (const key of hookKeys) {
     const dest = path.join(os.homedir(), '.claude', 'hooks', `${key}.js`);
     if (fileExists(dest)) {

package/src/files.js

@@ -80,12 +80,18 @@ const commands = {
   'guard':    readBundled('commands/hydra/guard.md'),
   'quiet':    readBundled('commands/hydra/quiet.md'),
   'verbose':  readBundled('commands/hydra/verbose.md'),
+  'report':   readBundled('commands/hydra/report.md'),
 };
 
 const hooks = {
   'hydra-check-update': readBundled('hooks/hydra-check-update.js'),
   'hydra-statusline':   readBundled('hooks/hydra-statusline.js'),
   'hydra-auto-guard':   readBundled('hooks/hydra-auto-guard.js'),
+  'hydra-notify':       readBundled('hooks/hydra-notify.js'),
 };
 
-module.exports = { agents, skill, references, commands, hooks };
+const binaryHooks = {
+  'hydra-task-complete.wav': path.join(FILES_DIR, 'hooks', 'hydra-task-complete.wav'),
+};
+
+module.exports = { agents, skill, references, commands, hooks, binaryHooks };

package/src/installer.js

@@ -5,7 +5,7 @@ const path = require('path');
 const os = require('os');
 const chalk = require('chalk');
 
-const { agents, skill, references, commands, hooks } = require('./files');
+const { agents, skill, references, commands, hooks, binaryHooks } = require('./files');
 const { showInstallHeader, showFileInstalled, showInstallComplete, showStatusTable, VERSION } = require('./display');
 
 // ── Install locations ────────────────────────────────────────────────────────
@@ -100,6 +100,17 @@ function installHooks() {
       showFileInstalled(`hooks/${key}.js`, false, err.message);
     }
   }
+
+  // Copy binary hook files (e.g., .wav) that can't be read as UTF-8 text
+  for (const [filename, srcPath] of Object.entries(binaryHooks)) {
+    const dest = path.join(hooksDir, filename);
+    try {
+      fs.copyFileSync(srcPath, dest);
+      showFileInstalled(`hooks/${filename}`, true);
+    } catch (err) {
+      showFileInstalled(`hooks/${filename}`, false, err.message);
+    }
+  }
 }
 
 function registerHooksInSettings() {
@@ -130,6 +141,12 @@ function registerHooksInSettings() {
     hooks:   [{ type: 'command', command: 'node ~/.claude/hooks/hydra-auto-guard.js' }]
   });
 
+  if (!settings.hooks.Notification) settings.hooks.Notification = [];
+  settings.hooks.Notification = settings.hooks.Notification.filter(x => !isHydraHook(x));
+  settings.hooks.Notification.push({
+    hooks: [{ type: 'command', command: 'node ~/.claude/hooks/hydra-notify.js' }]
+  });
+
   let statusLineConfigured = false;
   if (!settings.statusLine || (settings.statusLine.command && settings.statusLine.command.includes('hydra-'))) {
     settings.statusLine = {
@@ -161,6 +178,10 @@ function deregisterHooks() {
       settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(x => !isHydraHook(x));
       if (!settings.hooks.PostToolUse.length) delete settings.hooks.PostToolUse;
     }
+    if (settings.hooks?.Notification) {
+      settings.hooks.Notification = settings.hooks.Notification.filter(x => !isHydraHook(x));
+      if (!settings.hooks.Notification.length) delete settings.hooks.Notification;
+    }
     if (settings.hooks && !Object.keys(settings.hooks).length) delete settings.hooks;
 
     if (settings.statusLine?.command?.includes('hydra-')) delete settings.statusLine;
@@ -305,6 +326,15 @@ async function runUninstall({ interactive = true } = {}) {
     }
   }
 
+  // Remove binary hook files (e.g., .wav)
+  for (const filename of Object.keys(binaryHooks)) {
+    const dest = path.join(GLOBAL_BASE, 'hooks', filename);
+    if (fileExists(dest)) {
+      try { fs.unlinkSync(dest); console.log(chalk.green(`  \u2714 Removed hooks/${filename}`)); }
+      catch (err) { console.log(chalk.red(`  \u2716 Failed: hooks/${filename} \u2014 ${err.message}`)); }
+    }
+  }
+
   // Remove cache file
   const cacheFile = path.join(GLOBAL_BASE, 'cache', 'hydra-update-check.json');
   if (fileExists(cacheFile)) {