ai-cli-mcp 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.7.0](https://github.com/mkXultra/claude-code-mcp/compare/v2.6.0...v2.7.0) (2026-03-01)
+
+
+### Features
+
+* CLIラッパーとパーサーの追加（cli.run, cli.run.parse） ([330eacf](https://github.com/mkXultra/claude-code-mcp/commit/330eacf26e03484b389438522886448882f58289))
+
 # [2.6.0](https://github.com/mkXultra/claude-code-mcp/compare/v2.5.0...v2.6.0) (2026-02-09)
 
 

package/CONTRIBUTING.md

@@ -38,6 +38,16 @@ npm run build
 npx @modelcontextprotocol/inspector node dist/server.js
 ```
 
+## CLI Direct Execution
+
+Run AI CLI tools directly from the terminal (foreground, no MCP server):
+
+```bash
+npm run -s cli.run -- --model sonnet --workFolder /tmp --prompt "hello"
+```
+
+See [docs/development.md](docs/development.md#cli-direct-execution-clirun) for full options.
+
 ## Local Development with npm link
 
 ```bash

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

@@ -0,0 +1,278 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+// Mock dependencies
+vi.mock('node:fs');
+vi.mock('node:path', () => ({
+    resolve: vi.fn((...args) => args[args.length - 1]),
+    isAbsolute: vi.fn((p) => p.startsWith('/')),
+}));
+const mockExistsSync = vi.mocked(existsSync);
+const mockReadFileSync = vi.mocked(readFileSync);
+// Import after mocks
+import { buildCliCommand, resolveModelAlias, getReasoningEffort, } from '../cli-builder.js';
+const DEFAULT_CLI_PATHS = {
+    claude: '/usr/bin/claude',
+    codex: '/usr/bin/codex',
+    gemini: '/usr/bin/gemini',
+};
+describe('cli-builder', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // By default, workFolder exists
+        mockExistsSync.mockReturnValue(true);
+    });
+    describe('resolveModelAlias', () => {
+        it('should resolve claude-ultra to opus', () => {
+            expect(resolveModelAlias('claude-ultra')).toBe('opus');
+        });
+        it('should resolve codex-ultra to gpt-5.3-codex', () => {
+            expect(resolveModelAlias('codex-ultra')).toBe('gpt-5.3-codex');
+        });
+        it('should resolve gemini-ultra to gemini-3-pro-preview', () => {
+            expect(resolveModelAlias('gemini-ultra')).toBe('gemini-3-pro-preview');
+        });
+        it('should pass through non-alias model names', () => {
+            expect(resolveModelAlias('sonnet')).toBe('sonnet');
+            expect(resolveModelAlias('gpt-5.2-codex')).toBe('gpt-5.2-codex');
+        });
+        it('should pass through empty string', () => {
+            expect(resolveModelAlias('')).toBe('');
+        });
+    });
+    describe('getReasoningEffort', () => {
+        it('should return empty string for non-string input', () => {
+            expect(getReasoningEffort('gpt-5.2', undefined)).toBe('');
+            expect(getReasoningEffort('gpt-5.2', null)).toBe('');
+            expect(getReasoningEffort('gpt-5.2', 123)).toBe('');
+        });
+        it('should return empty string for empty/whitespace input', () => {
+            expect(getReasoningEffort('gpt-5.2', '')).toBe('');
+            expect(getReasoningEffort('gpt-5.2', '  ')).toBe('');
+        });
+        it('should normalize to lowercase', () => {
+            expect(getReasoningEffort('gpt-5.2', 'HIGH')).toBe('high');
+            expect(getReasoningEffort('gpt-5.2', 'Low')).toBe('low');
+        });
+        it('should accept valid values', () => {
+            expect(getReasoningEffort('gpt-5.2', 'low')).toBe('low');
+            expect(getReasoningEffort('gpt-5.2', 'medium')).toBe('medium');
+            expect(getReasoningEffort('gpt-5.2', 'high')).toBe('high');
+            expect(getReasoningEffort('gpt-5.2', 'xhigh')).toBe('xhigh');
+        });
+        it('should throw for invalid reasoning effort value', () => {
+            expect(() => getReasoningEffort('gpt-5.2', 'ultra')).toThrow('Invalid reasoning_effort: ultra. Allowed values: low, medium, high, xhigh.');
+        });
+        it('should throw for non-codex models', () => {
+            expect(() => getReasoningEffort('sonnet', 'high')).toThrow('reasoning_effort is only supported for Codex models (gpt-*).');
+        });
+    });
+    describe('buildCliCommand', () => {
+        describe('validation', () => {
+            it('should throw when workFolder is missing', () => {
+                expect(() => buildCliCommand({
+                    prompt: 'hello',
+                    workFolder: '',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                })).toThrow('Missing or invalid required parameter: workFolder');
+            });
+            it('should throw when neither prompt nor prompt_file is provided', () => {
+                expect(() => buildCliCommand({
+                    workFolder: '/tmp',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                })).toThrow('Either prompt or prompt_file must be provided');
+            });
+            it('should throw when both prompt and prompt_file are provided', () => {
+                expect(() => buildCliCommand({
+                    prompt: 'hello',
+                    prompt_file: '/tmp/prompt.txt',
+                    workFolder: '/tmp',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                })).toThrow('Cannot specify both prompt and prompt_file');
+            });
+            it('should throw when prompt_file does not exist', () => {
+                mockExistsSync.mockImplementation((p) => {
+                    if (p === '/tmp/nonexistent.txt')
+                        return false;
+                    return true; // workFolder exists
+                });
+                expect(() => buildCliCommand({
+                    prompt_file: '/tmp/nonexistent.txt',
+                    workFolder: '/tmp',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                })).toThrow('Prompt file does not exist');
+            });
+            it('should throw when workFolder does not exist', () => {
+                mockExistsSync.mockReturnValue(false);
+                expect(() => buildCliCommand({
+                    prompt: 'hello',
+                    workFolder: '/nonexistent',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                })).toThrow('Working folder does not exist');
+            });
+            it('should read prompt from file', () => {
+                mockExistsSync.mockReturnValue(true);
+                mockReadFileSync.mockReturnValue('prompt from file');
+                const cmd = buildCliCommand({
+                    prompt_file: '/tmp/prompt.txt',
+                    workFolder: '/tmp',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.prompt).toBe('prompt from file');
+            });
+        });
+        describe('claude agent', () => {
+            it('should build claude command with default model', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'hello world',
+                    workFolder: '/tmp',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.agent).toBe('claude');
+                expect(cmd.cliPath).toBe('/usr/bin/claude');
+                expect(cmd.args).toEqual([
+                    '--dangerously-skip-permissions',
+                    '--output-format',
+                    'stream-json',
+                    '--verbose',
+                    '-p',
+                    'hello world',
+                ]);
+                expect(cmd.resolvedModel).toBe('');
+            });
+            it('should build claude command with model', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'sonnet',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.agent).toBe('claude');
+                expect(cmd.args).toContain('--model');
+                expect(cmd.args).toContain('sonnet');
+                expect(cmd.resolvedModel).toBe('sonnet');
+            });
+            it('should build claude command with session_id', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    session_id: 'ses-123',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.args).toContain('-r');
+                expect(cmd.args).toContain('ses-123');
+            });
+            it('should resolve claude-ultra alias to opus', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'claude-ultra',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.agent).toBe('claude');
+                expect(cmd.resolvedModel).toBe('opus');
+                expect(cmd.args).toContain('opus');
+            });
+        });
+        describe('codex agent', () => {
+            it('should build codex command', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'gpt-5.2-codex',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.agent).toBe('codex');
+                expect(cmd.cliPath).toBe('/usr/bin/codex');
+                expect(cmd.args).toContain('exec');
+                expect(cmd.args).toContain('--full-auto');
+                expect(cmd.args).toContain('--json');
+                expect(cmd.args).toContain('--model');
+                expect(cmd.args).toContain('gpt-5.2-codex');
+            });
+            it('should build codex command with session_id using exec resume', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'gpt-5.2',
+                    session_id: 'codex-ses-456',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.args[0]).toBe('exec');
+                expect(cmd.args[1]).toBe('resume');
+                expect(cmd.args[2]).toBe('codex-ses-456');
+            });
+            it('should build codex command with reasoning_effort', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'gpt-5.2-codex',
+                    reasoning_effort: 'high',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.args).toContain('-c');
+                expect(cmd.args).toContain('model_reasoning_effort=high');
+            });
+            it('should resolve codex-ultra and default to xhigh reasoning', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'codex-ultra',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.agent).toBe('codex');
+                expect(cmd.resolvedModel).toBe('gpt-5.3-codex');
+                expect(cmd.args).toContain('-c');
+                expect(cmd.args).toContain('model_reasoning_effort=xhigh');
+            });
+            it('should allow overriding reasoning_effort for codex-ultra', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'codex-ultra',
+                    reasoning_effort: 'low',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.args).toContain('model_reasoning_effort=low');
+                expect(cmd.args).not.toContain('model_reasoning_effort=xhigh');
+            });
+        });
+        describe('gemini agent', () => {
+            it('should build gemini command', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'gemini-2.5-pro',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.agent).toBe('gemini');
+                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('--model');
+                expect(cmd.args).toContain('gemini-2.5-pro');
+            });
+            it('should build gemini command with session_id', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'gemini-2.5-pro',
+                    session_id: 'gem-789',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.args).toContain('-r');
+                expect(cmd.args).toContain('gem-789');
+            });
+            it('should resolve gemini-ultra alias', () => {
+                const cmd = buildCliCommand({
+                    prompt: 'test',
+                    workFolder: '/tmp',
+                    model: 'gemini-ultra',
+                    cliPaths: DEFAULT_CLI_PATHS,
+                });
+                expect(cmd.agent).toBe('gemini');
+                expect(cmd.resolvedModel).toBe('gemini-3-pro-preview');
+            });
+        });
+    });
+});

package/dist/cli-builder.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as pathResolve, isAbsolute } from 'node:path';
+// Model alias mappings for user-friendly model names
+export const MODEL_ALIASES = {
+    'claude-ultra': 'opus',
+    'codex-ultra': 'gpt-5.3-codex',
+    'gemini-ultra': 'gemini-3-pro-preview'
+};
+export const ALLOWED_REASONING_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh']);
+/**
+ * Resolves model aliases to their full model names
+ * @param model - The model name or alias to resolve
+ * @returns The full model name, or the original value if no alias exists
+ */
+export function resolveModelAlias(model) {
+    return MODEL_ALIASES[model] || model;
+}
+/**
+ * Validates and normalizes reasoning effort parameter.
+ * @returns normalized reasoning effort string, or '' if not applicable
+ * @throws Error for invalid values (plain Error, not MCP-specific)
+ */
+export function getReasoningEffort(model, rawValue) {
+    if (typeof rawValue !== 'string') {
+        return '';
+    }
+    const trimmed = rawValue.trim();
+    if (!trimmed) {
+        return '';
+    }
+    const normalized = trimmed.toLowerCase();
+    if (!ALLOWED_REASONING_EFFORTS.has(normalized)) {
+        throw new Error(`Invalid reasoning_effort: ${rawValue}. Allowed values: low, medium, high, xhigh.`);
+    }
+    if (!model.startsWith('gpt-')) {
+        throw new Error('reasoning_effort is only supported for Codex models (gpt-*).');
+    }
+    return normalized;
+}
+/**
+ * Build a CLI command from the given options.
+ * This is a pure function (aside from filesystem reads for prompt_file / workFolder validation).
+ * @throws Error on validation failures
+ */
+export function buildCliCommand(options) {
+    // Validate workFolder
+    if (!options.workFolder || typeof options.workFolder !== 'string') {
+        throw new Error('Missing or invalid required parameter: workFolder');
+    }
+    // Validate prompt / prompt_file
+    const hasPrompt = !!options.prompt && typeof options.prompt === 'string' && options.prompt.trim() !== '';
+    const hasPromptFile = !!options.prompt_file && typeof options.prompt_file === 'string' && options.prompt_file.trim() !== '';
+    if (!hasPrompt && !hasPromptFile) {
+        throw new Error('Either prompt or prompt_file must be provided');
+    }
+    if (hasPrompt && hasPromptFile) {
+        throw new Error('Cannot specify both prompt and prompt_file. Please use only one.');
+    }
+    // Determine prompt
+    let prompt;
+    if (hasPrompt) {
+        prompt = options.prompt;
+    }
+    else {
+        const promptFilePath = isAbsolute(options.prompt_file)
+            ? options.prompt_file
+            : pathResolve(options.workFolder, options.prompt_file);
+        if (!existsSync(promptFilePath)) {
+            throw new Error(`Prompt file does not exist: ${promptFilePath}`);
+        }
+        try {
+            prompt = readFileSync(promptFilePath, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to read prompt file: ${error.message}`);
+        }
+    }
+    // Resolve workFolder
+    const cwd = pathResolve(options.workFolder);
+    if (!existsSync(cwd)) {
+        throw new Error(`Working folder does not exist: ${options.workFolder}`);
+    }
+    // Resolve model
+    const rawModel = options.model || '';
+    const resolvedModel = resolveModelAlias(rawModel);
+    // Special handling for codex-ultra: default to high reasoning effort if not specified
+    let reasoningEffortArg = options.reasoning_effort;
+    if (rawModel === 'codex-ultra' && !reasoningEffortArg) {
+        reasoningEffortArg = 'xhigh';
+    }
+    const reasoningEffort = getReasoningEffort(resolvedModel, reasoningEffortArg);
+    // Determine agent
+    let agent;
+    if (resolvedModel.startsWith('gpt-')) {
+        agent = 'codex';
+    }
+    else if (resolvedModel.startsWith('gemini')) {
+        agent = 'gemini';
+    }
+    else {
+        agent = 'claude';
+    }
+    // Build CLI path and args
+    let cliPath;
+    let args;
+    if (agent === 'codex') {
+        cliPath = options.cliPaths.codex;
+        if (options.session_id && typeof options.session_id === 'string') {
+            args = ['exec', 'resume', options.session_id];
+        }
+        else {
+            args = ['exec'];
+        }
+        if (reasoningEffort) {
+            args.push('-c', `model_reasoning_effort=${reasoningEffort}`);
+        }
+        if (resolvedModel) {
+            args.push('--model', resolvedModel);
+        }
+        args.push('--full-auto', '--json', prompt);
+    }
+    else if (agent === 'gemini') {
+        cliPath = options.cliPaths.gemini;
+        args = ['-y', '--output-format', 'json'];
+        if (options.session_id && typeof options.session_id === 'string') {
+            args.push('-r', options.session_id);
+        }
+        if (resolvedModel) {
+            args.push('--model', resolvedModel);
+        }
+        args.push(prompt);
+    }
+    else {
+        cliPath = options.cliPaths.claude;
+        args = ['--dangerously-skip-permissions', '--output-format', 'stream-json', '--verbose'];
+        if (options.session_id && typeof options.session_id === 'string') {
+            args.push('-r', options.session_id);
+        }
+        args.push('-p', prompt);
+        if (resolvedModel) {
+            args.push('--model', resolvedModel);
+        }
+    }
+    return { cliPath, args, cwd, agent, prompt, resolvedModel };
+}

package/dist/cli-parse.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { parseClaudeOutput, parseCodexOutput, parseGeminiOutput } from './parsers.js';
+const AGENTS = ['claude', 'codex', 'gemini'];
+const USAGE = `Usage: npm run -s cli.run.parse -- --agent <claude|codex|gemini>
+
+Reads raw CLI output from stdin and outputs parsed JSON to stdout.
+
+Options:
+  --agent   Agent type: claude, codex, or gemini (required)
+  --help    Show this help message
+
+Examples:
+  npm run -s cli.run -- --model sonnet --workFolder /tmp --prompt "hi" > raw.txt
+  npm run -s cli.run.parse -- --agent claude < raw.txt
+
+  # Or pipe directly
+  npm run -s cli.run -- --model sonnet --workFolder /tmp --prompt "hi" | npm run -s cli.run.parse -- --agent claude
+`;
+function parseArgs(argv) {
+    const result = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const eqIdx = arg.indexOf('=');
+        if (eqIdx !== -1) {
+            result[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+        }
+        else {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                result[key] = next;
+                i++;
+            }
+            else {
+                result[key] = '';
+            }
+        }
+    }
+    return result;
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on('data', (chunk) => chunks.push(chunk));
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        process.stdin.on('error', reject);
+    });
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if ('help' in args) {
+        process.stdout.write(USAGE);
+        process.exit(0);
+    }
+    const agent = args.agent;
+    if (!agent || !AGENTS.includes(agent)) {
+        process.stderr.write(`Error: --agent is required (claude, codex, or gemini)\n\n`);
+        process.stderr.write(USAGE);
+        process.exit(1);
+    }
+    const input = await readStdin();
+    if (!input.trim()) {
+        process.stderr.write('Error: no input received from stdin\n');
+        process.exit(1);
+    }
+    let parsed = null;
+    switch (agent) {
+        case 'claude':
+            parsed = parseClaudeOutput(input);
+            break;
+        case 'codex':
+            parsed = parseCodexOutput(input);
+            break;
+        case 'gemini':
+            parsed = parseGeminiOutput(input);
+            break;
+    }
+    process.stdout.write(JSON.stringify(parsed, null, 2) + '\n');
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err.message}\n`);
+    process.exit(1);
+});

package/dist/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { buildCliCommand } from './cli-builder.js';
+import { findClaudeCli, findCodexCli, findGeminiCli } from './server.js';
+/**
+ * Minimal argv parser. No external dependencies.
+ * Supports: --key value, --key=value
+ */
+function parseArgs(argv) {
+    const result = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const eqIdx = arg.indexOf('=');
+        if (eqIdx !== -1) {
+            // --key=value
+            result[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+        }
+        else {
+            // --key value
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                result[key] = next;
+                i++;
+            }
+            else {
+                result[key] = '';
+            }
+        }
+    }
+    return result;
+}
+const USAGE = `Usage: npm run -s cli.run -- --model <model> --workFolder <path> --prompt "..." [options]
+
+Options:
+  --model              Model name or alias (e.g. sonnet, opus, gpt-5.2-codex, gemini-2.5-pro)
+  --workFolder         Working directory (absolute path)
+  --prompt             Prompt string (mutually exclusive with --prompt_file)
+  --prompt_file        Path to a file containing the prompt
+  --session_id         Session ID to resume
+  --reasoning_effort   Codex only: low, medium, high, xhigh
+  --help               Show this help message
+
+Raw CLI output goes to stdout. Use cli.run.parse to parse the output:
+  npm run -s cli.run -- ... > raw.txt
+  npm run -s cli.run.parse -- --agent claude < raw.txt
+`;
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if ('help' in args) {
+        process.stdout.write(USAGE);
+        process.exit(0);
+    }
+    if (!args.workFolder) {
+        process.stderr.write('Error: --workFolder is required\n\n');
+        process.stderr.write(USAGE);
+        process.exit(1);
+    }
+    if (!args.prompt && !args.prompt_file) {
+        process.stderr.write('Error: --prompt or --prompt_file is required\n\n');
+        process.stderr.write(USAGE);
+        process.exit(1);
+    }
+    // Resolve CLI paths
+    const cliPaths = {
+        claude: findClaudeCli(),
+        codex: findCodexCli(),
+        gemini: findGeminiCli(),
+    };
+    // Build command
+    let cmd;
+    try {
+        cmd = buildCliCommand({
+            prompt: args.prompt || undefined,
+            prompt_file: args.prompt_file || undefined,
+            workFolder: args.workFolder,
+            model: args.model || undefined,
+            session_id: args.session_id || undefined,
+            reasoning_effort: args.reasoning_effort || undefined,
+            cliPaths,
+        });
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error.message}\n`);
+        process.exit(1);
+    }
+    // Log agent info to stderr (does not pollute stdout)
+    process.stderr.write(`[cli.run] agent=${cmd.agent} model=${cmd.resolvedModel || '(default)'}\n`);
+    // Spawn foreground process — raw output passthrough
+    const child = spawn(cmd.cliPath, cmd.args, {
+        cwd: cmd.cwd,
+        stdio: 'inherit',
+        detached: false,
+    });
+    const exitCode = await new Promise((resolve) => {
+        child.on('close', (code) => {
+            resolve(code ?? 1);
+        });
+        child.on('error', (err) => {
+            process.stderr.write(`Process error: ${err.message}\n`);
+            resolve(1);
+        });
+    });
+    process.exit(exitCode);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err.message}\n`);
+    process.exit(1);
+});