vgxness 1.20.9 → 1.20.11

package/dist/application/code-context/code-context-service.js

@@ -133,7 +133,7 @@ export class CodeContextService {
                 workspaceRoot,
                 recommendedCommands: [
                     'codegraph init # optional: create/update CodeGraph index outside VGXNESS',
-                    'graphify --path . --output graphify-out # optional: create/update Graphify graph outside VGXNESS',
+                    'graphify update . --force --no-cluster # optional: create/update Graphify code graph outside VGXNESS',
                 ],
                 safety: { ...codeContextSafety },
                 summary: '[read-only] Advisory plan only. VGXNESS does not install packages, initialize indexes, register external MCP servers, or write provider config.',
@@ -156,7 +156,7 @@ function providerLabel(provider) {
     return provider === 'codegraph' ? 'CodeGraph' : 'Graphify';
 }
 function queryArgs(provider, mode, question) {
-    return provider === 'codegraph' ? [mode, question] : ['query', '--mode', mode, question];
+    return provider === 'codegraph' ? [mode, question] : ['query', question];
 }
 function firstNonEmpty(...values) {
     return values.find((value) => value.trim().length > 0)?.trim() ?? '';
@@ -185,7 +185,7 @@ function runBoundedCommand(request) {
         shell: false,
         encoding: 'utf8',
         timeout: request.timeoutMs,
-        maxBuffer: request.maxBytes,
+        maxBuffer: maxMaxBytes,
         stdio: ['ignore', 'pipe', 'pipe'],
         ...(request.env === undefined ? {} : { env: request.env }),
     };

package/dist/application/code-context/providers/status-probes.js

@@ -18,7 +18,7 @@ export const graphifyProviderDefinition = {
     reportRelativePath: join('graphify-out', 'GRAPH_REPORT.md'),
     setupGuidance: [
         'Install Graphify explicitly if desired: pipx install graphifyy',
-        'Generate graph output only after approval: graphify <workspace>',
+        'Generate graph output only after approval: graphify update <workspace> --force --no-cluster',
     ],
 };
 export const codeContextProviderDefinitions = [codegraphProviderDefinition, graphifyProviderDefinition];

package/dist/application/runs/parallel-agent-batch-service.js

@@ -0,0 +1,85 @@
+import { parallelAgentBatchCategories, parallelAgentBatchDefaultMaxConcurrency, parallelAgentBatchHardMaxConcurrency, parallelAgentBatchMaxTasks, } from '../../domain/runs/parallel-agent-batch.js';
+const requiredSynthesis = {
+    required: true,
+    includeEvidence: true,
+    includeConflicts: true,
+    includeFailures: true,
+    includeResidualRisk: true,
+    includeNextAction: true,
+};
+export class ParallelAgentBatchService {
+    defaultMaxConcurrency;
+    hardMaxConcurrency;
+    allowedAgentNames;
+    constructor(options = {}) {
+        this.hardMaxConcurrency = options.hardMaxConcurrency ?? parallelAgentBatchHardMaxConcurrency;
+        this.defaultMaxConcurrency = options.defaultMaxConcurrency ?? parallelAgentBatchDefaultMaxConcurrency;
+        this.allowedAgentNames = options.allowedAgentNames === undefined ? undefined : new Set(options.allowedAgentNames);
+    }
+    validatePlan(plan) {
+        const issues = [];
+        const warnings = [];
+        const maxConcurrency = plan.maxConcurrency ?? this.defaultMaxConcurrency;
+        if (!isValidConcurrency(maxConcurrency, this.hardMaxConcurrency))
+            issues.push({
+                code: 'invalid-concurrency',
+                message: `maxConcurrency must be an integer between 1 and ${this.hardMaxConcurrency}; received ${String(maxConcurrency)}`,
+            });
+        if (!isValidConcurrency(this.defaultMaxConcurrency, this.hardMaxConcurrency))
+            issues.push({
+                code: 'invalid-concurrency',
+                message: `defaultMaxConcurrency must be an integer between 1 and ${this.hardMaxConcurrency}; received ${String(this.defaultMaxConcurrency)}`,
+            });
+        if (!Array.isArray(plan.tasks) || plan.tasks.length === 0)
+            issues.push({ code: 'invalid-task-count', message: 'parallel batch must contain at least one task' });
+        else if (plan.tasks.length > parallelAgentBatchMaxTasks)
+            issues.push({ code: 'invalid-task-count', message: `parallel batch cannot exceed ${parallelAgentBatchMaxTasks} tasks` });
+        if (plan.tasks.length > 0 && plan.tasks.length <= maxConcurrency)
+            warnings.push('task count does not exceed concurrency; batch may finish in a single wave');
+        if (!hasRequiredSynthesisContract(plan.synthesis))
+            issues.push({ code: 'invalid-synthesis-contract', message: 'synthesis contract must require evidence, conflicts, failures, residual risk, and next action' });
+        const taskIds = new Set(plan.tasks.map((task) => task.id).filter((id) => id.trim().length > 0));
+        for (const task of plan.tasks)
+            this.validateTask(task, taskIds, issues);
+        if (issues.length > 0)
+            return { ok: false, issues, warnings };
+        return { ok: true, value: { ...plan, maxConcurrency }, warnings };
+    }
+    validateTask(task, taskIds, issues) {
+        requireTrimmed(task.id, 'id', task.id, issues);
+        requireTrimmed(task.agentName, 'agentName', task.id, issues);
+        requireTrimmed(task.workspaceRoot, 'workspaceRoot', task.id, issues);
+        requireTrimmed(task.scopeSummary, 'scopeSummary', task.id, issues);
+        requireTrimmed(task.independenceRationale, 'independenceRationale', task.id, issues);
+        if (task.allowedTools.length === 0)
+            issues.push({ code: 'missing-field', taskId: task.id, message: 'allowedTools must name at least one permitted tool' });
+        if (!parallelAgentBatchCategories.includes(task.category))
+            issues.push({ code: 'unknown-category', taskId: task.id, message: `unsupported category: ${task.category}` });
+        if (this.allowedAgentNames !== undefined && !this.allowedAgentNames.has(task.agentName))
+            issues.push({ code: 'unknown-agent', taskId: task.id, message: `agent is not allowlisted: ${task.agentName}` });
+        if (task.recursiveDelegationAllowed === true)
+            issues.push({ code: 'recursive-delegation', taskId: task.id, message: 'subagents must not be allowed to launch subagents recursively' });
+        for (const dependency of task.dependsOn ?? []) {
+            if (taskIds.has(dependency))
+                issues.push({ code: 'dependent-task', taskId: task.id, message: `task depends on same-batch task ${dependency}; run these serially instead` });
+        }
+        if (task.riskTier !== 'read-only' && task.requiresPreflight !== true)
+            issues.push({ code: 'risky-preflight-required', taskId: task.id, message: 'risky or mutating tasks require preflight' });
+        if (task.category === 'implementation') {
+            if ((task.targetPaths ?? []).filter((path) => path.trim().length > 0).length === 0)
+                issues.push({ code: 'implementation-scope-required', taskId: task.id, message: 'implementation tasks must declare independent target paths or scopes' });
+            if (task.requiresPreflight !== true)
+                issues.push({ code: 'implementation-preflight-required', taskId: task.id, message: 'implementation tasks require preflight before launch' });
+        }
+    }
+}
+function isValidConcurrency(value, hardMaxConcurrency) {
+    return Number.isInteger(value) && value >= 1 && value <= hardMaxConcurrency;
+}
+function requireTrimmed(value, field, taskId, issues) {
+    if (value.trim().length === 0)
+        issues.push({ code: 'missing-field', taskId, message: `${field} is required` });
+}
+function hasRequiredSynthesisContract(value) {
+    return Object.entries(requiredSynthesis).every(([key, expected]) => value[key] === expected);
+}

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

@@ -2,7 +2,7 @@ import { canonicalBehaviorContractVersion } from '../../behavior/behavior-contra
 export const canonicalDefaultAgentName = 'vgxness-manager';
 export const canonicalOpenCodeDefaultModel = 'openai/gpt-5.5';
 export const canonicalOpenCodeManagerReasoningEffort = 'high';
-export const canonicalPromptContractVersion = 24;
+export const canonicalPromptContractVersion = 25;
 export const canonicalSddSubagentNames = [
     'vgxness-sdd-explore',
     'vgxness-sdd-propose',
@@ -79,7 +79,7 @@ function managerDefinition() {
         name: canonicalDefaultAgentName,
         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: registryManagerInstructionsV11 },
-        capabilities: ['sdd-orchestration', 'agent-routing', 'mcp-coordination', 'project-local-automation', 'coordination', 'workflow-selection', 'resume'],
+        capabilities: ['sdd-orchestration', 'agent-routing', 'parallel-agent-delegation', 'mcp-coordination', 'project-local-automation', 'coordination', 'workflow-selection', 'resume'],
         permissions: { read: 'allow', edit: 'ask', shell: 'ask', git: 'ask', memory: 'allow', 'provider-tool': 'deny', secrets: 'deny' },
         memory: { scopes: ['project'] },
         workflows: ['explore', 'quickfix', 'plan', 'build', 'debug', 'sdd', 'agent-seeding', 'opencode-install'],
@@ -161,6 +161,7 @@ export function createCanonicalOpenCodeSddMcpToolPermissions() {
         vgxness_opencode_manager_payload: 'allow',
         vgxness_run_list: 'allow',
         vgxness_run_get: 'allow',
+        vgxness_run_parallel_batch_validate: 'allow',
         vgxness_run_start: 'allow',
         vgxness_run_checkpoint: 'allow',
         vgxness_run_preflight: 'allow',
@@ -209,6 +210,9 @@ This prompt is the VGXNESS operating contract; OpenCode also appends environment
 Use the lightest safe path; do not force SDD/subagents for small direct work. T0 answer/status, T1 inspect/read-only, T2 small direct edit/command, T3 preflighted risky action, T4 SDD only for phase-shaped product/architecture/large/multi-step changes. For small concrete changes, execute directly with normal verification and preflight only when risky. Do not create SDD artifacts, runs, or subagents just because code changes are involved.
 Do not invent or invoke generic reviewer subagents; use exact canonical SDD subagents only when the task is truly SDD-shaped or the user asks for SDD.
 
+## Parallel delegation
+When work has independent analysis, verification, research, codebase investigation, debugging, code review, SDD drafting/review, or context-dependent implementation streams, create a bounded parallel batch instead of serializing by habit. Default max concurrency is 3 subagents; honor configured lower/higher limits only within validated safety caps. Launch only exact allowlisted subagents/roles, never wildcard or unknown agents, and never allow recursive delegation. Stay serial when tasks depend on each other, scope is unclear, the result of one task chooses the next task, or the cost/noise exceeds the benefit. For implementation fan-out, require independent paths/scopes plus preflight/human gates for risky mutations, destructive actions, publish, merge, provider config, privileged scope, secrets, or external roots. Each launched subagent gets bounded instructions: task, workspace, allowed tools, expected evidence, no recursive delegation, and concise result envelope. Before reporting completion, synthesize every result with evidence, conflicts, failures/timeouts, residual risk, and the chosen next serial action.
+
 ## Provider-native daily flow
 SDD happens in OpenCode conversation + VGXNESS MCP/subagents. No terminal SDD phase commands. CLI is an escape hatch for bootstrap, doctor, recovery, setup gaps, or explicit request.
 
@@ -250,7 +254,7 @@ Be concise.`;
  */
 const registryManagerInstructionsV11 = [
     'You are the VGXNESS manager/coordinator, not a monolithic executor and not an SDD-only bot. Coach briefly while coordinating: explain useful tradeoffs, be realistic about risks and unknowns, respectfully challenge weak assumptions with better options, keep the user comfortable and in control, and stay concise. Always verify before agreeing with technical claims; when blocked, ask one focused question and stop.',
-    'Default to direct inline execution for small concrete user requests, narrow edits, single-file fixes, docs updates, simple commands, and focused verification. When a user starts a new project/product/app or brings an undeveloped idea, run a preparation phase first: clarify goals, users, scope, constraints, stack, repo/location, integrations, data, security, deliverables, milestones, success criteria, and desired PRD/requirements/design/tasks/roadmap artifacts; offer 2-4 options when provider UI supports choices. Delegate only when scope is SDD phase-shaped, broad repository exploration, complex implementation, incident recovery, or multi-step analysis that benefits from an exact focused executor. When uncertain, narrow scope first; use exact SDD subagents only if the work is genuinely phase-shaped. do not invent or invoke generic reviewer subagents; use exact canonical SDD subagents or MCP guidance only.',
+    'Default to direct inline execution for small concrete user requests, narrow edits, single-file fixes, docs updates, simple commands, and focused verification. When a user starts a new project/product/app or brings an undeveloped idea, run a preparation phase first: clarify goals, users, scope, constraints, stack, repo/location, integrations, data, security, deliverables, milestones, success criteria, and desired PRD/requirements/design/tasks/roadmap artifacts; offer 2-4 options when provider UI supports choices. Delegate only when scope is SDD phase-shaped, broad repository exploration, complex implementation, incident recovery, multi-step analysis, or independent workstreams that benefit from parallel subagents. When the task can split into independent analysis, verification, research, debugging, code review, SDD drafting/review, or context-dependent implementation streams, plan a bounded parallel batch with default max concurrency 3 and configurable validated caps. Launch exact allowlisted subagents only; never wildcard, unknown agents, or recursive delegation. Keep implementation fan-out gated by independent paths/scopes plus preflight/human approval for risky mutations, destructive actions, publish, merge, provider config, privileged scope, secrets, or external roots. Synthesize all subagent results with evidence, conflicts, failures, residual risk, and next action before reporting completion. When uncertain, narrow scope first; use exact SDD subagents only if the work is genuinely phase-shaped. do not invent or invoke generic reviewer subagents; use exact canonical SDD subagents or MCP guidance only.',
     'Use VGXNESS MCP as the durable control plane: for generic resume/continue prompts call vgxness_resume_context first, pass explicitChange only when the user gave an exact valid change, and do not infer a change from context_cockpit.memoryPreviews; for retrospective/status prompts such as "what did we do?" or "qué habíamos hecho", inspect recent completed run history first with vgxness_run_list completed and mention interrupted candidates only as old blockers, not as latest truth; vgxness_context_cockpit and vgxness_session_restore are advisory context only after the gate, and context cockpit previews, memoryPreviews, and SDD summaries are advisory only. Close/pause/compact with vgxness_session_close using actor manager plus an actionable summary when a current session id exists.',
     'For generic continue/sigamos/continuemos/resume development without an explicit user change, call vgxness_resume_context before any SDD status/continuation. If decision is proceed-explicit-change or proceed-single-active-work, then call SDD tools for that change. If inspect-interrupted-run, call vgxness_run_resume_inspect. If ask-change (no interrupted run, no exact user-specified change, and no single parsed active-work change), hard stop: do not call vgxness_agent_resolve; do not call vgxness_sdd_status or vgxness_sdd_continue, do not create runs, do not inspect repo files/native repo tools, do not delegate to SDD subagents, do not start runs, do not use skill_index/skill_search fallback, or invent agent ids; ask one question: "¿qué cambio retomamos?".',
     'Manager save-then-accept behavior: after a valid hidden phase subagent artifact, save it immediately as a draft with sdd_save_artifact, summarize the saved draft, then ask whether the human accepts it and wants to continue to the next phase. An affirmative continue/sí/yes/dale reply in that immediate context is explicit human acceptance. A reply of only save/no/revise keeps draft and must not advance. Never silently auto-accept.',

package/dist/domain/runs/parallel-agent-batch.js

@@ -0,0 +1,13 @@
+export const parallelAgentBatchDefaultMaxConcurrency = 3;
+export const parallelAgentBatchHardMaxConcurrency = 8;
+export const parallelAgentBatchMaxTasks = 20;
+export const parallelAgentBatchCategories = [
+    'analysis',
+    'verification',
+    'research',
+    'sdd',
+    'codebase-investigation',
+    'debugging',
+    'code-review',
+    'implementation',
+];

package/dist/interfaces/cli/commands/code-context-dispatcher.js

@@ -51,7 +51,7 @@ export function runCodeContextCommand(command, parsed, environment) {
         kind: 'code-context-setup-plan',
         version: 1,
         workspaceRoot,
-        recommendedCommands: ['codegraph init # optional: run manually outside VGXNESS', 'graphify --path . --output graphify-out # optional: run manually outside VGXNESS'],
+        recommendedCommands: ['codegraph init # optional: run manually outside VGXNESS', 'graphify update . --force --no-cluster # optional: run manually outside VGXNESS'],
         safety: { ...codeContextSafety },
         summary: '[read-only] Advisory plan only. VGXNESS does not install packages, initialize indexes, register external MCP servers, or write provider config.',
     };

package/dist/interfaces/mcp/control-plane/handlers/runs.js

@@ -1,3 +1,4 @@
+import { ParallelAgentBatchService } from '../../../../application/runs/parallel-agent-batch-service.js';
 import { AgentMemoryCaptureService } from '../../../../memory/agent-memory-capture-service.js';
 import { errorEnvelope, successEnvelope, } from '../../schema.js';
 function toEnvelope(tool, result) {
@@ -13,6 +14,39 @@ export function runListEnvelope(input, services) {
 export function runGetEnvelope(input, services) {
     return toEnvelope('vgxness_run_get', services.runs.getRun(input.id));
 }
+export function runParallelBatchValidateEnvelope(input) {
+    const options = {};
+    if (input.defaultMaxConcurrency !== undefined)
+        options.defaultMaxConcurrency = input.defaultMaxConcurrency;
+    if (input.hardMaxConcurrency !== undefined)
+        options.hardMaxConcurrency = input.hardMaxConcurrency;
+    if (input.allowedAgentNames !== undefined)
+        options.allowedAgentNames = input.allowedAgentNames;
+    const service = new ParallelAgentBatchService(options);
+    const { defaultMaxConcurrency: _defaultMaxConcurrency, hardMaxConcurrency: _hardMaxConcurrency, allowedAgentNames: _allowedAgentNames, ...plan } = input;
+    const validation = service.validatePlan(plan);
+    return successEnvelope('vgxness_run_parallel_batch_validate', {
+        kind: 'parallel-agent-batch-validation',
+        version: 1,
+        validation,
+        launchGuidance: {
+            launchSurface: 'opencode-native-delegate',
+            mcpExecutesSubagents: false,
+            nextStep: validation.ok
+                ? 'Use OpenCode native delegate/task launch for the validated subagent tasks, respecting maxConcurrency and synthesis requirements.'
+                : 'Fix validation issues before launching subagents.',
+        },
+        safety: {
+            readOnly: true,
+            validatesOnly: true,
+            launchesSubagents: false,
+            invokesProvider: false,
+            writesProviderConfig: false,
+            mutatesRunState: false,
+            mutatesSddArtifacts: false,
+        },
+    });
+}
 export function runPreflightEnvelope(input, services) {
     return toEnvelope('vgxness_run_preflight', services.runs.preflightOperation(input));
 }

package/dist/interfaces/mcp/control-plane.js

@@ -23,7 +23,7 @@ import { codeContextStatusEnvelope } from './control-plane/handlers/code-context
 import { contextCockpitEnvelope, resumeContextEnvelope } from './control-plane/handlers/context.js';
 import { memoryGetEnvelope, memorySaveEnvelope, memorySearchEnvelope, memoryUpdateEnvelope } from './control-plane/handlers/memory.js';
 import { providerChangePlanEnvelope, providerDoctorEnvelope, providerStatusEnvelope } from './control-plane/handlers/providers.js';
-import { runCheckpointEnvelope, runFinalizeEnvelope, runGetEnvelope, runListEnvelope, runPreflightEnvelope, runResumeCandidatesEnvelope, runResumeGateEnvelope, runResumeInspectEnvelope, runStartEnvelope, runTaskGrantCreateEnvelope, runTaskGrantGetEnvelope, runTaskGrantListEnvelope, runTaskGrantPreviewMatchEnvelope, runTaskGrantRevokeEnvelope, } from './control-plane/handlers/runs.js';
+import { runCheckpointEnvelope, runFinalizeEnvelope, runGetEnvelope, runListEnvelope, runParallelBatchValidateEnvelope, runPreflightEnvelope, runResumeCandidatesEnvelope, runResumeGateEnvelope, runResumeInspectEnvelope, runStartEnvelope, runTaskGrantCreateEnvelope, runTaskGrantGetEnvelope, runTaskGrantListEnvelope, runTaskGrantPreviewMatchEnvelope, runTaskGrantRevokeEnvelope, } from './control-plane/handlers/runs.js';
 import { governanceReportEnvelope, sddAcceptArtifactEnvelope, sddCockpitEnvelope, sddContinueEnvelope, sddGetArtifactEnvelope, sddGetReadinessEnvelope, sddListArtifactsEnvelope, sddNextEnvelope, sddReadyEnvelope, sddReopenArtifactEnvelope, sddSaveArtifactEnvelope, sddStatusEnvelope, } from './control-plane/handlers/sdd.js';
 import { sessionAppendActivityEnvelope, sessionCloseEnvelope, sessionRestoreEnvelope, sessionStartEnvelope } from './control-plane/handlers/sessions.js';
 import { skillActivateEnvelope, skillCreateDraftEnvelope, skillGetEnvelope, skillGetEvaluationEnvelope, skillIndexEnvelope, skillListEvaluationsEnvelope, skillListImprovementProposalsEnvelope, skillPayloadEnvelope, skillProposeImprovementEnvelope, skillPublishVersionEnvelope, skillRecordUsageEnvelope, skillRequestEvaluationEnvelope, skillSearchEnvelope, skillStatusEnvelope, skillUpdateDraftEnvelope, } from './control-plane/handlers/skills.js';
@@ -127,6 +127,8 @@ export function callVgxTool(call, services) {
             return runListEnvelope(validated.input, services);
         case 'vgxness_run_get':
             return runGetEnvelope(validated.input, services);
+        case 'vgxness_run_parallel_batch_validate':
+            return runParallelBatchValidateEnvelope(validated.input);
         case 'vgxness_run_preflight':
             return runPreflightEnvelope(validated.input, services);
         case 'vgxness_run_task_grant_create':

package/dist/interfaces/mcp/schema.js

@@ -48,6 +48,7 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_opencode_handoff_preview',
     'vgxness_run_list',
     'vgxness_run_get',
+    'vgxness_run_parallel_batch_validate',
     'vgxness_run_preflight',
     'vgxness_run_task_grant_create',
     'vgxness_run_task_grant_list',
@@ -112,6 +113,7 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'opencode_handoff_preview',
     'run_list',
     'run_get',
+    'run_parallel_batch_validate',
     'run_preflight',
     'run_task_grant_create',
     'run_task_grant_list',

package/dist/interfaces/mcp/schemas/inputs/runs.js

@@ -1,5 +1,33 @@
 import { z } from 'zod';
 import { agentModes, explicitRequestInputSchema, finalRunStatuses, jsonValueSchema, permissionCategories, runOutcomes, runStatuses, taskGrantCategories, taskGrantCommandPolicyInputSchema, taskGrantHumanActorInputSchema, taskGrantRevocationActorInputSchema, taskGrantStatuses, workflowIds, } from '../common.js';
+const parallelBatchCategories = ['analysis', 'verification', 'research', 'sdd', 'codebase-investigation', 'debugging', 'code-review', 'implementation'];
+const parallelBatchRiskTiers = ['read-only', 'risky', 'mutation'];
+const parallelBatchSynthesisSchema = z
+    .object({
+    required: z.literal(true),
+    includeEvidence: z.literal(true),
+    includeConflicts: z.literal(true),
+    includeFailures: z.literal(true),
+    includeResidualRisk: z.literal(true),
+    includeNextAction: z.literal(true),
+})
+    .strict();
+const parallelBatchTaskSchema = z
+    .object({
+    id: z.string().min(1),
+    category: z.enum(parallelBatchCategories),
+    agentName: z.string().min(1),
+    workspaceRoot: z.string().min(1),
+    allowedTools: z.array(z.string().min(1)).min(1),
+    scopeSummary: z.string().min(1),
+    independenceRationale: z.string().min(1),
+    riskTier: z.enum(parallelBatchRiskTiers),
+    requiresPreflight: z.boolean(),
+    targetPaths: z.array(z.string().min(1)).optional(),
+    dependsOn: z.array(z.string().min(1)).optional(),
+    recursiveDelegationAllowed: z.boolean().optional(),
+})
+    .strict();
 export const RUNS_MCP_TOOL_INPUT_SCHEMAS = {
     vgxness_run_list: z
         .object({
@@ -13,6 +41,16 @@ export const RUNS_MCP_TOOL_INPUT_SCHEMAS = {
         id: z.string().min(1),
     })
         .passthrough(),
+    vgxness_run_parallel_batch_validate: z
+        .object({
+        maxConcurrency: z.number().int().min(1).optional(),
+        defaultMaxConcurrency: z.number().int().min(1).optional(),
+        hardMaxConcurrency: z.number().int().min(1).optional(),
+        allowedAgentNames: z.array(z.string().min(1)).optional(),
+        tasks: z.array(parallelBatchTaskSchema).min(1),
+        synthesis: parallelBatchSynthesisSchema,
+    })
+        .strict(),
     vgxness_run_preflight: z
         .object({
         runId: z.string().min(1),

package/dist/interfaces/mcp/validation/runs.js

@@ -30,6 +30,123 @@ export function validateRunGetInput(input, tool) {
         return id;
     return { ok: true, value: { id: id.value } };
 }
+const parallelBatchCategories = ['analysis', 'verification', 'research', 'sdd', 'codebase-investigation', 'debugging', 'code-review', 'implementation'];
+const parallelBatchRiskTiers = ['read-only', 'risky', 'mutation'];
+export function validateRunParallelBatchValidateInput(input, tool) {
+    const record = inputRecord(input, tool, [
+        'maxConcurrency',
+        'defaultMaxConcurrency',
+        'hardMaxConcurrency',
+        'allowedAgentNames',
+        'tasks',
+        'synthesis',
+    ]);
+    if (!record.ok)
+        return record;
+    const result = {};
+    for (const field of ['maxConcurrency', 'defaultMaxConcurrency', 'hardMaxConcurrency']) {
+        if (record.value[field] === undefined)
+            continue;
+        if (!Number.isInteger(record.value[field]) || record.value[field] < 1)
+            return validationFailure(`${field} must be a positive integer`, tool);
+        result[field] = record.value[field];
+    }
+    const allowedAgentNames = readOptionalStringArray(record.value, 'allowedAgentNames', tool);
+    if (!allowedAgentNames.ok)
+        return allowedAgentNames;
+    if (allowedAgentNames.value !== undefined)
+        result.allowedAgentNames = allowedAgentNames.value;
+    const tasks = readParallelBatchTasks(record.value.tasks, tool);
+    if (!tasks.ok)
+        return tasks;
+    result.tasks = tasks.value;
+    const synthesis = readParallelBatchSynthesis(record.value.synthesis, tool);
+    if (!synthesis.ok)
+        return synthesis;
+    result.synthesis = synthesis.value;
+    return { ok: true, value: result };
+}
+function readParallelBatchTasks(value, tool) {
+    if (!Array.isArray(value) || value.length === 0)
+        return validationFailure('tasks must be a non-empty array', tool);
+    const tasks = [];
+    for (const [index, item] of value.entries()) {
+        const record = asRecord(item, tool, `tasks[${index}] must be an object`);
+        if (!record.ok)
+            return record;
+        const unexpected = Object.keys(record.value).find((key) => !['id', 'category', 'agentName', 'workspaceRoot', 'allowedTools', 'scopeSummary', 'independenceRationale', 'riskTier', 'requiresPreflight', 'targetPaths', 'dependsOn', 'recursiveDelegationAllowed'].includes(key));
+        if (unexpected !== undefined)
+            return validationFailure(`Unexpected tasks[${index}] field: ${unexpected}`, tool);
+        const id = readNonEmptyString(record.value, 'id', tool);
+        if (!id.ok)
+            return id;
+        const category = readRequiredOneOf(record.value, 'category', parallelBatchCategories, tool);
+        if (!category.ok)
+            return category;
+        const agentName = readNonEmptyString(record.value, 'agentName', tool);
+        if (!agentName.ok)
+            return agentName;
+        const workspaceRoot = readNonEmptyString(record.value, 'workspaceRoot', tool);
+        if (!workspaceRoot.ok)
+            return workspaceRoot;
+        const allowedTools = readRequiredStringArray(record.value, 'allowedTools', tool);
+        if (!allowedTools.ok)
+            return allowedTools;
+        const scopeSummary = readNonEmptyString(record.value, 'scopeSummary', tool);
+        if (!scopeSummary.ok)
+            return scopeSummary;
+        const independenceRationale = readNonEmptyString(record.value, 'independenceRationale', tool);
+        if (!independenceRationale.ok)
+            return independenceRationale;
+        const riskTier = readRequiredOneOf(record.value, 'riskTier', parallelBatchRiskTiers, tool);
+        if (!riskTier.ok)
+            return riskTier;
+        if (typeof record.value.requiresPreflight !== 'boolean')
+            return validationFailure('requiresPreflight must be a boolean', tool);
+        const task = {
+            id: id.value,
+            category: category.value,
+            agentName: agentName.value,
+            workspaceRoot: workspaceRoot.value,
+            allowedTools: allowedTools.value,
+            scopeSummary: scopeSummary.value,
+            independenceRationale: independenceRationale.value,
+            riskTier: riskTier.value,
+            requiresPreflight: record.value.requiresPreflight,
+        };
+        const targetPaths = readOptionalStringArray(record.value, 'targetPaths', tool);
+        if (!targetPaths.ok)
+            return targetPaths;
+        if (targetPaths.value !== undefined)
+            task.targetPaths = targetPaths.value;
+        const dependsOn = readOptionalStringArray(record.value, 'dependsOn', tool);
+        if (!dependsOn.ok)
+            return dependsOn;
+        if (dependsOn.value !== undefined)
+            task.dependsOn = dependsOn.value;
+        if (record.value.recursiveDelegationAllowed !== undefined) {
+            if (typeof record.value.recursiveDelegationAllowed !== 'boolean')
+                return validationFailure('recursiveDelegationAllowed must be a boolean', tool);
+            task.recursiveDelegationAllowed = record.value.recursiveDelegationAllowed;
+        }
+        tasks.push(task);
+    }
+    return { ok: true, value: tasks };
+}
+function readParallelBatchSynthesis(value, tool) {
+    const record = asRecord(value, tool, 'synthesis must be an object');
+    if (!record.ok)
+        return record;
+    const required = ['required', 'includeEvidence', 'includeConflicts', 'includeFailures', 'includeResidualRisk', 'includeNextAction'];
+    const unexpected = Object.keys(record.value).find((key) => !required.includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected synthesis field: ${unexpected}`, tool);
+    for (const field of required) {
+        if (record.value[field] !== true)
+            return validationFailure(`synthesis.${field} must be true`, tool);
+    }
+    return { ok: true, value: record.value };
+}
 export function validateRunPreflightInput(input, tool) {
     const record = inputRecord(input, tool, [
         'runId',

package/dist/interfaces/mcp/validation.js

@@ -5,7 +5,7 @@ import { asRecord, readString, toValidationResultFailure, validationFailure, val
 import { validateGovernanceReportInput } from './validation/governance.js';
 import { validateMemoryGetInput, validateMemorySaveInput, validateMemorySearchInput, validateMemoryUpdateInput } from './validation/memory.js';
 import { validateProviderChangePlanInput, validateProviderHealthInput } from './validation/providers.js';
-import { validateRunCheckpointInput, validateRunFinalizeInput, validateRunGetInput, validateRunListInput, validateRunPreflightInput, validateRunResumeCandidatesInput, validateRunResumeGateInput, validateRunResumeInspectInput, validateRunStartInput, validateRunTaskGrantCreateInput, validateRunTaskGrantGetInput, validateRunTaskGrantListInput, validateRunTaskGrantPreviewMatchInput, validateRunTaskGrantRevokeInput, } from './validation/runs.js';
+import { validateRunCheckpointInput, validateRunFinalizeInput, validateRunGetInput, validateRunListInput, validateRunParallelBatchValidateInput, validateRunPreflightInput, validateRunResumeCandidatesInput, validateRunResumeGateInput, validateRunResumeInspectInput, validateRunStartInput, validateRunTaskGrantCreateInput, validateRunTaskGrantGetInput, validateRunTaskGrantListInput, validateRunTaskGrantPreviewMatchInput, validateRunTaskGrantRevokeInput, } from './validation/runs.js';
 import { validateContextCockpitInput, validateResumeContextInput, validateSddAcceptArtifactInput, validateSddCockpitInput, validateSddContinueInput, validateSddGetArtifactInput, validateSddGetReadinessInput, validateSddListArtifactsInput, validateSddNextInput, validateSddReadyInput, validateSddReopenArtifactInput, validateSddSaveArtifactInput, validateSddStatusInput, } from './validation/sdd.js';
 import { validateSessionAppendActivityInput, validateSessionCloseInput, validateSessionRestoreInput, validateSessionStartInput, } from './validation/sessions.js';
 import { validateSkillActivateInput, validateSkillCreateDraftInput, validateSkillGetEvaluationInput, validateSkillGetInput, validateSkillIndexInput, validateSkillListEvaluationsInput, validateSkillListImprovementProposalsInput, validateSkillPayloadInput, validateSkillProposeImprovementInput, validateSkillPublishVersionInput, validateSkillRecordUsageInput, validateSkillRequestEvaluationInput, validateSkillSearchInput, validateSkillStatusInput, validateSkillUpdateDraftInput, } from './validation/skills.js';
@@ -113,6 +113,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateRunListInput(input, tool.value));
         case 'vgxness_run_get':
             return validationSuccess(tool.value, validateRunGetInput(input, tool.value));
+        case 'vgxness_run_parallel_batch_validate':
+            return validationSuccess(tool.value, validateRunParallelBatchValidateInput(input, tool.value));
         case 'vgxness_run_preflight':
             return validationSuccess(tool.value, validateRunPreflightInput(input, tool.value));
         case 'vgxness_run_task_grant_create':

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP tools
 
-VGXNESS exposes 43 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
+VGXNESS exposes 63 typed MCP tools over stdio through `vgxness mcp start`. The canonical list is the `SUPPORTED_VGX_MCP_TOOL_NAMES` array in `src/mcp/schema.ts` — treat that as the source of truth. The list below mirrors it; if a tool appears here that is not in the array, or vice versa, the array wins.
 
 Tools are exposed under the `vgxness_*` prefix. Some MCP hosts strip the prefix and accept the short form (`sdd_status`, `memory_save`, etc.). The schema accepts both.
 
@@ -83,12 +83,13 @@ Payload tools that accept `agentId` resolve it as a canonical registry id first.
 | `vgxness_opencode_manager_payload` | Build the OpenCode manager payload envelope. | `OpenCodeManagerPayloadInput` shape (project, scope, agent, workflow/phase, workspaceRoot, maxSourceBytes, payloadMode) | `installable: false`, `readOnly: true`. |
 | `vgxness_opencode_handoff_preview` | Compose a full handoff preview: provider artifacts + skill diagnostics + SDD status + provider status + safety flags. | `project`; optional `scope`, `agentId`, `agentName`, `workspaceRoot`, `maxSourceBytes`, `change`, `phase` | Read-only preview. Does not execute OpenCode, install hooks, write provider config, or capture memory candidates. |
 
-## Runs (9)
+## Runs (15)
 
 | Tool | Purpose | Required inputs | Notes |
 |---|---|---|---|
 | `vgxness_run_list` | List runs with filters. | `limit`; optional `project`, `status` (one of the 8 `RunStatus` values) | |
 | `vgxness_run_get` | Read a run with `events`, `checkpoints`, `approvals`, `operationAttempts`. | `id` | |
+| `vgxness_run_parallel_batch_validate` | Validate a bounded parallel subagent batch plan before provider-native launch. | `tasks`, `synthesis`; optional `maxConcurrency`, `defaultMaxConcurrency`, `hardMaxConcurrency`, `allowedAgentNames` | Read-only validation surface. Default concurrency is 3 unless configured. Does not launch subagents, invoke providers, mutate runs, or write SDD artifacts; it returns launch guidance for OpenCode native delegation. |
 | `vgxness_run_start` | Create a run record. | `CreateRunInput` shape | |
 | `vgxness_run_checkpoint` | Append a resumable JSON state. | `AppendRunCheckpointInput` shape | |
 | `vgxness_run_finalize` | Finalize a run with `outcome` and `outcomeReason`. | `FinalizeRunInput` shape | `outcome` must match a terminal `status`. Re-finalization is rejected. May return advisory `memoryCapture` candidates from bounded finalization fields; candidates are not persisted automatically. |
@@ -161,6 +162,20 @@ vgxness_run_finalize    { runId, outcome: "success", outcomeReason: "..." }
 
 `vgxness_run_preflight` output includes `workspaceStrategy` with one of `current-checkout`, `branch`, `manual-worktree`, or `stacked-prs`. This is advisory planning metadata only. Its execution guarantees are always non-mutating (`createsBranch:false`, `createsWorktree:false`, `createsPullRequest:false`, `mutatesRepository:false`, `mutatesProviderConfig:false`). Treat `manual-worktree` and `stacked-prs` as instructions for a human or future executor to arrange review/isolation deliberately before mutation, not as evidence that VGXNESS already created Git state.
 
+Validating a parallel subagent batch before provider-native launch:
+
+```text
+vgxness_run_parallel_batch_validate {
+  maxConcurrency: 3,
+  tasks: [
+    { id, category: "analysis", agentName, workspaceRoot, allowedTools, scopeSummary, independenceRationale, riskTier: "read-only", requiresPreflight: false }
+  ],
+  synthesis: { required: true, includeEvidence: true, includeConflicts: true, includeFailures: true, includeResidualRisk: true, includeNextAction: true }
+}
+```
+
+`vgxness_run_parallel_batch_validate` is a guardrail, not an executor. It checks batch size, configured concurrency, independent tasks, allowlisted agents, no recursive delegation, implementation preflight requirements, and synthesis obligations. When validation succeeds, the manager may use the provider's native subagent/delegation capability (for example OpenCode native delegation) while respecting the validated `maxConcurrency`. MCP itself does not launch or monitor those subagents.
+
 Finding interrupted runs when the run id is unknown:
 
 ```text
@@ -177,6 +192,7 @@ MCP tools do not:
 
 - Write project-local provider config (`.opencode/`, `.mcp.json`, `.claude/`, project-root `CLAUDE.md`). VGX-managed OpenCode and Claude writes are user-global only and must stay behind explicit install/apply confirmation outside read-only status/preview tools.
 - Execute providers (`opencode`, `claude`, etc.).
+- Launch subagents. Parallel subagent launch is provider-native after `vgxness_run_parallel_batch_validate` succeeds; MCP validates only.
 - Install global memory.
 - Persist `memoryCapture` lifecycle candidates automatically or use them as proof of SDD acceptance, readiness, verification, approval, or authorization.
 - Create `openspec/`.

package/docs/safety.md

@@ -68,6 +68,20 @@ The experimental `vgxness code` runtime approval flow was removed with `src/code
 
 The gateway is conservative by default: a non-`read` tool in a non-`apply-progress` phase defaults to `ask`. Even with `--approval-policy allow`, the gateway can re-promote to `ask` for risky categories or workspace boundary issues.
 
+## Parallel subagent delegation
+
+Parallel delegation is provider-native, not an MCP executor. The manager may decide to fan out independent analysis, verification, research, review, debugging, SDD drafting/review, or context-scoped implementation work, but the plan should pass through `vgxness_run_parallel_batch_validate` first when using the VGXNESS MCP control plane.
+
+`vgxness_run_parallel_batch_validate` is read-only and validates only:
+
+- default concurrency is 3 unless a smaller/larger bounded value is configured;
+- every task must declare category, agent, workspace root, allowed tools, scope, independence rationale, risk tier, and preflight requirement;
+- same-batch dependencies and recursive delegation are rejected;
+- implementation tasks require target paths and preflight declaration;
+- synthesis must include evidence, conflicts, failures, residual risk, and next action.
+
+The MCP tool does not launch subagents, invoke providers, mutate run state, write artifacts, or monitor provider-native executions. OpenCode or another provider performs the actual subagent launch after validation, and normal preflight/approval rules still apply to risky or mutating work.
+
 ## Task-scoped external command grants
 
 Task-scoped command grants are a narrow V1 escape hatch for a human to authorize a bounded external working directory for an allowlisted command preflight. They only convert an eligible `ask` decision to an audited `allow`; they never convert `deny` or hard-risk requests to `allow`, and apply/implementation work still requires the normal SDD governance gates.

package/package.json

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