fix(acr): SET typo-gates unknown-key false positives (M-BUG-10)

The CC settings schema is passthrough (verified against the 2.1.193 binary): it
forwards unrecognized keys unchanged rather than rejecting them, so an arbitrary
unknown key is valid/forward-compatible, not an error — the finding's "silently
ignored" claim was factually wrong. The only real risk is a TYPO of a real key
(the intended setting then silently has no effect). Fix: flag an unknown key only
when it closely matches a known key (new levenshtein helper; edit distance <= 2,
both keys >= 4 chars); severity medium -> low; honest passthrough framing in the
scanner + humanizer. Also refreshed KNOWN_KEYS with 6 binary-verified keys
(agentPushNotifEnabled, remoteControlAtStartup, skipAutoPermissionPrompt,
skipDangerousModePermissionPrompt, skipWorkflowUsageWarning, tui). Suite 1341/0
(+12). Frozen v5.0.0 snapshots untouched (0 CA-SET findings there), no re-seed.
Dogfood ~/.claude/settings.json 6->0 (all 6 keys above were false unknown-key
findings; 0 typo flags introduced across 167 walked files).

scanners/lib/humanizer-data.mjs

@@ -96,10 +96,10 @@ export const TRANSLATIONS = {
   // ─────────────────────────────────────────────────────────────
   SET: {
     static: {
-      'Unknown settings key': {
-        title: 'A settings key isn\'t recognized',
-        description: 'A key in your settings file isn\'t one Claude Code understands. It will be ignored.',
-        recommendation: 'Check the key name for typos, or remove the key if it\'s no longer in use.',
+      'Possible typo in settings key': {
+        title: 'A settings key looks like a typo',
+        description: 'A key in your settings file isn\'t recognized, but it\'s very close to a real one — likely a typo. Claude Code forwards unrecognized keys unchanged rather than rejecting them, so a misspelled key silently has no effect.',
+        recommendation: 'Check the suggested key name. Fix the spelling, or keep the key if it\'s intentional (e.g. a newer key this audit doesn\'t know yet).',
       },
       'Deprecated settings key': {
         title: 'A settings key is no longer supported',

scanners/lib/string-utils.mjs

@@ -43,6 +43,41 @@ export function isSimilar(a, b, threshold = 0.8) {
   return similarity >= threshold;
 }
 
+/**
+ * Levenshtein edit distance between two strings (insertions, deletions,
+ * substitutions; a transposition counts as 2). Used for typo detection on
+ * settings keys. Zero external dependencies, O(a*b) with two rolling rows.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function levenshtein(a, b) {
+  if (a === b) return 0;
+  const al = a.length;
+  const bl = b.length;
+  if (al === 0) return bl;
+  if (bl === 0) return al;
+  let prev = new Array(bl + 1);
+  let curr = new Array(bl + 1);
+  for (let j = 0; j <= bl; j++) prev[j] = j;
+  for (let i = 1; i <= al; i++) {
+    curr[0] = i;
+    const ac = a.charCodeAt(i - 1);
+    for (let j = 1; j <= bl; j++) {
+      const cost = ac === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        prev[j] + 1,        // deletion
+        curr[j - 1] + 1,    // insertion
+        prev[j - 1] + cost, // substitution
+      );
+    }
+    const tmp = prev;
+    prev = curr;
+    curr = tmp;
+  }
+  return prev[bl];
+}
+
 /**
  * Extract all key-like patterns from a settings.json or similar config.
  * @param {object} obj

scanners/settings-validator.mjs

@@ -8,11 +8,11 @@ import { readTextFile } from './lib/file-discovery.mjs';
 import { finding, scannerResult } from './lib/output.mjs';
 import { SEVERITY } from './lib/severity.mjs';
 import { parseJson } from './lib/yaml-parser.mjs';
-import { extractKeys } from './lib/string-utils.mjs';
+import { extractKeys, levenshtein } from './lib/string-utils.mjs';
 
 const SCANNER = 'SET';
 
-/** Known top-level settings.json keys (as of CC 2.1.181 / June 2026) */
+/** Known top-level settings.json keys (as of CC 2.1.193 / June 2026) */
 const KNOWN_KEYS = new Set([
   'additionalDirectories',
   'agent', 'allowAllClaudeAiMcps', 'allowedChannelPlugins', 'allowedHttpHookUrls',
@@ -37,6 +37,9 @@ const KNOWN_KEYS = new Set([
   'spinnerTipsOverride', 'spinnerVerbs', 'statusLine', 'strictKnownMarketplaces',
   'useAutoModeDuringPlan', 'voiceEnabled', 'wheelScrollAccelerationEnabled',
   'worktree', '$schema',
+  // CC 2.1.193 binary-verified (M-BUG-10): present as quoted string literals in the binary
+  'agentPushNotifEnabled', 'remoteControlAtStartup', 'skipAutoPermissionPrompt',
+  'skipDangerousModePermissionPrompt', 'skipWorkflowUsageWarning', 'tui',
 ]);
 
 /** Deprecated keys with migration info */
@@ -75,6 +78,16 @@ const VALID_EFFORT_LEVELS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
  * a project root to walks/discovery, inflating per-turn cost and confusing scope. */
 const ADDITIONAL_DIRS_THRESHOLD = 2;
 
+/** M-BUG-10: the CC settings schema is passthrough — it forwards unrecognized
+ * keys unchanged rather than rejecting them, so an arbitrary unknown key is
+ * valid/forward-compatible, not an error. The only real risk is a TYPO of a
+ * real key (the intended setting silently does nothing), so an unknown key is
+ * flagged ONLY when it closely matches a known key: edit distance within
+ * TYPO_MAX_DISTANCE and both keys at least TYPO_MIN_LEN chars (short keys are
+ * too noisy for reliable edit-distance matching). */
+const TYPO_MAX_DISTANCE = 2;
+const TYPO_MIN_LEN = 4;
+
 /** The only valid sub-keys of `autoMode`, each a prose-rule string array
  * (the literal "$defaults" is a valid entry). Verified against
  * code.claude.com/docs/en/auto-mode-config. */
@@ -115,17 +128,32 @@ export async function scan(targetPath, discovery) {
       continue;
     }
 
-    // Check for unknown keys
+    // Check for unknown keys — typo gate (M-BUG-10). The CC settings schema is
+    // passthrough, so an unrecognized key is NOT an error; only a typo of a real
+    // key is (the intended setting silently does nothing). Flag a key only when
+    // it closely matches a known key; an unknown key far from every known key is
+    // treated as valid/forward-compatible and emitted nothing.
     for (const key of Object.keys(parsed)) {
-      if (!KNOWN_KEYS.has(key)) {
+      if (KNOWN_KEYS.has(key)) continue;
+      let nearest = null;
+      let best = Infinity;
+      for (const known of KNOWN_KEYS) {
+        if (Math.min(key.length, known.length) < TYPO_MIN_LEN) continue;
+        const d = levenshtein(key, known);
+        if (d <= TYPO_MAX_DISTANCE && d < best) {
+          best = d;
+          nearest = known;
+        }
+      }
+      if (nearest) {
         findings.push(finding({
           scanner: SCANNER,
-          severity: SEVERITY.medium,
-          title: 'Unknown settings key',
-          description: `${file.relPath}: "${key}" is not a recognized settings.json key. It will be silently ignored.`,
+          severity: SEVERITY.low,
+          title: 'Possible typo in settings key',
+          description: `${file.relPath}: "${key}" is not a recognized settings.json key, but it closely matches "${nearest}". Claude Code forwards unrecognized keys unchanged (it does not reject them), so if "${key}" is a typo of "${nearest}" the intended setting silently has no effect.`,
           file: file.absPath,
           evidence: key,
-          recommendation: 'Check spelling. See https://json.schemastore.org/claude-code-settings.json for valid keys.',
+          recommendation: `Did you mean "${nearest}"? Fix the spelling, or keep "${key}" if it is intentional (e.g. a newer settings key this audit does not recognize yet).`,
           autoFixable: false,
         }));
       }

tests/lib/string-utils.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { lineCount, truncate, isSimilar, extractKeys, normalizePath } from '../../scanners/lib/string-utils.mjs';
+import { lineCount, truncate, isSimilar, extractKeys, normalizePath, levenshtein } from '../../scanners/lib/string-utils.mjs';
 
 describe('lineCount', () => {
   it('counts lines correctly', () => {
@@ -90,6 +90,42 @@ describe('extractKeys', () => {
   });
 });
 
+describe('levenshtein', () => {
+  it('returns 0 for identical strings', () => {
+    assert.strictEqual(levenshtein('permissions', 'permissions'), 0);
+  });
+
+  it('counts a single substitution as 1', () => {
+    assert.strictEqual(levenshtein('model', 'modet'), 1);
+  });
+
+  it('counts a single deletion as 1 (permisions → permissions)', () => {
+    assert.strictEqual(levenshtein('permisions', 'permissions'), 1);
+  });
+
+  it('counts a single insertion as 1', () => {
+    assert.strictEqual(levenshtein('hooks', 'hooks2'), 1);
+  });
+
+  it('counts a transposition as 2 (standard Levenshtein)', () => {
+    assert.strictEqual(levenshtein('import', 'improt'), 2);
+  });
+
+  it('returns the other length when one string is empty', () => {
+    assert.strictEqual(levenshtein('', 'abc'), 3);
+    assert.strictEqual(levenshtein('abc', ''), 3);
+    assert.strictEqual(levenshtein('', ''), 0);
+  });
+
+  it('is symmetric', () => {
+    assert.strictEqual(levenshtein('effortLevel', 'efortLevel'), levenshtein('efortLevel', 'effortLevel'));
+  });
+
+  it('gives a large distance for unrelated keys', () => {
+    assert.ok(levenshtein('unknownKey123', 'permissions') > 2);
+  });
+});
+
 describe('normalizePath', () => {
   it('expands ~ to HOME', () => {
     const home = process.env.HOME;

tests/scanners/settings-validator.test.mjs

@@ -47,10 +47,12 @@ describe('SET scanner — broken project', () => {
     result = await scan(resolve(FIXTURES, 'broken-project'), discovery);
   });
 
-  it('detects unknown settings key', () => {
-    // CA-SET-001 in broken-project, evidence='unknownKey123'.
+  it('does NOT flag an arbitrary unknown key (CC schema is passthrough)', () => {
+    // M-BUG-10: "unknownKey123" is not close to any known key, so it is a
+    // valid forward-compatible / passthrough key — NOT a typo. Claude Code
+    // forwards unrecognized keys unchanged, so flagging it is a false positive.
     const found = result.findings.some(f => f.scanner === 'SET' && /unknownKey123/.test(f.evidence || ''));
-    assert.ok(found, 'Should detect unknownKey123');
+    assert.ok(!found, 'unknownKey123 is far from every known key → must not be flagged');
   });
 
   it('detects deprecated key (includeCoAuthoredBy)', () => {
@@ -192,6 +194,63 @@ describe('SET scanner — CC 2.1.114→181 valid keys (Batch 1 false-positive fi
   });
 });
 
+describe('SET scanner — unknown-key typo gate (M-BUG-10)', () => {
+  // The CC settings schema is passthrough: it forwards unrecognized keys
+  // unchanged rather than rejecting them, so an arbitrary unknown key is
+  // valid/forward-compatible and must NOT be flagged. The only real risk is a
+  // TYPO of a real key (the intended setting silently has no effect), so the
+  // scanner flags ONLY unknown keys that closely match a known key.
+  // Path-guard blocks committing settings.json fixtures → materialize a temp one.
+  let tmpRoot;
+  let result;
+  const TYPO_TITLE = 'Possible typo in settings key';
+
+  beforeEach(async () => {
+    resetCounter();
+    tmpRoot = await mkdtemp(join(tmpdir(), 'ca-set-typo-'));
+    await mkdir(join(tmpRoot, '.claude'), { recursive: true });
+    const settings = {
+      $schema: 'https://json.schemastore.org/claude-code-settings.json',
+      permisions: { deny: ['Read(./.env)'] },   // TYPO of "permissions" (edit distance 1)
+      someNewKey2027: true,                      // forward-compat / passthrough — far from every known key
+      permissions: { deny: ['Read(./.env)'], allow: ['Bash(npm run *)'] },
+    };
+    await writeFile(
+      join(tmpRoot, '.claude', 'settings.json'),
+      JSON.stringify(settings, null, 2) + '\n',
+      'utf8',
+    );
+    const discovery = await discoverConfigFiles(tmpRoot);
+    result = await scan(tmpRoot, discovery);
+  });
+
+  afterEach(async () => {
+    if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('flags a likely typo ("permisions") and suggests the nearest known key', () => {
+    const typo = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'permisions');
+    assert.ok(typo, `expected a typo finding for "permisions"; got: ${result.findings.map(f => `${f.title}:${f.evidence || ''}`).join(' | ')}`);
+    assert.equal(typo.title, TYPO_TITLE);
+    assert.match(typo.recommendation, /permissions/, 'recommendation suggests the nearest known key');
+  });
+
+  it('marks the typo finding as low severity (passthrough → not a hard error)', () => {
+    const typo = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'permisions');
+    assert.equal(typo.severity, 'low');
+  });
+
+  it('does NOT flag a forward-compatible key far from any known key', () => {
+    const fwd = result.findings.find(f => f.scanner === 'SET' && f.evidence === 'someNewKey2027');
+    assert.equal(fwd, undefined, 'someNewKey2027 is far from every known key → passthrough, not flagged');
+  });
+
+  it('emits exactly one typo finding for this file', () => {
+    const typos = result.findings.filter(f => f.scanner === 'SET' && f.title === TYPO_TITLE);
+    assert.equal(typos.length, 1, `expected exactly one typo finding; got: ${typos.map(f => f.evidence).join(', ')}`);
+  });
+});
+
 describe('SET scanner — empty project', () => {
   let result;
   beforeEach(async () => {