@wooojin/forgen 0.5.0 → 0.5.5

package/dist/hooks/session-recovery.js

@@ -153,13 +153,28 @@ async function main() {
         // 이전엔 prepareHarness (fgx/forgen wrapper) 만 호출 → 직접 claude/codex 호출 시
         // ~/.forgen/state/sessions/<id>.json 미생성. SessionStart hook 에서도 호출하여
         // 양쪽 진입 경로 모두에서 session state 박제.
+        let v1RenderedRules = null;
         try {
             const { bootstrapV1Session } = await import('../core/v1-bootstrap.js');
-            bootstrapV1Session();
+            v1RenderedRules = bootstrapV1Session().renderedRules;
         }
         catch (e) {
             log.debug('v1-bootstrap SessionStart 호출 실패 (fail-open)', e);
         }
+        // ADR-014 D1 — Codex 에는 .claude/rules/ 로드 표면이 없으므로 같은 룰을 SessionStart
+        // additionalContext 로 주입한다 (Claude 세션은 파일 경로로 이미 로드되므로 skip).
+        const codexRulesBlock = await (async () => {
+            try {
+                const { isCodexRuntime, buildCodexRulesContext } = await import('../host/codex-rules-context.js');
+                if (!isCodexRuntime())
+                    return null;
+                return await buildCodexRulesContext(sessionContext.cwd, v1RenderedRules);
+            }
+            catch (e) {
+                log.debug('codex rules inject 실패 (fail-open)', e);
+                return null;
+            }
+        })();
         if (!fs.existsSync(STATE_DIR)) {
             console.log(approve());
             return;
@@ -435,6 +450,8 @@ async function main() {
         catch (e) {
             log.debug('lifecycle check 실패', e);
         }
+        if (codexRulesBlock)
+            recoveryMessages.unshift(codexRulesBlock);
         if (recoveryMessages.length > 0) {
             console.log(approveWithContext(recoveryMessages.join('\n\n'), 'SessionStart'));
         }

package/dist/hooks/shared/hook-timing.js

@@ -16,9 +16,14 @@ const MAX_LINES = 500;
 // MAX_LINES × 1.5 여유를 둠.
 const ROTATE_SIZE_BYTES = MAX_LINES * 80 * 2; // ~80KB
 export function recordHookTiming(hookName, durationMs, event) {
+    // ADR-015 C-G1 (critic #2): 중첩 추출 run 의 빠른 early-approve 타이밍이 p95 를 왜곡하지 않도록 기록 생략.
+    if (process.env.FORGEN_NESTED_RUN === '1')
+        return;
     try {
         fs.mkdirSync(STATE_DIR, { recursive: true });
-        const entry = JSON.stringify({ hook: hookName, ms: durationMs, event, at: Date.now() });
+        // ADR-014 D5 — host 별 발화 구분 (codex-adapter 가 FORGEN_RUNTIME=codex 주입).
+        const rt = process.env.FORGEN_RUNTIME === 'codex' ? 'codex' : 'claude';
+        const entry = JSON.stringify({ hook: hookName, ms: durationMs, event, at: Date.now(), rt });
         fs.appendFileSync(TIMING_LOG, `${entry}\n`);
         // Rotate if too large — size-gated (statSync only, skip read/write 대부분의 호출)
         try {

package/dist/host/codex-rules-context.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Codex 개인화 룰 주입 — ADR-014 D1
+ *
+ * Claude 는 `.claude/rules/*.md` 파일을 Claude Code 가 매 턴 로드하지만 Codex 에는 그 표면이 없다.
+ * 본 모듈은 *같은 소스* (generateClaudeRuleFiles) 를 *같은 캡* (RULE_FILE_CAPS) 으로 렌더해
+ * SessionStart additionalContext 로 넣을 블록을 만든다. hooks.json 을 바꾸지 않기 위해 새 훅이
+ * 아니라 session-recovery 내부의 codex 분기에서 호출된다.
+ *
+ * 컴팩션 후 재주입은 별도 경로가 없다: Claude Code 와 Codex 모두 compaction 시 SessionStart 를
+ * source="compact" 로 다시 발화하므로 (Codex 공식 hooks 문서), 같은 경로가 한 번 더 돈다.
+ * (critic 리뷰 2026-10-01: PreCompact 플래그 경로는 2중 주입이라 제거.)
+ */
+export declare const FORGEN_RULES_TAG = "forgen-rules";
+/** codex-adapter 가 delegate hook 에 FORGEN_RUNTIME=codex 를 주입한다 (0.4.6+). */
+export declare function isCodexRuntime(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 룰 파일 맵 → 단일 additionalContext 블록. Claude 의 injectClaudeRuleFiles 와 동일 캡:
+ * 파일당 perRuleFile, 총량 totalRuleFiles. 캡 초과 파일은 잘리고, 총량 초과 시 이후 파일은 생략.
+ */
+export declare function renderCodexRulesBlock(ruleFiles: Record<string, string>): string | null;
+/**
+ * cwd + 렌더된 v1 룰 → Codex 주입 블록. config-injector 는 무거워서 lazy import.
+ * 실패 시 null (fail-open — 룰 주입 실패가 세션 시작을 막으면 안 된다).
+ */
+export declare function buildCodexRulesContext(cwd: string, renderedRules: string | null): Promise<string | null>;

package/dist/host/codex-rules-context.js

@@ -0,0 +1,62 @@
+/**
+ * Codex 개인화 룰 주입 — ADR-014 D1
+ *
+ * Claude 는 `.claude/rules/*.md` 파일을 Claude Code 가 매 턴 로드하지만 Codex 에는 그 표면이 없다.
+ * 본 모듈은 *같은 소스* (generateClaudeRuleFiles) 를 *같은 캡* (RULE_FILE_CAPS) 으로 렌더해
+ * SessionStart additionalContext 로 넣을 블록을 만든다. hooks.json 을 바꾸지 않기 위해 새 훅이
+ * 아니라 session-recovery 내부의 codex 분기에서 호출된다.
+ *
+ * 컴팩션 후 재주입은 별도 경로가 없다: Claude Code 와 Codex 모두 compaction 시 SessionStart 를
+ * source="compact" 로 다시 발화하므로 (Codex 공식 hooks 문서), 같은 경로가 한 번 더 돈다.
+ * (critic 리뷰 2026-10-01: PreCompact 플래그 경로는 2중 주입이라 제거.)
+ */
+import { RULE_FILE_CAPS } from '../hooks/shared/injection-caps.js';
+export const FORGEN_RULES_TAG = 'forgen-rules';
+/** codex-adapter 가 delegate hook 에 FORGEN_RUNTIME=codex 를 주입한다 (0.4.6+). */
+export function isCodexRuntime(env = process.env) {
+    return env.FORGEN_RUNTIME === 'codex';
+}
+/**
+ * 룰 파일 맵 → 단일 additionalContext 블록. Claude 의 injectClaudeRuleFiles 와 동일 캡:
+ * 파일당 perRuleFile, 총량 totalRuleFiles. 캡 초과 파일은 잘리고, 총량 초과 시 이후 파일은 생략.
+ */
+export function renderCodexRulesBlock(ruleFiles) {
+    const entries = Object.entries(ruleFiles).filter(([, c]) => typeof c === 'string' && c.trim().length > 0);
+    if (entries.length === 0)
+        return null;
+    const PER = RULE_FILE_CAPS.perRuleFile;
+    const TOTAL = RULE_FILE_CAPS.totalRuleFiles;
+    const sections = [];
+    let total = 0;
+    for (const [filename, content] of entries) {
+        const capped = content.length > PER
+            ? `${content.slice(0, PER)}\n... (capped at rule file limit)\n`
+            : content;
+        if (total + capped.length > TOTAL)
+            break;
+        total += capped.length;
+        sections.push(`<!-- ${filename} -->\n${capped.trim()}`);
+    }
+    if (sections.length === 0)
+        return null;
+    return [
+        `<${FORGEN_RULES_TAG} host="codex">`,
+        'These are the same forgen rules Claude Code loads from .claude/rules/. They apply to this Codex session. Follow them.',
+        '',
+        sections.join('\n\n---\n\n'),
+        `</${FORGEN_RULES_TAG}>`,
+    ].join('\n');
+}
+/**
+ * cwd + 렌더된 v1 룰 → Codex 주입 블록. config-injector 는 무거워서 lazy import.
+ * 실패 시 null (fail-open — 룰 주입 실패가 세션 시작을 막으면 안 된다).
+ */
+export async function buildCodexRulesContext(cwd, renderedRules) {
+    try {
+        const { generateClaudeRuleFiles } = await import('../core/config-injector.js');
+        return renderCodexRulesBlock(generateClaudeRuleFiles(cwd, renderedRules));
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -11,6 +11,11 @@
  */
 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 사용) */
@@ -50,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

@@ -34,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'
@@ -53,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/install-codex.d.ts

@@ -44,8 +44,65 @@ 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;
@@ -54,3 +111,4 @@ export declare function upsertForgenRulesInAgentsMd(opts: {
 }): {
     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;
@@ -297,7 +565,7 @@ export 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,7 +575,7 @@ 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,
     ];

package/dist/host/install-orchestrator.js

@@ -127,6 +127,16 @@ export function renderResult(result, dryRun) {
         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(`    skills: ${result.codex.skillsInstalled} commands + ${result.codex.devGuideSkillsInstalled} dev-guide → ${result.codex.skillsPath}`);
+        lines.push(`    agents: ${result.codex.agentsInstalled} ch-*.toml → ${result.codex.agentsPath}${result.codex.multiAgentEnabled ? '' : '  (⚠ config.toml 에 [features] multi_agent = true 가 없어 Codex 가 spawn 하지 못함 — 추가 권장)'}`);
+        lines.push(`    rules: injected per session via SessionStart hook (<forgen-rules host="codex">)`);
+        const t = result.codex.hookTrust;
+        if (t.total > 0 && t.trusted === t.total) {
+            lines.push(`    hook trust: ${t.trusted}/${t.total} trusted${t.ignoredByCodex.length ? ` (+${t.ignoredByCodex.length} Claude-only event ignored by Codex)` : ''}`);
+        }
+        else {
+            lines.push(`    hook trust: ${t.trusted}/${t.total} trusted — ${t.untrusted.length} hook(s) need review. Codex skips untrusted hooks: run \`/hooks\` inside codex and trust the forgen entries.`);
+        }
     }
     if (result.opencode) {
         lines.push('');