git
Run git subcommands through a policy-gated tool that enforces tiered permissions for read, write, destructive, and network operations, and prevents cross-session conflicts.
Instructions
Run git through one tiered, policy-gated tool (no shell). Read subcommands (status, log, diff, show, blame, shortlog, branch/tag/stash listing) always run. Write subcommands (add, commit, switch, mv, branch/tag create, stash push/pop) need [git] allow_writes (default on). Destructive subcommands (reset, clean, checkout, restore, rebase, revert, cherry-pick, branch/tag delete, stash drop) need allow_destructive AND confirm:true. Network subcommands (push, fetch, pull) need allow_push AND confirm:true; force-pushing a protected branch (via -f/--force or a +refspec) and using an ad-hoc URL/remote (incl. any :: helper) on any network subcommand are always refused — and a force push must name its destination branch (a bare -f or +HEAD that relies on the current branch is refused, since it may target a protected branch). Typed parameters: add uses files (staged with -A semantics — new/modified/deleted); commit uses message (plus an optional files list for a path-limited commit, the safe way to commit just your change in a shared worktree); every other subcommand uses args. Cross-session guard: plumb tracks the HEAD+branch each session last observed per repo; before a write/destructive op, if a DIFFERENT plumb session moved it since this session's last observation, the op is refused unless re-run with confirm:true, and the response names the peer session and the old→new refs (movement by this session, an external tool, or an unknown mover adds no friction). expected_head pins the exact HEAD commit for write/destructive ops — a mismatch refuses the call outright. Attribution: with [git] commit_trailer = true (default off) every plumb-mediated commit is stamped with a Plumb-Session: trailer; regardless of that knob, workspace_sessions lists recent commits per session (short SHA, subject, repository) from its recent-writes feed. Peer intents: with [collab] intents = true, a repo-state op (any destructive-tier op, plus commit/switch/checkout) also surfaces live peer share_intent claims covering this repository as an advisory warning naming the peer and the claim — informational only: it never blocks the op and never requires confirm.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Flags and arguments passed directly to git for all subcommands except add and commit. Examples: ["--oneline", "-10"] for log; ["--cached"] or ["--staged"] for diff (shows staged changes ready to commit); ["--staged"] for restore. Ignored when subcommand is "add" (use files) or "commit" (use message). | |
| repo | No | Path to any file or directory inside the repository. Omit to use the attached workspace; if no workspace is attached the call is refused (git never falls back to the daemon's working directory). To operate on a nested git submodule, set this to a path inside the submodule — git resolves to the submodule's own root, so add/commit land there; a command run against the superproject only records the submodule's commit pointer, never its file contents. | |
| files | No | Paths to act on. For subcommand "add": paths to stage (-A semantics — new, modified, and deleted entries all staged). For subcommand "commit": optional path-limited commit — commits ONLY these tracked paths (git commit -m <message> -- <files>), ignoring any unrelated staged changes already in the index; omit to commit the whole index. No glob expansion. Ignored by other subcommands. | |
| confirm | No | Required (true) for destructive and network subcommands. Also required to override the cross-session ref-movement guard: when a DIFFERENT plumb session moved this repo's HEAD/branch since this session last observed it, a write/destructive op is refused until re-run with confirm:true. | |
| message | No | Commit message — only used for subcommand "commit". Maps to -m; pre-commit hooks always run. Combine with files to commit only specific paths. Not used by any other subcommand. | |
| subcommand | No | Git subcommand to run. Read (always): diff, log, show, blame, status, shortlog, check-ignore, plus branch/tag/stash listing. Write (needs allow_writes, default on): add, commit, switch, mv, branch/tag create, stash push/pop. Destructive (needs allow_destructive + confirm): reset, clean, checkout, restore, rebase, revert, cherry-pick, branch/tag delete, stash drop. Network (needs allow_push + confirm): push, fetch, pull. | |
| expected_head | No | Optimistic-concurrency guard for write/destructive subcommands (mirrors edit_file's expected_mtime): any git revision (full/short SHA, branch, tag) naming the commit HEAD must be at. When supplied and HEAD resolves elsewhere — or resolves to nothing — the operation is refused before running, regardless of which session (or external tool) moved it. Ignored by read and network subcommands. Omit for no check. |