cupcake: Instructions file for Claude Code

Custom Review Instructions for GitHub Copilot AI Reviewer

Branch Overview

Branch: tob/fix-bypasses Target: main Commits: 45 commits Purpose: Address external security audit findings from Trail of Bits (TOB) and implement comprehensive defense-in-depth security fixes

This branch represents a major security hardening effort implementing fixes for critical vulnerabilities identified in a professional security audit of the Cupcake policy engine.

---

What is Cupcake?

Cupcake is a policy enforcement engine for AI coding agents (like Claude Code and Cursor). It acts as a security and governance layer that:

1. Intercepts tool calls from AI agents before they execute
2. Evaluates them against policies written in OPA Rego (compiled to WebAssembly)
3. Returns decisions (Allow/Block/Warn/Ask) to enforce rules

Core Architecture:

AI Agent → Hook Event → Cupcake Engine → Policy Evaluation (WASM) → Decision → AI Agent

Key Concepts

1. Harnesses

A harness is the AI coding agent platform (Claude Code, Cursor, etc.). Each harness:

• Has unique event formats (different JSON structures)
• Has unique response formats
• Has different capabilities (context injection, file access)

Critical Design Decision: Cupcake uses a harness-specific architecture with NO normalization layer. Events flow through in their native format, and policies are physically separated by harness:

.cupcake/policies/
├── claude/          # Claude Code policies
└── cursor/          # Cursor policies

2. Hooks

Hooks are integration points where AI agents call external commands during their execution. Examples:

• PreToolUse - Before a tool executes (e.g., before running a shell command)
• PostToolUse - After a tool completes
• UserPromptSubmit - Before processing user input
• SessionStart - When a session begins

Cupcake integrates via hooks in .claude/settings.json or .cursor/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "cupcake eval --harness claude"
      }]
    }]
  }
}