@pixelbyte-software/pixcode 1.42.3 → 1.42.5

package/scripts/smoke/permission-policy.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+const policy = read('server/modules/orchestration/security/permission-policy.ts');
+assert.match(policy, /PIXCODE_PERMISSION_POLICY_PROTOCOL/, 'Permission policy should declare a stable protocol id.');
+assert.match(policy, /pixcode\.permission-policy\.v1/, 'Permission policy should use the v1 protocol id.');
+assert.match(policy, /shell/, 'Permission policy should classify shell access.');
+assert.match(policy, /file_write/, 'Permission policy should classify file-write access.');
+assert.match(policy, /external_directory/, 'Permission policy should classify external directory access.');
+assert.match(policy, /network/, 'Permission policy should classify network access.');
+assert.match(policy, /secret/, 'Permission policy should classify secret access.');
+assert.match(policy, /evaluatePermissionRequest/, 'Permission policy should expose a shared evaluator.');
+assert.match(policy, /createPermissionApprovalRequest/, 'Permission policy should create pending approval artifacts.');
+assert.match(policy, /redactPermissionText/, 'Permission policy should redact local paths and secrets.');
+
+const runner = read('server/modules/orchestration/workflows/workflow-runner.ts');
+assert.match(runner, /evaluatePermissionRequest/, 'Workflow runner should route node preflight through the shared policy evaluator.');
+assert.match(runner, /permissionPolicyEvents/, 'Workflow runner should store permission policy audit events.');
+assert.match(runner, /pendingPermissionApprovals/, 'Workflow runner should preserve pending approval context on the run.');
+
+const trace = read('server/modules/orchestration/workflows/workflow-trace.ts');
+assert.match(trace, /workflow\.trace\.permissionPolicy/, 'Trace timeline should surface permission policy decisions.');
+assert.match(trace, /permission_policy/, 'Trace events should include permission policy entries.');
+
+const routes = read('server/modules/orchestration/workflows/workflow.routes.ts');
+assert.match(routes, /permission-policy/, 'Workflow routes should expose the policy contract.');
+assert.match(routes, /permission-approvals/, 'Workflow routes should expose pending approval context.');
+
+const claude = read('server/claude-sdk.js');
+assert.match(claude, /evaluatePermissionRequest/, 'Claude tool approvals should use the shared policy evaluator.');
+assert.match(claude, /permissionPolicy/, 'Claude runtime should accept policy metadata.');
+
+const a2aContext = read('server/modules/orchestration/a2a/adapters/abstract-a2a.adapter.ts');
+assert.match(a2aContext, /permissionPolicy/, 'A2A adapter context should carry the shared permission policy.');
+
+const en = read('src/i18n/locales/en/common.json');
+const tr = read('src/i18n/locales/tr/common.json');
+assert.match(en, /"permission_policy"/, 'English trace type for permission policy is missing.');
+assert.match(tr, /"permission_policy"/, 'Turkish trace type for permission policy is missing.');
+
+console.log('permission-policy smoke passed');

package/scripts/smoke/workflow-templates.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function read(relativePath) {
+  return fs.readFileSync(path.join(root, relativePath), 'utf8');
+}
+
+const templates = read('server/modules/orchestration/workflows/workflow-templates.ts');
+assert.match(templates, /PIXCODE_WORKFLOW_TEMPLATE_PROTOCOL/, 'Workflow templates should declare a stable protocol id.');
+assert.match(templates, /pixcode\.workflow-template\.v1/, 'Workflow templates should use the v1 protocol id.');
+assert.match(templates, /bug_fix_team/, 'Bug fix team template is missing.');
+assert.match(templates, /pr_review_team/, 'PR review team template is missing.');
+assert.match(templates, /frontend_polish/, 'Frontend polish template is missing.');
+assert.match(templates, /release_manager/, 'Release manager template is missing.');
+assert.match(templates, /dependency_audit/, 'Dependency audit template is missing.');
+assert.match(templates, /agentSlots/, 'Templates should use provider-independent agent slots.');
+assert.match(templates, /acceptanceCriteria/, 'Templates should include acceptance criteria.');
+assert.match(templates, /applyWorkflowTemplateToMetadata/, 'Templates should be applicable to run metadata.');
+
+const routes = read('server/modules/orchestration/workflows/workflow.routes.ts');
+assert.match(routes, /workflows\/templates/, 'Workflow routes should expose templates.');
+assert.match(routes, /WORKFLOW_TEMPLATE_NOT_FOUND/, 'Workflow template start route should validate template ids.');
+assert.match(routes, /applyWorkflowTemplateToMetadata/, 'Workflow routes should apply templates before starting runs.');
+
+const trace = read('server/modules/orchestration/workflows/workflow-trace.ts');
+assert.match(trace, /workflow\.trace\.template/, 'Trace timeline should surface template metadata.');
+
+const page = read('src/components/orchestration/OrchestrationPage.tsx');
+assert.match(page, /WorkflowTemplate/, 'Orchestration page should type workflow templates.');
+assert.match(page, /applyTemplate/, 'Orchestration page should let users apply a template before launch.');
+assert.match(page, /workflowTemplate/, 'Template run metadata should be sent with orchestration runs.');
+
+const en = read('src/i18n/locales/en/common.json');
+const tr = read('src/i18n/locales/tr/common.json');
+assert.match(en, /"templates"/, 'English template UI label is missing.');
+assert.match(tr, /"templates"/, 'Turkish template UI label is missing.');
+
+console.log('workflow templates smoke passed');

package/server/claude-sdk.js

@@ -29,6 +29,7 @@ import { sessionsService } from './modules/providers/services/sessions.service.j
 import { providerAuthService } from './modules/providers/services/provider-auth.service.js';
 import { resolveClaudeExecutable, resolveGitBashPath } from './services/install-jobs.js';
 import { createNormalizedMessage } from './shared/utils.js';
+import { evaluatePermissionRequest } from './modules/orchestration/security/permission-policy.js';
 
 const activeSessions = new Map();
 const pendingToolApprovals = new Map();
@@ -184,7 +185,7 @@ function loadClaudeSettingsEnv(cwd) {
  * @returns {Object} SDK-compatible options
  */
 function mapCliOptionsToSDK(options = {}) {
-  const { sessionId, cwd, toolsSettings, permissionMode } = options;
+  const { sessionId, cwd, toolsSettings, permissionMode, permissionPolicy, permissionPolicyContext } = options;
 
   const sdkOptions = {};
 
@@ -231,6 +232,8 @@ function mapCliOptionsToSDK(options = {}) {
   if (permissionMode && permissionMode !== 'default') {
     sdkOptions.permissionMode = permissionMode;
   }
+  sdkOptions.permissionPolicy = permissionPolicy;
+  sdkOptions.permissionPolicyContext = permissionPolicyContext;
 
   // Map tool settings
   const settings = toolsSettings || {
@@ -595,8 +598,27 @@ async function queryClaudeSDK(command, options = {}, ws) {
 
     sdkOptions.canUseTool = async (toolName, input, context) => {
       const requiresInteraction = TOOLS_REQUIRING_INTERACTION.has(toolName);
+      const policyDecision = evaluatePermissionRequest({
+        policy: sdkOptions.permissionPolicy,
+        request: {
+          source: 'provider_tool',
+          toolName,
+          input,
+          command: input && typeof input === 'object' && typeof input.command === 'string'
+            ? input.command
+            : undefined,
+          cwd: options.cwd,
+          workspacePath: options.cwd,
+          summary: `${toolName} tool request`,
+        },
+        context: sdkOptions.permissionPolicyContext,
+      });
+
+      if (policyDecision.behavior === 'deny') {
+        return { behavior: 'deny', message: policyDecision.message };
+      }
 
-      if (!requiresInteraction) {
+      if (!requiresInteraction && policyDecision.behavior !== 'prompt') {
         if (sdkOptions.permissionMode === 'bypassPermissions') {
           return { behavior: 'allow', updatedInput: input };
         }

package/server/modules/orchestration/a2a/adapters/abstract-a2a.adapter.ts

@@ -13,6 +13,10 @@ import type {
   TaskState,
 } from '@/modules/orchestration/a2a/types.js';
 import type { WorkspaceHandle } from '@/modules/orchestration/workspace/types.js';
+import type {
+  PermissionPolicy,
+  PermissionPolicyContext,
+} from '@/modules/orchestration/security/permission-policy.js';
 
 export interface AdapterContext {
   /** Isolated execution workspace for the task. */
@@ -21,6 +25,10 @@ export interface AdapterContext {
   cwd: string;
   /** pixcode permission mode passed through to the underlying CLI. */
   permissionMode?: string;
+  /** Provider-independent permission/sandbox policy evaluated before runtime tool use. */
+  permissionPolicy?: PermissionPolicy;
+  /** Run context preserved when the policy needs a human approval. */
+  permissionPolicyContext?: PermissionPolicyContext;
   /** Provider model selected by the user in Pixcode. */
   model?: string;
   /** Provider-specific tool / permission settings from Pixcode Settings. */

package/server/modules/orchestration/a2a/adapters/claude-code.adapter.ts

@@ -99,6 +99,8 @@ export class ClaudeCodeA2AAdapter extends AbstractA2AAdapter {
           {
             cwd: ctx.cwd,
             permissionMode: ctx.permissionMode ?? 'default',
+            permissionPolicy: ctx.permissionPolicy,
+            permissionPolicyContext: ctx.permissionPolicyContext,
             toolsSettings: ctx.toolsSettings,
           },
           fakeWS,

package/server/modules/orchestration/a2a/routes.ts

@@ -31,6 +31,10 @@ import type {
   WorkspaceMetadata,
 } from '@/modules/orchestration/workspace/types.js';
 import { WorkspaceError } from '@/modules/orchestration/workspace/types.js';
+import type {
+  PermissionPolicy,
+  PermissionPolicyContext,
+} from '@/modules/orchestration/security/permission-policy.js';
 
 type RoutingHints = {
   preferredAdapterId?: string;
@@ -475,6 +479,8 @@ export function createA2ARouter(): Router {
         workspace,
         model: readString(metadata?.model),
         permissionMode: readString(metadata?.permissionMode),
+        permissionPolicy: readObject(metadata?.permissionPolicy) as PermissionPolicy | undefined,
+        permissionPolicyContext: readObject(metadata?.permissionPolicyContext) as PermissionPolicyContext | undefined,
         toolsSettings: readObject(metadata?.toolsSettings),
       });
     } catch (err) {

package/server/modules/orchestration/index.ts

@@ -19,9 +19,24 @@ export { AbstractA2AAdapter } from './a2a/adapters/abstract-a2a.adapter.js';
 export { a2aBus } from './a2a/bus.js';
 export { portWatcher } from './preview/port-watcher.js';
 export { createPreviewProxyRouter } from './preview/preview-proxy.js';
+export {
+  DEFAULT_PERMISSION_POLICY,
+  PERMISSION_CAPABILITIES,
+  PERMISSION_POLICY_MODES,
+  PIXCODE_PERMISSION_POLICY_PROTOCOL,
+  evaluatePermissionRequest,
+  normalizePermissionPolicy,
+  resolvePermissionPolicyFromMetadata,
+} from './security/permission-policy.js';
 export { createOrchestrationTaskRouter } from './tasks/orchestration-task.routes.js';
 export { orchestrationTaskService } from './tasks/orchestration-task.service.js';
 export { createWorkflowRouter } from './workflows/workflow.routes.js';
+export {
+  PIXCODE_WORKFLOW_TEMPLATE_PROTOCOL,
+  applyWorkflowTemplateToMetadata,
+  builtInWorkflowTemplates,
+  getWorkflowTemplate,
+} from './workflows/workflow-templates.js';
 export { workflowRunner } from './workflows/workflow-runner.js';
 export { workflowStore } from './workflows/workflow-store.js';
 export { workspaceManager } from './workspace/workspace-manager.js';
@@ -42,12 +57,25 @@ export type {
   PortEvent,
   PreviewArtifactData,
 } from './preview/types.js';
+export type {
+  PermissionApprovalRequest,
+  PermissionCapability,
+  PermissionDecision,
+  PermissionPolicy,
+  PermissionPolicyContext,
+  PermissionPolicyEvent,
+  PermissionPolicyMode,
+} from './security/permission-policy.js';
 export type {
   CreateOrchestrationTaskInput,
   DispatchOrchestrationTaskInput,
   OrchestrationTask,
   OrchestrationTaskState,
 } from './tasks/orchestration-task.types.js';
+export type {
+  WorkflowTemplate,
+  WorkflowTemplateAgentSlot,
+} from './workflows/workflow-templates.js';
 export type {
   Workflow,
   WorkflowNode,

package/server/modules/orchestration/security/permission-policy.ts

@@ -0,0 +1,401 @@
+import os from 'node:os';
+import path from 'node:path';
+
+export const PIXCODE_PERMISSION_POLICY_PROTOCOL = 'pixcode.permission-policy.v1' as const;
+
+export const PERMISSION_CAPABILITIES = [
+  'shell',
+  'file_write',
+  'external_directory',
+  'network',
+  'secret',
+] as const;
+
+export const PERMISSION_POLICY_MODES = ['allow', 'deny', 'prompt', 'audit'] as const;
+
+export type PermissionCapability = typeof PERMISSION_CAPABILITIES[number];
+export type PermissionPolicyMode = typeof PERMISSION_POLICY_MODES[number];
+export type PermissionDecisionStatus = 'allowed' | 'denied' | 'needs_approval';
+
+export interface PermissionPolicy {
+  protocol: typeof PIXCODE_PERMISSION_POLICY_PROTOCOL;
+  modes: Record<PermissionCapability, PermissionPolicyMode>;
+  allowedExternalDirectories: string[];
+  audit: boolean;
+}
+
+export interface PermissionRequest {
+  requestId?: string;
+  source: 'workflow_node' | 'provider_tool' | 'api' | 'shell' | 'file' | string;
+  capability?: PermissionCapability;
+  capabilities?: PermissionCapability[];
+  toolName?: string;
+  command?: string;
+  input?: unknown;
+  cwd?: string;
+  workspacePath?: string;
+  targetPaths?: string[];
+  summary?: string;
+}
+
+export interface PermissionPolicyContext {
+  runId?: string;
+  nodeId?: string;
+  workflowId?: string;
+  adapterId?: string;
+  agentLabel?: string;
+  userId?: string | number | null;
+}
+
+export interface PermissionApprovalRequest {
+  id: string;
+  protocol: typeof PIXCODE_PERMISSION_POLICY_PROTOCOL;
+  status: 'pending' | 'allowed' | 'denied' | 'canceled';
+  capabilities: PermissionCapability[];
+  source: string;
+  toolName?: string;
+  runId?: string;
+  nodeId?: string;
+  workflowId?: string;
+  adapterId?: string;
+  agentLabel?: string;
+  summary?: string;
+  message: string;
+  createdAt: number;
+  resolvedAt?: number;
+  resolvedBy?: string | number | null;
+  resolutionMessage?: string;
+}
+
+export interface PermissionPolicyEvent {
+  id: string;
+  protocol: typeof PIXCODE_PERMISSION_POLICY_PROTOCOL;
+  status: PermissionDecisionStatus;
+  behavior: 'allow' | 'deny' | 'prompt';
+  capabilities: PermissionCapability[];
+  source: string;
+  toolName?: string;
+  summary?: string;
+  message: string;
+  modeByCapability: Partial<Record<PermissionCapability, PermissionPolicyMode>>;
+  audit: boolean;
+  runId?: string;
+  nodeId?: string;
+  workflowId?: string;
+  adapterId?: string;
+  agentLabel?: string;
+  createdAt: number;
+}
+
+export interface PermissionDecision {
+  protocol: typeof PIXCODE_PERMISSION_POLICY_PROTOCOL;
+  requestId: string;
+  status: PermissionDecisionStatus;
+  behavior: 'allow' | 'deny' | 'prompt';
+  capabilities: PermissionCapability[];
+  modeByCapability: Partial<Record<PermissionCapability, PermissionPolicyMode>>;
+  message: string;
+  audit: boolean;
+  event: PermissionPolicyEvent;
+  approvalRequest?: PermissionApprovalRequest;
+}
+
+const DEFAULT_MODES: Record<PermissionCapability, PermissionPolicyMode> = {
+  shell: 'audit',
+  file_write: 'audit',
+  external_directory: 'audit',
+  network: 'audit',
+  secret: 'audit',
+};
+
+const NETWORK_COMMAND_PATTERN = /\b(curl|wget|fetch|ssh|scp|rsync|gh|git\s+(?:clone|fetch|pull|push)|npm\s+(?:install|publish|view|pack|audit)|pnpm\s+(?:install|publish)|yarn\s+(?:install|publish)|pip\s+install|cargo\s+(?:install|publish)|go\s+(?:get|install)|docker\s+(?:pull|push|run))\b|https?:\/\//iu;
+const FILE_WRITE_COMMAND_PATTERN = /(^|\s)(apply_patch|touch|mkdir|rm|mv|cp|tee|sed\s+-i|perl\s+-pi|truncate|chmod|chown)\b|>>?|\b(write|edit|patch|delete|create)\s+(?:file|folder|directory)\b/iu;
+const SECRET_COMMAND_PATTERN = /\b(printenv|env|set)\b|\b(cat|type|less|more)\s+(\S*\.env\b|\S*secret\S*|\S*token\S*|\S*key\S*)/iu;
+const SECRET_VALUE_PATTERN = /\b(?:sk|ghp|github_pat|glpat|npm)_[A-Za-z0-9_=-]{12,}\b|(?:api[_-]?key|secret|token|password)\s*[:=]\s*['"]?[A-Za-z0-9_./+=-]{8,}/iu;
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function readMode(value: unknown): PermissionPolicyMode | undefined {
+  return typeof value === 'string' && (PERMISSION_POLICY_MODES as readonly string[]).includes(value)
+    ? value as PermissionPolicyMode
+    : undefined;
+}
+
+function uniqueCapabilities(values: Array<PermissionCapability | undefined>): PermissionCapability[] {
+  return [...new Set(values.filter((value): value is PermissionCapability => Boolean(value)))];
+}
+
+function requestId(value?: string): string {
+  return value?.trim() || `perm_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function normalizePath(value: string | undefined): string | undefined {
+  if (!value?.trim()) return undefined;
+  try {
+    return path.resolve(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function isInsidePath(basePath: string | undefined, candidatePath: string | undefined): boolean {
+  const base = normalizePath(basePath);
+  const candidate = normalizePath(candidatePath);
+  if (!base || !candidate) return true;
+  if (candidate === base) return true;
+  const relative = path.relative(base, candidate);
+  return Boolean(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function collectInputPaths(input: unknown): string[] {
+  const paths: string[] = [];
+  const visit = (value: unknown) => {
+    if (typeof value === 'string') {
+      if (/^(?:[A-Za-z]:[\\/]|\/|~\/|\.\.?[\\/])/u.test(value.trim())) {
+        paths.push(value.trim().replace(/^~(?=$|[\\/])/u, os.homedir()));
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach(visit);
+      return;
+    }
+    const record = readRecord(value);
+    if (!record) return;
+    for (const [key, nested] of Object.entries(record)) {
+      if (/path|file|dir|cwd|target|source|destination/iu.test(key)) {
+        visit(nested);
+      }
+    }
+  };
+  visit(input);
+  return paths;
+}
+
+function inferCapabilities(request: PermissionRequest): PermissionCapability[] {
+  const capabilities: PermissionCapability[] = [];
+  if (request.capability) capabilities.push(request.capability);
+  if (Array.isArray(request.capabilities)) capabilities.push(...request.capabilities);
+
+  const toolName = request.toolName?.toLocaleLowerCase('en') ?? '';
+  const command = [
+    request.command,
+    typeof request.input === 'string' ? request.input : undefined,
+    readString(readRecord(request.input)?.command),
+    readString(readRecord(request.input)?.query),
+  ].filter(Boolean).join('\n');
+  const inputText = [
+    command,
+    typeof request.summary === 'string' ? request.summary : undefined,
+    typeof request.input === 'object' ? JSON.stringify(request.input) : undefined,
+  ].filter(Boolean).join('\n');
+
+  if (toolName === 'bash' || toolName.includes('shell') || toolName.includes('terminal') || command.trim()) {
+    capabilities.push('shell');
+  }
+  if (/write|edit|multiedit|notebookedit|delete|patch/iu.test(toolName) || FILE_WRITE_COMMAND_PATTERN.test(command)) {
+    capabilities.push('file_write');
+  }
+  if (/webfetch|websearch|fetch|search/iu.test(toolName) || NETWORK_COMMAND_PATTERN.test(command)) {
+    capabilities.push('network');
+  }
+  if (/secret|credential|token|keychain|vault/iu.test(toolName) || SECRET_COMMAND_PATTERN.test(command) || SECRET_VALUE_PATTERN.test(inputText)) {
+    capabilities.push('secret');
+  }
+
+  const targetPaths = [
+    ...(Array.isArray(request.targetPaths) ? request.targetPaths : []),
+    ...collectInputPaths(request.input),
+  ];
+  if (targetPaths.some((targetPath) => !isInsidePath(request.workspacePath ?? request.cwd, targetPath))) {
+    capabilities.push('external_directory');
+  }
+
+  return uniqueCapabilities(capabilities);
+}
+
+export const DEFAULT_PERMISSION_POLICY: PermissionPolicy = {
+  protocol: PIXCODE_PERMISSION_POLICY_PROTOCOL,
+  modes: DEFAULT_MODES,
+  allowedExternalDirectories: [],
+  audit: true,
+};
+
+export function normalizePermissionPolicy(value?: unknown): PermissionPolicy {
+  const record = readRecord(value);
+  const modeRecord = readRecord(record?.modes) ?? readRecord(record?.rules) ?? record ?? {};
+  const modes = { ...DEFAULT_MODES };
+  for (const capability of PERMISSION_CAPABILITIES) {
+    modes[capability] = readMode(modeRecord[capability]) ?? modes[capability];
+  }
+
+  const allowedExternalDirectories = Array.isArray(record?.allowedExternalDirectories)
+    ? record.allowedExternalDirectories
+      .map((item) => readString(item))
+      .filter((item): item is string => Boolean(item))
+    : [];
+
+  return {
+    protocol: PIXCODE_PERMISSION_POLICY_PROTOCOL,
+    modes,
+    allowedExternalDirectories,
+    audit: typeof record?.audit === 'boolean' ? record.audit : true,
+  };
+}
+
+export function resolvePermissionPolicyFromMetadata(metadata?: Record<string, unknown>): PermissionPolicy {
+  const settings = readRecord(metadata?.settings);
+  return normalizePermissionPolicy(metadata?.permissionPolicy ?? settings?.permissionPolicy);
+}
+
+export function redactPermissionText(
+  value: string | undefined,
+  context?: { workspacePath?: string; cwd?: string; projectPath?: string },
+): string | undefined {
+  if (!value?.trim()) return undefined;
+  const candidates = [
+    os.homedir(),
+    context?.workspacePath,
+    context?.cwd,
+    context?.projectPath,
+  ].filter((item): item is string => Boolean(item && item.length > 2));
+
+  let text = value;
+  for (const candidate of candidates) {
+    text = text.split(candidate).join('[workspace]');
+  }
+
+  return text
+    .replace(SECRET_VALUE_PATTERN, '[redacted-secret]')
+    .replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/gu, '[redacted-email]')
+    .trim();
+}
+
+function modeAllowsExternalDirectory(
+  request: PermissionRequest,
+  policy: PermissionPolicy,
+): boolean {
+  const targetPaths = [
+    ...(Array.isArray(request.targetPaths) ? request.targetPaths : []),
+    ...collectInputPaths(request.input),
+  ];
+  if (!targetPaths.length || !policy.allowedExternalDirectories.length) return false;
+
+  return targetPaths.every((targetPath) =>
+    policy.allowedExternalDirectories.some((allowedPath) => isInsidePath(allowedPath, targetPath)),
+  );
+}
+
+export function createPermissionApprovalRequest(
+  decision: Omit<PermissionDecision, 'approvalRequest'>,
+  context?: PermissionPolicyContext,
+): PermissionApprovalRequest {
+  return {
+    id: decision.requestId,
+    protocol: PIXCODE_PERMISSION_POLICY_PROTOCOL,
+    status: 'pending',
+    capabilities: decision.capabilities,
+    source: decision.event.source,
+    toolName: decision.event.toolName,
+    runId: context?.runId,
+    nodeId: context?.nodeId,
+    workflowId: context?.workflowId,
+    adapterId: context?.adapterId,
+    agentLabel: context?.agentLabel,
+    summary: decision.event.summary,
+    message: decision.message,
+    createdAt: decision.event.createdAt,
+  };
+}
+
+export function evaluatePermissionRequest({
+  policy: policyInput,
+  request,
+  context,
+}: {
+  policy?: unknown;
+  request: PermissionRequest;
+  context?: PermissionPolicyContext;
+}): PermissionDecision {
+  const policy = normalizePermissionPolicy(policyInput);
+  const id = requestId(request.requestId);
+  const capabilities = inferCapabilities(request);
+  const modeByCapability: Partial<Record<PermissionCapability, PermissionPolicyMode>> = {};
+
+  for (const capability of capabilities) {
+    const mode = capability === 'external_directory' && modeAllowsExternalDirectory(request, policy)
+      ? 'allow'
+      : policy.modes[capability];
+    modeByCapability[capability] = mode;
+  }
+
+  const modes = Object.values(modeByCapability);
+  const behavior: PermissionDecision['behavior'] = modes.includes('deny')
+    ? 'deny'
+    : modes.includes('prompt')
+      ? 'prompt'
+      : 'allow';
+  const status: PermissionDecisionStatus = behavior === 'deny'
+    ? 'denied'
+    : behavior === 'prompt'
+      ? 'needs_approval'
+      : 'allowed';
+  const summary = redactPermissionText(
+    request.summary
+      ?? request.command
+      ?? (request.toolName ? `${request.toolName} tool request` : `${request.source} permission request`),
+    {
+      workspacePath: request.workspacePath,
+      cwd: request.cwd,
+    },
+  );
+  const capabilityText = capabilities.length ? capabilities.join(', ') : 'unclassified';
+  const message = behavior === 'deny'
+    ? `Permission policy denied ${capabilityText}.`
+    : behavior === 'prompt'
+      ? `Permission policy requires approval for ${capabilityText}.`
+      : `Permission policy allowed ${capabilityText}.`;
+  const event: PermissionPolicyEvent = {
+    id,
+    protocol: PIXCODE_PERMISSION_POLICY_PROTOCOL,
+    status,
+    behavior,
+    capabilities,
+    source: request.source,
+    toolName: request.toolName,
+    summary,
+    message,
+    modeByCapability,
+    audit: policy.audit || modes.includes('audit'),
+    runId: context?.runId,
+    nodeId: context?.nodeId,
+    workflowId: context?.workflowId,
+    adapterId: context?.adapterId,
+    agentLabel: context?.agentLabel,
+    createdAt: Date.now(),
+  };
+  const decisionBase: Omit<PermissionDecision, 'approvalRequest'> = {
+    protocol: PIXCODE_PERMISSION_POLICY_PROTOCOL,
+    requestId: id,
+    status,
+    behavior,
+    capabilities,
+    modeByCapability,
+    message,
+    audit: event.audit,
+    event,
+  };
+
+  return {
+    ...decisionBase,
+    approvalRequest: behavior === 'prompt'
+      ? createPermissionApprovalRequest(decisionBase, context)
+      : undefined,
+  };
+}