@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/hooks/events.ts

@@ -0,0 +1,291 @@
+/** Stable canonical names used to compare hook surfaces without replacing runtime event types. */
+export const HookEventKind = {
+	UserPromptSubmit: "user_prompt_submit",
+	PreToolUse: "pre_tool_use",
+	PostToolUse: "post_tool_use",
+	Stop: "stop",
+	SessionStart: "session_start",
+	SessionShutdown: "session_shutdown",
+} as const;
+
+export type HookEventKind = (typeof HookEventKind)[keyof typeof HookEventKind];
+
+export const HookAuthority = {
+	Constrained: "constrained",
+	Command: "command",
+	InProcess: "in-process",
+} as const;
+
+export type HookAuthority = (typeof HookAuthority)[keyof typeof HookAuthority];
+
+export const HookSourceConvention = {
+	NativeGjc: "native-gjc",
+	ClaudeCode: "claude-code",
+	Codex: "codex",
+	CodexManagedJson: "codex-managed-json",
+	GjcPlugin: "gjc-plugin",
+	InProcess: "in-process",
+} as const;
+
+export type HookSourceConvention = (typeof HookSourceConvention)[keyof typeof HookSourceConvention];
+
+export interface HookEventSchemaContract {
+	kind: HookEventKind;
+	input: string;
+	output: string;
+}
+
+/**
+ * Canonical schema references. These point at existing runtime types; they are not a
+ * second runtime event union and do not change payloads dispatched by the hook runners.
+ */
+export const HOOK_EVENT_SCHEMAS: Record<HookEventKind, HookEventSchemaContract> = {
+	[HookEventKind.UserPromptSubmit]: {
+		kind: HookEventKind.UserPromptSubmit,
+		input: "BeforeAgentStartEvent { type, prompt, images?, systemPrompt } or provider-owned named-event payload",
+		output: "BeforeAgentStartEventResult { message?, systemPrompt? } or provider-owned command output",
+	},
+	[HookEventKind.PreToolUse]: {
+		kind: HookEventKind.PreToolUse,
+		input: "ToolCallEvent { type, toolName, toolCallId, input }",
+		output: "ToolCallEventResult { block?, reason? }",
+	},
+	[HookEventKind.PostToolUse]: {
+		kind: HookEventKind.PostToolUse,
+		input: "ToolResultEvent { type, toolName, toolCallId, input, content, details, isError }",
+		output: "ToolResultEventResult { content?, details?, isError? }",
+	},
+	[HookEventKind.Stop]: {
+		kind: HookEventKind.Stop,
+		input: "AgentEndEvent for GJC in-process hooks, or provider-owned Stop payload",
+		output: "void for GJC in-process hooks, or provider-owned command output",
+	},
+	[HookEventKind.SessionStart]: {
+		kind: HookEventKind.SessionStart,
+		input: "SessionStartEvent { type: session_start }",
+		output: "void",
+	},
+	[HookEventKind.SessionShutdown]: {
+		kind: HookEventKind.SessionShutdown,
+		input: "SessionShutdownEvent { type: session_shutdown }",
+		output: "void",
+	},
+};
+
+export type HookOrdering = "sequential" | "external-runtime";
+export type HookAwaitBehavior = "awaited" | "external-runtime";
+export type HookErrorBehavior = "isolate" | "fail-closed" | "external-runtime";
+export type HookProcessAuthority = "none" | "hook-api" | "command" | "ambient-host";
+export type HookTrustRequirement = "not-enforced" | "provider-owned";
+export type HookRedaction = "none" | "provider-owned";
+
+export interface HookExecutionContract {
+	kind: HookEventKind;
+	runtimeEvent: string;
+	authority: HookAuthority;
+	awaitBehavior: HookAwaitBehavior;
+	ordering: HookOrdering;
+	canCancel: boolean;
+	mutation: readonly string[];
+	timeoutMs: number | null;
+	errorBehavior: HookErrorBehavior;
+	processAuthority: HookProcessAuthority;
+	trustRequirement: HookTrustRequirement;
+	redaction: HookRedaction;
+	logging: string;
+	semanticNotes: string;
+}
+
+const hookModulePre: HookExecutionContract = {
+	kind: HookEventKind.PreToolUse,
+	runtimeEvent: "tool_call",
+	authority: HookAuthority.InProcess,
+	awaitBehavior: "awaited",
+	ordering: "sequential",
+	canCancel: true,
+	mutation: [],
+	timeoutMs: null,
+	errorBehavior: "fail-closed",
+	processAuthority: "hook-api",
+	trustRequirement: "not-enforced",
+	redaction: "none",
+	logging: "Extension errors expose the extension path, event name, error message, and stack to registered listeners.",
+	semanticNotes:
+		"The first blocking result stops later handlers. Directory hooks are imported modules, not shell scripts.",
+};
+
+const hookModulePost: HookExecutionContract = {
+	kind: HookEventKind.PostToolUse,
+	runtimeEvent: "tool_result",
+	authority: HookAuthority.InProcess,
+	awaitBehavior: "awaited",
+	ordering: "sequential",
+	canCancel: false,
+	mutation: ["content", "details", "isError"],
+	timeoutMs: 30_000,
+	errorBehavior: "isolate",
+	processAuthority: "hook-api",
+	trustRequirement: "not-enforced",
+	redaction: "none",
+	logging: "Extension errors expose the extension path, event name, error message, and stack to registered listeners.",
+	semanticNotes:
+		"Handlers receive the prior handler's replacements; content, details, and isError changes are chained in registration order.",
+};
+
+const constrainedPre: HookExecutionContract = {
+	...hookModulePre,
+	authority: HookAuthority.Constrained,
+	processAuthority: "ambient-host",
+	semanticNotes:
+		"The plugin API denies exec, messaging, commands, renderers, and session mutation, but the imported module is not a process sandbox and retains ambient Bun/host globals. A thrown pre-hook error blocks the tool.",
+};
+
+const constrainedPost: HookExecutionContract = {
+	...hookModulePost,
+	authority: HookAuthority.Constrained,
+	timeoutMs: 30_000,
+	processAuthority: "ambient-host",
+	mutation: ["content", "details", "isError"],
+	semanticNotes: "The constrained hook is adapted into ExtensionRunner; timeout and thrown errors are isolated.",
+};
+
+const constrainedLifecycle = (kind: HookEventKind, runtimeEvent: string): HookExecutionContract => ({
+	kind,
+	runtimeEvent,
+	authority: HookAuthority.Constrained,
+	awaitBehavior: "awaited",
+	ordering: "sequential",
+	canCancel: false,
+	mutation: [],
+	timeoutMs: 30_000,
+	errorBehavior: "isolate",
+	processAuthority: "ambient-host",
+	trustRequirement: "not-enforced",
+	redaction: "none",
+	logging: "Extension errors expose the extension path, event name, error message, and stack to registered listeners.",
+	semanticNotes:
+		"The constrained GJC API remains denied, but the imported plugin module retains ambient host-process authority.",
+});
+
+const managedPrompt: HookExecutionContract = {
+	kind: HookEventKind.UserPromptSubmit,
+	runtimeEvent: "UserPromptSubmit",
+	authority: HookAuthority.Command,
+	awaitBehavior: "external-runtime",
+	ordering: "external-runtime",
+	canCancel: false,
+	mutation: [],
+	timeoutMs: null,
+	errorBehavior: "external-runtime",
+	processAuthority: "command",
+	trustRequirement: "provider-owned",
+	redaction: "provider-owned",
+	logging: "Codex owns command invocation logging; GJC only installs and handles its managed command payload.",
+	semanticNotes: "Normalization describes hooks.json configuration; GJC does not schedule this command itself.",
+};
+
+const managedStop: HookExecutionContract = {
+	...managedPrompt,
+	kind: HookEventKind.Stop,
+	runtimeEvent: "Stop",
+};
+
+const inProcessPrompt: HookExecutionContract = {
+	kind: HookEventKind.UserPromptSubmit,
+	runtimeEvent: "before_agent_start",
+	authority: HookAuthority.InProcess,
+	awaitBehavior: "awaited",
+	ordering: "sequential",
+	canCancel: false,
+	mutation: ["message", "systemPrompt"],
+	timeoutMs: 30_000,
+	errorBehavior: "isolate",
+	processAuthority: "hook-api",
+	trustRequirement: "not-enforced",
+	redaction: "none",
+	logging: "Extension errors expose the extension path, event name, error message, and stack to registered listeners.",
+	semanticNotes: "This is a before-agent-start callback, not a byte-for-byte Claude/Codex UserPromptSubmit payload.",
+};
+
+const inProcessStop: HookExecutionContract = {
+	kind: HookEventKind.Stop,
+	runtimeEvent: "agent_end",
+	authority: HookAuthority.InProcess,
+	awaitBehavior: "awaited",
+	ordering: "sequential",
+	canCancel: false,
+	mutation: [],
+	timeoutMs: 30_000,
+	errorBehavior: "isolate",
+	processAuthority: "hook-api",
+	trustRequirement: "not-enforced",
+	redaction: "none",
+	logging: "Extension errors expose the extension path, event name, error message, and stack to registered listeners.",
+	semanticNotes:
+		"agent_end is the loop-end equivalent. turn_end is per-turn and is intentionally not normalized to Stop.",
+};
+
+const lifecycle = (kind: HookEventKind, runtimeEvent: string): HookExecutionContract => ({
+	kind,
+	runtimeEvent,
+	authority: HookAuthority.InProcess,
+	awaitBehavior: "awaited",
+	ordering: "sequential",
+	canCancel: false,
+	mutation: [],
+	timeoutMs: 30_000,
+	errorBehavior: "isolate",
+	processAuthority: "hook-api",
+	trustRequirement: "not-enforced",
+	redaction: "none",
+	logging: "Extension errors expose the extension path, event name, error message, and stack to registered listeners.",
+	semanticNotes: "Dispatched by ExtensionRunner and awaited sequentially with the shared extension timeout.",
+});
+
+/** Per-convention execution truth. Missing entries are unsupported. */
+export const CONVENTION_EVENT_CONTRACTS: Record<
+	HookSourceConvention,
+	Partial<Record<HookEventKind, HookExecutionContract>>
+> = {
+	[HookSourceConvention.NativeGjc]: {
+		[HookEventKind.PreToolUse]: hookModulePre,
+		[HookEventKind.PostToolUse]: hookModulePost,
+	},
+	[HookSourceConvention.ClaudeCode]: {
+		[HookEventKind.PreToolUse]: hookModulePre,
+		[HookEventKind.PostToolUse]: hookModulePost,
+	},
+	[HookSourceConvention.Codex]: {
+		[HookEventKind.PreToolUse]: hookModulePre,
+		[HookEventKind.PostToolUse]: hookModulePost,
+	},
+	[HookSourceConvention.CodexManagedJson]: {
+		[HookEventKind.UserPromptSubmit]: managedPrompt,
+		[HookEventKind.Stop]: managedStop,
+	},
+	[HookSourceConvention.GjcPlugin]: {
+		[HookEventKind.PreToolUse]: constrainedPre,
+		[HookEventKind.PostToolUse]: constrainedPost,
+		[HookEventKind.SessionStart]: constrainedLifecycle(HookEventKind.SessionStart, "session_start"),
+		[HookEventKind.SessionShutdown]: constrainedLifecycle(HookEventKind.SessionShutdown, "session_shutdown"),
+	},
+	[HookSourceConvention.InProcess]: {
+		[HookEventKind.UserPromptSubmit]: inProcessPrompt,
+		[HookEventKind.PreToolUse]: hookModulePre,
+		[HookEventKind.PostToolUse]: hookModulePost,
+		[HookEventKind.Stop]: inProcessStop,
+		[HookEventKind.SessionStart]: lifecycle(HookEventKind.SessionStart, "session_start"),
+		[HookEventKind.SessionShutdown]: lifecycle(HookEventKind.SessionShutdown, "session_shutdown"),
+	},
+};
+
+export const EXTERNAL_EVENT_ALIASES: Readonly<Record<string, HookEventKind>> = {
+	UserPromptSubmit: HookEventKind.UserPromptSubmit,
+	Stop: HookEventKind.Stop,
+	before_agent_start: HookEventKind.UserPromptSubmit,
+	tool_call: HookEventKind.PreToolUse,
+	tool_result: HookEventKind.PostToolUse,
+	agent_end: HookEventKind.Stop,
+	session_start: HookEventKind.SessionStart,
+	session_shutdown: HookEventKind.SessionShutdown,
+};

package/src/hooks/native-skill-hook.ts

@@ -119,6 +119,8 @@ function mergeRawSkillConfig(
 	const rawSkills = readNestedRecord(raw, "skills");
 	const enabled = readBoolean(rawSkills.enabled);
 	const enableSkillCommands = readBoolean(rawSkills.enableSkillCommands);
+	const trustProjectSkills = readBoolean(rawSkills.trustProjectSkills);
+	const trustUserSkills = readBoolean(rawSkills.trustUserSkills);
 	const enablePiUser = readBoolean(rawSkills.enablePiUser);
 	const enablePiProject = readBoolean(rawSkills.enablePiProject);
 	const enableCodexUser = readBoolean(rawSkills.enableCodexUser);
@@ -133,6 +135,8 @@ function mergeRawSkillConfig(
 		...currentSkills,
 		...(enabled !== undefined ? { enabled } : {}),
 		...(enableSkillCommands !== undefined ? { enableSkillCommands } : {}),
+		...(trustProjectSkills !== undefined ? { trustProjectSkills } : {}),
+		...(trustUserSkills !== undefined ? { trustUserSkills } : {}),
 		...(enablePiUser !== undefined ? { enablePiUser } : {}),
 		...(enablePiProject !== undefined ? { enablePiProject } : {}),
 		...(enableCodexUser !== undefined ? { enableCodexUser } : {}),

package/src/hooks/normalize.ts

@@ -0,0 +1,369 @@
+import {
+	CONVENTION_EVENT_CONTRACTS,
+	EXTERNAL_EVENT_ALIASES,
+	type HookAuthority,
+	HookEventKind,
+	type HookExecutionContract,
+	HookSourceConvention,
+} from "./events";
+
+export const HookDiagnosticSeverity = {
+	Error: "error",
+	Warning: "warning",
+} as const;
+
+export type HookDiagnosticSeverity = (typeof HookDiagnosticSeverity)[keyof typeof HookDiagnosticSeverity];
+
+export const HookDiagnosticCode = {
+	UnsupportedConventionEvent: "unsupported_convention_event",
+	UnrecognizedPluginEvent: "unrecognized_plugin_event",
+	InvalidPluginPhase: "invalid_plugin_phase",
+	InvalidToolMatcher: "invalid_tool_matcher",
+	InvalidSource: "invalid_source",
+	InvalidCommand: "invalid_command",
+	DuplicateHook: "duplicate_hook",
+	InProcessEventOutsideIr: "in_process_event_outside_hook_ir",
+	SemanticMismatch: "semantic_mismatch",
+} as const;
+
+export type HookDiagnosticCode = (typeof HookDiagnosticCode)[keyof typeof HookDiagnosticCode];
+
+export interface HookNormalizationDiagnostic {
+	severity: HookDiagnosticSeverity;
+	code: HookDiagnosticCode;
+	message: string;
+	convention: HookSourceConvention;
+	externalEvent?: string;
+	canonicalKind?: HookEventKind;
+	source?: string;
+}
+
+export interface NormalizedHook {
+	kind: HookEventKind;
+	authority: HookAuthority;
+	convention: HookSourceConvention;
+	runtimeEvent: string;
+	toolName: string;
+	source: string;
+	contract: HookExecutionContract;
+}
+
+export interface NormalizeHookResult {
+	hook: NormalizedHook | null;
+	diagnostics: HookNormalizationDiagnostic[];
+}
+
+export function resolveExecutionContract(
+	convention: HookSourceConvention,
+	kind: HookEventKind,
+): HookExecutionContract | null {
+	return CONVENTION_EVENT_CONTRACTS[convention][kind] ?? null;
+}
+
+export function resolveAuthority(convention: HookSourceConvention, kind: HookEventKind): HookAuthority | null {
+	return resolveExecutionContract(convention, kind)?.authority ?? null;
+}
+
+export function resolveCanonicalKind(externalEvent: string): HookEventKind | null {
+	return EXTERNAL_EVENT_ALIASES[externalEvent] ?? null;
+}
+
+export function unsupportedEventDiagnostic(
+	convention: HookSourceConvention,
+	externalEvent: string,
+	canonicalKind: HookEventKind | null,
+	source?: string,
+): HookNormalizationDiagnostic {
+	return {
+		severity: HookDiagnosticSeverity.Error,
+		code: HookDiagnosticCode.UnsupportedConventionEvent,
+		message: canonicalKind
+			? `Convention "${convention}" does not support canonical event "${canonicalKind}".`
+			: `Convention "${convention}" received unrecognized external event "${externalEvent}".`,
+		convention,
+		externalEvent,
+		canonicalKind: canonicalKind ?? undefined,
+		source,
+	};
+}
+
+function invalid(
+	code: HookDiagnosticCode,
+	message: string,
+	convention: HookSourceConvention,
+	input: { source?: string; externalEvent?: string; canonicalKind?: HookEventKind },
+): NormalizeHookResult {
+	return {
+		hook: null,
+		diagnostics: [{ severity: HookDiagnosticSeverity.Error, code, message, convention, ...input }],
+	};
+}
+
+function validateSource(convention: HookSourceConvention, source: string): NormalizeHookResult | null {
+	if (source.trim()) return null;
+	return invalid(HookDiagnosticCode.InvalidSource, "Hook source provenance must be non-empty.", convention, {
+		source,
+	});
+}
+
+/** Tool identifiers are logical, case-sensitive runtime names, not filesystem paths. */
+export function normalizeToolMatcher(toolName: unknown): string | null {
+	if (typeof toolName !== "string") return null;
+	const normalized = toolName.trim();
+	if (!normalized || normalized === "." || normalized === "..") return null;
+	if (normalized !== toolName) return null;
+	if (normalized !== "*" && (normalized.includes("/") || normalized.includes("\\") || normalized.includes("\0"))) {
+		return null;
+	}
+	return normalized;
+}
+
+function buildHook(
+	convention: HookSourceConvention,
+	kind: HookEventKind,
+	toolName: unknown,
+	source: string,
+): NormalizeHookResult {
+	const sourceFailure = validateSource(convention, source);
+	if (sourceFailure) return sourceFailure;
+	const contract = resolveExecutionContract(convention, kind);
+	if (!contract) return { hook: null, diagnostics: [unsupportedEventDiagnostic(convention, kind, kind, source)] };
+	const matcher = normalizeToolMatcher(toolName);
+	if (!matcher) {
+		return invalid(
+			HookDiagnosticCode.InvalidToolMatcher,
+			`Invalid tool matcher "${toolName}"; matchers are case-sensitive logical names or "*", never paths.`,
+			convention,
+			{ source, canonicalKind: kind },
+		);
+	}
+	return {
+		hook: {
+			kind,
+			authority: contract.authority,
+			convention,
+			runtimeEvent: contract.runtimeEvent,
+			toolName: matcher,
+			source,
+			contract,
+		},
+		diagnostics: [],
+	};
+}
+
+export interface DirectoryHookInput {
+	convention: HookSourceConvention;
+	phase: "pre" | "post";
+	toolName: string;
+	source: string;
+	/** Original discovered filename, when normalization participates in discovery. */
+	externalName?: string;
+}
+
+/** Normalize discovery metadata for native, Claude, or Codex hook modules. */
+export function normalizeDirectoryHook(input: DirectoryHookInput): NormalizeHookResult {
+	if (
+		input.convention !== HookSourceConvention.NativeGjc &&
+		input.convention !== HookSourceConvention.ClaudeCode &&
+		input.convention !== HookSourceConvention.Codex
+	) {
+		const kind = input.phase === "pre" ? HookEventKind.PreToolUse : HookEventKind.PostToolUse;
+		return {
+			hook: null,
+			diagnostics: [unsupportedEventDiagnostic(input.convention, input.phase, kind, input.source)],
+		};
+	}
+	if (input.convention === HookSourceConvention.Codex && input.externalName) {
+		const expectedPrefix = `${input.phase}-`;
+		if (!input.externalName.startsWith(expectedPrefix)) {
+			return invalid(
+				HookDiagnosticCode.SemanticMismatch,
+				`Codex hook filename "${input.externalName}" must use the ${expectedPrefix}<tool>.ts|js convention.`,
+				input.convention,
+				{ source: input.source, externalEvent: input.externalName },
+			);
+		}
+	}
+	return buildHook(
+		input.convention,
+		input.phase === "pre" ? HookEventKind.PreToolUse : HookEventKind.PostToolUse,
+		input.toolName,
+		input.source,
+	);
+}
+
+export interface ManagedJsonHookInput {
+	externalEvent: string;
+	command: string;
+	source: string;
+}
+
+/** Normalize the two GJC-managed Codex hooks.json entries. */
+export function normalizeManagedJsonHook(input: ManagedJsonHookInput): NormalizeHookResult {
+	if (!input.command.trim()) {
+		return invalid(
+			HookDiagnosticCode.InvalidCommand,
+			"Managed hooks.json command must be non-empty.",
+			HookSourceConvention.CodexManagedJson,
+			{ source: input.source, externalEvent: input.externalEvent },
+		);
+	}
+	const kind =
+		input.externalEvent === "UserPromptSubmit"
+			? HookEventKind.UserPromptSubmit
+			: input.externalEvent === "Stop"
+				? HookEventKind.Stop
+				: null;
+	if (!kind) {
+		return {
+			hook: null,
+			diagnostics: [
+				unsupportedEventDiagnostic(HookSourceConvention.CodexManagedJson, input.externalEvent, null, input.source),
+			],
+		};
+	}
+	return buildHook(HookSourceConvention.CodexManagedJson, kind, "*", input.source);
+}
+
+export interface PluginHookInput {
+	declaredEvent: string;
+	target?: unknown;
+	phase?: unknown;
+	plugin: string;
+	source: string;
+}
+
+/** Normalize only manifest shapes that the constrained plugin compiler accepts. */
+export function normalizePluginHook(input: PluginHookInput): NormalizeHookResult {
+	if (input.declaredEvent === "session_start" || input.declaredEvent === "session_shutdown") {
+		if (input.phase !== undefined || input.target !== undefined) {
+			return invalid(
+				HookDiagnosticCode.InvalidPluginPhase,
+				`Plugin "${input.plugin}" ${input.declaredEvent} hooks do not accept target or phase.`,
+				HookSourceConvention.GjcPlugin,
+				{ source: input.source, externalEvent: input.declaredEvent },
+			);
+		}
+		return buildHook(
+			HookSourceConvention.GjcPlugin,
+			input.declaredEvent === "session_start" ? HookEventKind.SessionStart : HookEventKind.SessionShutdown,
+			"*",
+			input.source,
+		);
+	}
+	if (input.declaredEvent !== "tool_call" && input.declaredEvent !== "tool_result") {
+		return invalid(
+			HookDiagnosticCode.UnrecognizedPluginEvent,
+			`Plugin "${input.plugin}" declared unsupported event "${input.declaredEvent}"; aliases cannot expand plugin authority.`,
+			HookSourceConvention.GjcPlugin,
+			{ source: input.source, externalEvent: input.declaredEvent },
+		);
+	}
+
+	if (input.declaredEvent === "tool_call") {
+		if (!input.target || (input.phase !== "before" && input.phase !== "after")) {
+			return invalid(
+				HookDiagnosticCode.InvalidPluginPhase,
+				`Plugin "${input.plugin}" tool_call hooks require both target and before/after phase.`,
+				HookSourceConvention.GjcPlugin,
+				{ source: input.source, externalEvent: input.declaredEvent },
+			);
+		}
+		return buildHook(
+			HookSourceConvention.GjcPlugin,
+			input.phase === "before" ? HookEventKind.PreToolUse : HookEventKind.PostToolUse,
+			input.target,
+			input.source,
+		);
+	}
+
+	if (input.phase !== "after") {
+		return invalid(
+			HookDiagnosticCode.InvalidPluginPhase,
+			`Plugin "${input.plugin}" tool_result hooks require phase "after".`,
+			HookSourceConvention.GjcPlugin,
+			{ source: input.source, externalEvent: input.declaredEvent },
+		);
+	}
+	return buildHook(HookSourceConvention.GjcPlugin, HookEventKind.PostToolUse, input.target ?? "*", input.source);
+}
+
+export interface InProcessHookInput {
+	registeredEvent: string;
+	source: string;
+}
+
+export function normalizeInProcessHook(input: InProcessHookInput): NormalizeHookResult {
+	if (input.registeredEvent === "turn_end") {
+		return invalid(
+			HookDiagnosticCode.SemanticMismatch,
+			"turn_end fires once per turn and is not equivalent to provider Stop/agent_end.",
+			HookSourceConvention.InProcess,
+			{ source: input.source, externalEvent: input.registeredEvent, canonicalKind: HookEventKind.Stop },
+		);
+	}
+	const kind =
+		input.registeredEvent === "before_agent_start"
+			? HookEventKind.UserPromptSubmit
+			: input.registeredEvent === "tool_call"
+				? HookEventKind.PreToolUse
+				: input.registeredEvent === "tool_result"
+					? HookEventKind.PostToolUse
+					: input.registeredEvent === "agent_end"
+						? HookEventKind.Stop
+						: input.registeredEvent === "session_start"
+							? HookEventKind.SessionStart
+							: input.registeredEvent === "session_shutdown"
+								? HookEventKind.SessionShutdown
+								: null;
+	if (!kind) {
+		return {
+			hook: null,
+			diagnostics: [
+				{
+					severity: HookDiagnosticSeverity.Warning,
+					code: HookDiagnosticCode.InProcessEventOutsideIr,
+					message: `In-process event "${input.registeredEvent}" remains on the broader HookAPI and is not normalized.`,
+					convention: HookSourceConvention.InProcess,
+					externalEvent: input.registeredEvent,
+					source: input.source,
+				},
+			],
+		};
+	}
+	return buildHook(HookSourceConvention.InProcess, kind, "*", input.source);
+}
+
+export interface BatchNormalizeResult {
+	hooks: NormalizedHook[];
+	diagnostics: HookNormalizationDiagnostic[];
+}
+
+/** Stable first-wins deduplication; rejected and duplicate entries remain visible as diagnostics. */
+export function normalizeHookBatch(results: ReadonlyArray<NormalizeHookResult>): BatchNormalizeResult {
+	const hooks: NormalizedHook[] = [];
+	const diagnostics: HookNormalizationDiagnostic[] = [];
+	const seen = new Map<string, NormalizedHook>();
+
+	for (const result of results) {
+		diagnostics.push(...result.diagnostics);
+		if (!result.hook) continue;
+		const key = `${result.hook.convention}\0${result.hook.kind}\0${result.hook.toolName}\0${result.hook.source}`;
+		const prior = seen.get(key);
+		if (prior) {
+			diagnostics.push({
+				severity: HookDiagnosticSeverity.Warning,
+				code: HookDiagnosticCode.DuplicateHook,
+				message: `Duplicate hook descriptor ignored; first occurrence remains ordered first.`,
+				convention: result.hook.convention,
+				canonicalKind: result.hook.kind,
+				source: result.hook.source,
+			});
+			continue;
+		}
+		seen.set(key, result.hook);
+		hooks.push(result.hook);
+	}
+
+	return { hooks, diagnostics };
+}