clean-room-skill 0.1.13 → 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.13",
+      "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.13",
+  "version": "0.1.15",
   "author": {
     "name": "whit3rabbit"
   },

package/.codex-plugin/plugin.json

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

package/README.md

@@ -99,7 +99,7 @@ In Claude Code, invoke skills with the plugin namespace:
 /clean-room
 /clean-room:attended
 /clean-room:unattended
-/clean-room:resume
+/clean-room:resume-cr
 /clean-room:start-over
 /clean-room:refocus
 ```
@@ -114,7 +114,7 @@ In Pi, invoke package skills with `/skill:<name>`:
 /skill:clean-room
 /skill:attended
 /skill:unattended
-/skill:resume
+/skill:resume-cr
 /skill:start-over
 /skill:refocus
 ```
@@ -156,7 +156,7 @@ In strict context-management mode, every `agent-commands.json` stage must set `c
 
 Use recovery skills instead of chat history:
 
-- `/clean-room:resume`: continue from durable artifacts.
+- `/clean-room:resume-cr`: continue from durable artifacts.
 - `/clean-room:start-over`: archive or quarantine current artifacts without deletion, then restart with a fresh neutral task id.
 - `/clean-room:refocus`: audit current artifacts against declared scope without expanding scope.
 
@@ -190,7 +190,7 @@ Use recovery skills instead of chat history:
 
 | Skill | Use it for |
 | --- | --- |
-| `/clean-room:resume` | Continue an existing run from durable artifacts. |
+| `/clean-room:resume-cr` | Continue an existing run from durable artifacts. |
 | `/clean-room:start-over` | Non-destructively archive or quarantine current artifacts and restart. |
 | `/clean-room:refocus` | Audit a run and route it back to missed gates without adding scope. |
 

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/HOOKS.md

@@ -68,6 +68,7 @@ Role sessions must provide the full clean-room environment block so the hooks ca
 | `CLEAN_ROOM_PRIVATE_IDENTIFIER_DENYLIST` | Optional path-separated denylist files for leakage scanning. |
 | `CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST` | Optional path-separated allowlist for unrecognized auxiliary JSON files under clean roots. |
 | `CLEAN_ROOM_ALLOW_AGENT3_SHELL` | Must be `1` before Agent 3 can invoke the verification runner through a shell-style tool. |
+| `CLEAN_ROOM_ALLOW_AGENT4_SHELL` | Must be `1` before Agent 4 can invoke the polish runner through a shell-style tool. |
 | `CLEAN_ROOM_HOOK_ENFORCE` | Forces enforcement in `safe` mode when truthy. |
 | `CLEAN_ROOM_HOOK_CHECK_TIMEOUT_SECONDS` | Optional per-check wrapper timeout. Defaults to 10 seconds. |
 

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/hooks/agent3-verification-runner.py

@@ -472,6 +472,8 @@ def run_command(
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         text=True,
+        encoding="utf-8",
+        errors="replace",
         timeout=effective_timeout,
         shell=False,
         check=False,

package/hooks/agent4-polish-runner.py

@@ -138,6 +138,8 @@ def run_command(argv: list[str], cwd: Path, timeout: int, blocked_roots: list[Pa
         cwd=cwd,
         env=safe_env(blocked_roots),
         text=True,
+        encoding="utf-8",
+        errors="replace",
         stdout=subprocess.PIPE,
         stderr=subprocess.PIPE,
         shell=False,

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.13",
+  "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.13",
+  "version": "0.1.15",
   "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
   "author": {
     "name": "whit3rabbit"

package/skills/attended/SKILL.md

@@ -13,7 +13,7 @@ In Pi, this entry point is invoked as `/skill:attended`.
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-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`. 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.
+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.
 
 Load or create `preflight-goal.json` first. Attended mode may continue with unresolved questions only when they are recorded as `open_questions`; blocking questions become pause gates before affected work starts.
 
@@ -30,4 +30,4 @@ Before indexing or artifact generation, confirm that source roots, contaminated
 
 Record `preflight_goal_ref`, `preflight_goal_sha256`, required `handoff_sequence`, and `controller_policy.mode` as `attended`. Pause for human review at preflight open questions, scope gate, clean handoff, terminal implementation or polish deltas, blocked units, and final coverage. Include stop conditions for `authorization-missing`, `scope-change`, `contamination-suspected`, `schema-validation-failed`, `leakage-scan-failed`, `unit-blocked`, `implementation-complete`, and `coverage-complete`; attended mode does not add an iteration-limit stop unless the user explicitly sets one.
 
-For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, guide agent zero/controller to run `skills/clean-room/scripts/build_visual_index.py` instead, store `visual-index.json` only under the contaminated artifact root, include visual roots in `CLEAN_ROOM_SOURCE_ROOTS`, and pause before decomposition to clarify the product goal, target user flow, screenshot coverage, target stack, UI exactness boundary, and public-compatibility status of visible words.
+For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, guide agent zero/controller to run `skills/clean-room/scripts/build_visual_index.py` instead, store `visual-index.json` only under the contaminated artifact root, include visual roots in `CLEAN_ROOM_SOURCE_ROOTS` (ensuring screenshot evidence directories are explicitly added to `CLEAN_ROOM_SOURCE_ROOTS` during execution so that path-aware read hooks such as `hooks/deny-clean-source-read.py` can protect them as expected), and pause before decomposition to clarify the product goal, target user flow, screenshot coverage, target stack, UI exactness boundary, and public-compatibility status of visible words.

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.
@@ -62,7 +64,7 @@ Post-write hook failures are policy failures, not implementation guidance. If a
 
 Use the recovery skills when a run already has durable artifacts:
 
-- `resume`: reload `task-manifest.json`, its `initialization_snapshot`, ledgers, `implementation-plan.json`, `implementation-report.json`, `qc-report.json`, and abstract delta tickets, then continue from the earliest incomplete gate using the recorded `controller_policy`. If `init-config.json` differs from the snapshot, report drift and wait for explicit confirmation.
+- `resume-cr`: reload `task-manifest.json`, its `initialization_snapshot`, ledgers, `implementation-plan.json`, `implementation-report.json`, `qc-report.json`, and abstract delta tickets, then continue from the earliest incomplete gate using the recorded `controller_policy`. If `init-config.json` differs from the snapshot, report drift and wait for explicit confirmation.
 - `start-over`: after explicit confirmation, non-destructively archive or quarantine existing artifacts and restart from the scope gate with a fresh `task_id`.
 - `refocus`: audit declared scope against current artifacts and steer the workflow back to missed gates without expanding scope.
 
@@ -84,7 +86,7 @@ If more than one candidate run is found without an explicit user path, list the
 
 Classify the selected candidate before starting the wizard:
 
-- Valid `task-manifest.json`: route to `resume` and continue from the earliest incomplete gate.
+- Valid `task-manifest.json`: route to `resume-cr` and continue from the earliest incomplete gate.
 - Valid canonical `preflight-goal.json` without `task-manifest.json`: continue at source/destination discovery and manifest creation. Do not ask the preflight wizard again.
 - `clean-room-bootstrap.json` only: run preflight using the bootstrap roots.
 - Invalid `preflight-goal.json`: stop, report canonical schema or required-field errors, and do not create a replacement preflight.

package/skills/clean-room/references/PREFLIGHT.md

@@ -75,6 +75,6 @@ When `context_management.enforcement` is `strict`, no role can start until Agent
 
 ## Recovery
 
-`resume` and `refocus` must stop when new-run artifacts lack `preflight_goal_ref`, `preflight_goal_sha256`, or a complete `handoff_sequence`. Report this as legacy or incomplete preflight state; do not infer intent from prior chat or source.
+`resume-cr` and `refocus` must stop when new-run artifacts lack `preflight_goal_ref`, `preflight_goal_sha256`, or a complete `handoff_sequence`. Report this as legacy or incomplete preflight state; do not infer intent from prior chat or source.
 
 `start-over` must create a new preflight goal or explicitly reuse a reviewed goal contract before recreating active artifacts.

package/skills/clean-room/references/PROCESS.md

@@ -104,7 +104,7 @@ The durable tasklist is `task-manifest.json` `units`, generated by agent zero du
 
 Use recovery entry points only when durable artifacts already exist:
 
-- `resume`: reload the manifest, referenced preflight goal, initialization snapshot, ledgers, clean run context, handoff artifacts, implementation plan, implementation report, QC report, and abstract delta tickets; validate schema and leakage state; continue from the earliest incomplete gate under the recorded controller policy. Agent 0 may write or refresh `controller-status.json`, then create the next role-specific `role-session-brief.json`. Clean roles must receive the brief and clean artifact refs, not full resume state. If reusable `init-config.json` differs from the manifest snapshot, report drift and stop before applying changes. If new-run artifacts lack preflight refs or handoff sequence, stop for reviewed preflight migration.
+- `resume-cr`: reload the manifest, referenced preflight goal, initialization snapshot, ledgers, clean run context, handoff artifacts, implementation plan, implementation report, QC report, and abstract delta tickets; validate schema and leakage state; continue from the earliest incomplete gate under the recorded controller policy. Agent 0 may write or refresh `controller-status.json`, then create the next role-specific `role-session-brief.json`. Clean roles must receive the brief and clean artifact refs, not full resume state. If reusable `init-config.json` differs from the manifest snapshot, report drift and stop before applying changes. If new-run artifacts lack preflight refs or handoff sequence, stop for reviewed preflight migration.
 - `start-over`: require explicit confirmation, archive or quarantine current artifacts without deletion, then return to the preflight gate with a fresh `task_id`.
 - `refocus`: compare current artifacts to declared scope and preflight goal, identify missed gates or open deltas, and steer Agent 0 back to the earliest required gate without expanding scope.
 

package/skills/clean-room/references/SPEC-SCHEMA.md

@@ -112,7 +112,7 @@ Capture:
 - user rules split into `clean_safe` and `contaminated_only`
 - reconfiguration policy requiring confirmation for root, schema, and model changes
 
-`clean-run-context.json` is the only run context Agent 2, Agent 3, and Agent 4 should read. It may contain clean artifact paths, implementation root environment references, target profile, native artifact expectations, clean-safe goal contract fields, code hygiene policy, approved public references, clean-safe rules, clean-side model preferences, optional Agent 4 local commit policy, and the artifact-only coordination boundary. It must not contain source roots, visual roots, contaminated artifact roots, source index refs, visual index refs, coverage ledgers, evidence ledgers, contaminated-only rules, full `preflight-goal.json`, or the full `task-manifest.json`.
+`clean-run-context.json` is the only run context Agent 2, Agent 3, and Agent 4 should read. It may contain clean artifact paths, implementation root environment references, target profile, native artifact expectations, clean-safe goal contract fields, code hygiene policy, approved public references, clean-safe rules, clean-side model preferences, optional Agent 4 local commit policy (e.g. `implementation.polish_commit` with `agent4_shell_allowed`, `cwd_policy`, and `git_policy`), and the artifact-only coordination boundary. It must not contain source roots, visual roots, contaminated artifact roots, source index refs, visual index refs, coverage ledgers, evidence ledgers, contaminated-only rules, full `preflight-goal.json`, or the full `task-manifest.json`.
 
 `context_management` is optional on `task-manifest.json` and `clean-run-context.json`. When present with `mode: "role-session-briefs"`, it records advisory or strict enforcement plus budgets for prompt characters, brief characters, artifact refs, and referenced artifact bytes. Strict mode requires a fresh role session and a valid `role-session-brief.json` for each stage.
 

package/skills/{resume → resume-cr}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: resume
+name: resume-cr
 description: Continues an existing Clean Room run from durable artifacts without relying on prior chat history.
 argument-hint: [existing task-manifest.json or artifact roots]
 disable-model-invocation: true
@@ -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

@@ -13,7 +13,9 @@ In Pi, this entry point is invoked as `/skill:unattended`.
 
 Use the canonical `clean-room` skill workflow and references in this plugin. Read `skills/clean-room/references/CONTROLLER-LOOP.md` before defining unattended loop behavior. Preserve the same clean-room boundary, role separation, artifact schemas, leakage rules, implementation-root rules, and hook expectations.
 
-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`. 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.
+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`.
 
@@ -36,4 +38,4 @@ Record `preflight_goal_ref`, `preflight_goal_sha256`, required `handoff_sequence
 
 The inner loop returns only after Agent 0 consumes the terminal Agent 3 report, any configured Agent 4 `polish-report.json`, and completes contaminated-side coverage verification. Write `clean-room-result.json` before returning control to the outer spec loop.
 
-For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, unattended mode may use `skills/clean-room/scripts/build_visual_index.py` only after preflight already answers the visual-fallback questions with no open questions. Store `visual-index.json` only under the contaminated artifact root and include visual roots in `CLEAN_ROOM_SOURCE_ROOTS`.
+For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages. If no indexable source code exists and screenshots/images are the only authorized evidence, unattended mode may use `skills/clean-room/scripts/build_visual_index.py` only after preflight already answers the visual-fallback questions with no open questions. Store `visual-index.json` only under the contaminated artifact root and include visual roots in `CLEAN_ROOM_SOURCE_ROOTS` (ensuring screenshot evidence directories are explicitly added to `CLEAN_ROOM_SOURCE_ROOTS` during execution so that path-aware read hooks such as `hooks/deny-clean-source-read.py` can protect them as expected).