@wooojin/forgen 0.5.0 → 0.5.6

package/dist/host/codex-hook-alive.js

@@ -0,0 +1,51 @@
+/**
+ * Codex 훅 생존 마커 — ADR-016 D1
+ *
+ * Codex 는 미승인(untrusted)/변경된(modified) 훅을 조용히 skip 한다. "forgen 훅이 실제로 실행되고 있는가"
+ * 를 관측하는 유일한 choke point 는 codex-adapter 다 (Codex 가 forgen 훅을 실행하면 반드시 거친다).
+ * 어댑터가 턴 경계 이벤트에서 전역 마커를 갱신하고, notify 폴백(codex-notify)이 그 신선도를 본다.
+ *
+ * 훅 신뢰 상태는 hooks.json 단위로 모든 세션이 공유하므로 마커는 세션별이 아니라 전역 1개다.
+ * 어댑터가 매 훅마다 import 하므로 의존성은 node 내장 + paths 만 둔다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { STATE_DIR } from '../core/paths.js';
+export const CODEX_HOOK_ALIVE_PATH = path.join(STATE_DIR, 'codex-hook-alive.json');
+/** notify 는 Stop 훅 직후 발화한다. Stop 훅 타임아웃(10s) 대비 넉넉한 창. */
+export const CODEX_HOOK_ALIVE_WINDOW_MS = 120_000;
+/** 턴 경계 이벤트만 기록 — PreToolUse/PostToolUse 마다 쓰지 않는다. */
+const ALIVE_EVENTS = new Set(['Stop', 'SubagentStop', 'UserPromptSubmit']);
+/** 어댑터 입력(stdin JSON)으로 마커 갱신. 대상 이벤트가 아니면 no-op. 실패는 삼킨다 (fail-open). */
+export function markCodexHookAlive(input, now = Date.now()) {
+    try {
+        const i = (input ?? {});
+        const event = typeof i.hook_event_name === 'string' ? i.hook_event_name
+            : typeof i.hookEventName === 'string' ? i.hookEventName : '';
+        if (!ALIVE_EVENTS.has(event))
+            return false;
+        const marker = { at: now, event };
+        if (typeof i.session_id === 'string')
+            marker.sessionId = i.session_id;
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        fs.writeFileSync(CODEX_HOOK_ALIVE_PATH, JSON.stringify(marker));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readCodexHookAlive() {
+    try {
+        const m = JSON.parse(fs.readFileSync(CODEX_HOOK_ALIVE_PATH, 'utf-8'));
+        return typeof m.at === 'number' && Number.isFinite(m.at) ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 최근 window 안에 forgen 훅이 Codex 에서 실행됐는가. */
+export function isCodexHookAlive(now = Date.now(), windowMs = CODEX_HOOK_ALIVE_WINDOW_MS) {
+    const m = readCodexHookAlive();
+    return m !== null && now - m.at >= 0 && now - m.at < windowMs;
+}

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Codex `notify` 폴백 — ADR-016 D1
+ *
+ * Codex 는 config.toml 의 top-level `notify = [argv…]` 프로그램을 **턴 완료마다**(Stop 훅 뒤) detached 로
+ * 실행하고, JSON 페이로드를 마지막 argv 로 넘긴다. 훅과 달리 **신뢰(trust) 승인과 무관**하게 돈다.
+ * forgen 은 이것을 "훅이 조용히 skip 되는 동안의 안전망" 으로만 쓴다:
+ *
+ *   1. forgen 훅이 살아 있으면(codex-adapter 가 방금 alive 마커를 갱신) 아무것도 하지 않는다 —
+ *      auto-compound 는 Stop 훅(context-guard) 소관이다.
+ *   2. 훅이 돌지 않았으면 silent 플래그를 남기고(`forgen doctor` 가 노출), 세션이 충분히 길면 Stop 훅과
+ *      같은 디바운스 경로로 auto-compound 를 띄운다.
+ *
+ * 페이로드 (codex-rs/hooks/src/legacy_notify.rs, 0.153.4):
+ *   { "type":"agent-turn-complete", "thread-id", "turn-id", "cwd", "client"?, "input-messages":[…],
+ *     "last-assistant-message" }  — transcript 경로는 없다. `thread-id` 로 rollout 파일을 찾는다.
+ *
+ * argv: `codex-notify.js [-- <chain program> <args…>] <payload JSON>`
+ *   `--` 뒤는 사용자가 수동으로 체인한 자기 notifier (단일 argv 제약 우회). 페이로드를 붙여 먼저 전달한다.
+ *
+ * 실패 정책: 모든 단계 fail-open. stdout/stderr 는 Codex 가 /dev/null 로 버린다.
+ */
+export declare const CODEX_HOOKS_SILENT_PATH: string;
+export interface CodexNotifyPayload {
+    type?: string;
+    'thread-id'?: string;
+    'turn-id'?: string;
+    cwd?: string;
+    client?: string;
+}
+export interface CodexHooksSilent {
+    detectedAt: string;
+    sessionId: string;
+    cwd: string;
+    /** 연속으로 관측된 silent 턴 수 */
+    count: number;
+}
+export type NotifyOutcome = 'nested-run' | 'no-payload' | 'ignored-event' | 'hooks-alive' | 'silent-recorded' | 'silent-compound-spawned';
+/** argv(스크립트 뒤) → 체인 프로그램 + 페이로드. 페이로드는 항상 마지막 argv. */
+export declare function parseNotifyArgv(argv: string[]): {
+    chain: string[];
+    payloadRaw: string | null;
+    payload: CodexNotifyPayload | null;
+};
+/** doctor 용 — 유효(24h 이내)한 silent 관측만 반환. */
+export declare function readCodexHooksSilent(now?: number): CodexHooksSilent | null;
+export interface NotifyDeps {
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+    /** 테스트 주입: auto-compound 디바운스 트리거 */
+    spawnCompound?: (sessionId: string, transcriptPath: string, promptCount: number, cwd: string) => Promise<boolean>;
+    /** 테스트 주입: forgen hook-config 조회 */
+    isHookEnabled?: (name: string) => boolean;
+}
+export declare function handleNotify(argv: string[], deps?: NotifyDeps): Promise<NotifyOutcome>;

package/dist/host/codex-notify.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Codex `notify` 폴백 — ADR-016 D1
+ *
+ * Codex 는 config.toml 의 top-level `notify = [argv…]` 프로그램을 **턴 완료마다**(Stop 훅 뒤) detached 로
+ * 실행하고, JSON 페이로드를 마지막 argv 로 넘긴다. 훅과 달리 **신뢰(trust) 승인과 무관**하게 돈다.
+ * forgen 은 이것을 "훅이 조용히 skip 되는 동안의 안전망" 으로만 쓴다:
+ *
+ *   1. forgen 훅이 살아 있으면(codex-adapter 가 방금 alive 마커를 갱신) 아무것도 하지 않는다 —
+ *      auto-compound 는 Stop 훅(context-guard) 소관이다.
+ *   2. 훅이 돌지 않았으면 silent 플래그를 남기고(`forgen doctor` 가 노출), 세션이 충분히 길면 Stop 훅과
+ *      같은 디바운스 경로로 auto-compound 를 띄운다.
+ *
+ * 페이로드 (codex-rs/hooks/src/legacy_notify.rs, 0.153.4):
+ *   { "type":"agent-turn-complete", "thread-id", "turn-id", "cwd", "client"?, "input-messages":[…],
+ *     "last-assistant-message" }  — transcript 경로는 없다. `thread-id` 로 rollout 파일을 찾는다.
+ *
+ * argv: `codex-notify.js [-- <chain program> <args…>] <payload JSON>`
+ *   `--` 뒤는 사용자가 수동으로 체인한 자기 notifier (단일 argv 제약 우회). 페이로드를 붙여 먼저 전달한다.
+ *
+ * 실패 정책: 모든 단계 fail-open. stdout/stderr 는 Codex 가 /dev/null 로 버린다.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STATE_DIR } from '../core/paths.js';
+import { isCodexHookAlive } from './codex-hook-alive.js';
+import { countCodexUserPrompts, findCodexRollout } from './codex-rollout.js';
+export const CODEX_HOOKS_SILENT_PATH = path.join(STATE_DIR, 'codex-hooks-silent.json');
+/** silent 플래그 유효기간 — 이보다 오래된 관측은 doctor 가 무시한다. */
+const SILENT_TTL_MS = 24 * 60 * 60 * 1000;
+/** Stop 훅 경로와 같은 "의미 있는 세션" 임계. */
+const MIN_USER_PROMPTS = 10;
+/** argv(스크립트 뒤) → 체인 프로그램 + 페이로드. 페이로드는 항상 마지막 argv. */
+export function parseNotifyArgv(argv) {
+    if (argv.length === 0)
+        return { chain: [], payloadRaw: null, payload: null };
+    const payloadRaw = argv[argv.length - 1];
+    const chain = argv[0] === '--' ? argv.slice(1, -1) : [];
+    let payload = null;
+    try {
+        const parsed = JSON.parse(payloadRaw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            payload = parsed;
+    }
+    catch { /* 페이로드 아님 */ }
+    return { chain, payloadRaw, payload };
+}
+/** doctor 용 — 유효(24h 이내)한 silent 관측만 반환. */
+export function readCodexHooksSilent(now = Date.now()) {
+    try {
+        const s = JSON.parse(fs.readFileSync(CODEX_HOOKS_SILENT_PATH, 'utf-8'));
+        const at = Date.parse(s.detectedAt);
+        if (!Number.isFinite(at) || now - at > SILENT_TTL_MS)
+            return null;
+        if (typeof s.sessionId !== 'string' || typeof s.count !== 'number')
+            return null;
+        return s;
+    }
+    catch {
+        return null;
+    }
+}
+function recordSilent(sessionId, cwd, now) {
+    const prev = readCodexHooksSilent(now);
+    const next = {
+        detectedAt: new Date(now).toISOString(),
+        sessionId,
+        cwd,
+        count: (prev?.count ?? 0) + 1,
+    };
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(CODEX_HOOKS_SILENT_PATH, JSON.stringify(next));
+}
+function clearSilent() {
+    try {
+        fs.rmSync(CODEX_HOOKS_SILENT_PATH, { force: true });
+    }
+    catch { /* noop */ }
+}
+function runChain(chain, payloadRaw) {
+    if (chain.length === 0)
+        return;
+    try {
+        const child = spawn(chain[0], [...chain.slice(1), payloadRaw], { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch { /* fail-open */ }
+}
+/** Stop 경로는 context-guard 훅이 auto-compound 를 띄운다 — 사용자가 그 훅을 껐으면 폴백도 띄우지 않는다. */
+async function contextGuardEnabled(deps) {
+    try {
+        const isEnabled = deps.isHookEnabled ?? (await import('../hooks/hook-config.js')).isHookEnabled;
+        return isEnabled('context-guard');
+    }
+    catch {
+        return true; // 설정을 못 읽으면 기본값(활성)
+    }
+}
+export async function handleNotify(argv, deps = {}) {
+    const env = deps.env ?? process.env;
+    const now = deps.now ?? Date.now();
+    // forgen 자신의 추출용 `codex exec` — 재귀/오탐 방지 (env 는 Codex 세션 시작 시점 스냅샷으로 상속된다).
+    if (env.FORGEN_NESTED_RUN === '1')
+        return 'nested-run';
+    const { chain, payloadRaw, payload } = parseNotifyArgv(argv);
+    if (payloadRaw !== null)
+        runChain(chain, payloadRaw);
+    if (!payload)
+        return 'no-payload';
+    if (payload.type !== 'agent-turn-complete')
+        return 'ignored-event';
+    if (isCodexHookAlive(now)) {
+        clearSilent();
+        return 'hooks-alive';
+    }
+    const sessionId = typeof payload['thread-id'] === 'string' ? payload['thread-id'] : 'unknown';
+    const cwd = typeof payload.cwd === 'string' && payload.cwd.length > 0 ? payload.cwd : process.cwd();
+    try {
+        recordSilent(sessionId, cwd, now);
+    }
+    catch { /* fail-open */ }
+    // 훅이 돌지 않으므로 Stop 트리거 auto-compound 도 없다 → 같은 디바운스 경로로 대신 띄운다.
+    // (프롬프트 수는 rollout 전체 기준이라 resume 된 세션에서는 Stop 경로의 훅 카운터보다 클 수 있다.)
+    try {
+        if (!(await contextGuardEnabled(deps)))
+            return 'silent-recorded';
+        const codexHome = env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+        const rollout = findCodexRollout(codexHome, sessionId);
+        if (!rollout)
+            return 'silent-recorded';
+        const prompts = countCodexUserPrompts(rollout);
+        if (prompts < MIN_USER_PROMPTS)
+            return 'silent-recorded';
+        const spawnCompound = deps.spawnCompound ?? (async (sid, transcript, count, dir) => {
+            // 훅 경로에선 codex-adapter 가 주입하는 값 — 러너의 evidence/timing 이 rt:"codex" 로 태깅된다.
+            // (추출에 쓸 LLM host 는 이것과 무관하게 profile.default_host 로 정해진다 — Stop 경로와 동일.)
+            process.env.FORGEN_RUNTIME = 'codex';
+            const { maybeSpawnAutoCompound } = await import('../hooks/context-guard.js');
+            return maybeSpawnAutoCompound(sid, transcript, count, dir);
+        });
+        return (await spawnCompound(sessionId, rollout, prompts, cwd)) ? 'silent-compound-spawned' : 'silent-recorded';
+    }
+    catch {
+        return 'silent-recorded';
+    }
+}
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
+    handleNotify(process.argv.slice(2)).catch(() => { });
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Codex rollout 파일 헬퍼 — ADR-016 (SessionEnd 훅 + notify 폴백 공용)
+ *
+ * rollout: `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<local ts>-<thread id>.jsonl` (compact JSONL).
+ */
+/**
+ * thread id(= 훅의 session_id = notify 의 `thread-id`) 로 rollout 파일을 찾는다 (최근 날짜부터).
+ * id 는 UUID 형태만 허용한다.
+ */
+export declare function findCodexRollout(codexHome: string, threadId: string): string | null;
+/** 스캔 상한. SessionEnd 훅은 3s 예산이라 전체 스트리밍(239MB ≈ 3s) 대신 raw 바이트 스캔 + 상한을 쓴다. */
+export declare const CODEX_PROMPT_SCAN_MAX_BYTES: number;
+/**
+ * Codex rollout 의 *실제 사용자 프롬프트* 수 — `event_msg` / `payload.type:"user_message"` 레코드.
+ *
+ * `response_item` role=user 는 AGENTS.md·환경 컨텍스트 주입까지 포함해 실측 ~1.8배 과대계수이고
+ * (51 vs 91), 줄당 수십 KB 인 tool 출력 때문에 "앞 200KB 만 JSON.parse" 로는 프롬프트 1~2개밖에 못 본다.
+ * 그래서 JSON 을 파싱하지 않고 구조 수준의 바이트 패턴을 센다 — 문자열 값 안의 같은 텍스트는 따옴표가
+ * `\"` 로 이스케이프되므로 매치되지 않는다. maxBytes 까지만 읽는다 (하한 추정).
+ */
+export declare function countCodexUserPrompts(rolloutPath: string, maxBytes?: number): number;

package/dist/host/codex-rollout.js

@@ -0,0 +1,82 @@
+/**
+ * Codex rollout 파일 헬퍼 — ADR-016 (SessionEnd 훅 + notify 폴백 공용)
+ *
+ * rollout: `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<local ts>-<thread id>.jsonl` (compact JSONL).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/** rollout 탐색 시 최근 일자 디렉토리만 본다 (resume 된 오래된 세션 대비 여유). */
+const MAX_DAY_DIRS = 45;
+function sortedDesc(dir) {
+    try {
+        return fs.readdirSync(dir).sort().reverse();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * thread id(= 훅의 session_id = notify 의 `thread-id`) 로 rollout 파일을 찾는다 (최근 날짜부터).
+ * id 는 UUID 형태만 허용한다.
+ */
+export function findCodexRollout(codexHome, threadId) {
+    if (!/^[A-Za-z0-9-]{8,64}$/.test(threadId))
+        return null;
+    const root = path.join(codexHome, 'sessions');
+    let scanned = 0;
+    for (const y of sortedDesc(root)) {
+        for (const m of sortedDesc(path.join(root, y))) {
+            for (const d of sortedDesc(path.join(root, y, m))) {
+                if (scanned >= MAX_DAY_DIRS)
+                    return null;
+                scanned += 1;
+                const dayDir = path.join(root, y, m, d);
+                const hit = sortedDesc(dayDir).find((f) => f.startsWith('rollout-') && f.endsWith('.jsonl') && f.includes(`-${threadId}`));
+                if (hit)
+                    return path.join(dayDir, hit);
+            }
+        }
+    }
+    return null;
+}
+const USER_PROMPT_NEEDLE = Buffer.from('"type":"user_message"');
+const CHUNK_BYTES = 1024 * 1024;
+/** 스캔 상한. SessionEnd 훅은 3s 예산이라 전체 스트리밍(239MB ≈ 3s) 대신 raw 바이트 스캔 + 상한을 쓴다. */
+export const CODEX_PROMPT_SCAN_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * Codex rollout 의 *실제 사용자 프롬프트* 수 — `event_msg` / `payload.type:"user_message"` 레코드.
+ *
+ * `response_item` role=user 는 AGENTS.md·환경 컨텍스트 주입까지 포함해 실측 ~1.8배 과대계수이고
+ * (51 vs 91), 줄당 수십 KB 인 tool 출력 때문에 "앞 200KB 만 JSON.parse" 로는 프롬프트 1~2개밖에 못 본다.
+ * 그래서 JSON 을 파싱하지 않고 구조 수준의 바이트 패턴을 센다 — 문자열 값 안의 같은 텍스트는 따옴표가
+ * `\"` 로 이스케이프되므로 매치되지 않는다. maxBytes 까지만 읽는다 (하한 추정).
+ */
+export function countCodexUserPrompts(rolloutPath, maxBytes = CODEX_PROMPT_SCAN_MAX_BYTES) {
+    const fd = fs.openSync(rolloutPath, 'r');
+    try {
+        const overlap = USER_PROMPT_NEEDLE.length - 1;
+        const buf = Buffer.alloc(CHUNK_BYTES + overlap);
+        let carry = 0;
+        let pos = 0;
+        let count = 0;
+        while (pos < maxBytes) {
+            const read = fs.readSync(fd, buf, carry, Math.min(CHUNK_BYTES, maxBytes - pos), pos);
+            if (read <= 0)
+                break;
+            const view = buf.subarray(0, carry + read);
+            let idx = view.indexOf(USER_PROMPT_NEEDLE);
+            while (idx !== -1) {
+                count += 1;
+                idx = view.indexOf(USER_PROMPT_NEEDLE, idx + USER_PROMPT_NEEDLE.length);
+            }
+            // 청크 경계에 걸친 패턴 대비: 끝 overlap 바이트를 다음 청크 앞에 붙인다 (needle 보다 짧아 이중계수 없음).
+            carry = Math.min(overlap, view.length);
+            view.copy(buf, 0, view.length - carry, view.length);
+            pos += read;
+        }
+        return count;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}

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'
@@ -71,7 +82,11 @@ export function execHost(opts) {
         '--skip-git-repo-check',
         opts.prompt,
     ];
-    const stdout = execFileSync('codex', args, baseOpts);
+    // ADR-016 (critic m2): Codex 추출 run 에도 중첩 표식을 준다. `--ephemeral` 은 rollout 만 안 남길 뿐
+    // 사용자 config(훅·notify)는 그대로 로드한다 — 표식이 없으면 forgen 훅이 추출 세션에서 발화하고
+    // notify 폴백이 그 세션을 "훅 미발화" 로 오기록한다.
+    const codexEnv = (opts.nestedRun ?? true) ? { ...(baseOpts.env ?? {}), ...NESTED_RUN_ENV } : baseOpts.env;
+    const stdout = execFileSync('codex', args, { ...baseOpts, env: codexEnv });
     const parsed = parseCodexJsonlOutput(stdout.toString());
     return {
         message: parsed.message,

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

@@ -10,6 +10,7 @@
  *   3. Settings hooks injection: ~/.claude/settings.json 의 hooks 머지 (forgen entry idempotent)
  *   4. MCP register: ~/.claude.json 에 mcpServers.forgen-compound 추가
  *   5. Dev-guide skills: ~/.claude/skills/forgen-<stack>-<skill>/ 설치 (forgen-managed only)
+ *   6. verify skill: ~/.claude/skills/verify/ 설치 (ADR-016 D3 — 사용자 소유면 보존)
  *
  * 사용자 비-forgen 자산 보존 + 재실행 idempotent.
  */
@@ -21,7 +22,17 @@ export interface ClaudeInstallOptions {
     dryRun?: boolean;
     /** MCP forgen-compound 등록 여부 (default true). */
     registerMcp?: boolean;
+    /** ADR-016 D3: user-level `verify` 스킬 설치 여부 (default true). */
+    installVerifySkill?: boolean;
 }
+/** ADR-016 D3 — `~/.claude/skills/verify` 설치 결과. */
+export type VerifySkillStatus = 
+/** forgen-managed 스킬을 새로 썼거나 갱신함 */
+'installed'
+/** 사용자가 직접 만든 `verify` 스킬이 있어 건드리지 않음 */
+ | 'user-owned'
+/** --no-verify-skill 또는 자산 부재 */
+ | 'skipped';
 export interface ClaudeInstallResult {
     homeDir: string;
     pluginCachePath: string;
@@ -35,5 +46,8 @@ export interface ClaudeInstallResult {
     skillsPath: string;
     skillsInstalled: number;
     skillsRemoved: number;
+    verifySkill: VerifySkillStatus;
 }
+/** `<skillsDir>/verify` 가 사용자 소유인가 (심링크 / 마커 없는 SKILL.md / SKILL.md 없이 다른 파일만 있음). */
+export declare function isUserOwnedVerifySkill(skillsDir: string): boolean;
 export declare function planClaudeInstall(opts: ClaudeInstallOptions): ClaudeInstallResult;

package/dist/host/install-claude.js

@@ -10,6 +10,7 @@
  *   3. Settings hooks injection: ~/.claude/settings.json 의 hooks 머지 (forgen entry idempotent)
  *   4. MCP register: ~/.claude.json 에 mcpServers.forgen-compound 추가
  *   5. Dev-guide skills: ~/.claude/skills/forgen-<stack>-<skill>/ 설치 (forgen-managed only)
+ *   6. verify skill: ~/.claude/skills/verify/ 설치 (ADR-016 D3 — 사용자 소유면 보존)
  *
  * 사용자 비-forgen 자산 보존 + 재실행 idempotent.
  */
@@ -301,6 +302,54 @@ function installDevGuideSkills(opts) {
     }
     return { skillsPath: skillsDir, skillsInstalled: installed, skillsRemoved: removed };
 }
+// ── 6. verify skill (ADR-016 D3) ───────────────────────────────────────
+/** frontmatter 직후에 forgen-managed 마커가 있는 SKILL.md 만 forgen 소유로 본다. */
+const MANAGED_SKILL_RE = /^---\n[\s\S]*?\n---\n\s*<!-- forgen-managed -->/;
+/** `<skillsDir>/verify` 가 사용자 소유인가 (심링크 / 마커 없는 SKILL.md / SKILL.md 없이 다른 파일만 있음). */
+export function isUserOwnedVerifySkill(skillsDir) {
+    const dir = path.join(skillsDir, 'verify');
+    try {
+        if (fs.lstatSync(dir).isSymbolicLink())
+            return true;
+    }
+    catch {
+        return false; // 없음
+    }
+    const file = path.join(dir, 'SKILL.md');
+    try {
+        if (fs.lstatSync(file).isSymbolicLink())
+            return true;
+        return !MANAGED_SKILL_RE.test(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        // SKILL.md 없음 — 디렉토리에 다른 것이 있으면 사용자가 만들던 것
+        try {
+            return fs.readdirSync(dir).length > 0;
+        }
+        catch {
+            return true;
+        }
+    }
+}
+/**
+ * Claude Code 2.1.286+ 는 project/user 스킬에 `verify` 가 있으면 커밋 직전에 실행하라고 모델에 안내한다
+ * (플러그인 스킬 `forgen:verify` 는 해당 없음). 그래서 user 레벨에 un-namespaced 로 설치한다.
+ * 사용자 소유 스킬은 절대 덮어쓰지 않는다.
+ */
+function installVerifySkill(opts) {
+    const src = path.join(opts.pkgRoot, 'assets', 'claude', 'skills', 'verify', 'SKILL.md');
+    if (!fs.existsSync(src))
+        return 'skipped';
+    if (isUserOwnedVerifySkill(opts.skillsDir))
+        return 'user-owned';
+    if (opts.dryRun)
+        return 'installed';
+    const dir = path.join(opts.skillsDir, 'verify');
+    fs.mkdirSync(dir, { recursive: true });
+    // 심링크가 아니라 복사 — 마커로 소유를 판정하고, npm 경로가 바뀌어도 깨지지 않게.
+    fs.copyFileSync(src, path.join(dir, 'SKILL.md'));
+    return 'installed';
+}
 // ── public ─────────────────────────────────────────────────────────────
 export function planClaudeInstall(opts) {
     if (!opts.pkgRoot || !fs.existsSync(opts.pkgRoot)) {
@@ -324,6 +373,9 @@ export function planClaudeInstall(opts) {
         ? registerMcpInClaudeJson({ pkgRoot: opts.pkgRoot, claudeJsonPath, dryRun })
         : { registered: false, alreadyPresent: false };
     const skills = installDevGuideSkills({ pkgRoot: opts.pkgRoot, skillsDir, dryRun });
+    const verifySkill = (opts.installVerifySkill ?? true)
+        ? installVerifySkill({ pkgRoot: opts.pkgRoot, skillsDir, dryRun })
+        : 'skipped';
     return {
         homeDir,
         pluginCachePath: cacheDir,
@@ -337,5 +389,6 @@ export function planClaudeInstall(opts) {
         skillsPath: skills.skillsPath,
         skillsInstalled: skills.skillsInstalled,
         skillsRemoved: skills.skillsRemoved,
+        verifySkill,
     };
 }