Claude Tools Native Gateway

En una frase: convertir ChatGPT web en el único cerebro principal, que impulse una Session nativa real de Claude Code en la máquina local para completar lectura, modificación, verificación y recuperación controladas.

El repositorio público solo contiene código fuente y pruebas, no incluye claves locales, configuración de Tunnel ni el estado de sesión de state/.

Arquitectura

Gateway ahora tiene un único motor de ejecución: Native V2.

当前 ChatGPT Chat（唯一主脑）
  ↔ Claude Tools Native MCP（六个 Session 控制工具）
      ↔ 本地模型回合桥（127.0.0.1）
          ↔ 隔离的 Claude Code 原生 Session
              → 原生 Agent loop
              → 网关自有的受控工具 Executor

Gateway realiza por sí mismo la inicialización de MCP, el inventario de herramientas y la distribución de llamadas; ya no inicia ni actúa como proxy del servidor de herramientas claude mcp serve de V1. Solo después de crear una Session nativa se inicia el proceso de Claude Code exclusivo de esa Session.

La antigua Agent Session de V1, las herramientas de nivel superior Read/Edit/Write/Bash, las herramientas de tareas locales, la antigua delegación a DeepSeek y el ChatGPT Bridge se han eliminado del punto de entrada de ejecución y del árbol de código. Lo que se conserva son las infraestructuras comunes de nivel inferior que V2 aún necesita: escritura atómica de estado, protección de rutas de credenciales, verificación de identidad de procesos y reglas de sandbox de macOS. Los antiguos archivos de estado de V1 no se eliminan automáticamente, pero Native Gateway no los lee ni los ejecuta.

Plano de control MCP

La versión web solo ve seis herramientas:

• native_session_start

• native_session_continue

• native_session_recover

• native_session_reply_and_wait

• native_session_status

• native_session_stop

Cualquier nombre de herramienta de V1, herramienta de archivos de nivel superior, Bash, antigua herramienta de DeepSeek u otro método MCP se rechaza en el servidor, no solo se oculta de la lista de herramientas.

Capacidades de la Session de Claude Code

La Session tiene tres niveles claramente definidos que, una vez creados, no se pueden subir, bajar de nivel ni cambiar de directorio raíz:

• read_only: Read, FindFiles, SearchText y RunCommand de solo lectura; el alcance de lectura es todo el equipo, excepto las rutas de estado/credenciales protegidas y los permisos de macOS.

• direct_write: añade Edit, Write y NotebookEdit a la capacidad de lectura de todo el equipo, modificando únicamente los directorios reales que el usuario haya seleccionado explícitamente. Solo se debe elegir este nivel cuando el usuario pida explícitamente modificar archivos reales.

• worktree_write: el conjunto de herramientas es el mismo que direct_write, pero las modificaciones se realizan en un Git worktree independiente creado y conservado por Gateway; el checkout de origen no cambia.

Estas son herramientas lógicas que el modelo puede invocar dentro del bucle de agente nativo de Claude Code, pero el ejecutor pertenece a Gateway. Las herramientas de archivos integradas de Claude Code sin supervisión y Bash permanecen desactivadas para evitar eludir la autorización de acciones, los hashes, la recuperación y el libro de auditoría.

Lectura y búsqueda

• Read puede leer cualquier archivo UTF-8 normal no protegido del equipo; ya no está limitado al directorio de escritura.

• FindFiles puede hacer enumeración de archivos acotada desde cualquier directorio absoluto.

• SearchText solo hace coincidencia literal UTF-8; no acepta expresiones regulares ni globs.

• La búsqueda no sigue enlaces simbólicos y omite .git, rutas protegidas y enlaces duros externos.

• Los resultados de una sola búsqueda y el recibo completo de acciones están limitados a 64 KiB.

• Todos los niveles pueden inspeccionar diferentes discos y directorios; working_directory es solo la ubicación de búsqueda predeterminada, el CWD de comandos y el límite de escritura para los niveles de escritura. Los permisos TCC/archivos de macOS aún pueden denegar el acceso a Escritorio, Documentos u otras ubicaciones protegidas por el sistema.

Modificación de archivos y Notebooks

• En direct_write, Edit, Write y NotebookEdit modifican el directorio real vinculado a la Session; en worktree_write solo modifican el worktree gestionado.

• Write puede crear directorios padre faltantes bajo demanda dentro del directorio raíz autorizado y luego crear atómicamente el archivo de destino; no puede cruzar el directorio raíz, enlaces simbólicos, .git ni rutas protegidas.

• NotebookEdit admite reemplazar, insertar y eliminar celdas por ID de celda, pero no ejecuta el Notebook.

• Cada acción de escritura guarda el SHA-256 antes y después de escribir, y utiliza preparación, CAS, escritura atómica en disco y recibo persistente.

• Tras un fallo del proceso se verifica el estado real de los archivos; si no se puede determinar, se detiene la recuperación y no se repite la escritura a ciegas.

• direct_write no tiene herramienta de eliminación de archivos y no escribe archivos por comandos de verificación de solo lectura; aún puede sobrescribir o modificar archivos de destino según las instrucciones explícitas del usuario.

• En worktree_write, los archivos, HEAD, tree, index y el estado del área de trabajo del checkout de origen permanecen sin cambios; el directorio común de Git registra el worktree conservado.

Comandos de verificación

RunCommand acepta comandos del sistema instalados y ejecutables dentro del directorio de la Session; ya no mantiene una lista blanca estática de comandos que dañe fácilmente las herramientas de desarrollo normales. Los argumentos se siguen pasando como argv exacto; Gateway no los ensambla automáticamente en una cadena de shell:

• El sistema de archivos raíz de la Session es de solo lectura desde la perspectiva del comando;

• La red, las señales de proceso, Keychain/XPC y los CLI de modelos están bloqueados por el Seatbelt de macOS;

• sudo, eliminación/movimiento directo, control del sistema, find -delete/-exec, rg --pre, CLI de modelos y otras entradas siguen rechazadas explícitamente;

• Los enlaces simbólicos, enlaces duros o la cantidad de archivos en proyectos normales ya no provocan el rechazo de todo el repositorio antes de iniciar el comando; al acceder realmente, lo limitan Seatbelt, las rutas protegidas y los permisos de macOS;

• La salida, el tiempo de ejecución y la recuperación del grupo de procesos hijo tienen límites;

• El resultado entra primero en el mismo libro de acciones y luego se entrega a la siguiente ronda de GPT.

Se utiliza para la verificación de repositorios de confianza, no es un contenedor contra procesos maliciosos de la misma cuenta de macOS. Durante la ejecución de la Session, no uses otros editores o procesos para modificar concurrentemente el worktree gestionado.

Modelo principal, búsqueda web y DeepSeek

La ruta principal está fijada en chatgpt-main; no acepta parámetros de model, provider, endpoint, API key ni fallback. Cuando la ronda actual de ChatGPT se detiene, Claude Code se queda en waiting_for_gpt; no cambia por su cuenta a Claude, DeepSeek o Codex para seguir pensando.

La búsqueda web la sigue realizando ChatGPT web. WebSearch/WebFetch de Claude Code no están habilitados, por lo que no habrá conflictos entre la búsqueda de GPT y la búsqueda propia de Claude, ni pérdida de control de las fuentes.

El subagent_policy: "none" predeterminado no crea DeepSeek. Solo cuando worktree_write elige explícitamente deepseek_explicit, GPT puede usarlo en el bucle principal:

• deepseek_subagent_start

• deepseek_subagent_get

• deepseek_subagent_stop

La delegación debe entrar primero en el libro de acciones persistente de la Session principal y solo después se permite la sub-Session aislada. Durante la subtarea, la Session principal no puede ejecutar concurrentemente Edit, Write, NotebookEdit, RunCommand ni iniciar una segunda subtarea. La ruta está fijada en Sonnet/Opus → Flash, Fable → Pro; un fallo no retrocede a Claude, Codex, OpenAI ni a otro nivel de DeepSeek.

Contexto de Skills

native_session_start puede recibir hasta ocho skill_contexts seleccionados explícitamente por ChatGPT. No son el runtime de Skills nativo de Claude Code:

• Solo se extrae y congela el cuerpo de instrucciones validado;

• No se cargan scripts, recursos, plugins, Hooks, Slash Commands ni herramientas adicionales;

• Cada elemento permitido fija simultáneamente el ID de skill y el SHA-256 del SKILL.md completo normalizado;

• El primer inicio y los resume posteriores usan la misma instantánea persistente;

• El cuerpo completo solo aparece en el estado privado 0600 y en el contexto de modelo necesario para el GPT actual.

Ejemplo de lista permitida:

CLAUDE_TOOLS_NATIVE_SKILL_ALLOWLIST_JSON='[{"skill_id":"personal:review","content_sha256":"<64位小写SHA-256>"}]' \
npm start

El hash se calcula sobre el texto completo después de eliminar el BOM UTF-8 y normalizar CRLF/CR a LF.

Aislamiento y recuperación

• Cada Session usa un HOME independiente, directorio de configuración de Claude, directorio de ejecución y grupo de procesos.

• Claude Code usa --bare, fuentes de configuración vacías, configuración MCP estricta y un conjunto de herramientas preciso.

• El proceso principal de Claude solo puede acceder al puerto de bucle local exacto del Broker/Executor.

• Los directorios de credenciales, el estado de Gateway, .git, los enlaces simbólicos y los enlaces duros externos fallan en modo cerrado (fail closed); el acceso a rutas normales del sistema/usuario lo determinan conjuntamente la raíz de la Session, TCC de macOS y los permisos de archivos.

• Las respuestas de ChatGPT y cada acción autorizada se escriben atómicamente en disco antes de liberarse al proceso en ejecución.

• La expiración del arrendamiento detiene el Runner y deja un estado inspeccionable.

• El reinicio de Gateway no mata a los Runners que aún pertenecen a una Session; native_session_recover verifica la propiedad, rota el arrendamiento y continúa con la misma Session de Claude Code.

• Si el Runner ya no existe, no se finge la recuperación ni se repiten acciones ya completadas.

Claude Code 2.1.247 no tiene un interruptor independiente verificado de "habilitar solo Hooks mientras se sigue desactivando keychain, plugins y memoria automática", por lo que los Hooks nativos, Skills/Slash nativos, Agent, Workflow, Web y MCP de terceros no supervisados por el libro de acciones permanecen desactivados.

Ejecución

npm start

Native Gateway ya no necesita los interruptores CLAUDE_TOOLS_NATIVE_V2 ni CLAUDE_TOOLS_NATIVE_V2_ONLY; Native-only es el único modo de ejecución.

El estado se guarda por defecto en state/ y se puede cambiar con la variable de entorno de ruta absoluta CLAUDE_TOOLS_STATE_DIR. La ruta predeterminada de Claude Code es $HOME/.npm-global/bin/claude y se puede sobrescribir con CLAUDE_BIN.

El Tunnel/Connector de larga ejecución necesita reiniciarse tras actualizar el código fuente. ChatGPT puede almacenar en caché el schema de las herramientas conectadas; si una sesión nueva no ve los seis native_session_*, actualiza o reconecta el Claude Tools Connector.

Verificación

npm test
npm run test:native:installed
npm run test:native:installed:write
npm run test:native:installed:direct-write
npm run test:native:installed:deepseek
npm run test:native:installed:skills

Las pruebas automáticas cubren:

• Inicialización MCP directa solo-Native, exactamente seis herramientas, rechazo de herramientas V1 y métodos desconocidos;

• Libro de rondas y acciones, idempotencia de respuestas, arrendamiento, propiedad de procesos, detención y recuperación;

• Lectura de todo el equipo con Read/FindFiles/SearchText, rutas protegidas, tamaño, orden, coincidencia literal y límites de condiciones de carrera;

• Escritura directa en directorio real con Edit/Write/NotebookEdit, aislamiento de worktree, CAS, hashes y recuperación tras fallo;

• Entrada flexible de comandos de desarrollo con RunCommand, ejecutables locales de la Session, sistema de archivos de solo lectura, cero red, bloqueo de servicios sensibles y recuperación por tiempo de espera;

• Fijación de ID/hash del cuerpo de Skills, consistencia entre start/resume y límites del estado privado;

• Barrera de inicio de la delegación explícita a DeepSeek, bloqueo de escritura de tarea única, verificación de ruta, recuperación tras reinicio de Gateway y detención;

• El MCP/Session/history público no filtra IDs de autorización, tokens de Runner, PIDs, rutas internas ni credenciales de modelos.

Las pruebas instaladas usan Claude Code 2.1.247 local y un script GPT en localhost, sin conectarse a modelos reales:

• test:native:installed: ejecuta FindFiles → SearchText literal → Read → final con / como raíz de solo lectura, y recuperación del mismo Runner/Session de Claude tras desconexión de Gateway.

• test:native:installed:write: Read → Edit → Write → NotebookEdit → RunCommand → resume → Read.

• test:native:installed:direct-write: el mismo conjunto de rondas reales de Claude Code modifica directamente el directorio real en el fixture de prueba, luego resume y verifica los resultados persistentes.

• test:native:installed:deepseek: usa un CLI falso de DeepSeek local para verificar delegación explícita, verificación de resultados, bloqueo de escritura activo, recuperación tras reinicio y detención.

• test:native:installed:skills: verifica que dos Skills de solo instrucciones con hash fijo usan la misma instantánea en start/resume.

Estas pruebas de script local no consumen cuota de modelos reales de ChatGPT, Claude ni DeepSeek. La prueba mínima de humo con DeepSeek real aún requiere autorización separada del usuario.