aiwcli 0.10.2 → 0.11.0

package/dist/templates/_shared/.claude/commands/handoff.md

@@ -19,14 +19,15 @@ 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.
+Resolve the active context ID programmatically:
 
-Look for the pattern in the system reminder:
-```
-Active Context: {context_id}
+```bash
+bun .aiwcli/_shared/scripts/resolve_context.ts
 ```
 
-If no active context is found, inform the user and stop - handoffs require an active context.
+This prints the active context ID to stdout. Use its output as `{context_id}` in subsequent steps.
+
+If the script exits with an error (no active context found), inform the user and stop — handoffs require an active context.
 
 ### Step 2: Gather Information
 
@@ -150,7 +151,7 @@ If a plan document path was provided in `$ARGUMENTS`:
 Instead of writing the file directly, pipe your handoff content to the save script:
 
 ```bash
-python .aiwcli/_shared/scripts/save_handoff.py "{context_id}" <<'EOF'
+bun .aiwcli/_shared/scripts/save_handoff.ts "{context_id}" <<'EOF'
 {Your complete handoff markdown content from Step 3}
 EOF
 ```
@@ -159,9 +160,13 @@ This script:
 1. Creates a folder at `_output/contexts/{context_id}/handoffs/{YYYY-MM-DD-HHMM}/`
 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)
+4. Sets `handoff_path` to the index.md path and `handoff_consumed = false` in state.json
+5. Mode stays `active` — staging happens later via session_end hook
 
-Use the handoff folder for context in the next session.
+When the session ends, `session_end.ts` stages `active → has_handoff` (if handoff_path
+exists and handoff_consumed is false). On next `/clear`, `session_start.ts` picks up the
+`has_handoff` state, binds the new session, transitions to `active`, and injects the
+handoff content via `formatHandoffContinuation()`.
 
 ## Dead Ends Section Guidelines
 
@@ -198,7 +203,8 @@ After creating file, output:
   - plan.md (copy of current plan, if any)
 
 To continue next session:
-  The index.md will be automatically suggested when you start a new session.
+  Automatic: Handoff restored on next /clear via session_start hook.
+  Manual: Use /handoff-resume to explicitly load handoff context at any time.
   Read dead-ends.md first to avoid repeating failed approaches.
 
 ⚠️  {N} dead ends documented — avoid re-attempting these approaches
@@ -223,4 +229,4 @@ If plan was updated:
 - [ ] Git status included in index.md
 - [ ] If plan provided: checkboxes updated to reflect completion status
 - [ ] If plan provided: Session Progress Log appended
-- [ ] Context state updated to indicate handoff pending
+- [ ] State has handoff_path set and handoff_consumed = false

package/dist/templates/_shared/.claude/settings.json

@@ -1,11 +1,11 @@
 {
   "statusLine": {
     "type": "command",
-    "command": "python .aiwcli/_shared/scripts/status_line.py"
+    "command": "bun .aiwcli/_shared/scripts/status_line.ts"
   },
   "fileSuggestion": {
     "type": "command",
-    "command": "python .aiwcli/_shared/hooks/file-suggestion.py"
+    "command": "bun .aiwcli/_shared/hooks-ts/file-suggestion.ts"
   },
   "hooks": {
     "UserPromptSubmit": [
@@ -13,7 +13,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python .aiwcli/_shared/hooks/user_prompt_submit.py",
+            "command": "bun .aiwcli/_shared/hooks-ts/user_prompt_submit.ts",
             "timeout": 5000
           }
         ]
@@ -25,7 +25,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python .aiwcli/_shared/hooks/context_monitor.py",
+            "command": "bun .aiwcli/_shared/hooks-ts/context_monitor.ts",
             "timeout": 5000
           }
         ]
@@ -35,7 +35,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python .aiwcli/_shared/hooks/task_create_capture.py",
+            "command": "bun .aiwcli/_shared/hooks-ts/task_create_capture.ts",
             "timeout": 3000
           }
         ]
@@ -45,7 +45,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python .aiwcli/_shared/hooks/task_update_capture.py",
+            "command": "bun .aiwcli/_shared/hooks-ts/task_update_capture.ts",
             "timeout": 3000
           }
         ]
@@ -55,7 +55,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python .aiwcli/_shared/hooks/archive_plan.py",
+            "command": "bun .aiwcli/_shared/hooks-ts/archive_plan.ts",
             "timeout": 5000
           }
         ]

package/dist/templates/_shared/hooks-ts/_utils/git-state.ts

@@ -0,0 +1,2 @@
+// Re-export from shared library — canonical location is lib-ts/base/git-state.ts
+export { getGitState } from "../../lib-ts/base/git-state.js";

package/dist/templates/_shared/hooks-ts/archive_plan.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env bun
+/**
+ * PermissionRequest:ExitPlanMode hook: Archive plan file to context's plans/ folder.
+ * Runs before user accepts/rejects. Silent output.
+ * Uses top-level await because archivePlan is async.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { getContextDir, getProjectRoot } from "../lib-ts/base/constants.js";
+import {
+  loadHookInput, logDebug, logError, logInfo, logWarn, runHookAsync,
+} from "../lib-ts/base/hook-utils.js";
+import { getContextBySessionId } from "../lib-ts/context/context-store.js";
+import {
+  archivePlan, extractPlanPathFromResult, findPlanPathInTranscript,
+} from "../lib-ts/context/plan-manager.js";
+
+/** Find the most recent .md file in a directory */
+function mostRecentMd(dir: string): null | string {
+  try {
+    if (!fs.existsSync(dir)) return null;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    let best: null | { mtime: number; path: string; } = null;
+    for (const e of entries) {
+      if (!e.isFile() || !e.name.endsWith(".md")) continue;
+      const fullPath = path.join(dir, e.name);
+      const stat = fs.statSync(fullPath);
+      if (!best || stat.mtimeMs > best.mtime) {
+        best = { path: fullPath, mtime: stat.mtimeMs };
+      }
+    }
+
+    return best?.path ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Multi-strategy plan path discovery */
+function findPlanPath(payload: Record<string, any>, projectRoot: string): null | string {
+  const toolResult = payload.tool_result as string | undefined;
+  const toolInput = (payload.tool_input ?? {}) as Record<string, any>;
+  const transcriptPath = payload.transcript_path as string | undefined;
+
+  // Strategy 1: Extract from tool result
+  if (toolResult) {
+    const fromResult = extractPlanPathFromResult(toolResult);
+    if (fromResult) {
+      logDebug("archive_plan", `Found plan path in tool_result: ${fromResult}`);
+      return fromResult;
+    }
+  }
+
+  // Strategy 2: Check tool_input fields
+  const inputPath = (toolInput.plan_path ?? toolInput.planPath) as string | undefined;
+  if (inputPath) {
+    logDebug("archive_plan", `Found plan path in tool_input: ${inputPath}`);
+    return inputPath;
+  }
+
+  // Strategy 3: Parse transcript for most recent Write to .claude/plans/
+  if (transcriptPath) {
+    const fromTranscript = findPlanPathInTranscript(transcriptPath);
+    if (fromTranscript) return fromTranscript;
+  }
+
+  // Strategy 4: Most recent .md in ~/.claude/plans/
+  const claudePlansDir = path.join(os.homedir(), ".claude", "plans");
+  const recentPlan = mostRecentMd(claudePlansDir);
+  if (recentPlan) {
+    logDebug("archive_plan", `Found plan in ~/.claude/plans/: ${recentPlan}`);
+    return recentPlan;
+  }
+
+  // Strategy 5: Fallback paths
+  const fallbacks = [
+    path.join(projectRoot, "_output", "cc-native", "plans", "current-plan.md"),
+    path.join(projectRoot, "_output", "plans", "current-plan.md"),
+    path.join(projectRoot, "plan.md"),
+  ];
+  for (const fb of fallbacks) {
+    if (fs.existsSync(fb)) {
+      logDebug("archive_plan", `Found plan at fallback: ${fb}`);
+      return fb;
+    }
+  }
+
+  return null;
+}
+
+async function asyncMain(): Promise<void> {
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  // Validate event
+  if (payload.hook_event_name !== "PermissionRequest" || payload.tool_name !== "ExitPlanMode") {
+    return;
+  }
+
+  // Check stop flag
+  if ((payload as any).stop_hook_active) {
+    logDebug("archive_plan", "stop_hook_active set, skipping");
+    return;
+  }
+
+  const projectRoot = getProjectRoot(payload.cwd);
+  const sessionId = payload.session_id;
+  if (!sessionId) {
+    logWarn("archive_plan", "No session_id");
+    return;
+  }
+
+  // Find plan path
+  let planPath = findPlanPath(payload as Record<string, any>, projectRoot);
+  if (!planPath) {
+    logWarn("archive_plan", "Could not locate plan file");
+    return;
+  }
+
+  // Resolve to absolute
+  if (!path.isAbsolute(planPath)) {
+    planPath = path.resolve(projectRoot, planPath);
+  }
+
+  // Verify exists
+  if (!fs.existsSync(planPath)) {
+    logWarn("archive_plan", `Plan file not found: ${planPath}`);
+    return;
+  }
+
+  // Find bound context
+  const state = getContextBySessionId(sessionId, projectRoot);
+  if (!state) {
+    logWarn("archive_plan", `No context bound to session ${sessionId}`);
+    return;
+  }
+
+  // Archive the plan (async — uses AI for slug generation)
+  const [archivedPath, planHash, _planSignature] = await archivePlan(planPath, state.id, projectRoot);
+
+  if (archivedPath) {
+    // Clean up debug logs (best effort, matches Python behavior)
+    try {
+      const ctxDir = getContextDir(state.id, projectRoot);
+      const debugDir = path.join(ctxDir, "debug");
+      if (fs.existsSync(debugDir)) {
+        fs.rmSync(debugDir, { recursive: true, force: true });
+      }
+    } catch { /* best effort */ }
+
+    logInfo("archive_plan", `Archived plan to ${archivedPath} (hash=${planHash})`);
+  } else {
+    logError("archive_plan", "archivePlan returned null");
+  }
+}
+
+runHookAsync(asyncMain, "archive_plan");

package/dist/templates/_shared/hooks-ts/context_monitor.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse:* hook: Monitor context window usage, trigger mode transitions,
+ * and progressive-save state when context runs low.
+ */
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import {
+  emitContext, getContextPercentRemaining, hookLog,
+  loadHookInput,
+  logDebug, logDiagnostic, logInfo, logWarn, runHook,
+} from "../lib-ts/base/hook-utils.js";
+import { nowIso } from "../lib-ts/base/utils.js";
+import { getContextBySessionId, maybeActivate, saveState } from "../lib-ts/context/context-store.js";
+import type { ContextState } from "../lib-ts/types.js";
+
+const WRITE_TOOLS = new Set(["Bash", "Edit", "NotebookEdit", "Write"]);
+
+const SAVE_STATE_THRESHOLD = 60;
+
+const CONTEXT_WARNING_30 = "## Context Window: ~30% Remaining\n\n" +
+  "This session is approaching its context limit. Consider:\n\n" +
+  "- Completing your current task, then pausing for the user to decide next steps\n" +
+  "- If significant work remains, mention that `/handoff` can capture progress " +
+  "for a fresh session\n\n" +
+  "Do not rush or cut corners — finish the current task properly. " +
+  "Just be aware that starting large new tasks may not complete before context runs out.";
+
+const CONTEXT_WARNING_15 = "## Context Window: ~15% Remaining — Wrap Up Now\n\n" +
+  "Context is critically low. After completing your current step:\n\n" +
+  "1. **Stop taking on new work**\n" +
+  "2. Summarize what was accomplished and what remains\n" +
+  "3. Offer to run `/handoff` so progress transfers to a fresh session\n\n" +
+  "Do not start new multi-step tasks. Focus on clean closure.";
+
+const WARNING_THRESHOLDS = [
+  { pct: 15, msg: CONTEXT_WARNING_15 },  // Most urgent first
+  { pct: 30, msg: CONTEXT_WARNING_30 },
+];
+
+/** Transition idle/has_plan → active when implementation tools are used. */
+function checkAndTransitionMode(
+  state: ContextState,
+  toolName: string | undefined,
+  permissionMode: string,
+  projectRoot: string,
+): void {
+  if (!toolName || !WRITE_TOOLS.has(toolName)) return;
+  try {
+    maybeActivate(state.id, permissionMode, projectRoot, "context_monitor");
+  } catch (error) {
+    logWarn("context_monitor", `maybeActivate failed (non-critical): ${error}`);
+  }
+}
+
+/** Save state snapshot at SAVE_STATE_THRESHOLD. */
+function progressiveSave(
+  state: ContextState,
+  sessionId: string,
+  projectRoot: string,
+): void {
+  state.last_session = {
+    ...state.last_session,
+    session_id: sessionId,
+    saved_at: nowIso(),
+    save_reason: "progressive_save",
+  };
+  state.last_active = nowIso();
+
+  const [ok] = saveState(state.id, state, projectRoot);
+  if (ok) {
+    logInfo("context_monitor", `Progressive save for ${state.id}`);
+  }
+}
+
+/** Emit context-low nudge if a new threshold is crossed. Fires at most once per threshold per session. */
+function checkContextWarnings(
+  state: ContextState,
+  pctRemaining: number,
+  projectRoot: string,
+): void {
+  if (!state.last_session) {
+    state.last_session = {};
+  }
+  const fired = state.last_session.context_warnings_fired ?? [];
+
+  for (const { pct, msg } of WARNING_THRESHOLDS) {
+    if (pctRemaining <= pct && !fired.includes(pct)) {
+      emitContext(msg);
+      state.last_session.context_warnings_fired = [...fired, pct];
+      saveState(state.id, state, projectRoot);
+      logInfo("context_monitor", `Context warning emitted at ${pct}% threshold`);
+      return; // One warning per tool call — most urgent fires first
+    }
+  }
+}
+
+function main(): void {
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const sessionId = payload.session_id;
+  if (!sessionId) return;
+
+  const projectRoot = getProjectRoot(payload.cwd);
+  const permissionMode = payload.permission_mode ?? "";
+  const toolName = payload.tool_name;
+
+  // Initial context lookup
+  let state = getContextBySessionId(sessionId, projectRoot);
+  if (!state) {
+    logDebug("context_monitor", `No context for session ${sessionId}`);
+    return;
+  }
+
+  // Phase 1: Mode transition for write tools
+  checkAndTransitionMode(state, toolName, permissionMode, projectRoot);
+
+  // Phase 2: Context window check (log only, no warnings emitted)
+  const [pctRemaining, tokensUsed, maxTokens] = getContextPercentRemaining(payload);
+
+  logDiagnostic("context_monitor", "receive", `tool=${toolName ?? "Unknown"}, pct_remaining=${pctRemaining}`);
+
+  if (pctRemaining === null) {
+    logDebug("context_monitor", "No context window data available");
+    return;
+  }
+
+  if (pctRemaining > SAVE_STATE_THRESHOLD) return;
+
+  // Reload state after maybeActivate may have mutated it on disk
+  state = getContextBySessionId(sessionId, projectRoot) ?? state;
+
+  // Progressive save for ≤ 60%
+  progressiveSave(state, sessionId, projectRoot);
+
+  // Context-low warnings (independent of save threshold)
+  checkContextWarnings(state, pctRemaining, projectRoot);
+
+  // Log context level (file only)
+  if (tokensUsed !== null && maxTokens !== null) {
+    hookLog("info", "context_monitor", `Context: ${pctRemaining}% remaining (~${Math.floor(tokensUsed / 1000)}k/${Math.floor(maxTokens / 1000)}k tokens)`, { stderr: false });
+  } else {
+    hookLog("info", "context_monitor", `Context: ~${pctRemaining}% remaining (from context.json)`, { stderr: false });
+  }
+}
+
+runHook(main, "context_monitor");

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

@@ -0,0 +1,130 @@
+#!/usr/bin/env bun
+/**
+ * fileSuggestion hook: Suggest context-relevant files for Claude's file inclusion.
+ * Outputs a plain JSON array (NOT hookSpecificOutput).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getContextFilePath, getContextHandoffsDir, getContextPlansDir, getContextReviewsDir, getProjectRoot } from "../lib-ts/base/constants.js";
+import { loadHookInput, logDebug, logError, runHook } from "../lib-ts/base/hook-utils.js";
+import { getAllContexts, getContextBySessionId } from "../lib-ts/context/context-store.js";
+import type { ContextState } from "../lib-ts/types.js";
+
+/** Get .md files sorted by mtime descending */
+function getMdFilesByMtime(dir: string): string[] {
+  try {
+    if (!fs.existsSync(dir)) return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const mdFiles = entries
+      .filter(e => e.isFile() && e.name.endsWith(".md"))
+      .map(e => {
+        const fullPath = path.join(dir, e.name);
+        const stat = fs.statSync(fullPath);
+        return { path: fullPath, mtime: stat.mtimeMs };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+    return mdFiles.map(f => f.path);
+  } catch {
+    return [];
+  }
+}
+
+/** Find latest folder-based document (subdirectory with index.md) */
+function getLatestFolderDoc(dir: string): null | string {
+  try {
+    if (!fs.existsSync(dir)) return null;
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const subdirs = entries
+      .filter(e => e.isDirectory())
+      .map(e => {
+        const indexPath = path.join(dir, e.name, "index.md");
+        if (fs.existsSync(indexPath)) {
+          const stat = fs.statSync(indexPath);
+          return { path: indexPath, mtime: stat.mtimeMs };
+        }
+
+        return null;
+      })
+      .filter((x): x is NonNullable<typeof x> => x !== null)
+      .sort((a, b) => b.mtime - a.mtime);
+    return subdirs.length > 0 ? subdirs[0].path : null;
+  } catch {
+    return null;
+  }
+}
+
+function main(): void {
+  const payload = loadHookInput();
+  if (!payload) {
+    console.log("[]");
+    return;
+  }
+
+  try {
+    const projectRoot = getProjectRoot(payload.cwd);
+    const sessionId = payload.session_id;
+
+    // Find active context
+    let ctx: ContextState | null = null;
+
+    if (sessionId) {
+      ctx = getContextBySessionId(sessionId, projectRoot);
+    }
+
+    // Fallback: single active (non-idle) context
+    if (!ctx) {
+      const all = getAllContexts("active", projectRoot);
+      const active = all.filter(c => c.status === "active" && c.mode !== "idle");
+      if (active.length === 1) {
+        ctx = active[0];
+      } else {
+        logDebug("file-suggestion", `Ambiguous: ${active.length} active non-idle contexts`);
+        console.log("[]");
+        return;
+      }
+    }
+
+    const suggestions: string[] = [];
+
+    // Context file
+    const ctxFile = getContextFilePath(ctx.id, projectRoot);
+    if (fs.existsSync(ctxFile)) suggestions.push(ctxFile);
+
+    // Plan files (most recent first)
+    const plansDir = getContextPlansDir(ctx.id, projectRoot);
+    suggestions.push(...getMdFilesByMtime(plansDir));
+
+    // Handoff files (prefer folder-based)
+    const handoffsDir = getContextHandoffsDir(ctx.id, projectRoot);
+    const latestHandoff = getLatestFolderDoc(handoffsDir);
+    if (latestHandoff) {
+      suggestions.push(latestHandoff);
+    } else {
+      // Legacy: only most recent flat .md file
+      const legacyHandoffs = getMdFilesByMtime(handoffsDir);
+      if (legacyHandoffs.length > 0) suggestions.push(legacyHandoffs[0]);
+    }
+
+    // Review files (prefer folder-based under cc-native/)
+    const reviewsDir = getContextReviewsDir(ctx.id, projectRoot);
+    const ccNativeReviews = path.join(reviewsDir, "cc-native");
+    const latestReview = getLatestFolderDoc(ccNativeReviews);
+    if (latestReview) {
+      suggestions.push(latestReview);
+    } else {
+      // Fallback to flat review.md files
+      suggestions.push(...getMdFilesByMtime(reviewsDir));
+    }
+
+    // Limit to 10
+    const limited = suggestions.slice(0, 10);
+    console.log(JSON.stringify(limited));
+  } catch (error) {
+    // Must output valid JSON array even on error — Claude Code expects it
+    logError("file-suggestion", `Error: ${error}`);
+    console.log("[]");
+  }
+}
+
+runHook(main, "file-suggestion");

package/dist/templates/_shared/hooks-ts/pre_compact.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env bun
+/**
+ * PreCompact hook: Save state.json snapshot before context compaction.
+ * Captures git state and session metadata for recovery.
+ */
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import { getGitState } from "../lib-ts/base/git-state.js";
+import {
+  loadHookInput, logDebug, logError, logInfo, runHook,
+} from "../lib-ts/base/hook-utils.js";
+import { nowIso } from "../lib-ts/base/utils.js";
+import { getContextBySessionId, saveState } from "../lib-ts/context/context-store.js";
+
+function main(): void {
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const sessionId = payload.session_id;
+  if (!sessionId) {
+    logDebug("pre_compact", "No session_id, skipping");
+    return;
+  }
+
+  const projectRoot = getProjectRoot(payload.cwd);
+  const state = getContextBySessionId(sessionId, projectRoot);
+  if (!state) {
+    logDebug("pre_compact", `No context bound to session ${sessionId}`);
+    return;
+  }
+
+  const gitState = getGitState(projectRoot);
+
+  state.last_session = {
+    ...state.last_session,
+    session_id: sessionId,
+    saved_at: nowIso(),
+    save_reason: "pre_compact",
+    git_state: gitState,
+  };
+
+  const [ok, err] = saveState(state.id, state, projectRoot);
+  if (ok) {
+    logInfo("pre_compact", `Saved pre-compact snapshot for ${state.id}`);
+  } else {
+    logError("pre_compact", `Failed to save state: ${err}`);
+  }
+}
+
+runHook(main, "pre_compact");