clean-room-skill 0.1.11 → 0.1.13

package/lib/doctor.cjs

@@ -6,11 +6,16 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const { readJsonFile } = require('./fs-utils.cjs');
-const { CLEAN_ROOM_HOOKS, configPathForRuntime } = require('./hooks.cjs');
+const {
+  CLEAN_ROOM_HOOKS,
+  configPathForRuntime,
+  hasManagedOpenCodePlugin,
+  pluginPathForRuntime,
+} = require('./hooks.cjs');
 const { resolveRuntimeLayout } = require('./runtime-layout.cjs');
 
 const HOOK_MODES = new Set(['safe', 'strict']);
-const RUNTIMES = new Set(['codex', 'claude']);
+const RUNTIMES = new Set(['codex', 'claude', 'opencode']);
 const MAX_SPAWN_OUTPUT_CHARS = 2000;
 const MAX_SPAWN_OUTPUT_BYTES = 256 * 1024;
 const DOCTOR_TIMEOUT_MS = envPositiveInteger('CLEAN_ROOM_DOCTOR_TIMEOUT_MS', 10_000);
@@ -66,7 +71,7 @@ function parseDoctorArgs(argv) {
     }
   }
   if (!RUNTIMES.has(options.runtime)) {
-    throw new Error('doctor --runtime must be codex or claude');
+    throw new Error('doctor --runtime must be codex, claude, or opencode');
   }
   if (!HOOK_MODES.has(options.hookMode)) {
     throw new Error('doctor --hooks must be safe or strict');
@@ -215,7 +220,7 @@ function smokeEnv(layout, tmpRoot, role) {
 }
 
 function runHookCommand(command, payload, env, cwd) {
-  const parts = shellSplit(command);
+  const parts = commandParts(command);
   return spawnSync(parts[0], parts.slice(1), {
     cwd,
     env,
@@ -228,7 +233,7 @@ function runHookCommand(command, payload, env, cwd) {
 }
 
 function runHookCommandRaw(command, input, env, cwd) {
-  const parts = shellSplit(command);
+  const parts = commandParts(command);
   return spawnSync(parts[0], parts.slice(1), {
     cwd,
     env,
@@ -240,6 +245,10 @@ function runHookCommandRaw(command, input, env, cwd) {
   });
 }
 
+function commandParts(command) {
+  return Array.isArray(command) ? command : shellSplit(command);
+}
+
 function spawnOutputSnippet(value) {
   const text = String(value || '').trim();
   if (!text) return null;
@@ -324,9 +333,152 @@ function assertStrictCoverage(entries) {
   }
 }
 
+function hookCommandParts(wrapperPath, hookMode, checks) {
+  const parts = ['python3', wrapperPath, '--mode', hookMode];
+  for (const check of checks) {
+    parts.push('--check', check);
+  }
+  return parts;
+}
+
+function extractStringConstant(content, name) {
+  const match = content.match(new RegExp(`const\\s+${name}\\s*=\\s*("(?:\\\\.|[^"\\\\])*")`));
+  if (!match) {
+    throw new Error(`OpenCode plugin is missing ${name}`);
+  }
+  return JSON.parse(match[1]);
+}
+
+function assertOpenCodePlugin(layout, hookMode) {
+  const pluginPath = pluginPathForRuntime(layout.runtime, layout.targetRoot);
+  if (!pluginPath || !fs.existsSync(pluginPath)) {
+    throw new Error(`OpenCode plugin does not exist: ${pluginPath}`);
+  }
+  if (!hasManagedOpenCodePlugin(pluginPath)) {
+    throw new Error(`OpenCode plugin is not managed by clean-room-skill: ${pluginPath}`);
+  }
+  const content = fs.readFileSync(pluginPath, 'utf8');
+  if (!content.includes('"tool.execute.before"')) {
+    throw new Error('OpenCode plugin is missing tool.execute.before hook');
+  }
+  if (!content.includes('"tool.execute.after"')) {
+    throw new Error('OpenCode plugin is missing tool.execute.after hook');
+  }
+  if (!content.includes('shell: false')) {
+    throw new Error('OpenCode plugin must spawn hook checks with shell: false');
+  }
+  const wrapperPath = extractStringConstant(content, 'CLEAN_ROOM_HOOK_WRAPPER');
+  if (!path.isAbsolute(wrapperPath) || path.basename(wrapperPath) !== 'clean-room-hook.py') {
+    throw new Error('OpenCode plugin wrapper path is not absolute');
+  }
+  if (!fs.existsSync(wrapperPath)) {
+    throw new Error(`OpenCode plugin wrapper does not exist: ${wrapperPath}`);
+  }
+  const observedMode = extractStringConstant(content, 'CLEAN_ROOM_HOOK_MODE');
+  if (observedMode !== hookMode) {
+    throw new Error(`OpenCode plugin does not use --mode ${hookMode}`);
+  }
+  for (const required of CLEAN_ROOM_HOOKS) {
+    for (const check of required.checks) {
+      if (!content.includes(check)) {
+        throw new Error(`OpenCode plugin is missing check ${check}`);
+      }
+    }
+  }
+  return { pluginPath, wrapperPath };
+}
+
+function printOpenCodeCoverage(plugin, hookMode) {
+  console.log('clean-room OpenCode plugin coverage:');
+  console.log('  ok             tool.execute.before shell/read/write');
+  console.log('  ok             tool.execute.after  write');
+  console.log(`  wrapper: ${plugin.wrapperPath}`);
+  console.log('  unsupported surfaces: OpenCode tools that do not emit tool.execute.* events are not covered');
+  console.log(`  strict required: ${hookMode === 'strict' ? 'yes' : 'no'}`);
+}
+
+function runOpenCodeDoctor(options, layout) {
+  const plugin = assertOpenCodePlugin(layout, options.hookMode);
+  const pathEnv = { PATH: process.env.PATH || '' };
+  if (options.coverage) {
+    printOpenCodeCoverage(plugin, options.hookMode);
+  }
+  const shellCommand = hookCommandParts(plugin.wrapperPath, options.hookMode, CLEAN_ROOM_HOOKS[0].checks);
+  const readCommand = hookCommandParts(plugin.wrapperPath, options.hookMode, CLEAN_ROOM_HOOKS[1].checks);
+  const writeCommand = hookCommandParts(plugin.wrapperPath, options.hookMode, CLEAN_ROOM_HOOKS[2].checks);
+  const postWriteCommand = hookCommandParts(plugin.wrapperPath, options.hookMode, CLEAN_ROOM_HOOKS[3].checks);
+
+  if (options.hookMode === 'safe') {
+    const safe = runHookCommandRaw(shellCommand, '', pathEnv, layout.targetRoot);
+    if (safe.status !== 0) {
+      throw new Error(`safe OpenCode hook did not no-op without clean-room env: ${describeSpawn(safe)}`);
+    }
+    assertHookFails(
+      shellCommand,
+      {},
+      { ...pathEnv, CLEAN_ROOM_HOOK_ENFORCE: '1' },
+      layout.targetRoot,
+      'enforced safe OpenCode',
+      /environment check failed/
+    );
+  } else {
+    assertHookFails(shellCommand, {}, pathEnv, layout.targetRoot, 'strict OpenCode', /environment check failed/);
+  }
+
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'clean-room-doctor-'));
+  try {
+    const cleanEnv = { ...pathEnv, ...smokeEnv(layout, tmpRoot, 'clean-architect') };
+    const qaEnv = {
+      ...pathEnv,
+      ...smokeEnv(layout, tmpRoot, 'clean-qa-editor'),
+      CLEAN_ROOM_ALLOW_AGENT3_SHELL: '1',
+    };
+    const sourceFile = path.join(cleanEnv.CLEAN_ROOM_SOURCE_ROOTS, 'secret.txt');
+    const cleanBadJson = path.join(cleanEnv.CLEAN_ROOM_CLEAN_ROOTS, 'behavior-spec.json');
+    fs.writeFileSync(sourceFile, 'secret\n');
+    fs.writeFileSync(cleanBadJson, '{\n');
+
+    assertHookFails(readCommand, {
+      tool_name: 'read',
+      tool: 'read',
+      tool_input: { filePath: sourceFile },
+      cwd: layout.targetRoot,
+    }, cleanEnv, layout.targetRoot, 'OpenCode read', /source-root/);
+    assertHookFails(writeCommand, {
+      tool_name: 'write',
+      tool: 'write',
+      tool_input: { filePath: sourceFile },
+      cwd: layout.targetRoot,
+    }, cleanEnv, layout.targetRoot, 'OpenCode write', /source-root/);
+    assertHookFails(shellCommand, {
+      tool_name: 'bash',
+      tool: 'bash',
+      tool_input: { cwd: qaEnv.CLEAN_ROOM_IMPLEMENTATION_ROOTS, command: `cat ${sourceFile}` },
+      cwd: qaEnv.CLEAN_ROOM_IMPLEMENTATION_ROOTS,
+    }, qaEnv, layout.targetRoot, 'OpenCode shell', /policy denied shell tool use|source-root/);
+    assertHookFails(postWriteCommand, {
+      tool_name: 'write',
+      tool: 'write',
+      tool_input: { filePath: cleanBadJson },
+      cwd: layout.targetRoot,
+    }, cleanEnv, layout.targetRoot, 'OpenCode post-write', /JSON parse failed/);
+  } finally {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+
+  console.log(`clean-room doctor passed for ${options.runtime}`);
+  console.log(`  plugin: ${plugin.pluginPath}`);
+  console.log('  managed plugin hooks: tool.execute.before, tool.execute.after');
+  console.log(`  mode: ${options.hookMode}`);
+  return { pluginPath: plugin.pluginPath, managedHooks: 2 };
+}
+
 function runDoctor(argv) {
   const options = parseDoctorArgs(argv);
   const layout = resolveRuntimeLayout(options.runtime, options.scope, { configDir: options.configDir });
+  if (layout.hookRegistration === 'local-plugin') {
+    return runOpenCodeDoctor(options, layout);
+  }
   const configPath = configPathForRuntime(layout.runtime, layout.targetRoot);
   if (!configPath) {
     throw new Error(`doctor is not supported for ${layout.runtime}`);

package/lib/hooks.cjs

@@ -7,6 +7,7 @@ const { readJsonFile, writeJsonFile } = require('./fs-utils.cjs');
 
 const HOOK_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart']);
 const CLEAN_ROOM_HOOK_TIMEOUT_SECONDS = 30;
+const OPENCODE_PLUGIN_MARKER = 'clean-room-skill-opencode-plugin-v1';
 
 const CLEAN_ROOM_HOOKS = [
   {
@@ -163,6 +164,20 @@ function hasManagedHookEntries(configPath) {
   return false;
 }
 
+function pluginPathForRuntime(runtime, targetRoot) {
+  if (runtime === 'opencode') {
+    return path.join(targetRoot, 'plugins', 'clean-room.ts');
+  }
+  return null;
+}
+
+function hasManagedOpenCodePlugin(pluginPath) {
+  if (!pluginPath || !fs.existsSync(pluginPath)) {
+    return false;
+  }
+  return fs.readFileSync(pluginPath, 'utf8').includes(OPENCODE_PLUGIN_MARKER);
+}
+
 function mergedHookConfig(configPath, entries) {
   const original = readJsonFile(configPath, {});
   if (!original || typeof original !== 'object' || Array.isArray(original)) {
@@ -231,6 +246,9 @@ module.exports = {
   CLEAN_ROOM_HOOK_TIMEOUT_SECONDS,
   configPathForRuntime,
   hasManagedHookEntries,
+  hasManagedOpenCodePlugin,
+  OPENCODE_PLUGIN_MARKER,
+  pluginPathForRuntime,
   removeHookEntries,
   mergeHookEntries,
   shellQuote,

package/lib/install-artifacts.cjs

@@ -7,6 +7,7 @@ const {
   listFiles,
   readJsonFile,
 } = require('./fs-utils.cjs');
+const { OPENCODE_PLUGIN_MARKER } = require('./hooks.cjs');
 const { resolveRuntimeLayout } = require('./runtime-layout.cjs');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
@@ -104,6 +105,168 @@ function generatePluginManifest() {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
+function generateOpenCodePlugin(layout, hookMode) {
+  const wrapperPath = path.join(layout.targetRoot, 'hooks', 'clean-room', 'clean-room-hook.py');
+  const mode = hookMode === 'strict' ? 'strict' : 'safe';
+  return `import { spawn } from "node:child_process"
+
+const CLEAN_ROOM_OPENCODE_PLUGIN_MARKER = ${JSON.stringify(OPENCODE_PLUGIN_MARKER)}
+const CLEAN_ROOM_HOOK_MODE = ${JSON.stringify(mode)}
+const CLEAN_ROOM_HOOK_WRAPPER = ${JSON.stringify(wrapperPath)}
+const CLEAN_ROOM_HOOK_PYTHON = process.env.CLEAN_ROOM_HOOK_PYTHON || "python3"
+const CLEAN_ROOM_HOOK_TIMEOUT_MS = 30_000
+const MAX_HOOK_OUTPUT_CHARS = 256 * 1024
+
+const CHECKS = {
+  shell: ["require-clean-room-env.py", "deny-clean-room-shell.py"],
+  read: ["require-clean-room-env.py", "deny-clean-source-read.py"],
+  write: ["require-clean-room-env.py", "deny-contaminated-clean-write.py"],
+  postWrite: [
+    "require-clean-room-env.py",
+    "check-artifact-leakage.py",
+    "validate-json-schema.py",
+    "validate-handoff-package.py",
+  ],
+}
+
+const SHELL_TOOLS = new Set([
+  "bash",
+  "shell",
+  "powershell",
+  "terminal",
+  "exec_command",
+  "shell_command",
+  "writestdin",
+  "write_stdin",
+])
+
+const READ_TOOLS = new Set([
+  "read",
+  "glob",
+  "grep",
+  "list",
+  "ls",
+  "lsp",
+  "notebookread",
+  "viewimage",
+  "view_image",
+])
+
+const DIRECTORY_READ_TOOLS = new Set(["glob", "grep", "list", "ls", "lsp"])
+const WRITE_TOOLS = new Set(["write", "edit", "multiedit", "notebookedit", "applypatch", "apply_patch"])
+const PATH_KEYS = ["file_path", "filePath", "path", "notebook_path", "notebookPath"]
+
+function normalizeTool(tool) {
+  return String(tool || "").toLowerCase().replace(/[^a-z0-9_]/g, "")
+}
+
+function objectArgs(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {}
+  return { ...value }
+}
+
+function cwdFor(args, directory, worktree) {
+  if (typeof args.cwd === "string" && args.cwd) return args.cwd
+  if (typeof directory === "string" && directory) return directory
+  if (typeof worktree === "string" && worktree) return worktree
+  return process.cwd()
+}
+
+function withDirectoryFallbackPath(tool, args, cwd) {
+  if (!DIRECTORY_READ_TOOLS.has(tool)) return args
+  if (PATH_KEYS.some((key) => typeof args[key] === "string" && args[key])) return args
+  return { ...args, path: cwd }
+}
+
+function hookPayload(input, args, directory, worktree) {
+  const tool = input?.tool
+  const normalized = normalizeTool(tool)
+  const cwd = cwdFor(args, directory, worktree)
+  return {
+    tool_name: tool,
+    tool,
+    tool_input: withDirectoryFallbackPath(normalized, args, cwd),
+    cwd,
+    opencode: {
+      sessionID: input?.sessionID,
+      callID: input?.callID,
+    },
+  }
+}
+
+function hookArgs(checks) {
+  const args = [CLEAN_ROOM_HOOK_WRAPPER, "--mode", CLEAN_ROOM_HOOK_MODE]
+  for (const check of checks) args.push("--check", check)
+  return args
+}
+
+function appendBounded(current, chunk) {
+  if (current.length >= MAX_HOOK_OUTPUT_CHARS) return current
+  return (current + String(chunk)).slice(0, MAX_HOOK_OUTPUT_CHARS)
+}
+
+function runHook(label, checks, payload) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(CLEAN_ROOM_HOOK_PYTHON, hookArgs(checks), {
+      env: process.env,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+    let stdout = ""
+    let stderr = ""
+    let settled = false
+    const timer = setTimeout(() => {
+      settled = true
+      child.kill("SIGTERM")
+      reject(new Error(\`clean-room \${label} hook timed out after \${CLEAN_ROOM_HOOK_TIMEOUT_MS}ms\`))
+    }, CLEAN_ROOM_HOOK_TIMEOUT_MS)
+    child.stdout.on("data", (chunk) => {
+      stdout = appendBounded(stdout, chunk)
+    })
+    child.stderr.on("data", (chunk) => {
+      stderr = appendBounded(stderr, chunk)
+    })
+    child.on("error", (error) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(error)
+    })
+    child.on("close", (status, signal) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      if (status === 0) {
+        resolve()
+        return
+      }
+      const detail = (stderr || stdout || \`status \${status}\${signal ? \`, signal \${signal}\` : ""}\`).trim()
+      reject(new Error(\`clean-room \${label} hook denied tool use: \${detail}\`))
+    })
+    child.stdin.end(JSON.stringify(payload))
+  })
+}
+
+export const CleanRoomPlugin = async ({ directory, worktree }) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      const tool = normalizeTool(input?.tool)
+      const payload = hookPayload(input, objectArgs(output?.args), directory, worktree)
+      if (SHELL_TOOLS.has(tool)) await runHook("shell", CHECKS.shell, payload)
+      if (READ_TOOLS.has(tool)) await runHook("read", CHECKS.read, payload)
+      if (WRITE_TOOLS.has(tool)) await runHook("write", CHECKS.write, payload)
+    },
+    "tool.execute.after": async (input) => {
+      const tool = normalizeTool(input?.tool)
+      if (!WRITE_TOOLS.has(tool)) return
+      const payload = hookPayload(input, objectArgs(input?.args), directory, worktree)
+      await runHook("post-write", CHECKS.postWrite, payload)
+    },
+  }
+}
+`;
+}
+
 function addCommandWrappers(desired, artifact) {
   const skillsRoot = path.join(PACKAGE_ROOT, artifact.source);
   const entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
@@ -117,7 +280,15 @@ function addCommandWrappers(desired, artifact) {
   }
 }
 
-function addArtifact(desired, artifact) {
+function shouldInstallArtifact(artifact, hookMode) {
+  if (!Array.isArray(artifact.hookModes)) return true;
+  return artifact.hookModes.includes(hookMode);
+}
+
+function addArtifact(desired, artifact, layout, hookMode) {
+  if (!shouldInstallArtifact(artifact, hookMode)) {
+    return;
+  }
   if (artifact.kind === 'skills' || artifact.kind === 'agents') {
     addTree(desired, artifact.source, artifact.destSubpath);
     return;
@@ -136,6 +307,10 @@ function addArtifact(desired, artifact) {
     desired.set(artifact.destSubpath, Buffer.from(generatePluginManifest(), 'utf8'));
     return;
   }
+  if (artifact.kind === 'opencode-plugin') {
+    desired.set(artifact.destSubpath, Buffer.from(generateOpenCodePlugin(layout, hookMode), 'utf8'));
+    return;
+  }
   throw new Error(`unsupported artifact kind: ${artifact.kind}`);
 }
 
@@ -147,12 +322,11 @@ function layoutFromInput(runtimeOrLayout, scope, configDir) {
 }
 
 function buildDesiredFiles(runtimeOrLayout, hookMode, scope = 'global', configDir = null) {
-  // Retained for callers that still pass the install hook mode.
-  void hookMode;
+  hookMode = hookMode || 'safe';
   const layout = layoutFromInput(runtimeOrLayout, scope, configDir);
   const desired = new Map();
   for (const artifact of layout.artifacts) {
-    addArtifact(desired, artifact);
+    addArtifact(desired, artifact, layout, hookMode);
   }
   return desired;
 }