clean-room-skill 0.1.14 → 0.1.15

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "clean-room",
       "source": "./",
       "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-      "version": "0.1.14",
+      "version": "0.1.15",
       "author": {
         "name": "whit3rabbit"
       },

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "clean-room",
   "displayName": "Clean Room",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "author": {
     "name": "whit3rabbit"

package/docs/ARCHITECTURE.md

@@ -250,14 +250,14 @@ The outer loop owns spec development: scope, behavior specs, acceptance criteria
 
 Agent 3's terminal report is not enough to return. If configured, Agent 4 must produce a passing `polish-report.json`. Agent 0 must then consume the terminal clean reports, verify contaminated-side coverage, and write `clean-room-result.json`.
 
-`clean-room-skill run` is the executable v1 inner-loop runner. It requires preflight refs, the required handoff sequence, unattended `controller_policy`, schema-valid `loop_context`, and a user-supplied agent command adapter. It does not automate outer spec development. The runner:
+`clean-room-skill run` is the executable v1 inner-loop runner. It requires preflight refs, the required handoff sequence, unattended `controller_policy`, schema-valid `loop_context`, and either a user-supplied agent command adapter or the built-in Claude Code agent runtime. It does not automate outer spec development. The runner:
 
 *   Locks the contaminated artifact root with `.clean-room-run.lock`.
 *   Reloads durable artifacts before each iteration.
 *   Selects at most one pending or gap unit inside `loop_context.approved_scope_refs`.
 *   Requires exactly one `unit_kind: "foundation"` unit, named by `loop_context.foundation_unit_ref`; behavior units cannot run or complete until that foundation unit is covered.
 *   Spawns configured role commands with `shell: false`, bounded output, and bounded timeout.
-*   In strict context-management mode, requires each configured stage to provide `context.fresh_session: true` and `context.brief_path`, then validates the session brief before spawn.
+*   In strict context-management mode, requires each configured worker stage after `contaminated-manager-prepare` to provide `context.fresh_session: true` and `context.brief_path`, then validates the session brief before spawn.
 *   Supports the optional `clean-polish-review` phase between `clean-implement-qc` and `contaminated-coverage-verify`.
 *   Validates schema, leakage, and handoff integrity before advancing state.
 *   Rejects `covered` coverage-ledger units that still have unresolved high-priority `discovery_leads`.

package/docs/REFERENCE.md

@@ -214,7 +214,7 @@ Usage:
 ```bash
 npx clean-room-skill@latest run \
   --task-manifest ~/Documents/CleanRoom/task-1234abcd/contaminated/task-manifest.json \
-  --agent-commands ./agent-commands.json \
+  --agent-runtime claude \
   --max-iterations 3
 ```
 
@@ -223,7 +223,9 @@ Options:
 | Option | Description |
 | --- | --- |
 | `--task-manifest <path>` | Required path to `task-manifest.json`. |
-| `--agent-commands <path>` | Required role command adapter JSON unless `--dry-run` is set. |
+| `--agent-commands <path>` | Role command adapter JSON unless `--agent-runtime` or `--dry-run` is set. |
+| `--agent-runtime claude` | Use the built-in Claude Code adapter to launch plugin role agents. Mutually exclusive with `--agent-commands`. |
+| `--agent-config-dir <path>` | Claude config directory for `--agent-runtime claude`; defaults to `CLAUDE_CONFIG_DIR` or `~/.claude`. |
 | `--max-iterations <n>` | May only lower the manifest and `loop_context` cap. |
 | `--once` | Run at most one inner-loop iteration. |
 | `--dry-run` | Validate and print the selected unit without writing or spawning agents. |
@@ -259,9 +261,9 @@ Minimal agent command adapter shape for advisory or disabled context management:
 }
 ```
 
-Supported phases are `contaminated-analysis`, `sanitize-handoff`, `clean-plan`, `clean-implement-qc`, optional `clean-polish-review`, and `contaminated-coverage-verify`. The coverage verification phase is required. When present, `clean-polish-review` must run after `clean-implement-qc` and before `contaminated-coverage-verify`.
+Supported phases are `contaminated-manager-prepare`, `contaminated-analysis`, `sanitize-handoff`, `clean-plan`, `clean-implement-qc`, optional `clean-polish-review`, and `contaminated-coverage-verify`. The coverage verification phase is required. The built-in Claude adapter includes `contaminated-manager-prepare` so Agent 0 can prepare controller state before downstream role agents run. When present, `clean-polish-review` must run after `clean-implement-qc` and before `contaminated-coverage-verify`.
 
-When `task-manifest.json` sets `context_management.mode` to `role-session-briefs` and `context_management.enforcement` to `strict`, every configured stage must include `context.fresh_session: true` and `context.brief_path`. The runner validates the brief before spawn, passes only the brief path plus environment facts in the stage prompt, and records the brief ref/hash in `controller-run-ledger.json`.
+When `task-manifest.json` sets `context_management.mode` to `role-session-briefs` and `context_management.enforcement` to `strict`, every configured worker stage after `contaminated-manager-prepare` must include `context.fresh_session: true` and `context.brief_path`. The runner validates the brief before spawn, passes only the brief path plus environment facts in the stage prompt, and records the brief ref/hash in `controller-run-ledger.json`.
 
 Strict context-management adapter example:
 

package/lib/claude-agents.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { readJsonFile } = require('./fs-utils.cjs');
+
+const CLAUDE_AGENT_FILES = Object.freeze([
+  'clean-architect.md',
+  'clean-implementer-verifier-shell.md',
+  'clean-polish-reviewer.md',
+  'clean-qa-editor.md',
+  'contaminated-handoff-sanitizer.md',
+  'contaminated-manager-verifier.md',
+  'contaminated-source-analyst.md',
+]);
+
+function packageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function localClaudePluginDir() {
+  return packageRoot();
+}
+
+function defaultClaudeConfigDir(env = process.env) {
+  if (env.CLAUDE_CONFIG_DIR) {
+    return path.resolve(expandTilde(env.CLAUDE_CONFIG_DIR));
+  }
+  return path.join(os.homedir(), '.claude');
+}
+
+function expandTilde(value) {
+  if (value === '~') return os.homedir();
+  if (typeof value === 'string' && value.startsWith('~/')) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function claudePluginDirFromInstallManifest(configDir) {
+  const manifestPath = path.join(configDir, 'clean-room-install-manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  const manifest = readJsonFile(manifestPath, null);
+  const installPath = manifest?.claude_plugin?.install_path;
+  return typeof installPath === 'string' && installPath !== '' ? path.resolve(installPath) : null;
+}
+
+function claudePluginCandidates(configDir, options = {}) {
+  const candidates = [];
+  const add = (label, pluginDir) => {
+    if (typeof pluginDir !== 'string' || pluginDir === '') return;
+    const resolved = path.resolve(pluginDir);
+    if (candidates.some((candidate) => candidate.pluginDir === resolved)) return;
+    candidates.push({ label, pluginDir: resolved });
+  };
+
+  if (options.pluginDir) {
+    add('explicit', options.pluginDir);
+  }
+  if (configDir) {
+    add('installed-plugin', claudePluginDirFromInstallManifest(path.resolve(configDir)));
+  }
+  if (options.includePackageFallback !== false) {
+    add('package-plugin', localClaudePluginDir());
+  }
+  if (configDir) {
+    add('local-claude-agents', path.resolve(configDir));
+  }
+  return candidates;
+}
+
+function claudeAgentStatus(configDir, options = {}) {
+  const candidates = claudePluginCandidates(configDir, options);
+  for (const candidate of candidates) {
+    const agentDir = path.join(candidate.pluginDir, 'agents');
+    const missing = missingClaudeAgentFiles(candidate.pluginDir);
+    if (missing.length === 0) {
+      return {
+        status: 'ok',
+        source: candidate.label,
+        pluginDir: candidate.pluginDir,
+        agentDir,
+        present: CLAUDE_AGENT_FILES.length,
+        missing,
+      };
+    }
+  }
+
+  const preferred = candidates[0] || { label: 'none', pluginDir: configDir ? path.resolve(configDir) : null };
+  const missing = preferred.pluginDir ? missingClaudeAgentFiles(preferred.pluginDir) : [...CLAUDE_AGENT_FILES];
+  return {
+    status: 'missing',
+    source: preferred.label,
+    pluginDir: preferred.pluginDir,
+    agentDir: preferred.pluginDir ? path.join(preferred.pluginDir, 'agents') : null,
+    present: CLAUDE_AGENT_FILES.length - missing.length,
+    missing,
+  };
+}
+
+function missingClaudeAgentFiles(pluginDir) {
+  const agentDir = path.join(pluginDir, 'agents');
+  return CLAUDE_AGENT_FILES.filter((name) => {
+    const filePath = path.join(agentDir, name);
+    try {
+      return !fs.statSync(filePath).isFile();
+    } catch {
+      return true;
+    }
+  });
+}
+
+function assertClaudeAgentsAvailable(configDir, options = {}) {
+  const status = claudeAgentStatus(configDir, options);
+  if (status.status !== 'ok') {
+    const base = status.pluginDir || String(configDir || '<unknown>');
+    throw new Error(`Claude role-agent dispatch unavailable: missing ${status.missing.join(', ')} under ${base}`);
+  }
+  return status;
+}
+
+module.exports = {
+  CLAUDE_AGENT_FILES,
+  assertClaudeAgentsAvailable,
+  claudeAgentStatus,
+  defaultClaudeConfigDir,
+  localClaudePluginDir,
+};

package/lib/doctor.cjs

@@ -6,6 +6,7 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const { readJsonFile } = require('./fs-utils.cjs');
+const { claudeAgentStatus } = require('./claude-agents.cjs');
 const {
   CLEAN_ROOM_HOOKS,
   configPathForRuntime,
@@ -397,6 +398,22 @@ function printOpenCodeCoverage(plugin, hookMode) {
   console.log(`  strict required: ${hookMode === 'strict' ? 'yes' : 'no'}`);
 }
 
+function assertClaudeAgentAvailability(layout) {
+  const status = claudeAgentStatus(layout.targetRoot, { includePackageFallback: false });
+  if (status.status !== 'ok') {
+    const base = status.pluginDir || layout.targetRoot;
+    throw new Error(`Claude role-agent dispatch unavailable: missing ${status.missing.join(', ')} under ${base}`);
+  }
+  return status;
+}
+
+function printClaudeAgentCoverage(status) {
+  console.log('clean-room Claude plugin agent coverage:');
+  console.log(`  ok             agents ${status.present}`);
+  console.log(`  source: ${status.source}`);
+  console.log(`  path: ${status.agentDir}`);
+}
+
 function runOpenCodeDoctor(options, layout) {
   const plugin = assertOpenCodePlugin(layout, options.hookMode);
   const pathEnv = { PATH: process.env.PATH || '' };
@@ -497,6 +514,10 @@ function runDoctor(argv) {
   if (options.coverage) {
     printCoverage(entries, options.hookMode);
   }
+  const claudeAgents = layout.runtime === 'claude' ? assertClaudeAgentAvailability(layout) : null;
+  if (options.coverage && claudeAgents) {
+    printClaudeAgentCoverage(claudeAgents);
+  }
   if (options.hookMode === 'strict') {
     assertStrictCoverage(entries);
   }
@@ -556,8 +577,11 @@ function runDoctor(argv) {
   console.log(`clean-room doctor passed for ${options.runtime}`);
   console.log(`  hooks config: ${configPath}`);
   console.log(`  managed hooks: ${entries.length}`);
+  if (claudeAgents) {
+    console.log(`  plugin agents: ${claudeAgents.present}`);
+  }
   console.log(`  mode: ${options.hookMode}`);
-  return { configPath, managedHooks: entries.length };
+  return { configPath, managedHooks: entries.length, pluginAgents: claudeAgents?.present || 0 };
 }
 
 module.exports = {

package/lib/install-status.cjs

@@ -2,6 +2,7 @@
 
 const fs = require('node:fs');
 
+const { claudeAgentStatus } = require('./claude-agents.cjs');
 const { assertManagedPath, fileHash } = require('./fs-utils.cjs');
 const {
   configPathForRuntime,
@@ -98,6 +99,7 @@ function collectRuntimeStatus(runtime, scope, configDir) {
     hookRegistration: layout.supportsHookRegistration ? 'none' : 'unsupported',
     updateAvailable: false,
     claudePlugin: null,
+    claudeAgents: null,
     issues: [],
   };
 
@@ -167,11 +169,18 @@ function collectRuntimeStatus(runtime, scope, configDir) {
   if (layout.supportsHookRegistration && hooksMode !== 'copy-only' && hookState !== 'present') {
     issues.push('managed hook registration missing');
   }
+  const claudeAgents = runtime === 'claude'
+    ? claudeAgentStatus(layout.targetRoot, { includePackageFallback: false })
+    : null;
+  if (claudeAgents && claudeAgents.status !== 'ok') {
+    issues.push(`Claude role-agent dispatch unavailable: missing ${claudeAgents.missing.join(', ')}`);
+  }
 
-  const updateAvailable = manifest.version !== packageVersion() ||
+  const updateAvailable = Boolean(manifest.version !== packageVersion() ||
     plan.removals.length > 0 ||
     plan.unknownConflicts.length > 0 ||
-    fileStats.missing > 0;
+    fileStats.missing > 0 ||
+    (claudeAgents && claudeAgents.status !== 'ok'));
 
   return {
     ...base,
@@ -188,6 +197,7 @@ function collectRuntimeStatus(runtime, scope, configDir) {
     hookRegistration: hookState,
     updateAvailable,
     claudePlugin: manifest.claude_plugin || null,
+    claudeAgents,
     issues,
   };
 }
@@ -243,6 +253,9 @@ function printStatusReport(statuses) {
       if (status.claudePlugin) {
         console.log(`  plugin: ${status.claudePlugin.plugin_id || CLAUDE_PLUGIN_ID}; marketplace ${status.claudePlugin.marketplace_name || CLAUDE_PLUGIN_MARKETPLACE_NAME}`);
       }
+      if (status.claudeAgents) {
+        console.log(`  plugin agents: ${status.claudeAgents.status}; present ${status.claudeAgents.present}; missing ${status.claudeAgents.missing.length}`);
+      }
     } else if (status.hookRegistration === 'present') {
       console.log('  hooks: managed hook registration present without install manifest');
     }

package/lib/run-claude-agent-runtime.cjs

@@ -0,0 +1,79 @@
+'use strict';
+
+const path = require('node:path');
+
+const { assertClaudeAgentsAvailable, defaultClaudeConfigDir } = require('./claude-agents.cjs');
+const { resolveClaudeExecutable } = require('./install-claude-plugin.cjs');
+const {
+  MANAGER_PREPARE_PHASE,
+  REQUIRED_COVERAGE_PHASE,
+  ROLE_BY_PHASE,
+} = require('./run-constants.cjs');
+const { resolvePath } = require('./run-roots.cjs');
+
+const CLAUDE_PERMISSION_MODE = 'acceptEdits';
+
+function buildClaudeAgentCommandConfig(options, roots, cwd = process.cwd()) {
+  const agentConfigDir = options.agentConfigDir
+    ? resolvePath(options.agentConfigDir, cwd)
+    : defaultClaudeConfigDir();
+  const agentStatus = assertClaudeAgentsAvailable(agentConfigDir);
+  const { executable, searchPath } = resolveClaudeExecutable();
+  const env = {
+    CLAUDE_CONFIG_DIR: agentConfigDir,
+    PATH: searchPath,
+  };
+  const pluginArgs = agentStatus.source === 'installed-plugin' || agentStatus.source === 'package-plugin'
+    ? ['--plugin-dir', agentStatus.pluginDir]
+    : [];
+
+  return {
+    configDir: agentConfigDir,
+    config: {
+      version: 1,
+      stages: claudeStages(roots, executable, env, pluginArgs),
+    },
+  };
+}
+
+function claudeStages(roots, executable, env, pluginArgs) {
+  const contaminatedCwd = roots.contaminatedRoot;
+  const cleanCwd = roots.cleanRoot;
+  const implementationCwd = roots.implementationRoots[0] || roots.cleanRoot;
+  return [
+    claudeStage(MANAGER_PREPARE_PHASE, contaminatedCwd, executable, env, pluginArgs),
+    claudeStage('contaminated-analysis', contaminatedCwd, executable, env, pluginArgs),
+    claudeStage('sanitize-handoff', contaminatedCwd, executable, env, pluginArgs),
+    claudeStage('clean-plan', cleanCwd, executable, env, pluginArgs),
+    claudeStage('clean-implement-qc', implementationCwd, executable, env, pluginArgs),
+    claudeStage(REQUIRED_COVERAGE_PHASE, contaminatedCwd, executable, env, pluginArgs),
+  ];
+}
+
+function claudeStage(phase, cwd, executable, env, pluginArgs) {
+  const role = ROLE_BY_PHASE[phase];
+  return {
+    phase,
+    role,
+    cwd,
+    argv: [
+      executable,
+      '--print',
+      '--input-format',
+      'text',
+      '--output-format',
+      'text',
+      '--no-session-persistence',
+      '--permission-mode',
+      CLAUDE_PERMISSION_MODE,
+      '--agent',
+      `clean-room:${role}`,
+      ...pluginArgs,
+    ],
+    env,
+  };
+}
+
+module.exports = {
+  buildClaudeAgentCommandConfig,
+};

package/lib/run-cli.cjs

@@ -1,13 +1,18 @@
 'use strict';
 
+const AGENT_RUNTIMES = new Set(['claude']);
+
 function printRunHelp() {
-  console.log(`Usage: clean-room-skill run --task-manifest <path> --agent-commands <path> [options]
+  console.log(`Usage: clean-room-skill run --task-manifest <path> (--agent-commands <path> | --agent-runtime claude) [options]
 
 Run one bounded inner clean-room controller loop for an approved spec slice.
 
 Options:
   --task-manifest <path>   Required task-manifest.json path
-  --agent-commands <path>  Required role command adapter JSON unless --dry-run is set
+  --agent-commands <path>  Role command adapter JSON unless --agent-runtime or --dry-run is set
+  --agent-runtime <name>   Built-in role agent runtime; currently supports claude
+  --agent-config-dir <path>
+                           Runtime config dir for --agent-runtime claude
   --max-iterations <n>     Lower the manifest/loop iteration cap
   --once                   Run at most one inner iteration
   --dry-run                Validate and print the selected unit without writing or spawning agents
@@ -21,6 +26,8 @@ function parseRunArgs(argv) {
   const options = {
     taskManifest: null,
     agentCommands: null,
+    agentRuntime: null,
+    agentConfigDir: null,
     maxIterations: null,
     once: false,
     dryRun: false,
@@ -47,6 +54,16 @@ function parseRunArgs(argv) {
       options.agentCommands = requiredValue(argv, index, '--agent-commands');
     } else if (arg.startsWith('--agent-commands=')) {
       options.agentCommands = arg.slice('--agent-commands='.length);
+    } else if (arg === '--agent-runtime') {
+      index += 1;
+      options.agentRuntime = parseAgentRuntime(requiredValue(argv, index, '--agent-runtime'));
+    } else if (arg.startsWith('--agent-runtime=')) {
+      options.agentRuntime = parseAgentRuntime(arg.slice('--agent-runtime='.length));
+    } else if (arg === '--agent-config-dir') {
+      index += 1;
+      options.agentConfigDir = requiredValue(argv, index, '--agent-config-dir');
+    } else if (arg.startsWith('--agent-config-dir=')) {
+      options.agentConfigDir = arg.slice('--agent-config-dir='.length);
     } else if (arg === '--max-iterations') {
       index += 1;
       options.maxIterations = parsePositiveInteger(requiredValue(argv, index, '--max-iterations'), '--max-iterations');
@@ -70,6 +87,13 @@ function parseRunArgs(argv) {
   return options;
 }
 
+function parseAgentRuntime(value) {
+  if (!AGENT_RUNTIMES.has(value)) {
+    throw new Error('--agent-runtime must be claude');
+  }
+  return value;
+}
+
 function requiredValue(argv, index, flag) {
   if (index >= argv.length || argv[index] === '') {
     throw new Error(`${flag} requires a value`);
@@ -85,6 +109,7 @@ function parsePositiveInteger(value, flag) {
 }
 
 module.exports = {
+  AGENT_RUNTIMES,
   parseRunArgs,
   printRunHelp,
 };

package/lib/run-constants.cjs

@@ -13,6 +13,7 @@ const STATUS_NAME = 'controller-status.json';
 const CLEAN_RUN_CONTEXT_NAME = 'clean-run-context.json';
 const HANDOFF_PACKAGE_NAME = 'handoff-package.json';
 const POLISH_REPORT_NAME = 'polish-report.json';
+const MANAGER_PREPARE_PHASE = 'contaminated-manager-prepare';
 const REQUIRED_COVERAGE_PHASE = 'contaminated-coverage-verify';
 const POLISH_PHASE = 'clean-polish-review';
 const PUBLIC_SURFACE_COMPLETION_LEVELS = new Set(['exact-public-contract', 'behavior-compatible']);
@@ -65,6 +66,7 @@ const HOOK_ONLY_ENV_ALLOWLIST = Object.freeze([
 ]);
 
 const ROLE_BY_PHASE = Object.freeze({
+  [MANAGER_PREPARE_PHASE]: 'contaminated-manager-verifier',
   'contaminated-analysis': 'contaminated-source-analyst',
   'sanitize-handoff': 'contaminated-handoff-sanitizer',
   'clean-plan': 'clean-architect',
@@ -153,6 +155,7 @@ module.exports = {
   MAX_LEDGER_ITERATIONS,
   MAX_OUTPUT_BYTES,
   MAX_TIMEOUT_MS,
+  MANAGER_PREPARE_PHASE,
   POLISH_PHASE,
   POLISH_REPORT_NAME,
   PUBLIC_SURFACE_COMPLETION_LEVELS,

package/lib/run-controller.cjs

@@ -24,6 +24,7 @@ const {
   validateArtifacts,
   validateTaskManifestSchema,
 } = require('./run-hooks.cjs');
+const { buildClaudeAgentCommandConfig } = require('./run-claude-agent-runtime.cjs');
 const {
   effectiveIterationCap,
   validateTaskManifestForRun,
@@ -70,6 +71,70 @@ function repeatedUnitSelection(previous, selectedUnit) {
   return previous?.unit_id === selectedUnit.unit_id && previous?.stop_reason === 'no-progress-detected';
 }
 
+function validateRunState(options, taskManifestPath, roots, manifest, coverageLedgerPath) {
+  validateImplementationArtifactPlacement(roots);
+  validateArtifacts(options.python, taskManifestPath, roots);
+  validateCleanRunContextReferences(options.python, roots);
+  const coverageLedger = readOptionalJson(coverageLedgerPath);
+  validateCoverageLedgerIntegrity(manifest, roots, coverageLedger);
+  validateFoundationCoverageGate(manifest, coverageLedger);
+  return coverageLedger;
+}
+
+function rootListEqual(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function assertStableRunRoots(initialRoots, currentRoots) {
+  if (
+    !rootListEqual(initialRoots.sourceRoots, currentRoots.sourceRoots) ||
+    initialRoots.contaminatedRoot !== currentRoots.contaminatedRoot ||
+    initialRoots.cleanRoot !== currentRoots.cleanRoot ||
+    !rootListEqual(initialRoots.implementationRoots, currentRoots.implementationRoots) ||
+    !rootListEqual(initialRoots.allowedReadRoots, currentRoots.allowedReadRoots) ||
+    initialRoots.schemaDir !== currentRoots.schemaDir
+  ) {
+    throw new Error('task manifest root drift detected during unattended run');
+  }
+}
+
+function reloadManifestForIteration(options, taskManifestPath, manifestDir, roots, schemaDir) {
+  validateTaskManifestSchema(options.python, taskManifestPath, schemaDir);
+  const currentManifest = readJsonFile(taskManifestPath, null);
+  validateTaskManifestForRun(currentManifest);
+  const currentRoots = resolveRoots(currentManifest, manifestDir, schemaDir);
+  assertStableRunRoots(roots, currentRoots);
+  validateTaskManifestLocation(taskManifestPath, currentRoots);
+  verifyPreflightGoal(currentManifest, manifestDir, currentRoots);
+  return currentManifest;
+}
+
+function resolveAgentConfig(options, context, roots, manifest, agentConfigPath) {
+  if (options.agentCommands && options.agentRuntime) {
+    throw new Error('--agent-runtime cannot be used with --agent-commands');
+  }
+  if (!options.agentCommands && !options.agentRuntime) {
+    return { agentConfig: null, configDir: process.cwd() };
+  }
+  if (options.agentRuntime === 'claude') {
+    const builtIn = buildClaudeAgentCommandConfig(options, roots, context.cwd || process.cwd());
+    validateCommandConfig(builtIn.config, {
+      roots,
+      configDir: builtIn.configDir,
+      contextManagement: manifest.context_management,
+    });
+    return { agentConfig: builtIn.config, configDir: builtIn.configDir };
+  }
+  const agentConfig = readJsonFile(agentConfigPath, null);
+  const configDir = path.dirname(agentConfigPath);
+  validateCommandConfig(agentConfig, { roots, configDir, contextManagement: manifest.context_management });
+  return { agentConfig, configDir };
+}
+
+function shouldContinueAfterUnitComplete(manifest, coverageLedger) {
+  return Boolean(selectUnit(manifest, coverageLedger));
+}
+
 async function runCleanRoom(options, context = {}) {
   if (options.help) {
     printRunHelp();
@@ -78,8 +143,11 @@ async function runCleanRoom(options, context = {}) {
   if (!options.taskManifest) {
     throw new Error('--task-manifest is required');
   }
-  if (!options.dryRun && !options.agentCommands) {
-    throw new Error('--agent-commands is required unless --dry-run is set');
+  if (!options.dryRun && !options.agentCommands && !options.agentRuntime) {
+    throw new Error('--agent-commands or --agent-runtime is required unless --dry-run is set');
+  }
+  if (options.agentCommands && options.agentRuntime) {
+    throw new Error('--agent-runtime cannot be used with --agent-commands');
   }
 
   const taskManifestPath = resolvePath(options.taskManifest, context.cwd || process.cwd());
@@ -96,20 +164,13 @@ async function runCleanRoom(options, context = {}) {
   verifyPreflightGoal(manifest, manifestDir, roots);
   const cap = effectiveIterationCap(manifest, options);
   const agentConfigPath = options.agentCommands ? resolvePath(options.agentCommands, context.cwd || process.cwd()) : null;
-  const agentConfig = agentConfigPath ? readJsonFile(agentConfigPath, null) : null;
-  const configDir = agentConfigPath ? path.dirname(agentConfigPath) : process.cwd();
-  if (agentConfig) {
-    validateCommandConfig(agentConfig, { roots, configDir, contextManagement: manifest.context_management });
-  }
+  const { agentConfig, configDir } = options.dryRun
+    ? { agentConfig: null, configDir: process.cwd() }
+    : resolveAgentConfig(options, context, roots, manifest, agentConfigPath);
 
   return withRunLock(roots.contaminatedRoot, options.dryRun, async () => {
     const coverageLedgerPath = path.join(roots.contaminatedRoot, 'coverage-ledger.json');
-    validateImplementationArtifactPlacement(roots);
-    validateArtifacts(options.python, taskManifestPath, roots);
-    validateCleanRunContextReferences(options.python, roots);
-    const coverageLedger = readOptionalJson(coverageLedgerPath);
-    validateCoverageLedgerIntegrity(manifest, roots, coverageLedger);
-    validateFoundationCoverageGate(manifest, coverageLedger);
+    const coverageLedger = validateRunState(options, taskManifestPath, roots, manifest, coverageLedgerPath);
     const selectedUnit = selectUnit(manifest, coverageLedger);
     if (!selectedUnit) {
       const result = completeResultOrSpecDelta(manifest, roots, coverageLedger);
@@ -121,28 +182,6 @@ async function runCleanRoom(options, context = {}) {
     const ledgerPath = path.join(roots.contaminatedRoot, LEDGER_NAME);
     const resultPath = path.join(roots.contaminatedRoot, RESULT_NAME);
     const ledger = loadLedger(ledgerPath, manifest);
-    const previous = previousIteration(ledger);
-    if (repeatedUnitSelection(previous, selectedUnit)) {
-      const result = buildResult(manifest, 'no-progress-detected', 'partial', null, null, [
-        {
-          kind: 'other',
-          summary: 'The same unit was selected again after a no-progress iteration.',
-          status: 'open',
-        },
-      ]);
-      if (!options.dryRun) {
-        writeResult(resultPath, result);
-        ledger.iterations.push({
-          iteration: ledger.iterations.length + 1,
-          unit_id: selectedUnit.unit_id,
-          stop_reason: 'repeated-unit-selection',
-          phases: [],
-        });
-        writeLedger(ledgerPath, ledger);
-      }
-      console.log('clean-room run: repeated-unit-selection');
-      return result;
-    }
 
     if (options.dryRun) {
       console.log(`clean-room run dry-run: selected ${selectedUnit.unit_id}`);
@@ -156,10 +195,39 @@ async function runCleanRoom(options, context = {}) {
     }
 
     let terminalResult = null;
+    let resultManifest = manifest;
     const polishRequired = agentConfig.stages.some((stage) => stage.phase === POLISH_PHASE);
-    const strictContext = strictContextManagement(manifest.context_management);
     for (let offset = 0; offset < cap; offset += 1) {
-      const iteration = (manifest.loop_context.inner_iteration || 0) + offset + 1;
+      const currentManifest = reloadManifestForIteration(options, taskManifestPath, manifestDir, roots, schemaDir);
+      resultManifest = currentManifest;
+      const strictContext = strictContextManagement(currentManifest.context_management);
+      const currentCoverageLedger = validateRunState(options, taskManifestPath, roots, currentManifest, coverageLedgerPath);
+      const selected = selectUnit(currentManifest, currentCoverageLedger);
+      if (!selected) {
+        terminalResult = completeResultOrSpecDelta(currentManifest, roots, currentCoverageLedger);
+        break;
+      }
+      const previous = previousIteration(ledger);
+      if (repeatedUnitSelection(previous, selected)) {
+        terminalResult = buildResult(currentManifest, 'no-progress-detected', 'partial', null, null, [
+          {
+            kind: 'other',
+            summary: 'The same unit was selected again after a no-progress iteration.',
+            status: 'open',
+          },
+        ]);
+        ledger.iterations.push({
+          iteration: ledger.iterations.length + 1,
+          unit_id: selected.unit_id,
+          stop_reason: 'repeated-unit-selection',
+          phases: [],
+        });
+        writeLedger(ledgerPath, ledger);
+        console.log('clean-room run: repeated-unit-selection');
+        break;
+      }
+
+      const iteration = (currentManifest.loop_context.inner_iteration || 0) + offset + 1;
       const before = semanticProgressSnapshot(taskManifestPath, roots);
       const phaseResults = [];
       let coveragePhaseRan = false;
@@ -172,19 +240,19 @@ async function runCleanRoom(options, context = {}) {
           stage,
           configDir,
           roots,
-          manifest,
-          selectedUnit,
+          currentManifest,
+          selected,
           strictContext
         );
-        const stageResult = runStage(stage, configDir, roots, manifest, selectedUnit, iteration, sessionContext);
+        const stageResult = runStage(stage, configDir, roots, currentManifest, selected, iteration, sessionContext);
         const afterStage = artifactSnapshot(taskManifestPath, roots);
         phaseResults.push(stageResult);
         validateImplementationArtifactPlacement(roots);
         validateArtifacts(options.python, taskManifestPath, roots, changedSnapshotPaths(beforeStage, afterStage));
         validateCleanRunContextReferences(options.python, roots);
         const stageCoverageLedger = readOptionalJson(coverageLedgerPath);
-        validateCoverageLedgerIntegrity(manifest, roots, stageCoverageLedger);
-        validateFoundationCoverageGate(manifest, stageCoverageLedger);
+        validateCoverageLedgerIntegrity(currentManifest, roots, stageCoverageLedger);
+        validateFoundationCoverageGate(currentManifest, stageCoverageLedger);
         if (stage.phase === REQUIRED_COVERAGE_PHASE && stageResult.status === 'passed') {
           coveragePhaseRan = true;
         }
@@ -198,25 +266,37 @@ async function runCleanRoom(options, context = {}) {
       const progressDetected = !snapshotsEqual(before, after);
       const ledgerEntry = {
         iteration,
-        unit_id: selectedUnit.unit_id,
-        spec_slice_ref: manifest.loop_context.spec_slice_ref,
+        unit_id: selected.unit_id,
+        spec_slice_ref: currentManifest.loop_context.spec_slice_ref,
         phases: phaseResults,
         progress_detected: progressDetected,
       };
 
       if (failedStage) {
-        terminalResult = stageFailureResult(manifest, failedStage);
+        terminalResult = stageFailureResult(currentManifest, failedStage);
         ledgerEntry.stop_reason = 'spec-slice-blocked';
       } else if (!progressDetected) {
-        terminalResult = noProgressResult(manifest);
+        terminalResult = noProgressResult(currentManifest);
         ledgerEntry.stop_reason = 'no-progress-detected';
       } else if (coveragePhaseRan) {
-        terminalResult = inferTerminalResult(manifest, roots, selectedUnit, {
+        terminalResult = inferTerminalResult(currentManifest, roots, selected, {
           polishRequired,
           observedChangedPaths: changedImplementationPaths(before, after),
         });
         if (terminalResult) {
-          ledgerEntry.stop_reason = terminalResult.result;
+          if (terminalResult.result === 'spec-slice-complete') {
+            const latestCoverageLedger = readOptionalJson(coverageLedgerPath);
+            validateCoverageLedgerIntegrity(currentManifest, roots, latestCoverageLedger);
+            validateFoundationCoverageGate(currentManifest, latestCoverageLedger);
+            if (shouldContinueAfterUnitComplete(currentManifest, latestCoverageLedger)) {
+              ledgerEntry.stop_reason = 'unit-complete';
+              terminalResult = null;
+            } else {
+              ledgerEntry.stop_reason = terminalResult.result;
+            }
+          } else {
+            ledgerEntry.stop_reason = terminalResult.result;
+          }
         }
       }
 
@@ -228,15 +308,15 @@ async function runCleanRoom(options, context = {}) {
     }
 
     if (!terminalResult) {
-      terminalResult = iterationLimitResult(manifest);
+      terminalResult = iterationLimitResult(resultManifest);
     }
     writeResult(resultPath, terminalResult);
     validateImplementationArtifactPlacement(roots);
     validateArtifacts(options.python, taskManifestPath, roots);
     validateCleanRunContextReferences(options.python, roots);
     const finalCoverageLedger = readOptionalJson(coverageLedgerPath);
-    validateCoverageLedgerIntegrity(manifest, roots, finalCoverageLedger);
-    validateFoundationCoverageGate(manifest, finalCoverageLedger);
+    validateCoverageLedgerIntegrity(resultManifest, roots, finalCoverageLedger);
+    validateFoundationCoverageGate(resultManifest, finalCoverageLedger);
     console.log(`clean-room run: ${terminalResult.result}`);
     return terminalResult;
   });

package/lib/run-stages.cjs

@@ -8,6 +8,7 @@ const { spawnSync } = require('node:child_process');
 const { fileHash } = require('./fs-utils.cjs');
 const {
   DEFAULT_TIMEOUT_MS,
+  MANAGER_PREPARE_PHASE,
   MAX_OUTPUT_BYTES,
   MAX_TIMEOUT_MS,
   POLISH_PHASE,
@@ -60,7 +61,7 @@ function validateStageBoundaries(stage, index, context) {
   }
 
   let allowed = false;
-  if (stage.phase === 'contaminated-analysis' || stage.phase === 'contaminated-coverage-verify') {
+  if (stage.phase === MANAGER_PREPARE_PHASE || stage.phase === 'contaminated-analysis' || stage.phase === 'contaminated-coverage-verify') {
     allowed = pathIsUnder(cwd, roots.contaminatedRoot) || pathIsUnder(cwd, configDir);
   } else if (stage.phase === 'sanitize-handoff') {
     allowed = pathIsUnder(cwd, roots.contaminatedRoot);
@@ -114,7 +115,7 @@ function resolveStageBriefPath(stage, configDir, roots) {
 function validateStageContext(stage, index, context = {}) {
   const strict = strictContextManagement(context.contextManagement);
   if (stage.context === undefined) {
-    if (strict) {
+    if (strict && stage.phase !== MANAGER_PREPARE_PHASE) {
       throw new Error(`agent command stage ${index} must provide context in strict context-management mode`);
     }
     return;
@@ -134,10 +135,10 @@ function validateStageContext(stage, index, context = {}) {
   if (stage.context.brief_path !== undefined && (typeof stage.context.brief_path !== 'string' || stage.context.brief_path === '')) {
     throw new Error(`agent command stage ${index} context.brief_path must be a non-empty string`);
   }
-  if (strict && stage.context.fresh_session !== true) {
+  if (strict && stage.phase !== MANAGER_PREPARE_PHASE && stage.context.fresh_session !== true) {
     throw new Error(`agent command stage ${index} context.fresh_session must be true in strict context-management mode`);
   }
-  if (strict && !stage.context.brief_path) {
+  if (strict && stage.phase !== MANAGER_PREPARE_PHASE && !stage.context.brief_path) {
     throw new Error(`agent command stage ${index} context.brief_path is required in strict context-management mode`);
   }
   if (stage.context.brief_path && context.roots && context.configDir) {
@@ -330,6 +331,10 @@ function stagePrompt(stage, manifest, unit, iteration, sessionContext = null) {
     '',
     'Run only this configured clean-room stage from durable artifacts.',
     'Do not use prior chat history as state.',
+    ...(stage.phase === MANAGER_PREPARE_PHASE ? [
+      'Act only as Agent 0 manager/controller for this selected unit.',
+      'Prepare durable controller status or role-session briefs as needed, then return. Do not perform downstream role work.',
+    ] : []),
     ...(sessionContext ? ['Read CLEAN_ROOM_SESSION_BRIEF_PATH first and load only the artifact refs it permits.'] : []),
     '',
   ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room-skill",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "bin": {
     "clean-room-skill": "bin/install.js"

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "clean-room",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "author": {
     "name": "whit3rabbit"

package/skills/clean-room/SKILL.md

@@ -54,6 +54,8 @@ Optional AST/indexing helpers are detected before the controller loop through `s
 
 Controller mode defaults to `attended` when `task-manifest.json` has no `controller_policy`. The outer loop evolves specs and selects one approved spec slice. Code-development runs start with exactly one `unit_kind: "foundation"` unit named by `loop_context.foundation_unit_ref`; non-foundation behavior slices wait until that unit is covered. The inner clean-room loop completes the approved slice through sanitized handoff, implementation, QC, optional final polish review, and contaminated-side coverage verification, then returns `clean-room-result.json` to the outer loop. In `attended` mode, agent zero pauses for human review at scope gate, handoff, QC deltas, polish deltas, blocked units, and final coverage. In `unattended` mode, agent zero may run a bounded inner loop: reload durable artifacts for each iteration, select at most one pending or gap unit inside `loop_context.approved_scope_refs`, start each role from fresh context with the required environment block, validate before advancing, and stop on any configured safety or ambiguity condition.
 
+In Claude Code unattended mode, launch the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude` when possible. The main conversation must not do Agent 1, Agent 2, Agent 3, or Agent 4 work, and must not ask to continue while unattended policy still allows bounded progress. If role-agent dispatch is unavailable, fail closed with a blocker.
+
 Do not grant shell-style tools to Agent 0, Agent 1, Agent 1.5, Agent 2, or the default Agent 3/4 role sessions. Agent 3 terminal verification may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT3_SHELL=1`, the command cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent3-verification-runner.py`. Agent 4 polish verification and commit may use shell-style tools only when `CLEAN_ROOM_ALLOW_AGENT4_SHELL=1`, cwd is under `CLEAN_ROOM_IMPLEMENTATION_ROOTS`, and the command invokes the installed `agent4-polish-runner.py`. Use `--hooks=strict` for dedicated Codex, Claude, or OpenCode clean-room homes so hooks fail closed if required environment is missing or shell tools are invoked outside the allowed runner boundaries. Safe hook installs are compatibility-only between runs; during init/onboarding, prepare the role environment block and pass it into every clean-room role session so safe hooks enforce during active work.
 
 Post-write hook failures are policy failures, not implementation guidance. If a clean or staged artifact cannot be read, scanned, schema-checked, or hashed because the filesystem changed, report the controlled redacted failure and ask the controller/user to restore readable artifact state before retrying.

package/skills/resume-cr/SKILL.md

@@ -11,6 +11,8 @@ Resume an existing clean-room run from durable artifacts. Never use prior chat h
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Read `skills/clean-room/references/CONTROLLER-LOOP.md` when the manifest records `loop_context` or unattended mode. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
+If `task-manifest.json` records `controller_policy.mode: "unattended"` in Claude Code, prefer launching `clean-room-skill run --task-manifest <path> --agent-runtime claude` and let the durable runner assign role agents. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while unattended policy, iteration budget, and approved pending or gap units still permit progress. If the runner or Claude role-agent dispatch is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` rather than silently continuing in the main chat.
+
 ## Load Order
 
 Load these artifacts from the paths recorded in `task-manifest.json` and the configured root environment. Treat missing optional artifacts as blockers only when the current gate requires them.

package/skills/unattended/SKILL.md

@@ -15,6 +15,8 @@ Use the canonical `clean-room` skill workflow and references in this plugin. Rea
 
 Before asking setup or preflight questions, use the canonical `clean-room` "Run State Discovery Before Wizard" rules. Resolve explicit artifact paths first, then configured clean-room roots, then bounded `~/Documents/CleanRoom/task-*` candidates. If a valid `task-manifest.json` exists, route to `resume-cr`. If a valid canonical `preflight-goal.json` exists without a manifest, continue at source/destination discovery and manifest creation. If a preflight artifact exists but is invalid, stop with schema errors instead of restarting preflight. If multiple candidates are found without an explicit path, list them and stop for selection.
 
+When resuming a valid unattended `task-manifest.json` in Claude Code, prefer launching the durable runner with `clean-room-skill run --task-manifest <path> --agent-runtime claude`. The main conversation must not perform Agent 1, Agent 2, Agent 3, or Agent 4 work. Do not ask to continue while `controller_policy.mode` is `unattended`, the iteration budget remains, and approved pending or gap units remain. If Claude role-agent dispatch or the runner is unavailable, stop with `BLOCKERS: Claude role-agent dispatch unavailable` instead of falling back to main-chat execution.
+
 Load or create `preflight-goal.json` first. Unattended mode requires a complete goal contract with no blocking or non-blocking `open_questions`, `controller_policy.unattended_allowed_after_preflight: true`, and a finite `controller_policy.max_iterations`.
 
 Do not assume target language, license policy, dependency policy, exactness policy, output directory, or feature add/remove policy during the unattended loop. Stop on ambiguity instead of inventing product decisions.