feat: add comprehensive hooks system with Claude Code integration and AI decision making

- Add 7 new Claude Code hook types for complete lifecycle integration
- Implement native system notifications with cross-platform support
- Add AI-powered hook decisions for security and automation
- Create comprehensive hook management CLI commands
- Add examples and documentation for all hook features
- Integrate with beeep library for system notifications
- Support configurable notifications with custom titles and icons
- Enable AI analysis of hook outputs for tool approval/blocking
- Add test commands for validating hook configurations

Author: themusicman

.workie.yaml

@@ -1,205 +1,7 @@
-# Workie Configuration File
-# =========================
-# This file defines how Workie manages your development worktrees.
-# Uncomment and customize the settings below for your project.
-
-# Core Configuration - Files to Copy to New Worktrees
-# ====================================================
-files_to_copy:
-  # Environment files (commonly needed in all worktrees)
-  - .env.example
-  # - .env.dev.example
-  # - .env.test.example
-  # - .env.local.example
-
-  # Configuration files
-  # - config/development.yaml
-  # - config/testing.yaml
-  # - config/staging.yaml
-  # - .editorconfig
-  # - .gitignore
-
-  # Documentation
-  # - README.md
-  # - docs/setup.md
-  # - docs/development.md
-  # - CONTRIBUTING.md
-
-  # Scripts and tools (use trailing slash for directories)
-  # - scripts/
-  # - tools/
-  # - bin/
-
-  # Language-specific files
-  # Node.js/JavaScript
-  # - package.json
-  # - package-lock.json
-  # - yarn.lock
-  # - .eslintrc.js
-  # - .prettierrc
-  # - tsconfig.json
-  # - jest.config.js
-
-  # Python
-  # - requirements.txt
-  # - requirements-dev.txt
-  # - pyproject.toml
-  # - setup.py
-  # - tox.ini
-  # - .flake8
-
-  # Go
-  # - go.mod
-  # - go.sum
-  # - Makefile
-
-  # Ruby
-  # - Gemfile
-  # - Gemfile.lock
-  # - .ruby-version
-
-  # Docker files
-  # - Dockerfile
-  # - Dockerfile.dev
-  # - docker-compose.yml
-  # - docker-compose.dev.yml
-  # - docker-compose.test.yml
-  # - .dockerignore
-
-  # CI/CD files
-  # - .github/
-  # - .gitlab-ci.yml
-  # - .travis.yml
-  # - circle.yml
-
-  # IDE/Editor settings (uncomment if your team uses these)
-  # - .vscode/
-  # - .idea/
-  # - .sublime-project
-
-# Hooks - Run custom commands at various stages
-# =============================================
-# Workie lifecycle hooks and Claude Code integration hooks
 hooks:
-  post_create:
-    - 'echo "🚀 Starting work session in $(basename $(pwd))"'
-    - 'echo "📁 Working directory: $(pwd)"'
-  pre_remove:
-    - 'echo "👋 Finishing work session"'
-    - 'git status --short'
-  # Claude Code hooks (https://docs.anthropic.com/en/docs/claude-code/hooks)
-  claude_pre_tool_use:          # Before Claude uses any tool (Bash, Edit, Read, etc.)
-    - 'echo "🔧 Claude Code is about to use a tool: $TOOL_NAME"'
-    - 'test "$TOOL_NAME" = "Write" && echo "⚠️  WARNING: Write operation detected" >&2 || true'
-    - 'echo "$TOOL_NAME" | grep -E "^(Write|Edit|Delete)" && echo "📝 File modification tool" || echo "✅ Read-only tool"'
-  claude_post_tool_use:         # After Claude successfully uses a tool
-    - 'echo "✅ Claude Code finished using tool: $TOOL_NAME"'
-  claude_user_prompt_submit:    # When user submits a prompt to Claude
-    - 'echo "💬 User submitted prompt"'
-  claude_stop:                  # When Claude finishes responding
-    - 'echo "🏁 Claude Code finished responding"'
-  # claude_notification:        # On Claude notifications (permissions, idle)
-  # claude_subagent_stop:       # When a subagent (Task tool) finishes
-  # claude_pre_compact:         # Before context compaction
+  claude_notification:
+    - 'echo "Notification hook executed: $MESSAGE"'
 
-  timeout_minutes: 2     # Timeout for all hooks (default: 5)
-  
-  # AI-powered decision making for Claude Code hooks
-  ai_decision:
-    enabled: true        # Enable AI to analyze hook outputs and make decisions
-    strict_mode: false   # If true, any hook failure results in automatic block
-
-# AI Configuration (Ollama-based Assistant)
-# =========================================
-# Configure AI features for intelligent code assistance
-ai:
-  enabled: true
-  model:
-    provider: "ollama"
-    name: "zephyr"
-    temperature: 0.7
-    max_tokens: 2048
-#   ollama:
-#     base_url: "http://localhost:11434"
-#     keep_alive: "5m"
-#   features:
-#     code_analysis: true
-#     code_generation: true
-#     commit_message_generation: true
-#     documentation_generation: true
-
-# Tips for Customizing Your Configuration:
-# ========================================
-# 1. Start simple - uncomment just the files you need most
-# 2. Use relative paths from your repository root
-# 3. For directories, include the trailing slash (/)
-# 4. Test your configuration with a temporary branch first
-# 5. Add comments to explain project-specific choices
-# 6. Consider different needs for different branch types
-# 7. Keep the file under version control so your team can share it
-
-# Common Patterns:
-# ===============
-# - Always copy environment examples and config files
-# - Include package manager files for dependency installation
-# - Copy scripts and tools that help with development
-# - Include documentation that developers need to reference
-# - Add IDE settings if your team standardizes on specific tools
-# - Be selective with CI/CD files to avoid conflicts
-
-# Troubleshooting:
-# ===============
-# - If a file doesn't exist, Workie will show a warning but continue
-# - Use 'workie --verbose' to see detailed copy operations
-# - Check file permissions if copies fail
-# - Use 'workie --list' to see all your worktrees
-# - Use 'workie finish <branch>' to clean up test worktrees
-
-# Issue Provider Configuration (Optional)
-# ======================================
-# Connect to GitHub, Jira, or Linear to work with issues
-
-# Default provider to use when no provider is specified in issue commands
-# default_provider: github
-
-providers:
-  github:
+  system_notifications:
     enabled: true
-    settings:
-      token_env: "WORKIE_GITHUB_TOKEN" # Environment variable containing GitHub personal access token
-      owner: "agoodway" # Repository owner/organization
-      repo: "workie" # Repository name
-    branch_prefix:
-      bug: "fix/"
-      feature: "feat/"
-      default: "issue/"
-#
-#   jira:
-#     enabled: false
-#     settings:
-#       base_url: "https://your-company.atlassian.net"
-#       email_env: "JIRA_EMAIL"      # Environment variable for Jira email
-#       api_token_env: "JIRA_TOKEN"  # Environment variable for Jira API token
-#       project: "PROJ"              # Default project key
-#     branch_prefix:
-#       bug: "bugfix/"
-#       story: "feature/"
-#       task: "task/"
-#       default: "jira/"
-#
-#   linear:
-#     enabled: false
-#     settings:
-#       api_key_env: "LINEAR_API_KEY"  # Environment variable for Linear API key
-#       team_id: "TEAM"                # Optional: filter by team
-#     branch_prefix:
-#       bug: "fix/"
-#       feature: "feat/"
-#       default: "linear/"
-
-# Issue Provider Usage:
-# ===================
-# - List issues: workie issues
-# - View issue: workie issues github:123
-# - Create worktree from issue: workie issues github:123 --create
-# - Filter issues: workie issues --assignee me --status open
+    title: "Workie Test"

README.md

@@ -503,6 +503,34 @@ hooks:
   claude_pre_compact:        # Before context compaction
 ```
 
+### System Notifications
+
+Workie can send system notifications when Claude Code events occur. This is particularly useful for the `claude_notification` hook to alert you when Claude needs your attention.
+
+```yaml
+hooks:
+  # Claude notification hooks
+  claude_notification:
+    - 'echo "Notification: $MESSAGE" >> ~/.workie/notifications.log'
+    - 'play-sound.sh'  # Your custom notification sound
+  
+  # Enable system notifications
+  system_notifications:
+    enabled: true
+    title: "Workie - Claude Code"  # Optional: custom title
+    icon: "assets/icon.png"         # Optional: custom icon path
+```
+
+When enabled, Workie will:
+1. Execute all configured `claude_notification` hooks
+2. Send a native system notification with the Claude message
+3. Support cross-platform notifications (macOS, Linux, Windows)
+
+The notification will appear as a system alert with:
+- **Title**: "Workie - Claude Code" (or your custom title)
+- **Message**: The actual notification from Claude (e.g., "Claude needs your permission to use Bash")
+- **Icon**: Platform default or your custom icon
+
 ### AI-Powered Tool Use Decisions 🤖
 
 Workie can use AI to analyze hook outputs and decide whether to approve or block tool usage:
@@ -654,6 +682,16 @@ To integrate Workie with Claude Code's native hook system, you need to modify yo
           }
         ]
       }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "workie hooks run claude_notification"
+          }
+        ]
+      }
     ]
   }
 }