# Agent permissions

Source of truth for what AI coding agents may run here. The 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 on 2026-10-30. Only `worked` rows may appear in a tier, a tool file, or `AGENTS.md` Commands.

| Command | Result |
|---|---|
| `bun install --frozen-lockfile` | worked |
| `bun test` | worked (runner starts; reports "0 test files" until tests exist) |
| `bun run typecheck` | failed: TS18003, no source files yet |
| `bunx tsc --noEmit -p tsconfig.json` | failed: same as above |

TODO(maintainer): confirm every row above that is not `worked` once Phase 1 code lands.

## Tiers

| Tier | Commands | Why |
|---|---|---|
| Allow | `git status/diff/log/show/branch --list/rev-parse/add/commit`, `bun install --frozen-lockfile`, `bun test` | Inspection and the verified dev loop; no prompt needed. |
| Ask | `git push/merge/rebase/switch/restore`, `git commit --amend`, `rm`, `bun add/remove/update/upgrade`, `bunx`, `npx`, `docker` | Leaves the machine, rewrites work, changes dependencies, or downloads and runs code. A human decides. |
| Deny | force pushes, `git reset --hard`, `git clean`, `git add -f`, `git commit --no-verify/-n`, recursive `rm`, `sudo`; reading `.env`, `.env.*`, `secrets/**` | Destroys work, skips checks, or exposes secrets. |

## 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`),
  and `+refspec` pushes. Claude Code's `:*` matches at a word boundary, so each flag cluster must be
  listed. That is why `git clean` is denied whole and `rm` always asks.
- Allowed test 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` does not stop a script that opens it itself, and git can print staged or
  committed secrets. `git add -f` is denied so an agent cannot stage an ignored secret.
- Codex: `approval_policy` in `.codex/config.toml` can loosen a stricter user setting. Codex has no `allow` rules here,
  because in Codex `allow` means "run outside the sandbox". Codex cannot deny file reads.
- Gemini: `tools.exclude` is deprecated but is the only project-level deny. Gemini has no Ask tier and cannot deny file reads.