aiwcli 0.9.2 → 0.9.5

package/dist/templates/_shared/lib/base/hook_utils.py

@@ -0,0 +1,169 @@
+"""Common utilities for hook scripts.
+
+Provides standardized boilerplate for:
+- Path setup for imports
+- JSON parsing from stdin
+- Hook payload validation
+- Error handling decorators
+"""
+
+import json
+import sys
+from functools import wraps
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+from .utils import eprint
+
+# Type variable for generic decorators
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def setup_hook_paths() -> Path:
+    """
+    Setup import paths for hooks.
+
+    Call this at module level in hook scripts to ensure
+    the shared lib directory is in sys.path.
+
+    Returns:
+        Path to the lib directory
+
+    Example:
+        SCRIPT_DIR = Path(__file__).resolve().parent
+        SHARED_LIB = SCRIPT_DIR.parent / "lib"
+        sys.path.insert(0, str(SHARED_LIB.parent))
+    """
+    # This function exists mainly for documentation
+    # Actual path setup must happen at module level before imports
+    hook_dir = Path(__file__).resolve().parent.parent.parent / "hooks"
+    lib_dir = hook_dir.parent / "lib"
+    if str(lib_dir.parent) not in sys.path:
+        sys.path.insert(0, str(lib_dir.parent))
+    return lib_dir
+
+
+def load_hook_input() -> Optional[Dict[str, Any]]:
+    """
+    Load and parse JSON from stdin.
+
+    Returns:
+        Parsed JSON dict, or None if stdin is empty or invalid JSON
+    """
+    try:
+        input_data = sys.stdin.read().strip()
+        if not input_data:
+            return None
+        return json.loads(input_data)
+    except json.JSONDecodeError:
+        return None
+
+
+def validate_hook_event(
+    payload: Dict[str, Any],
+    expected_event: str,
+    expected_tool: Optional[str] = None
+) -> bool:
+    """
+    Validate hook event type and optional tool name.
+
+    Args:
+        payload: Hook payload from stdin
+        expected_event: Expected hook_event_name (e.g., "PostToolUse", "PreToolUse")
+        expected_tool: Optional expected tool_name (e.g., "TaskCreate")
+
+    Returns:
+        True if payload matches expected event/tool, False otherwise
+    """
+    if payload.get("hook_event_name") != expected_event:
+        return False
+    if expected_tool and payload.get("tool_name") != expected_tool:
+        return False
+    return True
+
+
+def get_tool_input(payload: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Extract and validate tool_input from payload.
+
+    Args:
+        payload: Hook payload from stdin
+
+    Returns:
+        tool_input dict, or None if missing/invalid
+    """
+    tool_input = payload.get("tool_input", {})
+    return tool_input if isinstance(tool_input, dict) else None
+
+
+def check_skip_persistence(payload: Dict[str, Any], hook_name: str = "hook") -> bool:
+    """
+    Check if persistence should be skipped based on metadata flags.
+
+    Args:
+        payload: Hook payload from stdin
+        hook_name: Name of hook for logging
+
+    Returns:
+        True if skip_persistence flag is set, False otherwise
+    """
+    tool_input = get_tool_input(payload)
+    if not tool_input:
+        return False
+
+    metadata = tool_input.get("metadata", {})
+    if isinstance(metadata, dict) and metadata.get("skip_persistence"):
+        eprint(f"[{hook_name}] Skipping persistence (skip_persistence flag set)")
+        return True
+    return False
+
+
+def safe_hook_main(hook_name: str) -> Callable[[F], F]:
+    """
+    Decorator for hook main functions with standard error handling.
+
+    Catches exceptions, logs them to stderr, and returns 0 (non-blocking).
+
+    Args:
+        hook_name: Name of hook for error messages
+
+    Returns:
+        Decorator function
+
+    Example:
+        @safe_hook_main("my_hook")
+        def main() -> int:
+            # ... hook logic ...
+            return 0
+    """
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                return func(*args, **kwargs)
+            except json.JSONDecodeError as e:
+                eprint(f"[{hook_name}] JSON decode error: {e}")
+                return 0
+            except Exception as e:
+                eprint(f"[{hook_name}] Unexpected error: {e}")
+                import traceback
+                eprint(traceback.format_exc())
+                return 0
+        return wrapper  # type: ignore
+    return decorator
+
+
+def run_hook(main_func: Callable[[], int]) -> None:
+    """
+    Standard hook entry point wrapper.
+
+    Calls main function and exits with its return code.
+
+    Args:
+        main_func: Hook main function that returns exit code
+
+    Example:
+        if __name__ == "__main__":
+            run_hook(main)
+    """
+    raise SystemExit(main_func())

package/dist/templates/_shared/lib/context/__init__.py

@@ -37,6 +37,7 @@ from .discovery import (
     format_implementation_continuation,
     format_context_picker_prompt,
     format_ready_for_new_work,
+    format_relative_time,
 )
 from .task_sync import (
     generate_task_summary,
@@ -54,6 +55,10 @@ from .plan_archive import (
     mark_plan_implementation_started,
     mark_plan_completed,
 )
+from .context_extractor import (
+    extract_context_id,
+    extract_context_id_for_session,
+)
 
 __all__ = [
     # Data Classes
@@ -92,6 +97,7 @@ __all__ = [
     "format_implementation_continuation",
     "format_context_picker_prompt",
     "format_ready_for_new_work",
+    "format_relative_time",
     # Task Sync
     "generate_task_summary",
     "record_session_start",
@@ -106,4 +112,7 @@ __all__ = [
     "create_context_from_plan",
     "mark_plan_implementation_started",
     "mark_plan_completed",
+    # Context Extractor
+    "extract_context_id",
+    "extract_context_id_for_session",
 ]

package/dist/templates/_shared/lib/context/context_extractor.py

@@ -0,0 +1,115 @@
+"""Context ID extraction from hook payloads.
+
+Centralizes the logic for determining which context a hook operation
+belongs to, using multiple fallback strategies.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .context_manager import get_context_by_session_id, get_all_contexts
+from ..base.utils import eprint
+
+
+def extract_context_id(
+    tool_input: Dict[str, Any],
+    project_root: Path,
+    session_id: Optional[str] = None,
+    hook_name: str = "hook",
+    check_persistent_id: bool = False
+) -> Optional[str]:
+    """
+    Extract context ID from tool input with multiple fallback strategies.
+
+    Order of precedence:
+    1. metadata.context field (explicit context specification)
+    2. Session ID lookup (session bound to context)
+    3. persistent_id parsing (if check_persistent_id=True, for TaskCreate)
+    4. Single active context fallback
+
+    Args:
+        tool_input: Tool input dict from hook payload
+        project_root: Project root directory
+        session_id: Optional session ID from hook payload
+        hook_name: Name of calling hook for log messages
+        check_persistent_id: Whether to check persistent_id for context hint
+                           (used by task_create_capture for ID format parsing)
+
+    Returns:
+        Context ID string, or None if context cannot be determined
+    """
+    # 1. Check metadata.context field (explicit)
+    metadata = tool_input.get("metadata", {})
+    if isinstance(metadata, dict):
+        context = metadata.get("context")
+        if context:
+            return context
+
+    # 2. Check session ID (session may be bound to a context)
+    if session_id:
+        try:
+            session_context = get_context_by_session_id(session_id, project_root)
+            if session_context:
+                eprint(f"[{hook_name}] Found context via session_id: {session_context.id}")
+                return session_context.id
+        except Exception as e:
+            eprint(f"[{hook_name}] Failed to lookup context by session: {e}")
+
+    # 3. Check persistent_id for context hint (task_create only)
+    # Format: "context-id-task-N" or similar
+    if check_persistent_id and isinstance(metadata, dict):
+        persistent_id = metadata.get("persistent_id", "")
+        if persistent_id and "-" in persistent_id:
+            parts = persistent_id.split("-")
+            if len(parts) >= 2:
+                # Reconstruct context ID (everything before last two parts)
+                context_parts = parts[:-2] if len(parts) > 2 else parts[:1]
+                potential_id = "-".join(context_parts)
+                if potential_id:
+                    return potential_id
+
+    # 4. Check for single active context (fallback)
+    try:
+        contexts = get_all_contexts(status="active", project_root=project_root)
+        if len(contexts) == 1:
+            return contexts[0].id
+    except Exception as e:
+        eprint(f"[{hook_name}] Failed to get active contexts: {e}")
+
+    return None
+
+
+def extract_context_id_for_session(
+    session_id: str,
+    project_root: Path,
+    hook_name: str = "hook"
+) -> Optional[str]:
+    """
+    Find context that matches this session_id.
+
+    Simpler variant for hooks that only need session-based lookup.
+
+    Args:
+        session_id: Session ID to match
+        project_root: Project root directory
+        hook_name: Name of calling hook for log messages
+
+    Returns:
+        Context ID or None if not found
+    """
+    contexts = get_all_contexts(status="active", project_root=project_root)
+
+    # Primary strategy: Find context with matching session_id
+    for ctx in contexts:
+        if ctx.in_flight and ctx.in_flight.session_ids and session_id in ctx.in_flight.session_ids:
+            eprint(f"[{hook_name}] Found context by session: {ctx.id}")
+            return ctx.id
+
+    # Fallback: If only one context is planning, assume it's the one
+    planning_contexts = [c for c in contexts if c.in_flight and c.in_flight.mode == "planning"]
+    if len(planning_contexts) == 1:
+        eprint(f"[{hook_name}] Fallback: Single planning context: {planning_contexts[0].id}")
+        return planning_contexts[0].id
+
+    eprint(f"[{hook_name}] Could not find context for session {session_id}")
+    return None

package/dist/templates/_shared/lib/context/discovery.py

@@ -105,7 +105,7 @@ def format_context_list(contexts: List[Context]) -> str:
 
     for i, ctx in enumerate(contexts, 1):
         # Format last active time
-        time_str = _format_relative_time(ctx.last_active)
+        time_str = format_relative_time(ctx.last_active)
 
         # Build status indicator
         status_indicator = ""
@@ -314,7 +314,7 @@ def format_context_selection_required(contexts: List[Context]) -> str:
     ]
 
     for i, ctx in enumerate(contexts, 1):
-        time_str = _format_relative_time(ctx.last_active)
+        time_str = format_relative_time(ctx.last_active)
 
         # Add status indicator for in-flight work
         status = ""
@@ -345,7 +345,7 @@ def format_active_context_reminder(context: Context) -> str:
     Returns:
         Formatted system reminder
     """
-    time_str = _format_relative_time(context.last_active)
+    time_str = format_relative_time(context.last_active)
 
     # Build mode display
     mode_display = "Active"
@@ -392,7 +392,7 @@ def format_context_created(context: Context) -> str:
     return "\n".join(lines)
 
 
-def _format_relative_time(iso_timestamp: Optional[str]) -> str:
+def format_relative_time(iso_timestamp: Optional[str]) -> str:
     """
     Format ISO timestamp as relative time string.
 

package/dist/templates/cc-native/.claude/agents/cc-native/ARCHITECT-REVIEWER.md

@@ -8,14 +8,13 @@ categories:
   - code
   - infrastructure
   - design
-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
-## Role
+# Architect Reviewer - Plan Review Agent
 
-Senior architecture reviewer with expertise in evaluating system designs, architectural decisions, and technology choices. Focus on design patterns, scalability assessment, integration strategies, and technical debt analysis with emphasis on building sustainable, evolvable systems.
+Senior architecture reviewer evaluating system designs, architectural decisions, and technology choices.
 
-## Review Focus
+## Your Expertise
 
 ### 1. Design Patterns & Structure
 Component boundaries, service contracts, dependency management, coupling/cohesion balance, appropriate pattern selection (microservices, event-driven, layered), and domain-driven design alignment.
@@ -26,50 +25,24 @@ Horizontal/vertical scaling readiness, data partitioning strategy, caching layer
 ### 3. Technical Debt & Evolution
 Architecture smells, technology obsolescence risks, complexity metrics, maintenance burden assessment, modernization path clarity, and reversibility of decisions.
 
-## Output Format
+## CRITICAL: Single-Turn Review
 
-**Example 1: Design Pattern Issue**
-```
-HIGH: Tight coupling between OrderService and PaymentService
-- Location: services/order.ts imports payment internals directly
-- Issue: Changes to PaymentService internal implementation will break OrderService
-- Fix: Define PaymentGateway interface in shared contracts, inject implementation
-```
+When reviewing a plan, you MUST:
+1. Analyze the plan content provided directly (do NOT use Read, Write, Edit, Bash, Glob, Grep, or any tools)
+2. Call StructuredOutput IMMEDIATELY with your assessment
+3. Complete your entire review in ONE response
 
-**Example 2: Scalability Concern**
-```
-MEDIUM: Single-threaded processing bottleneck in data pipeline
-- Location: workers/etl-processor.ts
-- Issue: Sequential processing limits throughput to ~100 records/sec
-- Fix: Implement worker pool pattern or use message queue for parallel processing
-```
+Do NOT:
+- Query context managers or external systems
+- Read files from the codebase
+- Request architecture documentation
+- Ask follow-up questions
 
-## Process
+## Required Output
 
-1. Review architectural documentation and codebase structure
-2. Evaluate design decisions against stated requirements and constraints
-3. Assess scalability headroom and evolution flexibility
-4. Provide strategic recommendations with trade-off analysis
-
-## Communication Protocol
-
-Request architecture context when starting:
-```json
-{
-  "requesting_agent": "architect-reviewer",
-  "request_type": "get_architecture_context",
-  "payload": {
-    "query": "Architecture context needed: system purpose, scale requirements, constraints, and evolution plans."
-  }
-}
-```
-
-## Review Completion
-
-Report findings structured by impact (architectural → systemic → local) with:
-- Component/service references
-- Clear problem description with trade-off analysis
-- Recommended approach with alternatives considered
-- Migration path if changes required
-
-Prioritize long-term sustainability, scalability, and maintainability while providing pragmatic recommendations that balance ideal architecture with practical constraints.
+Call StructuredOutput with exactly these fields:
+- **verdict**: "pass" (architecturally sound), "warn" (some concerns), or "fail" (critical architectural issues)
+- **summary**: 2-3 sentences explaining your architectural assessment (minimum 20 characters)
+- **issues**: Array of architectural concerns, each with: severity (high/medium/low), category (e.g., "coupling", "scalability", "tech-debt"), issue description, suggested_fix
+- **missing_sections**: Architectural considerations the plan should address but doesn't
+- **questions**: Design decisions that need clarification before implementation