vgxness 1.8.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/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/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',
@@ -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'];
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "1.8.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": {