Epic-The-Musical-Timeline/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 2026-10-23 with Bun 1.3.14, each in a fresh shell. Only worked rows may appear in a tier, a tool file, or AGENTS.md Commands.

Command	Result
bun install --frozen-lockfile	worked (no changes)
bun test	worked — 32 pass, 0 fail, 3 files
bun test tests/data.test.ts	worked — 10 pass
bun test -t "registry has 7"	worked — 1 pass
bun run typecheck	worked (tsc --noEmit, exit 0)
bun run build	worked — dist/server.js + hashed page assets
bun run dev (PORT=3113)	worked — / and all mockup routes 200, no-slash form 302
bun run start (PORT=3112)	worked — same route results as dev
bun dist/server.js (from repo root)	failed — TypeError: Bundled file "./index-….js" not found; assets resolve from cwd
docker build -t epic-timeline .	worked
docker run --rm -p 3000:3000 epic-timeline	worked — /mockups/06-constellation/ 200
docker run -e PORT=8080 -p 8099:8080 epic-timeline	worked — / and all 7 mockups 200, credits hook present (host port 8080 was taken on this machine)
google-chrome --headless --window-size=1440,900 --screenshot=… <url>	worked (no chromium binary on this machine)
codex execpolicy check --rules .codex/rules/project.rules -- <cmd>	worked — deny/ask rules match as intended
Lint / format	not run — no linter or formatter configured

TODO(maintainer): confirm whether a linter/formatter should be added.

Tiers

Tier	Commands	Why
Allow	git status, git diff, git log, git show, git branch --list, git rev-parse, git add, git commit; bun install --frozen-lockfile, bun test, bun run typecheck, bun run build, bun run dev, bun run start	Inspection and the verified dev loop; 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; docker (any)	Leaves the machine, rewrites work, changes dependencies, downloads and runs code, or touches containers — 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.

docker build/docker run are verified but stay in Ask because they touch containers.

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.
• Allowed test, typecheck, and build commands run code from the repo; an agent that can edit package.json or the tests can run anything through them (bun run dev/start run the server).
• 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: loaded only once the user trusts the project; approval_policy here can loosen a stricter user setting. No allow rules (allow = run outside the sandbox). In workspace-write, .git/ is read-only, so git add/git commit ask for escalation, and bun install needs network and asks too. Codex rules cannot deny file reads. --force-with-lease=<ref>, +refspec and later-placed flags only hit the Ask rule.
• Gemini CLI: ignored until the folder is trusted. tools.exclude is deprecated but is the only project-level deny. No Ask tier (anything not allowed asks). Cannot deny file reads.
• Cursor and Copilot: not configured — no sign the team uses them.