# 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 in this session. Only `worked` rows may appear in a tier, a tool file, or `AGENTS.md` Commands.

| Command | Result |
|---|---|
| `git status`, `git log`, `git diff`, `git mv` | worked |
| `bun --version` | worked (1.3.14) |
| `bun install --frozen-lockfile` | worked |
| `bun test` | worked |
| `bun run typecheck` (`tsc --noEmit`) | worked |
| `bun run build` (`build:web`, `build:userscript`) | worked |
| `bun run start` | worked (local smoke run) |

## 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` | Inspection and the 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` (download and run code, incl. `wrangler deploy`) | Leaves the machine, rewrites work, changes dependencies, or deploys — 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.*`, `.dev.vars`, `secrets/**` | Destroys work, skips checks, or exposes secrets. |

## Known gaps
- `bun run start` stays out of Allow: it opens a port and fetches from the internet, so it prompts.
- Codex: the allowed bun commands need no rule — they run inside the `workspace-write` sandbox.
- 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, 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` / `.dev.vars` does not stop a script that opens them 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 project is trusted; `approval_policy` here can loosen a stricter user
  setting. No `allow` rules (in Codex that means "outside the sandbox"); `git add`/`git commit`
  ask for escalation because `.git/` is read-only in `workspace-write`. Codex cannot deny file reads.
  `--force-with-lease=<ref>`, `+refspec`, and later-placed flags only match the Ask rule.
- Gemini: ignored until the folder is trusted; `tools.exclude` is deprecated but is the only
  project-level deny. No Ask tier (anything not allowed asks). Gemini cannot deny file reads.