ai-cli-mcp 2.17.0 → 2.18.0

package/src/__tests__/parsers.test.ts

@@ -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', () => {
@@ -190,6 +190,160 @@ describe('PeekMessageExtractor', () => {
   });
 });
 
+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/src/__tests__/peek.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { appendPeekMessages, validatePeekPids, validatePeekTimeSec, type PeekProcessResult } from '../peek.js';
+import { appendPeekEvents, validatePeekPids, validatePeekTimeSec, type PeekProcessResult } from '../peek.js';
 
 describe('peek helpers', () => {
   it('dedupes pids while preserving first occurrence order', () => {
@@ -17,27 +17,28 @@ describe('peek helpers', () => {
     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: PeekProcessResult = {
       pid: 123,
       agent: 'codex',
       status: 'running',
-      messages: [],
+      events: [],
       truncated: false,
       error: null,
     };
 
-    appendPeekMessages(
+    appendPeekEvents(
       process,
       Array.from({ length: 55 }, (_, index) => ({
+        kind: 'message' as const,
         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/src/__tests__/process-management.test.ts

@@ -166,8 +166,9 @@ describe('Process Management Tests', () => {
         pid: 12345,
         agent: 'claude',
         status: 'completed',
-        messages: [
+        events: [
           {
+            kind: 'message',
             ts: expect.any(String),
             text: 'new message',
           },
@@ -179,7 +180,7 @@ describe('Process Management Tests', () => {
         pid: 99999,
         agent: null,
         status: 'not_found',
-        messages: [],
+        events: [],
         truncated: false,
         error: 'process not found',
       });
@@ -232,8 +233,9 @@ describe('Process Management Tests', () => {
         pid: 12346,
         agent: 'opencode',
         status: 'completed',
-        messages: [
+        events: [
           {
+            kind: 'message',
             ts: expect.any(String),
             text: 'OpenCode visible text',
           },
@@ -291,8 +293,9 @@ describe('Process Management Tests', () => {
         pid: 12347,
         agent: 'gemini',
         status: 'completed',
-        messages: [
+        events: [
           {
+            kind: 'message',
             ts: expect.any(String),
             text: 'Visible Gemini text',
           },
@@ -302,6 +305,85 @@ describe('Process Management Tests', () => {
       });
     });
 
+    it('should include normalized tool_call events when requested', async () => {
+      const { handlers } = await setupServer();
+
+      const mockProcess = new EventEmitter() as any;
+      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();
       

package/src/app/cli.ts

@@ -9,7 +9,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
@@ -62,12 +62,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
 `;
 
@@ -131,7 +132,7 @@ interface CliDeps {
   listProcesses: () => Promise<any>;
   getProcessResult: (pid: number, verbose: boolean) => Promise<any>;
   waitForProcesses: (pids: number[], timeoutSeconds?: number, verbose?: boolean) => Promise<any>;
-  peekProcesses: (pids: number[], peekTimeSec?: number) => Promise<any>;
+  peekProcesses: (pids: number[], peekTimeSec?: number, includeToolCalls?: boolean) => Promise<any>;
   killProcess: (pid: number) => Promise<any>;
   cleanupProcesses: () => Promise<any>;
   getDoctorStatus: () => any;
@@ -154,7 +155,7 @@ const defaultDeps: CliDeps = {
   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(),
@@ -367,7 +368,7 @@ export async function runCli(argv: string[], deps: Partial<CliDeps> = {}): Promi
       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;
   }
 

package/src/app/mcp.ts

@@ -233,7 +233,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: {
@@ -246,6 +246,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'],
           },
@@ -384,16 +388,21 @@ ${getSupportedModelsDescription()}
   private async handlePeek(toolArguments: any): Promise<ServerResult> {
     let pids: number[];
     let peekTimeSec: number;
+    let includeToolCalls: boolean;
 
     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: any) {
       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',

package/src/cli-process-service.ts

@@ -19,10 +19,10 @@ import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { buildCliCommand, type BuildCliCommandOptions } from './cli-builder.js';
 import { findClaudeCli, findCodexCli, findForgeCli, findGeminiCli, findOpencodeCli } from './cli-utils.js';
-import { parseClaudeOutput, parseCodexOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekMessageExtractor } from './parsers.js';
+import { parseClaudeOutput, parseCodexOutput, parseForgeOutput, parseGeminiOutput, parseOpenCodeOutput, PeekEventExtractor } from './parsers.js';
 import { buildProcessResult } from './process-result.js';
 import {
-  appendPeekMessages,
+  appendPeekEvents,
   buildNotFoundPeekProcess,
   observedDurationSec,
   validatePeekPids,
@@ -255,15 +255,15 @@ export class CliProcessService {
     }
   }
 
-  async peekProcesses(pids: number[], peekTimeSec = 10): Promise<PeekResponse> {
+  async peekProcesses(pids: number[], peekTimeSec = 10, includeToolCalls = false): Promise<PeekResponse> {
     const targetPids = validatePeekPids(pids);
     const targetPeekTimeSec = validatePeekTimeSec(peekTimeSec);
     const processes: PeekProcessResult[] = [];
     const observers: Array<{
       process: StoredProcess;
       result: PeekProcessResult;
-      stdoutExtractor: PeekMessageExtractor;
-      stderrExtractor: PeekMessageExtractor;
+      stdoutExtractor: PeekEventExtractor;
+      stderrExtractor: PeekEventExtractor;
       stdoutOffset: number;
       stderrOffset: number;
     }> = [];
@@ -281,7 +281,7 @@ export class CliProcessService {
         pid,
         agent: process.toolType,
         status: process.status,
-        messages: [],
+        events: [],
         truncated: false,
         error: null,
       };
@@ -289,8 +289,8 @@ export class CliProcessService {
       observers.push({
         process,
         result,
-        stdoutExtractor: new PeekMessageExtractor(process.toolType),
-        stderrExtractor: new PeekMessageExtractor(process.toolType),
+        stdoutExtractor: new PeekEventExtractor(process.toolType, { includeToolCalls }),
+        stderrExtractor: new PeekEventExtractor(process.toolType, { includeToolCalls }),
         stdoutOffset: this.fileSizeSafe(process.stdoutPath),
         stderrOffset: this.fileSizeSafe(process.stderrPath),
       });
@@ -307,11 +307,11 @@ export class CliProcessService {
       for (const observer of observers) {
         const stdoutRead = this.readTextFromOffset(observer.process.stdoutPath, observer.stdoutOffset);
         observer.stdoutOffset = stdoutRead.offset;
-        appendPeekMessages(observer.result, observer.stdoutExtractor.push(stdoutRead.text, observedAt));
+        appendPeekEvents(observer.result, observer.stdoutExtractor.push(stdoutRead.text, observedAt));
 
         const stderrRead = this.readTextFromOffset(observer.process.stderrPath, observer.stderrOffset);
         observer.stderrOffset = stderrRead.offset;
-        appendPeekMessages(observer.result, observer.stderrExtractor.push(stderrRead.text, observedAt));
+        appendPeekEvents(observer.result, observer.stderrExtractor.push(stderrRead.text, observedAt));
 
         observer.process = this.refreshStatus(this.readProcess(observer.process.pid));
         observer.result.status = observer.process.status;
@@ -335,8 +335,8 @@ export class CliProcessService {
     for (const observer of observers) {
       observer.process = this.refreshStatus(this.readProcess(observer.process.pid));
       observer.result.status = observer.process.status;
-      appendPeekMessages(observer.result, observer.stdoutExtractor.flush(flushTs));
-      appendPeekMessages(observer.result, observer.stderrExtractor.flush(flushTs));
+      appendPeekEvents(observer.result, observer.stdoutExtractor.flush(flushTs));
+      appendPeekEvents(observer.result, observer.stderrExtractor.flush(flushTs));
     }
 
     return {