STaurtomation/docs/PERMISSIONS.md

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.