plumb-git

Plumb's git tool is a policy-gated wrapper, not a shell. The subcommand leads the argv, nothing is interpolated by a shell, and eight global flags that could re-target the repository or inject config are refused wherever they appear in args: -c, -C, --exec-path, --git-dir, --work-tree, --namespace, --upload-pack, --receive-pack. The one exception is switch, where -c / -C mean create-branch rather than anything global: they are rewritten to --create / --force-create before the denylist runs, and the response says so. Prefer this tool over shelling out — the shell path bypasses the policy and plumb's per-repository git lock.

Under a lean tool profile file_status and minimal_diff_review are not advertised; set [tools] profile = "full" in .plumb/config.toml to see them.

The four tiers

rm is refused at every tier: delete the file with delete_file, then stage the deletion with add.

Because the read tier is always on, a read verb's options that would do anything but read this repository are refused. --output (on diff, log, show, shortlog, blame and stash show) writes a file. grep -O runs a pager. --no-index, blame --contents, blame -S / --ignore-revs-file, grep -f, ls-files -X and -O<orderfile> read files outside the repository. So does any argument that names an existing path outside it — including a search pattern such as /usr, which you can anchor (^/usr) to get past the check. Use git grep <pattern> <rev> to search a past revision, ls-files to ask whether a path is tracked, and cherry -v <upstream> to see which commits are already upstream after a squash merge.

Eight subcommands are classified by their arguments, biased towards the safer-to-deny higher tier — so the same subcommand can land in different tiers on different calls. Options are read as git reads them: an abbreviation (--disc), a bundle (-dr) or a value (tag -m -d) counts exactly as git counts it:

• checkout -b (branch creation) is write; every other checkout is destructive, since it can discard the working tree or detach HEAD — including -B on a branch that already exists (on a new, plain-named branch -B given once is a write). Prefer switch for a safe branch change.
• switch is write, but switch -f / --force / --discard-changes and -C / --force-create on a branch that already exists are destructive (on a new, plain-named branch -C given once is a write; a name git expands, such as @{-1}, is not plain).
• restore: with --staged (the index only) it is write; with --worktree, or with no flag at all, it is destructive.
• branch: --list / -l / -a / -r / --show-current / --contains / --merged / --points-at, and a bare branch (-v included), are read — a later --no-list cancels list mode; creating, -m / --move / --copy and the upstream/description options are write; -d / --delete and every forced form (-f / --force, -M, -C — also inside a bundle such as -qC — and -D) are destructive whether or not the branch exists. Unlike checkout -B, switch -C and tag -f, a forced branch is never lowered to a write for a new name; to start a branch, use branch <name>, checkout -b or switch -c.
• tag: -l / --list / -n / --contains / --merged, and a bare tag, are read; creating is write; -d / --delete, and -f / --force on an existing tag, are destructive (on a new, plain-named tag -f given once is a write).
• stash: list / show are read; a bare stash plus push / save / pop / apply / create / store are write; drop / clear are destructive; any other sub-subcommand is refused with the permitted list.
• merge (--no-ff, --ff-only, --no-edit, -m <message>, <ref>) is write, like commit, and runs the merge hooks; --abort / --quit are destructive. --continue, --no-verify, -e / --edit and -F / --file are refused: conclude a merge with commit and a message instead. A merge that stops on conflicts names the conflicted files and leaves git's merging state: resolve, add, then commit.
• worktree: list is read; add, remove, lock and unlock are write; move, prune and repair are destructive, as are add -B (which resets a branch) and add -f (which lets two worktrees hold one branch). add, move and remove are confined to the workspace — an outside path is refused outright, and confirm does not lift it — and remove needs confirm: true only when it would discard something: uncommitted work, or a detached HEAD whose commits no branch, tag or remote reaches.