claude-mpm 4.25.10__py3-none-any.whl → 5.1.8__py3-none-any.whl

claude_mpm/hooks/README.md

@@ -1,143 +0,0 @@
-# Claude Code Hooks System
-
-This directory contains the Claude Code hook integration for claude-mpm.
-
-## Overview
-
-The hook system allows claude-mpm to intercept and handle commands typed in Claude Code, particularly the `/mpm` commands.
-
-## Version Requirements
-
-**Claude Code 1.0.92 or higher is required for hook monitoring features.**
-
-Earlier versions of Claude Code do not support the matcher-based hook configuration format needed for real-time event monitoring. If you have an older version:
-- The dashboard and other features will still work
-- Real-time monitoring will not be available
-- You'll see a clear message about the version requirement
-- To enable monitoring, upgrade Claude Code to 1.0.92+
-
-**Claude Code 2.0.30 or higher is required for PreToolUse input modification.**
-
-This advanced feature allows hooks to modify tool inputs before execution, enabling:
-- Context injection into file operations
-- Security guards that validate and block dangerous operations
-- Parameter enhancement with default values
-- Logging and auditing of tool invocations
-
-See [PreToolUse Hook Documentation](../../docs/developer/pretool-use-hooks.md) for details.
-
-## Architecture (v4.1.8+)
-
-Claude MPM uses a **deployment-root hook architecture** where Claude Code directly calls a script within the claude-mpm installation. See [HOOK_ARCHITECTURE.md](../../docs/developer/HOOK_ARCHITECTURE.md) for details.
-
-## Structure
-
-```
-hooks/
-├── claude_hooks/                      # Claude Code hook implementation
-│   ├── hook_handler.py               # Main Python handler that processes events
-│   ├── installer.py                  # Hook installation and configuration
-│   ├── event_handlers.py             # Event processing logic
-│   ├── memory_integration.py         # Memory system integration
-│   ├── response_tracking.py          # Response tracking
-│   └── services/                     # Service modules
-│       ├── connection_manager.py     # SocketIO/HTTP connections
-│       ├── state_manager.py          # State and delegation tracking
-│       └── subagent_processor.py     # Subagent response processing
-├── templates/                         # Hook script templates
-│   ├── pre_tool_use_template.py      # Comprehensive PreToolUse template
-│   ├── pre_tool_use_simple.py        # Simple PreToolUse template
-│   └── README.md                     # Template documentation
-└── scripts/
-    └── claude-hook-handler.sh        # Deployment-root hook script (called by Claude Code)
-```
-
-## Claude Code Hooks
-
-The Claude Code hooks are the primary integration point between claude-mpm and Claude Code. They allow:
-
-- Intercepting `/mpm` commands before they reach the LLM
-- Providing custom responses and actions
-- Blocking LLM processing when appropriate
-
-### Installation
-
-To install the Claude Code hooks:
-
-```bash
-# Using the configure command (recommended)
-claude-mpm configure --install-hooks
-
-# Or check your version compatibility first
-claude-mpm configure --verify-hooks
-```
-
-This will:
-1. Check your Claude Code version for compatibility
-2. If compatible (1.0.92+), create/update `~/.claude/settings.json` with hook configuration
-3. Install the smart hook script that dynamically finds claude-mpm
-4. Copy any custom commands to `~/.claude/commands/`
-
-If your Claude Code version is older than 1.0.92:
-- You'll see a message explaining the version requirement
-- Hooks will not be installed to prevent configuration errors
-- The system will continue to work without real-time monitoring
-
-### How It Works
-
-1. When you type in Claude Code, it triggers hook events
-2. Claude Code calls `hook_wrapper.sh` (the path in `~/.claude/settings.json`)
-3. The wrapper script:
-   - Detects if it's running from a local dev environment, npm, or PyPI installation
-   - Activates the appropriate Python environment
-   - Runs `hook_handler.py` with the event data
-4. The handler processes various event types:
-   - **UserPromptSubmit**: Checks if the prompt starts with `/mpm` and handles commands
-   - **PreToolUse**: Logs tool usage before execution
-   - **PostToolUse**: Logs tool results after execution
-   - **Stop**: Logs when a session or task stops
-   - **SubagentStop**: Logs when a subagent completes with agent type and ID
-5. For `/mpm` commands, it returns exit code 2 to block LLM processing
-6. All events are logged to project-specific log files in `.claude-mpm/logs/`
-
-### Available Commands
-
-- `/mpm` - Show help and available commands
-- `/mpm status` - Show claude-mpm status and environment
-- `/mpm help` - Show detailed help
-
-### Debugging
-
-To enable debug logging for hooks:
-
-```bash
-export CLAUDE_MPM_LOG_LEVEL=DEBUG
-```
-
-Then run Claude Code from that terminal. Hook events will be logged to `~/.claude-mpm/logs/`.
-
-## Legacy Hook System (Removed)
-
-The `builtin/` directory that contained the old internal hook system has been removed. All hook functionality is now handled through the Claude Code hooks system.
-
-## Development
-
-To add new `/mpm` commands:
-
-1. Edit `hook_handler.py` to handle the new command
-2. Update the help text in the `handle_mpm_help()` function
-3. Test by running Claude Code with the new command
-
-## Exit Codes
-
-The hook system uses specific exit codes:
-
-- `0` - Success, continue normal processing
-- `2` - Block LLM processing (command was handled)
-- Other - Error occurred
-
-## Environment Variables
-
-- `CLAUDE_MPM_LOG_LEVEL` - Set to DEBUG for detailed logging
-- `HOOK_EVENT_TYPE` - Set by Claude Code (UserPromptSubmit, PreToolUse, PostToolUse)
-- `HOOK_DATA` - JSON data from Claude Code with event details

claude_mpm/hooks/templates/README.md

@@ -1,180 +0,0 @@
-# Claude MPM Hook Templates
-
-This directory contains ready-to-use hook templates for extending Claude Code functionality.
-
-## Available Templates
-
-### PreToolUse Hooks (Claude Code v2.0.30+)
-
-#### `pre_tool_use_template.py`
-
-Comprehensive template with multiple example implementations:
-
-- **ContextInjectionHook**: Auto-inject project context into file operations
-- **SecurityGuardHook**: Block operations on sensitive files
-- **LoggingHook**: Log all tool invocations for debugging
-- **ParameterEnhancementHook**: Add default parameters to tool calls
-
-**Usage:**
-```bash
-# Copy and customize
-cp pre_tool_use_template.py ~/.claude-mpm/hooks/my_hook.py
-chmod +x ~/.claude-mpm/hooks/my_hook.py
-
-# Edit to uncomment the implementation you want
-nano ~/.claude-mpm/hooks/my_hook.py
-```
-
-#### `pre_tool_use_simple.py`
-
-Minimal example for quick customization:
-
-- Shows basic hook structure
-- Includes simple parameter enhancement example
-- Includes security guard example
-- Easy to understand and modify
-
-**Usage:**
-```bash
-# Copy for quick start
-cp pre_tool_use_simple.py ~/.claude-mpm/hooks/my_hook.py
-chmod +x ~/.claude-mpm/hooks/my_hook.py
-```
-
-## Configuration
-
-Add hooks to `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/my_hook.py",
-            "modifyInput": true
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Requirements
-
-- Claude Code v2.0.30+ for PreToolUse input modification
-- Python 3.7+
-- claude-mpm installed and configured
-
-## Version Check
-
-Check if your Claude Code version supports input modification:
-
-```bash
-claude --version
-```
-
-Or programmatically:
-
-```python
-from claude_mpm.hooks.claude_hooks.installer import HookInstaller
-
-installer = HookInstaller()
-if installer.supports_pretool_modify():
-    print("✓ PreToolUse input modification supported")
-else:
-    print(f"✗ Requires Claude Code 2.0.30+ (current: {installer.get_claude_version()})")
-```
-
-## Documentation
-
-See [PreToolUse Hook Documentation](../../../docs/developer/pretool-use-hooks.md) for:
-- Detailed usage guide
-- Best practices
-- Testing strategies
-- Troubleshooting
-- Advanced examples
-
-## Quick Examples
-
-### Add Line Numbers to Grep
-
-```python
-#!/usr/bin/env python3
-import json
-import sys
-
-event = json.loads(sys.stdin.read())
-if event.get("tool_name") == "Grep":
-    modified = event["tool_input"].copy()
-    modified["-n"] = True
-    print(json.dumps({"action": "continue", "tool_input": modified}))
-else:
-    print(json.dumps({"action": "continue"}))
-```
-
-### Block Sensitive Files
-
-```python
-#!/usr/bin/env python3
-import json
-import sys
-
-event = json.loads(sys.stdin.read())
-tool_name = event.get("tool_name", "")
-if tool_name in ["Write", "Edit", "Read"]:
-    file_path = event["tool_input"].get("file_path", "")
-    if ".env" in file_path:
-        print(json.dumps({"action": "block", "message": "Access to .env blocked"}))
-        sys.exit(0)
-
-print(json.dumps({"action": "continue"}))
-```
-
-### Add Default Timeout to Bash
-
-```python
-#!/usr/bin/env python3
-import json
-import sys
-
-event = json.loads(sys.stdin.read())
-if event.get("tool_name") == "Bash":
-    modified = event["tool_input"].copy()
-    if "timeout" not in modified:
-        modified["timeout"] = 30000  # 30 seconds
-        print(json.dumps({"action": "continue", "tool_input": modified}))
-        sys.exit(0)
-
-print(json.dumps({"action": "continue"}))
-```
-
-## Testing Your Hook
-
-Test manually with sample input:
-
-```bash
-echo '{
-  "hook_event_name": "PreToolUse",
-  "tool_name": "Grep",
-  "tool_input": {"pattern": "test"},
-  "session_id": "test123",
-  "cwd": "/tmp"
-}' | python3 your_hook.py
-```
-
-Enable debug mode:
-```bash
-export CLAUDE_MPM_HOOK_DEBUG=true
-```
-
-## Support
-
-For issues or questions:
-- See [Documentation](../../../docs/developer/pretool-use-hooks.md)
-- Check [GitHub Issues](https://github.com/yourusername/claude-mpm/issues)
-- Review [Examples](./pre_tool_use_template.py)

claude_mpm/hooks/templates/settings.json.example

@@ -1,147 +0,0 @@
-{
-  "// NOTE": "This is an example configuration for Claude Code PreToolUse hooks",
-  "// FILE": "Copy relevant sections to ~/.claude/settings.json",
-  "// VERSION": "Requires Claude Code 2.0.30+ for input modification",
-
-  "hooks": {
-    "// PreToolUse with input modification (v2.0.30+)": {
-      "description": "Hooks that can modify tool inputs before execution",
-      "examples": [
-        "Context injection: Add project context to file operations",
-        "Security guards: Block operations on sensitive files",
-        "Parameter enhancement: Add default parameters",
-        "Logging: Track all tool invocations"
-      ]
-    },
-
-    "PreToolUse": [
-      {
-        "// Matcher": "Use '*' for all tools or specify tool name",
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "// IMPORTANT": "Replace YOUR_USERNAME with your actual username",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/my_hook.py",
-            "// modifyInput": "Set to true to enable input modification (v2.0.30+)",
-            "modifyInput": true
-          }
-        ]
-      }
-    ],
-
-    "// Tool-specific examples": {
-      "description": "Target specific tools instead of all tools"
-    },
-
-    "// Example: Security guard for Edit operations": [
-      {
-        "matcher": "Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/edit-guard.py",
-            "modifyInput": true
-          }
-        ]
-      }
-    ],
-
-    "// Example: Add timeout to all Bash commands": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/bash-timeout.py",
-            "modifyInput": true
-          }
-        ]
-      }
-    ],
-
-    "// Example: Log all Grep operations": [
-      {
-        "matcher": "Grep",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/grep-logger.py",
-            "modifyInput": true
-          }
-        ]
-      }
-    ],
-
-    "// Example: Multiple hooks in sequence": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/logger.py",
-            "modifyInput": true,
-            "// note": "First hook: Log the operation"
-          },
-          {
-            "type": "command",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/guard.py",
-            "modifyInput": true,
-            "// note": "Second hook: Validate and potentially block"
-          },
-          {
-            "type": "command",
-            "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/enhancer.py",
-            "modifyInput": true,
-            "// note": "Third hook: Add default parameters"
-          }
-        ]
-      }
-    ],
-
-    "// Legacy hooks (v1.0.92+) still work": {
-      "UserPromptSubmit": [
-        {
-          "hooks": [
-            {
-              "type": "command",
-              "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/claude-hook-handler.sh"
-            }
-          ]
-        }
-      ],
-      "PostToolUse": [
-        {
-          "matcher": "*",
-          "hooks": [
-            {
-              "type": "command",
-              "command": "/Users/YOUR_USERNAME/.claude-mpm/hooks/claude-hook-handler.sh"
-            }
-          ]
-        }
-      ]
-    }
-  },
-
-  "// Quick Setup Instructions": {
-    "1": "Copy a template from src/claude_mpm/hooks/templates/",
-    "2": "Make it executable: chmod +x ~/.claude-mpm/hooks/my_hook.py",
-    "3": "Copy the relevant configuration section above to ~/.claude/settings.json",
-    "4": "Replace YOUR_USERNAME with your actual username",
-    "5": "Test: echo '{...}' | python3 ~/.claude-mpm/hooks/my_hook.py"
-  },
-
-  "// Documentation": {
-    "Quick Start": "docs/user/pretool-use-quick-start.md",
-    "Developer Guide": "docs/developer/pretool-use-hooks.md",
-    "Templates": "src/claude_mpm/hooks/templates/",
-    "Examples": "src/claude_mpm/hooks/templates/pre_tool_use_template.py"
-  },
-
-  "// Version Requirements": {
-    "Hooks": "Claude Code 1.0.92+",
-    "Input Modification": "Claude Code 2.0.30+",
-    "Check Version": "claude --version"
-  }
-}