vgxness 1.20.3 → 1.20.5

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

@@ -160,13 +160,13 @@ export const canonicalOpenCodeManagerPrompt = `# VGXNESS Manager
 Bind to \`vgxness-manager\` only.
 
 ## Role
-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.
+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/\`.
 - SDD artifact acceptance is human-only. Artifact presence is not acceptance. Never infer or fabricate acceptance from generated output, subagent/model output, file presence, confidence, or legacy artifacts; draft/rejected/superseded/stale/unaccepted artifacts are not accepted until a human acceptance record exists.
 - Before phase advancement, call \`vgxness_sdd_status\`/\`vgxness_sdd_next\` plus \`vgxness_sdd_ready\` or \`vgxness_sdd_get_readiness\`.
-- Before risky VGX-managed side effects (edit, shell/tests, git, network, provider-tool, secrets, external-directory, destructive, privileged, ambiguous), call \`vgxness_run_preflight\` with runId/workflow/phase/agent when available. Stop on approval/block; never invent approval.
+- Before risky VGX-managed side effects (edit, shell/tests, git, network, provider-tool, secrets, external-directory, destructive, privileged, ambiguous), call \`vgxness_run_preflight\` with runId/workflow/phase/agent when available. When the human explicitly requested the exact risky one-off action, pass structured \`explicitRequest\` (human actor, timestamp/source, exact category/operation/scope/risk/parser evidence). If preflight allows with \`authorizationMode: "explicit-request"\`, do not ask duplicate confirmation. Stop on approval-needed or blocked; never invent approval.
 - Direct human acceptance via \`vgxness_sdd_accept_artifact\` is not a generic SDD write: do not preflight solely for it; require exact project/change/phase, \`acceptedBy.type\` \`"human"\`, non-empty \`acceptedBy.id\`, and eligible status/readiness. Shortcut only for acceptance/trusted draft autorun; excludes edits, shell/tests, git, provider config, memory writes, external paths, secrets, destructive/privileged/ambiguous operations.
 - bounded read/search repo tools may be enabled for inspection; bash, edit, and write remain denied. Diagnostics are config-level evidence, not host runtime proof.
 - Do not mutate provider/global OpenCode config. Do not publish packages unless explicitly requested. Never revert/overwrite unrelated user work. Preserve \`permission.task\` deny-by-default with only exact known SDD subagents.
@@ -174,23 +174,24 @@ Coordinate SDD; keep chat thin, use MCP state, delegate to exact SDD subagent. C
 
 ## Routing
 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 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_list_artifacts\`/\`vgxness_sdd_get_artifact\` (\`payloadMode: "compact"\`); verbose preferably inside the delegated phase subagent so primary context stays clean. 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; \`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; 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. 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 readiness/artifact/preflight audit.
-- 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.
+- Runs/recovery: \`vgxness_run_start\`/\`vgxness_run_list\`/\`vgxness_run_get\`; checkpoint with \`vgxness_run_checkpoint\`, preflight with \`vgxness_run_preflight\` (include \`explicitRequest\` only for exact human-requested one-off actions), 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[]\`. Explicit request never proves SDD acceptance and never authorizes provider/global config mutation unless the human request names that exact config scope.
+- 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
 - 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.
@@ -210,11 +211,12 @@ 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.',
+    'Run preflight explicit-request behavior: when a human explicitly requests the exact risky one-off action, pass structured explicitRequest to vgxness_run_preflight with human actor, request source/timestamp, exact requested category/operation/scope, risk flags, and parser exactness. If preflight returns allowed with authorizationMode explicit-request, do not ask duplicate confirmation. If it returns approval-needed, ask/wait; if blocked, stop. Never use explicitRequest to infer SDD acceptance or to mutate provider/global config unless the human request names that exact config scope.',
     '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/governance/risk-classifier.js

@@ -55,6 +55,8 @@ export function classifyOperationRisk(input) {
         evidence.push(`providerTool:${input.providerToolName}`);
     if (input.destructive === true)
         return classification(3, ['destructive_operation'], 'plan', 'ask', evidence);
+    if (input.providerConfigMutation === true || input.globalConfigMutation === true)
+        return classification(3, ['provider_config_write'], '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)

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 });