vgxness 1.20.2 → 1.20.4

package/dist/runs/sandbox-process-execution.js

@@ -1,7 +1,6 @@
 import { spawn, spawnSync } from 'node:child_process';
-import { realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { isAbsolute, resolve, sep } from 'node:path';
+import { isAbsolute, sep } from 'node:path';
+import { canonicalizeExistingPath, isPathInside, isProviderConfigPath } from '../permissions/path-boundaries.js';
 const defaultTimeoutMs = 10_000;
 const defaultOutputLimitBytes = 64 * 1024;
 const allowedEnvKey = /^[A-Z_][A-Z0-9_]*$/u;
@@ -13,10 +12,11 @@ export function buildSandboxExecutionPlan(request) {
     const cwd = realpathOrUndefined(request.cwd ?? request.workspaceRoot);
     if (cwd === undefined)
         return rejected('cwd-not-found', `Process cwd does not exist: ${request.cwd ?? request.workspaceRoot}`, workspaceRoot);
-    if (!isInside(cwd, workspaceRoot))
-        return rejected('cwd-escapes-workspace', `Process cwd escapes workspace boundary: ${request.cwd ?? request.workspaceRoot}`, workspaceRoot, cwd);
-    if (isProviderConfigPath(cwd, workspaceRoot))
-        return rejected('provider-config-cwd-rejected', `Process cwd targets provider/OpenCode config: ${request.cwd ?? request.workspaceRoot}`, workspaceRoot, cwd);
+    const externalCwd = externalCwdAuthorization({ cwd, workspaceRoot, request });
+    if (!externalCwd.ok)
+        return rejected(externalCwd.code, externalCwd.message, workspaceRoot, cwd, externalCwd.approvedExternalRoot, request.externalAuthorization);
+    if (isProviderConfigPathForAnyRoot(cwd, workspaceRoot, externalCwd.approvedExternalRoot))
+        return rejected('provider-config-cwd-rejected', `Process cwd targets provider/OpenCode config: ${request.cwd ?? request.workspaceRoot}`, workspaceRoot, cwd, externalCwd.approvedExternalRoot, request.externalAuthorization);
     if (request.command.length === 0)
         return rejected('empty-command', 'Process command is required.', workspaceRoot, cwd);
     if (isAbsolute(request.command) || request.command.includes(sep) || shellMetaCharacters.test(request.command)) {
@@ -31,9 +31,9 @@ export function buildSandboxExecutionPlan(request) {
     const targetPaths = request.targetPaths ?? [];
     if (!targetPaths.every((targetPath) => typeof targetPath === 'string'))
         return rejected('invalid-target-paths', 'Target paths must be an array of strings.', workspaceRoot, cwd);
-    const providerConfigTargetPath = targetPaths.find((targetPath) => isProviderConfigPath(targetPath, workspaceRoot));
+    const providerConfigTargetPath = targetPaths.find((targetPath) => isProviderConfigPathForAnyRoot(targetPath, workspaceRoot, cwd, externalCwd.approvedExternalRoot));
     if (providerConfigTargetPath !== undefined)
-        return rejected('provider-config-target-path-rejected', `Process plan target path targets provider/OpenCode config: ${providerConfigTargetPath}`, workspaceRoot, cwd);
+        return rejected('provider-config-target-path-rejected', `Process plan target path targets provider/OpenCode config: ${providerConfigTargetPath}`, workspaceRoot, cwd, externalCwd.approvedExternalRoot, request.externalAuthorization);
     const env = request.env ?? {};
     const envKeys = Object.keys(env).sort();
     const invalidEnvKey = envKeys.find((key) => !allowedEnvKey.test(key));
@@ -45,9 +45,9 @@ export function buildSandboxExecutionPlan(request) {
     const outputLimitBytes = request.outputLimitBytes ?? defaultOutputLimitBytes;
     if (!Number.isInteger(outputLimitBytes) || outputLimitBytes < 1 || outputLimitBytes > 1024 * 1024)
         return rejected('invalid-output-limit', 'Output limit must be an integer between 1 byte and 1 MiB.', workspaceRoot, cwd);
-    const evidence = acceptedEvidence(workspaceRoot, cwd, [
+    const evidence = acceptedEvidence(workspaceRoot, cwd, externalCwd.approvedExternalRoot, request.externalAuthorization, [
         'workspace-root-realpath-resolved',
-        'cwd-realpath-inside-workspace',
+        externalCwd.approvedExternalRoot === undefined ? 'cwd-realpath-inside-workspace' : 'cwd-realpath-inside-approved-external-root',
         'command-is-executable-name-not-shell-string',
         'command-allowlisted',
         'argv-array-only',
@@ -156,7 +156,7 @@ function bufferToLimitedString(buffer, limit) {
     const source = typeof buffer === 'string' ? Buffer.from(buffer) : buffer;
     return source.subarray(0, limit).toString('utf8');
 }
-function acceptedEvidence(workspaceRoot, cwd, checks) {
+function acceptedEvidence(workspaceRoot, cwd, approvedExternalRoot, externalAuthorization, checks) {
     return {
         strategy: 'bounded-process',
         enforceable: true,
@@ -169,6 +169,9 @@ function acceptedEvidence(workspaceRoot, cwd, checks) {
         providerConfigWritesBlocked: true,
         workspaceRoot,
         cwd,
+        externalCwdAuthorized: approvedExternalRoot !== undefined,
+        ...(approvedExternalRoot === undefined ? {} : { approvedExternalRoot }),
+        ...(externalAuthorization === undefined || approvedExternalRoot === undefined ? {} : { externalAuthorization }),
         capabilities: {
             sandboxEnforceable: false,
             processExecutionEnforceable: true,
@@ -193,32 +196,40 @@ function acceptedEvidence(workspaceRoot, cwd, checks) {
         validation: { accepted: true, checks },
     };
 }
-function rejected(code, message, workspaceRoot, cwd) {
+function rejected(code, message, workspaceRoot, cwd, approvedExternalRoot, externalAuthorization) {
     const evidence = workspaceRoot === undefined || cwd === undefined
         ? undefined
-        : { ...acceptedEvidence(workspaceRoot, cwd, []), enforceable: false, validation: { accepted: false, checks: [code] } };
+        : { ...acceptedEvidence(workspaceRoot, cwd, approvedExternalRoot, externalAuthorization, []), enforceable: false, validation: { accepted: false, checks: [code] } };
     return { ok: false, error: { code, message, ...(evidence === undefined ? {} : { evidence }) } };
 }
-function realpathOrUndefined(path) {
-    try {
-        return realpathSync.native(resolve(path));
+function externalCwdAuthorization(input) {
+    if (isInside(input.cwd, input.workspaceRoot))
+        return { ok: true };
+    if (input.request.externalAuthorization === undefined) {
+        return { ok: false, code: 'cwd-escapes-workspace', message: `Process cwd escapes workspace boundary: ${input.request.cwd ?? input.request.workspaceRoot}` };
     }
-    catch {
-        return undefined;
+    const roots = input.request.approvedExternalRoots ?? [];
+    for (const root of roots) {
+        const canonicalRoot = realpathOrUndefined(root);
+        if (canonicalRoot !== undefined && isInside(input.cwd, canonicalRoot))
+            return { ok: true, approvedExternalRoot: canonicalRoot };
     }
+    return {
+        ok: false,
+        code: 'cwd-not-approved-external-root',
+        message: `Process cwd is outside the workspace and not inside an approved external root: ${input.request.cwd ?? input.request.workspaceRoot}`,
+    };
 }
-function isInside(path, workspaceRoot) {
-    return path === workspaceRoot || path.startsWith(`${workspaceRoot}${sep}`);
-}
-function isProviderConfigPath(path, workspaceRoot) {
-    const absolutePath = resolve(workspaceRoot, path);
-    const projectOpenCodeDirectory = resolve(workspaceRoot, '.opencode');
-    if (absolutePath === projectOpenCodeDirectory || isInside(absolutePath, projectOpenCodeDirectory))
+function isProviderConfigPathForAnyRoot(path, workspaceRoot, ...additionalRoots) {
+    if (isProviderConfigPath(path, workspaceRoot))
         return true;
-    if (absolutePath === resolve(workspaceRoot, 'opencode.json') || absolutePath === resolve(workspaceRoot, 'opencode.jsonc'))
-        return true;
-    const userOpenCodeDirectory = resolve(homedir(), '.config', 'opencode');
-    return absolutePath === userOpenCodeDirectory || isInside(absolutePath, userOpenCodeDirectory);
+    return additionalRoots.some((root) => root !== undefined && isProviderConfigPath(path, root));
+}
+function realpathOrUndefined(path) {
+    return canonicalizeExistingPath(path);
+}
+function isInside(path, workspaceRoot) {
+    return isPathInside(path, workspaceRoot);
 }
 function limitedEnv(input) {
     const env = { PATH: process.env.PATH ?? '' };

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

@@ -0,0 +1,216 @@
+import { matchTaskScopedCommandGrant } from '../permissions/task-scoped-command-grant-matcher.js';
+import { validateTaskScopedCommandGrantCreationInput } from '../permissions/task-scoped-command-grant-validation.js';
+import { commandAllowlistIds } from '../workflows/command-allowlist-adapter.js';
+import { TaskScopedCommandGrantRepository } from './repositories/task-scoped-command-grants.js';
+import { RunRepository } from './repositories/runs.js';
+import { isTerminalRunStatus } from './schema.js';
+const grantableCategories = new Set(['shell', 'test-run', 'git']);
+export class TaskScopedCommandGrantService {
+    runs;
+    grants;
+    constructor(database) {
+        this.runs = new RunRepository(database);
+        this.grants = new TaskScopedCommandGrantRepository(database);
+    }
+    create(input) {
+        const run = this.runs.getById(input.runId);
+        if (!run.ok)
+            return run;
+        if (isTerminalRunStatus(run.value.status))
+            return validationFailure(`Cannot create task-scoped command grants for terminal run status: ${run.value.status}`);
+        if (input.agentId !== run.value.selectedAgentId)
+            return validationFailure('Grant agentId must match the run selected agent');
+        const validated = validateTaskScopedCommandGrantCreationInput(input, { knownAllowlistIds: commandAllowlistIds(), now: input.createdAt === undefined ? new Date() : new Date(input.createdAt) });
+        if (!validated.ok)
+            return validated;
+        const createInput = validated.value;
+        return this.grants.create(createInput);
+    }
+    list(filters = {}) {
+        return this.grants.list(filters);
+    }
+    get(id) {
+        return this.grants.get(id);
+    }
+    revoke(input) {
+        return this.grants.revoke(input);
+    }
+    previewMatch(input) {
+        return this.evaluateMatch(input, false);
+    }
+    tryAuthorizeAsk(input) {
+        if (input.baseDecision.decision !== 'ask')
+            return { ok: true, value: { authorized: false, evaluation: emptyEvaluation(false, ['base-decision-not-ask']) } };
+        const preview = this.evaluateMatch({
+            runId: input.run.id,
+            agentId: input.request.agentId ?? input.request.agent?.id ?? input.run.selectedAgentId,
+            category: input.request.category,
+            operation: input.request.operation,
+            ...(input.request.taskFingerprint === undefined ? {} : { taskFingerprint: input.request.taskFingerprint }),
+            ...(input.request.commandId === undefined ? {} : { commandId: input.request.commandId }),
+            ...(input.request.workspaceRoot === undefined ? {} : { workspaceRoot: input.request.workspaceRoot }),
+            ...(input.request.cwd === undefined ? {} : { cwd: input.request.cwd }),
+            ...taskGrantTargetPaths(input.request),
+            ...(input.request.destructive === undefined ? {} : { destructive: input.request.destructive }),
+            ...(input.request.privileged === undefined ? {} : { privileged: input.request.privileged }),
+            ...(input.request.ambiguous === undefined ? {} : { ambiguous: input.request.ambiguous }),
+            ...(input.now === undefined ? {} : { now: input.now }),
+        }, true);
+        if (!preview.ok)
+            return preview;
+        if (preview.value.selectedGrantId === undefined)
+            return { ok: true, value: { authorized: false, evaluation: preview.value } };
+        const before = this.grants.get(preview.value.selectedGrantId);
+        if (!before.ok)
+            return before;
+        const consumeInput = {
+            grantId: preview.value.selectedGrantId,
+            now: (input.now ?? new Date()).toISOString(),
+            ...(preview.value.commandId === undefined ? {} : { commandId: preview.value.commandId }),
+            ...(preview.value.canonicalCwd === undefined ? {} : { canonicalCwd: preview.value.canonicalCwd }),
+            ...(preview.value.matchedExternalRoot === undefined ? {} : { matchedExternalRoot: preview.value.matchedExternalRoot }),
+        };
+        const consumed = this.grants.consumeUse(consumeInput);
+        if (!consumed.ok) {
+            return {
+                ok: true,
+                value: {
+                    authorized: false,
+                    evaluation: { ...preview.value, matched: false, missReasons: [...new Set([...preview.value.missReasons, 'concurrent-consume-lost'])].sort() },
+                },
+            };
+        }
+        const evaluation = {
+            ...preview.value,
+            matched: true,
+            useCountBefore: before.value.usedCount,
+            useCountAfter: consumed.value.usedCount,
+        };
+        const event = this.runs.appendEvent({
+            runId: input.run.id,
+            kind: 'evidence',
+            title: 'Task-scoped command grant authorized preflight ask',
+            payload: grantEvaluationPayload(evaluation),
+            relatedType: 'task-scoped-command-grant',
+            relatedId: consumed.value.id,
+        });
+        if (!event.ok)
+            return { ok: false, error: event.error };
+        const decision = {
+            ...input.baseDecision,
+            decision: 'allow',
+            reason: 'task_scoped_grant',
+            message: `Task-scoped grant ${consumed.value.id} authorizes this bounded external command preflight.`,
+            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 } };
+    }
+    evaluateMatch(input, requireEligibleAskMetadata) {
+        const missing = requiredMissReasons(input);
+        if (missing.length > 0)
+            return { ok: true, value: emptyEvaluation(true, missing) };
+        if (!grantableCategories.has(input.category))
+            return { ok: true, value: emptyEvaluation(true, ['unsupported-category']) };
+        if (requireEligibleAskMetadata && (input.destructive === true || input.privileged === true || input.ambiguous === true)) {
+            return { ok: true, value: emptyEvaluation(true, ['hard-risk-override']) };
+        }
+        const run = this.runs.getById(input.runId);
+        if (!run.ok)
+            return run;
+        if (input.agentId !== run.value.selectedAgentId)
+            return { ok: true, value: emptyEvaluation(true, ['agent-mismatch']) };
+        const agentId = input.agentId;
+        const taskFingerprint = input.taskFingerprint;
+        const cwd = input.cwd;
+        const workspaceRoot = input.workspaceRoot;
+        if (agentId === undefined || taskFingerprint === undefined || cwd === undefined || workspaceRoot === undefined) {
+            return { ok: true, value: emptyEvaluation(true, requiredMissReasons(input)) };
+        }
+        const candidates = this.grants.list({ runId: input.runId, agentId, status: 'active' });
+        if (!candidates.ok)
+            return candidates;
+        const matched = matchTaskScopedCommandGrant({
+            request: {
+                runId: input.runId,
+                agentId,
+                taskFingerprint,
+                category: input.category,
+                operation: input.operation,
+                ...(input.commandId === undefined ? {} : { commandId: input.commandId }),
+                cwd,
+                ...(input.targetPaths === undefined ? {} : { targetPaths: input.targetPaths }),
+                ...(input.destructive === undefined ? {} : { destructive: input.destructive }),
+                ...(input.privileged === undefined ? {} : { privileged: input.privileged }),
+                ...(input.ambiguous === undefined ? {} : { ambiguous: input.ambiguous }),
+            },
+            candidates: candidates.value,
+            knownAllowlistIds: commandAllowlistIds(),
+            now: input.now ?? new Date(),
+            workspaceRoot,
+        });
+        return { ok: true, value: evaluationFromMatch(matched) };
+    }
+}
+export function grantEvaluationPayload(evaluation) {
+    return {
+        evaluated: evaluation.evaluated,
+        matched: evaluation.matched,
+        selectedGrantId: evaluation.selectedGrantId ?? null,
+        matchedGrantIds: evaluation.matchedGrantIds,
+        missReasons: evaluation.missReasons,
+        commandId: evaluation.commandId ?? null,
+        canonicalCwd: evaluation.canonicalCwd ?? null,
+        matchedExternalRoot: evaluation.matchedExternalRoot ?? null,
+        useCountBefore: evaluation.useCountBefore ?? null,
+        useCountAfter: evaluation.useCountAfter ?? null,
+        candidates: evaluation.candidates,
+    };
+}
+function evaluationFromMatch(match) {
+    return {
+        evaluated: true,
+        matched: match.selectedGrantId !== undefined,
+        ...(match.selectedGrantId === undefined ? {} : { selectedGrantId: match.selectedGrantId }),
+        matchedGrantIds: match.matchedGrantIds,
+        missReasons: match.missReasons,
+        ...(match.canonicalCwd === undefined ? {} : { canonicalCwd: match.canonicalCwd }),
+        ...(match.matchedExternalRoot === undefined ? {} : { matchedExternalRoot: match.matchedExternalRoot }),
+        ...(match.commandId === undefined ? {} : { commandId: match.commandId }),
+        candidates: match.candidates.map((candidate) => ({
+            grantId: candidate.grantId,
+            matched: candidate.matched,
+            selected: candidate.selected,
+            missReasons: candidate.missReasons,
+            commandId: candidate.commandId ?? null,
+            canonicalCwd: candidate.canonicalCwd ?? null,
+            matchedExternalRoot: candidate.matchedExternalRoot ?? null,
+        })),
+    };
+}
+function emptyEvaluation(evaluated, missReasons) {
+    return { evaluated, matched: false, matchedGrantIds: [], missReasons, candidates: [] };
+}
+function requiredMissReasons(input) {
+    const reasons = [];
+    if (input.runId.trim().length === 0)
+        reasons.push('missing-run-id');
+    if (input.agentId === undefined || input.agentId.trim().length === 0)
+        reasons.push('missing-agent-id');
+    if (input.taskFingerprint === undefined || input.taskFingerprint.trim().length === 0)
+        reasons.push('missing-task-fingerprint');
+    if (input.workspaceRoot === undefined || input.workspaceRoot.trim().length === 0)
+        reasons.push('missing-workspace-root');
+    if (input.cwd === undefined || input.cwd.trim().length === 0)
+        reasons.push('missing-cwd');
+    return reasons;
+}
+function taskGrantTargetPaths(request) {
+    if (request.targetPaths !== undefined)
+        return { targetPaths: request.targetPaths };
+    if (request.targetPath !== undefined)
+        return { targetPaths: [request.targetPath] };
+    return {};
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}

package/dist/sdd/sdd-continuation-plan.js

@@ -115,7 +115,7 @@ function draftPhaseAction(project, change, phase, reason) {
         id: `sdd.${change}.${phase}.draft`,
         label: `Prepare ${phase} draft through normal SDD phase flow`,
         title: `Prepare ${phase} draft`,
-        description: 'The next SDD phase appears runnable; draft generation must still use the normal phase workflow and any required preflight/confirmation gates.',
+        description: 'The next SDD phase appears runnable; draft generation must still use the normal phase workflow and any required preflight gates. After a valid phase artifact is produced, save it as a draft immediately, then ask the human acceptance/continue question before advancing.',
         kind: 'draft-phase',
         category: 'sdd-phase',
         phase,

package/dist/workflows/command-allowlist-adapter.js

@@ -43,6 +43,10 @@ export class CommandAllowlistAdapter {
             outputLimitBytes: entry.outputLimitBytes,
             targetPaths: options.targetPaths ?? [],
         };
+        if (options.approvedExternalRoots !== undefined && options.externalAuthorization !== undefined) {
+            this.request.approvedExternalRoots = options.approvedExternalRoots;
+            this.request.externalAuthorization = options.externalAuthorization;
+        }
         const plan = buildSandboxExecutionPlan(this.request);
         if (!plan.ok)
             throw new Error(`${plan.error.code}: ${plan.error.message}`);
@@ -67,6 +71,18 @@ export class CommandAllowlistAdapter {
             shellDisabled: result.value.evidence.shellDisabled,
             argvArrayOnly: result.value.evidence.argvArrayOnly,
             providerConfigWritesBlocked: result.value.evidence.providerConfigWritesBlocked,
+            externalCwdAuthorized: result.value.evidence.externalCwdAuthorized,
+            ...(result.value.evidence.approvedExternalRoot === undefined ? {} : { approvedExternalRoot: result.value.evidence.approvedExternalRoot }),
+            ...(result.value.evidence.externalAuthorization === undefined
+                ? {}
+                : {
+                    externalAuthorization: {
+                        kind: result.value.evidence.externalAuthorization.kind,
+                        grantId: result.value.evidence.externalAuthorization.grantId,
+                        runId: result.value.evidence.externalAuthorization.runId,
+                        agentId: result.value.evidence.externalAuthorization.agentId,
+                    },
+                }),
         };
         const output = {
             commandId: this.commandId,
@@ -136,6 +152,11 @@ export class AllowlistedApplyProgressCommandExecutor {
             const cwd = this.options.cwd ?? contract.value.cwd;
             if (cwd !== undefined)
                 adapterOptions.cwd = cwd;
+            const externalGrant = grantAuthorizationFromContract(request, contract.value);
+            if (externalGrant !== undefined) {
+                adapterOptions.approvedExternalRoots = externalGrant.approvedExternalRoots;
+                adapterOptions.externalAuthorization = externalGrant.externalAuthorization;
+            }
             if (this.options.allowlist !== undefined)
                 adapterOptions.allowlist = this.options.allowlist;
             if (this.options.runner !== undefined)
@@ -193,6 +214,9 @@ function applyProgressCommandContract(input) {
     const rawTargets = input.targetPaths;
     if (rawTargets !== undefined && (!Array.isArray(rawTargets) || !rawTargets.every((item) => typeof item === 'string')))
         return validationFailure('Allowlisted command targetPaths must be an array of strings.');
+    const grantEvaluation = parseGrantEvaluation(input.grantEvaluation);
+    if (!grantEvaluation.ok)
+        return grantEvaluation;
     return {
         ok: true,
         value: {
@@ -200,9 +224,35 @@ function applyProgressCommandContract(input) {
             ...(workspaceRoot === undefined ? {} : { workspaceRoot }),
             ...(cwd === undefined ? {} : { cwd }),
             targetPaths: rawTargets === undefined ? [] : rawTargets,
+            ...(grantEvaluation.value === undefined ? {} : { grantEvaluation: grantEvaluation.value }),
         },
     };
 }
+function parseGrantEvaluation(input) {
+    if (input === undefined)
+        return { ok: true, value: undefined };
+    if (!isObject(input))
+        return validationFailure('Allowlisted command grantEvaluation must be an object when provided.');
+    if (input.matched !== true)
+        return { ok: true, value: undefined };
+    if (typeof input.selectedGrantId !== 'string' || input.selectedGrantId.trim().length === 0)
+        return validationFailure('Matched allowlisted command grantEvaluation requires selectedGrantId.');
+    if (typeof input.matchedExternalRoot !== 'string' || input.matchedExternalRoot.trim().length === 0)
+        return validationFailure('Matched allowlisted command grantEvaluation requires matchedExternalRoot.');
+    return { ok: true, value: { matched: true, selectedGrantId: input.selectedGrantId, matchedExternalRoot: input.matchedExternalRoot } };
+}
+function grantAuthorizationFromContract(request, contract) {
+    const evaluation = contract.grantEvaluation;
+    if (evaluation === undefined)
+        return undefined;
+    const agentId = request.operation.agentId ?? request.operation.agent?.id;
+    if (agentId === undefined || agentId.trim().length === 0)
+        return undefined;
+    return {
+        approvedExternalRoots: [evaluation.matchedExternalRoot],
+        externalAuthorization: { kind: 'task-scoped-command-grant', grantId: evaluation.selectedGrantId, runId: request.runId, agentId },
+    };
+}
 function isObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/docs/safety.md

@@ -68,6 +68,29 @@ The experimental `vgxness code` runtime approval flow was removed with `src/code
 
 The gateway is conservative by default: a non-`read` tool in a non-`apply-progress` phase defaults to `ask`. Even with `--approval-policy allow`, the gateway can re-promote to `ask` for risky categories or workspace boundary issues.
 
+## Task-scoped external command grants
+
+Task-scoped command grants are a narrow V1 escape hatch for a human to authorize a bounded external working directory for an allowlisted command preflight. They only convert an eligible `ask` decision to an audited `allow`; they never convert `deny` or hard-risk requests to `allow`, and apply/implementation work still requires the normal SDD governance gates.
+
+Operator-facing grant commands live under the `runs` command surface:
+
+- `runs task-grant-create` creates an auditable, human-scoped grant lifecycle record through the run service.
+- `runs task-grant-list` lists grant metadata for an existing run scope.
+- `runs task-grant-get` reads one grant by ID.
+- `runs task-grant-revoke` revokes an existing grant without deleting its audit record.
+- `runs task-grant-preview` checks whether current grant metadata would match a proposed bounded command request.
+
+`task-grant-preview` is diagnostic only: it is read-only, does not authorize execution, does not consume grant usage, and does not append authorization evidence events. A negative preview is still a successful preview result (`matched: false`) when the input is valid.
+
+`task-grant-create` and `task-grant-revoke` are grant lifecycle mutations. They are auditable metadata operations, require explicit actor/reason context, and must go through `TaskScopedCommandGrantService`; they are not shortcuts around run preflight or SDD governance.
+
+Grant lifecycle commands never execute shell, test, or git commands. They only create, read, revoke, or preview grant records. The service remains the policy authority for run eligibility, categories, allowlisted command IDs, root/cwd matching, expiry, usage limits, and hard-risk exclusions.
+
+- V1 supports allowlisted command IDs only (`command-allowlist:<id>`). Arbitrary shell strings and executable path/argv grants are rejected.
+- Grantable categories are `shell`, `test-run`, and `git`. `install`, `network`, `secrets`, `external-directory`, `provider-tool`, `edit`, `implementation-edit`, `git-write`, and `memory-write` fail closed.
+- Every grant requires a human creation actor, at least one external root, a future expiry, and a positive `maxUses` limit. Preview matching is read-only and does not increment use count.
+- Grants cannot be created for terminal runs (`completed`, `failed`, `blocked`, `cancelled`), but existing grants may still be listed, read, or revoked for audit cleanup.
+
 ## Redaction
 
 Export redaction helpers remain in `src/export/redaction.ts`.

package/package.json

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