aiwcli 0.9.7 → 0.10.0

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

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""PostToolUse hook for ExitPlanMode — assigns plan fields to state.json.
+
+This hook fires when the user ACCEPTS the plan (ExitPlanMode succeeds).
+PostToolUse fires ONLY on success, so this reliably indicates acceptance.
+
+The plan was already archived by archive_plan.py (PermissionRequest).
+This hook finds the archived plan, computes hash + signature, and assigns
+plan_hash, plan_signature, plan_path to state.json — without changing mode.
+
+Separation of concerns:
+- archive_plan.py (PermissionRequest) -> archives file only, no state.json changes
+- plan_accepted.py (PostToolUse) -> assigns plan fields (hash/signature/path)
+- session_end.py (SessionEnd) -> transitions active -> has_plan when plan is assigned
+- context_selector.py -> matches plan content, transitions has_plan -> active
+
+Usage in .claude/settings.json:
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "ExitPlanMode",
+      "hooks": [{
+        "type": "command",
+        "command": "python .aiwcli/_cc-native/hooks/plan_accepted.py",
+        "timeout": 5000
+      }]
+    }]
+  }
+}
+"""
+import hashlib
+import sys
+from pathlib import Path
+
+# Add parent directories to path for imports
+SCRIPT_DIR = Path(__file__).resolve().parent
+SHARED_LIB = SCRIPT_DIR.parent.parent / "_shared" / "lib"
+sys.path.insert(0, str(SHARED_LIB.parent))
+
+from lib.base.hook_utils import load_hook_input, log_hook_error
+from lib.base.logger import log_info, log_debug, log_warn, log_error
+from lib.base.utils import project_dir
+from lib.context.context_store import get_context_by_session_id, update_mode
+from lib.context.plan_manager import (
+    find_latest_plan,
+    extract_plan_path_from_result,
+    generate_plan_id,
+    normalize_plan_content,
+    extract_plan_anchors,
+)
+
+
+def main():
+    """Assign plan fields (hash/signature/path) to state.json on plan acceptance."""
+    hook_input = load_hook_input()
+    if not hook_input:
+        log_warn("plan_accepted", "EXIT: no hook_input (stdin empty or invalid JSON)")
+        return
+
+    hook_event = hook_input.get("hook_event_name", "")
+    tool_name = hook_input.get("tool_name", "")
+    session_id = hook_input.get("session_id", "MISSING")
+
+    if not (hook_event == "PostToolUse" and tool_name == "ExitPlanMode"):
+        log_debug("plan_accepted", f"Skipping: {hook_event}/{tool_name}")
+        return
+
+    project_root = project_dir(hook_input)
+    state = get_context_by_session_id(session_id, project_root)
+    if not state:
+        log_warn("plan_accepted", f"No context for session {session_id}")
+        return
+
+    log_debug("plan_accepted", f"Found context: {state.id}, mode: {state.mode}")
+
+    # Find the latest archived plan
+    plan_path = find_latest_plan(state.id, project_root)
+    if not plan_path:
+        log_warn("plan_accepted", f"No archived plan found for {state.id}")
+        return
+
+    # Find the original plan file (in ~/.claude/plans/) to inject plan-id there too
+    original_plan_path = extract_plan_path_from_result(hook_input.get("tool_result", ""))
+    if not original_plan_path:
+        claude_plans_dir = Path.home() / ".claude" / "plans"
+        if claude_plans_dir.exists():
+            plans = sorted(claude_plans_dir.glob("*.md"), key=lambda p: p.stat().st_mtime, reverse=True)
+            if plans:
+                original_plan_path = str(plans[0])
+
+    # Generate plan ID and inject into plan files
+    plan_id = generate_plan_id()
+    id_marker = f"<!-- plan-id: {plan_id} -->\n"
+
+    for file_path in [plan_path, original_plan_path]:
+        if file_path and Path(file_path).exists():
+            file_content = Path(file_path).read_text(encoding="utf-8")
+            if "<!-- plan-id:" not in file_content:
+                Path(file_path).write_text(id_marker + file_content, encoding="utf-8")
+
+    # Read the modified content (with plan ID) for hashing
+    content = Path(plan_path).read_text(encoding="utf-8")
+
+    # Compute normalized hash (Tier 2)
+    normalized = normalize_plan_content(content)
+    plan_hash = hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:12]
+    plan_signature = content[:200]  # Keep for backward compat
+
+    # Extract structural anchors (Tier 3)
+    plan_anchors = extract_plan_anchors(content)
+
+    # Assign plan to context (no mode change — keep current mode)
+    update_mode(
+        state.id, state.mode,
+        project_root=project_root,
+        plan_path=plan_path,
+        plan_hash=plan_hash,
+        plan_signature=plan_signature,
+        plan_id=plan_id,
+        plan_anchors=plan_anchors,
+    )
+    log_info("plan_accepted", f"Assigned plan to {state.id} (id: {plan_id}, hash: {plan_hash}, anchors: {len(plan_anchors)})")
+
+
+if __name__ == "__main__":
+    from lib.base.hook_utils import run_hook
+    run_hook(main, "plan_accepted")

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

@@ -0,0 +1,81 @@
+#!/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

@@ -29,12 +29,16 @@ import tempfile
 from pathlib import Path
 from typing import Any, Dict
 
-# Add lib directory to path for imports
+# 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 utils import eprint, sanitize_filename
+from base.hook_utils import emit_context
+from base.logger import log_debug, log_info, log_warn, log_error
+from utils import sanitize_filename
 
 
 # ---------------------------
@@ -78,7 +82,7 @@ def load_config(project_dir: Path) -> Dict[str, Any]:
         section = full_config.get("stuckDetection", {})
         return {**DEFAULT_CONFIG, **section}
     except Exception as e:
-        eprint(f"[suggest-fresh-perspective] Failed to load config: {e}")
+        log_warn("suggest-fresh-perspective", f"Failed to load config: {e}")
         return DEFAULT_CONFIG.copy()
 
 
@@ -144,7 +148,7 @@ def save_state(session_id: str, state: Dict[str, Any]) -> None:
     try:
         state_path.write_text(json.dumps(state), encoding="utf-8")
     except Exception as e:
-        eprint(f"[suggest-fresh-perspective] Warning: failed to save state: {e}")
+        log_warn("suggest-fresh-perspective", f"Failed to save state: {e}")
 
 
 # ---------------------------
@@ -226,19 +230,15 @@ def should_suggest(state: Dict[str, Any], cooldown: int) -> bool:
     return state.get("tool_calls_since_suggestion", 0) >= cooldown
 
 
-def create_suggestion() -> Dict[str, Any]:
-    """Create the suggestion output."""
-    return {
-        "hookSpecificOutput": {
-            "additionalContext": (
-                "\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 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:
@@ -249,8 +249,8 @@ def main() -> int:
     except json.JSONDecodeError:
         return 0  # Fail-safe
 
-    # 1. Check hook_type (cheap dict lookup)
-    if payload.get("hook_type") != "PostToolUse":
+    # 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)
@@ -314,11 +314,11 @@ def main() -> int:
 
     if is_stuck:
         if error_detected:
-            eprint("[suggest-fresh-perspective] Detected repeated error pattern")
+            log_info("suggest-fresh-perspective", "Detected repeated error pattern")
         if file_edit_detected:
-            eprint("[suggest-fresh-perspective] Detected repeated file edits")
+            log_info("suggest-fresh-perspective", "Detected repeated file edits")
         if test_failure_detected:
-            eprint("[suggest-fresh-perspective] Detected repeated test failures")
+            log_info("suggest-fresh-perspective", "Detected repeated test failures")
 
     # Only suggest if stuck AND past cooldown
     if is_stuck and should_suggest(state, cooldown):
@@ -329,11 +329,12 @@ def main() -> int:
 
         # Only suggest up to maxSuggestions times per session
         if state["suggestion_count"] <= max_suggestions:
-            eprint(f"[suggest-fresh-perspective] Suggesting fresh perspective (suggestion #{state['suggestion_count']})")
-            print(json.dumps(create_suggestion(), ensure_ascii=False))
+            log_info("suggest-fresh-perspective", f"Suggesting fresh perspective (suggestion #{state['suggestion_count']})")
+            create_suggestion()
 
     return 0
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    from base.hook_utils import run_hook
+    run_hook(main, "suggest_fresh_perspective")

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

@@ -11,12 +11,21 @@
 | `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.py` | CLI and agent-based plan review implementations |
-| `atomic_write.py` | Atomic file writes for crash safety |
-| `constants.py` | Shared constants and configuration |
-| `async_archive.py` | Async plan archival operations |
+| `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
@@ -25,8 +34,8 @@
 Hooks (cc-native-plan-review.py, etc.)
     │
     ├── lib/utils.py (core utilities)
-    │       └── lib/atomic_write.py
     │       └── lib/constants.py
+    │       └── _shared/lib/base/atomic_write.py
     │
     ├── lib/state.py (state management)
     │       └── lib/utils.py (eprint)
@@ -34,6 +43,14 @@ Hooks (cc-native-plan-review.py, etc.)
     ├── 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
@@ -117,7 +134,8 @@ This is a recurring issue. Any path string comparison must handle both separator
 For critical files (state, reviews), use atomic writes to prevent corruption on crash:
 
 ```python
-from atomic_write import atomic_write
+# Import from shared lib (canonical location)
+from _shared.lib.base.atomic_write import atomic_write
 
 # CORRECT - atomic write
 success, error = atomic_write(path, content)
@@ -130,14 +148,16 @@ if not success:
 path.write_text(content, encoding="utf-8")
 ```
 
-Atomic writes use a temp file + rename pattern. Check `constants.ENABLE_ROBUST_PLAN_WRITES` for the feature flag.
+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 function** in `reviewers.py`:
+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],
@@ -154,7 +174,10 @@ Atomic writes use a temp file + rename pattern. Check `constants.ENABLE_ROBUST_P
        )
    ```
 
-2. **Export in `__init__.py`** (if needed for external use)
+2. **Export in `reviewers/__init__.py`**:
+   ```python
+   from .myreviewer import run_myreviewer_review
+   ```
 
 3. **Add config** in `plan-review.config.json`:
    ```json
@@ -222,7 +245,7 @@ content = path.read_text()  # May use cp1252 on Windows
 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 `eprint()` to avoid corrupting stdout
+- **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
@@ -237,4 +260,6 @@ These are reminders based on past issues. Not enforcement rules.
 
 | 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 |

package/dist/templates/cc-native/_cc-native/lib/debug.py

@@ -1,20 +1,35 @@
 """
 Permanent debug logging for cc-native hooks.
 
-Logs are written to context folder: _output/contexts/<context-id>/debug/<session-name>.log
+Thin delegation layer over the unified logger (_shared/lib/base/logger.py).
+Logs are written to context folder: _output/contexts/<context-id>/debug/hook-log.jsonl
 Append-only, cleaned up when context is archived.
 Can be disabled via CCNATIVE_DEBUG_DISABLE=1 environment variable.
 """
 
-import json
 import os
-from datetime import datetime
 from pathlib import Path
 from typing import Any, Optional
 
 # Feature flag - set CCNATIVE_DEBUG_DISABLE=1 to turn off
 DEBUG_ENABLED = os.environ.get("CCNATIVE_DEBUG_DISABLE", "").lower() not in ("1", "true", "yes")
 
+# Import unified logger
+try:
+    from _shared.lib.base.logger import hook_log
+except ImportError:
+    # Fallback: try relative import path used by hooks
+    try:
+        import sys
+        _shared = Path(__file__).parent.parent.parent.parent / "_shared"
+        if str(_shared) not in sys.path:
+            sys.path.insert(0, str(_shared))
+        from lib.base.logger import hook_log
+    except ImportError:
+        # Last resort: no-op
+        def hook_log(*args, **kwargs):
+            pass
+
 
 def get_debug_dir(context_path: Path) -> Path:
     """Get or create debug directory within context folder.
@@ -51,7 +66,7 @@ def debug_log(
     message: str,
     data: Optional[Any] = None
 ) -> None:
-    """Write a debug log entry (append-only).
+    """Write a debug log entry. Delegates to unified logger.
 
     Args:
         context_path: Path to context folder
@@ -63,22 +78,15 @@ def debug_log(
     if not DEBUG_ENABLED:
         return
 
-    try:
-        log_path = get_log_path(context_path, session_name)
-        timestamp = datetime.now().isoformat()
-
-        entry = f"[{timestamp}] [{component}] {message}"
-        if data is not None:
-            try:
-                data_str = json.dumps(data, indent=2, ensure_ascii=True, default=str)
-                entry += f"\n{data_str}"
-            except Exception:
-                entry += f"\n<data serialization failed: {type(data)}>"
-
-        with open(log_path, "a", encoding="utf-8") as f:
-            f.write(entry + "\n\n")
-    except Exception:
-        pass  # Never fail on debug logging
+    hook_log(
+        "debug",
+        session_name,
+        message,
+        component=component,
+        data=data,
+        context_path=context_path,
+        stderr=False,
+    )
 
 
 def debug_raw(
@@ -89,7 +97,7 @@ def debug_raw(
     raw: str,
     max_len: int = 10000
 ) -> None:
-    """Log raw output (stdout, stderr, etc).
+    """Log raw output (stdout, stderr, etc). Delegates to unified logger.
 
     Args:
         context_path: Path to context folder
@@ -104,7 +112,14 @@ def debug_raw(
 
     truncated = raw[:max_len] if len(raw) > max_len else raw
     suffix = f" [TRUNCATED from {len(raw)} chars]" if len(raw) > max_len else ""
-    debug_log(context_path, session_name, component, f"{label}{suffix}:", truncated)
+    hook_log(
+        "debug",
+        session_name,
+        f"{label}{suffix}: {truncated}",
+        component=component,
+        context_path=context_path,
+        stderr=False,
+    )
 
 
 def cleanup_debug_folder(context_path: Path) -> None: