dsh-permission-rules 0.2.0

package/src/events.ts

@@ -0,0 +1,75 @@
+/**
+ * Durable session vocabulary for `dsh-permission-rules`: the
+ * `permissionRules/decision` audit event, appended for every hit AND every
+ * passthrough. Log-only — it never enters the model transcript; the only
+ * model-visible plugin content is the deny/ask reason the tools registry
+ * materializes into the denied tool result, which carries the same
+ * `callId`, keeping model-visible ⟺ logged reconstructable.
+ *
+ * `outcome` records the FINAL pre-execute decision: on a deny/ask hit it
+ * equals `action` (the plugin short-circuits); on an allow hit or a
+ * passthrough it carries the downstream listeners' decision, so the audit
+ * never claims a call was allowed when a later listener denied it.
+ *
+ * The event is appended with the envelope's `ignorable: true` marker (see
+ * {@link AuditAppend}), so a harness build whose generated event vocabulary
+ * does not include this out-of-repo type still loads the log — it skips the
+ * audit record instead of refusing the whole session.
+ * @module dsh-permission-rules/events
+ */
+
+import type { CallId } from '@deepseek-ai/dsh-llm'
+import type { PreToolDecision } from '@deepseek-ai/dsh-tools'
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * One permission-rules decision for a pending tool call — log-only
+     * audit (like `approval/asked`; NOT a surface event). `action` is
+     * `'allow' | 'deny' | 'ask' | 'passthrough'`; `ruleIndex` (0-based) and
+     * `reason` appear only on hits. `source` is the absolute rule file of
+     * the matched rule, or the nearest effective file on a passthrough, or
+     * `''` when no rule file was active. `outcome` is the final pre-execute
+     * decision the waterfall settled on.
+     */
+    'permissionRules/decision': {
+      toolName: string
+      callId?: CallId
+      source: string
+      action: 'allow' | 'deny' | 'ask' | 'passthrough'
+      outcome?: 'allow' | 'deny' | 'ask'
+      ruleIndex?: number
+      reason?: string
+    }
+  }
+}
+
+/** Every action a decision event can carry. */
+export type DecisionAction = 'allow' | 'deny' | 'ask' | 'passthrough'
+
+/** The final pre-execute decision kinds a host can settle on. */
+export type DecisionOutcome = PreToolDecision['kind']
+
+/** The payload of one `permissionRules/decision` audit record. */
+export interface AuditDecision {
+  toolName: string
+  callId?: CallId
+  source: string
+  action: DecisionAction
+  outcome?: DecisionOutcome
+  ruleIndex?: number
+  reason?: string
+}
+
+/**
+ * `Session.append` narrowed to this plugin's audit event. The options bag
+ * exists only on host builds that expose the `ignorable` envelope-marker
+ * surface (post-rc.6 `@deepseek-ai/dsh-session`); an rc.6 host accepts and
+ * ignores the third argument, appending the identical event without the
+ * marker — no behavior change, no failure either way.
+ */
+export type AuditAppend = (
+  type: 'permissionRules/decision',
+  data: AuditDecision,
+  options?: { ignorable?: true },
+) => unknown

package/src/glob.ts

@@ -0,0 +1,303 @@
+/**
+ * Strict glob→RegExp compilation and regex-safety validation for rule
+ * patterns. A conservative, validated glob subset: `*` (within one path
+ * segment), `**` (any depth, including zero), `?` (one character),
+ * `[abc]` / `[!abc]` character classes, and `\x` escapes. Unbalanced
+ * brackets, empty classes, and trailing escapes throw at compile time — a
+ * bad glob must fail loudly at load, never silently match nothing at
+ * runtime.
+ *
+ * Catastrophic-backtracking defense, tuned per pattern flavor:
+ * - Glob output is fully machine-generated, so the backtracking degree is
+ *   exactly the number of star expansions: each `*`/`**` emits exactly one
+ *   unbounded quantifier and no group is ever emitted. {@link compileGlob}
+ *   therefore caps that count via `maxStars`.
+ * - User regexes (patternMode `regex`) are scanned structurally: a
+ *   quantifier applied to a group containing an unbounded quantifier, and a
+ *   quantified group whose literal alternation branches overlap, are
+ *   rejected at load. Chains of independent top-level quantifiers
+ *   (`\d+\.\d+\.\d+`) stay allowed — a documented, deliberate limitation:
+ *   regex mode is the escape hatch, glob mode is the guarded default.
+ * @module dsh-permission-rules/glob
+ */
+
+/** Raised by {@link compileGlob} on a syntactically invalid or over-quantified pattern. */
+export class GlobError extends TypeError {
+  constructor(message: string) {
+    super(message)
+    this.name = 'GlobError'
+  }
+}
+
+/** Compile options for {@link compileGlob}. */
+export interface GlobCompileOptions {
+  /** `true` keeps `*`/`?` inside one path segment (for `paths` patterns). */
+  readonly segments: boolean
+  /** Compile with the `i` flag so matching ignores ASCII case. */
+  readonly caseInsensitive?: boolean
+  /** Hard cap on unbounded star expansions; exceeding it throws. Unset = unlimited. */
+  readonly maxStars?: number
+}
+
+/**
+ * Compile one glob pattern to an anchored regular expression.
+ * @param pattern - the glob source.
+ * @param options - segment semantics, case handling, and the star cap.
+ * @returns a RegExp matching the whole candidate string.
+ * @throws {@link GlobError} on unbalanced `[`, empty classes, a trailing
+ *   escape, or more star expansions than `options.maxStars` allows.
+ */
+export function compileGlob(pattern: string, options: GlobCompileOptions): RegExp {
+  let out = ''
+  let stars = 0
+  let i = 0
+  while (i < pattern.length) {
+    const ch = pattern[i] as string
+    if (ch === '\\') {
+      const next = pattern[i + 1]
+      if (next === undefined) throw new GlobError(`glob ${JSON.stringify(pattern)} ends with a dangling escape`)
+      out += escapeRegExpChar(next)
+      i += 2
+      continue
+    }
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**` crosses path segments. Collapse runs of `**` and any
+        // following separator into one zero-or-more-any-depth group, so
+        // `a/**/b`, `a/**b`, and `a/***/b` all behave the same.
+        out += '.*'
+        stars += 1
+        i += 2
+        while (pattern[i] === '*') i += 1
+        if (pattern[i] === '/') i += 1
+        continue
+      }
+      // A single star never crosses a path separator.
+      out += options.segments ? '[^/]*' : '.*'
+      stars += 1
+      i += 1
+      continue
+    }
+    if (ch === '?') {
+      out += options.segments ? '[^/]' : '.'
+      i += 1
+      continue
+    }
+    if (ch === '[') {
+      const end = pattern.indexOf(']', i + 1)
+      if (end < 0) throw new GlobError(`glob ${JSON.stringify(pattern)} has an unbalanced "["`)
+      const body = pattern.slice(i + 1, end)
+      if (body.length === 0) throw new GlobError(`glob ${JSON.stringify(pattern)} has an empty character class`)
+      let content = body
+      let negate = false
+      if (content.startsWith('!')) {
+        negate = true
+        content = content.slice(1)
+      }
+      if (content.length === 0) throw new GlobError(`glob ${JSON.stringify(pattern)} has an empty character class`)
+      out += `[${negate ? '^' : ''}${content.replaceAll('\\', '\\\\')}]`
+      i = end + 1
+      continue
+    }
+    if (ch === ']') throw new GlobError(`glob ${JSON.stringify(pattern)} has an unbalanced "]"`)
+    out += escapeRegExpChar(ch)
+    i += 1
+  }
+  if (options.maxStars !== undefined && stars > options.maxStars) {
+    throw new GlobError(`glob ${JSON.stringify(pattern)} expands to ${stars} unbounded star quantifiers (max ${options.maxStars}); split it into several patterns`)
+  }
+  try {
+    return new RegExp(`^${out}$`, options.caseInsensitive === true ? 'iu' : 'u')
+  } catch (error) {
+    throw new GlobError(`glob ${JSON.stringify(pattern)} compiles to an invalid regular expression: ${String(error)}`)
+  }
+}
+
+/** Escape one literal character for a RegExp source. */
+function escapeRegExpChar(ch: string): string {
+  return /[.*+?^${}()|[\]\\/]/.test(ch) ? `\\${ch}` : ch
+}
+
+/**
+ * Compile one pattern as an unanchored regex, rejecting syntax errors and
+ * catastrophic-backtracking structures loudly.
+ * @param pattern - the regex source.
+ * @returns the compiled RegExp.
+ * @throws TypeError when the pattern is invalid, nests an unbounded
+ *   quantifier, or quantifies a group with overlapping literal alternation
+ *   branches.
+ */
+export function compilePatternRegex(pattern: string): RegExp {
+  let compiled: RegExp
+  try {
+    compiled = new RegExp(pattern, 'u')
+  } catch (error) {
+    throw new TypeError(`pattern ${JSON.stringify(pattern)} is not a valid regular expression: ${String(error)}`, { cause: error })
+  }
+  assertSafeRegexStructure(pattern)
+  return compiled
+}
+
+/**
+ * Structural ReDoS scan. Rejects (a) an unbounded quantifier (`*`, `+`,
+ * `{m,}`) applied to a group whose body contains an unbounded quantifier,
+ * and (b) a quantified group whose fully-literal alternation branches
+ * overlap as prefixes. Everything else — including chains of independent
+ * top-level quantifiers — compiles untouched.
+ * @param pattern - the already-syntax-valid regex source.
+ * @throws TypeError on a rejected structure.
+ */
+function assertSafeRegexStructure(pattern: string): void {
+  const stack: { start: number; unbounded: boolean }[] = []
+  let i = 0
+  const markUnbounded = (): void => {
+    const top = stack[stack.length - 1]
+    if (top !== undefined) top.unbounded = true
+  }
+  const reject = (message: string): never => {
+    throw new TypeError(`pattern ${JSON.stringify(pattern)} is rejected: ${message} risks catastrophic backtracking; restructure the pattern or use glob mode`)
+  }
+  while (i < pattern.length) {
+    const ch = pattern[i] as string
+    if (ch === '\\') {
+      i += 2
+      continue
+    }
+    if (ch === '[') {
+      i += 1
+      while (i < pattern.length && pattern[i] !== ']') {
+        if (pattern[i] === '\\') i += 1
+        i += 1
+      }
+      i += 1
+      continue
+    }
+    if (ch === '(') {
+      stack.push({ start: i, unbounded: false })
+      i += 1
+      continue
+    }
+    if (ch === ')') {
+      const group = stack.pop()
+      // An unbalanced `)` is invalid syntax; the compile above already rejected it.
+      if (group === undefined) {
+        i += 1
+        continue
+      }
+      const quantifier = quantifierAt(pattern, i + 1)
+      if (quantifier !== undefined) {
+        if (quantifier.unbounded) {
+          if (group.unbounded) {
+            reject(`quantifier ${quantifier.text} applies to a group containing an unbounded quantifier`)
+          }
+          if (hasAmbiguousAlternation(pattern, group.start + 1, i)) {
+            reject(`quantified group ${JSON.stringify(pattern.slice(group.start, quantifier.end + 1))} has overlapping alternation branches`)
+          }
+          markUnbounded()
+        }
+        i = quantifier.end + 1
+        continue
+      }
+      if (group.unbounded) markUnbounded()
+      i += 1
+      continue
+    }
+    if (ch === '*' || ch === '+') {
+      markUnbounded()
+      i += 1
+      continue
+    }
+    if (ch === '{') {
+      const parsed = parseBraceQuantifier(pattern, i)
+      if (parsed !== undefined) {
+        if (parsed.unbounded) markUnbounded()
+        i = parsed.end + 1
+        continue
+      }
+      // Not a quantifier (a `\p{L}`-style body is reached after its escape
+      // was skipped above): an ordinary literal.
+      i += 1
+      continue
+    }
+    // `?` is always bounded; literals, `.`, `|`, `^`, `$` pass through.
+    i += 1
+  }
+}
+
+/** One parsed quantifier token, when the character at `index` starts one. */
+function quantifierAt(pattern: string, index: number): { text: string; end: number; unbounded: boolean } | undefined {
+  const ch = pattern[index]
+  if (ch === '*' || ch === '+') return { text: ch, end: index, unbounded: true }
+  if (ch === '?') return { text: ch, end: index, unbounded: false }
+  if (ch === '{') return parseBraceQuantifier(pattern, index)
+  return undefined
+}
+
+/** Parse `{m}`, `{m,}`, or `{m,n}` at `start`; other braces are not quantifiers. */
+function parseBraceQuantifier(pattern: string, start: number): { text: string; end: number; unbounded: boolean } | undefined {
+  const close = pattern.indexOf('}', start + 1)
+  if (close < 0) return undefined
+  const body = pattern.slice(start + 1, close)
+  if (!/^\d+(,\d*)?$/.test(body)) return undefined
+  const unbounded = body.includes(',') && body.endsWith(',')
+  return { text: pattern.slice(start, close + 1), end: close, unbounded }
+}
+
+/**
+ * Whether a group body (between the parens) contains a top-level
+ * alternation with two fully-literal branches where one is a prefix of the
+ * other — the `(a|aa)+` ambiguity that makes repetition exponential.
+ * @param pattern - the full pattern.
+ * @param start - index just after the group's `(`.
+ * @param end - index of the group's `)`.
+ * @returns true when such an overlap exists.
+ */
+function hasAmbiguousAlternation(pattern: string, start: number, end: number): boolean {
+  const branches: string[] = []
+  let depth = 0
+  let branchStart = start
+  let hasPipe = false
+  for (let i = start; i < end; i += 1) {
+    const ch = pattern[i] as string
+    if (ch === '\\') {
+      i += 1
+      continue
+    }
+    if (ch === '[') {
+      while (i < end && pattern[i] !== ']') {
+        if (pattern[i] === '\\') i += 1
+        i += 1
+      }
+      continue
+    }
+    if (ch === '(') {
+      depth += 1
+      continue
+    }
+    if (ch === ')') {
+      depth -= 1
+      continue
+    }
+    if (ch === '|' && depth === 0) {
+      hasPipe = true
+      branches.push(pattern.slice(branchStart, i))
+      branchStart = i + 1
+    }
+  }
+  if (!hasPipe) return false
+  branches.push(pattern.slice(branchStart, end))
+  for (let a = 0; a < branches.length; a += 1) {
+    for (let b = a + 1; b < branches.length; b += 1) {
+      if (literalPrefixOf(branches[a] as string, branches[b] as string)) return true
+    }
+  }
+  return false
+}
+
+/** True when two fully-literal branches share their complete shorter text as a prefix. */
+function literalPrefixOf(x: string, y: string): boolean {
+  const literal = /^[^*+?()|[\]{}^$.\\]+$/
+  if (!literal.test(x) || !literal.test(y)) return false
+  const min = Math.min(x.length, y.length)
+  return x.slice(0, min) === y.slice(0, min)
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * `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.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`, and a stray default would discard
+ * `name`/`inject`/`Config`/`apply`).
+ * @module dsh-permission-rules
+ */
+
+import { apply } from './runtime.ts'
+
+export const name = 'permission-rules'
+export const inject = ['commands', 'tools']
+
+export { apply }
+export { PermissionRulesRuntime } from './runtime.ts'
+export * from './config.ts'
+export * from './events.ts'
+export * from './rules.ts'
+export * from './glob.ts'

package/src/prose.ts

@@ -0,0 +1,206 @@
+/**
+ * UI-facing prose for the `/rules` session command, per language. Only the
+ * command surface localizes: rule `reason`s are author-provided and are
+ * never translated, and logger diagnostics stay English for greppability.
+ * `en` and `zh` are the reference translations; `es`/`pt`/`hi` are
+ * community-quality.
+ * @module dsh-permission-rules/prose
+ */
+
+/** Supported command-output languages. */
+export type UiLanguage = 'en' | 'zh' | 'es' | 'pt' | 'hi'
+
+/** The localized strings one language provides for the command surface. */
+export interface UiProse {
+  /** Header line naming the active rules, their sources, and the workspace. */
+  rulesHeader: (count: number, sources: readonly string[], cwd: string) => string
+  /** Line shown when no rule file is in effect. */
+  noRules: (cwd: string, fallbackNote: string) => string
+  /** Note appended when a fallback path is configured but missing. */
+  fallbackMissing: string
+  /** Success line of `/rules reload`. */
+  reloaded: (count: number, source: string) => string
+  /** Error line of a failed reload. */
+  reloadFailed: (error: string) => string
+  /** Warning appended to a listing whose last reload failed. */
+  lastReloadWarning: (error: string) => string
+  /** Rejection of an unknown `/rules` argument. */
+  unknownArg: (arg: string) => string
+  /** Usage hint. */
+  usage: string
+  /** Header for `/rules decisions` when decisions exist. */
+  decisionsHeader: (shown: number, total: number) => string
+  /** Line shown when the session log holds no audit decisions. */
+  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
+  /** 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
+  /** Usage hint of `/rules test`. */
+  testUsage: string
+  /** Warning naming shadowed (unreachable) rules by 1-based number. */
+  unreachableWarning: (numbers: readonly number[]) => string
+  /** Empty-source placeholder in the rules header. */
+  emptySource: string
+}
+
+/** Tokens `describeRule` uses for its match-dimension prefixes. */
+export interface DescribeTokens {
+  allTools: string
+  tools: string
+  params: string
+  paths: string
+  absent: string
+  when: string
+  platform: string
+  disabled: string
+  tags: string
+}
+
+/** Truncate long reasons/descriptions in one-line displays. */
+function short(text: string, limit = 120): string {
+  return text.length > limit ? `${text.slice(0, limit)}…` : text
+}
+
+const EN: UiProse = {
+  rulesHeader: (count, sources, cwd) => `Permission rules: ${count} rule(s) from ${sources.join(', ')} (workspace ${cwd}).`,
+  noRules: (cwd, fallbackNote) => `No permission rules active: no rule file found for workspace ${cwd}${fallbackNote}; the empty rule set passes everything through.`,
+  fallbackMissing: ' (and the configured fallback path is missing)',
+  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.`,
+  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) => {
+    const rule = ruleIndex === undefined ? '' : ` (rule ${ruleIndex + 1})`
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- #${seq} ${action} ${toolName}${rule}${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"}',
+  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)',
+}
+
+const ZH: UiProse = {
+  rulesHeader: (count, sources, cwd) => `权限规则：共 ${count} 条，来自 ${sources.join('、')}（工作区 ${cwd}）。`,
+  noRules: (cwd, fallbackNote) => `当前没有生效的权限规则：工作区 ${cwd} 未找到规则文件${fallbackNote}；空规则集全部放行。`,
+  fallbackMissing: '（且配置的回退路径不存在）',
+  reloaded: (count, source) => `已重载 ${count} 条规则，来自 ${source}。`,
+  reloadFailed: error => `重载失败：${error}。之前的规则仍然生效。`,
+  lastReloadWarning: error => `警告：上次重载失败（${error}）；以上列出的是之前的规则。`,
+  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) => {
+    const rule = ruleIndex === undefined ? '' : `（规则 ${ruleIndex + 1}）`
+    const why = reason === undefined ? '' : `：${short(reason)}`
+    return `- #${seq} ${action} ${toolName}${rule}${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"}',
+  unreachableWarning: numbers => `警告：规则 ${numbers.join('、')} 不可达（被前面的通配规则遮蔽）。`,
+  emptySource: '（无规则文件——空规则集）',
+}
+
+const ES: UiProse = {
+  rulesHeader: (count, sources, cwd) => `Reglas de permiso: ${count} regla(s) desde ${sources.join(', ')} (espacio de trabajo ${cwd}).`,
+  noRules: (cwd, fallbackNote) => `No hay reglas de permiso activas: no se encontró archivo de reglas para el espacio de trabajo ${cwd}${fallbackNote}; el conjunto vacío lo permite todo.`,
+  fallbackMissing: ' (y la ruta de respaldo configurada no existe)',
+  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.`,
+  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) => {
+    const rule = ruleIndex === undefined ? '' : ` (regla ${ruleIndex + 1})`
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- #${seq} ${action} ${toolName}${rule}${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"}',
+  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)',
+}
+
+const PT: UiProse = {
+  rulesHeader: (count, sources, cwd) => `Regras de permissão: ${count} regra(s) de ${sources.join(', ')} (workspace ${cwd}).`,
+  noRules: (cwd, fallbackNote) => `Nenhuma regra de permissão ativa: nenhum arquivo de regras encontrado para o workspace ${cwd}${fallbackNote}; o conjunto vazio permite tudo.`,
+  fallbackMissing: ' (e o caminho de fallback configurado não existe)',
+  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.`,
+  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) => {
+    const rule = ruleIndex === undefined ? '' : ` (regra ${ruleIndex + 1})`
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- #${seq} ${action} ${toolName}${rule}${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"}',
+  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)',
+}
+
+const HI: UiProse = {
+  rulesHeader: (count, sources, cwd) => `अनुमति नियम: ${count} नियम, स्रोत ${sources.join(', ')} (कार्यक्षेत्र ${cwd})।`,
+  noRules: (cwd, fallbackNote) => `कोई अनुमति नियम सक्रिय नहीं: कार्यक्षेत्र ${cwd} के लिए नियम फ़ाइल नहीं मिली${fallbackNote}; खाली नियम-समूह सब कुछ पास कर देता है।`,
+  fallbackMissing: ' (और कॉन्फ़िगर किया गया फ़ॉलबैक पथ मौजूद नहीं है)',
+  reloaded: (count, source) => `${count} नियम पुनः लोड किए गए, स्रोत ${source}।`,
+  reloadFailed: error => `पुनः लोड विफल: ${error}। पिछले नियम अब भी सक्रिय हैं।`,
+  lastReloadWarning: error => `चेतावनी: अंतिम पुनः लोड विफल रहा (${error}); ऊपर सूचीबद्ध नियम पिछले वाले हैं।`,
+  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) => {
+    const rule = ruleIndex === undefined ? '' : ` (नियम ${ruleIndex + 1})`
+    const why = reason === undefined ? '' : `: ${short(reason)}`
+    return `- #${seq} ${action} ${toolName}${rule}${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"}',
+  unreachableWarning: numbers => `चेतावनी: नियम ${numbers.join(', ')} अप्राप्य हैं (पहले वाले सर्व-मिलान नियम से ढके हुए)।`,
+  emptySource: '(कोई नियम फ़ाइल नहीं — खाली नियम-समूह)',
+}
+
+/** The localized prose tables by language. */
+export const UI_PROSE: Readonly<Record<UiLanguage, UiProse>> = { en: EN, zh: ZH, es: ES, pt: PT, hi: HI }
+
+/** `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: 'टैग' },
+}