@wooojin/forgen 0.4.0 → 0.4.3

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

@@ -20,6 +20,8 @@ import { approve, approveWithWarning, failOpenWithTracking } from './shared/hook
 import { STATE_DIR } from '../core/paths.js';
 import { recordHookTiming } from './shared/hook-timing.js';
 import { createDriftState, evaluateDrift } from '../core/drift-score.js';
+import { appendImplicitFeedback } from '../store/implicit-feedback-store.js';
+const RECENT_TOOL_NAMES_WINDOW = 20;
 /** Lightweight hash for content comparison (not cryptographic) */
 function simpleHash(content) {
     let hash = 0;
@@ -30,15 +32,6 @@ function simpleHash(content) {
     }
     return hash.toString(36);
 }
-const IMPLICIT_FEEDBACK_LOG = path.join(STATE_DIR, 'implicit-feedback.jsonl');
-/** Record implicit feedback signal to JSONL */
-function recordImplicitFeedback(entry) {
-    try {
-        fs.mkdirSync(STATE_DIR, { recursive: true });
-        fs.appendFileSync(IMPLICIT_FEEDBACK_LOG, JSON.stringify(entry) + '\n');
-    }
-    catch { /* fail-open: implicit feedback recording must not throw */ }
-}
 // ── State management ──
 function getModifiedFilesPath(sessionId) {
     return path.join(STATE_DIR, `modified-files-${sanitizeId(sessionId)}.json`);
@@ -82,15 +75,21 @@ const AGENT_QUALITY_PATTERNS = [
     { pattern: /(?:context (?:window|limit) (?:exceeded|reached)|too (?:large|long) to (?:read|process))/i, signal: 'agent_context_overflow', severity: 'warning', message: 'Agent hit context limits — output may be incomplete' },
 ];
 export function validateAgentOutput(toolResponse) {
-    if (!toolResponse || toolResponse.trim().length < AGENT_MIN_OUTPUT_LENGTH) {
+    // tool_response 는 string / object / array 모두 가능. main() 측에서 stringify 를 한 번 더
+    // 하지만 직접 호출 보호 (defense in depth).
+    if (typeof toolResponse !== 'string') {
+        toolResponse = toolResponse == null ? '' : JSON.stringify(toolResponse);
+    }
+    const r = toolResponse;
+    if (!r || r.trim().length < AGENT_MIN_OUTPUT_LENGTH) {
         return {
             signal: 'agent_empty_output',
             severity: 'warning',
-            message: `Agent returned minimal output (${toolResponse?.trim().length ?? 0} chars). Verify the result is usable.`,
+            message: `Agent returned minimal output (${r.trim().length} chars). Verify the result is usable.`,
         };
     }
     for (const p of AGENT_QUALITY_PATTERNS) {
-        if (p.pattern.test(toolResponse)) {
+        if (p.pattern.test(r)) {
             return { signal: p.signal, severity: p.severity, message: p.message };
         }
     }
@@ -121,10 +120,22 @@ async function main() {
         }
         const toolName = data.tool_name ?? data.toolName ?? '';
         const toolInput = data.tool_input ?? data.toolInput ?? {};
-        const toolResponse = data.tool_response ?? data.toolOutput ?? '';
+        // tool_response 는 string / object / array 모두 가능 (sub-agent 결과는 object 가 흔함).
+        // 모든 downstream 이 string 가정이라 stringify 로 normalize. 회귀 박제: tests/hooks/post-tool-use.test.ts
+        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);
         modState.toolCallCount = (modState.toolCallCount ?? 0) + 1;
+        // TEST-2: recent tool name window — stop-guard 의 self-score inflation 가드가
+        // "최근 세션에서 측정 도구 몇 번 불렸나?" 를 이 배열로 계산한다.
+        if (toolName) {
+            const names = modState.recentToolNames ?? [];
+            names.push(toolName);
+            if (names.length > RECENT_TOOL_NAMES_WINDOW)
+                names.splice(0, names.length - RECENT_TOOL_NAMES_WINDOW);
+            modState.recentToolNames = names;
+        }
         const messages = [];
         let revertDetected = false;
         // 1. Checkpoint (every 5 calls)
@@ -152,8 +163,9 @@ async function main() {
                     // Implicit feedback: repeated edit detection (5+ edits on same file)
                     if (count >= 5) {
                         messages.push(`<compound-tool-warning>\n[Forgen] ⚠ ${path.basename(filePath)} has been modified ${count} times.\nConsider redesigning the overall structure and restarting.\n</compound-tool-warning>`);
-                        recordImplicitFeedback({
+                        appendImplicitFeedback({
                             type: 'repeated_edit',
+                            category: 'edit',
                             file: filePath,
                             editCount: count,
                             at: new Date().toISOString(),
@@ -172,8 +184,9 @@ async function main() {
                         // Skip the most recent hash (which would be the write being "reverted from")
                         if (prevHashes.length >= 2 && prevHashes.slice(0, -1).includes(hash)) {
                             revertDetected = true;
-                            recordImplicitFeedback({
+                            appendImplicitFeedback({
                                 type: 'revert_detected',
+                                category: 'revert',
                                 file: filePath,
                                 at: new Date().toISOString(),
                                 sessionId,
@@ -198,8 +211,9 @@ async function main() {
             const driftResult = evaluateDrift(modState.drift, true, revertDetected);
             if (driftResult.message) {
                 messages.push(`<compound-tool-warning>\n${driftResult.message}\n</compound-tool-warning>`);
-                recordImplicitFeedback({
+                appendImplicitFeedback({
                     type: driftResult.level === 'critical' || driftResult.level === 'hardcap' ? 'drift_critical' : 'drift_warning',
+                    category: 'drift',
                     score: driftResult.score,
                     totalEdits: modState.drift.totalEdits,
                     totalReverts: modState.drift.totalReverts,
@@ -213,8 +227,9 @@ async function main() {
             const agentResult = validateAgentOutput(toolResponse);
             if (agentResult) {
                 messages.push(`<compound-agent-validation>\n[Forgen] ${agentResult.severity === 'error' ? '⛔' : '⚠'} ${agentResult.message}\n</compound-agent-validation>`);
-                recordImplicitFeedback({
+                appendImplicitFeedback({
                     type: `agent_${agentResult.signal}`,
+                    category: 'agent',
                     severity: agentResult.severity,
                     outputLength: toolResponse.trim().length,
                     at: new Date().toISOString(),
@@ -254,14 +269,18 @@ async function main() {
             })() || toolResponse;
             if (target) {
                 try {
-                    const [{ loadActiveRules }, { recordViolation, recordBypass }, { scanForBypass }, { compileSafeRegex, safeRegexTest },] = await Promise.all([
+                    const [{ loadActiveRules }, { recordViolation, recordBypass }, { scanForBypass }, { compileSafeRegex, safeRegexTest }, { preprocessForMatch },] = await Promise.all([
                         import('../store/rule-store.js'),
                         import('../engine/lifecycle/signals.js'),
                         import('../engine/lifecycle/bypass-detector.js'),
                         import('./shared/safe-regex.js'),
+                        import('./shared/command-parser.js'),
                     ]);
                     const rules = loadActiveRules();
-                    // Mech-A pattern_match dispatcher
+                    // Mech-A pattern_match dispatcher — match_target 은 **rule-per-rule**.
+                    // AWS key / DROP 류 secret/dangerous SQL 은 파일 content 에 들어있어도
+                    // 실제 leak 이라 raw 검사가 맞고, rm -rf 류 shell 명령은 quote 안 본문이면
+                    // false-positive 이므로 masked 가 맞다. pre-tool-use 와 동일한 spec 기반 분기.
                     for (const rule of rules) {
                         for (const spec of rule.enforce_via ?? []) {
                             if (spec.hook !== 'PostToolUse' || spec.mech !== 'A')
@@ -277,7 +296,9 @@ async function main() {
                                 log.debug(`rule ${rule.rule_id} unsafe regex: ${re.reason}`);
                                 continue;
                             }
-                            if (!safeRegexTest(re.regex, target))
+                            const matchTarget = (v.params?.match_target ?? 'raw');
+                            const mechTarget = preprocessForMatch(target, matchTarget);
+                            if (!safeRegexTest(re.regex, mechTarget))
                                 continue;
                             recordViolation({
                                 rule_id: rule.rule_id, session_id: sessionId,
@@ -288,8 +309,14 @@ async function main() {
                             messages.push(`<compound-rule-violation>\n[Forgen] Rule ${rule.rule_id.slice(0, 8)} pattern matched in ${toolName} output.\n${spec.block_message ?? rule.policy.slice(0, 120)}\n</compound-rule-violation>`);
                         }
                     }
-                    // T3 bypass detection (same rules, same target)
-                    const candidates = scanForBypass({ rules, tool_name: toolName, tool_output: target, session_id: sessionId });
+                    // T3 bypass detection — scanForBypass 는 rule.policy 자연어에서 패턴 추출이라
+                    // match_target 개념 없음. Write/Edit 는 파일 본문이라 bypass-detector 의
+                    // 자연어 휴리스틱이 false-positive 과다 (L1-no-rm-rf-unconfirmed bypass 20건
+                    // 중 Write/Edit 15건이 실측). 이 경로만 masked. Bash 는 실제 실행된 명령이라
+                    // raw 유지. Mech-A pattern_match 는 위에서 rule-per-rule 로 이미 처리.
+                    const isFileContentTool = toolName === 'Write' || toolName === 'Edit';
+                    const bypassTarget = isFileContentTool ? preprocessForMatch(target, 'masked') : target;
+                    const candidates = scanForBypass({ rules, tool_name: toolName, tool_output: bypassTarget, session_id: sessionId });
                     for (const c of candidates) {
                         recordBypass({ rule_id: c.rule_id, session_id: c.session_id, tool: c.tool, pattern_preview: c.pattern_preview });
                     }
@@ -322,5 +349,5 @@ async function main() {
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('post-tool-use'));
+    console.log(failOpenWithTracking('post-tool-use', e));
 });

package/dist/hooks/pre-compact.js

@@ -74,7 +74,7 @@ export function buildSessionBrief(sessionId) {
     }
     catch { /* fail-open */ }
     // solutionsInjected: read injection-cache-*.json files, collect solutions[].name
-    let solutionsInjected = [];
+    const solutionsInjected = [];
     try {
         if (fs.existsSync(STATE_DIR)) {
             for (const f of fs.readdirSync(STATE_DIR)) {
@@ -271,5 +271,5 @@ Rules:
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('pre-compact'));
+    console.log(failOpenWithTracking('pre-compact', e));
 });

package/dist/hooks/pre-tool-use.d.ts

@@ -10,6 +10,13 @@ interface DangerousPatternEntry {
     pattern: RegExp;
     description: string;
     severity: 'block' | 'warn';
+    /**
+     * match_target (v0.4.1): 'masked' (default) — quote/heredoc 본문 제거 후 매칭.
+     *   실 shell 실행 토큰 검사에 적합. 'raw' — 원본 command 그대로 매칭.
+     *   `python -c "..."`, `eval "..."` 처럼 **quote 안 본문이 실제 payload 로 실행**
+     *   되는 패턴에 사용.
+     */
+    matchTarget?: 'raw' | 'masked';
 }
 /** 위험 Bash 명령어 패턴 (패키지 내장 + 사용자 커스텀 병합) */
 export declare const DANGEROUS_PATTERNS: DangerousPatternEntry[];

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

@@ -19,9 +19,10 @@ import { sanitizeId } from './shared/sanitize-id.js';
 import { incrementEvidence } from '../engine/solution-writer.js';
 import { isReflectionCandidate } from './compound-reflection.js';
 import { isHookEnabled } from './hook-config.js';
-import { approve, approveWithWarning, deny, failOpenWithTracking } from './shared/hook-response.js';
+import { approve, approveWithWarning, denyOrObserve, failOpenWithTracking } from './shared/hook-response.js';
 import { FORGEN_HOME, STATE_DIR } from '../core/paths.js';
 import { recordHookTiming } from './shared/hook-timing.js';
+import { maskQuotedContent } from './shared/command-parser.js';
 const FAIL_COUNTER_PATH = path.join(STATE_DIR, 'pre-tool-fail-counter.json');
 const FAIL_CLOSE_THRESHOLD = 3; // 연속 3회 파싱 실패 시에만 reject
 /** RegExp 안전성 검증 (ReDoS 방지) — 매칭/비매칭 양쪽 모두 테스트 */
@@ -59,12 +60,16 @@ function loadDangerousPatterns() {
                 pattern: new RegExp(entry.pattern, entry.flags ?? ''),
                 description: entry.description,
                 severity: entry.severity,
+                matchTarget: entry.match_target === 'raw' ? 'raw' : 'masked',
             });
         }
     }
     catch {
         // JSON 로드 실패 시 하드코딩 폴백 (최소 안전장치)
-        results.push({ pattern: /rm\s+(-rf|-fr)\s+[/~]/, description: 'rm -rf on root/home path', severity: 'block' }, { pattern: /curl\s+.*\|\s*(ba)?sh/, description: 'curl pipe to shell', severity: 'block' }, { pattern: /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/, description: 'fork bomb', severity: 'block' });
+        results.push(
+        // v0.4.1 false-positive fix: /tmp, /var/folders, /var/tmp 같은 임시 경로는
+        // 일반 개발에서 매일 정리 대상. 위험한 시스템 경로만 blacklist.
+        { pattern: /rm\s+(-rf|-fr)\s+(\/(?!tmp\b|var\/folders\b|var\/tmp\b)|~)/, description: 'rm -rf on root/home path', severity: 'block' }, { pattern: /curl\s+.*\|\s*(ba)?sh/, description: 'curl pipe to shell', severity: 'block' }, { pattern: /:\(\)\s*\{\s*:\|:&\s*\}\s*;:/, description: 'fork bomb', severity: 'block' });
     }
     // 2. 사용자 커스텀 패턴 (~/.compound/dangerous-patterns.json)
     try {
@@ -100,8 +105,14 @@ export function checkDangerousCommand(toolName, toolInput) {
     const command = typeof toolInput === 'string'
         ? toolInput
         : (toolInput.command ?? '');
-    for (const { pattern, description, severity } of DANGEROUS_PATTERNS) {
-        if (pattern.test(command)) {
+    // v0.4.1 (2026-04-24) quote-aware built-in scan:
+    // 기본은 masked (quote/heredoc 본문 제거) — shell 실행 토큰 검사. 하지만
+    // `python -c "..."` / `eval "..."` 처럼 quote 안 본문이 실 payload 로 실행되는
+    // 패턴은 match_target:raw 로 지정해 원본 command 전체 검사.
+    const maskedCommand = maskQuotedContent(command);
+    for (const { pattern, description, severity, matchTarget } of DANGEROUS_PATTERNS) {
+        const target = matchTarget === 'raw' ? command : maskedCommand;
+        if (pattern.test(target)) {
             return { action: severity, description, command: command.slice(0, 100) };
         }
     }
@@ -294,7 +305,7 @@ async function main() {
             // for `forgen doctor` / log inspection. Mirrors `db-guard.ts:85-96`.
             const failCount = getAndIncrementFailCount();
             if (failCount >= FAIL_CLOSE_THRESHOLD) {
-                console.log(deny(`[Forgen] PreToolUse: stdin parse failed ${failCount} consecutive times — blocking for safety.`));
+                console.log(denyOrObserve('pre-tool-use', `[Forgen] PreToolUse: stdin parse failed ${failCount} consecutive times — blocking for safety.`));
             }
             else {
                 process.stderr.write(`[ch-hook] pre-tool-use stdin parse failed (${failCount}/${FAIL_CLOSE_THRESHOLD})\n`);
@@ -315,10 +326,11 @@ async function main() {
         // 이렇게 해야 rule.block_message (맥락 있는 안내) 가 제네릭 "Dangerous command blocked" 대신 노출됨.
         // fail-open: 예외는 hook 차단 안 함.
         try {
-            const [{ loadActiveRules }, { recordViolation }, { compileSafeRegex, safeRegexTest },] = await Promise.all([
+            const [{ loadActiveRules }, { recordViolation }, { compileSafeRegex, safeRegexTest }, { preprocessForMatch },] = await Promise.all([
                 import('../store/rule-store.js'),
                 import('../engine/lifecycle/signals.js'),
                 import('./shared/safe-regex.js'),
+                import('./shared/command-parser.js'),
             ]);
             const rules = loadActiveRules();
             const command = typeof toolInput.command === 'string'
@@ -339,7 +351,13 @@ async function main() {
                         log.debug(`rule ${rule.rule_id} unsafe regex: ${re.reason}`);
                         continue;
                     }
-                    if (!safeRegexTest(re.regex, command))
+                    // TEST-6 / RC5: quote-aware preprocessing. Default 'raw' = backward compat.
+                    // Rules that target real command invocations should set match_target: 'masked'
+                    // so quoted argument text (e.g. body of `forgen compound --solution "..."`)
+                    // doesn't trigger false positive blocks.
+                    const matchTarget = (v.params?.match_target ?? 'raw');
+                    const target = preprocessForMatch(command, matchTarget);
+                    if (!safeRegexTest(re.regex, target))
                         continue;
                     const requiresFlag = v.params?.requires_flag;
                     const confirmed = process.env.FORGEN_USER_CONFIRMED === '1';
@@ -348,7 +366,7 @@ async function main() {
                         const baseMsg = spec.block_message ?? `[${rule.rule_id}] policy violation: ${rule.policy.slice(0, 120)}`;
                         // G8: override 힌트 — FORGEN_USER_CONFIRMED=1 으로 사용자 명시 승인 가능, 감사 로그 기록됨.
                         const msgWithHint = `${baseMsg}\n\n(override: set FORGEN_USER_CONFIRMED=1 (bypass will be audited in violations.jsonl))`;
-                        console.log(deny(msgWithHint));
+                        console.log(denyOrObserve('pre-tool-use', msgWithHint));
                         return;
                     }
                     if (requiresFlag && confirmed) {
@@ -370,7 +388,7 @@ async function main() {
         // Bash 도구: 위험 명령어 감지 (빌트인 safety net)
         const check = checkDangerousCommand(toolName, toolInput);
         if (check.action === 'block') {
-            console.log(deny(`[Forgen] Dangerous command blocked: ${check.description}\nCommand: ${check.command}`));
+            console.log(denyOrObserve('pre-tool-use', `[Forgen] Dangerous command blocked: ${check.description}\nCommand: ${check.command}`));
             return;
         }
         if (check.action === 'warn') {
@@ -413,5 +431,5 @@ main().catch((e) => {
     });
     process.stderr.write(`[ch-hook] ${hookErr.name}: ${hookErr.message}\n`);
     // fail-open: approve on internal error to avoid blocking all tool calls
-    console.log(failOpenWithTracking('pre-tool-use'));
+    console.log(failOpenWithTracking('pre-tool-use', e));
 });

package/dist/hooks/rate-limiter.js

@@ -10,7 +10,7 @@ import * as path from 'node:path';
 import { readStdinJSON } from './shared/read-stdin.js';
 import { atomicWriteJSON } from './shared/atomic-write.js';
 import { isHookEnabled } from './hook-config.js';
-import { approve, deny, failOpenWithTracking } from './shared/hook-response.js';
+import { approve, denyOrObserve, failOpenWithTracking } from './shared/hook-response.js';
 import { STATE_DIR } from '../core/paths.js';
 const RATE_LIMIT_PATH = path.join(STATE_DIR, 'rate-limit.json');
 const DEFAULT_LIMIT = 30; // calls per minute
@@ -75,12 +75,12 @@ async function main() {
         saveRateLimitState(updatedState);
     }
     if (exceeded) {
-        console.log(deny(`[Forgen] Rate limit exceeded (${count}/${DEFAULT_LIMIT}/min). Wait before retrying.`));
+        console.log(denyOrObserve('rate-limiter', `[Forgen] Rate limit exceeded (${count}/${DEFAULT_LIMIT}/min). Wait before retrying.`));
         return;
     }
     console.log(approve());
 }
 main().catch((e) => {
     process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-    console.log(failOpenWithTracking('rate-limiter'));
+    console.log(failOpenWithTracking('rate-limiter', e));
 });

package/dist/hooks/secret-filter.js

@@ -87,5 +87,5 @@ main().catch((e) => {
         hookName: 'secret-filter', eventType: 'PostToolUse', cause: e,
     });
     process.stderr.write(`[ch-hook] ${hookErr.name}: ${hookErr.message}\n`);
-    console.log(failOpenWithTracking('secret-filter'));
+    console.log(failOpenWithTracking('secret-filter', e));
 });

package/dist/hooks/session-recovery.js

@@ -320,6 +320,17 @@ async function main() {
             }
         }
         catch { /* fail-open */ }
+        // US-M1 (RC6 가드): 직전 forge-loop findings 또는 진행 중 stories 자동 inject.
+        // 본 세션 자기증거 — head -80 truncation 으로 findings 누락 → 같은 가설 재발.
+        try {
+            const { readForgeLoopState, renderForgeLoopForSession } = await import('./shared/forge-loop-state.js');
+            const block = renderForgeLoopForSession(readForgeLoopState());
+            if (block)
+                recoveryMessages.push(block);
+        }
+        catch (e) {
+            log.debug('forge-loop findings inject 실패', e);
+        }
         const sessionId = sessionContext.sessionId;
         // 이전 세션 자동 compound (fire-and-forget)
         // /new로 세션 리셋 시 SessionStart가 다시 호출됨 — 이때 이전 transcript를 compound
@@ -429,6 +440,6 @@ async function main() {
 if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fileURLToPath(import.meta.url)) {
     main().catch((e) => {
         process.stderr.write(`[ch-hook] ${e instanceof Error ? e.message : String(e)}\n`);
-        console.log(failOpenWithTracking('session-recovery'));
+        console.log(failOpenWithTracking('session-recovery', e));
     });
 }

package/dist/hooks/shared/blocking-allowlist.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Blocking ALLOW-LIST — P3' (2026-04-27)
+ *
+ * 사용자 작업을 차단(block)할 권한을 가진 hook 의 명시적 화이트리스트.
+ * 목록 외 hook 의 부정적 판정은 "관찰 신호"(log only) 로만 처리되어야 한다.
+ *
+ * RC5 (retro-v040): 분산된 detector 가 각자 block 결정을 내리면서 false-positive
+ * 가 메인 로직 흐름까지 차단하는 회귀 패턴 발생. ALLOW-LIST 명시화로 차단 권한
+ * 의 source-of-truth 를 단일화.
+ *
+ * v0.4.2 정책:
+ *   - 본 모듈은 ALLOW-LIST 정의 + 검증 helper. 기존 deny() 직접 호출 hook 들은
+ *     v0.4.2 에서 denyOrObserve(name, reason) 로 마이그레이션 완료.
+ *   - 신규 hook 추가 시 차단 권한이 필요하면 본 ALLOW-LIST 에 추가 + 본 파일의
+ *     사유 문서화 의무. 본 commit diff 가 review 필수 항목.
+ *
+ * 멤버 사유:
+ *   - stop-guard: Stop hook — false-completion 메타 가드 (자가 검증 강제)
+ *   - pre-tool-use: Bash dangerous-pattern + 수동 confirm 가드
+ *   - secret-filter: Write/Edit 결과의 .env / API key 노출 차단
+ *   - db-guard: Bash 의 destructive DB 명령 (DROP/TRUNCATE/DELETE) 차단
+ *   - rate-limiter: 사용자 작업 빈도 임계 초과 시 cool-down 차단 (resource abuse 방어)
+ */
+export declare const BLOCKING_ALLOWLIST: ReadonlySet<string>;
+/** hook 이 block 결정을 출력할 권한이 있는지. */
+export declare function canBlock(hookName: string): boolean;
+/** ALLOW-LIST 에 추가하려는 hook 이 정책 문서화를 요구하는지 (lint helper). */
+export declare function requiresPolicyDoc(hookName: string): boolean;

package/dist/hooks/shared/blocking-allowlist.js

@@ -0,0 +1,38 @@
+/**
+ * Blocking ALLOW-LIST — P3' (2026-04-27)
+ *
+ * 사용자 작업을 차단(block)할 권한을 가진 hook 의 명시적 화이트리스트.
+ * 목록 외 hook 의 부정적 판정은 "관찰 신호"(log only) 로만 처리되어야 한다.
+ *
+ * RC5 (retro-v040): 분산된 detector 가 각자 block 결정을 내리면서 false-positive
+ * 가 메인 로직 흐름까지 차단하는 회귀 패턴 발생. ALLOW-LIST 명시화로 차단 권한
+ * 의 source-of-truth 를 단일화.
+ *
+ * v0.4.2 정책:
+ *   - 본 모듈은 ALLOW-LIST 정의 + 검증 helper. 기존 deny() 직접 호출 hook 들은
+ *     v0.4.2 에서 denyOrObserve(name, reason) 로 마이그레이션 완료.
+ *   - 신규 hook 추가 시 차단 권한이 필요하면 본 ALLOW-LIST 에 추가 + 본 파일의
+ *     사유 문서화 의무. 본 commit diff 가 review 필수 항목.
+ *
+ * 멤버 사유:
+ *   - stop-guard: Stop hook — false-completion 메타 가드 (자가 검증 강제)
+ *   - pre-tool-use: Bash dangerous-pattern + 수동 confirm 가드
+ *   - secret-filter: Write/Edit 결과의 .env / API key 노출 차단
+ *   - db-guard: Bash 의 destructive DB 명령 (DROP/TRUNCATE/DELETE) 차단
+ *   - rate-limiter: 사용자 작업 빈도 임계 초과 시 cool-down 차단 (resource abuse 방어)
+ */
+export const BLOCKING_ALLOWLIST = new Set([
+    'stop-guard',
+    'pre-tool-use',
+    'secret-filter',
+    'db-guard',
+    'rate-limiter',
+]);
+/** hook 이 block 결정을 출력할 권한이 있는지. */
+export function canBlock(hookName) {
+    return BLOCKING_ALLOWLIST.has(hookName);
+}
+/** ALLOW-LIST 에 추가하려는 hook 이 정책 문서화를 요구하는지 (lint helper). */
+export function requiresPolicyDoc(hookName) {
+    return !BLOCKING_ALLOWLIST.has(hookName);
+}

package/dist/hooks/shared/command-parser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Command-token parser — quote-aware shell command preprocessing.
+ *
+ * 목적: PreToolUse enforce_via 룰의 정규식이 quote된 인자 텍스트와
+ * 명령 토큰을 구분 못 해서 false positive block 발생 (TEST-6, RC5).
+ *
+ * 사례: forgen compound --solution "title" "본문에 rm -rf 텍스트 포함" 명령이
+ * "rm\s+-rf" 패턴에 매칭되어 차단됨. 실제 rm 명령이 아닌데도.
+ *
+ * 해법: quote된 문자열을 마스킹한 뒤 패턴 매칭. 99% 케이스 커버.
+ * 완벽한 shell 파싱은 아니지만 정직하게 한정된 범위.
+ */
+/**
+ * Mask quoted string contents in a shell command so that text inside
+ * single/double quotes, backticks, or $(...) is not matched by patterns
+ * intended for command tokens.
+ *
+ * Examples:
+ *   maskQuotedContent('rm -rf /')                                → 'rm -rf /'
+ *   maskQuotedContent('echo "rm -rf foo"')                       → 'echo ""'
+ *   maskQuotedContent("forgen save 'rm -rf body'")               → "forgen save ''"
+ *   maskQuotedContent('rm -rf $(pwd)')                           → 'rm -rf $()'
+ *   maskQuotedContent('echo `rm -rf x`')                         → 'echo ``'
+ *
+ * Limitations (documented, not silently broken):
+ *   - escaped quotes inside quoted strings: best-effort only
+ *   - heredoc bodies (<<EOF ... EOF): masked as `<<HEREDOC>>` (v0.4.1+)
+ *   - nested $(...) / `...`: outer level masked
+ */
+export declare function maskQuotedContent(cmd: string): string;
+/**
+ * Decide if a verifier should match against the raw command, masked command,
+ * or the leading command tokens of each statement.
+ *
+ * 'raw'             — backward compat. Match against the unmodified command string.
+ * 'masked'          — Strip quoted contents first. Use this when the rule wants to
+ *                     guard a real command invocation (e.g. rm -rf) and not text
+ *                     inside string literals passed as arguments to other commands.
+ * 'command_tokens'  — Reserved for future use (per-statement leading-token check).
+ *                     Currently behaves like 'masked' to avoid silently breaking
+ *                     when rule files use it.
+ */
+export type MatchTarget = 'raw' | 'masked' | 'command_tokens';
+export declare function preprocessForMatch(cmd: string, target: MatchTarget | undefined): string;

package/dist/hooks/shared/command-parser.js

@@ -0,0 +1,50 @@
+/**
+ * Command-token parser — quote-aware shell command preprocessing.
+ *
+ * 목적: PreToolUse enforce_via 룰의 정규식이 quote된 인자 텍스트와
+ * 명령 토큰을 구분 못 해서 false positive block 발생 (TEST-6, RC5).
+ *
+ * 사례: forgen compound --solution "title" "본문에 rm -rf 텍스트 포함" 명령이
+ * "rm\s+-rf" 패턴에 매칭되어 차단됨. 실제 rm 명령이 아닌데도.
+ *
+ * 해법: quote된 문자열을 마스킹한 뒤 패턴 매칭. 99% 케이스 커버.
+ * 완벽한 shell 파싱은 아니지만 정직하게 한정된 범위.
+ */
+/**
+ * Mask quoted string contents in a shell command so that text inside
+ * single/double quotes, backticks, or $(...) is not matched by patterns
+ * intended for command tokens.
+ *
+ * Examples:
+ *   maskQuotedContent('rm -rf /')                                → 'rm -rf /'
+ *   maskQuotedContent('echo "rm -rf foo"')                       → 'echo ""'
+ *   maskQuotedContent("forgen save 'rm -rf body'")               → "forgen save ''"
+ *   maskQuotedContent('rm -rf $(pwd)')                           → 'rm -rf $()'
+ *   maskQuotedContent('echo `rm -rf x`')                         → 'echo ``'
+ *
+ * Limitations (documented, not silently broken):
+ *   - escaped quotes inside quoted strings: best-effort only
+ *   - heredoc bodies (<<EOF ... EOF): masked as `<<HEREDOC>>` (v0.4.1+)
+ *   - nested $(...) / `...`: outer level masked
+ */
+export function maskQuotedContent(cmd) {
+    if (!cmd)
+        return cmd;
+    let out = cmd;
+    // v0.4.1 (2026-04-24) — heredoc body 마스킹 추가. 이전엔 `cat > f <<EOF\n rm -rf /tmp \nEOF`
+    // 처럼 heredoc 본문이 command string 에 포함돼 false-positive block 발생.
+    // 지원 형식: <<EOF / <<'EOF' / <<"EOF" / <<-EOF (indent 무시 변종).
+    // <<-MARK 은 indent 허용 (terminator 앞 whitespace). `\n\s*\2` 로 반영.
+    out = out.replace(/<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?\n\s*\2\b/g, '<<HEREDOC>>');
+    // Order matters: command substitution before plain quotes (they may contain quotes themselves).
+    out = out.replace(/\$\([^)]*\)/g, '$()');
+    out = out.replace(/`[^`]*`/g, '``');
+    out = out.replace(/'[^']*'/g, "''");
+    out = out.replace(/"[^"]*"/g, '""');
+    return out;
+}
+export function preprocessForMatch(cmd, target) {
+    if (!target || target === 'raw')
+        return cmd;
+    return maskQuotedContent(cmd);
+}

package/dist/hooks/shared/forge-loop-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Forge Loop State — RC6 가드 (US-M1)
+ *
+ * 직전 forge-loop 의 findings 또는 진행 중 stories 를 ≤1KB 요약으로 렌더한다.
+ * SessionStart 와 UserPromptSubmit 두 hook 이 공유하는 단일 진입점.
+ *
+ * RC6 자기증거: 본 세션 R1 에서 head -80 으로 forge-loop.json 을 읽어 findings
+ * 8줄(line 92~99)이 잘렸음. 결과적으로 직전 결론을 컨텍스트에 못 가져 같은
+ * 가설을 재발. 이 모듈은 그 회귀를 시스템 레벨에서 차단한다.
+ */
+interface ForgeLoopStory {
+    id: string;
+    title: string;
+    passes?: boolean;
+}
+export interface ForgeLoopState {
+    active?: boolean;
+    task?: string;
+    startedAt?: string;
+    completedAt?: string;
+    stories?: ForgeLoopStory[];
+    findings?: Record<string, string>;
+}
+export declare function readForgeLoopState(filePath?: string): ForgeLoopState | null;
+/** SessionStart 용 — 완료된 forge-loop 의 findings 또는 진행 중 stories 요약. */
+export declare function renderForgeLoopForSession(state: ForgeLoopState | null, now?: number): string | null;
+/** UserPromptSubmit 용 — active=true 시에만 짧은 진행 상황 1~2줄. */
+export declare function renderForgeLoopForPrompt(state: ForgeLoopState | null, now?: number): string | null;
+/** 테스트 노출용 상수 — 회귀 시 임계값 변경 즉시 감지. */
+export declare const FORGE_LOOP_LIMITS: {
+    readonly SOFT_STALE_MS: number;
+    readonly HARD_STALE_MS: number;
+    readonly MAX_INJECT_BYTES: 1024;
+    readonly MAX_PENDING: 5;
+};
+export {};