portfolio-next/docs/PERMISSIONS.md

Agent permissions

Source of truth for what AI coding agents may run here. Tool files are renderings of this page: .claude/settings.json, .codex/config.toml, .codex/rules/project.rules, .gemini/settings.json. Change this page and every tool file in the same commit.

Verified commands

Run on 2026-11-09. Only worked rows may appear in a tier, a tool file, or AGENTS.md Commands.

Command	Result
bun --version	worked (1.3.14)
google-chrome --headless=new --no-sandbox --screenshot=out.png --window-size=1440,900 file://…	worked
bun install --frozen-lockfile	not run: no package.json yet
bun test, bun run build, bunx tsc --noEmit	not run: no tooling yet

TODO(maintainer): confirm every row above that is not worked, and add stack commands to the Allow tier once the Astro project exists.

Tiers

Tier	Commands	Why
Allow	git status, git diff, git log, git show, git branch --list, git rev-parse, git add, git commit	Inspection and committing; no prompt needed.
Ask	git push, git merge, git rebase, git switch, git restore, git commit --amend, rm (any), bun add, bun remove, bun update, bun upgrade, bunx, npx	Leaves the machine, rewrites work, changes dependencies, or downloads and runs code: a human decides.
Deny	git push --force / -f / --force-with-lease, git reset --hard, git clean, git add -f / --force, git commit --no-verify / -n, rm -r / -R / -rf / -fr / -Rf / -fR / --recursive, sudo; reading .env, .env.*, secrets/**	Destroys work, skips checks, or exposes secrets.

Known gaps

• Allowlists save prompts; they are not a security boundary. Use the tool's sandbox for isolation.
• Prefix rules are bypassable: git -C dir push, flags placed later (git push origin main --force), +refspec pushes. Claude Code's :* matches at a word boundary, so each flag cluster must be listed, which is why git clean is denied whole and rm always asks.
• Once they exist, allowed test, lint and build commands run code from the repo. An agent that can edit package.json or the tests can run anything through them.
• Denying reads of .env does not stop a script that opens it itself, and git can print staged or committed secrets (git show HEAD:.env). git add -f is denied so an agent cannot stage an ignored secret; keep real secrets out of the working tree.
• Codex: no allow rules are written (in Codex allow means "run outside the sandbox"). In the workspace-write sandbox .git/ is read-only, so git add/git commit ask for escalation. approval_policy in .codex/config.toml can loosen a stricter user setting. Codex rules cannot deny file reads.
• Gemini: tools.exclude is deprecated but is the only project-level deny; there is no Ask tier (anything not allowed asks). Gemini cannot deny file reads. Ignored until the folder is trusted.