@wooojin/forgen 0.5.0 → 0.5.6

package/dist/host/install-codex.js

@@ -11,12 +11,15 @@
  * - MCP 등록은 TOML 라이브러리 없이 marker block 으로 idempotent 관리.
  * - dryRun 시 파일을 쓰지 않고 결과만 반환 (테스트 + preview 용).
  */
+import * as crypto from 'node:crypto';
 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 NOTIFY_MARKER_BEGIN = '# >>> forgen-managed-notify';
+const NOTIFY_MARKER_END = '# <<< forgen-managed-notify';
 const FORGEN_SKILL_MARKER = '<!-- forgen-managed -->';
 const AGENTS_MD_BEGIN = '<!-- >>> forgen-managed-rules -->';
 const AGENTS_MD_END = '<!-- <<< forgen-managed-rules -->';
@@ -47,31 +50,150 @@ function readJsonFile(p) {
         return null;
     }
 }
-function buildMcpBlock(pkgRoot) {
+function splitManagedSpan(lines, begin, end) {
+    const b = lines.findIndex((l) => l.trim() === begin);
+    if (b === -1)
+        return null;
+    const rel = lines.slice(b + 1).findIndex((l) => l.trim() === end);
+    if (rel === -1)
+        return null;
+    const e = b + 1 + rel;
+    return { before: lines.slice(0, b), inner: lines.slice(b + 1, e), after: lines.slice(e + 1) };
+}
+function trimBlankEdges(lines) {
+    let a = 0;
+    let z = lines.length;
+    while (a < z && lines[a].trim() === '')
+        a += 1;
+    while (z > a && lines[z - 1].trim() === '')
+        z -= 1;
+    return lines.slice(a, z);
+}
+/** BOM 은 파일 맨 앞에 있어야 한다 — 떼어 두었다가 결과 맨 앞에 다시 붙인다. 줄 끝(CRLF)도 보존. */
+function tomlShape(toml) {
+    const bom = toml.startsWith('') ? '' : '';
+    return { bom, body: toml.slice(bom.length), cr: /\r\n/.test(toml) ? '\r' : '' };
+}
+const MCP_TABLE_HEADER = '[mcp_servers.forgen-compound]';
+const MCP_OWN_KEY_RE = /^\s*(command|args)\s*=/;
+function upsertMcpBlock(currentToml, pkgRoot) {
+    const { bom, body, cr } = tomlShape(currentToml);
+    const serverPath = path.join(pkgRoot, 'dist', 'mcp', 'server.js');
     // 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');
+    const ownKeys = ['command = "node"', `args = [${JSON.stringify(serverPath)}, "--host=codex"]`];
+    const lines = body.split('\n');
+    const span = splitManagedSpan(lines, MCP_MARKER_BEGIN, MCP_MARKER_END);
+    if (!span) {
+        // 마커 없이 같은 테이블이 있으면(사용자 직접 작성 / 마커 손상) append 하지 않는다 — 중복 테이블 = 파싱 실패.
+        if (lines.some((l) => l.trim() === MCP_TABLE_HEADER))
+            return { content: currentToml, alreadyPresent: true };
+        const block = [MCP_MARKER_BEGIN, MCP_TABLE_HEADER, ...ownKeys, MCP_MARKER_END].map((l) => l + cr).join('\n');
+        const trimmed = body.replace(/\s+$/, '');
+        const sep = trimmed.length > 0 ? `${cr}\n${cr}\n` : '';
+        return { content: `${bom}${trimmed}${sep}${block}\n`, alreadyPresent: false };
+    }
+    const h = span.inner.findIndex((l) => l.trim() === MCP_TABLE_HEADER);
+    let extraKeys = [];
+    let foreign = span.inner;
+    if (h !== -1) {
+        const afterHeader = span.inner.slice(h + 1);
+        const next = afterHeader.findIndex((l) => /^\s*\[/.test(l));
+        const tableBody = next === -1 ? afterHeader : afterHeader.slice(0, next);
+        // 손으로 고쳐 여러 줄이 된 command/args 는 안전하게 다시 쓸 수 없다 — 블록을 그대로 둔다.
+        const own = tableBody.filter((l) => MCP_OWN_KEY_RE.test(l));
+        if (own.some((l) => !/(["'\]])\s*(#.*)?$/.test(l.trim())))
+            return { content: currentToml, alreadyPresent: true };
+        // 사용자가 Codex 로 이 서버에 붙인 설정(enabled, startup_timeout_sec …)은 테이블 안에 유지.
+        extraKeys = tableBody.filter((l) => l.trim() !== '' && !MCP_OWN_KEY_RE.test(l)).map((l) => l.replace(/\r$/, ''));
+        foreign = [...span.inner.slice(0, h), ...(next === -1 ? [] : afterHeader.slice(next))];
+    }
+    const block = [MCP_MARKER_BEGIN, MCP_TABLE_HEADER, ...ownKeys, ...extraKeys, MCP_MARKER_END].map((l) => l + cr);
+    const moved = trimBlankEdges(foreign);
+    const out = [...span.before, ...block, ...(moved.length > 0 ? [cr, ...moved] : []), ...span.after];
+    const content = bom + out.join('\n');
+    return { content, alreadyPresent: content === currentToml };
 }
-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 };
+// ── ADR-016 D1: notify 폴백 (config.toml top-level `notify`) ───────────
+/** forgen notify 바이너리 argv 접두 (`--` 뒤는 사용자가 수동으로 붙인 체인 프로그램). */
+function forgenNotifyArgv(pkgRoot) {
+    return ['node', path.join(pkgRoot, 'dist', 'host', 'codex-notify.js')];
+}
+const NOTIFY_OWN_COMMENTS = [
+    '# forgen turn-complete fallback (ADR-016): works even while forgen hooks are untrusted.',
+    '# To chain your own notifier, append:  "--", "<program>", "<args…>"  (kept across re-install).',
+];
+/** `notify`, `"notify"`, `'notify'` 키 (dotted `notify.x` 포함) — 어느 것이든 forgen 의 notify 와 충돌한다. */
+const NOTIFY_KEY_RE = /^[ \t]*(?:notify|"notify"|'notify')[ \t]*[.=]/;
+function parseNotifyBlock(lines) {
+    const span = splitManagedSpan(lines, NOTIFY_MARKER_BEGIN, NOTIFY_MARKER_END);
+    if (!span)
+        return { span: null, foreign: [], argv: null };
+    const idx = span.inner.findIndex((l) => NOTIFY_KEY_RE.test(l));
+    let argv = null;
+    if (idx !== -1) {
+        argv = 'unparseable';
+        const value = span.inner[idx].trim().match(/^notify[ \t]*=[ \t]*(\[.*\])$/)?.[1];
+        try {
+            const parsed = value ? JSON.parse(value) : null;
+            if (Array.isArray(parsed) && parsed.every((a) => typeof a === 'string'))
+                argv = parsed;
+        }
+        catch { /* multi-line / single-quoted / trailing comment — 아래에서 블록을 그대로 둔다 */ }
+    }
+    const foreign = span.inner.filter((l, i) => i !== idx && l.trim() !== '' && !l.trim().startsWith('# forgen turn-complete fallback') && !l.trim().startsWith('# To chain your own notifier'));
+    return { span, foreign, argv };
+}
+/**
+ * config.toml 에 forgen notify 블록을 upsert.
+ *
+ * - Codex 의 `notify` 는 top-level 단일 argv 다. 사용자가 이미 정의했으면 **건드리지 않는다** — 그리고
+ *   forgen 블록이 남아 있으면 제거한다 (중복 키 = config.toml 파싱 실패 → Codex 기동 불가).
+ * - top-level 키는 첫 테이블 헤더 앞에 와야 하므로 블록은 항상 파일 최상단(BOM 뒤)에 둔다.
+ * - 사용자가 forgen 블록의 argv 뒤에 `"--", "<prog>", …` 로 자기 notifier 를 체인해 뒀으면 그 꼬리를 보존.
+ *   블록의 notify 줄을 한 줄 JSON 으로 읽을 수 없으면(여러 줄 배열 등 손편집) 아무것도 바꾸지 않는다.
+ * - 블록 사이에 Codex 가 끼워 넣은 줄(root 키)은 블록 바로 뒤로 옮겨 보존한다.
+ */
+export function upsertNotifyBlock(currentToml, pkgRoot) {
+    const { bom, body, cr } = tomlShape(currentToml);
+    const lines = body.split('\n');
+    const { span, foreign, argv: existingArgv } = parseNotifyBlock(lines);
+    const outside = span ? [...span.before, ...span.after] : lines;
+    // 보수적 판정: 블록 밖 어디든 `notify =` 줄이 있으면 사용자 정의로 본다 (프로필 테이블 안이어도 skip —
+    // 폴백을 못 넣는 쪽이 config 를 깨뜨리는 쪽보다 낫다).
+    if (outside.some((l) => NOTIFY_KEY_RE.test(l))) {
+        if (!span)
+            return { content: currentToml, status: 'user-defined' };
+        return { content: bom + [...span.before, ...foreign, ...span.after].join('\n'), status: 'user-defined' };
+    }
+    if (existingArgv === 'unparseable')
+        return { content: currentToml, status: 'custom-block' };
+    const sep = existingArgv ? existingArgv.indexOf('--') : -1;
+    const chainTail = existingArgv && sep !== -1 ? existingArgv.slice(sep) : [];
+    const argv = [...forgenNotifyArgv(pkgRoot), ...chainTail];
+    const block = [NOTIFY_MARKER_BEGIN, ...NOTIFY_OWN_COMMENTS, `notify = ${JSON.stringify(argv)}`, NOTIFY_MARKER_END].map((l) => l + cr);
+    const rest = span ? [...span.before, ...foreign, ...span.after] : lines;
+    let start = 0;
+    while (start < rest.length && rest[start].trim() === '')
+        start += 1;
+    const tail = rest.slice(start);
+    const content = bom + (tail.length > 0 ? [...block, cr, ...tail] : [...block, '']).join('\n');
+    return { content, status: content === currentToml ? 'already-present' : 'installed' };
+}
+/** forgen notify 블록 제거 (`--no-notify`, uninstall). 블록 사이에 끼어든 다른 줄은 보존. */
+export function removeNotifyBlock(currentToml) {
+    const { bom, body } = tomlShape(currentToml);
+    const { span, foreign } = parseNotifyBlock(body.split('\n'));
+    if (!span)
+        return { content: currentToml, removed: false };
+    const rest = [...span.before, ...foreign, ...span.after];
+    let start = 0;
+    if (span.before.every((l) => l.trim() === '') && foreign.length === 0) {
+        while (start < rest.length && rest[start].trim() === '')
+            start += 1;
+    }
+    return { content: bom + rest.slice(start).join('\n'), removed: true };
 }
 export function planCodexInstall(opts) {
     const codexHome = resolveCodexHome(opts);
@@ -85,29 +207,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;
@@ -121,22 +253,36 @@ export function planCodexInstall(opts) {
     const registerMcp = opts.registerMcp ?? true;
     let mcpAlreadyPresent = false;
     let mcpRegistered = false;
-    let mcpContentToWrite = null;
+    const currentToml = fs.existsSync(configTomlPath) ? fs.readFileSync(configTomlPath, 'utf-8') : '';
+    let configToml = currentToml;
     if (registerMcp) {
-        const currentToml = fs.existsSync(configTomlPath)
-            ? fs.readFileSync(configTomlPath, 'utf-8')
-            : '';
-        const { content, alreadyPresent } = upsertMcpBlock(currentToml, opts.pkgRoot);
+        const { content, alreadyPresent } = upsertMcpBlock(configToml, opts.pkgRoot);
         mcpAlreadyPresent = alreadyPresent;
         mcpRegistered = !alreadyPresent;
-        mcpContentToWrite = content;
+        configToml = content;
     }
+    // 4b) ADR-016 D1: notify 폴백 (사용자 notify 가 있으면 보존)
+    let notify = 'skipped';
+    if (opts.registerNotify ?? true) {
+        const r = upsertNotifyBlock(configToml, opts.pkgRoot);
+        notify = r.status;
+        configToml = r.content;
+    }
+    else {
+        // opt-out 은 "더 이상 등록하지 않음" 이 아니라 "없앰" 이어야 한다 (이전 설치의 블록이 남지 않게).
+        const r = removeNotifyBlock(configToml);
+        if (r.removed) {
+            notify = 'removed';
+            configToml = r.content;
+        }
+    }
+    const configTomlToWrite = configToml !== currentToml ? configToml : null;
     // 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');
+        if (configTomlToWrite !== null) {
+            fs.writeFileSync(configTomlPath, configTomlToWrite, 'utf-8');
         }
     }
     // 6) P3-3 (US-013): Codex skills/ 에 forgen 10 commands install
@@ -156,6 +302,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: opts.dryRun ? currentToml : configToml,
+    });
+    const multiAgentEnabled = isCodexMultiAgentEnabled(configToml);
     return {
         codexHome,
         hooksPath,
@@ -172,7 +333,333 @@ export function planCodexInstall(opts) {
         devGuideSkillsPath: devGuideResult.devGuideSkillsPath,
         devGuideSkillsInstalled: devGuideResult.devGuideSkillsInstalled,
         devGuideSkillsRemoved: devGuideResult.devGuideSkillsRemoved,
+        agentsPath: codexAgents.agentsPath,
+        agentsInstalled: codexAgents.installed,
+        agentsRemoved: codexAgents.removed,
+        hookTrust,
+        multiAgentEnabled,
+        notify,
+    };
+}
+/** `[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();
+}
+/** `additionalContextLimit` 을 인정하는 이벤트 (codex-rs/hooks/src/engine/discovery.rs). */
+const CODEX_CONTEXT_LIMIT_EVENTS = new Set([
+    'PreToolUse', 'PostToolUse', 'SessionStart', 'UserPromptSubmit', 'SubagentStart',
+]);
+/** matcher 를 해시에서 제외하는 이벤트 (Codex 가 matcher 를 무시). */
+const CODEX_NO_MATCHER_EVENTS = new Set(['UserPromptSubmit', 'Stop', 'Interrupt']);
+const CODEX_DEFAULT_CONTEXT_LIMIT = 2500;
+/** 키 정렬 + compact JSON (codex-rs/config/src/fingerprint.rs `canonical_json`). */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const obj = value;
+        return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * ADR-016 D2 — Codex 0.153.4 의 hook trust 해시 재현 (`hook_hash`, discovery.rs).
+ *
+ * 해시는 *핸들러 단위*: `{event_name, matcher?, hooks:[정규화된 핸들러 1개]}` 의 canonical JSON sha256.
+ * 정규화: timeout 은 기본값/clamp 적용 후 항상 포함, async 항상 포함, statusMessage 는 있을 때만,
+ * additionalContextLimit 은 허용 이벤트에서 기본값(2500)이 아닐 때만. 파일 경로·인덱스·미지 필드는 불포함.
+ * `type:"command"` 가 아니면 null (forgen 은 command 훅만 쓴다).
+ */
+export function codexHookTrustHash(event, matcher, handler) {
+    if (handler.type !== 'command' || typeof handler.command !== 'string')
+        return null;
+    const rawTimeout = typeof handler.timeout === 'number' ? handler.timeout : undefined;
+    const timeout = event === 'SessionEnd' || event === 'Interrupt'
+        ? Math.min(3, Math.max(1, rawTimeout ?? 1))
+        : Math.max(1, rawTimeout ?? 600);
+    const normalized = {
+        type: 'command',
+        command: handler.command,
+        timeout,
+        // upstream 은 raw 플래그를 해시한다 (SessionEnd 의 "동기로 실행" 강등은 실행 방식에만 반영).
+        async: handler.async === true,
     };
+    if (typeof handler.statusMessage === 'string')
+        normalized.statusMessage = handler.statusMessage;
+    if (typeof handler.additionalContextLimit === 'number' &&
+        CODEX_CONTEXT_LIMIT_EVENTS.has(event) &&
+        handler.additionalContextLimit !== CODEX_DEFAULT_CONTEXT_LIMIT) {
+        normalized.additionalContextLimit = handler.additionalContextLimit;
+    }
+    const identity = { event_name: codexHookEventKey(event), hooks: [normalized] };
+    if (!CODEX_NO_MATCHER_EVENTS.has(event) && typeof matcher === 'string')
+        identity.matcher = matcher;
+    return `sha256:${crypto.createHash('sha256').update(canonicalJson(identity)).digest('hex')}`;
+}
+/** config.toml 의 `[hooks.state."<key>"]` (또는 literal `'<key>'`) 섹션 → trusted_hash / enabled. */
+function parseCodexHookState(toml) {
+    const state = new Map();
+    let current = null;
+    for (const raw of toml.split('\n')) {
+        const line = raw.replace(/\r$/, '');
+        const header = line.match(/^\[hooks\.state\.(?:"((?:[^"\\]|\\.)*)"|'([^']*)')\]\s*(#.*)?$/);
+        if (header) {
+            // basic string 은 이스케이프(\\, \") 를 풀고, literal string 은 그대로.
+            const key = header[1] !== undefined ? header[1].replace(/\\(["\\])/g, '$1') : header[2];
+            current = { hash: null, enabled: true };
+            state.set(key, current);
+            continue;
+        }
+        if (/^\s*\[/.test(line)) {
+            current = null;
+            continue;
+        }
+        if (current === null)
+            continue;
+        const hash = line.match(/^\s*trusted_hash\s*=\s*(?:"([^"]*)"|'([^']*)')/);
+        if (hash)
+            current.hash = hash[1] ?? hash[2];
+        if (/^\s*enabled\s*=\s*false\b/.test(line))
+            current.enabled = false;
+    }
+    return state;
+}
+/**
+ * hooks.json 의 forgen 엔트리 각각을 config.toml 의
+ * `[hooks.state."<hooksPath>:<event>:<groupIdx>:<hookIdx>"] trusted_hash` 와 대조한다 (ADR-014 D4).
+ *
+ * ADR-016 D2: 이전엔 *기록 유무* 만 봤다 — 그래서 핸들러가 바뀌어 Codex 가 `modified` 로 skip 하는 훅을
+ * "trusted" 로 오표시했다. 이제 Codex 와 같은 해시를 계산해 trusted / modified / untrusted 를 구분한다.
+ * 읽기 전용 대조이며 trusted_hash 를 쓰지 않는다 — Codex 의 review 정책을 우회하지 않는다.
+ */
+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 state = parseCodexHookState(toml);
+    // Codex 는 $CODEX_HOME 을 canonicalize 한 경로로 키를 쓴다 — 심링크된 홈에서는 raw 경로와 다르다.
+    const keyPrefixes = [opts.hooksPath];
+    try {
+        const real = fs.realpathSync(opts.hooksPath);
+        if (real !== opts.hooksPath)
+            keyPrefixes.push(real);
+    }
+    catch { /* hooks.json 없음 (dry-run) */ }
+    const lookup = (key) => {
+        for (const prefix of keyPrefixes) {
+            const hit = state.get(`${prefix}:${key}`);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    };
+    let total = 0;
+    let trusted = 0;
+    const untrusted = [];
+    const modified = [];
+    const disabled = [];
+    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;
+                const recorded = lookup(key);
+                if (!recorded || recorded.hash === null) {
+                    untrusted.push(key);
+                    return;
+                }
+                if (recorded.hash !== codexHookTrustHash(event, g.matcher, h)) {
+                    modified.push(key);
+                    return;
+                }
+                if (!recorded.enabled) {
+                    disabled.push(key);
+                    return;
+                }
+                trusted += 1;
+            });
+        });
+    }
+    return { total, trusted, untrusted, modified, disabled, ignoredByCodex, noStateRecorded: state.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)
@@ -237,6 +724,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 +772,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 +805,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 +815,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,
     ];