STTracker/docs/PERMISSIONS.md

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.