Claude Tools Native Gateway

一言で言えば：Web版ChatGPTを唯一の主脳とし、ローカルの本物のClaude CodeネイティブSessionを駆動して、制御された読み取り・変更・検証・復元を完了する。

公開リポジトリにはソースコードとテストのみが含まれ、ローカルキー、Tunnel設定、state/セッション状態は含まれません。

アーキテクチャ

Gatewayは現在、Native V2の単一の実行エンジンのみを備えています：

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

Gateway自身がMCP初期化、ツール一覧、呼び出しディスパッチを完了し、V1のclaude mcp serveツールサーバーを起動またはプロキシしません。Native Sessionを作成した後にのみ、そのSession専用のClaude Codeプロセスが起動されます。

旧V1 Agent Session、トップレベルのRead/Edit/Write/Bash、ローカルタスクツール、旧DeepSeek委任、ChatGPT Bridgeは、実行エントリとコードツリーから削除されました。残っているのはV2が引き続き必要とする共通の基盤機能です：原子的状態書き込み、資格情報パスの保護、プロセス身元認証、macOSサンドボックスルール。旧V1状態ファイルは自動削除されませんが、Native Gatewayはそれらを読み取ったり実行したりしません。

MCPコントロールプレーン

Web版には6つのツールのみが表示されます：

• 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 Session機能

Sessionには明確な3つのグレードがあり、作成後にアップグレード・ダウングレードやルートディレクトリの変更はできません：

• read_only：Read、FindFiles、SearchText、読み取り専用RunCommand。読み取り範囲はコンピュータ全体で、保護された状態/資格情報パスとmacOS権限を除きます。

• direct_write：コンピュータ全体の読み取り機能にEdit、Write、NotebookEditを追加し、ユーザーが明示的に選択した実際のディレクトリのみを直接変更します。ユーザーが明示的に実ファイルの変更を要求した場合にのみ、このグレードを選択すべきです。

• worktree_write：ツールセットはdirect_writeと同じですが、変更対象はGatewayが作成・保持する独立したGit worktreeであり、ソースcheckoutは変更されません。

これらはClaude CodeネイティブAgentループ内でモデルが呼び出せる論理ツールですが、実行器はGatewayが所有します。監督されていないClaude Code組み込みファイルツールとBashは引き続き無効化され、アクション認可、ハッシュ、復元、監査台帳の迂回を防ぎます。

読み取りと検索

• Readは、コンピュータ上の保護されていない任意の通常のUTF-8ファイルを読み取れます。書き込みディレクトリに制限されなくなりました。

• FindFilesは、任意の絶対ディレクトリから境界付きファイル列挙ができます。

• SearchTextはUTF-8リテラル一致のみで、正規表現やglobは受け付けません。

• 検索はシンボリックリンクを追跡せず、.git、保護パス、外部ハードリンクをスキップします。

• 単一の検索結果と完全なアクション受領書は64 KiB以内に制限されます。

• すべてのグレードで異なるディスクやディレクトリを検査できます。working_directoryはデフォルトの検索位置、コマンドCWD、書き込みグレードの書き込み境界にすぎません。macOS TCC/ファイル権限により、Desktop、Documents、その他のシステム保護位置が拒否される場合があります。

ファイルとNotebookの変更

• direct_writeでは、Edit、Write、NotebookEditがSessionにバインドされた実際のディレクトリを変更します。worktree_writeでは管理対象worktreeのみを変更します。

• Writeは、認可されたルートディレクトリ内で不足している親ディレクトリを必要に応じて作成し、その後ターゲットファイルを原子的に作成します。これによってルートディレクトリ、シンボリックリンク、.git、保護パスを越えることはできません。

• NotebookEditはcell IDによる置換、挿入、削除をサポートしますが、Notebookを実行しません。

• 各書き込みアクションは書き込み前と書き込み後のSHA-256を保存し、準備、CAS、原子的ディスク書き込み、永続的な受領書を使用します。

• プロセスクラッシュ後は実際のファイル状態を照合し、確定できない場合は復元を停止し、盲目的に書き込みを繰り返しません。

• direct_writeにはファイル削除ツールがなく、読み取り専用チェックコマンドによってファイルを書き込むこともありません。ユーザーの明示的な指示に従ってターゲットファイルを上書きまたは変更することは可能です。

• worktree_writeでは、ソースcheckoutのファイル、HEAD、tree、index、ワークスペース状態は変更されません。Git common dirは保持型worktreeとして登録されます。

検証コマンド

RunCommandは、インストール済みのシステムコマンドとSessionディレクトリ内の実行可能ファイルを受け付けます。通常の開発ツールを誤って傷つけやすい静的コマンドホワイトリストは維持されません。引数は正確なargvとして渡され、Gatewayが自動的にシェル文字列に組み立てることはありません：

• コマンドから見たSessionルートファイルシステムは読み取り専用。

• ネットワーク、プロセスシグナル、Keychain/XPC、モデルCLIはmacOS Seatbeltによってブロック。

• sudo、直接削除/移動、システム制御、find -delete/-exec、rg --pre、モデルCLIなどのエントリは明示的に拒否。

• 通常のプロジェクト内のシンボリックリンク、ハードリンク、ファイル数によって、コマンドが起動前にリポジトリ全体で拒否されることはありません。実際のアクセス時にはSeatbelt、保護パス、macOS権限によって制約されます。

• 出力、実行時間、子プロセスグループの回収には境界があります。

• 結果はまず同じアクション台帳に入り、その後次のGPTターンに渡されます。

これは信頼できるリポジトリの検証に使用され、同じmacOSアカウントの悪意あるプロセスに対抗するコンテナではありません。Session実行中は、他のエディタやプロセスで管理対象worktreeを並行して変更しないでください。

メインモデル、Web検索、DeepSeek

メインルートはchatgpt-mainに固定され、model、provider、endpoint、API key、fallbackパラメータは受け付けません。現在のChatGPTターンが停止すると、Claude Codeはwaiting_for_gptで停止します。Claude、DeepSeek、Codexに勝手に切り替えて思考を続けることはありません。

Web検索は引き続きWeb版ChatGPTが実行します。Claude CodeのWebSearch/WebFetchは開放されないため、GPTの検索とClaude自身の検索が衝突したり、ソースが制御不能になったりすることはありません。

デフォルトのsubagent_policy: "none"ではDeepSeekは作成されません。worktree_writeが明示的にdeepseek_explicitを選択した場合のみ、GPTはメインループで使用できます：

• deepseek_subagent_start

• deepseek_subagent_get

• deepseek_subagent_stop

委任はまずメインSessionの永続的なアクション台帳に入り、その後隔離されたサブSessionが許可されます。サブタスク中、メインSessionはEdit、Write、NotebookEdit、RunCommandを並行実行したり、2つ目のサブタスクを開始したりできません。ルートはSonnet/Opus → Flash、Fable → Proに固定され、失敗してもClaude、Codex、OpenAI、別のグレードのDeepSeekにフォールバックしません。

Skillコンテキスト

native_session_startは、ChatGPTが明示的に選択した最大8つのskill_contextsを受け取れます。これらはClaude CodeネイティブSkillランタイムではありません：

• 検証済みの指示本文のみを抽出して凍結。

• スクリプト、リソース、プラグイン、Hook、Slash Command、追加ツールは読み込まれません。

• 各許可項目はskill IDと正規化された完全なSKILL.mdのSHA-256の両方を固定します。

• 初回起動とその後の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に統一した後の完全なテキストに対して計算されます。

分離と復元

• 各Sessionは独立したHOME、Claude設定ディレクトリ、実行ディレクトリ、プロセスグループを使用します。

• Claude Codeは--bare、空のsetting sources、厳格なMCP設定、正確なツールセットを使用します。

• メインのClaudeプロセスは、正確なローカルBroker/Executorループバックポートにのみアクセスできます。

• 資格情報ディレクトリ、Gateway状態、.git、シンボリックリンク、外部ハードリンクはすべてfail closed。通常のシステム/ユーザーパスへのアクセス可否は、Sessionルート、macOS TCC、ファイル権限によって共同で決定されます。

• ChatGPTの返信と各承認済みアクションは、まず原子的にディスクに書き込まれてから、実行中のプロセスに解放されます。

• リースの期限切れはRunnerを停止し、検査可能な状態を残します。

• Gatewayの再起動は、Sessionに属するRunnerを殺しません。native_session_recoverは所有権を検証し、リースをローテーションし、同じClaude Code Sessionを継続します。

• 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は接続済みツールのschemaをキャッシュする可能性があります。新しいセッションで6つの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

自動テストの対象：

• Native-only MCPの直接初期化、正確な6ツール、V1ツールと未知メソッドの拒否。

• ターンとアクション台帳、返信の冪等性、リース、プロセス所有権、停止と復元。

• Read/FindFiles/SearchTextのコンピュータ全体読み取り、保護パス、サイズ、ソート、リテラル一致、競合境界。

• Edit/Write/NotebookEditのdirect real-directory書き込み、worktree分離、CAS、ハッシュ、クラッシュ復元。

• RunCommandの寛容な開発コマンドエントリ、Sessionローカル実行可能ファイル、読み取り専用ファイルシステム、ゼロネットワーク、機密サービスブロック、タイムアウト回収。

• SkillのID/本文ハッシュ固定、start/resumeの一貫性、プライベート状態境界。

• DeepSeek明示委任の起動バリア、単一タスク書き込みロック、ルート検証、Gateway再起動復元、停止。

• 公開MCP/Session/historyが認可ID、Runner token、PID、内部パス、モデル資格情報を漏洩しないこと。

InstalledテストはローカルのClaude Code 2.1.247とlocalhostスクリプトGPTを使用し、実際のモデルには接続しません：

• test:native:installed：/を読み取り専用ルートとしてFindFiles → リテラルSearchText → Read → finalを実行し、Gateway切断後に同じRunner/Claude Sessionを復元。

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

• test:native:installed:direct-write：同じ一連の実際のClaude Codeターンでテストフィクスチャ内の実際のディレクトリを直接変更し、resumeして永続結果を検証。

• test:native:installed:deepseek：ローカルの偽DeepSeek CLIを使用して、明示的委任、結果検証、アクティブ書き込みロック、再起動復元、停止を検証。

• test:native:installed:skills：ハッシュ固定された2つの純粋指示Skillがstart/resumeで同じスナップショットを使用することを検証。

これらのローカルスクリプトテストは、実際のChatGPT、Claude、DeepSeekモデルクォータを消費しません。実際のDeepSeek最小スモークテストは、ユーザーの個別承認が引き続き必要です。