Lucas WintherandClaude Opus 5.5
0ece4b3a2a
Root AGENTS.md is now the single source of truth for coding agents; CLAUDE.md, GEMINI.md and docs/CLAUDE.md are pointers. The product spec moves from docs/CLAUDE.md to PRODUCT.md, DESIGN.md records the shipped visual system, and docs/PERMISSIONS.md defines agent permission tiers rendered to .claude/, .codex/ and .gemini/. Adds docs/specs/ and docs/plans/, logs issues noticed (not fixed) in WorkBreakdown.md. Co-Authored-By: Claude Opus 5.5 <[email protected]>
57 lines
4.2 KiB
Markdown
57 lines
4.2 KiB
Markdown
# 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. (No Cursor/Copilot files: no sign the team uses them.)
|
||
|
||
## Verified commands
|
||
|
||
Run on 2026-10-29 (Bun 1.3.14). Only `worked` rows may appear in a tier, a tool file, or `AGENTS.md` Commands.
|
||
|
||
| Command | Result |
|
||
|---|---|
|
||
| `bun install --frozen-lockfile` | worked |
|
||
| `bun test tests/export.test.ts` | worked — 28 pass |
|
||
| `bun test tests/models.test.ts -t "dtype"` | worked — 5 pass, 14 filtered |
|
||
| `bun test --path-ignore-patterns='tests/live-real-model.test.ts'` | worked — 239 pass, 1 skip, ~6 s |
|
||
| `bun test` | ran — 242 pass, 1 skip, 1 fail in ~17 min. The fail is pre-existing: `tests/live-real-model.test.ts` › `en_alien` hits its 900 s timeout (reproduced in isolation). Allowed anyway: the command itself is the verified dev loop. |
|
||
| `bun run build` | worked |
|
||
| `bun run icons` | worked |
|
||
| `bun dev` | worked — HTTP 200 on `/` |
|
||
| `FW_INTEGRATION=1 bun test tests/transcribe.test.ts` | not run — faster-whisper not installed here |
|
||
| `bun start` | not run — documented in README |
|
||
| Typecheck / lint | not run — `typescript` not installed, no linter configured |
|
||
| `docker build .` | not run — CI-only; in Ask tier |
|
||
|
||
TODO(maintainer): confirm every row above that is not worked.
|
||
|
||
## 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 build`, `bun run icons`, `bun dev` | Inspection and the verified dev loop; no prompt needed. |
|
||
| Ask | `git push`, `git merge`, `git rebase`, `git switch`, `git restore`, `git commit --amend`, `rm`; `bun add`/`remove`/`update`/`upgrade`/`patch`, `bunx`, `bun x`; `docker`; `pip install`, `python3 -m pip install` | Leaves the machine, rewrites work, changes dependencies or the transformers patch, or touches deployment — 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.*`, `data/**` (local SQLite users + sessions) | Destroys work, skips checks, or exposes secrets/user data. |
|
||
|
||
## 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.
|
||
- `bun install <pkg>` adds a dependency but cannot be put in Ask without also catching the allowed
|
||
`bun install --frozen-lockfile` (Ask beats Allow in Claude Code). Treat it as Ask by convention.
|
||
- `bun run build` deletes and rewrites `dist/` itself (`scripts/build.ts`), outside the `rm` rules.
|
||
- Allowed test, build, and dev commands run code from the repo; an agent that can edit
|
||
`package.json`, `scripts/`, or the tests can run anything through them. `bun test` also downloads
|
||
model weights from huggingface.co (`tests/live-real-model.test.ts`).
|
||
- Denying reads of `.env` does not stop a script that opens it itself (Bun auto-loads `.env`), and
|
||
git can print staged or committed secrets. `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 project is trusted; `approval_policy = "on-request"` here can loosen a
|
||
stricter user setting. No allow rules (Codex `allow` = run outside the sandbox). In
|
||
`workspace-write`, `.git/` is read-only, so `git add`/`commit` ask for escalation; `bun install`
|
||
needs network and asks too. `--force-with-lease=<ref>` and late flags only match the Ask rule.
|
||
Rules checked with `codex execpolicy check`.
|
||
- Gemini: ignored until the folder is trusted; `tools.exclude` is the only project-level deny; no
|
||
Ask tier (anything not allowed already asks); cannot deny file reads.
|