The Project .pi Directory and Trust

You clone a repository. It contains .pi/extensions/migrate-schema.ts, and migrate-schema.ts calls execSync with a string built from a prompt. Pi asks whether you trust the folder. You are being asked a real question, and the honest answer is that the prompt is ambiguous about what “yes” buys you.

security.md answers it precisely, and the answer has a wrinkle worth knowing before you answer.

What triggers the prompt

Pi requires a project-trust decision when it finds any of these from the current working directory:

• .pi/settings.json
• .pi/mcp.json
• .pi/extensions, .pi/skills, .pi/prompts, or .pi/themes
• .pi/SYSTEM.md or .pi/APPEND_SYSTEM.md
• project .agents/skills in the current directory or an ancestor directory

A bare .pi directory does not require trust. Trust is requested because something would load.

What trust admits

Granting trust allows Pi to load project settings, MCP servers from .pi/mcp.json, the extensions, skills, prompt templates, themes and system-prompt files under .pi, missing packages configured through project settings, and project-local and project-package extensions.

That is a complete list, and it is narrower than it first appears: everything on it is a thing that loads, not a permission that is granted.

What trust does not do

security.md is unusually direct on this point: project trust does not limit what tool calls can access or affect. After Pi starts, enabled tools still use the operating-system permissions of the Pi process. Instructions and other content in the folder can also influence the model.

And the one thing that loads regardless:

Context files such as AGENTS.override.md, AGENTS.md, and CLAUDE.md load regardless of project trust unless you disable context loading. Treat instructions in a folder as untrusted input even when you decline project trust.

This is the distinction that catches people. Trust governs executable resources; context files carry instructions, and they arrive either way. configuration.md confirms it from the other direction: context-file discovery does not require project trust.

Wrong: “declining trust means the folder cannot influence this run.” Correct: declining trust stops the listed project resources from loading. AGENTS.md and CLAUDE.md still reach the model, and so does the text of the files themselves once a tool reads one.

    flowchart TD
  W["Working directory"] --> D["Discover project resources"]
  D --> K{"Which kind?"}
  K -->|"context file"| CF["Loads under the context rules"]
  CF --> CFN["No trust decision asked"]
  K -->|"protected resource"| T{"Trust decision"}
  T -->|"granted"| L["Loaded"]
  T -->|"declined"| X["Skipped"]
  

The one exception

Project trust is not a complete startup boundary. Pi reads the project sessionDir setting while selecting or creating a session, before it resolves trust. Declining trust prevents the remaining project settings and protected resources from loading, but it cannot undo that initial session-directory lookup.

Practically: a project can point your sessions at an arbitrary directory before you answer anything. That is worth knowing when you cd into a directory you do not control.

How the decision is made

A command-line --approve or --no-approve override applies first. Otherwise:

1. User-level and command-line extensions can handle the project_trust event. The first extension that returns yes or no owns the decision.
2. If no extension decides, Pi looks for a saved decision for the current directory or one of its parents. The closest decision applies.
3. If no saved decision applies, Pi follows defaultProjectTrust, whose default is "ask".

Saved decisions use canonical directory paths and live in:

~/.pi/agent/trust.json

/trust saves a decision for future processes. A parent-directory decision propagating to children is convenient and is worth thinking about before you rely on it.

The hole automation cannot see through

Print, JSON, and RPC modes cannot show the built-in trust prompt. With no override, extension, or saved decision:

• defaultProjectTrust: "always" loads protected project resources.
• "ask" or "never" skips them.

So an automated run cannot answer a question it cannot ask. Use --approve or --no-approve when you want an explicit one-time decision in a script:

pi --no-approve --print "Summarize README.md"
pi --approve --print "Run the project's own test suite"

What a safe project actually contains

Nothing in .pi is inherently dangerous. The risk profile is whether the folder contains executable resources and whether you would run them in a folder you trust.

A review-friendly project looks like this:

.pi/
├── settings.json          # tool selection, compaction budget; no extensions
├── APPEND_SYSTEM.md       # conventions worth stating every run
├── prompts/               # reviewed text
└── skills/                # reviewed text and reviewed scripts

The order of review matters. Extensions execute inside the Pi process with your permissions; a skill can instruct the model to run scripts; a prompt template is text that a human chose to run. Reading them in that order tells you where the actual risk sits.

Trust is not your sandbox

security.md gives three ways of running Pi and what each protects:

Whichever you choose, provide only the files and services the task requires. Restrict network access when commands do not need it. Trust is a review gate; isolation is the boundary.

Disable context files when you need a hard edge

If you want to run Pi against an unfamiliar repository and no folder instruction should reach the model, -nc/--no-context-files disables AGENTS.md and CLAUDE.md discovery. That is the only documented way to remove the ungated channel.

All of this is a loading gate. Nothing decided here constrains what a tool does once Pi is running, so the next question is not what the folder was allowed to contribute but what environment the first command actually lands in.