@wooojin/forgen 0.4.12 → 0.5.0

package/dist/host/install-opencode.js

@@ -0,0 +1,148 @@
+/**
+ * install-opencode — forgen 을 OpenCode host 에 설치 (W3-3 P1).
+ *
+ * OpenCode 는 in-process TS plugin + opencode.json(c) MCP + AGENTS.md 를 쓴다:
+ *   1. plugin: `~/.config/opencode/plugins/forgen.ts` (assets/opencode/forgen.ts 배포).
+ *      GUARD_CMD 는 절대 forgen CLI 경로로 치환(런타임 PATH 비의존 — 리뷰 MED4).
+ *   2. MCP: 기존 config 파일(opencode.jsonc 우선, 없으면 opencode.json)에 mcp.forgen-compound
+ *      surgical 병합. **JSONC 파서(jsonc-parser)로 주석/trailing-comma 보존**, 쓰기 전 백업
+ *      (리뷰 HIGH: JSON.parse 가 공식 JSONC 를 clobber 하던 데이터 손실 수정).
+ *   3. AGENTS.md: cwd 의 forgen rules block (Codex 헬퍼 재사용).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { applyEdits, modify, parse as parseJsonc } from 'jsonc-parser';
+import { createLogger } from '../core/logger.js';
+import { resolveAgentsMdPath, upsertForgenRulesInAgentsMd } from './install-codex.js';
+const log = createLogger('install-opencode');
+const PLUGIN_FILENAME = 'forgen.ts';
+const PLUGIN_MARKER = 'forgen-managed';
+const MCP_SERVER_NAME = 'forgen-compound';
+export function resolveOpencodeConfigDir(opts) {
+    if (opts.opencodeConfigDir)
+        return opts.opencodeConfigDir;
+    // OpenCode 는 XDG_CONFIG_HOME 을 존중한다(config docs). forgen 도 동일 해석해야 실제 로드
+    // 위치에 배포된다 — hardcode ~/.config 이면 XDG override 사용자에게 미도달.
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    const base = xdg && xdg.length > 0 ? xdg : path.join(os.homedir(), '.config');
+    return path.join(base, 'opencode');
+}
+/** 기존 config 파일 경로 감지 — opencode.jsonc 우선, 없으면 opencode.json (둘 다 없으면 .json 신규). */
+function resolveConfigFilePath(configDir) {
+    const jsonc = path.join(configDir, 'opencode.jsonc');
+    if (fs.existsSync(jsonc))
+        return jsonc;
+    return path.join(configDir, 'opencode.json');
+}
+/**
+ * config 텍스트에 mcp.forgen-compound 를 surgical 병합. jsonc-parser 로 주석/포맷 보존.
+ * 파싱 불가(errors)면 clobber 하지 않고 null 반환(데이터 손실 방지, 리뷰 HIGH).
+ */
+function upsertOpencodeMcp(currentText, pkgRoot) {
+    const serverPath = path.join(pkgRoot, 'dist', 'mcp', 'server.js');
+    const desired = { type: 'local', command: ['node', serverPath, '--host=opencode'], enabled: true };
+    const src = currentText.trim().length > 0 ? currentText : '{}';
+    // 파싱 검증 — 유효 JSONC 가 아니면(구조 손상) abort.
+    const errors = [];
+    const parsed = parseJsonc(src, errors, { allowTrailingComma: true });
+    if (errors.length > 0 || parsed === undefined || (parsed !== null && typeof parsed !== 'object')) {
+        return { content: null, alreadyPresent: false, unparseable: true };
+    }
+    const existing = parsed?.mcp?.[MCP_SERVER_NAME];
+    const alreadyPresent = JSON.stringify(existing) === JSON.stringify(desired);
+    if (alreadyPresent)
+        return { content: src, alreadyPresent: true, unparseable: false };
+    // surgical edit — 주석/기타 키/포맷 보존.
+    let out = src;
+    const opts = { formattingOptions: { insertSpaces: true, tabSize: 2 } };
+    out = applyEdits(out, modify(out, ['mcp', MCP_SERVER_NAME], desired, opts));
+    // $schema 없으면 추가(있으면 유지).
+    if (parsed.$schema === undefined) {
+        out = applyEdits(out, modify(out, ['$schema'], 'https://opencode.ai/config.json', opts));
+    }
+    return { content: out.endsWith('\n') ? out : `${out}\n`, alreadyPresent: false, unparseable: false };
+}
+/** 배포 plugin 소스 로드 + GUARD_CMD 를 절대 forgen CLI 경로로 치환(런타임 PATH 비의존). */
+function loadPluginSource(pkgRoot) {
+    const srcPath = path.join(pkgRoot, 'assets', 'opencode', PLUGIN_FILENAME);
+    let src;
+    try {
+        src = fs.readFileSync(srcPath, 'utf-8');
+    }
+    catch (e) {
+        log.debug('opencode plugin asset 읽기 실패', e);
+        return null;
+    }
+    const cliPath = path.join(pkgRoot, 'dist', 'cli.js');
+    // ["forgen", "<sub>"] → ["node", "<abs cli>", "<sub>"] (PATH 비의존, 리뷰 MED4).
+    const replaced = src
+        .replace(/\["forgen",\s*"opencode-guard"\]/, `["node", ${JSON.stringify(cliPath)}, "opencode-guard"]`)
+        .replace(/\["forgen",\s*"opencode-context"\]/, `["node", ${JSON.stringify(cliPath)}, "opencode-context"]`);
+    return replaced;
+}
+export function planOpencodeInstall(opts) {
+    const configDir = resolveOpencodeConfigDir(opts);
+    const pluginsDir = path.join(configDir, 'plugins');
+    const pluginPath = path.join(pluginsDir, PLUGIN_FILENAME);
+    const mcpConfigPath = resolveConfigFilePath(configDir);
+    const registerMcp = opts.registerMcp ?? true;
+    const dryRun = opts.dryRun ?? false;
+    const result = {
+        configDir,
+        pluginPath,
+        pluginInstalled: false,
+        mcpRegistered: false,
+        mcpAlreadyPresent: false,
+        mcpConfigPath,
+        mcpSkippedUnparseable: false,
+        agentsMdInjected: false,
+    };
+    // ── 1) plugin 배포 (marker 확인 + 사용자 파일 백업) ──
+    const pluginSrc = loadPluginSource(opts.pkgRoot);
+    if (pluginSrc) {
+        // 기존 plugin 이 forgen-managed 가 아니면(사용자 소유) 백업.
+        if (!dryRun && fs.existsSync(pluginPath)) {
+            const existing = fs.readFileSync(pluginPath, 'utf-8');
+            if (!existing.includes(PLUGIN_MARKER)) {
+                const bak = `${pluginPath}.bak`;
+                fs.copyFileSync(pluginPath, bak);
+                result.pluginBackupPath = bak;
+            }
+        }
+        if (!dryRun) {
+            fs.mkdirSync(pluginsDir, { recursive: true });
+            fs.writeFileSync(pluginPath, pluginSrc, 'utf-8');
+        }
+        result.pluginInstalled = true;
+    }
+    // ── 2) MCP surgical 병합 (JSONC 안전 + 백업 + abort-on-unparseable) ──
+    if (registerMcp) {
+        const current = fs.existsSync(mcpConfigPath) ? fs.readFileSync(mcpConfigPath, 'utf-8') : '';
+        const merge = upsertOpencodeMcp(current, opts.pkgRoot);
+        if (merge.unparseable) {
+            // 파싱 불가 → 사용자 config 보존, MCP 스킵 + 경고 (데이터 손실 방지).
+            result.mcpSkippedUnparseable = true;
+            log.debug(`opencode config 파싱 불가 — MCP 등록 스킵(사용자 파일 보존): ${mcpConfigPath}`);
+        }
+        else {
+            result.mcpAlreadyPresent = merge.alreadyPresent;
+            result.mcpRegistered = !merge.alreadyPresent;
+            if (!dryRun && merge.content !== null && !merge.alreadyPresent) {
+                fs.mkdirSync(configDir, { recursive: true });
+                // 쓰기 전 백업(기존 파일이 있을 때만).
+                if (current.length > 0) {
+                    const bak = `${mcpConfigPath}.bak`;
+                    fs.writeFileSync(bak, current, 'utf-8');
+                    result.mcpBackupPath = bak;
+                }
+                fs.writeFileSync(mcpConfigPath, merge.content, 'utf-8');
+            }
+        }
+    }
+    // ── 3) AGENTS.md rules (Codex 헬퍼 재사용) ──
+    const agentsMdPath = opts.agentsMdPath ?? resolveAgentsMdPath(opts.pkgRoot);
+    const agentsResult = upsertForgenRulesInAgentsMd({ agentsMdPath, pkgRoot: opts.pkgRoot, dryRun });
+    result.agentsMdInjected = agentsResult.injected;
+    return result;
+}

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

@@ -13,7 +13,9 @@
 import { detectAvailableHosts } from '../core/host-detect.js';
 import { type ClaudeInstallResult } from './install-claude.js';
 import { type CodexInstallResult } from './install-codex.js';
-export type InstallTarget = 'claude' | 'codex' | 'both';
+import { type OpencodeInstallResult } from './install-opencode.js';
+import type { HostId } from '../core/trust-layer-intent.js';
+export type InstallTarget = HostId | 'both';
 export interface OrchestratorOptions {
     /** Sub-command 인자: 'claude'|'codex'|'both' 또는 undefined (interactive). */
     target?: string;
@@ -25,6 +27,7 @@ export interface OrchestratorResult {
     target: InstallTarget;
     claude?: ClaudeInstallResult;
     codex?: CodexInstallResult;
+    opencode?: OpencodeInstallResult;
     detection: ReturnType<typeof detectAvailableHosts>;
 }
 export declare function runInstall(opts: OrchestratorOptions): Promise<OrchestratorResult | null>;

package/dist/host/install-orchestrator.js

@@ -16,6 +16,7 @@ import { fileURLToPath } from 'node:url';
 import { detectAvailableHosts } from '../core/host-detect.js';
 import { planClaudeInstall } from './install-claude.js';
 import { planCodexInstall } from './install-codex.js';
+import { planOpencodeInstall } from './install-opencode.js';
 function askChoice(rl, question, validChoices) {
     return new Promise((resolve) => {
         const ask = () => {
@@ -49,6 +50,11 @@ async function chooseTargetInteractively(detection) {
     console.log('  Detected hosts:');
     console.log(renderHostStatus(detection.claude));
     console.log(renderHostStatus(detection.codex));
+    // W3-3 P1: OpenCode 는 감지만 하고 설치 대상엔 아직 안 넣는다(plugin 슬림 미구현).
+    // 감지됐을 때만 정직하게 "detected, install pending" 안내.
+    if (detection.opencode.available) {
+        console.log(`  ⋯ opencode (detected — 설치는 P1 plugin 슬림 착지 후 지원 예정, 현재 미지원)`);
+    }
     console.log('');
     if (detection.noneAvailable) {
         console.log('  ⚠ Neither Claude nor Codex detected. Install one of:');
@@ -75,7 +81,7 @@ async function chooseTargetInteractively(detection) {
 export async function runInstall(opts) {
     const detection = detectAvailableHosts();
     let target;
-    if (opts.target === 'claude' || opts.target === 'codex' || opts.target === 'both') {
+    if (opts.target === 'claude' || opts.target === 'codex' || opts.target === 'opencode' || opts.target === 'both') {
         target = opts.target;
     }
     else if (opts.target === undefined) {
@@ -96,6 +102,10 @@ export async function runInstall(opts) {
     if (target === 'codex' || target === 'both') {
         result.codex = planCodexInstall({ pkgRoot: opts.pkgRoot, dryRun, registerMcp });
     }
+    // W3-3: opencode 는 명시 타겟일 때만 설치('both' 는 claude+codex primary-pair 유지).
+    if (target === 'opencode') {
+        result.opencode = planOpencodeInstall({ pkgRoot: opts.pkgRoot, dryRun, registerMcp });
+    }
     return result;
 }
 /** CLI 출력 포맷터 — orchestrator 결과를 사용자에게 표시. */
@@ -118,6 +128,15 @@ export function renderResult(result, dryRun) {
         lines.push(`    hooks.json: ${result.codex.hooksCount} forgen hooks (preserved user: ${result.codex.preservedUserHookCount})`);
         lines.push(`    MCP: ${result.codex.mcpAlreadyPresent ? 'already present' : (result.codex.mcpRegistered ? 'registered' : 'skipped')}`);
     }
+    if (result.opencode) {
+        lines.push('');
+        lines.push('  OpenCode (P1 — block-tool-use + MCP, 실험적):');
+        lines.push(`    config dir: ${result.opencode.configDir}`);
+        lines.push(`    plugin: ${result.opencode.pluginInstalled ? 'installed' : 'skipped'} → ${result.opencode.pluginPath}`);
+        lines.push(`    MCP: ${result.opencode.mcpAlreadyPresent ? 'already present' : (result.opencode.mcpRegistered ? 'registered' : 'skipped')}`);
+        lines.push(`    AGENTS.md rules: ${result.opencode.agentsMdInjected ? 'injected' : 'skipped'}`);
+        lines.push('    note: 완료가드/context 주입은 후속 증분 (projection/inject 미완).');
+    }
     lines.push('');
     return lines.join('\n');
 }

package/dist/host/invoke-agent.d.ts

@@ -9,17 +9,18 @@
  * 또 sub-agent 호출 시도 → 차단).
  */
 import { type ExecHostResult } from './exec-host.js';
+import type { HostId } from '../core/trust-layer-intent.js';
 export interface InvokeAgentOptions {
     agentName: string;
     task: string;
     /** Child process timeout (ms). Default 60s. */
     timeoutMs?: number;
     /** Override host (default: profile.default_host). */
-    host?: 'claude' | 'codex';
+    host?: HostId;
 }
 export interface InvokeAgentResult {
     agentName: string;
-    host: 'claude' | 'codex';
+    host: HostId;
     summary: string;
     durationMs: number;
     usage: ExecHostResult['usage'];

package/dist/host/opencode/context-cli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `forgen opencode-context` — OpenCode plugin 이 compaction 시 주입할 forgen context 출력 (W3-3 P1).
+ *
+ * OpenCode 의 유일한 문서화된 context 주입 표면은 `experimental.session.compacting`
+ * (output.context.push) — *compaction 시점*에 context 를 얹는다. forgen 은 여기에 활성
+ * forge-loop 상태(≤1KB)를 얹어 **compaction 을 넘어 목표가 유지**되게 한다
+ * (forge-loop-state-inject intent, capabilities-opencode=partial).
+ *
+ * 정직한 스코프: Claude 의 per-prompt 주입(UserPromptSubmit)과 달리 OpenCode 플러그인은
+ * 매 프롬프트 주입 표면이 문서화돼 있지 않다 → 정적 룰은 AGENTS.md(install), compound 는
+ * MCP tool 로 커버하고, 동적 forge-loop 상태만 compaction 에 얹는다.
+ *
+ * 활성 forge-loop 이 없으면 빈 출력(주입할 것 없음).
+ */
+export declare function runOpencodeContext(): void;

package/dist/host/opencode/context-cli.js

@@ -0,0 +1,25 @@
+/**
+ * `forgen opencode-context` — OpenCode plugin 이 compaction 시 주입할 forgen context 출력 (W3-3 P1).
+ *
+ * OpenCode 의 유일한 문서화된 context 주입 표면은 `experimental.session.compacting`
+ * (output.context.push) — *compaction 시점*에 context 를 얹는다. forgen 은 여기에 활성
+ * forge-loop 상태(≤1KB)를 얹어 **compaction 을 넘어 목표가 유지**되게 한다
+ * (forge-loop-state-inject intent, capabilities-opencode=partial).
+ *
+ * 정직한 스코프: Claude 의 per-prompt 주입(UserPromptSubmit)과 달리 OpenCode 플러그인은
+ * 매 프롬프트 주입 표면이 문서화돼 있지 않다 → 정적 룰은 AGENTS.md(install), compound 는
+ * MCP tool 로 커버하고, 동적 forge-loop 상태만 compaction 에 얹는다.
+ *
+ * 활성 forge-loop 이 없으면 빈 출력(주입할 것 없음).
+ */
+import { readForgeLoopState, renderForgeLoopForSession } from '../../hooks/shared/forge-loop-state.js';
+export function runOpencodeContext() {
+    let block = null;
+    try {
+        block = renderForgeLoopForSession(readForgeLoopState());
+    }
+    catch {
+        block = null; // fail-safe — 주입 실패가 세션을 막지 않는다
+    }
+    process.stdout.write(block ?? '');
+}

package/dist/host/opencode/guard-cli.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `forgen opencode-guard` — OpenCode plugin 슬림이 호출하는 경량 브릿지 CLI (W3-3 P1).
+ *
+ * OpenCode 플러그인(`~/.config/opencode/plugins/forgen.ts`)이 `tool.execute.before` 에서
+ * `{tool, args}` 를 stdin 으로 넘기면, 이 명령이 forgen PreToolUse 가드 체인을 돌려
+ * `{block, reason}` 을 stdout 으로 반환한다. 플러그인은 block 이면 throw(도구 차단).
+ *
+ * 플러그인을 얇게 유지(= 번역/가드 로직 중복 없음, drift-free)하는 대신 forgen 이 이
+ * 한 명령으로 전부 처리한다. per-tool-call 이라 cli.ts 최상단 fast-path 로 진입한다.
+ *
+ * fail-open: stdin 파싱 실패/가드 오류는 도구를 막지 않는다 → {block:false}.
+ */
+export declare function runOpencodeGuard(): Promise<void>;

package/dist/host/opencode/guard-cli.js

@@ -0,0 +1,39 @@
+/**
+ * `forgen opencode-guard` — OpenCode plugin 슬림이 호출하는 경량 브릿지 CLI (W3-3 P1).
+ *
+ * OpenCode 플러그인(`~/.config/opencode/plugins/forgen.ts`)이 `tool.execute.before` 에서
+ * `{tool, args}` 를 stdin 으로 넘기면, 이 명령이 forgen PreToolUse 가드 체인을 돌려
+ * `{block, reason}` 을 stdout 으로 반환한다. 플러그인은 block 이면 throw(도구 차단).
+ *
+ * 플러그인을 얇게 유지(= 번역/가드 로직 중복 없음, drift-free)하는 대신 forgen 이 이
+ * 한 명령으로 전부 처리한다. per-tool-call 이라 cli.ts 최상단 fast-path 로 진입한다.
+ *
+ * fail-open: stdin 파싱 실패/가드 오류는 도구를 막지 않는다 → {block:false}.
+ */
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { toolBeforeToClaudeInput } from './translate.js';
+import { runPreToolGuards } from './plugin/forgen.js';
+/** 이 CLI(dist/host/opencode/guard-cli.js) 기준 forgen dist/hooks 절대경로. */
+function forgenHookDir() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'hooks');
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+}
+export async function runOpencodeGuard() {
+    let payload = {};
+    try {
+        payload = JSON.parse((await readStdin()) || '{}');
+    }
+    catch {
+        process.stdout.write(JSON.stringify({ block: false }));
+        return;
+    }
+    const claudeInput = toolBeforeToClaudeInput(payload.tool ?? '', payload.args);
+    const decision = await runPreToolGuards(claudeInput, { hookDir: forgenHookDir() });
+    process.stdout.write(JSON.stringify(decision));
+}

package/dist/host/opencode/plugin/forgen.d.ts

@@ -0,0 +1,31 @@
+/**
+ * forgen OpenCode 가드 러너 (W3-3 P1, adapter-plan §4.1 in-process-plugin binding).
+ *
+ * OpenCode `tool.execute.before` → forgen 기존 PreToolUse 가드(pre-tool-use/db-guard) 브릿지의
+ * *핵심 로직*. `forgen opencode-guard` CLI(guard-cli.ts)가 이 함수를 호출한다. 실 배포되는
+ * 플러그인(assets/opencode/forgen.ts)은 이 CLI 를 async 로 부르는 얇은 shim 이라, OpenCode
+ * 이벤트루프를 막지 않는다.
+ *
+ * 리뷰 MED (a): spawnSync 는 in-process 플러그인에서 이벤트루프를 막으므로 **async spawn**
+ * (execFile+await)으로 구현. (b): spawn 실패는 fail-open 하되 **로그**를 남겨 systematically
+ * -broken 가드를 관찰 가능하게 한다.
+ *
+ * fail-open 정책: 가드 해소/spawn 실패는 도구를 막지 않는다(forgen hook 실패 정책과 동일).
+ */
+import { type ClaudePreToolInput, type OpencodeToolDecision } from '../translate.js';
+/** PreToolUse 가드 순서: pre-tool-use(룰+위험명령 디스패처) → db-guard(rm -rf/위험 SQL). */
+export declare const PRE_TOOL_GUARDS: readonly ["pre-tool-use.js", "db-guard.js"];
+export interface GuardRunOptions {
+    /** forgen hook 바이너리 디렉터리. guard-cli 가 forgen dist/hooks 를 주입. */
+    hookDir?: string;
+    /** spawn 타임아웃(ms). */
+    timeoutMs?: number;
+}
+/** forgen hook 디렉터리 해소: 명시 > FORGEN_HOOK_DIR env > ~/.forgen/hooks 폴백. */
+export declare function resolveHookDir(explicit?: string): string;
+/**
+ * Claude PreToolUse 입력을 forgen 가드 체인에 흘려 첫 deny 를 반환(테스트 가능한 핵심).
+ * **async** — execFile 로 비동기 spawn (이벤트루프 비차단). 어느 가드든 deny 하면 즉시 block.
+ * 전부 통과/실패(fail-open)면 block=false. spawn 실패는 로그 후 계속(fail-open).
+ */
+export declare function runPreToolGuards(claudeInput: ClaudePreToolInput, opts?: GuardRunOptions): Promise<OpencodeToolDecision>;

package/dist/host/opencode/plugin/forgen.js

@@ -0,0 +1,60 @@
+/**
+ * forgen OpenCode 가드 러너 (W3-3 P1, adapter-plan §4.1 in-process-plugin binding).
+ *
+ * OpenCode `tool.execute.before` → forgen 기존 PreToolUse 가드(pre-tool-use/db-guard) 브릿지의
+ * *핵심 로직*. `forgen opencode-guard` CLI(guard-cli.ts)가 이 함수를 호출한다. 실 배포되는
+ * 플러그인(assets/opencode/forgen.ts)은 이 CLI 를 async 로 부르는 얇은 shim 이라, OpenCode
+ * 이벤트루프를 막지 않는다.
+ *
+ * 리뷰 MED (a): spawnSync 는 in-process 플러그인에서 이벤트루프를 막으므로 **async spawn**
+ * (execFile+await)으로 구현. (b): spawn 실패는 fail-open 하되 **로그**를 남겨 systematically
+ * -broken 가드를 관찰 가능하게 한다.
+ *
+ * fail-open 정책: 가드 해소/spawn 실패는 도구를 막지 않는다(forgen hook 실패 정책과 동일).
+ */
+import { execFile } from 'node:child_process';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import { createLogger } from '../../../core/logger.js';
+import { decisionFromForgenOutput, } from '../translate.js';
+const execFileAsync = promisify(execFile);
+const log = createLogger('opencode-guard');
+/** PreToolUse 가드 순서: pre-tool-use(룰+위험명령 디스패처) → db-guard(rm -rf/위험 SQL). */
+export const PRE_TOOL_GUARDS = ['pre-tool-use.js', 'db-guard.js'];
+/** forgen hook 디렉터리 해소: 명시 > FORGEN_HOOK_DIR env > ~/.forgen/hooks 폴백. */
+export function resolveHookDir(explicit) {
+    return explicit ?? process.env.FORGEN_HOOK_DIR ?? path.join(os.homedir(), '.forgen', 'hooks');
+}
+/**
+ * Claude PreToolUse 입력을 forgen 가드 체인에 흘려 첫 deny 를 반환(테스트 가능한 핵심).
+ * **async** — execFile 로 비동기 spawn (이벤트루프 비차단). 어느 가드든 deny 하면 즉시 block.
+ * 전부 통과/실패(fail-open)면 block=false. spawn 실패는 로그 후 계속(fail-open).
+ */
+export async function runPreToolGuards(claudeInput, opts = {}) {
+    const dir = resolveHookDir(opts.hookDir);
+    const stdin = JSON.stringify(claudeInput);
+    const timeout = opts.timeoutMs ?? 5000;
+    for (const guard of PRE_TOOL_GUARDS) {
+        try {
+            const child = execFileAsync('node', [path.join(dir, guard)], { timeout, encoding: 'utf-8' });
+            child.child.stdin?.end(stdin);
+            const { stdout } = await child;
+            const decision = decisionFromForgenOutput(stdout ?? '');
+            if (decision.block)
+                return decision;
+        }
+        catch (e) {
+            // fail-open, 그러나 관찰 가능하게 — systematically-broken 가드 발견용 (리뷰 MED b).
+            // execFile 은 non-zero exit(가드가 정상 deny 로 종료해도)에서 throw 할 수 있어 stdout 을 확인.
+            const stdout = e?.stdout;
+            if (typeof stdout === 'string') {
+                const decision = decisionFromForgenOutput(stdout);
+                if (decision.block)
+                    return decision;
+            }
+            log.debug(`opencode 가드 spawn 실패(fail-open): ${guard}`, e);
+        }
+    }
+    return { block: false };
+}

package/dist/host/opencode/translate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OpenCode ↔ Claude hook translation (W3-3 P1 plugin 슬림, adapter-plan §4.1).
+ *
+ * OpenCode 는 in-process TS plugin(`tool.execute.before(input, output)`)이라 forgen 의
+ * subprocess hook(Claude PreToolUse schema stdin/stdout)과 형태가 다르다. 이 모듈은 그 사이
+ * *순수* 번역만 담당한다 — spawn/파일 IO 는 plugin shim(forgen.ts)이 수행.
+ *
+ * 번역 축:
+ *   1. tool 이름: opencode(소문자 bash/read/write/edit…) → Claude(Bash/Read/Write/Edit…).
+ *   2. tool 인자 키: opencode(filePath) → Claude(file_path) 등, 가드가 읽는 필드 정합.
+ *   3. 결정: forgen PreToolUse 출력(permissionDecision:deny) → OpenCode block(throw) 신호.
+ *
+ * 이 계약은 docs-level(adapter-plan §2.2 web probe) 기반이며, 실제 OpenCode tool 스키마로
+ * plugin 슬림 통합 시 검증·보정한다.
+ */
+/** Claude PreToolUse hook 에 넣을 입력 (forgen hook 이 stdin 으로 받는 형태). */
+export interface ClaudePreToolInput {
+    hook_event_name: 'PreToolUse';
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+}
+/** forgen PreToolUse hook 결정 → OpenCode 로 번역한 판정. */
+export interface OpencodeToolDecision {
+    /** true 면 plugin 이 throw 해서 도구 실행을 차단. */
+    block: boolean;
+    reason?: string;
+}
+/**
+ * OpenCode tool 이름 → Claude tool 이름. forgen 가드(db-guard/pre-tool-use)가 Claude tool
+ * 이름 관습(Bash/Read/Write/Edit)으로 매칭하므로 정합이 필요하다.
+ */
+export declare const OPENCODE_TO_CLAUDE_TOOL: Readonly<Record<string, string>>;
+/** 매핑에 없으면 첫 글자 대문자화(안전 폴백) — 가드가 못 알아봐도 fail-open(허용). */
+export declare function mapToolName(opencodeTool: string): string;
+/**
+ * OpenCode tool 인자 키 → Claude tool_input 키. 가드가 읽는 필드만 정규화한다:
+ *   - filePath → file_path (Read/Write/Edit 대상 파일)
+ *   - command 는 그대로 (Bash) — db-guard 가 tool_input.command 로 rm -rf 감지.
+ * 나머지 키는 원본 유지(추가 정보는 무해).
+ */
+export declare function normalizeToolArgs(args: Record<string, unknown> | undefined | null): Record<string, unknown>;
+/** OpenCode `tool.execute.before` (input.tool, output.args) → Claude PreToolUse stdin. */
+export declare function toolBeforeToClaudeInput(opencodeTool: string, opencodeArgs: Record<string, unknown> | undefined | null): ClaudePreToolInput;
+/**
+ * forgen PreToolUse hook 의 stdout(JSON 여러 줄일 수 있음) → OpenCode 판정.
+ * permissionDecision:"deny" → block(throw). 그 외/파싱 실패 → 허용(fail-open — 가드 부재가
+ * 도구를 막지 않는다, forgen 의 hook 실패 정책과 동일).
+ */
+export declare function decisionFromForgenOutput(stdout: string): OpencodeToolDecision;

package/dist/host/opencode/translate.js

@@ -0,0 +1,96 @@
+/**
+ * OpenCode ↔ Claude hook translation (W3-3 P1 plugin 슬림, adapter-plan §4.1).
+ *
+ * OpenCode 는 in-process TS plugin(`tool.execute.before(input, output)`)이라 forgen 의
+ * subprocess hook(Claude PreToolUse schema stdin/stdout)과 형태가 다르다. 이 모듈은 그 사이
+ * *순수* 번역만 담당한다 — spawn/파일 IO 는 plugin shim(forgen.ts)이 수행.
+ *
+ * 번역 축:
+ *   1. tool 이름: opencode(소문자 bash/read/write/edit…) → Claude(Bash/Read/Write/Edit…).
+ *   2. tool 인자 키: opencode(filePath) → Claude(file_path) 등, 가드가 읽는 필드 정합.
+ *   3. 결정: forgen PreToolUse 출력(permissionDecision:deny) → OpenCode block(throw) 신호.
+ *
+ * 이 계약은 docs-level(adapter-plan §2.2 web probe) 기반이며, 실제 OpenCode tool 스키마로
+ * plugin 슬림 통합 시 검증·보정한다.
+ */
+/**
+ * OpenCode tool 이름 → Claude tool 이름. forgen 가드(db-guard/pre-tool-use)가 Claude tool
+ * 이름 관습(Bash/Read/Write/Edit)으로 매칭하므로 정합이 필요하다.
+ */
+export const OPENCODE_TO_CLAUDE_TOOL = Object.freeze({
+    bash: 'Bash',
+    read: 'Read',
+    write: 'Write',
+    edit: 'Edit',
+    patch: 'Edit',
+    grep: 'Grep',
+    glob: 'Glob',
+    list: 'LS',
+    webfetch: 'WebFetch',
+    task: 'Task',
+});
+/** 매핑에 없으면 첫 글자 대문자화(안전 폴백) — 가드가 못 알아봐도 fail-open(허용). */
+export function mapToolName(opencodeTool) {
+    if (!opencodeTool)
+        return '';
+    return OPENCODE_TO_CLAUDE_TOOL[opencodeTool.toLowerCase()] ?? (opencodeTool[0].toUpperCase() + opencodeTool.slice(1));
+}
+/**
+ * OpenCode tool 인자 키 → Claude tool_input 키. 가드가 읽는 필드만 정규화한다:
+ *   - filePath → file_path (Read/Write/Edit 대상 파일)
+ *   - command 는 그대로 (Bash) — db-guard 가 tool_input.command 로 rm -rf 감지.
+ * 나머지 키는 원본 유지(추가 정보는 무해).
+ */
+export function normalizeToolArgs(args) {
+    if (!args || typeof args !== 'object')
+        return {};
+    const out = { ...args };
+    if ('filePath' in out && !('file_path' in out)) {
+        out.file_path = out.filePath;
+    }
+    return out;
+}
+/** OpenCode `tool.execute.before` (input.tool, output.args) → Claude PreToolUse stdin. */
+export function toolBeforeToClaudeInput(opencodeTool, opencodeArgs) {
+    return {
+        hook_event_name: 'PreToolUse',
+        tool_name: mapToolName(opencodeTool),
+        tool_input: normalizeToolArgs(opencodeArgs),
+    };
+}
+/**
+ * forgen PreToolUse hook 의 stdout(JSON 여러 줄일 수 있음) → OpenCode 판정.
+ * permissionDecision:"deny" → block(throw). 그 외/파싱 실패 → 허용(fail-open — 가드 부재가
+ * 도구를 막지 않는다, forgen 의 hook 실패 정책과 동일).
+ */
+export function decisionFromForgenOutput(stdout) {
+    const parsed = lastJsonObject(stdout);
+    if (!parsed || typeof parsed !== 'object')
+        return { block: false };
+    const hso = parsed.hookSpecificOutput;
+    if (hso && typeof hso === 'object') {
+        const decision = hso.permissionDecision;
+        if (decision === 'deny') {
+            const reason = hso.permissionDecisionReason;
+            return { block: true, reason: typeof reason === 'string' ? reason : '[forgen] blocked by guard' };
+        }
+    }
+    return { block: false };
+}
+/** 텍스트에서 마지막 JSON 객체를 파싱(hook 이 로그+JSON 을 섞어 낼 수 있음). */
+function lastJsonObject(raw) {
+    if (!raw)
+        return null;
+    const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        if (!lines[i].startsWith('{'))
+            continue;
+        try {
+            return JSON.parse(lines[i]);
+        }
+        catch {
+            /* try previous line */
+        }
+    }
+    return null;
+}

package/dist/host/parity-harness.d.ts

@@ -15,6 +15,13 @@
  */
 import type { HookEventInput, HookEventOutput } from '../core/types.js';
 import type { HostId, TrustLayerIntent } from '../core/trust-layer-intent.js';
+/**
+ * Parity 는 *subprocess-hook* 형태 호스트(Claude/Codex) 간 projection 등가성만 검증한다.
+ * OpenCode(P1)는 in-process plugin 형태라 projection 이 아직 미구현(fail-loud 스텁)이므로
+ * parity corpus 범위에서 **명시적으로 제외** — 플러그인 슬림 착지 후 별도 parity 바인딩으로
+ * 편입한다(plan §4.3). 여기에 opencode 를 넣어 가짜 등가 주장을 만들지 않는다.
+ */
+type ParityHost = Extract<HostId, 'claude' | 'codex'>;
 export interface BehavioralParityScenario {
     readonly id: string;
     /** 검증하려는 Trust Layer 의도. */
@@ -26,7 +33,7 @@ export interface BehavioralParityScenario {
      * 각 host 가 *내보낼 것으로 가정* 하는 raw 출력. P4 단계에서는 spec §18 source schema
      * 기반 직접 작성. P6 단계에서는 실 Codex CLI 출력으로 대체.
      */
-    readonly hostRaw: Record<HostId, unknown>;
+    readonly hostRaw: Record<ParityHost, unknown>;
     /**
      * 사영 후 의미 동치성을 검증할 키들.
      * 예: ['continue', 'hookSpecificOutput.permissionDecision'].
@@ -44,7 +51,7 @@ export interface ParityCheckResult {
         codex: unknown;
     }>;
     /** 사영 결과 자체 (디버깅용). */
-    readonly projected: Readonly<Record<HostId, HookEventOutput>>;
+    readonly projected: Readonly<Record<ParityHost, HookEventOutput>>;
 }
 export declare function runScenario(scenario: BehavioralParityScenario): ParityCheckResult;
 /**
@@ -60,3 +67,4 @@ export declare function runScenario(scenario: BehavioralParityScenario): ParityC
  *   - suppress-output-equivalence      : suppressOutput 동치성
  */
 export declare const SCENARIO_CORPUS: ReadonlyArray<BehavioralParityScenario>;
+export {};

package/dist/host/projection.js

@@ -114,9 +114,20 @@ export const projectCodexToClaude = (raw, input) => {
  * 교체하면 되도록 — `getProjection(host)` 가 단일 진입점.)
  */
 export const projectClaudeToClaude = (raw, input) => projectCodexToClaude(raw, input);
+/**
+ * OpenCode projection — P1 파운데이션 fail-loud 스텁.
+ * OpenCode 는 in-process plugin(throw/return)이라 subprocess stdout projection 과 형태가
+ * 다르다(plan §5 blocker 1). 실제 translation 은 plugin 슬림이 착지할 때 구현한다. 그 전까지
+ * 이 함수는 도달 불가(install-opencode 미구현 → getProjection('opencode') 미호출)이며,
+ * 혹시 호출되면 조용히 잘못된 결과를 내는 대신 명시적으로 실패한다.
+ */
+const projectOpencodeToClaude = () => {
+    throw new Error('[forgen] OpenCode projection 미구현 — P1 plugin 슬림 착지 후 구현 예정 (plan §4.1 in-process-plugin binding).');
+};
 const PROJECTIONS = {
     claude: projectClaudeToClaude,
     codex: projectCodexToClaude,
+    opencode: projectOpencodeToClaude,
 };
 export function getProjection(host) {
     const fn = PROJECTIONS[host];