dsh-permission-rules 0.2.0 → 0.4.0

package/lib/index.js

@@ -31,13 +31,16 @@ const Config = z.object({
 	caseInsensitivePaths: z.boolean().default(process.platform === "win32"),
 	audit: z.union(["all", "hits"]).default("all"),
 	searchUp: z.boolean().default(false),
-	maxGlobStars: z.number().default(2)
+	maxGlobStars: z.number().default(2),
+	enforce: z.boolean().default(true)
 });
 /**
 * Validate raw values and fill explicit defaults. A `maxRules`,
 * `maxCachedWorkspaces`, or `maxGlobStars` that is not a positive safe
-* integer, a non-positive stability window, or `searchUp` combined with an
-* absolute `rulesFile` throws here — misconfiguration fails loud at mount.
+* integer, a non-positive stability window, `searchUp` combined with an
+* absolute `rulesFile`, a value outside a closed enum, or a non-boolean
+* flag throws here — misconfiguration fails loud at mount even when the
+* plugin is mounted without the Schemastery loader.
 * @param config - raw (possibly partial) plugin config.
 * @returns the fully resolved config.
 */
@@ -53,6 +56,20 @@ function resolveConfig(config = {}) {
 	if (!Number.isSafeInteger(maxCachedWorkspaces) || maxCachedWorkspaces <= 0) throw new TypeError(`maxCachedWorkspaces must be a positive safe integer, got ${String(config.maxCachedWorkspaces)}`);
 	const maxGlobStars = config.maxGlobStars ?? 2;
 	if (!Number.isSafeInteger(maxGlobStars) || maxGlobStars <= 0) throw new TypeError(`maxGlobStars must be a positive safe integer, got ${String(config.maxGlobStars)}`);
+	assertEnum("badFilePolicy", config.badFilePolicy ?? "fail", ["fail", "ignore-with-warning"]);
+	assertEnum("patternMode", config.patternMode ?? "glob", ["glob", "regex"]);
+	assertEnum("language", config.language ?? "en", [
+		"en",
+		"zh",
+		"es",
+		"pt",
+		"hi"
+	]);
+	assertEnum("audit", config.audit ?? "all", ["all", "hits"]);
+	assertBoolean("watch", config.watch ?? true);
+	assertBoolean("searchUp", searchUp);
+	assertBoolean("caseInsensitivePaths", config.caseInsensitivePaths ?? process.platform === "win32");
+	assertBoolean("enforce", config.enforce ?? true);
 	return {
 		rulesFile,
 		fallbackPath: config.fallbackPath,
@@ -66,9 +83,18 @@ function resolveConfig(config = {}) {
 		caseInsensitivePaths: config.caseInsensitivePaths ?? process.platform === "win32",
 		audit: config.audit ?? "all",
 		searchUp,
-		maxGlobStars
+		maxGlobStars,
+		enforce: config.enforce ?? true
 	};
 }
+/** Throw unless `key` is one of `allowed` (TypeScript's closed enums are not runtime checks). */
+function assertEnum(key, value, allowed) {
+	if (!allowed.includes(value)) throw new TypeError(`${key} must be one of ${allowed.map((item) => JSON.stringify(item)).join(" | ")}, got ${JSON.stringify(value)}`);
+}
+/** Throw unless `key` is a boolean (plain-JS mounts bypass the Schemastery coercion). */
+function assertBoolean(key, value) {
+	if (typeof value !== "boolean") throw new TypeError(`${key} must be a boolean, got ${typeof value}`);
+}
 //#endregion
 //#region src/glob.ts
 /**
@@ -455,6 +481,7 @@ function compileRulesChain(entries, options) {
 /** Compile one parsed rule into its hot-path form. */
 function compileRule(entry, index, sourceIndex, options) {
 	const tools = entry.match.tools.map((pattern) => compileToolPattern(pattern, options.maxGlobStars));
+	const agents = entry.match.agents.map((pattern) => compileToolPattern(pattern, options.maxGlobStars));
 	const params = /* @__PURE__ */ new Map();
 	for (const [key, patterns] of Object.entries(entry.match.params)) params.set(key, compileParamPatterns(key, patterns, options));
 	const paths = entry.match.paths.map((pattern) => compilePathPattern(pattern, options));
@@ -469,6 +496,7 @@ function compileRule(entry, index, sourceIndex, options) {
 		...entry.description !== void 0 ? { description: entry.description } : {},
 		tags: entry.tags,
 		tools,
+		agents,
 		params,
 		paths,
 		absent: entry.match.absent,
@@ -496,6 +524,7 @@ function matchRules(ruleset, toolName, args, cwd, context = {}) {
 	for (const rule of ruleset.rules) {
 		if (!rule.enabled) continue;
 		if (!matchTools(rule, toolName)) continue;
+		if (!matchAgents(rule, context)) continue;
 		if (!matchWhen(rule, context)) continue;
 		if (rule.params.size > 0 && (argRecord === void 0 || !matchParams(rule, argRecord))) continue;
 		if (rule.absent.length > 0 && !matchAbsent(rule, argRecord)) continue;
@@ -529,19 +558,24 @@ function findUnreachableRules(ruleset) {
 }
 /** Whether every match dimension of one rule is empty. */
 function isCatchAll(rule) {
-	return rule.tools.length === 0 && rule.params.size === 0 && rule.paths.length === 0 && rule.absent.length === 0 && rule.when === void 0;
+	return rule.tools.length === 0 && rule.agents.length === 0 && rule.params.size === 0 && rule.paths.length === 0 && rule.absent.length === 0 && rule.when === void 0;
 }
 /**
 * 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(",")}`);
 	const params = Object.entries(rule.source.match.params).map(([key, patterns]) => `${key}=${patterns.join("|")}`).join(" ");
 	if (params.length > 0) parts.push(`${tokens.params}:${params}`);
 	if (rule.source.match.paths.length > 0) parts.push(`${tokens.paths}:${rule.source.match.paths.join(",")}`);
@@ -551,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) {
@@ -564,6 +599,18 @@ function matchTools(rule, toolName) {
 	if (rule.tools.length === 0) return true;
 	return rule.tools.some((regex) => regex.test(toolName));
 }
+/**
+* Whether a rule's agents dimension selects the caller. Any selector glob
+* matching any identity candidate satisfies the dimension; unknown
+* identity (no agent or no candidates) fails the dimension, so an
+* agent-scoped rule can never fire where the caller cannot be identified.
+*/
+function matchAgents(rule, context) {
+	if (rule.agents.length === 0) return true;
+	const candidates = context.agents;
+	if (candidates === void 0 || candidates.length === 0) return false;
+	return rule.agents.some((regex) => candidates.some((candidate) => regex.test(candidate)));
+}
 /** Whether a rule's params dimension holds: EVERY key present and matching. */
 function matchParams(rule, args) {
 	for (const [key, { positive, negative }] of rule.params) {
@@ -675,6 +722,7 @@ function parseRuleEntry(raw, index) {
 function parseMatch(raw, at) {
 	if (raw === void 0) return {
 		tools: [],
+		agents: [],
 		params: {},
 		paths: [],
 		absent: [],
@@ -684,10 +732,11 @@ function parseMatch(raw, at) {
 		}
 	};
 	const record = asRecord(raw, `${at}.match`);
-	const unknownFields = Object.keys(record).filter((key) => key !== "tools" && key !== "params" && key !== "paths" && key !== "absent" && key !== "when");
-	if (unknownFields.length > 0) throw new RuleError(`${at}.match: unknown field${unknownFields.length > 1 ? "s" : ""} ${unknownFields.map((k) => JSON.stringify(k)).join(", ")} (allowed: tools, params, paths, absent, when)`);
+	const unknownFields = Object.keys(record).filter((key) => key !== "tools" && key !== "agents" && key !== "params" && key !== "paths" && key !== "absent" && key !== "when");
+	if (unknownFields.length > 0) throw new RuleError(`${at}.match: unknown field${unknownFields.length > 1 ? "s" : ""} ${unknownFields.map((k) => JSON.stringify(k)).join(", ")} (allowed: tools, agents, params, paths, absent, when)`);
 	return {
 		tools: parseStringList(record["tools"], `${at}.match.tools`),
+		agents: parseStringList(record["agents"], `${at}.match.agents`),
 		params: parseParams(record["params"], `${at}.match.params`),
 		paths: parseStringList(record["paths"], `${at}.match.paths`),
 		absent: parseStringList(record["absent"], `${at}.match.absent`),
@@ -851,7 +900,7 @@ function relFromRoot(root, path, rest, rootRest, caseInsensitive) {
 	const restLower = caseInsensitive ? rest.toLowerCase() : rest;
 	const rootRestLower = caseInsensitive ? rootRest.toLowerCase() : rootRest;
 	if (rootRestLower.length === 0) return rest.slice(1);
-	if (path.toLowerCase() === root.toLowerCase()) return "";
+	if (path === root || caseInsensitive && path.toLowerCase() === root.toLowerCase()) return "";
 	return restLower.startsWith(`${rootRestLower}/`) ? rest.slice(rootRest.length + 1) : "";
 }
 /** Convert a path to posix separators. */
@@ -880,18 +929,22 @@ const EN = {
 	reloaded: (count, source) => `Reloaded ${count} rule(s) from ${source}.`,
 	reloadFailed: (error) => `Reload failed: ${error}. The previous rules are still active.`,
 	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).`,
-	decisionLine: (seq, action, toolName, ruleIndex, reason) => {
-		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (rule ${ruleIndex + 1})`}${reason === void 0 ? "" : `: ${short(reason)}`}`;
+	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
+		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (rule ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (dry-run)" : ` (dry-run → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
 	},
 	testHit: (tool, ruleIndex, action, reason) => `"${tool}" matches rule ${ruleIndex + 1} (${action}): ${short(reason)}`,
 	testNoMatch: (tool) => `"${tool}" matches no rule — the call passes through.`,
 	testBadJson: (text) => `Invalid JSON arguments "${text}": the arguments must parse as JSON.`,
-	testUsage: "Usage: /rules test <tool> <json-args>, e.g. /rules test bash {\"command\":\"git push origin main\"}",
+	testUnknownFlag: (flag) => `Unknown /rules test flag "${flag}". ${EN.testUsage}`,
+	testBadFlag: (flag) => `Invalid /rules test flag "${flag}": expected a value. ${EN.testUsage}`,
+	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)"
 };
@@ -902,18 +955,22 @@ const ZH = {
 	reloaded: (count, source) => `已重载 ${count} 条规则，来自 ${source}。`,
 	reloadFailed: (error) => `重载失败：${error}。之前的规则仍然生效。`,
 	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）。`,
-	decisionLine: (seq, action, toolName, ruleIndex, reason) => {
-		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : `（规则 ${ruleIndex + 1}）`}${reason === void 0 ? "" : `：${short(reason)}`}`;
+	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
+		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : `（规则 ${ruleIndex + 1}）`}${dryRun ? outcome === void 0 ? "（干跑）" : `（干跑 → ${outcome}）` : ""}${reason === void 0 ? "" : `：${short(reason)}`}`;
 	},
 	testHit: (tool, ruleIndex, action, reason) => `"${tool}" 命中规则 ${ruleIndex + 1}（${action}）：${short(reason)}`,
 	testNoMatch: (tool) => `"${tool}" 未命中任何规则——该调用将透传。`,
 	testBadJson: (text) => `无效的 JSON 参数 "${text}"：参数必须能被解析为 JSON。`,
-	testUsage: "用法：/rules test <工具名> <json-参数>，例如 /rules test bash {\"command\":\"git push origin main\"}",
+	testUnknownFlag: (flag) => `未知的 /rules test 标志 "${flag}"。${ZH.testUsage}`,
+	testBadFlag: (flag) => `无效的 /rules test 标志 "${flag}"：缺少取值。${ZH.testUsage}`,
+	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: "（无规则文件——空规则集）"
 };
@@ -924,18 +981,22 @@ const ES = {
 	reloaded: (count, source) => `Recargadas ${count} regla(s) desde ${source}.`,
 	reloadFailed: (error) => `Error de recarga: ${error}. Las reglas anteriores siguen activas.`,
 	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).`,
-	decisionLine: (seq, action, toolName, ruleIndex, reason) => {
-		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (regla ${ruleIndex + 1})`}${reason === void 0 ? "" : `: ${short(reason)}`}`;
+	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
+		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (regla ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (simulación)" : ` (simulación → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
 	},
 	testHit: (tool, ruleIndex, action, reason) => `"${tool}" coincide con la regla ${ruleIndex + 1} (${action}): ${short(reason)}`,
 	testNoMatch: (tool) => `"${tool}" no coincide con ninguna regla — la llamada pasa sin restricciones.`,
 	testBadJson: (text) => `Argumentos JSON inválidos "${text}": los argumentos deben poderse analizar como JSON.`,
-	testUsage: "Uso: /rules test <herramienta> <json-args>, p. ej. /rules test bash {\"command\":\"git push origin main\"}",
+	testUnknownFlag: (flag) => `Bandera de /rules test desconocida "${flag}". ${ES.testUsage}`,
+	testBadFlag: (flag) => `Bandera de /rules test inválida "${flag}": falta un valor. ${ES.testUsage}`,
+	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)"
 };
@@ -946,18 +1007,22 @@ const PT = {
 	reloaded: (count, source) => `Recarregadas ${count} regra(s) de ${source}.`,
 	reloadFailed: (error) => `Falha ao recarregar: ${error}. As regras anteriores continuam ativas.`,
 	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).`,
-	decisionLine: (seq, action, toolName, ruleIndex, reason) => {
-		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (regra ${ruleIndex + 1})`}${reason === void 0 ? "" : `: ${short(reason)}`}`;
+	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
+		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (regra ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (simulação)" : ` (simulação → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
 	},
 	testHit: (tool, ruleIndex, action, reason) => `"${tool}" corresponde à regra ${ruleIndex + 1} (${action}): ${short(reason)}`,
 	testNoMatch: (tool) => `"${tool}" não corresponde a nenhuma regra — a chamada passa livremente.`,
 	testBadJson: (text) => `Argumentos JSON inválidos "${text}": os argumentos precisam ser JSON analisável.`,
-	testUsage: "Uso: /rules test <ferramenta> <json-args>, ex.: /rules test bash {\"command\":\"git push origin main\"}",
+	testUnknownFlag: (flag) => `Sinalizador de /rules test desconhecido "${flag}". ${PT.testUsage}`,
+	testBadFlag: (flag) => `Sinalizador de /rules test inválido "${flag}": falta um valor. ${PT.testUsage}`,
+	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)"
 };
@@ -968,18 +1033,22 @@ const HI = {
 	reloaded: (count, source) => `${count} नियम पुनः लोड किए गए, स्रोत ${source}।`,
 	reloadFailed: (error) => `पुनः लोड विफल: ${error}। पिछले नियम अब भी सक्रिय हैं।`,
 	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)।`,
-	decisionLine: (seq, action, toolName, ruleIndex, reason) => {
-		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (नियम ${ruleIndex + 1})`}${reason === void 0 ? "" : `: ${short(reason)}`}`;
+	decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
+		return `- #${seq} ${action} ${toolName}${ruleIndex === void 0 ? "" : ` (नियम ${ruleIndex + 1})`}${dryRun ? outcome === void 0 ? " (ड्राई-रन)" : ` (ड्राई-रन → ${outcome})` : ""}${reason === void 0 ? "" : `: ${short(reason)}`}`;
 	},
 	testHit: (tool, ruleIndex, action, reason) => `"${tool}" नियम ${ruleIndex + 1} से मेल खाता है (${action}): ${short(reason)}`,
 	testNoMatch: (tool) => `"${tool}" किसी नियम से मेल नहीं खाता — कॉल बिना रोक पास होगी।`,
 	testBadJson: (text) => `अमान्य JSON तर्क "${text}": तर्क JSON के रूप में पार्स होने चाहिए।`,
-	testUsage: "उपयोग: /rules test <टूल> <json-args>, जैसे /rules test bash {\"command\":\"git push origin main\"}",
+	testUnknownFlag: (flag) => `अज्ञात /rules test फ़्लैग "${flag}"। ${HI.testUsage}`,
+	testBadFlag: (flag) => `अमान्य /rules test फ़्लैग "${flag}": मान गायब है। ${HI.testUsage}`,
+	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: "(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)"
 };
@@ -996,57 +1065,67 @@ const DESCRIBE_TOKENS = {
 	en: {
 		allTools: "all tools",
 		tools: "tools",
+		agents: "agents",
 		params: "params",
 		paths: "paths",
 		absent: "absent",
 		when: "when",
 		platform: "platform",
 		disabled: "disabled",
-		tags: "tags"
+		tags: "tags",
+		src: "src"
 	},
 	zh: {
 		allTools: "全部工具",
 		tools: "工具",
+		agents: "代理",
 		params: "参数",
 		paths: "路径",
 		absent: "缺省键",
 		when: "条件",
 		platform: "平台",
 		disabled: "已禁用",
-		tags: "标签"
+		tags: "标签",
+		src: "来源"
 	},
 	es: {
 		allTools: "todas las herramientas",
 		tools: "herramientas",
+		agents: "agentes",
 		params: "parámetros",
 		paths: "rutas",
 		absent: "ausentes",
 		when: "cuándo",
 		platform: "plataforma",
 		disabled: "deshabilitada",
-		tags: "etiquetas"
+		tags: "etiquetas",
+		src: "origen"
 	},
 	pt: {
 		allTools: "todas as ferramentas",
 		tools: "ferramentas",
+		agents: "agentes",
 		params: "parâmetros",
 		paths: "caminhos",
 		absent: "ausentes",
 		when: "quando",
 		platform: "plataforma",
 		disabled: "desativada",
-		tags: "etiquetas"
+		tags: "etiquetas",
+		src: "origem"
 	},
 	hi: {
 		allTools: "सभी टूल",
 		tools: "टूल",
+		agents: "एजेंट",
 		params: "पैरामीटर",
 		paths: "पथ",
 		absent: "अनुपस्थित",
 		when: "शर्त",
 		platform: "प्लेटफ़ॉर्म",
 		disabled: "अक्षम",
-		tags: "टैग"
+		tags: "टैग",
+		src: "स्रोत"
 	}
 };
 //#endregion
@@ -1057,8 +1136,10 @@ const DESCRIBE_TOKENS = {
 * `tools/pre-execute` listener that turns a first-match hit into a
 * 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 <tool> <json>`), and
-* Chokidar-driven reloads. Every registration is an effect.
+* (`list | reload | decisions [n] | test [flags] <tool> <json>`), and
+* 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
 */
 /**
@@ -1070,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();
@@ -1168,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
@@ -1178,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: {
@@ -1204,7 +1297,7 @@ var PermissionRulesRuntime = class {
 				lastError: message,
 				failed: true
 			});
-			this.reconcileWatch(cwd, sources);
+			this.reconcileWatch(key, sources);
 			throw error;
 		}
 	}
@@ -1216,44 +1309,59 @@ 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);
+			}
 		}
 	}
-	/** The match context `when` conditions evaluate against. */
-	matchContext() {
+	/**
+	* The match context `when`/`agents` conditions evaluate against: host
+	* facts plus the caller's agent-identity candidates derived from the
+	* session header (`main` for top-level sessions, `subagent` for
+	* subagent children, `preset:<name>` when a preset composed the agent).
+	* @param exec - the pending call whose caller supplies the identity.
+	*/
+	matchContext(exec) {
 		return {
 			platform: process.platform,
-			env: process.env
+			env: process.env,
+			agents: agentCandidates(exec?.agent)
 		};
 	}
 	/**
 	* The `tools/pre-execute` listener. A deny/ask hit returns the decision
 	* (first match wins, short-circuiting downstream listeners); an allow hit
 	* and a passthrough MUST delegate via `next()` so later listeners keep
-	* their say. Audit is appended once the final outcome is known, so the
-	* recorded `outcome` matches what the waterfall settled on.
+	* their say. Under `enforce: false` (dry-run) a deny/ask hit also
+	* delegates — the record keeps the would-be action with `dryRun: true`
+	* and the actual downstream outcome. Audit is appended once the final
+	* outcome is known, so the recorded `outcome` matches what the waterfall
+	* settled on.
 	* @param exec - the pending call (name, parsed arguments, caller agent).
 	* @param next - the downstream chain.
 	* @returns the pre-execute decision.
@@ -1261,12 +1369,17 @@ var PermissionRulesRuntime = class {
 	async preExecute(exec, next) {
 		const cwd = exec.agent?.session.header.cwd ?? process.cwd();
 		const loaded = this.rulesFor(cwd);
-		const hit = matchRules(loaded.compiled, exec.name, exec.arguments, cwd, this.matchContext());
+		const hit = matchRules(loaded.compiled, exec.name, exec.arguments, cwd, this.matchContext(exec));
 		if (hit === void 0 || hit.rule.action === "allow") {
 			const decision = await next();
 			this.audit(exec, loaded, hit, decision.kind);
 			return decision;
 		}
+		if (!this.config.enforce) {
+			const decision = await next();
+			this.audit(exec, loaded, hit, decision.kind, true);
+			return decision;
+		}
 		const outcome = hit.rule.action;
 		this.audit(exec, loaded, hit, outcome);
 		if (outcome === "deny") return {
@@ -1284,15 +1397,18 @@ var PermissionRulesRuntime = class {
 	* envelope's `ignorable: true` marker so any harness build can load the
 	* log (readers that do not know the type skip the audit record instead of
 	* refusing the session). `source` names the matched rule's file, or the
-	* nearest effective file on a passthrough. Agentless calls have no
-	* session to audit; append failures are contained so an audit hiccup can
-	* never change a permission decision.
+	* nearest effective file on a passthrough; `cwd` names the workspace the
+	* rules were resolved for; `dryRun` marks would-be deny/ask hits under
+	* `enforce: false`. Agentless calls have no session to audit; append
+	* failures are contained so an audit hiccup can never change a
+	* permission decision.
 	* @param exec - the pending call.
 	* @param loaded - the rules in effect.
 	* @param hit - the first matching rule, or undefined for passthrough.
 	* @param outcome - the final pre-execute decision.
+	* @param dryRun - mark the record as a would-be decision (dry-run mode).
 	*/
-	audit(exec, loaded, hit, outcome) {
+	audit(exec, loaded, hit, outcome, dryRun = false) {
 		if (this.config.audit === "hits" && hit === void 0) return;
 		const agent = exec.agent;
 		if (agent === void 0) return;
@@ -1303,10 +1419,12 @@ var PermissionRulesRuntime = class {
 				source: hit === void 0 ? loaded.sources[0] ?? "" : loaded.sources[hit.rule.sourceIndex] ?? "",
 				action: hit === void 0 ? "passthrough" : hit.rule.action,
 				outcome,
+				cwd: loaded.cwd,
 				...hit !== void 0 ? {
 					ruleIndex: hit.ruleIndex,
 					reason: hit.rule.reason
-				} : {}
+				} : {},
+				...dryRun ? { dryRun: true } : {}
 			}, { ignorable: true });
 		} catch (error) {
 			this.ctx.logger.warn(`permission-rules: audit append failed: ${String(error)}`);
@@ -1315,8 +1433,9 @@ var PermissionRulesRuntime = class {
 	/**
 	* Execute the `/rules` command: bare `/rules` lists the active rules and
 	* their sources; `/rules reload` re-reads the chain; `/rules decisions
-	* [n]` shows the session's audit trail; `/rules test <tool> <json>`
-	* dry-evaluates the rules against a hypothetical call. Command output
+	* [n]` shows the session's audit trail; `/rules test [flags] <tool>
+	* <json>` dry-evaluates the rules against a hypothetical call (flags
+	* override the workspace, host env, and agent identity). Command output
 	* stays in the UI — nothing here is injected into the model context.
 	* @param invocation - the received command invocation.
 	* @returns the command result shown to the user.
@@ -1333,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)
@@ -1345,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",
@@ -1361,41 +1484,8 @@ var PermissionRulesRuntime = class {
 			}
 			return this.decisionsCommand(invocation, count, prose);
 		}
-		if (verb === "test") {
-			const verbText = verbRaw ?? "";
-			const restLine = raw.length > verbText.length ? raw.slice(verbText.length).trim() : "";
-			const match = /^(\S+)\s*(.*)$/s.exec(restLine);
-			const tool = match?.[1];
-			const jsonText = match?.[2] ?? "";
-			if (tool === void 0 || tool.length === 0) return {
-				kind: "error",
-				text: prose.testUsage
-			};
-			let args;
-			try {
-				args = jsonText.length > 0 ? JSON.parse(jsonText) : {};
-			} catch {
-				return {
-					kind: "error",
-					text: prose.testBadJson(jsonText)
-				};
-			}
-			let loaded;
-			try {
-				loaded = this.rulesFor(cwd);
-			} catch (error) {
-				return {
-					kind: "error",
-					text: error instanceof Error ? error.message : String(error)
-				};
-			}
-			const hit = matchRules(loaded.compiled, tool, args, cwd, this.matchContext());
-			return {
-				kind: "success",
-				text: hit === void 0 ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason)
-			};
-		}
-		if (verb !== "") return {
+		if (verb === "test") return this.testCommand(raw, verbRaw ?? "", invocation, cwd, prose);
+		if (verb !== "" && verb !== "list") return {
 			kind: "error",
 			text: prose.unknownArg(invocation.rawInput.trim())
 		};
@@ -1412,17 +1502,116 @@ 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)));
 		}
 		if (loaded.lastError !== void 0) lines.push(prose.lastReloadWarning(loaded.lastError));
+		if (!this.config.enforce) lines.push(prose.dryRunNotice);
 		lines.push(prose.usage);
 		return {
 			kind: "success",
 			text: lines.join("\n")
 		};
 	}
+	/**
+	* 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, `--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).
+	* @param sessionCwd - the session's workspace root.
+	* @param prose - localized output vocabulary.
+	* @returns the dry-evaluation result.
+	*/
+	testCommand(raw, verbRaw, invocation, sessionCwd, prose) {
+		let rest = raw.length > verbRaw.length ? raw.slice(verbRaw.length).trim() : "";
+		const envOverrides = {};
+		const agentSelectors = [];
+		let testCwd;
+		let testPlatform;
+		let parsed = nextToken(rest);
+		while (parsed !== void 0 && parsed.token.startsWith("--")) {
+			const flag = parsed.token;
+			const value = nextToken(parsed.rest);
+			if (value === void 0 || value.token.startsWith("--")) return {
+				kind: "error",
+				text: prose.testBadFlag(flag)
+			};
+			if (flag === "--cwd") testCwd = isAbsolute(value.token) ? value.token : resolve(sessionCwd, value.token);
+			else if (flag === "--env") {
+				const equals = value.token.indexOf("=");
+				if (equals <= 0) return {
+					kind: "error",
+					text: prose.testBadFlag(`${flag} ${value.token}`)
+				};
+				envOverrides[value.token.slice(0, equals)] = value.token.slice(equals + 1);
+			} else if (flag === "--agent") agentSelectors.push(value.token);
+			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)
+			};
+			rest = value.rest;
+			parsed = nextToken(rest);
+		}
+		const tool = parsed?.token;
+		const jsonText = parsed === void 0 ? "" : parsed.rest.trim();
+		if (tool === void 0 || tool.length === 0) return {
+			kind: "error",
+			text: prose.testUsage
+		};
+		let args;
+		try {
+			args = jsonText.length > 0 ? JSON.parse(jsonText) : {};
+		} catch {
+			return {
+				kind: "error",
+				text: prose.testBadJson(jsonText)
+			};
+		}
+		const evalCwd = testCwd ?? sessionCwd;
+		let loaded;
+		try {
+			loaded = this.rulesFor(evalCwd);
+		} catch (error) {
+			return {
+				kind: "error",
+				text: error instanceof Error ? error.message : String(error)
+			};
+		}
+		const context = {
+			platform: testPlatform ?? process.platform,
+			env: Object.keys(envOverrides).length === 0 ? process.env : {
+				...process.env,
+				...envOverrides
+			},
+			agents: agentSelectors.length > 0 ? agentSelectors : agentCandidates(invocation.agent)
+		};
+		const hit = matchRules(loaded.compiled, tool, args, evalCwd, context);
+		return {
+			kind: "success",
+			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");
@@ -1434,7 +1623,7 @@ var PermissionRulesRuntime = class {
 		const lines = [prose.decisionsHeader(shown.length, decisions.length)];
 		for (const event of shown) {
 			const data = event.data;
-			lines.push(prose.decisionLine(event.seq, data.action, data.toolName, data.ruleIndex, data.reason));
+			lines.push(prose.decisionLine(event.seq, data.action, data.toolName, data.ruleIndex, data.reason, data.dryRun === true, data.outcome));
 		}
 		return {
 			kind: "success",
@@ -1507,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() {
@@ -1543,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. */
@@ -1554,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);
 	}
@@ -1579,21 +1863,76 @@ 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 <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)
 	});
 }
+/**
+* Identity candidates for the `agents` match dimension, derived from the
+* caller agent's session header: `main` for top-level sessions, `subagent`
+* for subagent children (`header.origin === 'subagent'`), and
+* `preset:<name>` when a preset composed the agent. No agent (or an
+* unidentifiable one) yields no candidates, so agent-scoped rules fail
+* closed instead of matching an unknown caller.
+* @param agent - the calling agent, when the call has one.
+* @returns the candidate strings, in a stable order.
+*/
+function agentCandidates(agent) {
+	if (agent === void 0) return [];
+	const header = agent.session.header;
+	const candidates = [header.origin === "subagent" ? "subagent" : "main"];
+	if (typeof header.agentPreset === "string" && header.agentPreset.length > 0) candidates.push(`preset:${header.agentPreset}`);
+	return candidates;
+}
+/**
+* Pull the next whitespace-delimited argument from a command tail,
+* honoring single/double quotes (with backslash escapes) so JSON blobs and
+* paths with spaces survive. The remainder is returned verbatim — the JSON
+* argument tail of `/rules test` is never re-tokenized.
+* @param text - the remaining command tail.
+* @returns the token plus the untouched remainder, or undefined when only
+*   whitespace remains.
+*/
+function nextToken(text) {
+	let i = 0;
+	while (i < text.length && /\s/.test(text[i])) i += 1;
+	if (i >= text.length) return void 0;
+	const quote = text[i];
+	if (quote === "\"" || quote === "'") {
+		let end = i + 1;
+		while (end < text.length && text[end] !== quote) {
+			if (text[end] === "\\") end += 1;
+			end += 1;
+		}
+		if (end >= text.length) return {
+			token: text.slice(i + 1),
+			rest: ""
+		};
+		return {
+			token: text.slice(i + 1, end),
+			rest: text.slice(end + 1)
+		};
+	}
+	let end = i;
+	while (end < text.length && !/\s/.test(text[end])) end += 1;
+	return {
+		token: text.slice(i, end),
+		rest: text.slice(end)
+	};
+}
 //#endregion
 //#region src/index.ts
 /**
 * `dsh-permission-rules` — Claude Code-style declarative permission rules
 * for DeepSeek Harness. A `tools/pre-execute` waterfall listener evaluates
-* an ordered `allow`/`deny`/`ask` rule list (tool-name globs, argument
-* glob/regex matching, workspace-path matching) per session cwd; deny and
-* ask decisions short-circuit the chain, while allow and passthrough always
-* delegate via `next()`. `ask` rides the official approval seam, where
-* answerers such as `dsh-auto-review` or a human UI decide — the plugin
-* itself never runs a reviewer. Every decision is audit-logged.
+* an ordered `allow`/`deny`/`ask` rule list (tool-name globs, agent
+* selectors, argument glob/regex matching, workspace-path matching) per
+* session cwd; deny and ask decisions short-circuit the chain, while allow
+* and passthrough always delegate via `next()`. Under `enforce: false` the
+* plugin audits what it WOULD decide and lets everything through (dry-run
+* policy rollout). `ask` rides the official approval seam, where answerers
+* such as `dsh-auto-review` or a human UI decide — the plugin itself never
+* runs a reviewer. Every decision is audit-logged.
 *
 * Function plugin — no default export (the Loader unwraps
 * `exports.default ?? exports`, and a stray default would discard