@gajae-code/coding-agent 0.16.4 → 0.16.6

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

@@ -1,3 +1,8 @@
+import {
+	FUNCTION_HOOK_CAPABILITIES,
+	type FunctionHookCapability,
+	normalizeFunctionHookGrant,
+} from "../extensions/function-hooks";
 import {
 	GJC_PLUGIN_KIND,
 	GJC_SUBSKILL_PARENT_AGENTS,
@@ -94,6 +99,23 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function rejectUnknownKeys(
+	value: Record<string, unknown>,
+	allowed: readonly string[],
+	context: string,
+	manifestPath: string,
+): void {
+	const allowedSet = new Set(allowed);
+	for (const key of Object.keys(value)) {
+		if (!allowedSet.has(key)) {
+			throw new GjcPluginLoadError(
+				"unsupported_surface",
+				`Unsupported GJC plugin field "${key}" at ${context} (${manifestPath}); supported fields are ${[...allowed].sort().join(", ")}`,
+			);
+		}
+	}
+}
+
 function requireNonEmptyString(value: unknown, field: string, filePath: string): string {
 	if (typeof value !== "string" || value.trim().length === 0) {
 		throw new GjcPluginLoadError(
@@ -221,6 +243,23 @@ function parseTools(value: unknown, manifestPath: string): GjcPluginToolManifest
 				`Invalid GJC plugin manifest at ${manifestPath}: tools[${index}] must be a string or object`,
 			);
 		}
+		rejectUnknownKeys(
+			entry,
+			[
+				"name",
+				"path",
+				"description",
+				"sha256",
+				"schemaPath",
+				"schema_path",
+				"schema",
+				"inputSchema",
+				"input_schema",
+				"parameters",
+			],
+			`tools[${index}]`,
+			manifestPath,
+		);
 		const name = manifestSafeName(entry.name, `tools[${index}].name`, manifestPath);
 		const path = manifestString(entry.path, `tools[${index}].path`, manifestPath);
 		const description =
@@ -258,6 +297,25 @@ function parseHooks(value: unknown, manifestPath: string): GjcPluginHookManifest
 				`Invalid GJC plugin manifest at ${manifestPath}: hooks[${index}] must be an object`,
 			);
 		}
+		const allowedKeys = new Set([
+			"name",
+			"event",
+			"target",
+			"phase",
+			"path",
+			"sha256",
+			"capabilities",
+			"networkDestinations",
+			"filesystemRoots",
+		]);
+		for (const key of Object.keys(entry)) {
+			if (!allowedKeys.has(key)) {
+				throw new GjcPluginLoadError(
+					"unsupported_surface",
+					`Unsupported GJC plugin hook field "${key}" at ${manifestPath}; supported fields are ${[...allowedKeys].sort().join(", ")}`,
+				);
+			}
+		}
 		const name = manifestSafeName(entry.name, `hooks[${index}].name`, manifestPath);
 		// event/target become part of the hook surface ID
 		// (`hook:<event>:<phase>:<target>:<name>`), which is rendered and printed.
@@ -266,7 +324,9 @@ function parseHooks(value: unknown, manifestPath: string): GjcPluginHookManifest
 		const target =
 			entry.target === undefined
 				? undefined
-				: manifestSafeName(entry.target, `hooks[${index}].target`, manifestPath);
+				: entry.target === "*"
+					? "*"
+					: manifestSafeName(entry.target, `hooks[${index}].target`, manifestPath);
 		let phase: "before" | "after" | undefined;
 		if (entry.phase !== undefined) {
 			if (entry.phase !== "before" && entry.phase !== "after") {
@@ -279,7 +339,41 @@ function parseHooks(value: unknown, manifestPath: string): GjcPluginHookManifest
 		}
 		const sha256 =
 			entry.sha256 === undefined ? undefined : manifestString(entry.sha256, `hooks[${index}].sha256`, manifestPath);
-		return { name, event, target, phase, path, sha256 };
+		let capabilities: FunctionHookCapability[] | undefined;
+		if (entry.capabilities !== undefined) {
+			if (
+				!Array.isArray(entry.capabilities) ||
+				!entry.capabilities.every(
+					capability =>
+						typeof capability === "string" &&
+						FUNCTION_HOOK_CAPABILITIES.includes(capability as FunctionHookCapability),
+				)
+			) {
+				throw new GjcPluginLoadError(
+					"unsupported_surface",
+					`Invalid GJC plugin hook capabilities at ${manifestPath}: use only ${FUNCTION_HOOK_CAPABILITIES.join(", ")}`,
+				);
+			}
+			capabilities = [...(entry.capabilities as FunctionHookCapability[])];
+		}
+		const parseStringArray = (field: "networkDestinations" | "filesystemRoots"): string[] | undefined => {
+			const value = entry[field];
+			if (value === undefined) return undefined;
+			if (!Array.isArray(value) || !value.every(item => typeof item === "string"))
+				throw new GjcPluginLoadError(
+					"invalid_manifest",
+					`Invalid ${field} at ${manifestPath}: expected a string array`,
+				);
+			return [...(value as string[])];
+		};
+		const networkDestinations = parseStringArray("networkDestinations");
+		const filesystemRoots = parseStringArray("filesystemRoots");
+		try {
+			normalizeFunctionHookGrant({ capabilities, networkDestinations, filesystemRoots });
+		} catch (error) {
+			throw new GjcPluginLoadError("invalid_manifest", error instanceof Error ? error.message : String(error));
+		}
+		return { name, event, target, phase, path, sha256, capabilities, networkDestinations, filesystemRoots };
 	});
 }
 
@@ -290,6 +384,12 @@ function parseMcpEntry(entry: unknown, field: string, manifestPath: string): Gjc
 			`Invalid GJC plugin manifest at ${manifestPath}: ${field} must be an object`,
 		);
 	}
+	rejectUnknownKeys(
+		entry,
+		["name", "transport", "command", "args", "cwd", "url", "headers", "sha256"],
+		field,
+		manifestPath,
+	);
 	const name = manifestSafeName(entry.name, `${field}.name`, manifestPath);
 	const transport = entry.transport;
 	if (typeof transport !== "string" || !MCP_TRANSPORTS.includes(transport as GjcPluginMcpTransport)) {
@@ -430,13 +530,24 @@ function pickOptional(entry: Record<string, unknown>, keys: readonly string[]):
 	return out;
 }
 
-function parseAppendixEntry(entry: unknown, field: string, manifestPath: string): GjcPluginAppendixManifestEntry {
+function parseAppendixEntry(
+	entry: unknown,
+	field: string,
+	manifestPath: string,
+	allowAgent = false,
+): GjcPluginAppendixManifestEntry {
 	if (!isRecord(entry)) {
 		throw new GjcPluginLoadError(
 			"invalid_manifest",
 			`Invalid GJC plugin manifest at ${manifestPath}: ${field} must be an object`,
 		);
 	}
+	rejectUnknownKeys(
+		entry,
+		allowAgent ? ["name", "path", "content", "sha256", "agent"] : ["name", "path", "content", "sha256"],
+		field,
+		manifestPath,
+	);
 	const name = manifestSafeName(entry.name, `${field}.name`, manifestPath);
 	const path = entry.path === undefined ? undefined : manifestString(entry.path, `${field}.path`, manifestPath);
 	// Content may be empty/whitespace here; the compiler enforces non-empty and
@@ -461,7 +572,7 @@ function parseSystemAppendix(value: unknown, manifestPath: string): GjcPluginApp
 function parseAgentAppendix(value: unknown, manifestPath: string): GjcPluginAgentAppendixManifestEntry[] {
 	const raw = optionalArray(value, "agent-appendix", manifestPath);
 	return raw.map((entry, index) => {
-		const base = parseAppendixEntry(entry, `agent-appendix[${index}]`, manifestPath);
+		const base = parseAppendixEntry(entry, `agent-appendix[${index}]`, manifestPath, true);
 		const agent = (entry as Record<string, unknown>).agent;
 		if (typeof agent !== "string" || !GJC_SUBSKILL_PARENT_AGENTS.includes(agent as GjcSubskillParentAgent)) {
 			throw new GjcPluginLoadError(
@@ -553,6 +664,12 @@ export function parseManifest(raw: unknown, manifestPath: string): GjcPluginMani
 }
 
 export function parseSubskillFrontmatter(fm: Record<string, unknown>, filePath: string): SubskillFrontmatter {
+	rejectUnknownKeys(
+		fm,
+		["name", "binds_to", "phase", "activation_arg", "description", "tools"],
+		"frontmatter",
+		filePath,
+	);
 	return {
 		// Name and activation_arg become part of the surface ID
 		// (`subskill:<parent>:<phase>:<arg>`) and are rendered, so they share the

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

@@ -1,5 +1,6 @@
 import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
 import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../../skill-state/active-state";
+import type { FunctionHookCapability } from "../extensions/function-hooks";
 
 export const GJC_PLUGIN_MANIFEST_FILENAME = "gajae-plugin.json";
 export const GJC_PLUGIN_KIND = "gajae-code-plugin";
@@ -48,6 +49,10 @@ export interface GjcPluginHookManifestEntry {
 	phase?: "before" | "after";
 	path: string;
 	sha256?: string;
+	/** Requested capability families; the runtime never grants more than declared. */
+	capabilities?: FunctionHookCapability[];
+	networkDestinations?: string[];
+	filesystemRoots?: string[];
 }
 
 export type GjcPluginMcpTransport = "stdio" | "http" | "sse";
@@ -290,6 +295,11 @@ export interface NormalizedHookSurface {
 	relativePath: string;
 	sha256: string;
 	implementationHash?: string;
+	capabilities?: FunctionHookCapability[];
+	networkDestinations?: string[];
+	filesystemRoots?: string[];
+	capabilityHash?: string;
+	functionHook?: boolean;
 }
 
 export interface NormalizedMcpSurface {
@@ -522,6 +532,21 @@ export interface GjcRuntimeFinding {
 	surfaceId: string;
 	code: GjcPluginLoadErrorCode;
 	message: string;
+	decision?: "loaded" | "quarantined" | "blocked" | "error";
+	event?: string;
+	phase?: "before" | "after";
+	requestedCapabilities?: readonly FunctionHookCapability[];
+	effectiveCapabilities?: readonly FunctionHookCapability[];
+	capabilityHash?: string;
+	provenance?: {
+		source: "builtin" | "user" | "project" | "extension" | "plugin-bundle";
+		scope?: "user" | "project" | "native";
+		plugin?: string;
+		path?: string;
+		extensionId?: string;
+	};
+	audit?: Record<string, unknown>;
+	generation?: number;
 }
 
 export interface GjcRuntimeSnapshot {

package/src/extensibility/hooks/loader.ts

@@ -11,6 +11,24 @@ 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 {
+	DEFAULT_EXTENSION_FUNCTION_HOOK_GRANT,
+	type FunctionHook,
+	type FunctionHookEventType,
+	type FunctionHookPayloadFor,
+	type FunctionHookRegistration,
+	type FunctionHookRegistrationOptions,
+	intersectFunctionHookGrants,
+	normalizeFunctionHookGrant,
+	validateFunctionHookTarget,
+} from "../extensions/function-hooks";
+import {
+	getExtensionHandlerRegistrationOrder,
+	getFunctionHookRegistration,
+	tagExtensionHandlerRegistrationOrder,
+	tagFunctionHookHandler,
+	wrapExtensionHandlerRegistration,
+} from "../extensions/function-hooks-internal";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -114,6 +132,7 @@ export interface LoadHookExtensionsResult {
 async function createHookAPI(
 	handlers: Map<string, HandlerFn[]>,
 	cwd: string,
+	sourcePath: string,
 ): Promise<{
 	api: HookAPI;
 	messageRenderers: Map<string, HookMessageRenderer>;
@@ -125,6 +144,7 @@ async function createHookAPI(
 	let appendEntryHandler: AppendEntryHandler | null = null;
 	const messageRenderers = new Map<string, HookMessageRenderer>();
 	const commands = new Map<string, RegisteredCommand>();
+	let handlerRegistrationOrder = 0;
 
 	// Cast to HookAPI - the implementation is more general (string event names)
 	// but the interface has specific overloads for type safety in hooks
@@ -133,7 +153,7 @@ async function createHookAPI(
 			if (!handlers.has(event)) {
 				handlers.set(event, []);
 			}
-			handlers.get(event)!.push(handler);
+			handlers.get(event)!.push(wrapExtensionHandlerRegistration(handler, handlerRegistrationOrder++));
 		},
 		sendMessage<T = unknown>(
 			message: HookMessage<T>,
@@ -156,6 +176,39 @@ async function createHookAPI(
 		registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void {
 			commands.set(name, { name, ...options });
 		},
+		registerFunctionHook<T extends FunctionHookEventType>(
+			event: T,
+			handler: FunctionHook<FunctionHookPayloadFor<T>>,
+			options: FunctionHookRegistrationOptions = {},
+		): void {
+			if (options.target !== undefined) {
+				if (event === "*") throw new Error("Wildcard function hooks cannot declare a target");
+				if (event !== "tool_call" && event !== "tool_result")
+					throw new Error("Function hook targets are only valid for tool_call and tool_result events");
+				if (options.target !== "*") validateFunctionHookTarget(options.target);
+			}
+			const registrationOrder = handlerRegistrationOrder++;
+			const registration: FunctionHookRegistration = {
+				event,
+				...(options.target === undefined ? {} : { target: options.target }),
+				...(options.registrationId === undefined ? {} : { registrationId: options.registrationId }),
+				registrationOrder,
+				handler: handler as unknown as FunctionHook,
+				grant: intersectFunctionHookGrants(
+					normalizeFunctionHookGrant(options),
+					DEFAULT_EXTENSION_FUNCTION_HOOK_GRANT,
+				),
+				provenance: { source: "extension", path: sourcePath, extensionId: sourcePath },
+			};
+			const list = handlers.get(event) ?? [];
+			list.push(
+				tagExtensionHandlerRegistrationOrder(
+					tagFunctionHookHandler(registration) as unknown as HandlerFn,
+					registrationOrder,
+				),
+			);
+			handlers.set(event, list);
+		},
 		exec(command: string, args: string[], options?: ExecOptions) {
 			return execCommand(command, args, options?.cwd ?? cwd, options);
 		},
@@ -198,6 +251,7 @@ async function loadHook(hookPath: string, cwd: string): Promise<{ hook: LoadedHo
 		const { api, messageRenderers, commands, setSendMessageHandler, setAppendEntryHandler } = await createHookAPI(
 			handlers,
 			cwd,
+			resolvedPath,
 		);
 
 		// Call factory to register handlers
@@ -258,6 +312,27 @@ export async function discoverAndLoadHooks(configuredPaths: string[], cwd: strin
 	const seen = new Set<string>();
 	const normalizationErrors: Array<{ path: string; error: string }> = [];
 	const normalizationByPath = new Map<string, NormalizedHook>();
+	const normalizeExplicitPath = (inputPath: string): NormalizedHook | undefined => {
+		const resolved = resolvePath(inputPath, cwd);
+		const phase = path.basename(path.dirname(resolved));
+		if (phase !== "pre" && phase !== "post") return undefined;
+		const fileName = path.basename(resolved);
+		const toolName = fileName.includes(".") ? fileName.slice(0, fileName.lastIndexOf(".")) : fileName;
+		const normalized = normalizeDirectoryHook({
+			convention: HookSourceConvention.NativeGjc,
+			phase,
+			toolName: toolName === "*" ? "*" : toolName,
+			source: resolved,
+			externalName: fileName,
+		});
+		if (!normalized.hook) {
+			normalizationErrors.push({
+				path: resolved,
+				error: normalized.diagnostics.map(diagnostic => `${diagnostic.code}: ${diagnostic.message}`).join("; "),
+			});
+		}
+		return normalized.hook ?? undefined;
+	};
 
 	// Helper to add paths without duplicates
 	const addPaths = (paths: string[]) => {
@@ -297,13 +372,18 @@ export async function discoverAndLoadHooks(configuredPaths: string[], cwd: strin
 				});
 				continue;
 			}
-			normalizationByPath.set(path.resolve(hook.path), normalized.hook);
+			normalizationByPath.set(resolvePath(hook.path, cwd), normalized.hook);
 		}
 		addPaths([hook.path]);
 	}
 
 	// 2. Explicitly configured paths (can override/add)
-	addPaths(configuredPaths.map(p => resolvePath(p, cwd)));
+	for (const configuredPath of configuredPaths) {
+		const resolved = resolvePath(configuredPath, cwd);
+		const normalized = normalizeExplicitPath(resolved);
+		if (normalized) normalizationByPath.set(resolved, normalized);
+		addPaths([resolved]);
+	}
 
 	const loaded = await loadHooks(allPaths, cwd);
 	for (const hook of loaded.hooks) {
@@ -352,23 +432,60 @@ function createHookExtensionFactory(hook: LoadedHook): ExtensionFactory {
 		hook.setSendMessageHandler((message, options) => api.sendMessage(message, options));
 		hook.setAppendEntryHandler((customType, data) => api.appendEntry(customType, data));
 
+		const orderedHandlers: Array<{ event: string; handler: HandlerFn; order: number; fallback: number }> = [];
+		let fallback = 0;
 		for (const [event, handlers] of hook.handlers) {
 			for (const handler of handlers) {
+				orderedHandlers.push({
+					event,
+					handler,
+					order:
+						getExtensionHandlerRegistrationOrder(handler) ??
+						getFunctionHookRegistration(handler)?.registrationOrder ??
+						Number.MAX_SAFE_INTEGER,
+					fallback: fallback++,
+				});
+			}
+		}
+		orderedHandlers.sort((a, b) => a.order - b.order || a.fallback - b.fallback);
+
+		for (const { event, handler } of orderedHandlers) {
+			const functionRegistration = getFunctionHookRegistration(handler);
+			if (functionRegistration) {
 				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);
+				const normalizedTarget = normalized && normalized.toolName !== "*" ? normalized.toolName : undefined;
+				if (
+					normalized &&
+					(functionRegistration.event !== normalized.runtimeEvent ||
+						(functionRegistration.target !== undefined && functionRegistration.target !== normalizedTarget))
+				) {
+					throw new Error("Function hook registration conflicts with its normalized discovery target");
+				}
+				api.registerFunctionHook(functionRegistration.event, functionRegistration.handler, {
+					...(normalizedTarget === undefined && functionRegistration.target === undefined
+						? {}
+						: { target: normalizedTarget ?? functionRegistration.target }),
+					...(functionRegistration.registrationId === undefined
+						? {}
+						: { registrationId: functionRegistration.registrationId }),
+					...functionRegistration.grant,
+				});
+				continue;
 			}
+			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) {

package/src/extensibility/hooks/types.ts

@@ -7,6 +7,12 @@ import type { Theme } from "../../modes/theme/theme";
 import type { HookMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
 import type { BashToolDetails, FindToolDetails, ReadToolDetails, SearchToolDetails } from "../../tools";
+import type {
+	FunctionHook,
+	FunctionHookEventType,
+	FunctionHookPayloadFor,
+	FunctionHookRegistrationOptions,
+} from "../extensions/function-hooks";
 import type {
 	AgentEndEvent,
 	AgentStartEvent,
@@ -42,6 +48,23 @@ import type {
 
 // Re-export for backward compatibility
 export type { ExecOptions, ExecResult } from "../../exec/exec";
+/** Capability-scoped Function Hooks share the ExtensionRunner event contract. */
+export type {
+	FunctionHook,
+	FunctionHookAuditRecord,
+	FunctionHookCapabilities,
+	FunctionHookCapability,
+	FunctionHookEventType,
+	FunctionHookGrant,
+	FunctionHookGrantInput,
+	FunctionHookNext,
+	FunctionHookOperation,
+	FunctionHookPayloadFor,
+	FunctionHookProvenance,
+	FunctionHookRegistration,
+	FunctionHookRegistrationOptions,
+	FunctionHookResult,
+} from "../extensions/function-hooks";
 
 /**
  * UI context for hooks to request interactive UI from the harness.
@@ -499,6 +522,11 @@ export interface HookAPI {
 	on(event: "todo_reminder", handler: HookHandler<TodoReminderEvent>): void;
 	on(event: "tool_call", handler: HookHandler<ToolCallEvent, ToolCallEventResult>): void;
 	on(event: "tool_result", handler: HookHandler<ToolResultEvent, ToolResultEventResult>): void;
+	registerFunctionHook<T extends FunctionHookEventType>(
+		event: T,
+		handler: FunctionHook<FunctionHookPayloadFor<T>>,
+		options?: FunctionHookRegistrationOptions,
+	): void;
 
 	/**
 	 * Send a custom message to the session. Creates a CustomMessageEntry that