@gajae-code/coding-agent 0.7.3 → 0.7.5

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

@@ -0,0 +1,84 @@
+import { loadEffectiveGjcPluginRegistry } from "./registry";
+import { type SessionQuarantine, validateSessionBundles, verifyEntryHashes } from "./session-validation";
+import type { GjcPluginRegistryEntry, GjcPluginScope } from "./types";
+
+/**
+ * Observability for GJC plugin bundle surfaces, consumable by the extension
+ * dashboard / state manager. Each surface row carries its stable extension id,
+ * owning plugin, scope, source kind, enabled/disabled/quarantined status, and a
+ * content hash. MCP auth/header values are NEVER included.
+ */
+
+export type PluginSurfaceStatus = "enabled" | "disabled" | "quarantined";
+
+export interface PluginSurfaceRow {
+	extensionId: string;
+	kind: "tool" | "hook" | "mcp" | "system-appendix" | "agent-appendix" | "subskill";
+	plugin: string;
+	scope: GjcPluginScope;
+	sourceKind: GjcPluginRegistryEntry["source"]["kind"];
+	status: PluginSurfaceStatus;
+	hash: string;
+	quarantineCode?: string;
+}
+
+export interface PluginObservabilitySummary {
+	plugins: number;
+	surfaces: PluginSurfaceRow[];
+}
+
+function statusFor(
+	entry: GjcPluginRegistryEntry,
+	extensionId: string,
+	quarantinedIds: Map<string, string>,
+): { status: PluginSurfaceStatus; quarantineCode?: string } {
+	const q =
+		quarantinedIds.get(`${entry.name}\u0000${extensionId}`) ??
+		quarantinedIds.get(`${entry.name}\u0000plugin:${entry.name}`);
+	if (q) return { status: "quarantined", quarantineCode: q };
+	if (!entry.enabled || entry.disabledSurfaceIds.includes(extensionId)) return { status: "disabled" };
+	return { status: "enabled" };
+}
+
+function rowsForEntry(entry: GjcPluginRegistryEntry, quarantinedIds: Map<string, string>): PluginSurfaceRow[] {
+	const base = (extensionId: string, hash: string): Omit<PluginSurfaceRow, "kind"> => ({
+		extensionId,
+		plugin: entry.name,
+		scope: entry.scope,
+		sourceKind: entry.source.kind,
+		hash,
+		...statusFor(entry, extensionId, quarantinedIds),
+	});
+	const rows: PluginSurfaceRow[] = [];
+	for (const t of entry.surfaces.tools) rows.push({ kind: "tool", ...base(t.extensionId, t.sha256) });
+	for (const h of entry.surfaces.hooks) rows.push({ kind: "hook", ...base(h.extensionId, h.sha256) });
+	// MCP: only name/config hash, never command/url/headers/auth.
+	for (const m of entry.surfaces.mcps) rows.push({ kind: "mcp", ...base(m.extensionId, m.configHash) });
+	for (const a of entry.surfaces.systemAppendices)
+		rows.push({ kind: "system-appendix", ...base(a.extensionId, a.contentHash) });
+	for (const a of entry.surfaces.agentAppendices)
+		rows.push({ kind: "agent-appendix", ...base(a.extensionId, a.contentHash) });
+	for (const s of entry.surfaces.subskills) rows.push({ kind: "subskill", ...base(s.extensionId, s.sha256) });
+	return rows;
+}
+
+/**
+ * Build the observability summary for the effective registry at `cwd`, including
+ * hash-drift and session-collision quarantine status.
+ */
+export async function summarizeGjcPluginObservability(cwd: string): Promise<PluginObservabilitySummary> {
+	const effective = await loadEffectiveGjcPluginRegistry(cwd);
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashes(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+	const { quarantine } = validateSessionBundles(effective, {}, preQuarantine);
+	const quarantinedIds = new Map<string, string>();
+	for (const q of quarantine) quarantinedIds.set(`${q.plugin}\u0000${q.surfaceId}`, q.code);
+
+	const surfaces: PluginSurfaceRow[] = [];
+	for (const entry of effective) surfaces.push(...rowsForEntry(entry, quarantinedIds));
+	return { plugins: effective.length, surfaces };
+}

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

@@ -45,7 +45,7 @@ async function discoverGjcPluginRootsIn(baseDir: string): Promise<string[]> {
 			}),
 	);
 
-	return roots.filter((root): root is string => root !== null);
+	return roots.filter((root): root is string => root !== null).sort((a, b) => a.localeCompare(b));
 }
 
 export async function discoverGjcPluginRoots({ cwd }: { cwd: string; home?: string }): Promise<string[]> {

package/src/extensibility/gjc-plugins/prompt-appendix.ts

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { GjcPluginRegistryEntry, GjcSubskillParentAgent, NormalizedAppendixSurface } from "./types";
+
+/**
+ * Renders plugin system/agent appendices as lower-authority, delimited blocks
+ * appended AFTER the base prompt. The base/developer instructions always retain
+ * higher authority; plugin appendices can never override them.
+ */
+
+const MAX_APPENDIX_BYTES = 8 * 1024;
+const MAX_TOTAL_APPENDIX_BYTES = 32 * 1024;
+const MAX_APPENDIX_COUNT = 32;
+const MAX_NAME_LEN = 128;
+
+function escapeAttr(value: string): string {
+	const clamped = value.length > MAX_NAME_LEN ? `${value.slice(0, MAX_NAME_LEN - 1)}\u2026` : value;
+	return clamped.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function sanitizeBody(text: string): string {
+	// Strip control chars (except tab/newline), then XML-escape &, <, > so a
+	// malicious body can NEVER emit a closing delimiter or fake <system>/
+	// <developer>/<gjc-subskill> tag that escapes the lower-authority block.
+	const stripped = text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, "");
+	return stripped.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+async function readAppendixBody(entry: GjcPluginRegistryEntry, surface: NormalizedAppendixSurface): Promise<string> {
+	if (surface.content !== undefined) return surface.content; // inline-content appendix
+	if (!surface.relativePath) return "";
+	const abs = path.join(entry.pluginRoot, surface.relativePath);
+	try {
+		return await fs.readFile(abs, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+export interface RenderedPluginAppendices {
+	/** Combined system-appendix block text (empty if none). */
+	system: string;
+	/** Per-agent appendix block text. */
+	byAgent: Map<GjcSubskillParentAgent, string>;
+	/** Stable digest of all rendered appendix content + identities (for cache/refresh). */
+	digest: string;
+}
+
+/**
+ * Build appendix blocks from the active, enabled registry entries in their
+ * deterministic order. Per-appendix and total size caps are enforced
+ * fail-closed (oversize content is dropped with a marker, never silently
+ * truncated into the prompt as authoritative text).
+ */
+export async function renderPluginAppendices(
+	entries: readonly GjcPluginRegistryEntry[],
+): Promise<RenderedPluginAppendices> {
+	const systemBlocks: string[] = [];
+	const byAgent = new Map<GjcSubskillParentAgent, string[]>();
+	const digestParts: string[] = [];
+	let totalBytes = 0;
+	let count = 0;
+
+	// Admission is measured on the FULL rendered block (wrapper + escaped
+	// metadata + body), not just the body, and capped by per-block size, total
+	// size, and appendix count.
+	const admit = (block: string): boolean => {
+		const bytes = Buffer.byteLength(block);
+		if (bytes > MAX_APPENDIX_BYTES) return false;
+		if (count >= MAX_APPENDIX_COUNT) return false;
+		if (totalBytes + bytes > MAX_TOTAL_APPENDIX_BYTES) return false;
+		totalBytes += bytes;
+		count += 1;
+		return true;
+	};
+
+	for (const entry of entries) {
+		if (!entry.enabled) continue;
+		const disabled = new Set(entry.disabledSurfaceIds);
+		for (const sa of entry.surfaces.systemAppendices) {
+			if (disabled.has(sa.extensionId)) continue;
+			const body = sanitizeBody(await readAppendixBody(entry, sa));
+			digestParts.push(`${sa.extensionId}:${sa.contentHash}`);
+			if (!body) continue;
+			const block = `<gjc-plugin-system-appendix plugin="${escapeAttr(entry.name)}" name="${escapeAttr(sa.name)}" sha256="${sa.contentHash}" authority="appendix-lower-than-system">\n${body}\n</gjc-plugin-system-appendix>`;
+			if (!admit(block)) continue;
+			systemBlocks.push(block);
+		}
+		for (const aa of entry.surfaces.agentAppendices) {
+			if (disabled.has(aa.extensionId)) continue;
+			const body = sanitizeBody(await readAppendixBody(entry, aa));
+			digestParts.push(`${aa.extensionId}:${aa.contentHash}`);
+			if (!body) continue;
+			const block = `<gjc-plugin-agent-appendix plugin="${escapeAttr(entry.name)}" agent="${escapeAttr(aa.agent)}" name="${escapeAttr(aa.name)}" sha256="${aa.contentHash}" authority="appendix-lower-than-agent">\n${body}\n</gjc-plugin-agent-appendix>`;
+			if (!admit(block)) continue;
+			const list = byAgent.get(aa.agent) ?? [];
+			list.push(block);
+			byAgent.set(aa.agent, list);
+		}
+	}
+
+	const digest = createHash("sha256").update(digestParts.join("\u0000")).digest("hex");
+	return {
+		system: systemBlocks.join("\n\n"),
+		byAgent: new Map([...byAgent].map(([agent, blocks]) => [agent, blocks.join("\n\n")])),
+		digest,
+	};
+}

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

@@ -0,0 +1,180 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { gjcPluginProjectRoot, gjcPluginUserRoot } from "./paths";
+import { GjcPluginLoadError, type GjcPluginRegistry, type GjcPluginRegistryEntry, type GjcPluginScope } from "./types";
+
+const REGISTRY_FILENAME = "registry.json";
+const LOCK_FILENAME = "registry.lock";
+const LOCK_TIMEOUT_MS = 5000;
+const LOCK_RETRY_MS = 50;
+
+export function registryRootForScope(scope: GjcPluginScope, cwd: string): string {
+	return scope === "user" ? gjcPluginUserRoot() : gjcPluginProjectRoot(cwd);
+}
+
+export function registryPathForScope(scope: GjcPluginScope, cwd: string): string {
+	return path.join(registryRootForScope(scope, cwd), REGISTRY_FILENAME);
+}
+
+function emptyRegistry(scope: GjcPluginScope): GjcPluginRegistry {
+	return { version: 1, scope, plugins: [] };
+}
+
+function isEnoent(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException)?.code === "ENOENT";
+}
+
+/**
+ * Deterministic ordering: scope (user before project) -> normalized name ->
+ * resolved plugin root. Collisions are errors elsewhere; order only controls
+ * stable hook/appendix sequencing.
+ */
+export function sortRegistryEntries(entries: GjcPluginRegistryEntry[]): GjcPluginRegistryEntry[] {
+	const scopeRank = (scope: GjcPluginScope): number => (scope === "user" ? 0 : 1);
+	return [...entries].sort((a, b) => {
+		if (a.scope !== b.scope) return scopeRank(a.scope) - scopeRank(b.scope);
+		if (a.name !== b.name) return a.name.localeCompare(b.name);
+		return a.pluginRoot.localeCompare(b.pluginRoot);
+	});
+}
+
+export async function readRegistry(scope: GjcPluginScope, cwd: string): Promise<GjcPluginRegistry> {
+	const registryPath = registryPathForScope(scope, cwd);
+	let text: string;
+	try {
+		text = await fs.readFile(registryPath, "utf8");
+	} catch (error) {
+		if (isEnoent(error)) return emptyRegistry(scope);
+		throw error;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new GjcPluginLoadError("invalid_manifest", `Corrupt GJC plugin registry at ${registryPath}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	if (typeof parsed !== "object" || parsed === null || (parsed as GjcPluginRegistry).version !== 1) {
+		throw new GjcPluginLoadError("invalid_manifest", `Unsupported GJC plugin registry shape at ${registryPath}`);
+	}
+	const registry = parsed as GjcPluginRegistry;
+	registry.plugins = sortRegistryEntries(registry.plugins ?? []);
+	return registry;
+}
+
+async function acquireLock(lockPath: string): Promise<() => Promise<void>> {
+	await fs.mkdir(path.dirname(lockPath), { recursive: true });
+	const token = `${process.pid}-${randomBytes(8).toString("hex")}`;
+	const deadline = Date.now() + LOCK_TIMEOUT_MS;
+	for (;;) {
+		try {
+			const handle = await fs.open(lockPath, "wx");
+			try {
+				await handle.writeFile(token);
+			} finally {
+				await handle.close();
+			}
+			let released = false;
+			return async () => {
+				if (released) return;
+				released = true;
+				// Owner-safe release: only remove the lock if it is still ours.
+				try {
+					const current = await fs.readFile(lockPath, "utf8");
+					if (current === token) await fs.rm(lockPath, { force: true });
+				} catch {
+					// Lock already gone; nothing to release.
+				}
+			};
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException)?.code !== "EEXIST") throw error;
+			// Fail-closed: never auto-evict an existing lock (a live holder may run
+			// longer than the timeout). Time out instead and leave the lock for
+			// diagnostics/manual cleanup. A lease/heartbeat protocol can be added
+			// later if automatic stale recovery becomes necessary.
+			if (Date.now() > deadline) {
+				throw new GjcPluginLoadError(
+					"install_conflict",
+					`Timed out acquiring GJC plugin registry lock at ${lockPath}; remove it manually if no install is running`,
+				);
+			}
+			await new Promise(resolve => setTimeout(resolve, LOCK_RETRY_MS));
+		}
+	}
+}
+
+export async function withRegistryLock<T>(scope: GjcPluginScope, cwd: string, fn: () => Promise<T>): Promise<T> {
+	const lockPath = path.join(registryRootForScope(scope, cwd), LOCK_FILENAME);
+	const release = await acquireLock(lockPath);
+	try {
+		return await fn();
+	} finally {
+		await release();
+	}
+}
+
+/**
+ * Lock-free atomic write (temp+fsync+rename). Only call while already holding
+ * the per-scope registry lock via withRegistryLock.
+ */
+export async function writeRegistryUnlocked(registry: GjcPluginRegistry, cwd: string): Promise<void> {
+	const registryPath = registryPathForScope(registry.scope, cwd);
+	await fs.mkdir(path.dirname(registryPath), { recursive: true });
+	const sorted: GjcPluginRegistry = { ...registry, plugins: sortRegistryEntries(registry.plugins) };
+	const text = `${JSON.stringify(sorted, null, 2)}\n`;
+	const tmpPath = `${registryPath}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+	const handle = await fs.open(tmpPath, "w");
+	try {
+		await handle.writeFile(text);
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	await fs.rename(tmpPath, registryPath);
+}
+
+/**
+ * Atomic registry write: write to a temp sibling, fsync, then rename. Guarded
+ * by an interprocess lockfile so concurrent installs cannot clobber each other.
+ */
+export async function writeRegistry(registry: GjcPluginRegistry, cwd: string): Promise<void> {
+	await withRegistryLock(registry.scope, cwd, () => writeRegistryUnlocked(registry, cwd));
+}
+
+/**
+ * Mutate a scope's registry as a single locked read-modify-write transaction so
+ * concurrent installs cannot lose each other's updates. The mutator receives a
+ * sorted copy and returns the next entry list.
+ */
+export async function updateRegistry(
+	scope: GjcPluginScope,
+	cwd: string,
+	mutator: (entries: GjcPluginRegistryEntry[]) => GjcPluginRegistryEntry[],
+): Promise<GjcPluginRegistry> {
+	return await withRegistryLock(scope, cwd, async () => {
+		const current = await readRegistry(scope, cwd);
+		const nextEntries = mutator([...current.plugins]);
+		const next: GjcPluginRegistry = { version: 1, scope, plugins: sortRegistryEntries(nextEntries) };
+		await writeRegistryUnlocked(next, cwd);
+		return next;
+	});
+}
+
+/**
+ * Effective registry for a cwd: user + project entries in deterministic order.
+ */
+export async function loadEffectiveGjcPluginRegistry(cwd: string): Promise<GjcPluginRegistryEntry[]> {
+	const [user, project] = await Promise.all([readRegistry("user", cwd), readRegistry("project", cwd)]);
+	return sortRegistryEntries([...user.plugins, ...project.plugins]);
+}
+
+export function registryEntryFingerprint(entry: GjcPluginRegistryEntry): string {
+	const canonical = JSON.stringify({
+		name: entry.name,
+		manifestHash: entry.manifestHash,
+		files: entry.copiedFiles.map(f => [f.relativePath, f.sha256]).sort(),
+	});
+	return createHash("sha256").update(canonical).digest("hex");
+}

package/src/extensibility/gjc-plugins/runtime-adapters.ts

@@ -0,0 +1,234 @@
+import * as path from "node:path";
+import { loadCustomTools } from "../custom-tools/loader";
+import type { CustomTool } from "../custom-tools/types";
+import { loadEffectiveGjcPluginRegistry } from "./registry";
+import { type SessionQuarantine, validateSessionBundles, verifyEntryHashes } from "./session-validation";
+
+export interface AlwaysOnPluginTools {
+	tools: CustomTool[];
+	quarantine: SessionQuarantine[];
+}
+
+/**
+ * Load the always-on plugin tool surfaces for the effective registry at `cwd`.
+ *
+ * Safety properties:
+ * - Hash drift quarantines the plugin (runtime_mismatch) before any import.
+ * - Session-start collisions vs reserved/built-in names quarantine fail-closed.
+ * - Manifest-declared tool names are authoritative: a factory that returns a
+ *   different/extra/missing name is rejected with runtime_mismatch and skipped.
+ * - Reserved tool names are never overwritten.
+ *
+ * Returns an empty result when no plugins are installed, so callers that always
+ * call this in `createAgentSession` incur no behavior change without plugins.
+ */
+export async function loadAlwaysOnPluginTools(input: {
+	cwd: string;
+	reservedToolNames: string[];
+}): Promise<AlwaysOnPluginTools> {
+	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	if (effective.length === 0) return { tools: [], quarantine: [] };
+
+	// Hash-drift quarantine before importing any plugin code.
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashes(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+
+	const reserved = new Set(input.reservedToolNames);
+	const { active, quarantine } = validateSessionBundles(
+		effective,
+		{ toolNames: input.reservedToolNames },
+		preQuarantine,
+	);
+
+	// Map declared (path -> name) for every active always-on tool surface.
+	const declared = new Map<string, { name: string; plugin: string }>();
+	for (const entry of active) {
+		const disabled = new Set(entry.disabledSurfaceIds);
+		for (const t of entry.surfaces.tools) {
+			if (disabled.has(t.extensionId)) continue;
+			declared.set(path.join(entry.pluginRoot, t.relativePath), { name: t.name, plugin: entry.name });
+		}
+	}
+	if (declared.size === 0) return { tools: [], quarantine };
+
+	const loaded = await loadCustomTools(
+		[...declared.keys()].map(p => ({ path: p })),
+		input.cwd,
+		input.reservedToolNames,
+	);
+
+	// Group loaded tools by their source path for exact-name verification.
+	const byPath = new Map<string, string[]>();
+	for (const lt of loaded.tools) {
+		const key = path.resolve(lt.path);
+		const list = byPath.get(key) ?? [];
+		list.push(lt.tool.name);
+		byPath.set(key, list);
+	}
+
+	const tools: CustomTool[] = [];
+	const seenNames = new Set<string>(reserved);
+	for (const [declaredPath, info] of declared) {
+		const returned = byPath.get(path.resolve(declaredPath)) ?? [];
+		// Manifest is authoritative: exactly the one declared name must come back.
+		if (returned.length !== 1 || returned[0] !== info.name) {
+			quarantine.push({
+				plugin: info.plugin,
+				surfaceId: `tool:${info.name}`,
+				code: "runtime_mismatch",
+				message: `Tool factory returned ${JSON.stringify(returned)}, expected exactly ["${info.name}"]`,
+			});
+			continue;
+		}
+		if (seenNames.has(info.name)) {
+			// Defense in depth: never overwrite a reserved/earlier name.
+			quarantine.push({
+				plugin: info.plugin,
+				surfaceId: `tool:${info.name}`,
+				code: "session_collision",
+				message: `Tool name "${info.name}" already present; refusing to overwrite`,
+			});
+			continue;
+		}
+		const match = loaded.tools.find(lt => path.resolve(lt.path) === path.resolve(declaredPath));
+		if (match) {
+			tools.push(match.tool);
+			seenNames.add(info.name);
+		}
+	}
+	return { tools, quarantine };
+}
+
+/**
+ * Render the always-on system-appendix blocks for the effective registry at
+ * `cwd`, applying hash-drift + collision quarantine first. Returns "" when no
+ * plugins are installed/enabled. Safe to call unconditionally at session start.
+ */
+export async function renderAlwaysOnSystemAppendices(input: { cwd: string }): Promise<string> {
+	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	if (effective.length === 0) return "";
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashes(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+	const { active } = validateSessionBundles(effective, {}, preQuarantine);
+	const { renderPluginAppendices } = await import("./prompt-appendix");
+	return (await renderPluginAppendices(active)).system;
+}
+
+/**
+ * Render the agent-appendix block and Tier-1 sub-skill advertisement for a role
+ * agent at session/spawn time. Hash-drift + collision quarantine applied first.
+ * Returns empty strings when nothing applies.
+ */
+export async function renderAgentPromptAdditions(input: {
+	cwd: string;
+	agentName: string;
+}): Promise<{ appendix: string; advertisement: string }> {
+	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	if (effective.length === 0) return { appendix: "", advertisement: "" };
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashes(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+	const { active } = validateSessionBundles(effective, {}, preQuarantine);
+	const { renderPluginAppendices } = await import("./prompt-appendix");
+	const { buildAgentSubskillAdvertisement } = await import("./injection");
+	const rendered = await renderPluginAppendices(active);
+	return {
+		appendix: rendered.byAgent.get(input.agentName as never) ?? "",
+		advertisement: buildAgentSubskillAdvertisement(active, input.agentName),
+	};
+}
+
+/**
+ * Render the Tier-1 sub-skill advertisement for a workflow parent skill.
+ * Returns "" when nothing applies. Quarantine applied first.
+ */
+export async function renderSkillAdvertisement(input: {
+	cwd: string;
+	skillName: string;
+	phase?: string;
+}): Promise<string> {
+	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	if (effective.length === 0) return "";
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashes(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+	const { active } = validateSessionBundles(effective, {}, preQuarantine);
+	const { buildSubskillAdvertisement } = await import("./injection");
+	return buildSubskillAdvertisement(active, input.skillName, input.phase);
+}
+
+/**
+ * Convert active plugin-bundle MCP surfaces into runtime MCPServerConfig entries,
+ * applying install + runtime MCP policy (URL scheme/private-range deny, DNS
+ * re-resolution for http/sse, stdio root-confinement) before connection. Servers
+ * failing policy are quarantined and excluded. Returns {} when none.
+ */
+export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
+	configs: Record<string, any>;
+	quarantine: SessionQuarantine[];
+}> {
+	const effective = await loadEffectiveGjcPluginRegistry(input.cwd);
+	if (effective.length === 0) return { configs: {}, quarantine: [] };
+	const preQuarantine: SessionQuarantine[] = [];
+	for (const entry of effective) {
+		if (!entry.enabled) continue;
+		const drift = await verifyEntryHashes(entry);
+		if (drift) preQuarantine.push(drift);
+	}
+	const { active, quarantine } = validateSessionBundles(effective, {}, preQuarantine);
+	const { assertMcpInstallPolicy, assertDnsResolvesPublic, assertUrlAllowed } = await import("./mcp-policy");
+	const nodePath = await import("node:path");
+
+	const configs: Record<string, any> = {};
+	for (const entry of active) {
+		const disabled = new Set(entry.disabledSurfaceIds);
+		for (const m of entry.surfaces.mcps) {
+			if (disabled.has(m.extensionId)) continue;
+			const cfg = m.config;
+			try {
+				assertMcpInstallPolicy(cfg, { pluginRoot: entry.pluginRoot });
+				if (cfg.transport === "stdio") {
+					configs[m.name] = {
+						type: "stdio",
+						command: cfg.command,
+						args: cfg.args,
+						cwd: cfg.cwd ? nodePath.resolve(entry.pluginRoot, cfg.cwd) : entry.pluginRoot,
+						// Third-party plugin MCP processes must not inherit host secrets;
+						// only a minimal OS allowlist (PATH/HOME/temp/locale) is provided.
+						noInheritEnv: true,
+					};
+				} else {
+					const url = assertUrlAllowed(cfg.url ?? "", `MCP "${m.name}" url`);
+					await assertDnsResolvesPublic(url.hostname, `MCP "${m.name}" host`);
+					// Headers are intentionally NOT forwarded: the generic MCP config
+					// resolution path expands ${env:...}/shell templates, which would let
+					// a third-party bundle exfiltrate host secrets. Plugin-bundle MCP
+					// servers connect without bundle-declared headers.
+					configs[m.name] = { type: cfg.transport, url: cfg.url };
+				}
+			} catch (error) {
+				quarantine.push({
+					plugin: entry.name,
+					surfaceId: m.extensionId,
+					code: "security_policy",
+					message: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+	}
+	return { configs, quarantine };
+}