@wooojin/forgen 0.4.10 → 0.4.11

package/dist/fgx.js

@@ -19,7 +19,7 @@ const FORGEN_SUBCOMMANDS = new Set([
     'notepad', 'inspect', 'onboarding', 'doctor', 'uninstall', 'rule',
     'classify-enforce', 'rule-meta-scan', 'lifecycle-scan',
     'stats', 'last-block', 'recall', 'migrate', 'suppress-rule', 'activate-rule',
-    'regress-map',
+    'regress-map', 'watch', 'health', 'probe-workflow', 'workflows', 'explain', 'changelog',
     // 메타 명령도 cli.ts 가 처리 (fgx claude spawn 으로는 의미 없음)
     'help', '--help', '-h', '--version', '-V',
 ]);

package/dist/hooks/notepad-injector.js

@@ -22,6 +22,7 @@ import { truncateContent } from './shared/injection-caps.js';
 import { calculateBudget } from './shared/context-budget.js';
 import { approve, approveWithContext, failOpenWithTracking } from './shared/hook-response.js';
 import { escapeAllXmlTags } from './prompt-injection-filter.js';
+import { checkForgenInitialized, hasPreflightWarned, markPreflightWarned } from './shared/preflight-check.js';
 // ── 메인 ──
 async function main() {
     const input = await readStdinJSON();
@@ -33,6 +34,12 @@ async function main() {
         console.log(approve());
         return;
     }
+    const sessionId = input.session_id ?? 'unknown';
+    const preflight = checkForgenInitialized();
+    if (!preflight.initialized && !hasPreflightWarned(sessionId)) {
+        markPreflightWarned(sessionId);
+        process.stderr.write(`${preflight.message}\n`);
+    }
     const effectiveCwd = input.cwd ?? process.env.FORGEN_CWD ?? process.env.COMPOUND_CWD ?? process.cwd();
     const notepadContent = readNotepad(effectiveCwd);
     if (!notepadContent.trim()) {

package/dist/hooks/post-tool-use.js

@@ -131,7 +131,14 @@ async function main() {
         const rawResponse = data.tool_response ?? data.toolOutput ?? '';
         const toolResponse = typeof rawResponse === 'string' ? rawResponse : JSON.stringify(rawResponse);
         const sessionId = data.session_id ?? 'default';
-        const modState = loadModifiedFiles(sessionId);
+        // ADR-009 §2d: subagent context (agent_id 존재) 의 tool 추적은 per-agent 파일로
+        // 분리한다 → (a) 메인 세션 recentTools 가 subagent tool 노이즈에 오염되지 않고,
+        // (b) 각 subagent 가 자기 TEST-2 윈도우를 가지며, (c) 워크플로우 동시 subagent 가
+        // 서로의 recentTools 를 덮어쓰는 레이스를 제거. agent_id 가 없으면(메인 세션)
+        // sessionId 그대로 → 기존 동작 불변. violation/bypass 기록은 실 sessionId 유지.
+        const agentId = data.agent_id ?? data.agentId;
+        const trackingKey = agentId ? `${sessionId}.agent-${agentId}` : sessionId;
+        const modState = loadModifiedFiles(trackingKey);
         modState.toolCallCount = (modState.toolCallCount ?? 0) + 1;
         // TEST-2: recent tool name window — stop-guard 의 self-score inflation 가드가
         // "최근 세션에서 측정 도구 몇 번 불렸나?" 를 이 배열로 계산한다.

package/dist/hooks/shared/preflight-check.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Preflight check for forgen initialization state.
+ *
+ * Detects "hooks wired but no profile" — a user who ran `forgen install`
+ * but never completed onboarding via `forgen`. Emits a one-time warning
+ * per session so the user knows personalization is disabled.
+ */
+export declare function checkForgenInitialized(): {
+    initialized: boolean;
+    message?: string;
+};
+/** Returns true if a preflight warning has already been emitted this session */
+export declare function hasPreflightWarned(sessionId: string): boolean;
+/** Mark that a preflight warning has been emitted for this session */
+export declare function markPreflightWarned(sessionId: string): void;

package/dist/hooks/shared/preflight-check.js

@@ -0,0 +1,51 @@
+/**
+ * Preflight check for forgen initialization state.
+ *
+ * Detects "hooks wired but no profile" — a user who ran `forgen install`
+ * but never completed onboarding via `forgen`. Emits a one-time warning
+ * per session so the user knows personalization is disabled.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { FORGEN_HOME, STATE_DIR } from '../../core/paths.js';
+const ME_DIR = path.join(FORGEN_HOME, 'me');
+const PROFILE_PATH = path.join(ME_DIR, 'forge-profile.json');
+export function checkForgenInitialized() {
+    try {
+        if (!fs.existsSync(FORGEN_HOME)) {
+            return {
+                initialized: false,
+                message: '[forgen] ~/.forgen not found — run `forgen` to complete setup.',
+            };
+        }
+        if (!fs.existsSync(PROFILE_PATH)) {
+            return {
+                initialized: false,
+                message: '[forgen] Profile not found — run `forgen` to complete onboarding. Hooks are active but personalization is disabled.',
+            };
+        }
+        return { initialized: true };
+    }
+    catch {
+        return { initialized: true };
+    }
+}
+/** Returns true if a preflight warning has already been emitted this session */
+export function hasPreflightWarned(sessionId) {
+    try {
+        return fs.existsSync(path.join(STATE_DIR, `preflight-warned-${sessionId}`));
+    }
+    catch {
+        return true;
+    }
+}
+/** Mark that a preflight warning has been emitted for this session */
+export function markPreflightWarned(sessionId) {
+    try {
+        fs.mkdirSync(STATE_DIR, { recursive: true });
+        fs.writeFileSync(path.join(STATE_DIR, `preflight-warned-${sessionId}`), '1');
+    }
+    catch {
+        // fail-open
+    }
+}

package/dist/hooks/stop-guard.js

@@ -24,10 +24,7 @@ import * as os from 'node:os';
 import { readStdinJSON } from './shared/read-stdin.js';
 import { approve, approveWithWarning, blockStop, failOpenWithTracking } from './shared/hook-response.js';
 import { takeLastExtractionNotice } from '../core/extraction-notice.js';
-import { checkConclusionVerificationRatio } from '../checks/conclusion-verification-ratio.js';
-import { checkSelfScoreInflation } from '../checks/self-score-deflation.js';
-import { checkFactVsAgreement } from '../checks/fact-vs-agreement.js';
-import { checkDangerousResponsePattern } from '../checks/dangerous-response-pattern.js';
+import { runMetaGuards } from '../checks/_shared/meta-guard-dispatch.js';
 import { sanitizeForGuard } from '../checks/_shared/text-sanitizer.js';
 import { STATE_DIR } from '../core/paths.js';
 import { sanitizeId } from './shared/sanitize-id.js';
@@ -179,14 +176,19 @@ function messageTriggersRule(message, rule) {
     const t = rule.trigger;
     if (!t.response_keywords_regex)
         return false;
+    // ADR-009 §7 후속: 룰-스토어 트리거도 built-in 메타가드와 동일하게 sanitize 된
+    // 텍스트로 매칭한다. 트리거 어휘를 코드펜스/백틱/인용으로 *언급만* 한 referential
+    // 케이스(메타 대화)에서 룰이 self-match 하던 거짓양성을 줄인다. 자연 산문 속 실제
+    // 주장은 sanitize 후에도 남으므로 진짜 탐지(TP)는 보존된다.
+    const m = sanitizeForGuard(message);
     const includeRes = compileSafeRegex(t.response_keywords_regex, 'i');
     if (!includeRes.regex)
         return false;
-    if (!safeRegexTest(includeRes.regex, message))
+    if (!safeRegexTest(includeRes.regex, m))
         return false;
     if (t.context_exclude_regex) {
         const excludeRes = compileSafeRegex(t.context_exclude_regex, 'i');
-        if (excludeRes.regex && safeRegexTest(excludeRes.regex, message))
+        if (excludeRes.regex && safeRegexTest(excludeRes.regex, m))
             return false;
     }
     return true;
@@ -498,71 +500,28 @@ export async function main() {
         // block/approve 어느 경로이든 동일하게 기록 (참조는 응답 내용이 결정).
         const sessionIdForRef = input?.session_id ?? 'unknown';
         emitRecallReferencesFailOpen(sessionIdForRef, lastMessage);
-        // TEST-1/2/3: rule-free meta guards — FORGEN_USER_CONFIRMED=1 우회 공통.
-        // Pathfinder D7: 3중 보일러플레이트를 CHECKS 배열 + for-loop 디스패처로 통합.
-        // Pathfinder D4/D5: sanitizeForGuard 가 모든 체크 입력 단계에 일괄 적용.
+        // TEST-1/2/3 + DANGEROUS: rule-free meta guards — FORGEN_USER_CONFIRMED=1 우회 공통.
+        // ADR-009 §2a: 디스패처 본체를 checks/_shared/meta-guard-dispatch 로 추출 (Stop 과
+        // SubagentStop 이 공유). 여기서는 순수 평가 결과를 받아 recordViolation·blockStop
+        // 부수효과만 수행한다. 평가 순서/sanitize/laziness 는 추출 모듈이 보존.
         if (process.env.FORGEN_USER_CONFIRMED !== '1') {
             const sessionId = input?.session_id ?? 'unknown';
             const recentTools = loadRecentToolNames(sessionId);
-            const sanitized = sanitizeForGuard(lastMessage);
-            // 평가 순서: DANGEROUS-RESPONSE (즉시 차단 — 안전 우선) → TEST-2 (강한 신호) → TEST-3 (텍스트 비율) → TEST-1 (alert-only).
-            const checks = [
-                {
-                    shortId: 'dangerous-response-pattern',
-                    ruleSlug: 'rule:DANGEROUS-RESPONSE — destructive command suggestion',
-                    kind: 'block',
-                    // 주의: sanitizer 가 백틱/코드블록을 제거하므로 raw lastMessage 를 전달.
-                    // 위험 명령은 코드 fence 안에 있어도 동등하게 위험함.
-                    run: () => {
-                        const r = checkDangerousResponsePattern({ text: lastMessage });
-                        return { triggered: r.block, reason: r.reason };
-                    },
-                },
-                {
-                    shortId: 'self-score-inflation',
-                    ruleSlug: 'rule:TEST-2 — self-score inflation',
-                    kind: 'block',
-                    run: () => {
-                        const r = checkSelfScoreInflation({ text: sanitized, recentTools });
-                        return { triggered: r.block, reason: r.reason };
-                    },
-                },
-                {
-                    shortId: 'conclusion-ratio',
-                    ruleSlug: 'rule:TEST-3 — conclusion/verification ratio',
-                    kind: 'block',
-                    run: () => {
-                        const r = checkConclusionVerificationRatio({ text: sanitized });
-                        return { triggered: r.block, reason: r.reason };
-                    },
-                },
-                {
-                    shortId: 'fact-vs-agreement',
-                    ruleSlug: 'rule:TEST-1 — fact vs agreement',
-                    kind: 'correction', // alert-level only per fact-vs-agreement.ts design
-                    run: () => {
-                        const r = checkFactVsAgreement({ text: sanitized, recentTools, minMeasurements: 1 });
-                        return { triggered: r.alert, reason: r.reason };
-                    },
-                },
-            ];
-            for (const c of checks) {
-                const out = c.run();
-                if (!out.triggered)
-                    continue;
+            const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1 });
+            for (const r of results) {
                 recordViolation({
-                    rule_id: `builtin:${c.shortId}`,
+                    rule_id: `builtin:${r.shortId}`,
                     session_id: sessionId,
                     source: 'stop-guard',
-                    kind: c.kind,
+                    kind: r.kind,
                     message_preview: lastMessage.slice(0, 120),
                 });
-                if (c.kind !== 'block')
+                if (r.kind !== 'block')
                     continue;
-                const reasonText = `[forgen:stop-guard/${c.shortId}] ${out.reason}
+                const reasonText = `[forgen:stop-guard/${r.shortId}] ${r.reason}
 
 (Override this turn: set FORGEN_USER_CONFIRMED=1 (audited).)`;
-                console.log(blockStop(reasonText, c.ruleSlug));
+                console.log(blockStop(reasonText, r.ruleSlug));
                 return;
             }
         }

package/dist/hooks/subagent-stop-guard.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * Forgen — SubagentStop Guard (ADR-009 §2)
+ *
+ * 워크플로우/Task subagent 의 마지막 응답에 메타 가드(TEST-1/2/3 + DANGEROUS)를
+ * 적용한다. probe 실측(2026-05-29)으로 워크플로우 내부 에이전트도 forgen 훅을
+ * 발화함이 확인되어, 대화 밖에서 수행되는 subagent 산출물도 검증 사각지대에서
+ * 끌어낸다. SubagentStop 은 `decision:"block"` + `reason` 을 지원하므로(공식 문서
+ * 확인) 메인 Stop 과 동일한 Mech-B 재개 메커니즘이 작동한다.
+ *
+ * 설계 (ADR-009 §2a/2c/2d):
+ *   - 평가 본체는 checks/_shared/meta-guard-dispatch.runMetaGuards 를 Stop 과 공유.
+ *   - block-count 는 (sessionId, agentId) 합성 키로 분리 → 동시 subagent 간 stuck-
+ *     loop 카운터 충돌 방지 (2c).
+ *   - recentTools 는 per-agent modified-files (post-tool-use 2d 키) 에서 로드 →
+ *     subagent 자기 tool 윈도우로 TEST-1/2 를 정확히 판정 (2d).
+ *
+ * fail-open: 어떤 단계든 throw/누락이면 approve. subagent 추적/검증은 best-effort —
+ * 에이전트 실행을 막지 않는다.
+ */
+/** SubagentStop 에는 last_assistant_message 가 없으므로 transcript JSONL 을 역순 스캔. */
+export declare function readLastAssistantFromTranscript(transcriptPath?: string): string | null;
+export declare function main(): Promise<void>;

package/dist/hooks/subagent-stop-guard.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Forgen — SubagentStop Guard (ADR-009 §2)
+ *
+ * 워크플로우/Task subagent 의 마지막 응답에 메타 가드(TEST-1/2/3 + DANGEROUS)를
+ * 적용한다. probe 실측(2026-05-29)으로 워크플로우 내부 에이전트도 forgen 훅을
+ * 발화함이 확인되어, 대화 밖에서 수행되는 subagent 산출물도 검증 사각지대에서
+ * 끌어낸다. SubagentStop 은 `decision:"block"` + `reason` 을 지원하므로(공식 문서
+ * 확인) 메인 Stop 과 동일한 Mech-B 재개 메커니즘이 작동한다.
+ *
+ * 설계 (ADR-009 §2a/2c/2d):
+ *   - 평가 본체는 checks/_shared/meta-guard-dispatch.runMetaGuards 를 Stop 과 공유.
+ *   - block-count 는 (sessionId, agentId) 합성 키로 분리 → 동시 subagent 간 stuck-
+ *     loop 카운터 충돌 방지 (2c).
+ *   - recentTools 는 per-agent modified-files (post-tool-use 2d 키) 에서 로드 →
+ *     subagent 자기 tool 윈도우로 TEST-1/2 를 정확히 판정 (2d).
+ *
+ * fail-open: 어떤 단계든 throw/누락이면 approve. subagent 추적/검증은 best-effort —
+ * 에이전트 실행을 막지 않는다.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { readStdinJSON } from './shared/read-stdin.js';
+import { approve, blockStop, failOpenWithTracking } from './shared/hook-response.js';
+import { isHookEnabled } from './hook-config.js';
+import { sanitizeId } from './shared/sanitize-id.js';
+import { recordHookTiming } from './shared/hook-timing.js';
+import { STATE_DIR } from '../core/paths.js';
+import { runMetaGuards } from '../checks/_shared/meta-guard-dispatch.js';
+import { recordViolation } from '../engine/lifecycle/signals.js';
+import { incrementBlockCount, resetBlockCount, getStuckLoopThreshold, logDriftEvent, } from './stop-guard.js';
+const HOOK_NAME = 'subagent-stop-guard';
+/** SubagentStop 에는 last_assistant_message 가 없으므로 transcript JSONL 을 역순 스캔. */
+export function readLastAssistantFromTranscript(transcriptPath) {
+    if (!transcriptPath)
+        return null;
+    try {
+        const lines = fs.readFileSync(transcriptPath, 'utf-8').trim().split('\n');
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i].trim();
+            if (!line)
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (entry.role !== 'assistant')
+                    continue;
+                if (typeof entry.content === 'string')
+                    return entry.content;
+                if (Array.isArray(entry.content)) {
+                    const parts = entry.content
+                        .map((p) => {
+                        if (typeof p === 'string')
+                            return p;
+                        if (p && typeof p === 'object' && 'text' in p)
+                            return String(p.text);
+                        return '';
+                    })
+                        .filter(Boolean);
+                    if (parts.length)
+                        return parts.join('\n');
+                }
+            }
+            catch {
+                // skip malformed line
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** ADR-009 §2d: per-agent modified-files 에서 recentToolNames 로드. 없으면 []. */
+function loadAgentRecentTools(sessionId, agentId) {
+    try {
+        const key = `${sessionId}.agent-${agentId}`;
+        const p = path.join(STATE_DIR, `modified-files-${sanitizeId(key)}.json`);
+        if (!fs.existsSync(p))
+            return [];
+        const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (Array.isArray(data.recentToolNames)) {
+            return data.recentToolNames.filter((n) => typeof n === 'string');
+        }
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function main() {
+    const started = Date.now();
+    try {
+        if (!isHookEnabled(HOOK_NAME)) {
+            console.log(approve());
+            return;
+        }
+        const input = await readStdinJSON();
+        const lastMessage = readLastAssistantFromTranscript(input?.transcript_path);
+        if (!lastMessage) {
+            console.log(approve());
+            return;
+        }
+        // 사용자 명시 우회 — 메인 Stop 과 일관.
+        if (process.env.FORGEN_USER_CONFIRMED === '1') {
+            console.log(approve());
+            return;
+        }
+        const sessionId = input?.session_id ?? 'unknown';
+        const agentId = input?.agent_id ?? input?.agentId ?? 'unknown';
+        const recentTools = loadAgentRecentTools(sessionId, agentId);
+        const results = runMetaGuards({ lastMessage, recentTools, minMeasurements: 1 });
+        // 2c: stuck-loop 카운터를 (sessionId, agentId) 로 분리해 동시 subagent 간 충돌 방지.
+        const counterKey = `${sessionId}:${agentId}`;
+        for (const r of results) {
+            recordViolation({
+                rule_id: `builtin:${r.shortId}`,
+                session_id: sessionId,
+                source: HOOK_NAME,
+                kind: r.kind,
+                message_preview: lastMessage.slice(0, 120),
+            });
+            if (r.kind !== 'block')
+                continue;
+            const count = incrementBlockCount(counterKey, r.shortId);
+            if (count > getStuckLoopThreshold()) {
+                // 같은 subagent 가 같은 가드에 반복 차단 → block reason 에 말려든 루프.
+                // force approve + drift 기록 후 카운터 리셋 (메인 Stop 과 동일 정책).
+                logDriftEvent({
+                    kind: 'subagent_stuck_loop_force_approve',
+                    session_id: counterKey,
+                    rule_id: r.shortId,
+                    count,
+                    reason_preview: r.reason.slice(0, 120),
+                    message_preview: lastMessage.slice(0, 120),
+                });
+                resetBlockCount(counterKey, r.shortId);
+                console.log(approve());
+                return;
+            }
+            const reasonText = `[forgen:subagent-stop-guard/${r.shortId}] (agent ${agentId.slice(0, 8)}) ${r.reason}
+
+(Override this turn: set FORGEN_USER_CONFIRMED=1 (audited).)`;
+            console.log(blockStop(reasonText, r.ruleSlug));
+            return;
+        }
+        console.log(approve());
+    }
+    catch (e) {
+        console.log(failOpenWithTracking(HOOK_NAME, e));
+    }
+    finally {
+        recordHookTiming(HOOK_NAME, Date.now() - started, 'SubagentStop');
+    }
+}
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+    void main();
+}

package/dist/hooks/subagent-tracker.d.ts

@@ -3,8 +3,41 @@
  * Forgen — SubagentStart/Stop Hook
  *
  * 에이전트 생성/종료 추적.
- * - 활성 에이전트 수 모니터링
- * - 에이전트 동시 실행 제한 (10개 초과 시 경고)
+ * - 활성 에이전트 수 모니터링 + 동시 실행 경고 (ADR-009 §4: 기본 16, workflow 면제)
  * - 에이전트 실행 이력 기록
+ * - ADR-009 §A: 상태 갱신을 file-lock 으로 보호 (동시 fanout lost-update 방지)
  */
-export {};
+/**
+ * 동시 에이전트 경고 임계값.
+ * ADR-009 §4: dynamic workflows 는 동시 16 까지 정상 사용하므로 기본값을 16 으로
+ * 올리고 env 로 조정 가능하게 한다. 과거 10 고정값은 workflow/team/swarm 실행마다
+ * 거짓 경고를 뱉었다.
+ */
+export declare function maxConcurrentAgents(): number;
+/**
+ * 동시성 경고를 띄울지 결정 (순수 — 테스트 대상).
+ * ADR-009 §4/§B: workflow-subagent 는 동시 16 이 정상이므로 면제. 그 외 에이전트가
+ * 임계값을 초과할 때만 경고.
+ */
+export declare function shouldWarnConcurrency(agentType: string, activeCount: number, max: number): boolean;
+export interface AgentEvent {
+    sessionId: string;
+    action: 'start' | 'stop';
+    agentId: string;
+    agentType?: string;
+    model?: string;
+}
+/**
+ * 에이전트 이벤트를 file-lock 아래에서 적용한다 (ADR-009 §A).
+ *
+ * 락이 없던 시절에는 동시 SubagentStart (워크플로우 fanout) 가 같은 active-agents
+ * 파일을 read-modify-write 하면서 lost-update 로 일부 에이전트가 누락됐다 (probe 에서
+ * 3개 중 1개 손실 관찰). 락 안에서 **fresh re-read** 후 mutate 해야 변경이 보존된다.
+ * staleMs 는 hook fn 이 짧으므로 5s 로 단축.
+ *
+ * statePath 는 테스트 주입용 (기본은 sessionId 파생 경로). 반환값은 start 후 활성
+ * 에이전트 수 (경고 판정에 사용; stop 은 0).
+ */
+export declare function recordAgentEvent(ev: AgentEvent, statePath?: string): Promise<{
+    activeCount: number;
+}>;

package/dist/hooks/subagent-tracker.js

@@ -3,9 +3,9 @@
  * Forgen — SubagentStart/Stop Hook
  *
  * 에이전트 생성/종료 추적.
- * - 활성 에이전트 수 모니터링
- * - 에이전트 동시 실행 제한 (10개 초과 시 경고)
+ * - 활성 에이전트 수 모니터링 + 동시 실행 경고 (ADR-009 §4: 기본 16, workflow 면제)
  * - 에이전트 실행 이력 기록
+ * - ADR-009 §A: 상태 갱신을 file-lock 으로 보호 (동시 fanout lost-update 방지)
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -14,23 +14,47 @@ import { isHookEnabled } from './hook-config.js';
 import { sanitizeId } from './shared/sanitize-id.js';
 import { atomicWriteJSON } from './shared/atomic-write.js';
 import { approve, approveWithWarning, failOpenWithTracking } from './shared/hook-response.js';
+import { withFileLock } from './shared/file-lock.js';
 import { STATE_DIR } from '../core/paths.js';
-const MAX_CONCURRENT_AGENTS = 10;
+/**
+ * 동시 에이전트 경고 임계값.
+ * ADR-009 §4: dynamic workflows 는 동시 16 까지 정상 사용하므로 기본값을 16 으로
+ * 올리고 env 로 조정 가능하게 한다. 과거 10 고정값은 workflow/team/swarm 실행마다
+ * 거짓 경고를 뱉었다.
+ */
+export function maxConcurrentAgents() {
+    const env = Number(process.env.FORGEN_MAX_CONCURRENT_AGENTS);
+    return Number.isFinite(env) && env > 0 ? env : 16;
+}
+/**
+ * Claude Code 가 dynamic-workflow 내부 에이전트에 부여하는 agentType (probe 실측,
+ * 2026-05-29). 워크플로우 에이전트는 동시 16 이 정상이므로 동시성 경고에서 면제한다.
+ */
+const WORKFLOW_AGENT_TYPE = 'workflow-subagent';
+/**
+ * 동시성 경고를 띄울지 결정 (순수 — 테스트 대상).
+ * ADR-009 §4/§B: workflow-subagent 는 동시 16 이 정상이므로 면제. 그 외 에이전트가
+ * 임계값을 초과할 때만 경고.
+ */
+export function shouldWarnConcurrency(agentType, activeCount, max) {
+    if (agentType === WORKFLOW_AGENT_TYPE)
+        return false;
+    return activeCount > max;
+}
 const AGENT_GC_AGE_MS = 60 * 60 * 1000; // 1시간 이상 종료된 에이전트는 GC
 function getAgentsStatePath(sessionId) {
     return path.join(STATE_DIR, `active-agents-${sanitizeId(sessionId)}.json`);
 }
-function loadAgentsState(sessionId) {
+function loadAgentsStateAt(statePath, sessionId) {
     try {
-        const filePath = getAgentsStatePath(sessionId);
-        if (fs.existsSync(filePath)) {
-            return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        if (fs.existsSync(statePath)) {
+            return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
         }
     }
-    catch { /* agent state parse failure — starting fresh, active agent count history for this session is lost */ }
+    catch { /* parse failure — starting fresh, prior agent history for this session is lost */ }
     return { sessionId, agents: [] };
 }
-function saveAgentsState(state) {
+function saveAgentsStateAt(statePath, state) {
     // GC: 1시간 이상 종료된 에이전트 제거
     const now = Date.now();
     state.agents = state.agents.filter(a => {
@@ -38,7 +62,41 @@ function saveAgentsState(state) {
             return true; // 활성 에이전트는 유지
         return now - new Date(a.stoppedAt).getTime() < AGENT_GC_AGE_MS;
     });
-    atomicWriteJSON(getAgentsStatePath(state.sessionId), state);
+    atomicWriteJSON(statePath, state);
+}
+/**
+ * 에이전트 이벤트를 file-lock 아래에서 적용한다 (ADR-009 §A).
+ *
+ * 락이 없던 시절에는 동시 SubagentStart (워크플로우 fanout) 가 같은 active-agents
+ * 파일을 read-modify-write 하면서 lost-update 로 일부 에이전트가 누락됐다 (probe 에서
+ * 3개 중 1개 손실 관찰). 락 안에서 **fresh re-read** 후 mutate 해야 변경이 보존된다.
+ * staleMs 는 hook fn 이 짧으므로 5s 로 단축.
+ *
+ * statePath 는 테스트 주입용 (기본은 sessionId 파생 경로). 반환값은 start 후 활성
+ * 에이전트 수 (경고 판정에 사용; stop 은 0).
+ */
+export async function recordAgentEvent(ev, statePath = getAgentsStatePath(ev.sessionId)) {
+    fs.mkdirSync(path.dirname(statePath), { recursive: true }); // lock 파일 생성 전 디렉토리 보장
+    let activeCount = 0;
+    await withFileLock(statePath, () => {
+        const state = loadAgentsStateAt(statePath, ev.sessionId); // 락 안에서 fresh re-read
+        if (ev.action === 'start') {
+            state.agents.push({
+                agentId: ev.agentId,
+                agentType: ev.agentType || undefined,
+                model: ev.model,
+                startedAt: new Date().toISOString(),
+            });
+            activeCount = state.agents.filter(a => !a.stoppedAt).length;
+        }
+        else if (ev.action === 'stop') {
+            const agent = state.agents.find(a => a.agentId === ev.agentId && !a.stoppedAt);
+            if (agent)
+                agent.stoppedAt = new Date().toISOString();
+        }
+        saveAgentsStateAt(statePath, state);
+    }, { staleMs: 5000 });
+    return { activeCount };
 }
 async function main() {
     const data = await readStdinJSON();
@@ -54,37 +112,26 @@ async function main() {
     }
     const sessionId = data.session_id ?? 'default';
     // 이벤트 타입은 argv[2] 또는 data 필드에서 판별
-    const action = process.argv[2] ?? data.action ?? '';
+    const action = (process.argv[2] ?? data.action ?? '') === 'stop' ? 'stop' : 'start';
     const agentId = data.agent_id ?? data.agentId ?? `agent-${Date.now()}`;
     const agentType = data.agent_type ?? data.agentType ?? data.subagent_type ?? '';
-    const state = loadAgentsState(sessionId);
-    if (action === 'start') {
-        const model = data.model ?? data.agentModel ?? undefined;
-        state.agents.push({
-            agentId,
-            agentType: agentType || undefined,
-            model,
-            startedAt: new Date().toISOString(),
-        });
-        saveAgentsState(state);
-        // 활성 에이전트 수 체크
-        const activeCount = state.agents.filter(a => !a.stoppedAt).length;
-        if (activeCount > MAX_CONCURRENT_AGENTS) {
-            console.log(approveWithWarning(`<compound-tool-warning>\n[Forgen] ⚠ ${activeCount} active agents — too many concurrent executions. Watch resource usage.\n</compound-tool-warning>`));
-            return;
-        }
-    }
-    else if (action === 'stop') {
-        // 해당 에이전트 종료 표시
-        const agent = state.agents.find(a => a.agentId === agentId && !a.stoppedAt);
-        if (agent) {
-            agent.stoppedAt = new Date().toISOString();
-        }
-        saveAgentsState(state);
+    const model = data.model ?? data.agentModel ?? undefined;
+    // ADR-009 §A: 상태 갱신은 file-lock 아래에서. 락 실패/타임아웃은 .catch 의 fail-open
+    // 으로 흡수 (추적은 best-effort — 에이전트 실행 자체를 막지 않는다).
+    const { activeCount } = await recordAgentEvent({ sessionId, action, agentId, agentType, model });
+    // 동시성 경고 (락 밖). 면제/임계값 판정은 shouldWarnConcurrency (테스트 박제).
+    if (action === 'start' && shouldWarnConcurrency(agentType, activeCount, maxConcurrentAgents())) {
+        console.log(approveWithWarning(`<compound-tool-warning>\n[Forgen] ⚠ ${activeCount} active agents — too many concurrent executions. Watch resource usage.\n</compound-tool-warning>`));
+        return;
     }
     console.log(approve());
 }
-main().catch((e) => {
-    process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('subagent-tracker', e));
-});
+// import.meta 가드: 직접 실행 시에만 main() — 테스트가 헬퍼를 import 할 때
+// stdin 을 읽는 main 이 돌지 않도록 한다 (모듈 위생).
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+    main().catch((e) => {
+        process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
+        console.log(failOpenWithTracking('subagent-tracker', e));
+    });
+}

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Forgen harness hooks (auto-generated, 21/21 active)",
+  "description": "Forgen harness hooks (auto-generated, 22/22 active)",
   "hooks": {
     "UserPromptSubmit": [
       {
@@ -175,6 +175,11 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/hooks/subagent-tracker.js\" \"stop\"",
             "timeout": 2
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/hooks/subagent-stop-guard.js\"",
+            "timeout": 10
           }
         ]
       }