@sayknow-cli/coding-agent 0.3.0 → 0.3.2

package/src/notifications/telegram-reference.ts

@@ -15,7 +15,14 @@
  */
 
 import * as fs from "node:fs";
-import { bold, buildButtonGrid, escapeHtml, TELEGRAM_PARSE_MODE, truncateTelegramHtml } from "./html-format";
+import {
+	bold,
+	buildCompactChoiceGrid,
+	escapeHtml,
+	numberedOptionList,
+	TELEGRAM_PARSE_MODE,
+	truncateTelegramHtml,
+} from "./html-format";
 import { renderThreadedFrame } from "./threaded-render";
 
 /** One inline-keyboard button. */
@@ -129,8 +136,9 @@ export function buildActionMessage(action: {
 	const text = `❓ ${bold(action.question ?? "Question")}`;
 	const options = action.options ?? [];
 	if (options.length === 0) return { text: truncateTelegramHtml(`${text}\n\n(reply with text)`) };
-	const inline_keyboard = buildButtonGrid(options, i => encodeCallbackData(action.id, i));
-	return { text: truncateTelegramHtml(text), inline_keyboard };
+	const body = `${text}\n\n${numberedOptionList(options)}`;
+	const inline_keyboard = buildCompactChoiceGrid(options, i => encodeCallbackData(action.id, i));
+	return { text: truncateTelegramHtml(body), inline_keyboard };
 }
 
 /** A protocol `reply` frame the client should send to the server. */
@@ -235,13 +243,23 @@ export function routeInboundUpdate(update: unknown, ctx: RouteInboundContext): R
 	return { kind: "ignore" };
 }
 
-/** Read `{url, token}` from an endpoint discovery file. */
-export function readEndpoint(path: string): { url: string; token: string } {
-	const raw = JSON.parse(fs.readFileSync(path, "utf8")) as { url?: unknown; token?: unknown };
+/** Read `{url, token, pid?, stale?}` from an endpoint discovery file. */
+export function readEndpoint(path: string): { url: string; token: string; pid?: number; stale?: boolean } {
+	const raw = JSON.parse(fs.readFileSync(path, "utf8")) as {
+		url?: unknown;
+		token?: unknown;
+		pid?: unknown;
+		stale?: unknown;
+	};
 	if (typeof raw.url !== "string" || typeof raw.token !== "string") {
 		throw new Error(`invalid endpoint file: ${path}`);
 	}
-	return { url: raw.url, token: raw.token };
+	return {
+		url: raw.url,
+		token: raw.token,
+		pid: typeof raw.pid === "number" ? raw.pid : undefined,
+		stale: raw.stale === true,
+	};
 }
 
 /** Options for {@link runTelegramReferenceClient}. */

package/src/notifications/threaded-inbound.ts

@@ -21,11 +21,30 @@ export interface InboundUpdate {
 	message?: {
 		message_id?: unknown;
 		text?: unknown;
+		caption?: unknown;
+		photo?: unknown;
+		document?: unknown;
+		video?: unknown;
+		audio?: unknown;
+		voice?: unknown;
+		animation?: unknown;
 		chat?: { id?: unknown };
 		message_thread_id?: unknown;
 	};
 }
 
+/** A downloadable media attachment referenced by an inbound message. */
+export interface InboundAttachment {
+	/** Telegram file_id to resolve via getFile. */
+	fileId: string;
+	/** Source media kind; "photo" is always an image. */
+	kind: "photo" | "document" | "video" | "audio" | "voice" | "animation";
+	/** MIME type when Telegram provides one. */
+	mime?: string;
+	/** Original file name when provided. */
+	fileName?: string;
+}
+
 /** Context for {@link decideThreadedInbound}. All lookups are injected. */
 export interface ThreadedInboundCtx {
 	/** The single paired chat id (string-compared). */
@@ -38,7 +57,15 @@ export interface ThreadedInboundCtx {
 
 /** Outcome of routing an inbound update. */
 export type ThreadedInboundDecision =
-	| { kind: "inject"; sessionId: string; text: string; updateId: number; threadId: string; messageId?: number }
+	| {
+			kind: "inject";
+			sessionId: string;
+			text: string;
+			updateId: number;
+			threadId: string;
+			messageId?: number;
+			attachment?: InboundAttachment;
+	  }
 	| { kind: "duplicate"; updateId: number }
 	| { kind: "ignore"; reason: string };
 
@@ -48,6 +75,29 @@ function asString(value: unknown): string | undefined {
 	return undefined;
 }
 
+function extractAttachment(message: NonNullable<InboundUpdate["message"]>): InboundAttachment | undefined {
+	if (Array.isArray(message.photo) && message.photo.length > 0) {
+		const photo = message.photo[message.photo.length - 1];
+		if (photo && typeof photo === "object" && "file_id" in photo && typeof photo.file_id === "string") {
+			return { fileId: photo.file_id, kind: "photo", mime: "image/jpeg" };
+		}
+	}
+
+	for (const kind of ["document", "video", "audio", "voice", "animation"] as const) {
+		const file = message[kind];
+		if (file && typeof file === "object" && "file_id" in file && typeof file.file_id === "string") {
+			return {
+				fileId: file.file_id,
+				kind,
+				mime: "mime_type" in file && typeof file.mime_type === "string" ? file.mime_type : undefined,
+				fileName: "file_name" in file && typeof file.file_name === "string" ? file.file_name : undefined,
+			};
+		}
+	}
+
+	return undefined;
+}
+
 /**
  * Decide whether an inbound update should inject a user turn. Fail-closed:
  * returns `ignore` (with a reason) or `duplicate` for anything that is not an
@@ -72,9 +122,15 @@ export function decideThreadedInbound(update: InboundUpdate, ctx: ThreadedInboun
 	const updateId = update.update_id;
 	if (ctx.isDuplicate(updateId)) return { kind: "duplicate", updateId };
 
-	const text = typeof message.text === "string" ? message.text.trim() : "";
-	if (!text) return { kind: "ignore", reason: "empty_text" };
+	const text =
+		typeof message.text === "string"
+			? message.text.trim()
+			: typeof message.caption === "string"
+				? message.caption.trim()
+				: "";
+	const attachment = extractAttachment(message);
+	if (!text && attachment === undefined) return { kind: "ignore", reason: "empty_text" };
 
 	const messageId = typeof message.message_id === "number" ? message.message_id : undefined;
-	return { kind: "inject", sessionId, text, updateId, threadId, messageId };
+	return { kind: "inject", sessionId, text, updateId, threadId, messageId, attachment };
 }

package/src/notifications/threaded-render.ts

@@ -15,15 +15,19 @@ import type { RateLimitLane } from "./rate-limit-pool";
 
 /** A Telegram send derived from a threaded frame (topic id is applied by the daemon). */
 export interface ThreadedSend {
-	method: "sendMessage" | "sendPhoto";
+	method: "sendMessage" | "sendPhoto" | "sendDocument";
 	/** Rate-limit lane for prioritisation/fairness. */
 	lane: RateLimitLane;
 	/** Message text (sendMessage) or photo caption (sendPhoto). */
 	text?: string;
 	/** Base64 image bytes for sendPhoto. */
 	photoBase64?: string;
+	/** Base64 file bytes for sendDocument. */
+	documentBase64?: string;
 	/** Image MIME type for sendPhoto. */
 	mime?: string;
+	/** Suggested document filename. */
+	fileName?: string;
 	/** Coalesce key for live edits (same key collapses to the latest). */
 	coalesceKey?: string;
 	/** True for the one-time identity header (the daemon pins it once). */
@@ -49,11 +53,12 @@ interface ThreadedFrame {
 	phase?: unknown;
 	text?: unknown;
 	messageRef?: unknown;
-	// image_attachment
+	// image_attachment / file_attachment
 	source?: unknown;
 	data?: unknown;
 	mime?: unknown;
 	caption?: unknown;
+	name?: unknown;
 	// config_update
 	verbosity?: unknown;
 	redact?: unknown;
@@ -141,6 +146,19 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 				text: finalizeTelegramHtml(caption === undefined ? undefined : escapeHtml(caption)),
 			};
 		}
+		case "file_attachment": {
+			const data = str(frame.data);
+			if (!data) return undefined;
+			const caption = str(frame.caption);
+			return {
+				method: "sendDocument",
+				lane: "finalized",
+				documentBase64: data,
+				mime: str(frame.mime),
+				fileName: str(frame.name),
+				text: finalizeTelegramHtml(caption === undefined ? undefined : escapeHtml(caption)),
+			};
+		}
 		case "config_update": {
 			const verbosity = str(frame.verbosity);
 			const redact = typeof frame.redact === "boolean" ? `redact ${frame.redact ? "on" : "off"}` : undefined;

package/src/notifications/topic-registry.ts

@@ -1,11 +1,11 @@
 /**
  * Per-session forum-topic registry for the threaded session surface.
  *
- * Each SKC session owns exactly one Telegram forum topic in the paired private
- * DM. The topic is created once (via `createForumTopic`) and REUSED on resume,
- * keyed by session id, so a resumed session streams back into its existing
- * thread/history. The registry also tracks whether the one-time identity header
- * has already been pinned, so it is sent exactly once per topic even across
+ * Each SKC session owns one active Telegram forum topic in the paired private
+ * DM. The topic is created via `createForumTopic`, reused while the session
+ * remains active, and removed from the registry when the daemon deletes it on
+ * shutdown. The registry also tracks whether the one-time identity header has
+ * already been pinned, so it is sent exactly once per active topic, even across
  * reconnects.
  *
  * State is a plain serialisable map persisted beside the daemon state files;
@@ -65,20 +65,25 @@ export class TopicRegistry {
 		return this.byTopic.get(topicId);
 	}
 
+	/** All session ids with a persisted topic record. */
+	sessionIds(): string[] {
+		return [...this.topics.keys()];
+	}
+
 	/** The existing topic record for a session, if any. */
 	get(sessionId: string): TopicRecord | undefined {
 		return this.topics.get(sessionId);
 	}
 
 	/**
-	 * Return the existing topic for `sessionId`, or create one via `create`
-	 * (called only on first use). Reuse-on-resume: an existing record is
-	 * returned without invoking `create`.
+	 * Return the existing active topic for `sessionId`, or create one via
+	 * `create` (called only on first use).
 	 */
 	async getOrCreateTopic(
 		sessionId: string,
 		create: () => Promise<string>,
 		now: () => number = Date.now,
+		name?: string,
 	): Promise<TopicRecord> {
 		const existing = this.topics.get(sessionId);
 		if (existing) return existing;
@@ -90,7 +95,7 @@ export class TopicRegistry {
 		if (pending) return pending;
 		const promise = (async () => {
 			const topicId = await create();
-			const record: TopicRecord = { topicId, identitySent: false, createdAt: now() };
+			const record: TopicRecord = { topicId, name, identitySent: false, createdAt: now() };
 			this.topics.set(sessionId, record);
 			this.byTopic.set(topicId, sessionId);
 			return record;
@@ -126,6 +131,15 @@ export class TopicRegistry {
 		return true;
 	}
 
+	/** Remove a session topic record after Telegram deletes the topic. */
+	delete(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record) return false;
+		this.topics.delete(sessionId);
+		this.byTopic.delete(record.topicId);
+		return true;
+	}
+
 	/** Serialise for atomic persistence beside the daemon state. */
 	serialize(): TopicRegistryState {
 		return { topics: Object.fromEntries(this.topics) };

package/src/prompts/agents/executor.md

@@ -36,8 +36,8 @@ This mode activates only when the assignment explicitly labels Executor as Ultra
 
 When active:
 - Start from the approved plan/spec/acceptance criteria, then user-facing contracts, then implementation code only as supporting evidence. Treat plan/code mismatches as blockers.
-- Exercise the real user-facing invocation rather than inspecting internals alone. Live artifacts must be runtime-valid: GUI/web needs a real automation transcript plus non-uniform screenshot; CLI needs executed argv-only replay; native/desktop/TUI needs a real screenshot, PTY capture with control codes, or app-automation transcript. `inlineEvidence` is supplemental only and is never sole proof for live surfaces.
-- For CLI evidence, emit argv-only replay JSON with `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, and `command` as a string array. Use only allowlisted deterministic executables/arguments, or mark unsafe/non-deterministic commands with audited `replayExempt` metadata plus a valid structural fallback artifact. `replayExempt` must use exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs`; allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
+- Exercise the real user-facing invocation rather than inspecting internals alone. Live artifacts must be runtime-valid: GUI/web needs a real automation transcript plus non-uniform screenshot; CLI needs executed argv-only replay; native/desktop/TUI needs a real screenshot, PTY capture with control codes, or app-automation transcript. API/package surfaces need a real artifact file or typed receipt whose artifact `kind` contains `api`, `package`, `consumer`, `black-box`, or `test-report`; good kinds include `api-package-test-report`, `package-consumer-report`, and `black-box-api-receipt`. Algorithm/math surfaces need a real artifact file or typed receipt whose artifact `kind` contains `property`, `boundary`, `edge`, `adversarial`, `failure`, `math`, `algorithm`, or `test-report`; good kinds include `property-test-report` and `algorithm-boundary-report`. `inlineEvidence` is supplemental only and is never sole proof for live surfaces.
+- For CLI evidence, emit argv-only replay JSON with `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, and `command` as a string array. Use only allowlisted deterministic executables/arguments: `bun --version`, `node --version`, deterministic `bun/node -e "console.log(...)"`, `npm|pnpm|yarn --version`, `npm|pnpm|yarn list`, read-only `git status|rev-parse|merge-base|diff|show|log` with safe args, and `skc read|status`. Mark any other command with audited `replayExempt` metadata plus a valid structural fallback artifact. `replayExempt` must use exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs`; allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
 - Native/TUI evidence must be structural, not prose-only: screenshot, app transcript, or PTY artifact with terminal control codes.
 - Do not call the `ask` tool while an Ultragoal run is active; record unresolved decisions with `skc ultragoal record-review-blockers`.
 - Try to break the work with adversarial cases, not just happy-path confirmations.

package/src/runtime-mcp/transports/stdio.ts

@@ -24,6 +24,38 @@ import { toJsonRpcError } from "../../runtime-mcp/types";
  */
 const CLOSE_WAIT_MS = 1_000;
 
+/**
+ * Build a minimal environment for a no-inherit stdio MCP child. Only OS-level
+ * keys needed to locate/run an interpreter (PATH, HOME, temp, locale, and the
+ * Windows system essentials) are copied from the host; everything else
+ * (API keys, tokens, secrets) is withheld. Explicit `env` overrides win.
+ */
+function buildMinimalStdioEnv(explicit?: Record<string, string>): Record<string, string> {
+	const allow = [
+		"PATH",
+		"HOME",
+		"TMPDIR",
+		"TEMP",
+		"TMP",
+		"LANG",
+		"LC_ALL",
+		"LC_CTYPE",
+		"SHELL",
+		"USER",
+		"SystemRoot",
+		"SYSTEMROOT",
+		"PATHEXT",
+		"COMSPEC",
+		"WINDIR",
+	];
+	const env: Record<string, string> = {};
+	for (const key of allow) {
+		const value = Bun.env[key];
+		if (typeof value === "string") env[key] = value;
+	}
+	return { ...env, ...explicit };
+}
+
 export class StdioTransport implements MCPTransport {
 	#process: OwnedProcess | null = null;
 	#pendingRequests = new Map<
@@ -63,10 +95,12 @@ export class StdioTransport implements MCPTransport {
 		if (this.#connected) return;
 
 		const args = this.config.args ?? [];
-		const env = {
-			...Bun.env,
-			...this.config.env,
-		};
+		const env = this.config.noInheritEnv
+			? buildMinimalStdioEnv(this.config.env)
+			: {
+					...Bun.env,
+					...this.config.env,
+				};
 
 		this.#process = spawnOwnedProcess([this.config.command, ...args], {
 			cwd: this.config.cwd ?? getProjectDir(),

package/src/runtime-mcp/types.ts

@@ -81,6 +81,13 @@ export interface MCPStdioServerConfig extends MCPServerConfigBase {
 	command: string;
 	args?: string[];
 	env?: Record<string, string>;
+	/**
+	 * When true, the child process is NOT given the host environment. Only a
+	 * minimal OS allowlist (PATH/HOME/temp/locale) plus any explicit `env` keys
+	 * are passed. Used for third-party plugin-bundle MCP servers so they cannot
+	 * read host secrets from the inherited environment.
+	 */
+	noInheritEnv?: boolean;
 	cwd?: string;
 }
 

package/src/sdk.ts

@@ -73,7 +73,13 @@ import {
 	wrapRegisteredTools,
 } from "./extensibility/extensions";
 import { ExtensionRuntime } from "./extensibility/extensions/loader";
+import { type ConstrainedPluginHook, loadConstrainedPluginHooks } from "./extensibility/skc-plugins/constrained-hooks";
 import { resolveCurrentPhaseForParent } from "./extensibility/skc-plugins/injection";
+import {
+	buildPluginMcpConfigs,
+	loadAlwaysOnPluginTools,
+	renderAlwaysOnSystemAppendices,
+} from "./extensibility/skc-plugins/runtime-adapters";
 import { loadActiveSubskillTools } from "./extensibility/skc-plugins/tools";
 import { loadSkills, type Skill, type SkillWarning, setActiveSkills } from "./extensibility/skills";
 import type { FileSlashCommand } from "./extensibility/slash-commands";
@@ -748,6 +754,27 @@ function createCustomToolsExtension(tools: CustomTool[]): ExtensionFactory {
 	};
 }
 
+export function createPluginHooksExtension(hooks: ConstrainedPluginHook[]): ExtensionFactory {
+	return api => {
+		for (const hook of hooks) {
+			// Constrained plugin hooks register exactly their declared event handler
+			// through the standard extension API; the loader already denied every
+			// session-mutation/command/exec capability at load time. At execution we
+			// additionally enforce the declared `target`: a tool-scoped hook only
+			// fires for its declared tool, never for arbitrary tool events.
+			const target = hook.target;
+			const handler = target
+				? (event: { toolName?: string; tool?: { name?: string }; name?: string }, ...rest: unknown[]) => {
+						const toolName = event?.toolName ?? event?.tool?.name ?? event?.name;
+						if (toolName !== target) return undefined;
+						return (hook.handler as (...a: unknown[]) => unknown)(event, ...rest);
+					}
+				: hook.handler;
+			(api.on as (event: string, handler: (...args: unknown[]) => unknown) => void)(hook.event, handler);
+		}
+	};
+}
+
 // Factory
 
 /**
@@ -1233,6 +1260,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			get model() {
 				return agent?.state.model ?? model;
 			},
+			get serviceTier() {
+				// Live parent service-tier intent (e.g. runtime `/fast on|off`), inherited
+				// by `inherit` subagents. Only fall back to the startup tier when there is
+				// no live agent yet — never `??`, or an intentional `/fast off`
+				// (serviceTier === undefined) would be resurrected to the startup value.
+				return agent ? agent.serviceTier : initialServiceTier;
+			},
 			getAgentId: () => resolvedAgentId,
 			bashAllowedPrefixes: options.bashAllowedPrefixes,
 			bashRestrictionProfile: options.bashRestrictionProfile,
@@ -1327,14 +1361,13 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		// MCP runtime discovery is quarantined for the SKC surface. Keep an
 		// explicitly supplied manager only for legacy in-process callers that own
-		// lifecycle themselves; never discover project/user MCP configs here.
-		const mcpManager: MCPManager | undefined = options.mcpManager;
+		// lifecycle themselves; never discover project/user MCP configs here. The
+		// owned manager for always-on plugin-bundle MCP servers is created further
+		// below, after `customTools` is populated, so its tools can be surfaced as
+		// always-on tools per the plugin product contract.
+		let mcpManager: MCPManager | undefined = options.mcpManager;
+		let ownsMcpManager = false;
 		const customTools: CustomTool[] = [];
-		// Only top-level sessions own the global MCPManager. Subagents already
-		// receive the parent's manager via `options.mcpManager`, and reassigning
-		// the singleton to the same value is a no-op \u2014 keep the gate explicit
-		// to mirror the AsyncJobManager ownership rule.
-		if (mcpManager && !options.parentTaskPrefix) MCPManager.setInstance(mcpManager);
 
 		// Add image tools when the active model or configured image providers can generate images.
 		const imageGenTools = await logger.time("getImageGenTools", () => getImageGenTools(modelRegistry, model));
@@ -1388,6 +1421,84 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 		}
 
+		// Always-on SKC plugin bundle tools (validated registry surfaces). This is
+		// additive and a no-op when no plugins are installed for the cwd. Surfaces
+		// are hash-verified and collision-checked; declared names are authoritative.
+		try {
+			const pluginToolResult = await loadAlwaysOnPluginTools({
+				cwd,
+				reservedToolNames: [...getReservedSubskillToolNames(), ...customTools.map(tool => tool.name)],
+			});
+			if (pluginToolResult.tools.length > 0) customTools.push(...pluginToolResult.tools);
+			for (const q of pluginToolResult.quarantine) {
+				logger.warn("Quarantined SKC plugin surface", { plugin: q.plugin, surface: q.surfaceId, code: q.code });
+			}
+		} catch (error) {
+			logger.warn("Failed to load always-on SKC plugin tools", { error });
+		}
+
+		// Always-on SKC plugin-bundle MCP servers. Top-level sessions own a manager
+		// and connect the validated servers; subagents inherit the parent's manager
+		// via options.mcpManager and never spawn their own (prevents duplicate
+		// processes and leaks). Per the plugin product contract, connected MCP tools
+		// are surfaced as always-on tools rather than gated behind MCP selection.
+		if (!mcpManager && !options.parentTaskPrefix) {
+			try {
+				const { configs, quarantine } = await buildPluginMcpConfigs({ cwd });
+				for (const q of quarantine) {
+					logger.warn("Quarantined SKC plugin MCP", { plugin: q.plugin, surface: q.surfaceId, code: q.code });
+				}
+				if (Object.keys(configs).length > 0) {
+					const owned = new MCPManager(cwd);
+					try {
+						const sources = Object.fromEntries(
+							Object.keys(configs).map(name => [
+								name,
+								{ provider: "skc-plugins", providerName: "SKC plugin bundle", level: "project" as const },
+							]),
+						);
+						const result = await owned.connectServers(configs, sources as never);
+						for (const [server, err] of result.errors) {
+							logger.warn("SKC plugin MCP connect failed", { path: `mcp:${server}`, error: err });
+						}
+						if (result.connectedServers.length > 0) {
+							mcpManager = owned;
+							ownsMcpManager = true;
+							customTools.push(...(result.tools as CustomTool[]));
+						} else {
+							await owned.disconnectAll().catch(() => {});
+						}
+					} catch (error) {
+						// Avoid leaking partially-started server processes on failure.
+						await owned.disconnectAll().catch(() => {});
+						throw error;
+					}
+				}
+			} catch (error) {
+				logger.warn("Failed to wire SKC plugin MCP servers", { error });
+			}
+		} else if (options.parentTaskPrefix) {
+			// Subagent: inherit the parent's always-on plugin MCP tools WITHOUT
+			// owning the manager (no connect, no callbacks, no disposal). The
+			// top-level session installed its manager as the process-global
+			// instance; reading getTools() surfaces the same always-on tools so the
+			// product decision holds for subagent sessions too.
+			const inherited = mcpManager ?? MCPManager.instance();
+			if (inherited) {
+				try {
+					const inheritedTools = inherited.getTools();
+					if (inheritedTools.length > 0) customTools.push(...(inheritedTools as CustomTool[]));
+				} catch (error) {
+					logger.warn("Failed to inherit plugin MCP tools in subagent", { error });
+				}
+			}
+		}
+		// Only top-level sessions own the global MCPManager. Subagents already
+		// receive the parent's manager via options.mcpManager; reassigning the
+		// singleton to the same value is a no-op. Keep the gate explicit to mirror
+		// the AsyncJobManager ownership rule.
+		if (mcpManager && !options.parentTaskPrefix) MCPManager.setInstance(mcpManager);
+
 		// Custom tool and extension discovery is quarantined from the public SKC utility surface.
 		// Explicit SDK extension factories are still honored; callers use them to
 		// register in-process tools/providers without enabling filesystem discovery.
@@ -1395,6 +1506,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		if (customTools.length > 0) {
 			inlineExtensions.push(createCustomToolsExtension(customTools));
 		}
+
+		// Always-on constrained plugin hooks (validated registry surfaces). Additive
+		// and a no-op without installed plugins; the loader denies all dangerous APIs.
+		try {
+			const pluginHookResult = await loadConstrainedPluginHooks({ cwd });
+			if (pluginHookResult.hooks.length > 0) {
+				inlineExtensions.push(createPluginHooksExtension(pluginHookResult.hooks));
+			}
+			for (const q of pluginHookResult.quarantine) {
+				logger.warn("Quarantined SKC plugin hook", { plugin: q.plugin, surface: q.surfaceId, code: q.code });
+			}
+		} catch (error) {
+			logger.warn("Failed to load constrained SKC plugin hooks", { error });
+		}
 		let notificationCfg: NotificationConfig | undefined;
 		try {
 			notificationCfg = getNotificationConfig(Settings.instance);
@@ -1693,6 +1818,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				}
 				appendPrompt = parts.join("\n\n");
 			}
+			let pluginSystemAppendices = "";
+			try {
+				pluginSystemAppendices = await renderAlwaysOnSystemAppendices({ cwd });
+			} catch (error) {
+				logger.warn("Failed to render SKC plugin system appendices", { error });
+			}
 			const defaultPrompt = await buildSystemPromptInternal({
 				cwd,
 				skills,
@@ -1703,6 +1834,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				alwaysApplyRules,
 				skillsSettings: settings.getGroup("skills"),
 				appendSystemPrompt: appendPrompt,
+				pluginAppendices: pluginSystemAppendices,
 				repeatToolDescriptions,
 				intentField,
 				mcpDiscoveryMode: false,
@@ -2059,6 +2191,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			// AsyncJobManager on teardown; subagents inherit the parent's and
 			// **MUST NOT** tear it down.
 			ownedAsyncJobManager: asyncJobManager,
+			// Only the owned plugin-bundle MCP manager is torn down on dispose;
+			// subagents/callers that merely observe the global must not (see
+			// AgentSession.dispose).
+			ownedMcpManager: ownsMcpManager ? mcpManager : undefined,
 			scopedModels: options.scopedModels,
 			promptTemplates,
 			slashCommands,
@@ -2223,9 +2359,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		// Wire MCP manager callbacks to session for reactive tool updates.
 		// Skip when reusing a parent's manager — the parent owns the callbacks.
 		if (mcpManager && !options.mcpManager) {
-			mcpManager.setOnToolsChanged(tools => {
-				void session.refreshMCPTools(tools);
-			});
+			// The owned plugin-bundle manager surfaces its tools as always-on custom
+			// tools (registered above), so it must NOT drive refreshMCPTools — that
+			// path strips MCP bridge tools and re-gates them behind MCP selection,
+			// which would deactivate the always-on plugin tools. Reactive tool
+			// updates remain wired only for externally supplied managers.
+			// The owned manager is disconnected by AgentSession.dispose via
+			// ownedMcpManager; only externally supplied managers wire reactive
+			// refreshMCPTools (the owned always-on path must not, or it would
+			// deactivate the plugin tools).
+			if (!ownsMcpManager) {
+				mcpManager.setOnToolsChanged(tools => {
+					void session.refreshMCPTools(tools);
+				});
+			}
 			// Wire prompt refresh → rebuild MCP prompt slash commands
 			mcpManager.setOnPromptsChanged(serverName => {
 				const promptCommands = buildMCPPromptCommands(mcpManager);