@wooojin/forgen 0.4.13 → 0.5.5

package/dist/host/exec-host.d.ts

@@ -9,7 +9,13 @@
  * 호환성: 기존 'claude -p prompt --model haiku' 호출은 default_host 가 'claude' 인
  * 경우 동일 동작. Codex 메인 사용자는 자동으로 codex exec --json 호출.
  */
+import type { HostId } from '../core/trust-layer-intent.js';
 export interface ExecHostOptions {
+    /**
+     * ADR-015 C-G1: forgen 훅을 끄고(FORGEN_NESTED_RUN=1) 세션을 남기지 않는 "추출용 중첩 실행" 모드.
+     * 기본 true. 위임 에이전트(invoke-agent)처럼 훅이 살아 있어야 하는 호출은 false.
+     */
+    nestedRun?: boolean;
     /** prompt — `-p`/`exec` 의 본문 */
     prompt: string;
     /** model 힌트 (claude: --model haiku, codex: 무시 — codex CLI 가 default 사용) */
@@ -19,7 +25,7 @@ export interface ExecHostOptions {
     /** working directory */
     cwd?: string;
     /** explicit host override (default: profile.default_host). */
-    host?: 'claude' | 'codex';
+    host?: HostId;
     /** ENV vars 추가 (기존 process.env 위에 머지) */
     env?: NodeJS.ProcessEnv;
 }
@@ -30,10 +36,10 @@ export interface ExecHostOptions {
  *     30s default 가 false-positive ETIMEDOUT 발생. 90s 마진 필요.
  *   - 명시 timeout 옵션은 그대로 우선.
  */
-export declare const DEFAULT_TIMEOUT_BY_HOST: Record<'claude' | 'codex', number>;
+export declare const DEFAULT_TIMEOUT_BY_HOST: Record<HostId, number>;
 export interface ExecHostResult {
     message: string;
-    host: 'claude' | 'codex';
+    host: HostId;
     /** 토큰 사용량 (codex 만 노출. claude 는 null). */
     usage: {
         input_tokens?: number;
@@ -49,6 +55,11 @@ export interface ExecHostResult {
  * 보장 (사용자 환경 미오염). compound-extractor / auto-compound-runner 같은
  * 백그라운드 학습 호출에 적합.
  */
+/** ADR-015 C-G1 — forgen 이 띄우는 중첩 claude 실행의 공통 표식. hook-config.isHookEnabled 가 읽는다. */
+export declare const NESTED_RUN_ENV: Readonly<Record<string, string>>;
+/** `--no-session-persistence` 는 --print 전용 — 추출 run 의 transcript 를 디스크에 남기지 않는다. */
+export declare const NESTED_RUN_CLAUDE_ARGS: ReadonlyArray<string>;
+export declare function withNestedRunClaudeArgs(args: string[]): string[];
 export declare function execHost(opts: ExecHostOptions): ExecHostResult;
 /** 1회 retry — transient 에러(ETIMEDOUT 등) 대응. */
 export declare function execHostRetry(opts: ExecHostOptions): ExecHostResult;

package/dist/host/exec-host.js

@@ -22,6 +22,8 @@ import { parseCodexJsonlOutput } from './codex-output-parser.js';
 export const DEFAULT_TIMEOUT_BY_HOST = {
     claude: 30_000,
     codex: 90_000,
+    // opencode headless CLI: reasoning-mode 응답이 codex 처럼 길 수 있어 넉넉히(P1 실측 후 조정).
+    opencode: 90_000,
 };
 /**
  * 실 host CLI 를 호출하여 prompt 응답 받기.
@@ -32,6 +34,13 @@ export const DEFAULT_TIMEOUT_BY_HOST = {
  * 보장 (사용자 환경 미오염). compound-extractor / auto-compound-runner 같은
  * 백그라운드 학습 호출에 적합.
  */
+/** ADR-015 C-G1 — forgen 이 띄우는 중첩 claude 실행의 공통 표식. hook-config.isHookEnabled 가 읽는다. */
+export const NESTED_RUN_ENV = { FORGEN_NESTED_RUN: '1' };
+/** `--no-session-persistence` 는 --print 전용 — 추출 run 의 transcript 를 디스크에 남기지 않는다. */
+export const NESTED_RUN_CLAUDE_ARGS = ['--no-session-persistence'];
+export function withNestedRunClaudeArgs(args) {
+    return args.includes('--no-session-persistence') ? args : [...args, ...NESTED_RUN_CLAUDE_ARGS];
+}
 export function execHost(opts) {
     const resolved = resolveDefaultHost(opts.host);
     // 'ask' 는 자동 호출 컨텍스트라 명시 fallback. 그러나 Codex-only 사용자가 'ask'
@@ -51,10 +60,14 @@ export function execHost(opts) {
         env: { ...process.env, ...(opts.env ?? {}) },
     };
     if (host === 'claude') {
-        const args = ['-p', opts.prompt];
+        // ADR-015 C-G1: 중첩 실행 표식 + 세션 비영속 (추출 run 의 transcript 가 다음 SessionStart 의
+        // "이전 세션 auto-compound" 후보로 잡히거나 forgen 훅이 재귀 발화하지 않도록).
+        const nested = opts.nestedRun ?? true;
+        const args = ['-p', opts.prompt, ...(nested ? NESTED_RUN_CLAUDE_ARGS : [])];
         if (opts.model)
             args.push('--model', opts.model);
-        const stdout = execFileSync('claude', args, baseOpts);
+        const env = nested ? { ...(baseOpts.env ?? {}), ...NESTED_RUN_ENV } : baseOpts.env;
+        const stdout = execFileSync('claude', args, { ...baseOpts, env });
         return { message: stdout.toString().trim(), host: 'claude', usage: null };
     }
     // host === 'codex'

package/dist/host/host-binding.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HostBinding — Multi-Harness Adapter Plan P0 (`reports/harness-probe/adapter-plan-2026-07-20.md` §4.1)
+ *
+ * `prepareHarness` 의 host if-ladder (`harness.ts:447-479`) 를 formalize 한 계약.
+ * 각 host 는 capabilities 선언(`capabilities-registry.ts`) + projection 함수(`projection.ts`) +
+ * 세션 준비 단계(hook-surface wiring, 구 if-ladder 분기)를 하나의 등록 단위로 묶는다.
+ *
+ * `Record<HostId, HostBinding>` 완전성 요구로, 새 host 를 `HostId` 에 추가하면 registry
+ * 엔트리 누락이 컴파일 타임에 걸린다 (§4.2 P1 OpenCode 확장의 전제 조건).
+ */
+import type { HostCapabilities, HostId } from '../core/trust-layer-intent.js';
+import type { ProjectToClaudeEvent } from './projection.js';
+import type { V1BootstrapResult } from '../core/v1-bootstrap.js';
+/** `prepareHarness` 가 host-specific 세션 준비 단계에 넘기는 컨텍스트. */
+export interface HarnessSessionContext {
+    readonly cwd: string;
+    readonly pkgRoot: string;
+    readonly env: Record<string, string>;
+    readonly v1Result: V1BootstrapResult;
+}
+export interface HostBinding {
+    readonly id: HostId;
+    readonly capabilities: HostCapabilities;
+    readonly projection: ProjectToClaudeEvent;
+    /** harness.ts 의 host-specific artifact 준비 단계 (구 if-ladder 분기 대체). */
+    prepareSession(ctx: HarnessSessionContext): Promise<void>;
+}

package/dist/host/host-binding.js

@@ -0,0 +1,11 @@
+/**
+ * HostBinding — Multi-Harness Adapter Plan P0 (`reports/harness-probe/adapter-plan-2026-07-20.md` §4.1)
+ *
+ * `prepareHarness` 의 host if-ladder (`harness.ts:447-479`) 를 formalize 한 계약.
+ * 각 host 는 capabilities 선언(`capabilities-registry.ts`) + projection 함수(`projection.ts`) +
+ * 세션 준비 단계(hook-surface wiring, 구 if-ladder 분기)를 하나의 등록 단위로 묶는다.
+ *
+ * `Record<HostId, HostBinding>` 완전성 요구로, 새 host 를 `HostId` 에 추가하면 registry
+ * 엔트리 누락이 컴파일 타임에 걸린다 (§4.2 P1 OpenCode 확장의 전제 조건).
+ */
+export {};

package/dist/host/host-runtime.js

@@ -41,9 +41,27 @@ const codexRuntime = {
     hookInjectionStrategy: 'generate',
     dangerousSkipFlag: '--dangerously-bypass-approvals-and-sandbox',
 };
+/**
+ * OpenCode runtime — P1 파운데이션 스텁. OpenCode 는 subprocess-hook 이 아니라 in-process
+ * plugin 형태라(plan §2.2), hook wrapping 은 plugin 슬림(`install-opencode` 미구현)이 담당한다.
+ * launcher(headless `opencode` CLI)와 라벨만 실값; wrapHookCommand 는 슬림 착지 전까지 fail-loud.
+ */
+const opencodeRuntime = {
+    id: 'opencode',
+    displayName: 'OpenCode',
+    launcher: 'opencode',
+    missingInstallMessage: 'OpenCode is not installed.',
+    wrapHookCommand() {
+        throw new Error('[forgen] OpenCode hook wrapping은 in-process plugin 슬림(install-opencode)이 담당합니다 — P1 미구현.');
+    },
+    // in-process plugin 이라 subprocess hook 생성 전략과 무관. 슬림 착지 시 재정의.
+    hookInjectionStrategy: 'generate',
+    dangerousSkipFlag: '',
+};
 const RUNTIMES = {
     claude: claudeRuntime,
     codex: codexRuntime,
+    opencode: opencodeRuntime,
 };
 export function getHostRuntime(runtime) {
     const r = RUNTIMES[runtime];

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

@@ -44,5 +44,71 @@ export interface CodexInstallResult {
     devGuideSkillsPath: string;
     devGuideSkillsInstalled: number;
     devGuideSkillsRemoved: number;
+    /** ADR-014 D2: ~/.codex/agents/ch-*.toml 커스텀 에이전트 설치 결과 */
+    agentsPath: string;
+    agentsInstalled: number;
+    agentsRemoved: number;
+    /** ADR-014 D4: hooks.json forgen 엔트리 중 config.toml hooks.state 에 신뢰 기록이 있는 수 */
+    hookTrust: CodexHookTrustAudit;
+    /** ADR-014 D2: config.toml `[features] multi_agent = true` 여부 (false 면 ch-* 에이전트 spawn 불가 → 안내) */
+    multiAgentEnabled: boolean;
+}
+export interface CodexHookTrustAudit {
+    /** hooks.json 의 forgen hook 명령 수 (Codex 가 지원하는 이벤트만) */
+    total: number;
+    /** Codex 가 모르는 이벤트라 조용히 무시되는 forgen 엔트리 (`<event>:<i>:<j>`) — trust 대상이 아님 */
+    ignoredByCodex: string[];
+    /** config.toml `[hooks.state."<hooks.json>:<event>:<i>:<j>"]` 에 trusted_hash 가 있는 수 */
+    trusted: number;
+    /** 신뢰 기록이 없는 hook 키 (`<event>:<i>:<j>`) */
+    untrusted: string[];
+    /** config.toml 자체가 없거나 hooks.state 가 전혀 없으면 true (Codex 가 아직 한 번도 훅을 review 안 함) */
+    noStateRecorded: boolean;
+}
+interface HooksFile {
+    description?: string;
+    hooks: Record<string, Array<unknown>>;
 }
 export declare function planCodexInstall(opts: CodexInstallOptions): CodexInstallResult;
+/** `[features]` 섹션 안에 `multi_agent = true` 가 있는지 (TOML 라이브러리 없이 섹션 범위만 본다). */
+export declare function isCodexMultiAgentEnabled(configToml: string): boolean;
+/**
+ * Codex 0.153 hooks 공식 이벤트 12종 (learn.chatgpt.com/docs/hooks + binary 문자열). 이 밖의 이벤트
+ * (예: Claude 전용 PostToolUseFailure) 는 Codex 가 조용히 무시하므로 trust 대상이 아니다.
+ */
+export declare const CODEX_SUPPORTED_HOOK_EVENTS: ReadonlySet<string>;
+/** Codex 는 hooks.state 키에 이벤트명을 snake_case 로 쓴다 (PreToolUse → pre_tool_use). */
+export declare function codexHookEventKey(event: string): string;
+/**
+ * hooks.json 의 forgen 엔트리 각각에 대해 config.toml 의
+ * `[hooks.state."<hooksPath>:<event>:<groupIdx>:<hookIdx>"]` 섹션(trusted_hash) 존재를 대조한다.
+ * trusted_hash 자체는 검증하지 않는다 — Codex 가 변경된 훅을 review 전까지 skip 하는 정책을
+ * forgen 이 우회하지 않기 위해, *기록 유무* 만 가시화한다 (ADR-014 D4).
+ */
+export declare function auditCodexHookTrust(opts: {
+    hooksPath: string;
+    configTomlPath: string;
+    pkgRoot: string;
+    hooksFile?: HooksFile | null;
+    configToml?: string;
+}): CodexHookTrustAudit;
+/**
+ * Claude agent .md → Codex agent role TOML.
+ * 공식 스키마(필수 name/description/developer_instructions, 선택 model_reasoning_effort/sandbox_mode)
+ * 외 필드는 쓰지 않는다 — Codex 가 unknown field 를 거부 (ADR-014 D2).
+ */
+export declare function renderCodexAgentToml(file: string, raw: string): {
+    name: string;
+    toml: string;
+} | null;
+/** ADR-014 D3 — Codex 스킬에는 `$ARGUMENTS` 치환 변수가 없다. */
+export declare function adaptSkillBodyForCodex(body: string): string;
+export declare function resolveAgentsMdPath(_pkgRoot: string): string;
+export declare function upsertForgenRulesInAgentsMd(opts: {
+    agentsMdPath: string;
+    pkgRoot: string;
+    dryRun: boolean;
+}): {
+    injected: boolean;
+};
+export {};

package/dist/host/install-codex.js

@@ -85,29 +85,39 @@ export function planCodexInstall(opts) {
         releaseMode,
     });
     const generatedHooks = generated.hooks;
-    // 2) 기존 hooks.json 읽기 + forgen entry 제거 후 보존
+    // 2) 기존 hooks.json 읽기 — forgen 그룹은 *제자리에서* 교체, 사용자 그룹은 위치 그대로 보존.
+    //    (0.5.3 critic/실머신: 이전엔 사용자 그룹을 앞으로 모으고 forgen 을 뒤에 붙여 그룹 인덱스가
+    //    바뀌었고, Codex 의 trust 키 `<event>:<groupIdx>:<hookIdx>` 가 어긋나 20/21 → 12/21 로
+    //    훅 신뢰가 깨졌다. 바이트 동일성이 곧 신뢰 보존이다.)
     const existing = readJsonFile(hooksPath);
     const existingHooksByEvent = (existing?.hooks ?? {});
-    const preserved = {};
+    const eventOrder = [...new Set([...Object.keys(existingHooksByEvent), ...Object.keys(generatedHooks)])];
+    const merged = {};
     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) {
+    for (const event of eventOrder) {
+        const existingGroups = Array.isArray(existingHooksByEvent[event]) ? existingHooksByEvent[event] : [];
+        const generatedGroups = generatedHooks[event] ?? [];
+        const out = [];
+        let inserted = false;
+        for (const group of existingGroups) {
+            if (isForgenManagedHook(group, opts.pkgRoot)) {
+                if (!inserted) {
+                    out.push(...generatedGroups);
+                    inserted = true;
+                }
+                // 이후 중복 forgen 그룹은 드롭 (stale 누적 방지)
+            }
+            else {
+                out.push(group);
+                preservedCount += 1;
+            }
+        }
+        if (!inserted && generatedGroups.length > 0)
+            out.push(...generatedGroups);
+        if (out.length > 0)
+            merged[event] = out;
+        for (const group of generatedGroups) {
             const g = group;
             if (Array.isArray(g.hooks))
                 forgenCount += g.hooks.length;
@@ -156,6 +166,21 @@ export function planCodexInstall(opts) {
         codexHome,
         dryRun: opts.dryRun ?? false,
     });
+    // 9) ADR-014 D2: assets/claude/agents/*.md → ~/.codex/agents/ch-<name>.toml
+    const codexAgents = installCodexAgents({
+        sourceDir: path.join(opts.pkgRoot, 'assets', 'claude', 'agents'),
+        targetDir: path.join(codexHome, 'agents'),
+        dryRun: opts.dryRun ?? false,
+    });
+    // 10) ADR-014 D4: 훅 신뢰 감사 (dryRun 이면 현재 디스크 상태 기준)
+    const hookTrust = auditCodexHookTrust({
+        hooksPath,
+        configTomlPath,
+        pkgRoot: opts.pkgRoot,
+        hooksFile: opts.dryRun ? (existing ?? finalHooksFile) : finalHooksFile,
+        configToml: mcpContentToWrite ?? (fs.existsSync(configTomlPath) ? fs.readFileSync(configTomlPath, 'utf-8') : ''),
+    });
+    const multiAgentEnabled = isCodexMultiAgentEnabled(mcpContentToWrite ?? (fs.existsSync(configTomlPath) ? fs.readFileSync(configTomlPath, 'utf-8') : ''));
     return {
         codexHome,
         hooksPath,
@@ -172,8 +197,230 @@ export function planCodexInstall(opts) {
         devGuideSkillsPath: devGuideResult.devGuideSkillsPath,
         devGuideSkillsInstalled: devGuideResult.devGuideSkillsInstalled,
         devGuideSkillsRemoved: devGuideResult.devGuideSkillsRemoved,
+        agentsPath: codexAgents.agentsPath,
+        agentsInstalled: codexAgents.installed,
+        agentsRemoved: codexAgents.removed,
+        hookTrust,
+        multiAgentEnabled,
     };
 }
+/** `[features]` 섹션 안에 `multi_agent = true` 가 있는지 (TOML 라이브러리 없이 섹션 범위만 본다). */
+export function isCodexMultiAgentEnabled(configToml) {
+    const m = configToml.match(/^\[features\]\s*$([\s\S]*?)(?=^\[|(?![\s\S]))/m);
+    if (!m)
+        return false;
+    return /^\s*multi_agent\s*=\s*true\s*$/m.test(m[1]);
+}
+// ── ADR-014 D4: Codex hook trust audit ────────────────────────────────
+/**
+ * Codex 0.153 hooks 공식 이벤트 12종 (learn.chatgpt.com/docs/hooks + binary 문자열). 이 밖의 이벤트
+ * (예: Claude 전용 PostToolUseFailure) 는 Codex 가 조용히 무시하므로 trust 대상이 아니다.
+ */
+export const CODEX_SUPPORTED_HOOK_EVENTS = new Set([
+    'PreToolUse', 'PermissionRequest', 'PostToolUse', 'PreCompact', 'PostCompact', 'UserPromptSubmit',
+    'SubagentStart', 'SubagentStop', 'Stop', 'Interrupt', 'SessionStart', 'SessionEnd',
+]);
+/** Codex 는 hooks.state 키에 이벤트명을 snake_case 로 쓴다 (PreToolUse → pre_tool_use). */
+export function codexHookEventKey(event) {
+    return event.replace(/(?<!^)([A-Z])/g, '_$1').toLowerCase();
+}
+/**
+ * hooks.json 의 forgen 엔트리 각각에 대해 config.toml 의
+ * `[hooks.state."<hooksPath>:<event>:<groupIdx>:<hookIdx>"]` 섹션(trusted_hash) 존재를 대조한다.
+ * trusted_hash 자체는 검증하지 않는다 — Codex 가 변경된 훅을 review 전까지 skip 하는 정책을
+ * forgen 이 우회하지 않기 위해, *기록 유무* 만 가시화한다 (ADR-014 D4).
+ */
+export function auditCodexHookTrust(opts) {
+    const hooksFile = opts.hooksFile ?? readJsonFile(opts.hooksPath);
+    const toml = opts.configToml ?? (fs.existsSync(opts.configTomlPath) ? fs.readFileSync(opts.configTomlPath, 'utf-8') : '');
+    const stateKeys = new Set();
+    const re = /^\[hooks\.state\."([^"]+)"\]\s*$/gm;
+    let m = re.exec(toml);
+    while (m !== null) {
+        stateKeys.add(m[1]);
+        m = re.exec(toml);
+    }
+    let total = 0;
+    let trusted = 0;
+    const untrusted = [];
+    const ignoredByCodex = [];
+    const events = (hooksFile?.hooks ?? {});
+    for (const [event, groups] of Object.entries(events)) {
+        if (!Array.isArray(groups))
+            continue;
+        groups.forEach((group, gi) => {
+            const g = group;
+            if (!Array.isArray(g.hooks))
+                return;
+            g.hooks.forEach((h, hi) => {
+                const isForgen = typeof h.command === 'string' &&
+                    (h.command.includes(opts.pkgRoot) || FORGEN_HOOK_SCRIPT_MARKER.test(h.command));
+                if (!isForgen)
+                    return;
+                const key = `${codexHookEventKey(event)}:${gi}:${hi}`;
+                if (!CODEX_SUPPORTED_HOOK_EVENTS.has(event)) {
+                    ignoredByCodex.push(key);
+                    return;
+                }
+                total += 1;
+                if (stateKeys.has(`${opts.hooksPath}:${key}`))
+                    trusted += 1;
+                else
+                    untrusted.push(key);
+            });
+        });
+    }
+    return { total, trusted, untrusted, ignoredByCodex, noStateRecorded: stateKeys.size === 0 };
+}
+// ── ADR-014 D2: Codex custom agents (~/.codex/agents/ch-*.toml) ──────
+const AGENT_TOML_MARKER = '# forgen-managed';
+const AGENT_NAME_PREFIX = 'ch-';
+function parseAgentMarkdown(raw) {
+    const fm = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!fm)
+        return null;
+    const meta = {};
+    const tools = [];
+    const disallowedTools = [];
+    let currentList = null;
+    for (const line of fm[1].split('\n')) {
+        const listItem = line.match(/^\s+-\s+(.+)$/);
+        if (currentList && listItem) {
+            currentList.push(listItem[1].trim());
+            continue;
+        }
+        currentList = null;
+        const kv = line.match(/^([A-Za-z_]+):\s*(.*)$/);
+        if (!kv)
+            continue;
+        const [, k, v] = kv;
+        if (k === 'tools' || k === 'disallowedTools') {
+            const target = k === 'tools' ? tools : disallowedTools;
+            // 인라인 배열 `tools: [Read, Bash]` 도 허용
+            const inline = v.trim().match(/^\[(.*)\]$/);
+            if (inline)
+                target.push(...inline[1].split(',').map((t) => t.trim()).filter(Boolean));
+            else
+                currentList = target;
+            continue;
+        }
+        meta[k] = v.trim();
+    }
+    return { meta, tools, disallowedTools, body: fm[2].trim() };
+}
+/** TOML 문자열에 들어갈 수 없는 제어문자 제거 (탭/개행/CR 은 유지). */
+function stripTomlControlChars(v) {
+    let out = '';
+    for (const ch of v) {
+        const code = ch.charCodeAt(0);
+        const isAllowed = (code >= 0x20 && code !== 0x7f) || code === 0x09 || code === 0x0a || code === 0x0d;
+        if (isAllowed)
+            out += ch;
+    }
+    return out;
+}
+/** TOML basic string (한 줄). JSON 문자열 문법은 TOML basic string 의 부분집합. */
+function tomlString(v) {
+    return JSON.stringify(stripTomlControlChars(v));
+}
+/** TOML multi-line basic string. 백슬래시와 삼중따옴표만 이스케이프하면 된다. */
+function tomlMultiline(v) {
+    const cleaned = stripTomlControlChars(v)
+        .split('\\').join('\\\\')
+        .split('"""').join('\\"\\"\\"');
+    return `"""\n${cleaned}\n"""`;
+}
+const REASONING_BY_CLAUDE_MODEL = { opus: 'high', sonnet: 'medium', haiku: 'low' };
+/**
+ * Claude agent .md → Codex agent role TOML.
+ * 공식 스키마(필수 name/description/developer_instructions, 선택 model_reasoning_effort/sandbox_mode)
+ * 외 필드는 쓰지 않는다 — Codex 가 unknown field 를 거부 (ADR-014 D2).
+ */
+export function renderCodexAgentToml(file, raw) {
+    const parsed = parseAgentMarkdown(raw);
+    if (!parsed)
+        return null;
+    const base = file.replace(/\.md$/, '');
+    const name = base.startsWith(AGENT_NAME_PREFIX) ? base : `${AGENT_NAME_PREFIX}${base}`;
+    if (!/^[A-Za-z0-9 _-]+$/.test(name))
+        return null;
+    const description = parsed.meta.description || name;
+    // critic 2026-10-01: 7/14 에이전트는 `tools:` 대신 `disallowedTools: [Write, Edit]` 로 읽기전용을 선언.
+    const WRITE_TOOLS = new Set(['Write', 'Edit', 'NotebookEdit']);
+    const canWrite = parsed.tools.length > 0
+        ? parsed.tools.some((t) => WRITE_TOOLS.has(t))
+        : !parsed.disallowedTools.some((t) => WRITE_TOOLS.has(t));
+    const sandbox = canWrite ? 'workspace-write' : 'read-only';
+    const effort = REASONING_BY_CLAUDE_MODEL[parsed.meta.model ?? ''] ?? 'medium';
+    const body = parsed.body.length > 0 ? parsed.body : description;
+    const toml = [
+        AGENT_TOML_MARKER,
+        `# generated by \`forgen install codex\` from assets/claude/agents/${file} — do not edit; re-generated on install`,
+        `name = ${tomlString(name)}`,
+        `description = ${tomlString(description)}`,
+        `model_reasoning_effort = ${tomlString(effort)}`,
+        `sandbox_mode = ${tomlString(sandbox)}`,
+        `developer_instructions = ${tomlMultiline(body)}`,
+        '',
+    ].join('\n');
+    return { name, toml };
+}
+function installCodexAgents(opts) {
+    const { sourceDir, targetDir, dryRun } = opts;
+    if (!fs.existsSync(sourceDir))
+        return { agentsPath: targetDir, installed: 0, removed: 0 };
+    const files = fs.readdirSync(sourceDir).filter((f) => f.endsWith('.md'));
+    const isUserOwned = (p) => {
+        try {
+            const st = fs.lstatSync(p);
+            if (st.isSymbolicLink())
+                return true; // 사용자 심링크 (dangling 포함) — 건드리지 않음
+            return !fs.readFileSync(p, 'utf-8').slice(0, 64).startsWith(AGENT_TOML_MARKER);
+        }
+        catch {
+            return false; // 없음
+        }
+    };
+    if (dryRun) {
+        const wouldInstall = files.filter((f) => {
+            const r = renderCodexAgentToml(f, fs.readFileSync(path.join(sourceDir, f), 'utf-8'));
+            return r !== null && !isUserOwned(path.join(targetDir, `${r.name}.toml`));
+        }).length;
+        return { agentsPath: targetDir, installed: wouldInstall, removed: 0 };
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    // stale 정리: forgen-managed 마커가 있는 ch-*.toml 만. 사용자 파일은 보존.
+    let removed = 0;
+    for (const entry of fs.readdirSync(targetDir)) {
+        if (!entry.startsWith(AGENT_NAME_PREFIX) || !entry.endsWith('.toml'))
+            continue;
+        const p = path.join(targetDir, entry);
+        try {
+            if (fs.lstatSync(p).isSymbolicLink())
+                continue;
+            const head = fs.readFileSync(p, 'utf-8').slice(0, 64);
+            if (!head.startsWith(AGENT_TOML_MARKER))
+                continue;
+            fs.unlinkSync(p);
+            removed += 1;
+        }
+        catch { /* best-effort */ }
+    }
+    let installed = 0;
+    for (const file of files) {
+        const rendered = renderCodexAgentToml(file, fs.readFileSync(path.join(sourceDir, file), 'utf-8'));
+        if (!rendered)
+            continue;
+        const dst = path.join(targetDir, `${rendered.name}.toml`);
+        if (isUserOwned(dst)) {
+            // 방금 stale 정리에서 살아남은 = 사용자 작성 (마커 없음) 또는 심링크 → 보존
+            continue;
+        }
+        fs.writeFileSync(dst, rendered.toml, 'utf-8');
+        installed += 1;
+    }
+    return { agentsPath: targetDir, installed, removed };
+}
 // ── v0.4.9: dev-guide skills → ~/.codex/skills ────────────────────────
 // dev-guide prefix pattern: forgen-<stack>-<skill> (e.g. forgen-react-fe-build)
 // 반드시 stack 이 react|vue|node|go 인 것만 매칭 — forgen 자체 commands 보존
@@ -237,6 +484,27 @@ function installDevGuideSkillsToCodex(opts) {
     return { devGuideSkillsPath: codexSkillsDir, devGuideSkillsInstalled: installed, devGuideSkillsRemoved: removed };
 }
 // ── P3-3: Codex skills install ────────────────────────────────────────
+/** ADR-014 D3 — Codex 스킬에는 `$ARGUMENTS` 치환 변수가 없다. */
+export function adaptSkillBodyForCodex(body) {
+    return body
+        .replace(/\{\$ARGUMENTS\}/g, '{the user\'s request text}')
+        .replace(/`\$ARGUMENTS`/g, 'the user\'s request text (what follows the skill name)')
+        .replace(/\$ARGUMENTS/g, 'the user\'s request text (what follows the skill name)');
+}
+/** ADR-014 D2/D3 — 스킬 본문의 ch-* 에이전트 참조가 Codex 에서 어떻게 해석되는지 명시. */
+const CODEX_SKILL_HOST_NOTE = `
+---
+
+## Codex host note (forgen-managed)
+
+- Sub-agents named \`ch-*\` (ch-planner, ch-executor, ch-verifier, ch-critic, ...) are installed as Codex
+  custom agents under \`$CODEX_HOME/agents/ch-*.toml\`. Spawn them with Codex's multi-agent tools when
+  available (\`[features] multi_agent = true\` in config.toml).
+- If spawning is unavailable, call the \`invoke-agent\` tool on the \`forgen-compound\` MCP server
+  (agent_name + task) or perform that stage inline yourself. Do not skip the stage.
+- The forgen personalized rules for this session arrive as a \`<forgen-rules host="codex">\` block at
+  session start. Treat them exactly like Claude Code's .claude/rules/.
+`;
 function installCodexSkills(opts) {
     const { sourceDir, targetDir, dryRun } = opts;
     if (!fs.existsSync(sourceDir))
@@ -264,8 +532,8 @@ function installCodexSkills(opts) {
         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`;
+        const body = adaptSkillBodyForCodex(bodyMatch?.[1]?.trim() ?? raw);
+        const out = `---\nname: ${skillName}\ndescription: ${desc}\n---\n\n${FORGEN_SKILL_MARKER}\n\n${body}\n${CODEX_SKILL_HOST_NOTE}`;
         fs.mkdirSync(skillDir, { recursive: true });
         fs.writeFileSync(skillFile, out);
         count += 1;
@@ -273,7 +541,7 @@ function installCodexSkills(opts) {
     return { installed: count };
 }
 // ── P3-3: AGENTS.md inject ────────────────────────────────────────────
-function resolveAgentsMdPath(_pkgRoot) {
+export 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 자체.
@@ -297,7 +565,7 @@ function resolveAgentsMdPath(_pkgRoot) {
     return path.join(cwd, 'AGENTS.md');
 }
 function buildForgenRulesBlock(pkgRoot) {
-    // forgen 의 핵심 규칙 + 사용자 profile 안내 (가벼운 헤더만 — 실 rule 은 hook chain 이 inject)
+    // forgen 의 핵심 규칙 + 사용자 profile 안내 (가벼운 헤더만 — 실 rule 본문은 ADR-014 D1 의 SessionStart hook 주입)
     const lines = [
         AGENTS_MD_BEGIN,
         '## forgen managed rules',
@@ -307,13 +575,13 @@ function buildForgenRulesBlock(pkgRoot) {
         '- 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 경로로 흘러들어감.',
+        '- 개인화 룰 본문은 세션 시작 시 SessionStart hook 이 `<forgen-rules host="codex">` 블록으로 주입 (ADR-014). 서브에이전트는 ~/.codex/agents/ch-*.toml.',
         `- pkgRoot: ${pkgRoot}`,
         AGENTS_MD_END,
     ];
     return lines.join('\n');
 }
-function upsertForgenRulesInAgentsMd(opts) {
+export function upsertForgenRulesInAgentsMd(opts) {
     const { agentsMdPath, pkgRoot, dryRun } = opts;
     const block = buildForgenRulesBlock(pkgRoot);
     let current = '';

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

@@ -0,0 +1,38 @@
+/**
+ * install-opencode — forgen 을 OpenCode host 에 설치 (W3-3 P1).
+ *
+ * OpenCode 는 in-process TS plugin + opencode.json(c) MCP + AGENTS.md 를 쓴다:
+ *   1. plugin: `~/.config/opencode/plugins/forgen.ts` (assets/opencode/forgen.ts 배포).
+ *      GUARD_CMD 는 절대 forgen CLI 경로로 치환(런타임 PATH 비의존 — 리뷰 MED4).
+ *   2. MCP: 기존 config 파일(opencode.jsonc 우선, 없으면 opencode.json)에 mcp.forgen-compound
+ *      surgical 병합. **JSONC 파서(jsonc-parser)로 주석/trailing-comma 보존**, 쓰기 전 백업
+ *      (리뷰 HIGH: JSON.parse 가 공식 JSONC 를 clobber 하던 데이터 손실 수정).
+ *   3. AGENTS.md: cwd 의 forgen rules block (Codex 헬퍼 재사용).
+ */
+export interface OpencodeInstallOptions {
+    pkgRoot: string;
+    dryRun?: boolean;
+    registerMcp?: boolean;
+    /** ~/.config/opencode override (격리 테스트용). */
+    opencodeConfigDir?: string;
+    /** AGENTS.md 위치 override (격리 테스트용). */
+    agentsMdPath?: string;
+}
+export interface OpencodeInstallResult {
+    configDir: string;
+    pluginPath: string;
+    pluginInstalled: boolean;
+    /** 사용자 소유(비-managed) plugin 을 백업했으면 그 경로. */
+    pluginBackupPath?: string;
+    mcpRegistered: boolean;
+    mcpAlreadyPresent: boolean;
+    /** MCP 대상 config 파일(.jsonc 우선). */
+    mcpConfigPath: string;
+    /** 파싱 불가 config 라 MCP 를 건드리지 않고 abort 했으면 true(데이터 손실 방지). */
+    mcpSkippedUnparseable: boolean;
+    /** config 백업 경로(수정 전 .bak). */
+    mcpBackupPath?: string;
+    agentsMdInjected: boolean;
+}
+export declare function resolveOpencodeConfigDir(opts: OpencodeInstallOptions): string;
+export declare function planOpencodeInstall(opts: OpencodeInstallOptions): OpencodeInstallResult;