vgxness 1.5.2 → 1.6.0

package/dist/mcp/claude-code-cli.js

@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
+export function buildClaudeCodeMcpAddCommand(input = {}) {
+    const scope = resolveClaudeCodeScope(input.scope);
+    if (!scope.ok)
+        return scope;
+    const serverName = input.serverName ?? 'vgxness';
+    const command = input.command ?? 'vgxness';
+    const args = input.args ?? ['mcp', 'start'];
+    return commandEnvelope(['mcp', 'add', '--scope', scope.value.canonical, serverName, '--', command, ...args]);
+}
+export function buildClaudeCodeMcpAddJsonCommand(input) {
+    const scope = resolveClaudeCodeScope(input.scope);
+    if (!scope.ok)
+        return scope;
+    return commandEnvelope(['mcp', 'add-json', '--scope', scope.value.canonical, input.serverName ?? 'vgxness', sanitizeJsonArgument(input.json)]);
+}
+export async function runClaudeCodeCliCommand(command, runner = defaultClaudeCodeCliRunner) {
+    return runner(command);
+}
+export function createClaudeCodeCliRegistrationPreview(scope) {
+    const command = buildClaudeCodeMcpAddCommand({ scope });
+    return command.ok ? command.value.preview : ['claude', 'mcp', 'add', '--scope', scope, 'vgxness', '--', 'vgxness', 'mcp', 'start'];
+}
+function commandEnvelope(argv) {
+    return { ok: true, value: { executable: 'claude', argv, preview: ['claude', ...argv].map(redactArg), redacted: true } };
+}
+function sanitizeJsonArgument(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return JSON.stringify(redactUnknown(parsed));
+    }
+    catch {
+        return '<redacted-json>';
+    }
+}
+function redactUnknown(value) {
+    if (Array.isArray(value))
+        return value.map(redactUnknown);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const redacted = {};
+    for (const [key, nested] of Object.entries(value))
+        redacted[key] = /token|secret|password|key/i.test(key) ? '<redacted>' : redactUnknown(nested);
+    return redacted;
+}
+function redactArg(value) {
+    return /token|secret|password/i.test(value) ? '<redacted>' : value;
+}
+function defaultClaudeCodeCliRunner(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command.executable, command.argv, { shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (cause) => {
+            resolve({ command, exitCode: null, stdout: '', stderr: cause.message });
+        });
+        child.on('close', (exitCode) => {
+            resolve({ command, exitCode, stdout: redactOutput(stdout), stderr: redactOutput(stderr) });
+        });
+    });
+}
+function redactOutput(value) {
+    return value.replace(/(token|secret|password)=\S+/gi, '$1=<redacted>');
+}

package/dist/mcp/claude-code-config.js

@@ -74,7 +74,7 @@ export function assertInsideWorkspace(workspaceRoot, targetPath) {
         throw new Error(`Target path is outside workspace root: ${targetPath}`);
 }
 export function claudeAdvisoryPaths(workspaceRoot) {
-    return [join(workspaceRoot, '.claude', 'settings.json'), join(workspaceRoot, '.claude', 'settings.local.json'), join(workspaceRoot, 'CLAUDE.md'), join(workspaceRoot, '.claude', 'CLAUDE.md')];
+    return [join(workspaceRoot, '.claude', 'settings.json'), join(workspaceRoot, '.claude', 'settings.local.json'), join(workspaceRoot, '.claude', 'CLAUDE.md')];
 }
 function arraysEqual(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);

package/dist/mcp/claude-code-project-memory.js

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { projectCanonicalAgentManifestToClaudeProjectMemory } from '../agents/canonical-agent-projection.js';
+import { assertInsideWorkspace } from './claude-code-config.js';
+export const claudeProjectMemoryBeginMarker = '<!-- BEGIN VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
+export const claudeProjectMemoryEndMarker = '<!-- END VGXNESS-MANAGED CLAUDE PROJECT MEMORY -->';
+export function resolveClaudeProjectMemoryPath(workspaceRoot) {
+    const target = resolve(workspaceRoot, 'CLAUDE.md');
+    assertInsideWorkspace(workspaceRoot, target);
+    return target;
+}
+export function renderClaudeProjectMemoryBlock() {
+    const projection = projectCanonicalAgentManifestToClaudeProjectMemory();
+    return [
+        claudeProjectMemoryBeginMarker,
+        `<!-- VGXNESS-GENERATED owner=vgxness provider=claude artifact=claude-project-memory safe-update=true defaultAgent=${projection.defaultAgent} promptContractVersion=${projection.promptContractVersion} canonicalSource=canonical-agent-manifest repositoryInstructions=${projection.repositoryInstructions} -->`,
+        '',
+        '# VGXNESS Claude Project Memory',
+        '',
+        projection.guidance[0] ?? '',
+        '',
+        ...projection.guidance.slice(1).map((line) => `- ${line}`),
+        '',
+        claudeProjectMemoryEndMarker,
+    ].join('\n');
+}
+export function inspectClaudeProjectMemory(workspaceRoot) {
+    let path;
+    try {
+        path = resolveClaudeProjectMemoryPath(workspaceRoot);
+    }
+    catch (cause) {
+        return blocked(resolve(workspaceRoot, 'CLAUDE.md'), false, 'outside_workspace', cause instanceof Error ? cause.message : String(cause));
+    }
+    if (!existsSync(path))
+        return { status: 'missing', path, exists: false, action: 'create', backupRequired: false, message: 'Claude project memory CLAUDE.md does not exist.' };
+    let contents;
+    try {
+        const bytes = readFileSync(path);
+        contents = bytes.toString('utf8');
+        if (!Buffer.from(contents, 'utf8').equals(bytes))
+            return blocked(path, true, 'non_utf8', 'Claude project memory is not valid UTF-8; refusing safe managed-block updates.');
+    }
+    catch (cause) {
+        return blocked(path, true, 'unreadable', `Claude project memory could not be read: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    const beginCount = countOccurrences(contents, claudeProjectMemoryBeginMarker);
+    const endCount = countOccurrences(contents, claudeProjectMemoryEndMarker);
+    if (beginCount === 0 && endCount === 0)
+        return { status: 'unmanaged', path, exists: true, action: 'append-managed-block', backupRequired: true, message: 'Claude project memory exists without a VGXNESS managed block; future apply would append one after backup.', contents };
+    if (beginCount === 0)
+        return blocked(path, true, 'missing_begin_marker', 'Claude project memory has an end marker without a begin marker.');
+    if (endCount === 0)
+        return blocked(path, true, 'missing_end_marker', 'Claude project memory has a begin marker without an end marker.');
+    if (beginCount > 1 || endCount > 1)
+        return blocked(path, true, 'duplicate_markers', 'Claude project memory has duplicate VGXNESS managed-block markers.');
+    const start = contents.indexOf(claudeProjectMemoryBeginMarker);
+    const endMarkerStart = contents.indexOf(claudeProjectMemoryEndMarker);
+    if (endMarkerStart < start)
+        return blocked(path, true, 'reordered_markers', 'Claude project memory end marker appears before begin marker.');
+    const end = endMarkerStart + claudeProjectMemoryEndMarker.length;
+    const inner = contents.slice(start + claudeProjectMemoryBeginMarker.length, endMarkerStart);
+    if (inner.includes(claudeProjectMemoryBeginMarker) || inner.includes(claudeProjectMemoryEndMarker))
+        return blocked(path, true, 'nested_markers', 'Claude project memory has nested VGXNESS managed-block markers.');
+    const metadata = parseMetadata(inner);
+    if (metadata === undefined)
+        return blocked(path, true, 'invalid_metadata', 'Claude project memory managed block is missing VGXNESS metadata.');
+    const ownership = validateMetadataOwnership(metadata);
+    if (!ownership.ok)
+        return blocked(path, true, ownership.reason, ownership.message);
+    const expected = renderClaudeProjectMemoryBlock();
+    const actual = contents.slice(start, end);
+    if (actual === expected)
+        return { status: 'managed-current', path, exists: true, action: 'none', backupRequired: false, message: 'Claude project memory has the current VGXNESS managed block.', blockRange: { start, end }, contents };
+    return { status: 'managed-stale', path, exists: true, action: 'update-managed-block', backupRequired: true, message: 'Claude project memory has a stale VGXNESS managed block; future apply would update only that block after backup.', blockRange: { start, end }, staleReasons: ['managed_block_differs_from_canonical_render'], contents };
+}
+export function mergeClaudeProjectMemory(state) {
+    const block = renderClaudeProjectMemoryBlock();
+    if (state.status === 'missing')
+        return { ok: true, value: { path: state.path, contents: `${block}\n` } };
+    if (state.status === 'unmanaged') {
+        const separator = state.contents.length === 0 ? '' : state.contents.endsWith('\n') ? '\n' : '\n\n';
+        return { ok: true, value: { path: state.path, contents: `${state.contents}${separator}${block}\n` } };
+    }
+    if (state.status === 'managed-stale')
+        return { ok: true, value: { path: state.path, contents: state.contents.slice(0, state.blockRange.start) + block + state.contents.slice(state.blockRange.end) } };
+    if (state.status === 'managed-current')
+        return { ok: true, value: { path: state.path, contents: state.contents } };
+    return { ok: false, error: { code: 'validation_failed', message: state.message } };
+}
+function blocked(path, exists, reason, message) {
+    return { status: 'blocked', path, exists, action: 'blocked', backupRequired: false, reason, message };
+}
+function countOccurrences(contents, needle) {
+    let count = 0;
+    let index = contents.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = contents.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+function parseMetadata(inner) {
+    const line = inner.split(/\r?\n/).find((item) => item.includes('VGXNESS-GENERATED'));
+    if (line === undefined)
+        return undefined;
+    const metadata = {};
+    for (const part of line.replace('<!--', '').replace('-->', '').trim().split(/\s+/)) {
+        const [key, value] = part.split('=');
+        if (key !== undefined && value !== undefined)
+            metadata[key] = value;
+    }
+    return metadata;
+}
+function validateMetadataOwnership(metadata) {
+    if (metadata['VGXNESS-GENERATED'] !== undefined)
+        return { ok: false, reason: 'invalid_metadata', message: 'Claude project memory metadata is malformed.' };
+    if (metadata.owner !== 'vgxness')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not owned by VGXNESS.' };
+    if (metadata.provider !== 'claude')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not for the Claude provider.' };
+    if (metadata.artifact !== 'claude-project-memory')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block has a conflicting artifact type.' };
+    if (metadata['safe-update'] !== 'true')
+        return { ok: false, reason: 'conflicting_ownership', message: 'Claude project memory managed block is not marked safe for update.' };
+    return { ok: true };
+}

package/dist/mcp/claude-code-scope.js

@@ -0,0 +1,18 @@
+export const claudeCodeCanonicalScopes = ['local', 'project', 'user'];
+export function resolveClaudeCodeScope(input, fallback = 'project') {
+    if (input !== undefined && input.trim().length === 0)
+        return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+    const raw = input?.trim() || fallback;
+    if (raw === 'local' || raw === 'project' || raw === 'user')
+        return { ok: true, value: { canonical: raw, input: raw, warnings: [] } };
+    if (raw === 'personal') {
+        return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code scope `personal` is accepted for VGXNESS compatibility and maps to Claude `user`.'] } };
+    }
+    if (raw === 'global') {
+        return { ok: true, value: { canonical: 'user', input: raw, warnings: ['Claude Code legacy scope `global` is deprecated and maps to Claude `user`.'] } };
+    }
+    return { ok: false, error: { code: 'validation_failed', message: '--scope for Claude must be local, project, or user (compatibility aliases: personal, global).' } };
+}
+export function isClaudeCodeUserScope(scope) {
+    return scope === 'user';
+}

package/dist/mcp/client-install-claude-code-contract.js

@@ -1,9 +1,22 @@
 import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
+import { buildClaudeCodeMcpAddCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, resolveClaudeCodeMcpJsonPath } from './claude-code-config.js';
+import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
 export function planClaudeCodeMcpInstall(input) {
     const source = input.databasePathSource ?? 'flag';
     const server = createClaudeCodeMcpServerConfig(input.databasePath, source);
     const overwriteVgxness = input.overwriteVgxness === true;
+    const resolvedScope = resolveClaudeCodeScope(input.scope);
+    if (!resolvedScope.ok)
+        return refused(input, server, 'unsupported_scope', resolvedScope.error.message, [], [], overwriteVgxness);
+    const cliCommand = buildClaudeCodeMcpAddCommand({ scope: resolvedScope.value.canonical });
+    if (!cliCommand.ok)
+        return refused(input, server, 'unsupported_scope', cliCommand.error.message, [], [], overwriteVgxness);
+    if (resolvedScope.value.canonical !== 'project') {
+        const targets = [{ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' }];
+        return { ...base(input, server, targets, [], false, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings), status: 'would_install' };
+    }
     let mcpPath;
     try {
         mcpPath = resolveClaudeCodeMcpJsonPath(input.cwd);
@@ -13,6 +26,7 @@ export function planClaudeCodeMcpInstall(input) {
     }
     const mcpState = inspectClaudeCodeMcpConfig(input.cwd);
     const targets = [];
+    targets.push({ kind: 'cli-mcp-registration', scope: resolvedScope.value.canonical, command: cliCommand.value, action: 'register' });
     const preservedTopLevelKeys = mcpState.parsed ? Object.keys(mcpState.config) : [];
     if (mcpState.status === 'missing')
         targets.push({ kind: 'mcp-json', path: mcpPath, action: 'create' });
@@ -25,20 +39,22 @@ export function planClaudeCodeMcpInstall(input) {
     const agentInspection = inspectClaudeCodeAgents(input.cwd);
     for (const agent of agentInspection.agents) {
         if (agent.status === 'missing')
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'create' });
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'create' });
         else if (agent.status === 'managed')
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'update-vgxness' });
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'update-vgxness' });
         else
-            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'blocked', reason: agent.detail });
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, scope: 'project', external: false, action: 'blocked', reason: agent.detail });
     }
+    const projectMemory = inspectClaudeProjectMemory(input.cwd);
+    targets.push({ kind: 'project-memory', path: projectMemory.path, action: projectMemory.action, status: projectMemory.status, backupRequired: projectMemory.backupRequired, ...(projectMemory.status === 'blocked' ? { reason: projectMemory.message } : {}) });
     const blocked = targets.find((target) => target.action === 'blocked');
     if (blocked !== undefined) {
-        const reason = blocked.kind === 'mcp-json' ? mcpRefusalReason(mcpState.status) : 'existing_vgxness_agent';
+        const reason = blocked.kind === 'mcp-json' ? mcpRefusalReason(mcpState.status) : blocked.kind === 'project-memory' ? projectMemoryRefusalReason(projectMemory) : 'existing_vgxness_agent';
         return refused(input, server, reason, blocked.reason ?? 'Claude Code install plan is blocked by an existing conflicting target.', targets, preservedTopLevelKeys, overwriteVgxness);
     }
-    const backupRequired = targets.some((target) => (target.kind === 'mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness'));
+    const backupRequired = targets.some((target) => (target.kind === 'mcp-json' && target.action !== 'create') || (target.kind === 'agent-file' && target.action === 'update-vgxness') || (target.kind === 'project-memory' && target.backupRequired));
     return {
-        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness),
+        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, resolvedScope.value.canonical, cliCommand.value, resolvedScope.value.warnings),
         status: 'would_install',
     };
 }
@@ -46,25 +62,30 @@ export function expectedClaudeCodeRenderedAgents(workspaceRoot) {
     return expectedClaudeCodeAgentFiles(workspaceRoot).map((agent) => ({ path: agent.path, agentName: agent.name, contents: renderClaudeCodeAgentMarkdown(agent) }));
 }
 function refused(input, server, reason, message, targets, preservedTopLevelKeys, overwriteVgxness) {
-    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness), status: 'refused', reason, message };
+    const resolved = resolveClaudeCodeScope(input.scope);
+    const canonical = resolved.ok ? resolved.value.canonical : 'project';
+    const cli = buildClaudeCodeMcpAddCommand({ scope: canonical });
+    return { ...base(input, server, targets, preservedTopLevelKeys, false, overwriteVgxness, canonical, cli.ok ? cli.value : undefined, resolved.ok ? resolved.value.warnings : []), status: 'refused', reason, message };
 }
-function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness) {
+function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness, canonicalClaudeScope, cliCommand, scopeWarnings) {
     const source = input.databasePathSource ?? 'flag';
-    const targetPath = resolveClaudeCodeMcpJsonPath(input.cwd);
+    const targetPath = canonicalClaudeScope === 'project' ? resolveClaudeCodeMcpJsonPath(input.cwd) : `claude-cli:${canonicalClaudeScope}:vgxness`;
     return {
         version: 1,
         kind: 'mcp-client-install-claude-code',
         installable: true,
         mutating: false,
         provider: 'claude',
-        scope: 'project',
+        scope: input.scope ?? 'project',
         targetPath,
         targets,
         backupRequired,
         safety: { operation: 'plan', mutating: false, writesProviderConfig: false, targetPath, backupRequired, mergePolicy: backupRequired ? 'merge-preserve-existing' : 'create' },
         warnings: [
-            'Claude Code support is project-local only and writes only .mcp.json plus .claude/agents/*.md after explicit confirmation.',
-            'VGXNESS never writes ~/.claude.json, CLAUDE.md, or .claude/CLAUDE.md and does not execute or install Claude Code.',
+            ...scopeWarnings,
+            'Claude Code MCP registration is modeled as Claude CLI argv, never shell strings or manual ~/.claude.json mutation.',
+            'Project compatibility may write .mcp.json, .claude/agents/*.md, and a guarded project-root CLAUDE.md managed block after explicit confirmation/preflight; user/local scopes do not inspect or write private Claude config.',
+            'VGXNESS never manually writes ~/.claude.json or .claude/CLAUDE.md; project-root CLAUDE.md is only touched through the guarded project install managed block.',
         ],
         verificationHints: [
             { kind: 'restart-client', message: 'Restart or reload Claude Code after confirmed project config installation.' },
@@ -72,6 +93,8 @@ function base(input, server, targets, preservedTopLevelKeys, backupRequired, ove
             { kind: 'command', message: 'Run the MCP doctor command after installation.', command: createClaudeCodeMcpDoctorCommand(input.databasePath, source) },
         ],
         server,
+        ...(cliCommand === undefined ? {} : { cliCommand }),
+        canonicalClaudeScope,
         preservedTopLevelKeys,
         agentNames: targets.filter((target) => target.kind === 'agent-file').map((target) => target.agentName),
         overwriteVgxness,
@@ -84,3 +107,8 @@ function mcpRefusalReason(status) {
         return 'existing_vgxness_mcp';
     return 'invalid_mcp_shape';
 }
+function projectMemoryRefusalReason(state) {
+    if (state.status === 'blocked' && state.reason === 'conflicting_ownership')
+        return 'conflicting_claude_project_memory';
+    return 'malformed_claude_project_memory';
+}

package/dist/mcp/client-install-claude-code.js

@@ -2,20 +2,24 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createManagedProviderConfigBackup } from '../setup/backup-rollback-service.js';
 import { parseClaudeAgentFrontmatter } from './claude-code-agent-config.js';
+import { runClaudeCodeCliCommand } from './claude-code-cli.js';
 import { createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, mergeClaudeCodeMcpConfig } from './claude-code-config.js';
+import { inspectClaudeProjectMemory, mergeClaudeProjectMemory } from './claude-code-project-memory.js';
 import { expectedClaudeCodeRenderedAgents, planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
 export async function installClaudeCodeMcpClient(input) {
     const source = input.databasePathSource ?? 'flag';
     const server = createClaudeCodeMcpServerConfig(input.databasePath, source);
-    const plan = planClaudeCodeMcpInstall({ cwd: input.cwd, databasePath: input.databasePath, databasePathSource: source, ...(input.overwriteVgxness !== undefined ? { overwriteVgxness: input.overwriteVgxness } : {}) });
-    if (!input.confirmed)
-        return refusal('confirmation_required', '`mcp install claude` requires explicit --yes before any project config write.', plan, server, [], []);
+    const plan = planClaudeCodeMcpInstall({ cwd: input.cwd, databasePath: input.databasePath, databasePathSource: source, ...(input.overwriteVgxness !== undefined ? { overwriteVgxness: input.overwriteVgxness } : {}), ...(input.scope !== undefined ? { scope: input.scope } : {}) });
     if (plan.status === 'refused')
         return refusal(plan.reason, plan.message, plan, server, [], []);
+    if (!input.confirmed)
+        return refusal('confirmation_required', '`mcp install claude` requires explicit --yes before any project config write.', plan, server, [], []);
     if (input.preflight === undefined) {
         return refusal('preflight_failed', 'Claude Code provider config writes require VGXNESS preflight before any project config write.', plan, server, [], []);
     }
-    const preflightPaths = unique(plan.targets.filter((target) => target.action !== 'blocked').map((target) => target.path));
+    const preflightPaths = unique(plan.targets.flatMap((target) => (isMutatingTarget(target) ? [target.path] : [])));
+    if (plan.canonicalClaudeScope !== 'project')
+        preflightPaths.unshift(plan.targetPath);
     for (const targetPath of preflightPaths) {
         const preflight = await input.preflight({
             category: 'provider-tool',
@@ -32,9 +36,20 @@ export async function installClaudeCodeMcpClient(input) {
     }
     const backups = [];
     const writtenPaths = [];
-    const existingTargets = plan.targets.filter((target) => target.action === 'merge' || target.action === 'update-vgxness');
+    if (plan.canonicalClaudeScope !== 'project') {
+        if (input.cliRunner === undefined)
+            return refusal('preflight_failed', 'Claude CLI MCP registration apply requires an injected runner boundary; read-only plans never execute Claude Code.', plan, server, [], []);
+        if (plan.cliCommand === undefined)
+            return refusal('preflight_failed', 'Claude CLI MCP registration command is unavailable.', plan, server, [], []);
+        const cli = await runClaudeCodeCliCommand(plan.cliCommand, input.cliRunner);
+        const cliResult = { exitCode: cli.exitCode, stdout: cli.stdout, stderr: cli.stderr, preview: cli.command.preview };
+        if (cli.exitCode !== 0)
+            return refusal('preflight_failed', `Claude CLI MCP registration failed with exit code ${cli.exitCode ?? 'unknown'}.`, plan, server, [], [], cliResult);
+        return { version: 1, kind: 'mcp-client-install-claude-code', status: 'installed', targetPath: plan.targetPath, writtenPaths: [], backups: [], safety: applySafety(plan), server, warnings: plan.warnings, verificationHints: plan.verificationHints, agentNames: plan.agentNames, overwriteVgxness: plan.overwriteVgxness, cliResult };
+    }
+    const existingTargets = plan.targets.filter((target) => target.kind !== 'cli-mcp-registration' && (target.action === 'merge' || target.action === 'update-vgxness' || target.action === 'append-managed-block'));
     for (const target of existingTargets) {
-        const backup = createBackup(target.path);
+        const backup = createBackup(target.path, target.kind === 'project-memory' ? 'project-memory' : 'config');
         if (!backup.ok)
             return refusal('backup_failed', backup.error.message, plan, server, writtenPaths, backups);
         backups.push(toBackupSummary(backup.value));
@@ -54,6 +69,11 @@ export async function installClaudeCodeMcpClient(input) {
             return refusal('post_write_validation_failed', `Claude agent ${agent.agentName} failed post-write validation.`, plan, server, writtenPaths, backups);
         writtenPaths.push(agent.path);
     }
+    const projectMemoryWrite = writeProjectMemory(plan);
+    if (!projectMemoryWrite.ok)
+        return refusal('post_write_validation_failed', projectMemoryWrite.error.message, plan, server, writtenPaths, backups);
+    if (projectMemoryWrite.value !== undefined)
+        writtenPaths.push(projectMemoryWrite.value);
     return { version: 1, kind: 'mcp-client-install-claude-code', status: 'installed', targetPath: plan.targetPath, writtenPaths, backups, safety: applySafety(plan), server, warnings: plan.warnings, verificationHints: plan.verificationHints, agentNames: plan.agentNames, overwriteVgxness: plan.overwriteVgxness };
 }
 function writeMcpJson(cwd, plan, server) {
@@ -68,11 +88,35 @@ function writeMcpJson(cwd, plan, server) {
     const after = inspectClaudeCodeMcpConfig(cwd);
     return after.status === 'configured' ? { ok: true, value: plan.targetPath } : { ok: false, error: { code: 'validation_failed', message: 'Claude .mcp.json did not validate after write.' } };
 }
-function createBackup(path) {
-    return createManagedProviderConfigBackup({ targetPath: path, provider: 'claude', scope: 'project', createdByOperation: 'mcp-client-install-claude-code', reason: 'pre-merge-safety', description: 'Backup existing Claude Code project config before merging VGXNESS MCP or agent configuration.' });
+function writeProjectMemory(plan) {
+    const target = plan.targets.find((item) => item.kind === 'project-memory');
+    if (target === undefined || target.action === 'none')
+        return { ok: true, value: undefined };
+    if (target.action === 'blocked')
+        return { ok: false, error: { code: 'validation_failed', message: target.reason ?? 'Claude project memory is blocked.' } };
+    const state = inspectClaudeProjectMemory(dirname(target.path));
+    if (state.action !== target.action)
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude project memory changed after planning; rerun apply.' } };
+    const merged = mergeClaudeProjectMemory(state);
+    if (!merged.ok)
+        return merged;
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeFileSync(target.path, merged.value.contents);
+    const after = inspectClaudeProjectMemory(dirname(target.path));
+    return after.status === 'managed-current' ? { ok: true, value: target.path } : { ok: false, error: { code: 'validation_failed', message: 'Claude project memory did not validate as managed-current after write.' } };
+}
+function createBackup(path, kind) {
+    return createManagedProviderConfigBackup({
+        targetPath: path,
+        provider: 'claude',
+        scope: 'project',
+        createdByOperation: 'mcp-client-install-claude-code',
+        reason: kind === 'project-memory' ? 'pre-project-memory-update-safety' : 'pre-merge-safety',
+        description: kind === 'project-memory' ? 'Backup existing Claude Code project memory before appending or updating the VGXNESS managed block.' : 'Backup existing Claude Code project config before merging VGXNESS MCP or agent configuration.',
+    });
 }
-function refusal(reason, message, plan, server, writtenPaths, backups) {
-    return { version: 1, kind: 'mcp-client-install-claude-code', status: 'refused', reason, message, targetPath: plan.targetPath, writtenPaths, backups, safety: { ...plan.safety, operation: 'apply', mutating: false, writesProviderConfig: false }, server, warnings: plan.warnings, verificationHints: plan.verificationHints, agentNames: plan.agentNames, overwriteVgxness: plan.overwriteVgxness };
+function refusal(reason, message, plan, server, writtenPaths, backups, cliResult) {
+    return { version: 1, kind: 'mcp-client-install-claude-code', status: 'refused', reason, message, targetPath: plan.targetPath, writtenPaths, backups, safety: { ...plan.safety, operation: 'apply', mutating: false, writesProviderConfig: false }, server, warnings: plan.warnings, verificationHints: plan.verificationHints, agentNames: plan.agentNames, overwriteVgxness: plan.overwriteVgxness, ...(cliResult === undefined ? {} : { cliResult }) };
 }
 function applySafety(plan) {
     return { ...plan.safety, operation: 'apply', mutating: true, writesProviderConfig: true };
@@ -83,3 +127,10 @@ function toBackupSummary(backup) {
 function unique(values) {
     return [...new Set(values)];
 }
+function isMutatingTarget(target) {
+    if (target.kind === 'cli-mcp-registration')
+        return false;
+    if (target.action === 'blocked' || target.action === 'none')
+        return false;
+    return true;
+}

package/dist/mcp/index.js

@@ -6,7 +6,10 @@ export * from './client-install-claude-code.js';
 export * from './client-install-claude-code-contract.js';
 export * from './client-setup-preview.js';
 export * from './claude-code-agent-config.js';
+export * from './claude-code-cli.js';
 export * from './claude-code-config.js';
+export * from './claude-code-project-memory.js';
+export * from './claude-code-scope.js';
 export * from './control-plane.js';
 export * from './doctor.js';
 export * from './opencode-visibility.js';

package/dist/mcp/provider-change-plan.js

@@ -2,7 +2,10 @@ import { resolveMemoryDatabasePath } from '../memory/storage-paths.js';
 import { planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from './client-install-opencode-contract.js';
 import { ProviderDoctorService } from './provider-doctor.js';
+import { CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, isUserGlobalScope } from './provider-health-types.js';
 import { ProviderStatusService } from './provider-status.js';
+import { createClaudeCodeCliRegistrationPreview } from './claude-code-cli.js';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
 export const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
 export const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
 const safety = {
@@ -75,6 +78,11 @@ export class ProviderChangePlanService {
         const doctor = (this.deps.providerDoctor ?? new ProviderDoctorService()).getDoctor({ project: normalized.project, scope: normalized.scope, providerAdapter: 'claude', workspaceRoot: normalized.workspaceRoot, env: this.deps.env ?? process.env, payloadMode: normalized.payloadMode });
         if (!doctor.ok)
             return doctor;
+        const claudeScope = resolveClaudeCodeScope(normalized.scope);
+        if (!claudeScope.ok)
+            return claudeScope;
+        if (isUserGlobalScope(normalized.scope) || claudeScope.value.canonical === 'local')
+            return { ok: true, value: claudeUserGlobalEnvelope(normalized, status.value, doctor.value, claudeScope.value.canonical, claudeScope.value.warnings) };
         const databasePath = resolveMemoryDatabasePath({ cwd: normalized.workspaceRoot, env: this.deps.env ?? process.env });
         if (!databasePath.ok)
             return { ok: true, value: blockedPlanEnvelope(normalized, status.value, doctor.value, databasePath.error.message) };
@@ -82,6 +90,42 @@ export class ProviderChangePlanService {
         return { ok: true, value: claudeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source) };
     }
 }
+function claudeUserGlobalEnvelope(input, status, doctor, canonicalScope = 'user', scopeWarnings = []) {
+    const warnings = [
+        ...scopeWarnings,
+        ...statusWarnings(status),
+        ...doctor.recommendations,
+        'Claude private config mutation is intentionally unsupported by VGXNESS; future apply uses Claude CLI argv only after confirmation/preflight.',
+    ];
+    const envelope = {
+        ...baseEnvelope(input),
+        supported: true,
+        status: 'planned',
+        summary: `Read-only Claude ${canonicalScope} change planning completed. VGXNESS will not read or write private Claude config files from this plan. Future apply requires confirmation/preflight and uses Claude CLI argv only: claude mcp add --scope ${canonicalScope} vgxness -- vgxness mcp start.`,
+        providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
+        statusSummary: statusSummary(status),
+        statusFindings: status.config,
+        doctorSummary: doctorSummary(doctor),
+        doctorFindings: doctor.checks,
+        previewEffects: {
+            action: 'none',
+            backupRequired: false,
+            preservedTopLevelKeys: [],
+            cliCommandPreview: createClaudeCodeCliRegistrationPreview(canonicalScope),
+            installsAgents: false,
+            agentNames: [],
+            refusalMessage: 'Read-only plan only; future apply requires confirmation/preflight and does not mutate ~/.claude.json manually.',
+        },
+        backupRollback: descriptiveBackupPolicy(false),
+        confirmations: confirmationPolicy(),
+        risks: [
+            `VGXNESS cannot verify Claude ${canonicalScope} MCP registration from read-only planning because it intentionally avoids reading private Claude config and does not execute Claude Code.`,
+            `Supported Claude read-only capabilities are: ${CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES.join(', ')}.`,
+        ],
+        warnings,
+    };
+    return input.payloadMode === 'verbose' ? { ...envelope, rawSources: { status, doctor } } : envelope;
+}
 function normalizeInput(input) {
     return {
         project: input.project?.trim() || 'vgxness',
@@ -180,7 +224,7 @@ function claudeEnvelope(input, status, doctor, installPlan, source) {
         supported: true,
         status: installPlan.status === 'refused' ? 'blocked' : 'planned',
         ...(installPlan.status === 'refused' ? { code: 'PLAN_UNAVAILABLE' } : {}),
-        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update project .mcp.json and ${installPlan.agentNames.length} agent file(s).`,
+        summary: installPlan.status === 'refused' ? `Read-only Claude ${input.changeType} planning completed; future install is currently refused: ${installPlan.message}` : `Read-only Claude ${input.changeType} planning completed; future confirmed write would update project .mcp.json, ${installPlan.agentNames.length} agent file(s), and project-root CLAUDE.md as needed.`,
         providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
@@ -262,10 +306,18 @@ function previewEffects(plan) {
     };
 }
 function previewEffectsClaude(plan) {
+    const projectMemory = projectMemoryPreview(plan.targets);
     if (plan.status === 'refused')
-        return { action: 'refused', targetPath: plan.targetPath, backupRequired: false, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'refused', refusalReason: plan.reason, refusalMessage: plan.message };
+        return { action: 'refused', targetPath: plan.targetPath, backupRequired: false, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'refused', refusalReason: plan.reason, refusalMessage: plan.message, ...(projectMemory === undefined ? {} : { projectMemory }) };
     const mcpTarget = plan.targets.find((target) => target.kind === 'mcp-json');
-    return { action: mcpTarget?.action === 'create' ? 'would-create' : 'would-merge', targetPath: plan.targetPath, backupRequired: plan.backupRequired, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'would_install' };
+    return { action: mcpTarget?.action === 'create' ? 'would-create' : 'would-merge', targetPath: plan.targetPath, backupRequired: plan.backupRequired, preservedTopLevelKeys: plan.preservedTopLevelKeys, serverCommand: ['vgxness', ...plan.server.args], installsAgents: true, agentNames: plan.agentNames, installPlanStatus: 'would_install', ...(projectMemory === undefined ? {} : { projectMemory }) };
+}
+function projectMemoryPreview(targets) {
+    const target = targets.find((item) => item.kind === 'project-memory');
+    if (target === undefined)
+        return undefined;
+    const action = target.action === 'create' ? 'would-create' : target.action === 'append-managed-block' ? 'would-append' : target.action === 'update-managed-block' ? 'would-update-managed-block' : target.action === 'none' ? 'up-to-date' : 'refused';
+    return { path: target.path, status: target.status, action, backupRequired: target.backupRequired, ...(target.reason === undefined ? {} : { message: target.reason }) };
 }
 function descriptiveBackupPolicy(backupRequired) {
     return {
@@ -300,7 +352,7 @@ function risksForOpenCode(status, doctor, plan, source) {
     return risks;
 }
 function risksForClaude(status, doctor, plan, source) {
-    const risks = ['Claude project .mcp.json may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
+    const risks = ['Claude project .mcp.json and project-root CLAUDE.md may affect collaborators if committed; review before committing.', 'Claude Code runtime MCP approval happens in Claude Code; this plan does not prove runtime connection.'];
     if (status.status !== 'ready')
         risks.push(`Provider status is ${status.status}; future writes should review status findings first.`);
     if (doctor.status !== 'healthy')