hail-hydra-cc 2.0.2 → 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
@@ -317,192 +360,128 @@ Deviate from this model only when:
 | Catastrophic test failure | Make final runner BLOCKING (something is fundamentally broken) |
 | Stale Session Index detected | Rebuild index; treat as Turn 1 |
 
-## Decomposition First Protocol
+## Mandatory Delegation Rules
 
-**Before executing ANY user request, decompose it.** This is not optional — it is the
-first step of every task. The whole point of Hydra is parallel execution, and you cannot
-parallelize what you haven't decomposed.
+These rules are BINDING. They are not heuristics, suggestions, or guidelines to consider. They are hard rules that determine whether YOU handle a task or DELEGATE it to a Hydra head. Violating these rules defeats the purpose of Hydra.
 
-### Step 1: Break the request into atomic subtasks
+### ALWAYS Delegate — No Exceptions
 
-An atomic subtask is one that can be fully handled by a single head independently.
-"Fix the auth bug" is atomic. "Fix the auth bug and add tests" is two subtasks.
+These task types MUST be delegated. You are NOT allowed to handle them yourself, regardless of how simple they seem.
 
-### Step 2: Map dependencies
+| Task Type | Delegate To | Why You Don't Do It |
+|-----------|-------------|---------------------|
+| File search / grep / find patterns | hydra-scout | Haiku is equally good at Glob/Grep and costs 95% less |
+| Read and summarize code or docs | hydra-scout | Reading files is mechanical — no Opus reasoning needed |
+| Run tests, builds, lints, type checks | hydra-runner | Executing commands and reporting output is mechanical |
+| Git operations (commit, branch, diff, log, stash) | hydra-git | Git commands are well-defined and deterministic |
+| Security/quality gate scans | hydra-guard | Pattern matching for secrets/issues is Haiku's strength |
+| Write/update docstrings, comments, changelogs | hydra-scribe | Descriptive writing from existing code is mechanical |
+| Implement features from clear specs | hydra-coder | Sonnet handles standard implementation patterns equally well |
+| Fix bugs with clear error messages/stack traces | hydra-coder | Error-driven debugging with clear clues is Sonnet-level |
+| Code review and PR analysis | hydra-analyst | Structured code analysis is Sonnet's sweet spot |
 
-For each subtask, ask: *does this require the output of another subtask?*
+**Self-check**: Before you start ANY task, ask: "Is this in the ALWAYS Delegate table?" If yes — delegate. No exceptions. No "but it's faster if I just..." No "it's only a small..." DELEGATE.
 
-- If NO → it can run in Wave 1
-- If it depends on Task A → it runs in the wave after Task A completes
+### ALWAYS Handle Yourself — Never Delegate
 
-### Step 3: Group into waves
+These task types stay with Opus. Delegating them wastes time or risks quality.
 
-A wave is a set of subtasks with no dependencies between them. All tasks in a wave
-launch simultaneously in a single message (multiple Task tool calls).
+| Task Type | Why You Keep It |
+|-----------|----------------|
+| Task classification and routing decisions | Only you see the full conversation context |
+| Verifying and synthesizing agent outputs | Judgment on whether a draft is acceptable requires orchestrator perspective |
+| System architecture and major design decisions | Novel architectural tradeoffs need Opus-level reasoning |
+| Ambiguous debugging with no clear clues | "It works in staging but not prod" needs deep investigation |
+| Context-dependent tasks requiring conversation history | Agents don't see prior turns — you do |
+| Trivial edits under 5 seconds (max 2-3 per session) | Delegation overhead exceeds task cost |
+| Planning and decomposition | Breaking tasks into waves IS the orchestrator's job |
+| Conversation management (clarification, alignment) | Only you talk to the user |
 
-### Step 4: Dispatch wave by wave
+### JUDGMENT CALLS — Use This Decision Framework
 
-Launch Wave 1 (all independent tasks) simultaneously. When Wave 1 completes, feed
-relevant outputs forward and launch Wave 2. Continue until all subtasks are done.
+For tasks NOT in either table above, apply this 3-step check:
 
-### The Cardinal Rule
+1. **Does it require conversation context?** (prior turns, user preferences, accumulated state)
+   - YES → Handle yourself. Agents don't have this context.
+2. **Can Haiku or Sonnet do this equally well?** (not "almost as well" — EQUALLY well)
+   - YES → Delegate. You're wasting money and time doing it yourself.
+   - NO → Handle yourself.
+3. **Would delegation take LONGER than doing it yourself?** (including prompt construction + wait time)
+   - YES, and the task is truly trivial → Handle yourself (counts toward overhead budget).
+   - NO or UNSURE → **Delegate.** This is the default. When in doubt, DELEGATE.
 
-> **NEVER dispatch sequentially when parallel is possible.**
-> Launching 3 Haiku agents simultaneously is always faster than launching them one at a time,
-> even if you have to wait for all three before continuing. A wave of 3 Haiku agents completes
-> in the time it takes 1 Haiku agent to finish, not 3× longer.
+### Parallel Dispatch — MANDATORY for Independent Subtasks
 
-### Quick Decomposition Example
+If a task decomposes into subtasks with no dependencies between them, you MUST dispatch them simultaneously in a single message. Sequential dispatch of independent tasks is a rule violation.
 
+**WRONG** (sequential — wastes time):
 ```
-User: "Fix the auth bug, add tests, and update the docs"
-
-Decomposition:
-  Task A: Explore auth module → hydra-scout   [no deps]
-  Task B: Run existing tests  → hydra-runner  [no deps]
-  Task C: Fix the bug         → hydra-coder   [depends on A]
-  Task D: Write new tests     → hydra-coder   [depends on C]
-  Task E: Run all tests       → hydra-runner  [depends on C, D]
-  Task F: Update docs         → hydra-scribe  [depends on C]
-
-Wave 1 → launch A + B simultaneously
-Wave 2 → launch C (using A's findings)
-Wave 3 → launch D + F simultaneously (both only need C)
-Wave 4 → launch E (needs D complete)
+Message 1: Launch hydra-scout to explore auth module
+[wait for result]
+Message 2: Launch hydra-runner to run existing tests
+[wait for result]
+Message 3: Launch hydra-scout to check test patterns
 ```
 
-## Task Classification Guide
-
-Classify every incoming task before executing. This is fast — just a mental check, not a separate
-step the user sees.
-
-### Tier 1 → Haiku 4.5 Heads (hydra-scout, hydra-runner, hydra-scribe, hydra-guard, hydra-git)
-
-Route to Haiku when the task is **mechanical, read-heavy, or well-defined**:
-
-- Searching/grepping across files
-- Reading and summarizing code or documentation
-- Running tests, lints, builds, format checks
-- Listing directory structures, finding files by pattern
-- Simple git operations (status, log, diff)
-- Generating boilerplate or repetitive code from clear templates
-- Writing/updating comments, docstrings, simple README sections
-- Quick factual lookups in the codebase
-- Security/quality gate scans on changed code (hydra-guard)
-- Git operations: staging, committing, branching, log inspection (hydra-git)
-
-**Heuristic**: If you could describe the task as a single imperative sentence with no ambiguity
-(e.g., "find all files importing X", "run the test suite"), it's Tier 1.
-
-### Tier 2 → Sonnet 4.6 Heads (hydra-coder, hydra-analyst)
-
-Route to Sonnet when the task requires **reasoning about code, but within well-understood patterns**:
-
-- Implementing a feature from a clear spec or description
-- Writing or modifying functions, classes, modules
-- Refactoring code (rename, extract, restructure)
-- Creating test cases that require understanding business logic
-- Debugging with stack traces or error messages as clues
-- Code review and suggesting improvements
-- Writing technical documentation that requires comprehension
-- Resolving straightforward merge conflicts
-- Making API integrations following documented patterns
-
-**Heuristic**: If you need to read, understand, and then produce code — but the approach is
-reasonably standard — it's Tier 2.
-
-### Tier 3 → Opus (handle directly, don't delegate)
-
-Keep it yourself when the task demands **deep reasoning, novel architecture, or high-stakes decisions**:
-
-- System architecture design and major refactoring decisions
-- Debugging subtle, non-obvious issues with no clear stack trace
-- Performance optimization requiring algorithmic insight
-- Security analysis and vulnerability assessment
-- Multi-file coordinated changes with complex interdependencies
-- Resolving ambiguous requirements that need clarification
-- Novel algorithm implementation
-- Tasks where getting it wrong would be very costly
-
-**Heuristic**: If you'd need to think hard even as Opus, don't delegate.
-
-### Edge Cases and Judgment Calls
+**RIGHT** (parallel — all independent):
+```
+Message 1: Launch hydra-scout (auth module) + hydra-runner (tests) + hydra-scout (test patterns)
+[all three return]
+Message 2: Launch dependent tasks using results from Message 1
+```
 
-- **When in doubt, go one tier up.** Better to use Sonnet for a Haiku task than Haiku for a
-  Sonnet task. Quality is never sacrificed.
-- **Compound tasks should be decomposed.** "Read the codebase and redesign the auth system"
-  becomes: hydra-scout reads, then you design (Opus).
-- **Iterative tasks escalate naturally.** If a Sonnet draft isn't right, don't retry with Sonnet —
-  do it yourself.
+**Trigger phrases that REQUIRE parallel dispatch:**
+- "...and..." (e.g., "fix the bug AND add tests" → scout + runner in parallel)
+- "...then..." where the "then" tasks are independent of each other
+- Any request with 2+ independent components
+- Any request where exploration and execution can overlap
 
-## Wave Execution Model
+### Delegation Overhead Budget
 
-Waves are the unit of parallel work in Hydra. Every multi-step task should be mapped
-to waves before any agent is dispatched.
+You are allowed a MAXIMUM of 2-3 "do it myself" exceptions per session for tasks that technically fall in the ALWAYS Delegate table but are genuinely trivial (e.g., adding a single `console.log` to a known file). Track this internally.
 
-### Rules for Wave Construction
+**Rules:**
+- If you've done 5+ tasks directly in a row without delegating, STOP. Re-read the ALWAYS Delegate table. You are almost certainly violating these rules.
+- "It's faster if I just do it" is not a valid exception after the 2-3 budget is spent.
+- The budget resets each session.
 
-1. **All tasks in a wave launch in a single message** — use multiple Task tool calls
-   in one response. Never send Wave 2 before Wave 1's results arrive.
-2. **Dependencies determine wave membership** — if Task B needs Task A's output, they
-   are in different waves. If they're independent, they're in the same wave.
-3. **Within a wave, order doesn't matter** — all tasks start simultaneously.
-4. **Between waves, results flow forward** — pass relevant context from each wave into
-   the prompts of the next wave's agents (see Handoff Protocol).
+### Plan Mode Behavior
 
-### Wave Execution Examples
+During planning phase (before execution begins):
+- Using Claude Code's built-in Explore agent is acceptable for quick codebase understanding.
+- No delegation rules apply yet — you're gathering context, not executing.
 
-#### Example 1: "Review this PR, fix the issues, and run the tests"
+Once execution begins (after plan is approved):
+- ALL mandatory delegation rules apply immediately.
+- **NEVER use the built-in Explore agent during execution when hydra-scout is available.** hydra-scout is faster and cheaper.
+- Plans MUST reference specific Hydra agents. Example format:
 
 ```
-Task A: Review PR changes     → hydra-analyst  [no deps]
-Task B: Check test coverage   → hydra-runner   [no deps]
-Task C: Fix identified issues → hydra-coder    [depends on A]
-Task D: Run full test suite   → hydra-runner   [depends on C]
-
-Wave 1 → A + B (parallel)
-Wave 2 → C (with A's findings as context)
-Wave 3 → D
+Step 1: hydra-scout → read auth module structure [parallel with Step 2]
+Step 2: hydra-runner → run existing test suite [parallel with Step 1]
+Step 3: hydra-coder → implement fix using findings from Steps 1-2
+Step 4: hydra-sentinel-scan + hydra-guard → verify changes [parallel]
+Step 5: hydra-runner → run tests to confirm fix
+Step 6: hydra-git → commit with descriptive message
 ```
 
-#### Example 2: "Set up a new feature: search endpoint with tests and docs"
+### Dispatch Logging
 
-```
-Task A: Map existing endpoints  → hydra-scout   [no deps]
-Task B: Map existing test style → hydra-scout   [no deps]
-Task C: Map existing doc style  → hydra-scout   [no deps]
-Task D: Implement endpoint      → hydra-coder   [depends on A]
-Task E: Write tests             → hydra-coder   [depends on A, B]
-Task F: Write API docs          → hydra-scribe  [depends on A, C]
-Task G: Run tests               → hydra-runner  [depends on E]
-
-Wave 1 → A + B + C (parallel — all pure exploration)
-Wave 2 → D + E + F (parallel — all depend only on Wave 1)
-Wave 3 → G
-```
-
-#### Example 3: "Debug why the payment service is slow, fix it, and verify"
+After every task completion (unless `/hydra:quiet` is active), show a dispatch summary:
 
 ```
-Task A: Profile payment service code  → hydra-analyst  [no deps]
-Task B: Check DB query patterns       → hydra-scout    [no deps]
-Task C: Run benchmark before fix      → hydra-runner   [no deps]
-Task D: Implement fix                 → hydra-coder    [depends on A, B]
-Task E: Run benchmark after fix       → hydra-runner   [depends on D]
-Task F: Update perf notes in README   → hydra-scribe   [depends on D]
-
-Wave 1 → A + B + C (parallel)
-Wave 2 → D (with A and B findings as context)
-Wave 3 → E + F (parallel)
+| Step | Agent | Task | Time |
+|------|-------|------|------|
+| 1 | hydra-scout | Explore auth module | 3.2s |
+| 2 | hydra-runner | Run test suite | 5.1s |
+| 3 | hydra-coder | Fix auth bug | 8.4s |
+| 4 | hydra-guard | Security scan | 2.1s |
+| 5 | hydra-runner | Verify fix | 4.8s |
+
+Delegation: 5/5 (100%) — Opus direct: 0
 ```
 
-### Why Waves Beat Sequential Dispatch
-
-- **3 Haiku agents in parallel** finish in ~1× the time of 1 agent
-- **3 Haiku agents sequentially** take ~3× the time
-- For a 4-wave workflow, parallelism within waves can cut total wall-clock time by 40-60%
-- The orchestrator (Opus) is not executing during waves — it's free to think about the
-  next wave while heads work
+If "Opus direct" exceeds "Delegation" count, the mandatory rules are not being followed. Re-read the ALWAYS Delegate table before continuing.
 
 ## Verification Protocol
 
@@ -569,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.
 
@@ -767,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
@@ -866,16 +862,8 @@ The user should never notice Hydra operating. Don't announce "I'm delegating to
 Don't explain the routing. Don't ask permission. Just do it. The user asked for a result, not
 a process narration. If a head does the work, present the output as if you did it.
 
-### Speed Over Ceremony
-Don't overthink classification. The whole point is speed. A quick mental "Haiku/Sonnet/Opus?"
-and go. If you spend 10 seconds classifying a 5-second task, you've defeated the purpose.
-
-### Parallel Heads
-Parallel dispatch is the default, not a bonus feature. Every multi-step request MUST be
-decomposed into waves before any agent is dispatched (see Decomposition First Protocol).
-Independent subtasks always launch simultaneously in a single message. Never dispatch
-sequentially when parallel is possible. The Wave Execution Model section has 3 concrete
-examples showing how to do this correctly.
+### Speed and Parallelism
+See "Mandatory Delegation Rules" for binding delegation and parallel dispatch rules.
 
 ### Escalate, Never Downgrade on Retry
 If Haiku's output wasn't good enough, don't try Haiku again or even Sonnet. Just do it yourself.
@@ -952,14 +940,29 @@ If the user types any of these exact phrases, respond with the corresponding act
 
 Track these mentally to calibrate:
 
-- **Delegation rate**: What % of tasks go to heads? Target: 60–80%.
+- **Delegation rate**: What % of tasks go to heads? Target: 60–70%.
 - **Rejection rate**: How often does a draft need Opus intervention? Target: <15%.
 - **User complaints**: Zero. If the user notices quality issues, tune the classification.
 
 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` — 30+ classification examples, decision flowchart
+- `references/routing-guide.md` — Mandatory delegation examples, decision flowchart
 - `references/model-capabilities.md` — What each model can and can't do

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/files/references/routing-guide.md

@@ -1,18 +1,18 @@
-# Routing Guide — Detailed Classification Examples
+# Routing Guide — Mandatory Delegation Examples
 
-This reference provides concrete examples to help calibrate task classification.
-Read this when you need to resolve ambiguous cases.
+This reference provides concrete examples to see mandatory delegation in action.
+Read this when you need to see how delegation rules apply to real tasks.
 
 ## Table of Contents
-1. [Tier 1 (Haiku 4.5) Examples](#tier-1-haiku)
-2. [Tier 2 (Sonnet 4.6) Examples](#tier-2-sonnet)
-3. [Tier 3 (Opus 4.6) Examples](#tier-3-opus)
+1. [ALWAYS Delegate — Haiku 4.5 Agents](#always-delegate-haiku)
+2. [ALWAYS Delegate — Sonnet 4.6 Agents](#always-delegate-sonnet)
+3. [ALWAYS Handle Yourself — Opus 4.6](#always-handle-yourself-opus)
 4. [Compound Task Decomposition](#compound-tasks)
 5. [Common Misclassifications](#common-misclassifications)
 
 ---
 
-## Tier 1 (Haiku 4.5)
+## ALWAYS Delegate — Haiku 4.5 Agents
 
 ### hydra-scout (Haiku 4.5) examples
 | User says | Route to | Why |
@@ -64,7 +64,7 @@ Read this when you need to resolve ambiguous cases.
 
 ---
 
-## Tier 2 (Sonnet 4.6)
+## ALWAYS Delegate — Sonnet 4.6 Agents
 
 ### hydra-coder (Sonnet 4.6) examples
 | User says | Route to | Why |
@@ -88,7 +88,7 @@ Read this when you need to resolve ambiguous cases.
 
 ---
 
-## Tier 3 (Opus 4.6 — handle directly)
+## ALWAYS Handle Yourself — Opus 4.6
 
 | User says | Why Opus? |
 |-----------|-----------|
@@ -147,48 +147,116 @@ These are tasks that look like one tier but are actually another:
 
 | Task | Looks like | Actually | Why |
 |------|-----------|----------|-----|
-| "Add a simple button" | Tier 1 (simple) | Tier 2 (Sonnet 4.6) | Needs to match existing component patterns |
-| "Read the logs and find the error" | Tier 1 (read) | Tier 2 (Sonnet 4.6) | Log analysis requires reasoning |
-| "Fix the typo in line 42" | Tier 2 (code change) | Tier 1 (Haiku 4.5) | Trivial mechanical change |
-| "Add caching" | Tier 2 (implementation) | Tier 3 (Opus 4.6) | Cache invalidation strategy is hard |
-| "Write a migration to add a column" | Tier 2 (code writing) | Tier 1 (Haiku 4.5) | Template-level SQL |
-| "Upgrade React from 17 to 18" | Tier 1 (simple) | Tier 3 (Opus 4.6) | Breaking changes need careful analysis |
+| "Add a simple button" | Haiku (simple) | hydra-coder (Sonnet) | Needs to match existing component patterns |
+| "Read the logs and find the error" | Haiku (read) | hydra-analyst (Sonnet) | Log analysis requires reasoning |
+| "Fix the typo in line 42" | hydra-coder (Sonnet) | hydra-scribe (Haiku) | Trivial mechanical change |
+| "Add caching" | hydra-coder (Sonnet) | Opus (handle yourself) | Cache invalidation strategy is hard |
+| "Write a migration to add a column" | hydra-coder (Sonnet) | hydra-scribe (Haiku) | Template-level SQL |
+| "Upgrade React from 17 to 18" | Haiku (simple) | Opus (handle yourself) | Breaking changes need careful analysis |
 
 ---
 
 ## Quick Decision Flowchart
 
 ```
-Is it read-only? ─── Yes ──→ Is it just finding/reading files?
-    │                              │
-    │                         Yes: hydra-scout (Haiku 4.5)
-    │                         No:  hydra-analyst (Sonnet 4.6)
-    │
-    No
-    │
-Is it a git operation? ─── Yes ──→ hydra-git (Haiku 4.5)
-    │
-    No
-    │
-Is it a security/quality scan? ─── Yes ──→ hydra-guard (Haiku 4.5)
-    │
-    No
-    │
-Is it just running a command? ─── Yes ──→ hydra-runner (Haiku 4.5)
-    │
-    No
-    │
-Is it writing docs/comments only? ─── Yes ──→ hydra-scribe (Haiku 4.5)
-    │
-    No
-    │
-Is the implementation approach clear? ─── Yes ──→ hydra-coder (Sonnet 4.6)
-    │
-    No
-    │
-Does it need architectural judgment? ─── Yes ──→ Opus 4.6 (you)
-    │
-    No ──→ hydra-coder (Sonnet 4.6), but monitor output closely
+Task arrives
+│
+├── In ALWAYS Delegate table? ── YES ──→ Route to specified agent
+│
+├── In ALWAYS Handle Yourself table? ── YES ──→ Opus handles directly
+│
+└── Neither? → JUDGMENT CALLS:
+    ├── Requires conversation context? ── YES ──→ Opus
+    ├── Haiku/Sonnet can do equally well? ── NO ──→ Opus
+    └── Delegation takes LONGER? ── YES (and truly trivial) ──→ Opus
+        └── Otherwise ──→ Delegate to best-fit agent
+```
+
+## Routing Examples — Mandatory Delegation
+
+These examples show the RIGHT and WRONG way to handle common requests under the mandatory delegation rules.
+
+### 1. "Fix the bug in auth.ts"
+
+**WRONG** (Opus does it all):
+```
+Read auth.ts yourself → find the bug → fix it → run tests
+```
+
+**RIGHT** (mandatory delegation):
+```
+1. hydra-scout → explore auth module, find the bug location
+2. hydra-analyst → analyze the bug, identify root cause
+3. hydra-coder → implement the fix
+4. hydra-sentinel-scan + hydra-guard → verify changes [parallel]
+5. hydra-runner → run tests to confirm fix
+```
+
+### 2. "What's the project structure?"
+
+**WRONG** (Opus runs find/ls itself):
+```
+Run `find . -type f` or `ls -R` yourself
+```
+
+**RIGHT** (mandatory delegation):
+```
+1. hydra-scout → map project structure, report back
+```
+
+### 3. "Run the tests"
+
+**WRONG** (Opus runs npm test itself):
+```
+Run `npm test` yourself
+```
+
+**RIGHT** (mandatory delegation):
+```
+1. hydra-runner → execute test suite, report results
+```
+
+### 4. "Commit these changes"
+
+**WRONG** (Opus runs git add/commit itself):
+```
+Run `git add . && git commit -m "..."` yourself
+```
+
+**RIGHT** (mandatory delegation):
+```
+1. hydra-git → stage and commit with well-crafted message
+```
+
+### 5. "This function is slow, figure out why"
+
+**RIGHT** (Opus orchestrates, delegates execution):
+```
+1. hydra-analyst → profile and diagnose the performance issue
+2. YOU → decide the optimization approach (architectural judgment)
+3. hydra-coder → implement the optimization
+4. hydra-runner → benchmark before and after
+```
+
+### 6. "Redesign the auth module to use OAuth2"
+
+**RIGHT** (Opus architects, delegates implementation):
+```
+1. hydra-scout → map current auth module structure [parallel with Step 2]
+2. hydra-scout → research OAuth2 patterns in codebase [parallel with Step 1]
+3. YOU → design the new architecture (this is YOUR job)
+4. hydra-coder #1 → implement OAuth2 provider [parallel with Steps 5-6]
+5. hydra-coder #2 → implement token management [parallel with Steps 4, 6]
+6. hydra-coder #3 → update route handlers [parallel with Steps 4-5]
+7. hydra-sentinel-scan → integration sweep on all changes
+8. hydra-runner → run full test suite
+```
+
+### 7. "Quick — add a console.log to line 5"
+
+**ACCEPTABLE** (trivial <5s edit — uses overhead budget):
+```
+YOU → add the console.log directly (counts as 1 of max 2-3 exceptions per session)
 ```
 
 ## Sentinel Routing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hail-hydra-cc",
-  "version": "2.0.2",
+  "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)) {