vgxness 1.5.1 → 1.5.2

package/dist/cli/commands/mcp-dispatcher.js

@@ -1,17 +1,20 @@
 import { installOpenCodeMcpClient } from '../../mcp/client-install-opencode.js';
+import { installClaudeCodeMcpClient } from '../../mcp/client-install-claude-code.js';
+import { planClaudeCodeMcpInstall } from '../../mcp/client-install-claude-code-contract.js';
 import { planOpenCodeMcpInstall } from '../../mcp/client-install-opencode-contract.js';
 import { createMcpClientSetupPreview, isMcpClientSetupProvider } from '../../mcp/client-setup-preview.js';
 import { createMcpDoctorReport } from '../../mcp/doctor.js';
 import { createOpenCodeMcpVisibilityReport } from '../../mcp/opencode-visibility.js';
+import { RunService } from '../../runs/run-service.js';
 import { databasePathFor, databasePathSelectionFor, opencodeInstallScopeFlag, optionalNumberFlag, optionalStringFlag } from '../cli-flags.js';
 import { usageFailure, validationFailure } from '../cli-help.js';
-import { jsonResult, resultFailure } from '../cli-helpers.js';
+import { jsonResult, openCliDatabase, resultFailure } from '../cli-helpers.js';
 import { renderDoctorReport } from '../doctor-renderer.js';
 export function runMcpInstallCommand(parsed, environment) {
     return (async () => {
         const client = parsed.positionals[2];
-        if (client !== 'opencode')
-            return usageFailure('mcp install requires client opencode');
+        if (client !== 'opencode' && client !== 'claude')
+            return usageFailure('mcp install requires client opencode or claude');
         const databasePath = databasePathSelectionFor(parsed.flags, environment);
         if (!databasePath.ok)
             return resultFailure(databasePath);
@@ -20,6 +23,35 @@ export function runMcpInstallCommand(parsed, environment) {
             return resultFailure(scope);
         const mcpOnly = parsed.flags['mcp-only'] === true || parsed.flags['no-agents'] === true;
         const overwriteVgxness = parsed.flags['overwrite-vgxness'] === true || parsed.flags.reinstall === true;
+        if (client === 'claude') {
+            if (parsed.flags.plan === true) {
+                return jsonResult({ ok: true, value: planClaudeCodeMcpInstall({ cwd: environment.cwd, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, overwriteVgxness }) });
+            }
+            if (parsed.flags.yes !== true) {
+                return resultFailure({ ok: false, error: { code: 'validation_failed', message: 'confirmation_required: `mcp install claude` requires explicit --yes before any project config write.' } });
+            }
+            if (optionalStringFlag(parsed.flags, 'run-id') === undefined) {
+                return resultFailure({ ok: false, error: { code: 'validation_failed', message: 'preflight_failed: Claude Code provider config writes require VGXNESS preflight; pass --run-id for an existing VGXNESS run before using --yes.' } });
+            }
+            const opened = openCliDatabase(databasePath.value.path);
+            if (!opened.ok)
+                return resultFailure(opened);
+            try {
+                const preflight = createClaudeCodeInstallPreflight(parsed, opened.value, environment);
+                const result = await installClaudeCodeMcpClient({
+                    cwd: environment.cwd,
+                    databasePath: databasePath.value.path,
+                    databasePathSource: databasePath.value.source,
+                    confirmed: true,
+                    overwriteVgxness,
+                    preflight,
+                });
+                return result.status === 'installed' ? jsonResult({ ok: true, value: result }) : resultFailure({ ok: false, error: { code: 'validation_failed', message: `${result.reason}: ${result.message}` } });
+            }
+            finally {
+                opened.value.close();
+            }
+        }
         if (parsed.flags.plan === true) {
             return jsonResult({
                 ok: true,
@@ -55,6 +87,36 @@ export function runMcpInstallCommand(parsed, environment) {
             });
     })();
 }
+function createClaudeCodeInstallPreflight(parsed, database, environment) {
+    return (request) => {
+        const runId = optionalStringFlag(parsed.flags, 'run-id');
+        if (runId === undefined) {
+            return validationFailure('Claude Code provider config writes require VGXNESS preflight; pass --run-id for an existing VGXNESS run before using --yes.');
+        }
+        const service = new RunService(database);
+        const details = service.getRun(runId);
+        if (!details.ok)
+            return details;
+        const phase = optionalStringFlag(parsed.flags, 'phase') ?? details.value.phase;
+        const agentId = optionalStringFlag(parsed.flags, 'agent-id') ?? details.value.selectedAgentId;
+        const preflight = service.preflightOperation({
+            runId,
+            category: request.category,
+            operation: request.operation,
+            workspaceRoot: environment.cwd,
+            targetPath: request.targetPath,
+            providerToolName: request.providerToolName,
+            phase,
+            agentId,
+        });
+        if (!preflight.ok)
+            return preflight;
+        if (preflight.value.outcome !== 'allowed') {
+            return validationFailure(`VGXNESS preflight ${preflight.value.outcome} for Claude Code provider config write: ${request.targetPath}`);
+        }
+        return { ok: true, value: preflight.value };
+    };
+}
 export function runMcpSetupCommand(parsed, environment) {
     if (parsed.flags.preview !== true)
         return usageFailure('mcp setup requires --preview; provider config installation is not supported');

package/dist/cli/index.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { startVgxMcpStdioServer } from '../mcp/stdio-server.js';
 import { dispatchCliAsync } from './dispatcher.js';
 import { resolveMcpStartDatabasePath } from './mcp-start-path.js';
 void main();
@@ -12,6 +11,7 @@ async function main() {
             process.exitCode = 1;
             return;
         }
+        const { startVgxMcpStdioServer } = await import('../mcp/stdio-server.js');
         await startVgxMcpStdioServer({ databasePath: databasePath.value });
         return;
     }

package/dist/governance/governance-report-builder.js

@@ -59,18 +59,53 @@ export class GovernanceReportBuilder {
             warnings.push('missing-change-sdd-snapshot-skipped');
             return { ok: true, value: report };
         }
-        const status = this.services.sdd.getStatus({
-            project: input.project,
+        if (this.tryBuildOptimizedSddSnapshot(report, input.project, change, phase, payloadMode, warnings)) {
+            report.warnings = dedupe(warnings);
+            report.openCode.warnings = dedupe(report.openCode.warnings ?? []);
+            return { ok: true, value: report };
+        }
+        this.buildFallbackSddSnapshot(report, input.project, change, phase, payloadMode, warnings);
+        report.warnings = dedupe(warnings);
+        report.openCode.warnings = dedupe(report.openCode.warnings ?? []);
+        return { ok: true, value: report };
+    }
+    tryBuildOptimizedSddSnapshot(report, project, change, phase, payloadMode, warnings) {
+        if (this.services.sdd.getGovernanceSnapshot === undefined)
+            return false;
+        if (phase !== undefined && !isSddPhase(phase)) {
+            warnings.push('sdd-readiness-skipped-non-sdd-phase');
+            return false;
+        }
+        const snapshot = this.services.sdd.getGovernanceSnapshot({
+            project,
             change,
+            payloadMode,
+            ...(phase === undefined ? {} : { phase }),
         });
+        if (!snapshot.ok) {
+            warnings.push(`sdd-snapshot-unavailable:${snapshot.error.code}`);
+            return false;
+        }
+        report.sdd.status = snapshot.value.status;
+        report.sdd.artifacts = snapshot.value.artifacts;
+        warnings.push(...snapshot.value.warnings);
+        if (snapshot.value.readiness !== undefined) {
+            report.sdd.readiness = snapshot.value.readiness;
+            for (const blocker of snapshot.value.readiness.blockedPrerequisites ?? [])
+                warnings.push(`missing-accepted-prerequisite:${blocker.phase}:${blocker.reason}`);
+        }
+        else {
+            warnings.push('sdd-readiness-skipped-missing-phase');
+        }
+        return true;
+    }
+    buildFallbackSddSnapshot(report, project, change, phase, payloadMode, warnings) {
+        const status = this.services.sdd.getStatus({ project, change });
         if (status.ok)
             report.sdd.status = status.value;
         else
             warnings.push(`sdd-status-unavailable:${status.error.code}`);
-        const listed = this.services.sdd.listArtifacts({
-            project: input.project,
-            change,
-        });
+        const listed = this.services.sdd.listArtifacts({ project, change });
         if (listed.ok) {
             report.sdd.artifacts = listed.value.artifacts.map((artifact) => {
                 const envelope = normalizeSddArtifact(artifact);
@@ -81,34 +116,21 @@ export class GovernanceReportBuilder {
                         phase: artifact.phase,
                         topicKey: artifact.topicKey,
                         artifact: compactArtifact,
-                        envelope: {
-                            ...envelope,
-                            artifact: compactArtifact,
-                        },
+                        envelope: { ...envelope, artifact: compactArtifact },
                     };
                 }
-                return {
-                    phase: artifact.phase,
-                    topicKey: artifact.topicKey,
-                    artifact,
-                    envelope,
-                };
+                return { phase: artifact.phase, topicKey: artifact.topicKey, artifact, envelope };
             });
         }
         else {
             warnings.push(`sdd-artifacts-unavailable:${listed.error.code}`);
         }
         if (phase !== undefined && isSddPhase(phase)) {
-            const readiness = this.services.sdd.getReady({
-                project: input.project,
-                change,
-                phase,
-            });
+            const readiness = this.services.sdd.getReady({ project, change, phase });
             if (readiness.ok) {
                 report.sdd.readiness = readiness.value;
-                for (const blocker of readiness.value.blockedPrerequisites ?? []) {
+                for (const blocker of readiness.value.blockedPrerequisites ?? [])
                     warnings.push(`missing-accepted-prerequisite:${blocker.phase}:${blocker.reason}`);
-                }
             }
             else {
                 warnings.push(`sdd-readiness-unavailable:${readiness.error.code}`);
@@ -120,9 +142,6 @@ export class GovernanceReportBuilder {
         else {
             warnings.push('sdd-readiness-skipped-missing-phase');
         }
-        report.warnings = dedupe(warnings);
-        report.openCode.warnings = dedupe(report.openCode.warnings ?? []);
-        return { ok: true, value: report };
     }
     buildOverlay(input, run, agent, warnings) {
         if (this.services.managerProfiles === undefined)

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

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { projectCanonicalAgentManifestToClaudeCode } from '../agents/canonical-agent-projection.js';
+import { assertInsideWorkspace } from './claude-code-config.js';
+export const claudeCodeGeneratedMarker = 'VGXNESS-GENERATED';
+export function expectedClaudeCodeAgentFiles(workspaceRoot) {
+    return projectCanonicalAgentManifestToClaudeCode().agents.map((agent) => {
+        const path = resolve(workspaceRoot, '.claude', 'agents', agent.fileName);
+        assertInsideWorkspace(workspaceRoot, path);
+        return { ...agent, path };
+    });
+}
+export function renderClaudeCodeAgentMarkdown(agent) {
+    return `---\nname: ${yamlScalar(agent.name)}\ndescription: ${yamlScalar(agent.description)}\n---\n\n<!-- ${claudeCodeGeneratedMarker} claude-code-provider-support provider=claude artifact=claude-code-subagent promptContractVersion=${agent.promptContractVersion} safe-update=true -->\n\n${agent.instructions.trim()}\n`;
+}
+export function inspectClaudeCodeAgents(workspaceRoot) {
+    const directoryPath = join(workspaceRoot, '.claude', 'agents');
+    const expected = expectedClaudeCodeAgentFiles(workspaceRoot);
+    return { directoryPath, directoryExists: existsSync(directoryPath), agents: expected.map(inspectAgent) };
+}
+export function isVgxnessOwnedClaudeAgentMarkdown(contents) {
+    return contents.includes(claudeCodeGeneratedMarker) && contents.includes('provider=claude') && contents.includes('artifact=claude-code-subagent');
+}
+export function parseClaudeAgentFrontmatter(contents) {
+    if (!contents.startsWith('---\n'))
+        return { ok: false, reason: 'Missing YAML frontmatter.' };
+    const end = contents.indexOf('\n---\n', 4);
+    if (end < 0)
+        return { ok: false, reason: 'Unclosed YAML frontmatter.' };
+    const lines = contents.slice(4, end).split('\n');
+    const data = {};
+    for (const line of lines) {
+        const index = line.indexOf(':');
+        if (index <= 0)
+            return { ok: false, reason: `Invalid frontmatter line: ${line}` };
+        const key = line.slice(0, index).trim();
+        const value = line.slice(index + 1).trim();
+        data[key] = unquoteYamlScalar(value);
+    }
+    if (!data.name?.trim())
+        return { ok: false, reason: 'Frontmatter name is required.' };
+    if (!data.description?.trim())
+        return { ok: false, reason: 'Frontmatter description is required.' };
+    return { ok: true, data: { name: data.name, description: data.description } };
+}
+function inspectAgent(agent) {
+    if (!existsSync(agent.path))
+        return { agentName: agent.name, path: agent.path, exists: false, status: 'missing', frontmatter: 'missing', generatedMarker: false, detail: 'Expected Claude agent file is missing.' };
+    try {
+        const contents = readFileSync(agent.path, 'utf8');
+        const frontmatter = parseClaudeAgentFrontmatter(contents);
+        const generatedMarker = isVgxnessOwnedClaudeAgentMarkdown(contents);
+        if (!frontmatter.ok)
+            return { agentName: agent.name, path: agent.path, exists: true, status: 'invalid', frontmatter: 'invalid', generatedMarker, detail: frontmatter.reason };
+        if (frontmatter.data.name !== agent.name)
+            return { agentName: agent.name, path: agent.path, exists: true, status: 'conflicting', frontmatter: 'valid', generatedMarker, detail: `Frontmatter name ${frontmatter.data.name} does not match expected ${agent.name}.` };
+        if (!generatedMarker)
+            return { agentName: agent.name, path: agent.path, exists: true, status: 'conflicting', frontmatter: 'valid', generatedMarker, detail: 'Existing agent file is not marked as VGXNESS-generated.' };
+        return { agentName: agent.name, path: agent.path, exists: true, status: 'managed', frontmatter: 'valid', generatedMarker, detail: 'Claude agent file is VGXNESS-managed.' };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { agentName: agent.name, path: agent.path, exists: true, status: 'invalid', frontmatter: 'invalid', generatedMarker: false, detail: `Unable to read Claude agent file: ${message}` };
+    }
+}
+function yamlScalar(value) {
+    return JSON.stringify(value);
+}
+function unquoteYamlScalar(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        try {
+            return value.startsWith('"') ? JSON.parse(value) : value.slice(1, -1).replaceAll("''", "'");
+        }
+        catch {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}

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

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+export function resolveClaudeCodeMcpJsonPath(workspaceRoot) {
+    const target = resolve(workspaceRoot, '.mcp.json');
+    assertInsideWorkspace(workspaceRoot, target);
+    return target;
+}
+export function createClaudeCodeMcpServerConfig(databasePath, source = 'flag') {
+    return { type: 'stdio', command: 'vgxness', args: source === 'global-default' ? ['mcp', 'start'] : ['mcp', 'start', '--db', databasePath] };
+}
+export function createClaudeCodeMcpDoctorCommand(databasePath, source) {
+    return source === 'global-default' ? ['vgxness', 'mcp', 'doctor'] : ['vgxness', 'mcp', 'doctor', '--db', databasePath];
+}
+export function isManagedClaudeCodeMcpServer(value) {
+    return isRecord(value) && value.type === 'stdio' && value.command === 'vgxness' && isManagedClaudeArgs(value.args);
+}
+export function isManagedClaudeArgs(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string'))
+        return false;
+    const dbPath = value[3];
+    return arraysEqual(value, ['mcp', 'start']) || (value.length === 4 && value[0] === 'mcp' && value[1] === 'start' && value[2] === '--db' && typeof dbPath === 'string' && dbPath.trim().length > 0);
+}
+export function inspectClaudeCodeMcpConfig(workspaceRoot) {
+    const path = resolveClaudeCodeMcpJsonPath(workspaceRoot);
+    if (!existsSync(path))
+        return { status: 'missing', path, exists: false, parsed: false, message: 'Claude project .mcp.json does not exist.' };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!isRecord(parsed))
+            return { status: 'invalid', path, exists: true, parsed: false, message: 'Claude project .mcp.json must be a JSON object.' };
+        if (parsed.mcpServers !== undefined && !isRecord(parsed.mcpServers)) {
+            return { status: 'invalid', path, exists: true, parsed: false, message: 'Claude project .mcp.json mcpServers must be a JSON object.' };
+        }
+        const entry = isRecord(parsed.mcpServers) ? parsed.mcpServers.vgxness : undefined;
+        if (entry === undefined)
+            return { status: 'stale', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json is readable but mcpServers.vgxness is missing.' };
+        if (isManagedClaudeCodeMcpServer(entry))
+            return { status: 'configured', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json has a managed mcpServers.vgxness entry.' };
+        return { status: 'conflicting', path, exists: true, parsed: true, config: parsed, message: 'Claude project .mcp.json has a conflicting mcpServers.vgxness entry.' };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { status: 'invalid', path, exists: true, parsed: false, message: `Claude project .mcp.json could not be read or parsed: ${message}` };
+    }
+}
+export function mergeClaudeCodeMcpConfig(existing, server) {
+    return { ...existing, mcpServers: { ...(isRecord(existing.mcpServers) ? existing.mcpServers : {}), vgxness: server } };
+}
+export function claudeMcpConfigPathStatus(state) {
+    return {
+        label: 'project .mcp.json',
+        path: state.path,
+        exists: state.exists,
+        readable: state.status !== 'invalid',
+        parsed: state.parsed,
+        status: state.status === 'configured' ? 'pass' : state.status === 'invalid' || state.status === 'conflicting' ? 'fail' : 'not-configured',
+        detail: state.message,
+    };
+}
+export function claudeMcpEntryStatus(state) {
+    if (state.status === 'configured')
+        return { configured: true, status: 'pass', serverName: 'vgxness', enabled: true, detail: state.message };
+    if (state.status === 'conflicting')
+        return { configured: true, status: 'fail', serverName: 'vgxness', detail: state.message };
+    if (state.status === 'invalid')
+        return { configured: false, status: 'fail', serverName: 'vgxness', detail: state.message };
+    return { configured: false, status: 'not-configured', serverName: 'vgxness', detail: state.message };
+}
+export function assertInsideWorkspace(workspaceRoot, targetPath) {
+    const root = resolve(workspaceRoot);
+    const target = resolve(targetPath);
+    const rel = relative(root, target);
+    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || rel === '' && target !== root)
+        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')];
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,86 @@
+import { expectedClaudeCodeAgentFiles, inspectClaudeCodeAgents, renderClaudeCodeAgentMarkdown } from './claude-code-agent-config.js';
+import { createClaudeCodeMcpDoctorCommand, createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, resolveClaudeCodeMcpJsonPath } from './claude-code-config.js';
+export function planClaudeCodeMcpInstall(input) {
+    const source = input.databasePathSource ?? 'flag';
+    const server = createClaudeCodeMcpServerConfig(input.databasePath, source);
+    const overwriteVgxness = input.overwriteVgxness === true;
+    let mcpPath;
+    try {
+        mcpPath = resolveClaudeCodeMcpJsonPath(input.cwd);
+    }
+    catch (cause) {
+        return refused(input, server, 'outside_workspace', cause instanceof Error ? cause.message : String(cause), [], [], overwriteVgxness);
+    }
+    const mcpState = inspectClaudeCodeMcpConfig(input.cwd);
+    const targets = [];
+    const preservedTopLevelKeys = mcpState.parsed ? Object.keys(mcpState.config) : [];
+    if (mcpState.status === 'missing')
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'create' });
+    else if (mcpState.status === 'stale')
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'merge' });
+    else if (mcpState.status === 'configured')
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'update-vgxness' });
+    else
+        targets.push({ kind: 'mcp-json', path: mcpPath, action: 'blocked', reason: mcpState.message });
+    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' });
+        else if (agent.status === 'managed')
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'update-vgxness' });
+        else
+            targets.push({ kind: 'agent-file', path: agent.path, agentName: agent.agentName, action: 'blocked', reason: agent.detail });
+    }
+    const blocked = targets.find((target) => target.action === 'blocked');
+    if (blocked !== undefined) {
+        const reason = blocked.kind === 'mcp-json' ? mcpRefusalReason(mcpState.status) : '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'));
+    return {
+        ...base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness),
+        status: 'would_install',
+    };
+}
+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 };
+}
+function base(input, server, targets, preservedTopLevelKeys, backupRequired, overwriteVgxness) {
+    const source = input.databasePathSource ?? 'flag';
+    const targetPath = resolveClaudeCodeMcpJsonPath(input.cwd);
+    return {
+        version: 1,
+        kind: 'mcp-client-install-claude-code',
+        installable: true,
+        mutating: false,
+        provider: 'claude',
+        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.',
+        ],
+        verificationHints: [
+            { kind: 'restart-client', message: 'Restart or reload Claude Code after confirmed project config installation.' },
+            { kind: 'manual-check', message: 'Open the project in Claude Code and verify the vgxness MCP server and project agents are visible.' },
+            { kind: 'command', message: 'Run the MCP doctor command after installation.', command: createClaudeCodeMcpDoctorCommand(input.databasePath, source) },
+        ],
+        server,
+        preservedTopLevelKeys,
+        agentNames: targets.filter((target) => target.kind === 'agent-file').map((target) => target.agentName),
+        overwriteVgxness,
+    };
+}
+function mcpRefusalReason(status) {
+    if (status === 'invalid')
+        return 'malformed_json';
+    if (status === 'conflicting')
+        return 'existing_vgxness_mcp';
+    return 'invalid_mcp_shape';
+}

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

@@ -0,0 +1,85 @@
+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 { createClaudeCodeMcpServerConfig, inspectClaudeCodeMcpConfig, mergeClaudeCodeMcpConfig } from './claude-code-config.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, [], []);
+    if (plan.status === 'refused')
+        return refusal(plan.reason, plan.message, 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));
+    for (const targetPath of preflightPaths) {
+        const preflight = await input.preflight({
+            category: 'provider-tool',
+            operation: 'write claude project provider config',
+            targetPath,
+            workspaceRoot: input.cwd,
+            providerToolName: 'claude-code',
+            ...(input.runId !== undefined ? { runId: input.runId } : {}),
+            ...(input.agentId !== undefined ? { agentId: input.agentId } : {}),
+            ...(input.phase !== undefined ? { phase: input.phase } : {}),
+        });
+        if (!preflight.ok)
+            return refusal('preflight_failed', preflight.error.message, plan, server, [], []);
+    }
+    const backups = [];
+    const writtenPaths = [];
+    const existingTargets = plan.targets.filter((target) => target.action === 'merge' || target.action === 'update-vgxness');
+    for (const target of existingTargets) {
+        const backup = createBackup(target.path);
+        if (!backup.ok)
+            return refusal('backup_failed', backup.error.message, plan, server, writtenPaths, backups);
+        backups.push(toBackupSummary(backup.value));
+    }
+    const mcpWrite = writeMcpJson(input.cwd, plan, server);
+    if (!mcpWrite.ok)
+        return refusal('post_write_validation_failed', mcpWrite.error.message, plan, server, writtenPaths, backups);
+    writtenPaths.push(mcpWrite.value);
+    for (const agent of expectedClaudeCodeRenderedAgents(input.cwd)) {
+        const target = plan.targets.find((item) => item.kind === 'agent-file' && item.path === agent.path);
+        if (target?.action !== 'create' && target?.action !== 'update-vgxness')
+            continue;
+        mkdirSync(dirname(agent.path), { recursive: true });
+        writeFileSync(agent.path, agent.contents);
+        const validation = parseClaudeAgentFrontmatter(readFileSync(agent.path, 'utf8'));
+        if (!validation.ok || validation.data.name !== agent.agentName)
+            return refusal('post_write_validation_failed', `Claude agent ${agent.agentName} failed post-write validation.`, plan, server, writtenPaths, backups);
+        writtenPaths.push(agent.path);
+    }
+    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) {
+    const state = inspectClaudeCodeMcpConfig(cwd);
+    if (state.status === 'invalid' || state.status === 'conflicting')
+        return { ok: false, error: { code: 'validation_failed', message: state.message } };
+    if (plan.targets.find((target) => target.kind === 'mcp-json')?.action === 'create' && existsSync(plan.targetPath))
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude .mcp.json appeared after planning; rerun apply to merge safely.' } };
+    const merged = mergeClaudeCodeMcpConfig(state.parsed ? state.config : {}, server);
+    mkdirSync(dirname(plan.targetPath), { recursive: true });
+    writeFileSync(plan.targetPath, `${JSON.stringify(merged, null, 2)}\n`);
+    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 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 applySafety(plan) {
+    return { ...plan.safety, operation: 'apply', mutating: true, writesProviderConfig: true };
+}
+function toBackupSummary(backup) {
+    return { kind: 'managed', backupId: backup.backupId, backupPath: backup.backupPath, metadataPath: backup.metadataPath, scope: backup.scope, byteSize: backup.byteSize, contentHash: backup.contentHash };
+}
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/mcp/index.js

@@ -2,12 +2,17 @@ export * from '../providers/opencode/manager-payload.js';
 export * from '../verification/index.js';
 export * from './client-install-opencode.js';
 export * from './client-install-opencode-contract.js';
+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-config.js';
 export * from './control-plane.js';
 export * from './doctor.js';
 export * from './opencode-visibility.js';
 export * from './opencode-handoff-preview.js';
 export * from './provider-change-plan.js';
+export * from './provider-canonical-agent-manifest.js';
 export * from './provider-doctor.js';
 export * from './provider-health-types.js';
 export * from './provider-status.js';