aiwcli 0.9.0

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

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""Context monitor hook for proactive handoff warnings.
+
+This hook runs on PostToolUse for context-heavy tools and monitors
+context window usage. When context drops below a threshold, it injects
+a system reminder instructing Claude to wrap up and create a handoff document.
+
+Unlike UserPromptSubmit hooks, this fires DURING Claude's work,
+allowing proactive intervention without waiting for user input.
+
+Monitored tools (configured via settings.json matcher):
+- Task: Subagent responses can be huge
+- Read: File content loads into context
+- Bash: Command output can be large
+- WebFetch: Web content loads into context
+
+Hook input (from Claude Code):
+{
+    "hook_event_name": "PostToolUse",
+    "tool_name": "Task",
+    "tool_input": {...},
+    "tool_result": {...},
+    "transcript_path": "/path/to/transcript.jsonl",
+    "session_id": "abc123",
+    "context_window": {
+        "current_usage": {
+            "cache_read_input_tokens": 0,
+            "input_tokens": 12345,
+            "cache_creation_input_tokens": 0,
+            "output_tokens": 6789
+        },
+        "context_window_size": 200000
+    },
+    ...
+}
+
+Hook output:
+- Outputs JSON with additionalContext if context is low
+- This injects a system reminder into Claude's context
+- Plain stdout from PostToolUse only goes to verbose mode, not Claude
+- Using additionalContext ensures Claude sees and responds to the warning
+
+KNOWN LIMITATION: Context percentage won't match /context exactly.
+Hook JSON excludes system prompt, tools, MCP tokens. We add a baseline
+to compensate (~22.6k tokens typical). See:
+https://github.com/anthropics/claude-code/issues/13783
+"""
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+# 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 (
+    get_all_contexts,
+    get_context_by_session_id,
+    update_plan_status,
+)
+
+# Configuration
+LOW_CONTEXT_THRESHOLD = 40  # Warn when below 40% remaining
+CRITICAL_CONTEXT_THRESHOLD = 25  # Urgent warning below 25%
+
+# Context baseline: preloaded tokens not visible to hooks (~22.6k typical)
+# This includes system prompt, tools, MCP tokens that aren't in hook data
+CONTEXT_BASELINE = 22_600
+
+# Default context window size (used when not provided in hook input)
+DEFAULT_CONTEXT_WINDOW = 200_000
+
+
+def get_context_tokens_from_hook(hook_input: dict) -> Tuple[Optional[int], Optional[int]]:
+    """
+    Extract actual token counts from Claude Code hook input.
+
+    Claude Code provides context_window data with actual token counts:
+    - cache_read_input_tokens: Tokens read from cache
+    - input_tokens: New input tokens
+    - cache_creation_input_tokens: Tokens written to cache
+    - output_tokens: Model output tokens
+
+    Args:
+        hook_input: Hook input data from Claude Code
+
+    Returns:
+        Tuple of (tokens_used, max_tokens) or (None, None) if not available
+    """
+    context_window = hook_input.get("context_window")
+    if not context_window:
+        return None, None
+
+    current_usage = context_window.get("current_usage")
+    if not current_usage:
+        return None, None
+
+    # Sum all token types
+    cache_read = current_usage.get("cache_read_input_tokens", 0) or 0
+    input_tokens = current_usage.get("input_tokens", 0) or 0
+    cache_creation = current_usage.get("cache_creation_input_tokens", 0) or 0
+    output_tokens = current_usage.get("output_tokens", 0) or 0
+
+    content_tokens = cache_read + input_tokens + cache_creation + output_tokens
+
+    # Add baseline for system prompt, tools, MCP tokens not in hook data
+    tokens_used = content_tokens + CONTEXT_BASELINE
+
+    # Get max context window from hook input
+    max_tokens = context_window.get("context_window_size") or DEFAULT_CONTEXT_WINDOW
+
+    return tokens_used, max_tokens
+
+
+def get_current_context_id(project_root: Path = None) -> Optional[str]:
+    """
+    Determine the current active context.
+
+    Falls back to most recently active context.
+
+    Returns:
+        Context ID or None if no active context
+    """
+    contexts = get_all_contexts(status="active", project_root=project_root)
+    if contexts:
+        return contexts[0].id  # Sorted by last_active desc
+    return None
+
+
+def get_context_warning(
+    percent_remaining: int,
+    tokens_used: int,
+    max_tokens: int,
+    context_id: Optional[str],
+    tool_name: str
+) -> str:
+    """
+    Generate appropriate warning based on context level.
+
+    Args:
+        percent_remaining: Percentage of context remaining
+        tokens_used: Estimated tokens used
+        max_tokens: Maximum context window
+        context_id: Current context ID (if any)
+        tool_name: Tool that triggered this check
+
+    Returns:
+        System reminder markdown
+    """
+    # Format token counts
+    tokens_used_k = tokens_used // 1000
+    max_tokens_k = max_tokens // 1000
+
+    if percent_remaining <= CRITICAL_CONTEXT_THRESHOLD:
+        urgency = "CRITICAL"
+        instruction = "You MUST wrap up immediately and create a handoff document."
+    else:
+        urgency = "LOW"
+        instruction = "Please wrap up your current task and prepare for handoff."
+
+    context_info = ""
+    if context_id:
+        context_info = f"""
+To create a handoff document, use the /handoff command or describe:
+- What you were working on
+- What's completed
+- What still needs to be done
+- Any important decisions or context
+
+Context ID: `{context_id}`"""
+
+    return f"""<system-reminder>
+## {urgency} CONTEXT WARNING ({percent_remaining}% remaining)
+
+**Estimated usage**: ~{tokens_used_k}k / {max_tokens_k}k tokens
+**Triggered by**: {tool_name} tool completion
+
+{instruction}
+{context_info}
+
+**Actions:**
+1. Complete your current atomic task (if 1-2 steps away)
+2. Do NOT start new multi-step work
+3. Create a handoff document summarizing progress
+4. Ask user: "Context is getting low. I've summarized my progress. Should we continue in a new session?"
+</system-reminder>"""
+
+
+def check_and_transition_mode(hook_input: dict) -> None:
+    """
+    Check if context needs to transition from pending_implementation to implementing.
+
+    This handles the case where a plan was approved and implementation has started,
+    but the context mode wasn't updated. If we're seeing tool usage (Edit, Write, Bash)
+    and the context is in "pending_implementation", we transition to "implementing".
+
+    Args:
+        hook_input: Hook input data from Claude Code
+    """
+    # Only transition on tools that indicate implementation work
+    implementation_tools = {"Edit", "Write", "Bash", "NotebookEdit"}
+    tool_name = hook_input.get("tool_name", "")
+
+    if tool_name not in implementation_tools:
+        return
+
+    project_root = project_dir(hook_input)
+    session_id = hook_input.get("session_id")
+
+    if not session_id:
+        return
+
+    # Get context for this session
+    context = get_context_by_session_id(session_id, project_root)
+    if not context:
+        return
+
+    # Check if we need to transition
+    if context.in_flight and context.in_flight.mode == "pending_implementation":
+        eprint(f"[context_monitor] Transitioning {context.id} from pending_implementation to implementing")
+        update_plan_status(context.id, "implementing", project_root=project_root)
+
+
+def check_context_level(hook_input: dict) -> Optional[str]:
+    """
+    Check context level and return warning if low.
+
+    Optimized for fail-fast: checks cheap conditions first before any file I/O.
+
+    Args:
+        hook_input: Hook input data from Claude Code
+
+    Returns:
+        System reminder string if context is low, None otherwise
+    """
+    # === FAST PATH: No I/O, just dict lookups and math ===
+
+    # 1. Try to get context_window data (fast dict access)
+    tokens_used, max_tokens = get_context_tokens_from_hook(hook_input)
+
+    # 2. If no context_window data, exit immediately - can't monitor accurately
+    if tokens_used is None or max_tokens is None:
+        # Only log if we want to debug
+        # eprint("[context_monitor] context_window data unavailable")
+        return None
+
+    # 3. Calculate percentage (fast math)
+    remaining = max_tokens - tokens_used
+    percent_remaining = max(0, min(100, int((remaining / max_tokens) * 100)))
+
+    # 4. Most common case: context is fine, exit early
+    if percent_remaining > LOW_CONTEXT_THRESHOLD:
+        return None
+
+    # === SLOW PATH: Only reached when context is low (rare) ===
+
+    # Log since we're in warning territory
+    eprint(f"[context_monitor] Context: {percent_remaining}% remaining "
+           f"(~{tokens_used//1000}k/{max_tokens//1000}k tokens)")
+
+    # Check mode transition (file I/O)
+    check_and_transition_mode(hook_input)
+
+    # Get current context for handoff info (file I/O)
+    project_root = project_dir(hook_input)
+    context_id = get_current_context_id(project_root)
+
+    tool_name = hook_input.get("tool_name", "Unknown")
+
+    return get_context_warning(
+        percent_remaining,
+        tokens_used,
+        max_tokens,
+        context_id,
+        tool_name
+    )
+
+
+def main():
+    """
+    Main entry point for PostToolUse hook.
+
+    Reads hook input from stdin, estimates context usage,
+    and prints system reminder if context is low.
+    """
+    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
+
+        # Check context level
+        warning = check_context_level(hook_input)
+
+        if warning:
+            # Output JSON with additionalContext so Claude sees the warning
+            # Plain stdout from PostToolUse only goes to verbose mode, not Claude's context
+            output = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": warning
+                }
+            }
+            print(json.dumps(output))
+
+    except Exception as e:
+        eprint(f"[context_monitor] ERROR: {e}")
+        import traceback
+        eprint(traceback.format_exc())
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/_shared/hooks/file-suggestion.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""File suggestion hook for Claude Code.
+
+Suggests relevant files to include in context based on the current session:
+- Context file (context.json) for the active context
+- Plans from the active context's plans/ directory
+- Handoffs from the active context's handoffs/ directory
+- Reviews from the active context's reviews/ directory (including cc-native subdirectory)
+
+Hook input (from Claude Code):
+{
+    "session_id": "abc123",
+    "cwd": "/path/to/project",
+    ...
+}
+
+Hook output:
+JSON array of file paths to suggest, or empty array if no suggestions.
+["/path/to/file1.md", "/path/to/file2.md"]
+"""
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+# 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.base.constants import (
+    get_context_plans_dir,
+    get_context_handoffs_dir,
+    get_context_reviews_dir,
+    get_context_file_path,
+)
+from lib.context.context_manager import (
+    get_context_by_session_id,
+    get_all_in_flight_contexts,
+    get_context,
+)
+
+
+def get_context_files(context_id: str, project_root: Path) -> List[str]:
+    """
+    Get all relevant files for a context.
+
+    Collects:
+    - Context file (context.json)
+    - Plans (most recent first)
+    - Handoffs (most recent first)
+    - Reviews (most recent first)
+
+    Args:
+        context_id: Context identifier
+        project_root: Project root path
+
+    Returns:
+        List of absolute file paths, sorted by modification time (most recent first)
+    """
+    files = []
+
+    # Get context.json file first
+    context_file = get_context_file_path(context_id, project_root)
+    if context_file.exists():
+        files.append(str(context_file))
+        eprint(f"[file-suggestion] Found context file for {context_id}")
+
+    # Get plans directory
+    plans_dir = get_context_plans_dir(context_id, project_root)
+    if plans_dir.exists():
+        plan_files = list(plans_dir.glob("*.md"))
+        # Sort by modification time, most recent first
+        plan_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        files.extend([str(p) for p in plan_files])
+        eprint(f"[file-suggestion] Found {len(plan_files)} plans in {context_id}")
+
+    # Get handoffs directory
+    handoffs_dir = get_context_handoffs_dir(context_id, project_root)
+    if handoffs_dir.exists():
+        handoff_files = list(handoffs_dir.glob("*.md"))
+        handoff_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        files.extend([str(p) for p in handoff_files])
+        eprint(f"[file-suggestion] Found {len(handoff_files)} handoffs in {context_id}")
+
+    # Get reviews directory (includes cc-native subdirectory)
+    reviews_dir = get_context_reviews_dir(context_id, project_root)
+    if reviews_dir.exists():
+        # Find review.md files in reviews/ and subdirectories (e.g., reviews/cc-native/review.md)
+        review_files = list(reviews_dir.glob("**/review.md"))
+        review_files.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+        files.extend([str(p) for p in review_files])
+        eprint(f"[file-suggestion] Found {len(review_files)} reviews in {context_id}")
+
+    return files
+
+
+def get_active_context_id(session_id: str, project_root: Path) -> Optional[str]:
+    """
+    Determine the active context for suggestions.
+
+    Priority:
+    1. Context bound to current session_id
+    2. Single in-flight context (if only one exists)
+    3. None (no suggestions if ambiguous)
+
+    Args:
+        session_id: Current session identifier
+        project_root: Project root path
+
+    Returns:
+        Context ID or None
+    """
+    # Try session_id lookup first
+    if session_id and session_id != "unknown":
+        context = get_context_by_session_id(session_id, project_root)
+        if context:
+            eprint(f"[file-suggestion] Found context by session: {context.id}")
+            return context.id
+
+    # Fall back to single in-flight context
+    in_flight = get_all_in_flight_contexts(project_root)
+    if len(in_flight) == 1:
+        eprint(f"[file-suggestion] Using single in-flight context: {in_flight[0].id}")
+        return in_flight[0].id
+
+    eprint(f"[file-suggestion] No unique context found (in-flight: {len(in_flight)})")
+    return None
+
+
+def main():
+    """
+    Main entry point for file suggestion hook.
+
+    Reads hook input from stdin, determines active context,
+    and outputs file suggestions as JSON array.
+    """
+    try:
+        # Read hook input from stdin
+        input_data = sys.stdin.read().strip()
+
+        if not input_data:
+            print("[]")
+            return
+
+        try:
+            hook_input = json.loads(input_data)
+        except json.JSONDecodeError:
+            eprint("[file-suggestion] Failed to parse input JSON")
+            print("[]")
+            return
+
+        # Get project root and session ID
+        project_root = project_dir(hook_input)
+        session_id = hook_input.get("session_id", "unknown")
+
+        eprint(f"[file-suggestion] Session: {session_id[:8]}..., Project: {project_root}")
+
+        # Determine active context
+        context_id = get_active_context_id(session_id, project_root)
+
+        if not context_id:
+            print("[]")
+            return
+
+        # Collect file suggestions
+        suggestions = get_context_files(context_id, project_root)
+
+        # Limit suggestions to prevent overwhelming the context
+        MAX_SUGGESTIONS = 10
+        if len(suggestions) > MAX_SUGGESTIONS:
+            eprint(f"[file-suggestion] Limiting suggestions to {MAX_SUGGESTIONS} (was {len(suggestions)})")
+            suggestions = suggestions[:MAX_SUGGESTIONS]
+
+        # Output suggestions as JSON array
+        eprint(f"[file-suggestion] Suggesting {len(suggestions)} files")
+        print(json.dumps(suggestions))
+
+    except Exception as e:
+        eprint(f"[file-suggestion] ERROR: {e}")
+        import traceback
+        eprint(traceback.format_exc())
+        print("[]")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""PostToolUse hook - captures TaskCreate operations for persistence.
+
+This hook runs after Claude uses the TaskCreate tool and automatically
+records the task creation event in the context's events.jsonl.
+
+Hook input (from Claude Code):
+{
+    "hook_event_name": "PostToolUse",
+    "tool_name": "TaskCreate",
+    "tool_input": {
+        "subject": "Task subject",
+        "description": "Task description",
+        "activeForm": "Present continuous form",
+        "metadata": {"context": "context-id", ...}
+    },
+    "tool_response": {"task": {"id": "1", "subject": "..."}},
+    "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_created, generate_next_task_id
+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. metadata.persistent_id prefix (e.g., "ctx-123-task-1" -> "ctx-123")
+    4. Single active context
+    5. None (will trigger auto-creation)
+
+    Args:
+        tool_input: Tool input from TaskCreate
+        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_create_capture] Found context via session_id: {session_context.id}")
+                return session_context.id
+        except Exception as e:
+            eprint(f"[task_create_capture] Failed to lookup context by session: {e}")
+
+    # Check persistent_id for context hint
+    if isinstance(metadata, dict):
+        persistent_id = metadata.get("persistent_id", "")
+        if persistent_id and "-" in persistent_id:
+            # Format: "context-id-task-1" or similar
+            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]
+                return "-".join(context_parts)
+
+    # 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_create_capture] Failed to get active contexts: {e}")
+
+    return None
+
+
+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") != "TaskCreate":
+            return 0
+
+        # Extract tool input
+        tool_input = payload.get("tool_input", {})
+        if not isinstance(tool_input, dict):
+            eprint("[task_create_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_create_capture] Skipping persistence (hydration mode)")
+            return 0
+
+        # Extract tool response (contains task ID assigned by Claude)
+        tool_response = payload.get("tool_response", {})
+        if not isinstance(tool_response, dict):
+            eprint("[task_create_capture] Invalid tool_response: not a dict")
+            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_create_capture] No context available - skipping persistence")
+            eprint("[task_create_capture] Task will be ephemeral until context is created")
+            return 0
+
+        # Extract task data
+        subject = tool_input.get("subject", "")
+        if not subject:
+            eprint("[task_create_capture] Missing required field: subject")
+            return 0
+
+        description = tool_input.get("description", "")
+        active_form = tool_input.get("activeForm", "")
+
+        # Generate persistent task ID
+        # Claude's native ID is ephemeral (1, 2, 3...)
+        # We need a persistent ID that survives sessions
+        persistent_task_id = generate_next_task_id(context_id, project_root)
+
+        # Record the task creation event
+        success = record_task_created(
+            context_id=context_id,
+            task_id=persistent_task_id,
+            subject=subject,
+            description=description,
+            active_form=active_form,
+            project_root=project_root
+        )
+
+        if success:
+            eprint(f"[task_create_capture] Recorded task_added: {persistent_task_id} in {context_id}")
+        else:
+            eprint(f"[task_create_capture] Failed to record task_added: {persistent_task_id}")
+
+        # Silent success (no stdout output)
+        return 0
+
+    except json.JSONDecodeError as e:
+        eprint(f"[task_create_capture] JSON decode error: {e}")
+        return 0  # Non-blocking
+    except Exception as e:
+        eprint(f"[task_create_capture] Unexpected error: {e}")
+        import traceback
+        eprint(traceback.format_exc())
+        return 0  # Non-blocking
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())