Claude Tools Native Gateway

Одной фразой: превратить веб-версию ChatGPT в единственный главный мозг, который управляет реальными нативными сессиями Claude Code на локальной машине для контролируемого чтения, изменения, проверки и восстановления.

Публичный репозиторий содержит только исходный код и тесты, без локальных ключей, конфигурации Tunnel или состояния сессий в state/.

Архитектура

У Gateway теперь только один движок исполнения — Native V2:

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

Gateway сам выполняет инициализацию MCP, список инструментов и диспетчеризацию вызовов, больше не запуская и не проксируя инструмент-сервер claude mcp serve из V1. Только после создания Native Session запускается процесс Claude Code, принадлежащий этой сессии.

Прежние V1 Agent Session, верхнеуровневые Read/Edit/Write/Bash, локальные инструменты задач, старая делегация DeepSeek и ChatGPT Bridge удалены из точки входа и дерева кода. Сохранены только общие низкоуровневые механизмы, которые по-прежнему нужны V2: атомарная запись состояния, защита путей к учётным данным, проверка подлинности процесса и правила песочницы macOS. Старые файлы состояния V1 не удаляются автоматически, но Native Gateway их не читает и не исполняет.

Плоскость управления MCP

Веб-версия видит только шесть инструментов:

• native_session_start

• native_session_continue

• native_session_recover

• native_session_reply_and_wait

• native_session_status

• native_session_stop

Любые имена инструментов V1, верхнеуровневые файловые инструменты, Bash, старые инструменты DeepSeek или другие методы MCP отклоняются на стороне сервера, а не просто скрываются из списка инструментов.

Возможности сессии Claude Code

У сессии есть три чётких уровня, которые нельзя повысить/понизить или сменить корневой каталог после создания:

• read_only: Read, FindFiles, SearchText и read-only RunCommand; область чтения — весь компьютер, за исключением защищённых путей состояния/учётных данных и разрешений macOS.

• direct_write: добавляет Edit, Write, NotebookEdit к чтению по всему компьютеру, изменяя только реальные каталоги, явно выбранные пользователем. Этот уровень следует выбирать только тогда, когда пользователь явно просит изменить реальные файлы.

• worktree_write: набор инструментов тот же, что и у direct_write, но изменения вносятся в отдельный Git worktree, созданный и сохраняемый Gateway; исходный checkout не меняется.

Это логические инструменты, которые модель может вызывать в нативном цикле агента Claude Code, но исполнитель принадлежит Gateway. Неуправляемые встроенные файловые инструменты и Bash Claude Code по-прежнему отключены, чтобы не обойти авторизацию действий, хеширование, восстановление и реестр аудита.

Чтение и поиск

• Read может читать любой незащищённый обычный UTF-8 файл на компьютере, больше не ограничен каталогом записи.

• FindFiles выполняет ограниченное перечисление файлов из любого абсолютного каталога.

• SearchText выполняет только буквальное сопоставление UTF-8, без регулярных выражений и glob.

• Поиск не следует по символическим ссылкам, пропускает .git, защищённые пути и внешние жёсткие ссылки.

• Результаты одного поиска и полные квитанции действий ограничены 64 КиБ.

• Все уровни могут проверять разные диски и каталоги; working_directory — это лишь место поиска по умолчанию, CWD команд и граница записи для уровней записи. Разрешения macOS TCC/файловые разрешения всё ещё могут отклонять доступ к Desktop, Documents и другим системно защищённым местам.

Изменение файлов и Notebook

• В direct_write Edit, Write и NotebookEdit изменяют реальный каталог, привязанный к сессии; в worktree_write — только управляемый worktree.

• Write может по мере необходимости создавать недостающие родительские каталоги внутри авторизованного корневого каталога, а затем атомарно создавать целевой файл; это не позволяет выйти за пределы корневого каталога, символических ссылок, .git или защищённых путей.

• NotebookEdit поддерживает замену, вставку и удаление ячеек по cell ID, но не исполняет Notebook.

• Каждое действие записи сохраняет SHA-256 до и после записи и использует подготовку, CAS, атомарную запись на диск и постоянную квитанцию.

• После сбоя процесса сверяется реальное состояние файла; если определить его нельзя, восстановление останавливается, без слепого повторения записи.

• В direct_write нет инструмента удаления файлов, и команды проверки только для чтения не записывают файлы; он всё же может перезаписывать или изменять целевые файлы по явной инструкции пользователя.

• В worktree_write файлы, HEAD, tree, index и состояние рабочей области исходного checkout остаются неизменными; общий каталог Git регистрирует сохраняемый worktree.

Команды проверки

RunCommand принимает установленные системные команды и исполняемые файлы внутри каталога сессии, больше не поддерживая статический белый список команд, который легко задевает обычные инструменты разработки. Аргументы по-прежнему передаются точным argv, Gateway не собирает их автоматически в строку shell:

• корневая файловая система сессии с точки зрения команды доступна только для чтения;

• сеть, сигналы процессов, Keychain/XPC и CLI моделей блокируются Seatbelt macOS;

• sudo, прямое удаление/перемещение, системное управление, find -delete/-exec, rg --pre, CLI моделей и другие точки входа по-прежнему явно отклоняются;

• символические ссылки, жёсткие ссылки или количество файлов в обычном проекте больше не приводят к отклонению всего репозитория до запуска команды; при реальном доступе действуют Seatbelt, защищённые пути и разрешения macOS;

• вывод, время выполнения и сбор дочерних групп процессов ограничены;

• результат сначала попадает в тот же реестр действий, затем передаётся следующему ходу GPT.

Он предназначен для проверки доверенных репозиториев, а не как контейнер против вредоносных процессов того же аккаунта macOS. Во время работы сессии не изменяйте управляемый worktree параллельно из других редакторов или процессов.

Основная модель, веб-поиск и DeepSeek

Основной маршрут жёстко задан как chatgpt-main, параметры model, provider, endpoint, API key или fallback не принимаются. Когда текущий ход ChatGPT останавливается, Claude Code останавливается в состоянии waiting_for_gpt; он не переключается самовольно на Claude, DeepSeek или Codex для продолжения размышлений.

Веб-поиск по-прежнему выполняет веб-версия ChatGPT. WebSearch/WebFetch Claude Code не открыты, поэтому не возникает конфликтов между поиском GPT и собственным поиском Claude или потери контроля над источниками.

По умолчанию subagent_policy: "none", DeepSeek не создаётся. Только когда worktree_write явно выбирает deepseek_explicit, GPT может использовать в основном цикле:

• deepseek_subagent_start

• deepseek_subagent_get

• deepseek_subagent_stop

Делегация сначала должна попасть в постоянный реестр действий основной сессии, и только затем разрешается изолированная подсессия. Во время подзадачи основная сессия не может параллельно выполнять Edit, Write, NotebookEdit, RunCommand или запускать вторую подзадачу. Маршрут жёстко задан: Sonnet/Opus → Flash, Fable → Pro; при сбое нет отката на Claude, Codex, OpenAI или другой уровень DeepSeek.

Контекст навыков

native_session_start может принимать до восьми skill_contexts, явно выбранных ChatGPT. Это не нативная среда выполнения навыков Claude Code:

• извлекается и замораживается только проверенное тело инструкций;

• не загружаются скрипты, ресурсы, плагины, Hook, Slash Command или дополнительные инструменты;

• для каждого разрешённого элемента фиксируются одновременно skill ID и SHA-256 нормализованного полного SKILL.md;

• первый запуск и последующий resume используют один и тот же постоянный снимок;

• полный текст появляется только в приватном состоянии 0600 и в контексте модели, необходимом текущему GPT.

Пример разрешённого списка:

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

Хеш вычисляется по полному тексту после удаления UTF-8 BOM и приведения CRLF/CR к LF.

Изоляция и восстановление

• Каждая сессия использует отдельные HOME, каталог конфигурации Claude, рабочий каталог и группу процессов.

• Claude Code запускается с --bare, пустыми источниками настроек, строгой конфигурацией MCP и точным набором инструментов.

• Основной процесс Claude может обращаться только к точному локальному loopback-порту Broker/Executor.

• Каталоги учётных данных, состояние Gateway, .git, символические ссылки и внешние жёсткие ссылки закрыты по принципу fail closed; доступность обычных системных/пользовательских путей определяется корнем сессии, TCC macOS и файловыми разрешениями.

• Ответ ChatGPT и каждое разрешённое действие сначала атомарно записываются на диск, затем передаются работающему процессу.

• Истечение аренды останавливает Runner и оставляет проверяемое состояние.

• Перезапуск Gateway не убивает Runner, всё ещё принадлежащий сессии; native_session_recover проверяет право владения, ротирует аренду и продолжает ту же сессию Claude Code.

• Если Runner уже не существует, восстановление не имитируется и завершённые действия не повторяются.

В Claude Code 2.1.247 нет проверенного отдельного переключателя «включить только Hooks, продолжая отключать keychain, плагины и автоматическую память», поэтому нативные Hooks, нативные Skill/Slash, Agent, Workflow, Web и сторонние MCP без надзора реестра действий остаются отключёнными.

Запуск

npm start

Native Gateway больше не требует переключателей CLAUDE_TOOLS_NATIVE_V2 или CLAUDE_TOOLS_NATIVE_V2_ONLY; Native-only — единственный режим работы.

Состояние по умолчанию сохраняется в state/, его можно изменить через переменную окружения с абсолютным путём CLAUDE_TOOLS_STATE_DIR. Путь Claude Code по умолчанию — $HOME/.npm-global/bin/claude, его можно переопределить через CLAUDE_BIN.

Долгоживущие Tunnel/Connector требуют перезапуска после обновления исходного кода. ChatGPT может кэшировать схему подключённых инструментов; если в новой сессии не видно шести native_session_*, обновите или переподключите Claude Tools Connector.

Проверка

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

Автоматические тесты покрывают:

• прямую инициализацию MCP только в Native-режиме, ровно шесть инструментов, отклонение инструментов V1 и неизвестных методов;

• реестр ходов и действий, идемпотентность ответов, аренду, право владения процессом, остановку и восстановление;

• чтение по всему компьютеру через Read/FindFiles/SearchText, защищённые пути, размеры, сортировку, буквальное сопоставление и границы гонок;

• Edit/Write/NotebookEdit: прямую запись в реальный каталог, изоляцию worktree, CAS, хеши и восстановление после сбоя;

• RunCommand: свободный вход для команд разработки, локальные исполняемые файлы сессии, файловую систему только для чтения, нулевую сеть, блокировку чувствительных служб и сбор по таймауту;

• фиксацию ID/хеша тела навыков, согласованность start/resume и границы приватного состояния;

• явную делегацию DeepSeek: барьер запуска, блокировку записи одной задачи, проверку маршрута, восстановление после перезапуска Gateway и остановку;

• отсутствие утечки авторизационных ID, токенов Runner, PID, внутренних путей или учётных данных модели в публичных MCP/Session/history.

Установочные тесты используют локальный Claude Code 2.1.247 и скриптовый GPT на localhost, не подключаясь к реальным моделям:

• test:native:installed: выполнение FindFiles → буквальный SearchText → Read → final с корнем только для чтения /, а также восстановление того же Runner/Claude Session после отключения Gateway.

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

• test:native:installed:direct-write: тот же набор реальных ходов Claude Code напрямую изменяет реальный каталог в тестовом фикстуре, затем resume и проверка постоянных результатов.

• test:native:installed:deepseek: проверка явной делегации, проверки результатов, активной блокировки записи, восстановления после перезапуска и остановки с помощью локального фейкового CLI DeepSeek.

• test:native:installed:skills: проверка, что два навыка с фиксированным хешем, содержащие только инструкции, используют один и тот же снимок при start/resume.

Эти локальные скриптовые тесты не расходуют квоты реальных моделей ChatGPT, Claude или DeepSeek. Минимальный смоук-тест с реальным DeepSeek по-прежнему требует отдельного разрешения пользователя.