agent-governance/agents/tier0-agent/README.md

Tier 0 Observer Agent

Read-only agent for documentation, inventory, and plan generation

Overview

The Tier 0 Observer Agent is a governed agent that operates in read-only mode. It can view documentation, check inventory, and generate plans, but it CANNOT execute any commands or modify any files. This is the entry-level tier for all new agents.

Capabilities

Capability	Allowed
Read files	Yes (within allowed paths)
List directories	Yes (within allowed paths)
Generate plans	Yes (draft only)
View logs	Yes
Execute commands	No
Write files	No
Access secrets	No
SSH/API access	No

Quick Start

# Enter directory
cd /opt/agent-governance/agents/tier0-agent

# Bootstrap the agent (sets up credentials, workspace)
./bootstrap.sh

# Check status
./run-agent.sh status

# Read a file
./run-agent.sh read /opt/agent-governance/docs/README.md

# List a directory
./run-agent.sh list /opt/agent-governance/docs

# Generate a plan (draft - cannot execute)
./run-agent.sh plan --title "Deploy service" --description "Deploy web service" --target "sandbox-01"

Directory Structure

tier0-agent/
├── agent.py          # Main agent implementation (603 lines)
├── bootstrap.sh      # Setup and credential retrieval
├── run-agent.sh      # CLI runner script
├── config/
│   └── agent.json    # Agent configuration
├── workspace/        # Working directory for agent
├── plans/            # Generated plans (draft only)
├── logs/             # Agent activity logs
└── credentials/      # Vault credentials (populated by bootstrap)

Configuration

agent.json

{
  "agent_id": "tier0-observer-001",
  "tier": 0,
  "role": "observer",
  "constraints": {
    "allowed_paths": [
      "/opt/agent-governance/docs",
      "/opt/agent-governance/inventory",
      "/opt/agent-governance/agents/tier0-agent/workspace"
    ],
    "forbidden_paths": [
      "/opt/vault",
      "/etc/shadow",
      "/root/.ssh"
    ],
    "allowed_actions": [
      "read_file",
      "list_directory",
      "generate_plan",
      "view_logs"
    ],
    "forbidden_actions": [
      "execute_command",
      "write_file",
      "delete_file",
      "ssh",
      "access_secrets"
    ]
  }
}

CLI Commands

Status

./run-agent.sh status

Shows agent status including:

• Agent ID and tier
• Connection to governance ledger
• Heartbeat status
• Revocation status

Read File

./run-agent.sh read <file_path>

Reads a file if within allowed paths. Blocked paths return an error.

List Directory

./run-agent.sh list <directory_path>

Lists directory contents if within allowed paths.

Generate Plan

./run-agent.sh plan \
    --title "Plan title" \
    --description "What this plan does" \
    --target "sandbox-01" \
    --steps '["step1", "step2"]'

Creates a draft plan. Plans are saved to plans/ directory but cannot be executed by Tier 0.

Governance Integration

Ledger Logging

All actions are logged to SQLite:

def log_action(action: str, success: bool, data: Any = None):
    conn = sqlite3.connect(LEDGER_DB)
    cursor = conn.cursor()
    cursor.execute("""
        INSERT INTO agent_actions
        (timestamp, agent_id, tier, action, decision, success)
        VALUES (?, ?, ?, ?, ?, ?)
    """, [
        datetime.now(timezone.utc).isoformat(),
        AGENT_ID,
        AGENT_TIER,
        action,
        "EXECUTE" if success else "BLOCKED",
        1 if success else 0
    ])
    conn.commit()

Heartbeat

Agent sends heartbeat to DragonflyDB:

def update_heartbeat():
    redis_client.setex(
        f"agent:heartbeat:{AGENT_ID}",
        30,  # 30 second TTL
        json.dumps({
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "status": "active",
            "tier": AGENT_TIER
        })
    )

Revocation Check

Before each action, agent checks if it has been revoked:

def is_revoked() -> bool:
    return redis_client.exists(f"agent:revoked:{AGENT_ID}")

Path Validation

def is_path_allowed(path: Path) -> bool:
    """Check if path is within allowed paths and not forbidden"""
    # Check forbidden first
    for forbidden in FORBIDDEN_PATHS:
        if str(path).startswith(forbidden):
            return False

    # Check allowed
    for allowed in ALLOWED_PATHS:
        if path.is_relative_to(allowed):
            return True

    return False

Promotion to Tier 1

To be promoted to Tier 1, this agent must demonstrate:

Requirement	Threshold
Total actions	100+
Consecutive compliant runs	10+
Error rate	< 5%
Days active	7+

Promotion is tracked in agent_metrics table:

SELECT compliant_runs, consecutive_compliant, current_tier
FROM agent_metrics
WHERE agent_id = 'tier0-observer-001';

Testing

# Test bootstrap
./bootstrap.sh

# Test status
./run-agent.sh status

# Test read (should succeed)
./run-agent.sh read /opt/agent-governance/docs/README.md

# Test forbidden read (should fail)
./run-agent.sh read /etc/shadow

# Test that execution is blocked
./run-agent.sh exec ls  # Should fail - Tier 0 cannot execute

Error Handling

Error	Cause	Resolution
PATH_FORBIDDEN	Attempted access to forbidden path	Use allowed paths only
ACTION_FORBIDDEN	Attempted forbidden action	Upgrade to higher tier
REVOKED	Agent has been revoked	Contact governance admin
HEARTBEAT_TIMEOUT	Lost connection to DragonflyDB	Check DragonflyDB status

Architecture Reference

Part of the Agent Governance System.

See also:

• Tier 1 Agent - Execution-capable agent (next tier)
• Agents Overview - All agents

---

Last updated: 2026-01-24