Authority & Safety

The authority system controls how much autonomy Usejarvis has. It determines which actions the agent can take on its own, which require your approval, and which are blocked entirely. Authority is enforced at every level: the primary agent, sub-agents, and workflows all respect the same rules.

Authority settings live in the dashboard (the Authority room and Settings → Authority); they are part of the first-run setup and stored in the settings database. The YAML below shows the setting shapes.

Authority Levels

Authority is a numeric level from 1 to 10. Every action category has a minimum level:

Action category	Minimum level	Impact
read_data	1	read
spawn_agent	1	write
write_data	3	write
send_message	3	external
execute_command	5	destructive
access_browser	5	external
control_app	5	write
send_email	7	external
install_software	7	destructive
make_payment	9	destructive
modify_settings	9	destructive
delete_data	9	destructive
terminate_agent	9	destructive

In practice: up to 2 is read-only; up to 4 adds writes and messages; up to 6 adds commands, apps, and browser; up to 8 adds email and software installs; 9 and 10 unlock everything.

default_level (shipped default: 3) is a floor, not a fallback: every agent runs at the higher of its own role level and the default. The dashboard authority slider is that floor.

authority:
  default_level: 3

Governed Actions

Governed categories never block an action; they convert an allowed action into an approval request. The shipped default governs three:

authority:
  governed_categories:
    - send_email
    - send_message
    - make_payment

Any of the 13 category names above can be added.

Decision Order

When the agent attempts an action, the authority engine evaluates in this order:

1. Temporary grants: a parent agent can grant a child a category for the duration of a task; a matching grant allows immediately
2. Per-action overrides: explicit allow/deny, with role-specific overrides beating global ones
3. Context rules: time-based, tool-based, or always-on rules
4. Level check: the effective level (max of role level and default_level) against the category’s minimum
5. Governed categories: if allowed but governed, the action becomes an approval request

Emergency state is a separate gate in front of all of this.

Per-Action Overrides

authority:
  overrides:
    - action: send_email
      allowed: false               # Block entirely, regardless of level

    - action: execute_command
      requires_approval: true      # Always ask, even at high authority

    - action: delete_data
      role_id: research-analyst    # Only applies to this specialist
      allowed: false

Context Rules

authority:
  context_rules:
    - id: no-purchases-at-night
      action: make_payment
      condition: time_range
      params:
        start_hour: 22
        end_hour: 24
      effect: deny
      description: "Block payments from 10 PM to midnight"

    - id: always-approve-browser
      action: access_browser
      condition: tool_name
      params:
        tool_name: "browser_"
      effect: require_approval

Condition Types

Condition	Params	Description
time_range	start_hour, end_hour (integer hours)	Matches when the current hour is in [start_hour, end_hour). Overnight windows need two rules.
tool_name	tool_name (string)	Exact or prefix match on the tool name
always	none	Always matches

Effects

allow, deny, require_approval.

Approval Workflow

When an action requires approval, Usejarvis asks everywhere you are:

• Dashboard: an approval card with the action’s impact, approve/deny buttons
• Telegram and Discord: a plain-text message; reply approve <id> or deny <id> with the short id from the message

The agent waits up to 5 minutes. After that it moves on, but the request stays pending and can still be resolved from the dashboard; stale requests are eventually expired.

Voice approvals are safety-gated: destructive actions (payments, deletes, shell execution, installs, settings changes, agent termination) can never be approved by voice. Non-destructive approvals by voice require high transcription confidence, otherwise you get a clarifier card instead.

Learning & Auto-Approve

authority:
  learning:
    enabled: true
    suggest_threshold: 5    # After 5 approvals, suggest auto-approve

When you approve the same type of action repeatedly, Usejarvis suggests an auto-approve rule. A denial resets the counter. This gradually reduces approval fatigue for routine actions.

Emergency Controls

State	Effect
normal	Agent operates according to authority rules
paused	The agent still receives messages, but every tool call returns blocked
killed	Agent fully stopped. No responses, no actions.

Set it from the Authority room, or:

authority:
  emergency_state: normal    # normal | paused | killed

Sub-Agent Authority

Sub-agents run through the same engine with two differences: governed actions are denied outright for sub-agents (they cannot request approval; authority stays with the top-level agent), and a parent can pass a temporary grant for a specific category for the duration of a delegated task. Per-action overrides can target specific roles via role_id.

Audit Trail

Every authority decision is logged to the audit_trail table in the SQLite database: which agent, which tool, the action category, the decision, whether it executed, execution time, and the resolution channel (click, voice, or system).

View recent decisions in the Authority room, or directly:

sqlite3 ~/.jarvis/jarvis.db "SELECT * FROM audit_trail ORDER BY created_at DESC LIMIT 20"