---
title: User-Agent Contract
description: The single source of truth for what the agent may and may not do
updated: 2026-04-04
---

# User-Agent Contract

> **What is this file?** The legally binding rules between you and your agent. Every action the agent takes is checked against this contract in real time — it is **enforced in code**, not a suggestion.
>
> **Who edits it?** You do, via the Control Panel or directly in this file. The agent can only modify it with your explicit confirmation (the `modify_contract` action requires confirm-level permission).
>
> **What can you change?** Move actions between `allow`, `confirm`, and `block`. Add new actions. Change proactivity level, privacy mode, coaching settings, or any other section.
>
> **What you should not do:** Do not remove the YAML code block structure or the `default: deny` line — the contract engine parses it. Malformed YAML will cause the agent to fall back to default-deny on everything.

---

## Who We Are

- **You** — your identity lives in USER.md and PROFILE.md
- **Your Agent** — its personality lives in SOUL.md
- **This Contract** — the rules between you, enforced programmatically

---

## How the Agent Operates

### Privacy

<!-- Choose one: cloud | local -->
**Mode**: cloud

- **Cloud** — vault content is sent to the LLM provider (Anthropic/OpenAI) during reasoning. Best quality and full tool support.
- **Local** — all reasoning on-device via Ollama. Nothing leaves your machine. Small models (7B-13B) handle direct commands well but may struggle with ambiguous requests. Larger models (70B+) approach cloud quality. See `docs/architecture/privacy-and-data-flow.md` for details.

### Proactivity

<!-- Choose one: Observer | Advisor | Assistant | Partner -->
**Level**: Advisor

| Level | Behavior |
|-------|----------|
| Observer | Only responds when explicitly asked |
| Advisor | Suggests actions but never executes without approval |
| Assistant | Executes routine tasks autonomously, asks for non-routine |
| Partner | Full autonomy within the permissions below |

---

## Permissions

> **This is the enforced section.** The YAML block below is parsed by the contract
> engine and checked before every action. Edit it to change what the agent can do.

<!-- MACHINE-ENFORCED — parsed automatically, checked on every action -->

```yaml
default: deny

allow:
  - read_inbox
  - read_vault
  - search
  - draft_content
  - journal_write
  - log_observation
  - log_decision
  - send_notification
  - audit_log
  - list_tasks
  - list_goals
  - heartbeat
  - daily_briefing
  - vault_search
  - list_folders
  - delegate_task
  - write_vault
  - canvas_push
  - analyze_user_behavior
  - track_predictions
  - generate_briefing
  - generate_eod
  - generate_reflection
  # Graph curator — auto-apply safe entity-merge proposals (default:
  # comma-prefix only; reversible via /api/graph/merge-audit retract).
  - auto_merge_entity
  # Finance subsystem (Phase 1) — read paths and OCR ingest
  - ingest_receipt        # extract receipt to draft (no commit)
  - query_finance         # read transactions / merchants
  - audit_transaction     # auditor's read-only quality check
  - query_budget          # read budget consumption (Phase 2)

confirm:
  - send_email
  - send_message
  - manage_channels
  - create_task
  - modify_vault_file
  - create_event
  - schedule_calendar
  - modify_project
  - financial_entry
  - modify_contract
  - update_memory
  - send_gated_content
  - move_email
  - delete_email
  - reset_wiki
  - store_user_insights
  - suggest_contract_change
  - proactive_outreach
  - create_video
  # Finance subsystem (Phase 1+2) — write paths gated by user approval
  - delete_transaction     # archive a verified transaction
  - merge_merchants        # consolidate two merchant records
  - set_budget             # create / update a budget cap (Phase 2)
  - delete_budget          # remove a budget (Phase 2)

block:
  - delete_vault_file
  - access_financial_account
  - share_external
  - override_security
  - modify_soul
  - log_vault_content
  - store_content_in_heartbeat

overrides:
  # Per-integration overrides (uncomment and edit as needed):
  # telegram: allow_send        # skip confirmation for Telegram
  # linkedin: block_all         # don't touch LinkedIn
  # slack: confirm_all          # always ask before Slack actions

gated_dirs:
  - finances
  - health
  - journal
  - goals
  - projects
  - companies
  - contacts
```

### What these mean

**Allowed** — the agent does these without asking:

| Action | What it does |
|--------|-------------|
| `read_inbox` | Read your email inbox and messages |
| `read_vault` | Read vault files (gated dirs require confirmation in cloud mode) |
| `search` | Search your knowledge base (always local, never sent to cloud) |
| `draft_content` | Draft messages and documents (saved to drafts/) |
| `journal_write` | Write observations and decisions to today's journal |
| `send_notification` | Notify you via configured channels |
| `heartbeat` | Background monitoring every 30 minutes |
| `daily_briefing` | Generate morning and end-of-day reports |
| `canvas_push` | Push content to the visual Canvas workspace (markdown, code, tables, JSON, diagrams) |
| `auto_merge_entity` | Auto-apply safe entity-merge proposals (default: comma-prefix only — "Sarah, Chen" + "Sarah Chen" merge into the shorter form). Reversible from the Graph page's Recent merges panel. |

**Requires Confirmation** — the agent asks before doing these:

| Action | What it does |
|--------|-------------|
| `send_email` | Send an email on your behalf |
| `send_message` | Send a message via a channel on your behalf |
| `create_task` | Create a new task |
| `modify_vault_file` | Change a vault file (not drafts) |
| `schedule_calendar` | Create or modify calendar events |
| `update_memory` | Update MEMORY.md from reflections |
| `send_gated_content` | Send content from gated directories to cloud LLM |
| `create_video` | Produce a narrated .mp4 video from a vault artifact or URL (opens a headless browser, generates voiceover) |

**Blocked** — the agent cannot do these under any circumstance:

| Action | Why |
|--------|-----|
| `delete_vault_file` | Permanent deletion requires human action |
| `access_financial_account` | No direct access to financial systems |
| `share_external` | No sharing with unapproved services |
| `modify_soul` | Agent cannot change its own identity without instruction |
| `log_vault_content` | Vault content and PII never appear in logs |

**Overrides** — per-integration exceptions. Uncomment a line to change behavior for a specific integration.

**Gated directories** — in cloud mode, the agent asks before sending content from these directories to the LLM provider. In local mode, this gate is unnecessary.

---

## Journal & Reflection

The journal (`vault/journal/YYYY-MM-DD.md`) is the shared thinking space. Four sections: Thoughts (you), Observations (agent), Decisions (both), Learnings (both).

| Setting | Value | Options |
|---------|-------|---------|
| Thinking-out-loud detection | ask | ask, auto, off |
| Agent observations | on | on, off |
| Agent decision logging | on | on, off |
| Reflection approval | review | review, auto |
| Weekly reflection | on | on, off |

- **ask**: agent asks "Save to journal?" when you think out loud in chat
- **review**: reflections produce a draft — you approve before MEMORY.md is updated
- **auto**: reflections update MEMORY.md directly (draft still saved for transparency)

---

## Task Delegation

When you delegate, the agent assigns a mode:

| Mode | Behavior |
|------|----------|
| Just do it (`jdi`) | Execute and report when done |
| Review (`review`) | Execute but show you before finalizing |
| Recommend (`recommend`) | Research options, you decide |
| Watch (`watch`) | Monitor a condition, alert when triggered |

You can specify mode explicitly or the agent infers from phrasing. When unsure, it asks.

When blocked, the agent escalates: logs the issue, notifies you, continues other work.

---

## Trust & Autonomy

Trust evolves per domain from task feedback. Stored in `vault/TRUST.md`.

### Evolution Rules
- 5 consecutive `good` → promote to next level
- 2 `redo` in 10 tasks → demote to previous level
- `needs_improvement` → no change (preference learned)
- Memory approvals boost "Knowledge management" trust (`good`)
- Memory rejections signal learning in "Knowledge management" (`needs_improvement`)

### Enforcement (Active)

Trust is a **real gating mechanism**, not advisory. The formula `max(global proactivity, domain trust)` is enforced at three checkpoints:

1. **Tool execution** (`agent._execute_tool`) — every tool call checks trust AFTER the contract check
2. **Subagent dispatch** (`orchestrator._dispatch_with_tools`) — subagent tool calls are always autonomous
3. **Goal pursuit** (`heartbeat._pursue_active_goals`) — goals need at least Assistant-level trust in their domain

**User-initiated actions are never gated by trust** — the user asked for it. Only autonomous paths (heartbeat, cron, goal pursuit, subagent dispatch) are gated.

Trust can **escalate** (require confirmation for contract-allowed actions) and **relax** (skip confirmation for contract-confirm actions when domain trust is Partner). Contract `block` is never overridable by trust.

### Trust Levels
| Level | Autonomous Behavior |
|-------|---------------------|
| Observer | Cannot act autonomously — all actions blocked |
| Advisor | All autonomous actions require confirmation |
| Assistant | Routine actions proceed, non-routine require confirmation |
| Partner | Full autonomy within contract boundaries |

### Domain Mapping
Each tool maps to a trust domain via `trust-evolution/config/domains.yaml`. Tools not listed inherit the `general` domain.

You can override any trust score at any time.

---

## Coaching

| Setting | Value | Options |
|---------|-------|---------|
| Coaching | on | on, off |
| Frequency | weekly | daily, weekly, on_stall |
| Quiet hours | 22:00-08:00 | — |
| Track aspirations | ask | ask, auto, off |

The coach tracks goals in `vault/goals/`, detects stalls, and nudges gently. It never tells you what your goals should be.

---

## Autopilot

<!-- Choose one: off | on | scheduled -->
**Mode**: off

When enabled: reflections auto-approve, trusted domains auto-execute, notifications batch into daily digest. Everything logged for post-review.

Set an expiry date and the agent reverts automatically: "Welcome back. Here's what happened."

---

## Your Rights

**Right to forget.** Request the agent forget any content. It is completely removed from all stores — vault, search index, chat history, memory. Not recoverable.

**Data portability.** Everything is markdown, TOML, and JSON. Export anytime. If AgntSpace ceases to exist, your data survives.

**Audit.** Every autonomous action is logged to `audit.log` with timestamp, action, target, and approval status. Never contains vault content or PII. View in the control panel: "What did my agent do?"

---

## Security

- External data sanitized before agent context
- API keys handled by Python, never exposed to the LLM
- Application logs never contain vault content or PII
- Database (`agntspace.db`) is disposable — rebuilds from vault files
- Optional SQLCipher encryption for database at rest
- Credentials encrypted with Fernet (AES-128) at rest
