affaan-m/ECC · error

Claude requires explicit --claude-scope and --claude-hooks c

Error message

Claude requires explicit --claude-scope and --claude-hooks choices in this mode.

What it means

In non-interactive mode (or any --json run), install-guided.js cannot prompt for the two Claude-specific choices, so selecting the claude harness requires explicit --claude-scope AND --claude-hooks on the command line. Missing either one throws.

Source

Thrown at scripts/install-guided.js:192

    claudeHooks,
    profile,
  };
}

function selectedHarnessIds(options) {
  if (options.allHarnesses) return normalizeHarnessSelection(['all']);
  if (options.harnesses.length === 0) return [];
  return normalizeHarnessSelection(options.harnesses);
}

function validateExecutionMode(options, interactive) {
  const harnesses = selectedHarnessIds(options);
  if (!interactive && harnesses.length === 0) {
    throw new Error('Non-interactive guided install requires at least one --harness.');
  }
  const requiresExplicit = !interactive || options.json;
  if (requiresExplicit && harnesses.includes('claude') && (!options.claudeScope || !options.claudeHooks)) {
    throw new Error('Claude requires explicit --claude-scope and --claude-hooks choices in this mode.');
  }
  if (requiresExplicit && harnesses.includes('kimi') && !options.profile) {
    throw new Error('Kimi requires an explicit --profile choice in this mode.');
  }
  if ((!interactive || options.json) && !options.yes && !options.dryRun) {
    throw new Error('Non-interactive and JSON mutations require --yes.');
  }
}

function printPlan(plan, output) {
  output.write('\nECC guided install preview\n\n');
  output.write('Harness       Channel           Destination\n');
  for (const entry of plan.harnesses) {
    const harness = getHarnessCapability(entry.id);
    output.write(`${harness.label.padEnd(13)} ${entry.channel.padEnd(17)} ${harness.destination}\n`);
  }
  if (plan.request.harnesses.includes('kimi')) {
    output.write('\nKimi note: ECC hooks are not configured; model, provider, and authentication settings are unchanged.\n');

View on GitHub (pinned to 01e15490f0)

Solutions

1. Add --claude-scope <user|project> and --claude-hooks <standard|strict|off> to the command
2. Use --dry-run to preview the plan without requiring --claude-scope/--claude-hooks (dry-run is exempt from the --yes requirement but still needs the Claude choices)
3. Drop claude from --harness if you do not want to configure it

Example fix

// before
node scripts/install-guided.js --harness claude --yes
// after
node scripts/install-guided.js --harness claude --claude-scope user --claude-hooks standard --yes

const interactive = process.stdin.isTTY === true;
const explicitMode = !interactive || argv.includes('--json');
const hasClaude = argv.includes('--harness'); // verify value separately
const needsClaudeExtras = explicitMode && selectsClaude(argv);
if (needsClaudeExtras && (!argv.includes('--claude-scope') || !argv.includes('--claude-hooks'))) {
  throw new Error('Claude needs --claude-scope and --claude-hooks in this mode');
}

function hasClaudeExtras(argv) {
  return argv.includes('--claude-scope') && argv.includes('--claude-hooks');
}

try { validateExecutionMode(options, interactive); }
catch (err) {
  if (/Claude requires explicit/.test(err.message)) {
    console.error(`${err.message} Add --claude-scope and --claude-hooks.`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Running --harness claude --yes in CI without --claude-scope/--claude-hooks, or adding --json to a partially-specified Claude install.

Common situations: Forgetting that Claude needs two extra answers that other harnesses do not, or assuming the interactive defaults apply in non-interactive mode.

Related errors

• Non-interactive guided install requires at least one --harne
• Kimi requires an explicit --profile choice in this mode.
• Non-interactive and JSON mutations require --yes.
• Missing value for ${argument}
• Value for ${argument} is too long.

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/9c7acb9c34f6af53. Report an issue: GitHub.