vgxness 1.20.4 → 1.20.5

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

@@ -166,7 +166,7 @@ Coordinate SDD; keep chat thin, use MCP state, delegate to exact SDD subagent. C
 - 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.
@@ -190,7 +190,7 @@ SDD happens in OpenCode conversation + VGXNESS MCP/subagents. No terminal SDD ph
 - 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[]\`.
+- 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
@@ -216,6 +216,7 @@ const registryManagerInstructionsV11 = [
     '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/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/schema.js

@@ -154,6 +154,63 @@ const skillSourceKinds = ['path', 'url', 'inline'];
 const skillUsageOutcomes = ['selected', 'injected', 'helped', 'failed', 'neutral'];
 const skillAttachmentTargetTypes = ['agent', 'subagent', 'workflow-phase', 'provider-adapter', 'intent-signal'];
 const jsonRecordSchema = z.record(z.string(), z.unknown());
+const explicitRequestInputSchema = z
+    .object({
+    version: z.literal(1),
+    actor: z
+        .object({
+        type: z.literal('human'),
+        id: z.string().min(1).optional(),
+        displayName: z.string().min(1).optional(),
+    })
+        .strict(),
+    request: z
+        .object({
+        id: z.string().min(1).optional(),
+        source: z.enum(['chat', 'mcp', 'cli', 'provider', 'unknown']),
+        utteranceRef: z.string().min(1).optional(),
+        excerpt: z.string().min(1).optional(),
+        requestedAt: z.string().min(1),
+        sessionId: z.string().min(1).optional(),
+        runId: z.string().min(1).optional(),
+    })
+        .strict(),
+    requestedOperation: z
+        .object({
+        category: z.enum(permissionCategories),
+        operation: z.string().min(1),
+        commandId: z.string().min(1).optional(),
+        providerToolName: z.string().min(1).optional(),
+        targetPath: z.string().min(1).optional(),
+        targetPaths: z.array(z.string().min(1)).optional(),
+        cwd: z.string().min(1).optional(),
+        workspaceRoot: z.string().min(1).optional(),
+        scopeSummary: z.string().min(1),
+    })
+        .strict(),
+    riskAttributes: z
+        .object({
+        destructive: z.boolean().optional(),
+        privileged: z.boolean().optional(),
+        external: z.boolean().optional(),
+        ambiguous: z.boolean().optional(),
+        secrets: z.boolean().optional(),
+        providerConfigMutation: z.boolean().optional(),
+        globalConfigMutation: z.boolean().optional(),
+        network: z.boolean().optional(),
+        install: z.boolean().optional(),
+    })
+        .strict(),
+    parser: z
+        .object({
+        exact: z.boolean(),
+        confidence: z.enum(['high', 'medium', 'low']).optional(),
+        ambiguityReasons: z.array(z.string().min(1)).optional(),
+        expansionReasons: z.array(z.string().min(1)).optional(),
+    })
+        .strict(),
+})
+    .strict();
 const skillLifecycleActorSchema = z
     .object({
     type: z.enum(['human', 'agent', 'system']),
@@ -860,6 +917,9 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         external: z.boolean().optional(),
         privileged: z.boolean().optional(),
         ambiguous: z.boolean().optional(),
+        providerConfigMutation: z.boolean().optional(),
+        globalConfigMutation: z.boolean().optional(),
+        explicitRequest: explicitRequestInputSchema.optional(),
     })
         .passthrough(),
     vgxness_run_task_grant_create: z

package/dist/mcp/validation.js

@@ -1589,6 +1589,9 @@ function validateRunPreflightInput(input, tool) {
         'external',
         'privileged',
         'ambiguous',
+        'providerConfigMutation',
+        'globalConfigMutation',
+        'explicitRequest',
     ]);
     if (!record.ok)
         return record;
@@ -1620,7 +1623,7 @@ function validateRunPreflightInput(input, tool) {
         return sandboxStrategy;
     if (sandboxStrategy.value !== undefined)
         result.sandboxStrategy = sandboxStrategy.value;
-    const booleans = copyOptionalBooleans(result, record.value, tool, ['destructive', 'external', 'privileged', 'ambiguous']);
+    const booleans = copyOptionalBooleans(result, record.value, tool, ['destructive', 'external', 'privileged', 'ambiguous', 'providerConfigMutation', 'globalConfigMutation']);
     if (!booleans.ok)
         return booleans;
     if (record.value.agent !== undefined) {
@@ -1629,6 +1632,12 @@ function validateRunPreflightInput(input, tool) {
             return agent;
         result.agent = agent.value;
     }
+    if (record.value.explicitRequest !== undefined) {
+        const explicitRequest = readExplicitRequest(record.value.explicitRequest, tool);
+        if (!explicitRequest.ok)
+            return explicitRequest;
+        result.explicitRequest = explicitRequest.value;
+    }
     if (isRiskyPermissionCategory(result.category)) {
         if (result.phase !== undefined && result.agentId === undefined && result.agent === undefined) {
             return validationFailure(`VGX-managed preflight for risky category ${result.category} requires agentId when phase metadata is provided`, tool);
@@ -1639,6 +1648,141 @@ function validateRunPreflightInput(input, tool) {
     }
     return { ok: true, value: result };
 }
+function readExplicitRequest(value, tool) {
+    const record = asRecord(value, tool, 'explicitRequest must be an object');
+    if (!record.ok)
+        return record;
+    const unexpected = Object.keys(record.value).find((key) => !['version', 'actor', 'request', 'requestedOperation', 'riskAttributes', 'parser'].includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected explicitRequest field: ${unexpected}`, tool);
+    if (record.value.version !== 1)
+        return validationFailure('explicitRequest.version must be 1', tool);
+    const actor = readExplicitRequestActor(record.value.actor, tool);
+    if (!actor.ok)
+        return actor;
+    const request = readExplicitRequestRequest(record.value.request, tool);
+    if (!request.ok)
+        return request;
+    const requestedOperation = readExplicitRequestedOperation(record.value.requestedOperation, tool);
+    if (!requestedOperation.ok)
+        return requestedOperation;
+    const riskAttributes = readExplicitRiskAttributes(record.value.riskAttributes, tool);
+    if (!riskAttributes.ok)
+        return riskAttributes;
+    const parser = readExplicitParser(record.value.parser, tool);
+    if (!parser.ok)
+        return parser;
+    return { ok: true, value: { version: 1, actor: actor.value, request: request.value, requestedOperation: requestedOperation.value, riskAttributes: riskAttributes.value, parser: parser.value } };
+}
+function readExplicitRequestActor(value, tool) {
+    const record = asRecord(value, tool, 'explicitRequest.actor must be an object');
+    if (!record.ok)
+        return record;
+    const unexpected = Object.keys(record.value).find((key) => !['type', 'id', 'displayName'].includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected explicitRequest.actor field: ${unexpected}`, tool);
+    const type = readRequiredOneOf(record.value, 'type', ['human'], tool);
+    if (!type.ok)
+        return type;
+    const actor = { type: type.value };
+    const copied = copyOptionalStrings(actor, record.value, tool, ['id', 'displayName']);
+    if (!copied.ok)
+        return copied;
+    return { ok: true, value: actor };
+}
+function readExplicitRequestRequest(value, tool) {
+    const record = asRecord(value, tool, 'explicitRequest.request must be an object');
+    if (!record.ok)
+        return record;
+    const unexpected = Object.keys(record.value).find((key) => !['id', 'source', 'utteranceRef', 'excerpt', 'requestedAt', 'sessionId', 'runId'].includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected explicitRequest.request field: ${unexpected}`, tool);
+    const source = readRequiredOneOf(record.value, 'source', ['chat', 'mcp', 'cli', 'provider', 'unknown'], tool);
+    if (!source.ok)
+        return source;
+    const requestedAt = readNonEmptyString(record.value, 'requestedAt', tool);
+    if (!requestedAt.ok)
+        return requestedAt;
+    if (!validIsoTimestamp(requestedAt.value))
+        return validationFailure('explicitRequest.request.requestedAt must be a valid ISO timestamp', tool);
+    const request = { source: source.value, requestedAt: requestedAt.value };
+    const copied = copyOptionalStrings(request, record.value, tool, ['id', 'utteranceRef', 'excerpt', 'sessionId', 'runId']);
+    if (!copied.ok)
+        return copied;
+    return { ok: true, value: request };
+}
+function readExplicitRequestedOperation(value, tool) {
+    const record = asRecord(value, tool, 'explicitRequest.requestedOperation must be an object');
+    if (!record.ok)
+        return record;
+    const unexpected = Object.keys(record.value).find((key) => !['category', 'operation', 'commandId', 'providerToolName', 'targetPath', 'targetPaths', 'cwd', 'workspaceRoot', 'scopeSummary'].includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected explicitRequest.requestedOperation field: ${unexpected}`, tool);
+    const category = readRequiredOneOf(record.value, 'category', permissionCategories, tool);
+    if (!category.ok)
+        return category;
+    const operation = readNonEmptyString(record.value, 'operation', tool);
+    if (!operation.ok)
+        return operation;
+    const scopeSummary = readNonEmptyString(record.value, 'scopeSummary', tool);
+    if (!scopeSummary.ok)
+        return scopeSummary;
+    const requestedOperation = { category: category.value, operation: operation.value, scopeSummary: scopeSummary.value };
+    const copied = copyOptionalStrings(requestedOperation, record.value, tool, ['commandId', 'providerToolName', 'targetPath', 'cwd', 'workspaceRoot']);
+    if (!copied.ok)
+        return copied;
+    const targetPaths = readOptionalStringArray(record.value, 'targetPaths', tool);
+    if (!targetPaths.ok)
+        return targetPaths;
+    if (targetPaths.value !== undefined)
+        requestedOperation.targetPaths = targetPaths.value;
+    return { ok: true, value: requestedOperation };
+}
+function readExplicitRiskAttributes(value, tool) {
+    const record = asRecord(value, tool, 'explicitRequest.riskAttributes must be an object');
+    if (!record.ok)
+        return record;
+    const fields = ['destructive', 'privileged', 'external', 'ambiguous', 'secrets', 'providerConfigMutation', 'globalConfigMutation', 'network', 'install'];
+    const unexpected = Object.keys(record.value).find((key) => !fields.includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected explicitRequest.riskAttributes field: ${unexpected}`, tool);
+    const riskAttributes = {};
+    const copied = copyOptionalBooleans(riskAttributes, record.value, tool, fields);
+    if (!copied.ok)
+        return copied;
+    return { ok: true, value: riskAttributes };
+}
+function readExplicitParser(value, tool) {
+    const record = asRecord(value, tool, 'explicitRequest.parser must be an object');
+    if (!record.ok)
+        return record;
+    const unexpected = Object.keys(record.value).find((key) => !['exact', 'confidence', 'ambiguityReasons', 'expansionReasons'].includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected explicitRequest.parser field: ${unexpected}`, tool);
+    if (typeof record.value.exact !== 'boolean')
+        return validationFailure('explicitRequest.parser.exact must be a boolean', tool);
+    const parser = { exact: record.value.exact };
+    const confidence = readOptionalOneOf(record.value, 'confidence', ['high', 'medium', 'low'], tool);
+    if (!confidence.ok)
+        return confidence;
+    if (confidence.value !== undefined)
+        parser.confidence = confidence.value;
+    const ambiguityReasons = readOptionalStringArray(record.value, 'ambiguityReasons', tool);
+    if (!ambiguityReasons.ok)
+        return ambiguityReasons;
+    if (ambiguityReasons.value !== undefined)
+        parser.ambiguityReasons = ambiguityReasons.value;
+    const expansionReasons = readOptionalStringArray(record.value, 'expansionReasons', tool);
+    if (!expansionReasons.ok)
+        return expansionReasons;
+    if (expansionReasons.value !== undefined)
+        parser.expansionReasons = expansionReasons.value;
+    return { ok: true, value: parser };
+}
+function validIsoTimestamp(value) {
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
+}
 function validateRunTaskGrantCreateInput(input, tool) {
     const record = inputRecord(input, tool, [
         'runId',

package/dist/permissions/explicit-request-authorization.js

@@ -0,0 +1,126 @@
+import { isAbsolute, resolve } from 'node:path';
+export function evaluateExplicitRequestAuthorization(input) {
+    const explicit = input.request.explicitRequest;
+    if (explicit === undefined)
+        return evaluation(input, 'ask', 'missing-context', ['explicit_request_missing']);
+    if (explicit.actor.type !== 'human')
+        return evaluation(input, 'ask', 'actor-mismatch', ['explicit_request_actor_mismatch']);
+    if (!validIsoTimestamp(explicit.request.requestedAt))
+        return evaluation(input, 'ask', 'timestamp-invalid', ['explicit_request_timestamp_invalid']);
+    if (explicit.request.runId !== undefined && input.request.runId !== undefined && explicit.request.runId !== input.request.runId)
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (explicit.parser.exact !== true || explicit.parser.confidence === 'medium' || explicit.parser.confidence === 'low' || hasItems(explicit.parser.ambiguityReasons))
+        return evaluation(input, 'ask', 'ambiguous-request', ['explicit_request_ambiguous']);
+    if (hasItems(explicit.parser.expansionReasons))
+        return evaluation(input, 'ask', 'scope-expanded', ['explicit_request_scope_expanded']);
+    if (isSddAcceptanceAttempt(input.request))
+        return evaluation(input, 'deny', 'hard-stop', ['sdd_human_acceptance_required']);
+    if (input.request.category === 'secrets' || input.risk.reasonCodes.includes('secret_access') || explicit.riskAttributes.secrets === true)
+        return evaluation(input, 'deny', 'hard-stop', ['explicit_request_secret_access']);
+    if (explicit.requestedOperation.category !== input.request.category)
+        return evaluation(input, 'ask', 'category-mismatch', ['explicit_request_category_mismatch']);
+    if (normalizeOperation(explicit.requestedOperation.operation) !== normalizeOperation(input.request.operation))
+        return evaluation(input, 'ask', 'operation-mismatch', ['explicit_request_operation_mismatch']);
+    if (!optionalExact(explicit.requestedOperation.commandId, input.request.commandId))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!optionalExact(explicit.requestedOperation.providerToolName, input.request.providerToolName))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!optionalPathExact(explicit.requestedOperation.workspaceRoot, input.request.workspaceRoot, input.request.workspaceRoot))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!optionalPathExact(explicit.requestedOperation.cwd, input.request.cwd, input.request.workspaceRoot))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    if (!targetSetMatches(input.request, explicit.requestedOperation))
+        return evaluation(input, 'ask', 'scope-mismatch', ['explicit_request_scope_mismatch']);
+    const riskMismatch = riskMismatchReasons(input.request, input.risk, explicit.riskAttributes);
+    if (riskMismatch.length > 0)
+        return evaluation(input, 'ask', 'risk-attribute-mismatch', riskMismatch);
+    return evaluation(input, 'allow', 'exact-match', ['explicit_request_exact_match']);
+}
+function evaluation(input, decision, matchStatus, reasonCodes) {
+    const explicit = input.request.explicitRequest;
+    return {
+        decision,
+        audit: {
+            authorization: 'explicit-request',
+            matched: decision === 'allow',
+            matchStatus,
+            ...(explicit?.request.id === undefined ? {} : { requestRef: explicit.request.id }),
+            ...(explicit?.actor === undefined ? {} : { actor: explicit.actor }),
+            ...(explicit?.request.requestedAt === undefined ? {} : { requestedAt: explicit.request.requestedAt }),
+            evaluatedAt: input.evaluatedAt,
+            runId: input.request.runId ?? explicit?.request.runId ?? '',
+            category: input.request.category,
+            operation: input.request.operation,
+            scopeSummary: explicit?.requestedOperation.scopeSummary ?? '',
+            riskAttributes: explicitRiskAttributes(explicit?.riskAttributes),
+            reasonCodes,
+        },
+    };
+}
+function riskMismatchReasons(request, risk, explicit) {
+    const reasons = [];
+    if (request.destructive === true && explicit.destructive !== true)
+        reasons.push('explicit_request_destructive_not_explicit');
+    if (request.privileged === true && explicit.privileged !== true)
+        reasons.push('explicit_request_privileged_not_explicit');
+    if ((request.external === true || risk.reasonCodes.includes('external_operation')) && explicit.external !== true && explicit.network !== true && explicit.install !== true)
+        reasons.push('explicit_request_external_not_explicit');
+    if (request.ambiguous === true && explicit.ambiguous !== true)
+        reasons.push('explicit_request_ambiguous');
+    if (request.globalConfigMutation === true && explicit.globalConfigMutation !== true)
+        reasons.push('explicit_request_global_config_not_explicit');
+    if (request.providerConfigMutation === true && explicit.providerConfigMutation !== true)
+        reasons.push('explicit_request_provider_config_not_explicit');
+    if (request.providerConfigMutation !== true && request.globalConfigMutation !== true && risk.reasonCodes.includes('provider_config_write') && explicit.providerConfigMutation !== true)
+        reasons.push('explicit_request_provider_config_not_explicit');
+    if (request.category === 'network' && explicit.network !== true)
+        reasons.push('explicit_request_risk_mismatch');
+    if (request.category === 'install' && explicit.install !== true)
+        reasons.push('explicit_request_risk_mismatch');
+    return [...new Set(reasons)];
+}
+function targetSetMatches(request, explicit) {
+    const requested = targetSet(request.targetPath, request.targetPaths, request.workspaceRoot);
+    const authorized = targetSet(explicit.targetPath, explicit.targetPaths, request.workspaceRoot ?? explicit.workspaceRoot);
+    if (requested.length === 0 && authorized.length === 0)
+        return true;
+    if (requested.length === 0 || authorized.length === 0)
+        return false;
+    if (requested.length !== authorized.length)
+        return false;
+    return requested.every((value, index) => value === authorized[index]);
+}
+function targetSet(targetPath, targetPaths, workspaceRoot) {
+    return [...new Set([...(targetPath === undefined ? [] : [targetPath]), ...(targetPaths ?? [])].map((path) => normalizePath(path, workspaceRoot)))].sort();
+}
+function optionalExact(explicit, actual) {
+    return actual === undefined ? explicit === undefined : explicit === actual;
+}
+function optionalPathExact(explicit, actual, workspaceRoot) {
+    return actual === undefined ? explicit === undefined : explicit !== undefined && normalizePath(explicit, workspaceRoot) === normalizePath(actual, workspaceRoot);
+}
+function normalizePath(path, workspaceRoot) {
+    const base = workspaceRoot === undefined ? undefined : resolve(workspaceRoot);
+    return resolve(isAbsolute(path) || base === undefined ? path : resolve(base, path));
+}
+function normalizeOperation(value) {
+    return value.trim().replace(/\s+/g, ' ');
+}
+function hasItems(values) {
+    return values !== undefined && values.length > 0;
+}
+function validIsoTimestamp(value) {
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value && timestamp <= Date.now() + 60_000;
+}
+function explicitRiskAttributes(value) {
+    const output = {};
+    for (const key of ['destructive', 'privileged', 'external', 'ambiguous', 'secrets', 'providerConfigMutation', 'globalConfigMutation', 'network', 'install']) {
+        output[key] = value?.[key] === true;
+    }
+    return output;
+}
+function isSddAcceptanceAttempt(request) {
+    const text = `${request.category} ${request.operation} ${request.providerToolName ?? ''}`.toLowerCase();
+    return /vgxness_sdd_accept_artifact|sdd_accept_artifact|artifact acceptance|accept artifact|acceptedby/.test(text);
+}

package/dist/permissions/policy-evaluator.js

@@ -3,6 +3,7 @@ import { dirname, isAbsolute, resolve, sep } from 'node:path';
 import { classifyOperationRisk } from '../governance/risk-classifier.js';
 import { isSddPhase, sddPhases } from '../sdd/schema.js';
 import { commandAllowlistIds } from '../workflows/command-allowlist-adapter.js';
+import { evaluateExplicitRequestAuthorization } from './explicit-request-authorization.js';
 export { isRiskyPermissionCategory, permissionCategories, riskyPermissionCategories } from './schema.js';
 export const permissionDecisions = ['allow', 'ask', 'deny'];
 export const permissionModes = ['allow', 'audit', 'require-preflight', 'deny'];
@@ -85,30 +86,30 @@ const filesystemCategories = new Set([
 export function evaluatePermission(request, policy = defaultPermissionPolicy) {
     const risk = classifyOperationRisk(request);
     if (request.category === 'secrets')
-        return result(request, 'deny', 'secret_access', 'Secret access is denied by default.', {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, 'deny', 'secret_access', 'Secret access is denied by default.', {}, risk), risk);
     if (request.category === 'external-directory') {
-        return result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.', {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, 'deny', 'workspace_boundary', 'External directory access is denied by the foundation policy.', {}, risk), risk);
     }
     const hardRisk = hardRiskDecision(request, risk);
     if (hardRisk !== undefined)
-        return hardRisk;
+        return withExplicitRequestAuthorization(request, hardRisk, risk);
     const workspaceEscape = workspaceEscapeDecision(request);
     if (workspaceEscape !== undefined)
-        return workspaceEscape;
+        return withExplicitRequestAuthorization(request, workspaceEscape, risk);
     const verifyAllowlistedCommand = verifyAllowlistedCommandDecision(request, risk);
     if (verifyAllowlistedCommand !== undefined)
         return verifyAllowlistedCommand;
     const sddPhaseDecision = phaseMatrixDecision(request);
     if (sddPhaseDecision !== undefined && sddPhaseDecision.mode !== 'allow' && sddPhaseDecision.mode !== 'audit')
-        return sddPhaseDecision;
+        return withExplicitRequestAuthorization(request, sddPhaseDecision, risk);
     const explicitValidation = explicitValidationDecision(request, risk);
     if (explicitValidation !== undefined)
-        return explicitValidation;
+        return withExplicitRequestAuthorization(request, explicitValidation, risk);
     if (sddPhaseDecision !== undefined)
         return sddPhaseDecision;
     const boundary = workspaceBoundaryDecision(request);
     if (boundary !== undefined)
-        return boundary;
+        return withExplicitRequestAuthorization(request, boundary, risk);
     const agentDecision = request.agent?.permissions[request.category];
     const baseRule = policy.rules.find((rule) => rule.category === request.category);
     const baseDecision = agentDecision ?? baseRule?.decision ?? 'ask';
@@ -118,7 +119,7 @@ export function evaluatePermission(request, policy = defaultPermissionPolicy) {
         : (baseRule?.reason ?? `No explicit rule exists for ${request.category}; ask by default.`);
     const flagRisk = riskDecision(request);
     if (flagRisk !== undefined && isLessRestrictive(baseDecision, flagRisk.decision)) {
-        return result(request, flagRisk.decision, flagRisk.reason, flagRisk.message, {}, risk);
+        return withExplicitRequestAuthorization(request, result(request, flagRisk.decision, flagRisk.reason, flagRisk.message, {}, risk), risk);
     }
     if (risk.defaultDecision === 'audit' && baseDecision !== 'deny') {
         return result(request, 'allow', risk.reasonCodes.includes('provider_readonly_audit') ? 'provider_readonly_audit' : risk.reasonCodes.includes('allowlisted_verification') ? 'allowlisted_command' : baseReason, baseMessage, {
@@ -127,7 +128,39 @@ export function evaluatePermission(request, policy = defaultPermissionPolicy) {
             warnings: risk.reasonCodes.includes('provider_readonly_audit') ? ['provider-readonly-audit-only'] : ['audit-only'],
         }, risk);
     }
-    return result(request, baseDecision, baseReason, baseMessage, {}, risk);
+    return withExplicitRequestAuthorization(request, result(request, baseDecision, baseReason, baseMessage, {}, risk), risk);
+}
+function withExplicitRequestAuthorization(request, decision, risk) {
+    if (request.explicitRequest === undefined)
+        return decision;
+    const explicit = evaluateExplicitRequestAuthorization({ request, risk, evaluatedAt: new Date().toISOString() });
+    if (decision.decision !== 'ask') {
+        return { ...decision, explicitRequestAudit: explicit.audit, auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`] };
+    }
+    if (explicit.decision === 'allow') {
+        return {
+            ...decision,
+            decision: 'allow',
+            reason: 'explicit_request_authorization',
+            message: 'Explicit human request authorizes this exact one-off operation.',
+            explicitRequestAudit: explicit.audit,
+            authorizationMode: 'explicit-request',
+            auditEvidence: [...(decision.auditEvidence ?? []), 'explicitRequest:exact-match'],
+        };
+    }
+    if (explicit.decision === 'deny') {
+        return {
+            ...decision,
+            decision: 'deny',
+            reason: explicit.audit.reasonCodes.includes('sdd_human_acceptance_required') ? 'sdd_phase_policy' : 'risk_tier_policy',
+            message: explicit.audit.reasonCodes.includes('sdd_human_acceptance_required')
+                ? 'SDD artifact acceptance is human-only and cannot be inferred from explicit-request preflight.'
+                : 'Explicit request contains a hard-stop condition and cannot authorize this operation.',
+            explicitRequestAudit: explicit.audit,
+            auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`],
+        };
+    }
+    return { ...decision, explicitRequestAudit: explicit.audit, auditEvidence: [...(decision.auditEvidence ?? []), `explicitRequest:${explicit.audit.matchStatus}`] };
 }
 export function isPathInsideWorkspace(workspaceRoot, targetPath) {
     const root = resolve(workspaceRoot);

package/dist/runs/run-service.js

@@ -364,6 +364,8 @@ export class RunService {
                 requestedOperation: operationMetadata(resolved.value),
                 decisionEventId: permission.value.event.id,
                 approvalId: permission.value.approval?.id ?? null,
+                authorizationMode: permission.value.decision.authorizationMode ?? null,
+                explicitRequestAudit: (permission.value.decision.explicitRequestAudit ?? null),
                 plan: plan,
                 workspaceStrategy: workspaceStrategy,
                 ...(sandboxDecision === undefined ? {} : { sandboxDecision: sandboxDecision }),
@@ -396,6 +398,8 @@ export class RunService {
         const audit = { permissionEventId: event.id, planEventId: planEvent.id };
         if (approval !== undefined)
             audit.approvalId = approval.id;
+        if (decision.explicitRequestAudit !== undefined)
+            audit.explicitRequestAudit = decision.explicitRequestAudit;
         const sandbox = plan.sandbox;
         const sandboxRejected = sandbox?.decision === 'rejected';
         const sandboxReason = sandboxRejected ? [{ code: sandbox.reason ?? 'sandbox_boundary', message: sandbox.audit.validationSummary }] : [];
@@ -404,6 +408,7 @@ export class RunService {
             permissionEventId: event.id,
             planEventId: planEvent.id,
             ...(approval === undefined ? {} : { approvalId: approval.id }),
+            ...(decision.explicitRequestAudit === undefined ? {} : { explicitRequestAudit: decision.explicitRequestAudit }),
         });
         return {
             ok: true,
@@ -772,6 +777,8 @@ export class RunService {
                         riskReasonCodes: reusedDecision.riskReasonCodes ?? [],
                         boundary: (reusedDecision.boundary ?? null),
                         auditEvidence: reusedDecision.auditEvidence ?? [],
+                        explicitRequestAudit: (reusedDecision.explicitRequestAudit ?? null),
+                        authorizationMode: reusedDecision.authorizationMode ?? (reusedDecision.decision === 'allow' && decision.decision === 'ask' ? 'approval-reuse' : null),
                         requiresHumanApproval: reusedDecision.decision === 'ask',
                         approvalStatus: prior.value.approval.status,
                         reusedApprovalId: prior.value.approval.id,
@@ -811,6 +818,8 @@ export class RunService {
                         riskReasonCodes: grantedDecision.riskReasonCodes ?? [],
                         boundary: (grantedDecision.boundary ?? null),
                         auditEvidence: grantedDecision.auditEvidence ?? [],
+                        explicitRequestAudit: (grantedDecision.explicitRequestAudit ?? null),
+                        authorizationMode: grantedDecision.authorizationMode ?? null,
                         requiresHumanApproval: false,
                         approvalStatus: 'not-required',
                         grantEvaluation: grantEvaluationPayload(grantAuthorization.value.evaluation),
@@ -841,6 +850,8 @@ export class RunService {
                 riskReasonCodes: decision.riskReasonCodes ?? [],
                 boundary: (decision.boundary ?? null),
                 auditEvidence: decision.auditEvidence ?? [],
+                explicitRequestAudit: (decision.explicitRequestAudit ?? null),
+                authorizationMode: decision.authorizationMode ?? null,
                 requiresHumanApproval: decision.decision === 'ask',
                 approvalStatus: decision.decision === 'ask' ? 'pending' : 'not-required',
                 ...(grantAuthorization === undefined ? {} : { grantEvaluation: grantEvaluationPayload(grantAuthorization.value.evaluation) }),
@@ -924,6 +935,7 @@ export class RunService {
                 permissionEventId: audit.permissionEventId,
                 planEventId: audit.planEventId,
                 approvalId: audit.approvalId ?? null,
+                explicitRequestAudit: (audit.explicitRequestAudit ?? null),
                 executorInvoked: false,
                 operationExecuted: false,
                 timestamp: new Date().toISOString(),
@@ -1274,6 +1286,10 @@ function operationMetadata(input) {
         metadata.privileged = input.privileged;
     if (input.ambiguous !== undefined)
         metadata.ambiguous = input.ambiguous;
+    if (input.providerConfigMutation !== undefined)
+        metadata.providerConfigMutation = input.providerConfigMutation;
+    if (input.globalConfigMutation !== undefined)
+        metadata.globalConfigMutation = input.globalConfigMutation;
     if (input.input !== undefined)
         metadata.input = input.input;
     return metadata;
@@ -1304,7 +1320,22 @@ function operationMetadataCompatible(preflightOperation, requestedOperation) {
         return jsonEqual(preflightOperation, requestedOperation);
     if (preflightOperation.category !== requestedOperation.category || preflightOperation.name !== requestedOperation.name)
         return false;
-    const strictKeys = ['workspaceRoot', 'targetPath', 'providerToolName', 'sandboxStrategy', 'taskFingerprint', 'commandId', 'cwd', 'targetPaths', 'destructive', 'external', 'privileged', 'ambiguous'];
+    const strictKeys = [
+        'workspaceRoot',
+        'targetPath',
+        'providerToolName',
+        'sandboxStrategy',
+        'taskFingerprint',
+        'commandId',
+        'cwd',
+        'targetPaths',
+        'destructive',
+        'external',
+        'privileged',
+        'ambiguous',
+        'providerConfigMutation',
+        'globalConfigMutation',
+    ];
     for (const key of strictKeys) {
         if (key in preflightOperation && key in requestedOperation && !jsonEqual(preflightOperation[key], requestedOperation[key]))
             return false;

package/dist/runs/task-scoped-command-grant-service.js

@@ -101,6 +101,7 @@ export class TaskScopedCommandGrantService {
             decision: 'allow',
             reason: 'task_scoped_grant',
             message: `Task-scoped grant ${consumed.value.id} authorizes this bounded external command preflight.`,
+            authorizationMode: 'task-scoped-grant',
             auditEvidence: [...(input.baseDecision.auditEvidence ?? []), `taskScopedGrant:${consumed.value.id}`, ...(evaluation.commandId === undefined ? [] : [`commandAllowlistId:${evaluation.commandId}`])],
         };
         return { ok: true, value: { authorized: true, decision, grant: consumed.value, evaluation, event: event.value } };

package/package.json

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