You're viewing documentation for unreleased changes. View the latest release.

Permissions & Trust

Posit Assistant asks for confirmation before performing potentially risky actions like editing files or running shell commands. You can customize this behavior with approval modes, per-tool permissions, and workspace trust.

With preview agent engines, these controls apply to Posit Assistant’s tools. Claude Agent, Codex Agent, and GitHub Copilot Agent also route their built-in tool actions through Assistant’s permission checks. ACP agents are different: they can run their own tools under the agent’s own settings, without asking Assistant. Assistant’s permissions and shell sandbox do not guarantee control of those actions; ACP agents require a trusted workspace.

Approval Modes

Four modes control how tool confirmations behave:

ModeBehaviorActivate with
NormalSafe operations run automatically; risky actions prompt for confirmation./auto command (toggles Auto off); default in headless runs
AutoDefault. A classifier model reviews risky tool calls and allows or blocks them.Default behavior, or --auto CLI flag in headless runs
YOLOAuto-approve most tool calls, including ones the assistant flags as risky. Deny rules and required confirmations still apply./yolo command
RestrictedAsk before anything that hasn’t been explicitly allowed. Applied automatically to untrusted workspaces. See Restricted Mode./restricted command, or open an untrusted workspace

Toggle between modes with the /auto, /yolo, and /restricted slash commands.

In YOLO mode, administrator-enforced asks and requests to run outside the sandbox still require confirmation. Some filesystem-safety checks also require confirmation.

In a managed deployment, an administrator can cap how permissive a mode may be — see Administrator Policy.

Auto Mode

See Auto Mode for how it reviews actions, how to turn it on or off, cost estimates, and limitations.

Auto mode sits between normal and YOLO — instead of asking you to confirm every risky tool call, it sends eligible calls to a classifier model that decides whether the action is safe. If the classifier approves, the tool runs without interruption. If it blocks, the tool call is declined and the assistant is told why. Tool calls the classifier decided show a shield icon; expand one to see the classifier’s reason.

The classifier generally allows routine actions such as reading and editing project files, running tests and builds, committing to the current branch, and making read-only HTTP requests. It blocks actions like piping uninspected remote scripts to an interpreter or sending credentials to external endpoints, and requires user authorization for force-pushing or modifying production infrastructure. Constraints you state in the conversation (e.g., “don’t push”) are treated as additional block signals.

If the classifier blocks three consecutive tool calls, auto mode pauses and drops back to normal approval mode. Approving the next prompted action resumes it. If the classifier is unavailable or times out, auto mode falls back to the normal confirmation dialog. In headless mode (--auto with a prompt), classifier failures decline the affected call instead of prompting; repeated blocks abort the run.

Restricted Mode

In restricted mode, every tool call asks for permission unless you’ve explicitly allowed it in your settings. This includes built-in defaults that are otherwise automatically allowed, such as reading files, editing the scratch directory, and running “safe” shell commands such as ls, cat, or git status.

An untrusted workspace is always in restricted mode, and the following locations can be used to explicitly allow certain tools:

  • Global settings
  • Host settings such as Positron or RStudio AI excludes
  • Administrator rules

Notably project settings are not loaded in an untrusted workspace, because they are considered part of the untrusted environment, so any allows there will be ignored until the workspace is trusted via /trust.

In a trusted workspace, you can opt in to restricted mode with /restricted.

For ACP agents, restricted mode applies only to Assistant’s tools and permission requests the agent sends to Assistant. It cannot make the agent ask about actions it allows on its own.

Approval Scopes

When the assistant asks for confirmation, you can approve at different scopes:

  • Once — Approve this single action.
  • For this session — Allow this type of action for the rest of the session.
  • For this project — Allow this type of action permanently for this project (saved to .posit/assistant/settings.json).

Not every scope is always offered. For this project needs a trusted workspace, because it writes to the project’s settings file. A prompt that comes from an administrator rule does not offer it either, because a project file cannot override administrator policy.

Tool confirmation dialog with approval scope options

Per-Tool Permissions

Configure permissions in your settings file using the permission key:

{
	"permission": {
		"bash": {
			"git *": "allow",
			"rm *": "deny"
		},
		"read": "allow",
		"edit": "ask"
	}
}

Each tool can be set to "allow", "ask", or "deny". For tools like bash, you can use pattern matching to set different permissions for different commands.

Subagent permissions use the task key and match the requested subtype. For example, to deny exploration subagents while continuing to prompt for general-purpose subagents:

{
	"permission": {
		"task": {
			"explore": "deny",
			"general": "ask"
		}
	}
}

The former permission.explore key is no longer supported. Move its "allow", "ask", or "deny" value to permission.task.explore.

Built-in Defaults

Some security defaults are always enforced:

  • .env files and .Renviron are blocked from reading (prevents accidental secret exposure)
  • Plan files (.posit/assistant/plans/*) are always readable; writing one prompts for confirmation
  • deny rules are always enforced, even in auto and YOLO modes

Administrator Policy

If Posit Assistant was started by Posit Workbench, Posit Connect, or another managed launcher, your administrator may have supplied settings that you cannot change. These arrive in the session’s environment rather than in a file you can edit; the delivery mechanism is documented in Administrator-Managed Settings.

Two things administrators most often set affect what you see day to day.

A cap on the approval mode

An enforced approval mode is a maximum, not a fixed value. The order is restricted → normal → auto → YOLO, and you can always choose something stricter than the cap. Above it:

  • The mode picker shows the capped modes disabled, labelled Managed by your administrator.
  • /auto and /yolo disappear from the command list, and are refused if you type them anyway.
  • A headless run started with --yolo or --auto above the cap exits with an error instead of running with prompts nobody can answer.

Your own saved preference is untouched. If your administrator raises the cap later, the mode you had chosen comes back on its own.

Permission rules you cannot override

Administrator permission rules sit above your global and project settings files:

  • An enforced deny is absolute. No approval, mode, or setting gets past it.
  • An enforced ask always requires a person to answer. YOLO mode won’t auto-approve it, auto mode’s classifier is not consulted for it, a PreToolUse hook cannot allow it on your behalf, and the For this project scope is not offered. Approving Once or For this session works normally. In headless runs these calls are declined, since there is nobody to ask. When shell syntax such as $(...) prevents a command from being split into subcommands, the same requirements apply if an enforced ask or deny for shell commands could match a subcommand that could not be checked.
  • An enforced allow overrides a deny you wrote yourself, and runs without a prompt in restricted mode. It cannot bypass Read-only mode’s read-only guarantee.

Administrators can also set defaults rather than enforced values. Those behave like ordinary settings: they sit below your own configuration, and you can override them.

Other things an administrator can manage this way include MCP servers (an administrator-supplied server starts even in an untrusted workspace) and plugins (managed marketplaces cannot be removed, and a plugin an administrator disabled cannot be re-enabled). Workspace trust itself is never administrator-configurable.

Workspace Trust

When you open a project for the first time, Posit Assistant checks for files that could influence its behavior:

  • AGENTS.md — Memory file
  • AGENTS.local.md — Personal memory file
  • .posit/assistant/settings.json — Project-level settings
  • AGENTS.md and AGENTS.local.md files in parent directories, up to your home directory (or, for projects outside your home directory, up to but not including the filesystem root)

If any of these exist, you’ll be asked to trust the workspace or open in restricted mode (as an untrusted workspace). This prevents untrusted projects from injecting prompts or auto-approving dangerous operations.

Workspace trust prompt with file preview and trust options

Until you trust a workspace, Posit Assistant ignores:

  • The project’s memory files (AGENTS.md), including those in parent directories
  • The project’s skills
  • The project’s settings (.posit/assistant/settings.json)

An untrusted workspace is always in restricted mode. A trusted workspace can opt in to restricted mode, so there are three states:

TrustedTrusted + restrictedUntrusted
Built-in allows (reading files, safe shell commands, and similar)AllowAskAsk
Project memory files, skills, and most settingsLoadedLoadedIgnored
Global, host, and administrator settingsLoadedLoadedLoaded
Approval scopesOnce, session, projectOnce, session, projectOnce, session
/auto and /yoloAvailableAvailableNot available
Leave restricted mode—Toggle /restricted/trust

Trust is persistent! Once trusted, the workspace stays trusted across sessions.

Sandbox Mode

Sandbox mode constrains how the shell tools (Bash and PowerShell) run. How it does so depends on your platform, and the two approaches differ in kind: macOS and Linux confine what a command can do, while Windows limits which commands may run at all.

On macOS and Linux, commands run inside an OS-level sandbox. macOS uses Seatbelt (SBPL) to deny by default: writes are allowed only to the workspace and $TMPDIR, all network access is blocked, and sensitive paths (~/.ssh, ~/.gnupg, ~/.aws, etc.) can’t be read. Linux uses bubblewrap to the same end. Any command may run, but commands are isolated at the OS level.

On Windows, no OS-level sandbox is available, so the safeguard is different: rather than confining a command, sandbox mode restricts which commands are allowed to run. A command executes only if every part of it is on a built-in allowlist of known-safe, read-only commands; anything else is refused with Operation not permitted. There is no filesystem or network isolation — an allowlisted command runs with full access to your machine.

In Sandbox mode, other tools (including web fetch, web search, and R/Python code execution) work as normal.

Toggle sandbox mode with the /sandbox command, or persist it via sandbox.enabled in your config file.

Environment Variables

Sandboxing and environment filtering are separate controls. Turning the sandbox on does not remove inherited credentials such as GITHUB_TOKEN or AWS_SECRET_ACCESS_KEY. Use env.filter in your global settings to withhold those variables, whether the sandbox is on, off, or bypassed for a single command.

The filter applies to shell commands, hooks, local MCP servers, and R and Python processes started by Posit Assistant. It does not change the environment of sessions started by the IDE: RStudio’s R session and Positron’s R and Python consoles.

Use -PATTERN to block matching variable names and +PATTERN to allow them. The last matching rule wins. For example:

  • ["-AWS_*", "+AWS_REGION"] blocks inherited AWS variables except AWS_REGION.
  • ["-*", "+HTTPS_PROXY", "+SSL_CERT_FILE"] allows only the two named variables and Posit Assistant’s built-in list of essential variables, including PATH and HOME.

Your rules cannot override an administrator’s enforced restrictions. See the configuration reference for details about administrator settings and filter rules.

The filter only controls inherited values. A matching - rule does not remove an explicit env.set assignment or a credential supplied by Posit Assistant for a configured connection. Processes can also set variables themselves or read secrets from files such as .env when file access is allowed. Environment filtering does not restrict file access; sandbox restrictions do.

Permission Resolution Order

When multiple sources define permissions, they’re resolved in this order (highest priority first):

  1. Administrator deny rules (absolute — nothing below can approve past them)
  2. Conversation-scoped approvals (from “Allow for conversation”)
  3. Project-scoped approvals (from “Allow for project”)
  4. Administrator ask / allow rules
  5. Project config (.posit/assistant/settings.json)
  6. Global config (~/.posit/assistant/settings.json)
  7. Administrator default rules
  8. Built-in security defaults
  9. Tool’s default permission
  10. Fallback: "ask"

Layers 1, 4, and 7 are empty unless your deployment sets them. Approving in the current conversation sits above administrator ask rules on purpose: an ask is a request for your decision, and giving it is exactly what satisfies the rule.

In older versions, the configuration directories were .positai/ and ~/.positai/ instead of .posit/assistant/ and ~/.posit/assistant/.