ai-cli-mcp 2.9.1 → 2.10.0

package/.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- Briefly describe what this PR does -->
+
+## Type of Change
+
+- [ ] feat: New feature
+- [ ] fix: Bug fix
+- [ ] refactor: Refactoring
+- [ ] docs: Documentation
+- [ ] test: Add or update tests
+- [ ] chore: Build, CI, dependencies, etc.
+
+## Changes
+
+<!-- List the main changes -->
+
+-
+
+## Test Plan
+
+- [ ] `npm run test:unit` passes
+- [ ] `npm run build` passes
+- [ ] Manual testing (if applicable)
+
+## Notes
+
+<!-- Any additional context for reviewers -->

package/.github/workflows/watch-codex-fork-pr.yml

@@ -0,0 +1,98 @@
+name: Watch Codex Fork PR
+
+on:
+  schedule:
+    - cron: '17 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  watch-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check upstream PR and notify issue
+        uses: actions/github-script@v7
+        env:
+          UPSTREAM_OWNER: openai
+          UPSTREAM_REPO: codex
+          UPSTREAM_PR_NUMBER: '13537'
+          TARGET_ISSUE_NUMBER: '7'
+          COMMENT_MARKER: '<!-- codex-fork-pr-13537-merged -->'
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const upstreamOwner = process.env.UPSTREAM_OWNER;
+            const upstreamRepo = process.env.UPSTREAM_REPO;
+            const pull_number = Number(process.env.UPSTREAM_PR_NUMBER);
+            const issue_number = Number(process.env.TARGET_ISSUE_NUMBER);
+            const marker = process.env.COMMENT_MARKER;
+
+            const { data: pr } = await github.rest.pulls.get({
+              owner: upstreamOwner,
+              repo: upstreamRepo,
+              pull_number,
+            });
+
+            core.summary
+              .addHeading('Upstream PR status')
+              .addTable([
+                [
+                  { data: 'Field', header: true },
+                  { data: 'Value', header: true },
+                ],
+                ['PR', `${upstreamOwner}/${upstreamRepo}#${pr.number}`],
+                ['Title', pr.title],
+                ['State', pr.state],
+                ['Merged', String(Boolean(pr.merged_at))],
+                ['Merged at', pr.merged_at ?? 'not merged'],
+                ['Updated at', pr.updated_at],
+                ['URL', pr.html_url],
+              ]);
+
+            if (!pr.merged_at) {
+              core.info(`PR #${pr.number} is not merged yet. No issue comment posted.`);
+              await core.summary.write();
+              return;
+            }
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              per_page: 100,
+            });
+
+            const existingComment = comments.find((comment) => comment.body?.includes(marker));
+            if (existingComment) {
+              core.info(`Issue #${issue_number} already has a merged notification comment.`);
+              await core.summary.addRaw(`Merged notification already exists: ${existingComment.html_url}\n`).write();
+              return;
+            }
+
+            const body = [
+              marker,
+              'upstream PR `openai/codex#13537` has been merged.',
+              '',
+              `- PR: ${pr.html_url}`,
+              `- Merged at: ${pr.merged_at}`,
+              '',
+              'This is the PR that adds non-interactive forking via `codex exec --fork <SESSION_ID> [PROMPT]`.',
+              'That means a new session ID can be issued when forking an existing session headlessly.',
+              '`resume` itself still continues the same session and does not issue a new session ID.',
+            ].join('\n');
+
+            const { data: comment } = await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              body,
+            });
+
+            core.info(`Posted merged notification to issue #${issue_number}: ${comment.html_url}`);
+            await core.summary
+              .addHeading('Issue notification')
+              .addRaw(`Posted merged notification: ${comment.html_url}\n`)
+              .write();

package/.husky/pre-commit

@@ -0,0 +1 @@
+npm run test:unit

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.10.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.9.1...v2.10.0) (2026-03-07)
+
+
+### Features
+
+* gpt-5.4モデルを追加しcodex-ultraエイリアスを更新 ([0fb15a6](https://github.com/mkXultra/ai-cli-mcp/commit/0fb15a635ab9d5450da16cb3b15132054c8c0dbe))
+
 ## [2.9.1](https://github.com/mkXultra/ai-cli-mcp/compare/v2.9.0...v2.9.1) (2026-03-07)
 
 

package/README.ja.md

@@ -18,7 +18,7 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 - 自動承認モードでGemini CLIを実行（`-y` を使用）
 - 複数のAIモデルのサポート：
     - Claude (sonnet, sonnet[1m], opus, opusplan, haiku)
-    - Codex (gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, など)
+    - Codex (gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, など)
     - Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview)
 - PID追跡によるバックグラウンドプロセスの管理
 - ツールからの構造化された出力の解析と返却
@@ -133,7 +133,7 @@ Claude CLI、Codex CLI、またはGemini CLIを使用してプロンプトを実
 - **モデル (Models):**
     - **Ultra エイリアス:** `claude-ultra`, `codex-ultra` (自動的に high-reasoning に設定), `gemini-ultra`
     - Claude: `sonnet`, `sonnet[1m]`, `opus`, `opusplan`, `haiku`
-    - Codex: `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
+    - Codex: `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
     - Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
 - `reasoning_effort` (string, 任意): Codex専用。`model_reasoning_effort` を設定します（許容値: "low", "medium", "high", "xhigh"）。
 - `session_id` (string, 任意): 以前のセッションを再開するためのセッションID。対応モデル: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview。

package/README.md

@@ -18,7 +18,7 @@ This MCP server provides tools that can be used by LLMs to interact with AI CLI
 - Run Claude CLI with all permissions bypassed (using `--dangerously-skip-permissions`)
 - Execute Codex CLI with automatic approval mode (using `--full-auto`)
 - Execute Gemini CLI with automatic approval mode (using `-y`)
-- Support multiple AI models: Claude (sonnet, sonnet[1m], opus, opusplan, haiku), Codex (gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.2, gpt-5.1, gpt-5.1-codex, gpt-5-codex, gpt-5-codex-mini, gpt-5), and Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview)
+- Support multiple AI models: Claude (sonnet, sonnet[1m], opus, opusplan, haiku), Codex (gpt-5.4, gpt-5.3-codex, gpt-5.2-codex, gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.2, gpt-5.1, gpt-5.1-codex, gpt-5-codex, gpt-5-codex-mini, gpt-5), and Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview)
 - Manage background processes with PID tracking
 - Parse and return structured outputs from both tools
 
@@ -132,7 +132,7 @@ Executes a prompt using Claude CLI, Codex CLI, or Gemini CLI. The appropriate CL
 **Models:**
 - **Ultra Aliases:** `claude-ultra`, `codex-ultra` (defaults to high-reasoning), `gemini-ultra`
 - Claude: `sonnet`, `sonnet[1m]`, `opus`, `opusplan`, `haiku`
-- Codex: `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
+- Codex: `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5`
 - Gemini: `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`
 - `reasoning_effort` (string, optional): Codex only. Sets `model_reasoning_effort` (allowed: "low", "medium", "high", "xhigh").
 - `session_id` (string, optional): Optional session ID to resume a previous session. Supported for: haiku, sonnet, opus, gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview.

package/dist/__tests__/cli-builder.test.js

@@ -25,8 +25,8 @@ describe('cli-builder', () => {
         it('should resolve claude-ultra to opus', () => {
             expect(resolveModelAlias('claude-ultra')).toBe('opus');
         });
-        it('should resolve codex-ultra to gpt-5.3-codex', () => {
-            expect(resolveModelAlias('codex-ultra')).toBe('gpt-5.3-codex');
+        it('should resolve codex-ultra to gpt-5.4', () => {
+            expect(resolveModelAlias('codex-ultra')).toBe('gpt-5.4');
         });
         it('should resolve gemini-ultra to gemini-3.1-pro-preview', () => {
             expect(resolveModelAlias('gemini-ultra')).toBe('gemini-3.1-pro-preview');
@@ -221,7 +221,7 @@ describe('cli-builder', () => {
                     cliPaths: DEFAULT_CLI_PATHS,
                 });
                 expect(cmd.agent).toBe('codex');
-                expect(cmd.resolvedModel).toBe('gpt-5.3-codex');
+                expect(cmd.resolvedModel).toBe('gpt-5.4');
                 expect(cmd.args).toContain('-c');
                 expect(cmd.args).toContain('model_reasoning_effort=xhigh');
             });

package/dist/cli-builder.js

@@ -3,7 +3,7 @@ import { resolve as pathResolve, isAbsolute } from 'node:path';
 // Model alias mappings for user-friendly model names
 export const MODEL_ALIASES = {
     'claude-ultra': 'opus',
-    'codex-ultra': 'gpt-5.3-codex',
+    'codex-ultra': 'gpt-5.4',
     'gemini-ultra': 'gemini-3.1-pro-preview'
 };
 export const ALLOWED_REASONING_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh']);

package/dist/server.js

@@ -116,7 +116,7 @@ export class ClaudeCodeServer {
 **IMPORTANT**: This tool now returns immediately with a PID. Use other tools to check status and get results.
 
 **Supported models**:
-"claude-ultra", "codex-ultra", "gemini-ultra", "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1-codex-max", "gpt-5.2", "gpt-5.1", "gpt-5.1-codex", "gpt-5-codex", "gpt-5-codex-mini", "gpt-5", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview"
+"claude-ultra", "codex-ultra", "gemini-ultra", "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.4", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1-codex-max", "gpt-5.2", "gpt-5.1", "gpt-5.1-codex", "gpt-5-codex", "gpt-5-codex-mini", "gpt-5", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview"
 
 **Prompt input**: You must provide EITHER prompt (string) OR prompt_file (file path), but not both.
 
@@ -144,7 +144,7 @@ export class ClaudeCodeServer {
                             },
                             model: {
                                 type: 'string',
-                                description: 'The model to use. Aliases: "claude-ultra", "codex-ultra" (auto high-reasoning), "gemini-ultra". Standard: "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1", "gemini-2.5-pro", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", etc.',
+                                description: 'The model to use. Aliases: "claude-ultra", "codex-ultra" (auto high-reasoning), "gemini-ultra". Standard: "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.4", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1", "gemini-2.5-pro", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", etc.',
                             },
                             reasoning_effort: {
                                 type: 'string',

package/docs/concept.md

@@ -0,0 +1,154 @@
+# AI CLI MCP Server - Concept
+
+## What is this?
+
+AI CLI MCP Server (`ai-cli-mcp`) は、複数のAI CLIツール（Claude Code, Codex, Gemini）をMCPプロトコル経由でバックグラウンド実行するサーバーである。
+
+## 解決する課題
+
+### 1. 単一エージェントのボトルネック
+
+CursorなどのAI IDE は内部で1つのAIエージェントを逐次実行する。複雑なマルチステップ作業（リファクタリング + テスト作成 + ドキュメント更新など）では、1つずつ順番に処理するしかなく時間がかかる。
+
+### 2. モデル/プロバイダーのロックイン
+
+IDE が採用するAIモデルに依存し、タスクごとに最適なモデルを選択できない。コード生成には Claude Opus、高速な軽作業には Haiku、といった使い分けができない。
+
+### 3. AI CLI の非同期実行の欠如
+
+Claude Code や Codex CLI は対話的に使うことを前提としており、バックグラウンドでの非同期プロセス管理をネイティブにはサポートしていない。
+
+## Core Idea
+
+**MCP を「AIエージェントのプロセスマネージャー」として使う。**
+
+```
+MCP Client (Cursor, Claude Code, etc.)
+  │
+  ├─ run(prompt, model="opus")     → PID 1234 (即座に返却)
+  ├─ run(prompt, model="gpt-5.2-codex")  → PID 1235
+  ├─ run(prompt, model="gemini-2.5-pro") → PID 1236
+  │
+  ├─ list_processes()  → 実行状況一覧
+  ├─ get_result(pid)   → 個別結果取得
+  └─ wait(pids)        → 全完了待ち
+```
+
+- **Fire-and-forget**: `run` は即座にPIDを返し、呼び出し側はブロックされない
+- **Blocking wait**: `wait(pids)` は指定プロセスが全完了するまでブロックする。利用者がポーリングループを組む必要はない。`run` で複数タスクを投げ、自分の作業を進めた後、`wait` 一発で全結果を回収するのが基本フロー
+- **マルチモデル**: プロンプトごとに異なるAIモデルを選択可能
+- **プロセスライフサイクル管理**: 起動・監視・結果取得・強制終了を統一APIで提供
+
+### 基本フロー
+
+```
+run(task1) → PID 1
+run(task2) → PID 2
+run(task3) → PID 3
+  ↓
+(呼び出し側は自分の作業を続行)
+  ↓
+wait([PID 1, 2, 3]) → ブロック → 全完了後に結果をまとめて返却
+```
+
+## Core Responsibility
+
+このツールの責務は3つに集約される:
+
+### 1. どのAI CLIからでも同じプロンプトで使える
+
+このMCPサーバーは Claude Code / Gemini CLI / Codex CLI のいずれをホスト（呼び出し元）としても、同じツール名・同じ引数・同じプロンプトで動作する。ホスト側のAIがどのプロバイダーであっても、統一されたMCPインターフェースを通じて同一の体験を提供する。
+
+### 2. CLI差異の完全な隠蔽
+
+利用者（主にAIエージェント）は Claude Code / Codex / Gemini の個別仕様を一切知る必要がない。
+
+- パーミッションフラグの違い（`--dangerously-skip-permissions` / `--full-auto` / `-y`）
+- 出力形式の違い（Claude の JSON / Codex のログ / Gemini の出力）
+- セッション管理の違い（`--session-id` / `--session` / `-s`）
+- モデル名の指定方法の違い
+
+これらはすべて内部で吸収される。利用者は「モデル名とプロンプトを渡すだけ」でよい。
+
+### 3. AI-Friendly な返り値
+
+返り値は人間ではなく **AIエージェントが消費する** ことを前提に設計する。
+
+- 各CLIの生出力（JSON、ログ、テキスト）をパースし、構造化されたオブジェクトとして返す
+- `session_id` や `exitCode` などのメタデータを統一フォーマットで付与する
+- `verbose` フラグで必要に応じてツール使用履歴も提供する
+- AIが次のアクションを判断しやすい、一貫した構造を維持する
+
+## Design Principles
+
+### Thin Wrapper, Not a Framework
+
+各AI CLIの既存機能をそのまま活かし、MCPのインターフェースでラップするだけに留める。独自のプロンプト処理やフィルタリングは行わない。
+
+### Immediate Return
+
+`run` は常に即座にPIDを返す。重い処理のブロッキングを避け、呼び出し元が他の作業を並行して進められるようにする。
+
+### CLI Agnostic
+
+Claude / Codex / Gemini のCLI差異（フラグ、出力形式）を内部で吸収し、統一されたインターフェースを提供する。新しいCLIの追加も最小限の変更で可能な構造にする。
+
+## Architecture Overview
+
+```
+src/
+├── server.ts       # MCP Server 本体 (ツールハンドラ + プロセス管理)
+├── cli-builder.ts  # モデル名 → CLI コマンド構築 (パス解決・引数組み立て)
+├── cli-utils.ts    # CLI バイナリ検出・デバッグログ
+├── parsers.ts      # 各CLI出力のパース (Claude JSON / Codex logs / Gemini)
+├── cli.ts          # スタンドアロン CLI エントリポイント
+└── cli-parse.ts    # パース単体テスト用エントリポイント
+```
+
+## Session Stacking
+
+`session_id` を使ってコンテキストを積み重ね、効率的にタスクを実行する推奨パターン。初回の `run` で構築したコンテキストを後続タスクに引き継ぎ、再読み込みコストを削減する。
+
+詳細は [Session Stacking](./session-stacking.md) を参照。
+
+## Model Aliases (Ultra)
+
+`claude-ultra` / `codex-ultra` / `gemini-ultra` というエイリアスを提供している。
+
+```
+claude-ultra  → opus
+codex-ultra   → gpt-5.4 (+ reasoning_effort: high)
+gemini-ultra  → gemini-3.1-pro-preview
+```
+
+**設計意図**: AI プロバイダーのモデル名は頻繁に変わる。利用者（特にAIエージェント）が個々のモデル名の変遷を追う必要がないよう、「そのプロバイダーの最強モデル」を指す安定したエイリアスを提供する。マッピング先はサーバー側で更新するだけで、利用者のプロンプトを変更する必要がない。
+
+## Security Model
+
+このツールは **信頼された環境でのみ使用する** ことを前提としている。
+
+- Claude Code は `--dangerously-skip-permissions` で実行される（すべてのファイル操作・コマンド実行が無許可で行われる）
+- Codex は `--full-auto` で実行される
+- Gemini は `-y`（自動承認）で実行される
+
+つまり、このMCPサーバーに接続できるクライアントは、ローカルマシン上で **任意のコード実行が可能** である。ネットワーク越しの不特定多数への公開や、信頼できないクライアントからのアクセスは想定していない。
+
+## Constraints
+
+| 制約 | 詳細 |
+|---|---|
+| インメモリプロセス管理 | プロセス情報はサーバーのメモリ上にのみ保持される。サーバー再起動で全プロセス情報が消失する |
+| stdio トランスポートのみ | HTTP/WebSocket 等のリモートトランスポートは未サポート。ローカル実行が前提 |
+| 単一マシン | 分散実行やリモートマシンへのプロセス委譲はサポートしない |
+| CLI の事前セットアップ必須 | 各AI CLIのインストール・認証はユーザーが事前に完了させる必要がある |
+
+## Key Technical Decisions
+
+| 決定 | 理由 |
+|---|---|
+| `node:child_process.spawn` でプロセス管理 | 軽量で直接的。外部依存なしにPIDベースの管理が可能 |
+| `--dangerously-skip-permissions` (Claude) | MCP経由の自動実行には非対話モードが必須 |
+| `--full-auto` (Codex) / `-y` (Gemini) | 同上。各CLIの自動承認モード |
+| `session_id` サポート | コンテキストキャッシュにより、大規模コードベースの読み込みコストを複数タスクで共有 |
+| 出力パーサーの分離 | CLI出力形式の変更に対して個別に対応可能 |
+| npx 配布 | インストール不要でMCP設定に直接記述可能 |

package/docs/prd.md

@@ -0,0 +1,146 @@
+# AI CLI MCP Server - Product Requirements Document
+
+## Product Overview
+
+| 項目 | 内容 |
+|---|---|
+| プロダクト名 | AI CLI MCP Server (`ai-cli-mcp`) |
+| npm パッケージ | [ai-cli-mcp](https://www.npmjs.com/package/ai-cli-mcp) |
+| 現バージョン | 2.8.2 |
+| ライセンス | MIT |
+| ターゲットユーザー | MCP対応AI IDE / CLI を利用する開発者 |
+
+## Problem Statement
+
+AI支援開発において、以下の制約がユーザーの生産性を阻害している:
+
+1. **逐次処理の制約**: IDEのAIエージェントは1タスクずつしか処理できず、並行作業ができない
+2. **モデル選択の制約**: IDEが提供するモデルに限定され、タスクに最適なモデルを選べない
+3. **環境の制約**: AI CLIツールの豊富な機能（ファイル操作、Git操作、Web検索等）をIDE内から活用できない
+
+## Goals
+
+- **ホスト非依存**: Claude Code / Gemini CLI / Codex CLI のどれをホスト（呼び出し元）として使っても、同じプロンプト・同じインターフェースで動作すること
+- **CLI差異の隠蔽**: 利用者が呼び出し先の Claude Code / Codex / Gemini の個別仕様（フラグ、出力形式、セッション管理等）を意識せず、モデル名とプロンプトだけで使えること
+- **AI-Friendly な返り値**: 各CLIの生出力をパースし、AIエージェントが次のアクションを判断しやすい構造化データとして返すこと
+- **並行実行**: MCP対応の任意のクライアントから、複数のAI CLIエージェントを並行実行できること
+- **最小セットアップ**: npx 一行で起動可能であること
+
+## Non-Goals
+
+- AI CLI ツール自体の機能拡張
+- 独自のプロンプトエンジニアリングやチェーン処理
+- Web UI やダッシュボードの提供
+- AI CLI ツールのインストールや認証の自動化
+- 人間向けのリッチなフォーマット出力（返り値はAI消費が前提）
+
+## Functional Requirements
+
+### FR-1: プロセス実行 (`run`)
+
+- ユーザーがプロンプト（文字列 or ファイルパス）、作業ディレクトリ、モデル名を指定してAIエージェントを起動できる
+- プロセスはバックグラウンドで実行され、即座にPIDが返却される
+- モデル名から適切なCLI（Claude / Codex / Gemini）が自動選択される
+- Ultra エイリアス（`claude-ultra`, `codex-ultra`, `gemini-ultra`）による簡易モデル指定をサポート
+- `session_id` による前回セッションの継続をサポート（Claude, Gemini）
+- `reasoning_effort` による推論深度の指定をサポート（Codex）
+
+### FR-2: プロセス一覧 (`list_processes`)
+
+- 実行中・完了・失敗の全プロセスをPID・エージェント種別・ステータスとともに一覧表示できる
+
+### FR-3: 結果取得 (`get_result`)
+
+- PIDを指定して、プロセスの出力（パース済み）とメタデータを取得できる
+- `verbose` オプションでツール使用履歴等の詳細情報を取得できる
+- `session_id` がある場合は結果に含まれる
+
+### FR-4: 一括待機 (`wait`)
+
+- 複数PIDを指定して、全プロセスの完了を待機できる
+- 呼び出し側がポーリングする必要はなく、`wait` 自体がブロックして完了まで待つ設計
+- `run` → (自分の作業) → `wait` で結果回収、が基本フロー
+- タイムアウト指定が可能（デフォルト: 180秒）
+
+### FR-5: プロセス終了 (`kill_process`)
+
+- PIDを指定して実行中のプロセスをSIGTERMで終了できる
+
+### FR-6: クリーンアップ (`cleanup_processes`)
+
+- 完了・失敗したプロセスをプロセスリストから削除し、メモリを解放できる
+
+## Non-Functional Requirements
+
+### NFR-1: パフォーマンス
+
+- `run` のレスポンスタイムはプロセスの実行時間に依存せず、即座に返却すること
+- 複数プロセスの同時実行をサポートすること
+
+### NFR-2: 互換性
+
+- Node.js v20 以上で動作すること
+- MCP プロトコル仕様に準拠すること（`@modelcontextprotocol/sdk` 使用）
+- stdio トランスポートで動作すること
+
+### NFR-3: 信頼性
+
+- CLIプロセスのクラッシュを適切にハンドリングし、ステータスに反映すること
+- プロセスの stdout / stderr を確実に収集すること
+
+### NFR-4: 運用性
+
+- `npx ai-cli-mcp@latest` のみで起動可能であること
+- 環境変数によるCLIパスのカスタマイズが可能であること
+- `MCP_CLAUDE_DEBUG` によるデバッグログ出力をサポートすること
+
+## Supported Models
+
+| Provider | Models |
+|---|---|
+| Claude | `sonnet`, `sonnet[1m]`, `opus`, `opusplan`, `haiku` |
+| Codex | `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.1-codex-mini`, `gpt-5.1-codex-max`, `gpt-5.2`, `gpt-5.1`, `gpt-5` |
+| Gemini | `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview` |
+| Ultra aliases | `claude-ultra`, `codex-ultra`, `gemini-ultra` |
+
+## User Scenarios
+
+### Scenario 1: 並列タスク実行
+
+1. ユーザーがMCPクライアント経由で3つの `run` を発行（リファクタリング / テスト作成 / ドキュメント更新）
+2. それぞれ異なるモデルで即座に起動、PIDが返却される
+3. ユーザーは別作業を進めつつ、`wait` で全完了を待機
+4. 各結果をまとめて確認
+
+### Scenario 2: Session Stacking（推奨パターン）
+
+`session_id` によるセッション再開を活用し、コンテキストを積み重ねて効率的にタスクを実行する。
+
+1. `opus` で大規模コードベースを読み込み、`session_id` を取得
+2. 同じ `session_id` を後続の `run` に渡して複数タスクを並行起動
+3. コンテキストの再読み込みコストなしに、共有コンテキスト上で実行される
+4. さらに後続タスクの `session_id` を使って追加の深掘りも可能（段階的スタッキング）
+
+ポーリング不要: 手順2の後は `wait` で全完了をブロッキング待機すればよい。
+
+**注意**: 多段スタッキング（手順4）に完全対応しているのは Claude のみ。Codex / Gemini は1回のセッション再開は可能だが、再開後に新しい `session_id` が返らないため、それ以上の連鎖はできない。詳細は [Session Stacking](./session-stacking.md) を参照。
+
+## Security Model
+
+本プロダクトは **信頼されたローカル環境** での使用を前提とする。
+
+- 各AI CLIは自動承認モード（`--dangerously-skip-permissions` / `--full-auto` / `-y`）で実行されるため、接続クライアントはローカルマシン上で任意のコード実行が可能になる
+- ネットワーク越しの不特定多数への公開は想定しない
+- セキュリティ境界は「MCPサーバーへの接続可否」で制御される
+
+## Constraints
+
+- プロセス情報はインメモリのみ。サーバー再起動で消失する（永続化なし）
+- stdio トランスポートのみ対応。リモート接続は未サポート
+- 単一マシンでの実行が前提。分散実行はサポートしない
+- 各AI CLIの事前インストール・認証はユーザー責任
+
+## Release History (Notable)
+
+- **v1.x**: Claude Code MCP として Claude CLI のみサポート
+- **v2.x**: `ai-cli-mcp` にリネーム、Codex / Gemini サポート追加、非同期実行モデルに移行

package/docs/session-stacking.md

@@ -0,0 +1,67 @@
+# Session Stacking
+
+## 概要
+
+Session Stacking は、`session_id` を使ってコンテキストを積み重ね、効率的にタスクを実行する推奨パターンである。
+
+最初の `run` で構築したコンテキスト（コードベースの理解等）を `session_id` 経由で後続タスクに引き継ぐことで、同じ情報の再読み込みを避ける。
+
+## 基本フロー
+
+```
+Step 1: コンテキスト構築
+run("src/を全部読んで構造を理解して", model="opus")
+  → 結果: { session_id: "abc-123", ... }
+
+Step 2: コンテキストを再利用して並行タスク実行
+run("utilsをリファクタして", session_id="abc-123", model="sonnet")  → PID 1
+run("READMEを更新して",       session_id="abc-123", model="haiku")   → PID 2
+
+Step 3: 結果回収
+wait([PID 1, PID 2])  → ブロッキング待機 → 全結果返却
+```
+
+## 利点
+
+- **コスト削減**: 大規模コードベースの再読み込みを避けられる
+- **コンテキスト共有**: 1回の理解をベースに複数の派生タスクを実行できる
+- **段階的な深掘り**: 概要把握 → 詳細分析 → 実装、とセッションを積み重ねられる
+
+## 多段スタッキング
+
+Session Stacking の真価は、セッションを2段、3段と重ねて深掘りしていける点にある。
+
+```
+Step 1: 全体理解
+run("src/を全部読んで構造を理解して", model="opus")
+  → session_id: "abc-123"
+
+Step 2: 詳細分析（Step 1 のコンテキストを継承）
+run("認証周りの問題点を洗い出して", session_id="abc-123", model="opus")
+  → session_id: "def-456"  ← 新しい session_id が返る
+
+Step 3: 実装（Step 1 + Step 2 のコンテキストを継承）
+run("洗い出した問題を修正して", session_id="def-456", model="sonnet")
+```
+
+各ステップのコンテキストが累積されるため、後段のタスクほど深い理解の上で実行される。
+
+## 各CLIの対応状況
+
+| CLI | 1回のセッション再開 | 多段スタッキング | 備考 |
+|---|---|---|---|
+| Claude | OK | **OK** | 再開後に新しい `session_id` が返る。`--fork-session` でセッションをフォークするため、元のセッションも保持される |
+| Codex | OK | **NG** | 再開後に新しい `session_id` が返らない。2段（初回 + 1回再開）まで |
+| Gemini | OK | **NG** | 再開後に新しい `session_id` が返らない。2段（初回 + 1回再開）まで |
+
+**完全な多段 Session Stacking ができるのは現時点では Claude のみ。** Codex / Gemini は1回のセッション再開には対応しているが、再開時に新しい `session_id` が発行されないため、それ以上の連鎖はできない。これは各CLIの制約であり、本ツール側の制限ではない。
+
+## 内部実装
+
+各CLIのセッション再開方法の違いは `cli-builder.ts` 内で吸収される。利用者は `session_id` パラメータを渡すだけでよい。
+
+| CLI | 内部で実行されるフラグ |
+|---|---|
+| Claude | `-r <session_id> --fork-session` |
+| Gemini | `-r <session_id>` |
+| Codex | `exec resume <session_id>` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-cli-mcp",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "mcpName": "io.github.mkXultra/ai-cli-mcp",
   "description": "MCP server for AI CLI tools (Claude, Codex, and Gemini) with background process management",
   "author": "mkXultra",
@@ -20,7 +20,8 @@
     "test:coverage": "npm run build && vitest --coverage --config vitest.config.unit.ts",
     "test:watch": "vitest --watch",
     "cli.run": "tsx src/cli.ts",
-    "cli.run.parse": "tsx src/cli-parse.ts"
+    "cli.run.parse": "tsx src/cli-parse.ts",
+    "prepare": "husky"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.2",
@@ -33,6 +34,7 @@
     "@semantic-release/git": "^10.0.1",
     "@types/node": "^22.15.17",
     "@vitest/coverage-v8": "^2.1.8",
+    "husky": "^9.1.7",
     "semantic-release": "^25.0.2",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",

package/src/__tests__/cli-builder.test.ts

@@ -36,8 +36,8 @@ describe('cli-builder', () => {
       expect(resolveModelAlias('claude-ultra')).toBe('opus');
     });
 
-    it('should resolve codex-ultra to gpt-5.3-codex', () => {
-      expect(resolveModelAlias('codex-ultra')).toBe('gpt-5.3-codex');
+    it('should resolve codex-ultra to gpt-5.4', () => {
+      expect(resolveModelAlias('codex-ultra')).toBe('gpt-5.4');
     });
 
     it('should resolve gemini-ultra to gemini-3.1-pro-preview', () => {
@@ -280,7 +280,7 @@ describe('cli-builder', () => {
         });
 
         expect(cmd.agent).toBe('codex');
-        expect(cmd.resolvedModel).toBe('gpt-5.3-codex');
+        expect(cmd.resolvedModel).toBe('gpt-5.4');
         expect(cmd.args).toContain('-c');
         expect(cmd.args).toContain('model_reasoning_effort=xhigh');
       });

package/src/cli-builder.ts

@@ -4,7 +4,7 @@ import { resolve as pathResolve, isAbsolute } from 'node:path';
 // Model alias mappings for user-friendly model names
 export const MODEL_ALIASES: Record<string, string> = {
   'claude-ultra': 'opus',
-  'codex-ultra': 'gpt-5.3-codex',
+  'codex-ultra': 'gpt-5.4',
   'gemini-ultra': 'gemini-3.1-pro-preview'
 };
 

package/src/server.ts

@@ -162,7 +162,7 @@ export class ClaudeCodeServer {
 **IMPORTANT**: This tool now returns immediately with a PID. Use other tools to check status and get results.
 
 **Supported models**:
-"claude-ultra", "codex-ultra", "gemini-ultra", "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1-codex-max", "gpt-5.2", "gpt-5.1", "gpt-5.1-codex", "gpt-5-codex", "gpt-5-codex-mini", "gpt-5", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview"
+"claude-ultra", "codex-ultra", "gemini-ultra", "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.4", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1-codex-max", "gpt-5.2", "gpt-5.1", "gpt-5.1-codex", "gpt-5-codex", "gpt-5-codex-mini", "gpt-5", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview"
 
 **Prompt input**: You must provide EITHER prompt (string) OR prompt_file (file path), but not both.
 
@@ -190,7 +190,7 @@ export class ClaudeCodeServer {
               },
               model: {
                 type: 'string',
-                description: 'The model to use. Aliases: "claude-ultra", "codex-ultra" (auto high-reasoning), "gemini-ultra". Standard: "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1", "gemini-2.5-pro", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", etc.',
+                description: 'The model to use. Aliases: "claude-ultra", "codex-ultra" (auto high-reasoning), "gemini-ultra". Standard: "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.4", "gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.1-codex-mini", "gpt-5.1", "gemini-2.5-pro", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", etc.',
               },
               reasoning_effort: {
                 type: 'string',