aiwcli 0.10.3 → 0.11.0

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

@@ -8,37 +8,31 @@
 
 | Hook | Trigger | Purpose |
 |------|---------|---------|
-| `cc-native-plan-review.py` | PreToolUse: ExitPlanMode | Review plans before user approval |
-| `add_plan_context.py` | PostToolUse: AskUserQuestion, PreToolUse: Task | Mark questions asked; nudge Plan subagent to ask questions first |
-| `suggest-fresh-perspective.py` | PostToolUse | Suggest fresh perspective workflow |
+| `cc-native-plan-review.ts` | PreToolUse: ExitPlanMode | Review plans before user approval |
+| `add_plan_context.ts` | PostToolUse: AskUserQuestion, PreToolUse: Task | Mark questions asked; nudge Plan subagent to ask questions first |
+| `plan_questions_early.ts` | UserPromptSubmit | Inject Phase A clarification prompt in plan mode |
 
 ---
 
 ## Import Pattern
 
-Hooks run from arbitrary working directories. Always set up sys.path explicitly.
+CC-native hooks are TypeScript, run via `bun`. Use relative imports from the hook file location.
 
-```python
-# CORRECT - works in hook context
-from pathlib import Path
-import sys
+```typescript
+// Shared library imports (via _shared/lib-ts/)
+import { loadHookInput, runHook, logInfo, emitContext } from "../../_shared/lib-ts/base/hook-utils.js";
+import { isInternalCall } from "../../_shared/lib-ts/base/subprocess-utils.js";
+import { getProjectRoot } from "../../_shared/lib-ts/base/constants.js";
 
-_lib = Path(__file__).parent.parent / "lib"
-sys.path.insert(0, str(_lib))
-
-# For shared library access
-_shared = Path(__file__).parent.parent.parent / "_shared"
-sys.path.insert(0, str(_shared))
-
-from utils import eprint, ReviewerResult
-from lib.base.subprocess_utils import is_internal_call
-from debug import log_debug  # Context-folder debug logging
+// CC-native library imports (via ../lib-ts/)
+import { wasQuestionsAsked, markQuestionsAsked } from "../lib-ts/cc-native-state.js";
+import { loadConfig } from "../lib-ts/config.js";
+import type { AgentConfig } from "../lib-ts/types.js";
 ```
 
-```python
-# WRONG - relative imports fail in hook context
-from ..lib import utils  # ModuleNotFoundError
-```
+**Important:** Always use `.js` extensions in import paths — Bun resolves `.ts` files from `.js` imports.
+
+**Import direction:** Hooks → `_cc-native/lib-ts/` → `_shared/lib-ts/`. Never reverse.
 
 ---
 
@@ -46,13 +40,15 @@ from ..lib import utils  # ModuleNotFoundError
 
 Hooks can be invoked recursively when spawning subprocesses (agents, orchestrator). Always check and skip:
 
-```python
-def main() -> int:
-    # FIRST LINE of main - before any other logic
-    if is_internal_call():
-        return 0  # Skip for subprocess calls
+```typescript
+import { isInternalCall } from "../../_shared/lib-ts/base/subprocess-utils.js";
 
-    # Rest of hook logic...
+function main(): void {
+  // FIRST LINE of main - before any other logic
+  if (isInternalCall()) return;
+
+  // Rest of hook logic...
+}
 ```
 
 Without this check, the hook runs multiple times per plan review, causing duplicate reviews and state corruption.
@@ -65,138 +61,115 @@ Claude Code hooks return JSON to stdout. The format is specific to each hook typ
 
 ### PreToolUse Output
 
-```python
-# CORRECT - current API format
-import json
+Use the shared hook utilities — never construct JSON manually:
 
-out = {
-    "hookSpecificOutput": {
-        "additionalContext": "Information for Claude to see...",
-    }
-}
+```typescript
+import { emitContext, emitContextAndBlock } from "../../_shared/lib-ts/base/hook-utils.js";
 
-# To block the tool call:
-out["hookSpecificOutput"]["permissionDecision"] = "deny"
-out["hookSpecificOutput"]["permissionDecisionReason"] = "Reason shown to Claude"
+// Inject context without blocking:
+emitContext("Information for Claude to see...");
 
-print(json.dumps(out, ensure_ascii=False))
+// Block the tool call with context and reason:
+emitContextAndBlock(
+  "Review feedback for Claude to see...",
+  "Reason shown to Claude for the denial",
+);
 ```
 
-```python
-# WRONG - old format, silently ignored
-{"decision": "block", "reason": "..."}  # Does nothing
-{"continue": False, "message": "..."}   # Does nothing
-```
+**Key insight:** The old `decision`/`reason` format fails silently. If your hook isn't affecting Claude's behavior, check the output format first. Only `hookSpecificOutput` with `additionalContext`, `permissionDecision`, and `permissionDecisionReason` fields are recognized.
 
-**Key insight:** The old `decision`/`reason` format fails silently. If your hook isn't affecting Claude's behavior, check the output format first.
+---
+
+## Debugging Output
 
-### Using Hook Utilities (Preferred)
+For logging tiers, visibility rules, and stderr behavior, see **`_shared/lib-ts/CLAUDE.md`** (the shared library guide). The key rules:
 
-Instead of manually constructing hookSpecificOutput dicts, use the shared utilities from `base.hook_utils`:
+- **stderr is opt-in.** `log_debug/log_info/log_warn/log_error` write to file only (no UI noise)
+- **`logBlocking()` / `log_hook_error()`** for problems that must be visible
+- **`eprint()`** for terminal-only UX (not logged to JSONL)
+- **`print()` corrupts stdout** — never use for diagnostics
 
-```python
-from base.hook_utils import emit_context, emit_context_and_block
+TypeScript hooks use re-exported logger functions from `hook-utils.ts`:
 
-# Inject context without blocking:
-emit_context("Information for Claude to see...")
+```typescript
+import { logDebug, logInfo, logWarn, logError } from "../../_shared/lib-ts/base/hook-utils.js";
 
-# Block the tool call with context and reason:
-emit_context_and_block(
-    "Review feedback for Claude to see...",
-    "Reason shown to Claude for the denial"
-)
+logDebug("hook-name", `Found ${items.length} items`);  // file only
+logInfo("hook-name", "Starting hook...");                // file only
+logError("hook-name", `Failed: ${e}`);                   // file only
 ```
 
-These handle the JSON serialization and stdout printing. `emit_context` defaults to `ensure_ascii=False`; `emit_context_and_block` defaults to `ensure_ascii=True` (safe for Windows cp1252).
-
 ---
 
-## Debugging Output
-
-Hooks communicate via stdout (JSON) and stderr (logs). Use the unified logger for all diagnostic output:
+## Context System Integration
 
-```python
-from base.hook_utils import log_debug, log_info, log_warn, log_error
+Plan review hooks integrate with the shared context system for state management:
 
-# CORRECT - unified logger: writes to stderr AND _output/hook-log.jsonl
-log_debug("hook-name", f"Found {len(items)} items")
-log_info("hook-name", "Starting hook...")
-log_warn("hook-name", f"Fallback used: {reason}")
-log_error("hook-name", f"Failed: {e}", traceback_str=tb)
-```
+```typescript
+import { getContextBySessionId, getAllContexts } from "../../_shared/lib-ts/context/context-store.js";
+import { getContextReviewsDir } from "../../_shared/lib-ts/base/constants.js";
+
+// Find active context
+const context = getContextBySessionId(sessionId, projectRoot);
+if (!context) {
+  // Fallback: find single planning context
+  const allActive = getAllContexts("active", projectRoot);
+  const planning = allActive.filter((c: any) => c.mode === "active" || c.mode === "has_plan");
+  if (planning.length === 1) {
+    context = planning[0];
+  }
+}
 
-```python
-# ACCEPTABLE - eprint() for terminal-only UX (usage help, progress)
-eprint("Usage: python hook.py <args>")
+// Get reviews directory for this context
+const reviewsDir = getContextReviewsDir(context.id, projectRoot);
 ```
 
-```python
-# WRONG - print() goes to stdout, corrupts JSON output
-print("Debug info")  # Breaks JSON parsing
+CC-native specific state is accessed via `cc-native-state.ts`:
 
-# WRONG - raw print to stderr instead of logger
-print(f"Error: {e}", file=sys.stderr)  # Use log_error() instead
+```typescript
+import { isPlanAlreadyReviewed, markPlanReviewed, wasQuestionsAsked } from "../lib-ts/cc-native-state.js";
 ```
 
 ---
 
-## Context System Integration
+## Error Handling
 
-Plan review hooks integrate with the shared context system for state management:
+Hooks should fail gracefully — a broken hook shouldn't break the user's workflow. `runHook()` and `runHookAsync()` handle this automatically: uncaught errors log to file and exit 0 (non-blocking).
 
-```python
-from lib.context.context_manager import (
-    get_context_by_session_id,
-    get_all_in_flight_contexts,
-)
-from lib.base.constants import get_context_reviews_dir
-
-# Find active context
-context = get_context_by_session_id(session_id, project_root)
-if not context:
-    # Fallback: find single planning context
-    in_flight = get_all_in_flight_contexts(project_root)
-    planning = [c for c in in_flight if c.in_flight and c.in_flight.mode == "planning"]
-    if len(planning) == 1:
-        context = planning[0]
-
-# Get reviews directory for this context
-reviews_dir = get_context_reviews_dir(context.id, project_root)
-```
+```typescript
+import { runHook, logInfo } from "../../_shared/lib-ts/base/hook-utils.js";
 
-If context isn't found, add diagnostic logging:
+function main(): void {
+  // Hook logic — uncaught errors are handled by runHook
+  logInfo("hook-name", "Starting...");
+}
 
-```python
-log_debug("hook", f"Session ID: {session_id}")
-log_debug("hook", f"In-flight contexts: {len(in_flight)}")
-log_debug("hook", f"Modes: {[c.in_flight.mode for c in in_flight]}")
+runHook(main, "hook_name");
 ```
 
----
+For async hooks (plan review with parallel agents):
 
-## Error Handling
+```typescript
+import { runHookAsync } from "../../_shared/lib-ts/base/hook-utils.js";
 
-Hooks should fail gracefully - a broken hook shouldn't break the user's workflow:
+async function main(): Promise<void> {
+  // Async hook logic with Promise.all() etc.
+}
 
-```python
-from base.hook_utils import log_error, run_hook
+runHookAsync(main, "hook_name");
+```
 
-def main() -> int:
-    try:
-        # Hook logic...
-        return 0
-    except Exception as e:
-        import traceback
-        tb = traceback.format_exc()
-        log_error("hook-name", str(e), traceback_str=tb)
-        # Return 0 to not block the user
-        return 0
+Use `emitContextAndBlock()` for intentional blocking (e.g., plan review denial). `hookEventName` is auto-detected.
 
-if __name__ == "__main__":
-    run_hook(main, "hook-name")
-```
+---
+
+## Error Handling: Non-Critical Operations
 
-Use `sys.exit(1)` only for intentional blocking (e.g., two-stage review decision denies the plan).
+Wrap non-critical shared library calls in try/catch to prevent false "hook error" UI display. See **`_shared/lib-ts/CLAUDE.md`** > Context Store for the pattern and rationale.
+
+**When to catch locally vs let bubble:**
+- **Catch locally:** Side effects like mode transitions, state saves — the hook's primary purpose can still succeed without them
+- **Let bubble:** Core operations where failure means the hook genuinely can't do its job
 
 ---
 
@@ -205,31 +178,29 @@ Use `sys.exit(1)` only for intentional blocking (e.g., two-stage review decision
 These are reminders based on past issues. Not enforcement rules.
 
 - **Don't modify hook output format** without verifying the current Claude Code hook API (it changes between versions)
-- **Don't use `sys.exit(1)`** for non-fatal errors - it blocks the user's workflow
+- **Don't use `process.exit(1)` or `process.exit(2)`** for non-fatal errors - it blocks the user's workflow
 - **Don't forget template sync** after modifying hooks in `.aiwcli/` - changes should also go to `packages/cli/src/templates/cc-native/`
-- **Don't use `print()`** for anything except the final JSON output
+- **Don't use `console.log()`** for anything — it corrupts stdout. Use `emitContext()` for hook output
 - **Don't assume session_id format** - it can be UUID, path-like, or other formats
 - **Don't skip `is_internal_call()` check** - recursive hook execution causes state corruption
-- **Don't hardcode paths** - use `Path(__file__)` and environment variables
+- **Don't hardcode paths** - use `getProjectRoot()` and relative imports
+- **Don't let non-critical operations bubble to `runHook`** - catch locally to prevent stderr "hook error" display
 
 ---
 
 ## Verification After Changes
 
-Always validate Python syntax after editing hooks:
+Validate TypeScript syntax after editing hooks:
 
 ```bash
-# Validate working copy
-python -m py_compile .aiwcli/_cc-native/hooks/cc-native-plan-review.py
-
-# Validate template copy (after sync)
-python -m py_compile packages/cli/src/templates/cc-native/_cc-native/hooks/cc-native-plan-review.py
+# Quick syntax check via bun
+bun --print "import('.aiwcli/_cc-native/hooks/cc-native-plan-review.ts')" 2>&1 | head -5
 
-# Validate all shared hooks (loop required — py_compile doesn't accept globs)
-for f in .aiwcli/_shared/hooks/*.py; do python -m py_compile "$f"; done
+# Or check imports resolve (dry run)
+bun build --no-bundle .aiwcli/_cc-native/hooks/add_plan_context.ts --outdir /dev/null 2>&1
 ```
 
-Hooks fail silently on syntax errors - this catches them before they reach production.
+Hooks fail silently on import errors — verify after any import path changes.
 
 ---
 
@@ -239,6 +210,9 @@ Hooks fail silently on syntax errors - this catches them before they reach produ
 
 | Date | Change |
 |------|--------|
+| 2026-02-10 | **Migrated cc-native hooks from Python to TypeScript.** `cc-native-plan-review.ts` (async, parallel agent reviews via `Promise.all()`), `add_plan_context.ts`, `plan_questions_early.ts`. All hooks use `runHook()`/`runHookAsync()` entry points. Library code in `_cc-native/lib-ts/` (18 files). Settings.json updated to use `bun` runner. Python `.py` files kept as fallback until TS hooks verified. |
+| 2026-02-10 | Flipped TS logger stderr default to opt-in (`opts?.stderr === true`). Added `logBlocking()` for intentional stderr visibility. Removed redundant `{stderr: false}` from hook-utils.ts, user_prompt_submit.ts, context_monitor.ts. Added "Hook Error Visibility" section documenting visibility tiers and exit code behavior. |
+| 2026-02-10 | Fixed `debug.py` `context_path` crash. Added local try/catch around `maybeActivate` in `user_prompt_submit.ts` and `context_monitor.ts` to prevent stderr error display on non-critical I/O failures. Removed dead `context_path` from `_emitHookEnd` in `hook-utils.ts`. Added "Error Handling" section to CLAUDE.md. |
 | 2026-02-07 | Handoff staging lifecycle: `has_handoff` mode + `handoff_consumed` flag mirrors plan lifecycle. `save_handoff.py` no longer transitions to idle — stays active for session_end staging. `session_end.py` stages `active→has_handoff` when handoff_path set and not consumed. `session_start.py` restores `has_handoff→active` on /clear. `context_selector.py` has fallback Case 3b for has_handoff. PostToolUse context_monitor matcher simplified from specific tool list to `*`. |
 | 2026-02-07 | Removed PreToolUse:Write matcher from `add_plan_context.py`. Write-time plan nudges were redundant after consolidating enforcement to PreToolUse:Task. Removed `is_plan_file_write()`, `load_plan_context_config()`, `PHASE_B_ENFORCEMENT`, `nudge_write_questions()`, and `project_dir` import. |
 | 2026-02-07 | Question enforcement is now advisory-only (never blocks). `add_plan_context.py` uses `emit_context()` for all question nudges — no `permissionDecision:deny` anywhere. Removed `emit_context_and_block` import and `TASK_ENFORCEMENT_REASON` constant. |

package/dist/templates/cc-native/_cc-native/hooks/add_plan_context.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+/**
+ * Plan context hook — handles question marking and advisory question nudges.
+ *
+ * Registered for two events:
+ * - PostToolUse: AskUserQuestion — marks that questions were asked this session.
+ * - PreToolUse: Task — nudges Plan subagent to ask questions first (advisory, never blocks).
+ *
+ * All enforcement is advisory: injects additionalContext to guide Claude toward asking
+ * non-obvious questions, but never blocks the tool call. Claude can proceed regardless.
+ *
+ * Fail-safe: Any error allows the action silently.
+ */
+
+import { getProjectRoot } from "../../_shared/lib-ts/base/constants.js";
+import {
+  emitContext,
+  loadHookInput,
+  logDebug,
+  logDiagnostic,
+  logInfo,
+  runHook,
+} from "../../_shared/lib-ts/base/hook-utils.js";
+import { isInternalCall } from "../../_shared/lib-ts/base/subprocess-utils.js";
+import { getEvaluationContextReminder } from "../../_shared/lib-ts/templates/plan-context.js";
+import { markQuestionsAsked, wasQuestionsAsked } from "../lib-ts/cc-native-state.js";
+
+const CONTEXT_REMINDER = getEvaluationContextReminder();
+
+const TASK_ENFORCEMENT_CONTEXT =
+  "Before spawning a Plan agent, consider asking the user non-obvious questions " +
+  "via AskUserQuestion. Code exploration reveals WHAT exists — questions reveal WHAT MATTERS.\n\n" +
+  "Generate 5+ candidate questions across these categories, then keep only 3-4 where " +
+  "different answers would lead to meaningfully different plans:\n\n" +
+  "1. INTENT & SUCCESS CRITERIA — What does 'done well' look like? Are there multiple " +
+  "interpretations of this request? What's a 10 vs a 6?\n\n" +
+  "2. CONSTRAINTS & HISTORY — Has this been attempted before? Are there off-limits areas, " +
+  "performance requirements, or security considerations not visible in the code?\n\n" +
+  "3. TRADE-OFF PREFERENCES — Speed vs thoroughness? Minimal change vs clean architecture? " +
+  "Backward compatibility vs clean break?\n\n" +
+  "Frame each question with 2-3 concrete options so the user can choose rather than compose. " +
+  "Use AskUserQuestion with structured options — never ask questions as inline text.";
+
+function isPlanTask(payload: Record<string, unknown>): boolean {
+  const toolInput = payload.tool_input;
+  if (!toolInput || typeof toolInput !== "object") return false;
+  return String((toolInput as Record<string, unknown>).subagent_type ?? "") === "Plan";
+}
+
+function main(): void {
+  // Guard: skip for internal subprocess calls (prevents recursive hook execution)
+  if (isInternalCall()) return;
+
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const toolName = payload.tool_name;
+  const hookEvent = payload.hook_event_name ?? "unknown";
+  logDiagnostic(
+    "add_plan_context",
+    "receive",
+    `tool=${toolName}, event=${hookEvent}`,
+    { inputs: { tool_name: toolName, hook_event: hookEvent } },
+  );
+
+  const projectRoot = getProjectRoot(payload.cwd);
+
+  // PostToolUse: AskUserQuestion — mark that questions were asked
+  if (toolName === "AskUserQuestion") {
+    const sessionId = String(payload.session_id ?? "");
+    if (sessionId) {
+      markQuestionsAsked(sessionId, projectRoot);
+      logInfo("add_plan_context", `Marked questions asked for session ${sessionId.slice(0, 8)}...`);
+    }
+
+    return;
+  }
+
+  // PreToolUse: Task — nudge Plan subagent to ask questions first (advisory)
+  if (toolName === "Task") {
+    if (!isPlanTask(payload)) return; // Only gate Plan subagent spawns
+
+    const permissionMode = payload.permission_mode ?? "";
+    if (permissionMode !== "plan") return; // Only enforce during plan mode
+
+    const sessionId = payload.session_id;
+    if (!sessionId) {
+      logDebug("add_plan_context", "No session_id for Task gate, skipping enforcement");
+      return;
+    }
+
+    const sessionIdStr = String(sessionId);
+
+    if (wasQuestionsAsked(sessionIdStr, projectRoot)) {
+      logInfo("add_plan_context", "Questions asked, allowing Plan Task with eval context");
+      logDiagnostic(
+        "add_plan_context",
+        "decide",
+        "Questions asked, allowing Plan Task",
+        { decision: "allow_with_context", reasoning: "was_questions_asked=True" },
+      );
+      emitContext(CONTEXT_REMINDER);
+      return;
+    }
+
+    // Questions NOT asked: nudge toward asking questions (advisory only)
+    logInfo("add_plan_context", "Questions not asked - nudging Plan Task to ask first");
+    logDiagnostic(
+      "add_plan_context",
+      "decide",
+      "Questions not asked, nudging Plan Task",
+      { decision: "nudge", reasoning: "was_questions_asked=False, advisory context" },
+    );
+    emitContext(TASK_ENFORCEMENT_CONTEXT);
+    
+  }
+}
+
+runHook(main, "add_plan_context");