affaan-m/ECC · error · Error

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

Error message

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

What it means

In non-interactive or --json mode, validateExecutionMode() refuses to invent defaults for Claude. Because there is no prompt to ask about scope (user/project) or hooks mode, both --claude-scope and --claude-hooks must be supplied explicitly whenever 'claude' is among the selected harnesses. Omitting either aborts the run.

Solutions

1. Add both --claude-scope <user|project> and --claude-hooks <value> to the command.
2. If claude is not actually wanted, remove --harness claude from the list.
3. In wrapper scripts, derive and pass the two flags whenever claude is selected.

Example fix

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

if (harnesses.includes('claude') && (!claudeScope || !claudeHooks)) { throw new Error('claude needs --claude-scope and --claude-hooks'); }

try { main(); } catch (e) { if (/Claude requires explicit/.test(e.message)) { console.error('Supply --claude-scope <scope> --claude-hooks <mode>'); process.exit(2); } throw e; }

When it happens

Trigger: Non-interactive run or run with --json where options.harnesses includes 'claude' but options.claudeScope or options.claudeHooks is falsy (flag absent).

Common situations: CI installs selecting claude with only --harness claude --yes; scripts migrated from interactive usage that never needed the flags before; JSON-mode automation adding claude to the harness list without updating flags.

Understand the failure class

Background: "Must pass :limit option" / "Missing required option" — required option errors explained — this error's family across 41 libraries.

Related errors

• Kimi requires an explicit --profile choice in this mode.
• Non-interactive guided install requires at least one…
• An executable is required after --.
• An install config path is required
• At least one --target is required for handoffs.

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/9c7acb9c34f6af53. Report an issue: GitHub.

Appendix: source

Thrown at scripts/install-guided.js:193

    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 8321021c54)