aiwcli 0.10.3 → 0.11.0

package/dist/templates/cc-native/_cc-native/hooks/plan_questions_early.py

@@ -1,81 +0,0 @@
-#!/usr/bin/env python3
-"""UserPromptSubmit hook - injects Phase A clarification prompt in plan mode.
-
-On the first prompt in plan mode (before any code exploration), injects
-a system-reminder telling Claude to ask clarification questions via
-AskUserQuestion before exploring the codebase.
-
-Skips if questions were already asked this session.
-"""
-import json
-import sys
-from pathlib import Path
-
-_hook_dir = Path(__file__).resolve().parent
-_cc_native_lib_dir = _hook_dir.parent / "lib"
-_shared_lib_dir = _hook_dir.parent.parent / "_shared" / "lib"
-sys.path.insert(0, str(_cc_native_lib_dir))
-sys.path.insert(0, str(_shared_lib_dir))
-
-from utils import was_questions_asked
-from base.hook_utils import load_hook_input
-from base.logger import log_debug, log_info, log_warn, log_error
-
-
-PHASE_A_PROMPT = """
-## Plan Mode: Clarify Before Exploring
-
-Use AskUserQuestion now — one call, 3-4 questions — before reading any code.
-
-### Why This Matters
-Once you explore the codebase, you anchor on what you find. Questions asked after exploration confirm your assumptions instead of challenging them. Ask now, while your interpretation is still flexible.
-
-### What to Ask About
-Only ask about things you cannot discover from code — the user's intent, constraints, history, and priorities:
-
-- **Ambiguity:** If you can read this request two different ways, ask which interpretation is correct. Provide your top 2-3 readings as options.
-- **Invisible context:** What does the user assume "everyone knows" about this system that isn't documented? What's obvious to them but hidden to you?
-- **Success criteria:** What does "done well" look like beyond the literal request? What would make them rate this a 10?
-- **Constraints and history:** Has this been attempted before? Are there parts of the system that are off-limits or sensitive?
-
-### How to Select Questions
-1. Generate 5+ candidate questions across the lenses above
-2. For each, evaluate: "If they answered A vs B, would I explore different files or take a different approach?" If no — discard it.
-3. Keep the 3-4 where different answers lead to meaningfully different exploration strategies
-4. Frame each with 2-3 concrete options so the user can react rather than generate from scratch
-""".strip()
-
-
-def main() -> int:
-    try:
-        payload = load_hook_input()
-        if not payload:
-            return 0
-
-        permission_mode = payload.get("permission_mode", "")
-        if permission_mode != "plan":
-            return 0
-
-        session_id = str(payload.get("session_id", ""))
-        if not session_id:
-            log_debug("plan_questions_early", "No session_id, skipping")
-            return 0
-
-        if was_questions_asked(session_id):
-            log_debug("plan_questions_early", "Questions already asked, skipping")
-            return 0
-
-        log_info("plan_questions_early", "Plan mode detected, injecting Phase A prompt")
-        print(f"<system-reminder>{PHASE_A_PROMPT}</system-reminder>")
-
-    except Exception as e:
-        from base.hook_utils import log_hook_error
-        log_hook_error("plan_questions_early", e, "UserPromptSubmit")
-        log_error("plan_questions_early", str(e))
-
-    return 0
-
-
-if __name__ == "__main__":
-    from base.hook_utils import run_hook
-    run_hook(main, "plan_questions_early")

package/dist/templates/cc-native/_cc-native/hooks/suggest-fresh-perspective.py

@@ -1,340 +0,0 @@
-#!/usr/bin/env python3
-"""
-PostToolUse hook - suggests /fresh-perspective when user appears stuck.
-
-Detection patterns:
-1. Same error appearing 3+ times
-2. Repeated edits to same file without resolution
-3. Test failures after multiple fix attempts
-
-Behavior: Suggests (doesn't force) running /fresh-perspective.
-Non-blocking - always returns success.
-
-Configuration (in _cc-native/plan-review.config.json):
-  "stuckDetection": {
-    "enabled": true,           // Set to false to disable entirely
-    "errorThreshold": 3,       // Errors before suggesting
-    "fileEditThreshold": 4,    // Edits to same file before suggesting
-    "testFailureThreshold": 3, // Test failures before suggesting
-    "cooldown": 10,            // Tool calls between suggestions
-    "maxSuggestions": 3        // Max suggestions per session
-  }
-"""
-
-import json
-import os
-import re
-import sys
-import tempfile
-from pathlib import Path
-from typing import Any, Dict
-
-# Add lib directories to path for imports
-_hook_dir = Path(__file__).resolve().parent
-_lib_dir = _hook_dir.parent / "lib"
-_shared_lib = _hook_dir.parent.parent / "_shared" / "lib"
-sys.path.insert(0, str(_lib_dir))
-sys.path.insert(0, str(_shared_lib))
-
-from base.hook_utils import emit_context
-from base.logger import log_debug, log_info, log_warn, log_error
-from utils import sanitize_filename
-
-
-# ---------------------------
-# Configuration (defaults, overridden by config.json)
-# ---------------------------
-
-DEFAULT_CONFIG = {
-    "enabled": True,
-    "errorThreshold": 3,
-    "fileEditThreshold": 4,
-    "testFailureThreshold": 3,
-    "cooldown": 10,
-    "maxSuggestions": 3,
-}
-
-
-def _int_or_default(value: Any, default: int) -> int:
-    """Coerce value to int, return default if not possible.
-
-    Handles string numbers, floats, and invalid types gracefully.
-    """
-    if isinstance(value, int):
-        return value
-    if isinstance(value, float):
-        return int(value)
-    if isinstance(value, str):
-        try:
-            return int(value)
-        except ValueError:
-            return default
-    return default
-
-
-def load_config(project_dir: Path) -> Dict[str, Any]:
-    """Load stuckDetection config from _cc-native/plan-review.config.json."""
-    config_path = project_dir / "_cc-native" / "plan-review.config.json"
-    if not config_path.exists():
-        return DEFAULT_CONFIG.copy()
-    try:
-        full_config = json.loads(config_path.read_text(encoding="utf-8"))
-        section = full_config.get("stuckDetection", {})
-        return {**DEFAULT_CONFIG, **section}
-    except Exception as e:
-        log_warn("suggest-fresh-perspective", f"Failed to load config: {e}")
-        return DEFAULT_CONFIG.copy()
-
-
-def get_project_dir(payload: Dict[str, Any]) -> Path:
-    """Get project directory from payload or environment."""
-    p = os.environ.get("CLAUDE_PROJECT_DIR") or payload.get("cwd") or os.getcwd()
-    return Path(p)
-
-
-# ---------------------------
-# Compiled patterns (performance optimization)
-# ---------------------------
-
-# Single combined pattern for error detection (case-insensitive)
-_ERROR_PATTERN = re.compile(
-    r'(error:|failed|exception)',
-    re.IGNORECASE
-)
-
-# Combined pattern for test failures
-_TEST_FAILURE_PATTERN = re.compile(
-    r'(\d+\s+failed|FAIL\s|✗|AssertionError|test.*failed|npm\s+ERR!.*test)',
-    re.IGNORECASE
-)
-
-# Pattern for normalizing error messages (line numbers)
-_LINE_NUMBER_PATTERN = re.compile(r':\d+')
-_MULTI_DIGIT_PATTERN = re.compile(r'\d{2,}')
-_PATH_PATTERN = re.compile(r'[/\\][^\s/\\]+[/\\]')
-
-
-# ---------------------------
-# State management (session-scoped)
-# ---------------------------
-
-def get_state_path(session_id: str) -> Path:
-    """Get path to stuck-detection state file for this session."""
-    safe_id = sanitize_filename(str(session_id), max_len=32)
-    return Path(tempfile.gettempdir()) / f"cc-native-stuck-state-{safe_id}.json"
-
-
-def load_state(session_id: str) -> Dict[str, Any]:
-    """Load stuck detection state for this session."""
-    state_path = get_state_path(session_id)
-    default_state = {
-        "error_hashes": {},  # hash -> count
-        "file_edits": {},     # file_path -> count
-        "test_failures": 0,
-        "tool_calls_since_suggestion": 0,
-        "suggestion_count": 0,
-    }
-    if not state_path.exists():
-        return default_state
-    try:
-        return json.loads(state_path.read_text(encoding="utf-8"))
-    except Exception:
-        return default_state
-
-
-def save_state(session_id: str, state: Dict[str, Any]) -> None:
-    """Save stuck detection state for this session."""
-    state_path = get_state_path(session_id)
-    try:
-        state_path.write_text(json.dumps(state), encoding="utf-8")
-    except Exception as e:
-        log_warn("suggest-fresh-perspective", f"Failed to save state: {e}")
-
-
-# ---------------------------
-# Detection logic
-# ---------------------------
-
-def hash_error(error_text: str) -> str:
-    """Create a simple hash of an error message for deduplication.
-
-    Normalizes by removing line numbers and multi-digit numbers,
-    but preserves enough context to distinguish different errors.
-    """
-    # Normalize: remove line numbers, preserve error type
-    normalized = _LINE_NUMBER_PATTERN.sub(':N', error_text)
-    normalized = _MULTI_DIGIT_PATTERN.sub('N', normalized)
-    # Simplify paths but keep some structure
-    normalized = _PATH_PATTERN.sub('.../', normalized)
-    # Take first 100 chars after normalization
-    return normalized[:100]
-
-
-def detect_repeated_error(state: Dict[str, Any], tool_result: str, threshold: int) -> bool:
-    """Check if we're seeing the same error repeatedly.
-
-    Returns True if threshold reached, always updates state.
-    """
-    if not tool_result:
-        return False
-
-    if _ERROR_PATTERN.search(tool_result):
-        error_hash = hash_error(tool_result)
-        state["error_hashes"][error_hash] = state["error_hashes"].get(error_hash, 0) + 1
-        return state["error_hashes"][error_hash] >= threshold
-
-    return False
-
-
-def detect_repeated_file_edits(state: Dict[str, Any], tool_name: str, tool_input: Dict[str, Any], threshold: int) -> bool:
-    """Check if we're editing the same file repeatedly.
-
-    Returns True if threshold reached, always updates state.
-    """
-    if tool_name != "Edit":
-        return False
-
-    # Validate tool_input is a dict
-    if not isinstance(tool_input, dict):
-        return False
-
-    file_path = tool_input.get("file_path", "")
-    if not file_path:
-        return False
-
-    state["file_edits"][file_path] = state["file_edits"].get(file_path, 0) + 1
-    return state["file_edits"][file_path] >= threshold
-
-
-def detect_test_failures(state: Dict[str, Any], tool_name: str, tool_result: str, threshold: int) -> bool:
-    """Check for repeated test failures.
-
-    Returns True if threshold reached, always updates state.
-    """
-    if tool_name != "Bash":
-        return False
-
-    if _TEST_FAILURE_PATTERN.search(tool_result):
-        state["test_failures"] = state.get("test_failures", 0) + 1
-        return state["test_failures"] >= threshold
-
-    return False
-
-
-# ---------------------------
-# Main hook logic
-# ---------------------------
-
-def should_suggest(state: Dict[str, Any], cooldown: int) -> bool:
-    """Check if we're past the cooldown period."""
-    return state.get("tool_calls_since_suggestion", 0) >= cooldown
-
-
-def create_suggestion() -> None:
-    """Emit the suggestion via hook utility."""
-    emit_context(
-        "\n---\n"
-        "**Stuck?** You've been working on similar issues for a while. "
-        "Consider running `/fresh-perspective` to get an unbiased view of the problem "
-        "without code context anchoring your thinking.\n"
-        "---\n"
-    )
-
-
-def main() -> int:
-    # === FAST PATH: Cheap checks first, no I/O ===
-
-    try:
-        payload = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return 0  # Fail-safe
-
-    # 1. Check hook_event_name (cheap dict lookup)
-    if payload.get("hook_event_name") != "PostToolUse":
-        return 0
-
-    # 2. Check session_id exists (cheap dict lookup)
-    session_id = payload.get("session_id")
-    if not session_id:
-        return 0
-
-    # 3. Check tool_name is relevant (cheap dict lookup)
-    # We only care about Edit and Bash - skip everything else
-    tool_name = payload.get("tool_name", "")
-    if tool_name not in ("Edit", "Bash"):
-        return 0
-
-    # === SLOW PATH: Only reached for Edit/Bash tools ===
-
-    # Load configuration (file I/O)
-    project_dir = get_project_dir(payload)
-    config = load_config(project_dir)
-
-    # Check if feature is disabled
-    if not config.get("enabled", True):
-        return 0
-
-    tool_input = payload.get("tool_input", {})
-    tool_result = payload.get("tool_result", {})
-
-    # Validate tool_input type
-    if not isinstance(tool_input, dict):
-        tool_input = {}
-
-    # Extract result text
-    result_text = ""
-    if isinstance(tool_result, dict):
-        result_text = str(tool_result.get("output", "") or tool_result.get("content", ""))
-    elif isinstance(tool_result, str):
-        result_text = tool_result
-
-    # Load state (file I/O)
-    state = load_state(session_id)
-
-    # Increment tool call counter
-    state["tool_calls_since_suggestion"] = state.get("tool_calls_since_suggestion", 0) + 1
-
-    # Get thresholds from config (with type coercion for safety)
-    error_threshold = _int_or_default(config.get("errorThreshold"), 3)
-    file_edit_threshold = _int_or_default(config.get("fileEditThreshold"), 4)
-    test_failure_threshold = _int_or_default(config.get("testFailureThreshold"), 3)
-    cooldown = _int_or_default(config.get("cooldown"), 10)
-    max_suggestions = _int_or_default(config.get("maxSuggestions"), 3)
-
-    # Run ALL detections (don't short-circuit - each updates state)
-    error_detected = detect_repeated_error(state, result_text, error_threshold)
-    file_edit_detected = detect_repeated_file_edits(state, tool_name, tool_input, file_edit_threshold)
-    test_failure_detected = detect_test_failures(state, tool_name, result_text, test_failure_threshold)
-
-    # Save state AFTER all detections have run
-    save_state(session_id, state)
-
-    # Check if any detection triggered
-    is_stuck = error_detected or file_edit_detected or test_failure_detected
-
-    if is_stuck:
-        if error_detected:
-            log_info("suggest-fresh-perspective", "Detected repeated error pattern")
-        if file_edit_detected:
-            log_info("suggest-fresh-perspective", "Detected repeated file edits")
-        if test_failure_detected:
-            log_info("suggest-fresh-perspective", "Detected repeated test failures")
-
-    # Only suggest if stuck AND past cooldown
-    if is_stuck and should_suggest(state, cooldown):
-        # Reset cooldown
-        state["tool_calls_since_suggestion"] = 0
-        state["suggestion_count"] = state.get("suggestion_count", 0) + 1
-        save_state(session_id, state)
-
-        # Only suggest up to maxSuggestions times per session
-        if state["suggestion_count"] <= max_suggestions:
-            log_info("suggest-fresh-perspective", f"Suggesting fresh perspective (suggestion #{state['suggestion_count']})")
-            create_suggestion()
-
-    return 0
-
-
-if __name__ == "__main__":
-    from base.hook_utils import run_hook
-    run_hook(main, "suggest_fresh_perspective")

package/dist/templates/cc-native/_cc-native/lib/CLAUDE.md

@@ -1,265 +0,0 @@
-# CC-Native Library Development Guide
-
-> **Keep this document updated.** When you solve an issue related to library code, add the solution to the relevant section and log it in the Changelog. This document should grow with discovered patterns and fixes—don't wait to be asked.
-
----
-
-## Module Overview
-
-| Module | Purpose |
-|--------|---------|
-| `utils.py` | Core utilities: eprint, sanitize, JSON parsing, artifact writing |
-| `state.py` | Plan state file management and iteration tracking |
-| `orchestrator.py` | Plan complexity analysis and agent selection |
-| `reviewers/` | Plan review implementations (package — see below) |
-| `constants.py` | Shared constants and feature flags (e.g., `ENABLE_ROBUST_PLAN_WRITES`) |
-| `debug.py` | Permanent debug logging to context folder (`CCNATIVE_DEBUG_DISABLE=1` to disable) |
-| `__init__.py` | Package exports |
-
-### reviewers/ Package
-
-| File | Purpose |
-|------|---------|
-| `__init__.py` | Re-exports: `ReviewerResult`, `run_codex_review`, `run_gemini_review`, `run_agent_review` |
-| `base.py` | `ReviewerResult`, `REVIEW_SCHEMA`, `AgentConfig`, `OrchestratorConfig` |
-| `agent.py` | Claude Code agent-based reviewer (uses `--system-prompt`) |
-| `codex.py` | Codex CLI reviewer |
-| `gemini.py` | Google Gemini API reviewer |
-
----
-
-## Dependency Graph
-
-```
-Hooks (cc-native-plan-review.py, etc.)
-    │
-    ├── lib/utils.py (core utilities)
-    │       └── lib/constants.py
-    │       └── _shared/lib/base/atomic_write.py
-    │
-    ├── lib/state.py (state management)
-    │       └── lib/utils.py (eprint)
-    │
-    ├── lib/orchestrator.py (agent selection)
-    │       └── lib/utils.py (ReviewerResult, etc.)
-    │
-    ├── lib/reviewers/ (plan review package)
-    │       ├── base.py (ReviewerResult, AgentConfig, schemas)
-    │       ├── agent.py → base.py
-    │       ├── codex.py → base.py
-    │       └── gemini.py → base.py
-    │
-    ├── lib/debug.py (context-folder debug logging)
-    │
-    └── _shared/lib/ (shared across all methods)
-            ├── lib/base/subprocess_utils.py
-            ├── lib/base/constants.py
-            └── lib/context/context_manager.py
-```
-
-**Import direction:** Hooks → cc-native lib → shared lib. Never the reverse.
-
----
-
-## Key Data Classes
-
-### ReviewerResult
-
-```python
-@dataclass
-class ReviewerResult:
-    name: str           # Reviewer name (e.g., "codex", "architect-reviewer")
-    ok: bool            # True if review completed successfully
-    verdict: str        # "pass" | "warn" | "fail" | "error" | "skip"
-    data: Dict[str, Any]  # Structured review data (summary, issues, etc.)
-    raw: str            # Raw response text
-    err: str            # Error message if any
-```
-
-### OrchestratorResult
-
-```python
-@dataclass
-class OrchestratorResult:
-    complexity: str         # "simple" | "medium" | "high"
-    category: str           # "code" | "infrastructure" | "documentation" | etc.
-    selected_agents: List[str]  # Agent names to run
-    reasoning: str          # Why these agents were selected
-    skip_reason: Optional[str]  # Why review was skipped (if applicable)
-    error: Optional[str]    # Error message if orchestrator failed
-```
-
-### CombinedReviewResult
-
-```python
-@dataclass
-class CombinedReviewResult:
-    plan_hash: str                          # SHA256 hash (first 16 chars)
-    overall_verdict: str                    # Worst verdict across all reviewers
-    cli_reviewers: Dict[str, ReviewerResult]  # Codex, Gemini results
-    orchestration: Optional[OrchestratorResult]
-    agents: Dict[str, ReviewerResult]       # Agent review results
-    timestamp: str                          # ISO format
-```
-
----
-
-## Windows Path Handling
-
-Windows uses backslashes in paths. Always normalize when comparing:
-
-```python
-# CORRECT - works on Windows and Unix
-if ".claude/plans/" in file_path.replace("\\", "/"):
-    # Found a plan file
-
-# Also correct - use Path for comparisons
-from pathlib import Path
-if Path(".claude/plans") in Path(file_path).parents:
-    # Found a plan file
-```
-
-```python
-# WRONG - fails on Windows
-if ".claude/plans/" in file_path:  # Windows path: ".claude\\plans\\"
-    # Never matches on Windows!
-```
-
-This is a recurring issue. Any path string comparison must handle both separators.
-
----
-
-## Atomic Writes
-
-For critical files (state, reviews), use atomic writes to prevent corruption on crash:
-
-```python
-# Import from shared lib (canonical location)
-from _shared.lib.base.atomic_write import atomic_write
-
-# CORRECT - atomic write
-success, error = atomic_write(path, content)
-if not success:
-    eprint(f"[module] Write failed: {error}")
-```
-
-```python
-# RISKY - can leave partial file on crash
-path.write_text(content, encoding="utf-8")
-```
-
-Atomic writes use a temp file + rename pattern. The `constants.ENABLE_ROBUST_PLAN_WRITES` feature flag (env: `CC_NATIVE_ROBUST_WRITES`, default: `true`) controls whether atomic writes are used for plan state files.
-
----
-
-## Adding New Reviewers
-
-1. **Create reviewer file** in `reviewers/` package (e.g., `reviewers/myreviewer.py`):
-   ```python
-   from .base import ReviewerResult, REVIEW_SCHEMA
-
-   def run_myreviewer_review(
-       plan: str,
-       schema: Dict[str, Any],
-       settings: Dict[str, Any],
-   ) -> ReviewerResult:
-       # Implementation
-       return ReviewerResult(
-           name="myreviewer",
-           ok=True,
-           verdict="pass",
-           data=parsed_data,
-           raw=raw_response,
-           err="",
-       )
-   ```
-
-2. **Export in `reviewers/__init__.py`**:
-   ```python
-   from .myreviewer import run_myreviewer_review
-   ```
-
-3. **Add config** in `plan-review.config.json`:
-   ```json
-   {
-     "planReview": {
-       "reviewers": {
-         "myreviewer": {"enabled": true, "timeout": 120}
-       }
-     }
-   }
-   ```
-
-4. **Wire in hook** (`cc-native-plan-review.py`):
-   ```python
-   from reviewers import run_myreviewer_review
-
-   if myreviewer_enabled:
-       phase1_tasks.append(("myreviewer", lambda: run_myreviewer_review(...)))
-   ```
-
----
-
-## JSON Parsing
-
-Use `parse_json_maybe` for LLM responses - it handles markdown code blocks and extraction:
-
-```python
-from utils import parse_json_maybe, coerce_to_review
-
-# Parse with field validation
-obj = parse_json_maybe(raw_response, require_fields=["verdict", "summary"])
-
-# Normalize to expected structure
-ok, verdict, data = coerce_to_review(obj)
-```
-
-The parser tries:
-1. Strict JSON parse
-2. Extract `{...}` block from text (handles ```json blocks)
-
----
-
-## Encoding
-
-Always specify encoding on file operations:
-
-```python
-# CORRECT
-content = path.read_text(encoding="utf-8")
-path.write_text(content, encoding="utf-8")
-
-with open(path, "r", encoding="utf-8") as f:
-    data = json.load(f)
-```
-
-```python
-# WRONG - uses system default (can fail on Windows)
-content = path.read_text()  # May use cp1252 on Windows
-```
-
----
-
-## DO NOT
-
-These are reminders based on past issues. Not enforcement rules.
-
-- **Don't import from `_cc-native/lib/` in `_shared/lib/`** - wrong direction, creates circular deps
-- **Don't use `print()` for debugging** - use `log_debug/log_info/log_warn/log_error` from `_shared/lib/base/logger.py` (writes to stderr + `_output/hook-log.jsonl`)
-- **Don't modify data class fields** without updating all consumers (hooks, formatters, tests)
-- **Don't hardcode paths** - use `Path(__file__)`, env vars, or config
-- **Don't forget `encoding="utf-8"`** on file operations - Windows defaults are unsafe
-- **Don't assume forward slashes** in file paths - Windows uses backslashes
-- **Don't skip atomic writes** for critical state files - use `atomic_write` function
-
----
-
-## Changelog
-
-<!-- Add dated entries as new issues are discovered -->
-
-| Date | Change |
-|------|--------|
-| 2026-02-07 | Unified logger: all diagnostic logging uses `_shared/lib/base/logger.py` instead of eprint/print-to-stderr |
-| 2026-02-06 | Remove duplicate `atomic_write.py` — consolidated to `_shared/lib/base/atomic_write.py` |
-| 2026-02-03 | Initial creation |