aiwcli 0.12.7 → 0.13.0

package/dist/templates/_shared/lib-ts/base/hook-utils.ts

@@ -12,7 +12,7 @@ import { getContextBySessionId } from "../context/context-store.js";
 import type { HookInput, HookOutput, PermissionRequestOutput } from "../types.js";
 
 // Re-export logger functions for convenience (matches Python hook_utils re-exports)
-export {          setSessionId };
+
 
 // Context window baseline: tokens not visible in hook data §5.9
 export const CONTEXT_BASELINE_TOKENS = 22_600;
@@ -281,23 +281,28 @@ export function emitPermissionDecision(
 export function emitBlock(reason: string, context?: string): void {
   const event = _lastHookEvent;
   switch (event) {
-    case "PermissionRequest":
+    case "PermissionRequest": {
       emitPermissionDecision("deny", { message: reason });
       break;
+    }
     case "PostToolUse":
-    case "PostToolUseFailure":
+    case "PostToolUseFailure": {
       emitBlockViaExit(reason, context);
       break;
-    case "PreToolUse":
+    }
+    case "PreToolUse": {
       emitContextAndBlock(context ?? reason, reason);
       break;
+    }
     case "Stop":
-    case "SubagentStop":
+    case "SubagentStop": {
       emitBlockTopLevel(reason);
       break;
-    case "UserPromptSubmit":
+    }
+    case "UserPromptSubmit": {
       emitBlockPrompt(reason, context);
       break;
+    }
     default: {
       logWarn(_cachedHookName ?? "unknown",
         `emitBlock() called from ${event ?? "unknown"} — no blocking mechanism exists for this event type, ignoring`);
@@ -431,6 +436,13 @@ export function runHook(
   _earlyReadInput(prefetchedInput);
   _cachedHookName = hookName;
 
+  // Ensure cwd is project root so relative paths in hooks resolve correctly,
+  // even when cwd has drifted via `cd` in a Bash tool call.
+  try {
+    const projectRoot = getProjectRoot(_prefetchedInput?.cwd);
+    if (process.cwd() !== projectRoot) process.chdir(projectRoot);
+  } catch { /* non-fatal — proceed with current cwd */ }
+
   const startTime = performance.now();
   const template = detectTemplate();
   const event = _lastHookEvent ?? "unknown";
@@ -482,6 +494,13 @@ export function runHookAsync(
   _earlyReadInput(prefetchedInput);
   _cachedHookName = hookName;
 
+  // Ensure cwd is project root so relative paths in hooks resolve correctly,
+  // even when cwd has drifted via `cd` in a Bash tool call.
+  try {
+    const projectRoot = getProjectRoot(_prefetchedInput?.cwd);
+    if (process.cwd() !== projectRoot) process.chdir(projectRoot);
+  } catch { /* non-fatal — proceed with current cwd */ }
+
   const startTime = performance.now();
   const template = detectTemplate();
   const event = _lastHookEvent ?? "unknown";
@@ -583,4 +602,4 @@ function _drainAndExit(code: number): void {
   });
 }
 
-export {logInfo, logError, logBlocking, logHookError, logDiagnostic, setContextPath, hookLog, logDebug, logWarn} from "./logger.js";
+export {hookLog, logBlocking, logDebug, logDiagnostic, logError, logHookError, logInfo, logWarn, setContextPath, setSessionId} from "./logger.js";

package/dist/templates/_shared/lib-ts/base/inference.ts

@@ -5,6 +5,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+
 import { logDebug, logWarn } from "./logger.js";
 import { STOP_WORDS } from "./stop-words.js";
 import type { InferenceResult } from "../types.js";
@@ -12,9 +13,9 @@ import { execFileAsync, getInternalSubprocessEnv, shellQuoteWin } from "./subpro
 
 // Model configurations §6.1
 const MODELS: Record<string, string> = {
-  fast: "claude-3-haiku-20240307",
-  standard: "claude-sonnet-4-20250514",
-  smart: "claude-opus-4-20250514",
+  fast: "claude-haiku-4-5-20251001",
+  standard: "claude-sonnet-4-6",
+  smart: "claude-opus-4-6",
 };
 
 const TIMEOUTS: Record<string, number> = {
@@ -44,7 +45,6 @@ export function inference(
 
   try {
     const isWin = process.platform === "win32";
-    let stdout: string;
 
     // On Windows with shell:true, Node.js sets windowsVerbatimArguments —
     // args are joined with spaces, NOT individually quoted. We must manually
@@ -53,10 +53,10 @@ export function inference(
     const empty = isWin ? '""' : "";
     let promptArg = fullPrompt;
     if (isWin) {
-      promptArg = '"' + fullPrompt.replace(/\r?\n/g, " ").replace(/"/g, '""') + '"';
+      promptArg = '"' + fullPrompt.replaceAll(/\r?\n/g, " ").replaceAll('"', '""') + '"';
     }
 
-    stdout = execFileSync(
+    const stdout = execFileSync(
       "claude",
       ["--model", model, "--print", "--setting-sources", empty, "-p", "--no-session-persistence", promptArg],
       {
@@ -74,10 +74,10 @@ export function inference(
       output: stdout.trim(),
       latency_ms: latencyMs,
     };
-  } catch (e: any) {
+  } catch (error: any) {
     const latencyMs = Date.now() - startTime;
 
-    if (e.code === "ETIMEDOUT" || e.killed) {
+    if (error.code === "ETIMEDOUT" || error.killed) {
       return {
         success: false,
         output: "",
@@ -86,7 +86,7 @@ export function inference(
       };
     }
 
-    if (e.code === "ENOENT") {
+    if (error.code === "ENOENT") {
       return {
         success: false,
         output: "",
@@ -96,11 +96,11 @@ export function inference(
     }
 
     // Non-zero exit code
-    if (e.status !== undefined && e.status !== 0) {
+    if (error.status !== undefined && error.status !== 0) {
       return {
         success: false,
-        output: (e.stdout ?? "").toString().trim(),
-        error: (e.stderr ?? "").toString().trim() || `Exit code: ${e.status}`,
+        output: (error.stdout ?? "").toString().trim(),
+        error: (error.stderr ?? "").toString().trim() || `Exit code: ${error.status}`,
         latency_ms: latencyMs,
       };
     }
@@ -108,7 +108,7 @@ export function inference(
     return {
       success: false,
       output: "",
-      error: String(e),
+      error: String(error),
       latency_ms: latencyMs,
     };
   }
@@ -140,7 +140,7 @@ export function generateSemanticSummary(
   if (!result.success || !result.output) return null;
 
   let summary = result.output.trim();
-  summary = summary.replace(/^["']+|["']+$/g, "");
+  summary = summary.replaceAll(/^["']+|["']+$/g, "");
   summary = summary.replace(/[.!?]+$/, "");
 
   // Filter stop words
@@ -221,11 +221,11 @@ export function generateContextIdSlug(
   if (!slug) slug = raw;
 
   // Clean up
-  slug = slug.replace(/^["'`]+|["'`]+$/g, "");
+  slug = slug.replaceAll(/^["'`]+|["'`]+$/g, "");
   slug = slug.replace(/[.!?]+$/, "");
-  slug = slug.replace(/-/g, " ");
-  slug = slug.replace(/[^a-zA-Z0-9 ]/g, "");
-  slug = slug.replace(/\s+/g, " ").trim();
+  slug = slug.replaceAll('-', " ");
+  slug = slug.replaceAll(/[^a-zA-Z0-9 ]/g, "");
+  slug = slug.replaceAll(/\s+/g, " ").trim();
 
   const words = slug.split(" ");
 
@@ -263,7 +263,7 @@ export async function inferenceAsync(
   const isWin = process.platform === "win32";
   const empty = isWin ? '""' : "";
   const promptArg = isWin
-    ? shellQuoteWin(fullPrompt.replace(/\r?\n/g, " "))
+    ? shellQuoteWin(fullPrompt.replaceAll(/\r?\n/g, " "))
     : fullPrompt;
 
   const result = await execFileAsync(

package/dist/templates/_shared/lib-ts/base/lint-dispatch.ts

@@ -0,0 +1,287 @@
+/**
+ * Linter dispatch table and runner for PostToolUse lint-after-edit hook.
+ * Maps file extensions to linter configs, runs linters, parses output.
+ * See root CLAUDE.md for template sync targets.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { logDebug, logWarn } from "./logger.js";
+import { findExecutable } from "./subprocess-utils.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface LinterConfig {
+  name: string;
+  extensions: string[];
+  source: "bundled" | "system";
+  binaryName: string;
+  buildArgs: (filePath: string) => string[];
+  parseOutput: (stdout: string, stderr: string, exitCode: number) => LintError[];
+  /** Exit codes that mean "lint errors found" (parse output). Other non-zero = crash (skip). */
+  lintExitCodes: number[];
+}
+
+export interface LintError {
+  line: number;
+  column?: number;
+  severity: "error" | "warning";
+  message: string;
+  rule?: string;
+}
+
+// ─── Output Parsers ─────────────────────────────────────────────────────────
+
+function parseBiomeOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
+  try {
+    const data = JSON.parse(stdout);
+    const diagnostics: any[] = data?.diagnostics ?? [];
+    return diagnostics.map((d) => ({
+      line: d.location?.span?.start?.line ?? d.location?.sourceCode?.lineIndex ?? 0,
+      column: d.location?.span?.start?.character ?? undefined,
+      severity: d.severity === "error" || d.severity === "fatal" ? "error" as const : "warning" as const,
+      message: typeof d.description === "string" ? d.description : (d.message ?? "Unknown issue"),
+      rule: d.category ?? undefined,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+function parseRuffOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
+  try {
+    const items: any[] = JSON.parse(stdout);
+    return items.map((item) => ({
+      line: item.location?.row ?? 0,
+      column: item.location?.column ?? undefined,
+      severity: "error" as const,
+      message: item.message ?? "Unknown issue",
+      rule: item.code ?? undefined,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+function parseShellcheckOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
+  try {
+    const data = JSON.parse(stdout);
+    const comments: any[] = data?.comments ?? [];
+    return comments.map((c) => ({
+      line: c.line ?? 0,
+      column: c.column ?? undefined,
+      severity: c.level === "error" ? "error" as const : "warning" as const,
+      message: c.message ?? "Unknown issue",
+      rule: c.code ? `SC${c.code}` : undefined,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+function parseRubocopOutput(stdout: string, _stderr: string, _exitCode: number): LintError[] {
+  try {
+    const data = JSON.parse(stdout);
+    const offenses: any[] = data?.files?.[0]?.offenses ?? [];
+    return offenses.map((o) => ({
+      line: o.location?.line ?? 0,
+      column: o.location?.column ?? undefined,
+      severity: o.severity === "error" || o.severity === "fatal" ? "error" as const : "warning" as const,
+      message: o.message ?? "Unknown issue",
+      rule: o.cop_name ?? undefined,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+const CPPCHECK_RE = /^(.+):(\d+):(\d+): (\w+): (.+) \[(.+)\]$/;
+
+function parseCppcheckOutput(_stdout: string, stderr: string, _exitCode: number): LintError[] {
+  const errors: LintError[] = [];
+  for (const line of stderr.split("\n")) {
+    const m = CPPCHECK_RE.exec(line.trim());
+    if (m) {
+      errors.push({
+        line: parseInt(m[2]!, 10),
+        column: parseInt(m[3]!, 10),
+        severity: m[4] === "error" ? "error" : "warning",
+        message: m[5]!,
+        rule: m[6],
+      });
+    }
+  }
+  return errors;
+}
+
+// ─── Dispatch Table ─────────────────────────────────────────────────────────
+
+const LINTERS: LinterConfig[] = [
+  {
+    name: "biome",
+    extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".jsonc", ".css"],
+    source: "bundled",
+    binaryName: "biome",
+    buildArgs: (filePath) => ["lint", "--reporter=json", "--max-diagnostics=20", filePath],
+    parseOutput: parseBiomeOutput,
+    lintExitCodes: [1],
+  },
+  {
+    name: "ruff",
+    extensions: [".py", ".pyi"],
+    source: "system",
+    binaryName: "ruff",
+    buildArgs: (filePath) => ["check", "--no-fix", "--output-format=json", filePath],
+    parseOutput: parseRuffOutput,
+    lintExitCodes: [1],
+  },
+  {
+    name: "shellcheck",
+    extensions: [".sh", ".bash"],
+    source: "system",
+    binaryName: "shellcheck",
+    buildArgs: (filePath) => ["-f", "json1", filePath],
+    parseOutput: parseShellcheckOutput,
+    lintExitCodes: [1],
+  },
+  {
+    name: "rubocop",
+    extensions: [".rb"],
+    source: "system",
+    binaryName: "rubocop",
+    buildArgs: (filePath) => ["--format", "json", "--no-autocorrect", filePath],
+    parseOutput: parseRubocopOutput,
+    lintExitCodes: [1, 2],
+  },
+  {
+    name: "cppcheck",
+    extensions: [".c", ".cpp", ".h", ".hpp"],
+    source: "system",
+    binaryName: "cppcheck",
+    buildArgs: (filePath) => ["--enable=warning,style", "--template=gcc", filePath],
+    parseOutput: parseCppcheckOutput,
+    lintExitCodes: [1],
+  },
+];
+
+/** Extension → LinterConfig lookup map (built once). */
+const EXT_MAP = new Map<string, LinterConfig>();
+for (const linter of LINTERS) {
+  for (const ext of linter.extensions) {
+    EXT_MAP.set(ext, linter);
+  }
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Look up the linter config for a file by extension.
+ * Returns null if no linter is configured for this file type.
+ */
+export function getLinterForFile(filePath: string): LinterConfig | null {
+  const ext = path.extname(filePath).toLowerCase();
+  return EXT_MAP.get(ext) ?? null;
+}
+
+/**
+ * Resolve the binary path for a linter.
+ * Bundled linters: check project node_modules/.bin first, then PATH.
+ * System linters: check PATH only.
+ * Returns null if binary not found.
+ */
+function resolveBinary(config: LinterConfig, projectRoot: string): string | null {
+  if (config.source === "bundled") {
+    // 1. Project-local node_modules
+    const localBin = path.join(projectRoot, "node_modules", ".bin", config.binaryName);
+    if (fs.existsSync(localBin)) return localBin;
+
+    // 2. PATH (covers global npm install of aiwcli)
+    return findExecutable(config.binaryName);
+  }
+
+  // System linters: PATH only
+  return findExecutable(config.binaryName);
+}
+
+/**
+ * Run a linter on a file.
+ * Returns null if the linter binary is not found.
+ * Returns { errors: [] } if the file passes lint.
+ */
+export function runLinter(
+  config: LinterConfig,
+  filePath: string,
+  projectRoot: string,
+): { errors: LintError[] } | null {
+  const binary = resolveBinary(config, projectRoot);
+  if (!binary) {
+    logDebug("lint-dispatch", `${config.name} binary not found, skipping`);
+    return null;
+  }
+
+  const args = config.buildArgs(filePath);
+
+  try {
+    // eslint-disable-next-line no-undef -- Bun runtime global
+    const result = (Bun as any).spawnSync([binary, ...args], {
+      cwd: projectRoot,
+      timeout: 8000, // 8s soft limit (10s hook timeout is the hard kill)
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const {exitCode} = result;
+    const stdout = result.stdout?.toString() ?? "";
+    const stderr = result.stderr?.toString() ?? "";
+
+    // Exit 0 = clean
+    if (exitCode === 0) return { errors: [] };
+
+    // Known lint-error exit codes → parse output
+    if (config.lintExitCodes.includes(exitCode)) {
+      const errors = config.parseOutput(stdout, stderr, exitCode);
+      return { errors };
+    }
+
+    // Unknown exit code = crash/timeout → skip
+    logWarn("lint-dispatch", `${config.name} exited with unexpected code ${exitCode} on ${filePath}`);
+    return { errors: [] };
+  } catch (error) {
+    logWarn("lint-dispatch", `${config.name} execution failed: ${error}`);
+    return { errors: [] };
+  }
+}
+
+/**
+ * Format lint errors for Claude's context injection.
+ * Returns a human-readable string suitable for emitContext().
+ */
+export function formatLintErrors(
+  filePath: string,
+  linterName: string,
+  errors: LintError[],
+  maxShown = 15,
+): string {
+  const shown = errors.slice(0, maxShown);
+  const lines = [
+    `Lint: ${errors.length} issue(s) in \`${filePath}\` (${linterName})`,
+    "",
+  ];
+
+  for (const err of shown) {
+    const loc = err.column ? `L${err.line}:${err.column}` : `L${err.line}`;
+    const sev = err.severity === "error" ? "error" : "warn";
+    const rule = err.rule ? ` [${err.rule}]` : "";
+    lines.push(`- **${sev}** ${loc}: ${err.message}${rule}`);
+  }
+
+  if (errors.length > maxShown) {
+    lines.push(`- ... and ${errors.length - maxShown} more`);
+  }
+
+  lines.push("");
+  lines.push("Fix these lint errors in the file you just edited.");
+
+  return lines.join("\n");
+}

package/dist/templates/_shared/lib-ts/base/state-io.ts

@@ -6,8 +6,9 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getContextDir } from "./constants.js";
+
 import { atomicWrite } from "./atomic-write.js";
+import { getContextDir } from "./constants.js";
 import { logWarn } from "./logger.js";
 import type { ContextState, Mode } from "../types.js";
 
@@ -121,8 +122,8 @@ export function readStateJson(
     const data = JSON.parse(raw) as Record<string, any>;
     migrateConsumedFlags(data); // Migrate before dictToState
     return dictToState(data);
-  } catch (e: any) {
-    logWarn("state_io", `Failed to read state.json for '${contextId}': ${e}`);
+  } catch (error: any) {
+    logWarn("state_io", `Failed to read state.json for '${contextId}': ${error}`);
     return null;
   }
 }

package/dist/templates/_shared/lib-ts/base/subprocess-utils.ts

@@ -26,14 +26,14 @@ const childProcesses = new Set<ChildProcess>();
  * Called by exit and signal handlers.
  */
 function cleanupChildren(): void {
-  childProcesses.forEach((child) => {
+  for (const child of childProcesses) {
     try {
       // Use SIGKILL for forceful termination (important on Windows with shell)
       child.kill("SIGKILL");
     } catch {
       // Ignore errors (child may have already exited)
     }
-  });
+  }
   childProcesses.clear();
 }
 
@@ -229,7 +229,7 @@ export function execFileAsync(
     });
 
     // Pipe input to stdin if provided
-    if (options?.input != null && child.stdin) {
+    if (options?.input !== null && options?.input !== undefined && child.stdin) {
       child.stdin.write(options.input);
       child.stdin.end();
     }

package/dist/templates/_shared/lib-ts/context/CLAUDE.md

@@ -0,0 +1,134 @@
+# Context Management System
+
+Shared library for context lifecycle management: state machine, session binding, plan tracking, and artifact routing.
+
+## Overview
+
+A "context" is a named work session with a state machine that tracks mode transitions, staged artifacts, and session history. Contexts persist to disk as `state.json` files under `_output/contexts/{id}/`. They are the backbone of the handoff and session-restore system.
+
+## File Structure
+
+```
+context/
+├── CLAUDE.md          ← This file
+├── context-store.ts   ← Core CRUD + state machine transitions
+├── context-formatter.ts ← Context → human-readable text for injection
+├── context-selector.ts  ← Find active/relevant contexts by criteria
+├── plan-manager.ts    ← Plan file archive, discovery, hash, path extraction
+└── task-tracker.ts    ← Task progress tracking within a context
+```
+
+## State Machine
+
+```
+                      ┌─────────────┐
+                      │   created   │
+                      └──────┬──────┘
+                             │ first user prompt / maybeActivate()
+                             ▼
+                      ┌─────────────┐
+                  ┌──▶│   active    │◀──────────────────┐
+                  │   └──────┬──────┘                   │
+                  │          │ session_end + artifact    │ session_start (clear)
+                  │          ▼                           │
+                  │   ┌─────────────────┐               │
+                  │   │ has_staged_work  │ ──────────────┘
+                  │   └──────┬──────────┘
+                  │          │ work_consumed = true
+                  │          ▼
+                  │   ┌─────────────┐
+                  │   │  archived   │──▶ (terminal)
+                  │   └─────────────┘
+                  │
+                  └─── reopenContext()
+```
+
+**Modes:**
+- `created` — context initialized, not yet bound to a session
+- `active` — session in progress, context is current
+- `has_staged_work` — session ended with staged artifact (plan or handoff)
+- `archived` — context complete and closed
+
+## API Reference
+
+### `context-store.ts`
+
+| Function | Purpose |
+|----------|---------|
+| `createContext(id, opts)` | Create new context with initial state |
+| `getContext(contextId)` | Read context by ID |
+| `getAllContexts(mode?, root?)` | List all contexts, optionally filtered by mode |
+| `getContextBySessionId(sessionId, root?)` | Find context that owns a session ID |
+| `updateContext(contextId, patch)` | Partial state update |
+| `bindSession(contextId, sessionId)` | Attach session ID to context |
+| `updateMode(contextId, mode)` | Transition state machine mode |
+| `maybeActivate(contextId)` | Activate if in `created` mode (idempotent) |
+| `completeContext(contextId)` | Mark complete, archive |
+| `archiveContext(contextId)` | Archive without completing |
+| `reopenContext(contextId)` | Transition `archived` → `active` |
+| `createContextFromPrompt(prompt)` | Create context from user prompt text |
+| `loadState(contextId)` | Raw state.json read |
+| `saveState(contextId, state)` | Raw state.json write |
+| `determineArtifactType(context)` | Detect `"plan"` or `"handoff"` from staged state |
+
+### `context-formatter.ts`
+
+Formats context state for injection into Claude's context window.
+
+| Function | Purpose |
+|----------|---------|
+| `formatContext(context)` | Full context as human-readable markdown |
+| `formatContextSummary(context)` | Short one-line summary |
+
+### `context-selector.ts`
+
+Finds contexts by various criteria.
+
+| Function | Purpose |
+|----------|---------|
+| `selectActiveContext(root?)` | Find the single active context (errors if multiple) |
+| `findContextByMode(mode, root?)` | Find contexts in a given mode |
+| `findStagedWorkContext(root?)` | Find context with `has_staged_work` mode |
+
+### `plan-manager.ts`
+
+Manages plan file lifecycle within a context.
+
+| Function | Purpose |
+|----------|---------|
+| `archivePlan(contextId, planPath)` | Copy plan to context's `plans/` folder |
+| `findLatestPlan(contextId)` | Find most recent archived plan |
+| `generatePlanId()` | Generate unique plan ID |
+| `normalizePlanContent(text)` | Strip metadata for hashing |
+| `extractPlanAnchors(content)` | Extract key phrases from plan for matching |
+| `findPlanPathInTranscript(transcriptPath)` | Parse plan path from JSONL transcript |
+| `extractPlanPathFromResult(toolResult)` | Extract plan path from tool result JSON |
+
+### `task-tracker.ts`
+
+Tracks task progress (ISC criteria) within a context.
+
+| Function | Purpose |
+|----------|---------|
+| `initTaskTracker(contextId)` | Create task tracker for context |
+| `addTask(contextId, task)` | Add tracked task |
+| `updateTask(contextId, taskId, patch)` | Update task status |
+| `getTaskSummary(contextId)` | Progress summary |
+
+## Which Hooks Use This System
+
+| Hook | Usage |
+|------|-------|
+| `session_start.ts` | `getContextBySessionId()`, `bindSession()`, `updateMode()`, `getAllContexts()` |
+| `session_end.ts` | `getContextBySessionId()`, `updateMode()`, `saveState()` |
+| `user_prompt_submit.ts` | `getAllContexts()`, `maybeActivate()`, `determineArtifactType()` |
+| `archive_plan.ts` | `getContextBySessionId()`, `archivePlan()` |
+| `save_handoff.ts` | `getContextBySessionId()`, `updateContext()` |
+| `cc-native-plan-review.ts` | `getContextBySessionId()`, `getAllContexts()` |
+
+## Design Decisions
+
+- **Single state.json per context:** All state is in one file. No distributed state. Atomic writes prevent corruption.
+- **No moves out of lib-ts:** Context is pure library code imported by ~8 shared hooks. Moving it would require updating all those import paths for no structural gain. The subfolder is already co-located; it just needed documentation.
+- **`maybeActivate()` is idempotent:** Can be called from any hook without checking current mode — safe to call repeatedly.
+- **`determineArtifactType()` drives session restore:** Returns `"plan"` or `"handoff"` to dispatch the correct restoration path in `session_start.ts`.