@su-record/vibe 2.12.5 → 2.14.0

package/hooks/scripts/post-edit-dispatcher.js

@@ -1,27 +1,100 @@
 #!/usr/bin/env node
 /**
- * PostToolUse dispatcher — Write/Edit 이후 순차 실행.
+ * PostToolUse dispatcher — Write/Edit 이후 후처리.
  *
- * 기존: PostToolUse.Write|Edit 배열에 3개 스크립트가 병렬 spawn (프로세스 피크 3배)
- *       + PostToolUse.Edit 추가로 post-edit.js 1개 더
- * 현재: 단일 디스패처에서 순차 실행. config.hooks.{name}.enabled로 개별 토글.
+ * in-process 평탄화 (2026-06): 자식 node spawn 없이 import 실행.
+ * 실작업(prettier/vitest 등)은 각 step이 자체 timeout을 가진 비동기 자식으로
+ * 실행하므로 step 간 병렬성(Promise.all)은 spawn 시절과 동일하게 유지된다.
  *
- * 실행 순서:
- *   1. auto-format — 코드 스타일 정규화
- *   2. code-check — 린트/품질 검사
- *   3. auto-test — 관련 테스트 실행
- *   4. post-edit — Edit 전용 후처리 (Write에서는 스크립트 내부에서 스킵)
+ * 실행 step (모두 비차단, config.hooks.{name}.enabled로 개별 토글):
+ *   auto-format — 코드 스타일 정규화 (변경 시 finding 반환)
+ *   code-check  — 린트/품질 검사 + P1 이슈 verifyRequired 기록
+ *   auto-test   — 관련 테스트 실행 (debounce 지원)
+ *   post-edit   — console.log 감지
  *
- * 실패 격리: 한 스크립트 실패해도 다음은 계속 진행.
+ * 출력 계약 (Claude Code PostToolUse):
+ *   findings 있음 → stdout에 JSON hookSpecificOutput 1개 출력, exit 0
+ *   findings 없음 → stdout 없음, exit 0
+ *   절대 exit 2 없음 — 차단은 downstream 게이트에서 (SPEC 설계 원칙)
+ *
+ * Codex 경로: codex-hook-adapter.js가 이 스크립트를 spawn하고
+ *   combinedOutput(stdout+stderr)을 writeAdditionalContext로 래핑함.
+ *   → stdout이 JSON hookSpecificOutput이면 어댑터가 이중 래핑함.
+ *   → 어댑터에서 JSON hookSpecificOutput 형식 감지 후 bypass 처리.
+ *
+ * 실패 격리: step별 try/catch — 한 step이 throw해도 나머지는 계속 진행.
  */
-import { dispatch } from './lib/dispatcher.js';
-
-try {
-  await dispatch([
-    { name: 'auto-format', script: 'auto-format.js' },
-    { name: 'code-check',  script: 'code-check.js'  },
-    { name: 'auto-test',   script: 'auto-test.js'   },
-    { name: 'post-edit',   script: 'post-edit.js'   },
-  ]);
-} catch { /* noise suppression */ }
+import { readStdinSync, buildCtx } from './lib/hook-context.js';
+import { readProjectConfig } from './utils.js';
+import fs from 'fs';
+import path from 'path';
+
+// ─── step 임포트 ─────────────────────────────────────────────────────
+import { run as autoFormat } from './auto-format.js';
+import { run as codeCheck } from './code-check.js';
+import { run as autoTest } from './auto-test.js';
+import { run as postEdit } from './post-edit.js';
+
+// ─── 설정 로딩 ────────────────────────────────────────────────────────
+function loadHookConfig() {
+  try {
+    return readProjectConfig()?.hooks || {};
+  } catch {
+    return {};
+  }
+}
+
+function isEnabled(hookConfig, name) {
+  const entry = hookConfig[name];
+  if (entry && typeof entry === 'object' && entry.enabled === false) return false;
+  return true;
+}
+
+// ─── 메인 ─────────────────────────────────────────────────────────────
+const { raw, parsed } = readStdinSync();
+const ctx = buildCtx({ rawInput: raw, payload: parsed });
+const hookConfig = loadHookConfig();
+
+const steps = [
+  { name: 'auto-format', run: autoFormat },
+  { name: 'code-check',  run: codeCheck  },
+  { name: 'auto-test',   run: autoTest   },
+  { name: 'post-edit',   run: postEdit   },
+];
+
+const enabledSteps = steps.filter(s => isEnabled(hookConfig, s.name));
+
+// 모든 step을 병렬 실행해 findings 수집
+const results = await Promise.all(
+  enabledSteps.map(async (step) => {
+    try {
+      const result = await step.run(ctx);
+      // findings 배열을 반환하는 새 구조 지원 + 구형 숫자 반환 폴백
+      if (result && typeof result === 'object' && Array.isArray(result.findings)) {
+        return result.findings;
+      }
+      return [];
+    } catch {
+      // 크래시 격리 — 해당 step만 건너뜀
+      return [];
+    }
+  })
+);
+
+const allFindings = results.flat().filter(f => typeof f === 'string' && f.trim().length > 0);
+
+// findings가 있을 때만 stdout 출력
+// Claude Code: JSON hookSpecificOutput → 모델이 additionalContext로 인식
+// findings 없음: 조용히 종료
+if (allFindings.length > 0) {
+  const summary = allFindings.join('\n');
+  const output = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext: summary,
+    },
+  });
+  process.stdout.write(output + '\n');
+}
+
 process.exit(0);

package/hooks/scripts/post-edit.js

@@ -3,33 +3,54 @@
  *
  * NOTE: tsc, prettier 제거 — 빌드/커밋 시점에 실행하므로 Edit마다 불필요
  * grep spawn 대신 fs.readFileSync + regex로 프로세스 오버헤드 제거
+ *
+ * findings를 console.log가 아닌 반환값으로 전달.
+ * (console.log 출력은 CC PostToolUse에서 transcript-only — 모델이 보지 못함)
  */
 import { existsSync, readFileSync } from 'fs';
 import path from 'path';
+import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
 
-process.on('uncaughtException', () => {});
-process.on('unhandledRejection', () => {});
-
-const CONSOLE_LOG_RE = /console\.log/;
+const CONSOLE_LOG_RE = /console\.log\(/;
 const CODE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
 
-try {
-  const input = JSON.parse(process.env.TOOL_INPUT || '{}');
-  const filePath = input.file_path || input.path || '';
+/**
+ * in-process 진입점 — console.log 감지만 수행.
+ * findings 배열 반환 (디스패처가 수집해 additionalContext에 주입).
+ * @param {{ toolInput: string }} ctx
+ * @returns {Promise<{ exitCode: number, findings: string[] }>}
+ */
+export async function run(ctx) {
+  const findings = [];
+  try {
+    const input = JSON.parse(ctx.toolInput || '{}');
+    const filePath = input.file_path || input.path || '';
 
-  if (filePath && CODE_EXT_RE.test(filePath)) {
-    const resolved = path.resolve(filePath);
-    if (existsSync(resolved)) {
-      const lines = readFileSync(resolved, 'utf-8').split('\n');
-      const hits = [];
-      for (let i = 0; i < lines.length && hits.length < 3; i++) {
-        if (CONSOLE_LOG_RE.test(lines[i])) hits.push(i + 1);
-      }
-      if (hits.length > 0) {
-        console.log(`[POST-EDIT] ${path.basename(resolved)}: console.log at line ${hits.join(',')}`);
+    if (filePath && CODE_EXT_RE.test(filePath)) {
+      const resolved = path.resolve(filePath);
+      if (existsSync(resolved)) {
+        const lines = readFileSync(resolved, 'utf-8').split('\n');
+        const hits = [];
+        for (let i = 0; i < lines.length && hits.length < 3; i++) {
+          if (CONSOLE_LOG_RE.test(lines[i])) hits.push(i + 1);
+        }
+        if (hits.length > 0) {
+          findings.push(`[POST-EDIT] ${path.basename(resolved)}: console.log at line ${hits.join(',')}`);
+        }
       }
     }
+  } catch {
+    // 조용히 실패
   }
-} catch {
-  // 조용히 실패
+  return { exitCode: 0, findings };
+}
+
+// standalone CLI 모드 — 전역 예외 흡수는 단독 프로세스일 때만 등록
+// (in-process import 시 디스패처의 전역 핸들러를 오염시키지 않도록)
+if (isDirectRun(import.meta.url)) {
+  process.on('uncaughtException', () => {});
+  process.on('unhandledRejection', () => {});
+  const { exitCode, findings } = await run(buildCliCtx());
+  if (findings.length > 0) process.stdout.write(findings.join('\n') + '\n');
+  process.exit(exitCode);
 }

package/hooks/scripts/pr-test-gate.js

@@ -4,49 +4,20 @@
  * mcp__github__create_pull_request 호출 시 테스트가 통과해야만 PR 생성 허용.
  * exit 2 = 차단, exit 0 = 통과
  */
-import { execSync } from 'child_process';
 import { PROJECT_DIR } from './utils.js';
-import { existsSync, readFileSync } from 'fs';
-import path from 'path';
+import { runPrTestGate } from './lib/pr-gate-runner.js';
 
-function detectTestCommand() {
-  const pkgPath = path.join(PROJECT_DIR, 'package.json');
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-      if (pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1') {
-        return 'npm test';
-      }
-    } catch { /* ignore */ }
-  }
-  // Python
-  if (existsSync(path.join(PROJECT_DIR, 'pytest.ini')) || existsSync(path.join(PROJECT_DIR, 'pyproject.toml'))) {
-    return 'python -m pytest --tb=short -q';
-  }
-  // Go
-  if (existsSync(path.join(PROJECT_DIR, 'go.mod'))) {
-    return 'go test ./...';
-  }
-  return null;
-}
+const { passed, testCmd, output } = runPrTestGate(PROJECT_DIR);
 
-try {
-  const testCmd = detectTestCommand();
-  if (!testCmd) {
-    // No test command detected — allow PR
-    process.exit(0);
-  }
+if (!testCmd) {
+  // 테스트 커맨드 없음 → PR 허용
+  process.exit(0);
+}
 
-  console.log(`[PR-GATE] Running tests before PR creation: ${testCmd}`);
-  execSync(testCmd, {
-    cwd: PROJECT_DIR,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    timeout: 120000,
-  });
+if (passed) {
   console.log('[PR-GATE] Tests passed — PR creation allowed');
   process.exit(0);
-} catch (err) {
-  const output = err.stdout ? err.stdout.toString().split('\n').slice(-5).join('\n') : '';
+} else {
   console.log(`[PR-GATE] Tests failed — PR creation blocked\n${output}`);
   process.exit(2);
 }

package/hooks/scripts/pre-tool-dispatcher.js

@@ -2,43 +2,45 @@
 /**
  * PreToolUse dispatcher — Bash/Edit/Write 공용.
  *
- * 기존: matcher별로 2~3개 스크립트가 병렬 spawn.
- *       - Bash: sentinel-guard + pre-tool-guard + command-log
- *       - Edit: sentinel-guard + pre-tool-guard
- *       - Write: sentinel-guard + pre-tool-guard
- * 현재: 단일 디스패처가 tool name을 인자로 받아 순차 실행.
+ * in-process 평탄화 (2026-06): 가드를 자식 node로 spawn하지 않고 import해서
+ * 같은 프로세스에서 실행한다. 자식 VM 기동(~20ms × N)과 stdin 재읽기 제거.
+ * daemon/IPC는 금지 (CLAUDE.md Gotchas) — 디스패처 프로세스 자체는 유지.
  *
  * Deny 시맨틱 보존:
- *   sentinel-guard / pre-tool-guard가 exit 2(deny)를 반환하면 dispatcher도
- *   즉시 exit 2로 상위에 전파 → Claude Code가 도구 실행을 차단.
+ *   sentinel-guard / pre-tool-guard / scope-guard의 run(ctx)이 2를 반환하면
+ *   dispatchInProcess가 process.exit(2)로 상위에 전파 → Claude Code가 도구 실행 차단.
  *
  * 사용법: node pre-tool-dispatcher.js <Bash|Edit|Write>
  */
-import { dispatch } from './lib/dispatcher.js';
+import { dispatchInProcess } from './lib/dispatcher.js';
+import { run as sentinelGuard } from './sentinel-guard.js';
+import { run as preToolGuard } from './pre-tool-guard.js';
+import { run as scopeGuard } from './scope-guard.js';
+import { run as commandLog } from './command-log.js';
 
 const toolName = process.argv[2] || '';
 
 const steps = [
-  { name: 'sentinel-guard', script: 'sentinel-guard.js', args: [toolName], denyOnExit2: true },
-  { name: 'pre-tool-guard', script: 'pre-tool-guard.js', args: [toolName], denyOnExit2: true },
+  { name: 'sentinel-guard', run: sentinelGuard, denyOnExit2: true },
+  { name: 'pre-tool-guard', run: preToolGuard, denyOnExit2: true },
 ];
 
-// scope-guard는 Edit/Write에만 의미 있음 — 불필요한 spawn 회피
+// scope-guard는 Edit/Write에만 의미 있음
 if (toolName === 'Edit' || toolName === 'Write') {
-  steps.push({ name: 'scope-guard', script: 'scope-guard.js', args: [toolName], denyOnExit2: true });
+  steps.push({ name: 'scope-guard', run: scopeGuard, denyOnExit2: true });
 }
 
 // command-log은 Bash 전용
 if (toolName === 'Bash') {
-  steps.push({ name: 'command-log', script: 'command-log.js' });
+  steps.push({ name: 'command-log', run: commandLog });
 }
 
 // 하네스에 노이즈를 주지 않도록 디스패처 자체의 예외는 모두 흡수.
-// exit 2 (deny 전파)는 dispatch() 내부에서 process.exit(2)로 처리되므로
+// exit 2 (deny 전파)는 dispatchInProcess 내부에서 process.exit(2)로 처리되므로
 // 여기까지 오면 "deny 아님" → 항상 exit 0.
 try {
-  await dispatch(steps);
+  await dispatchInProcess(steps, { argvToolName: toolName });
 } catch {
-  // ignore — 하위 스크립트 크래시가 상위 훅 실패로 표시되지 않도록
+  // ignore — step 크래시가 상위 훅 실패로 표시되지 않도록
 }
 process.exit(0);

package/hooks/scripts/pre-tool-guard.js

@@ -4,8 +4,6 @@
  * 위험한 도구 사용 전 검증 및 경고
  */
 
-import { VIBE_PATH, PROJECT_DIR } from './utils.js';
-
 // 위험한 명령어 패턴
 //
 // 각 엔트리의 `target`은 매칭 대상 필드:
@@ -197,63 +195,68 @@ function formatOutput(toolName, validation) {
   return lines.join('\n');
 }
 
+import { logHookDecision, PROJECT_DIR } from './utils.js';
+import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
+import { runPrTestGate } from './lib/pr-gate-runner.js';
+
+/** gh pr create 감지 정규식 (단어 경계 기준, 플래그 허용). */
+const GH_PR_CREATE_RE = /\bgh\s+pr\s+create\b/;
+
 /**
- * stdin에서 JSON 페이로드 읽기 (Claude Code 하네스 호환)
- * stdin이 없거나 파싱 실패 시 argv/env 폴백
+ * in-process 진입점 — 디스패처가 ctx를 전달해 직접 호출.
+ * @param {{ toolName: string, toolInput: string, payload: object|null }} ctx
+ * @returns {Promise<number>} exit code (0 = allowed, 2 = denied)
  */
-function readStdinSync() {
-  try {
-    if (process.stdin.isTTY) return null;
-    // fd 0을 직접 사용 (Windows는 '/dev/stdin'이 없음)
-    const buf = Buffer.alloc(65536);
-    const bytesRead = fs.readSync(0, buf, 0, buf.length, null);
-    if (bytesRead > 0) {
-      return JSON.parse(buf.toString('utf-8', 0, bytesRead));
+export async function run(ctx) {
+  const toolName = ctx.toolName || 'Bash';
+  const toolInput = ctx.toolInput;
+
+  // 1단계: 입력 스키마 검증 (구조적 오류 탐지)
+  const schemaResult = validateInputSchema(toolName, ctx.payload?.tool_input || toolInput);
+  if (!schemaResult.valid) {
+    // stderr: Claude Code surfaces stderr in hook-error notifications; stdout is injected
+    // into the assistant's context and never shown to the user. Guard messages target the user.
+    console.error(`⚠️ INPUT VALIDATION: ${toolName}`);
+    for (const err of schemaResult.errors) {
+      console.error(`  [SCHEMA] ${err}`);
     }
-  } catch { /* 파싱 실패 시 폴백 */ }
-  return null;
-}
+    logHookDecision('pre-tool-guard', toolName, 'warn', `schema: ${schemaResult.errors.join('; ')}`);
+    // 스키마 오류는 경고만 (차단하지 않음 — 레거시 호환)
+  }
 
-import fs from 'fs';
-
-// 메인 실행: stdin JSON 우선, argv 폴백
-const stdinPayload = readStdinSync();
-const toolName = stdinPayload?.tool_name || process.argv[2] || 'Bash';
-const toolInput = stdinPayload?.tool_input
-  ? (typeof stdinPayload.tool_input === 'string'
-    ? stdinPayload.tool_input
-    : JSON.stringify(stdinPayload.tool_input))
-  : (process.argv[3] || process.env.TOOL_INPUT || '');
-
-import { logHookDecision } from './utils.js';
-
-// 1단계: 입력 스키마 검증 (구조적 오류 탐지)
-const schemaResult = validateInputSchema(toolName, stdinPayload?.tool_input || toolInput);
-if (!schemaResult.valid) {
-  // stderr: Claude Code surfaces stderr in hook-error notifications; stdout is injected
-  // into the assistant's context and never shown to the user. Guard messages target the user.
-  console.error(`⚠️ INPUT VALIDATION: ${toolName}`);
-  for (const err of schemaResult.errors) {
-    console.error(`  [SCHEMA] ${err}`);
+  // 2단계: gh pr create Bash 명령 → PR 테스트 게이트
+  if (toolName === 'Bash' || toolName === 'bash') {
+    const command = extractTarget(toolInput, 'command') || toolInput;
+    if (GH_PR_CREATE_RE.test(command)) {
+      const gateResult = runPrTestGate(PROJECT_DIR);
+      if (!gateResult.passed) {
+        console.error(`[PR-GATE] Tests failed — gh pr create blocked\n${gateResult.output}`);
+        logHookDecision('pre-tool-guard', 'Bash', 'block', 'gh pr create: test gate failed');
+        return 2;
+      }
+    }
   }
-  logHookDecision('pre-tool-guard', toolName, 'warn', `schema: ${schemaResult.errors.join('; ')}`);
-  // 스키마 오류는 경고만 (차단하지 않음 — 레거시 호환)
-}
 
-// 2단계: 위험 패턴 검증 (보안 탐지)
-const validation = validateCommand(toolName, toolInput);
-const output = formatOutput(toolName, validation);
+  // 3단계: 위험 패턴 검증 (보안 탐지)
+  const validation = validateCommand(toolName, toolInput);
+  const output = formatOutput(toolName, validation);
 
-if (output) {
-  console.error(output);
-}
+  if (output) {
+    console.error(output);
+  }
 
-// Hook trace logging
-if (!validation.allowed) {
-  logHookDecision('pre-tool-guard', toolName, 'block', validation.warnings.join('; '));
-} else if (validation.warnings.length > 0) {
-  logHookDecision('pre-tool-guard', toolName, 'warn', validation.warnings.join('; '));
+  // Hook trace logging
+  if (!validation.allowed) {
+    logHookDecision('pre-tool-guard', toolName, 'block', validation.warnings.join('; '));
+  } else if (validation.warnings.length > 0) {
+    logHookDecision('pre-tool-guard', toolName, 'warn', validation.warnings.join('; '));
+  }
+
+  // Exit code: 0 = allowed, 2 = denied (claw-code 규약)
+  return validation.allowed ? 0 : 2;
 }
 
-// Exit code: 0 = allowed, 2 = denied (claw-code 규약), 1 = 레거시 호환
-process.exit(validation.allowed ? 0 : 2);
+// standalone CLI 모드: stdin JSON 우선, argv 폴백
+if (isDirectRun(import.meta.url)) {
+  process.exit(await run(buildCliCtx()));
+}

package/hooks/scripts/prompt-dispatcher.js

@@ -42,6 +42,16 @@ try {
 
 if (!prompt) process.exit(0);
 
+// vibe.run 감지 — runStarted 기록 및 verifyPassed 리셋 (in-process, stdout 없음).
+{
+  const { isVibeRunPrompt, extractRunFeature, recordRunStart } = await import('./lib/run-ledger.js');
+  if (isVibeRunPrompt(prompt)) {
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const feature = extractRunFeature(prompt);
+    recordRunStart(projectDir, feature);
+  }
+}
+
 // 레거시 SSOT 통합 — `/vibe.*` 진입 시 `.claude/vibe/` → `.vibe/` 자동 이동.
 // `vibe init`/`update` 와 동일한 `consolidateLegacyVibe` (dist/cli/setup/LegacyMigration.js) 를 직접 재사용. Idempotent.
 if (/^\s*\/vibe\b/i.test(prompt)) {

package/hooks/scripts/scope-guard.js

@@ -22,6 +22,7 @@
 import fs from 'fs';
 import path from 'path';
 import { PROJECT_DIR, logHookDecision, projectVibePath, projectVibeRoot } from './utils.js';
+import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
 
 const SCOPE_PATH = projectVibePath(PROJECT_DIR, 'scope.json');
 
@@ -86,16 +87,6 @@ function toRelative(filePath) {
   return rel || path.basename(filePath).replace(/\\/g, '/');
 }
 
-function readStdinSync() {
-  try {
-    if (process.stdin.isTTY) return null;
-    const buf = Buffer.alloc(65536);
-    const bytesRead = fs.readSync(0, buf, 0, buf.length, null);
-    if (bytesRead > 0) return JSON.parse(buf.toString('utf-8', 0, bytesRead));
-  } catch { /* ignore */ }
-  return null;
-}
-
 function extractFilePath(toolInput) {
   if (!toolInput) return '';
   if (typeof toolInput === 'string') {
@@ -105,41 +96,51 @@ function extractFilePath(toolInput) {
   return typeof toolInput.file_path === 'string' ? toolInput.file_path : '';
 }
 
-const scope = readScope();
-if (!scope) process.exit(0); // no scope declared → no-op
+/**
+ * in-process 진입점 — 디스패처가 ctx를 전달해 직접 호출.
+ * @param {{ toolName: string, toolInput: string }} ctx
+ * @returns {Promise<number>} exit code (0 = allow/no-op, 2 = block)
+ */
+export async function run(ctx) {
+  const scope = readScope();
+  if (!scope) return 0; // no scope declared → no-op
+
+  const toolName = ctx.toolName;
+  if (toolName !== 'Edit' && toolName !== 'Write') return 0;
 
-const stdinPayload = readStdinSync();
-const toolName = stdinPayload?.tool_name || process.argv[2] || '';
-if (toolName !== 'Edit' && toolName !== 'Write') process.exit(0);
+  const filePath = extractFilePath(ctx.toolInput);
+  if (!filePath) return 0;
 
-const rawInput = stdinPayload?.tool_input ?? process.argv[3] ?? process.env.TOOL_INPUT ?? '';
-const filePath = extractFilePath(rawInput);
-if (!filePath) process.exit(0);
+  const rel = toRelative(filePath);
 
-const rel = toRelative(filePath);
+  // 평가 순서: deny 우선 → allow 검증
+  const denied = scope.deny.length > 0 && matchesAny(rel, scope.deny);
+  const allowed = scope.allow.length === 0 || matchesAny(rel, scope.allow);
 
-// 평가 순서: deny 우선 → allow 검증
-const denied = scope.deny.length > 0 && matchesAny(rel, scope.deny);
-const allowed = scope.allow.length === 0 || matchesAny(rel, scope.allow);
+  const violated = denied || !allowed;
+  if (!violated) return 0;
 
-const violated = denied || !allowed;
-if (!violated) process.exit(0);
+  const lines = [];
+  lines.push(`🚧 SCOPE GUARD: ${toolName} — out of declared scope`);
+  lines.push(`  file: ${rel}`);
+  if (denied) lines.push(`  reason: matches deny pattern`);
+  else if (!allowed) lines.push(`  reason: not in allow list`);
+  if (scope.reason) lines.push(`  declared scope: ${scope.reason}`);
+  lines.push(`  declared in: ${path.relative(PROJECT_DIR, SCOPE_PATH)} (mode=${scope.mode})`);
 
-const lines = [];
-lines.push(`🚧 SCOPE GUARD: ${toolName} — out of declared scope`);
-lines.push(`  file: ${rel}`);
-if (denied) lines.push(`  reason: matches deny pattern`);
-else if (!allowed) lines.push(`  reason: not in allow list`);
-if (scope.reason) lines.push(`  declared scope: ${scope.reason}`);
-lines.push(`  declared in: ${path.relative(PROJECT_DIR, SCOPE_PATH)} (mode=${scope.mode})`);
+  const blocking = scope.mode === 'block';
+  if (blocking) {
+    lines.push('');
+    lines.push('🚫 BLOCKED. Edit scope.json or justify to the user before proceeding.');
+  }
 
-const blocking = scope.mode === 'block';
-if (blocking) {
-  lines.push('');
-  lines.push('🚫 BLOCKED. Edit scope.json or justify to the user before proceeding.');
-}
+  process.stderr.write(lines.join('\n') + '\n');
+  logHookDecision('scope-guard', toolName, blocking ? 'block' : 'warn', `${rel} ${denied ? '(deny)' : '(out-of-allow)'}`);
 
-console.log(lines.join('\n'));
-logHookDecision('scope-guard', toolName, blocking ? 'block' : 'warn', `${rel} ${denied ? '(deny)' : '(out-of-allow)'}`);
+  return blocking ? 2 : 0;
+}
 
-process.exit(blocking ? 2 : 0);
+// standalone CLI 모드: stdin JSON 우선, argv 폴백
+if (isDirectRun(import.meta.url)) {
+  process.exit(await run(buildCliCtx()));
+}