Governance Framework

Infrastructure-level enforcement. Not prompt-level suggestions.

Why This Exists

AI agents that can send emails, post to social media, modify brand assets, and interact with web pages need technical enforcement. Prompt-level rules ("don't send emails autonomously") can be ignored, forgotten, or overridden by sufficiently complex prompts. The governance engine provides a hard enforcement layer that operates outside the agent's context window. There is no way for an agent to bypass it.

Architecture

Every tool call made by every agent passes through the governance engine before execution. Both interactive sessions (Command Center, CLI) and autonomous background agents use the same enforcement path. Same rules, same code, no exceptions.

Agent requests tool call
        |
        +-- Command Center ---> canUseTool() callback
        |
        +-- CLI --------------> PreToolUse hook
                                    |
                            +-------+-------+
                            | governance.ts |
                            | evaluateToolUse|
                            +-------+-------+
                                    |
                    +---------------+---------------+
                    |               |               |
                 ALLOW            DENY       REQUIRE_APPROVAL
                    |               |               |
               Execute tool    Block with      Pause for
               (+ audit log)   explanation     human review

Permission Levels

Four levels, configurable per agent and per tool category. Clients customize these during onboarding based on their workflow and risk tolerance.

Allow

Execute silently. For low-risk operations you trust completely (file reads, search).

Log

Execute and record to the audit trail. For operations you want visibility into but don't need to approve (regular file writes).

Require Approval

Pause and ask for human approval before executing. For sensitive operations like sending messages or browser automation.

Deny

Block outright with an explanation. Agent cannot perform this action under any circumstances.

What's Governed

Category	Covers	Default
External Comms	Slack, Gmail, LinkedIn, Twitter, ConvertKit, any Pipedream service that contacts people	Require Approval
Browser Automation	Clicking, typing, form-filling in Chrome. Read-only actions (screenshots, page text) are not gated.	Require Approval
File Writes	Creating or editing files. Protected paths (brand config, agent definitions, governance rules) always require approval.	Log
Sub-agent Spawn	Launching specialist agents. Orchestrators need this to delegate work.	Allow

Autonomous Agent Lockdown

Background agents (stewards) run on scheduled cadences without human oversight. They are the highest-risk execution context. The steward policy is the most restrictive governance layer.

Stewards CANNOT:

Send any message (Slack, email, LinkedIn)
Interact with browser pages
Write or edit files
Run shell commands
Spawn sub-agents

Stewards CAN:

Read files and search the codebase
Search the web for intelligence
Fetch web pages for analysis
Report findings via session output

Protected Paths

Certain file paths always require human approval for writes, regardless of the agent's general file-write permission.

client-context/**Brand config, voice guides, business profiles, competitor data

config/governance.jsonThe governance rules themselves (self-referential protection)

.claude/agents/**Agent definitions and system prompts

.claude/settings.jsonHook configuration and permission settings

Audit Trail

Every governed action is logged to an append-only audit trail. Each entry records:

TimestampWhen the action was attempted

AgentWhich agent made the request

ToolWhat tool was called

CategoryWhich governance category matched

DecisionAllow, log, require approval, or deny

ReasonHuman-readable explanation of why

SourceWhich rule fired (steward policy, agent override, protected path, default)

Input SummaryAbbreviated tool input for context

The audit log is viewable in the Command Center under Configuration. Entries are append-only and cannot be modified by agents.

Fail Closed

If the governance config is missing or corrupt, the engine falls back to the most restrictive defaults. A broken config never results in an open system.

All external comms: require approval
All browser automation: require approval
All file writes: require approval
All sub-agent spawning: require approval
Stewards: denied everything except read and search

72 Governance Tests

The governance engine has a dedicated test suite verifying every enforcement path.

Config loading6 tests

Safe defaults, steward policy, tool categories

Always-allow tools9 tests

Read-only tools pass even for stewards

Steward policy8 tests

Slack deny, browser deny, Gmail deny

External comms5 tests

All MCP comm tools classified correctly

Browser automation3 tests

Chrome DevTools, Playwright enforcement

File writes6 tests

Regular writes logged, protected paths escalated

Pipedream parsing4 tests

Bash-wrapped API calls detected and governed

Agent overrides3 tests

Per-agent rules, no cross-agent bleed

Evaluation order3 tests

Steward > override > protected > default

Graceful degradation3 tests

Missing config falls to most restrictive

Audit logging4 tests

Denied logged, allowed not logged, append-only

Integration12 tests

Sessions.ts imports, env propagation, hooks

Evaluations Quality Overview →