vgxness 1.5.1 → 1.6.0

package/dist/mcp/provider-doctor.js

@@ -1,15 +1,27 @@
 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 { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, rollupProviderDoctor, } from './provider-health-types.js';
+import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.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;
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
     runDoctor(input = {}) {
         return this.getDoctor(input);
     }
     getDoctor(input = {}) {
         const normalized = normalizeProviderHealthInput(input);
+        if (normalized.providerAdapter === 'claude')
+            return this.getClaudeDoctor(normalized);
         if (normalized.providerAdapter !== 'opencode')
             return providerHealthFailure(`Unsupported provider adapter: ${normalized.providerAdapter}`);
+        const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
         const paths = inspectOpenCodeConfigPaths(normalized.workspaceRoot, normalized.env);
         const before = snapshotPaths(paths.map((path) => path.path), normalized.workspaceRoot);
         const readableJson = paths.filter((path) => path.parsed);
@@ -21,6 +33,7 @@ export class ProviderDoctorService {
                 detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}`,
             },
             { id: 'provider-supported', status: 'pass', detail: 'OpenCode provider adapter selected.' },
+            canonicalAgentManifestCheck(canonicalAgentManifest, normalized.payloadMode),
             configReadableCheck(readableJson.length, paths.filter((path) => path.exists).length),
             mcpEntryCheck(config),
             defaultAgentCheck(config),
@@ -71,6 +84,70 @@ 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), projectMemory.path, ...advisoryPaths];
+        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 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 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: 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)),
+        ];
+        const status = rollupProviderDoctor(checks.map((check) => check.status));
+        const compactChecksValue = compactChecks(checks, normalized.payloadMode);
+        const checkedPaths = normalized.payloadMode === 'verbose' ? checkedPathList : checkedPathList.filter((path) => existsSync(path) || path === mcp.path);
+        const failedChecks = checks.filter((check) => check.status === 'fail').map((check) => check.id);
+        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 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: 'warn', detail: `Claude ${canonicalScope} scope is supported as read-only advisory status/doctor/change-plan. Future install requires explicit confirmation/preflight and Claude CLI; private config mutation is unsupported.` },
+            { 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: 'provider-config-readonly-safety', status: 'pass', detail: `No Claude ${canonicalScope} paths were inspected or mutated; no repair/install/write occurred.` },
+        ];
+        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 = [
+            `If you choose to configure Claude ${canonicalScope} scope manually, run Claude Code yourself and use a command like: claude mcp add --scope ${canonicalScope} vgxness -- vgxness mcp start.`,
+            'VGXNESS will not read or write private Claude config files during status/doctor/change-plan, repair config, or execute Claude Code from read-only surfaces.',
+        ];
+        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: `Claude ${canonicalScope} doctor is advisory and read-only; no private Claude files were inspected, no config was changed, and Claude Code was not executed.`, recommendations, checks: compactChecksValue, checkedPaths: [], bytes: { originalBytes: Buffer.byteLength(JSON.stringify({ checks, checkedPaths: [] }), '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')
@@ -115,6 +192,20 @@ function configReadableCheck(readableCount, existingCount) {
         detail: `Found ${existingCount} OpenCode config path(s), ${readableCount} readable JSON config(s). Project config can override user/global config.`,
     };
 }
+function canonicalAgentManifestCheck(diagnostic, mode) {
+    if (diagnostic.status === 'pass') {
+        const detail = mode === 'verbose'
+            ? `Canonical agent manifest validates: defaultAgent=${diagnostic.defaultAgentName}, promptContractVersion=${diagnostic.promptContractVersion}, agents=${diagnostic.agentCount}, managers=${diagnostic.managerCount}, subagents=${diagnostic.subagentCount}, providerSupport=${diagnostic.providerSupport.map((support) => `${support.provider}:${support.level}${support.reason === undefined ? '' : ` (${support.reason})`}`).join(', ')}.`
+            : `Canonical agent manifest validates: defaultAgent=${diagnostic.defaultAgentName}, promptContractVersion=${diagnostic.promptContractVersion}, agents=${diagnostic.agentCount}, managers=${diagnostic.managerCount}, subagents=${diagnostic.subagentCount}.`;
+        return { id: 'canonical-agent-manifest', status: 'pass', detail };
+    }
+    return {
+        id: 'canonical-agent-manifest',
+        status: 'fail',
+        detail: `Canonical agent manifest validation failed: ${diagnostic.validationErrors.join('; ') || 'unknown validation failure'}.`,
+        remediation: 'Fix the canonical agent manifest validation errors before relying on provider projection or provider setup.',
+    };
+}
 function mcpEntryCheck(config) {
     const mcp = isRecord(config?.mcp) ? config.mcp : undefined;
     const entry = mcp?.vgxness;
@@ -169,6 +260,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

@@ -1,8 +1,14 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { inspectClaudeCodeAgents } from './claude-code-agent-config.js';
+import { createClaudeCodeCliRegistrationPreview } from './claude-code-cli.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 { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
 import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodePromptContractVersion, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
-import { normalizeProviderHealthInput, PROVIDER_HEALTH_SAFETY, providerHealthFailure, REQUIRED_PROVIDER_MCP_TOOLS, rollupProviderHealth, } from './provider-health-types.js';
+import { buildCanonicalAgentManifestDiagnostic } from './provider-canonical-agent-manifest.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;
@@ -11,8 +17,11 @@ export class ProviderStatusService {
     }
     getStatus(input = {}) {
         const normalized = normalizeProviderHealthInput(input);
+        if (normalized.providerAdapter === 'claude')
+            return this.getClaudeStatus(normalized);
         if (normalized.providerAdapter !== 'opencode')
             return providerHealthFailure(`Unsupported provider adapter: ${normalized.providerAdapter}`);
+        const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
         const paths = inspectOpenCodeConfigPaths(normalized.workspaceRoot, normalized.env);
         const mcpEntry = inspectOpenCodeMcpEntry(paths);
         const providerConfig = readFirstParsedConfig(paths);
@@ -20,7 +29,7 @@ export class ProviderStatusService {
         const subagentsConfigured = hasConfiguredSubagents(providerConfig);
         const tools = requiredToolPresence();
         const configStatus = resolveConfigStatus(paths, mcpEntry, managerConfigured, subagentsConfigured);
-        const status = rollupProviderHealth([configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))]);
+        const status = rollupProviderHealth([canonicalAgentManifest.status, configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))]);
         const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
         const generatedAt = 'read-only-snapshot';
         const checkedPaths = normalized.payloadMode === 'verbose'
@@ -28,17 +37,19 @@ export class ProviderStatusService {
             : paths.filter((path) => path.exists || path.status !== 'not-configured').map((path) => path.path);
         const verboseShape = {
             config: { status: configStatus, paths, mcpEntry },
+            canonicalAgentManifest,
             sdd,
             mcpRequiredTools: tools,
         };
         const compactShape = {
             config: { status: configStatus, paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') },
+            canonicalAgentManifest,
             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 = [configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))].filter((item) => item === 'fail' || item === 'not-configured').length;
+        const issueCount = [canonicalAgentManifest.status, configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))].filter((item) => item === 'fail' || item === 'not-configured').length;
         const warningCount = [configStatus, mcpEntry.status, ...paths.map((path) => path.status)].filter((item) => item === 'warn').length;
         return {
             ok: true,
@@ -58,6 +69,7 @@ export class ProviderStatusService {
                 summary: summarizeStatus(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,
@@ -77,6 +89,141 @@ export class ProviderStatusService {
         const next = this.deps.sdd.getNext({ project, change });
         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 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.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), 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 + resolvedScope.value.warnings.length + paths.filter((path) => path.status === 'warn').length;
+        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,
+                warningCount,
+                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,
+                compactBytes,
+                verboseAvailable: normalized.payloadMode === 'compact',
+                fullContentRef: `provider-status:claude:${normalized.workspaceRoot}`,
+                generatedAt: 'read-only-snapshot',
+                safety: PROVIDER_HEALTH_SAFETY,
+            },
+        };
+    }
+    getClaudeUserGlobalStatus(normalized, canonicalScope = 'user', scopeWarnings = []) {
+        const canonicalAgentManifest = (this.deps.canonicalAgentManifestDiagnostic ?? buildCanonicalAgentManifestDiagnostic)();
+        const paths = [
+            {
+                label: `Claude ${canonicalScope} scope`,
+                path: `${canonicalScope} Claude configuration (not inspected)`,
+                exists: false,
+                readable: false,
+                parsed: false,
+                status: 'warn',
+                detail: `Claude ${canonicalScope} scope is advisory only in read-only status: VGXNESS does not read private Claude files, write config, execute Claude Code, or install provider config.`,
+            },
+        ];
+        const mcpEntry = {
+            configured: false,
+            status: 'warn',
+            serverName: 'vgxness',
+            detail: `${canonicalScope} Claude MCP status is not inspected by VGXNESS; use this as planning guidance only. Future apply uses Claude CLI argv only: ${createClaudeCodeCliRegistrationPreview(canonicalScope).join(' ')}`,
+        };
+        const tools = requiredToolPresence();
+        const status = rollupProviderHealth([canonicalAgentManifest.status, 'warn']);
+        const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
+        const verboseShape = { config: { status: 'warn', paths, mcpEntry }, canonicalAgentManifest, scopeCapabilities: CLAUDE_USER_GLOBAL_SCOPE_CAPABILITIES, scopeWarnings, sdd, mcpRequiredTools: tools };
+        const compactShape = { config: { status: 'warn', paths: compactPaths(paths, 'compact'), mcpEntry: compactMcpEntry(mcpEntry, 'compact') }, canonicalAgentManifest, 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: [],
+                issueCount: canonicalAgentManifest.status === 'fail' ? 1 : 0,
+                warningCount: 1 + scopeWarnings.length,
+                summary: `Claude ${canonicalScope} scope status is read-only/advisory; no private Claude files are inspected or written, and Claude Code is not executed.`,
+                nextAction: { kind: 'review', message: 'Review the planning-only guidance; future apply requires explicit confirmation/preflight and uses Claude CLI argv, not private config mutation.' },
+                checkedPaths: [],
+                canonicalAgentManifest,
+                config: { status: 'warn', 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 };
+}
+function claudeConfigHealthStatus(statuses) {
+    if (statuses.some((status) => status === 'fail'))
+        return 'fail';
+    if (statuses.some((status) => status === 'not-configured'))
+        return 'not-configured';
+    if (statuses.some((status) => status === 'warn'))
+        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')
@@ -212,6 +359,15 @@ function summarizeStatus(status, mcpEntry) {
         return 'OpenCode provider config has warnings; no changes were made.';
     return 'OpenCode provider status check found a blocking issue; no changes were made.';
 }
+function summarizeClaudeStatus(status, mcpEntry) {
+    if (status === 'ready')
+        return 'Claude project .mcp.json and VGXNESS agent files are readable and configured.';
+    if (status === 'not-configured')
+        return mcpEntry.detail;
+    if (status === 'warning')
+        return 'Claude provider project config has warnings; no changes were made.';
+    return 'Claude provider status check found a blocking issue; no changes were made.';
+}
 function nextActionFor(status, mcpEntry, sddNext) {
     if (sddNext !== undefined)
         return { kind: 'advance-sdd', message: 'Continue the next SDD phase inside OpenCode using MCP status/ready/artifact tools and hidden SDD subagents.' };

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,8 +430,8 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_status: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
-        providerAdapter: z.literal('opencode').optional(),
+        scope: z.enum(providerScopes).optional(),
+        providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         change: z.string().min(1).optional(),
         payloadMode: z.enum(payloadModes).optional(),
@@ -439,8 +440,8 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_provider_doctor: z
         .object({
         project: z.string().min(1).optional(),
-        scope: z.enum(scopes).optional(),
-        providerAdapter: z.literal('opencode').optional(),
+        scope: z.enum(providerScopes).optional(),
+        providerAdapter: z.enum(['opencode', 'claude']).optional(),
         workspaceRoot: z.string().min(1).optional(),
         expectedPromptContractVersion: z.number().int().positive().optional(),
         payloadMode: z.enum(payloadModes).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),

package/dist/mcp/validation.js

@@ -187,7 +187,7 @@ function validateProviderHealthInput(input, tool) {
         return scope;
     if (scope.value !== undefined)
         result.scope = scope.value;
-    const providerAdapter = readOptionalOneOf(record.value, 'providerAdapter', ['opencode'], tool);
+    const providerAdapter = readOptionalOneOf(record.value, 'providerAdapter', ['opencode', 'claude'], tool);
     if (!providerAdapter.ok)
         return providerAdapter;
     if (providerAdapter.value !== undefined)

package/dist/memory/memory-service.js

@@ -161,6 +161,10 @@ export class MemoryService {
         const result = this.artifacts.listByTopicPrefix(project, topicPrefix);
         return this.record(result, context, { operation: 'artifact.list', targetType: 'artifact', topicKey: topicPrefix });
     }
+    /** Read artifacts for read-only/status projections without writing provenance traces. */
+    listArtifactsByTopicPrefixNoTrace(project, topicPrefix) {
+        return this.artifacts.listByTopicPrefix(project, topicPrefix);
+    }
     close() {
         this.database.close();
     }