aiwcli 0.9.0

package/dist/templates/_shared/hooks/task_update_capture.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""PostToolUse hook - captures TaskUpdate operations for persistence.
+
+This hook runs after Claude uses the TaskUpdate tool and automatically
+records the appropriate event in the context's events.jsonl based on the
+status change.
+
+Status mappings:
+- status: "in_progress" -> record_task_started()
+- status: "completed" -> record_task_completed()
+- blockedBy added -> record_task_blocked()
+
+Hook input (from Claude Code):
+{
+    "hook_event_name": "PostToolUse",
+    "tool_name": "TaskUpdate",
+    "tool_input": {
+        "taskId": "1",
+        "status": "completed",
+        "metadata": {"evidence": "...", "work_summary": "...", ...},
+        "addBlockedBy": ["2"],
+        ...
+    },
+    "tool_response": {...},
+    "session_id": "abc123",
+    "cwd": "/path/to/project"
+}
+
+Hook output:
+- Silent on success (no stdout output)
+- Logs to stderr for debugging
+"""
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+# Add parent directories to path for imports
+SCRIPT_DIR = Path(__file__).resolve().parent
+SHARED_LIB = SCRIPT_DIR.parent / "lib"
+sys.path.insert(0, str(SHARED_LIB.parent))
+
+from lib.context.task_sync import (
+    record_task_started,
+    record_task_completed,
+    record_task_blocked,
+)
+from lib.context.context_manager import get_all_contexts, get_context_by_session_id
+from lib.base.utils import eprint, project_dir
+
+
+def extract_context_id(
+    tool_input: Dict[str, Any],
+    project_root: Path,
+    session_id: Optional[str] = None
+) -> Optional[str]:
+    """
+    Extract context ID from tool input metadata, session, or active contexts.
+
+    Priority:
+    1. metadata.context field
+    2. Session ID lookup (session bound to context)
+    3. Single active context
+    4. None (skips persistence)
+
+    Args:
+        tool_input: Tool input from TaskUpdate
+        project_root: Project root directory
+        session_id: Session ID from hook payload
+
+    Returns:
+        Context ID or None if cannot determine
+    """
+    # Check metadata.context field
+    metadata = tool_input.get("metadata", {})
+    if isinstance(metadata, dict):
+        context = metadata.get("context")
+        if context:
+            return context
+
+    # 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"[task_update_capture] Found context via session_id: {session_context.id}")
+                return session_context.id
+        except Exception as e:
+            eprint(f"[task_update_capture] Failed to lookup context by session: {e}")
+
+    # Check for single active context
+    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"[task_update_capture] Failed to get active contexts: {e}")
+
+    return None
+
+
+def get_persistent_task_id(
+    claude_task_id: str,
+    tool_input: Dict[str, Any]
+) -> str:
+    """
+    Convert Claude's ephemeral task ID to persistent task ID.
+
+    If metadata.persistent_id exists, use that.
+    Otherwise, assume format "aiw-{claude_task_id}".
+
+    Args:
+        claude_task_id: Task ID from Claude (e.g., "1", "2")
+        tool_input: Tool input dict
+
+    Returns:
+        Persistent task ID (e.g., "aiw-1")
+    """
+    metadata = tool_input.get("metadata", {})
+    if isinstance(metadata, dict):
+        persistent_id = metadata.get("persistent_id")
+        if persistent_id:
+            return persistent_id
+
+    # Default: aiw-{id}
+    return f"aiw-{claude_task_id}"
+
+
+def main() -> int:
+    """
+    Main hook entry point.
+
+    Returns:
+        0 on success, non-zero on failure (but hook is non-blocking)
+    """
+    try:
+        # Parse hook input
+        payload = json.load(sys.stdin)
+
+        # Validate hook type
+        if payload.get("hook_event_name") != "PostToolUse":
+            return 0
+
+        # Validate tool name
+        if payload.get("tool_name") != "TaskUpdate":
+            return 0
+
+        # Extract tool input
+        tool_input = payload.get("tool_input", {})
+        if not isinstance(tool_input, dict):
+            eprint("[task_update_capture] Invalid tool_input: not a dict")
+            return 0
+
+        # Check for skip_persistence flag (used during hydration to avoid duplicates)
+        metadata = tool_input.get("metadata", {})
+        if isinstance(metadata, dict) and metadata.get("skip_persistence"):
+            eprint("[task_update_capture] Skipping persistence (hydration mode)")
+            return 0
+
+        # Get project root and session ID
+        project_root = project_dir(payload)
+        session_id = payload.get("session_id")
+
+        # Extract context ID
+        context_id = extract_context_id(tool_input, project_root, session_id)
+        if not context_id:
+            eprint("[task_update_capture] No context available - skipping persistence")
+            return 0
+
+        # Extract task ID
+        claude_task_id = tool_input.get("taskId")
+        if not claude_task_id:
+            eprint("[task_update_capture] Missing required field: taskId")
+            return 0
+
+        # Get persistent task ID
+        persistent_task_id = get_persistent_task_id(claude_task_id, tool_input)
+
+        # Check for status change
+        status = tool_input.get("status")
+        metadata = tool_input.get("metadata", {})
+        add_blocked_by = tool_input.get("addBlockedBy", [])
+
+        # Handle different update types
+        events_recorded = []
+
+        # Status: in_progress
+        if status == "in_progress":
+            success = record_task_started(
+                context_id=context_id,
+                task_id=persistent_task_id,
+                project_root=project_root
+            )
+            if success:
+                events_recorded.append("task_started")
+
+        # Status: completed
+        elif status == "completed":
+            # Extract rich completion context from metadata
+            if isinstance(metadata, dict):
+                evidence = metadata.get("evidence", "Task marked completed")
+                work_summary = metadata.get("work_summary", "")
+                files_changed = metadata.get("files_changed", [])
+                commit_ref = metadata.get("commit_ref", "")
+            else:
+                evidence = "Task marked completed"
+                work_summary = ""
+                files_changed = []
+                commit_ref = ""
+
+            success = record_task_completed(
+                context_id=context_id,
+                task_id=persistent_task_id,
+                evidence=evidence,
+                work_summary=work_summary,
+                files_changed=files_changed if isinstance(files_changed, list) else [],
+                commit_ref=commit_ref,
+                project_root=project_root
+            )
+            if success:
+                events_recorded.append("task_completed")
+
+        # Blocked by tasks
+        if add_blocked_by and isinstance(add_blocked_by, list) and len(add_blocked_by) > 0:
+            blocked_reason = f"Blocked by tasks: {', '.join(add_blocked_by)}"
+            success = record_task_blocked(
+                context_id=context_id,
+                task_id=persistent_task_id,
+                reason=blocked_reason,
+                project_root=project_root
+            )
+            if success:
+                events_recorded.append("task_blocked")
+
+        if events_recorded:
+            eprint(f"[task_update_capture] Recorded {', '.join(events_recorded)} for {persistent_task_id} in {context_id}")
+        else:
+            eprint(f"[task_update_capture] No relevant status changes detected for {persistent_task_id}")
+
+        # Silent success (no stdout output)
+        return 0
+
+    except json.JSONDecodeError as e:
+        eprint(f"[task_update_capture] JSON decode error: {e}")
+        return 0  # Non-blocking
+    except Exception as e:
+        eprint(f"[task_update_capture] Unexpected error: {e}")
+        import traceback
+        eprint(traceback.format_exc())
+        return 0  # Non-blocking
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/templates/_shared/hooks/user_prompt_submit.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Unified UserPromptSubmit hook entry point.
+
+This hook runs on every UserPromptSubmit and handles:
+- Context enforcement - ensures all work happens in a tracked context
+
+Note: Context monitoring (handoff warnings) is handled separately by
+context_monitor.py on PostToolUse events, which fires during Claude's
+work rather than waiting for user input.
+
+Hook input (from Claude Code):
+{
+    "hook_type": "UserPromptSubmit",
+    "prompt": "user's message text",
+    "session_id": "abc123",
+    ...
+}
+
+Hook output:
+- Prints system reminders to stdout for context enforcement
+"""
+import json
+import sys
+from pathlib import Path
+from typing import List
+
+# Add parent directories to path for imports
+SCRIPT_DIR = Path(__file__).resolve().parent
+SHARED_LIB = SCRIPT_DIR.parent / "lib"
+sys.path.insert(0, str(SHARED_LIB.parent))
+
+from lib.base.utils import eprint, project_dir
+from lib.context.context_manager import (
+    update_context_session_id,
+    update_plan_status,
+    clear_handoff_status,
+    get_context,
+    get_context_by_session_id,
+)
+from lib.context.task_sync import generate_hydration_instructions
+
+# Import the enforcement module
+from hooks.context_enforcer import determine_context, BlockRequest
+
+
+def _update_in_flight_status(context_id: str, hook_input: dict, project_root: Path) -> None:
+    """
+    Update context in-flight status based on permission mode.
+
+    - If handoff_pending: clear it (handoff has been consumed by this session)
+    - If permission_mode == "plan": set to "planning"
+    - If permission_mode in ["acceptEdits", "bypassPermissions"]: set to "implementing"
+    """
+    context = get_context(context_id, project_root)
+    if not context or not context.in_flight:
+        return
+
+    current_mode = context.in_flight.mode
+    permission_mode = hook_input.get("permission_mode", "default")
+    eprint(f"[user_prompt_submit] Current mode: {current_mode}, permission_mode: {permission_mode}")
+
+    # Clear handoff_pending if set (session resumption clears the handoff)
+    if current_mode == "handoff_pending":
+        clear_handoff_status(context_id, project_root)
+        eprint(f"[user_prompt_submit] Cleared handoff_pending status")
+        # Refresh context after clearing
+        context = get_context(context_id, project_root)
+        current_mode = context.in_flight.mode if context and context.in_flight else "none"
+
+    # Set status based on permission mode
+    if permission_mode == "plan":
+        if current_mode != "planning":
+            update_plan_status(context_id, "planning", project_root=project_root)
+            eprint(f"[user_prompt_submit] Set status to 'planning'")
+    elif permission_mode in ["acceptEdits", "bypassPermissions"]:
+        # Only transition to implementing if we have pending work
+        if current_mode in ["pending_implementation", "planning"]:
+            update_plan_status(context_id, "implementing", project_root=project_root)
+            eprint(f"[user_prompt_submit] Set status to 'implementing'")
+
+
+def main():
+    """
+    Main entry point for UserPromptSubmit hook.
+
+    Handles context enforcement for all user prompts.
+    Uses session_id to detect first prompt vs subsequent prompts.
+    """
+    try:
+        # Read hook input from stdin
+        input_data = sys.stdin.read().strip()
+
+        if not input_data:
+            return
+
+        try:
+            hook_input = json.loads(input_data)
+        except json.JSONDecodeError:
+            return
+
+        # Get user prompt and project root
+        user_prompt = hook_input.get("prompt", "")
+        project_root = project_dir(hook_input)
+        session_id = hook_input.get("session_id", "unknown")
+
+        outputs: List[str] = []
+
+        # First-prompt detection: check if session_id is already bound to a context
+        existing_context = get_context_by_session_id(session_id, project_root)
+
+        if existing_context:
+            # NOT first prompt - session already bound to context
+            # Skip expensive context detection and task hydration
+            eprint(f"[user_prompt_submit] Session {session_id[:8]}... already bound to {existing_context.id}")
+            # Still update in-flight status based on permission mode
+            _update_in_flight_status(existing_context.id, hook_input, project_root)
+        elif user_prompt:
+            # FIRST prompt - need context detection and potentially task hydration
+            try:
+                context_id, method, context_output = determine_context(user_prompt, project_root, session_id)
+                eprint(f"[user_prompt_submit] Context: {method} -> {context_id}")
+
+                if context_id:
+                    # Bind session to context
+                    update_context_session_id(context_id, session_id, project_root)
+                    eprint(f"[user_prompt_submit] Bound session {session_id[:8]}... to context '{context_id}'")
+
+                    # Update in-flight status based on permission mode
+                    _update_in_flight_status(context_id, hook_input, project_root)
+
+                    # Task hydration - restore pending tasks from events.jsonl
+                    hydration_instructions = generate_hydration_instructions(context_id, project_root)
+                    if hydration_instructions and "No pending tasks" not in hydration_instructions:
+                        outputs.append(hydration_instructions)
+                        eprint(f"[user_prompt_submit] Generated task hydration instructions")
+
+                if context_output:
+                    outputs.append(context_output)
+
+            except BlockRequest as e:
+                # Block the request - print to stderr and exit with code 2
+                # This shows the context picker to the user
+                print(e.message, file=sys.stderr)
+                sys.exit(2)
+
+        # Print output
+        if outputs:
+            print("\n\n".join(outputs))
+
+    except Exception as e:
+        eprint(f"[user_prompt_submit] ERROR: {e}")
+        import traceback
+        eprint(traceback.format_exc())
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1 @@
+"""Shared library for AIW CLI templates."""

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

@@ -0,0 +1,49 @@
+"""Base utilities for shared context management."""
+from .atomic_write import atomic_write, atomic_append
+from .constants import (
+    OUTPUT_DIR,
+    CONTEXTS_DIR,
+    INDEX_FILENAME,
+    validate_context_id,
+    get_output_dir,
+    get_contexts_dir,
+    get_context_dir,
+    get_context_plans_dir,
+    get_context_handoffs_dir,
+    get_index_path,
+    get_context_file_path,
+    get_events_file_path,
+)
+from .utils import (
+    eprint,
+    now_local,
+    now_iso,
+    project_dir,
+    sanitize_filename,
+    sanitize_title,
+    generate_context_id,
+)
+
+__all__ = [
+    "atomic_write",
+    "atomic_append",
+    "OUTPUT_DIR",
+    "CONTEXTS_DIR",
+    "INDEX_FILENAME",
+    "validate_context_id",
+    "get_output_dir",
+    "get_contexts_dir",
+    "get_context_dir",
+    "get_context_plans_dir",
+    "get_context_handoffs_dir",
+    "get_index_path",
+    "get_context_file_path",
+    "get_events_file_path",
+    "eprint",
+    "now_local",
+    "now_iso",
+    "project_dir",
+    "sanitize_filename",
+    "sanitize_title",
+    "generate_context_id",
+]

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

@@ -0,0 +1,180 @@
+"""Cross-platform atomic file writes with security.
+
+Provides crash-safe file writes by writing to a temp file first,
+then atomically replacing the target. This prevents corrupted files
+if the process crashes mid-write.
+
+Note: This is for crash-safety, NOT for concurrent access.
+The shared context system assumes single-session-per-context.
+"""
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+from typing import Optional, Tuple
+
+if sys.platform == 'win32':
+    import ctypes
+    from ctypes import wintypes
+
+    # Windows MoveFileEx flags
+    MOVEFILE_REPLACE_EXISTING = 0x1
+    MOVEFILE_WRITE_THROUGH = 0x8
+
+    def _atomic_replace_windows(src: Path, dst: Path) -> None:
+        """Atomic file replacement on Windows using MoveFileEx."""
+        kernel32 = ctypes.windll.kernel32
+
+        # Set proper function prototypes for 64-bit safety
+        kernel32.MoveFileExW.argtypes = [wintypes.LPCWSTR, wintypes.LPCWSTR, wintypes.DWORD]
+        kernel32.MoveFileExW.restype = wintypes.BOOL
+
+        result = kernel32.MoveFileExW(
+            str(src),
+            str(dst),
+            MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH
+        )
+        if not result:
+            error_code = kernel32.GetLastError()
+            raise ctypes.WinError(error_code)
+
+
+def atomic_write(
+    path: Path,
+    content: str,
+    max_attempts: int = 2,
+    backoff_ms: Optional[list] = None
+) -> Tuple[bool, Optional[str]]:
+    """
+    Write file atomically with retry logic.
+
+    Creates a temp file in the same directory, writes content,
+    then atomically replaces the target file. This ensures the
+    file is never left in a corrupted state.
+
+    Args:
+        path: Target file path
+        content: Content to write
+        max_attempts: Maximum retry attempts (default: 2)
+        backoff_ms: Retry backoff in milliseconds (default: [500, 1000])
+
+    Returns:
+        Tuple of (success: bool, error_message: Optional[str])
+    """
+    if backoff_ms is None:
+        backoff_ms = [500, 1000]
+
+    # Ensure parent directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    for attempt in range(max_attempts):
+        try:
+            # Create temp file in same directory for atomic rename
+            temp_fd, temp_path_str = tempfile.mkstemp(
+                dir=path.parent,
+                prefix=f".{path.stem}_",
+                suffix=".tmp"
+            )
+            temp_path = Path(temp_path_str)
+
+            try:
+                # Write content to temp file
+                with os.fdopen(temp_fd, 'w', encoding='utf-8') as f:
+                    f.write(content)
+                    f.flush()
+                    os.fsync(f.fileno())  # Force write to disk
+
+                # Set restrictive permissions before rename (chmod 600)
+                try:
+                    os.chmod(temp_path, 0o600)
+                except OSError:
+                    pass  # chmod may fail on some filesystems
+
+                # Platform-specific atomic rename
+                if sys.platform == 'win32':
+                    _atomic_replace_windows(temp_path, path)
+                else:
+                    temp_path.replace(path)  # POSIX atomic
+
+                return (True, None)
+
+            except Exception:
+                # Clean up temp file on failure
+                try:
+                    temp_path.unlink()
+                except Exception:
+                    pass  # Cleanup is best-effort
+                raise
+
+        except Exception as e:
+            if attempt < max_attempts - 1:
+                # Bounds-safe backoff indexing
+                wait_ms = backoff_ms[min(attempt, len(backoff_ms) - 1)]
+                time.sleep(wait_ms / 1000.0)
+            else:
+                # Sanitize error message (no paths, no stack trace)
+                error_type = type(e).__name__
+                error_msg = str(e).split('\n')[0][:200]  # First line only, max 200 chars
+                return (False, f"{error_type}: {error_msg}")
+
+    return (False, "Max retry attempts exceeded")
+
+
+def atomic_append(
+    path: Path,
+    content: str,
+    max_attempts: int = 2,
+    backoff_ms: Optional[list] = None
+) -> Tuple[bool, Optional[str]]:
+    """
+    Append to file atomically with retry logic.
+
+    For JSONL files, this is safe because each line is independent.
+    If process crashes mid-append, only the last partial line is lost,
+    which read_events() handles gracefully.
+
+    Args:
+        path: Target file path
+        content: Content to append (should include newline if needed)
+        max_attempts: Maximum retry attempts (default: 2)
+        backoff_ms: Retry backoff in milliseconds (default: [500, 1000])
+
+    Returns:
+        Tuple of (success: bool, error_message: Optional[str])
+    """
+    if backoff_ms is None:
+        backoff_ms = [500, 1000]
+
+    # Ensure parent directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Check if file is being created (for permission setting)
+    is_new_file = not path.exists()
+
+    for attempt in range(max_attempts):
+        try:
+            with open(path, 'a', encoding='utf-8') as f:
+                f.write(content)
+                f.flush()
+                os.fsync(f.fileno())  # Force write to disk
+
+            # Set restrictive permissions on newly created files (chmod 600)
+            if is_new_file:
+                try:
+                    os.chmod(path, 0o600)
+                except OSError:
+                    pass  # chmod may fail on some filesystems
+
+            return (True, None)
+
+        except Exception as e:
+            if attempt < max_attempts - 1:
+                wait_ms = backoff_ms[min(attempt, len(backoff_ms) - 1)]
+                time.sleep(wait_ms / 1000.0)
+            else:
+                error_type = type(e).__name__
+                error_msg = str(e).split('\n')[0][:200]
+                return (False, f"{error_type}: {error_msg}")
+
+    return (False, "Max retry attempts exceeded")