# 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 |
|---|---|
| `git status --short` | worked — exit 0 |
| `git diff --stat` | worked — exit 0 |
| `git log --oneline -1` | worked — exit 0 |
| `git show --stat --oneline HEAD` | worked — exit 0 |
| `git branch --list` | worked — lists `main` |
| `git rev-parse --short HEAD` | worked — exit 0 |
| `git add <paths>` | worked — evidence: the final-review fixes commit that added these rows |
| `git commit -m <msg>` | worked — evidence: the final-review fixes commit that added these rows |
| `bun install --frozen-lockfile` | worked (no changes) |
| `bun test` | worked — 34 pass, 0 fail, 3 files |
| `bun test tests/data.test.ts` | worked — 10 pass |
| `bun test -t "registry has 15"` | 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.