get: any, propertyKey: string, descriptor: PropertyDescriptor) { const originalMethod = descriptor.value; descriptor.value = async function (...args: any[]) { const policy: ApprovalMetadata = { requiresApproval: metadata.requiresApproval ?? false, riskLevel: metadata.riskLevel ?? 'low', destructive: metadata.destructive ?? false, ttlSeconds: metadata.ttlSeconds ?? 300, }; Reflect.defineMetadata('approvalPolicy', policy, target, propertyKey); return originalMethod.apply(this, args); }; }; }

### Step 2: Implement the Pluggable Handler Interface

The approval mechanism must remain surface-agnostic. Define a contract that any surface (CLI, MCP, A2A) can implement.

```typescript
interface ApprovalRequest {
  moduleId: string;
  action: string;
  parameters: Record<string, unknown>;
  riskLevel: 'low' | 'medium' | 'high' | 'critical';
  correlationId: string;
}

interface ApprovalResponse {
  approved: boolean;
  identity: string;
  timestamp: number;
  metadata?: Record<string, unknown>;
}

interface ApprovalHandler {
  canHandle(surface: string): boolean;
  requestConsent(request: ApprovalRequest): Promise<ApprovalResponse>;
  handleTimeout(correlationId: string): void;
}

Step 3: Build the Pipeline Interceptor (Step 5)

Position the interceptor after routing but before validation. This ensures the module is resolved, but no side effects have been triggered.

class ExecutionPipeline {
  private handlers: ApprovalHandler[] = [];
  private trustedIdentities: Set<string> = new Set(['system', 'ci-runner']);

  registerHandler(handler: ApprovalHandler) {
    this.handlers.push(handler);
  }

  async execute(moduleId: string, action: string, params: Record<string, unknown>, context: { surface: string; identity: string }) {
    const policy = Reflect.getMetadata('approvalPolicy', this, action) as ApprovalMetadata | undefined;
    
    if (!policy?.requiresApproval) {
      return this.runValidationAndExecute(moduleId, action, params);
    }

    // Trusted context bypass
    if (this.trustedIdentities.has(context.identity) || process.env.AUTO_APPROVE === 'true') {
      return this.runValidationAndExecute(moduleId, action, params);
    }

    const request: ApprovalRequest = {
      moduleId,
      action,
      parameters: params,
      riskLevel: policy.riskLevel,
      correlationId: crypto.randomUUID(),
    };

    const handler = this.handlers.find(h => h.canHandle(context.surface));
    if (!handler) {
      throw new Error(`No approval handler registered for surface: ${context.surface}`);
    }

    const response = await Promise.race([
      handler.requestConsent(request),
      new Promise<ApprovalResponse>((_, reject) => 
        setTimeout(() => reject(new Error('Approval timeout')), policy.ttlSeconds! * 1000)
      )
    ]);

    if (!response.approved) {
      throw new Error(`Execution blocked: ${moduleId}#${action} denied by ${response.identity}`);
    }

    return this.runValidationAndExecute(moduleId, action, params);
  }

  private async runValidationAndExecute(moduleId: string, action: string, params: Record<string, unknown>) {
    // Steps 6-11: Validation, execution, observability, cleanup
    return { status: 'executed', moduleId, action };
  }
}

Step 4: Surface-Specific Implementations

CLI Surface:

class CliApprovalHandler implements ApprovalHandler {
  canHandle(surface: string) { return surface === 'cli'; }
  
  async requestConsent(request: ApprovalRequest): Promise<ApprovalResponse> {
    const readline = require('readline').createInterface({ input: process.stdin, output: process.stdout });
    return new Promise(resolve => {
      readline.question(`[APPROVAL REQUIRED] ${request.moduleId}#${request.action} (${request.riskLevel} risk). Proceed? [y/N] `, answer => {
        readline.close();
        resolve({ approved: answer.toLowerCase() === 'y', identity: 'cli-user', timestamp: Date.now() });
      });
    });
  }
  
  handleTimeout(correlationId: string) { /* cleanup */ }
}

MCP Surface (Elicitation):

class McpApprovalHandler implements ApprovalHandler {
  canHandle(surface: string) { return surface === 'mcp'; }
  
  async requestConsent(request: ApprovalRequest): Promise<ApprovalResponse> {
    // Projects to Claude/Cursor via MCP Elicitation protocol
    const result = await mcpClient.elicit({
      message: `Approve ${request.moduleId}#${request.action}?`,
      schema: { type: 'boolean' },
      correlationId: request.correlationId,
    });
    return { approved: result.content === true, identity: 'mcp-user', timestamp: Date.now() };
  }
  
  handleTimeout(correlationId: string) { mcpClient.cancelElicitation(correlationId); }
}

A2A Surface:

class A2aApprovalHandler implements ApprovalHandler {
  canHandle(surface: string) { return surface === 'a2a'; }
  
  async requestConsent(request: ApprovalRequest): Promise<ApprovalResponse> {
    // Provider agent returns input-required status to consumer
    await a2aProtocol.sendStatus({
      status: 'input-required',
      correlationId: request.correlationId,
      payload: { moduleId: request.moduleId, action: request.action },
    });
    // Waits for consumer to forward human approval
    return new Promise(resolve => {
      a2aProtocol.on('approval-response', (resp) => {
        if (resp.correlationId === request.correlationId) {
          resolve({ approved: resp.approved, identity: resp.identity, timestamp: Date.now() });
        }
      });
    });
  }
  
  handleTimeout(correlationId: string) { a2aProtocol.sendStatus({ status: 'timeout', correlationId }); }
}

Architecture Decisions & Rationale

1. Interception at Pipeline Stage 5: Placing the gate after routing but before validation prevents unnecessary computation and ensures the module context is fully resolved. Stopping earlier would lack sufficient metadata; stopping later would risk partial execution.
2. Pluggable Handler Pattern: Decoupling the approval mechanism from the pipeline allows surfaces to evolve independently. CLI, MCP, and A2A each have distinct UX constraints. The protocol remains stable while surfaces adapt.
3. Identity-Aware Bypass: Automated environments (CI/CD, system administrators) require deterministic execution. Mapping identity.types to bypass rules prevents pipeline hangs without compromising safety for user or agent contexts.
4. Correlation IDs & TTLs: Distributed systems require traceability. Correlation IDs link approval requests to responses across surfaces. TTLs prevent indefinite blocking, enabling graceful degradation or fallback routing.

Pitfall Guide

1. Prompt-Only Safety Reliance

Explanation: Teams embed safety instructions in system prompts and assume the model will comply. LLMs treat these as suggestions, not constraints. Context drift and instruction following limits make this unreliable. Fix: Move safety enforcement to the execution pipeline. Use declarative metadata and runtime interception. Prompts should guide reasoning, not enforce boundaries.

2. Approval Fatigue from Over-Gating

Explanation: Marking every module as requires_approval creates friction. Users develop click-through behavior, negating the safety mechanism. Fix: Implement risk-based gating. Only enforce approval for high or critical risk levels. Use automated thresholds for low/medium operations. Log approval patterns to identify unnecessary gates.

3. CI/CD Pipeline Hangs

Explanation: Automated deployments trigger approval gates, causing pipelines to block indefinitely waiting for human input. Fix: Configure identity-based bypass rules. Map system or ci-runner identities to auto-approve. Use environment variables (AUTO_APPROVE=true) scoped to deployment contexts. Never expose bypass flags in user-facing interfaces.

4. MCP Elicitation Timeouts

Explanation: Claude or Cursor dialogs expire if the user does not respond. The pipeline remains blocked, causing cascading failures in agent workflows. Fix: Implement configurable TTLs with explicit timeout handlers. Route expired requests to fallback surfaces or queue them for batch review. Log timeout events for observability.

5. A2A State Desynchronization

Explanation: Provider agents wait for approval while consumer agents assume completion. Correlation IDs are missing or mismatched, causing state drift. Fix: Enforce strict correlation ID propagation across all A2A messages. Implement state reconciliation checkpoints. Use explicit input-required and approval-response status codes with idempotent handlers.

6. Missing Handler Fallbacks

Explanation: If no handler matches the active surface, the pipeline crashes or silently skips approval. Fix: Register a default terminal handler as a fallback. Validate handler availability during pipeline initialization. Throw explicit errors if no surface can process the request.

7. Hardcoded Bypass Flags in Scripts

Explanation: Developers pass -y or --yes flags directly in automation scripts, bypassing identity checks and audit trails. Fix: Restrict bypass mechanisms to identity context and environment configuration. Log all bypass events with identity, timestamp, and module details. Audit bypass usage quarterly.

Production Bundle

Action Checklist

• Define approval metadata schema: Map requires_approval, riskLevel, and destructive flags to module boundaries.
• Implement pluggable handler interface: Create ApprovalHandler contract with requestConsent, canHandle, and handleTimeout methods.
• Position interceptor at pipeline stage 5: Ensure routing completes before approval check, but validation and execution remain downstream.
• Register surface-specific handlers: Deploy CLI, MCP, and A2A implementations with explicit surface matching.
• Configure identity-based bypass: Map system and ci-runner identities to auto-approve rules. Scope bypass to environment variables.
• Implement TTL and correlation tracking: Add timeout thresholds and unique correlation IDs to all approval requests.
• Enable observability hooks: Log approval decisions, timeouts, and bypass events with identity and module context.
• Audit gate coverage quarterly: Review approval patterns, remove unnecessary gates, and adjust risk thresholds based on incident data.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
User-facing CLI tool	CLI surface handler with terminal prompt	Direct human interaction, low latency, explicit consent	Minimal infrastructure cost
LLM-assisted IDE (Claude/Cursor)	MCP Elicitation handler	Native UX integration, reduces context switching, protocol-compliant	Moderate MCP server overhead
Multi-agent orchestration	A2A surface handler with input-required status	Maintains agent autonomy, enables cross-agent consent routing	Higher state management complexity
CI/CD deployment pipeline	Identity-based bypass (system type)	Prevents pipeline hangs, maintains audit trail, deterministic execution	Low operational cost, requires strict identity mapping
High-risk production ops	Runtime approval gate + TTL + correlation ID	Deterministic safety, prevents cascading failures, traceable consent	Moderate latency, high risk mitigation ROI

Configuration Template

// pipeline.config.ts
import { ExecutionPipeline } from './pipeline';
import { CliApprovalHandler } from './surfaces/cli';
import { McpApprovalHandler } from './surfaces/mcp';
import { A2aApprovalHandler } from './surfaces/a2a';

const pipeline = new ExecutionPipeline();

// Register surface handlers
pipeline.registerHandler(new CliApprovalHandler());
pipeline.registerHandler(new McpApprovalHandler());
pipeline.registerHandler(new A2aApprovalHandler());

// Configure trusted identities
pipeline.setTrustedIdentities(['system', 'ci-runner', 'admin-service']);

// Global timeout fallback
pipeline.setDefaultTtlSeconds(180);

// Observability hooks
pipeline.on('approval-request', (req) => console.log(`[AUDIT] Approval requested: ${req.correlationId}`));
pipeline.on('approval-response', (res) => console.log(`[AUDIT] Approval ${res.approved ? 'granted' : 'denied'}: ${res.identity}`));
pipeline.on('approval-timeout', (corrId) => console.warn(`[AUDIT] Approval timeout: ${corrId}`));

export default pipeline;

Quick Start Guide

1. Install dependencies: Add reflect-metadata and your preferred surface SDKs (@apcore/mcp, @apcore/a2a) to your project.
2. Define a module: Decorate your execution function with @approvalGate({ requiresApproval: true, riskLevel: 'high', destructive: true }).
3. Initialize the pipeline: Import the configuration template, register handlers, and set trusted identities.
4. Execute with context: Call pipeline.execute(moduleId, action, params, { surface: 'cli', identity: 'user' }) and observe the approval prompt.
5. Verify observability: Check logs for [AUDIT] entries confirming request routing, consent capture, and execution completion.