Positron Assistant configuration for a project

Working specification: what the assistant should be allowed to do, and the file that says so

A committed settings file for Posit Assistant in Positron: the two settings to write, how the auto and normal approval modes differ, and a checklist of what the assistant may do without asking.

Obsolete, 2026-09-12. The approval mode is set from the chat pane, not from a settings file. Click the icon at the lower left of the chat input box and pick Auto mode. Nothing else in this document is needed to get that.

The shipped picker offers Normal, Plan, Auto, Cleaning and Ask, which is not the list of modes described below. What follows is kept for the permission key reference and for the description of what Auto mode allows.

1. Scope

One file, .posit/assistant/settings.json, committed to a project repository, that lets the assistant work in the repository without a confirmation click on every edit, and stops it from doing damage that version control cannot undo.

The user is a statistician or pharmacometrician using Positron with the assistant turned on. Section 3 explains agent permission systems from zero.

2. The Recommendation

Set the approval mode to auto, allow executeCode, and write nothing else.

{
  "approvalMode": "auto",
  "permission": {
    "executeCode": "allow"
  }
}

approvalMode: auto lets the assistant read, edit, run, build and commit inside the project without asking, and gates everything that leaves it. Section 4 compares it against the normal default.

executeCode: allow covers running R or Python in the active console session. That is the tool this group uses most, it is separate from bash, and no bash rule constrains it.

The same JSON works in either of two places. Both paths were confirmed on disk on 2026-09-12.

Path	Applies to	Committed
~/.posit/assistant/settings.json	Every project you open	No, personal to you
.posit/assistant/settings.json in the project root	That project only	Yes, shared with collaborators

Settings resolve last-wins, defaults then home then project, so a project file overrides the home file key by key.

✅ Start with the home file. One edit covers every repository, including the ones not created yet, and it avoids the unverified claim below. Nothing in the recommendation is project-specific, so there is little to gain from writing it once per repository.

Add a project file later, carrying executeCode alone, when you want everyone working in one repository to get the same posture without each of them setting it up. That is the case for a shared analysis repository and not much else.

⚠️ One thing here is unverified. Whether approvalMode is accepted in a project-level file at all, or only in the home file and the administrator environment variables. It is absent from the documented list of per-project settings. If it turns out to be home-only, the home file is the sole place it works, which is a further reason to start there. Set it, then read the mode indicator in the chat pane. The check takes a minute.

3. How the Permission System Works

The assistant does not edit a file or run a command directly. It proposes a tool call, a named request such as “edit model.R” or “run quarto render”. A permission layer answers each proposal with allow, which runs it silently, ask, which shows a dialog, or deny, which refuses and tells the assistant it was refused.

Each tool has a key used in the settings file.

Key	What it governs
executeCode	Running R or Python in the active console session
bash	Shell commands, matched as patterns
edit	Changing or creating a file, matched per file pattern
read	Reading a file
external_directory	Any path outside the working directory
webfetch	Retrieving a URL, including an intranet address
task	Spawning a subagent, by type
skill	Invoking a named skill

The remaining keys are glob, grep, list, websearch, todowrite, question, lsp and doom_loop. None needs a rule in a pharmacometrics project.

Both bash and edit take patterns, so "git *": "allow" and "rm *": "deny" can sit side by side. A tool can also take one answer for everything, written as "read": "allow".

A deny is documented as absolute: no approval, mode or setting gets past it, including in auto and yolo. That makes a written denial the strongest thing available, on the rare occasion one is needed.

The approval mode answers everything the written rules do not mention, which under the recommendation in Section 2 is everything.

4. Auto Against Normal

Four modes exist. restricted is for a repository you did not write and do not trust. yolo removes the classifier that makes auto acceptable in a repository holding analysis code. The real choice is between the two in the middle.

	normal, the default	auto, recommended
Who judges a risky tool call	You, in a dialog box	A classifier model reading the call
What the judgment uses	A fixed split of operations into safe and risky	The command, the path it touches, and the context
Where the boundary sits	Wherever accumulated approvals have put it	The working directory, plus a fixed blocked list
Is the decision written down	Yes, if you choose “for this project”	No
Prompts per hour	Many at first, fewer over time	Few, and the number does not drift

auto allows what stays inside the working directory: reading and editing files, running tests and builds, committing to the current branch, and read-only web requests. It blocks a published list: piping a remote script into an interpreter, sending credentials to an external endpoint, force-pushing, and modifying production infrastructure. normal publishes no equivalent list.

5. The Behavior Checklist

Each row is a behavior and a verdict. ✅ runs with no prompt, ⚠️ prompts, ❌ is refused. Everything marked auto needs no written rule.

Reading and editing

#	Behavior	Verdict	Handled by
1	Read any file in the project	✅	auto
2	Edit an existing file in the project	✅	auto
3	Create a new file in the project	✅	auto
4	Delete a file in the project	✅	auto, recoverable by git
5	Write anywhere outside the project	⚠️	auto boundary
6	Read ~/.ssh, ~/.aws, other credential paths	❌	sandbox, Section 6

Running code

#	Behavior	Verdict	Handled by
7	Run R or Python in the console session	✅	executeCode: allow
8	Run a script, render Quarto, run tests	✅	auto
9	Install a package	✅	auto
10	Change a dependency list or model definition	✅	auto, recoverable by git
11	Submit a job to a cluster or remote host	❌	"ssh *": "deny", "sbatch *": "deny"

Item 11 is the one case where a written rule earns its place on cost rather than on recoverability. A four-hour model fit is expensive to start by accident and the cost lands on a shared queue.

Version control

#	Behavior	Verdict	Handled by
12	git status, git diff, git log	✅	auto
13	git add, git commit on the current branch	✅	auto
14	git push	⚠️	auto
15	git push --force	❌	auto blocked list
16	git reset --hard over local changes	⚠️	auto

The outside world

#	Behavior	Verdict	Handled by
17	Read-only web requests for documentation	✅	auto
18	Send file contents to the model provider	⚠️	assistant.aiExcludes
19	Send session variables to the model provider	❌	nothing in this file
20	Spawn a subagent	⚠️	auto
21	Run an MCP server not listed in the project file	❌	mcpServers, unset

Model Context Protocol, abbreviated MCP, gives an assistant extra tools from an external process. Such a server can do anything its author wrote it to do and sits outside every rule in this file. None is configured here.

6. Optional Additions

None of these is in the recommendation. Each is listed with what it buys.

sandbox.enabled: true runs shell commands inside an operating-system sandbox, Seatbelt on macOS and bubblewrap on Linux. It restricts writes to the workspace and temp directories, blocks network access, and prevents reading paths such as ~/.ssh and ~/.aws. This is the only control in the document enforced by something other than the assistant honoring its own configuration, and it is what makes item 6 of the checklist a ❌ rather than a hope.

⚠️ Turning the sandbox on breaks package installation, because blocking network access stops install.packages() and renv::restore() when the assistant runs them. Turn it on for a project whose dependencies are stable, not for one being set up. Whether it covers executeCode as well as bash is unverified.

7. Where to Start

1. Copy the file in Section 2 into ~/.posit/assistant/settings.json. That covers every project at once and nothing needs committing.
2. Add a rule only when a prompt has annoyed you twice.
3. Copy the executeCode line into a project’s own .posit/assistant/settings.json and commit it, but only for a repository other people work in.