vgxness 1.7.0 → 1.9.0

package/dist/agents/canonical-agent-manifest.js

@@ -74,7 +74,7 @@ function managerDefinition() {
         mode: 'agent',
         builtIn: true,
         name: canonicalDefaultAgentName,
-        description: 'Coordinates VGXNESS MCP state and SDD sub-agents while avoiding unsafe inline execution.',
+        description: 'Coordinates VGXNESS MCP state and SDD sub-agents while routing Tier 0-2 lightweight work, Tier 3 preflight validation, and Tier 4 formal SDD.',
         instructions: { kind: 'inline', value: registryManagerInstructions },
         capabilities: ['sdd-orchestration', 'agent-routing', 'mcp-coordination', 'project-local-automation'],
         permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'ask', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' },
@@ -131,6 +131,9 @@ Coach while coordinating: teach briefly when helpful, explain practical tradeoff
 - Do not publish packages unless explicitly requested.
 - Do not change model or reasoning effort.
 
+## Flexible governance routing
+Use the lightest safe path: Tier 0-2 direct/explore/plan/debug/quickfix/build; keywords alone do not force SDD. Tier 3 needs preflight/explicit validation but not automatic SDD. Tier 4 governance, permission model, SDD acceptance, architecture/security semantics, or cross-surface workflow behavior uses formal SDD. Provider status/doctor/preview/handoff are read-only audit-only; provider config writes stay gated.
+
 ## 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.
 

package/dist/cli/cli-help.js

@@ -69,7 +69,7 @@ Areas:
   Use --overwrite-vgxness (alias --reinstall) to reinstall only VGXNESS-managed OpenCode entries while preserving unrelated config; --yes is still required to write.
   It writes only after --yes. The default target is $HOME/.config/opencode/opencode.json; use --scope project to target .opencode/opencode.json explicitly.
   Project OpenCode config can override user config. Plans are read-only; applies refuse unsafe existing config and create backups before merge.
-  Claude support is secondary. Claude scopes are local|project|user; compatibility aliases personal/global map to user with warnings. Plans show Claude CLI argv, project .mcp.json compatibility, user ~/.claude.json MCP merge, agents, and guarded CLAUDE.md managed memory separately. Project scope confirmed applies write .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block as needed. User/global confirmed applies narrowly merge only mcpServers.vgxness in ~/.claude.json, write ~/.claude/agents/*.md, and manage only the VGXNESS block in ~/.claude/CLAUDE.md. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). Status/doctor/change-plan are read-only and do not execute Claude Code.
+  Claude support is first-class for guarded MCP setup. Claude scopes are local|project|user; compatibility aliases personal/global map to user with warnings. Plans show Claude CLI argv, project .mcp.json compatibility, user ~/.claude.json MCP merge, agents, and guarded CLAUDE.md managed memory separately. Project scope confirmed applies write .mcp.json, .claude/agents/*.md, and the project-root CLAUDE.md managed block as needed. User/global confirmed applies narrowly merge only mcpServers.vgxness in ~/.claude.json, write ~/.claude/agents/*.md, and manage only the VGXNESS block in ~/.claude/CLAUDE.md. Confirmed Claude writes/CLI execution require VGXNESS run preflight metadata (--run-id, with optional --phase/--agent-id). Status/doctor/change-plan are read-only and do not execute Claude Code.
 
   skills register --project <name> --name <name> --description <text>
   skills list [--project <name>] [--scope project|personal]
@@ -98,7 +98,7 @@ Areas:
   No args in an interactive TTY opens the OpenTUI main menu.
   No args without a TTY prints static safe setup guidance and exits 0 without opening project state.
   Setup TUI may launch without --project; Installation remains available and project-scoped checks are deferred while project screens render project-required recovery states.
-  Provider setup support: OpenCode supported primary/default; Claude supported secondary for CLI MCP registration, project compatibility, and project/user agent planning; Antigravity placeholder; Custom/future extension point.
+  Provider setup support: OpenCode first-class supported default guided install; Claude first-class supported guarded install for CLI MCP registration, project compatibility, and project/user agent planning; Antigravity placeholder; Custom/future extension point.
   Provider config writes/install/apply are external-only and require explicit confirmation.
 
   sdd status --project <name> --change <id> [--json]

package/dist/cli/setup-status-renderer.js

@@ -41,5 +41,10 @@ function renderDefaults(status) {
 }
 function renderProvider(provider) {
     const safety = provider.actions.some((action) => action.safety.writesProviderConfig) ? 'external write action flagged' : 'no provider writes';
-    return `${provider.displayName} ${provider.status}/${provider.supportLevel} (${safety})`;
+    return `${provider.displayName} ${provider.status}/${renderSupportLevel(provider.supportLevel)} (${safety})`;
+}
+function renderSupportLevel(supportLevel) {
+    if (supportLevel === 'supported-primary' || supportLevel === 'supported-secondary')
+        return 'supported';
+    return supportLevel;
 }

package/dist/cli/tui/main-menu/main-menu-read-model.js

@@ -14,7 +14,7 @@ const statCards = [
     { label: 'SDD', value: 'guided', badge: '', description: 'MCP flow' },
 ];
 const statusSnapshotLines = [
-    'OpenCode primary; dashboard does not call providers.',
+    'OpenCode supported; dashboard does not call providers.',
     'Advanced checks stay explicit: setup status, mcp doctor opencode.',
 ];
 const optionCopy = {

package/dist/cli/tui/setup/setup-tui-read-model.js

@@ -31,7 +31,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         workspaceRootLabel: compactPath(workspaceRoot, 72),
         readinessLabel: label(readiness),
         readinessBadge: readinessBadge(readiness),
-        providerLabel: isOpenCode ? 'OpenCode' : isClaude ? 'Claude (supported secondary)' : 'Manual / none',
+        providerLabel: isOpenCode ? 'OpenCode' : isClaude ? 'Claude (first-class supported)' : 'Manual / none',
         databaseLabel: plan === undefined ? 'pending' : plan.db.mode,
         databasePathLabel: compactPath(databasePath, 72),
         databaseSourceLabel: String(databaseSource),
@@ -47,8 +47,8 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         opencodeActionLabel: isOpenCode ? opencodeActionLabel(opencode?.action) : isClaude ? 'No guided setup write; use guarded Claude install with run preflight.' : 'No automatic provider write; use manual setup guidance.',
         memoryPathExplanation: memoryExplanation,
         providerInstallabilityLabel: isOpenCode
-            ? 'OpenCode is the default guided install provider. Claude is supported secondary via guarded mcp install claude --scope project --yes --run-id <id>.'
-            : 'Manual / none is read-only guidance. Claude remains supported secondary through explicit guarded apply outside this guided OpenCode flow.',
+            ? 'OpenCode is the default guided install provider. Claude is first-class supported via guarded mcp install claude --scope project --yes --run-id <id>.'
+            : 'Manual / none is read-only guidance. Claude remains supported through explicit guarded apply outside this guided OpenCode flow.',
         agentReadinessLabel: agentReadiness.label,
         agentReadinessDetail: agentReadiness.detail,
         plannedActions: plan?.actions.map((action) => ({
@@ -79,7 +79,7 @@ export function setupTuiViewModelFromPlan(plan, status, state) {
         ],
         providerChoices: [
             choice('provider:opencode', 'OpenCode', 'Default guided install provider; writes still require final confirmation.', (selections?.provider ?? plan?.provider ?? 'opencode') === 'opencode', state?.focusedChoiceId, [badgeLabels.recommended]),
-            choice('provider:claude-supported-secondary', 'Claude (supported secondary)', 'Claude CLI MCP registration and project compatibility apply only via guarded mcp install claude --scope project --yes --run-id <id>; not default.', (selections?.provider ?? plan?.provider) === 'claude', state?.focusedChoiceId, ['[supported secondary]', badgeLabels.readOnly]),
+            choice('provider:claude-supported', 'Claude (first-class supported)', 'Claude CLI MCP registration and project compatibility apply only via guarded mcp install claude --scope project --yes --run-id <id>; explicit install path.', (selections?.provider ?? plan?.provider) === 'claude', state?.focusedChoiceId, ['[supported]', badgeLabels.readOnly]),
             choice('provider:none', 'Manual / none', 'No automatic provider config write; follow manual setup guidance.', (selections?.provider ?? plan?.provider) === 'none', state?.focusedChoiceId, [badgeLabels.manual, badgeLabels.readOnly]),
         ],
         scopeChoices: isOpenCode
@@ -106,13 +106,13 @@ function previewDetailLines(input) {
     const opencode = plan?.opencode;
     const actions = plan?.actions.map((action) => `Planned action: ${action.description}${action.targetPath === undefined ? '' : ` Target: ${compactPath(action.targetPath, 72)}`}${action.backupRequired ? ' Backup required.' : ''}`) ?? ['Planned action: create read-only preview plan.'];
     return [
-        `Provider: ${input.provider === 'opencode' ? 'OpenCode [recommended default]' : input.provider === 'claude' ? 'Claude [supported secondary] [guarded explicit apply]' : 'Manual / none [manual] [read-only]'}`,
+        `Provider: ${input.provider === 'opencode' ? 'OpenCode [recommended default]' : input.provider === 'claude' ? 'Claude [first-class supported] [guarded explicit apply]' : 'Manual / none [manual] [read-only]'}`,
         `Memory path: ${plan?.db.mode ?? 'pending'} at ${compactPath(input.databasePath, 72)} (source: ${String(input.databaseSource)})`,
         `Memory guidance: ${memoryPathExplanation(plan, input.databasePath, input.databaseSource)}`,
         `Scope: ${input.isOpenCode ? (opencode?.scope ?? 'user') : 'disabled for manual/none provider'}`,
         `Install mode: ${input.isOpenCode ? (opencode?.installsAgents === false ? 'mcp-only' : 'mcp-plus-agents') : 'disabled for manual/none provider'}`,
         `Reinstall VGXNESS entries: ${input.isOpenCode ? String(opencode?.overwriteVgxness ?? false) : 'disabled for manual/none provider'}`,
-        `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation; Claude supported secondary requires guarded mcp install claude --scope project --yes --run-id <id>.' : 'No guided provider install from this selection; Claude supported secondary uses guarded explicit apply.'}`,
+        `Provider installability: ${input.isOpenCode ? 'OpenCode installable after final confirmation; Claude first-class support requires guarded mcp install claude --scope project --yes --run-id <id>.' : 'No guided provider install from this selection; Claude uses guarded explicit apply.'}`,
         `Agent readiness: ${agentReadinessFromPlan(plan)}`,
         `Target config: ${input.isOpenCode && opencode?.targetPath !== undefined ? compactPath(opencode.targetPath, 72) : 'none; no provider config will be written'}`,
         `Safety: ${input.isOpenCode ? '[will write after confirm] only on final confirmation' : '[read-only] manual/no-provider-write mode'}`,
@@ -132,7 +132,7 @@ function helpLines(screen) {
         'Next/back: Tab continues; Shift+Tab goes back. Enter continues on review and confirms only on final confirmation.',
         'Cancel/close: q or Esc cancels setup; when help is open, ?/h toggles it closed.',
         reviewLine,
-        'Provider support: OpenCode is the default guided install provider; Claude is supported secondary for guarded explicit apply via mcp install claude --scope project --yes --run-id <id>; Manual / none writes no provider config.',
+        'Provider support: OpenCode is the default guided install provider; Claude is first-class supported for guarded explicit apply via mcp install claude --scope project --yes --run-id <id>; Manual / none writes no provider config.',
         'Agent readiness: the preview checks vgxness-manager/SDD readiness guidance; preview screens never seed agents.',
         'No-write guarantee: no provider config is written before explicit final confirmation.',
     ];

package/dist/governance/index.js

@@ -1,3 +1,4 @@
 export * from './governance-report-builder.js';
 export * from './overlay-fingerprint.js';
+export * from './risk-classifier.js';
 export * from './schema.js';

package/dist/governance/risk-classifier.js

@@ -0,0 +1,116 @@
+import { isWorkflowId } from '../workflows/schema.js';
+const readOnlyIntentTerms = [
+    /\b(explain|what|why|how|describe|read|inspect|search|status|doctor|preview|diagnos(?:e|tic|tics)|logs?)\b/,
+    /\b(explicar|diagnosticar)\b/,
+];
+const planningTerms = [/\b(plan|review|checklist|preview|dry[- ]run)\b/, /\btarea simple\b/];
+const quickfixTerms = [/\b(fix|patch|typo|small|bounded|arreglar)\b/];
+const buildTerms = [/\b(build|add|create|implement|feature|capability)\b/];
+const tier3Terms = [
+    /\b(install|repair|write config|provider config|\.opencode|\.claude|global config)\b/,
+    /\b(commit|push|tag|amend|force[- ]push|publish|release|delete|remove|destroy|drop|reset|secret|token|sudo|external|network)\b/,
+    /\b(aprobaci[oó]n|permiso)\b/,
+];
+const tier4MutationTerms = [
+    /\b(build|add|create|implement)\b.*\bnew\b.*\bworkflow\b/,
+    /\b(change|update|modify|refactor|implement|build|add|create|fix|arreglar)\b.*\b(governance|permission model|permissions?|sdd acceptance|artifact acceptance|workflow routing|workflow capability|routing|security semantics|architecture|cross[- ]surface)\b/,
+    /\b(governance|permission model|permissions?|sdd acceptance|artifact acceptance|workflow routing|workflow capability|routing|security semantics|architecture|cross[- ]surface)\b.*\b(change|update|modify|refactor|implement|build|add|create|fix|arreglar)\b/,
+];
+const keywordOnlyProtectedTerms = /\b(governance|permissions?|workflow|provider|sdd|security|architecture)\b/;
+export function classifyIntentRisk(input) {
+    const intent = normalize(input.intent);
+    const evidence = [`intent:${intent}`];
+    if (tier4MutationTerms.some((term) => term.test(intent))) {
+        const reasonCodes = [];
+        if (/\bpermissions?|permission model|permiso\b/.test(intent))
+            reasonCodes.push('permission_model_change');
+        if (/\bsdd acceptance|artifact acceptance|sdd\b/.test(intent))
+            reasonCodes.push('sdd_governance_change');
+        if (/\bgovernance\b/.test(intent))
+            reasonCodes.push('governance_change');
+        if (/\barchitecture\b/.test(intent))
+            reasonCodes.push('architecture_change');
+        if (/\bcross[- ]surface|workflow routing|workflow capability|routing\b/.test(intent))
+            reasonCodes.push('cross_surface_change');
+        return classification(4, unique(reasonCodes.length === 0 ? ['governance_change'] : reasonCodes), 'sdd', 'ask', evidence);
+    }
+    if (readOnlyIntentTerms.some((term) => term.test(intent)) || (/\b(no uses sdd)\b/.test(intent) && keywordOnlyProtectedTerms.test(intent))) {
+        const workflow = /\bdiagnos(?:e|tic|tics)|diagnosticar|doctor|status|logs?\b/.test(intent) ? 'debug' : 'direct';
+        return classification(0, ['read_only'], workflow, 'audit', evidence);
+    }
+    if (tier3Terms.some((term) => term.test(intent)))
+        return classification(3, ['unknown_conservative'], workflowFromHint(input.workflowHint, 'plan'), 'ask', evidence);
+    if (buildTerms.some((term) => term.test(intent)))
+        return classification(2, ['moderate_project_mutation'], 'build', 'ask', evidence);
+    if (planningTerms.some((term) => term.test(intent)))
+        return classification(1, ['read_only'], 'plan', 'audit', evidence);
+    if (quickfixTerms.some((term) => term.test(intent)))
+        return classification(1, ['small_local_change'], 'quickfix', 'allow', evidence);
+    return classification(0, ['read_only'], 'explore', 'audit', evidence);
+}
+export function classifyOperationRisk(input) {
+    const op = normalize([input.operation, input.providerToolName].filter(Boolean).join(' '));
+    const evidence = [`category:${input.category}`, `operation:${input.operation}`];
+    if (input.providerToolName !== undefined)
+        evidence.push(`providerTool:${input.providerToolName}`);
+    if (input.destructive === true)
+        return classification(3, ['destructive_operation'], 'plan', 'ask', evidence);
+    if (input.external === true || input.category === 'network' || input.category === 'external-directory')
+        return classification(3, ['external_operation'], 'plan', 'ask', evidence);
+    if (input.privileged === true)
+        return classification(3, ['privileged_operation'], 'plan', 'ask', evidence);
+    if (input.ambiguous === true)
+        return classification(3, ['ambiguous_mutation'], 'plan', 'ask', evidence);
+    if (input.category === 'secrets')
+        return classification(3, ['secret_access'], 'plan', 'deny', evidence);
+    if (input.category === 'provider-tool')
+        return classifyProviderTool(op, evidence);
+    if (input.category === 'git-write' || (input.category === 'git' && /\b(commit|amend|tag|push|delete[- ]branch|force[- ]push|merge|rebase)\b/.test(op)))
+        return classification(3, ['git_write'], 'plan', 'ask', evidence);
+    if (input.category === 'git')
+        return classification(0, ['read_only'], 'direct', 'audit', evidence);
+    if (/\b(publish|release|npm publish|package distribution)\b/.test(op))
+        return classification(3, ['publish_release'], 'plan', 'ask', evidence);
+    if (input.category === 'shell' && /^command-allowlist[ :-][a-z0-9._/-]+$/.test(op))
+        return classification(0, ['allowlisted_verification'], 'debug', 'allow', evidence);
+    if (input.category === 'shell')
+        return classification(3, ['unknown_conservative'], 'plan', 'ask', evidence);
+    if (input.category === 'test-run')
+        return classification(0, ['allowlisted_verification'], 'debug', 'audit', evidence);
+    if (input.category === 'read')
+        return classification(0, [input.workspaceRoot !== undefined ? 'workspace_read' : 'read_only'], 'direct', 'audit', evidence);
+    if (input.category === 'edit' || input.category === 'implementation-edit' || input.category === 'spec-write' || input.category === 'design-write' || input.category === 'task-write')
+        return classification(input.category === 'implementation-edit' ? 2 : 1, [input.category === 'implementation-edit' ? 'moderate_project_mutation' : 'small_local_change'], workflowFromHint(input.workflow, 'quickfix'), 'ask', evidence);
+    if (input.category === 'install')
+        return classification(3, ['external_operation'], 'plan', 'ask', evidence);
+    if (input.category === 'memory' || input.category === 'memory-write')
+        return classification(1, ['small_local_change'], 'explore', 'audit', evidence);
+    return classification(3, ['unknown_conservative'], 'plan', 'ask', evidence);
+}
+function classifyProviderTool(operation, evidence) {
+    if (/\b(status|doctor|preview|handoff|change[- ]plan|health)\b/.test(operation))
+        return classification(0, ['provider_readonly_audit'], 'direct', 'audit', evidence);
+    if (/\b(install|setup|repair|write|apply|config|mcp[- ]install)\b/.test(operation))
+        return classification(3, ['provider_config_write'], 'plan', 'ask', evidence);
+    return classification(3, ['unknown_conservative'], 'plan', 'ask', evidence);
+}
+function classification(tier, reasonCodes, recommendedWorkflow, defaultDecision, evidence) {
+    return {
+        tier,
+        reasonCodes,
+        recommendedWorkflow,
+        defaultDecision,
+        requiresSdd: tier === 4,
+        requiresExplicitValidation: tier >= 3,
+        evidence,
+    };
+}
+function workflowFromHint(value, fallback) {
+    return value !== undefined && isWorkflowId(value) ? value : fallback;
+}
+function normalize(value) {
+    return value.toLowerCase().replace(/[^a-z0-9._/ áéíóúüñ-]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function unique(values) {
+    return [...new Set(values)];
+}

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

@@ -5,7 +5,7 @@ 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'];
+export const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const safety = {
     readOnly: true,
     willWrite: false,
@@ -102,7 +102,7 @@ function unsupportedProviderEnvelope(input) {
         supported: false,
         status: 'unsupported',
         code: 'UNSUPPORTED_PROVIDER',
-        summary: `${input.provider} is a recognized provider value, but provider change planning is currently implemented only for OpenCode.`,
+        summary: `${input.provider} is a recognized provider value, but read-only provider change planning currently supports OpenCode and Claude.`,
         providerIdentity: {
             provider: input.provider,
             adapter: input.provider,
@@ -120,15 +120,16 @@ function unsupportedProviderEnvelope(input) {
     };
 }
 function blockedPlanEnvelope(input, status, doctor, message) {
+    const providerName = input.provider === 'claude' ? 'Claude' : 'OpenCode';
     return {
         ...baseEnvelope(input),
         supported: true,
         status: 'blocked',
         code: 'PLAN_UNAVAILABLE',
-        summary: `OpenCode change planning could not resolve the future MCP server command: ${message}`,
+        summary: `${providerName} change planning could not resolve the future MCP server command: ${message}`,
         providerIdentity: {
-            provider: 'opencode',
-            adapter: 'opencode',
+            provider: input.provider,
+            adapter: input.provider,
             support: 'supported',
         },
         statusSummary: statusSummary(status),
@@ -206,14 +207,24 @@ function baseEnvelope(input) {
         scope: input.scope,
         provider: input.provider,
         requestedChangeType: input.changeType,
-        normalizedChangeType: normalizeChangeType(input.changeType),
+        normalizedChangeType: normalizeChangeType(input.provider, input.changeType),
         payloadMode: input.payloadMode,
         workspaceRoot: input.workspaceRoot,
         safety,
     };
 }
-function normalizeChangeType(changeType) {
-    return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' ? 'opencode-mcp-install' : changeType;
+function normalizeChangeType(provider, changeType) {
+    if (provider === 'opencode') {
+        return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' || changeType === 'claude-mcp-install'
+            ? 'opencode-mcp-install'
+            : changeType;
+    }
+    if (provider === 'claude') {
+        return changeType === 'setup' || changeType === 'install' || changeType === 'config-preparation' || changeType === 'opencode-mcp-install'
+            ? 'claude-mcp-install'
+            : changeType;
+    }
+    return changeType;
 }
 function statusSummary(status) {
     return {

package/dist/mcp/schema.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { permissionCategories } from '../permissions/schema.js';
 import { sddPhases } from '../sdd/schema.js';
+import { workflowIds } from '../workflows/schema.js';
 import { verificationChangeTypes } from '../verification/index.js';
 export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_sdd_status',
@@ -99,7 +100,7 @@ const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
 const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const payloadModes = ['compact', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const jsonValueSchema = z.lazy(() => z.union([z.string(), z.number().finite(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)]));
 export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_sdd_status: z
@@ -364,6 +365,7 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         runId: z.string().min(1),
         category: z.enum(permissionCategories),
         operation: z.string().min(1),
+        workflow: z.enum(workflowIds).optional(),
         phase: z.string().min(1).optional(),
         agentId: z.string().min(1).optional(),
         workspaceRoot: z.string().min(1).optional(),

package/dist/mcp/validation.js

@@ -1,6 +1,7 @@
 import { isRiskyPermissionCategory, permissionCategories } from '../permissions/schema.js';
 import { parseOperationRetryPolicy } from '../runs/operation-retry.js';
 import { isSddPhase, sddPhases } from '../sdd/schema.js';
+import { workflowIds } from '../workflows/schema.js';
 import { supportedTypeMessage, verificationChangeTypes } from '../verification/index.js';
 import { errorEnvelope, isVgxMcpToolName, } from './schema.js';
 const scopes = ['project', 'personal'];
@@ -13,7 +14,7 @@ const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const permissionDecisions = ['allow', 'ask', 'deny'];
 const payloadModes = ['compact', 'verbose'];
 const providerChangePlanProviders = ['opencode', 'claude', 'antigravity', 'custom'];
-const providerChangePlanTypes = ['opencode-mcp-install', 'setup', 'install', 'config-preparation'];
+const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', 'setup', 'install', 'config-preparation'];
 const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const validMemoryTopicKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/;
 const maxMemoryTitleLength = 200;
@@ -822,6 +823,7 @@ function validateRunPreflightInput(input, tool) {
         'runId',
         'category',
         'operation',
+        'workflow',
         'phase',
         'agentId',
         'workspaceRoot',
@@ -846,6 +848,11 @@ function validateRunPreflightInput(input, tool) {
     if (!operation.ok)
         return operation;
     const result = { runId: runId.value, category: category.value, operation: operation.value };
+    const workflow = readOptionalOneOf(record.value, 'workflow', workflowIds, tool);
+    if (!workflow.ok)
+        return workflow;
+    if (workflow.value !== undefined)
+        result.workflow = workflow.value;
     const copied = copyOptionalStrings(result, record.value, tool, ['phase', 'agentId', 'workspaceRoot', 'targetPath', 'providerToolName']);
     if (!copied.ok)
         return copied;

package/dist/orchestrator/natural-language-planner.js

@@ -1,9 +1,11 @@
+import { classifyIntentRisk } from '../governance/risk-classifier.js';
 const stopWords = new Set(['a', 'an', 'the', 'to', 'for', 'of', 'and', 'or', 'with', 'we', 'before', 'new']);
 const signalRules = [
     {
         signal: 'diagnostic-request',
         terms: [
             /\bdiagnos(e|tic|tics)\b/,
+            /\bdiagnosticar\b/,
             /\bfail(ing|ure|ed)?\b/,
             /\bcrash(es|ing)?\b/,
             /\berrors?\b/,
@@ -18,17 +20,17 @@ const signalRules = [
     { signal: 'planning-request', terms: [/\bplan\b/, /\bpreview\b/, /\breview\b/, /\bdry[- ]run\b/] },
     {
         signal: 'answer-only',
-        terms: [/\bexplain\b/, /\bwhat\b/, /\bhow\b/, /\bwhy\b/, /\bdescribe\b/, /\bunderstand\b/, /\binvestigat(e|ion)\b/, /\binspect\b/, /\bread[- ]only\b/],
+        terms: [/\bexplain\b/, /\bexplicar\b/, /\bwhat\b/, /\bhow\b/, /\bwhy\b/, /\bdescribe\b/, /\bunderstand\b/, /\binvestigat(e|ion)\b/, /\binspect\b/, /\bread[- ]only\b/],
     },
     { signal: 'new-capability', terms: [/\bbuild\b/, /\badd\b/, /\bcreate\b/, /\bnew\b/, /\bcapabilit(y|ies)\b/, /\bfeature\b/] },
     { signal: 'architecture-change', terms: [/\barchitecture\b/, /\barchitectural\b/, /\brefactor\b/, /\bboundar(y|ies)\b/] },
     { signal: 'workflow-change', terms: [/\bworkflow\b/, /\borchestrat(e|ion|or)\b/, /\bsdd\b/, /\bphase\b/] },
     { signal: 'persistence-change', terms: [/\bpersist(ent|ence)?\b/, /\bstorage\b/, /\bsqlite\b/, /\bdatabase\b/, /\bmemory\b/, /\bmigration\b/] },
-    { signal: 'security-sensitive', terms: [/\bsecurity\b/, /\bauth\b/, /\btoken\b/, /\bsecret\b/, /\bpermission\b/] },
+    { signal: 'security-sensitive', terms: [/\bsecurity\b/, /\bauth\b/, /\btoken\b/, /\bsecret\b/, /\bpermission\b/, /\bpermiso\b/, /\baprobaci[oó]n\b/] },
     { signal: 'broad-change', terms: [/\bmulti[- ]file\b/, /\bacross\b/, /\bend[- ]to[- ]end\b/, /\bsystem\b/] },
     { signal: 'execution-request', terms: [/\brun\b/, /\bexecute\b/, /\bapply\b/, /\bstart\b/, /\binstall\b/, /\bpush\b/] },
     { signal: 'provider-execution', terms: [/\bprovider\b/, /\bopencode\b/, /\bclaude\b/, /\bmodel\b/, /\bllm\b/] },
-    { signal: 'file-edit-request', terms: [/\bedit\b/, /\bwrite\b/, /\bmodify\b/, /\bpatch\b/] },
+    { signal: 'file-edit-request', terms: [/\bedit\b/, /\bwrite\b/, /\bmodify\b/, /\bpatch\b/, /\barreglar\b/] },
     { signal: 'provider-config-write', terms: [/\bconfig\b/, /\.opencode\b/, /\.claude\b/, /\bglobal\b/] },
     { signal: 'run-recording', terms: [/\brun record\b/, /\brecord a run\b/, /\bcheckpoint\b/] },
     { signal: 'destructive', terms: [/\bdelete\b/, /\bremove\b/, /\bdestroy\b/, /\bdrop\b/, /\breset\b/] },
@@ -41,7 +43,8 @@ export function createNaturalLanguagePlan(input) {
     const ambiguous = isAmbiguous(normalizedIntent);
     if (ambiguous)
         addSignal(signals, 'ambiguous');
-    const flow = chooseFlow(signals);
+    const risk = classifyIntentRisk({ project: input.project, intent: input.intent });
+    const flow = chooseFlow(signals, risk);
     const workflow = workflowFor(flow);
     const needsClarification = ambiguous;
     const suggestedChangeId = suggestedChangeFor(input, flow);
@@ -67,13 +70,17 @@ export function createNaturalLanguagePlan(input) {
         ...(suggestedChangeId !== undefined ? { suggestedChangeId } : {}),
         previewActions,
         safety,
+        riskTier: risk.tier,
+        riskReasonCodes: risk.reasonCodes,
+        requiresSdd: risk.requiresSdd,
+        requiresExplicitValidation: risk.requiresExplicitValidation,
         ...(input.sdd !== undefined ? { sdd: input.sdd } : {}),
     };
 }
 function normalizeText(value) {
     return value
         .toLowerCase()
-        .replace(/[^a-z0-9._/ -]+/g, ' ')
+        .replace(/[^a-z0-9._/ áéíóúüñ-]+/g, ' ')
         .replace(/\s+/g, ' ')
         .trim();
 }
@@ -118,23 +125,35 @@ function isAmbiguous(intent) {
         return true;
     return /^(fix|update|change|do|handle) (it|this|that)$/.test(intent);
 }
-function chooseFlow(signals) {
+function chooseFlow(signals, risk) {
+    if (risk.requiresSdd)
+        return 'sdd';
+    if (risk.recommendedWorkflow === 'direct')
+        return 'explore';
+    if (risk.recommendedWorkflow === 'debug')
+        return 'debug';
+    if (risk.recommendedWorkflow === 'plan')
+        return 'plan';
+    if (risk.recommendedWorkflow === 'quickfix')
+        return 'quickfix';
+    if (risk.recommendedWorkflow === 'build')
+        return 'build';
     if (signals.includes('answer-only') &&
         !signals.includes('diagnostic-request') &&
         !signals.includes('new-capability') &&
         !signals.includes('planning-request') &&
         !signals.some((signal) => unsafeSignals.has(signal)))
         return 'explore';
-    if (signals.some((signal) => strongSddSignals.has(signal) || strongUnsafeSignals.has(signal)))
-        return 'sdd';
+    if (risk.tier >= 3)
+        return signals.includes('diagnostic-request') ? 'debug' : signals.includes('planning-request') ? 'plan' : 'plan';
     if (signals.includes('diagnostic-request'))
         return 'debug';
     if (signals.includes('answer-only') && !signals.includes('new-capability') && !signals.some((signal) => unsafeSignals.has(signal)))
         return 'explore';
     if (signals.includes('planning-request') && !signals.some((signal) => strongSddSignals.has(signal) || strongUnsafeSignals.has(signal)))
         return 'plan';
-    if (signals.some((signal) => sddSignals.has(signal)) || signals.some((signal) => unsafeSignals.has(signal)))
-        return 'sdd';
+    if (signals.some((signal) => unsafeSignals.has(signal)))
+        return 'plan';
     if (signals.includes('planning-request'))
         return 'plan';
     if (signals.includes('new-capability'))
@@ -171,7 +190,7 @@ function reasonFor(flow, signals, needsClarification) {
     if (flow === 'debug' || flow === 'diagnose')
         return 'The request asks for inspection or failure/status diagnosis, so the preview stays read-only.';
     if (flow === 'sdd')
-        return 'The request includes capability, architecture, workflow, persistence, safety, or execution risk signals, so SDD is the safest preview path.';
+        return 'The request changes governance, permission, SDD, architecture, or cross-surface safety semantics, so SDD is required.';
     if (flow === 'plan')
         return 'The request asks for planning or review without immediate mutation, so SDD is not required for this preview.';
     if (flow === 'build')
@@ -198,14 +217,14 @@ function buildSafety(signals) {
         'Preview only: this preview only classifies intent; no providers are called, no files are edited, no provider config is written, and no run is recorded.',
     ];
     if (signals.includes('execution-request') || signals.includes('provider-execution') || signals.includes('file-edit-request')) {
-        notes.push('Execution was requested but refused in this preview flow; continue manually or through an approved SDD apply phase.');
+        notes.push('Execution was requested but refused in this preview flow; continue manually or through an approved preflight/apply flow.');
     }
     if (signals.includes('destructive'))
         notes.push('Destructive impact was detected; review and approval are required before any real operation.');
     if (signals.includes('provider-config-write'))
         notes.push('Provider configuration impact was detected; this preview will not write provider config.');
     if (signals.includes('persistence-change'))
-        notes.push('Persistent behavior or storage impact was detected; SDD review is recommended.');
+        notes.push('Persistent behavior or storage impact was detected; use the lightest workflow that matches risk tier and require SDD only for Tier 4.');
     if (signals.includes('external'))
         notes.push('External or network impact was detected; this preview does not perform external calls.');
     if (signals.includes('privileged'))
@@ -225,13 +244,11 @@ function buildPreviewActions(input, flow, needsClarification) {
         return [{ kind: 'workflow-preview', description: 'Preview a small localized quickfix; no execution occurs in this planner response.' }];
     if (flow === 'build')
         return [{ kind: 'workflow-preview', description: 'Preview a scoped build workflow; no execution occurs in this planner response.' }];
-    const change = input.change;
-    const command = change === undefined ? undefined : `vgxness sdd next --project ${input.project} --change ${change}`;
     return [
         {
             kind: 'sdd-preview',
-            description: input.sdd?.next?.recommendedAction ?? 'Preview the SDD handoff for this substantial or risky request; do not execute it here.',
-            ...(command !== undefined ? { command } : {}),
+            description: input.sdd?.next?.recommendedAction ??
+                'Continue formal SDD progression through the provider-native manager flow and VGXNESS MCP; do not execute terminal SDD phase commands from this preview.',
         },
     ];
 }

package/dist/permissions/policy-evaluator.js

@@ -1,5 +1,6 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { dirname, isAbsolute, resolve, sep } from 'node:path';
+import { classifyOperationRisk } from '../governance/risk-classifier.js';
 import { isSddPhase, sddPhases } from '../sdd/schema.js';
 export { isRiskyPermissionCategory, permissionCategories, riskyPermissionCategories } from './schema.js';
 export const permissionDecisions = ['allow', 'ask', 'deny'];
@@ -81,15 +82,24 @@ const filesystemCategories = new Set([
     'external-directory',
 ]);
 export function evaluatePermission(request, policy = defaultPermissionPolicy) {
+    const risk = classifyOperationRisk(request);
     if (request.category === 'secrets')
-        return result(request, 'deny', 'secret_access', 'Secret access is denied by default.');
+        return result(request, 'deny', 'secret_access', 'Secret access is denied by default.', {}, risk);
     if (request.category === 'external-directory') {
-        return result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.');
+        return result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.', {}, risk);
     }
+    const hardRisk = hardRiskDecision(request, risk);
+    if (hardRisk !== undefined)
+        return hardRisk;
     const workspaceEscape = workspaceEscapeDecision(request);
     if (workspaceEscape !== undefined)
         return workspaceEscape;
     const sddPhaseDecision = phaseMatrixDecision(request);
+    if (sddPhaseDecision !== undefined && sddPhaseDecision.mode !== 'allow' && sddPhaseDecision.mode !== 'audit')
+        return sddPhaseDecision;
+    const explicitValidation = explicitValidationDecision(request, risk);
+    if (explicitValidation !== undefined)
+        return explicitValidation;
     if (sddPhaseDecision !== undefined)
         return sddPhaseDecision;
     const boundary = workspaceBoundaryDecision(request);
@@ -102,11 +112,18 @@ export function evaluatePermission(request, policy = defaultPermissionPolicy) {
     const baseMessage = agentDecision !== undefined
         ? `${request.agent?.mode ?? 'agent'} ${request.agent?.name ?? request.agent?.id ?? 'unknown'} sets ${request.category} to ${agentDecision}.`
         : (baseRule?.reason ?? `No explicit rule exists for ${request.category}; ask by default.`);
-    const risk = riskDecision(request);
-    if (risk !== undefined && isLessRestrictive(baseDecision, risk.decision)) {
-        return result(request, risk.decision, risk.reason, risk.message);
+    const flagRisk = riskDecision(request);
+    if (flagRisk !== undefined && isLessRestrictive(baseDecision, flagRisk.decision)) {
+        return result(request, flagRisk.decision, flagRisk.reason, flagRisk.message, {}, risk);
+    }
+    if (risk.defaultDecision === 'audit' && baseDecision !== 'deny') {
+        return result(request, 'allow', risk.reasonCodes.includes('provider_readonly_audit') ? 'provider_readonly_audit' : risk.reasonCodes.includes('allowlisted_verification') ? 'allowlisted_command' : baseReason, baseMessage, {
+            mode: 'audit',
+            auditOnly: true,
+            warnings: risk.reasonCodes.includes('provider_readonly_audit') ? ['provider-readonly-audit-only'] : ['audit-only'],
+        }, risk);
     }
-    return result(request, baseDecision, baseReason, baseMessage);
+    return result(request, baseDecision, baseReason, baseMessage, {}, risk);
 }
 export function isPathInsideWorkspace(workspaceRoot, targetPath) {
     const root = resolve(workspaceRoot);
@@ -148,11 +165,27 @@ function canonicalExistingPath(targetPath) {
 function workspaceBoundaryDecision(request) {
     if (!filesystemCategories.has(request.category))
         return undefined;
+    if (request.category === 'read' && request.workspaceRoot !== undefined && request.targetPath === undefined) {
+        return result(request, 'allow', 'workspace_boundary', 'Broad read-only workspace access is allowed when workspaceRoot is known.', {
+            mode: 'audit',
+            auditOnly: true,
+            boundary: { workspaceRoot: request.workspaceRoot, insideWorkspace: true, targetPathRequired: false },
+            warnings: ['broad-workspace-read'],
+        });
+    }
     if (request.workspaceRoot === undefined || request.targetPath === undefined) {
-        return result(request, 'ask', 'ambiguous_operation', 'Filesystem operation needs workspaceRoot and targetPath before it can be safely decided.');
+        return result(request, 'ask', 'ambiguous_operation', 'Filesystem mutation needs workspaceRoot and targetPath before it can be safely decided.', {
+            boundary: {
+                ...(request.workspaceRoot === undefined ? {} : { workspaceRoot: request.workspaceRoot }),
+                ...(request.targetPath === undefined ? {} : { targetPath: request.targetPath }),
+                targetPathRequired: request.category !== 'read',
+            },
+        });
     }
     if (!isPathInsideWorkspace(request.workspaceRoot, request.targetPath)) {
-        return result(request, 'deny', 'workspace_boundary', `Path escapes workspace boundary: ${request.targetPath}`);
+        return result(request, 'deny', 'workspace_boundary', `Path escapes workspace boundary: ${request.targetPath}`, {
+            boundary: { workspaceRoot: request.workspaceRoot, targetPath: request.targetPath, insideWorkspace: false, targetPathRequired: true },
+        });
     }
     return undefined;
 }
@@ -162,7 +195,9 @@ function workspaceEscapeDecision(request) {
     if (request.workspaceRoot === undefined || request.targetPath === undefined)
         return undefined;
     if (!isPathInsideWorkspace(request.workspaceRoot, request.targetPath)) {
-        return result(request, 'deny', 'workspace_boundary', `Path escapes workspace boundary: ${request.targetPath}`);
+        return result(request, 'deny', 'workspace_boundary', `Path escapes workspace boundary: ${request.targetPath}`, {
+            boundary: { workspaceRoot: request.workspaceRoot, targetPath: request.targetPath, insideWorkspace: false, targetPathRequired: true },
+        });
     }
     return undefined;
 }
@@ -212,6 +247,37 @@ function riskDecision(request) {
         return { decision: 'ask', reason: 'ambiguous_operation', message: 'Ambiguous operations require human approval.' };
     return undefined;
 }
+function hardRiskDecision(request, risk) {
+    if (request.category === 'shell' && /\b(arbitrary|shell-string)\b|[;&|`$()]/.test(request.operation))
+        return result(request, 'deny', 'risk_tier_policy', 'Arbitrary shell execution is denied unless represented as an allowlisted category.', {}, risk);
+    if (risk.defaultDecision === 'deny')
+        return result(request, 'deny', 'risk_tier_policy', 'Risk classifier denies this operation by default.', {}, risk);
+    return undefined;
+}
+function explicitValidationDecision(request, risk) {
+    if (!risk.requiresExplicitValidation)
+        return undefined;
+    if (request.category === 'secrets')
+        return undefined;
+    return result(request, 'ask', reasonForRisk(request, risk), 'Risk tier policy requires explicit validation before this operation.', {}, risk);
+}
+function reasonForRisk(request, risk) {
+    if (risk.reasonCodes.includes('provider_config_write'))
+        return 'risk_tier_policy';
+    if (risk.reasonCodes.includes('git_write'))
+        return 'risk_tier_policy';
+    if (risk.reasonCodes.includes('publish_release'))
+        return 'risk_tier_policy';
+    if (request.destructive === true)
+        return 'destructive_operation';
+    if (request.external === true)
+        return 'external_operation';
+    if (request.privileged === true)
+        return 'privileged_operation';
+    if (request.ambiguous === true)
+        return 'ambiguous_operation';
+    return 'risk_tier_policy';
+}
 function isLessRestrictive(candidate, floor) {
     return rank(candidate) < rank(floor);
 }
@@ -222,6 +288,17 @@ function rank(decision) {
         return 1;
     return 2;
 }
-function result(request, decision, reason, message, extras = {}) {
-    return { decision, category: request.category, operation: request.operation, reason, message, ...extras };
+function result(request, decision, reason, message, extras = {}, risk = classifyOperationRisk(request)) {
+    return {
+        decision,
+        category: request.category,
+        operation: request.operation,
+        reason,
+        message,
+        riskTier: risk.tier,
+        riskReasonCodes: risk.reasonCodes,
+        ...(request.workflow === undefined ? {} : { workflow: request.workflow }),
+        auditEvidence: risk.evidence,
+        ...extras,
+    };
 }

package/dist/runs/execution-planning.js

@@ -107,5 +107,5 @@ const defaultGitBoundaryInspector = ({ workspaceRoot }) => {
     if (existsSync(join(workspaceRoot, '.git'))) {
         return { status: 'compatible', reason: 'workspace git metadata is present' };
     }
-    return { status: 'uncertain', reason: 'workspace git metadata could not be proven safe without shell execution' };
+    return { status: 'compatible', reason: 'workspace has no git metadata to conflict with a planned worktree boundary' };
 };

package/dist/runs/run-service.js

@@ -233,22 +233,25 @@ export class RunService {
         };
     }
     planOperationExecution(input) {
-        const permission = this.evaluatePermissionForRun(input);
+        const resolved = this.buildPermissionContextForRun(input);
+        if (!resolved.ok)
+            return resolved;
+        const permission = this.evaluatePermissionForRun(resolved.value);
         if (!permission.ok)
             return permission;
         const plan = planExecutionIsolation({
-            operation: input,
+            operation: resolved.value,
             decision: permission.value.decision,
-            ...(input.gitBoundaryInspector === undefined ? {} : { gitBoundaryInspector: input.gitBoundaryInspector }),
+            ...(resolved.value.gitBoundaryInspector === undefined ? {} : { gitBoundaryInspector: resolved.value.gitBoundaryInspector }),
         });
         const sandboxDecision = sandboxDecisionSummary(plan.sandbox);
         const planEvent = this.runs.appendEvent({
-            runId: input.runId,
+            runId: resolved.value.runId,
             kind: 'execution-plan',
-            title: `Execution plan: ${input.category} ${input.operation}`,
+            title: `Execution plan: ${resolved.value.category} ${resolved.value.operation}`,
             payload: {
-                runId: input.runId,
-                requestedOperation: operationMetadata(input),
+                runId: resolved.value.runId,
+                requestedOperation: operationMetadata(resolved.value),
                 decisionEventId: permission.value.event.id,
                 approvalId: permission.value.approval?.id ?? null,
                 plan: plan,
@@ -262,17 +265,20 @@ export class RunService {
                 timestamp: new Date().toISOString(),
             },
             relatedType: 'operation',
-            relatedId: input.operation,
+            relatedId: resolved.value.operation,
         });
         if (!planEvent.ok)
             return { ok: false, error: planEvent.error };
         return { ok: true, value: { ...permission.value, plan, planEvent: planEvent.value } };
     }
     preflightOperation(input) {
-        const metadataValidation = this.validateVgxManagedPreflightMetadata(input);
+        const resolved = this.buildPermissionContextForRun(input);
+        if (!resolved.ok)
+            return resolved;
+        const metadataValidation = this.validateVgxManagedPreflightMetadata(resolved.value);
         if (!metadataValidation.ok)
             return metadataValidation;
-        const planned = this.planOperationExecution(input);
+        const planned = this.planOperationExecution(resolved.value);
         if (!planned.ok)
             return planned;
         const { decision, event, approval, plan, planEvent } = planned.value;
@@ -283,7 +289,7 @@ export class RunService {
         const sandboxRejected = sandbox?.decision === 'rejected';
         const sandboxReason = sandboxRejected ? [{ code: sandbox.reason ?? 'sandbox_boundary', message: sandbox.audit.validationSummary }] : [];
         const outcome = sandboxRejected ? 'blocked' : preflightOutcome(decision);
-        this.appendPreflightAuditEvent(input, outcome, {
+        this.appendPreflightAuditEvent(resolved.value, outcome, {
             permissionEventId: event.id,
             planEventId: planEvent.id,
             ...(approval === undefined ? {} : { approvalId: approval.id }),
@@ -313,14 +319,14 @@ export class RunService {
         const details = this.runs.getDetails(approval.value.runId);
         if (!details.ok)
             return details;
-        const permissionEvent = details.value.events.find((event) => event.id === approval.value.decisionEventId);
+        const pendingExecutionEvent = details.value.events.find((event) => isPendingExecutionEventForApproval(event, approval.value.id));
+        if (pendingExecutionEvent === undefined)
+            return validationFailure('Approved approval has no resumable pending operation event');
+        const permissionEvent = permissionEventForPendingExecution(details.value, approval.value, pendingExecutionEvent);
         if (permissionEvent === undefined)
             return validationFailure('Approval permission-decision event is missing');
         if (!isAskPermissionEvent(permissionEvent))
             return validationFailure('Approval is not linked to an ask permission decision');
-        const pendingExecutionEvent = details.value.events.find((event) => isPendingExecutionEventForApproval(event, approval.value.id));
-        if (pendingExecutionEvent === undefined)
-            return validationFailure('Approved approval has no resumable pending operation event');
         const operation = operationFromPendingExecution(pendingExecutionEvent.payload);
         if (operation === undefined)
             return validationFailure('Pending operation metadata is incomplete and cannot be resumed');
@@ -559,14 +565,19 @@ export class RunService {
             : { ok: false, error: executionEvent.error };
     }
     evaluatePermissionForRun(input) {
-        const run = this.runs.getById(input.runId);
+        const resolved = this.buildPermissionContextForRun(input);
+        if (!resolved.ok)
+            return resolved;
+        const inputWithRunContext = resolved.value;
+        const run = this.runs.getById(inputWithRunContext.runId);
         if (!run.ok)
             return { ok: false, error: run.error };
-        const decision = evaluatePermission(input);
+        const contextConflict = workflowConflictDecision(inputWithRunContext, run.value.workflow);
+        const decision = contextConflict ?? evaluatePermission(inputWithRunContext);
         const timestamp = new Date().toISOString();
-        const agent = input.agent === undefined ? { id: run.value.selectedAgentId } : { id: input.agent.id, name: input.agent.name, mode: input.agent.mode };
+        const agent = inputWithRunContext.agent === undefined ? { id: run.value.selectedAgentId } : { id: inputWithRunContext.agent.id, name: inputWithRunContext.agent.name, mode: inputWithRunContext.agent.mode };
         if (decision.decision === 'ask') {
-            const prior = this.findMatchingApproval(input, agent, input.reusePendingApproval === true);
+            const prior = this.findMatchingApproval(inputWithRunContext, agent, inputWithRunContext.reusePendingApproval === true);
             if (!prior.ok)
                 return prior;
             if (prior.value !== undefined) {
@@ -581,17 +592,23 @@ export class RunService {
                             message: `Previously ${prior.value.approval.status} approval ${prior.value.approval.id} denies this exact operation.`,
                         };
                 const event = this.runs.appendEvent({
-                    runId: input.runId,
+                    runId: inputWithRunContext.runId,
                     kind: 'permission-decision',
-                    title: `Permission ${reusedDecision.decision}: ${input.category} ${input.operation}`,
+                    title: `Permission ${reusedDecision.decision}: ${inputWithRunContext.category} ${inputWithRunContext.operation}`,
                     payload: {
-                        runId: input.runId,
-                        category: input.category,
-                        operation: input.operation,
-                        requestedOperation: operationMetadata(input),
+                        runId: inputWithRunContext.runId,
+                        category: inputWithRunContext.category,
+                        operation: inputWithRunContext.operation,
+                        workflow: inputWithRunContext.workflow ?? null,
+                        phase: inputWithRunContext.phase ?? null,
+                        requestedOperation: operationMetadata(inputWithRunContext),
                         agent,
                         decision: reusedDecision.decision,
                         reasons: [{ code: reusedDecision.reason, message: reusedDecision.message }],
+                        riskTier: reusedDecision.riskTier ?? null,
+                        riskReasonCodes: reusedDecision.riskReasonCodes ?? [],
+                        boundary: (reusedDecision.boundary ?? null),
+                        auditEvidence: reusedDecision.auditEvidence ?? [],
                         requiresHumanApproval: reusedDecision.decision === 'ask',
                         approvalStatus: prior.value.approval.status,
                         reusedApprovalId: prior.value.approval.id,
@@ -608,29 +625,35 @@ export class RunService {
             }
         }
         const event = this.runs.appendEvent({
-            runId: input.runId,
+            runId: inputWithRunContext.runId,
             kind: 'permission-decision',
-            title: `Permission ${decision.decision}: ${input.category} ${input.operation}`,
+            title: `Permission ${decision.decision}: ${inputWithRunContext.category} ${inputWithRunContext.operation}`,
             payload: {
-                runId: input.runId,
-                category: input.category,
-                operation: input.operation,
-                requestedOperation: operationMetadata(input),
+                runId: inputWithRunContext.runId,
+                category: inputWithRunContext.category,
+                operation: inputWithRunContext.operation,
+                workflow: inputWithRunContext.workflow ?? null,
+                phase: inputWithRunContext.phase ?? null,
+                requestedOperation: operationMetadata(inputWithRunContext),
                 agent,
                 decision: decision.decision,
                 reasons: [{ code: decision.reason, message: decision.message }],
+                riskTier: decision.riskTier ?? null,
+                riskReasonCodes: decision.riskReasonCodes ?? [],
+                boundary: (decision.boundary ?? null),
+                auditEvidence: decision.auditEvidence ?? [],
                 requiresHumanApproval: decision.decision === 'ask',
                 approvalStatus: decision.decision === 'ask' ? 'pending' : 'not-required',
                 timestamp,
             },
             relatedType: 'permission',
-            relatedId: input.category,
+            relatedId: inputWithRunContext.category,
         });
         if (!event.ok)
             return { ok: false, error: event.error };
         if (decision.decision !== 'ask')
             return { ok: true, value: { decision, event: event.value } };
-        const approval = this.runs.createApproval({ runId: input.runId, decisionEventId: event.value.id });
+        const approval = this.runs.createApproval({ runId: inputWithRunContext.runId, decisionEventId: event.value.id });
         return approval.ok ? { ok: true, value: { decision, event: event.value, approval: approval.value } } : { ok: false, error: approval.error };
     }
     validateVgxManagedPreflightMetadata(input) {
@@ -668,6 +691,19 @@ export class RunService {
         }
         return { ok: true, value: undefined };
     }
+    buildPermissionContextForRun(input) {
+        const run = this.runs.getById(input.runId);
+        if (!run.ok)
+            return { ok: false, error: run.error };
+        const phase = input.phase ?? canonicalRunPhase(run.value.phase);
+        const merged = {
+            ...input,
+            workflow: input.workflow ?? run.value.workflow,
+            ...(phase === undefined ? {} : { phase }),
+            agentId: input.agentId ?? input.agent?.id ?? run.value.selectedAgentId,
+        };
+        return { ok: true, value: merged };
+    }
     appendPreflightAuditEvent(input, outcome, audit) {
         const run = this.runs.getById(input.runId);
         if (!run.ok || !isVgxManagedWorkflow(run.value.workflow) || !isRiskyPermissionCategory(input.category))
@@ -774,6 +810,23 @@ function isVgxManagedWorkflow(workflow) {
     const normalized = workflow.toLowerCase();
     return normalized === 'sdd' || normalized.startsWith('sdd-') || normalized.includes('sdd') || normalized.includes('vgx');
 }
+function workflowConflictDecision(input, runWorkflow) {
+    if (input.workflow === undefined || input.workflow === runWorkflow)
+        return undefined;
+    const eitherSdd = input.workflow === 'sdd' || runWorkflow === 'sdd' || input.workflow.includes('sdd') || runWorkflow.includes('sdd');
+    if (!eitherSdd)
+        return undefined;
+    return {
+        decision: 'ask',
+        category: input.category,
+        operation: input.operation,
+        reason: 'workflow_context',
+        message: `Explicit workflow ${input.workflow} conflicts with run workflow ${runWorkflow}; human validation is required before crossing SDD/non-SDD context.`,
+        workflow: input.workflow,
+        warnings: [`workflow-conflict:${runWorkflow}->${input.workflow}`],
+        auditEvidence: [`runWorkflow:${runWorkflow}`, `explicitWorkflow:${input.workflow}`],
+    };
+}
 function executionPayload(operation, executorName, status, extra) {
     return {
         status,
@@ -830,6 +883,11 @@ function resumeGateManualNextCommands(approval, details, operation) {
         commands.push(`Review operation manually: ${operation.category} ${operation.operation}`);
     return commands;
 }
+function canonicalRunPhase(phase) {
+    if (phase === undefined || phase.trim().length === 0)
+        return undefined;
+    return phase === 'apply' ? 'apply-progress' : phase;
+}
 function operationMetadata(input) {
     const metadata = { category: input.category, name: input.operation };
     if (input.workspaceRoot !== undefined)
@@ -840,6 +898,12 @@ function operationMetadata(input) {
         metadata.providerToolName = input.providerToolName;
     if (input.sandboxStrategy !== undefined)
         metadata.sandboxStrategy = input.sandboxStrategy;
+    if (input.workflow !== undefined)
+        metadata.workflow = input.workflow;
+    if (input.phase !== undefined)
+        metadata.phase = input.phase;
+    if (input.agentId !== undefined)
+        metadata.agentId = input.agentId;
     if (input.destructive !== undefined)
         metadata.destructive = input.destructive;
     if (input.external !== undefined)
@@ -859,7 +923,7 @@ function approvalEventMatches(event, input, requestedOperation, agent) {
         return false;
     if (event.payload.category !== input.category || event.payload.operation !== input.operation)
         return false;
-    if (!jsonEqual(event.payload.requestedOperation, requestedOperation))
+    if (!operationMetadataCompatible(event.payload.requestedOperation, requestedOperation))
         return false;
     if (!jsonEqual(event.payload.agent, agent))
         return false;
@@ -869,7 +933,23 @@ function isMatchingPreflightPlanEvent(event, operation) {
     if (event.kind !== 'execution-plan' || !isObject(event.payload))
         return false;
     const requestedOperation = event.payload.requestedOperation;
-    return requestedOperation !== undefined && jsonEqual(requestedOperation, operationMetadata(operation));
+    return requestedOperation !== undefined && operationMetadataCompatible(requestedOperation, operationMetadata(operation));
+}
+function operationMetadataCompatible(preflightOperation, requestedOperation) {
+    if (preflightOperation === undefined || requestedOperation === undefined)
+        return jsonEqual(preflightOperation, requestedOperation);
+    if (!isObject(preflightOperation) || !isObject(requestedOperation))
+        return jsonEqual(preflightOperation, requestedOperation);
+    if (preflightOperation.category !== requestedOperation.category || preflightOperation.name !== requestedOperation.name)
+        return false;
+    const strictKeys = ['workspaceRoot', 'targetPath', 'providerToolName', 'sandboxStrategy', 'destructive', 'external', 'privileged', 'ambiguous'];
+    for (const key of strictKeys) {
+        if (key in preflightOperation && key in requestedOperation && !jsonEqual(preflightOperation[key], requestedOperation[key]))
+            return false;
+    }
+    if ('input' in preflightOperation && 'input' in requestedOperation && !jsonEqual(preflightOperation.input, requestedOperation.input))
+        return false;
+    return true;
 }
 function preflightPlanStatus(event) {
     if (!isObject(event.payload))
@@ -919,6 +999,12 @@ function isAskPermissionEvent(event) {
 function isPendingExecutionEventForApproval(event, approvalId) {
     return (event.kind === 'operation-execution' && isObject(event.payload) && event.payload.status === 'pending-approval' && event.payload.approvalId === approvalId);
 }
+function permissionEventForPendingExecution(details, approval, pendingExecutionEvent) {
+    const decisionEventId = isObject(pendingExecutionEvent.payload) && typeof pendingExecutionEvent.payload.decisionEventId === 'string'
+        ? pendingExecutionEvent.payload.decisionEventId
+        : approval.decisionEventId;
+    return details.events.find((event) => event.id === decisionEventId) ?? details.events.find((event) => event.id === approval.decisionEventId);
+}
 function operationFromPendingExecution(payload) {
     if (!isObject(payload))
         return undefined;
@@ -955,10 +1041,18 @@ function isObject(value) {
 function isPermissionCategory(value) {
     return (value === 'read' ||
         value === 'edit' ||
+        value === 'implementation-edit' ||
+        value === 'spec-write' ||
+        value === 'design-write' ||
+        value === 'task-write' ||
         value === 'shell' ||
+        value === 'test-run' ||
+        value === 'install' ||
         value === 'network' ||
         value === 'git' ||
+        value === 'git-write' ||
         value === 'memory' ||
+        value === 'memory-write' ||
         value === 'external-directory' ||
         value === 'provider-tool' ||
         value === 'secrets');

package/dist/setup/providers/claude-setup-adapter.js

@@ -1,9 +1,10 @@
+import { planClaudeCodeMcpInstall } from '../../mcp/client-install-claude-code-contract.js';
 import { createMcpClientSetupPreview } from '../../mcp/client-setup-preview.js';
-import { noWriteActionSafety } from './provider-setup-adapter.js';
+import { externalProviderWriteSafety, noWriteActionSafety } from './provider-setup-adapter.js';
 export const claudeSetupAdapter = {
     id: 'claude',
     displayName: 'Claude',
-    supportLevel: 'supported-secondary',
+    supportLevel: 'supported',
     capabilities: ['mcp-preview', 'mcp-install-plan', 'cli-mcp-plan', 'agent-preview', 'doctor', 'manual-guidance'],
     targets: [
         { kind: 'project-config', label: 'Project .mcp.json', path: '.mcp.json', writableBySetup: false },
@@ -14,10 +15,11 @@ export const claudeSetupAdapter = {
         { kind: 'user-config', label: 'User Claude memory', path: '~/.claude/CLAUDE.md', writableBySetup: false },
     ],
     getStatus(context) {
+        const plan = this.getInstallPlan?.(context);
         return {
             providerId: 'claude',
-            status: 'supported-secondary',
-            summary: 'Claude is supported as a secondary, non-default provider for CLI MCP registration planning/apply, project .mcp.json compatibility, guarded CLAUDE.md memory, user ~/.claude.json MCP merge, and project/user agents; explicit guarded apply is required for writes or CLI execution.',
+            status: plan?.status === 'blocked' ? 'blocked' : 'available',
+            summary: 'Claude provider setup is available for CLI MCP registration planning/apply, project .mcp.json compatibility, guarded CLAUDE.md memory, user ~/.claude.json MCP merge, and project/user agents; explicit guarded apply is required for writes or CLI execution.',
             evidence: context.databasePath !== undefined
                 ? ['Claude MCP preview can be generated from the selected database path.']
                 : ['Claude MCP preview uses a placeholder until a database path is selected.'],
@@ -27,9 +29,10 @@ export const claudeSetupAdapter = {
                     id: 'claude-manual-guidance',
                     label: 'Review guarded Claude install guidance',
                     kind: 'manual-guidance',
-                    description: 'Supported secondary guidance only in setup status; writes are available only through the guarded mcp install claude flow with run preflight metadata.',
+                    description: 'Claude install guidance only in setup status; writes are available only through the guarded mcp install claude flow with run preflight metadata.',
                     safety: noWriteActionSafety,
                 },
+                ...(plan?.actions ?? []),
             ],
         };
     },
@@ -48,4 +51,44 @@ export const claudeSetupAdapter = {
             warnings: preview.warnings,
         };
     },
+    getInstallPlan(context) {
+        const contract = planClaudeCodeMcpInstall({
+            cwd: context.workspaceRoot,
+            databasePath: context.databasePath ?? '<database-path>',
+            ...(context.databasePathSource !== undefined ? { databasePathSource: context.databasePathSource } : {}),
+            scope: 'project',
+            ...(context.env !== undefined ? { env: context.env } : {}),
+            ...(context.overwriteVgxness !== undefined ? { overwriteVgxness: context.overwriteVgxness } : {}),
+        });
+        return claudeInstallPlan(context, contract);
+    },
 };
+function claudeInstallPlan(_context, contract) {
+    const actions = contract.status === 'would_install' ? [externalInstallAction(contract.targetPath, contract.overwriteVgxness)] : [];
+    return {
+        providerId: 'claude',
+        status: contract.status === 'would_install' ? 'available' : 'blocked',
+        readOnly: true,
+        mutating: false,
+        writesProviderConfig: false,
+        summary: contract.status === 'would_install'
+            ? 'Claude project install plan is available for external guarded application; the read-only setup status does not write provider config.'
+            : contract.message,
+        targetPath: contract.targetPath,
+        warnings: contract.warnings,
+        actions,
+        source: contract,
+    };
+}
+function externalInstallAction(targetPath, overwriteVgxness = false) {
+    return {
+        id: 'claude-mcp-install-project',
+        label: 'Copy external Claude project install command',
+        kind: 'copy-command',
+        command: ['vgxness', 'mcp', 'install', 'claude', '--scope', 'project', '--yes', ...(overwriteVgxness ? ['--overwrite-vgxness'] : [])],
+        description: overwriteVgxness
+            ? 'Copy and run this outside setup status only after reviewing that VGXNESS entries will be overwritten and unrelated config preserved.'
+            : 'Copy and run this outside setup status only after reviewing the read-only plan.',
+        safety: externalProviderWriteSafety(targetPath),
+    };
+}

package/dist/setup/providers/opencode-setup-adapter.js

@@ -5,7 +5,7 @@ import { externalProviderWriteSafety, noWriteActionSafety, } from './provider-se
 export const openCodeSetupAdapter = {
     id: 'opencode',
     displayName: 'OpenCode',
-    supportLevel: 'supported-primary',
+    supportLevel: 'supported',
     capabilities: ['mcp-preview', 'mcp-install-plan', 'mcp-install-apply-external', 'agent-preview', 'doctor', 'visibility-check'],
     targets: [
         { kind: 'user-config', label: 'User/global OpenCode config (default)', path: '$HOME/.config/opencode/opencode.json', writableBySetup: false },
@@ -19,7 +19,7 @@ export const openCodeSetupAdapter = {
             status: visibility?.ready === true ? 'ready' : 'available',
             summary: visibility?.ready === true
                 ? 'OpenCode MCP visibility is ready.'
-                : 'OpenCode is the supported primary provider; install/apply remains external and explicit.',
+                : 'OpenCode provider setup is available; install/apply remains external and explicit.',
             evidence: visibility?.evidence ?? ['OpenCode setup preview and install planning are available.'],
             guidance: visibility?.guidance ?? ['Preview setup first, then copy and run external install commands only after review.'],
             actions: plan?.actions ?? [],

package/dist/setup/providers/provider-setup-adapter.js

@@ -1,3 +1,6 @@
+export function isSupportedProviderLevel(level) {
+    return level === 'supported' || level === 'supported-primary' || level === 'supported-secondary';
+}
 export const noWriteActionSafety = {
     mutating: false,
     writesProviderConfig: false,

package/dist/setup/setup-lifecycle-service.js

@@ -1,3 +1,4 @@
+import { isSupportedProviderLevel } from './providers/provider-setup-adapter.js';
 import { listProviderSetupAdapters } from './providers/provider-setup-registry.js';
 const agentName = 'vgxness-manager';
 export class SetupLifecycleService {
@@ -151,7 +152,7 @@ function verificationSummary(environment, project, providers, agents, mcp) {
         {
             id: 'providers',
             label: 'Providers',
-            status: providers.some((provider) => provider.supportLevel === 'supported-primary') ? 'ready' : 'unknown',
+            status: providers.some((provider) => isSupportedProviderLevel(provider.supportLevel)) ? 'ready' : 'unknown',
             detail: `${providers.length} provider targets are available for read-only setup status.`,
         },
         {

package/dist/setup/setup-plan.js

@@ -87,7 +87,7 @@ export function createSetupPlan(input) {
                 actions: [
                     {
                         id: 'claude-guarded-install',
-                        description: `Review supported secondary Claude plan for CLI MCP registration, .mcp.json compatibility, ${claude.agentNames.length} .claude/agents/*.md file(s), and guarded project-root CLAUDE.md managed block; apply only with vgxness mcp install claude --scope project --yes --run-id <id>.`,
+                        description: `Review first-class supported Claude plan for CLI MCP registration, .mcp.json compatibility, ${claude.agentNames.length} .claude/agents/*.md file(s), and guarded project-root CLAUDE.md managed block; apply only with vgxness mcp install claude --scope project --yes --run-id <id>.`,
                         mutating: false,
                         targetPath,
                         backupRequired: claude.backupRequired,
@@ -100,7 +100,7 @@ export function createSetupPlan(input) {
                     targetPath: target.path,
                     reason: target.kind === 'project-memory' ? 'A future guarded Claude apply would create a managed VGXNESS backup before appending or updating the project-root CLAUDE.md managed block.' : 'A future guarded Claude apply would create a managed VGXNESS backup before merging or updating Claude project configuration.',
                 })),
-                nextCommands: ['vgxness mcp install claude --plan --scope project', 'vgxness mcp install claude --scope project --yes --run-id <id>', 'OpenCode remains the default/primary provider.'],
+                nextCommands: ['vgxness mcp install claude --plan --scope project', 'vgxness mcp install claude --scope project --yes --run-id <id>', 'OpenCode remains the default guided setup provider.'],
             },
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {