Claude Tools Native Gateway

In one sentence: Make web ChatGPT the sole brain, driving real local Claude Code native Sessions to perform controlled reads, modifications, verification, and recovery.

The public repository contains only source code and tests; it does not include local keys, Tunnel configuration, or state/ session state.

Architecture

The Gateway now has only one execution engine: Native V2.

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

The Gateway itself handles MCP initialization, tool inventory, and call dispatch; it no longer starts or proxies V1's claude mcp serve tool server. A Claude Code process dedicated to a Session is started only after the Native Session is created.

The original V1 Agent Session, top-level Read/Edit/Write/Bash, local task tools, legacy DeepSeek delegation, and ChatGPT Bridge have been removed from the runtime entry points and the code tree. What remains are the shared low-level facilities V2 still needs: atomic state writes, credential path protection, process identity verification, and macOS sandbox rules. Old V1 state files are not automatically deleted, but the Native Gateway will not read or execute them.

MCP Control Plane

The web version sees only six tools:

• native_session_start

• native_session_continue

• native_session_recover

• native_session_reply_and_wait

• native_session_status

• native_session_stop

Any V1 tool name, top-level file tool, Bash, legacy DeepSeek tool, or other MCP method is rejected server-side, rather than merely hidden from the tool list.

Claude Code Session Capabilities

Sessions have three distinct tiers; after creation, they cannot be upgraded, downgraded, or have their root directory changed:

• read_only: Read, FindFiles, SearchText, and read-only RunCommand; the read scope is the entire computer, except for protected state/credential paths and macOS permissions.

• direct_write: adds Edit, Write, and NotebookEdit on top of full-computer read capability, modifying only the real directory the user explicitly selected. This tier should only be chosen when the user explicitly asks to modify real files.

• worktree_write: the tool set is the same as direct_write, but modifications go to a separate Git worktree created and retained by the Gateway; the source checkout remains unchanged.

These are logical tools the model can call in Claude Code's native Agent loop, but the executors belong to the Gateway. Unregulated Claude Code built-in file tools and Bash remain disabled, to avoid bypassing action authorization, hashing, recovery, and the audit ledger.

Reading and Search

• Read can read any unprotected plain UTF-8 file on the computer, no longer restricted to the write directory.

• FindFiles performs bounded file enumeration from any absolute directory.

• SearchText does UTF-8 literal matching only; it does not accept regex or glob.

• Searches do not follow symbolic links and skip .git, protected paths, and external hard links.

• Both a single search result and a full action receipt are limited to 64 KiB.

• All tiers can inspect different disks and directories; working_directory is only the default search location, the command CWD, and the write boundary for write tiers. macOS TCC/file permissions may still deny Desktop, Documents, or other system-protected locations.

File and Notebook Modification

• Under direct_write, Edit, Write, and NotebookEdit modify the real directory bound to the Session; under worktree_write, they modify only the managed worktree.

• Write can create missing parent directories on demand within the authorized root, then atomically create the target file; it cannot use this to escape the root, symbolic links, .git, or protected paths.

• NotebookEdit supports replacing, inserting, and deleting cells by cell ID, but does not execute the Notebook.

• Every write action saves pre-write and post-write SHA-256 and uses prepare, CAS, atomic persistence, and a durable receipt.

• After a process crash, the real file state is verified; if it cannot be determined, recovery stops rather than blindly repeating the write.

• direct_write has no file deletion tool and does not write files because of read-only check commands; it may still overwrite or modify target files per explicit user instructions.

• In worktree_write, the source checkout's files, HEAD, tree, index, and working tree state remain unchanged; the Git common dir registers a retained worktree.

Verification Commands

RunCommand accepts installed system commands and executables inside the Session directory; it no longer maintains a static command whitelist that could easily break normal development tools. Arguments are still passed as exact argv, never assembled into a shell string by the Gateway:

• The Session root filesystem is read-only from the command's perspective;

• Network, process signals, Keychain/XPC, and model CLIs are blocked by the macOS Seatbelt;

• Entry points such as sudo, direct delete/move, system control, find -delete/-exec, rg --pre, and model CLIs remain explicitly rejected;

• Symbolic links, hard links, or file counts in ordinary projects no longer cause the command to be rejected for the entire repository before startup; actual access is constrained by Seatbelt, protected paths, and macOS permissions;

• Output, runtime, and subprocess group reclamation all have bounds;

• Results first enter the same action ledger, then are handed to the next GPT turn.

It is intended for trusted repository verification, not as a container against malicious processes running under the same macOS account. Do not concurrently modify the managed worktree with other editors or processes while the Session is running.

Main Model, Web Search, and DeepSeek

The main route is fixed to chatgpt-main and does not accept model, provider, endpoint, API key, or fallback parameters. When the current ChatGPT turn stops, Claude Code pauses at waiting_for_gpt; it will not switch to Claude, DeepSeek, or Codex on its own to continue thinking.

Web search continues to be handled by web ChatGPT. Claude Code's WebSearch/WebFetch are not enabled, so there is no risk of GPT search conflicting with Claude's own search or of sources getting out of control.

By default, subagent_policy: "none" means no DeepSeek is created. Only after worktree_write explicitly selects deepseek_explicit can GPT use it in the main loop:

• deepseek_subagent_start

• deepseek_subagent_get

• deepseek_subagent_stop

Delegation must first enter the main Session's persistent action ledger before the isolated sub-Session is allowed through. While a subtask is running, the main Session cannot concurrently Edit, Write, NotebookEdit, RunCommand, or start a second subtask. The route is fixed as Sonnet/Opus → Flash, Fable → Pro; failures do not fall back to Claude, Codex, OpenAI, or another DeepSeek tier.

Skill Context

native_session_start can accept up to eight skill_contexts explicitly selected by ChatGPT. They are not Claude Code's native Skill runtime:

• Only the validated instruction body is extracted and frozen;

• Scripts, resources, plugins, Hooks, Slash Commands, and extra tools are not loaded;

• Each allowed item pins both the skill ID and the SHA-256 of the normalized full SKILL.md;

• The first start and subsequent resume use the same persistent snapshot;

• The full body appears only in 0600 private state and in the model context the current GPT turn requires.

Example allowlist:

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

The hash is computed over the full text after removing the UTF-8 BOM and normalizing CRLF/CR to LF.

Isolation and Recovery

• Each Session uses an independent HOME, Claude config directory, runtime directory, and process group.

• Claude Code runs with --bare, empty setting sources, strict MCP configuration, and a precise tool set.

• The main Claude process can only reach the exact local Broker/Executor loopback port.

• Credential directories, Gateway state, .git, symbolic links, and external hard links all fail closed; access to ordinary system/user paths is determined jointly by the Session root, macOS TCC, and file permissions.

• ChatGPT replies and each approved action are atomically persisted before being released to the running process.

• Lease expiry stops the Runner and leaves an inspectable state.

• A Gateway restart does not kill a Runner that still belongs to a Session; native_session_recover verifies ownership, rotates the lease, and continues the same Claude Code Session.

• When the Runner no longer exists, recovery is not faked, and completed actions are not repeated.

Claude Code 2.1.247 has no verified standalone switch to "enable only Hooks while continuing to disable keychain, plugins, and automatic memory," so native Hooks, native Skill/Slash, Agent, Workflow, Web, and third-party MCP not governed by the action ledger remain disabled.

Running

npm start

The Native Gateway no longer needs the CLAUDE_TOOLS_NATIVE_V2 or CLAUDE_TOOLS_NATIVE_V2_ONLY switches; Native-only is the only runtime mode.

State is saved in state/ by default and can be changed via the absolute-path environment variable CLAUDE_TOOLS_STATE_DIR. The default Claude Code path is $HOME/.npm-global/bin/claude and can be overridden with CLAUDE_BIN.

Long-running Tunnel/Connector instances need to be restarted after source updates. ChatGPT may cache the connected tool schema; if a new session does not see the six native_session_* tools, refresh or reconnect the Claude Tools Connector.

Verification

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

Automated tests cover:

• Native-only MCP direct initialization, the exact six tools, and rejection of V1 tools and unknown methods;

• Turn and action ledger, reply idempotency, leases, process ownership, stop and recovery;

• Read/FindFiles/SearchText full-computer reads, protected paths, size, ordering, literal matching, and race boundaries;

• Edit/Write/NotebookEdit direct real-directory writes, worktree isolation, CAS, hashing, and crash recovery;

• RunCommand permissive development command entry points, Session-local executables, read-only filesystem, zero network, sensitive service blocking, and timeout reclamation;

• Skill ID/body hash pinning, start/resume consistency, and private state boundaries;

• DeepSeek explicit delegation startup barrier, single-task write lock, route verification, Gateway restart recovery, and stop;

• Public MCP/Session/history does not leak authorization IDs, Runner tokens, PIDs, internal paths, or model credentials.

Installed tests use the local Claude Code 2.1.247 and a localhost scripted GPT, without connecting to real models:

• test:native:installed: executes FindFiles → literal SearchText → Read → final with / as the read-only root, and recovers the same Runner/Claude Session after the Gateway disconnects.

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

• test:native:installed:direct-write: the same set of real Claude Code turns directly modifies a real directory in the test fixture, then resumes and verifies the persisted results.

• test:native:installed:deepseek: uses a local fake DeepSeek CLI to verify explicit delegation, result verification, active write lock, restart recovery, and stop.

• test:native:installed:skills: verifies that two hash-pinned, instruction-only Skills use the same snapshot across start/resume.

These local scripted tests do not consume real ChatGPT, Claude, or DeepSeek model quota. A real DeepSeek minimal smoke test still requires separate user authorization.