aiwcli 0.9.7 → 0.10.0

package/dist/templates/_shared/workflows/handoff.md

@@ -19,7 +19,7 @@ Generate a handoff document summarizing the current session's work, decisions, a
 
 ### Step 1: Get Context ID
 
-Extract the `context_id` from the system reminder injected by the context enforcer hook.
+Extract the `context_id` from the system reminder injected by the user_prompt_submit hook.
 
 Look for the pattern in the system reminder:
 ```
@@ -160,8 +160,14 @@ This script:
 2. Parses sections and writes sharded files (index.md, completed-work.md, dead-ends.md, etc.)
 3. Copies the current plan (if any) to plan.md
 4. Records the event in the context's event log (informational only)
-
-Use the handoff folder for context in the next session.
+5. Sets the context to dormant (`mode="idle"`) so it won't auto-select in new sessions
+
+**After handoff is saved, the context becomes dormant:**
+- It will **not** auto-select when starting new sessions — new work gets a fresh context
+- It remains visible in the context picker (`^`) with a `[Handoff Ready]` label
+- To resume, use `^N` (where N is the context number) to explicitly select it
+- When selected via `^N`, the handoff content is automatically injected into the session
+- The `handoff_path` is cleared after injection to prevent re-injection
 
 ## Dead Ends Section Guidelines
 

package/dist/templates/cc-native/.claude/settings.json

@@ -1,4 +1,8 @@
 {
+  "statusLine": {
+    "type": "command",
+    "command": "python .aiwcli/_shared/scripts/status_line.py"
+  },
   "permissions": {
     "allow": [],
     "deny": []
@@ -14,7 +18,7 @@
       "ides": [
         "claude"
       ],
-      "installedAt": "{{INSTALLED_AT}}"
+      "installedAt": "2026-01-29T01:59:02.558Z"
     }
   },
   "hooks": {
@@ -29,13 +33,44 @@
         ]
       }
     ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/session_end.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/pre_compact.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "python .aiwcli/_shared/hooks/user_prompt_submit.py",
-            "timeout": 5000
+            "timeout": 10000
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_cc-native/hooks/plan_questions_early.py",
+            "timeout": 3000
           }
         ]
       }
@@ -57,7 +92,8 @@
           {
             "type": "command",
             "command": "python .aiwcli/_shared/hooks/task_create_capture.py",
-            "timeout": 3000
+            "timeout": 3000,
+            "async": true
           }
         ]
       },
@@ -67,7 +103,8 @@
           {
             "type": "command",
             "command": "python .aiwcli/_shared/hooks/task_update_capture.py",
-            "timeout": 3000
+            "timeout": 3000,
+            "async": true
           }
         ]
       },
@@ -76,7 +113,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python .aiwcli/_shared/hooks/archive_plan.py",
+            "command": "python .aiwcli/_cc-native/hooks/plan_accepted.py",
             "timeout": 5000
           }
         ]
@@ -90,6 +127,16 @@
             "timeout": 5000
           }
         ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_cc-native/hooks/add_plan_context.py",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PermissionRequest": [
@@ -106,12 +153,20 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "TaskCreate",
+        "matcher": "^TaskCreate$",
         "hooks": [
           {
-            "type": "command",
-            "command": "python .aiwcli/_shared/hooks/task_create_atomicity.py",
-            "timeout": 15000
+            "type": "prompt",
+            "prompt": "Evaluate this TaskCreate call for atomicity. Tasks become ISC criteria checked during verification — vague criteria cannot be verified, so precision matters. A well-specified task includes: (1) Explicit file paths like 'src/lib/auth.py' instead of 'the file above' or 'as discussed', (2) Specific function or component names instead of pronouns like 'it' or 'the function', (3) Clear expected state or behavior that is binary-testable in 2 seconds, (4) Concrete scope — one concern per task, not compound goals. If all four criteria are met and an agent with zero conversation history could verify the task was completed, return ok:true. If any criterion is missing, return ok:false with a response like: 'Missing context: [list each gap — e.g., no file path specified for the auth module, expected behavior is vague: what does fix the bug mean specifically, compound task should be split into separate criteria]'. When returning ok:false, end your response with: 'Retry: Re-invoke TaskCreate with a revised subject and description that address the gaps above.' This directive ensures the calling agent corrects and retries rather than abandoning the task."
+          }
+        ]
+      },
+      {
+        "matcher": "^Task$",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "The sub-agent receives ONLY the prompt text — no conversation history, no prior context.\n\nCheck 1 — Dangling References: Does the prompt use pronouns or demonstratives that ONLY make sense with prior conversation? Violations: 'the file we looked at', 'as discussed above', 'that approach we chose', 'the error from earlier', 'fix the issue mentioned above'. NOT violations: relative paths ('_output/', 'src/lib/'), search terms ('context-manager', 'auth module'), directory exploration ('find files matching X'), tool names, or any concrete noun — even if imprecise. Only flag references that are truly UNRESOLVABLE without conversation history.\n\nCheck 2 — Implicit Contract: Does the prompt have ANY discernible goal? 'Explore the _output directory and find context files' IS a clear goal. 'Search for hooks that handle Task events' IS a clear goal. 'Read and summarize all files in X' IS a clear goal. Only flag if the prompt is truly goalless — e.g., a sentence fragment with no verb, or pure context with no request.\n\nIf both checks pass, return ok:true. When in doubt, pass — false negatives (letting a vague prompt through) are far less costly than false positives (blocking legitimate work).\n\nWhen returning ok:false, end your response with: 'Retry: Re-invoke the Task tool with a revised prompt that resolves the issues above.'"
           }
         ]
       },

package/dist/templates/cc-native/CC-NATIVE-README.md

@@ -92,29 +92,26 @@ The brackets indicate optional steps. Research only needs Clarify → Explore
 
 ---
 
-## Context Management (Phase 1 - Shared Infrastructure)
+## Context Management (Phase 2 - Shared Infrastructure)
 
-CC-Native uses **event-sourced context management** via shared infrastructure in `_shared/`:
+CC-Native uses **direct-state context management** via shared infrastructure in `_shared/`:
 
 ```
 _output/contexts/
 ├── feature-auth/                    # Context folder (method-agnostic)
-│   ├── context.json                 # Derived cache with current state
-│   ├── events.jsonl                 # SOURCE OF TRUTH (append-only)
+│   ├── state.json                   # SOURCE OF TRUTH (direct read/write)
 │   └── plans/                       # Archived plans for this context
 │       └── 2026-01-25-auth-plan.md
 └── another-context/
-    ├── context.json
-    └── events.jsonl
+    └── state.json
 ```
 
 ### Data Hierarchy
 
 | File | Role | Notes |
 |------|------|-------|
-| `events.jsonl` | **Source of truth** | Append-only, never modified |
-| `context.json` | Derived cache | Rebuilt from events if corrupted |
-| `_output/index.json` | Global cache | Aggregates all contexts |
+| `state.json` | **Source of truth** | Direct read/write per context |
+| `_output/index.json` | Global cache | Fast session-to-context lookup |
 
 ### Context Schema
 
@@ -124,27 +121,25 @@ _output/contexts/
   "status": "active",
   "summary": "JWT authentication system",
   "method": "cc-native",
-  "in_flight": {
-    "mode": "implementing",
-    "artifact_path": "_output/contexts/feature-auth/plans/2026-01-25-auth.md",
-    "artifact_hash": "a1b2c3d4"
-  }
+  "mode": "active",
+  "plan_path": "_output/contexts/feature-auth/plans/2026-01-25-auth.md",
+  "plan_hash": "a1b2c3d4",
+  "plan_signature": "approved"
 }
 ```
 
-### In-Flight Modes
+### Context Modes
 
 | Mode | Meaning |
 |------|---------|
-| `none` | Normal context, no special handling |
-| `planning` | Currently in plan mode |
-| `pending_implementation` | Plan approved, awaiting implementation |
-| `implementing` | Implementation in progress |
+| `idle` | No active plan or work in progress |
+| `has_plan` | Plan exists but not yet being implemented |
+| `active` | Implementation in progress |
 
-### Why Event Sourcing?
+### Why 2-Layer Architecture?
 
-- **Crash recovery**: Replay events to rebuild state
-- **Audit trail**: Full history of all actions
+- **Simple reads**: `state.json` is read directly, no event replay needed
+- **Fast lookup**: `index.json` provides global session-to-context mapping without scanning directories
 - **No orphan state**: Contexts always visible (no "in_progress" limbo)
 - **Cross-session**: State persists across `/clear` and session restarts
 
@@ -158,7 +153,7 @@ _output/contexts/
 
 **Check:**
 1. Context exists: `ls _output/contexts/`
-2. Events logged: `cat _output/contexts/{id}/events.jsonl`
+2. State file exists: `cat _output/contexts/{id}/state.json`
 3. Hook logs in terminal output
 
 **Solutions:**
@@ -167,13 +162,15 @@ _output/contexts/
 
 ### Context Recovery
 
-**Symptom:** `context.json` appears corrupted
+**Symptom:** `state.json` appears corrupted
 
-**Fix:** Context can be rebuilt from events:
+**WARNING:** Do NOT delete `state.json` -- it IS the source of truth and cannot be rebuilt.
+
+**Fix:** Edit `state.json` directly to correct invalid fields, or restore from a backup:
 ```bash
-# Events are the source of truth - context.json is derived
-# Delete context.json and it will be rebuilt on next access
-rm _output/contexts/{id}/context.json
+# state.json is the source of truth - do NOT delete it
+# Instead, inspect and fix the JSON manually
+cat _output/contexts/{id}/state.json
 ```
 
 ### Notification Issues

package/dist/templates/cc-native/MIGRATION.md

@@ -41,7 +41,7 @@ mv config.json plan-review.config.json
 ### Context-Integrated Reviews (v1.5.0)
 - Reviews written to `_output/contexts/{context_id}/reviews/`
 - Iteration state persists across sessions in context folder
-- Automatic context discovery via session_id or single in-flight context
+- Automatic context selection via session_id or single active context
 
 ### Atomic Writes
 - Cross-platform atomic file writes (Windows + POSIX)

package/dist/templates/cc-native/TEMPLATE-SCHEMA.md

@@ -10,18 +10,6 @@ CC-Native uses Claude Code's native tools with minimal workflow overhead. Plan r
 
 ```
 packages/cli/src/templates/cc-native/
-├── _shared/                  # SHARED: Cross-method infrastructure (Phase 1)
-│   ├── lib/
-│   │   ├── base/             # Base utilities
-│   │   │   ├── atomic_write.py   # Cross-platform atomic file writes
-│   │   │   ├── constants.py      # Security and configuration constants
-│   │   │   └── utils.py          # Common functions
-│   │   └── context/          # Context management
-│   │       ├── context_manager.py  # Context CRUD operations
-│   │       ├── event_log.py        # JSONL append/read utilities
-│   │       └── cache.py            # Cache rebuild utilities
-│   └── hooks/
-│       └── session_start.py      # SessionStart hook (context discovery)
 ├── _cc-native/               # METHOD-SPECIFIC: CC-Native template code
 │   ├── workflows/*.md        # Workflow definitions
 │   ├── hooks/                # Hook scripts
@@ -77,8 +65,7 @@ _output/
 ├── index.json                # Global context cache
 ├── contexts/                 # Context folders (method-agnostic)
 │   └── {context-id}/
-│       ├── context.json      # Context state cache
-│       ├── events.jsonl      # Event log (source of truth)
+│       ├── state.json        # Context state (source of truth)
 │       └── plans/            # Archived plans for this context
 │           └── YYYY-MM-DD-{slug}.md
 ├── cc-native/                # CC-Native specific outputs
@@ -159,7 +146,7 @@ CC-Native settings are stored in `_cc-native/plan-review.config.json`:
 
 ---
 
-## Context Management (Phase 1 - Event Sourced)
+## Context Management (Phase 1 - State Based)
 
 CC-Native uses **shared infrastructure** for cross-session context persistence:
 
@@ -168,22 +155,19 @@ _output/
 ├── index.json                        # CACHE: Aggregates all contexts
 └── contexts/                         # All contexts (method-agnostic)
     ├── feature-auth/
-    │   ├── context.json              # CACHE: Derived from events
-    │   ├── events.jsonl              # SOURCE OF TRUTH (append-only)
+    │   ├── state.json                # SOURCE OF TRUTH: Context state
     │   └── plans/                    # Archived plans for this context
     │       └── 2026-01-25-auth.md
     └── another-context/
-        ├── context.json
-        └── events.jsonl
+        └── state.json
 ```
 
 ### Data Hierarchy
 
 | Level | File | Role | Recovery |
 |-------|------|------|----------|
-| 1 (Truth) | `events.jsonl` | Append-only event log | Cannot be rebuilt |
-| 2 (Cache) | `context.json` | Current state snapshot | Rebuild from events |
-| 3 (Cache) | `index.json` | Global context index | Rebuild from context files |
+| 1 (Truth) | `state.json` | Context state (source of truth) | Cannot be rebuilt |
+| 2 (Cache) | `index.json` | Global context index | Rebuild from state files |
 
 ### Context Schema
 
@@ -213,16 +197,6 @@ _output/
 | `pending_implementation` | Plan approved | Auto-continue implementation |
 | `implementing` | Implementation active | Continue implementation |
 
-### Event Types
-
-```jsonl
-{"event":"context_created","timestamp":"2026-01-20T10:00:00Z","summary":"JWT auth","method":"cc-native"}
-{"event":"task_added","task_id":"aiw-1","subject":"Add JWT middleware","timestamp":"..."}
-{"event":"task_completed","task_id":"aiw-1","evidence":"tests pass","timestamp":"..."}
-{"event":"plan_created","path":"_output/contexts/.../plans/...","hash":"a1b2c3","timestamp":"..."}
-{"event":"context_completed","timestamp":"..."}
-```
-
 ### Robust Writes
 
 When `CC_NATIVE_ROBUST_WRITES=true` (default):
@@ -255,12 +229,14 @@ Hook scripts live in `_cc-native/hooks/`. IDE-specific wiring in `.claude/settin
 }
 ```
 
-**Hook order matters:** Reviews run first; archive runs on Edit/Write/Bash. If a review blocks, the plan is not archived. Only plans that pass all reviews get archived.
+**Hook order matters:** Archive runs on PermissionRequest:ExitPlanMode before reviews. If a review blocks, the archived plan is available for reference. Only plans that pass all reviews proceed to implementation.
 
 | Hook | Trigger | Purpose |
 |------|---------|---------|
 | `cc-native-plan-review.py` | ExitPlanMode | Unified review: CLI + orchestrator + agents |
-| `archive_plan.py` | Edit/Write/Bash | Archives approved plans when implementation starts |
+| `archive_plan.py` | PermissionRequest:ExitPlanMode | Archives plan content and stores hash/signature before user acceptance |
+| `plan_accepted.py` | PostToolUse:ExitPlanMode | Sets context mode to has_plan |
+| `plan_questions_early.py` | UserPromptSubmit | Injects Phase A clarification in plan mode |
 
 ### Claude Feedback Mechanism
 
@@ -269,11 +245,10 @@ The unified review hook returns structured JSON to Claude Code:
 ```json
 {
   "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "additionalContext": "Review results and recommendations..."
-  },
-  "decision": "block",  // Optional: blocks Claude if review fails
-  "reason": "Reason for blocking..."
+    "additionalContext": "Review results and recommendations...",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Reason for blocking..."
+  }
 }
 ```
 

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

@@ -21,7 +21,7 @@ Each agent file has:
 - **Frontmatter (YAML):** name, model, focus, categories, enabled
 - **Body (Markdown):** Full persona content → becomes `system_prompt` for `--system-prompt` flag
 
-The `aggregate_agents.py` script extracts both parts. The body becomes `AgentConfig.system_prompt`.
+The `aggregate_agents.py` script (`_cc-native/scripts/aggregate_agents.py`) extracts both parts. The body becomes `AgentConfig.system_prompt`.
 
 ## --setting-sources "" Requirement
 

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

@@ -9,7 +9,7 @@
 | Hook | Trigger | Purpose |
 |------|---------|---------|
 | `cc-native-plan-review.py` | PreToolUse: ExitPlanMode | Review plans before user approval |
-| `add_plan_context.py` | PostToolUse: EnterPlanMode | Add context when entering plan mode |
+| `add_plan_context.py` | PostToolUse: AskUserQuestion, PreToolUse: Write | Mark questions asked; add context when writing plan files |
 | `suggest-fresh-perspective.py` | PostToolUse | Suggest fresh perspective workflow |
 
 ---
@@ -32,6 +32,7 @@ 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
 ```
 
 ```python
@@ -70,7 +71,6 @@ import json
 
 out = {
     "hookSpecificOutput": {
-        "hookEventName": "PreToolUse",
         "additionalContext": "Information for Claude to see...",
     }
 }
@@ -90,25 +90,52 @@ print(json.dumps(out, ensure_ascii=False))
 
 **Key insight:** The old `decision`/`reason` format fails silently. If your hook isn't affecting Claude's behavior, check the output format first.
 
+### Using Hook Utilities (Preferred)
+
+Instead of manually constructing hookSpecificOutput dicts, use the shared utilities from `base.hook_utils`:
+
+```python
+from base.hook_utils import emit_context, emit_context_and_block
+
+# Inject context without blocking:
+emit_context("Information for Claude to see...")
+
+# 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"
+)
+```
+
+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 them correctly:
+Hooks communicate via stdout (JSON) and stderr (logs). Use the unified logger for all diagnostic output:
 
 ```python
-# CORRECT - logs go to stderr, visible in terminal
-def eprint(*args):
-    print(*args, file=sys.stderr)
+from base.hook_utils import log_debug, log_info, log_warn, log_error
+
+# 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)
+```
 
-eprint("[hook-name] Starting hook...")
-eprint(f"[hook-name] Found {len(items)} items")
+```python
+# ACCEPTABLE - eprint() for terminal-only UX (usage help, progress)
+eprint("Usage: python hook.py <args>")
 ```
 
 ```python
 # WRONG - print() goes to stdout, corrupts JSON output
 print("Debug info")  # Breaks JSON parsing
-print(json.dumps(output))  # Now invalid because of previous print
+
+# WRONG - raw print to stderr instead of logger
+print(f"Error: {e}", file=sys.stderr)  # Use log_error() instead
 ```
 
 ---
@@ -140,9 +167,9 @@ reviews_dir = get_context_reviews_dir(context.id, project_root)
 If context isn't found, add diagnostic logging:
 
 ```python
-eprint(f"[hook] Session ID: {session_id}")
-eprint(f"[hook] In-flight contexts: {len(in_flight)}")
-eprint(f"[hook] Modes: {[c.in_flight.mode for c in in_flight]}")
+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]}")
 ```
 
 ---
@@ -152,27 +179,24 @@ eprint(f"[hook] Modes: {[c.in_flight.mode for c in in_flight]}")
 Hooks should fail gracefully - a broken hook shouldn't break the user's workflow:
 
 ```python
+from base.hook_utils import log_error, run_hook
+
 def main() -> int:
     try:
         # Hook logic...
         return 0
     except Exception as e:
-        eprint(f"[hook-name] Error: {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
 
 if __name__ == "__main__":
-    try:
-        raise SystemExit(main())
-    except Exception as e:
-        import traceback
-        eprint(f"[hook-name] FATAL: {e}")
-        traceback.print_exc(file=sys.stderr)
-        # Still exit 0 to not block - or exit 1 if blocking is intentional
-        raise SystemExit(0)
+    run_hook(main, "hook-name")
 ```
 
-Use `sys.exit(1)` only for intentional blocking (e.g., `blockOnFail: true` configured).
+Use `sys.exit(1)` only for intentional blocking (e.g., two-stage review decision denies the plan).
 
 ---
 
@@ -195,7 +219,14 @@ These are reminders based on past issues. Not enforcement rules.
 Always validate Python 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
+
+# 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
 ```
 
 Hooks fail silently on syntax errors - this catches them before they reach production.
@@ -208,4 +239,8 @@ Hooks fail silently on syntax errors - this catches them before they reach produ
 
 | Date | Change |
 |------|--------|
+| 2026-02-07 | Hook lifecycle diagnostics: all hooks now use `run_hook(main, "hook_name")` entry point. Logs HOOK_START/HOOK_END with template origin, event type, duration_ms, and status. Millisecond timestamps in logger. |
+| 2026-02-07 | Unified logger: all diagnostic logging uses `log_debug/log_info/log_warn/log_error` from `_shared/lib/base/logger.py` instead of eprint/print-to-stderr. Updated debugging and error handling docs. |
+| 2026-02-06 | Merged mark_questions_asked.py into add_plan_context.py. Hook now handles both PostToolUse:AskUserQuestion and PreToolUse:Write. Deleted standalone mark_questions_asked.py. |
+| 2026-02-06 | Fixed add_plan_context.py trigger docs (was PostToolUse: EnterPlanMode, is PreToolUse: Write). Added emit_context/emit_context_and_block utility docs. |
 | 2026-02-03 | Initial creation |