Agent Integrity Monitoring System¶

Last Updated: 2026-01-20 Status: Deployed and Operational

Overview¶

The Agent Integrity Monitoring System is a three-layer prevention architecture that ensures agents operate within their defined roles and prevents integrity violations.

Architecture¶

Layer 1: Agent Registry¶

Location: /ge-ops/master/AGENT-REGISTRY.json Generated by: /home/claude/ge-bootstrap/scripts/generate-agent-registry.py

Central source of truth containing: - 48 agents with complete metadata - 36 unique role types - Role signatures and boundaries - "does_NOT_do" constraints for each agent - Identity file hashes for verification

Registry Hash: sha256:1c475c2161cf42f1

Layer 2: Pre-Dispatch Validation (Dolly)¶

Component: dolly-orchestrator.py - AgentValidator class Action Point: Before dispatching triggers to agent queues

Validation Logic: 1. Loads agent registry on startup 2. Validates agent exists in registry 3. Checks trigger content against agent's "does_NOT_do" list 4. Blocks invalid triggers and logs violations 5. Fails open on validation errors (allows trigger)

Violation Logging: /ge-ops/system/integrity/violations/dolly-block-*.json

Verification:

docker logs ge-dolly | grep "Agent validator loaded"
# Expected: "Agent validator loaded: 48 agents"

Layer 3: Pre-Execution Validation (agent-runner)¶

Component: agent-runner.py - AgentValidator class Action Point: Before spawning Claude Code session

Validation Logic: 1. Loads agent registry on startup 2. Validates work assignment against agent role 3. Checks work context against "does_NOT_do" list 4. Blocks execution if validation fails 5. Acknowledges message without processing

Violation Logging: /ge-ops/system/integrity/violations/agent-runner-block-*.json

Layer 4: Post-Execution Auditing (Ron Guardian)¶

Component: ron-guardian.py - Enhanced monitoring Action Point: After session completion and hourly sweeps

Enhanced Capabilities: 1. Role Alignment Audits - Detects agents performing forbidden tasks 2. Documentation Scanning - Flags phantom agent references 3. Identity Integrity - Monitors IDENTITY.md file tampering 4. Registry Loading - Uses registry for validation rules

Violation Detection: - Role drift: HIGH severity (logged, not halted) - Phantom agents: MEDIUM severity (logged for review) - Identity tampering: CRITICAL severity (triggers HALT)

Violation Response¶

Severity Levels¶

CRITICAL - Immediate HALT - Identity file modification - Agent not in registry - Halt flag tampering

HIGH - Logged and monitored - Role drift violations - Forbidden task execution - Cross-team access

MEDIUM - Logged for review - Phantom agent references - Suspicious patterns

Violation Files¶

All violations are logged as JSON in:

/ge-ops/system/integrity/violations/
├── dolly-block-YYYYMMDD-HHMMSS.json
├── agent-runner-block-YYYYMMDD-HHMMSS.json
└── ron-*.json

Violation Format:

{
  "timestamp": "2026-01-20T14:30:00",
  "severity": "CRITICAL",
  "type": "invalid_agent_trigger",
  "agent": "agent_name",
  "work_item": "/path/to/work",
  "reason": "Agent 'X' should NOT handle 'Y'. Route to 'Z' instead.",
  "action": "BLOCKED"
}

Operational Notes¶

Fail-Safe Behavior¶

The system is designed to fail open: - If registry cannot be loaded, validation is disabled - Work proceeds with warning log - Prevents system lockup from registry issues

Registry Updates¶

To regenerate the registry after agent changes:

python3 /home/claude/ge-bootstrap/scripts/generate-agent-registry.py

The registry is automatically loaded on: - Dolly container start - Agent-runner container start - Ron Guardian start

Monitoring¶

Health Checks:

# Verify Dolly validator
docker logs ge-dolly | grep "Agent validator loaded"

# Verify agent-runner validator (when running)
docker logs ge-{agent} | grep "Agent validator loaded"

# Verify Ron Guardian registry
docker logs ge-ron | grep "Agent registry loaded"

Violation Monitoring:

# Check for recent violations
ls -lth /home/claude/ge-bootstrap/ge-ops/system/integrity/violations/ | head -20

# View specific violation
cat /ge-ops/system/integrity/violations/dolly-block-*.json | jq .

Deployment History¶

2026-01-20: Full prevention system deployed - Agent Registry: 48 agents, 36 role types - Dolly validation: Deployed and verified - Agent-runner validation: Code deployed - Ron Guardian enhancements: 4 new audit methods

Total Code: ~442 lines of prevention logic

Troubleshooting¶

Registry Not Loading¶

Symptom: "Agent validator loaded: 0 agents"

Causes: 1. Registry file not found 2. Invalid JSON in registry 3. Incorrect path (must use /ge-ops/master/AGENT-REGISTRY.json)

Fix:

# Verify registry exists and is valid
cat /home/claude/ge-bootstrap/ge-ops/master/AGENT-REGISTRY.json | jq '.agents | length'
# Should output: 48

# Regenerate if needed
python3 /home/claude/ge-bootstrap/scripts/generate-agent-registry.py

Validation Blocking Valid Work¶

Symptom: Work is blocked but should be allowed

Causes: 1. Agent's "does_NOT_do" list too broad 2. Keyword matching false positive

Fix: 1. Review agent's IDENTITY.md 2. Refine "does_NOT_do" boundaries 3. Regenerate registry 4. Restart affected containers

Violation False Positives¶

Symptom: Ron flagging valid agent names as phantoms

Causes: 1. Agent name used in different context 2. Registry not synced with recent changes

Fix: 1. Review violation context 2. Update registry if needed 3. Adjust detection patterns in Ron

Maintenance¶

Weekly Tasks¶

Review violation logs
Verify registry hash matches expected
Check for new phantom agent references

Monthly Tasks¶

Audit all agent IDENTITY.md files
Regenerate registry and compare hashes
Review and tune validation rules

On Agent Changes¶

Update agent's IDENTITY.md
Regenerate registry: python3 scripts/generate-agent-registry.py
Verify new hash in logs
Restart affected services

For questions about this system, contact the infrastructure team or review the audit reports in /ge-ops/system/integrity/audits/