@tekmidian/pai 0.5.2 → 0.5.3

package/ARCHITECTURE.md

@@ -500,6 +500,90 @@ PAI implements six Luhmann-inspired operations on the vault's dual representatio
 
 ---
 
+## Hook System
+
+PAI ships a comprehensive set of lifecycle hooks that integrate with Claude Code's hook events. Hooks are TypeScript source files (`src/hooks/ts/`) compiled to `.mjs` modules and deployed to `~/.claude/Hooks/`.
+
+### Hook Architecture
+
+```
+Claude Code Event
+    │
+    ├── stdin: JSON { session_id, transcript_path, cwd, hook_event_name }
+    │
+    ├── Hook Process (.mjs)
+    │       ├── Reads stdin for context
+    │       ├── Performs side effects (file writes, notifications)
+    │       └── Writes stdout (injected as <system-reminder> into conversation)
+    │
+    └── stderr: diagnostic logs (visible in Claude Code's hook output)
+```
+
+**Key constraint:** Not all hook events support stdout injection. `SessionStart` does. `PreCompact` does not. This matters for context preservation.
+
+### Hook Inventory
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `load-core-context.mjs` | SessionStart | Loads PAI skill system and core configuration |
+| `load-project-context.mjs` | SessionStart | Detects project, loads notes dir, TODO, session note |
+| `initialize-session.mjs` | SessionStart | Creates numbered session note, registers in PAI registry |
+| `post-compact-inject.mjs` | SessionStart (compact) | Reads saved state and injects into post-compaction context |
+| `security-validator.mjs` | PreToolUse (Bash) | Validates shell commands against security rules |
+| `capture-all-events.mjs` | All events | Observability — logs every hook event to session timeline |
+| `context-compression-hook.mjs` | PreCompact | Extracts session state, saves checkpoint, writes temp file for relay |
+| `capture-tool-output.mjs` | PostToolUse | Records tool inputs/outputs for observability dashboard |
+| `update-tab-on-action.mjs` | PostToolUse | Updates terminal tab title based on current activity |
+| `sync-todo-to-md.mjs` | PostToolUse (TodoWrite) | Syncs Claude's internal TODO list to `Notes/TODO.md` |
+| `cleanup-session-files.mjs` | UserPromptSubmit | Cleans up stale temp files between prompts |
+| `update-tab-titles.mjs` | UserPromptSubmit | Sets terminal tab title from session context |
+| `stop-hook.mjs` | Stop | Writes work items to session note, sends notification |
+| `capture-session-summary.mjs` | SessionEnd | Final session summary written to session note |
+| `subagent-stop-hook.mjs` | SubagentStop | Captures sub-agent completion for observability |
+
+### Context Preservation Relay
+
+The most critical hook interaction is the PreCompact → SessionStart relay that preserves context across compaction:
+
+```
+PreCompact fires (context-compression-hook.mjs)
+    │
+    ├── Reads transcript JSONL from stdin { transcript_path }
+    ├── Extracts: recent user messages, work summaries, files modified, captures
+    ├── Writes checkpoint to session note (persistent)
+    ├── Writes injection payload to /tmp/pai-compact-state-{session_id}.txt
+    └── Sends notification (WhatsApp or ntfy.sh)
+
+    ⬇ Claude Code runs compaction (conversation is summarized)
+
+SessionStart(compact) fires (post-compact-inject.mjs)
+    │
+    ├── Reads /tmp/pai-compact-state-{session_id}.txt
+    ├── Outputs content to stdout → injected into post-compaction context
+    └── Deletes temp file (one-shot relay)
+```
+
+**Why the relay?** PreCompact hooks cannot inject into the conversation (stdout is ignored by Claude Code for this event). SessionStart hooks can. The temp file bridges the gap.
+
+### Building Hooks
+
+```bash
+bun run build              # Builds everything including hooks
+node scripts/build-hooks.mjs   # Build hooks only
+```
+
+The build script compiles each `.ts` hook to a self-contained `.mjs` module using `tsx` bundling, then copies them to the configured hooks directory (`~/.claude/Hooks/` by default).
+
+### Adding a New Hook
+
+1. Create the TypeScript source in the appropriate `src/hooks/ts/<event>/` directory
+2. Read stdin for `HookInput` JSON (session_id, transcript_path, cwd, hook_event_name)
+3. Use stderr for diagnostics, stdout only if the event supports injection
+4. Register the hook in `~/.claude/settings.json` under the appropriate event with the correct matcher
+5. Run `bun run build` to compile and deploy
+
+---
+
 ## Templates
 
 PAI ships three templates used during setup and customizable for your workflow.

package/README.md

@@ -60,6 +60,44 @@ Claude finds the setup skill, checks your system, runs the interactive wizard, a
 
 ---
 
+## Context Preservation
+
+When Claude's context window fills up, it compresses the conversation. Without PAI, everything from before that point is lost — Claude forgets what it was working on, what files it changed, and what you asked for.
+
+PAI intercepts this compression with a two-stage relay:
+
+1. **Before compression** — PAI extracts session state from the conversation transcript: your recent requests, work summaries, files modified, and current task context. This gets saved to a checkpoint.
+
+2. **After compression** — PAI reads that checkpoint and injects it back into Claude's fresh context. Claude picks up exactly where it left off.
+
+This happens automatically. You don't need to do anything — just keep working, and PAI handles the continuity.
+
+### What Gets Preserved
+
+- Your last 3 requests (so Claude knows what you were asking)
+- Work summaries and captured context
+- Files modified during the session
+- Current working directory and task state
+- Session note checkpoints (persistent — survive even full restarts)
+
+### Session Lifecycle Hooks
+
+PAI runs hooks at every stage of a Claude Code session:
+
+| Event | What PAI Does |
+|-------|--------------|
+| **Session Start** | Loads project context, detects which project you're in, creates a session note |
+| **User Prompt** | Cleans up temp files, updates terminal tab titles |
+| **Pre-Compact** | Saves session state checkpoint, sends notification |
+| **Post-Compact** | Injects preserved state back into Claude's context |
+| **Tool Use** | Captures tool outputs for observability |
+| **Session End** | Summarizes work done, finalizes session note |
+| **Stop** | Writes work items to session note, sends notification |
+
+All hooks are TypeScript compiled to `.mjs` modules. They run as separate processes, communicate via stdin (JSON input from Claude Code) and stdout (context injection back into the conversation).
+
+---
+
 ## Auto-Compact Context Window
 
 Claude Code can automatically compact your context window when it fills up, preventing session interruptions mid-task. PAI's statusline shows you at a glance whether auto-compact is active.

package/dist/cli/index.mjs

@@ -4142,9 +4142,18 @@ function mergeEnv(settings, incoming, report) {
 	return changed;
 }
 /**
+* Strip file extension from a command basename for extension-agnostic dedup.
+* This ensures that e.g. "context-compression-hook.ts" and
+* "context-compression-hook.mjs" are treated as the same hook.
+*/
+function commandStem(cmd) {
+	return (cmd.split("/").pop() ?? cmd).replace(/\.(mjs|ts|js|sh)$/, "");
+}
+/**
 * Collect every command string already registered for a given hookType.
-* Stores both the full command and the basename for flexible matching
-* (handles ${PAI_DIR}/Hooks/foo.sh vs /Users/.../Hooks/foo.sh).
+* Stores full command, basename, AND extension-stripped stem for flexible
+* matching (handles ${PAI_DIR}/Hooks/foo.sh vs /Users/.../Hooks/foo.sh,
+* and .ts → .mjs migrations).
 */
 function existingCommandsForHookType(rules) {
 	const cmds = /* @__PURE__ */ new Set();
@@ -4152,11 +4161,30 @@ function existingCommandsForHookType(rules) {
 		cmds.add(entry.command);
 		const base = entry.command.split("/").pop();
 		if (base) cmds.add(base);
+		cmds.add(commandStem(entry.command));
 	}
 	return cmds;
 }
 /**
+* Find and remove an existing rule whose command has the same stem
+* (extension-agnostic) as the incoming command. Returns true if a
+* replacement was made. This handles .ts → .mjs migrations cleanly.
+*/
+function replaceStaleHook(existingRules, incomingStem, incomingCommand, incomingMatcher) {
+	for (let i = 0; i < existingRules.length; i++) {
+		const rule = existingRules[i];
+		for (let j = 0; j < rule.hooks.length; j++) if (commandStem(rule.hooks[j].command) === incomingStem && rule.hooks[j].command !== incomingCommand) {
+			rule.hooks[j].command = incomingCommand;
+			if (incomingMatcher !== void 0) rule.matcher = incomingMatcher;
+			return true;
+		}
+	}
+	return false;
+}
+/**
 * Merge hooks — append entries, deduplicating by command string.
+* Extension-agnostic: a .mjs hook replaces an existing .ts hook with the
+* same stem, ensuring clean .ts → .mjs migrations without duplicates.
 */
 function mergeHooks(settings, incoming, report) {
 	let changed = false;
@@ -4164,12 +4192,21 @@ function mergeHooks(settings, incoming, report) {
 	for (const entry of incoming) {
 		const { hookType, matcher, command } = entry;
 		const existingRules = Array.isArray(hooksSection[hookType]) ? hooksSection[hookType] : [];
-		const existingCmds = existingCommandsForHookType(existingRules);
 		const basename = command.split("/").pop() ?? command;
+		const stem = commandStem(command);
+		const existingCmds = existingCommandsForHookType(existingRules);
 		if (existingCmds.has(command) || existingCmds.has(basename)) {
 			report.push(chalk.dim(`  Skipped: hook ${hookType} → ${basename} already registered`));
 			continue;
 		}
+		if (existingCmds.has(stem)) {
+			if (replaceStaleHook(existingRules, stem, command, matcher)) {
+				hooksSection[hookType] = existingRules;
+				report.push(chalk.yellow(`  Upgraded: hook ${hookType} → ${basename} (replaced stale extension)`));
+				changed = true;
+				continue;
+			}
+		}
 		const newRule = { hooks: [{
 			type: "command",
 			command
@@ -4874,6 +4911,7 @@ async function stepTsHooks(rl) {
 	line$1();
 	let copiedCount = 0;
 	let skippedCount = 0;
+	let cleanedCount = 0;
 	for (const filename of allFiles) {
 		const src = join(distHooksDir, filename);
 		const dest = join(hooksTarget, filename);
@@ -4882,6 +4920,12 @@ async function stepTsHooks(rl) {
 			if (srcContent === readFileSync(dest, "utf-8")) {
 				console.log(c.dim(`  Unchanged: ${filename}`));
 				skippedCount++;
+				const staleTsPath = join(hooksTarget, filename.replace(/\.mjs$/, ".ts"));
+				if (existsSync(staleTsPath)) {
+					unlinkSync(staleTsPath);
+					console.log(c.ok(`Cleaned up stale: ${filename.replace(/\.mjs$/, ".ts")}`));
+					cleanedCount++;
+				}
 				continue;
 			}
 		}
@@ -4889,11 +4933,22 @@ async function stepTsHooks(rl) {
 		chmodSync(dest, 493);
 		console.log(c.ok(`Installed: ${filename}`));
 		copiedCount++;
+		const staleTsPath = join(hooksTarget, filename.replace(/\.mjs$/, ".ts"));
+		if (existsSync(staleTsPath)) {
+			unlinkSync(staleTsPath);
+			console.log(c.ok(`Cleaned up stale: ${filename.replace(/\.mjs$/, ".ts")}`));
+			cleanedCount++;
+		}
 	}
 	line$1();
-	if (copiedCount > 0) console.log(c.ok(`${copiedCount} hook(s) installed, ${skippedCount} unchanged.`));
-	else console.log(c.dim(`  All ${skippedCount} hook(s) already up-to-date.`));
-	return copiedCount > 0;
+	if (copiedCount > 0 || cleanedCount > 0) {
+		const parts = [];
+		if (copiedCount > 0) parts.push(`${copiedCount} hook(s) installed`);
+		if (skippedCount > 0) parts.push(`${skippedCount} unchanged`);
+		if (cleanedCount > 0) parts.push(`${cleanedCount} stale .ts file(s) cleaned up`);
+		console.log(c.ok(parts.join(", ") + "."));
+	} else console.log(c.dim(`  All ${skippedCount} hook(s) already up-to-date.`));
+	return copiedCount > 0 || cleanedCount > 0;
 }
 /**
 * Step 8b: Prompt for the DA (Digital Assistant) name
@@ -4952,6 +5007,11 @@ async function stepSettings(rl, daName) {
 				hookType: "SessionStart",
 				command: "${PAI_DIR}/Hooks/capture-all-events.mjs --event-type SessionStart"
 			},
+			{
+				hookType: "SessionStart",
+				matcher: "compact",
+				command: "${PAI_DIR}/Hooks/post-compact-inject.mjs"
+			},
 			{
 				hookType: "UserPromptSubmit",
 				command: "${PAI_DIR}/Hooks/cleanup-session-files.mjs"