dsh-permission-rules 0.2.0 → 0.3.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,7 +558,7 @@ 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
@@ -542,6 +571,7 @@ function isCatchAll(rule) {
 function describeRule(rule, tokens) {
 	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(",")}`);
@@ -564,6 +594,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 +717,7 @@ function parseRuleEntry(raw, index) {
 function parseMatch(raw, at) {
 	if (raw === void 0) return {
 		tools: [],
+		agents: [],
 		params: {},
 		paths: [],
 		absent: [],
@@ -684,10 +727,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 +895,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 +924,21 @@ 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>]",
 	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}`,
+	testUsage: "Usage: /rules test [--cwd <dir>] [--env KEY=VALUE]... [--agent <selector>]... <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 +949,21 @@ 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-参数>]",
 	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}`,
+	testUsage: "用法：/rules test [--cwd <目录>] [--env 键=值]... [--agent <选择器>]... <工具名> <json-参数>，例如 /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `警告：规则 ${numbers.join("、")} 不可达（被前面的通配规则遮蔽）。`,
 	emptySource: "（无规则文件——空规则集）"
 };
@@ -924,18 +974,21 @@ 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>]",
 	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}`,
+	testUsage: "Uso: /rules test [--cwd <dir>] [--env CLAVE=VALOR]... [--agent <selector>]... <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 +999,21 @@ 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>]",
 	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}`,
+	testUsage: "Uso: /rules test [--cwd <dir>] [--env CHAVE=VALOR]... [--agent <seletor>]... <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 +1024,21 @@ 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>]",
 	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}`,
+	testUsage: "उपयोग: /rules test [--cwd <dir>] [--env KEY=मान]... [--agent <चयनकर्ता>]... <टूल> <json-args>, जैसे /rules test bash {\"command\":\"git push origin main\"}",
 	unreachableWarning: (numbers) => `चेतावनी: नियम ${numbers.join(", ")} अप्राप्य हैं (पहले वाले सर्व-मिलान नियम से ढके हुए)।`,
 	emptySource: "(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)"
 };
@@ -996,6 +1055,7 @@ const DESCRIBE_TOKENS = {
 	en: {
 		allTools: "all tools",
 		tools: "tools",
+		agents: "agents",
 		params: "params",
 		paths: "paths",
 		absent: "absent",
@@ -1007,6 +1067,7 @@ const DESCRIBE_TOKENS = {
 	zh: {
 		allTools: "全部工具",
 		tools: "工具",
+		agents: "代理",
 		params: "参数",
 		paths: "路径",
 		absent: "缺省键",
@@ -1018,6 +1079,7 @@ const DESCRIBE_TOKENS = {
 	es: {
 		allTools: "todas las herramientas",
 		tools: "herramientas",
+		agents: "agentes",
 		params: "parámetros",
 		paths: "rutas",
 		absent: "ausentes",
@@ -1029,6 +1091,7 @@ const DESCRIBE_TOKENS = {
 	pt: {
 		allTools: "todas as ferramentas",
 		tools: "ferramentas",
+		agents: "agentes",
 		params: "parâmetros",
 		paths: "caminhos",
 		absent: "ausentes",
@@ -1040,6 +1103,7 @@ const DESCRIBE_TOKENS = {
 	hi: {
 		allTools: "सभी टूल",
 		tools: "टूल",
+		agents: "एजेंट",
 		params: "पैरामीटर",
 		paths: "पथ",
 		absent: "अनुपस्थित",
@@ -1057,7 +1121,7 @@ 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
+* (`list | reload | decisions [n] | test [flags] <tool> <json>`), and
 * Chokidar-driven reloads. Every registration is an effect.
 * @module dsh-permission-rules/runtime
 */
@@ -1241,19 +1305,29 @@ var PermissionRulesRuntime = class {
 			});
 		}
 	}
-	/** 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 +1335,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 +1363,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 +1385,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 +1399,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.
@@ -1361,40 +1446,7 @@ 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 === "test") return this.testCommand(raw, verbRaw ?? "", invocation, cwd, prose);
 		if (verb !== "") return {
 			kind: "error",
 			text: prose.unknownArg(invocation.rawInput.trim())
@@ -1417,12 +1469,95 @@ var PermissionRulesRuntime = class {
 			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, and `--agent <selector>` (repeatable) supplies
+	* agent-identity candidates for the `agents` dimension. 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 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 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: 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 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 +1569,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",
@@ -1579,21 +1714,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: "[reload | decisions [n] | test [--cwd <dir>] [--env K=V] [--agent <sel>] <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