docs/concepts/trust-and-learning.md

Trust and learning

Autonomy is set per action in each workspace (for example hubspot.update), not for an agent as a whole. An action either waits for a person or runs on its own above its confidence bar.

The six rungs

RungIdRuns on its own?
ObserveobserveNo
RecommendrecommendNo
AssistassistNo
Execute with approvalexecute-with-approvalNo — the default
Execute within boundsexecute-within-boundsYes, above the bar
Operate autonomouslyautonomousYes, above the bar

Every automatic run is recorded and shown on Decided.

Done for you, with Undo

An action runs on its own above 80% confidence, with Undo, when it is reversible, its risk tier is low, and nobody set a rule or rung for it.

Always waits for a person

Sending email (gmail.send, or anything granted send_email), connecting a new source (source.connect), and a few review and enrollment actions never run on their own. Also: an action waits if the agent didn't give a confidence, its own advice was to reject or snooze, or the conversation's autonomy is set to ask.

Earning a promotion

Each decision is written to the alignment ledger against the action it covers. An admin promotes an action at /dashboard/autonomy, and the server refuses a promotion the record doesn't support:

RiskDecisions in 30 daysAgreementAlsoHighest rung
Low2090%no rejection in 14 days; confidence ≥ 0.85Operate autonomously
Medium4095%no high-confidence rejection in 30 days; confidence ≥ 0.95Execute within bounds
High——needs an explicit rule in trust.yaml—

Agreement measures whether people would have let the action run, not whether it was correct. External actions without a default tier are high risk unless trust.yaml says otherwise.

Stepping down

If someone rejects work an action did on its own, it drops one rung (never below Execute with approval) and is flagged. An Undo on a done-for-you action puts a hold on it, so the next one asks.

trust.yaml

rules:
  - action: hubspot.update
    autoApproveAbove: 0.9
    enabled: true
    rung: execute-within-bounds
    risk: low

Applying the workspace overrides in-app promotions for the actions it names.

Learning from decisions

  • A reject or Other with a note, a thumbs up or down with a note on a chat message, and corrections in chat become candidate rules. Duplicates raise an existing rule's count instead of adding a new one.
  • Candidates are adopted through the learning.adopt_rule action, governed by defaults.learningEagerness in workspace.yaml (0–10, default 7). The bar is 0.96 − (eagerness − 1) × 0.04: 7 → 0.72, 10 → 0.60, 0 → always ask. Below the bar, a candidate shows on Review as a Suggested rule.
  • "Remember this" for a personal preference applies at once, for that person only.
  • Rules live in learning steps (learnings/<name>.yaml), mounted for agents and managed at /dashboard/learnings.
  • Voice rules (voice.yaml: never, prefer, allow, limits) block banned patterns before anything is sent. Phrases reviewers delete become never candidates that are never adopted automatically.