@wooojin/forgen 0.3.2 → 0.4.1

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`);
@@ -125,6 +118,15 @@ async function main() {
         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 +154,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 +175,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 +202,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 +218,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(),
@@ -237,6 +243,80 @@ async function main() {
         catch (e) {
             log.debug('compound negative check 실패', e);
         }
+        // 6a+b. ADR-001 Mech-A PostToolUse + T3 bypass — single rule load, 두 dispatcher 공유.
+        // R2-P perf: 이전에는 6a, 6b 각각 loadActiveRules() 재호출 → file read 2배.
+        if (toolName === 'Write' || toolName === 'Edit' || toolName === 'Bash') {
+            const target = (() => {
+                const c = toolInput.content;
+                if (typeof c === 'string')
+                    return c;
+                const ns = toolInput.new_string;
+                if (typeof ns === 'string')
+                    return ns;
+                const cmd = toolInput.command;
+                if (typeof cmd === 'string')
+                    return cmd;
+                return '';
+            })() || toolResponse;
+            if (target) {
+                try {
+                    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 — 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')
+                                continue;
+                            const v = spec.verifier;
+                            if (!v || v.kind !== 'pattern_match')
+                                continue;
+                            const pattern = String(v.params?.pattern ?? '');
+                            if (!pattern)
+                                continue;
+                            const re = compileSafeRegex(pattern);
+                            if (!re.regex) {
+                                log.debug(`rule ${rule.rule_id} unsafe regex: ${re.reason}`);
+                                continue;
+                            }
+                            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,
+                                source: 'post-tool-guard',
+                                kind: 'block',
+                                message_preview: target.slice(0, 120),
+                            });
+                            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 — 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 });
+                    }
+                }
+                catch (e) {
+                    log.debug('enforce_via/bypass post-tool dispatch 실패', e);
+                }
+            }
+        }
         // 7. Compound success hint (non-blocking)
         try {
             const successHint = getCompoundSuccessHint(toolName, toolResponse, sessionId);
@@ -260,5 +340,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

@@ -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

@@ -22,6 +22,7 @@ import { isHookEnabled } from './hook-config.js';
 import { approve, approveWithWarning, deny, 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) };
         }
     }
@@ -311,7 +322,70 @@ async function main() {
         const toolName = data.tool_name ?? data.toolName ?? '';
         const toolInput = data.tool_input ?? data.toolInput ?? {};
         const sessionId = data.session_id ?? 'default';
-        // Bash 도구: 위험 명령어 감지
+        // ADR-001 Mech-A PreToolUse dispatcher — 사용자가 정의한 rule 이 빌트인 위험-명령 감지보다 먼저.
+        // 이렇게 해야 rule.block_message (맥락 있는 안내) 가 제네릭 "Dangerous command blocked" 대신 노출됨.
+        // fail-open: 예외는 hook 차단 안 함.
+        try {
+            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'
+                ? String(toolInput.command)
+                : '';
+            for (const rule of rules) {
+                for (const spec of rule.enforce_via ?? []) {
+                    if (spec.hook !== 'PreToolUse' || spec.mech !== 'A')
+                        continue;
+                    const v = spec.verifier;
+                    if (!v || v.kind !== 'tool_arg_regex')
+                        continue;
+                    const pattern = String(v.params?.pattern ?? '');
+                    if (!pattern)
+                        continue;
+                    const re = compileSafeRegex(pattern, 'i');
+                    if (!re.regex) {
+                        log.debug(`rule ${rule.rule_id} unsafe regex: ${re.reason}`);
+                        continue;
+                    }
+                    // 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';
+                    if (requiresFlag && !confirmed) {
+                        recordViolation({ rule_id: rule.rule_id, session_id: sessionId, source: 'pre-tool-guard', kind: 'deny', message_preview: command.slice(0, 120) });
+                        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));
+                        return;
+                    }
+                    if (requiresFlag && confirmed) {
+                        // H3: 우회 감사 — FORGEN_USER_CONFIRMED 으로 Mech-A 를 우회할 때마다 violation 로그에
+                        // kind='correction' 으로 기록. T3 bypass 누적 대신 별도 채널로 운영자가 monitoring 가능.
+                        recordViolation({
+                            rule_id: rule.rule_id, session_id: sessionId,
+                            source: 'pre-tool-guard',
+                            kind: 'correction', // 'correction' = 사용자 명시 우회, rule 위반이지만 의도된 것
+                            message_preview: `[FORGEN_USER_CONFIRMED=1 bypass] ${command.slice(0, 120)}`,
+                        });
+                    }
+                }
+            }
+        }
+        catch (e) {
+            log.debug('enforce_via[PreToolUse] dispatch 실패', e);
+        }
+        // Bash 도구: 위험 명령어 감지 (빌트인 safety net)
         const check = checkDangerousCommand(toolName, toolInput);
         if (check.action === 'block') {
             console.log(deny(`[Forgen] Dangerous command blocked: ${check.description}\nCommand: ${check.command}`));
@@ -357,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

@@ -82,5 +82,5 @@ async function main() {
 }
 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.d.ts

@@ -10,5 +10,15 @@ export interface SecretPattern {
     pattern: RegExp;
 }
 export declare const SECRET_PATTERNS: SecretPattern[];
+/**
+ * 텍스트에서 민감 정보 패턴을 찾아 `[REDACTED:<NAME>]` 로 치환 (순수 함수).
+ *
+ * R5-G2: auto-compound-runner 가 사용자 transcript 를 Claude (Haiku) 로 송신하기 전
+ * 적용. `detectSecrets` 는 감지만, 이 함수는 실제 문자열에서 대체.
+ */
+export declare function redactSecrets(text: string): {
+    redacted: string;
+    hits: SecretPattern[];
+};
 /** 텍스트에서 민감 정보 패턴 감지 (순수 함수) */
 export declare function detectSecrets(text: string): SecretPattern[];

package/dist/hooks/secret-filter.js

@@ -23,6 +23,26 @@ export const SECRET_PATTERNS = [
     { name: 'Google API Key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/ },
     { name: 'Slack Token', pattern: /\bxox[abpors]-[A-Za-z0-9-]{10,}/ },
 ];
+/**
+ * 텍스트에서 민감 정보 패턴을 찾아 `[REDACTED:<NAME>]` 로 치환 (순수 함수).
+ *
+ * R5-G2: auto-compound-runner 가 사용자 transcript 를 Claude (Haiku) 로 송신하기 전
+ * 적용. `detectSecrets` 는 감지만, 이 함수는 실제 문자열에서 대체.
+ */
+export function redactSecrets(text) {
+    const hits = [];
+    let out = text;
+    for (const sp of SECRET_PATTERNS) {
+        // regex 복제 (global flag 없이 repeated test 되는 경우 lastIndex 안전)
+        const re = new RegExp(sp.pattern.source, (sp.pattern.flags.includes('g') ? sp.pattern.flags : sp.pattern.flags + 'g'));
+        if (re.test(out)) {
+            hits.push(sp);
+            const re2 = new RegExp(sp.pattern.source, (sp.pattern.flags.includes('g') ? sp.pattern.flags : sp.pattern.flags + 'g'));
+            out = out.replace(re2, `[REDACTED:${sp.name}]`);
+        }
+    }
+    return { redacted: out, hits };
+}
 /** 텍스트에서 민감 정보 패턴 감지 (순수 함수) */
 export function detectSecrets(text) {
     const found = [];
@@ -67,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

@@ -429,6 +429,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/atomic-write.d.ts

@@ -37,5 +37,12 @@ export declare function atomicWriteText(filePath: string, content: string, optio
     mode?: number;
     dirMode?: number;
 }): void;
-/** JSON 파일을 안전하게 읽기 (파싱 실패 시 fallback 반환) */
+/**
+ * JSON 파일을 안전하게 읽기 (파싱 실패 시 fallback 반환).
+ *
+ * R4-B3 (2026-04-22): UTF-8 BOM () prefix 제거 — Windows 메모장 등으로 저장된
+ *   rule/settings JSON 이 BOM 으로 시작해 JSON.parse 가 silent 실패하던 문제.
+ * R4-SKIP: FORGEN_DEBUG_SIGNALS=1 일 때 파싱 실패를 stderr 로 노출 — silent
+ *   누락을 운영자가 추적 가능하도록.
+ */
 export declare function safeReadJSON<T>(filePath: string, fallback: T): T;

package/dist/hooks/shared/atomic-write.js

@@ -136,13 +136,27 @@ export function atomicWriteText(filePath, content, options) {
         throw e;
     }
 }
-/** JSON 파일을 안전하게 읽기 (파싱 실패 시 fallback 반환) */
+/**
+ * JSON 파일을 안전하게 읽기 (파싱 실패 시 fallback 반환).
+ *
+ * R4-B3 (2026-04-22): UTF-8 BOM () prefix 제거 — Windows 메모장 등으로 저장된
+ *   rule/settings JSON 이 BOM 으로 시작해 JSON.parse 가 silent 실패하던 문제.
+ * R4-SKIP: FORGEN_DEBUG_SIGNALS=1 일 때 파싱 실패를 stderr 로 노출 — silent
+ *   누락을 운영자가 추적 가능하도록.
+ */
 export function safeReadJSON(filePath, fallback) {
     try {
         if (fs.existsSync(filePath)) {
-            return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            let raw = fs.readFileSync(filePath, 'utf-8');
+            if (raw.charCodeAt(0) === 0xFEFF)
+                raw = raw.slice(1); // strip BOM
+            return JSON.parse(raw);
+        }
+    }
+    catch (e) {
+        if (process.env.FORGEN_DEBUG_SIGNALS === '1') {
+            process.stderr.write(`[forgen:safeReadJSON] ${filePath} parse failed: ${e.message}\n`);
         }
     }
-    catch { /* JSON parse failure — return fallback */ }
     return fallback;
 }

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/hook-response.d.ts

@@ -18,8 +18,13 @@ export declare function approve(): string;
 /**
  * 통과 + 모델에 컨텍스트 주입.
  * UserPromptSubmit, SessionStart 이벤트에서만 모델에 도달함.
+ *
+ * H1 (v0.4.1): optional `userNotice` 로 사용자 UI (systemMessage) 에도 동시
+ * 1줄 노출. additionalContext 는 모델 전용이라 기존 recall hit 이 8,000+ 번
+ * 주입되었는데도 사용자는 0 건을 봤음. userNotice 로 같은 hit 을 사용자
+ * 에게 가시화한다.
  */
-export declare function approveWithContext(context: string, eventName: string): string;
+export declare function approveWithContext(context: string, eventName: string, userNotice?: string): string;
 /**
  * 통과 + UI 경고 표시 (모델에는 전달되지 않음).
  * PostToolUse, PreToolUse 경고 등 모델 도달이 불필요한 경우 사용.
@@ -29,10 +34,26 @@ export declare function approveWithWarning(warning: string): string;
 export declare function deny(reason: string): string;
 /** 사용자 확인 요청 (PreToolUse 전용) */
 export declare function ask(reason: string): string;
+/**
+ * Stop hook only — block the agent from stopping and feed a self-check
+ * question back to Claude so the current session resumes with new guidance.
+ *
+ * `reason` becomes the next-turn content (Claude reads this verbatim), while
+ * `systemMessage` is auxiliary context rendered alongside. Put the whole
+ * self-check question in `reason`; keep `systemMessage` to a short rule tag.
+ *
+ * Source: Stop hook spec — `decision: "block"` "prevents stopping and continues the agent's work".
+ */
+export declare function blockStop(reason: string, systemMessage?: string): string;
 /**
  * fail-open with error tracking: 에러 시 안전하게 통과하되, 실패 정보를 기록.
  * forgen doctor의 Hook Health 섹션에서 실패 이력을 표시할 수 있도록 JSONL 로그에 기록.
  *
+ * v0.4.1 (2026-04-24): optional `err` 매개변수 추가. 실 데이터상 106건의 hook 에러가
+ * 누적됐으나 전부 `{hook,at}` 만이라 근원 조사 불가했다. 이제 `error`/`stack` 을
+ * 함께 기록해 `forgen doctor` 가 원인 카테고리별로 빈도 surface 가능.
+ * payload 는 한 줄 cap(400자)로 잘라 JSONL 크기 폭주 방지.
+ *
  * @fail-open: hook failure must never block the user's workflow
  */
-export declare function failOpenWithTracking(hookName: string): string;
+export declare function failOpenWithTracking(hookName: string, err?: unknown): string;

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

@@ -23,11 +23,17 @@ export function approve() {
 /**
  * 통과 + 모델에 컨텍스트 주입.
  * UserPromptSubmit, SessionStart 이벤트에서만 모델에 도달함.
+ *
+ * H1 (v0.4.1): optional `userNotice` 로 사용자 UI (systemMessage) 에도 동시
+ * 1줄 노출. additionalContext 는 모델 전용이라 기존 recall hit 이 8,000+ 번
+ * 주입되었는데도 사용자는 0 건을 봤음. userNotice 로 같은 hit 을 사용자
+ * 에게 가시화한다.
  */
-export function approveWithContext(context, eventName) {
+export function approveWithContext(context, eventName, userNotice) {
     return JSON.stringify({
         continue: true,
         hookSpecificOutput: { hookEventName: eventName, additionalContext: context },
+        ...(userNotice ? { systemMessage: userNotice } : {}),
     });
 }
 /**
@@ -59,17 +65,56 @@ export function ask(reason) {
         },
     });
 }
+/**
+ * Stop hook only — block the agent from stopping and feed a self-check
+ * question back to Claude so the current session resumes with new guidance.
+ *
+ * `reason` becomes the next-turn content (Claude reads this verbatim), while
+ * `systemMessage` is auxiliary context rendered alongside. Put the whole
+ * self-check question in `reason`; keep `systemMessage` to a short rule tag.
+ *
+ * Source: Stop hook spec — `decision: "block"` "prevents stopping and continues the agent's work".
+ */
+export function blockStop(reason, systemMessage) {
+    return JSON.stringify({
+        continue: true,
+        decision: 'block',
+        reason,
+        ...(systemMessage ? { systemMessage } : {}),
+    });
+}
 /**
  * fail-open with error tracking: 에러 시 안전하게 통과하되, 실패 정보를 기록.
  * forgen doctor의 Hook Health 섹션에서 실패 이력을 표시할 수 있도록 JSONL 로그에 기록.
  *
+ * v0.4.1 (2026-04-24): optional `err` 매개변수 추가. 실 데이터상 106건의 hook 에러가
+ * 누적됐으나 전부 `{hook,at}` 만이라 근원 조사 불가했다. 이제 `error`/`stack` 을
+ * 함께 기록해 `forgen doctor` 가 원인 카테고리별로 빈도 surface 가능.
+ * payload 는 한 줄 cap(400자)로 잘라 JSONL 크기 폭주 방지.
+ *
  * @fail-open: hook failure must never block the user's workflow
  */
-export function failOpenWithTracking(hookName) {
+export function failOpenWithTracking(hookName, err) {
     try {
         fs.mkdirSync(STATE_DIR, { recursive: true });
         const logPath = path.join(STATE_DIR, 'hook-errors.jsonl');
-        const entry = JSON.stringify({ hook: hookName, at: Date.now() });
+        const payload = { hook: hookName, at: Date.now() };
+        if (err !== undefined && err !== null) {
+            if (err instanceof Error) {
+                payload.error = err.message.slice(0, 400);
+                if (err.stack) {
+                    // 스택 첫 3줄만 — 어느 파일/라인에서 throw 됐는지만 알면 충분.
+                    payload.stack = err.stack.split('\n').slice(0, 3).join(' | ').slice(0, 400);
+                }
+                const maybeCode = err.code;
+                if (typeof maybeCode === 'string')
+                    payload.code = maybeCode;
+            }
+            else {
+                payload.error = String(err).slice(0, 400);
+            }
+        }
+        const entry = JSON.stringify(payload);
         fs.appendFileSync(logPath, entry + '\n');
     }
     catch { /* fail-open: tracking itself must not throw */ }