opencode-git-permissions
v0.1.1
Published
OpenCode plugin that auto-approves read-only git commands by injecting permission rules into every agent.
Maintainers
Readme
opencode-git-permissions
OpenCode plugin that auto-approves read-only git commands by injecting
permission rules into every agent defined in your opencode.json.
Why
OpenCode's permission matcher is prefix-based: it compares the full command
line against each rule using a single Wildcard.match. There is no way to
distinguish git branch -vv (read-only listing) from git branch -d foo
(mutation) with a single pattern — both share the prefix git branch, but
the wildcards match too aggressively to enforce that -l requires
-l semantics.
In practice this means the only safe default is "bash": "ask", which
prompts the user for every git invocation. That is correct for safety
but tedious for high-volume workflows where most git usage is read-only.
This plugin reads your loaded config, classifies every git invocation
against a hand-curated read-only allowlist, and merges the allow patterns
into each agent's permission.bash. Commands not in the allowlist keep
their default "ask" behavior.
Install
Add the plugin to your OpenCode config (~/.config/opencode/opencode.json
or project-level .opencode/opencode.json):
{
"plugin": ["opencode-git-permissions@latest"]
}OpenCode resolves and installs the plugin on the next session start.
How it works
On plugin load, OpenCode calls the config hook with the parsed config.
This plugin walks every entry in cfg.agent and, for each agent:
| Existing permission.bash | Plugin action |
| -------------------------- | ------------------------------------------ |
| unset / undefined | injects read-only patterns |
| "ask" (default) | converts to object form with patterns added |
| "allow" | leaves as-is (already approved) |
| "deny" | leaves as-is (explicit deny preserved) |
| { ... } (object form) | spreads ours first, then user's rules |
User rules placed after the plugin's rules win on conflict because
OpenCode's matcher uses findLast. An explicit git status: "deny" in
your config overrides the plugin's allow.
Read-only patterns injected
For every subcommand whose every invocation is read-only — status, log,
diff, show, blame, reflog, rev-parse, ls-files, ls-tree,
cat-file, show-ref, for-each-ref, ls-remote, fsck,
count-objects, describe, diff-tree, diff-index, diff-files,
format-patch, get-tar-commit-id, hash-object, name-rev,
patch-id, shortlog, show-branch, show-index, verify-pack,
whatchanged, help, version — both the bare form (git status) and
the suffixed form (git status *) are allowed.
For push, pull, fetch, clean the only read-only mode is
--dry-run / -n. Both forms (git push --dry-run and
git push --dry-run *) are allowed.
Top-level git --version, git --help, and git -v are allowed in all
forms.
Commands that fall through to "ask"
The following git subcommands always prompt the user, even though they have read-only modes in some flags. The plugin errs on the side of explicit consent because the bash permission matcher cannot express the required flag-level conditions precisely:
branch(read-only listings with-l/-a/-r/etc., mutating deletes with-d/-D)tag(read-only listings with-l, mutating operations with-d/-a)remote(read-onlyshow/get-url, mutatingadd/remove/rename)config(read-only--get/--list, mutating--set/--unset)worktree(onlylistis read-only; everything else is mutating)stash(onlylist/showare read-only;push/pop/dropmutate)
If you want to extend your agent's policy with finer-grained rules for
these subcommands, add them to permission.bash directly in your
opencode.json — they will be merged on top of the plugin's defaults.
Safety model
The plugin never denies anything. Unknown git subcommands, mutating commands, and any command that requires flag-by-flag analysis fall through to the user's default "ask" policy. The user is always in control.
The classifier is the single source of truth. The list of injected patterns is derived from the classifier's data structures, and the test suite verifies every generated pattern is classified as read-only. If you change the classifier and forget to update the patterns, the test suite catches the drift.
Future runtime hook
OpenCode 1.18.x defines a permission.ask plugin hook but does not yet
invoke it anywhere in the runtime. When that hook gets wired up in a
future OpenCode release, this plugin's classifyGitInvocation function
becomes the runtime source of truth — git branch -l foo would be
allowed, git branch -d foo would prompt. The static patterns list
covers the bulk today; the classifier picks up the rest when upstream
support lands.
Development
Requires Bun.
bun install # install dependencies
bun test # run classifier + plugin tests
bun run typecheck # TypeScript type check
bun run build # produce dist/The test suite in test/classifier.test.ts verifies that every pattern
the plugin injects classifies as read-only. The test suite in
test/plugin.test.ts verifies the config hook's merge semantics for
each of the five permission.bash shapes (undefined, "ask", "allow",
"deny", object).
License
MIT — see LICENSE.
