one-code-extension 0.1.0

package/extensions/hooks/executor.ts

@@ -0,0 +1,132 @@
+/**
+ * Hook command execution — the only file in extensions/hooks that touches
+ * child_process. Everything upstream (matching, payload, envelope, decision)
+ * is pure and tested with a fake executor; this file is tested against real
+ * /bin/sh children.
+ *
+ * pi.exec is deliberately not used: it hardcodes shell:false and gives the
+ * child no stdin, while Claude Code hooks are shell command strings that read
+ * a JSON payload from stdin. (Ported from pi-code's runHookCommand, MIT — see
+ * docs/decisions.md.)
+ *
+ * Hardening carried over:
+ * - absolute /bin/sh, so a repo-local `sh` on PATH can't hijack the hook
+ * - detached:true makes the shell a process-group leader; timeout SIGKILLs
+ *   the negative pid so grandchildren holding the stdio pipes die too —
+ *   otherwise `close` never fires and the promise hangs past the timeout
+ * - setEncoding("utf8") so multi-byte characters can't be split across chunks
+ * - output capped at 1MB per stream
+ * - stdin errors ignored (a hook that exits without reading stdin — `exit 2`
+ *   — would otherwise EPIPE-crash the write)
+ * - timeout clamped under Node's 2^31-1 ms timer overflow, timer unref'd so a
+ *   pending hook can't keep a one-shot `pi -p` process alive
+ */
+
+import { spawn } from "node:child_process";
+
+export interface HookRunResult {
+	/** null when the process was killed (timeout) or never spawned. */
+	exitCode: number | null;
+	timedOut: boolean;
+	/** Set when the child could not be spawned at all. */
+	spawnError?: string;
+	stdout: string;
+	stderr: string;
+	durationMs: number;
+}
+
+export interface HookRunOptions {
+	cwd: string;
+	/** Seconds, Claude Code convention. Clamped to [1, MAX_TIMEOUT_S]. */
+	timeoutSeconds?: number;
+	/** Exposed to the hook as CLAUDE_PROJECT_DIR; defaults to cwd. */
+	projectDir?: string;
+}
+
+const MAX_OUTPUT_BYTES = 1_000_000;
+const DEFAULT_TIMEOUT_S = 60;
+/** Node timers silently fire immediately above 2^31-1 ms. */
+const MAX_TIMEOUT_S = 2_147_483;
+
+export function runHookCommand(command: string, stdinJson: string, opts: HookRunOptions): Promise<HookRunResult> {
+	const timeoutMs = Math.min(Math.max(opts.timeoutSeconds ?? DEFAULT_TIMEOUT_S, 1), MAX_TIMEOUT_S) * 1000;
+	const started = Date.now();
+
+	return new Promise((resolve) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn("/bin/sh", ["-c", command], {
+				cwd: opts.cwd,
+				detached: true,
+				stdio: ["pipe", "pipe", "pipe"],
+				env: { ...process.env, CLAUDE_PROJECT_DIR: opts.projectDir ?? opts.cwd },
+			});
+		} catch (error) {
+			resolve({
+				exitCode: null,
+				timedOut: false,
+				spawnError: error instanceof Error ? error.message : String(error),
+				stdout: "",
+				stderr: "",
+				durationMs: Date.now() - started,
+			});
+			return;
+		}
+		child.unref();
+
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let settled = false;
+
+		const capture = (sink: "stdout" | "stderr") => (chunk: string) => {
+			const current = sink === "stdout" ? stdout : stderr;
+			if (current.length >= MAX_OUTPUT_BYTES) return;
+			const next = current + chunk.slice(0, MAX_OUTPUT_BYTES - current.length);
+			if (sink === "stdout") stdout = next;
+			else stderr = next;
+		};
+		child.stdout?.setEncoding("utf8");
+		child.stderr?.setEncoding("utf8");
+		child.stdout?.on("data", capture("stdout"));
+		child.stderr?.on("data", capture("stderr"));
+
+		const killTree = () => {
+			// Negative pid = the whole process group the detached shell leads.
+			try {
+				if (child.pid) process.kill(-child.pid, "SIGKILL");
+			} catch {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					// Already gone.
+				}
+			}
+		};
+		const timer = setTimeout(() => {
+			timedOut = true;
+			killTree();
+		}, timeoutMs);
+		timer.unref();
+
+		const finish = (result: Omit<HookRunResult, "durationMs">) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve({ ...result, durationMs: Date.now() - started });
+		};
+
+		child.on("error", (error) => {
+			finish({ exitCode: null, timedOut, spawnError: error.message, stdout, stderr });
+		});
+		child.on("close", (code) => {
+			finish({ exitCode: code, timedOut, stdout, stderr });
+		});
+
+		// A hook that never reads stdin (e.g. plain `exit 2`) closes the pipe
+		// early; the resulting EPIPE must not take the extension down.
+		child.stdin?.on("error", () => {});
+		child.stdin?.write(stdinJson);
+		child.stdin?.end();
+	});
+}

package/extensions/hooks/index.ts

@@ -0,0 +1,310 @@
+/**
+ * hooks extension — Claude Code-compatible command hooks.
+ *
+ * Reads CC hook config (user/managed .claude settings always; project/local
+ * after a once-per-config consent — trust.ts; plugin hooks/hooks.json as user
+ * scope), matches CC-style matchers against tool calls and lifecycle events,
+ * runs the commands with the CC stdin/stdout protocol (protocol.ts,
+ * executor.ts), and applies the verdicts.
+ *
+ * Position in package.json pi.extensions is load-bearing: this extension must
+ * run its tool_call handler BEFORE worktree/file-tracker/permissions, so hook
+ * matchers and updatedInput see the tool call as the model produced it, and
+ * everything downstream — including the permission gate, safety floor, and
+ * auto-mode classifier — evaluates the hook-rewritten input (CC semantics).
+ *
+ * A hook can block anything, loaders included (tool_search/skill/
+ * structured_output) — full CC fidelity, the user's config is the user's
+ * choice; see docs/findings.md for the foot-gun note. A hook can never
+ * pre-approve: "allow" is informational and the permission gate still runs.
+ *
+ * pi's emitToolCall has no try/catch around handlers, so every hook dispatch
+ * here is wrapped — a throwing hook fails open, never takes the turn down.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { claudeConfigDir } from "../lib/paths.ts";
+import { appendHookLog, formatDebugLine, hooksDebugEnabled, hooksLogPath } from "./debug.ts";
+import { runHookCommand } from "./executor.ts";
+import { matcherApplies, ccToolName, toolMatchCandidates } from "./matcher.ts";
+import { loadPluginHooks } from "./plugin-hooks.ts";
+import {
+	type CcHookEvent,
+	type HookOutcome,
+	type HookStdinPayload,
+	interpretHookResult,
+} from "./protocol.ts";
+import { type HookCommand, type HooksSource, loadHookSettings } from "./settings.ts";
+import { projectHooksApproved } from "./trust.ts";
+
+interface MatchedHook {
+	source: HooksSource;
+	hook: HookCommand;
+}
+
+export default function hooksExtension(pi: ExtensionAPI) {
+	let stopHookActive = false;
+	let pendingPromptContext: string[] = [];
+
+	const notify = (ctx: ExtensionContext, message: string) => {
+		if (ctx.hasUI) ctx.ui.notify(message, "info");
+		else process.stderr.write(`${message}\n`);
+	};
+
+	/** All hooks for an event across trusted sources, matcher already applied. */
+	const collectHooks = async (
+		ctx: ExtensionContext,
+		event: CcHookEvent,
+		matchValue: { candidates?: string[]; ignoreMatcher?: boolean },
+	): Promise<MatchedHook[]> => {
+		const claudeDir = claudeConfigDir();
+		const loaded = loadHookSettings(claudeDir, ctx.cwd);
+		const pluginSources = loadPluginHooks(claudeDir, loaded.diagnostics);
+		if (hooksDebugEnabled()) {
+			for (const diagnostic of loaded.diagnostics) process.stderr.write(`[hooks] ${diagnostic}\n`);
+		}
+
+		const projectSources = loaded.sources.filter((s) => s.scope === "project" || s.scope === "local");
+		const hasProjectHooks = projectSources.some((s) => s.config[event]?.length);
+		let projectAllowed = true;
+		if (hasProjectHooks) {
+			projectAllowed = await projectHooksApproved(ctx.cwd, projectSources, {
+				hasUI: ctx.hasUI,
+				confirm: (title, message) => ctx.ui.confirm(title, message),
+				notify: (message) => notify(ctx, message),
+			});
+		}
+
+		const sources = [
+			...loaded.sources.filter((s) => s.scope === "user" || s.scope === "managed"),
+			...pluginSources,
+			...(projectAllowed ? projectSources : []),
+		];
+
+		const matched: MatchedHook[] = [];
+		for (const source of sources) {
+			for (const entry of source.config[event] ?? []) {
+				const applies = matchValue.ignoreMatcher || matcherApplies(entry.matcher, matchValue.candidates ?? []);
+				if (!applies) continue;
+				for (const hook of entry.hooks) matched.push({ source, hook });
+			}
+		}
+		return matched;
+	};
+
+	const basePayload = (ctx: ExtensionContext, event: CcHookEvent): HookStdinPayload => ({
+		session_id: ctx.sessionManager.getSessionId(),
+		transcript_path: ctx.sessionManager.getSessionFile() ?? "",
+		cwd: ctx.cwd,
+		hook_event_name: event,
+	});
+
+	/**
+	 * Run every matched hook in parallel (CC runs matching hooks concurrently)
+	 * and merge: first block wins, updatedInput merges in order, contexts and
+	 * systemMessages concatenate. Any throw inside is caught → fail open.
+	 */
+	const dispatch = async (
+		ctx: ExtensionContext,
+		event: CcHookEvent,
+		matchValue: { candidates?: string[]; ignoreMatcher?: boolean },
+		payload: HookStdinPayload,
+	): Promise<HookOutcome> => {
+		const merged: HookOutcome = {};
+		try {
+			const hooks = await collectHooks(ctx, event, matchValue);
+			if (hooks.length === 0) return merged;
+			const stdin = JSON.stringify(payload);
+			const outcomes = await Promise.all(
+				hooks.map(async ({ source, hook }) => {
+					const run = await runHookCommand(hook.command, stdin, {
+						cwd: ctx.cwd,
+						timeoutSeconds: hook.timeout,
+						projectDir: ctx.cwd,
+					});
+					const outcome = interpretHookResult(event, run);
+					const decision = outcome.block ? "block" : outcome.additionalContext ? "context" : run.exitCode === 0 || run.exitCode === 2 ? "allow" : "error";
+					const logEntry = {
+						event,
+						scope: source.pluginName ? `plugin:${source.pluginName}` : source.scope,
+						command: hook.command,
+						decision: decision as "allow" | "block" | "context" | "error",
+						reason: outcome.block?.reason,
+						exitCode: run.exitCode,
+						durationMs: run.durationMs,
+					};
+					if (hooksDebugEnabled()) process.stderr.write(`${formatDebugLine(logEntry)}\n`);
+					if (process.env.CC_HOOKS_DEBUG === "2") {
+						appendHookLog({ ts: new Date().toISOString(), sessionId: payload.session_id, ...logEntry }, hooksLogPath());
+					}
+					return outcome;
+				}),
+			);
+			for (const outcome of outcomes) {
+				merged.block ??= outcome.block;
+				if (outcome.updatedInput) merged.updatedInput = { ...merged.updatedInput, ...outcome.updatedInput };
+				if ("updatedToolResult" in outcome) merged.updatedToolResult = outcome.updatedToolResult;
+				if (outcome.additionalContext) {
+					merged.additionalContext = [merged.additionalContext, outcome.additionalContext].filter(Boolean).join("\n");
+				}
+				if (outcome.systemMessage) {
+					merged.systemMessage = [merged.systemMessage, outcome.systemMessage].filter(Boolean).join("\n");
+				}
+			}
+		} catch (error) {
+			// Fail open: a broken hook pipeline must never take the turn down.
+			if (hooksDebugEnabled()) {
+				process.stderr.write(`[hooks] dispatch error (${event}): ${error instanceof Error ? error.message : error}\n`);
+			}
+		}
+		if (merged.systemMessage) notify(ctx, merged.systemMessage);
+		return merged;
+	};
+
+	/** Hidden custom message the model sees as context, CC's additionalContext. */
+	const injectContext = (text: string, midLoop: boolean) => {
+		const message = { customType: "one-code:hook-context", content: `<hook-additional-context>\n${text}\n</hook-additional-context>`, display: false };
+		try {
+			if (midLoop) pi.sendMessage(message, { deliverAs: "steer" });
+			else pi.sendMessage(message);
+		} catch {
+			try {
+				pi.sendMessage(message);
+			} catch {
+				// No session to speak to; drop the context.
+			}
+		}
+	};
+
+	// ---- PreToolUse ---------------------------------------------------------
+	pi.on("tool_call", async (event, ctx) => {
+		const payload: HookStdinPayload = {
+			...basePayload(ctx, "PreToolUse"),
+			tool_name: ccToolName(event.toolName),
+			tool_input: event.input as Record<string, unknown>,
+		};
+		const outcome = await dispatch(ctx, "PreToolUse", { candidates: toolMatchCandidates(event.toolName) }, payload);
+		if (outcome.block) return { block: true, reason: `PreToolUse hook: ${outcome.block.reason}` };
+		if (outcome.updatedInput) {
+			// In-place, so worktree/file-tracker/permissions (later in the
+			// extension order) all see the rewritten input — CC applies hook
+			// input updates before permission evaluation.
+			Object.assign(event.input as Record<string, unknown>, outcome.updatedInput);
+		}
+		if (outcome.additionalContext) injectContext(outcome.additionalContext, true);
+		return undefined;
+	});
+
+	// ---- PostToolUse --------------------------------------------------------
+	pi.on("tool_result", async (event, ctx) => {
+		const payload: HookStdinPayload = {
+			...basePayload(ctx, "PostToolUse"),
+			tool_name: ccToolName(event.toolName),
+			tool_input: event.input,
+			tool_response: { content: event.content, is_error: event.isError },
+		};
+		const outcome = await dispatch(ctx, "PostToolUse", { candidates: toolMatchCandidates(event.toolName) }, payload);
+		if (!outcome.block && outcome.updatedToolResult === undefined && !outcome.additionalContext) return undefined;
+
+		let content = [...event.content];
+		let isError = event.isError;
+		if (outcome.updatedToolResult !== undefined) {
+			const replacement = outcome.updatedToolResult;
+			content = [{ type: "text", text: typeof replacement === "string" ? replacement : JSON.stringify(replacement) }];
+		}
+		if (outcome.block) {
+			// The tool already ran; the only channel left is the result the
+			// model reads, so the objection is delivered there (CC feeds
+			// PostToolUse block reasons back to the model the same way).
+			content = [{ type: "text" as const, text: `PostToolUse hook: ${outcome.block.reason}` }, ...content];
+			isError = true;
+		}
+		if (outcome.additionalContext) {
+			content = [...content, { type: "text" as const, text: `<hook-additional-context>\n${outcome.additionalContext}\n</hook-additional-context>` }];
+		}
+		return { content, isError };
+	});
+
+	// ---- UserPromptSubmit ---------------------------------------------------
+	pi.on("input", async (event, ctx) => {
+		if (event.source === "extension") return undefined;
+		stopHookActive = false;
+		const payload: HookStdinPayload = { ...basePayload(ctx, "UserPromptSubmit"), prompt: event.text };
+		const outcome = await dispatch(ctx, "UserPromptSubmit", { ignoreMatcher: true }, payload);
+		if (outcome.block) {
+			notify(ctx, `Prompt blocked by UserPromptSubmit hook: ${outcome.block.reason}`);
+			return { action: "handled" as const };
+		}
+		if (outcome.additionalContext) pendingPromptContext.push(outcome.additionalContext);
+		return undefined;
+	});
+
+	// Prompt-hook context is injected right before the agent loop builds its
+	// context, so it lands on the same turn as the prompt that produced it.
+	pi.on("before_agent_start", () => {
+		if (pendingPromptContext.length === 0) return;
+		const texts = pendingPromptContext;
+		pendingPromptContext = [];
+		for (const text of texts) injectContext(text, false);
+	});
+
+	// ---- SessionStart / SessionEnd -----------------------------------------
+	const dispatchSessionStart = async (ctx: ExtensionContext, source: string) => {
+		const payload: HookStdinPayload = { ...basePayload(ctx, "SessionStart"), source };
+		const outcome = await dispatch(ctx, "SessionStart", { candidates: [source] }, payload);
+		if (outcome.additionalContext) injectContext(outcome.additionalContext, false);
+	};
+
+	pi.on("session_start", async (event, ctx) => {
+		const reason = (event as { reason?: string }).reason ?? "startup";
+		if (reason === "reload" || reason === "fork") return;
+		await dispatchSessionStart(ctx, reason === "new" ? "startup" : reason);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		const payload: HookStdinPayload = { ...basePayload(ctx, "SessionEnd"), source: "other" };
+		// Fire and forget: the process is on its way out; nothing to apply.
+		void dispatch(ctx, "SessionEnd", { ignoreMatcher: true }, payload);
+	});
+
+	// ---- Stop ---------------------------------------------------------------
+	pi.on("agent_end", async (_event, ctx) => {
+		const payload: HookStdinPayload = { ...basePayload(ctx, "Stop"), stop_hook_active: stopHookActive };
+		const outcome = await dispatch(ctx, "Stop", { ignoreMatcher: true }, payload);
+		if (!outcome.block) return;
+		stopHookActive = true;
+		try {
+			pi.sendMessage(
+				{
+					customType: "one-code:hook-stop",
+					content: `Stop hook blocked stopping: ${outcome.block.reason}`,
+					display: false,
+				},
+				{ deliverAs: "followUp", triggerTurn: true },
+			);
+		} catch {
+			// Session is gone; nothing to continue.
+		}
+	});
+
+	// ---- PreCompact / PostCompact ------------------------------------------
+	pi.on("session_before_compact", async (event, ctx) => {
+		const reason = (event as { reason?: string }).reason;
+		const trigger = reason === "manual" ? "manual" : "auto";
+		const payload: HookStdinPayload = { ...basePayload(ctx, "PreCompact"), trigger };
+		const outcome = await dispatch(ctx, "PreCompact", { candidates: [trigger] }, payload);
+		if (outcome.block) {
+			notify(ctx, `Compaction cancelled by PreCompact hook: ${outcome.block.reason}`);
+			return { cancel: true };
+		}
+		return undefined;
+	});
+
+	pi.on("session_compact", async (_event, ctx) => {
+		const payload: HookStdinPayload = { ...basePayload(ctx, "PostCompact"), trigger: "auto" };
+		const outcome = await dispatch(ctx, "PostCompact", { ignoreMatcher: true }, payload);
+		if (outcome.additionalContext) injectContext(outcome.additionalContext, false);
+		// CC fires SessionStart(source: "compact") after compaction.
+		await dispatchSessionStart(ctx, "compact");
+	});
+}

package/extensions/hooks/matcher.ts

@@ -0,0 +1,72 @@
+/**
+ * Hook matcher evaluation (pure). Claude Code matchers are anchored,
+ * case-insensitive regexes over CC tool names ("Bash", "Edit|Write",
+ * "mcp__server__.*"); One Code tools are snake_case, so every candidate
+ * spelling of a tool — native name, canonical CC name, and the alias table
+ * from permissions/matcher.ts — is tested.
+ */
+
+import { ccAliasesForTool } from "../permissions/matcher.ts";
+
+/**
+ * Canonical Claude Code PascalCase name per One Code tool, for hook matchers
+ * and the `tool_name` stdin field (CC hook scripts compare exact strings like
+ * "Bash"). Tools with no CC counterpart pass through unchanged.
+ */
+const CC_CANONICAL: Record<string, string> = {
+	bash: "Bash",
+	read: "Read",
+	edit: "Edit",
+	write: "Write",
+	grep: "Grep",
+	find: "Glob",
+	ls: "LS",
+	notebook_edit: "NotebookEdit",
+	web_fetch: "WebFetch",
+	web_search: "WebSearch",
+	subagent: "Task",
+	todo_write: "TodoWrite",
+	skill: "Skill",
+	ask_user_question: "AskUserQuestion",
+	enter_plan_mode: "EnterPlanMode",
+	exit_plan_mode: "ExitPlanMode",
+	task_create: "TaskCreate",
+	task_get: "TaskGet",
+	task_list: "TaskList",
+	task_update: "TaskUpdate",
+	task_output: "TaskOutput",
+	task_stop: "TaskStop",
+	monitor: "Monitor",
+	schedule_wakeup: "ScheduleWakeup",
+	send_message: "SendMessage",
+	enter_worktree: "EnterWorktree",
+	exit_worktree: "ExitWorktree",
+	workflow: "Workflow",
+};
+
+export function ccToolName(nativeName: string): string {
+	if (nativeName.startsWith("mcp__")) return nativeName;
+	return CC_CANONICAL[nativeName] ?? nativeName;
+}
+
+/** Every spelling a matcher may reasonably target for this tool. */
+export function toolMatchCandidates(nativeName: string): string[] {
+	return [...new Set([nativeName, ccToolName(nativeName), ...ccAliasesForTool(nativeName)])];
+}
+
+/**
+ * Whether a CC matcher applies to any candidate spelling. Anchored and
+ * case-insensitive (`^(?:matcher)$`, the CC semantics); an invalid regex
+ * falls back to case-insensitive exact comparison rather than throwing.
+ */
+export function matcherApplies(matcher: string | undefined, candidates: string[]): boolean {
+	if (matcher === undefined || matcher === "" || matcher === "*") return true;
+	let regex: RegExp | undefined;
+	try {
+		regex = new RegExp(`^(?:${matcher})$`, "i");
+	} catch {
+		regex = undefined;
+	}
+	const lowered = matcher.toLowerCase();
+	return candidates.some((candidate) => (regex ? regex.test(candidate) : candidate.toLowerCase() === lowered));
+}

package/extensions/hooks/plugin-hooks.ts

@@ -0,0 +1,79 @@
+/**
+ * Plugin hook discovery (pure): each enabled plugin's hooks/hooks.json,
+ * re-derived per call via lib/plugins.ts like every other plugin consumer
+ * (no cross-extension state under jiti).
+ *
+ * Plugin hooks are user scope — installing the plugin was the consent step —
+ * so they run without the project-trust prompt, matching how plugin commands,
+ * skills, and MCP servers already work.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { discoverPlugins, pluginResources } from "../lib/plugins.ts";
+import { parseHooksBlock, type HooksSource } from "./settings.ts";
+
+interface CacheEntry {
+	mtimeMs: number;
+	source: HooksSource | undefined;
+	diagnostics: string[];
+}
+
+/**
+ * `loadPluginHooks` runs on every tool_call AND tool_result, so each plugin's
+ * hooks.json is mtime-cached like the settings files (settings.ts) instead of
+ * re-read and re-validated twice per tool invocation.
+ */
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * Read one plugin hooks.json. CC's format nests events under a "hooks" key;
+ * a bare top-level events map is accepted too, defensively. Commands may
+ * reference ${CLAUDE_PLUGIN_ROOT}, expanded to the plugin's install path.
+ */
+function readPluginHooksFile(hooksConfig: string, pluginName: string, pluginPath: string, diagnostics: string[]): HooksSource | undefined {
+	let mtimeMs: number;
+	try {
+		mtimeMs = statSync(hooksConfig).mtimeMs;
+	} catch {
+		cache.delete(hooksConfig);
+		return undefined;
+	}
+	const cached = cache.get(hooksConfig);
+	if (cached && cached.mtimeMs === mtimeMs) {
+		diagnostics.push(...cached.diagnostics);
+		return cached.source;
+	}
+	const fileDiagnostics: string[] = [];
+	let source: HooksSource | undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(hooksConfig, "utf-8")) as Record<string, unknown>;
+		const block = typeof parsed.hooks === "object" && parsed.hooks !== null ? parsed.hooks : parsed;
+		const config = parseHooksBlock(block, hooksConfig, fileDiagnostics);
+		for (const entries of Object.values(config)) {
+			for (const entry of entries) {
+				for (const hook of entry.hooks) {
+					hook.command = hook.command.replaceAll("${CLAUDE_PLUGIN_ROOT}", pluginPath);
+				}
+			}
+		}
+		if (Object.keys(config).length > 0) {
+			source = { scope: "plugin", path: hooksConfig, pluginName, config };
+		}
+	} catch (error) {
+		fileDiagnostics.push(`${hooksConfig}: unreadable plugin hooks skipped (${error instanceof Error ? error.message : error})`);
+	}
+	cache.set(hooksConfig, { mtimeMs, source, diagnostics: fileDiagnostics });
+	diagnostics.push(...fileDiagnostics);
+	return source;
+}
+
+export function loadPluginHooks(claudeDir: string, diagnostics: string[]): HooksSource[] {
+	const sources: HooksSource[] = [];
+	for (const plugin of discoverPlugins(claudeDir).plugins) {
+		const { hooksConfig } = pluginResources(plugin);
+		if (!hooksConfig) continue;
+		const source = readPluginHooksFile(hooksConfig, plugin.name, plugin.path, diagnostics);
+		if (source) sources.push(source);
+	}
+	return sources;
+}