A Practical Architecture for Governing AI Coding Agents, Without Slowing Developers Down
A repository-attached control plane architecture separates governance from guidance, placing policy enforcement in a `.ai-governance/` directory with deterministic checks rather than relying on prompts or LLM self-policing The system normalizes tool calls into canonical actions (category, operation, resource, effects, risk) before policy evaluation, preventing bypass through syntax variations like `-f` vs `--force` or symlink escapes Authority is decoupled from capability through privilege envel
Analysis
TL;DR
- A repository-attached control plane architecture separates governance from guidance, placing policy enforcement in a
.ai-governance/directory with deterministic checks rather than relying on prompts or LLM self-policing - The system normalizes tool calls into canonical actions (category, operation, resource, effects, risk) before policy evaluation, preventing bypass through syntax variations like
-fvs--forceor symlink escapes - Authority is decoupled from capability through privilege envelopes and three trust classes (TRUSTED, CONTEXT, UNTRUSTED), ensuring sessions cannot expand their own authority without explicit approval
- Actions and changes are governed as two distinct concerns: action governance evaluates individual tool calls, while change governance assesses accumulated modifications against evidence obligations tied to risk zones
- Adoption is designed to be gradual (OBSERVE → WARN → ENFORCE) with lightweight onboarding, progressive configuration scaling, and append-only hash-chained evidence receipts for auditability
Why It Matters
This architecture addresses the critical governance gap as coding agents transition from code suggestion to full repository manipulation, providing a practical reference implementation for teams needing deterministic policy enforcement without centralised infrastructure. It offers AI practitioners a concrete pattern for balancing agent autonomy with security boundaries, particularly relevant for regulated environments or teams deploying agents with write access to production systems.
Technical Details
- Architecture: A standalone, local-first governance layer using Claude Code's extension points (hooks, PreToolUse, permission system) with a
.ai-governance/directory containing versioned, inspectable policy files - Normalization layer: Converts raw tool calls into canonical action representations with fields for category, operation, resource, effects (external_write, destructive, credential_access), and risk level; handles bypass vectors including force-push aliases, symlink escapes, encoded shell commands, and compound command decomposition
- Privilege envelope system: Each session receives a bounded set of allowed operations/resources/environments; authority provenance tracked through three trust classes (TRUSTED from explicit human/company governance, CONTEXT from project files/tool results, UNTRUSTED from external/MCP sources)
- Change-state machine: Governs accumulated changes through states (READY → NEEDS_EVIDENCE → PENDING_HUMAN_REVIEW → HUMAN_REVIEWED → BLOCKED) with evidence obligations scaled to risk zones (Low/Medium/High/Critical)
- Evidence system: Append-only hash-chained receipts recording normalized actions, policy decisions, approvals, executed commands, file changes, test results, and verification outcomes with redacted sensitive values and no chain-of-thought capture
Industry Insight
- Teams deploying agentic coding tools should implement governance layers before agents gain write access to production systems; the OBSERVE→WARN→ENFORCE rollout path allows policy tuning without disrupting development velocity
- The separation of action governance from change governance is a critical architectural insight—individual permitted actions can accumulate into high-risk changes, requiring evidence obligations that scale with the risk zone of modified files
- Self-protection of the governance monitor is non-negotiable; the control plane must protect its own policy, evidence, and runtime state from tampering, with adversarial testing covering bypass variants like prompt injection in repository content and forged test evidence
Disclaimer: The above content is generated by AI and is for reference only.