@gajae-code/coding-agent 0.16.3 → 0.16.6

package/src/extensibility/extensions/types.ts

@@ -49,6 +49,7 @@ import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/workflow-gate-broker";
 import type { Theme } from "../../modes/theme/theme";
+import type { AgentSessionEventListener } from "../../session/agent-session";
 import type {
 	ClientBridge,
 	ClientBridgePermissionOption,
@@ -103,6 +104,12 @@ import type {
 	TurnStartEvent,
 } from "../shared-events";
 import type { SlashCommandInfo } from "../slash-commands";
+import type {
+	FunctionHook,
+	FunctionHookEventType,
+	FunctionHookPayloadFor,
+	FunctionHookRegistrationOptions,
+} from "./function-hooks";
 
 export type { AppKeybinding, KeybindingsManager } from "../../config/keybindings";
 export type { ExecOptions, ExecResult } from "../../exec/exec";
@@ -530,6 +537,8 @@ export interface ExtensionContext {
 	getJobs(): unknown;
 	/** Subscribe to foreground-wait folds (`bash_folded`). Returns an unsubscribe function. */
 	onJobFold?(listener: (event: JobFoldEvent) => void): () => void;
+	/** Observe session events synchronously in producer order. Returns an unsubscribe function. */
+	onSessionEvent?(listener: AgentSessionEventListener): () => void;
 	/** Typed skill and mode controls exposed to the SDK host. */
 	invokeSkill?(
 		name: string,
@@ -750,6 +759,8 @@ export type { AgentEndEvent, TurnEndEvent, TurnStartEvent } from "../shared-even
 /** Fired when an agent loop starts. `sdkRunToken` is an internal SDK queue-owner binding. */
 export interface AgentStartEvent extends SharedAgentStartEvent {
 	sdkRunToken?: string;
+	/** Complete set of SDK queue owners consumed together by this run. */
+	sdkRunTokens?: string[];
 }
 
 /** Fired when an agent run fails before emitting agent_end. The error is the
@@ -1234,6 +1245,18 @@ export interface ExtensionAPI {
 	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
 	on(event: "user_python", handler: ExtensionHandler<UserPythonEvent, UserPythonEventResult>): void;
 
+	/**
+	 * Register capability-scoped middleware on the authoritative ExtensionRunner.
+	 * The host supplies grants; an extension cannot self-grant capabilities.
+	 * Wildcard registrations receive a redacted payload unless the host explicitly
+	 * grants a tool inspection/transform capability.
+	 */
+	registerFunctionHook<T extends FunctionHookEventType>(
+		event: T,
+		handler: FunctionHook<FunctionHookPayloadFor<T>>,
+		options?: FunctionHookRegistrationOptions,
+	): void;
+
 	// =========================================================================
 	// Tool Registration
 	// =========================================================================
@@ -1692,6 +1715,8 @@ export interface ExtensionContextActions {
 	getJobs?: () => unknown;
 	/** Subscribe to foreground-wait folds so the SDK host can publish `bash_folded`. Returns an unsubscribe. */
 	onJobFold?: (listener: (event: JobFoldEvent) => void) => () => void;
+	/** Ordered, synchronous AgentSession subscription, independent of async extension hooks. */
+	onSessionEvent?: (listener: AgentSessionEventListener) => () => void;
 	setSdkPermissionProvider?: (
 		provider:
 			| ((
@@ -1752,6 +1777,23 @@ export interface Extension {
 	shortcuts: Map<KeyId, ExtensionShortcut>;
 }
 
+export type {
+	FunctionHook,
+	FunctionHookAuditRecord,
+	FunctionHookCapabilities,
+	FunctionHookCapability,
+	FunctionHookEventType,
+	FunctionHookGrant,
+	FunctionHookGrantInput,
+	FunctionHookNext,
+	FunctionHookOperation,
+	FunctionHookPayloadFor,
+	FunctionHookProvenance,
+	FunctionHookRegistration,
+	FunctionHookRegistrationOptions,
+	FunctionHookResult,
+} from "./function-hooks";
+
 /** Result of loading extensions. */
 export interface LoadExtensionsResult {
 	extensions: Extension[];

package/src/extensibility/extensions/wrapper.ts

@@ -2,12 +2,24 @@
  * Tool wrappers for extensions.
  */
 import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@gajae-code/agent-core";
-import type { ImageContent, Static, TextContent, TSchema } from "@gajae-code/ai/core";
+import {
+	type ImageContent,
+	type Static,
+	type TextContent,
+	type ToolCall,
+	type TSchema,
+	validateToolArguments,
+} from "@gajae-code/ai/core";
 import type { Theme } from "../../modes/theme/theme";
+import { ToolAbortError } from "../../tools/tool-errors";
 import { applyToolProxy } from "../tool-proxy";
 import type { ExtensionRunner } from "./runner";
 import type { RegisteredTool, ToolCallEventResult } from "./types";
 
+function toolAbortReason(signal: AbortSignal | undefined, fallback: string): Error {
+	return signal?.reason instanceof Error ? signal.reason : new ToolAbortError(fallback);
+}
+
 /**
  * Adapts a RegisteredTool into an AgentTool.
  */
@@ -92,6 +104,11 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		applyToolProxy(tool, this);
 	}
 
+	/** Host composition hook: guards must run inside Function Hook preflight. */
+	getInnerTool(): AgentTool<TParameters, TDetails> {
+		return this.tool;
+	}
+
 	/**
 	 * Forward browser mode changes when available.
 	 */
@@ -109,19 +126,21 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		context?: AgentToolContext,
 	) {
 		const scope = context?.attemptScope;
+		const toolCallEvent = {
+			type: "tool_call" as const,
+			toolName: this.tool.name,
+			toolCallId,
+			input: params as Record<string, unknown>,
+		};
 		// Emit tool_call event - extensions can block execution
 		if (this.runner.hasHandlers("tool_call")) {
 			try {
-				const callResult = (await this.runner.emitToolCall(
-					{
-						type: "tool_call",
-						toolName: this.tool.name,
-						toolCallId,
-						input: params as Record<string, unknown>,
-					},
-					scope,
-				)) as ToolCallEventResult | undefined;
+				const callResult = (await this.runner.emitToolCall(toolCallEvent, scope, {
+					signal,
+					correlationId: toolCallId,
+				})) as ToolCallEventResult | undefined;
 
+				if (signal?.aborted) throw toolAbortReason(signal, "Tool call aborted during Function Hook mediation");
 				if (callResult?.block) {
 					const reason = callResult.reason || "Tool execution was blocked by an extension";
 					throw new Error(reason);
@@ -133,14 +152,28 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 				throw new Error(`Extension failed, blocking execution: ${String(err)}`);
 			}
 		}
+		if (toolCallEvent.input !== params || !this.tool.lenientArgValidation) {
+			params = validateToolArguments(this.tool, {
+				type: "toolCall",
+				id: toolCallId,
+				name: this.tool.name,
+				arguments: toolCallEvent.input,
+			} satisfies ToolCall) as Static<TParameters>;
+		}
 
 		// Execute the actual tool
 		let result: { content: any; details?: TDetails };
 		let executionError: Error | undefined;
+		const mediatesToolResult = this.runner.hasToolResultMediation(this.tool.name);
+		const deliversToolResult = this.runner.hasHandlers("tool_result");
+		const effectiveOnUpdate = mediatesToolResult ? undefined : onUpdate;
 
 		try {
-			result = await this.tool.execute(toolCallId, params, signal, onUpdate, context);
+			result = await this.tool.execute(toolCallId, params, signal, effectiveOnUpdate, context);
 		} catch (err) {
+			if (err instanceof ToolAbortError || signal?.aborted) {
+				throw err instanceof ToolAbortError ? err : toolAbortReason(signal, "Tool execution aborted");
+			}
 			executionError = err instanceof Error ? err : new Error(String(err));
 			result = {
 				content: [{ type: "text", text: executionError.message }],
@@ -149,7 +182,8 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		}
 
 		// Emit tool_result event - extensions can modify the result and error status
-		if (this.runner.hasHandlers("tool_result")) {
+		if (signal?.aborted) throw toolAbortReason(signal, "Tool execution aborted");
+		if (deliversToolResult) {
 			const resultResult = await this.runner.emitToolResult(
 				{
 					type: "tool_result",
@@ -161,11 +195,17 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 					isError: !!executionError,
 				},
 				scope,
+				{ signal, correlationId: toolCallId },
 			);
+			if (signal?.aborted) throw toolAbortReason(signal, "Tool result mediation aborted");
 
 			if (resultResult) {
-				const modifiedContent: (TextContent | ImageContent)[] = resultResult.content ?? result.content;
-				const modifiedDetails = (resultResult.details ?? result.details) as TDetails;
+				const modifiedContent: (TextContent | ImageContent)[] = Object.hasOwn(resultResult, "content")
+					? (resultResult.content ?? [])
+					: result.content;
+				const modifiedDetails = (
+					Object.hasOwn(resultResult, "details") ? resultResult.details : result.details
+				) as TDetails;
 
 				// Extension can override error status
 				if (resultResult.isError === true && !executionError) {
@@ -181,7 +221,8 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 
 				// Error status unchanged, but content/details may be modified
 				if (executionError) {
-					throw executionError;
+					const textBlocks = modifiedContent.filter((content): content is TextContent => content.type === "text");
+					throw new Error(textBlocks.map(content => content.text).join("\n") || "Tool execution failed");
 				}
 				return { content: modifiedContent, details: modifiedDetails };
 			}

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

@@ -1,8 +1,11 @@
 import { createHash } from "node:crypto";
+import * as nodeFs from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { parseFrontmatter, pathIsWithin } from "@gajae-code/utils";
-import { readSchemaDeclaration, schemaHash } from "./metadata";
+import { functionHookGrantHash, normalizeFunctionHookGrant } from "../extensions/function-hooks";
+import { classifyStdioInvocation } from "./mcp-policy";
+import { canonicalizeJsonSchema, extractDeclaredToolSchema, schemaHash } from "./metadata";
 import { resolveWithinRoot } from "./paths";
 import { parseManifest, parseSubskillFrontmatter } from "./schema";
 import {
@@ -10,6 +13,7 @@ import {
 	type GjcPluginAppendixManifestEntry,
 	GjcPluginLoadError,
 	type GjcPluginMcpManifestEntry,
+	type JsonSchema202012,
 	type NormalizedAgentAppendixSurface,
 	type NormalizedAppendixSurface,
 	type NormalizedGjcPluginBundle,
@@ -22,6 +26,101 @@ import {
 } from "./types";
 import { validateBinding } from "./validation";
 
+const PLUGIN_FILE_MAX_BYTES = 16 * 1024 * 1024;
+const PLUGIN_MANIFEST_MAX_BYTES = PLUGIN_FILE_MAX_BYTES;
+const PLUGIN_FILE_OPEN_FLAGS =
+	nodeFs.constants.O_RDONLY | (process.platform === "win32" ? 0 : (nodeFs.constants.O_NOFOLLOW ?? 0));
+
+interface FileIdentity {
+	dev: bigint;
+	ino: bigint;
+}
+
+interface FileAuthority {
+	path: string;
+	realPath: string;
+	identity: FileIdentity;
+}
+
+interface ManifestSnapshot {
+	bytes: Buffer;
+	json: unknown;
+}
+
+function sameIdentity(left: FileIdentity, right: FileIdentity): boolean {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+
+function errorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+		? error.code
+		: undefined;
+}
+
+function tooLarge(rel: string, maxBytes: number): GjcPluginLoadError {
+	return new GjcPluginLoadError("security_policy", `GJC plugin file exceeds ${maxBytes} bytes: ${rel}`);
+}
+
+async function readBoundedFile(file: FileAuthority, rel: string, maxBytes: number): Promise<Buffer> {
+	let handle: fs.FileHandle;
+	try {
+		handle = await fs.open(file.path, PLUGIN_FILE_OPEN_FLAGS);
+	} catch (error) {
+		if (errorCode(error) === "ELOOP") {
+			throw new GjcPluginLoadError("security_policy", `GJC plugin path became a symlink before opening: ${rel}`, {
+				cause: error instanceof Error ? error : undefined,
+			});
+		}
+		throw error;
+	}
+	try {
+		const before = await handle.stat({ bigint: true });
+		if (!before.isFile()) {
+			throw new GjcPluginLoadError("security_policy", `GJC plugin path is not a regular file: ${rel}`);
+		}
+		if (!sameIdentity(file.identity, before)) {
+			throw new GjcPluginLoadError("security_policy", `GJC plugin file changed before opening: ${rel}`);
+		}
+		const [settledRealPath, settledPath] = await Promise.all([
+			fs.realpath(file.path),
+			fs.lstat(file.path, { bigint: true }),
+		]);
+		if (
+			settledRealPath !== file.realPath ||
+			settledPath.isSymbolicLink() ||
+			!settledPath.isFile() ||
+			!sameIdentity(settledPath, before)
+		) {
+			throw new GjcPluginLoadError("security_policy", `GJC plugin file changed before reading: ${rel}`);
+		}
+		if (before.size > BigInt(maxBytes)) throw tooLarge(rel, maxBytes);
+		const chunks: Buffer[] = [];
+		let offset = 0;
+		for (;;) {
+			const remaining = maxBytes + 1 - offset;
+			if (remaining <= 0) throw tooLarge(rel, maxBytes);
+			const chunk = Buffer.allocUnsafe(Math.min(1024 * 1024, remaining));
+			const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, offset);
+			if (bytesRead === 0) break;
+			chunks.push(chunk.subarray(0, bytesRead));
+			offset += bytesRead;
+		}
+		const after = await handle.stat({ bigint: true });
+		if (
+			!sameIdentity(before, after) ||
+			before.size !== after.size ||
+			before.mtimeNs !== after.mtimeNs ||
+			before.ctimeNs !== after.ctimeNs ||
+			BigInt(offset) !== after.size
+		) {
+			throw new GjcPluginLoadError("security_policy", `GJC plugin file changed while reading: ${rel}`);
+		}
+		return Buffer.concat(chunks, offset);
+	} finally {
+		await handle.close();
+	}
+}
+
 function sha256(bytes: Buffer | string): string {
 	return createHash("sha256").update(bytes).digest("hex");
 }
@@ -43,17 +142,19 @@ export const surfaceIds = {
 		`subskill-tool:${parent}:${phase}:${activationArg}:${relativePath}`,
 } as const;
 
-async function readManifestJson(filePath: string): Promise<unknown> {
-	let text: string;
+async function readManifestSnapshot(pluginRoot: string, filePath: string): Promise<ManifestSnapshot> {
+	let bytes: Buffer;
 	try {
-		text = await fs.readFile(filePath, "utf8");
+		const file = await resolveDeclaredFile(pluginRoot, GJC_PLUGIN_MANIFEST_FILENAME);
+		bytes = await readBoundedFile(file, GJC_PLUGIN_MANIFEST_FILENAME, PLUGIN_MANIFEST_MAX_BYTES);
 	} catch (error) {
+		if (error instanceof GjcPluginLoadError && error.code !== "missing_file") throw error;
 		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin manifest at ${filePath}`, {
 			cause: error instanceof Error ? error : undefined,
 		});
 	}
 	try {
-		return JSON.parse(text) as unknown;
+		return { bytes, json: JSON.parse(bytes.toString("utf8")) as unknown };
 	} catch (error) {
 		throw new GjcPluginLoadError("invalid_manifest", `Invalid GJC plugin manifest JSON at ${filePath}`, {
 			cause: error instanceof Error ? error : undefined,
@@ -61,37 +162,64 @@ async function readManifestJson(filePath: string): Promise<unknown> {
 	}
 }
 
+async function resolveDeclaredDirectory(pluginRoot: string, rel: string): Promise<string> {
+	const resolved = resolveWithinRoot(pluginRoot, rel || ".");
+	let stat: Awaited<ReturnType<typeof fs.lstat>>;
+	try {
+		stat = await fs.lstat(resolved);
+	} catch (error) {
+		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin directory at ${resolved}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	if (!stat.isDirectory()) {
+		throw new GjcPluginLoadError("security_policy", `GJC plugin cwd must be a real directory: ${rel || "."}`);
+	}
+	const [realRoot, real] = await Promise.all([fs.realpath(pluginRoot), fs.realpath(resolved)]);
+	if (real !== realRoot && !pathIsWithin(realRoot, real)) {
+		throw new GjcPluginLoadError("security_policy", `GJC plugin cwd escapes root via symlink: ${rel || "."}`);
+	}
+	return resolved;
+}
+
 /**
  * Resolve a declared relative path, rejecting lexical escapes AND symlink
  * escapes out of the plugin root. Never imports the file.
  */
-async function resolveDeclaredFile(pluginRoot: string, rel: string): Promise<string> {
+async function resolveDeclaredFile(pluginRoot: string, rel: string): Promise<FileAuthority> {
 	const resolved = resolveWithinRoot(pluginRoot, rel);
-	let real: string;
+	let realRoot: string;
+	let realPath: string;
+	let stat: nodeFs.BigIntStats;
 	try {
-		real = await fs.realpath(resolved);
+		realRoot = await fs.realpath(pluginRoot);
+		realPath = await fs.realpath(resolved);
+		stat = await fs.lstat(resolved, { bigint: true });
 	} catch (error) {
 		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin file at ${resolved}`, {
 			cause: error instanceof Error ? error : undefined,
 		});
 	}
-	const realRoot = await fs.realpath(pluginRoot);
-	if (!pathIsWithin(realRoot, real)) {
+	if (!pathIsWithin(realRoot, realPath)) {
 		throw new GjcPluginLoadError("security_policy", `GJC plugin file escapes root via symlink: ${rel}`);
 	}
-	return resolved;
+	if (stat.isSymbolicLink() || !stat.isFile()) {
+		throw new GjcPluginLoadError("security_policy", `GJC plugin path must be a real file: ${rel}`);
+	}
+	return { path: resolved, realPath, identity: stat };
 }
 
 async function hashFile(
-	absPath: string,
+	file: FileAuthority,
 	rel: string,
 	declaredSha?: string,
-): Promise<{ sha256: string; bytes: number }> {
+): Promise<{ sha256: string; bytes: number; content: Buffer }> {
 	let buf: Buffer;
 	try {
-		buf = await fs.readFile(absPath);
+		buf = await readBoundedFile(file, rel, PLUGIN_FILE_MAX_BYTES);
 	} catch (error) {
-		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin file at ${absPath}`, {
+		if (error instanceof GjcPluginLoadError) throw error;
+		throw new GjcPluginLoadError("missing_file", `Missing GJC plugin file at ${file.path}`, {
 			cause: error instanceof Error ? error : undefined,
 		});
 	}
@@ -99,7 +227,38 @@ async function hashFile(
 	if (declaredSha !== undefined && declaredSha.toLowerCase() !== digest) {
 		throw new GjcPluginLoadError("hash_mismatch", `GJC plugin file hash mismatch for ${rel}`);
 	}
-	return { sha256: digest, bytes: buf.byteLength };
+	return { sha256: digest, bytes: buf.byteLength, content: buf };
+}
+
+function schemaFromSnapshots(
+	declaration: unknown,
+	sourceBytes: Buffer,
+	schemaFile?: { relativePath: string; bytes: Buffer },
+): JsonSchema202012 {
+	if (schemaFile !== undefined) {
+		try {
+			return canonicalizeJsonSchema(JSON.parse(schemaFile.bytes.toString("utf8")) as unknown);
+		} catch (error) {
+			if (error instanceof GjcPluginLoadError) throw error;
+			throw new GjcPluginLoadError(
+				"invalid_schema",
+				`Invalid JSON Schema declaration at ${schemaFile.relativePath}`,
+				{
+					cause: error instanceof Error ? error : undefined,
+				},
+			);
+		}
+	}
+	if (declaration !== undefined) return canonicalizeJsonSchema(declaration);
+	try {
+		return extractDeclaredToolSchema(sourceBytes.toString("utf8"));
+	} catch (error) {
+		if (error instanceof GjcPluginLoadError) throw error;
+		throw new GjcPluginLoadError(
+			"invalid_schema",
+			`Tool parameters schema is not statically readable: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
 }
 
 function mcpConfigHash(entry: GjcPluginMcpManifestEntry): string {
@@ -141,8 +300,8 @@ async function compileAppendix(
 		return { contentHash: digest, bytes: Buffer.byteLength(content), content };
 	}
 	const rel = entry.path as string;
-	const abs = await resolveDeclaredFile(pluginRoot, rel);
-	const { sha256: digest, bytes } = await hashFile(abs, rel, entry.sha256);
+	const file = await resolveDeclaredFile(pluginRoot, rel);
+	const { sha256: digest, bytes } = await hashFile(file, rel, entry.sha256);
 	if (bytes === 0) {
 		throw new GjcPluginLoadError("invalid_appendix", `Invalid GJC plugin ${field}: file is empty`);
 	}
@@ -158,40 +317,34 @@ async function compileAppendix(
 export async function compileGjcPluginBundle(root: string): Promise<NormalizedGjcPluginBundle> {
 	const pluginRoot = path.resolve(root);
 	const manifestPath = path.join(pluginRoot, GJC_PLUGIN_MANIFEST_FILENAME);
-	const manifest = parseManifest(await readManifestJson(manifestPath), manifestPath);
+	const manifestSnapshot = await readManifestSnapshot(pluginRoot, manifestPath);
+	const manifest = parseManifest(manifestSnapshot.json, manifestPath);
 
 	const files = new Map<string, { sha256: string; bytes: number }>();
 	const manifestSubskillTools = manifest.tools.filter(tool => tool.surface === "subskill");
 	const manifestSubskillFiles = new Map<string, { name: string; sha256: string }>();
 	for (const tool of manifestSubskillTools) {
-		const abs = await resolveDeclaredFile(pluginRoot, tool.path);
-		const { sha256: digest, bytes } = await hashFile(abs, tool.path, tool.sha256);
+		const file = await resolveDeclaredFile(pluginRoot, tool.path);
+		const { sha256: digest, bytes } = await hashFile(file, tool.path, tool.sha256);
 		files.set(tool.path, { sha256: digest, bytes });
 		manifestSubskillFiles.set(tool.path, { name: tool.name, sha256: digest });
 	}
 
 	const subskills: NormalizedSubskillSurface[] = [];
 	for (const rel of manifest.subskills) {
-		const abs = await resolveDeclaredFile(pluginRoot, rel);
-		const { sha256: digest, bytes } = await hashFile(abs, rel);
+		const file = await resolveDeclaredFile(pluginRoot, rel);
+		const { sha256: digest, bytes, content: contentBytes } = await hashFile(file, rel);
 		files.set(rel, { sha256: digest, bytes });
-		let content: string;
-		try {
-			content = await fs.readFile(abs, "utf8");
-		} catch (error) {
-			throw new GjcPluginLoadError("missing_file", `Missing GJC sub-skill file at ${abs}`, {
-				cause: error instanceof Error ? error : undefined,
-			});
-		}
+		const content = contentBytes.toString("utf8");
 		let parsed: { frontmatter: Record<string, unknown>; body: string };
 		try {
-			parsed = parseFrontmatter(content, { source: abs, level: "fatal" });
+			parsed = parseFrontmatter(content, { source: file.path, level: "fatal" });
 		} catch (error) {
-			throw new GjcPluginLoadError("invalid_frontmatter", `Invalid GJC sub-skill frontmatter at ${abs}`, {
+			throw new GjcPluginLoadError("invalid_frontmatter", `Invalid GJC sub-skill frontmatter at ${file.path}`, {
 				cause: error instanceof Error ? error : undefined,
 			});
 		}
-		const fm = parseSubskillFrontmatter(parsed.frontmatter, abs);
+		const fm = parseSubskillFrontmatter(parsed.frontmatter, file.path);
 		validateBinding(fm);
 		// Subskill-scoped frontmatter tools are hashed for copy-ownership and
 		// escape checks (the loader resolves these at runtime).
@@ -212,8 +365,8 @@ export async function compileGjcPluginBundle(root: string): Promise<NormalizedGj
 		}
 		for (const toolRel of fmToolPaths) {
 			if (toolRel.trim().length === 0) continue;
-			const toolAbs = await resolveDeclaredFile(pluginRoot, toolRel);
-			const { sha256: toolDigest, bytes: toolBytes } = await hashFile(toolAbs, toolRel);
+			const toolFile = await resolveDeclaredFile(pluginRoot, toolRel);
+			const { sha256: toolDigest, bytes: toolBytes } = await hashFile(toolFile, toolRel);
 			files.set(toolRel, { sha256: toolDigest, bytes: toolBytes });
 			const extensionId = surfaceIds.subskillTool(fm.binds_to, fm.phase, fm.activation_arg, toolRel);
 			if (seenToolRefs.has(extensionId)) continue;
@@ -238,18 +391,18 @@ export async function compileGjcPluginBundle(root: string): Promise<NormalizedGj
 	// surface; legacy string shorthand stays subskill-scoped (loader-handled).
 	const tools: NormalizedToolSurface[] = [];
 	for (const tool of manifest.tools) {
-		const abs = await resolveDeclaredFile(pluginRoot, tool.path);
-		const { sha256: digest, bytes } = await hashFile(abs, tool.path, tool.sha256);
+		const file = await resolveDeclaredFile(pluginRoot, tool.path);
+		const { sha256: digest, bytes, content: sourceBytes } = await hashFile(file, tool.path, tool.sha256);
 		files.set(tool.path, { sha256: digest, bytes });
 		if (tool.surface !== "always-on") continue;
-		let schemaPath: string | undefined;
+		let schemaFileSnapshot: { relativePath: string; bytes: Buffer } | undefined;
 		if (tool.schemaPath !== undefined) {
-			const schemaAbs = await resolveDeclaredFile(pluginRoot, tool.schemaPath);
-			const schemaFile = await hashFile(schemaAbs, tool.schemaPath);
-			files.set(tool.schemaPath, schemaFile);
-			schemaPath = tool.schemaPath;
+			const schemaFile = await resolveDeclaredFile(pluginRoot, tool.schemaPath);
+			const { sha256: schemaDigest, bytes: schemaBytes, content } = await hashFile(schemaFile, tool.schemaPath);
+			files.set(tool.schemaPath, { sha256: schemaDigest, bytes: schemaBytes });
+			schemaFileSnapshot = { relativePath: tool.schemaPath, bytes: content };
 		}
-		const schema = await readSchemaDeclaration(pluginRoot, abs, tool.schema, schemaPath);
+		const schema = schemaFromSnapshots(tool.schema, sourceBytes, schemaFileSnapshot);
 		tools.push({
 			extensionId: surfaceIds.tool(tool.name),
 			name: tool.name,
@@ -267,8 +420,8 @@ export async function compileGjcPluginBundle(root: string): Promise<NormalizedGj
 	for (const hook of manifest.hooks) {
 		// Path safety first: resolve/hash before semantic checks so traversal and
 		// missing-file failures take precedence over contract validation.
-		const abs = await resolveDeclaredFile(pluginRoot, hook.path);
-		const { sha256: digest, bytes } = await hashFile(abs, hook.path, hook.sha256);
+		const file = await resolveDeclaredFile(pluginRoot, hook.path);
+		const { sha256: digest, bytes } = await hashFile(file, hook.path, hook.sha256);
 		files.set(hook.path, { sha256: digest, bytes });
 		// Minimal compile-time hook contract: tool_call hooks must name a target
 		// and a before/after phase so the constrained runner (M3/M4) can bind them.
@@ -295,7 +448,16 @@ export async function compileGjcPluginBundle(root: string): Promise<NormalizedGj
 				`GJC plugin hook "${hook.name}": tool_result requires the after phase`,
 			);
 		}
-		hooks.push({
+		const grant = normalizeFunctionHookGrant({
+			capabilities: hook.capabilities,
+			networkDestinations: hook.networkDestinations,
+			filesystemRoots: hook.filesystemRoots,
+		});
+		const functionHook =
+			hook.capabilities !== undefined ||
+			hook.networkDestinations !== undefined ||
+			hook.filesystemRoots !== undefined;
+		const normalizedHook: NormalizedHookSurface = {
 			extensionId: surfaceIds.hook(hook.event, hook.phase, hook.target, hook.name),
 			name: hook.name,
 			event: hook.event,
@@ -304,7 +466,15 @@ export async function compileGjcPluginBundle(root: string): Promise<NormalizedGj
 			relativePath: hook.path,
 			sha256: digest,
 			implementationHash: digest,
-		});
+		};
+		if (functionHook) {
+			normalizedHook.capabilities = [...grant.capabilities];
+			normalizedHook.networkDestinations = [...grant.networkDestinations];
+			normalizedHook.filesystemRoots = [...grant.filesystemRoots];
+			normalizedHook.capabilityHash = functionHookGrantHash(grant);
+			normalizedHook.functionHook = true;
+		}
+		hooks.push(normalizedHook);
 	}
 
 	const mcps: NormalizedMcpSurface[] = [];
@@ -320,17 +490,15 @@ export async function compileGjcPluginBundle(root: string): Promise<NormalizedGj
 				`GJC plugin MCP "${entry.name}": ${entry.transport} requires a url`,
 			);
 		}
-		// Hash bundled stdio script args (relative file paths) so the registry owns
-		// their copied-file boundary. Path/security failures must propagate, not be
-		// swallowed, so traversal/symlink-escape/missing bundled files fail compile.
-		for (const arg of entry.args ?? []) {
-			// Skip flags (e.g. "--port", "-v"); only treat clearly path-like args as
-			// bundled files subject to root confinement.
-			if (arg.startsWith("-")) continue;
-			if (!arg.startsWith(".") && !arg.includes("/")) continue;
-			const abs = await resolveDeclaredFile(pluginRoot, arg);
-			const { sha256: digest, bytes } = await hashFile(abs, arg, undefined);
-			files.set(arg, { sha256: digest, bytes });
+		// Derive ownership from the same cwd-aware bare Node/Bun grammar used at runtime.
+		if (entry.transport === "stdio") {
+			const invocation = classifyStdioInvocation(entry, { pluginRoot });
+			await resolveDeclaredDirectory(pluginRoot, path.relative(pluginRoot, invocation.cwd));
+			for (const relativePath of new Set(invocation.ownedRelativePaths)) {
+				const file = await resolveDeclaredFile(pluginRoot, relativePath);
+				const { sha256: digest, bytes } = await hashFile(file, relativePath, undefined);
+				files.set(relativePath, { sha256: digest, bytes });
+			}
 		}
 		mcps.push({
 			extensionId: surfaceIds.mcp(entry.name),
@@ -377,7 +545,7 @@ export async function compileGjcPluginBundle(root: string): Promise<NormalizedGj
 		agentAppendices,
 	};
 
-	const manifestBytes = await fs.readFile(manifestPath);
+	const manifestBytes = manifestSnapshot.bytes;
 	const manifestHash = sha256(manifestBytes);
 
 	const copiedFiles = [...files.entries()]