ratacode 0.2.5

package/mcp/lib/nucleo.js

@@ -0,0 +1,332 @@
+/**
+ * nucleo — el puente al core de DSH. Aquí NO hay lógica de modelos.
+ *
+ * Lo que hace: lanza UN hijo `dsh --profile sdk` por tarea, le habla el
+ * protocolo JSON-RPC por stdio que el propio DSH publica
+ * (`dsh-sdk-protocol`), y traduce lo que pasa dentro a un resultado.
+ *
+ * Por qué así, y no dentro del proceso de la web:
+ *   · el aislamiento: la tarea no comparte proceso con tu sesión de trabajo;
+ *   · cancelar es matar: inmediato y sin efectos raros en la web;
+ *   · el sandbox se fija por tarea con un parche, y no depende del entorno;
+ *   · y el core es EL MISMO: mismo binario, misma casa, mismos proveedores,
+ *     mismas claves. No se duplica nada.
+ *
+ * Medido antes de escribir esto (sonda del 24-sep): el perfil `sdk` se
+ * autocrea, resuelve sus bundles desde la instalación, contesta el handshake
+ * `initialize` y acepta `session/prompt`, avisando por notificaciones
+ * `session.event` y `session.status`.
+ */
+import { spawn } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { entornoDelMotorSinClaves } from './claves.js';
+import { copiarCerco, parcheDePolitica } from './seguridad.js';
+
+/** Cuánto se espera a que un hijo termine de irse antes de matarlo. */
+const GRACIA_MS = 2500;
+/** Cuántos bytes de stderr guardamos para poder explicar un fallo. */
+const TOPE_STDERR = 4096;
+
+/** Las variables que describen a ESTA sesión y que el hijo no debe heredar. */
+const NO_HEREDAR = ['DSH_SESSION_ID', 'DSH_SHELL', 'DSH_WEB_URL'];
+
+/**
+ * Lanzar una tarea. Devuelve el mando (para cancelar) y la promesa del resultado.
+ * @param {object} opciones - casa, motor, espacio, ruta de modelo, prompt, límites.
+ * @returns {{promesa: Promise<object>, cancelar: (motivo?: string) => void, pid: number|undefined}}
+ */
+export function lanzarTarea({
+  id,
+  casa,
+  dshBin,
+  espacio,
+  raices,
+  provider,
+  model,
+  prompt,
+  maxTokens,
+  timeoutMs,
+  modo,
+  alEvento,
+}) {
+  const carpetaTemporal = join(casa, 'mcp', 'tmp');
+  mkdirSync(carpetaTemporal, { recursive: true });
+  // El cerco de lectura: el plugin (`lectura.js`) tiene que estar EN la carpeta
+  // del parche, porque el motor lo busca por su nombre relativo desde ahí. Se
+  // copia ANTES de arrancar el motor: si no está, el cerco no se monta.
+  copiarCerco(casa);
+  const rutaParche = join(carpetaTemporal, 'politica-' + id + '.yml');
+  writeFileSync(rutaParche, parcheDePolitica({ modo, espacio, raices: raices ?? [espacio] }));
+
+  // El hijo arranca SIN las variables de claves (ni las del cliente MCP ni las
+  // de Windows): la única fuente de claves es el almacén de la casa, que es lo
+  // que escribe Ajustes › Models. Si las heredara, el motor las daría por
+  // puestas y una clave vieja del entorno ganaría a la buena.
+  const entorno = entornoDelMotorSinClaves(casa, { ...process.env, DSH_HOME: casa, DSH_PERMISSION_MODE: modo });
+  for (const nombre of NO_HEREDAR) delete entorno[nombre];
+
+  const hijo = spawn(process.execPath, [dshBin, '--profile', 'sdk', '--patch', rutaParche], {
+    cwd: espacio,
+    env: entorno,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+
+  const sessionId = 'mcp-' + id;
+  let buffer = '';
+  let stderr = '';
+  let terminado = false;
+  let cancelada = false;
+  let motivoCancelacion = null;
+  let promptAceptado = false;
+  let texto = '';
+  let pasos = 0;
+  let ultimoMotivo = null;
+  const errores = [];
+  const uso = { input: 0, output: 0, total: 0, cache_read: 0, cache_write: 0, reasoning: 0, informado: false };
+  const empezado = Date.now();
+
+  let resolver;
+  let temporizador;
+  const promesa = new Promise((listo) => { resolver = listo; });
+
+  /** Cerrar una vez, con lo que haya. */
+  const terminar = (extra = {}) => {
+    if (terminado) return;
+    terminado = true;
+    if (temporizador !== undefined) clearTimeout(temporizador);
+    const resultado = {
+      ok: extra.ok ?? (errores.length === 0 && !cancelada),
+      texto,
+      pasos,
+      provider,
+      model,
+      session_id: sessionId,
+      duracion_ms: Date.now() - empezado,
+      tokens: { ...uso },
+      motivo: ultimoMotivo,
+      errores,
+      cancelada,
+      motivo_cancelacion: motivoCancelacion,
+      codigo_salida: extra.codigoSalida ?? null,
+      ...extra.extra,
+    };
+    // El hijo se va por las buenas; si no se va, se le mata.
+    cerrar()
+      .catch(() => { /* da igual: abajo se le mata si sigue vivo */ })
+      .finally(() => {
+        try { rmSync(rutaParche, { force: true }); } catch { /* da igual */ }
+        resolver(resultado);
+      });
+  };
+
+  const enviar = (idPeticion, method, params) => {
+    if (hijo.stdin.destroyed) return;
+    const frame = { jsonrpc: '2.0', id: idPeticion, method };
+    if (params !== undefined) frame.params = params;
+    try {
+      hijo.stdin.write(JSON.stringify(frame) + '\n');
+    } catch {
+      // El hijo se fue entre medias: quien tenga que enterarse, se enterará por `exit`.
+    }
+  };
+
+  const anotarUso = (u) => {
+    if (u === null || typeof u !== 'object') return;
+    uso.informado = true;
+    uso.input += numeroSeguro(u.inputTokens);
+    uso.output += numeroSeguro(u.outputTokens);
+    uso.total += numeroSeguro(u.totalTokens);
+    uso.cache_read += numeroSeguro(u.cacheReadTokens);
+    uso.cache_write += numeroSeguro(u.cacheWriteTokens);
+    uso.reasoning += numeroSeguro(u.reasoningTokens);
+  };
+
+  const alEventoDeSesion = (evento) => {
+    if (evento === null || typeof evento !== 'object') return;
+    if (alEvento !== undefined) alEvento(evento);
+    if (evento.type === 'assistant/message') {
+      pasos += 1;
+      const trozos = textoDeMensaje(evento.data?.message);
+      if (trozos !== '') texto = trozos;
+      anotarUso(evento.data?.usage);
+      return;
+    }
+    if (evento.type === 'turn/end') {
+      const motivo = evento.data?.reason;
+      if (motivo !== null && typeof motivo === 'object') {
+        ultimoMotivo = motivo.kind ?? null;
+        if (motivo.kind === 'error') {
+          errores.push(enEspanol(motivo.error?.message ?? 'la tarea falló sin mensaje'));
+        }
+      }
+    }
+  };
+
+  const manejarFrame = (frame) => {
+    if (frame.method === 'session.event') {
+      alEventoDeSesion(frame.params?.event);
+      return;
+    }
+    if (frame.method === 'session.status') {
+      if (frame.params?.status === 'idle' && promptAceptado) terminar();
+      return;
+    }
+    if (frame.id === 1) {
+      if (frame.error !== undefined) {
+        errores.push('el motor rechazó el arranque: ' + (frame.error.message ?? JSON.stringify(frame.error)));
+        terminar({ ok: false });
+        return;
+      }
+      enviar(2, 'session/prompt', {
+        sessionId,
+        contentBlocks: [{ type: 'text', text: prompt }],
+      });
+      return;
+    }
+    if (frame.id === 2) {
+      if (frame.error !== undefined) {
+        errores.push('el motor rechazó la tarea: ' + enEspanol(frame.error.message ?? JSON.stringify(frame.error)));
+        terminar({ ok: false });
+        return;
+      }
+      promptAceptado = true;
+      return;
+    }
+    if (frame.id === 3) {
+      terminar();
+    }
+  };
+
+  hijo.stdout.setEncoding('utf8');
+  hijo.stdout.on('data', (trozo) => {
+    buffer += trozo;
+    let corte;
+    while ((corte = buffer.indexOf('\n')) >= 0) {
+      const linea = buffer.slice(0, corte).trim();
+      buffer = buffer.slice(corte + 1);
+      if (linea === '') continue;
+      let frame;
+      try {
+        frame = JSON.parse(linea);
+      } catch {
+        errores.push('el motor escribió algo que no es protocolo por stdout: ' + linea.slice(0, 200));
+        continue;
+      }
+      try {
+        manejarFrame(frame);
+      } catch (e) {
+        errores.push('error manejando un frame del motor: ' + (e instanceof Error ? e.message : String(e)));
+      }
+    }
+  });
+
+  hijo.stderr.setEncoding('utf8');
+  hijo.stderr.on('data', (trozo) => {
+    stderr = (stderr + trozo).slice(-TOPE_STDERR);
+  });
+
+  hijo.on('error', (e) => {
+    errores.push('no pude arrancar el motor: ' + e.message);
+    terminar({ ok: false });
+  });
+
+  hijo.on('exit', (codigo) => {
+    if (terminado) return;
+    if (cancelada) {
+      terminar({ ok: false, codigoSalida: codigo });
+      return;
+    }
+    if (errores.length === 0) {
+      errores.push('el motor se cerró antes de terminar (código ' + codigo + ')'
+        + (stderr.trim() === '' ? '' : ': ' + enEspanol(ultimaLinea(stderr))));
+    }
+    terminar({ ok: false, codigoSalida: codigo });
+  });
+
+  /** Pedirle al hijo que se vaya por las buenas. */
+  const cerrar = async () => {
+    // Cancelar es inmediato: el árbol ya está muerto y no se le espera cortesías.
+    if (cancelada) return;
+    if (hijo.exitCode !== null || hijo.signalCode !== null) return;
+    enviar(3, 'shutdown');
+    await esperar(GRACIA_MS);
+    if (hijo.exitCode === null && hijo.signalCode === null) matarArbol(hijo);
+  };
+
+  /** Cancelar: matar el árbol del hijo. Inmediato y sin efectos en la web. */
+  const cancelar = (motivo = 'cancelada por el cliente') => {
+    if (terminado) return;
+    cancelada = true;
+    motivoCancelacion = motivo;
+    matarArbol(hijo);
+    terminar({ ok: false, extra: { motivo_cancelacion: motivo } });
+  };
+
+  if (typeof timeoutMs === 'number' && timeoutMs > 0) {
+    temporizador = setTimeout(() => cancelar('se agotó el tiempo (' + timeoutMs + ' ms)'), timeoutMs);
+  }
+
+  enviar(1, 'initialize', {
+    cwd: espacio,
+    provider,
+    model,
+    ...(typeof maxTokens === 'number' && maxTokens > 0 ? { maxTokens } : {}),
+  });
+
+  return { promesa, cancelar, pid: hijo.pid };
+}
+
+/** Un número seguro (los contadores que falten cuentan como 0). */
+function numeroSeguro(valor) {
+  return typeof valor === 'number' && Number.isFinite(valor) ? valor : 0;
+}
+
+/** El texto de un mensaje del asistente, sin las partes que no son texto. */
+function textoDeMensaje(mensaje) {
+  const contenido = mensaje?.content;
+  if (!Array.isArray(contenido)) return '';
+  return contenido
+    .filter((bloque) => bloque !== null && typeof bloque === 'object' && bloque.type === 'text' && typeof bloque.text === 'string')
+    .map((bloque) => bloque.text)
+    .join('\n')
+    .trim();
+}
+
+/** La última línea con algo de un texto. */
+function ultimaLinea(texto) {
+  const lineas = texto.trim().split(/\r?\n/).filter((l) => l.trim() !== '');
+  return lineas.length === 0 ? '' : lineas[lineas.length - 1];
+}
+
+/**
+ * Traducir los fallos del motor que el humano va a leer. Sólo los que ya tienen
+ * traducción: el mensaje original del motor se conserva detrás, para poder
+ * buscarlo. Si no hay traducción, se devuelve tal cual (no se inventa nada).
+ */
+function enEspanol(mensaje) {
+  const texto = String(mensaje);
+  if (/MISSING_CREDENTIAL|no credential for provider route/i.test(texto)) {
+    return 'el motor no encontró la clave de ese proveedor en la casa.'
+      + ' Pégala en RATACODE › Ajustes › Models (queda en ' + '<casa>/.credentials.yaml' + '). [motor] ' + texto;
+  }
+  return texto;
+}
+
+/** Esperar, sin más. */
+function esperar(ms) {
+  return new Promise((listo) => setTimeout(listo, ms));
+}
+
+/** Matar el árbol entero del hijo (en Windows, `taskkill /T`). */
+function matarArbol(hijo) {
+  if (hijo === undefined || hijo === null || hijo.pid === undefined) return;
+  try {
+    if (process.platform === 'win32') {
+      spawn(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 'taskkill /pid ' + hijo.pid + ' /T /F'], { windowsHide: true, stdio: 'ignore' });
+    } else {
+      hijo.kill('SIGTERM');
+    }
+  } catch { /* ya se fue */ }
+}

package/mcp/lib/registro.js

@@ -0,0 +1,21 @@
+/**
+ * registro — hablar sin romper el protocolo.
+ *
+ * El transporte stdio de MCP es DUEÑO de stdout: un solo `console.log` nuestro
+ * dentro de stdout y el cliente deja de entender los frames. Por eso aquí todo
+ * lo que contamos va a stderr, y stdout sólo lo toca el SDK.
+ *
+ * Regla de la casa, además: aquí NUNCA se escribe el valor de una clave. Sólo
+ * su nombre y de dónde sale.
+ */
+
+/** Un aviso para el humano (stderr, nunca stdout). */
+export function aviso(...trozos) {
+  process.stderr.write('RATACODE-MCP · ' + trozos.join(' ') + '\n');
+}
+
+/** Un error con pila, también por stderr. */
+export function fallo(que, error) {
+  const texto = error instanceof Error ? (error.stack ?? error.message) : String(error);
+  process.stderr.write('RATACODE-MCP · ' + que + ': ' + texto + '\n');
+}

package/mcp/lib/seguridad.js

@@ -0,0 +1,283 @@
+/**
+ * seguridad — el espacio de trabajo manda, y lo peligroso se pide.
+ *
+ * Tres ideas, y ninguna es adorno:
+ *
+ * 1 · ESPACIO CERRADO. Una tarea sólo puede trabajar dentro de las raíces
+ *     autorizadas (`mcp.workspaces` en los ajustes de la casa). Si no hay
+ *     ninguna declarada, la única raíz es el espacio por defecto o la carpeta
+ *     desde la que arrancó el servidor. Todo lo demás se rechaza con un error
+ *     que dice qué hacer. Esto es lo que evita que un agente se ponga a
+ *     trabajar por todo el disco.
+ *
+ * 2 · EL SANDBOX LO IMPONE EL CORE, no nosotros. El modo por defecto es
+ *     `workspace-write` y el cwd de la sesión es su frontera de escritura
+ *     (medido en `dsh-sandbox-policy/lib/types/index.d.ts:40-55`). Nosotros no
+ *     reimplementamos nada: le pasamos al hijo un parche que FIJA el modo, para
+ *     que ni un `DSH_PERMISSION_MODE` heredado del entorno pueda aflojarlo.
+ *
+ *     OJO, y es lo que se midió en R25: fijar `sandbox-policy` NO bastaba. La
+ *     casa de fábrica trae `permission.defaultPreset: danger-full-access`
+ *     (`fabrica/settings.yaml`) y ese ajuste se aplica AL CREAR la sesión
+ *     (`dsh-permission-presets/README.md:64`), así que ganaba al parche. Por eso
+ *     el parche APAGA la fila `permission` en el hijo del MCP: sin ese servicio,
+ *     el modo que manda es el de `sandbox-policy`, que es el nuestro. El panel
+ *     del usuario no se toca: sigue con el preset que él elija.
+ *
+ * 3 · SIN VÍAS DE ESCAPE. Un modo de escritura no sirve de nada si el agente
+ *     puede abrir una terminal y escribir por ella. El parche apaga las filas
+ *     de las herramientas que ejecutan, navegan o delegan (abajo, una por una).
+ *
+ * 4 · LA LECTURA, CON GANCHO. El motor no sabe acotar la lectura (ni un modo,
+ *     ni un ajuste, ni un plugin: mira `lib/lectura.js`). Se acota con el gancho
+ *     `tools/pre-execute` de `@deepseek-ai/dsh-hooks-claude-code`, que recibe
+ *     cada llamada antes de ejecutarse y la puede DENEGAR. El parche monta ese
+ *     gancho con las raíces autorizadas, y el guion es `lib/lectura.js`.
+ *
+ * 5 · LO PELIGROSO SE PIDE DOS VECES. `allow_dangerous` en la llamada no basta:
+ *     hace falta que el humano haya encendido `mcp.permitir_peligroso` en la
+ *     casa. Si no, se deniega y se explica. Nunca se queda esperando una
+ *     aprobación que no existe: en un servidor MCP no hay a quién preguntar.
+ */
+import { copyFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ajustesMcp } from './casa.js';
+import { canonica, comparable, estaDentro, normalizarRuta } from './lectura.js';
+
+/** El fichero del cerco de lectura (el plugin que se copia junto al parche). */
+const GUION_DEL_CERCO = fileURLToPath(new URL('./lectura.js', import.meta.url));
+
+/**
+ * Las herramientas del motor que SE APAGAN en toda tarea del MCP, con el motivo
+ * de cada una (ids reales de la composición `sdk`, volcada con `--dump-config`).
+ *
+ *   · `tool-pwsh` y `tool-bash` — una terminal escribe fuera del cerco y lee
+ *     fuera del cerco: es la vía de escape entera.
+ *   · `tool-jobs` — `job_kill` mata procesos que la tarea no arrancó y
+ *     `job_output` lee lo que dejaron: control de procesos fuera del cerco.
+ *   · `tool-web` — `web_search`/`web_fetch` sacan a la red lo que la tarea lea
+ *     (y traen de fuera lo que sea, saltándose el cerco de ficheros).
+ *   · `tool-subagent`, `tool-subagent-fork`, `tool-subagent-control`,
+ *     `tool-subagent-list-agents` — delegan en otro agente: otra puerta con
+ *     herramientas que no son de esta tarea.
+ *   · `tool-workflow` — ejecuta un guion de JavaScript que orquesta subagentes.
+ *   · `tool-ralph` — el bucle «Ralph» arranca agentes nuevos (subagentes).
+ */
+export const HERRAMIENTAS_QUE_SE_APAGAN = [
+  ['tool-pwsh', 'una terminal ejecuta y lee fuera del cerco'],
+  ['tool-bash', 'una terminal ejecuta y lee fuera del cerco'],
+  ['tool-jobs', 'job_kill mata procesos ajenos; job_output lee lo que dejaron'],
+  ['tool-web', 'la red saca de la máquina lo que la tarea lea'],
+  ['tool-subagent', 'delega en otro agente, con sus propias herramientas'],
+  ['tool-subagent-fork', 'delega en otro agente heredando esta conversación'],
+  ['tool-subagent-control', 'habla con agentes ya lanzados y los interrumpe'],
+  ['tool-subagent-list-agents', 'enumera y alcanza agentes de otras sesiones'],
+  ['tool-workflow', 'un guion de JavaScript orquesta subagentes a escala'],
+  ['tool-ralph', 'el bucle Ralph arranca agentes nuevos'],
+];
+
+/**
+ * ¿Es la raíz de un disco (`C:\`, `/`)? Un espacio de trabajo así es todo el
+ * disco, y en modo HTTP eso no se admite.
+ * @param {string} ruta - ruta ya normalizada.
+ * @returns {boolean}
+ */
+export function esRaizDeDisco(ruta) {
+  const limpia = ruta.endsWith(sep) && ruta.length > 1 ? ruta.slice(0, -1) : ruta;
+  return /^[a-z]:$/i.test(limpia) || limpia === '' || limpia === '/';
+}
+
+/**
+ * ¿Es la carpeta del usuario (o la que los contiene a todos)? En modo HTTP no se
+ * admite como espacio de trabajo: con la URL en la mano sería el PC entero a un
+ * `working_directory` de distancia.
+ * @param {string} ruta - ruta ya normalizada.
+ * @returns {boolean}
+ */
+export function esCarpetaDeUsuario(ruta) {
+  const a = comparable(ruta);
+  return a === comparable(normalizarRuta(homedir())) || a === comparable(normalizarRuta(dirname(homedir())));
+}
+
+/**
+ * Resolver el espacio de una tarea, o negarse con un motivo útil.
+ * @param {{casa: string, pedido?: string, cwdPorDefecto: string, http?: boolean}} opciones
+ * @returns {{espacio: string, raiz: string, raices: string[], avisos: string[]}}
+ */
+export function resolverEspacio({ casa, pedido, cwdPorDefecto, http = false }) {
+  const ajustes = ajustesMcp(casa);
+  const avisos = [...ajustes.avisos];
+
+  // En modo HTTP (el del túnel) el espacio se aprieta: sin `mcp.workspaces`
+  // declarados no se trabaja. Si no, la única raíz sería la carpeta desde la que
+  // arrancó el servidor —que puede ser la carpeta de usuario entera— y con la
+  // URL en la mano eso es el disco ajeno.
+  if (http && ajustes.workspaces.length === 0) {
+    throw new Error(
+      'en modo HTTP hacen falta espacios declarados: pon `mcp.workspaces:` en ' + casa
+      + '\\settings.yaml con las carpetas donde puede trabajar (y `workspace_por_defecto:` si quieres'
+      + ' una por defecto). Sin esa lista, la única raíz sería la carpeta desde la que arrancó el'
+      + ' servidor, y eso, con la URL en la mano de cualquiera, es demasiado.',
+    );
+  }
+
+  let raices = ajustes.workspaces.length > 0
+    ? ajustes.workspaces.map(normalizarRuta)
+    : [normalizarRuta(ajustes.workspacePorDefecto ?? cwdPorDefecto)];
+  if (ajustes.workspaces.length === 0) {
+    avisos.push('la casa no tiene `mcp.workspaces`: sólo se permite ' + raices[0]);
+  }
+
+  // Ni la raíz de un disco ni la carpeta del usuario como espacio: se niegan en
+  // modo HTTP, que es el que se expone. (En local el humano arrancó el servidor
+  // en su propia carpeta a propósito, y ahí manda él.)
+  if (http) {
+    const permitidas = raices.filter((r) => !esRaizDeDisco(r) && !esCarpetaDeUsuario(r));
+    for (const fuera of raices.filter((r) => !permitidas.includes(r))) {
+      avisos.push('espacio demasiado ancho, lo ignoro: ' + fuera
+        + ' (ni la raíz de un disco ni tu carpeta de usuario valen como espacio de trabajo en modo HTTP)');
+    }
+    if (permitidas.length === 0) {
+      throw new Error(
+        'no queda ningún espacio de trabajo admisible: ni la raíz de un disco ni tu carpeta de usuario ('
+        + homedir() + ' y ' + dirname(homedir()) + ') valen. Declara `mcp.workspaces` en '
+        + casa + '\\settings.yaml con carpetas de trabajo de verdad.',
+      );
+    }
+    raices = permitidas;
+  }
+
+  const candidato = pedido === undefined || pedido === null || String(pedido).trim() === ''
+    ? raices[0]
+    : normalizarRuta(String(pedido));
+
+  if (!existsSync(candidato)) {
+    throw new Error('el espacio de trabajo no existe: ' + candidato);
+  }
+  if (!statSync(candidato).isDirectory()) {
+    throw new Error('el espacio de trabajo no es una carpeta: ' + candidato);
+  }
+  if (http && (esRaizDeDisco(candidato) || esCarpetaDeUsuario(candidato))) {
+    throw new Error(
+      'el espacio de trabajo ' + candidato + ' es demasiado ancho para modo HTTP: ni la raíz de un'
+      + ' disco ni tu carpeta de usuario valen. Usa una carpeta de trabajo de verdad.',
+    );
+  }
+
+  const raiz = raices.find((r) => estaDentro(candidato, r));
+  if (raiz === undefined) {
+    throw new Error(
+      'el espacio de trabajo ' + candidato + ' está fuera de los espacios autorizados ('
+      + raices.join(', ') + '). Si de verdad quieres trabajar ahí, añádelo a `mcp.workspaces` en '
+      + casa + '\\settings.yaml y vuelve a llamarme.',
+    );
+  }
+  return { espacio: candidato, raiz, raices, avisos };
+}
+
+/**
+ * Qué modo de sandbox se usará, y por qué.
+ * @param {{casa: string, allowDangerous?: boolean}} opciones
+ * @returns {{modo: 'workspace-write'|'danger-full-access', motivo: string}}
+ */
+export function resolverModo({ casa, allowDangerous }) {
+  if (allowDangerous !== true) {
+    return { modo: 'workspace-write', motivo: 'por defecto: escritura sólo dentro del espacio de trabajo' };
+  }
+  const ajustes = ajustesMcp(casa);
+  if (!ajustes.permitirPeligroso) {
+    throw new Error(
+      'me pides `allow_dangerous` pero la casa no lo tiene permitido. Para habilitarlo, pon '
+      + '`mcp: { permitir_peligroso: true }` en ' + casa + '\\settings.yaml. Hasta entonces, la tarea '
+      + 'corre en `workspace-write`: escribe sólo dentro del espacio de trabajo (y lee, en los dos casos,'
+      + ' sólo dentro de las carpetas autorizadas: mira `lib/lectura.js`).',
+    );
+  }
+  return { modo: 'danger-full-access', motivo: 'autorizado por la casa (`mcp.permitir_peligroso`) y pedido en la llamada' };
+}
+
+/** Un valor YAML entre comillas simples, sin sorpresas con las barras de Windows. */
+function yamlSeguro(texto) {
+  return "'" + String(texto).replace(/'/g, "''") + "'";
+}
+
+/**
+ * El parche que se le pasa al hijo para FIJAR su política, pase lo que pase en
+ * el entorno heredado. Es la única pieza que el MCP le añade al perfil `sdk`.
+ *
+ * Cinco bloques, y cada uno está por un motivo medido:
+ *   1. el modo y la raíz de escritura de esta tarea;
+ *   2. `permission` APAGADO: la casa puede tener
+ *      `permission.defaultPreset: danger-full-access` (es lo que trae la fábrica,
+ *      y es lo que el panel del usuario necesita), y ese ajuste se aplica al
+ *      crear la sesión y ganaría a (1). Sin ese servicio manda (1);
+ *   3. las herramientas que ejecutan, navegan o delegan, apagadas una a una
+ *      ({@link HERRAMIENTAS_QUE_SE_APAGAN});
+ *   4. el cerco de la LECTURA: se inserta `./lectura.js` (el plugin que copia
+ *      {@link copiarCerco}) con las carpetas autorizadas dentro;
+ *   5. nada más: no se toca ni un fichero del motor.
+ *
+ * El `insert` es la única forma de AÑADIR una fila (un parche con `id` sólo
+ * retoca una que ya exista: `cordis-plugin-include/lib/index.js:67-89`), y el
+ * nombre `./lectura.js` se resuelve desde la CARPETA DEL PARCHE
+ * (`cordis-plugin-loader/lib/index.js:273-278`), o sea, `<casa>\mcp\tmp\`.
+ * @param {{modo: string, espacio: string, raices?: string[]}} opciones
+ * @returns {string} contenido YAML del overlay `--patch`.
+ */
+export function parcheDePolitica({ modo, espacio, raices }) {
+  const lineas = [
+    '# Generado por RATACODE-MCP para UNA tarea. No editar: se reescribe en cada llamada.',
+    '# Fija el modo del sandbox, apaga las vías de escape y monta el cerco de lectura,',
+    '# por encima de lo que diga el entorno heredado o los ajustes de la casa.',
+    '- id: sandbox-policy',
+    '  config:',
+    '    mode: ' + modo,
+    '    workspaceRoot: ' + yamlSeguro(espacio),
+    '',
+    '# La casa de fábrica trae `permission.defaultPreset: danger-full-access` y ese ajuste',
+    '# se aplica AL CREAR la sesión, ganando al modo de arriba. Aquí se apaga el servicio de',
+    '# presets en el hijo del MCP: sin él, el modo que manda es el de `sandbox-policy`.',
+    '- id: permission',
+    '  disabled: true',
+    '',
+    '# Sin terminal, sin red, sin subagentes y sin guiones: nada con lo que saltar el cerco.',
+  ];
+  for (const [id, motivo] of HERRAMIENTAS_QUE_SE_APAGAN) {
+    lineas.push('', '# ' + id + ': ' + motivo, '- id: ' + id, '  disabled: true');
+  }
+  lineas.push(
+    '',
+    '# El cerco de la LECTURA: un plugin de cordis que engancha `tools/pre-execute` y',
+    '# deniega la herramienta que lleve una ruta fuera de estas carpetas.',
+    '- insert:',
+    '    - name: ' + yamlSeguro(NOMBRE_DEL_CERCO),
+    '      config:',
+    '        raices:',
+  );
+  const limpias = [...new Set((raices ?? [espacio]).map((r) => normalizarRuta(r)).filter((r) => r !== ''))];
+  for (const raiz of limpias) lineas.push('          - ' + yamlSeguro(raiz));
+  lineas.push('');
+  return lineas.join('\n') + '\n';
+}
+
+/** El nombre del fichero del cerco, copiado junto al parche (mismo directorio). */
+const NOMBRE_DEL_CERCO = './lectura.js';
+
+/**
+ * Dejar el plugin del cerco junto al parche: el motor lo busca por su nombre
+ * relativo (`./lectura.js`) desde la carpeta del parche, así que tiene que estar
+ * ahí. Se copia el fichero de verdad (el mismo que se prueba), no una copia
+ * escrita a mano: lo que se prueba es lo que se monta.
+ * @param {string} casa - la casa de RATACODE.
+ * @returns {string} la ruta del plugin copiado.
+ */
+export function copiarCerco(casa) {
+  const carpeta = join(casa, 'mcp', 'tmp');
+  mkdirSync(carpeta, { recursive: true });
+  const destino = join(carpeta, 'lectura.js');
+  copyFileSync(GUION_DEL_CERCO, destino);
+  return destino;
+}
+