# قبل (خطير - الوكيل لديه وصول كامل للنظام)
python my_agent.py

# بعد (داخل صندوق الرمل)
agentguard run -- python my_agent.py

┌─────────────────────────────────────────────────────────────┐
│ Layer 0: سجن نظام الملفات (sandbox-exec على macOS)          │
│   تطبيق على مستوى النواة. يقيد كتابات الملفات والشبكة       │
│   على مستوى استدعاءات النظام. لا يمكن للوكيل تجاوزه من      │
│   مساحة المستخدم. يمنع Python's open(), requests.post(), إلخ.│
├─────────────────────────────────────────────────────────────┤
│ Layer 1: وكيل الشبكة                                        │
│   وكيل HTTP/HTTPS شفاف. يتم فحص كل استدعاء شبكي يقوم به    │
│   الوكيل مقابل السياسة. السماح/المنع لكل وجهة مع رؤية كاملة  │
│   في واجهة المستخدم النصية (TUI).                            │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: واجهات PATH الوهمية                                 │
│   نصوص شل وهمية تعترض الأوامر مثل git, pip, curl, rm.       │
│   كل وهمية تطلب الإذن من الخفي (daemon) قبل تشغيل         │
│   الثنائي الحقيقي.                                          │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: محرك السياسات + خفي الموافقة                        │
│   قواعد مبنية على YAML تقيم كل إجراء معترض.                 │
│   السماح تلقائياً بالأوامر الآمنة، حظر الخطيرة تلقائياً،     │
│   وعرض الباقي على المستخدم للموافقة.                         │
└─────────────────────────────────────────────────────────────┘

go build -o agentguard ./cmd/agentguard/
go build -o agentguard-check ./cmd/agentguard-check/

agentguard init

agentguard run -- python my_agent.py

agentguard run --headless -- claude

tail -f ~/.agentguard/logs/headless.log

agentguard run [flags] -- <command> [args...]
    --policy <path>     استخدام ملف سياسة محدد
    --headless          لا TUI - الوكيل يحصل على الطرفية
    --default-allow     السماح تلقائياً بقرارات PROMPT في الوضع بدون رأس (افتراضياً: منع تلقائي)
    --no-sandbox        تعطيل sandbox-exec (الوهميات والوكيل لا يزالان نشطين)

agentguard init         إنشاء ملف سياسة افتراضي
agentguard version      طباعة الإصدار

version: 1

deny:
  # منع الأوامر الخطيرة
  - command: "rm"
    args: "-rf *"
    reason: "الحذف المتكرر القسري خطير جداً"
  - command: "sudo"
    args: "*"
    reason: "رفع الصلاحيات غير مسموح به"
  - command: "chmod"
    args: "777 *"
    reason: "الأذونات القابلة للكتابة عالمياً خطيرة"

  # منع قراءة الملفات الحساسة (يتم تطبيقه بواسطة sandbox-exec)
  - file:
      path: "*.env"
      action: "read"
      reason: "لا تدع الوكيل يقرأ ملفات .env"
  - file:
      path: "*.pem"
      action: "read"
      reason: "لا تدع الوكيل يقرأ المفاتيح الخاصة"

allow:
  # أوامر آمنة للقراءة فقط
  - command: "ls"
  - command: "cat"
  - command: "pwd"
  - command: "echo"
  - command: "grep"
  - command: "head"
  - command: "tail"
  - command: "wc"

  # git للقراءة فقط
  - command: "git"
    args: "status"
  - command: "git"
    args: "log *"
  - command: "git"
    args: "diff *"

  # السماح بالكتابة إلى مساحة العمل
  - file:
      path: "/tmp/workspace/**"
      action: "write"

  # السماح بنقاط نهاية API محددة
  - network:
      destination: "api.anthropic.com:443"
  - network:
      destination: "api.github.com:443"

- command: "git"
  args: "push *"
  reason: "الدفع يتطلب موافقة"

- file:
    path: "*.env"
    action: "read"     # "read" أو "write"
    reason: "حماية الأسرار"

- network:
    destination: "api.anthropic.com:443"

agentguard/
├── cmd/
│   ├── agentguard/              # الثنائي الرئيسي لواجهة CLI
│   └── agentguard-check/        # الثنائي المساعد للوهميات
├── internal/
│   ├── policy/                  # محرك السياسات (تحليل YAML، تقييم القواعد)
│   ├── events/                  # نظام الأحداث (سجل تدقيق JSONL، نشر/اشتراك)
│   ├── daemon/                  # خفي مركزي (مقبس Unix، قائمة انتظار الموافقة)
│   │   └── client/              # مكتبة العميل للوهميات
│   ├── shim/                    # مولد الوهميات (اعتراض قائم على PATH)
│   ├── proxy/                   # وكيل شبكة شفاف
│   ├── spawner/                 # التنسيق + تكامل صندوق رمل macOS
│   └── ui/tui/                  # واجهة المستخدم النصية (Bubble Tea)
├── configs/
│   └── default_policy.yaml      # ملف سياسة مرجعي
├── .gitignore
├── go.mod
├── LICENSE
└── README.md

{"id":"a1b2c3","timestamp":"2026-03-22T14:30:00Z","session_id":"abc123","source":"shim","command":"git","args":["push","origin","main"],"decision":"deny","decided_by":"human","response_time_ms":3200}
{"id":"d4e5f6","timestamp":"2026-03-22T14:30:01Z","session_id":"abc123","source":"proxy","network_dst":"api.anthropic.com:443","decision":"allow","decided_by":"policy"}

# جميع الإجراءات الممنوعة اليوم
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decision == "deny")'

# جميع طلبات الشبكة
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.source == "proxy")'

# الأوامر التي تطلبت موافقة بشرية
cat ~/.agentguard/logs/2026-03-22.jsonl | jq 'select(.decided_by == "human")'

go test ./... -race