clean-room-skill 0.1.12 → 0.1.13

package/docs/ARCHITECTURE.md

@@ -288,7 +288,7 @@ Note: Even though clean and source-denied roles (such as Agent 1.5, 2, 3, and 4)
 
 ## Guardrails and Hooks
 
-The architecture relies on agent/tool hook scaffolding located in `hooks/` to enforce boundary rules dynamically during agent sessions. Use installer-generated Codex or Claude hook configs with absolute wrapper paths. Static cwd-relative plugin hook declarations are not treated as an enforcement boundary. Use strict hooks for dedicated Codex or Claude clean-room homes; safe hooks are compatibility-only between runs and begin enforcing when init/onboarding launches role sessions with clean-room environment variables.
+The architecture relies on agent/tool hook scaffolding located in `hooks/` to enforce boundary rules dynamically during agent sessions. Use installer-generated Codex or Claude hook configs with absolute wrapper paths, or the generated OpenCode local plugin bridge. Static cwd-relative plugin hook declarations are not treated as an enforcement boundary. Use strict hooks for dedicated Codex, Claude, or OpenCode clean-room homes; safe hooks are compatibility-only between runs and begin enforcing when init/onboarding launches role sessions with clean-room environment variables.
 
 Matcher coverage depends on the host runtime emitting hook events for the tool invocation. Hosts that do not emit a pre/post tool event for a file, terminal, or resource tool are not protected by adding that tool name to the generated hook config. Run `clean-room-skill doctor --runtime codex --hooks=strict --coverage` or the Claude equivalent after install.
 

package/docs/HOOKS.md

@@ -6,7 +6,7 @@ The hooks are engineering guardrails. They reduce accidental cross-domain reads
 
 ## Install Locations
 
-The installer copies the Python hook files for every supported runtime layout. Runtime hook registration is verified only for Codex and Claude Code.
+The installer copies the Python hook files for every supported runtime layout. Runtime hook registration is verified for Codex, Claude Code, and OpenCode.
 
 | Runtime | Hook files copied to | Active hook config |
 | --- | --- | --- |
@@ -14,7 +14,7 @@ The installer copies the Python hook files for every supported runtime layout. R
 | Claude Code | `<targetRoot>/hooks/clean-room/*.py` | `<targetRoot>/settings.json` |
 | Antigravity | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Gemini CLI | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
-| OpenCode | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
+| OpenCode | `<targetRoot>/hooks/clean-room/*.py` | `<targetRoot>/plugins/clean-room.ts` |
 | Kilo | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | Cursor | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
 | GitHub Copilot | `<targetRoot>/hooks/clean-room/*.py` | Unsupported, copy only |
@@ -31,8 +31,8 @@ Codex uses `CODEX_HOME` or `~/.codex` for global installs. Claude Code uses `CLA
 
 | Mode | Behavior |
 | --- | --- |
-| `safe` | Default. Registers hooks for Codex or Claude, but `clean-room-hook.py` no-ops until a clean-room role environment is present or `CLEAN_ROOM_HOOK_ENFORCE` is truthy. |
-| `strict` | Registers hooks for Codex or Claude and fails closed even without clean-room role environment. Use only in dedicated clean-room runtime homes. |
+| `safe` | Default. Registers hooks for Codex, Claude, or OpenCode, but `clean-room-hook.py` no-ops until a clean-room role environment is present or `CLEAN_ROOM_HOOK_ENFORCE` is truthy. |
+| `strict` | Registers hooks for Codex, Claude, or OpenCode and fails closed even without clean-room role environment. Use only in dedicated clean-room runtime homes. |
 | `copy-only` | Copies hook files without modifying runtime hook config. This is also the effective behavior for runtimes without verified hook registration support. |
 
 `--no-hooks` is an alias for `--hooks=copy-only`.
@@ -41,6 +41,8 @@ Codex uses `CODEX_HOME` or `~/.codex` for global installs. Claude Code uses `CLA
 
 When hook mode is `safe` or `strict`, the installer registers four managed hook entries for Codex and Claude. Each entry invokes the installed `clean-room-hook.py` wrapper with an absolute Python path, an absolute wrapper path, the requested hook mode, and one or more `--check` scripts.
 
+For OpenCode, the installer writes a generated local plugin at `<targetRoot>/plugins/clean-room.ts`. OpenCode auto-loads that plugin from its config directory. The plugin subscribes to `tool.execute.before` and `tool.execute.after`, translates OpenCode tool payloads into the existing clean-room hook payload shape, and invokes the installed Python wrapper with `shell: false`. `copy-only` omits this plugin.
+
 | Event | Matcher | Checks |
 | --- | --- | --- |
 | `PreToolUse` | <code>Bash&#124;Shell&#124;PowerShell&#124;Monitor&#124;exec_command&#124;shell_command&#124;write_stdin</code> | `require-clean-room-env.py`, `deny-clean-room-shell.py` |
@@ -205,26 +207,28 @@ The hook policy is deny-by-default during active clean-room role sessions.
 
 ## Verification
 
-Use `doctor` after installing Codex or Claude hooks:
+Use `doctor` after installing Codex, Claude, or OpenCode hooks:
 
 ```bash
 clean-room-skill doctor --runtime codex --hooks=safe
 clean-room-skill doctor --runtime codex --hooks=strict
 clean-room-skill doctor --runtime codex --hooks=strict --coverage
 clean-room-skill doctor --runtime claude --hooks=strict --coverage
+clean-room-skill doctor --runtime opencode --hooks=strict --coverage
 ```
 
 Add `--config-dir <path>` when checking a non-default runtime config root.
 
 `doctor` verifies that:
 
-- The hook config exists.
-- Exactly four managed clean-room hook entries are present.
-- Managed commands use absolute Python and wrapper paths.
+- The hook config or OpenCode local plugin exists.
+- Exactly four managed clean-room hook entries are present for Codex and Claude.
+- Managed Codex and Claude commands use absolute Python and wrapper paths.
+- The OpenCode plugin declares `tool.execute.before`, `tool.execute.after`, an absolute wrapper path, and `shell: false`.
 - The requested safe or strict mode is configured.
 - Safe mode no-ops without clean-room environment.
 - Strict mode and enforced safe mode fail without required environment.
 - Smoke payloads fail for source reads, source writes, shell bypasses, and malformed post-write JSON.
-- `--coverage` prints matcher and check coverage for the generated entries.
+- `--coverage` prints matcher and check coverage for generated hook config entries or OpenCode plugin coverage.
 
-`doctor` is a smoke test. It does not prove host event coverage, legal sufficiency, or full runtime isolation.
+`doctor` is a smoke test. It does not prove host event coverage, legal sufficiency, or full runtime isolation. For OpenCode, it verifies the generated plugin bridge and Python guardrail checks, not every OpenCode tool surface.

package/docs/REFERENCE.md

@@ -64,12 +64,12 @@ Verified:
 
 - Codex
 - Claude Code
+- OpenCode
 
 Layout-only or experimental:
 
 - Antigravity
 - Gemini CLI
-- OpenCode
 - Kilo
 - Cursor
 - GitHub Copilot
@@ -80,7 +80,18 @@ Layout-only or experimental:
 - Hermes Agent
 - CodeBuddy
 
-Layout-only installs write files to expected runtime locations, but this repository does not verify that those hosts load the files or emit all hook events needed for clean-room enforcement.
+Layout-only installs write files to expected runtime locations, but this repository does not verify that those hosts load the files or emit all hook events needed for clean-room enforcement. OpenCode installs are verified through a generated local plugin bridge at `plugins/clean-room.ts`; `doctor` verifies that bridge and the Python guardrails, not every OpenCode tool surface.
+
+### Pi Package Compatibility
+
+Pi can install this package and load the bundled skills from the package metadata:
+
+```bash
+pi install npm:clean-room-skill@latest
+pi install https://github.com/whit3rabbit/clean-room-skill
+```
+
+Pi invokes skills as `/skill:<name>`. Use `/skill:init` for the setup pass, `/skill:clean-room` for the startup wizard, `/skill:attended` for attended controller mode, and `/skill:unattended` for bounded unattended mode. Pi support is package compatibility only: it does not add a `--pi` installer target, does not participate in `--all`, and does not register clean-room hooks. Clean-room safety still depends on role separation, path isolation, schema validation, and supported hook runtimes.
 
 Global install roots:
 
@@ -103,12 +114,20 @@ Global install roots:
 
 Local installs use each runtime's project config directory. Antigravity local installs write `.agents/plugins/clean-room/`.
 
+## Agent Metadata Compatibility
+
+Runtime agent metadata is intentionally runtime-specific. Claude Code Markdown agents support documented `model`, `effort`, `color`, and optional `memory` frontmatter. Clean-room role agents use `model`, `effort`, and `color` only. They do not use persistent `memory`, because clean-room state must come from durable artifacts, role-session briefs, and fresh role sessions rather than runtime recall.
+
+Codex TOML agents support documented session config fields such as `model`, `model_reasoning_effort`, `developer_instructions`, `sandbox_mode`, `mcp_servers`, and `skills.config`. Do not copy Claude aliases such as `sonnet` or `opus`, Claude `color`, or Claude `memory` fields into Codex TOML templates.
+
+Codex hooks support `updatedInput`, but clean-room hook enforcement should stay fail-closed through exit status and explicit deny decisions. Do not rewrite clean-room tool calls in hooks; command mutation makes boundary behavior harder to review and test.
+
 ## Hook Modes And Doctor
 
 Hook modes:
 
 - `safe`: default. Copies hooks and registers a wrapper that no-ops until role sessions provide clean-room environment variables. `CLEAN_ROOM_HOOK_ENFORCE=1` remains available for explicit smoke tests.
-- `strict`: fail-closed mode for dedicated Codex or Claude clean-room homes.
+- `strict`: fail-closed mode for dedicated Codex, Claude, or OpenCode clean-room homes.
 - `copy-only`: copies hook files without runtime hook registration.
 
 Smoke test generated hook registration:
@@ -117,11 +136,12 @@ Smoke test generated hook registration:
 clean-room-skill doctor --runtime codex --hooks=safe
 clean-room-skill doctor --runtime codex --hooks=strict
 clean-room-skill doctor --runtime codex --hooks=strict --coverage
+clean-room-skill doctor --runtime opencode --hooks=strict --coverage
 ```
 
 Use `--runtime claude` for Claude Code, and add `--config-dir <path>` when testing an alternate config root.
 
-`doctor` checks that Codex or Claude hook config exists, contains generated clean-room hooks, uses absolute wrapper paths, uses the requested safe or strict mode, and that smoke payloads fail for missing environment, source reads, source writes, shell use, and malformed post-write JSON. Safe mode also verifies no-op behavior without clean-room env.
+`doctor` checks that Codex or Claude hook config exists, or that the OpenCode local plugin exists. It verifies generated clean-room hooks or plugin wiring, absolute wrapper paths, the requested safe or strict mode, and smoke payload failures for missing environment, source reads, source writes, shell use, and malformed post-write JSON. Safe mode also verifies no-op behavior without clean-room env.
 
 It does not prove legal sufficiency, full runtime hook event coverage, host-side feature enablement, or full JSON Schema conformance.
 

package/examples/codex/.codex/agents/clean-architect.toml

@@ -1,10 +1,10 @@
 name = "clean-architect"
 description = "Plans clean implementation from approved clean behavior specs and the clean destination foundation."
 sandbox_mode = "workspace-write"
-model_reasoning_effort = "medium"
-enabled_skills = ["clean-room"]
+model = "gpt-5.5"
+model_reasoning_effort = "high"
 
-instructions = """
+developer_instructions = """
 Act as Agent 2 in the clean-room pipeline.
 Run only from the clean workspace.
 Before tool use, require CLEAN_ROOM_ROLE=clean-architect, CLEAN_ROOM_CLEAN_ROOTS, CLEAN_ROOM_IMPLEMENTATION_ROOTS, CLEAN_ROOM_SOURCE_ROOTS, CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS, CLEAN_ROOM_ALLOWED_READ_ROOTS, and CLEAN_ROOM_SCHEMA_DIR.

package/examples/codex/.codex/agents/clean-polish-reviewer.toml

@@ -1,10 +1,10 @@
 name = "clean-polish-reviewer"
 description = "Performs final clean code polish, repo hygiene, verification review, and constrained implementation-root commit."
 sandbox_mode = "workspace-write"
+model = "gpt-5.4-mini"
 model_reasoning_effort = "high"
-enabled_skills = ["clean-room"]
 
-instructions = """
+developer_instructions = """
 Act as Agent 4 in the clean-room pipeline.
 Run only in the clean domain after Agent 3 has produced terminal implementation and QC reports.
 Before tool use, require CLEAN_ROOM_ROLE=clean-polish-reviewer, CLEAN_ROOM_CLEAN_ROOTS, CLEAN_ROOM_IMPLEMENTATION_ROOTS, CLEAN_ROOM_SOURCE_ROOTS, CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS, CLEAN_ROOM_ALLOWED_READ_ROOTS, and CLEAN_ROOM_SCHEMA_DIR.

package/examples/codex/.codex/agents/clean-qa-editor.toml

@@ -1,10 +1,10 @@
 name = "clean-qa-editor"
 description = "Implements the clean plan, verifies clean destination code, and emits one terminal report for Agent 0."
 sandbox_mode = "workspace-write"
+model = "gpt-5.4-mini"
 model_reasoning_effort = "high"
-enabled_skills = ["clean-room"]
 
-instructions = """
+developer_instructions = """
 Act as Agent 3 in the clean-room pipeline.
 Run only in the clean domain.
 Before tool use, require CLEAN_ROOM_ROLE=clean-qa-editor, CLEAN_ROOM_CLEAN_ROOTS, CLEAN_ROOM_IMPLEMENTATION_ROOTS, CLEAN_ROOM_SOURCE_ROOTS, CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS, CLEAN_ROOM_ALLOWED_READ_ROOTS, and CLEAN_ROOM_SCHEMA_DIR.

package/examples/codex/.codex/agents/contaminated-handoff-sanitizer.toml

@@ -1,10 +1,10 @@
 name = "contaminated-handoff-sanitizer"
 description = "Reviews Agent 1 draft specs from a fresh source-denied contaminated context and approves only scrubbed handoff artifacts."
 sandbox_mode = "workspace-write"
+model = "gpt-5.4-mini"
 model_reasoning_effort = "high"
-enabled_skills = ["clean-room"]
 
-instructions = """
+developer_instructions = """
 Act as Agent 1.5 in the clean-room pipeline.
 Operate in the contaminated domain, but without source access or Agent 1 source-reading chat history.
 Before tool use, require CLEAN_ROOM_ROLE=contaminated-handoff-sanitizer, CLEAN_ROOM_CONTAMINATED_ARTIFACT_ROOTS, CLEAN_ROOM_SOURCE_ROOTS, CLEAN_ROOM_CLEAN_ROOTS, CLEAN_ROOM_IMPLEMENTATION_ROOTS, CLEAN_ROOM_ALLOWED_READ_ROOTS, and CLEAN_ROOM_SCHEMA_DIR.

package/examples/codex/.codex/agents/contaminated-manager-verifier.toml

@@ -1,10 +1,10 @@
 name = "contaminated-manager-verifier"
 description = "Consumes contaminated source indexes, tracks source coverage, and emits only abstract clean-room delta tickets."
 sandbox_mode = "workspace-write"
-model_reasoning_effort = "medium"
-enabled_skills = ["clean-room"]
+model = "gpt-5.5"
+model_reasoning_effort = "high"
 
-instructions = """
+developer_instructions = """
 Act as Agent 0 in the clean-room pipeline.
 Operate only in the contaminated domain.
 Read authorized source and contaminated ledgers as needed.

package/examples/codex/.codex/agents/contaminated-source-analyst.toml

@@ -1,10 +1,10 @@
 name = "contaminated-source-analyst"
 description = "Reads authorized source and writes neutral draft task slices plus behavior specs with evidence references."
 sandbox_mode = "workspace-write"
+model = "gpt-5.4-mini"
 model_reasoning_effort = "medium"
-enabled_skills = ["clean-room"]
 
-instructions = """
+developer_instructions = """
 Act as Agent 1 in the clean-room pipeline.
 Operate only in the contaminated domain.
 Before reading source, require active task-manifest.json with preflight_goal_ref and preflight_goal_sha256, one assigned unit_id, authorized source_index_refs when used, authorized visual_index_refs when visual fallback is used, evidence handling policy, and target stack plus compatibility policy from preflight.

package/lib/bootstrap.cjs

@@ -408,7 +408,11 @@ function printInitResult(options) {
   console.log('    install safe hooks: npx clean-room-skill@latest --claude --global --hooks=safe --yes');
   console.log('    start in Claude Code: /clean-room:init, then /clean-room or /clean-room:attended');
   console.log('    uninstall runtime install: npx clean-room-skill@latest --claude --global --uninstall --yes');
-  console.log('  strict hooks are only for dedicated clean-room Codex or Claude homes');
+  console.log('  Pi:');
+  console.log('    install package skills: pi install npm:clean-room-skill@latest');
+  console.log('    start in Pi: /skill:init, then /skill:clean-room or /skill:attended');
+  console.log('    Pi package install does not register clean-room hooks');
+  console.log('  strict hooks are only for dedicated clean-room Codex, Claude, or OpenCode homes');
 }
 
 function runInit(argv, context = {}) {

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,