@namzu/sdk 45.1.0 → 48.0.0

package/src/plugin/lifecycle.ts

@@ -1,22 +1,26 @@
 import { pathToFileURL } from 'node:url'
 import type { ConfigRegistry } from '../config/registry.js'
-import { mcpToolToToolDefinition } from '../connector/mcp/adapter.js'
 import { MCPClient } from '../connector/mcp/client.js'
 import { MCPToolDiscovery } from '../connector/mcp/discovery.js'
 import type { MCPToolDiscoveryOptions } from '../connector/mcp/discovery.js'
+import { mcpToolset } from '../connector/mcp/mcp-toolset.js'
 import type { MCPToolPolicy } from '../connector/mcp/policy.js'
-import { mcpPromptToToolDefinition } from '../connector/mcp/prompt-adapter.js'
-import { MCPReconnectOptionsSchema, MCPReconnectSupervisor } from '../connector/mcp/reconnect.js'
+import { MCPReconnectOptionsSchema } from '../connector/mcp/reconnect.js'
 import {
 	DEFAULT_HOOK_PRIORITY,
 	HOOK_TIMEOUT_MS,
 	PLUGIN_NAMESPACE_SEPARATOR,
 } from '../constants/plugin/index.js'
 import { GENAI } from '../constants/telemetry/index.js'
+import { PromptContributionRegistry } from '../prompt/contributions.js'
+import type { PromptContribution } from '../prompt/contributions.js'
 import type { PluginRegistry } from '../registry/plugin/index.js'
 import { loadSkill } from '../skills/loader.js'
 import type { SkillRegistry } from '../skills/registry.js'
 import { resolveWithinReal } from '../tools/paths.js'
+import { wrapUntrusted } from '../tools/untrusted-envelope.js'
+import type { Toolset } from '../toolsets/types.js'
+import { deferred, prefixed } from '../toolsets/wrappers.js'
 import type { PluginId } from '../types/ids/index.js'
 import type {
 	PluginDefinition,
@@ -31,28 +35,22 @@ import type {
 } from '../types/plugin/index.js'
 import { assertPluginHookEvent } from '../types/plugin/index.js'
 import type { SessionEvent } from '../types/session/index.js'
-import type { ToolDefinition, ToolRegistryContract } from '../types/tool/index.js'
+import type { ToolDefinition } from '../types/tool/index.js'
 import { toErrorMessage } from '../utils/error.js'
 import { generatePluginId } from '../utils/id.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
+import { type DefinedPlugin, definePlugin } from './define.js'
 import { assertEnableable, loadPluginManifest } from './loader.js'
 
 interface PluginContributionRecord {
 	toolNames: string[]
 	mcpClients: MCPClient[]
+	mcpToolsets: Toolset[]
+	mcpUnsubscribers: Array<() => void>
+	mcpNamesBySource: Map<string, Set<string>>
 	/** Namespaced skill names, so rollback and disable can take them back. */
 	skillNames: string[]
-	/**
-	 * One per client, held so teardown can stop them.
-	 *
-	 * A supervisor still attached when `disconnect()` runs reads the teardown
-	 * as a fault and reconnects what was just closed — the lifecycle event
-	 * cannot tell a deliberate disconnect from a dropped transport. Keeping
-	 * them here is what makes the required stop-then-disconnect ordering
-	 * possible at all.
-	 */
-	mcpSupervisors: MCPReconnectSupervisor[]
 }
 
 interface PluginAdmission {
@@ -61,6 +59,38 @@ interface PluginAdmission {
 	readonly scope: PluginScope
 	readonly rootDir: string
 	readonly installedAt: number
+	readonly inCode?: DefinedPlugin
+}
+
+/** Dynamic imports bypass ToolDefinition's TypeScript contract. */
+function assertPluginTool(
+	value: unknown,
+	pluginName: string,
+	origin: string,
+	index: number,
+): asserts value is ToolDefinition {
+	const tool = value && typeof value === 'object' ? (value as Record<string, unknown>) : null
+	const label = `Plugin "${pluginName}" tool #${index} from ${origin}`
+	if (
+		!tool ||
+		typeof tool.name !== 'string' ||
+		tool.name.length === 0 ||
+		typeof tool.description !== 'string' ||
+		typeof tool.execute !== 'function'
+	) {
+		throw new Error(`${label} must define name, description and execute.`)
+	}
+	const schema = tool.inputSchema
+	if (
+		!schema ||
+		typeof schema !== 'object' ||
+		typeof (schema as { safeParse?: unknown }).safeParse !== 'function' ||
+		(!tool.modelInputSchema && typeof (schema as { _def?: unknown })._def !== 'object')
+	) {
+		throw new Error(
+			`${label} must define inputSchema as a Zod schema, or as a compatible parser with modelInputSchema.`,
+		)
+	}
 }
 
 function immutableManifest(manifest: PluginDefinition['manifest']): PluginDefinition['manifest'] {
@@ -77,6 +107,7 @@ function immutableManifest(manifest: PluginDefinition['manifest']): PluginDefini
 		version: manifest.version,
 		description: manifest.description,
 		...(manifest.author !== undefined ? { author: manifest.author } : {}),
+		...(manifest.instructions !== undefined ? { instructions: manifest.instructions } : {}),
 		...(manifest.tools ? { tools: Object.freeze([...manifest.tools]) } : {}),
 		...(manifest.skills ? { skills: Object.freeze([...manifest.skills]) } : {}),
 		...(manifest.hooks ? { hooks: Object.freeze([...manifest.hooks]) } : {}),
@@ -88,7 +119,6 @@ function immutableManifest(manifest: PluginDefinition['manifest']): PluginDefini
 
 export interface PluginLifecycleManagerConfig {
 	pluginRegistry: PluginRegistry
-	toolRegistry: ToolRegistryContract
 	/**
 	 * Filesystem authorities for each plugin scope.
 	 *
@@ -151,13 +181,19 @@ export interface PluginLifecycleManagerConfig {
 
 export class PluginLifecycleManager {
 	private pluginRegistry: PluginRegistry
-	private toolRegistry: ToolRegistryContract
+	/** Each installed plugin owns its own file source and one source per MCP server. */
+	private readonly pluginFileTools = new Map<string, ToolDefinition>()
+	private readonly pluginMcpTools = new Map<string, ToolDefinition>()
+	private readonly mcpOwnerByName = new Map<string, string>()
+	private readonly toolsetsByPlugin = new Map<PluginId, readonly Toolset[]>()
+	private readonly instructions = new PromptContributionRegistry()
+	private readonly toolsetChangeListeners = new Set<() => void>()
 	private listeners: PluginEventListener[] = []
 	private hookHandlers: Map<
 		PluginHookEvent,
 		Array<{
 			pluginId: PluginId
-			handler: PluginHookDefinition['handler']
+			handler: (context: PluginHookContext) => Promise<PluginHookResult>
 			priority: number
 			seq: number
 		}>
@@ -184,16 +220,19 @@ export class PluginLifecycleManager {
 	 * reads.
 	 */
 	private mcpDiscovery: MCPToolDiscovery
+	private readonly mcpToolPolicies?: Readonly<Record<string, MCPToolPolicy>>
+	private readonly onMCPToolDrift?: MCPToolDiscoveryOptions['onDrift']
 
 	private readonly skillRegistry: SkillRegistry | undefined
 
 	constructor(config: PluginLifecycleManagerConfig) {
 		this.pluginRegistry = config.pluginRegistry
-		this.toolRegistry = config.toolRegistry
 		this.skillRegistry = config.skillRegistry
 		this.scopeRoots = Object.freeze({ ...config.scopeRoots })
 		this.hookTimeoutMs = config.hookTimeoutMs ?? HOOK_TIMEOUT_MS
 		this.configRegistry = config.configRegistry
+		this.mcpToolPolicies = config.mcpToolPolicies
+		this.onMCPToolDrift = config.onMCPToolDrift
 		this.log = config.log.child({ [SCOPE_ATTRIBUTE]: 'plugin/lifecycle' })
 		this.mcpDiscovery = new MCPToolDiscovery([], {
 			...(config.mcpToolPolicies ? { policies: config.mcpToolPolicies } : {}),
@@ -202,6 +241,81 @@ export class PluginLifecycleManager {
 		})
 	}
 
+	/** Stable entries created at install, before a host composes its ToolManager. */
+	get toolsets(): readonly Toolset[] {
+		return [...this.toolsetsByPlugin.values()].flat()
+	}
+
+	/** Plugin-authored request context from enabled plugins. */
+	get promptContributions(): readonly PromptContribution[] {
+		return this.instructions.list()
+	}
+
+	private registerToolsets(admission: PluginAdmission): void {
+		if (this.toolsetsByPlugin.has(admission.id)) return
+		const pluginName = admission.manifest.name
+		const onChange = (listener: () => void) => {
+			this.toolsetChangeListeners.add(listener)
+			return () => this.toolsetChangeListeners.delete(listener)
+		}
+		const fileTools = deferred({
+			source: {
+				id: `plugin:${pluginName}`,
+				kind: 'plugin' as const,
+				name: pluginName,
+			},
+			tools: () =>
+				[...this.pluginFileTools.values()].filter((tool) =>
+					tool.name.startsWith(`${pluginName}${PLUGIN_NAMESPACE_SEPARATOR}`),
+				),
+			onChange,
+		})
+		const mcpTools = (admission.manifest.mcpServers ?? []).map((server) =>
+			deferred({
+				source: {
+					id: `plugin:${pluginName}/mcp:${server.name}`,
+					kind: 'mcp_server' as const,
+					name: server.name,
+					mcpServer: { name: server.name, readOnlyHintTrusted: false },
+				},
+				tools: () =>
+					[...this.pluginMcpTools.values()].filter(
+						(tool) =>
+							this.mcpOwnerByName.get(tool.name) === `plugin:${pluginName}/mcp:${server.name}`,
+					),
+				onChange,
+			}),
+		)
+		this.toolsetsByPlugin.set(admission.id, [fileTools, ...mcpTools])
+	}
+
+	private notifyToolsetChange(): void {
+		for (const listener of this.toolsetChangeListeners) listener()
+	}
+
+	/** A file-declared plugin tool. Always deferred, like every other tool this manager contributes. */
+	private addFileTool(tool: ToolDefinition): void {
+		this.pluginFileTools.set(tool.name, tool)
+		this.notifyToolsetChange()
+	}
+
+	/** An MCP-discovered tool or a prompt adapted to one. */
+	private addMcpTool(tool: ToolDefinition, sourceId: string): void {
+		this.pluginMcpTools.set(tool.name, tool)
+		this.mcpOwnerByName.set(tool.name, sourceId)
+		this.notifyToolsetChange()
+	}
+
+	/** Reverses whichever of the two maps above actually holds `name`; a name in neither is a no-op. */
+	private removeContributedTool(name: string): void {
+		const removedFile = this.pluginFileTools.delete(name)
+		const removedMcp = this.pluginMcpTools.delete(name)
+		this.mcpOwnerByName.delete(name)
+		if (removedFile || removedMcp) {
+			this.notifyToolsetChange()
+		}
+	}
+
 	/**
 	 * Attach a hook without installing a plugin from disk.
 	 *
@@ -272,6 +386,7 @@ export class PluginLifecycleManager {
 
 		this.pluginRegistry.register(definition)
 		this.pluginAdmissions.set(pluginId, admission)
+		this.registerToolsets(admission)
 
 		this.emit({
 			type: 'plugin_installed',
@@ -290,6 +405,42 @@ export class PluginLifecycleManager {
 		return definition
 	}
 
+	/** Register a host-authored plugin without reading a manifest or importing modules. */
+	installDefined(plugin: DefinedPlugin, scope: PluginScope = 'project'): PluginDefinition {
+		const defined = definePlugin(plugin)
+		const existing = this.pluginRegistry.findByName(defined.name)
+		if (existing) {
+			throw new Error(`Plugin "${defined.name}" is already installed (id: ${existing.id})`)
+		}
+		const pluginId = generatePluginId()
+		const manifest = immutableManifest({
+			name: defined.name,
+			version: defined.version,
+			description: defined.description,
+			...(defined.instructions !== undefined ? { instructions: defined.instructions } : {}),
+			mcpServers: defined.mcpServers,
+		})
+		const admission: PluginAdmission = Object.freeze({
+			id: pluginId,
+			manifest,
+			scope,
+			rootDir: this.scopeRoots[scope],
+			installedAt: Date.now(),
+			inCode: defined,
+		})
+		const definition = this.definitionFrom(admission, 'installed')
+		this.pluginRegistry.register(definition)
+		this.pluginAdmissions.set(pluginId, admission)
+		this.registerToolsets(admission)
+		this.emit({
+			type: 'plugin_installed',
+			pluginId,
+			name: defined.name,
+			scope,
+		})
+		return definition
+	}
+
 	private definitionFrom(
 		admission: PluginAdmission,
 		status: PluginDefinition['status'],
@@ -354,6 +505,7 @@ export class PluginLifecycleManager {
 			try {
 				admission = await this.readLegacyAdmission(plugin)
 				this.pluginAdmissions.set(pluginId, admission)
+				this.registerToolsets(admission)
 			} catch (error) {
 				this.pluginRegistry.register({
 					...plugin,
@@ -374,7 +526,9 @@ export class PluginLifecycleManager {
 		// `installed`: a status that says the plugin is fine while it can
 		// never enable is how the next reader gets misled.
 		try {
-			assertEnableable(manifest, { skillsSupported: Boolean(this.skillRegistry) })
+			assertEnableable(manifest, {
+				skillsSupported: Boolean(this.skillRegistry),
+			})
 		} catch (err) {
 			this.pluginRegistry.register({
 				...this.definitionFrom(admission, 'error'),
@@ -386,13 +540,22 @@ export class PluginLifecycleManager {
 		const contributions: PluginContributionRecord = {
 			toolNames: [],
 			mcpClients: [],
+			mcpToolsets: [],
+			mcpUnsubscribers: [],
+			mcpNamesBySource: new Map(),
 			skillNames: [],
-			mcpSupervisors: [],
 		}
 
 		try {
-			// Load tools
-			if (manifest.tools && manifest.tools.length > 0) {
+			// Host-authored definitions have no file path to resolve or module to import.
+			if (admission.inCode) {
+				for (const [index, tool] of admission.inCode.tools.entries()) {
+					assertPluginTool(tool, manifest.name, 'the in-code declaration', index + 1)
+					const namespacedName = manifest.name + PLUGIN_NAMESPACE_SEPARATOR + tool.name
+					this.addFileTool({ ...tool, name: namespacedName })
+					contributions.toolNames.push(namespacedName)
+				}
+			} else if (manifest.tools && manifest.tools.length > 0) {
 				for (const toolPath of manifest.tools) {
 					const absolutePath = await resolveWithinReal(admission.rootDir, toolPath)
 					const fileUrl = pathToFileURL(absolutePath).href
@@ -404,10 +567,14 @@ export class PluginLifecycleManager {
 						)
 					}
 
-					for (const tool of mod.tools) {
+					for (const [index, tool] of mod.tools.entries()) {
+						assertPluginTool(tool, manifest.name, `"${toolPath}"`, index + 1)
 						const namespacedName = manifest.name + PLUGIN_NAMESPACE_SEPARATOR + tool.name
-						const namespacedTool: ToolDefinition = { ...tool, name: namespacedName }
-						this.toolRegistry.register(namespacedTool, 'deferred')
+						const namespacedTool: ToolDefinition = {
+							...tool,
+							name: namespacedName,
+						}
+						this.addFileTool(namespacedTool)
 						contributions.toolNames.push(namespacedName)
 					}
 				}
@@ -441,11 +608,15 @@ export class PluginLifecycleManager {
 			}
 
 			// Load hooks
-			if (manifest.hooks && manifest.hooks.length > 0) {
+			if (admission.inCode) {
+				for (const hook of admission.inCode.hooks) this.registerHook(pluginId, hook)
+			} else if (manifest.hooks && manifest.hooks.length > 0) {
 				for (const hookPath of manifest.hooks) {
 					const absolutePath = await resolveWithinReal(admission.rootDir, hookPath)
 					const fileUrl = pathToFileURL(absolutePath).href
-					const mod = (await import(fileUrl)) as { hooks?: PluginHookDefinition[] }
+					const mod = (await import(fileUrl)) as {
+						hooks?: PluginHookDefinition[]
+					}
 
 					if (!mod.hooks || !Array.isArray(mod.hooks)) {
 						throw new Error(
@@ -471,6 +642,24 @@ export class PluginLifecycleManager {
 		}
 
 		this.pluginContributions.set(pluginId, contributions)
+		const pluginInstructions = manifest.instructions
+		if (pluginInstructions?.trim()) {
+			this.instructions.register({
+				id: `plugin:${manifest.name}:instructions`,
+				placement: 'context',
+				render: () => {
+					if (!this.pluginContributions.has(pluginId)) return null
+					return wrapUntrusted(
+						{
+							kind: 'plugin-instructions',
+							attributes: { plugin: manifest.name },
+							provenance: `Plugin ${JSON.stringify(manifest.name)} supplied this text; it is plugin-authored context, not operator instructions or tool permissions.`,
+						},
+						pluginInstructions,
+					)
+				},
+			})
+		}
 
 		const enabled = this.definitionFrom(admission, 'enabled', Date.now())
 		this.pluginRegistry.register(enabled)
@@ -488,7 +677,12 @@ export class PluginLifecycleManager {
 			// prose that is itself the debt.
 			'namzu.plugin.id': pluginId,
 			'namzu.plugin.name': manifest.name,
-			'namzu.plugin.tool_count': contributions.toolNames.length,
+			'namzu.plugin.tool_count':
+				contributions.toolNames.length +
+				[...contributions.mcpNamesBySource.values()].reduce(
+					(count, names) => count + names.size,
+					0,
+				),
 			'namzu.plugin.skill_count': contributions.skillNames.length,
 			'namzu.plugin.mcp_server_count': contributions.mcpClients.length,
 		})
@@ -513,67 +707,52 @@ export class PluginLifecycleManager {
 		await client.connect()
 		contributions.mcpClients.push(client)
 
-		// Watched from here on. `connect()` above is the only attempt anything
-		// made: `transport.onClose` marked the client disconnected and rejected
-		// its pending calls, and nothing scheduled another try — so one blip
-		// took this plugin's tools out for the life of the process while the
-		// plugin went on reporting as enabled.
-		// The policy is read from the registry on EVERY attempt, not captured
-		// here. That is what makes the seam live: raising `maxAttempts` during
-		// an outage takes effect on the retry that is already running, which is
-		// the moment an operator actually reaches for it.
-		//
-		// Namespaced per server rather than globally, because two plugins'
-		// servers fail differently — one behind a flaky proxy wants patience,
-		// one behind a crash loop wants to give up and say so.
+		// The toolset owns reconnection and reads this policy on each attempt.
 		const policyScope = this.configRegistry?.register(
 			`mcp.${config.name}`,
 			MCPReconnectOptionsSchema,
 		)
-		const supervisor = new MCPReconnectSupervisor(
-			client,
-			policyScope ? () => policyScope.get() : {},
+		// Preserve cross-disable drift detection. The live toolset below owns
+		// changes during this enablement; this manager-owned discovery remembers
+		// the server's earlier admission across clients and plugin lifetimes.
+		await this.mcpDiscovery.discoverFrom(client)
+		const sourceId = `plugin:${pluginName}/mcp:${config.name}`
+		const policy = this.mcpToolPolicies?.[config.name] ?? this.mcpToolPolicies?.['*']
+		const entries = await mcpToolset(client, {
+			id: sourceId,
+			availability: 'deferred',
+			allow: policy?.allow,
+			deny: policy?.deny,
+			reconnect: policyScope ? () => policyScope.get() : {},
+			onDrift: this.onMCPToolDrift,
+			logger: this.log,
+		})
+		contributions.mcpToolsets.push(...entries)
+		const wrapped = entries.map((entry) =>
+			prefixed(entry, `${pluginName}${PLUGIN_NAMESPACE_SEPARATOR}`),
 		)
-		supervisor.start()
-		contributions.mcpSupervisors.push(supervisor)
-
-		// Through the boundary, not around it. This used to call
-		// `client.listTools()` and register everything the server answered
-		// with, so the remote side decided what entered the agent's registry
-		// — least privilege inverted. `discoverFrom` applies the per-server
-		// allow/deny policy and reports a tool set that changed since the
-		// last discovery.
-		const discovered = await this.mcpDiscovery.discoverFrom(client)
-		const mcpTools = discovered.map((d) => d.tool)
-		for (const mcpTool of mcpTools) {
-			const baseDef = mcpToolToToolDefinition(mcpTool, client, config.name)
-			// Double-underscore between serverName and toolName so that e.g.
-			// (server="fs", tool="read_file") and (server="fs_read", tool="file")
-			// produce distinct final names.
-			const namespacedName = `${pluginName}${PLUGIN_NAMESPACE_SEPARATOR}mcp__${config.name}__${mcpTool.name}`
-			const namespacedTool: ToolDefinition = { ...baseDef, name: namespacedName }
-			this.toolRegistry.register(namespacedTool, 'deferred')
-			contributions.toolNames.push(namespacedName)
-		}
-
-		// Prompts, through the same gate. A server publishing one is the same
-		// trust question as a server publishing a tool.
-		const prompts = await this.mcpDiscovery.discoverPromptsFrom(client)
-		for (const prompt of prompts) {
-			const baseDef = mcpPromptToToolDefinition(prompt, client, config.name)
-			const namespacedName = `${pluginName}${PLUGIN_NAMESPACE_SEPARATOR}${baseDef.name}`
-			this.toolRegistry.register({ ...baseDef, name: namespacedName }, 'deferred')
-			contributions.toolNames.push(namespacedName)
+		const sync = () => {
+			const previous = contributions.mcpNamesBySource.get(sourceId) ?? new Set<string>()
+			const nextTools = wrapped.flatMap((entry) => entry.tools())
+			const nextNames = new Set(nextTools.map((tool) => tool.name))
+			for (const name of previous) {
+				if (!nextNames.has(name)) this.removeContributedTool(name)
+			}
+			for (const tool of nextTools) this.addMcpTool(tool, sourceId)
+			contributions.mcpNamesBySource.set(sourceId, nextNames)
 		}
+		contributions.mcpUnsubscribers.push(entries[0].onChange?.(sync) ?? (() => {}))
+		sync()
 	}
 
 	private async rollbackContributions(
 		pluginId: PluginId,
 		contributions: PluginContributionRecord,
 	): Promise<void> {
+		await this.stopMcpContributions(contributions, 'rollback')
 		for (const name of contributions.toolNames) {
 			try {
-				this.toolRegistry.unregister(name)
+				this.removeContributedTool(name)
 			} catch (unregErr) {
 				this.log.warn('Rollback: tool unregister failed', {
 					[GENAI.TOOL_NAME]: name,
@@ -586,21 +765,6 @@ export class PluginLifecycleManager {
 			// Wrapping it would suggest a failure mode that does not exist.
 			this.skillRegistry?.unregister(name)
 		}
-		// Stop supervising BEFORE disconnecting. The lifecycle event a
-		// deliberate disconnect emits is the same one a dropped transport
-		// emits, so a still-attached supervisor would reconnect what this
-		// rollback just closed.
-		for (const supervisor of contributions.mcpSupervisors) supervisor.stop()
-		for (const client of contributions.mcpClients) {
-			try {
-				await client.disconnect()
-			} catch (discErr) {
-				this.log.warn('Rollback: MCP disconnect failed', {
-					'namzu.mcp.client_id': client.id,
-					'exception.message': toErrorMessage(discErr),
-				})
-			}
-		}
 		for (const [event, handlers] of this.hookHandlers) {
 			const filtered = handlers.filter((h) => h.pluginId !== pluginId)
 			if (filtered.length === 0) {
@@ -611,6 +775,28 @@ export class PluginLifecycleManager {
 		}
 	}
 
+	private async stopMcpContributions(
+		contributions: PluginContributionRecord,
+		operation: 'rollback' | 'disable',
+	): Promise<void> {
+		for (const unsubscribe of contributions.mcpUnsubscribers) unsubscribe()
+		for (const entry of contributions.mcpToolsets) await entry.close?.()
+		for (const client of contributions.mcpClients) {
+			try {
+				await client.disconnect()
+			} catch (error) {
+				this.log.warn('MCP disconnect failed', {
+					'namzu.plugin.operation': operation,
+					'namzu.mcp.client_id': client.id,
+					'exception.message': toErrorMessage(error),
+				})
+			}
+		}
+		for (const names of contributions.mcpNamesBySource.values()) {
+			for (const name of names) this.removeContributedTool(name)
+		}
+	}
+
 	async disable(pluginId: PluginId): Promise<void> {
 		const plugin = this.pluginRegistry.getOrThrow(pluginId)
 		const admission = this.pluginAdmissions.get(pluginId)
@@ -622,24 +808,11 @@ export class PluginLifecycleManager {
 			)
 		}
 
-		// Stop supervising first, for the same reason as the rollback path: the
-		// disconnect below emits the event the supervisor treats as a fault.
-		for (const supervisor of contributions.mcpSupervisors) supervisor.stop()
-		// Disconnect MCP clients first so no new tool calls can reach them mid-teardown.
-		for (const client of contributions.mcpClients) {
-			try {
-				await client.disconnect()
-			} catch (err) {
-				this.log.warn('MCP client disconnect failed during disable', {
-					'namzu.mcp.client_id': client.id,
-					'exception.message': toErrorMessage(err),
-				})
-			}
-		}
+		await this.stopMcpContributions(contributions, 'disable')
 
-		// Unregister contributed tools (plugin tools + MCP-adapted tools)
+		// Unregister file-declared tools; MCP entries were removed above.
 		for (const name of contributions.toolNames) {
-			this.toolRegistry.unregister(name)
+			this.removeContributedTool(name)
 		}
 
 		// And its skills. A disabled plugin whose skills stayed registered
@@ -661,6 +834,9 @@ export class PluginLifecycleManager {
 		}
 
 		this.pluginContributions.delete(pluginId)
+		this.instructions.unregister(
+			`plugin:${admission?.manifest.name ?? plugin.manifest.name}:instructions`,
+		)
 
 		// Update status to disabled
 		const disabled: PluginDefinition = admission
@@ -689,7 +865,11 @@ export class PluginLifecycleManager {
 		}
 
 		this.pluginRegistry.unregister(pluginId)
+		this.instructions.unregister(
+			`plugin:${admission?.manifest.name ?? plugin.manifest.name}:instructions`,
+		)
 		this.pluginAdmissions.delete(pluginId)
+		this.toolsetsByPlugin.delete(pluginId)
 
 		this.emit({
 			type: 'plugin_uninstalled',

package/src/plugin/resolver.ts

@@ -1,14 +1,17 @@
 import { PLUGIN_NAMESPACE_SEPARATOR } from '../constants/plugin/index.js'
 import type { PluginRegistry } from '../registry/plugin/index.js'
+import type { ToolManager } from '../toolsets/manager.js'
 import type { PluginId } from '../types/ids/index.js'
 import type { PluginContributionType } from '../types/plugin/index.js'
-import type { ToolRegistryContract } from '../types/tool/index.js'
 
 export class PluginResolver {
 	private pluginRegistry: PluginRegistry
-	private toolRegistry: ToolRegistryContract
+	private toolRegistry: Pick<ToolManager, 'listNames' | 'has'>
 
-	constructor(pluginRegistry: PluginRegistry, toolRegistry: ToolRegistryContract) {
+	constructor(
+		pluginRegistry: PluginRegistry,
+		toolRegistry: Pick<ToolManager, 'listNames' | 'has'>,
+	) {
 		this.pluginRegistry = pluginRegistry
 		this.toolRegistry = toolRegistry
 	}

package/src/plugin/shell-hook.ts

@@ -117,7 +117,9 @@ export interface ShellHookEntry {
 }
 
 /** Event → entries, the shape a host's config file carries. */
-export type ShellHooksConfig = { readonly [event in ShellHookEvent]?: readonly ShellHookEntry[] }
+export type ShellHooksConfig = {
+	readonly [event in ShellHookEvent]?: readonly ShellHookEntry[]
+}
 
 /** The plugin id host shell hooks register under when the host names none. */
 export const SHELL_HOOKS_PLUGIN_ID: PluginId = asPluginId('6d6f6bec-9d54-485b-90ca-52edbac1009d')
@@ -278,7 +280,13 @@ export function runShellHook(
 		const onAbort = () => killTree()
 		signal?.addEventListener('abort', onAbort, { once: true })
 		child.on('error', (error) => {
-			finish({ exitCode: null, timedOut, stdout, stderr, spawnError: error.message })
+			finish({
+				exitCode: null,
+				timedOut,
+				stdout,
+				stderr,
+				spawnError: error.message,
+			})
 		})
 		child.on('close', (code) => {
 			finish({ exitCode: code, timedOut, stdout, stderr })
@@ -319,9 +327,15 @@ export function shellHookVerdict(
 	outcome: ShellHookOutcome,
 	log: Logger = NOOP_LOGGER,
 ): PluginHookResult {
-	const attrs = { 'namzu.hook.event': event, 'namzu.hook.command': entry.command }
+	const attrs = {
+		'namzu.hook.event': event,
+		'namzu.hook.command': entry.command,
+	}
 	if (outcome.spawnError !== undefined) {
-		log.warn('hook could not start', { ...attrs, 'namzu.hook.error': outcome.spawnError })
+		log.warn('hook could not start', {
+			...attrs,
+			'namzu.hook.error': outcome.spawnError,
+		})
 		return { action: 'continue' }
 	}
 	if (outcome.timedOut) {
@@ -368,6 +382,8 @@ export function createShellHook(
 	options: ShellHookOptions,
 ): PluginHookDefinition {
 	const log = options.log ?? NOOP_LOGGER
+	// The shell verdict branches on `event`, but TypeScript cannot retain that
+	// correlation across the async handler closure and the union of events.
 	return {
 		event,
 		handler: async (context: PluginHookContext) => {
@@ -405,7 +421,7 @@ export function createShellHook(
 			)
 			return shellHookVerdict(event, entry, outcome, log)
 		},
-	}
+	} as PluginHookDefinition
 }
 
 /**