@sparkelf/dsh-knowledge-base 0.1.21 → 0.1.22

package/lib/index.js

@@ -14,11 +14,17 @@ import { DatabaseSync } from "node:sqlite";
 * Model-facing management tools for the knowledge base and the workflow plaza.
 *
 * The UI already exposes these operations. This module gives the model the same
-* operations without re-implementing authorization: every tool reads the backend
-* review context (roles + department scope) and refuses with a structured 403 before
-* touching the host. Writes additionally require an explicit human authorization flag,
-* because a model deciding on its own must never be indistinguishable from an operator
-* approving a review.
+* operations without re-implementing authorization: which tools exist is decided
+* once from the caller's review context by `toolDisclosure.ts`, so a tool body does
+* not re-read the permission tree on every call. The context is still read where it
+* decides WHICH rows a visible tool may return (department scope, own audit trail)
+* and for the actor recorded in an audit line. Writes additionally require an
+* explicit human authorization flag, because a model deciding on its own must never
+* be indistinguishable from an operator approving a review.
+*
+* DataOps remains the final authority: every host call below reaches a backend
+* route that enforces the JWT's current roles and grants, so a stale disclosure can
+* cause a refusal but never an unauthorized operation.
 *
 * Secrets are write-only through the UI; these tools deliberately reject secret-shaped
 * fields and redact them on reads.
@@ -99,10 +105,6 @@ function defaultPermissionsForRoles(roleKeys) {
 function hasPermission(context, permission) {
 	return context.permissions.includes(permission);
 }
-/** Require one backend permission key; a denial is a structured 403. */
-function requirePermission$1(context, permission, action) {
-	if (!hasPermission(context, permission)) throw new ManagementToolError("forbidden", `缺少权限 ${permission}${action === void 0 ? "" : "（" + action + "）"}`);
-}
 /** Global administrators: all resources and all review queues. */
 function isGlobalAdmin(context) {
 	return context.review.canReviewGlobal === true || context.dataScope.all === true || context.roleCodes.some((code) => code === "SUPER_ADMIN" || code === "ADMIN");
@@ -217,7 +219,6 @@ const createManagementTools = (host) => [
 		parameters: {},
 		output: jsonOutput$1,
 		execute: async () => run$2(async () => {
-			requirePermission$1(await host.context(), "kb:config:manage");
 			return { config: redactSecrets(await host.kbConfigGet()) };
 		})
 	}),
@@ -235,7 +236,6 @@ const createManagementTools = (host) => [
 		},
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			requirePermission$1(await host.context(), "kb:config:manage");
 			requireConfirmed(args.authorization);
 			assertNoSecretFields(args.patch);
 			return { config: redactSecrets(await host.kbConfigUpdate(args.patch)) };
@@ -248,7 +248,6 @@ const createManagementTools = (host) => [
 		output: jsonOutput$1,
 		execute: async () => run$2(async () => {
 			const context = await host.context();
-			requirePermission$1(context, "kb:grant:manage");
 			const grants = await host.kbGrantList();
 			return { grants: isGlobalAdmin(context) ? grants : grants.filter((grant) => isPathInDepartmentScope(context, grant.relPath)) };
 		})
@@ -281,9 +280,7 @@ const createManagementTools = (host) => [
 		},
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			const context = await host.context();
-			requirePermission$1(context, "kb:grant:manage");
-			requirePathScope(context, args.relPath);
+			requirePathScope(await host.context(), args.relPath);
 			requireConfirmed(args.authorization);
 			if (args.relPath.trim() === "" || args.principalId.trim() === "") throw new ManagementToolError("invalid", "relPath and principalId are required");
 			return { grant: await host.kbGrantSet(args) };
@@ -321,7 +318,6 @@ const createManagementTools = (host) => [
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
 			const context = await host.context();
-			requirePermission$1(context, "kb:audit:read");
 			const entries = await host.kbAuditList({
 				...args,
 				limit: Math.max(1, Math.min(500, args.limit ?? 100))
@@ -336,7 +332,6 @@ const createManagementTools = (host) => [
 		output: jsonOutput$1,
 		execute: async () => run$2(async () => {
 			const context = await host.context();
-			requirePermission$1(context, "kb:review:decide");
 			const pending = await host.kbReviewList();
 			return { pending: isGlobalAdmin(context) ? pending : pending.filter((item) => isPathInDepartmentScope(context, item.relPath)) };
 		})
@@ -364,7 +359,6 @@ const createManagementTools = (host) => [
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
 			const context = await host.context();
-			requirePermission$1(context, "kb:review:decide");
 			requireConfirmed(args.authorization);
 			if (args.decision !== "approve" && args.decision !== "reject") throw new ManagementToolError("invalid", "decision must be approve or reject");
 			const target = (await host.kbReviewList()).find((item) => item.name === args.name);
@@ -383,7 +377,6 @@ const createManagementTools = (host) => [
 		parameters: {},
 		output: jsonOutput$1,
 		execute: async () => run$2(async () => {
-			requirePermission$1(await host.context(), "kb:file:extract");
 			return { sync: await host.kbSync() };
 		})
 	}),
@@ -393,7 +386,6 @@ const createManagementTools = (host) => [
 		parameters: {},
 		output: jsonOutput$1,
 		execute: async () => run$2(async () => {
-			requirePermission$1(await host.context(), "kb:file:extract");
 			return { index: await host.kbIndexRebuild() };
 		})
 	}),
@@ -412,7 +404,6 @@ const createManagementTools = (host) => [
 		},
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			requirePermission$1(await host.context(), "workflow:read");
 			return { workflows: await host.workflowList(args) };
 		})
 	}),
@@ -449,7 +440,6 @@ const createManagementTools = (host) => [
 		},
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			requirePermission$1(await host.context(), "workflow:publish");
 			requireConfirmed(args.authorization);
 			return { workflow: await host.workflowUpdate(args) };
 		})
@@ -467,7 +457,6 @@ const createManagementTools = (host) => [
 		},
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			requirePermission$1(await host.context(), "workflow:manage");
 			requireConfirmed(args.authorization);
 			return { result: await host.workflowUnpublish(args.id) };
 		})
@@ -491,7 +480,6 @@ const createManagementTools = (host) => [
 		},
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			requirePermission$1(await host.context(), "workflow:review:decide");
 			return { workflows: await host.workflowReviewList(args) };
 		})
 	}),
@@ -505,7 +493,6 @@ const createManagementTools = (host) => [
 		} },
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			requirePermission$1(await host.context(), "workflow:read");
 			if (!Array.isArray(args.ids) || args.ids.length === 0) throw new ManagementToolError("invalid", "ids is required");
 			return { scan: await host.workflowReviewScan(args.ids) };
 		})
@@ -532,7 +519,6 @@ const createManagementTools = (host) => [
 		},
 		output: jsonOutput$1,
 		execute: async (args) => run$2(async () => {
-			requirePermission$1(await host.context(), "workflow:review:decide");
 			requireConfirmed(args.authorization);
 			if (args.decision !== "approve" && args.decision !== "reject") throw new ManagementToolError("invalid", "decision must be approve or reject");
 			const ids = Array.isArray(args.ids) ? args.ids.filter((id) => typeof id === "string" && id !== "") : [];
@@ -546,6 +532,355 @@ const createManagementTools = (host) => [
 	})
 ];
 //#endregion
+//#region src/toolDisclosure.ts
+/** The four disclosure groups a knowledge-base tool can belong to. */
+const TOOL_GROUPS = [
+	"read",
+	"write",
+	"manage",
+	"publish"
+];
+/**
+* Disclosure rules for every model-facing tool this package registers.
+*
+* The map is the single list of what exists; the coordinator rejects a tool
+* definition without a rule and a rule without a definition at construction time,
+* so a new tool cannot ship undisclosed or leave a stale policy behind.
+*/
+const KB_TOOL_ACCESS = Object.freeze({
+	kb_search: {
+		group: "read",
+		permissions: ["kb:file:read"]
+	},
+	kb_chunk_get: {
+		group: "read",
+		permissions: ["kb:file:read"]
+	},
+	kb_outline: {
+		group: "read",
+		permissions: ["kb:file:read"]
+	},
+	kb_outline_rewrite: {
+		group: "read",
+		permissions: ["kb:file:read"]
+	},
+	kb_vectorize: {
+		group: "read",
+		permissions: ["kb:file:read"]
+	},
+	workflow_list: {
+		group: "read",
+		permissions: ["workflow:read"]
+	},
+	kb_file_write: {
+		group: "write",
+		permissions: ["kb:file:write"]
+	},
+	kb_file_move: {
+		group: "write",
+		permissions: ["kb:file:write"]
+	},
+	kb_file_delete: {
+		group: "write",
+		permissions: ["kb:file:delete"]
+	},
+	kb_file_mkdir: {
+		group: "write",
+		permissions: ["kb:file:write"]
+	},
+	kb_file_extract: {
+		group: "write",
+		permissions: ["kb:file:extract"]
+	},
+	kb_outline_save: {
+		group: "write",
+		permissions: ["kb:file:read", "kb:file:write"]
+	},
+	kb_config_get: {
+		group: "manage",
+		permissions: ["kb:config:manage"]
+	},
+	kb_config_update: {
+		group: "manage",
+		permissions: ["kb:config:manage"]
+	},
+	kb_grant_list: {
+		group: "manage",
+		permissions: ["kb:grant:manage"]
+	},
+	kb_grant_set: {
+		group: "manage",
+		permissions: ["kb:grant:manage"]
+	},
+	kb_audit_list: {
+		group: "manage",
+		permissions: ["kb:audit:read"]
+	},
+	kb_review_list: {
+		group: "manage",
+		permissions: ["kb:review:decide"]
+	},
+	kb_review_decide: {
+		group: "manage",
+		permissions: ["kb:review:decide"]
+	},
+	kb_sync: {
+		group: "manage",
+		capability: "reviewer"
+	},
+	kb_index_rebuild: {
+		group: "manage",
+		permissions: ["kb:config:manage"]
+	},
+	workflow_unpublish: {
+		group: "manage",
+		permissions: ["workflow:manage"]
+	},
+	workflow_review_list: {
+		group: "manage",
+		permissions: ["workflow:review:decide"]
+	},
+	workflow_review_scan: {
+		group: "manage",
+		permissions: ["workflow:review:decide"]
+	},
+	workflow_review_decide: {
+		group: "manage",
+		permissions: ["workflow:review:decide"]
+	},
+	workflow_publish: {
+		group: "publish",
+		permissions: ["workflow:publish"]
+	},
+	workflow_update: {
+		group: "publish",
+		permissions: ["workflow:publish"]
+	}
+});
+Object.freeze({
+	read: namesIn("read"),
+	write: namesIn("write"),
+	manage: namesIn("manage"),
+	publish: namesIn("publish")
+});
+Object.freeze(Object.keys(KB_TOOL_ACCESS));
+function namesIn(group) {
+	return Object.freeze(Object.entries(KB_TOOL_ACCESS).filter(([, rule]) => rule.group === group).map(([name]) => name));
+}
+/**
+* Decide whether one tool is visible for a permission context.
+*
+* An absent context is a denial: disclosure happens before execution, so an
+* unresolved permission tree must withhold the surface rather than expose it.
+* Unknown tool names are denied too; the coordinator rejects them at construction,
+* and this function keeps the same fail-closed answer if one reaches it anyway.
+*
+* @param name - model-facing tool name.
+* @param context - the caller's review context, or undefined while it is unavailable.
+* @returns the decision and the requirements the context did not satisfy.
+*/
+function decideToolAccess(name, context) {
+	const rule = KB_TOOL_ACCESS[name];
+	if (rule === void 0) return {
+		allowed: false,
+		missing: ["disclosure-policy"]
+	};
+	if (context === void 0) return {
+		allowed: false,
+		group: rule.group,
+		missing: ["permission-context"]
+	};
+	const missing = [];
+	for (const permission of rule.permissions ?? []) if (!hasPermission(context, permission)) missing.push(permission);
+	if (rule.capability === "reviewer" && !(isGlobalAdmin(context) || context.review.canReview === true)) missing.push("reviewer");
+	if (rule.capability === "admin" && !isGlobalAdmin(context)) missing.push("admin");
+	return {
+		allowed: missing.length === 0,
+		group: rule.group,
+		missing
+	};
+}
+/**
+* Register and dispose knowledge-base tools as the caller's permission context changes.
+*
+* The coordinator owns every tool registration. A pass computes one decision per
+* tool, registers the newly allowed ones, disposes the newly denied ones and
+* leaves unchanged tools untouched, so an unchanged context causes no registry
+* churn. Concurrent refreshes share one in-flight context read; a pass that is
+* superseded by a newer context never applies its stale answer.
+*
+* On a context-resolution failure every gated tool is disposed. That is the
+* fail-closed direction: an unavailable permission tree cannot prove a capability,
+* and a tool surface that outlives its proof is exactly the leak disclosure exists
+* to prevent.
+*/
+var ToolDisclosureCoordinator = class {
+	definitions;
+	/** Registered tools and their exact registry disposers. */
+	disposers = /* @__PURE__ */ new Map();
+	options;
+	/** Monotonic pass counter; a slower older read must not overwrite a newer one. */
+	generation = 0;
+	inFlight;
+	disposed = false;
+	snapshot;
+	constructor(options) {
+		this.options = options;
+		this.definitions = new Map(options.tools.map((definition) => [definition.name, definition]));
+		assertCompleteDisclosure(this.definitions.keys());
+	}
+	/** Tool names currently registered, in definition order. */
+	get registeredTools() {
+		return [...this.definitions.keys()].filter((name) => this.disposers.has(name));
+	}
+	/** The most recent disclosure pass, if one has completed. */
+	get lastSnapshot() {
+		return this.snapshot;
+	}
+	/**
+	* Recompute the tool surface.
+	*
+	* @param context - a context already read by the caller (a route gate or status
+	*   request). Passing it avoids a second backend round trip. Omit it to resolve
+	*   one through {@link ToolDisclosureOptions.resolveContext}.
+	* @returns the resulting snapshot; a context failure is reported in `error`
+	*   rather than thrown, because a refresh must never fail the request that
+	*   triggered it.
+	*/
+	syncToolDisclosure(context) {
+		if (this.disposed) return Promise.resolve(this.emptySnapshot("tool disclosure is disposed"));
+		if (context !== void 0) {
+			this.generation += 1;
+			try {
+				return Promise.resolve(this.apply(context));
+			} catch (error) {
+				return Promise.resolve(this.fail(error));
+			}
+		}
+		if (this.inFlight !== void 0) return this.inFlight;
+		const generation = ++this.generation;
+		const run = Promise.resolve().then(() => this.options.resolveContext()).then((resolved) => generation === this.generation ? this.apply(resolved) : this.snapshot ?? this.emptySnapshot("a newer disclosure pass superseded this one")).catch((error) => generation === this.generation ? this.fail(error) : this.snapshot ?? this.emptySnapshot("a newer disclosure pass superseded this one")).finally(() => {
+			if (this.inFlight === run) this.inFlight = void 0;
+		});
+		this.inFlight = run;
+		return run;
+	}
+	/** Dispose every tool this coordinator registered; later refreshes are no-ops. */
+	dispose() {
+		this.disposed = true;
+		this.disposeRegistered();
+	}
+	/** Register allowed tools and dispose denied ones for one resolved context. */
+	apply(context) {
+		const denied = [];
+		for (const [name, definition] of this.definitions) {
+			const decision = decideToolAccess(name, context);
+			if (decision.allowed) {
+				if (!this.disposers.has(name)) try {
+					this.disposers.set(name, this.options.registry.register(definition));
+				} catch (error) {
+					this.options.log?.(`tool disclosure: could not register ${name}: ${messageOf$1(error)}`);
+					denied.push({
+						name,
+						...decision.group === void 0 ? {} : { group: decision.group },
+						missing: ["register-failed"]
+					});
+				}
+				continue;
+			}
+			denied.push({
+				name,
+				...decision.group === void 0 ? {} : { group: decision.group },
+				missing: decision.missing
+			});
+			const dispose = this.disposers.get(name);
+			if (dispose !== void 0) {
+				try {
+					dispose();
+				} catch (error) {
+					this.options.log?.(`tool disclosure: could not dispose ${name}: ${messageOf$1(error)}`);
+				}
+				this.disposers.delete(name);
+			}
+		}
+		const registered = this.registeredTools;
+		const snapshot = {
+			registered,
+			denied,
+			activeGroups: TOOL_GROUPS.filter((group) => registered.some((name) => KB_TOOL_ACCESS[name]?.group === group))
+		};
+		const changed = this.snapshot === void 0 || this.snapshot.registered.join("\0") !== registered.join("\0") || this.snapshot.error === void 0 !== (snapshot.error === void 0);
+		this.snapshot = snapshot;
+		if (changed) this.options.log?.(`tool disclosure: registered ${String(registered.length)} tool(s) [${registered.join(", ")}]; withheld ${String(denied.length)}`);
+		return snapshot;
+	}
+	/** Dispose everything and report why the surface is empty. */
+	fail(error) {
+		this.disposeRegistered();
+		const message = messageOf$1(error);
+		const snapshot = {
+			registered: [],
+			denied: [...this.definitions.keys()].map((name) => ({
+				name,
+				...KB_TOOL_ACCESS[name] === void 0 ? {} : { group: KB_TOOL_ACCESS[name].group },
+				missing: ["permission-context"]
+			})),
+			activeGroups: [],
+			error: message
+		};
+		this.snapshot = snapshot;
+		this.options.log?.(`tool disclosure: permission context unavailable; withheld every gated tool: ${message}`);
+		return snapshot;
+	}
+	/** Dispose every registered tool; safe to call more than once. */
+	disposeRegistered() {
+		for (const dispose of this.disposers.values()) try {
+			dispose();
+		} catch (error) {
+			this.options.log?.(`tool disclosure: could not dispose a tool: ${messageOf$1(error)}`);
+		}
+		this.disposers.clear();
+	}
+	/** Snapshot for a pass that cannot run at all. */
+	emptySnapshot(reason) {
+		return {
+			registered: [],
+			denied: [...this.definitions.keys()].map((name) => ({
+				name,
+				...KB_TOOL_ACCESS[name] === void 0 ? {} : { group: KB_TOOL_ACCESS[name].group },
+				missing: ["permission-context"]
+			})),
+			activeGroups: [],
+			error: reason
+		};
+	}
+};
+/**
+* Build a coordinator.
+*
+* @param options - the definitions, registry, context resolver and log sink.
+* @returns the coordinator the plugin stores and refreshes.
+*/
+function createToolDisclosure(options) {
+	return new ToolDisclosureCoordinator(options);
+}
+/**
+* Reject a policy map that drifted from the tool set.
+*
+* Called by the constructor, so a missing rule or a stale rule fails at plugin
+* start rather than silently exposing or hiding a tool later.
+*/
+function assertCompleteDisclosure(names) {
+	const present = new Set(names);
+	const unknown = [...present].filter((name) => KB_TOOL_ACCESS[name] === void 0);
+	const stale = Object.keys(KB_TOOL_ACCESS).filter((name) => !present.has(name));
+	if (unknown.length > 0 || stale.length > 0) throw new Error("knowledge-base tool disclosure is incomplete:" + (unknown.length === 0 ? "" : ` no policy for ${unknown.join(", ")};`) + (stale.length === 0 ? "" : ` policy without a tool for ${stale.join(", ")};`));
+}
+/** Error text safe to log from a contained refresh. */
+function messageOf$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
 //#region src/workflowPublish.ts
 /**
 * The workflow-plaza publish store.
@@ -8244,16 +8579,12 @@ const run = async (path, operation) => {
 		throw asKnowledgeToolError(error, path);
 	}
 };
-/** Require one backend DSH permission before the tool touches the tree. */
-async function requirePermission(host, permission) {
-	if (host.hasPermission === void 0) return;
-	if (!await host.hasPermission(permission)) throw new KnowledgeToolError("forbidden", `缺少权限 ${permission}`);
-}
 /**
-* Build the five file model-facing tools.
+* Build the knowledge-base model-facing tools.
 *
-* Returned definitions are registered by `apply`; tests call the same definitions with
-* a fake host to assert permission, path and audit behaviour without a live backend.
+* Returned definitions are registered by `apply` through the permission-based
+* disclosure coordinator; tests call the same definitions with a fake host to assert
+* path, audit and result behaviour without a live backend or a permission backend.
 */
 const createKnowledgeFileTools = (host) => [
 	defineTool({
@@ -8279,7 +8610,6 @@ const createKnowledgeFileTools = (host) => [
 		execute: async (args) => run(args.path, async () => {
 			const relPath = assertToolPath(args.path);
 			const content = typeof args.content === "string" ? args.content : "";
-			await requirePermission(host, "kb:file:write");
 			await requireWrite(host, relPath);
 			const caller = await host.resolveCaller();
 			const existing = await host.statEntry(relPath);
@@ -8344,7 +8674,6 @@ const createKnowledgeFileTools = (host) => [
 		execute: async (args) => run(args.from, async () => {
 			const from = assertToolPath(args.from);
 			const to = assertToolPath(args.to, true);
-			await requirePermission(host, "kb:file:write");
 			await requireWrite(host, from);
 			const caller = await host.resolveCaller();
 			const targetEntry = to === "" ? void 0 : await host.statEntry(to);
@@ -8391,7 +8720,6 @@ const createKnowledgeFileTools = (host) => [
 		output: jsonOutput,
 		isConcurrencySafe: () => true,
 		execute: async (args) => run(void 0, async () => {
-			await requirePermission(host, "kb:file:read");
 			if (host.searchIndex === void 0) throw new KnowledgeToolError("not-configured", "knowledge index is unavailable");
 			const query = typeof args.query === "string" ? args.query.trim() : "";
 			if (query === "") throw new KnowledgeToolError("empty-path", "query must be non-empty");
@@ -8482,7 +8810,6 @@ const createKnowledgeFileTools = (host) => [
 		},
 		output: jsonOutput,
 		execute: async (args) => run(args.path, async () => {
-			await requirePermission(host, "kb:file:read");
 			if (host.vectorize === void 0) throw new KnowledgeToolError("not-configured", "vector indexing is unavailable");
 			const hasDocId = args.docId !== void 0;
 			const hasPath = typeof args.path === "string" && args.path.trim() !== "";
@@ -8529,7 +8856,6 @@ const createKnowledgeFileTools = (host) => [
 		output: jsonOutput,
 		isConcurrencySafe: () => true,
 		execute: async (args) => run(void 0, async () => {
-			await requirePermission(host, "kb:file:read");
 			if (host.chunkGet === void 0) throw new KnowledgeToolError("not-configured", "knowledge chunk resolver is unavailable");
 			const fromToken = typeof args.citation === "string" ? /^kb:\/\/doc\/([^/\s?#]+)\/chunk\/([^/\s?#]+)/i.exec(args.citation.trim()) : null;
 			const docId = Number(fromToken?.[1] ?? args.docId);
@@ -8570,7 +8896,6 @@ const createKnowledgeFileTools = (host) => [
 		output: jsonOutput,
 		isConcurrencySafe: () => true,
 		execute: async (args) => run(void 0, async () => {
-			await requirePermission(host, "kb:file:read");
 			if (host.outline === void 0) throw new KnowledgeToolError("not-configured", "knowledge outline resolver is unavailable");
 			const rawToken = args.citation ?? args.citationToken ?? "";
 			const fromToken = rawToken.trim() !== "" ? /^kb:\/\/doc\/([^/\s?#]+)(?:\/chunk\/[^/\s?#]+)?/iu.exec(rawToken.trim()) : null;
@@ -8594,7 +8919,6 @@ const createKnowledgeFileTools = (host) => [
 		output: jsonOutput,
 		isConcurrencySafe: () => false,
 		execute: async (args) => run(void 0, async () => {
-			await requirePermission(host, "kb:file:read");
 			if (host.outlineRewrite === void 0) throw new KnowledgeToolError("not-configured", "knowledge outline rewrite is unavailable");
 			const docId = Number(args.docId);
 			if (!Number.isInteger(docId) || docId <= 0) throw new KnowledgeToolError("invalid-citation", "docId must be a positive integer");
@@ -8677,8 +9001,6 @@ const createKnowledgeFileTools = (host) => [
 		},
 		output: jsonOutput,
 		execute: async (args) => run(void 0, async () => {
-			await requirePermission(host, "kb:file:read");
-			await requirePermission(host, "kb:file:write");
 			if (host.outlineSave === void 0) throw new KnowledgeToolError("not-configured", "knowledge outline saver is unavailable");
 			const docId = Number(args.docId);
 			if (!Number.isInteger(docId) || docId <= 0) throw new KnowledgeToolError("invalid-summary", "docId must be a positive integer");
@@ -8708,7 +9030,6 @@ const createKnowledgeFileTools = (host) => [
 		output: jsonOutput,
 		execute: async (args) => run(args.path, async () => {
 			const relPath = assertToolPath(args.path);
-			await requirePermission(host, "kb:file:delete");
 			await requireWrite(host, relPath);
 			const caller = await host.resolveCaller();
 			const entry = await host.statEntry(relPath);
@@ -8737,7 +9058,6 @@ const createKnowledgeFileTools = (host) => [
 		output: jsonOutput,
 		execute: async (args) => run(args.path, async () => {
 			const relPath = assertToolPath(args.path);
-			await requirePermission(host, "kb:file:write");
 			await requireWrite(host, relPath);
 			const caller = await host.resolveCaller();
 			const created = await host.createEntry(relPath, { directory: true });
@@ -8762,7 +9082,6 @@ const createKnowledgeFileTools = (host) => [
 		output: jsonOutput,
 		execute: async (args) => run(args.path, async () => {
 			const relPath = assertToolPath(args.path ?? "", true);
-			await requirePermission(host, "kb:file:extract");
 			const caller = await host.resolveCaller();
 			if (relPath === "") {
 				const candidates = await host.listExtractCandidates(20);
@@ -8989,6 +9308,54 @@ function isTeamDeployment(config) {
 */
 const LOCAL_USER_ID = "local";
 /**
+* The permission context a personal deployment discloses tools from.
+*
+* A personal deployment has no accounts, so there is nobody to ask: the local
+* operator owns every capability the product knows about. Kept as a function rather
+* than the inline object inside the management host so the disclosure coordinator
+* can register the personal tool surface synchronously at startup, instead of
+* waiting for a backend round trip that does not exist.
+*
+* @returns the full-capability context a local owner holds.
+*/
+function localManagementContext() {
+	return {
+		userId: "local",
+		username: "local",
+		displayName: "个人用户",
+		primaryRole: "LOCAL_OWNER",
+		roleCodes: ["LOCAL_OWNER"],
+		permissions: [
+			"kb:file:read",
+			"kb:file:write",
+			"kb:file:delete",
+			"kb:file:extract",
+			"kb:audit:read",
+			"kb:grant:manage",
+			"kb:review:decide",
+			"kb:config:manage",
+			"workflow:read",
+			"workflow:publish",
+			"workflow:manage",
+			"workflow:review:decide",
+			"workflow:review:global"
+		],
+		departmentCode: null,
+		departmentPathCodes: [],
+		dataScope: {
+			all: true,
+			self: true,
+			departmentCodes: []
+		},
+		review: {
+			canReview: true,
+			canReviewGlobal: true,
+			canManagePermissions: true,
+			departments: []
+		}
+	};
+}
+/**
 * Whether a personal deployment may read or write one path.
 *
 * A personal deployment has no OTHER users to protect a path from, so there is no grant to
@@ -10837,6 +11204,24 @@ function knowledgeBaseSkillProvider() {
 		}
 	};
 }
+/**
+* Per-plugin-instance disclosure coordinators, keyed by the Host context.
+*
+* `apply` is synchronous and the Host does not hand a plugin a return value, but
+* the coordinator must be reachable for two legitimate callers: the host integration
+* that wants to force a refresh, and the tests that drive `apply` directly. A
+* WeakMap keeps this a discovery seam rather than a second lifecycle owner.
+*/
+const toolDisclosures = /* @__PURE__ */ new WeakMap();
+/**
+* The permission-based tool disclosure coordinator this plugin instance registered.
+*
+* @param host - the Host context the plugin was applied to.
+* @returns the coordinator, or undefined when this context has no knowledge-base plugin.
+*/
+function knowledgeBaseToolDisclosure(host) {
+	return toolDisclosures.get(host);
+}
 function apply(ctx, deploymentConfig) {
 	const config = deploymentConfig;
 	const host = ctx;
@@ -11037,6 +11422,15 @@ function apply(ctx, deploymentConfig) {
 			...lastFailure === void 0 ? {} : { failure: lastFailure }
 		};
 	};
+	/**
+	* Permission-based tool disclosure, assigned once the host seams exist below.
+	*
+	* Declared before the HTTP surface because the route handler closes over it: the
+	* route gate is one of the two existing places this plugin already reads the
+	* caller's permission context, so it is also where a changed context refreshes the
+	* model-facing tool surface.
+	*/
+	let toolDisclosure;
 	ctx.effect(() => host.webServer.register({
 		kind: "prefix",
 		path: "/knowledge-base/api",
@@ -11049,6 +11443,7 @@ function apply(ctx, deploymentConfig) {
 					const permissionContext = await Promise.race([managementHost.context().catch(() => void 0), new Promise((resolve) => setTimeout(() => {
 						resolve(void 0);
 					}, 750))]);
+					if (permissionContext !== void 0) await toolDisclosure?.syncToolDisclosure(permissionContext);
 					if (permissionContext !== void 0 && permissionContext.permissions.length > 0 && !hasPermission(permissionContext, requiredPermission)) return writeJson(res, 403, {
 						error: `缺少权限 ${requiredPermission}`,
 						code: "forbidden",
@@ -11257,21 +11652,18 @@ function apply(ctx, deploymentConfig) {
 						if (!initializer.hasSucceeded()) await initializer.ensure();
 						const canManage = isTeamDeployment(config) && await canManageGrants(host, config);
 						let permissionKeys = [];
+						let permissionContext;
 						if (isTeamDeployment(config)) try {
-							permissionKeys = [...(await managementHost.context()).permissions];
+							permissionContext = await managementHost.context();
+							permissionKeys = [...permissionContext.permissions];
 						} catch {
 							permissionKeys = [];
 						}
-						else permissionKeys = [
-							"kb:file:read",
-							"kb:file:write",
-							"kb:file:delete",
-							"kb:file:extract",
-							"kb:audit:read",
-							"kb:grant:manage",
-							"kb:review:decide",
-							"kb:config:manage"
-						];
+						else {
+							permissionContext = localManagementContext();
+							permissionKeys = [...permissionContext.permissions];
+						}
+						if (permissionContext !== void 0) await toolDisclosure?.syncToolDisclosure(permissionContext);
 						if (config.storageMode === "local") {
 							const localOnly = await localStatus(config);
 							let localCaller;
@@ -12679,7 +13071,7 @@ function apply(ctx, deploymentConfig) {
 	if (typeof hostWithInject.inject === "function") hostWithInject.inject(["skills"], (scoped) => {
 		scoped.skills.registerProvider(() => knowledgeBaseSkillProvider());
 	});
-	ctx.effect(() => host.tools.register(defineTool({
+	const workflowPublishTool = defineTool({
 		name: "workflow_publish",
 		description: "Publish one workflow from this conversation to the Workflow Plaza. The record is created as PENDING; it does NOT appear in the public plaza until an administrator approves it. 发布后需管理员审核，通过后才出现在广场。Use this only when the user explicitly asks to publish/share the workflow. Do not use it to edit an existing workflow or to run a task now. Provide the standing instruction that will run on the chosen schedule, in the user's language. cronHint should be a 5-field cron expression when the user gave one; category is a short group label.",
 		parameters: {
@@ -12746,8 +13138,7 @@ function apply(ctx, deploymentConfig) {
 		execute: async (args, exec) => {
 			const actor = await resolveWorkflowActor(host, config);
 			const context = await managementHost.context();
-			requirePermission$1(context, "workflow:publish", "workflow_publish");
-			if (args.visibility === "global") requirePermission$1(context, "workflow:review:global", "global workflow publish");
+			if (args.visibility === "global" && !hasPermission(context, "workflow:review:global")) throw new ManagementToolError("forbidden", "缺少权限 workflow:review:global（global workflow publish）");
 			const scope = normalizePublishScope(context, args.visibility, args.departmentCode);
 			const sessionId = exec.agent?.session.id;
 			const result = await publishWorkflow(publishStorePath(publishDirOf(config.publishDir)), {
@@ -12763,7 +13154,7 @@ function apply(ctx, deploymentConfig) {
 				report: `${prefix} 管理员审核通过后才会出现在工作流广场；当前状态：待审核。`
 			};
 		}
-	})), "dsh-knowledge-base: workflow_publish tool");
+	});
 	/** Sidecar path, guarded against living inside the agent-visible tree. */
 	const knowledgeIndexPath = () => {
 		const plan = localConfig(config);
@@ -13111,14 +13502,6 @@ function apply(ctx, deploymentConfig) {
 		}
 	};
 	const knowledgeToolHost = {
-		hasPermission: async (permission) => {
-			if (!isTeamDeployment(config)) return true;
-			try {
-				return (await managementHost.context()).permissions.includes(permission);
-			} catch {
-				return true;
-			}
-		},
 		vectorize: async (input) => {
 			try {
 				await syncKnowledgeIndex(false, false);
@@ -13459,8 +13842,9 @@ function apply(ctx, deploymentConfig) {
 	* Management-tool host.
 	*
 	* Every method reads/writes through the same backend or host primitive the matching
-	* UI surface uses. Role checks happen in the tool layer (which has the review
-	* context); this object does not silently turn a denial into an empty result.
+	* UI surface uses. Role checks happen once at tool disclosure; the context reads
+	* that remain here feed data scoping and audit identity, and the backend still
+	* refuses an operation the caller may not perform.
 	*/
 	const builtInWorkflowRows = [
 		{
@@ -13476,42 +13860,18 @@ function apply(ctx, deploymentConfig) {
 			title: "Archive stale personal documents"
 		}
 	];
+	/**
+	* The acting user id recorded in a management audit line.
+	*
+	* This is identity, not authorization: the permission decision happened at tool
+	* disclosure, and the backend re-checks the write. Reading `/auth/me` instead of
+	* the full review context keeps an audit write from fetching a permission tree it
+	* does not consult.
+	*/
+	const managementActorId = async () => isTeamDeployment(config) ? (await fetchCaller(host, config)).userId : LOCAL_USER_ID;
 	const managementHost = {
 		context: async () => {
-			if (!isTeamDeployment(config)) return {
-				userId: "local",
-				username: "local",
-				displayName: "个人用户",
-				primaryRole: "LOCAL_OWNER",
-				roleCodes: ["LOCAL_OWNER"],
-				permissions: [
-					"kb:file:read",
-					"kb:file:write",
-					"kb:file:delete",
-					"kb:file:extract",
-					"kb:audit:read",
-					"kb:grant:manage",
-					"kb:review:decide",
-					"workflow:read",
-					"workflow:publish",
-					"workflow:manage",
-					"workflow:review:decide",
-					"workflow:review:global"
-				],
-				departmentCode: null,
-				departmentPathCodes: [],
-				dataScope: {
-					all: true,
-					self: true,
-					departmentCodes: []
-				},
-				review: {
-					canReview: true,
-					canReviewGlobal: true,
-					canManagePermissions: true,
-					departments: []
-				}
-			};
+			if (!isTeamDeployment(config)) return localManagementContext();
 			const raw = await request(host, config, "/api/ai/review/context");
 			const dataScope = raw.dataScope ?? {};
 			const review = raw.review ?? {};
@@ -13549,7 +13909,7 @@ function apply(ctx, deploymentConfig) {
 		},
 		kbConfigGet: async () => {
 			const plan = localConfig(config);
-			const actorId = isTeamDeployment(config) ? (await fetchCaller(host, config)).userId : "local";
+			const actorId = await managementActorId();
 			const viewDir = viewPathFor({
 				actualRoot: plan.actualRoot,
 				viewRoot: plan.viewRoot,
@@ -13584,7 +13944,7 @@ function apply(ctx, deploymentConfig) {
 			if (patch.reviewRequired !== void 0) {
 				if (typeof patch.reviewRequired !== "boolean") throw new ManagementToolError("invalid", "reviewRequired must be boolean");
 				const plan = localConfig(config);
-				const actorId = isTeamDeployment(config) ? (await fetchCaller(host, config)).userId : "local";
+				const actorId = await managementActorId();
 				const targetView = viewPathFor({
 					actualRoot: plan.actualRoot,
 					viewRoot: plan.viewRoot,
@@ -13611,7 +13971,7 @@ function apply(ctx, deploymentConfig) {
 			});
 			await appendManagementAudit(config, host, {
 				action: "kb_grant_set",
-				actor: (await managementHost.context()).userId,
+				actor: await managementActorId(),
 				detail: input
 			});
 			return created;
@@ -13645,7 +14005,7 @@ function apply(ctx, deploymentConfig) {
 				await discardPendingWrite(plan.actualRoot, input.name);
 				await appendManagementAudit(config, host, {
 					action: "kb_review_reject",
-					actor: (await managementHost.context()).userId,
+					actor: await managementActorId(),
 					detail: {
 						name: input.name,
 						relPath: submission.relPath,
@@ -13664,7 +14024,7 @@ function apply(ctx, deploymentConfig) {
 			await refreshViewIfStale(true, created.relPath);
 			await appendManagementAudit(config, host, {
 				action: "kb_review_approve",
-				actor: (await managementHost.context()).userId,
+				actor: await managementActorId(),
 				detail: {
 					name: input.name,
 					relPath: submission.relPath,
@@ -13755,7 +14115,7 @@ function apply(ctx, deploymentConfig) {
 			});
 			await appendManagementAudit(config, host, {
 				action: "workflow_update",
-				actor: (await managementHost.context()).userId,
+				actor: await managementActorId(),
 				detail: { id }
 			});
 			return updated;
@@ -13765,7 +14125,7 @@ function apply(ctx, deploymentConfig) {
 			const result = await request(host, config, "/api/ai/workflow-publications/" + encodeURIComponent(id), { method: "DELETE" });
 			await appendManagementAudit(config, host, {
 				action: "workflow_unpublish",
-				actor: (await managementHost.context()).userId,
+				actor: await managementActorId(),
 				detail: { id }
 			});
 			return result;
@@ -13799,8 +14159,30 @@ function apply(ctx, deploymentConfig) {
 			});
 		}
 	};
-	for (const definition of createKnowledgeFileTools(knowledgeToolHost)) ctx.effect(() => host.tools.register(definition), "dsh-knowledge-base: " + definition.name + " tool");
-	for (const definition of createManagementTools(managementHost)) ctx.effect(() => host.tools.register(definition), "dsh-knowledge-base: " + definition.name + " tool");
+	const disclosure = createToolDisclosure({
+		tools: [
+			workflowPublishTool,
+			...createKnowledgeFileTools(knowledgeToolHost),
+			...createManagementTools(managementHost)
+		],
+		registry: { register: (definition) => host.tools.register(definition) },
+		resolveContext: () => managementHost.context(),
+		log: (message) => host.logger?.warn?.("knowledge-base: " + message)
+	});
+	toolDisclosures.set(ctx, disclosure);
+	toolDisclosure = disclosure;
+	ctx.effect(() => () => disclosure.dispose(), "dsh-knowledge-base: permission-based tool disclosure");
+	if (isTeamDeployment(config)) disclosure.syncToolDisclosure();
+	else disclosure.syncToolDisclosure(localManagementContext());
+	const hostWithEvents = host;
+	if (typeof hostWithEvents.on === "function") ctx.effect(() => {
+		const off = hostWithEvents.on?.("credentials/reference-updated", (ref) => {
+			if (ref === config.credentialRef) disclosure.syncToolDisclosure();
+		});
+		return () => {
+			off?.();
+		};
+	}, "dsh-knowledge-base: tool disclosure refresh on credential change");
 	ctx.effect(() => startExternalChangeWatcher({
 		actualRoot: localConfig(config).actualRoot,
 		log: (message) => host.logger?.warn?.("knowledge-base: " + message),
@@ -13844,4 +14226,4 @@ async function executeStep(runner, step, hostId, record) {
 	}
 }
 //#endregion
-export { Config, KB_ROOT_RESOURCE_ID, KB_SUMMARIZE_SKILL_DESCRIPTION, KB_SUMMARIZE_SKILL_NAME, KB_SUMMARIZE_SKILL_RANK, KB_VECTORIZE_SKILL_DESCRIPTION, KB_VECTORIZE_SKILL_NAME, KB_VECTORIZE_SKILL_RANK, KNOWLEDGE_SKILL_DESCRIPTION, KNOWLEDGE_SKILL_INVOCATION, KNOWLEDGE_SKILL_NAME, KNOWLEDGE_SKILL_PROVIDER, KNOWLEDGE_SKILL_RANK, KnowledgeError, KnowledgeWriteError, LOCAL_USER_ID, MAX_KNOWLEDGE_WRITE_BYTES, TEMPLATE_READ_TIMEOUT_MS, actualRelPathForView, apply, canManageGrants, canReadPath, canReviewWorkflows, canWritePath, checkLocalPath, classifyMount, createGrant, createKnowledgeEntry, extractBeside, extractionOutcomeOf, fetchCaller, fetchGrants, fetchPrincipals, inject, isTeamDeployment, kbSummarizeSkillPath, kbVectorizeSkillPath, knowledgeAncestorsFor, knowledgeBaseSkillProvider, knowledgeSkillPath, listDirectory, listDirectoryShapes, listDirectoryWithPermissions, listRelativeFiles, localConfig, localStatus, localStorageRoot, mineruUrlFor, name, permissionForKbRoute, planContext, readAuthorized, readDepartmentOf, readKnowledgeFile, readKnowledgeFileForDownload, readSharedMineruUrl, resolveMineruUrl, resolveWorkflowActor, revokeGrant, searchKnowledge, syncCallerView, tutorialTemplatePath, withLocalStorageRoot, withStoredStorage };
+export { Config, KB_ROOT_RESOURCE_ID, KB_SUMMARIZE_SKILL_DESCRIPTION, KB_SUMMARIZE_SKILL_NAME, KB_SUMMARIZE_SKILL_RANK, KB_VECTORIZE_SKILL_DESCRIPTION, KB_VECTORIZE_SKILL_NAME, KB_VECTORIZE_SKILL_RANK, KNOWLEDGE_SKILL_DESCRIPTION, KNOWLEDGE_SKILL_INVOCATION, KNOWLEDGE_SKILL_NAME, KNOWLEDGE_SKILL_PROVIDER, KNOWLEDGE_SKILL_RANK, KnowledgeError, KnowledgeWriteError, LOCAL_USER_ID, MAX_KNOWLEDGE_WRITE_BYTES, TEMPLATE_READ_TIMEOUT_MS, actualRelPathForView, apply, canManageGrants, canReadPath, canReviewWorkflows, canWritePath, checkLocalPath, classifyMount, createGrant, createKnowledgeEntry, extractBeside, extractionOutcomeOf, fetchCaller, fetchGrants, fetchPrincipals, inject, isTeamDeployment, kbSummarizeSkillPath, kbVectorizeSkillPath, knowledgeAncestorsFor, knowledgeBaseSkillProvider, knowledgeBaseToolDisclosure, knowledgeSkillPath, listDirectory, listDirectoryShapes, listDirectoryWithPermissions, listRelativeFiles, localConfig, localManagementContext, localStatus, localStorageRoot, mineruUrlFor, name, permissionForKbRoute, planContext, readAuthorized, readDepartmentOf, readKnowledgeFile, readKnowledgeFileForDownload, readSharedMineruUrl, resolveMineruUrl, resolveWorkflowActor, revokeGrant, searchKnowledge, syncCallerView, tutorialTemplatePath, withLocalStorageRoot, withStoredStorage };