@os-eco/overstory-cli 0.6.1

package/src/commands/hooks.test.ts

@@ -0,0 +1,458 @@
+/**
+ * Tests for overstory hooks install/uninstall/status command.
+ *
+ * Uses real temp directories and real filesystem (no mocks needed).
+ * Each test gets an isolated temp directory with minimal .overstory/
+ * and .claude/ scaffolding.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
+import { hooksCommand, mergeHooksByEventType } from "./hooks.ts";
+
+let tempDir: string;
+const originalCwd = process.cwd();
+
+/** Orchestrator hooks content for .overstory/hooks.json. */
+const SAMPLE_HOOKS = {
+	hooks: {
+		SessionStart: [
+			{
+				matcher: "",
+				hooks: [{ type: "command", command: "overstory prime --agent orchestrator" }],
+			},
+		],
+		Stop: [
+			{
+				matcher: "",
+				hooks: [{ type: "command", command: "overstory log session-end --agent orchestrator" }],
+			},
+		],
+	},
+};
+
+/** Capture stdout.write output during a function call. */
+async function captureStdout(fn: () => Promise<void>): Promise<string> {
+	const chunks: string[] = [];
+	const originalWrite = process.stdout.write;
+	process.stdout.write = ((chunk: string) => {
+		chunks.push(chunk);
+		return true;
+	}) as typeof process.stdout.write;
+	try {
+		await fn();
+	} finally {
+		process.stdout.write = originalWrite;
+	}
+	return chunks.join("");
+}
+
+beforeEach(async () => {
+	process.chdir(originalCwd);
+	tempDir = await realpath(await createTempGitRepo());
+
+	// Create minimal .overstory/ with config.yaml
+	const overstoryDir = join(tempDir, ".overstory");
+	await mkdir(overstoryDir, { recursive: true });
+	await Bun.write(
+		join(overstoryDir, "config.yaml"),
+		["project:", "  name: test-project", `  root: ${tempDir}`, "  canonicalBranch: main"].join(
+			"\n",
+		),
+	);
+
+	process.chdir(tempDir);
+});
+
+afterEach(async () => {
+	process.chdir(originalCwd);
+	await cleanupTempDir(tempDir);
+});
+
+describe("hooksCommand help", () => {
+	test("--help outputs help text", async () => {
+		const output = await captureStdout(() => hooksCommand(["--help"]));
+		expect(output).toContain("overstory hooks");
+		expect(output).toContain("install");
+		expect(output).toContain("uninstall");
+		expect(output).toContain("status");
+	});
+
+	test("empty args outputs help text", async () => {
+		const output = await captureStdout(() => hooksCommand([]));
+		expect(output).toContain("overstory hooks");
+	});
+
+	test("unknown subcommand throws ValidationError", async () => {
+		await expect(hooksCommand(["frobnicate"])).rejects.toThrow(ValidationError);
+	});
+});
+
+describe("hooks install", () => {
+	test("installs hooks from .overstory/hooks.json to .claude/settings.local.json", async () => {
+		// Write source hooks
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install"]));
+
+		// Verify target file was created
+		const targetPath = join(tempDir, ".claude", "settings.local.json");
+		const content = await Bun.file(targetPath).text();
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		expect(parsed.hooks).toBeDefined();
+		expect(content).toContain("overstory prime");
+	});
+
+	test("preserves existing non-hooks keys in settings.local.json", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		// Write existing settings.local.json with non-hooks content
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ env: { SOME_VAR: "1" } }, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install"]));
+
+		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		expect(parsed.hooks).toBeDefined();
+		expect(parsed.env).toEqual({ SOME_VAR: "1" });
+	});
+
+	test("warns when hooks already exist without --force", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: { old: "hooks" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["install"]));
+		expect(output).toContain("already present");
+		expect(output).toContain("--force");
+
+		// Verify hooks were NOT overwritten
+		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
+		expect(content).toContain("old");
+	});
+
+	test("--force merges existing hooks (not overwrites)", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		const existingSettings = {
+			hooks: {
+				UserInput: [
+					{
+						matcher: "",
+						hooks: [{ type: "command", command: "echo user-hook" }],
+					},
+				],
+			},
+		};
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify(existingSettings, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install", "--force"]));
+
+		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
+		// Existing user hook is preserved
+		expect(content).toContain("user-hook");
+		// Overstory hooks are added
+		expect(content).toContain("overstory prime");
+	});
+
+	test("throws when .overstory/hooks.json does not exist", async () => {
+		await expect(hooksCommand(["install"])).rejects.toThrow(ValidationError);
+	});
+
+	test("writes JSON with trailing newline", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install"]));
+
+		const content = await Bun.file(join(tempDir, ".claude", "settings.local.json")).text();
+		expect(content.endsWith("\n")).toBe(true);
+	});
+});
+
+describe("hooks uninstall", () => {
+	test("removes hooks-only settings.local.json file entirely", async () => {
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: { some: "hooks" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("Removed");
+
+		const exists = await Bun.file(join(claudeDir, "settings.local.json")).exists();
+		expect(exists).toBe(false);
+	});
+
+	test("preserves non-hooks keys when uninstalling", async () => {
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: { some: "hooks" }, env: { KEY: "val" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("preserved other settings");
+
+		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		expect(parsed.hooks).toBeUndefined();
+		expect(parsed.env).toEqual({ KEY: "val" });
+	});
+
+	test("handles missing settings.local.json gracefully", async () => {
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("nothing to uninstall");
+	});
+
+	test("handles settings.local.json with no hooks key", async () => {
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ env: { KEY: "val" } }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["uninstall"]));
+		expect(output).toContain("No hooks found");
+	});
+});
+
+describe("hooks install merge behavior", () => {
+	test("--force merges overstory hooks into existing user hooks", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		const existingSettings = {
+			hooks: {
+				PreToolUse: [
+					{
+						matcher: "Write",
+						hooks: [{ type: "command", command: "echo user-write-hook" }],
+					},
+				],
+			},
+		};
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify(existingSettings, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install", "--force"]));
+
+		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
+		const parsed = JSON.parse(content) as { hooks: Record<string, unknown[]> };
+		// User's PreToolUse hook preserved
+		expect(content).toContain("user-write-hook");
+		// Overstory's SessionStart hook added
+		expect(content).toContain("overstory prime");
+		// Both event types present
+		expect(parsed.hooks.PreToolUse).toBeDefined();
+		expect(parsed.hooks.SessionStart).toBeDefined();
+	});
+
+	test("--force deduplicates identical entries", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+
+		// First install
+		await captureStdout(() => hooksCommand(["install"]));
+
+		// Second install with --force (same hooks again)
+		await captureStdout(() => hooksCommand(["install", "--force"]));
+
+		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
+		const parsed = JSON.parse(content) as { hooks: Record<string, unknown[]> };
+
+		// SessionStart should have exactly 1 entry (no duplicate)
+		expect(parsed.hooks.SessionStart?.length).toBe(1);
+		// Stop should have exactly 1 entry (no duplicate)
+		expect(parsed.hooks.Stop?.length).toBe(1);
+	});
+
+	test("--force preserves existing event types not in source", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		const existingSettings = {
+			hooks: {
+				Notification: [
+					{
+						matcher: "",
+						hooks: [{ type: "command", command: "echo notification-hook" }],
+					},
+				],
+			},
+		};
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify(existingSettings, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install", "--force"]));
+
+		const content = await Bun.file(join(claudeDir, "settings.local.json")).text();
+		const parsed = JSON.parse(content) as { hooks: Record<string, unknown[]> };
+		// Custom event type preserved
+		expect(parsed.hooks.Notification).toBeDefined();
+		expect(content).toContain("notification-hook");
+		// Overstory hooks also present
+		expect(parsed.hooks.SessionStart).toBeDefined();
+		expect(parsed.hooks.Stop).toBeDefined();
+	});
+
+	test("first install without existing hooks works unchanged", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		await captureStdout(() => hooksCommand(["install"]));
+
+		const content = await Bun.file(join(tempDir, ".claude", "settings.local.json")).text();
+		const parsed = JSON.parse(content) as { hooks: Record<string, unknown[]> };
+		expect(parsed.hooks.SessionStart).toBeDefined();
+		expect(parsed.hooks.Stop).toBeDefined();
+		expect(content).toContain("overstory prime");
+	});
+
+	describe("mergeHooksByEventType unit tests", () => {
+		test("copies existing event types not in incoming", () => {
+			const existing = {
+				UserInput: [{ matcher: "", hooks: [{ type: "command", command: "echo a" }] }],
+			};
+			const incoming = {
+				SessionStart: [{ matcher: "", hooks: [{ type: "command", command: "echo b" }] }],
+			};
+			const result = mergeHooksByEventType(existing, incoming);
+			expect(result.UserInput).toBeDefined();
+			expect(result.SessionStart).toBeDefined();
+		});
+
+		test("appends non-duplicate incoming entries to existing event type", () => {
+			const existing = {
+				PreToolUse: [{ matcher: "Read", hooks: [{ type: "command", command: "echo read" }] }],
+			};
+			const incoming = {
+				PreToolUse: [{ matcher: "Write", hooks: [{ type: "command", command: "echo write" }] }],
+			};
+			const result = mergeHooksByEventType(existing, incoming);
+			expect(result.PreToolUse?.length).toBe(2);
+		});
+
+		test("does not add duplicate entries (same matcher + same commands)", () => {
+			const entry = { matcher: "", hooks: [{ type: "command", command: "echo dupe" }] };
+			const existing = { PreToolUse: [entry] };
+			const incoming = { PreToolUse: [entry] };
+			const result = mergeHooksByEventType(existing, incoming);
+			expect(result.PreToolUse?.length).toBe(1);
+		});
+
+		test("adds entry with same matcher but different commands", () => {
+			const existing = {
+				PreToolUse: [{ matcher: "", hooks: [{ type: "command", command: "echo a" }] }],
+			};
+			const incoming = {
+				PreToolUse: [{ matcher: "", hooks: [{ type: "command", command: "echo b" }] }],
+			};
+			const result = mergeHooksByEventType(existing, incoming);
+			expect(result.PreToolUse?.length).toBe(2);
+		});
+	});
+});
+
+describe("hooks status", () => {
+	test("reports source missing when .overstory/hooks.json does not exist", async () => {
+		const output = await captureStdout(() => hooksCommand(["status"]));
+		expect(output).toContain("missing");
+	});
+
+	test("reports installed:false when no hooks in .claude/", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["status"]));
+		expect(output).toContain("present");
+		expect(output).toContain("no");
+		expect(output).toContain("overstory hooks install");
+	});
+
+	test("reports installed:true when hooks present in .claude/", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const claudeDir = join(tempDir, ".claude");
+		await mkdir(claudeDir, { recursive: true });
+		await Bun.write(
+			join(claudeDir, "settings.local.json"),
+			`${JSON.stringify({ hooks: {} }, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["status"]));
+		expect(output).toContain("yes");
+	});
+
+	test("--json outputs correct fields", async () => {
+		await Bun.write(
+			join(tempDir, ".overstory", "hooks.json"),
+			`${JSON.stringify(SAMPLE_HOOKS, null, "\t")}\n`,
+		);
+
+		const output = await captureStdout(() => hooksCommand(["status", "--json"]));
+		const parsed = JSON.parse(output) as Record<string, unknown>;
+		expect(parsed.sourceExists).toBe(true);
+		expect(parsed.installed).toBe(false);
+	});
+});

package/src/commands/hooks.ts

@@ -0,0 +1,253 @@
+/**
+ * CLI command: overstory hooks install|uninstall|status
+ *
+ * Manages orchestrator hooks in .claude/settings.local.json.
+ * Hooks are sourced from .overstory/hooks.json (generated by overstory init).
+ *
+ * This keeps the canonical hook configuration in .overstory/ while placing
+ * a minimal copy in .claude/ only when the user explicitly opts in.
+ * Running `overstory init` alone does NOT modify .claude/ — the user must
+ * run `overstory hooks install` as a separate step.
+ */
+
+import { mkdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+
+interface HookEntry {
+	matcher: string;
+	hooks: ReadonlyArray<{ type: string; command: string }>;
+}
+
+function isDuplicateEntry(a: HookEntry, b: HookEntry): boolean {
+	if (a.matcher !== b.matcher) return false;
+	if (a.hooks.length !== b.hooks.length) return false;
+	return a.hooks.every((cmd, i) => {
+		const bCmd = b.hooks[i];
+		return bCmd !== undefined && bCmd.type === cmd.type && bCmd.command === cmd.command;
+	});
+}
+
+/**
+ * Merge two hook maps by event type, deduplicating entries with identical
+ * matcher + command list pairs. Preserves all existing entries and appends
+ * only non-duplicate incoming entries per event type.
+ */
+export function mergeHooksByEventType(
+	existing: Record<string, unknown[]>,
+	incoming: Record<string, unknown[]>,
+): Record<string, unknown[]> {
+	const merged: Record<string, unknown[]> = { ...existing };
+
+	for (const [eventType, incomingEntries] of Object.entries(incoming)) {
+		if (!(eventType in merged)) {
+			merged[eventType] = incomingEntries;
+			continue;
+		}
+
+		const existingEntries = merged[eventType] ?? [];
+		const toAdd: unknown[] = [];
+
+		for (const entry of incomingEntries) {
+			const incomingEntry = entry as HookEntry;
+			const isDupe = existingEntries.some((e) => isDuplicateEntry(e as HookEntry, incomingEntry));
+			if (!isDupe) {
+				toAdd.push(entry);
+			}
+		}
+
+		merged[eventType] = [...existingEntries, ...toAdd];
+	}
+
+	return merged;
+}
+
+const HOOKS_HELP = `overstory hooks — Manage orchestrator hooks
+
+Usage: overstory hooks <subcommand>
+
+Subcommands:
+  install                  Install orchestrator hooks to .claude/settings.local.json
+  uninstall                Remove orchestrator hooks from .claude/settings.local.json
+  status                   Check if hooks are installed
+
+Options:
+  --force                  Overwrite existing hooks in .claude/settings.local.json
+  --json                   Output as JSON
+  --help, -h               Show this help
+
+Hooks source: .overstory/hooks.json (generated by overstory init)
+Hooks target: .claude/settings.local.json (read by Claude Code)`;
+
+/**
+ * Install orchestrator hooks from .overstory/hooks.json to .claude/settings.local.json.
+ *
+ * Reads the canonical hook config from .overstory/hooks.json and writes it to
+ * .claude/settings.local.json where Claude Code discovers it. Preserves any
+ * existing non-hooks keys in the target file.
+ */
+async function installHooks(args: string[]): Promise<void> {
+	const force = args.includes("--force");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	// Read source hooks from .overstory/hooks.json
+	const sourcePath = join(projectRoot, ".overstory", "hooks.json");
+	const sourceFile = Bun.file(sourcePath);
+	if (!(await sourceFile.exists())) {
+		throw new ValidationError("No hooks.json found in .overstory/. Run 'overstory init' first.", {
+			field: "source",
+		});
+	}
+
+	const sourceContent = await sourceFile.text();
+	const sourceHooks = JSON.parse(sourceContent) as Record<string, unknown>;
+
+	// Check target .claude/settings.local.json
+	const targetDir = join(projectRoot, ".claude");
+	const targetPath = join(targetDir, "settings.local.json");
+	const targetFile = Bun.file(targetPath);
+
+	let targetConfig: Record<string, unknown> = {};
+	if (await targetFile.exists()) {
+		const existingContent = await targetFile.text();
+		const existing = JSON.parse(existingContent) as Record<string, unknown>;
+
+		if (existing.hooks && !force) {
+			process.stdout.write(
+				"Hooks already present in .claude/settings.local.json\nUse --force to overwrite.\n",
+			);
+			return;
+		}
+
+		// Preserve non-hooks keys (e.g., env settings)
+		targetConfig = existing;
+	}
+
+	// Merge: set hooks from source, preserve other keys
+	const existingHooks = targetConfig.hooks as Record<string, unknown[]> | undefined;
+	const incomingHooks = sourceHooks.hooks as Record<string, unknown[]>;
+	targetConfig.hooks = existingHooks
+		? mergeHooksByEventType(existingHooks, incomingHooks)
+		: incomingHooks;
+
+	// Write
+	await mkdir(targetDir, { recursive: true });
+	await Bun.write(targetPath, `${JSON.stringify(targetConfig, null, "\t")}\n`);
+
+	process.stdout.write("\u2713 Installed orchestrator hooks to .claude/settings.local.json\n");
+	process.stdout.write("  Source: .overstory/hooks.json\n");
+}
+
+/**
+ * Remove orchestrator hooks from .claude/settings.local.json.
+ *
+ * If hooks were the only content, removes the file entirely.
+ * Otherwise, preserves other keys and only removes the hooks key.
+ */
+async function uninstallHooks(_args: string[]): Promise<void> {
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const targetPath = join(projectRoot, ".claude", "settings.local.json");
+	const targetFile = Bun.file(targetPath);
+
+	if (!(await targetFile.exists())) {
+		process.stdout.write("No .claude/settings.local.json found \u2014 nothing to uninstall.\n");
+		return;
+	}
+
+	const content = await targetFile.text();
+	const parsed = JSON.parse(content) as Record<string, unknown>;
+
+	if (!parsed.hooks) {
+		process.stdout.write(
+			"No hooks found in .claude/settings.local.json \u2014 nothing to uninstall.\n",
+		);
+		return;
+	}
+
+	// Separate hooks from other settings
+	const { hooks: _hooks, ...rest } = parsed;
+
+	const remainingKeys = Object.keys(rest);
+	if (remainingKeys.length === 0) {
+		await unlink(targetPath);
+		process.stdout.write("\u2713 Removed .claude/settings.local.json (was hooks-only)\n");
+	} else {
+		await Bun.write(targetPath, `${JSON.stringify(rest, null, "\t")}\n`);
+		process.stdout.write(
+			"\u2713 Removed hooks from .claude/settings.local.json (preserved other settings)\n",
+		);
+	}
+}
+
+/**
+ * Show hooks installation status.
+ */
+async function statusHooks(args: string[]): Promise<void> {
+	const json = args.includes("--json");
+	const cwd = process.cwd();
+	const config = await loadConfig(cwd);
+	const projectRoot = config.project.root;
+
+	const sourcePath = join(projectRoot, ".overstory", "hooks.json");
+	const targetPath = join(projectRoot, ".claude", "settings.local.json");
+
+	const sourceExists = await Bun.file(sourcePath).exists();
+	const targetExists = await Bun.file(targetPath).exists();
+
+	let installed = false;
+	if (targetExists) {
+		const content = await Bun.file(targetPath).text();
+		const parsed = JSON.parse(content) as Record<string, unknown>;
+		installed = !!parsed.hooks;
+	}
+
+	if (json) {
+		process.stdout.write(`${JSON.stringify({ sourceExists, installed })}\n`);
+	} else {
+		process.stdout.write(
+			`Hooks source (.overstory/hooks.json): ${sourceExists ? "present" : "missing"}\n`,
+		);
+		process.stdout.write(
+			`Hooks installed (.claude/settings.local.json): ${installed ? "yes" : "no"}\n`,
+		);
+		if (!installed && sourceExists) {
+			process.stdout.write(`\nRun 'overstory hooks install' to install.\n`);
+		}
+	}
+}
+
+/**
+ * Entry point for `overstory hooks <subcommand>`.
+ */
+export async function hooksCommand(args: string[]): Promise<void> {
+	if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+		process.stdout.write(`${HOOKS_HELP}\n`);
+		return;
+	}
+
+	const subcommand = args[0];
+	const subArgs = args.slice(1);
+
+	switch (subcommand) {
+		case "install":
+			await installHooks(subArgs);
+			break;
+		case "uninstall":
+			await uninstallHooks(subArgs);
+			break;
+		case "status":
+			await statusHooks(subArgs);
+			break;
+		default:
+			throw new ValidationError(
+				`Unknown hooks subcommand: ${subcommand}. Run 'overstory hooks --help' for usage.`,
+				{ field: "subcommand", value: subcommand },
+			);
+	}
+}