ai-cli-mcp 2.15.0 → 2.16.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [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)
 
 

package/README.ja.md

@@ -124,6 +124,7 @@ ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt
 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
@@ -178,6 +179,7 @@ macOSでは、これらのツールを初めて実行する際にフォルダへ
 - `run`
 - `ps`
 - `result`
+- `peek`
 - `wait`
 - `kill`
 - `cleanup`
@@ -194,6 +196,8 @@ 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
@@ -272,6 +276,60 @@ Claude CLI、Codex CLI、Gemini CLI、Forge CLI、または OpenCode を使用
 - `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、基本情報とともにリストアップします。

package/README.md

@@ -121,6 +121,7 @@ ai-cli run --cwd "$PWD" --model oc-openai/gpt-5.4 --session-id ses_123 --prompt
 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
@@ -175,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`
@@ -191,6 +193,8 @@ 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
@@ -269,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.

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();
@@ -281,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();

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

@@ -305,7 +305,7 @@ describe('cli-builder', () => {
                 expect(cmd.cliPath).toBe('/usr/bin/gemini');
                 expect(cmd.args).toContain('-y');
                 expect(cmd.args).toContain('--output-format');
-                expect(cmd.args).toContain('json');
+                expect(cmd.args).toContain('stream-json');
                 expect(cmd.args).toContain('--model');
                 expect(cmd.args).toContain('gemini-2.5-pro');
             });

package/dist/__tests__/cli-process-service.test.js

@@ -107,6 +107,65 @@ describe('CliProcessService', () => {
         expect(result).not.toHaveProperty('prompt');
         expect(readFileSync(join(processDir, 'meta.json'), 'utf-8')).toContain('"status": "completed"');
     });
+    it('peeks only appended natural-language messages from detached logs', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'ai-cli-cli-service-'));
+        tempDirs.push(root);
+        const scriptPath = join(root, 'mock-claude-peek');
+        writeFileSync(scriptPath, `#!/bin/bash
+printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"old cli message"}]}}'
+sleep 2
+printf '%s\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"new cli message"},{"type":"tool_use","id":"tool-1","name":"Read","input":{"file_path":"/tmp/a"}}]}}'
+printf '%s\n' '{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"tool-1","content":"secret"}]}}'
+`);
+        chmodSync(scriptPath, 0o755);
+        const stateDir = join(root, 'state');
+        const workFolder = join(root, 'work');
+        mkdirSync(workFolder, { recursive: true });
+        const service = new CliProcessService({
+            stateDir,
+            cliPaths: {
+                claude: scriptPath,
+                codex: scriptPath,
+                gemini: scriptPath,
+                forge: scriptPath,
+                opencode: scriptPath,
+            },
+        });
+        const runResult = await service.startProcess({
+            prompt: 'hello peek',
+            cwd: workFolder,
+        });
+        const processDir = join(stateDir, 'cwds', encodeCwd(realpathSync(workFolder)), String(runResult.pid));
+        const stdoutPath = join(processDir, 'stdout.log');
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < 5000 && !readFileSync(stdoutPath, 'utf-8').includes('old cli message')) {
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        expect(readFileSync(stdoutPath, 'utf-8')).toContain('old cli message');
+        const peekResult = await service.peekProcesses([runResult.pid, runResult.pid, 999999], 3);
+        expect(peekResult.processes).toHaveLength(2);
+        expect(peekResult.processes[0]).toMatchObject({
+            pid: runResult.pid,
+            agent: 'claude',
+            status: 'completed',
+            messages: [
+                {
+                    ts: expect.any(String),
+                    text: 'new cli message',
+                },
+            ],
+            truncated: false,
+            error: null,
+        });
+        expect(peekResult.processes[1]).toEqual({
+            pid: 999999,
+            agent: null,
+            status: 'not_found',
+            messages: [],
+            truncated: false,
+            error: 'process not found',
+        });
+    });
     it('returns compact results by default and full results when verbose is true', async () => {
         const root = mkdtempSync(join(tmpdir(), 'ai-cli-cli-service-'));
         tempDirs.push(root);

package/dist/__tests__/e2e.test.js

@@ -29,7 +29,7 @@ describe('Claude Code MCP E2E Tests', () => {
     describe('Tool Registration', () => {
         it('should register run tool', async () => {
             const tools = await client.listTools();
-            expect(tools).toHaveLength(6);
+            expect(tools).toHaveLength(7);
             const claudeCodeTool = tools.find((t) => t.name === 'run');
             expect(claudeCodeTool.inputSchema.properties.model.description).toContain('sonnet');
             expect(claudeCodeTool.inputSchema.properties.model.description).toContain('opencode');
@@ -38,6 +38,7 @@ describe('Claude Code MCP E2E Tests', () => {
             // Verify other tools exist
             expect(tools.some((t) => t.name === 'list_processes')).toBe(true);
             expect(tools.some((t) => t.name === 'get_result')).toBe(true);
+            expect(tools.some((t) => t.name === 'peek')).toBe(true);
             expect(tools.some((t) => t.name === 'kill_process')).toBe(true);
         });
     });

package/dist/__tests__/mcp-contract.test.js

@@ -84,6 +84,7 @@ describe('MCP Contract Tests', () => {
             'get_result',
             'kill_process',
             'list_processes',
+            'peek',
             'run',
             'wait',
         ]);
@@ -115,6 +116,13 @@ describe('MCP Contract Tests', () => {
             'timeout',
             'verbose',
         ]);
+        const peekTool = tools.find((tool) => tool.name === 'peek');
+        expect(peekTool.inputSchema.required).toEqual(['pids']);
+        expect(Object.keys(peekTool.inputSchema.properties).sort()).toEqual([
+            'peek_time_sec',
+            'pids',
+        ]);
+        expect(peekTool.description).toContain('One-shot');
     });
     it('preserves the stdio MCP smoke flow and response shapes', async () => {
         const runResponse = await client.callTool('run', {

package/dist/__tests__/parsers.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseCodexOutput, parseClaudeOutput, parseForgeOutput, parseOpenCodeOutput } from '../parsers.js';
+import { parseCodexOutput, parseClaudeOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekMessageExtractor } from '../parsers.js';
 describe('parseCodexOutput', () => {
     it('should parse basic Codex output with message and session_id', () => {
         const output = `
@@ -58,6 +58,168 @@ INVALID_JSON
         expect(result.message).toBe("Still parses valid lines");
     });
 });
+describe('PeekMessageExtractor', () => {
+    const ts = '2026-04-11T12:34:56.789Z';
+    it('extracts only Codex agent_message text', () => {
+        const extractor = new PeekMessageExtractor('codex');
+        const output = [
+            '{"type":"item.completed","item":{"type":"reasoning","text":"hidden"}}',
+            '{"type":"item.completed","item":{"type":"command_execution","aggregated_output":"secret command output"}}',
+            '{"type":"item.completed","item":{"type":"agent_message","text":"Visible Codex message"}}',
+            '{"msg":{"type":"token_count","total":123}}',
+            '{"msg":{"type":"agent_message","message":"Visible legacy Codex message"}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            { ts, text: 'Visible Codex message' },
+            { ts, text: 'Visible legacy Codex message' },
+        ]);
+    });
+    it('extracts only Claude assistant text content', () => {
+        const extractor = new PeekMessageExtractor('claude');
+        const output = [
+            '{"type":"assistant","message":{"content":[{"type":"text","text":"Visible Claude text"},{"type":"tool_use","id":"tool-1","name":"Read","input":{"file_path":"/tmp/a"}}]}}',
+            '{"type":"user","message":{"content":[{"type":"tool_result","tool_use_id":"tool-1","content":"secret"}]}}',
+            '{"type":"result","result":"Final result is not peek assistant text"}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            { ts, text: 'Visible Claude text' },
+        ]);
+    });
+    it('extracts only Gemini assistant message content', () => {
+        const extractor = new PeekMessageExtractor('gemini');
+        const output = [
+            '{"type":"message","timestamp":"2026-04-11T14:44:42.294Z","role":"user","content":"hidden user text"}',
+            '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Visible Gemini text","delta":true}',
+            '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.821Z","tool_name":"run_shell_command","parameters":{"command":"echo secret"}}',
+            '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","status":"success","output":"secret command output"}',
+            '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Final result is not peek assistant text"}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            { ts, text: 'Visible Gemini text' },
+        ]);
+    });
+    it('joins split Gemini assistant chunks into one peek message on flush', () => {
+        const extractor = new PeekMessageExtractor('gemini');
+        const output = [
+            '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Step 2 done. Starting step ","delta":true}',
+            '{"type":"message","timestamp":"2026-04-11T14:44:53.821Z","role":"assistant","content":"3.","delta":true}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([]);
+        expect(extractor.flush('2026-04-11T12:34:59.000Z')).toEqual([
+            { ts: '2026-04-11T12:34:59.000Z', text: 'Step 2 done. Starting step 3.' },
+        ]);
+    });
+    it('emits separate Gemini peek messages when a boundary separates logical messages', () => {
+        const extractor = new PeekMessageExtractor('gemini');
+        const output = [
+            '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Starting step ","delta":true}',
+            '{"type":"message","timestamp":"2026-04-11T14:44:53.821Z","role":"assistant","content":"1.","delta":true}',
+            '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.822Z","tool_name":"run_shell_command","parameters":{"command":"echo secret"}}',
+            '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","status":"success","output":"secret command output"}',
+            '{"type":"message","timestamp":"2026-04-11T14:45:10.315Z","role":"assistant","content":"Final ","delta":true}',
+            '{"type":"message","timestamp":"2026-04-11T14:45:10.316Z","role":"assistant","content":"answer.","delta":true}',
+            '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Final result response is not peek text","stats":{"total_tokens":21999}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            { ts, text: 'Starting step 1.' },
+            { ts, text: 'Final answer.' },
+        ]);
+        expect(extractor.flush(ts)).toEqual([]);
+    });
+    it('does not emit Gemini user, tool, tool result, stats, or result response text', () => {
+        const extractor = new PeekMessageExtractor('gemini');
+        const output = [
+            '{"type":"message","timestamp":"2026-04-11T14:44:42.294Z","role":"user","content":"hidden user text"}',
+            '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.821Z","tool_name":"run_shell_command","parameters":{"command":"echo secret"}}',
+            '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","status":"success","output":"secret command output"}',
+            '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Final result response is not peek text","stats":{"total_tokens":21999}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([]);
+        expect(extractor.flush(ts)).toEqual([]);
+    });
+    it('denies unsupported agents and invalid shapes by default', () => {
+        const extractor = new PeekMessageExtractor('forge');
+        const output = [
+            '{"type":"assistant","message":{"content":[{"type":"text","text":"not supported here"}]}}',
+            '{"type":"item.completed","item":{"type":"agent_message","text":"not supported here"}}',
+            '{"type":"text","part":{"type":"text","text":"not supported here"}}',
+            '{"type":"message","role":"assistant","content":"not supported here"}',
+            'plain stdout',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([]);
+    });
+    it('extracts only OpenCode natural-language text events', () => {
+        const extractor = new PeekMessageExtractor('opencode');
+        const output = [
+            '{"type":"text","timestamp":1775918783605,"sessionID":"ses-1","part":{"type":"text","text":"OpenCode visible text"}}',
+            '{"type":"tool_use","timestamp":1775918783606,"sessionID":"ses-1","part":{"type":"tool","state":{"output":"secret command output"},"metadata":{"output":"secret metadata output"}}}',
+            '{"type":"text","timestamp":1775918783607,"sessionID":"ses-1","part":{"type":"tool","text":"wrong part type"}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            { ts, text: 'OpenCode visible text' },
+        ]);
+    });
+    it('can flush a complete JSON event without a trailing newline', () => {
+        const extractor = new PeekMessageExtractor('codex');
+        expect(extractor.push('{"type":"item.completed","item":{"type":"agent_message","text":"pending"}}', ts)).toEqual([]);
+        expect(extractor.flush(ts)).toEqual([{ ts, text: 'pending' }]);
+    });
+});
+describe('parseGeminiOutput', () => {
+    it('should parse legacy final JSON output', () => {
+        const output = JSON.stringify({
+            session_id: 'gemini-session-json',
+            response: 'Legacy Gemini final response',
+            stats: {
+                total_tokens: 123,
+            },
+        });
+        expect(parseGeminiOutput(output)).toEqual({
+            session_id: 'gemini-session-json',
+            response: 'Legacy Gemini final response',
+            stats: {
+                total_tokens: 123,
+            },
+        });
+    });
+    it('should normalize a single-line Gemini assistant stream event', () => {
+        const output = '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"Only answer","delta":true}';
+        const result = parseGeminiOutput(output);
+        expect(result).toMatchObject({
+            message: 'Only answer',
+            session_id: null,
+        });
+        expect(result).not.toHaveProperty('type');
+        expect(result).not.toHaveProperty('content');
+    });
+    it('should parse Gemini stream-json NDJSON output', () => {
+        const output = [
+            '{"type":"init","timestamp":"2026-04-11T14:44:42.293Z","session_id":"gemini-session-stream","model":"gemini-3.1-pro-preview"}',
+            '{"type":"message","timestamp":"2026-04-11T14:44:42.294Z","role":"user","content":"hidden user text"}',
+            '{"type":"message","timestamp":"2026-04-11T14:44:53.820Z","role":"assistant","content":"First logical assistant response.","delta":true}',
+            '{"type":"tool_use","timestamp":"2026-04-11T14:44:53.821Z","tool_name":"run_shell_command","tool_id":"tool-1","parameters":{"command":"echo hidden"}}',
+            '{"type":"tool_result","timestamp":"2026-04-11T14:45:03.011Z","tool_id":"tool-1","status":"success","output":"hidden command output"}',
+            '{"type":"message","timestamp":"2026-04-11T14:45:10.315Z","role":"assistant","content":"Final assistant ","delta":true}',
+            '{"type":"message","timestamp":"2026-04-11T14:45:10.316Z","role":"assistant","content":"response.","delta":true}',
+            '{"type":"result","timestamp":"2026-04-11T14:45:10.380Z","status":"success","response":"Result response is not the parsed message","stats":{"total_tokens":21999}}',
+        ].join('\n') + '\n';
+        expect(parseGeminiOutput(output)).toEqual({
+            message: 'Final assistant response.',
+            session_id: 'gemini-session-stream',
+            stats: {
+                total_tokens: 21999,
+            },
+            tools: [
+                {
+                    tool: 'run_shell_command',
+                    input: { command: 'echo hidden' },
+                    output: 'hidden command output',
+                    status: 'success',
+                },
+            ],
+        });
+    });
+});
 describe('parseClaudeOutput', () => {
     it('should parse legacy JSON output', () => {
         const output = JSON.stringify({

package/dist/__tests__/peek.test.js

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { appendPeekMessages, validatePeekPids, validatePeekTimeSec } from '../peek.js';
+describe('peek helpers', () => {
+    it('dedupes pids while preserving first occurrence order', () => {
+        expect(validatePeekPids([3, 1, 3, 2, 1])).toEqual([3, 1, 2]);
+    });
+    it('validates pid and time limits', () => {
+        expect(() => validatePeekPids([])).toThrow(/1..32/);
+        expect(() => validatePeekPids([1.5])).toThrow(/positive safe integers/);
+        expect(() => validatePeekPids([Number.MAX_SAFE_INTEGER + 1])).toThrow(/positive safe integers/);
+        expect(validatePeekTimeSec(undefined)).toBe(10);
+        expect(validatePeekTimeSec(60)).toBe(60);
+        expect(() => validatePeekTimeSec(0)).toThrow(/positive integer/);
+        expect(() => validatePeekTimeSec(1.5)).toThrow(/positive integer/);
+        expect(() => validatePeekTimeSec(61)).toThrow(/positive integer/);
+    });
+    it('keeps the first 50 messages and marks truncation when later messages are dropped', () => {
+        const process = {
+            pid: 123,
+            agent: 'codex',
+            status: 'running',
+            messages: [],
+            truncated: false,
+            error: null,
+        };
+        appendPeekMessages(process, Array.from({ length: 55 }, (_, index) => ({
+            ts: '2026-04-11T12:34:56.789Z',
+            text: `message ${index}`,
+        })));
+        expect(process.messages).toHaveLength(50);
+        expect(process.messages[0].text).toBe('message 0');
+        expect(process.messages[49].text).toBe('message 49');
+        expect(process.truncated).toBe(true);
+    });
+});