# 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.