xonecode 0.38.44 → 0.39.2

package/dist/agent/subagentes/escrituraExterna.d.ts

@@ -0,0 +1,419 @@
+/**
+ * Qué puede hacer un agente EXTERNO (Claude Code) dentro de la carpeta del proyecto.
+ *
+ * Este fichero existe porque conceder escritura a un agente externo no es levantar una
+ * bandera: sus `Write`/`Edit` van **directos al disco con una ruta ABSOLUTA**, así que se
+ * saltan por completo las cuatro capas que protegen al proyecto por el camino de LangGraph
+ * —`permisosDe`, el `virtualMode` del backend, las vistas aplanadas y las guardas de
+ * artefactos y descargas—. Sin volver a aplicarlas aquí, «el agente externo ya puede
+ * escribir» significaría también «ya puede escribir `.env`, `.git` y cualquier sitio fuera
+ * del proyecto», y eso no es una capacidad nueva: es el agujero más grande que este repo
+ * puede tener.
+ *
+ * Tres piezas, y las tres son puras o con su dependencia inyectada, para que `npm test` las
+ * pruebe sin lanzar un Claude Code:
+ * 1. **Tres listas** de tools (`claseDeToolExterna`): lectura, escritura y denegadas. Tres y
+ *    no dos, porque conceder escritura NO puede conceder `Bash` ni `WebFetch`.
+ * 2. **El veredicto de una ruta** (`veredictoDeRuta`), que vuelve a aplicar las guardas del
+ *    proyecto sobre la ruta absoluta del hijo — y las aplica DOS veces, sobre el texto y
+ *    sobre el `realpath`, que es la misma regla que ya sostiene `arbolDeProyecto.ts`.
+ * 3. **El adaptador de política** (`politicaDeAprobacionExterna`), que convierte el
+ *    `pedirAprobacion` que ya existe en la política de escritura del hijo.
+ */
+import type { LineaDeDiff } from "../../core/diff.js";
+import type { PendienteDeAprobacion } from "../../core/events.js";
+import type { ColaDeEventos } from "../../core/entrelazar.js";
+import type { ConsumoExterno, EjecucionExterna, EscrituraExternaPedida, PoliticaDeEscrituraExterna, ToolDeUnHijo } from "../../core/ports.js";
+import type { Decision } from "../../vendor/hitl.js";
+/**
+ * Las tools del hijo que solo LEEN.
+ *
+ * Los nombres salen del SDK instalado y no de la memoria: se comprobaron contra
+ * `sdk-tools.d.ts` de `@anthropic-ai/claude-agent-sdk`, cuya unión `ToolInputSchemas`
+ * enumera hoy **cuarenta y cuatro** tools —`REPL`, `Workflow`, `Cron*`, `Artifact`,
+ * `RemoteTrigger`, `Monitor`, `Mcp`, `EnterWorktree`…— y crece con cada versión del
+ * producto. Esa cifra es el argumento entero de este fichero: con una lista negra, la tool
+ * que Claude Code añada mañana entraría permitida.
+ *
+ * `TodoWrite` está dentro pese al nombre: es la lista de tareas del propio hijo, vive en su
+ * memoria y no toca el disco del proyecto.
+ */
+export declare const TOOLS_EXTERNAS_DE_LECTURA: ReadonlySet<string>;
+/**
+ * Las que escriben en el proyecto, y por tanto pasan por la política.
+ *
+ * **Solo `Write` y `Edit`**, y las dos por una razón que se puede comprobar: son las únicas
+ * cuyos argumentos encajan en `cambioDe()`, o sea las únicas de las que se puede COMPONER
+ * el diff que una persona tiene que ver antes de decidir. Medido en `sdk-tools.d.ts`:
+ * `FileWriteInput` es `{file_path, content}` y `FileEditInput` es
+ * `{file_path, old_string, new_string, replace_all?}`, que son exactamente las claves que
+ * `write_file` y `edit_file` ya traen por el camino de LangGraph.
+ *
+ * Lo que se queda fuera y por qué, dicho aquí para que no parezca un olvido:
+ * - **`NotebookEdit`** no lleva `file_path` sino `notebook_path`, y un proyecto XOne no
+ *   tiene cuadernos de Jupyter. Conceder una escritura de la que no se sabe componer el
+ *   diff sería aprobar a ciegas.
+ * - **`MultiEdit`** ya no existe en este SDK (cero apariciones en su unión de tools), y el
+ *   día que vuelva tampoco entra de rebote: es una LISTA de ediciones, así que una sola
+ *   aprobación cubriría N cambios — o se expande a N decisiones o se deniega. Hoy, denegada.
+ */
+export declare const TOOLS_EXTERNAS_DE_ESCRITURA: ReadonlySet<string>;
+/**
+ * Las que se deniegan SIEMPRE, con escritura concedida o sin ella.
+ *
+ * Aquí está la mitad del arreglo. Antes la decisión era
+ * `permitirEscritura || esDeLectura(nombre)`, o sea que el día que se concediera la
+ * escritura se concedía **todo**: `Bash` sola basta para escribir el proyecto entero
+ * —saltándose de paso la política, el diff y las guardas de ruta de este fichero—, y
+ * `WebFetch`/`WebSearch` no escriben pero sacan el contenido del proyecto fuera de la
+ * máquina, que no lo decide un especialista.
+ *
+ * La lista es ILUSTRATIVA y no la barrera: la barrera es que lo que no esté en las dos
+ * listas de arriba se deniega igual (`claseDeToolExterna` contesta «desconocida»). Existe
+ * para que el motivo pueda decir POR QUÉ se deniega esta en concreto, que es lo que evita
+ * que el hijo insista.
+ */
+export declare const TOOLS_EXTERNAS_DENEGADAS: ReadonlySet<string>;
+export type ClaseDeToolExterna = "lectura" | "escritura" | "denegada" | "desconocida";
+/**
+ * En qué lista cae una tool. **Deniega por omisión**: lo que no se reconoce es
+ * «desconocida», que no es un tercer estado benigno — se trata igual que «denegada».
+ */
+export declare function claseDeToolExterna(nombre: string): ClaseDeToolExterna;
+/** Admitida trae la ruta VIRTUAL (`/app/Clientes.xne`); denegada trae el motivo. */
+export type VeredictoDeRuta = {
+    admitida: true;
+    ruta: string;
+} | {
+    admitida: false;
+    motivo: string;
+};
+/**
+ * La ruta virtual de una ruta absoluta del hijo, o `undefined` si no se puede afirmar que
+ * cae dentro del proyecto.
+ *
+ * Una relativa se rechaza en vez de resolverse contra el `cwd`: el SDK documenta que
+ * `file_path` es absoluta («must be absolute, not relative»), así que una relativa es algo
+ * que no entendemos, y lo que no se entiende se deniega.
+ */
+export declare function rutaVirtualDeEscritura(cwd: string, filePath: string): string | undefined;
+/**
+ * ¿Puede el hijo escribir en esta ruta? **Las guardas del proyecto, reaplicadas.**
+ *
+ * Y se aplican DOS veces, que es la lección de `arbolDeProyecto.ts` medida en su día: sobre
+ * el TEXTO —de balde, antes de tocar el disco— y sobre el camino REAL. Sin la segunda no
+ * era verdad: en un sistema que no distingue mayúsculas (APFS, NTFS) `.ENV` no es `/.env`
+ * para `puedeLeerRuta` pero abre `.env`, y un enlace simbólico dentro de la raíz que apunte
+ * a un fichero denegado o a fuera del proyecto pasa la comprobación de «sigue dentro»
+ * porque su texto sí lo está. Lo que falla no es el sitio, es el destino.
+ *
+ * Del fichero que se va a escribir se canonicaliza el PADRE y no él: una escritura normal
+ * crea un fichero que todavía no existe, así que su `realpath` lanzaría y esto denegaría
+ * toda creación de ficheros nuevos.
+ *
+ * `real` entra por parámetro como el `leer` de `cambioDe`: en producción es `realpathSync`,
+ * y un test puede darle un doble. Que lance —el padre no existe— no es admitir: es denegar,
+ * porque entonces no se sabe dónde cae.
+ */
+export declare function veredictoDeRuta(opciones: {
+    cwd: string;
+    ruta: unknown;
+    /** Las del proyecto, para reconocer una vista aplanada (`X.xml` con un `X.xne` al lado). */
+    ficheros: ReadonlySet<string>;
+    real?: (ruta: string) => string;
+    /**
+     * `true` para una LECTURA: se comprueba el confinamiento y lo que no se puede ni leer,
+     * pero no las reglas que solo gobiernan escrituras (un artefacto mal puesto de antes hay
+     * que poder leerlo para moverlo, y `/skills/` y `/adjuntos/` existen para leerse).
+     */
+    soloConfinamiento?: boolean;
+}): VeredictoDeRuta;
+/**
+ * La decisión del hook `PreToolUse`, que es la que NO se puede ensombrecer.
+ *
+ * **Esto no es un cinturón de más: es el único sitio donde la denegación es cierta**, y sale
+ * de leer el SDK instalado en vez de suponerlo. Tres frases suyas, textuales:
+ * - «Allow rules from settings files can also shadow the callback» — o sea que `canUseTool`
+ *   puede no invocarse nunca.
+ * - «Denials that resolve before canUseTool runs — PreToolUse hook denies, and deny-rule
+ *   overrides of hook allow/ask decisions — are not covered here» — o sea que un deny del
+ *   hook resuelve ANTES y gana.
+ * - «With a permission prompt surface (stdio/SDK canUseTool), the 'ask' path surfaces via a
+ *   can_use_tool control_request» — o sea que `ask` es cómo se llega a nuestro callback.
+ *
+ * Y de ahí sale el reparto: el hook contesta las TRES clases explícitamente —`allow` para
+ * leer, `deny` para todo lo que no está en las listas, y `ask` para escribir, que es lo que
+ * empuja la decisión hacia `canUseTool`, donde sí se puede esperar a una persona— y no deja
+ * ninguna sin decidir. Dejar una sin decidir sería dejar que la decida el `permissionMode`,
+ * cuyas semánticas exactas NO están medidas: `dontAsk` («deny if not pre-approved») podría
+ * denegar la escritura antes del callback y dejar la función muerta con todo en verde, y
+ * `default` («prompts for dangerous operations») podría aprobar `WebSearch` por su cuenta
+ * sin consultarnos — que es el fallo en la dirección mala.
+ */
+export declare function decisionDePreToolUse(opciones: {
+    nombre: string;
+    entrada: Record<string, unknown>;
+    cwd: string;
+    ficheros: ReadonlySet<string>;
+    real?: (ruta: string) => string;
+    /** La ejecución concedida a ESTE hijo (`PeticionExterna.ejecucion`). Ausente: `Bash` se deniega. */
+    ejecucion?: Pick<EjecucionExterna, "scripts" | "lecturas">;
+    /** Las carpetas de las skills montadas (`pluginDeSkills.ts#carpetasDeLecturaDeSkills`): se pueden LEER enteras. */
+    lecturasDeSkills?: readonly string[];
+    /** Las carpetas de la sesión que puede leer aunque no ejecute (`PeticionExterna.lecturas`). */
+    lecturasDeSesion?: readonly string[];
+}): {
+    hookEventName: "PreToolUse";
+    permissionDecision: "allow" | "deny" | "ask";
+    permissionDecisionReason: string;
+};
+/**
+ * **Las tools de LECTURA también llevan guarda de ruta, y esto salió de correrlo.**
+ *
+ * Medido en la segunda ejecución viva (11-09-2026), dicho por el propio hijo: «`.env` — sí
+ * pude leerlo: contiene una línea `CLAVE=secreta`». La lista blanca permitía `Read` a secas,
+ * sin mirar la ruta — y era así desde el primer día, o sea que el agujero no lo abrió la
+ * escritura: ya estaba. Por el camino de LangGraph esto no pasa porque `DENEGADO_SIEMPRE`
+ * deniega `read` sobre `/.env`, `/.git` y `/.xonecode`; ahí dentro además vive el
+ * `checkpoint.sqlite`, que lleva la lista de mensajes ENTERA de cada conversación.
+ *
+ * Qué se deniega leer, y por qué no es la misma lista que para escribir:
+ * - `/.env`, `/.git`, `/.xonecode`: las de `DENEGADO_SIEMPRE` para `read`, por lo mismo.
+ * - Las **vistas aplanadas**: el backend se las RETIRA al agente entero
+ *   (`sinVistasAplanadas`), no solo para escribir — si las ve, edita el fichero equivocado.
+ * - Y lo que caiga **fuera de la carpeta del proyecto**, que es la mitad que nadie había
+ *   comprobado: el `file_path` de `Read` es absoluto y puede nombrar cualquier cosa.
+ * - `/skills/`, `/adjuntos/` y `/artefactos/` NO se deniegan: leerlos es su razón de ser.
+ *
+ * `Glob` y `Grep` llevan `path` OPCIONAL (medido en `sdk-tools.d.ts`), y ausente significa
+ * la raíz: entonces no hay nada que comprobar. **Límite declarado**: un `Grep` sobre la raíz
+ * puede devolver líneas de un fichero denegado, porque `canUseTool` decide sobre la LLAMADA
+ * y no puede filtrar su salida. Cerrarlo exigiría un hook `PostToolUse`, que no está puesto.
+ */
+export declare function veredictoDeLectura(opciones: {
+    cwd: string;
+    nombre: string;
+    entrada: Record<string, unknown>;
+    ficheros: ReadonlySet<string>;
+    real?: (ruta: string) => string;
+    /** Carpetas de FUERA del proyecto que este hijo puede leer (`EjecucionExterna.lecturas`). */
+    lecturas?: readonly string[];
+}): {
+    admitida: true;
+} | {
+    admitida: false;
+    motivo: string;
+};
+/**
+ * El motivo de NO dejar correr ese `Bash`, o `undefined` si se deja: su `command` tiene que pasar
+ * `motivoDeComandoExternoInaceptable`, y no puede ir en segundo plano (`BashOutput` y `KillShell`
+ * siguen cerrados: un comando que se queda vivo no lo para nadie).
+ */
+export declare function motivoDeBashExterno(entrada: Record<string, unknown>, scripts: readonly string[]): string | undefined;
+/**
+ * Todo lo de FUERA del proyecto que un hijo puede leer: las carpetas de su sesión si ejecuta (capturas, hotswap) y las de
+ * las skills montadas. Una sola función para el hook y para `canUseTool`: las dos llaves tienen que decir lo mismo.
+ */
+export declare function lecturasDelHijo(ejecucion: Pick<EjecucionExterna, "lecturas"> | undefined, lecturasDeSkills: readonly string[] | undefined, lecturasDeSesion?: readonly string[]): string[];
+/**
+ * ¿Cae esta ruta dentro de una de las carpetas de la sesión que el hijo con ejecución puede leer
+ * (sus capturas en artefactos, lo de hotswap)? Por TEXTO —`resolve` deshace un `..`— Y por el
+ * camino REAL —un enlace dentro de la carpeta que apunte a `checkpoint.sqlite` no pasa—, las dos,
+ * como el resto de guardas. Lo que no se puede canonicalizar no está dentro.
+ */
+export declare function dentroDeUnaLectura(ruta: string, lecturas: readonly string[], real: (ruta: string) => string): boolean;
+/** El motivo que se le devuelve al hijo cuando la tool entera no está concedida. */
+export declare function motivoDeToolDenegada(nombre: string, clase: ClaseDeToolExterna): string;
+/** Por qué `correr` rechaza cuando se paró el turno: el hijo se mató, no terminó su encargo. */
+export declare const MOTIVO_DE_CANCELACION_EXTERNA = "el turno se cancel\u00F3 y el agente externo se ha detenido";
+/** Y el motivo cuando el propio SDK abortó mientras se esperaba la decisión. */
+export declare const MOTIVO_DE_ESCRITURA_ABORTADA = "la petici\u00F3n se cancel\u00F3 antes de que nadie autorizara esa escritura, as\u00ED que no se ha escrito nada.";
+/** El motivo cuando la escritura se pidió bien y quien decide dijo que no. */
+export declare const MOTIVO_DE_ESCRITURA_RECHAZADA = "la escritura no se ha autorizado. No la intentes por otro camino: explica qu\u00E9 quer\u00EDas cambiar y por qu\u00E9.";
+/**
+ * El MODO de escritura de la sesión, tal y como lo ve la política de un motor externo.
+ *
+ * Es una función y no un booleano porque se pregunta en cada tanda (`/aprobacion` cambia el
+ * modo con la sesión en marcha), y el apunte es opcional porque quien monta la política en
+ * un test no tiene aviso de honestidad que alimentar.
+ */
+export interface ModoDeLaSesion {
+    /** ¿Se aplica sin enseñar el diff, AHORA? Ver `core/modoDeEscritura.ts#seEscribeSinPreguntar`. */
+    sinPreguntar: () => boolean;
+    /** Las rutas que se acaban de aplicar sin preguntar, para el aviso del turno. */
+    alAplicarSinPreguntar?: (rutas: readonly string[]) => void;
+}
+/**
+ * El `pedirAprobacion` de la sesión, convertido en la política de escritura del hijo.
+ *
+ * **Y aquí está la mitad buena del diseño: la política ya existía.** `pedirAprobacion` es el
+ * hueco que `abrirSesionReal` declara y que cada piel rellena, y sus implementaciones son
+ * exactamente las dos que hacían falta:
+ * - **La interactiva** (`consolaWeb.aprobacionesTui`, el modal de la TUI, `pedirDecisiones`
+ *   por readline): enseña el diff y espera. Nace RECHAZADA entera, tiene plazo, y sin
+ *   cliente enganchado contesta rechazo sin preguntar. Fail-closed por construcción, ya
+ *   probado, ya cableado en las tres pieles.
+ * - **La autónoma** (`consolaDeTarea.aprobacionesTui`): concede —la autorización fue crear
+ *   la tarea—, lo ANUNCIA con los nombres en el transcript y lo mete en `Tarea.autorizadas`
+ *   por su callback `autorizado`. O sea que la escritura de un agente externo dentro de una
+ *   tarea de fondo no puede ser muda ni quedarse fuera de la cuenta que lee el juez.
+ * Escribir un segundo tipo de política habría sido escribir una segunda forma de decidir
+ * sobre lo mismo, con dos sitios donde el fail-closed puede dejar de estarlo.
+ *
+ * Lo que esto añade es la TRADUCCIÓN, y nada más: un `PendienteDeAprobacion` sintético por
+ * escritura, con su ruta virtual y su diff, por los mismos dos mapas que ya viajan
+ * (`ficheros`, `diffs`).
+ * El id lleva el prefijo `externo:` para que no pueda colisionar con el de un interrupt del
+ * grafo — de esas claves se construye el `resume`, y una colisión resolvería el interrupt
+ * equivocado.
+ *
+ * **Fail-closed hasta el final**: si la promesa revienta, o si el mapa no trae `approve`
+ * para nuestro id, la respuesta es NO. Nunca se deja salir la excepción hacia el SDK, cuyo
+ * comportamiento ante un `canUseTool` que lanza no está medido.
+ */
+export declare function politicaDeAprobacionExterna(pedirAprobacion: (pendientes: PendienteDeAprobacion[], ficheros: Map<string, string>, diffs: Map<string, LineaDeDiff[]>) => Promise<Map<string, Decision>>, modo?: ModoDeLaSesion): PoliticaDeEscrituraExterna;
+/**
+ * Una escritura que un motor externo PROPONE, antes de pasar por ninguna guarda.
+ *
+ * La ruta llega `unknown` a propósito: viene de fuera, y quien decide si es una ruta es
+ * `veredictoDeRuta` y no quien la lee.
+ */
+export interface EscrituraPropuesta {
+    ruta: unknown;
+    lineas: LineaDeDiff[];
+}
+export type VeredictoDeEscrituras = {
+    admitidas: true;
+    escrituras: EscrituraExternaPedida[];
+} | {
+    admitidas: false;
+    motivo: string;
+};
+/**
+ * Las guardas de ruta sobre una tanda de escrituras propuestas, sea cual sea el motor.
+ *
+ * **Vive aquí, en UN sitio, y los dos motores externos que escriben por petición la llaman.**
+ * Cada uno traduce lo suyo —Codex sus `changes` con `kind` y `diff`, OpenCode el `toolCall`
+ * de ACP con su `oldText`/`newText`— y a partir de ahí el camino es el mismo. Escribir este
+ * bucle una vez por motor sería un segundo (y un tercer) sitio donde el fail-closed puede
+ * dejar de estarlo, que es la única forma en la que estas guardas se han roto nunca.
+ *
+ * **Una sola ruta mala tumba la tanda entera.** Es la dirección conservadora, y además la
+ * única que los dos protocolos saben expresar: los dos contestan una petición con UNA
+ * decisión, así que «las que pasen sí» no se puede decir.
+ */
+export declare function veredictoDeEscriturasExternas(opciones: {
+    cwd: string;
+    agente: string;
+    propuestas: readonly EscrituraPropuesta[];
+    ficheros: ReadonlySet<string>;
+    real?: (ruta: string) => string;
+}): VeredictoDeEscrituras;
+/**
+ * La decisión entera de una tanda: guardas de ruta y DESPUÉS la política.
+ *
+ * **Vive extraída y no en el cierre de cada adaptador**, que es donde este repo ha visto
+ * fallar esta arquitectura nueve veces: una composición de producción dentro de algo que
+ * todos los tests doblan. Con los adaptadores externos sería literal, porque los tests no
+ * lanzan sus binarios.
+ *
+ * Fail-closed en los cuatro caminos: sin política, con una ruta rechazada, si la política
+ * revienta, o si contesta que no. Y el orden importa: preguntar por algo cuyo único final
+ * posible es un rechazo es sacar un modal inútil — la misma regla que el `when` de
+ * `seDetieneEn` en `agent/grafo/perfiles.ts`.
+ */
+export declare function decisionDeEscrituraExterna(opciones: {
+    cwd: string;
+    agente: string;
+    propuestas: readonly EscrituraPropuesta[];
+    ficheros: ReadonlySet<string>;
+    real?: (ruta: string) => string;
+    /** Ausente = nadie autoriza en esta sesión, y «nadie a quien preguntar» nunca es «sí». */
+    aprobar?: PoliticaDeEscrituraExterna;
+}): Promise<{
+    concedida: boolean;
+    motivo?: string;
+}>;
+/**
+ * El diff de una escritura del hijo, con la MISMA función que compone el de una aprobación
+ * del grafo (`interrupts.ts#cambioDe`).
+ *
+ * La traducción es solo el NOMBRE de la tool: las claves de los argumentos coinciden —
+ * medido en `sdk-tools.d.ts`—, así que `Write` es un `write_file` y `Edit` un `edit_file`.
+ * Compartir la función en vez de escribir un segundo diff es lo que impide que la ventana de
+ * aprobación de un agente externo enseñe algo distinto de la de siempre.
+ *
+ * Un matiz declarado: `Edit` sin `replace_all` cambia UNA aparición y falla si hay varias,
+ * mientras que `cambioDe` pinta el reemplazo de todas. Cuando la edición es válida para el
+ * hijo hay exactamente una, así que coinciden; cuando no lo es, el diff enseña de más y la
+ * escritura no llega a ocurrir.
+ */
+export declare function diffDeEscrituraExterna(tool: string, entrada: Record<string, unknown>, rutaVirtual: string, leer?: (ruta: string) => string): LineaDeDiff[];
+/**
+ * La política de la SESIÓN, derivada de su `pedirAprobacion`. **Extraída y exportada a
+ * propósito**: es el cableado, y el cableado es donde este repo lleva SIETE reglas que se
+ * quedaron sin montar con todo en verde. Vive fuera del cierre de `abrirSesionReal` para
+ * poder probarla contra lo real en vez de contra un doble.
+ *
+ * Ausente es «no hay a quién preguntar», y entonces no hay política — o sea que el hijo no
+ * escribe. Es el caso de `xonecode run` en CI y de cualquier sesión montada sin aprobación:
+ * el mismo camino por el que hoy el turno dice «piden aprobación y no hay quién apruebe».
+ */
+export declare function politicaExternaDeSesion(pedirAprobacion: ((pendientes: PendienteDeAprobacion[], ficheros: Map<string, string>, diffs: Map<string, LineaDeDiff[]>) => Promise<Map<string, Decision>>) | undefined, modo?: ModoDeLaSesion): PoliticaDeEscrituraExterna | undefined;
+export declare function eventoDeToolExterna(nombre: string, entrada: Record<string, unknown>, cwd: string, real?: (ruta: string) => string): {
+    nombre: string;
+    detalle?: string;
+};
+/**
+ * Todo lo que un agente externo necesita de la SESIÓN, en un solo sitio y exportado.
+ *
+ * **Está extraída del cierre de `abrirSesionReal` a propósito**, y no por gusto: son cuatro
+ * campos opcionales que se componen dentro de algo que todos sus tests doblan, o sea el
+ * patrón de fallo que este repo lleva medido siete veces — una regla que deja de estar
+ * montada CON TODO EN VERDE. Aquí los tres que importan se pueden comprobar contra lo real:
+ * que sin `pedirAprobacion` no hay política (y por tanto no hay escritura), que la actividad
+ * del hijo acaba en la cola de eventos, y que la lista de ficheros es una FUNCIÓN y no una
+ * foto congelada al abrir la sesión.
+ */
+export declare function opcionesDeSubagenteExterno(opciones: {
+    pedirAprobacion?: (pendientes: PendienteDeAprobacion[], ficheros: Map<string, string>, diffs: Map<string, LineaDeDiff[]>) => Promise<Map<string, Decision>>;
+    ficherosDelProyecto: () => ReadonlySet<string>;
+    eventos: ColaDeEventos;
+    /** Lo que el hijo consumió, para la cuenta de la sesión. Ausente = no se lleva la cuenta. */
+    alConsumir?: (consumo: ConsumoExterno) => void;
+    /**
+     * El modo de escritura de la sesión. Ausente = supervisado, o sea que cada escritura del
+     * hijo se pregunta, que es lo que hacía antes de que el modo existiera.
+     */
+    modo?: ModoDeLaSesion;
+}): {
+    aprobarEscritura?: PoliticaDeEscrituraExterna;
+    ficherosDelProyecto: () => ReadonlySet<string>;
+    alUsarTool: (tool: ToolDeUnHijo) => void;
+    alRazonar: (texto: string) => void;
+    alConsumir?: (consumo: ConsumoExterno) => void;
+};
+/** Cuántos ficheros se le enumeran. Por encima, se dice cuántos quedan fuera. */
+export declare const TOPE_DE_INVENTARIO = 400;
+/**
+ * El inventario del proyecto, para un agente EXTERNO.
+ *
+ * **Existe porque un hijo de Claude Code no puede enumerar la carpeta, y eso está medido**
+ * (11-09-2026, espiando el hook en una ejecución real). Intentó `Bash ls`, `Bash find` —
+ * denegadas—, pidió `ToolSearch {"query":"select:Glob,Grep"}` y **no las encontró**: ese
+ * hijo no trae ninguna herramienta de listado. Después probó las tools MCP del usuario
+ * (denegadas también) y acabó leyendo a ciegas nombres inventados —`README.md`,
+ * `CLAUDE.md`, `app.ini`, `main.xml`…, ninguno existía— para concluir que «el proyecto está
+ * prácticamente vacío para mí, porque no puedo listarlo».
+ *
+ * La salida fácil habría sido concederle `Bash`, y es justo la que no se puede tomar: con
+ * `Bash` escribe el proyecto entero saltándose la política, el diff y las guardas de ruta.
+ * La buena es que el harness YA sabe qué ficheros hay —es la misma lista con la que
+ * reconoce una vista aplanada— así que se le DICE. Es el patrón de `core/adjuntos.ts`:
+ * montar no basta, hay que decir que están.
+ *
+ * Dos cosas que hereda de las reglas de siempre: las rutas van VIRTUALES (desde la raíz del
+ * proyecto, nunca las de la máquina) y la lista va ACOTADA con el total al lado, que es lo
+ * que impide leer los que caben como si fueran todos.
+ */
+export declare function inventarioDelProyecto(ficheros: ReadonlySet<string>, tope?: number): string;

package/dist/agent/subagentes/pluginDeSkills.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Las skills de xonecode, servidas a un hijo de **Claude Code** como un PLUGIN LOCAL.
+ *
+ * **La palanca es `plugins`, y eso se midió — `additionalDirectories` NO vale.** El primer
+ * intento fue montar una carpeta con la disposición `<dir>/.claude/skills/` y pasarla por
+ * `additionalDirectories`, porque su documentación dice que añadir un directorio recarga
+ * «CLAUDE.md, skills, and plugins». Probado contra un hijo de verdad, preguntándole qué
+ * skills tenía: listó las del usuario y las de sus plugins, y **ninguna de las dos del
+ * montaje**. Con `plugins: [{type:"local", path}]` y un `plugin.json` que apunta su `skills`
+ * a una carpeta, las mismas dos aparecen como `xonecode:xone-review` y
+ * `xonecode:xone-debugging`. Esa diferencia es todo el motivo de este fichero.
+ *
+ * **Y por eso no se escribe nada dentro del proyecto.** La otra forma de que Claude Code las
+ * encuentre sería un `.claude/skills/` en la carpeta del proyecto, y ahí no se puede: el
+ * proyecto es la app del cliente, se sincroniza con CloudStudio y entra en el commit de cada
+ * turno, así que nuestro andamiaje acabaría subido a Studio. Esta carpeta es NUESTRA
+ * (`~/.xonecode/motores/claude`) y el hijo la recibe por argumento.
+ *
+ * **Enlaces y no copias**: las de serie pesan megas —una sola son 77 ficheros— y esto se
+ * monta en cada arranque de un subagente externo.
+ *
+ * **Y el hijo puede LEER la carpeta entera de cada skill montada, no solo su `SKILL.md`**
+ * (`carpetasDeLecturaDeSkills`, sumadas a las lecturas de `veredictoDeLectura`). Antes se negaba, a
+ * propósito, y el precio resultó demasiado alto: medido en una tarea de Maset (15-10-2026), el
+ * developer y el consultor en Claude Code no pudieron leer `references/xml-ui/…` y escribieron
+ * atributos de XOne a ciegas —`img=` en un `type="IMG"`, donde la documentación dice `path=`—; el
+ * consultor lo dijo: «mi sandbox bloquea Read fuera del proyecto… No puedo confirmar si es `img` o
+ * `path`». No se abre «una carpeta de fuera por comodidad»: se abren SOLO las carpetas de las skills
+ * que este mismo montaje sirve, una a una, en LECTURA, comprobadas por texto y por camino real
+ * (`dentroDeUnaLectura`). La casa, `.xonecode/` y el resto de la máquina siguen cerrados.
+ *
+ * **Segundo límite**: el nombre le llega PREFIJADO (`xonecode:<nombre>`), que es como Claude
+ * Code nombra lo que viene de un plugin, mientras que el `.md` de un subagente y
+ * `promptDeAgente` lo nombran a secas. No se reescribe el prompt para igualarlo: el prefijo
+ * lo pone el motor y adivinarlo aquí sería atarse a su formato.
+ */
+/** El nombre del plugin. Sale en el nombre de cada skill (`xonecode:<nombre>`), así que
+ *  vive en una constante: es dato del producto, no una cadena suelta. */
+export declare const NOMBRE_DEL_PLUGIN = "xonecode";
+/** La carpeta que gobernamos para este motor. Fuera del proyecto, a propósito. */
+export declare function carpetaDelPluginDeSkills(casa?: string): string;
+/**
+ * El manifiesto, PURO y por eso comprobable sin disco.
+ *
+ * `skills` apunta a una subcarpeta relativa y no a la raíz del paquete: la carpeta de
+ * montaje FUNDE las tres raíces (serie, global y proyecto) con la precedencia de
+ * `cargarSkills`, y una ruta suelta solo podría apuntar a una de ellas.
+ */
+export declare function manifiestoDelPluginDeSkills(): string;
+/**
+ * Deja la carpeta del plugin lista y devuelve su ruta — o AUSENTE si no hay ninguna skill
+ * que servir, o si no se pudo montar.
+ *
+ * **Ausente no tumba el turno.** Esto cuelga del arranque de un subagente: un fallo al
+ * escribir en la casa del usuario no puede llevarse por delante el trabajo, así que el hijo
+ * arranca sin plugin y con las suyas, que es como estaba antes.
+ *
+ * **La carpeta de skills se RECREA entera** en cada montaje. Dentro solo hay enlaces que
+ * pusimos nosotros, así que borrarla es seguro; y sin borrarla, una skill que el usuario
+ * quitó del disco seguiría anunciada por un enlace roto — el ajuste viejo que sobrevive a su
+ * dueño, que es el fallo que este repo persigue en todas partes.
+ */
+export declare function montarPluginDeSkills(opciones?: {
+    casa?: string;
+    raiz?: string;
+}): string | undefined;
+/**
+ * Las skills que el hijo de Claude Code puede VER y usar (la opción `skills` del SDK): las de su `.md`, con el nombre que
+ * les da el plugin (`xonecode:<nombre>`). Sin plugin montado, ninguna. Omitir la opción «no es skills off» (su propia
+ * documentación): el hijo veía TODAS las que descubre, también las del usuario en `~/.claude` y las de sus plugins.
+ * Es un filtro de contexto, no un candado: los ficheros de las demás siguen en el disco, y leerlos lo niega
+ * `veredictoDeLectura` (fuera del proyecto y de las carpetas de las skills montadas).
+ */
+export declare function skillsVisiblesDelHijo(skills: readonly string[] | undefined, conPlugin: boolean): string[];
+/**
+ * Las carpetas que un hijo de Claude Code puede LEER de las skills montadas: de cada una, su enlace dentro del plugin
+ * (`<plugin>/skills/<nombre>`, que es la ruta que el motor le enseña) y su carpeta REAL. Las dos hacen falta:
+ * `dentroDeUnaLectura` compara el texto de la ruta Y su camino real, y el plugin usa ENLACES, así que una lectura por el
+ * enlace tiene el texto bajo el plugin y el camino real bajo la skill. Solo las que están en disco.
+ */
+export declare function carpetasDeLecturaDeSkills(opciones?: {
+    casa?: string;
+    raiz?: string;
+}): string[];

package/dist/agent/subagentes/subagenteCodex.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Codex como subagente: un turno contra `codex app-server --stdio`.
+ *
+ * **Todo lo que hay aquí está MEDIDO contra el binario real (0.152.1), no deducido de una
+ * documentación.** El encuadre es JSON por línea sin campo `jsonrpc`; `initialize` contesta
+ * con el `userAgent` y el `codexHome`; `thread/start` acepta `{cwd, ephemeral, approvalPolicy,
+ * sandbox}` y devuelve `{thread:{id}}`; `turn/start` toma
+ * `{threadId, input:[{type:"text", text, text_elements:[]}]}`; y la respuesta final llega en
+ * un `item/completed` cuyo `item.type` es `agentMessage` con `phase: "final_answer"`. Los
+ * valores de sandbox son exactamente tres, y los enumeró el propio servidor al rechazar uno
+ * mal escrito: `read-only`, `workspace-write` y `danger-full-access`.
+ *
+ * **Se usa el `codex` del PATH, no un paquete npm.** El harness de deepseek se trae
+ * `@openai/codex` para no depender del PATH; aquí se prefiere el que el usuario ya tiene
+ * instalado y autenticado, porque ese paquete son ~100 MB de binario por plataforma y
+ * traerlo obligaría a todo el mundo a bajarlo para una capacidad opcional. `CODEX_BIN`
+ * permite apuntar a otro.
+ *
+ * **El sandbox es `read-only` SIEMPRE, y lo que abre la escritura es el `approvalPolicy`.**
+ * Esa es la decisión central y está medida (11-09-2026, tres ejecuciones): con
+ * `sandbox: "workspace-write"` las escrituras dentro del cwd ocurren solas y no vuelven a
+ * xonecode, o sea que ninguna de sus guardas de ruta las vería. Con `read-only` la caja del
+ * sistema operativo sigue siendo la denegación —no depende de que el modelo colabore— y
+ * `approvalPolicy: "on-request"` convierte cada escritura en una PETICIÓN que contestamos
+ * nosotros: el mismo papel que el `ask` del hook `PreToolUse` en Claude Code. Medido:
+ * contestando `accept` el fichero se escribe, y contestando `decline` no queda fichero, el
+ * item queda `declined` y el turno SIGUE, así que el agente puede contarlo. Sin escritura
+ * concedida se manda `never`, que evita que el hijo se quede esperando a alguien.
+ *
+ * **Lo que se decide y lo que se pregunta llegan en mensajes DISTINTOS.** La petición
+ * (`item/fileChange/requestApproval`) trae solo un `itemId`; los ficheros vinieron antes, en
+ * el `item/started` de ese id. De ahí el registro de items de aquí abajo: sin él no hay diff
+ * que enseñar, y sin diff no hay decisión que tomar. La traducción de esos cambios a lo que
+ * las pieles pintan, y las guardas de ruta reaplicadas, viven en `escrituraDeCodex.ts`.
+ *
+ * **Lo que no se sabe decir que no, se ABORTA.** Se contestan las peticiones cuyo «no» está
+ * en su esquema (`{decision:"decline"}` para fichero, comando y permisos;
+ * `{action:"decline"}` para una elicitación de MCP). `item/tool/requestUserInput` no tiene
+ * «no» —su respuesta es `{answers:{…}}` y nada más—, así que ahí se aborta, igual que ante
+ * cualquier petición que no esté nombrada. Lo que NUNCA se puede hacer es dejarla sin
+ * contestar: eso deja a codex bloqueado hasta que el tope lo mate.
+ *
+ * Y una consecuencia que hay que saber: el hijo es el Codex DEL USUARIO, con su
+ * configuración —sus MCP, sus plugins, sus hooks y sus skills—. Medido: al abrir el hilo
+ * arrancan los servidores MCP que tenga puestos. xonecode no los filtra ni los toca.
+ */
+import type { PeticionExterna, PoliticaDeEscrituraExterna, ToolDeUnHijo } from "../../core/ports.js";
+/**
+ * El binario. `CODEX_BIN` gana, para poder apuntar a una versión concreta o a un envoltorio. En
+ * Windows, el `codex.exe` nativo que lanzaría el `codex.js` del shim de npm
+ * (`ejecutableParaLanzar`): ni el `.cmd` ni `node` se pueden matar con el nieto dentro.
+ */
+export declare function binarioDeCodex(): string;
+/** ¿Está el binario? Se pregunta lanzándolo, que es la única respuesta que no miente. */
+export declare function codexDisponible(): Promise<boolean>;
+export declare function correrCodex(peticion: PeticionExterna, opciones?: {
+    /** Lo que el hilo lleva consumido. Se avisa al terminar, con el último total visto. */
+    alConsumir?: (consumo: {
+        entrada: number;
+        salida: number;
+        cache: number;
+    }) => void;
+    /** Quién autoriza cada escritura. Ausente = no se escribe ninguna, y se dice por qué. */
+    aprobar?: PoliticaDeEscrituraExterna;
+    /**
+     * Los del proyecto AHORA, para reconocer una vista aplanada. Es una FUNCIÓN y no una
+     * lista por lo mismo que en `crearSubagenteExterno`: el hijo escribe durante el turno.
+     */
+    ficheros?: () => ReadonlySet<string>;
+    /** El `realpath`, inyectado para poder probar la guarda sin tocar disco. */
+    real?: (ruta: string) => string;
+    /** Lo que hace MIENTRAS trabaja, como línea de actividad (`actividadDeCodex.ts`). */
+    alUsarTool?: (tool: ToolDeUnHijo) => void;
+    /** Lo que va CONTANDO: sus mensajes de fase `commentary`. */
+    alRazonar?: (texto: string) => void;
+}): Promise<string>;