@wooojin/forgen 0.4.0 → 0.4.3

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>;

package/dist/host/parity-harness.js

@@ -0,0 +1,283 @@
+/**
+ * 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 { equal as deepEqual } from 'node:assert/strict';
+import { getProjection } from './projection.js';
+function pickPath(obj, dotted) {
+    const parts = dotted.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (cur && typeof cur === 'object' && p in cur) {
+            cur = cur[p];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+function valuesSemanticEqual(a, b) {
+    try {
+        deepEqual(a, b);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function runScenario(scenario) {
+    const projected = {
+        claude: getProjection('claude')(scenario.hostRaw.claude, scenario.input),
+        codex: getProjection('codex')(scenario.hostRaw.codex, scenario.input),
+    };
+    const diffs = [];
+    for (const key of scenario.compareKeys) {
+        const cv = pickPath(projected.claude, key);
+        const xv = pickPath(projected.codex, key);
+        if (!valuesSemanticEqual(cv, xv)) {
+            diffs.push({ key, claude: cv, codex: xv });
+        }
+    }
+    return {
+        scenarioId: scenario.id,
+        intent: scenario.intent,
+        passed: diffs.length === 0,
+        diffs,
+        projected,
+    };
+}
+/**
+ * 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 const SCENARIO_CORPUS = [
+    {
+        id: 'block-completion-stop',
+        intent: 'block-completion',
+        description: 'Stop hook 이 block + reason 으로 자동 continuation 트리거',
+        input: { hookEventName: 'Stop', stop_hook_active: false },
+        hostRaw: {
+            claude: { decision: 'block', reason: 'tests not yet executed' },
+            codex: { decision: 'block', reason: 'tests not yet executed' },
+        },
+        compareKeys: [
+            'continue',
+            'hookSpecificOutput.permissionDecision',
+        ],
+    },
+    {
+        id: 'block-tool-use-pretool-deny',
+        intent: 'block-tool-use',
+        description: 'PreToolUse 가 permissionDecision:deny + reason 으로 도구 차단',
+        input: { hookEventName: 'PreToolUse', tool_name: 'Bash' },
+        hostRaw: {
+            claude: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: 'rm -rf / matched',
+                },
+            },
+            codex: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: 'rm -rf / matched',
+                },
+            },
+        },
+        compareKeys: [
+            'hookSpecificOutput.permissionDecision',
+            'hookSpecificOutput.permissionDecisionReason',
+        ],
+    },
+    {
+        id: 'inject-context-session-start',
+        intent: 'inject-context',
+        description: 'SessionStart 가 additionalContext 로 forge-loop state 주입',
+        input: { hookEventName: 'SessionStart' },
+        hostRaw: {
+            claude: {
+                hookSpecificOutput: {
+                    hookEventName: 'SessionStart',
+                    additionalContext: '<forge-loop-state>...</forge-loop-state>',
+                },
+            },
+            codex: {
+                hookSpecificOutput: {
+                    hookEventName: 'SessionStart',
+                    additionalContext: '<forge-loop-state>...</forge-loop-state>',
+                },
+            },
+        },
+        compareKeys: [
+            'continue',
+            'hookSpecificOutput.additionalContext',
+        ],
+    },
+    {
+        id: 'observe-only-non-allowlist',
+        intent: 'observe-only',
+        description: 'ALLOW-LIST 외 hook 이 deny 시도 시 approve 강등',
+        input: { hookEventName: 'PreToolUse' },
+        hostRaw: {
+            claude: { continue: true },
+            codex: { continue: true },
+        },
+        compareKeys: ['continue'],
+    },
+    {
+        id: 'secret-filter-pretooluse-block',
+        intent: 'secret-filter',
+        description: 'API 키 노출 차단 — PreToolUse 가드 (양쪽 동일 경로)',
+        input: { hookEventName: 'PreToolUse', tool_name: 'Bash' },
+        hostRaw: {
+            claude: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: 'API_KEY=... matched',
+                },
+            },
+            codex: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: 'API_KEY=... matched',
+                },
+            },
+        },
+        compareKeys: [
+            'hookSpecificOutput.permissionDecision',
+            'hookSpecificOutput.permissionDecisionReason',
+        ],
+    },
+    // ── P4 2차 추가 시나리오 ────────────────────────────────────────────────────
+    {
+        id: 'forge-loop-m1-inject-stale',
+        intent: 'forge-loop-state-inject',
+        description: 'SessionStart 가 stale="true" 태그 포함 forge-loop-state 를 1KB cap 내에서 inject (spec §17.1 fact 1 / M1 hook)',
+        input: { hookEventName: 'SessionStart' },
+        hostRaw: {
+            claude: {
+                hookSpecificOutput: {
+                    hookEventName: 'SessionStart',
+                    additionalContext: '<forge-loop-state stale="true">{"phase":"M1","lastCompletedAt":"2026-04-26T22:00:00Z"}</forge-loop-state>',
+                },
+            },
+            codex: {
+                hookSpecificOutput: {
+                    hookEventName: 'SessionStart',
+                    additionalContext: '<forge-loop-state stale="true">{"phase":"M1","lastCompletedAt":"2026-04-26T22:00:00Z"}</forge-loop-state>',
+                },
+            },
+        },
+        compareKeys: [
+            'continue',
+            'hookSpecificOutput.additionalContext',
+        ],
+    },
+    {
+        id: 'block-tool-use-pretool-ask',
+        intent: 'block-tool-use',
+        description: 'Codex PreToolUse permissionDecision:"ask" 가 Claude ask 값과 의미 동치 — forgen denyOrObserve 의 ask 의도 (spec §9.0 block-tool-use row 메모)',
+        input: { hookEventName: 'PreToolUse', tool_name: 'Bash' },
+        hostRaw: {
+            claude: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'ask',
+                    permissionDecisionReason: 'requires human confirmation',
+                },
+            },
+            codex: {
+                hookSpecificOutput: {
+                    hookEventName: 'PreToolUse',
+                    permissionDecision: 'ask',
+                    permissionDecisionReason: 'requires human confirmation',
+                },
+            },
+        },
+        compareKeys: [
+            'hookSpecificOutput.permissionDecision',
+            'hookSpecificOutput.permissionDecisionReason',
+        ],
+    },
+    {
+        id: 'stop-hook-reentry-guard',
+        intent: 'block-completion',
+        description: 'stop_hook_active=true 시 Stop hook 이 즉시 approve(continue:true) 로 빠지는 재진입 가드 (spec §15)',
+        input: { hookEventName: 'Stop', stop_hook_active: true },
+        hostRaw: {
+            claude: { continue: true },
+            codex: { continue: true },
+        },
+        compareKeys: ['continue'],
+    },
+    {
+        id: 'posttooluse-general-block-only',
+        intent: 'secret-filter',
+        description: 'PostToolUse 일반 tool — Codex 는 redact 미보장이므로 block decision 만 양쪽 등가. updatedMCPToolOutput 없음 (spec §9.0 secret-filter row partial / §18.2 fact 4)',
+        input: { hookEventName: 'PostToolUse', tool_name: 'Bash' },
+        hostRaw: {
+            claude: {
+                hookSpecificOutput: {
+                    hookEventName: 'PostToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: 'SECRET=... detected in tool output',
+                },
+            },
+            codex: {
+                hookSpecificOutput: {
+                    hookEventName: 'PostToolUse',
+                    permissionDecision: 'deny',
+                    permissionDecisionReason: 'SECRET=... detected in tool output',
+                },
+            },
+        },
+        compareKeys: [
+            'hookSpecificOutput.permissionDecision',
+            'hookSpecificOutput.permissionDecisionReason',
+        ],
+    },
+    {
+        id: 'suppress-output-equivalence',
+        intent: 'observe-only',
+        description: 'PostToolUse suppressOutput=true 가 양쪽 host 에서 동치로 사영됨',
+        input: { hookEventName: 'PostToolUse', tool_name: 'Read' },
+        hostRaw: {
+            claude: {
+                continue: true,
+                suppressOutput: true,
+            },
+            codex: {
+                continue: true,
+                suppressOutput: true,
+            },
+        },
+        compareKeys: [
+            'continue',
+            'suppressOutput',
+        ],
+    },
+];

package/dist/host/projection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ProjectToClaudeEvent — Multi-Host Core Design §5.2 / §10 우선순위 2
+ *
+ * Codex (또는 미래의 다른 host) 의 hook 출력을 Claude Hook schema 로 사영하는
+ * 정식 계약. spec §17.4 / §18.4 에서 검증되었듯 schema-level 에서 거의 identity 이므로
+ * 본 함수는 *형식 정규화* 만 책임진다.
+ *
+ * - 입력: host-native 출력(JSON object, plaintext, exit-code 등은 별도 layer 에서 처리)
+ * - 출력: Claude HookEventOutput 동치 — `continue`, `hookSpecificOutput.permissionDecision`, etc.
+ * - 실패 정책: parse 실패 / 알 수 없는 형식 → fail-open (`{ continue: true }`)
+ *
+ * 본 모듈은 host 측 표면을 *모르고*, 받은 raw 의 형태만으로 동작한다 (1원칙: core 는 Claude
+ * semantics 알아도 됨, Codex 표면 모름). 즉 Codex CLI 의 stdout 을 받아 코어가 학습 가능한
+ * Claude 형 객체로 변환만 한다.
+ */
+import type { HookEventInput, HookEventOutput } from '../core/types.js';
+import type { HostId } from '../core/trust-layer-intent.js';
+export type ProjectToClaudeEvent = (raw: unknown, input: HookEventInput) => HookEventOutput;
+/**
+ * Codex 출력 → Claude HookEventOutput 정식 사영.
+ *
+ * spec §18.2 fact #3 에 따라 PreToolUse 의 *이중* decision 필드 중 어댑터는
+ * `hookSpecificOutput.permissionDecision` 을 우선한다. 본 함수가 그 규약을 강제.
+ */
+export declare const projectCodexToClaude: ProjectToClaudeEvent;
+/**
+ * Claude 어댑터의 사영. 1원칙(Claude reference) + spec §18.4 (Codex hooks.json schema 동일성)
+ * 에 따라 본 함수는 `projectCodexToClaude` 와 *같은 normalize 로직* 을 공유한다.
+ * 둘 다 같은 canonical Claude HookEventOutput 형식을 만든다.
+ *
+ * (왜 두 함수를 별도 export 하는가: 향후 schema 가 다른 host 가 추가될 때 본 binding 만
+ * 교체하면 되도록 — `getProjection(host)` 가 단일 진입점.)
+ */
+export declare const projectClaudeToClaude: ProjectToClaudeEvent;
+export declare function getProjection(host: HostId): ProjectToClaudeEvent;