dsh-permission-rules 0.3.0 → 0.4.0

package/lib/index.js

@@ -563,12 +563,16 @@ function isCatchAll(rule) {
 /**
 * One-line human summary of a compiled rule, for `/rules` output. The
 * 1-based number, action, match dimensions, and reason render first; a
-* disabled marker, tags, and a truncated description follow.
+* disabled marker, tags, and a truncated description follow. When `source`
+* is provided (multi-file chains), the rule's origin file is attributed on
+* the line.
 * @param rule - the compiled rule.
 * @param tokens - dimension-prefix vocabulary for the configured language.
+* @param source - display path of the rule's source file, when the listing
+*   spans several files.
 * @returns a single display line.
 */
-function describeRule(rule, tokens) {
+function describeRule(rule, tokens, source) {
 	const parts = [];
 	if (rule.source.match.tools.length > 0) parts.push(`${tokens.tools}:${rule.source.match.tools.join(",")}`);
 	if (rule.source.match.agents.length > 0) parts.push(`${tokens.agents}:${rule.source.match.agents.join(",")}`);
@@ -581,9 +585,10 @@ function describeRule(rule, tokens) {
 	if (whenParts.length > 0 || platformPart.length > 0) parts.push(`${tokens.when}:${whenParts}${whenParts.length > 0 && platformPart.length > 0 ? " " : ""}${platformPart}`);
 	const match = parts.length > 0 ? `[${parts.join(" ")}]` : `[${tokens.allTools}]`;
 	const disabled = rule.enabled ? "" : ` (${tokens.disabled})`;
+	const sourcePart = source !== void 0 && source.length > 0 ? ` [${tokens.src}:${source}]` : "";
 	const description = rule.description !== void 0 ? ` (${truncate(rule.description, DISPLAY_TRUNCATE)})` : "";
 	const tags = rule.tags.length > 0 ? ` [${tokens.tags}:${rule.tags.join(",")}]` : "";
-	return `${rule.index + 1}. ${rule.action}${disabled} ${match}: ${truncate(rule.reason, DISPLAY_TRUNCATE)}${description}${tags}`;
+	return `${rule.index + 1}. ${rule.action}${disabled} ${match}${sourcePart}: ${truncate(rule.reason, DISPLAY_TRUNCATE)}${description}${tags}`;
 }
 /** Cut a display string at `limit` characters, marking truncation with `…`. */
 function truncate(text, limit) {
@@ -926,7 +931,7 @@ const EN = {
 	lastReloadWarning: (error) => `Warning: the last reload failed (${error}); the rules listed above are the previous ones.`,
 	dryRunNotice: "Dry-run mode (enforce: false): deny/ask hits are audit-logged only — every call is passed through.",
 	unknownArg: (arg) => `Unknown /rules argument "${arg}". ${EN.usage}`,
-	usage: "Usage: /rules [reload | decisions [n] | test <tool> <json-args>]",
+	usage: "Usage: /rules [list | reload | decisions [n] | test <tool> <json-args>]",
 	decisionsHeader: (shown, total) => `Last ${shown} of ${total} permission decision(s) for this session:`,
 	noDecisions: "No permission decisions recorded in this session yet.",
 	invalidDecisionsCount: (arg) => `Invalid decisions count "${arg}": give a positive integer (default 10).`,
@@ -938,7 +943,8 @@ const EN = {
 	testBadJson: (text) => `Invalid JSON arguments "${text}": the arguments must parse as JSON.`,
 	testUnknownFlag: (flag) => `Unknown /rules test flag "${flag}". ${EN.testUsage}`,
 	testBadFlag: (flag) => `Invalid /rules test flag "${flag}": expected a value. ${EN.testUsage}`,
-	testUsage: "Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... <tool> <json-args>, e.g. /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `Unknown platform "${value}" in --platform: expected one of aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${EN.testUsage}`,
+	testUsage: "Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... [--platform <name>] <tool> <json-args>, e.g. /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `Warning: rule${numbers.length > 1 ? "s" : ""} ${numbers.join(", ")} ${numbers.length > 1 ? "are" : "is"} unreachable (shadowed by an earlier catch-all rule).`,
 	emptySource: "(no rule file — empty rule set)"
 };
@@ -951,7 +957,7 @@ const ZH = {
 	lastReloadWarning: (error) => `警告：上次重载失败（${error}）；以上列出的是之前的规则。`,
 	dryRunNotice: "干跑模式（enforce: false）：deny/ask 命中仅写入审计日志——所有调用照常透传。",
 	unknownArg: (arg) => `未知的 /rules 参数 "${arg}"。${ZH.usage}`,
-	usage: "用法：/rules [reload | decisions [n] | test <工具名> <json-参数>]",
+	usage: "用法：/rules [list | reload | decisions [n] | test <工具名> <json-参数>]",
 	decisionsHeader: (shown, total) => `本会话最近 ${shown}/${total} 条权限裁决：`,
 	noDecisions: "本会话还没有记录任何权限裁决。",
 	invalidDecisionsCount: (arg) => `无效的裁决条数 "${arg}"：请给正整数（默认 10）。`,
@@ -963,7 +969,8 @@ const ZH = {
 	testBadJson: (text) => `无效的 JSON 参数 "${text}"：参数必须能被解析为 JSON。`,
 	testUnknownFlag: (flag) => `未知的 /rules test 标志 "${flag}"。${ZH.testUsage}`,
 	testBadFlag: (flag) => `无效的 /rules test 标志 "${flag}"：缺少取值。${ZH.testUsage}`,
-	testUsage: "用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... <工具名> <json-参数>，例如 /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `未知的平台 "${value}"（--platform）：应为 aix、android、darwin、freebsd、linux、openbsd、sunos、win32 之一。${ZH.testUsage}`,
+	testUsage: "用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... [--platform <平台名>] <工具名> <json-参数>，例如 /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `警告：规则 ${numbers.join("、")} 不可达（被前面的通配规则遮蔽）。`,
 	emptySource: "（无规则文件——空规则集）"
 };
@@ -976,7 +983,7 @@ const ES = {
 	lastReloadWarning: (error) => `Aviso: la última recarga falló (${error}); las reglas mostradas son las anteriores.`,
 	dryRunNotice: "Modo simulación (enforce: false): los aciertos deny/ask solo se registran en auditoría — todas las llamadas pasan.",
 	unknownArg: (arg) => `Argumento de /rules desconocido "${arg}". ${ES.usage}`,
-	usage: "Uso: /rules [reload | decisions [n] | test <herramienta> <json-args>]",
+	usage: "Uso: /rules [list | reload | decisions [n] | test <herramienta> <json-args>]",
 	decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisión(es) de permiso de esta sesión:`,
 	noDecisions: "Esta sesión aún no registra decisiones de permiso.",
 	invalidDecisionsCount: (arg) => `Cantidad de decisiones inválida "${arg}": indique un entero positivo (por defecto 10).`,
@@ -988,7 +995,8 @@ const ES = {
 	testBadJson: (text) => `Argumentos JSON inválidos "${text}": los argumentos deben poderse analizar como JSON.`,
 	testUnknownFlag: (flag) => `Bandera de /rules test desconocida "${flag}". ${ES.testUsage}`,
 	testBadFlag: (flag) => `Bandera de /rules test inválida "${flag}": falta un valor. ${ES.testUsage}`,
-	testUsage: "Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... <herramienta> <json-args>, p. ej. /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `Plataforma desconocida "${value}" en --platform: se esperaba una de aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${ES.testUsage}`,
+	testUsage: "Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... [--platform <nombre>] <herramienta> <json-args>, p. ej. /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `Aviso: ${numbers.length > 1 ? "las reglas" : "la regla"} ${numbers.join(", ")} ${numbers.length > 1 ? "son inalcanzables" : "es inalcanzable"} (tapada por una regla general anterior).`,
 	emptySource: "(sin archivo de reglas — conjunto vacío)"
 };
@@ -1001,7 +1009,7 @@ const PT = {
 	lastReloadWarning: (error) => `Aviso: a última recarga falhou (${error}); as regras listadas são as anteriores.`,
 	dryRunNotice: "Modo simulação (enforce: false): acertos deny/ask são apenas registrados na auditoria — todas as chamadas passam.",
 	unknownArg: (arg) => `Argumento de /rules desconhecido "${arg}". ${PT.usage}`,
-	usage: "Uso: /rules [reload | decisions [n] | test <ferramenta> <json-args>]",
+	usage: "Uso: /rules [list | reload | decisions [n] | test <ferramenta> <json-args>]",
 	decisionsHeader: (shown, total) => `Últimas ${shown} de ${total} decisão(ões) de permissão desta sessão:`,
 	noDecisions: "Esta sessão ainda não registrou decisões de permissão.",
 	invalidDecisionsCount: (arg) => `Quantidade de decisões inválida "${arg}": informe um inteiro positivo (padrão 10).`,
@@ -1013,7 +1021,8 @@ const PT = {
 	testBadJson: (text) => `Argumentos JSON inválidos "${text}": os argumentos precisam ser JSON analisável.`,
 	testUnknownFlag: (flag) => `Sinalizador de /rules test desconhecido "${flag}". ${PT.testUsage}`,
 	testBadFlag: (flag) => `Sinalizador de /rules test inválido "${flag}": falta um valor. ${PT.testUsage}`,
-	testUsage: "Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... <ferramenta> <json-args>, ex.: /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `Plataforma desconhecida "${value}" em --platform: esperava-se uma de aix, android, darwin, freebsd, linux, openbsd, sunos, win32. ${PT.testUsage}`,
+	testUsage: "Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... [--platform <nome>] <ferramenta> <json-args>, ex.: /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `Aviso: ${numbers.length > 1 ? "as regras" : "a regra"} ${numbers.join(", ")} ${numbers.length > 1 ? "são inalcançáveis" : "é inalcançável"} (encoberta por uma regra geral anterior).`,
 	emptySource: "(sem arquivo de regras — conjunto vazio)"
 };
@@ -1026,7 +1035,7 @@ const HI = {
 	lastReloadWarning: (error) => `चेतावनी: अंतिम पुनः लोड विफल रहा (${error}); ऊपर सूचीबद्ध नियम पिछले वाले हैं।`,
 	dryRunNotice: "ड्राई-रन मोड (enforce: false): deny/ask हिट केवल ऑडिट में दर्ज होते हैं — हर कॉल पास हो जाती है।",
 	unknownArg: (arg) => `अज्ञात /rules तर्क "${arg}"। ${HI.usage}`,
-	usage: "उपयोग: /rules [reload | decisions [n] | test <टूल> <json-args>]",
+	usage: "उपयोग: /rules [list | reload | decisions [n] | test <टूल> <json-args>]",
 	decisionsHeader: (shown, total) => `इस सत्र के अंतिम ${shown}/${total} अनुमति निर्णय:`,
 	noDecisions: "इस सत्र में अभी कोई अनुमति निर्णय दर्ज नहीं है।",
 	invalidDecisionsCount: (arg) => `अमान्य निर्णय-संख्या "${arg}": एक धनात्मक पूर्णांक दें (डिफ़ॉल्ट 10)।`,
@@ -1038,7 +1047,8 @@ const HI = {
 	testBadJson: (text) => `अमान्य JSON तर्क "${text}": तर्क JSON के रूप में पार्स होने चाहिए।`,
 	testUnknownFlag: (flag) => `अज्ञात /rules test फ़्लैग "${flag}"। ${HI.testUsage}`,
 	testBadFlag: (flag) => `अमान्य /rules test फ़्लैग "${flag}": मान गायब है। ${HI.testUsage}`,
-	testUsage: "उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... <टूल> <json-args>, जैसे /rules test bash {\"command\":\"git push origin main\"}",
+	testBadPlatform: (value) => `अज्ञात प्लेटफ़ॉर्म "${value}" (--platform): aix, android, darwin, freebsd, linux, openbsd, sunos, win32 में से एक अपेक्षित। ${HI.testUsage}`,
+	testUsage: "उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... [--platform <नाम>] <टूल> <json-args>, जैसे /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `चेतावनी: नियम ${numbers.join(", ")} अप्राप्य हैं (पहले वाले सर्व-मिलान नियम से ढके हुए)।`,
 	emptySource: "(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)"
 };
@@ -1062,7 +1072,8 @@ const DESCRIBE_TOKENS = {
 		when: "when",
 		platform: "platform",
 		disabled: "disabled",
-		tags: "tags"
+		tags: "tags",
+		src: "src"
 	},
 	zh: {
 		allTools: "全部工具",
@@ -1074,7 +1085,8 @@ const DESCRIBE_TOKENS = {
 		when: "条件",
 		platform: "平台",
 		disabled: "已禁用",
-		tags: "标签"
+		tags: "标签",
+		src: "来源"
 	},
 	es: {
 		allTools: "todas las herramientas",
@@ -1086,7 +1098,8 @@ const DESCRIBE_TOKENS = {
 		when: "cuándo",
 		platform: "plataforma",
 		disabled: "deshabilitada",
-		tags: "etiquetas"
+		tags: "etiquetas",
+		src: "origen"
 	},
 	pt: {
 		allTools: "todas as ferramentas",
@@ -1098,7 +1111,8 @@ const DESCRIBE_TOKENS = {
 		when: "quando",
 		platform: "plataforma",
 		disabled: "desativada",
-		tags: "etiquetas"
+		tags: "etiquetas",
+		src: "origem"
 	},
 	hi: {
 		allTools: "सभी टूल",
@@ -1110,7 +1124,8 @@ const DESCRIBE_TOKENS = {
 		when: "शर्त",
 		platform: "प्लेटफ़ॉर्म",
 		disabled: "अक्षम",
-		tags: "टैग"
+		tags: "टैग",
+		src: "स्रोत"
 	}
 };
 //#endregion
@@ -1122,7 +1137,9 @@ const DESCRIBE_TOKENS = {
 * deny/ask decision (and NEVER short-circuits on allow or passthrough),
 * the `permissionRules/decision` audit event, the `/rules` session command
 * (`list | reload | decisions [n] | test [flags] <tool> <json>`), and
-* Chokidar-driven reloads. Every registration is an effect.
+* Chokidar-driven reloads (effective rule files plus candidate watches on
+* expected-but-absent files, so mid-session creation is adopted). Every
+* registration is an effect.
 * @module dsh-permission-rules/runtime
 */
 /**
@@ -1134,7 +1151,7 @@ var PermissionRulesRuntime = class {
 	config;
 	/** Loaded (or failed) rules per workspace cwd, least-recently-used first for eviction. */
 	byCwd = /* @__PURE__ */ new Map();
-	/** Live watchers per rule-file path, with the cwds each serves. */
+	/** Live watchers per watched path (rule file or candidate ancestor directory), with the cwds each serves. */
 	watchers = /* @__PURE__ */ new Map();
 	/** Debounce timers per rule-file path. */
 	timers = /* @__PURE__ */ new Map();
@@ -1232,6 +1249,17 @@ var PermissionRulesRuntime = class {
 		}
 	}
 	/**
+	* Canonical per-workspace cache key: the resolved root, case-folded on
+	* Windows so differently-spelled paths to the same workspace share one
+	* cache entry and one watcher set instead of doubling both.
+	* @param cwd - the session's absolute workspace root.
+	* @returns the canonical key.
+	*/
+	cacheKey(cwd) {
+		const resolved = resolve(cwd);
+		return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	}
+	/**
 	* The rules in effect for one cwd, loading on first use. Under
 	* `badFilePolicy: 'fail'` a bad initial load throws on EVERY use (the
 	* pending tool call errors loudly) while the watcher keeps observing the
@@ -1242,23 +1270,24 @@ var PermissionRulesRuntime = class {
 	* @returns the loaded rules.
 	*/
 	rulesFor(cwd) {
-		const existing = this.byCwd.get(cwd);
+		const key = this.cacheKey(cwd);
+		const existing = this.byCwd.get(key);
 		if (existing !== void 0) {
 			if (existing.failed === true) throw new RuleError(existing.lastError ?? `rule load failed for ${cwd}`);
-			this.byCwd.delete(cwd);
-			this.byCwd.set(cwd, existing);
+			this.byCwd.delete(key);
+			this.byCwd.set(key, existing);
 			return existing;
 		}
-		this.evictIfFull(cwd);
+		this.evictIfFull(key);
 		try {
 			const loaded = this.load(cwd);
-			this.byCwd.set(cwd, loaded);
-			this.reconcileWatch(cwd, loaded.sources);
+			this.byCwd.set(key, loaded);
+			this.reconcileWatch(key, loaded.sources);
 			return loaded;
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			const sources = this.resolveSources(cwd);
-			this.byCwd.set(cwd, {
+			this.byCwd.set(key, {
 				cwd,
 				sources,
 				compiled: {
@@ -1268,7 +1297,7 @@ var PermissionRulesRuntime = class {
 				lastError: message,
 				failed: true
 			});
-			this.reconcileWatch(cwd, sources);
+			this.reconcileWatch(key, sources);
 			throw error;
 		}
 	}
@@ -1280,29 +1309,34 @@ var PermissionRulesRuntime = class {
 	* @param cwd - the workspace root.
 	*/
 	reload(cwd) {
-		const previous = this.byCwd.get(cwd);
+		const key = this.cacheKey(cwd);
+		const previous = this.byCwd.get(key);
 		try {
 			const loaded = this.load(cwd);
-			this.byCwd.set(cwd, loaded);
-			this.reconcileWatch(cwd, loaded.sources);
+			this.byCwd.set(key, loaded);
+			this.reconcileWatch(key, loaded.sources);
 			this.ctx.logger.info(`permission-rules: reloaded ${loaded.compiled.rules.length} rule(s) from ${loaded.sources.join(", ") || "(empty rule set)"} for ${cwd}`);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
 			this.ctx.logger.warn(`permission-rules: reload failed for ${cwd}: ${message} (keeping previous rules)`);
-			if (previous !== void 0) this.byCwd.set(cwd, {
+			if (previous !== void 0) this.byCwd.set(key, {
 				...previous,
 				lastError: message
 			});
-			else this.byCwd.set(cwd, {
-				cwd,
-				sources: this.resolveSources(cwd),
-				compiled: {
-					rules: [],
-					caseInsensitivePaths: this.config.caseInsensitivePaths
-				},
-				lastError: message,
-				failed: true
-			});
+			else {
+				const sources = this.resolveSources(cwd);
+				this.byCwd.set(key, {
+					cwd,
+					sources,
+					compiled: {
+						rules: [],
+						caseInsensitivePaths: this.config.caseInsensitivePaths
+					},
+					lastError: message,
+					failed: true
+				});
+				this.reconcileWatch(key, sources);
+			}
 		}
 	}
 	/**
@@ -1418,7 +1452,7 @@ var PermissionRulesRuntime = class {
 				text: prose.unknownArg(invocation.rawInput.trim())
 			};
 			this.reload(cwd);
-			const reloaded = this.byCwd.get(cwd);
+			const reloaded = this.byCwd.get(this.cacheKey(cwd));
 			if (reloaded?.lastError !== void 0) return {
 				kind: "error",
 				text: prose.reloadFailed(reloaded.lastError)
@@ -1430,6 +1464,10 @@ var PermissionRulesRuntime = class {
 				text: prose.reloaded(rules.length, source)
 			};
 		}
+		if (verb === "list" && rest.length > 0) return {
+			kind: "error",
+			text: prose.unknownArg(invocation.rawInput.trim())
+		};
 		if (verb === "decisions") {
 			if (rest.length > 1) return {
 				kind: "error",
@@ -1447,7 +1485,7 @@ var PermissionRulesRuntime = class {
 			return this.decisionsCommand(invocation, count, prose);
 		}
 		if (verb === "test") return this.testCommand(raw, verbRaw ?? "", invocation, cwd, prose);
-		if (verb !== "") return {
+		if (verb !== "" && verb !== "list") return {
 			kind: "error",
 			text: prose.unknownArg(invocation.rawInput.trim())
 		};
@@ -1464,7 +1502,8 @@ var PermissionRulesRuntime = class {
 		if (loaded.sources.length === 0) lines.push(prose.noRules(cwd, this.config.fallbackPath !== void 0 ? prose.fallbackMissing : ""));
 		else {
 			lines.push(prose.rulesHeader(loaded.compiled.rules.length, loaded.sources, cwd));
-			lines.push(...loaded.compiled.rules.map((rule) => describeRule(rule, DESCRIBE_TOKENS[this.config.language])));
+			const multiSource = loaded.sources.length > 1;
+			lines.push(...loaded.compiled.rules.map((rule) => describeRule(rule, DESCRIBE_TOKENS[this.config.language], multiSource ? this.displaySource(loaded.sources[rule.sourceIndex] ?? "", cwd) : void 0)));
 			const unreachable = findUnreachableRules(loaded.compiled);
 			if (unreachable.length > 0) lines.push(prose.unreachableWarning(unreachable.map((index) => index + 1)));
 		}
@@ -1480,9 +1519,11 @@ var PermissionRulesRuntime = class {
 	* Execute `/rules test` with optional leading flags: `--cwd <dir>`
 	* evaluates against that workspace (rule discovery AND path
 	* normalization), `--env KEY=VALUE` (repeatable) overrides host env for
-	* `when.env` matching, and `--agent <selector>` (repeatable) supplies
-	* agent-identity candidates for the `agents` dimension. The JSON
-	* argument tail is kept verbatim, so quoted JSON survives unchanged.
+	* `when.env` matching, `--agent <selector>` (repeatable) supplies
+	* agent-identity candidates for the `agents` dimension, and
+	* `--platform <name>` overrides the host platform for `when.platform`.
+	* The JSON argument tail is kept verbatim, so quoted JSON survives
+	* unchanged.
 	* @param raw - the full raw command input.
 	* @param verbRaw - the verb as typed.
 	* @param invocation - the received command invocation (session agent).
@@ -1495,6 +1536,7 @@ var PermissionRulesRuntime = class {
 		const envOverrides = {};
 		const agentSelectors = [];
 		let testCwd;
+		let testPlatform;
 		let parsed = nextToken(rest);
 		while (parsed !== void 0 && parsed.token.startsWith("--")) {
 			const flag = parsed.token;
@@ -1512,7 +1554,13 @@ var PermissionRulesRuntime = class {
 				};
 				envOverrides[value.token.slice(0, equals)] = value.token.slice(equals + 1);
 			} else if (flag === "--agent") agentSelectors.push(value.token);
-			else return {
+			else if (flag === "--platform") {
+				if (!PLATFORMS.includes(value.token)) return {
+					kind: "error",
+					text: prose.testBadPlatform(value.token)
+				};
+				testPlatform = value.token;
+			} else return {
 				kind: "error",
 				text: prose.testUnknownFlag(flag)
 			};
@@ -1545,7 +1593,7 @@ var PermissionRulesRuntime = class {
 			};
 		}
 		const context = {
-			platform: process.platform,
+			platform: testPlatform ?? process.platform,
 			env: Object.keys(envOverrides).length === 0 ? process.env : {
 				...process.env,
 				...envOverrides
@@ -1558,6 +1606,12 @@ var PermissionRulesRuntime = class {
 			text: hit === void 0 ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason)
 		};
 	}
+	/** Render one rule-file source for per-rule attribution: workspace-relative when inside the cwd, raw otherwise. */
+	displaySource(source, cwd) {
+		if (source.length === 0) return "";
+		const relative = normalizeWorkspacePath(cwd, source, this.config.caseInsensitivePaths);
+		return relative.length > 0 ? relative : source;
+	}
 	/** Render the session's `permissionRules/decision` audit trail, newest last. */
 	decisionsCommand(invocation, count, prose) {
 		const decisions = invocation.agent.session.events.filter((event) => event.type === "permissionRules/decision");
@@ -1642,16 +1696,97 @@ var PermissionRulesRuntime = class {
 	* Rebind `cwd` to its current rule-source chain. When a concrete source
 	* left the chain (deleted file, fallback switch), detach the workspace
 	* from watchers serving other sources and close the ones left empty, so
-	* long-running hosts cannot accumulate stale watchers. An empty chain (no
-	* rule file in effect) keeps the previous watchers alive: they own the
-	* "file recreated → adopted" signal, and the workspace-cache bound keeps
-	* the set of such watchers finite.
+	* long-running hosts cannot accumulate stale watchers. Expected-but-absent
+	* rule files (the project file when it is not effective, and a configured
+	* fallback that does not exist) are covered by candidate watchers on
+	* their deepest existing ancestor directory, so a file created
+	* mid-session is adopted without a manual `/rules reload`. With
+	* `searchUp`, only the immediate cwd-level candidate is watched —
+	* deeper ancestors are discovered on the next load.
 	*/
 	reconcileWatch(cwd, sources) {
-		if (sources.length === 0) return;
-		for (const [watchedSource, entry] of this.watchers) if (!sources.includes(watchedSource)) entry.cwds.delete(cwd);
+		for (const [watchedSource, entry] of this.watchers) if (!sources.includes(watchedSource)) {
+			entry.cwds.delete(cwd);
+			entry.candidates?.delete(cwd);
+		}
 		this.pruneWatchers();
 		for (const source of sources) this.attachWatch(cwd, source);
+		for (const candidate of this.candidateSources(cwd)) {
+			if (sources.includes(candidate) || existsSync(candidate)) continue;
+			this.attachCandidateWatch(cwd, candidate);
+		}
+	}
+	/**
+	* The rule-file paths a workspace COULD be served by: the project file
+	* (an absolute `rulesFile`, or `<cwd>/<rulesFile>` — the immediate level
+	* only under `searchUp`) plus the configured fallback.
+	*/
+	candidateSources(cwd) {
+		const candidates = [isAbsolute(this.config.rulesFile) ? this.config.rulesFile : join(cwd, this.config.rulesFile)];
+		const fallback = this.config.fallbackPath;
+		if (fallback !== void 0) candidates.push(isAbsolute(fallback) ? fallback : resolve(fallback));
+		return candidates;
+	}
+	/**
+	* Watch one expected-but-absent rule file through its deepest existing
+	* ancestor directory. Chokidar cannot reliably watch a missing path when
+	* its parent is also missing, but directory watching is dependable; every
+	* relevant event re-checks existence and only triggers a reload once the
+	* candidate actually appeared, so unrelated workspace activity while the
+	* file is absent costs a stat, not a reload.
+	*/
+	attachCandidateWatch(cwd, candidate) {
+		if (!this.config.watch) return;
+		const dir = this.deepestExistingDir(dirname(candidate));
+		const existing = this.watchers.get(dir);
+		if (existing !== void 0) {
+			existing.cwds.add(cwd);
+			existing.candidates?.set(cwd, candidate);
+			return;
+		}
+		const cwds = /* @__PURE__ */ new Set([cwd]);
+		const candidates = /* @__PURE__ */ new Map([[cwd, candidate]]);
+		const watcher = chokidar.watch(dir, {
+			persistent: true,
+			ignoreInitial: true
+		});
+		const onEvent = () => this.scheduleReload(dir);
+		watcher.on("add", onEvent);
+		watcher.on("addDir", onEvent);
+		watcher.on("change", onEvent);
+		watcher.on("unlink", onEvent);
+		watcher.on("unlinkDir", onEvent);
+		watcher.on("error", (error) => {
+			this.ctx.logger.warn(`permission-rules: watcher error on ${dir}: ${String(error)}`);
+		});
+		this.watchers.set(dir, {
+			cwds,
+			candidates,
+			close: () => {
+				watcher.close().catch((error) => {
+					this.ctx.logger.warn(`permission-rules: failed to close watcher on ${dir}: ${String(error)}`);
+				});
+			}
+		});
+		this.ctx.effect(() => () => {
+			this.watchers.get(dir)?.close();
+			this.watchers.delete(dir);
+			const timer = this.timers.get(dir);
+			if (timer !== void 0) {
+				clearTimeout(timer);
+				this.timers.delete(dir);
+			}
+		});
+	}
+	/** The deepest existing ancestor directory of `dir` (candidate watchers target directories, never missing files). */
+	deepestExistingDir(dir) {
+		let current = dir;
+		for (;;) {
+			if (existsSync(current)) return current;
+			const parent = dirname(current);
+			if (parent === current) return current;
+			current = parent;
+		}
 	}
 	/** Close and drop watchers whose workspace sets are empty, clearing their debounce timers. */
 	pruneWatchers() {
@@ -1678,7 +1813,10 @@ var PermissionRulesRuntime = class {
 		const oldest = this.byCwd.keys().next().value;
 		if (oldest === void 0) return;
 		this.byCwd.delete(oldest);
-		for (const entry of this.watchers.values()) entry.cwds.delete(oldest);
+		for (const entry of this.watchers.values()) {
+			entry.cwds.delete(oldest);
+			entry.candidates?.delete(oldest);
+		}
 		this.pruneWatchers();
 	}
 	/** Number of live watchers, for observability and tests. */
@@ -1689,13 +1827,24 @@ var PermissionRulesRuntime = class {
 	pendingReloadCount() {
 		return this.timers.size;
 	}
-	/** Debounce watch events into one reload per stability window. */
+	/**
+	* Debounce watch events into one reload per stability window. A
+	* candidate (directory) watcher only reloads a cwd once its expected
+	* file actually exists — unrelated events while the file is absent are
+	* dropped before any re-read.
+	*/
 	scheduleReload(source) {
 		const existing = this.timers.get(source);
 		if (existing !== void 0) clearTimeout(existing);
 		const timer = setTimeout(() => {
 			this.timers.delete(source);
-			for (const cwd of this.watchers.get(source)?.cwds ?? []) this.reload(cwd);
+			const entry = this.watchers.get(source);
+			if (entry === void 0) return;
+			for (const cwd of entry.cwds) {
+				const candidate = entry.candidates?.get(cwd);
+				if (candidate !== void 0 && !existsSync(candidate)) continue;
+				this.reload(cwd);
+			}
 		}, this.config.watchStabilityThresholdMs);
 		this.timers.set(source, timer);
 	}
@@ -1714,7 +1863,7 @@ function apply(ctx, config) {
 	ctx.commands.register({
 		name: "rules",
 		description: "list, reload, audit, or dry-test the active permission rules for this workspace",
-		input: { hint: "[reload | decisions [n] | test [--cwd <dir>] [--env K=V] [--agent <sel>] <tool> <json-args>]" },
+		input: { hint: "[list | reload | decisions [n] | test [--cwd <dir>] [--env K=V] [--agent <sel>] [--platform <name>] <tool> <json-args>]" },
 		handler: (invocation) => runtime.command(invocation)
 	});
 }

package/lib/types/prose.d.ts

@@ -46,6 +46,8 @@ export interface UiProse {
     testUnknownFlag: (flag: string) => string;
     /** Rejection of a malformed `/rules test` flag (missing value, bad KEY=VALUE). */
     testBadFlag: (flag: string) => string;
+    /** Rejection of an unknown `--platform` value. */
+    testBadPlatform: (value: string) => string;
     /** Usage hint of `/rules test`. */
     testUsage: string;
     /** Warning naming shadowed (unreachable) rules by 1-based number. */
@@ -65,6 +67,8 @@ export interface DescribeTokens {
     platform: string;
     disabled: string;
     tags: string;
+    /** Prefix of the per-rule source-file attribution. */
+    src: string;
 }
 /** The localized prose tables by language. */
 export declare const UI_PROSE: Readonly<Record<UiLanguage, UiProse>>;

package/lib/types/prose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prose.d.ts","sourceRoot":"","sources":["../../src/prose.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prose.d.ts","sourceRoot":"","sources":["../../src/prose.ts"],"names":[],"mappings":"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"}