@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/discovery/mcp-json.ts

@@ -30,6 +30,7 @@ interface MCPConfigFile {
 			enabled?: boolean;
 			autoload?: boolean;
 			sharing?: "per-session" | "shared";
+			protocol?: "auto" | "2026-07-28" | "legacy";
 			timeout?: number;
 			command?: string;
 			args?: string[];
@@ -104,6 +105,10 @@ function isValidExactServerConfig(value: unknown): boolean {
 	return (
 		isOptionalBoolean(value.enabled) &&
 		(value.sharing === undefined || value.sharing === "per-session" || value.sharing === "shared") &&
+		(value.protocol === undefined ||
+			value.protocol === "auto" ||
+			value.protocol === "2026-07-28" ||
+			value.protocol === "legacy") &&
 		isOptionalBoolean(value.autoload) &&
 		isOptionalBoolean(value.noInheritEnv) &&
 		(value.timeout === undefined ||
@@ -203,6 +208,7 @@ function transformMCPConfig(config: MCPConfigFile, source: SourceMeta, quiet = f
 				enabled,
 				autoload,
 				sharing: serverConfig.sharing,
+				protocol: serverConfig.protocol,
 				timeout,
 				command: serverConfig.command,
 				args: serverConfig.args,

package/src/edit/renderer.ts

@@ -2,6 +2,7 @@
  * Edit tool renderer and LSP batching helpers.
  */
 
+import { createHash } from "node:crypto";
 import type { Component } from "@gajae-code/tui";
 import { Text, visibleWidth, wrapTextWithAnsi } from "@gajae-code/tui";
 import { sanitizeText } from "@gajae-code/utils";
@@ -85,6 +86,45 @@ export interface EditToolDetails {
 	newText?: string;
 }
 
+/**
+ * Bounded durable identity of one edit snapshot (#4566).
+ *
+ * Live edit results carry full `oldText`/`newText` file bodies so in-process
+ * consumers (ACP `diff` ToolCallContent, editors) keep working. Every persisted
+ * transcript entry replaces those bodies with this fixed-size receipt: byte
+ * length plus SHA-256 content digest, enough to detect source drift and to
+ * account for the edit durably without re-writing the whole file per edit.
+ */
+export interface EditSnapshotReceipt {
+	/** UTF-8 byte length of the snapshot (`0` for create/delete-absent sides). */
+	bytes: number;
+	/** SHA-256 hex digest of the exact snapshot text (empty string for length 0). */
+	sha256: string;
+}
+
+/** Per-edit-mode cap on any single persisted edit-result string field (#4566). */
+export const EDIT_PERSIST_FIELD_MAX_CHARS = 16 * 1024;
+
+/** Fixed marker used when a snapshot receipt replaces a full body. */
+export const EDIT_SNAPSHOT_EXTERNALIZED_NOTICE =
+	"[edit snapshot externalized: see oldTextDigest/newTextDigest; full body omitted from transcript]";
+
+function sha256Hex(text: string): string {
+	if (text.length === 0) return "";
+	return createHash("sha256").update(Buffer.from(text, "utf-8")).digest("hex");
+}
+
+/** Build the bounded durable receipt for one snapshot body. */
+export function editSnapshotReceipt(text: string | undefined): EditSnapshotReceipt | undefined {
+	if (text === undefined) return undefined;
+	return { bytes: Buffer.byteLength(text, "utf-8"), sha256: sha256Hex(text) };
+}
+
+/** True when a snapshot body is small enough to persist inline without amplification. */
+export function editSnapshotPersistableInline(text: string | undefined): boolean {
+	return text !== undefined && text.length <= EDIT_PERSIST_FIELD_MAX_CHARS;
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // TUI Renderer
 // ═══════════════════════════════════════════════════════════════════════════

package/src/edit/streaming.ts

@@ -82,7 +82,9 @@ export interface EditRequestTargetInventory {
 	/** First envelope entry rename target, for free-form modes that carry no structured `edits`. */
 	rename?: string;
 }
-const MISSING_APPLY_PATCH_END_ERROR = `The last line of the patch must be '${END_PATCH_MARKER}'`;
+function missingApplyPatchEndError(): string {
+	return `The last line of the patch must be '${END_PATCH_MARKER}'`;
+}
 
 export function orderedDistinctPaths(paths: readonly (string | undefined)[]): string[] {
 	const seen = new Set<string>();
@@ -181,7 +183,7 @@ export function getEditRequestTargetInventory(
 		} catch (err) {
 			const parseError = err instanceof Error ? err.message : String(err);
 			const inventory = applyPatchEntryInventory(expandApplyPatchToPreviewEntries({ input }));
-			if (options.isPartial && parseError === MISSING_APPLY_PATCH_END_ERROR) return inventory;
+			if (options.isPartial && parseError === missingApplyPatchEndError()) return inventory;
 			return { ...inventory, parseError };
 		}
 	}

package/src/exec/bash-executor.ts

@@ -184,7 +184,6 @@ export interface BashResult {
 }
 
 const shellSessions = new Map<string, Shell>();
-const brokenShellSessions = new Set<string>();
 const retiringShellSessions = new Set<Shell>();
 // Cover pi-shell's normal cancellation kill waves without turning a stalled
 // native cleanup into a multi-second JavaScript tool stall.
@@ -204,16 +203,18 @@ export function getShellSessionCount(): number {
  */
 export async function disposeAllShellSessions(): Promise<void> {
 	// Snapshot and drop strong references up front so concurrent callers cannot
-	// reuse a session that is being torn down, then await every native abort so
+	// reuse a session that is being torn down, then await every native close so
 	// shutdown/signal cleanup does not return before resources are released.
 	// Include retiring shells whose JS call returned after bounded abort cleanup
 	// while the native run is still unwinding; they are no longer reusable but
 	// remain owned until their run promise settles.
+	// `close` rather than `abort`: aborting only cancels in-flight commands and
+	// leaves a completed session retained for reuse, which keeps the native shell
+	// alive for the rest of the process lifetime.
 	const sessions = new Set([...shellSessions.values(), ...retiringShellSessions]);
 	shellSessions.clear();
 	retiringShellSessions.clear();
-	brokenShellSessions.clear();
-	await Promise.allSettled([...sessions].map(session => session.abort()));
+	await Promise.allSettled([...sessions].map(session => session.close()));
 }
 
 postmortem.register("bash-executor:shell-sessions", () => disposeAllShellSessions());
@@ -292,10 +293,9 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 
 	const usePersistentShell = options?.oneShot !== true;
 	const sessionKey = buildSessionKey(shell, configuredPrefix, snapshotPath, shellEnv, options?.sessionKey, minimizer);
-	const persistentSessionBroken = usePersistentShell && brokenShellSessions.has(sessionKey);
 
-	let shellSession = persistentSessionBroken || !usePersistentShell ? undefined : shellSessions.get(sessionKey);
-	if (!shellSession && !persistentSessionBroken && usePersistentShell) {
+	let shellSession = usePersistentShell ? shellSessions.get(sessionKey) : undefined;
+	if (!shellSession && usePersistentShell) {
 		shellSession = new Shell({
 			sessionEnv: shellEnv,
 			snapshotPath: snapshotPath ?? undefined,
@@ -306,14 +306,13 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 	// Non-persistent invocations still need an owned native Shell so its lifetime
 	// can be ended explicitly. executeShell creates a native shell outside the
 	// persistent registry, leaving its cleanup untrackable by the host process.
-	const oneShotShell =
-		!usePersistentShell || persistentSessionBroken
-			? new Shell({
-					sessionEnv: shellEnv,
-					snapshotPath: snapshotPath ?? undefined,
-					minimizer,
-				})
-			: undefined;
+	const oneShotShell = !usePersistentShell
+		? new Shell({
+				sessionEnv: shellEnv,
+				snapshotPath: snapshotPath ?? undefined,
+				minimizer,
+			})
+		: undefined;
 	const activeShell = shellSession ?? oneShotShell;
 	const userSignal = options?.signal;
 	const runAbortController = new AbortController();
@@ -389,20 +388,23 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			if (shellSession) {
 				resetSession = true;
 				retiringShellSessions.add(shellSession);
-				brokenShellSessions.add(sessionKey);
-				shellSessions.delete(sessionKey);
+				if (shellSessions.get(sessionKey) === shellSession) {
+					shellSessions.delete(sessionKey);
+				}
 				runSettled = await awaitAbortCleanup(runPromise);
+				// A retired session is never reused, so release the native shell instead
+				// of leaving it retained for the rest of the process lifetime.
 				if (runSettled) {
-					brokenShellSessions.delete(sessionKey);
 					retiringShellSessions.delete(shellSession);
+					void shellSession.close().catch(() => undefined);
 				} else {
 					void runPromise
 						.finally(() => {
-							brokenShellSessions.delete(sessionKey);
 							retiringShellSessions.delete(shellSession);
 							if (shellSessions.get(sessionKey) === shellSession) {
 								shellSessions.delete(sessionKey);
 							}
+							void shellSession.close().catch(() => undefined);
 						})
 						.catch(() => undefined);
 				}
@@ -508,7 +510,9 @@ export async function executeBash(command: string, options?: BashExecutorOptions
 			shellSessions.delete(sessionKey);
 		}
 		if (oneShotShell) {
-			const disposePromise = abortPromise ?? oneShotShell.abort();
+			// Always close: a successful run keeps its session retained, so aborting
+			// alone would leak the native shell and hold the event loop open.
+			const disposePromise = (abortPromise ?? Promise.resolve()).then(() => oneShotShell.close());
 			await Promise.race([disposePromise.catch(() => undefined), Bun.sleep(CANCEL_CLEANUP_WAIT_MS)]);
 		}
 	}

package/src/export/html/index.ts

@@ -1,3 +1,4 @@
+import * as syncFs from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AgentState } from "@gajae-code/agent-core";
@@ -162,6 +163,51 @@ async function assertExportDoesNotAliasSource(sourcePath: string, outputPath: st
 		throw new Error("HTML export output must not overwrite the source transcript");
 }
 
+const HTML_EXPORT_SOURCE_OPEN_FLAGS =
+	syncFs.constants.O_RDONLY |
+	syncFs.constants.O_NONBLOCK |
+	(process.platform === "win32" ? 0 : (syncFs.constants.O_NOFOLLOW ?? 0));
+
+const HTML_EXPORT_DESTINATION_OPEN_FLAGS =
+	syncFs.constants.O_WRONLY |
+	syncFs.constants.O_CREAT |
+	(process.platform === "win32" ? 0 : (syncFs.constants.O_NOFOLLOW ?? 0));
+
+function sameFileIdentity(left: syncFs.BigIntStats, right: syncFs.BigIntStats): boolean {
+	return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function openHtmlExportDescriptors(
+	sourcePath: string | undefined,
+	outputPath: string,
+): Promise<{ source: number | undefined; destination: number }> {
+	let source: number | undefined;
+	let destination: number | undefined;
+	try {
+		if (sourcePath) {
+			try {
+				source = syncFs.openSync(sourcePath, HTML_EXPORT_SOURCE_OPEN_FLAGS);
+			} catch (error) {
+				if (!isEnoent(error)) throw error;
+			}
+			await assertExportDoesNotAliasSource(sourcePath, outputPath);
+		}
+		destination = syncFs.openSync(outputPath, HTML_EXPORT_DESTINATION_OPEN_FLAGS, 0o666);
+		if (source !== undefined) {
+			const sourceIdentity = syncFs.fstatSync(source, { bigint: true });
+			const destinationIdentity = syncFs.fstatSync(destination, { bigint: true });
+			if (sameFileIdentity(sourceIdentity, destinationIdentity))
+				throw new Error("HTML export output must not overwrite the source transcript");
+		}
+		syncFs.ftruncateSync(destination, 0);
+		return { source, destination };
+	} catch (error) {
+		if (destination !== undefined) syncFs.closeSync(destination);
+		if (source !== undefined) syncFs.closeSync(source);
+		throw error;
+	}
+}
+
 async function writeSessionHtml(
 	sm: SessionManager,
 	state: AgentState | undefined,
@@ -174,8 +220,8 @@ async function writeSessionHtml(
 	const markerOffset = themedTemplate.indexOf(marker);
 	if (markerOffset < 0) throw new Error("HTML export template is missing the session-data marker");
 	const sourcePath = sm.getSessionFile();
-	if (sourcePath) await assertExportDoesNotAliasSource(sourcePath, outputPath);
-	const sink = Bun.file(outputPath).writer();
+	const descriptors = await openHtmlExportDescriptors(sourcePath, outputPath);
+	const sink = Bun.file(descriptors.destination).writer();
 	const encoder = new Base64StreamEncoder();
 	const writeEncoded = (value: string): void => {
 		const encoded = encoder.write(value);
@@ -204,6 +250,9 @@ async function writeSessionHtml(
 	} catch (error) {
 		await sink.end();
 		throw error;
+	} finally {
+		if (descriptors.source !== undefined) syncFs.closeSync(descriptors.source);
+		syncFs.closeSync(descriptors.destination);
 	}
 }
 

package/src/extensibility/extensions/loader.ts

@@ -240,7 +240,15 @@ class ConcreteExtensionAPI implements ExtensionAPI, IExtensionRuntime {
 
 	sendUserMessage(
 		content: string | (TextContent | ImageContent)[],
-		options?: { deliverAs?: "steer" | "followUp"; onPreflightAccepted?: () => void },
+		options?: {
+			deliverAs?: "steer" | "followUp";
+			queuedAtDispatch?: boolean;
+			onPreflightAccepted?: () => void;
+			onPreflightAcceptCommit?: () => void | Promise<void>;
+			onQueuedPromoted?: () => void;
+			preflightSignal?: AbortSignal;
+			sdkRunToken?: string;
+		},
 	): Promise<void> {
 		return Promise.resolve(this.runtime.sendUserMessage(content, options));
 	}

package/src/extensibility/extensions/runner.ts

@@ -69,12 +69,18 @@ interface BeforeAgentStartCombinedResult {
 
 export type ExtensionErrorListener = (error: ExtensionError) => void;
 
+/** Bounded timeout for session_shutdown handlers — generous but never infinite. */
+export const SESSION_SHUTDOWN_HANDLER_TIMEOUT_MS = 60_000;
 export const EXTENSION_HANDLER_TIMEOUT_MS = 30_000;
 let extensionHandlerTimeoutMs = EXTENSION_HANDLER_TIMEOUT_MS;
+let sessionShutdownHandlerTimeoutMs = SESSION_SHUTDOWN_HANDLER_TIMEOUT_MS;
 
 export function testSetExtensionHandlerTimeoutMs(timeoutMs: number): void {
 	extensionHandlerTimeoutMs = timeoutMs;
 }
+export function testSetSessionShutdownHandlerTimeoutMs(timeoutMs: number): void {
+	sessionShutdownHandlerTimeoutMs = timeoutMs;
+}
 
 const EXTENSION_HANDLER_TIMEOUT = Symbol("extensionHandlerTimeout");
 
@@ -201,7 +207,7 @@ export class ExtensionRunner {
 	#isIdleFn: () => boolean = () => true;
 	#getActivePromptHandleFn: () => string | undefined = () => undefined;
 	#waitForIdleFn: () => Promise<void> = async () => {};
-	#abortFn: () => void = () => {};
+	#abortFn: () => void | Promise<void> = () => {};
 	#abortPromptAndWaitFn: NonNullable<ExtensionContextActions["abortPromptAndWait"]> = async () => {
 		throw new Error("abortPromptAndWait binding is unavailable");
 	};
@@ -637,7 +643,7 @@ export class ExtensionRunner {
 			withSdkControlMutation: body => this.#withSdkControlMutationFn?.(body) ?? body(),
 			cycleThinkingLevel: () => this.#cycleThinkingLevelFn?.(),
 			setQueueMode: (kind, mode) => this.#setQueueModeFn?.(kind, mode) ?? false,
-			invokeSkill: async (name, args) => await this.#invokeSkillFn?.(name, args),
+			invokeSkill: async (name, args, options) => await this.#invokeSkillFn?.(name, args, options),
 
 			setPlanMode: on => this.#setPlanModeFn?.(on),
 			operateGoal: async (op, objective) => await this.#operateGoalFn?.(op, objective),
@@ -715,12 +721,13 @@ export class ExtensionRunner {
 		event: TEvent,
 		ctx: ExtensionContext,
 		ext: Extension,
-		timeoutMs: number,
+		timeoutMs: number | undefined,
 	): Promise<TResult | undefined> {
 		let timeout: NodeJS.Timeout | undefined;
 		const abortController = new AbortController();
 		const handlerContext = createHandlerContext(ctx, abortController.signal);
 		try {
+			if (timeoutMs === undefined) return await handler(event, handlerContext);
 			const timeoutPromise = new Promise<typeof EXTENSION_HANDLER_TIMEOUT>(resolve => {
 				timeout = setTimeout(() => resolve(EXTENSION_HANDLER_TIMEOUT), timeoutMs);
 			});
@@ -782,7 +789,13 @@ export class ExtensionRunner {
 				this.#markAttemptExecuted(scope);
 				marked = true;
 			}
-			const handlerResult = await this.#runHandlerWithTimeout(handler, event, ctx, ext, extensionHandlerTimeoutMs);
+			const handlerResult = await this.#runHandlerWithTimeout(
+				handler,
+				event,
+				ctx,
+				ext,
+				event.type === "session_shutdown" ? sessionShutdownHandlerTimeoutMs : extensionHandlerTimeoutMs,
+			);
 			if (continueWhile && !continueWhile()) return result as RunnerEmitResult<TEvent>;
 
 			if (this.#isSessionBeforeEvent(event) && handlerResult) {

package/src/extensibility/extensions/types.ts

@@ -65,7 +65,6 @@ import type {
 import type { EventBus } from "../../utils/event-bus";
 import type {
 	AgentEndEvent,
-	AgentStartEvent,
 	AutoCompactionEndEvent,
 	AutoCompactionStartEvent,
 	AutoRetryEndEvent,
@@ -89,6 +88,7 @@ import type {
 	SessionStartEvent,
 	SessionSwitchEvent,
 	SessionTreeEvent,
+	AgentStartEvent as SharedAgentStartEvent,
 	TodoReminderEvent,
 	ToolCallEventResult,
 	ToolResultEventResult,
@@ -369,7 +369,7 @@ export interface ExtensionContext {
 	/** Stable resource ownership identifier for the active prompt run. */
 	getActivePromptHandle(): string | undefined;
 	/** Abort the current agent operation */
-	abort(): void;
+	abort(): void | Promise<void>;
 	/** Abort and prove whether resources for a specific prompt settled. */
 	abortPromptAndWait?(handle: string, options: { graceMs: number }): Promise<RunSettlementProof>;
 	/** Whether there are queued messages waiting */
@@ -429,6 +429,7 @@ export interface ExtensionContext {
 			onPreflightAccepted?: () => void;
 			onPreflightAcceptCommit?: () => void | Promise<void>;
 			onSkillPrepared?: (meta: { name: string; path: string; lineCount?: number; cleanedArgs?: string }) => void;
+			preflightSignal?: AbortSignal;
 		},
 	): Promise<unknown>;
 	setPlanMode?(on: boolean): unknown;
@@ -634,7 +635,12 @@ export interface BeforeAgentStartEvent {
 	systemPrompt: string[];
 }
 
-export type { AgentEndEvent, AgentStartEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
+export type { AgentEndEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
+
+/** Fired when an agent loop starts. `sdkRunToken` is an internal SDK queue-owner binding. */
+export interface AgentStartEvent extends SharedAgentStartEvent {
+	sdkRunToken?: string;
+}
 
 /** Fired when a message starts (user, assistant, or toolResult) */
 export interface MessageStartEvent {
@@ -1169,7 +1175,10 @@ export interface ExtensionAPI {
 	 */
 	sendMessage<T = unknown>(
 		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">,
-		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+		options?: {
+			triggerTurn?: boolean;
+			deliverAs?: "steer" | "followUp" | "nextTurn";
+		},
 	): void;
 
 	/** Send a user message to the agent, or queue it when deliverAs is set. */
@@ -1177,8 +1186,14 @@ export interface ExtensionAPI {
 		content: string | (TextContent | ImageContent)[],
 		options?: {
 			deliverAs?: "steer" | "followUp";
+			/** Internal SDK signal preserving a busy dispatch across async admission fences. */
+			queuedAtDispatch?: boolean;
 			onPreflightAccepted?: () => void;
 			onPreflightAcceptCommit?: () => void | Promise<void>;
+			onQueuedPromoted?: () => void;
+			preflightSignal?: AbortSignal;
+			/** Internal SDK correlation owner for an exact queued follow-up. */
+			sdkRunToken?: string;
 		},
 	): Promise<void>;
 
@@ -1387,7 +1402,10 @@ export type SendMessageHandler = <T = unknown>(
 	 * When paired with `triggerTurn: true` during prompt teardown, the session schedules
 	 * an internal continuation without surfacing the message in the editable pending queue.
 	 */
-	options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	options?: {
+		triggerTurn?: boolean;
+		deliverAs?: "steer" | "followUp" | "nextTurn";
+	},
 ) => void;
 
 export type SendUserMessageHandler = (
@@ -1396,6 +1414,11 @@ export type SendUserMessageHandler = (
 		deliverAs?: "steer" | "followUp";
 		onPreflightAccepted?: () => void;
 		onPreflightAcceptCommit?: () => void | Promise<void>;
+		/** Fired when a queued submission (steering or follow-up) is promoted to its own run (SDK ownership correlation). */
+		onQueuedPromoted?: () => void;
+		preflightSignal?: AbortSignal;
+		/** Internal SDK correlation owner for an exact queued follow-up. */
+		sdkRunToken?: string;
 	},
 ) => void | Promise<void>;
 
@@ -1485,8 +1508,9 @@ export interface ExtensionContextActions {
 	isIdle: () => boolean;
 	/** Stable resource ownership identifier for the active prompt run. */
 	getActivePromptHandle?: () => string | undefined;
-	abort: () => void;
+	abort: () => void | Promise<void>;
 	abortPromptAndWait?: (handle: string, options: { graceMs: number }) => Promise<RunSettlementProof>;
+
 	hasPendingMessages: () => boolean;
 	/** Typed pending-message counts per queue; optional for embedders without a counted queue. */
 	getPendingMessageCounts?: () => { steering: number; followUp: number; nextTurn: number };
@@ -1555,6 +1579,7 @@ export interface ExtensionContextActions {
 			onPreflightAccepted?: () => void;
 			onPreflightAcceptCommit?: () => void | Promise<void>;
 			onSkillPrepared?: (meta: { name: string; path: string; lineCount?: number; cleanedArgs?: string }) => void;
+			preflightSignal?: AbortSignal;
 		},
 	) => Promise<unknown>;
 	setPlanMode?: (on: boolean) => unknown;

package/src/extensibility/gjc-plugins/constrained-hooks.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { logger } from "@gajae-code/utils";
+import { normalizePluginHook } from "../../hooks/normalize";
 import { bundleIdentity } from "./lifecycle-reconciliation";
 import { verifyImplementationHash } from "./metadata";
 import { resolveWithinRoot } from "./paths";
@@ -106,6 +107,19 @@ export class ConstrainedPluginHookDescriptor {
 	}
 
 	async load(): Promise<ConstrainedPluginHook> {
+		const normalized = normalizePluginHook({
+			declaredEvent: this.event,
+			target: this.target,
+			phase: this.phase,
+			plugin: this.plugin,
+			source: this.relativePath,
+		});
+		if (!normalized.hook) {
+			throw new GjcPluginLoadError(
+				"invalid_hook",
+				normalized.diagnostics.map(diagnostic => `${diagnostic.code}: ${diagnostic.message}`).join("; "),
+			);
+		}
 		if (this.implementationHash) await verifyImplementationHash(this.relativePath, this.implementationHash);
 		const registered: { event: string; handler: (...a: any[]) => unknown }[] = [];
 		const deny = (method: string) => () => {
@@ -171,6 +185,25 @@ export async function loadConstrainedPluginHooks(input: { cwd: string }): Promis
 	const invalidHookIds = new Set<string>();
 	for (const entry of effective) {
 		if (!entry.enabled) continue;
+		for (const hook of entry.surfaces.hooks) {
+			if (entry.disabledSurfaceIds.includes(hook.extensionId)) continue;
+			const normalized = normalizePluginHook({
+				declaredEvent: hook.event,
+				target: hook.target,
+				phase: hook.phase,
+				plugin: entry.name,
+				source: hook.relativePath,
+			});
+			if (normalized.hook) continue;
+			invalidHookIds.add(`${entry.scope}:${entry.name}:${hook.extensionId}`);
+			preQuarantine.push({
+				identity: bundleIdentity(entry.scope, entry.name),
+				plugin: entry.name,
+				surfaceId: hook.extensionId,
+				code: "invalid_hook",
+				message: normalized.diagnostics.map(diagnostic => `${diagnostic.code}: ${diagnostic.message}`).join("; "),
+			});
+		}
 		const drift = await verifyEntryHashes(entry);
 		if (drift) preQuarantine.push(drift);
 		for (const hook of entry.surfaces.hooks) {

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

@@ -392,8 +392,12 @@ export async function runGjcBundleTransaction(
 ): Promise<GjcBundleTransactionResult> {
 	const resolved = await resolveSource(source);
 	try {
-		// Compile + validate outside every lock (never imports plugin code).
+		// Compile + validate candidate-internal collisions and MCP policy outside
+		// every lock (never imports plugin code). Registry collisions are rechecked
+		// under both locks below, but a statically invalid candidate must not create
+		// lock roots or sweep installation remnants.
 		const bundle = await compileGjcPluginBundle(resolved.dir);
+		validateInstallPlan(bundle, []);
 		const dirName = safeDirSegment(bundle.name);
 		const root = scopeRoot(options.scope, options.cwd);
 		const finalDir = path.join(root, dirName);
@@ -450,10 +454,6 @@ export async function runGjcBundleTransaction(
 			if (decision.kind === "abort") return { status: "aborted", error: decision.error, remnants: [] };
 			if (decision.kind === "noop") return { status: "noop", entry: decision.entry, remnants: [] };
 
-			// The decision committed, so mutation may begin.
-			await fs.mkdir(root, { recursive: true });
-			await cleanupOrphans(root, dirName);
-
 			// Hard install-time collision + MCP security validation against the
 			// effective registry across BOTH scopes. Surface IDs derive from the
 			// surface name, not the bundle name, so a differently named bundle in
@@ -461,6 +461,10 @@ export async function runGjcBundleTransaction(
 			// identity is excluded, since that is the entry being replaced.
 			validateInstallPlan(bundle, effective);
 
+			// The decision and all validation committed, so mutation may begin.
+			await fs.mkdir(root, { recursive: true });
+			await cleanupOrphans(root, dirName);
+
 			const unique = `${process.pid}-${randomBytes(6).toString("hex")}`;
 			const stagingDir = `${finalDir}.installing-${unique}`;
 			const backupDir = `${finalDir}.backup-${unique}`;

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

@@ -65,9 +65,15 @@ function rowsForEntry(entry: GjcPluginRegistryEntry, quarantinedIds: Map<string,
 /**
  * Build the observability summary for the effective registry at `cwd`, including
  * hash-drift and session-collision quarantine status.
+ *
+ * Pass `{ migrate: false }` from read-only inspection surfaces (for example
+ * `gjc customize doctor`) so reporting never persists registry migrations.
  */
-export async function summarizeGjcPluginObservability(cwd: string): Promise<PluginObservabilitySummary> {
-	const effective = await loadEffectiveGjcPluginRegistry(cwd);
+export async function summarizeGjcPluginObservability(
+	cwd: string,
+	options: { migrate?: boolean } = {},
+): Promise<PluginObservabilitySummary> {
+	const effective = await loadEffectiveGjcPluginRegistry(cwd, options);
 	const preQuarantine: SessionQuarantine[] = [];
 	for (const entry of effective) {
 		if (!entry.enabled) continue;

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

@@ -319,9 +319,20 @@ export async function updateRegistry(
 
 /**
  * Effective registry for a cwd: user + project entries in deterministic order.
+ *
+ * Defaults to the startup semantics (legacy-entry discovery + migration, which
+ * may persist the migrated registry). Read-only inspection surfaces (for
+ * example `gjc customize doctor`) pass `{ migrate: false }` so reporting never
+ * writes to the registry.
  */
-export async function loadEffectiveGjcPluginRegistry(cwd: string): Promise<GjcPluginRegistryEntry[]> {
-	const [user, project] = await Promise.all([readRegistry("user", cwd), readRegistry("project", cwd)]);
+export async function loadEffectiveGjcPluginRegistry(
+	cwd: string,
+	options: { migrate?: boolean } = {},
+): Promise<GjcPluginRegistryEntry[]> {
+	const [user, project] = await Promise.all([
+		readRegistry("user", cwd, options),
+		readRegistry("project", cwd, options),
+	]);
 	return sortRegistryEntries([...user.plugins, ...project.plugins]);
 }
 

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

@@ -437,7 +437,9 @@ export async function buildPluginMcpConfigs(input: { cwd: string }): Promise<{
 	const { assertMcpInstallPolicy, assertDnsResolvesPublic, assertUrlAllowed } = await import("./mcp-policy");
 	const nodePath = await import("node:path");
 
-	const configs: Record<string, any> = {};
+	// A manifest-controlled MCP name such as "constructor" or "toString" must
+	// remain an ordinary own key rather than interacting with Object.prototype.
+	const configs: Record<string, any> = Object.create(null) as Record<string, any>;
 	for (const entry of active) {
 		const disabled = new Set(entry.disabledSurfaceIds);
 		for (const m of entry.surfaces.mcps) {