brainclaw 1.8.0 → 1.9.0

package/dist/core/agent-files.js

@@ -2,180 +2,14 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
 import yaml from 'yaml';
-import { MCP_HEADLESS_AUTO_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from '../commands/mcp.js';
+import { MCP_HEADLESS_AUTO_TOOL_NAMES, MCP_CANONICAL_GRAMMAR_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from '../commands/mcp.js';
 import { renderToml, tomlArrayTableHasEntry } from './toml-writer.js';
-/**
- * Resolve the brainclaw command for MCP configs.
- * Returns `{ command: "<node>", args: ["<cli.js>", "mcp"] }` so the config
- * works in non-login shells (VS Code Server, MCP subprocesses) on all OSes.
- *
- * Strategy:
- * 1. Find the brainclaw bin via which/where
- * 2. Trace from the bin/shim to the actual cli.js entry point
- * 3. Pair it with the absolute node path
- * Falls back to 'npx brainclaw mcp' if resolution fails.
- */
-function resolveBrainclawMcpCommand() {
-    const nodeBin = process.execPath;
-    // 1. Try to resolve the cli.js from the installed brainclaw binary
-    const cliJs = resolveBrainclawCliJs();
-    if (cliJs) {
-        return { command: nodeBin, args: [cliJs, 'mcp'] };
-    }
-    // 2. Fallback: npx (relies on PATH, may resolve wrong version)
-    return { command: 'npx', args: ['brainclaw', 'mcp'] };
-}
-/**
- * Trace from the brainclaw bin/shim to the actual dist/cli.js file.
- * Works on Windows (.cmd shim), macOS/Linux (symlink to bin stub).
- */
-function resolveBrainclawCliJs() {
-    // Strategy A: find via which/where and trace to cli.js
-    const whichCmd = os.platform() === 'win32' ? 'where' : 'which';
-    try {
-        const result = spawnSync(whichCmd, ['brainclaw'], { encoding: 'utf-8', timeout: 3000 });
-        if (result.status === 0) {
-            const resolved = result.stdout.trim().split(/\r?\n/)[0]?.trim();
-            if (resolved) {
-                const cliJs = traceToCliJs(resolved);
-                if (cliJs)
-                    return cliJs;
-            }
-        }
-    }
-    catch {
-        // Non-fatal — try next strategy
-    }
-    // Strategy B: resolve from this file's own package (we ARE brainclaw)
-    try {
-        const ownCliJs = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'cli.js');
-        if (fs.existsSync(ownCliJs))
-            return ownCliJs;
-    }
-    catch {
-        // Non-fatal
-    }
-    return undefined;
-}
-/**
- * Given a bin path (shim or symlink), trace to the dist/cli.js entry point.
- *
- * Windows: .cmd shim contains a line like `"%_prog%" "%dp0%\node_modules\brainclaw\dist\cli.js" %*`
- * Unix: bin is a symlink → resolve to real path → go up to package root → dist/cli.js
- */
-function traceToCliJs(binPath) {
-    const isWindows = os.platform() === 'win32';
-    if (isWindows) {
-        // Read the .cmd shim and extract the cli.js path
-        const cmdPath = binPath.endsWith('.cmd') ? binPath : `${binPath}.cmd`;
-        try {
-            const content = fs.readFileSync(cmdPath, 'utf-8');
-            // Match patterns like: "%dp0%\node_modules\brainclaw\dist\cli.js"
-            const match = content.match(/%dp0%\\([^\s"]+cli\.js)/);
-            if (match) {
-                const shimDir = path.dirname(cmdPath);
-                const cliJs = path.resolve(shimDir, match[1]);
-                if (fs.existsSync(cliJs))
-                    return cliJs;
-            }
-        }
-        catch {
-            // Fall through
-        }
-    }
-    else {
-        // Unix: follow symlink chain to the real bin, then find cli.js
-        try {
-            const realBin = fs.realpathSync(binPath);
-            // Typical layout: .../node_modules/.bin/brainclaw → ../brainclaw/dist/cli.js
-            // Or: .../node_modules/brainclaw/dist/cli.js (direct)
-            if (realBin.endsWith('cli.js') && fs.existsSync(realBin))
-                return realBin;
-            // The bin stub typically lives at node_modules/brainclaw/dist/cli.js
-            // or node_modules/.bin/brainclaw → ../brainclaw/dist/cli.js
-            const packageRoot = findPackageRoot(realBin);
-            if (packageRoot) {
-                const cliJs = path.join(packageRoot, 'dist', 'cli.js');
-                if (fs.existsSync(cliJs))
-                    return cliJs;
-            }
-        }
-        catch {
-            // Fall through
-        }
-    }
-    return undefined;
-}
-/** Walk up from a file to find the nearest directory containing package.json with name "brainclaw". */
-function findPackageRoot(from) {
-    let dir = path.dirname(from);
-    for (let i = 0; i < 10; i++) {
-        const pkgPath = path.join(dir, 'package.json');
-        try {
-            if (fs.existsSync(pkgPath)) {
-                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-                if (pkg.name === 'brainclaw')
-                    return dir;
-            }
-        }
-        catch { /* continue */ }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return undefined;
-}
-/** Cached MCP command — resolved once per process. */
-let cachedMcpCommand;
-function getBrainclawMcpCommand() {
-    if (!cachedMcpCommand) {
-        cachedMcpCommand = resolveBrainclawMcpCommand();
-    }
-    return cachedMcpCommand;
-}
-/** Reset the cached MCP command so it gets re-resolved on next access. */
-export function resetMcpCommandCache() {
-    cachedMcpCommand = undefined;
-}
-/** Module-level flag: when true, brainclawMcpEntry overwrites existing paths. */
-let _forceResolve = false;
-/**
- * Build a complete MCP server entry with relay model env injection.
- * Merges with the existing entry to preserve manual edits (e.g. custom command
- * path, additional env vars, extra args). Only sets defaults for missing fields.
- *
- * When `workspacePath` is provided, injects BRAINCLAW_CWD into the env so
- * the MCP server resolves the correct workspace root regardless of the IDE's
- * process.cwd() at launch time.
- */
-function brainclawMcpEntry(agentName, existing, workspacePath) {
-    const defaults = getBrainclawMcpCommand();
-    const ex = isJsonObject(existing) ? existing : {};
-    const exEnv = isJsonObject(ex.env) ? ex.env : {};
-    // When _forceResolve is true (post-upgrade), always use newly resolved paths.
-    // Otherwise preserve existing command if it's an absolute path (manual edit).
-    // CRITICAL: once we decide to preserve the command, we MUST also preserve
-    // the args. Previously args was always overwritten, which silently clobbered
-    // manual customizations (--cwd, --debug, etc.) and broke setups on DGX.
-    // See trp#12 + pln#450.
-    const useExisting = !_forceResolve && typeof ex.command === 'string' && ex.command !== 'npx';
-    const existingArgs = Array.isArray(ex.args) ? ex.args : undefined;
-    return {
-        command: useExisting ? ex.command : defaults.command,
-        args: useExisting && existingArgs ? existingArgs : defaults.args,
-        // Merge env: preserve user-added vars, ensure BRAINCLAW_AGENT is set
-        env: {
-            ...exEnv,
-            BRAINCLAW_AGENT: agentName,
-            ...(workspacePath ? { BRAINCLAW_CWD: workspacePath } : {}),
-        },
-        // Preserve timeout if set
-        ...(typeof ex.timeout === 'number' ? { timeout: ex.timeout } : {}),
-    };
-}
+import { PROTOCOL_SKILLS, renderProtocolSkill } from './protocol-skills.js';
+import { getInstalledBrainclawVersion } from './brainclaw-version.js';
+import { isAgentInstalledPerInventory } from './agent-inventory.js';
+import { brainclawMcpEntry, buildHookCommand, getBclawCliParts, getBrainclawMcpCommand, isForceResolveEnabled, quoteShellArg, resetMcpCommandCache, withForcedResolve, } from './mcp-command-resolution.js';
+export { resetMcpCommandCache };
 export const BRAINCLAW_SECTION_START = '<!-- brainclaw:start -->';
 export const BRAINCLAW_SECTION_END = '<!-- brainclaw:end -->';
 export function buildBrainclawSection(storageDir) {
@@ -295,8 +129,10 @@ export function ensureGitignoreEntries(cwd, entries) {
     const toAdd = entries.filter((e) => !lines.has(e));
     if (toAdd.length === 0)
         return;
+    const banner = '# Agent instruction files (generated by brainclaw)';
+    const bannerBlock = lines.has(banner) ? '' : `${banner}\n`;
     const separator = current.trimEnd().length > 0 ? '\n' : '';
-    const next = `${current.trimEnd()}${separator}\n# Agent instruction files (generated by brainclaw)\n${toAdd.join('\n')}\n`;
+    const next = `${current.trimEnd()}${separator}\n${bannerBlock}${toAdd.join('\n')}\n`;
     fs.writeFileSync(gitignorePath, next, 'utf-8');
 }
 export function collectWorkspaceGitignoreEntries(cwd, results) {
@@ -506,32 +342,289 @@ export const LOCAL_ONLY_AGENT_WORKSPACE_FILES = [
 function isJsonObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/**
+ * Read a JSON config file. Returns `{}` when the file doesn't exist, and
+ * `undefined` when the file exists but cannot be parsed as a JSON object.
+ * Callers MUST treat `undefined` as "abort the write" — overwriting a file we
+ * could not parse destroys user-owned configuration (a UTF-8 BOM or JSONC
+ * comments used to wipe entire settings files this way).
+ */
 function readJsonObject(filePath) {
     if (!fs.existsSync(filePath)) {
         return {};
     }
     try {
-        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-        return isJsonObject(parsed) ? parsed : {};
+        const parsed = JSON.parse(stripBom(fs.readFileSync(filePath, 'utf-8')));
+        return isJsonObject(parsed) ? parsed : undefined;
     }
     catch {
-        return {};
+        return undefined;
     }
 }
+/**
+ * Same contract as readJsonObject, but tolerates JSONC comments and trailing
+ * commas (VS Code files). Token-based, so comments inside string values
+ * ("https://…") never corrupt the parse.
+ */
 function readJsoncObject(filePath) {
     if (!fs.existsSync(filePath)) {
         return {};
     }
     try {
-        const raw = fs.readFileSync(filePath, 'utf-8');
-        const withoutBlockComments = raw.replace(/\/\*[\s\S]*?\*\//g, '');
-        const withoutLineComments = withoutBlockComments.replace(/^\s*\/\/.*$/gm, '');
-        const parsed = JSON.parse(withoutLineComments);
-        return isJsonObject(parsed) ? parsed : {};
+        const parsed = parseJsonc(stripBom(fs.readFileSync(filePath, 'utf-8')));
+        return isJsonObject(parsed) ? parsed : undefined;
     }
     catch {
-        return {};
+        return undefined;
+    }
+}
+/**
+ * Result for a writer that found an unparseable existing file: warn once and
+ * leave the file exactly as it is.
+ */
+function skippedAutoConfigResult(kind, label, filePath, relativePath) {
+    const warning = `cannot parse ${filePath} — file left untouched. Fix its syntax (or remove it) and re-run.`;
+    process.stderr.write(`[brainclaw] Warning: ${warning}\n`);
+    return {
+        kind,
+        label,
+        created: false,
+        updated: false,
+        filePath,
+        ...(relativePath ? { relativePath } : {}),
+        skipped: true,
+        warning,
+    };
+}
+/** Tokenize JSONC, preserving offsets. Returns undefined on malformed input. */
+function tokenizeJsonc(text) {
+    const tokens = [];
+    let i = 0;
+    const n = text.length;
+    while (i < n) {
+        const ch = text[i];
+        if (ch === ' ' || ch === '\t' || ch === '\r' || ch === '\n') {
+            i++;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '/') {
+            while (i < n && text[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '/' && text[i + 1] === '*') {
+            const close = text.indexOf('*/', i + 2);
+            if (close === -1)
+                return undefined;
+            i = close + 2;
+            continue;
+        }
+        if (ch === '"') {
+            const start = i;
+            i++;
+            while (i < n && text[i] !== '"') {
+                i += text[i] === '\\' ? 2 : 1;
+            }
+            if (i >= n)
+                return undefined;
+            i++;
+            let value;
+            try {
+                value = JSON.parse(text.slice(start, i));
+            }
+            catch {
+                return undefined;
+            }
+            tokens.push({ type: 'string', start, end: i, value });
+            continue;
+        }
+        if ('{}[]:,'.includes(ch)) {
+            tokens.push({ type: 'punct', start: i, end: i + 1, value: ch });
+            i++;
+            continue;
+        }
+        const start = i;
+        while (i < n && !' \t\r\n{}[]:,/"'.includes(text[i]))
+            i++;
+        if (i === start)
+            return undefined;
+        tokens.push({ type: 'literal', start, end: i });
+    }
+    return tokens;
+}
+/** Parse JSONC text (comments + trailing commas) into a JS value. Throws on malformed input. */
+function parseJsonc(text) {
+    const tokens = tokenizeJsonc(text);
+    if (!tokens)
+        throw new Error('malformed JSONC');
+    let pos = 0;
+    const next = () => {
+        const t = tokens[pos];
+        if (!t)
+            throw new Error('unexpected end of JSONC');
+        return t;
+    };
+    const parseValue = () => {
+        const t = next();
+        if (t.type === 'string') {
+            pos++;
+            return t.value;
+        }
+        if (t.type === 'literal') {
+            pos++;
+            return JSON.parse(text.slice(t.start, t.end));
+        }
+        if (t.value === '{') {
+            pos++;
+            const obj = {};
+            if (next().value === '}') {
+                pos++;
+                return obj;
+            }
+            for (;;) {
+                const key = next();
+                if (key.type !== 'string')
+                    throw new Error('expected object key');
+                pos++;
+                if (next().value !== ':')
+                    throw new Error('expected colon');
+                pos++;
+                obj[key.value] = parseValue();
+                const sep = next();
+                if (sep.value === ',') {
+                    pos++;
+                    if (next().value === '}') {
+                        pos++;
+                        return obj;
+                    }
+                    continue;
+                }
+                if (sep.value === '}') {
+                    pos++;
+                    return obj;
+                }
+                throw new Error('expected comma or closing brace');
+            }
+        }
+        if (t.value === '[') {
+            pos++;
+            const arr = [];
+            if (next().value === ']') {
+                pos++;
+                return arr;
+            }
+            for (;;) {
+                arr.push(parseValue());
+                const sep = next();
+                if (sep.value === ',') {
+                    pos++;
+                    if (next().value === ']') {
+                        pos++;
+                        return arr;
+                    }
+                    continue;
+                }
+                if (sep.value === ']') {
+                    pos++;
+                    return arr;
+                }
+                throw new Error('expected comma or closing bracket');
+            }
+        }
+        throw new Error('unexpected token');
+    };
+    const value = parseValue();
+    if (pos !== tokens.length)
+        throw new Error('trailing content after JSONC value');
+    return value;
+}
+/** Returns the token index just past the value starting at tokens[idx], or undefined. */
+function skipJsoncValue(tokens, idx) {
+    const tok = tokens[idx];
+    if (!tok)
+        return undefined;
+    if (tok.type === 'string' || tok.type === 'literal')
+        return idx + 1;
+    if (tok.value === '{' || tok.value === '[') {
+        const close = tok.value === '{' ? '}' : ']';
+        let depth = 0;
+        for (let i = idx; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t.type !== 'punct')
+                continue;
+            if (t.value === tok.value)
+                depth++;
+            else if (t.value === close && --depth === 0)
+                return i + 1;
+        }
+    }
+    return undefined;
+}
+/**
+ * Set `keyPath` to `valueJson` (a rendered JSON snippet) inside a JSONC text,
+ * preserving all comments, whitespace, and unrelated content byte-for-byte.
+ * Missing intermediate objects are created. Returns undefined when the input
+ * cannot be edited safely (malformed, non-object root, non-object intermediate).
+ */
+function setJsoncValue(text, keyPath, valueJson) {
+    if (keyPath.length === 0)
+        return undefined;
+    const tokens = tokenizeJsonc(text);
+    if (!tokens || tokens.length === 0 || tokens[0].value !== '{')
+        return undefined;
+    let objStart = 0;
+    for (let depth = 0; depth < keyPath.length; depth++) {
+        const key = keyPath[depth];
+        const openTok = tokens[objStart];
+        if (openTok.value !== '{')
+            return undefined;
+        const objEnd = skipJsoncValue(tokens, objStart);
+        if (objEnd === undefined)
+            return undefined;
+        // Scan direct members of this object for `key`
+        let i = objStart + 1;
+        let found = -1;
+        while (i < objEnd - 1) {
+            const keyTok = tokens[i];
+            if (!keyTok || keyTok.type !== 'string')
+                return undefined;
+            const colon = tokens[i + 1];
+            if (!colon || colon.value !== ':')
+                return undefined;
+            const valueIdx = i + 2;
+            const valueEnd = skipJsoncValue(tokens, valueIdx);
+            if (valueEnd === undefined)
+                return undefined;
+            if (keyTok.value === key) {
+                found = valueIdx;
+                break;
+            }
+            i = valueEnd;
+            if (tokens[i]?.value === ',')
+                i++;
+        }
+        if (found === -1) {
+            // Key absent — insert it (with the remaining path nested) after the brace.
+            let snippet = valueJson;
+            for (let d = keyPath.length - 1; d > depth; d--) {
+                snippet = `{ ${JSON.stringify(keyPath[d])}: ${snippet} }`;
+            }
+            const hasMembers = tokens[objStart + 1]?.value !== '}';
+            const insertAt = openTok.end;
+            const member = `${JSON.stringify(key)}: ${snippet}`;
+            const insertion = hasMembers ? ` ${member},` : ` ${member} `;
+            return text.slice(0, insertAt) + insertion + text.slice(insertAt);
+        }
+        if (depth === keyPath.length - 1) {
+            const valueEnd = skipJsoncValue(tokens, found);
+            return text.slice(0, tokens[found].start) + valueJson + text.slice(tokens[valueEnd - 1].end);
+        }
+        objStart = found;
     }
+    return undefined;
 }
 function writeTextFileIfChanged(filePath, content) {
     const existed = fs.existsSync(filePath);
@@ -548,7 +641,17 @@ function writeJsonFileIfChanged(filePath, next) {
     return writeTextFileIfChanged(filePath, serialized);
 }
 function resolveHomeDir(env) {
-    return env.HOME?.trim() || env.USERPROFILE?.trim() || undefined;
+    const fromEnv = env.HOME?.trim() || env.USERPROFILE?.trim();
+    if (fromEnv && fs.existsSync(fromEnv))
+        return fromEnv;
+    // Injected envs (tests, embedders) opt out of the machine fallback. For the
+    // real process env, fall back to os.homedir(): Git Bash exports HOME as a
+    // POSIX path (/c/Users/x) that breaks every user-level writer on Windows,
+    // and some CI shells unset HOME/USERPROFILE entirely.
+    if (env !== process.env)
+        return undefined;
+    const fallback = os.homedir();
+    return fallback && fs.existsSync(fallback) ? fallback : undefined;
 }
 function runGit(cwd, args, input) {
     const result = spawnSync('git', args, {
@@ -635,7 +738,10 @@ Steps:
 }
 export function ensureClineMcpConfig(cwd) {
     const filePath = path.join(cwd, '.vscode', 'cline_mcp_settings.json');
-    const existing = readJsonObject(filePath);
+    const existing = readJsoncObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Cline MCP settings', filePath, CLINE_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = {
         ...brainclawMcpEntry('cline', mcpServers.brainclaw, cwd),
@@ -661,6 +767,9 @@ export function ensureWindsurfMcpConfig(homeDir) {
     }
     const filePath = path.join(homeDir, '.codeium', 'windsurf', 'mcp_config.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Windsurf MCP settings', filePath, WINDSURF_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = {
         ...brainclawMcpEntry('windsurf', mcpServers.brainclaw),
@@ -797,9 +906,35 @@ CLI fallback only: \`brainclaw context --json\` / \`brainclaw claim create\` / \
         relativePath: UNIVERSAL_SKILL_RELATIVE_PATH,
     };
 }
+/**
+ * Write the protocol-skills pack (pln#519) to the universal `.agents/skills/`
+ * path — one SKILL.md per workflow (session / memory-capture / multi-agent).
+ * Orthogonal to the agent-PROFILE skill above; same agents discover both via
+ * the shared `.agents/skills/` convention, so no per-agent branching is needed.
+ * Idempotent (writeTextFileIfChanged). Called only for skill-capable agents.
+ */
+export function ensureProtocolSkills(cwd) {
+    const version = getInstalledBrainclawVersion();
+    return PROTOCOL_SKILLS.map((skill) => {
+        const relativePath = `.agents/skills/${skill.id}/SKILL.md`;
+        const filePath = path.join(cwd, '.agents', 'skills', skill.id, 'SKILL.md');
+        const { created, updated } = writeTextFileIfChanged(filePath, renderProtocolSkill(skill, version));
+        return {
+            kind: 'skill',
+            label: `Protocol-skill ${skill.id} (${relativePath})`,
+            created,
+            updated,
+            filePath,
+            relativePath,
+        };
+    });
+}
 export function ensureCopilotMcpConfig(cwd) {
     const filePath = path.join(cwd, '.vscode', 'settings.json');
-    const existing = readJsonObject(filePath);
+    const existing = readJsoncObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Copilot MCP settings (.vscode/settings.json)', filePath, COPILOT_MCP_RELATIVE_PATH);
+    }
     const copilotMcpKey = 'github.copilot.chat.mcpServers';
     const mcpServers = isJsonObject(existing[copilotMcpKey]) ? { ...existing[copilotMcpKey] } : {};
     mcpServers.brainclaw = brainclawMcpEntry('github-copilot', mcpServers.brainclaw, cwd);
@@ -823,7 +958,10 @@ export function ensureCopilotMcpConfig(cwd) {
  */
 export function ensureVscodeMcpConfig(cwd) {
     const filePath = path.join(cwd, '.vscode', 'mcp.json');
-    const existing = readJsonObject(filePath);
+    const existing = readJsoncObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'VS Code MCP config (.vscode/mcp.json)', filePath, VSCODE_MCP_RELATIVE_PATH);
+    }
     const servers = isJsonObject(existing.servers) ? { ...existing.servers } : {};
     servers.brainclaw = brainclawMcpEntry('github-copilot', servers.brainclaw, cwd);
     const { created, updated } = writeJsonFileIfChanged(filePath, {
@@ -842,7 +980,10 @@ export function ensureVscodeMcpConfig(cwd) {
 const BRAINCLAW_EXTENSION_ID = 'brainclaw.brainclaw-vscode';
 export function ensureVscodeExtensionRecommendation(cwd) {
     const filePath = path.join(cwd, '.vscode', 'extensions.json');
-    const existing = readJsonObject(filePath);
+    const existing = readJsoncObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('recommendation', 'VS Code extension recommendation (.vscode/extensions.json)', filePath, VSCODE_EXTENSIONS_RELATIVE_PATH);
+    }
     const recommendations = Array.isArray(existing.recommendations)
         ? [...existing.recommendations]
         : [];
@@ -900,57 +1041,47 @@ function buildMatchedCommandHookEntry(matcher, command) {
         hooks: [{ type: 'command', command }],
     };
 }
-function containsCommandHook(entries, command) {
-    return entries.some((entry) => isJsonObject(entry) &&
-        Array.isArray(entry.hooks) &&
-        entry.hooks.some((h) => isJsonObject(h) && h.command === command));
-}
 /**
- * Replace a legacy command hook with a new one, or add the new one if neither exists.
- * This enables clean upgrades: old hooks are swapped out, new hooks are added if fresh.
+ * Recognize a hook command emitted by any brainclaw version: `npx brainclaw …`,
+ * absolute bin paths ending in /brainclaw, the `.bclaw-session` marker wrapper,
+ * and the brainclaw-specific `check-events` subcommand (whose broken legacy
+ * form — bare node.exe, cli.js arg dropped — contained no other marker).
  */
-function replaceOrAddCommandHook(entries, newCommand, legacyCommand) {
-    if (containsCommandHook(entries, newCommand))
-        return;
-    // Find and replace legacy command
-    for (let i = 0; i < entries.length; i++) {
-        const entry = entries[i];
-        if (isJsonObject(entry) && Array.isArray(entry.hooks)) {
-            for (const h of entry.hooks) {
-                if (isJsonObject(h) && h.command === legacyCommand) {
-                    h.command = newCommand;
-                    return;
-                }
-            }
-        }
-    }
-    // Neither new nor legacy found — add fresh
-    entries.push(buildCommandHookEntry(newCommand));
-}
+function isBrainclawHookCommand(command) {
+    // Review follow-up L2 (lop_e2d566765b8b4ce3): match brainclaw/bclaw only in
+    // COMMAND position (start / path separator / shell delimiter, optional binary
+    // extension) and check-events only as a standalone shell word — the old
+    // substring regex ate any user hook that merely MENTIONED these words.
+    if (command.includes('.bclaw-session'))
+        return true;
+    if (/(^|\s)check-events(\s|$)/.test(command))
+        return true;
+    return /(^|[\s/\\"'`;&|(])(brainclaw|bclaw)(\.(cmd|exe|js|mjs|ps1))?([\s"')`;&|]|$)/.test(command);
+}
+/** Test-only export — hook recognition is the L2 contract worth pinning. */
+export const __agentFilesTesting = { isBrainclawHookCommand };
 /**
- * Replace a hook matching any of the legacy patterns, or add fresh.
- * Used for hooks where the command string changes across versions.
+ * Remove every brainclaw-emitted hook from `entries`, then append exactly one
+ * canonical entry. Keyed on recognition, not exact command text, so upgrades
+ * replace stale/broken variants instead of accumulating duplicates (we observed
+ * 2× UserPromptSubmit + 3× Stop hooks piled up across upgrades in the wild).
+ * User-authored hooks are preserved untouched.
  */
-function replaceOrAddCommandHookByPattern(entries, newCommand, legacyPatterns) {
-    // Already present with the exact new command
-    if (entries.some(entry => isJsonObject(entry) && Array.isArray(entry.hooks) &&
-        entry.hooks.some(h => isJsonObject(h) && typeof h.command === 'string' && h.command === newCommand)))
-        return;
-    // Find and replace any entry containing a legacy pattern substring
+function replaceBrainclawHooks(entries, canonical) {
+    const kept = [];
     for (const entry of entries) {
-        if (!isJsonObject(entry) || !Array.isArray(entry.hooks))
+        if (!isJsonObject(entry) || !Array.isArray(entry.hooks)) {
+            kept.push(entry);
             continue;
-        for (const h of entry.hooks) {
-            if (!isJsonObject(h) || typeof h.command !== 'string')
-                continue;
-            if (legacyPatterns.some(p => h.command.includes(p))) {
-                h.command = newCommand;
-                return;
-            }
         }
+        const hooks = entry.hooks;
+        const remaining = hooks.filter((h) => !(isJsonObject(h) && typeof h.command === 'string' && isBrainclawHookCommand(h.command)));
+        if (remaining.length === 0)
+            continue;
+        kept.push(remaining.length === hooks.length ? entry : { ...entry, hooks: remaining });
     }
-    // No match — add fresh
-    entries.push(buildCommandHookEntry(newCommand));
+    kept.push(canonical);
+    return kept;
 }
 export function ensureProjectDevDependency(cwd) {
     const filePath = path.join(cwd, 'package.json');
@@ -984,6 +1115,9 @@ export function ensureProjectDevDependency(cwd) {
 export function ensureClaudeCodeMcpConfig(cwd) {
     const filePath = path.join(cwd, '.mcp.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Claude Code MCP server', filePath, CLAUDE_CODE_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = brainclawMcpEntry('claude-code', mcpServers.brainclaw, cwd);
     const { created, updated } = writeJsonFileIfChanged(filePath, {
@@ -1017,6 +1151,9 @@ export function ensureClaudeCodeUserSettings(homeDir, env = process.env) {
         return undefined;
     const filePath = path.join(homeDir, '.claude', 'settings.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Claude Code user settings — MCP + permissions (global, all projects)', filePath);
+    }
     // MCP server
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = brainclawMcpEntry('claude-code', mcpServers.brainclaw);
@@ -1058,6 +1195,9 @@ export function ensureClaudeCodeUserCommand(homeDir) {
 export function ensureClaudeCodeSettings(cwd) {
     const filePath = path.join(cwd, '.claude', 'settings.local.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('rule', 'Claude Code settings (permissions + session hooks)', filePath, CLAUDE_CODE_SETTINGS_RELATIVE_PATH);
+    }
     // Merge permissions.allow
     const permissions = isJsonObject(existing.permissions) ? { ...existing.permissions } : {};
     const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
@@ -1084,40 +1224,19 @@ export function ensureClaudeCodeSettings(cwd) {
         }
     }
     permissions.additionalDirectories = additionalDirs;
-    // Merge hooks — UserPromptSubmit opens a session on first prompt, diff on subsequent
+    // Merge hooks — UserPromptSubmit opens a session on first prompt, diff on subsequent.
+    // getBclawCliParts() keeps the cli.js argument; the previous builder used only
+    // the bare command, emitting broken `node.exe session-start` hooks whenever
+    // binary resolution succeeded (hidden by 2>/dev/null).
     const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
-    const mcpCmd = getBrainclawMcpCommand();
-    // For shell hooks, normalize Windows backslashes to forward slashes and quote if needed
-    const bclawBin = mcpCmd.command === 'npx'
-        ? 'npx brainclaw'
-        : `"${mcpCmd.command.replace(/\\/g, '/')}"`;
+    const bclawBin = getBclawCliParts().map(quoteShellArg).join(' ');
     const sessionCommand = `f=.claude/.bclaw-session; if [ ! -f "$f" ]; then touch "$f"; ${bclawBin} session-start --include-context 2>/dev/null; else ${bclawBin} context-diff 2>/dev/null; fi`;
     const stopCommand = `rm -f .claude/.bclaw-session; ${bclawBin} session-end --auto-release --reflect --reflect-handoff --dispatch-review 2>/dev/null`;
-    // Legacy commands to replace on upgrade (substring patterns to match old hooks)
-    const legacyPatterns = [
-        'brainclaw context 2>/dev/null',
-        'brainclaw session-start --include-context 2>/dev/null',
-        'brainclaw session-end --auto-release',
-        'brainclaw context-diff 2>/dev/null',
-    ];
-    const userPromptHooks = Array.isArray(hooks.UserPromptSubmit) ? [...hooks.UserPromptSubmit] : [];
-    replaceOrAddCommandHookByPattern(userPromptHooks, sessionCommand, legacyPatterns);
-    hooks.UserPromptSubmit = userPromptHooks;
-    const stopHooks = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
-    replaceOrAddCommandHookByPattern(stopHooks, stopCommand, legacyPatterns);
-    hooks.Stop = stopHooks;
     // PostToolUse — check for unseen events after any brainclaw MCP tool call
     const checkEventsCommand = `${bclawBin} check-events 2>/dev/null`;
-    const postToolHooks = Array.isArray(hooks.PostToolUse) ? [...hooks.PostToolUse] : [];
-    replaceOrAddCommandHookByPattern(postToolHooks, checkEventsCommand, ['npx brainclaw check-events']);
-    // Preserve matcher for PostToolUse — only fire on brainclaw MCP tool calls
-    for (const entry of postToolHooks) {
-        if (isJsonObject(entry) && Array.isArray(entry.hooks) &&
-            entry.hooks.some(h => isJsonObject(h) && typeof h.command === 'string' && h.command.includes('check-events'))) {
-            entry.matcher = 'mcp__brainclaw__';
-        }
-    }
-    hooks.PostToolUse = postToolHooks;
+    hooks.UserPromptSubmit = replaceBrainclawHooks(Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : [], buildCommandHookEntry(sessionCommand));
+    hooks.Stop = replaceBrainclawHooks(Array.isArray(hooks.Stop) ? hooks.Stop : [], buildCommandHookEntry(stopCommand));
+    hooks.PostToolUse = replaceBrainclawHooks(Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [], buildMatchedCommandHookEntry('mcp__brainclaw__', checkEventsCommand));
     const { created, updated } = writeJsonFileIfChanged(filePath, {
         ...existing,
         permissions,
@@ -1138,6 +1257,9 @@ export function ensureCursorMcpConfig(homeDir) {
     }
     const filePath = path.join(homeDir, '.cursor', 'mcp.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Cursor MCP settings', filePath, CURSOR_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = brainclawMcpEntry('cursor', mcpServers.brainclaw);
     const { created, updated } = writeJsonFileIfChanged(filePath, {
@@ -1156,6 +1278,9 @@ export function ensureCursorMcpConfig(homeDir) {
 export function ensureRooMcpConfig(cwd) {
     const filePath = path.join(cwd, '.roo', 'mcp.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Roo Code MCP settings', filePath, ROO_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = {
         ...brainclawMcpEntry('roo', mcpServers.brainclaw, cwd),
@@ -1176,22 +1301,46 @@ export function ensureRooMcpConfig(cwd) {
 }
 export function ensureKilocodeConfig(cwd) {
     const filePath = path.join(cwd, KILOCODE_CONFIG_RELATIVE_PATH);
+    const label = 'Kilo Code permissions (kilo.jsonc)';
     const existing = readJsoncObject(filePath);
-    const permission = isJsonObject(existing.permission) ? { ...existing.permission } : {};
-    permission.external_directory = 'deny';
-    const { created, updated } = writeTextFileIfChanged(filePath, `${JSON.stringify({ ...existing, permission }, null, 2)}\n`);
-    return {
+    if (existing === undefined) {
+        return skippedAutoConfigResult('permissions', label, filePath, KILOCODE_CONFIG_RELATIVE_PATH);
+    }
+    const noop = {
         kind: 'permissions',
-        label: 'Kilo Code permissions (kilo.jsonc)',
-        created,
-        updated,
+        label,
+        created: false,
+        updated: false,
         filePath,
         relativePath: KILOCODE_CONFIG_RELATIVE_PATH,
     };
+    const permission = isJsonObject(existing.permission) ? existing.permission : {};
+    if (permission.external_directory === 'deny') {
+        return noop;
+    }
+    const existed = fs.existsSync(filePath);
+    if (!existed) {
+        const { created, updated } = writeTextFileIfChanged(filePath, `${JSON.stringify({ permission: { external_directory: 'deny' } }, null, 2)}\n`);
+        return { ...noop, created, updated };
+    }
+    // Surgical JSONC edit — kilo.jsonc is a user-owned file where comments are
+    // part of the official format; a parse→stringify round-trip would strip them.
+    const raw = stripBom(fs.readFileSync(filePath, 'utf-8'));
+    const next = raw.trim().length === 0
+        ? `${JSON.stringify({ permission: { external_directory: 'deny' } }, null, 2)}\n`
+        : setJsoncValue(raw, ['permission', 'external_directory'], '"deny"');
+    if (next === undefined) {
+        return skippedAutoConfigResult('permissions', label, filePath, KILOCODE_CONFIG_RELATIVE_PATH);
+    }
+    fs.writeFileSync(filePath, next, 'utf-8');
+    return { ...noop, updated: true };
 }
 export function ensureKilocodeMcpConfig(cwd) {
     const filePath = path.join(cwd, '.kilo', 'mcp.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Kilo Code MCP settings', filePath, KILOCODE_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = {
         ...brainclawMcpEntry('kilocode', mcpServers.brainclaw, cwd),
@@ -1282,48 +1431,71 @@ export function ensureMistralVibeMcpConfig(cwd) {
         relativePath: MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
     };
 }
-const HERMES_BRAINCLAW_MCP_TOOLS = [
-    'bclaw_work',
-    'bclaw_context',
-    'bclaw_find',
-    'bclaw_get',
-    'bclaw_create',
-    'bclaw_update',
-    'bclaw_transition',
-];
+// Hermes' MCP `tools.include` array — narrow canonical-grammar surface. Derived
+// from MCP_CANONICAL_GRAMMAR_TOOL_NAMES (which is itself ALL_TOOLS-derived) so
+// new facade tools or canonical grammar verbs propagate without a manual edit
+// here (pln#546 step 2). REMOVED_IN_V1_TOOLS are stripped so deprecated names
+// don't reappear in user-facing configs.
+//
+// LAZY (pln#564 coordinator fix): computed on first call, NOT at module init.
+// agent-files.ts ↔ commands/mcp.ts form an import cycle; reading the imported
+// MCP_CANONICAL_GRAMMAR_TOOL_NAMES at module-eval time threw a TDZ
+// ("Cannot access 'MCP_CANONICAL_GRAMMAR_TOOL_NAMES' before initialization")
+// when agent-files loaded mid-mcp-init — which broke the MCP server. tsc does
+// not catch this (runtime-only). Deferring the read to call time fixes it.
+let hermesBrainclawMcpToolsCache;
+function getHermesBrainclawMcpTools() {
+    if (!hermesBrainclawMcpToolsCache) {
+        hermesBrainclawMcpToolsCache = MCP_CANONICAL_GRAMMAR_TOOL_NAMES
+            .filter((name) => !REMOVED_IN_V1_TOOLS.has(name));
+    }
+    return hermesBrainclawMcpToolsCache;
+}
 export function ensureHermesMcpConfig(homeDir, workspacePath) {
     if (!homeDir)
         return undefined;
     const filePath = path.join(homeDir, HERMES_CONFIG_RELATIVE_PATH);
+    const label = 'Hermes MCP settings';
+    // Parse the existing file as a YAML *document* so we can update only the
+    // brainclaw-managed subtree. A parse→stringify round-trip of the whole file
+    // destroys user comments, anchors, and key order; a parse failure must
+    // abort instead of replacing the user's Hermes config with a stub.
+    let doc;
     let existing = {};
-    let existed = false;
     if (fs.existsSync(filePath)) {
-        existed = true;
-        try {
-            const parsed = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
-            existing = isJsonObject(parsed) ? { ...parsed } : {};
+        doc = yaml.parseDocument(stripBom(fs.readFileSync(filePath, 'utf-8')));
+        if (doc.errors.length > 0) {
+            return skippedAutoConfigResult('mcp', label, filePath, HERMES_CONFIG_RELATIVE_PATH);
+        }
+        const parsed = doc.toJS();
+        if (parsed == null) {
+            doc = undefined; // empty file — treat as fresh create
         }
-        catch {
-            existing = {};
+        else if (isJsonObject(parsed)) {
+            existing = parsed;
+        }
+        else {
+            return skippedAutoConfigResult('mcp', label, filePath, HERMES_CONFIG_RELATIVE_PATH);
         }
     }
-    const mcpServers = isJsonObject(existing.mcp_servers) ? { ...existing.mcp_servers } : {};
-    const current = isJsonObject(mcpServers.brainclaw) ? { ...mcpServers.brainclaw } : {};
+    const mcpServersJs = isJsonObject(existing.mcp_servers) ? existing.mcp_servers : {};
+    const current = isJsonObject(mcpServersJs.brainclaw) ? { ...mcpServersJs.brainclaw } : {};
     const currentEnv = isJsonObject(current.env) ? { ...current.env } : {};
     const currentTools = isJsonObject(current.tools) ? { ...current.tools } : {};
-    const skills = isJsonObject(existing.skills) ? { ...existing.skills } : {};
+    const skills = isJsonObject(existing.skills) ? existing.skills : {};
     const externalDirs = Array.isArray(skills.external_dirs)
         ? skills.external_dirs.filter((value) => typeof value === 'string')
         : [];
+    const newExternalDirs = [];
     if (workspacePath) {
         const projectSkillsDir = path.resolve(workspacePath, HERMES_EXTERNAL_SKILLS_RELATIVE_PATH);
         const normalized = projectSkillsDir.replace(/\\/g, '/').toLowerCase();
         if (!externalDirs.some((dir) => dir.replace(/\\/g, '/').toLowerCase() === normalized)) {
-            externalDirs.push(projectSkillsDir);
+            newExternalDirs.push(projectSkillsDir);
         }
     }
     const mcpCmd = getBrainclawMcpCommand();
-    mcpServers.brainclaw = {
+    const desiredEntry = {
         ...current,
         command: typeof current.command === 'string' ? current.command : mcpCmd.command,
         args: Array.isArray(current.args) ? current.args : mcpCmd.args,
@@ -1333,23 +1505,67 @@ export function ensureHermesMcpConfig(homeDir, workspacePath) {
         },
         tools: {
             ...currentTools,
-            include: Array.isArray(currentTools.include) ? currentTools.include : HERMES_BRAINCLAW_MCP_TOOLS,
+            include: Array.isArray(currentTools.include) ? currentTools.include : getHermesBrainclawMcpTools(),
             prompts: typeof currentTools.prompts === 'boolean' ? currentTools.prompts : false,
             resources: typeof currentTools.resources === 'boolean' ? currentTools.resources : false,
         },
     };
-    const nextConfig = {
-        ...existing,
-        mcp_servers: mcpServers,
-        ...(externalDirs.length > 0 ? { skills: { ...skills, external_dirs: externalDirs } } : {}),
-    };
-    const content = `# Managed by brainclaw — preserves existing Hermes settings\n${yaml.stringify(nextConfig)}`;
-    const { created, updated } = writeTextFileIfChanged(filePath, content);
+    if (!doc) {
+        const nextConfig = {
+            mcp_servers: { brainclaw: desiredEntry },
+            ...(externalDirs.length + newExternalDirs.length > 0
+                ? { skills: { ...skills, external_dirs: [...externalDirs, ...newExternalDirs] } }
+                : {}),
+        };
+        const content = `# brainclaw manages the mcp_servers.brainclaw entry below\n${yaml.stringify(nextConfig)}`;
+        const { created, updated } = writeTextFileIfChanged(filePath, content);
+        return {
+            kind: 'mcp',
+            label,
+            created,
+            updated,
+            filePath,
+            relativePath: HERMES_CONFIG_RELATIVE_PATH,
+        };
+    }
+    let changed = false;
+    try {
+        const currentRaw = isJsonObject(mcpServersJs.brainclaw) ? mcpServersJs.brainclaw : undefined;
+        if (JSON.stringify(currentRaw ?? null) !== JSON.stringify(desiredEntry)) {
+            doc.setIn(['mcp_servers', 'brainclaw'], desiredEntry);
+            changed = true;
+        }
+        if (newExternalDirs.length > 0) {
+            if (doc.getIn(['skills', 'external_dirs']) === undefined) {
+                doc.setIn(['skills', 'external_dirs'], [...externalDirs, ...newExternalDirs]);
+            }
+            else {
+                for (const dir of newExternalDirs) {
+                    doc.addIn(['skills', 'external_dirs'], dir);
+                }
+            }
+            changed = true;
+        }
+    }
+    catch {
+        return skippedAutoConfigResult('mcp', label, filePath, HERMES_CONFIG_RELATIVE_PATH);
+    }
+    if (!changed) {
+        return {
+            kind: 'mcp',
+            label,
+            created: false,
+            updated: false,
+            filePath,
+            relativePath: HERMES_CONFIG_RELATIVE_PATH,
+        };
+    }
+    fs.writeFileSync(filePath, doc.toString(), 'utf-8');
     return {
         kind: 'mcp',
-        label: 'Hermes MCP settings',
-        created: !existed && created,
-        updated: existed && updated,
+        label,
+        created: false,
+        updated: true,
         filePath,
         relativePath: HERMES_CONFIG_RELATIVE_PATH,
     };
@@ -1472,7 +1688,7 @@ export function ensureCodexMcpConfig(homeDir, env = process.env) {
         content = content + brainclawBlock + '\n';
         changed = true;
     }
-    else if (_forceResolve) {
+    else if (isForceResolveEnabled()) {
         const replaced = replaceTomlSection(content, 'mcp_servers.brainclaw', brainclawBlock.slice(1) + '\n');
         if (replaced !== content) {
             content = replaced;
@@ -1480,8 +1696,8 @@ export function ensureCodexMcpConfig(homeDir, env = process.env) {
         }
     }
     // Per-tool approval blocks: ALWAYS sync to the current catalog, regardless
-    // of _forceResolve. These sections are purely machine-managed (no user edits
-    // expected) and must match the narrowed headless-auto catalog.
+    // of force-resolve state. These sections are purely machine-managed (no user
+    // edits expected) and must match the narrowed headless-auto catalog.
     const hasToolSections = /^\[mcp_servers\.brainclaw\.tools\./m.test(content);
     if (hasToolSections) {
         const replaced = replaceTomlSection(content, 'mcp_servers.brainclaw.tools', toolsBlock.slice(1));
@@ -1555,6 +1771,9 @@ function replaceTomlSection(fileContent, sectionName, newBlock) {
 export function ensureContinueMcpConfig(cwd) {
     const filePath = path.join(cwd, '.continue', 'config.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Continue MCP settings', filePath, CONTINUE_CONFIG_RELATIVE_PATH);
+    }
     // Continue uses an array for mcpServers, not a keyed object
     const mcpServers = Array.isArray(existing.mcpServers) ? [...existing.mcpServers] : [];
     const existingIdx = mcpServers.findIndex((entry) => isJsonObject(entry) && entry.name === 'brainclaw');
@@ -1583,6 +1802,9 @@ export function ensureContinueUserMcpConfig(homeDir) {
         return undefined;
     const filePath = path.join(homeDir, '.continue', 'config.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Continue MCP settings (global, all projects)', filePath);
+    }
     const mcpServers = Array.isArray(existing.mcpServers) ? [...existing.mcpServers] : [];
     const existingIdx = mcpServers.findIndex((entry) => isJsonObject(entry) && entry.name === 'brainclaw');
     if (existingIdx >= 0) {
@@ -1622,40 +1844,69 @@ export function ensureContinueUserPermissions(homeDir) {
     if (!homeDir)
         return undefined;
     const filePath = path.join(homeDir, CONTINUE_PERMISSIONS_RELATIVE_PATH);
-    let existing = {};
+    const label = 'Continue tool permissions';
+    const noop = { kind: 'permissions', label, created: false, updated: false, filePath };
+    // Update only the per-tool `allow` flags in the YAML document; never
+    // round-trip the whole user file (comments/anchors/key order survive) and
+    // never replace an unparseable file with a stub.
+    let doc;
+    let existingTools = {};
     if (fs.existsSync(filePath)) {
-        try {
-            const parsed = yaml.parse(fs.readFileSync(filePath, 'utf-8'));
-            existing = isJsonObject(parsed) ? { ...parsed } : {};
+        doc = yaml.parseDocument(stripBom(fs.readFileSync(filePath, 'utf-8')));
+        if (doc.errors.length > 0) {
+            return skippedAutoConfigResult('permissions', label, filePath);
         }
-        catch {
-            existing = {};
+        const parsed = doc.toJS();
+        if (parsed == null) {
+            doc = undefined;
+        }
+        else if (isJsonObject(parsed)) {
+            existingTools = isJsonObject(parsed.tools) ? parsed.tools : {};
+        }
+        else {
+            return skippedAutoConfigResult('permissions', label, filePath);
         }
     }
-    const toolsObj = isJsonObject(existing.tools) ? { ...existing.tools } : {};
-    for (const name of getHeadlessAutoApprovedToolNames()) {
-        const current = isJsonObject(toolsObj[name]) ? { ...toolsObj[name] } : {};
-        toolsObj[name] = {
-            ...current,
-            allow: true,
-        };
+    if (!doc) {
+        const toolsObj = {};
+        for (const name of getHeadlessAutoApprovedToolNames()) {
+            toolsObj[name] = { allow: true };
+        }
+        const content = `# brainclaw manages the per-tool allow flags below\n${yaml.stringify({ tools: toolsObj })}`;
+        const { created, updated } = writeTextFileIfChanged(filePath, content);
+        return { ...noop, created, updated };
     }
-    const content = `# Managed by brainclaw — do not edit manually\n${yaml.stringify({
-        ...existing,
-        tools: toolsObj,
-    })}`;
-    const { created, updated } = writeTextFileIfChanged(filePath, content);
-    return {
-        kind: 'permissions',
-        label: 'Continue tool permissions',
-        created,
-        updated,
-        filePath,
-    };
+    let changed = false;
+    try {
+        for (const name of getHeadlessAutoApprovedToolNames()) {
+            const current = existingTools[name];
+            const allow = isJsonObject(current) ? current.allow : undefined;
+            if (allow !== true) {
+                if (current !== undefined && !isJsonObject(current)) {
+                    doc.setIn(['tools', name], { allow: true });
+                }
+                else {
+                    doc.setIn(['tools', name, 'allow'], true);
+                }
+                changed = true;
+            }
+        }
+    }
+    catch {
+        return skippedAutoConfigResult('permissions', label, filePath);
+    }
+    if (!changed) {
+        return noop;
+    }
+    fs.writeFileSync(filePath, doc.toString(), 'utf-8');
+    return { ...noop, updated: true };
 }
 export function ensureOpenCodeMcpConfig(cwd) {
     const filePath = path.join(cwd, 'opencode.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'OpenCode MCP config', filePath, OPENCODE_CONFIG_RELATIVE_PATH);
+    }
     const mcp = isJsonObject(existing.mcp) ? { ...existing.mcp } : {};
     const mcpCmd = getBrainclawMcpCommand();
     mcp.brainclaw = {
@@ -1683,6 +1934,9 @@ export function ensureAntigravityMcpConfig(homeDir) {
     }
     const filePath = path.join(homeDir, '.gemini', 'antigravity', 'mcp_config.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'Antigravity MCP config', filePath, ANTIGRAVITY_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = brainclawMcpEntry('antigravity', mcpServers.brainclaw);
     const { created, updated } = writeJsonFileIfChanged(filePath, {
@@ -1698,35 +1952,6 @@ export function ensureAntigravityMcpConfig(homeDir) {
         relativePath: ANTIGRAVITY_MCP_RELATIVE_PATH,
     };
 }
-function quoteShellArg(arg) {
-    if (/^[A-Za-z0-9_./:=+-]+$/.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '\\"')}"`;
-}
-/**
- * Resolve the brainclaw CLI invocation for hook configs.
- * Returns shell-safe parts like `["<node>", "<cli.js>"]` or `["npx", "brainclaw"]`.
- */
-function getBclawCliParts() {
-    const mcpCmd = getBrainclawMcpCommand();
-    if (mcpCmd.command === 'npx')
-        return ['npx', 'brainclaw'];
-    const argsWithoutMcp = [...mcpCmd.args];
-    if (argsWithoutMcp[argsWithoutMcp.length - 1] === 'mcp') {
-        argsWithoutMcp.pop();
-    }
-    return [
-        mcpCmd.command.replace(/\\/g, '/'),
-        ...argsWithoutMcp.map((arg) => arg.replace(/\\/g, '/')),
-    ];
-}
-function buildHookCommand(args, shell = os.platform() === 'win32' ? 'powershell' : 'bash') {
-    const rendered = [...getBclawCliParts(), ...args].map(quoteShellArg).join(' ');
-    if (shell === 'powershell') {
-        return `& ${rendered} 2>$null`;
-    }
-    return `${rendered} 2>/dev/null`;
-}
 /**
  * Writes `.cursor/hooks.json` — Cursor's native hooks config.
  * Events: sessionStart, beforeSubmitPrompt, stop (Cursor uses camelCase).
@@ -1735,6 +1960,9 @@ function buildHookCommand(args, shell = os.platform() === 'win32' ? 'powershell'
 export function ensureCursorHooks(cwd) {
     const filePath = path.join(cwd, CURSOR_HOOKS_RELATIVE_PATH);
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('rule', 'Cursor session hooks', filePath, CURSOR_HOOKS_RELATIVE_PATH);
+    }
     const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
     const sessionStartCmd = buildHookCommand(['session-start', '--include-context']);
     const contextDiffCmd = buildHookCommand(['context-diff']);
@@ -1765,6 +1993,9 @@ export function ensureAntigravityHooks(homeDir) {
         return undefined;
     const filePath = path.join(homeDir, ANTIGRAVITY_HOOKS_RELATIVE_PATH);
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('rule', 'Antigravity session hooks', filePath, ANTIGRAVITY_HOOKS_RELATIVE_PATH);
+    }
     const sessionStartCmd = buildHookCommand(['session-start', '--include-context']);
     const contextDiffCmd = buildHookCommand(['context-diff']);
     const sessionEndCmd = buildHookCommand(['session-end', '--auto-release', '--reflect', '--reflect-handoff', '--dispatch-review']);
@@ -1792,6 +2023,9 @@ export function ensureAntigravityHooks(homeDir) {
 export function ensureCopilotHooks(cwd) {
     const filePath = path.join(cwd, COPILOT_HOOKS_RELATIVE_PATH);
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('rule', 'Copilot session hooks', filePath, COPILOT_HOOKS_RELATIVE_PATH);
+    }
     const hooks = isJsonObject(existing.hooks) ? { ...existing.hooks } : {};
     hooks.sessionStart = [{
             type: 'command',
@@ -1831,6 +2065,9 @@ export function ensureOpenClawMcpConfig(homeDir) {
     }
     const filePath = path.join(homeDir, '.openclaw', 'mcp.json');
     const existing = readJsonObject(filePath);
+    if (existing === undefined) {
+        return skippedAutoConfigResult('mcp', 'OpenClaw MCP config', filePath, OPENCLAW_MCP_RELATIVE_PATH);
+    }
     const mcpServers = isJsonObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
     mcpServers.brainclaw = brainclawMcpEntry('openclaw', mcpServers.brainclaw);
     const { created, updated } = writeJsonFileIfChanged(filePath, {
@@ -1846,212 +2083,272 @@ export function ensureOpenClawMcpConfig(homeDir) {
         relativePath: OPENCLAW_MCP_RELATIVE_PATH,
     };
 }
-export function writeDetectedAgentAutoConfig(agentName, cwd, env = process.env) {
-    switch (agentName) {
-        case 'claude-code': {
-            const results = [
-                ensureClaudeCodeMcpConfig(cwd),
-                ensureClaudeCodeCommand(cwd),
-                ensureClaudeCodeSettings(cwd),
-                ensureVscodeExtensionRecommendation(cwd),
-            ];
-            const userSettings = ensureClaudeCodeUserSettings(resolveHomeDir(env));
-            if (userSettings)
-                results.push(userSettings);
-            const userCmd = ensureClaudeCodeUserCommand(resolveHomeDir(env));
-            if (userCmd)
-                results.push(userCmd);
-            const dep = ensureProjectDevDependency(cwd);
-            if (dep)
-                results.push(dep);
-            return results;
-        }
-        case 'cline':
-            return [ensureClineMcpConfig(cwd)];
-        case 'windsurf': {
-            const results = [ensureWindsurfModernRules(cwd)];
-            const mcp = ensureWindsurfMcpConfig(resolveHomeDir(env));
-            if (mcp)
-                results.push(mcp);
-            return results;
-        }
-        case 'github-copilot':
-            return [ensureCopilotMcpConfig(cwd), ensureCopilotSkill(cwd), ensureCopilotHooks(cwd), ensureUniversalBrainclawSkill(cwd), ensureVscodeExtensionRecommendation(cwd)];
-        case 'cursor': {
-            const results = [ensureCursorMdc(cwd), ensureCursorHooks(cwd), ensureUniversalBrainclawSkill(cwd)];
-            const mcp = ensureCursorMcpConfig(resolveHomeDir(env));
-            if (mcp)
-                results.push(mcp);
-            return results;
-        }
-        case 'roo':
-            return [ensureRooMcpConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
-        case 'kilocode':
-            return [ensureKilocodeMcpConfig(cwd), ensureKilocodeConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
-        case 'mistral-vibe':
-            return [ensureMistralVibeMcpConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
-        case 'hermes': {
-            const results = [ensureUniversalBrainclawSkill(cwd)];
-            const mcp = ensureHermesMcpConfig(resolveHomeDir(env), cwd);
-            if (mcp)
-                results.push(mcp);
-            return results;
-        }
-        case 'codex': {
-            const results = [ensureUniversalBrainclawSkill(cwd)];
-            const result = ensureCodexMcpConfig(resolveHomeDir(env), env);
-            if (result)
-                results.push(result);
-            return results;
-        }
-        case 'continue': {
-            const results = [ensureContinueMcpConfig(cwd)];
-            const homeDir = resolveHomeDir(env);
-            const userMcp = ensureContinueUserMcpConfig(homeDir);
-            if (userMcp)
-                results.push(userMcp);
-            const perms = ensureContinueUserPermissions(homeDir);
-            if (perms)
-                results.push(perms);
-            return results;
-        }
-        case 'opencode':
-            return [ensureOpenCodeMcpConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
-        case 'antigravity': {
-            const homeDir = resolveHomeDir(env);
-            const results = [];
-            const mcp = ensureAntigravityMcpConfig(homeDir);
-            if (mcp)
-                results.push(mcp);
-            const hooks = ensureAntigravityHooks(homeDir);
-            if (hooks)
-                results.push(hooks);
-            return results;
-        }
-        case 'openclaw': {
-            const result = ensureOpenClawMcpConfig(resolveHomeDir(env));
-            return result ? [result] : [];
-        }
-        default:
-            return [];
+// Shared writer builders — referenced across multiple agents.
+const writeUniversalSkill = (ctx) => ensureUniversalBrainclawSkill(ctx.cwd);
+const writeProtocolSkills = (ctx) => ensureProtocolSkills(ctx.cwd);
+const writeVscodeExtensionRec = (ctx) => ensureVscodeExtensionRecommendation(ctx.cwd);
+/**
+ * Per-agent writer wiring. The keys are canonical agent names from
+ * `AgentName` (see agent-capability.ts) — keep in sync with AGENT_EXPORT_REGISTRY.
+ * Agents missing from this map yield an empty writer list (no-op detection),
+ * which the drift test below guards against.
+ */
+export const AGENT_WIRING_REGISTRY = {
+    'claude-code': {
+        // .claude/settings.local.json bundles permissions + session/Stop/PostToolUse
+        // hooks in one file, so it lives in workspaceWriters — not duplicated in
+        // hookWriters (which would double-count the result).
+        workspaceWriters: [
+            (ctx) => ensureClaudeCodeMcpConfig(ctx.cwd),
+            (ctx) => ensureClaudeCodeCommand(ctx.cwd),
+            (ctx) => ensureClaudeCodeSettings(ctx.cwd),
+            writeVscodeExtensionRec,
+            (ctx) => ensureProjectDevDependency(ctx.cwd),
+        ],
+        userWriters: [
+            (ctx) => ensureClaudeCodeUserSettings(ctx.homeDir, ctx.env),
+            (ctx) => ensureClaudeCodeUserCommand(ctx.homeDir),
+        ],
+        hookWriters: [],
+    },
+    cline: {
+        workspaceWriters: [(ctx) => ensureClineMcpConfig(ctx.cwd)],
+        userWriters: [],
+        hookWriters: [],
+    },
+    windsurf: {
+        workspaceWriters: [(ctx) => ensureWindsurfModernRules(ctx.cwd)],
+        userWriters: [(ctx) => ensureWindsurfMcpConfig(ctx.homeDir)],
+        hookWriters: [],
+    },
+    'github-copilot': {
+        workspaceWriters: [
+            (ctx) => ensureCopilotMcpConfig(ctx.cwd),
+            (ctx) => ensureCopilotSkill(ctx.cwd),
+            writeUniversalSkill,
+            writeProtocolSkills,
+            writeVscodeExtensionRec,
+        ],
+        userWriters: [],
+        hookWriters: [(ctx) => ensureCopilotHooks(ctx.cwd)],
+    },
+    cursor: {
+        workspaceWriters: [
+            (ctx) => ensureCursorMdc(ctx.cwd),
+            writeUniversalSkill,
+            writeProtocolSkills,
+        ],
+        userWriters: [(ctx) => ensureCursorMcpConfig(ctx.homeDir)],
+        hookWriters: [(ctx) => ensureCursorHooks(ctx.cwd)],
+    },
+    roo: {
+        workspaceWriters: [
+            (ctx) => ensureRooMcpConfig(ctx.cwd),
+            writeUniversalSkill,
+            writeProtocolSkills,
+        ],
+        userWriters: [],
+        hookWriters: [],
+    },
+    kilocode: {
+        workspaceWriters: [
+            (ctx) => ensureKilocodeMcpConfig(ctx.cwd),
+            (ctx) => ensureKilocodeConfig(ctx.cwd),
+            writeUniversalSkill,
+            writeProtocolSkills,
+        ],
+        userWriters: [],
+        hookWriters: [],
+    },
+    'mistral-vibe': {
+        workspaceWriters: [
+            (ctx) => ensureMistralVibeMcpConfig(ctx.cwd),
+            writeUniversalSkill,
+            writeProtocolSkills,
+        ],
+        userWriters: [],
+        hookWriters: [],
+    },
+    hermes: {
+        workspaceWriters: [
+            writeUniversalSkill,
+            writeProtocolSkills,
+        ],
+        userWriters: [(ctx) => ensureHermesMcpConfig(ctx.homeDir, ctx.workspacePath ?? ctx.cwd)],
+        hookWriters: [],
+    },
+    codex: {
+        workspaceWriters: [
+            writeUniversalSkill,
+            writeProtocolSkills,
+        ],
+        userWriters: [(ctx) => ensureCodexMcpConfig(ctx.homeDir, ctx.env)],
+        hookWriters: [],
+    },
+    continue: {
+        workspaceWriters: [(ctx) => ensureContinueMcpConfig(ctx.cwd)],
+        userWriters: [
+            (ctx) => ensureContinueUserMcpConfig(ctx.homeDir),
+            (ctx) => ensureContinueUserPermissions(ctx.homeDir),
+        ],
+        hookWriters: [],
+    },
+    opencode: {
+        workspaceWriters: [
+            (ctx) => ensureOpenCodeMcpConfig(ctx.cwd),
+            writeUniversalSkill,
+            writeProtocolSkills,
+        ],
+        userWriters: [],
+        hookWriters: [],
+    },
+    antigravity: {
+        workspaceWriters: [],
+        userWriters: [(ctx) => ensureAntigravityMcpConfig(ctx.homeDir)],
+        // Antigravity hook config lives under the user home — keep it in
+        // hookWriters (semantic grouping) but skip with the inventory gate like
+        // the other user-level fabricators.
+        hookWriters: [(ctx) => ensureAntigravityHooks(ctx.homeDir)],
+    },
+    openclaw: {
+        workspaceWriters: [],
+        userWriters: [(ctx) => ensureOpenClawMcpConfig(ctx.homeDir)],
+        hookWriters: [],
+    },
+    // Pure SKILL.md surfaces — nanoclaw/nemoclaw/picoclaw/zeroclaw have no MCP
+    // config and their instruction file is written by the export pipeline.
+    nanoclaw: { workspaceWriters: [], userWriters: [], hookWriters: [] },
+    nemoclaw: { workspaceWriters: [], userWriters: [], hookWriters: [] },
+    picoclaw: { workspaceWriters: [], userWriters: [], hookWriters: [] },
+    zeroclaw: { workspaceWriters: [], userWriters: [], hookWriters: [] },
+    // claude-sonnet: shares CLAUDE.md surface with claude-code; the workspace
+    // and user wiring is identical, so detection should reuse claude-code's
+    // descriptor rather than duplicate it.
+    'claude-sonnet': {
+        workspaceWriters: [
+            (ctx) => ensureClaudeCodeMcpConfig(ctx.cwd),
+            (ctx) => ensureClaudeCodeCommand(ctx.cwd),
+            (ctx) => ensureClaudeCodeSettings(ctx.cwd),
+            writeVscodeExtensionRec,
+            (ctx) => ensureProjectDevDependency(ctx.cwd),
+        ],
+        userWriters: [
+            (ctx) => ensureClaudeCodeUserSettings(ctx.homeDir, ctx.env),
+            (ctx) => ensureClaudeCodeUserCommand(ctx.homeDir),
+        ],
+        hookWriters: [],
+    },
+};
+/**
+ * Drain a writer's return value into the result list (skip null/undefined,
+ * flatten arrays from writers like ensureProtocolSkills).
+ */
+function pushWriterResult(results, value) {
+    if (!value)
+        return;
+    if (Array.isArray(value)) {
+        for (const r of value)
+            results.push(r);
+    }
+    else {
+        results.push(value);
     }
 }
+/**
+ * Run a descriptor's writers against the given context. The `skipUserIfNotInstalled`
+ * flag consults `isAgentInstalledPerInventory` and drops user-level writers when
+ * the agent isn't present on this machine — preventing init from fabricating
+ * `~/.codex/config.toml` (etc.) on machines that never had codex installed.
+ */
+function runAgentWriters(descriptor, ctx, agentName, opts = {}) {
+    const out = [];
+    for (const fn of descriptor.workspaceWriters)
+        pushWriterResult(out, fn(ctx));
+    for (const fn of descriptor.hookWriters)
+        pushWriterResult(out, fn(ctx));
+    // User-level writers fabricate machine-wide config. When agents-inventory is
+    // available and reports the agent as NOT installed, skip them — see the
+    // brief's "consult agent-inventory before fabricating user-level configs".
+    const installed = opts.skipUserIfNotInstalled
+        ? isAgentInstalledPerInventory(agentName)
+        : undefined;
+    const skipUser = opts.skipUserIfNotInstalled && installed === false;
+    if (!skipUser) {
+        for (const fn of descriptor.userWriters)
+            pushWriterResult(out, fn(ctx));
+    }
+    if (opts.kindFilter) {
+        return out.filter((r) => r.kind === opts.kindFilter);
+    }
+    return out;
+}
+export function writeDetectedAgentAutoConfig(agentName, cwd, env = process.env) {
+    const descriptor = AGENT_WIRING_REGISTRY[agentName];
+    if (!descriptor)
+        return [];
+    const ctx = { cwd, homeDir: resolveHomeDir(env), env, workspacePath: cwd };
+    return runAgentWriters(descriptor, ctx, agentName);
+}
+/**
+ * Map an ExportFormat to the agent whose wiring should run. For formats shared
+ * by multiple agents (e.g. agents-md is reused by codex / opencode / mistral /
+ * hermes), the registry order in AGENT_EXPORT_REGISTRY determines the winner —
+ * matching the existing dedupe behaviour in `brainclaw export --all`.
+ */
+function resolveAgentForFormat(format) {
+    return AGENT_EXPORT_REGISTRY.find((t) => t.format === format)?.agentName;
+}
 export function writeExportCompanionFiles(format, cwd, env = process.env) {
-    switch (format) {
-        case 'claude-md': {
-            const results = [
-                ensureClaudeCodeMcpConfig(cwd),
-                ensureClaudeCodeCommand(cwd),
-                ensureClaudeCodeSettings(cwd),
-            ];
-            const userSettings = ensureClaudeCodeUserSettings(resolveHomeDir(env));
-            if (userSettings)
-                results.push(userSettings);
-            const userCmd = ensureClaudeCodeUserCommand(resolveHomeDir(env));
-            if (userCmd)
-                results.push(userCmd);
-            const dep = ensureProjectDevDependency(cwd);
-            if (dep)
-                results.push(dep);
-            return results;
-        }
-        case 'cline':
-            return [ensureClineMcpConfig(cwd)];
-        case 'windsurf': {
-            const results = [ensureWindsurfModernRules(cwd)];
-            const mcp = ensureWindsurfMcpConfig(resolveHomeDir(env));
-            if (mcp)
-                results.push(mcp);
-            return results;
-        }
-        case 'copilot-instructions':
-            return [ensureVscodeMcpConfig(cwd), ensureCopilotMcpConfig(cwd), ensureCopilotSkill(cwd), ensureCopilotHooks(cwd)];
-        case 'cursor-rules': {
-            const results = [ensureCursorMdc(cwd), ensureCursorHooks(cwd)];
-            const mcp = ensureCursorMcpConfig(resolveHomeDir(env));
-            if (mcp)
-                results.push(mcp);
-            return results;
-        }
-        case 'roo':
-            return [ensureRooMcpConfig(cwd)];
-        case 'kilocode':
-            return [ensureKilocodeMcpConfig(cwd), ensureKilocodeConfig(cwd), ensureUniversalBrainclawSkill(cwd)];
-        case 'continue': {
-            const results = [ensureContinueMcpConfig(cwd)];
-            const homeDir = resolveHomeDir(env);
-            const userMcp = ensureContinueUserMcpConfig(homeDir);
-            if (userMcp)
-                results.push(userMcp);
-            const perms = ensureContinueUserPermissions(homeDir);
-            if (perms)
-                results.push(perms);
-            return results;
-        }
-        case 'gemini-md': {
-            const homeDir = resolveHomeDir(env);
-            const results = [];
-            const mcp = ensureAntigravityMcpConfig(homeDir);
-            if (mcp)
-                results.push(mcp);
-            const hooks = ensureAntigravityHooks(homeDir);
-            if (hooks)
-                results.push(hooks);
-            return results;
-        }
-        case 'agents-md':
-            return [ensureUniversalBrainclawSkill(cwd)];
-        default:
-            return [];
-    }
+    const agentName = resolveAgentForFormat(format);
+    if (!agentName)
+        return [];
+    const descriptor = AGENT_WIRING_REGISTRY[agentName];
+    if (!descriptor)
+        return [];
+    const ctx = { cwd, homeDir: resolveHomeDir(env), env, workspacePath: cwd };
+    // Export is "I want this surface even if the agent isn't installed yet" —
+    // the user explicitly asked for it, so we don't gate on the inventory.
+    return runAgentWriters(descriptor, ctx, agentName);
 }
 /**
  * Patch all MCP config files to use the currently resolved brainclaw binary.
  *
  * Called after upgrade / version --publish-local to fix stale paths.
- * Re-resolves the brainclaw command, then re-runs all ensure*McpConfig()
- * functions with forceResolve=true so existing absolute paths are overwritten.
+ * Re-resolves the brainclaw command, then iterates AGENT_WIRING_REGISTRY with
+ * force-resolve enabled, filtering writer output to `kind: 'mcp'`. Agents that
+ * aren't installed on this machine skip their user-level writers (avoids
+ * minting unrelated user configs as a side effect of an upgrade).
  *
  * Returns the list of configs that were actually updated (not just created).
  */
 export function patchAllMcpConfigs(cwd, env = process.env) {
-    // 1. Clear cached path so resolution picks up the new install location
+    // Clear cached path so resolution picks up the new install location
     resetMcpCommandCache();
-    // 2. Set force-resolve mode so brainclawMcpEntry overwrites existing paths
-    _forceResolve = true;
-    const results = [];
-    const homeDir = resolveHomeDir(env);
-    try {
-        // Workspace-level configs
-        results.push(ensureClaudeCodeMcpConfig(cwd));
-        results.push(ensureVscodeMcpConfig(cwd));
-        results.push(ensureVscodeExtensionRecommendation(cwd));
-        results.push(ensureCopilotMcpConfig(cwd));
-        results.push(ensureClineMcpConfig(cwd));
-        results.push(ensureRooMcpConfig(cwd));
-        results.push(ensureContinueMcpConfig(cwd));
-        results.push(ensureOpenCodeMcpConfig(cwd));
-        // Machine-level configs (in ~ or platform-specific)
-        const userConfigs = [
-            ensureClaudeCodeUserSettings(homeDir, env),
-            ensureCursorMcpConfig(homeDir),
-            ensureWindsurfMcpConfig(homeDir),
-            ensureContinueUserMcpConfig(homeDir),
-            ensureContinueUserPermissions(homeDir),
-            ensureAntigravityMcpConfig(homeDir),
-            ensureOpenClawMcpConfig(homeDir),
-            ensureCodexMcpConfig(homeDir, env),
-            ensureHermesMcpConfig(homeDir),
-        ];
-        for (const r of userConfigs) {
-            if (r)
-                results.push(r);
+    const ctx = { cwd, homeDir: resolveHomeDir(env), env, workspacePath: cwd };
+    // Run inside withForcedResolve so brainclawMcpEntry overwrites existing
+    // absolute paths in user configs (the whole point of the patch pass).
+    const results = withForcedResolve(() => {
+        const acc = [];
+        for (const [agentName, descriptor] of Object.entries(AGENT_WIRING_REGISTRY)) {
+            const agentResults = runAgentWriters(descriptor, ctx, agentName, {
+                skipUserIfNotInstalled: true,
+                kindFilter: 'mcp',
+            });
+            for (const r of agentResults)
+                acc.push(r);
         }
+        return acc;
+    });
+    // Dedupe by filePath — claude-code and claude-sonnet share writers; running
+    // each one twice would emit duplicate "Updated …/.mcp.json" lines.
+    const seen = new Set();
+    const deduped = [];
+    for (const r of results) {
+        if (seen.has(r.filePath))
+            continue;
+        seen.add(r.filePath);
+        deduped.push(r);
     }
-    finally {
-        // Always reset force-resolve mode
-        _forceResolve = false;
-    }
-    return results.filter(r => r.created || r.updated);
+    return deduped.filter((r) => r.created || r.updated);
 }
 //# sourceMappingURL=agent-files.js.map