@rkarim08/sia 1.0.0

package/src/hooks/handlers/stop.ts

@@ -0,0 +1,128 @@
+// Module: stop — Stop hook handler
+//
+// Fires when Claude Code is about to exit. Reads the recent segment of
+// the transcript (JSONL), checks whether sia_note was already called,
+// and scans assistant messages for uncaptured knowledge patterns.
+
+import { readFileSync } from "node:fs";
+import type { SiaDb } from "@/graph/db-interface";
+import { insertEntity } from "@/graph/entities";
+import { detectKnowledgePatterns } from "@/hooks/extractors/pattern-detector";
+import type { HookEvent, HookHandler, HookResponse } from "@/hooks/types";
+
+/** How many lines from the tail of the transcript to scan. */
+const RECENT_SEGMENT_SIZE = 50;
+
+/** Shape of a single JSONL transcript line. */
+interface TranscriptLine {
+	role?: string;
+	content?: string;
+	tool_calls?: Array<{ name?: string; input?: Record<string, unknown> }>;
+}
+
+/**
+ * Read and parse the recent segment of a JSONL transcript file.
+ * Returns the last RECENT_SEGMENT_SIZE parsed lines.
+ */
+function readRecentTranscript(path: string): TranscriptLine[] {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch {
+		return [];
+	}
+
+	const allLines = raw.split("\n").filter((l) => l.trim().length > 0);
+	const recentLines = allLines.slice(-RECENT_SEGMENT_SIZE);
+
+	const parsed: TranscriptLine[] = [];
+	for (const line of recentLines) {
+		try {
+			parsed.push(JSON.parse(line) as TranscriptLine);
+		} catch {
+			// Skip malformed lines
+		}
+	}
+
+	return parsed;
+}
+
+/**
+ * Check if sia_note was called in the recent transcript segment.
+ */
+function hasSiaNoteCall(lines: TranscriptLine[]): boolean {
+	for (const line of lines) {
+		if (!line.tool_calls) continue;
+		for (const call of line.tool_calls) {
+			if (call.name === "sia_note") return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Collect assistant message content from transcript lines.
+ */
+function collectAssistantContent(lines: TranscriptLine[]): string[] {
+	const contents: string[] = [];
+	for (const line of lines) {
+		if (line.role === "assistant" && typeof line.content === "string") {
+			contents.push(line.content);
+		}
+	}
+	return contents;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Stop hook handler bound to the given graph database.
+ * Scans the transcript tail for uncaptured knowledge patterns.
+ */
+export function createStopHandler(db: SiaDb): HookHandler {
+	return async (event: HookEvent): Promise<HookResponse> => {
+		const lines = readRecentTranscript(event.transcript_path);
+
+		// If transcript is empty or unreadable, nothing to do
+		if (lines.length === 0) {
+			return { status: "no_new_knowledge", nodes_created: 0 };
+		}
+
+		// If sia_note was already called, knowledge was captured inline
+		if (hasSiaNoteCall(lines)) {
+			return { status: "already_captured", nodes_created: 0 };
+		}
+
+		// Scan assistant messages for knowledge patterns
+		const assistantContents = collectAssistantContent(lines);
+		if (assistantContents.length === 0) {
+			return { status: "no_new_knowledge", nodes_created: 0 };
+		}
+
+		let nodesCreated = 0;
+
+		for (const content of assistantContents) {
+			const patterns = detectKnowledgePatterns(content);
+			for (const p of patterns) {
+				await insertEntity(db, {
+					type: p.type,
+					name: `${p.type}: ${p.content.slice(0, 60)}`,
+					content: p.content,
+					summary: `${p.type} detected in session ${event.session_id}`,
+					confidence: p.confidence,
+					extraction_method: "hook:stop:pattern",
+					source_episode: event.session_id,
+				});
+				nodesCreated++;
+			}
+		}
+
+		if (nodesCreated === 0) {
+			return { status: "no_new_knowledge", nodes_created: 0 };
+		}
+
+		return { status: "processed", nodes_created: nodesCreated };
+	};
+}

package/src/hooks/handlers/user-prompt-submit.ts

@@ -0,0 +1,68 @@
+// Module: user-prompt-submit — UserPromptSubmit hook handler
+//
+// When a user submits a prompt:
+// - Always creates a UserPrompt node in the graph.
+// - If the prompt contains correction/preference patterns (e.g. "use X instead
+//   of Y", "don't use Z", "always do X"), also creates a UserDecision node
+//   with trust_tier 1.
+
+import type { SiaDb } from "@/graph/db-interface";
+import { insertEntity } from "@/graph/entities";
+import type { SiaConfig } from "@/shared/config";
+
+export interface UserPromptEvent {
+	session_id: string;
+	prompt: string;
+}
+
+const CORRECTION_PATTERNS = [
+	/use\s+\S+\s+instead\s+of/i,
+	/don't use/i,
+	/do not use/i,
+	/switch to/i,
+	/prefer\s+\S+/i,
+	/always\s+\S+/i,
+	/never\s+\S+/i,
+];
+
+export async function handleUserPromptSubmit(
+	db: SiaDb,
+	event: UserPromptEvent,
+	_config: SiaConfig,
+): Promise<{ nodesCreated: number }> {
+	if (!event.prompt?.trim()) return { nodesCreated: 0 };
+
+	let nodesCreated = 0;
+
+	// Always create a UserPrompt node
+	await insertEntity(db, {
+		type: "Concept",
+		name: event.prompt.slice(0, 50),
+		content: event.prompt,
+		summary: event.prompt.slice(0, 80),
+		tags: JSON.stringify(["user-prompt"]),
+		kind: "UserPrompt",
+		session_id: event.session_id,
+	});
+	nodesCreated++;
+
+	// Check for correction/preference patterns → UserDecision
+	for (const pattern of CORRECTION_PATTERNS) {
+		if (pattern.test(event.prompt)) {
+			await insertEntity(db, {
+				type: "Decision",
+				name: event.prompt.slice(0, 50),
+				content: event.prompt,
+				summary: event.prompt.slice(0, 80),
+				tags: JSON.stringify(["user-preference"]),
+				trust_tier: 1,
+				kind: "UserDecision",
+				session_id: event.session_id,
+			});
+			nodesCreated++;
+			break; // Only one UserDecision per prompt
+		}
+	}
+
+	return { nodesCreated };
+}

package/src/hooks/plugin-branch-switch.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+// Plugin hook: Branch switch detection
+//
+// Triggered by PostToolUse on Bash commands matching git checkout/switch.
+// Saves a snapshot of the current graph under the old branch name,
+// then restores (or creates) a snapshot for the new branch.
+
+import { resolveRepoHash } from "@/capture/hook";
+import { openGraphDb } from "@/graph/semantic-db";
+import { createBranchSnapshot, restoreBranchSnapshot } from "@/graph/snapshots";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+import { currentBranch, currentCommit, previousBranch } from "@/shared/git-utils";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		if (!input.trim()) return;
+
+		const event = parsePluginHookEvent(input);
+
+		if (event.tool_name !== "Bash") return;
+
+		const command = event.tool_input?.command as string | undefined;
+		if (!command) return;
+
+		const isCheckout = /^git\s+(checkout|switch)\b/.test(command);
+		if (!isCheckout) return;
+
+		const cwd = event.cwd || process.cwd();
+		const repoHash = resolveRepoHash(cwd);
+		const db = openGraphDb(repoHash);
+
+		try {
+			const newBranch = currentBranch(cwd);
+			const newCommit = currentCommit(cwd);
+
+			if (!newBranch) return; // detached HEAD — nothing to snapshot
+
+			// Save current graph state under the OLD branch name before restoring.
+			// Note: since this is a PostToolUse hook, checkout has already completed.
+			// We cannot recover the old branch's true commit hash — newCommit (the
+			// current HEAD) is stored as an approximation. This is acceptable because
+			// the snapshot data (nodes/edges) is the authoritative state, not the hash.
+			const oldBranch = previousBranch(cwd);
+			if (oldBranch && oldBranch !== newBranch) {
+				await createBranchSnapshot(db, oldBranch, newCommit);
+				process.stderr.write(`sia: saved graph snapshot for branch '${oldBranch}'\n`);
+			}
+
+			// Restore snapshot for the new branch, or create an initial one
+			const restored = await restoreBranchSnapshot(db, newBranch);
+
+			if (restored) {
+				process.stderr.write(`sia: restored graph snapshot for branch '${newBranch}'\n`);
+			} else {
+				await createBranchSnapshot(db, newBranch, newCommit);
+				process.stderr.write(`sia: created initial graph snapshot for branch '${newBranch}'\n`);
+			}
+		} finally {
+			await db.close();
+		}
+	} catch (err) {
+		process.stderr.write(`sia branch-switch hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/plugin-common.ts

@@ -0,0 +1,47 @@
+// Module: plugin-common — Shared utilities for plugin hook wrappers
+//
+// Claude Code hook events arrive as JSON on stdin. This module parses
+// them into SIA's HookEvent type.
+
+import type { HookEvent } from "./types";
+
+/**
+ * Parse a Claude Code hook event from a JSON string.
+ * Validates required fields and returns a typed HookEvent.
+ */
+export function parsePluginHookEvent(input: string): HookEvent {
+	let parsed: Record<string, unknown>;
+	try {
+		parsed = JSON.parse(input);
+	} catch {
+		throw new Error("Invalid JSON in hook event");
+	}
+
+	if (!parsed.session_id || typeof parsed.session_id !== "string") {
+		throw new Error("Missing required field: session_id");
+	}
+
+	return {
+		session_id: parsed.session_id as string,
+		transcript_path: (parsed.transcript_path as string) ?? "",
+		cwd: (parsed.cwd as string) ?? process.cwd(),
+		hook_event_name: (parsed.hook_event_name as string) ?? "unknown",
+		tool_name: parsed.tool_name as string | undefined,
+		tool_input: parsed.tool_input as Record<string, unknown> | undefined,
+		tool_response: parsed.tool_response,
+		tool_use_id: parsed.tool_use_id as string | undefined,
+		source: parsed.source as HookEvent["source"],
+		reason: parsed.reason as HookEvent["reason"],
+	};
+}
+
+/**
+ * Read all of stdin as a string.
+ */
+export async function readStdin(): Promise<string> {
+	const chunks: Buffer[] = [];
+	for await (const chunk of process.stdin) {
+		chunks.push(chunk as Buffer);
+	}
+	return Buffer.concat(chunks).toString("utf-8");
+}

package/src/hooks/plugin-post-compact.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+
+// Plugin hook wrapper: PostCompact
+//
+// Reads Claude Code PostCompact event from stdin. Lightweight handler
+// that logs compaction coverage info for observability.
+
+import { createPostCompactHandler } from "@/hooks/handlers/post-compact";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		if (!input.trim()) {
+			process.exit(0);
+		}
+
+		const event = parsePluginHookEvent(input);
+		const handler = createPostCompactHandler();
+		const result = await handler(event);
+		process.stdout.write(JSON.stringify(result));
+	} catch (err) {
+		process.stderr.write(`sia PostCompact hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/plugin-post-tool-use.ts

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+// Plugin hook wrapper: PostToolUse
+//
+// Reads Claude Code hook event from stdin, delegates to the
+// existing PostToolUse handler, writes response to stdout.
+
+import { resolveRepoHash } from "@/capture/hook";
+import { openGraphDb } from "@/graph/semantic-db";
+import { createPostToolUseHandler } from "@/hooks/handlers/post-tool-use";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		if (!input.trim()) {
+			process.exit(0);
+		}
+
+		const event = parsePluginHookEvent(input);
+		const cwd = event.cwd || process.cwd();
+		const repoHash = resolveRepoHash(cwd);
+		const db = openGraphDb(repoHash);
+
+		try {
+			const handler = createPostToolUseHandler(db);
+			const result = await handler(event);
+			process.stdout.write(JSON.stringify(result));
+		} finally {
+			await db.close();
+		}
+	} catch (err) {
+		// Hooks must not crash Claude Code — fail silently
+		process.stderr.write(`sia PostToolUse hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/plugin-pre-compact.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+// Plugin hook wrapper: PreCompact
+//
+// Reads Claude Code PreCompact event from stdin, scans transcript
+// tail for unextracted knowledge before compaction discards detail.
+
+import { resolveRepoHash } from "@/capture/hook";
+import { openGraphDb } from "@/graph/semantic-db";
+import { createPreCompactHandler } from "@/hooks/handlers/pre-compact";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		if (!input.trim()) {
+			process.exit(0);
+		}
+
+		const event = parsePluginHookEvent(input);
+		const cwd = event.cwd || process.cwd();
+		const repoHash = resolveRepoHash(cwd);
+		const db = openGraphDb(repoHash);
+
+		try {
+			const handler = createPreCompactHandler(db);
+			const result = await handler(event);
+			process.stdout.write(JSON.stringify(result));
+		} finally {
+			await db.close();
+		}
+	} catch (err) {
+		process.stderr.write(`sia PreCompact hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/plugin-session-end.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+// Plugin hook wrapper: SessionEnd
+//
+// Reads Claude Code SessionEnd event from stdin, records session
+// statistics and updates ended_at timestamp in the graph.
+
+import { resolveRepoHash } from "@/capture/hook";
+import { openGraphDb } from "@/graph/semantic-db";
+import { createSessionEndHandler } from "@/hooks/handlers/session-end";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		if (!input.trim()) {
+			process.exit(0);
+		}
+
+		const event = parsePluginHookEvent(input);
+		const cwd = event.cwd || process.cwd();
+		const repoHash = resolveRepoHash(cwd);
+		const db = openGraphDb(repoHash);
+
+		try {
+			const handler = createSessionEndHandler(db);
+			const result = await handler(event);
+			process.stdout.write(JSON.stringify(result));
+		} finally {
+			await db.close();
+		}
+	} catch (err) {
+		process.stderr.write(`sia SessionEnd hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/plugin-session-start.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env bun
+// Plugin hook wrapper: SessionStart
+//
+// Injects recent decisions, conventions, and known bugs as context
+// at the beginning of a Claude Code session.
+
+import { resolveRepoHash } from "@/capture/hook";
+import { openGraphDb } from "@/graph/semantic-db";
+import { buildSessionContext, formatSessionContext } from "@/hooks/handlers/session-start";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+import type { HookEvent } from "@/hooks/types";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		// SessionStart may be invoked without event data on initial install
+		let event: HookEvent;
+		if (input.trim()) {
+			event = parsePluginHookEvent(input);
+		} else {
+			event = {
+				session_id: "unknown",
+				cwd: process.cwd(),
+				transcript_path: "",
+				hook_event_name: "SessionStart",
+			};
+		}
+
+		const cwd = event.cwd || process.cwd();
+		const repoHash = resolveRepoHash(cwd);
+		const db = openGraphDb(repoHash);
+
+		try {
+			const isResume = event.source === "resume";
+			const context = await buildSessionContext(db, cwd, isResume);
+			let formatted = formatSessionContext(context);
+
+			// Load previous session subgraph if resuming
+			if (isResume && event.session_id && event.session_id !== "unknown") {
+				try {
+					const { loadSubgraph } = await import("@/graph/session-resume");
+					const resume = await loadSubgraph(db, event.session_id);
+					if (resume) {
+						const subgraph = JSON.parse(resume.subgraph_json);
+						const entities = subgraph.entities as Array<{
+							name: string;
+							summary: string;
+							type: string;
+						}>;
+						if (entities.length > 0) {
+							formatted += "\n## Previous Session Context\n";
+							formatted += "These entities were active in your previous session:\n\n";
+							for (const entity of entities.slice(0, 10)) {
+								formatted += `- **${entity.name}** (${entity.type}): ${entity.summary || "no summary"}\n`;
+							}
+						}
+					}
+				} catch (err) {
+					process.stderr.write(`sia: session resume load failed (non-fatal): ${err}\n`);
+				}
+			}
+
+			// SessionStart hooks output to stdout — Claude Code injects
+			// the output as context into the conversation.
+			process.stdout.write(formatted);
+		} finally {
+			await db.close();
+		}
+	} catch (err) {
+		process.stderr.write(`sia SessionStart hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/plugin-stop.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env bun
+// Plugin hook wrapper: Stop
+//
+// Reads Claude Code Stop event from stdin, runs pattern detection
+// on recent transcript, captures uncaptured knowledge.
+
+import { resolveRepoHash } from "@/capture/hook";
+import { openGraphDb } from "@/graph/semantic-db";
+import { createStopHandler } from "@/hooks/handlers/stop";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		if (!input.trim()) {
+			process.exit(0);
+		}
+
+		const event = parsePluginHookEvent(input);
+		const cwd = event.cwd || process.cwd();
+		const repoHash = resolveRepoHash(cwd);
+		const db = openGraphDb(repoHash);
+
+		try {
+			const handler = createStopHandler(db);
+			const result = await handler(event);
+			process.stdout.write(JSON.stringify(result));
+
+			// Save session subgraph for resume
+			try {
+				const { saveSubgraph } = await import("@/graph/session-resume");
+
+				const recentNodes = await db.execute(
+					`SELECT id, type, name, summary, kind, trust_tier, file_paths
+					 FROM graph_nodes
+					 WHERE session_id = ? OR last_accessed > ?
+					 ORDER BY last_accessed DESC
+					 LIMIT 20`,
+					[event.session_id, Date.now() - 3600000],
+				);
+
+				const subgraph = {
+					entities: recentNodes.rows,
+					timestamp: Date.now(),
+				};
+
+				await saveSubgraph(db, event.session_id, JSON.stringify(subgraph), null, 0);
+				process.stderr.write("sia: saved session subgraph for resume\n");
+			} catch (err) {
+				process.stderr.write(`sia: session save failed (non-fatal): ${err}\n`);
+			}
+		} finally {
+			await db.close();
+		}
+	} catch (err) {
+		process.stderr.write(`sia Stop hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/plugin-user-prompt-submit.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+// Plugin hook wrapper: UserPromptSubmit
+//
+// Reads Claude Code UserPromptSubmit event from stdin, creates a
+// UserPrompt node and optionally a UserDecision if the prompt
+// contains correction/preference patterns.
+
+import { resolveRepoHash } from "@/capture/hook";
+import { openGraphDb } from "@/graph/semantic-db";
+import { handleUserPromptSubmit } from "@/hooks/handlers/user-prompt-submit";
+import { parsePluginHookEvent, readStdin } from "@/hooks/plugin-common";
+import { getConfig } from "@/shared/config";
+
+async function main() {
+	try {
+		const input = await readStdin();
+		if (!input.trim()) {
+			process.exit(0);
+		}
+
+		const event = parsePluginHookEvent(input);
+		const cwd = event.cwd || process.cwd();
+		const repoHash = resolveRepoHash(cwd);
+		const db = openGraphDb(repoHash);
+
+		try {
+			const config = getConfig();
+			const prompt = (event.tool_input?.prompt as string) ?? "";
+			const result = await handleUserPromptSubmit(
+				db,
+				{
+					session_id: event.session_id,
+					prompt,
+				},
+				config,
+			);
+			process.stdout.write(JSON.stringify(result));
+		} finally {
+			await db.close();
+		}
+	} catch (err) {
+		process.stderr.write(`sia UserPromptSubmit hook error: ${err}\n`);
+		process.exit(0);
+	}
+}
+
+main();

package/src/hooks/types.ts

@@ -0,0 +1,43 @@
+// src/hooks/types.ts — Shared types for the hook system
+
+/** JSON envelope received from Claude Code hook events */
+export interface HookEvent {
+	session_id: string;
+	transcript_path: string;
+	cwd: string;
+	hook_event_name: string;
+	permission_mode?: string;
+
+	// Tool-specific (PostToolUse, PreToolUse)
+	tool_name?: string;
+	tool_input?: Record<string, unknown>;
+	tool_response?: unknown;
+	tool_use_id?: string;
+
+	// Compaction-specific
+	trigger?: "auto" | "manual";
+	compact_summary?: string;
+	custom_instructions?: string;
+
+	// Session-specific
+	source?: "startup" | "resume" | "clear";
+	reason?: "exit" | "sigint" | "error";
+}
+
+/** Standard response from a hook handler */
+export interface HookResponse {
+	status:
+		| "processed"
+		| "skipped"
+		| "error"
+		| "already_captured"
+		| "needs_semantic_analysis"
+		| "no_new_knowledge";
+	nodes_created?: number;
+	edges_created?: number;
+	error?: string;
+	[key: string]: unknown;
+}
+
+/** Handler function signature */
+export type HookHandler = (event: HookEvent) => Promise<HookResponse>;