dsh-permission-rules 0.2.0 → 0.3.0

package/src/prose.ts

@@ -24,6 +24,8 @@ export interface UiProse {
   reloadFailed: (error: string) => string
   /** Warning appended to a listing whose last reload failed. */
   lastReloadWarning: (error: string) => string
+  /** Notice appended to a listing when dry-run mode (`enforce: false`) is active. */
+  dryRunNotice: string
   /** Rejection of an unknown `/rules` argument. */
   unknownArg: (arg: string) => string
   /** Usage hint. */
@@ -34,14 +36,18 @@ export interface UiProse {
   noDecisions: string
   /** Rejection of a malformed decisions count. */
   invalidDecisionsCount: (arg: string) => string
-  /** One audit-decision row. */
-  decisionLine: (seq: number, action: string, toolName: string, ruleIndex: number | undefined, reason: string | undefined) => string
+  /** One audit-decision row (dry-run rows mark the actual outcome). */
+  decisionLine: (seq: number, action: string, toolName: string, ruleIndex: number | undefined, reason: string | undefined, dryRun: boolean, outcome: string | undefined) => string
   /** Hit line of `/rules test`. */
   testHit: (tool: string, ruleIndex: number, action: string, reason: string) => string
   /** No-match line of `/rules test`. */
   testNoMatch: (tool: string) => string
   /** Rejection of unparseable `/rules test` JSON arguments. */
   testBadJson: (text: string) => string
+  /** Rejection of an unknown `/rules test` flag. */
+  testUnknownFlag: (flag: string) => string
+  /** Rejection of a malformed `/rules test` flag (missing value, bad KEY=VALUE). */
+  testBadFlag: (flag: string) => string
   /** Usage hint of `/rules test`. */
   testUsage: string
   /** Warning naming shadowed (unreachable) rules by 1-based number. */
@@ -54,6 +60,7 @@ export interface UiProse {
 export interface DescribeTokens {
   allTools: string
   tools: string
+  agents: string
   params: string
   paths: string
   absent: string
@@ -75,20 +82,24 @@ const EN: UiProse = {
   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) => {
+  decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (rule ${ruleIndex + 1})`
+    const dry = dryRun ? (outcome === undefined ? ' (dry-run)' : ` (dry-run → ${outcome})`) : ''
     const why = reason === undefined ? '' : `: ${short(reason)}`
-    return `- #${seq} ${action} ${toolName}${rule}${why}`
+    return `- #${seq} ${action} ${toolName}${rule}${dry}${why}`
   },
   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)',
 }
@@ -100,20 +111,24 @@ const ZH: UiProse = {
   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) => {
+  decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : `（规则 ${ruleIndex + 1}）`
+    const dry = dryRun ? (outcome === undefined ? '（干跑）' : `（干跑 → ${outcome}）`) : ''
     const why = reason === undefined ? '' : `：${short(reason)}`
-    return `- #${seq} ${action} ${toolName}${rule}${why}`
+    return `- #${seq} ${action} ${toolName}${rule}${dry}${why}`
   },
   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: '（无规则文件——空规则集）',
 }
@@ -125,20 +140,24 @@ const ES: UiProse = {
   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) => {
+  decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (regla ${ruleIndex + 1})`
+    const dry = dryRun ? (outcome === undefined ? ' (simulación)' : ` (simulación → ${outcome})`) : ''
     const why = reason === undefined ? '' : `: ${short(reason)}`
-    return `- #${seq} ${action} ${toolName}${rule}${why}`
+    return `- #${seq} ${action} ${toolName}${rule}${dry}${why}`
   },
   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)',
 }
@@ -150,20 +169,24 @@ const PT: UiProse = {
   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) => {
+  decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (regra ${ruleIndex + 1})`
+    const dry = dryRun ? (outcome === undefined ? ' (simulação)' : ` (simulação → ${outcome})`) : ''
     const why = reason === undefined ? '' : `: ${short(reason)}`
-    return `- #${seq} ${action} ${toolName}${rule}${why}`
+    return `- #${seq} ${action} ${toolName}${rule}${dry}${why}`
   },
   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)',
 }
@@ -175,20 +198,24 @@ const HI: UiProse = {
   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) => {
+  decisionLine: (seq, action, toolName, ruleIndex, reason, dryRun, outcome) => {
     const rule = ruleIndex === undefined ? '' : ` (नियम ${ruleIndex + 1})`
+    const dry = dryRun ? (outcome === undefined ? ' (ड्राई-रन)' : ` (ड्राई-रन → ${outcome})`) : ''
     const why = reason === undefined ? '' : `: ${short(reason)}`
-    return `- #${seq} ${action} ${toolName}${rule}${why}`
+    return `- #${seq} ${action} ${toolName}${rule}${dry}${why}`
   },
   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: '(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)',
 }
@@ -198,9 +225,9 @@ export const UI_PROSE: Readonly<Record<UiLanguage, UiProse>> = { en: EN, zh: ZH,
 
 /** `describeRule` match-dimension tokens by language. */
 export const DESCRIBE_TOKENS: Readonly<Record<UiLanguage, DescribeTokens>> = {
-  en: { allTools: 'all tools', tools: 'tools', params: 'params', paths: 'paths', absent: 'absent', when: 'when', platform: 'platform', disabled: 'disabled', tags: 'tags' },
-  zh: { allTools: '全部工具', tools: '工具', params: '参数', paths: '路径', absent: '缺省键', when: '条件', platform: '平台', disabled: '已禁用', tags: '标签' },
-  es: { allTools: 'todas las herramientas', tools: 'herramientas', params: 'parámetros', paths: 'rutas', absent: 'ausentes', when: 'cuándo', platform: 'plataforma', disabled: 'deshabilitada', tags: 'etiquetas' },
-  pt: { allTools: 'todas as ferramentas', tools: 'ferramentas', params: 'parâmetros', paths: 'caminhos', absent: 'ausentes', when: 'quando', platform: 'plataforma', disabled: 'desativada', tags: 'etiquetas' },
-  hi: { allTools: 'सभी टूल', tools: 'टूल', params: 'पैरामीटर', paths: 'पथ', absent: 'अनुपस्थित', when: 'शर्त', platform: 'प्लेटफ़ॉर्म', disabled: 'अक्षम', tags: 'टैग' },
+  en: { allTools: 'all tools', tools: 'tools', agents: 'agents', params: 'params', paths: 'paths', absent: 'absent', when: 'when', platform: 'platform', disabled: 'disabled', tags: 'tags' },
+  zh: { allTools: '全部工具', tools: '工具', agents: '代理', params: '参数', paths: '路径', absent: '缺省键', when: '条件', platform: '平台', disabled: '已禁用', tags: '标签' },
+  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' },
+  pt: { allTools: 'todas as ferramentas', tools: 'ferramentas', agents: 'agentes', params: 'parâmetros', paths: 'caminhos', absent: 'ausentes', when: 'quando', platform: 'plataforma', disabled: 'desativada', tags: 'etiquetas' },
+  hi: { allTools: 'सभी टूल', tools: 'टूल', agents: 'एजेंट', params: 'पैरामीटर', paths: 'पथ', absent: 'अनुपस्थित', when: 'शर्त', platform: 'प्लेटफ़ॉर्म', disabled: 'अक्षम', tags: 'टैग' },
 }

package/src/rules.ts

@@ -68,6 +68,14 @@ export interface RuleMatchDoc {
   paths: string[]
   /** Argument keys that must be ABSENT; every listed key must be missing. */
   absent: string[]
+  /**
+   * Agent-identity selectors (globs against the calling agent's session
+   * header: `main`, `subagent`, and `preset:<name>` candidates); ANY
+   * selector matching ANY candidate satisfies the dimension. Empty matches
+   * every agent. Unknown agent identity never matches, so agent-scoped
+   * rules fail closed.
+   */
+  agents: string[]
   /** Environment/platform conditions; every listed env key must be present and match. */
   when: WhenDoc
 }
@@ -92,6 +100,8 @@ export interface CompiledRule {
   readonly description?: string
   readonly tags: readonly string[]
   readonly tools: readonly RegExp[]
+  /** Agent-selector globs; empty = every agent. */
+  readonly agents: readonly RegExp[]
   /** Param key → positive/negative pattern lists. */
   readonly params: ReadonlyMap<string, { positive: readonly RegExp[]; negative: readonly RegExp[] }>
   readonly paths: readonly RegExp[]
@@ -137,6 +147,12 @@ export interface MatchContext {
   readonly platform?: string
   /** Environment table; defaults to `process.env` when omitted. */
   readonly env?: Readonly<Record<string, string | undefined>>
+  /**
+   * Agent-identity candidate strings the `agents` dimension matches
+   * against (`main`, `subagent`, `preset:<name>`); omitted (or empty)
+   * means the identity is unknown and agent-scoped rules never match.
+   */
+  readonly agents?: readonly string[]
 }
 
 /**
@@ -207,6 +223,7 @@ export function compileRulesChain(entries: readonly RulesChainEntry[], options:
 /** Compile one parsed rule into its hot-path form. */
 function compileRule(entry: RuleDocEntry, index: number, sourceIndex: number, options: CompileOptions): CompiledRule {
   const tools = entry.match.tools.map(pattern => compileToolPattern(pattern, options.maxGlobStars))
+  const agents = entry.match.agents.map(pattern => compileToolPattern(pattern, options.maxGlobStars))
   const params = new Map<string, { positive: readonly RegExp[]; negative: readonly RegExp[] }>()
   for (const [key, patterns] of Object.entries(entry.match.params)) {
     params.set(key, compileParamPatterns(key, patterns, options))
@@ -225,6 +242,7 @@ function compileRule(entry: RuleDocEntry, index: number, sourceIndex: number, op
     ...(entry.description !== undefined ? { description: entry.description } : {}),
     tags: entry.tags,
     tools,
+    agents,
     params,
     paths,
     absent: entry.match.absent,
@@ -263,6 +281,7 @@ export function matchRules(
   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 === undefined || !matchParams(rule, argRecord))) continue
     if (rule.absent.length > 0 && !matchAbsent(rule, argRecord)) continue
@@ -296,7 +315,7 @@ export function findUnreachableRules(ruleset: CompiledRuleset): number[] {
 
 /** Whether every match dimension of one rule is empty. */
 function isCatchAll(rule: CompiledRule): boolean {
-  return rule.tools.length === 0 && rule.params.size === 0 && rule.paths.length === 0 && rule.absent.length === 0 && rule.when === undefined
+  return rule.tools.length === 0 && rule.agents.length === 0 && rule.params.size === 0 && rule.paths.length === 0 && rule.absent.length === 0 && rule.when === undefined
 }
 
 /**
@@ -310,6 +329,7 @@ function isCatchAll(rule: CompiledRule): boolean {
 export function describeRule(rule: CompiledRule, tokens: DescribeTokens): string {
   const parts: string[] = []
   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(' ')
@@ -332,6 +352,7 @@ export function describeRule(rule: CompiledRule, tokens: DescribeTokens): string
 export interface DescribeTokens {
   readonly allTools: string
   readonly tools: string
+  readonly agents: string
   readonly params: string
   readonly paths: string
   readonly absent: string
@@ -352,6 +373,19 @@ function matchTools(rule: CompiledRule, toolName: string): boolean {
   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: CompiledRule, context: MatchContext): boolean {
+  if (rule.agents.length === 0) return true
+  const candidates = context.agents
+  if (candidates === undefined || 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: CompiledRule, args: Record<string, unknown>): boolean {
   for (const [key, { positive, negative }] of rule.params) {
@@ -474,14 +508,15 @@ function parseRuleEntry(raw: unknown, index: number): RuleDocEntry {
 
 /** Validate the `match` block of one rule. */
 function parseMatch(raw: unknown, at: string): RuleMatchDoc {
-  if (raw === undefined) return { tools: [], params: {}, paths: [], absent: [], when: { env: {}, platform: [] } }
+  if (raw === undefined) return { tools: [], agents: [], params: {}, paths: [], absent: [], when: { env: {}, platform: [] } }
   const record = asRecord(raw, `${at}.match`)
-  const unknownFields = Object.keys(record).filter(key => key !== 'tools' && key !== 'params' && key !== 'paths' && key !== 'absent' && key !== '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, params, paths, absent, when)`)
+    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`),
@@ -671,7 +706,10 @@ function relFromRoot(root: string, path: string, rest: string, rootRest: string,
   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 ''
+  // A candidate equal to the root itself — modulo case only when the
+  // comparison is case-insensitive — is the workspace root, not a relative
+  // path inside it, and is dropped explicitly.
+  if (path === root || (caseInsensitive && path.toLowerCase() === root.toLowerCase())) return ''
   return restLower.startsWith(`${rootRestLower}/`) ? rest.slice(rootRest.length + 1) : ''
 }
 

package/src/runtime.ts

@@ -4,7 +4,7 @@
  * `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
  */
@@ -189,17 +189,26 @@ export class PermissionRulesRuntime {
     }
   }
 
-  /** The match context `when` conditions evaluate against. */
-  private matchContext(): MatchContext {
-    return { platform: process.platform, env: process.env }
+  /**
+   * 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.
+   */
+  private matchContext(exec?: ToolExecution): MatchContext {
+    return { platform: process.platform, 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.
@@ -207,12 +216,18 @@ export class PermissionRulesRuntime {
   async preExecute(exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision> {
     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 === undefined || hit.rule.action === 'allow') {
       const decision = await next()
       this.audit(exec, loaded, hit, decision.kind)
       return decision
     }
+    if (!this.config.enforce) {
+      // Dry-run: match the rule, log what it WOULD do, and delegate.
+      const decision = await next()
+      this.audit(exec, loaded, hit, decision.kind, true)
+      return decision
+    }
     const outcome: DecisionOutcome = hit.rule.action
     this.audit(exec, loaded, hit, outcome)
     if (outcome === 'deny') return { kind: 'deny', reason: hit.rule.reason }
@@ -225,15 +240,18 @@ export class PermissionRulesRuntime {
    * 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: ToolExecution, loaded: LoadedRules, hit: RuleHit | undefined, outcome: DecisionOutcome): void {
+  audit(exec: ToolExecution, loaded: LoadedRules, hit: RuleHit | undefined, outcome: DecisionOutcome, dryRun = false): void {
     if (this.config.audit === 'hits' && hit === undefined) return
     const agent = exec.agent
     if (agent === undefined) return
@@ -244,7 +262,9 @@ export class PermissionRulesRuntime {
         source: hit === undefined ? (loaded.sources[0] ?? '') : (loaded.sources[hit.rule.sourceIndex] ?? ''),
         action: hit === undefined ? 'passthrough' : hit.rule.action,
         outcome,
+        cwd: loaded.cwd,
         ...hit !== undefined ? { ruleIndex: hit.ruleIndex, reason: hit.rule.reason } : {},
+        ...dryRun ? { dryRun: true as const } : {},
       }, { ignorable: true })
     } catch (error: unknown) {
       this.ctx.logger.warn(`permission-rules: audit append failed: ${String(error)}`)
@@ -254,8 +274,9 @@ export class PermissionRulesRuntime {
   /**
    * 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.
@@ -286,29 +307,7 @@ export class PermissionRulesRuntime {
       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 === undefined || tool.length === 0) return { kind: 'error', text: prose.testUsage }
-      let args: unknown
-      try {
-        args = jsonText.length > 0 ? JSON.parse(jsonText) : {}
-      } catch {
-        return { kind: 'error', text: prose.testBadJson(jsonText) }
-      }
-      let loaded: LoadedRules
-      try {
-        loaded = this.rulesFor(cwd)
-      } catch (error: unknown) {
-        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 === undefined ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason),
-      }
+      return this.testCommand(raw, verbRaw ?? '', invocation, cwd, prose)
     }
     if (verb !== '') return { kind: 'error', text: prose.unknownArg(invocation.rawInput.trim()) }
     let loaded: LoadedRules
@@ -329,10 +328,81 @@ export class PermissionRulesRuntime {
     if (loaded.lastError !== undefined) {
       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.
+   */
+  private testCommand(raw: string, verbRaw: string, invocation: CommandInvocation, sessionCwd: string, prose: UiProse): CommandResult {
+    let rest = raw.length > verbRaw.length ? raw.slice(verbRaw.length).trim() : ''
+    const envOverrides: Record<string, string> = {}
+    const agentSelectors: string[] = []
+    let testCwd: string | undefined
+    let parsed = nextToken(rest)
+    while (parsed !== undefined && parsed.token.startsWith('--')) {
+      const flag = parsed.token
+      const value = nextToken(parsed.rest)
+      if (value === undefined || 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 === undefined ? '' : parsed.rest.trim()
+    if (tool === undefined || tool.length === 0) return { kind: 'error', text: prose.testUsage }
+    let args: unknown
+    try {
+      args = jsonText.length > 0 ? JSON.parse(jsonText) : {}
+    } catch {
+      return { kind: 'error', text: prose.testBadJson(jsonText) }
+    }
+    const evalCwd = testCwd ?? sessionCwd
+    let loaded: LoadedRules
+    try {
+      loaded = this.rulesFor(evalCwd)
+    } catch (error: unknown) {
+      return { kind: 'error', text: error instanceof Error ? error.message : String(error) }
+    }
+    const context: MatchContext = {
+      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 === undefined ? prose.testNoMatch(tool) : prose.testHit(tool, hit.ruleIndex, hit.rule.action, hit.rule.reason),
+    }
+  }
+
   /** Render the session's `permissionRules/decision` audit trail, newest last. */
   private decisionsCommand(invocation: CommandInvocation, count: number, prose: UiProse): CommandResult {
     const decisions = invocation.agent.session.events.filter(event => event.type === 'permissionRules/decision')
@@ -341,7 +411,7 @@ export class PermissionRulesRuntime {
     const lines = [prose.decisionsHeader(shown.length, decisions.length)]
     for (const event of shown) {
       const data = event.data as AuditDecision
-      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', text: lines.join('\n') }
   }
@@ -498,7 +568,53 @@ export function apply(ctx: Context, config: Config): void {
   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: ToolExecution['agent']): string[] {
+  if (agent === undefined) 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: string): { token: string; rest: string } | undefined {
+  let i = 0
+  while (i < text.length && /\s/.test(text[i] as string)) i += 1
+  if (i >= text.length) return undefined
+  const quote = text[i] as string
+  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] as string)) end += 1
+  return { token: text.slice(i, end), rest: text.slice(end) }
+}