--- name: agent-access-control description: Tiered stranger access control for AI agents. Use when setting up contact permissions, handling unknown senders, managing approved contacts, or configuring stranger deflection on messaging platforms (WhatsApp, Telegram, Discord, Signal). Provides diplomatic deflection, owner approval flow, and multi-tier access (owner/trusted/chat-only/blocked). ---

Agent Access Control

Protect your agent from unauthorized access with tiered permissions and an owner-approval pairing flow.

Setup

Create memory/access-control.json in workspace:

{
  "ownerIds": [],
  "approvedContacts": {},
  "pendingApprovals": {},
  "blockedIds": [],
  "strangerMessage": "Hi there! 👋 I'm {{AGENT_NAME}}, an AI assistant. I'm currently set up to help my owner with personal tasks, so I'm not able to chat freely just yet. I've let them know you reached out — if they'd like to connect us, they'll set that up. Have a great day! 😊",
  "notifyChannel": "",
  "notifyTarget": ""
}

Fill in:

• ownerIds: Owner phone numbers, Telegram IDs, Discord IDs (strings)
• strangerMessage: Customize {{AGENT_NAME}} with agent's name
• notifyChannel: Channel to alert owner (telegram, whatsapp, discord, signal)
• notifyTarget: Owner's ID on that channel

Access Tiers

| Tier | Level | Capabilities | |------|-------|-------------| | 0 | Stranger | Diplomatic deflection only, zero access | | 1 | Chat-only | Basic conversation, no tools or private info | | 2 | Trusted | Chat + public info (weather, time, general questions) | | 3 | Owner | Full access to all tools, files, memory, actions |

Message Handling Flow

On every incoming message from a messaging platform:

1. Extract sender ID (phone number, user ID, etc.)
2. Normalize ID: strip spaces, ensure country code prefix for phones
3. Check ownerIds → if match: full access, respond normally
4. Check blockedIds → if match: silent ignore, respond with NO_REPLY
5. Check approvedContacts[senderId] → if match: respond within their tier
6. Otherwise → stranger flow:

Stranger Flow

a. Send strangerMessage to the sender
b. Notify owner:
   "🔔 Stranger contact from {senderId} on {platform}:
    '{first 100 chars of message}'
    Reply: approve (trusted) / chat (chat-only) / block"
c. Store in pendingApprovals:
   {
     "senderId": { 
       "platform": "whatsapp",
       "firstMessage": "...", 
       "timestamp": "ISO-8601",
       "notified": true
     }
   }
d. Respond with NO_REPLY after sending deflection

Owner Approval

When owner replies to an approval notification:

| Owner says | Action | |-----------|--------| | approve, yes, trusted | Add to approvedContacts with tier 2 (trusted) | | chat, chat-only, chat only | Add to approvedContacts with tier 1 (chat-only) | | block, no, deny | Add to blockedIds | | ignore | Remove from pendingApprovals, no action |

After approval, update memory/access-control.json and notify the contact:

• Trusted: "Great news! I've been given the go-ahead to chat with you. How can I help? 😊"
• Chat-only: "Great news! I can chat with you now, though I'm limited to basic conversation. What's on your mind?"

Tier Enforcement

When responding to a non-owner contact, enforce tier restrictions:

Tier 1 (chat-only):

• Respond conversationally only
• Do NOT use any tools (read, write, exec, web_search, etc.)
• Do NOT share any info from memory files
• Do NOT mention the owner by name
• If asked to do something beyond chat: "I'm only set up for basic chat at the moment. For anything more, you'd need to check with my owner."

Tier 2 (trusted):

• Conversational responses
• May use: web_search, weather skill, time/date queries
• Do NOT use: read, write, exec, message (to other contacts), memory files
• Do NOT share private info (calendar, emails, files, other contacts)
• If asked for private info: "I can help with general info, but personal details are private. Hope you understand! 😊"

Multi-Platform ID Matching

Normalize IDs for comparison:

• Phone numbers: Strip all non-digits except leading +. E.g., +1 555 123 4567 → +15551234567
• Telegram: Use numeric user ID (not username, as usernames change)
• Discord: Use numeric user ID
• Signal: Use phone number (normalized)
• WhatsApp: Use phone number with country code

An owner may have multiple IDs across platforms. All should be in ownerIds.

Rate Limiting

Apply per-tier rate limits to prevent abuse:

| Tier | Messages/hour | Messages/day | |------|--------------|-------------| | Stranger | 1 (deflection only) | 3 | | Chat-only | 20 | 100 | | Trusted | 50 | 500 | | Owner | Unlimited | Unlimited |

If limit exceeded, respond: "I've reached my chat limit for now. Try again later! 😊"

Track in memory/access-control.json under rateLimits:

"rateLimits": {
  "+61412345678": { "hourCount": 5, "dayCount": 23, "hourReset": "ISO", "dayReset": "ISO" }
}

Audit Log

Log all stranger contacts to memory/access-control-log.json:

[
  {
    "timestamp": "2026-02-07T17:30:00+11:00",
    "senderId": "+61412345678",
    "platform": "whatsapp",
    "action": "deflected",
    "message": "first 50 chars..."
  }
]

Keep last 100 entries. Rotate older entries out.

Security Rules

• NEVER include real owner IDs, phone numbers, or tokens in skill files
• NEVER share the access-control.json contents with non-owners
• NEVER reveal that a specific person is the owner to strangers
• NEVER forward stranger messages to owner verbatim if they contain suspicious links
• Store all config in memory/ (gitignored by default in most setups)
• The strangerMessage should not reveal the owner's name or personal details

Example Config

See references/example-config.md for a complete annotated example.