claude-mpm 3.3.0__py3-none-any.whl → 3.4.0__py3-none-any.whl

claude_mpm/hooks/README.md

@@ -1,97 +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.
-
-## Structure
-
-```
-hooks/
-├── claude_hooks/              # Claude Code hook implementation
-│   ├── hook_handler.py       # Main Python handler that processes events
-│   └── hook_wrapper.sh       # Shell wrapper script (this is what gets installed in ~/.claude/settings.json)
-└── builtin/                  # Legacy internal hooks (deprecated)
-```
-
-## 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
-python scripts/install_hooks.py
-```
-
-This will:
-1. Create/update `~/.claude/settings.json` with hook configuration
-2. Point to the `hook_wrapper.sh` script
-3. Copy any custom commands to `~/.claude/commands/`
-
-### 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 (Deprecated)
-
-The `builtin/` directory contains the old internal hook system that was designed for JSON-RPC based hooks. This system is deprecated and will be removed in a future version. All hook functionality is now handled through the Claude Code hooks.
-
-## 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/orchestration/SUBPROCESS_DESIGN.md

@@ -1,66 +0,0 @@
-# Subprocess Orchestration Design
-
-## Problem
-Claude's `--print` mode times out when generating code or using tools, making subprocess orchestration in non-interactive mode impractical.
-
-## Findings
-
-### Interactive Mode (Working)
-- Claude uses built-in Task tool
-- Creates real subprocesses with ~11.4k tokens each
-- Runs in parallel with independent timing
-- Each subprocess gets framework context
-
-### Non-Interactive Mode Issues
-- `claude --print` works for simple queries (e.g., "What is 2+2?" in ~4s)
-- Times out for any code generation or complex tasks
-- Debug shows Claude is working but tool usage adds overhead
-- Requires `--dangerously-skip-permissions` flag to run
-
-## Alternative Approaches
-
-### 1. Use Claude's Conversation API
-Instead of `--print`, use conversation management:
-```bash
-# Start conversation
-claude --model opus -c "conversation_id" < prompt.txt
-
-# Continue conversation
-claude --continue conversation_id < next_prompt.txt
-```
-
-### 2. Use Interactive Mode with Expect
-Use expect/pexpect to control interactive Claude sessions programmatically.
-
-### 3. Mock Subprocess Mode
-For testing/development:
-- Detect delegations in PM response
-- Show subprocess-like output
-- But don't actually create subprocesses
-
-### 4. Direct API Integration
-Skip CLI entirely and use Claude's API directly (if available).
-
-## Implementation Status
-
-### Completed
-1. ✅ SubprocessOrchestrator class with full functionality
-2. ✅ Delegation detection for multiple formats
-3. ✅ Parallel subprocess execution framework
-4. ✅ Agent-specific prompt generation
-5. ✅ CLI integration via `--subprocess` flag
-6. ✅ Fixed command flags for permissions
-
-### Current Status
-- Implementation is complete but blocked by Claude CLI limitations
-- Use interactive mode for real subprocess orchestration
-- Keep implementation for future when Claude print mode improves
-
-## Delegation Detection Patterns
-
-The PM uses these formats:
-- `**Engineer Agent**: Create a function...`
-- `**QA**: Write tests for...`
-- `I'll delegate this to the Engineer agent...`
-
-We can parse these and show subprocess-style output even without real subprocesses.

claude_mpm/schemas/README_SECURITY.md

@@ -1,92 +0,0 @@
-# Agent Schema Security Guide
-
-## Critical Security Notice
-
-**This schema is a SECURITY BOUNDARY.** Any changes to agent_schema.json must be carefully reviewed for security implications.
-
-## Security Controls in agent_schema.json
-
-### 1. Field Validation
-- **agent_id**: Pattern `^[a-z][a-z0-9_]*$` prevents path traversal and command injection
-- **version fields**: Semantic versioning pattern prevents version injection
-- **enums**: All enums are allowlists preventing arbitrary values
-
-### 2. Size Limits
-- **instructions**: 8000 char max prevents memory exhaustion
-- **name**: 50 char max prevents UI breaking
-- **description**: 200 char max prevents storage abuse
-- **tags**: max 10 items prevents array bombing
-
-### 3. Resource Limits by Tier
-```
-intensive:    memory: 4096-8192MB, cpu: 60-100%, timeout: 600-3600s
-standard:     memory: 2048-4096MB, cpu: 30-60%,  timeout: 300-1200s  
-lightweight:  memory: 512-2048MB,  cpu: 10-30%,  timeout: 30-600s
-```
-
-### 4. Tool Security Matrix
-
-| Tool Combination | Risk Level | Security Impact |
-|-----------------|------------|-----------------|
-| Bash + Write | CRITICAL | Arbitrary code execution |
-| docker + kubectl | HIGH | Container escape potential |
-| aws + gcloud + azure | HIGH | Multi-cloud attack surface |
-| WebFetch + Write | MEDIUM | Data exfiltration risk |
-| Read + network_access | MEDIUM | Information disclosure |
-
-### 5. Required Security Reviews
-
-Any PR modifying agent_schema.json MUST include:
-1. Security impact assessment
-2. Validation that no new fields bypass security controls
-3. Test cases for new validation rules
-4. Update to this security guide if needed
-
-### 6. Security Checklist for Schema Changes
-
-- [ ] No new fields allow arbitrary string input without validation
-- [ ] All new arrays have maxItems limits
-- [ ] All new strings have maxLength limits
-- [ ] New enum values are reviewed for security impact
-- [ ] Resource limits maintain tier boundaries
-- [ ] No new fields can bypass additionalProperties: false
-- [ ] Pattern validations prevent injection attacks
-- [ ] Default values follow principle of least privilege
-
-## Common Security Mistakes to Avoid
-
-1. **Never** add fields that accept arbitrary file paths without validation
-2. **Never** increase resource limits without security review
-3. **Never** add tools that bypass the enum list
-4. **Never** remove pattern validation from ID fields
-5. **Never** set additionalProperties to true
-6. **Always** default network_access to false
-7. **Always** validate new tool combinations for security impact
-
-## Security Testing
-
-Run these tests after any schema change:
-```bash
-# Validate schema structure
-python scripts/validate_agent_schema.py
-
-# Test security boundaries
-python tests/test_agent_security_boundaries.py
-
-# Check for injection vulnerabilities
-python tests/test_agent_validation_security.py
-```
-
-## Incident Response
-
-If a security vulnerability is found in the schema:
-1. Immediately add validation in agent_validator.py as a hotfix
-2. Update schema to prevent the vulnerability
-3. Audit all existing agents for exploitation
-4. Document the vulnerability and fix in security log
-
-## Security Contacts
-
-- Security reviews: security-team@company.com
-- Vulnerability reports: security@company.com
-- Emergency response: security-oncall@company.com

claude_mpm/schemas/agent_schema.json

@@ -1,395 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.2.0",
-  "title": "Claude MPM Agent Schema",
-  "description": "Schema definition for Claude MPM agent templates. This schema enforces the structure and validation rules for all agent configurations in the Claude MPM system.",
-  "type": "object",
-  "required": [
-    "schema_version",
-    "agent_id",
-    "agent_version",
-    "agent_type",
-    "metadata",
-    "capabilities",
-    "instructions"
-  ],
-  "properties": {
-    "schema_version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Schema version for the agent template format. This ensures compatibility between the agent template and the schema validator. Must be updated when breaking changes are made to the schema.",
-      "examples": ["1.0.0", "1.2.0"]
-    },
-    "agent_id": {
-      "type": "string",
-      "pattern": "^[a-z][a-z0-9_]*$",
-      "description": "Unique agent identifier used for agent discovery and loading. This ID must be unique across all agents in the system and follows snake_case naming convention.",
-      "examples": ["research_agent", "engineer_agent", "qa_agent", "security_agent"]
-    },
-    "agent_version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Semantic version of the agent template itself (not the schema). Increment major for breaking changes, minor for new features, patch for bug fixes.",
-      "examples": ["1.0.0", "2.1.3"]
-    },
-    "agent_type": {
-      "type": "string",
-      "description": "Type of agent that determines its primary function and default capabilities. This categorization helps in agent discovery and capability matching.",
-      "enum": [
-        "base",
-        "engineer",
-        "qa",
-        "documentation",
-        "research",
-        "security",
-        "ops",
-        "data_engineer",
-        "version_control"
-      ]
-    },
-    "metadata": {
-      "type": "object",
-      "required": [
-        "name",
-        "description",
-        "tags"
-      ],
-      "properties": {
-        "name": {
-          "type": "string",
-          "minLength": 3,
-          "maxLength": 50,
-          "description": "Human-readable agent name displayed in UI and logs. Should be concise but descriptive."
-        },
-        "description": {
-          "type": "string",
-          "minLength": 10,
-          "maxLength": 200,
-          "description": "Brief description of agent purpose and capabilities. Used in agent selection and documentation."
-        },
-        "category": {
-          "type": "string",
-          "enum": ["engineering", "research", "quality", "operations", "specialized"],
-          "description": "Agent category for organization"
-        },
-        "tags": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "pattern": "^[a-z][a-z0-9-]*$"
-          },
-          "minItems": 1,
-          "maxItems": 10,
-          "uniqueItems": true,
-          "description": "Tags for agent discovery and categorization. Used by the agent registry for searching and filtering."
-        },
-        "author": {
-          "type": "string",
-          "description": "Agent template author"
-        },
-        "created_at": {
-          "type": "string",
-          "format": "date-time",
-          "description": "Creation timestamp"
-        },
-        "updated_at": {
-          "type": "string",
-          "format": "date-time",
-          "description": "Last update timestamp"
-        }
-      }
-    },
-    "capabilities": {
-      "type": "object",
-      "required": [
-        "model",
-        "tools",
-        "resource_tier"
-      ],
-      "properties": {
-        "model": {
-          "type": "string",
-          "enum": [
-            "claude-3-haiku-20240307",
-            "claude-3-5-haiku-20241022",
-            "claude-3-sonnet-20240229",
-            "claude-3-5-sonnet-20241022",
-            "claude-3-5-sonnet-20240620",
-            "claude-sonnet-4-20250514",
-            "claude-4-sonnet-20250514",
-            "claude-3-opus-20240229",
-            "claude-opus-4-20250514",
-            "claude-4-opus-20250514"
-          ],
-          "description": "Claude model to use for this agent. Choose based on task complexity and performance requirements."
-        },
-        "tools": {
-          "type": "array",
-          "items": {
-            "type": "string",
-            "enum": [
-              "Read",
-              "Write",
-              "Edit",
-              "MultiEdit",
-              "Grep",
-              "Glob",
-              "LS",
-              "Bash",
-              "WebSearch",
-              "WebFetch",
-              "NotebookRead",
-              "NotebookEdit",
-              "TodoWrite",
-              "ExitPlanMode",
-              "git",
-              "docker",
-              "kubectl",
-              "terraform",
-              "aws",
-              "gcloud",
-              "azure"
-            ]
-          },
-          "uniqueItems": true,
-          "description": "Available tools for the agent. Tools determine what operations the agent can perform."
-        },
-        "resource_tier": {
-          "type": "string",
-          "enum": [
-            "basic",
-            "standard",
-            "intensive",
-            "lightweight"
-          ],
-          "description": "Resource allocation tier that determines memory, CPU, and timeout limits. See definitions section for specific limits."
-        },
-        "max_tokens": {
-          "type": "integer",
-          "minimum": 1000,
-          "maximum": 200000,
-          "default": 8192,
-          "description": "Maximum tokens for response generation. Higher values allow longer responses but increase cost and latency."
-        },
-        "temperature": {
-          "type": "number",
-          "minimum": 0,
-          "maximum": 1,
-          "default": 0.7,
-          "description": "Model temperature setting controlling response randomness. Lower values for consistency, higher for creativity."
-        },
-        "timeout": {
-          "type": "integer",
-          "minimum": 30,
-          "maximum": 3600,
-          "default": 300,
-          "description": "Operation timeout in seconds. Should align with resource_tier settings."
-        },
-        "memory_limit": {
-          "type": "integer",
-          "minimum": 512,
-          "maximum": 8192,
-          "description": "Memory limit in MB (for resource tier)"
-        },
-        "cpu_limit": {
-          "type": "integer",
-          "minimum": 10,
-          "maximum": 100,
-          "description": "CPU limit percentage (for resource tier)"
-        },
-        "network_access": {
-          "type": "boolean",
-          "default": false,
-          "description": "Whether agent needs network access"
-        },
-        "file_access": {
-          "type": "object",
-          "properties": {
-            "read_paths": {
-              "type": "array",
-              "items": {"type": "string"},
-              "description": "Allowed read paths"
-            },
-            "write_paths": {
-              "type": "array",
-              "items": {"type": "string"},
-              "description": "Allowed write paths"
-            }
-          }
-        },
-        "allowed_tools": {
-          "type": "array",
-          "items": {"type": "string"},
-          "description": "Glob patterns for allowed file paths. Restricts which files the agent can access (e.g., 'tests/**' for test files only)."
-        },
-        "disallowed_tools": {
-          "type": "array",
-          "items": {"type": "string"},
-          "description": "Tool names to explicitly disallow, overriding the tools array. Use for security restrictions (e.g., 'Bash' to prevent shell access)."
-        }
-      }
-    },
-    "instructions": {
-      "type": "string",
-      "minLength": 100,
-      "maxLength": 8000,
-      "description": "Agent system instructions that define behavior, approach, and constraints. This becomes the agent's system prompt."
-    },
-    "knowledge": {
-      "type": "object",
-      "description": "Agent-specific knowledge and context",
-      "properties": {
-        "domain_expertise": {
-          "type": "array",
-          "items": {"type": "string"},
-          "description": "Areas of expertise"
-        },
-        "best_practices": {
-          "type": "array",
-          "items": {"type": "string"},
-          "description": "Best practices the agent follows"
-        },
-        "constraints": {
-          "type": "array",
-          "items": {"type": "string"},
-          "description": "Operating constraints"
-        },
-        "examples": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "scenario": {"type": "string"},
-              "approach": {"type": "string"}
-            }
-          },
-          "description": "Example scenarios and approaches"
-        }
-      }
-    },
-    "interactions": {
-      "type": "object",
-      "description": "Agent interaction patterns",
-      "properties": {
-        "input_format": {
-          "type": "object",
-          "properties": {
-            "required_fields": {
-              "type": "array",
-              "items": {"type": "string"}
-            },
-            "optional_fields": {
-              "type": "array",
-              "items": {"type": "string"}
-            }
-          }
-        },
-        "output_format": {
-          "type": "object",
-          "properties": {
-            "structure": {
-              "type": "string",
-              "enum": ["markdown", "json", "structured", "free-form"]
-            },
-            "includes": {
-              "type": "array",
-              "items": {"type": "string"}
-            }
-          }
-        },
-        "handoff_agents": {
-          "type": "array",
-          "items": {"type": "string"},
-          "description": "Agents this agent can hand off to"
-        },
-        "triggers": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "condition": {"type": "string"},
-              "action": {"type": "string"}
-            }
-          },
-          "description": "Conditions that trigger specific actions"
-        }
-      }
-    },
-    "testing": {
-      "type": "object",
-      "description": "Testing configuration for the agent",
-      "properties": {
-        "test_cases": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "required": ["input", "expected_behavior"],
-            "properties": {
-              "name": {"type": "string"},
-              "input": {"type": "string"},
-              "expected_behavior": {"type": "string"},
-              "validation_criteria": {
-                "type": "array",
-                "items": {"type": "string"}
-              }
-            }
-          }
-        },
-        "performance_benchmarks": {
-          "type": "object",
-          "properties": {
-            "response_time": {"type": "integer"},
-            "token_usage": {"type": "integer"},
-            "success_rate": {"type": "number"}
-          }
-        }
-      }
-    },
-    "hooks": {
-      "type": "object",
-      "description": "Hook configurations for extensibility",
-      "properties": {
-        "pre_execution": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "name": {"type": "string"},
-              "enabled": {"type": "boolean"}
-            }
-          }
-        },
-        "post_execution": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "name": {"type": "string"},
-              "enabled": {"type": "boolean"}
-            }
-          }
-        }
-      }
-    }
-  },
-  "additionalProperties": false,
-  "definitions": {
-    "resource_tier_limits": {
-      "intensive": {
-        "memory_limit": {"min": 4096, "max": 8192},
-        "cpu_limit": {"min": 60, "max": 100},
-        "timeout": {"min": 600, "max": 3600}
-      },
-      "standard": {
-        "memory_limit": {"min": 2048, "max": 4096},
-        "cpu_limit": {"min": 30, "max": 60},
-        "timeout": {"min": 300, "max": 1200}
-      },
-      "lightweight": {
-        "memory_limit": {"min": 512, "max": 2048},
-        "cpu_limit": {"min": 10, "max": 30},
-        "timeout": {"min": 30, "max": 600}
-      }
-    }
-  }
-}