@gajae-code/coding-agent 0.16.4 → 0.16.6

package/dist/types/sdk/session.d.ts

@@ -62,6 +62,8 @@ export interface CreateAgentSessionOptions {
     cwd?: string;
     /** Global config directory. Default: ~/.gjc/agent */
     agentDir?: string;
+    /** Resolver-owned classification for `agentDir`; required when authority must survive HOME/config refreshes. */
+    profileAuthority?: "default" | "custom";
     /** Spawns to allow. Default: "*" */
     spawns?: string;
     /** Auth storage for credentials. Default: discoverAuthStorage(agentDir) */
@@ -336,7 +338,7 @@ export declare function discoverSkills(_cwd?: string, _agentDir?: string, _setti
  * Discover context files (AGENTS.md) walking up from cwd.
  * Returns files sorted by depth (farther from cwd first, so closer files appear last/more prominent).
  */
-export declare function discoverContextFiles(cwd?: string, _agentDir?: string): Promise<Array<{
+export declare function discoverContextFiles(cwd?: string, agentDir?: string): Promise<Array<{
     path: string;
     content: string;
     depth?: number;
@@ -361,6 +363,8 @@ export interface BuildSystemPromptOptions {
         content: string;
     }>;
     cwd?: string;
+    agentDir?: string;
+    profileAuthority?: "default" | "custom";
     appendPrompt?: string;
     repeatToolDescriptions?: boolean;
 }

package/dist/types/session/agent-session.d.ts

@@ -826,6 +826,8 @@ export declare class AgentSession {
     awaitSessionSettlement(): Promise<void>;
     /** Test seam: hold prompt admission while bypassing a pending selection fence. */
     runWithPromptAdmissionForTests(body: () => Promise<void>): Promise<void>;
+    /** Test seam: await all currently admitted coordinator sidecar writes. */
+    awaitCoordinatorRuntimeStatePersistenceForTests(): Promise<void>;
     queueCoordinatorRuntimeStatePersistForTests(event: AgentSessionEvent, gate: Promise<void>): Promise<void>;
     parkAgentEndForCoordinatorPersistForTests(event: Extract<AgentSessionEvent, {
         type: "agent_end";

package/dist/types/session/fallback-chain-controller.d.ts

@@ -95,5 +95,20 @@ export declare function cappedExponentialWithFullJitter(baseDelayMs: number, max
  * A missing, NaN, or infinite hint collapses to "no usable hint".
  */
 export declare function compactionRetryDelay(baseDelayMs: number, maxDelayMs: number, attempt: number, retryAfterMs: number | undefined): number;
+export interface CompactionCandidateFailure {
+    readonly model: string;
+    readonly message: string;
+}
+/**
+ * Error for an auto-compaction run whose every candidate failed.
+ *
+ * The candidate chain starts at the session model and ends on a same-provider
+ * largest-context fallback, so surfacing only the final error named a model
+ * the user never chose and hid that their own model had already failed the
+ * same way. The message leads with the first failure (the one the user can act
+ * on), then lists every candidate that was tried with its own error. `cause`
+ * is the final error so callers that classify by type keep the same object.
+ */
+export declare function describeCompactionCandidateFailures(failures: readonly CompactionCandidateFailure[], lastError: unknown): Error;
 /** Retry-After is intentionally uncapped. */
 export declare function effectiveFallbackDelay(baseDelayMs: number, maxDelayMs: number, attemptK: number, retryAfterMs: number | undefined, random?: () => number): number;

package/dist/types/session/internal/managed-session-storage.d.ts

@@ -6,6 +6,13 @@ export declare const MANAGED_ARTIFACT_MAX_FILES = 50000;
 export declare const MANAGED_ARTIFACT_MAX_FILE_BYTES: number;
 export declare const MANAGED_ARTIFACT_MAX_TOTAL_BYTES: number;
 export declare const MANAGED_ARTIFACT_COPY_BATCH_SIZE = 256;
+/** A pre-mutation append fence rejection: no bytes from this append were written. */
+export declare class ManagedAppendIdentityMismatchError extends Error {
+    readonly code = "managed_append_identity_mismatch";
+    readonly relativePath: string;
+    readonly operatorMessage = "Session was resumed by another process; this resume did not run. Retry, or resume a different session.";
+    constructor(relativePath: string);
+}
 export declare class ManagedPublishError extends Error {
     readonly classification: "destination_conflict" | "atomic_unavailable" | "invalid_request" | "durability_not_provable" | "identity_mismatch" | "io_error" | "durability_failed";
     readonly diagnostic: string;

package/dist/types/session/messages.d.ts

@@ -82,6 +82,7 @@ export interface BashExecutionMessage {
     command: string;
     output: string;
     exitCode: number | undefined;
+    signal?: string;
     cancelled: boolean;
     truncated: boolean;
     meta?: OutputMeta;

package/dist/types/session/session-manager.d.ts

@@ -9,7 +9,7 @@ import type { ManagedLegacyLocalMigrationSource } from "../internal-urls/local-p
 import { ArtifactManager } from "./artifacts";
 import { type BlobPutResult, BlobStore } from "./blob-store";
 import { type ManagedMigrationPolicy } from "./internal/managed-session-scope";
-import { type ManagedBoundedAppendExpectation, type ManagedDirectoryRoot, type ManagedFileIdentity, ManagedSessionDescendantStore } from "./internal/managed-session-storage";
+import { ManagedAppendIdentityMismatchError, type ManagedBoundedAppendExpectation, type ManagedDirectoryRoot, type ManagedFileIdentity, ManagedSessionDescendantStore } from "./internal/managed-session-storage";
 import { type BaseAnchor, BoundedLabelsPinsStore, type CommittedTail, type DescriptorSnapshot, type DictionaryPartitionCommit, FixedCacheAccount, type MetadataDeltaValue, type ParentBucketCommit, type ReducerState, type ReopenClassification, SessionMemoryAccountant } from "./internal/session-memory-sidecar";
 import { type MemoryGuardCreateCheckpointInput, type MemoryGuardParticipantIngressLease, type MemoryGuardRestoreInput, type MemoryGuardRestoreResult, type MemoryGuardSessionManagerCheckpointV1 } from "./memory-guard-checkpoint-participant";
 import { type BashExecutionMessage, type CustomMessage, type FileMentionMessage, type HookMessage, type PythonExecutionMessage } from "./messages";
@@ -1291,6 +1291,8 @@ export declare class SessionManager {
             }) => Promise<fs.BigIntStats>;
         };
     }): Promise<void>;
+    /** Ownership loss remains observable even when an agent event listener aborts the turn. */
+    getAppendIdentityMismatch(): ManagedAppendIdentityMismatchError | undefined;
     isPersisted(): boolean;
     stageDefaultModelSelection(model: string, thinkingLevel: string | undefined, options?: {
         readonly appendThinkingLevel: boolean;

package/dist/types/setup/paseo/announce.d.ts

@@ -1,4 +1,3 @@
-export { resolvePaseoHome } from "./setup-deps";
 export type PaseoDaemonTarget = {
     readonly kind: "ipc";
     readonly socketPath: string;
@@ -40,6 +39,8 @@ export interface PaseoAnnounceDependencies {
         readonly providerKey: string;
         readonly cwd: string;
         readonly sessionId: string;
+        readonly daemonTarget: PaseoDaemonTarget;
+        readonly daemonHost: string;
         readonly signal?: AbortSignal;
     }): Promise<PaseoAnnounceOutcome>;
 }
@@ -64,7 +65,7 @@ export declare function parseDaemonListen(raw: string): PaseoDaemonTarget | unde
  * environment override, then the running daemon's own pid file, then the
  * configured listener, then Paseo's default.
  */
-export declare function resolveDaemonTarget(config: unknown, deps: Pick<PaseoAnnounceDependencies, "env" | "paseoHome" | "readJson">): Promise<PaseoDaemonTarget>;
+export declare function resolveDaemonTarget(config: unknown, deps: Pick<PaseoAnnounceDependencies, "env" | "paseoHome" | "readJson">): Promise<PaseoDaemonTarget | undefined>;
 /**
  * Turn a non-zero `paseo import` into an outcome.
  *
@@ -107,5 +108,5 @@ export declare function startPaseoAnnouncement(input: {
     isEnabled?: () => boolean;
     onOutcome?: (outcome: PaseoAnnounceOutcome) => void;
 }, deps: PaseoAnnounceDependencies): PaseoAnnouncementHandle;
-export declare function sessionListContainsLiveSessionForTests(sessions: readonly unknown[], sessionId: string, cwd: string): boolean;
+export declare function sessionListContainsLiveSession(sessions: readonly unknown[], sessionId: string, cwd: string): boolean;
 export declare function createDefaultPaseoAnnounceDependencies(agentDir: string, env?: NodeJS.ProcessEnv): PaseoAnnounceDependencies;

package/dist/types/skill-state/canonical-skills.d.ts

@@ -1,3 +1,7 @@
 /** Native-free canonical GJC workflow skill identifiers. */
 export declare const CANONICAL_GJC_WORKFLOW_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "autoresearch"];
 export type CanonicalGjcWorkflowSkill = (typeof CANONICAL_GJC_WORKFLOW_SKILLS)[number];
+/** Case-insensitive, Win32-path-equivalent key used for skill collision checks. */
+export declare function getSkillFilesystemIdentity(name: string): string;
+/** Whether a name resolves to a bundled workflow under portable filesystem semantics. */
+export declare function isCanonicalGjcWorkflowSkillFilesystemAlias(name: string): boolean;

package/dist/types/system-prompt.d.ts

@@ -15,6 +15,10 @@ export declare function resolvePromptInput(input: string | undefined, descriptio
 export interface LoadContextFilesOptions {
     /** Working directory to start walking up from. Default: getProjectDir() */
     cwd?: string;
+    /** Agent directory backing native user-scope context and system prompt files. */
+    agentDir?: string;
+    /** Resolver-owned classification for `agentDir`; preserve it across HOME/config refreshes. */
+    profileAuthority?: "default" | "custom";
 }
 export interface ProjectContextFilesResult {
     contextFiles: Array<{
@@ -70,6 +74,10 @@ export interface BuildSystemPromptOptions {
     skillsSettings?: SkillsSettings;
     /** Working directory. Default: getProjectDir() */
     cwd?: string;
+    /** Agent directory backing native user-scope prompt discovery. */
+    agentDir?: string;
+    /** Resolver-owned classification for `agentDir`; preserve it across HOME/config refreshes. */
+    profileAuthority?: "default" | "custom";
     /** Pre-loaded context files (skips discovery if provided). */
     contextFiles?: Array<{
         path: string;

package/dist/types/task/executor.d.ts

@@ -95,6 +95,9 @@ export interface ExecutorOptions {
     authStorage?: AuthStorage;
     modelRegistry?: ModelRegistry;
     settings?: Settings;
+    /** Parent session's selected agent directory and immutable resolver-owned authority. */
+    agentDir?: string;
+    profileAuthority?: "default" | "custom";
     /** Parent session's registry; shared by child sessions for IRC routing and roster visibility. */
     agentRegistry?: AgentRegistry;
     /**

package/dist/types/tools/bash.d.ts

@@ -19,6 +19,7 @@ export declare const STEER_FOLD_GRACE_MS = 2000;
 /** Model-facing line appended to a steer-folded background-start result. */
 export declare function steerFoldReasonLine(jobId: string): string;
 export type BashOriginalArtifactSaveResult = BashArtifactSaveResult;
+export declare function suffixPrefixOverlap(source: string, target: string): number;
 export declare function saveBashOriginalArtifactForTests(session: ToolSession, originalText: string, onResult?: (result: BashOriginalArtifactSaveResult) => void): Promise<string | undefined>;
 declare const bashSchemaBase: z.ZodObject<{
     command: z.ZodString;

package/dist/types/tools/github-cache.d.ts

@@ -78,9 +78,10 @@ export interface CacheLookupOptions<T> {
      * must bypass persistent cache reads/writes.
      */
     authKey?: string | null;
-    fetchFresh: () => Promise<FreshResult<T>>;
+    fetchFresh: (signal?: AbortSignal) => Promise<FreshResult<T>>;
     settings?: Settings | undefined;
     now?: number;
+    signal?: AbortSignal;
 }
 export type CacheStatus = "miss" | "fresh" | "stale" | "disabled";
 export interface CacheLookupResult<T> {

package/dist/types/tools/index.d.ts

@@ -152,6 +152,8 @@ export interface ToolSession {
      * Runtime discovery only; never threaded into capability loading.
      */
     home?: string;
+    /** Resolver-owned classification for the session's selected agent directory. */
+    profileAuthority?: "default" | "custom";
     skills?: Skill[];
     /** Currently executing skill prompt, when this tool session is inside one. */
     getActiveSkillState?: () => Pick<SkillActiveEntry, "skill" | "session_id"> | undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.16.4",
+	"version": "0.16.6",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -56,12 +56,12 @@
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.16.4",
-		"@gajae-code/agent-core": "0.16.4",
-		"@gajae-code/ai": "0.16.4",
-		"@gajae-code/natives": "0.16.4",
-		"@gajae-code/tui": "0.16.4",
-		"@gajae-code/utils": "0.16.4",
+		"@gajae-code/stats": "0.16.6",
+		"@gajae-code/agent-core": "0.16.6",
+		"@gajae-code/ai": "0.16.6",
+		"@gajae-code/natives": "0.16.6",
+		"@gajae-code/tui": "0.16.6",
+		"@gajae-code/utils": "0.16.6",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",
@@ -130,6 +130,8 @@
 		"./session/session-manager-internal.js": null,
 		"./session/sdk-run-capability": null,
 		"./session/sdk-run-capability.js": null,
+		"./extensibility/extensions/function-hooks-internal": null,
+		"./extensibility/extensions/function-hooks-internal.js": null,
 		"./sdk": {
 			"types": "./dist/types/sdk/index.d.ts",
 			"import": "./src/sdk/index.ts"

package/scripts/generate-sdk-operation-inventory.ts

@@ -115,6 +115,8 @@ const LOCKED_EXCLUSIONS: Readonly<Record<string, string>> = {
 	"agent_session:getPendingNextTurnMessagesForTests": "read-only test seam, not a user-facing SDK control seam",
 	"agent_session:queueCoordinatorRuntimeStatePersistForTests":
 		"test-only coordinator persistence ordering seam, not a user-facing SDK control seam",
+	"agent_session:awaitCoordinatorRuntimeStatePersistenceForTests":
+		"test-only coordinator persistence drain barrier, not a user-facing SDK control seam",
 	"agent_session:parkAgentEndForCoordinatorPersistForTests":
 		"test-only parked terminal persistence seam, not a user-facing SDK control seam",
 	"agent_session:flushParkedAgentEndForCoordinatorPersistForTests":

package/src/capability/index.ts

@@ -7,7 +7,14 @@
  * - Loading items for a capability across all providers
  */
 import * as path from "node:path";
-import { getAgentDir, getProjectDir, getTrustedHomeDir, logger } from "@gajae-code/utils";
+import {
+	getAgentDir,
+	getAgentProfileAuthority,
+	getProjectDir,
+	getTrustedHomeDir,
+	logger,
+	normalizePathForComparison,
+} from "@gajae-code/utils";
 
 import type { Settings } from "../config/settings";
 import { clearCache as clearFsCache, findRepoRoot, cacheStats as fsCacheStats, invalidate as invalidateFs } from "./fs";
@@ -243,8 +250,13 @@ export async function loadCapability<T>(capabilityId: string, options: LoadOptio
 	const cwd = options.cwd ?? getProjectDir();
 	const home = getTrustedHomeDir();
 	const userAgentDir = options.agentDir ? path.resolve(options.agentDir) : getAgentDir();
+	const profileAuthority =
+		options.profileAuthority ??
+		(options.agentDir && normalizePathForComparison(userAgentDir) !== normalizePathForComparison(getAgentDir())
+			? "custom"
+			: getAgentProfileAuthority());
 	const repoRoot = await findRepoRoot(cwd);
-	const ctx: LoadContext = { cwd, home, userAgentDir, repoRoot, settings: options.settings };
+	const ctx: LoadContext = { cwd, home, userAgentDir, profileAuthority, repoRoot, settings: options.settings };
 	const providers = filterProviders(capability, options);
 
 	return await loadImpl(capability, providers, ctx, options);

package/src/capability/types.ts

@@ -29,6 +29,8 @@ export interface LoadContext {
 	 * produced. This includes MCP registrations and user-installed skills.
 	 */
 	userAgentDir?: string;
+	/** Resolver-owned classification for the selected user agent directory. */
+	profileAuthority?: "default" | "custom";
 	/** Git repository root (directory containing .git), or null if not in a repo */
 	repoRoot: string | null;
 	/** Owning session settings for provider policy decisions. */
@@ -89,6 +91,8 @@ export interface LoadOptions {
 	 * process-wide one (`createAgentSession({ agentDir })`).
 	 */
 	agentDir?: string;
+	/** Resolver-owned classification for `agentDir`; preserve it across HOME/config refreshes. */
+	profileAuthority?: "default" | "custom";
 	/** Include items even if they fail validation. Default: false */
 	includeInvalid?: boolean;
 	/** Include items disabled via settings. Default: false */

package/src/cli/customize-doctor.ts

@@ -38,6 +38,8 @@ import { initializeWithSettings, loadCapability } from "../discovery";
 import { inspectClaudeConvention } from "../discovery/claude";
 import { inspectCodexConvention } from "../discovery/codex";
 import { scanSkillsFromDir } from "../discovery/helpers";
+import { functionHookGrantHash, normalizeFunctionHookGrant } from "../extensibility/extensions/function-hooks";
+import { compileGjcPluginBundle } from "../extensibility/gjc-plugins/compiler";
 import { summarizeGjcPluginObservability } from "../extensibility/gjc-plugins/observability";
 import { loadEffectiveGjcPluginRegistry } from "../extensibility/gjc-plugins/registry";
 import { getEnabledPlugins } from "../extensibility/plugins/loader";
@@ -47,7 +49,10 @@ import { loadAllMCPConfigs } from "../runtime-mcp/config";
 import { readDisabledServers } from "../runtime-mcp/config-writer";
 import { canonicalizeMCPEndpoint } from "../runtime-mcp/pool-key";
 import { redactMCPEndpoint } from "../runtime-mcp/redaction";
-import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+import {
+	getSkillFilesystemIdentity,
+	isCanonicalGjcWorkflowSkillFilesystemAlias,
+} from "../skill-state/canonical-skills";
 import { expandTilde } from "../tools/path-utils";
 
 // =============================================================================
@@ -153,6 +158,29 @@ export interface CustomizeDoctorItem {
 	mcp?: McpSafeSummary;
 	/** Present only for quarantined plugin-bundle surfaces. */
 	quarantineCode?: string;
+	/** Metadata-only Function Hook policy projection; hook code is never executed. */
+	functionHooks?: CustomizeFunctionHookSummary[];
+}
+
+export interface CustomizeFunctionHookSummary {
+	extensionId: string;
+	order: number;
+	event: string;
+	target?: string;
+	phase?: "before" | "after";
+	scope: "user" | "project";
+	plugin: string;
+	relativePath: string;
+	status: "disabled" | "quarantined" | "blocked-isolate" | "legacy-active";
+	requestedCapabilities: string[];
+	effectiveCapabilities: string[];
+	attenuateDownstream: string[];
+	networkDestinations: string[];
+	filesystemRoots: string[];
+	capabilityHash?: string;
+	implementationHash?: string;
+	quarantineCode?: string;
+	remediation: string;
 }
 
 export interface CustomizeDoctorSurface {
@@ -200,8 +228,6 @@ export interface CustomizeDoctorCommandOptions {
 
 const REDACTED = "<redacted>";
 
-const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
-
 const SENSITIVE_KEY_PATTERN =
 	/(?:token|secret|key|credential|password|passwd|pwd|authorization|auth|bearer|cookie|session|apikey)/i;
 
@@ -655,7 +681,7 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 			cwd,
 			disabledExtensions: activeSettings.get("disabledExtensions"),
 		});
-		for (const skill of result.skills) loadedNames.add(skill.name);
+		for (const skill of result.skills) loadedNames.add(getSkillFilesystemIdentity(skill.name));
 	}
 
 	const skillScopeNotes: string[] = [];
@@ -730,7 +756,7 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 				[`Move the skill under .gjc/skills/<name>/SKILL.md to make it loadable`],
 			);
 		}
-		if (BUILT_IN_SKILL_NAMES.has(entry.name)) {
+		if (isCanonicalGjcWorkflowSkillFilesystemAlias(entry.name)) {
 			return finalizeItem(
 				base,
 				"shadowed",
@@ -740,7 +766,7 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 				{ precedence: { priority: entry.priority, shadowedBy: { provider: "bundled", scope: "native" } } },
 			);
 		}
-		if (loadedNames.has(entry.name)) {
+		if (loadedNames.has(getSkillFilesystemIdentity(entry.name))) {
 			return finalizeItem(base, "loaded", "loaded", "Loaded by session startup.", []);
 		}
 		if (ignoredPatterns.length > 0 || includePatterns.length > 0) {
@@ -809,7 +835,7 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 				);
 				continue;
 			}
-			if (BUILT_IN_SKILL_NAMES.has(skill.name)) {
+			if (isCanonicalGjcWorkflowSkillFilesystemAlias(skill.name)) {
 				items.push(
 					finalizeItem(
 						base,
@@ -828,7 +854,10 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 			// in loadedNames even though it loses the name collision to an
 			// earlier-priority source. The collision must report shadowed-by-
 			// precedence, not a second "loaded" item.
-			const collisionWinner = items.find(i => i.name === skill.name && i.status === "loaded");
+			const skillIdentity = getSkillFilesystemIdentity(skill.name);
+			const collisionWinner = items.find(
+				i => getSkillFilesystemIdentity(i.name) === skillIdentity && i.status === "loaded",
+			);
 			if (collisionWinner) {
 				items.push(
 					finalizeItem(
@@ -847,7 +876,7 @@ async function collectSkills(cwd: string, activeSettings: SettingsInstance): Pro
 				);
 				continue;
 			}
-			if (loadedNames.has(skill.name)) {
+			if (loadedNames.has(skillIdentity)) {
 				items.push(
 					finalizeItem(base, "loaded", "loaded", "Loaded by session startup from skills.customDirectories.", []),
 				);
@@ -910,8 +939,11 @@ async function collectHooks(cwd: string, activeSettings: SettingsInstance): Prom
 		nameOf: hook => hook.name,
 		pathOf: hook => hook.path,
 		notExecutedDetail:
-			"Discovered and shown in the extension dashboard, but standalone sessions do not execute hook files. Runtime hooks come from validated GJC plugin bundles.",
-		notExecutedRemediation: ["See `gjc plugin list` for plugin bundles that contribute runtime hooks"],
+			"Trusted filesystem hook module discovered for session-start activation. Doctor does not execute the module, so dynamic Function Hook registrations and effective runtime order remain opaque until a session loads it.",
+		notExecutedRemediation: [
+			"Review the trusted hook source before session startup",
+			"Use plugin-bundle Function Hooks for declarative grants, hashes, quarantine, and metadata-only policy inspection",
+		],
 	});
 }
 
@@ -1140,7 +1172,101 @@ async function collectPluginBundles(cwd: string): Promise<CustomizeDoctorSurface
 	const bundleEntries = await loadEffectiveGjcPluginRegistry(cwd, { migrate: false });
 	const observability = await summarizeGjcPluginObservability(cwd, { migrate: false });
 	const items: CustomizeDoctorItem[] = [...npmItems];
+	let globalFunctionHookOrder = 0;
 	for (const entry of bundleEntries) {
+		const surfaces = observability.surfaces.filter(s => s.plugin === entry.name && s.scope === entry.scope);
+		let compiledHooks = new Map<
+			string,
+			Awaited<ReturnType<typeof compileGjcPluginBundle>>["surfaces"]["hooks"][number]
+		>();
+		try {
+			const compiled = await compileGjcPluginBundle(entry.pluginRoot);
+			compiledHooks = new Map(compiled.surfaces.hooks.map(hook => [hook.extensionId, hook]));
+		} catch {
+			// Existing observability reports unreadable/hash-drift bundles. Keep
+			// declarative rows visible and mark unmatched metadata quarantined.
+		}
+		const functionHooks: CustomizeFunctionHookSummary[] = entry.surfaces.hooks.map(hook => {
+			const observed = surfaces.find(surface => surface.extensionId === hook.extensionId);
+			const compiled = compiledHooks.get(hook.extensionId);
+			const hasGrantMetadata =
+				hook.capabilities !== undefined ||
+				hook.networkDestinations !== undefined ||
+				hook.filesystemRoots !== undefined ||
+				hook.capabilityHash !== undefined;
+			let metadataValid =
+				compiled !== undefined &&
+				((hook.functionHook === true && hasGrantMetadata) ||
+					(hook.functionHook !== true && !hasGrantMetadata && compiled.functionHook !== true));
+			try {
+				const grant = normalizeFunctionHookGrant({
+					capabilities: hook.capabilities,
+					networkDestinations: hook.networkDestinations,
+					filesystemRoots: hook.filesystemRoots,
+				});
+				metadataValid =
+					metadataValid &&
+					hook.functionHook === compiled?.functionHook &&
+					hook.event === compiled?.event &&
+					hook.target === compiled?.target &&
+					hook.phase === compiled?.phase &&
+					hook.relativePath === compiled?.relativePath &&
+					hook.implementationHash === compiled?.implementationHash &&
+					(hook.functionHook !== true ||
+						(hook.capabilityHash?.toLowerCase() === functionHookGrantHash(grant).toLowerCase() &&
+							hook.capabilityHash?.toLowerCase() === compiled?.capabilityHash?.toLowerCase() &&
+							JSON.stringify(grant.capabilities) === JSON.stringify(compiled?.capabilities ?? []) &&
+							JSON.stringify(grant.networkDestinations) ===
+								JSON.stringify(compiled?.networkDestinations ?? []) &&
+							JSON.stringify(grant.filesystemRoots) === JSON.stringify(compiled?.filesystemRoots ?? [])));
+			} catch {
+				metadataValid = false;
+			}
+			const status: CustomizeFunctionHookSummary["status"] =
+				!metadataValid || observed?.status === "quarantined"
+					? "quarantined"
+					: !entry.enabled || entry.disabledSurfaceIds.includes(hook.extensionId)
+						? "disabled"
+						: hook.functionHook === true
+							? "blocked-isolate"
+							: "legacy-active";
+			return {
+				extensionId: hook.extensionId,
+				order: globalFunctionHookOrder++,
+				event: hook.event,
+				...(hook.target === undefined ? {} : { target: hook.target }),
+				...(hook.phase === undefined ? {} : { phase: hook.phase }),
+				scope: entry.scope,
+				plugin: entry.name,
+				relativePath: hook.relativePath,
+				status,
+				requestedCapabilities: [...(hook.capabilities ?? [])],
+				effectiveCapabilities: status === "legacy-active" ? [...(hook.capabilities ?? [])] : [],
+				attenuateDownstream: [],
+				networkDestinations: (hook.networkDestinations ?? []).map(destination => {
+					try {
+						const url = new URL(destination);
+						return url.protocol === "https:" && !url.username && !url.password ? url.origin : "[redacted]";
+					} catch {
+						return "[redacted]";
+					}
+				}),
+				filesystemRoots: [...(hook.filesystemRoots ?? [])],
+				...(hook.capabilityHash === undefined ? {} : { capabilityHash: hook.capabilityHash }),
+				...(hook.implementationHash === undefined ? {} : { implementationHash: hook.implementationHash }),
+				...(observed?.quarantineCode === undefined && metadataValid
+					? {}
+					: { quarantineCode: observed?.quarantineCode ?? "security_policy" }),
+				remediation:
+					status === "blocked-isolate"
+						? "Function Hook remains disabled until a capability-enforcing plugin isolate is available."
+						: status === "quarantined"
+							? "Reinstall the bundle and verify installed metadata and file hashes."
+							: status === "disabled"
+								? `Enable surface ${hook.extensionId} only after reviewing its declared policy.`
+								: "Legacy constrained hook executes under the existing trusted compatibility policy.",
+			};
+		});
 		const base: Omit<CustomizeDoctorItem, "status" | "reason" | "detail" | "remediation"> = {
 			name: entry.name,
 			kind: "plugin-bundle",
@@ -1153,6 +1279,7 @@ async function collectPluginBundles(cwd: string): Promise<CustomizeDoctorSurface
 			trust: TRUST_BY_KIND["plugin-bundle"],
 			restartRequired: true,
 			precedence: { priority: 0 },
+			functionHooks,
 		};
 		if (!entry.enabled) {
 			items.push(
@@ -1166,7 +1293,6 @@ async function collectPluginBundles(cwd: string): Promise<CustomizeDoctorSurface
 			);
 			continue;
 		}
-		const surfaces = observability.surfaces.filter(s => s.plugin === entry.name && s.scope === entry.scope);
 		const quarantined = surfaces.filter(s => s.status === "quarantined");
 		if (quarantined.length > 0) {
 			const codes = Array.from(new Set(quarantined.map(s => s.quarantineCode ?? "unknown"))).join(", ");
@@ -1574,6 +1700,23 @@ export function renderCustomizeDoctorText(report: CustomizeDoctorReport): string
 			lines.push(`    reason: ${item.reason} — ${item.detail}`);
 			lines.push(`    source: ${item.path}`);
 			if (item.quarantineCode) lines.push(`    quarantine code: ${item.quarantineCode}`);
+			for (const hook of item.functionHooks ?? []) {
+				lines.push(
+					`    function hook[${hook.order}]: ${hook.extensionId} event=${hook.event}${hook.target ? ` target=${hook.target}` : ""} status=${hook.status}`,
+				);
+				lines.push(`      provenance: scope=${hook.scope} plugin=${hook.plugin} path=${hook.relativePath}`);
+				lines.push(
+					`      grants: requested=${hook.requestedCapabilities.join(",") || "none"} effective=${hook.effectiveCapabilities.join(",") || "none"} attenuate=${hook.attenuateDownstream.join(",") || "none"}`,
+				);
+				if (hook.networkDestinations.length > 0)
+					lines.push(`      network destinations: ${hook.networkDestinations.join(",")}`);
+				if (hook.filesystemRoots.length > 0)
+					lines.push(`      filesystem roots: ${hook.filesystemRoots.join(",")}`);
+				if (hook.capabilityHash) lines.push(`      capability hash: ${hook.capabilityHash}`);
+				if (hook.implementationHash) lines.push(`      implementation hash: ${hook.implementationHash}`);
+				if (hook.quarantineCode) lines.push(`      quarantine code: ${hook.quarantineCode}`);
+				lines.push(`      remediation: ${hook.remediation}`);
+			}
 			for (const fix of item.remediation) lines.push(`    fix: ${fix}`);
 			lines.push(`    trust: ${item.trust}`);
 			lines.push(`    restart required: ${item.restartRequired ? "yes (new session)" : "no"}`);

package/src/cli.ts

@@ -10,6 +10,15 @@ import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gaja
 import { runFixtureReport } from "./cli/fixture-report";
 import { ROOT_LAUNCH_FLAGS } from "./cli/root-flags";
 import QuickLane from "./commands/quick-lane";
+import { runBashShellGuardian } from "./exec/bash-shell-guardian";
+import { runBashShellSupervisor } from "./exec/bash-shell-supervisor";
+import { runBashShellWorker } from "./exec/bash-shell-worker";
+import {
+	BASH_SHELL_RUNTIME_ARG,
+	BASH_SHELL_SUPERVISOR_ARG,
+	BASH_SHELL_WORKER_ARG,
+} from "./exec/bash-shell-worker-protocol";
+import { smokeTestIsolatedShell } from "./exec/isolated-shell";
 import { smokeTestTabWorker } from "./tools/browser/tab-worker-smoke";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
@@ -340,6 +349,7 @@ async function runSmokeTest(): Promise<void> {
 	const { runNativeSmokeTest } = await import("./cli/native-smoke");
 	await runNativeSmokeTest();
 	await smokeTestTabWorker();
+	await smokeTestIsolatedShell();
 	process.stdout.write("smoke-test: ok\n");
 }
 
@@ -392,6 +402,18 @@ export function routeRootArgv(argv: readonly string[]): string[] {
 
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export async function runCli(argv: string[]): Promise<void> {
+	if (argv.length === 1 && argv[0] === BASH_SHELL_WORKER_ARG) {
+		await runBashShellGuardian();
+		return;
+	}
+	if (argv.length === 1 && argv[0] === BASH_SHELL_SUPERVISOR_ARG) {
+		await runBashShellSupervisor();
+		return;
+	}
+	if (argv.length === 1 && argv[0] === BASH_SHELL_RUNTIME_ARG) {
+		await runBashShellWorker();
+		return;
+	}
 	// macOS malloc-env launch boundary. Re-exec once with a scrubbed environment
 	// BEFORE any fast path or subprocess spawn, so the startup env snapshot Bun hands
 	// to every child lane (Bun.spawn defaults, node:child_process, native PTY, tmux