fix: preserve Claude policy preflight compatibility (#325)

Author: m1ngshum

CHANGELOG.md

@@ -12,6 +12,8 @@ published section (it happened to #170).
 
 ### Fixed
 
+- Keep Claude Code policy checks usable for projects beneath home by recognizing the existing user settings source once. Restore explicit initialization of empty current client configs while retaining strict policy-file parsing and exact original-byte backups.
+
 - Preflight Claude Code stdio file-policy decisions before wrapping or rewriting launches, including original and wrapper argv; refuse local denial or unknown policy without weakening managed controls, and surface unobserved host-policy planes. Guard policy refusals return exit 1, including dry-run; existing wrappers are audited and exact teardown can restore native denial. Previews no longer create the consent/confinement store directory merely to read absent state.
 
 ### Documentation

docs/BACKLOG.md

@@ -65,7 +65,7 @@ writes, recursive whole-home discovery or native policy reimplementation.
 
 ## #122 — Managed-policy-aware setup and wrap plan
 
-**Status:** candidate built by Sol and reviewed/fixed by Astra; 19 native cases and 87 protocol comparisons passed. Not merged or released. See [projection and limits](MANAGED-POLICY-VALIDATION.md). **User/problem:** changing the command to a
+**Status:** built by Sol and reviewed/fixed by Astra; merged in PR #324 but not released. The pre-follow-up candidate passed 19 native cases and 87 protocol comparisons. The home-ancestor and empty-current-config follow-up candidate is verified and Astra reviewed: 22 native cases, three packed initialization cases and 87 protocol checks passed. PR/CI, merge and release are pending. See [projection and limits](MANAGED-POLICY-VALIDATION.md). **User/problem:** changing the command to a
 wrapper can change a client's allow/deny decision. **MVP:** read one supported,
 versioned policy source set and compare current/proposed launches before writes.
 Report exact reason and uncertainty; preserve native restrictions.

docs/MAINTAINER-WORKFLOW.md

@@ -4,9 +4,12 @@
 
 Current published CLI: **v0.50.0**. The bounded Claude Code scope inventory from
 project backlog #141 shipped; broader host/project coverage remains open.
-**#122 managed-policy-aware setup** is a reviewed candidate, not yet merged or
-released; its [candidate validation](MANAGED-POLICY-VALIDATION.md) records the
-bounded Claude Code profile and migration limits. See the [active backlog](BACKLOG.md) and
+**#122 managed-policy-aware setup** merged in PR #324 but remains unreleased.
+The compatibility follow-up candidate is verified and Astra reviewed; PR/CI,
+merge and release are pending. Its [candidate validation](MANAGED-POLICY-VALIDATION.md)
+separates the earlier archive checkpoint from the verified follow-up and records
+the bounded profile and limits.
+See the [active backlog](BACKLOG.md) and
 [v0.50.0 release evidence](RELEASE-2026-11-06-v0.50.0.md) for the actual source,
 companion matrix, archive verification and proof limits. Historical native
 measurements belong to their named versions; this checkpoint is not a new run.

docs/MANAGED-POLICY-VALIDATION.md

@@ -42,6 +42,11 @@ canonicalized), non-regular files, invalid UTF-8, duplicate decoded JSON keys,
 malformed JSON and files larger than 1 MiB. Descriptor/path metadata changes
 during a read produce unknown. Missing files are distinct from unreadable files;
 an empty settings file is conservatively unknown rather than an empty allowlist.
+Only current user-global client-config reads accept empty/whitespace content as
+an empty object, retaining mcpm's explicit-initialization behavior and backing up
+the original bytes before a write. This is not native JSON-validity evidence:
+Claude Code 2.1.296 reports such input as corrupted and performs recovery. The
+strict default remains unchanged for policy files and the scope inventory.
 
 Rules contain exactly one `serverName`, `serverCommand` or `serverUrl` key.
 For stdio, command matching is an exact command-and-arguments array comparison;
@@ -77,7 +82,10 @@ macOS native result or all-client protection is implied.
 A present managed drop-in directory, detected macOS MDM preference file,
 Windows/WSL, alternate config directory, ancestor project settings, worktree
 root selection, or unsupported local policy/source selector refuses the
-transformation as unknown. A top-level `env` in legacy `~/.claude.json` is an
+transformation as unknown. The already-modeled `~/.claude/settings.json` source
+is not counted again as an unsupported ancestor when the project lives beneath
+home; other ancestor settings, including `~/.claude/settings.local.json`, still
+refuse. A top-level `env` in legacy `~/.claude.json` is an
 unsupported additional source and refuses stdio transformations. Supported settings
 JSON must not contain `policyHelper`, `policyHelpers`, `parentSettings`, `managedSourcesBehavior`, `strictPluginOnlyCustomization` or
 `wslInheritsWindowsSettings`; helpers never execute. The plan does not resolve
@@ -111,7 +119,7 @@ credential-variable probe did not reproduce and is not counted as a finding.
 Fresh artifact checks must use the final reviewed bytes, not those vulnerable
 pre-review candidate archives.
 
-### Reviewed candidate checkpoint — 2026-11-06
+### Reviewed pre-follow-up candidate checkpoint — 2026-11-06
 
 Sol built the slice; Astra independently reviewed and fixed confirmed regressions.
 The frozen candidate archive SHA-256 is
@@ -163,6 +171,27 @@ These are candidate observations, separate from the vulnerable published 0.50.0
 baseline and any later actual-published artifact verification. No model/provider
 turn, full host-policy coverage or macOS native-client result is claimed.
 
+### Compatibility follow-up — release pending
+
+PR #324 merged the reviewed implementation, but no release was published. A later
+review found two compatibility regressions: projects below home misclassified
+user settings as an unsupported ancestor, and empty current-config initialization
+was rejected. Both have shared-adapter regressions and narrowly scoped fixes. Node 24.20.0
+typecheck including tooling, build and the full suite pass: 161 files, 3,793 tests
+passed and three skipped. The archive and native/protocol checkpoint above precede these fixes and are not
+proof of the follow-up artifact. Fresh follow-up archive
+`a08c4f6347c4b4d812ebfe93f041ca0b59e62c9722f4a2fc37e514561927caf8`
+passed 22 native policy cases plus three packed initialization cases (empty,
+whitespace and strict empty-policy refusal), and 87 protocol checks with zero
+failures, two expected unsupported and four exclusions. All 66 installed JS files,
+archive, lock, harness/skill hashes and actual container boundaries were
+independently verified. Exact-archive clean-install smoke, coverage (91.56% lines,
+86.72% branches) and the negative-threshold gate passed. Receipts:
+`/private/tmp/mcpm-policy-122-compat-final-native-20261106/verified-final.json`
+and `/private/tmp/mcpm-policy-122-compat-final-protocol-20261106/verified-binding.json`.
+These remain candidate checks; publication verification is separate. The empty-config native probe observed corrupted-JSON recovery, not clean
+native acceptance; compatible mcpm initialization is a separate behavior.
+
 Semantics checked against official
 [managed MCP documentation](https://code.claude.com/docs/en/managed-mcp) and
 [settings source documentation](https://code.claude.com/docs/en/settings) on

src/__tests__/config/adapters/claude-policy.test.ts

@@ -31,6 +31,35 @@ beforeEach(async () => {
 afterEach(async () => { await rm(root, { recursive: true, force: true }); });
 
 describe("Claude Code file policy preflight", () => {
+  it("models user settings once when the project lives below home and still refuses other ancestors", async () => {
+    const project = path.join(home, "repos", "project");
+    await mkdir(project, { recursive: true });
+    await settings({ allowedMcpServers: [{ serverName: "fixture" }] }, "user");
+    const adapter = new ClaudeCodeAdapter({ ...context(), root: project });
+    await adapter.replaceServer(config, "fixture", wrapped());
+    expect(JSON.parse(await readFile(config, "utf8")).mcpServers.fixture).toEqual(wrapped());
+    await settings({ deniedMcpServers: [{ serverCommand: ["node", "fixture.js"] }] }, "user");
+    await expect(adapter.replaceServer(config, "fixture", wrapped())).rejects.toThrow(/underlying.*denied/i);
+    await settings({}, "user");
+    const ancestor = path.join(home, "repos", ".claude");
+    await mkdir(ancestor);
+    await writeFile(path.join(ancestor, "settings.json"), "{}");
+    await expect(adapter.replaceServer(config, "fixture", wrapped())).rejects.toThrow(/Ancestor project settings/);
+    await rm(ancestor, { recursive: true });
+    await writeFile(path.join(home, ".claude", "settings.local.json"), "{}");
+    await expect(adapter.replaceServer(config, "fixture", wrapped())).rejects.toThrow(/Ancestor project settings/);
+  });
+  it.each(["", " \t\r\n"])("initializes an empty current config while retaining strict empty policy handling (%j)", async raw => {
+    await writeFile(config, raw);
+    const adapter = new ClaudeCodeAdapter(context());
+    expect(await adapter.read(config)).toEqual({});
+    await adapter.addServer(config, "fixture", original);
+    expect(JSON.parse(await readFile(config, "utf8")).mcpServers.fixture).toEqual(original);
+    expect(await readFile(`${config}.bak`, "utf8")).toBe(raw);
+    await settings({});
+    await writeFile(path.join(managed, "managed-settings.json"), raw);
+    await expect(adapter.replaceServer(config, "fixture", wrapped())).rejects.toThrow(/managed policy malformed/);
+  });
   it("reproduces original-command deny bypass through replaceServer, before any writes", async () => {
     await settings({ deniedMcpServers: [{ serverCommand: ["node", "fixture.js"] }] });
     const before = await readFile(config, "utf8");

src/__tests__/config/read-bounded-json.test.ts

@@ -22,6 +22,17 @@ it("classifies absent, unreadable, oversized and symlink files without returning
   const link = path.join(dir, "link.json"); await symlink(file, link);
   expect((await readConfig(link)).state).toBe("symlink-skipped");
 });
+it("limits empty initialization to the opted-in current-config read without weakening JSON validation", async () => {
+  await writeFile(file, " \t\r\n");
+  expect(await readConfig(file)).toEqual({ state: "malformed" });
+  expect(await readConfig(file, { allowEmpty: true })).toEqual({ state: "present", value: {} });
+  await writeFile(file, Buffer.from([0xff]));
+  expect(await readConfig(file, { allowEmpty: true })).toEqual({ state: "malformed" });
+  await writeFile(file, '{"mcpServers":{},"mcpServers":{}}');
+  expect(await readConfig(file, { allowEmpty: true })).toEqual({ state: "malformed" });
+  await writeFile(file, " ".repeat(1024 * 1024 + 1));
+  expect(await readConfig(file, { allowEmpty: true })).toEqual({ state: "too-large" });
+});
 it("rejects changes during a read rather than returning a clean snapshot", async () => {
   await writeFile(file, "{}");
   const actual = await vi.importActual<typeof import("node:fs/promises")>("node:fs/promises");

src/config/adapters/claude-code.ts

@@ -26,7 +26,7 @@ export class ClaudeCodeAdapter extends BaseAdapter {
 
   protected override async readRaw(configPath: string): Promise<Record<string, unknown>> {
     const directory = await realpath(path.dirname(configPath)).catch(() => path.dirname(configPath));
-    const read = await readConfig(path.join(directory, path.basename(configPath)));
+    const read = await readConfig(path.join(directory, path.basename(configPath)), { allowEmpty: true });
     if (read.state !== "present" && read.state !== "missing") {
       throw new Error(`Claude Code file policy unknown: Current configuration ${read.state}`);
     }

src/config/claude-policy.ts

@@ -118,7 +118,9 @@ export async function planClaudePolicyChange(configPath: string, name: string, p
     ];
     for (let ancestor = path.dirname(root); ; ancestor = path.dirname(ancestor)) {
       for (const name of ["settings.json", "settings.local.json"]) {
-        const state = await inspect(path.join(ancestor, ".claude", name));
+        const candidate = path.join(ancestor, ".claude", name);
+        if (candidate === files[0].path) continue;
+        const state = await inspect(candidate);
         if (state !== "missing") return refuse("Ancestor project settings require unsupported root/selection resolution");
       }
       if (ancestor === path.dirname(ancestor)) break;
@@ -145,7 +147,7 @@ export async function planClaudePolicyChange(configPath: string, name: string, p
     if (exclusive.state !== "missing") return refuse(exclusive.state === "present" ? "managed-mcp exclusive control: user-global definitions are not selected" : `managed-mcp policy ${exclusive.state}`, exclusive.state === "present" ? "blocked" : "unknown");
     if (managedSettings.managedMcpServers && Object.hasOwn(managedSettings.managedMcpServers, name)) return refuse("managedMcpServers supplies this name; user-global definition is shadowed", "blocked");
     const configDirectory = await realpath(path.dirname(configPath)).catch(() => path.dirname(configPath));
-    const current = await readConfig(path.join(configDirectory, path.basename(configPath)));
+    const current = await readConfig(path.join(configDirectory, path.basename(configPath)), { allowEmpty: true });
     if (current.state !== "missing" && current.state !== "present") return refuse(`Current configuration ${current.state}`);
     if (current.value?.env !== undefined) return refuse("Legacy global configuration environment is outside the supported profile");
     const serverMap = current.value?.mcpServers;

src/config/read-bounded-json.ts

@@ -38,7 +38,7 @@ function duplicateKeys(node: Node): boolean {
   return node.children?.some(duplicateKeys) ?? false;
 }
 
-export async function readConfig(file: string): Promise<{ state: FileState; value?: Record<string, unknown> }> {
+export async function readConfig(file: string, options: { allowEmpty?: boolean } = {}): Promise<{ state: FileState; value?: Record<string, unknown> }> {
   const state = await inspect(file);
   if (state !== "present") return { state };
   try {
@@ -64,6 +64,7 @@ export async function readConfig(file: string): Promise<{ state: FileState; valu
       const bytes = buffer.subarray(0, length);
       if (!isUtf8(bytes)) return { state: "malformed" };
       const raw = bytes.toString("utf8");
+      if (options.allowEmpty && raw.trim() === "") return { state: "present", value: {} };
       const errors: ParseError[] = [];
       const tree = parseTree(raw, errors, { disallowComments: true, allowTrailingComma: false });
       if (!tree || errors.length || duplicateKeys(tree)) return { state: "malformed" };