vgxness 1.20.3 → 1.20.4

package/dist/mcp/validation.js

@@ -2,6 +2,7 @@ import { isRiskyPermissionCategory, permissionCategories } from '../permissions/
 import { parseOperationRetryPolicy } from '../runs/operation-retry.js';
 import { normalizeSddPhaseInput, sddPhases } from '../sdd/schema.js';
 import { workflowIds } from '../workflows/schema.js';
+import { commandAllowlistIds } from '../workflows/command-allowlist-adapter.js';
 import { supportedTypeMessage, verificationChangeTypes } from '../verification/index.js';
 import { errorEnvelope, isVgxMcpToolName, } from './schema.js';
 const scopes = ['project', 'personal'];
@@ -9,6 +10,8 @@ const agentModes = ['agent', 'subagent'];
 const memoryTypes = ['architecture', 'decision', 'bugfix', 'pattern', 'config', 'discovery', 'learning', 'preference', 'manual'];
 const activityKinds = ['prompt', 'tool_call', 'artifact', 'summary', 'error'];
 const runStatuses = ['created', 'planned', 'running', 'needs-human', 'completed', 'failed', 'blocked', 'cancelled'];
+const taskGrantStatuses = ['active', 'revoked', 'expired', 'exhausted'];
+const taskGrantCategories = ['shell', 'test-run', 'git'];
 const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
 const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
 const permissionDecisions = ['allow', 'ask', 'deny'];
@@ -132,6 +135,16 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateRunGetInput(input, tool.value));
         case 'vgxness_run_preflight':
             return validationSuccess(tool.value, validateRunPreflightInput(input, tool.value));
+        case 'vgxness_run_task_grant_create':
+            return validationSuccess(tool.value, validateRunTaskGrantCreateInput(input, tool.value));
+        case 'vgxness_run_task_grant_list':
+            return validationSuccess(tool.value, validateRunTaskGrantListInput(input, tool.value));
+        case 'vgxness_run_task_grant_get':
+            return validationSuccess(tool.value, validateRunTaskGrantGetInput(input, tool.value));
+        case 'vgxness_run_task_grant_revoke':
+            return validationSuccess(tool.value, validateRunTaskGrantRevokeInput(input, tool.value));
+        case 'vgxness_run_task_grant_preview_match':
+            return validationSuccess(tool.value, validateRunTaskGrantPreviewMatchInput(input, tool.value));
         case 'vgxness_run_start':
             return validationSuccess(tool.value, validateRunStartInput(input, tool.value));
         case 'vgxness_run_checkpoint':
@@ -1565,6 +1578,10 @@ function validateRunPreflightInput(input, tool) {
         'agentId',
         'workspaceRoot',
         'targetPath',
+        'taskFingerprint',
+        'commandId',
+        'cwd',
+        'targetPaths',
         'providerToolName',
         'agent',
         'sandboxStrategy',
@@ -1590,9 +1607,14 @@ function validateRunPreflightInput(input, tool) {
         return workflow;
     if (workflow.value !== undefined)
         result.workflow = workflow.value;
-    const copied = copyOptionalStrings(result, record.value, tool, ['phase', 'agentId', 'workspaceRoot', 'targetPath', 'providerToolName']);
+    const copied = copyOptionalStrings(result, record.value, tool, ['phase', 'agentId', 'workspaceRoot', 'targetPath', 'taskFingerprint', 'commandId', 'cwd', 'providerToolName']);
     if (!copied.ok)
         return copied;
+    const targetPaths = readOptionalStringArray(record.value, 'targetPaths', tool);
+    if (!targetPaths.ok)
+        return targetPaths;
+    if (targetPaths.value !== undefined)
+        result.targetPaths = targetPaths.value;
     const sandboxStrategy = readOptionalOneOf(record.value, 'sandboxStrategy', ['worktree'], tool);
     if (!sandboxStrategy.ok)
         return sandboxStrategy;
@@ -1617,6 +1639,135 @@ function validateRunPreflightInput(input, tool) {
     }
     return { ok: true, value: result };
 }
+function validateRunTaskGrantCreateInput(input, tool) {
+    const record = inputRecord(input, tool, [
+        'runId',
+        'agentId',
+        'taskFingerprint',
+        'categories',
+        'externalRoots',
+        'cwdPatterns',
+        'commandPolicy',
+        'expiresAt',
+        'maxUses',
+        'createdBy',
+        'creationReason',
+        'approvedScopeSummary',
+    ]);
+    if (!record.ok)
+        return record;
+    const result = {};
+    const copied = copyRequiredStrings(result, record.value, tool, ['runId', 'agentId', 'taskFingerprint', 'expiresAt', 'creationReason', 'approvedScopeSummary']);
+    if (!copied.ok)
+        return copied;
+    const categories = readRequiredOneOfArray(record.value, 'categories', taskGrantCategories, tool);
+    if (!categories.ok)
+        return categories;
+    result.categories = categories.value;
+    const externalRoots = readRequiredStringArray(record.value, 'externalRoots', tool);
+    if (!externalRoots.ok)
+        return externalRoots;
+    result.externalRoots = externalRoots.value;
+    const cwdPatterns = readOptionalStringArray(record.value, 'cwdPatterns', tool);
+    if (!cwdPatterns.ok)
+        return cwdPatterns;
+    if (cwdPatterns.value !== undefined)
+        result.cwdPatterns = cwdPatterns.value;
+    const commandPolicy = readTaskGrantCommandPolicy(record.value.commandPolicy, tool);
+    if (!commandPolicy.ok)
+        return commandPolicy;
+    result.commandPolicy = commandPolicy.value;
+    const createdBy = readTaskGrantActor(record.value.createdBy, tool, ['human']);
+    if (!createdBy.ok)
+        return createdBy;
+    result.createdBy = createdBy.value;
+    if (typeof record.value.maxUses !== 'number' || !Number.isSafeInteger(record.value.maxUses) || record.value.maxUses < 1)
+        return validationFailure('maxUses must be a positive safe integer', tool);
+    result.maxUses = record.value.maxUses;
+    const expiresAt = Date.parse(result.expiresAt ?? '');
+    if (!Number.isFinite(expiresAt) || new Date(expiresAt).toISOString() !== result.expiresAt)
+        return validationFailure('expiresAt must be a valid ISO date', tool);
+    const expiryDelta = expiresAt - Date.now();
+    if (expiryDelta <= 0)
+        return validationFailure('expiresAt must be in the future', tool);
+    if (expiryDelta > 24 * 60 * 60 * 1000)
+        return validationFailure('expiresAt must be within 24 hours', tool);
+    return { ok: true, value: result };
+}
+function validateRunTaskGrantListInput(input, tool) {
+    const record = inputRecord(input, tool, ['runId', 'agentId', 'status', 'limit']);
+    if (!record.ok)
+        return record;
+    const result = {};
+    const copied = copyOptionalStrings(result, record.value, tool, ['runId', 'agentId']);
+    if (!copied.ok)
+        return copied;
+    const status = readOptionalOneOf(record.value, 'status', taskGrantStatuses, tool);
+    if (!status.ok)
+        return status;
+    if (status.value !== undefined)
+        result.status = status.value;
+    const limit = readOptionalBoundedLimit(record.value, tool);
+    if (!limit.ok)
+        return limit;
+    if (limit.value !== undefined)
+        result.limit = limit.value;
+    return { ok: true, value: result };
+}
+function validateRunTaskGrantGetInput(input, tool) {
+    const record = inputRecord(input, tool, ['grantId']);
+    if (!record.ok)
+        return record;
+    const grantId = readNonEmptyString(record.value, 'grantId', tool);
+    if (!grantId.ok)
+        return grantId;
+    return { ok: true, value: { grantId: grantId.value } };
+}
+function validateRunTaskGrantRevokeInput(input, tool) {
+    const record = inputRecord(input, tool, ['grantId', 'actor', 'reason']);
+    if (!record.ok)
+        return record;
+    const grantId = readNonEmptyString(record.value, 'grantId', tool);
+    if (!grantId.ok)
+        return grantId;
+    const reason = readNonEmptyString(record.value, 'reason', tool);
+    if (!reason.ok)
+        return reason;
+    const actor = readTaskGrantActor(record.value.actor, tool, ['human', 'system']);
+    if (!actor.ok)
+        return actor;
+    return { ok: true, value: { grantId: grantId.value, actor: actor.value, reason: reason.value } };
+}
+function validateRunTaskGrantPreviewMatchInput(input, tool) {
+    const record = inputRecord(input, tool, ['runId', 'agentId', 'taskFingerprint', 'category', 'operation', 'workspaceRoot', 'cwd', 'targetPaths']);
+    if (!record.ok)
+        return record;
+    const runId = readNonEmptyString(record.value, 'runId', tool);
+    if (!runId.ok)
+        return runId;
+    const taskFingerprint = readNonEmptyString(record.value, 'taskFingerprint', tool);
+    if (!taskFingerprint.ok)
+        return taskFingerprint;
+    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 cwd = readNonEmptyString(record.value, 'cwd', tool);
+    if (!cwd.ok)
+        return cwd;
+    const result = { runId: runId.value, taskFingerprint: taskFingerprint.value, category: category.value, operation: operation.value, cwd: cwd.value };
+    const copied = copyOptionalStrings(result, record.value, tool, ['agentId', 'workspaceRoot']);
+    if (!copied.ok)
+        return copied;
+    const targetPaths = readOptionalStringArray(record.value, 'targetPaths', tool);
+    if (!targetPaths.ok)
+        return targetPaths;
+    if (targetPaths.value !== undefined)
+        result.targetPaths = targetPaths.value;
+    return { ok: true, value: result };
+}
 function validateRunStartInput(input, tool) {
     const record = inputRecord(input, tool, ['project', 'userIntent', 'workflow', 'phase', 'selectedAgentId', 'providerAdapter', 'model']);
     if (!record.ok)
@@ -1905,6 +2056,68 @@ function readRequiredOneOf(record, field, values, tool) {
         return validationFailure(`${field} must be one of: ${values.join(', ')}`, tool);
     return { ok: true, value: value.value };
 }
+function readRequiredOneOfArray(record, field, values, tool) {
+    const array = readRequiredStringArray(record, field, tool);
+    if (!array.ok)
+        return array;
+    for (const item of array.value) {
+        if (!values.includes(item))
+            return validationFailure(`${field} must contain only: ${values.join(', ')}`, tool);
+    }
+    return { ok: true, value: array.value };
+}
+function readRequiredStringArray(record, field, tool) {
+    if (record[field] === undefined)
+        return validationFailure(`${field} is required`, tool);
+    const values = readOptionalStringArray(record, field, tool);
+    if (!values.ok)
+        return values;
+    if (values.value === undefined || values.value.length === 0)
+        return validationFailure(`${field} must contain at least one item`, tool);
+    if (new Set(values.value).size !== values.value.length)
+        return validationFailure(`${field} must be unique`, tool);
+    return { ok: true, value: values.value };
+}
+function readTaskGrantCommandPolicy(value, tool) {
+    const record = asRecord(value, tool, 'commandPolicy must be an object');
+    if (!record.ok)
+        return record;
+    const unexpected = Object.keys(record.value).find((key) => !['kind', 'ids'].includes(key));
+    if (unexpected !== undefined)
+        return validationFailure(`Unexpected commandPolicy field: ${unexpected}`, tool);
+    const kind = readRequiredOneOf(record.value, 'kind', ['allowlisted-command-ids'], tool);
+    if (!kind.ok)
+        return kind;
+    const ids = readRequiredStringArray(record.value, 'ids', tool);
+    if (!ids.ok)
+        return ids;
+    const known = new Set(commandAllowlistIds());
+    for (const id of ids.value)
+        if (!known.has(id))
+            return validationFailure(`Unknown allowlisted command id: ${id}`, tool);
+    return { ok: true, value: { kind: kind.value, ids: ids.value } };
+}
+function readTaskGrantActor(value, tool, allowedTypes) {
+    const record = asRecord(value, tool, '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 actor field: ${unexpected}`, tool);
+    const type = readRequiredOneOf(record.value, 'type', allowedTypes, tool);
+    if (!type.ok)
+        return type;
+    const id = readNonEmptyString(record.value, 'id', tool);
+    if (!id.ok)
+        return id;
+    const actor = { type: type.value, id: id.value };
+    const displayName = readOptionalNonEmptyString(record.value, 'displayName', tool);
+    if (!displayName.ok)
+        return displayName;
+    if (displayName.value !== undefined)
+        actor.displayName = displayName.value;
+    return { ok: true, value: actor };
+}
 function readOptionalOneOf(record, field, values, tool) {
     if (record[field] === undefined)
         return { ok: true, value: undefined };

package/dist/memory/sqlite/migrations/019_task_scoped_command_grants.sql

@@ -0,0 +1,37 @@
+CREATE TABLE IF NOT EXISTS task_scoped_command_grants (
+  id TEXT PRIMARY KEY,
+  run_id TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  task_fingerprint TEXT NOT NULL,
+
+  categories_json TEXT NOT NULL,
+  external_roots_json TEXT NOT NULL,
+  canonical_external_roots_json TEXT NOT NULL,
+  cwd_patterns_json TEXT,
+  command_policy_json TEXT NOT NULL,
+
+  expires_at TEXT NOT NULL,
+  max_uses INTEGER NOT NULL,
+  used_count INTEGER NOT NULL DEFAULT 0,
+  status TEXT NOT NULL,
+
+  created_by_json TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+
+  revoked_by_json TEXT,
+  revoked_at TEXT,
+  revoke_reason TEXT,
+
+  audit_json TEXT NOT NULL,
+
+  FOREIGN KEY(run_id) REFERENCES runs(id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_task_scoped_command_grants_run
+  ON task_scoped_command_grants(run_id);
+
+CREATE INDEX IF NOT EXISTS idx_task_scoped_command_grants_match
+  ON task_scoped_command_grants(run_id, agent_id, task_fingerprint, status);
+
+CREATE INDEX IF NOT EXISTS idx_task_scoped_command_grants_status
+  ON task_scoped_command_grants(status);

package/dist/permissions/path-boundaries.js

@@ -0,0 +1,87 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, resolve, sep } from 'node:path';
+export function canonicalizeExistingPath(path) {
+    try {
+        return realpathSync.native(resolve(path));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isPathInside(path, root) {
+    return path === root || path.startsWith(`${root}${sep}`);
+}
+export function resolveCanonicalContainedPath(input) {
+    const root = canonicalizeExistingPath(input.root);
+    if (root === undefined)
+        return { ok: false, reason: 'root-not-found' };
+    const requested = resolve(root, input.requestedPath);
+    const existing = canonicalizeExistingPath(requested);
+    if (existing !== undefined) {
+        if (!isPathInside(existing, root))
+            return { ok: false, reason: 'path-escapes-root' };
+        return { ok: true, value: { root, path: existing } };
+    }
+    if (!input.allowNonexistentLeaf)
+        return { ok: false, reason: 'path-not-found' };
+    const nearest = nearestExistingAncestor(requested);
+    if (nearest === undefined)
+        return { ok: false, reason: 'path-ancestor-not-found' };
+    const canonicalAncestor = canonicalizeExistingPath(nearest);
+    if (canonicalAncestor === undefined)
+        return { ok: false, reason: 'path-ancestor-not-found' };
+    if (!isPathInside(canonicalAncestor, root))
+        return { ok: false, reason: 'path-escapes-root' };
+    const suffix = requested.slice(nearest.length).replace(/^[/\\]+/u, '').split(/[\\/]+/u).filter(Boolean);
+    const canonicalPath = resolve(canonicalAncestor, ...suffix);
+    if (!isPathInside(canonicalPath, root))
+        return { ok: false, reason: 'path-escapes-root' };
+    return { ok: true, value: { root, path: canonicalPath } };
+}
+export function validateSafeGrantRoot(rootPath) {
+    if (!isAbsolute(rootPath))
+        return { ok: false, reason: 'grant-root-relative' };
+    const canonicalRoot = canonicalizeExistingPath(rootPath);
+    if (canonicalRoot === undefined)
+        return { ok: false, reason: 'grant-root-not-found' };
+    const home = canonicalizeExistingPath(homedir()) ?? resolve(homedir());
+    if (canonicalRoot === resolve(sep))
+        return { ok: false, reason: 'grant-root-filesystem-root' };
+    if (canonicalRoot === home)
+        return { ok: false, reason: 'grant-root-home-directory' };
+    if (basename(canonicalRoot) === '.opencode' || basename(canonicalRoot) === '.claude')
+        return { ok: false, reason: 'grant-root-provider-config' };
+    if (basename(canonicalRoot) === 'opencode.json' || basename(canonicalRoot) === 'opencode.jsonc')
+        return { ok: false, reason: 'grant-root-provider-config' };
+    if (isProviderConfigPath(canonicalRoot, process.cwd()))
+        return { ok: false, reason: 'grant-root-provider-config' };
+    return { ok: true, value: { canonicalRoot } };
+}
+export function isUnsafeGrantRoot(rootPath) {
+    return !validateSafeGrantRoot(rootPath).ok;
+}
+export function isProviderConfigPath(path, workspaceRoot) {
+    const workspace = resolve(workspaceRoot);
+    const absolutePath = isAbsolute(path) ? resolve(path) : resolve(workspace, path);
+    const projectOpenCodeDirectory = resolve(workspace, '.opencode');
+    if (absolutePath === projectOpenCodeDirectory || isPathInside(absolutePath, projectOpenCodeDirectory))
+        return true;
+    if (absolutePath === resolve(workspace, 'opencode.json') || absolutePath === resolve(workspace, 'opencode.jsonc'))
+        return true;
+    const userOpenCodeDirectory = resolve(homedir(), '.config', 'opencode');
+    if (absolutePath === userOpenCodeDirectory || isPathInside(absolutePath, userOpenCodeDirectory))
+        return true;
+    const userClaudeDirectory = resolve(homedir(), '.claude');
+    return absolutePath === userClaudeDirectory || isPathInside(absolutePath, userClaudeDirectory);
+}
+function nearestExistingAncestor(path) {
+    let current = resolve(path);
+    while (!existsSync(current)) {
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return current;
+}

package/dist/permissions/task-scoped-command-grant-matcher.js

@@ -0,0 +1,117 @@
+import { canonicalizeExistingPath, isPathInside, isProviderConfigPath, resolveCanonicalContainedPath } from './path-boundaries.js';
+const grantableCategories = new Set(['shell', 'test-run', 'git']);
+export function matchTaskScopedCommandGrant(input) {
+    const known = new Set(input.knownAllowlistIds);
+    const commandId = input.request.commandId ?? commandIdFromOperation(input.request.operation);
+    const hardMissReasons = hardRequestMissReasons(input.request, commandId, known);
+    const candidateEvidence = input.candidates.map((grant) => evaluateCandidate({ ...input, commandId, hardMissReasons, grant }));
+    const matched = candidateEvidence.filter((candidate) => candidate.matched);
+    const sorted = [...matched].sort((left, right) => compareMatchedCandidates(left.grantId, right.grantId, input.candidates));
+    const selectedGrantId = sorted[0]?.grantId;
+    const candidates = candidateEvidence.map((candidate) => ({ ...candidate, selected: candidate.grantId === selectedGrantId }));
+    const selected = candidates.find((candidate) => candidate.selected);
+    const result = {
+        matchedGrantIds: matched.map((candidate) => candidate.grantId).sort(),
+        selectedOrder: sorted.map((candidate) => candidate.grantId),
+        missReasons: collectMissReasons(candidates),
+        candidates,
+    };
+    if (selectedGrantId !== undefined)
+        result.selectedGrantId = selectedGrantId;
+    if (selected?.canonicalCwd !== undefined)
+        result.canonicalCwd = selected.canonicalCwd;
+    if (selected?.matchedExternalRoot !== undefined)
+        result.matchedExternalRoot = selected.matchedExternalRoot;
+    if (commandId !== undefined)
+        result.commandId = commandId;
+    return result;
+}
+function evaluateCandidate(input) {
+    const missReasons = [...input.hardMissReasons];
+    const grant = input.grant;
+    if (grant.status !== 'active')
+        missReasons.push(`${grant.status}-grant`);
+    if (Date.parse(grant.expiresAt) <= input.now.getTime())
+        missReasons.push('expired');
+    if (grant.usedCount >= grant.maxUses)
+        missReasons.push('exhausted');
+    if (grant.runId !== input.request.runId)
+        missReasons.push('run-mismatch');
+    if (grant.agentId !== input.request.agentId)
+        missReasons.push('agent-mismatch');
+    if (grant.taskFingerprint !== input.request.taskFingerprint)
+        missReasons.push('task-fingerprint-mismatch');
+    if (!grant.categories.some((category) => category === input.request.category))
+        missReasons.push('category-mismatch');
+    if (input.commandId === undefined || !grant.commandPolicy.ids.includes(input.commandId))
+        missReasons.push('command-mismatch');
+    const rootMatch = matchRootForRequest(grant.canonicalExternalRoots, input.request.cwd, input.request.targetPaths ?? [], input.workspaceRoot);
+    if (!rootMatch.ok)
+        missReasons.push(rootMatch.reason);
+    const evidence = {
+        grantId: grant.id,
+        matched: missReasons.length === 0,
+        selected: false,
+        missReasons,
+    };
+    if (rootMatch.ok) {
+        evidence.canonicalCwd = rootMatch.value.canonicalCwd;
+        evidence.matchedExternalRoot = rootMatch.value.matchedExternalRoot;
+    }
+    if (input.commandId !== undefined)
+        evidence.commandId = input.commandId;
+    return evidence;
+}
+function hardRequestMissReasons(request, commandId, knownAllowlistIds) {
+    const reasons = [];
+    if (!grantableCategories.has(request.category))
+        reasons.push('unsupported-category');
+    if (request.destructive === true)
+        reasons.push('destructive-operation');
+    if (request.privileged === true)
+        reasons.push('privileged-operation');
+    if (request.ambiguous === true)
+        reasons.push('ambiguous-operation');
+    if (commandId === undefined)
+        reasons.push('missing-command-id');
+    else if (!knownAllowlistIds.has(commandId))
+        reasons.push('unknown-command-id');
+    return reasons;
+}
+function matchRootForRequest(canonicalRoots, cwd, targetPaths, workspaceRoot) {
+    if (isProviderConfigPath(cwd, workspaceRoot))
+        return { ok: false, reason: 'provider-config-path-blocked' };
+    const canonicalCwd = canonicalizeExistingPath(cwd);
+    if (canonicalCwd === undefined)
+        return { ok: false, reason: 'cwd-not-found' };
+    if (isProviderConfigPath(canonicalCwd, workspaceRoot))
+        return { ok: false, reason: 'provider-config-path-blocked' };
+    const matchedRoot = canonicalRoots.find((root) => isPathInside(canonicalCwd, root));
+    if (matchedRoot === undefined)
+        return { ok: false, reason: 'cwd-root-mismatch' };
+    for (const targetPath of targetPaths) {
+        if (isProviderConfigPath(targetPath, workspaceRoot))
+            return { ok: false, reason: 'provider-config-path-blocked' };
+        const resolved = resolveCanonicalContainedPath({ root: matchedRoot, requestedPath: targetPath, allowNonexistentLeaf: true });
+        if (!resolved.ok)
+            return { ok: false, reason: 'target-root-mismatch' };
+        if (isProviderConfigPath(resolved.value.path, workspaceRoot))
+            return { ok: false, reason: 'provider-config-path-blocked' };
+    }
+    return { ok: true, value: { canonicalCwd, matchedExternalRoot: matchedRoot } };
+}
+function compareMatchedCandidates(leftId, rightId, grants) {
+    const left = grants.find((grant) => grant.id === leftId);
+    const right = grants.find((grant) => grant.id === rightId);
+    if (left === undefined || right === undefined)
+        return leftId.localeCompare(rightId);
+    return Date.parse(left.expiresAt) - Date.parse(right.expiresAt) || Date.parse(left.createdAt) - Date.parse(right.createdAt) || left.id.localeCompare(right.id);
+}
+function collectMissReasons(candidates) {
+    if (candidates.length === 0)
+        return ['no-candidates'];
+    return [...new Set(candidates.flatMap((candidate) => candidate.missReasons))].sort();
+}
+function commandIdFromOperation(operation) {
+    return /^command-allowlist:([A-Za-z0-9._/-]+)$/u.exec(operation)?.[1];
+}

package/dist/permissions/task-scoped-command-grant-validation.js

@@ -0,0 +1,135 @@
+import { validateSafeGrantRoot } from './path-boundaries.js';
+const grantableCategories = new Set(['shell', 'test-run', 'git']);
+const rejectedCategories = new Set([
+    'secrets',
+    'external-directory',
+    'provider-tool',
+    'edit',
+    'implementation-edit',
+    'git-write',
+    'memory-write',
+    'install',
+    'network',
+]);
+const maxExpiryMs = 24 * 60 * 60 * 1000;
+export function validateTaskScopedCommandGrantCreationInput(input, options) {
+    if (!input.runId.trim())
+        return validationFailure('Grant runId is required');
+    if (!input.agentId.trim())
+        return validationFailure('Grant agentId is required');
+    if (!input.taskFingerprint.trim())
+        return validationFailure('Grant taskFingerprint is required');
+    if (input.createdBy.type !== 'human')
+        return validationFailure('Grant creator must be a human actor');
+    if (!input.createdBy.id.trim())
+        return validationFailure('Grant creator id is required');
+    const categories = validateCategories(input.categories);
+    if (!categories.ok)
+        return categories;
+    const commandPolicy = validateCommandPolicy(input.commandPolicy, options.knownAllowlistIds);
+    if (!commandPolicy.ok)
+        return commandPolicy;
+    const cwdPatterns = validateOptionalStringList(input.cwdPatterns, 'Grant cwdPatterns');
+    if (!cwdPatterns.ok)
+        return cwdPatterns;
+    const expiry = validateExpiry(input.expiresAt, options.now);
+    if (!expiry.ok)
+        return expiry;
+    if (!Number.isInteger(input.maxUses) || input.maxUses < 1)
+        return validationFailure('Grant maxUses must be a positive integer');
+    if (!input.audit.creationReason.trim())
+        return validationFailure('Grant audit creationReason is required');
+    if (!input.audit.approvedScopeSummary.trim())
+        return validationFailure('Grant audit approvedScopeSummary is required');
+    if (input.externalRoots.length === 0)
+        return validationFailure('Grant externalRoots are required');
+    const canonicalExternalRoots = [];
+    for (const root of input.externalRoots) {
+        const safe = validateSafeGrantRoot(root);
+        if (!safe.ok)
+            return validationFailure(`Grant external root is unsafe: ${safe.reason}`);
+        canonicalExternalRoots.push(safe.value.canonicalRoot);
+    }
+    if (new Set(canonicalExternalRoots).size !== canonicalExternalRoots.length)
+        return validationFailure('Grant external roots must be unique');
+    const createdBy = { type: 'human', id: input.createdBy.id.trim() };
+    const validated = {
+        runId: input.runId,
+        agentId: input.agentId,
+        taskFingerprint: input.taskFingerprint,
+        categories: categories.value,
+        externalRoots: input.externalRoots,
+        canonicalExternalRoots,
+        commandPolicy: commandPolicy.value,
+        expiresAt: input.expiresAt,
+        maxUses: input.maxUses,
+        createdBy,
+        audit: input.audit,
+    };
+    if (cwdPatterns.value !== undefined)
+        validated.cwdPatterns = cwdPatterns.value;
+    if (input.createdBy.displayName !== undefined)
+        validated.createdBy.displayName = input.createdBy.displayName;
+    return ok(validated);
+}
+function validateCategories(categories) {
+    if (!Array.isArray(categories) || categories.length === 0)
+        return validationFailure('Grant categories are required');
+    if (new Set(categories).size !== categories.length)
+        return validationFailure('Grant categories must be unique');
+    for (const category of categories) {
+        if (rejectedCategories.has(category))
+            return validationFailure(`Unsupported grant category: ${category}`);
+        if (!grantableCategories.has(category))
+            return validationFailure(`Unsupported grant category: ${category}`);
+    }
+    return ok(categories);
+}
+function validateCommandPolicy(policy, knownAllowlistIds) {
+    if (!isRecord(policy))
+        return validationFailure('Grant command policy is required');
+    if (policy.kind !== 'allowlisted-command-ids')
+        return validationFailure('Grant command policy must use allowlisted command ids');
+    if (!Array.isArray(policy.ids) || policy.ids.length === 0)
+        return validationFailure('Grant command policy ids are required');
+    if (!policy.ids.every((id) => typeof id === 'string' && id.trim().length > 0))
+        return validationFailure('Grant command policy ids must be non-empty strings');
+    if (new Set(policy.ids).size !== policy.ids.length)
+        return validationFailure('Grant command policy ids must be unique');
+    const known = new Set(knownAllowlistIds);
+    for (const id of policy.ids)
+        if (!known.has(id))
+            return validationFailure(`Unknown allowlisted command id: ${id}`);
+    return ok({ kind: 'allowlisted-command-ids', ids: policy.ids });
+}
+function validateOptionalStringList(values, label) {
+    if (values === undefined)
+        return ok(undefined);
+    if (!Array.isArray(values))
+        return validationFailure(`${label} must be an array when provided`);
+    if (!values.every((value) => typeof value === 'string' && value.trim().length > 0))
+        return validationFailure(`${label} must contain non-empty strings`);
+    if (new Set(values).size !== values.length)
+        return validationFailure(`${label} must be unique`);
+    return ok(values);
+}
+function validateExpiry(expiresAt, now) {
+    const timestamp = Date.parse(expiresAt);
+    if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== expiresAt)
+        return validationFailure('Grant expiresAt must be a valid ISO date');
+    const delta = timestamp - now.getTime();
+    if (delta <= 0)
+        return validationFailure('Grant expiresAt must be in the future');
+    if (delta > maxExpiryMs)
+        return validationFailure('Grant expiresAt must be within 24 hours');
+    return ok(undefined);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function ok(value) {
+    return { ok: true, value };
+}
+function validationFailure(message) {
+    return { ok: false, error: { code: 'validation_failed', message } };
+}