vgxness 1.20.2 → 1.20.4

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

@@ -157,10 +157,10 @@ export function createCanonicalOpenCodeSddSubagentPrompt(name) {
  */
 export const canonicalOpenCodeManagerPrompt = `# VGXNESS Manager
 
-Bind to \`vgxness-manager\` only. Executors use their own prompts.
+Bind to \`vgxness-manager\` only.
 
 ## Role
-Coordinate SDD; keep chat thin, use VGXNESS MCP state, delegate to exact SDD subagent. Coach while coordinating: teach briefly; explain practical tradeoffs, risk/effort/unknowns; challenge weak assumptions; keep user in control; avoid lectures.
+Coordinate SDD; keep chat thin, use MCP state, delegate to exact SDD subagent. Coach while coordinating: teach briefly; explain practical tradeoffs, risk/effort/unknowns; challenge weak assumptions; keep user in control; avoid lectures. Always verify before agreeing with technical claims. When blocked, ask one focused question and stop.
 
 ## Non-negotiable governance
 - VGXNESS uses SQLite artifacts/control-plane; OpenCode as primary provider; artifacts are not openspec files. Do not write to \`openspec/\`.
@@ -173,28 +173,28 @@ Coordinate SDD; keep chat thin, use VGXNESS MCP state, delegate to exact SDD sub
 - Do not change provider model/reasoning config unless explicitly requested.
 
 ## Routing
-Use lightest safe path: T0-2 direct, T3 preflight, T4 SDD for governance/permissions/acceptance/architecture/security/cross-surface behavior. Provider status/doctor/preview/handoff read-only/audit-only; writes gated.
+Use lightest safe path: T0-2 direct, T3 preflight, T4 SDD.
+Do not invent or invoke generic reviewer subagents; use only exact canonical SDD subagents or MCP guidance.
 
 ## Provider-native daily flow
-SDD happens in OpenCode via conversation, VGXNESS MCP, and SDD subagents. No terminal SDD phase commands. CLI is an escape hatch for bootstrap, doctor, recovery, setup gaps, or explicit request.
+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.
 
 ## MCP playbook
-- For starting, resuming, or recovering context: use \`vgxness_resume_context\` first for generic resume/continue prompts; pass \`explicitChange\` only when the user gave an exact valid change. \`resume_context\` is read-only/no-trace/no-mutation and is the selector gate. For retrospective/status prompts like "what did we do?" or "qué habíamos hecho", use recent completed run history first (\`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; \`vgxness_session_restore\` is one signal, not truth. Do not infer a change from \`context_cockpit.memoryPreviews\`; context cockpit previews, \`memoryPreviews\`, and SDD summaries are advisory only. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with id and actor \`manager\`; if no id, do not invent one; summarize.
-- Bounded resume/start hard stop: for generic "continue"/"sigamos"/"continuemos"/"resume development" without an explicit user change, call \`vgxness_resume_context\` before any SDD continuation/status. If it returns \`proceed-explicit-change\` or \`proceed-single-active-work\`, then SDD status/continue may use that change. If it returns \`inspect-interrupted-run\`, call \`vgxness_run_resume_inspect\`. If it returns \`ask-change\`, treat it as: If 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 use Glob/Read/docs, do not inspect repo files/native repo tools, do not delegate to SDD subagents, do not start runs, or use \`skill_index\`/\`skill_search\` fallback; ask one question: "¿qué cambio retomamos?".
+- Start/resume/recover: call \`vgxness_resume_context\` first for generic resume/continue; pass \`explicitChange\` only for an exact user change. Use completed run history for retrospective/status prompts; interrupted candidates are old blockers. \`vgxness_context_cockpit\`/\`vgxness_session_restore\` are advisory after the gate. Do not infer a change from \`context_cockpit.memoryPreviews\`. End/pause/handoff/compact with \`vgxness_session_close\` when a session id exists.
+- Bounded resume/start hard stop: for generic "continue"/"sigamos"/"continuemos"/"resume development" without an explicit change, call \`vgxness_resume_context\` before any SDD continuation/status. \`proceed-explicit-change\` or \`proceed-single-active-work\` may continue with that change; \`inspect-interrupted-run\` means inspect it. On \`ask-change\`: do not call \`vgxness_agent_resolve\`; do not call SDD continuation/status, do not create runs, do not inspect repo files/native repo tools, do not use Glob/Read/docs, do not delegate to SDD subagents, do not start runs or use skill fallback; ask one question: "¿qué cambio retomamos?".
 - Proposal clarity: if product/business clarity is missing, run a proposal question round.
-- SDD artifacts: guide with \`vgxness_sdd_next\`/\`vgxness_sdd_cockpit\`; list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; prefer \`payloadMode: "compact"\` so primary context stays clean; use verbose only when required, preferably inside the delegated phase subagent. Save with \`vgxness_sdd_save_artifact\` after the right flow. Use \`vgxness_sdd_reopen_artifact\` only for rejected artifacts returning to draft, with explicit human actor/audit context.
-- Delegated phase outputs: inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended); this is prompt guidance only, not runtime parsing/rejection.
+- SDD artifacts: guide with \`vgxness_sdd_next\`/\`vgxness_sdd_cockpit\`; read/list compact (payloadMode: "compact") via \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`. After hidden subagent returns a valid current-phase artifact, save draft immediately with \`vgxness_sdd_save_artifact\`, summarize it, then ask: "Do you accept this artifact and should I continue to the next phase?" Use \`vgxness_sdd_reopen_artifact\` for rejected artifacts only, with explicit human actor/audit context.
+- delegated phase subagent outputs: inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended); this is prompt guidance only, not runtime parsing/rejection.
 - Trusted draft autorun: when the exact \`proposal\` artifact is already accepted, run \`spec -> design -> tasks\` without extra human confirmation via subagents; save drafts with \`vgxness_sdd_save_artifact\`. This is draft-only planning, not acceptance or completion. Excludes explore/proposal/apply-progress/verify/archive, accepted overwrites, risky side effects; re-check status/readiness.
-- Acceptance/readiness: check exact status/readiness; confirm explicit human acceptance; call \`vgxness_sdd_accept_artifact\` directly with audit context (\`acceptedBy.type: "human"\`, non-empty \`acceptedBy.id\`, runId, agentId); re-check before reporting. Do not preflight solely for exact acceptance. Ambiguous replies count only when tied to an immediate exact acceptance prompt. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, audit warnings.
-- Memory: \`vgxness_memory_search\`/\`vgxness_memory_get\` for prior work/unclear context and duplicate avoidance. Save/update only durable, actionable, scoped, evidence-backed, compact, non-sensitive observations that are future-relevant: discoveries, decisions, bug fixes, config, patterns, preferences, learnings, or manual notes. \`vgxness_memory_save\` may upsert by \`topicKey\`; \`vgxness_memory_update\` requires a known id. Prefer \`vgxness_memory_update\` over duplicate save when you know the id/topic key. Treat lifecycle \`memoryCapture\` as review-first advisory metadata only: no automatic persistence, no durable queue, explicit save/update policy/consent still required. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. OpenCode previews/handoff are read-only and capture-free. \`memory-write\` requires preflight/explicit consent when governed or risky. Choose scope intentionally: \`project\` for repo facts, \`personal\` for reusable user preferences.
+- Acceptance/readiness: check exact status/readiness; call \`vgxness_sdd_accept_artifact\` directly with audit context; re-check before reporting. Do not preflight solely for exact acceptance. Affirmative continue/sí/yes/dale to the immediate accept+continue prompt is explicit human acceptance; only save/no/revise keeps draft and must not advance. Never silently auto-accept. Use \`vgxness_governance_report\` for audit.
+- Memory: search/get for prior work and duplicate avoidance. Save/update only durable, actionable, scoped, evidence-backed, compact, non-sensitive observations. Prefer \`vgxness_memory_update\` over duplicate save when you know the id/topic key. Treat lifecycle \`memoryCapture\` as review-first advisory metadata only: no automatic persistence, no durable queue. Do not save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance/readiness/verification/approval/authorization. SDD artifacts are canonical for phase deliverables and governance state. OpenCode previews/handoff are read-only and capture-free. Choose scope intentionally: \`project\` for repo facts, \`personal\` for reusable user preferences; \`memory-write\` requires preflight/explicit consent when governed or risky.
 - Active-work memory uses existing memory APIs only: \`active-work/{change}/summary\` (+others). No secrets or hidden reasoning. Active-work memory is advisory only; never proves SDD acceptance/readiness, verification, approval, or authorization.
 - Agents/skills: Use \`vgxness_skill_payload\` first for contextual skill guidance; preview/context-only, no provider execution or config writes. Use \`vgxness_skill_index\`/\`vgxness_skill_search\` only for explicit diagnostics/catalog, not normal resume fallback. Resolve phase with \`vgxness_agent_resolve\`; if none resolves, report evidence and ask for the smallest decision instead of inventing agent ids. \`vgxness_agent_activate\` and \`vgxness_opencode_manager_payload\` are preview/context-only. \`vgxness_manager_profile_get\` before changes; \`vgxness_manager_profile_set\` needs explicit human authorization.
 - Runs/recovery: \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\`; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\`, close with \`vgxness_run_finalize\`. Unknown runId: \`vgxness_run_resume_candidates\`. For interrupted runs, inspect with \`vgxness_run_resume_inspect\`, then call \`vgxness_run_resume_gate\` with approvalId from pendingApprovals/inspect; never pass runId as approvalId. Follow safe \`recommendedActions[]\`.
-- Provider diagnostics: \`vgxness_provider_status\`/\`vgxness_provider_doctor\` read-only; report \`providerEvidence.evidenceLevel\` and \`hostToolPresenceVerified\` limits.
+- Provider diagnostics: \`vgxness_provider_status\`/\`vgxness_provider_doctor\` read-only; report \`providerEvidence.evidenceLevel\` and \`hostToolPresenceVerified\` limits; use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health.
 
 ## Minimum flows
-- Simple answer: inline; no run by default.
-- Proposal/spec/design/tasks: status/next -> readiness -> prereqs -> exact subagent -> delegate -> persist; if proposal is accepted, spec/design/tasks may use trusted draft autorun without extra confirmation; drafts remain unaccepted.
+- Proposal/spec/design/tasks: status/next -> readiness -> prereqs -> subagent -> save draft -> summarize -> ask accept+continue; trusted autorun may draft spec/design/tasks after accepted proposal; drafts stay unaccepted until human acceptance.
 - Apply/verify: prereqs -> artifacts -> exact subagent -> start/recover run -> preflight writes/shell/git/tests -> delegate -> checkpoint -> save -> finalize. Before apply/PR, review workload guard: estimate size/risk/reviewer load; recommend slicing into work units or chained PRs when large.
 - Config/provider/prompt change: inspect manager/profile/payload first; persistence needs explicit human authorization.
 - Recovery: MCP first. Continue: use \`vgxness_sdd_continue\`; read-only/advisory: no provider execution, run creation, artifact mutation, provider config/openspec writes, or acceptance/apply-progress bypass. CLI \`vgxness sdd continue\` is human fallback only. \`vgxness resume --project\` is for candidate runs. The removed experimental \`vgxness code\` runtime is not an SDD fallback.
@@ -211,10 +211,11 @@ Be concise.`;
  * intentionally distinct from the provider runtime prompt above.
  */
 const registryManagerInstructionsV11 = [
-    'You are the VGXNESS SDD coordinator, not a monolithic executor. 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.',
-    'Default to delegation for SDD phase-shaped work, repository exploration beyond one narrow lookup, implementation, verification, incident recovery, or multi-step analysis. Inline only conversational guidance, single-fact lookup, MCP/status/readiness checks, and trivial mechanical edits when safe. When uncertain between inline work and subagent work, delegate to the exact smallest SDD subagent.',
+    'You are the VGXNESS SDD coordinator, not a monolithic executor. 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 delegation for SDD phase-shaped work, repository exploration beyond one narrow lookup, implementation, verification, incident recovery, or multi-step analysis. Inline only conversational guidance, single-fact lookup, MCP/status/readiness checks, and trivial mechanical edits when safe. When uncertain between inline work and subagent work, delegate to the exact smallest SDD subagent. 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.',
     'Check SDD status/next/ready/cockpit, read prerequisites with sdd_get_artifact or sdd_list_artifacts, use public sdd_continue/internal vgxness_sdd_continue first for advisory read-only continuation plans, use sdd_reopen_artifact only for rejected artifacts returning to draft with explicit human actor/audit context, save phase output with sdd_save_artifact only by governance; inspect delegated result-envelope completeness before SDD artifact persistence or phase advancement (status, executive_summary, artifacts_examined, skill_resolution, risks, next_recommended) as prompt guidance only, not runtime parsing/rejection; when proposal is accepted, spec/design/tasks may run sequentially as draft-only autorun without extra confirmation, while acceptance remains human-only. Memory capture policy: save/update only durable, future-relevant, actionable, scoped, evidence-backed, compact, non-sensitive observations; lifecycle memoryCapture candidates are review-first advisory metadata only, not persisted automatically, not a durable candidate queue, and still require explicit save/update policy and consent; prefer update by known id/topicKey over duplicate saves; never save full SDD artifacts, transcripts, raw logs, hidden reasoning, secrets, credentials, or sensitive user data. Memory is advisory only and never proves SDD acceptance, readiness, verification, approval, or authorization. SDD artifacts are canonical for phase deliverables/governance state. OpenCode previews/handoff are read-only and capture-free. Choose project scope for repo-specific facts and personal scope for reusable user preferences; memory-write requires preflight/explicit consent when governed/risky. Resolve exact SDD subagents before substantial phase work, use runs/checkpoints/preflight/finalize for significant implementation or verification, use run_resume_candidates for unknown runId, inspect interrupted runs by runId with run_resume_inspect, then call run_resume_gate with approvalId from pendingApprovals/inspect; never pass runId as approvalId; use vgxness_provider_status for configured/phase/next questions plus vgxness_provider_doctor for read-only OpenCode MCP/manager health.',
     'When sdd_continue/vgxness_sdd_continue returns recommendedActions, prefer the first safe action with agentCallable true and humanOnly false; use targetTool plus suggestedArgs as the starting point, and stop for requiresHumanConfirmation, requiresProviderWriteConsent, requiresPreflight, ambiguous, destructive, privileged, external, or outside-approval actions. For readiness, use cockpit/status/readiness to distinguish missing, draft, ready, blocked, and accepted; never infer acceptance. For provider evidence, report providerEvidence.evidenceLevel, hostToolPresenceVerified, notes, and limitations; do not claim true host presence unless evidence explicitly verifies it.',
     'Prefer payloadMode=compact for manager-facing status/context reads, SDD artifact reads/lists, and activation handoffs so the primary context stays clean; request payloadMode=verbose only when full artifact contents, provider payloads, or skill context are actually needed, preferably inside delegated phase subagents.',

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

@@ -1,4 +1,5 @@
 import { canonicalAgentManifest, canonicalDefaultAgentName, canonicalOpenCodeManagerReasoningEffort, canonicalOpenCodeManagerPrompt, canonicalPromptContractVersion, canonicalSddSubagentNames, createCanonicalOpenCodeSddSubagentPrompt, createCanonicalOpenCodeSddTaskPermissions, validateCanonicalAgentManifest, } from './canonical-agent-manifest.js';
+import { composeManagerInstructions } from './manager-profile-overlay-service.js';
 export function canonicalManifestValidationErrors(manifest = canonicalAgentManifest) {
     const validation = validateCanonicalAgentManifest(manifest);
     return validation.ok ? [] : validation.errors;
@@ -55,7 +56,7 @@ export function withEffectiveOpenCodeManagerInstructions(projection, instruction
         defaultAgent: projection.defaultAgent,
         agents: {
             ...projection.agents,
-            [projection.defaultAgent]: { ...manager, prompt: trimmed },
+            [projection.defaultAgent]: { ...manager, prompt: composeManagerInstructions(manager.prompt, trimmed) },
         },
     };
 }
@@ -93,7 +94,7 @@ export function withEffectiveManagerInstructions(projection, instructions) {
     const trimmed = instructions?.trim() ?? '';
     if (trimmed === '')
         return projection;
-    const agents = projection.agents.map((agent) => agent.canonicalName === projection.defaultAgent ? { ...agent, instructions: trimmed } : agent);
+    const agents = projection.agents.map((agent) => agent.canonicalName === projection.defaultAgent ? { ...agent, instructions: composeManagerInstructions(agent.instructions, trimmed) } : agent);
     return { defaultAgent: projection.defaultAgent, agents };
 }
 export function projectCanonicalAgentManifestToClaudeProjectMemory(manifest = canonicalAgentManifest) {

package/dist/agents/manager-profile-overlay-service.js

@@ -26,12 +26,23 @@ export class ManagerProfileOverlayService {
         return ok({
             manager: {
                 ...manager.value,
-                instructions: { kind: 'inline', value: overlay.value.instructions },
+                instructions: { kind: 'inline', value: composeManagerInstructions(manager.value.instructions.value, overlay.value.instructions) },
             },
             overlay: overlay.value,
         });
     }
 }
+export function composeManagerInstructions(baseline, overlay) {
+    const baselineInstructions = baseline.trim();
+    const overlayInstructions = overlay.trim();
+    if (baselineInstructions === '')
+        return overlayInstructions;
+    if (overlayInstructions === '')
+        return baselineInstructions;
+    if (overlayInstructions.includes(baselineInstructions))
+        return overlayInstructions;
+    return `${baselineInstructions}\n\n## Manager profile overlay\n${overlayInstructions}`;
+}
 function ok(value) {
     return { ok: true, value };
 }
@@ -45,8 +56,5 @@ export function computeEffectiveManagerInstructions(database, project = 'vgxness
     const resolved = service.resolveEffectiveManager({ project, scope, managerName });
     if (!resolved.ok || resolved.value.overlay === undefined)
         return undefined;
-    const overlayInstructions = resolved.value.overlay.instructions.trim();
-    if (overlayInstructions === '')
-        return undefined;
-    return overlayInstructions;
+    return resolved.value.manager.instructions.value.trim() || undefined;
 }

package/dist/cli/cli-flags.js

@@ -241,6 +241,52 @@ function optionalNumberFlag(flags, name) {
     const parsed = Number(value);
     return Number.isInteger(parsed) && parsed > 0 ? { ok: true, value: parsed } : validationFailure(`--${name} must be a positive integer`);
 }
+function requiredPositiveIntegerFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    const parsed = Number(value.value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? { ok: true, value: parsed } : validationFailure(`--${name} must be a positive integer`);
+}
+function taskGrantCategoryFlag(flags, name) {
+    const value = requiredFlag(flags, name);
+    if (!value.ok)
+        return value;
+    return value.value === 'shell' || value.value === 'test-run' || value.value === 'git'
+        ? { ok: true, value: value.value }
+        : validationFailure(`--${name} must be shell, test-run, or git`);
+}
+function optionalTaskGrantStatusFlag(flags, name) {
+    const value = optionalStringFlag(flags, name);
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    return value === 'active' || value === 'revoked' || value === 'expired' || value === 'exhausted'
+        ? { ok: true, value }
+        : validationFailure(`--${name} must be active, revoked, expired, or exhausted`);
+}
+function taskGrantExpirationFlag(flags) {
+    const expiresAt = optionalStringFlag(flags, 'expires-at');
+    const ttl = optionalStringFlag(flags, 'ttl');
+    if ((expiresAt === undefined) === (ttl === undefined))
+        return validationFailure('Pass exactly one of --expires-at or --ttl');
+    if (expiresAt !== undefined) {
+        const timestamp = Date.parse(expiresAt);
+        if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== expiresAt)
+            return validationFailure('--expires-at must be a valid ISO date-time');
+        return timestamp > Date.now() ? { ok: true, value: expiresAt } : validationFailure('--expires-at must be in the future');
+    }
+    if (ttl === undefined)
+        return validationFailure('Pass exactly one of --expires-at or --ttl');
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl);
+    if (match === null)
+        return validationFailure('--ttl must be a positive duration like 30s, 15m, 2h, or 1d');
+    const amount = Number(match[1]);
+    if (!Number.isSafeInteger(amount) || amount <= 0)
+        return validationFailure('--ttl must be a positive duration like 30s, 15m, 2h, or 1d');
+    const unit = match[2];
+    const multiplier = unit === 'ms' ? 1 : unit === 's' ? 1_000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
+    return { ok: true, value: new Date(Date.now() + amount * multiplier).toISOString() };
+}
 function optionalRunStatusFlag(flags, name) {
     const value = optionalStringFlag(flags, name);
     if (value === undefined)
@@ -338,4 +384,4 @@ function setupInstallModeFlag(flags) {
         return { ok: true, value: 'mcp-only' };
     return { ok: true, value: vgxnessSetupDefaults.defaultInstallMode };
 }
-export { acceptedAtFlag, codeApprovalPolicyFlag, codeMemoryPolicyFlag, codeTranscriptModeFlag, codeVerificationModeFlag, csvFlag, databasePathFor, databasePathSelectionFor, finalRunStatusFlag, instructionKindFlag, isRunStatus, isSkillEvaluationResultStatus, isSkillTargetType, jsonFlag, providerUserGlobalOnlyMigrationMessage, opencodeDiagnosticScopeFlag, opencodeInstallScopeFlag, optionalJsonFlag, optionalModeFlag, optionalNumberFlag, optionalRunStatusFlag, optionalScopeFlag, optionalSkillEvaluationResultStatusFlag, optionalSkillImprovementProposalStatusFlag, optionalSkillResolutionUsageFlag, optionalSkillTargetTypeFlag, optionalSkillVersionStatusFlag, optionalStringFlag, optionalTrimmedFlag, parseArgs, permissionCategoryFlag, requiredFlag, requiredTrimmedFlag, retryPolicyFlag, runOutcomeFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, skillEvaluationResultStatusFlag, skillSourceFromFlags, skillSourceKindFlag, skillTargetTypeFlag, skillUsageOutcomeFlag, };
+export { acceptedAtFlag, codeApprovalPolicyFlag, codeMemoryPolicyFlag, codeTranscriptModeFlag, codeVerificationModeFlag, csvFlag, databasePathFor, databasePathSelectionFor, finalRunStatusFlag, instructionKindFlag, isRunStatus, isSkillEvaluationResultStatus, isSkillTargetType, jsonFlag, providerUserGlobalOnlyMigrationMessage, opencodeDiagnosticScopeFlag, opencodeInstallScopeFlag, optionalJsonFlag, optionalModeFlag, optionalNumberFlag, optionalRunStatusFlag, optionalScopeFlag, optionalSkillEvaluationResultStatusFlag, optionalSkillImprovementProposalStatusFlag, optionalSkillResolutionUsageFlag, optionalSkillTargetTypeFlag, optionalSkillVersionStatusFlag, optionalTaskGrantStatusFlag, optionalStringFlag, optionalTrimmedFlag, parseArgs, permissionCategoryFlag, requiredPositiveIntegerFlag, requiredFlag, requiredTrimmedFlag, retryPolicyFlag, runOutcomeFlag, scopeFlag, setupDatabaseFlags, setupInstallModeFlag, setupProviderFlag, skillEvaluationResultStatusFlag, skillSourceFromFlags, skillSourceKindFlag, skillTargetTypeFlag, skillUsageOutcomeFlag, taskGrantCategoryFlag, taskGrantExpirationFlag, };

package/dist/cli/commands/run-permission-dispatcher.js

@@ -2,7 +2,8 @@ import { AgentRegistryService } from '../../agents/agent-registry-service.js';
 import { evaluatePermission } from '../../permissions/policy-evaluator.js';
 import { RunService } from '../../runs/run-service.js';
 import { RunSnapshotExportService } from '../../runs/run-snapshot-export-service.js';
-import { finalRunStatusFlag, jsonFlag, optionalRunStatusFlag, optionalStringFlag, permissionCategoryFlag, requiredFlag, retryPolicyFlag, runOutcomeFlag, } from '../cli-flags.js';
+import { grantEvaluationPayload } from '../../runs/task-scoped-command-grant-service.js';
+import { csvFlag, finalRunStatusFlag, jsonFlag, optionalRunStatusFlag, optionalStringFlag, optionalTaskGrantStatusFlag, permissionCategoryFlag, requiredPositiveIntegerFlag, requiredFlag, retryPolicyFlag, runOutcomeFlag, taskGrantCategoryFlag, taskGrantExpirationFlag, } from '../cli-flags.js';
 import { usageFailure } from '../cli-help.js';
 import { isJsonObject, jsonResult, resultFailure, writeJsonFile } from '../cli-helpers.js';
 function listCliApprovals(service, runId) {
@@ -94,8 +95,158 @@ function permissionRequestFromFlags(parsed, database, environment) {
     }
     return { ok: true, value: request };
 }
+function rejectExecutableGrantFlags(parsed) {
+    if (parsed.flags.executable !== undefined || parsed.flags.argv !== undefined)
+        return { ok: false, error: { code: 'validation_failed', message: 'Task grants accept --command-id only; arbitrary executable/argv inputs are not supported' } };
+    return { ok: true, value: undefined };
+}
+function taskGrantExternalRoots(parsed) {
+    const roots = [...csvFlag(parsed.flags, 'external-roots')];
+    const root = optionalStringFlag(parsed.flags, 'external-root');
+    if (root !== undefined)
+        roots.unshift(root);
+    return roots.length > 0 ? { ok: true, value: roots } : { ok: false, error: { code: 'validation_failed', message: 'Missing required --external-root or --external-roots' } };
+}
+function runTaskGrantCommand(command, parsed, service) {
+    const grantService = service.taskScopedCommandGrantService();
+    const executableFlags = rejectExecutableGrantFlags(parsed);
+    if (!executableFlags.ok)
+        return resultFailure(executableFlags);
+    if (command === 'task-grant-create') {
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        const agentId = requiredFlag(parsed.flags, 'agent-id');
+        const taskFingerprint = requiredFlag(parsed.flags, 'task-fingerprint');
+        const category = taskGrantCategoryFlag(parsed.flags, 'category');
+        const commandId = requiredFlag(parsed.flags, 'command-id');
+        const maxUses = requiredPositiveIntegerFlag(parsed.flags, 'max-uses');
+        const expiresAt = taskGrantExpirationFlag(parsed.flags);
+        const createdById = requiredFlag(parsed.flags, 'created-by-id');
+        const creationReason = requiredFlag(parsed.flags, 'creation-reason');
+        const approvedScopeSummary = requiredFlag(parsed.flags, 'approved-scope-summary');
+        const externalRoots = taskGrantExternalRoots(parsed);
+        if (!runId.ok)
+            return resultFailure(runId);
+        if (!agentId.ok)
+            return resultFailure(agentId);
+        if (!taskFingerprint.ok)
+            return resultFailure(taskFingerprint);
+        if (!category.ok)
+            return resultFailure(category);
+        if (!commandId.ok)
+            return resultFailure(commandId);
+        if (!maxUses.ok)
+            return resultFailure(maxUses);
+        if (!expiresAt.ok)
+            return resultFailure(expiresAt);
+        if (!createdById.ok)
+            return resultFailure(createdById);
+        if (!creationReason.ok)
+            return resultFailure(creationReason);
+        if (!approvedScopeSummary.ok)
+            return resultFailure(approvedScopeSummary);
+        if (!externalRoots.ok)
+            return resultFailure(externalRoots);
+        const createdByName = optionalStringFlag(parsed.flags, 'created-by-name');
+        const cwdPatterns = csvFlag(parsed.flags, 'cwd-patterns');
+        return jsonResult(grantService.create({
+            runId: runId.value,
+            agentId: agentId.value,
+            taskFingerprint: taskFingerprint.value,
+            categories: [category.value],
+            externalRoots: externalRoots.value,
+            ...(cwdPatterns.length === 0 ? {} : { cwdPatterns }),
+            commandPolicy: { kind: 'allowlisted-command-ids', ids: [commandId.value] },
+            expiresAt: expiresAt.value,
+            maxUses: maxUses.value,
+            createdBy: { type: 'human', id: createdById.value, ...(createdByName === undefined ? {} : { displayName: createdByName }) },
+            audit: { creationReason: creationReason.value, approvedScopeSummary: approvedScopeSummary.value },
+        }));
+    }
+    if (command === 'task-grant-list') {
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        const status = optionalTaskGrantStatusFlag(parsed.flags, 'status');
+        const limit = parsed.flags.limit === undefined ? { ok: true, value: undefined } : requiredPositiveIntegerFlag(parsed.flags, 'limit');
+        if (!runId.ok)
+            return resultFailure(runId);
+        if (!status.ok)
+            return resultFailure(status);
+        if (!limit.ok)
+            return resultFailure(limit);
+        const agentId = optionalStringFlag(parsed.flags, 'agent-id');
+        return jsonResult(grantService.list({
+            runId: runId.value,
+            ...(agentId === undefined ? {} : { agentId }),
+            ...(status.value === undefined ? {} : { status: status.value }),
+            ...(limit.value === undefined ? {} : { limit: limit.value }),
+        }));
+    }
+    if (command === 'task-grant-get') {
+        const grantId = requiredFlag(parsed.flags, 'grant-id');
+        return grantId.ok ? jsonResult(grantService.get(grantId.value)) : resultFailure(grantId);
+    }
+    if (command === 'task-grant-revoke') {
+        const grantId = requiredFlag(parsed.flags, 'grant-id');
+        const actorId = requiredFlag(parsed.flags, 'actor-id');
+        const reason = requiredFlag(parsed.flags, 'reason');
+        const actorType = optionalStringFlag(parsed.flags, 'actor-type') ?? 'human';
+        if (!grantId.ok)
+            return resultFailure(grantId);
+        if (!actorId.ok)
+            return resultFailure(actorId);
+        if (!reason.ok)
+            return resultFailure(reason);
+        if (actorType !== 'human' && actorType !== 'system')
+            return resultFailure({ ok: false, error: { code: 'validation_failed', message: '--actor-type must be human or system' } });
+        const actorName = optionalStringFlag(parsed.flags, 'actor-name');
+        return jsonResult(grantService.revoke({
+            grantId: grantId.value,
+            actor: { type: actorType, id: actorId.value, ...(actorName === undefined ? {} : { displayName: actorName }) },
+            reason: reason.value,
+        }));
+    }
+    if (command === 'task-grant-preview') {
+        const runId = requiredFlag(parsed.flags, 'run-id');
+        const agentId = requiredFlag(parsed.flags, 'agent-id');
+        const taskFingerprint = requiredFlag(parsed.flags, 'task-fingerprint');
+        const category = taskGrantCategoryFlag(parsed.flags, 'category');
+        const commandId = requiredFlag(parsed.flags, 'command-id');
+        const workspaceRoot = requiredFlag(parsed.flags, 'workspace-root');
+        const cwd = requiredFlag(parsed.flags, 'cwd');
+        if (!runId.ok)
+            return resultFailure(runId);
+        if (!agentId.ok)
+            return resultFailure(agentId);
+        if (!taskFingerprint.ok)
+            return resultFailure(taskFingerprint);
+        if (!category.ok)
+            return resultFailure(category);
+        if (!commandId.ok)
+            return resultFailure(commandId);
+        if (!workspaceRoot.ok)
+            return resultFailure(workspaceRoot);
+        if (!cwd.ok)
+            return resultFailure(cwd);
+        const operation = optionalStringFlag(parsed.flags, 'operation') ?? `command-allowlist:${commandId.value}`;
+        const targetPaths = csvFlag(parsed.flags, 'target-paths');
+        const preview = grantService.previewMatch({
+            runId: runId.value,
+            agentId: agentId.value,
+            taskFingerprint: taskFingerprint.value,
+            category: category.value,
+            commandId: commandId.value,
+            operation,
+            workspaceRoot: workspaceRoot.value,
+            cwd: cwd.value,
+            ...(targetPaths.length === 0 ? {} : { targetPaths }),
+        });
+        return preview.ok ? jsonResult({ ok: true, value: grantEvaluationPayload(preview.value) }) : resultFailure(preview);
+    }
+    return usageFailure(`Unknown runs command: ${command}`);
+}
 export function runRunsCommand(command, parsed, database, environment) {
     const service = new RunService(database);
+    if (command.startsWith('task-grant-'))
+        return runTaskGrantCommand(command, parsed, service);
     if (command === 'timeline' || command === 'debug' || command === 'resume-plan' || command === 'resume-inspect')
         return runRunInsightCommand(command, parsed, service);
     if (command === 'create') {

package/dist/cli/dispatcher.js

@@ -164,7 +164,12 @@ function validateCommand(area, command) {
             command === 'resume-gate' ||
             command === 'approve' ||
             command === 'reject' ||
-            command === 'cancel-approval'
+            command === 'cancel-approval' ||
+            command === 'task-grant-create' ||
+            command === 'task-grant-list' ||
+            command === 'task-grant-get' ||
+            command === 'task-grant-revoke' ||
+            command === 'task-grant-preview'
             ? { ok: true }
             : { ok: false, message: `Unknown runs command: ${command}` };
     }

package/dist/mcp/control-plane.js

@@ -157,6 +157,22 @@ export function callVgxTool(call, services) {
             return toEnvelope(validated.tool, services.runs.getRun(validated.input.id));
         case 'vgxness_run_preflight':
             return toEnvelope(validated.tool, services.runs.preflightOperation(validated.input));
+        case 'vgxness_run_task_grant_create':
+            return createTaskGrantEnvelope(validated.input, services);
+        case 'vgxness_run_task_grant_list':
+            return listTaskGrantsEnvelope(validated.input, services);
+        case 'vgxness_run_task_grant_get':
+            if (services.runs.taskScopedCommandGrantService === undefined)
+                return errorEnvelope('validation_failed', 'Task-scoped command grant service is not available', validated.tool);
+            return toEnvelope(validated.tool, services.runs.taskScopedCommandGrantService().get(validated.input.grantId));
+        case 'vgxness_run_task_grant_revoke':
+            if (services.runs.taskScopedCommandGrantService === undefined)
+                return errorEnvelope('validation_failed', 'Task-scoped command grant service is not available', validated.tool);
+            return toEnvelope(validated.tool, services.runs.taskScopedCommandGrantService().revoke(validated.input));
+        case 'vgxness_run_task_grant_preview_match':
+            if (services.runs.taskScopedCommandGrantService === undefined)
+                return errorEnvelope('validation_failed', 'Task-scoped command grant service is not available', validated.tool);
+            return toEnvelope(validated.tool, services.runs.taskScopedCommandGrantService().previewMatch(validated.input));
         case 'vgxness_run_start':
             return toEnvelope(validated.tool, services.runs.createRun(validated.input));
         case 'vgxness_run_checkpoint':
@@ -564,6 +580,24 @@ function listRunsEnvelope(input, services) {
         ? successEnvelope('vgxness_run_list', result.value.slice(0, limit))
         : errorEnvelope(result.error.code, result.error.message, 'vgxness_run_list');
 }
+function createTaskGrantEnvelope(input, services) {
+    if (services.runs.taskScopedCommandGrantService === undefined)
+        return errorEnvelope('validation_failed', 'Task-scoped command grant service is not available', 'vgxness_run_task_grant_create');
+    const { creationReason, approvedScopeSummary, ...grantInput } = input;
+    return toEnvelope('vgxness_run_task_grant_create', services.runs.taskScopedCommandGrantService().create({
+        ...grantInput,
+        audit: { creationReason, approvedScopeSummary },
+    }));
+}
+function listTaskGrantsEnvelope(input, services) {
+    if (services.runs.taskScopedCommandGrantService === undefined)
+        return errorEnvelope('validation_failed', 'Task-scoped command grant service is not available', 'vgxness_run_task_grant_list');
+    const { limit, ...filters } = input;
+    const result = services.runs.taskScopedCommandGrantService().list(filters);
+    return result.ok
+        ? successEnvelope('vgxness_run_task_grant_list', limit === undefined ? result.value : result.value.slice(0, limit))
+        : errorEnvelope(result.error.code, result.error.message, 'vgxness_run_task_grant_list');
+}
 function runResumeCandidatesEnvelope(input, services) {
     const limit = input.limit ?? 5;
     const result = services.runs.listRecentInterruptedRuns({ project: input.project, limit });

package/dist/mcp/schema.js

@@ -50,6 +50,11 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_run_list',
     'vgxness_run_get',
     'vgxness_run_preflight',
+    'vgxness_run_task_grant_create',
+    'vgxness_run_task_grant_list',
+    'vgxness_run_task_grant_get',
+    'vgxness_run_task_grant_revoke',
+    'vgxness_run_task_grant_preview_match',
     'vgxness_run_start',
     'vgxness_run_checkpoint',
     'vgxness_run_finalize',
@@ -108,6 +113,11 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'run_list',
     'run_get',
     'run_preflight',
+    'run_task_grant_create',
+    'run_task_grant_list',
+    'run_task_grant_get',
+    'run_task_grant_revoke',
+    'run_task_grant_preview_match',
     'run_start',
     'run_checkpoint',
     'run_finalize',
@@ -132,6 +142,8 @@ const agentModes = ['agent', 'subagent'];
 const memoryTypes = ['architecture', 'decision', 'bugfix', 'pattern', 'config', 'discovery', 'learning', 'preference', 'manual'];
 const activityKinds = ['prompt', 'tool_call', 'artifact', 'summary', 'error'];
 const runStatuses = ['created', 'planned', 'running', 'needs-human', 'completed', 'failed', 'blocked', 'cancelled'];
+const taskGrantStatuses = ['active', 'revoked', 'expired', 'exhausted'];
+const taskGrantCategories = ['shell', 'test-run', 'git'];
 const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
 const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const payloadModes = ['compact', 'verbose'];
@@ -163,6 +175,26 @@ const providerChangePlanTypes = ['opencode-mcp-install', 'claude-mcp-install', '
 const sddPhaseInputSchema = z.union([z.enum(sddPhases), z.literal('apply')]);
 const sddPhaseSchema = z.enum(sddPhases);
 const jsonValueSchema = z.lazy(() => z.union([z.string(), z.number().finite(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)]));
+const taskGrantHumanActorInputSchema = z
+    .object({
+    type: z.literal('human'),
+    id: z.string().min(1),
+    displayName: z.string().min(1).optional(),
+})
+    .strict();
+const taskGrantRevocationActorInputSchema = z
+    .object({
+    type: z.enum(['human', 'system']),
+    id: z.string().min(1),
+    displayName: z.string().min(1).optional(),
+})
+    .strict();
+const taskGrantCommandPolicyInputSchema = z
+    .object({
+    kind: z.literal('allowlisted-command-ids'),
+    ids: z.array(z.string().min(1)).min(1),
+})
+    .strict();
 const providerEvidenceOutputSchema = z
     .object({
     staticManifestKnown: z.boolean(),
@@ -810,6 +842,10 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         agentId: z.string().min(1).optional(),
         workspaceRoot: z.string().min(1).optional(),
         targetPath: z.string().min(1).optional(),
+        taskFingerprint: z.string().min(1).optional(),
+        commandId: z.string().min(1).optional(),
+        cwd: z.string().min(1).optional(),
+        targetPaths: z.array(z.string().min(1)).optional(),
         providerToolName: z.string().min(1).optional(),
         agent: z
             .object({
@@ -826,6 +862,54 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         ambiguous: z.boolean().optional(),
     })
         .passthrough(),
+    vgxness_run_task_grant_create: z
+        .object({
+        runId: z.string().min(1),
+        agentId: z.string().min(1),
+        taskFingerprint: z.string().min(1),
+        categories: z.array(z.enum(taskGrantCategories)).min(1),
+        externalRoots: z.array(z.string().min(1)).min(1),
+        cwdPatterns: z.array(z.string().min(1)).optional(),
+        commandPolicy: taskGrantCommandPolicyInputSchema,
+        expiresAt: z.string().min(1),
+        maxUses: z.number().int().positive(),
+        createdBy: taskGrantHumanActorInputSchema,
+        creationReason: z.string().min(1),
+        approvedScopeSummary: z.string().min(1),
+    })
+        .strict(),
+    vgxness_run_task_grant_list: z
+        .object({
+        runId: z.string().min(1).optional(),
+        agentId: z.string().min(1).optional(),
+        status: z.enum(taskGrantStatuses).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+    })
+        .strict(),
+    vgxness_run_task_grant_get: z
+        .object({
+        grantId: z.string().min(1),
+    })
+        .strict(),
+    vgxness_run_task_grant_revoke: z
+        .object({
+        grantId: z.string().min(1),
+        actor: taskGrantRevocationActorInputSchema,
+        reason: z.string().min(1),
+    })
+        .strict(),
+    vgxness_run_task_grant_preview_match: z
+        .object({
+        runId: z.string().min(1),
+        agentId: z.string().min(1).optional(),
+        taskFingerprint: z.string().min(1),
+        category: z.enum(permissionCategories),
+        operation: z.string().min(1),
+        workspaceRoot: z.string().min(1).optional(),
+        cwd: z.string().min(1),
+        targetPaths: z.array(z.string().min(1)).optional(),
+    })
+        .strict(),
     vgxness_run_start: z
         .object({
         project: z.string().min(1),

package/dist/mcp/stdio-server.js

@@ -93,6 +93,12 @@ function descriptionForTool(publicToolName) {
         return 'Human-only mutating SDD reopen gate; records an explicit human decision to reopen an artifact and must not be called by agents on their own behalf. Use only after human instruction, then revise or re-review the phase.';
     if (publicToolName === 'run_preflight')
         return 'Agent-callable advisory/planning-only run preflight; evaluates permissions, records a plan, and returns a workspace strategy recommendation, but does not execute the checked shell/git/install/network/provider/secrets operation and does not create branches, worktrees, or pull requests. Use it to decide whether human approval or a separate executor step is required.';
+    if (publicToolName === 'run_task_grant_create')
+        return 'Human-approved lifecycle tool that creates a task-scoped command grant for bounded allowlisted external command operations.';
+    if (publicToolName === 'run_task_grant_list' || publicToolName === 'run_task_grant_get' || publicToolName === 'run_task_grant_preview_match')
+        return 'Read-only task-scoped command grant lifecycle tool; does not execute commands, write provider config, or consume grant usage.';
+    if (publicToolName === 'run_task_grant_revoke')
+        return 'Revokes a task-scoped command grant with an explicit human or system actor and reason.';
     const toolName = toInternalVgxMcpToolName(publicToolName);
     return `VGX control-plane tool ${toolName}`;
 }