@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/single-use-store.js

@@ -0,0 +1,359 @@
+'use strict';
+
+/** Fachada single-use compuesta sobre transacciones privadas del ledger. */
+
+const crypto = require('node:crypto');
+
+const { assertApprovalCurrent, isVerifiedApproval } = require('./approval-receipts');
+const { assertPrincipalCurrent, isVerifiedPrincipal } = require('./principal-verifier');
+const {
+  exactKeys, fail, freezeDeep, getContractValidators, plainObject,
+} = require('./policy-verifier-utils');
+const { canonicalizarIJson, validarTimestampIso } = require('./signed-envelope');
+
+const GRANT_OWNERS = new WeakMap();
+const CLAIM_RECEIPT_OWNERS = new WeakMap();
+const SHA256 = /^[a-f0-9]{64}$/u;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const TASK = /^T-[0-9]{2}$/u;
+
+function hitFault(point) {
+  if (process.env.SWL_SINGLE_USE_FAULT !== point) return;
+  if (process.env.NODE_ENV !== 'test') fail('FAULT_CONFIG_INVALID', 'NODE_ENV inválido');
+  if (process.env.SWL_INTEGRITY_TEST_MODE !== '1') {
+    fail('FAULT_CONFIG_INVALID', 'modo de integridad inválido');
+  }
+  fail('FAULT_INJECTED', `falla inyectada: ${point}`);
+}
+
+function validatePrincipalOperation(principal, operation) {
+  if (!isVerifiedPrincipal(principal)) fail('SINGLE_USE_PRINCIPAL_INVALID', 'principal inválido');
+  if (!getContractValidators().isVerifiedOperation(operation)) {
+    fail('SINGLE_USE_OPERATION_INVALID', 'operación inválida');
+  }
+  if (principal.operationDigest !== operation.operationDigest) {
+    fail('SINGLE_USE_BINDING_INVALID', 'principal ligado a otra operación');
+  }
+}
+
+function validateApprovalBinding(approval, principal, operation, authority) {
+  if (!isVerifiedApproval(approval)) fail('APPROVAL_INVALID', 'approval no verificada');
+  assertPrincipalCurrent(principal, authority);
+  assertApprovalCurrent(approval, authority);
+  const expected = {
+    principalDigest: principal.principalDigest, operationDigest: operation.operationDigest,
+    sessionId: principal.sessionId, runtimeId: principal.runtimeId,
+    projectId: principal.projectId, worktreeDigest: principal.worktreeDigest,
+    capability: operation.capability, effectKind: operation.effectKind,
+    scopeDigest: operation.scope.digest, fsmVersion: operation.fsmVersion,
+    trustEpoch: authority.trustEpoch, trustDigest: authority.trustDigest,
+  };
+  if (Object.entries(expected).some(([key, value]) => approval[key] !== value)) {
+    fail('APPROVAL_BINDING_INVALID', 'approval prestada o stale');
+  }
+  validarTimestampIso(approval.expiresAt, 'approval expiresAt');
+}
+
+function grantIdFor(approval) {
+  return `grant:${approval.approvalDigest}`;
+}
+
+function grantClaims(approval, authority) {
+  const base = {
+    kind: 'authorization-grant', schemaVersion: '1.0.0', grantId: grantIdFor(approval),
+    approvalDigest: approval.approvalDigest,
+    principalDigest: approval.principalDigest, operationDigest: approval.operationDigest,
+    capability: approval.capability, effectKind: approval.effectKind,
+    scopeDigest: approval.scopeDigest, planDigest: approval.planDigest,
+    fsmVersion: approval.fsmVersion, issuedAt: authority.observedAt,
+    expiresAt: approval.expiresAt, trustEpoch: authority.trustEpoch,
+    trustDigest: authority.trustDigest, rootKeyDigest: authority.rootKeyDigest,
+    status: 'issued',
+  };
+  let claims = base;
+  if (approval.schemaVersion !== '1.0.0') {
+    claims = {
+      ...base, schemaVersion: approval.schemaVersion,
+      phaseId: approval.phaseId, taskId: approval.taskId,
+    };
+  }
+  if (approval.schemaVersion === '1.2.0') {
+    claims.g1ApprovalDigest = approval.g1ApprovalDigest;
+  }
+  return { ...claims, grantDigest: crypto.createHash('sha256')
+    .update(canonicalizarIJson(claims), 'utf8').digest('hex') };
+}
+
+function policyGrantBase(state, authority, options) {
+  const seed = canonicalizarIJson({
+    gateAuthorizationDigest: options.gate.gateAuthorizationDigest,
+    operationDigest: options.operation.operationDigest,
+    sequence: state.sequence + 1,
+  });
+  const base = {
+    kind: 'authorization-grant', schemaVersion: options.gate.g1ApprovalDigest
+      ? '1.2.0' : '1.1.0',
+    grantId: `grant:${crypto.createHash('sha256').update(seed).digest('hex')}`,
+    approvalDigest: options.gate.g1ApprovalDigest
+      || options.gate.gateAuthorizationDigest,
+    principalDigest: options.principal.principalDigest,
+    operationDigest: options.operation.operationDigest,
+    capability: options.operation.capability, effectKind: options.operation.effectKind,
+    scopeDigest: options.operation.scope.digest, planDigest: options.gate.planDigest,
+    fsmVersion: options.operation.fsmVersion, phaseId: options.operation.phaseId,
+    taskId: options.operation.taskId,
+    issuedAt: authority.observedAt, expiresAt: options.expiresAt,
+    trustEpoch: authority.trustEpoch, trustDigest: authority.trustDigest,
+    rootKeyDigest: authority.rootKeyDigest, status: 'issued',
+  };
+  return base;
+}
+
+function policyGrantClaims(state, authority, options) {
+  validatePrincipalOperation(options.principal, options.operation);
+  assertPrincipalCurrent(options.principal, authority);
+  validarTimestampIso(options.expiresAt, 'policy grant expiresAt');
+  if (options.expiresAt < authority.observedAt) {
+    fail('GRANT_EXPIRED', 'policy grant expirada');
+  }
+  const base = policyGrantBase(state, authority, options);
+  if (options.gate.g1ApprovalDigest) {
+    base.g1ApprovalDigest = options.gate.g1ApprovalDigest;
+  }
+  return { ...base, grantDigest: crypto.createHash('sha256')
+    .update(canonicalizarIJson(base), 'utf8').digest('hex') };
+}
+
+function createGrant(claims, owner) {
+  const grant = freezeDeep(structuredClone(claims));
+  GRANT_OWNERS.set(grant, owner);
+  return grant;
+}
+
+function committedEvents(state) {
+  return state.events.filter(({ eventType }) => eventType === 'authorization.committed');
+}
+
+function claimedEvents(state) {
+  return state.events.filter(({ eventType }) => eventType === 'grant.claimed');
+}
+
+function assertApprovalUnused(state, approval) {
+  const used = committedEvents(state).some(({ payload }) => (
+    payload.approvalClaim?.approvalDigest === approval.approvalDigest
+    || payload.approvalClaim?.approvalId === approval.approvalId
+    || payload.approvalClaim?.nonce === approval.nonce
+  ));
+  if (used) fail('APPROVAL_ALREADY_USED', 'approval ya reclamada');
+}
+
+function validateRedeemOptions(options) {
+  plainObject(options, 'SINGLE_USE_OPTIONS_INVALID', 'opciones redeem');
+  exactKeys(options, ['approval', 'principal', 'operation'],
+    'SINGLE_USE_OPTIONS_INVALID', 'opciones redeem');
+  validatePrincipalOperation(options.principal, options.operation);
+}
+
+function authorizationPayload(approval, grant) {
+  return {
+    schemaVersion: grant.schemaVersion,
+    approvalClaim: {
+      approvalId: approval.approvalId, approvalDigest: approval.approvalDigest,
+      nonce: approval.nonce, signerPublicKeyDigest: approval.signerPublicKeyDigest,
+    },
+    decision: { outcome: 'allow', reasonCode: 'APPROVAL_ACCEPTED' },
+    grant: structuredClone(grant),
+  };
+}
+
+function issueApprovalGrant(state, authority, owner, options) {
+  validateRedeemOptions(options);
+  validateApprovalBinding(options.approval, options.principal, options.operation, authority);
+  assertApprovalUnused(state, options.approval);
+  const grant = createGrant(grantClaims(options.approval, authority), owner);
+  return Object.freeze({
+    approvalClaim: Object.freeze({
+      approvalId: options.approval.approvalId,
+      approvalDigest: options.approval.approvalDigest,
+      nonce: options.approval.nonce,
+      signerPublicKeyDigest: options.approval.signerPublicKeyDigest,
+    }),
+    grant,
+  });
+}
+
+function issuePolicyGrant(state, authority, owner, options) {
+  plainObject(options, 'SINGLE_USE_OPTIONS_INVALID', 'opciones policy grant');
+  exactKeys(options, ['expiresAt', 'gate', 'principal', 'operation'],
+    'SINGLE_USE_OPTIONS_INVALID', 'opciones policy grant');
+  return createGrant(policyGrantClaims(state, authority, options), owner);
+}
+
+function redeemApproval(writer, owner, options) {
+  validateRedeemOptions(options);
+  let grant;
+  writer.transact((state, authority) => {
+    validateApprovalBinding(options.approval, options.principal, options.operation, authority);
+    assertApprovalUnused(state, options.approval);
+    hitFault('after-approval-claim-before-decision');
+    grant = createGrant(grantClaims(options.approval, authority), owner);
+    hitFault('after-decision-before-grant');
+    return {
+      expectedSequence: state.sequence, expectedHeadHash: state.headHash,
+      eventType: 'authorization.committed',
+      payload: authorizationPayload(options.approval, grant),
+    };
+  });
+  return grant;
+}
+
+function validateStoredGrant(grant) {
+  plainObject(grant, 'GRANT_INVALID', 'grant persistida');
+  const baseKeys = [
+    'kind', 'schemaVersion', 'grantId', 'approvalDigest', 'principalDigest',
+    'operationDigest', 'capability', 'effectKind', 'scopeDigest', 'planDigest',
+    'fsmVersion', 'issuedAt', 'expiresAt', 'trustEpoch', 'trustDigest', 'status',
+    'rootKeyDigest', 'grantDigest',
+  ];
+  const scoped = ['1.1.0', '1.2.0'].includes(grant.schemaVersion);
+  const keys = scoped ? [...baseKeys, 'phaseId', 'taskId'] : baseKeys;
+  if (grant.schemaVersion === '1.2.0') keys.push('g1ApprovalDigest');
+  exactKeys(grant, keys, 'GRANT_INVALID', 'grant persistida');
+  const unsigned = { ...grant };
+  delete unsigned.grantDigest;
+  const digest = crypto.createHash('sha256')
+    .update(canonicalizarIJson(unsigned), 'utf8').digest('hex');
+  if (grant.kind !== 'authorization-grant'
+      || !['1.0.0', '1.1.0', '1.2.0'].includes(grant.schemaVersion)
+      || grant.status !== 'issued' || !IDENTIFIER.test(grant.grantId)
+      || !SHA256.test(grant.grantDigest) || grant.grantDigest !== digest) {
+    fail('GRANT_INVALID', 'grant persistida inválida');
+  }
+  if (scoped && (!IDENTIFIER.test(grant.phaseId) || !TASK.test(grant.taskId))) {
+    fail('GRANT_INVALID', 'alcance de gate persistido inválido');
+  }
+  if (grant.schemaVersion === '1.2.0' && !SHA256.test(grant.g1ApprovalDigest)) {
+    fail('GRANT_INVALID', 'época G1 persistida inválida');
+  }
+}
+
+function validateGrantBinding(grant, principal, operation, authority) {
+  assertPrincipalCurrent(principal, authority);
+  const expected = {
+    principalDigest: principal.principalDigest, operationDigest: operation.operationDigest,
+    capability: operation.capability, effectKind: operation.effectKind,
+    scopeDigest: operation.scope.digest, trustEpoch: authority.trustEpoch,
+    trustDigest: authority.trustDigest, rootKeyDigest: authority.rootKeyDigest,
+  };
+  if (Object.entries(expected).some(([key, value]) => grant[key] !== value)) {
+    fail('GRANT_BINDING_INVALID', 'grant prestada o stale');
+  }
+  validarTimestampIso(grant.expiresAt, 'grant expiresAt');
+  if (grant.expiresAt < authority.observedAt || principal.expiresAt < authority.observedAt) {
+    fail('GRANT_EXPIRED', 'grant o principal expirado');
+  }
+}
+
+function findGrant(state, grantId) {
+  const matches = committedEvents(state).filter(({ payload }) => (
+    payload.grant?.grantId === grantId
+  ));
+  if (matches.length !== 1) fail('GRANT_NOT_FOUND', 'grant ausente o duplicada');
+  const grant = matches[0].payload.grant;
+  validateStoredGrant(grant);
+  return grant;
+}
+
+function validateLoadOptions(options) {
+  plainObject(options, 'SINGLE_USE_OPTIONS_INVALID', 'opciones load');
+  exactKeys(options, ['grantId', 'principal', 'operation'],
+    'SINGLE_USE_OPTIONS_INVALID', 'opciones load');
+  if (!IDENTIFIER.test(options.grantId)) fail('GRANT_INVALID', 'grantId inválido');
+  validatePrincipalOperation(options.principal, options.operation);
+}
+
+function loadGrant(writer, owner, options) {
+  validateLoadOptions(options);
+  return writer.inspect((state, authority) => {
+    const stored = findGrant(state, options.grantId);
+    validateGrantBinding(stored, options.principal, options.operation, authority);
+    return createGrant(stored, owner);
+  });
+}
+
+function validateClaimOptions(options, owner) {
+  plainObject(options, 'SINGLE_USE_OPTIONS_INVALID', 'opciones claim');
+  exactKeys(options, ['grant', 'principal', 'operation'],
+    'SINGLE_USE_OPTIONS_INVALID', 'opciones claim');
+  if (GRANT_OWNERS.get(options.grant) !== owner) {
+    fail('GRANT_INVALID', 'grant no verificada por esta store');
+  }
+  validatePrincipalOperation(options.principal, options.operation);
+}
+
+function claimGrant(writer, owner, options) {
+  validateClaimOptions(options, owner);
+  let receipt;
+  const appendReceipt = writer.transact((state, authority) => {
+    const stored = findGrant(state, options.grant.grantId);
+    validateGrantBinding(stored, options.principal, options.operation, authority);
+    if (stored.grantDigest !== options.grant.grantDigest) {
+      fail('GRANT_BINDING_INVALID', 'grant no coincide con autoridad durable');
+    }
+    if (claimedEvents(state).some(({ payload }) => payload.grantDigest === stored.grantDigest)) {
+      fail('GRANT_ALREADY_CLAIMED', 'grant ya reclamada');
+    }
+    const payload = {
+      schemaVersion: stored.schemaVersion, grantId: stored.grantId,
+      grantDigest: stored.grantDigest, principalDigest: stored.principalDigest,
+      operationDigest: stored.operationDigest, claimedAt: authority.observedAt,
+    };
+    if (stored.schemaVersion !== '1.0.0') {
+      payload.planDigest = stored.planDigest;
+      payload.phaseId = stored.phaseId;
+      payload.taskId = stored.taskId;
+    }
+    if (stored.schemaVersion === '1.2.0') {
+      payload.g1ApprovalDigest = stored.g1ApprovalDigest;
+    }
+    return {
+      expectedSequence: state.sequence, expectedHeadHash: state.headHash,
+      eventType: 'grant.claimed', payload,
+    };
+  });
+  receipt = freezeDeep({
+    kind: 'grant-claim-receipt', grantId: options.grant.grantId,
+    grantDigest: options.grant.grantDigest,
+    planDigest: options.grant.planDigest,
+    g1ApprovalDigest: options.grant.g1ApprovalDigest || null,
+    phaseId: options.grant.phaseId || null, taskId: options.grant.taskId || null,
+    sequence: appendReceipt.sequence, headHash: appendReceipt.headHash,
+  });
+  CLAIM_RECEIPT_OWNERS.set(receipt, owner);
+  return receipt;
+}
+
+function createSingleUseStore(writer) {
+  const owner = Object.freeze({});
+  const publicStore = Object.freeze({
+    claimGrant: (options) => claimGrant(writer, owner, options),
+    isAuthorizationGrant: (value) => GRANT_OWNERS.get(value) === owner,
+    isGrantClaimReceipt: (value) => CLAIM_RECEIPT_OWNERS.get(value) === owner,
+    loadGrant: (options) => loadGrant(writer, owner, options),
+  });
+  const authorizationStore = Object.freeze({
+    redeemApproval: (options) => redeemApproval(writer, owner, options),
+  });
+  const authorizationGrantIssuer = Object.freeze({
+    isVerifiedApproval,
+    issueApprovalGrant: (state, authority, options) => (
+      issueApprovalGrant(state, authority, owner, options)
+    ),
+    issuePolicyGrant: (state, authority, options) => (
+      issuePolicyGrant(state, authority, owner, options)
+    ),
+  });
+  return Object.freeze({ authorizationGrantIssuer, authorizationStore, publicStore });
+}
+
+module.exports = { createSingleUseStore };

package/scripts/lib/skills-externas.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/** Catálogo cerrado de referencias opt-in que no viven en habilidades/. */
+const SKILLS_EXTERNAS = Object.freeze([
+  'pdf',
+  'docx',
+  'xlsx',
+  'pptx',
+  'frontend-design',
+  'web-artifacts-builder',
+  'canvas-design',
+  'algorithmic-art',
+  'theme-factory',
+  'slack-gif-creator',
+  'claude-api',
+  'mcp-builder',
+  'webapp-testing',
+  'doc-coauthoring',
+  'internal-comms',
+  'brand-guidelines',
+  'skill-creator',
+]);
+
+const SKILLS_EXTERNAS_SET = new Set(SKILLS_EXTERNAS);
+const CENTINELA_TODOS = 'todos';
+
+module.exports = {
+  CENTINELA_TODOS,
+  SKILLS_EXTERNAS,
+  SKILLS_EXTERNAS_SET,
+};

package/scripts/lib/transformadores/codex.js

@@ -24,6 +24,8 @@ const path = require('path');
 const TransformadorBase = require('./base');
 const { upsertMcpServer } = require('../toml-merge');
 
+const CONTROLES_TOML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/u;
+
 class TransformadorCodex extends TransformadorBase {
   /**
    * Sub-fase 11 v1.5.0: Codex CLI SÍ acepta agentes individuales en formato
@@ -34,7 +36,6 @@ class TransformadorCodex extends TransformadorBase {
    *   - name (required)
    *   - description (required)
    *   - developer_instructions (required) — multi-line literal del cuerpo Markdown
-   *   - model (opcional) — heredado del frontmatter SWL si existe
    *   - sandbox_mode (opcional) — mapeado desde permisosEscritura=false → "read-only"
    *
    * El cuerpo del .md SWL completo (después del frontmatter) se inserta como
@@ -64,7 +65,6 @@ class TransformadorCodex extends TransformadorBase {
       name,
       description,
       developer_instructions: developerInstructions,
-      model: frontmatter.model || null,
       sandbox_mode: (frontmatter.permisosEscritura === false) ? 'read-only' : null,
     });
 
@@ -88,7 +88,6 @@ class TransformadorCodex extends TransformadorBase {
     lineas.push('');
     lineas.push(`name = ${this._tomlBasicString(campos.name)}`);
     lineas.push(`description = ${this._tomlBasicString(campos.description)}`);
-    if (campos.model) lineas.push(`model = ${this._tomlBasicString(campos.model)}`);
     if (campos.sandbox_mode) lineas.push(`sandbox_mode = ${this._tomlBasicString(campos.sandbox_mode)}`);
     lineas.push('');
     lineas.push(`developer_instructions = ${this._tomlMultiline(campos.developer_instructions)}`);
@@ -96,7 +95,9 @@ class TransformadorCodex extends TransformadorBase {
   }
 
   _tomlBasicString(s) {
-    const escapado = String(s)
+    const texto = String(s);
+    if (CONTROLES_TOML.test(texto)) throw new TypeError('Control TOML inválido');
+    const escapado = texto
       .replace(/\\/g, '\\\\')
       .replace(/"/g, '\\"')
       .replace(/\n/g, '\\n')
@@ -107,6 +108,7 @@ class TransformadorCodex extends TransformadorBase {
 
   _tomlMultiline(s) {
     const contenido = String(s);
+    if (CONTROLES_TOML.test(contenido)) throw new TypeError('Control TOML inválido');
     if (!contenido.includes("'''")) {
       // Literal multi-line: preserva contenido sin escapes.
       return `'''\n${contenido}\n'''`;
@@ -122,11 +124,13 @@ class TransformadorCodex extends TransformadorBase {
     // `.agents/skills/` como ubicaciones válidas — NO `~/.codex/skills/`.
     // El path `~/.codex/skills/` que apareció en Sub-fase 8 era de una sample
     // sub-doc del repo (no canónica). Ahora apunta al path correcto vía dirBase.
-    const dirBaseGlobal = path.join(require('os').homedir(), '.agents');
+    const dirBase = metadatos.esGlobal
+      ? path.join(require('os').homedir(), '.agents')
+      : '.agents';
     return {
       tipo: 'directorio',
       rutaRelativa: `skills/${metadatos.nombreDirectorio}`,
-      dirBase: dirBaseGlobal,
+      dirBase,
     };
   }
 
@@ -178,9 +182,12 @@ class TransformadorCodex extends TransformadorBase {
 
     for (const [hookFile, def] of Object.entries(hooksConfig)) {
       if (hookFilesFiltro && !hookFilesFiltro.has(hookFile)) continue;
-      if (!def || !Array.isArray(def.events)) continue;
+      if (!def) continue;
+      const events = Array.isArray(def.events)
+        ? def.events
+        : (typeof def.event === 'string' ? [def.event] : []);
 
-      for (const event of def.events) {
+      for (const event of events) {
         if (!EVENTOS_VALIDOS.has(event)) {
           descartados.push({ hookFile, event, motivo: 'evento no soportado por Codex' });
           continue;

package/scripts/lib/transformadores/gemini.js

@@ -2,6 +2,13 @@
 
 const TransformadorBase = require('./base');
 
+const EVENTOS_GEMINI = Object.freeze({
+  PreToolUse: 'BeforeTool',
+  PostToolUse: 'AfterTool',
+  SessionStart: 'SessionStart',
+});
+const CONTROLES_TOML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/u;
+
 class TransformadorGemini extends TransformadorBase {
   transformarAgente(contenidoMd, metadatos) {
     // Gemini soporta frontmatter similar a Claude
@@ -12,7 +19,6 @@ class TransformadorGemini extends TransformadorBase {
     if (frontmatter.name) fmGemini.name = frontmatter.name;
     if (frontmatter.description) fmGemini.description = frontmatter.description;
     if (frontmatter.tools) fmGemini.tools = frontmatter.tools;
-    if (frontmatter.model) fmGemini.model = frontmatter.model;
 
     return {
       contenido: this.construirMarkdown(fmGemini, cuerpo),
@@ -35,12 +41,36 @@ class TransformadorGemini extends TransformadorBase {
   }
 
   transformarComando(contenidoMd, metadatos) {
+    const { frontmatter, cuerpo } = this.parsearFrontmatter(contenidoMd);
+    const nombreArchivo = metadatos.nombreArchivo.replace(/\.md$/iu, '.toml');
+    const descripcion = this._tomlString(frontmatter.description || '');
+    const prompt = this._tomlMultiline(String(cuerpo || '').trim());
     return {
-      contenido: contenidoMd,
-      rutaRelativa: `commands/swl/${metadatos.nombreArchivo}`,
+      contenido: `description = ${descripcion}\nprompt = ${prompt}\n`,
+      rutaRelativa: `commands/swl/${nombreArchivo}`,
     };
   }
 
+  _tomlString(valor) {
+    const texto = String(valor);
+    if (CONTROLES_TOML.test(texto)) throw new TypeError('Control TOML inválido');
+    const escapado = texto
+      .replace(/\\/gu, '\\\\')
+      .replace(/"/gu, '\\"')
+      .replace(/\n/gu, '\\n')
+      .replace(/\r/gu, '\\r')
+      .replace(/\t/gu, '\\t');
+    return `"${escapado}"`;
+  }
+
+  _tomlMultiline(valor) {
+    const texto = String(valor);
+    if (CONTROLES_TOML.test(texto)) throw new TypeError('Control TOML inválido');
+    const escapado = texto.replace(/\r\n/gu, '\n')
+      .replace(/\\/gu, '\\\\').replace(/"""/gu, '\\"""');
+    return `"""\n${escapado}\n"""`;
+  }
+
   generarArchivoInstrucciones(contexto) {
     const lineas = [];
     lineas.push('# GEMINI.md — Sistema SWL');
@@ -86,8 +116,52 @@ class TransformadorGemini extends TransformadorBase {
   }
 
   transformarHooks(hooksConfig, opciones) {
-    // Gemini usa settings.json con formato similar a Claude
-    return { formato: 'gemini-settings', config: hooksConfig };
+    if (!hooksConfig || typeof hooksConfig !== 'object') return null;
+    const opts = opciones || {};
+    const filtro = Array.isArray(opts.hookFiles) ? new Set(opts.hookFiles) : null;
+    const rutaHooksDir = opts.rutaHooksDir || 'hooks';
+    const grupos = {};
+    const descartados = [];
+
+    for (const [hookFile, definicion] of Object.entries(hooksConfig)) {
+      const eventos = this._eventosHook(definicion);
+      if ((filtro && !filtro.has(hookFile)) || eventos.length === 0) continue;
+      for (const evento of eventos) {
+        const eventoGemini = EVENTOS_GEMINI[evento];
+        if (!eventoGemini) {
+          descartados.push({ hookFile, event: evento, motivo: 'evento no soportado por Gemini' });
+          continue;
+        }
+        if (!grupos[eventoGemini]) grupos[eventoGemini] = [];
+        const entrada = this._crearHookGemini(hookFile, definicion, rutaHooksDir);
+        grupos[eventoGemini].push(entrada);
+      }
+    }
+
+    return {
+      formato: 'gemini-hooks-json',
+      destino: 'hooks/hooks.json',
+      config: { hooks: grupos },
+      descartados,
+    };
+  }
+
+  _eventosHook(definicion) {
+    if (Array.isArray(definicion?.events)) return definicion.events;
+    return typeof definicion?.event === 'string' ? [definicion.event] : [];
+  }
+
+  _crearHookGemini(hookFile, definicion, rutaHooksDir) {
+    const hook = {
+      name: hookFile.replace(/\.js$/iu, ''),
+      type: 'command',
+      command: `node ${rutaHooksDir}/${hookFile}`,
+      ...(definicion.timeout ? { timeout: definicion.timeout } : {}),
+    };
+    return {
+      ...(definicion.matcher ? { matcher: definicion.matcher } : {}),
+      hooks: [hook],
+    };
   }
 }