vgxness 1.5.2 → 1.7.0

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

@@ -2,24 +2,30 @@ 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 { expectedClaudeCodeRenderedAgents, planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
+import { inspectClaudeProjectMemory, mergeClaudeProjectMemory } from './claude-code-project-memory.js';
+import { expectedClaudeCodeRenderedAgents, expectedClaudeCodeRenderedUserAgents, planClaudeCodeMcpInstall } from './client-install-claude-code-contract.js';
+import { inspectClaudeCodeUserMcpConfig, mergeClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory, mergeClaudeUserMemory } from './claude-code-user-memory.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 } : {}), ...(input.env !== undefined ? { env: input.env } : {}) });
     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',
-            operation: 'write claude project provider config',
+            operation: plan.canonicalClaudeScope === 'user' ? 'write claude user provider config' : 'write claude project provider config',
             targetPath,
             workspaceRoot: input.cwd,
             providerToolName: 'claude-code',
@@ -32,9 +38,22 @@ 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 === 'local') {
+        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 };
+    }
+    if (plan.canonicalClaudeScope === 'user')
+        return applyUserInstall(input, plan, server, writtenPaths, backups);
+    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 +73,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 +92,101 @@ 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 writeUserMcpJson(env, plan, server) {
+    const target = plan.targets.find((item) => item.kind === 'user-mcp-json');
+    if (target === undefined)
+        return { ok: true, value: plan.targetPath };
+    if (target.action === 'blocked')
+        return { ok: false, error: { code: 'validation_failed', message: target.reason ?? 'Claude user config is blocked.' } };
+    const state = inspectClaudeCodeUserMcpConfig(env);
+    if (state.status === 'invalid' || state.status === 'conflicting')
+        return { ok: false, error: { code: 'validation_failed', message: state.message } };
+    if (target.action === 'create' && existsSync(target.path))
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude user ~/.claude.json appeared after planning; rerun apply to merge safely.' } };
+    if (state.path !== target.path)
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude user config path changed after planning; rerun apply.' } };
+    const merged = mergeClaudeCodeUserMcpConfig(state.parsed ? state.config : {}, server);
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeFileSync(target.path, `${JSON.stringify(merged, null, 2)}\n`);
+    const after = inspectClaudeCodeUserMcpConfig(env);
+    return after.status === 'configured' ? { ok: true, value: target.path } : { ok: false, error: { code: 'validation_failed', message: 'Claude user ~/.claude.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.' } };
+}
+async function applyUserInstall(input, plan, server, writtenPaths, backups) {
+    const existingTargets = plan.targets.filter((target) => target.kind !== 'cli-mcp-registration' && (target.action === 'merge' || target.action === 'update-vgxness' || target.action === 'append-managed-block' || target.action === 'update-managed-block'));
+    for (const target of existingTargets) {
+        const backup = createBackup(target.path, target.kind === 'user-memory' ? 'user-memory' : 'config', 'user');
+        if (!backup.ok)
+            return refusal('backup_failed', backup.error.message, plan, server, writtenPaths, backups);
+        backups.push(toBackupSummary(backup.value));
+    }
+    const mcpWrite = writeUserMcpJson(input.env, 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 expectedClaudeCodeRenderedUserAgents(input.cwd, input.env)) {
+        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 user agent ${agent.agentName} failed post-write validation.`, plan, server, writtenPaths, backups);
+        writtenPaths.push(agent.path);
+    }
+    const memoryWrite = writeUserMemory(input.env, plan);
+    if (!memoryWrite.ok)
+        return refusal('post_write_validation_failed', memoryWrite.error.message, plan, server, writtenPaths, backups);
+    if (memoryWrite.value !== undefined)
+        writtenPaths.push(memoryWrite.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 writeUserMemory(env, plan) {
+    const target = plan.targets.find((item) => item.kind === 'user-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 user memory is blocked.' } };
+    const state = inspectClaudeUserMemory(env);
+    if (state.path !== target.path || state.action !== target.action)
+        return { ok: false, error: { code: 'validation_failed', message: 'Claude user memory changed after planning; rerun apply.' } };
+    const merged = mergeClaudeUserMemory(state);
+    if (!merged.ok)
+        return merged;
+    mkdirSync(dirname(target.path), { recursive: true });
+    writeFileSync(target.path, merged.value.contents);
+    const after = inspectClaudeUserMemory(env);
+    return after.status === 'managed-current' ? { ok: true, value: target.path } : { ok: false, error: { code: 'validation_failed', message: 'Claude user memory did not validate as managed-current after write.' } };
+}
+function createBackup(path, kind, scope = 'project') {
+    return createManagedProviderConfigBackup({
+        targetPath: path,
+        provider: 'claude',
+        scope,
+        createdByOperation: 'mcp-client-install-claude-code',
+        reason: kind === 'project-memory' ? 'pre-project-memory-update-safety' : kind === 'user-memory' ? 'pre-user-memory-update-safety' : 'pre-merge-safety',
+        description: kind === 'project-memory' ? 'Backup existing Claude Code project memory before appending or updating the VGXNESS managed block.' : kind === 'user-memory' ? 'Backup existing Claude Code user memory before appending or updating the VGXNESS managed block.' : 'Backup existing Claude Code 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 +197,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/control-plane.js

@@ -29,7 +29,7 @@ export function callVgxTool(call, services) {
         case 'vgxness_sdd_get_readiness':
             return auditedEnvelope(validated.tool, services.sdd.getReady(validated.input), services, sddReadinessAuditPayload(validated.input));
         case 'vgxness_sdd_save_artifact':
-            return toEnvelope(validated.tool, services.sdd.saveArtifact(validated.input));
+            return auditedEnvelope(validated.tool, services.sdd.saveArtifact(validated.input), services, sddSaveAuditPayload(validated.input));
         case 'vgxness_sdd_accept_artifact':
             return auditedEnvelope(validated.tool, services.sdd.acceptArtifact(toAcceptArtifactServiceInput(validated.input)), services, sddAcceptanceAuditPayload(validated.input));
         case 'vgxness_sdd_get_artifact':
@@ -170,6 +170,23 @@ function sddAcceptanceAuditPayload(input) {
         }),
     };
 }
+function sddSaveAuditPayload(input) {
+    return {
+        runId: input.runId,
+        title: 'Audit: sdd-artifact-saved',
+        relatedType: 'sdd-artifact',
+        relatedId: `${input.change}:${input.phase}`,
+        payload: (value) => ({
+            eventType: 'sdd-artifact-saved',
+            project: input.project,
+            change: input.change,
+            phase: input.phase,
+            topicKey: value.topicKey,
+            artifactId: value.id,
+            ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
+        }),
+    };
+}
 function governanceReportAuditPayload(input) {
     return {
         runId: input.runId,

package/dist/mcp/index.js

@@ -6,7 +6,12 @@ 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 './claude-code-user-config.js';
+export * from './claude-code-user-memory.js';
 export * from './control-plane.js';
 export * from './doctor.js';
 export * from './opencode-visibility.js';

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

@@ -3,6 +3,7 @@ import { planClaudeCodeMcpInstall } from './client-install-claude-code-contract.
 import { planOpenCodeMcpInstall } from './client-install-opencode-contract.js';
 import { ProviderDoctorService } from './provider-doctor.js';
 import { ProviderStatusService } from './provider-status.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,10 +76,13 @@ 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;
         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 });
+        const installPlan = planClaudeCodeMcpInstall({ cwd: normalized.workspaceRoot, databasePath: databasePath.value.path, databasePathSource: databasePath.value.source, scope: normalized.scope, env: this.deps.env ?? process.env });
         return { ok: true, value: claudeEnvelope(normalized, status.value, doctor.value, installPlan, databasePath.value.source) };
     }
 }
@@ -180,7 +184,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 ${installPlan.canonicalClaudeScope === 'user' ? '~/.claude.json, user agents, and ~/.claude/CLAUDE.md' : 'project .mcp.json, agent files, and project-root CLAUDE.md'} as needed.`,
         providerIdentity: { provider: 'claude', adapter: 'claude', support: 'supported' },
         statusSummary: statusSummary(status),
         statusFindings: status.config,
@@ -262,10 +266,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 };
-    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: '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' || target.kind === 'user-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' || item.kind === 'user-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 +312,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 = [plan.canonicalClaudeScope === 'user' ? 'Claude user/global files affect this OS user; backups are required before merging existing files.' : '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')

package/dist/mcp/provider-doctor.js

@@ -1,9 +1,13 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
 import { claudeAdvisoryPaths, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
+import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { inspectClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
+import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
 import { inspectOpenCodeConfigPaths } from './provider-status.js';
 export class ProviderDoctorService {
     deps;
@@ -83,24 +87,42 @@ export class ProviderDoctorService {
         };
     }
     getClaudeDoctor(normalized) {
+        const resolvedScope = resolveClaudeCodeScope(normalized.scope);
+        if (!resolvedScope.ok)
+            return resolvedScope;
+        if (isUserGlobalScope(normalized.scope) || resolvedScope.value.canonical === 'local')
+            return this.getClaudeUserGlobalDoctor(normalized, resolvedScope.value.canonical, resolvedScope.value.warnings);
         const mcp = inspectClaudeCodeMcpConfig(normalized.workspaceRoot);
         const agents = inspectClaudeCodeAgents(normalized.workspaceRoot);
+        const projectMemory = inspectClaudeProjectMemory(normalized.workspaceRoot);
         const advisoryPaths = claudeAdvisoryPaths(normalized.workspaceRoot);
-        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), ...advisoryPaths];
+        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), projectMemory.path, ...advisoryPaths];
         const before = snapshotPaths(checkedPathList, normalized.workspaceRoot);
         const missingAgents = agents.agents.filter((agent) => agent.status === 'missing');
-        const badFrontmatter = agents.agents.filter((agent) => agent.frontmatter === 'invalid' || agent.frontmatter === 'missing');
+        const blockingAgents = agents.agents.filter((agent) => agent.status === 'conflicting' || agent.status === 'invalid');
+        const badFrontmatter = agents.agents.filter((agent) => agent.exists && agent.frontmatter === 'invalid');
         const badMarkers = agents.agents.filter((agent) => agent.exists && !agent.generatedMarker);
         const memoryFiles = advisoryPaths.filter((path) => existsSync(path));
         const checks = [
             { id: 'workspace-root', status: existsSync(normalized.workspaceRoot) ? 'pass' : 'fail', detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}` },
-            { id: 'provider-supported', status: 'pass', detail: 'Claude provider adapter selected for project-local .mcp.json and .claude/agents support.' },
+            { id: 'provider-supported', status: 'pass', detail: 'Claude provider adapter selected for CLI MCP registration diagnostics, project .mcp.json compatibility, and Claude agents support.' },
+            { id: 'claude-scope', status: 'pass', detail: 'Claude scope project resolved to canonical project.' },
+            { id: 'claude-cli-presence', status: 'warn', detail: 'Read-only doctor does not execute `claude --version`; CLI availability is diagnosed during explicit apply/preflight only.' },
             { id: 'claude-project-mcp-readable', status: mcp.status === 'invalid' ? 'fail' : mcp.status === 'missing' ? 'not-configured' : 'pass', detail: mcp.message, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed .mcp.json before installing VGXNESS Claude support.' } : {}) },
             { id: 'claude-vgxness-mcp-entry', status: mcp.status === 'configured' ? 'pass' : mcp.status === 'conflicting' ? 'fail' : 'not-configured', detail: mcp.message, ...(mcp.status === 'conflicting' ? { remediation: 'Manually reconcile mcpServers.vgxness before applying VGXNESS Claude support.' } : {}) },
             { id: 'claude-agents-directory', status: agents.directoryExists ? 'pass' : 'not-configured', detail: agents.directoryExists ? 'Claude project agents directory exists.' : 'Claude project agents directory is missing; confirmed apply may create it.' },
-            { id: 'claude-vgxness-agents', status: missingAgents.length === 0 && agents.agents.every((agent) => agent.status !== 'conflicting' && agent.status !== 'invalid') ? 'pass' : missingAgents.length > 0 ? 'not-configured' : 'fail', detail: missingAgents.length > 0 ? `Missing VGXNESS Claude agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.` : 'Expected VGXNESS Claude agent targets were inspected.' },
+            {
+                id: 'claude-vgxness-agents',
+                status: blockingAgents.length > 0 ? 'fail' : missingAgents.length > 0 ? 'not-configured' : 'pass',
+                detail: blockingAgents.length > 0
+                    ? `Conflicting or invalid VGXNESS Claude agents: ${blockingAgents.map((agent) => agent.agentName).join(', ')}.`
+                    : missingAgents.length > 0
+                        ? `Missing VGXNESS Claude agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.`
+                        : 'Expected VGXNESS Claude agent targets were inspected.',
+            },
             { id: 'claude-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'fail', detail: badFrontmatter.length === 0 ? 'Expected Claude agent frontmatter is valid.' : `Invalid or missing frontmatter for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
             { id: 'claude-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'fail', detail: badMarkers.length === 0 ? 'Existing VGXNESS Claude agent files include generated metadata markers.' : `Missing VGXNESS generated marker for: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
+            claudeProjectMemoryCheck(projectMemory),
             { id: 'claude-project-memory-advisory', status: memoryFiles.length === 0 ? 'pass' : 'warn', detail: memoryFiles.length === 0 ? 'No Claude project memory/settings advisory files were found.' : `Advisory only; VGXNESS will not modify: ${memoryFiles.join(', ')}.` },
             readonlySafetyCheck(before, snapshotPaths(checkedPathList, normalized.workspaceRoot)),
         ];
@@ -111,6 +133,37 @@ export class ProviderDoctorService {
         const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
         return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: PROVIDER_HEALTH_SAFETY } };
     }
+    getClaudeUserGlobalDoctor(normalized, canonicalScope = 'user', scopeWarnings = []) {
+        const mcp = inspectClaudeCodeUserMcpConfig(normalized.env);
+        const agents = inspectClaudeCodeAgents({ workspaceRoot: normalized.workspaceRoot, scope: 'user', env: normalized.env });
+        const userMemory = inspectClaudeUserMemory(normalized.env);
+        const checkedPathList = [mcp.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), userMemory.path];
+        const before = snapshotPaths(checkedPathList, normalized.workspaceRoot);
+        const missingAgents = agents.agents.filter((agent) => agent.status === 'missing');
+        const blockingAgents = agents.agents.filter((agent) => agent.status === 'conflicting' || agent.status === 'invalid');
+        const badFrontmatter = agents.agents.filter((agent) => agent.exists && agent.frontmatter === 'invalid');
+        const badMarkers = agents.agents.filter((agent) => agent.exists && !agent.generatedMarker);
+        const checks = [
+            { id: 'workspace-root', status: existsSync(normalized.workspaceRoot) ? 'pass' : 'fail', detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}` },
+            { id: 'provider-supported', status: 'pass', detail: `Claude ${canonicalScope} scope supports guarded ~/.claude.json MCP merge, user agents, and ~/.claude/CLAUDE.md managed block after confirmation/preflight.` },
+            { id: 'claude-scope', status: scopeWarnings.length === 0 ? 'pass' : 'warn', detail: scopeWarnings.join(' ') || `Claude scope resolved to canonical ${canonicalScope}.` },
+            { id: 'claude-cli-presence', status: 'warn', detail: 'Read-only doctor does not execute `claude --version`; no provider process was launched.' },
+            { id: 'claude-user-mcp-readable', status: mcp.status === 'invalid' ? 'fail' : mcp.status === 'missing' ? 'not-configured' : 'pass', detail: mcp.message, ...(mcp.status === 'invalid' ? { remediation: 'Fix malformed ~/.claude.json before installing VGXNESS Claude user support.' } : {}) },
+            { id: 'claude-user-vgxness-mcp-entry', status: mcp.status === 'configured' ? 'pass' : mcp.status === 'conflicting' ? 'fail' : 'not-configured', detail: mcp.message, ...(mcp.status === 'conflicting' ? { remediation: 'Manually reconcile mcpServers.vgxness in ~/.claude.json before applying VGXNESS Claude user support.' } : {}) },
+            { id: 'claude-user-agents-directory', status: agents.directoryExists ? 'pass' : 'not-configured', detail: agents.directoryExists ? 'Claude user agents directory exists.' : 'Claude user agents directory is missing; confirmed apply may create it.' },
+            { id: 'claude-user-vgxness-agents', status: blockingAgents.length > 0 ? 'fail' : missingAgents.length > 0 ? 'not-configured' : 'pass', detail: blockingAgents.length > 0 ? `Conflicting or invalid VGXNESS Claude user agents: ${blockingAgents.map((agent) => agent.agentName).join(', ')}.` : missingAgents.length > 0 ? `Missing VGXNESS Claude user agents: ${missingAgents.map((agent) => agent.agentName).join(', ')}.` : 'Expected VGXNESS Claude user agent targets were inspected.' },
+            { id: 'claude-user-agent-frontmatter', status: badFrontmatter.length === 0 ? 'pass' : 'fail', detail: badFrontmatter.length === 0 ? 'Expected Claude user agent frontmatter is valid.' : `Invalid or missing frontmatter for: ${badFrontmatter.map((agent) => agent.agentName).join(', ')}.` },
+            { id: 'claude-user-agent-generated-metadata', status: badMarkers.length === 0 ? 'pass' : 'fail', detail: badMarkers.length === 0 ? 'Existing VGXNESS Claude user agent files include generated metadata markers.' : `Missing VGXNESS generated marker for: ${badMarkers.map((agent) => agent.agentName).join(', ')}.` },
+            { ...claudeProjectMemoryCheck(userMemory), id: 'claude-user-memory-managed-block' },
+            readonlySafetyCheck(before, snapshotPaths(checkedPathList, normalized.workspaceRoot)),
+        ];
+        const status = rollupProviderDoctor(checks.map((check) => check.status));
+        const compactChecksValue = compactChecks(checks, normalized.payloadMode);
+        const failedChecks = checks.filter((check) => check.status === 'fail').map((check) => check.id);
+        const recommendations = checks.flatMap((check) => (check.remediation === undefined ? [] : [check.remediation]));
+        const checkedPaths = normalized.payloadMode === 'verbose' ? checkedPathList : checkedPathList.filter((path) => existsSync(path) || path === mcp.path || path === userMemory.path);
+        return { ok: true, value: { version: 1, kind: 'provider-doctor', project: normalized.project, providerAdapter: 'claude', scope: normalized.scope, workspaceRoot: normalized.workspaceRoot, status, payloadMode: normalized.payloadMode, overallStatus: status, checkCount: checks.length, passedCount: checks.filter((check) => check.status === 'pass').length, warningCount: checks.filter((check) => check.status === 'warn' || check.status === 'not-configured').length, errorCount: failedChecks.length, skippedCount: checks.filter((check) => check.status === 'skip').length, failedChecks, summary: summarizeDoctor(status, failedChecks.length, recommendations.length), recommendations, checks: compactChecksValue, checkedPaths, bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: checkedPathList }), 'utf8'), compactBytes: Buffer.byteLength(JSON.stringify({ checks: compactChecksValue, checkedPaths }), 'utf8') }, verboseAvailable: normalized.payloadMode === 'compact', fullContentRef: `provider-doctor:claude:${canonicalScope}:${normalized.workspaceRoot}`, generatedAt: 'read-only-snapshot', safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES } } };
+    }
 }
 function summarizeDoctor(status, failedCount, recommendationCount) {
     if (status === 'healthy')
@@ -223,6 +276,19 @@ function readonlySafetyCheck(before, after) {
         }
         : { id: 'provider-config-readonly-safety', status: 'fail', detail: 'Provider config path existence or mtimes changed during read-only doctor.' };
 }
+function claudeProjectMemoryCheck(state) {
+    const status = state.status === 'managed-current' ? 'pass' : state.status === 'managed-stale' ? 'warn' : state.status === 'blocked' ? 'fail' : 'not-configured';
+    return {
+        id: 'claude-project-memory-managed-block',
+        status,
+        detail: state.message,
+        ...(state.status === 'blocked'
+            ? { remediation: 'Manually reconcile VGXNESS Claude project-memory markers before installing.' }
+            : state.status === 'managed-current'
+                ? {}
+                : { remediation: 'Run confirmed Claude project install when ready.' }),
+    };
+}
 function snapshotPaths(paths, workspaceRoot) {
     const unique = [...paths, `${workspaceRoot}/.vgx`];
     return Object.fromEntries(unique.map((path) => [path, existsSync(path) ? statSync(path).mtimeMs : false]));

package/dist/mcp/provider-health-types.js

@@ -11,6 +11,10 @@ export const PROVIDER_HEALTH_SAFETY = {
     runsRepair: false,
     executesProvider: false,
 };
+export const CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES = ['status', 'doctor', 'change-plan'];
+export function isUserGlobalScope(scope) {
+    return scope === 'personal' || scope === 'user';
+}
 export const REQUIRED_PROVIDER_MCP_TOOLS = ['vgxness_provider_status', 'vgxness_provider_doctor', 'vgxness_provider_change_plan'];
 export const REQUIRED_PROVIDER_NATIVE_MCP_TOOLS = [
     'vgxness_provider_status',

package/dist/mcp/provider-status.js

@@ -2,10 +2,14 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
 import { claudeAdvisoryPaths, claudeMcpConfigPathStatus, claudeMcpEntryStatus, inspectClaudeCodeMcpConfig } from './claude-code-config.js';
+import { inspectClaudeProjectMemory } from './claude-code-project-memory.js';
+import { resolveClaudeCodeScope } from './claude-code-scope.js';
+import { claudeUserMcpConfigPathStatus, claudeUserMcpEntryStatus, inspectClaudeCodeUserMcpConfig } from './claude-code-user-config.js';
+import { inspectClaudeUserMemory } from './claude-code-user-memory.js';
 import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodePromptContractVersion, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
 import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.js';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
+import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, providerHealthFailure, isUserGlobalScope, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
 const projectConfigTargets = ['.opencode/opencode.json', 'opencode.json', '.opencode/opencode.jsonc', 'opencode.jsonc'];
 export class ProviderStatusService {
     deps;
@@ -87,24 +91,30 @@ export class ProviderStatusService {
         return { change, ...(status.ok ? { status: status.value } : {}), ...(next.ok ? { next: next.value } : {}) };
     }
     getClaudeStatus(normalized) {
+        const resolvedScope = resolveClaudeCodeScope(normalized.scope);
+        if (!resolvedScope.ok)
+            return resolvedScope;
+        if (isUserGlobalScope(normalized.scope) || resolvedScope.value.canonical === 'local')
+            return this.getClaudeUserGlobalStatus(normalized, resolvedScope.value.canonical, resolvedScope.value.warnings);
         const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
         const mcpState = inspectClaudeCodeMcpConfig(normalized.workspaceRoot);
         const agents = inspectClaudeCodeAgents(normalized.workspaceRoot);
-        const paths = [claudeMcpConfigPathStatus(mcpState)];
+        const projectMemory = inspectClaudeProjectMemory(normalized.workspaceRoot);
+        const paths = [claudeMcpConfigPathStatus(mcpState), claudeProjectMemoryPathStatus(projectMemory)];
         const mcpEntry = claudeMcpEntryStatus(mcpState);
         const agentStatuses = agents.agents.map((agent) => (agent.status === 'managed' ? 'pass' : agent.status === 'missing' ? 'not-configured' : 'fail'));
         const advisory = claudeAdvisoryPaths(normalized.workspaceRoot).filter((path) => existsSync(path));
-        const configStatus = claudeConfigHealthStatus([paths[0]?.status ?? 'not-configured', ...agentStatuses]);
+        const configStatus = claudeConfigHealthStatus([...paths.map((path) => path.status), ...agentStatuses]);
         const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus]);
         const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
-        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), ...claudeAdvisoryPaths(normalized.workspaceRoot)] : [mcpState.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path), ...advisory];
-        const tools = requiredToolPresence();
-        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, advisory, sdd, mcpRequiredTools: tools };
-        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), advisory, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
+        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), projectMemory.path, ...claudeAdvisoryPaths(normalized.workspaceRoot)] : [mcpState.path, projectMemory.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path), ...advisory];
+        const tools = [...requiredToolPresence(), { tool: 'claude-cli', present: false, diagnostic: 'Read-only status does not execute `claude --version`; CLI presence is checked during explicit apply/preflight only.' }];
+        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, projectMemory, advisory, sdd, mcpRequiredTools: tools };
+        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), projectMemory: { status: projectMemory.status, action: projectMemory.action }, advisory, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
         const originalBytes = Buffer.byteLength(JSON.stringify(verboseShape), 'utf8');
         const compactBytes = Buffer.byteLength(JSON.stringify(compactShape), 'utf8');
         const issueCount = [canonicalAgentManifest.status, configStatus, ...agentStatuses].filter((item) => item === 'fail' || item === 'not-configured').length;
-        const warningCount = advisory.length;
+        const warningCount = advisory.length + resolvedScope.value.warnings.length + paths.filter((path) => path.status === 'warn').length;
         return {
             ok: true,
             value: {
@@ -136,6 +146,53 @@ export class ProviderStatusService {
             },
         };
     }
+    getClaudeUserGlobalStatus(normalized, canonicalScope = 'user', scopeWarnings = []) {
+        const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
+        const mcpState = inspectClaudeCodeUserMcpConfig(normalized.env);
+        const agents = inspectClaudeCodeAgents({ workspaceRoot: normalized.workspaceRoot, scope: 'user', env: normalized.env });
+        const userMemory = inspectClaudeUserMemory(normalized.env);
+        const userMemoryPathStatus = { ...claudeProjectMemoryPathStatus(userMemory), label: 'user ~/.claude/CLAUDE.md managed block' };
+        const paths = [claudeUserMcpConfigPathStatus(mcpState), userMemoryPathStatus];
+        const mcpEntry = claudeUserMcpEntryStatus(mcpState);
+        const agentStatuses = agents.agents.map((agent) => (agent.status === 'managed' ? 'pass' : agent.status === 'missing' ? 'not-configured' : 'fail'));
+        const configStatus = claudeConfigHealthStatus([...paths.map((path) => path.status), ...agentStatuses]);
+        const tools = [...requiredToolPresence(), { tool: 'claude-cli', present: false, diagnostic: 'Read-only status does not execute `claude --version`; no Claude Code process was launched.' }];
+        const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus]);
+        const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
+        const checkedPaths = normalized.payloadMode === 'verbose' ? [mcpState.path, agents.directoryPath, ...agents.agents.map((agent) => agent.path), userMemory.path] : [mcpState.path, userMemory.path, ...agents.agents.filter((agent) => agent.exists || agent.status !== 'missing').map((agent) => agent.path)];
+        const verboseShape = { config: { status: configStatus, paths, mcpEntry }, canonicalAgentManifest, agents, userMemory: { status: userMemory.status, action: userMemory.action }, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, scopeWarnings, sdd, mcpRequiredTools: tools };
+        const compactShape = { config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, agentSummary: summarizeClaudeAgents(agents), userMemory: { status: userMemory.status, action: userMemory.action }, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, sdd: sdd === undefined ? undefined : compactSdd(sdd, 'compact'), mcpRequiredTools: tools };
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'provider-status',
+                project: normalized.project,
+                providerAdapter: 'claude',
+                scope: normalized.scope,
+                workspaceRoot: normalized.workspaceRoot,
+                status,
+                payloadMode: normalized.payloadMode,
+                overallStatus: status,
+                inspectedPaths: checkedPaths,
+                issueCount: [canonicalAgentManifest.status, configStatus, ...agentStatuses].filter((item) => item === 'fail' || item === 'not-configured').length,
+                warningCount: scopeWarnings.length + paths.filter((path) => path.status === 'warn').length + 1,
+                summary: summarizeClaudeStatus(status, mcpEntry),
+                nextAction: nextActionFor(status, mcpEntry, sdd?.next),
+                checkedPaths,
+                canonicalAgentManifest,
+                config: { status: configStatus, paths: compactPaths(paths, normalized.payloadMode), mcpEntry: compactMcpEntry(mcpEntry, normalized.payloadMode) },
+                ...(sdd === undefined ? {} : { sdd: compactSdd(sdd, normalized.payloadMode) }),
+                mcpRequiredTools: tools,
+                originalBytes: Buffer.byteLength(JSON.stringify(verboseShape), 'utf8'),
+                compactBytes: Buffer.byteLength(JSON.stringify(compactShape), 'utf8'),
+                verboseAvailable: normalized.payloadMode === 'compact',
+                fullContentRef: `provider-status:claude:user-global:${normalized.workspaceRoot}`,
+                generatedAt: 'read-only-snapshot',
+                safety: { ...PROVIDER_HEALTH_SAFETY, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES },
+            },
+        };
+    }
 }
 function summarizeClaudeAgents(agents) {
     return { expected: agents.agents.length, managed: agents.agents.filter((agent) => agent.status === 'managed').length, missing: agents.agents.filter((agent) => agent.status === 'missing').length, conflicting: agents.agents.filter((agent) => agent.status === 'conflicting' || agent.status === 'invalid').length };
@@ -149,6 +206,18 @@ function claudeConfigHealthStatus(statuses) {
         return 'warn';
     return 'pass';
 }
+function claudeProjectMemoryPathStatus(state) {
+    const status = state.status === 'managed-current' ? 'pass' : state.status === 'managed-stale' ? 'warn' : state.status === 'blocked' ? 'fail' : 'not-configured';
+    return {
+        label: 'project CLAUDE.md managed block',
+        path: state.path,
+        exists: state.exists,
+        readable: state.status !== 'blocked' || state.reason !== 'unreadable',
+        parsed: state.status === 'managed-current' || state.status === 'managed-stale',
+        status,
+        detail: state.message,
+    };
+}
 function compactPaths(paths, mode) {
     if (mode === 'verbose')
         return paths;

package/dist/mcp/schema.js

@@ -90,6 +90,7 @@ export function toInternalVgxMcpToolName(toolName) {
     return EXPOSED_TO_INTERNAL_TOOL_NAMES[toolName];
 }
 const scopes = ['project', 'personal'];
+const providerScopes = ['project', 'personal', 'local', 'user'];
 const agentModes = ['agent', 'subagent'];
 const memoryTypes = ['architecture', 'decision', 'bugfix', 'pattern', 'config', 'discovery', 'learning', 'preference', 'manual'];
 const activityKinds = ['prompt', 'tool_call', 'artifact', 'summary', 'error'];
@@ -429,7 +430,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_status: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
+        scope: z.enum(providerScopes).optional(),
         providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         change: z.string().min(1).optional(),
@@ -439,7 +440,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_doctor: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
+        scope: z.enum(providerScopes).optional(),
         providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         expectedPromptContractVersion: z.number().int().positive().optional(),
@@ -449,7 +450,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_change_plan: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
+        scope: z.enum(providerScopes).optional(),
         provider: z.enum(providerChangePlanProviders),
         changeType: z.enum(providerChangePlanTypes),
         workspaceRoot: z.string().min(1),