11 KiB
11 KiB
Agent Escalation & Guidelines
Audit requirements, escalation procedures, and agent-specific guidelines.
Related: ../AGENT_GUARDRAILS.md | CODE_REVIEW.md
Overview
This document defines audit requirements, escalation procedures, and platform-specific guidelines for AI agents operating on this codebase. These protocols ensure safe, accountable, and predictable agent behavior across all AI platforms.
AUDIT REQUIREMENTS
All Agents MUST Maintain Logs
Every agent operation MUST be logged with:
REQUIRED LOG FIELDS:
1. Files Read:
- Timestamp
- File path
- Line ranges read
- Read method (Read tool, glob, grep)
2. Files Modified:
- Timestamp
- File path
- Change type (create, edit, delete)
- Lines changed (from-to)
- Commit hash (if committed)
3. Commands Executed:
- Timestamp
- Command and arguments
- Working directory
- Exit code
- Standard output (if relevant)
- Standard error (if error occurred)
4. Tests Run:
- Timestamp
- Test command
- Test files executed
- Pass/fail status
- Failed test names (if any)
5. Errors Encountered:
- Timestamp
- Error type
- Error message
- Stack trace (if available)
- Context (what operation caused error)
- Resolution (rollback, retry, or abort)
6. Decisions Made:
- Timestamp
- Decision point
- Options considered
- Choice made
- Rationale
7. User Interactions:
- Timestamp
- Interaction type (question, report, escalation)
- Message content
- User response (if any)
Log Format Standard
AI AGENT AUDIT LOG ENTRY
{
"timestamp": "2026-01-16T10:30:45Z",
"agent": "Claude Code",
"agent_id": "claude-3-sonnet",
"session_id": "sess_abc123",
"operation": {
"type": "file_edit",
"file": "/path/to/file.py",
"lines": [45, 52],
"change_summary": "Added null check"
},
"preconditions": {
"verified": true,
"method": "read",
"file_reads": ["/path/to/file.py"]
},
"result": {
"status": "success",
"validation": {
"syntax": "pass",
"tests": "pass"
},
"committed": true,
"commit_hash": "abc123def456"
},
"user_escalations": [],
"errors": []
}
Audit Log Storage
LOG STORAGE REQUIREMENTS:
Location: Agent-specific logs (platform-dependent)
Format: JSON or structured logs
Retention: Per project policy
Access: Project maintainers only
For Agents with MCP Integration:
- Use MCP checkpointing
- Save session context regularly
- Include audit trail in checkpoints
ESCALATION PROCEDURES
When to Escalate to Human
ALWAYS ESCALATE IF:
[ ] Security-related changes required
[ ] Production data access needed
[ ] Destructive operations requested
[ ] Test/production boundary unclear
[ ] Multiple valid interpretations exist
[ ] High-risk changes (auth, payments, etc.)
[ ] Cross-system changes required
[ ] Database schema changes proposed
[ ] Infrastructure/deployment changes
[ ] API contract changes proposed
[ ] Compliance requirements (GDPR, HIPAA, etc.)
[ ] Changes affecting multiple teams
[ ] Performance implications unclear
[ ] Any uncertainty about next step
How to Escalate
ESCALATION FORMAT:
"I need human review before proceeding.
CONTEXT: [Describe what you're doing]
URGENCY: [Critical/High/Medium/Low]
CONCERN: [What you need help with]
SPECIFIC QUESTIONS:
1. [Question 1]
2. [Question 2]
3. [Question 3]
OPTIONS CONSIDERED:
Option A: [Description] - Pros/Cons
Option B: [Description] - Pros/Cons
CURRENT STATUS: [What state are things in now]
RECOMMENDED ACTION: [What do you suggest]
Waiting for user guidance...
"
Escalation Scenarios
Scenario 1: Security Change Required
"I need human security review before proceeding.
CONTEXT: Implementing user authentication feature
URGENCY: High
CONCERN: Security implications unclear
SPECIFIC QUESTIONS:
1. Should I use bcrypt or Argon2 for password hashing?
2. Do you want two-factor authentication included?
3. What password policy should be enforced?
CURRENT STATUS:
- Production code created
- Test infrastructure separate
- Ready to implement auth
RECOMMENDED ACTION:
Use bcrypt with 12 rounds, require 2FA for admin accounts
Waiting for security review..."
Scenario 2: Database Schema Change
"I need DBA approval for schema change.
CONTEXT: Adding user preferences table
URGENCY: Medium
CONCERN: Impact on existing queries
SPECIFIC QUESTIONS:
1. Should table be in production or test database?
2. What indexes are needed?
3. Any migration considerations?
CURRENT STATUS:
- Table schema designed
- Migration script written
- Production code ready
RECOMMENDED ACTION:
Deploy to test DB first, get approval before production
Waiting for DBA review..."
AGENT-SPECIFIC GUIDELINES
Universal Requirements (ALL LLMs and AI Agents)
MANDATORY FOR ALL AGENTS:
- Follow platform's responsible AI guidelines
- Respect safety filters and guardrails
- Handle context/token limits gracefully
- Use tool/function calling appropriately
- Report capability limitations honestly
- Ask for clarification when uncertain
- Refuse harmful or destructive requests
- Maintain audit trails of actions
- Verify test/production separation before deployment
By Category
Commercial API-Based Models
(Claude, GPT, Gemini, Command R, etc.)
- Adhere to provider usage policies
- Respect rate limits and quotas
- Use official APIs and SDKs
- Handle API errors gracefully
- Implement retry logic with backoff
- Cache responses where appropriate
Open Source / Self-Hosted Models
(LLaMA, Mistral, Qwen, DeepSeek, Phi, Falcon, etc.)
- Follow local safety configurations
- Respect system prompts fully
- Handle resource/memory limits
- Configure appropriate guardrails
- Monitor for model drift
- Use appropriate quantization for deployment
Multimodal Models
(GPT-4V, Gemini Pro Vision, Claude 3, LLaVA, etc.)
- Handle image/audio/video inputs safely
- Do not process potentially harmful media
- Respect privacy in visual content
- Validate file types before processing
- Check for embedded malicious content
- Limit file size to reasonable bounds
Reasoning / Chain-of-Thought Models
(o1, o3, DeepSeek-R1, etc.)
- Allow sufficient reasoning time
- Do not interrupt reasoning chains
- Validate final outputs, not intermediate steps
- Handle extended context requirements
- Check for logical consistency
- Verify reasoning leads to correct result
Agent Frameworks
(CrewAI, LangChain, AutoGPT, LangGraph, Semantic Kernel, etc.)
- Implement proper task decomposition
- Respect iteration and recursion limits
- Handle agent failures gracefully
- Maintain comprehensive audit logs
- Implement proper stopping conditions
- Validate inter-agent communications
- Coordinate agent dependencies
- Avoid deadlocks in agent interactions
Model Compatibility Note
This guardrails framework is designed to work with:
- 30+ major LLM families including Claude, GPT, Gemini, LLaMA, Mistral, Qwen, DeepSeek, Cohere, Phi, Falcon, and others
- All future models that follow standard AI assistant patterns
- Custom fine-tuned models based on any architecture
- Multi-agent systems regardless of orchestration framework
If you are an AI system not explicitly listed, these guardrails still apply to you.
COMPLIANCE
Acknowledgment
By operating on this codebase, all AI systems implicitly acknowledge and agree to follow these guardrails. Failure to comply may result in:
- Task rejection
- Output being discarded
- Agent being blocked from future operations
- Escalation to human administrators
Reporting Violations
If you observe an agent violating these guardrails:
REPORTING VIOLATION PROTOCOL:
1. STOP the agent immediately
2. Document the violation:
- Timestamp
- Agent ID/name
- Violation description
- Impact assessment
- Evidence (logs, commits, etc.)
3. Report to repository maintainers
4. Review and rollback any unauthorized changes
5. Document lessons learned
Violation Categories
| Severity | Description | Action Required |
|---|---|---|
| Critical | Production data corruption, security breach | Immediate rollback, escalate to admin |
| High | Test/production mixing, deployment without approval | Rollback, user notification required |
| Medium | Missing audit logs, incomplete documentation | Log incident, improve process |
| Low | Style violations, minor documentation errors | Note for next cycle |
QUICK REFERENCE
+------------------------------------------------------------------+
| AGENT ESCALATION QUICK REFERENCE |
+------------------------------------------------------------------+
| ALWAYS ESCALATE FOR: |
| ✓ Security changes |
| ✓ Production data access |
| ✓ Test/production boundary unclear |
| ✓ Database schema changes |
| ✓ API contract changes |
| ✓ Any uncertainty |
+------------------------------------------------------------------+
| AUDIT LOG FIELDS: |
| Files read/modified, commands run, tests run |
| Errors encountered, decisions made, user interactions |
+------------------------------------------------------------------+
| ESCALATION FORMAT: |
| Context → Urgency → Concern → Questions → Options → Wait |
+------------------------------------------------------------------+
| UNIVERSAL REQUIREMENTS: |
| Follow safety guardrails, audit all actions, ask if uncertain |
+------------------------------------------------------------------+
| AGENT TYPES: |
| Commercial API → Respect rate limits, use official SDKs |
| Open Source → Follow local config, handle resource limits |
| Multimodal → Validate media, respect privacy |
| Reasoning → Allow time, validate outputs |
| Frameworks → Coordinate agents, avoid deadlocks |
+------------------------------------------------------------------+
Related Documents:
- AGENT_GUARDRAILS.md - Core safety protocols
- CODE_REVIEW.md - Code review and escalation
- AGENT_EXECUTION.md - Execution protocol
Last Updated: 2026-01-16 Authored by: TheArchitectit Document Owner: Project Maintainers Line Count: ~300