# 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 on 2026-10-30 while bootstrapping. Only `worked` rows may appear in a tier, a tool file, or `AGENTS.md` Commands.

| Command | Result |
|---|---|
| `git status` | worked |
| `git --version` | worked (2.47.3) |
| `bun --version` | worked (1.3.14) |
| `bun install --frozen-lockfile` | not run — no `package.json` yet |
| `bun test` | not run — no code yet |
| `bunx tsc --noEmit` | not run — no TypeScript installed yet |

TODO(maintainer): confirm every row above that is not worked once tooling exists, then add them to Allow.

## Tiers

| Tier | Commands | Why |
|---|---|---|
| Allow | `git status`, `git diff`, `git log`, `git show`, `git branch --list`, `git rev-parse`, `git add`, `git commit` | Inspection and the verified dev loop; no prompt needed. |
| Ask | `git push`, `git merge`, `git rebase`, `git switch`, `git restore`, `git commit --amend`, `git clone`, `rm`; `bun add/remove/update/upgrade`; `bunx`, `npx` | Leaves the machine, rewrites work, downloads code, or changes dependencies — 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. |
| Deny (clean room) | cloning `n8n-io`, `kestra-io`, `windmill-labs`, `activepieces` repos; `npm view/pack` and `bun add` of n8n/Activepieces packages; reading those packages under `node_modules`; WebFetch of `raw.githubusercontent.com`, `unpkg.com`, `cdn.jsdelivr.net` (raw source/package hosts) | Enforces AGENTS.md "Clean room" (spec §3.2). |

## 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.
- Clean-room denies are best effort: browsing github.com source pages, other mirrors, or `curl` are
  not blocked (Claude Code WebFetch rules are per domain, and github.com also hosts allowed material).
  The CI similarity scan and dependency denylist are the real guard (TODO).
- The raw-host WebFetch denies also block legitimate permissive sources on those hosts; ask a human
  to approve a one-off fetch when needed.
- 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` 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` here can loosen a stricter user setting; `.git/` is read-only in its
  sandbox, so commits ask for escalation. Codex and Gemini cannot deny file reads.
- Gemini: no Ask tier (anything not allowed asks); `tools.exclude` is deprecated but the only project-level deny.