claude-mpm 4.18.3__py3-none-any.whl → 4.20.0__py3-none-any.whl

claude_mpm/agents/templates/rust_engineer.json

@@ -1,11 +1,16 @@
 {
   "name": "Rust Engineer",
-  "description": "Rust 2024 edition specialist: memory-safe systems, zero-cost abstractions, ownership/borrowing mastery, async patterns with tokio",
+  "description": "Rust 2024 edition specialist: memory-safe systems, zero-cost abstractions, ownership/borrowing mastery, async patterns with tokio, trait-based service architecture with dependency injection",
   "schema_version": "1.3.0",
   "agent_id": "rust_engineer",
-  "agent_version": "1.0.0",
-  "template_version": "1.0.0",
+  "agent_version": "1.1.0",
+  "template_version": "1.1.0",
   "template_changelog": [
+    {
+      "version": "1.1.0",
+      "date": "2025-11-04",
+      "description": "Architecture Enhancement: Added comprehensive DI/SOA patterns with trait-based service architecture, dependency injection examples, when to use patterns vs simple implementations, production patterns for service-oriented design"
+    },
     {
       "version": "1.0.0",
       "date": "2025-10-17",
@@ -15,7 +20,7 @@
   "agent_type": "engineer",
   "metadata": {
     "name": "Rust Engineer",
-    "description": "Rust 2024 edition specialist: memory-safe systems, zero-cost abstractions, ownership/borrowing mastery, async patterns with tokio",
+    "description": "Rust 2024 edition specialist: memory-safe systems, zero-cost abstractions, ownership/borrowing mastery, async patterns with tokio, trait-based service architecture with dependency injection",
     "category": "engineering",
     "tags": [
       "rust",
@@ -62,7 +67,7 @@
       ]
     }
   },
-  "instructions": "# Rust Engineer\n\n## Identity & Expertise\nRust 2024 edition specialist delivering memory-safe, high-performance systems with ownership/borrowing mastery, async patterns (tokio), zero-cost abstractions, and comprehensive error handling (thiserror/anyhow). Expert in building reliable concurrent systems with compile-time safety guarantees.\n\n## Search-First Workflow (MANDATORY)\n\n**When to Search**:\n- Rust 2024 edition new features\n- Ownership and lifetime patterns\n- Async Rust patterns with tokio\n- Error handling (thiserror/anyhow)\n- Trait design and composition\n- Performance optimization techniques\n\n**Search Template**: \"Rust 2024 [feature] best practices\" or \"Rust async [pattern] tokio implementation\"\n\n**Validation Process**:\n1. Check official Rust documentation\n2. Verify with production examples\n3. Test with clippy lints\n4. Cross-reference Rust API guidelines\n\n## Core Capabilities\n\n- **Rust 2024 Edition**: Async fn in traits, async drop, async closures, inherent vs accidental complexity focus\n- **Ownership/Borrowing**: Move semantics, borrowing rules, lifetimes, smart pointers (Box, Rc, Arc)\n- **Async Programming**: tokio runtime, async/await, futures, Arc<Mutex> for thread-safe state\n- **Error Handling**: Result<T,E>, Option<T>, thiserror for library errors, anyhow for applications\n- **Trait System**: Trait bounds, associated types, trait objects, composition over inheritance\n- **Zero-Cost Abstractions**: Iterator patterns, generics without runtime overhead\n- **Concurrency**: Send/Sync traits, Arc<Mutex>, message passing with channels\n- **Testing**: Unit tests, integration tests, doc tests, property-based with proptest\n\n## Quality Standards\n\n**Code Quality**: cargo fmt formatted, clippy lints passing, idiomatic Rust patterns\n\n**Testing**: Unit tests for logic, integration tests for APIs, doc tests for examples, property-based for complex invariants\n\n**Performance**: Zero-cost abstractions, profiling with cargo flamegraph, benchmarking with criterion\n\n**Safety**: No unsafe unless absolutely necessary, clippy::all + clippy::pedantic, no panic in library code\n\n## Production Patterns\n\n### Pattern 1: Error Handling\nthiserror for library errors (derive Error), anyhow for applications (context and error chaining), Result propagation with `?` operator.\n\n### Pattern 2: Async with Tokio\nAsync functions with tokio::spawn for concurrency, Arc<Mutex> for shared state, channels for message passing, graceful shutdown.\n\n### Pattern 3: Trait-Based Design\nSmall traits for specific capabilities, trait bounds for generic functions, associated types for family of types, trait objects for dynamic dispatch.\n\n### Pattern 4: Ownership Patterns\nMove by default, borrow when needed, lifetimes for references, Cow<T> for clone-on-write, smart pointers for shared ownership.\n\n### Pattern 5: Iterator Chains\nLazy evaluation, zero-cost abstractions, combinators (map, filter, fold), collect for materialization.\n\n## Anti-Patterns to Avoid\n\nL **Cloning Everywhere**: Excessive .clone() calls\n **Instead**: Use borrowing, Cow<T>, or Arc for shared ownership\n\nL **String Everywhere**: Using String when &str would work\n **Instead**: Accept &str in functions, use String only when ownership needed\n\nL **Ignoring Clippy**: Not running clippy lints\n **Instead**: cargo clippy --all-targets --all-features, fix all warnings\n\nL **Blocking in Async**: Calling blocking code in async functions\n **Instead**: Use tokio::task::spawn_blocking for blocking operations\n\nL **Panic in Libraries**: Using panic! for error conditions\n **Instead**: Return Result<T, E> and let caller handle errors\n\n## Development Workflow\n\n1. **Design Types**: Define structs, enums, and traits\n2. **Implement Logic**: Ownership-aware implementation\n3. **Add Error Handling**: thiserror for libraries, anyhow for apps\n4. **Write Tests**: Unit, integration, doc tests\n5. **Async Patterns**: tokio for async I/O, proper task spawning\n6. **Run Clippy**: Fix all lints and warnings\n7. **Benchmark**: criterion for performance testing\n8. **Build Release**: cargo build --release with optimizations\n\n## Resources for Deep Dives\n\n- Official Rust Book: https://doc.rust-lang.org/book/\n- Rust by Example: https://doc.rust-lang.org/rust-by-example/\n- Async Rust: https://rust-lang.github.io/async-book/\n- Tokio Docs: https://tokio.rs/\n- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/\n\n## Success Metrics (95% Confidence)\n\n- **Safety**: No unsafe blocks without justification, clippy clean\n- **Testing**: Comprehensive unit/integration tests, property-based for complex logic\n- **Performance**: Zero-cost abstractions, profiled and optimized\n- **Error Handling**: Proper Result usage, no unwrap in production code\n- **Search Utilization**: WebSearch for all medium-complex Rust patterns\n\nAlways prioritize **memory safety without garbage collection**, **zero-cost abstractions**, **fearless concurrency**, and **search-first methodology**.",
+  "instructions": "# Rust Engineer\n\n## Identity & Expertise\nRust 2024 edition specialist delivering memory-safe, high-performance systems with ownership/borrowing mastery, async patterns (tokio), zero-cost abstractions, and comprehensive error handling (thiserror/anyhow). Expert in building reliable concurrent systems with compile-time safety guarantees.\n\n## Search-First Workflow (MANDATORY)\n\n**When to Search**:\n- Rust 2024 edition new features\n- Ownership and lifetime patterns\n- Async Rust patterns with tokio\n- Error handling (thiserror/anyhow)\n- Trait design and composition\n- Performance optimization techniques\n\n**Search Template**: \"Rust 2024 [feature] best practices\" or \"Rust async [pattern] tokio implementation\"\n\n**Validation Process**:\n1. Check official Rust documentation\n2. Verify with production examples\n3. Test with clippy lints\n4. Cross-reference Rust API guidelines\n\n## Core Capabilities\n\n- **Rust 2024 Edition**: Async fn in traits, async drop, async closures, inherent vs accidental complexity focus\n- **Ownership/Borrowing**: Move semantics, borrowing rules, lifetimes, smart pointers (Box, Rc, Arc)\n- **Async Programming**: tokio runtime, async/await, futures, Arc<Mutex> for thread-safe state\n- **Error Handling**: Result<T,E>, Option<T>, thiserror for library errors, anyhow for applications\n- **Trait System**: Trait bounds, associated types, trait objects, composition over inheritance\n- **Zero-Cost Abstractions**: Iterator patterns, generics without runtime overhead\n- **Concurrency**: Send/Sync traits, Arc<Mutex>, message passing with channels\n- **Testing**: Unit tests, integration tests, doc tests, property-based with proptest\n\n## Architecture Patterns (Service-Oriented Design)\n\n### When to Use Service-Oriented Architecture\n\n**Use DI/SOA Pattern For:**\n- Web services and REST APIs (actix-web, axum, rocket)\n- Microservices with multiple service layers\n- Applications with swappable implementations (mock DB for testing)\n- Domain-driven design with repositories and services\n- Systems requiring dependency injection for testing\n- Long-lived services with complex business logic\n\n**Keep It Simple For:**\n- CLI tools and command-line utilities\n- One-off scripts and automation tasks\n- Prototypes and proof-of-concepts\n- Single-responsibility binaries\n- Performance-critical tight loops\n- Embedded systems with size constraints\n\n### Dependency Injection with Traits\n\nRust achieves DI through trait-based abstractions and constructor injection.\n\n**Pattern 1: Constructor Injection with Trait Bounds**\n```rust\n// Define trait interface (contract)\ntrait UserRepository: Send + Sync {\n    async fn find_by_id(&self, id: u64) -> Result<Option<User>, DbError>;\n    async fn save(&self, user: &User) -> Result<(), DbError>;\n}\n\n// Service depends on trait, not concrete implementation\nstruct UserService<R: UserRepository> {\n    repository: R,\n    cache: Arc<dyn Cache>,\n}\n\nimpl<R: UserRepository> UserService<R> {\n    // Constructor injection\n    pub fn new(repository: R, cache: Arc<dyn Cache>) -> Self {\n        Self { repository, cache }\n    }\n    \n    pub async fn get_user(&self, id: u64) -> Result<User, ServiceError> {\n        // Check cache first\n        if let Some(cached) = self.cache.get(&format!(\"user:{}\", id)).await? {\n            return Ok(cached);\n        }\n        \n        // Fetch from repository\n        let user = self.repository.find_by_id(id).await?\n            .ok_or(ServiceError::NotFound)?;\n        \n        // Update cache\n        self.cache.set(&format!(\"user:{}\", id), &user).await?;\n        \n        Ok(user)\n    }\n}\n```\n\n**Pattern 2: Trait Objects for Runtime Polymorphism**\n```rust\n// Use trait objects when type must be determined at runtime\nstruct UserService {\n    repository: Arc<dyn UserRepository>,\n    cache: Arc<dyn Cache>,\n}\n\nimpl UserService {\n    pub fn new(\n        repository: Arc<dyn UserRepository>,\n        cache: Arc<dyn Cache>,\n    ) -> Self {\n        Self { repository, cache }\n    }\n}\n\n// Easy to swap implementations for testing\n#[cfg(test)]\nmod tests {\n    use super::*;\n    \n    struct MockUserRepository;\n    \n    #[async_trait]\n    impl UserRepository for MockUserRepository {\n        async fn find_by_id(&self, id: u64) -> Result<Option<User>, DbError> {\n            // Return test data\n            Ok(Some(User::test_user()))\n        }\n        \n        async fn save(&self, user: &User) -> Result<(), DbError> {\n            Ok(())\n        }\n    }\n    \n    #[tokio::test]\n    async fn test_get_user() {\n        let mock_repo = Arc::new(MockUserRepository);\n        let mock_cache = Arc::new(InMemoryCache::new());\n        let service = UserService::new(mock_repo, mock_cache);\n        \n        let user = service.get_user(1).await.unwrap();\n        assert_eq!(user.id, 1);\n    }\n}\n```\n\n**Pattern 3: Builder Pattern for Complex Construction**\n```rust\n// Builder for services with many dependencies\nstruct AppBuilder {\n    db_url: Option<String>,\n    cache_ttl: Option<Duration>,\n    log_level: Option<String>,\n}\n\nimpl AppBuilder {\n    pub fn new() -> Self {\n        Self {\n            db_url: None,\n            cache_ttl: None,\n            log_level: None,\n        }\n    }\n    \n    pub fn with_database(mut self, url: String) -> Self {\n        self.db_url = Some(url);\n        self\n    }\n    \n    pub fn with_cache_ttl(mut self, ttl: Duration) -> Self {\n        self.cache_ttl = Some(ttl);\n        self\n    }\n    \n    pub async fn build(self) -> Result<App, BuildError> {\n        let db_url = self.db_url.ok_or(BuildError::MissingDatabase)?;\n        let cache_ttl = self.cache_ttl.unwrap_or(Duration::from_secs(300));\n        \n        // Construct dependencies\n        let db_pool = create_pool(&db_url).await?;\n        let repository = Arc::new(PostgresUserRepository::new(db_pool));\n        let cache = Arc::new(RedisCache::new(cache_ttl));\n        \n        // Inject into services\n        let user_service = Arc::new(UserService::new(repository, cache));\n        \n        Ok(App { user_service })\n    }\n}\n\n// Usage\nlet app = AppBuilder::new()\n    .with_database(\"postgres://localhost/db\".to_string())\n    .with_cache_ttl(Duration::from_secs(600))\n    .build()\n    .await?;\n```\n\n**Repository Pattern for Data Access**\n```rust\n// Abstract data access behind trait\ntrait Repository<T>: Send + Sync {\n    async fn find(&self, id: u64) -> Result<Option<T>, DbError>;\n    async fn save(&self, entity: &T) -> Result<(), DbError>;\n    async fn delete(&self, id: u64) -> Result<(), DbError>;\n}\n\n// Concrete implementation\nstruct PostgresUserRepository {\n    pool: PgPool,\n}\n\n#[async_trait]\nimpl Repository<User> for PostgresUserRepository {\n    async fn find(&self, id: u64) -> Result<Option<User>, DbError> {\n        sqlx::query_as!(User, \"SELECT * FROM users WHERE id = $1\", id as i64)\n            .fetch_optional(&self.pool)\n            .await\n            .map_err(Into::into)\n    }\n    \n    async fn save(&self, user: &User) -> Result<(), DbError> {\n        sqlx::query!(\n            \"INSERT INTO users (id, email, name) VALUES ($1, $2, $3)\n             ON CONFLICT (id) DO UPDATE SET email = $2, name = $3\",\n            user.id as i64, user.email, user.name\n        )\n        .execute(&self.pool)\n        .await?;\n        Ok(())\n    }\n    \n    async fn delete(&self, id: u64) -> Result<(), DbError> {\n        sqlx::query!(\"DELETE FROM users WHERE id = $1\", id as i64)\n            .execute(&self.pool)\n            .await?;\n        Ok(())\n    }\n}\n```\n\n**Key Principles:**\n- **Depend on abstractions (traits), not concrete types**\n- **Constructor injection for compile-time polymorphism** (generic bounds)\n- **Trait objects for runtime polymorphism** (Arc<dyn Trait>)\n- **Repository pattern isolates data access**\n- **Service layer encapsulates business logic**\n- **Builder pattern for complex dependency graphs**\n- **Send + Sync bounds for async/concurrent safety**\n\n## Quality Standards\n\n**Code Quality**: cargo fmt formatted, clippy lints passing, idiomatic Rust patterns\n\n**Testing**: Unit tests for logic, integration tests for APIs, doc tests for examples, property-based for complex invariants\n\n**Performance**: Zero-cost abstractions, profiling with cargo flamegraph, benchmarking with criterion\n\n**Safety**: No unsafe unless absolutely necessary, clippy::all + clippy::pedantic, no panic in library code\n\n## Production Patterns\n\n### Pattern 1: Error Handling\nthiserror for library errors (derive Error), anyhow for applications (context and error chaining), Result propagation with `?` operator.\n\n### Pattern 2: Async with Tokio\nAsync functions with tokio::spawn for concurrency, Arc<Mutex> for shared state, channels for message passing, graceful shutdown.\n\n### Pattern 3: Trait-Based Design\nSmall traits for specific capabilities, trait bounds for generic functions, associated types for family of types, trait objects for dynamic dispatch.\n\n### Pattern 4: Ownership Patterns\nMove by default, borrow when needed, lifetimes for references, Cow<T> for clone-on-write, smart pointers for shared ownership.\n\n### Pattern 5: Iterator Chains\nLazy evaluation, zero-cost abstractions, combinators (map, filter, fold), collect for materialization.\n\n### Pattern 6: Dependency Injection with Traits\nTrait-based interfaces for services, constructor injection with generic bounds or trait objects, repository pattern for data access, service layer for business logic. Use Arc<dyn Trait> for runtime polymorphism, generic bounds for compile-time dispatch. Builder pattern for complex dependency graphs.\n\n## Anti-Patterns to Avoid\n\nL **Cloning Everywhere**: Excessive .clone() calls\n **Instead**: Use borrowing, Cow<T>, or Arc for shared ownership\n\nL **String Everywhere**: Using String when &str would work\n **Instead**: Accept &str in functions, use String only when ownership needed\n\nL **Ignoring Clippy**: Not running clippy lints\n **Instead**: cargo clippy --all-targets --all-features, fix all warnings\n\nL **Blocking in Async**: Calling blocking code in async functions\n **Instead**: Use tokio::task::spawn_blocking for blocking operations\n\nL **Panic in Libraries**: Using panic! for error conditions\n **Instead**: Return Result<T, E> and let caller handle errors\n\nL **Global State for Dependencies**: Using static/lazy_static for services\n **Instead**: Constructor injection with traits, pass dependencies explicitly\n\nL **Concrete Types in Service Signatures**: Coupling services to implementations\n **Instead**: Depend on trait abstractions (trait bounds or Arc<dyn Trait>)\n\n## Development Workflow\n\n1. **Design Types**: Define structs, enums, and traits\n2. **Implement Logic**: Ownership-aware implementation\n3. **Add Error Handling**: thiserror for libraries, anyhow for apps\n4. **Write Tests**: Unit, integration, doc tests\n5. **Async Patterns**: tokio for async I/O, proper task spawning\n6. **Run Clippy**: Fix all lints and warnings\n7. **Benchmark**: criterion for performance testing\n8. **Build Release**: cargo build --release with optimizations\n\n## Resources for Deep Dives\n\n- Official Rust Book: https://doc.rust-lang.org/book/\n- Rust by Example: https://doc.rust-lang.org/rust-by-example/\n- Async Rust: https://rust-lang.github.io/async-book/\n- Tokio Docs: https://tokio.rs/\n- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/\n\n## Success Metrics (95% Confidence)\n\n- **Safety**: No unsafe blocks without justification, clippy clean\n- **Testing**: Comprehensive unit/integration tests, property-based for complex logic\n- **Performance**: Zero-cost abstractions, profiled and optimized\n- **Error Handling**: Proper Result usage, no unwrap in production code\n- **Search Utilization**: WebSearch for all medium-complex Rust patterns\n\nAlways prioritize **memory safety without garbage collection**, **zero-cost abstractions**, **fearless concurrency**, and **search-first methodology**.",
   "knowledge": {
     "domain_expertise": [
       "Rust 2024 edition features",
@@ -98,8 +103,8 @@
     ],
     "examples": [
       {
-        "scenario": "Building async HTTP service",
-        "approach": "tokio runtime, async handlers, thiserror for errors, Arc<Mutex> for state, graceful shutdown"
+        "scenario": "Building async HTTP service with DI",
+        "approach": "Define UserRepository trait interface, implement UserService with constructor injection using generic bounds, use Arc<dyn Cache> for runtime polymorphism, tokio runtime for async handlers, thiserror for error types, graceful shutdown with proper cleanup"
       },
       {
         "scenario": "Error handling in library",

claude_mpm/cli/commands/mpm_init.py

@@ -1952,19 +1952,24 @@ def context_command(session_id, days, project_path):
         sys.exit(1)
 
 
-# Add deprecated 'resume' alias for backward compatibility
-@mpm_init.command(name="resume", hidden=True)
+# Resume command - NEW: reads from stop event logs
+@mpm_init.command(name="resume")
+@click.option(
+    "--list",
+    "list_sessions",
+    is_flag=True,
+    help="List available sessions from logs",
+)
 @click.option(
     "--session-id",
-    "-i",
+    "-s",
     type=str,
-    help="Unused (for compatibility) - will be removed in future version",
+    help="Resume specific session by ID",
 )
 @click.option(
-    "--days",
+    "--last",
     type=int,
-    default=7,
-    help="Number of days of git history to analyze (default: 7)",
+    help="Show last N sessions",
 )
 @click.argument(
     "project_path",
@@ -1972,35 +1977,115 @@ def context_command(session_id, days, project_path):
     required=False,
     default=".",
 )
-def resume_session(session_id, days, project_path):
+def resume_command(list_sessions, session_id, last, project_path):
     """
-    [DEPRECATED] Use 'context' instead.
+    Resume work from previous session using stop event logs.
+
+    Reads from:
+    - .claude-mpm/resume-logs/ (structured summaries, preferred)
+    - .claude-mpm/responses/ (raw conversation logs, fallback)
 
-    This command is deprecated and will be removed in a future version.
-    Please use 'claude-mpm mpm-init context' instead.
+    Examples:
+        claude-mpm mpm-init resume                    # Show latest session
+        claude-mpm mpm-init resume --list             # List all sessions
+        claude-mpm mpm-init resume --session-id ID    # Resume specific session
+        claude-mpm mpm-init resume --last 5           # Show last 5 sessions
     """
-    console.print(
-        "[yellow]⚠️  Warning: 'resume' is deprecated. Use 'context' instead.[/yellow]"
-    )
-    console.print("[dim]Run: claude-mpm mpm-init context[/dim]\n")
+    from claude_mpm.services.cli.resume_service import ResumeService
 
     try:
-        command = MPMInitCommand(Path(project_path))
-        result = command.handle_context(session_id=session_id, days=days)
+        service = ResumeService(Path(project_path))
 
-        if (
-            result["status"] == OperationResult.SUCCESS
-            or result["status"] == OperationResult.CONTEXT_READY
-        ):
+        # Handle --list flag
+        if list_sessions:
+            sessions = service.list_sessions()
+            if not sessions:
+                console.print("[yellow]No sessions found in response logs.[/yellow]")
+                console.print(
+                    "[dim]Sessions are stored in .claude-mpm/responses/[/dim]\n"
+                )
+                sys.exit(1)
+
+            # Limit by --last if specified
+            if last and last > 0:
+                sessions = sessions[:last]
+
+            console.print(
+                f"\n[bold cyan]📋 Available Sessions ({len(sessions)})[/bold cyan]\n"
+            )
+
+            from rich.table import Table
+
+            table = Table(show_header=True, header_style="bold magenta")
+            table.add_column("Session ID", style="cyan", width=25)
+            table.add_column("Time", style="yellow", width=20)
+            table.add_column("Agent", style="green", width=15)
+            table.add_column("Stop Reason", style="white", width=20)
+            table.add_column("Tokens", style="dim", width=10)
+
+            for session in sessions:
+                time_str = session.timestamp.strftime("%Y-%m-%d %H:%M")
+                tokens_str = (
+                    f"{session.token_usage // 1000}k"
+                    if session.token_usage > 0
+                    else "-"
+                )
+
+                table.add_row(
+                    session.session_id,
+                    time_str,
+                    session.last_agent,
+                    session.stop_reason,
+                    tokens_str,
+                )
+
+            console.print(table)
+            console.print()
             sys.exit(0)
+
+        # Handle --session-id
+        if session_id:
+            context = service.get_session_context(session_id)
+            if not context:
+                console.print(f"[red]Session '{session_id}' not found.[/red]")
+                console.print("[dim]Use --list to see available sessions.[/dim]\n")
+                sys.exit(1)
         else:
-            sys.exit(1)
+            # Default: get latest session
+            context = service.get_latest_session()
+            if not context:
+                console.print("[yellow]No sessions found in logs.[/yellow]")
+                console.print(
+                    "[dim]Sessions are stored in .claude-mpm/responses/[/dim]\n"
+                )
+                sys.exit(1)
+
+        # Display context
+        display_text = service.format_resume_display(context)
+        console.print(display_text)
+
+        # Ask if user wants to continue
+        from rich.prompt import Confirm
+
+        should_continue = Confirm.ask(
+            "\n[bold]Would you like to continue this work?[/bold]", default=True
+        )
+
+        if should_continue:
+            console.print(
+                "\n[green]✅ Great! Use this context to continue your work.[/green]\n"
+            )
+            sys.exit(0)
+        else:
+            console.print("\n[cyan]Starting fresh session instead.[/cyan]\n")
+            sys.exit(0)
 
     except KeyboardInterrupt:
-        console.print("\n[yellow]Context analysis cancelled by user[/yellow]")
+        console.print("\n[yellow]Resume cancelled by user[/yellow]")
         sys.exit(130)
     except Exception as e:
-        console.print(f"[red]Context analysis failed: {e}[/red]")
+        logger.error(f"Resume failed: {e}")
+        console.print(f"[red]Resume failed: {e}[/red]")
         sys.exit(1)
 
 

claude_mpm/commands/mpm-init.md

@@ -9,6 +9,9 @@ Initialize or intelligently update your project for optimal use with Claude Code
 /mpm-init update               # Lightweight update based on recent git activity
 /mpm-init context              # Intelligent context analysis from git history
 /mpm-init context --days 14    # Analyze last 14 days of git history
+/mpm-init resume               # Resume from stop event logs (NEW)
+/mpm-init resume --list        # List all sessions from logs
+/mpm-init resume --session-id ID  # Resume specific session
 /mpm-init catchup              # Quick commit history display (no analysis)
 /mpm-init --review             # Review project state without changes
 /mpm-init --update             # Full update of existing CLAUDE.md
@@ -24,7 +27,9 @@ This command has two primary modes:
 - **Project initialization/updates**: Delegates to the Agentic Coder Optimizer agent for documentation, tooling, and workflow setup
 - **Context analysis** (context/catchup): Provides intelligent project context from git history for resuming work
 
-**Note**: The `resume` subcommand is deprecated. Use `context` instead. The `resume` command still works for backward compatibility but will be removed in a future version.
+**Resume Modes**: The command provides two resume capabilities:
+- `/mpm-init resume`: Reads stop event logs from `.claude-mpm/responses/` to help resume work
+- `/mpm-init context`: Analyzes git history for intelligent work resumption (delegates to Research agent)
 
 **Quick Update Mode**: Running `/mpm-init update` performs a lightweight update focused on recent git activity. It analyzes recent commits, generates an activity report, and updates documentation with minimal changes. Perfect for quick refreshes after development sprints.
 
@@ -87,8 +92,46 @@ Analyzes recent git commits to identify:
 
 **NOT session state**: This does NOT save/restore conversation state like Claude Code. Instead, it reconstructs project context from git history using conventional commits and commit message analysis.
 
-#### `/mpm-init resume` [DEPRECATED]
-Alias for `context`. Use `context` instead.
+#### `/mpm-init resume` (Stop Event Logs)
+```bash
+/mpm-init resume                    # Show latest session from logs
+/mpm-init resume --list             # List all sessions
+/mpm-init resume --session-id ID    # Resume specific session
+/mpm-init resume --last 5           # Show last 5 sessions
+```
+
+Reads from stop event logs to help resume work from previous sessions:
+
+**Data Sources** (two-tier strategy):
+1. **Resume logs** (preferred): `.claude-mpm/resume-logs/*.md` - Structured 10k-token summaries
+2. **Response logs** (fallback): `.claude-mpm/responses/*.json` - Raw conversation stop events
+
+**What it shows**:
+- When session ended (time ago)
+- What was being worked on (request)
+- Tasks completed (from PM responses)
+- Files modified (from PM tracking)
+- Next steps (from PM recommendations)
+- Stop reason (why session ended)
+- Token usage (context consumption)
+- Git context (branch, working directory)
+
+**How it works**:
+1. Scans response logs in `.claude-mpm/responses/`
+2. Groups by `session_id`
+3. Parses PM response JSON for context
+4. Extracts tasks, files, next steps from PM summaries
+5. Displays comprehensive resume context
+
+**Use Cases**:
+- Resume work after context threshold pause
+- Review what was accomplished in previous session
+- Understand why session stopped (max_tokens, end_turn, etc.)
+- See exact files and tasks from last session
+
+**Difference from `context`**:
+- **resume**: Reads actual stop event logs (what PM logged)
+- **context**: Analyzes git commits (what was committed)
 
 ### `/mpm-init catchup` (Simple Git History)
 ```bash
@@ -225,6 +268,66 @@ This provides intelligent analysis including:
 
 The old `resume` command redirects to `context` with a deprecation warning.
 
+### Resume from Stop Event Logs
+
+Display context from previous sessions using stop event logs:
+
+```bash
+/mpm-init resume                    # Show latest session
+/mpm-init resume --list             # List all available sessions
+/mpm-init resume --session-id abc123  # Resume specific session
+/mpm-init resume --last 10          # Show last 10 sessions
+```
+
+Shows comprehensive context including:
+- What was being worked on
+- Tasks completed (from PM tracking)
+- Files modified
+- Next steps recommended
+- Stop reason (context limit, completion, etc.)
+- Token usage
+- Time elapsed since session
+
+**Example Output:**
+```
+================================================================================
+📋 Resume Context - Session from 2 hours ago
+================================================================================
+
+Session ID: 20251104_143000
+Ended: 2024-11-04 14:30 (2 hours ago)
+Stop Reason: Context threshold reached (70%)
+Token Usage: 140,000 / 200,000 (70%)
+
+Working on:
+  "Implementing auto-pause and resume functionality"
+
+✅ Completed:
+  • Researched stop event logging system
+  • Found response logs in .claude-mpm/responses/
+  • Identified two-tier resume strategy
+
+📝 Files Modified:
+  • src/claude_mpm/services/cli/resume_service.py (new)
+  • src/claude_mpm/cli/commands/mpm_init.py (updated)
+
+🎯 Next Steps:
+  • Implement ResumeService class
+  • Add resume subcommand to mpm-init
+  • Test with real response logs
+
+Git Context:
+  Branch: main
+  Working Directory: /Users/masa/Projects/claude-mpm
+================================================================================
+```
+
+**Use Cases:**
+- Resume after hitting context limit
+- Review what was accomplished in last session
+- See exact next steps recommended by PM
+- Understand why session stopped
+
 ### Quick Git History (Catchup)
 
 Display recent commit history without analysis:
@@ -388,9 +491,12 @@ The command delegates to the Agentic Coder Optimizer agent which:
 ## Notes
 
 - **Quick Update vs Full Update**: Use `/mpm-init update` for fast activity-based updates (30 days), or `/mpm-init --update` for comprehensive doc refresh
-- **Context Analysis**: Use `/mpm-init context` to analyze git history and get intelligent resumption context from Research agent
-- **Quick History**: Use `/mpm-init catchup` for instant commit history display without analysis
-- **Deprecation Notice**: The `resume` command is deprecated. Use `context` instead. The old command still works but shows a warning.
+- **Resume Strategies**:
+  - **`/mpm-init resume`**: Read stop event logs (what PM tracked in last session)
+  - **`/mpm-init context`**: Analyze git history (intelligent work stream analysis via Research)
+  - **`/mpm-init catchup`**: Quick commit history display (no analysis)
+- **Stop Event Logs**: Response logs in `.claude-mpm/responses/` contain PM summaries with tasks, files, and next steps
+- **Two-Tier Resume**: Prefers structured resume logs (`.claude-mpm/resume-logs/`), falls back to response logs
 - **Smart Mode**: Automatically detects existing CLAUDE.md and offers update vs recreate
 - **Safe Updates**: Previous versions always archived before updating
 - **Custom Content**: Your project-specific sections are preserved by default

claude_mpm/hooks/__init__.py

@@ -12,6 +12,11 @@ from .failure_learning import (
 from .kuzu_enrichment_hook import KuzuEnrichmentHook, get_kuzu_enrichment_hook
 from .kuzu_memory_hook import KuzuMemoryHook, get_kuzu_memory_hook
 from .kuzu_response_hook import KuzuResponseHook, get_kuzu_response_hook
+from .session_resume_hook import (
+    SessionResumeStartupHook,
+    get_session_resume_hook,
+    trigger_session_resume_check,
+)
 
 __all__ = [
     "BaseHook",
@@ -24,10 +29,13 @@ __all__ = [
     "KuzuMemoryHook",
     "KuzuResponseHook",
     "LearningExtractionHook",
+    "SessionResumeStartupHook",
     "get_failure_detection_hook",
     "get_fix_detection_hook",
     "get_kuzu_enrichment_hook",
     "get_kuzu_memory_hook",
     "get_kuzu_response_hook",
     "get_learning_extraction_hook",
+    "get_session_resume_hook",
+    "trigger_session_resume_check",
 ]

claude_mpm/hooks/session_resume_hook.py

@@ -0,0 +1,121 @@
+"""Session Resume Startup Hook.
+
+WHY: This hook automatically checks for paused sessions on PM startup and displays
+resume context to help users continue their work seamlessly.
+
+DESIGN DECISIONS:
+- Runs automatically on PM startup
+- Non-blocking: doesn't prevent PM from starting if check fails
+- Displays context to stdout for user visibility
+- Integrates with existing session pause/resume infrastructure
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logger import get_logger
+from claude_mpm.services.cli.session_resume_helper import SessionResumeHelper
+
+logger = get_logger(__name__)
+
+
+class SessionResumeStartupHook:
+    """Hook for automatic session resume detection on PM startup."""
+
+    def __init__(self, project_path: Optional[Path] = None):
+        """Initialize the session resume hook.
+
+        Args:
+            project_path: Project root path (default: current directory)
+        """
+        self.project_path = project_path or Path.cwd()
+        self.resume_helper = SessionResumeHelper(self.project_path)
+        self._session_displayed = False
+
+    def on_pm_startup(self) -> Optional[Dict[str, Any]]:
+        """Execute on PM startup to check for paused sessions.
+
+        Returns:
+            Session data if paused session found, None otherwise
+        """
+        try:
+            # Check if we already displayed a session in this process
+            if self._session_displayed:
+                logger.debug("Session already displayed, skipping")
+                return None
+
+            # Check for paused sessions
+            session_data = self.resume_helper.check_and_display_resume_prompt()
+
+            if session_data:
+                self._session_displayed = True
+                logger.info("Paused session context displayed to user")
+
+            return session_data
+
+        except Exception as e:
+            logger.error(f"Failed to check for paused sessions: {e}", exc_info=True)
+            return None
+
+    def get_session_count(self) -> int:
+        """Get count of paused sessions.
+
+        Returns:
+            Number of paused sessions
+        """
+        try:
+            return self.resume_helper.get_session_count()
+        except Exception as e:
+            logger.error(f"Failed to get session count: {e}")
+            return 0
+
+    def clear_displayed_session(self, session_data: Dict[str, Any]) -> bool:
+        """Clear a session after it has been displayed and user has acknowledged.
+
+        Args:
+            session_data: Session data to clear
+
+        Returns:
+            True if successfully cleared, False otherwise
+        """
+        try:
+            return self.resume_helper.clear_session(session_data)
+        except Exception as e:
+            logger.error(f"Failed to clear session: {e}")
+            return False
+
+
+# Global hook instance
+_session_resume_hook: Optional[SessionResumeStartupHook] = None
+
+
+def get_session_resume_hook(
+    project_path: Optional[Path] = None,
+) -> SessionResumeStartupHook:
+    """Get or create the global session resume hook instance.
+
+    Args:
+        project_path: Project root path (default: current directory)
+
+    Returns:
+        SessionResumeStartupHook instance
+    """
+    global _session_resume_hook
+
+    if _session_resume_hook is None:
+        _session_resume_hook = SessionResumeStartupHook(project_path)
+        logger.debug("Created session resume hook instance")
+
+    return _session_resume_hook
+
+
+def trigger_session_resume_check() -> Optional[Dict[str, Any]]:
+    """Trigger a session resume check (convenience function).
+
+    This is the main entry point for PM startup integration.
+
+    Returns:
+        Session data if found, None otherwise
+    """
+    hook = get_session_resume_hook()
+    return hook.on_pm_startup()