@milpa/comal 0.1.6 → 0.2.0

package/src/permission-controls.mjs

@@ -0,0 +1,232 @@
+import { PERMISSION_MODES, BYPASS_PERMISSION_MODE } from './permissions.mjs';
+import { parseRule, ruleText, scopeText, RULE_LISTS } from './permission-rules.mjs';
+import { t, languageInfo, registerMessages } from './i18n/index.mjs';
+
+// Controles humanos de permisos: /permissions y /autonomy. Son operaciones
+// audience:'human' sin permiso de herramienta: el modelo, los subagentes y CodeRun
+// no las ven. La autoridad vive con el host: el archivo de reglas está fuera del
+// workspace y sólo estas operaciones (y la tarjeta de permiso) lo escriben.
+
+registerMessages({
+  'Only reads and inspects; every change is denied.': 'Sólo lee e inspecciona; todo cambio se deniega.',
+  'Free reads; changes, Bash and external effects ask you.': 'Lecturas libres; cambios, Bash y efectos externos te preguntan.',
+  'Also accepts Write/Edit inside the workspace; Bash and MCP still ask.': 'Además acepta Write/Edit dentro del workspace; Bash y MCP siguen preguntando.',
+  'The guard and the classifier decide based on your request; doubtful actions ask you and destructive ones you did not request are denied.': 'El guardia y el clasificador deciden según tu pedido; lo dudoso te pregunta y lo destructivo sin pedido se deniega.',
+  'Use /permissions [MODE | allow|ask|deny RULE [--session|--project|--user] | remove RULE [--session|--project|--user]].': 'Usa /permissions [MODO | allow|ask|deny REGLA [--sesion|--proyecto|--usuario] | remove REGLA [--sesion|--proyecto|--usuario]].',
+  'Unknown scope {flag}. {usage}': 'Alcance desconocido {flag}. {usage}',
+  'Use /autonomy [observe|assist|edit|autonomous].': 'Usa /autonomy [observar|asistir|editar|autonomo].',
+  'Autonomy: startup bypass (bypassPermissions). It can only be chosen at startup with --dangerously-skip-permissions; /autonomy neither enables nor changes it.': 'Autonomía: sin permisos de arranque (bypassPermissions). Sólo se elige al arrancar con --dangerously-skip-permissions; /autonomy no la activa ni la cambia.',
+  'Autonomy: {level} (mode {mode})': 'Autonomía: {level} (modo {mode})',
+  'Autonomy: {level} → mode {mode}. {summary}': 'Autonomía: {level} → modo {mode}. {summary}',
+  'The deny, ask and allow rules of /permissions apply at every level; confirm:"always" always asks (in observe it is denied).': 'Las reglas deny, ask y allow de /permissions aplican en todos los niveles; confirm:"always" pregunta siempre (en observar se deniega).',
+  'Bash: any command.': 'Bash: cualquier comando.',
+  'The tool {name} with any arguments.': 'La herramienta {name} con cualquier argumento.',
+  'All plugin__{plugin}__* operations.': 'Todas las operaciones plugin__{plugin}__*.',
+  'The operations of group {group} declared by plugin {plugin}.': 'Las operaciones del grupo {group} que declara el plugin {plugin}.',
+  'All tools of MCP server {server} (mcp__{server}__*).': 'Todas las herramientas del servidor MCP {server} (mcp__{server}__*).',
+  'Any Bash command.': 'Cualquier comando Bash.',
+  'A single simple command that starts with the words «{words}». It does not cover compound commands (; && || | &), substitutions ($() ``), expansions ($VAR), redirections (< >) or commands the guard vetoes. As deny/ask, it covers any command containing those words.': 'Un único comando simple que empieza con las palabras «{words}». No cubre comandos compuestos (; && || | &), sustituciones ($() ``), expansiones ($VAR), redirecciones (< >) ni comandos que el guardia veta. Como deny/ask, cubre cualquier comando que contenga esas palabras.',
+  'Exactly the command «{command}». As deny/ask, also when it appears as part of a compound command.': 'Exactamente el comando «{command}». Como deny/ask, también cuando aparece como parte de un comando compuesto.',
+  '{tool} with a file_path inside the project matching {glob} (* does not cross /, ** does).': '{tool} con file_path dentro del proyecto que coincide con {glob} (* no cruza /, ** sí).',
+  'WebFetch to {domain} and its subdomains.': 'WebFetch a {domain} y sus subdominios.',
+  'you, on the card (saved «{rule}»)': 'tú, en la tarjeta (guardó «{rule}»)',
+  'rule «{rule}»': 'regla «{rule}»',
+  'guard {guard}': 'guardia {guard}',
+  'startup bypass': 'arranque sin permisos',
+  'session policy ({mode})': 'política de la sesión ({mode})',
+  'you, on the card': 'tú, en la tarjeta',
+  'you or no human': 'tú o sin humano',
+  'plan mode': 'modo plan',
+  'native read': 'lectura nativa',
+  'delegation': 'delegación',
+  'auto (guard/classifier)': 'auto (guardia/clasificador)',
+  'This session has no project; use --session or --user.': 'Esta sesión no tiene proyecto; usa --sesion o --usuario.',
+  'Mode: {mode}': 'Modo: {mode}',
+  ' · autonomy {level}': ' · autonomía {level}',
+  ' · fixed for this process; only denials apply': ' · fijo para este proceso; sólo las denegaciones aplican',
+  ' · change it with /permissions MODE, /autonomy LEVEL or Shift+Tab': ' · cambia con /permissions MODO, /autonomy NIVEL o Shift+Tab',
+  'Rules: {file}': 'Reglas: {file}',
+  'Session (in memory; lost on exit)': 'Sesión (en memoria; se pierden al salir)',
+  'Project {project}': 'Proyecto {project}',
+  '(no project)': '(ninguno)',
+  'User (all projects)': 'Usuario (todos los proyectos)',
+  '  (no rules)': '  (ninguna)',
+  '{count} rule(s) from other projects do not apply here.': '{count} regla(s) de otros proyectos no aplican aquí.',
+  'Startup: --allowed-tools {allowed} · --disallowed-tools {denied}': 'Arranque: --allowed-tools {allowed} · --disallowed-tools {denied}',
+  'Precedence: --disallowed-tools/deny > startup bypass > confirm:"always" > ask > plan/reads/allow > mode.': 'Precedencia: --disallowed-tools/deny > arranque sin permisos > confirm:"always" > ask > plan/lecturas/allow > modo.',
+  'Latest decisions:': 'Últimas decisiones:',
+  '  (none in this session)': '  (ninguna en esta sesión)',
+  'There is no permission rule store.': 'No hay almacén de reglas de permiso.',
+  'Broad rule: {why} Denials still win, but this stops asking you.': 'Regla amplia: {why} Las denegaciones siguen ganando, pero esto deja de preguntarte.',
+  '{warning} Confirm it in the TUI; -p cannot confirm it.': '{warning} Confírmala en la TUI; -p no puede confirmarla.',
+  '{rule} was not saved: you did not confirm the broad rule.': 'No se guardó {rule}: no confirmaste la regla amplia.',
+  'Saved {rule} · in memory only.': 'Guardada {rule} · sólo en memoria.',
+  'Saved {rule} · {file}.': 'Guardada {rule} · {file}.',
+  'Covers: {what}': 'Cubre: {what}',
+  'Note: there is a deny or ask rule with the same pattern, and it wins.': 'Nota: hay una regla deny o ask con el mismo patrón, y gana.',
+  'Note: in plan, allow does not turn changes into reads.': 'Nota: en plan, allow no convierte cambios en lecturas.',
+  'There is no rule «{rule}» in this session, this project or your user.': 'No hay regla «{rule}» en esta sesión, este proyecto ni tu usuario.',
+  '«{rule}» is in several scopes ({scopes}); pass --session, --project or --user.': '«{rule}» está en varios alcances ({scopes}); indica --sesion, --proyecto o --usuario.',
+  'There is no rule «{rule}» in {scope}.': 'No hay regla «{rule}» en {scope}.',
+  'Removed {rules}.': 'Quitada {rules}.',
+  'Removed {count} rules: {rules}.': 'Quitadas {rules}.',
+});
+
+// Nombres canónicos en inglés; los españoles siguen aceptándose como alias. Sólo el
+// modo (plan, default…) se persiste: el nivel es una etiqueta de la interfaz.
+export const AUTONOMY_LEVELS = Object.freeze([
+  Object.freeze({ level: 'observe', mode: 'plan', summary: 'Only reads and inspects; every change is denied.' }),
+  Object.freeze({ level: 'assist', mode: 'default', summary: 'Free reads; changes, Bash and external effects ask you.' }),
+  Object.freeze({ level: 'edit', mode: 'acceptEdits', summary: 'Also accepts Write/Edit inside the workspace; Bash and MCP still ask.' }),
+  Object.freeze({ level: 'autonomous', mode: 'auto', summary: 'The guard and the classifier decide based on your request; doubtful actions ask you and destructive ones you did not request are denied.' }),
+]);
+const LEVEL_ALIASES = { observe: 'observe', assist: 'assist', edit: 'edit', autonomous: 'autonomous', observar: 'observe', asistir: 'assist', editar: 'edit', autonomo: 'autonomous', 'autónomo': 'autonomous' };
+const LEVEL_NAMES_ES = { observe: 'observar', assist: 'asistir', edit: 'editar', autonomous: 'autonomo' };
+/** Nombre visible del nivel en el idioma de la interfaz. */
+export const levelName = level => languageInfo().language === 'es' ? LEVEL_NAMES_ES[level] || level : level;
+export const levelSummary = item => t(item.summary);
+const SCOPE_FLAGS = { '--session': 'session', '--sesion': 'session', '--sesión': 'session', '--project': 'project', '--proyecto': 'project', '--user': 'user', '--usuario': 'user' };
+const usage = () => t('Use /permissions [MODE | allow|ask|deny RULE [--session|--project|--user] | remove RULE [--session|--project|--user]].');
+const clip = (text, size) => { const value = String(text ?? '').replace(/\s+/g, ' ').trim(); return value.length > size ? value.slice(0, size - 1) + '…' : value; };
+
+/** Texto → { name, input } para /permissions. MODE se devuelve como { mode }. */
+export function parsePermissionsCommand(text = '') {
+  const trimmed = text.trim();
+  if (!trimmed) return { name: 'PermissionsShow', input: {} };
+  const [action] = trimmed.split(/\s+/);
+  if (PERMISSION_MODES.includes(trimmed)) return { mode: trimmed };
+  if (![...RULE_LISTS, 'remove'].includes(action)) throw new Error(usage());
+  let rest = trimmed.slice(action.length).trim(), scope;
+  const flag = /\s(--[\p{L}-]+)$/u.exec(' ' + rest);
+  if (flag) { if (!SCOPE_FLAGS[flag[1]]) throw new Error(t('Unknown scope {flag}. {usage}', { flag: flag[1], usage: usage() })); scope = SCOPE_FLAGS[flag[1]]; rest = rest.slice(0, rest.length - flag[1].length).trim(); }
+  if (!rest) throw new Error(usage());
+  if (action === 'remove') return { name: 'PermissionRuleRemove', input: { rule: rest, ...(scope ? { scope } : {}) } };
+  return { name: 'PermissionRuleAdd', input: { list: action, rule: rest, scope: scope || 'project' } };
+}
+
+/** Texto → modo para /autonomy, o null para mostrar. */
+export function parseAutonomy(text = '') {
+  const value = text.trim().toLowerCase();
+  if (!value) return null;
+  const level = LEVEL_ALIASES[value];
+  if (!level) throw new Error(t('Use /autonomy [observe|assist|edit|autonomous].'));
+  return AUTONOMY_LEVELS.find(item => item.level === level);
+}
+export const autonomyOf = mode => AUTONOMY_LEVELS.find(item => item.mode === mode) || null;
+
+export function autonomyText(mode) {
+  const current = autonomyOf(mode);
+  const lines = [mode === BYPASS_PERMISSION_MODE ? t('Autonomy: startup bypass (bypassPermissions). It can only be chosen at startup with --dangerously-skip-permissions; /autonomy neither enables nor changes it.') : t('Autonomy: {level} (mode {mode})', { level: current ? levelName(current.level) : mode, mode }), ''];
+  for (const item of AUTONOMY_LEVELS) lines.push(`${item.mode === mode ? '●' : '○'} ${levelName(item.level).padEnd(10)} ${item.mode.padEnd(11)} ${levelSummary(item)}`);
+  lines.push('', t('The deny, ask and allow rules of /permissions apply at every level; confirm:"always" always asks (in observe it is denied).'));
+  return lines.join('\n');
+}
+/** Confirmación de /autonomy NIVEL tras cambiar el modo. */
+export const autonomyChangedText = item => t('Autonomy: {level} → mode {mode}. {summary}', { level: levelName(item.level), mode: item.mode, summary: levelSummary(item) });
+
+/** Qué cubre exactamente una regla, en palabras. */
+export function explainRule(text) {
+  const parsed = parseRule(text);
+  switch (parsed.kind) {
+    case 'tool': return parsed.name === 'Bash' ? t('Bash: any command.') : t('The tool {name} with any arguments.', { name: parsed.name });
+    case 'group': return parsed.group === 'all' ? t('All plugin__{plugin}__* operations.', { plugin: parsed.plugin }) : t('The operations of group {group} declared by plugin {plugin}.', { group: parsed.group, plugin: parsed.plugin });
+    case 'mcp-server': return t('All tools of MCP server {server} (mcp__{server}__*).', { server: parsed.server });
+    case 'bash-any': return t('Any Bash command.');
+    case 'bash-prefix': return t('A single simple command that starts with the words «{words}». It does not cover compound commands (; && || | &), substitutions ($() ``), expansions ($VAR), redirections (< >) or commands the guard vetoes. As deny/ask, it covers any command containing those words.', { words: parsed.words.join(' ') });
+    case 'bash-exact': return t('Exactly the command «{command}». As deny/ask, also when it appears as part of a compound command.', { command: parsed.command });
+    case 'path': return t('{tool} with a file_path inside the project matching {glob} (* does not cross /, ** does).', { tool: parsed.tool, glob: parsed.glob });
+    case 'domain': return t('WebFetch to {domain} and its subdomains.', { domain: parsed.domain });
+    default: return text;
+  }
+}
+
+// Las razones del libro (row.reason) son texto del host en inglés; aquí sólo se elige la etiqueta.
+function decider(row) {
+  if (row.rule && String(row.reason || '').startsWith('User confirmation')) return t('you, on the card (saved «{rule}»)', { rule: row.rule });
+  if (row.rule) return t('rule «{rule}»', { rule: row.rule });
+  if (row.permission_source === 'confirm_always' || /confirm:"always"/.test(row.reason || '')) return 'confirm:"always"';
+  const reason = row.reason || '';
+  if (row.source === 'plugin_guard') return t('guard {guard}', { guard: row.guard || '' }).trim();
+  if (reason === 'Explicit denial rule') return '--disallowed-tools';
+  if (reason.startsWith('Explicit startup --dangerously-skip-permissions')) return t('startup bypass');
+  if (reason === 'Session policy') return t('session policy ({mode})', { mode: row.mode });
+  if (reason.startsWith('User confirmation')) return t('you, on the card');
+  if (reason === 'No authorization for this tool') return t('you or no human');
+  if (reason.startsWith('Plan mode')) return t('plan mode');
+  if (reason.startsWith('Native read-only')) return t('native read');
+  if (reason.startsWith('Delegation')) return t('delegation');
+  return row.mode === 'auto' ? t('auto (guard/classifier)') : row.mode || '—';
+}
+
+export class PermissionControls {
+  constructor({ policy, rules = policy.rules, decisions = async () => [], confirm } = {}) {
+    Object.assign(this, { policy, decisions, confirm });
+    this.rules = rules;
+  }
+  #scope(scope) {
+    if (scope === 'session' || scope === 'user') return scope;
+    if (!this.rules?.scope) throw new Error(t('This session has no project; use --session or --user.'));
+    return this.rules.scope;
+  }
+  async show() {
+    const policy = this.policy, rules = this.rules, mode = policy.mode, level = autonomyOf(mode);
+    const lines = [t('Mode: {mode}', { mode }) + (level ? t(' · autonomy {level}', { level: levelName(level.level) }) : '') + (mode === BYPASS_PERMISSION_MODE ? t(' · fixed for this process; only denials apply') : t(' · change it with /permissions MODE, /autonomy LEVEL or Shift+Tab'))];
+    if (rules) lines.push(t('Rules: {file}', { file: rules.file }) + (rules.warning ? ` · ${rules.warning}` : ''));
+    const all = rules ? rules.applicable() : [], others = rules ? rules.list().filter(rule => rule.scope !== 'user' && rule.scope !== rules.scope).length : 0;
+    const sections = [[t('Session (in memory; lost on exit)'), 'session'], [t('Project {project}', { project: rules?.project || t('(no project)') }), rules?.scope], [t('User (all projects)'), 'user']];
+    for (const [title, scope] of sections) {
+      const own = all.filter(rule => rule.scope === scope);
+      lines.push('', `${title}:`);
+      if (!own.length) { lines.push(t('  (no rules)')); continue; }
+      for (const list of RULE_LISTS) for (const rule of own.filter(item => item.list === list)) lines.push(`  ${list.padEnd(5)} ${rule.rule}`);
+    }
+    if (others) lines.push('', t('{count} rule(s) from other projects do not apply here.', { count: others }));
+    if (policy.allowed?.size || policy.denied?.size) lines.push('', t('Startup: --allowed-tools {allowed} · --disallowed-tools {denied}', { allowed: [...policy.allowed].join(',') || '—', denied: [...policy.denied].join(',') || '—' }));
+    lines.push('', t('Precedence: --disallowed-tools/deny > startup bypass > confirm:"always" > ask > plan/reads/allow > mode.'));
+    // Los controles humanos (audience:'human') no son decisiones de permiso; se omiten.
+    const rows = (await this.decisions()).filter(row => row?.type === 'house_decision' && !String(row.reason || '').startsWith('Explicit user control')).slice(-10);
+    lines.push('', t('Latest decisions:'));
+    if (!rows.length) lines.push(t('  (none in this session)'));
+    for (const row of rows) lines.push(`  ${row.allowed ? '✓' : '✗'} ${String(row.timestamp || row.at || '').slice(11, 19) || '        '} ${row.operation} · ${decider(row)} · ${clip(row.reason, 90)}`);
+    return lines.join('\n');
+  }
+  async add({ list, rule, scope = 'project' }, options = {}) {
+    if (!this.rules) throw new Error(t('There is no permission rule store.'));
+    const parsed = parseRule(rule), target = this.#scope(scope);
+    if (parsed.broad && list === 'allow') {
+      const warning = t('Broad rule: {why} Denials still win, but this stops asking you.', { why: parsed.broad });
+      if (!this.confirm) throw new Error(t('{warning} Confirm it in the TUI; -p cannot confirm it.', { warning }));
+      const accepted = await this.confirm('PermissionRuleBroad', { rule, list, scope: scopeText(target), warning }, options);
+      if (!(accepted === true || accepted?.allowed === true)) return t('{rule} was not saved: you did not confirm the broad rule.', { rule });
+    }
+    const saved = await this.rules.add({ list, rule, scope: target });
+    const lines = [target === 'session' ? t('Saved {rule} · in memory only.', { rule: ruleText(saved) }) : t('Saved {rule} · {file}.', { rule: ruleText(saved), file: this.rules.file }), t('Covers: {what}', { what: explainRule(rule) })];
+    if (list === 'allow' && this.rules.applicable().some(item => item.list !== 'allow' && item.rule === rule)) lines.push(t('Note: there is a deny or ask rule with the same pattern, and it wins.'));
+    if (list === 'allow' && this.policy.mode === 'plan') lines.push(t('Note: in plan, allow does not turn changes into reads.'));
+    return lines.join('\n');
+  }
+  async remove({ rule, scope }) {
+    if (!this.rules) throw new Error(t('There is no permission rule store.'));
+    let target = scope ? this.#scope(scope) : null;
+    if (!target) {
+      const scopes = [...new Set(this.rules.applicable().filter(item => item.rule === rule).map(item => item.scope))];
+      if (!scopes.length) throw new Error(t('There is no rule «{rule}» in this session, this project or your user.', { rule }));
+      if (scopes.length > 1) throw new Error(t('«{rule}» is in several scopes ({scopes}); pass --session, --project or --user.', { rule, scopes: scopes.map(scopeText).join(', ') }));
+      [target] = scopes;
+    }
+    const removed = await this.rules.remove({ rule, scope: target });
+    if (!removed.length) throw new Error(t('There is no rule «{rule}» in {scope}.', { rule, scope: scopeText(target) }));
+    const rules = removed.map(ruleText).join('; ');
+    return removed.length > 1 ? t('Removed {count} rules: {rules}.', { count: removed.length, rules }) : t('Removed {rules}.', { rules });
+  }
+  /** Publica los controles como operaciones humanas: sin permiso de herramienta, invisibles para el modelo. */
+  register(registry) {
+    const object = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+    const rule = { type: 'string', minLength: 1, maxLength: 512 }, scope = { enum: ['session', 'project', 'user'] };
+    for (const definition of [
+      { name: 'PermissionsShow', description: 'Human reads the permission mode, saved rules by scope and the last decisions.', input_schema: object(), run: () => this.show() },
+      { name: 'PermissionRuleAdd', description: 'Human saves an allow/ask/deny permission rule for this session, project or user.', input_schema: object({ list: { enum: RULE_LISTS }, rule, scope }, ['list', 'rule', 'scope']), run: (input, options) => this.add(input, options) },
+      { name: 'PermissionRuleRemove', description: 'Human removes a saved permission rule.', input_schema: object({ rule, scope }, ['rule']), run: input => this.remove(input) },
+    ]) registry.add({ ...definition, audience: 'human', surfaces: ['cli', 'tui'], permission: null, effects: { workspace: 'none', external: 'none', process: 'none', authority: 'permission_control' } });
+  }
+}

package/src/permission-rules.mjs

@@ -0,0 +1,312 @@
+import { lstat, open, readFile, rename, rm } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { ensurePrivateDirectory, assertPrivateDirectory, assertPrivateFile } from './private-fs.mjs';
+import { shellCommands, inspectAutoAction } from './auto-guard.mjs';
+import { t, registerMessages } from './i18n/index.mjs';
+
+registerMessages({
+  'Permission rule: empty or too long pattern.': 'Regla de permiso: patrón vacío o demasiado largo.',
+  'Permission rule: invalid pattern {text} (control characters).': 'Regla de permiso: patrón inválido {text} (caracteres de control).',
+  'Bash without parentheses authorizes any command.': 'Bash sin paréntesis autoriza cualquier comando.',
+  'Permission rule: pattern too broad or not supported {text}. Use mcp__server__*, plugin:ID:all or Bash(prefix:*).': 'Regla de permiso: patrón demasiado amplio o no admitido {text}. Usa mcp__servidor__*, plugin:ID:all o Bash(prefijo:*).',
+  'Permission rule: invalid pattern {text}. Only Bash, Edit, Write and WebFetch accept parentheses.': 'Regla de permiso: patrón inválido {text}. Sólo Bash, Edit, Write y WebFetch aceptan paréntesis.',
+  'Permission rule: invalid pattern {text}': 'Regla de permiso: patrón inválido {text}',
+  'Permission rule: invalid pattern {text} (empty parentheses).': 'Regla de permiso: patrón inválido {text} (paréntesis vacíos).',
+  'Permission rule: Bash(:*) has no prefix; use Bash(*) if you really want any command.': 'Regla de permiso: Bash(:*) no tiene prefijo; usa Bash(*) si de verdad quieres cualquier comando.',
+  'Bash(*) authorizes any command, including deletions and network access.': 'Bash(*) autoriza cualquier comando, incluidos borrados y red.',
+  'Permission rule: Bash(:*) has no prefix.': 'Regla de permiso: Bash(:*) no tiene prefijo.',
+  'Permission rule: the prefix of {text} only accepts plain words, without operators, quotes or wildcards.': 'Regla de permiso: el prefijo de {text} sólo admite palabras simples, sin operadores, comillas ni comodines.',
+  '{word} runs other programs: the prefix is equivalent to full Bash.': '{word} ejecuta otros programas: el prefijo equivale a Bash completo.',
+  'Permission rule: {text} is not a prefix. Use Bash(prefix:*) for a prefix or the exact command.': 'Regla de permiso: {text} no es un prefijo. Usa Bash(prefijo:*) para un prefijo o el comando exacto.',
+  'Permission rule: {text} must be WebFetch(domain:example.com).': 'Regla de permiso: {text} debe ser WebFetch(domain:ejemplo.com).',
+  'Permission rule: {text} must be a path or glob relative to the project, without .. or absolute paths.': 'Regla de permiso: {text} debe ser una ruta o glob relativo al proyecto, sin .. ni rutas absolutas.',
+  '{target} covers the whole project.': '{target} cubre todo el proyecto.',
+  '{file} is inside the workspace; it is ignored because the model tools could write it. Move XDG_CONFIG_HOME outside the project.': '{file} está dentro del workspace; se ignora porque las herramientas del modelo podrían escribirlo. Mueve XDG_CONFIG_HOME fuera del proyecto.',
+  '{file} exceeds 256 KiB.': '{file} supera 256 KiB.',
+  '{file} is inside the workspace; it is not written.': '{file} está dentro del workspace; no se escribe.',
+  'Invalid permission rule.': 'Regla de permiso inválida.',
+  'Permission rule: unknown field {key}': 'Regla de permiso: campo desconocido {key}',
+  'Permission rule: list must be allow, ask or deny.': 'Regla de permiso: list debe ser allow, ask o deny.',
+  'Permission rule: invalid pattern {rule}. {reason}': 'Regla de permiso: patrón inválido {rule}. {reason}',
+  'Permission rule: scope must be user or project:<absolute path>.': 'Regla de permiso: scope debe ser user o project:<ruta absoluta>.',
+  'Permission rule: added_at and source:"human" are required.': 'Regla de permiso: added_at y source:"human" requeridos.',
+  'Unrecognized permission rules format.': 'Formato de reglas de permiso no reconocido.',
+  'Permission rules ignored: {reason}': 'Reglas de permiso ignoradas: {reason}',
+  '{warning} Fix or delete {file} manually.': '{warning} Corrige o elimina {file} manualmente.',
+  'At most {max} rules.': 'Máximo {max} reglas.',
+  'At most {max} session rules.': 'Máximo {max} reglas de sesión.',
+  'scope:user': 'usuario', 'scope:session': 'sesión',
+  '{list} rule «{rule}» ({scope})': 'regla {list} «{rule}» ({scope})',
+});
+
+// Reglas de permiso guardadas por el humano, por usuario y fuera del workspace.
+// Las lee PermissionPolicy; las escriben sólo controles humanos (/plugins allow,
+// /permissions y «sí, siempre» desde la tarjeta de permiso). Formato:
+// { version: 1, rules: [{ list: 'allow'|'ask'|'deny', rule, scope: 'user'|'project:<ruta>', added_at, source: 'human' }] }
+// Las reglas de sesión (scope 'session') viven sólo en memoria y nunca se escriben.
+// Diferencia deliberada con Claude Code: no hay archivo de reglas dentro del repo,
+// porque las herramientas del modelo podrían editarlo. Las de proyecto se guardan
+// por usuario, ligadas a la ruta absoluta del proyecto.
+const VERSION = 1, MAX_BYTES = 256 * 1024, MAX_RULES = 512, MAX_RULE = 512;
+export const RULE_LISTS = Object.freeze(['deny', 'ask', 'allow']);
+const TOOL = /^[A-Za-z][A-Za-z0-9_-]{0,127}$/, GROUP = /^plugin:([a-z][a-z0-9]*(?:-[a-z0-9]+)*):(observe|actions|all)$/;
+const MCP_SERVER = /^mcp__([a-zA-Z0-9_-]{1,32})__\*$/, PARAMETRIC = /^(Bash|Edit|Write|WebFetch)\(([\s\S]*)\)$/;
+const DOMAIN = /^domain:((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,62})$/;
+// Primeras palabras que ejecutan otra cosa: un prefijo con ellas equivale a Bash completo.
+const WRAPPERS = new Set(['sh', 'bash', 'zsh', 'fish', 'dash', 'ksh', 'env', 'xargs', 'eval', 'exec', 'command', 'builtin', 'sudo', 'su', 'doas', 'timeout', 'nice', 'nohup', 'busybox', 'time', 'watch', 'stdbuf', 'setsid', 'npx', 'pnpx', 'bunx', 'node', 'deno', 'bun', 'python', 'python3', 'ruby', 'perl', 'php', 'lua', 'source', '.']);
+const fail = (message, code = 'PERMISSION_RULES_INVALID', extra = {}) => Object.assign(new Error(message), { code, ...extra });
+// Errores de patrón que validateRule muestra tal cual (sin volver a prefijarlos).
+const invalidPattern = message => fail(message, 'PERMISSION_RULES_INVALID', { invalidPattern: true });
+const inside = (root, file) => { const relative = path.relative(root, file); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)); };
+
+export const permissionRulesFile = (env = process.env) => path.resolve(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'comal', 'permissions.json');
+export const projectScope = cwd => `project:${path.resolve(cwd)}`;
+export const parseGroup = rule => { const match = GROUP.exec(rule); return match ? { plugin: match[1], group: match[2] } : null; };
+
+/**
+ * Analiza una regla. Formas admitidas:
+ *   Tool                      nombre exacto (incluye mcp__srv__tool y plugin__ID__Op)
+ *   mcp__srv__*               todas las herramientas de un servidor MCP
+ *   plugin:ID:observe|actions|all
+ *   Bash(prefijo:*)           un único comando simple cuyas primeras palabras son el prefijo
+ *   Bash(comando exacto)      el texto exacto del comando
+ *   Bash(*)                   cualquier Bash (amplia)
+ *   Edit(glob) / Write(glob)  file_path relativo al proyecto
+ *   WebFetch(domain:host)     host exacto o subdominios
+ * Devuelve { kind, ..., broad } o lanza con un mensaje que explica el rechazo.
+ */
+export function parseRule(text) {
+  if (typeof text !== 'string' || !text.length || text.length > MAX_RULE) throw fail(t('Permission rule: empty or too long pattern.'));
+  if (/[\x00-\x1f\x7f]/.test(text)) throw invalidPattern(t('Permission rule: invalid pattern {text} (control characters).', { text: JSON.stringify(text) }));
+  if (TOOL.test(text)) return { kind: 'tool', name: text, broad: text === 'Bash' ? t('Bash without parentheses authorizes any command.') : null };
+  const group = parseGroup(text); if (group) return { kind: 'group', ...group, broad: null };
+  const server = MCP_SERVER.exec(text); if (server) return { kind: 'mcp-server', server: server[1], broad: null };
+  const match = PARAMETRIC.exec(text);
+  if (!match) {
+    if (text.includes('*')) throw fail(t('Permission rule: pattern too broad or not supported {text}. Use mcp__server__*, plugin:ID:all or Bash(prefix:*).', { text }));
+    if (/^[A-Za-z][A-Za-z0-9_-]*\(/.test(text)) throw invalidPattern(t('Permission rule: invalid pattern {text}. Only Bash, Edit, Write and WebFetch accept parentheses.', { text }));
+    throw invalidPattern(t('Permission rule: invalid pattern {text}', { text }));
+  }
+  const [, tool, raw] = match, content = raw.trim();
+  if (!content) throw invalidPattern(t('Permission rule: invalid pattern {text} (empty parentheses).', { text }));
+  if (tool === 'Bash') {
+    if (content === '*' || content === ':*') { if (content === ':*') throw fail(t('Permission rule: Bash(:*) has no prefix; use Bash(*) if you really want any command.')); return { kind: 'bash-any', broad: t('Bash(*) authorizes any command, including deletions and network access.') }; }
+    if (content.endsWith(':*')) {
+      const prefix = content.slice(0, -2).trim();
+      if (!prefix) throw fail(t('Permission rule: Bash(:*) has no prefix.'));
+      if (/[;&|<>$`\\(){}*?[\]'"#~=]/.test(prefix)) throw fail(t('Permission rule: the prefix of {text} only accepts plain words, without operators, quotes or wildcards.', { text }));
+      const words = prefix.split(/\s+/);
+      return { kind: 'bash-prefix', words, broad: WRAPPERS.has(path.basename(words[0])) ? t('{word} runs other programs: the prefix is equivalent to full Bash.', { word: words[0] }) : null };
+    }
+    if (/(?:^|\s)\*$/.test(content)) throw fail(t('Permission rule: {text} is not a prefix. Use Bash(prefix:*) for a prefix or the exact command.', { text }));
+    return { kind: 'bash-exact', command: content, broad: null };
+  }
+  if (tool === 'WebFetch') {
+    const domain = DOMAIN.exec(content.toLowerCase());
+    if (!domain) throw fail(t('Permission rule: {text} must be WebFetch(domain:example.com).', { text }));
+    return { kind: 'domain', tool, domain: domain[1], broad: null };
+  }
+  // Edit/Write: glob relativo al proyecto, sin salir de él.
+  const glob = content.replace(/^\.\//, '');
+  if (path.isAbsolute(glob) || glob.startsWith('~') || glob.includes('\\') || glob.split('/').some(part => part === '..' || part === '')) throw fail(t('Permission rule: {text} must be a path or glob relative to the project, without .. or absolute paths.', { text }));
+  return { kind: 'path', tool, glob, broad: /^(?:\*\*|\*\*\/\*|\*)$/.test(glob) ? t('{target} covers the whole project.', { target: `${tool}(${glob})` }) : null };
+}
+export function validateRuleText(text) { parseRule(text); return text; }
+
+const globRegex = glob => new RegExp('^' + glob.split(/(\*\*\/|\*\*|\*|\?)/).map(part => part === '**/' ? '(?:.*/)?' : part === '**' ? '.*' : part === '*' ? '[^/]*' : part === '?' ? '[^/]' : part.replace(/[.+^${}()|[\]\\]/g, '\\$&')).join('') + '$');
+const startsWithWords = (tokens, words) => tokens.length >= words.length && words.every((word, index) => tokens[index] === word);
+
+/**
+ * ¿Cubre la regla Bash este comando? allow es estricto, deny/ask conservadores:
+ * - allow con prefijo: exactamente un comando simple (sin ; && || | & ni saltos de línea),
+ *   sin sustituciones, expansiones ni redirecciones (shellCommands devuelve null), sin
+ *   veto duro del guardia, y cuyas primeras palabras son exactamente las del prefijo.
+ * - allow exacto: el texto completo, igual tras recortar espacios.
+ * - deny/ask: basta con que el prefijo o el comando aparezca en cualquier subcomando;
+ *   si el comando no se puede analizar, se busca la secuencia de palabras en todo el texto.
+ */
+export function bashCovers(parsed, command, { list = 'allow', cwd = process.cwd() } = {}) {
+  if (typeof command !== 'string') return false;
+  if (parsed.kind === 'bash-any') return true;
+  const commands = shellCommands(command);
+  if (list === 'allow') {
+    if (parsed.kind === 'bash-exact') return command.trim() === parsed.command;
+    if (!commands || commands.length !== 1 || /[\r\n]/.test(command)) return false;
+    if (inspectAutoAction('Bash', { command }, cwd).hard) return false;
+    return startsWithWords(commands[0], parsed.words);
+  }
+  const words = parsed.kind === 'bash-exact' ? parsed.command.split(/\s+/) : parsed.words;
+  if (parsed.kind === 'bash-exact' && command.trim() === parsed.command) return true;
+  const exact = tokens => parsed.kind === 'bash-exact' ? tokens.join(' ') === words.join(' ') : startsWithWords(tokens, words);
+  if (commands?.some(tokens => exact(tokens) || exact([path.basename(tokens[0] || ''), ...tokens.slice(1)]))) return true;
+  const loose = command.split(/[\s;&|()<>`$"'{}\\]+/).filter(Boolean).map(word => word.includes('/') ? path.basename(word) : word);
+  return loose.some((_, index) => startsWithWords(loose.slice(index), words));
+}
+
+/** ¿Cubre la regla analizada esta invocación? */
+export function ruleCovers(parsed, name, input, { list = 'allow', project = process.cwd(), groups = () => [] } = {}) {
+  switch (parsed.kind) {
+    case 'tool': return parsed.name === name;
+    case 'group': return name.startsWith(`plugin__${parsed.plugin}__`) && (parsed.group === 'all' || (groups(parsed.plugin, parsed.group) || []).includes(name));
+    case 'mcp-server': return name.startsWith(`mcp__${parsed.server}__`);
+    case 'bash-any': return name === 'Bash';
+    case 'bash-prefix': case 'bash-exact': return name === 'Bash' && bashCovers(parsed, input?.command, { list, cwd: project });
+    case 'path': {
+      if (name !== parsed.tool || typeof input?.file_path !== 'string') return false;
+      const root = path.resolve(project), file = path.resolve(root, input.file_path), relative = path.relative(root, file);
+      if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return false;
+      return globRegex(parsed.glob).test(relative.split(path.sep).join('/'));
+    }
+    case 'domain': {
+      if (name !== 'WebFetch' || typeof input?.url !== 'string') return false;
+      let host; try { host = new URL(input.url).hostname.toLowerCase().replace(/\.$/, ''); } catch { return list !== 'allow'; }
+      return host === parsed.domain || host.endsWith(`.${parsed.domain}`);
+    }
+    default: return false;
+  }
+}
+
+/**
+ * Regla más específica razonable para «sí, siempre». null si no hay una segura.
+ * Bash: prefijo del primer comando simple (ejecutable y, si la hay, una suborden);
+ * comandos compuestos, opacos o destructivos → el comando exacto.
+ */
+export function suggestRule(name, input, options = {}) {
+  const rule = suggestion(name, input, options);
+  if (!rule) return null;
+  try { return parseRule(rule).broad ? null : rule; } catch { return null; }
+}
+function suggestion(name, input, { project = process.cwd() } = {}) {
+  if (name === 'Bash') {
+    const command = typeof input?.command === 'string' ? input.command.trim() : '';
+    if (!command || /[\x00-\x1f\x7f]/.test(command) || command.length > MAX_RULE - 6) return null;
+    const commands = shellCommands(command), inspection = inspectAutoAction('Bash', { command }, project);
+    if (inspection.hard) return null;
+    if (commands?.length === 1 && !inspection.opaque && !inspection.destructive) {
+      const [first, second] = commands[0], words = [first];
+      if (!/^[A-Za-z0-9_][A-Za-z0-9_.+-]*$/.test(first) || WRAPPERS.has(first)) return `Bash(${command})`;
+      if (second && /^[a-z][a-z0-9-]*$/.test(second)) words.push(second);
+      return `Bash(${words.join(' ')}:*)`;
+    }
+    return `Bash(${command})`;
+  }
+  if ((name === 'Edit' || name === 'Write') && typeof input?.file_path === 'string') {
+    const root = path.resolve(project), relative = path.relative(root, path.resolve(root, input.file_path));
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || /[*?[\]\x00-\x1f]/.test(relative)) return null;
+    return `${name}(${relative.split(path.sep).join('/')})`;
+  }
+  return TOOL.test(name) ? name : null;
+}
+
+/** Lectura acotada de un JSON privado (600, dueño actual, directorio 700). Ausente → undefined. */
+export async function readPrivateJson(file, { workspace } = {}) {
+  if (workspace && inside(path.resolve(workspace), path.resolve(file))) throw fail(t('{file} is inside the workspace; it is ignored because the model tools could write it. Move XDG_CONFIG_HOME outside the project.', { file }), 'PRIVATE_JSON_IN_WORKSPACE');
+  let info;
+  try { info = await lstat(file); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+  await assertPrivateDirectory(path.dirname(file)); await assertPrivateFile(file, info);
+  if (info.size > MAX_BYTES) throw fail(t('{file} exceeds 256 KiB.', { file }));
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+/** Escritura atómica: temporal 600 en el mismo directorio privado, fsync y rename. */
+export async function writePrivateJson(file, value, { workspace } = {}) {
+  if (workspace && inside(path.resolve(workspace), path.resolve(file))) throw fail(t('{file} is inside the workspace; it is not written.', { file }), 'PRIVATE_JSON_IN_WORKSPACE');
+  const directory = path.dirname(file);
+  await ensurePrivateDirectory(directory); await assertPrivateDirectory(directory);
+  const temporary = path.join(directory, `.${path.basename(file)}-${randomUUID()}.tmp`);
+  const handle = await open(temporary, 'wx', 0o600);
+  try { await handle.writeFile(JSON.stringify(value, null, 2) + '\n'); await handle.sync(); } finally { await handle.close(); }
+  try { await rename(temporary, file); } catch (error) { await rm(temporary, { force: true }); throw error; }
+}
+
+export function validateRule(value, { session = false } = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw fail(t('Invalid permission rule.'));
+  for (const key of Object.keys(value)) if (!['list', 'rule', 'scope', 'added_at', 'source'].includes(key)) throw fail(t('Permission rule: unknown field {key}', { key }));
+  if (!RULE_LISTS.includes(value.list)) throw fail(t('Permission rule: list must be allow, ask or deny.'));
+  try { parseRule(value.rule); } catch (error) { throw fail(error.invalidPattern ? error.message : t('Permission rule: invalid pattern {rule}. {reason}', { rule: value.rule, reason: error.message })); }
+  if (!(session && value.scope === 'session') && value.scope !== 'user' && !(typeof value.scope === 'string' && value.scope.startsWith('project:') && path.isAbsolute(value.scope.slice(8)))) throw fail(t('Permission rule: scope must be user or project:<absolute path>.'));
+  if (typeof value.added_at !== 'string' || value.source !== 'human') throw fail(t('Permission rule: added_at and source:"human" are required.'));
+  return { list: value.list, rule: value.rule, scope: value.scope, added_at: value.added_at, source: 'human' };
+}
+
+const key = rule => `${rule.list}\u0000${rule.rule}\u0000${rule.scope}`;
+
+/**
+ * Almacén y juez de reglas. `groups(plugin, group)` devuelve los nombres de un grupo
+ * declarado (p. ej. plugin:chrome-lab:observe); `plugin:ID:all` cubre plugin__ID__*.
+ * `gate(name)` puede vetar una regla allow (p. ej. si el código del plugin no es el confiado);
+ * deny y ask nunca se vetan.
+ */
+export class PermissionRules {
+  #rules = [];
+  #session = [];
+  #parsed = new Map();
+  constructor({ file = permissionRulesFile(), workspace, project = workspace, groups = () => [], gate = () => true } = {}) {
+    Object.assign(this, { file: path.resolve(file), workspace, groups, gate });
+    this.project = project ? path.resolve(project) : null;
+    this.scope = project ? projectScope(project) : null; this.revision = 0; this.warning = null; this.unsafe = false;
+  }
+  async load() {
+    this.warning = null; this.unsafe = false;
+    try {
+      const data = await readPrivateJson(this.file, { workspace: this.workspace });
+      if (data !== undefined && (!data || data.version !== VERSION || !Array.isArray(data.rules) || data.rules.length > MAX_RULES)) throw fail(t('Unrecognized permission rules format.'));
+      this.#rules = (data?.rules || []).map(rule => validateRule(rule));
+    } catch (error) { this.#rules = []; this.unsafe = true; this.warning = t('Permission rules ignored: {reason}', { reason: error.message }); }
+    this.revision++; return this.list();
+  }
+  /** Reglas guardadas en el archivo (todas, de cualquier proyecto). */
+  list() { return this.#rules.map(rule => ({ ...rule })); }
+  /** Reglas de sesión: en memoria, nunca escritas. */
+  sessionRules() { return this.#session.map(rule => ({ ...rule })); }
+  applicable() { return [...this.#session, ...this.#rules.filter(rule => rule.scope === 'user' || rule.scope === this.scope)]; }
+  #parse(text) { if (!this.#parsed.has(text)) this.#parsed.set(text, parseRule(text)); return this.#parsed.get(text); }
+  matches(rule, name, input, list = rule.list || 'allow') {
+    let parsed; try { parsed = this.#parse(rule.rule); } catch { return false; }
+    return ruleCovers(parsed, name, input, { list, project: this.project || process.cwd(), groups: this.groups });
+  }
+  /** Precedencia: deny > ask > allow. Devuelve la regla decisiva o undefined. */
+  decide(name, input) {
+    const found = this.applicable().filter(rule => this.matches(rule, name, input));
+    const deny = found.find(rule => rule.list === 'deny'); if (deny) return deny;
+    const ask = found.find(rule => rule.list === 'ask'); if (ask) return ask;
+    return found.find(rule => rule.list === 'allow' && this.gate(name));
+  }
+  /** Reemplaza las reglas que cumplen `remove` por `add`, en una sola escritura atómica. */
+  async update({ remove = () => false, add = [] } = {}) {
+    if (this.unsafe) throw fail(t('{warning} Fix or delete {file} manually.', { warning: this.warning, file: this.file }), 'PERMISSION_RULES_UNSAFE');
+    const stamp = new Date().toISOString();
+    const next = [...this.#rules.filter(rule => !remove(rule)), ...add.map(rule => validateRule({ added_at: stamp, source: 'human', ...rule }))];
+    const unique = [...new Map(next.map(rule => [key(rule), rule])).values()];
+    if (unique.length > MAX_RULES) throw fail(t('At most {max} rules.', { max: MAX_RULES }));
+    await writePrivateJson(this.file, { version: VERSION, rules: unique }, { workspace: this.workspace });
+    this.#rules = unique; this.revision++; return this.list();
+  }
+  /** Agrega una regla en `scope` (session|user|project:<ruta>); las de sesión no tocan el archivo. */
+  async add({ list, rule, scope }) {
+    if (scope === 'session') {
+      const value = validateRule({ list, rule, scope, added_at: new Date().toISOString(), source: 'human' }, { session: true });
+      if (!this.#session.some(item => key(item) === key(value))) { if (this.#session.length >= MAX_RULES) throw fail(t('At most {max} session rules.', { max: MAX_RULES })); this.#session.push(value); }
+      this.revision++; return value;
+    }
+    await this.update({ add: [{ list, rule, scope }] });
+    return this.#rules.find(item => key(item) === key({ list, rule, scope }));
+  }
+  /** Quita la regla `rule` en `scope` (de cualquier lista, o de `list` si se indica). Devuelve las retiradas. */
+  async remove({ rule, scope, list }) {
+    const hit = item => item.rule === rule && item.scope === scope && (!list || item.list === list);
+    if (scope === 'session') { const removed = this.#session.filter(hit); this.#session = this.#session.filter(item => !hit(item)); if (removed.length) this.revision++; return removed; }
+    const removed = this.#rules.filter(hit); if (removed.length) await this.update({ remove: hit });
+    return removed.map(item => ({ ...item }));
+  }
+}
+
+// describeRule/scopeLabel van en razones de decisión que también ve el modelo: inglés fijo.
+// scopeText/ruleText son para el humano y siguen el idioma de la interfaz.
+export const scopeLabel = scope => String(scope);
+export const describeRule = rule => `${rule.list} rule «${rule.rule}» (${scopeLabel(rule.scope)})`;
+const SCOPE_NAMES = { user: () => t('scope:user'), session: () => t('scope:session') };
+export const scopeText = scope => SCOPE_NAMES[scope] ? SCOPE_NAMES[scope]().replace(/^scope:/, '') : String(scope);
+export const ruleText = rule => t('{list} rule «{rule}» ({scope})', { list: rule.list, rule: rule.rule, scope: scopeText(rule.scope) });