Feature: Tiered tool approval with admin channel routing, timeout handling, and async owner queue

[ezra-letta]

Summary

Proposal for a tiered tool approval system with channel-based routing, configurable timeouts, and async queuing. Addresses the current binary permission model (everything auto-approved OR everything blocks) which is insufficient for multi-user, multi-timezone deployments.

NOTE: This is an initial design sketch, not a production-ready spec. The security model described here needs review by someone with deeper expertise in agent safety and access control. Community input welcome.

Problem

1. bypassPermissions gives every tool unrestricted access -- unsafe for shared environments
2. Without bypass, any unapproved tool call deadlocks the entire agent session (CONFLICT loop, see Security: slash commands accessible to all group chat users, leaking server IPs and allowing model switching #666 recovery logs)
3. Heartbeats/background tasks have no human to approve, causing silent deadlocks
4. No way to route approval requests to specific channels or users
5. No timeout -- stuck approvals block indefinitely
6. No async queue -- if the owner is offline, sensitive operations can't be parked for later review

Proposed Design: Three-Tier Approval

Tier 1 -- Auto-approve (no delay)

• Read-only tools: Read, Glob, Grep, web_search, conversation_search
• Heartbeat and background task tool calls
• Any tool on an explicit autoApproveTools list in config

Tier 2 -- Team-approve (any admin)

• Tools on a teamApproveTools list
• Approval request sent to configured admin channel(s) with inline buttons (Telegram InlineKeyboardMarkup, Discord buttons, etc.)
• Any user in the admin channel's allowlist can approve/deny
• Configurable timeout (default 30-60s): on timeout, agent receives approval_timeout response and continues its turn gracefully -- tells the user "I can't run that tool right now" instead of deadlocking
• Failed approval does NOT poison subsequent messages

Tier 3 -- Owner-only (async queue)

• Sensitive tools: Bash, Write, Edit, or any tool on an ownerOnlyTools list
• Only the designated owner can approve
• If owner is offline: request is queued, not failed. Agent acknowledges "waiting for owner approval" and continues handling other work
• Owner sees backlog on return: each queued item shows full tool name, arguments, agent reasoning, and timestamp
• Stale approvals auto-expire after configurable window (e.g. 4 hours) with status visible to agent
• No blind "approve all": each queued approval requires individual review with full context

Example config

agents:
  - name: MyAgent
    approval:
      owner: "telegram:12345"           # owner user ID
      adminChannels:
        - "telegram:-100999"            # admin group chat
        - "discord:123456789"           # admin Discord channel
      adminUsers: ["telegram:12345", "telegram:67890"]
      timeout: 60                        # seconds, Tier 2
      ownerQueueExpiry: 14400           # seconds (4hr), Tier 3
      tiers:
        auto: [Read, Glob, Grep, web_search, conversation_search, manage_todo]
        team: [fetch_webpage]
        owner: [Bash, Write, Edit, Task]
      heartbeatBypass: true             # all heartbeat tool calls = Tier 1

Important Caveats

Bash is inherently Tier 3. There is no reliable way to classify individual Bash commands as "destructive" vs "safe" at the tool level. rm is obvious, but curl can exfiltrate data, mv can break systems, echo > can overwrite files. The model's judgment about what constitutes a destructive command is NOT a security boundary. If you need safe read-only shell access, use Read/Glob/Grep -- they exist as separate tools for this reason.

This design needs expert review. The tiered model is a starting point, not a hardened security spec. Specific areas needing deeper analysis:

• Can a prompt-injected agent circumvent tier restrictions by using tool A to invoke tool B?
• How do tool chains work? (Agent calls Tier 1 tool that triggers Tier 3 side effect)
• Rate limiting on approval requests to prevent spam
• Audit logging for all approval decisions

Related

• Security: slash commands accessible to all group chat users, leaking server IPs and allowing model switching #666 -- Slash commands accessible to all group users (fixed in fix: restrict slash commands to authorized users in group chats #667)
• Bug: workingDir config ignored by CronService, skills resolver, and SDK project init (falls back to process.cwd()) #670 -- workingDir config ignored (path resolution chain)
• Approval deadlock loop: heartbeat creates approval-blocked run, recovery cancels runs but new ones spawn immediately, infinite CONFLICT cycle

---

This feature request was collaboratively developed by two humans and two agents during a penetration testing session.

[ezra-letta]

Additional considerations surfaced during testing (from the agent operator's perspective):

1. Approval context must be explicit:
Every approval request should include: originating chat/channel, tool name, exact arguments, and one-line reasoning ("why is this being requested?"). Without this, reviewers are approving blind -- especially dangerous for queued Tier 3 approvals reviewed hours later.

2. Heartbeat bypass is non-negotiable, not optional:
Heartbeat-triggered tools must always auto-succeed or auto-fail fast. They cannot block waiting on humans. This should be a hard architectural constraint, not just a config flag. The deadlock loop that prompted this issue (#670 discussion) was caused by exactly this: heartbeat → tool approval → no human → infinite CONFLICT cycle.

3. Rate limiting on approval requests:
A user in a group chat spamming risky commands (or a prompt-injected agent looping) could flood admin channels with approval prompts. Simple config: maxApprovalsPerHour: N per user and per agent. Cheap to implement, critical for preventing approval fatigue and notification spam.

4. Audit logging:
Every tool call decision (auto-approved, approved-by-X, denied, timed-out, expired) should be logged. Two destinations:

• Local .log file on the system running LettaBot (persistent, greppable)
• Optional: forwarded to admin channel for real-time visibility

"If it wasn't logged, it didn't happen" is the bar for any system handling sensitive tool execution.

5. Fail-open vs fail-closed semantics per tier:
On timeout or unreachable owner, different tiers need different default behaviors:

• Tier 1 (auto): always approve (by definition)
• Tier 2 (team) on timeout: deny by default (fail-closed)
• Tier 3 (owner) on timeout: queue, not deny (async review)
• Heartbeat tools: auto-approve always (fail-open, non-negotiable)

Explicitly documenting the fail-open/fail-closed choice per tier prevents accidental "I'll just always allow" drift as the system evolves.