Project Access
Work out which folders outside a project its agents need, and ask the dashboard
operator to approve them once, ahead of time, instead of one prompt per denial.
You only ever propose. The operator answers per line in the dashboard.
Nothing in this skill grants access, changes configuration, or answers for the
operator.
Setup — server URL
Discover the server the way the pi-dashboard skill does (config port, default 8000):
PORT=$(grep -m1 '"port"' ~/.pi/dashboard/config.json 2>/dev/null | grep -o '[0-9]*'); PORT=${PORT:-8000}
BASE="http://localhost:$PORT"
curl -s "$BASE/api/health"
(grep -m1 takes the top-level port; the config also nests other port keys.)
If health does not answer, say the dashboard is not running and stop (every mode
needs it, except reading .pi/access.json). When auth is enabled, pass the JWT
cookie as the pi-dashboard skill describes (curl -b "pi_dash_token=…").
Project root = git rev-parse --show-toplevel from the cwd; when that
fails, the cwd if it holds a .pi directory. A root with neither .git nor
.pi is not a project: say so and stop.
Profile — .pi/access.json (format v1)
Optional file in the project root. A proposal only: the dashboard server
never reads it, and the file alone grants nothing. Its contents take effect only
through an approved provision request.
{
"version": 1,
"folders": [{ "path": "../shared-lib", "why": "sibling package used by tests" }],
"remote": ["lan"]
}
folders[].path: absolute, ~/-rooted or relative to the project root.
why is optional, plain text, shown to the operator (cut at 200 characters).
remote (optional): any of lan, internet, device. A goal only points the
operator at the Remote access dialog; nothing is configured for them.
- At most 32 folder lines.
- An unknown
version (or a missing/non-numeric one): refuse. Say the file is
not version 1, show the value found, and do not read or send any of it.
Mode map
Read-only. It never writes a file, a grant or a configuration value. Report, for
the project root and each session cwd inside it (GET $BASE/api/sessions, rows
whose cwd lies in the root; if unreachable, say "session roots: unknown" and
use the project root alone):
- Covering grants —
GET $BASE/api/access/grants → pathGrants. A grant
covers a folder when its subject equals it or is an ancestor. For each, say
how it was created: via: "provision" = approved through a provisioning
request for project origin; via: "prompt" = allow-always on an access
dialog; via: "agent-prompt" = answered on an agent file-access prompt; no
via = created from the Access page. Include scope and grantedAt.
Also list projectTrust / worktreeTrust / kbTrust entries covering it.
- Profile coverage — when
.pi/access.json exists, resolve each folder and
mark it covered / not covered by the grants above. A missing or non-directory
path is reported as missing.
- YOLO —
GET $BASE/api/access/prompts → data.yolo.session: null (off)
or {source, expiresAt, unscoped, roots}. Also data.prompting (is the
operator being asked at all, and blockers).
- pi trust —
GET $BASE/api/access/pi-trust → data.effective entries
covering the root (sourceLabel), else "not trusted by the dashboard mirror".
- Path-gate —
GET $BASE/api/config → agentPathGate.enabled (default on).
PI_DASHBOARD_AGENT_PATH_GATE=off|on in the environment overrides it; report
that value when set.
bash is not gated. Always say so: grants and the path gate cover the
file tools, not shell commands, which run with the operator's own rights.
End with one line naming what could not be read. Every read that fails is
reported as unknown, never guessed.
Mode suggest
Draft .pi/access.json from grants this project's sessions created.
- Read
GET $BASE/api/access/grants → pathGrants. A grant is this project's
when its origin equals the project root, or origin is a session id whose
cwd (from GET $BASE/api/sessions, best effort) lies in the root.
- Count what you could not attribute: grants whose
origin is unknown, and
grants whose origin is a session id you could not resolve. Record whether the
sessions API answered.
- Drop grants whose subject lies inside the project root (they need nothing).
Express the rest relative to the root when under its parent, else absolute.
why = "granted via <via or Access page> on <date>".
- Show the draft. Before you ask to write, state the coverage gaps: "N
grants were skipped (origin unknown)" and, when the sessions API did not
answer, "the sessions API was unreachable, so this list may be partial". Say
this even when N is 0 and the API answered ("nothing skipped").
ask_user (confirm) to write .pi/access.json. Only on yes, write it. An
existing file is shown in full and needs its own overwrite confirmation.
Declined → write nothing.
The draft uses "version": 1. Never include credential folders (~/.ssh,
~/.pi, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker, ~/Library/Keychains):
the dashboard refuses them, so tell the user you left them out.
Mode provision
Submit the profile (or lines the user names) as one request, then follow it to
its end.
Build lines from .pi/access.json (apply the v1 rule above) or from the
folders the user names. Show them and ask_user (confirm) before sending.
Submit with POST $BASE/api/access/provision:
curl -s -X POST "$BASE/api/access/provision" -H 'Content-Type: application/json' \
-d '{"projectRoot":"<root>","lines":[{"path":"../shared-lib","why":"…"}],"remote":["lan"]}'
Success: { success: true, data: { requestId, status: "pending", projectRoot, lines:[{lineId, path, why, classification}], remote, expiresAt } }. Tell the
user the dashboard is asking, and report every line's classification and
real path: grantable lines wait for the operator; in-root / covered
need nothing; invalid, missing, forbidden and sensitive can never be
approved here — say why.
Refused: { success: false, error, reason?, requestId?, retryAfterMs? }.
Explain it and stop; never loop or resubmit on your own.
error |
Tell the user |
empty / too-many-lines / invalid-request |
Fix the profile (1–32 folder lines, or a remote goal). |
invalid-root (reason) |
The project root is not absolute, missing, not a directory, forbidden (e.g. home), or has no .git/.pi. |
no-operator |
Nobody can be asked: open the dashboard in a browser (signed in as operator), then retry with this skill. |
prompting-disabled |
Prompting is turned off in Settings ▸ Access. |
report-mode |
Host admission is in report mode, so the dashboard cannot ask. |
disabled |
The grant prompt is switched off (PI_DASHBOARD_DISABLE_GRANT_PROMPT). |
pending-exists |
A request for this project is already open (requestId): follow that one. |
capacity |
The dashboard has too many open requests; try later. |
rate-limited |
Too many requests; retry after retryAfterMs. |
cooldown |
A recent request for this project ended with nothing approved; retry after retryAfterMs, and only if the user asks. |
Poll until terminal with GET $BASE/api/access/provision/<requestId>, every
~3 s (bounded: one tool call at most ~60 s, then tell the user you are still
waiting and continue):
curl -s "$BASE/api/access/provision/<requestId>"
Keep going until data.status is not pending (settled, dismissed or
expired; a request expires after 10 minutes at data.expiresAt). A 404
means the server restarted and forgot the request: report
"unknown — check Settings ▸ Access" and stop; do not resubmit automatically.
Report each line's outcome and reason to the user:
granted (readable by every session now), rejected, changed (the folder
changed after the operator saw it), refused (e.g. capacity,
root-changed), failed, and handed-off for a remote goal (the operator
was pointed to the Remote access dialog; nothing was configured). dismissed
= everything rejected; expired = nothing granted.
Consent, not containment
Say this when you report a request, in your own words but without softening it:
- Approved folders become readable and writable by every session on this
machine until the operator revokes them on the Access page.
- Approval is consent, not containment: it records what the operator allowed.
It does not stop a program on this machine (an agent's
bash, for one) from
changing access by other means.
- The project name is the requester's claim; the operator sees the real paths.
Notes
- Never call
POST /api/access/provision/<id>/settle or /api/access/provision/dismiss-all. They are operator-only; an agent answering
its own request defeats the point.
- Never write or edit
~/.pi/dashboard/access-grants.json, the dashboard
config, or any pi trust file to obtain access.
- Requests live in the server's memory only; a restart loses pending ones.
- Related:
project-init offers this flow as an opt-in step after scaffolding.
1---2name: project-access3description: 'Map, suggest and request the folder access a project needs: `map` (read-only report), `suggest` (draft `.pi/access.json` from this project''s grants), `provision` (submit it for line-by-line operator approval). Use on "what folders can this project reach", "set up folder access", "write .pi/access.json", repeated folder access prompts, or retrying access setup after project-init.'4license: MIT5metadata:6 source: https://skillmd.com/skills/majiayu000/project-access7 author: pi-dashboard8 version: "1.0"9---1011# Project Access1213Work out which folders outside a project its agents need, and ask the dashboard14operator to approve them once, ahead of time, instead of one prompt per denial.1516You only ever **propose**. The operator answers per line in the dashboard.17Nothing in this skill grants access, changes configuration, or answers for the18operator.1920## Setup — server URL2122Discover the server the way the `pi-dashboard` skill does (config `port`, default 8000):2324```bash25PORT=$(grep -m1 '"port"' ~/.pi/dashboard/config.json 2>/dev/null | grep -o '[0-9]*'); PORT=${PORT:-8000}26BASE="http://localhost:$PORT"27curl -s "$BASE/api/health"28```2930(`grep -m1` takes the top-level `port`; the config also nests other `port` keys.)3132If health does not answer, say the dashboard is not running and stop (every mode33needs it, except reading `.pi/access.json`). When auth is enabled, pass the JWT34cookie as the `pi-dashboard` skill describes (`curl -b "pi_dash_token=…"`).3536**Project root** = `git rev-parse --show-toplevel` from the cwd; when that37fails, the cwd if it holds a `.pi` directory. A root with neither `.git` nor38`.pi` is not a project: say so and stop.3940## Profile — `.pi/access.json` (format v1)4142Optional file in the project root. A **proposal only**: the dashboard server43never reads it, and the file alone grants nothing. Its contents take effect only44through an approved `provision` request.4546```json47{48 "version": 1,49 "folders": [{ "path": "../shared-lib", "why": "sibling package used by tests" }],50 "remote": ["lan"]51}52```5354- `folders[].path`: absolute, `~/`-rooted or relative to the project root.55 `why` is optional, plain text, shown to the operator (cut at 200 characters).56- `remote` (optional): any of `lan`, `internet`, `device`. A goal only points the57 operator at the Remote access dialog; nothing is configured for them.58- At most 32 folder lines.59- An unknown `version` (or a missing/non-numeric one): refuse. Say the file is60 not version 1, show the value found, and do not read or send any of it.6162## Mode `map`6364Read-only. It never writes a file, a grant or a configuration value. Report, for65the project root and each session cwd inside it (`GET $BASE/api/sessions`, rows66whose `cwd` lies in the root; if unreachable, say "session roots: unknown" and67use the project root alone):68691. **Covering grants** — `GET $BASE/api/access/grants` → `pathGrants`. A grant70 covers a folder when its `subject` equals it or is an ancestor. For each, say71 how it was created: `via: "provision"` = approved through a provisioning72 request for project `origin`; `via: "prompt"` = allow-always on an access73 dialog; `via: "agent-prompt"` = answered on an agent file-access prompt; no74 `via` = created from the Access page. Include `scope` and `grantedAt`.75 Also list `projectTrust` / `worktreeTrust` / `kbTrust` entries covering it.762. **Profile coverage** — when `.pi/access.json` exists, resolve each folder and77 mark it covered / not covered by the grants above. A missing or non-directory78 path is reported as missing.793. **YOLO** — `GET $BASE/api/access/prompts` → `data.yolo.session`: `null` (off)80 or `{source, expiresAt, unscoped, roots}`. Also `data.prompting` (is the81 operator being asked at all, and `blockers`).824. **pi trust** — `GET $BASE/api/access/pi-trust` → `data.effective` entries83 covering the root (`sourceLabel`), else "not trusted by the dashboard mirror".845. **Path-gate** — `GET $BASE/api/config` → `agentPathGate.enabled` (default on).85 `PI_DASHBOARD_AGENT_PATH_GATE=off|on` in the environment overrides it; report86 that value when set.876. **`bash` is not gated.** Always say so: grants and the path gate cover the88 file tools, not shell commands, which run with the operator's own rights.8990End with one line naming what could not be read. Every read that fails is91reported as unknown, never guessed.9293## Mode `suggest`9495Draft `.pi/access.json` from grants this project's sessions created.96971. Read `GET $BASE/api/access/grants` → `pathGrants`. A grant is **this project's**98 when its `origin` equals the project root, or `origin` is a session id whose99 `cwd` (from `GET $BASE/api/sessions`, best effort) lies in the root.1002. Count what you could not attribute: grants whose `origin` is `unknown`, and101 grants whose origin is a session id you could not resolve. Record whether the102 sessions API answered.1033. Drop grants whose subject lies inside the project root (they need nothing).104 Express the rest relative to the root when under its parent, else absolute.105 `why` = `"granted via <via or Access page> on <date>"`.1064. Show the draft. **Before you ask to write**, state the coverage gaps: "N107 grants were skipped (origin unknown)" and, when the sessions API did not108 answer, "the sessions API was unreachable, so this list may be partial". Say109 this even when N is 0 and the API answered ("nothing skipped").1105. `ask_user` (confirm) to write `.pi/access.json`. Only on yes, write it. An111 existing file is shown in full and needs its own overwrite confirmation.112 Declined → write nothing.113114The draft uses `"version": 1`. Never include credential folders (`~/.ssh`,115`~/.pi`, `~/.aws`, `~/.gnupg`, `~/.kube`, `~/.docker`, `~/Library/Keychains`):116the dashboard refuses them, so tell the user you left them out.117118## Mode `provision`119120Submit the profile (or lines the user names) as one request, then follow it to121its end.1221231. Build `lines` from `.pi/access.json` (apply the v1 rule above) or from the124 folders the user names. Show them and `ask_user` (confirm) before sending.1252. Submit with `POST $BASE/api/access/provision`:126127 ```bash128 curl -s -X POST "$BASE/api/access/provision" -H 'Content-Type: application/json' \129 -d '{"projectRoot":"<root>","lines":[{"path":"../shared-lib","why":"…"}],"remote":["lan"]}'130 ```131132 Success: `{ success: true, data: { requestId, status: "pending", projectRoot,133 lines:[{lineId, path, why, classification}], remote, expiresAt } }`. Tell the134 user the dashboard is asking, and report every line's `classification` and135 real `path`: `grantable` lines wait for the operator; `in-root` / `covered`136 need nothing; `invalid`, `missing`, `forbidden` and `sensitive` can never be137 approved here — say why.1383. Refused: `{ success: false, error, reason?, requestId?, retryAfterMs? }`.139 Explain it and stop; never loop or resubmit on your own.140141 | `error` | Tell the user |142 |---|---|143 | `empty` / `too-many-lines` / `invalid-request` | Fix the profile (1–32 folder lines, or a remote goal). |144 | `invalid-root` (`reason`) | The project root is not absolute, missing, not a directory, forbidden (e.g. home), or has no `.git`/`.pi`. |145 | `no-operator` | Nobody can be asked: open the dashboard in a browser (signed in as operator), then retry with this skill. |146 | `prompting-disabled` | Prompting is turned off in Settings ▸ Access. |147 | `report-mode` | Host admission is in report mode, so the dashboard cannot ask. |148 | `disabled` | The grant prompt is switched off (`PI_DASHBOARD_DISABLE_GRANT_PROMPT`). |149 | `pending-exists` | A request for this project is already open (`requestId`): follow that one. |150 | `capacity` | The dashboard has too many open requests; try later. |151 | `rate-limited` | Too many requests; retry after `retryAfterMs`. |152 | `cooldown` | A recent request for this project ended with nothing approved; retry after `retryAfterMs`, and only if the user asks. |1531544. Poll until terminal with `GET $BASE/api/access/provision/<requestId>`, every155 ~3 s (bounded: one tool call at most ~60 s, then tell the user you are still156 waiting and continue):157158 ```bash159 curl -s "$BASE/api/access/provision/<requestId>"160 ```161162 Keep going until `data.status` is not `pending` (`settled`, `dismissed` or163 `expired`; a request expires after 10 minutes at `data.expiresAt`). A **404**164 means the server restarted and forgot the request: report165 "unknown — check Settings ▸ Access" and stop; do not resubmit automatically.1665. Report **each line's** `outcome` and `reason` to the user:167 `granted` (readable by every session now), `rejected`, `changed` (the folder168 changed after the operator saw it), `refused` (e.g. `capacity`,169 `root-changed`), `failed`, and `handed-off` for a remote goal (the operator170 was pointed to the Remote access dialog; nothing was configured). `dismissed`171 = everything rejected; `expired` = nothing granted.172173## Consent, not containment174175Say this when you report a request, in your own words but without softening it:176177- Approved folders become readable and writable by **every session on this178 machine** until the operator revokes them on the Access page.179- Approval is **consent, not containment**: it records what the operator allowed.180 It does not stop a program on this machine (an agent's `bash`, for one) from181 changing access by other means.182- The project name is the requester's claim; the operator sees the real paths.183184## Notes185186- **Never call** `POST /api/access/provision/<id>/settle` or `/api/access/provision/dismiss-all`. They are operator-only; an agent answering187 its own request defeats the point.188- **Never write or edit** `~/.pi/dashboard/access-grants.json`, the dashboard189 config, or any pi trust file to obtain access.190- Requests live in the server's memory only; a restart loses pending ones.191- Related: `project-init` offers this flow as an opt-in step after scaffolding.