ai-guard¶

Policy enforcement for AI agent actions

AI-Guard is the policy layer of the F3L1X four-layer scaffolding system. It enforces rules about what agents can and cannot do, preventing unauthorized or unsafe actions before they happen.

What It Does¶

AI-Guard provides:

Tool Gating - Allow, deny, or escalate tool invocations based on policy
Action Policies - Define per-realm rules about permitted agent behavior
Naming Conventions - Enforce file naming standards (UPPERCASE-KEBAB-CASE for docs)
Audit Trail - Log all policy decisions for review
Hook System - Pre-tool-use hooks that intercept actions in real-time

Think of AI-Guard as the security guard at the door - it checks every action against policy before allowing it through.

Key Capabilities¶

Pre-Tool-Use Hooks¶

AI-Guard hooks into Claude Code tool execution:

Agent wants to write file
    |
    v
AI-Guard hook fires
    |
    v
Check policies:
  - Is the file name compliant?
  - Is the target directory allowed?
  - Does the content violate any rules?
    |
    v
ALLOW / BLOCK (with reason)

Policy Categories¶

Category	What It Enforces
File Naming	UPPERCASE-KEBAB-CASE for documentation files
Directory Access	Prevent writes to protected directories
Content Safety	Block commits with secrets or credentials
Action Scope	Limit agent actions to authorized domains

Escalation¶

When AI-Guard is unsure about an action, it escalates to the user rather than silently blocking or allowing. This ensures agents do not get stuck but also do not take unauthorized actions.

The Four-Layer Scaffolding¶

AI-Guard is Layer 2 (Policy) in the scaffolding system:

Layer	System	Purpose
1. Architectural	Pipeline-Go	Correct patterns and structure
2. Policy	AI-Guard	Authorized actions only
3. Task	Plan-Master	Correct scope and priorities
4. Session	Agent Harness	Context preservation

Important Notes¶

Not a Firewall¶

AI-Guard enforces development policies, not network security. It prevents agents from making mistakes, not from being attacked.

Graceful Degradation¶

If AI-Guard is unavailable, agents can still operate but without policy enforcement. This is logged as a warning.

Pipeline-Go - Layer 1 (architectural) enforcement
Plan-Master - Layer 3 (task) enforcement
Hacker-Man - Security auditing (different from policy enforcement)
All realms - Subject to AI-Guard policies