anvil-dev-framework 0.1.7 → 0.1.9

package/project/hooks/README.md

@@ -0,0 +1,491 @@
+# Claude Code Hooks
+
+Hooks integrate with Claude Code's lifecycle events to automate common tasks.
+
+## Available Hooks
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `session_start.py` | Session begins | Load context, log session |
+| `stop.py` | Claude stops | Log completion, announce via TTS |
+| `pre_compact.py` | Before compaction | Backup transcript |
+| `pre_tool_use.py` | Before tool execution | Safety checks, logging |
+| `post_tool_use.py` | After tool execution | Log tool usage, announcements |
+| `subagent_start.py` | Subagent begins | Inject context, log start |
+| `subagent_stop.py` | Subagent finishes | Log and announce |
+| `permission_request.py` | Permission requested | Auto-approve/deny logic |
+| `user_prompt_submit.py` | User submits prompt | Log prompts |
+| `notification.py` | Notification event | Custom notifications |
+
+## Hook Types Reference
+
+### Lifecycle Hooks
+- **SessionStart** — Fires when a new Claude Code session begins
+- **Stop** — Fires when Claude Code stops (user or automatic)
+- **PreCompact** — Fires before conversation compaction
+
+### Tool Hooks
+- **PreToolUse** — Fires before any tool is executed
+- **PostToolUse** — Fires after any tool completes
+- **PermissionRequest** — Fires when Claude requests tool permission (NEW in 2.0.45)
+
+### Subagent Hooks
+- **SubagentStart** — Fires when a subagent begins execution (NEW in 2.0.43)
+- **SubagentStop** — Fires when a subagent completes
+
+### Other Hooks
+- **UserPromptSubmit** — Fires when user submits a prompt
+- **Notification** — Fires on notification events
+
+## Installation
+
+1. Copy hooks to your project's `.claude/hooks/` directory
+2. Make executable: `chmod +x .claude/hooks/*.py`
+3. Configure in `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/session_start.py --load-context"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/stop.py"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/pre_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/post_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/subagent_start.py --log --inject-context"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/subagent_stop.py"
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/permission_request.py --log"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Requirements
+
+Hooks use `uv` for dependency management (inline script dependencies):
+```bash
+# Install uv if not present
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+## Optional: TTS Announcements
+
+For voice announcements when tasks complete:
+
+1. Copy `utils/tts/` directory to `.claude/hooks/utils/tts/`
+2. Set API key (choose one):
+   - `ELEVENLABS_API_KEY` — Best quality
+   - `OPENAI_API_KEY` — Good quality
+   - None — Falls back to pyttsx3 (local, no API)
+
+3. Add `--announce` flag to hooks:
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/stop.py --announce"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Optional: HUD (Multi-Agent Dashboard)
+
+For visibility into all active Claude Code sessions across projects:
+
+1. Enable agent registration in your hooks:
+```json
+{
+  "hooks": {
+    "session_start": [".claude/hooks/session_start.py --load-context --register-agent"],
+    "post_tool_use": [".claude/hooks/post_tool_use.py --update-agent"],
+    "stop": [".claude/hooks/stop.py --cleanup-agent"]
+  }
+}
+```
+
+2. Run the dashboard in a separate terminal:
+```bash
+uv run global/tools/anvil-hud.py
+```
+
+The HUD shows:
+- All active agents with context usage bars
+- Per-agent costs and workflow phases
+- Aggregate totals across all sessions
+
+Configure via `.claude/anvil.config.json`:
+```json
+{
+  "hud": {
+    "enabled": true,
+    "showAgentCount": true
+  }
+}
+```
+
+## Logs
+
+Hooks write logs to `logs/` directory:
+- `logs/session_start.json` — Session start events
+- `logs/stop.json` — Stop events
+- `logs/pre_compact.json` — Compaction events
+- `logs/pre_tool_use.json` — Pre-tool events
+- `logs/post_tool_use.json` — Post-tool events
+- `logs/subagent_start.json` — Subagent start events
+- `logs/subagent_stop.json` — Subagent stop events
+- `logs/permission_requests.json` — Permission request decisions
+- `logs/transcript_backups/` — Transcript backups
+
+## Customization
+
+### Adding Context at Session Start
+
+Edit `session_start.py` to load additional context files:
+```python
+context_files = [
+    ".claude/CONTEXT.md",
+    ".claude/TODO.md",
+    "docs/ARCHITECTURE.md",  # Add your own
+]
+```
+
+### Custom Stop Actions
+
+Edit `stop.py` to add actions when Claude finishes:
+```python
+# Example: Send notification
+def on_stop():
+    # Your custom logic here
+    pass
+```
+
+### Injecting Context for Subagents
+
+Edit `subagent_start.py` to inject context based on agent type:
+```python
+context_map = {
+    "security-code-reviewer": ".claude/rules/security-review.md",
+    "cross-layer-debugger": ".claude/rules/debugging.md",
+}
+```
+
+### Permission Request Modes
+
+The `permission_request.py` hook supports multiple modes:
+
+```bash
+# Standard mode - log requests, block dangerous patterns
+uv run .claude/hooks/permission_request.py --log
+
+# CI mode - auto-approve safe commands, deny unknown
+uv run .claude/hooks/permission_request.py --ci-mode --log
+
+# Strict mode - require approval for all write operations
+uv run .claude/hooks/permission_request.py --strict --log
+```
+
+**Dangerous patterns always blocked:**
+- Recursive deletion of system paths (`rm -rf /`, `rm -rf ~`)
+- Disk formatting commands (`mkfs`, `fdisk`, `dd of=/dev/`)
+- Fork bombs and system overload patterns
+- Curl/wget piped to bash/sh
+- Credential exfiltration patterns
+
+**CI-safe patterns (auto-approved in --ci-mode):**
+- Package management (`npm install`, `pip install`, `uv sync`)
+- Build/test commands (`npm run build`, `pytest`, `vitest`)
+- Git read operations (`git status`, `git log`, `git diff`)
+- File listing/reading (`ls`, `cat`, `grep`, `find`)
+
+**Strict mode requirements:**
+- All Write/Edit operations require approval
+- All rm/mv/cp commands require approval
+- Git write operations require approval
+- Network operations require approval
+
+---
+
+## Hook Input/Output Schemas
+
+Hooks receive JSON on stdin with event-specific data.
+
+### SessionStart
+```json
+{
+  "session_id": "...",
+  "source": "startup|resume|clear"
+}
+```
+
+### Stop
+```json
+{
+  "session_id": "...",
+  "stop_hook_active": true,
+  "transcript_path": "/path/to/transcript.jsonl"
+}
+```
+
+### PreCompact
+```json
+{
+  "session_id": "...",
+  "transcript_path": "/path/to/transcript.jsonl",
+  "trigger": "manual|auto",
+  "custom_instructions": "..."
+}
+```
+
+### PreToolUse
+```json
+{
+  "session_id": "...",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "npm test"
+  },
+  "tool_use_id": "toolu_abc123..."
+}
+```
+
+**Fields:**
+- `tool_use_id` — Unique identifier for this tool invocation (NEW in 2.0.43)
+
+### PostToolUse
+```json
+{
+  "session_id": "...",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "npm test"
+  },
+  "tool_output": "...",
+  "tool_use_id": "toolu_abc123..."
+}
+```
+
+**Fields:**
+- `tool_use_id` — Unique identifier for this tool invocation (NEW in 2.0.43)
+
+### SubagentStart (NEW in 2.0.43)
+```json
+{
+  "session_id": "...",
+  "agent_id": "subagent-abc123",
+  "agent_type": "security-code-reviewer",
+  "tool_use_id": "toolu_xyz789..."
+}
+```
+
+**Fields:**
+- `agent_id` — Unique identifier for the subagent instance
+- `agent_type` — Type/name of the subagent being invoked
+- `tool_use_id` — ID of the Task tool invocation that spawned this subagent
+
+**Output:** Can return `hookSpecificOutput.additionalContext` to inject context:
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SubagentStart",
+    "additionalContext": "# Security Review Rules\n..."
+  }
+}
+```
+
+### SubagentStop
+```json
+{
+  "session_id": "...",
+  "agent_id": "subagent-abc123",
+  "agent_transcript_path": "/path/to/agent/transcript.jsonl",
+  "stop_hook_active": true,
+  "transcript_path": "/path/to/transcript.jsonl"
+}
+```
+
+**Fields:**
+- `agent_id` — Unique identifier for the subagent (NEW in 2.0.42)
+- `agent_transcript_path` — Path to subagent's transcript file (NEW in 2.0.42)
+
+### PermissionRequest (NEW in 2.0.45)
+```json
+{
+  "session_id": "...",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "npm install"
+  },
+  "permission_type": "tool_execution"
+}
+```
+
+**Output:** Must return a decision:
+```json
+{
+  "decision": "approve|deny|ask",
+  "reason": "Optional explanation"
+}
+```
+
+**Decision values:**
+- `approve` — Automatically approve the permission request
+- `deny` — Automatically deny the permission request
+- `ask` — Fall back to asking the user (default behavior)
+
+### UserPromptSubmit
+```json
+{
+  "session_id": "...",
+  "prompt": "User's input text"
+}
+```
+
+### Notification
+```json
+{
+  "session_id": "...",
+  "notification_type": "...",
+  "message": "..."
+}
+```
+
+---
+
+## Hook Matchers
+
+Hooks support matchers to filter when they run:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run .claude/hooks/bash_safety.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Matcher patterns:**
+- Empty string `""` — Match all events
+- `"Bash"` — Match only Bash tool
+- `"Write|Edit"` — Match Write or Edit tools
+
+---
+
+## Testing Hooks
+
+Test harnesses are available in `project/tests/` (or `.claude/tests/` after `anvil init`):
+
+```bash
+# Run all hook tests
+./test-hooks.sh
+
+# Run all statusline tests
+./test-statusline.sh
+
+# Run specific hook tests
+./test-hooks.sh pre_tool_use
+```
+
+These harnesses use **heredocs** to define JSON fixtures, eliminating shell escaping issues entirely.
+
+See `project/tests/README.md` for full documentation on:
+- Writing custom tests
+- Assertion functions (`assert_contains`, `assert_exit_code`, etc.)
+- Test environment setup
+
+---
+
+## Version History
+
+| Version | Additions |
+|---------|-----------|
+| 2.0.45 | PermissionRequest hook |
+| 2.0.43 | SubagentStart hook, `tool_use_id` field, `skills` frontmatter |
+| 2.0.42 | `agent_id` and `agent_transcript_path` in SubagentStop |
+| 2.0.41 | Prompt-based stop hooks, custom timeouts |
+| 2.0.37 | Notification hook with matcher values |

package/project/hooks/notification.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "python-dotenv",
+# ]
+# ///
+
+import argparse
+import json
+import os
+import platform
+import sys
+import subprocess
+import random
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # dotenv is optional
+
+
+def is_apple_silicon():
+    """Check if running on Apple Silicon Mac."""
+    return platform.system() == "Darwin" and platform.machine() == "arm64"
+
+
+def get_my_codename() -> str:
+    """Get this agent's codename (A1, A2, etc.) from registry.
+
+    Reads agent ID from local anvil-state.json, then looks up
+    the codename from the global agent registry.
+
+    Returns:
+        Codename like "A1" or empty string if not found.
+    """
+    try:
+        state_file = Path(".claude/anvil-state.json")
+        if not state_file.exists():
+            return ""
+
+        state = json.loads(state_file.read_text())
+        agent_id = state.get("session", {}).get("agentId", "")
+        if not agent_id:
+            return ""
+
+        registry_file = Path.home() / ".anvil" / "agents.json"
+        if registry_file.exists():
+            registry = json.loads(registry_file.read_text())
+            agent = registry.get("agents", {}).get(agent_id, {})
+            return agent.get("codename") or ""
+    except Exception:
+        pass
+    return ""
+
+
+def get_tts_script_path():
+    """
+    Determine which TTS script to use.
+    Priority order: MLX Audio (Apple Silicon) > ElevenLabs > OpenAI > pyttsx3 > macOS say
+    
+    MLX Audio with Kokoro provides ~300ms latency, free, local TTS on Apple Silicon.
+    Falls back to API-based TTS or system TTS if unavailable.
+    """
+    script_dir = Path(__file__).parent
+    tts_dir = script_dir / "utils" / "tts"
+
+    # MLX Audio is the primary choice for Apple Silicon (free, fast, local)
+    if is_apple_silicon():
+        mlx_script = tts_dir / "mlx_audio_tts.py"
+        if mlx_script.exists():
+            return str(mlx_script)
+
+    # ElevenLabs if API key is set (highest quality but costs money)
+    if os.getenv('ELEVENLABS_API_KEY'):
+        elevenlabs_script = tts_dir / "elevenlabs_tts.py"
+        if elevenlabs_script.exists():
+            return str(elevenlabs_script)
+
+    # OpenAI TTS if API key is set
+    if os.getenv('OPENAI_API_KEY'):
+        openai_script = tts_dir / "openai_tts.py"
+        if openai_script.exists():
+            return str(openai_script)
+
+    # pyttsx3 as offline fallback
+    pyttsx3_script = tts_dir / "pyttsx3_tts.py"
+    if pyttsx3_script.exists():
+        return str(pyttsx3_script)
+
+    # Final fallback: return None and use macOS say command
+    return None
+
+
+def announce_notification():
+    """Announce that the agent needs user input."""
+    try:
+        # Get agent codename for identification (ANV-135)
+        codename = get_my_codename()
+        agent_prefix = f"Agent {codename[1:]}" if codename.startswith("A") else "Your agent"
+
+        # Get engineer name if available
+        engineer_name = os.getenv('ENGINEER_NAME', '').strip()
+
+        # Create notification message with 30% chance to include name
+        if engineer_name and random.random() < 0.3:
+            notification_message = f"{engineer_name}, {agent_prefix} needs your input"
+        else:
+            notification_message = f"{agent_prefix} needs your input"
+
+        tts_script = get_tts_script_path()
+        
+        if tts_script:
+            # Use the selected TTS script
+            subprocess.run([
+                "uv", "run", tts_script, notification_message
+            ],
+            capture_output=True,
+            timeout=10
+            )
+        else:
+            # Ultimate fallback: macOS say command (~10ms, robotic but reliable)
+            subprocess.run(['say', notification_message], capture_output=True, timeout=10)
+
+    except (subprocess.TimeoutExpired, subprocess.SubprocessError, FileNotFoundError):
+        # Fail silently if TTS encounters issues
+        pass
+    except Exception:
+        # Fail silently for any other errors
+        pass
+
+
+def main():
+    try:
+        # Parse command line arguments
+        parser = argparse.ArgumentParser()
+        parser.add_argument('--notify', action='store_true', help='Enable TTS notifications')
+        args = parser.parse_args()
+
+        # Read JSON input from stdin
+        input_data = json.loads(sys.stdin.read())
+
+        # Ensure log directory exists
+        import os
+        log_dir = os.path.join(os.getcwd(), 'logs')
+        os.makedirs(log_dir, exist_ok=True)
+        log_file = os.path.join(log_dir, 'notification.json')
+
+        # Read existing log data or initialize empty list
+        if os.path.exists(log_file):
+            with open(log_file, 'r') as f:
+                try:
+                    log_data = json.load(f)
+                except (json.JSONDecodeError, ValueError):
+                    log_data = []
+        else:
+            log_data = []
+
+        # Append new data
+        log_data.append(input_data)
+
+        # Write back to file with formatting
+        with open(log_file, 'w') as f:
+            json.dump(log_data, f, indent=2)
+
+        # Announce notification via TTS only if --notify flag is set
+        # Skip TTS for the generic "Claude is waiting for your input" message
+        if args.notify and input_data.get('message') != 'Claude is waiting for your input':
+            announce_notification()
+
+        sys.exit(0)
+
+    except json.JSONDecodeError:
+        # Handle JSON decode errors gracefully
+        sys.exit(0)
+    except Exception:
+        # Handle any other errors gracefully
+        sys.exit(0)
+
+if __name__ == '__main__':
+    main()