@namzu/sdk 46.0.0 → 48.0.0

package/src/public-runtime.ts

@@ -278,9 +278,13 @@ export type { JsonSchemaDialect } from './registry/tool/dialect.js'
 // by construction. Exported so a driver or a CI gate can assert it.
 export {
 	findPortableSchemaViolations,
+	findUndescribedProperties,
 	toPortableToolSchema,
 } from './registry/tool/portable.js'
-export type { PortableSchemaViolation } from './registry/tool/portable.js'
+export type {
+	PortableSchemaViolation,
+	UndescribedPropertyViolation,
+} from './registry/tool/portable.js'
 // The renderer itself, so a driver or a contract test can ask what a tool will
 // actually put on the wire without reaching into the registry.
 export { renderToolSchema, toolWireSchema } from './registry/tool/schema.js'
@@ -424,6 +428,7 @@ export {
 	loadSkill,
 	resolveSkillChain,
 	SKILL_FRONTMATTER_KEYS,
+	SkillCollisionError,
 	SkillRegistry,
 } from './skills/index.js'
 // The one frontmatter reader. `loadSkill` is built on it, and a host reading
@@ -450,6 +455,7 @@ export {
 	loadDirectory,
 } from './directory/index.js'
 export {
+	AdvisorCollisionError,
 	AdvisorRegistry,
 	AdvisoryContext,
 	AdvisoryExecutor,
@@ -464,6 +470,7 @@ export {
 	defineAgent,
 	InvocationLock,
 	PipelineAgent,
+	QueryAgent,
 	ReactiveAgent,
 	RouterAgent,
 	// The short path: provider + model + prompt. Assembles the identity and
@@ -552,18 +559,42 @@ export {
 	BaseRegistry,
 	ManagedRegistry,
 	PluginRegistry,
-	ToolCatalog,
+	RegistryCollisionError,
 	ToolNameCollisionError,
-	ToolRegistry,
-	createToolCatalogFromRegistry,
-	loadingFromAvailability,
-	toolDefinitionToCatalogEntry,
 } from './registry/index.js'
+export type { ManagedRegistryConfig, RegistryCollisionPolicy } from './registry/index.js'
+
+// Toolsets (plan.md v3 §1-2): the unit every tool comes from, and the
+// runtime-owned resolver of them. `toolset()` builds a plain static one;
+// `combineToolsets` merges several under one umbrella source, atomically
+// (throwing `ToolsetConflictError` on a name collision instead of silently
+// picking a winner); the rest are composable wrappers over any `Toolset`.
+// `ToolManager` is an advanced API: `query()` builds one per turn from
+// `toolsets`, and a host embedding the execution pipeline directly (rather
+// than through `query()`/the agent classes) builds its own.
+export { combineToolsets, ToolsetConflictError } from './toolsets/combine.js'
+export { defineCapability, dynamicCapability } from './capabilities/index.js'
+export { ToolManager } from './toolsets/manager.js'
+export type { ToolManagerConfig, ToolsetChangeReport } from './toolsets/manager.js'
+export { matchesSourceIdGlob } from './toolsets/source-glob.js'
+export { toolset } from './toolsets/toolset.js'
+export { toToolSourceRef } from './toolsets/types.js'
+export {
+	deferred,
+	filtered,
+	mapTools,
+	prefixed,
+	renamed,
+	readyWhen,
+	requireApproval,
+	withMetadata,
+} from './toolsets/wrappers.js'
 
 export {
 	attachShellHooks,
 	createShellHook,
 	DEFAULT_SHELL_HOOK_TIMEOUT_MS,
+	definePlugin,
 	discoverAllPluginDirs,
 	discoverPlugins,
 	loadPluginManifest,
@@ -576,6 +607,7 @@ export {
 	shellHookMatches,
 	shellHookVerdict,
 } from './plugin/index.js'
+export type { DefinedPlugin, DefinePluginOptions } from './plugin/define.js'
 
 export {
 	AgentManager,
@@ -742,6 +774,7 @@ export {
 	CommandCancellationUnsupportedError,
 	ConnectorManager,
 	ConnectorRegistry,
+	EnvironmentCollisionError,
 	EnvironmentConnectorManager,
 	ExecutionContextFactory,
 	HttpConnector,
@@ -778,6 +811,8 @@ export {
 	renderPromptMessages,
 	mcpJsonSchemaToZod,
 	mcpToolResultToToolResult,
+	mcpToolset,
+	mcpToolsetName,
 	mcpToolToToolDefinition,
 	RemoteExecutionContext,
 	RemoteExecutionBusyError,
@@ -788,6 +823,7 @@ export {
 	ServerStdioTransport,
 	StdioTransport,
 	StreamableHttpTransport,
+	TenantCollisionError,
 	TenantConnectorManager,
 	toolDefinitionToMCPTool,
 	toolResultToMCPToolResult,
@@ -810,6 +846,8 @@ export type {
 	MCPToolDrift,
 	MCPToolPolicy,
 	MCPToolPolicyDecision,
+	MCPToolsetOptions,
+	MCPToolsets,
 } from './connector/index.js'
 
 // ─── bridges (a2a + sse) ─────────────────────────────────────────────────
@@ -931,6 +969,24 @@ export {
 	nestedShellCommand,
 } from './authorization/shell-lexer.js'
 
+// Where a command line actually execs a program — unwrapping `sudo`, `env`,
+// `nice`, `timeout` and the rest of a re-exec chain with their own real
+// option grammars, rather than assuming the program sits right after the
+// wrapper's name. The live `bash` tool's escalation, the CLI's
+// scheduled-run floor and its script check all read this the same way, so
+// `env $(echo git) push` and `timeout 5 $(echo systemctl) stop …` cannot be
+// verified by one and missed by another.
+export {
+	DYNAMIC_RESOLUTION_VARIABLES,
+	hasPoisoningPrefix,
+	poisonedProgramPosition,
+	poisonsLaterCommands,
+	programPositions,
+	resolveScriptPrograms,
+	unknownProgramInLine,
+} from './authorization/program.js'
+export type { CommandProgramPositions, ProgramPosition } from './authorization/program.js'
+
 // NZ-BOOT-03: the module-attributed invariant registry. `compaction.ts` and
 // `claim-disk.ts` register themselves against the shared `invariants`
 // instance at import time (see each file); `namzu doctor` and any host can
@@ -1325,6 +1381,7 @@ export { DECLINED_TOOL_CALL_FEEDBACK } from './runtime/query/declined.js'
 export {
 	CODING_AGENT_DELEGATION_DOCTRINE,
 	CODING_AGENT_DOCTRINE_CONTRIBUTION_ID,
+	CODING_AGENT_HYPERMODE_DOCTRINE,
 	CODING_AGENT_ORCHESTRATE_DOCTRINE,
 	CODING_AGENT_WORKING_DOCTRINE,
 	PLAN_MODE_DOCTRINE,
@@ -1424,7 +1481,6 @@ export type {
 	GoalCommandScope,
 	KernelCommandOptions,
 } from './registry/command/kernel-commands.js'
-export type { ToolCatalogFromRegistryOptions } from './registry/toolset/catalog.js'
 export type { MockBidiScript, MockBidiSession } from './runtime/bidi/mock.js'
 export type { BidiTurn, BidiTurnParams } from './runtime/bidi/session.js'
 export type { SecretRedactionOptions } from './runtime/query/guardrail-presets.js'
@@ -1558,3 +1614,76 @@ export * from './store/session-index/index.js'
 export * from './store/checkpoint/index.js'
 export * from './store/budget/index.js'
 export * from './contracts/session/index.js'
+
+// ─── system events (@experimental) ──────────────────────────────────────
+//
+// One envelope for every asynchronous event a running turn reads as
+// provider-required user-role context. See `runtime/system-events.ts`.
+
+export {
+	SYSTEM_EVENT_HEADER,
+	SYSTEM_EVENT_KINDS,
+	SYSTEM_EVENT_STATUSES,
+	formatSystemEvent,
+} from './runtime/system-events.js'
+
+// ─── peer messaging (@experimental) ─────────────────────────────────────
+//
+// Cross-session messaging's SDK half: the live-session registry, the
+// `namzu-peer/1` transport (server + client), and the runtime-context
+// rendering of a delivered message or notice. CLI wiring (registry
+// lifecycle, inbox policy, `/peers`) is a separate workstream. See
+// `peers/index.ts`.
+
+export {
+	DEFAULT_PEER_READ_DEADLINE_MS,
+	DeliverRequestSchema,
+	DeliverResponseSchema,
+	DeliverStatusSchema,
+	LONGEST_PEER_SOCKET_FILE_NAME_LENGTH,
+	MAX_OUTSTANDING_PEERS,
+	MAX_OUTSTANDING_PER_PEER,
+	MAX_PEER_CONNECTIONS,
+	MAX_PEER_MESSAGE_TEXT_BYTES,
+	MAX_PEER_REQUEST_BYTES,
+	NoticeRequestSchema,
+	NoticeResponseSchema,
+	OUTSTANDING_EXPIRY_MS,
+	PEER_PROTOCOL_VERSION,
+	PEER_RECORD_VERSION,
+	PeerAddressError,
+	PeerClient,
+	PeerClientError,
+	PeerDirectoryError,
+	PeerEndpointError,
+	PeerFromSchema,
+	PeerNoticeAboutSchema,
+	PeerNoticePayloadSchema,
+	PeerRecordSchema,
+	PeerRefSchema,
+	PeerRegistryError,
+	PeerRequestSchema,
+	PeerSessionKindSchema,
+	PeerSessionStateSchema,
+	PingRequestSchema,
+	PingResponseSchema,
+	SubscribeIdleRequestSchema,
+	SubscribeIdleResponseSchema,
+	createPeerEndpoint,
+	derivePeerRef,
+	formatPeerMessage,
+	formatPeerNotice,
+	hardenPeerRuntimeDir,
+	isPeerRecordLive,
+	listLivePeers,
+	parsePeerAddress,
+	peerSocketFileName,
+	pingPeer,
+	pipePeerAddress,
+	readPeerRecord,
+	readPeerRecords,
+	removePeerRecord,
+	resolvePeerRuntimeDir,
+	udsPeerAddress,
+	writePeerRecord,
+} from './peers/index.js'

package/src/public-tools.ts

@@ -32,8 +32,9 @@ export {
 	untrustedEnvelopeBody,
 	wrapUntrusted,
 } from './tools/untrusted-envelope.js'
-export { filterReadOnlyTools, filterToolsNamed } from './tools/roster.js'
-export type { UntrustedEnvelope } from './tools/untrusted-envelope.js'
+export { matchesToolSelector } from './tools/roster.js'
+export type { ToolSelector } from './tools/roster.js'
+export type { UntrustedEnvelope, WrapUntrustedOptions } from './tools/untrusted-envelope.js'
 
 // ─── Built-in tools ──────────────────────────────────────────────────────
 
@@ -44,10 +45,29 @@ export { buildResidentHistoryTools } from './tools/resident-history.js'
 // input, which is how an `allow` for `git status*` came to approve
 // `git status && rm -rf ~`.
 export { builtinCommandArguments, commandArgumentOf } from './tools/command-arguments.js'
+// Which shell a host-side command runs in, and how to spawn it, so a host
+// that runs a command line outside the `bash` tool itself (a scheduled
+// job's own script, say) resolves the SAME shell the rules already read the
+// line in — never a second, drifting copy of this resolution.
+export {
+	type CommandShell,
+	type CommandShellProbe,
+	findCommandShell,
+	findCommandShellForDialect,
+	hostCommandShell,
+	hostShellSpawn,
+	installedCommandShellForDialect,
+	withoutBashStartup,
+} from './tools/command-shell.js'
 export { ReadFileTool } from './tools/builtins/read-file.js'
 export { WriteFileTool } from './tools/builtins/write-file.js'
 export { EditTool } from './tools/builtins/edit.js'
-export { BashTool, SANDBOX_ESCAPE_NOT_APPROVED } from './tools/builtins/bash.js'
+export {
+	BashTool,
+	type ExecHostShellProgress,
+	SANDBOX_ESCAPE_NOT_APPROVED,
+	execHostShell,
+} from './tools/builtins/bash.js'
 export { LSP_TOOL_NAME, LspTool, getCodeNavigationTools } from './tools/builtins/lsp.js'
 export { GlobTool } from './tools/builtins/glob.js'
 export { GrepTool } from './tools/builtins/grep.js'
@@ -192,7 +212,7 @@ export {
 	allConnectorTools,
 	connectorInstanceToTools,
 	connectorMethodToTool,
-	ConnectorToolRouter,
+	connectorTools,
 	createConnectorExecuteTool,
 	createConnectorListTool,
 	createConnectorRouterTool,

package/src/public-types.ts

@@ -39,6 +39,23 @@ export type {
 	SupervisorPlan,
 } from './directory/derive-supervisor.js'
 export type * from './types/toolset/index.js'
+// The toolset layer (plan.md §1): the unit every tool comes from, and its
+// composable wrappers. `ToolSource`/`ToolSourceKind` above are the ones
+// `Toolset.source` and `toolset()` use — this only adds what is new.
+export type {
+	ToolFilterSelector,
+	ToolPredicate,
+	Toolset,
+	ToolsetAvailability,
+	ToolSourceRef,
+} from './toolsets/types.js'
+export type {
+	AgentCapability,
+	Capability,
+	CapabilityModelSettings,
+	CapabilityRunContext,
+	DynamicCapability,
+} from './capabilities/index.js'
 export type * from './types/permission/index.js'
 export type * from './types/errors/index.js'
 export type * from './types/provider/index.js'
@@ -183,11 +200,7 @@ export type {
 	Timestamped,
 } from './store/index.js'
 
-export type {
-	ManagedRegistryConfig,
-	ToolExecutionResult,
-	ToolRegistryForkOptions,
-} from './registry/index.js'
+export type { ManagedRegistryConfig } from './registry/index.js'
 
 export type { PluginLifecycleManagerConfig } from './plugin/lifecycle.js'
 export type {
@@ -242,7 +255,7 @@ export type {
 export type {
 	ConnectorRouterInput,
 	ConnectorToolConfig,
-	ConnectorToolRouterConfig,
+	ConnectorTools,
 	ConnectorToolStrategy,
 } from './connector/tools/index.js'
 
@@ -684,3 +697,44 @@ export type {
 	SessionLoop,
 	SessionLoopHost,
 } from './tools/schedules/index.js'
+
+// ─── system events + peer messaging (@experimental) ───────────────────────
+
+export type {
+	FormatSystemEventOptions,
+	SystemEvent,
+	SystemEventBody,
+	SystemEventKind,
+	SystemEventStatus,
+	SystemEventUsage,
+} from './runtime/system-events.js'
+
+export type { PeerAddress } from './peers/address.js'
+export type {
+	HardenPeerDirectory,
+	PeerRuntimeDir,
+	ResolvePeerRuntimeDirOptions,
+} from './peers/dir.js'
+export type { PeerRecord } from './peers/record.js'
+export type { ListLivePeersOptions, PeerLivenessOptions } from './peers/registry.js'
+export type {
+	DeliverRequest,
+	DeliverResponse,
+	DeliverStatus,
+	NoticeRequest,
+	NoticeResponse,
+	PeerFrom,
+	PeerNoticeAbout,
+	PeerNoticePayload,
+	PeerRequest,
+	PeerResponse,
+	PeerSessionKind,
+	PeerSessionState,
+	PingRequest,
+	PingResponse,
+	SubscribeIdleRequest,
+	SubscribeIdleResponse,
+} from './peers/protocol.js'
+export type { CreatePeerEndpointOptions, PeerEndpoint } from './peers/endpoint.js'
+export type { PeerClientOptions, PeerClientResult } from './peers/client.js'
+export type { PeerMessageEnvelopeInput } from './peers/envelope.js'

package/src/read-model/registry.ts

@@ -1,3 +1,4 @@
+import { RegistryCollisionError } from '../registry/collision.js'
 import type { SessionRecord } from '../types/session/index.js'
 
 /**
@@ -70,11 +71,15 @@ export class UnknownReadModelError extends Error {
 }
 
 /** Two models claiming one id. */
-export class ReadModelCollisionError extends Error {
+export class ReadModelCollisionError extends RegistryCollisionError {
 	readonly details: { id: string }
 
 	constructor(details: { id: string }) {
-		super(`A read model with id "${details.id}" is already registered.`)
+		super(
+			'ReadModelRegistry',
+			details.id,
+			`A read model with id "${details.id}" is already registered.`,
+		)
 		this.name = 'ReadModelCollisionError'
 		this.details = details
 	}

package/src/registry/ManagedRegistry.ts

@@ -2,6 +2,7 @@ import { NAMZU } from '../constants/telemetry/index.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
 import { BaseRegistry } from './BaseRegistry.js'
+import { RegistryCollisionError, type RegistryCollisionPolicy } from './collision.js'
 
 export interface ManagedRegistryConfig<TDefinition> {
 	componentName: string
@@ -12,17 +13,31 @@ export interface ManagedRegistryConfig<TDefinition> {
 	 */
 	computeId?: (item: TDefinition) => string
 	logger?: Logger
+	/**
+	 * What to do when `register` is given an id already present.
+	 *
+	 * Defaults to `'throw'`. Pass `'warn-overwrite'` or `'warn-skip'` only for
+	 * a registry that genuinely means one of those (see
+	 * {@link RegistryCollisionPolicy}). A single call that needs to replace
+	 * one entry on an otherwise-`'throw'` registry calls {@link ManagedRegistry.replace}
+	 * instead of changing the registry's policy.
+	 */
+	onCollision?: RegistryCollisionPolicy
 }
 
 export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 	protected log: Logger
 	private idField?: keyof TDefinition & string
 	private computeId?: (item: TDefinition) => string
+	private componentName: string
+	private onCollision: RegistryCollisionPolicy
 
 	constructor(config: ManagedRegistryConfig<TDefinition>) {
 		super()
 		this.idField = config.idField
 		this.computeId = config.computeId
+		this.componentName = config.componentName
+		this.onCollision = config.onCollision ?? 'throw'
 		this.log = resolveLogger(config.logger).child({
 			[SCOPE_ATTRIBUTE]: 'registry',
 			[NAMZU.REGISTRY_NAME]: config.componentName,
@@ -46,8 +61,8 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 			}
 			const id = idOrItem
 			const item = maybeItem
-			if (this.has(id)) {
-				this.log.warn('Already registered, overwriting', { 'namzu.registry.item_id': id })
+			if (this.has(id) && !this.applyCollisionPolicy(id)) {
+				return
 			}
 			super.register(id, item)
 			this.log.debug('Registered', { 'namzu.registry.item_id': id })
@@ -64,8 +79,8 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 			throw new Error('register(item) requires idField or computeId to be configured')
 		}
 
-		if (this.has(id)) {
-			this.log.warn('Already registered, overwriting', { 'namzu.registry.item_id': id })
+		if (this.has(id) && !this.applyCollisionPolicy(id)) {
+			return
 		}
 		super.register(id, item)
 		// `debug`, not `info`. Registration is the startup path doing exactly
@@ -75,8 +90,8 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 		// failure as silence with the sign flipped — the interesting lines are
 		// there, and nobody can find them.
 		//
-		// The overwrite case above stays at `warn`, because a second
-		// registration under a live id IS news.
+		// The overwrite case above stays at `warn` (or throws), because a
+		// second registration under a live id IS news.
 		//
 		// Found by running the CLI against a real provider rather than a mock.
 		// Every unit test here asserts on a logger stub, so the LEVEL was
@@ -85,6 +100,42 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 		this.log.debug('Registered', { 'namzu.registry.item_id': id })
 	}
 
+	/**
+	 * Register `item` under `id`, replacing whatever is already there —
+	 * regardless of this registry's {@link RegistryCollisionPolicy}.
+	 *
+	 * For the one call site that legitimately supersedes an earlier
+	 * registration under the same id (a plugin's status transition, a
+	 * reload) — not a registry-wide escape hatch. A registry whose intended
+	 * behaviour IS overwrite-by-default declares `onCollision: 'warn-overwrite'`
+	 * instead of routing every caller through this method.
+	 */
+	replace(id: string, item: TDefinition): void {
+		const existed = this.has(id)
+		super.register(id, item)
+		this.log.debug(existed ? 'Replaced' : 'Registered', { 'namzu.registry.item_id': id })
+	}
+
+	/**
+	 * Runs this registry's {@link RegistryCollisionPolicy} for an id already
+	 * present. Returns `true` when the caller should proceed to overwrite,
+	 * `false` when it should leave the existing item alone.
+	 */
+	private applyCollisionPolicy(id: string): boolean {
+		switch (this.onCollision) {
+			case 'throw':
+				throw new RegistryCollisionError(this.componentName, id)
+			case 'warn-skip':
+				this.log.warn('Already registered, keeping existing', {
+					'namzu.registry.item_id': id,
+				})
+				return false
+			default:
+				this.log.warn('Already registered, overwriting', { 'namzu.registry.item_id': id })
+				return true
+		}
+	}
+
 	getOrThrow(id: string): TDefinition {
 		const item = this.get(id)
 		if (!item) {

package/src/registry/collision.ts

@@ -0,0 +1,64 @@
+/**
+ * What a registry does when a second item claims an id it already holds.
+ *
+ * Nine `*CollisionError` classes existed across the SDK before this file did
+ * (tool, host command, config namespace, prompt contribution, read model,
+ * invariant, probe, provider — see `RegistryCollisionError` below), each
+ * hand-rolled, and a handful of registries never threw at all —
+ * `ManagedRegistry.register` warned and overwrote by default, `AdvisorRegistry`
+ * and the two connector managers (`manager/connector/environment.ts`,
+ * `tenant.ts`) warned and kept the original, and `SkillRegistry.add` did
+ * neither, in total silence. This file gives the concept a shared
+ * vocabulary, and every one of those registries now throws on a duplicate id
+ * by default (`RegistryCollisionError` or a domain-specific subclass); a
+ * caller that genuinely means to replace an existing entry says so
+ * explicitly at the call site.
+ */
+
+/**
+ * A named collision policy for a `ManagedRegistry`.
+ *
+ * - `'throw'` (default): raise a {@link RegistryCollisionError} naming this
+ *   registry and the id, and leave the existing item in place. Right for
+ *   every registry here unless a caller can name a reason a second
+ *   registration under one id should not be a bug.
+ * - `'warn-overwrite'`: log a warning and replace the existing item.
+ *   `ToolRegistry` used to keep this policy for its own `register`, so a
+ *   host mounting the same tool twice (once a legitimate, common shape)
+ *   kept working unchanged; that class is gone now (plan.md v3 §2) — a
+ *   `ToolManager`'s toolsets throw `ToolsetConflictError` on any collision
+ *   instead, naming both sources, with no overwrite mode at all.
+ * - `'warn-skip'`: log a warning and keep the existing item — the one being
+ *   registered is discarded.
+ *
+ * A single call that needs to replace an existing entry on a registry whose
+ * policy is `'throw'` passes `{ replace: true }` to that call instead of
+ * changing the registry's policy — see `ManagedRegistry.register`.
+ */
+export type RegistryCollisionPolicy = 'throw' | 'warn-overwrite' | 'warn-skip'
+
+/**
+ * A second item claiming an id a registry already holds.
+ *
+ * The base class every SDK `*CollisionError` extends, so a host that wants
+ * to catch "some registry collided" without naming every concrete error
+ * class can catch this one instead. Each concrete subclass keeps its own
+ * `name`, message and fields exactly as before — this only adds
+ * `registryName` and `collidingId`, which every collision shares by
+ * definition — and `ManagedRegistry`'s own `'throw'` policy (see
+ * {@link RegistryCollisionPolicy}) raises this class directly when a
+ * registry has no domain-specific subclass of its own.
+ */
+export class RegistryCollisionError extends Error {
+	/** Which registry raised this, e.g. `"ToolRegistry"`. */
+	readonly registryName: string
+	/** The id or name two registrations collided on. */
+	readonly collidingId: string
+
+	constructor(registryName: string, collidingId: string, message?: string) {
+		super(message ?? `"${collidingId}" is already registered in ${registryName}.`)
+		this.name = 'RegistryCollisionError'
+		this.registryName = registryName
+		this.collidingId = collidingId
+	}
+}

package/src/registry/command/index.ts

@@ -5,6 +5,7 @@ import type {
 	SerializableHostCommand,
 } from '../../types/command/index.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
+import { RegistryCollisionError } from '../collision.js'
 
 /**
  * A second command claiming a name that is already taken.
@@ -14,11 +15,13 @@ import { ManagedRegistry } from '../ManagedRegistry.js'
  * skip, rename, refuse to boot — has to catch it narrowly instead of
  * matching on message text.
  */
-export class HostCommandNameCollisionError extends Error {
+export class HostCommandNameCollisionError extends RegistryCollisionError {
 	readonly commandName: string
 
 	constructor(commandName: string) {
 		super(
+			'HostCommandRegistry',
+			commandName,
 			`Host command "/${commandName}" is already registered. Two commands answering to one name shadow each other silently, and which one wins depends on registration order.`,
 		)
 		this.name = 'HostCommandNameCollisionError'
@@ -35,8 +38,9 @@ export class HostCommandNameCollisionError extends Error {
  * right for a tool roster a host assembles deliberately and wrong here.
  * These are operator-facing, and a shadowed command is invisible — it does
  * not fail, it simply never runs, and the one that wins depends on
- * registration order. `ToolRegistry` reaches the same conclusion for the
- * same reason one directory over.
+ * registration order. `ToolManager` (`toolsets/manager.ts`) reaches the
+ * same conclusion for the same reason one directory over — a toolset
+ * collision throws rather than shadowing silently.
  */
 export class HostCommandRegistry extends ManagedRegistry<HostCommandDescriptor> {
 	constructor(logger?: ConstructorParameters<typeof ManagedRegistry>[0]['logger']) {

package/src/registry/index.ts

@@ -1,16 +1,10 @@
 export { BaseRegistry } from './BaseRegistry.js'
+export { RegistryCollisionError } from './collision.js'
+export type { RegistryCollisionPolicy } from './collision.js'
 export { ManagedRegistry } from './ManagedRegistry.js'
 export type { ManagedRegistryConfig } from './ManagedRegistry.js'
 
-export { ToolNameCollisionError, ToolRegistry } from './tool/execute.js'
-export type { ToolExecutionResult, ToolRegistryForkOptions } from './tool/execute.js'
-export {
-	ToolCatalog,
-	createToolCatalogFromRegistry,
-	loadingFromAvailability,
-	toolDefinitionToCatalogEntry,
-} from './toolset/catalog.js'
-export type { ToolCatalogFromRegistryOptions, ToolCatalogSearchOptions } from './toolset/catalog.js'
+export { ToolNameCollisionError, TOOL_NAME_PATTERN, assertToolName } from './tool/execute.js'
 
 export { ConnectorRegistry } from './connector/definitions.js'
 export { ScopedConnectorRegistry } from './connector/scoped.js'

package/src/registry/plugin/index.ts

@@ -3,7 +3,20 @@ import { ManagedRegistry } from '../ManagedRegistry.js'
 
 export class PluginRegistry extends ManagedRegistry<PluginDefinition> {
 	constructor() {
-		super({ componentName: 'PluginRegistry', idField: 'id' })
+		super({
+			componentName: 'PluginRegistry',
+			idField: 'id',
+			// A public projection a host is meant to be able to overwrite —
+			// `PluginLifecycleManager` itself re-registers the same id under
+			// a new status on every enable/disable/error transition, and a
+			// host may write its own record here directly (executable
+			// contribution ownership, not this registry, is the lifecycle's
+			// real guard against a forged status — see `enable()`'s comment
+			// in `plugin/lifecycle.ts`). `ManagedRegistry`'s own default is
+			// `'throw'` now (see `registry/collision.ts`); this registry is
+			// one of the named exceptions.
+			onCollision: 'warn-overwrite',
+		})
 	}
 
 	listByScope(scope: PluginScope): PluginDefinition[] {