aiwcli 0.10.3 → 0.11.1

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

@@ -0,0 +1,144 @@
+#!/usr/bin/env bun
+/**
+ * SessionStart hook: Restore context after /clear (plan/handoff) or compaction.
+ * Routes by source field to appropriate handler.
+ */
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import {
+  emitContext, loadHookInput, logDebug,
+  logDiagnostic, logError as _logError, logInfo, runHook,
+} from "../lib-ts/base/hook-utils.js";
+import {
+  buildRestoreSections, formatHandoffContinuation, getModeDisplay,
+} from "../lib-ts/context/context-formatter.js";
+import {
+  bindSession, getAllContexts, getContextBySessionId, updateMode,
+} from "../lib-ts/context/context-store.js";
+import type { ContextState as _ContextState } from "../lib-ts/types.js";
+
+/**
+ * Handle post-compaction restore: re-inject context that was lost during compaction.
+ * Plan content is inlined because Claude doesn't auto-paste after compact.
+ */
+function handleCompactRestore(sessionId: string, projectRoot: string): void {
+  const state = getContextBySessionId(sessionId, projectRoot);
+  if (!state) {
+    logDebug("session_start", `No context for session ${sessionId} (compact)`);
+    return;
+  }
+
+  const sections: string[] = [
+    `## Resuming Context After Compaction: ${state.id}`,
+    "",
+    `**Summary:** ${state.summary}`,
+    `**Mode:** ${getModeDisplay(state.mode) || state.mode}`,
+    "",
+  ];
+
+  // Inline plan = true (plan not auto-pasted after compact)
+  const restore = buildRestoreSections(state, projectRoot, true);
+  if (restore) sections.push(restore);
+
+  sections.push(
+    "",
+    "---",
+    "*Context was compacted to free up space. The above restores your working state.*",
+  );
+
+  emitContext(sections.join("\n"));
+  logInfo("session_start", `Compact restore for ${state.id}`);
+}
+
+/**
+ * Handle post-clear restore: find staged has_plan or has_handoff context,
+ * bind session, transition to active, inject context.
+ */
+function handleClearRestore(sessionId: string, projectRoot: string): void {
+  const allContexts = getAllContexts("active", projectRoot);
+
+  // Priority 1: has_plan contexts
+  const hasPlan = allContexts.filter(c => c.mode === "has_plan");
+  if (hasPlan.length > 0) {
+    // Pick most recently active (getAllContexts sorts by last_active desc)
+    const ctx = hasPlan[0]!;
+
+    bindSession(ctx.id, sessionId, projectRoot);
+    updateMode(ctx.id, "active", projectRoot, { plan_consumed: true });
+
+    logInfo("session_start", `Clear restore: ${ctx.id} has_plan → active (plan_consumed=true)`);
+
+    const sections: string[] = [
+      `## Resuming Context After Plan Clear: ${ctx.id}`,
+      "",
+      `**Summary:** ${ctx.summary}`,
+      `**Mode:** Active (Plan Restored)`,
+      "",
+    ];
+
+    // inline_plan=false — Claude auto-pastes plan content after /clear
+    const restore = buildRestoreSections(ctx, projectRoot, false);
+    if (restore) sections.push(restore);
+
+    sections.push(
+      "",
+      "---",
+      "*Plan has been accepted. The plan content was auto-pasted above. Implement according to the plan.*",
+    );
+
+    emitContext(sections.join("\n"));
+    return;
+  }
+
+  // Priority 2: has_handoff contexts
+  const hasHandoff = allContexts.filter(c => c.mode === "has_handoff");
+  if (hasHandoff.length > 0) {
+    const ctx = hasHandoff[0]!;
+
+    bindSession(ctx.id, sessionId, projectRoot);
+    updateMode(ctx.id, "active", projectRoot, { handoff_consumed: true });
+
+    logInfo("session_start", `Clear restore: ${ctx.id} has_handoff → active (handoff_consumed=true)`);
+
+    const handoffContent = formatHandoffContinuation(ctx, projectRoot);
+    emitContext(handoffContent);
+    return;
+  }
+
+  // Nothing to restore
+  logDebug("session_start", "No has_plan or has_handoff contexts found");
+}
+
+function main(): void {
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const sessionId = payload.session_id;
+  if (!sessionId) {
+    logDebug("session_start", "No session_id");
+    return;
+  }
+
+  const projectRoot = getProjectRoot(payload.cwd);
+  const source = payload.source ?? "";
+
+  logDiagnostic("session_start", "entry", `source=${source}, session=${sessionId}`);
+
+  switch (source) {
+    case "clear": {
+      handleClearRestore(sessionId, projectRoot);
+      break;
+    }
+
+    case "compact": {
+      handleCompactRestore(sessionId, projectRoot);
+      break;
+    }
+
+    default: {
+      logDebug("session_start", `Unhandled source: ${source}`);
+      break;
+    }
+  }
+}
+
+runHook(main, "session_start");

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

@@ -0,0 +1,48 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse:TaskCreate hook: Persist Claude's TaskCreate calls to state.json.
+ */
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import {
+  checkSkipPersistence, getToolInput, loadHookInput, logDebug,
+  logError, logInfo, logWarn, runHook, validateHookEvent,
+} from "../lib-ts/base/hook-utils.js";
+import { getContextBySessionId } from "../lib-ts/context/context-store.js";
+import { addTask } from "../lib-ts/context/task-tracker.js";
+
+function main(): void {
+  const payload = loadHookInput();
+  if (!payload) return;
+  if (!validateHookEvent(payload, "PostToolUse", "TaskCreate")) return;
+
+  const toolInput = getToolInput(payload);
+  if (!toolInput) return;
+  if (checkSkipPersistence(payload, "task_create_capture")) return;
+
+  const projectRoot = getProjectRoot(payload.cwd);
+  const sessionId = payload.session_id ?? "unknown";
+
+  const state = getContextBySessionId(sessionId, projectRoot);
+  if (!state) {
+    logDebug("task_create_capture", `No context for session ${sessionId}`);
+    return;
+  }
+
+  const subject = toolInput.subject as string | undefined;
+  if (!subject) {
+    logWarn("task_create_capture", "TaskCreate missing subject field");
+    return;
+  }
+
+  const description = (toolInput.description as string) ?? "";
+  const activeForm = (toolInput.activeForm as string) ?? "";
+
+  const task = addTask(state.id, subject, description, activeForm, sessionId, projectRoot);
+  if (task) {
+    logInfo("task_create_capture", `Persisted task ${task.id}: ${subject}`);
+  } else {
+    logError("task_create_capture", `Failed to persist task: ${subject}`);
+  }
+}
+
+runHook(main, "task_create_capture");

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env bun
+/**
+ * PostToolUse:TaskUpdate hook: Persist Claude's TaskUpdate calls to state.json.
+ * Maps Claude's ephemeral task IDs to persistent aiw-N IDs.
+ */
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import {
+  checkSkipPersistence, getToolInput, loadHookInput, logDebug,
+  logError as _logError, logInfo, logWarn, runHook, validateHookEvent,
+} from "../lib-ts/base/hook-utils.js";
+import { getContextBySessionId } from "../lib-ts/context/context-store.js";
+import { deleteTask, updateTask } from "../lib-ts/context/task-tracker.js";
+
+function main(): void {
+  const payload = loadHookInput();
+  if (!payload) return;
+  if (!validateHookEvent(payload, "PostToolUse", "TaskUpdate")) return;
+
+  const toolInput = getToolInput(payload);
+  if (!toolInput) return;
+  if (checkSkipPersistence(payload, "task_update_capture")) return;
+
+  const projectRoot = getProjectRoot(payload.cwd);
+  const sessionId = payload.session_id ?? "unknown";
+
+  const state = getContextBySessionId(sessionId, projectRoot);
+  if (!state) {
+    logDebug("task_update_capture", `No context for session ${sessionId}`);
+    return;
+  }
+
+  const claudeTaskId = toolInput.taskId as string | undefined;
+  if (!claudeTaskId) {
+    logWarn("task_update_capture", "TaskUpdate missing taskId");
+    return;
+  }
+
+  // Map Claude's ephemeral ID to persistent ID
+  const metadata = (toolInput.metadata ?? {}) as Record<string, any>;
+  const persistentId = (metadata.persistent_id as string) ?? `aiw-${claudeTaskId}`;
+
+  const status = toolInput.status as string | undefined;
+
+  if (status === "deleted") {
+    const ok = deleteTask(state.id, persistentId, projectRoot);
+    if (ok) {
+      logInfo("task_update_capture", `Deleted task ${persistentId}`);
+    } else {
+      logWarn("task_update_capture", `Task ${persistentId} not found for deletion`);
+    }
+
+    return;
+  }
+
+  if (status) {
+    const opts: Record<string, any> = { status };
+    if (metadata.evidence) opts.evidence = metadata.evidence;
+    if (metadata.work_summary) opts.work_summary = metadata.work_summary;
+    if (metadata.files_changed && Array.isArray(metadata.files_changed)) {
+      opts.files_changed = metadata.files_changed;
+    }
+
+    opts.session_id = sessionId;
+
+    const ok = updateTask(state.id, persistentId, opts, projectRoot);
+    if (ok) {
+      logInfo("task_update_capture", `Updated task ${persistentId} → ${status}`);
+    } else {
+      logWarn("task_update_capture", `Task ${persistentId} not found for update`);
+    }
+  }
+}
+
+runHook(main, "task_update_capture");

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+/**
+ * UserPromptSubmit hook: Context enforcement — ensures every prompt belongs
+ * to a tracked context. The most complex shared hook.
+ *
+ * Uses emitContext() for output — context text is passed via hookSpecificOutput JSON.
+ * Catches BlockRequest and exits with code 2 to block the prompt.
+ */
+import { getProjectRoot } from "../lib-ts/base/constants.js";
+import {
+  emitContext, hookLog, loadHookInput, logBlocking, logDebug, logDiagnostic as _logDiagnostic, logInfo, logWarn as _logWarn, runHookAsync,
+} from "../lib-ts/base/hook-utils.js";
+import { BlockRequest, determineContext } from "../lib-ts/context/context-selector.js";
+import {
+  bindSession, getContextBySessionId, maybeActivate, saveState,
+} from "../lib-ts/context/context-store.js";
+
+async function asyncMain(): Promise<void> {
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const prompt = (payload as any).prompt as string | undefined;
+  const sessionId = payload.session_id;
+  const permissionMode = payload.permission_mode ?? "";
+  const projectRoot = getProjectRoot(payload.cwd);
+
+  if (!sessionId) {
+    logDebug("user_prompt_submit", "No session_id");
+    return;
+  }
+
+  const outputs: string[] = [];
+
+  // Check if session is already bound to a context
+  const existingCtx = getContextBySessionId(sessionId, projectRoot);
+
+  if (existingCtx) {
+    // Returning user — context already bound (stderr: false to avoid "hook error" display)
+    try {
+      maybeActivate(existingCtx.id, permissionMode, projectRoot, "user_prompt_submit");
+    } catch (error) {
+      hookLog("warn", "user_prompt_submit", `maybeActivate failed (non-critical): ${error}`, { stderr: false });
+    }
+
+    hookLog("debug", "user_prompt_submit", `Session bound to ${existingCtx.id}`, { stderr: false });
+  } else if (prompt) {
+    // First prompt — need to determine context
+    try {
+      const [contextId, method, outputText] = await determineContext(prompt, sessionId, projectRoot);
+
+      if (contextId) {
+        bindSession(contextId, sessionId, projectRoot);
+        maybeActivate(contextId, permissionMode, projectRoot, "user_prompt_submit");
+
+        // Clear handoff_path after binding (prevents re-injection)
+        const state = getContextBySessionId(sessionId, projectRoot);
+        if (state && state.handoff_path) {
+          state.handoff_path = null;
+          saveState(state.id, state, projectRoot);
+        }
+
+        logInfo("user_prompt_submit", `Context ${contextId} via ${method}`);
+      }
+
+      if (outputText) {
+        outputs.push(outputText);
+      }
+    } catch (error) {
+      if (error instanceof BlockRequest) {
+        logBlocking("user_prompt_submit", (error as Error).message);
+        process.exit(2); // Block the prompt
+      }
+
+      throw error; // Re-throw unexpected errors
+    }
+  }
+
+  if (outputs.length > 0) {
+    emitContext(outputs.join("\n\n"));
+  }
+}
+
+runHookAsync(asyncMain, "user_prompt_submit");

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

@@ -0,0 +1,318 @@
+# Shared TypeScript Library
+
+**Location:** `_shared/lib-ts/` — cross-method infrastructure used by ALL templates.
+
+**One import gets you started:**
+```typescript
+import { loadHookInput, runHook, logInfo, emitContext } from "../lib-ts/base/hook-utils.js";
+```
+
+`hook-utils.ts` re-exports the most-used functions from `logger.ts`, `constants.ts`, and `context-store.ts`. Start here. Only import from deeper modules when you need specific capabilities.
+
+**Import direction:** Hooks --> method lib --> `_shared/lib-ts/`. Never the reverse.
+
+---
+
+## Critical Rules
+
+These cause silent failures or UI noise when violated:
+
+- **Entry point:** Every hook MUST use `runHook()` or `runHookAsync()` — never bare `main()` or `process.exit()`
+- **stdout is sacred:** Only hook JSON output goes to stdout. Use logger functions for diagnostics, never `console.log()` or `print()`
+- **stderr is opt-in:** `logDebug/logInfo/logWarn/logError` write to file only. Use `logBlocking()` when you NEED stderr visibility
+- **Catch non-critical errors locally:** Uncaught errors bubble to `runHook` which writes to stderr, showing "hook error" in the UI even on exit 0
+- **No reverse imports:** Never import from method lib (e.g., `_cc-native/lib/`) into shared lib
+
+---
+
+## Hook Skeleton
+
+Copy this for new hooks:
+
+```typescript
+#!/usr/bin/env bun
+import { loadHookInput, runHook, logDebug, logInfo, emitContext } from "../lib-ts/base/hook-utils.js";
+
+function main(): void {
+  const payload = loadHookInput();
+  if (!payload) return;
+
+  const sessionId = payload.session_id;
+  if (!sessionId) return;
+
+  // Your hook logic here...
+
+  emitContext("Context visible to Claude");
+}
+
+runHook(main, "my_hook_name");
+```
+
+For async hooks (AI inference, network calls):
+
+```typescript
+import { runHookAsync } from "../lib-ts/base/hook-utils.js";
+
+async function asyncMain(): Promise<void> {
+  // await something...
+}
+
+runHookAsync(asyncMain, "my_async_hook");
+```
+
+---
+
+## Logging
+
+All logging goes to `_output/hook-log.jsonl`. stderr visibility is opt-in.
+
+| Tier | Function | Visible in UI? | Use When |
+|------|----------|---------------|----------|
+| File-only | `logDebug()` / `logInfo()` / `logWarn()` / `logError()` | No | 99% of logging: diagnostics, state changes, non-critical errors |
+| Blocking | `logBlocking()` | Yes (stderr) | The hook found a real problem the user or Claude must see |
+| Unhandled | `logHookError()` | Yes (stderr) | Reserved for `runHook` crash handler — do not call directly |
+| Terminal | `eprint()` | Yes (raw stderr) | Usage help, progress indicators — not logged to JSONL |
+
+```typescript
+import { logDebug, logInfo, logWarn, logBlocking } from "../lib-ts/base/hook-utils.js";
+
+logInfo("my_hook", "Session started");           // file only
+logWarn("my_hook", `Fallback used: ${reason}`);   // file only
+logBlocking("my_hook", "Critical: state corrupt"); // shows in UI
+```
+
+---
+
+## Hook Output — Three Communication Channels
+
+Hooks have three channels back to the session. Pick the right one:
+
+| Want to... | Function | Who sees it |
+|------------|----------|-------------|
+| Block tool + return message | `emitContextAndBlock(context, reason)` | Claude + user (denial reason prominent) |
+| Return message, don't block | `emitContext(context)` | Claude + user (in transcript) |
+| Log only (diagnostics) | `logInfo()` / `logWarn()` / etc. | Nobody in session — file only |
+
+**There is no way to show something to the user but hide it from Claude, or vice versa.** Both `emitContext()` and `emitContextAndBlock()` produce output visible to both.
+
+### Channel 1: Block + Context (PreToolUse only)
+
+```typescript
+emitContextAndBlock(
+  "Detailed feedback Claude sees",    // additionalContext
+  "Short reason for the block"        // permissionDecisionReason
+);
+// No SystemExit needed — permissionDecision:"deny" with exit 0 is sufficient.
+// runHookAsync drains stdout before exit to ensure pipe consumers receive the JSON.
+```
+
+The tool call is **prevented from executing**. Only works for PreToolUse hooks.
+
+### Channel 2: Non-blocking Context (any hook event)
+
+```typescript
+emitContext("Information added to Claude's context");
+```
+
+The tool call / session continues normally. Works for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Notification, SubagentStart.
+
+### Channel 3: Log-only (diagnostics)
+
+```typescript
+logInfo("my_hook", "Processing started");     // File only
+logWarn("my_hook", `Fallback used: ${why}`);  // File only
+```
+
+Nobody in the session sees this. Written to `_output/hook-log.jsonl` for debugging.
+
+### Hook Output Logging
+
+Both `emitContext()` and `emitContextAndBlock()` automatically log their output to `_output/hook-log.jsonl` as `HOOK_OUTPUT` entries. This captures exactly what was sent to Claude via stdout, closing the visibility gap where the agent sees injected context the user doesn't.
+
+- **Log level:** `info` — visible unless `HOOK_LOG_LEVEL=warn`
+- **`msg` field:** Scannable summary: `HOOK_OUTPUT [context] 842 chars` or `HOOK_OUTPUT [block] 340 chars, reason="..."`
+- **`data` field:** Full payload including `additionalContext` and `blockReason` (for blocks)
+- **Controlled by:** Existing `HOOK_LOG_LEVEL` and `HOOK_LOG_DISABLE` env vars
+- **No hook changes needed:** Logging happens inside the emit functions themselves
+
+### Exit codes and JSON
+
+| Exit Code | JSON Parsed? | Effect |
+|-----------|-------------|--------|
+| **0** | Yes | Normal — `hookSpecificOutput` processed |
+| **2** | No | Blocking error — JSON ignored, stderr fed to Claude |
+| **Other** | No | Non-blocking error — stderr shown in verbose mode |
+
+You cannot mix exit 2 with JSON decisions. Pick one: exit 0 + JSON, or exit 2 + stderr.
+
+### hookSpecificOutput fields by event type
+
+| Event | `additionalContext` | `permissionDecision` | `permissionDecisionReason` | Other |
+|-------|:--:|:--:|:--:|-------|
+| **PreToolUse** | Y | Y (allow/deny/ask) | Y | `updatedInput` |
+| **PostToolUse** | Y | - | - | `updatedMCPToolOutput` (MCP only) |
+| **UserPromptSubmit** | Y | - | - | top-level `decision: "block"` |
+| **SessionStart** | Y | - | - | — |
+| **Notification** | Y | - | - | — |
+| **SubagentStart** | Y | - | - | — |
+| **Stop** | - | - | - | top-level `decision`, `reason` |
+| **SessionEnd** | - | - | - | — |
+
+**Invalid fields cause silent rejection of the entire output.** No error, no feedback. Conversely, **missing `hookEventName` also causes silent rejection** — see "Hook API: Critical Learnings" below.
+
+### Special case: fileSuggestion
+
+The `fileSuggestion` settings command is NOT a hook — it uses a different protocol. It outputs a plain JSON array to stdout (e.g., `console.log(JSON.stringify(paths))`). Do not use `emitContext()` for fileSuggestion.
+
+---
+
+## Hook API: Critical Learnings (Verified 2026-02-11)
+
+These findings were verified through systematic testing. They document Claude Code's actual behavior, which sometimes differs from what the docs suggest.
+
+### hookEventName is REQUIRED (CC 2.1.39+)
+
+Claude Code validates `hookSpecificOutput` using a Zod discriminated union keyed on `hookEventName`. If this field is missing:
+
+- The entire hook output is silently rejected — no error, no feedback
+- `permissionDecision: "deny"` is never processed
+- The hook appears to "not work" even though it runs successfully
+
+**You don't need to handle this manually.** `emitContext()` and `emitContextAndBlock()` auto-detect `hookEventName` from the stdin payload (via `_lastHookEvent`, set by `loadHookInput()`/`runHook()`). This works because hooks are synchronous single-process executions — each `bun` process has its own memory, so there's no concurrency risk between sessions.
+
+**If auto-detection fails** (e.g., `loadHookInput()` wasn't called), `hookEventName` is omitted and the output will be silently rejected. This is why `runHook()`/`runHookAsync()` is mandatory — it calls `_earlyReadInput()` first, guaranteeing `_lastHookEvent` is populated.
+
+### Exit Code Behavior (Tested)
+
+| Exit Code | JSON Parsed? | Blocks Tool? | What Claude Sees | Tested? |
+|-----------|-------------|-------------|------------------|---------|
+| **0** + deny JSON | Yes | Yes (PreToolUse only) | `additionalContext` + denial reason | Yes |
+| **0** + context JSON | Yes | No | `additionalContext` in transcript | Yes |
+| **1** | No | No | stderr in verbose mode only | Yes |
+| **2** | No | Yes (any event) | stderr fed as system-reminder | Yes |
+
+**Key insight:** Exit 0 + `permissionDecision: "deny"` is the correct way to block a tool. Exit 2 is a blunt instrument — it ignores your JSON and feeds raw stderr to Claude. Use exit 0 + deny for clean blocking with structured feedback.
+
+### ExitPlanMode: Not Special-Cased
+
+Early testing suggested ExitPlanMode was "immune" to PreToolUse deny. **This was wrong.** The actual issue was missing `hookEventName` — the Zod validator silently rejected the deny output.
+
+**With `hookEventName` included:**
+- PreToolUse `permissionDecision: "deny"` (exit 0) → **blocks ExitPlanMode**, no dialog appears, session stays in plan mode
+- `emitContextAndBlock()` handles this automatically via auto-detection
+
+**Without `hookEventName` (the bug):**
+- Deny silently rejected → dialog appeared → looked like ExitPlanMode was special-cased
+- Exit 2 also appeared to "not work" for PreToolUse (JSON was ignored as expected, but the blocking was via stderr, not deny)
+- PostToolUse with exit 2 appeared to work because it used stderr (not JSON), bypassing the Zod issue
+
+**Lesson:** When a hook output seems to be "silently ignored," check the JSON schema first. The Zod validator rejects malformed output without any error message.
+
+### Debugging Checklist
+
+When a hook's deny/context isn't working:
+
+1. **Is `hookEventName` in the JSON output?** Check `_output/hook-log.jsonl` for `HOOK_OUTPUT` entries
+2. **Is the hook using `runHook()`/`runHookAsync()`?** Required for auto-detection
+3. **Is `loadHookInput()` called before `emitContext()`?** It populates `_lastHookEvent`
+4. **Is the exit code 0?** Exit 1/2 cause JSON to be ignored
+5. **Are there extra fields in `hookSpecificOutput`?** Invalid fields cause silent rejection of the entire output
+
+---
+
+## Context Store
+
+2-layer CRUD: per-context `state.json` + global `_output/index.json`.
+
+```typescript
+import { getContextBySessionId, bindSession, maybeActivate, saveState } from "../lib-ts/context/context-store.js";
+
+const state = getContextBySessionId(sessionId, projectRoot);
+if (state) {
+  // ALWAYS wrap non-critical operations — uncaught errors become UI "hook error"
+  try {
+    maybeActivate(state.id, permissionMode, projectRoot, "hook_name");
+  } catch (e) {
+    logWarn("hook_name", `maybeActivate failed (non-critical): ${e}`);
+  }
+}
+```
+
+**Valid modes:** `idle` | `has_plan` | `has_handoff` | `active`
+
+Transitions: `idle`/`has_plan`/`has_handoff` --> `active` (via `maybeActivate`). `active` --> `has_plan`/`has_handoff` (via `session_end`).
+
+---
+
+## Module Reference
+
+Use this table to find the right file. Read the source for full API details.
+
+### `base/` — Core Infrastructure
+
+| File | Purpose | Key Exports |
+|------|---------|-------------|
+| `hook-utils.ts` | Hook lifecycle, stdin parsing, output emit, re-exports | `runHook`, `runHookAsync`, `loadHookInput`, `emitContext`, `emitContextAndBlock`, `logDebug`...`logBlocking` |
+| `logger.ts` | JSONL logging engine | `hookLog`, `logDebug`, `logInfo`, `logWarn`, `logError`, `logBlocking`, `logHookError`, `logDiagnostic` |
+| `constants.ts` | Path resolution, limits | `getProjectRoot()`, `getContextDir()`, `MAX_FILE_SIZE` |
+| `atomic-write.ts` | Crash-safe file writes | `atomicWriteFileSync()` |
+| `state-io.ts` | State serialization with mode migration | `readState()`, `writeState()` |
+| `inference.ts` | Claude CLI subprocess calls | `inferText()` |
+| `utils.ts` | Formatting, ID generation | `nowIso()`, `generateContextId()`, `slugify()` |
+| `git-state.ts` | Git snapshot | `captureGitState()` |
+| `subprocess-utils.ts` | Recursive call guard | `isInternalCall()` |
+| `stop-words.ts` | Word list for ID generation | Used by `utils.ts` internally |
+
+### `context/` — Context State Management
+
+| File | Purpose | Key Exports |
+|------|---------|-------------|
+| `context-store.ts` | CRUD for context state + index | `getContextBySessionId`, `bindSession`, `maybeActivate`, `saveState`, `createContext` |
+| `context-selector.ts` | Route prompts to contexts | `determineContext()`, `BlockRequest` |
+| `context-formatter.ts` | Display formatting | `formatContextSummary()` |
+| `plan-manager.ts` | Plan lifecycle (archive, hash, sign) | `archivePlan()`, `computePlanHash()` |
+| `task-tracker.ts` | Task CRUD on state.json | `addTask()`, `updateTask()`, `getTasks()` |
+
+### `handoff/` and `templates/`
+
+| File | Purpose | Key Exports |
+|------|---------|-------------|
+| `handoff/document-generator.ts` | Handoff document generation | `generateHandoffDocument()` |
+| `templates/formatters.ts` | Display constants, mode maps, icons | `MODE_MAP`, `STATUS_ICONS` |
+| `templates/plan-context.ts` | Plan evaluation templates | `PLAN_EVALUATION_REMINDER` |
+
+### Root
+
+| File | Purpose |
+|------|---------|
+| `types.ts` | All shared types: `Mode`, `ContextState`, `Task`, `HookInput`, `HookOutput` |
+
+---
+
+## Shared Hooks (`_shared/hooks-ts/`)
+
+These run for ALL templates. Method-specific hooks live in `_{method}/hooks/`.
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `user_prompt_submit.ts` | UserPromptSubmit | Context enforcement — binds prompts to tracked contexts |
+| `context_monitor.ts` | PostToolUse:* | Context window tracking, handoff warnings at 30/20/10% |
+| `session_start.ts` | SessionStart | Restores plan/handoff context after `/clear` or compaction |
+| `session_end.ts` | SessionEnd | Stages `active` --> `has_plan`/`has_handoff` for next session |
+| `archive_plan.ts` | PreToolUse:ExitPlanMode | Archives plan file before accept/reject decision |
+| `pre_compact.ts` | PreToolUse:Compact | Pre-compaction state snapshot |
+| `task_create_capture.ts` | PostToolUse:TaskCreate | Persists task creation to context state |
+| `task_update_capture.ts` | PostToolUse:TaskUpdate | Persists task updates to context state |
+| `file-suggestion.ts` | PostToolUse:Write | Suggests file organization improvements |
+
+---
+
+## Environment Variables
+
+| Variable | Effect |
+|----------|--------|
+| `CLAUDE_PROJECT_DIR` | Override project root detection |
+| `HOOK_LOG_DISABLE=1` | Disable all file logging |
+| `HOOK_LOG_LEVEL=warn` | Minimum log level (default: `debug`) |
+| `HOOK_ERROR_LOG_DISABLE=1` | Legacy alias for `HOOK_LOG_DISABLE` |
+| `_CC_INTERNAL=1` | Marks subprocess calls (checked by `isInternalCall()`) |