@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/extensibility/gjc-plugins/schema.ts

@@ -17,14 +17,39 @@ import {
 /**
  * Top-level surfaces that may never appear in a GJC plugin bundle: bundles may
  * only EXTEND existing skills/agents, never register new top-level ones.
+ * Each rejection is a targeted migration diagnostic naming the safe
+ * alternative (the loose surface or the sub-skill binding model) instead of a
+ * generic forbidden-key error.
  */
-const FORBIDDEN_MANIFEST_KEYS = ["skills", "slash-commands", "commands", "agents"];
+const FORBIDDEN_MANIFEST_KEYS = ["skills", "slash-commands", "commands", "agents"] as const;
+
+type ForbiddenManifestKey = (typeof FORBIDDEN_MANIFEST_KEYS)[number];
+
+const FORBIDDEN_SURFACE_DIAGNOSTICS: Record<ForbiddenManifestKey, string> = {
+	skills: `Forbidden GJC plugin surface "skills": bundles may only EXTEND the four bundled workflow skills (deep-interview, ralplan, ultragoal, team) and the four role agents (executor, architect, planner, critic), never register a new top-level skill. Bind an inline sub-skill with the canonical "subskills" surface (frontmatter binds_to/phase/activation_arg), or drop the manifest and use the loose surface .gjc/skills/<name>/SKILL.md (project) / ~/.gjc/agent/skills/<name>/SKILL.md (user).`,
+	"slash-commands": `Forbidden GJC plugin surface "slash-commands": bundles cannot register slash commands. Use the loose surface .gjc/commands/<name> (TypeScript module) or a markdown slash-command file instead.`,
+	commands: `Forbidden GJC plugin surface "commands" (Claude Code plugin.json vocabulary): bundles cannot register slash commands. Use the loose surface .gjc/commands/<name> (TypeScript module) or a markdown slash-command file instead.`,
+	agents: `Forbidden GJC plugin surface "agents" (Claude Code plugin.json vocabulary): bundles cannot register top-level agents; executor/architect/planner/critic are protected. Bind a sub-skill to an existing agent with the canonical "subskills" surface (frontmatter binds_to: one of executor|architect|planner|critic, phase, activation_arg) instead.`,
+};
+
+/**
+ * Ambiguous legacy aliases whose shape cannot be mapped onto the canonical
+ * compiled representation. Rejected as `unsupported_surface` with a targeted
+ * migration diagnostic naming the canonical form, never a generic unknown-key
+ * error. `mcp` is singular and shape-ambiguous (array entry vs single object),
+ * so it stays rejected; `mcpServers` is accepted and normalized (below).
+ */
+const AMBIGUOUS_ALIAS_KEYS = ["mcp"] as const;
 
 /**
- * Ambiguous legacy aliases. `mcps` is the only canonical MCP key; these are
- * rejected as `unsupported_surface` to avoid accidental legacy shape ambiguity.
+ * Accepted compatibility aliases from Claude Code / Codex-familiar plugin
+ * vocabulary. Each is normalized into the canonical compiled representation at
+ * parse time, so a canonical manifest and its alias compile to byte-equivalent
+ * normalized surfaces. Only aliases with an unambiguous semantic mapping are
+ * accepted here; anything else falls into AMBIGUOUS_ALIAS_KEYS or a targeted
+ * per-field migration diagnostic.
  */
-const UNSUPPORTED_ALIAS_KEYS = ["mcp", "mcpServers"];
+const ACCEPTED_ALIAS_KEYS = ["mcpServers"] as const;
 
 const KNOWN_MANIFEST_KEYS = new Set([
 	"kind",
@@ -36,8 +61,33 @@ const KNOWN_MANIFEST_KEYS = new Set([
 	"mcps",
 	"system_appendix",
 	"agent-appendix",
+	...ACCEPTED_ALIAS_KEYS,
 ]);
 
+/**
+ * Per-server keys the `mcpServers` alias accepts and maps onto the canonical
+ * `mcps` entry (`type` is Claude Code / loose mcp.json vocabulary for the
+ * canonical `transport` field).
+ */
+const MCP_SERVER_ALIAS_KEYS = new Set(["type", "command", "args", "cwd", "url"]);
+
+/**
+ * Per-server keys that exist in GJC's loose mcp.json surface but have NO
+ * equivalent in the canonical plugin-manifest `mcps` entry. An alias cannot
+ * preserve their semantics, so they raise a targeted migration diagnostic
+ * naming the loose surface that can hold them.
+ */
+const MCP_SERVER_ALIAS_UNSUPPORTED_KEYS = [
+	"env",
+	"auth",
+	"oauth",
+	"headers",
+	"enabled",
+	"timeout",
+	"autoload",
+	"noInheritEnv",
+] as const;
+
 const MCP_TRANSPORTS: readonly GjcPluginMcpTransport[] = ["stdio", "http", "sse"];
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -191,6 +241,17 @@ function parseTools(value: unknown, manifestPath: string): GjcPluginToolManifest
 function parseHooks(value: unknown, manifestPath: string): GjcPluginHookManifestEntry[] {
 	const raw = optionalArray(value, "hooks", manifestPath);
 	return raw.map((entry, index) => {
+		// Claude Code plugin.json hook entries are matcher groups ({ matcher,
+		// hooks, source }) with no `name`; a GJC bundle hook is a single
+		// constrained file with a declared event. The shapes cannot be mapped
+		// onto each other, so give the author a targeted migration diagnostic
+		// instead of a generic missing-field error.
+		if (isRecord(entry) && ("matcher" in entry || "hooks" in entry || "source" in entry)) {
+			throw new GjcPluginLoadError(
+				"invalid_manifest",
+				`Invalid GJC plugin manifest at ${manifestPath}: hooks[${index}] looks like a Claude Code plugin.json hook entry ({ matcher, hooks, source }), which cannot be preserved as a GJC bundle hook. Canonical GJC bundle hooks are { name, event, target?, phase?, path, sha256? } (event "tool_call"/"tool_result" with target/phase, or a session event). For unconstrained local hooks, use the loose surface .gjc/hooks/pre/<tool>.ts / .gjc/hooks/post/<tool>.ts.`,
+			);
+		}
 		if (!isRecord(entry)) {
 			throw new GjcPluginLoadError(
 				"invalid_manifest",
@@ -222,53 +283,151 @@ function parseHooks(value: unknown, manifestPath: string): GjcPluginHookManifest
 	});
 }
 
-function parseMcps(value: unknown, manifestPath: string): GjcPluginMcpManifestEntry[] {
-	const raw = optionalArray(value, "mcps", manifestPath);
-	return raw.map((entry, index) => {
-		if (!isRecord(entry)) {
+function parseMcpEntry(entry: unknown, field: string, manifestPath: string): GjcPluginMcpManifestEntry {
+	if (!isRecord(entry)) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: ${field} must be an object`,
+		);
+	}
+	const name = manifestSafeName(entry.name, `${field}.name`, manifestPath);
+	const transport = entry.transport;
+	if (typeof transport !== "string" || !MCP_TRANSPORTS.includes(transport as GjcPluginMcpTransport)) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: ${field}.transport must be one of ${MCP_TRANSPORTS.join(", ")}`,
+		);
+	}
+	const command =
+		entry.command === undefined ? undefined : manifestString(entry.command, `${field}.command`, manifestPath);
+	const url = entry.url === undefined ? undefined : manifestString(entry.url, `${field}.url`, manifestPath);
+	const cwd = entry.cwd === undefined ? undefined : manifestString(entry.cwd, `${field}.cwd`, manifestPath);
+	let args: string[] | undefined;
+	if (entry.args !== undefined) {
+		if (!Array.isArray(entry.args) || !entry.args.every(item => typeof item === "string")) {
 			throw new GjcPluginLoadError(
 				"invalid_manifest",
-				`Invalid GJC plugin manifest at ${manifestPath}: mcps[${index}] must be an object`,
+				`Invalid GJC plugin manifest at ${manifestPath}: ${field}.args must be a string array`,
 			);
 		}
-		const name = manifestSafeName(entry.name, `mcps[${index}].name`, manifestPath);
-		const transport = entry.transport;
-		if (typeof transport !== "string" || !MCP_TRANSPORTS.includes(transport as GjcPluginMcpTransport)) {
+		args = [...(entry.args as string[])];
+	}
+	let headers: Record<string, string> | undefined;
+	if (entry.headers !== undefined) {
+		if (!isRecord(entry.headers) || !Object.values(entry.headers).every(v => typeof v === "string")) {
 			throw new GjcPluginLoadError(
 				"invalid_manifest",
-				`Invalid GJC plugin manifest at ${manifestPath}: mcps[${index}].transport must be one of ${MCP_TRANSPORTS.join(", ")}`,
+				`Invalid GJC plugin manifest at ${manifestPath}: ${field}.headers must be a string map`,
 			);
 		}
-		const command =
-			entry.command === undefined
-				? undefined
-				: manifestString(entry.command, `mcps[${index}].command`, manifestPath);
-		const url = entry.url === undefined ? undefined : manifestString(entry.url, `mcps[${index}].url`, manifestPath);
-		const cwd = entry.cwd === undefined ? undefined : manifestString(entry.cwd, `mcps[${index}].cwd`, manifestPath);
-		let args: string[] | undefined;
-		if (entry.args !== undefined) {
-			if (!Array.isArray(entry.args) || !entry.args.every(item => typeof item === "string")) {
+		headers = { ...(entry.headers as Record<string, string>) };
+	}
+	const sha256 =
+		entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `${field}.sha256`, manifestPath);
+	return { name, transport: transport as GjcPluginMcpTransport, command, args, cwd, url, headers, sha256 };
+}
+
+function parseMcps(value: unknown, manifestPath: string): GjcPluginMcpManifestEntry[] {
+	const raw = optionalArray(value, "mcps", manifestPath);
+	return raw.map((entry, index) => parseMcpEntry(entry, `mcps[${index}]`, manifestPath));
+}
+
+/**
+ * Claude Code / Codex-familiar `mcpServers` map (server name -> server config),
+ * normalized into the canonical `mcps` array. Only fields with an unambiguous
+ * canonical equivalent are accepted; anything the canonical `mcps` entry cannot
+ * preserve (env, auth, oauth, headers, enablement/timeout/autoload controls, unknown
+ * keys) raises a targeted migration diagnostic naming the exact alternative.
+ */
+function normalizeMcpServersAlias(value: unknown, manifestPath: string): GjcPluginMcpManifestEntry[] {
+	if (!isRecord(value)) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: "mcpServers" must be a map of server name to configuration`,
+		);
+	}
+	const entries: GjcPluginMcpManifestEntry[] = [];
+	const serverEntries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+	for (const [serverName, rawEntry] of serverEntries) {
+		if (!isRecord(rawEntry)) {
+			throw new GjcPluginLoadError(
+				"invalid_manifest",
+				`Invalid GJC plugin manifest at ${manifestPath}: mcpServers["${serverName}"] must be an object`,
+			);
+		}
+		for (const key of Object.keys(rawEntry)) {
+			if ((MCP_SERVER_ALIAS_UNSUPPORTED_KEYS as readonly string[]).includes(key)) {
 				throw new GjcPluginLoadError(
-					"invalid_manifest",
-					`Invalid GJC plugin manifest at ${manifestPath}: mcps[${index}].args must be a string array`,
+					"unsupported_surface",
+					`mcpServers["${serverName}"] uses "${key}", which the canonical GJC bundle runtime cannot preserve end to end. "${key}" is supported by GJC's canonical loose MCP surface (mcpServers map in <project>/.gjc/mcp.json or ~/.gjc/agent/mcp.json): move this server there directly or through the /extensions import flow, or drop "${key}" from the bundle manifest (${manifestPath})`,
+				);
+			}
+			if (!MCP_SERVER_ALIAS_KEYS.has(key)) {
+				throw new GjcPluginLoadError(
+					"unsupported_surface",
+					`mcpServers["${serverName}"] has unknown key "${key}". Canonical "mcps" entries support name, transport, command, args, cwd, url, headers, sha256; the "mcpServers" alias additionally accepts "type" for the transport (${manifestPath})`,
 				);
 			}
-			args = [...(entry.args as string[])];
 		}
-		let headers: Record<string, string> | undefined;
-		if (entry.headers !== undefined) {
-			if (!isRecord(entry.headers) || !Object.values(entry.headers).every(v => typeof v === "string")) {
+		let transport: GjcPluginMcpTransport;
+		if (rawEntry.type !== undefined) {
+			if (typeof rawEntry.type !== "string" || !MCP_TRANSPORTS.includes(rawEntry.type as GjcPluginMcpTransport)) {
 				throw new GjcPluginLoadError(
 					"invalid_manifest",
-					`Invalid GJC plugin manifest at ${manifestPath}: mcps[${index}].headers must be a string map`,
+					`Invalid GJC plugin manifest at ${manifestPath}: mcpServers["${serverName}"].type must be one of ${MCP_TRANSPORTS.join(", ")}`,
 				);
 			}
-			headers = { ...(entry.headers as Record<string, string>) };
+			transport = rawEntry.type as GjcPluginMcpTransport;
+		} else if (typeof rawEntry.command === "string" && typeof rawEntry.url === "string") {
+			// Both stdio (command) and url transports declared without a type:
+			// ambiguous, refuse rather than guess.
+			throw new GjcPluginLoadError(
+				"invalid_manifest",
+				`Invalid GJC plugin manifest at ${manifestPath}: mcpServers["${serverName}"] declares both "command" and "url" without a "type". Set "type" to "stdio" (command) or "http"/"sse" (url).`,
+			);
+		} else if (typeof rawEntry.command === "string") {
+			// Claude Code defaults: a command means stdio.
+			transport = "stdio";
+		} else if (typeof rawEntry.url === "string") {
+			// A bare url means an http transport; sse must be declared explicitly.
+			transport = "http";
+		} else {
+			throw new GjcPluginLoadError(
+				"invalid_manifest",
+				`Invalid GJC plugin manifest at ${manifestPath}: mcpServers["${serverName}"] cannot determine a transport. Set "type" (stdio | http | sse), or provide "command" (stdio) or "url" (http)`,
+			);
 		}
-		const sha256 =
-			entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `mcps[${index}].sha256`, manifestPath);
-		return { name, transport: transport as GjcPluginMcpTransport, command, args, cwd, url, headers, sha256 };
-	});
+		const incompatibleKeys = transport === "stdio" ? ["url"] : ["command", "args", "cwd"];
+		for (const key of incompatibleKeys) {
+			if (rawEntry[key] !== undefined) {
+				throw new GjcPluginLoadError(
+					"unsupported_surface",
+					`mcpServers["${serverName}"] uses "${key}" with transport "${transport}", but the GJC bundle runtime cannot preserve that field for this transport. Use only command/args/cwd for stdio or url for http/sse, or move the server to the canonical loose .gjc/mcp.json surface (${manifestPath})`,
+				);
+			}
+		}
+		entries.push(
+			parseMcpEntry(
+				{
+					name: serverName,
+					transport,
+					...pickOptional(rawEntry, ["command", "args", "cwd", "url"]),
+				},
+				`mcpServers["${serverName}"]`,
+				manifestPath,
+			),
+		);
+	}
+	return entries;
+}
+
+function pickOptional(entry: Record<string, unknown>, keys: readonly string[]): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const key of keys) {
+		const value = entry[key];
+		if (value !== undefined) out[key] = value;
+	}
+	return out;
 }
 
 function parseAppendixEntry(entry: unknown, field: string, manifestPath: string): GjcPluginAppendixManifestEntry {
@@ -324,15 +483,18 @@ export function parseManifest(raw: unknown, manifestPath: string): GjcPluginMani
 
 	for (const key of FORBIDDEN_MANIFEST_KEYS) {
 		if (Object.hasOwn(raw, key)) {
-			throw new GjcPluginLoadError("forbidden_surface", `Forbidden GJC plugin surface in ${manifestPath}: ${key}`);
+			throw new GjcPluginLoadError(
+				"forbidden_surface",
+				`GJC plugin manifest at ${manifestPath}: ${FORBIDDEN_SURFACE_DIAGNOSTICS[key]}`,
+			);
 		}
 	}
 
-	for (const key of UNSUPPORTED_ALIAS_KEYS) {
+	for (const key of AMBIGUOUS_ALIAS_KEYS) {
 		if (Object.hasOwn(raw, key)) {
 			throw new GjcPluginLoadError(
 				"unsupported_surface",
-				`Unsupported GJC plugin surface in ${manifestPath}: ${key} (use the canonical "mcps" key)`,
+				`Unsupported GJC plugin surface "${key}" in ${manifestPath}: the singular "mcp" shape is ambiguous. Use the canonical "mcps" (array of { name, transport, command, args, cwd, url, headers }) or the Claude Code-compatible "mcpServers" map alias.`,
 			);
 		}
 	}
@@ -341,11 +503,22 @@ export function parseManifest(raw: unknown, manifestPath: string): GjcPluginMani
 		if (!KNOWN_MANIFEST_KEYS.has(key)) {
 			throw new GjcPluginLoadError(
 				"unsupported_surface",
-				`Unsupported GJC plugin surface in ${manifestPath}: ${key}`,
+				`Unsupported GJC plugin surface in ${manifestPath}: ${key}. Known GJC bundle keys: ${[...KNOWN_MANIFEST_KEYS].sort().join(", ")}.`,
 			);
 		}
 	}
 
+	// Claude Code plugin.json declares hooks as an event-keyed map; GJC bundle
+	// hooks are a constrained array. Detect the foreign shape and explain the
+	// canonical form (and the loose hook surface) instead of a generic
+	// must-be-an-array error.
+	if (raw.hooks !== undefined && !Array.isArray(raw.hooks)) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: "hooks" must be an array of { name, event, target?, phase?, path, sha256? }. A Claude Code plugin.json "hooks" map (event-keyed matcher groups) cannot be preserved as a GJC bundle hook. For unconstrained local hooks, use the loose surface .gjc/hooks/pre/<tool>.ts / .gjc/hooks/post/<tool>.ts.`,
+		);
+	}
+
 	if (raw.kind !== GJC_PLUGIN_KIND) {
 		throw new GjcPluginLoadError(
 			"invalid_kind",
@@ -353,6 +526,13 @@ export function parseManifest(raw: unknown, manifestPath: string): GjcPluginMani
 		);
 	}
 
+	if (raw.mcps !== undefined && raw.mcpServers !== undefined) {
+		throw new GjcPluginLoadError(
+			"invalid_manifest",
+			`Invalid GJC plugin manifest at ${manifestPath}: use either the canonical "mcps" array or the "mcpServers" alias map, not both.`,
+		);
+	}
+
 	const name = manifestSafeName(raw.name, "name", manifestPath);
 	const version = manifestSafeVersion(raw.version, manifestPath);
 
@@ -363,7 +543,10 @@ export function parseManifest(raw: unknown, manifestPath: string): GjcPluginMani
 		subskills: optionalStringArray(raw.subskills, "subskills", manifestPath),
 		tools: parseTools(raw.tools, manifestPath),
 		hooks: parseHooks(raw.hooks, manifestPath),
-		mcps: parseMcps(raw.mcps, manifestPath),
+		mcps:
+			raw.mcpServers !== undefined
+				? normalizeMcpServersAlias(raw.mcpServers, manifestPath)
+				: parseMcps(raw.mcps, manifestPath),
 		systemAppendix: parseSystemAppendix(raw.system_appendix, manifestPath),
 		agentAppendix: parseAgentAppendix(raw["agent-appendix"], manifestPath),
 	};

package/src/extensibility/hooks/loader.ts

@@ -7,12 +7,29 @@ import * as zod from "zod/v4";
 import { hookCapability } from "../../capability/hook";
 import type { Hook } from "../../discovery";
 import { loadCapability } from "../../discovery";
+import { HookSourceConvention } from "../../hooks/events";
+import { type NormalizedHook, normalizeDirectoryHook } from "../../hooks/normalize";
 import type { HookMessage } from "../../session/messages";
 import type { SessionManager } from "../../session/session-manager";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	ExtensionFactory,
+	MessageRenderer,
+} from "../extensions/types";
 import * as typebox from "../typebox";
 import { resolvePath } from "../utils";
 import { execCommand } from "./runner";
-import type { ExecOptions, HookAPI, HookFactory, HookMessageRenderer, RegisteredCommand } from "./types";
+import type {
+	ExecOptions,
+	HookAPI,
+	HookCommandContext,
+	HookContext,
+	HookFactory,
+	HookMessageRenderer,
+	RegisteredCommand,
+} from "./types";
 
 /**
  * Generic handler function type.
@@ -71,6 +88,8 @@ export interface LoadedHook {
 	setSendMessageHandler: (handler: SendMessageHandler) => void;
 	/** Set the append entry handler for this hook's pi.appendEntry() */
 	setAppendEntryHandler: (handler: AppendEntryHandler) => void;
+	/** Canonical discovery descriptor when loaded from a known hook convention. */
+	normalization?: NormalizedHook;
 }
 
 /**
@@ -83,6 +102,11 @@ export interface LoadHooksResult {
 	errors: Array<{ path: string; error: string }>;
 }
 
+export interface LoadHookExtensionsResult {
+	factories: Array<{ factory: ExtensionFactory; name: string }>;
+	errors: Array<{ path: string; error: string }>;
+}
+
 /**
  * Create a HookAPI instance that collects handlers, renderers, and commands.
  * Returns the API, maps, and functions to set handlers later.
@@ -223,17 +247,17 @@ export async function loadHooks(paths: string[], cwd: string): Promise<LoadHooks
 }
 
 /**
- * Discover and load hooks from all registered providers.
- * Uses the capability API to discover hook paths from:
- * 1. GJC native configs (.gjc/.pi hooks/)
- * 2. Installed plugins
- * 3. Other editor/IDE configurations
+ * Discover and load hooks from canonical native GJC configuration.
+ * Claude Code and Codex hook layouts remain registered capability providers for
+ * explicit import and diagnostics, but are not competing runtime authorities.
  *
  * Plus any explicitly configured paths from settings.
  */
 export async function discoverAndLoadHooks(configuredPaths: string[], cwd: string): Promise<LoadHooksResult> {
 	const allPaths: string[] = [];
 	const seen = new Set<string>();
+	const normalizationErrors: Array<{ path: string; error: string }> = [];
+	const normalizationByPath = new Map<string, NormalizedHook>();
 
 	// Helper to add paths without duplicates
 	const addPaths = (paths: string[]) => {
@@ -246,12 +270,132 @@ export async function discoverAndLoadHooks(configuredPaths: string[], cwd: strin
 		}
 	};
 
-	// 1. Discover hooks via capability API
-	const discovered = await loadCapability<Hook>(hookCapability.id, { cwd });
-	addPaths(discovered.items.map(hook => hook.path));
+	// 1. Discover hooks via capability API and validate the provider descriptor
+	// against the canonical model before importing project-controlled code.
+	const discovered = await loadCapability<Hook>(hookCapability.id, { cwd, providers: ["native"] });
+	for (const hook of discovered.items) {
+		const convention =
+			hook._source.provider === "native"
+				? HookSourceConvention.NativeGjc
+				: hook._source.provider === "claude"
+					? HookSourceConvention.ClaudeCode
+					: hook._source.provider === "codex"
+						? HookSourceConvention.Codex
+						: null;
+		if (convention) {
+			const normalized = normalizeDirectoryHook({
+				convention,
+				phase: hook.type,
+				toolName: hook.tool,
+				source: hook.path,
+				externalName: hook.name,
+			});
+			if (!normalized.hook) {
+				normalizationErrors.push({
+					path: hook.path,
+					error: normalized.diagnostics.map(diagnostic => `${diagnostic.code}: ${diagnostic.message}`).join("; "),
+				});
+				continue;
+			}
+			normalizationByPath.set(path.resolve(hook.path), normalized.hook);
+		}
+		addPaths([hook.path]);
+	}
 
 	// 2. Explicitly configured paths (can override/add)
 	addPaths(configuredPaths.map(p => resolvePath(p, cwd)));
 
-	return loadHooks(allPaths, cwd);
+	const loaded = await loadHooks(allPaths, cwd);
+	for (const hook of loaded.hooks) {
+		hook.normalization = normalizationByPath.get(path.resolve(hook.path));
+	}
+	return { hooks: loaded.hooks, errors: [...normalizationErrors, ...loaded.errors] };
+}
+
+function toHookContext(context: ExtensionContext): HookContext {
+	return {
+		ui: {
+			select: (title, options) => context.ui.select(title, options),
+			confirm: (title, message) => context.ui.confirm(title, message),
+			input: (title, placeholder) => context.ui.input(title, placeholder),
+			notify: (message, type) => context.ui.notify(message, type),
+			setStatus: (key, text) => context.ui.setStatus(key, text),
+			custom: factory => context.ui.custom((tui, theme, _keybindings, done) => factory(tui, theme, done)),
+			setEditorText: text => context.ui.setEditorText(text),
+			getEditorText: () => context.ui.getEditorText(),
+			editor: (title, prefill, options) => context.ui.editor(title, prefill, options),
+			theme: context.ui.theme,
+		},
+		hasUI: context.hasUI,
+		cwd: context.cwd,
+		sessionManager: context.sessionManager,
+		modelRegistry: context.modelRegistry,
+		model: context.model,
+		isIdle: () => context.isIdle(),
+		abort: () => context.abort(),
+		hasQueuedMessages: () => context.hasQueuedMessages(),
+	};
+}
+
+function toHookCommandContext(context: ExtensionCommandContext): HookCommandContext {
+	return {
+		...toHookContext(context),
+		waitForIdle: () => context.waitForIdle(),
+		newSession: options => context.newSession(options),
+		branch: entryId => context.branch(entryId),
+		navigateTree: (targetId, options) => context.navigateTree(targetId, options),
+	};
+}
+
+function createHookExtensionFactory(hook: LoadedHook): ExtensionFactory {
+	return (api: ExtensionAPI) => {
+		hook.setSendMessageHandler((message, options) => api.sendMessage(message, options));
+		hook.setAppendEntryHandler((customType, data) => api.appendEntry(customType, data));
+
+		for (const [event, handlers] of hook.handlers) {
+			for (const handler of handlers) {
+				const normalized = hook.normalization;
+				const adapted: HandlerFn = async (...args: unknown[]) => {
+					const payload = args[0] as { toolName?: string };
+					if (
+						normalized &&
+						event === normalized.runtimeEvent &&
+						normalized.toolName !== "*" &&
+						payload.toolName !== normalized.toolName
+					) {
+						return undefined;
+					}
+					return await handler(payload, toHookContext(args[1] as ExtensionContext));
+				};
+				(api.on as (event: string, handler: HandlerFn) => void)(event, adapted);
+			}
+		}
+
+		for (const [customType, renderer] of hook.messageRenderers) {
+			const adaptedRenderer: MessageRenderer = (message, options, theme) =>
+				renderer({ ...message, role: "hookMessage" }, options, theme);
+			api.registerMessageRenderer(customType, adaptedRenderer);
+		}
+		for (const command of hook.commands.values()) {
+			api.registerCommand(command.name, {
+				description: command.description,
+				handler: (args, context) => command.handler(args, toHookCommandContext(context)),
+			});
+		}
+	};
+}
+
+/** Load normalized directory hooks and adapt them into the authoritative ExtensionRunner path. */
+export async function discoverAndLoadHookExtensions(
+	configuredPaths: string[],
+	cwd: string,
+): Promise<LoadHookExtensionsResult> {
+	const loaded = await discoverAndLoadHooks(configuredPaths, cwd);
+	return {
+		factories: loaded.hooks.map(hook => ({
+			factory: createHookExtensionFactory(hook),
+			name: `hook:${hook.resolvedPath}`,
+		})),
+		errors: loaded.errors,
+	};
 }