vgxness 1.5.1 → 1.6.0

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

@@ -0,0 +1,136 @@
+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 } : {}), ...(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.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',
+            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 = [];
+    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, 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));
+    }
+    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);
+    }
+    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) {
+    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 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, 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 };
+}
+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)];
+}
+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

@@ -2,12 +2,20 @@ 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-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';
 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';

package/dist/mcp/opencode-default-agent-config.js

@@ -1,23 +1,11 @@
-export const vgxnessOpenCodeDefaultAgent = 'vgxness-manager';
-export const vgxnessOpenCodePromptContractVersion = 6;
+import { projectCanonicalAgentManifestToOpenCode, } from '../agents/canonical-agent-projection.js';
+import { canonicalDefaultAgentName, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddTaskPermissions, } from '../agents/canonical-agent-manifest.js';
+export const vgxnessOpenCodeDefaultAgent = canonicalDefaultAgentName;
+export const vgxnessOpenCodePromptContractVersion = canonicalPromptContractVersion;
 export const vgxnessOpenCodeInstructionsPath = 'AGENTS.md';
-export const vgxnessOpenCodeSddSubagents = [
-    'vgxness-sdd-explore',
-    'vgxness-sdd-propose',
-    'vgxness-sdd-spec',
-    'vgxness-sdd-design',
-    'vgxness-sdd-tasks',
-    'vgxness-sdd-apply',
-    'vgxness-sdd-verify',
-    'vgxness-sdd-archive',
-    'vgxness-sdd-init',
-    'vgxness-sdd-onboard',
-];
+export const vgxnessOpenCodeSddSubagents = canonicalSddSubagentNames;
 export function createOpenCodeSddTaskPermissions() {
-    const taskPermissions = { '*': 'deny' };
-    for (const subagent of vgxnessOpenCodeSddSubagents)
-        taskPermissions[subagent] = 'allow';
-    return taskPermissions;
+    return createCanonicalOpenCodeSddTaskPermissions();
 }
 export function createOpenCodeDefaultAgentInstallPlan(input = {}) {
     if (input.mcpOnly === true)
@@ -25,99 +13,5 @@ export function createOpenCodeDefaultAgentInstallPlan(input = {}) {
     return { installsAgents: true, agentNames: [vgxnessOpenCodeDefaultAgent, ...vgxnessOpenCodeSddSubagents], defaultAgent: vgxnessOpenCodeDefaultAgent };
 }
 export function createOpenCodeDefaultAgentConfig() {
-    const agents = {
-        [vgxnessOpenCodeDefaultAgent]: {
-            description: 'VGXNESS SDD Manager - coordinates MCP state and SDD sub-agents, avoids inline execution when delegation is safer',
-            mode: 'primary',
-            model: 'openai/gpt-5.5',
-            options: { reasoningEffort: 'high', vgxnessPromptContractVersion: vgxnessOpenCodePromptContractVersion },
-            permission: { task: createOpenCodeSddTaskPermissions() },
-            prompt: vgxnessManagerPrompt,
-            reasoningEffort: 'high',
-            tools: { bash: true, delegate: true, delegation_list: true, delegation_read: true, edit: true, read: true, write: true },
-            variant: '',
-        },
-    };
-    const descriptions = {
-        'vgxness-sdd-explore': 'Investigate codebase and think through ideas',
-        'vgxness-sdd-propose': 'Create change proposals from explorations',
-        'vgxness-sdd-spec': 'Write detailed specifications from proposals',
-        'vgxness-sdd-design': 'Create technical design from proposals',
-        'vgxness-sdd-tasks': 'Break down specs and designs into implementation tasks',
-        'vgxness-sdd-apply': 'Implement code changes from task definitions',
-        'vgxness-sdd-verify': 'Validate implementation against specs',
-        'vgxness-sdd-archive': 'Archive completed change artifacts',
-        'vgxness-sdd-init': 'Bootstrap SDD context and project configuration',
-        'vgxness-sdd-onboard': 'Guide user through a complete SDD cycle using their real codebase',
-    };
-    for (const name of vgxnessOpenCodeSddSubagents) {
-        agents[name] = {
-            description: descriptions[name],
-            hidden: true,
-            mode: 'subagent',
-            model: 'openai/gpt-5.5',
-            options: { vgxnessPromptContractVersion: vgxnessOpenCodePromptContractVersion },
-            prompt: createSddSubagentPrompt(name),
-            tools: { bash: true, edit: true, read: true, write: true },
-        };
-    }
-    return { defaultAgent: vgxnessOpenCodeDefaultAgent, agents };
+    return projectCanonicalAgentManifestToOpenCode();
 }
-function createSddSubagentPrompt(name) {
-    const phase = name.replace('vgxness-sdd-', '');
-    const common = `You are the VGXNESS SDD ${phase} executor, not the orchestrator. Do this phase's work yourself. Do NOT delegate, do NOT call task/delegate, and do NOT launch sub-agents. Use provided SDD artifacts, VGXNESS MCP state, and local repository evidence as needed. Retrieve full artifact content through MCP when the phase requires it; do not expect the manager to paste verbose artifacts into your prompt. Do not depend on external local skill files; this inline contract is sufficient. Preserve unrelated user work, keep output concise, and report evidence.`;
-    const contracts = {
-        'vgxness-sdd-explore': 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.',
-        'vgxness-sdd-propose': 'Create or refine a focused SDD proposal from exploration evidence. Do not implement code changes. Include scope, tradeoffs, non-goals, and acceptance direction.',
-        'vgxness-sdd-spec': 'Write requirements, acceptance criteria, edge cases, and out-of-scope items. Do not implement code changes.',
-        'vgxness-sdd-design': 'Create technical design grounded in the repository: affected modules, data shapes, safety, rollout, and verification. Do not implement code changes.',
-        'vgxness-sdd-tasks': 'Break approved spec/design into small ordered testable implementation tasks. Do not implement code changes.',
-        'vgxness-sdd-apply': 'Implement only assigned SDD tasks. Preserve unrelated dirty files and user work. Use focused tests when authorized. Report changed files, tests/evidence, and residual risks.',
-        'vgxness-sdd-verify': 'Validate implementation against SDD artifacts and task acceptance criteria. Prefer focused local tests and evidence review. Do not implement unrelated changes.',
-        'vgxness-sdd-archive': 'Archive completed SDD outcome with summary, verification evidence, follow-ups, and residual risks. Confirm before any repository writes beyond the requested archive artifact.',
-        'vgxness-sdd-init': 'Bootstrap SDD context and project setup safely. Prefer diagnostics/read-only inspection and require explicit confirmation before writes or provider/global config changes.',
-        'vgxness-sdd-onboard': 'Guide the user through the SDD cycle with the smallest missing decision at each step. Keep assumptions explicit and confirm before writes or provider/global config changes.',
-    };
-    return `${common}\n\nPhase contract: ${contracts[name]}\n\nSDD governance v1: SDD artifact acceptance is human-only. Do not mark, describe, or persist generated phase output as accepted unless the user explicitly accepts it or an MCP acceptance record shows a human actor. Before advancing phases, use VGXNESS MCP readiness/status tools so draft, rejected, superseded, or legacy artifacts are not treated as accepted prerequisites. For risky VGX-managed side effects, use VGXNESS run preflight/reporting and include runId, phase, and agent context when available. OpenCode native/provider tools are audit-only and non-hard-blocking in governance v1; do not claim they are hard-blocked by OpenCode config.\n\nProvider-native daily progression: daily SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not instruct the user to run terminal SDD phase commands for normal daily flow. Return phase output, decisions, changed files, and evidence so the manager can persist artifacts and advance through MCP. Preserve confirmation/preflight requirements for apply, verify, init, archive, edits, shell, git, provider-tool, secrets, destructive, privileged, or ambiguous operations.`;
-}
-const vgxnessManagerPrompt = `# VGXNESS Manager - compact SDD orchestrator
-
-Bind only to the primary \`vgxness-manager\` agent. Executor agents (for example \`vgxness-sdd-apply\`) use their own prompts.
-
-## Role
-Coordinate SDD; do not become a monolithic executor. Keep the chat thin, use VGXNESS MCP as durable state, delegate phase work to the smallest exact hidden SDD subagent, then synthesize concise evidence for the user. Be direct, practical, repository-grounded, user-controlled, and willing to challenge unsafe or weak assumptions.
-
-Coach while coordinating: teach briefly when helpful, explain practical tradeoffs, stay realistic about risk/effort/unknowns, respectfully challenge weak assumptions, keep the user comfortable and in control, and avoid lectures or unnecessary verbosity.
-
-## Non-negotiable governance
-- SDD artifact acceptance is human-only. Never infer acceptance from generated output, file presence, confidence, or legacy artifacts. Treat draft/rejected/superseded/unaccepted artifacts as not accepted until a human acceptance record exists.
-- Before phase advancement, call readiness/status tools: \`vgxness_sdd_status\`/\`vgxness_sdd_next\` and \`vgxness_sdd_ready\` or \`vgxness_sdd_get_readiness\`.
-- Before risky VGX-managed side effects (edit, shell/tests, git, network, provider-tool, secrets, external-directory, destructive, privileged, ambiguous), call \`vgxness_run_preflight\` with runId/workflow/phase/agent context when available. If approval/block is required, stop; do not invent approval.
-- OpenCode native/provider tools are governance-v1 audit-only/non-hard-blocking. Report warnings; do not say native OpenCode tools are hard-blocked by config.
-- Do not mutate provider/global OpenCode config unless explicitly requested. Do not write to \`openspec/\`. Never revert/overwrite unrelated user work. Preserve \`permission.task\` deny-by-default with only exact known SDD subagents allowed.
-- Do not publish packages unless explicitly requested.
-- Do not change model or reasoning effort.
-
-## Provider-native daily flow
-Normal SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not tell users to run terminal SDD phase commands for daily flow. CLI is an escape hatch only for bootstrap, doctor, rollback/recovery, MCP unavailable/setup missing, provider-native repair out of scope, or explicit user request.
-
-## MCP playbook
-- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\` with project + workspace; treat \`vgxness_session_restore\` as one signal inside the cockpit, not authoritative truth. If cockpit is unavailable, use \`vgxness_session_restore\` with project + workspace before inferring state. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one, say so and include summary in final response.
-- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; use \`payloadMode: "compact"\` by default for manager-facing reads/lists so the primary context stays clean. Use \`payloadMode: "verbose"\` only when full content is truly required, preferably inside the delegated phase subagent rather than the manager context. Save phase output with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
-- Acceptance/readiness: confirm explicit human acceptance, use \`vgxness_sdd_accept_artifact\` only for explicit human acceptance, then \`vgxness_sdd_get_readiness\`/readiness tools before reporting state. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, and audit warnings before risky/ambiguous transitions and in apply/verify summaries.
-- Memory: call \`vgxness_memory_search\`/\`vgxness_memory_get\` when prior work or unclear project context is referenced; call \`vgxness_memory_save\` for durable discoveries, decisions, bug fixes, config, patterns, or preferences; use \`vgxness_memory_update\` only to correct/evolve a known id. Do not duplicate full SDD artifacts as memory.
-- Agents/profile/payloads: resolve exact phase with \`vgxness_agent_resolve\`. \`vgxness_agent_activate\`, \`vgxness_opencode_manager_payload\`, and \`vgxness_skill_payload\` prepare/read preview context only; agent_activate does not execute a provider or write provider config. Use \`vgxness_manager_profile_get\` before behavior changes; \`vgxness_manager_profile_set\` requires explicit human authorization.
-- Runs: use \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\` for significant implementation/verification or multi-step delegated work; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\`, and close with \`vgxness_run_finalize\`.
-- Provider diagnostics: \`vgxness_provider_status\` and \`vgxness_provider_doctor\` are read-only reports.
-
-## Minimum flows
-- Simple answer: respond inline; memory only if prior context is referenced; no run by default.
-- Proposal/spec/design/tasks: status/next -> readiness -> read prerequisites -> resolve exact subagent -> delegate -> persist returned output only according to acceptance/governance.
-- Apply/verify: require tasks/apply-progress as appropriate -> read artifacts -> resolve exact subagent -> recover/start run -> preflight writes/shell/git/tests -> delegate -> checkpoint -> save apply-progress/verify -> finalize when clear.
-- Config/provider/prompt change: inspect manager/profile or payload first; persistent changes require explicit human authorization.
-
-## Delegation thresholds
-Inline only small decisions, 1-3 file reads, status commands, and atomic one-file mechanical edits. Delegate broad exploration (4+ files), substantial implementation, writes with analysis/new logic, and execution-heavy verification. Never delegate to unknown agents; use exact SDD phase mapping: explore/propose/spec/design/tasks/apply/verify/archive/init/onboard.
-
-## Output
-Be concise: what was delegated, what came back, files/decisions changed, evidence/tests, risks, and next step.`;

package/dist/mcp/provider-canonical-agent-manifest.js

@@ -0,0 +1,39 @@
+import { canonicalAgentManifest } from '../agents/canonical-agent-manifest.js';
+import { canonicalManifestValidationErrors, canonicalProviderProjection } from '../agents/canonical-agent-projection.js';
+const diagnosticProviders = ['opencode', 'claude'];
+export function buildCanonicalAgentManifestDiagnostic(manifest = canonicalAgentManifest) {
+    const validationErrors = canonicalManifestValidationErrors(manifest);
+    const managerCount = manifest.agents.filter((agent) => agent.mode === 'agent').length;
+    const subagentCount = manifest.agents.filter((agent) => agent.mode === 'subagent').length;
+    return {
+        status: validationErrors.length === 0 ? 'pass' : 'fail',
+        version: manifest.version,
+        project: manifest.project,
+        scope: manifest.scope,
+        defaultAgentName: manifest.defaultAgentName,
+        promptContractVersion: manifest.promptContractVersion,
+        agentCount: manifest.agents.length,
+        managerCount,
+        subagentCount,
+        validationErrors,
+        providerSupport: diagnosticProviders.map((provider) => providerSupportFor(provider, manifest)),
+    };
+}
+function providerSupportFor(provider, manifest) {
+    try {
+        const projection = canonicalProviderProjection(provider, manifest);
+        return {
+            provider: projection.provider,
+            level: projection.level,
+            ...(projection.reason === undefined ? {} : { reason: projection.reason }),
+        };
+    }
+    catch {
+        const fallback = manifest.agents.find((agent) => agent.providerSupport[provider] !== undefined)?.providerSupport[provider];
+        return {
+            provider,
+            level: fallback?.level ?? 'unsupported',
+            ...(fallback?.reason === undefined ? {} : { reason: fallback.reason }),
+        };
+    }
+}

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

@@ -1,7 +1,11 @@
 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 = {
@@ -22,8 +26,10 @@ export class ProviderChangePlanService {
     }
     getPlan(input) {
         const normalized = normalizeInput(input);
-        if (normalized.provider !== 'opencode')
+        if (normalized.provider !== 'opencode' && normalized.provider !== 'claude')
             return { ok: true, value: unsupportedProviderEnvelope(normalized) };
+        if (normalized.provider === 'claude')
+            return this.getClaudePlan(normalized);
         const status = (this.deps.providerStatus ?? new ProviderStatusService()).getStatus({
             project: normalized.project,
             scope: normalized.scope,
@@ -65,6 +71,60 @@ export class ProviderChangePlanService {
             value: opencodeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source),
         };
     }
+    getClaudePlan(normalized) {
+        const status = (this.deps.providerStatus ?? new ProviderStatusService()).getStatus({ project: normalized.project, scope: normalized.scope, providerAdapter: 'claude', workspaceRoot: normalized.workspaceRoot, env: this.deps.env ?? process.env, payloadMode: normalized.payloadMode });
+        if (!status.ok)
+            return status;
+        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) };
+        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source });
+        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 {
@@ -156,6 +216,28 @@ function opencodeEnvelope(input, status, doctor, installPlan, source) {
         }
         : envelope;
 }
+function claudeEnvelope(input, status, doctor, installPlan, source) {
+    const backupRequired = installPlan.status === 'would_install' ? installPlan.backupRequired : false;
+    const warnings = [...statusWarnings(status), ...doctor.recommendations, ...installPlan.warnings];
+    const envelope = {
+        ...baseEnvelope(input),
+        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, ${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,
+        doctorSummary: doctorSummary(doctor),
+        doctorFindings: doctor.checks,
+        previewEffects: previewEffectsClaude(installPlan),
+        backupRollback: descriptiveBackupPolicy(backupRequired),
+        confirmations: confirmationPolicy(),
+        risks: risksForClaude(status, doctor, installPlan, source),
+        warnings,
+    };
+    return input.payloadMode === 'verbose' ? { ...envelope, rawSources: { status, doctor, claudeCodeMcpInstallPlan: installPlan } } : envelope;
+}
 function baseEnvelope(input) {
     return {
         version: 1,
@@ -223,6 +305,20 @@ function previewEffects(plan) {
         ...(plan.defaultAgent === undefined ? {} : { defaultAgent: plan.defaultAgent }),
     };
 }
+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, ...(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', ...(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 {
         policy: 'descriptive-only',
@@ -255,6 +351,18 @@ function risksForOpenCode(status, doctor, plan, source) {
         risks.push('Future MCP server command would rely on the global default VGXNESS database path.');
     return risks;
 }
+function risksForClaude(status, doctor, plan, source) {
+    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')
+        risks.push(`Provider doctor is ${doctor.status}; future writes should review doctor findings first.`);
+    if (plan.status === 'refused')
+        risks.push(`Future install planner refused the operation: ${plan.reason}.`);
+    if (source === 'global-default')
+        risks.push('Future MCP server command would rely on the global default VGXNESS database path.');
+    return risks;
+}
 function summaryForOpenCode(input, plan) {
     if (plan.status === 'refused')
         return `Read-only OpenCode ${input.changeType} planning completed; future install is currently refused: ${plan.message}`;