ai-cli-mcp 2.17.0 → 2.18.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.18.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.17.0...v2.18.0) (2026-04-12)
+
+
+### Features
+
+* peekコマンドにtool_callイベントサポートを追加 ([c05b916](https://github.com/mkXultra/ai-cli-mcp/commit/c05b91677019714077d0803c4169a0b5205ff25f))
+
 # [2.17.0](https://github.com/mkXultra/ai-cli-mcp/compare/v2.16.0...v2.17.0) (2026-04-11)
 
 

package/README.ja.md

@@ -278,26 +278,29 @@ Claude CLI、Codex CLI、Gemini CLI、Forge CLI、または OpenCode を使用
 
 ### `peek`
 
-実行中の子エージェントを短時間だけ観測し、その `peek` 呼び出しの観測ウィンドウ内で ai-cli-mcp が受理した自然言語メッセージだけを返します。履歴APIではなく、欠落のないストリーミングでもなく、シェルの `stdout` / `stderr` tail でもありません。別々の `peek` 呼び出しの間に出たメッセージは取得できない場合があります。v1 では `--follow` はありません。
+実行中の子エージェントを短時間だけ観測し、その `peek` 呼び出しの観測ウィンドウ内で ai-cli-mcp が受理した構造化イベントを返します。デフォルトでは自然言語メッセージイベントだけを返し、`include_tool_calls` または `--include-tool-calls` を指定すると正規化された tool-call イベントも含めます。履歴APIではなく、欠落のないストリーミングでもなく、シェルの `stdout` / `stderr` tail でもありません。別々の `peek` 呼び出しの間に出たイベントは取得できない場合があります。v1 では `--follow` はありません。
 
 CLI v1:
 
 ```bash
 ai-cli peek 123 --time 10
 ai-cli peek 123 456 --time 10
+ai-cli peek 123 --time 10 --include-tool-calls
 ```
 
 **引数:**
 - `pids` (array of numbers, 必須): `run` が返したプロセスIDを 1..32 件指定します。重複したPIDはサーバー側で重複排除され、最初に出た順序が維持されます。未知または管理外のPIDは、呼び出し全体の失敗ではなく、プロセスごとに `not_found` として返されます。
 - `peek_time_sec` (number, 任意): 観測時間（秒）の正の整数です。デフォルトは10秒、最大60秒です。`0`、負数、小数は無効です。
+- `include_tool_calls` (boolean, 任意): `true` の場合、各プロセスの `events` 配列にメッセージイベントに加えて正規化された `tool_call` イベントを含めます。デフォルトは `false` です。
 
 **観測とフィルタリング:**
-- `peek_started_at` と `messages[].ts` は、ai-cli-mcp サーバー側の UTC RFC3339 タイムスタンプです。`peek_started_at` は検証とリスナー登録後に観測ウィンドウが始まった時刻、`messages[].ts` は ai-cli-mcp がメッセージを観測して受理した時刻です。
+- `peek_started_at` と `events[].ts` は、ai-cli-mcp サーバー側の UTC RFC3339 タイムスタンプです。`peek_started_at` は検証とリスナー登録後に観測ウィンドウが始まった時刻、`events[].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` になります。
+- 観測開始前のイベントは返しません。同じPIDへの同時 `peek` は可能で、それぞれ独立した観測ウィンドウを持つため、イベントが重複して返ることがあります。
+- メッセージイベントは、Codex の `agent_message` text、Claude assistant の text content、OpenCode の `type: "text"` かつ `part.type` が `"text"` のイベント、Gemini stream-json の `role` が `"assistant"` の `message` イベントから認識します。
+- tool call を含める場合、Codex の command/MCP call、Claude の tool use/result、Gemini の tool use/result、OpenCode の完了済み tool use event を正規化した `tool_call` イベントとして返します。tool summary は tool 名と入力メタデータだけから作る短い1行文字列です。raw `stdout` / `stderr`、raw JSONL、tool result output、コマンド出力、`result.response`、stats、token usage、verbose メタデータは除外します。
+- 未知のイベント形状はデフォルトで拒否します。Forge など、まだ明示対応されていない管理対象エージェントは、実際のプロセス状態を返しつつ、`events: []`、`truncated: false`、`error: null` にします。
+- 各PIDごとに、観測ウィンドウ内で最初に観測された50件までを保持します。それ以降のイベントを捨てた場合は `truncated` が `true` になります。
 - `status` は `running`、`completed`、`failed`、`not_found` のいずれかで、観測ウィンドウ終了時点の状態を表します。
 - `agent` は `claude`、`codex`、`gemini`、`forge`、`opencode`、将来追加される追跡済みエージェント文字列、または `null` です。`null` はプロセスが見つからない、またはエージェント種別を判断できない場合を表します。
 
@@ -312,8 +315,9 @@ ai-cli peek 123 456 --time 10
       "pid": 123,
       "agent": "codex",
       "status": "running",
-      "messages": [
-        { "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." }
+      "events": [
+        { "kind": "message", "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." },
+        { "kind": "tool_call", "ts": "2026-04-11T12:35:00.000Z", "phase": "started", "id": "item_0", "tool": "command_execution", "summary": "/bin/sh -c 'echo hi'" }
       ],
       "truncated": false,
       "error": null
@@ -322,7 +326,7 @@ ai-cli peek 123 456 --time 10
       "pid": 999,
       "agent": null,
       "status": "not_found",
-      "messages": [],
+      "events": [],
       "truncated": false,
       "error": "process not found"
     }

package/README.md

@@ -275,26 +275,29 @@ By default, each returned result item uses the compact shape shared with `get_re
 
 ### `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.
+Starts a one-shot short observation window for running child agents and returns structured events observed during that specific call. By default this includes only natural-language message events; pass `include_tool_calls` or `--include-tool-calls` to also include normalized tool-call events. It is not a history API, not gapless streaming, and not shell stdout/stderr tailing. Separate `peek` calls may miss events 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
+ai-cli peek 123 --time 10 --include-tool-calls
 ```
 
 **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.
+- `include_tool_calls` (boolean, optional): When `true`, each process `events` array includes normalized `tool_call` events in addition to message events. Defaults to `false`.
 
 **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.
+- `peek_started_at` and `events[].ts` are ai-cli-mcp server-side UTC RFC3339 timestamps. `peek_started_at` is when the observation window starts after validation and listener registration; `events[].ts` is when ai-cli-mcp observed and accepted the event.
 - 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`.
+- Events 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 events.
+- Message events are recognized from 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"`.
+- When tool calls are included, `tool_call` events are normalized for Codex command/MCP calls, Claude tool use/results, Gemini tool use/results, and OpenCode completed tool use events. Tool summaries are bounded one-line strings derived from tool names and input metadata only. Raw stdout/stderr, raw JSONL, tool result output, command output, `result.response`, stats, token usage, and verbose metadata are excluded.
+- Unknown event shapes are denied by default. Managed agents without supported extraction, such as Forge until explicitly supported, return their real process status with `events: []`, `truncated: false`, and `error: null`.
+- Each PID keeps the first 50 events observed in the window. If later events 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.
 
@@ -309,8 +312,9 @@ Example response:
       "pid": 123,
       "agent": "codex",
       "status": "running",
-      "messages": [
-        { "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." }
+      "events": [
+        { "kind": "message", "ts": "2026-04-11T12:34:59.120Z", "text": "I'm checking the implementation." },
+        { "kind": "tool_call", "ts": "2026-04-11T12:35:00.000Z", "phase": "started", "id": "item_0", "tool": "command_execution", "summary": "/bin/sh -c 'echo hi'" }
       ],
       "truncated": false,
       "error": null
@@ -319,7 +323,7 @@ Example response:
       "pid": 999,
       "agent": null,
       "status": "not_found",
-      "messages": [],
+      "events": [],
       "truncated": false,
       "error": "process not found"
     }

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

@@ -159,13 +159,13 @@ describe('ai-cli app', () => {
             observed_duration_sec: 0.01,
             processes: [],
         });
-        const exitCode = await runCli(['peek', '123', '456', '123', '--time', '5'], {
+        const exitCode = await runCli(['peek', '123', '456', '123', '--time', '5', '--include-tool-calls'], {
             stdout,
             stderr,
             peekProcesses,
         });
         expect(exitCode).toBe(0);
-        expect(peekProcesses).toHaveBeenCalledWith([123, 456], 5);
+        expect(peekProcesses).toHaveBeenCalledWith([123, 456], 5, true);
         expect(stdout).toHaveBeenCalledWith(expect.stringContaining('"peek_started_at"'));
         expect(stderr).not.toHaveBeenCalled();
     });
@@ -179,7 +179,7 @@ describe('ai-cli app', () => {
         });
         const defaultExitCode = await runCli(['peek', '123'], { stdout, stderr, peekProcesses });
         expect(defaultExitCode).toBe(0);
-        expect(peekProcesses).toHaveBeenCalledWith([123], 10);
+        expect(peekProcesses).toHaveBeenCalledWith([123], 10, false);
         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');

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

@@ -148,8 +148,9 @@ printf '%s\n' '{"type":"user","message":{"content":[{"type":"tool_result","tool_
             pid: runResult.pid,
             agent: 'claude',
             status: 'completed',
-            messages: [
+            events: [
                 {
+                    kind: 'message',
                     ts: expect.any(String),
                     text: 'new cli message',
                 },
@@ -161,7 +162,7 @@ printf '%s\n' '{"type":"user","message":{"content":[{"type":"tool_result","tool_
             pid: 999999,
             agent: null,
             status: 'not_found',
-            messages: [],
+            events: [],
             truncated: false,
             error: 'process not found',
         });

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

@@ -119,6 +119,7 @@ describe('MCP Contract Tests', () => {
         const peekTool = tools.find((tool) => tool.name === 'peek');
         expect(peekTool.inputSchema.required).toEqual(['pids']);
         expect(Object.keys(peekTool.inputSchema.properties).sort()).toEqual([
+            'include_tool_calls',
             'peek_time_sec',
             'pids',
         ]);

package/dist/__tests__/parsers.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseCodexOutput, parseClaudeOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekMessageExtractor } from '../parsers.js';
+import { parseCodexOutput, parseClaudeOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekEventExtractor, PeekMessageExtractor } from '../parsers.js';
 describe('parseCodexOutput', () => {
     it('should parse basic Codex output with message and session_id', () => {
         const output = `
@@ -165,6 +165,149 @@ describe('PeekMessageExtractor', () => {
         expect(extractor.flush(ts)).toEqual([{ ts, text: 'pending' }]);
     });
 });
+describe('PeekEventExtractor', () => {
+    const ts = '2026-04-12T02:10:00.000Z';
+    it('emits only message events when include_tool_calls is false', () => {
+        const extractor = new PeekEventExtractor('codex', { includeToolCalls: false });
+        const output = [
+            '{"type":"item.started","item":{"id":"item_0","type":"command_execution","command":"echo secret","status":"in_progress"}}',
+            '{"type":"item.completed","item":{"id":"item_0","type":"command_execution","command":"echo secret","aggregated_output":"secret output\\n","exit_code":0,"status":"completed"}}',
+            '{"type":"item.completed","item":{"id":"item_1","type":"agent_message","text":"Visible Codex message"}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            { kind: 'message', ts, text: 'Visible Codex message' },
+        ]);
+    });
+    it('emits Codex command and MCP tool_call events without raw output when include_tool_calls is true', () => {
+        const extractor = new PeekEventExtractor('codex', { includeToolCalls: true });
+        const output = [
+            '{"type":"item.started","item":{"id":"cmd_0","type":"command_execution","command":"/bin/sh -c \\"echo secret\\"","status":"in_progress"}}',
+            '{"type":"item.completed","item":{"id":"cmd_0","type":"command_execution","command":"/bin/sh -c \\"echo secret\\"","aggregated_output":"secret output\\n","exit_code":0,"status":"completed"}}',
+            '{"type":"item.started","item":{"id":"mcp_0","type":"mcp_tool_call","server":"acm","tool":"list_processes","arguments":{},"status":"in_progress"}}',
+            '{"type":"item.completed","item":{"id":"mcp_0","type":"mcp_tool_call","server":"acm","tool":"list_processes","arguments":{},"result":{"content":[{"type":"text","text":"secret result"}]},"status":"completed"}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'started',
+                id: 'cmd_0',
+                tool: 'command_execution',
+                summary: '/bin/sh -c "echo secret"',
+            },
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'completed',
+                id: 'cmd_0',
+                tool: 'command_execution',
+                summary: '/bin/sh -c "echo secret"',
+                status: 'success',
+                exit_code: 0,
+            },
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'started',
+                id: 'mcp_0',
+                tool: 'list_processes',
+                server: 'acm',
+                summary: 'acm.list_processes',
+            },
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'completed',
+                id: 'mcp_0',
+                tool: 'list_processes',
+                server: 'acm',
+                summary: 'acm.list_processes',
+                status: 'success',
+            },
+        ]);
+    });
+    it('emits Claude MCP tool_call events paired by id', () => {
+        const extractor = new PeekEventExtractor('claude', { includeToolCalls: true });
+        const output = [
+            '{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_1","name":"mcp__acm__list_processes","input":{}}]}}',
+            '{"type":"user","message":{"content":[{"tool_use_id":"toolu_1","type":"tool_result","content":[{"type":"text","text":"secret result"}]}]}}',
+            '{"type":"assistant","message":{"content":[{"type":"text","text":"Done."}]}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'started',
+                id: 'toolu_1',
+                tool: 'mcp__acm__list_processes',
+                server: 'acm',
+                summary: 'acm.list_processes',
+            },
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'completed',
+                id: 'toolu_1',
+                tool: 'mcp__acm__list_processes',
+                server: 'acm',
+                summary: 'acm.list_processes',
+                status: 'success',
+            },
+            { kind: 'message', ts, text: 'Done.' },
+        ]);
+    });
+    it('emits Gemini MCP tool_call events and joined assistant message events', () => {
+        const extractor = new PeekEventExtractor('gemini', { includeToolCalls: true });
+        const output = [
+            '{"type":"tool_use","timestamp":"2026-04-12T02:56:29.992Z","tool_name":"mcp_acm_list_processes","tool_id":"mcp_1","parameters":{}}',
+            '{"type":"tool_result","timestamp":"2026-04-12T02:56:30.059Z","tool_id":"mcp_1","status":"success","output":"secret result"}',
+            '{"type":"message","timestamp":"2026-04-12T02:56:32.855Z","role":"assistant","content":"The tool ","delta":true}',
+            '{"type":"message","timestamp":"2026-04-12T02:56:32.902Z","role":"assistant","content":"succeeded.","delta":true}',
+            '{"type":"result","timestamp":"2026-04-12T02:56:32.954Z","status":"success","stats":{"tool_calls":1}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'started',
+                id: 'mcp_1',
+                tool: 'mcp_acm_list_processes',
+                server: 'acm',
+                summary: 'acm.list_processes',
+            },
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'completed',
+                id: 'mcp_1',
+                tool: 'mcp_acm_list_processes',
+                server: 'acm',
+                summary: 'acm.list_processes',
+                status: 'success',
+            },
+            { kind: 'message', ts, text: 'The tool succeeded.' },
+        ]);
+    });
+    it('emits OpenCode completed MCP tool_call events from tool_use state', () => {
+        const extractor = new PeekEventExtractor('opencode', { includeToolCalls: true });
+        const output = [
+            '{"type":"tool_use","timestamp":1775962663837,"sessionID":"ses-1","part":{"id":"part-1","type":"tool","tool":"acm_list_processes","callID":"call_1","state":{"status":"completed","input":{},"output":"secret result","metadata":{"truncated":false},"time":{"start":1775962663834,"end":1775962663837}}}}',
+        ].join('\n') + '\n';
+        expect(extractor.push(output, ts)).toEqual([
+            {
+                kind: 'tool_call',
+                ts,
+                phase: 'completed',
+                id: 'call_1',
+                tool: 'acm_list_processes',
+                server: 'acm',
+                summary: 'acm.list_processes',
+                status: 'success',
+                duration_ms: 3,
+            },
+        ]);
+    });
+});
 describe('parseGeminiOutput', () => {
     it('should parse legacy final JSON output', () => {
         const output = JSON.stringify({

package/dist/__tests__/peek.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { appendPeekMessages, validatePeekPids, validatePeekTimeSec } from '../peek.js';
+import { appendPeekEvents, 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]);
@@ -14,22 +14,23 @@ describe('peek helpers', () => {
         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', () => {
+    it('keeps the first 50 events and marks truncation when later events are dropped', () => {
         const process = {
             pid: 123,
             agent: 'codex',
             status: 'running',
-            messages: [],
+            events: [],
             truncated: false,
             error: null,
         };
-        appendPeekMessages(process, Array.from({ length: 55 }, (_, index) => ({
+        appendPeekEvents(process, Array.from({ length: 55 }, (_, index) => ({
+            kind: 'message',
             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.events).toHaveLength(50);
+        expect(process.events[0]).toMatchObject({ kind: 'message', text: 'message 0' });
+        expect(process.events[49]).toMatchObject({ kind: 'message', text: 'message 49' });
         expect(process.truncated).toBe(true);
     });
 });

package/dist/__tests__/process-management.test.js

@@ -141,8 +141,9 @@ describe('Process Management Tests', () => {
                 pid: 12345,
                 agent: 'claude',
                 status: 'completed',
-                messages: [
+                events: [
                     {
+                        kind: 'message',
                         ts: expect.any(String),
                         text: 'new message',
                     },
@@ -154,7 +155,7 @@ describe('Process Management Tests', () => {
                 pid: 99999,
                 agent: null,
                 status: 'not_found',
-                messages: [],
+                events: [],
                 truncated: false,
                 error: 'process not found',
             });
@@ -199,8 +200,9 @@ describe('Process Management Tests', () => {
                 pid: 12346,
                 agent: 'opencode',
                 status: 'completed',
-                messages: [
+                events: [
                     {
+                        kind: 'message',
                         ts: expect.any(String),
                         text: 'OpenCode visible text',
                     },
@@ -250,8 +252,9 @@ describe('Process Management Tests', () => {
                 pid: 12347,
                 agent: 'gemini',
                 status: 'completed',
-                messages: [
+                events: [
                     {
+                        kind: 'message',
                         ts: expect.any(String),
                         text: 'Visible Gemini text',
                     },
@@ -260,6 +263,77 @@ describe('Process Management Tests', () => {
                 error: null,
             });
         });
+        it('should include normalized tool_call events when requested', async () => {
+            const { handlers } = await setupServer();
+            const mockProcess = new EventEmitter();
+            mockProcess.pid = 12348;
+            mockProcess.stdout = new EventEmitter();
+            mockProcess.stderr = new EventEmitter();
+            mockProcess.kill = vi.fn();
+            mockSpawn.mockReturnValue(mockProcess);
+            const callToolHandler = handlers.get('callTool');
+            await callToolHandler({
+                params: {
+                    name: 'run',
+                    arguments: {
+                        prompt: 'claude mcp peek prompt',
+                        workFolder: '/tmp',
+                        model: 'haiku',
+                    }
+                }
+            });
+            const peekPromise = callToolHandler({
+                params: {
+                    name: 'peek',
+                    arguments: {
+                        pids: [12348],
+                        peek_time_sec: 1,
+                        include_tool_calls: true,
+                    }
+                }
+            });
+            setTimeout(() => {
+                mockProcess.stdout.emit('data', '{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_1","name":"mcp__acm__list_processes","input":{}}]}}\n');
+                mockProcess.stdout.emit('data', '{"type":"user","message":{"content":[{"tool_use_id":"toolu_1","type":"tool_result","content":[{"type":"text","text":"secret result"}]}]}}\n');
+                mockProcess.stdout.emit('data', '{"type":"assistant","message":{"content":[{"type":"text","text":"MCP succeeded."}]}}\n');
+                mockProcess.emit('close', 0);
+            }, 10);
+            const result = await peekPromise;
+            const response = JSON.parse(result.content[0].text);
+            expect(response.processes).toHaveLength(1);
+            expect(response.processes[0]).toMatchObject({
+                pid: 12348,
+                agent: 'claude',
+                status: 'completed',
+                events: [
+                    {
+                        kind: 'tool_call',
+                        phase: 'started',
+                        id: 'toolu_1',
+                        tool: 'mcp__acm__list_processes',
+                        server: 'acm',
+                        summary: 'acm.list_processes',
+                    },
+                    {
+                        kind: 'tool_call',
+                        phase: 'completed',
+                        id: 'toolu_1',
+                        tool: 'mcp__acm__list_processes',
+                        server: 'acm',
+                        summary: 'acm.list_processes',
+                        status: 'success',
+                    },
+                    {
+                        kind: 'message',
+                        ts: expect.any(String),
+                        text: 'MCP succeeded.',
+                    },
+                ],
+                truncated: false,
+                error: null,
+            });
+            expect(JSON.stringify(response)).not.toContain('secret result');
+        });
         it('should handle process with model parameter', async () => {
             const { handlers } = await setupServer();
             const mockProcess = new EventEmitter();

package/dist/app/cli.js

@@ -8,7 +8,7 @@ export const CLI_HELP_TEXT = `Usage: ai-cli <command> [options]
 Commands:
   run       Start an AI CLI process in the background
   wait      Wait for one or more pids
-  peek      Observe new natural-language agent messages for a short window
+  peek      Observe new agent events for a short window
   ps        List tracked processes
   result    Get the current result for a pid
   kill      Terminate a tracked pid
@@ -57,12 +57,13 @@ Options:
 `;
 export const PEEK_HELP_TEXT = `Usage: ai-cli peek <pid...> [options]
 
-Observe new natural-language agent messages for a short one-shot window.
-In v1, message extraction is supported for Codex, Claude, OpenCode, and Gemini; Forge returns status with messages: [].
+Observe new natural-language agent messages, and optionally tool calls, for a short one-shot window.
+In v1, message extraction is supported for Codex, Claude, OpenCode, and Gemini; Forge returns status with events: [].
 This is not a history API, gapless streaming, or stdout/stderr tailing. No --follow mode is available in v1.
 
 Options:
   --time <seconds>             Observation window in seconds. Defaults to 10, maximum 60
+  --include-tool-calls         Include normalized tool_call events without raw tool output
   --help, -h                   Show this help message
 `;
 export const KILL_HELP_TEXT = `Usage: ai-cli kill <pid>
@@ -119,7 +120,7 @@ const defaultDeps = {
     listProcesses: () => getCliProcessService().listProcesses(),
     getProcessResult: (pid, verbose) => getCliProcessService().getProcessResult(pid, verbose),
     waitForProcesses: (pids, timeoutSeconds, verbose) => getCliProcessService().waitForProcesses(pids, timeoutSeconds, verbose),
-    peekProcesses: (pids, peekTimeSec) => getCliProcessService().peekProcesses(pids, peekTimeSec),
+    peekProcesses: (pids, peekTimeSec, includeToolCalls) => getCliProcessService().peekProcesses(pids, peekTimeSec, includeToolCalls),
     killProcess: (pid) => getCliProcessService().killProcess(pid),
     cleanupProcesses: () => getCliProcessService().cleanupProcesses(),
     getDoctorStatus: () => getCliDoctorStatus(),
@@ -297,7 +298,7 @@ export async function runCli(argv, deps = {}) {
             stdout(CLI_HELP_TEXT);
             return 1;
         }
-        writeJson(stdout, await peekProcesses(pids, peekTimeSec));
+        writeJson(stdout, await peekProcesses(pids, peekTimeSec, 'include-tool-calls' in flags || 'include_tool_calls' in flags));
         return 0;
     }
     if (command === 'kill') {

package/dist/app/mcp.js

@@ -211,7 +211,7 @@ ${getSupportedModelsDescription()}
                 },
                 {
                     name: 'peek',
-                    description: 'One-shot short observation window for running child agents. Returns only natural-language agent messages observed during this call; not a history API, not gapless streaming, and not stdout/stderr tailing. In v1, message extraction is supported for Codex, Claude, OpenCode, and Gemini; Forge returns status with messages: [].',
+                    description: 'One-shot short observation window for running child agents. Returns only natural-language message events, and optionally normalized tool_call events, observed during this call; not a history API, not gapless streaming, and not stdout/stderr tailing. In v1, message extraction is supported for Codex, Claude, OpenCode, and Gemini; Forge returns status with events: []. Tool calls exclude raw tool output.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -224,6 +224,10 @@ ${getSupportedModelsDescription()}
                                 type: 'number',
                                 description: 'Optional positive integer observation window in seconds. Defaults to 10; maximum is 60.',
                             },
+                            include_tool_calls: {
+                                type: 'boolean',
+                                description: 'Optional: include normalized tool_call events without raw tool output. Defaults to false.',
+                            },
                         },
                         required: ['pids'],
                     },
@@ -351,15 +355,20 @@ ${getSupportedModelsDescription()}
     async handlePeek(toolArguments) {
         let pids;
         let peekTimeSec;
+        let includeToolCalls;
         try {
             pids = validatePeekPids(toolArguments.pids);
             peekTimeSec = validatePeekTimeSec(toolArguments.peek_time_sec);
+            if (toolArguments.include_tool_calls !== undefined && typeof toolArguments.include_tool_calls !== 'boolean') {
+                throw new Error('include_tool_calls must be a boolean when provided');
+            }
+            includeToolCalls = toolArguments.include_tool_calls === true;
         }
         catch (error) {
             throw new McpError(ErrorCode.InvalidParams, error.message);
         }
         try {
-            const response = await this.processService.peekProcesses(pids, peekTimeSec);
+            const response = await this.processService.peekProcesses(pids, peekTimeSec, includeToolCalls);
             return {
                 content: [{
                         type: 'text',