whisper_web/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. (No Cursor/Copilot files: no sign the team uses them.)

Verified commands

Run on 2026-10-29 (Bun 1.3.14). Only worked rows may appear in a tier, a tool file, or AGENTS.md Commands.

Command	Result
bun install --frozen-lockfile	worked
bun test tests/export.test.ts	worked — 28 pass
bun test tests/models.test.ts -t "dtype"	worked — 5 pass, 14 filtered
bun test --path-ignore-patterns='tests/live-real-model.test.ts'	worked — 239 pass, 1 skip, ~6 s
bun test	worked — 243 pass, 1 skip (opt-in FW_INTEGRATION), ~19 min (after D-039)
bun run build	worked
bun run icons	worked
bun dev	worked — HTTP 200 on /
FW_INTEGRATION=1 bun test tests/transcribe.test.ts	not run — faster-whisper not installed here
bun start	not run — documented in README
bun run typecheck	worked — 0 errors (tsc 7.0.2, 57 files); exits 1 on a planted type error
google-chrome --headless=new --no-sandbox --disable-gpu --screenshot=… <url>	worked (UI screenshots; not in any tier — ad hoc)
Lint	not run — no linter configured
docker build .	not run — CI-only; in Ask tier

TODO(maintainer): confirm every row above that is not worked.

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 icons, bun dev	Inspection and the verified dev loop; no prompt needed.
Ask	git push, git merge, git rebase, git switch, git restore, git commit --amend, rm; bun add/remove/update/upgrade/patch, bunx, bun x; docker; pip install, python3 -m pip install	Leaves the machine, rewrites work, changes dependencies or the transformers patch, or touches deployment — 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.*, data/** (local SQLite users + sessions)	Destroys work, skips checks, or exposes secrets/user data.

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.
• bun install <pkg> adds a dependency but cannot be put in Ask without also catching the allowed bun install --frozen-lockfile (Ask beats Allow in Claude Code). Treat it as Ask by convention.
• bun run build deletes and rewrites dist/ itself (scripts/build.ts), outside the rm rules.
• Allowed test, build, and dev commands run code from the repo; an agent that can edit package.json, scripts/, or the tests can run anything through them. bun test also downloads model weights from huggingface.co (tests/live-real-model.test.ts).
• Denying reads of .env does not stop a script that opens it itself (Bun auto-loads .env), and git can print staged or committed secrets. 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 project is trusted; approval_policy = "on-request" here can loosen a stricter user setting. No allow rules (Codex allow = run outside the sandbox). In workspace-write, .git/ is read-only, so git add/commit ask for escalation; bun install needs network and asks too. --force-with-lease=<ref> and late flags only match the Ask rule. Rules checked with codex execpolicy check.
• Gemini: ignored until the folder is trusted; tools.exclude is the only project-level deny; no Ask tier (anything not allowed already asks); cannot deny file reads.