dsh-permission-rules 0.2.0 → 0.4.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,20 @@ 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
+  /** Rejection of an unknown `--platform` value. */
+  testBadPlatform: (value: string) => string
   /** Usage hint of `/rules test`. */
   testUsage: string
   /** Warning naming shadowed (unreachable) rules by 1-based number. */
@@ -54,6 +62,7 @@ export interface UiProse {
 export interface DescribeTokens {
   allTools: string
   tools: string
+  agents: string
   params: string
   paths: string
   absent: string
@@ -61,6 +70,8 @@ export interface DescribeTokens {
   platform: string
   disabled: string
   tags: string
+  /** Prefix of the per-rule source-file attribution. */
+  src: string
 }
 
 /** Truncate long reasons/descriptions in one-line displays. */
@@ -75,20 +86,25 @@ 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>]',
+  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) => {
+  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}`,
+  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)',
 }
@@ -100,20 +116,25 @@ 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-参数>]',
+  usage: '用法：/rules [list | 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}`,
+  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: '（无规则文件——空规则集）',
 }
@@ -125,20 +146,25 @@ 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>]',
+  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) => {
+  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}`,
+  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)',
 }
@@ -150,20 +176,25 @@ 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>]',
+  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) => {
+  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}`,
+  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)',
 }
@@ -175,20 +206,25 @@ 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>]',
+  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) => {
+  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}`,
+  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: '(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)',
 }
@@ -198,9 +234,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', src: 'src' },
+  zh: { allTools: '全部工具', tools: '工具', agents: '代理', params: '参数', paths: '路径', absent: '缺省键', when: '条件', platform: '平台', disabled: '已禁用', 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', 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', src: 'origem' },
+  hi: { allTools: 'सभी टूल', tools: 'टूल', agents: 'एजेंट', params: 'पैरामीटर', paths: 'पथ', absent: 'अनुपस्थित', when: 'शर्त', platform: 'प्लेटफ़ॉर्म', disabled: 'अक्षम', tags: 'टैग', src: 'स्रोत' },
 }

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,20 +315,25 @@ 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
 }
 
 /**
  * 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.
  */
-export function describeRule(rule: CompiledRule, tokens: DescribeTokens): string {
+export function describeRule(rule: CompiledRule, tokens: DescribeTokens, source?: string): 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(' ')
@@ -323,15 +347,17 @@ export function describeRule(rule: CompiledRule, tokens: DescribeTokens): string
   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 !== undefined && source.length > 0 ? ` [${tokens.src}:${source}]` : ''
   const description = rule.description !== undefined ? ` (${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}`
 }
 
 /** The localized dimension-prefix vocabulary {@link describeRule} renders. */
 export interface DescribeTokens {
   readonly allTools: string
   readonly tools: string
+  readonly agents: string
   readonly params: string
   readonly paths: string
   readonly absent: string
@@ -339,6 +365,8 @@ export interface DescribeTokens {
   readonly platform: string
   readonly disabled: string
   readonly tags: string
+  /** Prefix of the per-rule source-file attribution. */
+  readonly src: string
 }
 
 /** Cut a display string at `limit` characters, marking truncation with `…`. */
@@ -352,6 +380,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 +515,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 +713,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) : ''
 }