@wooojin/forgen 0.4.1 → 0.4.4

package/dist/host/install-codex.js

@@ -0,0 +1,276 @@
+/**
+ * Codex InstallPlan — Multi-Host Core Design §10 우선순위 3
+ *
+ * `~/.codex/hooks.json` 에 forgen hook 등록(절대경로, idempotent), `~/.codex/config.toml`
+ * 에 forgen-compound MCP 등록(managed marker block). $CODEX_HOME 환경변수 존중.
+ *
+ * 동작 원칙:
+ * - hook 등록은 generateHooksJson({runtime:'codex', pluginRoot, releaseMode}) 결과를 그대로 사용
+ *   — 이미 codex-adapter wrapper + 절대경로 적용됨 (spec §18.5 결정 옵션 1).
+ * - 사용자가 직접 작성한 비-forgen hook 은 보존 (`isForgenHookEntry` pattern).
+ * - MCP 등록은 TOML 라이브러리 없이 marker block 으로 idempotent 관리.
+ * - dryRun 시 파일을 쓰지 않고 결과만 반환 (테스트 + preview 용).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { generateHooksJson } from '../hooks/hooks-generator.js';
+const MCP_MARKER_BEGIN = '# >>> forgen-managed-mcp';
+const MCP_MARKER_END = '# <<< forgen-managed-mcp';
+const FORGEN_SKILL_MARKER = '<!-- forgen-managed -->';
+const AGENTS_MD_BEGIN = '<!-- >>> forgen-managed-rules -->';
+const AGENTS_MD_END = '<!-- <<< forgen-managed-rules -->';
+function resolveCodexHome(opts) {
+    return opts.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+}
+function isForgenManagedHook(entry, pkgRoot) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    if (!Array.isArray(e.hooks))
+        return false;
+    return e.hooks.some((h) => typeof h.command === 'string' && h.command.includes(pkgRoot));
+}
+function readJsonFile(p) {
+    try {
+        if (!fs.existsSync(p))
+            return null;
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function buildMcpBlock(pkgRoot) {
+    // forgen-mcp 는 dist/mcp/server.js. node 경로는 PATH 기반.
+    // `--host=codex` 인자는 server.ts 가 process.env.FORGEN_HOST 로 set 하여
+    // correction-record evidence 박제 시 host:"codex" 로 정확히 태깅되게 한다 (spec §10-5).
+    const serverPath = path.join(pkgRoot, 'dist', 'mcp', 'server.js');
+    return [
+        MCP_MARKER_BEGIN,
+        '[mcp_servers.forgen-compound]',
+        'command = "node"',
+        `args = [${JSON.stringify(serverPath)}, "--host=codex"]`,
+        MCP_MARKER_END,
+    ].join('\n');
+}
+function upsertMcpBlock(currentToml, pkgRoot) {
+    const block = buildMcpBlock(pkgRoot);
+    // marker block 이 있으면 그 사이를 새 block 으로 교체
+    const reMarker = new RegExp(`${MCP_MARKER_BEGIN}[\\s\\S]*?${MCP_MARKER_END}`, 'g');
+    if (reMarker.test(currentToml)) {
+        const replaced = currentToml.replace(reMarker, block);
+        return { content: replaced, alreadyPresent: replaced === currentToml };
+    }
+    // 없으면 끝에 append
+    const trimmed = currentToml.replace(/\s+$/, '');
+    const sep = trimmed.length > 0 ? '\n\n' : '';
+    return { content: `${trimmed}${sep}${block}\n`, alreadyPresent: false };
+}
+export function planCodexInstall(opts) {
+    const codexHome = resolveCodexHome(opts);
+    const hooksPath = path.join(codexHome, 'hooks.json');
+    const configTomlPath = path.join(codexHome, 'config.toml');
+    const releaseMode = opts.releaseMode ?? true;
+    // 1) forgen 측 hook (codex-adapter wrap + 절대경로) 생성
+    const generated = generateHooksJson({
+        pluginRoot: path.join(opts.pkgRoot, 'dist'),
+        runtime: 'codex',
+        releaseMode,
+    });
+    const generatedHooks = generated.hooks;
+    // 2) 기존 hooks.json 읽기 + forgen entry 제거 후 보존
+    const existing = readJsonFile(hooksPath);
+    const existingHooksByEvent = (existing?.hooks ?? {});
+    const preserved = {};
+    let preservedCount = 0;
+    for (const [event, entries] of Object.entries(existingHooksByEvent)) {
+        if (!Array.isArray(entries))
+            continue;
+        const userEntries = entries.filter((e) => !isForgenManagedHook(e, opts.pkgRoot));
+        if (userEntries.length > 0) {
+            preserved[event] = userEntries;
+            preservedCount += userEntries.length;
+        }
+    }
+    // 3) merge: user 보존 + forgen fresh.
+    //    `forgenCount` 는 실제 hook 명령 개수 (matcher group 내부 hooks[] 길이의 합) 로 집계한다.
+    const merged = { ...preserved };
+    let forgenCount = 0;
+    for (const [event, entries] of Object.entries(generatedHooks)) {
+        const list = merged[event] ?? [];
+        list.push(...entries);
+        merged[event] = list;
+        for (const group of entries) {
+            const g = group;
+            if (Array.isArray(g.hooks))
+                forgenCount += g.hooks.length;
+        }
+    }
+    const finalHooksFile = {
+        description: 'forgen Codex hooks (managed; user-authored entries preserved)',
+        hooks: merged,
+    };
+    // 4) MCP 등록
+    const registerMcp = opts.registerMcp ?? true;
+    let mcpAlreadyPresent = false;
+    let mcpRegistered = false;
+    let mcpContentToWrite = null;
+    if (registerMcp) {
+        const currentToml = fs.existsSync(configTomlPath)
+            ? fs.readFileSync(configTomlPath, 'utf-8')
+            : '';
+        const { content, alreadyPresent } = upsertMcpBlock(currentToml, opts.pkgRoot);
+        mcpAlreadyPresent = alreadyPresent;
+        mcpRegistered = !alreadyPresent;
+        mcpContentToWrite = content;
+    }
+    // 5) 실제 쓰기 (dryRun 이면 skip) — hooks.json + config.toml
+    if (!opts.dryRun) {
+        fs.mkdirSync(codexHome, { recursive: true });
+        fs.writeFileSync(hooksPath, `${JSON.stringify(finalHooksFile, null, 2)}\n`, 'utf-8');
+        if (mcpContentToWrite !== null) {
+            fs.writeFileSync(configTomlPath, mcpContentToWrite, 'utf-8');
+        }
+    }
+    // 6) P3-3 (US-013): Codex skills/ 에 forgen 10 commands install
+    //    Codex 의 skills 메커니즘 (codex-rs/core-skills) 구조: <skill-name>/SKILL.md
+    //    + frontmatter (name + description). forgen-managed marker 로 idempotent.
+    const skillsPath = path.join(codexHome, 'skills');
+    const sourceCommandsDir = path.join(opts.pkgRoot, 'assets', 'claude', 'commands');
+    const skillsResult = installCodexSkills({ sourceDir: sourceCommandsDir, targetDir: skillsPath, dryRun: opts.dryRun ?? false });
+    // 7) P3-3 (US-013): cwd/AGENTS.md 에 forgen rules block 인젝션 (managed marker)
+    //    Codex 가 AGENTS.md 를 자동 read (codex-rs/core/src/agents_md.rs 검증).
+    //    pkgRoot 의 git repo root 의 AGENTS.md, 또는 explicit override.
+    const agentsMdPath = opts.agentsMdPath ?? resolveAgentsMdPath(opts.pkgRoot);
+    const agentsResult = upsertForgenRulesInAgentsMd({ agentsMdPath, pkgRoot: opts.pkgRoot, dryRun: opts.dryRun ?? false });
+    return {
+        codexHome,
+        hooksPath,
+        hooksWritten: !opts.dryRun,
+        hooksCount: forgenCount,
+        preservedUserHookCount: preservedCount,
+        configTomlPath,
+        mcpRegistered,
+        mcpAlreadyPresent,
+        skillsInstalled: skillsResult.installed,
+        skillsPath,
+        agentsMdPath,
+        agentsMdInjected: agentsResult.injected,
+    };
+}
+// ── P3-3: Codex skills install ────────────────────────────────────────
+function installCodexSkills(opts) {
+    const { sourceDir, targetDir, dryRun } = opts;
+    if (!fs.existsSync(sourceDir))
+        return { installed: 0 };
+    const files = fs.readdirSync(sourceDir).filter((f) => f.endsWith('.md'));
+    if (dryRun)
+        return { installed: files.length };
+    fs.mkdirSync(targetDir, { recursive: true });
+    let count = 0;
+    for (const file of files) {
+        const skillName = file.replace(/\.md$/, '');
+        const skillDir = path.join(targetDir, skillName);
+        const skillFile = path.join(skillDir, 'SKILL.md');
+        if (fs.existsSync(skillFile)) {
+            const existing = fs.readFileSync(skillFile, 'utf-8');
+            // Phase 3 critic fix: marker 가 *frontmatter 직후* 위치에 있는지 검증.
+            // 사용자가 forgen 문서를 인용해 본문 안에 marker 가 우연히 포함될 수 있어
+            // includes() 만으론 안전 X. 정규식으로 frontmatter 종결(`---\n`) 다음 빈 줄 다음
+            // 첫 non-blank 줄에 marker 가 있는지 확인.
+            const fmMarkerRe = /^---\n[\s\S]*?\n---\n\s*<!-- forgen-managed -->/;
+            if (!fmMarkerRe.test(existing))
+                continue; // 사용자 작성 또는 손상 — skip
+        }
+        const raw = fs.readFileSync(path.join(sourceDir, file), 'utf-8');
+        const descMatch = raw.match(/description:\s*(.+)/);
+        const desc = descMatch?.[1]?.trim() ?? skillName;
+        const bodyMatch = raw.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+        const body = bodyMatch?.[1]?.trim() ?? raw;
+        const out = `---\nname: ${skillName}\ndescription: ${desc}\n---\n\n${FORGEN_SKILL_MARKER}\n\n${body}\n`;
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.writeFileSync(skillFile, out);
+        count += 1;
+    }
+    return { installed: count };
+}
+// ── P3-3: AGENTS.md inject ────────────────────────────────────────────
+function resolveAgentsMdPath(pkgRoot) {
+    // Phase 3 critic fix: pkgRoot 기반 walk-up 은 `npm install -g` 시 시스템 디렉토리
+    // (예: /usr/local/lib/node_modules/forgen) 에 fallback AGENTS.md 작성 위험.
+    // *cwd 기반* 으로 변경 — 사용자 작업 디렉토리의 git root, 없으면 cwd 자체.
+    // (사용자가 forgen install codex 를 실행하는 위치가 install target 이라는 자연 가정.)
+    // pkgRoot 는 fallback 으로 유지 (cwd 가 git root 를 못 찾고 / 등 시스템 dir 일 때).
+    const cwd = process.cwd();
+    let dir = cwd;
+    for (let depth = 0; depth < 8; depth += 1) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return path.join(dir, 'AGENTS.md');
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // cwd 에서 .git 못 찾음 — cwd 직접 사용 (시스템 dir 가 아닌 한 안전).
+    // 시스템 dir (예: /, /usr) 인 경우 ~/AGENTS.md fallback (사용자 home 안전).
+    if (cwd === '/' || cwd.startsWith('/usr/') || cwd.startsWith('/opt/')) {
+        return path.join(os.homedir(), 'AGENTS.md');
+    }
+    return path.join(cwd, 'AGENTS.md');
+}
+function buildForgenRulesBlock(pkgRoot) {
+    // forgen 의 핵심 규칙 + 사용자 profile 안내 (가벼운 헤더만 — 실 rule 은 hook chain 이 inject)
+    const lines = [
+        AGENTS_MD_BEGIN,
+        '## forgen managed rules',
+        '',
+        '본 블록은 `forgen install codex` 가 자동 관리. 직접 편집 금지 — 다음 install 시 덮어쓰임.',
+        '',
+        '- forgen-compound MCP 가 ~/.codex/config.toml 에 등록됨. 학습된 솔루션을 `compound-search` 로 조회 가능.',
+        '- 사용자 교정은 `correction-record` MCP 도구로 즉시 박제 (kind: fix-now / prefer-from-now / avoid-this).',
+        '- forgen 의 4축 profile (quality_safety / autonomy / judgment_philosophy / communication_style) 이 응답 톤 + 검증 깊이를 가이드.',
+        '- 본 rule 은 cwd 의 AGENTS.md 가 자동 read 되는 Codex 의 user_instructions 경로로 흘러들어감.',
+        `- pkgRoot: ${pkgRoot}`,
+        AGENTS_MD_END,
+    ];
+    return lines.join('\n');
+}
+function upsertForgenRulesInAgentsMd(opts) {
+    const { agentsMdPath, pkgRoot, dryRun } = opts;
+    const block = buildForgenRulesBlock(pkgRoot);
+    let current = '';
+    if (fs.existsSync(agentsMdPath)) {
+        current = fs.readFileSync(agentsMdPath, 'utf-8');
+    }
+    // Phase 3 critic fix #1: RegExp lastIndex 위험 회피 — g flag 제거 + 매번 새 RegExp.
+    const reMarker = new RegExp(`${escapeRegex(AGENTS_MD_BEGIN)}[\\s\\S]*?${escapeRegex(AGENTS_MD_END)}`);
+    const hasBlock = reMarker.test(current);
+    // Phase 3 critic fix #2: AGENTS.md self-heal — begin marker 만 있고 end 손상 시
+    // 누적 방지. begin 부터 파일 끝까지 + AGENTS_MD_END 미존재 = 손상으로 판단,
+    // begin 부터 파일 끝까지를 *전부* 새 block 으로 교체.
+    let newContent;
+    if (hasBlock) {
+        newContent = current.replace(reMarker, block);
+    }
+    else {
+        const beginIdx = current.indexOf(AGENTS_MD_BEGIN);
+        const endIdx = current.indexOf(AGENTS_MD_END);
+        if (beginIdx !== -1 && endIdx === -1) {
+            // 손상: begin 만 있음 → begin 부터 끝까지 교체 (self-heal)
+            newContent = `${current.slice(0, beginIdx).replace(/\s+$/, '')}\n\n${block}\n`;
+        }
+        else {
+            // 깨끗한 신규 또는 둘 다 없음 → 끝에 append
+            newContent = `${current.replace(/\s+$/, '')}${current.length > 0 ? '\n\n' : ''}${block}\n`;
+        }
+    }
+    if (dryRun)
+        return { injected: newContent !== current };
+    fs.mkdirSync(path.dirname(agentsMdPath), { recursive: true });
+    fs.writeFileSync(agentsMdPath, newContent, 'utf-8');
+    return { injected: newContent !== current };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/host/install-orchestrator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Install orchestrator — feat/codex-support P1-3
+ *
+ * `forgen install` CLI 의 분기 처리:
+ *   - 인자 없음    → interactive 3-choice (claude/codex/both/quit)
+ *   - 'claude'    → planClaudeInstall()
+ *   - 'codex'     → planCodexInstall()
+ *   - 'both'      → 둘 다 실행
+ *
+ * 사용자 host 선택 권한이 forgen 측에 위임 (1원칙: Claude default 강요 금지).
+ * Phase 1 Round 2 의 *마이그레이션 정책 C* (기존 entry 보존) 와 함께 동작.
+ */
+import { detectAvailableHosts } from '../core/host-detect.js';
+import { type ClaudeInstallResult } from './install-claude.js';
+import { type CodexInstallResult } from './install-codex.js';
+export type InstallTarget = 'claude' | 'codex' | 'both';
+export interface OrchestratorOptions {
+    /** Sub-command 인자: 'claude'|'codex'|'both' 또는 undefined (interactive). */
+    target?: string;
+    pkgRoot: string;
+    dryRun?: boolean;
+    registerMcp?: boolean;
+}
+export interface OrchestratorResult {
+    target: InstallTarget;
+    claude?: ClaudeInstallResult;
+    codex?: CodexInstallResult;
+    detection: ReturnType<typeof detectAvailableHosts>;
+}
+export declare function runInstall(opts: OrchestratorOptions): Promise<OrchestratorResult | null>;
+/** CLI 출력 포맷터 — orchestrator 결과를 사용자에게 표시. */
+export declare function renderResult(result: OrchestratorResult, dryRun: boolean): string;
+/** pkgRoot resolve from binary location (dist/cli.js → pkgRoot). */
+export declare function resolvePkgRootFromBinary(metaUrl: string): string;

package/dist/host/install-orchestrator.js

@@ -0,0 +1,126 @@
+/**
+ * Install orchestrator — feat/codex-support P1-3
+ *
+ * `forgen install` CLI 의 분기 처리:
+ *   - 인자 없음    → interactive 3-choice (claude/codex/both/quit)
+ *   - 'claude'    → planClaudeInstall()
+ *   - 'codex'     → planCodexInstall()
+ *   - 'both'      → 둘 다 실행
+ *
+ * 사용자 host 선택 권한이 forgen 측에 위임 (1원칙: Claude default 강요 금지).
+ * Phase 1 Round 2 의 *마이그레이션 정책 C* (기존 entry 보존) 와 함께 동작.
+ */
+import * as path from 'node:path';
+import * as readline from 'node:readline';
+import { detectAvailableHosts } from '../core/host-detect.js';
+import { planClaudeInstall } from './install-claude.js';
+import { planCodexInstall } from './install-codex.js';
+function askChoice(rl, question, validChoices) {
+    return new Promise((resolve) => {
+        const ask = () => {
+            rl.question(question, (answer) => {
+                const trimmed = answer.trim().toLowerCase();
+                if (validChoices.includes(trimmed))
+                    resolve(trimmed);
+                else {
+                    console.log(`  Please enter one of: ${validChoices.join(', ')}`);
+                    ask();
+                }
+            });
+        };
+        ask();
+    });
+}
+function renderHostStatus(host) {
+    if (!host.available)
+        return `  ✗ ${host.host} (not detected — binary 미설치 + ~/.${host.host}/ 부재)`;
+    const bits = [];
+    if (host.binaryFound)
+        bits.push(`binary: ${host.binaryPath}`);
+    if (host.homeExists)
+        bits.push(`home: ${host.homePath}`);
+    if (host.host === 'codex' && host.authPresent)
+        bits.push('auth: present');
+    return `  ✓ ${host.host} (${bits.join(', ')})`;
+}
+async function chooseTargetInteractively(detection) {
+    console.log('\n  [forgen] Setup wizard\n');
+    console.log('  Detected hosts:');
+    console.log(renderHostStatus(detection.claude));
+    console.log(renderHostStatus(detection.codex));
+    console.log('');
+    if (detection.noneAvailable) {
+        console.log('  ⚠ Neither Claude nor Codex detected. Install one of:');
+        console.log('     - Claude Code: npm install -g @anthropic-ai/claude-code');
+        console.log('     - Codex CLI:   npm install -g @openai/codex');
+        return null;
+    }
+    console.log('  Where to register forgen?');
+    console.log('    [1] Claude only');
+    console.log('    [2] Codex only');
+    console.log('    [3] Both');
+    console.log('    [q] Quit');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const choice = await askChoice(rl, '  Choice: ', ['1', '2', '3', 'q']);
+        if (choice === 'q')
+            return null;
+        return choice === '1' ? 'claude' : choice === '2' ? 'codex' : 'both';
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runInstall(opts) {
+    const detection = detectAvailableHosts();
+    let target;
+    if (opts.target === 'claude' || opts.target === 'codex' || opts.target === 'both') {
+        target = opts.target;
+    }
+    else if (opts.target === undefined) {
+        const interactive = await chooseTargetInteractively(detection);
+        if (interactive === null)
+            return null;
+        target = interactive;
+    }
+    else {
+        throw new Error(`Unknown install target: ${opts.target}. Use claude|codex|both or omit for interactive.`);
+    }
+    const result = { target, detection };
+    const dryRun = opts.dryRun ?? false;
+    const registerMcp = opts.registerMcp ?? true;
+    if (target === 'claude' || target === 'both') {
+        result.claude = planClaudeInstall({ pkgRoot: opts.pkgRoot, dryRun, registerMcp });
+    }
+    if (target === 'codex' || target === 'both') {
+        result.codex = planCodexInstall({ pkgRoot: opts.pkgRoot, dryRun, registerMcp });
+    }
+    return result;
+}
+/** CLI 출력 포맷터 — orchestrator 결과를 사용자에게 표시. */
+export function renderResult(result, dryRun) {
+    const lines = [];
+    lines.push(`\n  [forgen] Install ${dryRun ? '(dry-run)' : 'completed'} — target: ${result.target}`);
+    if (result.claude) {
+        lines.push('');
+        lines.push('  Claude:');
+        lines.push(`    plugin cache: ${result.claude.pluginCachePath}`);
+        lines.push(`    slash commands: ${result.claude.slashCommandsCount} → ${result.claude.slashCommandsPath}`);
+        lines.push(`    settings.json hooks: ${result.claude.hooksInjected}`);
+        lines.push(`    MCP: ${result.claude.mcpAlreadyPresent ? 'already present' : (result.claude.mcpRegistered ? 'registered' : 'skipped')}`);
+    }
+    if (result.codex) {
+        lines.push('');
+        lines.push('  Codex:');
+        lines.push(`    CODEX_HOME: ${result.codex.codexHome}`);
+        lines.push(`    hooks.json: ${result.codex.hooksCount} forgen hooks (preserved user: ${result.codex.preservedUserHookCount})`);
+        lines.push(`    MCP: ${result.codex.mcpAlreadyPresent ? 'already present' : (result.codex.mcpRegistered ? 'registered' : 'skipped')}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** pkgRoot resolve from binary location (dist/cli.js → pkgRoot). */
+export function resolvePkgRootFromBinary(metaUrl) {
+    const here = path.dirname(new URL(metaUrl).pathname);
+    return path.resolve(here, '..');
+}

package/dist/host/invoke-agent.d.ts

@@ -0,0 +1,27 @@
+/**
+ * invoke-agent — feat/codex-support P3-4/P3-5
+ *
+ * forgen 의 sub-agent (assets/claude/agents/<name>.md) 를 host-aware 로 호출.
+ * Claude 의 Task tool 동치 — 별도 child process 에서 sub-agent 의 system prompt 를
+ * prefix 로 사용자 task 실행 후 결과 반환.
+ *
+ * Recursion guard: FORGEN_INVOKE_DEPTH env var 로 depth 추적, max 2 (sub-agent 가
+ * 또 sub-agent 호출 시도 → 차단).
+ */
+import { type ExecHostResult } from './exec-host.js';
+export interface InvokeAgentOptions {
+    agentName: string;
+    task: string;
+    /** Child process timeout (ms). Default 60s. */
+    timeoutMs?: number;
+    /** Override host (default: profile.default_host). */
+    host?: 'claude' | 'codex';
+}
+export interface InvokeAgentResult {
+    agentName: string;
+    host: 'claude' | 'codex';
+    summary: string;
+    durationMs: number;
+    usage: ExecHostResult['usage'];
+}
+export declare function invokeAgent(opts: InvokeAgentOptions): Promise<InvokeAgentResult>;

package/dist/host/invoke-agent.js

@@ -0,0 +1,115 @@
+/**
+ * invoke-agent — feat/codex-support P3-4/P3-5
+ *
+ * forgen 의 sub-agent (assets/claude/agents/<name>.md) 를 host-aware 로 호출.
+ * Claude 의 Task tool 동치 — 별도 child process 에서 sub-agent 의 system prompt 를
+ * prefix 로 사용자 task 실행 후 결과 반환.
+ *
+ * Recursion guard: FORGEN_INVOKE_DEPTH env var 로 depth 추적, max 2 (sub-agent 가
+ * 또 sub-agent 호출 시도 → 차단).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execHost } from './exec-host.js';
+const MAX_DEPTH = 2;
+const MAX_CONCURRENT = 3;
+let activeInvocations = 0;
+function findAgentsRoot() {
+    // Phase 3 critic fix: 단순 디렉토리 매치 시 모노레포의 동명 디렉토리 위험.
+    // package.json 의 name === '@wooojin/forgen' 검증으로 *정확한 forgen pkg root* 확정.
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 8; depth += 1) {
+        const pkgJson = path.join(dir, 'package.json');
+        if (fs.existsSync(pkgJson)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgJson, 'utf-8'));
+                if (pkg.name === '@wooojin/forgen') {
+                    const candidate = path.join(dir, 'assets', 'claude', 'agents');
+                    if (fs.existsSync(candidate))
+                        return candidate;
+                }
+            }
+            catch { /* fallthrough — 다음 walk-up */ }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('invoke-agent: forgen pkg root + assets/claude/agents/ not found');
+}
+function loadAgentDefinition(agentName) {
+    const safeName = agentName.replace(/[^a-zA-Z0-9_-]/g, '');
+    if (safeName !== agentName || safeName.length === 0) {
+        throw new Error(`invoke-agent: invalid agent_name "${agentName}" — use only [a-zA-Z0-9_-]`);
+    }
+    const root = findAgentsRoot();
+    const filePath = path.join(root, `${safeName}.md`);
+    if (!fs.existsSync(filePath)) {
+        const available = fs.readdirSync(root)
+            .filter((f) => f.endsWith('.md'))
+            .map((f) => f.replace(/\.md$/, ''))
+            .sort();
+        throw new Error(`invoke-agent: agent "${agentName}" not found. Available: ${available.join(', ')}`);
+    }
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    // Phase 3 critic fix: BOM + CRLF 정규화 (Windows / Notion 파일 호환)
+    const normalized = raw.replace(/^/, '').replace(/\r\n/g, '\n');
+    const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    const description = fmMatch?.[1].match(/description:\s*(.+)/)?.[1].trim() ?? safeName;
+    const body = fmMatch?.[2]?.trim() ?? normalized;
+    return { systemPrompt: body, description };
+}
+function buildAgentPrompt(opts) {
+    return [
+        `You are the "${opts.agentName}" sub-agent. ${opts.description}`,
+        '',
+        '<system-prompt>',
+        opts.systemPrompt,
+        '</system-prompt>',
+        '',
+        'TASK:',
+        opts.task,
+        '',
+        'Respond with the deliverable — concise, focused on the task. No preamble.',
+    ].join('\n');
+}
+export async function invokeAgent(opts) {
+    // Phase 3 critic fix: depth 외에 fan-out 도 제한.
+    // depth 2 에서 N 개 sibling invoke 가 동시 시작되면 N² child spawn 가능 →
+    // 비용/timeout cascading. process-level concurrency limit MAX_CONCURRENT 로 제한.
+    const currentDepth = parseInt(process.env.FORGEN_INVOKE_DEPTH ?? '0', 10);
+    if (currentDepth >= MAX_DEPTH) {
+        throw new Error(`invoke-agent: max recursion depth ${MAX_DEPTH} exceeded (current=${currentDepth})`);
+    }
+    if (activeInvocations >= MAX_CONCURRENT) {
+        throw new Error(`invoke-agent: max concurrent invocations ${MAX_CONCURRENT} reached (active=${activeInvocations}). ` +
+            'Sibling sub-agents must run sequentially.');
+    }
+    const { systemPrompt, description } = loadAgentDefinition(opts.agentName);
+    const prompt = buildAgentPrompt({ agentName: opts.agentName, description, systemPrompt, task: opts.task });
+    const startedAt = Date.now();
+    activeInvocations += 1;
+    try {
+        // Phase 3 critic fix: default timeout 60s → 90s (codex sandbox startup +
+        // 인증 + LLM 응답까지 60s 부족할 수 있음. tail latency 안전마진).
+        const result = execHost({
+            prompt,
+            timeout: opts.timeoutMs ?? 90000,
+            host: opts.host,
+            env: { FORGEN_INVOKE_DEPTH: String(currentDepth + 1) },
+        });
+        const durationMs = Date.now() - startedAt;
+        return {
+            agentName: opts.agentName,
+            host: result.host,
+            summary: result.message,
+            durationMs,
+            usage: result.usage,
+        };
+    }
+    finally {
+        activeInvocations -= 1;
+    }
+}

package/dist/host/parity-harness.d.ts

@@ -0,0 +1,62 @@
+/**
+ * BehavioralParityScenario harness — Multi-Host Core Design §10 우선순위 4
+ *
+ * "Claude 와 Codex 양쪽에서 같은 입력을 흘려보냈을 때 evidence 가 의미적으로 같다" 를
+ * 검증하는 골격. P4 단계에서는 *projection 사영 후 등가성* 만 검증한다 — 실 모델 호출은
+ * P6 (실 Codex CLI) 트랙.
+ *
+ * 본 harness 가 verify 하는 것:
+ *   1. 같은 forgen hook 입력에 대해 양쪽 host 의 raw 출력을 사영하면 의미 동치한 객체가 된다.
+ *   2. 사영 결과가 1원칙 (Claude reference) 의 행동 의도와 일치한다.
+ *
+ * verify 하지 않는 것 (P6 별도 트랙):
+ *   - 실제 Codex 모델이 같은 prompt 에 같은 행동을 보이는지
+ *   - 실제 Claude 모델과의 동작 동등성
+ */
+import type { HookEventInput, HookEventOutput } from '../core/types.js';
+import type { HostId, TrustLayerIntent } from '../core/trust-layer-intent.js';
+export interface BehavioralParityScenario {
+    readonly id: string;
+    /** 검증하려는 Trust Layer 의도. */
+    readonly intent: TrustLayerIntent;
+    readonly description: string;
+    /** hook 입력 (HookEventInput 동치). */
+    readonly input: HookEventInput;
+    /**
+     * 각 host 가 *내보낼 것으로 가정* 하는 raw 출력. P4 단계에서는 spec §18 source schema
+     * 기반 직접 작성. P6 단계에서는 실 Codex CLI 출력으로 대체.
+     */
+    readonly hostRaw: Record<HostId, unknown>;
+    /**
+     * 사영 후 의미 동치성을 검증할 키들.
+     * 예: ['continue', 'hookSpecificOutput.permissionDecision'].
+     * 각 key 는 . 으로 nested path 표현.
+     */
+    readonly compareKeys: ReadonlyArray<string>;
+}
+export interface ParityCheckResult {
+    readonly scenarioId: string;
+    readonly intent: TrustLayerIntent;
+    readonly passed: boolean;
+    readonly diffs: ReadonlyArray<{
+        key: string;
+        claude: unknown;
+        codex: unknown;
+    }>;
+    /** 사영 결과 자체 (디버깅용). */
+    readonly projected: Readonly<Record<HostId, HookEventOutput>>;
+}
+export declare function runScenario(scenario: BehavioralParityScenario): ParityCheckResult;
+/**
+ * P4 1차 시나리오 corpus — Trust Layer 7 의도 중 hook 출력으로 직접 관측 가능한 5종.
+ * (`forge-loop-state-inject` 는 inject-context 의 특수 케이스, `self-evidence-record` 는
+ * 파일 시스템 사이드이펙트라 본 corpus 가 아닌 별도 e2e 트랙.)
+ *
+ * P4 2차 추가 시나리오 (spec §10 우선순위 4 산출물, 2026-04-27):
+ *   - forge-loop-m1-inject-stale       : §17.1 fact 1 / M1 hook 1KB cap + stale tag
+ *   - block-tool-use-pretool-ask       : §9.0 block-tool-use row — Codex ask 값 동치
+ *   - stop-hook-reentry-guard          : §15 stop_hook_active=true 즉시 approve 경로
+ *   - posttooluse-general-block-only   : §9.0 secret-filter row partial — block decision 만 등가
+ *   - suppress-output-equivalence      : suppressOutput 동치성
+ */
+export declare const SCENARIO_CORPUS: ReadonlyArray<BehavioralParityScenario>;