Agent Governance Model: Communication and External System Agents¶

Thinklio Shared Specification Version 0.1 | March 2026

1. Purpose¶

Several Thinklio agents interact with external systems — email, calendars, messaging platforms — where autonomous action carries real-world consequences. A consistent governance model applies across all of these agents. This document defines that model. Individual agent specs reference it rather than repeating it.

Agents governed by this model: Mail, Calendar, Messenger, Enquiry.

2. Permission Levels¶

Every action an agent can take falls into one of four permission levels:

Level	Description
`read`	The agent may read and retrieve data from the external system
`draft`	The agent may compose content (email, event, message) but not send or commit it without explicit user approval
`send_with_approval`	The agent may prepare and queue actions, which are executed only after the user approves each one
`send_autonomous`	The agent may act without per-action approval, within defined constraints

These levels are not globally assigned — they are assigned per action type within each agent. For example, a user might have read for all mail, draft for replies, and send_autonomous only for a narrow class of auto-responses.

3. Governance Hierarchy¶

Permissions are configured at three levels. Lower levels may only be equal to or more restrictive than the level above.

Org level  (set by org admin — hard ceiling)
    └── Team level  (set by team admin — within org limits)
            └── User level  (set by user — within team limits)

An org can prohibit send_autonomous entirely. A team within that org cannot grant it regardless of user preference. A user who wants broader permissions than their team allows must request a team-level change.

4. Constraint Types¶

Within a permission level, constraints narrow what the agent may do autonomously:

Constraint	Description
Recipient allowlist	Autonomous send only to specified addresses/contacts
Recipient blocklist	Autonomous send never to specified addresses/contacts
Domain restriction	Limit to/from specific email domains or platforms
Content rules	Prohibit certain content types (e.g. attachments, external links) in autonomous sends
Volume limit	Maximum number of autonomous actions per hour/day
Time window	Autonomous action only within specified hours
Escalation trigger	Conditions under which the agent must escalate to human approval regardless of permission level

5. Approval Workflow¶

When an action requires approval (send_with_approval level, or when an escalation trigger fires):

The agent queues the action with a full preview of what will be sent/done
The user is notified (in-app and/or via configured notification channel)
The user reviews and approves, edits, or rejects
On approval, the action executes immediately
On rejection, the action is discarded and the agent logs the outcome
Unapproved actions expire after a configurable timeout (default: 24 hours)

6. Audit Log¶

All agent actions on external systems — reads, drafts, sends, approvals, rejections — are recorded in an immutable audit log. The log records:

Timestamp
Agent and run ID
Action type and permission level applied
Summary of content (not full content for privacy)
Approval chain if applicable
Outcome

The audit log is accessible to org and team admins. Users can access their own log entries.

7. Credential Management¶

Credentials for external system access (OAuth tokens, API keys, app passwords) are stored in the Keeper agent. Communication agents do not hold credentials directly — they request authenticated access through the Keeper at run time, and the Keeper executes the external call on their behalf.

This means the agent never has visibility of the raw credential value. If a credential is revoked or rotated in the Keeper, all dependent agents lose access immediately.

Referenced by: Mail Agent, Calendar Agent, Messenger Agent, Enquiry Agent