StrataDocs
↑↓ navigate ↵ open esc close

Agent permissions and safety

Agents run without a human in the loop, so the rules for what they can do are stricter than for chat. This page covers the per-agent tool set, the dry-run sandbox, the safety patterns we recommend, and the org and per-user controls admins can apply on top.

The allowed tool set

Every agent has its own Capabilities map (the Capabilities step of the wizard). The map lists every tool the AI might call during a run, grouped by category:

  • Database — run_sql.
  • Outlook — search_outlook, read_outlook_email, read_outlook_attachment, send_email.
  • OneDrive — search_onedrive, read_onedrive_file, save_to_onedrive.
  • Jira — search_jira, write_jira.
  • Confluence — search_confluence, write_confluence.
  • Generation — generate_excel, generate_pdf.
  • Code & composition — run_python, invoke_agent.
  • Web — search_web.

A tool only enters the agent's toolset if its switch is on in the wizard and every layer of governance above it allows it (the org's enabled extensions and the per-user agent extension mask). At runtime the AI sees only the tools that survived all layers — others are stripped entirely, not just "denied on call".

Note

If web search is disabled for your account, the Web group never appears in the wizard. Other categories stay visible even when the underlying extension is off at the org level — those are enforced at runtime (see "Server-side enforcement" below), so a switch you flip on may still be stripped before the run if the org or your per-user mask disallows it.

"Sensitive" tools

These tools have visible side effects outside Strata. The four that send email, write files, or write into Jira or Confluence carry a small Sensitive tag next to the name in the wizard:

  • send_email — sends a message via Outlook with no in-run confirmation prompt. (Tagged Sensitive.)
  • save_to_onedrive — creates or overwrites files in OneDrive. (Tagged Sensitive.)
  • write_jira — files issues and posts comments in Jira with no in-run approval prompt. In chat, Strata asks the member before each write; a scheduled run has nobody to ask, so the write proceeds. It also needs Jira writes to be permitted for the agent's owner — see below. Treat it as one-way: a Jira Service Management comment cannot be edited or deleted through Atlassian's API once posted. (Tagged Sensitive.) See the Atlassian extensions page.
  • write_confluence — creates pages and posts page comments in Confluence with no in-run approval prompt, on the same no-one-to-ask reasoning as write_jira. The wizard labels it Create and edit pages, but Strata has no tool that edits an existing page — it can only create new ones and comment. It resolves against the owner's Confluence write access, separately from Jira's. (Tagged Sensitive.) See the Atlassian extensions page.
  • run_python — executes sandboxed code (no network, no host filesystem, but it can still produce files and consume tokens). It isn't tagged in the wizard, but it's treated as destructive for dry runs (see below).

Everything an agent writes into Jira ends with a trailing line naming Strata, the agent, and the member the run belonged to — for example Filed by Strata — scheduled agent "Ticket triage" for dana@example.com. Jira's own author field is whoever the connection authenticates as, so that line is the only signal to a reader that an automation did it.

An agent's Atlassian access is its owner's

A scheduled agent reaches Jira and Confluence through the member who deployed it — one Atlassian connection covers both. In the default each person signs in mode it runs on that person's connection and can never see more than they can; if they disconnect, its Jira and Confluence tools go quiet. (In one organization account mode the reads go through the org's service account instead, so what it sees stops depending on the owner.)

Whether it may write is resolved for the owner in both modes, from the organization's writes toggle for that product narrowed by the owner's role and their per-member override. Jira and Confluence writes resolve independently, so an owner can be cleared for one and denied the other. Setting any of those layers to Denied stops every agent that person owns — an owner narrowed out of writes cannot regain the capability by scheduling a run. And when writes do not resolve on, write_jira (or write_confluence) is not registered for the run at all: there is no tool for the AI to call, rather than a tool that refuses. See Who may write.

These tools shouldn't be granted unless the agent's prompt genuinely needs them. The wizard's blurb on the Capabilities step reads:

Flip on only what this agent needs. Tools that send email or write files take effect without confirmation, so enable them only when you trust the prompt.

Safety pattern — errors-only notifications

The cleanest pattern for a monitor agent is errors-only notifications + minimal capabilities + tight runtime cap:

  • Capabilities: only what the task absolutely needs.
  • Notifications mode: Only on failures.
  • Response size: Quick (60s, 5,000 tokens) unless the output genuinely needs more.

The built-in SQL anomaly watcher template uses this pattern. It runs hourly during business hours (9 AM–5 PM, Mon–Fri), finds nothing wrong most of the time, and only emails when something looks off. You stay quiet and trust the silence.

Dry runs

A dry run is the agent equivalent of a test pull request — it executes the prompt with destructive tools (send_email, save_to_onedrive, run_python, write_jira, write_confluence) stripped from the toolset for that single execution. The AI sees an extra system-prompt line:

DRY RUN: Tools that send email, save files, or run code are disabled. For any such step, describe in writing what you would have done — do not pretend it succeeded.

The line doesn't name Jira or Confluence, but write_jira and write_confluence are stripped on a dry run too — the tools aren't registered, so there is nothing for the AI to call.

Result lands in run history with trigger_type=manual-dry. Notifications are skipped (no point notifying about something that didn't actually happen).

There is no dry-run control in the agent UI. A dry run is reached programmatically — POST /api/agents/:id/run?dry=1 (or dry: true in the request body). See /docs/agents/schedules.

Use dry runs before enabling Sensitive tools on a new agent. Read the run output to confirm the agent describes the destructive action correctly (which email it would send, which file it would overwrite). Only then enable the capability and let it run for real.

Reviewing run logs and outputs

Every run lands in the agent's Recent runs section, with status, trigger type, elapsed time, a short summary, and (in the run modal) the full output and an Action steps trace of every tool the AI called. Status values:

  • success — the AI emitted STRATA_STATUS: SUCCESS.
  • error — the AI emitted STRATA_STATUS: FAILED - <reason>, or one or more tool calls returned errors and the AI didn't confirm completion.
  • timeout — the run exceeded its max_runtime_sec cap and was aborted.

After 5 consecutive failures (MAX_CONSECUTIVE_FAILURES), the agent auto-disables itself for an hour — the scheduler pushes its next_run_at out by an hour to give you time to fix the issue before retrying.

Server-side enforcement of "allowed"

The agent permission map is enforced at the scheduler, not at the AI's discretion. selectAvailableTools(agent, …) in agentScheduler.js builds the toolset by intersecting:

  1. The wizard's permission switches.
  2. (If dry run) the destructive-tools blocklist.
  3. (If admin set one) the per-user agent extension mask (see /docs/agents/per-user-governance).

A tool that doesn't survive that intersection is simply not registered for the run — even if the AI tries to call it, the call fails immediately because the tool isn't in its toolset. When a per-user mask is active, the system prompt also appends a line:

ADMIN RESTRICTION: Your administrator has limited the tools this agent can use. Only the following tools are actually available at runtime: <list>. Do not try other tools — they are stripped from your toolset and will fail. If the task requires a tool not in this list, fail with STRATA_STATUS: FAILED and explain that the required tool was not available.

This means the AI doesn't just try and fail — it sees the restriction up front and either completes the task within the allowed tools or fails cleanly with a clear reason.

[Admin] Org-level agent limits

Admins can apply broad controls in Admin > Org Settings > Agents:

  • max_agents_per_user — per-user cap on how many agents a single user can deploy. Hitting it returns Agent quota reached: your organization allows up to N agent(s) per user. Delete an existing agent to make room.
  • min_agent_interval_seconds — minimum cadence between runs. Schedules that fire more often return Schedule is too frequent: your organization requires at least Ns between runs...
  • max_agent_runs_per_day — soft daily cap. Once a user's daily count is reached, scheduled and webhook runs are skipped silently (skipped: true, reason: daily_cap_reached); manual Run now still works.
  • Cost ceilings — max_agent_tokens_per_run and max_agent_cost_cents_per_run cap what a single run may consume (the run is stopped mid-execution once a ceiling is reached), and max_agent_cost_cents_per_month caps each agent's total spend per calendar month (once reached, the agent is skipped until the month resets). See Rate limits and quotas for the recommended values.
  • lock_agents — org-wide kill switch. Blocks all new agent creation and content edits across the org. Existing agents continue to run on schedule.

These controls cascade through both POST /api/agents and PATCH /api/agents/:id. Pause / resume and starring an existing agent bypass the lock (see the pause-only exception in /docs/agents/per-user-governance).

[Admin] Per-user lock and tool mask

Independent of org-wide controls, admins can lock a single user out of creating or editing agents, and / or restrict which extension categories that user's agents can touch at runtime. See /docs/agents/per-user-governance for the full mechanics — including the lock-but-allow-pause exception, the intersection of template permissions and user mask, and how existing scheduled runs continue while the next create/edit gets blocked.

[Admin] The model an agent runs on

Each agent is pinned to one AI model in the Engine step of the wizard. The picker offers the models your organization has enabled in the Model Catalog (Org Settings → Models → Open the catalog). The effective set a model run is allowed to use — the same governed set chat uses — is the intersection of three layers:

  1. The models your organization has enabled in the catalog.
  2. The models the owner's role allows.
  3. The owner's per-user model override, if an admin set one.

The wizard's picker filters on the org layer; the role and per-user layers are enforced at run time alongside the org layer (so a model you can pick in the wizard may still be blocked at run time if your role or per-user override excludes it). Before a scheduled, webhook, or manual run starts, the scheduler re-resolves the owner's allowed list and:

  • Validates the agent's pinned model. If an admin later disables that model in the catalog, the run fails cleanly with a message telling the owner to either ask an admin to re-enable it, or edit the agent to use a currently-allowed model. The agent does not silently fall back to another model.
  • Clamps background reviewers (the artifact and document review passes) to the same allowed set, so a scheduled run can never reach a model the owner couldn't use in chat.

To restrict the models a single user — and therefore their agents — can pick, open Admin → Users → (manage user) → Extensions & Data → AI models and uncheck models. Leaving every box checked means the user inherits the full org-allowed set.

Warning

Disabling a model that deployed agents are pinned to will make those agents' next runs fail. Re-point the affected agents to an allowed model before, or right after, you change the catalog.

[Admin] Where to look for agent activity

  • Admin > Users > (click user) > Agents tab — every agent this user has deployed, with status and a delete affordance.
  • Admin > Usage — agent runs and cost roll up here alongside chat usage. Filter to a single user for per-person breakdowns.
  • Admin > Organization settings > Audit — agent-template create/edit/delete events. Run-level events are not audit-logged today (they're in the agent's own run history).

What can go wrong

  • An agent ran but did nothing useful — check Recent runs. Most often the agent had STRATA_STATUS: FAILED because a required extension wasn't connected, or a required tool was masked off. The failure reason is in the run detail.
  • Agent quota reached: your organization allows up to N agent(s) per user. Delete an existing agent to make room. — you've hit your org cap. Delete an unused agent.
  • Schedule is too frequent: ... — your schedule violates the org minimum interval. Pick a less frequent cadence.
  • The AI says "the required tool was not available" — the per-user agent extension mask is blocking a tool the agent's prompt needs. Ask your admin to enable the corresponding extension category on your account, or rewrite the agent to use a different tool.
  • An agent auto-disabled itself after 5 failures — open the agent and review the run history to find the root cause. The next-run timestamp is pushed an hour out; once you fix the issue, Run now clears the failure streak on success.
  • Dry run shows the AI "would have" sent an email but a real run sends a wildly different one — the AI is non-deterministic. Re-run the dry run a few times to see the spread of behaviors, and tighten the prompt with explicit constraints before enabling Sensitive tools.

Related