ai-cli-mcp 2.14.1 → 2.16.0

package/.github/dependabot.yml

@@ -0,0 +1,28 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    target-branch: "develop"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      npm-production:
+        dependency-type: "production"
+        patterns:
+          - "*"
+      npm-development:
+        dependency-type: "development"
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    target-branch: "develop"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 2
+    groups:
+      github-actions:
+        patterns:
+          - "*"

package/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [20.19.0, 22.12.0, 24.x]
 
     steps:
     - name: Checkout repository
@@ -29,3 +29,6 @@ jobs:
 
     - name: Build project
       run: npm run build
+
+    - name: Run unit tests
+      run: npm run test:unit

package/.github/workflows/dependency-review.yml

@@ -0,0 +1,22 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches:
+      - develop
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: moderate
+          fail-on-scopes: runtime

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [2.16.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.15.0...v2.16.0) (2026-04-11)
+
+
+### Features
+
+* peekコマンドを追加 — 実行中エージェントの自然言語メッセージをワンショット観測 ([c12fd4c](https://github.com/mkXultra/ai-cli-mcp/commit/c12fd4cbe374a05b5223191e10fb2144b5d86bd0))
+
+# [2.15.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.14.1...v2.15.0) (2026-04-09)
+
+
+### Features
+
+* OpenCode CLIを新しいAIバックエンドとして追加 ([0677c57](https://github.com/mkXultra/ai-cli-mcp/commit/0677c57659b36fd1083cd96166c2c608c45038b3))
+
 ## [2.14.1](https://github.com/mkXultra/ai-cli-mcp/compare/v2.14.0...v2.14.1) (2026-04-07)
 
 

package/README.ja.md

@@ -5,7 +5,7 @@
 
 > **📦 パッケージ移行のお知らせ**: 本パッケージは旧名 `@mkxultra/claude-code-mcp` から `ai-cli-mcp` に名称変更されました。これは、複数のAI CLIツールのサポート拡大を反映したものです。
 
-AI CLIツール（Claude, Codex, Gemini, Forge）をバックグラウンドプロセスとして実行し、権限処理を自動化するMCP（Model Context Protocol）サーバーです。
+AI CLIツール（Claude, Codex, Gemini, Forge, OpenCode）をバックグラウンドプロセスとして実行し、権限処理を自動化するMCP（Model Context Protocol）サーバーです。
 
 Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦戦していることに気づいたことはありませんか？このサーバーは、強力な統合 `run` ツールを提供し、複数のAIエージェントを活用してコーディングタスクをより効果的に処理できるようにします。
 
@@ -21,11 +21,13 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 - 自動承認モードでCodex CLIを実行（`--full-auto` を使用）
 - 自動承認モードでGemini CLIを実行（`-y` を使用）
 - Forge CLI を非対話モードで実行（`forge -C <workFolder> -p <prompt>` を使用）
+- OpenCode を非対話 JSON モードで実行（`opencode run --format json --dir <workFolder> <prompt>` を使用）
 - 複数のAIモデルのサポート：
     - 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, など)
     - Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview)
     - Forge (`forge`)
+    - OpenCode (`opencode` と `oc-<provider/model>` ラッパー。例: `oc-openai/gpt-5.4`)
 - PID追跡によるバックグラウンドプロセスの管理
 - ツールからの構造化された出力の解析と返却
 
@@ -67,6 +69,7 @@ Cursorなどのエディタが、複雑な手順を伴う編集や操作に苦
 - **Codex CLI**（オプション）: インストール済みで、ログインなどの初期設定が完了していること。
 - **Gemini CLI**（オプション）: インストール済みで、ログインなどの初期設定が完了していること。
 - **Forge CLI**（オプション）: インストール済みで、初期設定が完了していること。
+- **OpenCode**（オプション）: インストール済みで、設定が完了していること。この統合では `opencode run --format json` を使用し、明示的なモデル指定は `ai-cli models` が公開する `oc-<provider/model>` 構文に従います。
 
 ## インストールと使い方
 
@@ -116,9 +119,12 @@ npm install -g ai-cli-mcp
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli run --cwd "$PWD" --model opencode --prompt "OpenCode のデフォルト設定でこのリポジトリを要約して"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt "明示モデル付きでこの OpenCode セッションを続けて"
 ai-cli ps
 ai-cli result 12345
 ai-cli result 12345 --verbose
+ai-cli peek 12345 --time 10
 ai-cli wait 12345 --timeout 300
 ai-cli wait 12345 --verbose
 ai-cli kill 12345
@@ -132,6 +138,7 @@ ai-cli-mcp
 
 ```bash
 npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "OpenCode で hello"
 ```
 
 ## 重要な初回セットアップ
@@ -172,6 +179,7 @@ macOSでは、これらのツールを初めて実行する際にフォルダへ
 - `run`
 - `ps`
 - `result`
+- `peek`
 - `wait`
 - `kill`
 - `cleanup`
@@ -185,7 +193,11 @@ macOSでは、これらのツールを初めて実行する際にフォルダへ
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "この OpenCode セッションを継続して"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "明示的な OpenCode モデルで実行"
 ai-cli ps
+ai-cli peek 12345 --time 10
+ai-cli peek 12345 12346 --time 10
 ai-cli wait 12345
 ai-cli wait 12345 --verbose
 ai-cli result 12345
@@ -195,6 +207,13 @@ ai-cli cleanup
 
 `run` の作業ディレクトリ指定は `--cwd` が基本です。互換性のために `--workFolder` / `--work-folder` も受け付けます。
 
+OpenCode のモデル指定は次の 2 つを受け付けます。
+
+- `opencode`: OpenCode 側で設定されたデフォルトモデルを使用
+- `oc-<provider/model>`: 明示的な OpenCode の provider/model を指定。例: `oc-openai/gpt-5.4`
+
+`ai-cli models` は OpenCode を機械可読に `opencode: ["opencode"]` と `dynamicModelBackends.opencode` で公開します。実際に利用可能なバックエンドネイティブなモデル一覧は `opencode models` で確認してください。
+
 `doctor` は CLI バイナリの存在確認と path 解決だけを行います。ログイン状態や利用規約同意までは確認しません。
 
 ## CLI の状態保存先
@@ -210,12 +229,13 @@ ai-cli cleanup
 - `meta.json`
 - `stdout.log`
 - `stderr.log`
+- `exit-status.json`（detached な OpenCode 実行用）
 
 完了済み・失敗済みの実行は `ai-cli cleanup` で削除できます。`running` のものは保持されます。
 
 ## 既知の制約
 
-detached 実行された `ai-cli` の自然終了 exit code は、まだ永続化していません。そのため、CLI は出力と running/completed 状態は返せますが、自然終了したバックグラウンド実行の `exitCode` は現時点では保証しません。
+detached 実行された `ai-cli` では、OpenCode バックエンドに限り自然終了時の exit status を永続化します。そのため OpenCode の失敗終了は非ゼロ exit code を含めて `failed` として扱われ、結果では生の `stdout` / `stderr` を保持します。一方、他の detached バックエンドでは従来どおり、より広い exit-status 追跡が追加されるまでは自然終了した実行が信頼できる exit code なしで `completed` と見なされる制約が残ります。
 
 ## MCPクライアントへの接続
 
@@ -229,7 +249,7 @@ detached 実行された `ai-cli` の自然終了 exit code は、まだ永続
 
 ### `run`
 
-Claude CLI、Codex CLI、Gemini CLI、または Forge CLI を使用してプロンプトを実行します。モデル名に基づいて適切なCLIが自動的に選択されます。
+Claude CLI、Codex CLI、Gemini CLI、Forge CLI、または OpenCode を使用してプロンプトを実行します。モデル名に基づいて適切なCLIが自動的に選択されます。
 
 **引数:**
 - `prompt` (string, 任意): AIエージェントに送信するプロンプト。`prompt` または `prompt_file` のいずれかが必須です。
@@ -241,8 +261,9 @@ Claude CLI、Codex CLI、Gemini CLI、または Forge CLI を使用してプロ
     - 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`
     - Forge: `forge`
-- `reasoning_effort` (string, 任意): Claude と Codex の推論制御。Claude では `--effort` を使います（許容値: "low", "medium", "high"）。Codex では `model_reasoning_effort` を使います（許容値: "low", "medium", "high", "xhigh"）。Forge では `reasoning_effort` はサポートしません。
-- `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, forge。
+    - OpenCode: `opencode`（設定済みのデフォルトモデル）および `oc-openai/gpt-5.4` のような明示ラッパー
+- `reasoning_effort` (string, 任意): Claude と Codex の推論制御。Claude では `--effort` を使います（許容値: "low", "medium", "high"）。Codex では `model_reasoning_effort` を使います（許容値: "low", "medium", "high", "xhigh"）。Gemini、Forge、OpenCode では `reasoning_effort` はサポートしません。
+- `session_id` (string, 任意): 以前のセッションを再開するためのセッションID。Claude、Codex、Gemini、Forge、OpenCode でサポートされます。OpenCode は `--session` による in-place resume で再開し、`oc-<provider/model>` の明示指定と併用できます。
 
 ### `wait`
 
@@ -255,6 +276,60 @@ Claude CLI、Codex CLI、Gemini CLI、または Forge CLI を使用してプロ
 - `timeout` (number, 任意): 最大待機時間（秒）。デフォルトは180秒（3分）です。
 - `verbose` (boolean, 任意): `true` の場合、各結果項目を full 形で返します。デフォルトは `false` です。
 
+### `peek`
+
+実行中の子エージェントを短時間だけ観測し、その `peek` 呼び出しの観測ウィンドウ内で ai-cli-mcp が受理した自然言語メッセージだけを返します。履歴APIではなく、欠落のないストリーミングでもなく、シェルの `stdout` / `stderr` tail でもありません。別々の `peek` 呼び出しの間に出たメッセージは取得できない場合があります。v1 では `--follow` はありません。
+
+CLI v1:
+
+```bash
+ai-cli peek 123 --time 10
+ai-cli peek 123 456 --time 10
+```
+
+**引数:**
+- `pids` (array of numbers, 必須): `run` が返したプロセスIDを 1..32 件指定します。重複したPIDはサーバー側で重複排除され、最初に出た順序が維持されます。未知または管理外のPIDは、呼び出し全体の失敗ではなく、プロセスごとに `not_found` として返されます。
+- `peek_time_sec` (number, 任意): 観測時間（秒）の正の整数です。デフォルトは10秒、最大60秒です。`0`、負数、小数は無効です。
+
+**観測とフィルタリング:**
+- `peek_started_at` と `messages[].ts` は、ai-cli-mcp サーバー側の UTC RFC3339 タイムスタンプです。`peek_started_at` は検証とリスナー登録後に観測ウィンドウが始まった時刻、`messages[].ts` は ai-cli-mcp がメッセージを観測して受理した時刻です。
+- 観測ウィンドウは `peek_time_sec` が経過するか、対象プロセスがすべて終端状態になった時点で終了します。
+- 観測開始前のメッセージは返しません。同じPIDへの同時 `peek` は可能で、それぞれ独立した観測ウィンドウを持つため、メッセージが重複して返ることがあります。
+- 返すのは認識済みの自然言語メッセージだけです。Codex の `agent_message` text、Claude assistant の text content、OpenCode の `type: "text"` かつ `part.type` が `"text"` のイベント、Gemini stream-json の `role` が `"assistant"` の `message` イベントを含めます。raw `stdout` / `stderr`、raw JSONL、reasoning、`tool_use`、`tool_result`、コマンドの `stdout` / `stderr`、command execution メタデータ、token usage、verbose メタデータは除外します。
+- 未知のイベント形状はデフォルトで拒否します。Forge など、自然言語抽出がまだ明示対応されていない管理対象エージェントは、実際のプロセス状態を返しつつ、`messages: []`、`truncated: false`、`error: null` にします。
+- 各PIDごとに、観測ウィンドウ内で最初に観測された50件までを保持します。それ以降のメッセージを捨てた場合は `truncated` が `true` になります。
+- `status` は `running`、`completed`、`failed`、`not_found` のいずれかで、観測ウィンドウ終了時点の状態を表します。
+- `agent` は `claude`、`codex`、`gemini`、`forge`、`opencode`、将来追加される追跡済みエージェント文字列、または `null` です。`null` はプロセスが見つからない、またはエージェント種別を判断できない場合を表します。
+
+レスポンス例:
+
+```json
+{
+  "peek_started_at": "2026-04-11T12:34:56.789Z",
+  "observed_duration_sec": 10.01,
+  "processes": [
+    {
+      "pid": 123,
+      "agent": "codex",
+      "status": "running",
+      "messages": [
+        { "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." }
+      ],
+      "truncated": false,
+      "error": null
+    },
+    {
+      "pid": 999,
+      "agent": null,
+      "status": "not_found",
+      "messages": [],
+      "truncated": false,
+      "error": "process not found"
+    }
+  ]
+}
+```
+
 ### `list_processes`
 
 実行中および完了したすべてのAIエージェントプロセスを、ステータス、PID、基本情報とともにリストアップします。
@@ -311,6 +386,7 @@ npm run test:e2e
 - `CODEX_CLI_NAME`: Codex CLIのバイナリ名または絶対パスを上書き（デフォルト: `codex`）
 - `GEMINI_CLI_NAME`: Gemini CLIのバイナリ名または絶対パスを上書き（デフォルト: `gemini`）
 - `FORGE_CLI_NAME`: Forge CLIのバイナリ名または絶対パスを上書き（デフォルト: `forge`）
+- `OPENCODE_CLI_NAME`: OpenCode CLIのバイナリ名または絶対パスを上書き（デフォルト: `opencode`）
 - `MCP_CLAUDE_DEBUG`: デバッグログを有効化（`true` に設定すると詳細な出力が表示されます）
 
 **CLI名の指定方法:**
@@ -329,7 +405,8 @@ npm run test:e2e
       ],
       "env": {
         "CLAUDE_CLI_NAME": "claude-custom",
-        "CODEX_CLI_NAME": "codex-custom"
+        "CODEX_CLI_NAME": "codex-custom",
+        "OPENCODE_CLI_NAME": "opencode-custom"
       }
     },
 ```

package/README.md

@@ -7,7 +7,7 @@
 
 > **📦 Package Migration Notice**: This package was formerly `@mkxultra/claude-code-mcp` and has been renamed to `ai-cli-mcp` to reflect its expanded support for multiple AI CLI tools.
 
-An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude, Codex, Gemini, and Forge) in background processes with automatic permission handling.
+An MCP (Model Context Protocol) server that allows running AI CLI tools (Claude, Codex, Gemini, Forge, and OpenCode) in background processes with automatic permission handling.
 
 Did you notice that Cursor sometimes struggles with complex, multi-step edits or operations? This server, with its powerful unified `run` tool, enables multiple AI agents to handle your coding tasks more effectively.
 
@@ -23,7 +23,8 @@ This MCP server provides tools that can be used by LLMs to interact with AI CLI
 - Execute Codex CLI with automatic approval mode (using `--full-auto`)
 - Execute Gemini CLI with automatic approval mode (using `-y`)
 - Execute Forge CLI in non-interactive mode (using `forge -C <workFolder> -p <prompt>`)
-- 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), Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview), and Forge (`forge`)
+- Execute OpenCode in non-interactive JSON mode (using `opencode run --format json --dir <workFolder> <prompt>`)
+- 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), Gemini (gemini-2.5-pro, gemini-2.5-flash, gemini-3.1-pro-preview, gemini-3-pro-preview, gemini-3-flash-preview), Forge (`forge`), and OpenCode (`opencode` plus explicit `oc-<provider/model>` wrappers such as `oc-openai/gpt-5.4`)
 - Manage background processes with PID tracking
 - Parse and return structured outputs from both tools
 
@@ -65,6 +66,7 @@ The only prerequisite is that the AI CLI tools you want to use are locally insta
 - **Codex CLI** (Optional): Installed and initial setup (login etc.) completed.
 - **Gemini CLI** (Optional): Installed and initial setup (login etc.) completed.
 - **Forge CLI** (Optional): Installed and initial setup completed.
+- **OpenCode** (Optional): Installed and configured. This integration uses `opencode run --format json`, and explicit provider/model selection follows the `oc-<provider/model>` wrapper syntax exposed by `ai-cli models`.
 
 ## Installation & Usage
 
@@ -114,9 +116,12 @@ Examples:
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model sonnet --prompt "summarize this repository"
+ai-cli run --cwd "$PWD" --model opencode --prompt "summarize this repository with OpenCode defaults"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt "continue this session with an explicit OpenCode model"
 ai-cli ps
 ai-cli result 12345
 ai-cli result 12345 --verbose
+ai-cli peek 12345 --time 10
 ai-cli wait 12345 --timeout 300
 ai-cli wait 12345 --verbose
 ai-cli kill 12345
@@ -130,6 +135,7 @@ Because the published package name is still `ai-cli-mcp`, the shortest `npx` for
 
 ```bash
 npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model sonnet --prompt "hello"
+npx -y --package ai-cli-mcp@latest ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "hello from OpenCode"
 ```
 
 ## Important First-Time Setup
@@ -170,6 +176,7 @@ macOS might ask for folder permissions the first time any of these tools run. If
 - `run`
 - `ps`
 - `result`
+- `peek`
 - `wait`
 - `kill`
 - `cleanup`
@@ -183,7 +190,11 @@ Example flow:
 ai-cli doctor
 ai-cli models
 ai-cli run --cwd "$PWD" --model codex-ultra --prompt "fix failing tests"
+ai-cli run --cwd "$PWD" --model opencode --session-id ses_existing --prompt "continue this OpenCode session"
+ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --prompt "run with an explicit OpenCode backend model"
 ai-cli ps
+ai-cli peek 12345 --time 10
+ai-cli peek 12345 12346 --time 10
 ai-cli wait 12345
 ai-cli wait 12345 --verbose
 ai-cli result 12345
@@ -193,6 +204,13 @@ ai-cli cleanup
 
 `run` accepts `--cwd` as the primary working-directory flag and also accepts the older aliases `--workFolder` / `--work-folder` for compatibility.
 
+OpenCode model selection accepts either:
+
+- `opencode` for the CLI's configured default model
+- `oc-<provider/model>` for an explicit OpenCode provider/model, for example `oc-openai/gpt-5.4`
+
+`ai-cli models` exposes OpenCode machine-readably via `opencode: ["opencode"]` plus `dynamicModelBackends.opencode`, which points users to `opencode models` for backend-native discovery.
+
 `doctor` checks only binary existence and path resolution. It does not verify login state or terms acceptance.
 
 ## CLI State Storage
@@ -208,12 +226,13 @@ Each PID directory contains:
 - `meta.json`
 - `stdout.log`
 - `stderr.log`
+- `exit-status.json` for detached OpenCode runs
 
 Use `ai-cli cleanup` to remove completed and failed runs. Running processes are preserved.
 
 ## Known Limitation
 
-Detached `ai-cli` runs do not currently persist natural process exit codes. As a result, the CLI can report process output and running/completed state, but it does not yet guarantee `exitCode` for naturally finished background runs.
+Detached `ai-cli` runs persist natural exit status for OpenCode-backed runs, including failed exit codes used to preserve raw OpenCode stdout/stderr in result output. Other detached backends still keep the pre-existing limitation: naturally finished runs may be surfaced as completed without a reliable persisted exit code until broader exit tracking is added.
 
 ## Connecting to Your MCP Client
 
@@ -227,7 +246,7 @@ This server exposes the following tools:
 
 ### `run`
 
-Executes a prompt using Claude CLI, Codex CLI, Gemini CLI, or Forge CLI. The appropriate CLI is automatically selected based on the model name.
+Executes a prompt using Claude CLI, Codex CLI, Gemini CLI, Forge CLI, or OpenCode. The appropriate CLI is automatically selected based on the model name.
 
 **Arguments:**
 - `prompt` (string, optional): The prompt to send to the AI agent. Either `prompt` or `prompt_file` is required.
@@ -239,8 +258,9 @@ Executes a prompt using Claude CLI, Codex CLI, Gemini CLI, or Forge CLI. The app
 - 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`
 - Forge: `forge`
-- `reasoning_effort` (string, optional): Reasoning control for Claude and Codex. Claude uses `--effort` (allowed: "low", "medium", "high"). Codex uses `model_reasoning_effort` (allowed: "low", "medium", "high", "xhigh"). Forge does not support `reasoning_effort`.
-- `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, forge.
+- OpenCode: `opencode` for the configured default backend model, plus explicit wrappers like `oc-openai/gpt-5.4`
+- `reasoning_effort` (string, optional): Reasoning control for Claude and Codex. Claude uses `--effort` (allowed: "low", "medium", "high"). Codex uses `model_reasoning_effort` (allowed: "low", "medium", "high", "xhigh"). Gemini, Forge, and OpenCode do not support `reasoning_effort`.
+- `session_id` (string, optional): Optional session ID to resume a previous session. Supported for Claude, Codex, Gemini, Forge, and OpenCode. OpenCode resumes in place via `--session` and may also be combined with an explicit `oc-<provider/model>` selection.
 
 ### `wait`
 
@@ -253,6 +273,60 @@ By default, each returned result item uses the compact shape shared with `get_re
 - `timeout` (number, optional): Maximum wait time in seconds. Defaults to 180 (3 minutes).
 - `verbose` (boolean, optional): If `true`, each result item uses the full result shape. Defaults to `false`.
 
+### `peek`
+
+Starts a one-shot short observation window for running child agents and returns only natural-language agent messages observed during that specific call. It is not a history API, not gapless streaming, and not shell stdout/stderr tailing. Separate `peek` calls may miss messages emitted between calls; `--follow` is intentionally not part of v1.
+
+CLI v1:
+
+```bash
+ai-cli peek 123 --time 10
+ai-cli peek 123 456 --time 10
+```
+
+**Arguments:**
+- `pids` (array of numbers, required): 1..32 process IDs returned by `run`. Duplicate PIDs are deduplicated server-side, preserving first occurrence order. Unknown or unmanaged PIDs are returned per process as `not_found`, not as a whole-call failure.
+- `peek_time_sec` (number, optional): Positive integer observation length in seconds. Defaults to 10 and is capped at 60. `0`, negative values, and fractional values are invalid.
+
+**Observation and filtering:**
+- `peek_started_at` and `messages[].ts` are ai-cli-mcp server-side UTC RFC3339 timestamps. `peek_started_at` is when the observation window starts after validation and listener registration; `messages[].ts` is when ai-cli-mcp observed and accepted the message.
+- The window ends when `peek_time_sec` elapses or all target processes reach a terminal state, whichever comes first.
+- Messages emitted before the window starts are not returned. Concurrent `peek` calls for the same PID are allowed; each has an independent window and may return overlapping messages.
+- Only recognized natural-language agent messages are returned: Codex `agent_message` text, Claude assistant text content, OpenCode `type: "text"` events where `part.type` is `"text"`, and Gemini stream-json `message` events where `role` is `"assistant"`. Raw stdout/stderr, raw JSONL, reasoning, `tool_use`, `tool_result`, command stdout/stderr, command execution metadata, token usage, and verbose metadata are excluded.
+- Unknown event shapes are denied by default. Managed agents without supported natural-language extraction, such as Forge until explicitly supported, return their real process status with `messages: []`, `truncated: false`, and `error: null`.
+- Each PID keeps the first 50 messages observed in the window. If later messages are dropped, `truncated` is `true`.
+- `status` is one of `running`, `completed`, `failed`, or `not_found`, and reflects state when the observation window closes.
+- `agent` is `claude`, `codex`, `gemini`, `forge`, `opencode`, a future tracked string value, or `null` when the process is not found or the agent cannot be determined.
+
+Example response:
+
+```json
+{
+  "peek_started_at": "2026-04-11T12:34:56.789Z",
+  "observed_duration_sec": 10.01,
+  "processes": [
+    {
+      "pid": 123,
+      "agent": "codex",
+      "status": "running",
+      "messages": [
+        { "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." }
+      ],
+      "truncated": false,
+      "error": null
+    },
+    {
+      "pid": 999,
+      "agent": null,
+      "status": "not_found",
+      "messages": [],
+      "truncated": false,
+      "error": "process not found"
+    }
+  ]
+}
+```
+
 ### `list_processes`
 
 Lists all running and completed AI agent processes with their status, PID, and basic info.
@@ -295,6 +369,7 @@ Normally not required, but useful for customizing CLI paths or debugging.
 - `CODEX_CLI_NAME`: Override the Codex CLI binary name or provide an absolute path (default: `codex`)
 - `GEMINI_CLI_NAME`: Override the Gemini CLI binary name or provide an absolute path (default: `gemini`)
 - `FORGE_CLI_NAME`: Override the Forge CLI binary name or provide an absolute path (default: `forge`)
+- `OPENCODE_CLI_NAME`: Override the OpenCode CLI binary name or provide an absolute path (default: `opencode`)
 - `MCP_CLAUDE_DEBUG`: Enable debug logging (set to `true` for verbose output)
 
 **CLI Name Specification:**
@@ -313,7 +388,8 @@ Normally not required, but useful for customizing CLI paths or debugging.
       ],
       "env": {
         "CLAUDE_CLI_NAME": "claude-custom",
-        "CODEX_CLI_NAME": "codex-custom"
+        "CODEX_CLI_NAME": "codex-custom",
+        "OPENCODE_CLI_NAME": "opencode-custom"
       }
     },
 ```

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

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { CLI_HELP_TEXT, DOCTOR_HELP_TEXT, MODELS_HELP_TEXT, RESULT_HELP_TEXT, RUN_HELP_TEXT, WAIT_HELP_TEXT, runCli, } from '../app/cli.js';
+import { CLI_HELP_TEXT, DOCTOR_HELP_TEXT, MODELS_HELP_TEXT, PEEK_HELP_TEXT, RESULT_HELP_TEXT, RUN_HELP_TEXT, WAIT_HELP_TEXT, runCli, } from '../app/cli.js';
 describe('ai-cli app', () => {
     it('prints help and exits successfully when no subcommand is provided', async () => {
         const stdout = vi.fn();
@@ -151,6 +151,52 @@ describe('ai-cli app', () => {
         expect(stdout).toHaveBeenCalledWith(CLI_HELP_TEXT);
         expect(waitForProcesses).not.toHaveBeenCalled();
     });
+    it('dispatches peek with deduped pid arguments and time', async () => {
+        const stdout = vi.fn();
+        const stderr = vi.fn();
+        const peekProcesses = vi.fn().mockResolvedValue({
+            peek_started_at: '2026-04-11T12:34:56.789Z',
+            observed_duration_sec: 0.01,
+            processes: [],
+        });
+        const exitCode = await runCli(['peek', '123', '456', '123', '--time', '5'], {
+            stdout,
+            stderr,
+            peekProcesses,
+        });
+        expect(exitCode).toBe(0);
+        expect(peekProcesses).toHaveBeenCalledWith([123, 456], 5);
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"peek_started_at"'));
+        expect(stderr).not.toHaveBeenCalled();
+    });
+    it('defaults peek time and rejects --follow', async () => {
+        const stdout = vi.fn();
+        const stderr = vi.fn();
+        const peekProcesses = vi.fn().mockResolvedValue({
+            peek_started_at: '2026-04-11T12:34:56.789Z',
+            observed_duration_sec: 0.01,
+            processes: [],
+        });
+        const defaultExitCode = await runCli(['peek', '123'], { stdout, stderr, peekProcesses });
+        expect(defaultExitCode).toBe(0);
+        expect(peekProcesses).toHaveBeenCalledWith([123], 10);
+        const followExitCode = await runCli(['peek', '123', '--follow'], { stdout, stderr, peekProcesses });
+        expect(followExitCode).toBe(1);
+        expect(stderr).toHaveBeenCalledWith('peek does not support --follow in v1\n');
+    });
+    it('rejects invalid peek time values', async () => {
+        const stdout = vi.fn();
+        const stderr = vi.fn();
+        const peekProcesses = vi.fn();
+        const exitCode = await runCli(['peek', '123', '--time', '1.5'], {
+            stdout,
+            stderr,
+            peekProcesses,
+        });
+        expect(exitCode).toBe(1);
+        expect(stderr).toHaveBeenCalledWith(expect.stringContaining('peek_time_sec must be a positive integer'));
+        expect(peekProcesses).not.toHaveBeenCalled();
+    });
     it('dispatches ps, result, and kill', async () => {
         const stdout = vi.fn();
         const stderr = vi.fn();
@@ -180,11 +226,21 @@ describe('ai-cli app', () => {
         const stdout = vi.fn();
         const stderr = vi.fn();
         const exitCode = await runCli(['models'], { stdout, stderr });
+        const payload = JSON.parse(stdout.mock.calls[0][0]);
         expect(exitCode).toBe(0);
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"aliases"'));
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"claude-ultra"'));
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"gpt-5.4"'));
-        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"forge"'));
+        expect(payload.aliases).toEqual(expect.any(Array));
+        expect(payload.claude).toContain('sonnet');
+        expect(payload.codex).toContain('gpt-5.4');
+        expect(payload.forge).toEqual(['forge']);
+        expect(payload.opencode).toEqual(['opencode']);
+        expect(payload.dynamicModelBackends).toEqual({
+            opencode: {
+                explicitPrefix: 'oc-',
+                explicitPattern: 'oc-<provider/model>',
+                discoveryCommand: 'opencode models',
+                modelsAreDynamic: true,
+            },
+        });
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints doctor status as structured json', async () => {
@@ -215,6 +271,12 @@ describe('ai-cli app', () => {
                 available: true,
                 lookup: 'path',
             },
+            opencode: {
+                configuredCommand: 'opencode',
+                resolvedPath: '/tmp/bin/opencode',
+                available: true,
+                lookup: 'path',
+            },
         });
         const exitCode = await runCli(['doctor'], { stdout, stderr, getDoctorStatus });
         expect(exitCode).toBe(0);
@@ -241,6 +303,8 @@ describe('ai-cli app', () => {
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('gpt-5.2-codex'));
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('gemini-2.5-pro'));
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('forge'));
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('opencode'));
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('oc-openai/gpt-5.4'));
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints detailed help for result --help', async () => {
@@ -263,6 +327,15 @@ describe('ai-cli app', () => {
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('--verbose'));
         expect(stderr).not.toHaveBeenCalled();
     });
+    it('prints detailed help for peek --help', async () => {
+        const stdout = vi.fn();
+        const stderr = vi.fn();
+        const exitCode = await runCli(['peek', '--help'], { stdout, stderr });
+        expect(exitCode).toBe(0);
+        expect(stdout).toHaveBeenCalledWith(PEEK_HELP_TEXT);
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('No --follow mode'));
+        expect(stderr).not.toHaveBeenCalled();
+    });
     it('prints detailed help for models --help', async () => {
         const stdout = vi.fn();
         const stderr = vi.fn();
@@ -277,6 +350,7 @@ describe('ai-cli app', () => {
         const exitCode = await runCli(['doctor', '--help'], { stdout, stderr });
         expect(exitCode).toBe(0);
         expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('OpenCode'));
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints detailed help for doctor -h', async () => {
@@ -285,6 +359,7 @@ describe('ai-cli app', () => {
         const exitCode = await runCli(['doctor', '-h'], { stdout, stderr });
         expect(exitCode).toBe(0);
         expect(stdout).toHaveBeenCalledWith(DOCTOR_HELP_TEXT);
+        expect(stdout).toHaveBeenCalledWith(expect.stringContaining('OpenCode'));
         expect(stderr).not.toHaveBeenCalled();
     });
     it('prints help for --help', async () => {